docsgen check mode: generated data drift is ungated #1086

Closed
opened 2026-10-27 13:38:58 +00:00 by sam · 0 comments
Owner

docs/architecture/generated-documentation.md advertises docsgen data|asyncapi|all|check and gives the invocation go -C tools run ./docsgen check --repo-root .., but tools/docsgen/main.go defines only --repo-root and --out and run() unconditionally writes. No check mode exists, no docs:* task exists, and task check does not run one -- so committed generated data (docs/data/generated/contracts.json) can drift with nothing to catch it. Line 331 of the same document admits 'generated drift is currently ungated'.

Add a check mode comparing freshly generated output against the committed file and fail on any diff, then wire it into task check. This is the last surface docs/contract-declarations.json cannot cover, because contractaudit audits declared consumer surfaces and generated data is consumed by nothing yet (docsgen's own output has no reader).

Acceptance criteria

docsgen check compares committed output and exits non-zero on drift (prove by injecting a change, not by asserting); task docs:check exists; task check runs it; generated-documentation.md's 'ungated' line and subcommand list become true

Close reason

Closed


Imported from beads archie-core-5gzx · GitHub #855 · type task · priority P2 · created 2026-09-14 · closed 2026-09-18

docs/architecture/generated-documentation.md advertises `docsgen data|asyncapi|all|check` and gives the invocation `go -C tools run ./docsgen check --repo-root ..`, but tools/docsgen/main.go defines only --repo-root and --out and run() unconditionally writes. No check mode exists, no docs:* task exists, and task check does not run one -- so committed generated data (docs/data/generated/contracts.json) can drift with nothing to catch it. Line 331 of the same document admits 'generated drift is currently ungated'. Add a check mode comparing freshly generated output against the committed file and fail on any diff, then wire it into task check. This is the last surface docs/contract-declarations.json cannot cover, because contractaudit audits declared consumer surfaces and generated data is consumed by nothing yet (docsgen's own output has no reader). ### Acceptance criteria docsgen check compares committed output and exits non-zero on drift (prove by injecting a change, not by asserting); task docs:check exists; task check runs it; generated-documentation.md's 'ungated' line and subcommand list become true ### Close reason Closed --- _Imported from beads `archie-core-5gzx` · GitHub #855 · type task · priority P2 · created 2026-09-14 · closed 2026-09-18_
sam added the mediumtask labels 2026-10-27 13:38:58 +00:00
sam self-assigned this 2026-10-27 13:38:58 +00:00
sam closed this issue 2026-10-27 13:38:58 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#1086