From d1bbd37d95b6374fd86606334a0639bd9d972014 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Wed, 29 Jul 2026 02:10:44 +1000 Subject: [PATCH] chore: cleanup --- .../archie-architecture-contract/SKILL.md | 362 ++++++++++++ .../agents/openai.yaml | 4 + .../SKILL.md | 526 ++++++++++++++++++ .../agents/openai.yaml | 4 + .../scripts/go-inventory.go | 231 ++++++++ .agents/skills/archie-build-and-env/SKILL.md | 424 ++++++++++++++ .../archie-build-and-env/agents/openai.yaml | 4 + .agents/skills/archie-change-control/SKILL.md | 411 ++++++++++++++ .../archie-change-control/agents/openai.yaml | 4 + .../skills/archie-codebase-discovery/SKILL.md | 432 ++++++++++++++ .../agents/openai.yaml | 4 + .../scripts/package-edges.sh | 36 ++ .../scripts/scan-go-type-syntax.go | 176 ++++++ .../scripts/scan-go-type-syntax.sh | 13 + .../scripts/trace-go-position.sh | 61 ++ .../skills/archie-config-and-flags/SKILL.md | 343 ++++++++++++ .../agents/openai.yaml | 4 + .../skills/archie-debugging-playbook/SKILL.md | 473 ++++++++++++++++ .../agents/openai.yaml | 4 + .../archie-diagnostics-and-tooling/SKILL.md | 429 ++++++++++++++ .../agents/openai.yaml | 4 + .../scripts/config-use-candidates.go | 279 ++++++++++ .../scripts/delivery-snapshot.sh | 90 +++ .../scripts/package-shape.sh | 86 +++ .../scripts/source-metrics.go | 352 ++++++++++++ .../skills/archie-docs-and-writing/SKILL.md | 350 ++++++++++++ .../agents/openai.yaml | 4 + .../references/templates.md | 364 ++++++++++++ .../skills/archie-domain-reference/SKILL.md | 380 +++++++++++++ .../agents/openai.yaml | 4 + .../archie-failure-archaeology/SKILL.md | 269 +++++++++ .../agents/openai.yaml | 4 + .agents/skills/archie-nelldb/SKILL.md | 357 ++++++++++++ .../skills/archie-nelldb/agents/openai.yaml | 4 + .../archie-research-methodology/SKILL.md | 359 ++++++++++++ .../agents/openai.yaml | 4 + .../skills/archie-run-and-operate/SKILL.md | 384 +++++++++++++ .../archie-run-and-operate/agents/openai.yaml | 4 + .../archie-technical-accountability/SKILL.md | 400 +++++++++++++ .../agents/openai.yaml | 4 + .../skills/archie-validation-and-qa/SKILL.md | 397 +++++++++++++ .../agents/openai.yaml | 4 + .beads/interactions.jsonl | 1 + .beads/issues.jsonl | 5 +- docs-2/data/generated/contracts.json | 400 +++++++++++++ .../architecture/generated-documentation.md | 133 +++-- .../skills/archie-wf-frontend/SKILL.md | 0 .../skills/archie-wf-go-gate/SKILL.md | 0 .../skills/archie-wf-node/SKILL.md | 0 .../skills/archie-wf-python/SKILL.md | 0 .../skills/archie-wf-security/SKILL.md | 0 .../skills/archie-wf-tdd/SKILL.md | 0 internal/config/config.go | 9 +- tools/docsgen/main.go | 46 +- tools/docsgen/main_test.go | 215 +++++++ tools/go.mod | 2 +- 56 files changed, 8781 insertions(+), 78 deletions(-) create mode 100644 .agents/skills/archie-architecture-contract/SKILL.md create mode 100644 .agents/skills/archie-architecture-contract/agents/openai.yaml create mode 100644 .agents/skills/archie-architecture-planning-campaign/SKILL.md create mode 100644 .agents/skills/archie-architecture-planning-campaign/agents/openai.yaml create mode 100644 .agents/skills/archie-architecture-planning-campaign/scripts/go-inventory.go create mode 100644 .agents/skills/archie-build-and-env/SKILL.md create mode 100644 .agents/skills/archie-build-and-env/agents/openai.yaml create mode 100644 .agents/skills/archie-change-control/SKILL.md create mode 100644 .agents/skills/archie-change-control/agents/openai.yaml create mode 100644 .agents/skills/archie-codebase-discovery/SKILL.md create mode 100644 .agents/skills/archie-codebase-discovery/agents/openai.yaml create mode 100755 .agents/skills/archie-codebase-discovery/scripts/package-edges.sh create mode 100644 .agents/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.go create mode 100755 .agents/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh create mode 100755 .agents/skills/archie-codebase-discovery/scripts/trace-go-position.sh create mode 100644 .agents/skills/archie-config-and-flags/SKILL.md create mode 100644 .agents/skills/archie-config-and-flags/agents/openai.yaml create mode 100644 .agents/skills/archie-debugging-playbook/SKILL.md create mode 100644 .agents/skills/archie-debugging-playbook/agents/openai.yaml create mode 100644 .agents/skills/archie-diagnostics-and-tooling/SKILL.md create mode 100644 .agents/skills/archie-diagnostics-and-tooling/agents/openai.yaml create mode 100755 .agents/skills/archie-diagnostics-and-tooling/scripts/config-use-candidates.go create mode 100755 .agents/skills/archie-diagnostics-and-tooling/scripts/delivery-snapshot.sh create mode 100755 .agents/skills/archie-diagnostics-and-tooling/scripts/package-shape.sh create mode 100755 .agents/skills/archie-diagnostics-and-tooling/scripts/source-metrics.go create mode 100644 .agents/skills/archie-docs-and-writing/SKILL.md create mode 100644 .agents/skills/archie-docs-and-writing/agents/openai.yaml create mode 100644 .agents/skills/archie-docs-and-writing/references/templates.md create mode 100644 .agents/skills/archie-domain-reference/SKILL.md create mode 100644 .agents/skills/archie-domain-reference/agents/openai.yaml create mode 100644 .agents/skills/archie-failure-archaeology/SKILL.md create mode 100644 .agents/skills/archie-failure-archaeology/agents/openai.yaml create mode 100644 .agents/skills/archie-nelldb/SKILL.md create mode 100644 .agents/skills/archie-nelldb/agents/openai.yaml create mode 100644 .agents/skills/archie-research-methodology/SKILL.md create mode 100644 .agents/skills/archie-research-methodology/agents/openai.yaml create mode 100644 .agents/skills/archie-run-and-operate/SKILL.md create mode 100644 .agents/skills/archie-run-and-operate/agents/openai.yaml create mode 100644 .agents/skills/archie-technical-accountability/SKILL.md create mode 100644 .agents/skills/archie-technical-accountability/agents/openai.yaml create mode 100644 .agents/skills/archie-validation-and-qa/SKILL.md create mode 100644 .agents/skills/archie-validation-and-qa/agents/openai.yaml create mode 100644 docs-2/data/generated/contracts.json rename {.agents => examples}/skills/archie-wf-frontend/SKILL.md (100%) rename {.agents => examples}/skills/archie-wf-go-gate/SKILL.md (100%) rename {.agents => examples}/skills/archie-wf-node/SKILL.md (100%) rename {.agents => examples}/skills/archie-wf-python/SKILL.md (100%) rename {.agents => examples}/skills/archie-wf-security/SKILL.md (100%) rename {.agents => examples}/skills/archie-wf-tdd/SKILL.md (100%) diff --git a/.agents/skills/archie-architecture-contract/SKILL.md b/.agents/skills/archie-architecture-contract/SKILL.md new file mode 100644 index 000000000..7ccd82434 --- /dev/null +++ b/.agents/skills/archie-architecture-contract/SKILL.md @@ -0,0 +1,362 @@ +--- +name: archie-architecture-contract +description: >- + Protect Archie's load-bearing architecture while placing, implementing, or + reviewing behavior. Load this skill before changing daemon composition, + domains, workflows, task lifecycle, agent execution, messaging, work intake, + identity, memory, configuration, plugins, policies, persistence, NATS/RPC, + containers, or process boundaries; use it when deciding where new code + belongs, enforcing dependency direction, separating current runtime truth + from the approved target and open migration decisions, or ensuring every + behavior has one authoritative path. Route proof of duplication, dead-code + disposition, production reachability, and maintainability to + archie-technical-accountability. +--- + +# Archie Architecture Contract + +Treat architecture as executable safety policy. Preserve one understandable +owner and one production path for each behavior. + +## Read status before code + +Use these labels exactly: + +| Label | Meaning | Authority | +| --- | --- | --- | +| **CURRENT** | Behavior present in live code and production composition as of 2026-07-28. | Code, tests, and `cmd/archied/main.go` wiring | +| **APPROVED TARGET** | Direction an implementation must approach, but which may not exist on disk. | `docs/prds/01-project-management.md` and documents whose status says approved | +| **OPEN** | A migration or API decision no implementer may invent locally. | `docs/prds/architecture/migration-decisions.md` and documents marked in progress or under design | + +> **Do not implement target prose as though it describes current code.** +> Before treating a target package as available, prove that it exists and is +> used from a production entry point. If the task will create that package, +> classify it as a migration slice and obtain the focused package decision +> first. `internal/domain/` does not exist in the CURRENT tree as of 2026-07-28. + +Resolve apparent disagreement in this order: + +1. Read live code and production composition for CURRENT behavior. +2. Read `docs/prds/01-project-management.md` for APPROVED TARGET ownership. +3. Read the focused decision document for the selected behavior. +4. Read `docs/prds/architecture/migration-decisions.md` for OPEN work. +5. Stop and use `archie-architecture-planning-campaign` if a required semantic + decision remains open. + +## Route the task + +Use this skill to enforce boundaries and place behavior. + +Do **not** use it as: + +- a design interview or migration campaign; use + `archie-architecture-planning-campaign`; +- a project vocabulary glossary; use `archie-domain-reference`; +- NellDB mechanics, persistence behavior, or adapter guidance; use + `archie-nelldb`; +- a complete configuration field/default reference; use + `archie-config-and-flags`; +- proof that code is production-reachable, non-duplicated, or maintainable; use + `archie-technical-accountability`; +- a test, review, or release checklist; use `archie-change-control`. + +Load the sibling skill as well when the task crosses one of those boundaries. + +## Know the CURRENT system + +Do not simplify these facts into the target model: + +| Concern | CURRENT runtime truth on 2026-07-28 | Evidence | +| --- | --- | --- | +| Composition | `cmd/archied/main.go` performs substantial construction and wiring. Packages are organized mostly by technical mechanism. | `cmd/archied/main.go`; current `internal/*` tree | +| Durable work | `store.Task` combines forge/chat source data, workflow position, output, retry, identity, and PR state. | `internal/store/store.go` | +| Workflow | `internal/workflow` routes a `store.Task` into a `map[string]Workflow`, then mutates a broad `TaskContext` through sequential stages. | `internal/workflow/workflow.go` | +| Agent-stage boundary | A versioned `agentexec.Request`/`Result` carries one autonomous stage; validation correlates task, attempt, and stage. | `internal/agentexec/protocol.go` | +| Container handoff | `internal/taskrun` also carries an entire task plus `config.Repo` and `config.TaskConfig`; `archie-agent` runs routing and sequencing for this path. | `internal/taskrun/taskrun.go`; `cmd/archie-agent/main.go` | +| Git ownership | Daemon-owned worktree operations clone, commit, push, diff, and clean up. The model receives no git ownership. | `internal/worktree/`; `internal/workflow/steps.go`; `ARCHITECTURE.md` | +| Enforcement | Gates, read-only/protected paths, TDD inverted test gates, and diff caps are represented outside prompt prose. | `internal/agentexec/inprocess.go`; `internal/workflow/{agent,tdd,steps}.go` | +| Configuration | `internal/config.Config`, `IdentityConfig`, `Repo`, and task snapshots mix input decoding with runtime concerns. | `internal/config/config.go` | +| Identity | Configured names and bot usernames act as process-local identity keys. `daemon.IdentityRunner` groups per-name clients/config; there is no durable Identity domain. | `internal/daemon/daemon.go`; `internal/store/store.go`; `internal/gateway/session.go` | +| Messaging | `internal/gateway` contains both legacy `Message` flow and a richer `MessageEvent`; channel routing and chat task control are mixed with conversational behavior. | `internal/gateway/{gateway,messageevent,tasks}.go`; `internal/channels/` | +| Plugins | `plugin.Plugin` exposes only `Name` and `Version`; current loading interprets operator-installed Go files with Yaegi. | `internal/plugin/plugin.go` | +| Processes | Agent modes include in-process, subprocess, and NATS. Optional containers add a distinct boundary with known gaps; a subprocess alone is not a security sandbox. | `internal/config/config.go`; `cmd/archied/main.go`; `ARCHITECTURE.md` | + +### Interpret the current lifecycle honestly + +Use these CURRENT status values: + +```text +queued, running, waiting_human, pr_open, merged, +parked, dead, rejected, closed_wont_do +``` + +The intended flow includes queue/claim, workflow stages, human wait/resume, PR +reconciliation, parking/retry/exhaustion, and crash recovery. Read +`internal/store/store.go`, `internal/daemon/daemon.go`, and +`internal/workflow/workflow.go` before changing a transition. + +Do not call this an enforced state machine. CURRENT +`Store.Transition(ctx, taskID, from, to, detail)`: + +- does not include `from` in the update predicate; +- updates task state and inserts transition history in separate statements; +- can therefore accept an illegal/stale transition or leave state and history + inconsistent; +- is called from paths that sometimes discard its error. + +Treat atomic state plus event/history persistence as an OPEN migration design, +not a small local patch. + +## Preserve the load-bearing invariants + +| Invariant | Required action | Status and source | +| --- | --- | --- | +| The model never runs git | Keep clone, branch, commit, push, diff, and cleanup in deterministic workspace/worktree steps. Never expose git as an agent tool. | CURRENT: `ARCHITECTURE.md`; `internal/worktree/` | +| Deterministic constraints outrank prompts | Enforce gates, protected paths, read-only stages, test protection, and change caps outside model instructions. Do not replace enforcement with “must not” prose. | CURRENT: `ARCHITECTURE.md`; `internal/agentexec/inprocess.go`; `internal/workflow/` | +| Agent execution is a data boundary | Send bounded, versioned input; validate correlated output before applying it. Keep persistence, forge credentials, git authority, workflow outcomes, and policy enforcement outside the autonomous model. | CURRENT foundation: `internal/agentexec/protocol.go`; `ARCHITECTURE.md` | +| Every workflow ends explicitly | Preserve terminal outcome or visible park behavior. Preserve crash recovery of interrupted `running` work. | CURRENT: `internal/workflow/workflow.go`; `internal/store/store.go` | +| Generic plugins stay metadata-only | Keep `plugin.Plugin` at `Name()` and `Version()`. Put behavior on a typed capability interface with an owning `Registry` or `Manager`. | CURRENT-enforced rule: `internal/plugin/architecture_test.go`; `ARCHITECTURE.md#plugin-engine-rule-strict` | +| Capability engines own lifecycle | Give resource-owning engines explicit start/health/stop semantics and failure isolation. Supply narrow registrars/services, never `*daemon.Daemon` or a service locator. | APPROVED rule: `ARCHITECTURE.md#plugin-engine-rule-strict`; reviewers enforce non-mechanical parts | +| Trust is explicit | Treat trusted operator-installed in-process code, repository code, out-of-process integrations, and container-isolated code as different trust classes. Never call Yaegi or subprocess execution a sandbox. | APPROVED rule: `ARCHITECTURE.md#plugin-engine-rule-strict` | +| Infrastructure stays replaceable | Keep forge, persistence, workspace, transport, container, and model details behind behavior-owned contracts. Do not leak broker messages, DB rows, SDK types, or config DTOs into domain models. | APPROVED TARGET: `docs/prds/architecture/dependencies-and-contracts.md` | +| Same-repository execution serializes by default | Preserve the default unless an explicit scheduling policy permits concurrency. | CURRENT: `internal/config/config.go`; `internal/daemon/daemon.go` | + +Run the mechanical plugin guard after changing any plugin or `*Engine` +interface: + +```bash +go test ./internal/plugin -count=1 +``` + +Passing it does **not** prove lifecycle, host-access, shutdown, or trust +semantics. Review those manually through `archie-change-control`. + +## Apply the APPROVED TARGET + +Apply these ownership rules to migration plans and new seams. Do not claim they +are CURRENT until production wiring proves the cutover. + +### Keep dependency direction inward + +Use this target direction: + +```text +domain and shared application contracts <- infrastructure implementations + ^ + | + application composition +``` + +Enforce: + +1. Put cohesive behavior, vocabulary, state, commands, events, policies, + runtime settings, and required service interfaces with its owning domain. +2. Make infrastructure implement domain-required interfaces and translate + external representations. +3. Let only `internal/app` choose concrete implementations and connect domains. +4. Keep `cmd/*` limited to process input and invoking composition. +5. Use an owned command, event, or approved shared contract across domains. +6. Never let one domain mutate another domain's state or call its internals. +7. Reject generic `entities`, `services`, `repositories`, `messages`, or + `utils` layers that merely group mechanisms. + +Sources: `docs/prds/architecture/organisation.md` and +`docs/prds/architecture/dependencies-and-contracts.md`. + +### Keep source ownership independent of deployment + +Begin with a modular monolith even when capabilities run in separate processes. +Introduce or retain a process/service boundary only for demonstrated: + +- security isolation; +- independent scaling; +- failure containment; or +- independent operation. + +Do not add a network protocol or duplicate service scaffolding for possible +future extraction. A transport is an infrastructure implementation of a +behavior-owned contract, not the owner of the behavior. + +Source: `docs/prds/architecture/organisation.md`. + +### Separate interaction, admission, assistance, and execution + +Use this target handoff: + +```text +channel-neutral Message + -> selected Agent turn or deterministic automation + -> optional proposed work + -> Work Intake validates and emits AcceptedWorkRequest + -> Workflow domain selects a Workflow version + -> Workflow domain creates WorkflowExecution +``` + +Keep the concepts separate: + +- **Messaging** owns canonical messages, conversations, branches, channel/source + correlation, delivery attempts, and messaging projections. +- **Agent** owns a persistent assistant, model-independent continuity, + specialization, capability context, and memory associations. +- **Work Intake** owns admission, validation, deterministic routing, and the + accepted-work-request handoff. +- **Workflow** owns reusable versioned definitions, steps, durable executions, + attempts, outcomes, and typed Workflow plugin contracts. + +Do not equate an external issue/message with a WorkflowExecution. Do not let +Work Intake create one directly. Do not require ordinary conversation or direct +tool use to become durable workflow-backed work. + +Sources: `docs/prds/architecture/migration-decisions.md`, +`docs/prds/architecture/agent-system.md`, and +`docs/prds/architecture/messaging-and-work-intake.md`. + +### Separate identity, Agent, conversation, and memory + +Use immutable `IdentityID` for target attribution; never use display names, +forge usernames, bot names, or the empty string as canonical identity. Keep +Identity separate from Agent: Identity names the actor; Agent owns assistant +behavior and continuity. + +Preserve the four fixed target memory scopes: + +| Scope | Visibility | +| --- | --- | +| Global shared | Intentionally shared across Archie | +| Agent-wide | One Agent across its users; private to that Agent by default | +| User-wide | One user across authorized Agents | +| Agent-user relationship | Exactly one Agent and one user | + +Resolve Agent and initiating user before loading memory. Do not use conversation +branching as a fifth memory scope. + +Sources: `docs/prds/architecture/identity.md`, +`docs/prds/architecture/agent-system.md`, and +`docs/prds/architecture/migration-decisions.md`. + +### Dissolve global runtime configuration + +Treat the current `internal/config` package as a migration source inventory, not +a target domain: + +- move file/env/overlay/secret decoding to + `internal/infrastructure/configuration`; +- let each domain or plugin own typed runtime settings for its behavior; +- translate external DTOs to those settings in `internal/app`; +- never pass complete application config into a domain; +- never move `config.Repo` or `IdentityConfig` intact to a renamed shared + package; +- classify every behavioral value as invariant, runtime setting, policy value, + derived value, or runtime state. + +Do not add another unrelated concern to the global config model without an +explicit compatibility plan and deletion criterion. Use +`archie-config-and-flags` for the field ledger. + +Source: `docs/prds/architecture/configuration.md`. + +## Place new behavior deliberately + +Use this decision table. “Target” entries require a reviewed migration slice +when the target package is not yet live. + +| Behavior | Target owner/location | Decision gate | +| --- | --- | --- | +| Persistent actor lifecycle and attribution | `internal/domain/identity` | Do not mix authentication/access policy into Identity. | +| Persistent assistant behavior and continuity | `internal/domain/agent` | Keep model/provider replaceable; do not fold Workflow into Agent. | +| Workflow definitions, steps, executions, attempts, outcomes | `internal/domain/workflow` | Preserve version ownership and one authoritative lifecycle. | +| Canonical messages, conversations, branches, delivery | `internal/domain/messaging` | Keep platform IDs as external correlation, not canonical IDs. | +| Admission and deterministic routing of proposed durable work | `internal/domain/workintake` | Emit an accepted request; do not construct execution state. | +| Generic plugin identity/discovery/compatibility/lifecycle | `internal/domain/plugin` | Keep generic contract metadata-only. | +| Capability-specific plugin behavior | Owning domain's typed registry/manager | Never add behavior to `plugin.Plugin`. | +| Broker-neutral publication/subscription mechanics | `internal/eventbus` | Keep message meaning and schemas with their domain. | +| Shared policy evaluation/evidence mechanics | `internal/policy` | Keep policy vocabulary, evaluators, and consequences with the consuming domain. | +| NATS, SQLite/NellDB, forge, config decoding, external SDK adapters | `internal/infrastructure/` | 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. | + +## Confront known weak points + +State these plainly in every affected plan: + +| Weak point on 2026-07-28 | Required response | +| --- | --- | +| `TaskContext` is a mutable service bag containing complete config, services, policy, and scratch state. | Do not add another unrelated field casually. Design narrow step inputs/contracts and a staged removal path. | +| Workflow lifecycle is split across store, daemon, workflow, gateway, and worker code. | Trace every writer and reader before changing status. Require one owner, parity tests, and deletion criteria. | +| State changes and transition history are non-atomic; `from` is advisory. | Treat state-machine and atomic-event work as architecture migration. Do not “fix” one caller and claim completion. | +| In-process and container paths put workflow orchestration on different sides of the process boundary. | Decide which path survives and why before extending both. Fence compatibility adapters and name their deletion gate. | +| Identity uses strings; task uniqueness and NATS deduplication omit identity. | Do not promise independent multi-identity ownership until canonical IDs, uniqueness, and transport correlation migrate. | +| Container RPC registration uses root forge/worktree clients, not the task owner's identity bindings. | Treat non-root container execution as a known trust/correctness defect; never describe it as identity-isolated. | +| Missing or malformed container `task.json` makes `archie-agent` join the shared task-run queue. | Do not claim a per-task workspace binding after this fallback. Require valid boot identity to fail closed before treating the path as isolated. | +| Subprocess execution uses the daemon user and host access. | Never describe subprocess mode as a security boundary. Require a real container/isolation design for confidentiality or integrity. | +| Gateway duplicates lifecycle strings and has competing message contracts. | Do not add a third contract or another direct lifecycle mutation path. | +| Global config and `IdentityConfig` combine unrelated owners. | Do not cure complexity with a renamed global structure or an untyped `Extra` map. | +| Memory has fixed scope requirements but OPEN final placement and migration. | Preserve scope isolation; use focused design before moving providers or persistence. | +| Tests can make unused or duplicate code appear legitimate. | Prove production reachability from composition and dispose of the superseded path; use `archie-technical-accountability`. | + +## Control every architecture-affecting change + +Classify the change before editing: + +| Class | Action | +| --- | --- | +| Current-path repair | Stay inside the current owner, preserve invariants, and avoid speculative target scaffolding. | +| Migration slice | Record current owner, target owner, state/contracts to preserve, compatibility adapter, cutover, and objective deletion criteria. | +| New or changed architecture | Stop implementation and run `archie-architecture-planning-campaign` until the focused decision is approved. | + +Before implementation: + +- [ ] Name the single behavior under change. +- [ ] Trace its production entry point, constructor, consumers, mutable state, + persistence, lifecycle, config, tests, and process crossings. +- [ ] Search for duplicates, alternate implementations, and older code paths. +- [ ] Read the focused decision document; do not infer authority over neighbors. +- [ ] Mark every claim CURRENT, APPROVED TARGET, or OPEN. +- [ ] Name the authoritative owner and every superseded path. +- [ ] Define parity, cutover, rollback, and deletion evidence. +- [ ] Route unresolved ownership or semantics to the architecture campaign. + +Use evidence, not name matching: + +```bash +rg -n '||' cmd internal +go list -deps ./cmd/archied | rg 'github.com/samcharles93/archie-core/internal/' +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/prds/architecture/migration-decisions.md +sed -n '1,320p' internal/store/store.go +sed -n '1,240p' internal/workflow/workflow.go +sed -n '1,220p' internal/agentexec/protocol.go +sed -n '620,680p' cmd/archied/main.go +sed -n '930,975p' internal/daemon/daemon.go +go test ./internal/plugin -count=1 +command -v gopls && gopls help references +``` diff --git a/.agents/skills/archie-architecture-contract/agents/openai.yaml b/.agents/skills/archie-architecture-contract/agents/openai.yaml new file mode 100644 index 000000000..1048ff3d5 --- /dev/null +++ b/.agents/skills/archie-architecture-contract/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Archie Architecture Contract" + short_description: "Protect Archie load-bearing architecture decisions" + default_prompt: "Use $archie-architecture-contract to place and review this change without violating current or target architecture." diff --git a/.agents/skills/archie-architecture-planning-campaign/SKILL.md b/.agents/skills/archie-architecture-planning-campaign/SKILL.md new file mode 100644 index 000000000..7d58de6fc --- /dev/null +++ b/.agents/skills/archie-architecture-planning-campaign/SKILL.md @@ -0,0 +1,526 @@ +--- +name: archie-architecture-planning-campaign +description: Run a decision-gated architecture campaign for archie-core before implementing a cross-package feature, migration, new domain, new process boundary, configuration redesign, duplicated-path cleanup, or other change whose ownership and change surface are unclear. Use when an engineer would otherwise need to trace much of the repository to discover what a feature touches, when TDD can prove behavior but not maintainability, or when planning must distinguish the live implementation from the approved target architecture. +--- + +# Archie architecture planning campaign + +Prevent another last-minute migration. Produce an implementation-ready +architecture handoff in which every behavior, state transition, configuration +value, boundary, compatibility path, and deletion has an explicit owner and +testable disposition. Optimize for a cohesive change that a zero-context +engineer can locate, explain, extend, and remove without tracing unrelated code, +not the first green test. + +## Load the required skill chain + +Load these sibling skills before starting. For smaller-context sessions, +load only the first two initially, then load the rest at their relevant +phase: + +1. `archie-codebase-discovery` — investigate the complete live change cone. +2. `archie-architecture-contract` — apply Archie's load-bearing invariants. +3. `archie-research-methodology` — state hypotheses and measurable predictions + (needed by Phase 5). +4. `archie-technical-accountability` — record evidence, decisions, debt, and + ownership without hiding uncertainty (needed by Phase 6+). +5. `archie-change-control` — classify and gate any resulting source or runtime + change (needed by Phase 11). + +Also load `archie-domain-reference` at Phase 3 (vocabulary and ownership) and +`archie-docs-and-writing` plus its template at Phase 10 (ADR/PRD handoff). + +If a sibling is unavailable, stop at the current read-only gate and report the +missing control. Do not reconstruct its doctrine from memory. + +## Know when not to use this campaign + +- For a localized defect whose owner, state, consumers, and boundary are already proven, use `archie-change-control` and the repository TDD workflow. +- To explore an unfamiliar package, use `archie-codebase-discovery`. +- To review an already-written patch, use `archie-technical-accountability` plus the applicable review and validation skills. +- To justify a preferred rewrite, use `archie-research-methodology`; this campaign may conclude that no architecture change is warranted. + +## Use the ground-truth model + +Keep two ledgers. Never blend them. + +| Ledger | Authority | Meaning | +|---|---|---| +| Current implementation | Live production wiring, Go code, persistence, tests, deployment definitions, and observed behavior | What Archie does now, including duplication and defects | +| Approved target | `docs/prds/01-project-management.md` and the status-qualified decisions in `docs/prds/architecture/*.md` | What Archie has approved or explicitly left open | + +Treat `ARCHITECTURE.md` as a useful earlier architecture description, not proof +that current wiring still matches it. Treat a decision marked “in progress,” +“deferred,” or “under design” as a constraint plus open questions, not a +finished design. + +As of 2026-07-28, the approved target is domain-oriented, while much of the live +tree remains in technical packages such as `internal/config`, `internal/daemon`, +`internal/store`, and `internal/workflow`. Re-run the provenance commands before +relying on that volatile fact. + +## Define the terms once + +- **Area under review**: one cohesive application responsibility, not an existing directory name. +- **Owner**: the domain or capability with authority over behavior, vocabulary, state, settings, commands, events, and consequences. +- **Change cone**: every entry point, caller, consumer, state record, adapter, test, configuration input, process boundary, and document affected by the decision. +- **Domain contract**: the smallest behavior required by the owning domain; infrastructure implements it. +- **Compatibility path**: a temporary adapter, dual read, dual write, or translation used only to preserve behavior during cutover. +- **Authoritative path**: the sole path allowed to decide or mutate a behavior after cutover. +- **Deletion criterion**: observable evidence that makes removal safe; “after migration” is not a criterion. +- **Architecture packet**: the complete evidence and decision handoff produced by this campaign. + +## Establish dynamic expected numbers + +Do not invent repository counts. First verify the repository root, then +capture baselines and use them as expected numbers: + +```bash +git rev-parse --show-toplevel >/dev/null || { echo 'run from repo root' >&2; exit 1; } +test -f go.mod && test -f Taskfile.yml && test -f CLAUDE.md || { + echo 'go.mod, Taskfile.yml, or CLAUDE.md missing — wrong directory?' >&2 + exit 1 +} +git rev-parse HEAD +git status --short +go list -f '{{.ImportPath}}' ./internal/... | sort | tee /tmp/archie-architecture-packages.txt +wc -l /tmp/archie-architecture-packages.txt +find docs/prds/architecture -maxdepth 1 -type f -name '*.md' -print | sort | tee /tmp/archie-architecture-docs.txt +wc -l /tmp/archie-architecture-docs.txt +``` + +Name the resulting counts: + +- `P` = current internal package rows in scope; for the whole migration, use every row in `/tmp/archie-architecture-packages.txt`. +- `D` = architecture decision documents. +- `F(area)` = production and test Go files in the declared change cone. +- `R(symbol)` = typed references returned for a symbol by gopls. +- `C` = decoded configuration fields and behavior-affecting literals in scope. +- `L` = legacy or competing paths in scope. + +Record the commit and dirty-file list beside every baseline. If concurrent work changes either, refresh the affected baseline; never mix measurements from two tree states. + +## Phase 0 — Declare one decision scope + +Write one sentence in this form: + +> Decide who owns ``, how `` reaches ``, and how the current paths migrate without changing ``. + +List explicit non-goals and affected operators/users. Classify the work with `archie-change-control`, but authorize no implementation yet. + +**Gate 0 — scope** + +- Expected declared architecture questions: `1`. +- Expected unexplained dirty files in the change cone: `0`. +- Expected implementation edits during the campaign: `0`. +- Expected non-goal list: at least `1` item. + +If more than one independent architecture question remains, split campaigns. If a dirty file has unknown ownership, pause until its author or intent is known. + +## Phase 1 — Build the decision corpus + +Read the index and every focused architecture decision before designing: + +```bash +sed -n '1,240p' docs/prds/01-project-management.md +while IFS= read -r ARCHIE_DOC; do sed -n '1,520p' "$ARCHIE_DOC"; done < /tmp/archie-architecture-docs.txt +sed -n '1,360p' ARCHITECTURE.md +sed -n '1,240p' CLAUDE.md +``` + +Build a current-versus-target ledger with columns: + +| Claim | Current evidence | Target decision | Status | Conflict or open decision | +|---|---|---|---|---| + +Give special attention to: + +- `package-review.md` for the required investigation and decision set; +- `migration-decisions.md` for unresolved destinations and cutover; +- `organisation.md` and `dependencies-and-contracts.md` for ownership and dependency direction; +- `configuration.md` for the required dissolution of `internal/config`; +- `safe-change-and-recovery.md` for candidate promotion and rollback; +- identity, agent, messaging, workflow, policy, plugin, and generated-doc documents whenever their vocabulary or contracts enter the change cone. + +**Gate 1 — corpus** + +- Expected decision-document review rows: `D`. +- Expected documents with omitted status: `0`. +- Expected target claims presented as current behavior: `0`. +- Expected contradictions without an evidence link and disposition: `0`. + +If live code contradicts an approved target, record migration work; do not silently redefine the target. If approved documents conflict, stop and request a decision instead of choosing the easier implementation. + +## Phase 2 — Inventory the live change cone with syntax-aware tools + +Do not start from package names. Start at production entry points and behavior. + +```bash +rg -n '^func main\\(' cmd +rg -n 'flag\\.(String|Bool|Int|Int64|Duration|Var)' cmd --glob '*.go' +rg --files cmd internal | sort +env GOTMPDIR=/tmp GOCACHE=/tmp/archie-architecture-inventory-cache go run .claude/skills/archie-architecture-planning-campaign/scripts/go-inventory.go -root . -scope internal/ -include-tests=true +``` + +Replace `` with a real repository-relative directory. Run the inventory once per package in the change cone. It emits Go-parser-derived declarations as tab-separated columns: + +| Column | Kind values | Meaning | +|---|---|---| +| `KIND` | `IMPORT`, `TYPE`, `FUNC`, `METHOD`, `VAR`, `CONST` | Go AST declaration kind | +| `PACKAGE` | Directory path relative to `-root` | Package directory containing the declaration | +| `FILE` | Filename within the package | Source file | +| `LINE` | Positive integer | Declaration line number | +| `NAME` | Identifier string | Exported or unexported name | +| `DETAIL` | Short type/kind string | Receiver type for `METHOD`, underlying type for `TYPE`, signature summary for `FUNC` | + +Empty output means no matching Go packages were found under `-scope`. +Lines with empty `NAME` after the tab are parse-level artifacts; treat them +as noise. The inventory does not infer runtime use, cross-package references, +or dynamic registration. + +Use gopls after the inventory: + +- call `go_workspace` to confirm the module view; +- call `go_package_api` for every package exposing a boundary; +- call `go_search` for each domain term and competing synonym; +- call `go_symbol_references` for every constructor, interface, state type, command, event, setting, and persistence method in scope. + +If gopls is unavailable, use `go doc `, `go list -json `, and literal `rg` as a fallback. Label text-search counts approximate; do not claim typed coverage. + +Count files before reading: + +```bash +rg --files internal/ -g '*.go' | sort | tee /tmp/archie-architecture-area-files.txt +wc -l /tmp/archie-architecture-area-files.txt +``` + +**Gate 2 — inventory** + +- Expected files read: `F(area)`, the baseline line count. +- Expected boundary packages with API summaries: all boundary packages; omitted count `0`. +- Expected typed references traced for each selected symbol: `R(symbol)`; unexplained references `0`. +- Expected discoverable facts deferred as user questions: `0`. + +If gopls and text search disagree, inspect generated files, build tags, interfaces, reflection, Yaegi loading, and registration side effects. Do not infer “unused” from zero textual callers. + +## Phase 3 — Establish vocabulary and ownership + +Extract verbs, nouns, records, transitions, commands, events, settings, and failure outcomes from live behavior. Resolve overloaded terms rather than globally renaming `task`, `session`, `message`, `execution`, `identity`, or `plugin`. + +Create this table: + +| Term or behavior | Plain-language definition | Current locations | One owner | Competing meaning | Target contract | +|---|---|---|---|---|---| + +Use these ownership tests: + +1. Name the cohesive job. +2. Name the mutable records and transitions it governs. +3. Name the policy consequences it decides. +4. Name only the external services it requires. +5. Explain why this code changes together. + +Reject ceremonial `entities`, `services`, `helpers`, and `common` layers. A single-operation wrapper needs a boundary reason, a second genuine consumer, or removal/inlining. + +For NellDB-related areas, inspect `internal/nell`, every consumer, persistence tests, and the pinned module before assigning semantics: + +```bash +go list -m -f '{{.Path}} {{.Version}}' github.com/samcharles93/NellDB +rg -n 'nell\\.|NellDB|OpenStore|NewSessionStore' cmd internal --glob '*.go' +``` + +Do not make NellDB records domain models merely because they persist current state. + +**Gate 3 — vocabulary** + +- Expected behaviors or records without one owner: `0`. +- Expected unqualified terms with multiple meanings: `0`. +- Expected domain owners chosen because of an existing directory name: `0`. +- Expected boundaryless single-operation indirection: `0`, unless listed for deletion or justified by a tested contract. + +If one candidate owner must know another domain's internal state, redesign the handoff as an owned command, event, or narrow shared contract. + +## Phase 4 — Trace consumers, state, and failure semantics + +Trace each behavior from input to observable outcome: + +| Input/source | Entry point | Command/event | State mutation | Persistence | Side effect | Failure/retry | Output | +|---|---|---|---|---|---|---|---| + +For every mutable record, produce a transition table: + +| From | Command | Preconditions/version | To | Atomic event | Invalid result | Retry/idempotency | +|---|---|---|---|---|---|---| + +Inspect production construction in `cmd/archied/main.go` and `cmd/archie-agent/main.go`; constructors alone do not prove production use. Trace RPC, NATS, container, in-process, and subprocess paths separately. Trace tests after production; a mirrored fake can validate the same wrong assumption. + +**Gate 4 — runtime trace** + +- Expected production consumers reconciled per symbol: `R(symbol)`. +- Expected mutable records without a complete transition table: `0`. +- Expected state mutations without an identified transaction boundary: `0`. +- Expected side effects without failure, timeout, retry, and idempotency evidence: `0`. +- Expected competing authoritative write paths: `0`, or exactly `L` rows with cutover and deletion criteria. + +If two paths create the same outcome, do not add a third abstraction over both. Decide authority and migration direction first. + +## Phase 5 — Compare solutions and predict change locality + +Use `archie-research-methodology`. Compare at least three explicit options: + +| Rank | Approach | Normal use | Fence | +|---|---|---|---| +| 1 candidate default | Domain-first modular monolith with owner-defined contracts and composition in `internal/app` | Behavior and ownership are understood | Do not retain old technical ownership merely to reduce moves | +| 2 migration tool | Strangler cutover through the narrowest compatibility adapter | Data or live callers require staged migration | Require owner, expiry trigger, metrics, rollback, and deletion test | +| 3 conditional | Retain a process boundary or extract a service | Measured security isolation, failure containment, scaling, or independent-operation need exists | Future possibility is not evidence | +| rejected | Rename a generic package, pass global config, add a service locator, or keep parallel implementations indefinitely | Never | Violates approved architecture | + +Score each legitimate option on cohesion, dependency direction, state authority, contract size, configuration ownership, failure containment, migration risk, reversibility, deletion cost, and testability. + +Before choosing, rehearse at least three representative future changes: + +1. add a small behavior to the area; +2. replace an infrastructure implementation; +3. change one owned setting or policy. + +Predict the packages, contracts, and tests each would touch. Prefer obvious ownership and exclusion of unrelated packages over the smallest immediate diff. + +**Gate 5 — option decision** + +- Expected compared options: at least `3`, including the current structure. +- Expected selected option: `1`. +- Expected approved-invariant violations in the winner: `0`. +- Expected representative change rehearsals: at least `3`. +- Expected unexplained unrelated packages per rehearsal: `0`. +- Expected predictions without a measurement or later verification command: `0`. + +If no option clears every invariant, leave the decision open. Do not downgrade a MUST to get a winner. + +## Phase 6 — Complete the package destination matrix + +For the architecture migration, create one row for every package in `P`. For a bounded change, cover the measured change cone and prove why other packages are outside it. + +| Current package/behavior | Owner | Target path | Disposition | Dependencies to remove | State/contracts to preserve | Prerequisites | Deletion criterion | Decision status | +|---|---|---|---|---|---|---|---|---| + +Use only these dispositions: move, merge with named replacement, infrastructure adapter, application composition, approved shared contract, plugin/extra/deployment/example/generated artifact, or delete after proof. + +**Gate 6 — destinations** + +- Expected destination rows: `P` for the whole migration, otherwise every package in the recorded change cone. +- Expected blank owner, disposition, or status cells: `0`. +- Expected confirmed rows that still require an implementer to invent domain semantics: `0`. +- Expected compatibility rows without deletion criteria: `0`. + +An open row blocks that row, not an independent confirmed slice. + +## Phase 7 — Dissolve configuration by ownership + +Inventory both decoded fields and behavior-affecting literals: + +```bash +env GOTMPDIR=/tmp GOCACHE=/tmp/archie-architecture-inventory-cache go run .claude/skills/archie-architecture-planning-campaign/scripts/go-inventory.go -root . -scope internal/config -include-tests=false +rg -n '\\bconfig\\.' cmd internal --glob '*.go' +rg -n 'time\\.(Second|Minute|Hour)|time\\.Duration|http\\.DefaultClient|0\\.0\\.0\\.0|localhost|/usr/share|/data/' cmd internal --glob '*.go' +``` + +For each value, record external input, default/provenance, typed owner, validation, mutability, consumers, secrets, and migration. Keep the decoded document private to configuration infrastructure; never pass complete app configuration into a domain. + +Classify every literal as invariant, owned setting/default, policy value, external constraint, or defect. One current value does not make an invariant. + +**Gate 7 — configuration** + +- Expected inventoried configuration items: `C`. +- Expected items without exactly one runtime owner and classification: `0`. +- Expected domains importing configuration infrastructure or full app config: + `0` in the target. +- Expected live-setting mutation paths omitted from the migration ledger: `0`. +- Expected plugin settings added to an unrelated global model: `0`. + +If an item cannot reload safely, mark it restart-required and design candidate +validation, health observation, last-known-good preservation, and rollback. + +## Phase 8 — Justify process and trust boundaries + +Inventory current boundaries: + +```bash +rg -n 'Subprocess|NATS|nats\\.|RPC|rpc|container|Docker|Yaegi|plugin' cmd/archied cmd/archie-agent internal/{agentexec,container,nats,natsrpc,taskrun,forgerpc,storerpc,worktreerpc,plugin,yaegiutil} --glob '*.go' +``` + +For each retained boundary, record purpose, trusted principal, secrets and +resources exposed, protocol owner/version, failure containment, health, +startup/shutdown order, retries, and operator burden. + +Keep source ownership independent of deployment. Treat a subprocess as +transport, not a security sandbox. Keep model-owned work away from git +credentials and daemon authority. Give plugins narrow typed registrars, never +daemon access or generic hooks. + +**Gate 8 — boundaries** + +- Expected retained boundaries with one concrete justification: all retained + boundaries; unjustified count `0`. +- Expected external or cross-process contracts without owner/version: `0`. +- Expected boundaries described as isolation without an enforced isolation + mechanism: `0`. +- Expected domains split only for possible future deployment: `0`. + +If removal of a boundary changes confidentiality, integrity, availability, or +operations, return to Phase 5 with those constraints. + +## Phase 9 — Plan deprecation, cutover, rollback, and deletion + +Mine compatibility and prior replacement attempts: + +```bash +rg -n 'legacy|compat|deprecated|deprecat|TODO|FIXME|HACK|remove|delete' cmd internal docs --glob '*.go' --glob '*.md' +git log --oneline --decorate --all -- cmd internal docs/prds/architecture +git log -S'internal/config' --oneline --all +``` + +For each legacy path, record predecessor, successor, parity evidence, data +backfill, dual-read/write need, production switch, rollback trigger, observation +window, deletion criterion, and regression test. + +Require the production composition test to prove the successor is selected. +Require a negative test or architecture check to prevent reintroduction after +deletion. Time-box transitional duplication by an observable trigger, not a +calendar promise alone. + +**Gate 9 — cutover** + +- Expected legacy paths inventoried: `L`. +- Expected successor authorities per legacy behavior: exactly `1`. +- Expected compatibility paths without owner, rollback, and deletion proof: + `0`. +- Expected permanent duplicate authoritative paths after cutover: `0`. +- Expected old states/records without migration or explicit safe abandonment: + `0`. + +If parity cannot be measured, do not switch production wiring. Design the +observable first. + +## Phase 10 — Produce the ADR/PRD handoff + +Write or propose the focused architecture document only where change control +authorizes it. Include: + +1. scope and non-goals; +2. current-state trace with commit and dynamic baselines; +3. vocabulary and ownership; +4. current-versus-target ledger; +5. considered options, predicted numbers, and rejection reasons; +6. chosen owner, contracts, state machine, settings, policy, and boundaries; +7. destination matrix; +8. migration, compatibility, cutover, rollback, and deletion; +9. implementation slices and dependencies; +10. verification commands, expected evidence, unknowns, and named decisions + still requiring the user. + +Ask the user only questions whose answers materially change behavior or +structure and cannot be discovered in the repository. + +**Gate 10 — handoff** + +- Expected discoverable facts presented as questions: `0`. +- Expected undecided semantics delegated to implementers in a confirmed slice: + `0`. +- Expected claims without source evidence or explicit “candidate/open” status: + `0`. +- Expected unresolved normative contradictions: `0`. + +If a decision remains open, isolate it from executable slices and name its +owner. Never disguise it as an implementation detail. + +## Phase 11 — Slice for short, artful successes + +Route every slice through `archie-change-control`. Keep TDD and fresh +adversarial review, but add architecture acceptance before code acceptance. + +Each slice must: + +- deliver one observable behavior or migration proof; +- have one domain owner and a bounded change cone; +- establish or consume the final contract rather than create another temporary + model; +- preserve a working application at its boundary; +- remove a predecessor, or advance its recorded deletion criterion; +- add deterministic conformance protection where mechanically possible; +- state what becomes easier to change after the slice. + +Order slices as: characterization and observability, final contract, adapter or +data migration, production cutover, legacy deletion, architecture regression +guard. Do not create all target folders as empty scaffolding. + +**Gate 11 — executable plan** + +- Expected observable outcome per slice: `1`. +- Expected owner per slice: `1`. +- Expected unrelated domains modified per slice: `0`. +- Expected predecessors neither removed nor advanced toward deletion: `0`. +- Expected implementation slices bypassing change control: `0`. + +If a slice requires broad service-locator access or the full configuration +document, return to ownership and contract design. + +## Phase 12 — Re-measure after every slice + +Run the repository gate selected by `archie-change-control`, then compare the +slice against this packet. At minimum, re-run package inventory, typed +references, production construction tracing, configuration inventory, and +legacy-path search. + +Use a fresh adversarial reviewer to inspect every changed non-test file for +cohesion, hidden dead paths, duplicated authority, unchecked errors, +hard-coded behavior, interface leakage, nil/race/goroutine risk, and production +wiring. A green TDD suite proves required behavior; it does not prove the code +is maintainable. + +**Gate 12 — conformance** + +- Expected unexplained package/reference/configuration deltas from baseline: + `0`. +- Expected new authoritative paths beyond the selected design: `0`. +- Expected surviving reviewer findings: `0`. +- Expected destination/cutover rows left stale by the slice: `0`. +- Expected representative change rehearsals made harder without an accepted + rationale: `0`. + +If the slice passes tests but fails conformance, reject or redesign it. “Make it +work and move on” is not completion. + +## Fence off settled wrong paths + +- Do not code before mapping ownership, consumers, state, and cutover. +- Do not equate moving or renaming packages with architecture. +- Do not centralize unrelated runtime settings in a renamed global config. +- Do not add abstractions solely to wrap one operation or hide duplication. +- Do not preserve old and new models indefinitely “for compatibility.” +- Do not expose domain meaning through broker, database, SDK, or DTO types. +- Do not use process splits as source boundaries or subprocesses as sandboxes. +- Do not add capability methods to the generic plugin contract. +- Do not ask the user to rediscover code facts the tools can establish. +- Do not accept linter silence as dead-code evidence; inspect registration, + reflection, build tags, generated code, and production composition. +- Do not let a mirrored test fake become the sole proof of an external or + cross-process contract. +- Do not permit implementation difficulty to waive an approved invariant. + +## Provenance and maintenance + +Grounded on 2026-07-28 in the approved architecture index and every file under +`docs/prds/architecture/`, plus live `cmd`, `internal`, tests, `Taskfile.yml`, +and the user's quality requirements. Re-verify volatile facts before each use. + +```bash +sed -n '1,240p' docs/prds/01-project-management.md +for ARCHIE_DOC in docs/prds/architecture/*.md; do sed -n '1,8p' "$ARCHIE_DOC"; done +go list -f '{{.ImportPath}}' ./internal/... | sort +rg -n '^func main\\(' cmd +rg -n '\\bconfig\\.' cmd internal --glob '*.go' +rg -n 'legacy|compat|deprecated|TODO|FIXME|HACK' cmd internal docs --glob '*.go' --glob '*.md' +git log --oneline --decorate --all -- cmd internal docs/prds/architecture +env GOTMPDIR=/tmp GOCACHE=/tmp/archie-architecture-inventory-cache go run .claude/skills/archie-architecture-planning-campaign/scripts/go-inventory.go -root . -scope internal/config -include-tests=false +task --list +``` diff --git a/.agents/skills/archie-architecture-planning-campaign/agents/openai.yaml b/.agents/skills/archie-architecture-planning-campaign/agents/openai.yaml new file mode 100644 index 000000000..31f1083d6 --- /dev/null +++ b/.agents/skills/archie-architecture-planning-campaign/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Archie Architecture Planning Campaign" + short_description: "Plan maintainable Archie architecture before coding" + default_prompt: "Use $archie-architecture-planning-campaign to design and gate an Archie architectural change before implementation." diff --git a/.agents/skills/archie-architecture-planning-campaign/scripts/go-inventory.go b/.agents/skills/archie-architecture-planning-campaign/scripts/go-inventory.go new file mode 100644 index 000000000..4b6d0047c --- /dev/null +++ b/.agents/skills/archie-architecture-planning-campaign/scripts/go-inventory.go @@ -0,0 +1,231 @@ +// Command go-inventory emits a stable TSV inventory of Go declarations. +// +// It uses the Go parser instead of text matching, so architecture research can +// enumerate imports, types, struct fields, functions, methods, variables, and +// constants before tracing their references with gopls. +package main + +import ( + "bytes" + "flag" + "fmt" + "go/ast" + "go/format" + "go/parser" + "go/token" + "io/fs" + "os" + "path/filepath" + "sort" + "strconv" + "strings" +) + +type record struct { + kind string + pkg string + file string + line int + name string + detail string + sortKey string +} + +func main() { + rootFlag := flag.String("root", ".", "repository root") + scopeFlag := flag.String("scope", "internal", "repository-relative directory to inspect") + includeTests := flag.Bool("include-tests", true, "include _test.go files") + flag.Parse() + + root, err := filepath.Abs(*rootFlag) + if err != nil { + fatalf("resolve root: %v", err) + } + scope, err := confinedPath(root, *scopeFlag) + if err != nil { + fatalf("resolve scope: %v", err) + } + + fset := token.NewFileSet() + var records []record + err = filepath.WalkDir(scope, func(path string, entry fs.DirEntry, walkErr error) error { + if walkErr != nil { + return walkErr + } + if entry.IsDir() { + switch entry.Name() { + case ".git", "node_modules", "testdata", "vendor": + if path != scope { + return filepath.SkipDir + } + } + return nil + } + if filepath.Ext(path) != ".go" || (!*includeTests && strings.HasSuffix(path, "_test.go")) { + return nil + } + + parsed, parseErr := parser.ParseFile(fset, path, nil, 0) + if parseErr != nil { + return fmt.Errorf("parse %s: %w", path, parseErr) + } + relative, relErr := filepath.Rel(root, path) + if relErr != nil { + return relErr + } + relative = filepath.ToSlash(relative) + pkg := filepath.ToSlash(filepath.Dir(relative)) + records = append(records, fileRecords(fset, parsed, pkg, relative)...) + return nil + }) + if err != nil { + fatalf("inventory: %v", err) + } + + sort.Slice(records, func(i, j int) bool { + return records[i].sortKey < records[j].sortKey + }) + fmt.Println("KIND\tPACKAGE\tFILE\tLINE\tNAME\tDETAIL") + for _, item := range records { + fmt.Printf("%s\t%s\t%s\t%d\t%s\t%s\n", + item.kind, + item.pkg, + item.file, + item.line, + sanitize(item.name), + sanitize(item.detail), + ) + } +} + +func confinedPath(root, scope string) (string, error) { + if filepath.IsAbs(scope) { + return "", fmt.Errorf("scope must be repository-relative") + } + clean := filepath.Clean(scope) + if clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator)) { + return "", fmt.Errorf("scope escapes repository root") + } + path := filepath.Join(root, clean) + info, err := os.Stat(path) + if err != nil { + return "", err + } + if !info.IsDir() { + return "", fmt.Errorf("%s is not a directory", clean) + } + return path, nil +} + +func fileRecords(fset *token.FileSet, file *ast.File, pkg, relative string) []record { + var records []record + add := func(kind string, pos token.Pos, name, detail string) { + line := fset.Position(pos).Line + records = append(records, record{ + kind: kind, + pkg: pkg, + file: relative, + line: line, + name: name, + detail: detail, + sortKey: strings.Join([]string{pkg, relative, fmt.Sprintf("%09d", line), kind, name}, "\x00"), + }) + } + + for _, imported := range file.Imports { + path, err := strconv.Unquote(imported.Path.Value) + if err != nil { + path = imported.Path.Value + } + name := "" + if imported.Name != nil { + name = imported.Name.Name + } + add("IMPORT", imported.Pos(), name, path) + } + + for _, declaration := range file.Decls { + switch node := declaration.(type) { + case *ast.FuncDecl: + kind := "FUNC" + name := node.Name.Name + if node.Recv != nil && len(node.Recv.List) > 0 { + kind = "METHOD" + name = expression(node.Recv.List[0].Type) + "." + name + } + add(kind, node.Pos(), name, expression(node.Type)) + case *ast.GenDecl: + for _, spec := range node.Specs { + switch item := spec.(type) { + case *ast.TypeSpec: + detail := typeKind(item.Type) + add("TYPE", item.Pos(), item.Name.Name, detail) + structType, ok := item.Type.(*ast.StructType) + if !ok { + continue + } + for _, field := range structType.Fields.List { + fieldNames := make([]string, 0, len(field.Names)) + for _, name := range field.Names { + fieldNames = append(fieldNames, name.Name) + } + if len(fieldNames) == 0 { + fieldNames = append(fieldNames, expression(field.Type)) + } + for _, fieldName := range fieldNames { + add("FIELD", field.Pos(), item.Name.Name+"."+fieldName, expression(field.Type)) + } + } + case *ast.ValueSpec: + kind := "VAR" + if node.Tok == token.CONST { + kind = "CONST" + } + for _, name := range item.Names { + add(kind, item.Pos(), name.Name, expression(item.Type)) + } + } + } + } + } + return records +} + +func expression(node ast.Node) string { + if node == nil { + return "" + } + var buffer bytes.Buffer + if err := format.Node(&buffer, token.NewFileSet(), node); err != nil { + return fmt.Sprintf("%T", node) + } + return buffer.String() +} + +func typeKind(node ast.Expr) string { + switch node.(type) { + case *ast.StructType: + return "struct" + case *ast.InterfaceType: + return "interface" + case *ast.FuncType: + return "func" + case *ast.ArrayType: + return "array-or-slice" + case *ast.MapType: + return "map" + case *ast.ChanType: + return "chan" + default: + return expression(node) + } +} + +func sanitize(value string) string { + return strings.Join(strings.Fields(value), " ") +} + +func fatalf(format string, args ...any) { + fmt.Fprintf(os.Stderr, format+"\n", args...) + os.Exit(1) +} diff --git a/.agents/skills/archie-build-and-env/SKILL.md b/.agents/skills/archie-build-and-env/SKILL.md new file mode 100644 index 000000000..c28bbc82b --- /dev/null +++ b/.agents/skills/archie-build-and-env/SKILL.md @@ -0,0 +1,424 @@ +--- +name: archie-build-and-env +description: Recreate, inspect, and troubleshoot Archie Core's development, build, test, documentation, and container toolchains. Use when onboarding a checkout; diagnosing Go, Task, golangci-lint, gofumpt, pnpm, VitePress, Docker/Compose, NATS, GPG, cache, temporary-directory, listener, or network failures; comparing local work with repository automation; or proving which build surfaces a command actually covers. Load this before running task check in an unfamiliar or restricted environment because that gate rewrites files and omits several independent surfaces. +--- + +# Build and verify the Archie environment + +Recreate the environment as independently verified surfaces. Do not turn a +passing root-module command into a claim that the tools module, documentation +site, race detector, linter, or container images also passed. + +All volatile observations in this skill are snapshots from **2026-07-28**. +Re-run the maintenance commands at the end before relying on a number or +installed version. + +## Keep the scope narrow + +- Do not use this skill to decide whether evidence is sufficient for acceptance. + Load `archie-validation-and-qa`. +- Do not use it to start, stop, deploy, upgrade, or recover a running daemon. + Load `archie-run-and-operate`. +- Do not use it to interpret a product failure after the environment is known + good. Load `archie-debugging-playbook`. +- Do not use it to choose or wire runtime settings. Load + `archie-config-and-flags`. +- Do not use it to approve generated changes, dependency updates, cleanup, or + gate changes. Load `archie-change-control`. +- Do not use `docs-2/README.md` as onboarding documentation. It describes Tau, + and VitePress excludes it through `srcExclude` in + `docs-2/.vitepress/config.mts`. + +## Name the surfaces + +Use these terms consistently: + +| Term | Meaning here | +|---|---| +| Repository root | The directory containing `go.mod`, `Taskfile.yml`, and `CLAUDE.md`. | +| Runtime module | The root Go module, `github.com/samcharles93/archie-core`. It owns `cmd/`, `domain/`, and `internal/`. | +| Tools module | The independent nested Go module under `tools/`. It currently owns `tools/docsgen`. | +| Docs site | The pnpm/VitePress project under `docs-2/`. | +| Cold cache | A dependency cache that does not yet contain the required modules or packages; filling it requires network access. | +| Restricted sandbox | An environment that may allow file reads but deny loopback listeners, the container engine, or writes to default caches and temporary directories. | +| Host run | A run on an environment that permits the listeners and process features used by the tests. | + +No root `README*` or `CONTRIBUTING*` file exists as of the snapshot. Begin with: + +```bash +sed -n '1,240p' CLAUDE.md +sed -n '1,240p' ARCHITECTURE.md +task --list +``` + +Treat `CLAUDE.md` and `Taskfile.yml` as the current workflow contract. Treat +`ARCHITECTURE.md` as necessary design context, but verify implemented package +claims against current code and tests. + +## Inventory requirements before installing anything + +Do not guess versions from the installed machine. Compare the checkout's +declarations with the machine: + +```bash +go version +go env GOTOOLCHAIN GOVERSION GOOS GOARCH CGO_ENABLED GOTMPDIR GOCACHE GOMODCACHE +task --version +gofumpt -version +golangci-lint version +node --version +pnpm --version +npm --version +docker --version +docker compose version +git --version +gpg --version +``` + +Classify a missing command as an environment prerequisite, not a code failure. +The repository has no bootstrap installer and does not pin every host tool. +If you must bootstrap from scratch, the Dockerfiles provide a known-good +starting point (verified 2026-07-28): + +- Go ≥ 1.26.3 (Docker builder uses `golang:1.26-trixie`) +- Task ≥ 3.x (`go install github.com/go-task/task/v3/cmd/task@latest`) +- gofumpt (`go install mvdan.cc/gofumpt@latest`; unpinned in repo) +- golangci-lint v2 (`go install github.com/golangci-lint/v2/cmd/golangci-lint@latest`; unpinned) +- Node 24.x + pnpm ≥ 10 (see Dockerfile's `setup_24.x` and `npm install -g pnpm`) + +Always verify each installed version against the table below and record the +exact version in failure reports. The repository does not guarantee that +`@latest` today matches what was tested on the snapshot date. + +| Surface | Repository declaration | Installed snapshot | Interpretation | +|---|---|---|---| +| Runtime Go | `go 1.26.3` in `go.mod` | Go 1.26.5, linux/amd64 | The checkout requires at least the declared Go language/toolchain level. | +| Tools Go | `go 1.26.4` in `tools/go.mod` | Same Go 1.26.5 binary | Use a toolchain that satisfies both modules. | +| Task | Taskfile schema `version: "3"`; no executable version pin | Task 3.48.0 | Installed version is an environment fact, not a repo guarantee. | +| gofumpt | Used by `task fmt`; agent image installs `@latest` | v0.7.0 | Unpinned by the repository. | +| golangci-lint | v2 config in `.golangci.yml`; agent image installs `@latest` | 2.12.2 | Use the v2 CLI; exact release is unpinned. | +| Node | Docs CI uses `node-version: latest`; agent image configures Node 24 | 24.18.0 | The docs project has no `engines` or `packageManager` field. | +| pnpm | Docs CI selects major 10; agent image installs an unpinned global pnpm | 11.15.1 | Prefer CI's major 10 when reproducing CI. Do not call local 11 exact parity. | +| VitePress | `^1.6.4`, locked to 1.6.4 | Resolved by `pnpm-lock.yaml` | Install with the frozen lockfile. | +| Containers | Docker Compose commands in `Taskfile.yml` | `/usr/bin/docker` is a Podman-backed CLI that is unusable in this sandbox | Verify CLI, Compose plugin, daemon/socket, and privileges separately. | + +The Docker builders use `golang:1.26-trixie` and +`golang:1.26-bookworm`, while the agent runtime separately installs +`GO_VERSION=1.26.5`. The builder tags float across patch/image rebuilds; they do +not establish byte-for-byte reproducibility. + +## Prepare writable caches in a restricted sandbox + +First inspect the defaults: + +```bash +go env GOTMPDIR GOCACHE GOMODCACHE GOPATH +df -T /tmp +``` + +If any default is read-only, create task-specific paths. Do not repurpose +`HOME`, `CODEX_HOME`, or another system variable: + +```bash +export ARCHIE_GOTMPDIR=/tmp/archie-core-gotmp +export ARCHIE_GOCACHE=/tmp/archie-core-gocache +export ARCHIE_GOMODCACHE=/tmp/archie-core-gomodcache +export ARCHIE_GOPATH=/tmp/archie-core-gopath +export ARCHIE_LINT_CACHE=/tmp/archie-core-golangci +mkdir -p "$ARCHIE_GOTMPDIR" "$ARCHIE_GOCACHE" "$ARCHIE_GOMODCACHE" \ + "$ARCHIE_GOPATH" "$ARCHIE_LINT_CACHE" +``` + +Prefix Go commands with: + +```bash +env GOTMPDIR="$ARCHIE_GOTMPDIR" GOCACHE="$ARCHIE_GOCACHE" \ + GOMODCACHE="$ARCHIE_GOMODCACHE" GOPATH="$ARCHIE_GOPATH" \ + go test ./internal/config/... -count=1 +``` + +An empty `ARCHIE_GOMODCACHE` is a cold cache. Populate each module only when +network access is authorized: + +```bash +env GOTMPDIR="$ARCHIE_GOTMPDIR" GOCACHE="$ARCHIE_GOCACHE" \ + GOMODCACHE="$ARCHIE_GOMODCACHE" GOPATH="$ARCHIE_GOPATH" \ + go mod download +env GOTMPDIR="$ARCHIE_GOTMPDIR" GOCACHE="$ARCHIE_GOCACHE" \ + GOMODCACHE="$ARCHIE_GOMODCACHE" GOPATH="$ARCHIE_GOPATH" \ + go -C tools mod download +``` + +On this machine `/tmp` is tmpfs. Caches therefore consume memory-backed +storage. Measure them instead of filling them blindly: + +```bash +du -sh "$ARCHIE_GOTMPDIR" "$ARCHIE_GOCACHE" "$ARCHIE_GOMODCACHE" \ + "$ARCHIE_GOPATH" "$ARCHIE_LINT_CACHE" +``` + +## Recreate the root Go surface + +Use this cold-start sequence from the repository root: + +1. Confirm the module and entry points. +2. Download dependencies if the cache is cold and network is allowed. +3. Compile both binaries. +4. Run a focused test before the full suite. +5. Run vet and lint as separate facts. + +```bash +test -f go.mod +test -f cmd/archied/main.go +test -f cmd/archie-agent/main.go +go list -m +go build -o /tmp/archie-core-archied ./cmd/archied +go build -o /tmp/archie-core-agent ./cmd/archie-agent +go test ./internal/config/... -count=1 +go vet ./... +golangci-lint run ./... +``` + +Use the cache prefix from the previous section when defaults are read-only. +Writing binaries to `/tmp` verifies compilation without changing `bin/` or +Task's `.task/` checksum state. The equivalent repository task is: + +```bash +task build +``` + +Expect `task build` to write `bin/archied`, `bin/archie-agent`, and Task cache +state. Do not use it during a read-only review. + +## Understand exactly what Task runs + +Read `Taskfile.yml`; do not infer command graphs from task names. + +| Task | Exact effect | +|---|---| +| `task fmt` | Runs `gofumpt -w .`, then `go fix ./...`; both may rewrite source. | +| `task vet` | Runs `go vet ./...` in the runtime module. | +| `task lint` | Runs `golangci-lint run ./...`; this is separate from `task check`. | +| `task build` | Builds both commands into `bin/`. | +| `task test` | Runs `go test ./... -count=1` in the runtime module. | +| `task check` | Runs `fmt`, runs `go fix ./...` a second time, then `vet`, `build`, and `test`. | +| `task clean` | Recursively removes `bin/`; treat it as destructive. | +| `task docker-build` | Runs `docker compose build agent` only. | + +Repository doctrine calls `task check` the definitive gate. Its current +implementation is still only one surface: it omits `task lint`, race tests, the +`tools/` module, docs generation drift, and the VitePress build. + +Run `task check` only in an authorized writable worktree. Record its rewrites: + +```bash +git status --short +task check +git status --short +git diff --check +``` + +Never claim that pre-existing changes were produced by the gate. Capture the +first status before running it. + +For a read-only formatting preview, avoid `task fmt`: + +```bash +gofumpt -l . +``` + +As of the snapshot, this produced no output. `go fix ./...` has no equivalent +read-only task in this repository, so `task fmt` and `task check` remain +mutating commands even when the gofumpt preview is clean. + +## Verify the tools module separately + +The repository has no `go.work`. A root `go test ./...` does not enter +`tools/`. The tools module uses: + +```text +module github.com/samcharles93/archie-core/tools +replace github.com/samcharles93/archie-core => ../ +``` + +Run its tests explicitly: + +```bash +go -C tools test ./... -count=1 +``` + +Generate documentation data to a temporary file and compare it without +rewriting the checkout: + +```bash +go -C tools run ./docsgen \ + -repo-root .. \ + -out /tmp/archie-core-contracts.json +cmp --silent \ + docs-2/data/generated/contracts.json \ + /tmp/archie-core-contracts.json +``` + +The 2026-07-28 run wrote 10 schemas, the comparison passed, and +`go -C tools test ./... -count=1` passed. The planned `docsgen all` and +`docsgen check` commands described in +`docs/prds/architecture/generated-documentation.md` do **not** exist yet. +The checkout's `docs-2/data/generated/contracts.json` exists but is untracked +as of this snapshot. The comparison proves local generator parity, not +version-controlled drift protection. + +## Recreate and build the docs site + +Treat dependency installation and site compilation as two separate gates: + +```bash +pnpm --dir docs-2 install --frozen-lockfile +pnpm --dir docs-2 build +``` + +The install needs registry access on a cold pnpm store. The build writes +`docs-2/.vitepress/dist`. GitHub Pages CI uses pnpm major 10, Node `latest`, +the frozen lockfile, then `pnpm build`; it does not run Go tests or docsgen. + +The docs build could not be completed in the restricted 2026-07-28 session +because missing packages required npm registry access and DNS returned +`EAI_AGAIN`. Record that as an environment result, not a passing or failing +site build. + +Do not trust the checked-in `docs-2/node_modules` shape. It contains 237 +tracked symlink entries as of the snapshot, introduced by commit `308c199`. +Detect the condition: + +```bash +git ls-files -s 'docs-2/node_modules/**' \ + | awk '$1 == "120000" {count++} END {print count+0}' +git status --short -- docs-2 +``` + +Do not stage, normalize, or mass-delete that tree as incidental setup. Route +its cleanup through `archie-change-control`. Commit `4cb0577` records a +separate cleanup of accidentally committed `.gotmp` build/test artifacts; +`.gotmp/` is now ignored. + +## Treat container setup as a networked, privileged surface + +Before building, inspect the context and pinning: + +```bash +test -e .dockerignore || echo ".dockerignore is absent" +rg -n '^(FROM|[[:space:]]*image:)|@latest|:latest|setup_24.x' \ + Dockerfile Dockerfile.archied docker-compose.yml +git status --short +``` + +No `.dockerignore` exists as of the snapshot. Both Dockerfiles run +`COPY . .`; `.gitignore` does not filter a Docker build context. Local ignored +configuration, `.git`, caches, dependency trees, worktrees, and scratch data +can therefore be sent to the builder. Stop and inspect the context before any +build from a non-clean checkout. + +The images also contain floating inputs: + +- both Go builder image tags omit a patch version or digest; +- Ubuntu base images omit digests; +- the agent image installs multiple Go tools with `@latest`; +- Node comes from the moving `setup_24.x` channel; +- global npm tools are unpinned; +- Compose consumes `archied:latest`, `archie-agent:latest`, and an untagged + watchtower image. + +Do not label a rebuild reproducible. Treat pinning or build-context changes as +change-controlled work. + +`task docker-build` needs registry/network access and a functioning Compose +engine. `task docker-up` additionally pulls images, binds ports 4222, 8222, and +8484, mounts host paths and the container socket, and consumes external +configuration and credentials. Load `archie-run-and-operate` before using it. + +## Separate environment failures from code failures + +| Signature | Classify and branch | +|---|---| +| `go: creating work dir: mkdir /work/tmp/...: read-only file system` | `go env GOTMPDIR` points at a read-only path. Set task-specific `GOTMPDIR` under writable storage and retry. | +| `open .../.cache/go-build/...: read-only file system` | Set a writable `GOCACHE`. | +| `open .../pkg/mod/cache/...tmp: read-only file system` | Set writable `GOMODCACHE` and `GOPATH`; expect network access if the new cache is cold. | +| `listen ...: socket: operation not permitted` | The sandbox denies local listeners. Re-run on a host that permits loopback sockets; do not delete the integration test. | +| `Unable to start NATS Server in Go Routine` after about 10 seconds | First test whether local listeners are permitted. Embedded-NATS tests share this environmental requirement. | +| `cannot auto-sign commit` | Ambient `commit.gpgSign=true` reached a go-git fixture. Current worktree code and fixtures explicitly set repository-local `gpgsign=false`; a recurrence may be a regression. | +| `EAI_AGAIN` for `registry.npmjs.org` | Dependency retrieval failed. Do not diagnose VitePress until installation succeeds. | +| `Failed to obtain podman configuration ... /run/user/.../libpod: read-only file system` | The Docker-compatible CLI cannot initialize its container backend in this sandbox. Move the container check to a suitable host. | +| `TestRunWrapsExternalCommand ... Run() = "\n"` | This is a focused, listener-independent code failure in `internal/skillscript`, not an environment failure. | + +For hermetic test diagnosis only, suppress ambient global Git configuration: + +```bash +env GIT_CONFIG_GLOBAL=/dev/null \ + go test ./internal/worktree/... ./internal/worktreerpc/... -count=1 +``` + +Do not apply `GIT_CONFIG_GLOBAL=/dev/null` to runtime or deployment commands +that intentionally need host credentials or URL rewrites. + +## Use the complete validation matrix + +Choose rows by changed surface, then let `archie-validation-and-qa` decide the +required acceptance set. + +| Evidence | Command | Current snapshot | +|---|---|---| +| Focused Go behavior | `go test ./path/to/package/... -run '^TestName$' -count=1 -v` | Use first; distinguish a real failure from broad-suite noise. | +| Root unit/integration suite | `go test ./... -count=1` | Restricted sandbox also fails listener-dependent packages. A focused `internal/skillscript` test has a genuine failure. | +| Root race suite | `go test -race ./... -count=1` | Not run by `task check`; no current green claim. | +| Vet | `go vet ./...` | Passed on 2026-07-28. | +| Lint | `golangci-lint run ./...` | Failed with 54 findings on 2026-07-28; `task check` does not expose them. | +| Build | `go build -o /tmp/archie-core-archied ./cmd/archied` and the analogous `archie-agent` command | Both passed on 2026-07-28. | +| Tools tests | `go -C tools test ./... -count=1` | Passed on 2026-07-28. | +| Local generated contract parity | Temporary docsgen output plus `cmp --silent` | Passed for 10 schemas on 2026-07-28; the checkout output is untracked. | +| Docs install/build | `pnpm --dir docs-2 install --frozen-lockfile` then `pnpm --dir docs-2 build` | Blocked by restricted network; unknown, not failed. | +| Container build | `task docker-build` | Not verified in the restricted container environment. | +| Repository gate | `task check` | Currently non-green because the root suite reaches the genuine skillscript failure; it may also rewrite files first. | + +Do not hide a baseline failure by reporting only a focused pass. Record the +exact command, environment restrictions, exit status, and first actionable +failure. + +## Cold-start completion checklist + +- [ ] Read `CLAUDE.md`, `ARCHITECTURE.md`, and `Taskfile.yml`. +- [ ] Verify installed commands and compare them with repo declarations. +- [ ] Confirm writable temp and cache paths without changing system variables. +- [ ] Distinguish cold-cache network needs from compilation failures. +- [ ] Build both Go commands. +- [ ] Run a focused test, vet, lint, and the root suite. +- [ ] Run the tools-module tests explicitly. +- [ ] Generate docs contracts to `/tmp` and compare the checkout output. +- [ ] Install and build docs only with authorized registry access. +- [ ] Inspect Docker context and floating inputs before any image build. +- [ ] Record sandbox listener/container restrictions. +- [ ] Hand acceptance decisions to `archie-validation-and-qa`. + +## Provenance and maintenance + +Ground this skill in `CLAUDE.md`, `Taskfile.yml`, `.golangci.yml`, `go.mod`, +`tools/go.mod`, `tools/docsgen/`, `docs-2/package.json`, +`docs-2/pnpm-lock.yaml`, `.github/workflows/docs.yml`, both Dockerfiles, +`docker-compose.yml`, `.gitea/workflows/deploy.yml`, `.gitignore`, +`internal/worktree/`, and the tests named above. + +Re-verify module/toolchain declarations: +`sed -n '1,40p' go.mod; sed -n '1,40p' tools/go.mod; go version; task --version; gofumpt -version; golangci-lint version` + +Re-verify Task coverage: +`sed -n '1,180p' Taskfile.yml; rg -n 'task: lint|go test.*race|go -C tools|docsgen|pnpm' Taskfile.yml` + +Re-verify docs and CI: +`sed -n '1,120p' docs-2/package.json; sed -n '1,120p' .github/workflows/docs.yml; go -C tools test ./... -count=1` + +Re-verify container inputs: +`test -e .dockerignore || echo ABSENT; rg -n '^(FROM|[[:space:]]*image:)|@latest|:latest' Dockerfile Dockerfile.archied docker-compose.yml .gitea/workflows/deploy.yml` + +Re-verify artifact counts: +`git ls-files 'docs-2/node_modules/**' | wc -l; git ls-files '.gotmp/**' | wc -l` + +Re-verify current failures: +`go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v; golangci-lint run ./...` diff --git a/.agents/skills/archie-build-and-env/agents/openai.yaml b/.agents/skills/archie-build-and-env/agents/openai.yaml new file mode 100644 index 000000000..971323ae0 --- /dev/null +++ b/.agents/skills/archie-build-and-env/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Archie Build and Environment" + short_description: "Recreate and verify the Archie toolchain" + default_prompt: "Use $archie-build-and-env to recreate a clean Archie development environment and verify every build surface." diff --git a/.agents/skills/archie-change-control/SKILL.md b/.agents/skills/archie-change-control/SKILL.md new file mode 100644 index 000000000..09c78fd75 --- /dev/null +++ b/.agents/skills/archie-change-control/SKILL.md @@ -0,0 +1,411 @@ +--- +name: archie-change-control +description: "Classify, investigate, plan, gate, review, and accept archie-core changes without trading maintainability for a passing test. Use before changing or approving architecture, Go source, configuration, runtime lifecycle, dependencies, protocols, persistence, security boundaries, deployments, generated documentation, or read-only designs; also use when deciding whether scoped evidence is sufficient, whether an old path must be deprecated or deleted, or whether a change is ready to close." +--- + +# Archie change control + +Protect Archie's quality, not merely its test result. Treat a passing test as +necessary evidence for code changes, never as proof that the design is coherent, +the old path is gone, or production selects the new path. + +## Route to the right sibling + +Use this skill to control a change from classification through acceptance. +Load these siblings for the specialized work: + +| Need | Load | +|---|---| +| Design or revise boundaries, ownership, package structure, or a migration | `archie-architecture-planning-campaign` | +| Find duplication, hidden dead paths, poor names, misplaced responsibilities, or maintainability debt | `archie-technical-accountability` | +| Design tests, reproduce a defect, select QA evidence, or run complete gates | `archie-validation-and-qa` | +| Run, deploy, observe, recover, or roll back a live assembly | `archie-run-and-operate` | + +Do **not** use this skill alone to: + +- conduct an architecture campaign; +- perform a deep code-quality or AST investigation; +- invent a test strategy for a complex behaviour; +- operate production; +- replace the governing decision document for a domain. + +## Use these terms consistently + +| Term | Meaning here | +|---|---| +| Baseline | Recorded behaviour and gate output before the proposed change. | +| Current state | Behaviour selected by the checked-out live code, not a PRD target or branch-only fix. | +| Production wiring | The complete path by which a supported assembly selects, configures, runs, and observes an implementation. | +| Authoritative contract | The source whose semantics the producer and consumer are required to obey; a projection or shared test fake is not authoritative. | +| Compatibility adapter | Temporary code that preserves an older input or caller while migration proceeds, with explicit deletion criteria. | +| Last-known-good | The previously active version proved healthy and retained for restoration. | +| Evidence packet | Commands, outputs, traces, diffs, decisions, and reviews supporting acceptance. | +| Acceptance | Permission to close the controlled work; it is not permission to push, deploy, migrate, or delete. | + +## Apply the non-negotiables + +| Rule | Why it is mandatory | Repository evidence or incident | +|---|---|---| +| Investigate the live call path before planning. | A constructor, registry entry, config field, or test can exist without production ever selecting it. | Missing Compose passthroughs in `22fc0ef` and `d0624b7` left configured secrets absent at runtime. | +| Test the authoritative contract, not a convenient projection. | A best-effort or mirrored interface can pass while the real producer blocks or the peer rejects the exchange. | `6a0bd27`: consuming `TextStream` instead of draining authoritative `FullStream` deadlocked every streamed reply. `3ad57c9`: recreating a buffered reader dropped MCP messages; the harness also masked process-exit behaviour. | +| Preserve compatibility deliberately. Never rely on a decoder ignoring old input. | Silent omission turns a schema edit into an outage. | `1f8588d`: removing `[forge].token_env` compatibility caused both production containers to crash-loop because TOML ignored the old key. | +| Make deployment dependencies explicit and observable. | Hostname, network, secret, mount, and environment assumptions differ between tests and the running Compose assembly. | `37cf089` and `2ac306b`: failed Docker-network auto-detection put workers on the default bridge, so NATS returned “no responders.” | +| Inspect every mechanical or generated edit semantically. Never accept a broad cleanup by count alone. | Formatting, autofix, rebasing, and three-way application can alter behaviour or erase concurrent work. | `9b44bac`: `golangci-lint --fix` introduced a bad `:=` that would have defeated a timeout if it compiled. `affc717`: worktree diffs were based on an older tree and required explicit survival checks. `308c199`: a broad cleanup changed the skillscript command so its test now emits only a newline. | +| Enforce lifecycle transitions and audit atomically. | Ignoring expected state permits lost updates; splitting state and history permits contradictory evidence. | As of 2026-07-28, `internal/store.Store.Transition` ignores `from` and performs two writes. Fix `a7f294e` exists only on `origin/fix/48-transition-ignores-from-status-guard-allowing-lost-updates`, not on `main`; the Nell adapter also does not record equivalent transition history. | +| Keep deterministic constraints outside the proposing model. | A prompt can be ignored to make a test pass. | `CLAUDE.md` requires gates, protected tests, and diff limits to be code-enforced; the model never owns git operations. | +| Require a fresh adversarial reviewer after green. | The implementer is biased toward the path it just made pass. | `CLAUDE.md` makes a memory-independent review mandatory and blocks completion on surviving findings. | + +## Classify the change + +Classify every affected surface. For a composite change, apply the union of all +required controls and use the highest-risk class. + +| Class | Examples | Minimum control | +|---|---|---| +| Read-only investigation | Review, diagnosis, inventory, impact map | Do not mutate. Cite live code, tests, history, and unresolved uncertainty. | +| Design or documentation | PRD, ADR-like decision, architecture guide, skill | Separate current facts from approved target and open candidates. Validate links/format. Do not imply implementation. | +| Source | Go behaviour, refactor, API, workflow | Current-state map, red-green, scoped iteration, architecture and maintainability review, final relevant gates. | +| Configuration | Decoder, default, env name, overlay, secret reference, setting owner | Old/new input fixtures, precedence/default proof, production composition trace, invalid-input behaviour, explicit rollback. | +| Runtime lifecycle | Start, stop, reload, concurrency, stream, retry, health | Cancellation/backpressure/failure tests, race test, bounded retry, shutdown and rollback proof. | +| Dependency | Root or `tools` module dependency/version | Adoption rationale, API/behaviour delta, both module manifests as applicable, transitive/security review, reverse plan. | +| Protocol | MCP, NATS, RPC, subprocess, JSON/wire schema | Version and compatibility matrix, independent-peer or recorded-wire evidence, malformed/partial/multi-message tests. | +| Persistence | SQLite, NellDB, schema, lifecycle state, migrations | Old-data fixture, legal-transition and concurrency tests, atomic state/audit proof, backup/rollback strategy. | +| Security or trust boundary | Secret flow, plugins, tools, containers, identity, authorization | Threat/authority analysis, deny tests, deterministic enforcement, fresh security review, no “subprocess equals sandbox” claims. | +| Deployment | Dockerfile, Compose, image/tag, env passthrough, volume/network | Exact assembly validation, secret-name-to-container trace, health observation, previous image/config recovery plan. | +| Generated documentation | `tools/docsgen`, registries, generated JSON, VitePress | Generator tests, byte-for-byte drift check, site build, generated-vs-handwritten ownership check. | + +Escalate the risk class when the change crosses a process boundary, changes +stored or wire data, changes operator-visible defaults, alters authorization, +removes compatibility, or can affect a live deployment. + +## Execute the control loop + +### 1. Establish authority and scope + +For implementation work, start from the existing Beads issue and claim it. +Create durable work before writing code if no issue exists. Do not create a +Markdown task list. + +```bash +bd prime +: "${BEADS_ISSUE_ID:?set BEADS_ISSUE_ID to the target issue}" +bd show "$BEADS_ISSUE_ID" +bd update "$BEADS_ISSUE_ID" --claim +``` + +For a review or investigation, remain read-only unless the user separately +authorizes implementation. + +Record: + +- the requested outcome and explicit non-goals; +- every selected change class; +- files and domains believed to be in scope; +- user authority for source, config, deployment, dependency, and destructive + operations; +- whether another session owns overlapping files. + +### 2. Protect concurrent work + +Inspect before editing: + +```sh +git status --short +git diff --stat +git worktree list --porcelain +``` + +Treat every pre-existing change as somebody else's. Stop before overlapping it +unless ownership and integration order are known. Never discard, reset, or +silently reformat unrelated changes. + +Partition parallel work by non-overlapping file ownership. Before applying an +agent result based on another tree, compare its base and verify that every +intervening semantic fix survives. The `affc717` history demonstrates why a +cleanly applied diff is not proof of preservation. + +Do not run broad autofix against a shared dirty tree. `task check` and +`task fmt` are broad mutators; isolate them and inspect their complete diff. + +### 3. Map the current state before proposing a change + +Read `CLAUDE.md`, `ARCHITECTURE.md`, `docs/prds/01-project-management.md`, and +the focused decision document linked from the architecture index. + +For the selected behaviour, trace all of: + +- entry points under `cmd/` and application composition; +- constructors, registries, interfaces, adapters, and concrete selection; +- every caller and consumer, including RPC/process peers; +- settings, defaults, overlays, secrets, and deployment passthrough; +- state ownership, persistence, lifecycle, cancellation, and recovery; +- tests and what they do **not** exercise; +- duplicated implementations, compatibility adapters, generated copies, and + apparently dead paths; +- git history for rejected, stalled, reverted, or branch-only work; +- documents that disagree with live code. + +Use read-only evidence: + +```bash +# Guard: verify repository root first +git rev-parse --show-toplevel >/dev/null || { echo 'run from repo root' >&2; exit 1; } +: "${ARCHIE_SYMBOL:?set ARCHIE_SYMBOL to the symbol or config key}" +rg -n "$ARCHIE_SYMBOL" cmd internal config*.toml docker-compose.yml docs +: "${ARCHIE_PACKAGE:?set ARCHIE_PACKAGE to the package path relative to repo root}" +go list -deps "./internal/$ARCHIE_PACKAGE/..." +: "${ARCHIE_PATHS:?set ARCHIE_PATHS to the space-separated affected paths}" +git log --all --oneline -- $ARCHIE_PATHS +git blame -- $ARCHIE_PATHS +``` + +Do not ask the user for a fact the repository can reveal. Ask only when a real +product, compatibility, ownership, or risk decision remains. + +### 4. Write the change brief + +Do not begin implementation until the brief answers: + +| Question | Required answer | +|---|---| +| What owns this behaviour? | One cohesive domain/capability and the governing decision document. | +| Where does production select it? | Exact entry point-to-implementation path. “Registered” is insufficient. | +| What changes and what stays stable? | Behavioural contract, invariants, non-goals, and affected consumers. | +| What does this supersede? | Every older or parallel path, with keep/merge/deprecate/delete decision. | +| What gets deleted? | Obsolete code, compatibility adapters, duplicated config, tests, and docs, or a justified reason to retain each. | +| What proves failure first? | A behavioural red test that fails for the intended reason, not a compile error. | +| What proves maintainability? | Ownership, dependency direction, naming, size, duplication, and dead-path checks. | +| What is the compatibility plan? | Old/new config, protocol, data, caller, and rollout combinations. | +| How is it reversed? | Last-known-good state and evidence that reversal preserves data and service. | +| What remains uncertain? | Explicit open/candidate claims; never convert a hunch into a requirement. | + +If adding a feature makes an existing path redundant, deletion is part of the +feature unless compatibility has a named owner, deadline or deletion +criterion, and test. Do not leave two active paths merely because deleting the +old one is harder. + +Route boundary or ownership uncertainty through +`archie-architecture-planning-campaign` before coding. Route unlocatable impact, +duplication, or dead-path uncertainty through `archie-technical-accountability`. + +### 5. Capture a baseline + +Run the narrowest non-mutating checks that exercise the affected area before +the red test. Preserve exact command, exit status, and output. + +Example for one Go package: + +```sh +go test ./internal/gateway/... -count=1 +go vet ./internal/gateway/... +golangci-lint run ./internal/gateway/... +gofumpt -l internal/gateway +``` + +Distinguish: + +- **clean baseline**: proceed; +- **unrelated known failure**: preserve its exact signature and escalate; +- **failure in the affected surface**: do not build on it; repair or split the + work with explicit authority; +- **environment failure**: prove it is environmental before classifying it as + non-code. + +Do not call a baseline green when a command was skipped. + +### 6. Apply red-green without surrendering design + +1. Add a behavioural test for the intended contract. +2. Run it and capture a meaningful failure. +3. Implement the smallest coherent design, not the smallest patch. +4. Run the focused test until green. +5. Add every relevant error, boundary, compatibility, cancellation, and + concurrency case. +6. Re-read every changed non-test file for ownership, clarity, duplication, + unused branches, and superseded paths. + +Load `archie-validation-and-qa` for the test design. Load +`archie-technical-accountability` before accepting “works but ugly” code. + +Never weaken or rewrite the red test merely to admit the implementation. +Environmental test protection is preferable to a prompt-only prohibition. + +### 7. Prove production wiring + +Demonstrate all applicable links: + +```text +external input + -> decoder/adapter + -> application composition + -> selected implementation + -> state or external effect + -> observable outcome +``` + +Test at the highest practical seam. A package unit test does not prove that +`cmd/archied` supplies the new setting, registers the implementation, forwards +the environment variable, chooses the right mode, or exposes the result. + +For configuration, test the deployed legacy form and the new form. Verify both +the source environment and `docker-compose.yml` passthrough. For protocols, +verify bytes/messages with an independently implemented peer or fixture rather +than a client and server sharing the same wrong assumption. + +### 8. Make rollback executable + +Identify last-known-good **before** changing runtime state. Define the trigger, +owner, commands or deterministic mechanism, data consequences, and health check +for restoration. + +| Change | Required rollback evidence | +|---|---| +| Source or dependency | Exact prior version plus proof that reverting does not leave incompatible data, config, or generated output. | +| Configuration | Prior accepted input and effective values, secret-safe diff, reload/restart consequence, and health check. | +| Protocol | Old/new peer matrix; retain the old path until mixed-version operation or coordinated cutover is proved. | +| Persistence | Backup/restore or reversible migration rehearsal against an old-data fixture; never call a destructive forward-only migration rollback-safe. | +| Deployment | Previous image digest and config, exact supported assembly, restoration command, and post-restore observation. | +| Generated documentation | Regenerate from authoritative definitions; never recover by hand-editing generated JSON. | + +The candidate-promotion and automatic last-known-good protocol in +`docs/prds/architecture/safe-change-and-recovery.md` is an approved requirement, +but its exact Go contracts and atomicity boundary are explicitly still under +design as of 2026-07-28. Do not claim Archie currently provides it. For live +work, route the concrete manual or implemented recovery procedure through +`archie-run-and-operate`. + +### 9. Run the required evidence set + +Use scoped checks while iterating. Use a scoped final gate only for a genuinely +isolated single-package change allowed by `CLAUDE.md`. Require full and +class-specific checks for cross-package, configuration, runtime, dependency, +protocol, persistence, security, deployment, or generated-documentation work. + +`task check` is repository doctrine but is not the complete evidence set: + +```sh +task check +golangci-lint run ./... +go test -race ./... -count=1 +go -C tools test ./... -count=1 +go -C tools vet ./... +``` + +For generated contracts and the site, run the current commands: + +```sh +go -C tools test ./docsgen -count=1 +go -C tools run ./docsgen --repo-root .. --out /tmp/archie-contracts.check.json +cmp /tmp/archie-contracts.check.json docs-2/data/generated/contracts.json +pnpm --dir docs-2 build +``` + +Inspect the diff after any formatter, fixer, generator, or `task check`. A zero +exit status does not authorize unrelated edits. + +### 10. Run fresh adversarial review + +Give a reviewer with no implementation memory the requirement, governing +architecture, current diff, and raw validation output. Require findings first; +do not let that pass silently fix its own findings. + +Require review of: + +- production selection and every affected consumer; +- correctness and error propagation; +- architecture ownership and dependency direction; +- obsolete, duplicate, disconnected, or single-use paths; +- config/default/identity hardcoding; +- interface satisfaction and wire compatibility; +- nil, cancellation, goroutine, race, transaction, and rollback hazards; +- whether tests prove the contract rather than mirror the implementation. + +Resolve every blocking and important finding, rerun affected checks, then use a +fresh final pass if semantics changed. Surviving findings block acceptance. + +### 11. Accept or stop + +Accept only when the evidence packet contains: + +- issue/scope and all change classes; +- current-state impact map and governing decisions; +- baseline, red, green, and final command outputs; +- production-wiring proof; +- compatibility, deprecation, deletion, and rollback decisions; +- architecture and maintainability review; +- fresh adversarial review with zero surviving blocking or important findings; +- explicit uncertainties and follow-up ownership; +- no unexplained diff. + +Do not close a Beads issue until its acceptance criteria and the session close +protocol are satisfied. Do not push, deploy, migrate, or delete data without +separate authority. + +## Know the current gate gaps + +**Volatile snapshot: 2026-07-28. Re-verify before every acceptance decision.** + +- `task check` runs `task fmt`, which executes `gofumpt -w .` and + `go fix ./...`; it then executes `go fix ./...` a second time before vet, + build, and root tests. It mutates source. +- `task check` does not run `task lint`, race tests, the nested `tools` module, + docsgen drift checks, or the VitePress build. +- Root `go test ./...` does not cross the nested `tools/go.mod` boundary. +- `.gitea/workflows/deploy.yml` builds and pushes images without a Go quality + job. `.github/workflows/docs.yml` installs and builds VitePress but does not + run the Go gate or docsgen. +- `go test ./internal/skillscript -count=1` currently fails + `TestRunWrapsExternalCommand`: `Run() = "\n"`. +- The approved generated-documentation document describes future + `task docs:*` and `docsgen check` commands, but neither exists in the current + `Taskfile.yml`/CLI. Use the current commands above. +- No `task deadcode` target exists. Never report it as executed. + +Repository doctrine still requires a clean relevant gate. A known baseline +failure is not permission to report completion. Either repair it under +separately controlled scope or report the work blocked with scoped no-regression +evidence. + +## Escalate instead of improvising + +Stop and obtain a decision when: + +- a requested feature conflicts with an approved architecture decision; +- ownership or the production selection path remains ambiguous after research; +- a new path overlaps an existing feature and no deprecation/deletion decision + exists; +- compatibility requires supporting two behaviours with no sunset criterion; +- a migration can lose data or cannot demonstrate restoration; +- a runtime/config change cannot preserve last-known-good state; +- a protocol change lacks an independent interoperability oracle; +- a security rule exists only in a prompt; +- a baseline failure touches the same surface; +- concurrent work overlaps the files or semantics; +- the required full gate cannot run or has an unexplained failure; +- an adversarial finding survives. + +Do not escalate discoverable facts or ordinary implementation choices. Bring +the evidence, the smallest decision required, and the consequences of each +option. + +## Provenance and maintenance + +Re-verify commands, gates, current defects, and incidents before updating this +skill: + +```sh +sed -n '1,220p' Taskfile.yml +sed -n '1,260p' CLAUDE.md +find .gitea/workflows .github/workflows -maxdepth 1 -type f -print +sed -n '1,140p' .gitea/workflows/deploy.yml +sed -n '1,180p' .github/workflows/docs.yml +sed -n '1,130p' docs/prds/architecture/safe-change-and-recovery.md +sed -n '1,120p' docs/prds/architecture/package-review.md +sed -n '300,350p' docs/prds/architecture/agent-system.md +sed -n '255,280p' internal/store/store.go +sed -n '270,305p' internal/nell/adapter.go +go test ./internal/skillscript -count=1 +git log --all --format='%h %ad %s' --date=short --grep='FullStream\|MCP transport framing\|token_env\|container Docker network\|autofix\|Transition() ignores' -i +git branch -a --contains a7f294e +rg -n 'docs:|deadcode' Taskfile.yml +``` diff --git a/.agents/skills/archie-change-control/agents/openai.yaml b/.agents/skills/archie-change-control/agents/openai.yaml new file mode 100644 index 000000000..6b0911c68 --- /dev/null +++ b/.agents/skills/archie-change-control/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Archie Change Control" + short_description: "Plan, gate, and accept Archie changes safely" + default_prompt: "Use $archie-change-control to classify, plan, verify, review, and accept this archie-core change." diff --git a/.agents/skills/archie-codebase-discovery/SKILL.md b/.agents/skills/archie-codebase-discovery/SKILL.md new file mode 100644 index 000000000..012b2d641 --- /dev/null +++ b/.agents/skills/archie-codebase-discovery/SKILL.md @@ -0,0 +1,432 @@ +--- +name: archie-codebase-discovery +description: "Trace Archie behavior and blast radius through Go source, types, state, persistence, transports, consumers, tests, configuration, production composition, and target architecture. Load before changing or planning a non-trivial feature, refactor, config field, interface, persistence path, workflow, channel, plugin, or agent execution path; also load to investigate duplicate behavior, hidden dead code, constructor bypasses, package dependencies, decoded-but-unwired configuration, or uncertainty about what a symbol actually affects." +--- + +# Discover the Archie codebase + +Use evidence from the current checkout to explain a behavior before changing it. +Produce a trace that another engineer can reproduce. Do not stop at "tests pass" +or "grep found one call." + +Volatile tool facts below were verified on **2026-07-28**. Re-check them before +depending on exact versions or subcommands. + +## Scope and routing + +This skill is read-only. Use it to establish what exists, who owns state, which +paths are live, and what a proposed change would displace. + +Do **not** use it as: + +| Need | Load instead | +|---|---| +| Assign ownership, justify deletion, or record cleanup debt | `archie-technical-accountability` | +| Design boundaries, packages, migrations, or a future architecture | `archie-architecture-planning-campaign` | +| Collect runtime, coverage, complexity, latency, or production measurements | `archie-diagnostics-and-tooling` | +| Turn a hypothesis into a controlled evidence campaign | `archie-research-methodology` | +| Learn NellDB's API, document model, MVCC, HLC, or persistence semantics | `archie-nelldb` | +| Implement or approve a behavior-changing patch | Route the resulting trace through `archie-change-control` | + +Do not delete, move, or redesign code while running this skill. A discovery can +recommend a next investigation, but an ownership or architecture decision needs +the sibling skill named above. + +## Define the evidence terms + +- **Composition root:** executable code that selects concrete implementations + and connects them. Archie's principal composition root is + `cmd/archied/main.go`; the sandbox worker has its own root under + `cmd/archie-agent/`. +- **Production wiring:** a path selected by a shipped entrypoint under an actual + config/mode branch. A constructor, decoder, or passing unit test is not wiring. +- **State owner:** the component with authority to validate and persist a state + transition, not every component that holds a copy. +- **Target PRD:** an approved description under `docs/prds/` of where the system + should go. It is not proof that current code works that way. +- **Candidate:** a result from text or syntax search that still requires + type-aware or composition-root confirmation. + +## Establish a reproducible baseline + +Run from the repository root: + +```sh +go version +go env GOMOD GOWORK GOOS GOARCH +gopls version +golangci-lint version +staticcheck -version +rg --version | sed -n '1p' +``` + +Record missing tools instead of silently substituting a weaker claim. As of +2026-07-28 this checkout had Go 1.26.5, gopls 0.23.0, +golangci-lint 2.12.2, staticcheck 2026.1 (v0.7.0), and `rg`. `go tool` listed +no `callgraph` command. Do not write `go tool callgraph`; use +`gopls call_hierarchy`. + +Use writable caches when the host's default Go caches are read-only: + +```sh +export GOCACHE="${TMPDIR:-/tmp}/archie-discovery-gocache" +export XDG_CACHE_HOME="${TMPDIR:-/tmp}/archie-discovery-xdg" +export GOLANGCI_LINT_CACHE="${TMPDIR:-/tmp}/archie-discovery-lint" +export GOTMPDIR="${TMPDIR:-/tmp}" +export GOPROXY=off +export GOFLAGS=-mod=readonly +``` + +`GOPROXY=off` prevents discovery from fetching dependencies. If an uncached +module is required, report that as an environment blocker; do not turn a +read-only investigation into dependency mutation. + +Inventory module boundaries before interpreting `./...`: + +```sh +find . \( -path './.git' -o -path './.references' -o -path './.claude/worktrees' -o -name node_modules \) -prune -o -name go.mod -print +go list -m -f '{{.Path}} {{.GoVersion}}' +go -C tools list -m -f '{{.Path}} {{.GoVersion}}' +``` + +The root module and `tools/` are separate modules as of 2026-07-28. A root +`go test ./...` or `go list ./...` does not validate `tools/`. + +## Build the behavior trace + +Write the question first: + +```text +Behavior: +Observable input: +Expected externally visible output: +State that may change: +Modes/configurations to compare: +``` + +Then traverse every row in order. Mark a row `N/A` only with evidence. + +| Step | Find | Required evidence | +|---:|---|---| +| 1 | Entrypoint | `main`, handler, poller, RPC subject, or tool registration that admits the input | +| 2 | Construction | Constructor and every direct struct literal that can create the component | +| 3 | Contract | Interface, wire type, command, event, or public method actually crossed | +| 4 | Implementation | All type-valid implementations, then the one selected in each relevant mode | +| 5 | State owner | The function that validates the transition and owns concurrency/transaction rules | +| 6 | Persistence | Store adapter, schema/key/document, serialization, and reload/recovery path | +| 7 | Event/transport | Publish/send and subscribe/receive sides, subject/framing, timeout, retry, and acknowledgement | +| 8 | Consumer | Callers and downstream readers, including UI, channel, daemon, agent, and reconciliation paths | +| 9 | Tests | Unit, integration, contract, architecture, and production-composition tests; identify absent layers | +| 10 | Configuration | Decode, default, validation, normalization/copy, composition-root consumption, and deploy passthrough | +| 11 | Target architecture | Current-to-target mapping in `docs/prds/`; label gaps instead of describing target text as current | + +Start at these verified anchors: + +| Concern | Current anchor | +|---|---| +| Resident daemon | `cmd/archied/main.go` → `run()` → `daemon.Daemon` | +| Sandboxed worker | `cmd/archie-agent/main.go`, `cmd/archie-agent/taskrun.go` | +| Task orchestration | `internal/daemon/daemon.go`, `internal/workflow/` | +| Task contracts and SQLite | `internal/store/interface.go`, `internal/store/` | +| Production task persistence | `internal/nell/adapter.go`; selected by `nell.OpenStore` in `cmd/archied/main.go` | +| RPC split | `internal/{nats,taskrun,natsrpc,storerpc,forgerpc,worktreerpc}/` | +| Chat and channels | `internal/gateway/`, `internal/channels/` | +| Configuration | `internal/config/`, `config.example.toml`, `config.docker.toml` | +| Production/deploy shape | `cmd/archied/main.go`, `docker-compose.yml`, `.gitea/workflows/deploy.yml` | +| Target map | `docs/prds/01-project-management.md` and linked `docs/prds/architecture/*.md` | + +Do not assume this table is complete after code moves. Re-find anchors with +`go list` and `gopls`. + +## Use syntax, type, and call evidence + +### Map packages before reading files + +List source and test files as the Go tool sees them: + +```sh +go list -f '{{.ImportPath}}|go={{join .GoFiles ","}}|tests={{join .TestGoFiles ","}}|imports={{join .Imports ","}}' ./internal/store +go list -json ./internal/store +``` + +Map internal dependency direction: + +```sh +.claude/skills/archie-codebase-discovery/scripts/package-edges.sh ./internal/... +``` + +Treat imports as dependency evidence, not ownership proof. Compare the result +with `docs/prds/architecture/dependencies-and-contracts.md` only after +distinguishing current from target. + +### Resolve symbols with gopls + +Use a 1-indexed `file:line:column` position on the identifier: + +```sh +gopls symbols internal/store/interface.go +gopls definition cmd/archied/main.go:154:18 +gopls references -d internal/store/interface.go:25:2 +gopls implementation internal/store/interface.go:16:6 +gopls call_hierarchy internal/store/interface.go:25:2 +``` + +Run all four queries together: + +```sh +.claude/skills/archie-codebase-discovery/scripts/trace-go-position.sh internal/store/interface.go:25:2 +``` + +Use `gopls implementation` on interfaces and interface methods. Use +`gopls references -d` on struct fields, functions, constants, and types. +`gopls call_hierarchy` exposes callers missed by a search for one textual call +shape. Read the resolved bodies; tool output is an index, not the explanation. + +Inspect exported contracts and available tests: + +```sh +go doc ./internal/store.TaskStore +go test ./internal/store -list '.' +rg -n '^func Test|^func Benchmark|^func Fuzz' internal/store +``` + +`go test -list` compiles the package and lists matching top-level tests; it does +not execute them. + +### Generate AST candidates for construction + +Find type declarations, direct composite literals, and functions returning a +named type: + +```sh +.claude/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh Daemon . +.claude/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh -tests Task . +``` + +The helper parses Go ASTs; it does not infer the package identity of an +unqualified name. Treat results as candidates, then confirm each with +`gopls definition` or `gopls references`. Production-only output is the default; +pass `-tests` to expose test-only construction. + +## Run focused discovery recipes + +### Find duplicate behavior paths + +1. Run the configured duplicate-code detector: + + ```sh + golangci-lint run --enable-only=dupl ./internal/... + ``` + +2. Search for the externally visible operation, status, subject, or log phrase: + + ```sh + rg -n 'Transition\(|PublishTask\(|ClaimNext\(|StatusWaitingHuman' cmd internal + ``` + +3. Trace each candidate back to an entrypoint and forward to its state owner. +4. Compare mode branches: in-process, subprocess, NATS/container, + single-identity, and multi-identity where applicable. +5. Report semantic duplicates even when the code is textually different. +6. Do not call compatibility paths obsolete until production composition, + deployed config, persistence compatibility, and target removal criteria agree. + +`dupl` finds similar syntax, not two different implementations of one +responsibility. + +### Find unused-but-compiled code + +Run the available unexported-code check: + +```sh +staticcheck -checks=U1000 ./internal/... +``` + +For every suspect: + +1. Run `gopls references -d` on the declaration. +2. Search registration tables, `init`, reflection/Yaegi symbols, templates, + JSON/TOML/YAML tags, RPC subjects, plugin manifests, and string dispatch. +3. Check build tags and OS-specific files from `go list -json`. +4. Search both executable composition roots. +5. Separate production, test-only, compatibility, generated, and unreachable + paths. + +`U1000` does not prove exported code, reflection targets, wire names, or +registrations are dead. Zero type references does not prove a string-addressed +capability is dead. Route any deletion decision to +`archie-technical-accountability`. + +### Find interface implementations + +1. Put the cursor position on the interface name and run + `gopls implementation`. +2. Put it on each important method and run `gopls implementation` again. +3. Find compile-time assertions: + + ```sh + rg -n 'var _ .*=' --glob '*.go' cmd internal + ``` + +4. Trace which implementation the composition root selects for each mode. +5. Inspect test doubles separately; they establish substitutability only for + exercised behavior. + +An interface with three valid implementers still has only the implementation +selected by `cmd/archied` on a given production branch. + +### Find struct-field consumers + +1. Run `gopls references -d` on the **field declaration**, not its common name. +2. Trace assignments into the field and reads out of it separately. +3. Follow copies and normalization methods such as `ForTask`/`ToConfig`. +4. Check JSON/TOML/YAML tags and reflection separately; gopls cannot turn a + decoder's string key into a field reference. +5. Compare production and `_test.go` references. + +A field read only while constructing an unused object is not an effective +consumer. + +### Detect constructor bypasses + +1. Run `scan-go-type-syntax.sh Type .` without tests. +2. Inspect every `literal` outside the owning package. +3. Compare required validation/defaulting in constructors with direct literals. +4. Repeat with `-tests`; record tests that exercise impossible production + states. +5. Use `gopls references` on the constructor and type to catch aliases and + indirect uses the syntax helper cannot resolve. + +Do not prohibit literals mechanically. Composition roots and test fixtures may +need them, but bypassed invariants must be explicit. + +### Prove package dependency direction + +1. Run `package-edges.sh` for the smallest package pattern. +2. Run `go list -deps -json ` when standard-library and third-party + edges matter. +3. Identify cycles prevented by interfaces, adapters, or RPC packages. +4. Compare current edges with the target dependency rules. +5. Treat a new shared package as an architecture decision, not a quick cycle fix. + +### Find decoded-but-unused configuration + +For each field, prove this chain: + +```text +file/key → decoder → default → validation → normalization/copy +→ composition-root read → concrete component → observable behavior +``` + +Use: + +```sh +rg -n 'toml:"|yaml:"|json:"' internal/config +rg -n 'LoadOverlay|LoadDir|finalize|ForTask|ToConfig' internal/config cmd +``` + +Then run `gopls references -d` on the exact field. Check +`config.example.toml`, `config.docker.toml`, `docker-compose.yml`, config tests, +and `cmd/archied/main.go`. + +As of 2026-07-28 `cmd/archied` calls `config.LoadOverlay`; the separate +`config.LoadDir` feature-file loader exists and has tests but was not selected +by that production entrypoint. Re-verify this before using the fact. Decoder +coverage proves accepted syntax, not deployed behavior. + +### Prove production composition + +1. Start at `cmd/archied/main.go:run`, not at the package under investigation. +2. Record the config condition for each branch. +3. Follow concrete construction into `daemon.Daemon` and gateway start + functions. +4. For container/NATS behavior, also trace `cmd/archie-agent`. +5. Trace both sides of every RPC/transport and its error/timeout path. +6. Read contract/architecture tests, including files matching + `*contract_test.go` and `*architecture_test.go`. +7. Confirm deploy inputs in Compose and CI; do not infer remote runtime state + from repository files. + +### Trace NellDB without guessing + +Treat `internal/store` as the application contract and `internal/nell` as one +adapter. Do not transfer SQLite behavior to NellDB by analogy. + +```sh +go doc github.com/samcharles93/NellDB.Store +go doc github.com/samcharles93/NellDB/sdk.DocDB +gopls implementation internal/store/interface.go:16:6 +rg -n 'sdk\.New|\.Get\(|\.Put\(|AllDocs|taskKey|docToTask|taskFields' internal/nell +``` + +Trace `store.Task` field → `sdk.Doc` key → read/conversion → locking or MVCC +around update/transition → reopen/recovery test. The adapter currently uses +`tasks` and `events` collections and performs scans for several queries; verify +those facts in `internal/nell/adapter.go` before relying on them. As of +2026-07-28, `Adapter.Transition` neither locks nor checks its `from` argument; +record that as observed current behavior, not a target promise. NellDB's +`_id`/`_rev`, HLC, and conflict semantics come from the dependency API, while +Archie's legal task transitions remain an Archie concern. Route deeper domain +and persistence background to `archie-nelldb`. + +## Reject false confidence + +| Weak evidence | Why it fails | Required correction | +|---|---|---| +| One `rg` result | Misses interface dispatch, aliases, generated registration, reflection, and string-addressed protocols | Use gopls, AST candidates, package edges, and composition | +| Green unit test | May construct a component directly and bypass actual config, lifecycle, or transport | Add or inspect composition/contract/integration evidence | +| Fake client and fake server agree | Both sides can mirror the same wrong framing, subject, or state assumption | Compare an independent spec/implementation or real boundary fixture | +| High coverage | Does not establish ownership, maintainability, deprecation, or correct mode selection | Trace authority and current production selection | +| Constructor exists | Does not prove callers use it | Find struct literals and type-aware references | +| Config field decodes | Does not prove the executable reads it | Complete the config-to-observable chain | +| Target PRD says it | Describes required destination, not necessarily current code | Cite current implementation and label the gap | + +## Produce the discovery handoff + +End with these sections: + +1. **Behavior trace:** one row per traversal step with `path:line`, symbol, and + current responsibility. +2. **Mode matrix:** mode/config branch → concrete implementation → state store + → transport → consumer. +3. **State and authority:** owner, copies, persistence, transition rules, and + recovery. +4. **Blast radius:** callers, consumers, tests, config, deploy wiring, docs, and + compatibility paths. +5. **Duplication/deprecation ledger:** each candidate, evidence it is live or + dead, replacement, and objective removal gate. +6. **Current-to-target gap:** current fact, target PRD, migration implication; + never blend the two. +7. **Unknowns:** exact command attempted, output/blocker, and next evidence + needed. + +Do not propose implementation until the trace can answer: + +- What entrypoint selects this path? +- Which component owns the state and invariant? +- Which parallel or older path would the feature replace or deprecate? +- Which production modes and persisted data must remain compatible? +- Which evidence would falsify the current understanding? + +Short successes are acceptable, but complete one vertical trace rather than +collecting many shallow search hits. + +## Provenance and maintenance + +Repository evidence verified on 2026-07-28: +`cmd/archied/main.go`, `cmd/archie-agent/`, `internal/{config,daemon,nell,store,workflow,tools/mcp}/`, +`Taskfile.yml`, `.golangci.yml`, `go.mod`, `tools/go.mod`, +`docker-compose.yml`, `.gitea/workflows/deploy.yml`, `CLAUDE.md`, +`ARCHITECTURE.md`, and `docs/prds/`. + +Re-verify tools: `go version && gopls version && golangci-lint version && staticcheck -version && go tool` + +Re-verify entrypoints: `rg -n '^func main|^func run' cmd/archied cmd/archie-agent` + +Re-verify config selection: `rg -n 'config\.(Load|LoadOverlay|LoadDir)\(' cmd internal --glob '*.go'` + +Re-verify modules: `find . \( -path './.git' -o -path './.references' -o -path './.claude/worktrees' -o -name node_modules \) -prune -o -name go.mod -print` + +Re-verify production construction: `rg -n '&daemon\.Daemon\{|nell\.OpenStore|registerTaskRPCServers|startGateways' cmd/archied/main.go` + +Re-verify contract tests: `find internal -type f \( -name '*contract_test.go' -o -name '*architecture_test.go' \) -print | sort` diff --git a/.agents/skills/archie-codebase-discovery/agents/openai.yaml b/.agents/skills/archie-codebase-discovery/agents/openai.yaml new file mode 100644 index 000000000..2957f7f74 --- /dev/null +++ b/.agents/skills/archie-codebase-discovery/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Archie Codebase Discovery" + short_description: "Trace Archie behavior from entrypoint to production" + default_prompt: "Use $archie-codebase-discovery to trace this behavior through production wiring before proposing a change." diff --git a/.agents/skills/archie-codebase-discovery/scripts/package-edges.sh b/.agents/skills/archie-codebase-discovery/scripts/package-edges.sh new file mode 100755 index 000000000..e2e833674 --- /dev/null +++ b/.agents/skills/archie-codebase-discovery/scripts/package-edges.sh @@ -0,0 +1,36 @@ +#!/bin/sh +set -eu + +if [ "$#" -gt 1 ]; then + printf '%s\n' "usage: $0 [go-package-pattern]" >&2 + exit 2 +fi + +command -v go >/dev/null 2>&1 || { + printf '%s\n' "error: go is required" >&2 + exit 127 +} + +pattern=${1:-./...} +cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"} +mkdir -p "$cache_root/go-build" "$cache_root/tmp" + +export GOCACHE="$cache_root/go-build" +export GOTMPDIR="$cache_root/tmp" +export GOPROXY=off +export GOFLAGS=-mod=readonly + +module_path=$(go list -m -f '{{.Path}}') + +go list -f '{{.ImportPath}}{{range .Imports}}{{printf "\t%s" .}}{{end}}' "$pattern" | + awk -F ' ' -v module="$module_path" ' + { + from = $1 + for (i = 2; i <= NF; i++) { + if ($i == module || index($i, module "/") == 1) { + printf "%s -> %s\n", from, $i + } + } + } + ' | + LC_ALL=C sort -u diff --git a/.agents/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.go b/.agents/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.go new file mode 100644 index 000000000..6e562e2bc --- /dev/null +++ b/.agents/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.go @@ -0,0 +1,176 @@ +// Command scan-go-type-syntax reports syntax-level construction candidates for +// a named Go type. It deliberately uses only the standard library and never +// writes to the inspected tree. +package main + +import ( + "bufio" + "flag" + "fmt" + "go/ast" + "go/parser" + "go/token" + "io/fs" + "os" + "path/filepath" + "sort" + "strings" +) + +type finding struct { + path string + line int + column int + kind string + detail string +} + +func main() { + includeTests := flag.Bool("tests", false, "include *_test.go files") + flag.Usage = func() { + fmt.Fprintf(flag.CommandLine.Output(), "usage: %s [-tests] TypeName [root]\n", os.Args[0]) + flag.PrintDefaults() + } + flag.Parse() + if flag.NArg() < 1 || flag.NArg() > 2 { + flag.Usage() + os.Exit(2) + } + + typeName := flag.Arg(0) + root := "." + if flag.NArg() == 2 { + root = flag.Arg(1) + } + if !token.IsIdentifier(typeName) { + fmt.Fprintf(os.Stderr, "error: %q is not a Go identifier\n", typeName) + os.Exit(2) + } + + results, err := scan(root, typeName, *includeTests) + if err != nil { + fmt.Fprintf(os.Stderr, "error: %v\n", err) + os.Exit(1) + } + + out := bufio.NewWriter(os.Stdout) + defer out.Flush() + fmt.Fprintln(out, "kind\tlocation\tdetail") + for _, result := range results { + fmt.Fprintf(out, "%s\t%s:%d:%d\t%s\n", + result.kind, result.path, result.line, result.column, result.detail) + } +} + +func scan(root, typeName string, includeTests bool) ([]finding, error) { + fset := token.NewFileSet() + var results []finding + + err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error { + if walkErr != nil { + return walkErr + } + if entry.IsDir() { + if path == root { + return nil + } + name := entry.Name() + if strings.HasPrefix(name, ".") || name == "node_modules" || + name == "vendor" || name == "bin" { + return filepath.SkipDir + } + return nil + } + if filepath.Ext(path) != ".go" { + return nil + } + if !includeTests && strings.HasSuffix(path, "_test.go") { + return nil + } + + file, err := parser.ParseFile(fset, path, nil, 0) + if err != nil { + return fmt.Errorf("parse %s: %w", path, err) + } + + ast.Inspect(file, func(node ast.Node) bool { + switch node := node.(type) { + case *ast.TypeSpec: + if node.Name.Name == typeName { + results = appendFinding(results, fset, node.Name.Pos(), + path, "declaration", "type "+node.Name.Name) + } + case *ast.CompositeLit: + if matchesType(node.Type, typeName) { + results = appendFinding(results, fset, node.Type.Pos(), + path, "literal", "direct composite literal of "+typeName) + } + case *ast.FuncDecl: + if returnsType(node.Type.Results, typeName) { + results = appendFinding(results, fset, node.Name.Pos(), + path, "returns-type", "func "+node.Name.Name) + } + } + return true + }) + return nil + }) + if err != nil { + return nil, err + } + + sort.Slice(results, func(i, j int) bool { + left, right := results[i], results[j] + if left.path != right.path { + return left.path < right.path + } + if left.line != right.line { + return left.line < right.line + } + if left.column != right.column { + return left.column < right.column + } + return left.kind < right.kind + }) + return results, nil +} + +func appendFinding(results []finding, fset *token.FileSet, pos token.Pos, path, kind, detail string) []finding { + position := fset.Position(pos) + return append(results, finding{ + path: filepath.ToSlash(path), + line: position.Line, + column: position.Column, + kind: kind, + detail: detail, + }) +} + +func returnsType(fields *ast.FieldList, typeName string) bool { + if fields == nil { + return false + } + for _, field := range fields.List { + if matchesType(field.Type, typeName) { + return true + } + } + return false +} + +func matchesType(expr ast.Expr, typeName string) bool { + switch expr := expr.(type) { + case *ast.Ident: + return expr.Name == typeName + case *ast.SelectorExpr: + return expr.Sel.Name == typeName + case *ast.StarExpr: + return matchesType(expr.X, typeName) + case *ast.IndexExpr: + return matchesType(expr.X, typeName) + case *ast.IndexListExpr: + return matchesType(expr.X, typeName) + default: + return false + } +} diff --git a/.agents/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh b/.agents/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh new file mode 100755 index 000000000..d4ac0e53a --- /dev/null +++ b/.agents/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh @@ -0,0 +1,13 @@ +#!/bin/sh +set -eu + +script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"} +mkdir -p "$cache_root/go-build" "$cache_root/tmp" + +export GOCACHE="$cache_root/go-build" +export GOTMPDIR="$cache_root/tmp" +export GOPROXY=off +export GOFLAGS=-mod=readonly + +exec go run "$script_dir/scan-go-type-syntax.go" "$@" diff --git a/.agents/skills/archie-codebase-discovery/scripts/trace-go-position.sh b/.agents/skills/archie-codebase-discovery/scripts/trace-go-position.sh new file mode 100755 index 000000000..50be4283a --- /dev/null +++ b/.agents/skills/archie-codebase-discovery/scripts/trace-go-position.sh @@ -0,0 +1,61 @@ +#!/bin/sh +set -u + +usage() { + printf '%s\n' "usage: $0 file.go:line:column" >&2 + exit 2 +} + +[ "$#" -eq 1 ] || usage +position=$1 + +command -v go >/dev/null 2>&1 || { + printf '%s\n' "error: go is required" >&2 + exit 127 +} +command -v gopls >/dev/null 2>&1 || { + printf '%s\n' "error: gopls is required" >&2 + exit 127 +} + +case "$position" in + *.go:[1-9]*:[1-9]*) ;; + *) usage ;; +esac + +cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"} +mkdir -p "$cache_root/go-build" "$cache_root/xdg" "$cache_root/tmp" || exit 1 + +export GOCACHE="$cache_root/go-build" +export XDG_CACHE_HOME="$cache_root/xdg" +export GOTMPDIR="$cache_root/tmp" +export GOPROXY=off +export GOFLAGS=-mod=readonly + +gomod=$(go env GOMOD) +if [ "$gomod" = "/dev/null" ] || [ -z "$gomod" ]; then + printf '%s\n' "error: run from inside a Go module" >&2 + exit 1 +fi + +run_query() { + label=$1 + shift + printf '\n== %s ==\n' "$label" + if output=$(gopls "$@" 2>&1); then + printf '%s\n' "$output" + return 0 + else + printf '%s\n' "$output" + printf '%s\n' "(query is not applicable at this position, or failed)" + return 1 + fi +} + +successful=0 +run_query "definition" definition "$position" && successful=$((successful + 1)) +run_query "references (including declaration)" references -d "$position" && successful=$((successful + 1)) +run_query "implementations" implementation "$position" && successful=$((successful + 1)) +run_query "call hierarchy" call_hierarchy "$position" && successful=$((successful + 1)) + +[ "$successful" -gt 0 ] diff --git a/.agents/skills/archie-config-and-flags/SKILL.md b/.agents/skills/archie-config-and-flags/SKILL.md new file mode 100644 index 000000000..8b46bae39 --- /dev/null +++ b/.agents/skills/archie-config-and-flags/SKILL.md @@ -0,0 +1,343 @@ +--- +name: archie-config-and-flags +description: Trace, add, rename, deprecate, or debug Archie configuration and command-line flags from external input through defaults, validation, overlays, environment and secret handling, worker snapshots, deployment passthrough, and the production consumer. Use for internal/config, config.example.toml, config.docker.toml, docker-compose.yml, archied or archie-agent flags, multi-identity settings, mode-parity questions, and reports of a setting that parses but has no effect. +--- + +# Trace Archie configuration and flags + +Treat configuration as a dataflow, not as a struct inventory. Prove every +claimed setting has an input, normalization path, composition seam, and runtime +consumer. + +Current evidence date: **2026-07-28**. Re-verify volatile defaults, deployment +wiring, and status labels before changing behavior. + +## Route work to the right skill + +Do not use this skill to: + +- choose a new architecture or owner; use + `archie-architecture-planning-campaign` and `archie-architecture-contract`; +- discover an unknown feature's whole blast radius; use + `archie-codebase-discovery`, then return here for its configuration seam; +- inspect live hosts, rotate secrets, deploy, or recover an instance; use + `archie-run-and-operate`; +- define NellDB settings or persistence semantics; use `archie-nelldb`; +- approve a behavioral change or claim acceptance; use + `archie-change-control` and `archie-validation-and-qa`. + +Use these status terms exactly: + +| Status | Meaning | +| --- | --- | +| **production-wired** | A real entrypoint decodes or accepts the value and a runtime consumer uses it. | +| **partially-wired** | Some modes, scopes, or fields consume it, but parity is incomplete. | +| **test/library-only** | An API and tests exist, but no current binary selects it. | +| **decoded-but-unwired** | Decoding/defaulting succeeds, but no production consumer uses the effective value. | +| **experimental/candidate** | Code exists, but operational correctness or the public contract is not established. | +| **external-production-unknown** | The repository does not contain the deployed effective value. | + +Never upgrade a status merely because decoding tests pass. + +## Trace one setting before editing it + +Perform this sequence: + +1. Find every external spelling, Go field, flag, environment name, example, and + deployment reference. +2. Identify the selected loader or flag set. Do not assume every exported loader + is used. +3. Read `finalize` and any consumer-side defaults. Record zero, empty, negative, + and sentinel semantics separately. +4. Follow copies across `ForTask`, `ToConfig`, NATS messages, subprocess + environment selection, container environment construction, and identity + overlays. +5. Find the production composition site and final behavior-changing read. +6. Find a test for decoding, defaulting, invalid input, production composition, + and mode parity. Record missing layers as gaps. +7. Check `config.example.toml`, `config.docker.toml`, `docker-compose.yml`, and + deployment environment passthrough. +8. Assign one status from the table above and cite the exact evidence paths in + the change record. + +Start with: + +```bash +rg -n 'LoadOverlay|LoadDir|ForTask|ToConfig|flag\.' \ + internal/config cmd/archied cmd/archie-agent +rg -n 'FIELD_NAME|external_key|ENV_NAME' \ + --glob '*.go' --glob '*.toml' --glob '*.yml' --glob '*.yaml' . +``` + +Do not search only `internal/config`: a field with no reads outside that package +is usually not production-wired. + +## Select the real input path + +| Input path | Current behavior | Status | +| --- | --- | --- | +| `archied -config PATH` | Defaults to `$XDG_CONFIG_HOME/archie/config.toml`, or `$HOME/.config/archie/config.toml`; `cmd/archied/main.go` calls `config.LoadOverlay`. | production-wired | +| `archied -config-overlay PATH` | Decodes base TOML, then overlay TOML into the same `Config`, then calls `finalize` once. Omitted overlay fields retain base values. | production-wired | +| `config.Load(PATH)` | Loads one TOML and finalizes it; no current binary calls it directly. | test/library-only | +| `config.LoadDir(base, overlay)` | Supports main YAML/TOML plus feature YAML and `conf.d`; no current entrypoint calls it. | test/library-only | +| `config.example.toml` | Load-tested example, not a deployed configuration. | test/library-only | +| `config.docker.toml` | Repository overlay mounted by Compose; it still depends on the host base config. | production-wired | +| Host base config and environment on `carina` | Mounted from `${HOME}/.config/archie/config.toml`; contents are absent from this repository. | external-production-unknown | + +`LoadDir` recognizes `gateway`, `tools`, `memory`, `models`, and `identities` +feature YAML. It rejects unknown `config..yaml` names, but accepts +unknown `conf.d/*.yaml` into `Config.Extra`. YAML takes precedence over TOML +when both are present in one directory. None of this changes the current daemon +path: `archied` selects TOML `LoadOverlay`, including during Telegram reload. + +Both TOML and YAML decoding are non-strict at the field level: the loaders do +not reject every unknown key. Add explicit compatibility and typo tests; never +use “the file loaded” as evidence that a key took effect. + +## Inventory CLI flags + +### Public binaries + +| Binary | Flag | Default and effect | +| --- | --- | --- | +| `archied` | `-config PATH` | Computed config path described above. | +| `archied` | `-config-overlay PATH` | Empty; overlay only fields explicitly present in the second TOML. | +| `archied` | `-once` | `false`; run one poll/process cycle and exit. | +| `archied` | `-requeue ID` | `0`; values greater than zero requeue one parked/waiting task, then exit unless `-once` is also set. | +| `archie-agent` | `-nats-url URL` | Empty; takes precedence over `NATS_URL`. Missing both is fatal. | +| `archie-agent` | `-consumer NAME` | `archie-agent`; names the JetStream durable consumer. | +| both | `-quickchecks N` | Incidental flag registered by `github.com/traefik/yaegi/stdlib` importing `testing/quick`; default `100`. Archie has no intentional consumer. Treat it as an unowned candidate defect, not supported configuration. | + +The standalone agent always reads its token from `NATS_TOKEN`; there is no +token flag. + +### Internal codesearch helper + +`archied workspace-codesearch` bypasses daemon configuration before normal flag +parsing. It is an internal child-process contract: + +| Subcommand | Required flags | Optional flags | +| --- | --- | --- | +| `build` | `--root`, `--index` | none | +| `candidates` | `--index`, `--pattern` | `--literal`, `--case-sensitive` | + +Do not expose these helper flags as daemon settings without an architecture and +compatibility decision. + +## Read the current wiring matrix + +### Root daemon and capability settings + +| Keys | Default, validation, and consumer | Status | +| --- | --- | --- | +| `work_dir`, `db_path` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; `work_dir` drives worktrees, memory, derived index paths, and state files, while `db_path` opens NellDB. Literal `~` in an explicit value is not expanded by the loader. | production-wired | +| `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. The `skill_activate` catalog still reads `work_dir`, and a container rebuilds from its mounted worktree. | partially-wired | +| `plugin_dir` | Empty disables daemon plugin loading; a configured directory is loaded in `cmd/archied`. | production-wired | +| `poll_interval` | Defaults to `60s`; root poll loop uses it and identities may override only their interval. | production-wired | +| `label` | No default or validation; used for `dispatch.trigger = "label"` or `"either"`. Empty therefore remains an accepted but likely ineffective pickup label. | production-wired | +| `max_retries` | Defaults to `3`; a repository value greater than zero overrides it. | production-wired | +| `bot_user`, `bot_email` | Single-identity mode requires `bot_user`; email defaults by forge type. `bot_user` drives assignment polling, store actor, sessions, and release state; both values form the Git signature. | production-wired | +| `forge.type`, `host`, `token` | Type defaults `github`, host defaults `https://github.com`; only `github` and `gitea` validate. The root token resolves before daemon construction and must be non-empty. | production-wired | +| `dispatch.trigger` | Defaults `assignee`; validates `assignee`, `label`, or `either`. | production-wired | +| `dispatch.ack_reaction` | Defaults `eyes`; case-insensitive `off` normalizes to empty. | production-wired | +| `dispatch.labels.*` | Missing `queued`, `working`, `waiting`, `pr`, `parked`, or `dead` keys default independently to `agent:*`. Used for forge state presentation. | production-wired | +| `models.` | 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 | +| `tools.tool_policy.*` | Feature YAML decodes `max_result_chars` and `parallel_execution`; no production read exists. | decoded-but-unwired | +| `indexing.index_dir`, `indexing.db_path` | `finalize` derives paths under `work_dir`; no entrypoint constructs `internal/indexing.Manager` from them. The internal helper alone does not complete wiring. | decoded-but-unwired | +| `extra` / unknown `conf.d` values | Test/library-only `LoadDir` stores untyped data, but core production has no consumer and the approved target forbids a core catch-all. | decoded-but-unwired | + +The default `agent.command = "archie-agent"` is not verified subprocess +operation. `SubprocessRunner` expects one JSON invocation on stdin and one JSON +response on stdout; `cmd/archie-agent` is a long-running NATS worker that parses +NATS flags. Treat subprocess mode with that command as an open incompatibility +until an end-to-end test proves otherwise. + +### Repository settings + +| Keys | Effective behavior | Status | +| --- | --- | --- | +| `owner`, `name` | Required for every declared repo. A single-identity config with zero repos currently loads but polls nothing. | production-wired | +| `base` | `BaseBranch()` maps empty to `main`, but `daemon.process` pre-clones with raw `repo.Base`. Set it explicitly: the advertised empty default is not honored on that production path. | partially-wired | +| `gate` | Argv arrays run in order. Empty entries are skipped. TDD inverts the last non-empty command as the repro test by convention. No loader validates command meaning. | production-wired | +| `protect` | Path suffixes are enforced by the agent runner; this is not a prompt-only rule. | production-wired | +| `ecosystem`, `preflight`, `test_glob` | Resolved preflight/test-glob logic treats empty ecosystem as Go. Container storage receives the raw ecosystem, so empty gets no Go cache mounts. Go/Python/Node/Rust have defaults; `custom` or an unknown name yields none. Explicit test globs validate with `filepath.Match`. | partially-wired | +| `persistent_storage` | Controls Docker-backed per-repo volume setup; it has no equivalent effect without container storage. | partially-wired | +| `max_retries` | Values greater than zero override global retry count; zero or negative falls back to global. | production-wired | +| `allow_concurrent` | Root repo entries affect the dispatcher. `allowConcurrentFor` does not inspect identity repo lists. | partially-wired | + +### Container settings + +| Key | Effective behavior | +| --- | --- | +| `enabled` | Requires non-empty `image`, `agent.mode = "nats"`, and non-empty `nats.url`. | +| `image` | Required only when enabled. | +| `max_concurrency` | Zero means no limit; used by the general task dispatcher and again by the container pool. | +| `max_uptime` | Defaults to `60m` only when enabled; caps a container lifetime. | +| `volume_ttl` | Defaults to `72h` only when enabled; negative is rejected; governs persistent-volume cleanup. | +| `pull_policy` | Defaults to `missing` when enabled. Pool code recognizes `missing` and `always`; other strings are not rejected and silently skip pre-pull. | +| `network` | Empty uses best-effort self-network detection. The repository overlay pins `archie-core_default`. | + +### Channel settings + +| Keys | Effective behavior | +| --- | --- | +| `chat.models` | Optional interactive catalog; empty falls back to distinct top-level workflow model references. | +| `chat.telegram.token_env` | Empty disables Telegram; non-empty names an environment variable and an empty value is fatal. | +| `chat.telegram.allowed_user_ids` | Empty denies every sender; IDs match Telegram sender IDs, not chat IDs. | +| `chat.telegram.update_check_command`, `update_install_command` | Argv arrays; check enables update status, and install additionally enables approved installation. | +| `chat.email.listen_addr`, `relay_addr` | Empty listen disables SMTP; relay configures outbound replies. | +| `chat.webhook_addr` | Empty disables; malformed host/port input falls back inside `parseListenAddr` rather than failing config validation. | + +Telegram `/restart` re-runs the same TOML overlay load, then replaces only the +gateway token and allowed-user list. Every other file setting is startup-only +in current composition. Active chat model/provider and persona selection are +runtime state, not configuration-file reload. + +## Treat multi-identity as partially wired + +`finalize` requires each identity's `name`, `bot_user`, non-empty repos, forge +type, and `SecretRef` token. It validates repository identity and test globs, +and `cmd/archied` builds an identity forge client and worktree manager. + +Do not infer complete isolation: + +- `cmd/archied` still resolves and constructs the root forge client before all + identity runners, so a config accepted without root fields can still fail in + production composition. +- Identity `name`, forge, repos, poll interval, bot user, and bot email have + some production reads. Identity bot email is not defaulted despite its + comment promising a fallback. +- Identity `models`, `providers`, `dispatch`, `budgets`, `notify`, and + `diff_cap_lines` decode but workflows still receive root `Config`. +- Identity polling reads root `dispatch`, `label`, and `bot_user`. +- Container task snapshots and provider maps come from root config; task RPC + servers are root-forge/root-worktree; container identity isolation is + explicitly incomplete in `internal/daemon/daemon.go`. +- Root-only concurrency lookup ignores identity repo `allow_concurrent`. + +Classify multi-identity changes field by field. Never label the aggregate +`IdentityConfig` production-wired. + +## Preserve worker and secret boundaries + +`Config.ForTask` creates a detached root snapshot containing only models, +budgets, dispatch, diff cap, notification, and forge host. `TaskConfig.ToConfig` +reconstructs only those fields. Provider descriptions travel separately in the +task-run request; forge tokens, provider values, NATS credential references, +repos, and infrastructure settings do not enter `TaskConfig`. + +At the top-level `[forge]`, prefer +`token = {engine = "env", key = "NAME"}`. Legacy `token_env = "NAME"` is +converted only when the structured reference is empty; the structured +reference wins when both appear. This compatibility rule exists because an +earlier migration silently dropped deployed `token_env` values and crash-looped +the daemon. `finalize` does not apply that conversion inside each identity: +identity forges require an explicit structured `token`. + +Use this environment matrix: + +| Source | Archied | Subprocess | Agent container / standalone worker | +| --- | --- | --- | --- | +| Forge `token = {engine="env", key="X"}` | Resolves `X`; empty is fatal. | Not forwarded unless explicitly abused through `agent.env`. | Not forwarded; forge operations proxy to daemon. | +| Provider `api_key_env = "X"` | Runtime reads `X`. | Automatically allowlists the selected provider's `X`. | Daemon forwards each present provider variable under its original name. | +| `nats.token_env = "X"` | Reads `X`; empty is fatal when configured. | Not an agent subprocess setting. | Daemon maps its value to fixed `NATS_TOKEN`; worker also reads `NATS_URL`. | +| Telegram `token_env = "X"` | Reads `X`. | Not forwarded. | Not forwarded. | +| `agent.env = ["X"]` | Names are validated. | Copies present `X` from daemon environment. | Not used by container construction. | + +`cmd/archied` creates `secret.NewRegistry`, which registers only the `env` +engine, and does not call `Registry.LoadDir`. Although plugin loading APIs and +comments describe custom secret engines, non-env `SecretRef` values are not +production-wired at token-resolution time. + +Compose passes only `ARCHIE_GITEA_TOKEN`, +`ARCHIE_GITEA_TOKEN_ARCHIE`, `HEYARCHIE_TELEGRAM_BOT_TOKEN`, and +`DEEPSEEK_API_KEY` into `archied`. A config reference to any other environment +name requires an explicit deployment passthrough change. The live base config +is external, so do not assert which of these names it uses. + +## Add, rename, or remove an axis + +Use this checklist: + +- [ ] Classify the value as invariant, runtime setting, policy, derived value, + or runtime state. +- [ ] Name one target capability owner and its scope: installation, identity, + repository, workflow, channel, or plugin instance. +- [ ] Prefer capability-owned settings. If a temporary `internal/config` field + is unavoidable, record its target owner and deletion gate. +- [ ] Add a failing decoder test for the production TOML path. +- [ ] Add failing tests for default, explicit value, zero/empty/negative input, + invalid syntax, semantic combination, and overlay inheritance. +- [ ] Add a production-composition test that observes the final consumer; a + struct equality test is insufficient. +- [ ] Test single identity, multiple identities, and every affected execution + mode separately. +- [ ] Update `ForTask`/`ToConfig` only when the worker needs the value; prove + maps are detached and secret values/references are absent. +- [ ] Trace in-process, subprocess allowlisting, NATS payload, container + environment, and RPC ownership. Fence unsupported modes explicitly. +- [ ] Update `config.example.toml`, `config.docker.toml`, Compose environment + passthrough, and generated/reference docs only where applicable. +- [ ] For a rename, decode old and new spellings at the loader boundary, define + precedence, and test old-only, new-only, and both. The `forge.token_env` + crash-loop regression is the minimum compatibility standard. +- [ ] For removal, prove no production consumer, external spelling, overlay, + worker copy, deploy reference, or supported old config remains. Define a + dated deprecation and deletion gate; do not leave a permanent alias. +- [ ] Route behavior-changing acceptance through change control and validation. + +Do not add a field that merely parses. Do not add arbitrary plugin fields to the +global struct. Do not expose secret values in config dumps, logs, task payloads, +or review evidence. + +## Follow the approved target, not the current sprawl + +Current code puts infrastructure paths, domain policy, channel settings, +secrets, execution settings, repository associations, and extension data in one +mutable `config.Config`. It passes that aggregate into `daemon.Daemon`, +`workflow.TaskContext`, and a second worker DTO. Treat this as a current +load-bearing weakness, not a pattern to copy. + +`docs/prds/architecture/configuration.md` is approved as of 2026-07-28: + +- move file/env/secret/overlay loading to a private + `internal/infrastructure/configuration` input boundary; +- translate inputs in `internal/app`; +- give each domain/plugin typed owned settings and validation; +- dissolve `internal/config` rather than rename the global model; +- split `Repo` and `IdentityConfig` by actual capability ownership; +- stage, validate, health-check, promote, audit, and roll back configuration + candidates without replacing last-known-good settings. + +Use `archie-architecture-planning-campaign` before moving ownership, and use +`archie-change-control` for every behavior-changing migration slice. Keep each +slice small enough to deliver a visible success while deleting one obsolete +path. + +## Provenance and maintenance + +Re-verify declarations and defaults: `rg -n 'type (Config|IdentityConfig|Repo|Agent|ContainerConfig|ChatConfig|ToolsConfig)|func (Load|LoadOverlay|LoadDir|finalize|\(c Config\) ForTask|\(tc TaskConfig\) ToConfig)' internal/config` + +Re-verify entrypoint and flag selection: `rg -n 'flag\.|LoadOverlay|LoadDir|ForTask|ToConfig|containerEnv' cmd/archied cmd/archie-agent internal/daemon` + +Re-verify all exposed help: `env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-help-gocache go run ./cmd/archied -h` + +Re-verify worker help: `env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-help-gocache go run ./cmd/archie-agent -h` + +Re-verify config behavior: `env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-test-gocache go test ./internal/config -count=1` + +Re-verify deployment passthrough: `rg -n 'command:|environment:|config\.toml|config\.docker\.toml|NATS_|TOKEN|API_KEY' docker-compose.yml config.docker.toml config.example.toml Dockerfile Dockerfile.archied` + +Re-verify target doctrine: `rg -n 'Ownership|Dissolution|Current configuration migration ledger|Universal change protocol|Completion criteria' docs/prds/architecture/configuration.md` diff --git a/.agents/skills/archie-config-and-flags/agents/openai.yaml b/.agents/skills/archie-config-and-flags/agents/openai.yaml new file mode 100644 index 000000000..a0b413c7b --- /dev/null +++ b/.agents/skills/archie-config-and-flags/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Archie Config and Flags" + short_description: "Trace Archie configuration from input to runtime" + default_prompt: "Use $archie-config-and-flags to trace this Archie setting or CLI flag from declaration through production wiring." diff --git a/.agents/skills/archie-debugging-playbook/SKILL.md b/.agents/skills/archie-debugging-playbook/SKILL.md new file mode 100644 index 000000000..4a1bdcc71 --- /dev/null +++ b/.agents/skills/archie-debugging-playbook/SKILL.md @@ -0,0 +1,473 @@ +--- +name: archie-debugging-playbook +description: Project-specific symptom-to-evidence triage for archie-core. Load this skill when Archied hangs, parks a task, loses or duplicates work, cannot reach NATS or an agent container, rejects configuration or secrets, shows stale Telegram or dashboard state, loses streamed text, fails MCP startup, reports NellDB state surprises, degrades an optional feature, or when Go tests disagree between a sandbox, editor, CI, and the host. Use it to separate environment failures from code regressions and to choose the next exact diagnostic. +--- + +# Debug Archie from evidence + +Use this runbook to identify the failing boundary. Stop after establishing the +smallest reproducible symptom and its owner. Do not edit code while collecting +the first evidence set. + +Treat facts marked **current** as verified against the repository on +2026-07-28. Treat facts marked **fixed history** as regression patterns, not +claims that production is failing now. Treat **open** as a verified gap whose +production impact still depends on deployment state. + +Define these terms once: + +- **Composition root**: `cmd/archied/main.go`, where decoded configuration + becomes live services. +- **Core NATS request/reply**: a request sent directly to a subject and answered + through its reply inbox. +- **JetStream**: the persisted NATS task/agent stream named `ARCHIE_TASKS`. +- **Wiring**: construction and connection of an implemented package into the + running daemon. +- **Environment failure**: a test or process cannot use a host resource such as + a listener, temp directory, Docker socket, or credential. +- **Code regression**: the same focused behavior fails in an environment that + provides its declared prerequisites. + +## Do not use this skill for the wrong job + +- For the incident timeline, rejected fixes, or reverts, load + `archie-failure-archaeology`. +- For AST traversal, callers, duplicate paths, or feature impact, load + `archie-codebase-discovery`. +- For repeatable inventories and measurements, load + `archie-diagnostics-and-tooling`. +- For installing tools or recreating the machine, load `archie-build-and-env`. +- For live startup, Compose, deployment, logs, or rollback, load + `archie-run-and-operate`. +- For acceptance evidence after a fix, load `archie-validation-and-qa`, then + route behavior-changing work through `archie-change-control`. +- For NellDB design or persistence changes, load `archie-nelldb`. + +## Run the first-ten-minutes protocol + +1. Record the exact command, exit code, first causal error, working directory, + configuration paths, execution mode, and whether the run was sandboxed. +2. Reproduce one package or one process boundary. Do not begin with `task + check`: it writes through `gofumpt -w .` and `go fix ./...`. +3. Compile tests without running them: + + ```bash + env GOTMPDIR=/tmp GOCACHE=/tmp/archie-debug-gocache \ + GIT_CONFIG_GLOBAL=/dev/null go test ./PATH/TO/PACKAGE -run '^$' -count=1 + ``` + +4. Run only the named test: + + ```bash + env GOTMPDIR=/tmp GOCACHE=/tmp/archie-debug-gocache \ + GIT_CONFIG_GLOBAL=/dev/null go test ./PATH/TO/PACKAGE \ + -run '^TestName$' -count=1 -v + ``` + +5. Classify the first failure: + + - Compile-only failure: inspect code, generated inputs, build tags, and the + actual Go toolchain. + - `listen ... operation not permitted` or an embedded NATS panic: rerun in an + environment that permits loopback listeners before blaming code. + - `mkdir /work/tmp/...: read-only file system`: keep `GOTMPDIR=/tmp`; the + repository code has not run yet. + - Behavioral assertion with the prerequisite available: treat it as a code + regression. +6. Preserve the failing output. Predict the expected observation before trying + a workaround. + +Use this symptom index to select the detailed branch: + +| Symptom | First boundary | Go to | +|---|---|---| +| `Run() = "\n"` in `TestRunWrapsExternalCommand` | Skill-script test command shape | Current known regression | +| Embedded NATS panics before a test assertion | Listener permission | Test environment | +| `nats: no responders available for request` | Core NATS subscription | NATS request/reply | +| Agent reply timeout | JetStream request, inbox, or worker | NATS request/reply | +| Queue looks empty while NATS reports an error | `Client.Fetch` batch error | NATS request/reply | +| Config test passes but daemon ignores the field | Composition/wiring | Configuration | +| Daemon has an env var but container does not | Compose or `containerEnv` | Configuration | +| Telegram reply hangs on the first token | Stream consumer | Streaming | +| MCP unit tests pass but a real server hangs | Framing mirror | MCP | +| Telegram shows old commands | Token-scoped Telegram state | Telegram | +| Transition succeeds from the wrong state | Store semantics | NellDB/state | +| Dashboard skips events but task state is correct | Bounded event buffers | Events | +| Search works but never becomes indexed | Missing production wiring | Optional features | +| Agent container cannot resolve `nats` | Docker network | Containers | +| `agent.mode = "subprocess"` fails at protocol startup | Worker binary mismatch | Subprocess mode | +| IDE reports an error that CLI cannot reproduce | Editor/cache state | Test environment | + +## Separate test-environment failures from regressions + +Inspect the active Go paths before changing code: + +```bash +go version +go env GOTMPDIR GOCACHE GOPATH GOMODCACHE GOENV +``` + +This checkout can inherit `GOTMPDIR=/work/tmp`; that path is read-only in some +sandboxes. Setting both `GOTMPDIR=/tmp` and a task-specific `GOCACHE` is a +diagnostic isolation step, not a product fix. + +Listener-dependent tests include embedded NATS, `httptest.NewServer`, and SMTP +listeners. Locate them: + +```bash +rg -n 'httptest\.NewServer|net\.Listen|RunRandClientPortServer|RunServer' \ + --glob '*_test.go' cmd internal +``` + +If a listener is forbidden, the characteristic evidence is a panic such as +`Unable to start NATS Server in Go Routine` or +`httptest: failed to listen on a port ... operation not permitted`. A +listener-free package passing does not waive the blocked integration tests. + +Do not attribute current go-git commit failures to GPG without checking the +repository-local mitigation. `worktree.Manager.setIdentity` pins +`commit.gpgsign=false`; its fixtures do the same. Isolate ambient global config: + +```bash +env GOTMPDIR=/tmp GOCACHE=/tmp/archie-worktree-gocache \ + GIT_CONFIG_GLOBAL=/dev/null go test ./internal/worktree -count=1 +``` + +If this passes while an editor still reports compiler errors, record the CLI +result as authoritative and restart the editor language server. Do not delete +module caches merely to silence a diagnostic. + +**Fixed history:** `.gotmp/` once held a workaround for tmpfs quota pressure and +was accidentally committed by a broad add. It is ignored now. Keep diagnostics +in `/tmp`, and never turn a local cache workaround into repository content. + +## Confirm the current known regression + +As of 2026-07-28, this focused test fails in an otherwise runnable package: + +```bash +env GOTMPDIR=/tmp GOCACHE=/tmp/archie-skillscript-gocache \ + GIT_CONFIG_GLOBAL=/dev/null go test ./internal/skillscript \ + -run '^TestRunWrapsExternalCommand$' -count=1 -v +``` + +Expected current failure: + +```text +Run() = "\n" +``` + +The test constructs: + +```go +exec.CommandContext(ctx, "sh", "-c", "echo", "wrapped") +``` + +For `sh -c`, the argument after the command string becomes shell `$0`; +therefore the command string is only `echo`, which prints a newline. This is a +test regression introduced by cleanup commit `308c199`, not proof that Yaegi +cannot run external commands. Do not weaken the expected `"wrapped\n"` value. +Route the fix and its acceptance evidence through `archie-change-control` and +`archie-validation-and-qa`. + +## Triage NATS request/reply and JetStream + +Keep the two transports distinct: + +| Surface | Subject or resource | Bound/current behavior | +|---|---|---| +| Task discovery | `archie.task.>` in `ARCHIE_TASKS` | Work-queue retention; daemon durable `archie-daemon`; max deliver 3 | +| Legacy agent stage | `archie.agent..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` | +| 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: + +```bash +docker compose ps +docker compose logs --since=10m archied nats +docker ps --filter label=archie-daemon=true \ + --format '{{.ID}}\t{{.Names}}\t{{.Networks}}\t{{.Status}}' +docker compose exec -T nats wget -q -O - http://localhost:8222/healthz +``` + +No stable container count exists; compare the task ID, agent container, and +subscription timing rather than demanding a fixed number. + +Branch on `no responders`: + +1. If a responder appears within 20 seconds, classify it as container startup + lag. `Daemon.requestTaskRun` deliberately retries only + `nats.ErrNoResponders`. +2. If every task exhausts the window, inspect the spawned agent's network and + environment. The Compose overlay currently sets + `containers.network = "archie-core_default"` and NATS URL + `nats://nats:4222`. +3. Look for agent logs `nats connected`, `taskrun: dedicated per-task + subscription`, and `archie-agent ready`. Absence of all three points before + workflow execution. +4. If only store/forge/worktree calls time out, confirm the composition root + reached `registerTaskRPCServers`; do not debug JetStream task discovery. + +**Fixed history:** network auto-detection once silently put task containers on +the default bridge, so `nats` never resolved and every request had no +responders. Explicit `containers.network` plus warning logs now fence that +path. + +Check duplicate and error semantics before "fixing" them: + +- Republishing the same owner/repo/issue within two minutes is intentionally + deduplicated. +- A reply inbox auto-unsubscribes after one response. Search for two handlers + subscribed to the same request subject before assuming response loss. +- `Client.Fetch` must inspect `batch.Error()` after the message channel closes; + returning `(nil, nil)` would mask a JetStream failure as an empty queue. +- `agentexec.runStages` returns a response envelope and a nil Go error for a + stage failure. Returning both the envelope error and a Go error aborts the + handler before it can publish the response. + +Run listener-free regression coverage for the last two rules: + +```bash +env GOTMPDIR=/tmp GOCACHE=/tmp/archie-nats-unit-gocache \ + go test ./internal/nats \ + -run '^TestFetchPropagatesBatchError' -count=1 -v +env GOTMPDIR=/tmp GOCACHE=/tmp/archie-agent-unit-gocache \ + go test ./internal/agentexec \ + -run '^TestHandleMessage' -count=1 -v +``` + +## Trace configuration from source to behavior + +Never stop at "the field decoded." Trace this sequence: + +1. `cmd/archied` reads `-config` and optional `-config-overlay`. +2. `config.LoadOverlay` TOML-decodes and `finalize` defaults/validates. +3. Secret references resolve or named environment variables are read. +4. The composition root constructs a service from the field. +5. Compose, subprocess allowlists, or `containerEnv` propagate needed values. +6. A focused behavior test observes the value at its consumer. + +Use these source checks: + +```bash +rg -n 'config\.LoadOverlay|config\.LoadDir' cmd/archied internal/config +rg -n 'cfg\.[A-Za-z0-9_.]+' cmd/archied/main.go +rg -n 'containerEnv|WorkerEnvironment|environment:' \ + cmd internal docker-compose.yml +env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-gocache \ + go test ./internal/config \ + -run 'Test(LoadOverlay|LoadForgeToken|DockerConfig)' -count=1 -v +``` + +Expected current observation: production `cmd/archied` calls +`config.LoadOverlay`; feature-file `config.LoadDir` is covered by tests but has +no `config.LoadDir` call in the composition root. A YAML feature field can +therefore decode correctly without affecting the daemon. Classify that as a +wiring gap, not a parser bug. + +For environment failures, distinguish: + +- Compose passes only the names listed under `archied.environment`. +- `containerEnv` translates the configured NATS token name into `NATS_TOKEN` + for `archie-agent` and forwards configured provider key variables. +- `SubprocessRunner` forwards default compatibility variables, configured + `[agent].env` names, and only the requested provider key. +- The legacy top-level `[forge] token_env` is converted to an env `SecretRef` + by `finalize`; explicit `[forge.token]` wins. + +Do not print secret values. Record only the variable name and +set/unset/propagated status. + +## Diagnose streaming, MCP, and Telegram + +### Streaming + +If a Telegram draft shows an empty cursor, typing never clears, and the turn +never completes, inspect the consumer in `cmd/archied/main.go`. Current code +must drain `stream.FullStream`, collect only `core.StreamPartTextDelta`, then +check `FinishReason`. `TextStream` is a best-effort view and cannot reconstruct +the authoritative response. + +**Fixed history:** consuming `TextStream` while leaving synchronous +`FullStream` unread deadlocked every streamed reply. Do not add a second +consumer or return before `FullStream` closes. + +### MCP + +Current stdio framing is one compact JSON-RPC object per line. Despite a stale +package comment in `internal/tools/mcp/types.go`, `Content-Length` framing is +not the implemented contract. Verify unit behavior: + +```bash +env GOTMPDIR=/tmp GOCACHE=/tmp/archie-mcp-gocache \ + go test ./internal/tools/mcp \ + -run 'Test(ReadMessage|WriteMessage|StdioTransportBadFraming)' \ + -count=1 -v +``` + +Do not accept this alone as protocol compatibility: the helper server in +`transport_test.go` calls the same `readMessage` and `writeMessage` functions, +so client and fake can mirror the same mistake. With network access and `npx` +explicitly allowed, run the real-server test: + +```bash +ARCHIE_TEST_DESKTOP_COMMANDER=1 \ + env GOTMPDIR=/tmp GOCACHE=/tmp/archie-mcp-integration-gocache \ + go test ./internal/tools/provider/mcp \ + -run '^TestDesktopCommanderClientCompatibility$' -count=1 -v +``` + +No stable tool count is asserted. The gate is non-empty discovery containing +`start_process`, `interact_with_process`, and `read_process_output`. + +### Telegram + +If commands work when typed but the menu is stale, inspect all three command +scopes in `internal/channels/telegram/commands.go`: default, all private chats, +and all group chats. Telegram stores command menus outside this repository, +keyed by bot token, and a narrower scope shadows the default. + +If access is wrong, verify sender IDs, not chat IDs. Empty +`allowed_user_ids` denies everyone; message, model, provider, and update +callbacks each enforce sender authorization. + +```bash +env GOTMPDIR=/tmp GOCACHE=/tmp/archie-telegram-gocache \ + go test ./internal/channels/telegram \ + -run 'Test(SenderAllowlistFailsClosed|IsSenderAllowed|PublishedCommandsMatchExecutableCommandSurface)$' \ + -count=1 -v +``` + +**Fixed history:** publishing only the default menu left roughly 60 commands +from a previous bot implementation visible in narrower scopes. A successful +single `SetMyCommands` call was insufficient evidence. + +## Diagnose state, events, containers, and optional features + +### NellDB and transitions + +Current `internal/nell.Adapter.Transition` looks up the task, writes `to`, and +does not compare `from` or persist `detail`. The legacy SQLite store also does +not guard its update with `from`, although it records a transition row. Thus +"transition returned nil" does not prove the source state matched. + +When state is surprising: + +1. Read `TaskByID` immediately before and after the caller. +2. Trace every `Transition`, `Requeue`, `RecoverStale`, and `Update` call. +3. Do not infer a valid state machine from the `from` argument. +4. Run both backends' focused suites: + + ```bash + env GOTMPDIR=/tmp GOCACHE=/tmp/archie-state-gocache \ + GIT_CONFIG_GLOBAL=/dev/null go test \ + ./internal/nell ./internal/store -count=1 + ``` + +Route any semantic change to `archie-nelldb`, architecture planning, and change +control; it is not a local error-message fix. + +### Events + +The in-process bus drops when a subscriber buffer is full. The composition +root's database sink buffer is 256; SSE client buffers are 64. The sink's drop +counter is not read in production, and per-client drops are not counted. +Therefore a dashboard gap can coexist with correct task state. + +```bash +rg -n 'Subscribe\(256\)|make\(chan events\.Event, 64\)|Dropped\(\)' \ + cmd/archied/main.go internal/events internal/webui +env GOTMPDIR=/tmp GOCACHE=/tmp/archie-events-gocache \ + go test ./internal/events -count=1 +``` + +No stable production drop count exists. Treat missing events as an +observability defect only after comparing the persisted task document and +event log. + +### Containers, worktrees, and subprocess mode + +- A container-mode task clones on the host, mounts it at `/data/worktree`, + writes `task.json`, then uses a dedicated `archie.taskrun.` + 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 "$evidence_dir/revision.txt" +git status --short >>"$evidence_dir/revision.txt" +go version >"$evidence_dir/tools.txt" +gopls version >>"$evidence_dir/tools.txt" +golangci-lint version >>"$evidence_dir/tools.txt" +staticcheck -version >>"$evidence_dir/tools.txt" + +go run "$skill/scripts/source-metrics.go" -root . >"$evidence_dir/source.tsv" +go run "$skill/scripts/config-use-candidates.go" -root . >"$evidence_dir/config.tsv" +"$skill/scripts/package-shape.sh" . >"$evidence_dir/packages-root.tsv" +"$skill/scripts/package-shape.sh" tools >"$evidence_dir/packages-tools.tsv" +"$skill/scripts/delivery-snapshot.sh" >"$evidence_dir/delivery.tsv" +``` + +`GOPROXY=off` and `-mod=readonly` prevent this evidence pass from fetching or +changing dependencies. Report an uncached dependency as an environment blocker. +The package helper preserves a harmless read-only module stat-cache warning but +normalizes its random temporary suffix to ``; preserve stderr and the exit +status with the report. + +Write a measurement charter before interpreting output: + +| Field | Required content | +|---|---| +| Question | One falsifiable maintainability, wiring, or delivery claim | +| Scope | Exact packages, modes, config branches, and modules | +| Predicted result | Expected baseline and before/after delta | +| Collection command | Exact command and environment | +| Branch condition | What contrary number triggers deeper discovery | +| Decision owner | Skill or reviewer that may approve action | + +Do not invent a composite “quality score.” Keep size, complexity, dependency, +duplication, coverage, runtime, and ownership evidence separate. + +## Use the bundled reports + +### Measure source shape + +Run: + +```sh +go run "$skill/scripts/source-metrics.go" -root . -top 30 +``` + +Read its tab-separated schema: + +| Record | Columns after record name | +|---|---| +| `META` | key, value | +| `METRIC` | module, metric, integer | +| `PACKAGE` | module, directory, production files, test files, generated files, production lines, test lines, generated lines | +| `HOTSPOT` | module, file, declaration line, symbol, body-span lines, statement nodes, approximate syntactic complexity | + +The script: + +- scans repository-owned Go files; +- separates the root and `tools` modules; +- separates production, test, and generated files; +- excludes `.git`, `.claude`, `.references`, `node_modules`, `vendor`, + `.gotmp`, and VitePress cache/output; +- sorts output deterministically; +- reports only production hotspots unless + `-include-test-hotspots` is passed. + +The defaults, 80 body lines and complexity 15, mirror two numeric triage points +in `.golangci.yml`. They do **not** implement `funlen` or `cyclop`. Run the +configured linters for authoritative linter findings: + +```sh +golangci-lint run --enable-only=funlen,gocognit,gocyclo,cyclop,maintidx,nestif ./internal/... +``` + +If a hotspot shrinks, verify that responsibility moved to a cohesive owner. +Moving the same work into unowned helpers is not improvement. + +### Measure package shape + +Run both module reports: + +```sh +"$skill/scripts/package-shape.sh" . >"$evidence_dir/packages-root.tsv" +"$skill/scripts/package-shape.sh" tools >"$evidence_dir/packages-tools.tsv" +awk -F ' ' '$1=="PACKAGE" {print $3 "\t" $4 "\t" $2}' "$evidence_dir/packages-root.tsv" | + sort -nr -k1,1 -k2,2 | + sed -n '1,20p' +``` + +Read `PACKAGE package fan_in fan_out` and `EDGE from -> to` rows. The script +reuses +`.claude/skills/archie-codebase-discovery/scripts/package-edges.sh`; do not +create a second package-edge implementation. + +Interpret high fan-in as a change-risk signal and high fan-out as an +orchestration signal, not as automatic defects. The report contains only +direct, intra-module imports. It does not show `tools` importing the root +module, interface dispatch, RPC relationships, string registrations, or state +ownership. A successful `go list` rejects Go import cycles; it does not prove +the target dependency doctrine. + +When an edge looks wrong: + +1. Run `archie-codebase-discovery` on the imported contract. +2. Identify the concrete production consumer. +3. Compare the current edge with `docs/prds/architecture/`. +4. Route any boundary change through the architecture campaign. + +### Find configuration-consumption candidates + +Run: + +```sh +go run "$skill/scripts/config-use-candidates.go" -root . >"$evidence_dir/config.tsv" +rg 'candidate-no-(selector-outside-config|entrypoint-selector)' "$evidence_dir/config.tsv" +``` + +Read each `CONFIG_FIELD` row as: + +```text +path, line, Type.Field, tags, same-name definition count, +config-package selector count, cmd selector count, +other-production selector count, test selector count, +generated selector count, candidate status +``` + +The report finds named fields with `toml`, `yaml`, or `json` tags declared in +`internal/config`, then counts selectors with the same **spelling**. It is +deliberately fast and deliberately not type-aware. + +For every candidate: + +1. Inspect the declaration at the reported `path:line`. +2. Run `gopls references -d` on that exact field identifier. +3. Trace decode → default → validation → normalization/copy → composition-root + read → concrete component → observable behavior. +4. Check reflection, serialization tags, Yaegi, registries, and string keys. +5. Separate feature-file tests from production selection. + +Repeated names such as `Name`, `Command`, or `Budgets` have high false-positive +rates; use the same-name count as a warning. A zero `cmd` count may be correct +when the composition root passes an enclosing struct. A nonzero count may +belong to an unrelated field. Only type-aware references plus composition prove +wiring. + +### Measure delivery and hygiene drift + +Run: + +```sh +"$skill/scripts/delivery-snapshot.sh" >"$evidence_dir/delivery.tsv" +``` + +Read: + +- `SURFACE axis scope literal_count` as literal text evidence, not parsed YAML + semantics; +- `HYGIENE metric count` as tracked-path candidates; +- `MODULE path` as discovered Go module boundaries. + +The snapshot compares Task, GitHub docs CI, Gitea deploy CI, and selected +composition-root anchors. A zero says the literal pattern was absent. It does +not prove the behavior is absent from a called script or external system. + +Inspect hygiene candidates directly: + +```sh +git ls-files | + rg '(^|/)(node_modules|bin|dist|\.gotmp)(/|$)|\.(exe|test|out)$' +git ls-files -s | awk '$1=="120000" {print}' +``` + +Do not delete a tracked candidate from a metric alone. Establish ownership, +generation source, consumers, deployment need, and a rollback path with +`archie-technical-accountability`. + +## Investigate duplication and hidden dead paths + +Measure textual duplication: + +```sh +golangci-lint run --enable-only=dupl ./internal/... +``` + +Measure unused unexported declarations: + +```sh +staticcheck -checks=U1000 ./internal/... +``` + +On 2026-07-28, the focused `dupl` command reported zero issues. That does not +contradict the known maintainability problem: two code paths can implement the +same responsibility with different syntax. + +For a duplicate or one-shot candidate: + +1. Name the externally visible operation, state transition, event subject, or + side effect. +2. Search all entrypoints and modes for that operation. +3. Use `gopls call_hierarchy`, `gopls references -d`, and the discovery skill's + AST construction scan. +4. Check interfaces, registrations, reflection, build tags, OS files, and wire + names. +5. Identify what a new feature supersedes and the objective removal gate. +6. Record production-only, test-only, compatibility, generated, and + unreachable paths separately. + +As of 2026-07-28, `Taskfile.yml` defines no `deadcode` task and the installed +`go tool` lists no dead-code analyzer. Archived PRDs mentioning +`task deadcode` describe a desired or former command, not a live command. + +## Collect test, race, coverage, and runtime evidence + +Keep collection scoped to the hypothesis: + +```sh +go test ./internal/nell -count=1 -coverprofile=/tmp/archie-nell.cover +go tool cover -func=/tmp/archie-nell.cover +go test -race ./internal/nell -count=1 +``` + +These commands were verified on 2026-07-28; the package reported 65.2% statement +coverage and passed its race run. The percentage is volatile and is not a +quality threshold. Read uncovered functions and error paths. + +`go test` can write CPU and memory profiles, but this checkout's `go tool` +listed no `pprof` frontend on 2026-07-28. Do not promise profile inspection +until `command -v pprof` or another approved viewer succeeds. Do not download a +viewer during a read-only evidence pass. + +Collect container logs without following indefinitely: + +```sh +docker compose logs archied >"$evidence_dir/archied.log" +docker compose logs nats >"$evidence_dir/nats.log" +curl -fsS http://localhost:8222/healthz >"$evidence_dir/nats-health.txt" +``` + +Run those only when the local Compose stack is in scope. Repository files do +not prove the remote `carina` instances match local Compose. `docker-compose.yml` +publishes NATS monitoring on port 8222 and uses `/healthz` in its healthcheck; +it does not establish a metrics endpoint contract. Route remote operations and +log interpretation through `archie-run-and-operate` and +`archie-debugging-playbook`. + +Some tests bind loopback listeners, including email, forge, storage, Telegram, +web UI, and MCP tests. A sandbox refusal to listen is environment evidence, not +a code regression. Re-run in an allowed environment before classifying it. + +## Compare before and after + +Predict exact deltas before changing code. Example: + +```text +Prediction: +- cmd/archied.run body span: 668 → below 350 +- root package count: unchanged +- new internal package edges: zero unless named in the design +- config candidate statuses: no regressions +- Task/CI/docs surface counts: unchanged unless explicitly in scope +``` + +Collect a second snapshot with the same script revision, flags, environment, +and toolchain: + +```sh +after_dir=/tmp/archie-diagnostics-after +mkdir -p "$after_dir" +go run "$skill/scripts/source-metrics.go" -root . >"$after_dir/source.tsv" +go run "$skill/scripts/config-use-candidates.go" -root . >"$after_dir/config.tsv" +"$skill/scripts/package-shape.sh" . >"$after_dir/packages-root.tsv" +"$skill/scripts/delivery-snapshot.sh" >"$after_dir/delivery.tsv" + +diff -u "$evidence_dir/source.tsv" "$after_dir/source.tsv" +diff -u "$evidence_dir/config.tsv" "$after_dir/config.tsv" +diff -u "$evidence_dir/packages-root.tsv" "$after_dir/packages-root.tsv" +diff -u "$evidence_dir/delivery.tsv" "$after_dir/delivery.tsv" +``` + +If output differs from the prediction: + +- confirm the checkout, dirty state, script revision, flags, and toolchain; +- explain each delta from changed source; +- branch to semantic discovery when a count cannot explain behavior; +- reject a “better” metric that moved duplication, hid a path, or weakened a + gate; +- route the resulting change through validation and fresh adversarial review. + +## Record the evidence packet + +Report: + +1. question and numeric prediction; +2. revision, dirty state, date, tools, and environment constraints; +3. exact commands and exit codes; +4. raw evidence paths; +5. before/after deltas by independent dimension; +6. semantic confirmation for every candidate used in a decision; +7. unexpected results and branch taken; +8. acceptance owner and remaining unknowns. + +Short wins count only when they leave a reproducible vertical slice: one +measured problem, one explained change, and no displaced responsibility left +unowned. + +## Dated current snapshot + +The bundled scripts measured this checkout on 2026-07-28: + +| Observation | Unstable value | +|---|---:| +| Root production/test/generated Go files | 123 / 111 / 4 | +| Root production/test/generated physical lines | 25,952 / 31,675 / 157 | +| `cmd/archied.run` body span / approximate complexity | 668 / 96 | +| `internal/config.finalize` body span / approximate complexity | 177 / 64 | +| Root internal packages / direct internal edges | 51 / 129 | +| Tagged config field rows | 110 | +| Tracked paths / tracked `node_modules` paths / tracked symlinks | 558 / 237 / 238 | +| `.dockerignore` present | 0 | + +The delivery snapshot found no Taskfile literals for race, the `tools` module, +or docs; no Go-gate literals in either workflow; a docs build in GitHub CI; and +container build/push in Gitea CI. `task check` is mutating because it invokes +`gofumpt -w .` and `go fix ./...`; do not run it as a read-only diagnostic. +Route it to acceptance. + +The focused test +`go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v` +failed on 2026-07-28 with `Run() = "\n"`. Preserve that known-red baseline; do +not claim a clean full suite or attribute it to unrelated work. + +## Provenance and maintenance + +Ground truth verified on 2026-07-28: +`Taskfile.yml`, `.golangci.yml`, `go.mod`, `tools/go.mod`, +`cmd/{archied,archie-agent}/`, `internal/{config,nell,skillscript}/`, +`.github/workflows/docs.yml`, `.gitea/workflows/deploy.yml`, +`docker-compose.yml`, `docs-2/package.json`, and `tools/docsgen/`. + +Re-verify scripts: `sh -n .claude/skills/archie-diagnostics-and-tooling/scripts/*.sh && go vet .claude/skills/archie-diagnostics-and-tooling/scripts/source-metrics.go && go vet .claude/skills/archie-diagnostics-and-tooling/scripts/config-use-candidates.go` + +Re-verify source baseline: `GOCACHE=/tmp/archie-diagnostics-gocache GOTMPDIR=/tmp go run .claude/skills/archie-diagnostics-and-tooling/scripts/source-metrics.go -root . -top 12` + +Re-verify config candidates: `GOCACHE=/tmp/archie-diagnostics-gocache GOTMPDIR=/tmp go run .claude/skills/archie-diagnostics-and-tooling/scripts/config-use-candidates.go -root .` + +Re-verify package edges: `.claude/skills/archie-diagnostics-and-tooling/scripts/package-shape.sh .` + +Re-verify delivery surfaces: `.claude/skills/archie-diagnostics-and-tooling/scripts/delivery-snapshot.sh` + +Re-verify lint thresholds: `rg -n 'cyclop:|dupl:|funlen:|gocognit:|gocyclo:|maintidx:|nestif:' .golangci.yml` + +Re-verify current test baseline: `GOCACHE=/tmp/archie-diagnostics-test-cache GOTMPDIR=/tmp GIT_CONFIG_GLOBAL=/dev/null GOPROXY=off GOFLAGS=-mod=readonly go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v` diff --git a/.agents/skills/archie-diagnostics-and-tooling/agents/openai.yaml b/.agents/skills/archie-diagnostics-and-tooling/agents/openai.yaml new file mode 100644 index 000000000..8e4014620 --- /dev/null +++ b/.agents/skills/archie-diagnostics-and-tooling/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Archie Diagnostics and Tooling" + short_description: "Measure maintainability, wiring, and delivery drift" + default_prompt: "Use $archie-diagnostics-and-tooling to collect a dated, reproducible evidence baseline before changing Archie." diff --git a/.agents/skills/archie-diagnostics-and-tooling/scripts/config-use-candidates.go b/.agents/skills/archie-diagnostics-and-tooling/scripts/config-use-candidates.go new file mode 100755 index 000000000..e8b1c9ac8 --- /dev/null +++ b/.agents/skills/archie-diagnostics-and-tooling/scripts/config-use-candidates.go @@ -0,0 +1,279 @@ +// Command config-use-candidates reports syntax-level selector evidence for +// tagged fields declared by internal/config. Results are candidates, not proof +// that a field is wired, live, or dead. +package main + +import ( + "flag" + "fmt" + "go/ast" + "go/parser" + "go/token" + "io/fs" + "os" + "path/filepath" + "reflect" + "sort" + "strconv" + "strings" +) + +type fieldDefinition struct { + path string + line int + typeName string + fieldName string + tags string + duplicates int +} + +type referenceCounts struct { + config int + entrypoint int + production int + test int + generated int +} + +func main() { + root := flag.String("root", ".", "repository root to inspect") + flag.Parse() + + absoluteRoot, err := filepath.Abs(*root) + if err != nil { + fail(2, "resolve root: %v", err) + } + info, err := os.Stat(absoluteRoot) + if err != nil { + fail(2, "inspect root: %v", err) + } + if !info.IsDir() { + fail(2, "root is not a directory: %s", absoluteRoot) + } + + fset := token.NewFileSet() + fields, err := readFieldDefinitions(absoluteRoot, fset) + if err != nil { + fail(1, "%v", err) + } + if len(fields) == 0 { + fail(1, "no tagged fields found under internal/config") + } + + nameCounts := map[string]int{} + for _, field := range fields { + nameCounts[field.fieldName]++ + } + for index := range fields { + fields[index].duplicates = nameCounts[fields[index].fieldName] + } + + references := map[string]*referenceCounts{} + for name := range nameCounts { + references[name] = &referenceCounts{} + } + if err := countSelectors(absoluteRoot, fset, references); err != nil { + fail(1, "%v", err) + } + + sort.Slice(fields, func(i, j int) bool { + if fields[i].typeName != fields[j].typeName { + return fields[i].typeName < fields[j].typeName + } + if fields[i].fieldName != fields[j].fieldName { + return fields[i].fieldName < fields[j].fieldName + } + if fields[i].path != fields[j].path { + return fields[i].path < fields[j].path + } + return fields[i].line < fields[j].line + }) + + fmt.Println("META\tschema\tarchie-config-use-candidates/v1") + fmt.Println("META\tmeaning\tselector-name counts are heuristic candidates; confirm exact fields with gopls references and production composition") + for _, field := range fields { + count := references[field.fieldName] + status := "candidate-selector-seen-in-entrypoint" + switch { + case count.production == 0 && count.entrypoint == 0: + status = "candidate-no-selector-outside-config" + case count.entrypoint == 0: + status = "candidate-no-entrypoint-selector" + } + fmt.Printf( + "CONFIG_FIELD\t%s\t%d\t%s.%s\t%s\t%d\t%d\t%d\t%d\t%d\t%d\t%s\n", + field.path, + field.line, + field.typeName, + field.fieldName, + field.tags, + field.duplicates, + count.config, + count.entrypoint, + count.production, + count.test, + count.generated, + status, + ) + } +} + +func readFieldDefinitions(root string, fset *token.FileSet) ([]fieldDefinition, error) { + configDir := filepath.Join(root, "internal", "config") + info, err := os.Stat(configDir) + if err != nil { + return nil, fmt.Errorf("inspect internal/config: %w", err) + } + if !info.IsDir() { + return nil, fmt.Errorf("internal/config is not a directory") + } + + var fields []fieldDefinition + err = filepath.WalkDir(configDir, func(path string, entry fs.DirEntry, walkErr error) error { + if walkErr != nil { + return walkErr + } + if entry.IsDir() || filepath.Ext(entry.Name()) != ".go" || strings.HasSuffix(entry.Name(), "_test.go") { + return nil + } + body, err := os.ReadFile(path) + if err != nil { + return err + } + file, err := parser.ParseFile(fset, path, body, parser.ParseComments) + if err != nil { + return fmt.Errorf("parse %s: %w", path, err) + } + relative, err := filepath.Rel(root, path) + if err != nil { + return err + } + relative = filepath.ToSlash(relative) + for _, declaration := range file.Decls { + general, ok := declaration.(*ast.GenDecl) + if !ok || general.Tok != token.TYPE { + continue + } + for _, specification := range general.Specs { + typeSpec, ok := specification.(*ast.TypeSpec) + if !ok { + continue + } + structType, ok := typeSpec.Type.(*ast.StructType) + if !ok { + continue + } + for _, field := range structType.Fields.List { + tags, ok := configTags(field.Tag) + if !ok { + continue + } + for _, name := range field.Names { + fields = append(fields, fieldDefinition{ + path: relative, + line: fset.Position(name.Pos()).Line, + typeName: typeSpec.Name.Name, + fieldName: name.Name, + tags: tags, + }) + } + } + } + } + return nil + }) + return fields, err +} + +func configTags(literal *ast.BasicLit) (string, bool) { + if literal == nil { + return "", false + } + raw, err := strconv.Unquote(literal.Value) + if err != nil { + return "", false + } + tag := reflect.StructTag(raw) + var parts []string + for _, key := range []string{"toml", "yaml", "json"} { + value, ok := tag.Lookup(key) + if !ok { + continue + } + parts = append(parts, key+"="+value) + } + return strings.Join(parts, ";"), len(parts) > 0 +} + +func countSelectors(root string, fset *token.FileSet, references map[string]*referenceCounts) error { + return filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error { + if walkErr != nil { + return walkErr + } + relative, err := filepath.Rel(root, path) + if err != nil { + return err + } + relative = filepath.ToSlash(relative) + if entry.IsDir() { + if relative != "." && excludedDirectory(relative, entry.Name()) { + return filepath.SkipDir + } + return nil + } + if filepath.Ext(entry.Name()) != ".go" { + return nil + } + body, err := os.ReadFile(path) + if err != nil { + return err + } + file, err := parser.ParseFile(fset, path, body, parser.ParseComments) + if err != nil { + return fmt.Errorf("parse %s: %w", relative, err) + } + generated := ast.IsGenerated(file) + isTest := strings.HasSuffix(entry.Name(), "_test.go") + inConfig := strings.HasPrefix(relative, "internal/config/") + inEntrypoint := strings.HasPrefix(relative, "cmd/") + + ast.Inspect(file, func(node ast.Node) bool { + selector, ok := node.(*ast.SelectorExpr) + if !ok { + return true + } + count := references[selector.Sel.Name] + if count == nil { + return true + } + switch { + case generated: + count.generated++ + case isTest: + count.test++ + case inConfig: + count.config++ + case inEntrypoint: + count.entrypoint++ + default: + count.production++ + } + return true + }) + return nil + }) +} + +func excludedDirectory(relative, name string) bool { + switch name { + case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp": + return true + } + return strings.HasPrefix(relative, "docs-2/.vitepress/cache") || + strings.HasPrefix(relative, "docs-2/.vitepress/dist") +} + +func fail(code int, format string, arguments ...any) { + fmt.Fprintf(os.Stderr, "config-use-candidates: "+format+"\n", arguments...) + os.Exit(code) +} diff --git a/.agents/skills/archie-diagnostics-and-tooling/scripts/delivery-snapshot.sh b/.agents/skills/archie-diagnostics-and-tooling/scripts/delivery-snapshot.sh new file mode 100755 index 000000000..d0ae4c108 --- /dev/null +++ b/.agents/skills/archie-diagnostics-and-tooling/scripts/delivery-snapshot.sh @@ -0,0 +1,90 @@ +#!/bin/sh +set -eu + +if [ "$#" -ne 0 ]; then + printf '%s\n' "usage: delivery-snapshot.sh" >&2 + exit 2 +fi + +for tool in git rg sed wc; do + command -v "$tool" >/dev/null 2>&1 || { + printf 'delivery-snapshot: %s is required\n' "$tool" >&2 + exit 127 + } +done + +script_dir=$(CDPATH= cd "$(dirname "$0")" && pwd) +repo_root=$(CDPATH= cd "$script_dir/../../../.." && pwd) +if [ ! -f "$repo_root/go.mod" ] || [ ! -f "$repo_root/Taskfile.yml" ]; then + printf 'delivery-snapshot: expected Archie repository root at %s\n' "$repo_root" >&2 + exit 2 +fi + +temporary=$(mktemp -d "${TMPDIR:-/tmp}/archie-delivery-snapshot.XXXXXX") +trap 'rm -rf "$temporary"' EXIT HUP INT TERM +cd "$repo_root" + +printf '%s\n' "META schema archie-delivery-snapshot/v1" + +scan_literal() { + axis=$1 + scope=$2 + pattern=$3 + shift 3 + result="$temporary/$axis" + if rg -n --no-heading --color never -e "$pattern" "$@" >"$result"; then + : + else + status=$? + if [ "$status" -ne 1 ]; then + printf 'delivery-snapshot: scan failed for %s\n' "$axis" >&2 + exit "$status" + fi + fi + count=$(wc -l <"$result" | sed 's/[[:space:]]//g') + printf 'SURFACE\t%s\t%s\t%s\n' "$axis" "$scope" "$count" +} + +scan_literal task_format taskfile 'gofumpt[[:space:]]+-w|go fix' Taskfile.yml +scan_literal task_vet taskfile 'go vet' Taskfile.yml +scan_literal task_build taskfile 'go build|task:[[:space:]]+build' Taskfile.yml +scan_literal task_test taskfile 'go test|task:[[:space:]]+test' Taskfile.yml +scan_literal task_lint taskfile 'golangci-lint|task:[[:space:]]+lint' Taskfile.yml +scan_literal task_race taskfile 'go test[^#\n]*-race|-race[^#\n]*go test' Taskfile.yml +scan_literal task_tools_module taskfile 'go -C tools|cd tools|task:[[:space:]]+tools' Taskfile.yml +scan_literal task_docs taskfile 'docsgen|pnpm[^#\n]*build|docs:generate|docs:check' Taskfile.yml + +scan_literal github_go_gate github-workflows 'go test|go vet|go build|golangci-lint|task[[:space:]]+check' .github/workflows +scan_literal github_docs_build github-workflows 'pnpm[[:space:]]+build|vitepress[[:space:]]+build' .github/workflows +scan_literal gitea_go_gate gitea-workflows 'go test|go vet|go build|golangci-lint|task[[:space:]]+check' .gitea/workflows +scan_literal gitea_container_publish gitea-workflows 'docker build|docker push' .gitea/workflows + +scan_literal production_load_overlay composition-root 'config\.LoadOverlay\(' cmd/archied/main.go +scan_literal production_load_dir composition-root 'config\.LoadDir\(' cmd/archied/main.go +scan_literal production_nell_store composition-root 'nell\.OpenStore\(' cmd/archied/main.go +scan_literal production_daemon composition-root '&daemon\.Daemon\{' cmd/archied/main.go +scan_literal production_rpc_servers composition-root 'registerTaskRPCServers\(' cmd/archied/main.go + +git ls-files >"$temporary/tracked" +tracked_total=$(wc -l <"$temporary/tracked" | sed 's/[[:space:]]//g') +tracked_node_modules=$(rg -c '(^|/)node_modules(/|$)' "$temporary/tracked" || true) +tracked_artifacts=$(rg -c '(^|/)(node_modules|bin|dist|\.gotmp)(/|$)|\.(exe|test|out)$' "$temporary/tracked" || true) +tracked_symlinks=$(git ls-files -s | awk '$1 == "120000" {count++} END {print count + 0}') + +printf 'HYGIENE\ttracked_paths\t%s\n' "$tracked_total" +printf 'HYGIENE\ttracked_node_modules_paths\t%s\n' "${tracked_node_modules:-0}" +printf 'HYGIENE\ttracked_artifact_candidates\t%s\n' "${tracked_artifacts:-0}" +printf 'HYGIENE\ttracked_symlinks\t%s\n' "$tracked_symlinks" +if [ -f .dockerignore ]; then + printf '%s\n' "HYGIENE dockerignore_present 1" +else + printf '%s\n' "HYGIENE dockerignore_present 0" +fi + +find . \ + \( -path './.git' -o -path './.claude' -o -path './.references' -o -name node_modules \) -prune -o \ + -name go.mod -print | + LC_ALL=C sort | + while IFS= read -r module; do + printf 'MODULE\t%s\n' "$module" + done diff --git a/.agents/skills/archie-diagnostics-and-tooling/scripts/package-shape.sh b/.agents/skills/archie-diagnostics-and-tooling/scripts/package-shape.sh new file mode 100755 index 000000000..beb7723bb --- /dev/null +++ b/.agents/skills/archie-diagnostics-and-tooling/scripts/package-shape.sh @@ -0,0 +1,86 @@ +#!/bin/sh +set -eu + +if [ "$#" -gt 1 ]; then + printf '%s\n' "usage: $0 [module-directory-relative-to-repo]" >&2 + exit 2 +fi + +command -v go >/dev/null 2>&1 || { + printf '%s\n' "package-shape: go is required" >&2 + exit 127 +} +command -v awk >/dev/null 2>&1 || { + printf '%s\n' "package-shape: awk is required" >&2 + exit 127 +} + +script_dir=$(CDPATH= cd "$(dirname "$0")" && pwd) +repo_root=$(CDPATH= cd "$script_dir/../../../.." && pwd) +module_relative=${1:-.} +module_root="$repo_root/$module_relative" +edge_helper="$repo_root/.claude/skills/archie-codebase-discovery/scripts/package-edges.sh" + +if [ ! -f "$module_root/go.mod" ]; then + printf 'package-shape: no go.mod at %s\n' "$module_root" >&2 + exit 2 +fi +if [ ! -x "$edge_helper" ]; then + printf 'package-shape: required sibling helper is missing or not executable: %s\n' "$edge_helper" >&2 + exit 2 +fi + +temporary=$(mktemp -d "${TMPDIR:-/tmp}/archie-package-shape.XXXXXX") +trap 'rm -rf "$temporary"' EXIT HUP INT TERM +mkdir -p "$temporary/cache" "$temporary/build-tmp" + +export GOCACHE="$temporary/cache" +export GOTMPDIR="$temporary/build-tmp" +export GOPROXY=off +export GOFLAGS="-mod=readonly -buildvcs=false" +export ARCHIE_DISCOVERY_CACHE="$temporary/discovery" + +( + cd "$module_root" + go list ./... | LC_ALL=C sort +) >"$temporary/packages" +if ( + cd "$module_root" + "$edge_helper" ./... +) >"$temporary/edges" 2>"$temporary/edge-stderr"; then + # The sibling helper sets its own GOFLAGS and can trigger a harmless, + # nondeterministic temporary filename when GOMODCACHE is read-only. + # Preserve the warning while normalizing only that filename suffix. + sed 's/\.info[0-9][0-9]*\.tmp/.info.tmp/' "$temporary/edge-stderr" >&2 +else + status=$? + cat "$temporary/edge-stderr" >&2 + exit "$status" +fi +( + cd "$module_root" + go list -m -f '{{.Path}}' +) >"$temporary/module" + +module_path=$(sed -n '1p' "$temporary/module") +printf '%s\n' "META schema archie-package-shape/v1" +printf 'META\tmodule\t%s\n' "$module_path" + +awk -F ' ' ' + NR == FNR { + packages[$0] = 1 + next + } + { + split($0, edge, " -> ") + outbound[edge[1]]++ + inbound[edge[2]]++ + } + END { + for (packageName in packages) { + printf "PACKAGE\t%s\t%d\t%d\n", packageName, inbound[packageName] + 0, outbound[packageName] + 0 + } + } +' "$temporary/packages" "$temporary/edges" | LC_ALL=C sort + +awk '{printf "EDGE\t%s\n", $0}' "$temporary/edges" diff --git a/.agents/skills/archie-diagnostics-and-tooling/scripts/source-metrics.go b/.agents/skills/archie-diagnostics-and-tooling/scripts/source-metrics.go new file mode 100755 index 000000000..14262b6e9 --- /dev/null +++ b/.agents/skills/archie-diagnostics-and-tooling/scripts/source-metrics.go @@ -0,0 +1,352 @@ +// Command source-metrics emits deterministic, syntax-derived Go source metrics. +// It never writes to the inspected tree and uses only the Go standard library. +package main + +import ( + "bytes" + "flag" + "fmt" + "go/ast" + "go/parser" + "go/token" + "io/fs" + "os" + "path/filepath" + "sort" + "strings" +) + +type counts struct { + productionFiles int + testFiles int + generatedFiles int + productionLines int + testLines int + generatedLines int + functions int + methods int +} + +type packageCounts struct { + module string + path string + productionFiles int + testFiles int + generatedFiles int + productionLines int + testLines int + generatedLines int +} + +type hotspot struct { + module string + path string + line int + symbol string + spanLines int + statements int + complexity int +} + +func main() { + root := flag.String("root", ".", "repository root to inspect") + top := flag.Int("top", 30, "maximum hotspot rows; zero means all") + largeLines := flag.Int("large-lines", 80, "minimum body span for a hotspot") + complexity := flag.Int("complexity", 15, "minimum approximate syntactic complexity for a hotspot") + includeTests := flag.Bool("include-test-hotspots", false, "include test functions in hotspot rows") + flag.Parse() + + if *top < 0 || *largeLines < 1 || *complexity < 1 { + fail(2, "top must be non-negative; thresholds must be positive") + } + + absoluteRoot, err := filepath.Abs(*root) + if err != nil { + fail(2, "resolve root: %v", err) + } + info, err := os.Stat(absoluteRoot) + if err != nil { + fail(2, "inspect root: %v", err) + } + if !info.IsDir() { + fail(2, "root is not a directory: %s", absoluteRoot) + } + + modules := map[string]*counts{} + packages := map[string]*packageCounts{} + var hotspots []hotspot + fset := token.NewFileSet() + + err = filepath.WalkDir(absoluteRoot, func(path string, entry fs.DirEntry, walkErr error) error { + if walkErr != nil { + return walkErr + } + relative, err := filepath.Rel(absoluteRoot, path) + if err != nil { + return err + } + relative = filepath.ToSlash(relative) + if entry.IsDir() { + if relative != "." && excludedDirectory(relative, entry.Name()) { + return filepath.SkipDir + } + return nil + } + if filepath.Ext(entry.Name()) != ".go" { + return nil + } + + body, err := os.ReadFile(path) + if err != nil { + return err + } + file, err := parser.ParseFile(fset, path, body, parser.ParseComments) + if err != nil { + return fmt.Errorf("parse %s: %w", relative, err) + } + + module := moduleFor(relative) + moduleCounts := modules[module] + if moduleCounts == nil { + moduleCounts = &counts{} + modules[module] = moduleCounts + } + dir := filepath.ToSlash(filepath.Dir(relative)) + packageKey := module + "\x00" + dir + pkg := packages[packageKey] + if pkg == nil { + pkg = &packageCounts{module: module, path: dir} + packages[packageKey] = pkg + } + + lines := physicalLines(body) + generated := ast.IsGenerated(file) + isTest := strings.HasSuffix(entry.Name(), "_test.go") + switch { + case generated: + moduleCounts.generatedFiles++ + moduleCounts.generatedLines += lines + pkg.generatedFiles++ + pkg.generatedLines += lines + case isTest: + moduleCounts.testFiles++ + moduleCounts.testLines += lines + pkg.testFiles++ + pkg.testLines += lines + default: + moduleCounts.productionFiles++ + moduleCounts.productionLines += lines + pkg.productionFiles++ + pkg.productionLines += lines + } + + for _, declaration := range file.Decls { + function, ok := declaration.(*ast.FuncDecl) + if !ok || function.Body == nil { + continue + } + if function.Recv == nil { + moduleCounts.functions++ + } else { + moduleCounts.methods++ + } + if generated || (isTest && !*includeTests) { + continue + } + + start := fset.Position(function.Body.Lbrace).Line + end := fset.Position(function.Body.Rbrace).Line + row := hotspot{ + module: module, + path: relative, + line: fset.Position(function.Pos()).Line, + symbol: symbolName(function), + spanLines: end - start + 1, + statements: statementNodes(function.Body), + complexity: syntacticComplexity(function.Body), + } + if row.spanLines >= *largeLines || row.complexity >= *complexity { + hotspots = append(hotspots, row) + } + } + return nil + }) + if err != nil { + fail(1, "%v", err) + } + + fmt.Println("META\tschema\tarchie-source-metrics/v1") + fmt.Printf("META\tthresholds\tlarge_lines=%d;syntactic_complexity=%d;top=%d\n", *largeLines, *complexity, *top) + + moduleNames := sortedKeys(modules) + for _, module := range moduleNames { + value := modules[module] + emitMetric(module, "production_go_files", value.productionFiles) + emitMetric(module, "test_go_files", value.testFiles) + emitMetric(module, "generated_go_files", value.generatedFiles) + emitMetric(module, "production_physical_lines", value.productionLines) + emitMetric(module, "test_physical_lines", value.testLines) + emitMetric(module, "generated_physical_lines", value.generatedLines) + emitMetric(module, "functions", value.functions) + emitMetric(module, "methods", value.methods) + } + + packageRows := make([]*packageCounts, 0, len(packages)) + for _, row := range packages { + packageRows = append(packageRows, row) + } + sort.Slice(packageRows, func(i, j int) bool { + if packageRows[i].module != packageRows[j].module { + return packageRows[i].module < packageRows[j].module + } + return packageRows[i].path < packageRows[j].path + }) + for _, row := range packageRows { + fmt.Printf( + "PACKAGE\t%s\t%s\t%d\t%d\t%d\t%d\t%d\t%d\n", + row.module, + row.path, + row.productionFiles, + row.testFiles, + row.generatedFiles, + row.productionLines, + row.testLines, + row.generatedLines, + ) + } + + sort.Slice(hotspots, func(i, j int) bool { + if hotspots[i].spanLines != hotspots[j].spanLines { + return hotspots[i].spanLines > hotspots[j].spanLines + } + if hotspots[i].complexity != hotspots[j].complexity { + return hotspots[i].complexity > hotspots[j].complexity + } + if hotspots[i].path != hotspots[j].path { + return hotspots[i].path < hotspots[j].path + } + if hotspots[i].line != hotspots[j].line { + return hotspots[i].line < hotspots[j].line + } + return hotspots[i].symbol < hotspots[j].symbol + }) + if *top > 0 && len(hotspots) > *top { + hotspots = hotspots[:*top] + } + for _, row := range hotspots { + fmt.Printf( + "HOTSPOT\t%s\t%s\t%d\t%s\t%d\t%d\t%d\n", + row.module, + row.path, + row.line, + row.symbol, + row.spanLines, + row.statements, + row.complexity, + ) + } +} + +func excludedDirectory(relative, name string) bool { + switch name { + case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp": + return true + } + return strings.HasPrefix(relative, "docs-2/.vitepress/cache") || + strings.HasPrefix(relative, "docs-2/.vitepress/dist") +} + +func moduleFor(relative string) string { + if relative == "tools" || strings.HasPrefix(relative, "tools/") { + return "tools" + } + return "root" +} + +func physicalLines(body []byte) int { + if len(body) == 0 { + return 0 + } + lines := bytes.Count(body, []byte{'\n'}) + if body[len(body)-1] != '\n' { + lines++ + } + return lines +} + +func symbolName(function *ast.FuncDecl) string { + if function.Recv == nil || len(function.Recv.List) == 0 { + return function.Name.Name + } + return receiverName(function.Recv.List[0].Type) + "." + function.Name.Name +} + +func receiverName(expression ast.Expr) string { + switch value := expression.(type) { + case *ast.Ident: + return value.Name + case *ast.StarExpr: + return "*" + receiverName(value.X) + case *ast.IndexExpr: + return receiverName(value.X) + case *ast.IndexListExpr: + return receiverName(value.X) + default: + return "receiver" + } +} + +func statementNodes(node ast.Node) int { + count := 0 + ast.Inspect(node, func(candidate ast.Node) bool { + statement, ok := candidate.(ast.Stmt) + if !ok { + return true + } + switch statement.(type) { + case *ast.BlockStmt, *ast.EmptyStmt: + default: + count++ + } + return true + }) + return count +} + +func syntacticComplexity(node ast.Node) int { + value := 1 + ast.Inspect(node, func(candidate ast.Node) bool { + switch item := candidate.(type) { + case *ast.IfStmt, *ast.ForStmt, *ast.RangeStmt, *ast.CommClause: + value++ + case *ast.CaseClause: + if len(item.List) > 0 { + value++ + } + case *ast.BinaryExpr: + if item.Op == token.LAND || item.Op == token.LOR { + value++ + } + } + return true + }) + return value +} + +func sortedKeys(values map[string]*counts) []string { + keys := make([]string, 0, len(values)) + for key := range values { + keys = append(keys, key) + } + sort.Strings(keys) + return keys +} + +func emitMetric(module, name string, value int) { + fmt.Printf("METRIC\t%s\t%s\t%d\n", module, name, value) +} + +func fail(code int, format string, arguments ...any) { + fmt.Fprintf(os.Stderr, "source-metrics: "+format+"\n", arguments...) + os.Exit(code) +} diff --git a/.agents/skills/archie-docs-and-writing/SKILL.md b/.agents/skills/archie-docs-and-writing/SKILL.md new file mode 100644 index 000000000..0caf31bdd --- /dev/null +++ b/.agents/skills/archie-docs-and-writing/SKILL.md @@ -0,0 +1,350 @@ +--- +name: archie-docs-and-writing +description: Maintain Archie's documentation of record and write durable architecture decisions, migration plans, parity matrices, incident and dead-end records, feature ownership and deprecation records, operational runbooks, and documentation reviews. Use when deciding where an Archie fact belongs; reconciling code with ARCHITECTURE.md, CLAUDE.md, docs/prds, docs/archive, generated contracts, or the docs-2 VitePress site; changing tools/docsgen; documenting a feature so future maintainers can find its owners, consumers, invariants, superseded paths, deletion gates, evidence, and rollback; or checking documentation authority, drift, links, copied content, and source-artifact hygiene. +--- + +# Maintain Archie documentation + +Write one durable record for each decision or behavior. Separate what runs now +from what Archie has approved as its destination. Make a future feature change +possible without rediscovering every code path. + +## Route work before writing + +Do not use this skill to make the underlying decision, investigate an incident, +or certify a code change: + +| Need | Load instead | +|---|---| +| Decide package ownership, boundaries, or migration order | `archie-architecture-planning-campaign` | +| Check a load-bearing invariant | `archie-architecture-contract` | +| Map live entry points, consumers, and call paths | `archie-codebase-discovery` | +| Establish feature ownership, supersession, or deletion accountability | `archie-technical-accountability` | +| Reconstruct an incident, revert, or rejected fix | `archie-failure-archaeology` | +| Change configuration, build, deployment, or operations | `archie-config-and-flags`, `archie-build-and-env`, or `archie-run-and-operate` | +| Gate or accept a change | `archie-change-control` and `archie-validation-and-qa` | +| Turn an unproven hypothesis into evidence | `archie-research-methodology` | + +Return here after those skills establish the facts or decision. Record their +result without broadening it. + +## Use the authority vocabulary + +Define a **record of authority** as the one canonical location whose owner may +change a claim. Label every material statement with one of these states: + +| State | Meaning | Permitted wording | +|---|---|---| +| `CURRENT` | Verified behavior in the checked-out code, tests, composition, or executable config | “Currently does” | +| `APPROVED TARGET` | Normative destination approved in the architecture index | “Must become”; never “currently does” | +| `OPEN` | Investigation, candidate, or unresolved decision | “Candidate”, “unknown”, or “requires decision” | +| `HISTORICAL` | Prior design, incident, dead end, or superseded choice | “Previously did”; never normative | +| `GENERATED` | Derivative output produced from an owned source definition | “Generated from”; never hand-edit | +| `EXTERNAL` | Fact held outside this repository, such as deployed config or host state | Date, name the verifier, and give a re-check command | + +When `CURRENT` conflicts with `APPROVED TARGET`, preserve both and state the +migration delta. Do not rewrite the target to match accidental code. Do not +describe target behavior as implemented merely because a PRD uses normative +language. + +## Use the repository authority map + +Treat this as a volatile map verified on 2026-07-28: + +| Location | Role | Discipline | +|---|---|---| +| Live Go code, tests, `Taskfile.yml`, executable config parsing, and composition under `cmd/` | `CURRENT` execution evidence | Trace producers and consumers; tests prove only their asserted behavior | +| `CLAUDE.md` | Current contributor and safety protocol plus a compact architecture orientation | Verify operational claims against code and `Taskfile.yml`; `AGENTS.md` is a symlink to this file | +| `ARCHITECTURE.md` | Useful architecture history and partial current overview | Corroborate every inventory/status claim; its “Planned” list is stale for implemented skill support | +| `docs/prds/01-project-management.md` | Index and approved foundation for the target architecture | Add or change target decisions in the focused document it names | +| `docs/prds/architecture/*.md` | Focused target decisions, active review procedure, and migration inventory | Read each file's status; distinguish fixed decisions from explicitly remaining decisions | +| `docs/prds/architecture/migration-decisions.md` | `OPEN` migration inventory constrained by approved decisions | Close a question only after code-grounded review and an approved record | +| `docs/archive/` | `HISTORICAL` material | Mine rationale and failure evidence; never restore authority from a title such as “Final” | +| `CHANGELOG.md`, `CHANGELOG.archied.md`, `CHANGELOG.archie.md` | Component release-note index and packaged runtime inputs | Keep gateway and agent-runtime entries separate; `internal/releaseannounce` parses the version headings | +| `tools/docsgen` | Current, partial generator implementation in the nested `tools` Go module | Treat its flags and tests—not planned PRD commands—as executable truth | +| `docs-2/data/generated/contracts.json` | Current working-tree `GENERATED` output | Regenerate; never edit by hand; re-check whether it is tracked | +| `docs-2/` | Staging VitePress site | Do not treat a rendered summary as the architecture record | +| `.github/workflows/docs.yml` | Current Pages build/deploy workflow | It builds the site; it does not currently run Go setup, generator tests, or drift checking | + +The repository root has no `README.md` or `CONTRIBUTING.md` as of 2026-07-28. +Record this as an onboarding coverage gap, not permission to invent a new +authority. `docs-2/README.md` is excluded by VitePress and still contains copied +Tau material; it is not a root onboarding guide. + +## Choose one destination + +1. State the reader's question in one sentence. +2. Identify the owner of the behavior or decision. +3. Find the existing record of authority. +4. Extend that record or link to it. Do not make a second canonical table. +5. If no owner exists, stop and route the ownership decision through + `archie-technical-accountability` or the architecture campaign. +6. If the fact is generated, change the owned source definition and generator; + do not patch output. +7. If the fact is external, date it and name the exact observation command. + +Use this placement guide: + +| Content | Destination | +|---|---| +| Cross-cutting approved architecture index | `docs/prds/01-project-management.md` | +| Focused domain or requirement decision | The matching `docs/prds/architecture/*.md` file | +| Unresolved migration question or cutover requirement | `docs/prds/architecture/migration-decisions.md` | +| Contributor protocol that must load before work | `CLAUDE.md` | +| Runtime/API/config reference derivable from code | Domain-owned registry/type, then `tools/docsgen` output | +| User-facing staging site prose | `docs-2/`, linking back to its authority | +| Shipped release behavior | The matching component changelog; keep `CHANGELOG.md` as the two-component index | +| Superseded design retained only for context | `docs/archive/`, with historical status | +| Incident or rejected approach | `archie-failure-archaeology`'s authoritative chronology | + +Do not duplicate a package map in `CLAUDE.md`, `ARCHITECTURE.md`, a PRD, and the +site. Name the authoritative map and link to it. + +## Research before drafting + +Run from the repository root: + +```bash +rg -n 'ExactTerm|RelatedTerm' --glob '*.go' --glob '*.md' --glob '*.toml' --glob '*.yml' +rg -n 'type ExactType|func .*ExactMethod|ExactConfigField' cmd internal domain tools +rg -n 'ExactType|ExactMethod' --glob '*_test.go' +rg -n 'ExactTerm' docs/prds ARCHITECTURE.md CLAUDE.md docs/archive docs-2 +``` + +Then build a fact ledger: + +| Claim | State | Owner | Evidence | Conflicts | Destination | +|---|---|---|---|---|---| +| One precise claim | `CURRENT` / `APPROVED TARGET` / `OPEN` | Domain or boundary | `path` + symbol/test/heading | Other path or none | Existing authority | + +Investigate entry points, runtime composition, persistence, configuration, +consumers, tests, failure behavior, duplicate implementations, and stale docs. +Do not ask the user a question that repository evidence can answer. + +## Write for future change + +Every architecture, feature, or migration record must answer: + +- **Responsibility:** What cohesive job exists? +- **Owner:** Which domain, application boundary, or infrastructure adapter owns + its meaning and mutable state? +- **Boundaries:** What is explicitly inside and outside? +- **Consumers:** Which entry points, interfaces, commands, events, config, and + processes depend on it? +- **Invariants:** What must remain true, and where is each invariant enforced? +- **Superseded path:** Which older mechanism becomes redundant? +- **Deletion gate:** What observable proof permits removal, and what temporary + compatibility has an expiry condition? +- **Evidence:** Which symbols, tests, commands, and runtime observations support + the record? +- **Rollback:** How can behavior and data return safely? +- **Unresolved questions:** What remains `OPEN`, who owns the decision, and what + evidence will close it? + +Name one owner for every mutable record. Name every current code path that +performs the same operation. A new path is incomplete until the document says +whether each older path remains, delegates, migrates, or is deleted. + +Use [references/templates.md](references/templates.md) when drafting an ADR, +migration/parity plan, incident/dead-end record, feature ownership/deprecation +record, operational runbook, or docs review. Copy only the matching template; +delete prompts that do not apply rather than filling them with ceremony. + +## Cite evidence without freezing line numbers + +Prefer: + +- repository-relative path plus exact Go symbol, test name, config key, workflow + job/step, or Markdown heading; +- a relative Markdown link to the record of authority; +- the command that re-discovers the evidence. + +Write `internal/agentexec.Request` and `tools/docsgen.currentContractTypes`, for +example. Avoid permanent `file.go:123` citations: line numbers drift without +changing meaning. Use line numbers in a time-bounded review comment only. + +Distinguish evidence strength: + +1. Runtime composition and executable behavior. +2. Tests that exercise the relevant production seam. +3. Approved target decision. +4. Comments and summaries corroborated by the first three. +5. Historical or external notes, explicitly dated. + +## Maintain component changelogs + +Keep gateway behavior in `CHANGELOG.archied.md` and agent-runtime behavior in +`CHANGELOG.archie.md`; keep `CHANGELOG.md` as their index. The archied image +copies both component files to `/usr/share/archie/`, and +`internal/releaseannounce.changelogSection` parses a version heading to build +Telegram update messages. + +Do not copy the current heading format without investigation. A verified +2026-07-28 contradiction is `OPEN`: + +- `.gitea/workflows/deploy.yml` passes `vX.Y.Z` component versions. +- `changelogSection` searches for `## []`, and its fixtures use + `## [v0.1.0]`. +- The two current component changelogs use headings such as `## [1.1.0]` + without `v`. +- `cmd/archied.TestChangelogsTrackGatewayAndRuntimeIndependently` explicitly + expects the unprefixed current heading. + +Resolve the parser, release metadata tests, and both documents atomically +through `archie-change-control`; do not “fix” only the prose. Until resolved, +do not claim that a current component entry is parseable by the deployed +release announcer. + +## Maintain generated contracts + +The current implementation is smaller than the approved target in +`docs/prds/architecture/generated-documentation.md`. + +### Current behavior, verified 2026-07-28 + +- The tool path is `tools/docsgen`, not `tools/cmd/docsgen`. +- It is a separate Go module that replaces the root module with `../`. +- It accepts `--repo-root` and `--out`; it has no implemented `data`, + `asyncapi`, `all`, or `check` subcommands. +- `currentContractTypes` explicitly publishes three top-level contracts and + collects their referenced schemas into one JSON object. +- Its default output is `docs-2/data/generated/contracts.json`. +- The current test proves byte-identical repeated output, expected top-level + contracts, resolvable local references, duplicate/conflict rejection, and + filesystem/source error reporting. +- The output in this working tree matches a fresh temporary generation, but + `git ls-files` reports it as untracked. Re-check before relying on it in CI. + +Test and compare without changing the repository: + +```bash +GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools test ./docsgen -count=1 +docs_tmp="$(mktemp /tmp/archie-contracts.XXXXXX.json)" +GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools run ./docsgen --repo-root .. --out "$docs_tmp" +cmp "$docs_tmp" docs-2/data/generated/contracts.json +``` + +Exit status `0` from `cmp` means the one current output matches. This is not a +complete obsolete-file, site-route, or target-registry drift check. + +Regenerate the working-tree output only when the change is classified and +authorized: + +```bash +GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools run ./docsgen --repo-root .. +``` + +Treat the PRD's `docsgen all`, `docsgen check`, and `task docs:*` commands as +`APPROVED TARGET`. Do not run or document them as current until their CLI and +Taskfile entries exist and tests prove them. + +## Maintain the VitePress staging site + +Current behavior, verified 2026-07-28: + +| Surface | Current state | +|---|---| +| Package | `docs-2/package.json`; VitePress `^1.6.4`; pnpm lockfile resolves 1.6.4 | +| Site config | Archie title, local search, clean URLs, last-updated metadata, output at `.vitepress/dist` | +| Published prose | Handwritten home and architecture pages; no generated-data loader is present | +| Copied content | `docs-2/README.md` describes Tau and is excluded by `srcExclude` | +| Workflow | Frozen-lockfile install, `pnpm build`, Pages artifact upload/deploy | +| Versioning | pnpm major `10`; Node is `latest`, so the Node input is volatile | +| Missing gates | No Go setup, docsgen test, generator drift check, or root `task check` integration | + +Run the implemented site commands for review and acceptance: + +```bash +pnpm --dir docs-2 install --frozen-lockfile +pnpm --dir docs-2 build +``` + +Use `build` for review evidence. + +### Interactive authoring (not for automated acceptance) + +```bash +pnpm --dir docs-2 dev +``` + +This starts a long-running dev server at `http://localhost:5173` (by default). +Only use it for interactive authoring; stop it with `Ctrl-C` before proceeding. +It is not an acceptance gate. Record the exact pnpm and Node +versions in failure reports because CI currently permits version drift. + +### Enforce source-artifact hygiene + +As of 2026-07-28, Git tracks 237 `docs-2/node_modules` symlink entries. +Neither `docs-2/node_modules` nor `docs-2/.vitepress/dist` is ignored by the +root `.gitignore`. Treat cleanup and ignore changes as a classified repository +change; route them through `archie-change-control`. + +Before review, inspect rather than assuming: + +```bash +git ls-files -s 'docs-2/node_modules/**' | awk '$1 == 120000 { count++ } END { print count + 0 }' +git ls-files 'docs-2/.vitepress/dist/**' +git check-ignore -v docs-2/node_modules docs-2/.vitepress/dist || true +rg -n -i 'tau|template|placeholder' docs-2 --glob '!node_modules/**' +``` + +Never stage dependency installs, VitePress output, generator scratch files, +credentials, absolute paths, wall-clock data, or machine-specific values. + +## Review a documentation change + +Require all of the following: + +- [ ] The document names its state, date, scope, owner, and record of authority. +- [ ] `CURRENT`, `APPROVED TARGET`, `OPEN`, `HISTORICAL`, `GENERATED`, and + `EXTERNAL` claims are not blended. +- [ ] Every code claim has a path plus symbol, test, config key, or workflow + step that can be re-discovered. +- [ ] The writer traced consumers and runtime composition, not just type + declarations. +- [ ] The document states boundaries, invariants, superseded paths, deletion + gates, evidence, rollback, and unresolved questions where applicable. +- [ ] No authoritative table or definition is copied from another owner. +- [ ] Generated files were regenerated, not hand-edited. +- [ ] Release notes use the correct component file, and release metadata, + parser behavior, tests, and version headings agree. +- [ ] Generator tests and a non-mutating drift comparison pass. +- [ ] `pnpm --dir docs-2 build` passes for site changes. +- [ ] Copied product text and tracked build/dependency artifacts are absent from + the intended change. +- [ ] Behavior-changing decisions passed `archie-change-control` and + `archie-validation-and-qa`. + +Reject “the code is self-explanatory,” “temporary compatibility” without a +deletion gate, and status-free future tense. A durable record must let a new +engineer determine what exists, what should replace it, and how to prove the +transition. + +## Provenance and maintenance + +Last verified against the checked-out repository on 2026-07-28. Re-run these +one-line checks before relying on volatile facts: + +```bash +test -L AGENTS.md && readlink AGENTS.md && test ! -e README.md && test ! -e CONTRIBUTING.md +``` + +```bash +rg -n '^\\*\\*Status:\\*\\*|^# ' docs/prds/01-project-management.md docs/prds/architecture/*.md docs/archive/*.md +``` + +```bash +rg -n 'docsgen|docs:|pnpm|vitepress|CHANGELOG' Taskfile.yml .github/workflows/docs.yml tools/docsgen docs-2/package.json docs-2/.vitepress/config.mts Dockerfile.archied internal/releaseannounce cmd/archied +``` + +```bash +GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools test ./docsgen -count=1 +``` + +```bash +docs_tmp="$(mktemp /tmp/archie-contracts.XXXXXX.json)"; GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools run ./docsgen --repo-root .. --out "$docs_tmp" && cmp "$docs_tmp" docs-2/data/generated/contracts.json +``` + +```bash +git status --short -- docs-2 tools docs/prds/architecture/generated-documentation.md .github/workflows/docs.yml; git ls-files -s 'docs-2/node_modules/**' | awk '$1 == 120000 { count++ } END { print count + 0 }' +``` diff --git a/.agents/skills/archie-docs-and-writing/agents/openai.yaml b/.agents/skills/archie-docs-and-writing/agents/openai.yaml new file mode 100644 index 000000000..7cd8e4bde --- /dev/null +++ b/.agents/skills/archie-docs-and-writing/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Archie Docs and Writing" + short_description: "Maintain authoritative Archie documentation" + default_prompt: "Use $archie-docs-and-writing to write or update an authoritative Archie design, migration, incident, ownership, or operations document." diff --git a/.agents/skills/archie-docs-and-writing/references/templates.md b/.agents/skills/archie-docs-and-writing/references/templates.md new file mode 100644 index 000000000..c8099d50d --- /dev/null +++ b/.agents/skills/archie-docs-and-writing/references/templates.md @@ -0,0 +1,364 @@ +# Archie durable-writing templates + +Use one template at a time. Replace every angle-bracket prompt. Remove unused +sections. Keep facts, decisions, and open questions visibly separate. + +## Contents + +- [Architecture decision record](#architecture-decision-record) +- [Migration plan and parity matrix](#migration-plan-and-parity-matrix) +- [Incident or dead-end record](#incident-or-dead-end-record) +- [Feature ownership and deprecation record](#feature-ownership-and-deprecation-record) +- [Operational runbook](#operational-runbook) +- [Documentation change review](#documentation-change-review) + +## Architecture decision record + +````markdown +# + +**Status:** Proposed | Approved | Superseded by +**Date:** YYYY-MM-DD +**Owner:** +**Record of authority:** +**Change-control reference:** + +## Decision + + + +## Problem and scope + + + +## Current evidence + +| Claim | Evidence | +|---|---| +| | `` — `` | + +## Constraints and invariants + +- + +## Consumers and boundaries + +| Consumer | Contract used | Failure effect | +|---|---|---| +| | | | + +## Options considered + +| Option | Benefits | Costs and risks | Evidence | Result | +|---|---|---|---|---| +|