Setting Boundaries for AI Drafts: A Document Ownership Escalation Ladder and Commit Gate

Title

Setting Boundaries for AI Drafts: A Document Ownership Escalation Ladder and Commit Gate

Meta Description

Introducing a repo-native document ownership mechanism: use four triggers—reach, churn, impact, and irreversibility—to classify sections as model-writable or human-owned, then use a Drafted-By git trailer gate to prevent the model from modifying beyond its bounds. Includes a complete Python scoring script and GitHub Actions configuration ideas, suitable for documentation repositories with PR CI.

Article Content

The biggest risk with AI-generated documentation isn't that it's wrong—it's that no one remembers which parts were written by a machine. A model generates a section on authentication in March, someone edits two sentences in April, and by June no one can say whether the token-expiration logic was ever actually verified. This article introduces a repo-native document ownership mechanism: use four computable triggers to classify sections as "model-writable" or "human-owned," then use a git trailer gate to prevent the model from modifying beyond its bounds.

Why "Ownership" Is More Reliable Than "Gating Every Generation"

The draft gate answers a single-generation question: is this output acceptable? The ownership table answers a question that persists across runs: is this section allowed to be model-generated at all? The former is a filter; the latter is a boundary. Filters get forgotten; boundaries get enforced.

The actual failure mode is "silent promotion": a model-drafted section gets a couple of human touch-ups, and over time a piece of machine text that was never truly verified becomes de facto "human documentation." Placing an HTML comment above each section to mark ownership, and adding a trailer to the commit, makes that history searchable via git grep instead of relying on word of mouth.

Step One: Define the Four Escalation Triggers

Triggers are only useful if a script can evaluate them unambiguously. The original article gives four, each mapped to an installed command, with thresholds written in the script rather than in a wiki—so a threshold change shows up in code review.

• Reach: the section anchor appears in three or more source or example files. High reach means an incorrect sentence will propagate into user code.
• Churn: the file containing the section has been changed more than three times in the past 90 days. Frequent changes mean the underlying behavior is still evolving.
• Impact: the anchor appears in a hand-maintained reference list of support tickets or incident postmortems. This is the only subjective input, kept minimal in a reviewed JSON file.
• Irreversibility: the section covers installation, authentication, security, migration, or billing. A reader who follows incorrect steps cannot undo them at low cost, so this trigger escalates on its own.

The decision rule is mechanical: irreversibility escalates on its own; any two of the other three hitting escalates. Hitting only one trigger keeps the section model-writable, which keeps the human-owned set small enough that it will actually get read.

Git trailer is a set of Key: Value metadata lines at the end of a Git commit message, such as Signed-off-by: Alice <alice@example.com>, usually separated from the commit body by a blank line. Git natively supports the git interpret-trailers command to parse and add trailers, git log --format=%(trailers:key=Drafted-By) to filter output by key, and git commit --trailer to write them. The Linux kernel's Signed-off-by is the most famous application, used to record code provenance and the chain of responsibility. This article borrows that mechanism to turn "this content was drafted by a model" into a structured fact that git log, git grep, and CI scripts can mechanically search, rather than an easily overlooked free-text note.

HTML comment ownership markers rely on a Markdown feature: <!-- ... --> is ignored by browsers when rendered to HTML and does not appear on the published page, but is fully preserved in the source file and in diffs. Compared with recording ownership via YAML front matter or a sidecar manifest, the advantage of inline comments is that ownership information sits right next to the section—reviewers reading a diff don't need to jump to a second file, and git blame can directly locate the change history of the marker. The cost is that it double-writes with the derived manifest, so the article requires the gate to fail outright when the two disagree.

Step Two: Score Sections from Repo Data

The scoring script walks the docs directory, extracts headings as anchors, evaluates the triggers one by one, and outputs a single JSON manifest for subsequent steps to consume. The original article provides a reference implementation whose core logic is:

flags = {
    "reach": code_refs(slug) >= REACH_MIN,
    "churn": churn(path, slug) >= CHURN_MIN,
    "impact": slug in impact,
    "irreversible": any(word in slug for word in IRREVERSIBLE),
}
secondary = sum(flags[k] for k in ("reach", "churn", "impact"))
owner = "human" if flags["irreversible"] or secondary >= 2 else "model"

The churn function runs git show once per commit, which suits a nightly job but not a pre-commit hook. If you need to run it on every push, cache patch text by SHA. The first run on a repository with large history will be noticeably slower.

Step Three: Mark Ownership in the Body Text

The manifest tells CI what the rule produced, but reviewers shouldn't have to open a second file for it. Place an HTML comment above each section declaring ownership, and have the gate cross-check the manifest as a derived artifact. The comment is invisible on the published page and also passes Markdown lint.

<!-- owner:human anchor:auth-tokens -->
## Rotating API tokens

<!-- owner:model anchor:list-supported-regions -->
## Supported regions

If the manifest and the inline markers disagree, the gate should fail outright rather than pick a winner. A disagreement means someone hand-edited the manifest, or made substantial content changes and forgot to rescore—either case warrants a human look before the model touches the page again.

Step Four: Lock Model Drafts with a Trailer

Ownership only truly takes effect when a violating commit cannot be merged. Tag machine-assisted commits with a Drafted-By trailer, and have the gate map each changed line range in the PR back to the nearest preceding ownership marker. Git's --trailer flag is available in newer versions; older clients can manually append the same two lines to the message body.

git commit -m "docs: regenerate model-owned reference sections" \
  --trailer "Drafted-By: model" \
  --trailer "Draft-Run: 2026-10-17T09:00Z"

The gate script first checks whether Drafted-By is model; if not, it skips immediately. For model-draft commits, it parses the hunks from git diff --unified=0 origin/main...HEAD -- docs and judges the ownership of the section each modified line belongs to. Unmarked sections default to human, which means new pages must explicitly decide owner:model to be rewritten by batch jobs. This default is deliberately a bit annoying, because only an annoying version survives a busy week.

The accompanying CI configuration only needs to check out and run python3 tools/doc_gate.py on PRs.

Diff hunks and line-range mapping are the technical core of this gate. git diff --unified=0 outputs a minimal patch with zero context; each hunk header looks like @@ -12,3 +12,5 @@, meaning 3 lines starting at line 12 in the old file and 5 lines starting at line 12 in the new file changed. After parsing these ranges, the gate script must walk upward in the HEAD version of the document to the nearest <!-- owner:... --> comment and determine which section each changed line falls into. Edge cases need special handling: a newly added file has no preceding marker and defaults to human; deleting an entire section may also delete the ownership marker itself, so the pre-deletion version should be used; and a hunk spanning sections must be split into multiple line ranges judged separately. Implementation typically uses git diff --unified=0 -U0 | grep '^@@' or Python's unidiff library to parse, which is more robust than hand-rolling regex.

Step Five: Only Draft Model-Owned Sections

The nightly job reads docs/ownership.json, filters for owner == "model", and regenerates only those sections from source inputs. The original author mentions running this batch process on MonkeyCode's free model quota, making the marginal cost of full regeneration zero, with the scheduler on a free server option so failed retries cost nothing.

Since the free tier offers no availability guarantee, the job must be written to be idempotent and restartable: write to a branch rather than main, and reread the manifest on every run to ensure sections already escalated by the scorer are not regenerated.

python3 tools/doc_owner_score.py
git checkout -B docs/auto-refresh
python3 tools/draft_model_sections.py --manifest docs/ownership.json --out docs/
git commit -am "docs: regenerate model-owned reference sections" \
  --trailer "Drafted-By: model"

Idempotent and restartable batch processing here is not a stylistic preference but a hard constraint of free scheduling environments. Idempotent means the same input executed repeatedly produces the same result, so the script treats the manifest as the single source of truth, writes to a fixed-named branch docs/auto-refresh rather than main, and rereads docs/ownership.json at the start of each run to avoid overwriting sections already escalated to human by the scorer with a stale snapshot from a previous run. Restartable means the job can continue from any point after interruption; a common approach is to force-reset the branch with git checkout -B before each run instead of incrementally appending to an old branch. No availability guarantee on the free tier means timeouts or reclamation can happen at any time, and if retries incur costs or side effects things spiral; idempotent design reduces retries to pure replay. This is consistent with the general CI pattern of "don't land build artifacts on main—merge them via PR."

The Escalation Table at a Glance

Reach	Churn	Impact	Irreversible	Owner	Review Action
Any	Any	Any	Yes	human	Read changes line by line
Yes	Yes	No	No	human	Read changes line by line
Yes	No	Yes	No	human	Read changes line by line
No	Yes	Yes	No	human	Read changes line by line
Yes	No	No	No	model	Skim diff, check anchors
No	No	No	No	model	Skim diff, check anchors

When a section flips from model to human, the flip itself is the deliverable. Open a small PR that only changes the ownership comment and regenerates the manifest, giving the escalation its own review moment rather than hiding it in a large regeneration diff.

Limitations and Applicable Boundaries

The four triggers are heuristics, not a correctness measure. A section could score zero on every axis and still be wrong. The scoring script assumes anchors are stable; renaming a heading resets the churn history and quietly demotes a section that deserved attention. Repositories with fewer than about twenty doc pages will find the table's overhead exceeds the review time it saves.

If compliance requires every sentence of documentation to have a named human author, skip this mechanism—the whole tree is human-owned and the gate devolves into always failing. Skip it without PR CI too; a trailer no one enforces is just a line in a commit message.

The thing most worth tuning first is the trigger thresholds, not the code. Lower REACH_MIN to 2 on a small public API surface, observe how many sections flip to human, and then decide whether to automate downstream processes.

One-line Summary

Use four computable triggers to classify document section ownership and a git trailer gate to prevent the model from modifying beyond its bounds.

Paragraph Summary

The article points out that the biggest risk with AI-generated documentation is ambiguous ownership, not incorrect content—model drafts patched sporadically by humans get silently promoted into de facto "human documentation." It proposes a repo-native ownership mechanism: score each section with four scriptable triggers—reach, churn, impact, and irreversibility—where irreversibility escalates on its own and any two of the rest escalate, outputting a JSON manifest; mark ownership inline with HTML comments in the body, with the gate failing outright when manifest and markers disagree; then use a Drafted-By git trailer combined with diff hunk line-range mapping to prevent model-draft commits from modifying human-owned sections; and have a nightly job regenerate only model-owned sections, running idempotently and restartably. The article also explains the boundaries of this heuristic: renaming anchors resets churn history, small repositories see insufficient benefit, and without CI the whole mechanism breaks down.