docs: correct CLAUDE.md and ARCHITECTURE.md against the current tree
Both documents had drifted far enough to mislead a new session on its first read. CLAUDE.md is symlinked as AGENTS.md, so its rules now name required behaviour rather than one harness's command for it. Corrections verified against the tree: - internal/workflow moved to internal/domain/workflow; the single-test example pointed at a package that no longer exists - there is no internal/nats package; the eventbus transport is internal/infrastructure/eventbus - task check also runs test:ui, so the gate needs Node, and task fmt rewrites files rather than only verifying - Gitea is implemented, not planned - the nats.url passthrough is containerEnv, not a line number that moved - ARCHITECTURE.md claimed every park comments on the forge issue; the code records park_reason on the task and requeue clears it - the opening sentence described a single-forge, label-only daemon Deployment no longer presents systemd as the model: deployments/ carries five profiles and systemd is one runbook among them. The chat agent's file tools are workspace-confined by default and unrestricted_filesystem is an operator opt-in, which had been written as an architectural constraint. Host-specific operator details are removed, along with a pointer to a memory that never existed. Adds what every session needs and nothing recorded: toolchain prerequisites, Conventional Commits, and that ui/dist is committed so the Go build never requires a Node toolchain. Folds in seven traps recovered from the pre-migration tracker: the three NATS behaviours, Telegram scope-specificity menus, the ai-sdk FullStream deadlock, the chat prompt's tools-block invariant, the two lint-autofix regression shapes, and commit-the-meaning.
This commit is contained in:
1 parent
fd4420a038
commit
95f6a3fae7
2 files changed
+252
-66
No files matched your search
+39
-21
@@ -1,27 +1,38 @@
|
||||
# archie-core Architecture
|
||||
|
||||
**archied** is a resident daemon that polls GitHub for issues labelled `archie`,
|
||||
works each one in an isolated worktree through a routed workflow, and opens pull
|
||||
requests for human review.
|
||||
**archied** is a resident daemon that polls its configured forges — GitHub and
|
||||
Gitea — for issues assigned to its bot user, carrying its label, or either
|
||||
(`dispatch` mode, per identity), works each one in an isolated worktree through
|
||||
a routed workflow, and opens pull requests for human review. A single daemon can
|
||||
serve several identities across several forges, each with its own `bot_user`,
|
||||
label, and repository set.
|
||||
|
||||
## Package Map
|
||||
|
||||
| Package | Role |
|
||||
| --------------------- | ------------------------------------------------------------------------- |
|
||||
| `cmd/archied/` | Binary entry: config→forge→store→runtime→workflows→daemon |
|
||||
| `cmd/archie-agent/` | One-invocation autonomous stage worker (JSON stdin/stdout) |
|
||||
| `internal/config/` | TOML config, per-repo gates, budgets, providers, ecosystems |
|
||||
| `internal/daemon/` | Resident loop: poll, enqueue, claim, route, process, reconcile |
|
||||
| `internal/workflow/` | Engine: stage lists, routing, shared steps, workflow definitions |
|
||||
| `internal/agentexec/` | Versioned agent-stage protocol, worker, and in-process/subprocess runners |
|
||||
| `internal/forge/` | GitHub interface: issues, labels, PRs, comments, reactions |
|
||||
| `internal/worktree/` | Git operations: clone, branch, commit, push, diff, cleanup |
|
||||
| `internal/store/` | SQLite: task rows, status transitions, crash recovery |
|
||||
| `internal/events/` | In-process event bus: publish/subscribe for observability |
|
||||
| `internal/webui/` | SSE dashboard: live event stream, task status |
|
||||
| `ai-sdk/runtime` | External: provider-agnostic LLM runtime |
|
||||
| `ai-sdk/agentloop` | External: gated agent loop with budgets and tool jails |
|
||||
| `ai-sdk/core` | External: tool definitions, generate options |
|
||||
This lists the load-bearing packages, not all of them — `internal/` holds ~36.
|
||||
The domain migration is in progress (`internal/domain/`,
|
||||
`internal/infrastructure/`), so **the tree is authoritative over this table**.
|
||||
See `docs/architecture/organisation.md` for the target structure and
|
||||
`docs/architecture/migration-decisions.md` for the current position.
|
||||
|
||||
| Package | Role |
|
||||
| ---------------------------- | ------------------------------------------------------------------------- |
|
||||
| `cmd/archied/` | Binary entry: config→forge→store→runtime→workflows→daemon |
|
||||
| `cmd/archie-agent/` | One-invocation autonomous stage worker (JSON stdin/stdout) |
|
||||
| `internal/config/` | Config types only — loading lives in `infrastructure/configuration` |
|
||||
| `internal/daemon/` | Resident loop: poll, enqueue, claim, route, process, reconcile |
|
||||
| `internal/domain/workflow/` | Engine: stage lists, routing, shared steps, workflow definitions |
|
||||
| `internal/domain/workintake/`| `TaskEnvelope`, routing `Kind`, label vocabulary, task subjects |
|
||||
| `internal/agentexec/` | Versioned agent-stage protocol, worker, and in-process/subprocess runners |
|
||||
| `internal/forge/` | Forge interface: GitHub and Gitea implementations |
|
||||
| `internal/worktree/` | Git operations: clone, branch, commit, push, diff, cleanup |
|
||||
| `internal/store/` | Task store interface; SQLite, RPC client, and nell adapters satisfy it |
|
||||
| `internal/events/` | In-process event bus: publish/subscribe for observability |
|
||||
| `internal/infrastructure/` | Config loading, eventbus transport, model catalog |
|
||||
| `internal/webui/` | SSE dashboard: live event stream, task status |
|
||||
| `ai-sdk/runtime` | External: provider-agnostic LLM runtime |
|
||||
| `ai-sdk/agentloop` | External: gated agent loop with budgets and tool jails |
|
||||
| `ai-sdk/core` | External: tool definitions, generate options |
|
||||
|
||||
## Task Lifecycle
|
||||
|
||||
@@ -34,7 +45,10 @@ queued → running(workflow:stage) → pr_open → merged | rejected
|
||||
```
|
||||
|
||||
**Crash recovery:** tasks left in `running` are re-queued on startup. Parks are
|
||||
never silent -- every park posts a comment with the reason and gate output.
|
||||
never silent, but they no longer comment on the forge issue: the reason is
|
||||
recorded on the task as `park_reason` (cleared on requeue) and surfaced by the
|
||||
dashboard and `/api/tasks`. Retries are an explicit operator action capped by
|
||||
`max_retries`, not a label a human removes.
|
||||
|
||||
**PR reconciliation:** the daemon polls open PRs, checks GitHub state
|
||||
(`merged`/`closed`), transitions the task, and cleans up worktrees.
|
||||
@@ -130,7 +144,11 @@ prepare → assess(planner, with decide tool) → [close_if_bad_fit | prd(planne
|
||||
|
||||
## Forge Interface
|
||||
|
||||
A thin abstraction over GitHub (Gitea planned):
|
||||
A thin abstraction over the forge. GitHub (`github.go`) and Gitea (`gitea.go`)
|
||||
both implement it, plus a no-op (`noop.go`) used when no credential resolves —
|
||||
see the degradation rule in `docs/architecture/configuration.md`. A multi-forge
|
||||
deployment is configured per identity; see
|
||||
`deployments/multi-forge-github-gitea.toml`.
|
||||
|
||||
| Method | Purpose |
|
||||
| ------------------- | --------------------------------------- |
|
||||
|
||||
@@ -1,7 +1,13 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with
|
||||
code in this repository.
|
||||
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.
|
||||
|
||||
## What this is
|
||||
|
||||
@@ -30,41 +36,51 @@ authoritative**. It is a design to implement against — not a draft to extend.
|
||||
that works over the most defensible one.
|
||||
- Default to producing a diff. If a task's output would be a document rather
|
||||
than code, confirm that's actually wanted before starting.
|
||||
- Issues are tracked in GitHub Issues, grouped issues can be linked under an epic,
|
||||
with subtasks linked to the epic.
|
||||
|
||||
## Deployment model
|
||||
|
||||
**archied runs on the host under systemd.** Its chat tools operate on host files
|
||||
(shell, read, write, edit, find, grep), which a container cannot reach. NATS and
|
||||
per-task archie-agent containers stay in Docker.
|
||||
**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.
|
||||
|
||||
```bash
|
||||
# On the deployment host (carina):
|
||||
systemctl --user status archied # daemon
|
||||
journalctl --user -u archied -f # logs
|
||||
docker compose -f ~/projects/archie-core/docker-compose.yml up -d
|
||||
docker compose pull agent # refresh agent image after CI pushes
|
||||
```
|
||||
**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. NATS and the per-task
|
||||
archie-agent containers are Docker regardless.
|
||||
|
||||
**The daemon hands agent containers its own `nats.url` verbatim**
|
||||
(`internal/daemon/daemon.go:1177`), so that URL must reachable from both the
|
||||
host _and_ from inside containers. Use the compose network's gateway address
|
||||
(`172.19.0.1:4222`), not the service name or localhost. The subnet is pinned in
|
||||
`docker-compose.yml` so this address cannot drift.
|
||||
**The daemon hands agent containers its own `nats.url` verbatim** — see
|
||||
`containerEnv` in `internal/daemon/daemon.go`, which appends `NATS_URL=` from
|
||||
`d.Cfg.NATS.URL`. That URL must therefore be reachable from wherever the daemon
|
||||
runs *and* from inside the containers. When the daemon is on the host, that
|
||||
means the compose network's gateway address, not the service name and not
|
||||
localhost. `docker-compose.yml` pins the subnet to `172.19.0.0/16` so the
|
||||
gateway address cannot drift when the network is recreated.
|
||||
|
||||
**`containers.pull_policy` can only be `"missing"`** (the default) or
|
||||
`"always"`. `"always"` against the private Gitea registry answers 401 because
|
||||
the daemon sends no credentials to the Docker API. Refresh the agent image by
|
||||
hand: `docker compose pull agent`.
|
||||
`"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`** carries only NATS and the agent build stanza. The agent
|
||||
has a build profile so `up -d` skips it — 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` still work by
|
||||
name without activating the profile.
|
||||
has a `build` profile so `up -d` skips it — 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` still
|
||||
work by name without activating the profile.
|
||||
|
||||
**Config lives at `~/.config/archie/config.toml`**, outside the repo. Nothing in
|
||||
the repo working tree is load-bearing at runtime. The reference template is
|
||||
`deployments/docker-nats-stack.toml`.
|
||||
**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
|
||||
|
||||
@@ -95,20 +111,52 @@ No tags at HEAD prints a warning (images get stamped `dev`).
|
||||
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
|
||||
|
||||
```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 fmt # gofumpt -w . && go fix ./...
|
||||
task vet # go vet ./...
|
||||
task lint # golangci-lint run ./...
|
||||
task check # fmt + go fix + vet + build + test — matches the per-repo [[repos.gate]] archied runs on itself
|
||||
task check # fmt + go fix + vet + build + test + test:ui
|
||||
task dev # archied live-reload + Vite HMR together, on :5173
|
||||
```
|
||||
|
||||
Run a single test: `go test ./internal/workflow/... -run TestName -v`.
|
||||
`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/NATS stack: `task docker-build` (builds the agent image locally),
|
||||
`task docker-up`, `task docker-down`, `task docker-logs`.
|
||||
|
||||
## 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): ...`.
|
||||
- Only commit or push when asked.
|
||||
|
||||
## Organisation (strict)
|
||||
|
||||
`docs/architecture/organisation.md` is authoritative and approved. This section
|
||||
@@ -225,11 +273,16 @@ 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`, `internal/nats`) alongside the
|
||||
in-process model described in ARCHITECTURE.md — check `internal/nats/` and
|
||||
`docker-compose.yml` for the current split between `archied` and sandboxed
|
||||
workers.
|
||||
`internal/worktreerpc`, `internal/natsrpc`) alongside the in-process model
|
||||
described in ARCHITECTURE.md. 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
|
||||
@@ -251,6 +304,63 @@ boundaries. Summary of what's evolved since that doc was last fully accurate:
|
||||
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, as `cmd/archie-agent` and the agentexec round-trip fake do.
|
||||
(2) *Reply inboxes are not stream subjects.* Answering a request must use core
|
||||
NATS publish, not the JetStream path: a `Message.ReplyAddress` is an ephemeral
|
||||
`_INBOX.*` belonging to one waiting caller and part of no stream, so a durable
|
||||
publish to it fails. That is why `eventbus.Publisher` declares `Respond` as a
|
||||
method distinct from `Publish` rather than a convenience over it.
|
||||
(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
|
||||
@@ -281,16 +391,35 @@ 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. Two live instances run on a separate host (`carina`), each with a
|
||||
distinct `bot_user` — see the `two-archied-instances-run-on-host-carina-ssh`
|
||||
beads memory (`bd memories carina`) if working on multi-identity/dispatch
|
||||
behavior.
|
||||
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`.
|
||||
@@ -343,23 +472,62 @@ clean.
|
||||
fresh reviewer — never self-certified by the implementer.** After red-then-green
|
||||
is green:
|
||||
|
||||
- Spawn a review with no memory of how the code was written (a fresh subagent,
|
||||
or `/code-review`/`/security-review` as appropriate) and instruct it to assume
|
||||
every line is wrong until proven correct.
|
||||
- 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 (use `ReportFindings` when running as a review agent),
|
||||
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.
|
||||
- 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`) for issue
|
||||
tracking. Epics are parent issues; their work items are linked as native
|
||||
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.
|
||||
Reference in new issue
Block a user