Declare the Doc Boundary: A Zone-Based CI Gate for AI-Generated Documentation

AI-generated documentation becomes safe when the ownership boundary is declared in code and enforced by CI, not negotiated in every review. Over the past week, multiple developer discussions asked what a human still does while AI writes code. For documentation, the same question has a more precise answer: the reviewer no longer checks grammar, they check whether the model overstepped a boundary that was never defined. This article proposes a zone-based delegation matrix and a repository script that fails a build when an AI draft appears where a human should own the words.

The example below uses two free resources: MonkeyCode's free model access for drafting the low-risk zones and its free server option for running the boundary check on a schedule. Disclosure: This article was prepared as part of MonkeyCode's product outreach. No model names, quotas, or uptime guarantees are implied; check the current documentation for exact limits.

The delegation matrix

The core idea is simple: split documentation into three zones, each with an explicit ownership rule. A green zone contains stable, low-judgment text that the model may draft without human verification beyond a light proofread. A yellow zone contains instructional material where the model can produce a useful first version, but every factual claim needs human verification. A red zone contains decisions, guarantees, and consequences where the human must be the sole author; the model is never even prompted for that text.

Zone	Who owns the output	Typical sections	Review required
Green	Model drafts, human merges	API references, parameter tables, setup commands	Light proofread
Yellow	Model drafts, human verifies	Tutorials, troubleshooting, migration notes, examples	Fact-check each claim
Red	Human writes, model never drafts	Security considerations, compatibility promises, pricing, legal, reliability	Full human authorship

The matrix works because the boundaries are explicit and visible. Teams that rely on a one-line rule like AI drafts everything, human reviews usually fail because the review load becomes a blunt instrument. The zone model turns ownership into a routing decision that can be automated.

Encoding the contract in the repository

Create a docs/delegation.yaml file at the root of your documentation tree. This file is the single source of truth for which paths belong to which zone and what markers the script should look for.

zones:
  green:
    paths:
      - 'docs/reference/**'
      - 'docs/api/**'
    marker: 'AI-DRAFT'
  yellow:
    paths:
      - 'docs/tutorials/**'
      - 'docs/guides/**'
    marker: 'AI-DRAFT'
  red:
    paths:
      - 'docs/security/**'
      - 'docs/legal/**'
      - 'docs/compatibility/**'
    marker: 'FORBIDDEN'

Every AI-generated snippet, regardless of zone, must start with an HTML comment that contains AI-DRAFT. A yellow-zone file is considered verified only after a human adds a REVIEWED comment immediately below the draft. Red-zone files must never contain AI-DRAFT; if they do, the build fails.

The boundary check script

The script below loads the delegation contract, scans files from a git diff, and applies the zone rules. It is deliberately small so it can run anywhere: locally, in a GitHub Action, or on a free server scheduled with cron.

#!/usr/bin/env python3
'''Fail a PR if an AI draft appears in a zone the human must own.'''
import sys
import pathlib
import yaml

def load_zones(path):
    data = yaml.safe_load(path.read_text())
    return [(zone, pathlib.Path(p), cfg['marker'])
            for zone, cfg in data['zones'].items()
            for p in cfg['paths']]

def zone_for(file, zones):
    for zone, prefix, marker in zones:
        if file.is_relative_to(prefix):
            return zone, marker
    return 'unknown', None

def main(change_list):
    zones = load_zones(pathlib.Path('docs/delegation.yaml'))
    errors = []
    for change in change_list:
        f = pathlib.Path(change)
        if not f.is_file() or f.suffix not in {'.md', '.mdx'}:
            continue
        zone, marker = zone_for(f, zones)
        text = f.read_text()
        if zone == 'red' and 'AI-DRAFT' in text:
            errors.append(f'{f}: AI draft found in {zone} zone')
        if zone == 'yellow' and 'AI-DRAFT' in text and 'REVIEWED' not in text:
            errors.append(f'{f}: yellow zone needs REVIEWED marker')
    if errors:
        print('\n'.join(errors))
        sys.exit(1)
    print('Boundary check passed')

if __name__ == '__main__':
    main(sys.stdin.read().splitlines())

The script expects the changed file list on standard input. In CI, feed it the output of git diff --name-only HEAD.... On a free server, you can run the same command in a cron job that checks the main branch every hour and posts a comment if the boundary is violated.

Workflow: five steps to a guarded documentation process

1. Define the zones with the team. Schedule a thirty-minute session to list every documentation directory and assign each to green, yellow, or red. The output of that session is delegation.yaml.
2. Send only green and yellow prompts to the model. For red sections, write by hand or do not write them at all. Never include a red-zone filename in a prompt.
3. Paste the model output with the AI-DRAFT marker. The marker is the key that lets the CI script identify generated text.
4. Run the boundary check before every merge. Either in your PR pipeline or in the cron job, the script produces a clear failure when a red file hides an AI draft or a yellow file lacks the REVIEWED comment.
5. Review only yellow files, and only for substance. The human's job shrinks to fact-checking claims in yellow zones and authoring red zones. Green zones receive a quick proofread, not a line-by-line negotiation.

That last step is where the reviewer role finally gets a proper test. Instead of wondering whether a paragraph came from a model, the reviewer sees the AI-DRAFT comment and knows exactly what to check.

Limitations and who should not use this approach

The boundary check enforces placement, not truth. A green-zone API reference can still contain a hallucinated parameter, and the script cannot detect that. Pair the zone gate with a staleness detector or a runnable-example harness for factual coverage. The matrix also depends on honest labeling; a human who removes the AI-DRAFT marker accidentally bypasses the gate and returns the team to unmarked review. Finally, the zones themselves require maintenance. If a new directory appears, someone must add it to delegation.yaml before the next PR touches it.

Who should not use it? Small documentation suites of fewer than five pages will find the YAML and script overhead larger than the benefit of the workflow. Strictly regulated projects that must prove human authorship for every sentence can use the red-zone rule, but they should never send any prompt to a model for those sections. Teams that cannot agree on what counts as judgment-heavy should start with a one-week trial and let the CI failures teach them where the boundary actually belongs.

The boundary is the product

Documentation AI tools keep improving, but the bottleneck is not generation quality; it is ownership clarity. When the delegation boundary lives in code, the human reviewer gains a scoped job instead of a vague one. The model drafts the stable, the human owns the consequential, and the build enforces the difference. That is a workflow worth committing to a repository.