DEV Community: Avery Lin

Gate Changelog Narratives Against a Human-Owned Release Ledger

Avery Lin — Sat, 10 Oct 2026 23:27:19 +0000

A generated changelog stays trustworthy only when every version, date, breaking flag, and issue identifier already lives in a human-owned ledger. The drafting model may explain those pinned rows, but it may not add, rename, or soften them. A validator should fail the documentation build whenever drafted prose cites an unknown identifier or states a date the ledger does not list. That split keeps narrative assistance useful without letting a draft become the system of record for release facts.

Changelog pages fail in a narrower way than general reference pages, because readers treat each version line as an upgrade fact. Support staff, release managers, and downstream maintainers often copy those lines into tickets, pins, and migration plans. An invented patch number or a shifted date can therefore move work onto the wrong build. The remedy is not a longer prompt, but a ledger that the prose is forbidden to outgrow.

The ownership split

Fields a human must pin

A human editor should pin the version, the date, the breaking flag, the public status, and each issue identifier. The same editor should pin a successor when one release replaces another, because that pointer is a commitment rather than a style choice. The ledger should sit in review beside the product repository, and a named owner should approve every row. Until that approval exists, a fluent paragraph can look finished while the release facts remain unsettled.

Fields a model may narrate

The model may draft impact paragraphs, upgrade context, and short headings that repeat a ledger version exactly. Every drafted sentence that names a release should cite a version or an issue identifier from the published allowlist. The model may reorder explanatory clauses for readability, provided the cited facts stay unchanged and the status stays published. It should not add customer names, quotas, or legal promises, because those claims sit outside this ledger and need separate owners.

How to classify a changelog claim

The table below is a decision aid for reviewers, not a measurement from a production corpus. A claim passes the review only when its class is human-pinned or explicitly allowed as narrative. Mixed sentences should be split so the factual half can be scanned and the explanatory half can be edited. If a sentence cannot be classified, keep it out of the public page until the owner adds a row or deletes the claim.

Claim class	Required owner	Model permission	Gate result
Version identifier	Human ledger	Cite the exact string	Fail if absent
Calendar date	Human ledger	Cite the exact date	Fail if absent
Breaking flag	Human ledger	Repeat a fixed label only	Fail if that label is missing
Issue identifier	Human ledger	Cite the exact string	Fail if absent
Successor version	Human ledger	Cite only a pinned pointer	Fail if absent
Impact narrative	Model draft	Explain rows already pinned	Pass when citations match
Heading text	Model draft	Anchor on a pinned version	Pass when the version matches

Six steps that keep the draft inside the ledger

1. Freeze a ledger fixture before prose exists

Create a ledger file and treat published rows as the only changelog facts the narrative may cite. The YAML below is a proposed fixture for reviewers, not a record of a shipped release and not a benchmark. Each row includes a status field so planning notes cannot be narrated as if they were public history. A reviewer should reject any row whose date or issue list is still described as a guess.

# Proposed fixture. Not a record of a shipped release.
schema: release-ledger/1
owner: release-editor
entries:
  - version: "1.4.0"
    date: "2026-09-02"
    breaking: true
    status: published
    issues: ["GH-1042", "GH-1066"]
    successor: null
  - version: "1.4.1"
    date: "2026-09-18"
    breaking: false
    status: published
    issues: ["GH-1104"]
    successor: null

After the fixture is approved, store it at a stable path such as releases/ledger.yaml and review later edits like code. A changed date is a product fact change, so it should not hide inside a documentation wording commit. The owner field is an accountability label for humans, and the model should copy it into no public sentence. This first step is complete only when a second reviewer can point to the file that wins every conflict.

2. Bind the draft to a ledger digest

Compute a digest of the ledger bytes and require the drafted page to name that digest in a comment. The binding prevents an older narrative from shipping after someone corrects a date or removes an issue. The command below is a local pattern for a repository that already has Python 3, and it states no hosted size. If the digest comment is missing, the build should fail closed rather than assume the latest ledger was used.

python -c "import hashlib,pathlib; p=pathlib.Path('releases/ledger.yaml'); print(hashlib.sha256(p.read_bytes()).hexdigest())"

The draft should begin with two comments that record the ledger path and the current digest. A mismatch means the prose was not regenerated against the current pin, even when the sentences still read well. Writers should update the comment only by rerunning the digest command, not by typing a hash from memory. That mechanical rule is what removes an entire class of unreviewed edits from the public release page.

<!-- ledger: releases/ledger.yaml -->
<!-- ledger-sha256: REPLACE_WITH_DIGEST -->

3. Build an allowlist from published rows

The scanner should load the YAML ledger and keep only those rows whose status equals published. Draft rows may remain in the file for planning, but their versions and issues must stay off the public page. The function below is unexecuted example code, and a maintainer should review it before wiring it to a required check. Separate sets for versions, dates, and issues let a failure name the claim class instead of a vague mismatch.

# Unexecuted example. Requires PyYAML. Review before use in a build.
from pathlib import Path
import re
import yaml

DATE_RE = re.compile(r"\b\d{4}-\d{2}-\d{2}\b")
ISSUE_RE = re.compile(r"\b[A-Z]{2,}-\d+\b")
VERSION_RE = re.compile(r"\b\d+\.\d+\.\d+\b")

def allowlist(path: Path) -> dict:
    data = yaml.safe_load(path.read_text(encoding="utf-8"))
    rows = [row for row in data["entries"] if row["status"] == "published"]
    return {
        "versions": {row["version"] for row in rows},
        "dates": {row["date"] for row in rows},
        "issues": {issue for row in rows for issue in row["issues"]},
        "breaking": {row["version"]: row["breaking"] for row in rows},
    }

4. Reject unknown versions, dates, and issue identifiers

A second function should scan the Markdown after the binding comments and compare every match with the allowlist. The check is a consistency gate, so it cannot prove that a human typed the true calendar date. It can prove that the page does not cite a version, date, or issue that the published rows omit. Unknown matches should become build errors that include the offending string, so reviewers need not hunt through the page.

# Unexecuted example. Consistency only; not a truth check.
def scan(markdown: str, allowed: dict) -> list[str]:
    errors = []
    rules = (
        ("version", VERSION_RE, "versions"),
        ("date", DATE_RE, "dates"),
        ("issue", ISSUE_RE, "issues"),
    )
    for kind, pattern, key in rules:
        for hit in sorted(set(pattern.findall(markdown))):
            if hit not in allowed[key]:
                errors.append(f"unowned {kind}: {hit}")
    return errors

The sample scanner above does not read free-form claims about breakage, because those sentences are too easy to soften. A second helper should require a fixed label such as 1.4.0 breaking: yes for each published version. The helper below is also unexecuted example code, and it checks presence of the label rather than the quality of nearby prose. If the label is absent, the build fails even when the surrounding paragraph never uses the word breaking.

# Unexecuted example. Requires the exact label, not a paraphrase.
def missing_breaking_labels(markdown: str, allowed: dict) -> list[str]:
    errors = []
    for version, is_breaking in allowed["breaking"].items():
        word = "yes" if is_breaking else "no"
        label = f"{version} breaking: {word}"
        if label not in markdown:
            errors.append(f"missing fixed label: {label}")
    return errors

Consider a constructed mismatch, not an observed production incident, when judging whether the gate is specific enough. The ledger lists version 1.4.1 on 2026-09-18 with issue GH-1104, and those three strings are the only allowed citations for that row. The draft instead announces version 1.4.2 on 2026-09-20 and cites GH-1200, which the published rows never contained. The scanner should report those three unowned hits and should refuse to repair any of the sentences.

5. Request narrative that cites the allowlist and nothing else

Send the model only the published rows, the heading pattern, and a ban on new identifiers, dates, and breaking claims. The prompt below is a template for reviewers to adapt, not a transcript of a finished run and not a quality score. Store the template beside the ledger so the constraint is visible in the same change as the facts. If the returned draft contains an identifier outside the rows, discard it and rerun the scan instead of patching facts in the prose.

You are drafting changelog narrative for published ledger rows only.
Cite version strings, dates, and issue identifiers exactly as listed.
Include the fixed breaking label for every published version.
Do not add versions, dates, issues, customer names, or breaking claims.
If a row is not in the ledger, omit it rather than inferring it.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode's free model access fits this narration step, because the ledger already holds the facts and the scanner decides what may ship. The free server option fits when the checker should run away from one laptop, after the team confirms the current offering can execute it. Those availability notes are operator-supplied, not quotas, model names, hardware sizes, or duration promises, and they should be rechecked. If hosted access is absent, the ledger, the prompt template, and the local scanner still form a complete workflow.

Reviewers should prefer the owned ledger file over any generated sentence whenever the two sources disagree. That preference is the operational point of the gate, and it does not depend on which editor produced the draft. A passing narrative style review is not a substitute for a matching digest and a clean citation scan. Keep both checks, because a readable paragraph can still smuggle a version the ledger never approved.

6. Make the intended exit contract explicit

The checker command should stay boring, visible, and identical in local review and in any later hosted run. The line below is the proposed interface for the unexecuted script, and a team should implement it before trusting the exits. Exit codes belong in the interface notes so a documentation failure is not mistaken for a style complaint. No timing or cost figure is attached, because this article does not report an executed benchmark.

python scripts/check_changelog.py releases/ledger.yaml docs/changelog.md

The intended contract, which remains a proposal until the script is implemented and run, uses three exits. Exit 0 means the digest matches and every detected citation is already in the published allowlist. Exit 1 means the digest matches, but an unknown version, date, or issue identifier appeared in the draft. Exit 2 means the digest comment is missing or does not match the ledger bytes, so the narrative is unbound.

Limitations that the gate does not remove

Regular expressions miss implied dates such as mid-September and miss versions that are spelled as words rather than digits. A human can still approve a wrong date, after which the scanner will enforce that wrong date with perfect consistency. A new issue prefix will fail until the pattern is updated, which protects the allowlist but can block a legitimate key. Pages that announce security fixes should not share this ledger, because embargo timing and vulnerability identifiers need a separate owner.

This approach also does not judge whether the impact paragraph is clear, complete, or fair to affected users. A citation can be valid while the surrounding explanation hides a breaking change behind soft language. The breaking flag should be rendered with fixed wording, such as a required label, rather than left entirely to paraphrase. Teams that need legal review of release notes should add that review after the gate, and should not treat a passing scan as approval.

Who should not use this workflow

Skip this workflow when no person will approve ledger rows before a model is asked to write. Skip it when annotated history is already the system of record and the public page is a direct render of that history. Skip it when the goal is to discover unreleased work, because discovery is research and this gate only checks citations. A repository that ships several products should keep one ledger per product, or unrelated version lines will share one allowlist.

What to do with one file first

The useful conclusion is narrow enough to test against one unpublished changelog page in the current repository. Pin the published facts, bind the draft to the ledger digest, and reject unknown citations before the page becomes public. Narrative editing remains a human task, but that edit should not be the only control on dates and identifiers. A team that already reviews release facts can apply the checker to one current file, then decide whether older notes deserve the same pin.

Keep Unsourced Limits Out of Model-Drafted Product Pages

Avery Lin — Sat, 10 Oct 2026 19:23:38 +0000

Model-drafted product pages should ship only when every availability sentence is copied from a human-owned pin. A true option becomes a false support fact as soon as the draft adds a quota, a duration, a region, or a hardware shape. The workflow below separates draftable procedure from owned availability, then fails the docs check when that split is violated. Readers can reproduce the check with the file layout and the Python example that follows.

The failure mode is invented precision

Routine documentation review will catch a broken command, yet still miss a confident extra that no operator ever sourced. A page can correctly say that a free model access option exists, and that a free server option exists, without knowing any numeric allowance. When a generator treats that silence as a blank to fill, it may emit token counts, retention windows, instance classes, or model identifiers. Those additions are not style issues, because a later reader can treat each one as an operational commitment.

Weekly headlines do not repair that gap, even when a team wants the page to feel current. A title seen on a community feed is an untrusted topic signal, not a primary source for access limits or server terms. This walkthrough therefore ignores unsourced news claims and uses only the two availability options supplied for the drafting step. If a newer limit appears in a vendor document, a human adds it to the pin before any model is allowed to repeat it.

Split ownership before the first draft

The model may draft sequencing, transitions, and cautions, provided none of those sentences assert a product limit. The human must own the pin, the source note, the review date, and every phrase that mentions access or compute availability. The model must not add pin keys, rewrite allowed phrases, or infer a limit from a neighboring sentence. This split is what keeps generated prose away from facts a maintainer has not explicitly signed.

Surface	Model may draft	Human must own
Procedure between markers	Steps, transitions, and cautions	Whether those steps match the repository
Availability pin entries	Nothing	Statement, source, review date, and allowed phrases
Quotas, durations, and regions	Nothing	Omission, unless a primary source is attached
Model names and hardware nouns	Nothing	Omission, unless the pin lists the exact token
Checker fixtures	Nothing	Expected pass file and expected failure files

The table is the review contract, and a draft that adds a column of estimated limits has already crossed the boundary. Procedure quality can be discussed only after the checker passes, and not while an ownership defect is still open. A cautious adjective does not convert an unsourced limit into an owned claim that reviewers can trust. Ownership means presence in the pin, rather than confidence in the wording of the drafted sentence.

The pin is the only availability source

Store the pin at a fixed ownership path, and treat a missing review date as a failed documentation build. Each claim carries an identifier, a kind, one statement, a source label, and the exact phrases a draft may repeat. The two claims in the example are operator-supplied availability options, not measured quotas and not a permanence promise. If a statement cannot be sourced, it stays out of the pin, and the draft is not allowed to mention it.

{
  "schema_version": 1,
  "owner": "docs-platform",
  "reviewed_on": "2026-10-10",
  "claims": [
    {
      "id": "AVAIL-001",
      "kind": "access_option",
      "statement": "A free model access option is available for the drafting step.",
      "source": "operator-supplied",
      "allowed_phrases": ["free model access"]
    },
    {
      "id": "AVAIL-002",
      "kind": "compute_option",
      "statement": "A free server option is available for the drafting step.",
      "source": "operator-supplied",
      "allowed_phrases": ["free server option"]
    }
  ]
}

The date in that file is the walkthrough freeze date for this explanation, not a certification of unnamed product terms. A maintainer who adopts the schema replaces both statements with sentences the operator can still support. Changing a statement without changing the review date should fail review, even if the checker does not yet encode that policy. A claim identifier remains stable only for as long as the meaning of its statement remains completely unchanged.

Run the workflow in four steps

1. Freeze the pin on the review date

A maintainer copies only statements supplied for this publication, then sets the review date before opening a drafting session. No model call is allowed to create the file, append a claim, or complete a blank numeric field. The commit that introduces the pin should contain no generated page, so the ownership diff is visible on its own. Later statement edits require a human commit, a new review date, and a note that names the primary source.

2. Mark the draftable region and constrain the prompt

The page template keeps availability sentences outside the draft region, or repeats them only as exact allowed phrases. A model may fill the procedure region with steps for running the checker, reading the failure output, and opening a review. It may not edit the pin, the disclosure paragraph, the ownership table, or any fixture that defines a failure. The markers make that boundary visible, so a diff review can reject an edit that crosses it.

Draft only inside the PROCEDURE markers.
Do not add numbers, durations, hardware nouns, model names, or availability claims.
Repeat an availability phrase only if it appears in allowed_phrases.
If a fact is missing, write OWNER_MUST_SUPPLY rather than guessing.

That prompt is only a constraint, and it is not evidence that any particular model will follow it. The checker remains mandatory because instruction text does not bind a later edit, a paste from a chat, or a merge from another branch. Teams that skip the checker and simply trust the prompt have not actually separated ownership from drafting. Prompt compliance is only an input convenience, while the pin check remains the actual publication gate.

3. Run the checker before prose review

The example below is a proposal, and it was not executed against a production docs tree for this article. It uses only the Python standard library, reads the pin, and scans markdown after removing exact allowed phrases. A remaining digit, duration word, hardware noun, or model-identifier pattern is reported with a line number and a non-zero exit status. Exact repeats of pinned phrases are removed before the scan, so the allowed availability wording can appear without becoming a failure.

#!/usr/bin/env python3
"""Proposal checker: reject availability prose that extends the human pin.

Unexecuted example. Run it locally before adopting it in a docs build.
"""

import json
import re
import sys
from pathlib import Path

DURATION = re.compile(
    r"\b(day|days|month|months|year|years|forever|permanent|hourly)\b",
    re.IGNORECASE,
)
HARDWARE = re.compile(
    r"\b(gpu|cpu|core|cores|region|regions|ram|ssd)\b",
    re.IGNORECASE,
)
NUMBER = re.compile(r"\b\d[\d,._]*\b")
MODEL_ID = re.compile(
    r"\b(?:gpt|claude|gemini|llama|qwen|deepseek)[\w.-]*\b",
    re.IGNORECASE,
)


def load_pin(path: Path) -> tuple[list[str], str]:
    data = json.loads(path.read_text(encoding="utf-8"))
    reviewed = str(data.get("reviewed_on") or "")
    if not reviewed:
        raise SystemExit("pin missing reviewed_on")
    phrases = []
    for claim in data.get("claims", []):
        phrases.append(claim.get("statement", ""))
        phrases.extend(claim.get("allowed_phrases", []))
    return [phrase for phrase in phrases if phrase], reviewed


def scan(markdown: str, phrases: list[str], reviewed: str) -> list[str]:
    redacted = markdown.replace(reviewed, " ")
    for phrase in phrases:
        redacted = redacted.replace(phrase, " ")
    errors = []
    rules = (
        ("number", NUMBER),
        ("duration", DURATION),
        ("hardware", HARDWARE),
        ("model_id", MODEL_ID),
    )
    for index, line in enumerate(redacted.splitlines(), start=1):
        for label, pattern in rules:
            for match in pattern.finditer(line):
                errors.append(
                    f"{label} not in pin at line {index}: {match.group(0)}"
                )
    return errors


def main() -> int:
    if len(sys.argv) != 3:
        raise SystemExit(
            "usage: check_availability_pin.py PIN.json PAGE.md"
        )
    phrases, reviewed = load_pin(Path(sys.argv[1]))
    text = Path(sys.argv[2]).read_text(encoding="utf-8")
    errors = scan(text, phrases, reviewed)
    if errors:
        print("\n".join(errors))
        return 1
    print("availability pin check passed")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

The pass fixture repeats only pinned phrases inside ordinary procedure sentences that a reviewer could ship. The number fixture adds an unsourced integer, and the duration fixture calls an option permanent without a sourced window. Both negative fixtures must exit with status 1 before this publication gate is considered fully defined. These files are part of the owned artifact, not optional illustrations that a later draft is free to delete.

Run the checker against the frozen pin, then read the exit status before editing prose.
The drafting step may use free model access.
The drafting step may use the free server option.

The drafting step includes 123456 units at no cost.

The free server option is permanent.

python3 scripts/check_availability_pin.py \
  docs/ownership/availability-pin.json \
  docs/fixtures/availability_pass.md

python3 scripts/check_availability_pin.py \
  docs/ownership/availability-pin.json \
  docs/fixtures/availability_number.md

The first command is the pass path, and it should exit with status 0 on the clean fixture. The second command should exit with status 1 when its fixture contains an unsourced integer such as 123456. A duration fixture that calls the option permanent must also fail, even though that sentence contains no digits. Store those fixtures beside the pin so a later edit cannot quietly drop the negative cases from the test plan.

4. Review the failure, not the model's confidence

A failing line returns to the owner as an ownership defect, not as a request to make the sentence sound more cautious. Replacing an unsourced integer with a vague magnitude still fails the policy, even if this first checker only catches the listed patterns. The durable fix is deletion, or a human update to the pin with a primary source attached. Prose review should start only after the checker exits with status zero on the page under review.

Checker result	Next action	Not an acceptable fix
Status 0	Human reads the procedure for accuracy	Skipping the diff because the draft sounded sure
Number finding	Delete the integer or pin a sourced value	Rounding it, or calling the figure approximate
Duration finding	Delete the duration	Writing a for-now hedge without a sourced window
Hardware or model-id finding	Delete the noun	Substituting a different unsourced name

Where the drafting step may run

A drafting pass can use MonkeyCode's free model access, or the free server option if the draft should stay off a laptop. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Those two options matter only as the place where procedure prose is generated, after a human has already frozen the pin. They are not a source for quotas, model names, hardware shapes, or any claim that either option is permanent.

The checker still runs in the repository, because a hosted draft does not become an owned fact. The outreach relationship does not extend the pin, and it does not authorize extra capability claims on the page. No model list, token allowance, server size, or retention period appears here, because none was supplied as a sourced pin entry. Teams that need those details should stop, obtain a primary source, and add one narrow claim before drafting.

Limitations and who should skip it

This gate does not understand synonyms, so a draft can still sneak an unsourced limit through unusual wording. It does not verify that an operator-supplied statement remains true later, which is why a person must refresh the review date. It will false-fail version numbers, benchmark tables, and ordinary words such as core, unless those tokens live in a separate allowlist. Teams that need rich numeric docs should split those pages, rather than weakening this checker until it accepts every digit.

Teams should not use this workflow when they lack a named owner for the pin, because an unowned file is only another draft. They should not use it as the sole control for legal terms, security advisories, or pricing pages, where counsel or finance must own the full text. They should not point the checker at vendor blogs or community roundups, because those pages are not availability sources. A private notebook that never publishes product claims will also gain little from maintaining the extra file.

Close the loop before publish

The publication rule is small: freeze the pin, draft only the procedure, and treat every unsourced number as a build failure. Copy the schema, replace the sample claims with statements your operator can source, and run the fixtures before the next publish. If free model access and a free server option are already part of that drafting step, keep them inside the pin as exact phrases. Leave every unsourced limit out, including any limit that would make the page sound more current than the pin.

Keep Escalation Facts Out of Model-Drafted Troubleshooting Pages

Avery Lin — Sat, 10 Oct 2026 09:23:18 +0000

Generated troubleshooting pages remain trustworthy only when escalation facts stay entirely outside the model draft boundary. A model may describe symptoms, quote captured commands, and arrange fixture output into readable prose for reviewers. A human must own severity, data handling, supported versions, and the explicit decision to page an on-call owner. This article specifies that split as a section manifest, a failing checker, and a narrow review path for operators.

Troubleshooting prose fails in a predictable way when a draft copies an incident note into a public page. The draft sounds specific, yet the severity label, retention window, and paging rule were never approved for publication. Readers then treat a generated sentence as an operational commitment, which is a documentation defect rather than a style issue. The workflow below separates draftable narration from owned assertions before any model call is allowed to begin.

Scope of the split

The split applies to internal runbooks that later become public troubleshooting pages, not to legal notices or status pages. It assumes the repository already stores redacted logs, command transcripts, and expected fixture output under version control. It does not assume a particular model vendor, quota, or hosting duration, because those details change and must be read from current terms. Operators who lack a named human owner for escalation facts should stop before generating any public prose.

What the model may draft

The model may draft only those sections that the boundary manifest explicitly marks as model_draftable for this page. Those sections cover symptom narrative, command sequence explanation, and a plain-language reading of fixture output that already exists in the repository. The model may also propose headings, cross-links, and a short note that points readers back toward the owned sections. It may not invent exit codes, version ranges, customer impact, or paging thresholds that are absent from the supplied packet.

A useful draft packet contains exactly three inputs, and it should contain nothing beyond those three inputs. The first input is a redacted symptom log whose timestamps have been removed or normalized before packaging. The second input is the exact command list the operator already ran, including flags that are safe to publish. The third input is the fixture output file that the checker will later hash, so the prose cannot drift from the captured result.

What a human must own

A human must own every sentence that would change operational behavior if a reader followed it literally. That set includes severity, paging criteria, data-retention statements, supported version ranges, and the named escalation owner. The human also owns the decision that a fixture is canonical rather than illustrative, because that choice changes what the page guarantees. Ownership is recorded as an identifier and a review date, not as a vague reviewed badge in the generated file.

Owned sections live in a separate file that the generator is forbidden to overwrite during a draft run. The draft file may quote an owned section by identifier, but the quote is rendered from the owned file at build time. If the owned file changes, the draft is stale until a human re-approves the boundary, even when the surrounding prose still reads well. This rule keeps support commitments attached to a named person instead of a model completion or a merge timestamp.

Decision table

The table below classifies five common runbook sections and states which side may write each one. A missing human owner is a hard failure, while a missing fixture hash is also a hard failure for draftable sections. The failure column is a review rule for the checker, not an estimate of how often drafts misbehave. Edit the rows before adoption so they match the support policy your readers already rely on.

Section	Class	Model may draft	Human must own	Failure if missing
Symptom narrative	model_draftable	Yes, from a redacted log	Confirm that no secrets remain	Checker rejects raw tokens
Command explanation	model_draftable	Yes, from listed commands	Confirm that flags are publishable	Checker rejects unknown flags
Fixture reading	model_draftable	Yes, from a hashed fixture	Mark the fixture canonical or sample	Checker rejects a hash mismatch
Severity and paging	human_owned	No	Severity, page rule, and owner	Checker rejects model markers
Retention and versions	human_owned	No	Retention statement and version range	Checker rejects forbidden draft phrases

The table is a proposal for this workflow, not a measured benchmark and not a claim about any vendor's accuracy. Teams should edit the forbidden-phrase list to match their own support policy before they trust the gate. A phrase that is harmless in one product can be a commitment in another, so the list is local data.

Numbered workflow

Follow the five steps in order, and do not skip the packet check merely to save a model call. Each step writes or reads a file that the next step can verify without opening a chat transcript. The sequence assumes a single runbook page, though the same manifest shape can list several pages. If a step fails, fix that file and rerun the checker before you continue to the model path.

Create the boundary file, list every section with a class and an owner, and keep owned sources outside the draft directory.
Redact logs, copy only publishable commands into the packet directory, and store a SHA-256 digest beside each fixture.
Run the checker in packet mode so it refuses the job when a forbidden key appears in the packet.
Send only model-draftable section briefs to the model path, then write the result under the draft directory with a provenance footer.
Run the checker in draft mode, render a local preview, and require the named owner to update the review date before merge.

Each step is intentionally small so a failed check points at one file rather than a whole conversation. The generator never receives the owned directory as writable context during the model call or the preview build. If a step needs a new operational fact, a person adds that fact to the owned file and rebuilds the packet. That rebuild is the only path by which a new fact becomes visible to later narration.

Proposed checker

The following Python is an unexecuted example intended for a repository CI job, and it does not call a remote API. It is not a production library, so install PyYAML yourself and review the marker format before you rely on it. The script reads a YAML boundary, hashes fixtures, and scans drafts for markers that indicate owned-section contamination. Adapt the forbidden list to your support policy, because the sample phrases are illustrations rather than a complete policy.

#!/usr/bin/env python3
"""Unexecuted example: reject drafts that touch human-owned runbook facts."""
from __future__ import annotations

import hashlib
import re
import sys
from pathlib import Path

import yaml  # proposal: PyYAML; pin it in your own lockfile

BOUNDARY_MARK = re.compile(
    r"<!--\s*boundary:\s*([a-z0-9-]+)\s+class:\s*(human_owned|model_draftable)"
)
FORBIDDEN = ("page immediately", "retention is", "supported since", "severity: p")


def read_text(path: Path) -> str:
    if not path.is_file():
        raise SystemExit(f"missing file: {path}")
    return path.read_text(encoding="utf-8")


def sha256(path: Path) -> str:
    return hashlib.sha256(path.read_bytes()).hexdigest()


def load_boundary(path: Path) -> dict:
    data = yaml.safe_load(read_text(path))
    if not isinstance(data, dict) or "sections" not in data:
        raise SystemExit("boundary file missing sections")
    return data


def marker_error(path: Path, section_id: str, klass: str) -> str | None:
    match = BOUNDARY_MARK.search(read_text(path))
    if not match:
        return f"{path}: missing boundary marker"
    found_id, found_class = match.group(1), match.group(2)
    if found_id != section_id or found_class != klass:
        return f"{path}: marker {found_id}/{found_class} != {section_id}/{klass}"
    return None


def check_packet(boundary: dict, root: Path) -> list[str]:
    errors: list[str] = []
    for section in boundary["sections"]:
        if section["class"] != "model_draftable":
            continue
        packet = root / section["packet"]
        err = marker_error(packet, section["id"], "model_draftable")
        if err:
            errors.append(err)
        text = read_text(packet).lower()
        for phrase in FORBIDDEN:
            if phrase in text:
                errors.append(f"{packet}: forbidden phrase {phrase!r}")
        fixture = root / section["fixture"]
        if sha256(fixture) != section["fixture_sha256"]:
            errors.append(f"{fixture}: hash mismatch")
    return errors


def check_draft(boundary: dict, root: Path) -> list[str]:
    errors: list[str] = []
    for section in boundary["sections"]:
        if section["class"] != "human_owned":
            continue
        if not section.get("owner") or not section.get("reviewed_on"):
            errors.append(f"{section['id']}: owner and reviewed_on required")
        source = root / section["source"]
        err = marker_error(source, section["id"], "human_owned")
        if err:
            errors.append(err)
        owned = read_text(source)
        if "MODEL_DRAFT" in owned or "provenance:" in owned:
            errors.append(f"{section['source']}: model marker in owned file")
        sibling = section.get("draft_sibling")
        if not sibling:
            errors.append(f"{section['id']}: draft_sibling required")
            continue
        draft = root / sibling
        if draft.exists() and owned.strip() and owned.strip() in read_text(draft):
            errors.append(f"{draft}: owned text copied into draft; render it at build time")
    return errors


def main() -> int:
    if len(sys.argv) != 4 or sys.argv[1] not in {"--packet", "--draft"}:
        print("usage: check_runbook_boundary.py --packet|--draft BOUNDARY ROOT")
        return 2
    mode, boundary_path, root = sys.argv[1], Path(sys.argv[2]), Path(sys.argv[3])
    boundary = load_boundary(boundary_path)
    if mode == "--packet":
        errors = check_packet(boundary, root)
    else:
        errors = check_draft(boundary, root)
    for err in errors:
        print(err)
    return 1 if errors else 0


if __name__ == "__main__":
    sys.exit(main())

Marker files

Place the boundary marker on the first lines of each packet and each owned file so the checker can confirm identity. The marker is a review aid, not a security control, because a writer can still add unsafe prose below it. Use the packet example only after redaction, and use the owned example only as a shell for human text. Do not copy the sample paging sentence into a real page, because it is a placeholder rather than a policy.

<!-- boundary: symptom-narrative class: model_draftable -->

The health command exits with status 1.
The captured stderr is stored in the fixture file.
No customer name appears in this packet.

<!-- boundary: escalation class: human_owned -->

Owner: oncall-lead
Paging rule: replace this sentence with human-authored policy.

A matching manifest can start as the short YAML file shown below, with dates and hashes treated as placeholders. Those placeholders are not observed measurements, and you should replace them after you compute digests locally. The owned section records a person and a review date, while the draftable section records a packet and a fixture hash. Keep the two records in one manifest so a reviewer can see the split without opening the generator prompt.

sections:
  - id: symptom-narrative
    class: model_draftable
    packet: docs/runbooks/packet/symptom.md
    fixture: docs/runbooks/packet/fixture.txt
    fixture_sha256: "replace-with-real-sha256"
    owner: none
  - id: escalation
    class: human_owned
    source: docs/runbooks/owned/escalation.md
    owner: oncall-lead
    reviewed_on: "2026-10-10"
    draft_sibling: docs/runbooks/draft/escalation.md

The commands below are a local shell sequence, not a vendor CLI, and they assume the script sits in the working directory. The first command blocks a contaminated packet before any model is allowed to receive those files. The second command blocks an owned file that contains draft markers or a draft that inlines owned text. The third command prints the digest you paste into the manifest after you recompute it on your own machine.

python3 check_runbook_boundary.py --packet docs/runbooks/boundary.yaml .
python3 check_runbook_boundary.py --draft docs/runbooks/boundary.yaml .
sha256sum docs/runbooks/packet/fixture.txt

Where a free model path and a free server fit

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode's free model access is a reasonable place to draft only the model-draftable packet, provided you confirm current terms first. The free server option is a reasonable place to run the same checker and to serve the owner preview. Those two availability claims are operator-supplied for this article, and they are not quotas, hardware specs, or duration limits. They are also not a promise that the offer remains unchanged, so read the current terms before a release gate depends on them.

The model path should receive the packet directory and the section brief, not the owned directory as context. The server path should run the same checker binary you would run in CI, then expose the draft preview to the named owner. If either option is unavailable, the workflow still stands on a laptop, because the artifact does not require a hosted model to be valid. Using a free path does not reduce the human review step or justify an accuracy claim without a published measurement.

Limitations

The checker looks for phrases and markers, so a paraphrase can still smuggle a paging rule into a symptom section. Hash checks prove the fixture bytes did not change, but they do not prove the fixture was redacted correctly. A review date shows who accepted the owned file, yet it does not prove the owner still holds that role next week. Teams should add a periodic owner lookup outside this script rather than treating the review date as a permanent approval.

This example also ignores localization, screenshots, and diagrams, which can carry commitments the phrase list never sees. A translated page can reintroduce a forbidden commitment even when the source draft passed the checker cleanly. Screenshot text stays invisible to the phrase list unless you extract that text before the draft check runs. Those gaps are reasons to keep the gate narrow, not reasons to let the model own escalation facts.

Who should not use this approach

Skip this approach if you have no named owner for severity and paging, because the manifest would then record a fiction. Skip it for customer-specific incident reports, where even a carefully redacted symptom narrative may remain confidential. Skip it if the page is a contractual service commitment or a security advisory, because those documents need counsel rather than a phrase list. Skip it if you cannot keep the owned file out of the model context, since the split would then exist only on paper.

Closing

Treat the manifest as the contract between draft prose and operational facts, and regenerate narration only after that contract still passes. The checker is a proposal you can copy, pin, and extend with the forbidden phrases your support policy already uses. If you want a hosted place to draft only the allowed sections, confirm MonkeyCode's current free model access and free server option. Then keep the owned file on the human side of the boundary, regardless of which host runs the checker.

An Owned Command Matrix for Setup Guides That Models Must Not Extend

Avery Lin — Sat, 10 Oct 2026 02:46:46 +0000

Generated setup guides stay reviewable when humans freeze commands, versions, and expected exits before any model writes narrative. That split stops a fluent paragraph from becoming the source of truth for a flag that nobody ran. The workflow uses a boundary file, a deterministic checker, and a narrow drafting pass with an explicit human owner. The examples below are a labeled proposal, and they were not executed against a production repository or a live package index.

Why setup prose outruns the last verified install

Install pages fail quietly when a draft invents a package flag, a minimum version, or a success line the last release never produced. Reviewers often approve the page because the sentences sound finished and the headings match the existing product voice. The operational facts sit inside those sentences, so a later release can change a flag without a named owner. A support matrix makes those facts visible and reviewable before anyone requests narrative from a model.

Split the page into a matrix lane and a narrative lane

The page has two lanes that meet only at review time, and neither lane is allowed to silently edit the other. The matrix lane stores owned facts, while the narrative lane stores explanations that must quote those facts rather than replace them. A fixture file sits beside each matrix row and holds the captured output from the last human verification. If a sentence in the draft conflicts with a row, the row wins and the sentence is rewritten or removed.

What the model may draft

A model may draft the section introduction, the reason a step exists, and a plain restatement of an owned command. It may draft troubleshooting hypotheses when each hypothesis is labeled unverified and cites a matrix row identifier. It may propose shorter headings when the owned command, version, and exit code remain byte-for-byte unchanged. It may not invent package names, version floors, environment variables, exit codes, download URLs, or alternate installers.

What a human must own

A human must own the operating system label, the package manager, the minimum version, and the exact install command. The same owner must record the expected exit code, the verification date, and the repository path of the fixture output. Those fields are the only inputs the checker treats as facts, and narrative quality never repairs a missing pin. Ownership here means a named person or rotation can refresh the row, not a shared inbox that nobody checks.

Store facts in a synthetic matrix

The JSON file below is synthetic, and the package name, versions, and dates are placeholders rather than measured results. Replace every placeholder after a person runs the command on a machine your team actually supports. Keep one row per supported path so a partial guide cannot hide an unverified installer inside a combined paragraph. Store the file in the docs repository so the review diff shows fact changes separately from prose changes.

{
  "schema": "support-matrix/v1",
  "rows": [
    {
      "id": "linux-apt",
      "os": "linux-placeholder",
      "manager": "apt",
      "min_version": "0.0.0-placeholder",
      "command": "sudo apt-get install -y examplectl",
      "expect_exit": 0,
      "verified_on": "YYYY-MM-DD",
      "fixture": "fixtures/linux-apt.out",
      "owner": "docs-platform-rotation"
    },
    {
      "id": "macos-brew",
      "os": "macos-placeholder",
      "manager": "brew",
      "min_version": "0.0.0-placeholder",
      "command": "brew install examplectl",
      "expect_exit": 0,
      "verified_on": "YYYY-MM-DD",
      "fixture": "fixtures/macos-brew.out",
      "owner": "docs-platform-rotation"
    }
  ]
}

Read the boundary as a decision table

The table below states the draft boundary in operational terms, which is easier to audit than a style guide paragraph. Use it during review when a sentence feels helpful but introduces a new flag, a new host, or a new success claim. If a cell says the human owns the field, the model output may mention it only by copying the matrix value. If a cell says the model may draft it, the checker does not treat that text as evidence of a working install.

Field or passage	Lane	Who may write it	Checker rule
Install command	Matrix	Human owner	Exact match required inside shell fences
Minimum version and exit code	Matrix	Human owner	Not inferred from prose
Fixture stdout and stderr	Fixture	Human owner	Not rewritten by the model
Why the step exists	Narrative	Model draft, then human edit	Must not add commands
Unverified troubleshooting idea	Narrative	Model draft, then human edit	Must cite a row id and must not be stated as fact

Run the workflow in five steps

1. Freeze one row per supported path

Start from the install paths you already support, and write one row before you open a drafting session. Copy the command from a shell history you trust, or retype it from the last release checklist, not from memory alone. Record the exit code you observed, including a non-zero code when the supported path is a documented failure. Leave the narrative file untouched until every supported path has an owner, a command, and a fixture path.

2. Capture fixture output without cleanup

Run the owned command in the environment named by the row, and save standard output and standard error without editing. Commit the fixture next to the matrix so a reviewer can see the captured text that the prose will later summarize. Do not let a model rewrite the fixture into a cleaner transcript, because cleanup is how invented success lines appear. If the command prints secrets, redact them with a documented rule before commit, and record that rule beside the row.

# proposal: capture the owned command; do not let a model rewrite this file
brew install examplectl > fixtures/macos-brew.out 2>&1
echo fixture_exit=$?

3. Reject unknown shell fences

Point the checker at the matrix and the markdown file so unknown shell lines fail before anyone requests new prose. The proposal script reads only fenced bash, sh, and shell blocks, and it ignores prose that merely names a tool. A failing exit means the draft contains a command the matrix does not own, not that the install itself is broken. Fix the failure by adding a verified row or by deleting the shell line, and do not silence the checker with a waiver comment.

Run the two commands below from the repository root after you place both files on the paths shown in the example. A zero exit means every fenced shell line matches an owned command, while a non-zero exit prints the unmatched lines. Treat the script as unexecuted proposal code, and read it before you rely on it in a continuous integration job. Extend the matcher only when your guides use a fence label the pattern does not already include.

python3 check_install_matrix.py support-matrix.json docs/install.md
echo checker_exit=$?

4. Request narrative by row identifier

Ask for narrative that explains each row identifier, and require the draft to repeat the owned command without edits. Ask for a short note on why the step exists, and forbid new flags, new packages, and new version comparisons. Ask for troubleshooting ideas only as unverified hypotheses that cite a row identifier and a fixture filename. Reject any completion that adds a shell block, even when the added command looks like a harmless variant of the owned line.

5. Let the named owner accept the diff

The named owner reads the diff, confirms the matrix did not change inside the prose pull request, and accepts or returns the narrative. A docs editor may improve clarity, but that editor may not update a version, a command, or an exit code alone. If the command must change, update the matrix and the fixture first, then regenerate the narrative in a follow-up commit. Merge only when the checker exits zero and the owner has confirmed the verification date is still within your team policy.

Inspect the proposal checker

The script builds a set of owned commands and compares each non-comment shell line from the draft against that set. Matching is exact, including spacing, because a changed flag is a different command even when the package name stays the same. Comment lines inside a fence are ignored so reviewers can annotate a block without creating a false missing command. The script does not execute the install command, does not fetch packages, and does not judge whether the fixture is stale.

#!/usr/bin/env python3
'''Proposal only: unexecuted checker. Rejects fenced commands absent from the matrix.'''

import json
import sys
from pathlib import Path

def load_matrix(path):
    data = json.loads(Path(path).read_text(encoding='utf-8'))
    return {row['command'] for row in data['rows']}

def fenced_commands(text):
    found = []
    marker = '`' * 3
    parts = text.split(marker)
    for index in range(1, len(parts), 2):
        header, sep, body = parts[index].partition(chr(10))
        if header.strip() not in ('bash', 'sh', 'shell'):
            continue
        for line in body.splitlines():
            stripped = line.strip()
            if stripped and not stripped.startswith('#'):
                found.append(stripped)
    return found

def main(argv):
    owned = load_matrix(argv[1])
    draft = Path(argv[2]).read_text(encoding='utf-8')
    missing = [cmd for cmd in fenced_commands(draft) if cmd not in owned]
    if missing:
        print('unowned commands:')
        for cmd in missing:
            print('- ' + cmd)
        return 1
    print('ok: ' + str(len(owned)) + ' owned commands, no extra shell lines')
    return 0

if __name__ == '__main__':
    sys.exit(main(sys.argv))

The main function returns one when any fenced line is missing from the matrix, and it returns zero when the sets agree. It prints a short summary on success so a log shows how many owned commands were loaded during that run. It does not parse continuations, and a fence marker inside the page can confuse the simple split. Those gaps are intentional in this proposal, because a small exact matcher is easier to audit than a shell interpreter.

An illustrative failure, not a measured run, would look like the lines below if a draft added an unowned flag. The checker would exit one and print the extra shell line so the owner can delete it or verify it first. That output is a format example for reviewers, and it is not evidence that any package manager returned those words. Use that sample only to explain the log shape during a design review, not as a recorded result from a package manager.

unowned commands:
- brew install examplectl --HEAD

Show a draft that stays inside the boundary

The markdown fragment below is also synthetic, and it shows how narrative can cite a row without adding a second installer. The shell fence repeats the owned command exactly, which is the only shape the proposal checker will accept. The hypothesis sentence names the row and the fixture, and it does not promote the guess into a supported step. A reviewer should still compare the fence with the matrix, because the checker does not understand synonyms or wrapped lines.

## Install on the apt path

The `linux-apt` row is the supported path for this placeholder page.
The command below is copied from that row and must not be edited in prose.

```bash
sudo apt-get install -y examplectl
```

If `fixtures/linux-apt.out` disagrees with this command, the matrix is stale and the prose must not paper over it.
Unverified hypothesis: a held package could explain a non-zero exit, but that idea cites `linux-apt` and is not a new command.

Use a free drafting pass without moving ownership

Once commands are frozen, the narrative lane is a bounded drafting task rather than a source of install facts. MonkeyCode's free model access can draft that lane, and its free server option can run the same checker you already trust locally. Disclosure: This article was prepared as part of MonkeyCode's product outreach. If this split matches your review, use that free model access for narrative only, and leave every command under the named owner.

This draft does not claim model names, quotas, hardware, duration, benchmarks, or permanence, because those details were not supplied. Keep fixtures in your repository, and treat a hosted run as a convenience that must match the local script. If the hosted result and the local script disagree, trust the local script and investigate the input files first. Do not send secrets, customer hostnames, or private fixture output to a hosted checker unless your policy already allows it.

Limitations of the checker and the split

The checker cannot prove that a command still works, because it never runs the installer or inspects the target machine. Exact string matching misses equivalent commands that differ only by argument order, quoting, or an inserted environment prefix. A stale verification date looks valid to the script, so your team still needs a calendar policy outside the code. Multi-line pipelines, heredocs, and generated shell from templates require a stricter parser than the proposal includes.

The approach also fails if reviewers paste commands into prose without fences, since those lines are invisible to the matcher. Fixture files can drift from the matrix when someone updates a command and forgets to replace the captured output. The proposal does not hash the fixture, so a follow-up change could add a digest if your review process needs it. Nothing here validates license text, trademark lines, or regional download rules that some install pages must carry.

Who should not use this workflow

Skip this workflow if no person can own each row, because an unowned matrix becomes another document that quietly rots. Skip it for marketing pages that contain no commands, since the checker would pass while saying nothing useful about claims. Skip it when install facts change many times a day and nobody can refresh fixtures before narrative is requested. Skip it for command lines that embed secrets, tokens, or customer hostnames, and keep those values out of both lanes.

What the split does and does not prove

The practical conclusion is narrow: freeze the support matrix, check fenced commands, and only then allow drafted explanation. Human ownership covers commands, versions, exits, dates, and fixtures, while the model covers clarity around those pins. That division will not make an install guide complete, but it will stop generated prose from owning facts it cannot verify. Adopt the checker only after a human reads the proposal and decides the exact-match rule fits the guides you publish.

Pin Failure Contracts Before Drafting Troubleshooting Pages

Avery Lin — Fri, 09 Oct 2026 20:00:38 +0000

Generated troubleshooting pages stay trustworthy only when a human-owned failure contract pins every status, retry class, and compensation rule before prose exists. A model may draft explanations, examples, and sequencing language that cite those pins, but it must not invent operational facts. A small checker then rejects any draft sentence that asserts a code, a wait, or a side effect absent from the pin file. Teams that skip the pin will publish fluent pages that disagree with the tests that actually define the API.

The split that keeps drafts from owning behavior

Public API docs fail in a narrow way: the narrative sounds specific while the numbers and side effects are unverified. Readers follow a retry hint, a status table, or a compensation step, then hit production behavior that the page never extracted from tests. That gap is a documentation ownership problem, not a wording problem, because fluent prose cannot repair a missing contract. The workflow below treats the contract as the only mergeable source for operational claims in the published page.

A useful page still needs readable recovery language, sample requests, and a short sequence of what the caller should try next. Those parts are draftable once each sentence points at a pin identifier that a human already accepted. The model is a drafter of exposition, and the human remains the owner of behavior, scope, and publication. This split is stricter than a style review, because style review never checks whether a status code exists.

Claim classes in one decision table

Claim class	Example in a page	Drafter	Owner	Merge rule
Transport status	HTTP 409 on duplicate submit	Extract from tests	Human	Prose must quote the pin row
Retry class	safe to retry with the same key	Human label only	Human	Draft may not upgrade the class
Wait or backoff	two seconds, three attempts	Human if stated	Human	Omit unless the pin records it
Compensation	void the hold, then refresh	Human sequence	Human	Draft may explain, not reorder
Caller explanation	why the cart looks unchanged	Model	Human edits tone	Allowed if it cites a pin id
Sample payload	redacted request body	Model from fixture	Human confirms redaction	Fixture path must be in the pin
Escalation severity	page the on-call tier	Nobody but the human	Human	Forbidden in generated drafts
Support promise	response within an hour	Nobody but the human	Human	Forbidden in generated drafts

The table is the editorial policy for this workflow, and it should live next to the pin file in the same review. Rows marked Forbidden stay out of generated drafts, and a later edit may not soften them into hints. If a fact is missing from the pin, the page must stay silent rather than guess a helpful number. Reviewers should treat a missing cell as an omission, not as permission for the drafter to fill a plausible value.

What the model may draft

The model may draft opening context, the plain meaning of a pin row, and a short example copied from a named fixture. It may also draft transition sentences that connect two pin identifiers without adding a new status, a new wait, or a new side effect. It may propose headings, a glossary sentence, and a short what-you-will-see paragraph when every concrete token appears in the pin. It may not draft escalation policy, billing outcomes, legal remedies, security workarounds, or any promise about support response time.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. Free model access is enough for this drafting pass, because the task is bounded exposition over a pin the human already wrote. Use the free server option only as a review surface after you confirm what that option actually provides. Do not assume retention, isolation, quotas, or hardware from this article, and confirm those limits with the operator before you depend on them.

What a human must own

Extract failure rows only from the tests or handlers that define the behavior, and reject rows that survive only in old wiki pages.
Assign a stable pin identifier, a retry class, and an explicit compensation list, including an empty list when no compensation exists.
Record fixture paths for every sample the page may show, and strip secrets before that fixture becomes eligible for drafting.
Review the drafted essay only after the checker passes, then sign the pin hash so later prose edits cannot drift silently.

Human ownership here means the person can defend each row against the test suite, not merely approve the tone of the paragraph. If nobody can point to the asserting test, the row stays out of the pin and out of the page. That rule slows the first page and prevents a second page from laundering the same guess. The signature belongs on the pin, not on the model draft, because the draft is replaceable and the contract is not.

Build the pin file

The pin format below is a proposal you can commit beside the docs tree, and it is not a measured production schema. It stays small on purpose, so a reviewer can diff behavior without reading the surrounding essay. Each row names the asserting test, which keeps the contract tied to executable evidence rather than to memory. Empty compensation arrays are valid and should stay explicit, because silence is not the same as an empty list.

{
  "pin_version": 1,
  "surface": "checkout.submit",
  "rows": [
    {
      "id": "FC-409-DUP",
      "status": 409,
      "retry_class": "same_key_safe",
      "compensation": [],
      "fixture": "fixtures/dup_submit.json",
      "asserted_by": "tests/checkout_test.py::test_duplicate_submit",
      "caller_may_see": "duplicate submit"
    },
    {
      "id": "FC-422-FIELD",
      "status": 422,
      "retry_class": "fix_then_new_attempt",
      "compensation": ["drop the invalid field"],
      "fixture": "fixtures/bad_field.json",
      "asserted_by": "tests/checkout_test.py::test_unknown_field",
      "caller_may_see": "unknown field"
    }
  ]
}

Check drafts before they can merge

The checker is an unexecuted example, not a measured production gate, and you should run it in your own repository before you trust it. It loads the pin, collects allowed tokens, and fails when the markdown invents a status code or a forbidden phrase. It also requires every cited pin identifier to exist, and it requires every status in the page to be listed. Extend the forbidden list for your own support promises rather than weakening the defaults to quiet a noisy draft.

#!/usr/bin/env python3
"""Unexecuted example: reject troubleshooting drafts that outrun the pin."""

import json
import re
import sys
from pathlib import Path

FORBIDDEN = (
    "page the on-call",
    "within an hour",
    "guaranteed",
    "we will refund",
    "severity 1",
)

def main() -> int:
    pin = json.loads(Path(sys.argv[1]).read_text())
    draft = Path(sys.argv[2]).read_text()
    rows = pin["rows"]
    allowed_status = {str(row["status"]) for row in rows}
    allowed_ids = {row["id"] for row in rows}
    errors: list[str] = []

    for code in set(re.findall(r"\b[1-5]\d{2}\b", draft)):
        if code not in allowed_status:
            errors.append(f"status {code} is not in the pin")

    for pin_id in set(re.findall(r"\bFC-\d{3}-[A-Z0-9-]+\b", draft)):
        if pin_id not in allowed_ids:
            errors.append(f"unknown pin id {pin_id}")

    lowered = draft.lower()
    for phrase in FORBIDDEN:
        if phrase in lowered:
            errors.append(f"forbidden phrase: {phrase}")

    mentioned = set(re.findall(r"\bFC-\d{3}-[A-Z0-9-]+\b", draft))
    if not mentioned:
        errors.append("draft cites no pin id")

    if errors:
        print("\n".join(errors))
        return 1
    print(f"ok: {len(rows)} pin rows, {len(mentioned)} ids cited")
    return 0

if __name__ == "__main__":
    raise SystemExit(main())

python3 check_failure_pin.py failure_contract.json docs/checkout-failures.md

The commands above are the local gate, and they do not require a hosted model at all. Run them in continuous integration on every docs pull request that touches a troubleshooting page in the repository. If the checker fails, fix the pin or delete the sentence, and do not ask the model to invent a matching row. A green run only means the draft stayed inside the pin, not that the pin matches production behavior today.

Numbered drafting procedure

Freeze the pin and record its hash before any model call, so the draft cannot quietly edit the contract underneath the review.
Send the model only the pin rows, the fixture excerpts, and a written instruction to cite pin identifiers and omit unknown numbers.
Write the draft to a branch, run the checker locally, and run it again in continuous integration before a human reads for tone.
If a free server option is available, use it only for the drafting review, and merge only after the pin hash is unchanged.

Step two is where free model access fits, because the input is a closed set of rows rather than an open invention request. Keep the prompt narrow: explain the listed rows, quote status values only from those rows, and leave escalation blank. If the model adds a backoff interval, treat that as a failed draft even when the sentence sounds cautious. The human adds waits only by editing the pin first, then regenerating the explanation from the updated rows.

Review notes that belong in the pull request

A reviewer should see four artifacts in one change: the pin, the asserting tests, the draft, and the checker output. The review comment should name the pin hash and the ids the page cites, rather than saying that the page looks complete. Completeness is not a property of prose length, and a short page citing two real rows is safer than a long silent page. If the tests changed since the pin was frozen, the pin update is a separate commit with its own owner.

Compare the draft against the decision table before you approve wording, and allow explanation to move only when the cited fixture is unchanged. Retry class, compensation order, and status codes cannot move unless the pin diff shows the same change in the same review. That comparison takes minutes when the table lives in the repository, and much longer when the policy lives only in chat. Keep the table versioned with the pin so a future reviewer can see which policy governed the merged page.

Limitations you should keep visible

This checker catches status-shaped numbers and a short forbidden list, and it will miss paraphrases that smuggle a new side effect without a code. A sentence such as "the hold is released automatically" can pass the regex while still inventing compensation the pin left empty. A human reading pass remains mandatory, and the checker is a floor rather than a proof of behavioral accuracy. You should add project-specific patterns for currency amounts, region names, and retry counts if those tokens appear in your pages.

The pin is only as true as the tests it names, so a stale test will stamp a stale contract with false confidence. Free model output can still be wrong inside the allowed vocabulary, for example by swapping two pin explanations while citing both identifiers. A review on the free server option does not validate behavior, execute the suite, or replace the local checker in continuous integration. Nothing in this workflow measures latency, cost, or quality scores, and you should not invent those numbers to justify the gate.

Who should not use this approach

Skip this workflow when the failure behavior lives only in production logs and nobody can point to an asserting test or handler. Skip it for security advisories, legal terms, billing promises, and live incident notices that need a named owner. Skip it if the team will treat a green checker as permission to publish without reading the compensation column. Also skip it when the API surface changes hourly and the pin cannot be frozen for the length of one review.

Small libraries with one obvious error type may not need the full table, and a single owned example in the README can be enough. Large platforms with several client languages should still keep one pin per surface, then let language pages cite it instead of restating codes. Duplicating the contract into every SDK guide recreates the drift this gate is meant to stop. If two pages must differ, the difference belongs in the pin as a client note, not in untracked prose.

Keep the essay replaceable

The practical conclusion is narrow: freeze behavior in a pin, and block merge when drafted sentences outrun that file. Free model access fits the drafting step, and the free server option is only a review surface, but neither one owns the status map. The checker and the human signature are the parts you should keep even if you later swap the drafting tool. If asserting tests already exist, start with two pin rows, then try one free model pass only after the hash is frozen.

Freeze a Repo Contract Before Drafting Contributor Orientation

Avery Lin — Fri, 09 Oct 2026 15:44:13 +0000

Generated contributor pages fail when a drafting model is allowed to invent owners, secrets, and license duties. Teams should freeze those facts in a repo contract before any orientation narrative is written at all. The model may explain existing contract entries in plain language, but it may not create new entries. A local checker can then reject drafts that cite missing identifiers or insert unsupported product claims.

This split matters because onboarding text can look authoritative even when nobody has reviewed its hidden assumptions. A new contributor may treat a generated path owner as if it were a real review rule. The same reader may copy a generated secret location into a shell script before anyone notices the error. The contract file keeps those high-impact lines explicit, reviewable, and separate from ordinary prose style choices.

Public drafting tools have made this particular failure cheaper to produce and easier to merge unnoticed. A short prompt can expand a plain README into a welcoming guide that sounds unusually specific. Specificity is not the same thing as custody, because a fluent sentence can name a path that no human approved. The workflow below treats custody as a reviewed file, and it treats fluency as a later pass.

What the model may draft

The model may draft transitions, definitions, and step explanations that cite identifiers already present in the contract. It may also propose heading order, a glossary paraphrase, and a short where-to-look-next close. Those drafts should stay inside a marked section so review tools can scan them apart from owned facts. If a sentence needs a new owner, secret, license, or version, the model should stop and leave a gap.

That boundary is narrower than a blanket request to write the entire onboarding page from scratch. Narrative help is allowed only when every concrete noun in the sentence is already an identifier. Allowed sentences include pointers to [[cmd-test]] and short reminders that the reader should open [[lic-apache]] next. Disallowed sentences include new support windows, new token quotas, and new claims about which service is free.

The checker below enforces the easy cases and leaves harder judgment calls to the named human owner. It does not understand intent, and it will not rescue a prompt that asks for new facts. Reviewers should still read the draft, because a clean citation can sit beside a misleading verb.

What a human must own

A human owner must freeze path ownership, secret names, license identifiers, and the commands a new contributor is expected to run. The same person, or a named delegate, must freeze which version strings may appear in the draft. Ownership here means the right to change the contract, not a vague note that docs already reviewed this. The owner stamp belongs in the contract file and again beside the human-owned heading in the page.

Humans must also own any sentence that could change legal, security, or support behavior if it were wrong. That set includes where credentials live, which files require review, and which license text actually applies. A model can restate those rows after they exist, using the citation marks defined in the artifact below. It cannot be the source of the row, even when the generated wording sounds more polished than the table.

Permission boundary

Read the table as a permission boundary, not as a style guide for tone or length. Rows marked for humans stay in the contract even when the model could guess a plausible value. Rows marked for the model still have to cite an identifier when they mention a concrete repo fact. The checker implements only the rows that a surface pattern can see, so the table remains the editorial rule.

Claim in the orientation page	Model may draft	Human must own
Heading order and transitions	Yes, inside Model draft	No
Restatement of an existing contract id	Yes, with a `[[id]]` citation	The source row
Path reviewer	No	Yes, in the owners table
Secret handling rule	No	Yes, in the secrets table
License identity	No	Yes, in the licenses table
Command and expected result	No	Yes, in the commands table
Version string	Only if already listed	`allowed_versions`
Pricing, quota, uptime, or SLA	No	Out of scope for this page

Proposed artifact

The following files are a proposed local check, and they were not executed while this article was written. These examples use Python 3.11 because tomllib ships in the standard library from that version onward. The citation mark is a double-bracket identifier such as [[own-docs]], which is easy to grep and hard to confuse with Markdown links. You should treat the patterns as a starting gate, not as a proof that the prose is true.

Contract file, repo-contract.toml:

owner = "docs-platform"
reviewed = "2026-10-09"

allowed_versions = ["3.11", "3.12"]

[[owners]]
id = "own-docs"
path = "docs/"
reviewer = "@docs-platform"

[[secrets]]
id = "sec-none-local"
rule = "Local orientation uses no production secret."

[[licenses]]
id = "lic-apache"
spdx = "Apache-2.0"
note = "License text in LICENSE is the source."

[[commands]]
id = "cmd-test"
argv = "python -m unittest discover -s tests"
expect = "exit 0 on a clean tree"

Checker, check_orientation.py:

#!/usr/bin/env python3
"""Proposed gate. Not executed for this article."""

from __future__ import annotations

import re
import sys
from pathlib import Path

try:
    import tomllib
except ModuleNotFoundError:  # Python older than 3.11
    sys.stderr.write("Python 3.11+ is required for tomllib\n")
    raise SystemExit(2)

FORBIDDEN = re.compile(
    r"\b(uptime|pricing|quota|sla|guarantee|free forever)\b",
    re.IGNORECASE,
)
CITE = re.compile(r"\[\[([A-Za-z0-9_-]+)\]\]")
VERSION = re.compile(r"\b\d+\.\d+(?:\.\d+)?\b")


def load_contract(path: Path) -> dict:
    data = tomllib.loads(path.read_text(encoding="utf-8"))
    ids = set()
    for section in ("owners", "secrets", "licenses", "commands"):
        for row in data.get(section, []):
            ids.add(row["id"])
    data["_ids"] = ids
    data["_versions"] = set(data.get("allowed_versions", []))
    if not data.get("owner"):
        raise ValueError("contract owner is required")
    return data


def check(markdown: str, contract: dict) -> list[str]:
    errors = []
    if "## Human-owned contract" not in markdown:
        errors.append("missing heading: Human-owned contract")
    if "## Model draft" not in markdown:
        errors.append("missing heading: Model draft")
    head, _, draft = markdown.partition("## Model draft")
    if f"owner: {contract['owner']}" not in head:
        errors.append("human owner stamp missing above the draft")
    for match in FORBIDDEN.finditer(draft):
        errors.append(f"forbidden claim in draft: {match.group(0)}")
    for match in CITE.finditer(draft):
        if match.group(1) not in contract["_ids"]:
            errors.append(f"unknown citation: {match.group(1)}")
    if not set(CITE.findall(draft)):
        errors.append("model draft cites no contract ids")
    for match in VERSION.finditer(draft):
        if match.group(0) not in contract["_versions"]:
            errors.append(f"version not in contract: {match.group(0)}")
    return errors


def main() -> int:
    if len(sys.argv) != 3:
        sys.stderr.write("usage: check_orientation.py repo-contract.toml PAGE.md\n")
        return 2
    contract = load_contract(Path(sys.argv[1]))
    page = Path(sys.argv[2]).read_text(encoding="utf-8")
    errors = check(page, contract)
    if errors:
        sys.stderr.write("\n".join(errors) + "\n")
        return 1
    print("orientation draft accepted")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

Sample page fragment, docs/orientation.md:

## Human-owned contract

owner: docs-platform

Facts below are copied from repo-contract.toml and are not model output.
Path docs/ is reviewed by the docs platform group. See [[own-docs]].

## Model draft

Run [[cmd-test]] after you clone the tree, and expect a clean exit on Python 3.12.
Do not add a production credential for this exercise, as [[sec-none-local]] already states.
The license pointer [[lic-apache]] is the only license identifier this page may name.

Commands a reviewer can save and run later:

python3 check_orientation.py repo-contract.toml docs/orientation.md
git diff -- repo-contract.toml docs/orientation.md

The first command is the citation gate, and a prose-only review will miss a changed owner row in the diff. None of these commands were run for this article, so copy them as a lab sketch rather than as a measured result. A useful negative case is a draft that cites [[own-missing]] or prints a version outside allowed_versions, which should exit non-zero. Keep that failing page beside the script so a later edit cannot silently drop the citation rule.

Numbered workflow

A named human writes repo-contract.toml with path owners, secret rules, license identifiers, and the expected commands. Each row needs a stable id so later prose can cite the fact without quietly renaming it. The owner field names the person or team that is allowed to change those rows after review. Versions that may appear in prose go in allowed_versions, and every other version string should fail closed.
The same human pastes only the rows they intend to publish into the page section named Human-owned contract. That section also carries the owner stamp that the checker expects to find above the draft. The stamp is a review handle, not a cryptographic signature, so your real approval still lives in the pull request. If the stamp and the contract owner disagree, the checker fails and the page should not merge.
Only after that contract file is frozen should a model be asked to draft the narrative section. The prompt should include the contract text and should forbid new identifiers, new versions, and any availability or pricing language. Ask for citations in [[id]] form so the checker can see which rows the prose used. If the model cannot explain a step without a missing row, it should return a question instead of a guess.
Run the checker in the repository, then read the contract diff separately from the prose diff. A green checker means citations and a few banned words are in bounds, not that the commands still succeed on a clean machine. You should execute the listed contract commands yourself whenever the page claims a newcomer can run them. Update the contract first if a command, an owner, or a license row changed during that review.

Where a free drafting workspace fits

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode enters this workflow only as a drafting workspace with free model access and a free server option. Those two availability claims are enough to place the narrative step on a hosted workspace after the contract file exists locally. This article does not state model names, token quotas, hardware size, service regions, or a duration. Those details were not verified here as stable facts, so they stay outside the written method.

A practical split is to edit repo-contract.toml in the repository, then paste only that frozen file into the drafting session. The model returns the Model draft section, and the checker runs in CI or in a local shell before merge. A free server can hold that scratch session so the experiment does not require a paid workstation. The contract, the owner stamp, and a green checker belong in repository history, not only in the hosted session.

Do not upload production secrets, customer names, or unreleased security notes in order to obtain a smoother paragraph. The sample contract deliberately says local orientation uses no production secret, and that rule should stay intact. If the free offering's current terms are unclear, read them on the project page before you rely on the workspace. Published terms can change, and a documentation gate should not assume yesterday's limit is still today's limit.

Limitations

The regular expressions catch listed words and version-shaped numbers, and they miss paraphrases that imply the same claim. A sentence can avoid the word quota and still invent a limit, which means a human still has to read the draft. Citations prove that an identifier exists, not that the surrounding verb is fair to the row. A page can cite [[cmd-test]] and still describe the wrong expected result in the next clause.

The owner stamp is plain text, so it does not prove the identity of the editor. It will not stop someone with push access from editing the contract and the page together. Teams that need stronger custody should map the contract owner to their existing code review rules. Any interpreter older than Python 3.11 needs another TOML parser, which this sketch does not ship.

The sample was not executed here, so a defect in the script may still be waiting in your tree. Copy the files into a scratch branch and run the checker against both a good page and a bad page. A bad page should mention an unknown citation and a version that allowed_versions does not list. Keep that negative test beside the script so later edits cannot silently weaken the citation gate.

Who should skip this

Skip this gate if nobody will update the contract when path owners or license files change. A stale contract is worse than a short README, because the checker will bless prose that cites outdated rows. Skip it for security advisories, legal terms, and support commitments, where this pattern is too shallow to carry the risk. Skip it if the team would paste live credentials into a hosted model just to finish a paragraph.

Also skip it if you need measured quality scores, latency numbers, or a comparison against another assistant. This article provides a file layout and a proposed checker, not a benchmark against any other tool. Teams that already bind every generated sentence to a reviewed extract may not need a second gate with a different citation syntax. Use the approach when contributor orientation is drifting, and when a named human can keep the contract small.

Close

Freeze the repo contract, draft only cited orientation prose, and fail the page when a new fact appears outside that file. That order keeps a free drafting pass useful without letting it own path review, secrets, or license identity. If you want a hosted place to write the narrative after the contract is frozen, try a workspace only for that section. MonkeyCode's free model access and free server option are a reasonable place to start, after you confirm the current terms yourself.

Fail the Docs Build When CLI Examples Drift From a Fixture Ledger

Avery Lin — Fri, 09 Oct 2026 12:43:01 +0000

Generated command documentation fails in review when example lines are invented rather than recorded from a controlled run. A fixture ledger should freeze the argv list, the exit status, and a hash of stdout before any model writes surrounding prose. The drafting model may explain flags, suggest section order, and propose cautionary notes, but it must not own the recorded commands. Reviewers then accept or reject the page by comparing fenced examples with the ledger, rather than by trusting the model's confident wording.

Why help examples drift after a clean draft

Help text and short tutorial snippets often outlive the exact binary build that originally produced them. A renamed flag or a changed default can leave a polished paragraph pointing at a command that now exits nonzero. Hashing the captured output makes silent format drift visible without requiring the prose to quote every byte. The same ledger also tells a later editor which examples are safe to paraphrase and which lines are frozen.

Manual screenshots and pasted terminal blocks do not, by themselves, stop this kind of example drift. A paste can be edited during drafting, and a screenshot cannot be diffed when a flag moves between releases. A small JSON ledger is easier to review in pull requests because each field has a single owner. The prose file then becomes a view over that ledger, not a second source of truth.

What the model may draft, and what a human must own

Ownership of each field should be decided before the first generated paragraph is opened for editing. Human owners keep every field that a user might copy into a shell or cite in an incident note. The drafting model may write connective prose only after those owned fields already exist as committed data. If a sentence would change user behavior when it is wrong, it stays outside the drafting pass entirely.

Field	Human owner	Model role
Argv list	Yes, from the fixture run	Must not invent or reorder arguments
Exit code	Yes, from the fixture run	Must not guess success or failure
Stdout and stderr hashes	Yes, from the fixture run	Must not describe unseen bytes as facts
Flag names and defaults	Yes, from source or a machine help dump	May mention a flag only if the inventory lists it
Section order and flag rationale	Reviews the draft	May draft the wording
Canonical URL and anchor id	Yes	May suggest visible link text only
Support windows and warranty lines	Yes	Must not draft those sentences

That table is a review contract for the docs pull request, not a claim about any particular generator. A missing human owner for exit codes is enough reason to block the documentation pull request. A missing owner for introductory tone is not a blocking defect, because tone does not change the command result. The distinction keeps the drafting pass narrow, reviewable, and clearly separate from the recorded command facts.

A numbered workflow you can rerun

1. Dump a flag inventory from the binary

Start from the command itself, or from the parser definition that the release binary actually ships. Write one JSON object per flag, including the canonical spelling, the default, and whether the flag is stable. Do not ask a model to reconstruct that inventory from memory or from an old README. Commit the dump beside the docs so a later release can diff added, removed, and renamed flags.

2. Specify fixtures before any prose exists

Each fixture names an id, an argv list, optional stdin, and the doc files allowed to cite it. Keep the first fixture set small, covering version output, a dry-run lint, and one deliberate failure. Reject any fixture that needs production credentials, live tenant identifiers, or unbounded network calls to complete. The spec is human-owned input, and the model should not be allowed to append commands to it.

3. Record the ledger on a clean runner

Run the recorder in a disposable environment so local shell aliases and developer config files cannot leak into the examples. A disposable server or a locked CI job is enough for this recording pass when the binary and fixtures fit that environment. Confirm those limits in the provider's own console before you depend on them for a release. Store exit codes and hashes, not a private stdout body, unless the example is already public.

4. Draft prose only from the ledger and the inventory

Give the drafting model the ledger, the flag inventory, and a short style note as its only inputs. Ask it to explain when to use each recorded command, and to leave argv lines untouched. Require every fenced example to carry the fixture id, the argv list, the exit code, and the stdout hash. If the model adds a command that is not in the ledger, discard that block instead of editing it into truth.

5. Fail the docs check when cited fields drift

The checker loads the ledger, scans documentation for fixture fences, and compares argv, exit code, and stdout hash. A field mismatch fails the pull request even when the surrounding paragraph reads smoothly and completely. Unknown fixture ids fail as well, because a new example must be recorded before it is explained. Prose-only edits pass this mechanical gate and can continue through the ordinary editorial review that follows.

6. Review the human-owned sentences by hand

After the checker passes, a human still reads rationale, warnings, and any sentence that states a guarantee. The checker cannot tell whether a caution note overclaims safety or omits a required privilege for the command. That reading stays on the docs owner, not on the model and not on the hash comparison. Merge the page only when both the ledger gate and that human reading are fully complete.

Reference checker and ledger shape

The following Python is an unexecuted reference implementation, not a measured result from a production repository. It shows the recording step and the comparison step in one file so a team can adapt the paths. Command timeouts, argv allowlists, and secret scanning belong in the wrapper that calls this reference script. Do not point it at commands whose stdout may contain tokens, customer data, or unredacted paths.

#!/usr/bin/env python3
"""Unexecuted reference: record CLI fixtures and check doc fences."""
import hashlib
import json
import re
import subprocess
import sys
from pathlib import Path

FENCE = re.compile(r"```

fixture\n(.*?)

```", re.S)

def record(spec: dict, timeout: int = 30) -> dict:
    proc = subprocess.run(
        spec["argv"],
        input=spec.get("stdin"),
        text=True,
        capture_output=True,
        timeout=timeout,
        check=False,
    )
    stdout = proc.stdout.encode()
    stderr = proc.stderr.encode()
    return {
        "id": spec["id"],
        "argv": spec["argv"],
        "exit_code": proc.returncode,
        "stdout_sha256": hashlib.sha256(stdout).hexdigest(),
        "stderr_sha256": hashlib.sha256(stderr).hexdigest(),
        "stdout_bytes": len(stdout),
    }

def check(ledger_path: Path, docs: list[Path]) -> list[str]:
    ledger = json.loads(ledger_path.read_text())
    by_id = {row["id"]: row for row in ledger["fixtures"]}
    errors = []
    if not ledger.get("binary_version"):
        errors.append("ledger: binary_version is missing")
    for path in docs:
        for block in FENCE.findall(path.read_text()):
            claimed = json.loads(block)
            recorded = by_id.get(claimed["id"])
            if recorded is None:
                errors.append(f"{path}: unknown fixture {claimed['id']}")
                continue
            for key in ("argv", "exit_code", "stdout_sha256"):
                if claimed.get(key) != recorded.get(key):
                    errors.append(f"{path}: {claimed['id']} {key} drifted")
    return errors

def main() -> int:
    if len(sys.argv) < 3:
        print("usage: fixture_gate.py record spec.json ledger.json", file=sys.stderr)
        print("       fixture_gate.py check ledger.json docs.md", file=sys.stderr)
        return 2
    if sys.argv[1] == "record":
        spec = json.loads(Path(sys.argv[2]).read_text())
        rows = [record(item) for item in spec["fixtures"]]
        payload = {
            "binary_version": spec.get("binary_version"),
            "fixtures": rows,
        }
        Path(sys.argv[3]).write_text(json.dumps(payload, indent=2) + "\n")
        return 0
    errors = check(Path(sys.argv[2]), [Path(p) for p in sys.argv[3:]])
    print("\n".join(errors))
    return 1 if errors else 0

if __name__ == "__main__":
    raise SystemExit(main())

A spec file can stay small while the team proves that the gate fails closed on a bad example. The ids below are placeholders for the workflow, not observed runs, and the exit codes are not measurements. Replace the argv entries with the binary you actually ship before anyone records a ledger from this sample. Record that ledger only after the replacement, then copy recorded fields into documentation fences without retyping them.

{
  "binary_version": "REPLACE_FROM_BUILD",
  "fixtures": [
    {"id": "version", "argv": ["tool", "version"], "stdin": null},
    {"id": "lint-dry-run", "argv": ["tool", "lint", "--dry-run", "sample/"], "stdin": null},
    {"id": "lint-missing-path", "argv": ["tool", "lint"], "stdin": null}
  ]
}

python3 fixture_gate.py record fixtures/spec.json fixtures/ledger.json
python3 fixture_gate.py check fixtures/ledger.json docs/cli/lint.md

A documentation fence then cites the recorded row instead of a loose terminal paste from a chat transcript. The hash is a merge gate for editors, not a value that readers are expected to type into a shell. Editors can still show a short redacted excerpt beside the fence when that excerpt comes from the same recorded run. If the excerpt and the hash disagree, the excerpt is discarded and the ledger row remains the cited result.

{
  "id": "lint-missing-path",
  "argv": ["tool", "lint"],
  "exit_code": null,
  "stdout_sha256": "REPLACE_FROM_LEDGER"
}

Where a free model and a free server fit

MonkeyCode's free model access and free server option can sit inside this workflow without becoming the source of truth. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The free server is a reasonable place to record fixtures when a clean process environment is required and current plan limits are confirmed. The free model is a reasonable drafter for rationale paragraphs once the ledger and the flag inventory are the only behavioral inputs.

Those two availability claims are not a capacity plan, a hardware specification, or a promise that a named model remains on the free tier. This article does not report quotas, durations, benchmark scores, or supported binary sizes, because those facts were not measured here. Treat the provider console and the current product terms as the primary sources before a release depends on either option. If the server cannot run the binary, record the ledger in the existing CI runner and keep the same checker in the repository.

The drafting prompt should stay narrow so the model cannot widen the set of recorded commands on its own. Pass the ledger JSON, the flag inventory, and an instruction to refuse any command that is not already recorded. Ask for explanations, failure meaning, and related reading, while forbidding new flags, new exit codes, and new URLs. Save the model output as a proposal file, then run the checker before a human edits tone or order.

Limitations of the ledger gate

Hashes do not prove that an example is wise, only that the cited run still matches the recorded ledger. Nondeterministic output, timestamps, and unordered maps will fail the gate unless a normalizer strips them before hashing. A command that passes today can still be a poor teaching example if it requires privileges the page never states. The human review in the last workflow step exists because those judgments are not hash comparisons at all.

The checker also trusts whatever environment recorded the ledger, which may not match the release under review. A fixture recorded on a developer laptop can embed aliases, extra path entries, or a locally patched binary. That risk is why the recording step prefers a clean server or a locked CI image with a noted binary version. If the version field is absent, reviewers should treat the hashes as incomplete evidence rather than as a release proof.

Secret handling needs a separate control from the documentation checker that the workflow above already described. Hashing stdout does not make it safe to execute a command that prints credentials, because the process still ran. Keep fixture argv free of tokens, and block any fixture that reads production configuration or private environment files. If a team cannot meet that bar, this workflow is the wrong place to generate public help pages from live runs.

Who should not use this approach

Skip the ledger gate when public output is inherently unstable and cannot be normalized without hiding the lesson. Interactive installers, full-screen pagers, and commands that wait on a live service fit this method poorly. Also skip it when legal or support commitments dominate the page, because those lines need specialist owners. A small internal tool with two stable subcommands is a better first candidate than a platform CLI with remote side effects.

Teams that cannot store a binary version beside the ledger should wait before adopting the gate. Without that version, a green check only says the docs match some earlier machine, not the release under review. The method is also a poor fit for marketing pages that intentionally compress commands into slogans or screenshots. Use the ledger for reference pages where a copied command must exit as the documentation claims it will.

Close the review with one failing example

Start with one subcommand, three fixtures, and a pull request that fails on a deliberately wrong exit code. That single failure shows reviewers what the gate catches before anyone drafts a full help chapter around it. After that failure is understood, allow the model to draft rationale from the passing ledger and review human-owned sentences by hand. If a free recording environment is available, use it for the clean run, and keep the checker in the repository for the next release.

A Claim-Class Router That Keeps Generated Docs From Owning Support Facts

Avery Lin — Fri, 09 Oct 2026 08:43:26 +0000

Generated documentation stays reviewable only when normative claims are rendered from a human ledger and the model is limited to narration. A page that mixes support promises, version pins, and explanatory prose hides the sentences a reviewer must actually own. This workflow compiles a claim-class manifest first, rejects unmarked sections, and lets a model fill only the classes marked draftable. The resulting pull request can trace each promise to a named owner before any generated paragraph is merged.

Why mixed drafts fail a merge gate

A documentation generator can rewrite a README, a configuration guide, or an internal library page in a single pass. That speed is useful for wording, and it is unsafe for facts that change support, security, or compatibility. Reviewers then search fluent paragraphs for implied guarantees, which is a weak control compared with a failing check. The practical failure is an unowned sentence that later readers will treat as a commitment the repository never accepted.

Sampling a generated page does not scale once teaching text and operational claims share the same file. A phrase such as "works on current long-term releases" can outlive the matrix the team actually tests. Classifying sections before generation makes that phrase either disallowed in narration or explicit in a ledger row. The extra manifest is small relative to the page, and it gives the reviewer a stable place to inspect promises.

Five classes, one writer each

The manifest defines five claim classes, and each class has exactly one allowed writer for the published page. Narration covers motivation, reading order, and conceptual explanation, so a model may draft it after the ledger is locked. Unverified examples cover illustrative commands, so a model may draft them only when an explicit unverified label stays in the section. Verified examples cover commands with an expected result, so a human owns the fixture and a model may only cite its identifier.

Normative rows cover versions, support windows, authentication requirements, breaking-change rules, and license grants, so only a human may author those fields. Pointer rows cover links to source files, so a deterministic renderer emits them from the manifest rather than from free prose. The RFC 2119 rules and the RFC 8174 update describe how specifications mark normative keywords such as MUST and SHOULD. Those documents remain the right reference when a page is itself a specification, and the RFC Editor publishes both texts.

This workflow does not replace that keyword convention inside a standards-track document or any other protocol specification. It applies a narrower split to everyday project guides, where most pages never declare which sentences a reader may rely on. When a section could sit in either narration or the normative class, the safer default is the normative class. That default adds a few ledger rows and avoids letting a fluent draft widen a support pin during rewriting.

A later edit can move a section toward narration only after the owner confirms that no reader would treat it as a promise. The checker enforces the recorded class, not the author's intention at the moment the draft was requested. Moving a section without updating the manifest is a failed build, which is preferable to a silent class change. Reviewers should treat that failure as a routing error, not as a comment on writing quality or tone.

Class	Allowed writer	May state support or versions	Required fields
narration	model, after lock	no	id, sources
example_unverified	model, with label	no	id, label text
example_verified	human fixture	only inside the fixture	fixture_id, expected
normative	human ledger	yes, as ledger fields	owner, reviewed_on, source
pointer	renderer	no	path, git_ref

Lock the inventory before prompting

Store the ledger at docs/claim-inventory.yaml in the same pull request as the page that will be generated. Generation must not start while locked is false, and a normative row without an owner fails closed. Dates in the sample are review metadata that a human types, not inferred uptime, quotas, or product availability. Replace the owner, the paths, and the runtime pin with values that the repository actually maintains.

page: docs/config-guide.md
locked: true
sections:
  - id: why-this-exists
    heading: "Why this page exists"
    claim_class: narration
    sources:
      - config/schema.json
  - id: support-matrix
    heading: "Support matrix"
    claim_class: normative
    owner: docs-maintainers
    reviewed_on: 2026-10-09
    source: docs/support-matrix.yaml
    fields:
      runtimes:
        - {name: python, range: "3.11"}
      auth: "token required for write routes"
  - id: sample-call
    heading: "Sample call"
    claim_class: example_unverified
    label: "illustrative only; not a support promise"
  - id: schema-link
    heading: "Schema source"
    claim_class: pointer
    path: config/schema.json
    git_ref: HEAD

The runtime pin is deliberately narrow so that a later prose pass cannot silently widen the tested range. If the tested range changes, a human edits the source file, updates reviewed_on, and regenerates the normative block. The model is not an editor of that block, even when the surrounding introduction needs a complete rewrite. This split is the reason promises are rendered before any generation prompt is sent to a model.

The sample pin is fixture data for the checker, not a statement of which runtime is current on any particular date. A pointer row that still says HEAD is not reproducible after later commits land on the branch. Replace that ref with the commit the reviewer actually read before the page is merged. Otherwise the rendered link can drift away from the schema the normative block described.

Steps from ledger to pull request

Compile the inventory before any prompt is sent, and fail the build when a normative row lacks an owner.
Render normative and pointer sections with a deterministic template before a model is allowed to run at all.
Build a prompt that lists only narration and unverified-example identifiers, with rendered promises attached as read-only context.
Require the model to return Markdown for those identifiers alone, and discard any response that adds a new heading.
Run the phrase gate on draftable sections, then open the pull request with the manifest, fixtures, and rendered page together.

Each step is a separate command so a reviewer can rerun the gate without trusting the draft narrative. The model never receives write permission on the ledger, the support matrix, or the verified example fixtures. If a response introduces a new heading, the checker treats that heading as unmarked and fails the build immediately. Hand-merging stray sentences back into the page defeats the class split, so the correct action is to drop the response and rerun.

A local checker you can rerun

The following script is a proposal for local or continuous-integration use, and it does not call a model or a network service. It checks class coverage, required owner fields, and a short denylist inside sections the model is allowed to draft. Extend the denylist with product-specific promise words, because a fixed expression cannot catch every implication a paragraph might carry. Treat a green run as a necessary merge condition, not as proof that the narration is semantically safe for readers.

#!/usr/bin/env python3
"""Proposal: block normative wording inside draftable doc sections."""
import re
import sys
import pathlib
import yaml  # PyYAML, reviewed dependency

DENY = re.compile(
    r"\b(supported|guaranteed|production-ready|warranty|"
    r"generally available|officially)\b",
    re.IGNORECASE,
)
DRAFTABLE = {"narration", "example_unverified"}

def section_body(page: str, heading: str) -> str:
    marker = f"## {heading}"
    chunk = page.split(marker, 1)[1]
    return chunk.split("\n## ", 1)[0]

def main(manifest_path: str, page_path: str) -> int:
    data = yaml.safe_load(pathlib.Path(manifest_path).read_text())
    if not data.get("locked"):
        print("inventory is not locked")
        return 1
    page = pathlib.Path(page_path).read_text()
    for spec in data["sections"]:
        if f"## {spec['heading']}" not in page:
            print("missing heading", spec["heading"])
            return 1
        kind = spec["claim_class"]
        if kind == "normative" and not (spec.get("owner") and spec.get("reviewed_on")):
            print("unowned normative section", spec["id"])
            return 1
        if kind not in DRAFTABLE:
            continue
        body = section_body(page, spec["heading"])
        hit = DENY.search(body)
        if hit:
            print(f"denied term {hit.group(0)!r} in {spec['id']}")
            return 1
        label = spec.get("label", "")
        if kind == "example_unverified" and label.lower() not in body.lower():
            print("missing unverified label", spec["id"])
            return 1
    print("claim-class gate passed")
    return 0

if __name__ == "__main__":
    sys.exit(main(sys.argv[1], sys.argv[2]))

Install the YAML parser, then point the gate at the manifest and the rendered page using the commands below. A passing run prints a single status line and exits with code zero, which a job can require before merge. A narration block that contains "supported" or "guaranteed" fails before a human spends review time on tone alone. Keep RFC 2119 verbs out of narration by review policy, because this sample expression intentionally does not fail the build on "must".

python3 -m pip install pyyaml
python3 tools/claim_class_gate.py docs/claim-inventory.yaml docs/config-guide.md

A deterministic renderer can stay smaller than the gate, because it only prints ledger fields and refuses to paraphrase them. The sketch below writes the support section from the manifest so the model cannot restate the runtime pin in its own words. Wire that function into step two, and commit its output beside the inventory so reviewers can diff the promises directly. If the function and the page disagree, trust the inventory and regenerate, rather than editing the rendered sentences by hand.

def render_normative(spec: dict) -> str:
    fields = spec["fields"]
    lines = [
        f"## {spec['heading']}",
        "",
        "Values below are copied from the claim inventory.",
    ]
    for item in fields["runtimes"]:
        lines.append(f"- Runtime pin: {item['name']} {item['range']}")
    lines.append(f"- Auth rule: {fields['auth']}")
    lines.append(
        f"- Owner: {spec['owner']}; reviewed_on: {spec['reviewed_on']}"
    )
    return "\n".join(lines) + "\n"

Using free model access without widening claims

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode's free model access and free server option fit this workflow because the hard part is a locked prompt plus a repeatable check. Send a free model only the draftable section identifiers, and include the rendered normative blocks as context that the model must not rewrite. Run the checker and the renderer on the free server whenever the page changes, so one laptop is not the only place the gate can run.

Keep the generation instruction narrow enough that a reviewer can audit it after a failed run. Ask for Markdown under the listed headings, forbid new headings, and forbid support, version, license, and availability claims in those sections. If the response adds a heading or edits a normative block, discard it and rerun rather than splicing sentences by hand. Store the checker log with the pull request so the reviewer can see each section class without rereading every paragraph.

Free access does not relax the ownership rule, and a green checker does not certify that the prose is safe. A missing owner still fails the build, whether the command runs locally or on the free server option. This description names neither a model nor a quota nor a server size, because those details were not verified inputs. If the inventory is already locked, a free model can draft only the narration sections that the manifest names.

Limits, noisy terms, and teams that should not start here

The phrase gate is a heuristic, and a careful paragraph can imply a promise without using any denied word. A line such as "teams already depend on this path for live traffic" may pass the sample expression and still over-claim. Human review of narration remains necessary, especially when readers include customers rather than internal contributors only. Heading matching is also brittle, so a renderer that changes punctuation will report mismatches until both sides use the same string.

Skip this approach for security advisories, compliance attestations, and any license text that still needs legal counsel. Skip it when nobody will accept the owner field, because the file would then imitate an audit trail without a responsible person. Skip it as the only control on executable examples, since verified fixtures still need a test that runs the command and compares the expected result. The sample denylist is English-only, so a multilingual guide needs a term list maintained by the same owners who edit the ledger.

A repository that already ships a formal specification should keep its existing RFC 2119 review on that specification. This router is intended for the surrounding guides that models are now asked to rewrite between releases. Start with one page, record which failures were true over-claims versus noisy teaching words, and only then extend the expression. That measurement stays local to the repository, and it should not be replaced with a generic score from an unrelated benchmark.

Split Config Migration Pages Into an Owned Schema Pin and a Drafted Essay

Avery Lin — Fri, 09 Oct 2026 01:48:38 +0000

A migration page is trustworthy only when commands, keys, and defaults come from a reviewed schema diff. Drafted prose may explain those pinned facts, but it must not add a flag, a path, or a version. The workflow below stores the diff as a JSON pin, marks narrative sections, and fails when a command is absent from the pin. Teams without a versioned schema, and teams writing security advisories, should not use this split at all.

Where generated upgrade notes usually break

Generated upgrade notes often mix a real diff with a plausible command that never existed in the repository. Reviewers then approve the tone and miss a wrong default, a renamed key, or a rollback step that cannot run. Separating the pin from the essay turns that class of error into a mechanical mismatch instead of a careful reading exercise. The pin is the only place where versions, keys, types, defaults, and shell commands are allowed to appear as facts.

The same split also limits how much context a drafting model needs before it writes the essay. A short pin is easier to review than a full schema history pasted into a chat window. It gives the checker an allowlist, and it gives the human a single file to approve when the code change lands. When the pin is wrong, the page is wrong, which is a better failure mode than a fluent page that cannot be traced.

Facts a human must own

A human owner records the source schema path, the target schema path, and the exact key set that the note is allowed to cite. That owner also records each command as a literal string, including the working directory assumption and the expected exit condition. Ownership includes the rollback decision, because a draft can describe a reverse migration that the schema change does not support. The owner name and the review date stay in the pin, so a later edit cannot hide who accepted the facts.

Human ownership of the pin stops at facts that a schema diff can actually prove on its own. Impact adjectives, audience guesses, and broad most-teams claims are not made true by a green checker. Those sentences can remain in the drafted essay, but a reviewer still has to reject unsupported scope. The checker described in the procedure only enforces keys, commands, version strings, and the rollback flag.

Prose a model may draft

The model may draft why a key moved, which workloads notice the change, and how to read the command the pin already lists. It may also draft a short sequencing paragraph, provided every command string in that paragraph already exists in the pin. It may not draft new flags, sample values that contradict the recorded default, or dates that are absent from the pin. If a sentence needs a fact that is not pinned, the draft stops and the human extends the pin before any prose continues.

Keep the drafted region small on purpose so the essay cannot quietly replace the generated fact table. A useful essay is three or four paragraphs that point at the generated fact table, not a second copy of the table in sentences. Repeating the default in prose is how drift starts when someone updates the pin and forgets the paragraph. Prefer a cross-reference such as the default recorded for pool.timeout_ms over a restated number in prose.

Use a free draft pass without making it authoritative

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode's free model access can draft the marked narrative sections when the pin file is the only context you paste. The free server option can run the same local checker and a static preview you start yourself, so review needs no paid host. Neither option is the source of truth, and the pin plus the checker stay authoritative if that hosted environment is unavailable.

Confirm current access terms in the product documentation before you depend on either option, because this article does not claim quotas, hardware, or permanence. Do not paste secrets, customer data, or unreleased credentials into a hosted draft even when the schema itself looks harmless. If the free path is down, write the essay locally and still run the same checker on the branch. The procedure does not require a hosted model in order to reject an unowned command during review.

Procedure

1. Capture the two schema versions that the note covers

Store the old and new config schemas next to the code change that introduced them in git. Prefer the files already reviewed in the pull request, rather than a schema reconstructed from memory. Record those paths in the pin so a later reader can regenerate the diff without guessing. If the change is not representable as a schema diff, stop and write the page under a different review process.

2. Write the pin and review it like production code

Create the pin file with versions, an owner, keys, and the literal commands reviewers expect operators to run. Review that file in the same pull request as the schema change, before any essay exists. Treat a pin edit as a behavior change, because the published commands will be copied from it. A sample pin is included below so you can run the checker without a private repository.

3. Render the fact table from the pin

Generate the fact section with a script so the model never types keys or shell commands. Commit the generator output, or regenerate it in continuous integration and fail on a dirty diff. The essay then links to that section instead of restating the same keys in surrounding prose. This generated section remains the practical boundary between human-owned facts and every later drafted explanation on the page.

4. Draft only inside the narrative markers

Paste the pin, not the whole repository, into the drafting session as the only factual source. Ask only for prose that stays strictly between the narrative draft markers shown in the sample page. Reject any response that adds a fenced shell block you did not already supply in the pin. If you start a static preview on the free server, compare that page with the pin and look for unknown keys.

python3 -m http.server 8080 --directory docs

5. Run the local allowlist checker

Run the Python checker from the repository root against the pin file and the Markdown page. The checker extracts fenced commands and dotted backtick tokens from the narrative region only, not the fact table. It fails when a command is not an exact argv string, or when a dotted token is not listed in keys. Fix the pin or delete the sentence, and do not weaken the checker to accept a fluent mismatch.

6. Read the claims the checker cannot see

After a green run, a human still reads impact, ordering advice, and any sentence that says who is affected. The checker does not know whether background workers are the right audience for that timeout key. It also does not execute the commands, so a pinned command can still be operationally wrong. Schedule a dry run of each pinned command in a disposable environment before you call the page done.

Sample pin

{
  "from_version": "1.4",
  "to_version": "1.5",
  "owner": "config-reviewer",
  "reviewed_on": "2026-10-09",
  "source_schema": "schema/config-1.4.json",
  "target_schema": "schema/config-1.5.json",
  "keys": {
    "pool.timeout_ms": {"change": "default", "from": 1000, "to": 2500},
    "pool.max_idle": {"change": "removed"}
  },
  "commands": [
    {
      "argv": "python scripts/migrate_config.py --from 1.4 --to 1.5",
      "expects": "exit 0 and a rewritten config file"
    }
  ],
  "rollback_supported": false
}

The numbers in that pin are sample data for the checker, not measurements from a running service. Replace them with the defaults your schema review actually accepted. Keep reviewed_on equal to the review date you can defend, and do not copy this date forward. A pin that cannot point at real schema paths should not be used to publish a page.

Sample page shape

## Facts

| Key | Owned change |
| --- | --- |
| `pool.timeout_ms` | default from 1000 to 2500 |
| `pool.max_idle` | removed |

bash
python scripts/migrate_config.py --from 1.4 --to 1.5


Expected: exit 0 and a rewritten config file

Rollback: not supported by this pin.

<!-- narrative:draft -->
Workers that set `pool.timeout_ms` explicitly keep their value, and only omitted keys receive the new default recorded in the fact table. There is no rollback command in the pin, so this essay does not describe a reverse migration. Run the listed command once in a staging copy, then compare the rewritten file with the 1.5 schema.
<!-- /narrative:draft -->

python

The fact table above is illustrative and should be emitted by your generator, not typed by the model. The narrative mentions the timeout key, which is allowlisted, and it avoids adding a second shell fence. A sentence that added an unknown dotted token would fail, because that token is absent from keys. That failure is the behavior you want when a draft tries to document a setting the schema diff never contained.

Local checker

#!/usr/bin/env python3
"""Fail a migration essay when narrative invents a key or command outside the pin.

This file is a local proposal, and it does not call a model or record hosted metrics.
"""

import json
import re
import sys
from pathlib import Path

FENCE_MARK = "`" * 3
FENCE = re.compile(
    FENCE_MARK + r"(?:bash|sh|shell)?\n(.*?)" + FENCE_MARK,
    re.S,
)
NARRATIVE = re.compile(
    r"<!-- narrative:draft -->(.*?)<!-- /narrative:draft -->",
    re.S,
)
TOKEN = re.compile(r"`([^`\n]+)`")


def load_pin(path: Path) -> dict:
    pin = json.loads(path.read_text(encoding="utf-8"))
    required = ["from_version", "to_version", "owner", "keys", "commands"]
    missing = [name for name in required if name not in pin]
    if missing:
        raise SystemExit("pin missing fields: " + ", ".join(missing))
    return pin


def render_facts(pin: dict) -> str:
    lines = ["## Facts", "", "| Key | Owned change |", "| --- | --- |"]
    keys = pin["keys"]
    items = keys.items() if isinstance(keys, dict) else [(key, {}) for key in keys]
    for key, meta in items:
        change = meta.get("change", "cited") if isinstance(meta, dict) else "cited"
        detail = change
        if isinstance(meta, dict) and "from" in meta and "to" in meta:
            detail = change + " from " + str(meta["from"]) + " to " + str(meta["to"])
        lines.append("| `" + key + "` | " + detail + " |")
    lines.append("")
    for item in pin["commands"]:
        lines.append(FENCE_MARK + "bash")
        lines.append(item["argv"])
        lines.append(FENCE_MARK)
        lines.append("")
        lines.append("Expected: " + item["expects"])
    if pin.get("rollback_supported") is False:
        lines.append("")
        lines.append("Rollback: not supported by this pin.")
    return "\n".join(lines)


def check(pin: dict, markdown: str) -> list[str]:
    errors = []
    blocks = NARRATIVE.findall(markdown)
    if not blocks:
        return ["no narrative:draft region found"]
    body = "\n".join(blocks)
    allowed_argv = {item["argv"] for item in pin["commands"]}
    allowed_keys = set(pin["keys"])
    for fence in FENCE.findall(body):
        command = fence.strip()
        if command not in allowed_argv:
            errors.append("unowned command: " + command)
    for token in TOKEN.findall(body):
        if token in allowed_keys or token in allowed_argv:
            continue
        if "." in token and re.fullmatch(r"[A-Za-z0-9_.-]+", token):
            errors.append("unowned key token: " + token)
    for version in (pin["from_version"], pin["to_version"]):
        if version not in markdown:
            errors.append("missing version string: " + version)
    if pin.get("rollback_supported") is False and "rollback" in body.lower():
        allowed_phrase = (
            "no rollback" in body.lower()
            or "not describe a reverse" in body.lower()
        )
        if not allowed_phrase:
            errors.append("rollback mentioned but pin sets rollback_supported false")
    return errors


def main() -> int:
    args = sys.argv[1:]
    render = False
    if args and args[0] == "--render":
        render = True
        args = args[1:]
    if render:
        if len(args) != 1:
            raise SystemExit("usage: check_migration_pin.py --render PIN.json")
        print(render_facts(load_pin(Path(args[0]))))
        return 0
    if len(args) != 2:
        raise SystemExit("usage: check_migration_pin.py PIN.json PAGE.md")
    pin = load_pin(Path(args[0]))
    page = Path(args[1]).read_text(encoding="utf-8")
    errors = check(pin, page)
    if errors:
        print("\n".join(errors))
        return 1
    print("pin check passed")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

python3 scripts/check_migration_pin.py --render \
  docs/migrations/pins/1.4-to-1.5.json \
  > docs/migrations/partials/1.4-to-1.5.facts.md

python3 scripts/check_migration_pin.py \
  docs/migrations/pins/1.4-to-1.5.json \
  docs/migrations/1.4-to-1.5.md

A render pass prints the fact section from the pin and does not read the essay at all. A check pass prints pin check passed and exits with status 0 when the narrative stays inside the allowlist. Any unowned command prints the offending string and exits with status 1 so the branch fails. The static server command is only a local preview you start, and it is not a benchmark of the free server option.

Decision table

Situation	Model may draft	Human must own	Checker result
Key default changed in schema	Why callers notice	Old default, new default, key name	Fail if the essay cites an unknown dotted token
Command already stored in the pin	When to run it	Exact argv and expected exit	Fail if a narrative fence differs from argv
Rollback marked unsupported	A warning that no reverse step exists	`rollback_supported: false`	Fail if the essay invents a reverse command
Behavior change outside the schema	Nothing, until a different review path is chosen	Decision not to force a pin	Do not bypass the checker to publish anyway

Read the table as a routing rule, not as a suggestion that every row deserves a generated page. Rows without a schema diff have no pin, so they never reach the drafting step described above. Rows with a pin still need the dry run, because an exact argv string can point at a script that fails on real files. Use the checker column to decide what automation may block, and leave audience claims to the human review in step 6.

Limitations

The allowlist is intentionally narrow, and several real defects still pass through it without a warning. A pinned command can be outdated if the owner copies the wrong script path and nobody executes it. A dotted token rule misses bare words, so a model can still invent a flag that is not wrapped in backticks. Version presence and the rollback phrase check are heuristics, not proof that tags or reverse migrations were reviewed.

Hosted drafting adds a second class of limitation that the local checker is not able to measure. Free model access and the free server option can speed review, but either one can be unavailable or unfit for private schemas. This article states those two availability options as operator-supplied claims, not as measured capacity or uptime. Keep a local editor path so a documentation change is not blocked when the hosted preview is down.

Who should skip this workflow

Skip this split when the change has no schema, because the pin would be a story rather than a diff. Skip it for security advisories, legal terms, pricing, and uptime promises, where every sentence needs specialist review rather than an allowlist. Skip it if your reviewers will not dry-run commands, since a green checker can still ship a broken migration. Skip it in environments that forbid sending schema excerpts to a hosted model, and write the essay offline instead.

The useful outcome is a page whose commands trace to a reviewed file and whose essay can be regenerated cleanly. The essay can change voice without forcing a second review of every argv string already stored in the pin. If the next upgrade already has two schema files in git, draft the marked essay from the pin alone. Run the checker on the free server when that option is currently available, and merge only after it exits cleanly.

Gate Changelog Drafts With a Signed Release Impact Packet

Avery Lin — Thu, 08 Oct 2026 22:38:39 +0000

Generated changelog prose stays reviewable only after a human release owner locks version, date, breaking changes, and security notes. A model may then summarize commit subjects that already match an allowlist, and it must not invent impact language. This article specifies that ownership split, a release packet schema, and a proposed Python gate for the draft. Treat the listed code as an unexecuted reference implementation, not as a measured result from a production release.

Why summaries and contracts must stay apart

A changelog mixes two different evidence classes, and a single generation prompt collapses that difference into one voice. Commit subjects are historical text that a parser can group, while version numbers and support windows are decisions a person must accept. When both classes sit in one instruction, the draft can sound complete even though no owner confirmed impact. The practical rule is therefore narrow: draft narration from locked inputs, and refuse the draft when those inputs are absent.

Keep a Changelog 1.1.0 separates Added, Changed, Deprecated, Removed, Fixed, and Security into heading names only. Those headings are a vocabulary for organizers, not permission for a model to invent missing entries. Conventional Commits 1.0.0 defines types such as feat, fix, and docs, plus a breaking-change footer a script can read. Semantic Versioning 2.0.0 defines how version numbers move, but it does not decide whether users can absorb that move.

Primary pages for those three specifications should be rechecked before anyone encodes them into a release bot. This article cites Keep a Changelog 1.1.0, Conventional Commits 1.0.0, and Semantic Versioning 2.0.0 as stable references. It does not claim that a newer revision was reviewed on 2026-10-09, so the links below remain the verification path. Use the linked pages rather than a copied summary if your tooling already pins a different specification version.

Keep a Changelog 1.1.0: https://keepachangelog.com/en/1.1.0/
Conventional Commits 1.0.0: https://www.conventionalcommits.org/en/v1.0.0/
Semantic Versioning 2.0.0: https://semver.org/spec/v2.0.0.html

Field rights before any prose exists

The table below assigns each packet field to a writer and states the merge rule that precedes prose. Human fields record decisions, while grouped summaries are narration over commits the owner already accepted into the packet. An empty breaking-change list is valid only when the owner recorded that absence on purpose in the packet. A missing list is a different fact, because a model can fill silence with plausible incidents that nobody reviewed.

Packet field	Evidence source	Who may write it	Merge rule
`version`	Human release decision	Human owner	Required SemVer core triple
`release_date`	Owner calendar confirmation	Human owner	Required `YYYY-MM-DD`
`breaking_changes`	Owner list, not commit adjectives	Human owner	Present list, empty allowed
`security_notes`	Advisory process outside the model	Human owner	Empty or already approved
`support_window`	Team support policy allowlist	Human owner	Required, no invented labels
`commits`	Reviewed subjects and short SHAs	Human owner selects rows	Types limited before drafting
`grouped_summaries`	Brief built only from `commits`	Model after the gate	Each bullet must cite a packet SHA
`sign_off`	Named role and timestamp	Human owner	Required before a brief is printed

Read the table as a control surface, not as guidance for sentence style or marketing tone. Support window values should come from a team allowlist, and the sample uses three labels only as placeholders. Replace those labels with the words your support policy actually uses before the first real packet is signed. Do not let a model invent a fourth support label in order to make a draft sound more precise.

Packet file the gate will read

Store the human packet in release_packet.json beside the changelog, and store model output in a separate file. The JSON example is illustrative, and it was not copied from a shipping product or a customer release. Short SHAs are placeholders, so replace them with commits you can open before anyone trusts a summary. Subject lines in the sample are synthetic, and they should not be cited as evidence of a real defect or feature.

{
  "version": "1.4.0",
  "release_date": "2026-10-09",
  "support_window": "current_minor_only",
  "breaking_changes": [],
  "security_notes": [],
  "commits": [
    {"sha": "a1b2c3d", "type": "feat", "subject": "add export filter for closed accounts"},
    {"sha": "e4f5a6b", "type": "fix", "subject": "retain timezone when saving weekly reports"}
  ],
  "sign_off": {"name": "release-owner", "role": "release", "signed_at": "2026-10-09T15:00:00Z"}
}

Numbered workflow

Collect candidate subjects with a normal git log command, then copy only reviewed lines into the commits array. A subject that you would not say to a user does not become safer because a model rewrites the wording. The owner deletes or edits bad subjects before sign-off, because the gate checks structure rather than factual accuracy. Keep the command output in the review notes so a later reader can see which range was considered.

git log --pretty=format:'%h%x09%s' v1.3.0..HEAD

Fill version, release date, support window, breaking changes, and security notes without a model in the loop. Use an empty array when the honest answer is none, and record that choice where reviewers can see it. Do not ask a model whether a refactor is breaking, because a commit type is not a customer contract. If security notes are non-empty, the named security owner must already have approved each identifier outside this workflow.
Run the proposed checker so it either prints a constrained draft brief or exits with status 2. The checker refuses the brief when sign-off, version shape, date shape, or the support allowlist fails. It also refuses commit types outside feat, fix, perf, and docs, which keeps chores out of user-facing summaries. Refactor and chore commits can still matter internally, but they should not be narrated as product changes by default.
Send only the printed brief to the model, then save the returned Markdown as summary_draft.md for scanning. The brief allows grouping under Added, Changed, and Fixed, and it requires each bullet to end with a packet SHA. It forbids version promises, calendar dates, advisory identifiers, and any sentence that orders users to migrate now. If the model adds a heading that the brief did not allow, discard the file instead of editing the extra claim into safety.
Scan the draft with the same checker in scan mode before a human spends time on tone. Any forbidden token fails the run even when the surrounding paragraph is clear and grammatically clean. A release owner still reads every bullet against the cited commit, because a matching SHA does not prove the subject. Open the commit in the repository when the subject and the diff disagree, and then rewrite the bullet by hand.
Merge only after the owner accepts or rewrites the draft and the signed packet remains byte-for-byte unchanged. If any impact field changes, discard the draft and generate a new brief from the updated packet. That order stops a polished paragraph from outliving the decision it appears to describe to readers. Keep the brief, the draft, and the packet in the same pull request so reviewers can audit the boundary.

Proposed checker and unexecuted checks

The script below is a proposal for local review, and it has not been executed for this article. It uses only the Python standard library, so the control flow does not depend on a model vendor SDK. Run it with python3 check_release_packet.py release_packet.json and expect a non-zero exit when human fields are incomplete. Pass --scan and a draft path only after a brief has been produced from the same packet file.

#!/usr/bin/env python3
"""Proposed gate: refuse changelog drafts until human impact fields exist."""
import json, re, sys

SUPPORT = {"current_minor_only", "current_major", "extended_lts"}
TYPES = {"feat", "fix", "perf", "docs"}
SEMVER = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$")
FORBIDDEN = re.compile(r"\b(CVE-\d{4}-\d+|SLA|guaranteed|must migrate)\b", re.I)

def require_human(packet):
    errors = []
    if not SEMVER.match(str(packet.get("version", ""))):
        errors.append("version must be a SemVer core triple")
    if not re.match(r"^\d{4}-\d{2}-\d{2}$", str(packet.get("release_date", ""))):
        errors.append("release_date must be YYYY-MM-DD")
    if packet.get("support_window") not in SUPPORT:
        errors.append("support_window is outside the allowlist")
    for key in ("breaking_changes", "security_notes", "commits"):
        if not isinstance(packet.get(key), list):
            errors.append(f"{key} must be a list")
    sign = packet.get("sign_off") or {}
    if not sign.get("name") or not sign.get("role") or not sign.get("signed_at"):
        errors.append("sign_off name, role, and signed_at are required")
    for item in packet.get("commits") or []:
        if item.get("type") not in TYPES:
            errors.append("commit type not draftable: %s" % item.get("type"))
        if not re.match(r"^[0-9a-f]{7,40}$", str(item.get("sha", ""))):
            errors.append("commit sha must be lowercase hex")
    return errors

def brief(packet):
    lines = [
        "Summarize only these commits. Cite each sha.",
        "Do not add versions, dates, CVEs, or migration orders.",
    ]
    for item in packet["commits"]:
        lines.append("- %s %s: %s" % (item["type"], item["sha"], item["subject"]))
    return "\n".join(lines)

def main():
    with open(sys.argv[1], encoding="utf-8") as handle:
        packet = json.load(handle)
    errors = require_human(packet)
    if errors:
        print("\n".join(errors), file=sys.stderr)
        return 2
    if len(sys.argv) > 2 and sys.argv[2] == "--scan":
        with open(sys.argv[3], encoding="utf-8") as handle:
            text = handle.read()
        shas = {item["sha"] for item in packet["commits"]}
        if FORBIDDEN.search(text) or not any(sha in text for sha in shas):
            print("draft failed citation or forbidden-language scan", file=sys.stderr)
            return 3
        print("scan passed")
        return 0
    print(brief(packet))
    return 0

if __name__ == "__main__":
    sys.exit(main())

A passing scan is not a release approval, and the forbidden-language list in the sample is intentionally small. A careful sentence can still overclaim without using CVE, SLA, guaranteed, or the phrase must migrate. Extend the expression from incidents your team has actually recorded, rather than from hypothetical model failures. Do not treat this sample as a complete compliance control for regulated products or public security notices.

The version expression accepts only a core triple, so tags such as release candidates need an owner exception. The scan checks that at least one packet SHA appears, which is weaker than requiring every bullet to cite one. Tighten that test before you rely on it, and keep the human read of each bullet even after you do. These gaps are reasons to treat the script as a gate sketch, not as a finished release system.

The following checks describe how to validate the proposal, and they were not run for this article. Use a temporary directory and synthetic JSON so the exercise cannot touch a real release branch. Expect exit status 0 only for the complete packet, and expect status 2 when sign-off is removed. Expect status 3 when the draft contains an advisory token or omits every SHA that the packet listed.

python3 check_release_packet.py release_packet.json
python3 check_release_packet.py release_packet.json --scan summary_draft.md

Where a free model may enter

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode free model access belongs in this workflow only after the checker prints a constrained brief. The brief is the instruction boundary, and the model should not receive unsigned impact fields or raw repository secrets. The free server option is a candidate host for the checker only when that environment already provides Python 3. This article does not assert image contents, quotas, hardware, durations, or that either free option is permanent.

If that access is already available, prefer the free server for the checker only when Python 3 is already installed there. That order is the useful product step in this method, and the same gate still works on any Python 3 host you trust. Do not add a second model pass to invent missing security notes, because absence must stay an owner decision. Remove the product from the procedure and the packet, the brief, and the scan remain the parts that protect readers.

Who should not use this split

Do not use this split for security advisories, legal notices, or status pages, because those pages are commitments. Skip the workflow when no named person will sign the packet, since an unsigned file is only a draft container. Also skip it when history is squashed into vague messages that hide user-visible behavior behind a single merge commit. Private customer notices are a poor fit, because a missing qualifier can change an agreement the checker cannot read.

The gate does not prove that a commit subject is true, and a sloppy subject can pass every regular expression. Free model access adds no factual warranty, and a free server does not store an approval or a legal signature. As of 2026-10-09, recheck the three linked specification pages before you encode version policy into automation. Review the packet, the brief, and the draft together, and reject any bullet whose SHA you cannot open.

Gate Generated Config Guides with an Extract and an Owner File

Avery Lin — Thu, 08 Oct 2026 15:34:26 +0000

Configuration documentation should merge only after every sentence is classified as an extracted fact, a human recommendation, or narration that makes no operational promise. A model may explain keys that a schema extract already lists, and it may restate defaults that the same extract records. A human must own recommended values, secret handling, environment overrides, and any sentence that implies support. This split keeps generated guidance useful without letting drafted prose invent a contract the repository cannot prove.

Why generated config pages drift

Most configuration pages fail quietly because reviewers judge fluency while the evidence grade of each sentence stays invisible. The page names a real key, then slides from the shipped default into a preferred production value without a second source. Operators treat that slide as a supported promise, and a later incident can inherit a setting nobody agreed to own. The useful fix is a frozen schema extract, a separate recommendation file, and a checker that rejects mixed claims before merge.

Three evidence grades on one page

An extracted fact is a key name, type, or default that appears in the current schema extract and nowhere else. A recommendation is an owner-approved value for a named environment, with a review date and an explicit non-goal. Narration may define a term, point to a file path, or explain why two recorded facts sit near each other. Narration may not introduce a number, a port, a timeout, or a security outcome that neither input file contains.

Claim in the draft	Required evidence	Writer	Merge rule
Key exists, with type	Schema extract row	Model may restate	Fail if the path is absent
Shipped default	Extract default field, copied exactly	Model may restate	Fail on any mismatch
Recommended value	Human entry with owner, environment, and review date	Human writes the entry; model may quote it	Fail if the quote or owner fields are missing
Secret handling	Human file names the key and the store, never the value	Human only	Fail if a literal secret appears
Support or compliance sentence	Out of scope for this page	Nobody in this workflow	Fail closed
Navigation and definitions	Extract descriptions plus file paths	Model may draft	Allowed only without new numbers

The table above is the merge policy for this workflow, and it is intentionally smaller than a full style guide. Rows describe claim types rather than page sections, because a single paragraph often mixes more than one grade. A sentence that fails its row should be deleted or moved into the human file before anyone rewrites tone. This policy is a proposal for review gates, and it does not describe the behavior of any particular documentation platform.

What the model may draft

The model may draft a definition sentence for each key present in the extract, using the type and description fields already stored there. It may restate a default only by copying the extracted value, including units and nullability, without rounding or substituting a common port. It may write a short navigation sentence that points to the recommendation file when a key has an owner-approved override. It may not choose that override, estimate a safe timeout, or describe compliance effects that the inputs do not state.

What a human must own

A human owner must record every recommended value, the environment it applies to, and the date when that recommendation expires or needs review. The same owner must state which keys are secrets, which files must never be committed, and which defaults are unsafe outside local development. Support boundaries belong in that file too, including which combinations the team will debug and which combinations are explicitly unsupported. Generated prose may quote those recorded lines, but it may not soften, extend, or generalize them into a broader promise.

Workflow

1. Freeze a schema extract from a real input

Start from a schema file that the repository already treats as input to validation, not from an old README table. The extract should keep key path, type, default, and a content hash so later prose can be tied to one revision. If no schema exists, build the extract from a checked-in fixture that a test already loads, and label that fixture as the source. Do not ask a model to infer missing defaults from memory, because that inference is exactly the claim this gate exists to block.

python3 tools/extract_config_keys.py \
  --schema config/app.schema.json \
  --out build/schema-extract.json

#!/usr/bin/env python3
"""Build a flat key extract from a small JSON Schema document.

Labeled example: allOf, $ref, and remote schema URLs are not handled here.
"""

import argparse
import hashlib
import json
from pathlib import Path

def render_default(spec):
    if 'default' not in spec:
        return None
    if spec['default'] is None:
        return 'null'
    return str(spec['default'])

def walk(node, prefix, out):
    props = node.get('properties') or {}
    for name, spec in props.items():
        path = prefix + '.' + name if prefix else name
        if isinstance(spec, dict) and 'properties' in spec:
            walk(spec, path, out)
            continue
        out.append({
            'path': path,
            'type': spec.get('type', 'unknown') if isinstance(spec, dict) else 'unknown',
            'default': render_default(spec if isinstance(spec, dict) else {}),
            'description': spec.get('description', '') if isinstance(spec, dict) else '',
        })

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument('--schema', required=True)
    parser.add_argument('--out', required=True)
    args = parser.parse_args()
    raw = Path(args.schema).read_bytes()
    keys = []
    walk(json.loads(raw), '', keys)
    payload = {
        'source': args.schema,
        'content_hash': 'sha256:' + hashlib.sha256(raw).hexdigest(),
        'keys': keys,
    }
    Path(args.out).write_text(json.dumps(payload, indent=2) + '\n')

if __name__ == '__main__':
    main()

The walker above is a proposed local tool, and it only reads the schema file you pass on the command line. It records a hash of that file so the documentation job can show which revision the prose describes. Nested objects become dotted paths, which keeps the later checks simple without inventing values that the schema never stored. Schema combinators, remote references, and network URLs stay out of scope for this first gate on purpose.

2. Record recommendations in a human-owned file

The recommendation file is short on purpose, and a human edits it in the same pull request that changes supported settings. Each entry names an owner, an environment, a review date, a value, and a reason that points to an issue or decision record. Absence is meaningful: if a key has no entry, the doc may describe the extracted default and must not recommend a replacement. Secret values never appear here; the file may only name the key and say that the value comes from a secret store.

{
  "recommendations": [
    {
      "path": "http.timeout_ms",
      "value": "5000",
      "environment": "staging",
      "owner": "ops-docs",
      "review_date": "2026-12-01",
      "reason": "placeholder decision id, replace with a real record",
      "non_goal": "not a production support promise"
    }
  ]
}

Treat the JSON above as a fixture shape, not as a setting any running service uses. The review date should be a real calendar date your owner accepts, and the reason should point to a record your team can open. The non-goal line is there so a later quote cannot be read as a broader warranty. If you cannot fill owner and review date, leave the key out rather than asking a model to invent them.

3. Draft narration only from those two inputs

Give the model only the schema extract, the recommendation file, and a sentence budget for each key. Ask it to label each paragraph as extracted, recommended, or narration, and to omit any key missing from the extract. Run that draft on a host you already trust, then discard any sentence that cites a file the prompt did not include. Save the raw draft beside the extract hash so a reviewer can see which inputs the narration was allowed to use.

Require three surface patterns in the draft so the checker can stay small, deterministic, and easy to explain. State a shipped default only with the fixed phrase for extracted defaults, followed by the exact value in backticks. State an owned override only with the fixed phrase for recorded recommendations, followed by the human value in backticks. Any other sentence may name backticked key paths, but it must not add digits, support language, or recommendation verbs.

4. Run the lane checker before review

The checker reads the extract, the recommendation file, and the markdown draft, then fails the build on four conditions. A mentioned key path must exist in the extract, and a stated default must match the extracted value exactly. A sentence that uses recommendation language must quote a value present in the human file for that key. A sentence that mentions a secret value, a support promise, or an unlisted number must fail even if the surrounding prose sounds cautious.

python3 tools/check_config_doc.py \
  --extract build/schema-extract.json \
  --recs owners/recommendations.json \
  --doc docs/configuration.md

#!/usr/bin/env python3
"""Fail config docs that mix extracted defaults with unowned recommendations.

Proposed local gate. It does not call a model and does not open a network connection.
"""

import argparse
import json
import re
import sys
from pathlib import Path

KEY_RE = re.compile(r'`([A-Za-z0-9_.-]+)`')
DEFAULT_RE = re.compile(r'extracted default is `([^`]+)`')
REC_VALUE_RE = re.compile(r'recorded recommendation is `([^`]+)`')
REC_WORD_RE = re.compile(
    r'\b(recommend(?:ed|ation)?|should set|prefer(?:red)?|production value)\b',
    re.I,
)
SUPPORT_RE = re.compile(
    r'\b(we support|supported combination|service level|guaranteed)\b',
    re.I,
)
SECRET_LITERAL_RE = re.compile(
    r'\b(api[_-]?key|password|secret|token)\b.{0,40}`[^`]{6,}`',
    re.I,
)
NUMBER_RE = re.compile(r'\d')

def load(path):
    return json.loads(Path(path).read_text())

def check(doc, extract, recs):
    errors = []
    by_path = {item['path']: item for item in extract['keys']}
    rec_by_path = {item['path']: item for item in recs['recommendations']}
    known = set(by_path) | set(rec_by_path)
    for lineno, line in enumerate(doc.splitlines(), 1):
        mentioned = KEY_RE.findall(line)
        for key in mentioned:
            if '.' in key and key not in known:
                errors.append(f'{lineno}: `{key}` is not in the schema extract')
        for shown in DEFAULT_RE.findall(line):
            keys = [key for key in mentioned if key in by_path]
            if not keys:
                errors.append(f'{lineno}: extracted default without a known key')
            for key in keys:
                expected = by_path[key]['default']
                if shown != expected:
                    errors.append(
                        f'{lineno}: default `{shown}` for `{key}` != extract `{expected}`'
                    )
        recommends = bool(REC_WORD_RE.search(line) or REC_VALUE_RE.search(line))
        if recommends:
            keys = [key for key in mentioned if key in known]
            if not keys:
                errors.append(f'{lineno}: recommendation language without a known key')
            for key in keys:
                rec = rec_by_path.get(key)
                if rec is None:
                    errors.append(f'{lineno}: `{key}` has no human recommendation entry')
                    continue
                quoted = REC_VALUE_RE.findall(line)
                recorded = str(rec['value'])
                if recorded not in quoted:
                    errors.append(
                        f'{lineno}: `{key}` must quote recorded value `{recorded}`'
                    )
                for field in ('owner', 'environment', 'review_date'):
                    if not rec.get(field):
                        errors.append(f'{lineno}: human entry `{key}` missing {field}')
        if SUPPORT_RE.search(line):
            errors.append(f'{lineno}: support language is outside this config page')
        if SECRET_LITERAL_RE.search(line):
            errors.append(f'{lineno}: possible secret literal; name the store, not the value')
        allowed_numbers = set(DEFAULT_RE.findall(line)) | set(REC_VALUE_RE.findall(line))
        residue = line
        for value in allowed_numbers:
            residue = residue.replace('`' + value + '`', '')
        if NUMBER_RE.search(residue):
            errors.append(
                f'{lineno}: number is neither an extracted default nor a recorded recommendation'
            )
    return errors

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument('--extract', required=True)
    parser.add_argument('--recs', required=True)
    parser.add_argument('--doc', required=True)
    args = parser.parse_args()
    errors = check(Path(args.doc).read_text(), load(args.extract), load(args.recs))
    if errors:
        print('\n'.join(errors))
        return 1
    print('config doc claims match extract and human recommendations')
    return 0

if __name__ == '__main__':
    sys.exit(main())

5. Review the human file before the prose

Review time should land on the recommendation file and the extract hash, not on whether the generated sentences sound friendly. If the hash changed, regenerate the draft from the new extract instead of patching numbers by hand inside the markdown. If the owner, environment, or review date is missing, the page is not ready, even when every key name is correct. This order keeps the model in a drafting role and keeps the support boundary in a file a person can diff.

Expected results on the fixtures

The fixtures below are illustrative inputs for the method, and they are not measurements from a production service. You can place them next to the script and compare the exit status with the two cases described here. The failing page is written to report a default mismatch, an unowned recommendation, and a key missing from the extract. The passing page is written to print the success line and exit with status zero, because every number is an exact copy.

Minimal schema fixture, config/app.schema.json:

{
  "type": "object",
  "properties": {
    "http": {
      "type": "object",
      "properties": {
        "port": {
          "type": "integer",
          "default": 8080,
          "description": "Listen port for the local process."
        },
        "timeout_ms": {
          "type": "integer",
          "default": 2000,
          "description": "Request timeout in milliseconds."
        }
      }
    },
    "log": {
      "type": "object",
      "properties": {
        "level": {
          "type": "string",
          "default": "info",
          "description": "Log verbosity name."
        }
      }
    }
  }
}

Failing draft, written so the checker should reject it:

`http.port` is the listen port. The extracted default is `80`.
Prefer a production value `443` for `http.port`.
`cache.ttl_seconds` should set the value to `30`.

The script is written to emit a default mismatch for http.port, a missing human entry for that same key, and an unknown-key error for cache.ttl_seconds. It is also written to flag the extra digits 443 and 30, because those numbers are neither extracted defaults nor recorded recommendations. Run the command on your machine before you trust the gate, and treat a different message as a bug in the local copy. These lines are specified behavior of the example, not a benchmark from a hosted documentation run.

Passing draft, which stays inside the two files:

`http.port` is the listen port. The extracted default is `8080`.
`http.timeout_ms` has a staging override. The recorded recommendation is `5000`.
`log.level` controls verbosity. The extracted default is `info`.

How to read a failed check

Read the line number first, then decide whether the fix belongs in the schema, the human file, or the draft. A missing key means the prose invented a path, so delete the sentence or add the key through the normal schema change. A default mismatch means the draft drifted, so copy the extract value again instead of editing the schema to match the prose. An unowned recommendation means a person must either record the value with owner fields or remove the advice entirely.

Limitations of a phrase gate

This checker is a text gate, so it misses recommendations that avoid words like recommended, should, and prefer. A synonym pass will still miss implied advice, which means a human read of narration remains necessary on every change. The extract can also drift from the running binary if your build does not regenerate it in the same job that validates docs. Do not use this workflow for security advisories, legal terms, or incident updates, which need a different ownership record.

Who should not start with generated guidance

Skip this approach when the repository has no schema, no fixture, and no person willing to sign the recommendation file. Skip pages that must state a service level, compliance status, or a customer-specific exception outside config narration. Teams that want the model to pick production values will find the gate frustrating, and that frustration is the intended result. A docs-only repository with unchecked examples should first capture an extract, then adopt the checker, rather than generating a full guide on day one.

Put the gate on the merge path

Add the checker to the same job that already builds docs, and fail the job when the exit status is non-zero. Keep the recommendation file beside a named code owner so generated markdown cannot update supported values unnoticed. Regenerate the draft whenever the extract hash changes, and do not patch numeric claims by hand in the markdown. The page is ready only when the extract hash, the recommendation review date, and the checker result match the commit you intend to merge.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

If both files already exist, MonkeyCode's free model access is a fitting place to draft narration from those files alone. The free server option is a reasonable place to run this checker before review when Python 3 is already available. Neither option chooses recommended values, and neither option replaces the human owner named in the recommendation file.

Stamp Human Ownership on Product Facts Before Generated Docs Merge

Avery Lin — Thu, 08 Oct 2026 11:04:20 +0000

Generated documentation fails when a model is allowed to invent the facts a maintainer must defend. The useful split is operational rather than stylistic, so reviewers should fix it before any drafting starts. A model may draft page structure, section transitions, and code examples that stay labeled as unexecuted proposals.

A human must own versions, limits, security boundaries, and any availability statement a reader might rely on. Teams that skip that split ship pages that read smoothly and still misstate what the product currently offers. This workflow keeps the generated draft useful without treating raw model output as a source of record.

Why generated setup pages drift

A setup page mixes local procedure with product claims, and those two kinds of sentences age differently. Local commands can be checked against a repository at a known commit, while quotas and server offers change outside that commit. If the model writes both kinds in one pass, reviewers tend to edit tone and miss an unsupported number. The failure is measurable as a count of unowned claims rather than as awkward or unfinished prose.

Public write-ups of generated personal sites show the same ownership gap under a different page format. A page can look finished while its factual layer was never assigned to a named person. Documentation teams should treat that pattern as a review defect, not as a reason to ban drafting tools. The remedy is a register that decides ownership before any generated paragraph is accepted into the branch.

What the model may draft

Reviewers should use the table below as a merge gate rather than as a prose style guide. A sentence moves to the model only when a false statement would be caught by a local test or an explicit proposal label. Everything else stays with a named human owner until a primary source is attached to the row.

Claim type	Model may draft	Human must own	Gate before merge
Heading outline and section order	Yes	Reviews the outline	No product facts inside headings
Explanation of code already in the repo	Yes, if cited to a path	Confirms path and commit	Link the file and revision
Commands marked as unexecuted proposals	Yes, with a proposal label	Decides whether to run them	Do not present them as measured results
Version pins, API names, and default flags	No	Yes	Quote the repo or upstream docs
Quotas, duration, hardware, and price	No	Yes	Attach a current primary source or omit
Security boundaries and data handling	No	Yes	Name the control and the owner
Rankings and permanence language	No	Yes	Refuse unsupported comparisons

Quotas, durations, hardware notes, and model menus stay in the human-owned lane even when a vendor brief sounds specific. A reviewer copies those sentences only from a primary page retrieved on the publication day, and stores that URL on the row. If that page is silent, the generated draft must not invent a number to make the setup section feel complete. The same block applies to rankings, permanence language, and any claim that becomes false if the offer changes tomorrow.

Worked classification

Consider these three sentences that often land together in a generated setup guide for a hosted tool. The first sentence lists local files the reader will edit, and it can be drafted if the paths exist at the frozen commit. The second sentence says a free server option exists, and it stays human-owned until the current documentation URL is stored on the row. The third sentence names a token quantity, and it is blocked until a primary source states that quantity on the day of publication.

That third block is deliberate, because an outreach brief is not a primary source and can go stale before review finishes. The same rule covers hardware shapes, time limits, model identifiers, and any ranking against other tools. If the source is missing on publication day, the page ships without the sentence instead of shipping a guessed figure.

Numbered workflow

Follow the six steps in order, and do not ask a model for prose until the register rows exist.

Freeze the source set by recording the repository commit, the document path, and every product page a human will cite.
Extract candidate sentences so each claim occupies one line and can receive an owner stamp before generation.
Classify each line as model_draft, human_own, or blocked, and attach a source to every current human-owned fact.
Draft only open lanes by requesting headings, transitions, and proposal-labeled examples, then paste frozen human lines back unchanged.
Diff the draft against the register, and fail the page when a blocked claim appears or a human line was paraphrased.
Require approval from a person who can defend the product facts, and keep model output marked as a draft until that approval.

The sequence stays intentionally strict because generation is cheap and a later public correction is expensive. A reviewer who cannot explain a human-owned row should send the page back before any model sentence is expanded. Shared notes from that rejection belong in the register, not in a chat transcript that the next draft can quietly drop.

Register checker

The script below is a local review proposal, and it is not a record of an executed benchmark. It reads a JSON register and a markdown draft, then exits non-zero when unowned product language sits outside stamped lines. Adapt the forbidden token list to your own unsupported claims rather than treating the sample list as a product specification. Store the checker under tools so the same command can run in review and on a shared server workspace.

#!/usr/bin/env python3
"""Proposal: flag unowned product claims in a generated doc draft."""
import json
import sys
import re

FORBIDDEN = re.compile(
    r"\b(quota|tokens?|gpu|sla|permanent|unlimited|benchmark)\b",
    re.I,
)

def load(path):
    with open(path, encoding="utf-8") as handle:
        return json.load(handle)

def main(register_path, draft_path):
    register = load(register_path)
    draft = open(draft_path, encoding="utf-8").read()
    owned = [
        row["text"]
        for row in register["claims"]
        if row["lane"] == "human_own"
    ]
    errors = []
    for row in register["claims"]:
        if row["lane"] == "human_own" and row["text"] not in draft:
            errors.append("missing owned line: %s" % row["id"])
        if row["lane"] == "blocked" and row["text"] in draft:
            errors.append("blocked line present: %s" % row["id"])
    residue = draft
    for text in owned:
        residue = residue.replace(text, "")
    for match in FORBIDDEN.finditer(residue):
        errors.append("unowned term in draft residue: %s" % match.group(0))
    if errors:
        print("\n".join(errors))
        return 1
    print("register check passed")
    return 0

if __name__ == "__main__":
    sys.exit(main(sys.argv[1], sys.argv[2]))

A matching register should stay small enough that a reviewer can read every owned sentence during the same pass. Each row names the lane, the exact sentence a human will defend, and the source that justified the stamp. Replace the placeholder commit and URL before the checker is allowed to pass in a real review.

{
  "commit": "REPLACE_WITH_REVIEWED_SHA",
  "claims": [
    {
      "id": "avail-1",
      "lane": "human_own",
      "text": "Operator-stated options are free model access and a free server option.",
      "source": "REPLACE_WITH_CURRENT_PRODUCT_DOC_URL"
    },
    {
      "id": "quota-1",
      "lane": "blocked",
      "text": "The free tier includes a fixed token quantity.",
      "source": null
    }
  ]
}

Run the checker from the repository root after the draft exists, and treat a non-zero exit as a merge block. A zero exit only means the scanned strings matched the register, not that the claims are true. Link checks, example execution, and legal review remain separate gates that this script does not pretend to cover.

mkdir -p tools docs
python3 tools/doc_ownership_check.py docs/register.json docs/setup.md

An unexecuted expectation is a non-zero exit when the draft residue contains the word quota outside a human-owned line. A clean draft that repeats only stamped lines, and avoids the forbidden list elsewhere, is expected to print the pass line. Those expectations were not executed for this article, so a team should run them on a fixture before trusting the gate.

Where a free drafting pass fits

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode enters this method only as the drafting workspace those two operator-supplied options are meant to cover. A free model access option and a free server option are the two availability claims the operator supplied for this workflow. Neither option is a quota, a hardware profile, a duration, or permission to skip the ownership stamp.

A free model is enough for the drafting step because that step is forbidden from creating product facts. A free server is enough when reviewers need one workspace that holds the register, the draft, and the checker. Readers should confirm both options in the current project documentation before a setup page repeats them. If a repository is the source of truth for licensing, cite that repository instead of restating license terms from memory.

Limitations

This checker is a string gate, so a paraphrase of a blocked claim can still pass after forbidden words are removed. It does not execute examples, verify links, or prove that a cited page still matches the register from yesterday. Teams should not treat a passing run as compliance certification, a security review, or a substitute for reading. Authors who cannot name a human owner for an availability claim should omit that claim instead of drafting around it.

Who should skip this approach

Skip the workflow when the page is a personal log that states no product facts a stranger might rely on. In that case the register adds ceremony without reducing the risk of an unsupported public statement. Skip it when legal or security copy must come from counsel, because a documentation lane is the wrong owner. Also skip it when the only goal is to maximize mentions of a tool, because the page must stay useful without those mentions.

If the ownership split is the constraint you actually have, rehearse the six steps on one setup page before expanding the register. Keep the product mention to the single sentence a human can still defend after every model sentence is removed. That remaining sentence should point readers to current project documentation rather than freeze a quota, a duration, or a hardware claim.