From b422b56bc145371e17152f16fa19cd7043c1cc36 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Fri, 18 Sep 2026 12:43:54 +1000 Subject: [PATCH] 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. --- .agents/skills/archie-build-and-env/SKILL.md | 18 +++++++--- .../archie-diagnostics-and-tooling/SKILL.md | 10 +++--- .../skills/archie-docs-and-writing/SKILL.md | 19 ++++++---- CLAUDE.md | 2 +- Taskfile.yml | 32 ++++++++++++++++- docs/architecture/generated-documentation.md | 35 ++++++++++++------- docs/prds/config-example-drift.md | 8 +++-- docs/prds/contract-conformance-audit.md | 11 +++--- 8 files changed, 95 insertions(+), 40 deletions(-) diff --git a/.agents/skills/archie-build-and-env/SKILL.md b/.agents/skills/archie-build-and-env/SKILL.md index a62610dce..33034224e 100644 --- a/.agents/skills/archie-build-and-env/SKILL.md +++ b/.agents/skills/archie-build-and-env/SKILL.md @@ -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 diff --git a/.agents/skills/archie-diagnostics-and-tooling/SKILL.md b/.agents/skills/archie-diagnostics-and-tooling/SKILL.md index f6df6d084..03697c9ce 100644 --- a/.agents/skills/archie-diagnostics-and-tooling/SKILL.md +++ b/.agents/skills/archie-diagnostics-and-tooling/SKILL.md @@ -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` diff --git a/.agents/skills/archie-docs-and-writing/SKILL.md b/.agents/skills/archie-docs-and-writing/SKILL.md index c0cf9354f..18cbf7360 100644 --- a/.agents/skills/archie-docs-and-writing/SKILL.md +++ b/.agents/skills/archie-docs-and-writing/SKILL.md @@ -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 diff --git a/CLAUDE.md b/CLAUDE.md index bb4e9596b..ce7282cd1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 ``` diff --git a/Taskfile.yml b/Taskfile.yml index 4356c12d4..4683f8f95 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -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 diff --git a/docs/architecture/generated-documentation.md b/docs/architecture/generated-documentation.md index 291ff752d..473caef53 100644 --- a/docs/architecture/generated-documentation.md +++ b/docs/architecture/generated-documentation.md @@ -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. diff --git a/docs/prds/config-example-drift.md b/docs/prds/config-example-drift.md index 4897475e7..b549338f0 100644 --- a/docs/prds/config-example-drift.md +++ b/docs/prds/config-example-drift.md @@ -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, diff --git a/docs/prds/contract-conformance-audit.md b/docs/prds/contract-conformance-audit.md index 98f812343..1f4afcb24 100644 --- a/docs/prds/contract-conformance-audit.md +++ b/docs/prds/contract-conformance-audit.md @@ -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