39 lines
1.8 KiB
Markdown
39 lines
1.8 KiB
Markdown
# US09-05 — Automate Documentation Acceptance
|
|
|
|
Epic: [E09](../E09-documentation.md)
|
|
|
|
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
|