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:
8 files changed
+95
-40
No files matched your search
@@ -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
|
||||
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user