From 7e819d85efb78eb165bb50f1b8fed3668b73eda9 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Fri, 28 Aug 2026 23:06:17 +1000 Subject: [PATCH] chore: fix CLAUDE.md to flow and remove contradictions. --- CLAUDE.md | 786 ++++++++++++++---------------------------------------- 1 file changed, 201 insertions(+), 585 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1bfb836dd..123026e40 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,627 +1,243 @@ -# CLAUDE.md +# AGENTS.md Guidance for any coding agent working in this repository. -`AGENTS.md` is a symlink to this file, so Claude, Codex, Pi, Tau and anything -else reading either name get the same instructions. **Keep every rule here -harness-agnostic**: name the behaviour required, not the tool that provides it. -"Spawn a fresh reviewer that did not write the code" is a rule; "run -`/code-review`" is one harness's way of satisfying it. The single exception is -the memory note under Issue Tracking, which is explicitly Claude-scoped. +Keep every rule here harness-agnostic: name the required behaviour, not the tool +that provides it (e.g. "spawn a fresh reviewer that did not write the code", not +a specific sub-command). + +## Code Quality & Refactoring Standards + +- **Zero Patch Stacking:** Never apply more than two sequential fixes to the + same logic block. If a solution fails twice, scrap the block and rewrite it + cleanly. +- **Root-Cause Fixes:** Fix invalid state at the producer, not via defensive + checks at the consumer. +- **Architectural Simplicity:** Prefer a complete 20-line rewrite over a 5-line + band-aid that adds conditional complexity or obscures intent. +- **Revert on Flail:** If an implementation becomes convoluted to satisfy edge + cases, discard the approach and select a simpler design. ## What this is -**archied** is a resident daemon that polls a forge (GitHub, Gitea planned) for -issues assigned/labelled to it, works each one in an isolated git worktree -through a routed workflow (bootstrap / implement / TDD / feasibility), and opens -pull requests for human review. See `ARCHITECTURE.md` for the full package map, -workflow engine design, task lifecycle, and key design decisions — read it -before making non-trivial changes, since several invariants (env-enforced gates, -model never runs git, agent execution as a data boundary) aren't obvious from -the code alone. +**archied** is a resident daemon that polls a forge (GitHub, Gitea) for issues +assigned/labelled to it, works each one in an isolated git worktree through a +routed workflow (bootstrap / implement / TDD / feasibility), and opens pull +requests for human review. -## Scope discipline (read this before planning anything) +See `ARCHITECTURE.md` for the package map, workflow engine design, task +lifecycle, and key design decisions. Read it before making non-trivial changes. +Key invariants: env-enforced gates, model never runs git, and agent execution +functions as a strict data boundary. -`docs/architecture/` is authoritative for everything it covers: implement -against it, don't re-litigate it, don't restate it in a new document. +## Scope Discipline -It does not cover everything, and this section used to claim it did — it -called the design "complete" and banned design documents outright. That was -wrong on its face: this repo is mid-migration to a domain-oriented structure, -and `docs/architecture/migration-decisions.md` is an **open decision -register** whose entire job is holding design that is not settled yet. A rule -asserting the design is finished, in a tree that ships a list of what remains -to be decided, pushed every genuinely new capability through a prohibition -aimed only at sprawl. The ban was a proxy: what it meant to stop was prose -substituting for a diff, not thinking before building something new. +`docs/architecture/` is authoritative for settled design. +`docs/architecture/migration-decisions.md` is the open decision register for the +domain migration. -So the test is **is there a settled design for this**, never **is this a -document**: +- **Settled design exists** → Implement it immediately with a diff. Do not + produce design prose. If a small detail is missing, ask the maintainer + directly. +- **No settled design exists (or open in `migration-decisions.md`)** → Write a + decisive, 1-page design doc before coding. Land new capabilities in + `docs/prds/` and migration questions in + `docs/architecture/migration-decisions.md`. Promote to `docs/architecture/` + only after implementation lands. +- **Strictly Prohibited:** Ownership ledgers, field-level inventories, + current-state traces, parity matrices for their own sake, and + planning/refactor tracking issues. +- **Solo Project Context:** Prefer the smallest workable change over extensive + defensive scaffolding. -- **Settled design exists** → implement it. Producing prose instead of a diff - is the failure. If one detail is missing, ask the maintainer in a sentence; - don't write a document to resolve a sentence-sized question. -- **No settled design exists** — genuinely new capability, or an open item in - `migration-decisions.md` → design first, briefly and decisively. This is - required, not merely tolerated. Accreting diffs toward a new architecture - without deciding its shape is how the flat `internal/` layout happened, and - undoing that is measured in weeks. +## Deployment Model -A design artifact earns its place by being short, decisive, and followed by -code: +- **Systemd is optional:** `deployments/` holds supported profiles + (`single-forge-github.toml`, `multi-forge-github-gitea.toml`, + `local-ollama-standalone.toml`, `docker-nats-stack.toml`, + `systemd-user-service.md`). Never assume a systemd unit exists. +- **Chat filesystem confinement:** Builtin tools default to workspace jail via + `SetPathConfinement(!unrestricted)`. Unrestricted access requires + `[chat] unrestricted_filesystem = true`. +- **NATS endpoint immutability:** The daemon passes agent containers its startup + connection URL (`d.ConnectedNATS.URL`). Containers and daemon must resolve + this address. Embedded mode binds to the Docker bridge gateway. A SIGHUP + reload of `nats.url` logs an error requiring restart to prevent split-brain + delivery. +- **Container pull policy:** `containers.pull_policy` must be `"missing"` + (default) or `"always"`. Private registries return 401 on `"always"` because + no auth is sent. Refresh explicitly via `docker compose pull agent`. +- **Docker Compose:** `docker-compose.yml` carries optional external NATS and + the `agent` build stanza. The agent uses a `build` profile so `up -d nats` + never starts it as a persistent service. +- **Config path:** Runtime configuration lives at + `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`. Nothing in the working + tree is load-bearing at runtime. -- One page, and it **decides**. It does not survey options, inventory fields, - or trace current state — the code is the current state, so a document - restating it is stale on arrival. -- It lands in a named home: `docs/prds/` for new capability, an entry in - `docs/architecture/migration-decisions.md` for an open migration question. - Promote it into `docs/architecture/` only once it is built and true. -- It is not finished until a diff follows it. Design with no implementation is - the same sprawl in better clothes. -- Failure test: cut anything a reader could have learned by reading the code. +## Release Process -Still prohibited, and none of these were ever design: - -- Ownership ledgers, field-level inventories, current-state traces, parity - matrices written for their own sake, and review campaigns. -- Planning, review, or refactor **issues**. Open issues only for concrete bugs - and user-facing features. - -This is a **solo project**. There is no review board, no handoff to a -zero-context engineer, no compliance requirement. Prefer the smallest change -that works over the most defensible one. - -Issues are tracked in GitHub Issues; grouped issues can be linked under an -epic, with subtasks linked to the epic. - -## Deployment model - -**archied supports several deployment shapes; systemd is not required.** -`deployments/` holds the supported profiles — `single-forge-github.toml`, -`multi-forge-github-gitea.toml`, `local-ollama-standalone.toml`, -`docker-nats-stack.toml`, and `systemd-user-service.md` as one operational -runbook among them. Do not write code or docs that assume a systemd unit exists. - -**The chat agent's file tools are workspace-confined by default.** `builtin` -tool construction calls `SetPathConfinement(!unrestricted)`, so read, write, -edit, find and grep are jailed to the configured workspace unless -`[chat] unrestricted_filesystem = true` lifts it -(`internal/config/config.go`, `internal/tools/provider/builtin/provider.go`). -That setting is commented out in `config.example.toml` — an operator opt-in, not -the default, and not an architectural requirement. Where the daemon runs and -whether the jail is lifted together determine which filesystem those tools can -reach; neither is something the code should assume. `archied` and embedded NATS -run in the native daemon; per-task `archie-agent` workers run in Docker. - -**The daemon hands agent containers the NATS endpoint its own client connected with at startup** — see -`containerEnv` in `internal/daemon/daemon.go`, which appends `NATS_URL=` from -`d.ConnectedNATS.URL`, captured at construction. That endpoint must therefore -be reachable from wherever the daemon runs *and* from inside the containers. -Embedded mode resolves the selected Docker bridge first and binds its -authenticated listener to that bridge's host gateway. External mode needs an -operator-supplied URL reachable from both; for the optional Compose broker that -is the pinned `172.19.0.1` gateway, not the service name and not localhost. - -The two URLs are the same today and deliberately *not* the same after a -SIGHUP reload of `nats.url`: the daemon's own client is startup-built, so a -reload that pointed new containers at the new URL would launch them on a -server the daemon is not publishing on, and every task would park with -`ErrNoResponders`. Freezing the connected endpoint makes that divergence -impossible regardless of what the config says or who reloads it; a reloaded -`nats.url` is logged as a change that requires a restart. - -**`containers.pull_policy` can only be `"missing"`** (the default) or -`"always"`. `"always"` against a private registry answers 401, because the -daemon sends no credentials to the Docker API. Refresh the agent image -explicitly instead: `docker compose pull agent`. - -**`docker-compose.yml`** is optional in the default embedded deployment. It -carries an external NATS service plus the agent build stanza. The agent has a -`build` profile so `up -d nats` never starts it as a service — without the -profile, Compose creates a container that exits 0 immediately and reports -"Started", which reads as a crash loop. `docker compose build agent` and -`docker compose pull agent` work by name without activating the profile. - -**Config lives outside the repo**, at -`${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`. Nothing in the repo working -tree is load-bearing at runtime. Reference templates are in `deployments/`; -`config.example.toml` is the annotated schema. - -## Release process - -See `RELEASING.md` for the full process and the standing rule on when to -version each component — most sessions only touch `archied`, so most releases -are gateway-only (`RUNTIME=skip`) by default. Don't ask whether to skip an -untouched component; skip it and say so in the handoff. +See `RELEASING.md`. Most sessions touch only `archied`, making releases +gateway-only (`RUNTIME=skip`) by default. Skip untouched components +automatically and note it in the handoff. ## Build & Test -Commands are defined in `Taskfile.yml` (uses [Task](https://taskfile.dev)); run -`task --list` to see everything. - -**Prerequisites:** Go 1.26.5 (matched exactly by `go.mod`), [Task], `gofumpt`, -`golangci-lint`, and **Node/npm** — `task check` runs the dashboard suite too, so -a Go-only toolchain cannot complete the gate. - -[Task]: https://taskfile.dev +Commands are defined in `Taskfile.yml` (requires Go 1.26.5, +[Task](https://taskfile.dev), `gofumpt`, `golangci-lint`, and Node/npm). ```bash task build # build archied and archie-agent binaries into bin/ task test # go test ./... -count=1 task test:ui # dashboard node tests (DOM-building primitives) -task ui # build the dashboard into ui/dist (committed — see below) +task ui # build dashboard into ui/dist (LAW asset) task fmt # gofumpt -w . && go fix ./... task vet # go vet ./... task lint # golangci-lint run ./... -task check # fmt + go fix + vet + build + test + test:ui -task dev # archied live-reload + Vite HMR together, on :5173 +task check # fmt + go fix + vet + build + test + test:ui (The Definitive Gate) +task dev # archied live-reload + Vite HMR together on :5173 ``` -`task check` is the gate, and it includes `test:ui` deliberately: nothing else -runs the dashboard suite, so left out it rots silently and a broken DOM -primitive ships. Note that `task fmt` **rewrites files**, so `check` is not a -read-only verification step. - -Run a single test: `go test ./internal/domain/workflow/... -run TestName -v`. - -Docker helpers: `task docker-build` builds the agent image locally; -`task docker-up`, `task docker-down`, and `task docker-logs` manage the optional -external NATS service. - -## Repository hygiene - -- **`ui/dist` is committed on purpose.** The Go build embeds it, so building - `archied` must never require a Node toolchain. If you change anything under - `ui/src`, run `task ui` and commit the rebuilt `ui/dist` in the same change. - Never add it to `.gitignore`. -- **Do not commit** build artefacts or local state: `/archied`, `/archie-agent`, - `/bin/`, `*.db`, `*.png` working screenshots, `.references/`, - `config.production.toml`, `.env`, or the docs site's `node_modules/` and - `.vitepress/{cache,dist}/`. `.gitignore` already covers these; the point is not - to defeat it. -- **Scratch files go outside the repo**, in the OS temp directory or your - harness's scratch area — not in the working tree, where `worktree.CommitAll` - will sweep them up (see the `WriteTaskJSON` trap below). -- Commits follow **Conventional Commits** scoped by package: - `feat(webui): ...`, `fix(build): ...`, `ci: ...`, `chore(release): ...`. -- Commit finished, gate-clean work (passing `task check`, adversarial review - clean) without stopping to ask first. Only push when asked. - -## Organisation (strict) - -`docs/architecture/organisation.md` is authoritative and approved. This section -is the enforcement summary — read that doc before any structural change, and -change the doc first if the rule itself needs to change. - -**Archie is domain-driven, not flat.** `internal/` currently holds ~35 packages -side by side. That is a migration in progress, not the target. Do **not** infer -the structure from what is there: adding a sibling package next to -`internal/gateway/` because that is where similar code lives today is how the -flat layout keeps regrowing, and undoing it is measured in weeks. - -### The layers, and what each owns - -- **`internal/domain//`** — one cohesive job Archie performs. Owns that - job's language, state, rules, operations, commands, events, policy - implementations, runtime settings, and the _contracts_ it needs from the - outside world. A domain declares the interface it needs; it never names who - implements it. -- **`internal/infrastructure//`** — implementations of those contracts: - configuration, persistence, forge clients, event-bus transports, anything that - talks to something external. -- **`internal/app//`** — composition. Constructs domains and - infrastructure, translates external configuration into domain settings, - connects commands and events, starts services in dependency order, owns health - aggregation and shutdown ordering. It is the only layer that knows about both - of the two above. -- **`cmd//`** — process-level input only: flags, environment, signals. - It MUST NOT contain substantive wiring and MUST NOT act as a service locator. - -These stay under `internal/`. That is a compiler-enforced visibility boundary, -not a naming convention: moving a layer to the repository root would make -Archie's domain types importable by any module that depends on this one, and -silently commit us to API stability on exactly the code that most needs to keep -changing. - -### Dependency direction is the invariant - -`cmd → app → {domain, infrastructure}`, and `infrastructure → domain` to -implement its contracts. Nothing points back up: a domain importing -infrastructure, or infrastructure importing app, is a defect regardless of how -convenient it is. If a domain needs something an infrastructure package has, the -domain declares an interface and app wires the implementation in. - -### Cross-cutting packages - -Some packages are neither domain nor infrastructure because they serve both — -`logging`, `events`, `eventbus`, `policy`, `taskstate`. They sit as named -top-level packages under `internal/`, each named for what it provides. - -The defining property is checkable, and it is the whole rule: **a cross-cutting -package may be imported by any layer, and imports none of them.** Zero -dependencies on domain, infrastructure or app. That is what lets it sit outside -the dependency direction safely — it is a sink, never a source, so it cannot -create a cycle or smuggle a dependency inward. - -It is also the failure test: the moment such a package imports a domain type it -has stopped being cross-cutting and become domain code that has been misfiled. - -There is deliberately **no `shared/` directory**. "Shared" is a category, not a -name, and a directory named for a category becomes the place things go when -nobody can say what they are. `utils`, `helpers`, `common` and `misc` are -prohibited for the same reason: if a package cannot be named for what it -provides, it is misplaced, not shared. - -Cross-cutting utilities exist precisely to keep the code DRY — a function owned -by no single package and used by many. Do not wait for a second consumer to -justify one, and do not copy a helper into two domains to avoid creating one. -(The "second consumer" rule below is about feature code, not this.) - -### Within a package: organise by concern, never by layer or type - -- One file per API area, named for it: `api_tasks.go`, `api_logs.go`, - `api_skills.go`. A new endpoint group is a new file. Cross-cutting wiring gets - its own file too: `server.go` (routes and construction only), `auth.go`, - `sse.go`. -- **A package owns its own format end to end.** `internal/logging` defines the - on-disk log format _and_ reads it (`reader.go`); `internal/webui/api_logs.go` - is transport and parses nothing. If two packages both know a format, one of - them is wrong. -- Empty or ceremonial `entities`, `repositories` or `services` layers are - prohibited. Code that changes together lives together. -- No grab-bag file. If you cannot name a file after the single thing it does, it - is doing more than one thing. - -### Frontend - -- One folder per feature under `ui/src//`, holding its own `.js` and - `.css`, with the JS importing its own CSS. Changing logs cannot disturb tasks. -- Shared primitives live in `ui/src/base/` and `ui/src/css/`, one file per - primitive (`button.css`, `card.css`, `pill.css`, `table.css`). -- Extract a feature's code into a shared primitive on the **second** real - consumer, never in anticipation of one. - -### When to split - -Split on concern, not line count. The triggers are: you scroll past unrelated -code to change one thing, or two people editing different features collide in -one file. Renaming a file to something vaguer to make new code fit is the -failure this rule exists to prevent — add a file. - -### Why - -A domain that declares its own contracts can be tested, reviewed, replaced and -reasoned about without the rest of the system. Once the direction of dependency -inverts anywhere, that stops being true everywhere downstream. It also has an -immediate cost with parallel sessions: `cmd/archied/main.go` had to be split -hunk-by-hunk three times in one day because two sessions were editing it at once -— a symptom of wiring living where it should not. - -## Architecture - -Full details live in `ARCHITECTURE.md` — do not duplicate it here; skim it -whenever touching the daemon, workflow engine, or forge/worktree/store -boundaries. Summary of what's evolved since that doc was last fully accurate: - -- **The domain migration has begun.** `internal/domain/` (curator, workflow, - workintake) and `internal/infrastructure/` (configuration, eventbus, - modelcatalog, terminalprompt) both exist. The tree is authoritative over any - package table; see `docs/architecture/migration-decisions.md` for the recorded - position and what was agreed next. -- The daemon has grown an RPC split (`internal/forgerpc`, `internal/storerpc`, - `internal/worktreerpc`, `internal/natsrpc`) used by the task-scoped - `archie-agent` worker. Autonomous workflows cross one full-task core-NATS - handoff; the daemon has no local workflow runner. The eventbus transport is - `internal/infrastructure/eventbus/`. Check those plus `docker-compose.yml` for - the current split between `archied` and sandboxed workers. -- `internal/gate/` — quality gate execution (the "environmental constraints over - prompt rules" mechanism). -- `internal/skill/`, `internal/skillscript/`, `internal/yaegiutil/` — SKILL.md - support (listed as "Planned" in ARCHITECTURE.md; now has real implementation — - check these packages for current state before assuming it's unbuilt). -- `internal/channels/` — inbound chat/notification channels (e.g. Telegram — see - `internal/channels/telegram/`, `internal/channels/email/`); channel-agnostic - interface in `internal/channels/channel.go`. -- `internal/memory/`, `internal/gateway/`, - `internal/container/`, `internal/plugin/`, `internal/tools/`, - `internal/taskrun/` — not documented in ARCHITECTURE.md; read the package - before modifying, its doc comment and tests are the source of truth. - -### Per-package traps (things an agent will break if it doesn't check first) - -- **`internal/channels/telegram/`** — the long-polling branch calls - `dropPendingUpdates(ctx, b)` before `go b.Start(ctx)`. This clears Telegram's - 24h undelivered-update queue so a reboot doesn't answer hours-old messages. It - also runs on `/restart`. The webhook branch already passes - `DropPendingUpdates: true` in `SetWebhookParams`; both paths must stay - consistent. -- **Telegram command menus resolve by SCOPE SPECIFICITY, not recency.** Order, - most specific first: `chat_member` > `chat` > `chat_administrators` > - `all_chat_administrators` > `all_group_chats` > `all_private_chats` > - `default`. So `SetMyCommands` on `default` alone is **invisible in DMs** if - anything was ever registered on `all_private_chats`. Hit when migrating a bot - token between applications: our 8 commands landed on `default` and logged - success while the menu still showed ~60 stale commands from the previous app. - Menus are server-side state owned by Telegram and keyed to the **bot token** — - they survive redeploys, rewrites and whole-application migrations. Inheriting a - token means inheriting its menu, webhook config and other bot-level settings, - so audit `getMyCommands` per scope and `getWebhookInfo` when taking one over. - `commands.go` publishes to `default` + `all_private_chats` + `all_group_chats` - so leftovers are overwritten rather than shadowing. -- **`ai-sdk` streaming: `FullStream` is authoritative and MUST be drained until - close.** Its writes are *synchronous*, so an unread `FullStream` stalls the - producer and deadlocks the turn. `TextStream` is best-effort and silently - DROPS deltas when not drained — consuming it deadlocked every streamed reply - in production. Range `FullStream` and collect `core.StreamPartTextDelta`. See - the doc comment on `core/stream_impl.go`. Related: check the pinned - `go-telegram/bot` version against latest before hand-rolling anything — a - Markdown→HTML converter was written while 4 releases behind, and - `SendRichMessage` with `models.InputRichMessage{Markdown}` had made it - obsolete. `EscapeMarkdown` does the *inverse* of formatting, and - `ParseModeMarkdown == "MarkdownV2"` while `ParseModeMarkdownV1 == "Markdown"` - — the names disagree with the values. -- **NATS, three behaviours that have each caused a real defect:** - (1) *Work-queue retention forbids overlapping consumers.* `ARCHIE_TASKS` uses - `jetstream.WorkQueuePolicy`, so two consumers with overlapping `FilterSubjects` - conflict and the later one silently receives nothing. `nats.Client.Subscribe` - creates a NEW consumer, so calling it on subjects the client's own durable - consumer already filters will never deliver — drain the existing consumer with - `Fetch` instead. `internal/app/agentworker` deliberately uses core NATS only; - restoring a worker JetStream consumer would also restore the deleted - single-stage execution topology. - (2) *Reply inboxes are not stream subjects.* Answering a request must use core - NATS: the request message's reply address is an ephemeral `_INBOX.*` belonging - to one waiting caller and part of no stream, so a durable publish to it fails. - Full-task and RPC responders use core `msg.Respond`; never route their replies - through `eventbus.Publisher`. - (3) *Subscribe does not mean reachable.* `nc.Subscribe` only queues the SUB - frame client-side, so code that registers a responder and immediately issues a - request can beat its own subscription and get `ErrNoResponders` from a - responder that is, by then, listening. `natsrpc.RegisterAll` now flushes before - returning — this was the cause of the long-standing - `TestRunTaskExecutesBootstrapWorkflowEndToEnd` CI flake that passed in - isolation and failed under full-suite load. -- **`internal/gateway/` chat prompt** — `BuildSystemPrompt` renders - `templates/archie.md.tpl`. The `` block is built from the **same** - `core.ToolSet` passed to the model, so the prompt cannot claim a tool the model - cannot call; never source the tool list from anywhere else. An empty toolset - deliberately renders "no tools are available" rather than an empty block, - because an empty block reads as "you have tools" and the model invents them. - Personas are the STYLE layer only — instruction precedence, core rules and the - ``/`` blocks live in the template, so selecting a persona can never - strip rules or tool inventory. Do not move rules into persona strings. - `internal/tools/provider/contract_test.go` asserts the literal wiring strings - `chatGenerateOptions(nil, toolReg` and `toolSummaries(options.Tools)` in - `cmd/archied/main.go` — refactoring that call site fails that test **by - design**. -- **`internal/container/pool.go` `WriteTaskJSON`** — the per-task boot brief - goes to `/.git/task.json`, not the worktree root. - `worktree.CommitAll` stages via go-git `Add{All:true}`, which ignores - `.gitignore` and `.git/info/exclude`, so anything in the worktree root is - pushed onto the task branch. Nothing under `.git` can be tracked; - `worktree.go:41-46` documents this reasoning for the prepared sentinel. If you - change the path, update `internal/infrastructure/agentboot/task.go` `TaskID` - (the reader) in lockstep. -- **MCP providers are registered by the daemon as _optional_** - (`cmd/archied/ main.go`, `providerRegistry.RegisterOptional`). One that cannot - start is logged at error level, excluded from the running set, and reported - through `Registry.Health` as degraded — it does not roll back the other - providers or stop the daemon. That was previously a hard failure, so one - broken npm package unregistered every builtin tool and crash-looped archied - under `Restart=on-failure`, taking Telegram with it. Providers the daemon - genuinely requires still use `Register` and keep atomic rollback; check - `providerRegistry.Skipped()` when tools are mysteriously missing. No - npx-launched servers are configured in production anyway — the builtin tools - (read, write, edit, find, grep, shell) and `web_fetch`. There is no `test` - tool; gates run test commands, the model does not. - -**Task lifecycle** (from ARCHITECTURE.md, still current): -`queued → running(workflow:stage) → pr_open → merged|rejected`, with -`waiting_human` and `parked` side states. Crash recovery re-queues anything left -`running`. A park records its reason on the task, which the dashboard and -`/api/tasks` surface; it no longer comments on the forge issue. Retries are an -explicit operator action (dashboard or chat), capped by `max_retries`, not a -label a human removes. - -**Config** is daemon-level TOML (see `config.example.toml`), not per-repo files -in this repo. Multi-identity deployments run more than one identity from a -single daemon, each with a distinct `bot_user`; see -`deployments/multi-forge-github-gitea.toml` and `docs/architecture/identity.md` -before changing multi-identity or dispatch behaviour. Details of any particular -operator's hosts belong in that operator's own notes, not here. - -## Conventions - -- Go 1.26.5, module `github.com/samcharles93/archie-core`. -- `ai-sdk/runtime`, `ai-sdk/agentloop`, `ai-sdk/core` are external other - projects, not vendored copies. Changes affect other repos. -- **Commit the meaning, not just the change.** When a change alters what - something MEANS rather than what it does, say so explicitly in the commit body - and in the code comment: "X used to mean A; it now means B, because C." Update - the doc comment in the same commit — a comment that contradicts its code is - worse than no comment, because the next reader trusts it. This is not - ceremony: over 2026-08-04/05, three consecutive rounds of fixes each introduced - a regression the next round caught, and **every one passed `task check` with - tests written for it** (a summary that sorted to the end of history; a cache - slot claimed before the store write; a degraded container pool that silently - ran agent loops in-process with the daemon's own authority, removing the - isolation boundary `[containers]` exists to provide). Tests catch behaviour - that breaks; they do not catch behaviour that quietly starts meaning something - else. Roughly half of what adversarial reviewers found, they found by noticing - a doc comment or commit message that no longer matched the code. -- **Lifting code from tau requires a provenance header** on every copied file, - naming the tau source path, the tau commit it came from, and the deliberate - mutations. This turns copy-paste drift into a diff instead of archaeology. - (Reuse strategy is copy-and-mutate, never extraction into shared libraries.) -- Non-interactive shell commands only: some environments alias `cp`/`mv`/`rm` to - `-i`. Use `cp -f`, `mv -f`, `rm -f`/`rm -rf`, `scp -o BatchMode=yes`, - `ssh -o BatchMode=yes`, `apt-get -y`. -- Environmental enforcement over prompt rules: gates, test-file protection, and - diff caps are code-level checks the agent cannot talk its way around — follow - this pattern for any new safety constraint rather than adding it to a system - prompt. -- **Plugin engine rule (strict):** “engine” means a typed, lifecycle-managed - capability family with an owning registry or manager; it never means another - method on the generic plugin interface. Keep `plugin.Plugin` metadata-only, - give plugins narrow typed registrars instead of daemon access, and apply the - lifecycle and trust-boundary requirements in - [ARCHITECTURE.md#plugin-engine-rule-strict](ARCHITECTURE.md#plugin-engine-rule-strict). - Its mechanically testable structure is enforced by - `internal/plugin/architecture_test.go`; reviewers enforce its lifecycle, - access, and trust semantics. -- The model/agent never runs git directly — worktree operations - (`internal/worktree/`) are deterministic daemon-owned steps, not agent tools. - -## Development Protocol (mandatory) - -This is not optional style guidance — every code change in this repo follows -this sequence. It's the same discipline archied enforces on _itself_ via the -TDD workflow in `ARCHITECTURE.md`. - -**`task check` is the definitive quality gate.** `task check` = `fmt` + -`go fix ./...` + `vet` + `build` + `test`, and it is the one command that must -pass, clean, before any change is considered done — it's the literal analogue of -the `[[repos.gate]]` archied runs against every PR it opens. Don't hand-pick a -subset of `go test`/`go vet`/`go build` and call it good; run `task check` (or -the scoped equivalent, e.g. `go test ./internal/foo/... -count=1` + -`golangci-lint run ./internal/foo/...` for a single package) and confirm it's -clean. - -**Red-then-green, definitively:** - -1. **Red** — write the failing test(s) first, against the _intended_ behavior, - before any implementation code exists. Run them and confirm they fail for the - right reason (not a compile error). -2. **Green** — write the minimum implementation to make those tests pass. No - implementation code is written before its test exists and fails. -3. Confirm via `task check` (or scoped `go test .../... -count=1`) that the - suite is green, `golangci-lint run` reports zero findings, and `gofumpt -w .` - reports no unformatted files. -4. No hardcoded values in tests (use parameterized test tables), no hardcoded - identity/config values in implementation code, and every error path gets a - test. - -**Adversarial verification is mandatory, and it runs as a separate pass from a -fresh reviewer — never self-certified by the implementer.** After red-then-green -is green: - -- Run the review from a context with no memory of how the code was written, and - instruct it to assume every line is wrong until proven correct. Any mechanism - that achieves this is fine — a fresh subagent, a separate session, a review - command your harness provides. -- The checklist: all tests pass, lint is zero-findings, formatting is clean, - then a manual read of every non-test file in the changed package for — dead - code paths, unchecked error returns, hardcoded values that should be - parameters/constants, interface satisfaction, nil-pointer risk, goroutine - leaks, and races on shared mutable state. -- Findings are **reported**, not silently fixed by the same pass that wrote the - code — a finding that survives blocks closing the work, it doesn't get waved - through. (If your harness has a structured findings mechanism, use it; - otherwise a plain list is fine.) -- Only close out the issue once the adversarial pass reports zero surviving - findings. - -**Lint-driven changes are behaviour-bearing. Review them; never trust them.** -Two confirmed regressions, one from each shape lint work takes: - -1. **Autofix.** A `golangci-lint --fix` batch across 8 files had its `errorlint` - fix in `internal/tools/builtin/grep.go` rewrite - `if exitErr, ok := err.(*exec.ExitError); ok && exitErr.ExitCode() == 1` into - `errors.As(err, &exitErr)` **without the exit-code check**. ripgrep exit 1 - means no matches; exit 2 means the search never ran. So every failure was - reported to the model as "no matches found", and the agent would state a file - contains nothing on the strength of a search that never happened. The fix kept - `errors.As` **and** restored the predicate — errorlint reports 0 issues on - that form, so satisfying the linter never required dropping it. *Pattern:* - fixers rewrite the error-matching part of a compound condition and can widen - or narrow the predicate around it. Any autofix touching a condition needs its - pre-fix behaviour checked. -2. **Structural extraction** — the riskier shape. Clearing a `nestif` finding - extracted a helper that took a slice **by pointer** and appended every - surviving field to it; the caller's own loop then appended the same fields - again. Every model name doubled (`/model gpt-5.6` asked the router for - `gpt-5.6 gpt-5.6`), and an index loop becoming a range loop meant a - space-separated `--provider openai` value was no longer consumed with its - flag. Telegram model switching broke outright and nobody noticed. *Pattern:* - when a `gocognit`/`nestif`/`cyclop` extraction hands a collection to a helper - by pointer, or turns an index loop into a range loop, check the accumulation - and skip semantics. The compiler catches neither. - -**Verification discipline:** confirm a regression test actually fails against the -buggy version before trusting it. The grep bug returned -`Content: "no matches found", IsError: false`, which a naive test asserting only -"no error" would have passed. For the doubled model name, assert **field count** -rather than string equality, so a future re-extraction cannot pass by doubling a -different part of the string. - -## Issue Tracking - -This project uses **GitHub Issues** (`samcharles93/archie-core`) via `gh` for -issue tracking. Epics are parent issues; their work items are linked as native -GitHub sub-issues. Labels: `task`, `feature`/`enhancement`, `bug`, `epic`, -plus `in-progress` for active work. - -*Claude-specific:* project memory lives in -`~/.claude/projects/-work-apps-archie-core/memory/`. Other harnesses should use -their own equivalent — nothing in this repo depends on it. - - - -## Beads Issue Tracker - -This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands. - -### Quick Reference +Single package/test runs: ```bash -bd ready # Find available work -bd show # View issue details -bd update --claim # Claim work -bd close # Complete work +go test ./internal/domain/workflow/... -run TestName -v -count=1 ``` -### Rules +## Repository Hygiene -- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists -- Run `bd prime` for detailed command reference and session close protocol -- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files +- **Generated assets are LAW:** Never modify, revert, or ignore generated files + in `ui/dist/` or schema outputs. Incorporate them into relevant commits. +- **Ignored paths:** Never commit build artifacts, binaries (`/bin/`, + `/archied`), DB files, working screenshots, `.references/`, or + `node_modules/`. +- **Scratch files:** Place scratch files strictly in `/tmp` or the harness + scratch space. Never put scratch files in the working tree + (`worktree.CommitAll` will stage them). +- **Conventional Commits:** Scope by package: `feat(webui): ...`, + `fix(build): ...`, `chore(release): ...`. +- **Commit policy:** Commit finished, gate-clean changes (`task check` passing + + clean adversarial review) without asking. Push only when instructed. -**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns. +## Organisation (Strict Domain-Driven Architecture) -## Agent Context Profiles +`docs/architecture/organisation.md` is authoritative. Do not follow flat +structures found in legacy packages. -The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions. +### Layers and Ownership -- **Default**: Use `bd` for task tracking. Commit finished, gate-clean work - (passing `task check`, adversarial review clean) without stopping to ask - first, scoping `git add` to the files the change actually touches. - Do not push or run Dolt remote sync unless explicitly asked. At handoff, - report changed files, validation, and issue status. +- `internal/domain//`: Domain logic, entities, state machines, commands, + events, and required contracts (interfaces). Never imports infrastructure or + app. +- `internal/infrastructure//`: Implementations of domain contracts + (persistence, forge clients, external transports, config loading). +- `internal/app//`: Dependency injection, wiring domain to + infrastructure, lifecycle management, and shutdown ordering. +- `cmd//`: CLI flag parsing, OS signal traps, and entry point routing + only. No domain wiring. -## Session Completion +### Invariants -This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions. +- **Dependency Flow:** `cmd → app → {domain, infrastructure}`, with + `infrastructure → domain` implementing contracts. Downward/inward dependencies + only. +- **Cross-Cutting Packages:** `logging`, `events`, `eventbus`, `policy`, + `taskstate` sit directly under `internal/`. They may be imported by any layer, + but **must import zero internal packages**. No `shared/`, `utils/`, or + `common/` catch-alls. +- **File Layout:** One file per API concern (`api_tasks.go`, `api_logs.go`). A + package owns its on-disk format end-to-end (e.g. `internal/logging` defines + and reads its format; transport layers do not parse). +- **Frontend:** Features live in `ui/src//` with colocated `.js` and + `.css`. Extract to `ui/src/base/` only on the second distinct consumer. + +## Per-Package Invariants & Traps + +- **`internal/channels/telegram/`:** +- The long-polling worker must call `dropPendingUpdates(ctx, b)` before + `b.Start(ctx)` and on `/restart`. +- Always publish command menus to `default`, `all_private_chats`, and + `all_group_chats` simultaneously via `commands.go` to avoid scope shadowing + from legacy registrations. + +- **`ai-sdk` Streaming:** `FullStream` writes synchronously and MUST be drained + completely to prevent producer deadlocks. Do not rely on `TextStream` (drops + deltas). +- **NATS Invariants:** +- `ARCHIE_TASKS` uses `jetstream.WorkQueuePolicy`. Do not bind overlapping + consumer filters; use `Fetch` on existing durables instead of new `Subscribe` + calls. +- RPC and task responses must use core NATS `msg.Respond` to write to ephemeral + `_INBOX.*` subjects, not `eventbus.Publisher`. +- Always flush connections (`nc.Flush()`) immediately after registering + responders to avoid race conditions on initial requests. + +- **`internal/gateway/` Chat Prompt:** System prompt `` blocks are + rendered strictly from the active `core.ToolSet`. Never decouple prompt tool + definitions from passed runtime tools. +- **`internal/container/pool.go` (`WriteTaskJSON`):** Write task briefs to + `/.git/task.json`. Never place them in the worktree root (`go-git` + `Add{All:true}` ignores `.gitignore` and leaks root files into branch + commits). +- **MCP Providers:** Daemon registers providers as optional via + `providerRegistry.RegisterOptional`. Missing or failed providers log warnings + and degrade health without terminating the process. + +## Development Protocol + +1. **Red (Failing Test):** Write failing test cases first using table-driven + tests against target behaviour. Verify the failure originates from test + assertions, not compilation errors. +2. **Green (Implementation):** Implement minimal code to satisfy the failing + tests. +3. **Quality Gate:** Run `task check`. +4. **Formatting is LAW:** Adopt all formatting and simplification changes from + `task fmt` (`gofumpt` + `go fix`) verbatim. Never revert or fight canonical + linter/formatter diffs. +5. **Adversarial Verification:** Run a verification pass using an isolated + reviewer context assuming all changes are incorrect until verified. Check: + dead code, unchecked errors, hardcoded constants, missing error paths, nil + pointers, goroutine leaks, and race conditions. +6. **Linter Guard:** + +- When using `errorlint` fixes, ensure boolean predicates (e.g. + `exitErr.ExitCode() == 1`) are retained alongside `errors.As`. +- When extracting loops/conditionals, verify slice mutations and pointer + semantics do not duplicate elements. + +## Issue Tracking (Beads) + +All task management is tracked via **bd (beads)**. Do not write local Markdown +TODO lists or use non-Beads trackers. + +### Commands + +```bash +bd ready # List unclaimed work +bd show # View issue details +bd update --claim # Claim an issue +bd close # Mark issue complete +bd remember # Persist cross-session architectural facts +``` + +- Run `bd prime` to inspect full engine context. +- Use `bd remember` for knowledge retention. Do not write to root `MEMORY.md` + files. +- Issues live in a local Dolt DB; `.beads/issues.jsonl` is an export. + +## Session Completion Protocol + +1. **Log remaining work:** File new items via `bd` for identified debt or + follow-up tasks. +2. **Run gate:** Verify `task check` passes completely clean. +3. **Update tracker:** Close finished issues via `bd close `. +4. **Commit:** -1. **File issues for remaining work** - Create beads for anything that needs follow-up -2. **Run quality gates** (if code changed) - Tests, linters, builds -3. **Update issue status** - Close finished work, update in-progress items -4. **Commit, then handle push/sync**: ```bash - # Default: commit finished, gate-clean work directly. - git add - git commit -m "..." - git status - - # Push/sync only when explicitly asked: - git pull --rebase - bd dolt push - git push - git status + git add + git commit -m "feat(scope): description" ``` -5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/push step -**Critical rules:** -- Explicit user or orchestrator instructions override this Beads block. -- Do not push or run Dolt remote sync without explicit authority. -- If a required sync or push is blocked, stop and report the exact command and error. - +5. **Sync & Push Policy:** Do not push to git remotes or run `bd dolt push` + unless explicitly instructed. +6. **Handoff:** Report changed files, gate verification results, and active + issue states.