chore: cleanup

This commit is contained in:
sam committed 2026-07-29 02:10:44 +10:00
1 parent 65aa5b462d
commit d1bbd37d95
56 files changed
+8781 -78

No files matched your search

@@ -0,0 +1,362 @@
---
name: archie-architecture-contract
description: >-
Protect Archie's load-bearing architecture while placing, implementing, or
reviewing behavior. Load this skill before changing daemon composition,
domains, workflows, task lifecycle, agent execution, messaging, work intake,
identity, memory, configuration, plugins, policies, persistence, NATS/RPC,
containers, or process boundaries; use it when deciding where new code
belongs, enforcing dependency direction, separating current runtime truth
from the approved target and open migration decisions, or ensuring every
behavior has one authoritative path. Route proof of duplication, dead-code
disposition, production reachability, and maintainability to
archie-technical-accountability.
---
# Archie Architecture Contract
Treat architecture as executable safety policy. Preserve one understandable
owner and one production path for each behavior.
## Read status before code
Use these labels exactly:
| Label | Meaning | Authority |
| --- | --- | --- |
| **CURRENT** | Behavior present in live code and production composition as of 2026-07-28. | Code, tests, and `cmd/archied/main.go` wiring |
| **APPROVED TARGET** | Direction an implementation must approach, but which may not exist on disk. | `docs/prds/01-project-management.md` and documents whose status says approved |
| **OPEN** | A migration or API decision no implementer may invent locally. | `docs/prds/architecture/migration-decisions.md` and documents marked in progress or under design |
> **Do not implement target prose as though it describes current code.**
> Before treating a target package as available, prove that it exists and is
> used from a production entry point. If the task will create that package,
> classify it as a migration slice and obtain the focused package decision
> first. `internal/domain/` does not exist in the CURRENT tree as of 2026-07-28.
Resolve apparent disagreement in this order:
1. Read live code and production composition for CURRENT behavior.
2. Read `docs/prds/01-project-management.md` for APPROVED TARGET ownership.
3. Read the focused decision document for the selected behavior.
4. Read `docs/prds/architecture/migration-decisions.md` for OPEN work.
5. Stop and use `archie-architecture-planning-campaign` if a required semantic
decision remains open.
## Route the task
Use this skill to enforce boundaries and place behavior.
Do **not** use it as:
- a design interview or migration campaign; use
`archie-architecture-planning-campaign`;
- a project vocabulary glossary; use `archie-domain-reference`;
- NellDB mechanics, persistence behavior, or adapter guidance; use
`archie-nelldb`;
- a complete configuration field/default reference; use
`archie-config-and-flags`;
- proof that code is production-reachable, non-duplicated, or maintainable; use
`archie-technical-accountability`;
- a test, review, or release checklist; use `archie-change-control`.
Load the sibling skill as well when the task crosses one of those boundaries.
## Know the CURRENT system
Do not simplify these facts into the target model:
| Concern | CURRENT runtime truth on 2026-07-28 | Evidence |
| --- | --- | --- |
| Composition | `cmd/archied/main.go` performs substantial construction and wiring. Packages are organized mostly by technical mechanism. | `cmd/archied/main.go`; current `internal/*` tree |
| Durable work | `store.Task` combines forge/chat source data, workflow position, output, retry, identity, and PR state. | `internal/store/store.go` |
| Workflow | `internal/workflow` routes a `store.Task` into a `map[string]Workflow`, then mutates a broad `TaskContext` through sequential stages. | `internal/workflow/workflow.go` |
| Agent-stage boundary | A versioned `agentexec.Request`/`Result` carries one autonomous stage; validation correlates task, attempt, and stage. | `internal/agentexec/protocol.go` |
| Container handoff | `internal/taskrun` also carries an entire task plus `config.Repo` and `config.TaskConfig`; `archie-agent` runs routing and sequencing for this path. | `internal/taskrun/taskrun.go`; `cmd/archie-agent/main.go` |
| Git ownership | Daemon-owned worktree operations clone, commit, push, diff, and clean up. The model receives no git ownership. | `internal/worktree/`; `internal/workflow/steps.go`; `ARCHITECTURE.md` |
| Enforcement | Gates, read-only/protected paths, TDD inverted test gates, and diff caps are represented outside prompt prose. | `internal/agentexec/inprocess.go`; `internal/workflow/{agent,tdd,steps}.go` |
| Configuration | `internal/config.Config`, `IdentityConfig`, `Repo`, and task snapshots mix input decoding with runtime concerns. | `internal/config/config.go` |
| Identity | Configured names and bot usernames act as process-local identity keys. `daemon.IdentityRunner` groups per-name clients/config; there is no durable Identity domain. | `internal/daemon/daemon.go`; `internal/store/store.go`; `internal/gateway/session.go` |
| Messaging | `internal/gateway` contains both legacy `Message` flow and a richer `MessageEvent`; channel routing and chat task control are mixed with conversational behavior. | `internal/gateway/{gateway,messageevent,tasks}.go`; `internal/channels/` |
| Plugins | `plugin.Plugin` exposes only `Name` and `Version`; current loading interprets operator-installed Go files with Yaegi. | `internal/plugin/plugin.go` |
| Processes | Agent modes include in-process, subprocess, and NATS. Optional containers add a distinct boundary with known gaps; a subprocess alone is not a security sandbox. | `internal/config/config.go`; `cmd/archied/main.go`; `ARCHITECTURE.md` |
### Interpret the current lifecycle honestly
Use these CURRENT status values:
```text
queued, running, waiting_human, pr_open, merged,
parked, dead, rejected, closed_wont_do
```
The intended flow includes queue/claim, workflow stages, human wait/resume, PR
reconciliation, parking/retry/exhaustion, and crash recovery. Read
`internal/store/store.go`, `internal/daemon/daemon.go`, and
`internal/workflow/workflow.go` before changing a transition.
Do not call this an enforced state machine. CURRENT
`Store.Transition(ctx, taskID, from, to, detail)`:
- does not include `from` in the update predicate;
- updates task state and inserts transition history in separate statements;
- can therefore accept an illegal/stale transition or leave state and history
inconsistent;
- is called from paths that sometimes discard its error.
Treat atomic state plus event/history persistence as an OPEN migration design,
not a small local patch.
## Preserve the load-bearing invariants
| Invariant | Required action | Status and source |
| --- | --- | --- |
| The model never runs git | Keep clone, branch, commit, push, diff, and cleanup in deterministic workspace/worktree steps. Never expose git as an agent tool. | CURRENT: `ARCHITECTURE.md`; `internal/worktree/` |
| Deterministic constraints outrank prompts | Enforce gates, protected paths, read-only stages, test protection, and change caps outside model instructions. Do not replace enforcement with “must not” prose. | CURRENT: `ARCHITECTURE.md`; `internal/agentexec/inprocess.go`; `internal/workflow/` |
| Agent execution is a data boundary | Send bounded, versioned input; validate correlated output before applying it. Keep persistence, forge credentials, git authority, workflow outcomes, and policy enforcement outside the autonomous model. | CURRENT foundation: `internal/agentexec/protocol.go`; `ARCHITECTURE.md` |
| Every workflow ends explicitly | Preserve terminal outcome or visible park behavior. Preserve crash recovery of interrupted `running` work. | CURRENT: `internal/workflow/workflow.go`; `internal/store/store.go` |
| Generic plugins stay metadata-only | Keep `plugin.Plugin` at `Name()` and `Version()`. Put behavior on a typed capability interface with an owning `Registry` or `Manager`. | CURRENT-enforced rule: `internal/plugin/architecture_test.go`; `ARCHITECTURE.md#plugin-engine-rule-strict` |
| Capability engines own lifecycle | Give resource-owning engines explicit start/health/stop semantics and failure isolation. Supply narrow registrars/services, never `*daemon.Daemon` or a service locator. | APPROVED rule: `ARCHITECTURE.md#plugin-engine-rule-strict`; reviewers enforce non-mechanical parts |
| Trust is explicit | Treat trusted operator-installed in-process code, repository code, out-of-process integrations, and container-isolated code as different trust classes. Never call Yaegi or subprocess execution a sandbox. | APPROVED rule: `ARCHITECTURE.md#plugin-engine-rule-strict` |
| Infrastructure stays replaceable | Keep forge, persistence, workspace, transport, container, and model details behind behavior-owned contracts. Do not leak broker messages, DB rows, SDK types, or config DTOs into domain models. | APPROVED TARGET: `docs/prds/architecture/dependencies-and-contracts.md` |
| Same-repository execution serializes by default | Preserve the default unless an explicit scheduling policy permits concurrency. | CURRENT: `internal/config/config.go`; `internal/daemon/daemon.go` |
Run the mechanical plugin guard after changing any plugin or `*Engine`
interface:
```bash
go test ./internal/plugin -count=1
```
Passing it does **not** prove lifecycle, host-access, shutdown, or trust
semantics. Review those manually through `archie-change-control`.
## Apply the APPROVED TARGET
Apply these ownership rules to migration plans and new seams. Do not claim they
are CURRENT until production wiring proves the cutover.
### Keep dependency direction inward
Use this target direction:
```text
domain and shared application contracts <- infrastructure implementations
^
|
application composition
```
Enforce:
1. Put cohesive behavior, vocabulary, state, commands, events, policies,
runtime settings, and required service interfaces with its owning domain.
2. Make infrastructure implement domain-required interfaces and translate
external representations.
3. Let only `internal/app` choose concrete implementations and connect domains.
4. Keep `cmd/*` limited to process input and invoking composition.
5. Use an owned command, event, or approved shared contract across domains.
6. Never let one domain mutate another domain's state or call its internals.
7. Reject generic `entities`, `services`, `repositories`, `messages`, or
`utils` layers that merely group mechanisms.
Sources: `docs/prds/architecture/organisation.md` and
`docs/prds/architecture/dependencies-and-contracts.md`.
### Keep source ownership independent of deployment
Begin with a modular monolith even when capabilities run in separate processes.
Introduce or retain a process/service boundary only for demonstrated:
- security isolation;
- independent scaling;
- failure containment; or
- independent operation.
Do not add a network protocol or duplicate service scaffolding for possible
future extraction. A transport is an infrastructure implementation of a
behavior-owned contract, not the owner of the behavior.
Source: `docs/prds/architecture/organisation.md`.
### Separate interaction, admission, assistance, and execution
Use this target handoff:
```text
channel-neutral Message
-> selected Agent turn or deterministic automation
-> optional proposed work
-> Work Intake validates and emits AcceptedWorkRequest
-> Workflow domain selects a Workflow version
-> Workflow domain creates WorkflowExecution
```
Keep the concepts separate:
- **Messaging** owns canonical messages, conversations, branches, channel/source
correlation, delivery attempts, and messaging projections.
- **Agent** owns a persistent assistant, model-independent continuity,
specialization, capability context, and memory associations.
- **Work Intake** owns admission, validation, deterministic routing, and the
accepted-work-request handoff.
- **Workflow** owns reusable versioned definitions, steps, durable executions,
attempts, outcomes, and typed Workflow plugin contracts.
Do not equate an external issue/message with a WorkflowExecution. Do not let
Work Intake create one directly. Do not require ordinary conversation or direct
tool use to become durable workflow-backed work.
Sources: `docs/prds/architecture/migration-decisions.md`,
`docs/prds/architecture/agent-system.md`, and
`docs/prds/architecture/messaging-and-work-intake.md`.
### Separate identity, Agent, conversation, and memory
Use immutable `IdentityID` for target attribution; never use display names,
forge usernames, bot names, or the empty string as canonical identity. Keep
Identity separate from Agent: Identity names the actor; Agent owns assistant
behavior and continuity.
Preserve the four fixed target memory scopes:
| Scope | Visibility |
| --- | --- |
| Global shared | Intentionally shared across Archie |
| Agent-wide | One Agent across its users; private to that Agent by default |
| User-wide | One user across authorized Agents |
| Agent-user relationship | Exactly one Agent and one user |
Resolve Agent and initiating user before loading memory. Do not use conversation
branching as a fifth memory scope.
Sources: `docs/prds/architecture/identity.md`,
`docs/prds/architecture/agent-system.md`, and
`docs/prds/architecture/migration-decisions.md`.
### Dissolve global runtime configuration
Treat the current `internal/config` package as a migration source inventory, not
a target domain:
- move file/env/overlay/secret decoding to
`internal/infrastructure/configuration`;
- let each domain or plugin own typed runtime settings for its behavior;
- translate external DTOs to those settings in `internal/app`;
- never pass complete application config into a domain;
- never move `config.Repo` or `IdentityConfig` intact to a renamed shared
package;
- classify every behavioral value as invariant, runtime setting, policy value,
derived value, or runtime state.
Do not add another unrelated concern to the global config model without an
explicit compatibility plan and deletion criterion. Use
`archie-config-and-flags` for the field ledger.
Source: `docs/prds/architecture/configuration.md`.
## Place new behavior deliberately
Use this decision table. “Target” entries require a reviewed migration slice
when the target package is not yet live.
| Behavior | Target owner/location | Decision gate |
| --- | --- | --- |
| Persistent actor lifecycle and attribution | `internal/domain/identity` | Do not mix authentication/access policy into Identity. |
| Persistent assistant behavior and continuity | `internal/domain/agent` | Keep model/provider replaceable; do not fold Workflow into Agent. |
| Workflow definitions, steps, executions, attempts, outcomes | `internal/domain/workflow` | Preserve version ownership and one authoritative lifecycle. |
| Canonical messages, conversations, branches, delivery | `internal/domain/messaging` | Keep platform IDs as external correlation, not canonical IDs. |
| Admission and deterministic routing of proposed durable work | `internal/domain/workintake` | Emit an accepted request; do not construct execution state. |
| Generic plugin identity/discovery/compatibility/lifecycle | `internal/domain/plugin` | Keep generic contract metadata-only. |
| Capability-specific plugin behavior | Owning domain's typed registry/manager | Never add behavior to `plugin.Plugin`. |
| Broker-neutral publication/subscription mechanics | `internal/eventbus` | Keep message meaning and schemas with their domain. |
| Shared policy evaluation/evidence mechanics | `internal/policy` | Keep policy vocabulary, evaluators, and consequences with the consuming domain. |
| NATS, SQLite/NellDB, forge, config decoding, external SDK adapters | `internal/infrastructure/<capability>` | Implement a narrow owner-defined contract; translate at boundary. |
| Construction, cross-domain connection, startup/shutdown | `internal/app/archied` or `internal/app/agentworker` | Keep `cmd/*` thin; define health and shutdown order. |
| First-party optional capability | `plugins/<plugin>` | Make it removable; give only narrow contracts/services. |
| Deployment assembly | `deployments/<assembly>` | Do not move application behavior into deployment files. |
| Unreviewed memory/tools/workspace/gate/storage/web/RPC/scheduling behavior | **OPEN** | Run `archie-architecture-planning-campaign`; do not guess placement. |
## Confront known weak points
State these plainly in every affected plan:
| Weak point on 2026-07-28 | Required response |
| --- | --- |
| `TaskContext` is a mutable service bag containing complete config, services, policy, and scratch state. | Do not add another unrelated field casually. Design narrow step inputs/contracts and a staged removal path. |
| Workflow lifecycle is split across store, daemon, workflow, gateway, and worker code. | Trace every writer and reader before changing status. Require one owner, parity tests, and deletion criteria. |
| State changes and transition history are non-atomic; `from` is advisory. | Treat state-machine and atomic-event work as architecture migration. Do not “fix” one caller and claim completion. |
| In-process and container paths put workflow orchestration on different sides of the process boundary. | Decide which path survives and why before extending both. Fence compatibility adapters and name their deletion gate. |
| Identity uses strings; task uniqueness and NATS deduplication omit identity. | Do not promise independent multi-identity ownership until canonical IDs, uniqueness, and transport correlation migrate. |
| Container RPC registration uses root forge/worktree clients, not the task owner's identity bindings. | Treat non-root container execution as a known trust/correctness defect; never describe it as identity-isolated. |
| Missing or malformed container `task.json` makes `archie-agent` join the shared task-run queue. | Do not claim a per-task workspace binding after this fallback. Require valid boot identity to fail closed before treating the path as isolated. |
| Subprocess execution uses the daemon user and host access. | Never describe subprocess mode as a security boundary. Require a real container/isolation design for confidentiality or integrity. |
| Gateway duplicates lifecycle strings and has competing message contracts. | Do not add a third contract or another direct lifecycle mutation path. |
| Global config and `IdentityConfig` combine unrelated owners. | Do not cure complexity with a renamed global structure or an untyped `Extra` map. |
| Memory has fixed scope requirements but OPEN final placement and migration. | Preserve scope isolation; use focused design before moving providers or persistence. |
| Tests can make unused or duplicate code appear legitimate. | Prove production reachability from composition and dispose of the superseded path; use `archie-technical-accountability`. |
## Control every architecture-affecting change
Classify the change before editing:
| Class | Action |
| --- | --- |
| Current-path repair | Stay inside the current owner, preserve invariants, and avoid speculative target scaffolding. |
| Migration slice | Record current owner, target owner, state/contracts to preserve, compatibility adapter, cutover, and objective deletion criteria. |
| New or changed architecture | Stop implementation and run `archie-architecture-planning-campaign` until the focused decision is approved. |
Before implementation:
- [ ] Name the single behavior under change.
- [ ] Trace its production entry point, constructor, consumers, mutable state,
persistence, lifecycle, config, tests, and process crossings.
- [ ] Search for duplicates, alternate implementations, and older code paths.
- [ ] Read the focused decision document; do not infer authority over neighbors.
- [ ] Mark every claim CURRENT, APPROVED TARGET, or OPEN.
- [ ] Name the authoritative owner and every superseded path.
- [ ] Define parity, cutover, rollback, and deletion evidence.
- [ ] Route unresolved ownership or semantics to the architecture campaign.
Use evidence, not name matching:
```bash
rg -n '<constructor>|<interface>|<method>' cmd internal
go list -deps ./cmd/archied | rg 'github.com/samcharles93/archie-core/internal/'
gopls references path/to/file.go:<line>:<column>
```
Use `gopls references` or another AST-aware reference query when interfaces,
embedding, generated symbols, or same-named methods make text search ambiguous.
Trace from `cmd/archied/main.go`; a unit test, constructor, or exported symbol
does not prove production use.
After implementation:
- [ ] Show the production call path to the changed behavior.
- [ ] Show that state has one authoritative writer or explicitly fence the
temporary compatibility path.
- [ ] Show what old path was deleted, retained with rationale, or assigned a
dated/objective deletion gate.
- [ ] Re-run focused tests plus `archie-change-control`.
- [ ] Run an independent architecture review that assumes every new boundary is
wrong until evidence proves it.
- [ ] Reject “tests pass” as sufficient evidence of maintainability.
## Provenance and maintenance
Volatile facts in this skill were verified on **2026-07-28**. Re-verify them
before architecture work:
```bash
test ! -d internal/domain && echo 'target domain tree is not current'
sed -n '1,90p' docs/prds/01-project-management.md
sed -n '1,260p' docs/prds/architecture/migration-decisions.md
sed -n '1,320p' internal/store/store.go
sed -n '1,240p' internal/workflow/workflow.go
sed -n '1,220p' internal/agentexec/protocol.go
sed -n '620,680p' cmd/archied/main.go
sed -n '930,975p' internal/daemon/daemon.go
go test ./internal/plugin -count=1
command -v gopls && gopls help references
```
@@ -0,0 +1,4 @@
interface:
display_name: "Archie Architecture Contract"
short_description: "Protect Archie load-bearing architecture decisions"
default_prompt: "Use $archie-architecture-contract to place and review this change without violating current or target architecture."
@@ -0,0 +1,526 @@
---
name: archie-architecture-planning-campaign
description: Run a decision-gated architecture campaign for archie-core before implementing a cross-package feature, migration, new domain, new process boundary, configuration redesign, duplicated-path cleanup, or other change whose ownership and change surface are unclear. Use when an engineer would otherwise need to trace much of the repository to discover what a feature touches, when TDD can prove behavior but not maintainability, or when planning must distinguish the live implementation from the approved target architecture.
---
# Archie architecture planning campaign
Prevent another last-minute migration. Produce an implementation-ready
architecture handoff in which every behavior, state transition, configuration
value, boundary, compatibility path, and deletion has an explicit owner and
testable disposition. Optimize for a cohesive change that a zero-context
engineer can locate, explain, extend, and remove without tracing unrelated code,
not the first green test.
## Load the required skill chain
Load these sibling skills before starting. For smaller-context sessions,
load only the first two initially, then load the rest at their relevant
phase:
1. `archie-codebase-discovery` — investigate the complete live change cone.
2. `archie-architecture-contract` — apply Archie's load-bearing invariants.
3. `archie-research-methodology` — state hypotheses and measurable predictions
(needed by Phase 5).
4. `archie-technical-accountability` — record evidence, decisions, debt, and
ownership without hiding uncertainty (needed by Phase 6+).
5. `archie-change-control` — classify and gate any resulting source or runtime
change (needed by Phase 11).
Also load `archie-domain-reference` at Phase 3 (vocabulary and ownership) and
`archie-docs-and-writing` plus its template at Phase 10 (ADR/PRD handoff).
If a sibling is unavailable, stop at the current read-only gate and report the
missing control. Do not reconstruct its doctrine from memory.
## Know when not to use this campaign
- For a localized defect whose owner, state, consumers, and boundary are already proven, use `archie-change-control` and the repository TDD workflow.
- To explore an unfamiliar package, use `archie-codebase-discovery`.
- To review an already-written patch, use `archie-technical-accountability` plus the applicable review and validation skills.
- To justify a preferred rewrite, use `archie-research-methodology`; this campaign may conclude that no architecture change is warranted.
## Use the ground-truth model
Keep two ledgers. Never blend them.
| Ledger | Authority | Meaning |
|---|---|---|
| Current implementation | Live production wiring, Go code, persistence, tests, deployment definitions, and observed behavior | What Archie does now, including duplication and defects |
| Approved target | `docs/prds/01-project-management.md` and the status-qualified decisions in `docs/prds/architecture/*.md` | What Archie has approved or explicitly left open |
Treat `ARCHITECTURE.md` as a useful earlier architecture description, not proof
that current wiring still matches it. Treat a decision marked “in progress,”
“deferred,” or “under design” as a constraint plus open questions, not a
finished design.
As of 2026-07-28, the approved target is domain-oriented, while much of the live
tree remains in technical packages such as `internal/config`, `internal/daemon`,
`internal/store`, and `internal/workflow`. Re-run the provenance commands before
relying on that volatile fact.
## Define the terms once
- **Area under review**: one cohesive application responsibility, not an existing directory name.
- **Owner**: the domain or capability with authority over behavior, vocabulary, state, settings, commands, events, and consequences.
- **Change cone**: every entry point, caller, consumer, state record, adapter, test, configuration input, process boundary, and document affected by the decision.
- **Domain contract**: the smallest behavior required by the owning domain; infrastructure implements it.
- **Compatibility path**: a temporary adapter, dual read, dual write, or translation used only to preserve behavior during cutover.
- **Authoritative path**: the sole path allowed to decide or mutate a behavior after cutover.
- **Deletion criterion**: observable evidence that makes removal safe; “after migration” is not a criterion.
- **Architecture packet**: the complete evidence and decision handoff produced by this campaign.
## Establish dynamic expected numbers
Do not invent repository counts. First verify the repository root, then
capture baselines and use them as expected numbers:
```bash
git rev-parse --show-toplevel >/dev/null || { echo 'run from repo root' >&2; exit 1; }
test -f go.mod && test -f Taskfile.yml && test -f CLAUDE.md || {
echo 'go.mod, Taskfile.yml, or CLAUDE.md missing — wrong directory?' >&2
exit 1
}
git rev-parse HEAD
git status --short
go list -f '{{.ImportPath}}' ./internal/... | sort | tee /tmp/archie-architecture-packages.txt
wc -l /tmp/archie-architecture-packages.txt
find docs/prds/architecture -maxdepth 1 -type f -name '*.md' -print | sort | tee /tmp/archie-architecture-docs.txt
wc -l /tmp/archie-architecture-docs.txt
```
Name the resulting counts:
- `P` = current internal package rows in scope; for the whole migration, use every row in `/tmp/archie-architecture-packages.txt`.
- `D` = architecture decision documents.
- `F(area)` = production and test Go files in the declared change cone.
- `R(symbol)` = typed references returned for a symbol by gopls.
- `C` = decoded configuration fields and behavior-affecting literals in scope.
- `L` = legacy or competing paths in scope.
Record the commit and dirty-file list beside every baseline. If concurrent work changes either, refresh the affected baseline; never mix measurements from two tree states.
## Phase 0 — Declare one decision scope
Write one sentence in this form:
> Decide who owns `<behavior>`, how `<input>` reaches `<outcome>`, and how the current paths migrate without changing `<preserved invariants>`.
List explicit non-goals and affected operators/users. Classify the work with `archie-change-control`, but authorize no implementation yet.
**Gate 0 — scope**
- Expected declared architecture questions: `1`.
- Expected unexplained dirty files in the change cone: `0`.
- Expected implementation edits during the campaign: `0`.
- Expected non-goal list: at least `1` item.
If more than one independent architecture question remains, split campaigns. If a dirty file has unknown ownership, pause until its author or intent is known.
## Phase 1 — Build the decision corpus
Read the index and every focused architecture decision before designing:
```bash
sed -n '1,240p' docs/prds/01-project-management.md
while IFS= read -r ARCHIE_DOC; do sed -n '1,520p' "$ARCHIE_DOC"; done < /tmp/archie-architecture-docs.txt
sed -n '1,360p' ARCHITECTURE.md
sed -n '1,240p' CLAUDE.md
```
Build a current-versus-target ledger with columns:
| Claim | Current evidence | Target decision | Status | Conflict or open decision |
|---|---|---|---|---|
Give special attention to:
- `package-review.md` for the required investigation and decision set;
- `migration-decisions.md` for unresolved destinations and cutover;
- `organisation.md` and `dependencies-and-contracts.md` for ownership and dependency direction;
- `configuration.md` for the required dissolution of `internal/config`;
- `safe-change-and-recovery.md` for candidate promotion and rollback;
- identity, agent, messaging, workflow, policy, plugin, and generated-doc documents whenever their vocabulary or contracts enter the change cone.
**Gate 1 — corpus**
- Expected decision-document review rows: `D`.
- Expected documents with omitted status: `0`.
- Expected target claims presented as current behavior: `0`.
- Expected contradictions without an evidence link and disposition: `0`.
If live code contradicts an approved target, record migration work; do not silently redefine the target. If approved documents conflict, stop and request a decision instead of choosing the easier implementation.
## Phase 2 — Inventory the live change cone with syntax-aware tools
Do not start from package names. Start at production entry points and behavior.
```bash
rg -n '^func main\\(' cmd
rg -n 'flag\\.(String|Bool|Int|Int64|Duration|Var)' cmd --glob '*.go'
rg --files cmd internal | sort
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-architecture-inventory-cache go run .claude/skills/archie-architecture-planning-campaign/scripts/go-inventory.go -root . -scope internal/<area> -include-tests=true
```
Replace `<area>` with a real repository-relative directory. Run the inventory once per package in the change cone. It emits Go-parser-derived declarations as tab-separated columns:
| Column | Kind values | Meaning |
|---|---|---|
| `KIND` | `IMPORT`, `TYPE`, `FUNC`, `METHOD`, `VAR`, `CONST` | Go AST declaration kind |
| `PACKAGE` | Directory path relative to `-root` | Package directory containing the declaration |
| `FILE` | Filename within the package | Source file |
| `LINE` | Positive integer | Declaration line number |
| `NAME` | Identifier string | Exported or unexported name |
| `DETAIL` | Short type/kind string | Receiver type for `METHOD`, underlying type for `TYPE`, signature summary for `FUNC` |
Empty output means no matching Go packages were found under `-scope`.
Lines with empty `NAME` after the tab are parse-level artifacts; treat them
as noise. The inventory does not infer runtime use, cross-package references,
or dynamic registration.
Use gopls after the inventory:
- call `go_workspace` to confirm the module view;
- call `go_package_api` for every package exposing a boundary;
- call `go_search` for each domain term and competing synonym;
- call `go_symbol_references` for every constructor, interface, state type, command, event, setting, and persistence method in scope.
If gopls is unavailable, use `go doc <package>`, `go list -json <package>`, and literal `rg` as a fallback. Label text-search counts approximate; do not claim typed coverage.
Count files before reading:
```bash
rg --files internal/<area> -g '*.go' | sort | tee /tmp/archie-architecture-area-files.txt
wc -l /tmp/archie-architecture-area-files.txt
```
**Gate 2 — inventory**
- Expected files read: `F(area)`, the baseline line count.
- Expected boundary packages with API summaries: all boundary packages; omitted count `0`.
- Expected typed references traced for each selected symbol: `R(symbol)`; unexplained references `0`.
- Expected discoverable facts deferred as user questions: `0`.
If gopls and text search disagree, inspect generated files, build tags, interfaces, reflection, Yaegi loading, and registration side effects. Do not infer “unused” from zero textual callers.
## Phase 3 — Establish vocabulary and ownership
Extract verbs, nouns, records, transitions, commands, events, settings, and failure outcomes from live behavior. Resolve overloaded terms rather than globally renaming `task`, `session`, `message`, `execution`, `identity`, or `plugin`.
Create this table:
| Term or behavior | Plain-language definition | Current locations | One owner | Competing meaning | Target contract |
|---|---|---|---|---|---|
Use these ownership tests:
1. Name the cohesive job.
2. Name the mutable records and transitions it governs.
3. Name the policy consequences it decides.
4. Name only the external services it requires.
5. Explain why this code changes together.
Reject ceremonial `entities`, `services`, `helpers`, and `common` layers. A single-operation wrapper needs a boundary reason, a second genuine consumer, or removal/inlining.
For NellDB-related areas, inspect `internal/nell`, every consumer, persistence tests, and the pinned module before assigning semantics:
```bash
go list -m -f '{{.Path}} {{.Version}}' github.com/samcharles93/NellDB
rg -n 'nell\\.|NellDB|OpenStore|NewSessionStore' cmd internal --glob '*.go'
```
Do not make NellDB records domain models merely because they persist current state.
**Gate 3 — vocabulary**
- Expected behaviors or records without one owner: `0`.
- Expected unqualified terms with multiple meanings: `0`.
- Expected domain owners chosen because of an existing directory name: `0`.
- Expected boundaryless single-operation indirection: `0`, unless listed for deletion or justified by a tested contract.
If one candidate owner must know another domain's internal state, redesign the handoff as an owned command, event, or narrow shared contract.
## Phase 4 — Trace consumers, state, and failure semantics
Trace each behavior from input to observable outcome:
| Input/source | Entry point | Command/event | State mutation | Persistence | Side effect | Failure/retry | Output |
|---|---|---|---|---|---|---|---|
For every mutable record, produce a transition table:
| From | Command | Preconditions/version | To | Atomic event | Invalid result | Retry/idempotency |
|---|---|---|---|---|---|---|
Inspect production construction in `cmd/archied/main.go` and `cmd/archie-agent/main.go`; constructors alone do not prove production use. Trace RPC, NATS, container, in-process, and subprocess paths separately. Trace tests after production; a mirrored fake can validate the same wrong assumption.
**Gate 4 — runtime trace**
- Expected production consumers reconciled per symbol: `R(symbol)`.
- Expected mutable records without a complete transition table: `0`.
- Expected state mutations without an identified transaction boundary: `0`.
- Expected side effects without failure, timeout, retry, and idempotency evidence: `0`.
- Expected competing authoritative write paths: `0`, or exactly `L` rows with cutover and deletion criteria.
If two paths create the same outcome, do not add a third abstraction over both. Decide authority and migration direction first.
## Phase 5 — Compare solutions and predict change locality
Use `archie-research-methodology`. Compare at least three explicit options:
| Rank | Approach | Normal use | Fence |
|---|---|---|---|
| 1 candidate default | Domain-first modular monolith with owner-defined contracts and composition in `internal/app` | Behavior and ownership are understood | Do not retain old technical ownership merely to reduce moves |
| 2 migration tool | Strangler cutover through the narrowest compatibility adapter | Data or live callers require staged migration | Require owner, expiry trigger, metrics, rollback, and deletion test |
| 3 conditional | Retain a process boundary or extract a service | Measured security isolation, failure containment, scaling, or independent-operation need exists | Future possibility is not evidence |
| rejected | Rename a generic package, pass global config, add a service locator, or keep parallel implementations indefinitely | Never | Violates approved architecture |
Score each legitimate option on cohesion, dependency direction, state authority, contract size, configuration ownership, failure containment, migration risk, reversibility, deletion cost, and testability.
Before choosing, rehearse at least three representative future changes:
1. add a small behavior to the area;
2. replace an infrastructure implementation;
3. change one owned setting or policy.
Predict the packages, contracts, and tests each would touch. Prefer obvious ownership and exclusion of unrelated packages over the smallest immediate diff.
**Gate 5 — option decision**
- Expected compared options: at least `3`, including the current structure.
- Expected selected option: `1`.
- Expected approved-invariant violations in the winner: `0`.
- Expected representative change rehearsals: at least `3`.
- Expected unexplained unrelated packages per rehearsal: `0`.
- Expected predictions without a measurement or later verification command: `0`.
If no option clears every invariant, leave the decision open. Do not downgrade a MUST to get a winner.
## Phase 6 — Complete the package destination matrix
For the architecture migration, create one row for every package in `P`. For a bounded change, cover the measured change cone and prove why other packages are outside it.
| Current package/behavior | Owner | Target path | Disposition | Dependencies to remove | State/contracts to preserve | Prerequisites | Deletion criterion | Decision status |
|---|---|---|---|---|---|---|---|---|
Use only these dispositions: move, merge with named replacement, infrastructure adapter, application composition, approved shared contract, plugin/extra/deployment/example/generated artifact, or delete after proof.
**Gate 6 — destinations**
- Expected destination rows: `P` for the whole migration, otherwise every package in the recorded change cone.
- Expected blank owner, disposition, or status cells: `0`.
- Expected confirmed rows that still require an implementer to invent domain semantics: `0`.
- Expected compatibility rows without deletion criteria: `0`.
An open row blocks that row, not an independent confirmed slice.
## Phase 7 — Dissolve configuration by ownership
Inventory both decoded fields and behavior-affecting literals:
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-architecture-inventory-cache go run .claude/skills/archie-architecture-planning-campaign/scripts/go-inventory.go -root . -scope internal/config -include-tests=false
rg -n '\\bconfig\\.' cmd internal --glob '*.go'
rg -n 'time\\.(Second|Minute|Hour)|time\\.Duration|http\\.DefaultClient|0\\.0\\.0\\.0|localhost|/usr/share|/data/' cmd internal --glob '*.go'
```
For each value, record external input, default/provenance, typed owner, validation, mutability, consumers, secrets, and migration. Keep the decoded document private to configuration infrastructure; never pass complete app configuration into a domain.
Classify every literal as invariant, owned setting/default, policy value, external constraint, or defect. One current value does not make an invariant.
**Gate 7 — configuration**
- Expected inventoried configuration items: `C`.
- Expected items without exactly one runtime owner and classification: `0`.
- Expected domains importing configuration infrastructure or full app config:
`0` in the target.
- Expected live-setting mutation paths omitted from the migration ledger: `0`.
- Expected plugin settings added to an unrelated global model: `0`.
If an item cannot reload safely, mark it restart-required and design candidate
validation, health observation, last-known-good preservation, and rollback.
## Phase 8 — Justify process and trust boundaries
Inventory current boundaries:
```bash
rg -n 'Subprocess|NATS|nats\\.|RPC|rpc|container|Docker|Yaegi|plugin' cmd/archied cmd/archie-agent internal/{agentexec,container,nats,natsrpc,taskrun,forgerpc,storerpc,worktreerpc,plugin,yaegiutil} --glob '*.go'
```
For each retained boundary, record purpose, trusted principal, secrets and
resources exposed, protocol owner/version, failure containment, health,
startup/shutdown order, retries, and operator burden.
Keep source ownership independent of deployment. Treat a subprocess as
transport, not a security sandbox. Keep model-owned work away from git
credentials and daemon authority. Give plugins narrow typed registrars, never
daemon access or generic hooks.
**Gate 8 — boundaries**
- Expected retained boundaries with one concrete justification: all retained
boundaries; unjustified count `0`.
- Expected external or cross-process contracts without owner/version: `0`.
- Expected boundaries described as isolation without an enforced isolation
mechanism: `0`.
- Expected domains split only for possible future deployment: `0`.
If removal of a boundary changes confidentiality, integrity, availability, or
operations, return to Phase 5 with those constraints.
## Phase 9 — Plan deprecation, cutover, rollback, and deletion
Mine compatibility and prior replacement attempts:
```bash
rg -n 'legacy|compat|deprecated|deprecat|TODO|FIXME|HACK|remove|delete' cmd internal docs --glob '*.go' --glob '*.md'
git log --oneline --decorate --all -- cmd internal docs/prds/architecture
git log -S'internal/config' --oneline --all
```
For each legacy path, record predecessor, successor, parity evidence, data
backfill, dual-read/write need, production switch, rollback trigger, observation
window, deletion criterion, and regression test.
Require the production composition test to prove the successor is selected.
Require a negative test or architecture check to prevent reintroduction after
deletion. Time-box transitional duplication by an observable trigger, not a
calendar promise alone.
**Gate 9 — cutover**
- Expected legacy paths inventoried: `L`.
- Expected successor authorities per legacy behavior: exactly `1`.
- Expected compatibility paths without owner, rollback, and deletion proof:
`0`.
- Expected permanent duplicate authoritative paths after cutover: `0`.
- Expected old states/records without migration or explicit safe abandonment:
`0`.
If parity cannot be measured, do not switch production wiring. Design the
observable first.
## Phase 10 — Produce the ADR/PRD handoff
Write or propose the focused architecture document only where change control
authorizes it. Include:
1. scope and non-goals;
2. current-state trace with commit and dynamic baselines;
3. vocabulary and ownership;
4. current-versus-target ledger;
5. considered options, predicted numbers, and rejection reasons;
6. chosen owner, contracts, state machine, settings, policy, and boundaries;
7. destination matrix;
8. migration, compatibility, cutover, rollback, and deletion;
9. implementation slices and dependencies;
10. verification commands, expected evidence, unknowns, and named decisions
still requiring the user.
Ask the user only questions whose answers materially change behavior or
structure and cannot be discovered in the repository.
**Gate 10 — handoff**
- Expected discoverable facts presented as questions: `0`.
- Expected undecided semantics delegated to implementers in a confirmed slice:
`0`.
- Expected claims without source evidence or explicit “candidate/open” status:
`0`.
- Expected unresolved normative contradictions: `0`.
If a decision remains open, isolate it from executable slices and name its
owner. Never disguise it as an implementation detail.
## Phase 11 — Slice for short, artful successes
Route every slice through `archie-change-control`. Keep TDD and fresh
adversarial review, but add architecture acceptance before code acceptance.
Each slice must:
- deliver one observable behavior or migration proof;
- have one domain owner and a bounded change cone;
- establish or consume the final contract rather than create another temporary
model;
- preserve a working application at its boundary;
- remove a predecessor, or advance its recorded deletion criterion;
- add deterministic conformance protection where mechanically possible;
- state what becomes easier to change after the slice.
Order slices as: characterization and observability, final contract, adapter or
data migration, production cutover, legacy deletion, architecture regression
guard. Do not create all target folders as empty scaffolding.
**Gate 11 — executable plan**
- Expected observable outcome per slice: `1`.
- Expected owner per slice: `1`.
- Expected unrelated domains modified per slice: `0`.
- Expected predecessors neither removed nor advanced toward deletion: `0`.
- Expected implementation slices bypassing change control: `0`.
If a slice requires broad service-locator access or the full configuration
document, return to ownership and contract design.
## Phase 12 — Re-measure after every slice
Run the repository gate selected by `archie-change-control`, then compare the
slice against this packet. At minimum, re-run package inventory, typed
references, production construction tracing, configuration inventory, and
legacy-path search.
Use a fresh adversarial reviewer to inspect every changed non-test file for
cohesion, hidden dead paths, duplicated authority, unchecked errors,
hard-coded behavior, interface leakage, nil/race/goroutine risk, and production
wiring. A green TDD suite proves required behavior; it does not prove the code
is maintainable.
**Gate 12 — conformance**
- Expected unexplained package/reference/configuration deltas from baseline:
`0`.
- Expected new authoritative paths beyond the selected design: `0`.
- Expected surviving reviewer findings: `0`.
- Expected destination/cutover rows left stale by the slice: `0`.
- Expected representative change rehearsals made harder without an accepted
rationale: `0`.
If the slice passes tests but fails conformance, reject or redesign it. “Make it
work and move on” is not completion.
## Fence off settled wrong paths
- Do not code before mapping ownership, consumers, state, and cutover.
- Do not equate moving or renaming packages with architecture.
- Do not centralize unrelated runtime settings in a renamed global config.
- Do not add abstractions solely to wrap one operation or hide duplication.
- Do not preserve old and new models indefinitely “for compatibility.”
- Do not expose domain meaning through broker, database, SDK, or DTO types.
- Do not use process splits as source boundaries or subprocesses as sandboxes.
- Do not add capability methods to the generic plugin contract.
- Do not ask the user to rediscover code facts the tools can establish.
- Do not accept linter silence as dead-code evidence; inspect registration,
reflection, build tags, generated code, and production composition.
- Do not let a mirrored test fake become the sole proof of an external or
cross-process contract.
- Do not permit implementation difficulty to waive an approved invariant.
## Provenance and maintenance
Grounded on 2026-07-28 in the approved architecture index and every file under
`docs/prds/architecture/`, plus live `cmd`, `internal`, tests, `Taskfile.yml`,
and the user's quality requirements. Re-verify volatile facts before each use.
```bash
sed -n '1,240p' docs/prds/01-project-management.md
for ARCHIE_DOC in docs/prds/architecture/*.md; do sed -n '1,8p' "$ARCHIE_DOC"; done
go list -f '{{.ImportPath}}' ./internal/... | sort
rg -n '^func main\\(' cmd
rg -n '\\bconfig\\.' cmd internal --glob '*.go'
rg -n 'legacy|compat|deprecated|TODO|FIXME|HACK' cmd internal docs --glob '*.go' --glob '*.md'
git log --oneline --decorate --all -- cmd internal docs/prds/architecture
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-architecture-inventory-cache go run .claude/skills/archie-architecture-planning-campaign/scripts/go-inventory.go -root . -scope internal/config -include-tests=false
task --list
```
@@ -0,0 +1,4 @@
interface:
display_name: "Archie Architecture Planning Campaign"
short_description: "Plan maintainable Archie architecture before coding"
default_prompt: "Use $archie-architecture-planning-campaign to design and gate an Archie architectural change before implementation."
@@ -0,0 +1,231 @@
// Command go-inventory emits a stable TSV inventory of Go declarations.
//
// It uses the Go parser instead of text matching, so architecture research can
// enumerate imports, types, struct fields, functions, methods, variables, and
// constants before tracing their references with gopls.
package main
import (
"bytes"
"flag"
"fmt"
"go/ast"
"go/format"
"go/parser"
"go/token"
"io/fs"
"os"
"path/filepath"
"sort"
"strconv"
"strings"
)
type record struct {
kind string
pkg string
file string
line int
name string
detail string
sortKey string
}
func main() {
rootFlag := flag.String("root", ".", "repository root")
scopeFlag := flag.String("scope", "internal", "repository-relative directory to inspect")
includeTests := flag.Bool("include-tests", true, "include _test.go files")
flag.Parse()
root, err := filepath.Abs(*rootFlag)
if err != nil {
fatalf("resolve root: %v", err)
}
scope, err := confinedPath(root, *scopeFlag)
if err != nil {
fatalf("resolve scope: %v", err)
}
fset := token.NewFileSet()
var records []record
err = filepath.WalkDir(scope, func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
if entry.IsDir() {
switch entry.Name() {
case ".git", "node_modules", "testdata", "vendor":
if path != scope {
return filepath.SkipDir
}
}
return nil
}
if filepath.Ext(path) != ".go" || (!*includeTests && strings.HasSuffix(path, "_test.go")) {
return nil
}
parsed, parseErr := parser.ParseFile(fset, path, nil, 0)
if parseErr != nil {
return fmt.Errorf("parse %s: %w", path, parseErr)
}
relative, relErr := filepath.Rel(root, path)
if relErr != nil {
return relErr
}
relative = filepath.ToSlash(relative)
pkg := filepath.ToSlash(filepath.Dir(relative))
records = append(records, fileRecords(fset, parsed, pkg, relative)...)
return nil
})
if err != nil {
fatalf("inventory: %v", err)
}
sort.Slice(records, func(i, j int) bool {
return records[i].sortKey < records[j].sortKey
})
fmt.Println("KIND\tPACKAGE\tFILE\tLINE\tNAME\tDETAIL")
for _, item := range records {
fmt.Printf("%s\t%s\t%s\t%d\t%s\t%s\n",
item.kind,
item.pkg,
item.file,
item.line,
sanitize(item.name),
sanitize(item.detail),
)
}
}
func confinedPath(root, scope string) (string, error) {
if filepath.IsAbs(scope) {
return "", fmt.Errorf("scope must be repository-relative")
}
clean := filepath.Clean(scope)
if clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator)) {
return "", fmt.Errorf("scope escapes repository root")
}
path := filepath.Join(root, clean)
info, err := os.Stat(path)
if err != nil {
return "", err
}
if !info.IsDir() {
return "", fmt.Errorf("%s is not a directory", clean)
}
return path, nil
}
func fileRecords(fset *token.FileSet, file *ast.File, pkg, relative string) []record {
var records []record
add := func(kind string, pos token.Pos, name, detail string) {
line := fset.Position(pos).Line
records = append(records, record{
kind: kind,
pkg: pkg,
file: relative,
line: line,
name: name,
detail: detail,
sortKey: strings.Join([]string{pkg, relative, fmt.Sprintf("%09d", line), kind, name}, "\x00"),
})
}
for _, imported := range file.Imports {
path, err := strconv.Unquote(imported.Path.Value)
if err != nil {
path = imported.Path.Value
}
name := ""
if imported.Name != nil {
name = imported.Name.Name
}
add("IMPORT", imported.Pos(), name, path)
}
for _, declaration := range file.Decls {
switch node := declaration.(type) {
case *ast.FuncDecl:
kind := "FUNC"
name := node.Name.Name
if node.Recv != nil && len(node.Recv.List) > 0 {
kind = "METHOD"
name = expression(node.Recv.List[0].Type) + "." + name
}
add(kind, node.Pos(), name, expression(node.Type))
case *ast.GenDecl:
for _, spec := range node.Specs {
switch item := spec.(type) {
case *ast.TypeSpec:
detail := typeKind(item.Type)
add("TYPE", item.Pos(), item.Name.Name, detail)
structType, ok := item.Type.(*ast.StructType)
if !ok {
continue
}
for _, field := range structType.Fields.List {
fieldNames := make([]string, 0, len(field.Names))
for _, name := range field.Names {
fieldNames = append(fieldNames, name.Name)
}
if len(fieldNames) == 0 {
fieldNames = append(fieldNames, expression(field.Type))
}
for _, fieldName := range fieldNames {
add("FIELD", field.Pos(), item.Name.Name+"."+fieldName, expression(field.Type))
}
}
case *ast.ValueSpec:
kind := "VAR"
if node.Tok == token.CONST {
kind = "CONST"
}
for _, name := range item.Names {
add(kind, item.Pos(), name.Name, expression(item.Type))
}
}
}
}
}
return records
}
func expression(node ast.Node) string {
if node == nil {
return ""
}
var buffer bytes.Buffer
if err := format.Node(&buffer, token.NewFileSet(), node); err != nil {
return fmt.Sprintf("%T", node)
}
return buffer.String()
}
func typeKind(node ast.Expr) string {
switch node.(type) {
case *ast.StructType:
return "struct"
case *ast.InterfaceType:
return "interface"
case *ast.FuncType:
return "func"
case *ast.ArrayType:
return "array-or-slice"
case *ast.MapType:
return "map"
case *ast.ChanType:
return "chan"
default:
return expression(node)
}
}
func sanitize(value string) string {
return strings.Join(strings.Fields(value), " ")
}
func fatalf(format string, args ...any) {
fmt.Fprintf(os.Stderr, format+"\n", args...)
os.Exit(1)
}
@@ -0,0 +1,424 @@
---
name: archie-build-and-env
description: Recreate, inspect, and troubleshoot Archie Core's development, build, test, documentation, and container toolchains. Use when onboarding a checkout; diagnosing Go, Task, golangci-lint, gofumpt, pnpm, VitePress, Docker/Compose, NATS, GPG, cache, temporary-directory, listener, or network failures; comparing local work with repository automation; or proving which build surfaces a command actually covers. Load this before running task check in an unfamiliar or restricted environment because that gate rewrites files and omits several independent surfaces.
---
# Build and verify the Archie environment
Recreate the environment as independently verified surfaces. Do not turn a
passing root-module command into a claim that the tools module, documentation
site, race detector, linter, or container images also passed.
All volatile observations in this skill are snapshots from **2026-07-28**.
Re-run the maintenance commands at the end before relying on a number or
installed version.
## Keep the scope narrow
- Do not use this skill to decide whether evidence is sufficient for acceptance.
Load `archie-validation-and-qa`.
- Do not use it to start, stop, deploy, upgrade, or recover a running daemon.
Load `archie-run-and-operate`.
- Do not use it to interpret a product failure after the environment is known
good. Load `archie-debugging-playbook`.
- Do not use it to choose or wire runtime settings. Load
`archie-config-and-flags`.
- Do not use it to approve generated changes, dependency updates, cleanup, or
gate changes. Load `archie-change-control`.
- Do not use `docs-2/README.md` as onboarding documentation. It describes Tau,
and VitePress excludes it through `srcExclude` in
`docs-2/.vitepress/config.mts`.
## Name the surfaces
Use these terms consistently:
| Term | Meaning here |
|---|---|
| Repository root | The directory containing `go.mod`, `Taskfile.yml`, and `CLAUDE.md`. |
| Runtime module | The root Go module, `github.com/samcharles93/archie-core`. It owns `cmd/`, `domain/`, and `internal/`. |
| Tools module | The independent nested Go module under `tools/`. It currently owns `tools/docsgen`. |
| Docs site | The pnpm/VitePress project under `docs-2/`. |
| Cold cache | A dependency cache that does not yet contain the required modules or packages; filling it requires network access. |
| Restricted sandbox | An environment that may allow file reads but deny loopback listeners, the container engine, or writes to default caches and temporary directories. |
| Host run | A run on an environment that permits the listeners and process features used by the tests. |
No root `README*` or `CONTRIBUTING*` file exists as of the snapshot. Begin with:
```bash
sed -n '1,240p' CLAUDE.md
sed -n '1,240p' ARCHITECTURE.md
task --list
```
Treat `CLAUDE.md` and `Taskfile.yml` as the current workflow contract. Treat
`ARCHITECTURE.md` as necessary design context, but verify implemented package
claims against current code and tests.
## Inventory requirements before installing anything
Do not guess versions from the installed machine. Compare the checkout's
declarations with the machine:
```bash
go version
go env GOTOOLCHAIN GOVERSION GOOS GOARCH CGO_ENABLED GOTMPDIR GOCACHE GOMODCACHE
task --version
gofumpt -version
golangci-lint version
node --version
pnpm --version
npm --version
docker --version
docker compose version
git --version
gpg --version
```
Classify a missing command as an environment prerequisite, not a code failure.
The repository has no bootstrap installer and does not pin every host tool.
If you must bootstrap from scratch, the Dockerfiles provide a known-good
starting point (verified 2026-07-28):
- Go ≥ 1.26.3 (Docker builder uses `golang:1.26-trixie`)
- Task ≥ 3.x (`go install github.com/go-task/task/v3/cmd/task@latest`)
- gofumpt (`go install mvdan.cc/gofumpt@latest`; unpinned in repo)
- golangci-lint v2 (`go install github.com/golangci-lint/v2/cmd/golangci-lint@latest`; unpinned)
- Node 24.x + pnpm ≥ 10 (see Dockerfile's `setup_24.x` and `npm install -g pnpm`)
Always verify each installed version against the table below and record the
exact version in failure reports. The repository does not guarantee that
`@latest` today matches what was tested on the snapshot date.
| Surface | Repository declaration | Installed snapshot | Interpretation |
|---|---|---|---|
| Runtime Go | `go 1.26.3` in `go.mod` | Go 1.26.5, linux/amd64 | The checkout requires at least the declared Go language/toolchain level. |
| Tools Go | `go 1.26.4` in `tools/go.mod` | Same Go 1.26.5 binary | Use a toolchain that satisfies both modules. |
| Task | Taskfile schema `version: "3"`; no executable version pin | Task 3.48.0 | Installed version is an environment fact, not a repo guarantee. |
| gofumpt | Used by `task fmt`; agent image installs `@latest` | v0.7.0 | Unpinned by the repository. |
| golangci-lint | v2 config in `.golangci.yml`; agent image installs `@latest` | 2.12.2 | Use the v2 CLI; exact release is unpinned. |
| Node | Docs CI uses `node-version: latest`; agent image configures Node 24 | 24.18.0 | The docs project has no `engines` or `packageManager` field. |
| pnpm | Docs CI selects major 10; agent image installs an unpinned global pnpm | 11.15.1 | Prefer CI's major 10 when reproducing CI. Do not call local 11 exact parity. |
| VitePress | `^1.6.4`, locked to 1.6.4 | Resolved by `pnpm-lock.yaml` | Install with the frozen lockfile. |
| Containers | Docker Compose commands in `Taskfile.yml` | `/usr/bin/docker` is a Podman-backed CLI that is unusable in this sandbox | Verify CLI, Compose plugin, daemon/socket, and privileges separately. |
The Docker builders use `golang:1.26-trixie` and
`golang:1.26-bookworm`, while the agent runtime separately installs
`GO_VERSION=1.26.5`. The builder tags float across patch/image rebuilds; they do
not establish byte-for-byte reproducibility.
## Prepare writable caches in a restricted sandbox
First inspect the defaults:
```bash
go env GOTMPDIR GOCACHE GOMODCACHE GOPATH
df -T /tmp
```
If any default is read-only, create task-specific paths. Do not repurpose
`HOME`, `CODEX_HOME`, or another system variable:
```bash
export ARCHIE_GOTMPDIR=/tmp/archie-core-gotmp
export ARCHIE_GOCACHE=/tmp/archie-core-gocache
export ARCHIE_GOMODCACHE=/tmp/archie-core-gomodcache
export ARCHIE_GOPATH=/tmp/archie-core-gopath
export ARCHIE_LINT_CACHE=/tmp/archie-core-golangci
mkdir -p "$ARCHIE_GOTMPDIR" "$ARCHIE_GOCACHE" "$ARCHIE_GOMODCACHE" \
"$ARCHIE_GOPATH" "$ARCHIE_LINT_CACHE"
```
Prefix Go commands with:
```bash
env GOTMPDIR="$ARCHIE_GOTMPDIR" GOCACHE="$ARCHIE_GOCACHE" \
GOMODCACHE="$ARCHIE_GOMODCACHE" GOPATH="$ARCHIE_GOPATH" \
go test ./internal/config/... -count=1
```
An empty `ARCHIE_GOMODCACHE` is a cold cache. Populate each module only when
network access is authorized:
```bash
env GOTMPDIR="$ARCHIE_GOTMPDIR" GOCACHE="$ARCHIE_GOCACHE" \
GOMODCACHE="$ARCHIE_GOMODCACHE" GOPATH="$ARCHIE_GOPATH" \
go mod download
env GOTMPDIR="$ARCHIE_GOTMPDIR" GOCACHE="$ARCHIE_GOCACHE" \
GOMODCACHE="$ARCHIE_GOMODCACHE" GOPATH="$ARCHIE_GOPATH" \
go -C tools mod download
```
On this machine `/tmp` is tmpfs. Caches therefore consume memory-backed
storage. Measure them instead of filling them blindly:
```bash
du -sh "$ARCHIE_GOTMPDIR" "$ARCHIE_GOCACHE" "$ARCHIE_GOMODCACHE" \
"$ARCHIE_GOPATH" "$ARCHIE_LINT_CACHE"
```
## Recreate the root Go surface
Use this cold-start sequence from the repository root:
1. Confirm the module and entry points.
2. Download dependencies if the cache is cold and network is allowed.
3. Compile both binaries.
4. Run a focused test before the full suite.
5. Run vet and lint as separate facts.
```bash
test -f go.mod
test -f cmd/archied/main.go
test -f cmd/archie-agent/main.go
go list -m
go build -o /tmp/archie-core-archied ./cmd/archied
go build -o /tmp/archie-core-agent ./cmd/archie-agent
go test ./internal/config/... -count=1
go vet ./...
golangci-lint run ./...
```
Use the cache prefix from the previous section when defaults are read-only.
Writing binaries to `/tmp` verifies compilation without changing `bin/` or
Task's `.task/` checksum state. The equivalent repository task is:
```bash
task build
```
Expect `task build` to write `bin/archied`, `bin/archie-agent`, and Task cache
state. Do not use it during a read-only review.
## Understand exactly what Task runs
Read `Taskfile.yml`; do not infer command graphs from task names.
| Task | Exact effect |
|---|---|
| `task fmt` | Runs `gofumpt -w .`, then `go fix ./...`; both may rewrite source. |
| `task vet` | Runs `go vet ./...` in the runtime module. |
| `task lint` | Runs `golangci-lint run ./...`; this is separate from `task check`. |
| `task build` | Builds both commands into `bin/`. |
| `task test` | Runs `go test ./... -count=1` in the runtime module. |
| `task check` | Runs `fmt`, runs `go fix ./...` a second time, then `vet`, `build`, and `test`. |
| `task clean` | Recursively removes `bin/`; treat it as destructive. |
| `task docker-build` | Runs `docker compose build agent` only. |
Repository doctrine calls `task check` the definitive gate. Its current
implementation is still only one surface: it omits `task lint`, race tests, the
`tools/` module, docs generation drift, and the VitePress build.
Run `task check` only in an authorized writable worktree. Record its rewrites:
```bash
git status --short
task check
git status --short
git diff --check
```
Never claim that pre-existing changes were produced by the gate. Capture the
first status before running it.
For a read-only formatting preview, avoid `task fmt`:
```bash
gofumpt -l .
```
As of the snapshot, this produced no output. `go fix ./...` has no equivalent
read-only task in this repository, so `task fmt` and `task check` remain
mutating commands even when the gofumpt preview is clean.
## Verify the tools module separately
The repository has no `go.work`. A root `go test ./...` does not enter
`tools/`. The tools module uses:
```text
module github.com/samcharles93/archie-core/tools
replace github.com/samcharles93/archie-core => ../
```
Run its tests explicitly:
```bash
go -C tools test ./... -count=1
```
Generate documentation data to a temporary file and compare it without
rewriting the checkout:
```bash
go -C tools run ./docsgen \
-repo-root .. \
-out /tmp/archie-core-contracts.json
cmp --silent \
docs-2/data/generated/contracts.json \
/tmp/archie-core-contracts.json
```
The 2026-07-28 run wrote 10 schemas, the comparison passed, and
`go -C tools test ./... -count=1` passed. The planned `docsgen all` and
`docsgen check` commands described in
`docs/prds/architecture/generated-documentation.md` do **not** exist yet.
The checkout's `docs-2/data/generated/contracts.json` exists but is untracked
as of this snapshot. The comparison proves local generator parity, not
version-controlled drift protection.
## Recreate and build the docs site
Treat dependency installation and site compilation as two separate gates:
```bash
pnpm --dir docs-2 install --frozen-lockfile
pnpm --dir docs-2 build
```
The install needs registry access on a cold pnpm store. The build writes
`docs-2/.vitepress/dist`. GitHub Pages CI uses pnpm major 10, Node `latest`,
the frozen lockfile, then `pnpm build`; it does not run Go tests or docsgen.
The docs build could not be completed in the restricted 2026-07-28 session
because missing packages required npm registry access and DNS returned
`EAI_AGAIN`. Record that as an environment result, not a passing or failing
site build.
Do not trust the checked-in `docs-2/node_modules` shape. It contains 237
tracked symlink entries as of the snapshot, introduced by commit `308c199`.
Detect the condition:
```bash
git ls-files -s 'docs-2/node_modules/**' \
| awk '$1 == "120000" {count++} END {print count+0}'
git status --short -- docs-2
```
Do not stage, normalize, or mass-delete that tree as incidental setup. Route
its cleanup through `archie-change-control`. Commit `4cb0577` records a
separate cleanup of accidentally committed `.gotmp` build/test artifacts;
`.gotmp/` is now ignored.
## Treat container setup as a networked, privileged surface
Before building, inspect the context and pinning:
```bash
test -e .dockerignore || echo ".dockerignore is absent"
rg -n '^(FROM|[[:space:]]*image:)|@latest|:latest|setup_24.x' \
Dockerfile Dockerfile.archied docker-compose.yml
git status --short
```
No `.dockerignore` exists as of the snapshot. Both Dockerfiles run
`COPY . .`; `.gitignore` does not filter a Docker build context. Local ignored
configuration, `.git`, caches, dependency trees, worktrees, and scratch data
can therefore be sent to the builder. Stop and inspect the context before any
build from a non-clean checkout.
The images also contain floating inputs:
- both Go builder image tags omit a patch version or digest;
- Ubuntu base images omit digests;
- the agent image installs multiple Go tools with `@latest`;
- Node comes from the moving `setup_24.x` channel;
- global npm tools are unpinned;
- Compose consumes `archied:latest`, `archie-agent:latest`, and an untagged
watchtower image.
Do not label a rebuild reproducible. Treat pinning or build-context changes as
change-controlled work.
`task docker-build` needs registry/network access and a functioning Compose
engine. `task docker-up` additionally pulls images, binds ports 4222, 8222, and
8484, mounts host paths and the container socket, and consumes external
configuration and credentials. Load `archie-run-and-operate` before using it.
## Separate environment failures from code failures
| Signature | Classify and branch |
|---|---|
| `go: creating work dir: mkdir /work/tmp/...: read-only file system` | `go env GOTMPDIR` points at a read-only path. Set task-specific `GOTMPDIR` under writable storage and retry. |
| `open .../.cache/go-build/...: read-only file system` | Set a writable `GOCACHE`. |
| `open .../pkg/mod/cache/...tmp: read-only file system` | Set writable `GOMODCACHE` and `GOPATH`; expect network access if the new cache is cold. |
| `listen ...: socket: operation not permitted` | The sandbox denies local listeners. Re-run on a host that permits loopback sockets; do not delete the integration test. |
| `Unable to start NATS Server in Go Routine` after about 10 seconds | First test whether local listeners are permitted. Embedded-NATS tests share this environmental requirement. |
| `cannot auto-sign commit` | Ambient `commit.gpgSign=true` reached a go-git fixture. Current worktree code and fixtures explicitly set repository-local `gpgsign=false`; a recurrence may be a regression. |
| `EAI_AGAIN` for `registry.npmjs.org` | Dependency retrieval failed. Do not diagnose VitePress until installation succeeds. |
| `Failed to obtain podman configuration ... /run/user/.../libpod: read-only file system` | The Docker-compatible CLI cannot initialize its container backend in this sandbox. Move the container check to a suitable host. |
| `TestRunWrapsExternalCommand ... Run() = "\n"` | This is a focused, listener-independent code failure in `internal/skillscript`, not an environment failure. |
For hermetic test diagnosis only, suppress ambient global Git configuration:
```bash
env GIT_CONFIG_GLOBAL=/dev/null \
go test ./internal/worktree/... ./internal/worktreerpc/... -count=1
```
Do not apply `GIT_CONFIG_GLOBAL=/dev/null` to runtime or deployment commands
that intentionally need host credentials or URL rewrites.
## Use the complete validation matrix
Choose rows by changed surface, then let `archie-validation-and-qa` decide the
required acceptance set.
| Evidence | Command | Current snapshot |
|---|---|---|
| Focused Go behavior | `go test ./path/to/package/... -run '^TestName$' -count=1 -v` | Use first; distinguish a real failure from broad-suite noise. |
| Root unit/integration suite | `go test ./... -count=1` | Restricted sandbox also fails listener-dependent packages. A focused `internal/skillscript` test has a genuine failure. |
| Root race suite | `go test -race ./... -count=1` | Not run by `task check`; no current green claim. |
| Vet | `go vet ./...` | Passed on 2026-07-28. |
| Lint | `golangci-lint run ./...` | Failed with 54 findings on 2026-07-28; `task check` does not expose them. |
| Build | `go build -o /tmp/archie-core-archied ./cmd/archied` and the analogous `archie-agent` command | Both passed on 2026-07-28. |
| Tools tests | `go -C tools test ./... -count=1` | Passed on 2026-07-28. |
| Local generated contract parity | Temporary docsgen output plus `cmp --silent` | Passed for 10 schemas on 2026-07-28; the checkout output is untracked. |
| Docs install/build | `pnpm --dir docs-2 install --frozen-lockfile` then `pnpm --dir docs-2 build` | Blocked by restricted network; unknown, not failed. |
| Container build | `task docker-build` | Not verified in the restricted container environment. |
| Repository gate | `task check` | Currently non-green because the root suite reaches the genuine skillscript failure; it may also rewrite files first. |
Do not hide a baseline failure by reporting only a focused pass. Record the
exact command, environment restrictions, exit status, and first actionable
failure.
## Cold-start completion checklist
- [ ] Read `CLAUDE.md`, `ARCHITECTURE.md`, and `Taskfile.yml`.
- [ ] Verify installed commands and compare them with repo declarations.
- [ ] Confirm writable temp and cache paths without changing system variables.
- [ ] Distinguish cold-cache network needs from compilation failures.
- [ ] Build both Go commands.
- [ ] Run a focused test, vet, lint, and the root suite.
- [ ] Run the tools-module tests explicitly.
- [ ] Generate docs contracts to `/tmp` and compare the checkout output.
- [ ] Install and build docs only with authorized registry access.
- [ ] Inspect Docker context and floating inputs before any image build.
- [ ] Record sandbox listener/container restrictions.
- [ ] Hand acceptance decisions to `archie-validation-and-qa`.
## Provenance and maintenance
Ground this skill in `CLAUDE.md`, `Taskfile.yml`, `.golangci.yml`, `go.mod`,
`tools/go.mod`, `tools/docsgen/`, `docs-2/package.json`,
`docs-2/pnpm-lock.yaml`, `.github/workflows/docs.yml`, both Dockerfiles,
`docker-compose.yml`, `.gitea/workflows/deploy.yml`, `.gitignore`,
`internal/worktree/`, and the tests named above.
Re-verify module/toolchain declarations:
`sed -n '1,40p' go.mod; sed -n '1,40p' tools/go.mod; go version; task --version; gofumpt -version; golangci-lint version`
Re-verify Task coverage:
`sed -n '1,180p' Taskfile.yml; rg -n 'task: lint|go test.*race|go -C tools|docsgen|pnpm' Taskfile.yml`
Re-verify docs and CI:
`sed -n '1,120p' docs-2/package.json; sed -n '1,120p' .github/workflows/docs.yml; go -C tools test ./... -count=1`
Re-verify container inputs:
`test -e .dockerignore || echo ABSENT; rg -n '^(FROM|[[:space:]]*image:)|@latest|:latest' Dockerfile Dockerfile.archied docker-compose.yml .gitea/workflows/deploy.yml`
Re-verify artifact counts:
`git ls-files 'docs-2/node_modules/**' | wc -l; git ls-files '.gotmp/**' | wc -l`
Re-verify current failures:
`go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v; golangci-lint run ./...`
@@ -0,0 +1,4 @@
interface:
display_name: "Archie Build and Environment"
short_description: "Recreate and verify the Archie toolchain"
default_prompt: "Use $archie-build-and-env to recreate a clean Archie development environment and verify every build surface."
@@ -0,0 +1,411 @@
---
name: archie-change-control
description: "Classify, investigate, plan, gate, review, and accept archie-core changes without trading maintainability for a passing test. Use before changing or approving architecture, Go source, configuration, runtime lifecycle, dependencies, protocols, persistence, security boundaries, deployments, generated documentation, or read-only designs; also use when deciding whether scoped evidence is sufficient, whether an old path must be deprecated or deleted, or whether a change is ready to close."
---
# Archie change control
Protect Archie's quality, not merely its test result. Treat a passing test as
necessary evidence for code changes, never as proof that the design is coherent,
the old path is gone, or production selects the new path.
## Route to the right sibling
Use this skill to control a change from classification through acceptance.
Load these siblings for the specialized work:
| Need | Load |
|---|---|
| Design or revise boundaries, ownership, package structure, or a migration | `archie-architecture-planning-campaign` |
| Find duplication, hidden dead paths, poor names, misplaced responsibilities, or maintainability debt | `archie-technical-accountability` |
| Design tests, reproduce a defect, select QA evidence, or run complete gates | `archie-validation-and-qa` |
| Run, deploy, observe, recover, or roll back a live assembly | `archie-run-and-operate` |
Do **not** use this skill alone to:
- conduct an architecture campaign;
- perform a deep code-quality or AST investigation;
- invent a test strategy for a complex behaviour;
- operate production;
- replace the governing decision document for a domain.
## Use these terms consistently
| Term | Meaning here |
|---|---|
| Baseline | Recorded behaviour and gate output before the proposed change. |
| Current state | Behaviour selected by the checked-out live code, not a PRD target or branch-only fix. |
| Production wiring | The complete path by which a supported assembly selects, configures, runs, and observes an implementation. |
| Authoritative contract | The source whose semantics the producer and consumer are required to obey; a projection or shared test fake is not authoritative. |
| Compatibility adapter | Temporary code that preserves an older input or caller while migration proceeds, with explicit deletion criteria. |
| Last-known-good | The previously active version proved healthy and retained for restoration. |
| Evidence packet | Commands, outputs, traces, diffs, decisions, and reviews supporting acceptance. |
| Acceptance | Permission to close the controlled work; it is not permission to push, deploy, migrate, or delete. |
## Apply the non-negotiables
| Rule | Why it is mandatory | Repository evidence or incident |
|---|---|---|
| Investigate the live call path before planning. | A constructor, registry entry, config field, or test can exist without production ever selecting it. | Missing Compose passthroughs in `22fc0ef` and `d0624b7` left configured secrets absent at runtime. |
| Test the authoritative contract, not a convenient projection. | A best-effort or mirrored interface can pass while the real producer blocks or the peer rejects the exchange. | `6a0bd27`: consuming `TextStream` instead of draining authoritative `FullStream` deadlocked every streamed reply. `3ad57c9`: recreating a buffered reader dropped MCP messages; the harness also masked process-exit behaviour. |
| Preserve compatibility deliberately. Never rely on a decoder ignoring old input. | Silent omission turns a schema edit into an outage. | `1f8588d`: removing `[forge].token_env` compatibility caused both production containers to crash-loop because TOML ignored the old key. |
| Make deployment dependencies explicit and observable. | Hostname, network, secret, mount, and environment assumptions differ between tests and the running Compose assembly. | `37cf089` and `2ac306b`: failed Docker-network auto-detection put workers on the default bridge, so NATS returned “no responders.” |
| Inspect every mechanical or generated edit semantically. Never accept a broad cleanup by count alone. | Formatting, autofix, rebasing, and three-way application can alter behaviour or erase concurrent work. | `9b44bac`: `golangci-lint --fix` introduced a bad `:=` that would have defeated a timeout if it compiled. `affc717`: worktree diffs were based on an older tree and required explicit survival checks. `308c199`: a broad cleanup changed the skillscript command so its test now emits only a newline. |
| Enforce lifecycle transitions and audit atomically. | Ignoring expected state permits lost updates; splitting state and history permits contradictory evidence. | As of 2026-07-28, `internal/store.Store.Transition` ignores `from` and performs two writes. Fix `a7f294e` exists only on `origin/fix/48-transition-ignores-from-status-guard-allowing-lost-updates`, not on `main`; the Nell adapter also does not record equivalent transition history. |
| Keep deterministic constraints outside the proposing model. | A prompt can be ignored to make a test pass. | `CLAUDE.md` requires gates, protected tests, and diff limits to be code-enforced; the model never owns git operations. |
| Require a fresh adversarial reviewer after green. | The implementer is biased toward the path it just made pass. | `CLAUDE.md` makes a memory-independent review mandatory and blocks completion on surviving findings. |
## Classify the change
Classify every affected surface. For a composite change, apply the union of all
required controls and use the highest-risk class.
| Class | Examples | Minimum control |
|---|---|---|
| Read-only investigation | Review, diagnosis, inventory, impact map | Do not mutate. Cite live code, tests, history, and unresolved uncertainty. |
| Design or documentation | PRD, ADR-like decision, architecture guide, skill | Separate current facts from approved target and open candidates. Validate links/format. Do not imply implementation. |
| Source | Go behaviour, refactor, API, workflow | Current-state map, red-green, scoped iteration, architecture and maintainability review, final relevant gates. |
| Configuration | Decoder, default, env name, overlay, secret reference, setting owner | Old/new input fixtures, precedence/default proof, production composition trace, invalid-input behaviour, explicit rollback. |
| Runtime lifecycle | Start, stop, reload, concurrency, stream, retry, health | Cancellation/backpressure/failure tests, race test, bounded retry, shutdown and rollback proof. |
| Dependency | Root or `tools` module dependency/version | Adoption rationale, API/behaviour delta, both module manifests as applicable, transitive/security review, reverse plan. |
| Protocol | MCP, NATS, RPC, subprocess, JSON/wire schema | Version and compatibility matrix, independent-peer or recorded-wire evidence, malformed/partial/multi-message tests. |
| Persistence | SQLite, NellDB, schema, lifecycle state, migrations | Old-data fixture, legal-transition and concurrency tests, atomic state/audit proof, backup/rollback strategy. |
| Security or trust boundary | Secret flow, plugins, tools, containers, identity, authorization | Threat/authority analysis, deny tests, deterministic enforcement, fresh security review, no “subprocess equals sandbox” claims. |
| Deployment | Dockerfile, Compose, image/tag, env passthrough, volume/network | Exact assembly validation, secret-name-to-container trace, health observation, previous image/config recovery plan. |
| Generated documentation | `tools/docsgen`, registries, generated JSON, VitePress | Generator tests, byte-for-byte drift check, site build, generated-vs-handwritten ownership check. |
Escalate the risk class when the change crosses a process boundary, changes
stored or wire data, changes operator-visible defaults, alters authorization,
removes compatibility, or can affect a live deployment.
## Execute the control loop
### 1. Establish authority and scope
For implementation work, start from the existing Beads issue and claim it.
Create durable work before writing code if no issue exists. Do not create a
Markdown task list.
```bash
bd prime
: "${BEADS_ISSUE_ID:?set BEADS_ISSUE_ID to the target issue}"
bd show "$BEADS_ISSUE_ID"
bd update "$BEADS_ISSUE_ID" --claim
```
For a review or investigation, remain read-only unless the user separately
authorizes implementation.
Record:
- the requested outcome and explicit non-goals;
- every selected change class;
- files and domains believed to be in scope;
- user authority for source, config, deployment, dependency, and destructive
operations;
- whether another session owns overlapping files.
### 2. Protect concurrent work
Inspect before editing:
```sh
git status --short
git diff --stat
git worktree list --porcelain
```
Treat every pre-existing change as somebody else's. Stop before overlapping it
unless ownership and integration order are known. Never discard, reset, or
silently reformat unrelated changes.
Partition parallel work by non-overlapping file ownership. Before applying an
agent result based on another tree, compare its base and verify that every
intervening semantic fix survives. The `affc717` history demonstrates why a
cleanly applied diff is not proof of preservation.
Do not run broad autofix against a shared dirty tree. `task check` and
`task fmt` are broad mutators; isolate them and inspect their complete diff.
### 3. Map the current state before proposing a change
Read `CLAUDE.md`, `ARCHITECTURE.md`, `docs/prds/01-project-management.md`, and
the focused decision document linked from the architecture index.
For the selected behaviour, trace all of:
- entry points under `cmd/` and application composition;
- constructors, registries, interfaces, adapters, and concrete selection;
- every caller and consumer, including RPC/process peers;
- settings, defaults, overlays, secrets, and deployment passthrough;
- state ownership, persistence, lifecycle, cancellation, and recovery;
- tests and what they do **not** exercise;
- duplicated implementations, compatibility adapters, generated copies, and
apparently dead paths;
- git history for rejected, stalled, reverted, or branch-only work;
- documents that disagree with live code.
Use read-only evidence:
```bash
# Guard: verify repository root first
git rev-parse --show-toplevel >/dev/null || { echo 'run from repo root' >&2; exit 1; }
: "${ARCHIE_SYMBOL:?set ARCHIE_SYMBOL to the symbol or config key}"
rg -n "$ARCHIE_SYMBOL" cmd internal config*.toml docker-compose.yml docs
: "${ARCHIE_PACKAGE:?set ARCHIE_PACKAGE to the package path relative to repo root}"
go list -deps "./internal/$ARCHIE_PACKAGE/..."
: "${ARCHIE_PATHS:?set ARCHIE_PATHS to the space-separated affected paths}"
git log --all --oneline -- $ARCHIE_PATHS
git blame -- $ARCHIE_PATHS
```
Do not ask the user for a fact the repository can reveal. Ask only when a real
product, compatibility, ownership, or risk decision remains.
### 4. Write the change brief
Do not begin implementation until the brief answers:
| Question | Required answer |
|---|---|
| What owns this behaviour? | One cohesive domain/capability and the governing decision document. |
| Where does production select it? | Exact entry point-to-implementation path. “Registered” is insufficient. |
| What changes and what stays stable? | Behavioural contract, invariants, non-goals, and affected consumers. |
| What does this supersede? | Every older or parallel path, with keep/merge/deprecate/delete decision. |
| What gets deleted? | Obsolete code, compatibility adapters, duplicated config, tests, and docs, or a justified reason to retain each. |
| What proves failure first? | A behavioural red test that fails for the intended reason, not a compile error. |
| What proves maintainability? | Ownership, dependency direction, naming, size, duplication, and dead-path checks. |
| What is the compatibility plan? | Old/new config, protocol, data, caller, and rollout combinations. |
| How is it reversed? | Last-known-good state and evidence that reversal preserves data and service. |
| What remains uncertain? | Explicit open/candidate claims; never convert a hunch into a requirement. |
If adding a feature makes an existing path redundant, deletion is part of the
feature unless compatibility has a named owner, deadline or deletion
criterion, and test. Do not leave two active paths merely because deleting the
old one is harder.
Route boundary or ownership uncertainty through
`archie-architecture-planning-campaign` before coding. Route unlocatable impact,
duplication, or dead-path uncertainty through `archie-technical-accountability`.
### 5. Capture a baseline
Run the narrowest non-mutating checks that exercise the affected area before
the red test. Preserve exact command, exit status, and output.
Example for one Go package:
```sh
go test ./internal/gateway/... -count=1
go vet ./internal/gateway/...
golangci-lint run ./internal/gateway/...
gofumpt -l internal/gateway
```
Distinguish:
- **clean baseline**: proceed;
- **unrelated known failure**: preserve its exact signature and escalate;
- **failure in the affected surface**: do not build on it; repair or split the
work with explicit authority;
- **environment failure**: prove it is environmental before classifying it as
non-code.
Do not call a baseline green when a command was skipped.
### 6. Apply red-green without surrendering design
1. Add a behavioural test for the intended contract.
2. Run it and capture a meaningful failure.
3. Implement the smallest coherent design, not the smallest patch.
4. Run the focused test until green.
5. Add every relevant error, boundary, compatibility, cancellation, and
concurrency case.
6. Re-read every changed non-test file for ownership, clarity, duplication,
unused branches, and superseded paths.
Load `archie-validation-and-qa` for the test design. Load
`archie-technical-accountability` before accepting “works but ugly” code.
Never weaken or rewrite the red test merely to admit the implementation.
Environmental test protection is preferable to a prompt-only prohibition.
### 7. Prove production wiring
Demonstrate all applicable links:
```text
external input
-> decoder/adapter
-> application composition
-> selected implementation
-> state or external effect
-> observable outcome
```
Test at the highest practical seam. A package unit test does not prove that
`cmd/archied` supplies the new setting, registers the implementation, forwards
the environment variable, chooses the right mode, or exposes the result.
For configuration, test the deployed legacy form and the new form. Verify both
the source environment and `docker-compose.yml` passthrough. For protocols,
verify bytes/messages with an independently implemented peer or fixture rather
than a client and server sharing the same wrong assumption.
### 8. Make rollback executable
Identify last-known-good **before** changing runtime state. Define the trigger,
owner, commands or deterministic mechanism, data consequences, and health check
for restoration.
| Change | Required rollback evidence |
|---|---|
| Source or dependency | Exact prior version plus proof that reverting does not leave incompatible data, config, or generated output. |
| Configuration | Prior accepted input and effective values, secret-safe diff, reload/restart consequence, and health check. |
| Protocol | Old/new peer matrix; retain the old path until mixed-version operation or coordinated cutover is proved. |
| Persistence | Backup/restore or reversible migration rehearsal against an old-data fixture; never call a destructive forward-only migration rollback-safe. |
| Deployment | Previous image digest and config, exact supported assembly, restoration command, and post-restore observation. |
| Generated documentation | Regenerate from authoritative definitions; never recover by hand-editing generated JSON. |
The candidate-promotion and automatic last-known-good protocol in
`docs/prds/architecture/safe-change-and-recovery.md` is an approved requirement,
but its exact Go contracts and atomicity boundary are explicitly still under
design as of 2026-07-28. Do not claim Archie currently provides it. For live
work, route the concrete manual or implemented recovery procedure through
`archie-run-and-operate`.
### 9. Run the required evidence set
Use scoped checks while iterating. Use a scoped final gate only for a genuinely
isolated single-package change allowed by `CLAUDE.md`. Require full and
class-specific checks for cross-package, configuration, runtime, dependency,
protocol, persistence, security, deployment, or generated-documentation work.
`task check` is repository doctrine but is not the complete evidence set:
```sh
task check
golangci-lint run ./...
go test -race ./... -count=1
go -C tools test ./... -count=1
go -C tools vet ./...
```
For generated contracts and the site, run the current commands:
```sh
go -C tools test ./docsgen -count=1
go -C tools run ./docsgen --repo-root .. --out /tmp/archie-contracts.check.json
cmp /tmp/archie-contracts.check.json docs-2/data/generated/contracts.json
pnpm --dir docs-2 build
```
Inspect the diff after any formatter, fixer, generator, or `task check`. A zero
exit status does not authorize unrelated edits.
### 10. Run fresh adversarial review
Give a reviewer with no implementation memory the requirement, governing
architecture, current diff, and raw validation output. Require findings first;
do not let that pass silently fix its own findings.
Require review of:
- production selection and every affected consumer;
- correctness and error propagation;
- architecture ownership and dependency direction;
- obsolete, duplicate, disconnected, or single-use paths;
- config/default/identity hardcoding;
- interface satisfaction and wire compatibility;
- nil, cancellation, goroutine, race, transaction, and rollback hazards;
- whether tests prove the contract rather than mirror the implementation.
Resolve every blocking and important finding, rerun affected checks, then use a
fresh final pass if semantics changed. Surviving findings block acceptance.
### 11. Accept or stop
Accept only when the evidence packet contains:
- issue/scope and all change classes;
- current-state impact map and governing decisions;
- baseline, red, green, and final command outputs;
- production-wiring proof;
- compatibility, deprecation, deletion, and rollback decisions;
- architecture and maintainability review;
- fresh adversarial review with zero surviving blocking or important findings;
- explicit uncertainties and follow-up ownership;
- no unexplained diff.
Do not close a Beads issue until its acceptance criteria and the session close
protocol are satisfied. Do not push, deploy, migrate, or delete data without
separate authority.
## Know the current gate gaps
**Volatile snapshot: 2026-07-28. Re-verify before every acceptance decision.**
- `task check` runs `task fmt`, which executes `gofumpt -w .` and
`go fix ./...`; it then executes `go fix ./...` a second time before vet,
build, and root tests. It mutates source.
- `task check` does not run `task lint`, race tests, the nested `tools` module,
docsgen drift checks, or the VitePress build.
- Root `go test ./...` does not cross the nested `tools/go.mod` boundary.
- `.gitea/workflows/deploy.yml` builds and pushes images without a Go quality
job. `.github/workflows/docs.yml` installs and builds VitePress but does not
run the Go gate or docsgen.
- `go test ./internal/skillscript -count=1` currently fails
`TestRunWrapsExternalCommand`: `Run() = "\n"`.
- The approved generated-documentation document describes future
`task docs:*` and `docsgen check` commands, but neither exists in the current
`Taskfile.yml`/CLI. Use the current commands above.
- No `task deadcode` target exists. Never report it as executed.
Repository doctrine still requires a clean relevant gate. A known baseline
failure is not permission to report completion. Either repair it under
separately controlled scope or report the work blocked with scoped no-regression
evidence.
## Escalate instead of improvising
Stop and obtain a decision when:
- a requested feature conflicts with an approved architecture decision;
- ownership or the production selection path remains ambiguous after research;
- a new path overlaps an existing feature and no deprecation/deletion decision
exists;
- compatibility requires supporting two behaviours with no sunset criterion;
- a migration can lose data or cannot demonstrate restoration;
- a runtime/config change cannot preserve last-known-good state;
- a protocol change lacks an independent interoperability oracle;
- a security rule exists only in a prompt;
- a baseline failure touches the same surface;
- concurrent work overlaps the files or semantics;
- the required full gate cannot run or has an unexplained failure;
- an adversarial finding survives.
Do not escalate discoverable facts or ordinary implementation choices. Bring
the evidence, the smallest decision required, and the consequences of each
option.
## Provenance and maintenance
Re-verify commands, gates, current defects, and incidents before updating this
skill:
```sh
sed -n '1,220p' Taskfile.yml
sed -n '1,260p' CLAUDE.md
find .gitea/workflows .github/workflows -maxdepth 1 -type f -print
sed -n '1,140p' .gitea/workflows/deploy.yml
sed -n '1,180p' .github/workflows/docs.yml
sed -n '1,130p' docs/prds/architecture/safe-change-and-recovery.md
sed -n '1,120p' docs/prds/architecture/package-review.md
sed -n '300,350p' docs/prds/architecture/agent-system.md
sed -n '255,280p' internal/store/store.go
sed -n '270,305p' internal/nell/adapter.go
go test ./internal/skillscript -count=1
git log --all --format='%h %ad %s' --date=short --grep='FullStream\|MCP transport framing\|token_env\|container Docker network\|autofix\|Transition() ignores' -i
git branch -a --contains a7f294e
rg -n 'docs:|deadcode' Taskfile.yml
```
@@ -0,0 +1,4 @@
interface:
display_name: "Archie Change Control"
short_description: "Plan, gate, and accept Archie changes safely"
default_prompt: "Use $archie-change-control to classify, plan, verify, review, and accept this archie-core change."
@@ -0,0 +1,432 @@
---
name: archie-codebase-discovery
description: "Trace Archie behavior and blast radius through Go source, types, state, persistence, transports, consumers, tests, configuration, production composition, and target architecture. Load before changing or planning a non-trivial feature, refactor, config field, interface, persistence path, workflow, channel, plugin, or agent execution path; also load to investigate duplicate behavior, hidden dead code, constructor bypasses, package dependencies, decoded-but-unwired configuration, or uncertainty about what a symbol actually affects."
---
# Discover the Archie codebase
Use evidence from the current checkout to explain a behavior before changing it.
Produce a trace that another engineer can reproduce. Do not stop at "tests pass"
or "grep found one call."
Volatile tool facts below were verified on **2026-07-28**. Re-check them before
depending on exact versions or subcommands.
## Scope and routing
This skill is read-only. Use it to establish what exists, who owns state, which
paths are live, and what a proposed change would displace.
Do **not** use it as:
| Need | Load instead |
|---|---|
| Assign ownership, justify deletion, or record cleanup debt | `archie-technical-accountability` |
| Design boundaries, packages, migrations, or a future architecture | `archie-architecture-planning-campaign` |
| Collect runtime, coverage, complexity, latency, or production measurements | `archie-diagnostics-and-tooling` |
| Turn a hypothesis into a controlled evidence campaign | `archie-research-methodology` |
| Learn NellDB's API, document model, MVCC, HLC, or persistence semantics | `archie-nelldb` |
| Implement or approve a behavior-changing patch | Route the resulting trace through `archie-change-control` |
Do not delete, move, or redesign code while running this skill. A discovery can
recommend a next investigation, but an ownership or architecture decision needs
the sibling skill named above.
## Define the evidence terms
- **Composition root:** executable code that selects concrete implementations
and connects them. Archie's principal composition root is
`cmd/archied/main.go`; the sandbox worker has its own root under
`cmd/archie-agent/`.
- **Production wiring:** a path selected by a shipped entrypoint under an actual
config/mode branch. A constructor, decoder, or passing unit test is not wiring.
- **State owner:** the component with authority to validate and persist a state
transition, not every component that holds a copy.
- **Target PRD:** an approved description under `docs/prds/` of where the system
should go. It is not proof that current code works that way.
- **Candidate:** a result from text or syntax search that still requires
type-aware or composition-root confirmation.
## Establish a reproducible baseline
Run from the repository root:
```sh
go version
go env GOMOD GOWORK GOOS GOARCH
gopls version
golangci-lint version
staticcheck -version
rg --version | sed -n '1p'
```
Record missing tools instead of silently substituting a weaker claim. As of
2026-07-28 this checkout had Go 1.26.5, gopls 0.23.0,
golangci-lint 2.12.2, staticcheck 2026.1 (v0.7.0), and `rg`. `go tool` listed
no `callgraph` command. Do not write `go tool callgraph`; use
`gopls call_hierarchy`.
Use writable caches when the host's default Go caches are read-only:
```sh
export GOCACHE="${TMPDIR:-/tmp}/archie-discovery-gocache"
export XDG_CACHE_HOME="${TMPDIR:-/tmp}/archie-discovery-xdg"
export GOLANGCI_LINT_CACHE="${TMPDIR:-/tmp}/archie-discovery-lint"
export GOTMPDIR="${TMPDIR:-/tmp}"
export GOPROXY=off
export GOFLAGS=-mod=readonly
```
`GOPROXY=off` prevents discovery from fetching dependencies. If an uncached
module is required, report that as an environment blocker; do not turn a
read-only investigation into dependency mutation.
Inventory module boundaries before interpreting `./...`:
```sh
find . \( -path './.git' -o -path './.references' -o -path './.claude/worktrees' -o -name node_modules \) -prune -o -name go.mod -print
go list -m -f '{{.Path}} {{.GoVersion}}'
go -C tools list -m -f '{{.Path}} {{.GoVersion}}'
```
The root module and `tools/` are separate modules as of 2026-07-28. A root
`go test ./...` or `go list ./...` does not validate `tools/`.
## Build the behavior trace
Write the question first:
```text
Behavior:
Observable input:
Expected externally visible output:
State that may change:
Modes/configurations to compare:
```
Then traverse every row in order. Mark a row `N/A` only with evidence.
| Step | Find | Required evidence |
|---:|---|---|
| 1 | Entrypoint | `main`, handler, poller, RPC subject, or tool registration that admits the input |
| 2 | Construction | Constructor and every direct struct literal that can create the component |
| 3 | Contract | Interface, wire type, command, event, or public method actually crossed |
| 4 | Implementation | All type-valid implementations, then the one selected in each relevant mode |
| 5 | State owner | The function that validates the transition and owns concurrency/transaction rules |
| 6 | Persistence | Store adapter, schema/key/document, serialization, and reload/recovery path |
| 7 | Event/transport | Publish/send and subscribe/receive sides, subject/framing, timeout, retry, and acknowledgement |
| 8 | Consumer | Callers and downstream readers, including UI, channel, daemon, agent, and reconciliation paths |
| 9 | Tests | Unit, integration, contract, architecture, and production-composition tests; identify absent layers |
| 10 | Configuration | Decode, default, validation, normalization/copy, composition-root consumption, and deploy passthrough |
| 11 | Target architecture | Current-to-target mapping in `docs/prds/`; label gaps instead of describing target text as current |
Start at these verified anchors:
| Concern | Current anchor |
|---|---|
| Resident daemon | `cmd/archied/main.go` → `run()` → `daemon.Daemon` |
| Sandboxed worker | `cmd/archie-agent/main.go`, `cmd/archie-agent/taskrun.go` |
| Task orchestration | `internal/daemon/daemon.go`, `internal/workflow/` |
| Task contracts and SQLite | `internal/store/interface.go`, `internal/store/` |
| Production task persistence | `internal/nell/adapter.go`; selected by `nell.OpenStore` in `cmd/archied/main.go` |
| RPC split | `internal/{nats,taskrun,natsrpc,storerpc,forgerpc,worktreerpc}/` |
| Chat and channels | `internal/gateway/`, `internal/channels/` |
| Configuration | `internal/config/`, `config.example.toml`, `config.docker.toml` |
| Production/deploy shape | `cmd/archied/main.go`, `docker-compose.yml`, `.gitea/workflows/deploy.yml` |
| Target map | `docs/prds/01-project-management.md` and linked `docs/prds/architecture/*.md` |
Do not assume this table is complete after code moves. Re-find anchors with
`go list` and `gopls`.
## Use syntax, type, and call evidence
### Map packages before reading files
List source and test files as the Go tool sees them:
```sh
go list -f '{{.ImportPath}}|go={{join .GoFiles ","}}|tests={{join .TestGoFiles ","}}|imports={{join .Imports ","}}' ./internal/store
go list -json ./internal/store
```
Map internal dependency direction:
```sh
.claude/skills/archie-codebase-discovery/scripts/package-edges.sh ./internal/...
```
Treat imports as dependency evidence, not ownership proof. Compare the result
with `docs/prds/architecture/dependencies-and-contracts.md` only after
distinguishing current from target.
### Resolve symbols with gopls
Use a 1-indexed `file:line:column` position on the identifier:
```sh
gopls symbols internal/store/interface.go
gopls definition cmd/archied/main.go:154:18
gopls references -d internal/store/interface.go:25:2
gopls implementation internal/store/interface.go:16:6
gopls call_hierarchy internal/store/interface.go:25:2
```
Run all four queries together:
```sh
.claude/skills/archie-codebase-discovery/scripts/trace-go-position.sh internal/store/interface.go:25:2
```
Use `gopls implementation` on interfaces and interface methods. Use
`gopls references -d` on struct fields, functions, constants, and types.
`gopls call_hierarchy` exposes callers missed by a search for one textual call
shape. Read the resolved bodies; tool output is an index, not the explanation.
Inspect exported contracts and available tests:
```sh
go doc ./internal/store.TaskStore
go test ./internal/store -list '.'
rg -n '^func Test|^func Benchmark|^func Fuzz' internal/store
```
`go test -list` compiles the package and lists matching top-level tests; it does
not execute them.
### Generate AST candidates for construction
Find type declarations, direct composite literals, and functions returning a
named type:
```sh
.claude/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh Daemon .
.claude/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh -tests Task .
```
The helper parses Go ASTs; it does not infer the package identity of an
unqualified name. Treat results as candidates, then confirm each with
`gopls definition` or `gopls references`. Production-only output is the default;
pass `-tests` to expose test-only construction.
## Run focused discovery recipes
### Find duplicate behavior paths
1. Run the configured duplicate-code detector:
```sh
golangci-lint run --enable-only=dupl ./internal/...
```
2. Search for the externally visible operation, status, subject, or log phrase:
```sh
rg -n 'Transition\(|PublishTask\(|ClaimNext\(|StatusWaitingHuman' cmd internal
```
3. Trace each candidate back to an entrypoint and forward to its state owner.
4. Compare mode branches: in-process, subprocess, NATS/container,
single-identity, and multi-identity where applicable.
5. Report semantic duplicates even when the code is textually different.
6. Do not call compatibility paths obsolete until production composition,
deployed config, persistence compatibility, and target removal criteria agree.
`dupl` finds similar syntax, not two different implementations of one
responsibility.
### Find unused-but-compiled code
Run the available unexported-code check:
```sh
staticcheck -checks=U1000 ./internal/...
```
For every suspect:
1. Run `gopls references -d` on the declaration.
2. Search registration tables, `init`, reflection/Yaegi symbols, templates,
JSON/TOML/YAML tags, RPC subjects, plugin manifests, and string dispatch.
3. Check build tags and OS-specific files from `go list -json`.
4. Search both executable composition roots.
5. Separate production, test-only, compatibility, generated, and unreachable
paths.
`U1000` does not prove exported code, reflection targets, wire names, or
registrations are dead. Zero type references does not prove a string-addressed
capability is dead. Route any deletion decision to
`archie-technical-accountability`.
### Find interface implementations
1. Put the cursor position on the interface name and run
`gopls implementation`.
2. Put it on each important method and run `gopls implementation` again.
3. Find compile-time assertions:
```sh
rg -n 'var _ .*=' --glob '*.go' cmd internal
```
4. Trace which implementation the composition root selects for each mode.
5. Inspect test doubles separately; they establish substitutability only for
exercised behavior.
An interface with three valid implementers still has only the implementation
selected by `cmd/archied` on a given production branch.
### Find struct-field consumers
1. Run `gopls references -d` on the **field declaration**, not its common name.
2. Trace assignments into the field and reads out of it separately.
3. Follow copies and normalization methods such as `ForTask`/`ToConfig`.
4. Check JSON/TOML/YAML tags and reflection separately; gopls cannot turn a
decoder's string key into a field reference.
5. Compare production and `_test.go` references.
A field read only while constructing an unused object is not an effective
consumer.
### Detect constructor bypasses
1. Run `scan-go-type-syntax.sh Type .` without tests.
2. Inspect every `literal` outside the owning package.
3. Compare required validation/defaulting in constructors with direct literals.
4. Repeat with `-tests`; record tests that exercise impossible production
states.
5. Use `gopls references` on the constructor and type to catch aliases and
indirect uses the syntax helper cannot resolve.
Do not prohibit literals mechanically. Composition roots and test fixtures may
need them, but bypassed invariants must be explicit.
### Prove package dependency direction
1. Run `package-edges.sh` for the smallest package pattern.
2. Run `go list -deps -json <pattern>` when standard-library and third-party
edges matter.
3. Identify cycles prevented by interfaces, adapters, or RPC packages.
4. Compare current edges with the target dependency rules.
5. Treat a new shared package as an architecture decision, not a quick cycle fix.
### Find decoded-but-unused configuration
For each field, prove this chain:
```text
file/key → decoder → default → validation → normalization/copy
→ composition-root read → concrete component → observable behavior
```
Use:
```sh
rg -n 'toml:"|yaml:"|json:"' internal/config
rg -n 'LoadOverlay|LoadDir|finalize|ForTask|ToConfig' internal/config cmd
```
Then run `gopls references -d` on the exact field. Check
`config.example.toml`, `config.docker.toml`, `docker-compose.yml`, config tests,
and `cmd/archied/main.go`.
As of 2026-07-28 `cmd/archied` calls `config.LoadOverlay`; the separate
`config.LoadDir` feature-file loader exists and has tests but was not selected
by that production entrypoint. Re-verify this before using the fact. Decoder
coverage proves accepted syntax, not deployed behavior.
### Prove production composition
1. Start at `cmd/archied/main.go:run`, not at the package under investigation.
2. Record the config condition for each branch.
3. Follow concrete construction into `daemon.Daemon` and gateway start
functions.
4. For container/NATS behavior, also trace `cmd/archie-agent`.
5. Trace both sides of every RPC/transport and its error/timeout path.
6. Read contract/architecture tests, including files matching
`*contract_test.go` and `*architecture_test.go`.
7. Confirm deploy inputs in Compose and CI; do not infer remote runtime state
from repository files.
### Trace NellDB without guessing
Treat `internal/store` as the application contract and `internal/nell` as one
adapter. Do not transfer SQLite behavior to NellDB by analogy.
```sh
go doc github.com/samcharles93/NellDB.Store
go doc github.com/samcharles93/NellDB/sdk.DocDB
gopls implementation internal/store/interface.go:16:6
rg -n 'sdk\.New|\.Get\(|\.Put\(|AllDocs|taskKey|docToTask|taskFields' internal/nell
```
Trace `store.Task` field → `sdk.Doc` key → read/conversion → locking or MVCC
around update/transition → reopen/recovery test. The adapter currently uses
`tasks` and `events` collections and performs scans for several queries; verify
those facts in `internal/nell/adapter.go` before relying on them. As of
2026-07-28, `Adapter.Transition` neither locks nor checks its `from` argument;
record that as observed current behavior, not a target promise. NellDB's
`_id`/`_rev`, HLC, and conflict semantics come from the dependency API, while
Archie's legal task transitions remain an Archie concern. Route deeper domain
and persistence background to `archie-nelldb`.
## Reject false confidence
| Weak evidence | Why it fails | Required correction |
|---|---|---|
| One `rg` result | Misses interface dispatch, aliases, generated registration, reflection, and string-addressed protocols | Use gopls, AST candidates, package edges, and composition |
| Green unit test | May construct a component directly and bypass actual config, lifecycle, or transport | Add or inspect composition/contract/integration evidence |
| Fake client and fake server agree | Both sides can mirror the same wrong framing, subject, or state assumption | Compare an independent spec/implementation or real boundary fixture |
| High coverage | Does not establish ownership, maintainability, deprecation, or correct mode selection | Trace authority and current production selection |
| Constructor exists | Does not prove callers use it | Find struct literals and type-aware references |
| Config field decodes | Does not prove the executable reads it | Complete the config-to-observable chain |
| Target PRD says it | Describes required destination, not necessarily current code | Cite current implementation and label the gap |
## Produce the discovery handoff
End with these sections:
1. **Behavior trace:** one row per traversal step with `path:line`, symbol, and
current responsibility.
2. **Mode matrix:** mode/config branch → concrete implementation → state store
→ transport → consumer.
3. **State and authority:** owner, copies, persistence, transition rules, and
recovery.
4. **Blast radius:** callers, consumers, tests, config, deploy wiring, docs, and
compatibility paths.
5. **Duplication/deprecation ledger:** each candidate, evidence it is live or
dead, replacement, and objective removal gate.
6. **Current-to-target gap:** current fact, target PRD, migration implication;
never blend the two.
7. **Unknowns:** exact command attempted, output/blocker, and next evidence
needed.
Do not propose implementation until the trace can answer:
- What entrypoint selects this path?
- Which component owns the state and invariant?
- Which parallel or older path would the feature replace or deprecate?
- Which production modes and persisted data must remain compatible?
- Which evidence would falsify the current understanding?
Short successes are acceptable, but complete one vertical trace rather than
collecting many shallow search hits.
## Provenance and maintenance
Repository evidence verified on 2026-07-28:
`cmd/archied/main.go`, `cmd/archie-agent/`, `internal/{config,daemon,nell,store,workflow,tools/mcp}/`,
`Taskfile.yml`, `.golangci.yml`, `go.mod`, `tools/go.mod`,
`docker-compose.yml`, `.gitea/workflows/deploy.yml`, `CLAUDE.md`,
`ARCHITECTURE.md`, and `docs/prds/`.
Re-verify tools: `go version && gopls version && golangci-lint version && staticcheck -version && go tool`
Re-verify entrypoints: `rg -n '^func main|^func run' cmd/archied cmd/archie-agent`
Re-verify config selection: `rg -n 'config\.(Load|LoadOverlay|LoadDir)\(' cmd internal --glob '*.go'`
Re-verify modules: `find . \( -path './.git' -o -path './.references' -o -path './.claude/worktrees' -o -name node_modules \) -prune -o -name go.mod -print`
Re-verify production construction: `rg -n '&daemon\.Daemon\{|nell\.OpenStore|registerTaskRPCServers|startGateways' cmd/archied/main.go`
Re-verify contract tests: `find internal -type f \( -name '*contract_test.go' -o -name '*architecture_test.go' \) -print | sort`
@@ -0,0 +1,4 @@
interface:
display_name: "Archie Codebase Discovery"
short_description: "Trace Archie behavior from entrypoint to production"
default_prompt: "Use $archie-codebase-discovery to trace this behavior through production wiring before proposing a change."
@@ -0,0 +1,36 @@
#!/bin/sh
set -eu
if [ "$#" -gt 1 ]; then
printf '%s\n' "usage: $0 [go-package-pattern]" >&2
exit 2
fi
command -v go >/dev/null 2>&1 || {
printf '%s\n' "error: go is required" >&2
exit 127
}
pattern=${1:-./...}
cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"}
mkdir -p "$cache_root/go-build" "$cache_root/tmp"
export GOCACHE="$cache_root/go-build"
export GOTMPDIR="$cache_root/tmp"
export GOPROXY=off
export GOFLAGS=-mod=readonly
module_path=$(go list -m -f '{{.Path}}')
go list -f '{{.ImportPath}}{{range .Imports}}{{printf "\t%s" .}}{{end}}' "$pattern" |
awk -F ' ' -v module="$module_path" '
{
from = $1
for (i = 2; i <= NF; i++) {
if ($i == module || index($i, module "/") == 1) {
printf "%s -> %s\n", from, $i
}
}
}
' |
LC_ALL=C sort -u
@@ -0,0 +1,176 @@
// Command scan-go-type-syntax reports syntax-level construction candidates for
// a named Go type. It deliberately uses only the standard library and never
// writes to the inspected tree.
package main
import (
"bufio"
"flag"
"fmt"
"go/ast"
"go/parser"
"go/token"
"io/fs"
"os"
"path/filepath"
"sort"
"strings"
)
type finding struct {
path string
line int
column int
kind string
detail string
}
func main() {
includeTests := flag.Bool("tests", false, "include *_test.go files")
flag.Usage = func() {
fmt.Fprintf(flag.CommandLine.Output(), "usage: %s [-tests] TypeName [root]\n", os.Args[0])
flag.PrintDefaults()
}
flag.Parse()
if flag.NArg() < 1 || flag.NArg() > 2 {
flag.Usage()
os.Exit(2)
}
typeName := flag.Arg(0)
root := "."
if flag.NArg() == 2 {
root = flag.Arg(1)
}
if !token.IsIdentifier(typeName) {
fmt.Fprintf(os.Stderr, "error: %q is not a Go identifier\n", typeName)
os.Exit(2)
}
results, err := scan(root, typeName, *includeTests)
if err != nil {
fmt.Fprintf(os.Stderr, "error: %v\n", err)
os.Exit(1)
}
out := bufio.NewWriter(os.Stdout)
defer out.Flush()
fmt.Fprintln(out, "kind\tlocation\tdetail")
for _, result := range results {
fmt.Fprintf(out, "%s\t%s:%d:%d\t%s\n",
result.kind, result.path, result.line, result.column, result.detail)
}
}
func scan(root, typeName string, includeTests bool) ([]finding, error) {
fset := token.NewFileSet()
var results []finding
err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
if entry.IsDir() {
if path == root {
return nil
}
name := entry.Name()
if strings.HasPrefix(name, ".") || name == "node_modules" ||
name == "vendor" || name == "bin" {
return filepath.SkipDir
}
return nil
}
if filepath.Ext(path) != ".go" {
return nil
}
if !includeTests && strings.HasSuffix(path, "_test.go") {
return nil
}
file, err := parser.ParseFile(fset, path, nil, 0)
if err != nil {
return fmt.Errorf("parse %s: %w", path, err)
}
ast.Inspect(file, func(node ast.Node) bool {
switch node := node.(type) {
case *ast.TypeSpec:
if node.Name.Name == typeName {
results = appendFinding(results, fset, node.Name.Pos(),
path, "declaration", "type "+node.Name.Name)
}
case *ast.CompositeLit:
if matchesType(node.Type, typeName) {
results = appendFinding(results, fset, node.Type.Pos(),
path, "literal", "direct composite literal of "+typeName)
}
case *ast.FuncDecl:
if returnsType(node.Type.Results, typeName) {
results = appendFinding(results, fset, node.Name.Pos(),
path, "returns-type", "func "+node.Name.Name)
}
}
return true
})
return nil
})
if err != nil {
return nil, err
}
sort.Slice(results, func(i, j int) bool {
left, right := results[i], results[j]
if left.path != right.path {
return left.path < right.path
}
if left.line != right.line {
return left.line < right.line
}
if left.column != right.column {
return left.column < right.column
}
return left.kind < right.kind
})
return results, nil
}
func appendFinding(results []finding, fset *token.FileSet, pos token.Pos, path, kind, detail string) []finding {
position := fset.Position(pos)
return append(results, finding{
path: filepath.ToSlash(path),
line: position.Line,
column: position.Column,
kind: kind,
detail: detail,
})
}
func returnsType(fields *ast.FieldList, typeName string) bool {
if fields == nil {
return false
}
for _, field := range fields.List {
if matchesType(field.Type, typeName) {
return true
}
}
return false
}
func matchesType(expr ast.Expr, typeName string) bool {
switch expr := expr.(type) {
case *ast.Ident:
return expr.Name == typeName
case *ast.SelectorExpr:
return expr.Sel.Name == typeName
case *ast.StarExpr:
return matchesType(expr.X, typeName)
case *ast.IndexExpr:
return matchesType(expr.X, typeName)
case *ast.IndexListExpr:
return matchesType(expr.X, typeName)
default:
return false
}
}
@@ -0,0 +1,13 @@
#!/bin/sh
set -eu
script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"}
mkdir -p "$cache_root/go-build" "$cache_root/tmp"
export GOCACHE="$cache_root/go-build"
export GOTMPDIR="$cache_root/tmp"
export GOPROXY=off
export GOFLAGS=-mod=readonly
exec go run "$script_dir/scan-go-type-syntax.go" "$@"
@@ -0,0 +1,61 @@
#!/bin/sh
set -u
usage() {
printf '%s\n' "usage: $0 file.go:line:column" >&2
exit 2
}
[ "$#" -eq 1 ] || usage
position=$1
command -v go >/dev/null 2>&1 || {
printf '%s\n' "error: go is required" >&2
exit 127
}
command -v gopls >/dev/null 2>&1 || {
printf '%s\n' "error: gopls is required" >&2
exit 127
}
case "$position" in
*.go:[1-9]*:[1-9]*) ;;
*) usage ;;
esac
cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"}
mkdir -p "$cache_root/go-build" "$cache_root/xdg" "$cache_root/tmp" || exit 1
export GOCACHE="$cache_root/go-build"
export XDG_CACHE_HOME="$cache_root/xdg"
export GOTMPDIR="$cache_root/tmp"
export GOPROXY=off
export GOFLAGS=-mod=readonly
gomod=$(go env GOMOD)
if [ "$gomod" = "/dev/null" ] || [ -z "$gomod" ]; then
printf '%s\n' "error: run from inside a Go module" >&2
exit 1
fi
run_query() {
label=$1
shift
printf '\n== %s ==\n' "$label"
if output=$(gopls "$@" 2>&1); then
printf '%s\n' "$output"
return 0
else
printf '%s\n' "$output"
printf '%s\n' "(query is not applicable at this position, or failed)"
return 1
fi
}
successful=0
run_query "definition" definition "$position" && successful=$((successful + 1))
run_query "references (including declaration)" references -d "$position" && successful=$((successful + 1))
run_query "implementations" implementation "$position" && successful=$((successful + 1))
run_query "call hierarchy" call_hierarchy "$position" && successful=$((successful + 1))
[ "$successful" -gt 0 ]
@@ -0,0 +1,343 @@
---
name: archie-config-and-flags
description: Trace, add, rename, deprecate, or debug Archie configuration and command-line flags from external input through defaults, validation, overlays, environment and secret handling, worker snapshots, deployment passthrough, and the production consumer. Use for internal/config, config.example.toml, config.docker.toml, docker-compose.yml, archied or archie-agent flags, multi-identity settings, mode-parity questions, and reports of a setting that parses but has no effect.
---
# Trace Archie configuration and flags
Treat configuration as a dataflow, not as a struct inventory. Prove every
claimed setting has an input, normalization path, composition seam, and runtime
consumer.
Current evidence date: **2026-07-28**. Re-verify volatile defaults, deployment
wiring, and status labels before changing behavior.
## Route work to the right skill
Do not use this skill to:
- choose a new architecture or owner; use
`archie-architecture-planning-campaign` and `archie-architecture-contract`;
- discover an unknown feature's whole blast radius; use
`archie-codebase-discovery`, then return here for its configuration seam;
- inspect live hosts, rotate secrets, deploy, or recover an instance; use
`archie-run-and-operate`;
- define NellDB settings or persistence semantics; use `archie-nelldb`;
- approve a behavioral change or claim acceptance; use
`archie-change-control` and `archie-validation-and-qa`.
Use these status terms exactly:
| Status | Meaning |
| --- | --- |
| **production-wired** | A real entrypoint decodes or accepts the value and a runtime consumer uses it. |
| **partially-wired** | Some modes, scopes, or fields consume it, but parity is incomplete. |
| **test/library-only** | An API and tests exist, but no current binary selects it. |
| **decoded-but-unwired** | Decoding/defaulting succeeds, but no production consumer uses the effective value. |
| **experimental/candidate** | Code exists, but operational correctness or the public contract is not established. |
| **external-production-unknown** | The repository does not contain the deployed effective value. |
Never upgrade a status merely because decoding tests pass.
## Trace one setting before editing it
Perform this sequence:
1. Find every external spelling, Go field, flag, environment name, example, and
deployment reference.
2. Identify the selected loader or flag set. Do not assume every exported loader
is used.
3. Read `finalize` and any consumer-side defaults. Record zero, empty, negative,
and sentinel semantics separately.
4. Follow copies across `ForTask`, `ToConfig`, NATS messages, subprocess
environment selection, container environment construction, and identity
overlays.
5. Find the production composition site and final behavior-changing read.
6. Find a test for decoding, defaulting, invalid input, production composition,
and mode parity. Record missing layers as gaps.
7. Check `config.example.toml`, `config.docker.toml`, `docker-compose.yml`, and
deployment environment passthrough.
8. Assign one status from the table above and cite the exact evidence paths in
the change record.
Start with:
```bash
rg -n 'LoadOverlay|LoadDir|ForTask|ToConfig|flag\.' \
internal/config cmd/archied cmd/archie-agent
rg -n 'FIELD_NAME|external_key|ENV_NAME' \
--glob '*.go' --glob '*.toml' --glob '*.yml' --glob '*.yaml' .
```
Do not search only `internal/config`: a field with no reads outside that package
is usually not production-wired.
## Select the real input path
| Input path | Current behavior | Status |
| --- | --- | --- |
| `archied -config PATH` | Defaults to `$XDG_CONFIG_HOME/archie/config.toml`, or `$HOME/.config/archie/config.toml`; `cmd/archied/main.go` calls `config.LoadOverlay`. | production-wired |
| `archied -config-overlay PATH` | Decodes base TOML, then overlay TOML into the same `Config`, then calls `finalize` once. Omitted overlay fields retain base values. | production-wired |
| `config.Load(PATH)` | Loads one TOML and finalizes it; no current binary calls it directly. | test/library-only |
| `config.LoadDir(base, overlay)` | Supports main YAML/TOML plus feature YAML and `conf.d`; no current entrypoint calls it. | test/library-only |
| `config.example.toml` | Load-tested example, not a deployed configuration. | test/library-only |
| `config.docker.toml` | Repository overlay mounted by Compose; it still depends on the host base config. | production-wired |
| Host base config and environment on `carina` | Mounted from `${HOME}/.config/archie/config.toml`; contents are absent from this repository. | external-production-unknown |
`LoadDir` recognizes `gateway`, `tools`, `memory`, `models`, and `identities`
feature YAML. It rejects unknown `config.<feature>.yaml` names, but accepts
unknown `conf.d/*.yaml` into `Config.Extra`. YAML takes precedence over TOML
when both are present in one directory. None of this changes the current daemon
path: `archied` selects TOML `LoadOverlay`, including during Telegram reload.
Both TOML and YAML decoding are non-strict at the field level: the loaders do
not reject every unknown key. Add explicit compatibility and typo tests; never
use “the file loaded” as evidence that a key took effect.
## Inventory CLI flags
### Public binaries
| Binary | Flag | Default and effect |
| --- | --- | --- |
| `archied` | `-config PATH` | Computed config path described above. |
| `archied` | `-config-overlay PATH` | Empty; overlay only fields explicitly present in the second TOML. |
| `archied` | `-once` | `false`; run one poll/process cycle and exit. |
| `archied` | `-requeue ID` | `0`; values greater than zero requeue one parked/waiting task, then exit unless `-once` is also set. |
| `archie-agent` | `-nats-url URL` | Empty; takes precedence over `NATS_URL`. Missing both is fatal. |
| `archie-agent` | `-consumer NAME` | `archie-agent`; names the JetStream durable consumer. |
| both | `-quickchecks N` | Incidental flag registered by `github.com/traefik/yaegi/stdlib` importing `testing/quick`; default `100`. Archie has no intentional consumer. Treat it as an unowned candidate defect, not supported configuration. |
The standalone agent always reads its token from `NATS_TOKEN`; there is no
token flag.
### Internal codesearch helper
`archied workspace-codesearch` bypasses daemon configuration before normal flag
parsing. It is an internal child-process contract:
| Subcommand | Required flags | Optional flags |
| --- | --- | --- |
| `build` | `--root`, `--index` | none |
| `candidates` | `--index`, `--pattern` | `--literal`, `--case-sensitive` |
Do not expose these helper flags as daemon settings without an architecture and
compatibility decision.
## Read the current wiring matrix
### Root daemon and capability settings
| Keys | Default, validation, and consumer | Status |
| --- | --- | --- |
| `work_dir`, `db_path` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; `work_dir` drives worktrees, memory, derived index paths, and state files, while `db_path` opens NellDB. Literal `~` in an explicit value is not expanded by the loader. | production-wired |
| `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. The `skill_activate` catalog still reads `work_dir`, and a container rebuilds from its mounted worktree. | partially-wired |
| `plugin_dir` | Empty disables daemon plugin loading; a configured directory is loaded in `cmd/archied`. | production-wired |
| `poll_interval` | Defaults to `60s`; root poll loop uses it and identities may override only their interval. | production-wired |
| `label` | No default or validation; used for `dispatch.trigger = "label"` or `"either"`. Empty therefore remains an accepted but likely ineffective pickup label. | production-wired |
| `max_retries` | Defaults to `3`; a repository value greater than zero overrides it. | production-wired |
| `bot_user`, `bot_email` | Single-identity mode requires `bot_user`; email defaults by forge type. `bot_user` drives assignment polling, store actor, sessions, and release state; both values form the Git signature. | production-wired |
| `forge.type`, `host`, `token` | Type defaults `github`, host defaults `https://github.com`; only `github` and `gitea` validate. The root token resolves before daemon construction and must be non-empty. | production-wired |
| `dispatch.trigger` | Defaults `assignee`; validates `assignee`, `label`, or `either`. | production-wired |
| `dispatch.ack_reaction` | Defaults `eyes`; case-insensitive `off` normalizes to empty. | production-wired |
| `dispatch.labels.*` | Missing `queued`, `working`, `waiting`, `pr`, `parked`, or `dead` keys default independently to `agent:*`. Used for forge state presentation. | production-wired |
| `models.<role>` | Workflow stages read a requested role then fall back to `builder`; triage reply judging falls back from `triage` to `planner`. References are not validated at load time. | production-wired |
| `providers.<name>.class`, `api_key_env`, `base_url` | Builds the ai-sdk catalog. `base_url` rejects parse errors, userinfo, query, and fragment; class/key/model compatibility is deferred. | production-wired |
| `agent.mode` | Defaults to `nats` when containers are enabled, otherwise `inprocess`; validates `inprocess`, `subprocess`, or `nats`. Subprocess caveat follows this table. | production-wired |
| `agent.command`, `agent.env` | Command defaults `archie-agent`; environment entries must be nonblank names without `=` and apply only to subprocess mode. | partially-wired |
| `budgets.max_steps`, `max_tokens`, `wall_clock`, `gate_max_failures` | No loader defaults; `Budgets` documents zero as disabling the limit. Workflow agent requests and gates consume them. | production-wired |
| `diff_cap_lines` | Zero is replaced by `400` in `finalize`; `StageDiffCap` treats values `<= 0` as disabled. Thus TOML zero cannot disable the cap, while an unvalidated negative value does. Do not use negative as a hidden operator contract. | production-wired |
| `web.listen` | Empty becomes `127.0.0.1:8484`; literal `off` disables. The dashboard has no authentication. | production-wired |
| `notify.webhook` | Empty disables; feasibility workflow POSTs human-decision notifications when set. Included in worker `TaskConfig`. | production-wired |
| `nats.url`, `token_env` | Empty URL keeps the SQLite path. A configured token variable must be non-empty. NATS enables distributed queue/RPC composition. | production-wired |
| `containers.*` | See the dedicated table below. Some values also control scheduling/storage outside the pool, demonstrating current cross-concern ownership. | production-wired |
| `chat.*` | See the channel table below. Empty channel addresses/token names disable those channels. | production-wired |
| `memory.provider`, `provider_config`, `session_ttl` | Feature YAML decodes and tests these fields, but `cmd/archied` always starts the built-in file provider at `work_dir/memory` and never reads them. | decoded-but-unwired |
| `tools.mcp_servers` | `cmd/archied` registers daemon-side MCP providers. Empty transport becomes `stdio`; only `stdio` is accepted; name and command are required. Invalid entries warn and skip. `url` is decoded but unused. Worker parity is not established. | partially-wired |
| `tools.tool_policy.*` | Feature YAML decodes `max_result_chars` and `parallel_execution`; no production read exists. | decoded-but-unwired |
| `indexing.index_dir`, `indexing.db_path` | `finalize` derives paths under `work_dir`; no entrypoint constructs `internal/indexing.Manager` from them. The internal helper alone does not complete wiring. | decoded-but-unwired |
| `extra` / unknown `conf.d` values | Test/library-only `LoadDir` stores untyped data, but core production has no consumer and the approved target forbids a core catch-all. | decoded-but-unwired |
The default `agent.command = "archie-agent"` is not verified subprocess
operation. `SubprocessRunner` expects one JSON invocation on stdin and one JSON
response on stdout; `cmd/archie-agent` is a long-running NATS worker that parses
NATS flags. Treat subprocess mode with that command as an open incompatibility
until an end-to-end test proves otherwise.
### Repository settings
| Keys | Effective behavior | Status |
| --- | --- | --- |
| `owner`, `name` | Required for every declared repo. A single-identity config with zero repos currently loads but polls nothing. | production-wired |
| `base` | `BaseBranch()` maps empty to `main`, but `daemon.process` pre-clones with raw `repo.Base`. Set it explicitly: the advertised empty default is not honored on that production path. | partially-wired |
| `gate` | Argv arrays run in order. Empty entries are skipped. TDD inverts the last non-empty command as the repro test by convention. No loader validates command meaning. | production-wired |
| `protect` | Path suffixes are enforced by the agent runner; this is not a prompt-only rule. | production-wired |
| `ecosystem`, `preflight`, `test_glob` | Resolved preflight/test-glob logic treats empty ecosystem as Go. Container storage receives the raw ecosystem, so empty gets no Go cache mounts. Go/Python/Node/Rust have defaults; `custom` or an unknown name yields none. Explicit test globs validate with `filepath.Match`. | partially-wired |
| `persistent_storage` | Controls Docker-backed per-repo volume setup; it has no equivalent effect without container storage. | partially-wired |
| `max_retries` | Values greater than zero override global retry count; zero or negative falls back to global. | production-wired |
| `allow_concurrent` | Root repo entries affect the dispatcher. `allowConcurrentFor` does not inspect identity repo lists. | partially-wired |
### Container settings
| Key | Effective behavior |
| --- | --- |
| `enabled` | Requires non-empty `image`, `agent.mode = "nats"`, and non-empty `nats.url`. |
| `image` | Required only when enabled. |
| `max_concurrency` | Zero means no limit; used by the general task dispatcher and again by the container pool. |
| `max_uptime` | Defaults to `60m` only when enabled; caps a container lifetime. |
| `volume_ttl` | Defaults to `72h` only when enabled; negative is rejected; governs persistent-volume cleanup. |
| `pull_policy` | Defaults to `missing` when enabled. Pool code recognizes `missing` and `always`; other strings are not rejected and silently skip pre-pull. |
| `network` | Empty uses best-effort self-network detection. The repository overlay pins `archie-core_default`. |
### Channel settings
| Keys | Effective behavior |
| --- | --- |
| `chat.models` | Optional interactive catalog; empty falls back to distinct top-level workflow model references. |
| `chat.telegram.token_env` | Empty disables Telegram; non-empty names an environment variable and an empty value is fatal. |
| `chat.telegram.allowed_user_ids` | Empty denies every sender; IDs match Telegram sender IDs, not chat IDs. |
| `chat.telegram.update_check_command`, `update_install_command` | Argv arrays; check enables update status, and install additionally enables approved installation. |
| `chat.email.listen_addr`, `relay_addr` | Empty listen disables SMTP; relay configures outbound replies. |
| `chat.webhook_addr` | Empty disables; malformed host/port input falls back inside `parseListenAddr` rather than failing config validation. |
Telegram `/restart` re-runs the same TOML overlay load, then replaces only the
gateway token and allowed-user list. Every other file setting is startup-only
in current composition. Active chat model/provider and persona selection are
runtime state, not configuration-file reload.
## Treat multi-identity as partially wired
`finalize` requires each identity's `name`, `bot_user`, non-empty repos, forge
type, and `SecretRef` token. It validates repository identity and test globs,
and `cmd/archied` builds an identity forge client and worktree manager.
Do not infer complete isolation:
- `cmd/archied` still resolves and constructs the root forge client before all
identity runners, so a config accepted without root fields can still fail in
production composition.
- Identity `name`, forge, repos, poll interval, bot user, and bot email have
some production reads. Identity bot email is not defaulted despite its
comment promising a fallback.
- Identity `models`, `providers`, `dispatch`, `budgets`, `notify`, and
`diff_cap_lines` decode but workflows still receive root `Config`.
- Identity polling reads root `dispatch`, `label`, and `bot_user`.
- Container task snapshots and provider maps come from root config; task RPC
servers are root-forge/root-worktree; container identity isolation is
explicitly incomplete in `internal/daemon/daemon.go`.
- Root-only concurrency lookup ignores identity repo `allow_concurrent`.
Classify multi-identity changes field by field. Never label the aggregate
`IdentityConfig` production-wired.
## Preserve worker and secret boundaries
`Config.ForTask` creates a detached root snapshot containing only models,
budgets, dispatch, diff cap, notification, and forge host. `TaskConfig.ToConfig`
reconstructs only those fields. Provider descriptions travel separately in the
task-run request; forge tokens, provider values, NATS credential references,
repos, and infrastructure settings do not enter `TaskConfig`.
At the top-level `[forge]`, prefer
`token = {engine = "env", key = "NAME"}`. Legacy `token_env = "NAME"` is
converted only when the structured reference is empty; the structured
reference wins when both appear. This compatibility rule exists because an
earlier migration silently dropped deployed `token_env` values and crash-looped
the daemon. `finalize` does not apply that conversion inside each identity:
identity forges require an explicit structured `token`.
Use this environment matrix:
| Source | Archied | Subprocess | Agent container / standalone worker |
| --- | --- | --- | --- |
| Forge `token = {engine="env", key="X"}` | Resolves `X`; empty is fatal. | Not forwarded unless explicitly abused through `agent.env`. | Not forwarded; forge operations proxy to daemon. |
| Provider `api_key_env = "X"` | Runtime reads `X`. | Automatically allowlists the selected provider's `X`. | Daemon forwards each present provider variable under its original name. |
| `nats.token_env = "X"` | Reads `X`; empty is fatal when configured. | Not an agent subprocess setting. | Daemon maps its value to fixed `NATS_TOKEN`; worker also reads `NATS_URL`. |
| Telegram `token_env = "X"` | Reads `X`. | Not forwarded. | Not forwarded. |
| `agent.env = ["X"]` | Names are validated. | Copies present `X` from daemon environment. | Not used by container construction. |
`cmd/archied` creates `secret.NewRegistry`, which registers only the `env`
engine, and does not call `Registry.LoadDir`. Although plugin loading APIs and
comments describe custom secret engines, non-env `SecretRef` values are not
production-wired at token-resolution time.
Compose passes only `ARCHIE_GITEA_TOKEN`,
`ARCHIE_GITEA_TOKEN_ARCHIE`, `HEYARCHIE_TELEGRAM_BOT_TOKEN`, and
`DEEPSEEK_API_KEY` into `archied`. A config reference to any other environment
name requires an explicit deployment passthrough change. The live base config
is external, so do not assert which of these names it uses.
## Add, rename, or remove an axis
Use this checklist:
- [ ] Classify the value as invariant, runtime setting, policy, derived value,
or runtime state.
- [ ] Name one target capability owner and its scope: installation, identity,
repository, workflow, channel, or plugin instance.
- [ ] Prefer capability-owned settings. If a temporary `internal/config` field
is unavoidable, record its target owner and deletion gate.
- [ ] Add a failing decoder test for the production TOML path.
- [ ] Add failing tests for default, explicit value, zero/empty/negative input,
invalid syntax, semantic combination, and overlay inheritance.
- [ ] Add a production-composition test that observes the final consumer; a
struct equality test is insufficient.
- [ ] Test single identity, multiple identities, and every affected execution
mode separately.
- [ ] Update `ForTask`/`ToConfig` only when the worker needs the value; prove
maps are detached and secret values/references are absent.
- [ ] Trace in-process, subprocess allowlisting, NATS payload, container
environment, and RPC ownership. Fence unsupported modes explicitly.
- [ ] Update `config.example.toml`, `config.docker.toml`, Compose environment
passthrough, and generated/reference docs only where applicable.
- [ ] For a rename, decode old and new spellings at the loader boundary, define
precedence, and test old-only, new-only, and both. The `forge.token_env`
crash-loop regression is the minimum compatibility standard.
- [ ] For removal, prove no production consumer, external spelling, overlay,
worker copy, deploy reference, or supported old config remains. Define a
dated deprecation and deletion gate; do not leave a permanent alias.
- [ ] Route behavior-changing acceptance through change control and validation.
Do not add a field that merely parses. Do not add arbitrary plugin fields to the
global struct. Do not expose secret values in config dumps, logs, task payloads,
or review evidence.
## Follow the approved target, not the current sprawl
Current code puts infrastructure paths, domain policy, channel settings,
secrets, execution settings, repository associations, and extension data in one
mutable `config.Config`. It passes that aggregate into `daemon.Daemon`,
`workflow.TaskContext`, and a second worker DTO. Treat this as a current
load-bearing weakness, not a pattern to copy.
`docs/prds/architecture/configuration.md` is approved as of 2026-07-28:
- move file/env/secret/overlay loading to a private
`internal/infrastructure/configuration` input boundary;
- translate inputs in `internal/app`;
- give each domain/plugin typed owned settings and validation;
- dissolve `internal/config` rather than rename the global model;
- split `Repo` and `IdentityConfig` by actual capability ownership;
- stage, validate, health-check, promote, audit, and roll back configuration
candidates without replacing last-known-good settings.
Use `archie-architecture-planning-campaign` before moving ownership, and use
`archie-change-control` for every behavior-changing migration slice. Keep each
slice small enough to deliver a visible success while deleting one obsolete
path.
## Provenance and maintenance
Re-verify declarations and defaults: `rg -n 'type (Config|IdentityConfig|Repo|Agent|ContainerConfig|ChatConfig|ToolsConfig)|func (Load|LoadOverlay|LoadDir|finalize|\(c Config\) ForTask|\(tc TaskConfig\) ToConfig)' internal/config`
Re-verify entrypoint and flag selection: `rg -n 'flag\.|LoadOverlay|LoadDir|ForTask|ToConfig|containerEnv' cmd/archied cmd/archie-agent internal/daemon`
Re-verify all exposed help: `env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-help-gocache go run ./cmd/archied -h`
Re-verify worker help: `env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-help-gocache go run ./cmd/archie-agent -h`
Re-verify config behavior: `env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-test-gocache go test ./internal/config -count=1`
Re-verify deployment passthrough: `rg -n 'command:|environment:|config\.toml|config\.docker\.toml|NATS_|TOKEN|API_KEY' docker-compose.yml config.docker.toml config.example.toml Dockerfile Dockerfile.archied`
Re-verify target doctrine: `rg -n 'Ownership|Dissolution|Current configuration migration ledger|Universal change protocol|Completion criteria' docs/prds/architecture/configuration.md`
@@ -0,0 +1,4 @@
interface:
display_name: "Archie Config and Flags"
short_description: "Trace Archie configuration from input to runtime"
default_prompt: "Use $archie-config-and-flags to trace this Archie setting or CLI flag from declaration through production wiring."
@@ -0,0 +1,473 @@
---
name: archie-debugging-playbook
description: Project-specific symptom-to-evidence triage for archie-core. Load this skill when Archied hangs, parks a task, loses or duplicates work, cannot reach NATS or an agent container, rejects configuration or secrets, shows stale Telegram or dashboard state, loses streamed text, fails MCP startup, reports NellDB state surprises, degrades an optional feature, or when Go tests disagree between a sandbox, editor, CI, and the host. Use it to separate environment failures from code regressions and to choose the next exact diagnostic.
---
# Debug Archie from evidence
Use this runbook to identify the failing boundary. Stop after establishing the
smallest reproducible symptom and its owner. Do not edit code while collecting
the first evidence set.
Treat facts marked **current** as verified against the repository on
2026-07-28. Treat facts marked **fixed history** as regression patterns, not
claims that production is failing now. Treat **open** as a verified gap whose
production impact still depends on deployment state.
Define these terms once:
- **Composition root**: `cmd/archied/main.go`, where decoded configuration
becomes live services.
- **Core NATS request/reply**: a request sent directly to a subject and answered
through its reply inbox.
- **JetStream**: the persisted NATS task/agent stream named `ARCHIE_TASKS`.
- **Wiring**: construction and connection of an implemented package into the
running daemon.
- **Environment failure**: a test or process cannot use a host resource such as
a listener, temp directory, Docker socket, or credential.
- **Code regression**: the same focused behavior fails in an environment that
provides its declared prerequisites.
## Do not use this skill for the wrong job
- For the incident timeline, rejected fixes, or reverts, load
`archie-failure-archaeology`.
- For AST traversal, callers, duplicate paths, or feature impact, load
`archie-codebase-discovery`.
- For repeatable inventories and measurements, load
`archie-diagnostics-and-tooling`.
- For installing tools or recreating the machine, load `archie-build-and-env`.
- For live startup, Compose, deployment, logs, or rollback, load
`archie-run-and-operate`.
- For acceptance evidence after a fix, load `archie-validation-and-qa`, then
route behavior-changing work through `archie-change-control`.
- For NellDB design or persistence changes, load `archie-nelldb`.
## Run the first-ten-minutes protocol
1. Record the exact command, exit code, first causal error, working directory,
configuration paths, execution mode, and whether the run was sandboxed.
2. Reproduce one package or one process boundary. Do not begin with `task
check`: it writes through `gofumpt -w .` and `go fix ./...`.
3. Compile tests without running them:
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-debug-gocache \
GIT_CONFIG_GLOBAL=/dev/null go test ./PATH/TO/PACKAGE -run '^$' -count=1
```
4. Run only the named test:
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-debug-gocache \
GIT_CONFIG_GLOBAL=/dev/null go test ./PATH/TO/PACKAGE \
-run '^TestName$' -count=1 -v
```
5. Classify the first failure:
- Compile-only failure: inspect code, generated inputs, build tags, and the
actual Go toolchain.
- `listen ... operation not permitted` or an embedded NATS panic: rerun in an
environment that permits loopback listeners before blaming code.
- `mkdir /work/tmp/...: read-only file system`: keep `GOTMPDIR=/tmp`; the
repository code has not run yet.
- Behavioral assertion with the prerequisite available: treat it as a code
regression.
6. Preserve the failing output. Predict the expected observation before trying
a workaround.
Use this symptom index to select the detailed branch:
| Symptom | First boundary | Go to |
|---|---|---|
| `Run() = "\n"` in `TestRunWrapsExternalCommand` | Skill-script test command shape | Current known regression |
| Embedded NATS panics before a test assertion | Listener permission | Test environment |
| `nats: no responders available for request` | Core NATS subscription | NATS request/reply |
| Agent reply timeout | JetStream request, inbox, or worker | NATS request/reply |
| Queue looks empty while NATS reports an error | `Client.Fetch` batch error | NATS request/reply |
| Config test passes but daemon ignores the field | Composition/wiring | Configuration |
| Daemon has an env var but container does not | Compose or `containerEnv` | Configuration |
| Telegram reply hangs on the first token | Stream consumer | Streaming |
| MCP unit tests pass but a real server hangs | Framing mirror | MCP |
| Telegram shows old commands | Token-scoped Telegram state | Telegram |
| Transition succeeds from the wrong state | Store semantics | NellDB/state |
| Dashboard skips events but task state is correct | Bounded event buffers | Events |
| Search works but never becomes indexed | Missing production wiring | Optional features |
| Agent container cannot resolve `nats` | Docker network | Containers |
| `agent.mode = "subprocess"` fails at protocol startup | Worker binary mismatch | Subprocess mode |
| IDE reports an error that CLI cannot reproduce | Editor/cache state | Test environment |
## Separate test-environment failures from regressions
Inspect the active Go paths before changing code:
```bash
go version
go env GOTMPDIR GOCACHE GOPATH GOMODCACHE GOENV
```
This checkout can inherit `GOTMPDIR=/work/tmp`; that path is read-only in some
sandboxes. Setting both `GOTMPDIR=/tmp` and a task-specific `GOCACHE` is a
diagnostic isolation step, not a product fix.
Listener-dependent tests include embedded NATS, `httptest.NewServer`, and SMTP
listeners. Locate them:
```bash
rg -n 'httptest\.NewServer|net\.Listen|RunRandClientPortServer|RunServer' \
--glob '*_test.go' cmd internal
```
If a listener is forbidden, the characteristic evidence is a panic such as
`Unable to start NATS Server in Go Routine` or
`httptest: failed to listen on a port ... operation not permitted`. A
listener-free package passing does not waive the blocked integration tests.
Do not attribute current go-git commit failures to GPG without checking the
repository-local mitigation. `worktree.Manager.setIdentity` pins
`commit.gpgsign=false`; its fixtures do the same. Isolate ambient global config:
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-worktree-gocache \
GIT_CONFIG_GLOBAL=/dev/null go test ./internal/worktree -count=1
```
If this passes while an editor still reports compiler errors, record the CLI
result as authoritative and restart the editor language server. Do not delete
module caches merely to silence a diagnostic.
**Fixed history:** `.gotmp/` once held a workaround for tmpfs quota pressure and
was accidentally committed by a broad add. It is ignored now. Keep diagnostics
in `/tmp`, and never turn a local cache workaround into repository content.
## Confirm the current known regression
As of 2026-07-28, this focused test fails in an otherwise runnable package:
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-skillscript-gocache \
GIT_CONFIG_GLOBAL=/dev/null go test ./internal/skillscript \
-run '^TestRunWrapsExternalCommand$' -count=1 -v
```
Expected current failure:
```text
Run() = "\n"
```
The test constructs:
```go
exec.CommandContext(ctx, "sh", "-c", "echo", "wrapped")
```
For `sh -c`, the argument after the command string becomes shell `$0`;
therefore the command string is only `echo`, which prints a newline. This is a
test regression introduced by cleanup commit `308c199`, not proof that Yaegi
cannot run external commands. Do not weaken the expected `"wrapped\n"` value.
Route the fix and its acceptance evidence through `archie-change-control` and
`archie-validation-and-qa`.
## Triage NATS request/reply and JetStream
Keep the two transports distinct:
| Surface | Subject or resource | Bound/current behavior |
|---|---|---|
| Task discovery | `archie.task.>` in `ARCHIE_TASKS` | Work-queue retention; daemon durable `archie-daemon`; max deliver 3 |
| Legacy agent stage | `archie.agent.<task>.request` | Reply inbox in `X-Archie-Reply`; wall-clock budget or 30m |
| Full task handoff | `archie.taskrun.<task-id>` | Core request/reply; no-responder retry defaults to 20s every 250ms |
| Store RPC | `archie.store.update`, `.transition` | Client timeout set to 60s by `cmd/archie-agent/taskrun.go` |
| Forge RPC | `archie.forge.*` | Error travels in a JSON envelope |
| Worktree RPC | `archie.worktree.prepare`, `.push` | Server default handler bound is 15m |
| Discovery deduplication | `Nats-Msg-Id: archie:<owner>/<repo>/<issue>` | JetStream duplicate window is 2m |
For any NATS failure, collect read-only deployment evidence:
```bash
docker compose ps
docker compose logs --since=10m archied nats
docker ps --filter label=archie-daemon=true \
--format '{{.ID}}\t{{.Names}}\t{{.Networks}}\t{{.Status}}'
docker compose exec -T nats wget -q -O - http://localhost:8222/healthz
```
No stable container count exists; compare the task ID, agent container, and
subscription timing rather than demanding a fixed number.
Branch on `no responders`:
1. If a responder appears within 20 seconds, classify it as container startup
lag. `Daemon.requestTaskRun` deliberately retries only
`nats.ErrNoResponders`.
2. If every task exhausts the window, inspect the spawned agent's network and
environment. The Compose overlay currently sets
`containers.network = "archie-core_default"` and NATS URL
`nats://nats:4222`.
3. Look for agent logs `nats connected`, `taskrun: dedicated per-task
subscription`, and `archie-agent ready`. Absence of all three points before
workflow execution.
4. If only store/forge/worktree calls time out, confirm the composition root
reached `registerTaskRPCServers`; do not debug JetStream task discovery.
**Fixed history:** network auto-detection once silently put task containers on
the default bridge, so `nats` never resolved and every request had no
responders. Explicit `containers.network` plus warning logs now fence that
path.
Check duplicate and error semantics before "fixing" them:
- Republishing the same owner/repo/issue within two minutes is intentionally
deduplicated.
- A reply inbox auto-unsubscribes after one response. Search for two handlers
subscribed to the same request subject before assuming response loss.
- `Client.Fetch` must inspect `batch.Error()` after the message channel closes;
returning `(nil, nil)` would mask a JetStream failure as an empty queue.
- `agentexec.runStages` returns a response envelope and a nil Go error for a
stage failure. Returning both the envelope error and a Go error aborts the
handler before it can publish the response.
Run listener-free regression coverage for the last two rules:
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-nats-unit-gocache \
go test ./internal/nats \
-run '^TestFetchPropagatesBatchError' -count=1 -v
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-agent-unit-gocache \
go test ./internal/agentexec \
-run '^TestHandleMessage' -count=1 -v
```
## Trace configuration from source to behavior
Never stop at "the field decoded." Trace this sequence:
1. `cmd/archied` reads `-config` and optional `-config-overlay`.
2. `config.LoadOverlay` TOML-decodes and `finalize` defaults/validates.
3. Secret references resolve or named environment variables are read.
4. The composition root constructs a service from the field.
5. Compose, subprocess allowlists, or `containerEnv` propagate needed values.
6. A focused behavior test observes the value at its consumer.
Use these source checks:
```bash
rg -n 'config\.LoadOverlay|config\.LoadDir' cmd/archied internal/config
rg -n 'cfg\.[A-Za-z0-9_.]+' cmd/archied/main.go
rg -n 'containerEnv|WorkerEnvironment|environment:' \
cmd internal docker-compose.yml
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-gocache \
go test ./internal/config \
-run 'Test(LoadOverlay|LoadForgeToken|DockerConfig)' -count=1 -v
```
Expected current observation: production `cmd/archied` calls
`config.LoadOverlay`; feature-file `config.LoadDir` is covered by tests but has
no `config.LoadDir` call in the composition root. A YAML feature field can
therefore decode correctly without affecting the daemon. Classify that as a
wiring gap, not a parser bug.
For environment failures, distinguish:
- Compose passes only the names listed under `archied.environment`.
- `containerEnv` translates the configured NATS token name into `NATS_TOKEN`
for `archie-agent` and forwards configured provider key variables.
- `SubprocessRunner` forwards default compatibility variables, configured
`[agent].env` names, and only the requested provider key.
- The legacy top-level `[forge] token_env` is converted to an env `SecretRef`
by `finalize`; explicit `[forge.token]` wins.
Do not print secret values. Record only the variable name and
set/unset/propagated status.
## Diagnose streaming, MCP, and Telegram
### Streaming
If a Telegram draft shows an empty cursor, typing never clears, and the turn
never completes, inspect the consumer in `cmd/archied/main.go`. Current code
must drain `stream.FullStream`, collect only `core.StreamPartTextDelta`, then
check `FinishReason`. `TextStream` is a best-effort view and cannot reconstruct
the authoritative response.
**Fixed history:** consuming `TextStream` while leaving synchronous
`FullStream` unread deadlocked every streamed reply. Do not add a second
consumer or return before `FullStream` closes.
### MCP
Current stdio framing is one compact JSON-RPC object per line. Despite a stale
package comment in `internal/tools/mcp/types.go`, `Content-Length` framing is
not the implemented contract. Verify unit behavior:
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-mcp-gocache \
go test ./internal/tools/mcp \
-run 'Test(ReadMessage|WriteMessage|StdioTransportBadFraming)' \
-count=1 -v
```
Do not accept this alone as protocol compatibility: the helper server in
`transport_test.go` calls the same `readMessage` and `writeMessage` functions,
so client and fake can mirror the same mistake. With network access and `npx`
explicitly allowed, run the real-server test:
```bash
ARCHIE_TEST_DESKTOP_COMMANDER=1 \
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-mcp-integration-gocache \
go test ./internal/tools/provider/mcp \
-run '^TestDesktopCommanderClientCompatibility$' -count=1 -v
```
No stable tool count is asserted. The gate is non-empty discovery containing
`start_process`, `interact_with_process`, and `read_process_output`.
### Telegram
If commands work when typed but the menu is stale, inspect all three command
scopes in `internal/channels/telegram/commands.go`: default, all private chats,
and all group chats. Telegram stores command menus outside this repository,
keyed by bot token, and a narrower scope shadows the default.
If access is wrong, verify sender IDs, not chat IDs. Empty
`allowed_user_ids` denies everyone; message, model, provider, and update
callbacks each enforce sender authorization.
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-telegram-gocache \
go test ./internal/channels/telegram \
-run 'Test(SenderAllowlistFailsClosed|IsSenderAllowed|PublishedCommandsMatchExecutableCommandSurface)$' \
-count=1 -v
```
**Fixed history:** publishing only the default menu left roughly 60 commands
from a previous bot implementation visible in narrower scopes. A successful
single `SetMyCommands` call was insufficient evidence.
## Diagnose state, events, containers, and optional features
### NellDB and transitions
Current `internal/nell.Adapter.Transition` looks up the task, writes `to`, and
does not compare `from` or persist `detail`. The legacy SQLite store also does
not guard its update with `from`, although it records a transition row. Thus
"transition returned nil" does not prove the source state matched.
When state is surprising:
1. Read `TaskByID` immediately before and after the caller.
2. Trace every `Transition`, `Requeue`, `RecoverStale`, and `Update` call.
3. Do not infer a valid state machine from the `from` argument.
4. Run both backends' focused suites:
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-state-gocache \
GIT_CONFIG_GLOBAL=/dev/null go test \
./internal/nell ./internal/store -count=1
```
Route any semantic change to `archie-nelldb`, architecture planning, and change
control; it is not a local error-message fix.
### Events
The in-process bus drops when a subscriber buffer is full. The composition
root's database sink buffer is 256; SSE client buffers are 64. The sink's drop
counter is not read in production, and per-client drops are not counted.
Therefore a dashboard gap can coexist with correct task state.
```bash
rg -n 'Subscribe\(256\)|make\(chan events\.Event, 64\)|Dropped\(\)' \
cmd/archied/main.go internal/events internal/webui
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-events-gocache \
go test ./internal/events -count=1
```
No stable production drop count exists. Treat missing events as an
observability defect only after comparing the persisted task document and
event log.
### Containers, worktrees, and subprocess mode
- A container-mode task clones on the host, mounts it at `/data/worktree`,
writes `task.json`, then uses a dedicated `archie.taskrun.<id>`
subscription when that file parses.
- The worktree manager uses go-git, pins signing off, stores its prepared
sentinel under `.git`, and performs an independent full clone per task.
- **Open:** container RPC registration is root-identity-bound; the comment in
`Daemon.process` says non-root identity container calls can use the wrong
forge/worktree clients.
- **Open:** the default `archie-agent` binary is now a long-running NATS worker,
while `SubprocessRunner` expects one JSON invocation on stdin and one JSON
response on stdout. `agent.mode="subprocess"` remains accepted by config, so
verify the configured command implements the old protocol before using it.
Confirm the binary shape without starting NATS:
```bash
env -u NATS_URL -u NATS_TOKEN GOTMPDIR=/tmp \
GOCACHE=/tmp/archie-agent-shape-gocache \
go run ./cmd/archie-agent </dev/null
```
Expected current observation: exit 1 with
`-nats-url or NATS_URL is required`, not a decoded stdin invocation. Label a
deployment using another compatible command separately.
### Optional feature degradation
Configuration is not capability evidence. Check startup logs and production
construction:
| Feature | Current failure behavior |
|---|---|
| Daemon plugin adaptation/registration | Warn and skip that capability |
| Invalid MCP server config | Warn `mcp tool provider skipped` and continue |
| Skill catalog/activation registration | Warn and continue without the tool |
| Worktree workflow augmentation | Log error, emit `registry_augment_failed`, use startup registry |
| Workspace indexing | **Open:** config defaults and helper exist, but no production `indexing.NewManager` call |
Verify the indexing wiring gap:
```bash
rg -n 'indexing\.NewManager|NewManager\(.*Index' \
cmd internal --glob '*.go' --glob '!*_test.go'
```
Expected current result: no production call. Do not diagnose slow unindexed
search by tuning index paths until this wiring changes.
## Close the diagnostic
Record:
- the smallest failing command and its prerequisite;
- the first causal error, not the final wrapper;
- the boundary owner and current/fixed-history/open classification;
- the expected observation and actual observation;
- the source symbol and focused test that protect the behavior;
- whether the result reproduces outside the sandbox;
- the next sibling skill and change-control class.
Do not call a diagnosis complete because a workaround made the symptom vanish.
Require a falsifiable cause: removing or restoring the suspected condition must
toggle the failure.
## Provenance and maintenance
Repository state and volatile facts were re-verified on 2026-07-28. Re-run
these one-line checks after changes:
```bash
rg -n 'defaultTaskRunReadyTimeout|defaultTaskRunRetryBackoff' internal/daemon/daemon.go
rg -n 'dedupWindow|pollTimeout|AckWait|MaxDeliver' internal/nats/client.go cmd/archie-agent/main.go
rg -n 'FullStream|TextStream|FinishReason' cmd/archied/main.go
rg -n 'Content-Length|newline-delimited' internal/tools/mcp
rg -n 'commandScopes|AllowedUserIDs|isSenderAllowed' internal/channels/telegram
rg -n 'func \(a \*Adapter\) Transition|func \(s \*Store\) Transition' internal/nell/adapter.go internal/store/store.go
rg -n 'Subscribe\(256\)|Dropped\(\)' cmd/archied/main.go internal/events
rg -n 'config\.LoadOverlay|config\.LoadDir|indexing\.NewManager' cmd internal --glob '*.go'
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-skillscript-gocache go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v
```
@@ -0,0 +1,4 @@
interface:
display_name: "Archie Debugging Playbook"
short_description: "Diagnose Archie failures from symptoms"
default_prompt: "Use $archie-debugging-playbook to diagnose this Archie failure from symptoms and evidence."
@@ -0,0 +1,429 @@
---
name: archie-diagnostics-and-tooling
description: "Measure Archie codebase maintainability, Go package dependency shape, configuration consumption, production composition, test and delivery-gate drift, tracked-artifact hygiene, coverage, races, and runtime evidence. Load when establishing a dated baseline, finding large or complex functions, investigating duplicate or dead-path candidates, checking whether configuration reaches an entrypoint, comparing architecture before and after a refactor, or replacing an eyeballed quality claim with reproducible numbers."
---
# Measure Archie instead of eyeballing it
Collect evidence before judging quality. Keep collection read-only, save raw
output, state what each metric cannot prove, and route behavior-changing
decisions through the appropriate gate.
Volatile facts and numeric snapshots below were verified on **2026-07-28**.
Re-run the commands before using any number as a baseline.
## Scope and routing
Use this skill to answer measurable questions:
- Which production functions exceed the repository's size or complexity
triage thresholds?
- Which packages have high internal fan-in or fan-out?
- Which tagged config fields have no syntax-level production or entrypoint
selector evidence?
- Which checks appear literally in Task, CI, docs, and deploy surfaces?
- Did a refactor reduce a named hotspot without adding dependencies or losing
validation coverage?
Do **not** use this skill as:
| Need | Load instead |
|---|---|
| Traverse an input through types, state, persistence, transports, consumers, and production composition | `archie-codebase-discovery` |
| Turn a hunch into a decision-gated experiment | `archie-research-methodology` |
| Decide package boundaries or run an architecture migration | `archie-architecture-planning-campaign` and `archie-architecture-contract` |
| Approve a patch or define acceptance evidence | `archie-validation-and-qa` and `archie-change-control` |
| Diagnose a live failure or operate a deployment | `archie-debugging-playbook` and `archie-run-and-operate` |
| Assign an owner, prove supersession, or approve deletion | `archie-technical-accountability` |
| Enumerate config defaults and supported axes | `archie-config-and-flags` |
Never call a path dead, a field unwired, or a package misplaced from one report.
Use reports to prioritize exact semantic traversal.
## Define the measurement terms
- **Baseline:** dated raw output tied to a commit, toolchain, command, and
environment.
- **Candidate:** a machine-found item requiring semantic confirmation.
- **Production composition:** concrete construction selected by a shipped
entrypoint. Archie's principal composition root is `cmd/archied/main.go`.
- **Fan-in:** number of packages in the same module that directly import a
package.
- **Fan-out:** number of packages in the same module that a package directly
imports.
- **Physical line:** a newline-delimited source line, including comments and
blanks. It is not a statement count.
- **Syntactic complexity:** this skill's approximation: one plus `if`, loop,
non-default case, communication clause, `&&`, and `||` nodes. It is not
`gocyclo`, `gocognit`, or `cyclop`.
- **Acceptance evidence:** evidence sufficient to approve the intended
behavior. Diagnostics are inputs to acceptance, not acceptance by themselves.
## Establish a reproducible snapshot
Run from the repository root. Keep caches and output outside the tree:
```sh
export LC_ALL=C
export GOCACHE=/tmp/archie-diagnostics-gocache
export GOTMPDIR=/tmp
export XDG_CACHE_HOME=/tmp/archie-diagnostics-xdg
export GOLANGCI_LINT_CACHE=/tmp/archie-diagnostics-lint
export GOPROXY=off
export GOFLAGS=-mod=readonly
skill=.claude/skills/archie-diagnostics-and-tooling
stamp=$(date -u +%Y%m%dT%H%M%SZ)
evidence_dir=/tmp/archie-diagnostics-"$stamp"
mkdir -p "$evidence_dir"
git rev-parse --verify HEAD >"$evidence_dir/revision.txt"
git status --short >>"$evidence_dir/revision.txt"
go version >"$evidence_dir/tools.txt"
gopls version >>"$evidence_dir/tools.txt"
golangci-lint version >>"$evidence_dir/tools.txt"
staticcheck -version >>"$evidence_dir/tools.txt"
go run "$skill/scripts/source-metrics.go" -root . >"$evidence_dir/source.tsv"
go run "$skill/scripts/config-use-candidates.go" -root . >"$evidence_dir/config.tsv"
"$skill/scripts/package-shape.sh" . >"$evidence_dir/packages-root.tsv"
"$skill/scripts/package-shape.sh" tools >"$evidence_dir/packages-tools.tsv"
"$skill/scripts/delivery-snapshot.sh" >"$evidence_dir/delivery.tsv"
```
`GOPROXY=off` and `-mod=readonly` prevent this evidence pass from fetching or
changing dependencies. Report an uncached dependency as an environment blocker.
The package helper preserves a harmless read-only module stat-cache warning but
normalizes its random temporary suffix to `<TEMP>`; preserve stderr and the exit
status with the report.
Write a measurement charter before interpreting output:
| Field | Required content |
|---|---|
| Question | One falsifiable maintainability, wiring, or delivery claim |
| Scope | Exact packages, modes, config branches, and modules |
| Predicted result | Expected baseline and before/after delta |
| Collection command | Exact command and environment |
| Branch condition | What contrary number triggers deeper discovery |
| Decision owner | Skill or reviewer that may approve action |
Do not invent a composite “quality score.” Keep size, complexity, dependency,
duplication, coverage, runtime, and ownership evidence separate.
## Use the bundled reports
### Measure source shape
Run:
```sh
go run "$skill/scripts/source-metrics.go" -root . -top 30
```
Read its tab-separated schema:
| Record | Columns after record name |
|---|---|
| `META` | key, value |
| `METRIC` | module, metric, integer |
| `PACKAGE` | module, directory, production files, test files, generated files, production lines, test lines, generated lines |
| `HOTSPOT` | module, file, declaration line, symbol, body-span lines, statement nodes, approximate syntactic complexity |
The script:
- scans repository-owned Go files;
- separates the root and `tools` modules;
- separates production, test, and generated files;
- excludes `.git`, `.claude`, `.references`, `node_modules`, `vendor`,
`.gotmp`, and VitePress cache/output;
- sorts output deterministically;
- reports only production hotspots unless
`-include-test-hotspots` is passed.
The defaults, 80 body lines and complexity 15, mirror two numeric triage points
in `.golangci.yml`. They do **not** implement `funlen` or `cyclop`. Run the
configured linters for authoritative linter findings:
```sh
golangci-lint run --enable-only=funlen,gocognit,gocyclo,cyclop,maintidx,nestif ./internal/...
```
If a hotspot shrinks, verify that responsibility moved to a cohesive owner.
Moving the same work into unowned helpers is not improvement.
### Measure package shape
Run both module reports:
```sh
"$skill/scripts/package-shape.sh" . >"$evidence_dir/packages-root.tsv"
"$skill/scripts/package-shape.sh" tools >"$evidence_dir/packages-tools.tsv"
awk -F ' ' '$1=="PACKAGE" {print $3 "\t" $4 "\t" $2}' "$evidence_dir/packages-root.tsv" |
sort -nr -k1,1 -k2,2 |
sed -n '1,20p'
```
Read `PACKAGE package fan_in fan_out` and `EDGE from -> to` rows. The script
reuses
`.claude/skills/archie-codebase-discovery/scripts/package-edges.sh`; do not
create a second package-edge implementation.
Interpret high fan-in as a change-risk signal and high fan-out as an
orchestration signal, not as automatic defects. The report contains only
direct, intra-module imports. It does not show `tools` importing the root
module, interface dispatch, RPC relationships, string registrations, or state
ownership. A successful `go list` rejects Go import cycles; it does not prove
the target dependency doctrine.
When an edge looks wrong:
1. Run `archie-codebase-discovery` on the imported contract.
2. Identify the concrete production consumer.
3. Compare the current edge with `docs/prds/architecture/`.
4. Route any boundary change through the architecture campaign.
### Find configuration-consumption candidates
Run:
```sh
go run "$skill/scripts/config-use-candidates.go" -root . >"$evidence_dir/config.tsv"
rg 'candidate-no-(selector-outside-config|entrypoint-selector)' "$evidence_dir/config.tsv"
```
Read each `CONFIG_FIELD` row as:
```text
path, line, Type.Field, tags, same-name definition count,
config-package selector count, cmd selector count,
other-production selector count, test selector count,
generated selector count, candidate status
```
The report finds named fields with `toml`, `yaml`, or `json` tags declared in
`internal/config`, then counts selectors with the same **spelling**. It is
deliberately fast and deliberately not type-aware.
For every candidate:
1. Inspect the declaration at the reported `path:line`.
2. Run `gopls references -d` on that exact field identifier.
3. Trace decode → default → validation → normalization/copy → composition-root
read → concrete component → observable behavior.
4. Check reflection, serialization tags, Yaegi, registries, and string keys.
5. Separate feature-file tests from production selection.
Repeated names such as `Name`, `Command`, or `Budgets` have high false-positive
rates; use the same-name count as a warning. A zero `cmd` count may be correct
when the composition root passes an enclosing struct. A nonzero count may
belong to an unrelated field. Only type-aware references plus composition prove
wiring.
### Measure delivery and hygiene drift
Run:
```sh
"$skill/scripts/delivery-snapshot.sh" >"$evidence_dir/delivery.tsv"
```
Read:
- `SURFACE axis scope literal_count` as literal text evidence, not parsed YAML
semantics;
- `HYGIENE metric count` as tracked-path candidates;
- `MODULE path` as discovered Go module boundaries.
The snapshot compares Task, GitHub docs CI, Gitea deploy CI, and selected
composition-root anchors. A zero says the literal pattern was absent. It does
not prove the behavior is absent from a called script or external system.
Inspect hygiene candidates directly:
```sh
git ls-files |
rg '(^|/)(node_modules|bin|dist|\.gotmp)(/|$)|\.(exe|test|out)$'
git ls-files -s | awk '$1=="120000" {print}'
```
Do not delete a tracked candidate from a metric alone. Establish ownership,
generation source, consumers, deployment need, and a rollback path with
`archie-technical-accountability`.
## Investigate duplication and hidden dead paths
Measure textual duplication:
```sh
golangci-lint run --enable-only=dupl ./internal/...
```
Measure unused unexported declarations:
```sh
staticcheck -checks=U1000 ./internal/...
```
On 2026-07-28, the focused `dupl` command reported zero issues. That does not
contradict the known maintainability problem: two code paths can implement the
same responsibility with different syntax.
For a duplicate or one-shot candidate:
1. Name the externally visible operation, state transition, event subject, or
side effect.
2. Search all entrypoints and modes for that operation.
3. Use `gopls call_hierarchy`, `gopls references -d`, and the discovery skill's
AST construction scan.
4. Check interfaces, registrations, reflection, build tags, OS files, and wire
names.
5. Identify what a new feature supersedes and the objective removal gate.
6. Record production-only, test-only, compatibility, generated, and
unreachable paths separately.
As of 2026-07-28, `Taskfile.yml` defines no `deadcode` task and the installed
`go tool` lists no dead-code analyzer. Archived PRDs mentioning
`task deadcode` describe a desired or former command, not a live command.
## Collect test, race, coverage, and runtime evidence
Keep collection scoped to the hypothesis:
```sh
go test ./internal/nell -count=1 -coverprofile=/tmp/archie-nell.cover
go tool cover -func=/tmp/archie-nell.cover
go test -race ./internal/nell -count=1
```
These commands were verified on 2026-07-28; the package reported 65.2% statement
coverage and passed its race run. The percentage is volatile and is not a
quality threshold. Read uncovered functions and error paths.
`go test` can write CPU and memory profiles, but this checkout's `go tool`
listed no `pprof` frontend on 2026-07-28. Do not promise profile inspection
until `command -v pprof` or another approved viewer succeeds. Do not download a
viewer during a read-only evidence pass.
Collect container logs without following indefinitely:
```sh
docker compose logs archied >"$evidence_dir/archied.log"
docker compose logs nats >"$evidence_dir/nats.log"
curl -fsS http://localhost:8222/healthz >"$evidence_dir/nats-health.txt"
```
Run those only when the local Compose stack is in scope. Repository files do
not prove the remote `carina` instances match local Compose. `docker-compose.yml`
publishes NATS monitoring on port 8222 and uses `/healthz` in its healthcheck;
it does not establish a metrics endpoint contract. Route remote operations and
log interpretation through `archie-run-and-operate` and
`archie-debugging-playbook`.
Some tests bind loopback listeners, including email, forge, storage, Telegram,
web UI, and MCP tests. A sandbox refusal to listen is environment evidence, not
a code regression. Re-run in an allowed environment before classifying it.
## Compare before and after
Predict exact deltas before changing code. Example:
```text
Prediction:
- cmd/archied.run body span: 668 → below 350
- root package count: unchanged
- new internal package edges: zero unless named in the design
- config candidate statuses: no regressions
- Task/CI/docs surface counts: unchanged unless explicitly in scope
```
Collect a second snapshot with the same script revision, flags, environment,
and toolchain:
```sh
after_dir=/tmp/archie-diagnostics-after
mkdir -p "$after_dir"
go run "$skill/scripts/source-metrics.go" -root . >"$after_dir/source.tsv"
go run "$skill/scripts/config-use-candidates.go" -root . >"$after_dir/config.tsv"
"$skill/scripts/package-shape.sh" . >"$after_dir/packages-root.tsv"
"$skill/scripts/delivery-snapshot.sh" >"$after_dir/delivery.tsv"
diff -u "$evidence_dir/source.tsv" "$after_dir/source.tsv"
diff -u "$evidence_dir/config.tsv" "$after_dir/config.tsv"
diff -u "$evidence_dir/packages-root.tsv" "$after_dir/packages-root.tsv"
diff -u "$evidence_dir/delivery.tsv" "$after_dir/delivery.tsv"
```
If output differs from the prediction:
- confirm the checkout, dirty state, script revision, flags, and toolchain;
- explain each delta from changed source;
- branch to semantic discovery when a count cannot explain behavior;
- reject a “better” metric that moved duplication, hid a path, or weakened a
gate;
- route the resulting change through validation and fresh adversarial review.
## Record the evidence packet
Report:
1. question and numeric prediction;
2. revision, dirty state, date, tools, and environment constraints;
3. exact commands and exit codes;
4. raw evidence paths;
5. before/after deltas by independent dimension;
6. semantic confirmation for every candidate used in a decision;
7. unexpected results and branch taken;
8. acceptance owner and remaining unknowns.
Short wins count only when they leave a reproducible vertical slice: one
measured problem, one explained change, and no displaced responsibility left
unowned.
## Dated current snapshot
The bundled scripts measured this checkout on 2026-07-28:
| Observation | Unstable value |
|---|---:|
| Root production/test/generated Go files | 123 / 111 / 4 |
| Root production/test/generated physical lines | 25,952 / 31,675 / 157 |
| `cmd/archied.run` body span / approximate complexity | 668 / 96 |
| `internal/config.finalize` body span / approximate complexity | 177 / 64 |
| Root internal packages / direct internal edges | 51 / 129 |
| Tagged config field rows | 110 |
| Tracked paths / tracked `node_modules` paths / tracked symlinks | 558 / 237 / 238 |
| `.dockerignore` present | 0 |
The delivery snapshot found no Taskfile literals for race, the `tools` module,
or docs; no Go-gate literals in either workflow; a docs build in GitHub CI; and
container build/push in Gitea CI. `task check` is mutating because it invokes
`gofumpt -w .` and `go fix ./...`; do not run it as a read-only diagnostic.
Route it to acceptance.
The focused test
`go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v`
failed on 2026-07-28 with `Run() = "\n"`. Preserve that known-red baseline; do
not claim a clean full suite or attribute it to unrelated work.
## Provenance and maintenance
Ground truth verified on 2026-07-28:
`Taskfile.yml`, `.golangci.yml`, `go.mod`, `tools/go.mod`,
`cmd/{archied,archie-agent}/`, `internal/{config,nell,skillscript}/`,
`.github/workflows/docs.yml`, `.gitea/workflows/deploy.yml`,
`docker-compose.yml`, `docs-2/package.json`, and `tools/docsgen/`.
Re-verify scripts: `sh -n .claude/skills/archie-diagnostics-and-tooling/scripts/*.sh && go vet .claude/skills/archie-diagnostics-and-tooling/scripts/source-metrics.go && go vet .claude/skills/archie-diagnostics-and-tooling/scripts/config-use-candidates.go`
Re-verify source baseline: `GOCACHE=/tmp/archie-diagnostics-gocache GOTMPDIR=/tmp go run .claude/skills/archie-diagnostics-and-tooling/scripts/source-metrics.go -root . -top 12`
Re-verify config candidates: `GOCACHE=/tmp/archie-diagnostics-gocache GOTMPDIR=/tmp go run .claude/skills/archie-diagnostics-and-tooling/scripts/config-use-candidates.go -root .`
Re-verify package edges: `.claude/skills/archie-diagnostics-and-tooling/scripts/package-shape.sh .`
Re-verify delivery surfaces: `.claude/skills/archie-diagnostics-and-tooling/scripts/delivery-snapshot.sh`
Re-verify lint thresholds: `rg -n 'cyclop:|dupl:|funlen:|gocognit:|gocyclo:|maintidx:|nestif:' .golangci.yml`
Re-verify current test baseline: `GOCACHE=/tmp/archie-diagnostics-test-cache GOTMPDIR=/tmp GIT_CONFIG_GLOBAL=/dev/null GOPROXY=off GOFLAGS=-mod=readonly go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v`
@@ -0,0 +1,4 @@
interface:
display_name: "Archie Diagnostics and Tooling"
short_description: "Measure maintainability, wiring, and delivery drift"
default_prompt: "Use $archie-diagnostics-and-tooling to collect a dated, reproducible evidence baseline before changing Archie."
@@ -0,0 +1,279 @@
// Command config-use-candidates reports syntax-level selector evidence for
// tagged fields declared by internal/config. Results are candidates, not proof
// that a field is wired, live, or dead.
package main
import (
"flag"
"fmt"
"go/ast"
"go/parser"
"go/token"
"io/fs"
"os"
"path/filepath"
"reflect"
"sort"
"strconv"
"strings"
)
type fieldDefinition struct {
path string
line int
typeName string
fieldName string
tags string
duplicates int
}
type referenceCounts struct {
config int
entrypoint int
production int
test int
generated int
}
func main() {
root := flag.String("root", ".", "repository root to inspect")
flag.Parse()
absoluteRoot, err := filepath.Abs(*root)
if err != nil {
fail(2, "resolve root: %v", err)
}
info, err := os.Stat(absoluteRoot)
if err != nil {
fail(2, "inspect root: %v", err)
}
if !info.IsDir() {
fail(2, "root is not a directory: %s", absoluteRoot)
}
fset := token.NewFileSet()
fields, err := readFieldDefinitions(absoluteRoot, fset)
if err != nil {
fail(1, "%v", err)
}
if len(fields) == 0 {
fail(1, "no tagged fields found under internal/config")
}
nameCounts := map[string]int{}
for _, field := range fields {
nameCounts[field.fieldName]++
}
for index := range fields {
fields[index].duplicates = nameCounts[fields[index].fieldName]
}
references := map[string]*referenceCounts{}
for name := range nameCounts {
references[name] = &referenceCounts{}
}
if err := countSelectors(absoluteRoot, fset, references); err != nil {
fail(1, "%v", err)
}
sort.Slice(fields, func(i, j int) bool {
if fields[i].typeName != fields[j].typeName {
return fields[i].typeName < fields[j].typeName
}
if fields[i].fieldName != fields[j].fieldName {
return fields[i].fieldName < fields[j].fieldName
}
if fields[i].path != fields[j].path {
return fields[i].path < fields[j].path
}
return fields[i].line < fields[j].line
})
fmt.Println("META\tschema\tarchie-config-use-candidates/v1")
fmt.Println("META\tmeaning\tselector-name counts are heuristic candidates; confirm exact fields with gopls references and production composition")
for _, field := range fields {
count := references[field.fieldName]
status := "candidate-selector-seen-in-entrypoint"
switch {
case count.production == 0 && count.entrypoint == 0:
status = "candidate-no-selector-outside-config"
case count.entrypoint == 0:
status = "candidate-no-entrypoint-selector"
}
fmt.Printf(
"CONFIG_FIELD\t%s\t%d\t%s.%s\t%s\t%d\t%d\t%d\t%d\t%d\t%d\t%s\n",
field.path,
field.line,
field.typeName,
field.fieldName,
field.tags,
field.duplicates,
count.config,
count.entrypoint,
count.production,
count.test,
count.generated,
status,
)
}
}
func readFieldDefinitions(root string, fset *token.FileSet) ([]fieldDefinition, error) {
configDir := filepath.Join(root, "internal", "config")
info, err := os.Stat(configDir)
if err != nil {
return nil, fmt.Errorf("inspect internal/config: %w", err)
}
if !info.IsDir() {
return nil, fmt.Errorf("internal/config is not a directory")
}
var fields []fieldDefinition
err = filepath.WalkDir(configDir, func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
if entry.IsDir() || filepath.Ext(entry.Name()) != ".go" || strings.HasSuffix(entry.Name(), "_test.go") {
return nil
}
body, err := os.ReadFile(path)
if err != nil {
return err
}
file, err := parser.ParseFile(fset, path, body, parser.ParseComments)
if err != nil {
return fmt.Errorf("parse %s: %w", path, err)
}
relative, err := filepath.Rel(root, path)
if err != nil {
return err
}
relative = filepath.ToSlash(relative)
for _, declaration := range file.Decls {
general, ok := declaration.(*ast.GenDecl)
if !ok || general.Tok != token.TYPE {
continue
}
for _, specification := range general.Specs {
typeSpec, ok := specification.(*ast.TypeSpec)
if !ok {
continue
}
structType, ok := typeSpec.Type.(*ast.StructType)
if !ok {
continue
}
for _, field := range structType.Fields.List {
tags, ok := configTags(field.Tag)
if !ok {
continue
}
for _, name := range field.Names {
fields = append(fields, fieldDefinition{
path: relative,
line: fset.Position(name.Pos()).Line,
typeName: typeSpec.Name.Name,
fieldName: name.Name,
tags: tags,
})
}
}
}
}
return nil
})
return fields, err
}
func configTags(literal *ast.BasicLit) (string, bool) {
if literal == nil {
return "", false
}
raw, err := strconv.Unquote(literal.Value)
if err != nil {
return "", false
}
tag := reflect.StructTag(raw)
var parts []string
for _, key := range []string{"toml", "yaml", "json"} {
value, ok := tag.Lookup(key)
if !ok {
continue
}
parts = append(parts, key+"="+value)
}
return strings.Join(parts, ";"), len(parts) > 0
}
func countSelectors(root string, fset *token.FileSet, references map[string]*referenceCounts) error {
return filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
relative, err := filepath.Rel(root, path)
if err != nil {
return err
}
relative = filepath.ToSlash(relative)
if entry.IsDir() {
if relative != "." && excludedDirectory(relative, entry.Name()) {
return filepath.SkipDir
}
return nil
}
if filepath.Ext(entry.Name()) != ".go" {
return nil
}
body, err := os.ReadFile(path)
if err != nil {
return err
}
file, err := parser.ParseFile(fset, path, body, parser.ParseComments)
if err != nil {
return fmt.Errorf("parse %s: %w", relative, err)
}
generated := ast.IsGenerated(file)
isTest := strings.HasSuffix(entry.Name(), "_test.go")
inConfig := strings.HasPrefix(relative, "internal/config/")
inEntrypoint := strings.HasPrefix(relative, "cmd/")
ast.Inspect(file, func(node ast.Node) bool {
selector, ok := node.(*ast.SelectorExpr)
if !ok {
return true
}
count := references[selector.Sel.Name]
if count == nil {
return true
}
switch {
case generated:
count.generated++
case isTest:
count.test++
case inConfig:
count.config++
case inEntrypoint:
count.entrypoint++
default:
count.production++
}
return true
})
return nil
})
}
func excludedDirectory(relative, name string) bool {
switch name {
case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp":
return true
}
return strings.HasPrefix(relative, "docs-2/.vitepress/cache") ||
strings.HasPrefix(relative, "docs-2/.vitepress/dist")
}
func fail(code int, format string, arguments ...any) {
fmt.Fprintf(os.Stderr, "config-use-candidates: "+format+"\n", arguments...)
os.Exit(code)
}
@@ -0,0 +1,90 @@
#!/bin/sh
set -eu
if [ "$#" -ne 0 ]; then
printf '%s\n' "usage: delivery-snapshot.sh" >&2
exit 2
fi
for tool in git rg sed wc; do
command -v "$tool" >/dev/null 2>&1 || {
printf 'delivery-snapshot: %s is required\n' "$tool" >&2
exit 127
}
done
script_dir=$(CDPATH= cd "$(dirname "$0")" && pwd)
repo_root=$(CDPATH= cd "$script_dir/../../../.." && pwd)
if [ ! -f "$repo_root/go.mod" ] || [ ! -f "$repo_root/Taskfile.yml" ]; then
printf 'delivery-snapshot: expected Archie repository root at %s\n' "$repo_root" >&2
exit 2
fi
temporary=$(mktemp -d "${TMPDIR:-/tmp}/archie-delivery-snapshot.XXXXXX")
trap 'rm -rf "$temporary"' EXIT HUP INT TERM
cd "$repo_root"
printf '%s\n' "META schema archie-delivery-snapshot/v1"
scan_literal() {
axis=$1
scope=$2
pattern=$3
shift 3
result="$temporary/$axis"
if rg -n --no-heading --color never -e "$pattern" "$@" >"$result"; then
:
else
status=$?
if [ "$status" -ne 1 ]; then
printf 'delivery-snapshot: scan failed for %s\n' "$axis" >&2
exit "$status"
fi
fi
count=$(wc -l <"$result" | sed 's/[[:space:]]//g')
printf 'SURFACE\t%s\t%s\t%s\n' "$axis" "$scope" "$count"
}
scan_literal task_format taskfile 'gofumpt[[:space:]]+-w|go fix' Taskfile.yml
scan_literal task_vet taskfile 'go vet' Taskfile.yml
scan_literal task_build taskfile 'go build|task:[[:space:]]+build' Taskfile.yml
scan_literal task_test taskfile 'go test|task:[[:space:]]+test' Taskfile.yml
scan_literal task_lint taskfile 'golangci-lint|task:[[:space:]]+lint' Taskfile.yml
scan_literal task_race taskfile 'go test[^#\n]*-race|-race[^#\n]*go test' Taskfile.yml
scan_literal task_tools_module taskfile 'go -C tools|cd tools|task:[[:space:]]+tools' Taskfile.yml
scan_literal task_docs taskfile 'docsgen|pnpm[^#\n]*build|docs:generate|docs:check' Taskfile.yml
scan_literal github_go_gate github-workflows 'go test|go vet|go build|golangci-lint|task[[:space:]]+check' .github/workflows
scan_literal github_docs_build github-workflows 'pnpm[[:space:]]+build|vitepress[[:space:]]+build' .github/workflows
scan_literal gitea_go_gate gitea-workflows 'go test|go vet|go build|golangci-lint|task[[:space:]]+check' .gitea/workflows
scan_literal gitea_container_publish gitea-workflows 'docker build|docker push' .gitea/workflows
scan_literal production_load_overlay composition-root 'config\.LoadOverlay\(' cmd/archied/main.go
scan_literal production_load_dir composition-root 'config\.LoadDir\(' cmd/archied/main.go
scan_literal production_nell_store composition-root 'nell\.OpenStore\(' cmd/archied/main.go
scan_literal production_daemon composition-root '&daemon\.Daemon\{' cmd/archied/main.go
scan_literal production_rpc_servers composition-root 'registerTaskRPCServers\(' cmd/archied/main.go
git ls-files >"$temporary/tracked"
tracked_total=$(wc -l <"$temporary/tracked" | sed 's/[[:space:]]//g')
tracked_node_modules=$(rg -c '(^|/)node_modules(/|$)' "$temporary/tracked" || true)
tracked_artifacts=$(rg -c '(^|/)(node_modules|bin|dist|\.gotmp)(/|$)|\.(exe|test|out)$' "$temporary/tracked" || true)
tracked_symlinks=$(git ls-files -s | awk '$1 == "120000" {count++} END {print count + 0}')
printf 'HYGIENE\ttracked_paths\t%s\n' "$tracked_total"
printf 'HYGIENE\ttracked_node_modules_paths\t%s\n' "${tracked_node_modules:-0}"
printf 'HYGIENE\ttracked_artifact_candidates\t%s\n' "${tracked_artifacts:-0}"
printf 'HYGIENE\ttracked_symlinks\t%s\n' "$tracked_symlinks"
if [ -f .dockerignore ]; then
printf '%s\n' "HYGIENE dockerignore_present 1"
else
printf '%s\n' "HYGIENE dockerignore_present 0"
fi
find . \
\( -path './.git' -o -path './.claude' -o -path './.references' -o -name node_modules \) -prune -o \
-name go.mod -print |
LC_ALL=C sort |
while IFS= read -r module; do
printf 'MODULE\t%s\n' "$module"
done
@@ -0,0 +1,86 @@
#!/bin/sh
set -eu
if [ "$#" -gt 1 ]; then
printf '%s\n' "usage: $0 [module-directory-relative-to-repo]" >&2
exit 2
fi
command -v go >/dev/null 2>&1 || {
printf '%s\n' "package-shape: go is required" >&2
exit 127
}
command -v awk >/dev/null 2>&1 || {
printf '%s\n' "package-shape: awk is required" >&2
exit 127
}
script_dir=$(CDPATH= cd "$(dirname "$0")" && pwd)
repo_root=$(CDPATH= cd "$script_dir/../../../.." && pwd)
module_relative=${1:-.}
module_root="$repo_root/$module_relative"
edge_helper="$repo_root/.claude/skills/archie-codebase-discovery/scripts/package-edges.sh"
if [ ! -f "$module_root/go.mod" ]; then
printf 'package-shape: no go.mod at %s\n' "$module_root" >&2
exit 2
fi
if [ ! -x "$edge_helper" ]; then
printf 'package-shape: required sibling helper is missing or not executable: %s\n' "$edge_helper" >&2
exit 2
fi
temporary=$(mktemp -d "${TMPDIR:-/tmp}/archie-package-shape.XXXXXX")
trap 'rm -rf "$temporary"' EXIT HUP INT TERM
mkdir -p "$temporary/cache" "$temporary/build-tmp"
export GOCACHE="$temporary/cache"
export GOTMPDIR="$temporary/build-tmp"
export GOPROXY=off
export GOFLAGS="-mod=readonly -buildvcs=false"
export ARCHIE_DISCOVERY_CACHE="$temporary/discovery"
(
cd "$module_root"
go list ./... | LC_ALL=C sort
) >"$temporary/packages"
if (
cd "$module_root"
"$edge_helper" ./...
) >"$temporary/edges" 2>"$temporary/edge-stderr"; then
# The sibling helper sets its own GOFLAGS and can trigger a harmless,
# nondeterministic temporary filename when GOMODCACHE is read-only.
# Preserve the warning while normalizing only that filename suffix.
sed 's/\.info[0-9][0-9]*\.tmp/.info<TEMP>.tmp/' "$temporary/edge-stderr" >&2
else
status=$?
cat "$temporary/edge-stderr" >&2
exit "$status"
fi
(
cd "$module_root"
go list -m -f '{{.Path}}'
) >"$temporary/module"
module_path=$(sed -n '1p' "$temporary/module")
printf '%s\n' "META schema archie-package-shape/v1"
printf 'META\tmodule\t%s\n' "$module_path"
awk -F ' ' '
NR == FNR {
packages[$0] = 1
next
}
{
split($0, edge, " -> ")
outbound[edge[1]]++
inbound[edge[2]]++
}
END {
for (packageName in packages) {
printf "PACKAGE\t%s\t%d\t%d\n", packageName, inbound[packageName] + 0, outbound[packageName] + 0
}
}
' "$temporary/packages" "$temporary/edges" | LC_ALL=C sort
awk '{printf "EDGE\t%s\n", $0}' "$temporary/edges"
@@ -0,0 +1,352 @@
// Command source-metrics emits deterministic, syntax-derived Go source metrics.
// It never writes to the inspected tree and uses only the Go standard library.
package main
import (
"bytes"
"flag"
"fmt"
"go/ast"
"go/parser"
"go/token"
"io/fs"
"os"
"path/filepath"
"sort"
"strings"
)
type counts struct {
productionFiles int
testFiles int
generatedFiles int
productionLines int
testLines int
generatedLines int
functions int
methods int
}
type packageCounts struct {
module string
path string
productionFiles int
testFiles int
generatedFiles int
productionLines int
testLines int
generatedLines int
}
type hotspot struct {
module string
path string
line int
symbol string
spanLines int
statements int
complexity int
}
func main() {
root := flag.String("root", ".", "repository root to inspect")
top := flag.Int("top", 30, "maximum hotspot rows; zero means all")
largeLines := flag.Int("large-lines", 80, "minimum body span for a hotspot")
complexity := flag.Int("complexity", 15, "minimum approximate syntactic complexity for a hotspot")
includeTests := flag.Bool("include-test-hotspots", false, "include test functions in hotspot rows")
flag.Parse()
if *top < 0 || *largeLines < 1 || *complexity < 1 {
fail(2, "top must be non-negative; thresholds must be positive")
}
absoluteRoot, err := filepath.Abs(*root)
if err != nil {
fail(2, "resolve root: %v", err)
}
info, err := os.Stat(absoluteRoot)
if err != nil {
fail(2, "inspect root: %v", err)
}
if !info.IsDir() {
fail(2, "root is not a directory: %s", absoluteRoot)
}
modules := map[string]*counts{}
packages := map[string]*packageCounts{}
var hotspots []hotspot
fset := token.NewFileSet()
err = filepath.WalkDir(absoluteRoot, func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
relative, err := filepath.Rel(absoluteRoot, path)
if err != nil {
return err
}
relative = filepath.ToSlash(relative)
if entry.IsDir() {
if relative != "." && excludedDirectory(relative, entry.Name()) {
return filepath.SkipDir
}
return nil
}
if filepath.Ext(entry.Name()) != ".go" {
return nil
}
body, err := os.ReadFile(path)
if err != nil {
return err
}
file, err := parser.ParseFile(fset, path, body, parser.ParseComments)
if err != nil {
return fmt.Errorf("parse %s: %w", relative, err)
}
module := moduleFor(relative)
moduleCounts := modules[module]
if moduleCounts == nil {
moduleCounts = &counts{}
modules[module] = moduleCounts
}
dir := filepath.ToSlash(filepath.Dir(relative))
packageKey := module + "\x00" + dir
pkg := packages[packageKey]
if pkg == nil {
pkg = &packageCounts{module: module, path: dir}
packages[packageKey] = pkg
}
lines := physicalLines(body)
generated := ast.IsGenerated(file)
isTest := strings.HasSuffix(entry.Name(), "_test.go")
switch {
case generated:
moduleCounts.generatedFiles++
moduleCounts.generatedLines += lines
pkg.generatedFiles++
pkg.generatedLines += lines
case isTest:
moduleCounts.testFiles++
moduleCounts.testLines += lines
pkg.testFiles++
pkg.testLines += lines
default:
moduleCounts.productionFiles++
moduleCounts.productionLines += lines
pkg.productionFiles++
pkg.productionLines += lines
}
for _, declaration := range file.Decls {
function, ok := declaration.(*ast.FuncDecl)
if !ok || function.Body == nil {
continue
}
if function.Recv == nil {
moduleCounts.functions++
} else {
moduleCounts.methods++
}
if generated || (isTest && !*includeTests) {
continue
}
start := fset.Position(function.Body.Lbrace).Line
end := fset.Position(function.Body.Rbrace).Line
row := hotspot{
module: module,
path: relative,
line: fset.Position(function.Pos()).Line,
symbol: symbolName(function),
spanLines: end - start + 1,
statements: statementNodes(function.Body),
complexity: syntacticComplexity(function.Body),
}
if row.spanLines >= *largeLines || row.complexity >= *complexity {
hotspots = append(hotspots, row)
}
}
return nil
})
if err != nil {
fail(1, "%v", err)
}
fmt.Println("META\tschema\tarchie-source-metrics/v1")
fmt.Printf("META\tthresholds\tlarge_lines=%d;syntactic_complexity=%d;top=%d\n", *largeLines, *complexity, *top)
moduleNames := sortedKeys(modules)
for _, module := range moduleNames {
value := modules[module]
emitMetric(module, "production_go_files", value.productionFiles)
emitMetric(module, "test_go_files", value.testFiles)
emitMetric(module, "generated_go_files", value.generatedFiles)
emitMetric(module, "production_physical_lines", value.productionLines)
emitMetric(module, "test_physical_lines", value.testLines)
emitMetric(module, "generated_physical_lines", value.generatedLines)
emitMetric(module, "functions", value.functions)
emitMetric(module, "methods", value.methods)
}
packageRows := make([]*packageCounts, 0, len(packages))
for _, row := range packages {
packageRows = append(packageRows, row)
}
sort.Slice(packageRows, func(i, j int) bool {
if packageRows[i].module != packageRows[j].module {
return packageRows[i].module < packageRows[j].module
}
return packageRows[i].path < packageRows[j].path
})
for _, row := range packageRows {
fmt.Printf(
"PACKAGE\t%s\t%s\t%d\t%d\t%d\t%d\t%d\t%d\n",
row.module,
row.path,
row.productionFiles,
row.testFiles,
row.generatedFiles,
row.productionLines,
row.testLines,
row.generatedLines,
)
}
sort.Slice(hotspots, func(i, j int) bool {
if hotspots[i].spanLines != hotspots[j].spanLines {
return hotspots[i].spanLines > hotspots[j].spanLines
}
if hotspots[i].complexity != hotspots[j].complexity {
return hotspots[i].complexity > hotspots[j].complexity
}
if hotspots[i].path != hotspots[j].path {
return hotspots[i].path < hotspots[j].path
}
if hotspots[i].line != hotspots[j].line {
return hotspots[i].line < hotspots[j].line
}
return hotspots[i].symbol < hotspots[j].symbol
})
if *top > 0 && len(hotspots) > *top {
hotspots = hotspots[:*top]
}
for _, row := range hotspots {
fmt.Printf(
"HOTSPOT\t%s\t%s\t%d\t%s\t%d\t%d\t%d\n",
row.module,
row.path,
row.line,
row.symbol,
row.spanLines,
row.statements,
row.complexity,
)
}
}
func excludedDirectory(relative, name string) bool {
switch name {
case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp":
return true
}
return strings.HasPrefix(relative, "docs-2/.vitepress/cache") ||
strings.HasPrefix(relative, "docs-2/.vitepress/dist")
}
func moduleFor(relative string) string {
if relative == "tools" || strings.HasPrefix(relative, "tools/") {
return "tools"
}
return "root"
}
func physicalLines(body []byte) int {
if len(body) == 0 {
return 0
}
lines := bytes.Count(body, []byte{'\n'})
if body[len(body)-1] != '\n' {
lines++
}
return lines
}
func symbolName(function *ast.FuncDecl) string {
if function.Recv == nil || len(function.Recv.List) == 0 {
return function.Name.Name
}
return receiverName(function.Recv.List[0].Type) + "." + function.Name.Name
}
func receiverName(expression ast.Expr) string {
switch value := expression.(type) {
case *ast.Ident:
return value.Name
case *ast.StarExpr:
return "*" + receiverName(value.X)
case *ast.IndexExpr:
return receiverName(value.X)
case *ast.IndexListExpr:
return receiverName(value.X)
default:
return "receiver"
}
}
func statementNodes(node ast.Node) int {
count := 0
ast.Inspect(node, func(candidate ast.Node) bool {
statement, ok := candidate.(ast.Stmt)
if !ok {
return true
}
switch statement.(type) {
case *ast.BlockStmt, *ast.EmptyStmt:
default:
count++
}
return true
})
return count
}
func syntacticComplexity(node ast.Node) int {
value := 1
ast.Inspect(node, func(candidate ast.Node) bool {
switch item := candidate.(type) {
case *ast.IfStmt, *ast.ForStmt, *ast.RangeStmt, *ast.CommClause:
value++
case *ast.CaseClause:
if len(item.List) > 0 {
value++
}
case *ast.BinaryExpr:
if item.Op == token.LAND || item.Op == token.LOR {
value++
}
}
return true
})
return value
}
func sortedKeys(values map[string]*counts) []string {
keys := make([]string, 0, len(values))
for key := range values {
keys = append(keys, key)
}
sort.Strings(keys)
return keys
}
func emitMetric(module, name string, value int) {
fmt.Printf("METRIC\t%s\t%s\t%d\n", module, name, value)
}
func fail(code int, format string, arguments ...any) {
fmt.Fprintf(os.Stderr, "source-metrics: "+format+"\n", arguments...)
os.Exit(code)
}
@@ -0,0 +1,350 @@
---
name: archie-docs-and-writing
description: Maintain Archie's documentation of record and write durable architecture decisions, migration plans, parity matrices, incident and dead-end records, feature ownership and deprecation records, operational runbooks, and documentation reviews. Use when deciding where an Archie fact belongs; reconciling code with ARCHITECTURE.md, CLAUDE.md, docs/prds, docs/archive, generated contracts, or the docs-2 VitePress site; changing tools/docsgen; documenting a feature so future maintainers can find its owners, consumers, invariants, superseded paths, deletion gates, evidence, and rollback; or checking documentation authority, drift, links, copied content, and source-artifact hygiene.
---
# Maintain Archie documentation
Write one durable record for each decision or behavior. Separate what runs now
from what Archie has approved as its destination. Make a future feature change
possible without rediscovering every code path.
## Route work before writing
Do not use this skill to make the underlying decision, investigate an incident,
or certify a code change:
| Need | Load instead |
|---|---|
| Decide package ownership, boundaries, or migration order | `archie-architecture-planning-campaign` |
| Check a load-bearing invariant | `archie-architecture-contract` |
| Map live entry points, consumers, and call paths | `archie-codebase-discovery` |
| Establish feature ownership, supersession, or deletion accountability | `archie-technical-accountability` |
| Reconstruct an incident, revert, or rejected fix | `archie-failure-archaeology` |
| Change configuration, build, deployment, or operations | `archie-config-and-flags`, `archie-build-and-env`, or `archie-run-and-operate` |
| Gate or accept a change | `archie-change-control` and `archie-validation-and-qa` |
| Turn an unproven hypothesis into evidence | `archie-research-methodology` |
Return here after those skills establish the facts or decision. Record their
result without broadening it.
## Use the authority vocabulary
Define a **record of authority** as the one canonical location whose owner may
change a claim. Label every material statement with one of these states:
| State | Meaning | Permitted wording |
|---|---|---|
| `CURRENT` | Verified behavior in the checked-out code, tests, composition, or executable config | “Currently does” |
| `APPROVED TARGET` | Normative destination approved in the architecture index | “Must become”; never “currently does” |
| `OPEN` | Investigation, candidate, or unresolved decision | “Candidate”, “unknown”, or “requires decision” |
| `HISTORICAL` | Prior design, incident, dead end, or superseded choice | “Previously did”; never normative |
| `GENERATED` | Derivative output produced from an owned source definition | “Generated from”; never hand-edit |
| `EXTERNAL` | Fact held outside this repository, such as deployed config or host state | Date, name the verifier, and give a re-check command |
When `CURRENT` conflicts with `APPROVED TARGET`, preserve both and state the
migration delta. Do not rewrite the target to match accidental code. Do not
describe target behavior as implemented merely because a PRD uses normative
language.
## Use the repository authority map
Treat this as a volatile map verified on 2026-07-28:
| Location | Role | Discipline |
|---|---|---|
| Live Go code, tests, `Taskfile.yml`, executable config parsing, and composition under `cmd/` | `CURRENT` execution evidence | Trace producers and consumers; tests prove only their asserted behavior |
| `CLAUDE.md` | Current contributor and safety protocol plus a compact architecture orientation | Verify operational claims against code and `Taskfile.yml`; `AGENTS.md` is a symlink to this file |
| `ARCHITECTURE.md` | Useful architecture history and partial current overview | Corroborate every inventory/status claim; its “Planned” list is stale for implemented skill support |
| `docs/prds/01-project-management.md` | Index and approved foundation for the target architecture | Add or change target decisions in the focused document it names |
| `docs/prds/architecture/*.md` | Focused target decisions, active review procedure, and migration inventory | Read each file's status; distinguish fixed decisions from explicitly remaining decisions |
| `docs/prds/architecture/migration-decisions.md` | `OPEN` migration inventory constrained by approved decisions | Close a question only after code-grounded review and an approved record |
| `docs/archive/` | `HISTORICAL` material | Mine rationale and failure evidence; never restore authority from a title such as “Final” |
| `CHANGELOG.md`, `CHANGELOG.archied.md`, `CHANGELOG.archie.md` | Component release-note index and packaged runtime inputs | Keep gateway and agent-runtime entries separate; `internal/releaseannounce` parses the version headings |
| `tools/docsgen` | Current, partial generator implementation in the nested `tools` Go module | Treat its flags and tests—not planned PRD commands—as executable truth |
| `docs-2/data/generated/contracts.json` | Current working-tree `GENERATED` output | Regenerate; never edit by hand; re-check whether it is tracked |
| `docs-2/` | Staging VitePress site | Do not treat a rendered summary as the architecture record |
| `.github/workflows/docs.yml` | Current Pages build/deploy workflow | It builds the site; it does not currently run Go setup, generator tests, or drift checking |
The repository root has no `README.md` or `CONTRIBUTING.md` as of 2026-07-28.
Record this as an onboarding coverage gap, not permission to invent a new
authority. `docs-2/README.md` is excluded by VitePress and still contains copied
Tau material; it is not a root onboarding guide.
## Choose one destination
1. State the reader's question in one sentence.
2. Identify the owner of the behavior or decision.
3. Find the existing record of authority.
4. Extend that record or link to it. Do not make a second canonical table.
5. If no owner exists, stop and route the ownership decision through
`archie-technical-accountability` or the architecture campaign.
6. If the fact is generated, change the owned source definition and generator;
do not patch output.
7. If the fact is external, date it and name the exact observation command.
Use this placement guide:
| Content | Destination |
|---|---|
| Cross-cutting approved architecture index | `docs/prds/01-project-management.md` |
| Focused domain or requirement decision | The matching `docs/prds/architecture/*.md` file |
| Unresolved migration question or cutover requirement | `docs/prds/architecture/migration-decisions.md` |
| Contributor protocol that must load before work | `CLAUDE.md` |
| Runtime/API/config reference derivable from code | Domain-owned registry/type, then `tools/docsgen` output |
| User-facing staging site prose | `docs-2/`, linking back to its authority |
| Shipped release behavior | The matching component changelog; keep `CHANGELOG.md` as the two-component index |
| Superseded design retained only for context | `docs/archive/`, with historical status |
| Incident or rejected approach | `archie-failure-archaeology`'s authoritative chronology |
Do not duplicate a package map in `CLAUDE.md`, `ARCHITECTURE.md`, a PRD, and the
site. Name the authoritative map and link to it.
## Research before drafting
Run from the repository root:
```bash
rg -n 'ExactTerm|RelatedTerm' --glob '*.go' --glob '*.md' --glob '*.toml' --glob '*.yml'
rg -n 'type ExactType|func .*ExactMethod|ExactConfigField' cmd internal domain tools
rg -n 'ExactType|ExactMethod' --glob '*_test.go'
rg -n 'ExactTerm' docs/prds ARCHITECTURE.md CLAUDE.md docs/archive docs-2
```
Then build a fact ledger:
| Claim | State | Owner | Evidence | Conflicts | Destination |
|---|---|---|---|---|---|
| One precise claim | `CURRENT` / `APPROVED TARGET` / `OPEN` | Domain or boundary | `path` + symbol/test/heading | Other path or none | Existing authority |
Investigate entry points, runtime composition, persistence, configuration,
consumers, tests, failure behavior, duplicate implementations, and stale docs.
Do not ask the user a question that repository evidence can answer.
## Write for future change
Every architecture, feature, or migration record must answer:
- **Responsibility:** What cohesive job exists?
- **Owner:** Which domain, application boundary, or infrastructure adapter owns
its meaning and mutable state?
- **Boundaries:** What is explicitly inside and outside?
- **Consumers:** Which entry points, interfaces, commands, events, config, and
processes depend on it?
- **Invariants:** What must remain true, and where is each invariant enforced?
- **Superseded path:** Which older mechanism becomes redundant?
- **Deletion gate:** What observable proof permits removal, and what temporary
compatibility has an expiry condition?
- **Evidence:** Which symbols, tests, commands, and runtime observations support
the record?
- **Rollback:** How can behavior and data return safely?
- **Unresolved questions:** What remains `OPEN`, who owns the decision, and what
evidence will close it?
Name one owner for every mutable record. Name every current code path that
performs the same operation. A new path is incomplete until the document says
whether each older path remains, delegates, migrates, or is deleted.
Use [references/templates.md](references/templates.md) when drafting an ADR,
migration/parity plan, incident/dead-end record, feature ownership/deprecation
record, operational runbook, or docs review. Copy only the matching template;
delete prompts that do not apply rather than filling them with ceremony.
## Cite evidence without freezing line numbers
Prefer:
- repository-relative path plus exact Go symbol, test name, config key, workflow
job/step, or Markdown heading;
- a relative Markdown link to the record of authority;
- the command that re-discovers the evidence.
Write `internal/agentexec.Request` and `tools/docsgen.currentContractTypes`, for
example. Avoid permanent `file.go:123` citations: line numbers drift without
changing meaning. Use line numbers in a time-bounded review comment only.
Distinguish evidence strength:
1. Runtime composition and executable behavior.
2. Tests that exercise the relevant production seam.
3. Approved target decision.
4. Comments and summaries corroborated by the first three.
5. Historical or external notes, explicitly dated.
## Maintain component changelogs
Keep gateway behavior in `CHANGELOG.archied.md` and agent-runtime behavior in
`CHANGELOG.archie.md`; keep `CHANGELOG.md` as their index. The archied image
copies both component files to `/usr/share/archie/`, and
`internal/releaseannounce.changelogSection` parses a version heading to build
Telegram update messages.
Do not copy the current heading format without investigation. A verified
2026-07-28 contradiction is `OPEN`:
- `.gitea/workflows/deploy.yml` passes `vX.Y.Z` component versions.
- `changelogSection` searches for `## [<version>]`, and its fixtures use
`## [v0.1.0]`.
- The two current component changelogs use headings such as `## [1.1.0]`
without `v`.
- `cmd/archied.TestChangelogsTrackGatewayAndRuntimeIndependently` explicitly
expects the unprefixed current heading.
Resolve the parser, release metadata tests, and both documents atomically
through `archie-change-control`; do not “fix” only the prose. Until resolved,
do not claim that a current component entry is parseable by the deployed
release announcer.
## Maintain generated contracts
The current implementation is smaller than the approved target in
`docs/prds/architecture/generated-documentation.md`.
### Current behavior, verified 2026-07-28
- The tool path is `tools/docsgen`, not `tools/cmd/docsgen`.
- It is a separate Go module that replaces the root module with `../`.
- It accepts `--repo-root` and `--out`; it has no implemented `data`,
`asyncapi`, `all`, or `check` subcommands.
- `currentContractTypes` explicitly publishes three top-level contracts and
collects their referenced schemas into one JSON object.
- Its default output is `docs-2/data/generated/contracts.json`.
- The current test proves byte-identical repeated output, expected top-level
contracts, resolvable local references, duplicate/conflict rejection, and
filesystem/source error reporting.
- The output in this working tree matches a fresh temporary generation, but
`git ls-files` reports it as untracked. Re-check before relying on it in CI.
Test and compare without changing the repository:
```bash
GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools test ./docsgen -count=1
docs_tmp="$(mktemp /tmp/archie-contracts.XXXXXX.json)"
GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools run ./docsgen --repo-root .. --out "$docs_tmp"
cmp "$docs_tmp" docs-2/data/generated/contracts.json
```
Exit status `0` from `cmp` means the one current output matches. This is not a
complete obsolete-file, site-route, or target-registry drift check.
Regenerate the working-tree output only when the change is classified and
authorized:
```bash
GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools run ./docsgen --repo-root ..
```
Treat the PRD's `docsgen all`, `docsgen check`, and `task docs:*` commands as
`APPROVED TARGET`. Do not run or document them as current until their CLI and
Taskfile entries exist and tests prove them.
## Maintain the VitePress staging site
Current behavior, verified 2026-07-28:
| Surface | Current state |
|---|---|
| Package | `docs-2/package.json`; VitePress `^1.6.4`; pnpm lockfile resolves 1.6.4 |
| Site config | Archie title, local search, clean URLs, last-updated metadata, output at `.vitepress/dist` |
| Published prose | Handwritten home and architecture pages; no generated-data loader is present |
| Copied content | `docs-2/README.md` describes Tau and is excluded by `srcExclude` |
| Workflow | Frozen-lockfile install, `pnpm build`, Pages artifact upload/deploy |
| Versioning | pnpm major `10`; Node is `latest`, so the Node input is volatile |
| Missing gates | No Go setup, docsgen test, generator drift check, or root `task check` integration |
Run the implemented site commands for review and acceptance:
```bash
pnpm --dir docs-2 install --frozen-lockfile
pnpm --dir docs-2 build
```
Use `build` for review evidence.
### Interactive authoring (not for automated acceptance)
```bash
pnpm --dir docs-2 dev
```
This starts a long-running dev server at `http://localhost:5173` (by default).
Only use it for interactive authoring; stop it with `Ctrl-C` before proceeding.
It is not an acceptance gate. Record the exact pnpm and Node
versions in failure reports because CI currently permits version drift.
### Enforce source-artifact hygiene
As of 2026-07-28, Git tracks 237 `docs-2/node_modules` symlink entries.
Neither `docs-2/node_modules` nor `docs-2/.vitepress/dist` is ignored by the
root `.gitignore`. Treat cleanup and ignore changes as a classified repository
change; route them through `archie-change-control`.
Before review, inspect rather than assuming:
```bash
git ls-files -s 'docs-2/node_modules/**' | awk '$1 == 120000 { count++ } END { print count + 0 }'
git ls-files 'docs-2/.vitepress/dist/**'
git check-ignore -v docs-2/node_modules docs-2/.vitepress/dist || true
rg -n -i 'tau|template|placeholder' docs-2 --glob '!node_modules/**'
```
Never stage dependency installs, VitePress output, generator scratch files,
credentials, absolute paths, wall-clock data, or machine-specific values.
## Review a documentation change
Require all of the following:
- [ ] The document names its state, date, scope, owner, and record of authority.
- [ ] `CURRENT`, `APPROVED TARGET`, `OPEN`, `HISTORICAL`, `GENERATED`, and
`EXTERNAL` claims are not blended.
- [ ] Every code claim has a path plus symbol, test, config key, or workflow
step that can be re-discovered.
- [ ] The writer traced consumers and runtime composition, not just type
declarations.
- [ ] The document states boundaries, invariants, superseded paths, deletion
gates, evidence, rollback, and unresolved questions where applicable.
- [ ] No authoritative table or definition is copied from another owner.
- [ ] Generated files were regenerated, not hand-edited.
- [ ] Release notes use the correct component file, and release metadata,
parser behavior, tests, and version headings agree.
- [ ] Generator tests and a non-mutating drift comparison pass.
- [ ] `pnpm --dir docs-2 build` passes for site changes.
- [ ] Copied product text and tracked build/dependency artifacts are absent from
the intended change.
- [ ] Behavior-changing decisions passed `archie-change-control` and
`archie-validation-and-qa`.
Reject “the code is self-explanatory,” “temporary compatibility” without a
deletion gate, and status-free future tense. A durable record must let a new
engineer determine what exists, what should replace it, and how to prove the
transition.
## Provenance and maintenance
Last verified against the checked-out repository on 2026-07-28. Re-run these
one-line checks before relying on volatile facts:
```bash
test -L AGENTS.md && readlink AGENTS.md && test ! -e README.md && test ! -e CONTRIBUTING.md
```
```bash
rg -n '^\\*\\*Status:\\*\\*|^# ' docs/prds/01-project-management.md docs/prds/architecture/*.md docs/archive/*.md
```
```bash
rg -n 'docsgen|docs:|pnpm|vitepress|CHANGELOG' Taskfile.yml .github/workflows/docs.yml tools/docsgen docs-2/package.json docs-2/.vitepress/config.mts Dockerfile.archied internal/releaseannounce cmd/archied
```
```bash
GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools test ./docsgen -count=1
```
```bash
docs_tmp="$(mktemp /tmp/archie-contracts.XXXXXX.json)"; GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools run ./docsgen --repo-root .. --out "$docs_tmp" && cmp "$docs_tmp" docs-2/data/generated/contracts.json
```
```bash
git status --short -- docs-2 tools docs/prds/architecture/generated-documentation.md .github/workflows/docs.yml; git ls-files -s 'docs-2/node_modules/**' | awk '$1 == 120000 { count++ } END { print count + 0 }'
```
@@ -0,0 +1,4 @@
interface:
display_name: "Archie Docs and Writing"
short_description: "Maintain authoritative Archie documentation"
default_prompt: "Use $archie-docs-and-writing to write or update an authoritative Archie design, migration, incident, ownership, or operations document."
@@ -0,0 +1,364 @@
# Archie durable-writing templates
Use one template at a time. Replace every angle-bracket prompt. Remove unused
sections. Keep facts, decisions, and open questions visibly separate.
## Contents
- [Architecture decision record](#architecture-decision-record)
- [Migration plan and parity matrix](#migration-plan-and-parity-matrix)
- [Incident or dead-end record](#incident-or-dead-end-record)
- [Feature ownership and deprecation record](#feature-ownership-and-deprecation-record)
- [Operational runbook](#operational-runbook)
- [Documentation change review](#documentation-change-review)
## Architecture decision record
````markdown
# <Decision title>
**Status:** Proposed | Approved | Superseded by <link>
**Date:** YYYY-MM-DD
**Owner:** <domain or application boundary>
**Record of authority:** <this document or existing focused document>
**Change-control reference:** <issue/review identifier>
## Decision
<One unambiguous normative statement.>
## Problem and scope
<Describe the problem, the included behavior, and explicit non-goals.>
## Current evidence
| Claim | Evidence |
|---|---|
| <CURRENT behavior> | `<path>` — `<symbol/test/config key>` |
## Constraints and invariants
- <Invariant and where it is enforced>
## Consumers and boundaries
| Consumer | Contract used | Failure effect |
|---|---|---|
| <entry point/package/process> | <interface/command/event/data> | <effect> |
## Options considered
| Option | Benefits | Costs and risks | Evidence | Result |
|---|---|---|---|---|
| <option> | <benefit> | <cost> | <measurement/source> | Accepted / Rejected |
## Consequences
<State new responsibilities, dependency direction, state ownership, and
operational effects.>
## Supersession and deletion
- Superseded path: `<path/symbol>` or none
- Compatibility owner: <owner or none>
- Deletion gate: <observable proof>
- Architecture test: <test or OPEN>
## Rollback
<State how code, behavior, and data return safely.>
## Open questions
| Question | Owner | Evidence required | Decision deadline/gate |
|---|---|---|---|
| <OPEN question> | <owner> | <measurement> | <gate> |
## Validation
- `<exact command>` — expected <observable result>
````
## Migration plan and parity matrix
````markdown
# <Capability> migration plan
**Status:** Proposed | Approved | In progress | Complete
**Date:** YYYY-MM-DD
**Owner:** <domain>
**Source authority:** <approved target decision>
**Current baseline:** <code paths and runtime composition>
## Outcome
<Describe the final single authoritative path and what becomes easier to
change.>
## Current-path inventory
| Operation | Entry point | Owner today | State/data touched | Consumers | Disposition |
|---|---|---|---|---|---|
| <operation> | `<path.Symbol>` | <owner/none> | <state> | <consumers> | Keep / Adapt / Merge / Delete |
## Parity matrix
| Behavior | Current evidence | Target owner/path | Required parity | Test or observation | Status |
|---|---|---|---|---|---|
| <behavior> | `<test/symbol/log>` | <target> | <exact result> | `<command>` | OPEN |
Include success, validation failure, retry, cancellation, crash recovery,
authorization, persistence, event emission, and shutdown where applicable.
## Dependency and data movement
| From | To | Adapter/backfill | Consistency rule | Rollback |
|---|---|---|---|---|
| <source> | <target> | <mechanism> | <invariant> | <method> |
## Slices and gates
### Slice 1 — <small vertical outcome>
- Change: <bounded change>
- Expected evidence: <number/result predicted before implementation>
- Command: `<exact command>`
- Pass: <observable result>
- Branch if not: <diagnostic route>
- Legacy path after slice: Active / Delegating / Read-only / Removable
<Repeat for each independently reviewable slice.>
## Cutover
1. <Prepare compatibility/data>
2. <Change production composition>
3. <Observe explicit health/parity signals>
4. <Disable legacy entry>
5. <Delete only after the deletion gate>
## Deletion gates
| Legacy path | Replacement proof | Consumer-zero proof | Data proof | Removal test |
|---|---|---|---|---|
| `<path.Symbol>` | <proof> | <search/inventory> | <proof> | `<command>` |
## Rollback and stop conditions
- Roll back when: <condition>
- Restore: <code/config/data sequence>
- Preserve for diagnosis: <artifacts>
## Remaining open decisions
| Decision | Owner | Evidence needed | Blocks |
|---|---|---|---|
| <OPEN> | <owner> | <evidence> | <slice/cutover> |
````
## Incident or dead-end record
````markdown
# <Symptom or rejected approach>
**Status:** Resolved | Mitigated | Rejected | Reopened
**Observed:** YYYY-MM-DD
**Last verified:** YYYY-MM-DD
**Owner:** <capability>
**Related changes:** <commit/issue/PR identifiers>
## Symptom and impact
<State the observable failure, affected path, and cost. Do not begin with the
proposed fix.>
## Reproduction
```text
<exact non-secret command or event sequence>
```
Expected: <result>
Observed: <result>
## Investigation chronology
| Time/order | Hypothesis | Prediction | Evidence | Result |
|---|---|---|---|---|
| 1 | <hypothesis> | <expected observation> | `<command/log/test>` | Confirmed / Rejected |
## Root cause
<Name the owning code path and causal mechanism. Separate cause from trigger.>
## Attempted or rejected fixes
| Fix | Why plausible | Evidence against it | Status |
|---|---|---|---|
| <approach> | <reason> | <test/runtime evidence> | Rejected / Reverted |
## Resolution and invariant
- Resolution: <what changed>
- Preserved invariant: <what must not regress>
- Regression test: `<test name/path>`
- Operational signal: <log/metric/state>
## Reopen condition
<State the evidence that would justify revisiting the settled result.>
````
## Feature ownership and deprecation record
````markdown
# <Feature/capability> ownership
**Status:** Current | Migrating | Deprecated | Removed
**Date:** YYYY-MM-DD
**Behavior owner:** <domain>
**State owner:** <domain/repository>
**Composition owner:** <application boundary>
## Responsibility and non-responsibilities
- Owns: <cohesive behavior>
- Does not own: <adjacent concerns>
## Complete path
| Layer | Path/symbol | Responsibility |
|---|---|---|
| Entry | `<path.Symbol>` | <role> |
| Domain | `<path.Symbol>` | <role> |
| State | `<path.Symbol>` | <role> |
| Adapter | `<path.Symbol>` | <role> |
| Composition | `<path.Symbol>` | <role> |
## Consumers
| Consumer | Contract | Configuration | Test evidence |
|---|---|---|---|
| <consumer> | <interface/event/data> | <key or none> | `<test>` |
## Invariants and failures
| Invariant | Enforcement | Failure behavior | Test |
|---|---|---|---|
| <invariant> | `<path.Symbol>` | <result> | `<test>` |
## Duplicate and superseded paths
| Path | Same operation? | Disposition | Deletion gate |
|---|---|---|---|
| `<path.Symbol>` | Yes / No, because <reason> | Keep / Delegate / Migrate / Delete | <proof> |
## Change checklist
- [ ] Trace every entry point and consumer.
- [ ] Decide whether the feature deprecates earlier work.
- [ ] Keep one owner for mutable state.
- [ ] Add failure-path and architecture tests.
- [ ] Prove the replacement before deleting the old path.
- [ ] Update generated reference from owned definitions.
````
## Operational runbook
````markdown
# Operate <service/capability>
**Status:** Current
**Last verified:** YYYY-MM-DD
**Environment:** <local/staging/production>
**Owner:** <operator/capability>
**External sources:** <host/config/dashboard; no secrets>
## Purpose and safety boundary
<State what this runbook operates and what requires separate authorization.>
## Preconditions
- <access/tool/config precondition>
- Secret names only; never secret values
## Start or change
1. Run `<exact command>`.
2. Expect `<observable output/state>` within `<bounded interval>`.
3. If `<alternate result>`, stop and route to `<diagnostic branch>`.
## Health and outputs
| Signal | Location/command | Healthy result | Unhealthy branch |
|---|---|---|---|
| <signal> | `<command/path>` | <result> | <action> |
## Rollback
1. <Restore previous code/config/data>
2. Run `<health command>`.
3. Preserve <logs/artifacts> for incident review.
## Known failure modes
| Symptom | First measurement | Likely seam | Next runbook |
|---|---|---|---|
| <symptom> | `<command>` | <boundary> | <sibling skill/doc> |
## Provenance
- External fact observed by <who/how> on YYYY-MM-DD.
- Re-check: `<one-line command>`
````
## Documentation change review
````markdown
# Documentation review: <scope>
**Date:** YYYY-MM-DD
**Reviewer:** <name/session>
**Changed authority:** <path or none>
## Classification
| Claim/change | State | Owner | Evidence |
|---|---|---|---|
| <claim> | CURRENT / APPROVED TARGET / OPEN / HISTORICAL / GENERATED / EXTERNAL | <owner> | `<path.Symbol/test/command>` |
## Findings
| Severity | Location | Problem | Evidence | Required correction |
|---|---|---|---|---|
| Blocking / Important / Minor | <heading/path> | <problem> | <evidence> | <fix> |
## Authority and duplication checks
- [ ] One record of authority owns each claim.
- [ ] Current and target behavior are separated.
- [ ] Open questions remain visibly open.
- [ ] Historical material is not used normatively.
- [ ] Generated output was not hand-edited.
- [ ] Symbols and headings replace durable line-number citations.
## Maintainability checks
- [ ] Responsibility, owner, boundaries, consumers, and invariants are explicit.
- [ ] Superseded paths and deletion gates are named.
- [ ] Evidence, rollback, and unresolved questions are actionable.
- [ ] A zero-context engineer can locate the complete feature path.
## Validation evidence
| Command | Expected | Observed |
|---|---|---|
| `<exact command>` | <result> | <result> |
## Residual uncertainty
<List unverified external facts, unavailable environments, or still-open
decisions. Never convert them into implied acceptance.>
````
@@ -0,0 +1,380 @@
---
name: archie-domain-reference
description: "Use when naming, designing, reviewing, documenting, tracing, or migrating Archie concepts such as Agent, Identity, user, Message, Conversation, work intake, WorkflowExecution, plugin engines, channels, events, policy, forge, worktrees, or gates; when current task/gateway/store vocabulary conflicts with the approved architecture; or when a feature risks crossing domain ownership boundaries. Provides project-specific current-to-target mappings, ownership rules, lifecycle language, and glossary checks. Do not use for NellDB API mechanics, general code tracing, config enumeration, debugging, or operations."
---
# Archie Domain Reference
Use one meaning for each noun. Keep external-system words at adapters, keep
domain meaning with its owner, and mark migration state explicitly.
## Route work to the right sibling
Do not use this skill as a substitute for:
| Need | Load instead |
| --- | --- |
| Decide or sequence an architectural migration | `archie-architecture-planning-campaign` and `archie-architecture-contract` |
| Trace definitions, call sites, interfaces, or AST relationships | `archie-codebase-discovery` |
| Understand NellDB documents, queries, adapters, or persistence behavior | `archie-nelldb` |
| Enumerate or change TOML, environment, flag, or runtime-setting axes | `archie-config-and-flags` |
| Prove supersession, remove a legacy path, or assign accountable ownership | `archie-technical-accountability` |
| Classify and gate a proposed change | `archie-change-control` |
| Diagnose a failing runtime or test symptom | `archie-debugging-playbook` |
| Run or deploy the system | `archie-run-and-operate` |
Use this skill first when another task is blocked on the meaning or owner of a
word.
## Classify every statement
As of 2026-07-28, Archie is between a technical-package implementation and an
approved domain-oriented target. Never blend the two.
| Label | Meaning | Evidence rule |
| --- | --- | --- |
| **CURRENT** | Behavior or structure present in live code and tests | Cite the defining type/function and a production caller or test. |
| **APPROVED TARGET** | A normative rule in an approved foundation document, or a confirmed constraint repeated in `migration-decisions.md` | Cite the exact PRD. Do not claim it is implemented. |
| **OPEN/CANDIDATE** | A deferred API, owner, package destination, migration mechanism, or behavior still under investigation | Preserve the open question. Do not fill it with a plausible design. |
| **ARCHIVED** | Historical context under `docs/archive/` | Use only for archaeology; reverify against live code and active PRDs. |
Start each design or review note with a status sentence:
```text
CURRENT: store.Task persists one mutable Stage string.
APPROVED TARGET: WorkflowExecution records StepExecution history.
OPEN: the exact schema and Go API for that history.
```
Read status markers and the architecture index before treating a statement as
settled:
```bash
sed -n '1,180p' docs/prds/01-project-management.md
rg -n '^\*\*Status:\*\*|^## Decisions still required|^## Remaining migration decisions' docs/prds/architecture
```
`docs/prds/architecture/agent-system.md` is marked current-state investigation
in progress, and `messaging-and-work-intake.md` says foundation decisions are in
progress. Treat only their constraints confirmed by approved documents or
`migration-decisions.md` as settled target doctrine. Treat their explicit
decision lists as open.
## Use the canonical actor vocabulary
| Term | Archie meaning | State and owner |
| --- | --- | --- |
| **Identity** | A durable actor reference used for ownership, attribution, routing, commands, events, and audit. Display names and external usernames are bindings, not IDs. Identity is not authentication or access control. | **APPROVED TARGET:** `internal/domain/identity`; see `identity.md`. **CURRENT:** configured names and empty strings act as identifiers. |
| **User** | A person represented as the `user` kind of Identity, not a second foundational identity system. | **APPROVED TARGET:** Identity domain. User authentication and authorization remain separate capabilities if later justified. |
| **Agent** | A persistent assistant with its own acting IdentityID, specialization, instructions, capability context, conversation continuity, and memory. It survives model/provider changes. | **CONFIRMED TARGET CONCEPT:** Agent and Identity are separate aggregates; `internal/domain/agent` is confirmed in `migration-decisions.md`. A complete Agent domain is not current. |
| **Model invocation** | One call through an LLM provider/runtime. It is replaceable execution machinery, not an Agent. | **CURRENT:** runtime/agent execution packages perform calls. **TARGET:** infrastructure behind Agent-owned behavior. |
| **System identity** | The one permanent actor for startup, migration, supervision, remediation, and rollback attribution. It is always active. | **APPROVED TARGET:** a real IdentityID; the current empty-string legacy path is not the system identity. |
| **Service-account identity** | A durable non-Agent actor for an explicitly justified unattended use case. | **TARGET OPTION:** not the default Agent execution identity. Delegated run-as behavior is future work. |
Apply these rules:
- Record the acting Agent identity and initiating user identity separately.
- Never authorize solely because two mutable identity-name strings match.
- Never rename an Agent when only its model, provider, display name, or forge
account changes.
- Never pool two Agents' agent-wide memory because one user owns both.
- Never pass a complete per-identity config bundle into a domain. Split settings
by the capability that owns them.
Verify the current mismatch:
```bash
rg -n 'type IdentityConfig|type IdentityRunner|Identity string|BotUser string|identity == ""|Identity != identity' internal/config internal/daemon internal/store internal/gateway
```
## Use the canonical interaction vocabulary
| Term | Archie meaning | State and owner |
| --- | --- | --- |
| **Channel** | An external interaction source or delivery system such as Telegram, email, webhook, forge, or future Jira. Its native nouns remain valid inside its adapter. | **CURRENT:** `internal/channels` extends `gateway.Gateway`; forge polling bypasses it. **TARGET:** infrastructure adapter for Messaging. |
| **Adapter** | Boundary code that translates an external payload, identifier, delivery result, or SDK type into an owned application contract and back. | **TARGET RULE:** infrastructure implements domain-owned interfaces. An adapter does not own domain state. |
| **Gateway** | A current technical interface/router and package, not approved domain vocabulary. It currently combines channel lifecycle, commands, conversational routing, sessions, and task control. | **CURRENT ONLY:** `internal/gateway`, `internal/channels`, and `cmd/archied`. Do not make a new domain named Gateway by default. |
| **ChannelBindingID** | Stable reference connecting a configured Agent to a particular external channel binding. | **APPROVED TARGET INPUT:** part of Conversation identity. Exact storage/API remains migration work. |
| **Message** | An immutable application record with its own MessageID and typed content. Platform message IDs are external correlations. | **TARGET:** Messaging owns it. **CURRENT:** production adapters mostly use `gateway.Message`; the richer `MessageEvent` exists beside it. |
| **Conversation** | Interaction history identified by AgentID + UserIdentityID + ChannelBindingID + ExternalConversationID + ThreadID. | **CONFIRMED TARGET:** Messaging. **CURRENT:** `gateway.SessionSource` has platform, bot user, channel, and thread, but lacks canonical Agent and user IDs. |
| **Conversation branch** | A child conversation continuing from one exact immutable parent message, identified by ParentConversationID and ForkMessageID. | **CONFIRMED TARGET:** parent/child transcripts diverge after the fork. No current implementation provides this complete contract. |
| **Work Intake** | The optional admission, validation, and deterministic routing boundary between an interaction and durable workflow-backed work. | **CONFIRMED TARGET DOMAIN:** `internal/domain/workintake`. It does not exist as a current package. |
| **Accepted work request** | The channel-neutral handoff emitted after Work Intake accepts a proposed durable outcome. It carries source correlation, acting identity, requested outcome, inputs, and routing evidence. | **TARGET HANDOFF:** the Agent System consumes it, selects a Workflow version, and alone creates a WorkflowExecution. Exact minimal contract is open. |
Do not equate an inbound Message with work. An Agent may answer, use a
capability, retain information, or propose durable work without creating a
WorkflowExecution. Deterministic automation may enter Work Intake without an
LLM turn only when its trigger and admission rule are unambiguous.
Use this target flow:
```text
external payload
-> channel adapter
-> canonical Message and Conversation
-> selected Agent turn
-> optional proposed work
-> Work Intake admission
-> accepted work request
-> Agent System selects Workflow version
-> WorkflowExecution
```
Do not describe the current `/spawn` path as this target. It directly creates a
`store.Task` with a synthetic forge issue number.
Verify both current message contracts and the direct task path:
```bash
rg -n 'type Message struct|type MessageEvent struct|ToLegacy|type SessionSource|CreateTask|EnqueueChatTask|synthetic' internal/gateway internal/store cmd/archied
```
## Use the canonical execution vocabulary
| Term | Archie meaning | Current representation |
| --- | --- | --- |
| **Workflow** | Reusable, versioned definition of behavior. | `workflow.Workflow` is currently a named ordered `[]Stage` without a durable version model. |
| **WorkflowExecution** | One durable execution of one specific Workflow version. | `store.Task` is the migration baseline, despite its name. |
| **WorkflowStep** | One defined operation in a Workflow. | A current `workflow.Stage` is the closest definition, but migration is not a mechanical rename. |
| **StepExecution** | Durable record of one WorkflowStep's execution and outcome. | Missing as an explicit current record; `store.Task.Stage` is one mutable string and event records are not authoritative history. |
| **Attempt** | A retry within the same WorkflowExecution, not a new execution. | Current `Task.Attempt` and `RetryCount` must become explicit attempt history; worker-delivery retry is a different concern. |
| **WorkflowExecution workspace** | Isolated mutable source workspace leased to one execution. | Current worktree, storage, container, branch, and cleanup behavior is spread across packages. |
| **Agent step execution** | One bounded model-backed WorkflowStep invocation. | `agentexec.Request`/`Result` correlate current TaskID, Attempt, Stage, and protocol version. This serializable request/result pair is a data boundary. |
Use `WorkflowExecution` in domain contracts, architecture, generated reference,
commands, and events. Qualify `workflow.Execution` in Go when useful. Never use
bare `Execution` across domains.
Retain `task` only for:
- the external Task build tool in `Taskfile.yml`;
- a forge/Jira product's own noun inside its adapter;
- informal prose that unambiguously means external work.
Never globally replace `task`. Classify each occurrence first:
```bash
rg -n '\b(Task|task|TaskID|task_id)\b' --glob '*.go' --glob '*.md' cmd internal docs/prds/architecture
```
### Interpret the current lifecycle exactly
These are **CURRENT** `store.Task` states, not proof of an implemented target
state machine:
```text
queued -> running
running -> waiting_human | pr_open | merged | parked | closed_wont_do
waiting_human -> queued | closed_wont_do
parked -> queued | dead
pr_open -> merged | rejected
running after crash -> queued
```
Use `waiting_human` for a paused current execution awaiting correlated human
input. Use `parked` for a current failure/manual-intervention state that may be
retried; use `dead` after retry exhaustion. Treat `pr_open`, `merged`,
`rejected`, and `closed_wont_do` as current delivery/outcome states.
Do not claim these transitions are enforced. `Store.Transition` writes the new
status without comparing `from`, then inserts history in a separate statement.
`internal/gateway/tasks.go` duplicates status strings locally.
Verify before changing lifecycle language:
```bash
rg -n 'Status[A-Za-z]+|status[A-Za-z]+|func \(s \*Store\) Transition|func \(s \*Store\) Requeue|RecoverStale' internal/store internal/gateway
```
## Keep memory scope separate from conversation scope
The following four scopes are fixed target constraints:
| Scope | Address and visibility |
| --- | --- |
| **Global shared** | Intentionally visible across the Archie application; retain provenance. |
| **Agent-wide** | Owned by one Agent and private to that Agent by default, even across users. |
| **User-wide** | Associated with one user and available only to authorized Agents serving that user. |
| **Agent-user relationship** | Addressed by both AgentID and User IdentityID; private to that pair. |
A Conversation branch is not a fifth memory scope. Branches isolate immediate
transcripts. A memory written from a branch follows the same selected durable
scope as one written from its parent; provenance may retain ConversationID and
MessageIDs.
Label scope mechanics **OPEN** beyond these constraints. The exact write-scope
selection, grants, cross-scope sharing, record/revision model, and final memory
package placement require a focused design.
Do not claim current scope enforcement. The current `MemoryProvider` initializes
with a session ID and contains no explicit AgentID, User IdentityID, or scope
parameter. The built-in provider separates `MEMORY.md` and `USER.md` under one
configured directory, which is not the four-scope target model.
Verify that gap without entering NellDB mechanics:
```bash
rg -n 'type MemoryProvider|Initialize\(|type Config struct|MEMORY.md|USER.md|AgentID|IdentityID|Scope' internal/memory
```
## Distinguish extension terms
| Term | Meaning |
| --- | --- |
| **Plugin** | A removable module with identity, metadata, compatibility, discovery, and lifecycle mechanics. Generic `plugin.Plugin` must remain metadata-only. |
| **Capability family** | One cohesive typed behavior owned by its domain or approved manager/registry, such as tools, channels, delivery, or Workflow extensions. |
| **Engine** | A typed, lifecycle-managed capability family with one owning Registry or Manager that both registers and returns the typed engine. It is never an extra generic-plugin method. |
| **Host** | Current cross-family lifecycle/manifest coordinator in `internal/plugin`. It must not become a daemon service locator. |
Give a plugin only narrow typed registrars and explicitly supplied contracts.
Do not give it daemon internals, application composition, arbitrary
infrastructure, or an untyped map of services. Keep Workflow plugin semantics
owned by Workflow.
The current repository mechanically enforces the strict engine shape and
metadata-only `Plugin{Name, Version}` contract:
```bash
go test ./internal/plugin -run 'Test(GenericPluginContractRemainsMetadataOnly|EveryEngineInterfaceHasTypedCapabilityAndFamilyOwner)' -count=1
```
## Distinguish ownership and boundary terms
| Term | Archie-specific rule |
| --- | --- |
| **Domain** | Own one cohesive application responsibility: vocabulary, state, rules, operations, commands, events, policy implementations, runtime settings, and required service contracts. Do not create ceremonial layers. |
| **Command** | Request an action. The receiving domain owns the contract and decides the result. |
| **Domain event** | Record something that happened. The publishing domain owns its schema and meaning. Consumers do not redefine it. |
| **Event bus** | Broker-neutral delivery/lifecycle contract only. It transports domain-owned messages and does not own their meaning. `internal/eventbus` is an approved target package but is not current. |
| **Observability event** | Current `internal/events.Event` projection input. Its bounded in-process bus may drop per-subscriber events. Do not treat it as authoritative state or as the target domain event bus. |
| **Policy** | A typed rule evaluated through shared mechanics. The consuming domain owns vocabulary, inputs, evaluator, and consequence. `internal/policy` owns common evaluation mechanics, not all rules. Its exact API is open. |
| **Infrastructure** | Implements domain-owned ports and translates databases, brokers, SDKs, files, networks, containers, or external services. External DTOs must not leak into domains. |
| **Application composition** | Chooses implementations, translates external configuration into owned settings, connects contracts, orders startup/shutdown, and aggregates health. Target owner is `internal/app`; current substantive wiring remains in `cmd/archied`. |
As of 2026-07-28, `internal/domain`, `internal/eventbus`,
`internal/policy`, `internal/infrastructure`, and `internal/app` do not exist.
They are target paths, not current imports.
Verify the separation:
```bash
for p in internal/domain internal/eventbus internal/policy internal/infrastructure internal/app; do test -d "$p" && echo "$p CURRENT" || echo "$p TARGET-ONLY"; done
```
## Distinguish forge, repository, workspace, gate, and agent boundaries
| Term | Owns | Must not own |
| --- | --- | --- |
| **Forge** | External code-host operations: issues, comments, labels, pull requests, reactions, and external references. | Workflow lifecycle, canonical identity, or work admission. |
| **Repository** | External source repository identity and repository-specific policy/settings. | A mutable execution workspace or a WorkflowExecution identity. |
| **Worktree/workspace** | Isolated files, branch, diff, commit, push, retention, and cleanup for one execution. Current `internal/worktree` performs git deterministically. | Agent/domain identity or forge issue lifecycle. |
| **Gate** | Deterministic evidence and constraints over an execution, including shell gates and custom findings. | Prompt advice that the model may waive. |
| **Agent execution boundary** | Versioned, validated data entering and leaving one unprivileged autonomous stage. The stage `Request` excludes workspace layout; the outer `Invocation` supplies the worker-visible workspace. | Daemon internals, forge tokens, direct git ownership, or workflow orchestration. |
Preserve the current invariant that the model never runs git directly.
Worktree operations are daemon-owned deterministic steps. Keep gates, protected
paths, budgets, and result review outside the model's discretion.
Inspect the narrow current contracts before changing a boundary:
```bash
sed -n '1,180p' internal/agentexec/protocol.go
sed -n '1,140p' internal/forge/forge.go
sed -n '1,120p' internal/worktree/worktree.go
sed -n '1,120p' internal/gate/gate.go
```
## Map current names before adding or migrating behavior
Use this map as a starting point, then trace actual consumers:
| Current name/path | Target meaning | Migration warning |
| --- | --- | --- |
| `config.IdentityConfig.Name` | Canonical IdentityID reference plus separate capability bindings | Do not preserve a mutable display name as the ID. |
| `config.IdentityConfig.BotUser` | Forge/Git or channel external binding | Do not use it as Conversation or Agent identity. |
| `daemon.IdentityRunner` | Composition of identity-correlated capabilities | It is currently a service bundle, not an Identity aggregate. |
| `gateway.Message`, `MessageEvent` | Canonical Messaging Message | Choose one immutable typed contract; do not maintain indefinite parallel models. |
| `gateway.SessionContext` | Conversation metadata | Add canonical Agent/user/binding ownership and exact branch lineage deliberately. |
| forge `Issue` or future Jira item | Channel message or external artifact | Preserve native reference inside its adapter. |
| gateway `/spawn` and `TaskCreator` | Proposed/accepted work handoff | Work Intake admits; Agent System alone creates execution. |
| `store.Task` | WorkflowExecution | Preserve every field intentionally; do not rename blindly. |
| `workflow.Workflow` | Versioned Workflow definition | Add identity/version ownership before claiming parity. |
| `workflow.Stage` | WorkflowStep definition | A definition is not execution history. |
| mutable `Task.Stage` | Derived position plus StepExecution records | Deletion requires proven history parity. |
| `Task.Attempt`, `RetryCount` | Attempt history and retry evidence | Keep worker delivery retries distinct. |
| `workflow.TaskContext` | Execution state plus narrow step ports | Remove the global config/service bag; do not reproduce it under a new name. |
| `events.Event` and `Bus` | Projections fed by authoritative domain events | Current drops are acceptable for observability, not state. |
| `cmd/archied` wiring | `internal/app/archied` composition | Keep `cmd/*` process-input-only in the target. |
| NATS/RPC/store/forge/worktree implementations | Infrastructure adapters | Process boundaries do not decide domain ownership. |
Do not infer a final package destination for every current package from this
table. `migration-decisions.md` explicitly leaves memory, tools, workspaces,
gates, storage, events, web UI, containers, RPC, release management, and
scheduling pending focused review.
## Recognize terminology-driven bugs
Use these examples during design and review:
| Incorrect shortcut | Resulting bug |
| --- | --- |
| “A forge issue is a Task, so persist its coordinates as execution identity.” | Chat work needs synthetic issue numbers; uniqueness and deduplication stay forge-shaped. This is a current hazard. |
| “Agent and Identity are the same config object.” | Model/persona/capability changes can alter attribution, and mutable string equality becomes access control. |
| “Every Message is work.” | Conversational turns and direct capabilities are forced through a durable workflow lifecycle. |
| “An accepted request is already a WorkflowExecution.” | Intake can bypass Workflow version selection and construct invalid execution state. |
| “Stage is StepExecution.” | Overwriting one stage string destroys durable step outcomes and audit history. |
| “A NATS retry is another Attempt.” | Transport availability changes domain retry counts and can exhaust work incorrectly. |
| “The event bus owns events.” | Broker subjects or a generic event envelope become domain vocabulary and state meaning drifts by consumer. |
| “A branch is a memory scope.” | Returning to a parent hides or duplicates durable learning instead of isolating only transcript history. |
| “Engine means another generic plugin hook.” | Capability ownership becomes untyped and plugins gain service-locator access. |
| “Configuration owns the feature because it has the fields.” | A cross-concern config package becomes the de facto domain and every feature must traverse it. |
## Review a spec or change with the glossary
Complete this checklist before accepting a design:
- [ ] Label every material claim CURRENT, APPROVED TARGET, or OPEN/CANDIDATE.
- [ ] Define every overloaded noun once; qualify `WorkflowExecution` and
`StepExecution`.
- [ ] Keep external issue/task/message vocabulary inside the relevant adapter.
- [ ] Name one domain owner for each state mutation, command, event, and policy.
- [ ] Identify both acting IdentityID and initiating user IdentityID where
applicable.
- [ ] Decide whether the interaction ends directly or enters Work Intake.
- [ ] Let only the Agent System create a WorkflowExecution.
- [ ] Separate a definition (`WorkflowStep`) from its record
(`StepExecution`).
- [ ] Separate workflow attempts, step attempts, and transport retries.
- [ ] Keep domain event meaning outside event-bus and infrastructure packages.
- [ ] Keep generic plugins metadata-only and capabilities typed.
- [ ] Keep external DTOs and complete configuration objects out of domains.
- [ ] Name the current path being superseded and its objective deletion
criteria; route the proof to `archie-technical-accountability`.
- [ ] Preserve unresolved questions rather than inventing an API.
During code review, reject:
- a second channel-neutral Message or execution model without a bounded cutover;
- a new status string copied into a consumer;
- a mutable display name used as a durable identifier;
- a service bag passed into a domain, plugin, or WorkflowStep;
- lifecycle state written by an adapter, UI, or transport;
- a domain importing concrete persistence, NATS, forge SDK, container, or
configuration DTO types;
- a test that proves only the new path while leaving the old production path
active.
## Provenance and maintenance
Volatile facts were verified against the working tree on 2026-07-28. Re-run
these one-line commands before relying on this skill after architecture or
package changes:
```bash
rg -n '^\*\*Status:\*\*|^## (Confirmed|Decisions still required|Remaining migration decisions|Completion criteria)' docs/prds/01-project-management.md docs/prds/architecture/*.md
rg -n '^type (Task|Workflow|Stage|TaskContext|Request|Result|Message|MessageEvent|SessionContext|Event|Plugin|Channel|BasePlatformAdapter)\b' internal
rg -n 'Status[A-Za-z]+|status[A-Za-z]+|func \(s \*Store\) Transition' internal/store internal/gateway
rg -n 'AgentID|IdentityID|ParentConversationID|ForkMessageID|WorkflowExecution|StepExecution|accepted work request' docs/prds/architecture
for p in internal/domain internal/eventbus internal/policy internal/infrastructure internal/app; do test -d "$p" && echo "$p CURRENT" || echo "$p TARGET-ONLY"; done
go test ./internal/plugin -run 'Test(GenericPluginContractRemainsMetadataOnly|EveryEngineInterfaceHasTypedCapabilityAndFamilyOwner)' -count=1
```
@@ -0,0 +1,4 @@
interface:
display_name: "Archie Domain Reference"
short_description: "Use Archie terminology without boundary mistakes"
default_prompt: "Use $archie-domain-reference to classify these Archie concepts and map current code terms to their approved target owners."
@@ -0,0 +1,269 @@
---
name: archie-failure-archaeology
description: "Reconstruct archie-core failures, dead ends, reversals, rejected fixes, and branch-only repairs from read-only git history and live call sites. Use when a symptom resembles a past production outage, deadlock, retry loop, protocol mismatch, configuration regression, worktree/cache fault, unsafe cleanup, linter semantic change, artifact leak, or recurring baseline repair; also use before reviving an old approach, declaring a fix reverted, or deciding whether a repair is current, settled, conditional, superseded, open, or merely a candidate."
---
# Archie failure archaeology
Stop the project from paying twice for the same lesson. Reconstruct what
happened from the checked-out code, tests, configuration, and commit graph.
Treat commit prose as a lead, not proof. Preserve uncertainty.
All volatile observations below are dated **2026-07-28**. Re-run the
provenance commands before relying on a status.
## Route the work
| Need | Load instead or alongside |
|---|---|
| Triage an active symptom and choose the next diagnostic | `archie-debugging-playbook` |
| Decide ownership, boundaries, migration, or a replacement design | `archie-architecture-planning-campaign` |
| Accept, gate, review, or close a change | `archie-change-control` |
| Traverse callers, ASTs, duplicate paths, or apparently dead code deeply | `archie-codebase-discovery` |
Do **not** use this skill:
- as permission to change code, configuration, git state, or production;
- as a substitute for reproducing a current failure;
- to promote a commit subject, old PRD, Beads record, or remote branch into
current truth;
- to call work “reverted” unless a revert commit or an inverse diff proves it;
- to design the next architecture. Carry proven constraints into
`archie-architecture-planning-campaign`.
## Use the status taxonomy exactly
| Status | Meaning |
|---|---|
| `settled` (`fixed`) | The failure, cause, resolution, and live replacement are proven. Preserve the resulting rule. |
| `current` | The checked-out authoritative path still contains the behavior or contradiction. |
| `open` | The defect is evidenced, but no accepted and integrated resolution is proven. |
| `conditional` | A fix is proven only for the named configuration, execution mode, peer, or deployment assembly. |
| `superseded` | A mechanism was intentionally replaced. Study it for constraints; do not restore it by default. |
| `candidate` | A branch, proposal, or partial implementation may help, but is not accepted current behavior. |
Never use `settled` to mean “a fix commit exists.” Prove that the fix is an
ancestor of the checkout and that live composition still selects it.
## Run the archaeology workflow
### 1. Freeze the observation point
Run only read-only git commands:
```sh
git rev-parse HEAD
git status --short
git log -1 --date=iso-strict --format='%H %ad %s'
git branch -a --no-color --no-merged HEAD
```
Record the commit and dirty paths. A dirty live file may contain a repair that
`HEAD` does not. Report both; do not silently choose one.
### 2. Name the exact symptom
Capture:
- the first wrong observable result;
- the last confirmed-good boundary;
- process mode (`inprocess`, `subprocess`, or NATS/container);
- the active config and deployment assembly;
- whether the failure is deterministic, load-dependent, or production-only.
Do not start with a preferred fix.
### 3. Trace current behavior before history
```sh
rg -n '<symptom|symbol|setting|error>' cmd internal config*.toml docker-compose.yml docs
git log --all --date=iso-strict --format='%H %ad %s' -- <affected-paths>
git blame -L <start>,<end> -- <live-file>
```
Trace entry point, caller, owner, adapter, peer, persistence, config decoder,
environment passthrough, and tests. Use `archie-codebase-discovery` when that
cone is not obvious.
### 4. Prove the historical transition
```sh
git show --no-ext-diff --format=fuller --stat <commit>
git show --no-ext-diff -U80 <commit> -- <affected-paths>
git merge-base --is-ancestor <commit> HEAD
git branch -a --contains <commit>
```
Read the parent version when the failure is semantic:
```sh
git show <commit>^:<path>
git show <commit>:<path>
```
Require all six fields in an incident packet:
| Field | Required content |
|---|---|
| Symptom | Operator, user, test, or protocol observation |
| Attempted solution | What was tried before or during the failure |
| Root cause | The violated contract or mistaken assumption |
| Evidence | Commit, live path, test, trace, or production observation |
| Current status | One taxonomy value, dated when volatile |
| Settled rule | A constraint future work must preserve |
### 5. Reproduce narrowly, then route
Use a focused, non-mutating check where practical. Put Go caches in `/tmp`:
```sh
env GOCACHE=/tmp/archie-archaeology-gocache GOTMPDIR=/tmp go test ./internal/<package> -run '^TestName$' -count=1 -v
```
If current behavior differs from the chronicle, update the packet rather than
forcing the symptom into an old story. Route a proposed correction through
`archie-change-control`.
## Match symptoms to known incidents
| Symptom | Start with |
|---|---|
| `nats: no responders available for request` only from agent containers | Container network incident |
| Daemon crash-loops after config/schema work | SecretRef compatibility and Compose passthrough incidents |
| Stream shows an empty cursor or first token, then hangs | FullStream/TextStream incident |
| MCP unit tests pass but a real SDK server hangs or rejects input | MCP framing and mirrored-peer incident |
| Telegram shows old commands after a successful menu update | Telegram server-side scope incident |
| Tool discovery deadlocks, aliases mutate, or one bad plugin hides the rest | Tool-registry adversarial findings |
| Hidden `<memory>` content appears at end of a truncated stream | Scrubber `Flush` leak |
| Broad lint cleanup compiles poorly or changes semantics while tests pass | Autofix, `nilerr`, and `308c199` incidents |
| A reused worktree is stale, half-prepared, or coupled to expired objects | Worktree/askpass/cache history |
| Repeated `fix: baseline gate repair` commits or parked tasks cycle | Baseline, no-op, and retry-loop incidents |
| CI cannot resolve `/work/apps/...` | Local module replacement incident |
| Build caches or dependency trees appear in the diff | `.gotmp` and `node_modules` incidents |
| `diff_cap_lines = 0` still behaves as 400 | Diff-cap zero contradiction |
## Chronicle: work intake and retry loops
| Incident and date | Symptom | Attempted solution and root cause | Evidence and status | Settled rule |
|---|---|---|---|---|
| Label auto-claim, 2026-07-22 | More than 80 labelled issues were enrolled when the deployment used label polling. | **Attempt:** use the `archie` label as the work trigger. **Cause:** label polling means eligibility, not a hint; it selected every matching issue without explicit assignment. | `519882f` changes `config.docker.toml` from `label` to `assignee`; `docs/archive/decisions.md` records the 80+ issue incident. `internal/config/config.go` now defaults to `assignee` but still permits explicit `label` and `either`. **Status:** `settled`. | Default to assignee-driven pickup. Treat `label` or `either` as deliberate bulk enrollment and review their full candidate set first. |
| Baseline-red park storm and repair churn, 2026-07-23 onward | A task repeatedly parks on a gate failure that existed before its feature work. History then accumulates unrelated baseline-repair commits. | **Attempt:** `b2482af` made `StageBaselineGate` launch the builder to repair a red baseline instead of parking. **Cause:** parking and retrying cannot change a pre-existing failure; auto-repair avoids that loop but mixes repository repair into feature scope. | `internal/workflow/implement.go`; `docs/archive/decisions.md`; `git log --all --grep='baseline gate repair'` returns nine repair commits in the recorded history. **Status:** `current` mitigation and architecture weak point. | Measure the untouched baseline first. Track baseline repair as an explicit change with its own evidence; never attribute its diff or success to the requested feature. |
| Passed build with zero changes, 2026-07-23 | Commit-push reports “worktree has no changes,” parks, retries, and repeats even though the requested fix already exists. | **Attempt:** `62c0df1` introduced no-op detection; it was incomplete until `2bf42bd` set an `Outcome` so the workflow actually stopped. **Cause:** “passed with no changes” lacked a terminal domain outcome. | `TaskContext.BuildNoChanges`, build `OnResult`, and `StageCommitPush` in `internal/workflow`; `TestStageCommitPushClosesIssueWhenBuildNoChanges`. **Status:** `settled`. | Model no-op as an explicit terminal result. Test both the side effect and workflow termination. |
| Infinite parked-task retry, 2026-07-23 | Removing the parked label repeatedly requeues a task with no terminal bound. | **Attempt:** requeue on label removal. **Cause:** retry count was not durable or capped. `a8fdb50` added persisted `retry_count`, global/per-repo `max_retries`, and `dead`. | `internal/daemon/daemon.go` (`maybeRetryParked`, `markDead`), `internal/store` retry tests, `config.example.toml`. Default is three in `finalize`. **Status:** `settled`. | Every autonomous retry needs durable attempt state, an explicit bound, a terminal state, and an operator-visible reason. |
## Chronicle: runtime and peer contracts
| Incident and date | Symptom | Attempted solution and root cause | Evidence and status | Settled rule |
|---|---|---|---|---|
| Container network auto-detection, 2026-07-27 | Every container-mode task returns `nats: no responders available for request`; workers never subscribe. | **Attempt:** `selfNetwork` inspected a container named after `os.Hostname` and silently fell back to the default bridge. **Cause:** the production hostname/container identity did not resolve to the running daemon, so spawned workers could not resolve `nats`. | `37cf089` records the production incident and adds `containers.network`; `2ac306b` pins `archie-core_default`; live `config.docker.toml` remains explicit and `internal/container/pool.go` warns on fallback. **Status:** `conditional`: fixed for the tracked Docker overlay; auto-detection remains a fallback elsewhere. | Make cross-container network membership explicit in deployment. Keep auto-detection diagnostic fallback only. |
| SecretRef schema crash-loop, 2026-07-27 and again at current `HEAD` | Both production identities demand `ARCHIE_GITHUB_TOKEN` despite Gitea config, then crash-loop. | **Attempt:** replace flat `[forge].token_env` with `Forge.Token SecretRef`. **Cause:** removing the old field let TOML silently ignore deployed `token_env`; defaulting then selected the wrong secret. `1f8588d` restored precedence-compatible fallback. | `1f8588d` and `internal/config/config_test.go` document the outage. `308c199` removes the `Forge.TokenEnv` declaration while `finalize` still references it, so that commit's tree does not compile. As of 2026-07-28 the dirty worktree reintroduces the field, but `HEAD` does not. **Status:** `open` regression at `HEAD`; reverify. | Preserve decoded compatibility until deployed files are migrated and rejection of stale keys is observable. Never rely on permissive decoding. |
| Repeated Compose secret omission, 2026-07-27 | Config names a valid env var, but the container sees it as empty and exits. | **Attempt:** define variables in the host environment/config only. **Cause:** Compose forwards only listed environment entries. `ARCHIE_GITEA_TOKEN_ARCHIE` and later `HEYARCHIE_TELEGRAM_BOT_TOKEN` were each omitted. | `22fc0ef`, `d0624b7`, live `docker-compose.yml`, and token resolution in `cmd/archied/main.go`. **Status:** `conditional`: fixed for these exact names in the tracked Compose assembly. | Trace every secret from config key to host value to Compose passthrough to process lookup. Add an assembly test or checklist whenever a secret name changes. |
| FullStream/TextStream deadlock, 2026-07-27 | A streamed Telegram reply renders an empty cursor or first token, typing never clears, and the turn never completes. | **Attempt:** reconstruct replies from `TextStream`. **Cause:** ai-sdk makes `FullStream` authoritative and synchronously backpressured; leaving it unread blocks the producer. `TextStream` is best-effort and may drop deltas. | `6a0bd27` and the live loop in `cmd/archied/main.go`; current gateway tests exercise routing but do not directly recreate ai-sdk channel backpressure. **Status:** `settled` implementation with a regression-test gap. | Drain the authoritative stream through close, derive text from its typed parts, then inspect terminal error state. Do not validate with a convenience projection alone. |
| MCP Content-Length framing and mirrored fake, 2026-07-26 to 2026-07-27 | Internal MCP tests pass while official-SDK servers do not understand the client. | **Attempt:** `f2768eb` implemented LSP-style `Content-Length`; `3ad57c9` strengthened that implementation. **Cause:** MCP stdio uses newline-delimited JSON. The test subprocess called the same `readMessage` and `writeMessage` helpers as the client, so both sides agreed on the same wrong protocol. | Compare `f2768eb:internal/tools/mcp/framing.go` with `dda4cde`; inspect `testMCPServer.serve` in `transport_test.go`; live opt-in independent peer is `TestDesktopCommanderClientCompatibility`. **Status:** `settled`. | For wire contracts, test raw canonical frames and an independently implemented peer. A mirrored fake proves internal symmetry, not interoperability. |
| Telegram command scopes persist by bot token, 2026-07-27 | Startup reports eight commands published, but DMs still show roughly 60 old Hermes commands. | **Attempt:** call `SetMyCommands` for only the default scope. **Cause:** Telegram chooses the most specific scope, and older `all_private_chats`/`all_group_chats` state survives redeploys because it is server-side and keyed to the token. | `cec0f3e` adds the menu and deny-by-default sender allowlist; `576c7f5` records `getMyCommands` evidence and publishes all three scopes. Live command specs are centralized in `internal/channels/telegram`. **Status:** `settled`. | Inventory and overwrite every relevant server-side scope. A new process or code deploy does not reset remote token state. Authorize by sender identity, not group membership. |
| NATS fetch error looked like an empty queue, 2026-07-27 | A consumer receives zero messages and treats a JetStream failure as “no work.” | **Attempt:** infer success from the message count alone. **Cause:** batch error state was not checked after the channel closed. | `0d09a2e` is the repro; `78a9145` is merged through `21ceef0`; `internal/nats/client_test.go` constructs zero messages plus a batch error. **Status:** `settled`. | Check terminal iterator/batch error state even when the data channel is empty. Empty is data, not proof of success. |
## Chronicle: implementation and tooling traps
| Incident and date | Symptom | Attempted solution and root cause | Evidence and status | Settled rule |
|---|---|---|---|---|
| Tool registry passed its first implementation but held eight defects, 2026-07-26 | Availability can deadlock; caller-owned schemas mutate after registration; discovery stops at the first bad source; Go-literal extraction accepts the wrong calls or loses values. | **Attempt:** implement the happy-path registry and source extractor. **Cause:** callbacks ran under `RLock`, copies were shallow/shared, literal parsing was partial, matching was broad, and discovery was fail-fast. | `9f6c36c` lists all eight fixes and regression tests in `internal/tools/registry_test.go` and `toolentry_test.go`. **Status:** `settled`. | Never call extension code under a registry lock. Clone nested caller data. Parse the complete supported literal grammar. Isolate discovery failures and match only the intended registration shape. |
| Memory scrubber `Flush` leak, 2026-07-26 | A stream ending inside `...secret</mem` emits buffered hidden memory text to the visible response. | **Attempt:** flush every unresolved partial tag as literal text. **Cause:** pending bytes did not retain whether they were captured inside a `<memory>` block. | `b4aaaf0`, `internal/memory/scrubber/scrubber.go`, and truncated-close-tag tests. Found by adversarial review. **Status:** `settled`; implementation has since been simplified, so re-run tests before changing it. | Test every streaming state at EOF: outside block, inside block, nested block, and every partial open/close-tag prefix. Flush is a security boundary. |
| Linter autofix shadowing, 2026-07-28 | A 24-file “style” pass stops compiling; one token away, a prefetch timeout would silently stop applying. | **Attempt:** run `golangci-lint --fix` plus formatters broadly. **Cause:** `gocritic` changed `ctx, cancel = context.WithTimeout(...)` to `:=` inside the conditional, shadowing the context. | `9b44bac`; live assignment in `internal/memory/manager.go`. **Status:** `settled` incident. | Treat autofix output as authored behavior. Inspect every semantic diff and preserve assignment-versus-declaration intent explicitly. |
| All eleven `nilerr` findings were semantic false positives, 2026-07-28 | Mechanical “fixes” would return Go errors while tests could still pass, breaking model correction, chat usage feedback, NATS envelopes, clean shutdown, and best-effort indexing. | **Attempt:** classify all `nilerr` reports as bug candidates. **Cause:** the linter cannot see that failures are deliberately carried as text, envelopes, shutdown signals, or skipped entries. | `86cfc19` documents each site; live `//nolint:nilerr` comments state local intent. **Status:** `settled`. | Review semantic channels one site at a time. Suppress locally with the reason. Never fan out a rule-name cleanup without contract analysis. |
| NellDB local replace broke delivery, 2026-07-26 to 2026-07-27 | Every CI Docker build fails `go mod download` on `/work/apps/nell-engine`, leaving production on an older image. | **Attempt:** point `github.com/samcharles93/NellDB v0.2.5` at a developer checkout in `d9d4822`. **Cause:** local module paths do not exist in CI/build contexts. | `07fb291` removes the replace after comparing local HEAD with published v0.2.5; live `go.mod` has the module and no replace. **Status:** `settled`. | Never commit machine-local `replace` directives. Prove the published version, checksum resolution, and container build path. |
| Broad checkpoint hid an unresolved merge conflict, 2026-07-27 | A literal conflict marker reached committed source amid many unrelated epics. | **Attempt:** checkpoint broad concurrent in-flight work to avoid loss. **Cause:** unrelated surfaces were combined without a whole-diff conflict scan. | Commit message for `4429ae5` states that it fixed a previously committed conflict in `internal/memory/scrubber/scrubber.go`. **Status:** `settled` incident. | Keep commits cohesive. Before any checkpoint, scan the exact diff for conflict markers and run affected package tests. |
### Preserve the eight tool-registry review lessons
| Defect fixed in `9f6c36c` | Required review question |
|---|---|
| `Available` evaluated `CheckFn` under `RLock` | Can a callback re-enter or block while a lock is held? |
| `Register` stored caller references | Can the caller mutate registered state afterward? |
| `Clone` copied nested schema maps/slices shallowly | Is every mutable layer detached? |
| `stringLit` mishandled escapes/backticks | Does parsing follow Go literal semantics? |
| `intLit` omitted negative/hex/octal/binary forms | Are all supported numeric forms handled or rejected explicitly? |
| `Discover` aborted on its first error | Can one bad extension hide healthy extensions? |
| `isRegisterCall` matched too broadly | Is the exact receiver/call shape proven? |
| `schemaLit` accepted only string values | Are booleans, integers, arrays, and nested maps preserved? |
## Chronicle: worktree and repository state reversals
Do not restore an intermediate mechanism just because one commit fixed it.
Follow the whole chain.
| Step and date | Symptom and attempted solution | Root cause, evidence, and status | Settled rule |
|---|---|---|---|
| Existing worktree skipped, 2026-07-23 | `Prepare` returned when `.git` existed. `89530ad` added fetch/checkout/reset to refresh it. | Existence did not prove freshness or completed preparation. Later `5883568` replaced `.git` readiness with a sentinel. **Status:** `superseded` implementation, enduring lesson. | Define a completed-state marker and revalidate remote/base/branch state on reuse. |
| Sentinel outside `.git`, 2026-07-24 | `.archie-prepared` marked successful setup and `.git/info/exclude` kept it untracked. | go-git `Add(All)` does not honor that exclude. `9c5f6a0` moved the sentinel to `.git/archie-prepared`. **Status:** `superseded` location. | Put orchestration metadata outside the tracked worktree by construction, not by ignore convention. |
| Askpass rewritten each call, 2026-07-24 | The “writes once” helper rewrote a token-emitting shell script for every git command. `7f796b3` added `sync.Once`. | The comment was not an invariant and no test checked mtime. `9c5f6a0` later removed shell git and askpass entirely. **Status:** `superseded`. | Prefer in-process credentials. If a secret helper is unavoidable, test lifecycle, permissions, exposure, and cleanup. |
| Bare object cache, 2026-07-24 | `4c1cfb1` added `--reference-if-able --dissociate` plus TTL to accelerate clones while keeping tasks independent. | go-git has shared alternates but no equivalent of `--dissociate`; expiring the cache would corrupt active worktrees. `9c5f6a0` intentionally dropped the Git cache and retained only persistent container volumes. **Status:** `superseded`, not proven “reverted.” | Never accept clone acceleration that makes task correctness depend on an expiring cache. Independence beats reuse. |
| Shell git replaced by go-git, 2026-07-28 | `9c5f6a0` removed token-bearing child environments and no-context shell calls. Porting exposed host GPG inheritance, sentinel tracking, and merge-base diff semantics. | The port stopped at a compiling sibling package: `0a813fb` then found worktree RPC handlers using `context.Background`, making in-process clones unbounded. **Status:** `current` go-git design with settled follow-up. | Audit every adapter and cancellation boundary after replacing a killable subprocess with in-process I/O. Rebuild tests against the new implementation rather than letting old binaries skip them. |
## Chronicle: cleanup, artifacts, and contradictory policy
| Incident and date | Symptom | Attempted solution and root cause | Evidence and status | Settled rule |
|---|---|---|---|---|
| Tracked `.gotmp`, 2026-07-27 | Go build-cache binaries, generated `_testmain.go`, and `.git-askpass` appear in commits. | **Attempt:** use repo-local `.gotmp` to work around tmpfs quota, then broad `git add -A`. **Cause:** the workaround path was not ignored before use. | `da61e4e`/`f715db2` introduced artifacts; `4cb0577` removes them and adds `.gotmp/` to `.gitignore`. Live tracked count is zero. **Status:** `settled`. | Put caches outside the repo or ignore them before the first command. Scan tracked files before accepting a broad add. |
| Tracked `docs-2/node_modules`, 2026-07-28 | Hundreds of pnpm symlink entries become repository content. | **Attempt:** broad `308c199` cleanup/documentation commit. **Cause:** `docs-2/node_modules` was neither ignored nor excluded from the commit. | `git ls-files 'docs-2/node_modules/**'` reports 237 entries at `HEAD`; `.gitignore` has no `node_modules` rule. **Status:** `current/open`. | Track lockfiles, never installed dependency trees. Add the ignore before installation and verify tracked counts are zero. |
| `308c199` cleanup regression, 2026-07-28 | `TestRunWrapsExternalCommand` returns `"\n"` instead of `"wrapped\n"`; forge compatibility is removed again; dependency artifacts are added. | **Attempt:** a 311-file cleanup/source-reference purge changed `exec.Command("echo", "wrapped")` to `exec.CommandContext(ctx, "sh", "-c", "echo", "wrapped")`, where `"wrapped"` becomes shell `$0`, and removed `Forge.TokenEnv`. **Cause:** semantic edits were classified and reviewed as cleanup. | `git show 308c199`; focused skillscript test fails at current `HEAD`; compare `HEAD:internal/config/config.go` with the dirty worktree; tracked node_modules count above. **Status:** `current/open`; do not assume dirty repairs are accepted. | No commit is “cleanup” for gating purposes. Classify each changed behavior, inspect every non-test semantic diff, run the full relevant suite, and scan artifact/compatibility deltas. |
| `diff_cap_lines = 0` contradiction, introduced at project start and exposed 2026-07-23 | Operators set zero expecting unlimited, but decoded config becomes 400. | **Attempt:** `5d60e75` made `StageDiffCap` treat `<=0` as disabled and later Docker config used zero. **Cause:** `finalize` has always converted zero to the default 400, so the same sentinel means both “unset” and “unlimited.” | `internal/config/config.go` defaults zero to 400; `internal/workflow/steps.go` treats zero as unlimited; `config.example.toml` advertises 400. **Status:** `current/open` contradiction. | Never overload a zero value with both defaulting and explicit policy. Use presence-aware decoding or a distinct explicit value, then test config-to-runtime behavior end to end. |
## Keep unmerged work as dated candidates
As of **2026-07-28**, these remote branches are not merged into the checked-out
`HEAD`. Their subjects and diffs are evidence of proposed fixes, not proof that
the live defect or exact patch remains valid.
| Candidate branch | Claimed concern | Required reconciliation |
|---|---|---|
| `origin/fix/43-loaddir-no-timeout-around-yaegi-eval-can-hang-daemon-startup` | Bound Yaegi evaluation during `LoadDir` | Compare current `internal/yaegiutil`, plugin startup, cancellation, and tests before adopting. |
| `origin/fix/45-skillscriptrun-ignores-context-cannot-be-canceledtimed-out` | Make skill scripts cancellable | Reconcile with current `skillscript.Run` API and the `308c199` failing test. |
| `origin/fix/48-transition-ignores-from-status-guard-allowing-lost-updates` | Enforce expected source state atomically | Compare both SQLite and NellDB transition/audit semantics; do not patch only one backend. |
| `origin/fix/52-handlesse-silently-swallows-eventssince-backlog-fetch-errors` | Surface SSE backlog query errors | Recheck current web handler composition and observable HTTP behavior. |
| `origin/feat/51-no-test-coverage-for-stagestats-query` | Add `StageStats` query coverage | Treat as test-only candidate; verify query/schema drift. |
| `origin/feat/75-add-mcp-client-capabilities-to-archied-and-archie-agent` | Wire MCP through both execution modes | Live `HEAD` already contains later MCP/provider work; compare behavior, never cherry-pick the branch wholesale. |
Verify candidate state:
```sh
git branch -r --no-merged HEAD
git log -1 --date=iso-strict --format='%H %ad %s' <branch>
git diff --stat HEAD...<branch>
git merge-base --is-ancestor <branch> HEAD
```
If equivalent behavior exists on `HEAD`, mark the branch `superseded`, not
merged. If no current reproduction exists, leave it `candidate`.
## Produce the archaeology handoff
Return:
1. observation commit and dirty paths;
2. exact symptom and current call path;
3. the closest incident packet with all six fields;
4. differences between the historical and current assemblies;
5. status using the taxonomy;
6. forbidden wrong paths derived from the settled rule;
7. one focused reproduction command;
8. the sibling skill that owns the next step.
Never end with “probably the same bug.” State what is proven, what is inferred,
and what remains unknown.
## Provenance and maintenance
Re-verify the chronology: `git log --all --date=iso-strict --format='%H %ad %s' -- cmd internal config.docker.toml docker-compose.yml go.mod .gitignore`
Re-verify a transition: `git show --no-ext-diff --format=fuller --stat <commit> && git merge-base --is-ancestor <commit> HEAD`
Re-verify live incident anchors: `rg -n 'selfNetwork|TokenEnv|FullStream|readMessage|BuildNoChanges|maybeRetryParked|DiffCapLines|prefetchTimeout|nolint:nilerr' cmd internal`
Re-verify dependency locality: `rg -n '^replace|/work/apps|/work/projects' go.mod tools/go.mod`
Re-verify tracked artifact counts: `git ls-files '.gotmp/**' 'docs-2/node_modules/**'`
Re-verify branch-only candidates: `git branch -r --no-merged HEAD`
Re-verify the current cleanup regression: `env GOCACHE=/tmp/archie-archaeology-gocache GOTMPDIR=/tmp go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v`
@@ -0,0 +1,4 @@
interface:
display_name: "Archie Failure Archaeology"
short_description: "Avoid repeating Archie failure history"
default_prompt: "Use $archie-failure-archaeology to trace this symptom through Archies proven incidents before proposing a fix."
+357
View File
@@ -0,0 +1,357 @@
---
name: archie-nelldb
description: >-
Maintain, debug, review, or migrate Archie's current NellDB-backed
persistence. Load this skill when touching internal/nell, store.TaskStore,
db_path, the tasks/events/sessions/messages collections, persisted task or
event fields, document IDs, _rev or HLC conflicts, scans and ordering,
restart recovery, SQLite-to-NellDB compatibility, backfills, or the pinned
NellDB dependency; also load it when tasks, events, identities, or chat
history disappear, duplicate, reorder, fail to transition, or fail to
survive restart.
---
# Archie NellDB
Treat Archie's database as domain state behind an application adapter. Do not
treat it as a generic JSON map, a SQLite file with a new driver, or proof that
the target persistence architecture already exists.
## Route before acting
Use this skill for NellDB mechanics and Archie's current adapter.
Do **not** use it alone to:
| Need | Load instead or as well |
| --- | --- |
| Define general Archie terms such as Identity, Agent, Message, or WorkflowExecution | `archie-domain-reference` |
| Find every caller, data path, generated consumer, or dead adapter | `archie-codebase-discovery` |
| Decide the target repository, state machine, event model, or migration boundary | `archie-architecture-planning-campaign` and `archie-architecture-contract` |
| Add or reinterpret `db_path`, `bot_user`, or another setting | `archie-config-and-flags` |
| Triage a running daemon, damaged deployment, or missing volume | `archie-debugging-playbook` and `archie-run-and-operate` |
| Accept a storage change, migration, or dependency upgrade | `archie-validation-and-qa` and `archie-change-control` |
Stop and route to architecture planning when the requested change would define
atomic state-plus-event persistence, WorkflowExecution storage, identity-aware
keys, session/message migration, or a new process boundary. Those are OPEN
migration decisions, not adapter cleanup.
## Use the vocabulary precisely
| Term | Meaning in this repository |
| --- | --- |
| `store.TaskStore` | Archie's current application-facing task, query, event, and lifecycle interface in `internal/store/interface.go`. |
| NellDB engine | The pinned `github.com/samcharles93/NellDB` `Store` layer: records, collections, HLC ordering, conflict resolution, and storage backends. |
| `LogStore` | NellDB's persistent append-only, Zstd-framed implementation opened by `logstore.OpenLog`. |
| `sdk.DocDB` | NellDB's document adapter over one named collection. It maps `sdk.Doc` values to engine records and maintains `_rev` bookkeeping. |
| Collection | A namespace in the engine. The engine key is `collection + ":" + record ID`. |
| Document ID | The application key stored in reserved field `_id`; it is distinct from `store.Task.ID`. |
| Revision (`_rev`) | An SDK MVCC token of form `<generation>-<sha1>`. It detects an explicitly stale local document write; it is not a domain version. |
| HLC | NellDB's hybrid logical clock: Unix milliseconds plus a logical counter, used for engine ordering. |
| Node ID | The writer string stamped into `UpdatedBy`. Archie currently passes `cfg.BotUser`; `LogStore` uses the value supplied at each open. |
| LWW | Engine-level last-write-wins: higher HLC wins; equal HLC uses lexically larger `UpdatedBy`. |
| Tombstone | A record with `Deleted=true`. Normal `Get`/`List` hides it, but it remains in the append-only log until compaction. |
| Backfill | An explicit, restartable conversion of already-persisted data. Adding a decoder default is compatibility, not a backfill. |
Never transfer SQL transactions, constraints, `ORDER BY`, WAL, row counts, or
index behavior to NellDB by analogy.
## Establish CURRENT production truth
The following snapshot was verified on **2026-07-28**:
```text
config.LoadOverlay
-> cfg.DBPath and cfg.BotUser
-> nell.OpenStore
-> logstore.OpenLog
-> one underlying NellDB Store
-> "tasks" DocDB
-> "events" DocDB
-> "sessions" DocDB when Telegram is configured
-> "messages" DocDB when Telegram is configured
```
| Fact | Current evidence | Consequence |
| --- | --- | --- |
| `cmd/archied/main.go` unconditionally opens `nell.OpenStore(cfg.DBPath, cfg.BotUser)`. | `cmd/archied/main.go` | NellDB is the production task/event backend. There is no runtime backend selector. |
| `internal/store.Store` still implements `TaskStore` using SQLite. | `internal/store/{interface,store,events}.go` | SQLite remains a test/legacy implementation, not a production fallback. |
| The same engine is lent to `gateway.NewSessionStore` only inside Telegram wiring. | `cmd/archied/main.go`; `internal/gateway/session_store.go` | Tasks/events always use NellDB; session/message collections exist only when that path writes them. |
| `go.mod` pins `github.com/samcharles93/NellDB v0.2.5` with no `replace`. | `go.mod`; `go.sum` | Review behavior against the published v0.2.5 source, not a local Nell checkout. |
| Archie does not call NellDB replication, compaction, changes-feed, or vector-search APIs. | No production matches for those APIs | Do not claim those engine features are active Archie behavior. |
| Several comments and older architecture documents still say SQLite. | `cmd/archied/main.go`; `ARCHITECTURE.md` | Follow production construction and code, not stale storage nouns in prose. |
Verify the dependency without network access:
```bash
go list -m -f '{{.Path}} {{.Version}}{{if .Replace}} => {{.Replace.Path}} {{.Replace.Version}}{{end}}' github.com/samcharles93/NellDB
rg -n '^replace .*NellDB|github.com/samcharles93/NellDB' go.mod go.sum
go list -m -f '{{.Dir}}' github.com/samcharles93/NellDB
```
Expected first-line result on this snapshot:
```text
github.com/samcharles93/NellDB v0.2.5
```
If a `=> /local/path` suffix appears, stop. Commit `07fb291` removed exactly
that failure mode after a local replace made the CI Docker build unable to
resolve `/work/apps/nell-engine` and left deployment stale.
## Separate engine guarantees from Archie guarantees
| Concern | NellDB v0.2.5 proves | Archie currently adds or fails to add |
| --- | --- | --- |
| Concurrency | `MemoryStore`, `LogStore`, and `DocDB` protect individual calls with mutexes. | `Adapter.mu` serializes selected multi-call operations in one adapter instance only. It is not a file lock or distributed transaction. |
| Document conflicts | Supplying stale `_rev` to `DocDB.Put` returns `sdk.ErrConflict`. Omitting `_rev` continues from the SDK's current local revision. | Adapter helpers usually re-read a current document before `Put`; this can avoid a conflict while still copying stale application fields. |
| Cross-node conflict | Engine `Put` applies HLC LWW, then lexical `UpdatedBy` tie-break. | No Archie replication path is wired. Do not present LWW as an enforced task state machine. |
| Persistence | Default `OpenLog` appends a frame and flushes the buffered writer on each write. `Close` flushes again. | Archie defers one adapter close. No application checkpoint, snapshot, or compaction service is wired. |
| Crash behavior | Replay rebuilds the in-memory index. An incomplete tail frame is ignored. | `Daemon.Startup` separately calls `RecoverStale`, changing every `running` task to `queued`. |
| Power loss | Neither default flush nor group commit calls `fsync`. | Archie adds no explicit sync. Do not promise power-loss durability. |
| Deletes | `Remove` writes a tombstone; ordinary list/get operations hide it. | `ClearTerminalTasks` tombstones terminal task documents. File space is not reclaimed because Archie never calls compaction. |
| Queries | The engine indexes collection membership and HLC changes. `Query` is a collection-list stub; vector search is a linear scan. | The adapter performs field queries by collection scans. Gateway message search uses substring matching, not NellDB vector search. |
| Listing | `AllDocs` returns a snapshot filtered after `Store.List`; range results are not sorted by key. | Task/event methods sort when their contract needs it. Session/message code currently assumes ordering in places where the SDK does not guarantee it. |
| Node identity | Records retain their `UpdatedBy`; conflict resolution uses it. | `LogStore.NodeID()` returns the value passed to the current open. Changing `bot_user` changes future writer identity. |
Do not open the same log file from multiple processes or adapter instances and
assume `Adapter.mu` coordinates them. No cross-process lock or supported
multi-writer assembly is proven in Archie or the pinned `LogStore`.
## Know the stored shapes
### Collections and keys
| Collection | Document ID | Application data | Read pattern |
| --- | --- | --- | --- |
| `tasks` | `<owner>:<repo>:<issue_number>` | Current `store.Task` fields plus `created_at` | Direct `Get` by forge coordinates; scans for numeric task ID, status, claims, counts, and stats |
| `events` | `event:<numeric-id>` | `events.Event`; `data` is stored as a JSON string | Full scan, application filter, then explicit ID sort |
| `sessions` | `SessionContext.SessionID` | platform, bot, channel, optional thread, timestamps | Direct `Get`; full scan for list/channel lookup |
| `messages` | `<session-id>:<20-digit-sequence>` | session, sequence, sender, text, channel/thread, timestamp | Collection scan plus key-range filter |
Each `DocDB` may also contain SDK IDs `meta:clock` and `meta:vector`. Archie adds
`meta:task_id_counter` and `meta:event_id_counter`. The adapters skip IDs with
the `meta:` prefix.
Do not create an application ID beginning with `meta:`. As written,
`isMetaKey` will also hide a legitimate task whose composite key begins
`meta:` from scan-based claims and queries, even though direct `Get` can find
it. Treat this as a CURRENT risk requiring a failing test before repair.
### Task document mapping
| Group | Fields |
| --- | --- |
| Reserved and local identity | `_id`, SDK-managed `_rev`, numeric `id`, `created_at` |
| Source snapshot | `owner`, `repo`, `issue_number`, `title`, `body`, `labels`, `source`, `identity` |
| Lifecycle | `status`, `attempt`, `retry_count`, `park_reason`, `watch_comment_id` |
| Workflow/output | `workflow`, `stage`, `branch`, `plan`, `notes`, `pr_number`, `tokens_used`, `iterations` |
Apply these conversion rules:
- Store numeric fields as `int64`. `intField` accepts `float64`, `int64`,
`int`, and `json.Number` because JSON document round trips may yield
`float64`.
- Treat a missing `source` as `forge`; `sourceOrDefault` preserves old
documents.
- Preserve `_id` and `_rev` by starting updates from `DocDB.Get`, not a fresh
map.
- Do not expect `created_at` in `store.Task`; `docToTask` currently discards it,
and the Nell document has no `updated_at`.
- Keep workflow `Update` restricted to its documented mutable subset. Do not
silently let it rewrite identity, source coordinates, status, attempt, or
retry state.
CURRENT defect: `EnqueueIssue` accepts `identity` but does not put `identity`
into the Nell document. Forge tasks therefore read back with an empty identity.
`EnqueueChatTask` does write both `source=chat` and `identity`, and subsequent
helpers preserve those existing fields. Do not quote target identity
documentation as proof that forge identity round-trips.
### Event document mapping
`InsertEvent` stores:
```text
id, at, kind, task_id, repo, issue, workflow, stage, detail, data
```
It clips `detail` to 4000 bytes without splitting a UTF-8 rune. It serializes
`data` to a JSON string and substitutes a `marshal_error` object when
marshalling fails. `docToEvent` ignores invalid timestamps and invalid `data`
JSON rather than returning conversion errors.
Events are observability records, not atomic task-transition history. Nell
`Transition` ignores `detail`, and the event sink writes asynchronously through
the event bus. Never claim task state and its event were committed together.
## Audit lifecycle and atomicity before editing
| Operation | Current serialization | Important limit |
| --- | --- | --- |
| `ClaimNext`, `ClaimByIssue` | Entire scan/get plus task write under `Adapter.mu` | Atomic only against operations using the same mutex on the same adapter instance. |
| Task/event ID allocation | Counter read-modify-write under `Adapter.mu` | Enqueue's duplicate check is outside the critical section; a duplicate concurrent enqueue is not proven idempotent. |
| `RecoverStale`, `ClearTerminalTasks` | Full scan and writes under `Adapter.mu` | `Transition`, `Update`, and `Requeue` do not take this mutex. |
| `Transition` | Find by numeric ID, set `Status`, put | Ignores `from` and `detail`; writes no transition record; has no adapter lock. |
| `Requeue` | Find, mutate several fields, put | Ignores `fromStatus`; writes no transition record; has no adapter lock. |
| `Update` | Get by composite key, replace allowed fields, put | One document write, but no domain state/event transaction. |
| `IncrementRetryCount` | Find, increment, put | Multi-call read-modify-write without adapter lock. |
| `InsertEvent` | ID allocation and put under `Adapter.mu` | Separate from the state mutation that caused the event. |
The method name `Transition` does not make a state machine. A correct target
must compare expected state/version, enforce legal transitions, and commit the
authoritative domain event with state at one proven atomic boundary. Design
that through the architecture campaign; do not patch only one caller.
## Investigate without damaging the log
Start read-only:
```bash
rg -n 'OpenStore|NewSessionStore|TaskStore|DBPath' cmd/archied internal
rg -n 'func \\(a \\*Adapter\\)|sdk\\.New|AllDocs|FieldID|isMetaKey' internal/nell/adapter.go
rg -n 'SaveMessage|RecentMessages|SearchMessages|sdk\\.New' internal/gateway/session_store.go
rg -n 'store\\.Open\\(|nell\\.OpenStore\\(' --glob '*.go'
```
Inspect a configured file without opening it through either database:
```bash
# Assign from the approved effective config before running
: "${DB_PATH:?set DB_PATH from the running config's db_path field}"
test -r "$DB_PATH" || { echo "DB_PATH is not readable: $DB_PATH" >&2; exit 1; }
test -f "$DB_PATH" || { echo "DB_PATH is not a regular file: $DB_PATH" >&2; exit 1; }
file -- "$DB_PATH"
od -An -tc -N16 -- "$DB_PATH"
stat -- "$DB_PATH"
```
Never run `sqlite3 "$DB_PATH"` merely because the name ends in `.db`. A current
NellDB file is a Zstd-framed binary append log. Conversely, never pass a legacy
SQLite file to `nell.OpenStore`; there is no format detector or automatic
migration.
Use focused executable evidence:
```bash
go test ./internal/nell -run '^(TestEnqueueIdempotent|TestChatTaskLifecyclePreservesRouting|TestPersistenceAcrossRestart|TestConcurrentEnqueueAndClaim)$' -count=1
go test -race ./internal/nell ./internal/gateway -count=1
go test ./internal/store ./internal/nell -count=1
go test ./cmd/archied -run '^TestChatTaskCommandsEndToEnd$' -count=1
```
As verified on 2026-07-28, those focused commands pass in an environment with
writable Go caches. If the workspace points Go temporary files at a read-only
directory, rerun without changing repository files:
```bash
mkdir -p /tmp/archie-nelldb-gotmp /tmp/archie-nelldb-gocache
env GOTMPDIR=/tmp/archie-nelldb-gotmp GOCACHE=/tmp/archie-nelldb-gocache go test -race ./internal/nell ./internal/gateway -count=1
```
`internal/storerpc` tests also require a local NATS listener. A panic saying the
embedded NATS server could not start is environment evidence until reproduced
where listener creation is allowed.
## Change persisted data safely
Follow this checklist for every field, key, collection, or dependency change:
- [ ] Name the domain owner and distinguish CURRENT behavior from APPROVED
TARGET and OPEN migration work.
- [ ] Trace every producer, converter, reader, projection, RPC payload, JSON
consumer, test backend, and production constructor.
- [ ] State what the new data supersedes and when the old field/path is deleted.
- [ ] Add a red test using an old document with the field absent.
- [ ] Add red round-trip tests for both forge and chat sources when task data is
involved.
- [ ] Update every creation path, `docToTask`, `taskFields`, and the restricted
`Update` set only when that operation owns the field.
- [ ] Preserve `_id` and `_rev`; never “fix” conflicts by deleting `_rev`.
- [ ] Give missing or legacy data an explicit compatibility rule. Label any
guessed default OPEN.
- [ ] Check the SQLite implementation deliberately: schema, additive migration,
every `SELECT`/`Scan`, query projections, and tests. Either preserve contract
parity or document and prove a completed cutover.
- [ ] Test field preservation through claim, transition, requeue, retry,
recovery, update, delete, close, and reopen as applicable.
- [ ] Add stale-revision, concurrent-writer, cancellation, malformed-value, and
restart cases. A race-clean engine call does not prove a multi-call
application operation is atomic.
- [ ] Measure scans at representative collection sizes before accepting another
scan or claiming current scale makes it safe.
- [ ] Run the focused tests, then route final evidence through
`archie-validation-and-qa` and `archie-change-control`.
Use a shared backend contract test suite when changing `TaskStore`. Current
tests are split between `internal/store` and `internal/nell`; there is no single
factory-driven suite proving identical semantics.
## Gate migration and backfill explicitly
There is no repository-supported SQLite-to-NellDB migration or backfill command
as of 2026-07-28. Do not invent an operator command in a runbook.
Require this sequence before any cutover:
1. Freeze the authoritative source or define a proven dual-write protocol.
2. Keep the SQLite input and NellDB output at different paths. Never convert in
place.
3. Inventory task rows, numeric IDs, source coordinates, statuses, mutable
fields, event IDs/timestamps/data, and SQLite transition history.
4. Decide explicitly where transition history goes; the current Nell adapter
has no equivalent collection.
5. Include sessions/messages only if the chosen source actually contains them;
current Nell gateway data has no SQLite equivalent in this repository.
6. Build a dry-run exporter/importer with schema/version identification,
deterministic IDs, idempotent writes, checkpoints, and rejection reporting.
7. Compare counts by status/source/workflow plus stable content digests. Test
close/reopen and crash-resume from every checkpoint.
8. Quiesce, copy, convert, validate through public application reads, then
switch `db_path` once.
9. Retain the untouched source and a last-known-good binary/config until the
observation window passes.
10. Delete the old reader or compatibility path only after production wiring,
rollback evidence, and change control prove the cutover complete.
Treat NellDB `PutMany` as sequential engine writes, not a crash-atomic
transaction. Its SDK cache rollback does not undo records already written to
`MemoryStore` or `LogStore`.
## Triage by symptom
| Symptom | Prove first | Likely CURRENT seam |
| --- | --- | --- |
| `nell: path is required` | Trace `cfg.DBPath` and the direct caller. | `OpenStore` rejects an empty path; normal config finalization supplies a default. |
| `nell: open log: log: open ... no such file or directory` | Check the parent directory, mount, UID, and `db_path`. | `OpenStore` does not create the parent directory; unlike SQLite `store.Open`, it calls `os.OpenFile` directly. |
| Old tasks vanish after the backend switch | Inspect file signature and exact configured path; do not start another writer. | No SQLite import or format check exists. |
| Forge task identity is empty after reload | Compare enqueue arguments with the Nell document constructor. | `EnqueueIssue` currently drops `identity`; chat enqueue does not. |
| A stale or illegal transition succeeds | Read `Transition` and capture before/after state. | `from` is currently unused in both Nell and SQLite implementations. |
| State changed but no matching history/detail exists | Trace state write and event sink independently. | Nell transition history is absent; observability event persistence is asynchronous. |
| A directly addressable queued task is never claimed | Check whether its document ID begins `meta:`. | Scan paths filter every `meta:` prefix as internal. |
| Recent messages reorder or omit expected turns | Test more than one insertion order and restart. | `RecentMessages` assumes key-sorted `AllDocs`; v0.2.5 range results are not sorted. No message persistence tests exist. |
| `sdk: revision conflict` | Preserve the conflicting docs/revisions and identify both writers. | A stale explicit `_rev` was supplied. Re-read and recompute only if the domain command is safe to retry. |
| Database grows after updates/deletes | Compare file size with live document counts. | Append-only versions and tombstones accumulate; Archie wires no compaction. |
| Data survives process restart but not host power loss | Separate close/replay evidence from storage durability evidence. | Default writes flush but do not `fsync`. |
| NellDB SDK dependency tests fail on `server/webui/dist/nell.wasm` | Run Archie's focused packages and inspect the downloaded module archive. | Published v0.2.5 omits that embedded WASM asset; `go test github.com/samcharles93/NellDB/logstore` passes, while SDK tests cannot compile from the module cache. |
| A fix exists on another branch but main still fails | Inspect current source and branch containment. | Candidate or branch-only code is not live behavior. Never document it as fixed until merged and reverified. |
Escalate damaged-file handling to `archie-run-and-operate`. The pinned engine
proves incomplete-tail tolerance; it does not prove arbitrary corruption can be
repaired or that silently skipped data is acceptable.
## Provenance and maintenance
Volatile facts and focused tests in this skill were reverified on 2026-07-28.
Reverify after any change to `go.mod`, `cmd/archied/main.go`, `internal/nell`,
`internal/store`, `internal/gateway/session_store.go`, or the NellDB version.
```bash
go list -m -f '{{.Path}} {{.Version}}{{if .Replace}} => {{.Replace.Path}}{{end}}' github.com/samcharles93/NellDB
rg -n 'nell\\.OpenStore|NewSessionStore|store\\.Open\\(' cmd internal --glob '*.go'
rg -n 'func \\(a \\*Adapter\\)|sdk\\.New|AllDocs|isMetaKey|identity' internal/nell/adapter.go
go test ./internal/nell ./internal/gateway -count=1
go test -race ./internal/nell ./internal/gateway -count=1
git log --all --oneline -- go.mod internal/nell internal/store internal/gateway/session_store.go
```
@@ -0,0 +1,4 @@
interface:
display_name: "Archie NellDB"
short_description: "Maintain Archie persistence on NellDB safely"
default_prompt: "Use $archie-nelldb to inspect or change Archie persistence without importing SQLite assumptions."
@@ -0,0 +1,359 @@
---
name: archie-research-methodology
description: Turn an Archie architecture, maintainability, performance, persistence, configuration, protocol, concurrency, or migration hunch into reproducible evidence and an accountable decision. Use before advocating a redesign, accepting a surprising test result, claiming code is duplicate or dead, comparing execution modes or stores, measuring NellDB scans, validating an external protocol, or promoting a candidate fix; also use when a green TDD result does not prove production wiring or design quality.
---
# Research Archie with falsifiable evidence
Use research to expose a decision, not to decorate a preferred answer. Ask one
vertical question, predict an observable result before measuring, preserve
failures and negative results, and hand any resulting change to Archie's change
control. Optimize for a small meaningful answer that improves the architecture
ledger.
All volatile repository observations in this skill were verified on
**2026-07-28**. Re-run the provenance commands before treating them as current.
## Route the work
| Need | Load instead or alongside |
|---|---|
| Trace entry points, types, callers, registrations, and complete change cones | `archie-codebase-discovery` |
| Collect repeatable counts, coverage, timings, profiles, or runtime diagnostics | `archie-diagnostics-and-tooling` |
| Decide boundaries, ownership, target packages, and migration slices | `archie-architecture-planning-campaign` |
| Reconstruct an earlier failure, rejected fix, revert, or branch-only candidate | `archie-failure-archaeology` |
| Decide test sufficiency and acceptance thresholds | `archie-validation-and-qa` |
| Classify, authorize, review, or accept a change | `archie-change-control` |
| Assign ownership, supersession, deletion criteria, and maintainability debt | `archie-technical-accountability` |
Do **not** use this skill to implement the hypothesized fix, to operate
production, or to replace NellDB domain knowledge. Use `archie-nelldb` for the
database model and `archie-run-and-operate` for live operations. Stop the
research pass before mutation.
## Define the terms once
- **Question**: one uncertainty whose answer changes a design or acceptance
decision.
- **Hypothesis**: a falsifiable explanation, written before the experiment.
- **Prediction**: a number, relation, state, byte sequence, error, or call path
that must be observed if the hypothesis is correct.
- **Falsifier**: an observation that rejects the hypothesis. “The test fails”
is too vague; name the failure that matters.
- **Baseline**: the unchanged tree, environment, mode, data, and measurements
against which a treatment is compared.
- **Treatment**: the one intentional difference between baseline and
comparison.
- **Control**: an unchanged case that detects a broken fixture or measurement.
- **Confounder**: another difference that could explain the result.
- **Replication**: a repeat from the same frozen inputs.
- **Triangulation**: evidence from a different mechanism that does not share
the first mechanism's assumptions or helpers.
- **Decision gate**: a predeclared rule that maps observed evidence to proceed,
reject, redesign, or investigate.
## Keep current and target truth separate
Maintain two columns throughout the record:
| Ledger | Authority | Permitted conclusion |
|---|---|---|
| Current implementation | Checked-out production composition, source, tests, deployed assembly evidence, and captured runtime behavior | What this exact tree and assembly do now |
| Approved target | `docs/prds/01-project-management.md` and status-qualified documents under `docs/prds/architecture/` | What the project requires or has deliberately left open |
Treat `ARCHITECTURE.md`, comments, commit messages, Beads history, unmerged
branches, and proposals as leads until reconciled with those ledgers. An
approved target is authoritative for direction but is never evidence that the
live implementation already satisfies it.
Use these claim labels:
- `observed-current`: directly reproduced or traced in the frozen tree;
- `approved-target`: required by a status-qualified target document;
- `candidate`: plausible and worth testing, but not accepted;
- `open`: evidence is insufficient or contradictory.
## Apply the evidence hierarchy
Match evidence to the claim. Do not add two correlated tests and call them
independent.
| Rank | Evidence | What it can prove | Required caution |
|---:|---|---|---|
| 1 | Captured behavior from the exact binary/config/data plus a trace through live production composition and source | What the named assembly selected and did | Record version, mode, inputs, secrets redacted, and environment; one deployment is not universal |
| 2 | Independent protocol peer, official SDK, published conformance vector, or raw fixture captured outside Archie's helpers | Interoperability at an external boundary | Pin peer/version and preserve bytes or messages |
| 3 | Integration, composition, legal-transition, deterministic concurrency, cancellation, recovery, and race evidence | Behavior across real internal boundaries and schedules | Prove the test uses the production handoff rather than a parallel constructor |
| 4 | Focused unit tests, benchmarks, AST/type queries, lint findings, coverage, and source inspection | Local behavior and structural candidates | Do not infer production use, ownership, absence, or protocol compatibility |
| 5 | Current docs, history, incident reports, issue records, branches, and proposals | Intent, constraints, and candidate explanations | Reconcile with live code; never present a candidate as current |
For a current-code claim, include at least one live composition/source trace and
one independently produced check. For an external protocol claim, include Rank
2. For a concurrency claim, include deterministic ordering plus `-race`.
## Run the decision-gated method
### Gate 0 — Declare one vertical question
Write one sentence:
> Determine whether `<current mechanism>` causes `<observable outcome>` under
> `<named mode/input/state>`, so we can decide `<specific architecture or
> maintenance action>`.
Require:
- question count: exactly `1`;
- named decision owner: exactly `1`;
- implementation edits during research: `0`;
- meaningful falsifiers: at least `1`;
- explicit non-goals: at least `1`.
Split the work if the question contains “and” between independently testable
behaviors. A short success must still traverse one complete path from real
input through ownership and state to observable outcome.
### Gate 1 — Freeze the observation point
Run from the repository root before changing anything:
```bash
git rev-parse HEAD
git status --short
go version
go env GOMOD GOWORK GOOS GOARCH CGO_ENABLED GOTMPDIR GOCACHE
go list -m -f '{{.Path}} {{.Version}} {{.GoVersion}}'
find . \( -path './.git' -o -path './.references' -o -path './.claude/worktrees' -o -name node_modules \) -prune -o -name go.mod -print
```
Record:
- commit and every dirty path;
- Go/tool versions and module boundary;
- operating system, architecture, sandbox/host, and resource restrictions;
- execution mode and concrete implementation;
- configuration source and relevant effective values, with secrets redacted;
- data/fixture identity and size;
- exact command, exit status, output, and run time.
The root and `tools/` directories are separate Go modules as of 2026-07-28.
Never blend their results. Do not run `task check` to establish a read-only
baseline: it runs `gofumpt -w`, `go fix`, and builds into `bin/`.
The focused command below currently fails with `Run() = "\n"`; preserve that
signature as a real pre-existing code failure rather than an environmental
confounder:
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-research-gocache \
GIT_CONFIG_GLOBAL=/dev/null go test ./internal/skillscript \
-run '^TestRunWrapsExternalCommand$' -count=1 -v
```
If the tree, dependency set, configuration, mode, fixture, or environment
changes, invalidate the affected baseline and restart this gate.
### Gate 2 — Predict before measuring
State both the explanation and the null:
```text
Hypothesis H1:
Null H0:
Mechanism:
Primary metric/observable:
Baseline prediction:
Treatment prediction:
Falsifier:
Invariant predictions:
```
Use numbers whenever the result is countable. If no dated baseline exists,
write `predict before measurement`, choose the number or relation now, and only
then run the command. Never backfill an “expected” value from the observed
output.
Predict all of:
1. the primary result;
2. one negative/control result;
3. preserved behavior in every affected mode, adapter, or data form;
4. the expected error or failure consequence;
5. what result makes the experiment inconclusive.
### Gate 3 — Design independent controls
Build a matrix before execution:
| Variable | Baseline | Treatment | Held constant | Measurement |
|---|---|---|---|---|
| one intentional difference | exact value | exact value | commit, mode, data, tools, timeouts | exact command/output |
List confounders explicitly. Check at least:
- sandbox listener, process, keyring, Docker socket, and cache restrictions;
- stale editor/compiler diagnostics versus a real `go build` or `go test`;
- warm versus cold cache and network access;
- test-only constructors versus production composition;
- reused parsing, framing, constants, fixtures, or server helpers;
- background goroutines, timing, retries, and global mutable state;
- local module replacements and unpublished dependency checkouts;
- dirty concurrent work and generated artifacts.
Require one control that would fail if the fixture or instrumentation were
broken. For protocols, require an independently implemented peer. For
architecture claims, require a source/type trace and a runtime or
composition-level observation.
### Gate 4 — Execute without moving the target
Run the baseline first, then the treatment, then the baseline again when
ordering or cache effects are plausible. Preserve raw output under a
task-specific temporary path or in the controlled work artifact.
Do not:
- edit implementation, tests, config, fixtures, or success criteria mid-run;
- discard outliers without a predeclared rule;
- turn a failing hypothesis into a differently worded success;
- replace a denied listener, missing peer, or cold dependency with a weaker
test and claim equivalence.
If execution exposes a separate defect, freeze it as a new question. Do not
fold its repair into the experiment.
### Gate 5 — Apply the predeclared decision
Classify the result exactly:
| Result | Action |
|---|---|
| Every prediction and invariant holds, controls work, and required evidence ranks are present | Mark `supported`, not “proven forever”; proceed to replication and change control |
| A falsifier occurs with valid controls | Mark `falsified`; preserve the negative result and reject solutions depending on H1 |
| Fixture, environment, baseline, independence, or statistical power is inadequate | Mark `inconclusive`; state the next evidence needed |
| Current and target ledgers conflict | Record the migration gap; do not redefine either ledger |
| Another mechanism explains the result equally well | Design a discriminating experiment; do not choose by preference |
Post-hoc success criteria count: `0`. Unexplained deviations count: `0`.
### Gate 6 — Replicate and triangulate
Repeat deterministic checks from a clean process. For variable measurements,
declare the run count before starting and report every sample. Compare an
independent mechanism:
- AST/type references versus runtime composition;
- SQLite behavior versus NellDB behavior;
- in-process behavior versus subprocess/NATS behavior;
- raw protocol frames versus an official peer;
- unit behavior versus race/integration behavior;
- source expectation versus persisted reload/recovery.
If two checks share the same implementation helper, parser, mock, global, or
fixture generator, treat them as one evidence source.
### Gate 7 — Preserve the reproducibility packet
Attach this compact record to the controlled issue, architecture handoff, or
decision document selected by sibling skills. Do not create an orphan report.
```markdown
## Research record R-<id>
Question:
Decision affected:
Current claim / target claim:
Tree: <commit>; dirty paths:
Environment/mode/config/data:
H1 / H0 / mechanism:
Predictions: <metric | baseline | treatment | falsifier | invariants>
Controls and confounders:
Commands and raw-output locations:
Observed results:
Verdict: supported | falsified | inconclusive
Independent evidence:
Negative results and fenced paths:
Open uncertainty:
Owner and next gate:
```
Preserve negative results with the same care as positive results. Route a
recurring rejected approach to `archie-failure-archaeology`.
### Gate 8 — Hand off; do not self-approve
Send ownership/boundary conclusions to
`archie-architecture-planning-campaign`. Send deprecation and deletion to
`archie-technical-accountability`. Send tests and acceptance thresholds to
`archie-validation-and-qa`, then route every behavior-changing proposal through
`archie-change-control`.
Research acceptance does not authorize implementation, config mutation,
dependency changes, deployment, data migration, or deletion. A fresh
adversarial reviewer must be able to reproduce the packet without the
researcher's unstated knowledge.
## Choose an Archie experiment
Write every `N`, `R`, `M`, latency, allocation, and ratio prediction before
running its command.
| Question | Controlled method | Required prediction and falsifier |
|---|---|---|
| Are two paths duplicates? | Run `golangci-lint run --enable-only=dupl ./internal/<area>/...`; then trace both by domain effect, entrypoint, state mutation, mode, and consumer with `archie-codebase-discovery` | Predict textual candidates `N`, live authorities, and preserved differences. Falsify “one authority” with a second production-selected path that decides or mutates the same meaning. |
| Is code dead or a one-shot abstraction? | Run `staticcheck -checks=U1000 ./internal/<area>/...`, `gopls references -d <file:line:column>`, and the discovery skill's AST construction scan; inspect registrations, Yaegi, tags, build variants, tests, and both binaries | Predict typed references `R`, production constructions, dynamic registrations, and compatibility consumers. Zero text hits alone is never the falsifier. |
| Does configuration affect production? | Trace `key → decode → default → validate → translate → cmd/archied read → concrete component → observable`; inspect Compose passthrough separately | Predict exactly one effective owner and every production read. As of 2026-07-28, `cmd/archied` has two `config.LoadOverlay` call sites and no `LoadDir` call; `LoadDir` tests therefore do not prove production selection. |
| Do execution modes have parity? | Enumerate the three accepted `agent.mode` values from `internal/config`; test the same input/error/cancel matrix through `inprocess`, `subprocess`, and `nats`; treat containers as a NATS deployment assembly, not a fourth mode | Predict `M` matrix rows and the exact outcome for every cell. One direct runner unit test cannot falsify a mode-wiring defect. |
| Are persistence transitions correct? | Run shared legal/illegal transition cases against SQLite and `internal/nell`; include two stale-`from` contenders, state reload, and audit evidence under `-race` | Predict `2/2` adapters reject stale `from`, one winner, unchanged loser, and one matching audit record. Current `Store.Transition` and `Adapter.Transition` ignore `from`; classify that observation as current/open until corrected and accepted. |
| Is a protocol compatible? | Preserve canonical bytes/messages; run malformed, partial, multi-message, timeout, EOF, and cancellation cases; then run an official or independent peer | Predict handshake/result bytes and error identity. A fake peer using Archie's `readMessage`/`writeMessage` cannot satisfy independence. |
| Is cancellation/concurrency safe? | Use barriers/channels to force ordering; test cancel-before-start, cancel-while-blocked, close/send, retry, and shutdown; run `go test -race ./internal/<area>/... -count=1` | Predict terminal result, side-effect count, retry count, resource closure, and absence of races. Wall-clock sleep alone is not a schedule proof. |
| Do NellDB scans meet a requirement? | Define fixture sizes `N` and `10N`; benchmark the exact adapter query with fixed data, cache state, and run count; capture `-benchmem` | Predict latency/allocation slope and acceptance bound before running. `internal/nell/adapter.go` has 14 `AllDocs` call sites as of 2026-07-28; that is structural evidence of scans, not a performance result. |
| Did maintainability improve? | Compare owner count, production paths, package edges, public surface, config consumers, complexity findings, and files a future feature must understand; inspect every changed non-test file | Predict which counts fall, stay equal, or may rise with rationale. Linter silence and a lower aggregate score do not prove cohesion, readability, or artfulness. |
| Is a migration parity-safe? | Build an old/new matrix across config forms, stored data, modes, peers, errors, restart/recovery, rollback, and deletion criteria; execute every supported row | Predict `M` rows and exact observable parity. A PRD or candidate branch cannot satisfy a live row. Permanent duplicate authoritative paths after cutover must be `0`. |
Replace `<area>` and `<file:line:column>` with concrete values recorded in the
research packet. Use `archie-diagnostics-and-tooling` when a metric needs a
repeatable helper rather than an ad hoc shell pipeline.
## Learn from settled failures
| Lesson | Archie evidence | Research rule |
|---|---|---|
| Mirrored peers can validate the same wrong protocol | MCP `Content-Length` work in `f2768eb`/`3ad57c9` passed a server using the same helpers; `dda4cde` moved live framing to newline-delimited JSON and `TestDesktopCommanderClientCompatibility` supplies an opt-in external peer | Require independent bytes or peer behavior before claiming compatibility. |
| Green loader tests do not prove shipped wiring | `internal/config/feature_config_test.go` exercises `LoadDir`, while `cmd/archied/main.go` selects `LoadOverlay` as of the dated snapshot | Trace from a real entrypoint through the effect. |
| A linter name is not a semantic verdict | `86cfc19` records eleven `nilerr` findings whose errors were deliberately carried through text, envelopes, shutdown, or best-effort behavior; live sites explain local suppressions | Predict the contract consequence per site before changing it. |
| Diagnostics can measure the environment instead of the code | Listener-denied sandboxes, inherited GPG settings, read-only temp paths, and stale editor diagnostics have produced different failures from host runs | Freeze environment and confirm with real build/test output; never waive the blocked evidence. |
| A local dependency can make a local result unreproducible | `07fb291` removed a machine-local NellDB `replace` that CI/container builds could not resolve | Use the published module and checksum path; label local-checkout evidence candidate. |
| “Cleanup” can change behavior while looking mechanical | `308c199` changed the skillscript wrapper to `sh -c` with argument placement that now yields only a newline in the focused test | Treat every cleanup diff as authored semantics and keep the pre-change baseline. |
## Fence off wrong paths
- Do not choose success criteria after seeing output.
- Do not let a client and fake server import the same framing, parser, or
constants and call the result compatibility.
- Do not change implementation, tests, config, or fixtures during baseline
capture.
- Do not treat a candidate branch, commit subject, comment, PRD, or old
architecture document as live proof.
- Do not infer dead code from text search or `U1000` alone.
- Do not equate coverage, lint silence, or green TDD with production wiring,
one coherent owner, or maintainability.
- Do not suppress a negative result because the attempted slice was small.
- Do not reduce artfulness to one complexity score; measure locality and then
review names, ownership, cohesion, failure clarity, and deletion.
## Provenance and maintenance
Re-verify current versus target authority: `sed -n '1,180p' docs/prds/01-project-management.md && sed -n '1,180p' docs/prds/architecture/package-review.md`
Re-verify module and gate boundaries: `find . \( -path './.git' -o -path './.references' -o -path './.claude/worktrees' -o -name node_modules \) -prune -o -name go.mod -print && sed -n '1,180p' Taskfile.yml`
Re-verify configuration selection: `rg -n 'config\.(Load|LoadOverlay|LoadDir)\(' cmd internal --glob '*.go'`
Re-verify execution modes: `rg -n 'case "inprocess"|case "subprocess"|case "nats"|agent\.mode' cmd/archied internal/config --glob '*.go'`
Re-verify transition semantics: `sed -n '255,285p' internal/store/store.go && sed -n '268,290p' internal/nell/adapter.go`
Re-verify NellDB scan candidates: `rg -n 'AllDocs\(' internal/nell/adapter.go`
Re-verify protocol independence: `rg -n 'readMessage|writeMessage|TestDesktopCommanderClientCompatibility|newline-delimited|Content-Length' internal/tools --glob '*.go'`
Re-verify the cleanup regression: `env GOTMPDIR=/tmp GOCACHE=/tmp/archie-research-gocache GIT_CONFIG_GLOBAL=/dev/null go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v`
@@ -0,0 +1,4 @@
interface:
display_name: "Archie Research Methodology"
short_description: "Turn Archie hunches into reproducible evidence"
default_prompt: "Use $archie-research-methodology to design a falsifiable Archie experiment and decision record."
@@ -0,0 +1,384 @@
---
name: archie-run-and-operate
description: "Run and observe Archie safely from a local binary or the repository Docker Compose stack. Use when starting or stopping archied, running an archie-agent NATS worker, checking readiness, following logs, locating task state/worktrees/memory/container volumes, understanding inprocess/subprocess/NATS execution, inspecting the deployment watcher or image pipeline, or planning an operational rollback without changing architecture."
---
# Run and operate Archie
Use this runbook to operate the implementation that exists on **2026-07-28**.
Treat source and tests as current; treat `docs/archive/` as history, not an
operational contract.
## Route work to the right skill
Do **not** use this skill to:
- install Go, Task, Docker, or project dependencies; use
`archie-build-and-env`;
- choose, add, or migrate flags and TOML fields; use
`archie-config-and-flags`;
- diagnose a failure beyond the first observations below; use
`archie-debugging-playbook`;
- inspect or repair NellDB data; use `archie-nelldb`;
- decide whether a runtime or deployment change is acceptable; use
`archie-change-control` and `archie-validation-and-qa`;
- redesign process boundaries or deployment topology; use
`archie-architecture-planning-campaign` and
`archie-architecture-contract`.
## Define the process shapes
| Term | Meaning here |
|---|---|
| `archied` | Resident orchestrator. It owns config, forge credentials, the NellDB store, worktrees, gateways, the dashboard, and optional NATS/Docker orchestration. |
| `archie-agent` | Current long-running NATS worker. It consumes legacy per-stage requests and full-task `archie.taskrun.>` requests. It is **not** a stdin/stdout worker. |
| Stage request | One autonomous workflow stage sent on `archie.agent.<task-id>.request`. |
| Full-task handoff | A whole workflow sent on core NATS subject `archie.taskrun.<task-id>` to a task container. |
| Work directory | `work_dir`: task clones plus memory and candidate index artifacts. |
| State database | `db_path`: the NellDB append-log file holding tasks, events, and Nell-backed chat sessions/messages. It is not SQLite despite the `.db` examples and stale comments. |
## Apply the operational safety boundary
Assume every daemon start can change local and external state.
- Obtain explicit authority for the config, forge identity, repositories, NATS
account, Docker host, and deployment host before starting anything.
- Never use production tokens for a smoke test.
- Do not call `archied -once` as a dry run. It accepts invitations, verifies
push access, polls the forge, enqueues/labels work, reconciles PRs, processes
tasks, and then exits.
- Do not call `archied -requeue` while observing. It mutates durable task state.
- Do not start a standalone `archie-agent` against an unfamiliar NATS URL. It
immediately joins the worker pool and may execute queued work.
- Do not expose the dashboard publicly. It has no authentication, and
`POST /api/tasks/clear` deletes terminal task records even though the package
describes the dashboard as read-only.
- Do not print secret values. Record environment-variable **names**, config
checksums, image digests, and paths instead.
- Stop with `Ctrl-C`, `SIGTERM`, or Compose. Do not use `SIGKILL` unless graceful
shutdown has demonstrably failed.
There is no config-only or dry-run flag. Validate a candidate config through
`archie-config-and-flags` and tests before allowing the daemon to open it.
## Know the command surfaces
### `archied`
| Flag | Exact behavior |
|---|---|
| `-config <path>` | Load base TOML. Default: `$XDG_CONFIG_HOME/archie/config.toml`, or `~/.config/archie/config.toml`. |
| `-config-overlay <path>` | Decode a second TOML file into the base config before defaults and validation. |
| `-once` | Run startup plus one poll/process cycle, then exit. This changes state. |
| `-requeue <task-id>` | Requeue a parked/waiting task, then exit unless `-once` is also set. This changes state. |
### `archie-agent`
| Flag or environment | Exact behavior |
|---|---|
| `-nats-url <url>` | Select NATS; falls back to `NATS_URL`. One of them is required. |
| `-consumer <name>` | Set the durable JetStream consumer name; default `archie-agent`. |
| `NATS_TOKEN` | Optional NATS token read directly by the worker. |
Both linked binaries may also display Go's dependency-registered
`-quickchecks` flag. It belongs to `testing/quick`; it is not an Archie
operations control.
## Select the execution mode deliberately
| Config shape | What runs | Operational status on 2026-07-28 |
|---|---|---|
| `agent.mode = "inprocess"` and no `[nats]` | `archied` polls and claims from NellDB, then runs workflow stages and model tools in its own process. | **Production-wired candidate.** `config.production.toml` selects it, but live production was not inspected. No process or OS isolation. |
| `agent.mode = "subprocess"` | `archied` starts `agent.command` per stage and expects one JSON invocation on stdin and one response on stdout. | **Open/broken with the default command.** `cmd/archie-agent` is a long-running NATS worker and never calls `agentexec.ServeOne`. No compatible repository entrypoint was found. |
| `agent.mode = "nats"`, `[nats]`, containers disabled | `archied` still runs the workflow, but each autonomous stage goes to a separately started `archie-agent`. | **Implemented but operator-assembled.** The Compose `agent` service is not a running worker; launch and supervise a worker separately. |
| `agent.mode = "nats"`, `[nats]`, `containers.enabled = true` | `archied` publishes task discovery through JetStream, prepares a worktree, spawns one agent container, and sends the whole workflow on `archie.taskrun.<id>`. | **Repository Compose path.** `config.docker.toml` wires it. Live production status is unknown, and the limitations below remain. |
Config validation requires containers to use NATS mode, a non-empty NATS URL,
and a container image.
## Run a local foreground daemon
First build through `archie-build-and-env`. The non-mutating build commands in
that skill write binaries to `/tmp/`; the commands below expect `task build` to
have placed them in `bin/`. Either run `task build` first, or set explicit
variables:
```bash
# Either use task build (authorized writable worktree only):
task build
# …or point at the /tmp binaries from the build skill's cold-start sequence:
# ARCHIE_DAEMON_BIN=/tmp/archie-core-archied
# ARCHIE_AGENT_BIN=/tmp/archie-core-agent
```
Then perform only read-only orientation:
```bash
task --list
./bin/archied -h
./bin/archie-agent -h
```
Choose an explicitly approved config; do not substitute
`config.example.toml` blindly because its repository and forge values are
examples:
```bash
ARCHIE_CONFIG=/absolute/path/to/config.toml
test -r "$ARCHIE_CONFIG"
```
Start in the foreground only after the safety boundary is satisfied:
```bash
./bin/archied -config "$ARCHIE_CONFIG"
```
Apply an approved deployment overlay with:
```bash
ARCHIE_OVERLAY=/absolute/path/to/config.overlay.toml
test -r "$ARCHIE_OVERLAY"
./bin/archied -config "$ARCHIE_CONFIG" -config-overlay "$ARCHIE_OVERLAY"
```
Expect JSON logs on stderr. Require the following sequence as applicable:
1. `nats connected` when `[nats]` is configured.
2. `workflow registry built`.
3. `memory manager started`.
4. `web ui listening` unless `web.listen = "off"`.
5. gateway-start messages for configured Telegram, email, or webhook channels.
6. `archied running` after startup verification and before the resident loop.
Absence of `archied running` means startup did not complete. The daemon has no
HTTP health endpoint and no container healthcheck; a running process alone is
not readiness evidence.
Stop the foreground process with `Ctrl-C`. The signal cancels active work,
waits for dispatch goroutines, stops capability and memory managers, removes
Archie-labelled containers, closes NATS, and closes the NellDB log. Allow the
bounded cleanup calls to finish.
## Run a standalone NATS worker
Use this only for an approved NATS-without-containers deployment:
```bash
NATS_URL=nats://127.0.0.1:4222 ./bin/archie-agent
```
Require both `nats connected` and `archie-agent ready`. Stop with `Ctrl-C`.
Assign a non-default `-consumer` only when the queue topology has been reviewed;
consumer names define durable JetStream state.
Do not use this command to test subprocess mode. The worker requires NATS and
does not speak the subprocess JSON protocol.
## Run the repository Compose stack
Read `docker-compose.yml` and the host base config before acting. Compose mounts
`${HOME}/.config/archie/config.toml` as the base and
`config.docker.toml` as the overlay. It also mounts the Docker socket and
host data directories, so this is host-authoritative execution.
| Repository command | Actual scope |
|---|---|
| `task docker-build` | Build only the `agent` image from `Dockerfile`. It does not build `archied`. |
| `task docker-up` | Run `docker compose up -d` for **all** services, including watchtower. |
| `task docker-logs` | Follow only the `archied` service logs. |
| `task docker-down` | Run `docker compose down`. It does not request volume deletion. |
Prefer the narrow start when a deployment watcher is not intended:
```bash
docker compose up -d nats archied
```
Use read-only observations:
```bash
docker compose ps
docker compose logs --tail=200 archied
docker compose logs --tail=200 nats
docker compose exec -T nats wget -q -O - http://localhost:8222/healthz
```
If a local HTTP client is installed, inspect only GET endpoints:
```bash
curl -fsS http://127.0.0.1:8484/api/summary
curl -fsS http://127.0.0.1:8484/api/tasks
```
The NATS healthcheck must become healthy before Compose starts `archied`.
Require `archied running` in logs as the daemon readiness gate. Do not invoke
`POST /api/tasks/clear`.
Stop the repository stack with:
```bash
task docker-down
```
Never add `-v` during routine shutdown; `nats_data` and any Compose-managed
volumes may contain durable state.
The Compose `agent` service is a build-only placeholder: it clears the image
entrypoint and runs `true`. Actual task workers are spawned by `archied`
through `/var/run/docker.sock`.
## Locate output and durable state
| Output or state | Current destination |
|---|---|
| Daemon logs | JSON on stderr; Docker's configured log driver captures them under Compose. The repository defines no log file or rotation policy. |
| Agent logs | JSON on worker/container stderr. Task containers use `AutoRemove`; capture logs while the container exists because the repository defines no agent log archive. |
| Tasks, events, chat sessions/messages | NellDB append log at `db_path`; default `~/.local/share/archie/archie.db`. |
| Default task worktree | `<work_dir>/<owner>-<repo>/issue-<number>`; default root `~/.local/share/archie/work`. |
| Identity worktree | `<work_dir>/identity-<identity>/<owner>-<repo>/issue-<number>`. |
| Container worktree | Host worktree bind-mounted read/write at `/data/worktree`; `task.json` is written at its root and ignored by this repository's `.gitignore`. |
| Built-in memory | `<work_dir>/memory/MEMORY.md` and `<work_dir>/memory/USER.md`. |
| Telegram update state | `<work_dir>/telegram-update-deferrals.json` plus a hashed `release-announcements-*.json`. |
| Codesearch candidates | Defaults derive as `<work_dir>/indexes` and `<work_dir>/workspace-indexes.db`; no `indexing.Manager` construction was found in the daemon composition root, so do not assume these artifacts are produced. |
| Optional repository volume | `archie-repo-<owner>-<repo>` mounted at `/data/repo`. The workflow still runs in `/data/worktree`. |
| Ecosystem cache volumes | `archie-cache-go`, `archie-cache-node`, `archie-cache-pnpm`, `archie-cache-deno`, `archie-cache-bun`, `archie-cache-pip`, or `archie-cache-cargo`, mounted below `/data/cache`. No code currently sets tool cache environment variables to those mount paths; a mount is not proof of cache use. |
| NATS data | Compose declares `nats_data:/data`, while its NATS command does not set a store directory. Verify the live server's store directory before claiming this volume preserves JetStream data. |
| Forge-visible output | Reactions, state labels, comments, pushed task branches, closed issues, and PRs. These are external mutations, not local logs. |
In Compose, the host paths are:
- `/var/lib/archie/work` for worktrees;
- `/var/lib/archie/db/archie.db` for the container's
`/var/lib/archie/archie.db`;
- the repository checkout mounted at `/workspace`;
- the host Docker socket mounted into `archied`.
Parked worktrees are retained for investigation. Terminal cleanup behavior is
owned by the worktree/daemon lifecycle; do not delete paths manually while a
task is active.
## Understand NATS and container observation
The `ARCHIE_TASKS` JetStream stream uses file storage and work-queue retention
for `archie.task.>` and `archie.agent.>`.
| Plane | Subjects and behavior |
|---|---|
| Discovery | `archie.task.bug`, `.feature`, `.bootstrap`, or `.default`; daemon durable consumer `archie-daemon`, 5-minute ack wait, max 3 deliveries. |
| Legacy stages | `archie.agent.<id>.request`; worker durable consumer defaults to `archie-agent`, 30-minute ack wait, max 3 deliveries; response address travels in `X-Archie-Reply`. |
| Container task | Core NATS request/reply on `archie.taskrun.<id>`. A task container reads `/data/worktree/task.json` and creates a dedicated subscription; a shared worker uses queue group `archie-taskrun-workers`. |
| Privileged RPC | Store, forge, and worktree operations return to `archied` over core NATS subjects in `internal/storerpc`, `internal/forgerpc`, and `internal/worktreerpc`. |
Set `containers.network` explicitly. `config.docker.toml` uses
`archie-core_default`. Auto-detection inspects the daemon container; on failure,
spawned workers join Docker's default bridge and cannot resolve `nats` by
service name. An initial `ErrNoResponders` is retried for 20 seconds at 250 ms
intervals; other request errors are not readiness retries.
If `nats.token_env` is configured, `archied` refuses startup when that variable
is empty. It injects the resolved value as `NATS_TOKEN` into task containers.
It also forwards only configured provider-key variables. Compose forwards a
fixed environment list; adding a config reference without matching Compose
passthrough leaves the container empty.
## Fence current operational limitations
Treat these as open until code and tests prove otherwise:
- `subprocess` plus default `archie-agent` is protocol-incompatible.
- `config.production.toml` is not proof of a working deployment. Its identity
uses legacy `token_env`, while current validation requires each identity's
`forge.token` secret reference.
- Container-mode RPC servers use root forge/worktree objects for every
identity; non-root identity tasks can use the wrong authority.
- Container orphan recovery and pool shutdown select every container labelled
`archie-daemon=true`, without a daemon-instance label. One daemon can remove
another daemon's workers on the same Docker host.
- `containers.max_uptime` only bounds the create/start context in
`Pool.Acquire`; no running-container timer enforces the advertised lifetime.
- The container workflow builds `TaskContext` without an event bus. Do not
expect in-process stage/agent event timelines to have container-mode parity.
- Live SSE clients drop events when their channel is full. Reconnect with the
last event ID to replay at most 200 stored events.
- The dashboard binds `0.0.0.0:8484` in the Docker overlay and Compose publishes
port 8484. It is unauthenticated and includes a mutating clear endpoint.
Route operational symptoms from these limitations to
`archie-debugging-playbook`; route fixes through change control.
## Understand deployment and rollback seams
The repository Gitea workflow runs on pushes to `main` and component tags. It
builds and pushes only:
- `git.catlow.cloud/sam/archied:latest`;
- `git.catlow.cloud/sam/archie-agent:latest`.
It injects component versions into labels/binary metadata but does not publish
versioned image tags. It runs no repository quality gate (`task check`, tests,
lint, or vet) before Docker builds; the Docker builds themselves compile the
binaries. Treat a successful workflow as image publication evidence only, not
application acceptance evidence.
Compose watchtower polls every 60 seconds with `--cleanup` and names
`archie-core-archied-1` plus `archie-core-archied-winter-1`. The workflow never
contacts the host directly. Do not infer that watchtower found, restarted, or
validated either live daemon.
Before any authorized promotion:
- record the running image IDs and immutable registry digests;
- record config file checksums without printing secrets;
- record task counts and active task IDs through safe GET observations;
- establish a NellDB-consistent backup procedure with `archie-nelldb`;
- define which prior digest will be restored and who may restart services.
The repository has no complete rollback command and publishes no versioned
image tags. Do not improvise a production rollback from `latest`; route it
through `archie-change-control`. Restoring a binary does not undo forge changes,
task transitions, or data-format changes.
## Treat carina facts as unverified external state
Repository guidance dated 2026-07-28 says two live instances run on `carina`
with distinct `bot_user` values. An archived PRD says this was confirmed on
2026-07-25, while `config.production.toml` proposes replacing them with one
multi-identity process and Compose watchtower still names two containers.
No live `carina` process list, config, image digest, service manager, or
deployment success was verified for this skill. Do not invent SSH, systemd, or
service commands. Query the approved operational source of truth under explicit
production-read authority before acting.
## Use the operator checklist
- [ ] Confirm the target host, config paths, bot identity, repos, and authority.
- [ ] Confirm secret variable names exist without printing values.
- [ ] Select one execution row from the mode matrix.
- [ ] Capture baseline logs, task summary, image digests, and config checksums.
- [ ] Start only the required services; exclude watchtower unless intended.
- [ ] Require NATS health when configured and `archied running` always.
- [ ] Observe NellDB state and forge-visible effects, not process status alone.
- [ ] Stop gracefully and allow deferred cleanup to finish.
- [ ] Confirm no tasks remain `running`; startup will requeue stale ones.
- [ ] Record open deviations and route behavior changes through validation and
change control.
## Provenance and maintenance
Verified against repository state on **2026-07-28**. Re-run these one-line,
read-only checks after changes:
```bash
rg -n 'flag\.(String|Bool|Int64)' cmd/archied/main.go cmd/archie-agent/main.go
sed -n '1,120p' Taskfile.yml
sed -n '1,220p' docker-compose.yml
sed -n '1,220p' config.docker.toml
rg -n 'Mode|Command|NATS|Containers|WorkDir|DBPath|withDefaults|MaxUptime|PullPolicy' internal/config/config.go internal/config/indexer.go
rg -n 'SubprocessRunner|ServeOne|taskRunSubjectWildcard|archie-agent ready' internal/agentexec cmd/archie-agent
rg -n 'AutoRemove|archie-daemon|recoverOrphans|MaxUptime|NetworkMode' internal/container/pool.go
rg -n 'WorktreeMountDir|archie-cache-|archie-repo-|CleanupExpired' internal/storage/storage.go
rg -n 'HandleFunc|api/summary|api/tasks|events|ListenAndServe' internal/webui/webui.go
sed -n '1,220p' .gitea/workflows/deploy.yml
```
@@ -0,0 +1,4 @@
interface:
display_name: "Run and Operate Archie"
short_description: "Run Archie safely and locate its operational state"
default_prompt: "Use $archie-run-and-operate to start Archie locally, inspect its runtime state, and stop it safely."
@@ -0,0 +1,400 @@
---
name: archie-technical-accountability
description: Prove that an Archie change is maintainable, owned, reachable, reversible, and simpler than the code it replaces. Use when designing, implementing, reviewing, or accepting a feature, refactor, configuration path, registry, adapter, interface, or cleanup; when tests are green but code quality is uncertain; or when duplicate paths, dead code, one-use abstractions, supersession, production wiring, or concern ownership may be hidden.
---
# Archie Technical Accountability
Accept behavior only after proving both correctness and maintainability. Treat a
green test as evidence about the tested seam, never as proof that production
uses the seam or that the design has one coherent owner.
Use imperative runbook voice in the resulting review. Mark every conclusion as
`proven`, `candidate`, or `open`. Do not convert absence of evidence into proof.
## Route the work
Load the sibling skill named for each responsibility:
| Need | Load instead or next |
| --- | --- |
| Select domains, boundaries, ownership, or a migration shape | `archie-architecture-planning-campaign` first |
| Traverse an unfamiliar area, its AST, consumers, runtime paths, or history | `archie-codebase-discovery` first |
| Classify the change and determine required gates and reviewers | `archie-change-control` |
| Prove tests, lint, formatting, race behavior, or acceptance thresholds | `archie-validation-and-qa` |
| Triage an active failure or unexplained runtime symptom | `archie-debugging-playbook` first |
| Reconstruct a historical failure, revert, rejected fix, or settled dead end | `archie-failure-archaeology` first |
Do **not** use this skill as:
- a substitute for architecture planning before ownership is decided;
- a substitute for deep codebase discovery or AST-aware call-path analysis;
- a debugging playbook for an active incident;
- permission to implement before the repository's change-control and TDD rules;
- a reason to keep an obsolete path "for safety"; define a real rollback and
deletion plan instead.
## Define the evidence vocabulary
- **Owner**: the one domain or capability accountable for a behavior, its
vocabulary, state, rules, settings, and required service contracts.
- **Source of truth**: the only authoritative implementation or mutable record
for one meaning. Adapters may translate it; they must not reimplement it.
- **Consumer**: production code, test code, generated code, or an external
process that calls, imports, decodes, registers, or depends on the subject.
- **Production wiring**: the executable path from a real `cmd/*` entry point,
configuration source, or inbound adapter through composition to an observable
effect.
- **Parallel path**: another implementation that can satisfy the same intent or
mutate the same state, even when names and types differ.
- **One-shot abstraction**: an interface, wrapper, registry, service, or helper
introduced for one call or implementation without owning policy, lifecycle,
translation, isolation, or a stable boundary.
- **Deletion criterion**: an observable condition that permits removing a
legacy or compatibility path.
- **Archaeology**: history evidence explaining why a seam exists, what it
replaced, and which failed approach must not be repeated.
## Produce one accountability record
Attach one record to the change artifact selected by
`archie-change-control`. Do not create an ad hoc TODO document. Complete the
record before implementation, then update it from the final diff.
### Header
| Field | Required content |
| --- | --- |
| Requested outcome | One behavior stated without naming an implementation |
| Change class | Classification from `archie-change-control` |
| Owner | One current owner and, during migration, one approved target owner |
| Source of truth | Current authoritative code/state and the post-change authority |
| Scope | Packages, entry points, settings, persisted records, and contracts touched |
| Accountable actors | Implementer and independent adversarial reviewer |
| Status | `proven`, `candidate`, or `open` |
### Consumer and path inventory
Record every row; use `none proven` rather than leaving a cell blank.
| Consumer/path | Entry | Dispatch or translation | Authority called | Effect | Evidence |
| --- | --- | --- | --- | --- | --- |
| Production | command, channel, worker, poller, or startup | exact functions | exact owner | state/output | file:line and test |
| Alternate process | subprocess, NATS worker, container, or RPC | exact contract | exact owner | state/output | file:line and test |
| Dynamic | registry, plugin, Yaegi, callback, reflection, or config | registration/load seam | exact owner | state/output | file:line and test |
| Tests | focused, integration, contract, race | seam exercised | fake or real authority | assertion | test name |
| Generated/docs | generator or schema consumer | source contract | owner | artifact | generator path |
Block acceptance if a production row stops at a constructor, parser, registry,
schema, test fake, or helper subcommand without reaching the running
composition path.
## Run the accountability workflow
### 1. Freeze the behavioral claim
Write one sentence:
> When `<real entry>` receives `<input>`, `<owner>` performs `<behavior>` and
> produces `<observable result or failure>`.
Reject claims such as "add manager," "add interface," or "support YAML." Those
name an implementation, not an outcome.
List the behavior that must remain unchanged. Include persistence, errors,
timeouts, concurrency, process boundaries, authorization, and compatibility
when applicable.
### 2. Establish the owner and source of truth
Read the approved architecture requirements and the live code. Keep the two
states distinct. As of 2026-07-28:
- `docs/prds/architecture/organisation.md` defines the approved target
organization.
- `docs/prds/architecture/dependencies-and-contracts.md` defines strict target
dependency direction and contract ownership.
- `docs/prds/architecture/configuration.md` requires dissolution of the current
shared `internal/config` model; this is an approved target, not completed
live behavior.
- `docs/prds/architecture/package-review.md` requires current-state research
before package decisions.
Answer:
1. Which cohesive job owns this behavior?
2. Which mutable record or function is authoritative now?
3. Which authority will remain after the change?
4. Is another package allowed to mutate the same meaning?
5. Does the proposed location reduce or increase required knowledge?
Block if the answer is "shared," "config," "utils," "manager," or "registry"
without naming the behavior owner. Mechanics may be shared; domain meaning may
not.
### 3. Inventory all consumers and call paths
Start with text and package evidence:
```bash
rg -n '\bMessageEvent\b' --glob '*.go' .
rg -n '\bMessageEvent\b' --glob '*.go' --glob '!**/*_test.go' .
go doc github.com/samcharles93/archie-core/internal/gateway.MessageEvent
go list -f '{{.ImportPath}}: {{join .Imports " "}}' ./...
go list -deps ./cmd/archied ./cmd/archie-agent
go -C tools list ./...
```
Replace `MessageEvent` and its package path with the subject under review.
Separate production, test, generated, and documentation hits. An imported
package proves only package reachability, not function reachability. The
`tools` directory is a nested Go module, so root `go list ./...` does not include
it; inspect it separately whenever the change touches generation tooling.
Trace each real path in both directions:
1. Start at `cmd/archied`, `cmd/archie-agent`, or an inbound adapter.
2. Follow construction, registration, translation, dispatch, and callbacks.
3. Continue through interfaces to every implementation.
4. End at persisted state, outbound I/O, or a user-visible result.
5. Walk backward from the effect to find alternate writers.
Use `archie-codebase-discovery` for AST traversal. `rg` cannot resolve
interface dispatch, method expressions, callbacks, reflection, generated
registries, Yaegi-loaded code, or config-selected implementations. Never declare
code dead from text search alone.
### 4. Detect duplicate, parallel, and superseded paths
Search by domain language and effects, not only symbol names:
```bash
rg -n -i 'message|conversation|session|reply|acknowledg' internal cmd --glob '*.go'
rg -n -i 'insert|update|put|delete|transition|publish|enqueue' internal cmd --glob '*.go'
rg -n 'TODO|FIXME|HACK|XXX' internal cmd docs --glob '*.go' --glob '*.md'
```
Narrow those searches to the changed behavior. Compare:
- inputs and outputs;
- state read and written;
- retry, timeout, error, and fallback semantics;
- authorization and identity;
- startup, shutdown, and health behavior;
- process-specific implementations;
- test doubles that may mirror the implementation rather than the contract.
Complete this supersession table:
| Existing path | Proposed relation | Production caller | Parity needed | Deletion criterion |
| --- | --- | --- | --- | --- |
| exact path | retain, adapt, merge, supersede, or delete | exact entry | named semantics | observable condition |
Block if new work overlaps an existing path without one explicit relation.
Block any indefinite "temporary" compatibility path. A dual path requires a
named cutover, authoritative side, observation method, and deletion criterion.
### 5. Prove production wiring
For every feature, prove this complete chain:
```text
real input -> loader/adapter -> application composition -> owner
-> side effect -> observable success/failure
```
Require all of:
- a source citation at each handoff;
- one focused behavior test;
- one composition, integration, or contract test that crosses the handoff;
- a negative test proving the old/unconfigured/failed path does not masquerade
as success;
- an operator- or caller-visible failure when silent fallback would hide loss.
A decode test proves decoding. A constructor test proves construction. A
registry test proves registration. None proves production wiring.
For protocols, validate against an independent implementation, published
fixture, or official SDK. A client tested only against a server using the same
framing/parser proves self-consistency, not interoperability.
### 6. Hold configuration to concern ownership
Classify every behavioral value as the approved configuration requirements
direct:
| Class | Meaning |
| --- | --- |
| Invariant | Changing it changes a domain concept or wire meaning |
| Runtime setting | An installation, identity, domain, plugin, or deployment may choose it |
| Policy value | It controls permission, limits, routing, retry, protection, or gates |
| Derived value | It is computed and not independently mutable |
| Runtime state | A domain command changes it during operation |
For each new or changed setting, require:
- one domain/plugin owner;
- type, units, constraints, safe bounds, default, and derivation;
- startup-only, reloadable, or restart-required semantics;
- scope: installation, identity, repository, workflow, channel, or plugin;
- secret/sensitive/reportable classification;
- external DTO decoding separated from the owner's runtime settings;
- composition translation and validation;
- an exact production consumer;
- compatibility and last-known-good behavior;
- documentation and tests for invalid, omitted, and explicit values;
- removal of any superseded field or a bounded migration plan.
Do not deepen `internal/config` merely because it is convenient. If migration
timing forces a compatibility edit there, label it transitional and route the
ownership decision through `archie-architecture-planning-campaign`.
### 7. Challenge every abstraction and dead-path candidate
Use this table during manual review:
| Signal | Required challenge | Accept only when |
| --- | --- | --- |
| Interface has one implementation and one consumer | Why is dynamic substitution required? | It owns a consumer need, stable boundary, or useful test seam |
| Wrapper delegates one operation | What policy, translation, lifecycle, or isolation does it own? | The added responsibility is named and tested |
| Manager/registry exists without lifecycle wiring | Who starts, uses, observes, and stops it? | Production composition and failure paths are proven |
| Exported type appears only in tests/generation | Is it a contract or an abandoned future path? | A real external consumer is cited or it is removed/labeled candidate |
| Config field is decoded but never consumed | What running behavior changes? | Exact constructor/operation use is cited and tested |
| Branch/fallback has no constructible input | What reaches it? | A real path and negative test exist |
| Replacement leaves old reads/writes | Which side is authoritative? | Cutover and deletion criteria are explicit |
| Helper exists for one call | Would direct code be clearer? | The helper names a stable concept or removes real duplication |
Do not keep an abstraction for hypothetical reuse. Do not delete a dynamic path
until AST, registry, plugin, configuration, and runtime evidence are checked.
### 8. Justify interfaces and locations
Require a one-paragraph location decision:
1. Name the behavior and owner.
2. Name the dependencies it may import.
3. Name the smallest contract it needs.
4. State why the contract belongs with the domain/capability that defines its
meaning.
5. State why infrastructure representations do not leak through it.
6. State what future change should remain local to this package.
Reject ceremonial `entities`, `repositories`, or `services` layers; the
approved organization document prohibits them. Reject an interface that merely
duplicates a concrete API without narrowing authority.
### 9. Review readability and artfulness
Treat artful code as code with an obvious owner, a small surface, explicit
consequences, and no cleverness tax. Review every changed non-test file and
answer:
- Can a zero-context mid-level engineer explain the behavior without traversing
unrelated domains?
- Do names use the domain vocabulary rather than `helper`, `manager`, `data`,
`thing`, or transport vocabulary?
- Does each function perform one coherent step at the right abstraction level?
- Are error, rollback, cancellation, and shutdown paths adjacent and visible?
- Do comments explain why a constraint exists rather than narrate syntax?
- Can a reader distinguish authority from adapter, DTO, projection, and cache?
- Did the change remove more accidental concepts than it added?
Block if the reviewer cannot summarize owner, input, decision, effect, and
failure in five plain sentences. Simplify before adding comments that explain a
convoluted path.
### 10. Prove reversibility and deletion
Do not use retained dead code as rollback. Record:
| Concern | Required proof |
| --- | --- |
| Source rollback | Known-good release/change and behavioral compatibility |
| Data rollback | Migration direction, backup, forward/backward readability, and loss risk |
| Runtime rollback | Health signal, observation period, bounded retry, and last-known-good behavior |
| Compatibility | Authoritative path, expiry/cutover, and removal owner |
| Deletion | No production/test/generated consumers, parity evidence, config/docs removal, regression guard |
The approved recovery requirements are in
`docs/prds/architecture/safe-change-and-recovery.md`; exact runtime-supervision
mechanics remain under design as of 2026-07-28. Label unimplemented mechanics
`open`; do not describe them as available.
### 11. Perform post-change archaeology
Re-run discovery against the final diff:
```bash
git diff --name-status
git diff --stat
git log --all --date=short --oneline -- internal/gateway
git log -S'MessageEvent' --all --oneline -- internal/gateway
git blame internal/gateway/messageevent.go
rg -n '\bMessageEvent\b' --glob '*.go' .
```
Replace the example path and symbol. Record:
- which historical decision the change preserves or overturns;
- what old path became obsolete;
- what was actually deleted;
- what remains transitional and why;
- which regression test or architecture check prevents reintroduction;
- which uncertainty still requires production evidence.
Then route validation through `archie-validation-and-qa` and acceptance through
`archie-change-control`. The implementer must not self-certify the adversarial
maintainability review.
## Apply blocking acceptance rules
Return `BLOCK` when any row lacks evidence:
| Blocking proof | Minimum evidence |
| --- | --- |
| Owner | One behavior owner; current and target separated |
| Source of truth | One authoritative implementation/record after cutover |
| Consumers | Production, alternate-process, dynamic, test, and generated paths classified |
| Wiring | Real entry-to-effect chain plus integration/contract evidence |
| Supersession | Every overlap marked retain/adapt/merge/supersede/delete |
| Deletion | Objective criteria for every legacy/compatibility path |
| Configuration | Owner, translation, validation, consumer, reload, and compatibility semantics |
| Boundary | Interface and package location justified |
| Failure semantics | Errors, cancellation, rollback, health, and observability reviewed |
| Readability | Independent reviewer can state the path plainly |
| Reversibility | Source, state, runtime, and compatibility rollback addressed |
| Archaeology | Relevant history and rejected paths recorded |
| Validation | Required evidence from `archie-validation-and-qa` |
Return `ACCEPT` only when all rows are proven and the fresh adversarial reviewer
reports no surviving blocking or important maintainability finding. Return
`CANDIDATE` for an explicitly experimental seam that is not production-wired;
never call it shipped or complete.
## Learn from repository incidents
Treat these as evidence patterns, not legends:
| Incident | Repository evidence | Accountability lesson |
| --- | --- | --- |
| Richer message path exists beside the live path | `internal/gateway/messageevent.go`; `docs/prds/architecture/messaging-and-work-intake.md` states that adapters use `gateway.Message` while richer `MessageEvent` is unused; production-only `rg` finds no concrete live adapter use as of 2026-07-28 | Tests and a rich contract do not establish adoption; inventory callers and delete or cut over the competing contract |
| Feature YAML loader is not the daemon loader | `internal/config/feature_config.go` defines `LoadDir`; its hits are tests, while `cmd/archied/main.go` calls `config.LoadOverlay` as of 2026-07-28 | Parsed and heavily tested configuration can still be unwired |
| Indexing arrived as an isolated feature/settings island | `ddf624d` added indexing; `f934ef5` records undiscoverable settings and silent degradation; as of 2026-07-28 `cmd/archied` uses indexing only in the helper subcommand and does not construct `indexing.Manager` | Prove configuration surface, running composition, and observable failure separately |
| Mirrored MCP server validated the same wrong protocol | Before `dda4cde`, the test helper in `internal/tools/mcp/transport_test.go` called the same `readMessage`/`writeMessage` functions as the client; `dda4cde` replaced LSP-style `Content-Length` with MCP newline-delimited JSON for official-SDK interoperability | A mirrored fake can preserve a shared misconception; require independent contract evidence |
| A green tool registry needed eight adversarial fixes | `9f6c36c` records deadlock, shared-reference mutation, shallow copies, incomplete AST literal parsing, abort-on-first-error, and an over-broad register-call matcher | Test reentrancy, ownership/aliasing, partial failure, and AST false positives—not only happy-path registration |
| Mechanical cleanup broke a focused behavior | `308c199` changed `exec.Command("echo", "wrapped")` to `exec.CommandContext(ctx, "sh", "-c", "echo", "wrapped")`; `wrapped` became shell `$0`, and `TestRunWrapsExternalCommand` returns only `"\n"` as of 2026-07-28. The same commit added 237 tracked `docs-2/node_modules` symlinks | A broad cleanup needs semantic diff review, artifact review, and focused tests; "mechanical" is not a lower evidence class |
| Autofix nearly changed timeout semantics | `9b44bac` records `golangci-lint --fix` changing an assignment to a shadowing declaration in `internal/memory/manager.go`; it was manually restored | Inspect every automated rewrite; compilation is necessary but does not prove preserved semantics |
Re-verify volatile status before reusing any "as of" claim.
## Provenance and maintenance
- Re-verify architecture status: `sed -n '1,180p' docs/prds/architecture/{package-review,organisation,configuration,dependencies-and-contracts,safe-change-and-recovery}.md`
- Re-verify live entry points and config loaders: `rg -n 'func (main|run)\b|config\.(Load|LoadOverlay|LoadDir)\(' cmd internal --glob '*.go'`
- Re-verify message-path consumers: `rg -n '\b(Message|MessageEvent)\b' cmd internal --glob '*.go'`
- Re-verify indexing wiring: `rg -n 'indexing\.|IndexingConfig|cfg\.Indexing' cmd internal --glob '*.go'`
- Re-verify incident commits: `git show -s --format='%H%n%B' 9f6c36c dda4cde f934ef5 9b44bac 308c199`
- Re-verify cleanup regression: `go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1`
- Re-verify repository gates: `sed -n '1,140p' Taskfile.yml && sed -n '90,145p' CLAUDE.md`
- Re-verify this skill structurally with the skill validator available in the active agent environment.
@@ -0,0 +1,4 @@
interface:
display_name: "Archie Technical Accountability"
short_description: "Prove maintainability before accepting changes"
default_prompt: "Use $archie-technical-accountability to audit this Archie change for maintainability, ownership, supersession, production wiring, and dead paths."
@@ -0,0 +1,397 @@
---
name: archie-validation-and-qa
description: "Design, run, interpret, and review defensible validation evidence for archie-core. Use when adding or assessing Go tests, proving a red-then-green change, choosing focused versus repository-wide gates, validating production wiring or protocols, investigating race/cancellation/state-transition behavior, distinguishing sandbox failures from code regressions, or deciding whether an implementation has enough evidence to be accepted."
---
# Archie validation and QA
Prove the behavior, integration, and maintainability claim. A passing unit test
is necessary evidence; it is not proof that production selects the code, a
protocol interoperates, concurrency is safe, or the superseded path is gone.
## Route work before testing
| Need | Load instead or alongside this skill |
|---|---|
| Classify risk, authorize mutation, choose mandatory gates, or accept/close work | `archie-change-control` |
| Find duplicate, dead, misplaced, or unmaintainable code and test whether the change is locally comprehensible | `archie-technical-accountability` |
| Triage an unexplained runtime or test symptom | `archie-debugging-playbook` |
| Decide ownership, boundaries, migration, configuration responsibility, or deletion of competing paths | `archie-architecture-planning-campaign` |
Do **not** use this skill:
- to turn a design dispute into a test implementation;
- to waive a gate because a focused test passes;
- to diagnose an unfamiliar failure without the debugging playbook;
- to certify maintainability without technical-accountability review;
- to run `task check` during a read-only review or in a shared dirty tree: it
rewrites Go files.
## Define the evidence terms
| Term | Meaning here |
|---|---|
| Right-reason red | The intended behavioral assertion fails against compiling code because the capability is absent or wrong. |
| Focused test | One named test or one owning package used for fast iteration. |
| Root suite | `go test ./... -count=1` in the repository root module. |
| Tools suite | `go -C tools test ./... -count=1` in the separate `tools` Go module. |
| Composition test | A test that crosses the real construction or dispatch handoff used by a binary. |
| Independent peer | A protocol implementation, official SDK, executable, or conformance fixture that does not reuse the code under test. |
| Environmental failure | The test cannot acquire a required host resource, such as a listener, writable keyring, executable, or cache. |
| Code regression | The test reached the behavior under test and observed the wrong result. |
| Evidence packet | The exact commands, outputs, tree identity, test design, integration proof, and independent review used for acceptance. |
## Recheck the volatile baseline
Treat this as a dated warning, not a permanent exception.
As of **2026-07-28**:
- A recorded unrestricted run of `go test ./... -count=1` has one code failure:
`internal/skillscript.TestRunWrapsExternalCommand` gets `"\n"` instead of
`"wrapped\n"`.
- The root suite excludes `tools` because `tools/go.mod` starts a nested module.
- No separate integration-test task or build tag exists. Embedded NATS servers,
loopback HTTP/SMTP servers, and Git fixture commits run inside the ordinary
root suite.
- `TestDesktopCommanderClientCompatibility` is the one explicit external
integration opt-in found; it skips unless
`ARCHIE_TEST_DESKTOP_COMMANDER=1`.
- `task check` runs `gofumpt -w .`, `go fix ./...` twice, `go vet ./...`,
the two binary builds, and the root suite. It does **not** run
`golangci-lint`, race tests, the `tools` module, docs generation, or the docs
build.
- The Gitea deploy workflow builds and pushes images, and the GitHub docs
workflow builds VitePress. Neither workflow runs the Go quality gate.
This baseline means the repository-wide suite is not green. Prove local
non-regression if work must continue, but never report the full gate as passing
until the failure is fixed and the unrestricted suite is rerun. Route any
acceptance decision through `archie-change-control`.
## Choose the required evidence surface
Apply every row that matches the change.
| Change surface | Minimum additional evidence |
|---|---|
| One genuinely isolated package | Right-reason red and green; whole-package test; scoped lint; formatting/fix check; prove no cross-package runtime contract changed. |
| Cross-package behavior or shared contract | Root suite; full lint; vet/build; race suite; composition test at each changed handoff. |
| `cmd/archied` or `cmd/archie-agent` wiring | Test from real configuration/construction through selected implementation and observable result; test missing/invalid wiring. |
| Protocol, RPC, MCP, NATS, subprocess, or wire schema | Malformed, partial, multiple, out-of-order, timeout, cancellation, and peer-exit cases; at least one independent-peer or conformance test. |
| Mutable shared state | Deterministic concurrency test plus `-race`; ownership/aliasing test; cancellation and shutdown proof. |
| Store or lifecycle transition | Legal/illegal transition table; stale-`from` contenders; atomic state-and-audit proof; adapter parity where both SQLite and NellDB implement the contract. |
| Configuration | Default, explicit, absent, invalid, compatibility, precedence, secret-reference, and production-passthrough tests. |
| `tools/**` or generated contracts | Tools suite and lint; generator determinism/drift check; root consumer tests; docs build when rendered data changes. |
| Docker/Compose/deployment | Configuration-to-container passthrough, network/volume/health behavior, failure visibility, and last-known-good recovery evidence. |
| External integration | Hermetic tests first; then an explicitly authorized live compatibility run with version, environment, and observed output recorded. |
Do not call a change isolated merely because only one file changed. Trace its
callers and consumers with the architecture campaign or technical-accountability
skill first.
## Execute red then green
### 1. Freeze one behavioral claim
Write:
> Given `<input and state>`, when `<real entry point>` is called, `<owner>`
> produces `<observable result or error>` while preserving `<invariants>`.
Name the failure surface, production consumer, and superseded behavior. If
ownership or the affected paths are unclear, stop and run the architecture
campaign.
### 2. Establish the pre-change baseline
Run the nearest existing tests before adding the repro. Record the current
commit or supplied tree identity, existing dirty paths, command, exit status,
and failures. Do not assign a concurrent or pre-existing failure to the change
without a before/after comparison.
### 3. Write the test first
Make the test compile against the intended public or package contract. Exercise
the behavior, not a private implementation sequence. Then run only the named
test and prove:
- the assertion fails;
- the failure message names the wrong behavior;
- the fixture reached the intended branch;
- the cause is not compilation, a missing executable, a listener denial, GPG,
a timeout chosen too tightly, or stale generated data.
A compile error is not red. A test that panics in setup is not red. Deliberately
corrupting unrelated code to manufacture red is not TDD.
For a behavior-preserving refactor, retain green characterization tests. Add a
structural test only for a stable, load-bearing architecture constraint; do not
invent a brittle implementation assertion merely to manufacture red. Have
`archie-change-control` classify the work before proceeding.
### 4. Implement the smallest coherent change
Make the named test green, then run the owning package. “Smallest” does not mean
leaving a second active implementation or a one-call wrapper with no boundary
purpose. Use `archie-technical-accountability` to inspect deletion,
supersession, dependency direction, and comprehensibility.
### 5. Complete the test matrix
Use table-driven cases. Put identities, repositories, configuration values,
durations, states, and expected results in case fields or fixture builders.
Never couple tests or implementation to live identities such as production bot
names. Use named constants only when the value is itself a contract.
Test every reachable error path. At minimum consider:
- empty, malformed, duplicate, and boundary inputs;
- missing configuration, environment references, credentials, and resources;
- downstream returned errors, partial results, and peer exit;
- timeout before work, cancellation during blocked work, and shutdown;
- partial side effects, retry, idempotency, and recovery;
- unauthorized identity or cross-scope access;
- old configuration, stored data, or wire forms when compatibility is claimed.
Assert the result **and** the consequence: returned error identity/wrapping,
persisted state, emitted event, audit entry, side-effect count, and absence of
silent fallback.
## Test the seams models commonly miss
### Prove production wiring
Trace and test this chain:
```text
real input -> decode/load -> binary composition -> selected owner
-> state or side effect -> observable success/failure
```
A decoder test proves decoding. A constructor test proves construction. A
registry test proves registration. None proves that `cmd/archied` or
`cmd/archie-agent` selects the implementation.
Add one test at the owning behavior and one composition/contract test across
each changed handoff. Include a negative case showing that absent or failed
wiring cannot report success. Structural source-string tests may protect an
especially fragile seam, but they cannot be the only production-wiring proof.
### Test protocols independently
Do not validate a client only against a fake that calls the same framing,
parser, constants, or helpers. That proves self-consistency.
Use, in ranked order:
1. the supported real peer pinned to an explicit version;
2. an official SDK or independent reference implementation;
3. published conformance vectors or captured wire fixtures;
4. a deliberately independent minimal peer that encodes from the written
contract without importing the implementation.
Keep fast in-process fakes for malformed and failure cases. Add boundaries for
split/coalesced frames, multiple buffered messages, unknown fields, peer EOF,
stderr noise, slow response, cancellation, and restart. For MCP, the live
Desktop Commander opt-in is compatibility evidence; a helper server that uses
Archie's own `readMessage`/`writeMessage` is not.
### Test aliasing and ownership
For maps, slices, schemas, options, registries, and configuration projections:
1. mutate the input after construction and prove owned state does not change;
2. mutate the returned value and prove internal state does not change;
3. mutate nested maps/slices, not only the top level;
4. run concurrent readers/writers under `-race` when sharing is permitted.
### Test concurrency and cancellation deterministically
Use barriers, channels, fakes, and explicit clocks to force ordering. Do not use
`time.Sleep` as the sole synchronization proof.
Cover:
- cancellation before work starts;
- cancellation while blocked on I/O, a stream, child process, or queue;
- child and grandchild termination for subprocesses;
- no retry after caller cancellation;
- start/stop and close/send races;
- bounded drain and no goroutine leak;
- same-repository serialization and permitted cross-repository overlap;
- defensive copies around shared mutable state.
Run the race detector after deterministic tests pass. `-race` can reveal a race;
it cannot prove the intended ordering or state machine.
### Test transitions as compare-and-set operations
For every state-changing method, table legal and illegal transitions. Assert
that:
- the supplied `from` state or version is enforced;
- two contenders starting from the same state cannot both succeed;
- the new state and audit/event record are one atomic outcome;
- retries are idempotent or explicitly rejected;
- failure leaves neither partial state nor a false success record;
- every live adapter preserves the same semantics.
Do not accept a test that only shows `queued -> running` succeeds. It misses
lost updates, invalid transitions, and state/audit divergence.
## Run exact gates
Create writable, task-specific caches once:
```bash
mkdir -p /tmp/archie-qa-tmp /tmp/archie-qa-gocache /tmp/archie-qa-lintcache
```
### Iterate on one test and package
Replace the placeholders with real names:
```bash
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go test ./internal/<package>/... -run '^TestName$' -count=1 -v
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go test ./internal/<package>/... -count=1
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache GOLANGCI_LINT_CACHE=/tmp/archie-qa-lintcache golangci-lint run ./internal/<package>/...
```
Use the same command for red and green. Record both outputs.
### Run the root evidence
Run `task check` only in an authorized, isolated tree. It mutates source with
`gofumpt -w .` and `go fix ./...`, and writes binaries under `bin/`. Inspect
the complete before/after diff; never let its broad rewrite hide concurrent
changes.
```bash
git status --short
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache task check
git status --short
gofumpt -l .
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go fix -diff ./...
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache GOLANGCI_LINT_CACHE=/tmp/archie-qa-lintcache golangci-lint run ./...
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go test -race ./... -count=1
```
Expected acceptance output:
- `gofumpt -l .`: no paths;
- `go fix -diff ./...`: no diff and exit zero;
- lint: zero findings;
- tests, vet, and builds: exit zero;
- race suite: exit zero and no race report.
Do not say `task check` covers lint or race. It does not.
### Run the nested tools and documentation evidence
Run this when `tools/**`, published contracts, generated data, or their root
consumers change:
```bash
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go -C tools test ./... -count=1
(cd tools && env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache GOLANGCI_LINT_CACHE=/tmp/archie-qa-lintcache golangci-lint run ./...)
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go -C tools run ./docsgen
git diff --exit-code -- docs-2/data/generated/contracts.json
(cd docs-2 && pnpm install --frozen-lockfile)
(cd docs-2 && pnpm build)
```
The current docsgen command generates data only. Do not use target-only
`docsgen all` or `docsgen check` commands from the architecture PRD until the
live binary implements them.
## Separate environment failures from regressions
| Symptom | Classify first as | Required next action |
|---|---|---|
| `listen tcp ... operation not permitted`, `httptest: failed to listen`, or NATS “Unable to start” | Restricted sandbox lacks loopback/listener access | Rerun the same command in an environment that permits local listeners. Do not weaken or skip the test. |
| Git fixture commit fails with GPG/keybox read-only errors | Inherited host `commit.gpgSign`, inaccessible keyring | Rerun with the temporary Git config override below; do not modify global Git configuration. |
| Go or lint cache reports read-only/permission errors | Environment/cache | Use the writable cache paths above. If the module cache itself is read-only, use a prewarmed writable `GOMODCACHE`; a dependency-download failure is still environmental evidence, not a product result. |
| Desktop Commander test is skipped | Expected default | Run the explicit opt-in only with authorization for `npx` network/download and external process execution. |
| `TestRunWrapsExternalCommand` returns `"\n"` | Known 2026-07-28 code baseline | Treat as a real failure until fixed; do not group it with sandbox denials. |
| Assertion reports wrong state/output after setup completed | Probable code regression | Minimize with the named test, compare pre-change baseline, and use `archie-debugging-playbook`. |
Use this non-persistent signing override for tests that spawn Git commits:
```bash
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=commit.gpgSign GIT_CONFIG_VALUE_0=false go test ./internal/workflow/... -count=1
```
Run the external MCP compatibility check only when explicitly authorized:
```bash
env ARCHIE_TEST_DESKTOP_COMMANDER=1 GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go test ./internal/tools/provider/mcp -run '^TestDesktopCommanderClientCompatibility$' -count=1 -v
```
Record the external package version, network availability, platform, and
whether the failure occurred during download/startup or after MCP exchange.
## Require adversarial review after green
Use a fresh reviewer with no implementation narrative. Give it the request,
diff, governing contract, and raw gate outputs. Do not give it the author's
defense of the design.
Require the reviewer to:
- rerun or inspect all applicable gates;
- read every changed non-test file and its production callers/consumers;
- find dead or duplicate paths and identify what the feature supersedes;
- inspect unchecked errors, nil risks, hardcoded identity/config, and partial
side effects;
- inspect interface satisfaction, ownership, aliasing, cancellation,
goroutine/process leaks, races, and state transitions;
- verify real composition, protocol independence, deployment passthrough, and
negative cases;
- report findings without silently fixing them.
Fix blocking and important findings in a separate implementation pass. Rerun
all affected gates, then have the reviewer verify that **zero surviving
findings** remain. The implementer never self-certifies this pass.
## Enforce acceptance thresholds
Build this evidence packet:
| Evidence | Threshold |
|---|---|
| Scope and tree identity | Exact change claim, affected packages/processes, commit or supplied tree identity, and pre-existing dirty paths recorded. |
| Red | Named test fails for the intended assertion; compile/setup/environment failures: `0`. |
| Green | Named test and owning package pass; unexpected failures: `0`. |
| Error behavior | Every reachable error path in scope has an assertion on error and consequence; unexplained paths: `0`. |
| Wiring | At least one composition/contract test per changed handoff plus a negative wiring case. |
| Protocol | At least one independent-peer/conformance result for changed protocol semantics. |
| Concurrency/state | Deterministic ordering/transition tests pass; race reports: `0`; partial state/audit outcomes: `0`. |
| Formatting/fix/lint | Formatter paths: `0`; fix diff: `0`; lint findings: `0`. |
| Applicable suites | Scoped or root gate, race, tools, docs, and external checks selected by the matrix above; unexplained failures/skips: `0`. |
| Maintainability | Superseded paths have keep/delete/cutover dispositions; unexplained duplicate or dead production paths: `0`. |
| Review | Fresh adversarial reviewer has zero surviving blocking or important findings. |
| Uncertainty | Every unproved claim is labeled `open` or `candidate`; hidden assumptions: `0`. |
Do not average evidence. One surviving race, wiring gap, unexplained skip,
state-transition flaw, or blocking review finding blocks acceptance even when
hundreds of unit tests pass. Route the completed packet through
`archie-change-control`; testing does not itself authorize closure, deployment,
or migration.
## Provenance and maintenance
Grounded on 2026-07-28 in `CLAUDE.md`, `Taskfile.yml`, root and `tools` module
manifests, both workflow directories, the ordinary test suite, the Desktop
Commander opt-in, and the live docsgen command. Recheck volatile facts before
using them:
```bash
sed -n '1,120p' Taskfile.yml
find . -name go.mod -print | sort
rg -n '^//go:build|ARCHIE_TEST_[A-Z0-9_]+' --glob '*_test.go' .
rg -n 'task check|go test|golangci-lint|go vet|pnpm build' .github/workflows .gitea/workflows Taskfile.yml
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go test ./... -count=1
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go -C tools test ./... -count=1
go -C tools run ./docsgen -h
```
@@ -0,0 +1,4 @@
interface:
display_name: "Archie Validation and QA"
short_description: "Build defensible test and quality evidence"
default_prompt: "Use $archie-validation-and-qa to design and run the evidence needed to accept this archie-core change."
+1
View File
@@ -157,3 +157,4 @@
{"id":"int-e2b07b5c81dd19cabd9e2a18ff94f7f7","kind":"field_change","created_at":"2026-07-27T12:20:51.572157777Z","actor":"Sam Catlow","issue_id":"archie-core-sc5","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Implemented gateway.BuildSystemPrompt rendering internal/gateway/templates/archie.md.tpl: instruction precedence, core rules, communication rules, <tools> and <env> blocks, with PersonaRegistry kept as the style layer on top. Tool inventory is derived from the same core.ToolSet passed to the model (cmd/archied/toolSummaries) so prompt and reality cannot drift; empty toolset renders an explicit 'no tools are available'. Tool metadata is markup-escaped and whitespace-flattened against forged tags and forged list entries. task check clean: vet, full go test ./... , golangci-lint 0 issues on changed packages, gofumpt clean. Commit 7fde716. NOT yet deployed - not pushed."}}
{"id":"int-c52b1ab5add5f30c8a63b5f03e5faff7","kind":"field_change","created_at":"2026-07-27T13:47:42.515040687Z","actor":"Sam Catlow","issue_id":"archie-core-4we","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Ported tau internal/indexing/codesearch.go @ 4893818d0c76 into archie-core internal/indexing. Mutations: global config path helpers replaced by explicit indexing.Config + DefaultConfig(workDir) (two archied instances share carina and must not share an index); child-process helper is archied's own 'workspace-codesearch' subcommand in cmd/archied/codesearch.go, dispatched from main() before flag parsing so it touches no config/store/NATS; deferred db.Close explicitly discarded for errcheck. Added dep github.com/google/codesearch v1.3.0-rc.1 (uuid and modernc sqlite already present). Verified E2E against the real repo: 2.2MB indexed in 0.05s, correct hits, [] for no match, corrupt index -> clean error exit 1 rather than process death. task check clean; golangci-lint 0 issues on both packages. Commit c924281. NOT pushed. Follow-up: nothing calls indexing.NewManager yet -- it is ported and proven but not wired into the agent's grep path."}}
{"id":"int-eccef7ef7597bda3a8162e06651e8ea2","kind":"field_change","created_at":"2026-07-28T08:35:54.89529236Z","actor":"Sam Catlow","issue_id":"archie-core-6pp","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Removed all unauthorized source-project references and accompanying rationale; validation and independent review complete."}}
{"id":"int-629331053ed3e16cfc7e4c66ec2dd88b","kind":"field_change","created_at":"2026-07-28T09:32:22.211586558Z","actor":"Sam Catlow","issue_id":"archie-core-5d7.1","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Deterministic contract data JSON slice implemented test-first, validated, documented, and independently reviewed with zero surviving findings."}}
+3 -2
View File
@@ -53,8 +53,8 @@
{"_type":"issue","id":"archie-core-abg.18","title":"[EPIC] Memory: pluggable provider architecture with file-backed persistence","description":"Pluggable memory system to match Hermes parity:\\n\\n1. **MemoryProvider interface**: Abstract interface with methods for initialize(), get_tool_schemas(), prefetch(), sync_turn(), and optional lifecycle hooks (on_session_end, on_session_switch, on_pre_compress, on_memory_write).\\n\\n2. **Built-in file-backed memory**: MEMORY.md and USER.md stored per-session/profile. LLM-callable memory tool with add/replace/remove actions. Frozen snapshot at session start (preserves prefix cache), immediate disk write on updates. Section-sign delimited entries with substring matching.\\n\\n3. **MemoryManager**: Orchestrates built-in + at most one external provider. Background serialized write executor. Prefetch with timeout (8s). Streaming context scrubber that strips injected memory spans from model output.\\n\\nRef: docs/prds/hermes-gap-analysis.md section 4","acceptance_criteria":"An external memory provider (e.g. Honcho, Mem0) can be plugged in via config. The built-in memory tool persists across sessions. Conversation context is recalled on session resume.","status":"open","priority":0,"issue_type":"epic","owner":"sam@catlow.tech","created_at":"2026-07-25T14:02:22Z","created_by":"Sam Catlow","updated_at":"2026-07-25T14:02:22Z","dependencies":[{"issue_id":"archie-core-abg.18","depends_on_id":"archie-core-abg","type":"parent-child","created_at":"2026-07-26T00:02:22Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-abg.16","title":"[EPIC] Gateway: rich message model, adapter lifecycle, session management","description":"Foundational gateway infrastructure to match Hermes parity. Three interdependent pieces:\\n\\n1. **Message model**: Replace the 3-field Message struct with a rich MessageEvent (MessageType enum: text/photo/video/audio/voice/document/sticker/command, media_urls, reply_to context, metadata dict, source). This is the wire type every adapter produces.\\n\\n2. **Adapter lifecycle**: Replace the 3-method Gateway interface with a BasePlatformAdapter interface: connect()/disconnect()/send() as required methods, plus optional overrides for typing indicators, edit/delete, image/voice/video/document send, interactive UX (clarify buttons, approval dialogs). Capability flags (supports_code_blocks, splits_long_messages, supports_async_delivery).\\n\\n3. **Session management**: SessionSource struct (platform, chat_id, chat_type, user_id, thread_id, guild_id, profile), AsyncSessionStore for persistent session storage, SessionContext for system prompt injection.\\n\\nAll three blocks together enable adding new platforms as plugins without touching core gateway code.\\n\\nRef: docs/prds/hermes-gap-analysis.md sections 1-2","acceptance_criteria":"New adapters can be added by implementing a Go interface with connect/disconnect/send + optional media methods. Messages carry full metadata through the pipeline. Sessions persist across gateway restarts.","status":"open","priority":0,"issue_type":"epic","owner":"sam@catlow.tech","created_at":"2026-07-25T14:02:21Z","created_by":"Sam Catlow","updated_at":"2026-07-25T14:02:21Z","dependencies":[{"issue_id":"archie-core-abg.16","depends_on_id":"archie-core-abg","type":"parent-child","created_at":"2026-07-26T00:02:21Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-jfg","title":"Spawned archie-agent containers not on daemon's docker network — can't reach NATS","description":"Root cause of 'agent still failing on the server': archied's container.Pool.Acquire creates archie-agent containers via the Docker SDK with no NetworkMode set, so Docker attaches them to the default bridge network. archied and nats run on the compose-created 'archie-core_default' network instead, so the spawned container's hostname resolution for 'nats' (from NATS_URL=nats://nats:4222) fails and archie-agent can't connect. Confirmed on carina host logs: archied logs show repeating 'taskrun request failed err=\"nats: no responders available for request\"' for every task, containers created and destroyed within ~1.5s (consistent with archie-agent's NATS client failing fast). Fixed by detecting the daemon's own container's network in NewPool (selfNetwork, via ContainerInspect on os.Hostname()) and setting HostConfig.NetworkMode on spawned containers to match.","status":"closed","priority":0,"issue_type":"bug","owner":"sam@catlow.tech","created_at":"2026-07-24T03:10:26Z","created_by":"Sam Catlow","updated_at":"2026-07-25T13:04:34Z","closed_at":"2026-07-25T13:04:34Z","close_reason":"Fix already implemented and verified: selfNetwork() in internal/container/pool.go detects the daemon's own container network via ContainerInspect(os.Hostname()) and Acquire() sets HostConfig.NetworkMode to match, so spawned archie-agent containers join the same compose network as nats. Build and internal/container tests pass.","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-6pp","title":"Remove source-project references from Archie","description":"Remove every tau reference outside the explicitly preserved Beads data and docs-2/README.md. Delete copied product-specific documentation and accompanied rationale rather than mechanically renaming it. Retain reusable documentation-generation and VitePress scaffolding only after removing source-specific coupling. Update code, tests, archives, and architecture documents so archie-core contains no unauthorized tau references.","acceptance_criteria":"rg 'tau' -ow excluding .beads/** and docs-2/README.md returns zero; retained tools and documentation scaffolding contain no source-project imports, paths, product claims, or rationale; relevant validation passes.","notes":"Complete. Exact case-insensitive whole-word scan excluding .git/**, .beads/**, and docs-2/README.md returns 0. Source-specific provenance and rationale removed, neutral fixtures preserve behavior, docs workflow/site build from docs-2, retained README excluded from publication, and Archie-owned docsgen generates current agent contracts without process-global cwd mutation. tools tests/vet pass; affected package tests pass; VitePress production build passes. Fresh adversarial review reports zero surviving findings. Full task check passes fmt/go-fix/vet/build and all packages except unrelated pre-existing internal/skillscript TestRunWrapsExternalCommand (Run returned newline).","status":"in_progress","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T08:00:32Z","created_by":"Sam Catlow","updated_at":"2026-07-28T08:35:54Z","started_at":"2026-07-28T08:00:37Z","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-5d7","title":"Define target project organisation and restructuring rules","description":"Run a package-by-package architecture grilling session, establish the target DDD and semi-microservice organisation, record strict restructuring requirements and package destinations, and produce docs/prds/01-project-management.md as the durable handoff.","acceptance_criteria":"The PRD records agreed project-wide organisation rules, bounded-context and service/plugin boundaries, dependency constraints, migration principles, and the destination of each reviewed package. Decisions are confirmed one at a time with the user before the document is finalized.","notes":"Corrected documentation-generation wording: removed repeated source-project provenance from the target architecture. The copied generator/site are now described only as an implementation baseline with concrete adaptation gaps; the architecture is expressed entirely in Archie terms. Updated generated-documentation.md and its migration-decisions.md reference.","status":"in_progress","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T00:00:36Z","created_by":"Sam Catlow","updated_at":"2026-07-28T07:27:47Z","started_at":"2026-07-28T00:00:42Z","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-6pp","title":"Remove source-project references from Archie","description":"Remove every tau reference outside the explicitly preserved Beads data and docs-2/README.md. Delete copied product-specific documentation and accompanied rationale rather than mechanically renaming it. Retain reusable documentation-generation and VitePress scaffolding only after removing source-specific coupling. Update code, tests, archives, and architecture documents so archie-core contains no unauthorized tau references.","acceptance_criteria":"rg 'tau' -ow excluding .beads/** and docs-2/README.md returns zero; retained tools and documentation scaffolding contain no source-project imports, paths, product claims, or rationale; relevant validation passes.","notes":"Complete. Exact case-insensitive whole-word scan excluding .git/**, .beads/**, and docs-2/README.md returns 0. Source-specific provenance and rationale removed, neutral fixtures preserve behavior, docs workflow/site build from docs-2, retained README excluded from publication, and Archie-owned docsgen generates current agent contracts without process-global cwd mutation. tools tests/vet pass; affected package tests pass; VitePress production build passes. Fresh adversarial review reports zero surviving findings. Full task check passes fmt/go-fix/vet/build and all packages except unrelated pre-existing internal/skillscript TestRunWrapsExternalCommand (Run returned newline).","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T08:00:32Z","created_by":"Sam Catlow","updated_at":"2026-07-28T08:35:55Z","started_at":"2026-07-28T08:00:37Z","closed_at":"2026-07-28T08:35:55Z","close_reason":"Removed all unauthorized source-project references and accompanying rationale; validation and independent review complete.","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-5d7","title":"Define target project organisation and restructuring rules","description":"Run a package-by-package architecture grilling session, establish the target DDD and semi-microservice organisation, record strict restructuring requirements and package destinations, and produce docs/prds/01-project-management.md as the durable handoff.","acceptance_criteria":"The PRD records agreed project-wide organisation rules, bounded-context and service/plugin boundaries, dependency constraints, migration principles, and the destination of each reviewed package. Decisions are confirmed one at a time with the user before the document is finalized.","notes":"Corrected generated-documentation.md to the agreed architecture: production code/registries/config/CLI are authoritative; docsgen emits deterministic JSON data and protocol schemas only; typed VitePress data loaders/components/templates own page rendering; generated Markdown is prohibited. First implementation slice tracked and completed as archie-core-5d7.1.","status":"in_progress","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T00:00:36Z","created_by":"Sam Catlow","updated_at":"2026-07-28T09:32:22Z","started_at":"2026-07-28T00:00:42Z","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-qa4.4","title":"Phase 4: structural refactor (~28 issues)","description":"funlen, gocognit, cyclop, nestif, maintidx, interfacebloat. This IS the internal/config restructure already discussed (finalize at cognitive complexity 106, feature_config loadDirInto at 74) plus daemon process/checkWaiting. MUST BE LAST: refactoring moves line numbers and invalidates every other phase in flight. Fold into the config file-per-responsibility split rather than doing the same work twice.","status":"open","priority":1,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-07-27T15:23:01Z","created_by":"Sam Catlow","updated_at":"2026-07-27T15:23:01Z","dependencies":[{"issue_id":"archie-core-qa4.4","depends_on_id":"archie-core-qa4","type":"parent-child","created_at":"2026-07-28T01:23:00Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-qa4.3","title":"Phase 3: correctness findings needing judgement (~62 issues)","description":"nilerr (11: 6 in internal/agentexec inprocess.go/worker.go, 2 gateway), bodyclose (1), contextcheck (7), containedctx (2), fatcontext. SINGLE SESSION, sequential, no subagents: each nilerr site needs a read of whether the swallow is deliberate degradation or a real bug, and a context-free worker will silently convert deliberate behaviour into a change. Do nilerr FIRST -- highest bug probability in the whole set. BLOCKED on a policy decision for noctx (41 sites, mostly webui/worktree/store): fixing it means threading context through public APIs, which is an API change, not a lint fix.","status":"open","priority":1,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-07-27T15:23:00Z","created_by":"Sam Catlow","updated_at":"2026-07-27T15:23:00Z","dependencies":[{"issue_id":"archie-core-qa4.3","depends_on_id":"archie-core-qa4","type":"parent-child","created_at":"2026-07-28T01:23:00Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-qa4.1","title":"Phase 1: autofix pass (~35 issues)","description":"golangci-lint run --fix plus the formatters. Covers errorlint, fatcontext, gocritic, sloglint, usestdlibvars, usetesting, gci, gofumpt, goimports. Zero judgement. MUST run first: it touches formatting across every file and would conflict with anything in flight. Single command, single commit, verify with task check.","status":"open","priority":1,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-07-27T15:22:59Z","created_by":"Sam Catlow","updated_at":"2026-07-27T15:22:59Z","dependencies":[{"issue_id":"archie-core-qa4.1","depends_on_id":"archie-core-qa4","type":"parent-child","created_at":"2026-07-28T01:22:58Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
@@ -145,6 +145,7 @@
{"_type":"issue","id":"archie-core-s1r","title":"Test forge fakes missing LinkBranch method broke go vet/test for whole module","description":"forge.Forge gained LinkBranch(ctx, owner, repo, issueNumber, branch) error in the branch-linking feature (ff4c51e) but the hand-rolled test doubles (stubForge in cmd/archied/main_test.go, prCapturingForge in cmd/archie-agent/taskrun_test.go, testForge in internal/daemon/daemon_test.go, fakeForge in internal/forgerpc/forgerpc_test.go) never got the method added, so they stopped satisfying forge.Forge. This broke go vet ./... and go test ./... for the entire module, not just those 4 packages, since go vet type-checks all test files as part of module vet. Fixed by adding LinkBranch stubs to all four fakes.","status":"closed","priority":1,"issue_type":"bug","owner":"sam@catlow.tech","created_at":"2026-07-24T03:04:53Z","created_by":"Sam Catlow","updated_at":"2026-07-24T03:04:58Z","closed_at":"2026-07-24T03:04:58Z","close_reason":"Added LinkBranch stub methods to stubForge, prCapturingForge, testForge, and fakeForge. go build/vet/test ./... now clean across the whole module.","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-633","title":"config.docker.toml missing required fields, no overlay merge implemented","description":"config.docker.toml was rewritten to be a docs-as-overlay file (comment says base+overlay merge) but internal/config.Load has no merge logic and docker-compose.yml mounts only config.docker.toml at /etc/archie/config.toml. It is missing bot_user, [forge], [dispatch], [models], [providers], [budgets] which Load requires -\u003e daemon fails to start in docker as currently configured. Implement real base+overlay config loading (or restore a full standalone docker config) so there is one source of truth.","status":"closed","priority":1,"issue_type":"bug","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-24T02:42:07Z","created_by":"Sam Catlow","updated_at":"2026-07-24T02:44:53Z","started_at":"2026-07-24T02:42:11Z","closed_at":"2026-07-24T02:44:53Z","close_reason":"Implemented config.LoadOverlay (base decode + overlay decode into same struct, then shared finalize/validate), wired -config-overlay flag in cmd/archied, fixed docker-compose.yml to mount both base config.toml and config.docker.toml overlay, minimized config.docker.toml to true diff-only overlay, added tests proving overlay-omitted required fields (bot_user, repos) still come from base.","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-u64","title":"Daemon: process multiple tasks concurrently (max_concurrency enforcement)","description":"Daemon currently processes one task at a time (docs/prds/archie-core-v2-architecture.md Phase 2). This is the core blocker between current state and any multi-agent scaling mode — needed before container max_concurrency or same-repo concurrency can matter. Wire the daemon's dispatch loop to run N tasks in parallel, respecting a configurable max_concurrency.","design":"internal/container/pool.go already enforces max_concurrency for container lifecycle — reuse that limit/pattern in the daemon's task dispatch rather than inventing a second concurrency control.","acceptance_criteria":"Daemon dispatch loop runs multiple tasks concurrently up to a configured max_concurrency limit; single-task-at-a-time behavior is gone.","status":"closed","priority":1,"issue_type":"feature","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-23T19:36:31Z","created_by":"Sam Catlow","updated_at":"2026-07-23T21:37:42Z","started_at":"2026-07-23T21:29:41Z","closed_at":"2026-07-23T21:37:42Z","close_reason":"Implemented concurrent SQLite and NATS task dispatch using containers.max_concurrency, with default same-repo serialization and race-tested dispatcher coverage.","dependency_count":0,"dependent_count":2,"comment_count":0}
{"_type":"issue","id":"archie-core-5d7.1","title":"Docsgen: emit deterministic contract data JSON","description":"Begin the generated-documentation implementation with the smallest vertical slice: normalize the existing Archie contract schemas into deterministic JSON under docs-2/data/generated for VitePress consumption, without generating Markdown pages. Preserve the nested tools module and existing source-of-truth imports.","acceptance_criteria":"A failing test first proves docsgen emits valid generated JSON at the data path; repeated generation is byte-identical; tools tests and vet pass; generated-documentation.md reflects the agreed data-loader architecture.","notes":"Implemented the first docs generation slice test-first: docsgen now emits deterministic JSON contract data at docs-2/data/generated/contracts.json, carries generator provenance, rejects duplicate published names and conflicting definitions, validates resolved internal references in tests, and keeps the current hardcoded contract set as an explicit migration adapter with deletion criteria. Scoped tools tests, vet, and golangci-lint pass; repeated generation is byte-identical; adversarial review reports zero surviving findings.","status":"closed","priority":2,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T09:17:08Z","created_by":"Sam Catlow","updated_at":"2026-07-28T09:32:22Z","started_at":"2026-07-28T09:17:13Z","closed_at":"2026-07-28T09:32:22Z","close_reason":"Deterministic contract data JSON slice implemented test-first, validated, documented, and independently reviewed with zero surviving findings.","dependencies":[{"issue_id":"archie-core-5d7.1","depends_on_id":"archie-core-5d7","type":"parent-child","created_at":"2026-07-28T19:17:08Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-qfx","title":"Flaky: TestRunTaskExecutesBootstrapWorkflowEndToEnd races on NATS responders","description":"cmd/archie-agent. Intermittently fails with ParkReason 'stage prepare: archie.worktree.prepare: nats: no responders available for request'; passes on re-run (-count=3 clean). The test does not wait for the worktreerpc subscription to be established before dispatching. A flaky test in task check is poison: it trains everyone to re-run instead of read, which is how a real regression gets waved through.","status":"open","priority":2,"issue_type":"bug","owner":"sam@catlow.tech","created_at":"2026-07-27T15:27:55Z","created_by":"Sam Catlow","updated_at":"2026-07-27T15:27:55Z","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-5dn","title":"Document Hermes capabilities missing from Archie","description":"Investigate Hermes' available features and commands, compare them with Archie, and publish a simple Markdown TODO checklist excluding Kanban.","status":"closed","priority":2,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-27T12:09:56Z","created_by":"Sam Catlow","updated_at":"2026-07-27T12:11:14Z","started_at":"2026-07-27T12:10:00Z","closed_at":"2026-07-27T12:11:14Z","close_reason":"Investigated local Hermes CLI and current Archie implementation; added the requested parity TODO checklist.","dependency_count":0,"dependent_count":0,"comment_count":0}
{"_type":"issue","id":"archie-core-alm.3","title":"Telegram: multi-home-channel command","description":"When multiple home channels are introduced, design /sethome with /set_home alias to set a chat as a home channel. Define identity ownership, overwrite/confirmation rules, group authorization, persistence, and relationship to sessions before implementation.","acceptance_criteria":"Blocked on the multiple-home-channel model; once unblocked, both aliases have identical safe behaviour, persist correctly, and are covered by authorization and migration tests.","status":"open","priority":2,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-07-27T08:56:50Z","created_by":"Sam Catlow","updated_at":"2026-07-27T08:56:50Z","dependencies":[{"issue_id":"archie-core-alm.3","depends_on_id":"archie-core-alm","type":"parent-child","created_at":"2026-07-27T18:56:49Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
+400
View File
@@ -0,0 +1,400 @@
{
"generatedBy": "tools/docsgen",
"schemas": {
"AgentExecutionRequest": {
"additionalProperties": false,
"description": "Request is the complete, serializable input for one agent stage.",
"properties": {
"attempt": {
"type": "integer"
},
"budget": {
"$ref": "#/schemas/Budget"
},
"capture_tools": {
"items": {
"$ref": "#/schemas/CaptureTool"
},
"type": "array"
},
"extra_rules": {
"type": "string"
},
"gate": {
"$ref": "#/schemas/Gate"
},
"mission": {
"type": "string"
},
"model": {
"type": "string"
},
"notes": {
"type": "string"
},
"plugins": {
"description": "Plugins are bundled Yaegi plugins from the skill's plugins/\ndirectory. Each entry carries the name and source so the agent\ncan register them as tools. PRD section 5 Layer 1.",
"items": {
"$ref": "#/schemas/PluginSpec"
},
"type": "array"
},
"preflight": {
"items": {
"$ref": "#/schemas/Command"
},
"type": "array"
},
"protection": {
"$ref": "#/schemas/Protection"
},
"read_only": {
"type": "boolean"
},
"stage": {
"type": "string"
},
"task_id": {
"type": "integer"
},
"version": {
"type": "integer"
},
"workflow": {
"type": "string"
}
},
"required": [
"version",
"task_id",
"attempt",
"stage",
"model",
"mission",
"budget",
"gate",
"protection"
],
"type": "object"
},
"AgentExecutionResult": {
"additionalProperties": false,
"description": "Result is the serializable outcome of one agent stage.",
"properties": {
"appended_notes": {
"items": {
"type": "string"
},
"type": "array"
},
"attempt": {
"type": "integer"
},
"captures": {
"additionalProperties": {
"items": true,
"type": "array"
},
"type": "object"
},
"changes": {
"items": {
"type": "string"
},
"type": "array"
},
"detail": {
"type": "string"
},
"iterations": {
"type": "integer"
},
"stage": {
"type": "string"
},
"status": {
"type": "string"
},
"stop_reason": {
"type": "string"
},
"summary": {
"type": "string"
},
"task_id": {
"type": "integer"
},
"tokens_used": {
"type": "integer"
},
"version": {
"type": "integer"
}
},
"required": [
"version",
"task_id",
"attempt",
"stage",
"status"
],
"type": "object"
},
"Budget": {
"additionalProperties": false,
"description": "Budget bounds one autonomous execution.",
"properties": {
"max_steps": {
"type": "integer"
},
"max_tokens": {
"type": "integer"
},
"wall_clock": {
"type": "integer"
}
},
"type": "object"
},
"CaptureTool": {
"additionalProperties": false,
"description": "CaptureTool declares a structured-output tool whose calls are returned to the daemon as data.",
"properties": {
"boolean_fields": {
"items": {
"type": "string"
},
"type": "array"
},
"description": {
"type": "string"
},
"max_calls": {
"type": "integer"
},
"name": {
"type": "string"
},
"non_empty_strings": {
"items": {
"type": "string"
},
"type": "array"
},
"parameters": true,
"required_fields": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"name"
],
"type": "object"
},
"Command": {
"additionalProperties": false,
"description": "Command is one executable gate or preflight command.",
"properties": {
"argv": {
"items": {
"type": "string"
},
"type": "array"
},
"expect_failure": {
"type": "boolean"
},
"name": {
"type": "string"
}
},
"required": [
"name",
"argv"
],
"type": "object"
},
"Gate": {
"additionalProperties": false,
"description": "Gate is the quality gate an agent must satisfy.",
"properties": {
"commands": {
"items": {
"$ref": "#/schemas/Command"
},
"type": "array"
},
"max_consecutive_failures": {
"type": "integer"
}
},
"type": "object"
},
"MediaAttachment": {
"additionalProperties": false,
"description": "MediaAttachment describes a file attached to a message.",
"properties": {
"duration": {
"description": "Duration is the play time in seconds for audio and video.",
"type": "integer"
},
"file_id": {
"description": "FileID is the platform-assigned identifier for download APIs.",
"type": "string"
},
"file_name": {
"description": "FileName is the original file name when known.",
"type": "string"
},
"file_size": {
"description": "FileSize is the attachment size in bytes. nil means unknown.",
"type": "integer"
},
"height": {
"description": "Height is the pixel height for images and video.",
"type": "integer"
},
"mime_type": {
"description": "MIMEType is the content type (e.g. \"image/png\", \"audio/ogg\").",
"type": "string"
},
"type": {
"description": "Type is \"image\", \"video\", \"audio\", or \"document\".",
"type": "string"
},
"url": {
"description": "URL is a direct download URL when available. May be empty for\nplatforms that require a download API call.",
"type": "string"
},
"width": {
"description": "Width is the pixel width for images and video. nil means unknown\nor not applicable.",
"type": "integer"
}
},
"required": [
"type",
"file_id"
],
"type": "object"
},
"MessageEvent": {
"additionalProperties": false,
"description": "MessageEvent is the rich message model for all gateway channels.",
"properties": {
"callback_data": {
"description": "CallbackData is the payload from a button or inline-keyboard\npress (Type == MsgCallback).",
"type": "string"
},
"channel_id": {
"description": "ChannelID identifies the conversation within the platform\n(chat ID, channel name, DM thread).",
"type": "string"
},
"edited_from": {
"description": "EditedFrom is the original text before the edit. Set only when\nType is MsgEdited.",
"type": "string"
},
"id": {
"description": "ID is the platform-assigned message identifier. Used for reply\nthreading, reactions, and edit/delete tracking.",
"type": "string"
},
"media": {
"description": "Media holds attached files. Nil for text-only messages.",
"items": {
"$ref": "#/schemas/MediaAttachment"
},
"type": "array"
},
"platform": {
"description": "Platform names the source adapter (\"telegram\", \"discord\",\n\"web\", \"slack\").",
"type": "string"
},
"raw": {
"description": "Raw is the original platform-specific payload. Adapters set\nthis for debug logging or handlers that need platform details\nnot captured by the generic fields.",
"type": "object"
},
"reacted_to_id": {
"description": "ReactedToID is the message being reacted to.",
"type": "string"
},
"reaction": {
"description": "Reaction is the emoji used when Type is MsgReaction.",
"type": "string"
},
"reply_to_id": {
"description": "ReplyToID is the platform message ID this message is in reply\nto. Empty for top-level messages.",
"type": "string"
},
"sender_id": {
"description": "SenderID is the platform-specific sender identifier.",
"type": "string"
},
"sender_name": {
"description": "SenderName is the display name when available.",
"type": "string"
},
"text": {
"description": "Text is the human-readable message body. It carries the caption\nfor media messages and the full content for text and system\nmessages.",
"type": "string"
},
"thread_id": {
"description": "ThreadID identifies the conversation thread for platforms that\nsupport threading (Slack, Discord forums).",
"type": "string"
},
"timestamp": {
"description": "Timestamp is the platform-assigned message time in Unix\nmilliseconds. Zero when unknown.",
"type": "integer"
},
"type": {
"description": "Type discriminates the message kind.",
"type": "string"
}
},
"required": [
"type",
"channel_id",
"platform",
"sender_id"
],
"type": "object"
},
"PluginSpec": {
"additionalProperties": false,
"description": "PluginSpec is a bundled Yaegi plugin passed from daemon to agent.",
"properties": {
"name": {
"type": "string"
},
"src": {
"type": "string"
}
},
"required": [
"name",
"src"
],
"type": "object"
},
"Protection": {
"additionalProperties": false,
"description": "Protection describes paths the agent may read but not mutate.",
"properties": {
"globs": {
"items": {
"type": "string"
},
"type": "array"
},
"suffixes": {
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
}
}
@@ -8,9 +8,12 @@
Archie's documentation-generation approach is:
- Go code and registries remain the source of truth for published contracts;
- a repository-local Go generator produces schemas and reference pages;
- VitePress renders handwritten and generated Markdown;
- production Go code, registries, configuration, and CLI behaviour remain the
source of truth for published contracts;
- a repository-local Go generator extracts and normalizes documentation data;
- the generator writes deterministic JSON/data files and protocol schemas;
- VitePress data loaders, components, and templates render the generated data
into reference pages;
- GitHub Actions builds and publishes the static site.
Hugo is not part of the target architecture.
@@ -90,8 +93,9 @@ authoritative tables.
## Target generation architecture
`tools/docsgen` is Archie's documentation generator. It produces protocol
specifications and Markdown reference pages.
`tools/docsgen` is Archie's documentation extractor and normalizer. It produces
structured documentation data and protocol specifications. It does not own
page layout and MUST NOT generate Markdown pages or fragments.
The generator is divided internally into reusable stages:
@@ -99,7 +103,7 @@ The generator is divided internally into reusable stages:
load registries and types
-> normalize documentation model
-> validate ownership and identifiers
-> render target artifacts
-> serialize data and protocol artifacts
-> compare or write output
```
@@ -111,14 +115,14 @@ defaults, validation, secret classifications, and relationships.
Initial generator targets:
```text
docsgen data
docsgen asyncapi
docsgen pages
docsgen all
docsgen check
```
- `data` writes the normalized JSON consumed by VitePress.
- `asyncapi` writes protocol schemas and envelopes.
- `pages` writes generated Markdown reference and its manifest.
- `all` generates every committed artifact.
- `check` generates into a temporary directory and fails on drift.
@@ -132,37 +136,48 @@ a visibly owned subtree:
```text
docs-2/
asyncapi/
header.yaml
archie.yaml
reference/
data/
generated/
_index.md
cli/
configuration/
messaging/
agents/
workflows/
policies/
plugins/
tools/
manifest.json
catalog.json
contracts.json
cli.json
configuration.json
messaging.json
agents.json
workflows.json
policies.json
plugins.json
tools.json
public/
schemas/
asyncapi-header.yaml
archie.yaml
.vitepress/
config.mts
generated-sidebar.mts
data/
reference.data.ts
theme/
components/
.tmp/
```
All files under `reference/generated/` carry a generated marker and MUST NOT be
edited manually.
All files under `data/generated/` and `public/schemas/` carry generated
ownership metadata where their format permits it and MUST NOT be edited
manually. `.tmp/` is generator-owned, ignored, and never committed.
`manifest.json` is the deterministic machine-readable index used for:
`catalog.json` is the deterministic machine-readable index used for:
- generated sidebar and navigation entries;
- reference navigation and route inputs;
- duplicate-ID and duplicate-route validation;
- coverage checks;
- source-to-page drift diagnostics;
- source-to-data drift diagnostics;
- future external consumers.
VitePress loads these files at build time through a typed `.data.ts` loader.
Pages and components import the loader's `data` export and render reference
views. Archie uses a custom loader because the authoritative inputs are JSON;
VitePress `createContentLoader` is reserved for Markdown content collections.
The final move from `docs-2/` to `docs/` occurs only after Archie content
contains intentional Archie pages and the current architecture documents have an
intentional destination. The staging name MUST NOT leak into public URLs.
@@ -181,10 +196,12 @@ require github.com/samcharles93/archie-core v0.0.0-00010101000000-000000000000
replace github.com/samcharles93/archie-core => ../
```
Keep generator-only dependencies such as `invopop/jsonschema` and YAML in the
nested tools module. They MUST NOT enter the root module.
Keep generator-only dependencies such as `invopop/jsonschema` and any future
protocol-schema serializer in the nested tools module. They MUST NOT enter the
root module.
`docsgen` imports Archie-owned contracts and writes Archie reference artifacts.
`docsgen` imports Archie-owned contracts and writes normalized Archie data and
protocol artifacts.
### Step 2: establish authoritative registries
@@ -208,6 +225,10 @@ Where the migration has not yet created a final domain registry, the generator
may use a narrow compatibility adapter over the current registry. That adapter
has explicit deletion criteria.
The initial agent-execution and messaging schema set is such an adapter. It is
deleted when those domains expose their production-owned documentation
registries; adding another hardcoded type list to `docsgen` is prohibited.
### Step 3: generate AsyncAPI
Use Archie's messaging and worker wire registries as the authoritative inputs.
@@ -232,15 +253,16 @@ The generator owns:
The generated protocol artifact becomes:
```text
docs-2/asyncapi/archie.yaml
docs-2/public/schemas/archie.yaml
```
The final owner of each wire registry is the domain or capability defining its
meaning. `docsgen` renders the contract; it does not own the message semantics.
### Step 4: add Markdown page generation
### Step 4: add generated documentation data
Add renderers for the missing reference categories one vertical slice at a time.
Add extractors for the missing reference categories one vertical slice at a
time.
Recommended implementation order:
@@ -253,29 +275,27 @@ Recommended implementation order:
7. tools and capability contracts;
8. worker and external wire contracts.
Each category renderer produces:
Each category extractor contributes:
- a section index;
- one stable page per published definition where useful;
- field/type/default/validation tables;
- source links;
- stable IDs, owners, routes, and display ordering;
- fields, types, defaults, and validation metadata;
- source references;
- version and deprecation information;
- cross-links to related commands, events, policies, and contracts.
- relationships to commands, events, policies, and contracts.
The first vertical slice proves the normalized model and templates. Later
categories reuse them rather than introducing category-specific ad hoc
generation.
The first vertical slice proves the normalized model and deterministic JSON
serialization. Later categories reuse it rather than introducing
category-specific ad hoc output formats.
### Step 5: generate VitePress navigation
### Step 5: render data with VitePress
Generate navigation data from `manifest.json`, not by manually duplicating every
generated page in `.vitepress/config.mts`.
Create typed data loaders, components, and page templates for the normalized
data. The loaders watch `data/generated/*.json`, parse and validate the files,
and return serializable data at build time.
Handwritten top-level navigation remains explicit. Generated reference sections
are imported from `.vitepress/generated-sidebar.mts`.
The generated navigation file is deterministic and committed with the reference
pages.
Handwritten top-level navigation remains explicit. Reference navigation and
routes derive from `catalog.json`; they are not emitted as generated TypeScript
or duplicated manually in `.vitepress/config.mts`.
### Step 6: implement deterministic drift checking
@@ -283,7 +303,7 @@ pages.
1. generates all artifacts into a temporary directory;
2. normalizes line endings and file modes;
3. compares the complete expected tree with committed outputs;
3. compares the complete expected data and schema trees with committed outputs;
4. reports missing, changed, and obsolete files;
5. identifies the authoritative definition associated with each mismatch;
6. exits non-zero without modifying the working tree.
@@ -415,7 +435,7 @@ CI:
1. runs `task docs:check` without modifying committed output;
2. builds the static site;
3. publishes only from the approved branch or release;
4. never treats generated reference as handwritten source.
4. never treats generated data as handwritten source.
A commit MUST NOT be created while generated documentation is stale.
@@ -439,7 +459,7 @@ Site validation covers:
- frozen dependency installation;
- VitePress production build;
- dead internal links;
- generated navigation imports;
- generated-data loader imports;
- expected output routes;
- absence of unrelated product names and URLs;
- absence of committed build artifacts.
@@ -453,8 +473,9 @@ The documentation migration is complete when:
- `tools` belongs to Archie and builds against the working tree;
- `docsgen` consumes Archie-owned registries and types;
- AsyncAPI output describes Archie;
- required reference categories are generated as committed Markdown;
- generated navigation and manifest match generated pages;
- required reference categories are generated as committed deterministic data;
- `catalog.json` matches the generated definitions and rendered routes;
- VitePress components and templates render the generated data;
- two consecutive generations are byte-identical;
- `docsgen check` detects changed, missing, and obsolete artifacts;
- VitePress contains only intentional Archie content;
File renamed without changes.
+4 -5
View File
@@ -185,9 +185,10 @@ type Agent struct {
// Forge configures the code forge integration.
type Forge struct {
Type string `toml:"type" yaml:"type"`
Host string `toml:"host" yaml:"host"`
Token secret.SecretRef `toml:"token" yaml:"token"`
Type string `toml:"type" yaml:"type"`
Host string `toml:"host" yaml:"host"`
Token secret.SecretRef `toml:"token" yaml:"token"`
TokenEnv string `toml:"token_env" yaml:"token_env"`
}
// Dispatch configures how archied discovers work and reflects task state
@@ -578,8 +579,6 @@ func finalize(cfg Config) (Config, error) {
if cfg.Forge.Token.Engine == "" && cfg.Forge.Token.Key == "" {
if cfg.Forge.TokenEnv != "" {
cfg.Forge.Token = secret.SecretRef{Engine: "env", Key: cfg.Forge.TokenEnv}
} else {
cfg.Forge.Token = secret.SecretRef{Engine: "env", Key: "ARCHIE_GITHUB_TOKEN"}
}
}
if cfg.Agent.Mode == "" {
+32 -14
View File
@@ -13,16 +13,16 @@ import (
"strings"
"github.com/invopop/jsonschema"
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/gateway"
"gopkg.in/yaml.v3"
)
func main() {
repoRoot := flag.String("repo-root", "..", "path to the Archie repository root")
out := flag.String(
"out",
"docs-2/reference/generated/agent-contracts.yaml",
"docs-2/data/generated/contracts.json",
"output path relative to the repository root",
)
flag.Parse()
@@ -47,11 +47,7 @@ func run(repoRoot, outPath string) error {
}
schemas := map[string]any{}
types := map[string]reflect.Type{
"AgentExecutionRequest": reflect.TypeFor[agentexec.Request](),
"AgentExecutionResult": reflect.TypeFor[agentexec.Result](),
"MessageEvent": reflect.TypeFor[gateway.MessageEvent](),
}
types := currentContractTypes()
names := make([]string, 0, len(types))
for name := range types {
names = append(names, name)
@@ -64,10 +60,17 @@ func run(repoRoot, outPath string) error {
}
rewriteDefRefs(schemas)
body, err := yaml.Marshal(map[string]any{"schemas": schemas})
body, err := json.MarshalIndent(struct {
GeneratedBy string `json:"generatedBy"`
Schemas map[string]any `json:"schemas"`
}{
GeneratedBy: "tools/docsgen",
Schemas: schemas,
}, "", " ")
if err != nil {
return fmt.Errorf("marshal schemas: %w", err)
return fmt.Errorf("marshal documentation data: %w", err)
}
body = append(body, '\n')
destination := outPath
if !filepath.IsAbs(destination) {
@@ -76,8 +79,7 @@ func run(repoRoot, outPath string) error {
if err := os.MkdirAll(filepath.Dir(destination), 0o755); err != nil {
return fmt.Errorf("create output directory: %w", err)
}
header := []byte("# Code generated by tools/docsgen. DO NOT EDIT.\n")
if err := os.WriteFile(destination, append(header, body...), 0o644); err != nil {
if err := os.WriteFile(destination, body, 0o644); err != nil {
return fmt.Errorf("write %s: %w", destination, err)
}
@@ -85,6 +87,18 @@ func run(repoRoot, outPath string) error {
return nil
}
// currentContractTypes adapts the pre-domain-registry contract set during the
// architecture migration. Delete it when agent execution and messaging expose
// domain-owned documentation registries; docsgen must then consume those
// registries directly.
func currentContractTypes() map[string]reflect.Type {
return map[string]reflect.Type{
"AgentExecutionRequest": reflect.TypeFor[agentexec.Request](),
"AgentExecutionResult": reflect.TypeFor[agentexec.Result](),
"MessageEvent": reflect.TypeFor[gateway.MessageEvent](),
}
}
func loadGoComments(reflector *jsonschema.Reflector, repoRoot string) error {
const modulePath = "github.com/samcharles93/archie-core"
if err := reflector.AddGoComments("", filepath.Join(repoRoot, "internal")); err != nil {
@@ -108,7 +122,7 @@ func collectSchema(
t reflect.Type,
) error {
if _, exists := schemas[name]; exists {
return nil
return fmt.Errorf("duplicate published schema name %q", name)
}
raw, err := json.Marshal(reflector.ReflectFromType(t))
if err != nil {
@@ -124,9 +138,13 @@ func collectSchema(
delete(tree, "$id")
schemas[name] = tree
for defName, defSchema := range defs {
if _, exists := schemas[defName]; !exists {
schemas[defName] = defSchema
if existing, exists := schemas[defName]; exists {
if !reflect.DeepEqual(existing, defSchema) {
return fmt.Errorf("conflicting schema definition %q", defName)
}
continue
}
schemas[defName] = defSchema
}
return nil
}
+215
View File
@@ -1,11 +1,75 @@
package main
import (
"bytes"
"encoding/json"
"os"
"path/filepath"
"reflect"
"strings"
"testing"
"github.com/invopop/jsonschema"
)
type contractWithConflictingDefinition struct {
Value conflictingDefinition `json:"value"`
}
type conflictingDefinition struct {
Value string `json:"value"`
}
func TestRunWritesDeterministicContractData(t *testing.T) {
repoRoot := filepath.Clean("../..")
outputDir := t.TempDir()
outputs := []string{
filepath.Join(outputDir, "first.json"),
filepath.Join(outputDir, "second.json"),
}
for _, output := range outputs {
if err := run(repoRoot, output); err != nil {
t.Fatalf("run(%q) error = %v", output, err)
}
}
first, err := os.ReadFile(outputs[0])
if err != nil {
t.Fatalf("read first output: %v", err)
}
second, err := os.ReadFile(outputs[1])
if err != nil {
t.Fatalf("read second output: %v", err)
}
if !bytes.Equal(first, second) {
t.Fatal("repeated generation produced different bytes")
}
var data struct {
GeneratedBy string `json:"generatedBy"`
Schemas map[string]json.RawMessage `json:"schemas"`
}
if err := json.Unmarshal(first, &data); err != nil {
t.Fatalf("decode generated data: %v", err)
}
if data.GeneratedBy != "tools/docsgen" {
t.Fatalf("generatedBy = %q, want %q", data.GeneratedBy, "tools/docsgen")
}
for _, name := range []string{
"AgentExecutionRequest",
"AgentExecutionResult",
"MessageEvent",
} {
if _, ok := data.Schemas[name]; !ok {
t.Errorf("schemas[%q] is missing", name)
}
}
for name, schema := range data.Schemas {
assertSchemaRefsResolve(t, name, schema, data.Schemas)
}
}
func TestRunHonoursAbsoluteOutputPath(t *testing.T) {
repoRoot := filepath.Clean("../..")
outputDir := t.TempDir()
@@ -31,3 +95,154 @@ func TestRunHonoursAbsoluteOutputPath(t *testing.T) {
t.Fatalf("working directory = %q, want %q", currentDir, originalDir)
}
}
func TestCollectSchemaRejectsDuplicatePublishedName(t *testing.T) {
reflector := &jsonschema.Reflector{ExpandedStruct: true}
schemas := map[string]any{}
const name = "PublishedContract"
if err := collectSchema(reflector, schemas, name, reflect.TypeFor[struct {
First string `json:"first"`
}]()); err != nil {
t.Fatalf("collect first schema: %v", err)
}
err := collectSchema(reflector, schemas, name, reflect.TypeFor[struct {
Second int `json:"second"`
}]())
if err == nil {
t.Fatal("collect duplicate schema returned nil error")
}
}
func TestCollectSchemaRejectsConflictingDefinition(t *testing.T) {
reflector := &jsonschema.Reflector{ExpandedStruct: true}
schemas := map[string]any{
"conflictingDefinition": map[string]any{"type": "integer"},
}
err := collectSchema(
reflector,
schemas,
"PublishedContract",
reflect.TypeFor[contractWithConflictingDefinition](),
)
if err == nil {
t.Fatal("collect conflicting definition returned nil error")
}
if !strings.Contains(err.Error(), `conflicting schema definition "conflictingDefinition"`) {
t.Fatalf("collect conflicting definition error = %q", err)
}
}
func TestRunReportsFilesystemAndSourceErrors(t *testing.T) {
repoRoot := filepath.Clean("../..")
blocker := filepath.Join(t.TempDir(), "file")
if err := os.WriteFile(blocker, []byte("occupied"), 0o600); err != nil {
t.Fatalf("create blocker: %v", err)
}
tests := []struct {
name string
root string
output string
contains string
}{
{
name: "missing source tree",
root: t.TempDir(),
output: filepath.Join(t.TempDir(), "contracts.json"),
contains: "load Go comments",
},
{
name: "output parent is a file",
root: repoRoot,
output: filepath.Join(blocker, "contracts.json"),
contains: "create output directory",
},
{
name: "output is a directory",
root: repoRoot,
output: t.TempDir(),
contains: "write ",
},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
err := run(test.root, test.output)
if err == nil {
t.Fatal("run() returned nil error")
}
if !bytes.Contains([]byte(err.Error()), []byte(test.contains)) {
t.Fatalf("run() error = %q, want substring %q", err, test.contains)
}
})
}
}
func TestRewriteRef(t *testing.T) {
tests := map[string]string{
"definition": "#/schemas/Contract",
"external": "https://example.com/schema.json",
"empty name": "#/$defs/",
}
for name, want := range tests {
t.Run(name, func(t *testing.T) {
input := want
if name == "definition" {
input = "#/$defs/Contract"
}
if got := rewriteRef(input); got != want {
t.Fatalf("rewriteRef(%q) = %q, want %q", input, got, want)
}
})
}
}
func assertSchemaRefsResolve(
t *testing.T,
name string,
raw json.RawMessage,
schemas map[string]json.RawMessage,
) {
t.Helper()
var value any
if err := json.Unmarshal(raw, &value); err != nil {
t.Fatalf("decode schema %q: %v", name, err)
}
walkJSON(value, func(ref string) {
const prefix = "#/schemas/"
if !strings.HasPrefix(ref, "#") {
return
}
if !strings.HasPrefix(ref, prefix) {
t.Errorf("schema %q contains unresolved local reference %q", name, ref)
return
}
target := ref[len(prefix):]
if _, ok := schemas[target]; !ok {
t.Errorf("schema %q references missing schema %q", name, target)
}
})
}
func walkJSON(value any, visitRef func(string)) {
switch node := value.(type) {
case map[string]any:
for key, child := range node {
if key == "$ref" {
if ref, ok := child.(string); ok {
visitRef(ref)
}
continue
}
walkJSON(child, visitRef)
}
case []any:
for _, child := range node {
walkJSON(child, visitRef)
}
}
}
+1 -1
View File
@@ -5,7 +5,6 @@ go 1.26.4
require (
github.com/invopop/jsonschema v0.14.0
github.com/samcharles93/archie-core v0.0.0-00010101000000-000000000000
gopkg.in/yaml.v3 v3.0.1
)
require (
@@ -25,6 +24,7 @@ require (
go.yaml.in/yaml/v4 v4.0.0-rc.2 // indirect
golang.org/x/crypto v0.53.0 // indirect
golang.org/x/sys v0.46.0 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
)
replace github.com/samcharles93/archie-core => ../