From 82bef76caf5aca368779b2ef924e47d485e13c8e Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Wed, 30 Sep 2026 11:38:57 +1000 Subject: [PATCH] docs(development): task check writes no module file on a consistent tree The index page warned that task check adds linter-tool lines to go.sum (bead 1e37) and told contributors to restore the file before committing. Measured at HEAD c6623d53 on a copy of go.sum, with the originals restored after every step, that is not what the gate does: go fix ./..., golangci-lint fmt, go vet ./..., golangci-lint run ./... (root and tools), go build ./cmd/..., go test -short ./..., the docsgen and docsite checks and go -C tools test -mod=readonly ./... left go.mod, go.sum, tools/go.mod and tools/go.sum byte-identical, with GOFLAGS unset and again with GOFLAGS=-mod=mod. golangci-lint cannot write its own lines into go.sum either: it is in no require or tool directive, go mod tidy -diff is empty, and the committed go.sum carries none of its dependencies. What the page should say is the rule the measurements show. A stale go.mod or go.sum fails the gate (missing go.sum entry, updates to go.mod needed) instead of being repaired, because every Go step runs under the toolchain's readonly default and the tools steps pass -mod=readonly. Only a global GOFLAGS=-mod=mod in go env re-enables the repair, which is why the flag is spelled out on the go -C tools steps; when go.sum does go dirty, go mod tidy and its own commit are the fix. The regenerated docs/data/generated/dev-docs.json rides along, as the page requires: docsite check failed on the edited page first (stale dev-docs.json) and passes after task docs:artifact. --- docs/data/generated/dev-docs.json | 2 +- docs/development/index.md | 10 +++++++--- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 0a671947e..6c8fe1b8c 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -106,7 +106,7 @@ "url": "/dev/development/", "title": "Development guides", "section": "Development", - "body": "# Development guides\n\nChecklists for changing Archie, one page per area. Each names every place a\nchange must reach, so a feature that works in one layer does not silently stop\nat the next. A change that spans areas starts on the page for the area it\nbegins in, which points to the others. The pages point at the documents that\nown the design (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than\nrestating them.\n\n| Area | Covers |\n| ---------------------------------------------- | -------------------------------------------------------------------------------- |\n| [Frontend UI](/dev/development/frontend-ui/) | Anything under `ui/`, and the dashboard's API routes |\n| [Agent](/dev/development/agent/) | The agent container, its image, profiles, tools and workspace |\n| [Workflows](/dev/development/workflows/) | Workflow definitions and step types |\n| [Daemon](/dev/development/daemon/) | Task statuses, fields and the brief; sources, event types, mappings and bindings |\n| [State Store](/dev/development/state-store/) | Stored fields, tables, RPCs and errors |\n| [Control plane and settings](/dev/development/control-plane/) | Settings in `config.toml` or the dashboard |\n| [Processes and wiring](/dev/development/wiring/) | Where code goes, processes, plugin engines, channels, NATS subjects |\n| [Merging work](/dev/development/merging-work/) | Merging a lane or a branch |\n\n## Every change\n\n- Write the failing test first for anything with logic, branching or a\n contract, and check it fails on an assertion, not a compile error.\n- Test through the path production uses. A test that sets a value directly on\n the consumer proves nothing about the layers that normally deliver it.\n- Run `task check` and let its exit status decide the commit:\n `task check \u0026\u0026 git commit ...`. `task test` passes `-short`, which skips the\n process and Postgres tests, so run `go test -count=1 ./cmd/... ./internal/...`\n too when a change crosses a process or the database.\n- Regenerate, never hand-edit, generated output: `task proto:generate`,\n `go -C tools tool sqlc generate -f $PWD/internal/infrastructure/postgres/sqlc.yaml`,\n `task ui`, `task docs:artifact`. `task proto:check` compares against the git\n index, so stage regenerated contracts before running it.\n- Stage by path, or read `git status` before `git add -A`. Tests that start\n embedded NATS or write logs must use `t.TempDir()`; anything they leave in the\n tree gets committed. `task check` also adds linter-tool lines to `go.sum`\n (bead 1e37); restore `go.sum` before committing unless you changed a\n dependency.\n- A change to `docs/prds/`, `docs/architecture/` **or `docs/development/`**\n carries the regenerated `docs/data/generated/dev-docs.json`: run\n `task docs:artifact` (not `task docs:check`, which checks contracts only).\n PRD edits also follow `docs/prds/RULES.md` and pass `task docs:prds`.\n" + "body": "# Development guides\n\nChecklists for changing Archie, one page per area. Each names every place a\nchange must reach, so a feature that works in one layer does not silently stop\nat the next. A change that spans areas starts on the page for the area it\nbegins in, which points to the others. The pages point at the documents that\nown the design (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than\nrestating them.\n\n| Area | Covers |\n| ---------------------------------------------- | -------------------------------------------------------------------------------- |\n| [Frontend UI](/dev/development/frontend-ui/) | Anything under `ui/`, and the dashboard's API routes |\n| [Agent](/dev/development/agent/) | The agent container, its image, profiles, tools and workspace |\n| [Workflows](/dev/development/workflows/) | Workflow definitions and step types |\n| [Daemon](/dev/development/daemon/) | Task statuses, fields and the brief; sources, event types, mappings and bindings |\n| [State Store](/dev/development/state-store/) | Stored fields, tables, RPCs and errors |\n| [Control plane and settings](/dev/development/control-plane/) | Settings in `config.toml` or the dashboard |\n| [Processes and wiring](/dev/development/wiring/) | Where code goes, processes, plugin engines, channels, NATS subjects |\n| [Merging work](/dev/development/merging-work/) | Merging a lane or a branch |\n\n## Every change\n\n- Write the failing test first for anything with logic, branching or a\n contract, and check it fails on an assertion, not a compile error.\n- Test through the path production uses. A test that sets a value directly on\n the consumer proves nothing about the layers that normally deliver it.\n- Run `task check` and let its exit status decide the commit:\n `task check \u0026\u0026 git commit ...`. `task test` passes `-short`, which skips the\n process and Postgres tests, so run `go test -count=1 ./cmd/... ./internal/...`\n too when a change crosses a process or the database.\n- Regenerate, never hand-edit, generated output: `task proto:generate`,\n `go -C tools tool sqlc generate -f $PWD/internal/infrastructure/postgres/sqlc.yaml`,\n `task ui`, `task docs:artifact`. `task proto:check` compares against the git\n index, so stage regenerated contracts before running it.\n- Stage by path, or read `git status` before `git add -A`. Tests that start\n embedded NATS or write logs must use `t.TempDir()`; anything they leave in the\n tree gets committed. `task check` writes no module file on a consistent tree,\n root or `tools/` (verified at HEAD with `GOFLAGS` unset and with `-mod=mod`):\n a stale `go.mod` or `go.sum` fails it, with `missing go.sum entry` or\n `updates to go.mod needed`, rather than being repaired. Only a global\n `GOFLAGS=-mod=mod` in `go env` re-enables that repair, which is why the\n `go -C tools` steps pass `-mod=readonly`; if `go.sum` goes dirty, run\n `go mod tidy` and commit the result on its own.\n- A change to `docs/prds/`, `docs/architecture/` **or `docs/development/`**\n carries the regenerated `docs/data/generated/dev-docs.json`: run\n `task docs:artifact` (not `task docs:check`, which checks contracts only).\n PRD edits also follow `docs/prds/RULES.md` and pass `task docs:prds`.\n" }, { "url": "/dev/development/agent/", diff --git a/docs/development/index.md b/docs/development/index.md index 51bb9b6fc..17b2f232a 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -34,9 +34,13 @@ restating them. index, so stage regenerated contracts before running it. - Stage by path, or read `git status` before `git add -A`. Tests that start embedded NATS or write logs must use `t.TempDir()`; anything they leave in the - tree gets committed. `task check` also adds linter-tool lines to `go.sum` - (bead 1e37); restore `go.sum` before committing unless you changed a - dependency. + tree gets committed. `task check` writes no module file on a consistent tree, + root or `tools/` (verified at HEAD with `GOFLAGS` unset and with `-mod=mod`): + a stale `go.mod` or `go.sum` fails it, with `missing go.sum entry` or + `updates to go.mod needed`, rather than being repaired. Only a global + `GOFLAGS=-mod=mod` in `go env` re-enables that repair, which is why the + `go -C tools` steps pass `-mod=readonly`; if `go.sum` goes dirty, run + `go mod tidy` and commit the result on its own. - A change to `docs/prds/`, `docs/architecture/` **or `docs/development/`** carries the regenerated `docs/data/generated/dev-docs.json`: run `task docs:artifact` (not `task docs:check`, which checks contracts only).