Hash‑Lock the SLA: Generate Reference, Freeze Policy

Description and use

Documentation policy is protected from AI drift: critical sections are stored in separate files, hashed, and validated in CI, while the AI generator can only modify generated references.

Problem

AI‑generated documentation can unintentionally alter or remove critical policy text such as SLAs, leading to incorrect or misleading promises in public docs.

Outcome

Policy sections in documentation are protected from AI drift, ensuring accurate SLA and other critical statements while still allowing automated generation of reference content.

Workflow

• 1. Classify each README section as rebuildable reference or human policy using a decision table.
• 2. Create a docs.ownership.yml file listing sections, owners, freeze status, and source files.
• 3. Store frozen policy sections as raw files in docs/frozen/ and generate a SHA256SUMS file.
• 4. In the README, wrap sections with HTML comment markers (e.g., <!-- section:sla:start -->).
• 5. Run a CI validator script that extracts section bodies, hashes them, and compares to SHA256SUMS. Fail if mismatched.
• 6. When a policy change is needed, edit the corresponding frozen file, run the hash updater, and review the isolated diff. Do not ask the AI to refresh the README.

Evidence

If a human intends to change the SLA, they edit docs/frozen/sla.md, run the hash updater, and review that diff in isolation.

Source