Where May the Model Draft? A Delegation Boundary for Generated Docs

#ai #documentation #git #workflow

Free model access makes drafting cheap, but the cost simply moves to review: unless the workflow defines where the model may write, the human reviewer carries all the risk. A delegation boundary turns that problem into a machine-readable region map with a CI gate, and this article builds that gate with a small YAML file plus a short Python script. The workflow keeps model drafting useful while keeping human ownership explicit, and it does not depend on any quota or benchmark number.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. It uses that product's free model access and free server option as an example backend, but the gate works with any model endpoint that can write into a Git checkout.

Cheap Drafts, Expensive Review

Unconstrained generated docs create pull requests that are faster to produce and slower to review, because every generated line still asks a human to verify its meaning. For a thousand lines of fluent prose, "trust but verify" becomes no verification at all, and that is how stale examples and silent API changes get merged. Code generation has a safety net that documentation does not: the compiler. The delegation boundary is a small substitute for that net, and it must exist before the first prompt is sent.

The Delegation Rule File

The boundary is one YAML file that maps paths to regions and states what may enter each region:

# doc-boundary.yaml
version: 1
rules:
  - pattern: "guides/**"
    boundary: model_draft
    require: review
  - pattern: "api/reference/**"
    boundary: human_owned
    require: approval

Files that match no rule default to human_owned, which means the gate treats any change there as unauthorized unless an approval marker is present. The model can draft freely inside guides, but if it produces several thousand lines under api/reference, the gate fails before a human sees the diff. This is not an ownership manifesto; it is a scope-control mechanism for a docs-generation workflow.

The Gate: A Checker, Not a Compiler

The script reads the Git diff, matches every changed Markdown file against the first matching rule, and fails on any human-owned path that lacks an approval marker:

# docboundary.py
import sys, yaml
from pathlib import Path
from subprocess import check_output

APPROVAL = "[[human-approved]]"

def changed_md():
    out = check_output(["git", "diff", "--name-only", "main", "HEAD"])
    return [f for f in out.decode().splitlines() if f.endswith(".md")]

def rule_for(path):
    rules = yaml.safe_load(Path("doc-boundary.yaml").read_text())["rules"]
    for r in rules:
        if Path(path).match(r["pattern"]):
            return r
    return {"boundary": "human_owned", "require": "approval"}

def main():
    failures = []
    for path in changed_md():
        text = Path(path).read_text()
        rule = rule_for(path)
        if rule["boundary"] == "human_owned" and APPROVAL not in text:
            failures.append(f"{path}: human-owned change without approval")
    if failures:
        sys.exit("\n".join(failures))
    print("boundary OK")

if __name__ == "__main__":
    main()

The checker is deliberately dumb: it parses no semantics, understands no sentences, and verifies no claims. Its only job is to classify changes by region and mark whose burden is on the table. When the marker is missing, the reviewer knows exactly which lines were produced outside the agreed boundary, and the review effort becomes measurable instead of infinite.

A Five-Step Docs Generation Workflow

Protect doc-boundary.yaml and main so changing a region silently requires a human review.
Wire a drafting backend to the guides/** area; MonkeyCode's free server option and free model access fit here as a local, freely reachable backend, and the gate stays independent of that choice.
Ask the model to draft only inside the allowed areas and to list every touched file in a ## Draft Summary section.
Run docboundary.py in CI or as a pre-commit hook; the gate rejects boundary crossings before merge.
Approve reviewed sections explicitly and record the date:

echo "[[human-approved]] $(date -u +%F)" >> api/reference/client.md

This sequence converts "who may write what" into a check that every commit runs. Cost now has a structure: model drafts are cheap, manual corrections are visible per file, and the human owns only what the boundary map calls human-owned.

Decision Matrix

Directory	Drafting allowed	Required before merge
`guides/**`	model draft	static gate + reviewer
`api/reference/**`	no model access	boundary gate + approval marker
`changelog/**`	model for patch listing	source-linked verification

The matrix works because the YAML file and the Python script are no larger than the scope they protect. When a new docs area appears, the team makes one explicit choice: widen a region or leave the file under human ownership.

Limits and Who Should Skip This

A boundary decides provenance, not correctness, because the gate knows who wrote a line but not whether the line is true. Behavioral changes, security notes, and API contracts still need human review before anyone sees the model output; the marker cannot replace the reviewer. The setup also demands repo discipline, since any maintainer can rewrite the YAML, and an unwatched rule file quickly becomes decoration. For fast experiments, short READMEs, or non-docs work, this gate is overkill, and adding it is cost without benefit. Teams that build long-running customer documentation should still keep requirements work human-owned, then apply the boundary to the drafting step, not to the product decisions.

If your review queue motivates this, start with a minimal two-rule boundary and one pre-commit hook; the benefit shows once the backlog lets you see what is generated, not just what is merged.

DEV Community