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