fix(build): gate the tools module read-only in task check

Nothing in the delivery gate entered tools/, so its dependency drift was
only ever discovered by a command that silently repaired it, dirtying the
tree with an unrelated diff. task check now runs test:tools.

-mod=readonly is passed explicitly on every documented tools command: a
developer's global GOFLAGS=-mod=mod in go env overrides the toolchain
default and re-enables the rewrite.

Also corrects the archie-build-and-env coverage table, which claimed task
check omits task lint.
This commit is contained in:
sam committed 2026-09-13 15:00:33 +10:00
1 parent c12f6865d7
commit 27203c6523
4 files changed
+38 -10

No files matched your search

+16 -6
View File
@@ -109,12 +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 + `vet` + `build` + `test`. |
| `task check` | `fmt` + `go fix ./...` again + `proto:lint` + `proto: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 `task lint`, race tests, and the
`tools/` module. It has no docs step: there is no documentation build to omit.
`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.
Run only in authorized writable worktree. For read-only preview: `gofumpt -l .`.
## Verify the tools module separately
@@ -127,13 +128,22 @@ replace github.com/samcharles93/archie-core => ../
```
```bash
go -C tools test ./... -count=1
go -C tools test -mod=readonly ./... -count=1
```
`-mod=readonly` is mandatory on every `go -C tools` command. The `replace`
forces the tools build list to satisfy the root module's requirements, so a
root dependency bump leaves tools stale, and a writable command repairs
`tools/go.mod` and `tools/go.sum` in place, dirtying the tree with an
unrelated diff. Pass the flag explicitly: a global `GOFLAGS=-mod=mod` in
`go env` beats the toolchain default. A failure here means run
`go -C tools mod tidy` and commit that on its own. `task check` runs this via
`task test:tools`.
Generate documentation to temp file:
```bash
go -C tools run ./docsgen --repo-root .. --out /tmp/archie-core-contracts.json
go -C tools run -mod=readonly ./docsgen --repo-root .. --out /tmp/archie-core-contracts.json
cmp --silent docs/data/generated/contracts.json /tmp/archie-core-contracts.json
```
@@ -200,7 +210,7 @@ env GIT_CONFIG_GLOBAL=/dev/null go test ./internal/worktree/... ./internal/workt
| Vet | `go vet ./...` | Passed on 2026-07-28. |
| Lint | `golangci-lint run ./...` | Failed with 54 findings on 2026-07-28. |
| Build | `go build -o /tmp/... ./cmd/archied` and `cmd/archie-agent` | Both passed on 2026-07-28. |
| Tools tests | `go -C tools test ./... -count=1` | Passed on 2026-07-28. |
| Tools tests | `go -C tools test -mod=readonly ./... -count=1` | Passed on 2026-07-28. |
| Generated contract parity | Temp docsgen output + `cmp --silent` | Passed for 10 schemas. |
| Container build | `task docker-build` | Not verified in restricted environment. |
| Repository gate | `task check` | Non-green; skillscript failure in root suite. |
@@ -38,7 +38,7 @@ Module boundaries (root and `tools/` are separate):
```sh
find . -name go.mod -not -path './.git/*' -not -path './node_modules/*'
go list -m -f '{{.Path}} {{.GoVersion}}'
go -C tools list -m -f '{{.Path}} {{.GoVersion}}'
go -C tools list -mod=readonly -m -f '{{.Path}} {{.GoVersion}}'
```
## Build the behavior trace
@@ -147,9 +147,9 @@ Current behavior, verified 2026-07-28:
- Default output is `docs/data/generated/contracts.json`.
```bash
GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools test ./docsgen -count=1
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 ./docsgen --repo-root .. --out "$docs_tmp"
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
```
+19 -1
View File
@@ -206,8 +206,22 @@ tasks:
cmds:
- go test ./... -count=1
test:tools:
desc: Run the nested tools module suite, refusing to rewrite its go.mod
summary: |
tools/go.mod replaces the root module, so its build list must satisfy
the root module's requirements. When the root moves on, the tools module
goes stale and any plain go command there rewrites tools/go.mod and
tools/go.sum to catch up, leaving an unrelated dirty diff.
-mod=readonly is explicit because a developer's global GOFLAGS=-mod=mod
overrides the toolchain default and re-enables the silent rewrite.
Fix a failure here with: go -C tools mod tidy
cmds:
- go -C tools test -mod=readonly ./... -count=1
check:
desc: "Full quality gate: fmt, go fix, proto, vet, lint, build, test, ui tests"
desc: "Full quality gate: fmt, go fix, proto, vet, lint, build, test, tools tests, ui tests"
cmds:
- task: fmt
- go fix ./...
@@ -217,6 +231,10 @@ tasks:
- task: lint
- task: build
- task: test
# The tools module is not covered by ./... from the root; without this
# its dependency drift is only ever discovered by a command that
# silently repairs it.
- task: test:tools
# The dashboard's suite runs here too. Left out of the gate it rots
# silently: nothing else executes it, so a broken DOM primitive ships.
- task: test:ui