docs(skills): carry the projection, link-graph and gate-contention traps
This commit is contained in:
1 parent
ce006fabc7
commit
ad64ed0ec3
1 file changed
+30
-1
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user