photoanalyzer/delivery_backlog/stories/US09-05-docs-gate.md

US09-05 — Automate Documentation Acceptance

Epic: E09

As a release owner, I want one gate that proves the documentation still describes the application, so that a change to the code cannot quietly make the manuals wrong.

Acceptance criteria

• One documented command runs every documentation check and retains its evidence, in the shape the release and container gates already use.
• The gate fails when: an internal link or anchor is dead; a page is unreachable from the index; an image is referenced but missing or present but unreferenced; a documented setting, command, exit code, error code, or state does not exist in the code; a code path exists that the documentation is required to cover and does not.
• The gate regenerates the screenshots and fails when a regenerated image no longer matches the committed one beyond a stated tolerance, so a UI change that invalidates the manual is a red build rather than a discovery months later.
• The gate renders every documentation page in a real browser and fails on any console error or CSP violation, and asserts that script-src contains neither 'unsafe-eval' nor 'unsafe-inline'.
• The checks run on a phase_i marker; CI runs the gate, and the earlier epic suites keep running unchanged.
• The README and the application's documentation index point at each other, so neither is the forgotten copy.
• Documentation stories are mapped in the story traceability matrix like every other story.

Automated tests

• The gate's own contract is testable without a browser: a seeded broken link, a missing image, an undocumented error code, and a stale screenshot each fail it, and a clean tree passes.
• The full documentation suite runs on phase_i in CI.

Dependencies

• US09-01 through US09-04