Hash‑Lock the SLA: Generate Reference, Freeze Policy

Описание и применение

Политика документации защищена от изменений ИИ: критические разделы хранятся в отдельных файлах, хешируются и проверяются в CI, а генератор ИИ может менять только сгенерированные ссылки.

Задача

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

Результат

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

Рабочий процесс

• 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.

Доказательства

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

Источник