feat(build): gate generated contract data in task check

Closes #855 (archie-core-5gzx).

The check mode added in the preceding commit had no caller, so it prevented nothing: a
stale contracts.json still passed every gate. This wires it in and makes
drift fail the build.

- `task docs:generate` writes the committed artifact.
- `task docs:check` verifies it, non-destructively.
- `task check` runs `docs:check`, right after `proto:check`, so both
  generated-artifact surfaces are judged the same way in the same place.

The check cannot be satisfied by rewriting: it generates into a temporary
directory, so a failing gate leaves the artifact exactly as it found it and
the author applies the regenerated bytes. That keeps the regenerated diff
reviewable in the same commit as the code change that caused it, which is
what Step 9 of the architecture document requires and what a CI auto-update
would quietly bypass.

Documents that called this gap open are updated rather than left to
contradict the code:

- `generated-documentation.md` Step 8 (no `docs:*` task exists -> both exist),
  Step 9 (drift is gated locally, not in CI), and the hook/CI policy (rule 3
  is now enforced by the gate; rules 1, 2, and 4 still rely on the author,
  since nothing observes a commit).
- `contract-conformance-audit.md` gap 1, now closed.
- `config-example-drift.md` item 3, which asked for exactly this wiring.
- `CLAUDE.md`, whose `task check` description listed neither `docs:check`
  nor `test:tools`.
- The build, docs, and diagnostics skills, plus a re-baselined diagnostics
  snapshot: the `task_docs` delivery surface went 0 -> 6 and the `tools`
  module 4 -> 7 now that the tasks exist.

Verified with `task check` (green), including the new `docs:check` step.
This commit is contained in:
sam committed 2026-09-18 12:46:40 +10:00
1 parent 1f975f37ad
commit b422b56bc1
8 files changed
+95 -40

No files matched your search

+13 -5
View File
@@ -109,13 +109,13 @@ golangci-lint run ./...
| `task lint` | `golangci-lint run ./...`. |
| `task build` | Builds both commands into `bin/`. |
| `task test` | `go test ./... -count=1` in the runtime module. |
| `task check` | `fmt` + `go fix ./...` again + `proto:lint` + `proto:check` + `vet` + `lint` + `build` + `test` + `test:tools` + `test:ui`. |
| `task check` | `fmt` + `go fix ./...` again + `proto:lint` + `proto:check` + `docs:check` + `vet` + `lint` + `build` + `test` + `test:tools` + `test:ui`. |
| `task clean` | Recursively removes `bin/`; destructive. |
| `task docker-build` | `docker compose build agent` only. |
`task check` is the definitive gate but omits race tests, `task vuln`, and
`task docker-build`. It has no docs step: there is no documentation build to
omit.
`task docker-build`. Its docs step, `docs:check`, verifies committed generated
data and never renders anything: there is still no documentation build.
Run only in authorized writable worktree. For read-only preview: `gofumpt -l .`.
## Verify the tools module separately
@@ -148,8 +148,16 @@ cmp --silent docs/data/generated/contracts.json /tmp/archie-core-contracts.json
```
2026-09-18 run wrote 11 schemas. The committed output was stale since
`4b340d2b` and was regenerated the same day; `cmp` now passes. Planned
`docsgen all` and `docsgen check` do **not** exist yet.
`4b340d2b` and was regenerated the same day; `cmp` now passes. `task docs:check`
now runs inside `task check`, so this drift fails the gate instead of waiting to
be found by hand. `docsgen all` does not exist yet.
Prefer the task over the raw commands:
```bash
task docs:check # non-destructive; fails loudly and names the Go type
task docs:generate # rewrites the committed artifact; review the diff
```
## Documentation needs no build
@@ -242,7 +242,7 @@ These are post-fix numbers: earlier runs of the same scripts reported roughly
| `internal/app/archied.Run` body span / approximate complexity | 97 / 19 |
| Root internal packages / direct internal edges | 110 / 316 |
| Tagged config field rows | 194 |
| Tracked paths / tracked `node_modules` paths / tracked symlinks | 1,087 / 0 / 1 |
| Tracked paths / tracked `node_modules` paths / tracked symlinks | 1,088 / 0 / 1 |
| `.dockerignore` present | 1 |
`source-metrics.go` and `git ls-files` reconcile here: 408 + 9 generated
@@ -255,10 +255,10 @@ production lines. Editing a bundled script therefore moves
`production_physical_lines` on its own, so re-baseline after any script change
rather than reading the delta as a change in the product code.
The delivery snapshot found no Taskfile literals for race or docs, but four
for the `tools` module; GitHub `go gate` 4 and container publish 3; and
non-zero literals for all five composition-root anchors under
`internal/app/archied`.
The delivery snapshot found no Taskfile literals for race; docs now has 6 and
the `tools` module 7, both grown by wiring `task docs:check` into the gate;
GitHub `go gate` 4 and container publish 3; and non-zero literals for all five
composition-root anchors under `internal/app/archied`.
The focused test
`go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v`
@@ -140,21 +140,26 @@ Current behavior, verified 2026-09-18:
- Tool path is `tools/docsgen`, not `tools/cmd/docsgen`.
- Separate Go module replacing root module with `../`.
- Accepts `--repo-root` and `--out`; no implemented `data`, `asyncapi`, `all`,
or `check` subcommands.
- Accepts `--repo-root` and `--out`, plus a `check` subcommand that compares
against the committed artifact without writing. No implemented `data`,
`asyncapi`, or `all` subcommands.
- `currentContractTypes` publishes three top-level contracts and collects
referenced schemas into one JSON object.
- Default output is `docs/data/generated/contracts.json`.
```bash
GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools test -mod=readonly ./docsgen -count=1
docs_tmp="$(mktemp /tmp/archie-contracts.XXXXXX.json)"
GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools run -mod=readonly ./docsgen --repo-root .. --out "$docs_tmp"
cmp "$docs_tmp" docs/data/generated/contracts.json
task docs:check # fails loudly, and names the Go type behind each mismatch
```
Treat the PRD's `docsgen all`, `docsgen check`, and `task docs:*` commands as
`APPROVED TARGET`.
`docsgen check` and the `docs:generate`/`docs:check` tasks are implemented, and
`task check` runs `docs:check` — generated drift is gated. `docsgen data`,
`docsgen asyncapi`, and `docsgen all` remain `APPROVED TARGET`.
The check is deliberately non-destructive: it generates into a temporary
directory, so a failing gate never rewrites the artifact it judges. Fix a
failure with `task docs:generate` and commit the result with the code change
that shifted the contract surface.
## Store documentation as repository Markdown
+1 -1
View File
@@ -94,7 +94,7 @@ task ui # build dashboard into ui/dist (LAW asset)
task fmt # gofumpt -w . && go fix ./...
task vet # go vet ./...
task lint # golangci-lint run ./...
task check # fmt + go fix + proto:lint + proto:check + vet + lint + build + test + test:ui (The Definitive Gate)
task check # fmt + go fix + proto:lint + proto:check + docs:check + vet + lint + build + test + test:tools + test:ui (The Definitive Gate)
task dev # archied live-reload + Vite HMR together on :5173
```
+31 -1
View File
@@ -35,6 +35,35 @@ tasks:
cmds:
- bash tools/proto.sh check
docs:generate:
desc: Regenerate the committed contract reference from Archie-owned types
summary: |
Writes docs/data/generated/contracts.json. The output is committed, so
this dirties the tree deliberately: review the diff and commit it with
the code change that shifted the contract surface. Never hand-edit the
artifact.
-mod=readonly is mandatory on every `go -C tools` command; see
task test:tools for why.
cmds:
- go -C tools run -mod=readonly ./docsgen --repo-root ..
docs:check:
desc: Verify the committed contract reference matches Archie-owned types
summary: |
Implements Step 6 of docs/architecture/generated-documentation.md:
generates into a temporary directory, compares it with the committed
output, names the authoritative Go definition behind each mismatch, and
exits non-zero without modifying the working tree.
Fix a failure with `task docs:generate`, then commit the result in the
same commit as the code change that shifted the contract surface. This
checks rather than regenerates on purpose: a gate that silently rewrote
the artifact would bless an unintended contract change with no reviewer
ever seeing it, which Step 9 explicitly forbids.
cmds:
- go -C tools run -mod=readonly ./docsgen check --repo-root ..
vet:
desc: Run go vet
cmds:
@@ -226,12 +255,13 @@ tasks:
- go -C tools test -mod=readonly ./... -count=1
check:
desc: "Full quality gate: fmt, go fix, proto, vet, lint, build, test, tools tests, ui tests"
desc: "Full quality gate: fmt, go fix, proto, docs, vet, lint, build, test, tools tests, ui tests"
cmds:
- task: fmt
- go fix ./...
- task: proto:lint
- task: proto:check
- task: docs:check
- task: vet
- task: lint
- task: build
+22 -13
View File
@@ -327,27 +327,35 @@ When a renderer is selected it MUST:
### Step 8: developer commands
No `docs:*` task exists. `Taskfile.yml` does not reference the generator, and
`task check` does not run `docs:check`, so generated drift is currently ungated.
The generator is run directly:
`task docs:generate` writes the committed artifact; `task docs:check` verifies
it. `task check` runs `docs:check`, so generated drift is gated rather than
advisory: a stale artifact fails the gate and names the authoritative Go
definition behind each mismatch.
```sh
go -C tools run ./docsgen all --repo-root ..
go -C tools run ./docsgen check --repo-root ..
task docs:generate
task docs:check
```
Wiring `docs:check` into `task check` is worth doing and does not depend on the
renderer decision.
Both wrap the generator, which can still be run directly:
```sh
go -C tools run -mod=readonly ./docsgen --repo-root ..
go -C tools run -mod=readonly ./docsgen check --repo-root ..
```
`docsgen all` is still target-only: `docsgen data` and `docsgen asyncapi` do not
exist, and only the single `contracts.json` artifact is generated today.
### Step 9: CI
The documentation workflow was deleted on 2026-09-12. No workflow builds, checks,
or publishes documentation. `deploy.yml` does not reference `docs/**`.
Reintroducing CI for documentation requires the renderer decision first. Any
such workflow MUST check generated output and MUST NOT regenerate and silently
publish uncommitted differences.
Drift is therefore gated locally, by `task check` running `docs:check` — not in
CI. Reintroducing CI for documentation requires the renderer decision first.
Any such workflow MUST check generated output and MUST NOT regenerate and
silently publish uncommitted differences.
### Step 10: cutover — done, in reverse
@@ -373,11 +381,12 @@ Documents MUST describe Archie. Publishing is a separate, undecided concern.
Generated documentation is committed.
No pre-commit hook is installed in this repository, and no CI step runs the
generator. The policy below is the intended contract, currently unenforced:
generator. Step 3 below is enforced by `task check`; steps 1, 2, and 4 still
rely on the author, because nothing observes a commit:
1. detects authoritative definition or generator changes;
2. runs the generator;
3. runs `docsgen check`;
3. runs `docsgen check` — enforced by `task check`;
4. refuses the commit when generated changes are unstaged or validation fails.
A commit MUST NOT be created while generated documentation is stale.
+5 -3
View File
@@ -78,9 +78,11 @@ empty, with an explicit allowlist for keys another binary owns. This is the
mechanism that would have caught a renamed key left behind in an example, and it
needs no inventory.
**3. Gate generated data in `task check`.** Add `docs:check` to the gate, closing
the admitted `generated-documentation.md:331` hole. Cheap, already implemented as
`go -C tools run ./docsgen check`.
**3. Gate generated data in `task check`.** Done. `task docs:check` runs in the
gate, closing the admitted "generated drift is currently ungated" hole. The
check mode did not exist when this was written; it was added for issue #855,
which also made the check non-destructive so the gate can never rewrite the
artifact it is judging.
**4. Explicitly NOT now: a generated key inventory.** `configuration.md`'s
completion criteria want "generated documentation lists every external key,
+6 -5
View File
@@ -93,11 +93,12 @@ the survey, not about the tree.
## The two gaps this was aimed at
**1. `docsgen check` is documented and does not exist.** Still open, filed as
`archie-core-5gzx`. `generated-documentation.md:118-121` advertises
`docsgen data|asyncapi|all|check`; `tools/docsgen/main.go` has exactly two flags
and always writes, so the documented check mode cannot run and line 331's
"generated drift is currently ungated" stands.
**1. `docsgen check` is documented and does not exist.** Closed by issue #855.
(issue #855 / `archie-core-5gzx`). `tools/docsgen` now has a `check` subcommand
and `task docs:check`, wired into `task check`: it generates into a temporary
directory, compares against the committed artifact, names the authoritative Go
definition behind each mismatch, and never writes to the working tree.
`docsgen data` and `docsgen asyncapi` remain target-only.
**2. The dashboard's client was not centralised while its own docstring claimed
it was.** Now closed by `18e8f8f`. The docstring said "Single place that knows how