DEV Community: Avery Lin

Citation or a Named Owner: A Routing Gate for Model-Drafted Docs

Avery Lin — Wed, 28 Oct 2026 01:13:31 +0000

A paragraph drafted by a model should reach main only when it resolves to something in the repository or carries a human's name. Everything else is a paragraph nobody has agreed to defend, and the usual review queue hides that fact behind a green check. This article describes a small router I use to enforce that rule, plus the parts of documentation a model should never draft at all.

The gate splits a Markdown page into paragraph-sized blocks, tries to resolve every [[ev:...]] pointer against the codebase, and returns one of four tiers per block. Blocks that resolve and carry a ledger signature pass; blocks that resolve without a signature wait for a named reviewer; blocks with no evidence are blocked outright. Human-owned blocks are marked with an invisible owner comment and are stripped out of the prompt before the model ever sees the page. If you have read the debate about reviewers acting as a proxy between a team and a model, this is the mechanical version of that complaint.

The rule: a citation or a name

The rule is deliberately binary, because three-way ownership conversations never terminate. A single sentence of documentation is either tied to an artifact that a script can find, or it belongs to a person who accepts responsibility. Tone, warnings, migration advice, and anything legal fall in the second category by definition, no matter how confident the model sounds.

This also fixes a review pathology that is easy to miss. When every paragraph is equally reviewable, reviewers skim and sign everything, which is exactly the proxy behaviour that upstream discussions of AI-assisted work keep warning about. Making sign-off paragraph-scoped and hash-bound makes blanket approval visible as a suspiciously fast ledger.

The four tiers

Tier	Who writes it	Who signs it	Merge rule
`merge_ready`	model, from evidence	a human, once, bound to the paragraph hash	passes CI
`unsigned`	model, from evidence	a named human	blocked until signed
`unowned`	model or human	nobody	blocked; assign an owner or delete
`human_owned`	humans only	the owner named in the marker	model output for that block is discarded

The tier names are the whole contract, and the pipeline only needs to understand four strings. Everything below is the implementation that produces them.

Step 1 — Mark the human-owned zone with an invisible comment

Use an HTML comment immediately after the heading, so the marker disappears in the rendered page. The heading text stays clean for readers, and the owner name is greppable in review diffs.

## Security posture
<!-- owner: security-team -->
Data at rest is encrypted, and the rotation schedule is documented internally.

Anything matching  is treated as human-owned, and this takes precedence over evidence. A block can have perfect citations and still be human-owned, which is the correct outcome for security, pricing, deprecation policy, and support commitments. Before building the drafting prompt, drop these blocks from the input entirely, rather than instructing the model to leave them alone.

Step 2 — Give the model a pointer vocabulary it cannot invent

The model may only cite four kinds of pointer, each with a mechanically checkable shape. Anything else is prose, and prose is owned by a person.

## Retry policy

The client retries idempotent requests three times with exponential backoff [[ev:cfg:settings.retry_attempts]].
The budget is pinned by a test [[ev:test:test_retry_budget]] and the helper lives in [[ev:sym:RetryPolicy]].

sym targets a definition, test targets a collected test id, cfg targets a configuration key, and issue is accepted syntactically but never resolved. Issue pointers are always human-owned, because a script cannot verify what a tracker link claims. Keep the vocabulary small: every new pointer type is a new way for a confident sentence to look verified when it is not.

Step 3 — Resolve pointers against the repo and fail closed

The gate is about eighty lines of standard library and shell calls, and it exits non-zero when any block is not merge_ready. Resolution is intentionally crude; a grep that finds nothing is a rejection, not a warning.

#!/usr/bin/env python3
"""evidence_gate.py: route every doc block to a citation or a named owner."""
import hashlib, json, re, subprocess, sys
from pathlib import Path

POINTER = re.compile(r"\[\[ev:(sym|test|cfg|issue):([^\]\s]+)\]\]")
OWNER = re.compile(r"<!--\s*owner:\s*([a-z0-9_.-]+)\s*-->")
HEADING = re.compile(r"^(#{1,6})\s+(.+)$")


def split_blocks(text: str) -> list[dict]:
    blocks, heading, buf = [], "", []

    def flush() -> None:
        block = "\n".join(buf).strip()
        if block:
            blocks.append({"heading": heading, "text": block,
                           "sha": hashlib.sha256(block.encode()).hexdigest()[:16]})

    for line in text.splitlines():
        match = HEADING.match(line)
        if match:
            flush(); buf = []; heading = match.group(2).strip(); continue
        if not line.strip():
            flush(); buf = []; continue
        buf.append(line)
    flush()
    return blocks


def grep(pattern: str, root: Path) -> list[str]:
    done = subprocess.run(["grep", "-rIlE", "--exclude-dir=.git", pattern, str(root)],
                          capture_output=True, text=True)
    return [line for line in done.stdout.splitlines() if line]


def collected_tests(root: Path) -> set[str]:
    done = subprocess.run([sys.executable, "-m", "pytest", "--collect-only", "-q"],
                          cwd=root, capture_output=True, text=True)
    return {line.split("::")[-1] for line in done.stdout.splitlines() if "::" in line}


def resolve(kind: str, target: str, root: Path, tests: set[str]) -> list[str]:
    if kind == "sym":
        return grep(rf"(def|class|const|function)\s+{re.escape(target)}\b", root)
    if kind == "cfg":
        key = target.split(":")[-1]
        return grep(rf"^\s*{re.escape(key)}\s*[:=]", root)
    if kind == "test":
        return [target] if target.split("::")[-1] in tests else []
    return []  # issue links are not verifiable from the repo


def route(docs: Path, root: Path, signed: set[str]) -> list[dict]:
    tests = collected_tests(root)
    rows = []
    for block in split_blocks(docs.read_text(encoding="utf-8")):
        owner = OWNER.search(block["text"])
        evidence, unresolved = [], []
        for kind, target in POINTER.findall(block["text"]):
            hits = resolve(kind, target, root, tests)
            (evidence if hits else unresolved).append({"kind": kind, "target": target, "hits": hits})
        if owner:
            tier, who = "human_owned", owner.group(1)
        elif unresolved or not evidence:
            tier, who = "unowned", None
        elif block["sha"] not in signed:
            tier, who = "unsigned", None
        else:
            tier, who = "merge_ready", None
        rows.append({**block, "tier": tier, "owner": who,
                     "evidence": evidence, "unresolved": unresolved})
    return rows


if __name__ == "__main__":
    docs = Path(sys.argv[1])
    root = Path(sys.argv[2] if len(sys.argv) > 2 else ".")
    ledger = Path("signatures.json")
    signed = set(json.loads(ledger.read_text())) if ledger.exists() else set()
    rows = route(docs, root, signed)
    print(json.dumps(rows, indent=2))
    blocked = [row for row in rows if row["tier"] != "merge_ready"]
    print(f"{len(rows)} blocks, {len(blocked)} blocked", file=sys.stderr)
    sys.exit(1 if blocked else 0)

Run it from the repository root, so that the grep and the test collection see the same tree the docs describe.

python -m pytest --collect-only -q | grep '::' | head   # sanity-check test ids
python evidence_gate.py docs/retries.md . > routing.json

The JSON output is the review artifact, and it is intentionally boring. Each row lists the block hash, its tier, the files that satisfied each pointer, and the pointers that failed. This is where the drafting pass runs naturally on MonkeyCode's free model access, with the resolver and the test collection on the free server option; both are operator-supplied availability claims, and I make no assumptions about quotas, model names, or throughput. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Step 4 — Hash the paragraph so a re-draft voids the old signature

Signatures must attach to text, not to sections, or a regenerated paragraph inherits an approval it never earned. That is why the ledger stores only the sixteen-character block hash, and why a single changed word returns the block to unsigned.

# sign.py <block-sha> — append one human sign-off to the ledger
import json, sys
from pathlib import Path
ledger = Path("signatures.json")
signed = set(json.loads(ledger.read_text())) if ledger.exists() else set()
signed.add(sys.argv[1])
ledger.write_text(json.dumps(sorted(signed), indent=2) + "\n")

Example output for the snippet in step 2 looks like the following, and it is illustrative rather than a benchmark. The retry block resolves both pointers and waits for a signature, while the security block is human-owned and never enters a prompt.

[
  {"heading": "Retry policy", "sha": "9f2c41ab77d0e3c5", "tier": "unsigned",
   "evidence": [{"kind": "cfg", "target": "settings.retry_attempts", "hits": ["./settings.toml"]},
                {"kind": "test", "target": "test_retry_budget", "hits": ["test_retry_budget"]}],
   "unresolved": []},
  {"heading": "Security posture", "sha": "1c8de40a55b9f271", "tier": "human_owned",
   "owner": "security-team", "evidence": [], "unresolved": []}
]

Step 5 — Wire the gate into CI and cap the human queue

Put the script in the docs job, cache the pytest --collect-only output, and fail the build on any tier other than merge_ready. Caching matters on large suites, because collection can take longer than the gate itself and will otherwise dominate the job.

A useful second rule is a hard cap on unsigned blocks per pull request, for example five. When the cap is exceeded, the author must either find more evidence or move content into a human-owned block and assign an owner. That single limit prevents the pattern where a model regenerates a whole page and the review queue silently becomes a reading queue.

What this gate cannot prove

Pointer resolution proves existence, not correctness, which is the most important limitation here. A citation can point at a real configuration key that the paragraph describes incorrectly, and no hash will notice. Symbol lookup is also grep-based, so renames produce false rejections until the pointer is updated, which is annoying but safe.

Parametrised test ids drift when fixtures change, and issue pointers never resolve by design, so a tracker-heavy page stays effectively human-owned. Formatting-only edits invalidate signatures, so reformat before signing rather than after. None of these costs are hidden in the tier names, and none of them justify skipping the gate on a page that has already shipped wrong numbers.

Who should not use this

Skip this approach if your documentation lives outside the code repository, because the resolver has nothing to search. Skip it if no named humans can own security, pricing, or migration blocks, since the gate will manufacture a queue nobody drains. Skip it for marketing pages and regulation-bound text, where the correct default is human authorship from the first draft.

For everything else, start with one page and one owner, and let the blocked count tell you whether the model is drafting what the repository can actually support.

Human Sign-Off Expires: Bind Doc Attestations to Fact Hashes

Avery Lin — Tue, 27 Oct 2026 22:07:22 +0000

A documentation approval should never be permanent. It should be a short lease on one specific, machine-checkable fact, and it should expire the moment that fact moves. The workflow below turns every human-owned sentence in a generated doc into a hashed attestation, so a stale approval fails CI instead of quietly shipping.

This is the part of model-assisted documentation that most teams skip. They argue about what the model may draft, then hand the result to a reviewer whose approval outlives the code it described. Six weeks later the version floor, the default port, or the required permission has changed, and the page still reads as reviewed.

The failure is not hallucination, it is approval drift

Hallucination gets caught in review because it looks wrong. Approval drift survives review because it looked right when someone checked it. The reviewer was correct on the day of review, and nothing in the repo records which fact that correctness depended on.

Attestation expiry fixes the shape of the problem rather than the wording. Each human-owned span stores a hash of the fact value plus the claim text, and the check re-resolves the fact on every pull request. If the value changed, the signature is void and a human has to re-read one paragraph, not the whole page.

Decide drafting rights before you write a prompt

Write the split down once, in the repository, so the model's job and the reviewer's job are not renegotiated per page.

Span type	Model may draft	Human must sign	Lease breaks when
Prose that restates verified code or output	Yes	No	Code block or fact selector changes
Version floors, ports, env var names, limits	Yes, if a fact selector exists	Yes	Selector value changes
Rollback, recovery, and migration steps	No	Yes	Any cited fact changes
Permissions, security posture, data handling	No	Yes	Any cited fact changes
Changelog and release summaries	Yes	No	Next release

Two rules make this table usable. A span with no machine-checkable fact cannot be signed, because the signature would be a vibe. A span marked draft: model cannot be signed at all, because signing model prose adds paperwork without adding a guarantee.

Step 1: Write the span manifest

Keep the manifest beside the docs it governs. Each entry names a span, the owner who accepts responsibility, the exact claim being attested, and how to resolve the fact that claim depends on.

# docs/ownership.yaml
version: 1
spans:
  - id: readme.install.node-floor
    owner: "@avery"
    draft: human
    claim: "Requires Node 20 or newer."
    fact:
      kind: regex
      file: package.json
      pattern: '"node":\s*">=([0-9]+)'
      group: 1
    anchor: "## Requirements"

  - id: readme.install.default-port
    owner: "@avery"
    draft: human
    claim: "The server listens on port 8080 by default."
    fact:
      kind: regex
      file: internal/config/defaults.go
      pattern: 'DefaultPort\s*=\s*([0-9]+)'
      group: 1
    anchor: "## Run it"

  - id: readme.install.intro
    owner: "@avery"
    draft: model
    claim: "Painless local setup for the sync daemon."
    anchor: "## Requirements"

Fact selectors should be boring. Prefer a regex over a config file or a small command whose stdout is stable, and never point a selector at a generated artifact that changes on every build.

Step 2: Hash the fact and the claim together

Hashing the fact alone is not enough. If someone edits the claim text, the attested sentence no longer exists, so the signature must fall away too.

# tools/attest.py
from __future__ import annotations

import argparse
import hashlib
import json
import re
import subprocess
from datetime import datetime, timezone
from pathlib import Path

import yaml

LEDGER = Path(".attest/ledger.json")
MANIFEST = Path("docs/ownership.yaml")


def resolve(spec: dict) -> str:
    if spec["kind"] == "regex":
        text = Path(spec["file"]).read_text(encoding="utf-8")
        match = re.search(spec["pattern"], text, re.MULTILINE)
        if match is None:
            raise ValueError(f"selector matched nothing in {spec['file']}")
        return match.group(spec.get("group", 0)).strip()
    if spec["kind"] == "command":
        proc = subprocess.run(spec["run"], shell=True, capture_output=True, text=True)
        if proc.returncode != 0:
            raise ValueError(f"fact command failed: {spec['run']}")
        return proc.stdout.strip()
    raise ValueError(f"unknown fact kind: {spec['kind']!r}")


def digest(value: str, claim: str) -> str:
    h = hashlib.sha256()
    h.update(value.encode("utf-8"))
    h.update(b"\x00")
    h.update(" ".join(claim.split()).encode("utf-8"))
    return h.hexdigest()[:16]

Normalising whitespace before hashing keeps the check honest about content and indifferent to reformatting. A reviewer who reflows a paragraph should not have to re-sign it.

Step 3: Keep a ledger of signatures, not permissions

The ledger is a flat JSON file in the repository, so signatures travel with the branch and appear in review diffs. Every entry records the owner, the digest, the resolved value, and the UTC timestamp.

def load_ledger() -> dict:
    return json.loads(LEDGER.read_text()) if LEDGER.exists() else {}


def save_ledger(ledger: dict) -> None:
    LEDGER.parent.mkdir(parents=True, exist_ok=True)
    LEDGER.write_text(json.dumps(ledger, indent=2, sort_keys=True) + "\n")

Storing fact_value next to the digest is deliberate. When the check fails, the error message can print both the signed value and the current one, which turns a red build into a one-line diagnosis.

Step 4: Gate on freshness, sign on purpose

Two subcommands cover the whole lifecycle: check runs in CI and never writes, sign runs locally after a human read the span.

# reviewer signs one span after reading it against the code
python3 tools/attest.py sign readme.install.node-floor --owner "@avery"

# CI: fail if any human-owned span cites a fact that has moved
python3 tools/attest.py check
# FRESH readme.install.node-floor (human)
# STALE readme.install.default-port: signed 2026-10-21T09:14:03+00:00 by @avery, fact has moved
# 3 spans, 1 stale

Exit codes matter more than the log: 0 means every signature still matches, 1 means at least one lease expired, and 2 means a selector is broken and the gate cannot judge at all. Treat 2 as a build failure, never as a warning.

# .github/workflows/docs.yml
- name: Human attestations must be fresh
  run: python3 tools/attest.py check

The signing command refuses spans marked draft: model, which keeps the queue of human-owned work visible and small. In the example manifest above, three spans produce two signatures and one irreducibly human decision per release.

Step 5: Prove the gate can fail

A green check on an untouched repo proves nothing, so mutate the facts on a scratch branch and confirm each exit code.

Bump the Node floor in package.json to 22, run check, expect exit 1 with the version span named.
Reword the attested claim without signing, run check, expect exit 1 because the claim hash changed.
Run sign for that span, run check, expect exit 0 and a new ledger diff in review.
Rename the config field that the port selector reads, run check, expect exit 2 and a selector matched nothing message.
Let a model rewrite the prose around a human-owned span while its fact is unchanged, run check, expect exit 0 — and then read the diff, because the checker guards facts, not sentences.

Step 5 is the honest limitation, and it should live in the repository rather than in someone's memory. Fact hashes catch drift in numbers, names, and paths; they cannot catch a model that keeps every fact and still gets the tone, ordering, or preconditions wrong.

Where free model access fits, and where it does not

Drafting prose around verified code is the cheapest part of this pipeline to delegate, because the facts enter the page from selectors rather than from the model. I use MonkeyCode's free model access for those draft: model spans and review them like any other generated paragraph.

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

The nightly check job is a good fit for the free server option as well, since the check is a short Python process that reads YAML and JSON and exits. Anything that needs long-lived storage or heavy compute should stay on infrastructure you already control, and I would not move the ledger anywhere that hides it from code review.

If you want to try the loop on one README, start with a single human-owned span and let the check fail once on purpose before wiring it into CI.

Who should not use this

Single-maintainer docs with no reviewers do not need a signature ledger, because the author and the owner are the same person and the diff already shows the change. Teams whose claims have no machine-checkable source should skip the hash layer and invest in fact injection instead.

Regulated documentation that requires formal approval records, wet signatures, or audit trails outside the repository should keep its existing process; this ledger is a drift detector, not a compliance artifact. And if your fact selectors change weekly because the underlying config is unstable, fix the instability first, or the gate will cry wolf until people ignore it.

The goal is modest: make the human promise small enough that re-making it costs a minute.

Route Every Model-Drafted Sentence to a Named Human: A Provenance Ownership Gate for Docs

Avery Lin — Tue, 27 Oct 2026 19:02:04 +0000

A documentation draft is only reviewable when each factual sentence has a named owner who can be wrong about it. Most generated-docs pipelines enforce style, tone, and length, then hand the whole file to whoever happens to be on call. That reviewer cannot verify forty unrelated claims across three subsystems, so the review becomes a skim and the numbers drift. The gate below takes a different position: the model drafts prose freely, but every sentence that carries a fact must point at the code that produced it, and that pointer must resolve to a human or the build fails.

This is an ownership routing problem, not a writing problem. If you want a style linter, this article will not help you; if you want a reviewer with a defensible reason to approve a paragraph, keep reading.

The division of labor, stated as a table

Before writing any checker, decide in writing what the model is allowed to produce. Teams that skip this step end up arguing about individual sentences in review, which is the slowest possible feedback loop.

Artifact	Who drafts	Who owns the final wording
Transitions, intros, section ordering	Model	Docs reviewer
Restating a function signature already in the repo	Model	Docs reviewer
Error explanations that quote an existing message string	Model	Docs reviewer
Retry counts, timeouts, size limits, default values	Model copies from source	Owner of the source file
Deprecation dates, support windows, pricing, SLAs	Nobody	Product or legal, never model-generated
Security posture, data retention, compliance statements	Nobody	Security owner, never model-generated
Migration steps across a breaking change	Model proposes	Owner of the changed API

The right column is the important one, because it names a person or a team rather than a role. A paragraph about rate limits belongs to whoever owns the limiter, and that mapping already exists in your repository as .github/CODEOWNERS plus commit history.

Step 1: force facts to carry a pointer at draft time

Require the drafting prompt to emit an HTML comment immediately before any sentence that states a verifiable value. The marker is invisible in rendered Markdown and cheap for a model to produce consistently.

<!-- fact: src/limiter.ts:MAX_RETRIES -->
Requests are retried up to three times before the client receives an error.

<!-- fact: src/limiter.ts -->
The limiter resets its window on every successful call.

The optional symbol after the colon narrows the pointer to an identifier inside the file. Symbol-level pointers give you staleness detection later; file-level pointers only give you ownership. Ask for symbol-level whenever the fact is a constant, and accept file-level for behavioral descriptions.

Step 2: resolve each pointer to an owner

The resolver reads CODEOWNERS with GitHub's last-match-wins precedence, then falls back to the most recent commit author for that path. The fallback matters because plenty of real repositories have files that no pattern covers, and "nobody" is a worse answer than "the person who last touched it".

#!/usr/bin/env python3
"""route_owners.py - provenance ownership gate for model-drafted docs."""
import fnmatch
import re
import subprocess
import sys
from pathlib import Path

FACT = re.compile(
    r"<!--\s*fact:\s*(?P<path>[^\s:>]+)(?::(?P<symbol>[A-Za-z0-9_]+))?\s*-->"
)
CODEOWNER_FILES = (".github/CODEOWNERS", "CODEOWNERS", "docs/CODEOWNERS")


def load_codeowners(root: Path):
    for rel in CODEOWNER_FILES:
        candidate = root / rel
        if candidate.is_file():
            rules = []
            for line in candidate.read_text(encoding="utf-8").splitlines():
                line = line.split("#", 1)[0].strip()
                if not line:
                    continue
                parts = line.split()
                pattern = parts[0].lstrip("/").rstrip("/") or "*"
                rules.append((pattern, parts[1:]))
            return rules
    return []


def owner_for(path: str, rules):
    chosen = None
    for pattern, owners in rules:          # GitHub semantics: last match wins
        if fnmatch.fnmatch(path, pattern) or fnmatch.fnmatch(Path(path).name, pattern):
            chosen = owners
    return chosen or []


def git_author(root: Path, path: str):
    proc = subprocess.run(
        ["git", "-C", str(root), "log", "-1", "--format=%ae", "--", path],
        capture_output=True,
        text=True,
    )
    if proc.returncode != 0:
        return None
    return proc.stdout.strip() or None


def symbol_present(root: Path, path: str, symbol) -> bool:
    if not symbol:
        return True
    source = root / path
    if not source.is_file():
        return False
    return symbol in source.read_text(encoding="utf-8", errors="ignore")


def blocks(draft: str):
    result, pending, buffer = [], [], []
    for line in draft.splitlines():
        hits = FACT.findall(line)
        rest = FACT.sub("", line).strip()
        if hits and not rest:
            pending.extend(hits)
            continue
        if not rest:
            if buffer:
                result.append((" ".join(buffer), pending))
                buffer, pending = [], []
            continue
        buffer.append(rest)
        pending.extend(hits)
    if buffer:
        result.append((" ".join(buffer), pending))
    return result


def main(root: Path, draft_path: Path) -> int:
    rules = load_codeowners(root)
    failures, rows = 0, []
    text = draft_path.read_text(encoding="utf-8")
    for index, (block, facts) in enumerate(blocks(text), start=1):
        if block.startswith("#"):
            continue
        if not facts:
            if re.search(r"\d", block):          # a number with no provenance
                failures += 1
                rows.append((index, "-", "UNMARKED", block[:60]))
            continue
        for path, symbol in facts:
            owners = owner_for(path, rules)
            if not owners:
                fallback = git_author(root, path)
                owners = [fallback] if fallback else []
            if not owners:
                status = "UNOWNED"
            elif not symbol_present(root, path, symbol):
                status = "STALE"
            else:
                status = "OK"
            if status != "OK":
                failures += 1
            rows.append((index, f"{path}:{symbol or '*'}", f"{status} {' '.join(owners)}", block[:60]))

    print("| # | fact | status / owner | sentence |")
    print("|---|---|---|---|")
    for row in rows:
        print(f"| {row[0]} | `{row[1]}` | {row[2]} | {row[3]}... |")
    return 1 if failures else 0


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

The script prints a routing table and exits non-zero on any problem, so it works both as a human briefing and as a CI gate.

Step 3: read the three failure statuses correctly

UNOWNED means the pointer resolved to nothing, which is almost always a wrong path in the marker rather than a missing team. Fix the path first, and only add a CODEOWNERS rule when the path is genuinely legitimate. STALE means the file exists but no longer contains the symbol, which is the cheapest possible signal that a documented constant was renamed or removed. UNMARKED means a paragraph contains a digit and no provenance marker, and that rule is what stops the model from quietly inventing a plausible timeout value.

The staleness check is a substring test, so it can produce false negatives when a symbol name appears in a comment for unrelated reasons. Treat it as a smoke alarm, not a proof: it catches renames, and it will not catch a changed value behind an unchanged name.

Step 4: run it where the drafts are produced

Drafting in bulk only makes economic sense when generation is cheap, which is the case with MonkeyCode's free model access, and the routing job is small enough to sit next to that loop on the free server option rather than on a laptop. Disclosure: This article was prepared as part of MonkeyCode's product outreach. The point of running the gate near the generator is latency: a draft that fails ownership routing should never reach a pull request, because a reviewer who sees an unowned paragraph learns to ignore the table entirely.

# .github/workflows/docs-ownership.yml
name: docs-ownership
on:
  pull_request:
    paths: ["docs/**/*.md"]
jobs:
  route:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # git-log fallback needs history
      - run: python3 tools/route_owners.py . docs/limits.md

fetch-depth: 0 is required, because a shallow clone makes the commit-author fallback return nothing and silently converts owned files into UNOWNED.

Verification: build negative fixtures before trusting the gate

Create three fixture drafts and assert the exit codes, since a gate that has only ever passed has demonstrated nothing about its behavior. An owned fixture should exit 0 with an OK row, a fixture pointing at src/missing.ts should exit 1 with UNOWNED, and a fixture pointing at a deleted symbol should exit 1 with STALE. Add a fourth fixture with a bare number and no marker to confirm UNMARKED fires. Running these four cases locally takes seconds and gives you a defensible claim that the checker works.

Limitations and who should skip this

This approach is a poor fit for repositories where documentation intentionally describes behavior no single file owns, such as conceptual overviews or cross-service architecture narratives. It is also wrong for teams that cannot name owners at all, because the gate will simply produce a wall of UNOWNED rows and get disabled within a week. Single-maintainer projects should skip the CODEOWNERS layer and rely on the git-log fallback alone, which is close to zero configuration. Finally, the fnmatch matching in this script is an approximation of GitHub's path semantics, so translate patterns conservatively and prefer literal directory prefixes over clever globs.

The rule worth keeping is the one that survives tool changes: the model may draft sentences, and a human must own every fact in them. Provenance markers make that rule executable instead of aspirational, and the routing table turns a vague review request into a short list of people who can actually be wrong.

Route Every Drafted Sentence to an Owner: A Claim-Class Gate for Model-Written Docs

Avery Lin — Tue, 27 Oct 2026 15:57:48 +0000

Liquid syntax error: Unknown tag 'endraw'

Make Doc Drafting Idempotent: A Content-Addressed Cache and Stability Gate for Free-Tier Models

Avery Lin — Tue, 27 Oct 2026 13:51:54 +0000

If you run a model over the same documentation twice and get two different diffs, you do not have a pipeline — you have a random number generator attached to your git history. The fix is not a better prompt; it is to make draft generation idempotent, so the same source inputs either produce the same bytes or produce nothing at all. This post builds that: a content-addressed draft cache, a cold-cache stability gate, and an ownership table that says exactly which parts of a page a model may draft and which parts a human must sign.

The pipeline is model-agnostic on purpose. It was designed for the awkward middle case that most teams actually live in: drafting prose with a free-tier model on a scheduled job, with no budget line and no dedicated reviewer. Free-tier availability is treated here only as an operator-supplied starting condition, never as a guarantee of throughput, latency, or permanence.

1. The failure mode: re-run churn

A nightly job drafts forty sections. On Monday it rewrites the wording of nineteen of them even though no source file changed, and reviewers learn to ignore the bot. That churn has three real costs: review attention burned on non-changes, git blame polluted with machine commits, and worse, a genuine correction buried inside cosmetic noise. None of those costs appear in a token bill, which is why the problem survives so long.

The root cause is that drafts have no identity. A section is regenerated from a prompt string, and the prompt string is not the input — the input is the prompt plus the source files it describes. Until you hash the actual inputs, you cannot tell "the model changed" apart from "the docs changed," and you will keep paying for both.

2. The artifact: a section contract and an input fingerprint

Start with a contract file that names each section, its sources, and a human owner. The owner is required, not optional, because the cache proves a draft is reproducible, not that it is correct.

# docs/contract.yml
prompt_version: "v3"
sections:
  - name: install
    mode: draft
    owner: "@avery"
    prompt: "Explain install prerequisites, then the three install paths."
    sources:
      - pyproject.toml
      - scripts/setup.sh
  - name: security-model
    mode: human-only
    owner: "@avery"
    prompt: ""
    sources: []

The fingerprint hashes the prompt version, the prompt text, and the byte content of every declared source. Change any of them and the fingerprint changes; change nothing and you get the same key back.

# docsgen/contract.py
import hashlib, pathlib
from dataclasses import dataclass

@dataclass(frozen=True)
class Section:
    name: str
    prompt: str
    sources: tuple[str, ...]
    owner: str
    mode: str  # "draft" | "human-only"

def fingerprint(sec: Section, prompt_version: str) -> str:
    h = hashlib.sha256()
    h.update(prompt_version.encode())
    h.update(sec.prompt.encode())
    for src in sorted(sec.sources):
        h.update(src.encode())
        h.update(pathlib.Path(src).read_bytes())
    return h.hexdigest()[:16]

Two properties matter here. First, the hash is stable across machines, so a laptop run and a server run agree. Second, human-only sections are declared in the same file, which means the pipeline can assert that no model output ever lands in them.

3. Five steps to an idempotent run

Step 1 — Cache on the fingerprint, not on the section name. A section name is a location; the fingerprint is a content identity. Store both, but key on the fingerprint so old drafts remain addressable after an edit.

# docsgen/cache.py
import sqlite3, pathlib

SCHEMA = """
CREATE TABLE IF NOT EXISTS drafts (
  fingerprint TEXT PRIMARY KEY,
  section     TEXT NOT NULL,
  body        TEXT NOT NULL,
  run_id      TEXT NOT NULL
);
"""

def open_cache(path=".docsgen/cache.sqlite3"):
    pathlib.Path(path).parent.mkdir(parents=True, exist_ok=True)
    con = sqlite3.connect(path)
    con.executescript(SCHEMA)
    return con

def get(con, fp):
    row = con.execute("SELECT body FROM drafts WHERE fingerprint = ?", (fp,)).fetchone()
    return row[0] if row else None

def put(con, fp, section, body, run_id):
    con.execute("INSERT OR REPLACE INTO drafts VALUES (?,?,?,?)", (fp, section, body, run_id))
    con.commit()

Step 2 — Default to diff, not write. The job prints a unified diff and only touches files when --write is passed. Dry-run is the normal mode for scheduled jobs; --write is for the run a human is watching.

Step 3 — Skip human-only sections explicitly. Assert their absence rather than trusting that nobody added one to a prompt list. A one-line check here prevents the worst class of regression, where a policy page quietly becomes machine-drafted.

# docsgen/run.py
import argparse, difflib, json, pathlib, uuid, yaml
from contract import Section, fingerprint
from cache import open_cache, get, put

def render(sec: Section) -> str:
    raise NotImplementedError("wire your model client here; return markdown")

def load(path="docs/contract.yml"):
    raw = yaml.safe_load(pathlib.Path(path).read_text())
    secs = [Section(**s) for s in raw["sections"]]
    return raw["prompt_version"], secs

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--write", action="store_true")
    args = ap.parse_args()
    run_id, changed, spent = uuid.uuid4().hex[:8], [], 0
    version, secs = load()
    con = open_cache()
    for sec in secs:
        if sec.mode == "human-only":
            continue
        fp = fingerprint(sec, version)
        body = get(con, fp)
        if body is None:
            body = render(sec)
            spent += 1
            put(con, fp, sec.name, body, run_id)
        target = pathlib.Path(f"docs/{sec.name}.md")
        old = target.read_text() if target.exists() else ""
        if old == body:
            continue
        changed.append(sec.name)
        if args.write:
            target.write_text(body)
        else:
            print("".join(difflib.unified_diff(
                old.splitlines(True), body.splitlines(True), f"a/{target}", f"b/{target}")))
    print(json.dumps({"run_id": run_id, "changed": changed, "model_calls": spent}))

if __name__ == "__main__":
    main()

Step 4 — Emit a machine-readable run summary. The changed list and model_calls count are the only evidence a reviewer needs, and they make the stability gate below a two-line shell check instead of a bespoke script.

Step 5 — Fail the job when a second pass is not empty. This is the gate that turns an idempotent design into an enforced property.

python -m docsgen.run --write \
  && python -m docsgen.run | tee /tmp/pass2.json \
  && jq -e '.changed == []' /tmp/pass2.json

On a warm cache, pass two must report zero changes with zero model calls. If it reports changes, either the fingerprint is incomplete or something is writing to docs/ outside the pipeline; both are bugs worth stopping the build for.

4. The cold-cache audit you still need

The warm-cache gate proves determinism of your cache, not of the model, and those are different claims. Once a day, or once per prompt-version bump, run the same section twice against an empty cache and diff the two outputs. Three outcomes, three actions:

Cold-cache result	What it means	Action
Byte-identical	Draft is stable enough to automate	Keep it in the scheduled job
Differs in wording only	Prose is unstable but claims agree	Cache it, require human review on refresh
Differs in a claim, number, or code identifier	Contract is underspecified	Demote the section to `human-only`

That third row is why the audit is not optional. A wording difference is a review cost, while a changed number is an incident, and no amount of caching converts the second into the first.

5. Where a free model and a free server actually fit

MonkeyCode is an open-source coding agent project that the operator advertises with free model access and a free server option, and both matter for this specific design rather than as general convenience. The drafting call in render() is the only place a model appears, and the cache means a rate-limited or interrupted run resumes without re-spending tokens on sections already drafted. The free server hosts nothing but a scheduled docsgen job and a sqlite file, which is a small enough footprint to run on modest hardware.

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

Treat the free-tier numbers as volatile. The project page states a token allotment and a free server tier, and those terms should be read there on the day you adopt them rather than from any article, including this one. The engineering point stands either way: a cache keyed on inputs makes an unreliable tier usable, because a failed run costs you a retry and not a corrupted doc tree.

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

The cache answers "is this reproducible." It does not answer "is this right," and the split below is the difference between a pipeline and a liability.

Artifact	Model may draft	Human must own
Prerequisite lists	Yes, from declared sources	Final omission check
Parameter descriptions	Yes, from code and docstrings	Whether the parameter is public
Worked examples	Narration only	The runnable file the example points to
"Supported / not supported" claims	No	Yes, with a primary source
Deprecation dates and version ranges	No	Yes
Security and permission behavior	No	Yes
Section owner and prompt version	No	Yes, in `contract.yml`

Two rules make this table enforceable. First, every row marked "No" gets mode: human-only in the contract, so the pipeline physically cannot write it. Second, every accepted claim gets a source path in sources:, because a claim with no file behind it is exactly the thing a model will happily invent and a reviewer will happily approve.

7. Limitations and who should skip this

The approach assumes your source of truth lives in the repository. If prerequisites are configured in a vendor console, the fingerprint cannot see them, and caching will happily freeze a stale draft forever. It also assumes someone reads diffs: an idempotent pipeline that nobody reviews produces stable, confidently wrong documentation on a schedule.

Skip this if you have no reviewer for docs pull requests, if the page is a security or compliance statement, or if your team cannot maintain a contract.yml. For those cases a single human-written page per quarter beats a nightly job nobody owns. Small teams with one reviewer and a handful of generated pages are the sweet spot; large doc sites will want the same fingerprint idea wired into their existing build rather than a parallel script.

Start with three sections, run the cold-cache audit on each, and demote anything that changes a number. If you want to try it end to end without a billing decision, the free model access and free server option are enough to run the cron job while you evaluate it — bring your own contract.yml and leave the stability gate switched on.

Budget Human Minutes Before You Generate Docs: A Contract-Driven Draft Queue

Avery Lin — Tue, 27 Oct 2026 12:50:57 +0000

The scarce resource in an AI-assisted documentation pipeline is not model output; it is the reviewer minutes you can actually schedule. Free model access makes drafts nearly costless to produce, so pipelines that optimize generation quality often just create a larger unreviewed backlog. A better control point is a per-section contract that decides, before any generation, whether a section is draftable at all and how many minutes its review will consume. The artifact below turns that contract into a sorted queue and exits non-zero whenever an unowned or over-budget section tries to enter the model lane.

1. What the model may draft, and what stays human

The split is not about difficulty; it is about who can be held responsible for the sentence. A model may draft text whose correctness is checkable against an existing artifact: a command that already runs in CI, a config key that exists in the schema, a return type declared in code. A human must own anything that encodes intent, tradeoffs, deprecation promises, security posture, or a claim that no file in the repository can confirm.

That rule is only useful if it is executable, so encode it as a column. Each documentation section gets a lane, a named owner, an estimated review cost in minutes, and a count of claims that need traceable evidence. The model lane is allowed to fill the text; the human lane produces text that a model may only format.

2. Write the section contract as data

Keep the contract as a flat CSV next to the docs, because it diffs cleanly in review and any script can read it. Start with a fixture that intentionally contains one valid draftable section and two that must be refused.

section,lane,owner,review_minutes,claims
quickstart/draft,model,alex,20,2
concepts/auth-model,human,,0,5
reference/api-errors,model,,15,3
guides/migration,model,priya,90,4

The fixture encodes three different failure modes: a human-lane section, a model-lane section with no owner, and a model-lane section whose review cost exceeds a single sitting. Only quickstart/draft should reach the queue.

3. Turn the contract into a queue with a hard stop

The script below uses only the standard library, so it runs identically on a laptop and on any server. It sorts draftable sections by rising review cost, which lets you fill short review windows first instead of opening the most expensive draft last.

#!/usr/bin/env python3
"""Order model-draftable doc sections by the human minutes they will cost."""
import csv
import sys

REQUIRED = {"section", "lane", "owner", "review_minutes", "claims"}
MAX_MINUTES = 45


def load(path):
    with open(path, newline="", encoding="utf-8") as fh:
        rows = list(csv.DictReader(fh))
    if not rows:
        raise SystemExit("empty contract file")
    missing = REQUIRED - set(rows[0].keys())
    if missing:
        raise SystemExit(f"contract missing columns: {sorted(missing)}")
    return rows


def classify(rows):
    draftable, blocked, human = [], [], []
    for row in rows:
        minutes = int(row["review_minutes"])
        if row["lane"] == "human":
            human.append(row)
            continue
        if row["lane"] != "model":
            blocked.append((row["section"], f"unknown lane={row['lane']}"))
            continue
        if not row["owner"].strip():
            blocked.append((row["section"], "no owner"))
            continue
        if minutes > MAX_MINUTES:
            blocked.append((row["section"], f"review_minutes={minutes} > {MAX_MINUTES}"))
            continue
        draftable.append((minutes, row["section"], row["claims"]))
    return draftable, blocked, human


def main(argv):
    if len(argv) != 2:
        raise SystemExit("usage: draft_queue.py <contract.csv>")
    draftable, blocked, human = classify(load(argv[1]))
    for minutes, section, claims in sorted(draftable):
        print(f"DRAFT  {section}  minutes={minutes} claims={claims}")
    for section, reason in blocked:
        print(f"BLOCK  {section}  reason={reason}")
    for row in human:
        print(f"HUMAN  {row['section']}  review_minutes={row['review_minutes']}")
    budget = sum(minutes for minutes, _, _ in draftable)
    print(f"summary draft={len(draftable)} blocked={len(blocked)} "
          f"human={len(human)} budget_minutes={budget}")
    return 1 if blocked else 0


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

Run it against the fixture and compare with the expected output shown below. The non-zero exit code is the important part: the same check can gate a CI job, so a section with no owner cannot silently enter the model lane even if the docs build is green.

python3 draft_queue.py fixture_contract.csv; echo "exit=$?"

DRAFT  quickstart/draft  minutes=20 claims=2
BLOCK  reference/api-errors  reason=no owner
BLOCK  guides/migration  reason=review_minutes=90 > 45
HUMAN  concepts/auth-model  review_minutes=0
summary draft=1 blocked=2 human=1 budget_minutes=20
exit=1

4. Run batches from the queue head, never from the file tree

A scheduled job should read the queue rather than glob a directory, because the queue already encodes the owner and cost decisions. This keeps capacity honest: if the queue is empty, the job does nothing and you have not manufactured review work.

#!/usr/bin/env bash
set -euo pipefail
cd /srv/docs-pipeline
mapfile -t SECTIONS < <(
  python3 draft_queue.py contract.csv | awk '/^DRAFT/{print $2}' | head -n "${BATCH:-2}"
)
for section in "${SECTIONS[@]}"; do
  ./draft_one.sh "$section" >> "drafts/$(date +%F).log" 2>&1 \
    || echo "FAILED $section" >&2
done

This is where a free drafting tier changes the economics: the batch can run on a free server option with free model access, so the cost of a wasted draft is bounded by scheduling noise rather than by tokens. I use MonkeyCode for that layer because the operator supplies free model access and a free server option, and I keep every release-blocking document out of that path regardless. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The draft_one.sh script stays deliberately thin: it reads the section contract row, sends the section's evidence files as context, and writes the output to drafts/<section>.md with the contract row appended as a header comment. Nothing in that script is allowed to overwrite a file outside drafts/, which keeps the human lane physically separate from generated text.

5. Decide in advance what happens when the draft tier is unavailable

Free capacity is best-effort, and a pipeline that blocks on it will eventually stall a release. Write the fallback before you need it, and treat each row as a default action rather than a discussion.

Condition observed	Default action	Human lane impact
Draft request fails twice	Skip section, log to `drafts/failed.log`	None; humans continue on their lane
Draft tier slow beyond your batch window	Lower `BATCH` to 1 and keep the queue intact	None
Draft tier unavailable for the whole run	Publish human-lane sections only, queue stays frozen	Unchanged scope
Draft rejected by review twice	Move section to human lane in the contract	Owner writes the section directly

The last row matters most: repeated rejection is evidence that the section needs intent, not more prompting. Moving it to the human lane records that decision in the same file the pipeline reads.

6. Record the minutes you actually spent

Estimated review cost drifts, so keep a ledger and recalibrate the contract monthly. A five-column CSV is enough, and it converts opinions about drafting speed into a number you can compare across sections.

section,drafted_at,reviewer,minutes,verdict
quickstart/draft,2026-10-05,alex,26,accepted
reference/api-errors,2026-10-05,priya,44,rewritten

Compute the median minutes per lane and compare it with review_minutes in the contract. When the median exceeds the estimate by a wide margin for a section type, raise the estimate and let the queue push that type behind cheaper work. This keeps the budget column honest without any scoring model.

7. Verify the pipeline with three assertions

A short test plan is enough to prove the queue does its job, and it runs in under a second. Feed the fixture to the script and assert on exit code, on sort order, and on the absence of blocked sections in the draft list.

python3 draft_queue.py fixture_contract.csv exits with status 1 because two sections are blocked.
The DRAFT lines appear in ascending minutes order; add a second draftable row at 10 minutes to confirm the sort.
No section with an empty owner appears on a DRAFT line, even after you add more rows.

If all three pass, the model lane cannot absorb unowned work through a contract edit alone, which is the property the pipeline exists to guarantee.

Limitations and who should skip this

The script cannot tell whether a claim is true; it only enforces that someone is accountable for checking it. review_minutes is an estimate that decays as the codebase changes, and the contract itself can drift out of sync with the docs tree unless the CI check runs on every docs change. Free-tier availability is best-effort, so a nightly cron with no fallback will occasionally produce nothing at all. Teams without an owner-per-section habit should not adopt this, because the queue will block everything on day one. Solo maintainers of a handful of pages will find the contract heavier than the docs. Projects with formal audit requirements should keep drafting inside their approved tooling rather than adding a free external tier to the path.

If you want to try it, copy the fixture and the script into the docs repository first, run the three assertions, and only then wire the batch job into a schedule.

Lock the Sentences a Model Must Never Rewrite: A Line-Level Ownership Checker for Docs

Avery Lin — Tue, 27 Oct 2026 09:38:27 +0000

Model-drafted documentation usually fails at the level of one word, not one page. A fluent rewrite can delete a negation, widen a numeric limit, or weaken a modal verb while every surrounding paragraph genuinely improves. Section-level ownership cannot see that kind of edit, because the reviewer checks a heading and the guarantee lives three lines below it.

MonkeyCode's free model access and free server option make a repeated drafting pass cheap enough to run often, which is exactly why the guard rails have to be cheaper still. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The failure mode is a flipped guard word

Generated prose has a recognizable signature: well organized, readable, and wrong by one token. Real examples from review queues look like never becoming generally, at most three times becoming up to three times, or only admin tokens losing the word only. Because the paragraph around the edit reads better than before, reviewers approve the improvement and inherit the constraint.

A section owner answers a social question, namely who looked at this heading. The checker below answers a mechanical question instead, namely whether the text that carries a guarantee is byte-identical after normalization. Those are different properties, and only the second one survives a busy review week.

A delegation table you can argue about

Before writing code, decide which sentence classes a model may draft. The table below is the one I would defend in review; change the rows deliberately rather than by accident.

Sentence class	Model may draft	Human must own	Typical silent failure
Narrative explanation, motivation, background	Yes	Final read only	Tone drift, invented rationale
Numbers copied from config or code	Only via generation from source	The mapping rule	Rounded or stale limits
Negations, exceptions, exclusions	No	Author who knows why	A dropped `not` inverts the contract
Modal verbs such as must, may, should	No	API or security owner	`must` softened to `may`
Preconditions and call ordering	No	Owner of the runtime path	Ordering stated but not enforced
Compatibility and deprecation promises	No	Release owner	Promise survives a version bump

Notice that the human-owned column is small. Most of a page is delegable, and the non-delegable part is usually a handful of sentences that deserve their own review path.

Step 1: mark non-delegable spans in the source

Use an HTML comment pair, require a stable id, and keep one span per guarantee. The id is what the lock file keys on, so renaming it is a deliberate act reviewed like a code change.

<!-- owned:start id=retry-cap -->
The client retries **at most three times** on 5xx responses and never retries a 4xx response.
<!-- owned:end -->

Give the drafting model one instruction and repeat it verbatim: rewrite anything outside owned:start and owned:end, and never emit those markers yourself. If the model deletes a marker instead of the text, the checker below reports marker drift rather than a rewritten guarantee, which is a different failure with a different owner.

Step 2: normalize narrowly, then hash

Normalization decides how much cosmetic change you tolerate. Strip markdown emphasis, collapse whitespace, and stop there. Casefolding is usually safe, but stemming, synonym mapping, or sentence splitting all hide the edits you built the system to catch.

def normalize(s):
    s = re.sub(r'[*_`]', '', s)
    return ' '.join(s.split())

def digest(s):
    return hashlib.sha256(normalize(s).encode()).hexdigest()[:16]

The result is intentionally boring: reflowing a paragraph or removing bold text passes, while changing three to five fails. That split matches how documentation actually gets edited, where formatting churn is frequent and guarantee edits are rare but expensive.

Step 3: the checker, with three exit codes

The script below is standard-library Python and runs in well under a second on a few hundred pages. Exit code 0 means all spans match, 1 means a locked span was rewritten, and 2 means the marker set moved and needs a human decision.

#!/usr/bin/env python3
# tools/owned.py - lock and verify non-delegable doc sentences
import hashlib, json, re, sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
DOCS = ROOT / 'docs'
LOCK = DOCS / 'owned.lock.json'

START = re.compile(r'<!--[ ]*owned:start[ ]+id=(?P<id>[a-z0-9-]+)[ ]*-->')
END = re.compile(r'<!--[ ]*owned:end[ ]*-->')

NEG = {'not', 'no', 'never', 'cannot', 'without', 'nor'}
MODAL = {'must', 'may', 'should', 'shall', 'can', 'will'}
SCOPE = {'only', 'except', 'all', 'any', 'least', 'most', 'always'}

def spans(text):
    found, cur, buf = {}, None, []
    for line in text.splitlines():
        hit = START.search(line)
        if hit:
            cur, buf = hit.group('id'), []
            continue
        if END.search(line) and cur:
            found[cur] = ' '.join(buf)
            cur = None
            continue
        if cur is not None:
            buf.append(line)
    return found

def normalize(s):
    s = re.sub(r'[*_`]', '', s)
    return ' '.join(s.split())

def digest(s):
    return hashlib.sha256(normalize(s).encode()).hexdigest()[:16]

def classes(s):
    toks = re.findall(r'[a-z0-9]+', normalize(s).lower())
    return {
        'neg': sorted({t for t in toks if t in NEG}),
        'modal': sorted({t for t in toks if t in MODAL}),
        'num': sorted({t for t in toks if t.isdigit()}),
        'scope': sorted({t for t in toks if t in SCOPE}),
    }

def scan():
    out = {}
    for path in sorted(DOCS.rglob('*.md')):
        for sid, text in spans(path.read_text()).items():
            out[sid] = {
                'file': str(path.relative_to(ROOT)),
                'sha': digest(text),
                'cls': classes(text),
            }
    return out

def main(argv):
    mode = argv[1] if len(argv) > 1 else 'check'
    force = '--force' in argv
    lock = json.loads(LOCK.read_text()) if LOCK.exists() else {}
    current = scan()

    if mode == 'seal':
        blocked = [k for k, v in lock.items()
                   if k in current and current[k]['sha'] != v['sha']]
        if blocked and not force:
            print('reseal needs owner review, then --force:', ', '.join(blocked))
            return 2
        LOCK.write_text(json.dumps(current, indent=2, sort_keys=True) + '\n')
        print('sealed', len(current), 'spans')
        return 0

    drift = sorted(set(current) ^ set(lock))
    if drift:
        print('marker drift:', ', '.join(drift))
        return 2

    failed = 0
    for sid, entry in current.items():
        if entry['sha'] == lock[sid]['sha'] and entry['file'] == lock[sid]['file']:
            continue
        failed += 1
        print('FAIL', sid, entry['file'])
        for k in ('neg', 'modal', 'num', 'scope'):
            lost = set(lock[sid]['cls'][k]) - set(entry['cls'][k])
            gained = set(entry['cls'][k]) - set(lock[sid]['cls'][k])
            if lost or gained:
                print('  ', k, 'lost', sorted(lost), 'gained', sorted(gained))
    print('checked', len(current), 'spans,', failed, 'rewritten')
    return 1 if failed else 0

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

Storing the four token classes in the lock file is what makes a failure readable without keeping a copy of the prose. The lock file stays small, and a failing run tells the reviewer which class moved instead of only that a hash differs.

Step 4: read the failure output first, then the diff

When a rewrite is caught, the output names the mechanism rather than the location. A run against a seeded change to the retry sentence above should print something close to the block below.

FAIL retry-cap docs/concepts/retry.md
   neg lost ['never'] gained []
   num lost ['3'] gained ['5']
checked 14 spans, 1 rewritten

That output is the review ticket. The reviewer opens one sentence, confirms whether the change was intended, and either reverts it or re-seals the lock in a commit that a human authored. Nothing in this loop requires reading the whole page again, which is the actual time saving.

Step 5: sealing is a human commit

A lock that the drafting process can update is decoration. Make seal refuse to overwrite a changed span without an explicit --force, and add a workflow step that rejects any pull request touching the lock file before a human has reviewed the change.

# CI step for docs pull requests
if git diff --name-only "origin/$GITHUB_BASE_REF..." | grep -qx 'docs/owned.lock.json'; then
  echo 'lockfile edited in a draft PR: needs a separate human seal commit'
  exit 1
fi
python tools/owned.py check

Two commits are better than one here: the model-authored rewrite, then the human seal. That ordering leaves an audit trail naming the person who accepted the new guarantee, which is the only part of this system that cannot be automated away.

Step 6: a mutation test plan for the checker

The table below is a plan, not a measured result, and it takes about ten minutes to execute against the script above. Seed each edit by hand, run the checker, and record the exit code; if any row disagrees with your implementation, the normalizer is too permissive.

Seeded edit	Expected detection	Exit code
`at most three` becomes `up to five`	hash mismatch, num lost 3, gained 5	1
`never retries` becomes `rarely retries`	neg lost `never`	1
`must call init` becomes `may call init`	modal lost `must`, gained `may`	1
`only admin tokens` becomes `admin tokens`	scope lost `only`	1
bold removed, line reflowed	normalized text equal	0
marker pair moved to another file	file field differs, reported as FAIL	1
marker pair deleted	marker drift	2

Keep this table in the repository next to the script. When someone later proposes a looser normalizer, the seed rows are the argument, and a passing mutation run is much harder to dismiss than a policy document.

Where the free model and free server actually fit

Use the free drafting pass for the delegable majority and keep the locked spans out of its write scope. On the free server option, clone the repository to a scratch directory, run the drafting pass there, and let the model execute python tools/owned.py check on its own output before any human looks at it.

PASS 1: rewrite docs/concepts/retry.md. Do not emit or edit text between
        owned:start and owned:end markers. Do not edit docs/owned.lock.json.
PASS 2: list every owned span you wanted to change, with a one-line reason.
        Do not apply those changes.

The second pass is the useful one, because it turns silent rewrites into a review queue. In practice the model often proposes a legitimate update such as a new default timeout, and the request arrives as text a human can accept or reject instead of as a diff mixed into prose.

I have not measured throughput, cost, or model quality here, and free-tier terms change. Treat the availability of free model access and the free server as operator-supplied information and re-verify it against current terms before you build a workflow around it.

Limitations and who should skip this

Small documentation sets with one maintainer gain little, because the review problem the lock solves does not exist yet. Teams whose guarantees change every sprint will generate seal churn and should start with two or three spans, not twenty. Repositories without CI cannot enforce the seal step and should not pretend the lock file is a control.

Marketing copy and tutorials with no contractual claims fit poorly, since almost nothing in them is worth hashing. Multilingual documentation needs the check to run per locale, or the translation becomes an unguarded edit path. Finally, this workflow protects sentences you remembered to mark, and no script can find the guarantee you never wrote down.

If you try this on a real documentation repository, the first useful artifact is not the passing check but the first FAIL line, because it names a guarantee that was already being edited without review.

Lock the Glossary Before the Model Writes: A Term-Contract Checker for Docs Drafts

Avery Lin — Tue, 27 Oct 2026 06:31:21 +0000

Most model-drafted docs pages fail on nouns, not on sentences. The prose reads fine, the code samples compile, and then a reader discovers that the page calls the same object a "workspace", a "project space", and a "tenant" in three consecutive paragraphs. Grammar review never catches this, because each sentence is locally correct. The failure lives at the vocabulary layer, and that layer belongs to a human.

This post describes a workflow I use for that layer: a human-owned glossary file, a draft contract that forces the model to flag concepts it cannot name, and a small lexical checker that fails a pull request when a draft renames something it was told to leave alone. The model drafts prose and examples; the human owns every definition, every allowed spelling, and every decision to admit a new term. The checker is a heuristic, not a semantic tool, and I will be explicit about where it stops being useful.

The failure mode that survives review

Renaming is cheap for a model and expensive for a reader. A model that has seen the word "tenant" in a thousand other projects will reach for it when the source page says "workspace", and nothing in the prompt forbids it unless the prompt carries a vocabulary contract. Human reviewers skim for wrong claims and broken links, so a synonym slips through in exactly the kind of low-attention pass that model-drafted pages receive. Two weeks later the search index contains both spellings, and support tickets use a third.

The fix is not a longer style guide. Style guides are prose, and prose is what the model is already good at generating around. The fix is a machine-readable list of terms with allowed forms, banned forms, and a named owner, so that both the drafter and the CI job read the same source of truth.

Step 1: Write the glossary as a human-owned lockfile

The glossary is a file in the repository, reviewed like code, and never written by the model. I keep it in TOML because it parses with the standard library and diffs cleanly in review.

# docs/glossary.toml — human-owned. The model may read this file; it may not edit it.
[terms.workspace]
definition = "A named container for projects, members, and billing."
allowed  = ["workspace", "workspaces"]
banned   = ["project space", "work area", "tenant"]
owner    = "@avery"

[terms.run]
definition = "One execution of a workflow, identified by run_id."
allowed  = ["run", "runs"]
banned   = ["job", "task", "execution"]
owner    = "@avery"

[terms.member]
definition = "A person with an account in a workspace."
allowed  = ["member", "members"]
banned   = ["user", "seat", "account holder"]
owner    = "@sam"

Three fields carry the weight. definition is what a human signs off on, and it is the only place a concept is allowed to mean something. banned is the list of near-misses the model is most likely to produce, drawn from your own review history rather than from imagination. owner matters because a glossary with no owner decays into a second style guide that nobody reads.

Keep the first version small. Twelve to twenty terms covering the objects on your most-visited pages will catch more drift than an exhaustive list assembled in one sitting and never updated.

Step 2: Give the drafter a contract with an escape hatch

A model told "use the approved terms" will still guess when it meets a concept that has no entry. Give it a legal way to say "I do not know what to call this" and the guessing drops sharply. I put this contract in the prompt and also commit it as docs/draft-contract.md so a reviewer can see what the model was told.

You are drafting one documentation page. Read docs/glossary.toml first.

1. Use only the `allowed` spelling for each glossary term. Never use a `banned` variant.
2. If a concept has no glossary entry, do not invent a name. Insert the inline
   marker [TERM_NEEDED] where the concept first appears.
3. At the end of the draft, emit a section titled OPEN TERM with one line per
   marker: `[TERM_NEEDED] <phrase you would have used> — <why it is needed>`.
4. Do not modify docs/glossary.toml. Do not add definitions of your own.
5. Fenced code blocks must come from a file that exists in the repo; cite the path.

Rule 3 is the part people skip, and it is the part that makes the workflow economical. Instead of a draft full of confident wrong nouns, you get a draft with a short, bounded queue of naming decisions waiting for a human. Naming a concept is a design decision, and design decisions do not belong in a generated paragraph.

Step 3: Check the draft with a lexical gate

The checker does one thing: it fails when a banned variant appears outside a fenced code block. It runs in milliseconds, needs no API key, and produces line numbers a reviewer can jump to.

#!/usr/bin/env python3
"""tools/termcheck.py — fail a docs draft that renames human-owned terms."""
import pathlib
import re
import sys
import tomllib

GLOSSARY = pathlib.Path("docs/glossary.toml")
FENCE = re.compile(r"```

.*?

```", re.S)


def load_terms():
    data = tomllib.loads(GLOSSARY.read_text(encoding="utf-8"))
    return data["terms"]


def check(path, terms):
    raw = path.read_text(encoding="utf-8")
    text = FENCE.sub("", raw)          # never police code samples
    lowered = text.lower()
    problems = []
    for term, spec in terms.items():
        for variant in spec.get("banned", []):
            pattern = rf"\b{re.escape(variant.lower())}\b"
            for match in re.finditer(pattern, lowered):
                line = text.count("\n", 0, match.start()) + 1
                problems.append(
                    f"{path}:{line}: banned variant {variant!r} for term {term!r}"
                )
    return problems


def main(argv):
    terms = load_terms()
    files = [pathlib.Path(p) for p in argv[1:]]
    problems = [p for f in files for p in check(f, terms)]
    for line in problems:
        print(line)
    print(f"termcheck: {len(problems)} violation(s) in {len(files)} file(s)")
    return 1 if problems else 0


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

The fence-stripping line is not cosmetic. Without it, every CLI example containing the flag --user becomes a violation, and the team turns the check off within a week. Policing prose and policing code are different jobs, so keep them in different passes.

Run it against only the files a pull request touched, which keeps the signal local to the change:

git diff --name-only origin/main...HEAD -- 'docs/**/*.md' \
  | xargs python3 tools/termcheck.py

Step 4: Run the loop where the draft lives

A draft-and-check loop is only cheap if the environment is disposable. I run the generation pass, the checker, and a Markdown link check inside a remote workspace rather than on my laptop, which is where MonkeyCode's free model access and free server option come into this workflow.

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

The relevant part is not the drafting itself; it is that the feedback loop is quick enough to run on every page instead of on a weekly batch. The model reads docs/glossary.toml and docs/draft-contract.md, writes one page plus an OPEN TERM list, and the checker decides whether the result reaches a human. I keep the glossary and the contract in the repository either way, so the workflow survives a change of tooling, and I treat availability as something to confirm for your own account rather than a permanent guarantee.

Review the OPEN TERM list before anything else, because it is the highest-value artifact in the output. Each entry is either a genuine gap in the glossary or a sign that the model misread the page, and both are worth two minutes of a human's attention. Accept an entry by adding a term to the lockfile with a definition and an owner, then discard the draft's temporary phrasing.

Step 5: Separate what the model drafts from what a human owns

The table below is the working boundary I use. It is deliberately conservative at the edges where a wrong noun becomes a wrong contract.

Artifact	Model	Human
Page prose, transitions, headings	Drafts	Edits
Code samples	Copies from cited repo files	Confirms the file exists and runs
Glossary definitions	Never writes	Writes and signs off
Allowed and banned variants	Never writes	Writes after review
OPEN TERM entries	Proposes	Accepts or rejects
Page-level claims about behavior	Drafts with citations	Verifies against source
Removing a deprecated term	Never	Human, with a redirect plan

Limitations and who should not use this

The checker is lexical. It catches the variants you listed and nothing else, so a model that invents an entirely new synonym for an unlisted concept passes cleanly. It also says nothing about whether a definition is correct, whether a page is complete, or whether two teams mean the same thing by the same word.

Do not adopt this if you have fewer than roughly ten stable domain terms, because the lockfile costs more to maintain than the drift it prevents. Do not adopt it for marketing or tutorial prose, where synonyms are a feature and the vocabulary is intentionally loose. Do not gate a merge on the banned list during the first week either, since the initial run will surface legitimate uses in quoted text and historical changelogs; fix those, then turn the check into a required status.

One optional extension is worth the effort once the base check is quiet: extract capitalized multiword phrases from the draft and report any that have no glossary entry.

CANDIDATE = re.compile(r"\b(?:[A-Z][a-z]+(?:\s+[A-Z][a-z]+){1,2})\b")

Expect noise from sentence starts and product names, so treat the output as a review aid and never as a failing check. The moment a heuristic produces false failures, reviewers stop reading it.

If you try one thing from this post, make it the lockfile plus the OPEN TERM rule; the checker can come later, and the naming decisions will still land in front of a human instead of inside a generated paragraph.

Make the Draft Refuse: An Abstention Ledger for Model-Written Docs

Avery Lin — Tue, 27 Oct 2026 03:26:18 +0000

Most teams measure a model-written doc page by what it contains, which is the wrong signal to optimize first. The cheaper, earlier signal is where the draft refused to answer, because a refusal is a named human decision waiting to happen. This article describes a workflow I use for documentation generation with a strict split: the model may draft prose, structure, and cross-links, while a human must own every command, version number, limit, and interface guarantee. The artifact is an abstention ledger — a marked-up draft plus a parser that turns refusals into an assignment table your review can act on.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. The drafting pass described below is one place where MonkeyCode's free model access fits (availability as described by the operator; verify current terms before depending on it), and the free server option is only relevant if you want the check reachable from CI without a self-hosted runner.

The failure mode is silent confidence, not bad prose

A generated page usually fails in one of two directions, and only one of them is visible in review. The visible failure is a placeholder like TODO or a dangling link, which a reviewer catches in seconds. The expensive failure is a sentence that reads perfectly, asserts a version pin or a rate limit, and is simply not true. Reviewers skim prose for tone and miss those assertions, because nothing in the sentence signals that it needs verification.

Forcing abstention inverts that default. Instead of asking the model to be cautious in prose, you give it a syntactic obligation: when a claim depends on a fact it cannot cite from your repository, it must emit a marker and stop. The marker converts an invisible risk into a countable object with a line number and an owner.

Step 1 — Contract the draft with a marker the parser can read

Write the marker once in the system prompt and keep it stable across drafting runs. HTML comments survive Markdown rendering, so they disappear from the published page while remaining greppable in the source. The three required fields are deliberately minimal, because every extra field is another thing the model can get wrong.

When a sentence would need a fact you cannot cite from the provided files,
replace the claim with exactly this comment and continue:

<!-- NEEDS id="<short-slug>" owner="<team-or-person>" question="<one question>" -->

Do not guess the fact. Do not soften it with "typically" or "usually".
Emit the marker and move on.

A drafting run that produces zero markers across a long page is a warning, not a success. It usually means the model absorbed unstated assumptions from its training data instead of from your repository, and those assumptions are exactly the ones a reviewer cannot check quickly.

Step 2 — Parse the draft into a routing table

The parser does two jobs: it extracts every marker, and it finds silent assertions — version numbers, shell commands, URLs, and unit-bearing figures that appear without a marker. The ratio between those two counts is the metric used in Step 4.

#!/usr/bin/env python3
"""abstention.py: turn a model-drafted page into a review routing table."""
from __future__ import annotations

import json
import re
import sys
from dataclasses import asdict, dataclass
from pathlib import Path

MARKER = re.compile(r"<!--\s*NEEDS\s+(?P<body>[^>]*?)-->", re.S)
FIELD = re.compile(r'(?P<key>[a-z_]+)\s*=\s*"(?P<val>[^"]*)"')

RISK = {
    "version": re.compile(r"\bv?\d+\.\d+(?:\.\d+)?\b"),
    "command": re.compile(r"^\s*(?:\$ |npm |pip |docker |curl |git )", re.M),
    "url": re.compile(r"https?://[^\s)]+"),
    "quantity": re.compile(r"\b\d+(?:\s?%|\s?ms|\s?MB|\s?GB|\s?rps)\b"),
}


@dataclass(frozen=True)
class Need:
    line: int
    id: str
    owner: str
    question: str


def parse_needs(text: str) -> list[Need]:
    needs: list[Need] = []
    for match in MARKER.finditer(text):
        fields = {f["key"]: f["val"] for f in FIELD.finditer(match["body"])}
        missing = {"id", "owner", "question"} - fields.keys()
        if missing:
            raise ValueError(f"marker at line offset {match.start()} missing {sorted(missing)}")
        line = text.count("\n", 0, match.start()) + 1
        needs.append(Need(line, fields["id"], fields["owner"], fields["question"]))
    return needs


def silent_assertions(text: str) -> list[dict]:
    hits: list[dict] = []
    for kind, pattern in RISK.items():
        for match in pattern.finditer(text):
            hits.append({
                "kind": kind,
                "line": text.count("\n", 0, match.start()) + 1,
                "text": match.group(0).strip()[:80],
            })
    return hits


def build_report(text: str) -> dict:
    needs = parse_needs(text)
    bare = silent_assertions(text)
    by_owner: dict[str, list[str]] = {}
    for need in needs:
        by_owner.setdefault(need.owner, []).append(need.id)
    return {
        "lines": text.count("\n") + 1,
        "needs": [asdict(n) for n in needs],
        "by_owner": by_owner,
        "silent_assertions": bare,
        "abstention_density": round(len(needs) / max(len(bare), 1), 3),
        "unowned": [n.id for n in needs if n.owner.lower() in {"", "tbd", "docs"}],
    }


def main(argv: list[str]) -> int:
    report = build_report(Path(argv[1]).read_text(encoding="utf-8"))
    json.dump(report, sys.stdout, indent=2)
    sys.stdout.write("\n")
    return 2 if report["unowned"] else 0


if __name__ == "__main__":
    raise SystemExit(main(sys.argv))

Run it as a normal check and keep the exit code meaningful, so CI fails on unowned markers rather than on aesthetics:

python abstention.py docs/queue.md > abstention-report.json
echo "exit=$?"   # 2 means at least one marker has owner="", "tbd", or "docs"

Pin the behaviour with a small fixture instead of trusting the regex by inspection. The test below is the one I keep next to the script; it is deliberately boring, because a parser that surprises you is worse than no parser.

# test_abstention.py
from abstention import build_report

DRAFT = '''
Set the retry window to 30s.
<!-- NEEDS id="retry-window" owner="platform" question="What is the default retry window?" -->
Run `npm i pkg@2.4.1` before starting.
'''


def test_counts_marker_and_silent_assertions():
    report = build_report(DRAFT)
    assert [n["id"] for n in report["needs"]] == ["retry-window"]
    kinds = {hit["kind"] for hit in report["silent_assertions"]}
    assert "version" in kinds and "command" in kinds
    assert report["unowned"] == []


def test_rejects_malformed_marker():
    import pytest
    from abstention import parse_needs
    with pytest.raises(ValueError):
        parse_needs('<!-- NEEDS id="x" -->')

Step 3 — Route each need to an owner, not to "the docs team"

The parser is only useful if owner maps to someone who can answer in one message. Reject generated owners like docs, team, or tbd in the contract itself, and let the exit code enforce it. The table below is a template; replace the middle column with the roles that actually exist in your repository's ownership file.

Marker subject	Owner to name	Human decision that cannot be delegated
Version pins, dependency ranges	Release or build owner	Which version is supported today, and which is deprecated
Limits, quotas, timeouts	Service owner	The enforced value, plus whether it is configurable per plan
CLI flags and exit codes	Maintainer of the command	Whether the documented flag is public or internal
Compatibility statements	API or SDK owner	The support window and its start date
Cross-links to other pages	Docs maintainer	Whether the target page is canonical or scheduled for removal

Two rules keep this from decaying into a second backlog. First, every marker must resolve into either a sentence with a citation in the page or a linked registry entry. Second, resolved markers are deleted, never left in place as commentary, so the ledger always reflects open work only.

Step 4 — Gate the re-draft on abstention density

Abstention density is markers divided by silent assertions, and it is a prompt-quality signal rather than a quality score for the page. A low density means the model asserted facts it could not source, which usually points to a prompt that omitted the repository context it needed. A very high density with few assertions means the draft is thin and probably dropped sections you expected, which a heading-coverage diff will confirm.

Use it as a routing decision, not a number to chase:

density < 0.3 and assertions present: re-draft with narrower scope and the specific files attached, rather than sending it to review.
density >= 0.3 with assertions clustered in one section: send that section to its owner first and hold the rest.
Zero markers on a page longer than roughly 150 lines: treat as suspicious and diff the headings against the previous version before reading prose.
Markers whose questions repeat across two drafts: the fact belongs in the registry, not in the prompt.

Step 5 — Feed resolved needs back into the registry

The last step closes the loop, and it is the one teams skip. When an owner answers a marker question, write the answer as a dated entry in the facts file the drafting prompt already receives, then delete the marker. The next draft starts with one fewer unknown, so the ledger shrinks instead of resetting every release.

This is also where the free-server option is worth considering: exposing abstention.py as a small endpoint lets a webhook run the check on a pull request without provisioning a machine for it. If that is more moving parts than your team wants, a pre-commit hook calling the same script is equivalent, and the ledger does not care which one you pick.

What this does not fix

Abstention markers catch ungrounded claims, not wrong ones: a model can cite a stale file and produce a confidently sourced error. The approach also says nothing about structure, tone, or whether the page answers the reader's actual question. And it adds real friction — every marker is a human round-trip, so a page with twenty markers can take longer than writing it by hand.

Skip this workflow when the model already has a narrow, tested context: a generated reference page rebuilt from a schema, a changelog assembled from merged pull requests, or any page where examples are extracted from executed test files. In those cases the facts are already constrained, and a marker layer mostly adds ceremony. Skip it too if your repository has no ownership file, because routing needs an owner that exists.

If you try one thing from this article, make it the contract in Step 1 and the exit code in Step 2 — a draft that names its own gaps is easier to review than a fluent one that hides them.

Your Docs Gate Has Never Failed, So It Proves Nothing: Mutation-Testing a Model-Drafted Page

Avery Lin — Tue, 27 Oct 2026 00:21:04 +0000

A documentation gate that has only ever printed pass is not evidence of quality; it is evidence that nobody has tried to break it. Before you let a free model draft a page into a review queue, spend twenty minutes proving that your checks actually reject bad drafts. This post builds a small gate, then a mutation harness that injects known defects and asserts the gate fails on each one. The conclusion up front: the mutation sheet, not the gate, is the artifact that tells you which parts of the page a human still has to own.

1. The failure mode this fixes

Most AI-drafting pipelines fail in the same quiet way: the checker looks for things the model already produces. If your gate only verifies that headings exist and links resolve, then a draft that invents a version number and deletes a data-loss warning will pass with a green check. The reviewer then reads a green check instead of reading the section, and the deletion ships.

Mutation testing gives you a cheap way to measure that blindness. You take a draft that legitimately passes, introduce one defect at a time, and require the gate to exit non-zero for every single mutation. Any mutation that survives marks a rule you believed in but never implemented.

Mutation	Defect class	Gate rule that must catch it
M1	Command altered after testing	Command must appear in `tested_commands`
M2	Version swapped	Version must appear in `versions`
M3	Human-owned block emptied	Human block must be non-empty
M4	Safety caveat deleted	Required human phrases must exist
M5	Example replaced with placeholder	Every command must be tested

2. Decide ownership before any drafting happens

Write the ownership split down once, then encode the machine-checkable half of it. The table below is the split I keep coming back to, because each row on the right is something a model writes fluently and gets wrong silently.

Section type	Model may draft	Human must own
Install and quickstart	Yes, from tested commands	Command list, prerequisites
Concept explanations	Yes, from registered facts	Boundaries and non-goals
Error and recovery guidance	Yes, structure only	Exact messages, data-loss warnings
Deprecation and migration	No	Dates, ordering, support window
Security and permissions	No	Threat model, caveats, review sign-off
Pricing, SLA, support scope	No	Every sentence

Two rules fall out of this table and they drive the whole pipeline. First, anything in the right column must be physically present in the draft as a marked block, so deletion is detectable. Second, anything in the left column must trace back to a file that runs, so invention is detectable.

3. Build the gate: five rules, five exit conditions

The gate reads one draft page and one facts file, and it does not care which model wrote the prose. Keep it dependency-free so it runs anywhere a free server can run Python.

#!/usr/bin/env python3
# tools/check_docs.py
import json, re, sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
PAGE = ROOT / "docs/draft.md"
FACTS = json.loads((ROOT / "docs/facts.json").read_text(encoding="utf-8"))

FENCE = re.compile(r"```

[a-zA-Z0-9]*\n(.*?)

```", re.S)
COMMAND = re.compile(r"^\$ (.+)$", re.M)
VERSION = re.compile(r"\b\d+\.\d+(?:\.\d+)?\b")
HUMAN_BLOCK = re.compile(r"<!-- owner: human -->\n(.*?)\n<!-- /owner -->", re.S)

def check(text: str) -> list[str]:
    errors = []
    blocks = FENCE.findall(text)
    if not blocks:
        errors.append("D1: no fenced blocks; page cannot be verified")
    for block in blocks:
        for cmd in COMMAND.findall(block):
            if cmd.strip() not in FACTS["tested_commands"]:
                errors.append(f"D2: untested command: {cmd.strip()}")
    for version in sorted(set(VERSION.findall(text))):
        if version not in FACTS["versions"]:
            errors.append(f"D3: unregistered version: {version}")
    humans = [b.strip() for b in HUMAN_BLOCK.findall(text)]
    if not humans:
        errors.append("D4: no human-owned block found")
    if any(not b for b in humans):
        errors.append("D4: empty human-owned block")
    for phrase in FACTS["required_human_phrases"]:
        if phrase not in text:
            errors.append(f"D5: missing caveat: {phrase[:40]}")
    return errors

if __name__ == "__main__":
    errs = check(PAGE.read_text(encoding="utf-8"))
    print("\n".join(errs) or "pass")
    sys.exit(1 if errs else 0)

The matching facts file is small on purpose, because every entry is a promise you have to maintain:

{
  "tested_commands": ["pytest -q", "python tools/check_docs.py"],
  "versions": ["3.11", "20.11.1"],
  "required_human_phrases": [
    "Do not run this against production data.",
    "Backups are kept for 30 days."
  ]
}

4. Mark the human-owned region in the draft itself

Put the ownership marker in the page rather than in a side manifest, so deletion shows up in the same diff a reviewer reads. The marker is an HTML comment, which renders as nothing on DEV or GitHub but is trivially greppable in CI.

<!-- owner: human -->
Do not run this against production data.
Backups are kept for 30 days.
<!-- /owner -->

Give the model exactly this instruction: you may write around the block, you may not edit inside it, and if the block looks misplaced you must stop and report it. That single constraint removes the most expensive review failure, which is a model politely rewriting a warning into something friendlier and less true.

5. Number the steps and keep the draft in a fixed shape

Write docs/facts.json from the test suite, not from memory.
Write the human-owned blocks yourself, before the prompt, in the empty draft.
Ask the model for prose only, with the block contract above.
Run python tools/check_docs.py and fix commands rather than prose.
Run the mutation harness and require every line to print caught.
Review the diff, then publish; never publish from the draft directory.

6. The mutation harness is the real test

The harness copies the draft, applies one textual defect, and asserts a non-zero exit. It restores the file in a finally block, because a crashed run must not leave a mutated page behind for the next person.

#!/usr/bin/env python3
# tools/mutate_docs.py
import subprocess, sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
DRAFT = ROOT / "docs/draft.md"
GATE = ROOT / "tools/check_docs.py"

MUTATIONS = {
    "M1_untested_command": lambda t: t.replace("$ pytest -q", "$ pytest -q --all", 1),
    "M2_version_swap": lambda t: t.replace("Python 3.11", "Python 3.9", 1),
    "M3_empty_human": lambda t: t.replace(
        "Do not run this against production data.", "", 1),
    "M4_drop_caveat": lambda t: t.replace("Backups are kept for 30 days.", "", 1),
    "M5_placeholder": lambda t: t.replace("$ pytest -q", "$ <your test command>", 1),
}

def gate_rc() -> int:
    return subprocess.run([sys.executable, str(GATE)], capture_output=True).returncode

def main() -> int:
    original = DRAFT.read_text(encoding="utf-8")
    survivors = []
    try:
        if gate_rc() != 0:
            print("M0_baseline=fail — fix the draft before mutating")
            return 2
        print("M0_baseline=pass")
        for name, mutate in MUTATIONS.items():
            DRAFT.write_text(mutate(original), encoding="utf-8")
            caught = gate_rc() != 0
            print(f"{name}={'caught' if caught else 'SURVIVED'}")
            if not caught:
                survivors.append(name)
    finally:
        DRAFT.write_text(original, encoding="utf-8")
    if survivors:
        print(f"survivors: {', '.join(survivors)}")
    return 1 if survivors else 0

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

The baseline line matters more than the rest. If M0_baseline fails, every later caught is meaningless noise, so treat a red baseline as a stop condition rather than a warning. Run the harness on every change to the gate, and treat a surviving mutation as a bug report against the rules, not against the draft.

7. What the harness still cannot see

Surviving mutations are honest, but passing mutations are not proof of a safe page. Five defect classes have no mechanical check in this design: whether a warning is strong enough for the risk, whether a deprecation date is politically acceptable, whether migration ordering is correct for real upgrade paths, whether the tone suits an incident postmortem, and whether a caveat was omitted entirely rather than deleted.

Keep those five on a written human checklist attached to the pull request. The gate's job is to make sure the reviewer spends attention on judgement calls instead of on verifying that pytest -q still exists.

8. Limitations and who should skip this

This pipeline assumes you can express facts as files, and that assumption fails in several common situations. Teams without a runnable source of truth will spend more time maintaining facts.json than reviewing pages. Pages dominated by narrative, positioning, or opinion gain nothing from command and version rules. Documentation under regulatory or contractual review often needs per-sentence citation, which this gate does not provide. Single README projects should stay with a human reviewer and a link checker.

There is also a maintenance cost that is easy to underestimate: every new tested command, version, and required caveat is a line somebody must keep true. Budget that work explicitly, or the facts file becomes the new stale doc.

9. Where a free model and a free server fit

Drafting prose from a fixed facts file and a marked block contract is low-risk model work, and it is the part worth automating first. I used MonkeyCode's free model access to produce the prose-only drafts and its free server option to run the gate and the mutation harness in a throwaway environment before opening a review. Disclosure: This article was prepared as part of MonkeyCode's product outreach. Availability and limits of the free tiers are whatever the operator currently offers, so confirm them yourself rather than reading them into this post. If you already have a CI runner you trust, use that instead; the harness has no dependency on any particular model or host.

Churn-Gated Doc Drafting: Let the Model Write Only Sections Whose API Surface Has Settled

Avery Lin — Mon, 26 Oct 2026 21:15:51 +0000

A model should draft a documentation section only when the exported surface that section describes has stopped moving, and every other section should stay human-owned with an explicit anchor. That single rule replaces the vague question "what can the model write?" with two measurements you can compute from git and from your compiler's own output. The workflow below turns those measurements into a gate that runs in CI, so drafting rights are decided by data instead of by whoever is impatient that afternoon.

The core insight is that documentation risk tracks API volatility far more than it tracks prose difficulty. A glossary paragraph about a service that shipped three breaking changes this quarter is riskier than a nuanced explanation of a function that has not changed in a year. Most teams already have the evidence for that asymmetry in their commit history; they simply never join it to their docs.

Step 1: Write the anchor map by hand, once

The anchor map is the human-owned input to the whole system, and it is the only file a model is never allowed to edit. Each section of each page points at one symbol and one source file, and it declares an ownership status.

# docs/anchors.yml
pages:
  rate-limits.md:
    sections:
      retry-policy:
        package: "./pkg/retry"
        symbol: "pkg/retry.Client.Do"
        file: "pkg/retry/client.go"
        status: drafted
      error-codes:
        package: "./pkg/retry"
        symbol: "pkg/retry.ErrCodes"
        file: "pkg/retry/errors.go"
        status: human
        human_notes: "Error strings are contractual; only the owner edits this table."

The status field has exactly two legal values, drafted and human, and demoting a section is always allowed while promoting one requires a clean gate run. The human_notes field is where reviewers record the answer to any question the model raised, which keeps decisions next to the anchor instead of buried in a pull request thread. Keep this file small: one anchor per section, no wildcards, no inheritance.

Step 2: Fingerprint the public surface, not the file

A file hash is useless here, because formatting and comments churn constantly while the contract stays stable. Fingerprint the exported declarations instead, which requires filtering the tool output rather than hashing it raw.

#!/usr/bin/env bash
set -euo pipefail
pkg="$(go list ./pkg/retry)"
go doc -all "$pkg" \
  | grep -E '^(func|type|var|const|\t[A-Z][A-Za-z0-9_]*)' \
  | sed 's/[[:space:]]\+/ /g' \
  | sha256sum | cut -d' ' -f1

The filter is the whole trick. go doc -all includes doc comments, so hashing it unfiltered makes the fingerprint change on every comment edit and the gate becomes noise within a week. Restricting the hash to declaration lines means a renamed parameter, a changed return type, or a new exported constant flips the fingerprint, while prose cleanup does not.

Step 3: Measure churn over a fixed window

Churn is a count of commits touching the defining file inside a rolling window, and it is deliberately cheap to compute.

git log --since="180 days ago" --pretty=format:%H -- pkg/retry/client.go | wc -l

Use one window for the whole repository so the numbers stay comparable, and write the window into the gate output so reviewers see the basis of the decision. A threshold of 180 days works for libraries with quarterly releases and should shrink for services that deploy daily. The exact number matters less than applying it uniformly.

Step 4: Apply the drafting rights table

The table below is the decision surface, and it is the part you should argue about with your team before automating anything.

Churn (commits / window)	Surface fingerprint	Model may draft	Human must own
0–2	unchanged since last receipt	full section prose, glossary, cross-links	final review, error semantics, examples
3–9	unchanged since last receipt	intro paragraph, terminology, navigation prose	tables, defaults, deprecation notes, anything numeric
≥10	any value	outline only, labeled `PROPOSAL`	the entire section
any value	changed since last receipt	nothing	rewrite plus re-anchoring

Four categories stay human-owned no matter what the numbers say: error message meaning, permission and security boundaries, deprecation promises, and numeric limits. Those are the claims readers act on and the claims that generate support tickets when they drift. A model can restate them once a human has written them, but it should never be the origin.

Step 5: Enforce the drafting contract with refusal tokens

The prompt is short because the gate has already done the scoping work. The model receives one section, the source excerpt for that symbol, and a requirement to refuse rather than guess.

Draft exactly one documentation section.
Section id: {{section_id}}
Anchor symbol: {{symbol}} (surface fingerprint {{fp}})
Allowed output: prose only.
Forbidden: inventing flags, defaults, error strings, limits, or version numbers.
If a required fact is absent from the source excerpt, emit a line:
NEEDS_HUMAN: <one-line question>

Every NEEDS_HUMAN line becomes a review task, and the reviewer's answer is appended to human_notes on the anchor so the next draft has it. This is where a free drafting tier pays off, because the volume of low-risk sections is high and the gate caps the downside of any single bad draft. In this workflow MonkeyCode's free model access covers the low-churn drafting tier, and its free server option is where the gate script can run if you do not want a laptop awake at night; verify current availability and terms yourself, since free offerings change.

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

Step 6: Fail the build on drift

The gate is a single script, and it fails for exactly two reasons: a drafted section whose surface fingerprint moved, or a drafted section that crossed the churn threshold.

#!/usr/bin/env python3
import hashlib, json, pathlib, subprocess, sys, yaml

def surface_fp(pkg):
    out = subprocess.run(["go", "doc", "-all", pkg], check=True,
                         capture_output=True, text=True).stdout
    keep = [l for l in out.splitlines()
            if l.startswith(("func", "type", "var", "const")) or l.startswith("\t")]
    norm = [ " ".join(l.split()) for l in keep if l.strip() ]
    return hashlib.sha256("\n".join(norm).encode()).hexdigest()

def churn(path, days=180):
    out = subprocess.run(["git", "log", f"--since={days} days ago",
                          "--pretty=%H", "--", path],
                         check=True, capture_output=True, text=True).stdout
    return len([l for l in out.splitlines() if l.strip()])

anchors = yaml.safe_load(pathlib.Path("docs/anchors.yml").read_text())
failures = []
for page, spec in anchors["pages"].items():
    rec_path = pathlib.Path("docs/.draft-receipts") / f"{page}.json"
    receipt = json.loads(rec_path.read_text()) if rec_path.exists() else {}
    for sec, a in spec["sections"].items():
        fp, c = surface_fp(a["package"]), churn(a["file"])
        prev = receipt.get(sec, {}).get("fingerprint")
        if a["status"] == "drafted":
            if prev and prev != fp:
                failures.append(f"{page}#{sec}: surface changed {prev[:8]} -> {fp[:8]}")
            if c >= 10:
                failures.append(f"{page}#{sec}: churn {c} >= 10, must be human-owned")
        receipt.setdefault(sec, {}).update(
            fingerprint=fp, churn=c, symbol=a["symbol"])
    rec_path.parent.mkdir(parents=True, exist_ok=True)
    rec_path.write_text(json.dumps(receipt, indent=2))
    print("\n".join(failures) or "anchors ok")
    sys.exit(1 if failures else 0)

This is a reference implementation rather than a battle-tested tool, and it has a known rough edge: it rewrites receipts even when the run fails, so commit receipts explicitly or move the write behind a --record flag. The Go-specific filtering also needs a per-language equivalent, which for TypeScript means hashing declaration output instead of go doc.

Limitations and who should skip this

A fingerprint proves the declaration changed, not that the meaning changed, so a semantics-only edit in a function body will pass the gate while making the prose wrong. Churn is a proxy for volatility, not a measure of consequence, and a low-churn internal helper can still be load-bearing for thousands of readers. The gate also cannot see documentation that lives outside symbol-anchored prose, such as tutorials, migration guides, and runbooks, which need separate ownership rules.

Skip this approach if your API is pre-1.0, because almost everything will land in the human-owned row and the automation earns nothing. Skip it if your docs must carry a formal audit trail that a JSON receipt cannot satisfy, or if you cannot send source excerpts to a hosted model without a policy review. Skip it too if your team has no CI, since a gate that runs only when someone remembers is a suggestion rather than a gate.

Start narrow: pick one high-traffic page, add three anchors, and run the gate in report-only mode for two weeks to see how often fingerprints actually move. The threshold table will need adjusting, and the honest answer to "what may the model draft" will come from your own churn data rather than from any article, including this one.

Review Cost Per Section Decides Who Drafts It: A Stop Rule for Model-Assisted Docs

Avery Lin — Mon, 26 Oct 2026 18:10:34 +0000

Cheaper drafting does not make documentation cheaper; it moves the bill from writing minutes to review minutes. The practical stop rule is therefore economic rather than stylistic: measure what reviewing a section costs relative to writing it by hand, and let that ratio decide which sections a model may draft and which stay human-owned. This post gives the ledger schema, a small runnable script that assigns draft rights, a unit test for the rule, a CI gate for the whole page, and the cases where you should not adopt any of it. Every number in the fixture below is synthetic and labeled as such, so you can drop in your own review data without inheriting my assumptions.

Why review time is the honest budget

When a draft costs nothing, the only scarce resource left in the loop is a reviewer's attention, and attention is spent per claim rather than per page. A 900-word concept page with two contested statements can consume more senior time than a 200-word reference stub with none, which means word count is the wrong denominator for planning. Review minutes per section survive tooling changes, because they are measured from artifacts you already produce: comments, resolved threads, and the edits that changed a factual statement rather than a comma.

The rule I use has three outcomes instead of two, because "model drafts it" and "human owns it" are not the only options on a real docs team. A section can be freely drafted, drafted behind a named checkpoint, or reserved for a human author from the first sentence. The thresholds below are starting values, and you should treat them as calibration targets rather than universal constants.

The ledger: four numbers per section

Each row describes one reviewable unit, and a unit should be a section with a single owner and a single topic. words is the rendered length, review_minutes is time spent on that section in review, and blockers counts comments that changed a factual claim. human_minutes is the measured time to write the same section by hand, and it is the anchor that keeps the ratio meaningful across teams.

{
  "page": "docs/concepts/queue.md",
  "captured_at": "2026-10-24",
  "sections": [
    {"path": "overview",   "words": 320, "review_minutes": 9.0,  "blockers": 0, "human_minutes": 75.0},
    {"path": "delivery",   "words": 410, "review_minutes": 22.0, "blockers": 1, "human_minutes": 80.0},
    {"path": "limits",     "words": 180, "review_minutes": 34.0, "blockers": 3, "human_minutes": 55.0},
    {"path": "migration",  "words": 260, "review_minutes": 41.0, "blockers": 2, "human_minutes": 70.0}
  ]
}

Those four rows are invented to make the rule visible; replace them with exported review timings before you believe any verdict. The interesting row is limits, which is the shortest section and the most expensive to review, because short sections about behavior attract exactly the claims nobody can verify quickly.

Step 1: capture the baseline once per page

You need human_minutes only once per section, and a timeboxed reconstruction is good enough for a first pass. Ask an engineer to write that section on a throwaway branch from the same sources, stop at the same level of detail, and record the elapsed minutes in the ledger with the capture date. Store the date because baselines decay when the subject matter changes, and a stale baseline silently inflates or deflates every verdict downstream.

Step 2: instrument review minutes per section

Most review tools already timestamp comments, so approximate attribution is cheap: assign each comment thread to the section it touches and sum the gap between the first and last human reply. Exclude bot comments, exclude pure formatting threads, and keep a separate blockers count for threads that changed a claim. If your tooling cannot attribute a thread, put it in an unattributed bucket instead of guessing, and report that bucket in the output so the ratio never looks more precise than it is.

Step 3: assign draft rights with a script

The artifact below is standard-library Python, keeps thresholds in named constants, and returns a machine-readable verdict per section plus a page-level ratio. It is deliberately small so a reviewer can read the whole rule in one sitting.

# draftcost.py — assign draft rights per docs section from review cost
from __future__ import annotations

import json
import sys
from dataclasses import dataclass
from pathlib import Path

BUDGET_RATIO = 0.40      # page review minutes / page hand-written minutes
FREE_RATIO = 0.15        # section may be drafted without a checkpoint
CHECKPOINT_RATIO = 0.50  # above this, a human writes the section
BLOCKER_HARD_STOP = 2


@dataclass(frozen=True)
class Section:
    path: str
    words: int
    review_minutes: float
    blockers: int
    human_minutes: float


def per_100w(words: int, minutes: float) -> float:
    if words <= 0:
        raise ValueError(f"words must be > 0, got {words}")
    if minutes < 0:
        raise ValueError(f"minutes must be >= 0, got {minutes}")
    return minutes / words * 100.0


def assign(section: Section) -> str:
    if section.human_minutes <= 0:
        raise ValueError(f"{section.path}: human_minutes must be > 0")
    ratio = section.review_minutes / section.human_minutes
    if section.blockers >= BLOCKER_HARD_STOP or ratio > CHECKPOINT_RATIO:
        return "human_owned"
    if section.blockers >= 1 or ratio > FREE_RATIO:
        return "model_with_checkpoint"
    return "model_free"


def load(path: Path) -> list[Section]:
    raw = json.loads(path.read_text(encoding="utf-8"))
    return [Section(**row) for row in raw["sections"]]


def main(argv: list[str]) -> int:
    ledger_path = Path(argv[1])
    sections = load(ledger_path)
    rows = [
        {
            "path": s.path,
            "review_per_100w": round(per_100w(s.words, s.review_minutes), 2),
            "ratio": round(s.review_minutes / s.human_minutes, 3),
            "blockers": s.blockers,
            "verdict": assign(s),
        }
        for s in sections
    ]
    total_review = sum(s.review_minutes for s in sections)
    total_human = sum(s.human_minutes for s in sections)
    page_ratio = total_review / total_human
    print(json.dumps(
        {"sections": rows, "page_ratio": round(page_ratio, 3), "budget": BUDGET_RATIO},
        indent=2,
    ))
    return 0 if page_ratio <= BUDGET_RATIO else 1


if __name__ == "__main__":
    raise SystemExit(main(sys.argv))

Run it against the fixture and check the exit code, because the exit code is the part CI reads.

python draftcost.py ledger.json; echo "exit=$?"

With the synthetic fixture the page ratio exceeds the 0.40 budget, so the script exits non-zero and the page fails its gate. That is the intended behavior: the rule is supposed to tell you that this particular page is cheaper to write by hand than to review.

Step 4: pin the rule with tests

A rule that lives only in CI configuration drifts, so keep two assertions that encode the intent of each boundary. These tests use only unittest and run in milliseconds, which makes them safe to keep in the docs repository itself.

# test_draftcost.py
import unittest

from draftcost import Section, assign, per_100w


class DraftCostTest(unittest.TestCase):
    def test_zero_words_is_rejected(self):
        with self.assertRaises(ValueError):
            per_100w(0, 12.0)

    def test_low_cost_no_blockers_is_model_free(self):
        s = Section("overview", 320, 4.0, 0, 75.0)
        self.assertEqual(assign(s), "model_free")

    def test_blockers_force_human_ownership(self):
        s = Section("limits", 180, 6.0, 3, 55.0)
        self.assertEqual(assign(s), "human_owned")

    def test_expensive_section_is_human_owned(self):
        s = Section("migration", 260, 41.0, 0, 70.0)
        self.assertEqual(assign(s), "human_owned")


if __name__ == "__main__":
    unittest.main()

python -m unittest -v test_draftcost.py

The decision table you can argue about

Section profile	Review ratio	Blockers	Verdict	Who signs off
Restates config names, links a test	<= 0.15	0	`model_free`	Any reviewer on rotation
Explains behavior with one contested word	0.15–0.50	1	`model_with_checkpoint`	Named section owner
Anything about limits, security, or timing	any	>= 2	`human_owned`	Human writes from scratch
Long but mechanical reference	<= 0.15	0	`model_free`	Any reviewer on rotation
Migration steps	any	>= 1	`human_owned`	Human writes from scratch

What the model may draft, and what a human owns

The table is only useful if it maps onto content types, because nobody assigns draft rights to a ratio in the abstract. A model may draft restatements of values that already exist in source, prose that describes a signature with a linked definition, and explanations of an error whose message is produced by a test. A model may draft under checkpoint the sections that describe observable behavior but depend on one team-specific term.

A human must own every statement about safety, defaults, deprecation timelines, supported versions, data handling, and migration order. Those claims fail quietly and expensively, and their review cost is high precisely because they cannot be validated from the repository alone. The ratio is a detector for that failure mode, not a substitute for judgment about which category a sentence belongs to.

Where free model access and a free server actually fit

If drafting runs on free model access, the generator can be a disposable job rather than a permanent resident, which changes the security posture more than it changes the cost. The free server option is useful for exactly that shape of work: a short-lived container that checks out the repository, drafts the sections marked model_free, and exits without holding long-lived credentials. That least-privilege argument is the real reason I would run the draft step remotely instead of on a laptop with a personal token. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Treat the availability of free model access and a free server as operator-supplied and time-sensitive rather than guaranteed; verify current terms before you put either behind an automated job. Do not send confidential drafts, unpublished security notes, or customer-specific content to any free endpoint without an explicit review of the terms in force that day. The workflow above degrades gracefully to local models, because the only interface it needs is "given a section outline and registered sources, return prose."

Limitations and who should not use this

The measurement overhead can exceed the savings on small docs sets, so a team publishing a handful of pages per quarter should skip the ledger and review everything by hand. Teams without timestamped review data should not fabricate review_minutes, because invented inputs make the verdicts look authoritative while being arbitrary. Pages whose sections cannot be attributed to a single owner will produce noisy ratios, and pages with volatile subject matter need their human_minutes baseline refreshed on a schedule.

Finally, the rule optimizes for predictable review cost, not for documentation quality, and those goals diverge whenever a page is strategically important but cheap to review. Use the ratio to allocate attention and to escalate contested sections, then keep a human decision on the pages that carry the most risk. If you try the ledger on one page this week, start by recording blockers honestly, since that single integer changes more verdicts than any threshold you tune.