docs(skills): carry the projection, link-graph and gate-contention traps

This commit is contained in:
sam committed 2026-09-22 01:57:00 +10:00
1 parent ce006fabc7
commit ad64ed0ec3
1 file changed
+30 -1
+30 -1
View File
@@ -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.** `<db_path>-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 `<db>.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-<lane>`), not a
@@ -107,6 +121,21 @@ ln -sfn /work/apps/archie-core/.pi/agents /work/apps/cp-<lane>/.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.