From ad64ed0ec3bddab2e4ede50b3cef15bf9784bfba Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 22 Sep 2026 01:54:57 +1000 Subject: [PATCH] docs(skills): carry the projection, link-graph and gate-contention traps --- .agents/skills/archie-agent-fleet/SKILL.md | 31 +++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/.agents/skills/archie-agent-fleet/SKILL.md b/.agents/skills/archie-agent-fleet/SKILL.md index 59def8e1c..8b09233ca 100644 --- a/.agents/skills/archie-agent-fleet/SKILL.md +++ b/.agents/skills/archie-agent-fleet/SKILL.md @@ -39,11 +39,12 @@ State these as facts to each lane, not as advice. Each one has cost a real run. | Invariant | Why it matters to a lane | |---|---| | **The control plane fails closed.** A stored resource that will not validate stops `archied` starting, and nothing bypasses the control plane at boot. Resource history is the only in-band remedy, and it needs the State Store up. | A lane touching the boot path, a stored resource kind, or the recovery commands is a risk-routed lane for the operator's eyes, not a gate-and-merge lane. Evidence: `docs/architecture/safe-change-and-recovery.md` ("Database settings: degrade paths and recovery"). | -| **`internal/webui` must not reach `internal/domain/workflow`.** Go imports are atomic: one reference relinks the whole daemon runtime into the UI binary. | `cmd/archie-ui/architecture_test.go` measures the linked binary (`go list -deps .`), not the imports, and fails on anything under `internal/domain/workflow`. `internal/domain/workflow/task` is a named `gateExceptions` entry that must stay linked — it carries only contract and view types, and a stale exception fails the test in both directions. | +| **`internal/webui` must not reach `internal/domain/workflow`.** Go imports are atomic: one reference relinks the whole daemon runtime into the UI binary. | `cmd/archie-ui/architecture_test.go` measures the linked binary (`go list -deps .`), not the imports, and fails on anything under `internal/domain/workflow`. `internal/domain/workflow/task` is a named `gateExceptions` entry that must stay linked — it carries only contract and view types, and a stale exception fails the test in both directions. The same test's gate also excludes `internal/app/archied` from the UI binary, so a helper needed by both the daemon and the `cmd/` binaries belongs in `internal/infrastructure/configuration` (which already owns path resolution), never in `archied`. | | **The task DB has one owner.** `-tasks.sqlite` is served by the standalone `cmd/archie-state-store` process alone. No second listener, no in-process serving path in the daemon or Gateway. | `boot.openStateStore` (`internal/app/archied/state_store.go`) is the only production caller of `openProductionTaskStore`, and it takes an exclusive flock on `.lock` for the process's life — a second State Store on the same file fails there rather than merely being discouraged. Offline maintenance belongs in subcommands of that binary, never a new `cmd/` entry (`docs/architecture/organisation.md#process-boundaries`). | | **Never commit `.beads/`.** Bead state moves through Dolt; `issues.jsonl` and `interactions.jsonl` are local-only. | A lane that stages `.beads/` pollutes its diff. Closing a bead is not commit-worthy on its own. | | **Generated assets are LAW.** `ui/dist/` and the schema outputs (`docs/data/generated/contracts.json`). | Incorporate them into the commit that shifted them. Never revert, regenerate away, or leave them out. | | **Scratch goes to `/tmp` only.** Never the working tree. | `worktree.CommitAll` stages with go-git's `AddWithOptions{All: true}` (`internal/worktree/worktree.go:502`), which does **not** honour `.gitignore`. An untracked scratch file in a lane worktree is swept onto the task branch. The task brief lives in `.git/task.json` for exactly this reason. | +| **A config field must survive the control-plane round trip or it does nothing.** A field added to `MCPServer` (or any projected settings type) must be carried in three sites: `mcpServerSettings` and `seedTools` in `internal/app/controlplane/tool_settings.go`, and `runtimeToolConfigFrom` in `runtime_config.go`. | The control plane rebuilds the whole resource from that projection, so a field missing there is silently dropped whenever a control plane is configured: the setting parses, appears in the dashboard, and has no effect. `TestToolSettingsProjectionCarriesEveryMCPServerField` reflects over `MCPServer` and fails on an omitted field, in both directions (seed and layering) — but it covers that type only; every other mirrored type (`minimaxSettings`, ...) is still hand-mirrored. Adding the field to just `internal/config` is the `xrux`/`parallel_tool_calls` failure shape. | | **Dependency direction is `cmd -> app -> {domain, infrastructure}`**, with infrastructure implementing domain contracts. | A lane that needs a new edge says so before writing it. The `internal/{logging,events,eventbus,policy,taskstate}` cross-cutting packages import zero internal packages. Source: `docs/architecture/organisation.md`. | ## The canonical gate @@ -90,6 +91,19 @@ lint, build, `go test ./...`, the tools tests and the dashboard tests. The merge train owns it. Never run it in a lane, and never two at once: it saturates the host. +"Never two at once" includes gates you did not start. More than one agent session +works in this checkout, so before the merge train gates, check who holds it: + +```bash +ps -ef | grep -E '[t]ask check|[t]ask ' | grep -v grep +``` + +A concurrent gate is not merely slow. Both runs regenerate +`docs/data/generated/contracts.json` and `ui/dist`, so a contended result is +worthless in either direction — neither run's verdict tells you anything about +the tree. Wait for the host to be quiet and bound the wait: still held after +about twenty minutes means report the contention rather than gate anyway. + ## The agent-discovery trap A lane worktree is a **sibling** of the repository (`/work/apps/cp-`), not a @@ -107,6 +121,21 @@ ln -sfn /work/apps/archie-core/.pi/agents /work/apps/cp-/.pi/agents `.pi/` is gitignored, so the worktree stays clean and the symlink cannot reach a commit. This costs an hour to rediscover. +## Traps worth carrying + +- **`touch` does not invalidate a Task source.** Task hashes file *content*, so a + stale-binary probe has to change bytes. `task build` now tracks `ui/dist/**`, + the generated dashboard the binary embeds, which is why the merge train still + runs `task build --force` before the gate. +- **`GATEWAY_VERSION` and `RUNTIME_VERSION` come from `git describe`**, which no + file checksum can invalidate: an empty commit moves the stamp while `task + build` still reports the binary up to date, shipping the old value. Tracked as + `archie-core-pdq2`. +- **Untracked files in the shared checkout are other sessions'.** prdlint + scratch (`docs/prds/rules.jsonl`), editor state, and gate-written artifacts + appear and vanish under a lane. Never chase, add, stage or commit them: a + merge train's scope is its own lanes' files, and nothing else. + ## Tracker conventions `bd` is the only tracker; no markdown TODO lists, no local trackers.