chore: fix CLAUDE.md to flow and remove contradictions.

This commit is contained in:
sam committed 2026-08-28 23:06:17 +10:00
1 parent ec5e83a995
commit 7e819d85ef
1 file changed
+201 -585
+201 -585
View File
@@ -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/<area>/`** — 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/<service>/`** — implementations of those contracts:
configuration, persistence, forge clients, event-bus transports, anything that
talks to something external.
- **`internal/app/<application>/`** — 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/<binary>/`** — 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/<feature>/`, 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 `<tools>` 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
`<tools>`/`<env>` 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 `<worktree>/.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.
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:46cd31e7 -->
## 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 <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # 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/<area>/`: Domain logic, entities, state machines, commands,
events, and required contracts (interfaces). Never imports infrastructure or
app.
- `internal/infrastructure/<service>/`: Implementations of domain contracts
(persistence, forge clients, external transports, config loading).
- `internal/app/<application>/`: Dependency injection, wiring domain to
infrastructure, lifecycle management, and shutdown ordering.
- `cmd/<binary>/`: 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/<feature>/` 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 `<tools>` 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
`<worktree>/.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 <id> # View issue details
bd update <id> --claim # Claim an issue
bd close <id> # 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 <id>`.
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 <files the change touches>
git commit -m "..."
git status
# Push/sync only when explicitly asked:
git pull --rebase
bd dolt push
git push
git status
git add <scoped-files>
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.
<!-- END BEADS INTEGRATION -->
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.