Merge branch 'crew/skills2'
This commit is contained in:
commit
5f5b488b9f
12 files changed
+882
-2685
No files matched your search
@@ -20,8 +20,6 @@ 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 |
|
||||
@@ -30,9 +28,8 @@ Use these labels exactly:
|
||||
|
||||
> **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.
|
||||
> used from a production entry point. `internal/domain/` does not exist in the
|
||||
> CURRENT tree as of 2026-07-28.
|
||||
|
||||
Resolve apparent disagreement in this order:
|
||||
|
||||
@@ -43,24 +40,8 @@ Resolve apparent disagreement in this order:
|
||||
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.
|
||||
Route to `archie-domain-reference` for glossary, `archie-nelldb` for
|
||||
persistence, `archie-config-and-flags` for config enumeration.
|
||||
|
||||
## Know the CURRENT system
|
||||
|
||||
@@ -68,18 +49,18 @@ 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 |
|
||||
| Composition | `cmd/archied/main.go` performs substantial construction and wiring. | `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` |
|
||||
| Workflow | `internal/workflow` routes a `store.Task` into a `map[string]Workflow`, mutates a broad `TaskContext` through sequential stages. | `internal/workflow/workflow.go` |
|
||||
| Agent-stage boundary | Versioned `agentexec.Request`/`Result` carries one autonomous stage; validation correlates task, attempt, and stage. | `internal/agentexec/protocol.go` |
|
||||
| Container handoff | `internal/taskrun` carries entire task plus `config.Repo` and `config.TaskConfig`; `archie-agent` runs routing and sequencing. | `internal/taskrun/taskrun.go`; `cmd/archie-agent/main.go` |
|
||||
| Git ownership | Daemon-owned worktree operations clone, commit, push, diff, and clean up. | `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/` |
|
||||
| Identity | Configured names and bot usernames act as process-local identity keys. 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 richer `MessageEvent`; channel routing and 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` |
|
||||
| Processes | Agent modes include in-process, subprocess, and NATS. Optional containers add a distinct boundary with known gaps. | `internal/config/config.go`; `cmd/archied/main.go`; `ARCHITECTURE.md` |
|
||||
|
||||
### Interpret the current lifecycle honestly
|
||||
|
||||
@@ -95,31 +76,26 @@ 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.
|
||||
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 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.
|
||||
|
||||
## 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/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` |
|
||||
| The model never runs git | Keep clone, branch, commit, push, diff, and cleanup in deterministic workspace/worktree steps. | CURRENT: `ARCHITECTURE.md`; `internal/worktree/` |
|
||||
| Deterministic constraints outrank prompts | Enforce gates, protected paths, read-only stages, test protection, and change caps outside model instructions. | 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. | CURRENT foundation: `internal/agentexec/protocol.go`; `ARCHITECTURE.md` |
|
||||
| Every workflow ends explicitly | Preserve terminal outcome or visible park. 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()`/`Version()`. Behavior on typed capability interface with owning `Registry`/`Manager`. | CURRENT-enforced rule: `internal/plugin/architecture_test.go` |
|
||||
| Capability engines own lifecycle | Give resource-owning engines explicit start/health/stop semantics and failure isolation. | APPROVED rule: `ARCHITECTURE.md#plugin-engine-rule-strict` |
|
||||
| Trust is explicit | Treat trusted operator-installed in-process code, repository code, out-of-process integrations, and container-isolated code as different trust classes. | APPROVED rule: `ARCHITECTURE.md#plugin-engine-rule-strict` |
|
||||
| Infrastructure stays replaceable | Keep forge, persistence, workspace, transport, container, and model details behind behavior-owned contracts. | APPROVED TARGET: `docs/architecture/dependencies-and-contracts.md` |
|
||||
| Same-repository execution serializes by default | Preserve default unless 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:
|
||||
@@ -128,18 +104,13 @@ interface:
|
||||
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.
|
||||
Apply ownership rules to migration plans and new seams. Not CURRENT until
|
||||
production wiring proves the cutover.
|
||||
|
||||
### Keep dependency direction inward
|
||||
|
||||
Use this target direction:
|
||||
|
||||
```text
|
||||
domain and shared application contracts <- infrastructure implementations
|
||||
^
|
||||
@@ -147,8 +118,6 @@ 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
|
||||
@@ -157,168 +126,102 @@ Enforce:
|
||||
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/architecture/organisation.md` and
|
||||
Sources: `docs/architecture/organisation.md`,
|
||||
`docs/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/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
|
||||
channel-neutral Message -> Agent turn -> optional proposed work
|
||||
-> Work Intake -> AcceptedWorkRequest -> Workflow selects version -> WorkflowExecution
|
||||
```
|
||||
|
||||
Keep the concepts separate:
|
||||
- **Messaging** owns canonical messages, conversations, branches, channel correlation, delivery.
|
||||
- **Agent** owns persistent assistant, continuity, specialization, memory.
|
||||
- **Work Intake** owns admission, validation, routing, accepted-work-request handoff.
|
||||
- **Workflow** owns versioned definitions, steps, executions, attempts, outcomes.
|
||||
|
||||
- **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.
|
||||
Do not equate external issue/message with WorkflowExecution; do not let Work
|
||||
Intake create one directly.
|
||||
|
||||
Sources: `docs/architecture/migration-decisions.md`,
|
||||
`docs/architecture/agent-system.md`, and
|
||||
`docs/architecture/messaging-and-work-intake.md`.
|
||||
`docs/architecture/agent-system.md`, `docs/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:
|
||||
Use immutable `IdentityID` for target attribution. Keep Identity separate from
|
||||
Agent. Four fixed memory scopes:
|
||||
|
||||
| Scope | Visibility |
|
||||
| --- | --- |
|
||||
| Global shared | Intentionally shared across Archie |
|
||||
| Agent-wide | One Agent across its users; private to that Agent by default |
|
||||
| Global shared | Shared across Archie |
|
||||
| Agent-wide | One Agent across users; private 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.
|
||||
Do not use conversation branching as a fifth memory scope.
|
||||
|
||||
Sources: `docs/architecture/identity.md`,
|
||||
`docs/architecture/agent-system.md`, and
|
||||
Sources: `docs/architecture/identity.md`, `docs/architecture/agent-system.md`,
|
||||
`docs/architecture/migration-decisions.md`.
|
||||
|
||||
### Dissolve global runtime configuration
|
||||
|
||||
Treat the current `internal/config` package as a migration source inventory, not
|
||||
a target domain:
|
||||
Treat `internal/config` as migration source inventory:
|
||||
|
||||
- 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`;
|
||||
- move file/env/overlay/secret decoding to `internal/infrastructure/configuration`;
|
||||
- let each domain or plugin own typed runtime settings;
|
||||
- translate external DTOs 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,
|
||||
- classify each 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/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. |
|
||||
| Canonical messages, conversations, branches, delivery | `internal/domain/messaging` | Keep platform IDs as external correlation. |
|
||||
| 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. |
|
||||
| Shared policy evaluation/evidence mechanics | `internal/policy` | Keep policy vocabulary, evaluators, and consequences with 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. |
|
||||
| Deploy assembly | `deployments/<assembly>` | Do not move application behavior into deployment files. |
|
||||
| Unreviewed memory/tools/workspace/gate/storage/web/RPC/scheduling | **OPEN** | Run `archie-architecture-planning-campaign`. |
|
||||
|
||||
## 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`. |
|
||||
| `TaskContext` is a mutable service bag with config, services, policy, scratch state. | Design narrow step inputs and staged removal. |
|
||||
| Workflow lifecycle split across store, daemon, workflow, gateway, worker. | Trace every writer and reader before changing status. |
|
||||
| State changes and transition history non-atomic; `from` is advisory. | Treat as architecture migration, not local fix. |
|
||||
| In-process and container paths put orchestration on different sides of process boundary. | Decide which path survives before extending both. |
|
||||
| Identity uses strings; task uniqueness/NATS dedup omit identity. | Don't promise multi-identity ownership until canonical IDs migrate. |
|
||||
| Container RPC uses root forge/worktree, not task owner's identity. | Known trust/correctness defect — not identity-isolated. |
|
||||
| Missing `task.json` makes `archie-agent` join shared queue. | Fail closed before treating as isolated. |
|
||||
| Subprocess uses daemon user and host access. | Not a security boundary. |
|
||||
| Gateway duplicates lifecycle strings, competing message contracts. | No third contract or direct lifecycle mutation path. |
|
||||
| Global config and `IdentityConfig` combine unrelated owners. | Don't rename global structure or add `Extra` map. |
|
||||
| Memory has fixed scope requirements but OPEN final placement/migration. | Preserve scope isolation; focused design before moving. |
|
||||
| Tests can make unused/duplicate code appear legitimate. | Prove production reachability from composition. |
|
||||
|
||||
## 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. |
|
||||
| Current-path repair | Stay inside current owner, preserve invariants. |
|
||||
| Migration slice | Record current/target owner, contracts, compatibility adapter, cutover, deletion criteria. |
|
||||
| New/changed architecture | Stop; run `archie-architecture-planning-campaign` until 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:
|
||||
Trace with evidence:
|
||||
|
||||
```bash
|
||||
rg -n '<constructor>|<interface>|<method>' cmd internal
|
||||
@@ -328,35 +231,4 @@ 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/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
|
||||
```
|
||||
Trace from `cmd/archied/main.go`.
|
||||
@@ -9,41 +9,20 @@ 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/README.md` as onboarding documentation. It describes Tau,
|
||||
and VitePress excludes it through `srcExclude` in
|
||||
`docs/.vitepress/config.mts`.
|
||||
All volatile observations are snapshots from **2026-07-28**.
|
||||
|
||||
## 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/`. |
|
||||
| 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. |
|
||||
| Repository root | Directory containing `go.mod`, `Taskfile.yml`, and `CLAUDE.md`. |
|
||||
| Runtime module | Root Go module `github.com/samcharles93/archie-core`. |
|
||||
| Tools module | Independent nested Go module under `tools/`. |
|
||||
| Docs site | pnpm/VitePress project under `docs/`. |
|
||||
| Cold cache | Dependency cache not yet containing required modules/packages. |
|
||||
| Restricted sandbox | May allow file reads but deny loopback listeners, container engine, or writes to default caches. |
|
||||
|
||||
No root `README*` or `CONTRIBUTING*` file exists as of the snapshot. Begin with:
|
||||
No root `README*` or `CONTRIBUTING*` file exists. Begin with:
|
||||
|
||||
```bash
|
||||
sed -n '1,240p' CLAUDE.md
|
||||
@@ -51,73 +30,41 @@ 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
|
||||
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.
|
||||
Classify a missing command as an environment prerequisite. Bootstrap (verified
|
||||
2026-07-28): Go ≥ 1.26.3, Task ≥ 3.x, gofumpt (unpinned), golangci-lint v2
|
||||
(unpinned), Node 24.x + pnpm ≥ 10.
|
||||
|
||||
| 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.
|
||||
| Runtime Go | `go 1.26.3` in `go.mod` | Go 1.26.5, linux/amd64 | Requires at least declared Go level. |
|
||||
| Tools Go | `go 1.26.4` in `tools/go.mod` | Same Go 1.26.5 binary | Toolchain must satisfy both modules. |
|
||||
| Task | Taskfile schema `version: "3"` | Task 3.48.0 | Installed version is environment fact. |
|
||||
| gofumpt | Used by `task fmt`; `@latest` install | v0.7.0 | Unpinned. |
|
||||
| golangci-lint | v2 config in `.golangci.yml`; `@latest` install | 2.12.2 | Use v2 CLI; exact release unpinned. |
|
||||
| Node | Docs CI `node-version: latest` | 24.18.0 | No `engines`/`packageManager` field. |
|
||||
| pnpm | Docs CI major 10 | 11.15.1 | Prefer CI's major 10. |
|
||||
| VitePress | `^1.6.4`, locked to 1.6.4 | Resolved by `pnpm-lock.yaml` | Install with frozen lockfile. |
|
||||
| Containers | Compose commands in `Taskfile.yml` | Podman-backed, unusable in this sandbox | Verify CLI, Compose plugin, daemon/socket separately. |
|
||||
|
||||
## 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:
|
||||
If any default is read-only:
|
||||
|
||||
```bash
|
||||
export ARCHIE_GOTMPDIR=/tmp/archie-core-gotmp
|
||||
@@ -129,7 +76,7 @@ mkdir -p "$ARCHIE_GOTMPDIR" "$ARCHIE_GOCACHE" "$ARCHIE_GOMODCACHE" \
|
||||
"$ARCHIE_GOPATH" "$ARCHIE_LINT_CACHE"
|
||||
```
|
||||
|
||||
Prefix Go commands with:
|
||||
Prefix Go commands:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR="$ARCHIE_GOTMPDIR" GOCACHE="$ARCHIE_GOCACHE" \
|
||||
@@ -137,40 +84,16 @@ env GOTMPDIR="$ARCHIE_GOTMPDIR" GOCACHE="$ARCHIE_GOCACHE" \
|
||||
go test ./internal/config/... -count=1
|
||||
```
|
||||
|
||||
An empty `ARCHIE_GOMODCACHE` is a cold cache. Populate each module only when
|
||||
network access is authorized:
|
||||
Populate cold cache only with network 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"
|
||||
env ... go mod download; env ... go -C tools mod download
|
||||
```
|
||||
|
||||
## 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
|
||||
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
|
||||
@@ -179,246 +102,109 @@ 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 fmt` | `gofumpt -w .`, then `go fix ./...` — both may rewrite source. |
|
||||
| `task vet` | `go vet ./...` in the runtime module. |
|
||||
| `task lint` | `golangci-lint run ./...`. |
|
||||
| `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. |
|
||||
| `task test` | `go test ./... -count=1` in the runtime module. |
|
||||
| `task check` | `fmt` + `go fix ./...` again + `vet` + `build` + `test`. |
|
||||
| `task clean` | Recursively removes `bin/`; destructive. |
|
||||
| `task docker-build` | `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.
|
||||
`task check` is the definitive gate but omits `task lint`, race tests, `tools/`
|
||||
module, docs generation drift, and VitePress build. Run only in authorized
|
||||
writable worktree. For read-only preview: `gofumpt -l .`.
|
||||
|
||||
## Verify the tools module separately
|
||||
|
||||
The repository has no `go.work`. A root `go test ./...` does not enter
|
||||
`tools/`. The tools module uses:
|
||||
No `go.work`. Root `go test ./...` does not enter `tools/`.
|
||||
|
||||
```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:
|
||||
Generate documentation to temp file:
|
||||
|
||||
```bash
|
||||
go -C tools run ./docsgen \
|
||||
-repo-root .. \
|
||||
-out /tmp/archie-core-contracts.json
|
||||
cmp --silent \
|
||||
docs/data/generated/contracts.json \
|
||||
/tmp/archie-core-contracts.json
|
||||
go -C tools run ./docsgen --repo-root .. --out /tmp/archie-core-contracts.json
|
||||
cmp --silent docs/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/architecture/generated-documentation.md` do **not** exist yet.
|
||||
The checkout's `docs/data/generated/contracts.json` exists but is untracked
|
||||
as of this snapshot. The comparison proves local generator parity, not
|
||||
version-controlled drift protection.
|
||||
2026-07-28 run wrote 10 schemas; comparison passed. Planned `docsgen all` and
|
||||
`docsgen check` do **not** exist yet.
|
||||
|
||||
## Recreate and build the docs site
|
||||
|
||||
Treat dependency installation and site compilation as two separate gates:
|
||||
|
||||
```bash
|
||||
pnpm --dir docs install --frozen-lockfile
|
||||
pnpm --dir docs build
|
||||
```
|
||||
|
||||
The install needs registry access on a cold pnpm store. The build writes
|
||||
`docs/.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/node_modules` shape. It contains 237
|
||||
tracked symlink entries as of the snapshot, introduced by commit `308c199`.
|
||||
Detect the condition:
|
||||
Git tracks 237 `docs/node_modules` symlink entries (commit `308c199`):
|
||||
|
||||
```bash
|
||||
git ls-files -s 'docs/node_modules/**' \
|
||||
| awk '$1 == "120000" {count++} END {print count+0}'
|
||||
git status --short -- docs
|
||||
git ls-files -s 'docs/node_modules/**' | awk '$1 == "120000" {count++} END {print count+0}'
|
||||
```
|
||||
|
||||
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.
|
||||
Commit `4cb0577` cleaned up accidentally committed `.gotmp`; `.gotmp/` 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.
|
||||
No `.dockerignore` exists. Both Dockerfiles run `COPY . .`. Floating inputs: Go
|
||||
builder tags omit patch/digest; Ubuntu base images omit digests; agent installs
|
||||
multiple `@latest` Go tools; Node from moving `setup_24.x` channel.
|
||||
|
||||
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.
|
||||
`task docker-build` needs registry/network and functioning Compose.
|
||||
`task docker-up` additionally pulls images, binds ports 4222/8222/8484, mounts
|
||||
host paths and container socket.
|
||||
|
||||
## 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. |
|
||||
| `go: creating work dir: mkdir /work/tmp/...: read-only file system` | Set task-specific `GOTMPDIR`. |
|
||||
| `open .../.cache/go-build/...: read-only file system` | Set writable `GOCACHE`. |
|
||||
| `open .../pkg/mod/cache/...tmp: read-only file system` | Set writable `GOMODCACHE` and `GOPATH`. |
|
||||
| `listen ...: socket: operation not permitted` | Re-run on host with loopback sockets. |
|
||||
| `Unable to start NATS Server in Go Routine` after ~10s | Test whether local listeners permitted. |
|
||||
| `cannot auto-sign commit` | Ambient `commit.gpgSign=true`; fixtures set `gpgsign=false`. |
|
||||
| `EAI_AGAIN` for `registry.npmjs.org` | Dependency retrieval failed. |
|
||||
| `Podman configuration ... read-only file system` | Container backend cannot initialize. |
|
||||
| `TestRunWrapsExternalCommand ... Run() = "\n"` | Focused code failure in `internal/skillscript`. |
|
||||
|
||||
For hermetic test diagnosis only, suppress ambient global Git configuration:
|
||||
For hermetic test diagnosis:
|
||||
|
||||
```bash
|
||||
env GIT_CONFIG_GLOBAL=/dev/null \
|
||||
go test ./internal/worktree/... ./internal/worktreerpc/... -count=1
|
||||
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. |
|
||||
| Focused Go behavior | `go test ./pkg/... -run '^TestName$' -count=1 -v` | Use first. |
|
||||
| Root unit/integration suite | `go test ./... -count=1` | Restricted sandbox fails listener-dependent packages. |
|
||||
| Root race suite | `go test -race ./... -count=1` | Not run by `task check`. |
|
||||
| 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. |
|
||||
| Lint | `golangci-lint run ./...` | Failed with 54 findings on 2026-07-28. |
|
||||
| Build | `go build -o /tmp/... ./cmd/archied` and `cmd/archie-agent` | 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 install --frozen-lockfile` then `pnpm --dir docs 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/package.json`,
|
||||
`docs/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/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/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 ./...`
|
||||
| Generated contract parity | Temp docsgen output + `cmp --silent` | Passed for 10 schemas. |
|
||||
| Docs install/build | `pnpm --dir docs install --frozen-lockfile` then `pnpm build` | Blocked by restricted network. |
|
||||
| Container build | `task docker-build` | Not verified in restricted environment. |
|
||||
| Repository gate | `task check` | Non-green; skillscript failure in root suite. |
|
||||
@@ -6,119 +6,57 @@ description: "Trace Archie behavior and blast radius through Go source, types, s
|
||||
# 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**.
|
||||
|
||||
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.
|
||||
**Composition root**: `cmd/archied/main.go` and `cmd/archie-agent/`.
|
||||
**Production wiring**: a path selected by a shipped entrypoint — not a
|
||||
constructor, decoder, or passing unit test. **State owner**: component with
|
||||
authority to validate and persist a state transition.
|
||||
|
||||
## 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'
|
||||
go version; go env GOMOD GOWORK GOOS GOARCH
|
||||
gopls version; golangci-lint version; staticcheck -version
|
||||
```
|
||||
|
||||
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`.
|
||||
As of 2026-07-28: Go 1.26.5, gopls 0.23.0, golangci-lint 2.12.2,
|
||||
staticcheck 2026.1. Use `gopls call_hierarchy` (no `go tool callgraph`).
|
||||
|
||||
Use writable caches when the host's default Go caches are read-only:
|
||||
Writable caches when defaults 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
|
||||
export GOPROXY=off 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 `./...`:
|
||||
Module boundaries (root and `tools/` are separate):
|
||||
|
||||
```sh
|
||||
find . \( -path './.git' -o -path './.references' -o -path './.claude/worktrees' -o -name node_modules \) -prune -o -name go.mod -print
|
||||
find . -name go.mod -not -path './.git/*' -not -path './node_modules/*'
|
||||
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.
|
||||
Write: behavior, observable input, expected output, state that may change, modes.
|
||||
|
||||
| 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 |
|
||||
| 1 | Entrypoint | `main`, handler, poller, RPC subject, or tool registration |
|
||||
| 2 | Construction | Constructor and every direct struct literal |
|
||||
| 3 | Contract | Interface, wire type, command, event, or public method crossed |
|
||||
| 4 | Implementation | All type-valid implementations, selected per mode |
|
||||
| 5 | State owner | Function validating transition, owning concurrency/transaction rules |
|
||||
| 6 | Persistence | Store adapter, schema/key/document, serialization, reload/recovery |
|
||||
| 7 | Event/transport | Publish/send and subscribe/receive, subject/framing, timeout, retry, ack |
|
||||
| 8 | Consumer | Callers and downstream readers |
|
||||
| 9 | Tests | Unit, integration, contract, architecture, production-composition |
|
||||
| 10 | Configuration | Decode, default, validation, normalization, composition-root consumption |
|
||||
| 11 | Target architecture | Current-to-target mapping in `docs/prds/`; label gaps |
|
||||
|
||||
Start at these verified anchors:
|
||||
|
||||
@@ -128,40 +66,25 @@ Start at these verified anchors:
|
||||
| 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` |
|
||||
| Production task persistence | `internal/nell/adapter.go`; `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/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 -f '{{.ImportPath}}|go={{join .GoFiles ","}}|tests={{join .TestGoFiles ","}}' ./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/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:
|
||||
1-indexed `file:line:column`:
|
||||
|
||||
```sh
|
||||
gopls symbols internal/store/interface.go
|
||||
@@ -169,264 +92,134 @@ 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.
|
||||
Confirms candidates with `gopls definition` or `gopls references`. 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/...
|
||||
rg -n 'Transition\(|PublishTask\(|ClaimNext\(|StatusWaitingHuman' cmd internal
|
||||
```
|
||||
|
||||
```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.
|
||||
Trace each candidate to entrypoint and state owner. `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`.
|
||||
For every suspect: `gopls references -d`; search init, reflection/Yaegi, tags,
|
||||
RPC subjects, plugin manifests, string dispatch; check build tags/OS files;
|
||||
search both composition roots. `U1000` does not prove exported/reflection/wire
|
||||
targets are dead.
|
||||
|
||||
### 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
|
||||
gopls implementation
|
||||
rg -n 'var _ .*=' --glob '*.go' cmd internal
|
||||
```
|
||||
|
||||
```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.
|
||||
Trace which implementation the composition root selects for each mode.
|
||||
|
||||
### 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.
|
||||
`gopls references -d` on field declaration, not common name. Trace assignments
|
||||
and reads separately. Follow `ForTask`/`ToConfig` copies. Check JSON/TOML/YAML
|
||||
tags. Compare production and `_test.go` references.
|
||||
|
||||
### 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.
|
||||
Run `scan-go-type-syntax.sh Type .`. Inspect struct literals outside owning
|
||||
package. Compare validation/defaulting in constructors with direct literals.
|
||||
Use `gopls references` on constructor and type.
|
||||
|
||||
### 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.
|
||||
```sh
|
||||
.claude/skills/archie-codebase-discovery/scripts/package-edges.sh ./internal/...
|
||||
go list -deps -json <pattern>
|
||||
```
|
||||
|
||||
### 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:
|
||||
Prove: `file/key → decoder → default → validation → normalization/copy →
|
||||
composition-root read → concrete component → observable behavior`.
|
||||
|
||||
```sh
|
||||
rg -n 'toml:"|yaml:"|json:"' internal/config
|
||||
rg -n 'LoadOverlay|LoadDir|finalize|ForTask|ToConfig' internal/config cmd
|
||||
gopls references -d <exact-field>
|
||||
```
|
||||
|
||||
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.
|
||||
As of 2026-07-28 `cmd/archied` calls `config.LoadOverlay`; `config.LoadDir` is
|
||||
test-only.
|
||||
|
||||
### 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.
|
||||
1. Start at `cmd/archied/main.go:run`.
|
||||
2. Record config condition per branch.
|
||||
3. Follow concrete construction into `daemon.Daemon` and gateway start.
|
||||
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.
|
||||
5. Trace both sides of every RPC/transport and error/timeout paths.
|
||||
6. Read contract/architecture tests.
|
||||
7. Confirm deploy inputs in Compose and CI.
|
||||
|
||||
### 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.
|
||||
Treat `internal/store` as application contract, `internal/nell` as one adapter.
|
||||
|
||||
```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`.
|
||||
As of 2026-07-28, `Adapter.Transition` neither locks nor checks `from`. NellDB's
|
||||
`_id`/`_rev`, HLC, and conflict semantics come from the dependency API.
|
||||
|
||||
## 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 |
|
||||
| One `rg` result | Misses interface dispatch, aliases, generated registration, reflection | Use gopls, AST candidates, package edges, composition |
|
||||
| Green unit test | May bypass config, lifecycle, transport | Add composition/contract/integration evidence |
|
||||
| Fake client and server agree | Both mirror same wrong framing/subject/state assumption | Compare independent spec or real boundary fixture |
|
||||
| High coverage | Does not establish ownership, maintainability, mode selection | Trace authority and 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 |
|
||||
| Config field decodes | Does not prove executable reads it | Complete config-to-observable chain |
|
||||
| Target PRD says it | Not necessarily current code | Cite current implementation and label gap |
|
||||
|
||||
## Produce the discovery handoff
|
||||
|
||||
End with these sections:
|
||||
|
||||
1. **Behavior trace:** one row per traversal step with `path:line`, symbol, and
|
||||
current responsibility.
|
||||
1. **Behavior trace:** path:line, symbol, current responsibility per traversal step.
|
||||
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
|
||||
3. **State and authority:** owner, copies, persistence, transition rules, recovery.
|
||||
4. **Blast radius:** callers, consumers, tests, config, deploy wiring, docs,
|
||||
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.
|
||||
5. **Duplication/deprecation ledger:** each candidate, live/dead evidence,
|
||||
replacement, objective removal gate.
|
||||
6. **Current-to-target gap:** current fact, target PRD, migration implication.
|
||||
7. **Unknowns:** exact command, output/blocker, 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`
|
||||
Do not propose implementation until the trace answers: what entrypoint selects
|
||||
this path, which component owns state, which parallel/older path the feature
|
||||
replaces, which production modes and persisted data must remain compatible,
|
||||
which evidence would falsify current understanding.
|
||||
@@ -9,22 +9,7 @@ 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`.
|
||||
Current evidence date: **2026-07-28**.
|
||||
|
||||
Use these status terms exactly:
|
||||
|
||||
@@ -34,33 +19,24 @@ Use these status terms exactly:
|
||||
| **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.
|
||||
2. Identify the selected loader or flag set.
|
||||
3. Read `finalize` and any consumer-side defaults.
|
||||
4. Follow copies across `ForTask`, `ToConfig`, NATS messages, subprocess
|
||||
environment selection, container environment construction, and identity
|
||||
overlays.
|
||||
env selection, container env 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.
|
||||
6. Find tests for decoding, defaulting, invalid input, production composition,
|
||||
and mode parity.
|
||||
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:
|
||||
8. Assign one status from the table above.
|
||||
|
||||
```bash
|
||||
rg -n 'LoadOverlay|LoadDir|ForTask|ToConfig|flag\.' \
|
||||
@@ -69,30 +45,21 @@ 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 |
|
||||
| `archied -config-overlay PATH` | Decodes base TOML, then overlay TOML into the same `Config`, 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 |
|
||||
| `config.docker.toml` | Repository overlay mounted by Compose; still depends on host base config. | production-wired |
|
||||
| Host base config and environment on `carina` | Mounted from `${HOME}/.config/archie/config.toml`; contents 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.
|
||||
Both TOML and YAML decoding are non-strict at the field level. Add explicit
|
||||
compatibility and typo tests; never use "the file loaded" as evidence that a
|
||||
key took effect.
|
||||
|
||||
## Inventory CLI flags
|
||||
|
||||
@@ -101,12 +68,12 @@ use “the file loaded” as evidence that a key took effect.
|
||||
| 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` | `-config-overlay PATH` | Empty; overlay only fields explicitly present in 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. |
|
||||
| `archied` | `-requeue ID` | `0`; values greater than zero requeue one parked/waiting task, then exit unless `-once` 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. |
|
||||
| both | `-quickchecks N` | Incidental flag registered by `github.com/traefik/yaegi/stdlib` importing `testing/quick`; default `100`. Treat as unowned candidate defect. |
|
||||
|
||||
The standalone agent always reads its token from `NATS_TOKEN`; there is no
|
||||
token flag.
|
||||
@@ -114,15 +81,14 @@ token flag.
|
||||
### Internal codesearch helper
|
||||
|
||||
`archied workspace-codesearch` bypasses daemon configuration before normal flag
|
||||
parsing. It is an internal child-process contract:
|
||||
parsing:
|
||||
|
||||
| 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.
|
||||
Do not expose these helper flags as daemon settings.
|
||||
|
||||
## Read the current wiring matrix
|
||||
|
||||
@@ -130,52 +96,50 @@ compatibility decision.
|
||||
|
||||
| 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 |
|
||||
| `work_dir`, `db_path` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; literal `~` in explicit value not expanded. | production-wired |
|
||||
| `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. | partially-wired |
|
||||
| `plugin_dir` | Empty disables daemon plugin loading; configured directory loaded in `cmd/archied`. | production-wired |
|
||||
| `poll_interval` | Default `60s`; root poll loop uses it, identities may override only interval. | production-wired |
|
||||
| `label` | No default or validation; used for `dispatch.trigger = "label"` or `"either"`. | production-wired |
|
||||
| `max_retries` | Default `3`; repository value greater than zero overrides. | production-wired |
|
||||
| `bot_user`, `bot_email` | Single-identity requires `bot_user`; email defaults by forge type. | production-wired |
|
||||
| `forge.type`, `host`, `token` | Type defaults `github`, host defaults `https://github.com`; only `github` and `gitea` validate. | production-wired |
|
||||
| `dispatch.trigger` | Default `assignee`; validates `assignee`, `label`, or `either`. | production-wired |
|
||||
| `dispatch.ack_reaction` | Default `eyes`; case-insensitive `off` normalizes to empty. | production-wired |
|
||||
| `dispatch.labels.*` | Missing keys default independently to `agent:*`. | production-wired |
|
||||
| `models.<role>` | Workflow stages read requested role then fall back to `builder`; triage judge falls back `triage` to `planner`. | production-wired |
|
||||
| `providers.<name>.class`, `api_key_env`, `base_url` | Builds ai-sdk catalog. `base_url` rejects parse errors, userinfo, query, and fragment. | production-wired |
|
||||
| `agent.mode` | Default `nats` when containers enabled, otherwise `inprocess`; validates `inprocess`, `subprocess`, or `nats`. | production-wired |
|
||||
| `agent.command`, `agent.env` | Command defaults `archie-agent`; env entries must be nonblank names without `=`. | partially-wired |
|
||||
| `budgets.max_steps`, `max_tokens`, `wall_clock`, `gate_max_failures` | No loader defaults; `Budgets` documents zero as disabling. | production-wired |
|
||||
| `diff_cap_lines` | Zero replaced by `400` in `finalize`; `StageDiffCap` treats `<= 0` as disabled. TOML zero cannot disable; negative value does. | production-wired |
|
||||
| `web.listen` | Empty becomes `127.0.0.1:8484`; literal `off` disables. No authentication. | production-wired |
|
||||
| `notify.webhook` | Empty disables; feasibility workflow POSTs human-decision notifications when set. | production-wired |
|
||||
| `nats.url`, `token_env` | Empty URL keeps SQLite path. Configured token variable must be non-empty. | production-wired |
|
||||
| `containers.*` | See dedicated table below. | production-wired |
|
||||
| `chat.*` | See channel table below. | production-wired |
|
||||
| `memory.provider`, `provider_config`, `session_ttl` | Feature YAML decodes and tests these; `cmd/archied` always starts built-in file provider at `work_dir/memory`. | decoded-but-unwired |
|
||||
| `tools.mcp_servers` | `cmd/archied` registers daemon-side MCP providers. Empty transport becomes `stdio`; only `stdio` accepted. `url` decoded but unused. | 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 |
|
||||
| `indexing.index_dir`, `indexing.db_path` | `finalize` derives paths under `work_dir`; no entrypoint constructs `internal/indexing.Manager`. | decoded-but-unwired |
|
||||
| `extra` / unknown `conf.d` values | Test/library-only `LoadDir` stores untyped data; no core production consumer. | 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.
|
||||
response on stdout; `cmd/archie-agent` is a long-running NATS worker.
|
||||
|
||||
### 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 |
|
||||
| `owner`, `name` | Required for every declared repo. Single-identity config with zero repos loads but polls nothing. | production-wired |
|
||||
| `base` | `BaseBranch()` maps empty to `main`, but `daemon.process` pre-clones with raw `repo.Base`. Set it explicitly. | partially-wired |
|
||||
| `gate` | Argv arrays run in order. Empty entries skipped. TDD inverts last non-empty command as repro test by convention. | production-wired |
|
||||
| `protect` | Path suffixes enforced by agent runner; not prompt-only rule. | production-wired |
|
||||
| `ecosystem`, `preflight`, `test_glob` | Resolved preflight/test-glob treats empty ecosystem as Go. Container storage receives raw ecosystem. Go/Python/Node/Rust have defaults; `custom` or unknown yields none. | partially-wired |
|
||||
| `persistent_storage` | Controls Docker-backed per-repo volume setup; no equivalent without container storage. | partially-wired |
|
||||
| `max_retries` | Values greater than zero override global; zero or negative falls back to global. | production-wired |
|
||||
| `allow_concurrent` | Root repo entries affect dispatcher. `allowConcurrentFor` does not inspect identity repo lists. | partially-wired |
|
||||
|
||||
### Container settings
|
||||
|
||||
@@ -183,161 +147,88 @@ until an end-to-end test proves otherwise.
|
||||
| --- | --- |
|
||||
| `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`. |
|
||||
| `max_concurrency` | Zero means no limit; used by general task dispatcher and container pool. |
|
||||
| `max_uptime` | Default `60m` only when enabled; caps container lifetime. |
|
||||
| `volume_ttl` | Default `72h` only when enabled; negative rejected. |
|
||||
| `pull_policy` | Default `missing` when enabled. Pool code recognizes `missing` and `always`; other strings silently skip pre-pull. |
|
||||
| `network` | Empty uses best-effort self-network detection. 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.models` | Optional interactive catalog; empty falls back to workflow model references. |
|
||||
| `chat.telegram.token_env` | Empty disables Telegram; non-empty names env variable; 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.telegram.update_check_command`, `update_install_command` | Argv arrays; check enables update status; install further 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. |
|
||||
| `chat.webhook_addr` | Empty disables; malformed host/port falls back inside `parseListenAddr`. |
|
||||
|
||||
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.
|
||||
Telegram `/restart` re-runs same TOML overlay load, then replaces only gateway
|
||||
token and allowed-user list. Every other file setting is startup-only.
|
||||
|
||||
## 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.
|
||||
type, and `SecretRef` token. `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.
|
||||
- `cmd/archied` resolves root forge client before all identity runners.
|
||||
- Identity `name`, forge, repos, poll interval, bot user, bot email have
|
||||
production reads. Identity bot email not defaulted despite comment.
|
||||
- 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`.
|
||||
servers are root-forge/root-worktree.
|
||||
- Root-only concurrency lookup ignores identity repo `allow_concurrent`.
|
||||
|
||||
Classify multi-identity changes field by field. Never label the aggregate
|
||||
Classify multi-identity changes field by field. Never label 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,
|
||||
`Config.ForTask` creates a detached root snapshot: models, budgets, dispatch,
|
||||
diff cap, notification, and forge host. `TaskConfig.ToConfig` reconstructs
|
||||
only those fields. 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:
|
||||
At top-level `[forge]`, prefer `token = {engine = "env", key = "NAME"}`. Legacy
|
||||
`token_env = "NAME"` is converted only when structured reference is empty;
|
||||
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 explicit structured `token`.
|
||||
|
||||
| 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`. |
|
||||
| Forge `token = {engine="env", key="X"}` | Resolves `X`; empty is fatal. | Not forwarded. | Not forwarded; forge ops proxy to daemon. |
|
||||
| Provider `api_key_env = "X"` | Runtime reads `X`. | Auto-allowlists selected provider's `X`. | Daemon forwards each present provider variable under original name. |
|
||||
| `nats.token_env = "X"` | Reads `X`; empty fatal when configured. | Not agent subprocess setting. | Daemon maps 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. |
|
||||
| `agent.env = ["X"]` | Names validated. | Copies present `X` from daemon env. | 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.
|
||||
engine. Non-env `SecretRef` values are not production-wired.
|
||||
|
||||
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.
|
||||
`DEEPSEEK_API_KEY` into `archied`.
|
||||
|
||||
## 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
|
||||
## Follow the approved target
|
||||
|
||||
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.
|
||||
mutable `config.Config`. Treat this as a current load-bearing weakness, not a
|
||||
pattern to copy.
|
||||
|
||||
`docs/architecture/configuration.md` is approved as of 2026-07-28:
|
||||
|
||||
- move file/env/secret/overlay loading to a private
|
||||
- move file/env/secret/overlay loading to 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/architecture/configuration.md`
|
||||
- split `Repo` and `IdentityConfig` by actual capability ownership.
|
||||
@@ -5,79 +5,28 @@ description: Project-specific symptom-to-evidence triage for archie-core. Load t
|
||||
|
||||
# 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.
|
||||
**current** = 2026-07-28 verified; **fixed history** = regression patterns;
|
||||
**open** = verified gap.
|
||||
|
||||
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`.
|
||||
**Composition root**: `cmd/archied/main.go`. **Core NATS request/reply**: direct
|
||||
subject + reply inbox. **JetStream**: persisted stream `ARCHIE_TASKS`.
|
||||
**Environment failure**: test/process cannot use host resource (listener, tmp,
|
||||
Docker). **Code regression**: behavior fails where prerequisites available.
|
||||
|
||||
## 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:
|
||||
Do not begin with `task check` (mutates via `gofumpt -w .`/`go fix ./...`).
|
||||
Compile, then run:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-debug-gocache \
|
||||
GIT_CONFIG_GLOBAL=/dev/null go test ./PATH/TO/PACKAGE -run '^$' -count=1
|
||||
```
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-debug-gocache \
|
||||
GIT_CONFIG_GLOBAL=/dev/null go test ./PATH/TO/PACKAGE -run '^TestName$' -count=1 -v
|
||||
```
|
||||
|
||||
4. Run only the named test:
|
||||
Classify: compile-only, listener failure, read-only tmp, code regression.
|
||||
- Behavioral assertion with the prerequisite available: code regression.
|
||||
|
||||
```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:
|
||||
Use this symptom index:
|
||||
|
||||
| Symptom | First boundary | Go to |
|
||||
|---|---|---|
|
||||
@@ -96,54 +45,41 @@ Use this symptom index to select the detailed branch:
|
||||
| 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.
|
||||
sandboxes. Setting `GOTMPDIR=/tmp` and a task-specific `GOCACHE` is diagnostic
|
||||
isolation.
|
||||
|
||||
Listener-dependent tests include embedded NATS, `httptest.NewServer`, and SMTP
|
||||
listeners. Locate them:
|
||||
listeners:
|
||||
|
||||
```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
|
||||
Do not attribute 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:
|
||||
`commit.gpgsign=false`. 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.
|
||||
was accidentally committed. It is ignored now.
|
||||
|
||||
## Confirm the current known regression
|
||||
|
||||
As of 2026-07-28, this focused test fails in an otherwise runnable package:
|
||||
As of 2026-07-28:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-skillscript-gocache \
|
||||
@@ -151,189 +87,111 @@ env GOTMPDIR=/tmp GOCACHE=/tmp/archie-skillscript-gocache \
|
||||
-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`.
|
||||
Expected current failure: `Run() = "\n"`. The test constructs
|
||||
`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 from
|
||||
commit `308c199`, not proof that Yaegi cannot run external commands.
|
||||
|
||||
## 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` |
|
||||
| Full task handoff | `archie.taskrun.<task-id>` | Core request/reply; no-responder retry 20s every 250ms |
|
||||
| Store RPC | `archie.store.update`, `.transition` | Client timeout 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:
|
||||
| Worktree RPC | `archie.worktree.prepare`, `.push` | Server default handler bound 15m |
|
||||
| Discovery dedup | `Nats-Msg-Id: archie:<owner>/<repo>/<issue>` | JetStream duplicate window 2m |
|
||||
|
||||
```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`: container startup lag if responder appears within 20s;
|
||||
inspect agent's network/environment if every task exhausts window; confirm
|
||||
`registerTaskRPCServers` if only RPC calls time out.
|
||||
|
||||
Branch on `no responders`:
|
||||
**Fixed history:** auto-detection once put task containers on default bridge;
|
||||
explicit `containers.network` plus warning logs now fence that path.
|
||||
|
||||
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:
|
||||
Check semantics: republishing same owner/repo/issue within 2m is dedup'd; reply
|
||||
inbox auto-unsubscribes after one response; `Client.Fetch` must inspect
|
||||
`batch.Error()`; `agentexec.runStages` returns envelope and nil error for stage
|
||||
failure.
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-nats-unit-gocache \
|
||||
go test ./internal/nats \
|
||||
-run '^TestFetchPropagatesBatchError' -count=1 -v
|
||||
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
|
||||
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:
|
||||
Trace: `cmd/archied` reads `-config`/`-config-overlay` → `config.LoadOverlay`
|
||||
decodes, `finalize` defaults/validates → secrets resolve → composition root
|
||||
constructs service → Compose/subprocess/`containerEnv` propagate → consumer.
|
||||
|
||||
```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:
|
||||
`config.LoadDir` is test-only; a YAML field decoding correctly without
|
||||
composition-root read is a wiring gap, not a parser bug.
|
||||
|
||||
For environment failures:
|
||||
- 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.
|
||||
- `containerEnv` translates configured NATS token name into `NATS_TOKEN` 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.
|
||||
- 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.
|
||||
Do not print secret values.
|
||||
|
||||
## 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.
|
||||
Must drain `stream.FullStream`, collect `core.StreamPartTextDelta`, check
|
||||
`FinishReason`. `TextStream` is best-effort. **Fixed history:** consuming
|
||||
`TextStream` while `FullStream` unread deadlocked every reply.
|
||||
|
||||
### 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:
|
||||
Stdio framing is one compact JSON-RPC object per line. Stale
|
||||
`internal/tools/mcp/types.go` comment mentions `Content-Length` — not the
|
||||
implemented contract.
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-mcp-gocache \
|
||||
go test ./internal/tools/mcp \
|
||||
-run 'Test(ReadMessage|WriteMessage|StdioTransportBadFraming)' \
|
||||
-count=1 -v
|
||||
-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:
|
||||
Test helper and client share the same `readMessage`/`writeMessage` — can mirror
|
||||
mistakes. With `npx`:
|
||||
|
||||
```bash
|
||||
ARCHIE_TEST_DESKTOP_COMMANDER=1 \
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-mcp-integration-gocache \
|
||||
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`.
|
||||
Gate: non-empty discovery with `start_process`, `interact_with_process`,
|
||||
`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.
|
||||
Three command scopes in `internal/channels/telegram/commands.go`: default, all
|
||||
private chats, all group chats. Narrower scope shadows default; state keyed by
|
||||
bot token. Empty `allowed_user_ids` denies everyone.
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-telegram-gocache \
|
||||
@@ -342,132 +200,35 @@ env GOTMPDIR=/tmp GOCACHE=/tmp/archie-telegram-gocache \
|
||||
-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.
|
||||
**Fixed history:** publishing only default left ~60 old Hermes commands visible.
|
||||
|
||||
## Diagnose state, events, containers, and optional features
|
||||
|
||||
### NellDB and transitions
|
||||
`internal/nell.Adapter.Transition` writes `to`, ignores `from` and `detail`.
|
||||
When state is surprising: read `TaskByID` before/after caller; trace every
|
||||
`Transition`, `Requeue`, `RecoverStale`, `Update`.
|
||||
|
||||
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.
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-state-gocache go test ./internal/nell ./internal/store -count=1
|
||||
```
|
||||
|
||||
### 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.
|
||||
DB sink buffer 256; SSE client buffers 64. Drop counter not read in production.
|
||||
Dashboard gap can coexist with correct task state.
|
||||
|
||||
### 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.
|
||||
Container-mode: clones on host, mounts `/data/worktree`, writes `task.json`,
|
||||
dedicated `archie.taskrun.<id>` subscription. **Open:** container RPC is
|
||||
root-identity-bound; `SubprocessRunner` expects stdin JSON protocol.
|
||||
|
||||
### 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 |
|
||||
| Daemon plugins | Warn and skip |
|
||||
| Invalid MCP config | Warn and continue |
|
||||
| Skill catalog | Warn, continue without tool |
|
||||
| Worktree augmentation | Log error, use startup registry |
|
||||
| Workspace indexing | **Open:** 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
|
||||
```
|
||||
@@ -6,39 +6,13 @@ description: "Measure Archie codebase maintainability, Go package dependency sha
|
||||
# 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.
|
||||
output, state what each metric cannot prove.
|
||||
|
||||
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.
|
||||
Route to `archie-codebase-discovery` for semantic traces,
|
||||
`archie-config-and-flags` for config enumeration,
|
||||
`archie-debugging-playbook` for live failures.
|
||||
|
||||
## Define the measurement terms
|
||||
|
||||
@@ -46,23 +20,18 @@ Use reports to prioritize exact semantic traversal.
|
||||
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`.
|
||||
entrypoint. Principal: `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.
|
||||
blanks.
|
||||
- **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.
|
||||
non-default case, communication clause, `&&`, and `||` nodes.
|
||||
|
||||
## 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
|
||||
@@ -91,32 +60,10 @@ go run "$skill/scripts/config-use-candidates.go" -root . >"$evidence_dir/config.
|
||||
"$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
|
||||
```
|
||||
@@ -130,20 +77,9 @@ Read its tab-separated schema:
|
||||
| `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:
|
||||
The defaults (80 body lines, complexity 15) mirror numeric triage points in
|
||||
`.golangci.yml`. They do **not** implement `funlen` or `cyclop`. Run configured
|
||||
linters for authoritative findings:
|
||||
|
||||
```sh
|
||||
golangci-lint run --enable-only=funlen,gocognit,gocyclo,cyclop,maintidx,nestif ./internal/...
|
||||
@@ -154,8 +90,6 @@ 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"
|
||||
@@ -164,80 +98,38 @@ awk -F ' ' '$1=="PACKAGE" {print $3 "\t" $4 "\t" $2}' "$evidence_dir/packages-ro
|
||||
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/architecture/`.
|
||||
4. Route any boundary change through the architecture campaign.
|
||||
Read `PACKAGE package fan_in fan_out` and `EDGE from -> to` rows. High fan-in
|
||||
signals change risk; high fan-out signals orchestration. The report contains
|
||||
only direct, intra-module imports.
|
||||
|
||||
### 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:
|
||||
Read each `CONFIG_FIELD` row as path, line, Type.Field, tags, same-name
|
||||
definition count, config-package selectors, cmd selectors, other-production
|
||||
selectors, test selectors, generated selectors, candidate status. The report
|
||||
finds named fields with `toml`/`yaml`/`json` tags in `internal/config`, then
|
||||
counts selectors with the same **spelling**. It is deliberately fast and not
|
||||
type-aware.
|
||||
|
||||
```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.
|
||||
For every candidate: run `gopls references -d` on the exact field identifier;
|
||||
trace decode → default → validation → normalization/copy → composition-root read
|
||||
→ concrete component → observable behavior.
|
||||
|
||||
### 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.
|
||||
Read: `SURFACE axis scope literal_count` as literal text evidence;
|
||||
`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.
|
||||
|
||||
Inspect hygiene candidates directly:
|
||||
|
||||
@@ -247,65 +139,39 @@ git ls-files |
|
||||
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.
|
||||
On 2026-07-28, the focused `dupl` command reported zero issues. Two code paths
|
||||
can implement the same responsibility with different syntax.
|
||||
|
||||
For a duplicate or one-shot candidate:
|
||||
For every candidate: name the externally visible operation; search all
|
||||
entrypoints and modes; use `gopls call_hierarchy`, `gopls references -d`, and
|
||||
AST construction scan; check interfaces, registrations, reflection, build tags,
|
||||
OS files, and wire names; identify what a new feature supersedes; record
|
||||
production-only, test-only, compatibility, generated, and unreachable paths
|
||||
separately.
|
||||
|
||||
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.
|
||||
As of 2026-07-28, `Taskfile.yml` defines no `deadcode` task and `go tool` lists
|
||||
no dead-code analyzer.
|
||||
|
||||
## 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:
|
||||
As of 2026-07-28, the package reported 65.2% statement coverage and passed its
|
||||
race run.
|
||||
|
||||
```sh
|
||||
docker compose logs archied >"$evidence_dir/archied.log"
|
||||
@@ -313,32 +179,12 @@ 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.
|
||||
Run only when local Compose stack is in scope.
|
||||
|
||||
## 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:
|
||||
Predict exact deltas before changing code. Collect a second snapshot with the
|
||||
same script revision, flags, environment, and toolchain:
|
||||
|
||||
```sh
|
||||
after_dir=/tmp/archie-diagnostics-after
|
||||
@@ -354,31 +200,10 @@ 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.
|
||||
If output differs from prediction: confirm checkout, dirty state, script
|
||||
revision, flags, toolchain; explain each delta; branch to semantic discovery
|
||||
when a count cannot explain behavior. Reject a "better" metric that moved
|
||||
duplication, hid a path, or weakened a gate.
|
||||
|
||||
## Dated current snapshot
|
||||
|
||||
@@ -396,34 +221,9 @@ The bundled scripts measured this checkout on 2026-07-28:
|
||||
| `.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.
|
||||
or docs; no Go-gate literals in either workflow; docs build in GitHub CI;
|
||||
container build/push in Gitea CI.
|
||||
|
||||
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/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`
|
||||
failed on 2026-07-28 with `Run() = "\n"`.
|
||||
@@ -6,120 +6,78 @@ description: Maintain Archie's documentation of record and write durable archite
|
||||
# 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.
|
||||
from what Archie has approved as its destination.
|
||||
|
||||
## 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.
|
||||
Route to `archie-architecture-planning-campaign` for ownership/boundary
|
||||
decisions, `archie-architecture-contract` for invariants,
|
||||
`archie-codebase-discovery` for live entry points,
|
||||
`archie-failure-archaeology` for incidents,
|
||||
`archie-config-and-flags`, `archie-build-and-env`, or `archie-run-and-operate`
|
||||
for runtime/operations facts.
|
||||
|
||||
## 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:
|
||||
change a claim.
|
||||
|
||||
| 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 |
|
||||
| `CURRENT` | Verified behavior in checked-out code, tests, composition, or executable config | "Currently does" |
|
||||
| `APPROVED TARGET` | Normative destination approved in 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" |
|
||||
| `GENERATED` | Derivative output produced from owned source definition | "Generated from"; never hand-edit |
|
||||
| `EXTERNAL` | Fact held outside repository, such as deployed config or host state | Date, name verifier, give 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.
|
||||
migration delta.
|
||||
|
||||
## Use the repository authority map
|
||||
|
||||
Treat this as a volatile map verified on 2026-07-28:
|
||||
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/architecture/*.md` | Focused target decisions, active review procedure, and migration inventory | Read each file's status; distinguish fixed decisions from explicitly remaining decisions |
|
||||
| `docs/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/data/generated/contracts.json` | Current working-tree `GENERATED` output | Regenerate; never edit by hand; re-check whether it is tracked |
|
||||
| `docs/` | 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 |
|
||||
| Live Go code, tests, `Taskfile.yml`, executable config parsing, composition under `cmd/` | `CURRENT` execution evidence | Trace producers and consumers; tests prove only asserted behavior |
|
||||
| `CLAUDE.md` | Current contributor and safety protocol plus compact architecture orientation | Verify operational claims against code and `Taskfile.yml`; `AGENTS.md` is a symlink |
|
||||
| `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 target architecture | Add or change target decisions in the focused document it names |
|
||||
| `docs/architecture/*.md` | Focused target decisions, active review procedure, migration inventory | Read each file's status |
|
||||
| `docs/architecture/migration-decisions.md` | `OPEN` migration inventory constrained by approved decisions | Close a question only after code-grounded review |
|
||||
| `docs/archive/` | `HISTORICAL` material | Mine rationale and failure evidence |
|
||||
| `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 version headings |
|
||||
| `tools/docsgen` | Current, partial generator in nested `tools` Go module | Treat its flags and tests—not planned PRD commands—as executable truth |
|
||||
| `docs/data/generated/contracts.json` | Current working-tree `GENERATED` output | Regenerate; never edit by hand |
|
||||
| `docs/` | Staging VitePress site | Do not treat rendered summary as architecture record |
|
||||
| `.github/workflows/docs.yml` | Current Pages build/deploy workflow | Builds the site; does not 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/README.md` is excluded by VitePress and still contains copied
|
||||
Tau material; it is not a root onboarding guide.
|
||||
`docs/README.md` is excluded by VitePress and contains copied Tau material.
|
||||
|
||||
## Choose one destination
|
||||
|
||||
1. State the reader's question in one sentence.
|
||||
1. State the reader's question.
|
||||
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.
|
||||
5. If no owner exists, route the ownership decision through the architecture campaign.
|
||||
6. If the fact is generated, change the owned source definition and generator.
|
||||
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/architecture/*.md` file |
|
||||
| Unresolved migration question or cutover requirement | `docs/architecture/migration-decisions.md` |
|
||||
| Focused domain or requirement decision | Matching `docs/architecture/*.md` file |
|
||||
| Unresolved migration question | `docs/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/`, 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 |
|
||||
| User-facing staging site prose | `docs/`, linking back to authority |
|
||||
| Shipped release behavior | Matching component changelog; keep `CHANGELOG.md` as two-component index |
|
||||
| Superseded design retained for context | `docs/archive/`, with historical status |
|
||||
| Incident or rejected approach | `archie-failure-archaeology`'s 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
|
||||
```
|
||||
|
||||
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.
|
||||
Do not duplicate a package map across `CLAUDE.md`, `ARCHITECTURE.md`, a PRD, and
|
||||
the site. Name the authoritative map and link to it.
|
||||
|
||||
## Write for future change
|
||||
|
||||
@@ -131,38 +89,25 @@ Every architecture, feature, or migration record must answer:
|
||||
- **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?
|
||||
- **Invariants:** What must remain true, and where is each enforced?
|
||||
- **Superseded path:** Which older mechanism becomes redundant?
|
||||
- **Deletion gate:** What observable proof permits removal, and what temporary
|
||||
compatibility has an expiry condition?
|
||||
- **Deletion gate:** What observable proof permits removal?
|
||||
- **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?
|
||||
- **Unresolved questions:** What remains `OPEN`?
|
||||
|
||||
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.
|
||||
Name one owner for every mutable record. A new path is incomplete until the
|
||||
document says whether each older path remains, delegates, migrates, or is
|
||||
deleted.
|
||||
|
||||
## 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.
|
||||
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`.
|
||||
Distinguish evidence strength:
|
||||
|
||||
1. Runtime composition and executable behavior.
|
||||
@@ -176,46 +121,32 @@ Distinguish evidence strength:
|
||||
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.
|
||||
`internal/releaseannounce.changelogSection` parses a version heading.
|
||||
|
||||
Do not copy the current heading format without investigation. A verified
|
||||
2026-07-28 contradiction is `OPEN`:
|
||||
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.
|
||||
- `cmd/archied.TestChangelogsTrackGatewayAndRuntimeIndependently` 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.
|
||||
Resolve parser, release metadata tests, and both documents atomically; do not
|
||||
"fix" only the prose.
|
||||
|
||||
## Maintain generated contracts
|
||||
|
||||
The current implementation is smaller than the approved target in
|
||||
`docs/architecture/generated-documentation.md`.
|
||||
Current behavior, verified 2026-07-28:
|
||||
|
||||
### 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/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:
|
||||
- Tool path is `tools/docsgen`, not `tools/cmd/docsgen`.
|
||||
- Separate Go module replacing root module with `../`.
|
||||
- Accepts `--repo-root` and `--out`; no implemented `data`, `asyncapi`, `all`,
|
||||
or `check` subcommands.
|
||||
- `currentContractTypes` publishes three top-level contracts and collects
|
||||
referenced schemas into one JSON object.
|
||||
- Default output is `docs/data/generated/contracts.json`.
|
||||
|
||||
```bash
|
||||
GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools test ./docsgen -count=1
|
||||
@@ -224,62 +155,28 @@ GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools run ./docsgen --re
|
||||
cmp "$docs_tmp" docs/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.
|
||||
`APPROVED TARGET`.
|
||||
|
||||
## Maintain the VitePress staging site
|
||||
|
||||
Current behavior, verified 2026-07-28:
|
||||
|
||||
| Surface | Current state |
|
||||
|---|---|
|
||||
| Package | `docs/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/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 install --frozen-lockfile
|
||||
pnpm --dir docs build
|
||||
```
|
||||
|
||||
Use `build` for review evidence.
|
||||
|
||||
### Interactive authoring (not for automated acceptance)
|
||||
|
||||
```bash
|
||||
pnpm --dir docs 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/node_modules` symlink entries.
|
||||
Neither `docs/node_modules` nor `docs/.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:
|
||||
As of 2026-07-28, Git tracks 237 `docs/node_modules` symlink entries. Neither
|
||||
`docs/node_modules` nor `docs/.vitepress/dist` is ignored by root `.gitignore`.
|
||||
|
||||
```bash
|
||||
git ls-files -s 'docs/node_modules/**' | awk '$1 == 120000 { count++ } END { print count + 0 }'
|
||||
@@ -290,61 +187,3 @@ rg -n -i 'tau|template|placeholder' docs --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 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/architecture/*.md docs/archive/*.md
|
||||
```
|
||||
|
||||
```bash
|
||||
rg -n 'docsgen|docs:|pnpm|vitepress|CHANGELOG' Taskfile.yml .github/workflows/docs.yml tools/docsgen docs/package.json docs/.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/data/generated/contracts.json
|
||||
```
|
||||
|
||||
```bash
|
||||
git status --short -- docs tools docs/architecture/generated-documentation.md .github/workflows/docs.yml; git ls-files -s 'docs/node_modules/**' | awk '$1 == 120000 { count++ } END { print count + 0 }'
|
||||
```
|
||||
@@ -8,37 +8,19 @@ description: "Use when naming, designing, reviewing, documenting, tracing, or mi
|
||||
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
|
||||
As of 2026-07-28, Archie is between technical-package implementation and
|
||||
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. |
|
||||
| **CURRENT** | Behavior present in live code and tests | Cite defining type/function and production caller or test. |
|
||||
| **APPROVED TARGET** | Normative rule in approved foundation document | Cite exact PRD. Do not claim implemented. |
|
||||
| **OPEN/CANDIDATE** | Deferred API, owner, package, migration, or behavior | Preserve open question. |
|
||||
| **ARCHIVED** | Historical context under `docs/archive/` | Use only for archaeology. |
|
||||
|
||||
Start each design or review note with a status sentence:
|
||||
Start design notes with status sentences:
|
||||
|
||||
```text
|
||||
CURRENT: store.Task persists one mutable Stage string.
|
||||
@@ -46,84 +28,59 @@ 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:
|
||||
Read status markers:
|
||||
|
||||
```bash
|
||||
sed -n '1,180p' docs/prds/01-project-management.md
|
||||
rg -n '^\*\*Status:\*\*|^## Decisions still required|^## Remaining migration decisions' docs/architecture
|
||||
rg -n '^\*\*Status:\*\*|^## Decisions still required' docs/architecture
|
||||
```
|
||||
|
||||
`docs/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. |
|
||||
| **Identity** | Durable actor reference for ownership, attribution, routing, commands, events, audit. | **APPROVED TARGET:** `internal/domain/identity`. **CURRENT:** configured names and empty strings act as identifiers. |
|
||||
| **User** | Person represented as `user` kind of Identity. | **APPROVED TARGET:** Identity domain. |
|
||||
| **Agent** | Persistent assistant with acting IdentityID, specialization, instructions, capability context, memory. | **CONFIRMED TARGET:** Agent and Identity separate aggregates; `internal/domain/agent` confirmed in `migration-decisions.md`. |
|
||||
| **Model invocation** | One call through LLM provider/runtime. Replaceable execution machinery. | **CURRENT:** runtime packages. **TARGET:** infrastructure behind Agent-owned behavior. |
|
||||
| **System identity** | One permanent actor for startup, migration, supervision, rollback. | **APPROVED TARGET:** a real IdentityID. |
|
||||
|
||||
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:
|
||||
Apply: record acting Agent identity and initiating user identity separately;
|
||||
never authorize because two mutable strings match; never rename Agent when only
|
||||
model/provider/display name changes; never pool two Agents' memory.
|
||||
|
||||
```bash
|
||||
rg -n 'type IdentityConfig|type IdentityRunner|Identity string|BotUser string|identity == ""|Identity != identity' internal/config internal/daemon internal/store internal/gateway
|
||||
rg -n 'type IdentityConfig|type IdentityRunner|Identity string|BotUser string' 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. |
|
||||
| **Channel** | External interaction source (Telegram, email, webhook, forge). | **CURRENT:** `internal/channels` extends `gateway.Gateway`. **TARGET:** infrastructure adapter for Messaging. |
|
||||
| **Adapter** | Boundary code translating external payloads into owned contracts. | **TARGET RULE:** infrastructure implements domain-owned interfaces. |
|
||||
| **Gateway** | Current technical interface/router and package — not approved domain vocabulary. | **CURRENT ONLY:** `internal/gateway`, `internal/channels`. |
|
||||
| **ChannelBindingID** | Stable reference connecting Agent to channel binding. | **APPROVED TARGET INPUT:** part of Conversation identity. |
|
||||
| **Message** | Immutable application record with MessageID and typed content. Platform IDs are external correlations. | **TARGET:** Messaging. **CURRENT:** `gateway.Message`; richer `MessageEvent` exists beside it. |
|
||||
| **Conversation** | AgentID + UserIdentityID + ChannelBindingID + ExternalConversationID + ThreadID. | **CONFIRMED TARGET:** Messaging. **CURRENT:** `gateway.SessionSource` lacks canonical Agent/user IDs. |
|
||||
| **Conversation branch** | Child conversation from one immutable parent message. | **CONFIRMED TARGET.** No current implementation. |
|
||||
| **Work Intake** | Admission, validation, routing boundary between interaction and durable workflow-backed work. | **CONFIRMED TARGET:** `internal/domain/workintake`. Does not exist as current package. |
|
||||
| **Accepted work request** | Channel-neutral handoff after Work Intake accepts proposed outcome. | **TARGET HANDOFF:** Agent System consumes it, selects Workflow version, creates WorkflowExecution. |
|
||||
|
||||
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.
|
||||
Do not equate an inbound Message with work. An Agent may answer, use
|
||||
capabilities, retain information, or propose work without creating a
|
||||
WorkflowExecution.
|
||||
|
||||
Use this target flow:
|
||||
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
|
||||
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:
|
||||
Do not describe current `/spawn` as this target. It directly creates a
|
||||
`store.Task` with synthetic forge issue number.
|
||||
|
||||
```bash
|
||||
rg -n 'type Message struct|type MessageEvent struct|ToLegacy|type SessionSource|CreateTask|EnqueueChatTask|synthetic' internal/gateway internal/store cmd/archied
|
||||
@@ -133,34 +90,20 @@ rg -n 'type Message struct|type MessageEvent struct|ToLegacy|type SessionSource|
|
||||
|
||||
| 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. |
|
||||
| **Workflow** | Reusable, versioned definition. | `workflow.Workflow` is named `[]Stage` without durable version model. |
|
||||
| **WorkflowExecution** | One durable execution of one Workflow version. | `store.Task` is migration baseline. |
|
||||
| **WorkflowStep** | One defined operation. | `workflow.Stage` is closest definition. |
|
||||
| **StepExecution** | Durable record of one step's execution and outcome. | Missing; `store.Task.Stage` is one mutable string. |
|
||||
| **Attempt** | Retry within same WorkflowExecution. | `Task.Attempt`/`RetryCount` must become explicit attempt history. |
|
||||
| **Agent step execution** | One bounded model-backed WorkflowStep invocation. | `agentexec.Request`/`Result` correlate TaskID, Attempt, Stage, protocol version. |
|
||||
|
||||
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/architecture
|
||||
```
|
||||
Use `WorkflowExecution` in domain contracts, architecture, generated reference.
|
||||
Retain `task` only for Task build tool, forge product nouns in adapters,
|
||||
informal prose.
|
||||
|
||||
### Interpret the current lifecycle exactly
|
||||
|
||||
These are **CURRENT** `store.Task` states, not proof of an implemented target
|
||||
state machine:
|
||||
**CURRENT** `store.Task` states:
|
||||
|
||||
```text
|
||||
queued -> running
|
||||
@@ -171,47 +114,29 @@ 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:
|
||||
Do not claim enforced. `Store.Transition` writes new status without comparing
|
||||
`from`, inserts history separately. `internal/gateway/tasks.go` duplicates
|
||||
status strings locally.
|
||||
|
||||
```bash
|
||||
rg -n 'Status[A-Za-z]+|status[A-Za-z]+|func \(s \*Store\) Transition|func \(s \*Store\) Requeue|RecoverStale' internal/store internal/gateway
|
||||
rg -n '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. |
|
||||
| **Global shared** | Intentionally visible across Archie. |
|
||||
| **Agent-wide** | Owned by one Agent, private by default even across users. |
|
||||
| **User-wide** | One user across authorized Agents. |
|
||||
| **Agent-user relationship** | Addressed by both AgentID and User IdentityID. |
|
||||
|
||||
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.
|
||||
Conversation branch is not a fifth memory scope. Scope mechanics **OPEN** beyond
|
||||
these constraints.
|
||||
|
||||
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:
|
||||
Current `MemoryProvider` initializes with session ID, contains no explicit
|
||||
AgentID, User IdentityID, or scope parameter. Built-in provider separates
|
||||
`MEMORY.md` and `USER.md` under one directory — not the four-scope target model.
|
||||
|
||||
```bash
|
||||
rg -n 'type MemoryProvider|Initialize\(|type Config struct|MEMORY.md|USER.md|AgentID|IdentityID|Scope' internal/memory
|
||||
@@ -221,18 +146,12 @@ rg -n 'type MemoryProvider|Initialize\(|type Config struct|MEMORY.md|USER.md|Age
|
||||
|
||||
| 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. |
|
||||
| **Plugin** | Removable module with identity, metadata, compatibility, lifecycle. Generic `plugin.Plugin` must remain metadata-only. |
|
||||
| **Capability family** | One cohesive typed behavior owned by its domain or approved manager/registry. |
|
||||
| **Engine** | Typed, lifecycle-managed capability family with owning Registry or Manager. |
|
||||
| **Host** | Current cross-family lifecycle/manifest coordinator in `internal/plugin`. Must not become 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:
|
||||
Give plugin only narrow typed registrars and explicitly supplied contracts.
|
||||
|
||||
```bash
|
||||
go test ./internal/plugin -run 'Test(GenericPluginContractRemainsMetadataOnly|EveryEngineInterfaceHasTypedCapabilityAndFamilyOwner)' -count=1
|
||||
@@ -242,20 +161,17 @@ go test ./internal/plugin -run 'Test(GenericPluginContractRemainsMetadataOnly|Ev
|
||||
|
||||
| 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`. |
|
||||
| **Domain** | Own one cohesive responsibility: vocabulary, state, rules, operations, commands, events, policies, runtime settings, required service contracts. |
|
||||
| **Command** | Request an action. Receiving domain owns contract and decides result. |
|
||||
| **Domain event** | Record something that happened. Publishing domain owns schema. |
|
||||
| **Event bus** | Broker-neutral delivery/lifecycle contract. `internal/eventbus` is approved target, not current. |
|
||||
| **Observability event** | `internal/events.Event` projection input. Bounded in-process bus may drop. Not authoritative state. |
|
||||
| **Policy** | Typed rule evaluated through shared mechanics. Consuming domain owns vocabulary. |
|
||||
| **Infrastructure** | Implements domain-owned ports, translates DBs, brokers, SDKs, files, containers. |
|
||||
| **Application composition** | Chooses implementations, translates config, connects contracts, orders startup/shutdown. Target: `internal/app`; current wiring 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:
|
||||
As of 2026-07-28, `internal/domain`, `internal/eventbus`, `internal/policy`,
|
||||
`internal/infrastructure`, `internal/app` do not exist. Target paths only.
|
||||
|
||||
```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
|
||||
@@ -265,116 +181,55 @@ for p in internal/domain internal/eventbus internal/policy internal/infrastructu
|
||||
|
||||
| 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. |
|
||||
| **Forge** | External code-host ops: issues, comments, labels, PRs, reactions. | Workflow lifecycle, canonical identity, work admission. |
|
||||
| **Repository** | External source repo identity and repo-specific policy. | Mutable execution workspace or WorkflowExecution identity. |
|
||||
| **Worktree/workspace** | Isolated files, branch, diff, commit, push, cleanup for one execution. | Agent/domain identity or forge issue lifecycle. |
|
||||
| **Gate** | Deterministic evidence and constraints over execution. | Prompt advice model may waive. |
|
||||
| **Agent execution boundary** | Versioned, validated data entering/leaving one unprivileged stage. | Daemon internals, forge tokens, direct git, 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
|
||||
```
|
||||
Model never runs git directly. Worktree operations are daemon-owned.
|
||||
|
||||
## 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. |
|
||||
| `config.IdentityConfig.Name` | Canonical IdentityID plus separate bindings | Do not preserve mutable display name as ID. |
|
||||
| `config.IdentityConfig.BotUser` | Forge/Git or channel external binding | Not Conversation or Agent identity. |
|
||||
| `daemon.IdentityRunner` | Composition of identity-correlated capabilities | Currently service bundle, not Identity aggregate. |
|
||||
| `gateway.Message`, `MessageEvent` | Canonical Messaging Message | Choose one immutable typed contract. |
|
||||
| `gateway.SessionContext` | Conversation metadata | Add canonical Agent/user/binding ownership. |
|
||||
| forge `Issue` or future Jira item | Channel message or external artifact | Preserve native reference in adapter. |
|
||||
| gateway `/spawn` and `TaskCreator` | Proposed/accepted work handoff | Work Intake admits; Agent System creates execution. |
|
||||
| `store.Task` | WorkflowExecution | Preserve every field intentionally. |
|
||||
| `workflow.Workflow` | Versioned Workflow definition | Add identity/version ownership before 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. |
|
||||
| `workflow.TaskContext` | Execution state plus narrow step ports | Remove global config/service bag. |
|
||||
| `events.Event` and `Bus` | Projections fed by authoritative domain events | Current drops acceptable for observability, not state. |
|
||||
| `cmd/archied` wiring | `internal/app/archied` composition | Keep `cmd/*` process-input-only. |
|
||||
| NATS/RPC/store/forge/worktree | Infrastructure adapters | Process boundaries don't 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.
|
||||
`migration-decisions.md` leaves memory, tools, workspaces, gates, storage,
|
||||
events, web UI, containers, RPC, release management, scheduling pending.
|
||||
|
||||
## 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. |
|
||||
| "A forge issue is a Task" | Chat needs synthetic issues; uniqueness/dedup stay forge-shaped. |
|
||||
| "Agent and Identity are same config object" | Model/persona changes alter attribution; mutable string equality becomes access control. |
|
||||
| "Every Message is work" | Conversational turns forced through durable workflow lifecycle. |
|
||||
| "Accepted request is already a WorkflowExecution" | Intake bypasses version selection and constructs invalid state. |
|
||||
| "Stage is StepExecution" | Overwriting one string destroys step outcomes and audit history. |
|
||||
| "NATS retry is another Attempt" | Transport availability changes domain retry counts. |
|
||||
| "Event bus owns events" | Broker subjects become domain vocabulary; meaning drifts by consumer. |
|
||||
| "Branch is a memory scope" | Returning to parent hides/duplicates durable learning. |
|
||||
| "Engine means another generic plugin hook" | Capability ownership becomes untyped; plugins gain service-locator access. |
|
||||
| "Configuration owns the feature" | Cross-concern config becomes de facto domain. |
|
||||
|
||||
## 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/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/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
|
||||
```
|
||||
Reject in review: a second parallel model without bounded cutover; status string
|
||||
copied into consumer; mutable display name as durable ID; service bag passed
|
||||
into domain/plugin/WorkflowStep; lifecycle state written by adapter/UI/transport;
|
||||
domain importing concrete persistence/NATS/forge SDK/container/config DTO types;
|
||||
test proving only new path while old production path remains active.
|
||||
@@ -6,51 +6,31 @@ description: "Reconstruct archie-core failures, dead ends, reversals, rejected f
|
||||
# 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.
|
||||
happened from 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.
|
||||
All volatile observations are dated **2026-07-28**.
|
||||
|
||||
## 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`.
|
||||
Route to `archie-debugging-playbook` for active symptoms,
|
||||
`archie-codebase-discovery` for deep caller tracing.
|
||||
|
||||
## Use the status taxonomy exactly
|
||||
|
||||
| Status | Meaning |
|
||||
|---|---|
|
||||
| `settled` (`fixed`) | The failure, cause, resolution, and live replacement are proven. Preserve the resulting rule. |
|
||||
| `settled` (`fixed`) | The failure, cause, resolution, and live replacement are proven. |
|
||||
| `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. |
|
||||
| `open` | The defect is evidenced, but no accepted and integrated resolution. |
|
||||
| `conditional` | A fix is proven only for the named configuration, execution mode, peer, or assembly. |
|
||||
| `superseded` | A mechanism was intentionally replaced. |
|
||||
| `candidate` | A branch, proposal, or partial implementation may help but is not accepted. |
|
||||
|
||||
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.
|
||||
Never use `settled` to mean "a fix commit exists."
|
||||
|
||||
## Run the archaeology workflow
|
||||
|
||||
### 1. Freeze the observation point
|
||||
|
||||
Run only read-only git commands:
|
||||
|
||||
```sh
|
||||
git rev-parse HEAD
|
||||
git status --short
|
||||
@@ -58,20 +38,11 @@ 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.
|
||||
Capture: first wrong observable result; last confirmed-good boundary; process
|
||||
mode; active config and deployment assembly; whether deterministic,
|
||||
load-dependent, or production-only.
|
||||
|
||||
### 3. Trace current behavior before history
|
||||
|
||||
@@ -81,10 +52,6 @@ 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
|
||||
@@ -94,7 +61,7 @@ git merge-base --is-ancestor <commit> HEAD
|
||||
git branch -a --contains <commit>
|
||||
```
|
||||
|
||||
Read the parent version when the failure is semantic:
|
||||
Read parent version when failure is semantic:
|
||||
|
||||
```sh
|
||||
git show <commit>^:<path>
|
||||
@@ -114,15 +81,11 @@ Require all six fields in an incident packet:
|
||||
|
||||
### 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`.
|
||||
If current behavior differs from chronicle, update the packet.
|
||||
|
||||
## Match symptoms to known incidents
|
||||
|
||||
@@ -130,99 +93,94 @@ forcing the symptom into an old story. Route a proposed correction through
|
||||
|---|---|
|
||||
| `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 |
|
||||
| Stream shows empty cursor or first token, then hangs | FullStream/TextStream incident |
|
||||
| MCP unit tests pass but real SDK server hangs | MCP framing and mirrored-peer incident |
|
||||
| Telegram shows old commands after menu update | Telegram server-side scope incident |
|
||||
| Tool discovery deadlocks, aliases mutate, or bad plugin hides rest | Tool-registry adversarial findings |
|
||||
| Hidden `<memory>` content appears at end of truncated stream | Scrubber `Flush` leak |
|
||||
| Broad lint cleanup compiles poorly while tests pass | Autofix, `nilerr`, and `308c199` incidents |
|
||||
| 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 |
|
||||
| Build caches or dependency trees appear in 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 |
|
||||
| Incident and date | Symptom | 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. |
|
||||
| Label auto-claim, 2026-07-22 | >80 labelled issues enrolled under label polling. | Label polling means eligibility, not hint. | `519882f` changes `config.docker.toml` to `assignee`. `internal/config/config.go` defaults to `assignee` but permits `label` and `either`. **Status:** `settled`. | Default to assignee-driven pickup. Label/either are deliberate bulk enrollment. |
|
||||
| Baseline-red park storm, 2026-07-23 onward | Task parks on gate failure that existed before its feature work. | Parking/retrying cannot change pre-existing failure; auto-repair mixes repository repair into feature scope. | `b2482af` made `StageBaselineGate` launch builder instead of parking. Nine repair commits in history. **Status:** `current` mitigation and architecture weak point. | Measure untouched baseline first. Track baseline repair as explicit change. |
|
||||
| Passed build with zero changes, 2026-07-23 | Commit-push reports "no changes," parks, retries, repeats. | "Passed with no changes" lacked terminal domain outcome. | `62c0df1` introduced no-op detection; `2bf42bd` set `Outcome`. `TestStageCommitPushClosesIssueWhenBuildNoChanges`. **Status:** `settled`. | Model no-op as explicit terminal result. |
|
||||
| Infinite parked-task retry, 2026-07-23 | Removing parked label repeatedly requeues with no terminal bound. | Retry count not durable or capped. | `a8fdb50` added persisted `retry_count`, global/per-repo `max_retries`, and `dead`. **Status:** `settled`. | Every autonomous retry needs durable attempt state, explicit bound, terminal state, and operator-visible reason. |
|
||||
|
||||
## Chronicle: runtime and peer contracts
|
||||
|
||||
| Incident and date | Symptom | Attempted solution and root cause | Evidence and status | Settled rule |
|
||||
| Incident and date | Symptom | 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. |
|
||||
| Container network auto-detection, 2026-07-27 | Every container task returns `nats: no responders`. | `selfNetwork` inspected hostnamed container, silently fell back to default bridge. | `37cf089` records incident, adds `containers.network`; `2ac306b` pins `archie-core_default`. **Status:** `conditional`. | Make cross-container network membership explicit in deployment. |
|
||||
| SecretRef schema crash-loop, 2026-07-27 and current `HEAD` | Both identities demand `ARCHIE_GITHUB_TOKEN` despite Gitea config. | Removing old `token_env` field let TOML ignore deployed value. `1f8588d` restored precedence-compatible fallback; `308c199` removed `Forge.TokenEnv` declaration while `finalize` still references it. **Status:** `open` regression at `HEAD`. | Preserve decoded compatibility until deployed files migrated and rejection of stale keys observable. |
|
||||
| Compose secret omission, 2026-07-27 | Config names valid env var, container sees it empty. | Compose forwards only listed environment entries. | `22fc0ef`, `d0624b7`. **Status:** `conditional`. | Trace every secret from config key to host value to Compose passthrough to process lookup. |
|
||||
| FullStream/TextStream deadlock, 2026-07-27 | Streamed Telegram reply renders empty cursor, typing never clears. | ai-sdk makes `FullStream` authoritative and backpressured; `TextStream` is best-effort. | `6a0bd27`. **Status:** `settled` with regression-test gap. | Drain authoritative stream through close. |
|
||||
| MCP Content-Length framing and mirrored fake, 2026-07-26 to 2026-07-27 | Internal MCP tests pass while official-SDK servers do not. | MCP stdio uses newline-delimited JSON. Test subprocess called same helpers, mirroring the same wrong protocol. | Compare `f2768eb:internal/tools/mcp/framing.go` with `dda4cde`. **Status:** `settled`. | For wire contracts, test raw canonical frames and independently implemented peer. |
|
||||
| Telegram command scopes persist by bot token, 2026-07-27 | Startup reports eight commands published, DMs show ~60 old Hermes commands. | Telegram chooses most specific scope; older scopes survive redeploys. | `cec0f3e` adds menu and deny-by-default; `576c7f5` publishes all three scopes. **Status:** `settled`. | Inventory and overwrite every relevant server-side scope. |
|
||||
| NATS fetch error looked like empty queue, 2026-07-27 | Consumer receives zero messages, treats JetStream failure as "no work." | Batch error state not checked after channel closed. | `0d09a2e` repro; `78a9145` merged through `21ceef0`. **Status:** `settled`. | Check terminal iterator/batch error state even when data channel is empty. |
|
||||
|
||||
## 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. |
|
||||
| Incident and date | Symptom | Root cause | Status |
|
||||
|---|---|---|---|
|
||||
| Tool registry passed first implementation but held eight defects, 2026-07-26 | Availability can deadlock; schemas mutate after registration; discovery stops at first bad source; literal extraction wrong. | Callbacks ran under `RLock`, copies shallow/shared, parsing partial, matching broad, discovery fail-fast. | `9f6c36c` lists all eight fixes. **Settled.** Never call extension code under registry lock. Clone nested data. Parse complete grammar. Isolate discovery failures. |
|
||||
| Memory scrubber `Flush` leak, 2026-07-26 | Stream ending inside `...secret</mem` emits buffered hidden memory to visible response. | Pending bytes did not retain whether captured inside `<memory>` block. | `b4aaaf0`. **Settled.** Test every streaming state at EOF. Flush is security boundary. |
|
||||
| Linter autofix shadowing, 2026-07-28 | 24-file "style" pass stops compiling. | `gocritic` changed `ctx, cancel = context.WithTimeout(...)` to `:=` inside conditional, shadowing context. | `9b44bac`. **Settled.** Treat autofix output as authored behavior. |
|
||||
| All eleven `nilerr` findings semantic false positives, 2026-07-28 | Mechanical "fixes" would return Go errors while tests pass, breaking model correction, chat, NATS envelopes, clean shutdown, indexing. | Linter cannot see failures carried as text, envelopes, shutdown signals, or skipped entries. | `86cfc19`. **Settled.** Review semantic channels one site at a time. |
|
||||
| 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`. | Local `replace` paths don't exist in CI/build contexts. | `07fb291` removes replace. **Settled.** Never commit machine-local `replace` directives. |
|
||||
| Broad checkpoint hid unresolved merge conflict, 2026-07-27 | Literal conflict marker reached committed source. | Unrelated surfaces combined without whole-diff conflict scan. | `4429ae5`. **Settled.** Keep commits cohesive. |
|
||||
|
||||
### 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? |
|
||||
| `Available` evaluated `CheckFn` under `RLock` | Can a callback re-enter or block while lock is held? |
|
||||
| `Register` stored caller references | Can 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? |
|
||||
| `intLit` omitted negative/hex/octal/binary forms | Are all supported numeric forms handled or rejected? |
|
||||
| `Discover` aborted on 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? |
|
||||
| `schemaLit` accepted only string values | Are booleans, integers, arrays, 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 |
|
||||
| Step and date | Symptom | Root cause | 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. |
|
||||
| Existing worktree skipped, 2026-07-23 | `Prepare` returned when `.git` existed. | Existence did not prove freshness or completed preparation. Later replaced `.git` readiness with sentinel. | Define completed-state marker and revalidate remote/base/branch state on reuse. |
|
||||
| Sentinel outside `.git`, 2026-07-24 | `.archie-prepared` marked setup; go-git `Add(All)` doesn't honor exclude. | Orchestration metadata needs to be outside tracked worktree by construction. | Put sentinel at `.git/archie-prepared`. |
|
||||
| Askpass rewritten each call, 2026-07-24 | Token-emitting shell script rewritten for every git command. | Comment wasn't invariant; no test checked mtime. Later removed shell git and askpass entirely. | Prefer in-process credentials. |
|
||||
| Bare object cache, 2026-07-24 | `--reference-if-able --dissociate` plus TTL to accelerate clones. | go-git has no `--dissociate` equivalent; expiring cache would corrupt active worktrees. | Never accept clone acceleration making task correctness depend on expiring cache. |
|
||||
| Shell git replaced by go-git, 2026-07-28 | Port exposed host GPG inheritance, sentinel tracking, merge-base diff semantics. | RPC handlers used `context.Background`, making in-process clones unbounded. | Audit every adapter and cancellation boundary after replacing killable subprocess with in-process I/O. |
|
||||
|
||||
## Chronicle: cleanup, artifacts, and contradictory policy
|
||||
|
||||
| Incident and date | Symptom | Attempted solution and root cause | Evidence and status | Settled rule |
|
||||
| Incident and date | Symptom | Root cause | 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/node_modules`, 2026-07-28 | Hundreds of pnpm symlink entries become repository content. | **Attempt:** broad `308c199` cleanup/documentation commit. **Cause:** `docs/node_modules` was neither ignored nor excluded from the commit. | `git ls-files 'docs/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. |
|
||||
| Tracked `.gotmp`, 2026-07-27 | Build-cache binaries, generated `_testmain.go`, `.git-askpass` appear in commits. | Workaround path not ignored before use. | `4cb0577` removes artifacts and adds `.gotmp/` to `.gitignore`. **Settled.** | Put caches outside repo or ignore before first command. |
|
||||
| Tracked `docs/node_modules`, 2026-07-28 | Hundreds of pnpm symlink entries become repository content. | `docs/node_modules` neither ignored nor excluded from commit. | 237 entries at `HEAD`; no `.gitignore` rule. **Current/open.** | Track lockfiles, never installed trees. |
|
||||
| `308c199` cleanup regression, 2026-07-28 | `TestRunWrapsExternalCommand` returns `"\n"` instead of `"wrapped\n"`; forge compatibility removed again; dependency artifacts added. | Semantic edits classified and reviewed as cleanup. | Focused skillscript test fails at `HEAD`. **Current/open.** | No commit is "cleanup" for gating purposes. |
|
||||
| `diff_cap_lines = 0` contradiction, introduced at project start | Operators set zero expecting unlimited, but decoded config becomes 400. | `finalize` converts zero to default 400; same sentinel means both "unset" and "unlimited." | **Current/open** contradiction. | Never overload zero value with both defaulting and explicit policy. |
|
||||
|
||||
## 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.
|
||||
As of **2026-07-28**, these remote branches are not merged:
|
||||
|
||||
| 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. |
|
||||
| Candidate branch | Claimed concern |
|
||||
|---|---|
|
||||
| `origin/fix/43-loaddir-no-timeout-around-yaegi-eval-can-hang-daemon-startup` | Bound Yaegi evaluation during `LoadDir` |
|
||||
| `origin/fix/45-skillscriptrun-ignores-context-cannot-be-canceledtimed-out` | Make skill scripts cancellable |
|
||||
| `origin/fix/48-transition-ignores-from-status-guard-allowing-lost-updates` | Enforce expected source state atomically |
|
||||
| `origin/fix/52-handlesse-silently-swallows-eventssince-backlog-fetch-errors` | Surface SSE backlog query errors |
|
||||
| `origin/feat/51-no-test-coverage-for-stagestats-query` | Add `StageStats` query coverage |
|
||||
| `origin/feat/75-add-mcp-client-capabilities-to-archied-and-archie-agent` | Wire MCP through both execution modes |
|
||||
|
||||
Verify candidate state:
|
||||
|
||||
@@ -232,38 +190,3 @@ 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/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`
|
||||
@@ -13,76 +13,45 @@ description: >-
|
||||
|
||||
# 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.
|
||||
Treat Archie's database as domain state behind an application adapter.
|
||||
|
||||
## 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.
|
||||
Stop for architecture planning when the change defines atomic
|
||||
state-plus-event persistence or WorkflowExecution storage — OPEN decisions.
|
||||
|
||||
## 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`. |
|
||||
| `store.TaskStore` | Archie's 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. |
|
||||
| `sdk.DocDB` | NellDB's document adapter over one named collection. Maps `sdk.Doc` values to engine records. |
|
||||
| Collection | A namespace in the engine. Engine key is `collection + ":" + record ID`. |
|
||||
| Document ID | The application key stored in reserved field `_id`; distinct from `store.Task.ID`. |
|
||||
| Revision (`_rev`) | SDK MVCC token of form `<generation>-<sha1>`. Detects stale local document writes. |
|
||||
| HLC | NellDB's hybrid logical clock: Unix milliseconds plus logical counter. |
|
||||
| Node ID | Writer string stamped into `UpdatedBy`. Archie passes `cfg.BotUser`. |
|
||||
| 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. |
|
||||
| Tombstone | Record with `Deleted=true`. Normal `Get`/`List` hides it; remains in append-only log until compaction. |
|
||||
|
||||
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
|
||||
```
|
||||
Verified **2026-07-28**: `config.LoadOverlay` → `cfg.DBPath`/`cfg.BotUser` →
|
||||
`nell.OpenStore` → `logstore.OpenLog` → one Store with `"tasks"`, `"events"`,
|
||||
and optionally `"sessions"`/`"messages"` DocDBs.
|
||||
|
||||
| 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. |
|
||||
| `cmd/archied/main.go` unconditionally opens `nell.OpenStore(cfg.DBPath, cfg.BotUser)`. | `cmd/archied/main.go` | NellDB is the production task/event backend. No runtime backend selector. |
|
||||
| `internal/store.Store` still implements `TaskStore` using SQLite. | `internal/store/{interface,store,events}.go` | SQLite remains a test/legacy implementation. |
|
||||
| The same engine is lent to `gateway.NewSessionStore` only inside Telegram wiring. | `cmd/archied/main.go`; `internal/gateway/session_store.go` | 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 against published v0.2.5 source. |
|
||||
| Archie does not call NellDB replication, compaction, changes-feed, or vector-search APIs. | No production matches | Do not claim those engine features are active. |
|
||||
|
||||
Verify the dependency without network access:
|
||||
Verify dependency:
|
||||
|
||||
```bash
|
||||
go list -m -f '{{.Path}} {{.Version}}{{if .Replace}} => {{.Replace.Path}} {{.Replace.Version}}{{end}}' github.com/samcharles93/NellDB
|
||||
@@ -90,34 +59,26 @@ 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.
|
||||
Expected: `github.com/samcharles93/NellDB v0.2.5`. If a `=> /local/path` suffix
|
||||
appears, stop. Commit `07fb291` removed exactly that failure mode.
|
||||
|
||||
## 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. |
|
||||
| Concurrency | `MemoryStore`, `LogStore`, and `DocDB` protect individual calls with mutexes. | `Adapter.mu` serializes selected multi-call operations in one adapter instance only. |
|
||||
| Document conflicts | Stale `_rev` to `DocDB.Put` returns `sdk.ErrConflict`. | Adapter helpers usually re-read before `Put`; can avoid conflict while copying stale application fields. |
|
||||
| Cross-node conflict | Engine `Put` applies HLC LWW, then lexical `UpdatedBy` tie-break. | No Archie replication path is wired. |
|
||||
| Persistence | Default `OpenLog` appends a frame and flushes buffered writer on each write. Close flushes again. | Archie defers one adapter close. No checkpoint, snapshot, or compaction service wired. |
|
||||
| Crash behavior | Replay rebuilds in-memory index. 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. |
|
||||
| Deletes | `Remove` writes a tombstone; ordinary list/get hide it. | `ClearTerminalTasks` tombstones terminal task documents. File space not reclaimed (no compaction). |
|
||||
| Queries | Engine indexes collection membership and HLC changes. `Query` is a collection-list stub. | Adapter performs field queries by collection scans. Gateway message search uses substring matching. |
|
||||
| Listing | `AllDocs` returns a snapshot filtered after `Store.List`; range results not sorted by key. | Task/event methods sort when contract needs it. Session/message code assumes ordering where SDK does not guarantee it. |
|
||||
| Node identity | Records retain their `UpdatedBy`; conflict resolution uses it. | `LogStore.NodeID()` returns value passed to 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`.
|
||||
Do not open the same log file from multiple processes or adapter instances.
|
||||
No cross-process lock or supported multi-writer assembly is proven.
|
||||
|
||||
## Know the stored shapes
|
||||
|
||||
@@ -125,19 +86,17 @@ multi-writer assembly is proven in Archie or the pinned `LogStore`.
|
||||
|
||||
| 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 |
|
||||
| `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, stats |
|
||||
| `events` | `event:<numeric-id>` | `events.Event`; `data` stored as JSON string | Full scan, application filter, 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.
|
||||
`meta:task_id_counter` and `meta:event_id_counter`. Adapters skip `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.
|
||||
Do not create an application ID beginning with `meta:`. `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 as CURRENT risk.
|
||||
|
||||
### Task document mapping
|
||||
|
||||
@@ -148,66 +107,46 @@ it. Treat this as a CURRENT risk requiring a failing test before repair.
|
||||
| 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:
|
||||
|
||||
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.
|
||||
`int`, and `json.Number`.
|
||||
- Treat missing `source` as `forge`; `sourceOrDefault` preserves old documents.
|
||||
- Preserve `_id` and `_rev` by starting updates from `DocDB.Get`.
|
||||
- Keep workflow `Update` restricted to its documented mutable subset.
|
||||
|
||||
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.
|
||||
into the Nell document. Forge tasks read back with empty identity.
|
||||
`EnqueueChatTask` does write both `source=chat` and `identity`.
|
||||
|
||||
### 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.
|
||||
`InsertEvent` stores: `id, at, kind, task_id, repo, issue, workflow, stage,
|
||||
detail, data`. Clips `detail` to 4000 bytes without splitting UTF-8 rune.
|
||||
Serializes `data` to JSON string; substitutes `marshal_error` on failure.
|
||||
`docToEvent` ignores invalid timestamps and invalid `data` JSON.
|
||||
|
||||
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.
|
||||
`Transition` ignores `detail`, and the event sink writes asynchronously.
|
||||
|
||||
## 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. |
|
||||
| `ClaimNext`, `ClaimByIssue` | Scan/get + write under `Adapter.mu` | Atomic only with same mutex on same instance. |
|
||||
| Task/event ID allocation | Counter RMW under `Adapter.mu` | Enqueue duplicate check outside critical section. |
|
||||
| `RecoverStale`, `ClearTerminalTasks` | Full scan + writes under `Adapter.mu` | `Transition`, `Update`, `Requeue` do not take mutex. |
|
||||
| `Transition` | Find by ID, set `Status`, put | Ignores `from`/`detail`; writes no transition record; no lock. |
|
||||
| `Requeue` | Find, mutate fields, put | Ignores `fromStatus`; writes no transition record; no lock. |
|
||||
| `Update` | Get by key, replace allowed fields, put | One doc write, no domain state/event transaction. |
|
||||
| `IncrementRetryCount` | Find, increment, put | Multi-call RMW without adapter lock. |
|
||||
| `InsertEvent` | ID allocation + put under `Adapter.mu` | Separate from state mutation that caused 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.
|
||||
`Transition` does not make a state machine. Target must compare expected
|
||||
state/version, enforce legal transitions, commit state with domain event at one
|
||||
atomic boundary.
|
||||
|
||||
## 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
|
||||
@@ -215,24 +154,19 @@ rg -n 'SaveMessage|RecentMessages|SearchMessages|sdk\\.New' internal/gateway/ses
|
||||
rg -n 'store\\.Open\\(|nell\\.OpenStore\\(' --glob '*.go'
|
||||
```
|
||||
|
||||
Inspect a configured file without opening it through either database:
|
||||
Inspect a configured file without opening it:
|
||||
|
||||
```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; }
|
||||
test -r "$DB_PATH" && test -f "$DB_PATH"
|
||||
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:
|
||||
Never run `sqlite3 "$DB_PATH"` because the name ends in `.db`. A current
|
||||
NellDB file is a Zstd-framed binary append log. Never pass a legacy SQLite file
|
||||
to `nell.OpenStore`; there is no format detector or automatic migration.
|
||||
|
||||
```bash
|
||||
go test ./internal/nell -run '^(TestEnqueueIdempotent|TestChatTaskLifecyclePreservesRouting|TestPersistenceAcrossRestart|TestConcurrentEnqueueAndClaim)$' -count=1
|
||||
@@ -241,117 +175,55 @@ 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.
|
||||
As verified 2026-07-28, these pass with writable Go caches.
|
||||
|
||||
## 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.
|
||||
- Trace every producer, converter, reader, projection, RPC payload, test
|
||||
backend, and production constructor. State what new data supersedes.
|
||||
- Add red tests with old/missing fields. Test round-trips for forge and chat.
|
||||
- Update creation paths, `docToTask`, `taskFields`, and restricted `Update` set.
|
||||
- Preserve `_id`/`_rev`; never delete `_rev` to "fix" conflicts.
|
||||
- Give missing/legacy data explicit compatibility rules.
|
||||
- Check SQLite implementation deliberately — contract parity or proven cutover.
|
||||
- Test field preservation through all lifecycle operations and reopen.
|
||||
- Add stale-revision, concurrent-writer, cancellation, malformed-value, restart cases.
|
||||
- Measure scans at representative sizes before accepting another scan.
|
||||
- Use shared backend contract test suite for `TaskStore` changes.
|
||||
|
||||
## 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.
|
||||
as of 2026-07-28.
|
||||
|
||||
Require this sequence before any cutover:
|
||||
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`.
|
||||
1. Freeze authoritative source or define proven dual-write protocol.
|
||||
2. Keep SQLite input and NellDB output at different paths.
|
||||
3. Inventory task rows, IDs, coordinates, statuses, fields, events, transition history.
|
||||
4. Decide where transition history goes; build dry-run exporter/importer with
|
||||
deterministic IDs, idempotent writes, checkpoints, rejection reporting.
|
||||
5. Compare counts by status/source/workflow plus content digests.
|
||||
6. Quiesce, copy, convert, validate, switch `db_path` once.
|
||||
7. Retain untouched source and last-known-good binary/config until window passes.
|
||||
8. Delete old reader only after production wiring, rollback, and change control.
|
||||
|
||||
Treat NellDB `PutMany` as sequential engine writes, not crash-atomic.
|
||||
Its SDK cache rollback does not undo records already written.
|
||||
## 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
|
||||
```
|
||||
| `nell: path is required` | Trace `cfg.DBPath` and direct caller. | `OpenStore` rejects empty path. |
|
||||
| `nell: open log: ... no such file or directory` | Check parent directory, mount, UID, `db_path`. | `OpenStore` does not create parent directory. |
|
||||
| Old tasks vanish after backend switch | Inspect file signature and configured path. | No SQLite import or format check. |
|
||||
| Forge task identity empty after reload | Compare enqueue args with Nell document constructor. | `EnqueueIssue` drops `identity`; chat enqueue does not. |
|
||||
| Stale/illegal transition succeeds | Read `Transition`, capture before/after state. | `from` unused in both Nell and SQLite. |
|
||||
| State changed but no matching history/detail | Trace state write and event sink independently. | Nell transition history absent; event persistence async. |
|
||||
| Directly addressable queued task never claimed | Check if document ID begins `meta:`. | Scan paths filter every `meta:` prefix. |
|
||||
| Recent messages reorder or omit turns | Test more than one insertion order and restart. | `RecentMessages` assumes key-sorted `AllDocs`; v0.2.5 not sorted. |
|
||||
| `sdk: revision conflict` | Preserve conflicting docs/revisions. | Stale explicit `_rev` supplied. |
|
||||
| Database grows after updates/deletes | Compare file size with document counts. | Append-only tombstones accumulate; no compaction. |
|
||||
| Data survives restart but not power loss | Separate close/replay from storage durability. | Default writes flush but don't `fsync`. |
|
||||
| NellDB SDK tests fail on `server/webui/dist/nell.wasm` | Run Archie's focused packages. | Published v0.2.5 omits embedded WASM asset. |
|
||||
| Fix on another branch; main still fails | Inspect current source and branch containment. | Candidate code is not live behavior. |
|
||||
@@ -6,60 +6,37 @@ description: "Run and observe Archie safely from a local binary or the repositor
|
||||
# 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`.
|
||||
Treat source and tests as current; treat `docs/archive/` as history.
|
||||
|
||||
## 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. |
|
||||
| `archied` | Resident orchestrator. Owns config, forge credentials, NellDB store, worktrees, gateways, dashboard, optional NATS/Docker orchestration. |
|
||||
| `archie-agent` | Current long-running NATS worker. Consumes legacy per-stage requests and full-task `archie.taskrun.>` requests. 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. |
|
||||
| State database | `db_path`: the NellDB append-log file holding tasks, events, and Nell-backed chat sessions/messages. Not SQLite despite the `.db` examples. |
|
||||
|
||||
## 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.
|
||||
- Obtain explicit authority for config, forge identity, repositories, NATS
|
||||
account, Docker host, and deployment host before starting.
|
||||
- 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.
|
||||
`POST /api/tasks/clear` deletes terminal task records.
|
||||
- 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.
|
||||
There is no config-only or dry-run flag.
|
||||
|
||||
## Know the command surfaces
|
||||
|
||||
@@ -80,122 +57,70 @@ There is no config-only or dry-run flag. Validate a candidate config through
|
||||
| `-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.
|
||||
Both linked binaries may also display Go's `-quickchecks` flag from
|
||||
`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.
|
||||
| `agent.mode = "inprocess"` and no `[nats]` | `archied` polls and claims from NellDB, runs workflow stages and model tools in-process. | **Production-wired candidate.** No process or OS isolation. |
|
||||
| `agent.mode = "subprocess"` | `archied` starts `agent.command` per stage and expects one JSON invocation on stdin, one response on stdout. | **Open/broken with default command.** `cmd/archie-agent` is a long-running NATS worker and never calls `agentexec.ServeOne`. |
|
||||
| `agent.mode = "nats"`, `[nats]`, containers disabled | `archied` runs the workflow; each autonomous stage goes to a separately started `archie-agent`. | **Implemented but operator-assembled.** 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, sends the whole workflow on `archie.taskrun.<id>`. | **Repository Compose path.** `config.docker.toml` wires it. |
|
||||
|
||||
## 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:
|
||||
Choose an explicitly approved config:
|
||||
|
||||
```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:
|
||||
Expect JSON logs on stderr. Require: `nats connected` when `[nats]` configured;
|
||||
`workflow registry built`; `memory manager started`; `web ui listening` unless
|
||||
`web.listen = "off"`; gateway-start messages for configured channels;
|
||||
`archied running` after startup verification. Absence of `archied running` means
|
||||
startup did not complete. The daemon has no HTTP health endpoint.
|
||||
|
||||
```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.
|
||||
Stop 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.
|
||||
|
||||
## 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.
|
||||
Do not use this to test subprocess mode.
|
||||
|
||||
## 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-build` | Build only the `agent` image from `Dockerfile`. |
|
||||
| `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. |
|
||||
| `task docker-down` | Run `docker compose down`. Does not request volume deletion. |
|
||||
|
||||
Prefer the narrow start when a deployment watcher is not intended:
|
||||
Prefer the narrow start:
|
||||
|
||||
```bash
|
||||
docker compose up -d nats archied
|
||||
```
|
||||
|
||||
Use read-only observations:
|
||||
Read-only observations:
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
@@ -204,59 +129,44 @@ 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`.
|
||||
Require `archied running` in logs as the daemon readiness gate.
|
||||
|
||||
Stop the repository stack with:
|
||||
Stop 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`.
|
||||
Never add `-v` during routine shutdown. The Compose `agent` service is a
|
||||
build-only placeholder that 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. |
|
||||
| Daemon logs | JSON on stderr; Docker's configured log driver captures them under Compose. |
|
||||
| Agent logs | JSON on worker/container stderr. Task containers use `AutoRemove`. |
|
||||
| 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`. |
|
||||
| Container worktree | Host worktree bind-mounted read/write at `/data/worktree`; `task.json` written at root. |
|
||||
| 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. |
|
||||
| Telegram update state | `<work_dir>/telegram-update-deferrals.json` plus hashed `release-announcements-*.json`. |
|
||||
| Codesearch candidates | Defaults derive as `<work_dir>/indexes` and `<work_dir>/workspace-indexes.db`; no `indexing.Manager` construction found in daemon composition root. |
|
||||
| Optional repository volume | `archie-repo-<owner>-<repo>` mounted at `/data/repo`. |
|
||||
| Ecosystem cache volumes | `archie-cache-go`, `archie-cache-node`, etc., mounted below `/data/cache`. No code sets tool cache env vars to those mount paths. |
|
||||
| NATS data | Compose declares `nats_data:/data`; NATS command does not set a store directory. |
|
||||
|
||||
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.
|
||||
In Compose, host paths are: `/var/lib/archie/work` for worktrees;
|
||||
`/var/lib/archie/db/archie.db` for the container's `/var/lib/archie/archie.db`;
|
||||
repository checkout mounted at `/workspace`; host Docker socket mounted into `archied`.
|
||||
|
||||
## Understand NATS and container observation
|
||||
|
||||
@@ -265,120 +175,49 @@ 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`. |
|
||||
| Discovery | `archie.task.bug`, `.feature`, `.bootstrap`, or `.default`; daemon durable consumer `archie-daemon`, 5-min ack wait, max 3 deliveries. |
|
||||
| Legacy stages | `archie.agent.<id>.request`; worker durable consumer defaults to `archie-agent`, 30-min ack wait, max 3 deliveries; response address in `X-Archie-Reply`. |
|
||||
| Container task | Core NATS request/reply on `archie.taskrun.<id>`. Task container reads `/data/worktree/task.json` and creates dedicated subscription; 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.
|
||||
workers join Docker's default bridge and cannot resolve `nats`. Initial
|
||||
`ErrNoResponders` is retried for 20s at 250ms intervals.
|
||||
|
||||
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.
|
||||
It forwards only configured provider-key variables.
|
||||
|
||||
## Fence current operational limitations
|
||||
|
||||
Treat these as open until code and tests prove otherwise:
|
||||
Open limitations until code/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
|
||||
- `subprocess` + default `archie-agent` is protocol-incompatible.
|
||||
- `config.production.toml` uses legacy `token_env`; validation requires
|
||||
`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.
|
||||
- Container RPC uses root forge/worktree for every identity.
|
||||
- Container orphan recovery lacks daemon-instance label.
|
||||
- `max_uptime` only bounds `Pool.Acquire` create/start; no lifetime timer.
|
||||
- Container workflow builds `TaskContext` without event bus.
|
||||
- SSE clients drop when channel full; replay at most 200 events.
|
||||
- Dashboard unauthenticated, includes mutating clear endpoint.
|
||||
|
||||
## Understand deployment and rollback seams
|
||||
|
||||
The repository Gitea workflow runs on pushes to `main` and component tags. It
|
||||
builds and pushes only:
|
||||
The Gitea workflow builds/pushes only `archied:latest` and `archie-agent:latest`.
|
||||
It injects component versions into labels/metadata but publishes no versioned
|
||||
tags. It runs no quality gate before Docker builds.
|
||||
|
||||
- `git.catlow.cloud/sam/archied:latest`;
|
||||
- `git.catlow.cloud/sam/archie-agent:latest`.
|
||||
Before promotion: record running image IDs/digests; config checksums (no
|
||||
secrets); task counts via safe GET; establish NellDB backup procedure.
|
||||
|
||||
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.
|
||||
No complete rollback command exists, no versioned image tags. 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.
|
||||
Repository guidance (2026-07-28): two instances on `carina` with distinct
|
||||
`bot_user` values. No live process list, config, image digest, service manager,
|
||||
or deployment was verified. Do not invent SSH, systemd, or service commands.
|
||||
|
||||
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
|
||||
```
|
||||
@@ -9,54 +9,20 @@ Use Beads as the shared project task system. Local plans, scratch files, and per
|
||||
|
||||
## First Step
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
bd prime
|
||||
```
|
||||
|
||||
If that prints nothing, check whether the repository has an active Beads workspace:
|
||||
|
||||
```bash
|
||||
bd where
|
||||
```
|
||||
|
||||
## Preferred Route
|
||||
|
||||
Use the `bd` CLI when shell access is available. It is the most compact and direct Beads interface.
|
||||
|
||||
## Core CLI Workflow
|
||||
|
||||
1. Find work:
|
||||
|
||||
```bash
|
||||
bd ready
|
||||
bd list --status=open
|
||||
bd list --status=in_progress
|
||||
```
|
||||
|
||||
2. Inspect before editing:
|
||||
|
||||
```bash
|
||||
bd show <id>
|
||||
```
|
||||
|
||||
3. Claim work atomically:
|
||||
|
||||
```bash
|
||||
bd update <id> --claim
|
||||
```
|
||||
|
||||
4. Create durable follow-up work when implementation reveals new tasks:
|
||||
|
||||
```bash
|
||||
bd create "Short title" --description="Why this exists and what needs to be done" --type=task --priority=2
|
||||
```
|
||||
|
||||
5. Close completed work:
|
||||
|
||||
```bash
|
||||
bd close <id> --reason="Completed"
|
||||
bd ready # Find work
|
||||
bd list --status=open # List open work
|
||||
bd show <id> # Inspect
|
||||
bd update <id> --claim # Claim
|
||||
bd create "Title" --description="Why" --type=task --priority=2 # Create follow-up
|
||||
bd close <id> --reason="Completed" # Close
|
||||
```
|
||||
|
||||
## What Belongs In Beads
|
||||
|
||||
Reference in new issue
Block a user