Files
archie/CLAUDE.md
T

414 lines
22 KiB
Markdown

# AGENTS.md
Guidance for any coding agent working in this repository.
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) 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.
Architecture of record lives in `docs/architecture/` -- `organisation.md` for
the package map, `agent-system.md` for the workflow-execution lifecycle and its
invariants, `plugins-and-extensions.md` for engine families. 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. Before adding a new
plugin engine, satisfy
`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`.
Before changing an area (frontend UI, agent, workflows, daemon, State Store,
control plane), read its page in `docs/development/`: it names every layer the
change must reach. This is not optional colour reading -- archie-core is built
as an extensible, customisable surface, not a fixed product, so a change that
looks complete inside one package routinely is not: a new setting that never
reaches the control-plane schema descriptor and dashboard parses but never
renders, is never editable, and never live-applies, exactly like a config
field with no consumer. The dev-docs page for the area is where that
cross-layer reach is written down; read it before starting, not after
something downstream turns out silently unwired. This applies whether the
work is yours directly or handed to a subagent or crew worker -- carry the
relevant docs/development page into their prompt, the same way a bead ID is
carried; "figure out what else needs updating" left implicit is exactly the
gap this note exists to close.
## Scope Discipline
`docs/architecture/` is authoritative for settled design.
`docs/architecture/migration-decisions.md` is the open decision register for the
domain migration.
- **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.
- **Verify handed-over input before acting on it.** An export, transcript, or
artifact that is empty, missing, or truncated is a blocking fact: report it
before starting work that assumes its contents. Never reconstruct the intent
from the working tree instead.
- **PRD writing:** Read and follow `docs/prds/RULES.md` before creating or
editing a PRD.
## Deployment Model
- **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.
## Release Process
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` (requires Go 1.27.0,
[Task](https://taskfile.dev), `gofumpt`, `golangci-lint`, Node/npm, and a
running Docker daemon: Postgres tests start `postgres:18` through
testcontainers via `internal/infrastructure/postgres/pgtest`).
`golangci-lint` is the single writer for ordinary Go formatting; standalone
`gofumpt` formats generated protobuf contracts only.
```bash
task build # build archied and archie-agent binaries into bin/
task test # go test -short ./... (cached; task test:full runs everything uncached)
task test:ui # dashboard node tests (DOM-building primitives)
task ui # build dashboard into ui/dist (LAW asset)
task fmt # go fix ./... && golangci-lint fmt
task vet # go vet ./...
task lint # golangci-lint run ./...
task check # fmt + proto:lint + proto:check + docs:check + vet + lint + build + test + test:tools + test:ui (The Definitive Gate)
task dev # archied live-reload + Vite HMR together on :5173
```
Single package/test runs:
```bash
go test ./internal/domain/workflow/... -run TestName -v -count=1
```
## Repository Hygiene
- **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) without asking. Push only when instructed.
## Organisation (Strict Domain-Driven Architecture)
`docs/architecture/organisation.md` is authoritative. Do not follow flat
structures found in legacy packages.
### Layers and Ownership
- `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.
### Invariants
- **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
- **Config fields (cross-cutting): a field that parses is not a field that works.**
A knob added to a struct the extensible surface reuses _parses_ everywhere
without taking effect anywhere, and a knob read from the wrong layer is just
as invisible: a file key is only a seed once a stored resource outranks it.
Before adding or reusing a config field, name its consumer, and reject the
configuration when there is none - which is what this repo now does for
per-identity `forge.intake`. Two documents carry the detail:
`.agents/skills/archie-config-and-flags` holds the wiring matrix, the
decoded-but-unwired ledger and the three shapes an unwired field can take;
`docs/architecture/configuration.md` is the authority on the config model and
its reloadability criterion.
- **`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.
- **`internal/infrastructure/staterpc/` (State Store gRPC contract):**
Authority is `docs/prds/state-store-contract.md` (rev. 2e) -- read it before
changing this package or its callers.
- The proto (`proto/state/v1/state.proto`, service `StateStoreService`,
package `statev1` in `internal/contracts/state/v1/`) is one gRPC service
fronting every ratified store contract, including grant management; the Go
consumer facades
stay narrow (`workflow.Store`, `store.TaskStore`, etc., all ≤8 methods
except the `TaskStore` composite) via `staterpc.Client`'s multiple `var _`
assertions -- never add a Go interface method without a matching RPC.
- Error sentinels (`store.ErrStaleTransition`, `ErrBindingNotFound`, ...)
cross the wire via `mapError`/`unmapError` in `values.go`, matched on
`(code, exact canonical message)`. Changing a canonical message string
breaks `errors.Is` on the client without changing behaviour visibly --
treat those message constants as part of the wire contract.
- The State Store is a standalone process (`cmd/archie-state-store`, run via
`archied.RunStateStore`) -- the daemon and Gateway never own the task
tables or serve this service in-process; `boot.openStateStore` in
`internal/app/archied/state_store.go` is the only place the task store
is built. Never add a second listener for the same
service, and never reintroduce an in-process serving path in the
daemon/Gateway (`TestOpenStoresNeverOwnsTaskDB` guards this).
- Per-task credentials are scoped, not just authenticated: `daemon.
StateStoreGrantIssuer` (`staterpc.GrantIssuer`) registers a fresh
task-scoped grant at the remote State Store via `RegisterTaskGrant` before
`ContainerPool.Acquire` and revokes it via `RevokeTaskGrant` on `Release`
(`acquireTaskContainer`/`process` in `internal/daemon/daemon.go`). Fails
closed (parks the task) if a State Store is configured but no issuer is
wired -- it must never fall back to forwarding the daemon's own
administrative token. Server-side, `staterpc.TaskGrants.UnaryInterceptor`
authorises a task-scoped token for only `Update`/`Transition`/`InsertEvent`
on its own task ID; every other RPC (including `RegisterTaskGrant`/
`RevokeTaskGrant` themselves and the streaming capture RPCs) requires the
administrative token.
- `archie-agent` has exactly one `workflow.Store` path: gRPC via
`staterpc.Client` (`agenttransport/nats.Transport.Store`), using the
`STATE_STORE_URL`/`STATE_STORE_TOKEN` env the daemon injects. The legacy
NATS `storerpc` transport is deleted (`internal/storerpc` no longer
exists); do not reintroduce a dual-path selection.
- `store.BindingDispatcher.RecordDispatch` takes no `*sql.Tx` (dropped in
`.4.2` -- it cannot cross a gRPC boundary; production always passed `nil`).
Do not reintroduce a transaction parameter on a producer-owned store
interface that a remote adapter must also implement.
- **`internal/forge/webhook/` (forge webhook receiver):**
- Verify HMAC (`webhookguard.VerifyHMAC` against `X-Hub-Signature-256`) before
parsing the payload, never after -- an unverified body must not reach
`github.ParseWebHook`.
- Do not give the webhook-built `workintake.TaskEnvelope` a delivery-source-
specific idempotency key. `IdempotencyKey()` is keyed on `owner/repo/number`
only so a webhook-delivered issue and a later poll of the same issue dedup
against each other via `PublishUnique`; adding an event ID or timestamp to
the key defeats that and reintroduces poll/webhook double-dispatch.
- Webhook intake refuses to start when `[[identities]]` is configured (one
receiver, one dispatch config). Do not silently enable it for multi-identity
deployments without first building per-identity routing -- see
`docs/architecture/messaging-and-work-intake.md`'s "Intake provenance"
section.
- **`internal/domain/embedding/` + `internal/infrastructure/embedding/`:**
Embedding client contract + implementation. Config-driven exactly like chat
model roles: `models.embedding = "provider/model"` plus a `[providers.*]`
entry. `infrastructure/embedding.New` degrades to `(nil, false)` -- never an
error -- for a missing role, unknown provider, unsupported class, or
unresolved credential; wired as an optional capability in
`bootstrap.go`'s `setupEmbeddings`. Only provider classes matching
`config.Provider`'s shape are supported (openai, gemini, ollama, cohere,
mistral) -- azure needs a `Deployment` field this config type doesn't have.
- **`internal/domain/sampling/`:** The curator `Sampler` interface (see
`docs/prds/curator-sampler-wave1.md`) plus four pure, deterministic
strategies (recency, staleness, random, all). No curator consumes a
`Sampler` yet -- `curator.Registrar` is untouched by this package.
## Development Protocol
1. **Red (Failing Test):** For behaviour with real logic, branching, or a
contract, write failing table-driven tests first against target behaviour.
Verify the failure originates from test assertions, not compilation errors.
Do not write tests that restate an assignment or a constant: a test that
cannot fail for an interesting reason is noise in the gate.
- **A test is a maintenance liability, not free insurance.** Every test
added is code the project now carries forever: it must compile, it must
keep passing as the code around it changes, and someone reads it during
every future change to that area. Write one because a real regression
would slip through without it, not because the function was touched.
- **Never pin a literal end-user config value, database row, or settings
document as the thing under test.** Test the validation rule, the
migration's shape, or the round-trip contract -- not one operator's
specific `config.toml` value, a hand-picked DB fixture that mirrors real
data, or a setting's current default. Those change for reasons that have
nothing to do with a regression, and a test pinned to one breaks on
every such change, which is cost with no signal.
- **Test-only helpers, fakes and fixtures live in `_test.go` files (or a
package no production `.go` file imports), never in a file the binary
ships.** `go build` does not compile `_test.go` files into the binary,
but an exported "test helper" living in a regular source file compiles
into every binary that imports the package, whether or not a test ever
runs. If a helper must be shared across packages, put it behind a
build-tagged or `_test.go`-suffixed file in an `xtest`-style package,
not behind a normal export.
- **Coverage is not the goal.** A codebase that grows mostly because tests
multiplied faster than the feature they cover is a symptom, not
progress -- prefer fewer, sharper tests over one per line changed.
2. **Green (Implementation):** Implement minimal code to satisfy the failing
tests.
3. **Quality Gate:** Run `task check`.
- **The gate gates the commit.** Let the gate's exit status decide whether
the commit runs, as one conditional chain (`check && commit && push`).
Writing them as separate statements on one command line makes the gate
decorative: nothing reads its status but the operator, and a failure is
discovered after it has already been pushed.
- **Never assert a gate result you have not just produced on that exact
tree.** A commit message outlives the tree it describes, and "verified"
is read by people who were not there. If the tree moved, describe the
change and let the run speak.
4. **Formatting is LAW:** Adopt all formatting and simplification changes from
`task fmt` (`go fix` + the configured golangci-lint formatters) verbatim.
Never revert or fight canonical linter/formatter diffs.
5. **No standing adversarial-review pass (for contributors):** Do not spawn a
separate fresh-context reviewer pass on every change as a matter of course.
Red-green TDD plus `task check` is the gate; a manual adversarial pass is
opt-in per request — ask before running one. This is the rule for a human or
agent _contributor_. Separately, archied runs the same adversarial review
automatically on the PRs it opens (gated per repo by `repo.review_enabled`)
— see `docs/architecture/adversarial-review.md`. The two paths are distinct:
you run one when asked; archied runs one before it opens a PR.
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, synced to its own `git+` remote via
`bd dolt push`/`bd dolt pull`. `.beads/issues.jsonl` and
`.beads/interactions.jsonl` are local-only export/audit files
(`.gitignore`d, `export.auto: false`) -- never `git add` them and never
create a commit whose only content is beads bookkeeping. Bead state moves
through Dolt, not through git commits on this repo.
- **A bead never carries production instance detail.** No operator host name,
hostname, IP or port, filesystem path, PID, or credential -- in the body
_or_ the title, since both sync to the Dolt remote and are therefore
published. Write the mechanism and the evidence shape instead ("a production
host", "the State Store target", "the host's `config.toml`"), and put the
host-specific facts in the operator's memos instance, which the bead may
point at. This is the same class of rule as never committing a credential:
the tracker is not a private store.
## 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>`. This alone
is not commit-worthy -- do not stage or commit `.beads/` for it.
4. **Commit:** Only for actual code/doc changes, scoped to the files that
changed.
```bash
git add <scoped-files>
git commit -m "feat(scope): description"
```
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.
## Maintaining this file
Keep this file for knowledge useful to almost every future agent session in this project.
Do not repeat what the codebase already shows; point to the authoritative file or command instead.
Prefer rewriting or pruning existing entries over appending new ones.
When updating this file, preserve this bar for all agents and keep entries concise.