Who Owns This Heading? A Contract for AI-Drafted Docs

Description and use

Implement a YAML ownership contract assigning each documentation heading a clear owner, and a gate script that blocks merges if human‑owned sections lack a DOC‑OWN signature. This ensures critical sections are verified by humans and AI‑generated content does not cause operational failures.

Problem

AI-generated documentation can contain critical operational or policy information that, if incorrect, leads to failures. Existing file-level ownership is too coarse, allowing human‑owned sections to be drafted by models without verification.

Outcome

The workflow enforces clear ownership of documentation sections, preventing AI‑generated errors in critical operational content and ensuring human review before merge.

Workflow

• 1. Define a doc_ownership.yaml with rules mapping heading patterns to owners and reasons.
• 2. Generate documentation with an AI model, marking model_draft sections.
• 3. Add DOC‑OWN signatures to human_own headings by a reviewer.
• 4. Run ownership_gate.py to fail the build if any human_own heading lacks a valid signature.
• 5. Merge only after all gates pass, ensuring correct ownership and verification.

Evidence

That failure was not a grammar problem. It was an ownership problem.

Source

Unsigned, or signed with owner=model_draft on a human_own rule, is a gate failure.

Source