diff --git a/.agents/skills/archie-architecture-contract/SKILL.md b/.agents/skills/archie-architecture-contract/SKILL.md index 0e3360f62..9955e424b 100644 --- a/.agents/skills/archie-architecture-contract/SKILL.md +++ b/.agents/skills/archie-architecture-contract/SKILL.md @@ -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/` | 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/` | Make it removable; give only narrow contracts/services. | -| Deployment assembly | `deployments/` | 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/` | 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 '||' cmd internal @@ -328,35 +231,4 @@ gopls references path/to/file.go:: 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`. diff --git a/.agents/skills/archie-build-and-env/SKILL.md b/.agents/skills/archie-build-and-env/SKILL.md index b566a385a..f01e5ee7c 100644 --- a/.agents/skills/archie-build-and-env/SKILL.md +++ b/.agents/skills/archie-build-and-env/SKILL.md @@ -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. | diff --git a/.agents/skills/archie-codebase-discovery/SKILL.md b/.agents/skills/archie-codebase-discovery/SKILL.md index 7cb5c5c94..b63fa74a7 100644 --- a/.agents/skills/archie-codebase-discovery/SKILL.md +++ b/.agents/skills/archie-codebase-discovery/SKILL.md @@ -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 ` 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 +``` ### 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 ``` -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. diff --git a/.agents/skills/archie-config-and-flags/SKILL.md b/.agents/skills/archie-config-and-flags/SKILL.md index 6ac05df34..e49c2965a 100644 --- a/.agents/skills/archie-config-and-flags/SKILL.md +++ b/.agents/skills/archie-config-and-flags/SKILL.md @@ -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..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.` | 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..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.` | Workflow stages read requested role then fall back to `builder`; triage judge falls back `triage` to `planner`. | production-wired | +| `providers..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. diff --git a/.agents/skills/archie-debugging-playbook/SKILL.md b/.agents/skills/archie-debugging-playbook/SKILL.md index 4a1bdcc71..e13ec5213 100644 --- a/.agents/skills/archie-debugging-playbook/SKILL.md +++ b/.agents/skills/archie-debugging-playbook/SKILL.md @@ -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..request` | Reply inbox in `X-Archie-Reply`; wall-clock budget or 30m | -| Full task handoff | `archie.taskrun.` | 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.` | 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://` | 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://` | 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.` - 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 ` 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 -``` diff --git a/.agents/skills/archie-diagnostics-and-tooling/SKILL.md b/.agents/skills/archie-diagnostics-and-tooling/SKILL.md index 058eb839e..62da0074a 100644 --- a/.agents/skills/archie-diagnostics-and-tooling/SKILL.md +++ b/.agents/skills/archie-diagnostics-and-tooling/SKILL.md @@ -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 ``; 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"`. diff --git a/.agents/skills/archie-docs-and-writing/SKILL.md b/.agents/skills/archie-docs-and-writing/SKILL.md index 2ce251273..1d8c760e0 100644 --- a/.agents/skills/archie-docs-and-writing/SKILL.md +++ b/.agents/skills/archie-docs-and-writing/SKILL.md @@ -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 `## []`, 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 }' -``` diff --git a/.agents/skills/archie-domain-reference/SKILL.md b/.agents/skills/archie-domain-reference/SKILL.md index 2f2a2f964..3db7b34ff 100644 --- a/.agents/skills/archie-domain-reference/SKILL.md +++ b/.agents/skills/archie-domain-reference/SKILL.md @@ -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. diff --git a/.agents/skills/archie-failure-archaeology/SKILL.md b/.agents/skills/archie-failure-archaeology/SKILL.md index d6224e77d..57974a9df 100644 --- a/.agents/skills/archie-failure-archaeology/SKILL.md +++ b/.agents/skills/archie-failure-archaeology/SKILL.md @@ -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' -- git blame -L , -- ``` -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 HEAD git branch -a --contains ``` -Read the parent version when the failure is semantic: +Read parent version when failure is semantic: ```sh git show ^: @@ -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/ -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 `` 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 `` 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` 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` 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' git diff --stat HEAD... git merge-base --is-ancestor 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 && git merge-base --is-ancestor 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` diff --git a/.agents/skills/archie-nelldb/SKILL.md b/.agents/skills/archie-nelldb/SKILL.md index e56089842..758f8e7a8 100644 --- a/.agents/skills/archie-nelldb/SKILL.md +++ b/.agents/skills/archie-nelldb/SKILL.md @@ -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 `-`. 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 `-`. 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` | `::` | Current `store.Task` fields plus `created_at` | Direct `Get` by forge coordinates; scans for numeric task ID, status, claims, counts, and stats | -| `events` | `event:` | `events.Event`; `data` is stored as a JSON string | Full scan, application filter, then explicit ID sort | +| `tasks` | `::` | Current `store.Task` fields plus `created_at` | Direct `Get` by forge coordinates; scans for numeric task ID, status, claims, counts, stats | +| `events` | `event:` | `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` | `:<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. | diff --git a/.agents/skills/archie-run-and-operate/SKILL.md b/.agents/skills/archie-run-and-operate/SKILL.md index 9121683e3..afb9bccf3 100644 --- a/.agents/skills/archie-run-and-operate/SKILL.md +++ b/.agents/skills/archie-run-and-operate/SKILL.md @@ -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..request`. | | Full-task handoff | A whole workflow sent on core NATS subject `archie.taskrun.` 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 ` | 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.`. | **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.`. | **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 | `/-/issue-`; default root `~/.local/share/archie/work`. | | Identity worktree | `/identity-/-/issue-`. | -| 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 | `/memory/MEMORY.md` and `/memory/USER.md`. | -| Telegram update state | `/telegram-update-deferrals.json` plus a hashed `release-announcements-*.json`. | -| Codesearch candidates | Defaults derive as `/indexes` and `/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--` 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 | `/telegram-update-deferrals.json` plus hashed `release-announcements-*.json`. | +| Codesearch candidates | Defaults derive as `/indexes` and `/workspace-indexes.db`; no `indexing.Manager` construction found in daemon composition root. | +| Optional repository volume | `archie-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..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.`. 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..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.`. 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 -``` diff --git a/.agents/skills/beads/SKILL.md b/.agents/skills/beads/SKILL.md index a5a3344cf..596bc7f18 100644 --- a/.agents/skills/beads/SKILL.md +++ b/.agents/skills/beads/SKILL.md @@ -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 -``` - -3. Claim work atomically: - -```bash -bd update --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 --reason="Completed" +bd ready # Find work +bd list --status=open # List open work +bd show # Inspect +bd update --claim # Claim +bd create "Title" --description="Why" --type=task --priority=2 # Create follow-up +bd close --reason="Completed" # Close ``` ## What Belongs In Beads