diff --git a/.agents/skills/archie-agent-fleet/SKILL.md b/.agents/skills/archie-agent-fleet/SKILL.md index 6817655be..5cd0f1013 100644 --- a/.agents/skills/archie-agent-fleet/SKILL.md +++ b/.agents/skills/archie-agent-fleet/SKILL.md @@ -12,7 +12,7 @@ description: >- # Run an agent fleet on archie-core -This skill carries the facts about *this repository*. It deliberately does not +This skill carries the facts about _this repository_. It deliberately does not restate the process. ## Where the method lives @@ -36,16 +36,16 @@ Route runtime facts to `archie-run-and-operate`, toolchain facts to 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. 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.** The task tables are 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 place the task store is built, and it holds the `state-store` Postgres ownership lock for the process's life — a second State Store on the same database 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`. | +| 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. 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.** The task tables are 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 place the task store is built, and it holds the `state-store` Postgres ownership lock for the process's life — a second State Store on the same database 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 @@ -80,13 +80,13 @@ go test ./internal/app/controlplane/... ./internal/domain/applystatus/... -count Real examples, from the worked example's `lanes.json`: -| Lane surface | Scoped command | -|---|---| -| CLI subcommands and the State Store contract | `go test ./cmd/... ./internal/infrastructure/staterpc/... -count=1 && go vet ./cmd/...` | -| Workflow registry and the agent worker | `go test ./internal/domain/workflow/... ./internal/app/agentworker/... -count=1 && go vet ./internal/domain/workflow/...` | -| Config decoding and daemon boot | `go test ./internal/infrastructure/configuration/... ./internal/app/archied/... -count=1 && go vet ./internal/infrastructure/configuration/... ./internal/app/archied/...` | +| Lane surface | Scoped command | +| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CLI subcommands and the State Store contract | `go test ./cmd/... ./internal/infrastructure/staterpc/... -count=1 && go vet ./cmd/...` | +| Workflow registry and the agent worker | `go test ./internal/domain/workflow/... ./internal/app/agentworker/... -count=1 && go vet ./internal/domain/workflow/...` | +| Config decoding and daemon boot | `go test ./internal/infrastructure/configuration/... ./internal/app/archied/... -count=1 && go vet ./internal/infrastructure/configuration/... ./internal/app/archied/...` | -`task check` is the *serial full gate* — fmt, proto checks, `docs:check`, vet, +`task check` is the _serial full gate_ — fmt, proto checks, `docs:check`, vet, 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. @@ -128,13 +128,13 @@ commit. This costs an hour to rediscover. ## Traps worth carrying -- **`touch` does not invalidate a Task source.** Task hashes file *content*, so a +- **`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 +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 diff --git a/.agents/skills/archie-agent-fleet/references/worked-example/00-orchestrator.md b/.agents/skills/archie-agent-fleet/references/worked-example/00-orchestrator.md index b18136d51..687740e4b 100644 --- a/.agents/skills/archie-agent-fleet/references/worked-example/00-orchestrator.md +++ b/.agents/skills/archie-agent-fleet/references/worked-example/00-orchestrator.md @@ -12,8 +12,8 @@ You are the orchestrator. You do not write production code yourself. You run waves of subagents through the `subagent` tool, verify their work against git evidence rather than their reports, and land finished slices on `main`. -Repository: `/work/apps/archie-core`, branch `main`, working tree clean at start. -Gate: `task check`. Tracker: `bd`. Read `CLAUDE.md` and +Repository: `/work/apps/archie-core`, branch `main`, working tree clean at +start. Gate: `task check`. Tracker: `bd`. Read `CLAUDE.md` and `docs/architecture/organisation.md` before Wave 1. --- @@ -34,20 +34,20 @@ Gate: `task check`. Tracker: `bd`. Read `CLAUDE.md` and manifest path, `git -C status --short`, `git log --oneline`, and `git diff --stat` against the lane's own base. A bead marked closed with no commits means the work did not happen. -5. **No suppression.** Children may not add `//nolint`, `t.Skip`, build tags that - exclude a failing test, or delete an assertion to make a gate pass. Say this - in every writer and fix task. A child that suppresses gets its lane reverted, - not patched. +5. **No suppression.** Children may not add `//nolint`, `t.Skip`, build tags + that exclude a failing test, or delete an assertion to make a gate pass. Say + this in every writer and fix task. A child that suppresses gets its lane + reverted, not patched. 6. **Formatting is law.** Adopt `task fmt` output verbatim. Never revert a linter or formatter diff. 7. **Zero patch stacking.** Two failed fixes on the same logic block means the - block gets rewritten, not patched a third time. This is a `CLAUDE.md` rule and - it applies to children. + block gets rewritten, not patched a third time. This is a `CLAUDE.md` rule + and it applies to children. 8. **Do not push.** Commit gate-clean work to `main` in the captain checkout. Sam pushes manually and does not always announce it, so never assume a commit is local or remote without checking `git log origin/main..main`. -9. **No `.beads/` commits.** Bead state moves through Dolt. Closing a bead is not - commit-worthy on its own. +9. **No `.beads/` commits.** Bead state moves through Dolt. Closing a bead is + not commit-worthy on its own. 10. **Scratch stays out of the tree.** Children write scratch to `/tmp` only. `.pi/` is gitignored; nothing else you create may land in a commit. 11. **Separation of duties.** No agent merges, closes or approves its own work. @@ -66,16 +66,17 @@ Gate: `task check`. Tracker: `bd`. Read `CLAUDE.md` and This came from the session that just ended. Treat it as fact. - `docs/prds/runtime-control-plane.md` is Approved and is the spec. Its resource - surface, YAML workflow definitions, identity-backed attribution and audit trail - are already built. + surface, YAML workflow definitions, identity-backed attribution and audit + trail are already built. - **Restore is not its own command.** A revision carries its value, so restoring replays it through the ordinary replace. Do not add a rollback RPC. -- **Dashboard writes attribute to `identity.SystemID`.** One shared bearer token, - no per-user session. `webAudit` in `internal/webui/api_identities.go` is the - only source. Named attribution needs a dashboard login first. +- **Dashboard writes attribute to `identity.SystemID`.** One shared bearer + token, no per-user session. `webAudit` in `internal/webui/api_identities.go` + is the only source. Named attribution needs a dashboard login first. - **`internal/webui` must not link the workflow engine.** It decodes definitions - with the projection types in `internal/domain/workflow/task`. `cmd/archie-ui`'s - deletion gate fails if anything reaches `internal/domain/workflow`. + with the projection types in `internal/domain/workflow/task`. + `cmd/archie-ui`'s deletion gate fails if anything reaches + `internal/domain/workflow`. - Shipped defaults ride `ResourceDescriptor.defaults_json`. The API is fixed at four operations, so defaults get no REST route. - `archie-messaging` fails closed when the State Store is unreachable. The @@ -85,18 +86,18 @@ This came from the session that just ended. Treat it as fact. boot. `docs/architecture/safe-change-and-recovery.md` records this posture. Resource history is the only in-band remedy and needs the State Store up. - **`task check` will not catch a field the server stopped sending.** Optional - chaining made a dead dashboard banner typecheck silently; `delivery-snapshot.sh` - scanned for a symbol its composition root no longer calls. Both fixed in - `85f0fd0b`. When a server-side field is deleted, grep the dashboard and the - snapshot scripts by name. Add this to every review task. -- **Reload re-reads the database layer and can fail.** `boot.runtimeConfig` is the - one layering call; the SIGHUP callback makes the same call over the document it - just resolved (`9af013eb`). A new database-owned layer goes in `runtimeConfig` - and nowhere else. + chaining made a dead dashboard banner typecheck silently; + `delivery-snapshot.sh` scanned for a symbol its composition root no longer + calls. Both fixed in `85f0fd0b`. When a server-side field is deleted, grep the + dashboard and the snapshot scripts by name. Add this to every review task. +- **Reload re-reads the database layer and can fail.** `boot.runtimeConfig` is + the one layering call; the SIGHUP callback makes the same call over the + document it just resolved (`9af013eb`). A new database-owned layer goes in + `runtimeConfig` and nowhere else. - **Apply status lives on the State Store contract, not the control plane.** `PutApplyStatus`/`ListApplyStatus` are administrative, keyed on - `(process, kind)`, replaced in place, re-stamped every 30s, stale at 90s, and a - stale record renders as "Not reporting", never as current. `applystatus.New` + `(process, kind)`, replaced in place, re-stamped every 30s, stale at 90s, and + a stale record renders as "Not reporting", never as current. `applystatus.New` refuses a process name `Processes()` does not list. - Five commits are local as of 2026-09-21: `731a9a06`, `1dd0d874`, `d9dd7885`, `9accf112`, `d38e27fd`. `archie-core-pskb` is closed. There is no post-commit @@ -109,31 +110,31 @@ This came from the session that just ended. Treat it as fact. Seven ready beads carry the `control-plane` label. Their real shape is what decides the lanes, and it is not the same as their titles. -| Bead | Title shape | Primary surface | -|------|-------------|-----------------| -| `archie-core-nwa0` | check a live replacement before switching to it | live apply path + apply-status surface | -| `archie-core-fwmp` | let plugins register workflow step types | `workflow.BuiltinStepRegistry()` and all five call sites | -| `archie-core-8szi` | registered steps covering the deleted `.archie` gate | `internal/domain/workflow/steps.go`, needs fwmp's answer | -| `archie-core-6zw0` | offline backup/restore/validate/rollback for `archie.db` | new `cmd/` binary + state-store infrastructure | -| `archie-core-i3qm` | stop TOML blocking State Store startup | `internal/app/archied/control_plane.go`, bootstrap validation | -| `archie-core-xrux` | `ApplyOverlayValues` is dead, confirm the file overlay | `internal/infrastructure/configuration/loader.go`, `apply.go` | -| `archie-core-eju6` | end-to-end restart test for a database-backed change | test only, proves the whole loop | +| Bead | Title shape | Primary surface | +| ------------------ | -------------------------------------------------------- | ------------------------------------------------------------- | +| `archie-core-nwa0` | check a live replacement before switching to it | live apply path + apply-status surface | +| `archie-core-fwmp` | let plugins register workflow step types | `workflow.BuiltinStepRegistry()` and all five call sites | +| `archie-core-8szi` | registered steps covering the deleted `.archie` gate | `internal/domain/workflow/steps.go`, needs fwmp's answer | +| `archie-core-6zw0` | offline backup/restore/validate/rollback for `archie.db` | new `cmd/` binary + state-store infrastructure | +| `archie-core-i3qm` | stop TOML blocking State Store startup | `internal/app/archied/control_plane.go`, bootstrap validation | +| `archie-core-xrux` | `ApplyOverlayValues` is dead, confirm the file overlay | `internal/infrastructure/configuration/loader.go`, `apply.go` | +| `archie-core-eju6` | end-to-end restart test for a database-backed change | test only, proves the whole loop | Three couplings you already know about, and Wave 0 exists to find the rest: -- **fwmp is the shared shape.** It changes the registry every call site hardcodes - (`app/agentworker/task_execution.go:319,:335`, - `app/controlplane/workflow_definitions.go:26,:33`, `app/controlplane/client.go:41`) - and the validating side and the executing side must resolve it identically. - 8szi has nothing to register against until fwmp lands. These two are never - concurrent writers. +- **fwmp is the shared shape.** It changes the registry every call site + hardcodes (`app/agentworker/task_execution.go:319,:335`, + `app/controlplane/workflow_definitions.go:26,:33`, + `app/controlplane/client.go:41`) and the validating side and the executing + side must resolve it identically. 8szi has nothing to register against until + fwmp lands. These two are never concurrent writers. - **xrux decides i3qm's blast radius.** xrux is an investigation with two opposite outcomes: either the file overlay zeroes omitted map fields, in which - case `foldOverrides` moves there and it is a live bug, or it does not, in which - case `apply.go`, `apply_test.go` and `Loader.ApplyOverlay` are deleted. Both - land in the same package i3qm rewrites. One lane owns both, in that order. - `archie-core-xrux` is a trap, not a cleanup. Read the bead before deleting - `apply.go`. + case `foldOverrides` moves there and it is a live bug, or it does not, in + which case `apply.go`, `apply_test.go` and `Loader.ApplyOverlay` are deleted. + Both land in the same package i3qm rewrites. One lane owns both, in that + order. `archie-core-xrux` is a trap, not a cleanup. Read the bead before + deleting `apply.go`. - **eju6 proves the others.** It goes last, against everything merged. --- @@ -143,11 +144,11 @@ Three couplings you already know about, and Wave 0 exists to find the rest: Run `subagent({ action: "models" })` first and pick exact `provider/id` strings. Bare ids resolve only when unique. Then print the table you resolved and use it. -| Tier | Used by | Pick | -|------|---------|------| -| Fast | recon, inventory, grep-shaped probes | cheapest capable, low or medium thinking. Default `ollama/deepseek-v4.1-flash:cloud`. | -| Strong | writers, integrator | best reasoning model authenticated here, high thinking. Prefer a `deepseek-v4-pro` class id if `models` lists one. | -| Review | reviewers, oracle | a **different family** from the writer that produced the diff. Model diversity catches different failure modes; it does not rescue an ambiguous prompt. | +| Tier | Used by | Pick | +| ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Fast | recon, inventory, grep-shaped probes | cheapest capable, low or medium thinking. Default `ollama/deepseek-v4.1-flash:cloud`. | +| Strong | writers, integrator | best reasoning model authenticated here, high thinking. Prefer a `deepseek-v4-pro` class id if `models` lists one. | +| Review | reviewers, oracle | a **different family** from the writer that produced the diff. Model diversity catches different failure modes; it does not rescue an ambiguous prompt. | If a tier cannot be resolved, say so and fall back to the session default rather than inventing an id. Provider 429s return from that model; do not kill a rate @@ -159,8 +160,8 @@ limited child, it keeps its context and recovers. Defaults in this install (`pi-subagents` 0.70.0) are not 64. -- `globalConcurrencyLimit` defaults to **20** concurrent children per run. Set it - explicitly on each top-level call. +- `globalConcurrencyLimit` defaults to **20** concurrent children per run. Set + it explicitly on each top-level call. - `maxSubagentSpawnsPerRun` defaults to **64** cumulative admissions per run tree, never refunded. Retries and fix passes spend it too. - **Each wave is its own top-level run, so each wave gets its own budget.** This @@ -169,24 +170,24 @@ Defaults in this install (`pi-subagents` 0.70.0) are not 64. Per-wave dials: -| Wave | Shape | `globalConcurrencyLimit` | `maxSubagentSpawnsPerRun` | -|------|-------|--------------------------|---------------------------| -| 0 recon | `runs.all`, read-only | 32 | 64 | -| 0R audit | `review.js`, angles `claims` | 16 | 24 | -| 1 shape-first | one writer plus one probe | 2 | 8 | -| 1R review | `review.js`, full angle set, one target | 12 | 16 | -| 2 writer lanes | `runs.lanes`, one worktree each | 4 | 32 | -| 2R review | `review.js`, full angle set, four targets | 24 | 48 | -| 3 fix pass | `runs.lanes`, retained writers | 4 | 24 | -| 4 merge train | serial, one `task check` at a time | 1 | 8 | -| 4R post-merge | `review.js` on merged `main`, angles `boundary`, `deadfield`, `contract` | 8 | 12 | -| 5 eju6 | one lane, then its own review | 2 | 12 | +| Wave | Shape | `globalConcurrencyLimit` | `maxSubagentSpawnsPerRun` | +| -------------- | ------------------------------------------------------------------------ | ------------------------ | ------------------------- | +| 0 recon | `runs.all`, read-only | 32 | 64 | +| 0R audit | `review.js`, angles `claims` | 16 | 24 | +| 1 shape-first | one writer plus one probe | 2 | 8 | +| 1R review | `review.js`, full angle set, one target | 12 | 16 | +| 2 writer lanes | `runs.lanes`, one worktree each | 4 | 32 | +| 2R review | `review.js`, full angle set, four targets | 24 | 48 | +| 3 fix pass | `runs.lanes`, retained writers | 4 | 24 | +| 4 merge train | serial, one `task check` at a time | 1 | 8 | +| 4R post-merge | `review.js` on merged `main`, angles `boundary`, `deadfield`, `contract` | 8 | 12 | +| 5 eju6 | one lane, then its own review | 2 | 12 | Do not set a hard `toolBudget` or a tight `usageBudget` on any writer, fix worker, or reviewer with edit authority: the default budget blocks read and search tools rather than mutation tools, which leaves a half-written tree. Bound -writers with `timeoutMs` plus `checkpointBeforeDeadlineMs` instead. Hard caps are -fine on explicitly read-only children. +writers with `timeoutMs` plus `checkpointBeforeDeadlineMs` instead. Hard caps +are fine on explicitly read-only children. --- @@ -206,7 +207,7 @@ Act on that as follows. - **WIP is capped by review, not by cores.** Four writer lanes exist because four is what the review pass and the merge train can absorb per cycle. Do not raise it to use spare concurrency. -- **Put the judgment upstream.** Before a writer starts, its task must carry +- **Put the judgement upstream.** Before a writer starts, its task must carry intent, acceptance criteria and non-goals, so verification has an external reference. "Does this do what it was supposed to do" is checkable; "does this look right" is not, and fluent output passes a read-through scan regardless of @@ -229,10 +230,11 @@ Act on that as follows. gets split at a coherent boundary. - **Route risk, do not review uniformly.** These surfaces get Sam's eyes before merge, named explicitly in your report: the fail-closed boot path - (`boot.runtimeConfig`, bootstrap validation), the State Store wire contract and - its error sentinels, task-scoped grants and credentials, anything that writes - or migrates `archie.db`, and the release or CI surface. Everything else merges - on gate plus reviewer verdict, with a sample called out for him to spot-check. + (`boot.runtimeConfig`, bootstrap validation), the State Store wire contract + and its error sentinels, task-scoped grants and credentials, anything that + writes or migrates `archie.db`, and the release or CI surface. Everything else + merges on gate plus reviewer verdict, with a sample called out for him to + spot-check. - **Watch the right numbers.** Report per wave: reviewer findings raised versus accepted, lanes blocked by gate versus by review, rework passes per lane, and wall-clock from lane start to merged. Lines written and beads closed measure @@ -242,11 +244,12 @@ Act on that as follows. ## 6. Wave 0: recon fanout (read-only, wide) -One top-level call, `async: true`, `workflowScriptPath: ".pi/control-plane-run/wave0.js"`. +One top-level call, `async: true`, +`workflowScriptPath: ".pi/control-plane-run/wave0.js"`. Three probes per bead, plus four cross-cutting probes: 25 children, all -`cp-recon`, all read-only, all returning structured output. The probe text is composed inside -`wave0.js`; do not retype it. +`cp-recon`, all read-only, all returning structured output. The probe text is +composed inside `wave0.js`; do not retype it. Per bead: @@ -261,8 +264,9 @@ Cross-cutting: - **overlap** — for all seven beads, the set of packages and files each one must modify, in one table. -- **gate-cost** — time `task build` and `go test ./internal/app/controlplane/...` - and report wall-clock, so Wave 2 timeouts are measured rather than guessed. +- **gate-cost** — time `task build` and + `go test ./internal/app/controlplane/...` and report wall-clock, so Wave 2 + timeouts are measured rather than guessed. - **dead-field** — grep `ui/src/` and `scripts/delivery-snapshot.sh` for every control-plane field name the server sends today, and flag any the server no longer sends. This is the failure class `task check` cannot see. @@ -271,12 +275,12 @@ Cross-cutting: the single test that would tie each pair together. Every probe returns `structuredOutput` matching the schema in `wave0.js`. Long -findings go to a file via `outputMode: "file-only"`; do not pull transcripts into -your context. +findings go to a file via `outputMode: "file-only"`; do not pull transcripts +into your context. -**Do not let a recon child draw the conclusion.** A scout that measures correctly -can still land the wrong call, and its write-up reads confident either way. Take -their facts, make the call yourself. +**Do not let a recon child draw the conclusion.** A scout that measures +correctly can still land the wrong call, and its write-up reads confident either +way. Take their facts, make the call yourself. --- @@ -316,7 +320,7 @@ Sub-prompts for both children are in `prompts/wave1.md`. 2. Merge fwmp through the Wave 4 train immediately, before Wave 2 starts. Wave 2 branches from the merged shape. 3. **xrux investigation** runs concurrently with fwmp, because it is read-only - until it has a verdict: one `cp-recon` writes a characterization test in a + until it has a verdict: one `cp-recon` writes a characterisation test in a scratch worktree that answers the single question, does `Loader.overlayFile` zero omitted fields of a map-valued entry. It returns the verdict and the test, and nothing else. The verdict decides the i3qm lane's stages. @@ -328,12 +332,12 @@ Sub-prompts for both children are in `prompts/wave1.md`. One top-level call, `runs.lanes`, `worktree: true` on every writer stage, `baseRef: "HEAD"` resolved after fwmp merged. Four lanes, concurrency 4. -| Lane | Beads | Stages | -|------|-------|--------| -| `live` | nwa0 | red, green, self-gate, challenge | -| `recovery` | 6zw0 | red, green, self-gate, challenge | -| `steps` | 8szi | red, green, self-gate, challenge | -| `config` | xrux then i3qm | verdict-apply, red, green, self-gate, challenge | +| Lane | Beads | Stages | +| ---------- | -------------- | ----------------------------------------------- | +| `live` | nwa0 | red, green, self-gate, challenge | +| `recovery` | 6zw0 | red, green, self-gate, challenge | +| `steps` | 8szi | red, green, self-gate, challenge | +| `config` | xrux then i3qm | verdict-apply, red, green, self-gate, challenge | Stage contract, enforced by `wave2.js` and the `cp-writer` agent definition: @@ -348,10 +352,10 @@ Stage contract, enforced by `wave2.js` and the `cp-writer` agent definition: and tail, plus the gate-gaming counters. Never `task check`. The evidence comes from the host, so a child cannot report a pass it did not get. - **challenge**: `resume: "previous"` against the same writer, with the - adversarial prompt built into `wave2.js`'s challenge stage. The writer still holds the - context; a fresh child pays for that context twice. Only resume a child - `children.list` reports as `resumable`; otherwise start a same-role fallback - and label it a fallback. + adversarial prompt built into `wave2.js`'s challenge stage. The writer still + holds the context; a fresh child pays for that context twice. Only resume a + child `children.list` reports as `resumable`; otherwise start a same-role + fallback and label it a fallback. Each lane's writer also returns the evidence handoff in `wave2.js`: intent, non-goals, files with reasons, alternatives rejected, commands run with pasted @@ -361,12 +365,14 @@ remains rather than growing further. Every writer opens by printing `pwd`, `git branch --show-current` and `git status --short`, and repeats that evidence in its final report. A worker -that finishes in the wrong checkout looks exactly like a worker that did nothing. +that finishes in the wrong checkout looks exactly like a worker that did +nothing. -A failed stage blocks only its lane. Do not repair a lane by hand and do not fall -back to running the work yourself, `pi -ne`, or an external CLI: a child launch -or tooling failure is a lane infrastructure blocker, so report the exact failure, -the run status, and the worktree state, then retry through the same path. +A failed stage blocks only its lane. Do not repair a lane by hand and do not +fall back to running the work yourself, `pi -ne`, or an external CLI: a child +launch or tooling failure is a lane infrastructure blocker, so report the exact +failure, the run status, and the worktree state, then retry through the same +path. --- @@ -378,13 +384,13 @@ angles live in that script: `bead`, `invariant`, `contract`, `deadfield`, `boundary`, `operator`, `tests`, `gaming`, `intent`, plus `claims` for auditing recon findings. -| After | Targets | Angles | -|-------|---------|--------| -| Wave 0 | the recon findings themselves | `claims` | -| Wave 1 | `cp/shape` | full set | -| Wave 2 | the four lane branches | full set | -| Wave 4 | merged `main` | `boundary`, `deadfield`, `contract` | -| Wave 5 | the eju6 branch | `tests`, `operator`, `intent` | +| After | Targets | Angles | +| ------ | ----------------------------- | ----------------------------------- | +| Wave 0 | the recon findings themselves | `claims` | +| Wave 1 | `cp/shape` | full set | +| Wave 2 | the four lane branches | full set | +| Wave 4 | merged `main` | `boundary`, `deadfield`, `contract` | +| Wave 5 | the eju6 branch | `tests`, `operator`, `intent` | The Wave 0 audit is the cheapest of these and catches the most: a recon child that measures correctly can still carry a wrong conclusion into your lane plan, @@ -425,22 +431,23 @@ One branch at a time, in dependency order, in the captain checkout at `fix(config): ...`). Include generated assets under `ui/dist/` in the same commit; they are LAW, never reverted or ignored. 6. `bd close `. Do not stage `.beads/`. -7. Verify it landed: `git log --oneline -1`, then - `git branch --no-merged main`. Done has three states: no commits, committed - and unmerged, merged. Only the third counts. +7. Verify it landed: `git log --oneline -1`, then `git branch --no-merged main`. + Done has three states: no commits, committed and unmerged, merged. Only the + third counts. -Your own edits get the same gate as the children's. A coordinator `sed` broke the -build on this repo once and nobody else reviews your diffs. +Your own edits get the same gate as the children's. A coordinator `sed` broke +the build on this repo once and nobody else reviews your diffs. --- ## 12. Wave 5: eju6 -Sub-prompt in `prompts/wave5-eju6.md`. Last, against merged `main`. One lane: an end-to-end test that drives a change -through the API, restarts a process, and asserts the change survived. Not a unit -test, and not a rewrite of `internal/app/controlplane/controlplane_test.go`, -which covers seeding and catalog only. This is the proof the whole feature works -across a restart, which nothing currently provides. +Sub-prompt in `prompts/wave5-eju6.md`. Last, against merged `main`. One lane: an +end-to-end test that drives a change through the API, restarts a process, and +asserts the change survived. Not a unit test, and not a rewrite of +`internal/app/controlplane/controlplane_test.go`, which covers seeding and +catalogue only. This is the proof the whole feature works across a restart, +which nothing currently provides. If it fails, that is a finding about the feature, not about the test. Report it and stop rather than weakening the assertion. @@ -451,7 +458,7 @@ and stop rather than weakening the assertion. - Beads closed, with the commit that closed each one. - Beads deliberately not attempted, and why. -- `task check` result on final `main`, quoted, not summarized. +- `task check` result on final `main`, quoted, not summarised. - Every branch still unmerged, and whether it holds work. - Commits now local and unpushed (`git log --oneline origin/main..main`), stated as fact without pushing. diff --git a/.agents/skills/archie-agent-fleet/references/worked-example/ABOUT.md b/.agents/skills/archie-agent-fleet/references/worked-example/ABOUT.md index b87b8c9bb..21d0aa842 100644 --- a/.agents/skills/archie-agent-fleet/references/worked-example/ABOUT.md +++ b/.agents/skills/archie-agent-fleet/references/worked-example/ABOUT.md @@ -22,13 +22,13 @@ briefs — none of the archie specifics here transfer. Seven tracker items, one shared shape, four lanes, a review pass after every wave, a serial merge train. -| File | Note | -|------|------| -| `00-orchestrator.md` | The filled orchestrator prompt. Section 2 is the project's ground truth, section 5a the review-is-the-constraint doctrine, section 10 the review cadence. | -| `lanes.json` | Lane briefs carrying intent, traps and `file:line` premises. Read one to see the level of detail a brief needs. | -| `prompts/wave1.md` | The shared shape, plus an investigation whose verdict gated another lane. | -| `prompts/wave4-merge-train.md` | The serial merge procedure with the project's own hazards in it. | -| `agents/` | The three agent definitions with project invariants inlined. | +| File | Note | +| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `00-orchestrator.md` | The filled orchestrator prompt. Section 2 is the project's ground truth, section 5a the review-is-the-constraint doctrine, section 10 the review cadence. | +| `lanes.json` | Lane briefs carrying intent, traps and `file:line` premises. Read one to see the level of detail a brief needs. | +| `prompts/wave1.md` | The shared shape, plus an investigation whose verdict gated another lane. | +| `prompts/wave4-merge-train.md` | The serial merge procedure with the project's own hazards in it. | +| `agents/` | The three agent definitions with project invariants inlined. | No scripts are copied here. This run's `wave0.js`, `wave2.js`, `review.js` and `gate-evidence.sh` became `templates/recon.js`, `templates/lanes.js`, diff --git a/.agents/skills/archie-agent-fleet/references/worked-example/README.md b/.agents/skills/archie-agent-fleet/references/worked-example/README.md index 34a5fc2db..697d5ec50 100644 --- a/.agents/skills/archie-agent-fleet/references/worked-example/README.md +++ b/.agents/skills/archie-agent-fleet/references/worked-example/README.md @@ -15,15 +15,15 @@ parent `archie-agent-fleet` skill. A run in another repository uses that skill's ## Files -| File | What it is | -|------|------------| -| `00-orchestrator.md` | The prompt you give pi. It owns the waves, the ceilings and the verification rules. | -| *(the scripts)* | This run's `wave0.js`, `wave2.js`, `review.js` and `gate-evidence.sh` are **not copied here**: they live on as `templates/recon.js`, `templates/lanes.js`, `templates/review.js` and `scripts/gate-evidence.sh` under `~/.agents/skills/high-throughput-programming/`, which are normative. The snapshot's copies were stale, so they were deleted rather than duplicated. | -| `lanes.json` | Lane definitions: worktree paths, branches, beads, scoped test commands, briefs. Fill in the model id. | -| `prompts/wave1.md` | fwmp shape-first writer, and the xrux verdict probe. | -| `prompts/wave4-merge-train.md` | The serial merge procedure and the landing checks. | -| `prompts/wave5-eju6.md` | The end-to-end restart test. | -| `agents/cp-recon.md`, `agents/cp-writer.md`, `agents/cp-reviewer.md` | Project-scope agent definitions, as the run used them from `.pi/agents/`; these committed copies sit beside this file. | +| File | What it is | +| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `00-orchestrator.md` | The prompt you give pi. It owns the waves, the ceilings and the verification rules. | +| _(the scripts)_ | This run's `wave0.js`, `wave2.js`, `review.js` and `gate-evidence.sh` are **not copied here**: they live on as `templates/recon.js`, `templates/lanes.js`, `templates/review.js` and `scripts/gate-evidence.sh` under `~/.agents/skills/high-throughput-programming/`, which are normative. The snapshot's copies were stale, so they were deleted rather than duplicated. | +| `lanes.json` | Lane definitions: worktree paths, branches, beads, scoped test commands, briefs. Fill in the model id. | +| `prompts/wave1.md` | fwmp shape-first writer, and the xrux verdict probe. | +| `prompts/wave4-merge-train.md` | The serial merge procedure and the landing checks. | +| `prompts/wave5-eju6.md` | The end-to-end restart test. | +| `agents/cp-recon.md`, `agents/cp-writer.md`, `agents/cp-reviewer.md` | Project-scope agent definitions, as the run used them from `.pi/agents/`; these committed copies sit beside this file. | ## Start it @@ -94,7 +94,7 @@ writers here. Two limits bite first: that has to land alone first. Five workers each adding a field to one struct cost eight cleanup commits on this repo in July. 2. **The machine.** 16 cores, 117 Go packages, and `task check` also runs the - dashboard tests. One full gate saturates the host, so the gate is serialized + dashboard tests. One full gate saturates the host, so the gate is serialised into the merge train and writers run package-scoped tests. The throughput comes from recon and review: 25 recon children, then a review diff --git a/.agents/skills/archie-agent-fleet/references/worked-example/agents/cp-recon.md b/.agents/skills/archie-agent-fleet/references/worked-example/agents/cp-recon.md index cd3c59f92..816615515 100644 --- a/.agents/skills/archie-agent-fleet/references/worked-example/agents/cp-recon.md +++ b/.agents/skills/archie-agent-fleet/references/worked-example/agents/cp-recon.md @@ -1,6 +1,8 @@ --- name: cp-recon -description: Read-only recon on archie-core. Traces call sites, extracts spec clauses, inventories tests. Returns citations, never conclusions. +description: + Read-only recon on archie-core. Traces call sites, extracts spec clauses, + inventories tests. Returns citations, never conclusions. tools: read, grep, find, ls, bash excludeTools: write, edit acceptanceRole: read-only @@ -12,16 +14,26 @@ thinking: high systemPromptMode: replace --- -You are a read-only investigator in the archie-core Go repository. You measure; you do not decide. +You are a read-only investigator in the archie-core Go repository. You measure; +you do not decide. Rules: -- Never edit, write, stage, commit, or run anything that mutates the tree. `bash` is for `git log`, `grep`, `go list`, `bd show`, and timing commands only. -- Every claim carries `file:line`. A claim without a citation is not a finding, it is a guess. -- Report facts. The orchestrator draws the conclusion. Do not recommend a course of action unless you were asked for one, and never close or reopen a bead. -- Grep first, then read only the lines that matter. Do not pull whole packages into context. +- Never edit, write, stage, commit, or run anything that mutates the tree. + `bash` is for `git log`, `grep`, `go list`, `bd show`, and timing commands + only. +- Every claim carries `file:line`. A claim without a citation is not a finding, + it is a guess. +- Report facts. The orchestrator draws the conclusion. Do not recommend a course + of action unless you were asked for one, and never close or reopen a bead. +- Grep first, then read only the lines that matter. Do not pull whole packages + into context. - Directory and bead names are not evidence of coupling. Check the imports. -- `ARCHITECTURE.md` and `CLAUDE.md` are stale by construction in this repo. The tree is the only evidence of current state; when a doc and the code disagree, report both and say which file you read. -- If your task's premise is false, say so plainly as your first line instead of answering the question you were asked. +- `ARCHITECTURE.md` and `CLAUDE.md` are stale by construction in this repo. The + tree is the only evidence of current state; when a doc and the code disagree, + report both and say which file you read. +- If your task's premise is false, say so plainly as your first line instead of + answering the question you were asked. -Finish with your structured output. Keep prose under 40 lines; long inventories belong in your output file. +Finish with your structured output. Keep prose under 40 lines; long inventories +belong in your output file. diff --git a/.agents/skills/archie-agent-fleet/references/worked-example/agents/cp-reviewer.md b/.agents/skills/archie-agent-fleet/references/worked-example/agents/cp-reviewer.md index 0dff99c86..96ba4f8dc 100644 --- a/.agents/skills/archie-agent-fleet/references/worked-example/agents/cp-reviewer.md +++ b/.agents/skills/archie-agent-fleet/references/worked-example/agents/cp-reviewer.md @@ -1,6 +1,8 @@ --- name: cp-reviewer -description: Read-only adversarial reviewer for one archie-core lane and one angle. Evidence-labelled findings and a single merge verdict. +description: + Read-only adversarial reviewer for one archie-core lane and one angle. + Evidence-labelled findings and a single merge verdict. tools: read, grep, find, ls, bash excludeTools: write, edit acceptanceRole: read-only @@ -12,23 +14,35 @@ thinking: high systemPromptMode: replace --- -You review one lane of archie-core work from one angle. You did not write this code and you do not fix it. +You review one lane of archie-core work from one angle. You did not write this +code and you do not fix it. -Start from `git diff main..` and `git diff --stat main..`. Review the diff, never the writer's transcript: the transcript costs context and carries almost no signal. +Start from `git diff main..` and `git diff --stat main..`. +Review the diff, never the writer's transcript: the transcript costs context and +carries almost no signal. What you are looking for, in order: -1. Behaviour the change dropped while keeping the shape. Refactors lose guards. Read every new or changed doc comment: one that describes a silent fallback is usually a confession. +1. Behaviour the change dropped while keeping the shape. Refactors lose guards. + Read every new or changed doc comment: one that describes a silent fallback + is usually a confession. 2. A claim in the diff that the code does not support. -3. A test that restates an assignment or a constant instead of failing for an interesting reason. +3. A test that restates an assignment or a constant instead of failing for an + interesting reason. 4. Two sides that must agree and have no test tying them together. Rules: - Read-only. Do not edit, stage, commit, or fix. Propose the fix in words. - Every finding carries `file:line` and a quoted proof. -- Label by evidence, not by how bad it sounds: P0 breaks a user-reachable path or an invariant, P1 is a real defect with a bounded blast radius, P2 is worth fixing but not now. -- "No finding" is a valid and useful answer. Do not manufacture findings to look thorough. -- `task check` passing is not evidence of correctness: it cannot see a field the server stopped sending, because optional chaining makes a dead dashboard binding typecheck. +- Label by evidence, not by how bad it sounds: P0 breaks a user-reachable path + or an invariant, P1 is a real defect with a bounded blast radius, P2 is worth + fixing but not now. +- "No finding" is a valid and useful answer. Do not manufacture findings to look + thorough. +- `task check` passing is not evidence of correctness: it cannot see a field the + server stopped sending, because optional chaining makes a dead dashboard + binding typecheck. -End with exactly one line: `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. +End with exactly one line: `Merge verdict: BLOCK`, `Merge verdict: OK`, or +`Merge verdict: OK with notes`. diff --git a/.agents/skills/archie-agent-fleet/references/worked-example/agents/cp-writer.md b/.agents/skills/archie-agent-fleet/references/worked-example/agents/cp-writer.md index 550a02ae1..c74461aab 100644 --- a/.agents/skills/archie-agent-fleet/references/worked-example/agents/cp-writer.md +++ b/.agents/skills/archie-agent-fleet/references/worked-example/agents/cp-writer.md @@ -1,6 +1,8 @@ --- name: cp-writer -description: Implementation worker for archie-core lanes. Red-green TDD in an isolated worktree, package-scoped gate, no suppression. +description: + Implementation worker for archie-core lanes. Red-green TDD in an isolated + worktree, package-scoped gate, no suppression. tools: read, write, edit, grep, find, ls, bash acceptanceRole: writer inheritProjectContext: true @@ -11,28 +13,43 @@ timeoutMs: 5400000 systemPromptMode: replace --- -You implement one lane of work in the archie-core Go repository, inside your own git worktree. +You implement one lane of work in the archie-core Go repository, inside your own +git worktree. -Open every run by printing `pwd`, `git branch --show-current` and `git status --short`, and repeat all three in your final report. A worker that finishes in the wrong checkout looks exactly like one that did nothing. +Open every run by printing `pwd`, `git branch --show-current` and +`git status --short`, and repeat all three in your final report. A worker that +finishes in the wrong checkout looks exactly like one that did nothing. Method: -1. Read the bead with `bd show `, then `CLAUDE.md` and `docs/architecture/organisation.md`. -2. Red: write the failing table-driven test first. Run it. Paste the failure. Confirm it fails on an assertion, not a compile error. A test that cannot fail for an interesting reason is noise in the gate. +1. Read the bead with `bd show `, then `CLAUDE.md` and + `docs/architecture/organisation.md`. +2. Red: write the failing table-driven test first. Run it. Paste the failure. + Confirm it fails on an assertion, not a compile error. A test that cannot + fail for an interesting reason is noise in the gate. 3. Green: the minimal implementation that satisfies the test. -4. Run your lane's scoped test command. Never run `task check`: it saturates the machine and the merge train owns it. -5. Commit on your lane branch with a conventional-commit subject scoped by package (`feat(controlplane): ...`). +4. Run your lane's scoped test command. Never run `task check`: it saturates the + machine and the merge train owns it. +5. Commit on your lane branch with a conventional-commit subject scoped by + package (`feat(controlplane): ...`). Hard rules: - Fix invalid state at the producer, not with a defensive check at the consumer. -- Never suppress: no `//nolint`, no `t.Skip`, no build tag that hides a failing test, no deleted assertion. If a lint is wrong, leave it failing and say why. +- Never suppress: no `//nolint`, no `t.Skip`, no build tag that hides a failing + test, no deleted assertion. If a lint is wrong, leave it failing and say why. - Adopt `task fmt` output verbatim. Never revert a formatter or linter diff. -- Two failed fixes on the same logic block means you rewrite the block, not patch it a third time. Prefer a clean 20-line rewrite over a 5-line band-aid. -- Dependency flow is `cmd -> app -> {domain, infrastructure}`, with infrastructure implementing domain contracts. Nothing in `internal/webui` may reach `internal/domain/workflow`. +- Two failed fixes on the same logic block means you rewrite the block, not + patch it a third time. Prefer a clean 20-line rewrite over a 5-line band-aid. +- Dependency flow is `cmd -> app -> {domain, infrastructure}`, with + infrastructure implementing domain contracts. Nothing in `internal/webui` may + reach `internal/domain/workflow`. - Do not widen scope. Work not asked for is a finding to report, not work to do. -- Do not merge, do not push, do not touch `.beads/`, do not edit the main checkout. +- Do not merge, do not push, do not touch `.beads/`, do not edit the main + checkout. - Scratch files live in `/tmp`. Never in the working tree. -- If the bead describes a world the tree no longer has, stop and report that instead of implementing it. +- If the bead describes a world the tree no longer has, stop and report that + instead of implementing it. -Your final report states: the commit sha, changed files, the scoped test command and its result, what you deliberately did not do, and any residual risk. +Your final report states: the commit sha, changed files, the scoped test command +and its result, what you deliberately did not do, and any residual risk. diff --git a/.agents/skills/archie-agent-fleet/references/worked-example/lanes.json b/.agents/skills/archie-agent-fleet/references/worked-example/lanes.json index a6313733c..27dbafb3d 100644 --- a/.agents/skills/archie-agent-fleet/references/worked-example/lanes.json +++ b/.agents/skills/archie-agent-fleet/references/worked-example/lanes.json @@ -6,9 +6,7 @@ "key": "live", "dir": "/work/apps/cp-live", "branch": "cp/live", - "beads": [ - "archie-core-nwa0" - ], + "beads": ["archie-core-nwa0"], "test": "go test ./internal/app/controlplane/... ./internal/domain/applystatus/... -count=1 && go vet ./internal/app/controlplane/... ./internal/domain/applystatus/...", "brief": "Wave 0 and its claims audit corrected this bead's premise, and the correction is the work. There is not one live apply path, there are two, and the PRD clause (Archie starts and checks a replacement before switching, and if the check fails the old one keeps running) applies to both. (1) workflow-execution-settings is applied on a watch (internal/app/archied/control_plane.go:94) and reports apply status at :118. (2) personas is also watched and applied live in the same process (internal/app/archied/gateway_runtime.go:37 watch, :79-86 apply) and reports NO apply status at all, so personas is the live-watched kind that widens this bead. Correction to the earlier version of this brief: workflow-definitions is not applied by a daemon watch, but do not read that as \"no watch anywhere\" -- the webui streams it at internal/webui/api_control_plane.go:139, which is a generic SSE passthrough for any kind. That is a read path, not a component-replacement path, so it does not widen nwa0. What the audit also established: the hard-coded nil at control_plane.go:118 is inert (no path in applyWorkflowExecutionSettings can fail), so do not build the bead around \"the report path cannot carry a rejection\"; that framing is wrong. Order of work: add the build-and-probe step to the live apply path, retain the previous component when the check fails, and report the failure through the apply-status surface. Decide explicitly whether personas gets the same treatment in this bead or a follow-up bead; if it is a follow-up, file the bead rather than half-wiring it. Do NOT fix the watch-reconnect defect opportunistically: it is filed separately as archie-core-yrmr, and a defect found by a review pass must not be silently repaired inside another lane. Apply status is on the State Store contract, not the control plane: PutApplyStatus/ListApplyStatus are administrative, keyed on (process, kind), replaced in place, re-stamped every 30s, stale at 90s, and a stale record renders as \"Not reporting\", never as current. applystatus.New refuses a process name Processes() does not list, deliberately: an invented name would read as a process that is not running, which the PRD blesses as legitimate, so the failure would be invisible." }, @@ -16,9 +14,7 @@ "key": "recovery", "dir": "/work/apps/cp-recovery", "branch": "cp/recovery", - "beads": [ - "archie-core-6zw0" - ], + "beads": ["archie-core-6zw0"], "test": "go test ./cmd/... ./internal/infrastructure/staterpc/... -count=1 && go vet ./cmd/...", "brief": "DECIDED: subcommands of cmd/archie-state-store (backup, restore, validate, rollback). Not a new binary. Sam's standing rule, restated 2026-09-21 and now recorded in docs/architecture/organisation.md#process-boundaries: a cmd/ entry is a process boundary, earned only when a surface fails independently of the rest of the fleet or when that process may need to run in more than one location (HA pair, NAT traversal, separate host). Operational commands over a surface an existing binary already owns are subcommands of it. Do not reopen this. Two premise corrections from Wave 0 that change the work. First, the file is /archie.db-tasks.sqlite (cmd/archie-state-store/main.go:290-292, asserted at main_test.go:435-439), not archie.db, so a command that operates on 'archie.db' by name operates on nothing. Second, part of this already exists in shell: scripts/archie-update-install:189 takes a sqlite3 .backup of the task database and describes it as the watchdog's only route back from a forward schema migration. That makes this bead partly consolidation. The subcommand becomes the one authoritative implementation and the install script calls it, rather than a Go path and a shell path that drift apart. Changing that script is in scope for this lane; the watchdog's refusal semantics (an update that cannot back up must not start) must survive the change unchanged. The command operates on the database file directly with the State Store stopped, refuses to run against a live store, and adds no rollback RPC: a revision carries its value and restoring replays it through the ordinary replace." }, @@ -26,9 +22,7 @@ "key": "steps", "dir": "/work/apps/cp-steps", "branch": "cp/steps", - "beads": [ - "archie-core-8szi" - ], + "beads": ["archie-core-8szi"], "test": "go test ./internal/domain/workflow/... ./internal/app/agentworker/... -count=1 && go vet ./internal/domain/workflow/...", "brief": "internal/domain/workflow/steps.go:215 and :227 hard-error on legacy .archie/stages/*.go and .archie/gate.go and tell the operator to migrate to a registered YAML workflow step, but BuiltinStepRegistry() only exposes the six shipped workflows' own stages, so there is nothing to migrate to. Identify what the removed hooks actually did and land the equivalent as registered step types. This lane starts only after archie-core-fwmp has merged, and registers against the extension point fwmp created. Do not re-open the registry design." }, @@ -36,10 +30,7 @@ "key": "config", "dir": "/work/apps/cp-config", "branch": "cp/config", - "beads": [ - "archie-core-xrux", - "archie-core-i3qm" - ], + "beads": ["archie-core-xrux", "archie-core-i3qm"], "test": "go test ./internal/infrastructure/configuration/... ./internal/app/archied/... -count=1 && go vet ./internal/infrastructure/configuration/... ./internal/app/archied/...", "brief": "Two beads in order, one package owner. First archie-core-xrux. The verdict is already measured with evidence (Wave 0R claims audit c6) and it is ZEROES: the -config-overlay file path silently drops every field a partial map-valued entry omits, which is exactly the archie-core-e2e2 hazard, and it is user-reachable because deployments/dev.toml is the documented -config-overlay argument and sets [services.state] target/listen, while the base config.toml is where [services.state].target_token lives -- so the overlay drops the token. The red stage is a committed characterization test through the production entry point (Loader.Resolve / -config-overlay) that loads a config with a populated map-valued entry, overlays a file setting one sibling key, and asserts the omitted keys survive; it fails today. Then move apply.go's foldOverrides (apply.go:60) onto the file overlay path (loader.go:161-194, decode at :176) so it passes. Do NOT delete apply.go, apply_test.go or Loader.ApplyOverlay: the hazard they were written for is live on that path. No dotted-path field merge is wanted beyond this guard, because the control plane replaces whole documents. Then archie-core-i3qm, whose anchor and scope the audit corrected. control_plane.go:13 is a blank line (the doc comment is :14-18); the calls moved to :20 (RuntimeConfig) and :27 (configuration.Validate) in 9accf112. More importantly the PRD clause names State Store startup, and state_store.go:75-104 never calls runtimeConfig: it reaches Loader.finalize via bootstrap.go:263 (the loader.Resolve call site, not finalize itself) and loader.go:341-346, where Validate runs. Scope correction: that file-only Validate runs before loadRuntimeConfig for ALL THREE binaries (main.go:358, gateway.go:61, state_store.go:78), so it is not state-store-specific; and a value that is valid alone but invalid only after the DB merge never blocks the state store at all, because it is imported unvalidated at state_store.go:104 and fails later in the daemon's loadRuntimeConfig (control_plane.go:27). Reduce the bootstrap document to the fields the PRD lists (database path, listen addresses, credentials, TLS, encryption-key references) and stop validating the migrated surface at startup, so a stale TOML value in a database-owned field cannot fail boot. boot.runtimeConfig is the one layering call and the SIGHUP callback makes the same call: if you add a database-owned layer, add it there and nowhere else." } diff --git a/.agents/skills/archie-agent-fleet/references/worked-example/prompts/wave1.md b/.agents/skills/archie-agent-fleet/references/worked-example/prompts/wave1.md index 977109252..1a4dc6b41 100644 --- a/.agents/skills/archie-agent-fleet/references/worked-example/prompts/wave1.md +++ b/.agents/skills/archie-agent-fleet/references/worked-example/prompts/wave1.md @@ -1,19 +1,20 @@ # Wave 1 sub-prompt: shape first -**One child. fwmp alone.** Nothing else runs until it merges, and Wave 2 branches -from the merged shape. +**One child. fwmp alone.** Nothing else runs until it merges, and Wave 2 +branches from the merged shape. xrux is no longer a Wave 1 probe. Its verdict is already measured with evidence -(Wave 0R claims audit c6) and the answer is **ZEROES**. Re-measuring buys nothing, -so the characterization test is folded into the `config` lane's red stage, where -it is committed and the evidence lives in the tree rather than in a transcript. -See the `config` brief in `lanes.json`. +(Wave 0R claims audit c6) and the answer is **ZEROES**. Re-measuring buys +nothing, so the characterisation test is folded into the `config` lane's red +stage, where it is committed and the evidence lives in the tree rather than in a +transcript. See the `config` brief in `lanes.json`. --- ## fwmp: the shared shape (cp-writer, worktree `/work/apps/cp-shape`, branch `cp/shape`) -Gate: `go test ./internal/domain/workflow/... ./internal/app/controlplane/... ./internal/app/agentworker/... -count=1` +Gate: +`go test ./internal/domain/workflow/... ./internal/app/controlplane/... ./internal/app/agentworker/... -count=1` ```text Bead archie-core-fwmp. Run `bd show archie-core-fwmp` first. diff --git a/.agents/skills/archie-agent-fleet/references/worked-example/prompts/wave4-merge-train.md b/.agents/skills/archie-agent-fleet/references/worked-example/prompts/wave4-merge-train.md index a604ab13f..4ca14efa3 100644 --- a/.agents/skills/archie-agent-fleet/references/worked-example/prompts/wave4-merge-train.md +++ b/.agents/skills/archie-agent-fleet/references/worked-example/prompts/wave4-merge-train.md @@ -29,7 +29,11 @@ Then: 1. `git merge --no-ff $BR` (or apply the lane's handoff patch if the lane ran in a managed worktree). -2. `task build --force`, then `task check`, once, alone. Nothing else runs on this machine while it does. The force-build is required until archie-core-hhgw lands: `task build`'s sources are Go-only (Taskfile.yml:325), so a ui/dist-only change does not retrigger it and a stale embedded dashboard would ship (Wave 0R audit c10). +2. `task build --force`, then `task check`, once, alone. Nothing else runs on + this machine while it does. The force-build is required until + archie-core-hhgw lands: `task build`'s sources are Go-only + (Taskfile.yml:325), so a ui/dist-only change does not retrigger it and a + stale embedded dashboard would ship (Wave 0R audit c10). 3. On failure: one fix pass back to that lane's retained writer with the real output pasted in, not a summary. On a second failure, `git reset --hard` the merge, requeue the lane, and move to the next branch. Do not stack a third diff --git a/.agents/skills/archie-agent-fleet/references/worked-example/prompts/wave5-eju6.md b/.agents/skills/archie-agent-fleet/references/worked-example/prompts/wave5-eju6.md index c47de9554..5b0192e55 100644 --- a/.agents/skills/archie-agent-fleet/references/worked-example/prompts/wave5-eju6.md +++ b/.agents/skills/archie-agent-fleet/references/worked-example/prompts/wave5-eju6.md @@ -3,8 +3,8 @@ One lane, one `cp-writer`, against merged `main`. This is the only bead that proves the feature rather than adding to it, so it runs last and alone. -Gate: `cd && go test ./internal/app/controlplane/... -count=1`, -then `task check` through the merge train as usual. +Gate: `cd && go test ./internal/app/controlplane/... -count=1`, then +`task check` through the merge train as usual. ```text Bead archie-core-eju6. Run `bd show archie-core-eju6` first. diff --git a/.agents/skills/archie-architecture-contract/SKILL.md b/.agents/skills/archie-architecture-contract/SKILL.md index 4aefe05e5..831753e5b 100644 --- a/.agents/skills/archie-architecture-contract/SKILL.md +++ b/.agents/skills/archie-architecture-contract/SKILL.md @@ -2,13 +2,13 @@ name: archie-architecture-contract description: >- Protect Archie's load-bearing architecture while placing, implementing, or - reviewing behavior. Load this skill before changing daemon composition, + reviewing behaviour. Load this skill before changing daemon composition, domains, workflows, task lifecycle, agent execution, messaging, work intake, identity, memory, configuration, plugins, policies, persistence, NATS/RPC, containers, or process boundaries; use it when deciding where new code belongs, enforcing dependency direction, separating current runtime truth from the approved target and open migration decisions, or ensuring every - behavior has one authoritative path. Route proof of duplication, dead-code + behaviour has one authoritative path. Route proof of duplication, dead-code disposition, production reachability, and maintainability to archie-technical-accountability. --- @@ -16,15 +16,15 @@ description: >- # Archie Architecture Contract Treat architecture as executable safety policy. Preserve one understandable -owner and one production path for each behavior. +owner and one production path for each behaviour. ## Read status before code -| Label | Meaning | Authority | -| --- | --- | --- | -| **CURRENT** | Behavior present in live code and production composition as of 2026-09-18. | Code, tests, and `internal/app/archied` wiring (`cmd/archied/main.go` is a thin dispatcher) | -| **APPROVED TARGET** | Direction an implementation must approach, but which may not exist on disk. | `docs/prds/01-project-management.md` and documents whose status says approved | -| **OPEN** | A migration or API decision no implementer may invent locally. | `docs/architecture/migration-decisions.md` and documents marked in progress or under design | +| Label | Meaning | Authority | +| ------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | +| **CURRENT** | Behaviour present in live code and production composition as of 2026-09-18. | Code, tests, and `internal/app/archied` wiring (`cmd/archied/main.go` is a thin dispatcher) | +| **APPROVED TARGET** | Direction an implementation must approach, but which may not exist on disk. | `docs/prds/01-project-management.md` and documents whose status says approved | +| **OPEN** | A migration or API decision no implementer may invent locally. | `docs/architecture/migration-decisions.md` and documents marked in progress or under design | > **Do not implement target prose as though it describes current code.** > Before treating a target package as available, prove that it exists and is @@ -35,9 +35,9 @@ owner and one production path for each behavior. Resolve apparent disagreement in this order: -1. Read live code and production composition for CURRENT behavior. +1. Read live code and production composition for CURRENT behaviour. 2. Read `docs/prds/01-project-management.md` for APPROVED TARGET ownership. -3. Read the focused decision document for the selected behavior. +3. Read the focused decision document for the selected behaviour. 4. Read `docs/architecture/migration-decisions.md` for OPEN work. 5. Stop and use `archie-architecture-planning-campaign` if a required semantic decision remains open. @@ -56,20 +56,20 @@ Also: `cmd/archied/main.go` is a thin dispatcher; the wiring lives in Do not simplify these facts into the target model: -| Concern | CURRENT runtime truth on 2026-09-18 | Evidence | -| --- | --- | --- | -| Composition | `cmd/archied/main.go` dispatches to `internal/app/archied.Run()`, which performs construction and wiring in `bootstrap.go`. | `cmd/archied/main.go`; `internal/app/archied/` | -| Durable work | `task.Task` combines forge/chat source data, workflow position, output, retry, identity, and PR state. | `internal/domain/workflow/task/task.go`; `internal/domain/storecontract/storecontract.go` | -| Workflow | `internal/domain/workflow` routes a `task.Task` into a `map[string]Workflow`, mutates a broad `TaskContext` through sequential stages. | `internal/domain/workflow/workflow.go` | -| Agent-stage boundary | Versioned `agentexec.Request`/`Result` carries one autonomous stage; validation correlates task, attempt, and stage. | `internal/agentexec/protocol.go` | -| Container handoff | `internal/taskrun` carries entire task plus `config.Repo` and `config.TaskConfig`; `internal/app/agentworker` owns routing and sequencing while its NATS adapter owns wire mechanics. | `internal/taskrun/taskrun.go`; `internal/app/agentworker/`; `internal/infrastructure/agenttransport/nats/` | -| Git ownership | Daemon-owned worktree operations clone, commit, push, diff, and clean up. | `internal/worktree/`; `internal/domain/workflow/steps.go`; `docs/architecture/agent-system.md` | -| Enforcement | Gates, read-only/protected paths, TDD inverted test gates, and diff caps are represented outside prompt prose. | `internal/gate/`; `internal/domain/workflow/{agent,tdd,steps}.go` | -| Configuration | `internal/config.Config`, `IdentityConfig`, `Repo`, and task snapshots mix input decoding with runtime concerns. Decoding itself lives in `internal/infrastructure/configuration`. | `internal/config/config.go`; `internal/infrastructure/configuration/` | -| Identity | Configured names and bot usernames act as process-local identity keys. There is no durable Identity domain. | `internal/daemon/daemon.go`; `internal/domain/storecontract/storecontract.go`; `internal/gateway/session.go` | -| Messaging | `internal/gateway` contains both the `Message` struct flow and richer `MessageEvent`; channel routing and task control are mixed with conversational behavior. | `internal/gateway/{gateway,messageevent,tasks}.go`; `internal/channels/` | -| Plugins | `plugin.Plugin` exposes only `Name` and `Version`; current loading interprets operator-installed Go files with Yaegi. | `internal/plugin/plugin.go` | -| Processes | Agent modes include in-process, subprocess, and NATS. Optional containers add a distinct boundary with known gaps. | `internal/config/config.go`; `internal/app/archied/`; `docs/architecture/organisation.md` | +| Concern | CURRENT runtime truth on 2026-09-18 | Evidence | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| Composition | `cmd/archied/main.go` dispatches to `internal/app/archied.Run()`, which performs construction and wiring in `bootstrap.go`. | `cmd/archied/main.go`; `internal/app/archied/` | +| Durable work | `task.Task` combines forge/chat source data, workflow position, output, retry, identity, and PR state. | `internal/domain/workflow/task/task.go`; `internal/domain/storecontract/storecontract.go` | +| Workflow | `internal/domain/workflow` routes a `task.Task` into a `map[string]Workflow`, mutates a broad `TaskContext` through sequential stages. | `internal/domain/workflow/workflow.go` | +| Agent-stage boundary | Versioned `agentexec.Request`/`Result` carries one autonomous stage; validation correlates task, attempt, and stage. | `internal/agentexec/protocol.go` | +| Container handoff | `internal/taskrun` carries entire task plus `config.Repo` and `config.TaskConfig`; `internal/app/agentworker` owns routing and sequencing while its NATS adapter owns wire mechanics. | `internal/taskrun/taskrun.go`; `internal/app/agentworker/`; `internal/infrastructure/agenttransport/nats/` | +| Git ownership | Daemon-owned worktree operations clone, commit, push, diff, and clean up. | `internal/worktree/`; `internal/domain/workflow/steps.go`; `docs/architecture/agent-system.md` | +| Enforcement | Gates, read-only/protected paths, TDD inverted test gates, and diff caps are represented outside prompt prose. | `internal/gate/`; `internal/domain/workflow/{agent,tdd,steps}.go` | +| Configuration | `internal/config.Config`, `IdentityConfig`, `Repo`, and task snapshots mix input decoding with runtime concerns. Decoding itself lives in `internal/infrastructure/configuration`. | `internal/config/config.go`; `internal/infrastructure/configuration/` | +| Identity | Configured names and bot usernames act as process-local identity keys. There is no durable Identity domain. | `internal/daemon/daemon.go`; `internal/domain/storecontract/storecontract.go`; `internal/gateway/session.go` | +| Messaging | `internal/gateway` contains both the `Message` struct flow and richer `MessageEvent`; channel routing and task control are mixed with conversational behaviour. | `internal/gateway/{gateway,messageevent,tasks}.go`; `internal/channels/` | +| Plugins | `plugin.Plugin` exposes only `Name` and `Version`; current loading interprets operator-installed Go files with Yaegi. | `internal/plugin/plugin.go` | +| Processes | Agent modes include in-process, subprocess, and NATS. Optional containers add a distinct boundary with known gaps. | `internal/config/config.go`; `internal/app/archied/`; `docs/architecture/organisation.md` | ### Interpret the current lifecycle honestly @@ -91,22 +91,22 @@ and runs the status update plus the transition-history insert in one transaction (`internal/infrastructure/postgres/store.go`). The sentinel crosses the State Store gRPC boundary via `mapError`/`unmapError` in `internal/infrastructure/staterpc/values.go`; its canonical message string is -part of the wire contract. Earlier non-atomic behavior is the settled fix, +part of the wire contract. Earlier non-atomic behaviour is the settled fix, not an open design. ## Preserve the load-bearing invariants -| Invariant | Required action | Status and source | -| --- | --- | --- | -| The model never runs git | Keep clone, branch, commit, push, diff, and cleanup in deterministic workspace/worktree steps. | CURRENT: `docs/architecture/agent-system.md`; `internal/worktree/` | -| Deterministic constraints outrank prompts | Enforce gates, protected paths, read-only stages, test protection, and change caps outside model instructions. | CURRENT: `docs/architecture/agent-system.md`; `internal/gate/`; `internal/domain/workflow/` | -| Agent execution is a data boundary | Send bounded, versioned input; validate correlated output before applying it. | CURRENT foundation: `internal/agentexec/protocol.go`; `docs/architecture/agent-system.md` | -| Every workflow ends explicitly | Preserve terminal outcome or visible park. Preserve crash recovery of interrupted `running` work. | CURRENT: `internal/domain/workflow/workflow.go`; `internal/infrastructure/postgres/store.go` | -| Generic plugins stay metadata-only | Keep `plugin.Plugin` at `Name()`/`Version()`. Behavior on typed capability interface with owning `Registry`/`Manager`. | CURRENT-enforced rule: `internal/plugin/architecture_test.go` | -| Capability engines own lifecycle | Give resource-owning engines explicit start/health/stop semantics and failure isolation. | APPROVED rule: `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict` | -| Trust is explicit | Treat trusted operator-installed in-process code, repository code, out-of-process integrations, and container-isolated code as different trust classes. | APPROVED rule: `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict` | -| Infrastructure stays replaceable | Keep forge, persistence, workspace, transport, container, and model details behind behavior-owned contracts. | APPROVED TARGET: `docs/architecture/dependencies-and-contracts.md` | -| Same-repository execution serializes by default | Preserve default unless explicit scheduling policy permits concurrency. | CURRENT: `internal/config/config.go`; `internal/daemon/daemon.go` | +| Invariant | Required action | Status and source | +| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | +| The model never runs git | Keep clone, branch, commit, push, diff, and cleanup in deterministic workspace/worktree steps. | CURRENT: `docs/architecture/agent-system.md`; `internal/worktree/` | +| Deterministic constraints outrank prompts | Enforce gates, protected paths, read-only stages, test protection, and change caps outside model instructions. | CURRENT: `docs/architecture/agent-system.md`; `internal/gate/`; `internal/domain/workflow/` | +| Agent execution is a data boundary | Send bounded, versioned input; validate correlated output before applying it. | CURRENT foundation: `internal/agentexec/protocol.go`; `docs/architecture/agent-system.md` | +| Every workflow ends explicitly | Preserve terminal outcome or visible park. Preserve crash recovery of interrupted `running` work. | CURRENT: `internal/domain/workflow/workflow.go`; `internal/infrastructure/postgres/store.go` | +| Generic plugins stay metadata-only | Keep `plugin.Plugin` at `Name()`/`Version()`. Behaviour on typed capability interface with owning `Registry`/`Manager`. | CURRENT-enforced rule: `internal/plugin/architecture_test.go` | +| Capability engines own lifecycle | Give resource-owning engines explicit start/health/stop semantics and failure isolation. | APPROVED rule: `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict` | +| Trust is explicit | Treat trusted operator-installed in-process code, repository code, out-of-process integrations, and container-isolated code as different trust classes. | APPROVED rule: `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict` | +| Infrastructure stays replaceable | Keep forge, persistence, workspace, transport, container, and model details behind behaviour-owned contracts. | APPROVED TARGET: `docs/architecture/dependencies-and-contracts.md` | +| Same-repository execution serialises by default | Preserve default unless explicit scheduling policy permits concurrency. | CURRENT: `internal/config/config.go`; `internal/daemon/daemon.go` | Run the mechanical plugin guard after changing any plugin or `*Engine` interface: @@ -129,7 +129,7 @@ domain and shared application contracts <- infrastructure implementations application composition ``` -1. Put cohesive behavior, vocabulary, state, commands, events, policies, +1. Put cohesive behaviour, vocabulary, state, commands, events, policies, runtime settings, and required service interfaces with its owning domain. 2. Make infrastructure implement domain-required interfaces and translate external representations. @@ -149,7 +149,7 @@ channel-neutral Message -> Agent turn -> optional proposed work ``` - **Messaging** owns canonical messages, conversations, branches, channel correlation, delivery. -- **Agent** owns persistent assistant, continuity, specialization, memory. +- **Agent** owns persistent assistant, continuity, specialisation, memory. - **Work Intake** owns admission, validation, routing, accepted-work-request handoff. - **Workflow** owns versioned definitions, steps, executions, attempts, outcomes. @@ -164,12 +164,12 @@ Sources: `docs/architecture/migration-decisions.md`, Use immutable `IdentityID` for target attribution. Keep Identity separate from Agent. Four fixed memory scopes: -| Scope | Visibility | -| --- | --- | -| Global shared | Shared across Archie | -| Agent-wide | One Agent across users; private by default | -| User-wide | One user across authorized Agents | -| Agent-user relationship | Exactly one Agent and one user | +| Scope | Visibility | +| ----------------------- | ------------------------------------------ | +| Global shared | Shared across Archie | +| Agent-wide | One Agent across users; private by default | +| User-wide | One user across authorised Agents | +| Agent-user relationship | Exactly one Agent and one user | Do not use conversation branching as a fifth memory scope. @@ -184,53 +184,53 @@ Treat `internal/config` as migration source inventory: - let each domain or plugin own typed runtime settings; - translate external DTOs in `internal/app`; - never pass complete application config into a domain; -- classify each behavioral value as invariant, runtime setting, policy value, +- classify each behavioural value as invariant, runtime setting, policy value, derived value, or runtime state. Source: `docs/architecture/configuration.md`. -## Place new behavior deliberately +## Place new behaviour deliberately -| Behavior | Target owner/location | Decision gate | -| --- | --- | --- | -| Persistent actor lifecycle and attribution | `internal/domain/identity` | Do not mix authentication/access policy into Identity. | -| Persistent assistant behavior and continuity | `internal/domain/agent` | Keep model/provider replaceable; do not fold Workflow into Agent. | -| Workflow definitions, steps, executions, attempts, outcomes | `internal/domain/workflow` | Preserve version ownership and one authoritative lifecycle. | -| Canonical messages, conversations, branches, delivery | `internal/domain/messaging` | Keep platform IDs as external correlation. | -| Admission and deterministic routing of proposed durable work | `internal/domain/workintake` | Emit an accepted request; do not construct execution state. | -| Generic plugin identity/discovery/compatibility/lifecycle | `internal/domain/plugin` | Keep generic contract metadata-only. | -| Capability-specific plugin behavior | Owning domain's typed registry/manager | Never add behavior to `plugin.Plugin`. | -| Broker-neutral publication/subscription mechanics | `internal/eventbus` | Keep message meaning and schemas with their domain. | -| Shared policy evaluation/evidence mechanics | No current package. `internal/policy` was the planned location; as of 2026-09-18 policy lives inside playbook bindings (`playbooks/`, `internal/domain/eda/playbook`) and `internal/gate/`. | Keep policy vocabulary, evaluators, and consequences with consuming domain. | -| NATS, PostgreSQL, forge, config decoding, external SDK adapters | `internal/infrastructure/` | Implement a narrow owner-defined contract; translate at boundary. | -| Construction, cross-domain connection, startup/shutdown | `internal/app/archied` or `internal/app/agentworker` | Keep `cmd/*` thin; define health and shutdown order. | -| Deploy assembly | `deployments/` | Do not move application behavior into deployment files. | -| Unreviewed memory/tools/workspace/gate/storage/web/RPC/scheduling | **OPEN** | Run `archie-architecture-planning-campaign`. | +| Behaviour | Target owner/location | Decision gate | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | +| Persistent actor lifecycle and attribution | `internal/domain/identity` | Do not mix authentication/access policy into Identity. | +| Persistent assistant behaviour and continuity | `internal/domain/agent` | Keep model/provider replaceable; do not fold Workflow into Agent. | +| Workflow definitions, steps, executions, attempts, outcomes | `internal/domain/workflow` | Preserve version ownership and one authoritative lifecycle. | +| Canonical messages, conversations, branches, delivery | `internal/domain/messaging` | Keep platform IDs as external correlation. | +| Admission and deterministic routing of proposed durable work | `internal/domain/workintake` | Emit an accepted request; do not construct execution state. | +| Generic plugin identity/discovery/compatibility/lifecycle | `internal/domain/plugin` | Keep generic contract metadata-only. | +| Capability-specific plugin behaviour | Owning domain's typed registry/manager | Never add behaviour to `plugin.Plugin`. | +| Broker-neutral publication/subscription mechanics | `internal/eventbus` | Keep message meaning and schemas with their domain. | +| Shared policy evaluation/evidence mechanics | No current package. `internal/policy` was the planned location; as of 2026-09-18 policy lives inside playbook bindings (`playbooks/`, `internal/domain/eda/playbook`) and `internal/gate/`. | Keep policy vocabulary, evaluators, and consequences with consuming domain. | +| NATS, PostgreSQL, forge, config decoding, external SDK adapters | `internal/infrastructure/` | Implement a narrow owner-defined contract; translate at boundary. | +| Construction, cross-domain connection, startup/shutdown | `internal/app/archied` or `internal/app/agentworker` | Keep `cmd/*` thin; define health and shutdown order. | +| Deploy assembly | `deployments/` | Do not move application behaviour into deployment files. | +| Unreviewed memory/tools/workspace/gate/storage/web/RPC/scheduling | **OPEN** | Run `archie-architecture-planning-campaign`. | ## Confront known weak points -| Weak point on 2026-09-18 | Required response | -| --- | --- | -| `TaskContext` is a mutable service bag with config, services, policy, scratch state. | Design narrow step inputs and staged removal. | -| Workflow lifecycle split across store, daemon, workflow, gateway, worker. | Trace every writer and reader before changing status. | -| State changes and transition history were non-atomic and `from` was advisory — **settled** in `internal/infrastructure/postgres`: `Transition` guards on the current status and writes status plus history in one transaction. | Keep every status writer behind `Transition`; do not reintroduce a raw `UPDATE tasks SET status`. | -| In-process and container paths put orchestration on different sides of process boundary. | Decide which path survives before extending both. | -| Identity uses strings; task uniqueness/NATS dedup omit identity. | Don't promise multi-identity ownership until canonical IDs migrate. | -| Container RPC uses root forge/worktree, not task owner's identity. | Known trust/correctness defect — not identity-isolated. | -| Missing `task.json` makes `archie-agent` join shared queue. | Fail closed before treating as isolated. | -| Subprocess uses daemon user and host access. | Not a security boundary. | -| Gateway formerly duplicated lifecycle strings, competing message contracts. | No third contract or direct lifecycle mutation path; status constants live in `internal/domain/workflow`. | -| Global config and `IdentityConfig` combine unrelated owners. | Don't rename global structure or add `Extra` map. | -| Memory has fixed scope requirements but OPEN final placement/migration. | Preserve scope isolation; focused design before moving. | -| Tests can make unused/duplicate code appear legitimate. | Prove production reachability from composition. | +| Weak point on 2026-09-18 | Required response | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | +| `TaskContext` is a mutable service bag with config, services, policy, scratch state. | Design narrow step inputs and staged removal. | +| Workflow lifecycle split across store, daemon, workflow, gateway, worker. | Trace every writer and reader before changing status. | +| State changes and transition history were non-atomic and `from` was advisory — **settled** in `internal/infrastructure/postgres`: `Transition` guards on the current status and writes status plus history in one transaction. | Keep every status writer behind `Transition`; do not reintroduce a raw `UPDATE tasks SET status`. | +| In-process and container paths put orchestration on different sides of process boundary. | Decide which path survives before extending both. | +| Identity uses strings; task uniqueness/NATS dedup omit identity. | Don't promise multi-identity ownership until canonical IDs migrate. | +| Container RPC uses root forge/worktree, not task owner's identity. | Known trust/correctness defect — not identity-isolated. | +| Missing `task.json` makes `archie-agent` join shared queue. | Fail closed before treating as isolated. | +| Subprocess uses daemon user and host access. | Not a security boundary. | +| Gateway formerly duplicated lifecycle strings, competing message contracts. | No third contract or direct lifecycle mutation path; status constants live in `internal/domain/workflow`. | +| Global config and `IdentityConfig` combine unrelated owners. | Don't rename global structure or add `Extra` map. | +| Memory has fixed scope requirements but OPEN final placement/migration. | Preserve scope isolation; focused design before moving. | +| Tests can make unused/duplicate code appear legitimate. | Prove production reachability from composition. | ## Control every architecture-affecting change -| Class | Action | -| --- | --- | -| Current-path repair | Stay inside current owner, preserve invariants. | -| Migration slice | Record current/target owner, contracts, compatibility adapter, cutover, deletion criteria. | -| New/changed architecture | Stop; run `archie-architecture-planning-campaign` until approved. | +| Class | Action | +| ------------------------ | ------------------------------------------------------------------------------------------ | +| Current-path repair | Stay inside current owner, preserve invariants. | +| Migration slice | Record current/target owner, contracts, compatibility adapter, cutover, deletion criteria. | +| New/changed architecture | Stop; run `archie-architecture-planning-campaign` until approved. | Trace with evidence: diff --git a/.agents/skills/archie-build-and-env/SKILL.md b/.agents/skills/archie-build-and-env/SKILL.md index f7b02e80e..22d47ebef 100644 --- a/.agents/skills/archie-build-and-env/SKILL.md +++ b/.agents/skills/archie-build-and-env/SKILL.md @@ -13,14 +13,14 @@ All volatile observations are snapshots from **2026-09-18** (HEAD `2e1e1549`). ## Name the surfaces -| Term | Meaning here | -|---|---| -| Repository root | Directory containing `go.mod`, `Taskfile.yml`, and `CLAUDE.md`. | -| Runtime module | Root Go module `github.com/samcharles93/archie-core`. | -| Tools module | Independent nested Go module under `tools/`. | -| Docs | Markdown under `docs/`, read directly; no build, no renderer. | -| Cold cache | Dependency cache not yet containing required modules/packages. | -| Restricted sandbox | May allow file reads but deny loopback listeners, container engine, or writes to default caches. | +| Term | Meaning here | +| ------------------ | ----------------------------------------------------------------------------------------------------------------- | +| Repository root | Directory containing `go.mod`, `Taskfile.yml`, and `CLAUDE.md`. | +| Runtime module | Root Go module `github.com/samcharles93/archie-core`. | +| Tools module | Independent nested Go module under `tools/`. | +| Docs | Markdown and generated JSON under `docs/`; an external Astro website renders and deploys the generated artifacts. | +| Cold cache | Dependency cache not yet containing required modules/packages. | +| Restricted sandbox | May allow file reads but deny loopback listeners, container engine, or writes to default caches. | No root `README*` or `CONTRIBUTING*` file exists. Begin with: @@ -55,15 +55,15 @@ cannot type-check them and deletes a genuinely used `internal/secret` import, so `.golangci.yml` excludes those exact files from the formatter set. Their runtime loading remains covered by `internal/secret/engines_test.go`. -| Surface | Repository declaration | Installed snapshot | Interpretation | -|---|---|---|---| -| Runtime Go | `go 1.27.0` in `go.mod` | Go 1.27.0, linux/amd64 | Requires at least declared Go level. | -| Tools Go | `go 1.27.0` in `tools/go.mod` | Same Go 1.27.0 binary | Toolchain must satisfy both modules. | -| Task | Taskfile schema `version: "3"` | Task 3.48.0 | Installed version is environment fact. | -| gofumpt | Generated protobuf formatting; pinned in `Dockerfile` | v0.11.0 | Not the ordinary source formatter. | -| golangci-lint | v2 config in `.golangci.yml`; pinned in `Dockerfile` | 2.13.2 | Owns ordinary formatting and lint checks. | -| Node | `ui/` frontend build | 26.9.0 / npm 11.19.1 | No `engines`/`packageManager` field. Docs need no Node. | -| Containers | Compose commands in `Taskfile.yml` | Podman-backed, unusable in this sandbox | Verify CLI, Compose plugin, daemon/socket separately. | +| Surface | Repository declaration | Installed snapshot | Interpretation | +| ------------- | ----------------------------------------------------- | --------------------------------------- | ------------------------------------------------------- | +| Runtime Go | `go 1.27.0` in `go.mod` | Go 1.27.0, linux/amd64 | Requires at least declared Go level. | +| Tools Go | `go 1.27.0` in `tools/go.mod` | Same Go 1.27.0 binary | Toolchain must satisfy both modules. | +| Task | Taskfile schema `version: "3"` | Task 3.48.0 | Installed version is environment fact. | +| gofumpt | Generated protobuf formatting; pinned in `Dockerfile` | v0.11.0 | Not the ordinary source formatter. | +| golangci-lint | v2 config in `.golangci.yml`; pinned in `Dockerfile` | 2.13.2 | Owns ordinary formatting and lint checks. | +| Node | `ui/` frontend build | 26.9.0 / npm 11.19.1 | No `engines`/`packageManager` field. Docs need no Node. | +| Containers | Compose commands in `Taskfile.yml` | Podman-backed, unusable in this sandbox | Verify CLI, Compose plugin, daemon/socket separately. | ## Prepare writable caches in a restricted sandbox @@ -92,7 +92,7 @@ env GOTMPDIR="$ARCHIE_GOTMPDIR" GOCACHE="$ARCHIE_GOCACHE" \ go test ./internal/config/... -count=1 ``` -Populate cold cache only with network authorized: +Populate cold cache only with network authorised: ```bash env ... go mod download; env ... go -C tools mod download @@ -112,16 +112,16 @@ golangci-lint run ./... ## Understand exactly what Task runs -| Task | Exact effect | -|---|---| -| `task fmt` | `go fix ./...`, then `golangci-lint fmt` — both may rewrite source. | -| `task vet` | `go vet ./...` in the runtime module. | -| `task lint` | `golangci-lint run ./...`. | -| `task build` | Builds both commands into `bin/`. | -| `task test` | `go test -short ./...` in the runtime module, test cache on. `task test:full` is the uncached run including wall-clock-bound tests. | -| `task check` | `fmt` + `proto:lint` + `proto:check` + `docs:check` + `vet` + `lint` + `build` + `test` + `test:tools` + `test:ui`. | -| `task clean` | Recursively removes `bin/`; destructive. | -| `task docker-build` | `docker compose build agent` only. | +| Task | Exact effect | +| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `task fmt` | `go fix ./...`, then `golangci-lint fmt` — both may rewrite source. | +| `task vet` | `go vet ./...` in the runtime module. | +| `task lint` | `golangci-lint run ./...`. | +| `task build` | Builds both commands into `bin/`. | +| `task test` | `go test -short ./...` in the runtime module, test cache on. `task test:full` is the uncached run including wall-clock-bound tests. | +| `task check` | `fmt` + `proto:lint` + `proto:check` + `docs: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 race tests, `task vuln`, and `task docker-build`. Its docs step, `docs:check`, verifies committed generated @@ -138,7 +138,7 @@ on work that is correct but unstaged, and both read as a broken generator: they differ. `task check` never rebuilds the bundle: run `task ui` after any `ui/src` change and commit the result with that change. -Run only in an authorized writable worktree. For a read-only ordinary-source +Run only in an authorised writable worktree. For a read-only ordinary-source preview, use `golangci-lint fmt --diff`. ## Verify the tools module separately @@ -217,17 +217,17 @@ omit patch/digest; Ubuntu base images omit digests; agent installs multiple ## Separate environment failures from code failures -| Signature | Classify and branch | -|---|---| -| `go: creating work dir: mkdir /work/tmp/...: read-only file system` | Set task-specific `GOTMPDIR`. | -| `open .../.cache/go-build/...: read-only file system` | Set writable `GOCACHE`. | -| `open .../pkg/mod/cache/...tmp: read-only file system` | Set writable `GOMODCACHE` and `GOPATH`. | -| `listen ...: socket: operation not permitted` | Re-run on host with loopback sockets. | -| `Unable to start NATS Server in Go Routine` after ~10s | Test whether local listeners permitted. | -| `cannot auto-sign commit` | Ambient `commit.gpgSign=true`; fixtures set `gpgsign=false`. | -| `EAI_AGAIN` for `registry.npmjs.org` | Dependency retrieval failed. | -| `Podman configuration ... read-only file system` | Container backend cannot initialize. | -| `TestRunWrapsExternalCommand ... Run() = "\n"` | Focused code failure in `internal/skillscript`. | +| Signature | Classify and branch | +| ------------------------------------------------------------------- | ------------------------------------------------------------ | +| `go: creating work dir: mkdir /work/tmp/...: read-only file system` | Set task-specific `GOTMPDIR`. | +| `open .../.cache/go-build/...: read-only file system` | Set writable `GOCACHE`. | +| `open .../pkg/mod/cache/...tmp: read-only file system` | Set writable `GOMODCACHE` and `GOPATH`. | +| `listen ...: socket: operation not permitted` | Re-run on host with loopback sockets. | +| `Unable to start NATS Server in Go Routine` after ~10s | Test whether local listeners permitted. | +| `cannot auto-sign commit` | Ambient `commit.gpgSign=true`; fixtures set `gpgsign=false`. | +| `EAI_AGAIN` for `registry.npmjs.org` | Dependency retrieval failed. | +| `Podman configuration ... read-only file system` | Container backend cannot initialise. | +| `TestRunWrapsExternalCommand ... Run() = "\n"` | Focused code failure in `internal/skillscript`. | For hermetic test diagnosis: @@ -237,15 +237,15 @@ env GIT_CONFIG_GLOBAL=/dev/null go test ./internal/worktree/... ./internal/workt ## Use the complete validation matrix -| Evidence | Command | Current snapshot | -|---|---|---| -| Focused Go behavior | `go test ./pkg/... -run '^TestName$' -count=1 -v` | Use first. | -| Root unit/integration suite | `go test ./... -count=1` | Restricted sandbox fails listener-dependent packages. | -| Root race suite | `go test -race ./... -count=1` | Not run by `task check`. | -| Vet | `go vet ./...` | Passed on 2026-09-18. | -| Lint | `golangci-lint run ./...` | Not re-run on 2026-09-18; a focused `--enable-only=dupl ./internal/...` run reported 0 issues. Re-run before quoting a total. | -| Build | `go build -o /tmp/... ./cmd/archied` and `cmd/archie-agent` | Both passed on 2026-09-18. | -| Tools tests | `go -C tools test -mod=readonly ./... -count=1` | Passed on 2026-09-18. | -| Generated contract parity | Temp docsgen output + `cmp --silent` | Passed for 11 schemas on 2026-09-18, after regenerating a file stale since `4b340d2b`. | -| Container build | `task docker-build` | Not verified in restricted environment. | -| Repository gate | `task check` | See `archie-diagnostics-and-tooling` for the dated snapshot. | +| Evidence | Command | Current snapshot | +| --------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| Focused Go behaviour | `go test ./pkg/... -run '^TestName$' -count=1 -v` | Use first. | +| Root unit/integration suite | `go test ./... -count=1` | Restricted sandbox fails listener-dependent packages. | +| Root race suite | `go test -race ./... -count=1` | Not run by `task check`. | +| Vet | `go vet ./...` | Passed on 2026-09-18. | +| Lint | `golangci-lint run ./...` | Not re-run on 2026-09-18; a focused `--enable-only=dupl ./internal/...` run reported 0 issues. Re-run before quoting a total. | +| Build | `go build -o /tmp/... ./cmd/archied` and `cmd/archie-agent` | Both passed on 2026-09-18. | +| Tools tests | `go -C tools test -mod=readonly ./... -count=1` | Passed on 2026-09-18. | +| Generated contract parity | Temp docsgen output + `cmp --silent` | Passed for 11 schemas on 2026-09-18, after regenerating a file stale since `4b340d2b`. | +| Container build | `task docker-build` | Not verified in restricted environment. | +| Repository gate | `task check` | See `archie-diagnostics-and-tooling` for the dated snapshot. | diff --git a/.agents/skills/archie-codebase-discovery/SKILL.md b/.agents/skills/archie-codebase-discovery/SKILL.md index 6ef5af266..9b2dea956 100644 --- a/.agents/skills/archie-codebase-discovery/SKILL.md +++ b/.agents/skills/archie-codebase-discovery/SKILL.md @@ -1,11 +1,11 @@ --- name: archie-codebase-discovery -description: "Trace Archie behavior and blast radius through Go source, types, state, persistence, transports, consumers, tests, configuration, production composition, and target architecture. Load before changing or planning a non-trivial feature, refactor, config field, interface, persistence path, workflow, channel, plugin, or agent execution path; also load to investigate duplicate behavior, hidden dead code, constructor bypasses, package dependencies, decoded-but-unwired configuration, or uncertainty about what a symbol actually affects." +description: "Trace Archie behaviour and blast radius through Go source, types, state, persistence, transports, consumers, tests, configuration, production composition, and target architecture. Load before changing or planning a non-trivial feature, refactor, config field, interface, persistence path, workflow, channel, plugin, or agent execution path; also load to investigate duplicate behaviour, hidden dead code, constructor bypasses, package dependencies, decoded-but-unwired configuration, or uncertainty about what a symbol actually affects." --- # Discover the Archie codebase -Use evidence from the current checkout to explain a behavior before changing it. +Use evidence from the current checkout to explain a behaviour before changing it. Volatile tool facts below were verified on **2026-09-18**. **Composition roots**: `cmd/archied/main.go` (thin dispatcher) → @@ -43,37 +43,37 @@ go list -m -f '{{.Path}} {{.GoVersion}}' go -C tools list -mod=readonly -m -f '{{.Path}} {{.GoVersion}}' ``` -## Build the behavior trace +## Build the behaviour trace -Write: behavior, observable input, expected output, state that may change, modes. +Write: behaviour, observable input, expected output, state that may change, modes. -| Step | Find | Required evidence | -|---:|---|---| -| 1 | Entrypoint | `main`, handler, poller, RPC subject, or tool registration | -| 2 | Construction | Constructor and every direct struct literal | -| 3 | Contract | Interface, wire type, command, event, or public method crossed | -| 4 | Implementation | All type-valid implementations, selected per mode | -| 5 | State owner | Function validating transition, owning concurrency/transaction rules | -| 6 | Persistence | Store adapter, schema/key/document, serialization, reload/recovery | -| 7 | Event/transport | Publish/send and subscribe/receive, subject/framing, timeout, retry, ack | -| 8 | Consumer | Callers and downstream readers | -| 9 | Tests | Unit, integration, contract, architecture, production-composition | -| 10 | Configuration | Decode, default, validation, normalization, composition-root consumption | -| 11 | Target architecture | Current-to-target mapping in `docs/prds/`; label gaps | +| Step | Find | Required evidence | +| ---: | ------------------- | ------------------------------------------------------------------------ | +| 1 | Entrypoint | `main`, handler, poller, RPC subject, or tool registration | +| 2 | Construction | Constructor and every direct struct literal | +| 3 | Contract | Interface, wire type, command, event, or public method crossed | +| 4 | Implementation | All type-valid implementations, selected per mode | +| 5 | State owner | Function validating transition, owning concurrency/transaction rules | +| 6 | Persistence | Store adapter, schema/key/document, serialisation, reload/recovery | +| 7 | Event/transport | Publish/send and subscribe/receive, subject/framing, timeout, retry, ack | +| 8 | Consumer | Callers and downstream readers | +| 9 | Tests | Unit, integration, contract, architecture, production-composition | +| 10 | Configuration | Decode, default, validation, normalisation, composition-root consumption | +| 11 | Target architecture | Current-to-target mapping in `docs/prds/`; label gaps | Start at these verified anchors: -| Concern | Current anchor | -|---|---| -| Resident daemon | `cmd/archied/main.go` → `internal/app/archied.Run()` (`internal/app/archied/main.go`) → `daemon.Daemon` | -| Sandboxed worker | `cmd/archie-agent/main.go` → `internal/app/agentworker/`; NATS boundary in `internal/infrastructure/agenttransport/nats/` | -| Task orchestration | `internal/daemon/daemon.go`, `internal/domain/workflow/` | -| Task contracts | `internal/domain/storecontract/storecontract.go` (`TaskStore`) | -| Production task persistence | `internal/infrastructure/postgres/`; built in `internal/app/archied/state_store.go` | -| RPC split | `internal/{taskrun,natsrpc,forgerpc,worktreerpc}/` plus `internal/infrastructure/staterpc/` (gRPC State Store) | -| Chat and channels | `internal/gateway/`, `internal/channels/` | -| Configuration | `internal/config/`, `internal/infrastructure/configuration/`, `config.example.toml`, `deployments/*.toml` | -| Target map | `docs/prds/01-project-management.md` and linked `docs/architecture/*.md` | +| Concern | Current anchor | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| Resident daemon | `cmd/archied/main.go` → `internal/app/archied.Run()` (`internal/app/archied/main.go`) → `daemon.Daemon` | +| Sandboxed worker | `cmd/archie-agent/main.go` → `internal/app/agentworker/`; NATS boundary in `internal/infrastructure/agenttransport/nats/` | +| Task orchestration | `internal/daemon/daemon.go`, `internal/domain/workflow/` | +| Task contracts | `internal/domain/storecontract/storecontract.go` (`TaskStore`) | +| Production task persistence | `internal/infrastructure/postgres/`; built in `internal/app/archied/state_store.go` | +| RPC split | `internal/{taskrun,natsrpc,forgerpc,worktreerpc}/` plus `internal/infrastructure/staterpc/` (gRPC State Store) | +| Chat and channels | `internal/gateway/`, `internal/channels/` | +| Configuration | `internal/config/`, `internal/infrastructure/configuration/`, `config.example.toml`, `deployments/*.toml` | +| Target map | `docs/prds/01-project-management.md` and linked `docs/architecture/*.md` | ## Use syntax, type, and call evidence @@ -111,7 +111,7 @@ Confirms candidates with `gopls definition` or `gopls references`. Pass ## Run focused discovery recipes -### Find duplicate behavior paths +### Find duplicate behaviour paths ```sh golangci-lint run --enable-only=dupl ./internal/... @@ -162,8 +162,8 @@ go list -deps -json ### Find decoded-but-unused configuration -Prove: `file/key → decoder → default → validation → normalization/copy → -composition-root read → concrete component → observable behavior`. +Prove: `file/key → decoder → default → validation → normalisation/copy → +composition-root read → concrete component → observable behaviour`. ```sh rg -n 'toml:"|yaml:"|json:"' internal/config @@ -183,7 +183,7 @@ and `Loader.Dir` for overlay/`conf.d` inputs). There is no `config.Load` or `cmd/archied/main.go`. 2. Record config condition per branch. 3. Follow concrete construction into `daemon.Daemon` and gateway start. -4. For container/NATS behavior, trace `cmd/archie-agent/main.go` into +4. For container/NATS behaviour, trace `cmd/archie-agent/main.go` into `internal/app/agentworker` and `internal/infrastructure/agenttransport/nats`. 5. Trace both sides of every RPC/transport and error/timeout paths. 6. Read contract/architecture tests. @@ -203,19 +203,19 @@ rg -n 'CREATE TABLE|CREATE INDEX' internal/infrastructure/postgres/migrations ## Reject false confidence -| Weak evidence | Why it fails | Required correction | -|---|---|---| -| One `rg` result | Misses interface dispatch, aliases, generated registration, reflection | Use gopls, AST candidates, package edges, composition | -| Green unit test | May bypass config, lifecycle, transport | Add composition/contract/integration evidence | -| Fake client and server agree | Both mirror same wrong framing/subject/state assumption | Compare independent spec or real boundary fixture | -| High coverage | Does not establish ownership, maintainability, mode selection | Trace authority and production selection | -| Constructor exists | Does not prove callers use it | Find struct literals and type-aware references | -| Config field decodes | Does not prove executable reads it | Complete config-to-observable chain | -| Target PRD says it | Not necessarily current code | Cite current implementation and label gap | +| Weak evidence | Why it fails | Required correction | +| ---------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- | +| One `rg` result | Misses interface dispatch, aliases, generated registration, reflection | Use gopls, AST candidates, package edges, composition | +| Green unit test | May bypass config, lifecycle, transport | Add composition/contract/integration evidence | +| Fake client and server agree | Both mirror same wrong framing/subject/state assumption | Compare independent spec or real boundary fixture | +| High coverage | Does not establish ownership, maintainability, mode selection | Trace authority and production selection | +| Constructor exists | Does not prove callers use it | Find struct literals and type-aware references | +| Config field decodes | Does not prove executable reads it | Complete config-to-observable chain | +| Target PRD says it | Not necessarily current code | Cite current implementation and label gap | ## Produce the discovery handoff -1. **Behavior trace:** path:line, symbol, current responsibility per traversal step. +1. **Behaviour trace:** path:line, symbol, current responsibility per traversal step. 2. **Mode matrix:** mode/config branch → concrete implementation → state store → transport → consumer. 3. **State and authority:** owner, copies, persistence, transition rules, recovery. diff --git a/.agents/skills/archie-config-and-flags/SKILL.md b/.agents/skills/archie-config-and-flags/SKILL.md index cd1ab837d..8e003d9b4 100644 --- a/.agents/skills/archie-config-and-flags/SKILL.md +++ b/.agents/skills/archie-config-and-flags/SKILL.md @@ -6,7 +6,7 @@ description: Trace, add, rename, deprecate, or debug Archie configuration and co # Trace Archie configuration and flags Treat configuration as a dataflow, not as a struct inventory. Prove every -claimed setting has an input, normalization path, composition seam, and runtime +claimed setting has an input, normalisation path, composition seam, and runtime consumer. Current evidence date: **2026-09-18** for the matrix below. Entries added later @@ -14,13 +14,13 @@ carry their own date inline. Use these status terms exactly: -| Status | Meaning | -| --- | --- | -| **production-wired** | A real entrypoint decodes or accepts the value and a runtime consumer uses it. | -| **partially-wired** | Some modes, scopes, or fields consume it, but parity is incomplete. | -| **test/library-only** | An API and tests exist, but no current binary selects it. | -| **decoded-but-unwired** | Decoding/defaulting succeeds, but no production consumer uses the effective value. | -| **external-production-unknown** | The repository does not contain the deployed effective value. | +| Status | Meaning | +| ------------------------------- | ---------------------------------------------------------------------------------- | +| **production-wired** | A real entrypoint decodes or accepts the value and a runtime consumer uses it. | +| **partially-wired** | Some modes, scopes, or fields consume it, but parity is incomplete. | +| **test/library-only** | An API and tests exist, but no current binary selects it. | +| **decoded-but-unwired** | Decoding/defaulting succeeds, but no production consumer uses the effective value. | +| **external-production-unknown** | The repository does not contain the deployed effective value. | Never upgrade a status merely because decoding tests pass. @@ -32,7 +32,7 @@ Never upgrade a status merely because decoding tests pass. 3. Read `finalize` and any consumer-side defaults. 4. Follow copies across `ForTask`, `ToConfig`, NATS messages, subprocess env selection, container env construction, and identity overlays. -5. Find the production composition site and final behavior-changing read. +5. Find the production composition site and final behaviour-changing read. 6. Find tests for decoding, defaulting, invalid input, production composition, and mode parity. 7. Check `config.example.toml`, `deployments/*.toml`, `docker-compose.yml`, and @@ -48,15 +48,15 @@ rg -n 'FIELD_NAME|external_key|ENV_NAME' \ ## Select the real input path -| Input path | Current behavior | Status | -| --- | --- | --- | -| `archied -config PATH` | Defaults to `$XDG_CONFIG_HOME/archie/config.toml`, or `$HOME/.config/archie/config.toml`; `internal/app/archied/bootstrap.go` builds `configuration.New(log)` and calls `Loader.Resolve`. | production-wired | -| `archied -config-overlay PATH` | Resolves a file or directory overlay through the same loader. Omitted overlay fields retain base values. This is the only overlay: the dashboard runtime overlay and its SQLite store were deleted when the control plane took over settings writes. | production-wired | -| `configuration.Loader.Dir(base, overlay)` | Supports main YAML/TOML plus feature YAML and `conf.d`; no current entrypoint calls it. | test/library-only | -| `config.Load(path)`, `config.LoadDir(...)` | Removed. The old `internal/config` package-level helpers no longer exist; decoding is `Loader`-based. | not applicable | -| `config.example.toml` | Load-tested example, not a deployed configuration. | test/library-only | -| `deployments/docker-nats-stack.toml` | Complete host-daemon configuration for the Compose-managed NATS service. It is copied into the operator's config directory; Compose does not mount it. | supported-example | -| Operator config and environment | Lives outside the repository; contents are deployment-specific. | external-production-unknown | +| Input path | Current behaviour | Status | +| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | +| `archied -config PATH` | Defaults to `$XDG_CONFIG_HOME/archie/config.toml`, or `$HOME/.config/archie/config.toml`; `internal/app/archied/bootstrap.go` builds `configuration.New(log)` and calls `Loader.Resolve`. | production-wired | +| `archied -config-overlay PATH` | Resolves a file or directory overlay through the same loader. Omitted overlay fields retain base values. This is the only overlay: the dashboard runtime overlay and its SQLite store were deleted when the control plane took over settings writes. | production-wired | +| `configuration.Loader.Dir(base, overlay)` | Supports main YAML/TOML plus feature YAML and `conf.d`; no current entrypoint calls it. | test/library-only | +| `config.Load(path)`, `config.LoadDir(...)` | Removed. The old `internal/config` package-level helpers no longer exist; decoding is `Loader`-based. | not applicable | +| `config.example.toml` | Load-tested example, not a deployed configuration. | test/library-only | +| `deployments/docker-nats-stack.toml` | Complete host-daemon configuration for the Compose-managed NATS service. It is copied into the operator's config directory; Compose does not mount it. | supported-example | +| Operator config and environment | Lives outside the repository; contents are deployment-specific. | external-production-unknown | Both TOML and YAML decoding are non-strict at the field level. Add explicit compatibility and typo tests; never use "the file loaded" as evidence that a @@ -75,15 +75,15 @@ flag or on the dial succeeding, and give a binary its own ### Public binaries -| Binary | Flag | Default and effect | -| --- | --- | --- | -| `archied` | `-config PATH` | Computed config path described above. | -| `archied` | `-config-overlay PATH` | Empty; overlay only fields explicitly present in second TOML. | -| `archied` | `-once` | `false`; run one poll/process cycle and exit. | -| `archied` | `-requeue ID` | `0`; values greater than zero requeue one parked/waiting task, then exit unless `-once` also set. | -| `archie-agent` | `-nats-url URL` | Empty; takes precedence over `NATS_URL`. Missing both is fatal. | -| `archie-agent` | `-consumer NAME` | `archie-agent`; names the JetStream durable consumer. | -| both | `-quickchecks N` | Incidental flag registered by `github.com/traefik/yaegi/stdlib` importing `testing/quick`; default `100`. Treat as unowned candidate defect. | +| Binary | Flag | Default and effect | +| -------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `archied` | `-config PATH` | Computed config path described above. | +| `archied` | `-config-overlay PATH` | Empty; overlay only fields explicitly present in second TOML. | +| `archied` | `-once` | `false`; run one poll/process cycle and exit. | +| `archied` | `-requeue ID` | `0`; values greater than zero requeue one parked/waiting task, then exit unless `-once` also set. | +| `archie-agent` | `-nats-url URL` | Empty; takes precedence over `NATS_URL`. Missing both is fatal. | +| `archie-agent` | `-consumer NAME` | `archie-agent`; names the JetStream durable consumer. | +| both | `-quickchecks N` | Incidental flag registered by `github.com/traefik/yaegi/stdlib` importing `testing/quick`; default `100`. Treat as unowned candidate defect. | The standalone agent always reads its token from `NATS_TOKEN`; there is no token flag. @@ -93,9 +93,9 @@ token flag. `archied workspace-codesearch` bypasses daemon configuration before normal flag parsing: -| Subcommand | Required flags | Optional flags | -| --- | --- | --- | -| `build` | `--root`, `--index` | none | +| Subcommand | Required flags | Optional flags | +| ------------ | ---------------------- | ------------------------------- | +| `build` | `--root`, `--index` | none | | `candidates` | `--index`, `--pattern` | `--literal`, `--case-sensitive` | Do not expose these helper flags as daemon settings. @@ -104,41 +104,39 @@ Do not expose these helper flags as daemon settings. ### Root daemon and capability settings -| Keys | Default, validation, and consumer | Status | -| --- | --- | --- | -| `work_dir`, `state_dir`, `db_path` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; explicit `~` paths are home-expanded. `state_dir` holds the embedded NATS store and endpoint file, task logs and the readiness disk target. `db_path` only locates the legacy `-tasks.sqlite`, `-eda.sqlite` and `-conversations.sqlite` files for `archie-state-store import` and the boot gate. | production-wired | -| `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. | partially-wired | -| `plugin_dir` | Empty disables daemon plugin loading; configured directory loaded in `internal/app/archied`. | production-wired | -| `poll_interval` | Default `60s`; root poll loop uses it, identities may override only interval. | production-wired | -| `label` | No default or validation; used for `dispatch.trigger = "label"` or `"either"`. | production-wired | -| `max_retries` | Default `3`; repository value greater than zero overrides. | production-wired | -| `bot_user`, `bot_email` | Single-identity requires `bot_user`; email defaults by forge type. | production-wired | -| `forge.type`, `host`, `token` | Type defaults `github`, host defaults `https://github.com`; only `github` and `gitea` validate. | production-wired | -| `dispatch.trigger` | Default `assignee`; validates `assignee`, `label`, or `either`. | production-wired | -| `dispatch.ack_reaction` | Default `eyes`; case-insensitive `off` normalizes to empty. | production-wired | -| `dispatch.labels.*` | Missing keys default independently to `agent:*`. | production-wired | -| `models.` | Workflow stages read requested role then fall back to `builder`; triage judge falls back `triage` to `planner`. | production-wired | -| `providers..class`, `api_key_env`, `base_url` | Builds ai-sdk catalog. `base_url` rejects parse errors, userinfo, query, and fragment. | production-wired | -| `agent.mode` | Default `nats` when containers enabled, otherwise `inprocess`; validates `inprocess`, `subprocess`, or `nats`. | production-wired | -| `agent.command`, `agent.env` | Command defaults `archie-agent`; env entries must be nonblank names without `=`. | partially-wired | -| `budgets.max_steps`, `max_tokens`, `wall_clock`, `gate_max_failures` | No loader defaults; `Budgets` documents zero as disabling. | production-wired | -| `diff_cap_lines` | Zero replaced by `400` in `finalize`; `StageDiffCap` treats `<= 0` as disabled. TOML zero cannot disable; negative value does. | production-wired | -| `web.listen` | Empty becomes `127.0.0.1:8484`; literal `off` disables. No authentication. | production-wired | -| `notify.webhook` | Empty disables; feasibility workflow POSTs human-decision notifications when set. | production-wired | -| `nats.url`, `token_env` | Empty URL keeps the in-process path. Configured token variable must be non-empty. | production-wired | -| `containers.*` | See dedicated table below. | production-wired | -| `chat.*` | See channel table below. | production-wired | -| `memory.provider`, `provider_config` | Feature YAML decodes these; `internal/app/archied` always starts built-in file provider at `work_dir/memory`. | decoded-but-unwired | -| `tools.mcp_servers` | `internal/app/archied` registers daemon-side MCP providers. Empty transport becomes `stdio`; only `stdio` accepted. `url` decoded but unused. | partially-wired | -| `indexing.index_dir`, `indexing.db_path` | `finalize` derives paths under `work_dir`; no entrypoint constructs `internal/indexing.Manager` (the exported `NewManager` exists but has no production caller). | decoded-but-unwired | -| `extra` / unknown `conf.d` values | Test/library-only `Loader.Dir` stores untyped data; no core production consumer. | decoded-but-unwired | -| `[identities.forge].intake`, `.webhook_secret`, `.webhook_addr` | 2026-09-22: these parse because `IdentityConfig` embeds `Forge` (`internal/config/config.go:573`), while every read is the root `[forge]` block (`validate.go`, `defaults.go`, `bootstrap.go`). Wiring them is the intake migration, tracked as `archie-core-1786637497036-275-8838629e`. | partially-wired | +| Keys | Default, validation, and consumer | Status | +| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | +| `work_dir`, `state_dir` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; explicit `~` paths are home-expanded. `state_dir` holds the embedded NATS store and endpoint file, task logs and the readiness disk target. | production-wired | +| `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. | partially-wired | +| `plugin_dir` | Empty disables daemon plugin loading; configured directory loaded in `internal/app/archied`. | production-wired | +| `poll_interval` | Default `60s`; root poll loop uses it, identities may override only interval. | production-wired | +| `label` | No default or validation; used for `dispatch.trigger = "label"` or `"either"`. | production-wired | +| `max_retries` | Default `3`; repository value greater than zero overrides. | production-wired | +| `bot_user`, `bot_email` | Single-identity requires `bot_user`; email defaults by forge type. | production-wired | +| `forge.type`, `host`, `token` | Type defaults `github`, host defaults `https://github.com`; only `github` and `gitea` validate. | production-wired | +| `dispatch.trigger` | Default `assignee`; validates `assignee`, `label`, or `either`. | production-wired | +| `dispatch.ack_reaction` | Default `eyes`; case-insensitive `off` normalises to empty. | production-wired | +| `dispatch.labels.*` | Missing keys default independently to `agent:*`. | production-wired | +| `models.` | Workflow stages read requested role then fall back to `builder`; triage judge falls back `triage` to `planner`. | production-wired | +| `providers..class`, `api_key_env`, `base_url` | Builds ai-sdk catalogue. `base_url` rejects parse errors, userinfo, query, and fragment. | production-wired | +| `budgets.max_steps`, `max_tokens`, `wall_clock`, `gate_max_failures` | No loader defaults; `Budgets` documents zero as disabling. | production-wired | +| `diff_cap_lines` | Zero replaced by `400` in `finalize`; `StageDiffCap` treats `<= 0` as disabled. TOML zero cannot disable; negative value does. | production-wired | +| `web.listen` | Empty becomes `127.0.0.1:8484`; literal `off` disables. No authentication. | production-wired | +| `notify.webhook` | Empty disables; feasibility workflow POSTs human-decision notifications when set. | production-wired | +| `nats.url`, `token_env` | Empty URL keeps the in-process path. Configured token variable must be non-empty. | production-wired | +| `containers.*` | See dedicated table below. | production-wired | +| `chat.*` | See channel table below. | production-wired | +| `memory.provider`, `provider_config` | Feature YAML decodes these; `internal/app/archied` always starts built-in file provider at `work_dir/memory`. | decoded-but-unwired | +| `tools.mcp_servers` | `internal/app/archied` registers daemon-side MCP providers. Empty transport becomes `stdio`; only `stdio` accepted. `url` decoded but unused. | partially-wired | +| `indexing.index_dir`, `indexing.db_path` | `finalize` derives paths under `work_dir`; no entrypoint constructs `internal/indexing.Manager` (the exported `NewManager` exists but has no production caller). | decoded-but-unwired | +| `extra` / unknown `conf.d` values | Test/library-only `Loader.Dir` stores untyped data; no core production consumer. | decoded-but-unwired | +| `[identities.forge].intake`, `.webhook_secret`, `.webhook_addr` | 2026-09-22: these parse because `IdentityConfig` embeds `Forge` (`internal/config/config.go:573`), while every read is the root `[forge]` block (`validate.go`, `defaults.go`, `bootstrap.go`). Wiring them is the intake migration, tracked as `archie-core-1786637497036-275-8838629e`. | partially-wired | **Three shapes of an unwired field.** All three read as working from the file alone, and only the first two are defects - so establish which shape you are looking at before reporting one: -1. **not-consumed.** Decoded and normalized, but no production consumer uses the +1. **not-consumed.** Decoded and normalised, but no production consumer uses the effective value (`memory.provider` and `indexing.*` above; per-identity intake was this shape until 2026-09-22, when the configuration was made to reject it rather than accept it). @@ -154,45 +152,40 @@ looking at before reporting one: from the stored resource, on purpose. Check for that comment before filing a defect. -The default `agent.command = "archie-agent"` is not verified subprocess -operation. `SubprocessRunner` expects one JSON invocation on stdin and one JSON -response on stdout; `cmd/archie-agent` is a long-running NATS worker. - ### Repository settings -| Keys | Effective behavior | Status | -| --- | --- | --- | -| `owner`, `name` | Required for every declared repo. Single-identity config with zero repos loads but polls nothing. | production-wired | -| `base` | `BaseBranch()` maps empty to `main`, but `daemon.process` pre-clones with raw `repo.Base`. Set it explicitly. | partially-wired | -| `gate` | Argv arrays run in order. Empty entries skipped. TDD inverts last non-empty command as repro test by convention. | production-wired | -| `protect` | Path suffixes enforced by agent runner; not prompt-only rule. | production-wired | -| `ecosystem`, `preflight`, `test_glob` | Resolved preflight/test-glob treats empty ecosystem as Go. Container storage receives raw ecosystem. Go/Python/Node/Rust have defaults; `custom` or unknown yields none. | partially-wired | -| `persistent_storage` | Controls Docker-backed per-repo volume setup; no equivalent without container storage. | partially-wired | -| `max_retries` | Values greater than zero override global; zero or negative falls back to global. | production-wired | -| `allow_concurrent` | Root repo entries affect dispatcher. `allowConcurrentFor` does not inspect identity repo lists. | partially-wired | +| Keys | Effective behaviour | Status | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | +| `owner`, `name` | Required for every declared repo. Single-identity config with zero repos loads but polls nothing. | production-wired | +| `base` | `BaseBranch()` maps empty to `main`, but `daemon.process` pre-clones with raw `repo.Base`. Set it explicitly. | partially-wired | +| `gate` | Argv arrays run in order. Empty entries skipped. TDD inverts last non-empty command as repro test by convention. | production-wired | +| `protect` | Path suffixes enforced by agent runner; not prompt-only rule. | production-wired | +| `ecosystem`, `preflight`, `test_glob` | Resolved preflight/test-glob treats empty ecosystem as Go. Container storage receives raw ecosystem. Go/Python/Node/Rust have defaults; `custom` or unknown yields none. | partially-wired | +| `persistent_storage` | Controls Docker-backed per-repo volume setup; no equivalent without container storage. | partially-wired | +| `max_retries` | Values greater than zero override global; zero or negative falls back to global. | production-wired | +| `allow_concurrent` | Root repo entries affect dispatcher. `allowConcurrentFor` does not inspect identity repo lists. | partially-wired | ### Container settings -| Key | Effective behavior | -| --- | --- | -| `enabled` | Requires non-empty `image`, `agent.mode = "nats"`, and non-empty `nats.url`. | -| `image` | Required only when enabled. | -| `max_concurrency` | Zero means no limit; used by general task dispatcher and container pool. | -| `max_uptime` | Default `60m` only when enabled; caps container lifetime. | -| `volume_ttl` | Default `72h` only when enabled; negative rejected. | -| `pull_policy` | Default `missing` when enabled. Pool code recognizes `missing` and `always`; other strings silently skip pre-pull. | -| `network` | Empty uses best-effort self-network detection. Repository overlay pins `archie-core_default`. | +| Key | Effective behaviour | +| ----------------- | ------------------------------------------------------------------------------------------------------------------ | +| `image` | Required only when enabled. | +| `max_concurrency` | Zero means no limit; used by general task dispatcher and container pool. | +| `max_uptime` | Default `60m` only when enabled; caps container lifetime. | +| `volume_ttl` | Default `72h` only when enabled; negative rejected. | +| `pull_policy` | Default `missing` when enabled. Pool code recognises `missing` and `always`; other strings silently skip pre-pull. | +| `network` | Empty uses best-effort self-network detection. Repository overlay pins `archie-core_default`. | ### Channel settings -| Keys | Effective behavior | -| --- | --- | -| `chat.models` | Optional interactive catalog; empty falls back to workflow model references. | -| `chat.telegram.token_env` | Empty disables Telegram; non-empty names env variable; empty value is fatal. | -| `chat.telegram.allowed_user_ids` | Empty denies every sender; IDs match Telegram sender IDs, not chat IDs. | +| Keys | Effective behaviour | +| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| `chat.models` | Optional interactive catalogue; empty falls back to workflow model references. | +| `chat.telegram.token` | Unset disables Telegram; otherwise a secret reference resolved at channel start. | +| `chat.telegram.allowed_user_ids` | Empty denies every sender; IDs match Telegram sender IDs, not chat IDs. | | `chat.telegram.update_check_command`, `update_install_command` | Argv arrays; check enables update status; install further enables approved installation. | -| `chat.email.listen_addr`, `relay_addr` | Empty listen disables SMTP; relay configures outbound replies. | -| `chat.webhook_addr` | Empty disables; malformed host/port falls back inside `parseListenAddr`. | +| `chat.email.listen_addr`, `relay_addr` | Empty listen disables SMTP; relay configures outbound replies. | +| `chat.webhook_addr` | Empty disables; malformed host/port falls back inside `parseListenAddr`. | Telegram `/restart` re-runs same TOML overlay load, then replaces only gateway token and allowed-user list. Every other file setting is startup-only. @@ -225,20 +218,17 @@ diff cap, notification, and forge host. `TaskConfig.ToConfig` reconstructs only those fields. Forge tokens, provider values, NATS credential references, repos, and infrastructure settings do not enter `TaskConfig`. -At top-level `[forge]`, prefer `token = {engine = "env", key = "NAME"}`. The -`token_env = "NAME"` form is converted only when structured reference is empty; -structured reference wins when both appear. This compatibility rule exists -because an earlier migration silently dropped deployed `token_env` values and -crash-looped the daemon. `finalize` does not apply that conversion inside each -identity: identity forges require explicit structured `token`. +Every credential except `nats.token_env` is a `{engine, key}` secret +reference; the flat `token_env` aliases for forge, artifacts and Telegram are +removed. A stale alias in a file is reported at startup as an unrecognised key +(`bootstrap.go`), not silently ignored. -| Source | Archied | Subprocess | Agent container / standalone worker | -| --- | --- | --- | --- | -| Forge `token = {engine="env", key="X"}` | Resolves `X`; empty is fatal. | Not forwarded. | Not forwarded; forge ops proxy to daemon. | -| Provider `api_key_env = "X"` | Runtime reads `X`. | Auto-allowlists selected provider's `X`. | Daemon forwards each present provider variable under original name. | -| `nats.token_env = "X"` | Reads `X`; empty fatal when configured. | Not agent subprocess setting. | Daemon maps to fixed `NATS_TOKEN`; worker also reads `NATS_URL`. | -| Telegram `token_env = "X"` | Reads `X`. | Not forwarded. | Not forwarded. | -| `agent.env = ["X"]` | Names validated. | Copies present `X` from daemon env. | Not used by container construction. | +| Source | Archied | Subprocess | Agent container / standalone worker | +| ------------------------------------------ | --------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------- | +| Forge `token = {engine="env", key="X"}` | Resolves `X`; empty is fatal. | Not forwarded. | Not forwarded; forge ops proxy to daemon. | +| Provider `api_key_env = "X"` | Runtime reads `X`. | Auto-allowlists selected provider's `X`. | Daemon forwards each present provider variable under original name. | +| `nats.token_env = "X"` | Reads `X`; empty fatal when configured. | Not agent subprocess setting. | Daemon maps to fixed `NATS_TOKEN`; worker also reads `NATS_URL`. | +| Telegram `token = {engine="env", key="X"}` | Resolves `X`. | Not forwarded. | Not forwarded. | `internal/app/archied` creates `secret.NewRegistry`, which registers only the `env` engine. Non-env `SecretRef` values are not production-wired. diff --git a/.agents/skills/archie-debugging-playbook/SKILL.md b/.agents/skills/archie-debugging-playbook/SKILL.md index 3c4150285..200c35904 100644 --- a/.agents/skills/archie-debugging-playbook/SKILL.md +++ b/.agents/skills/archie-debugging-playbook/SKILL.md @@ -14,7 +14,7 @@ request/reply**: direct subject + reply inbox. **JetStream**: persisted stream `ARCHIE_TASKS`. **State Store**: gRPC (`internal/infrastructure/staterpc`), not NATS. **Environment failure**: test/process cannot use host resource (listener, tmp, -Docker). **Code regression**: behavior fails where prerequisites available. +Docker). **Code regression**: behaviour fails where prerequisites available. ## Run the first-ten-minutes protocol @@ -26,27 +26,28 @@ GIT_CONFIG_GLOBAL=/dev/null go test ./PATH/TO/PACKAGE -run '^TestName$' -count=1 ``` Classify: compile-only, listener failure, read-only tmp, code regression. - - Behavioral assertion with the prerequisite available: code regression. + +- Behavioural assertion with the prerequisite available: code regression. Use this symptom index: -| Symptom | First boundary | Go to | -|---|---|---| -| `Run() = "\n"` in `TestRunWrapsExternalCommand` | Skill-script test command shape | Fixed history — passes since 2026-09-16 | -| Embedded NATS panics before a test assertion | Listener permission | Test environment | -| `nats: no responders available for request` | Core NATS subscription | NATS request/reply | -| Agent reply timeout | JetStream request, inbox, or worker | NATS request/reply | -| Queue looks empty while NATS reports an error | `Client.Fetch` batch error | NATS request/reply | -| Config test passes but daemon ignores the field | Composition/wiring | Configuration | -| Daemon has an env var but container does not | Compose or `containerEnv` | Configuration | -| Telegram reply hangs on the first token | Stream consumer | Streaming | -| MCP unit tests pass but a real server hangs | Framing mirror | MCP | -| Telegram shows old commands | Token-scoped Telegram state | Telegram | -| Transition succeeds from the wrong state | Store semantics | Database/state | -| Dashboard skips events but task state is correct | Bounded event buffers | Events | -| Search works but never becomes indexed | Missing production wiring | Optional features | -| Agent container cannot resolve `nats` | Docker network | Containers | -| `agent.mode = "subprocess"` fails at protocol startup | Worker binary mismatch | Subprocess mode | +| Symptom | First boundary | Go to | +| ----------------------------------------------------- | ----------------------------------- | --------------------------------------- | +| `Run() = "\n"` in `TestRunWrapsExternalCommand` | Skill-script test command shape | Fixed history — passes since 2026-09-16 | +| Embedded NATS panics before a test assertion | Listener permission | Test environment | +| `nats: no responders available for request` | Core NATS subscription | NATS request/reply | +| Agent reply timeout | JetStream request, inbox, or worker | NATS request/reply | +| Queue looks empty while NATS reports an error | `Client.Fetch` batch error | NATS request/reply | +| Config test passes but daemon ignores the field | Composition/wiring | Configuration | +| Daemon has an env var but container does not | Compose or `containerEnv` | Configuration | +| Telegram reply hangs on the first token | Stream consumer | Streaming | +| MCP unit tests pass but a real server hangs | Framing mirror | MCP | +| Telegram shows old commands | Token-scoped Telegram state | Telegram | +| Transition succeeds from the wrong state | Store semantics | Database/state | +| Dashboard skips events but task state is correct | Bounded event buffers | Events | +| Search works but never becomes indexed | Missing production wiring | Optional features | +| Agent container cannot resolve `nats` | Docker network | Containers | +| `agent.mode = "subprocess"` fails at protocol startup | Worker binary mismatch | Subprocess mode | ## Separate test-environment failures from regressions @@ -87,15 +88,15 @@ env GOTMPDIR=/tmp GOCACHE=/tmp/archie-skillscript-gocache \ ## Triage NATS request/reply and JetStream -| Surface | Subject or resource | Bound/current behavior | -|---|---|---| -| Task discovery | `archie.task.>` in `ARCHIE_TASKS` | Work-queue retention; daemon durable `archie-daemon`; max deliver 3 | -| Per-stage agent request | `archie.agent..request` | Reply inbox in `X-Archie-Reply`; wall-clock budget or 30m | -| Full task handoff | `archie.taskrun.` | Core request/reply; no-responder retry 20s every 250ms | -| Store RPC | gRPC State Store (`internal/infrastructure/staterpc`) | Client timeout 60s (`rpcTimeout` in `internal/app/agentworker/worker.go`); task-scoped grants for Update/Transition/InsertEvent only | -| Forge RPC | `archie.forge.*` | Error travels in a JSON envelope | -| Worktree RPC | `archie.worktree.prepare`, `.push` | Server default handler bound 15m | -| Discovery dedup | `Nats-Msg-Id: archie://` | JetStream duplicate window 2m | +| Surface | Subject or resource | Bound/current behaviour | +| ----------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| Task discovery | `archie.task.>` in `ARCHIE_TASKS` | Work-queue retention; daemon durable `archie-daemon`; max deliver 3 | +| Per-stage agent request | `archie.agent..request` | Reply inbox in `X-Archie-Reply`; wall-clock budget or 30m | +| Full task handoff | `archie.taskrun.` | Core request/reply; no-responder retry 20s every 250ms | +| Store RPC | gRPC State Store (`internal/infrastructure/staterpc`) | Client timeout 60s (`rpcTimeout` in `internal/app/agentworker/worker.go`); task-scoped grants for Update/Transition/InsertEvent only | +| Forge RPC | `archie.forge.*` | Error travels in a JSON envelope | +| Worktree RPC | `archie.worktree.prepare`, `.push` | Server default handler bound 15m | +| Discovery dedup | `Nats-Msg-Id: archie://` | JetStream duplicate window 2m | ```bash docker compose ps @@ -122,7 +123,7 @@ env GOTMPDIR=/tmp GOCACHE=/tmp/archie-agent-unit-gocache \ go test ./internal/agentexec -run '^TestToolSetHandler' -count=1 -v ``` -## Trace configuration from source to behavior +## Trace configuration from source to behaviour Trace: `cmd/archied` (`internal/app/archied/bootstrap.go`) reads `-config`/`-config-overlay` → `configuration.New(log)` + `Loader.Resolve` @@ -141,25 +142,24 @@ The `config.Load`/`config.LoadDir` helpers are gone; decoding is is a wiring gap, not a parser bug. For environment failures: + - The host supervisor supplies the daemon environment; inspect its unit or launch environment rather than Compose. - `containerEnv` translates configured NATS token name into `NATS_TOKEN` and forwards configured provider key variables. -- `SubprocessRunner` forwards default compatibility variables, configured - `[agent].env` names, and only the requested provider key. -- Top-level `[forge] token_env` is converted to an env `SecretRef` by - `finalize`; explicit `[forge.token]` wins. Do not print secret values. ## Diagnose streaming, MCP, and Telegram ### Streaming + Must drain `stream.FullStream`, collect `core.StreamPartTextDelta`, check `FinishReason`. `TextStream` is best-effort. **Fixed history:** consuming `TextStream` while `FullStream` unread deadlocked every reply. ### MCP + Stdio framing is one compact JSON-RPC object per line. Stale `internal/tools/mcp/types.go` comment mentions `Content-Length` — not the implemented contract. @@ -184,6 +184,7 @@ Gate: non-empty discovery with `start_process`, `interact_with_process`, `read_process_output`. ### Telegram + Three command scopes in `internal/channels/telegram/commands.go`: default, all private chats, all group chats. Narrower scope shadows default; state keyed by bot token. Empty `allowed_user_ids` denies everyone. @@ -200,6 +201,7 @@ env GOTMPDIR=/tmp GOCACHE=/tmp/archie-telegram-gocache \ ## Diagnose state, events, containers, and optional features ### Database and transitions + `internal/infrastructure/postgres.Store.Transition` owns task state changes and transition history: it guards on `from`, returning `storecontract.ErrStaleTransition`, and writes status plus history in one transaction. @@ -212,20 +214,22 @@ env GOTMPDIR=/tmp GOCACHE=/tmp/archie-state-gocache go test ./internal/infrastru ``` ### Events + DB sink buffer 256; SSE client buffers 64. Drop counter not read in production. Dashboard gap can coexist with correct task state. ### Containers, worktrees, and subprocess mode + Container-mode: clones on host, mounts `/data/worktree`, writes `.git/task.json`, dedicated `archie.taskrun.` subscription. **Open:** container RPC is root-identity-bound; `SubprocessRunner` expects stdin JSON protocol. ### Optional feature degradation -| Feature | Current failure behavior | -|---|---| -| Daemon plugins | Warn and skip | -| Invalid MCP config | Warn and continue | -| Skill catalog | Warn, continue without tool | -| Worktree augmentation | Log error, use startup registry | -| Workspace indexing | **Open:** `indexing.NewManager` exists but has no production caller in `internal/app/archied` | +| Feature | Current failure behaviour | +| --------------------- | --------------------------------------------------------------------------------------------- | +| Daemon plugins | Warn and skip | +| Invalid MCP config | Warn and continue | +| Skill catalogue | Warn, continue without tool | +| Worktree augmentation | Log error, use startup registry | +| Workspace indexing | **Open:** `indexing.NewManager` exists but has no production caller in `internal/app/archied` | diff --git a/.agents/skills/archie-diagnostics-and-tooling/SKILL.md b/.agents/skills/archie-diagnostics-and-tooling/SKILL.md index a7c16d51a..25d83d72d 100644 --- a/.agents/skills/archie-diagnostics-and-tooling/SKILL.md +++ b/.agents/skills/archie-diagnostics-and-tooling/SKILL.md @@ -79,12 +79,12 @@ go run "$skill/scripts/source-metrics.go" -root . -top 30 Read its tab-separated schema: -| Record | Columns after record name | -|---|---| -| `META` | key, value | -| `METRIC` | module, metric, integer | +| Record | Columns after record name | +| --------- | --------------------------------------------------------------------------------------------------------------- | +| `META` | key, value | +| `METRIC` | module, metric, integer | | `PACKAGE` | module, directory, production files, test files, generated files, production lines, test lines, generated lines | -| `HOTSPOT` | module, file, declaration line, symbol, body-span lines, statement nodes, approximate syntactic complexity | +| `HOTSPOT` | module, file, declaration line, symbol, body-span lines, statement nodes, approximate syntactic complexity | The defaults (80 body lines, complexity 15) mirror numeric triage points in `.golangci.yml`. They do **not** implement `funlen` or `cyclop`. Run configured @@ -135,8 +135,8 @@ marshalling) reports zero. Confirm each candidate by hand before calling a field dead. For every candidate: run `gopls references -d` on the exact field identifier; -trace decode → default → validation → normalization/copy → composition-root read -→ concrete component → observable behavior. +trace decode → default → validation → normalisation/copy → composition-root read +→ concrete component → observable behaviour. ### Measure delivery and hygiene drift @@ -184,7 +184,7 @@ production-only, test-only, compatibility, generated, and unreachable paths separately. As of 2026-09-18, `Taskfile.yml` defines no `deadcode` task and `go tool` lists -no dead-code analyzer. +no dead-code analyser. ## Collect test, race, coverage, and runtime evidence @@ -226,7 +226,7 @@ diff -u "$evidence_dir/delivery.tsv" "$after_dir/delivery.tsv" If output differs from prediction: confirm checkout, dirty state, script revision, flags, toolchain; explain each delta; branch to semantic discovery -when a count cannot explain behavior. Reject a "better" metric that moved +when a count cannot explain behaviour. Reject a "better" metric that moved duplication, hid a path, or weakened a gate. ## Dated current snapshot @@ -235,15 +235,15 @@ The bundled scripts measured this checkout on 2026-09-18 (HEAD `2e1e1549`). These are post-fix numbers: earlier runs of the same scripts reported roughly 3x these file and line counts because they walked `.worktrees/`. -| Observation | Unstable value | -|---|---:| -| Root production/test/generated Go files | 408 / 402 / 9 | -| Root production/test/generated physical lines | 74,752 / 95,264 / 12,774 | -| `internal/app/archied.Run` body span / approximate complexity | 97 / 19 | -| Root internal packages / direct internal edges | 110 / 316 | -| Tagged config field rows | 194 | -| Tracked paths / tracked `node_modules` paths / tracked symlinks | 1,088 / 0 / 1 | -| `.dockerignore` present | 1 | +| Observation | Unstable value | +| --------------------------------------------------------------- | -----------------------: | +| Root production/test/generated Go files | 408 / 402 / 9 | +| Root production/test/generated physical lines | 74,752 / 95,264 / 12,774 | +| `internal/app/archied.Run` body span / approximate complexity | 97 / 19 | +| Root internal packages / direct internal edges | 110 / 316 | +| Tagged config field rows | 194 | +| Tracked paths / tracked `node_modules` paths / tracked symlinks | 1,088 / 0 / 1 | +| `.dockerignore` present | 1 | `source-metrics.go` and `git ls-files` reconcile here: 408 + 9 generated production files and 402 test files, plus the `tools` module's 5 / 2 / 0, diff --git a/.agents/skills/archie-docs-and-writing/SKILL.md b/.agents/skills/archie-docs-and-writing/SKILL.md index b83bb71cd..69bad5173 100644 --- a/.agents/skills/archie-docs-and-writing/SKILL.md +++ b/.agents/skills/archie-docs-and-writing/SKILL.md @@ -5,7 +5,7 @@ description: Maintain Archie's documentation of record and write durable archite # Maintain Archie documentation -Write one durable record for each decision or behavior. Separate what runs now +Write one durable record for each decision or behaviour. Separate what runs now from what Archie has approved as its destination. Route to `archie-architecture-planning-campaign` for ownership/boundary @@ -22,14 +22,14 @@ for runtime/operations facts. Define a **record of authority** as the one canonical location whose owner may change a claim. -| State | Meaning | Permitted wording | -|---|---|---| -| `CURRENT` | Verified behavior in checked-out code, tests, composition, or executable config | "Currently does" | -| `APPROVED TARGET` | Normative destination approved in architecture index | "Must become"; never "currently does" | -| `OPEN` | Investigation, candidate, or unresolved decision | "Candidate", "unknown", or "requires decision" | -| `HISTORICAL` | Prior design, incident, dead end, or superseded choice | "Previously did" | -| `GENERATED` | Derivative output produced from owned source definition | "Generated from"; never hand-edit | -| `EXTERNAL` | Fact held outside repository, such as deployed config or host state | Date, name verifier, give re-check command | +| State | Meaning | Permitted wording | +| ----------------- | -------------------------------------------------------------------------------- | ---------------------------------------------- | +| `CURRENT` | Verified behaviour in checked-out code, tests, composition, or executable config | "Currently does" | +| `APPROVED TARGET` | Normative destination approved in architecture index | "Must become"; never "currently does" | +| `OPEN` | Investigation, candidate, or unresolved decision | "Candidate", "unknown", or "requires decision" | +| `HISTORICAL` | Prior design, incident, dead end, or superseded choice | "Previously did" | +| `GENERATED` | Derivative output produced from owned source definition | "Generated from"; never hand-edit | +| `EXTERNAL` | Fact held outside repository, such as deployed config or host state | Date, name verifier, give re-check command | When `CURRENT` conflicts with `APPROVED TARGET`, preserve both and state the migration delta. @@ -38,43 +38,43 @@ migration delta. Verified on 2026-09-18: -| Location | Role | Discipline | -|---|---|---| -| Live Go code, tests, `Taskfile.yml`, executable config parsing, composition under `internal/app/` (entered from `cmd/`) | `CURRENT` execution evidence | Trace producers and consumers; tests prove only asserted behavior | -| `CLAUDE.md` | Current contributor and safety protocol plus compact architecture orientation | Verify operational claims against code and `Taskfile.yml`; `AGENTS.md` is a symlink to it | -| `docs/prds/01-project-management.md` | Index and approved foundation for target architecture | Add or change target decisions in the focused document it names | -| `docs/architecture/*.md` | Focused target decisions, active review procedure, migration inventory | Read each file's status | -| `docs/architecture/migration-decisions.md` | `OPEN` migration inventory constrained by approved decisions | Close a question only after code-grounded review | -| `docs/archive/` | `HISTORICAL` material | Mine rationale and failure evidence | -| `CHANGELOG.md` | Release stream and packaged runtime input | One file holds every release; `internal/releaseannounce` parses version headings | -| `tools/docsgen` | Current, partial generator in nested `tools` Go module | Treat its flags and tests—not planned PRD commands—as executable truth | -| `docs/data/generated/contracts.json` | Current working-tree `GENERATED` output | Regenerate; never edit by hand | -| `docs/` | Repository documentation only | Nothing builds, renders, or publishes it; Markdown is the artifact | +| Location | Role | Discipline | +| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| Live Go code, tests, `Taskfile.yml`, executable config parsing, composition under `internal/app/` (entered from `cmd/`) | `CURRENT` execution evidence | Trace producers and consumers; tests prove only asserted behaviour | +| `CLAUDE.md` | Current contributor and safety protocol plus compact architecture orientation | Verify operational claims against code and `Taskfile.yml`; `AGENTS.md` is a symlink to it | +| `docs/prds/01-project-management.md` | Index and approved foundation for target architecture | Add or change target decisions in the focused document it names | +| `docs/architecture/*.md` | Focused target decisions, active review procedure, migration inventory | Read each file's status | +| `docs/architecture/migration-decisions.md` | `OPEN` migration inventory constrained by approved decisions | Close a question only after code-grounded review | +| `docs/archive/` | `HISTORICAL` material | Mine rationale and failure evidence | +| `CHANGELOG.md` | Release stream and packaged runtime input | One file holds every release; `internal/releaseannounce` parses version headings | +| `tools/docsgen` | Current, partial generator in nested `tools` Go module | Treat its flags and tests—not planned PRD commands—as executable truth | +| `docs/data/generated/contracts.json` | Current working-tree `GENERATED` output | Regenerate; never edit by hand | +| `docs/` | Markdown sources and generated JSON for the external Astro website | This repository generates and validates artifacts; the website repository renders and deploys them | The repository root has no `README.md` or `CONTRIBUTING.md` as of 2026-09-18. ## Choose one destination 1. State the reader's question. -2. Identify the owner of the behavior or decision. +2. Identify the owner of the behaviour or decision. 3. Find the existing record of authority. 4. Extend that record or link to it. Do not make a second canonical table. 5. If no owner exists, route the ownership decision through the architecture campaign. 6. If the fact is generated, change the owned source definition and generator. 7. If the fact is external, date it and name the exact observation command. -| Content | Destination | -|---|---| -| Cross-cutting approved architecture index | `docs/prds/01-project-management.md` | +| Content | Destination | +| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Cross-cutting approved architecture index | `docs/prds/01-project-management.md` | | New capability with no settled design yet (CLAUDE.md's "write a decisive doc before coding") | New `docs/prds/.md` — use the PRD template in `references/templates.md`, which folds in a multi-agent execution breakdown so the sub-issues can be picked up without re-deriving the design | -| Focused domain or requirement decision | Matching `docs/architecture/*.md` file | -| Unresolved migration question | `docs/architecture/migration-decisions.md` | -| Contributor protocol that must load before work | `CLAUDE.md` | -| Runtime/API/config reference derivable from code | Domain-owned registry/type, then `tools/docsgen` output | -| Repository documentation prose | `docs/`, linking back to authority with repository-relative paths | -| Shipped release behavior | Matching component changelog; keep `CHANGELOG.md` as two-component index | -| Superseded design retained for context | `docs/archive/`, with historical status | -| Incident or rejected approach | `archie-failure-archaeology`'s chronology | +| Focused domain or requirement decision | Matching `docs/architecture/*.md` file | +| Unresolved migration question | `docs/architecture/migration-decisions.md` | +| Contributor protocol that must load before work | `CLAUDE.md` | +| Runtime/API/config reference derivable from code | Domain-owned registry/type, then `tools/docsgen` output | +| Repository documentation prose | `docs/`, linking back to authority with repository-relative paths | +| Shipped release behaviour | Matching component changelog; keep `CHANGELOG.md` as two-component index | +| Superseded design retained for context | `docs/archive/`, with historical status | +| Incident or rejected approach | `archie-failure-archaeology`'s chronology | Do not duplicate a package map across `CLAUDE.md`, a PRD, and the site. Name the authoritative map and link to it. @@ -94,7 +94,7 @@ Every architecture, feature, or migration record must answer: - **Deletion gate:** What observable proof permits removal? - **Evidence:** Which symbols, tests, commands, and runtime observations support the record? -- **Rollback:** How can behavior and data return safely? +- **Rollback:** How can behaviour and data return safely? - **Unresolved questions:** What remains `OPEN`? Name one owner for every mutable record. A new path is incomplete until the @@ -110,7 +110,7 @@ of authority; the command that re-discovers the evidence. Write `internal/agentexec.Request` and `tools/docsgen.currentContractTypes`. Distinguish evidence strength: -1. Runtime composition and executable behavior. +1. Runtime composition and executable behaviour. 2. Tests that exercise the relevant production seam. 3. Approved target decision. 4. Comments and summaries corroborated by the first three. @@ -136,7 +136,7 @@ the CI shell gate plus `internal/releaseannounce`'s announcer tests ## Maintain generated contracts -Current behavior, verified 2026-09-18: +Current behaviour, verified 2026-09-18: - Tool path is `tools/docsgen`, not `tools/cmd/docsgen`. - Separate Go module replacing root module with `../`. @@ -161,24 +161,22 @@ directory, so a failing gate never rewrites the artifact it judges. Fix a failure with `task docs:generate` and commit the result with the code change that shifted the contract surface. -## Store documentation as repository Markdown +## Maintain documentation consumed by the external Astro website -`docs/` is Markdown read directly in the repository, an editor, or the forge's -file view. Nothing builds, renders, or publishes it. The VitePress site, its -package manifest and lockfile, its landing page, and -`.github/workflows/docs.yml` were removed on 2026-09-12 as an unnecessary build -step; the publishing surface is an open decision -(`docs/architecture/generated-documentation.md`, "Rendering and publishing"). +`docs/` holds Markdown sources and generated JSON consumed by the Astro website +at `offloaded.dev/docs/`. The website is maintained outside this repository. +This repository owns artifact generation and drift checks; it does not build, +preview, or deploy the website. -| Surface | Current state | -|---|---| -| Content | Markdown under `docs/`, including `docs/data/generated/contracts.json` | -| Links | Repository-relative (`../architecture/organisation.md`); no root-absolute links | -| Build | None. There is no site, no dev server, no link checker, no Pages deploy | -| Nav | `docs/prds/01-project-management.md` is the index; there is no site nav | +| Surface | Current state | +| ---------------- | ---------------------------------------------------------------------- | +| Content | Markdown under `docs/` and generated JSON under `docs/data/generated/` | +| Rendering | External Astro website consumes generated artifacts | +| Build and deploy | Owned by the Astro website repository | +| Local checks | `task docs:check`, `task docs:artifact:check`, and `task news:check` | -Because no build validates links, check them yourself or with a one-off script — -nothing catches a dead link for you: +The repository checks artifact drift, not the external site's rendered routes or +links. Verify those in the website repository. ```bash # every relative markdown link target that does not resolve @@ -187,9 +185,8 @@ grep -rhoE '\]\([^)#]+' docs --include=*.md | sed -E 's/^\]\(//' | sort -u ### Enforce source-artifact hygiene -Git tracks no `node_modules` entries (verified 2026-09-12; the 237 `docs/` -symlinks recorded on 2026-07-28 are gone) and no VitePress output. A future -renderer must not reintroduce committed installs or build output. +Git tracks no `node_modules` entries or website build output. The external Astro +repository owns its installed dependencies and generated site files. ```bash git ls-files | grep -c node_modules # expect 0 diff --git a/.agents/skills/archie-docs-and-writing/references/templates.md b/.agents/skills/archie-docs-and-writing/references/templates.md index d7bf57b15..486b6f285 100644 --- a/.agents/skills/archie-docs-and-writing/references/templates.md +++ b/.agents/skills/archie-docs-and-writing/references/templates.md @@ -15,7 +15,7 @@ sections. Keep facts, decisions, and open questions visibly separate. ## Architecture decision record -````markdown +```markdown # **Status:** Proposed | Approved | Superseded by @@ -34,8 +34,8 @@ sections. Keep facts, decisions, and open questions visibly separate. ## Current evidence -| Claim | Evidence | -|---|---| +| Claim | Evidence | +| ------------------ | ------------------------------------- | | | `` — `` | ## Constraints and invariants @@ -44,15 +44,15 @@ sections. Keep facts, decisions, and open questions visibly separate. ## Consumers and boundaries -| Consumer | Contract used | Failure effect | -|---|---|---| -| | | | +| Consumer | Contract used | Failure effect | +| ----------------------------- | ------------------------------ | -------------- | +| | | | ## Options considered -| Option | Benefits | Costs and risks | Evidence | Result | -|---|---|---|---|---| -|