`docs/data/generated/contracts.json` sat stale since a825db28 with nothing
to notice: no task, no test, and no CI step regenerates or compares it, so
the committed contract reference quietly drifted from the Go types it
claims to describe. It was only found by hand-running the generator.
Implements Step 6 of docs/architecture/generated-documentation.md, which
already specified this command and closed the gap filed in
docs/prds/contract-conformance-audit.md ("`docsgen check` is documented and
does not exist"):
1. generates into a temporary directory;
2. normalizes line endings;
3. compares the schema trees with the committed output;
4. reports missing, changed, and obsolete files;
5. names the authoritative definition behind each mismatch;
6. exits non-zero without modifying the working tree.
The check never writes to the working tree, so the author applies the
regenerated bytes rather than the gate silently doing it. That is why this
is a `check` and not a CI auto-update: the code change that shifted the
contract surface should be reviewed with its regenerated artifact in one
commit, and a bot commit would bless an unintended contract change with no
reviewer ever seeing it. Step 9 states the same prohibition directly.
Diagnostics name the Go type, so a failure says where to look:
docs/data/generated/contracts.json is stale; regenerate it with:
go -C tools run ./docsgen --repo-root ..
schema "AgentExecutionResult" changed (authoritative definition:
github.com/samcharles93/archie-core/internal/agentexec.Result)
schema "MediaAttachment" changed (authoritative definition:
reached from .../internal/gateway.MessageEvent)
Nested definitions are attributed through the published contract that
references them, iterated in sorted order so the diagnostic is
deterministic when several contracts share a definition.
Usage: `go -C tools run ./docsgen check --repo-root ..`, plus the existing
`--out` to compare an arbitrary artifact.
Reuses the write path rather than reimplementing encoding, so check and
generate cannot disagree about the expected bytes.
Tests cover: the committed artifact is current (the regression guard that
would have caught this), changed/removed/missing/obsolete detection, and
that a failing check leaves the artifact's bytes, mode, and directory
contents untouched.
`task docs:check` wiring into `task check` is deliberately not in this
commit: Taskfile.yml is being edited concurrently in this working tree.
Verified with `task check` (green).