chore: cleanup
This commit is contained in:
1 parent
65aa5b462d
commit
d1bbd37d95
56 files changed
+8781
-78
No files matched your search
@@ -0,0 +1,362 @@
|
||||
---
|
||||
name: archie-architecture-contract
|
||||
description: >-
|
||||
Protect Archie's load-bearing architecture while placing, implementing, or
|
||||
reviewing behavior. Load this skill before changing daemon composition,
|
||||
domains, workflows, task lifecycle, agent execution, messaging, work intake,
|
||||
identity, memory, configuration, plugins, policies, persistence, NATS/RPC,
|
||||
containers, or process boundaries; use it when deciding where new code
|
||||
belongs, enforcing dependency direction, separating current runtime truth
|
||||
from the approved target and open migration decisions, or ensuring every
|
||||
behavior has one authoritative path. Route proof of duplication, dead-code
|
||||
disposition, production reachability, and maintainability to
|
||||
archie-technical-accountability.
|
||||
---
|
||||
|
||||
# Archie Architecture Contract
|
||||
|
||||
Treat architecture as executable safety policy. Preserve one understandable
|
||||
owner and one production path for each behavior.
|
||||
|
||||
## Read status before code
|
||||
|
||||
Use these labels exactly:
|
||||
|
||||
| Label | Meaning | Authority |
|
||||
| --- | --- | --- |
|
||||
| **CURRENT** | Behavior present in live code and production composition as of 2026-07-28. | Code, tests, and `cmd/archied/main.go` wiring |
|
||||
| **APPROVED TARGET** | Direction an implementation must approach, but which may not exist on disk. | `docs/prds/01-project-management.md` and documents whose status says approved |
|
||||
| **OPEN** | A migration or API decision no implementer may invent locally. | `docs/prds/architecture/migration-decisions.md` and documents marked in progress or under design |
|
||||
|
||||
> **Do not implement target prose as though it describes current code.**
|
||||
> Before treating a target package as available, prove that it exists and is
|
||||
> used from a production entry point. If the task will create that package,
|
||||
> classify it as a migration slice and obtain the focused package decision
|
||||
> first. `internal/domain/` does not exist in the CURRENT tree as of 2026-07-28.
|
||||
|
||||
Resolve apparent disagreement in this order:
|
||||
|
||||
1. Read live code and production composition for CURRENT behavior.
|
||||
2. Read `docs/prds/01-project-management.md` for APPROVED TARGET ownership.
|
||||
3. Read the focused decision document for the selected behavior.
|
||||
4. Read `docs/prds/architecture/migration-decisions.md` for OPEN work.
|
||||
5. Stop and use `archie-architecture-planning-campaign` if a required semantic
|
||||
decision remains open.
|
||||
|
||||
## Route the task
|
||||
|
||||
Use this skill to enforce boundaries and place behavior.
|
||||
|
||||
Do **not** use it as:
|
||||
|
||||
- a design interview or migration campaign; use
|
||||
`archie-architecture-planning-campaign`;
|
||||
- a project vocabulary glossary; use `archie-domain-reference`;
|
||||
- NellDB mechanics, persistence behavior, or adapter guidance; use
|
||||
`archie-nelldb`;
|
||||
- a complete configuration field/default reference; use
|
||||
`archie-config-and-flags`;
|
||||
- proof that code is production-reachable, non-duplicated, or maintainable; use
|
||||
`archie-technical-accountability`;
|
||||
- a test, review, or release checklist; use `archie-change-control`.
|
||||
|
||||
Load the sibling skill as well when the task crosses one of those boundaries.
|
||||
|
||||
## Know the CURRENT system
|
||||
|
||||
Do not simplify these facts into the target model:
|
||||
|
||||
| Concern | CURRENT runtime truth on 2026-07-28 | Evidence |
|
||||
| --- | --- | --- |
|
||||
| Composition | `cmd/archied/main.go` performs substantial construction and wiring. Packages are organized mostly by technical mechanism. | `cmd/archied/main.go`; current `internal/*` tree |
|
||||
| Durable work | `store.Task` combines forge/chat source data, workflow position, output, retry, identity, and PR state. | `internal/store/store.go` |
|
||||
| Workflow | `internal/workflow` routes a `store.Task` into a `map[string]Workflow`, then mutates a broad `TaskContext` through sequential stages. | `internal/workflow/workflow.go` |
|
||||
| Agent-stage boundary | A versioned `agentexec.Request`/`Result` carries one autonomous stage; validation correlates task, attempt, and stage. | `internal/agentexec/protocol.go` |
|
||||
| Container handoff | `internal/taskrun` also carries an entire task plus `config.Repo` and `config.TaskConfig`; `archie-agent` runs routing and sequencing for this path. | `internal/taskrun/taskrun.go`; `cmd/archie-agent/main.go` |
|
||||
| Git ownership | Daemon-owned worktree operations clone, commit, push, diff, and clean up. The model receives no git ownership. | `internal/worktree/`; `internal/workflow/steps.go`; `ARCHITECTURE.md` |
|
||||
| Enforcement | Gates, read-only/protected paths, TDD inverted test gates, and diff caps are represented outside prompt prose. | `internal/agentexec/inprocess.go`; `internal/workflow/{agent,tdd,steps}.go` |
|
||||
| Configuration | `internal/config.Config`, `IdentityConfig`, `Repo`, and task snapshots mix input decoding with runtime concerns. | `internal/config/config.go` |
|
||||
| Identity | Configured names and bot usernames act as process-local identity keys. `daemon.IdentityRunner` groups per-name clients/config; there is no durable Identity domain. | `internal/daemon/daemon.go`; `internal/store/store.go`; `internal/gateway/session.go` |
|
||||
| Messaging | `internal/gateway` contains both legacy `Message` flow and a richer `MessageEvent`; channel routing and chat task control are mixed with conversational behavior. | `internal/gateway/{gateway,messageevent,tasks}.go`; `internal/channels/` |
|
||||
| Plugins | `plugin.Plugin` exposes only `Name` and `Version`; current loading interprets operator-installed Go files with Yaegi. | `internal/plugin/plugin.go` |
|
||||
| Processes | Agent modes include in-process, subprocess, and NATS. Optional containers add a distinct boundary with known gaps; a subprocess alone is not a security sandbox. | `internal/config/config.go`; `cmd/archied/main.go`; `ARCHITECTURE.md` |
|
||||
|
||||
### Interpret the current lifecycle honestly
|
||||
|
||||
Use these CURRENT status values:
|
||||
|
||||
```text
|
||||
queued, running, waiting_human, pr_open, merged,
|
||||
parked, dead, rejected, closed_wont_do
|
||||
```
|
||||
|
||||
The intended flow includes queue/claim, workflow stages, human wait/resume, PR
|
||||
reconciliation, parking/retry/exhaustion, and crash recovery. Read
|
||||
`internal/store/store.go`, `internal/daemon/daemon.go`, and
|
||||
`internal/workflow/workflow.go` before changing a transition.
|
||||
|
||||
Do not call this an enforced state machine. CURRENT
|
||||
`Store.Transition(ctx, taskID, from, to, detail)`:
|
||||
|
||||
- does not include `from` in the update predicate;
|
||||
- updates task state and inserts transition history in separate statements;
|
||||
- can therefore accept an illegal/stale transition or leave state and history
|
||||
inconsistent;
|
||||
- is called from paths that sometimes discard its error.
|
||||
|
||||
Treat atomic state plus event/history persistence as an OPEN migration design,
|
||||
not a small local patch.
|
||||
|
||||
## Preserve the load-bearing invariants
|
||||
|
||||
| Invariant | Required action | Status and source |
|
||||
| --- | --- | --- |
|
||||
| The model never runs git | Keep clone, branch, commit, push, diff, and cleanup in deterministic workspace/worktree steps. Never expose git as an agent tool. | CURRENT: `ARCHITECTURE.md`; `internal/worktree/` |
|
||||
| Deterministic constraints outrank prompts | Enforce gates, protected paths, read-only stages, test protection, and change caps outside model instructions. Do not replace enforcement with “must not” prose. | CURRENT: `ARCHITECTURE.md`; `internal/agentexec/inprocess.go`; `internal/workflow/` |
|
||||
| Agent execution is a data boundary | Send bounded, versioned input; validate correlated output before applying it. Keep persistence, forge credentials, git authority, workflow outcomes, and policy enforcement outside the autonomous model. | CURRENT foundation: `internal/agentexec/protocol.go`; `ARCHITECTURE.md` |
|
||||
| Every workflow ends explicitly | Preserve terminal outcome or visible park behavior. Preserve crash recovery of interrupted `running` work. | CURRENT: `internal/workflow/workflow.go`; `internal/store/store.go` |
|
||||
| Generic plugins stay metadata-only | Keep `plugin.Plugin` at `Name()` and `Version()`. Put behavior on a typed capability interface with an owning `Registry` or `Manager`. | CURRENT-enforced rule: `internal/plugin/architecture_test.go`; `ARCHITECTURE.md#plugin-engine-rule-strict` |
|
||||
| Capability engines own lifecycle | Give resource-owning engines explicit start/health/stop semantics and failure isolation. Supply narrow registrars/services, never `*daemon.Daemon` or a service locator. | APPROVED rule: `ARCHITECTURE.md#plugin-engine-rule-strict`; reviewers enforce non-mechanical parts |
|
||||
| Trust is explicit | Treat trusted operator-installed in-process code, repository code, out-of-process integrations, and container-isolated code as different trust classes. Never call Yaegi or subprocess execution a sandbox. | APPROVED rule: `ARCHITECTURE.md#plugin-engine-rule-strict` |
|
||||
| Infrastructure stays replaceable | Keep forge, persistence, workspace, transport, container, and model details behind behavior-owned contracts. Do not leak broker messages, DB rows, SDK types, or config DTOs into domain models. | APPROVED TARGET: `docs/prds/architecture/dependencies-and-contracts.md` |
|
||||
| Same-repository execution serializes by default | Preserve the default unless an explicit scheduling policy permits concurrency. | CURRENT: `internal/config/config.go`; `internal/daemon/daemon.go` |
|
||||
|
||||
Run the mechanical plugin guard after changing any plugin or `*Engine`
|
||||
interface:
|
||||
|
||||
```bash
|
||||
go test ./internal/plugin -count=1
|
||||
```
|
||||
|
||||
Passing it does **not** prove lifecycle, host-access, shutdown, or trust
|
||||
semantics. Review those manually through `archie-change-control`.
|
||||
|
||||
## Apply the APPROVED TARGET
|
||||
|
||||
Apply these ownership rules to migration plans and new seams. Do not claim they
|
||||
are CURRENT until production wiring proves the cutover.
|
||||
|
||||
### Keep dependency direction inward
|
||||
|
||||
Use this target direction:
|
||||
|
||||
```text
|
||||
domain and shared application contracts <- infrastructure implementations
|
||||
^
|
||||
|
|
||||
application composition
|
||||
```
|
||||
|
||||
Enforce:
|
||||
|
||||
1. Put cohesive behavior, vocabulary, state, commands, events, policies,
|
||||
runtime settings, and required service interfaces with its owning domain.
|
||||
2. Make infrastructure implement domain-required interfaces and translate
|
||||
external representations.
|
||||
3. Let only `internal/app` choose concrete implementations and connect domains.
|
||||
4. Keep `cmd/*` limited to process input and invoking composition.
|
||||
5. Use an owned command, event, or approved shared contract across domains.
|
||||
6. Never let one domain mutate another domain's state or call its internals.
|
||||
7. Reject generic `entities`, `services`, `repositories`, `messages`, or
|
||||
`utils` layers that merely group mechanisms.
|
||||
|
||||
Sources: `docs/prds/architecture/organisation.md` and
|
||||
`docs/prds/architecture/dependencies-and-contracts.md`.
|
||||
|
||||
### Keep source ownership independent of deployment
|
||||
|
||||
Begin with a modular monolith even when capabilities run in separate processes.
|
||||
Introduce or retain a process/service boundary only for demonstrated:
|
||||
|
||||
- security isolation;
|
||||
- independent scaling;
|
||||
- failure containment; or
|
||||
- independent operation.
|
||||
|
||||
Do not add a network protocol or duplicate service scaffolding for possible
|
||||
future extraction. A transport is an infrastructure implementation of a
|
||||
behavior-owned contract, not the owner of the behavior.
|
||||
|
||||
Source: `docs/prds/architecture/organisation.md`.
|
||||
|
||||
### Separate interaction, admission, assistance, and execution
|
||||
|
||||
Use this target handoff:
|
||||
|
||||
```text
|
||||
channel-neutral Message
|
||||
-> selected Agent turn or deterministic automation
|
||||
-> optional proposed work
|
||||
-> Work Intake validates and emits AcceptedWorkRequest
|
||||
-> Workflow domain selects a Workflow version
|
||||
-> Workflow domain creates WorkflowExecution
|
||||
```
|
||||
|
||||
Keep the concepts separate:
|
||||
|
||||
- **Messaging** owns canonical messages, conversations, branches, channel/source
|
||||
correlation, delivery attempts, and messaging projections.
|
||||
- **Agent** owns a persistent assistant, model-independent continuity,
|
||||
specialization, capability context, and memory associations.
|
||||
- **Work Intake** owns admission, validation, deterministic routing, and the
|
||||
accepted-work-request handoff.
|
||||
- **Workflow** owns reusable versioned definitions, steps, durable executions,
|
||||
attempts, outcomes, and typed Workflow plugin contracts.
|
||||
|
||||
Do not equate an external issue/message with a WorkflowExecution. Do not let
|
||||
Work Intake create one directly. Do not require ordinary conversation or direct
|
||||
tool use to become durable workflow-backed work.
|
||||
|
||||
Sources: `docs/prds/architecture/migration-decisions.md`,
|
||||
`docs/prds/architecture/agent-system.md`, and
|
||||
`docs/prds/architecture/messaging-and-work-intake.md`.
|
||||
|
||||
### Separate identity, Agent, conversation, and memory
|
||||
|
||||
Use immutable `IdentityID` for target attribution; never use display names,
|
||||
forge usernames, bot names, or the empty string as canonical identity. Keep
|
||||
Identity separate from Agent: Identity names the actor; Agent owns assistant
|
||||
behavior and continuity.
|
||||
|
||||
Preserve the four fixed target memory scopes:
|
||||
|
||||
| Scope | Visibility |
|
||||
| --- | --- |
|
||||
| Global shared | Intentionally shared across Archie |
|
||||
| Agent-wide | One Agent across its users; private to that Agent by default |
|
||||
| User-wide | One user across authorized Agents |
|
||||
| Agent-user relationship | Exactly one Agent and one user |
|
||||
|
||||
Resolve Agent and initiating user before loading memory. Do not use conversation
|
||||
branching as a fifth memory scope.
|
||||
|
||||
Sources: `docs/prds/architecture/identity.md`,
|
||||
`docs/prds/architecture/agent-system.md`, and
|
||||
`docs/prds/architecture/migration-decisions.md`.
|
||||
|
||||
### Dissolve global runtime configuration
|
||||
|
||||
Treat the current `internal/config` package as a migration source inventory, not
|
||||
a target domain:
|
||||
|
||||
- move file/env/overlay/secret decoding to
|
||||
`internal/infrastructure/configuration`;
|
||||
- let each domain or plugin own typed runtime settings for its behavior;
|
||||
- translate external DTOs to those settings in `internal/app`;
|
||||
- never pass complete application config into a domain;
|
||||
- never move `config.Repo` or `IdentityConfig` intact to a renamed shared
|
||||
package;
|
||||
- classify every behavioral value as invariant, runtime setting, policy value,
|
||||
derived value, or runtime state.
|
||||
|
||||
Do not add another unrelated concern to the global config model without an
|
||||
explicit compatibility plan and deletion criterion. Use
|
||||
`archie-config-and-flags` for the field ledger.
|
||||
|
||||
Source: `docs/prds/architecture/configuration.md`.
|
||||
|
||||
## Place new behavior deliberately
|
||||
|
||||
Use this decision table. “Target” entries require a reviewed migration slice
|
||||
when the target package is not yet live.
|
||||
|
||||
| Behavior | Target owner/location | Decision gate |
|
||||
| --- | --- | --- |
|
||||
| Persistent actor lifecycle and attribution | `internal/domain/identity` | Do not mix authentication/access policy into Identity. |
|
||||
| Persistent assistant behavior and continuity | `internal/domain/agent` | Keep model/provider replaceable; do not fold Workflow into Agent. |
|
||||
| Workflow definitions, steps, executions, attempts, outcomes | `internal/domain/workflow` | Preserve version ownership and one authoritative lifecycle. |
|
||||
| Canonical messages, conversations, branches, delivery | `internal/domain/messaging` | Keep platform IDs as external correlation, not canonical IDs. |
|
||||
| Admission and deterministic routing of proposed durable work | `internal/domain/workintake` | Emit an accepted request; do not construct execution state. |
|
||||
| Generic plugin identity/discovery/compatibility/lifecycle | `internal/domain/plugin` | Keep generic contract metadata-only. |
|
||||
| Capability-specific plugin behavior | Owning domain's typed registry/manager | Never add behavior to `plugin.Plugin`. |
|
||||
| Broker-neutral publication/subscription mechanics | `internal/eventbus` | Keep message meaning and schemas with their domain. |
|
||||
| Shared policy evaluation/evidence mechanics | `internal/policy` | Keep policy vocabulary, evaluators, and consequences with the consuming domain. |
|
||||
| NATS, SQLite/NellDB, forge, config decoding, external SDK adapters | `internal/infrastructure/<capability>` | Implement a narrow owner-defined contract; translate at boundary. |
|
||||
| Construction, cross-domain connection, startup/shutdown | `internal/app/archied` or `internal/app/agentworker` | Keep `cmd/*` thin; define health and shutdown order. |
|
||||
| First-party optional capability | `plugins/<plugin>` | Make it removable; give only narrow contracts/services. |
|
||||
| Deployment assembly | `deployments/<assembly>` | Do not move application behavior into deployment files. |
|
||||
| Unreviewed memory/tools/workspace/gate/storage/web/RPC/scheduling behavior | **OPEN** | Run `archie-architecture-planning-campaign`; do not guess placement. |
|
||||
|
||||
## Confront known weak points
|
||||
|
||||
State these plainly in every affected plan:
|
||||
|
||||
| Weak point on 2026-07-28 | Required response |
|
||||
| --- | --- |
|
||||
| `TaskContext` is a mutable service bag containing complete config, services, policy, and scratch state. | Do not add another unrelated field casually. Design narrow step inputs/contracts and a staged removal path. |
|
||||
| Workflow lifecycle is split across store, daemon, workflow, gateway, and worker code. | Trace every writer and reader before changing status. Require one owner, parity tests, and deletion criteria. |
|
||||
| State changes and transition history are non-atomic; `from` is advisory. | Treat state-machine and atomic-event work as architecture migration. Do not “fix” one caller and claim completion. |
|
||||
| In-process and container paths put workflow orchestration on different sides of the process boundary. | Decide which path survives and why before extending both. Fence compatibility adapters and name their deletion gate. |
|
||||
| Identity uses strings; task uniqueness and NATS deduplication omit identity. | Do not promise independent multi-identity ownership until canonical IDs, uniqueness, and transport correlation migrate. |
|
||||
| Container RPC registration uses root forge/worktree clients, not the task owner's identity bindings. | Treat non-root container execution as a known trust/correctness defect; never describe it as identity-isolated. |
|
||||
| Missing or malformed container `task.json` makes `archie-agent` join the shared task-run queue. | Do not claim a per-task workspace binding after this fallback. Require valid boot identity to fail closed before treating the path as isolated. |
|
||||
| Subprocess execution uses the daemon user and host access. | Never describe subprocess mode as a security boundary. Require a real container/isolation design for confidentiality or integrity. |
|
||||
| Gateway duplicates lifecycle strings and has competing message contracts. | Do not add a third contract or another direct lifecycle mutation path. |
|
||||
| Global config and `IdentityConfig` combine unrelated owners. | Do not cure complexity with a renamed global structure or an untyped `Extra` map. |
|
||||
| Memory has fixed scope requirements but OPEN final placement and migration. | Preserve scope isolation; use focused design before moving providers or persistence. |
|
||||
| Tests can make unused or duplicate code appear legitimate. | Prove production reachability from composition and dispose of the superseded path; use `archie-technical-accountability`. |
|
||||
|
||||
## Control every architecture-affecting change
|
||||
|
||||
Classify the change before editing:
|
||||
|
||||
| Class | Action |
|
||||
| --- | --- |
|
||||
| Current-path repair | Stay inside the current owner, preserve invariants, and avoid speculative target scaffolding. |
|
||||
| Migration slice | Record current owner, target owner, state/contracts to preserve, compatibility adapter, cutover, and objective deletion criteria. |
|
||||
| New or changed architecture | Stop implementation and run `archie-architecture-planning-campaign` until the focused decision is approved. |
|
||||
|
||||
Before implementation:
|
||||
|
||||
- [ ] Name the single behavior under change.
|
||||
- [ ] Trace its production entry point, constructor, consumers, mutable state,
|
||||
persistence, lifecycle, config, tests, and process crossings.
|
||||
- [ ] Search for duplicates, alternate implementations, and older code paths.
|
||||
- [ ] Read the focused decision document; do not infer authority over neighbors.
|
||||
- [ ] Mark every claim CURRENT, APPROVED TARGET, or OPEN.
|
||||
- [ ] Name the authoritative owner and every superseded path.
|
||||
- [ ] Define parity, cutover, rollback, and deletion evidence.
|
||||
- [ ] Route unresolved ownership or semantics to the architecture campaign.
|
||||
|
||||
Use evidence, not name matching:
|
||||
|
||||
```bash
|
||||
rg -n '<constructor>|<interface>|<method>' cmd internal
|
||||
go list -deps ./cmd/archied | rg 'github.com/samcharles93/archie-core/internal/'
|
||||
gopls references path/to/file.go:<line>:<column>
|
||||
```
|
||||
|
||||
Use `gopls references` or another AST-aware reference query when interfaces,
|
||||
embedding, generated symbols, or same-named methods make text search ambiguous.
|
||||
Trace from `cmd/archied/main.go`; a unit test, constructor, or exported symbol
|
||||
does not prove production use.
|
||||
|
||||
After implementation:
|
||||
|
||||
- [ ] Show the production call path to the changed behavior.
|
||||
- [ ] Show that state has one authoritative writer or explicitly fence the
|
||||
temporary compatibility path.
|
||||
- [ ] Show what old path was deleted, retained with rationale, or assigned a
|
||||
dated/objective deletion gate.
|
||||
- [ ] Re-run focused tests plus `archie-change-control`.
|
||||
- [ ] Run an independent architecture review that assumes every new boundary is
|
||||
wrong until evidence proves it.
|
||||
- [ ] Reject “tests pass” as sufficient evidence of maintainability.
|
||||
|
||||
## Provenance and maintenance
|
||||
|
||||
Volatile facts in this skill were verified on **2026-07-28**. Re-verify them
|
||||
before architecture work:
|
||||
|
||||
```bash
|
||||
test ! -d internal/domain && echo 'target domain tree is not current'
|
||||
sed -n '1,90p' docs/prds/01-project-management.md
|
||||
sed -n '1,260p' docs/prds/architecture/migration-decisions.md
|
||||
sed -n '1,320p' internal/store/store.go
|
||||
sed -n '1,240p' internal/workflow/workflow.go
|
||||
sed -n '1,220p' internal/agentexec/protocol.go
|
||||
sed -n '620,680p' cmd/archied/main.go
|
||||
sed -n '930,975p' internal/daemon/daemon.go
|
||||
go test ./internal/plugin -count=1
|
||||
command -v gopls && gopls help references
|
||||
```
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Archie Architecture Contract"
|
||||
short_description: "Protect Archie load-bearing architecture decisions"
|
||||
default_prompt: "Use $archie-architecture-contract to place and review this change without violating current or target architecture."
|
||||
@@ -0,0 +1,526 @@
|
||||
---
|
||||
name: archie-architecture-planning-campaign
|
||||
description: Run a decision-gated architecture campaign for archie-core before implementing a cross-package feature, migration, new domain, new process boundary, configuration redesign, duplicated-path cleanup, or other change whose ownership and change surface are unclear. Use when an engineer would otherwise need to trace much of the repository to discover what a feature touches, when TDD can prove behavior but not maintainability, or when planning must distinguish the live implementation from the approved target architecture.
|
||||
---
|
||||
|
||||
# Archie architecture planning campaign
|
||||
|
||||
Prevent another last-minute migration. Produce an implementation-ready
|
||||
architecture handoff in which every behavior, state transition, configuration
|
||||
value, boundary, compatibility path, and deletion has an explicit owner and
|
||||
testable disposition. Optimize for a cohesive change that a zero-context
|
||||
engineer can locate, explain, extend, and remove without tracing unrelated code,
|
||||
not the first green test.
|
||||
|
||||
## Load the required skill chain
|
||||
|
||||
Load these sibling skills before starting. For smaller-context sessions,
|
||||
load only the first two initially, then load the rest at their relevant
|
||||
phase:
|
||||
|
||||
1. `archie-codebase-discovery` — investigate the complete live change cone.
|
||||
2. `archie-architecture-contract` — apply Archie's load-bearing invariants.
|
||||
3. `archie-research-methodology` — state hypotheses and measurable predictions
|
||||
(needed by Phase 5).
|
||||
4. `archie-technical-accountability` — record evidence, decisions, debt, and
|
||||
ownership without hiding uncertainty (needed by Phase 6+).
|
||||
5. `archie-change-control` — classify and gate any resulting source or runtime
|
||||
change (needed by Phase 11).
|
||||
|
||||
Also load `archie-domain-reference` at Phase 3 (vocabulary and ownership) and
|
||||
`archie-docs-and-writing` plus its template at Phase 10 (ADR/PRD handoff).
|
||||
|
||||
If a sibling is unavailable, stop at the current read-only gate and report the
|
||||
missing control. Do not reconstruct its doctrine from memory.
|
||||
|
||||
## Know when not to use this campaign
|
||||
|
||||
- For a localized defect whose owner, state, consumers, and boundary are already proven, use `archie-change-control` and the repository TDD workflow.
|
||||
- To explore an unfamiliar package, use `archie-codebase-discovery`.
|
||||
- To review an already-written patch, use `archie-technical-accountability` plus the applicable review and validation skills.
|
||||
- To justify a preferred rewrite, use `archie-research-methodology`; this campaign may conclude that no architecture change is warranted.
|
||||
|
||||
## Use the ground-truth model
|
||||
|
||||
Keep two ledgers. Never blend them.
|
||||
|
||||
| Ledger | Authority | Meaning |
|
||||
|---|---|---|
|
||||
| Current implementation | Live production wiring, Go code, persistence, tests, deployment definitions, and observed behavior | What Archie does now, including duplication and defects |
|
||||
| Approved target | `docs/prds/01-project-management.md` and the status-qualified decisions in `docs/prds/architecture/*.md` | What Archie has approved or explicitly left open |
|
||||
|
||||
Treat `ARCHITECTURE.md` as a useful earlier architecture description, not proof
|
||||
that current wiring still matches it. Treat a decision marked “in progress,”
|
||||
“deferred,” or “under design” as a constraint plus open questions, not a
|
||||
finished design.
|
||||
|
||||
As of 2026-07-28, the approved target is domain-oriented, while much of the live
|
||||
tree remains in technical packages such as `internal/config`, `internal/daemon`,
|
||||
`internal/store`, and `internal/workflow`. Re-run the provenance commands before
|
||||
relying on that volatile fact.
|
||||
|
||||
## Define the terms once
|
||||
|
||||
- **Area under review**: one cohesive application responsibility, not an existing directory name.
|
||||
- **Owner**: the domain or capability with authority over behavior, vocabulary, state, settings, commands, events, and consequences.
|
||||
- **Change cone**: every entry point, caller, consumer, state record, adapter, test, configuration input, process boundary, and document affected by the decision.
|
||||
- **Domain contract**: the smallest behavior required by the owning domain; infrastructure implements it.
|
||||
- **Compatibility path**: a temporary adapter, dual read, dual write, or translation used only to preserve behavior during cutover.
|
||||
- **Authoritative path**: the sole path allowed to decide or mutate a behavior after cutover.
|
||||
- **Deletion criterion**: observable evidence that makes removal safe; “after migration” is not a criterion.
|
||||
- **Architecture packet**: the complete evidence and decision handoff produced by this campaign.
|
||||
|
||||
## Establish dynamic expected numbers
|
||||
|
||||
Do not invent repository counts. First verify the repository root, then
|
||||
capture baselines and use them as expected numbers:
|
||||
|
||||
```bash
|
||||
git rev-parse --show-toplevel >/dev/null || { echo 'run from repo root' >&2; exit 1; }
|
||||
test -f go.mod && test -f Taskfile.yml && test -f CLAUDE.md || {
|
||||
echo 'go.mod, Taskfile.yml, or CLAUDE.md missing — wrong directory?' >&2
|
||||
exit 1
|
||||
}
|
||||
git rev-parse HEAD
|
||||
git status --short
|
||||
go list -f '{{.ImportPath}}' ./internal/... | sort | tee /tmp/archie-architecture-packages.txt
|
||||
wc -l /tmp/archie-architecture-packages.txt
|
||||
find docs/prds/architecture -maxdepth 1 -type f -name '*.md' -print | sort | tee /tmp/archie-architecture-docs.txt
|
||||
wc -l /tmp/archie-architecture-docs.txt
|
||||
```
|
||||
|
||||
Name the resulting counts:
|
||||
|
||||
- `P` = current internal package rows in scope; for the whole migration, use every row in `/tmp/archie-architecture-packages.txt`.
|
||||
- `D` = architecture decision documents.
|
||||
- `F(area)` = production and test Go files in the declared change cone.
|
||||
- `R(symbol)` = typed references returned for a symbol by gopls.
|
||||
- `C` = decoded configuration fields and behavior-affecting literals in scope.
|
||||
- `L` = legacy or competing paths in scope.
|
||||
|
||||
Record the commit and dirty-file list beside every baseline. If concurrent work changes either, refresh the affected baseline; never mix measurements from two tree states.
|
||||
|
||||
## Phase 0 — Declare one decision scope
|
||||
|
||||
Write one sentence in this form:
|
||||
|
||||
> Decide who owns `<behavior>`, how `<input>` reaches `<outcome>`, and how the current paths migrate without changing `<preserved invariants>`.
|
||||
|
||||
List explicit non-goals and affected operators/users. Classify the work with `archie-change-control`, but authorize no implementation yet.
|
||||
|
||||
**Gate 0 — scope**
|
||||
|
||||
- Expected declared architecture questions: `1`.
|
||||
- Expected unexplained dirty files in the change cone: `0`.
|
||||
- Expected implementation edits during the campaign: `0`.
|
||||
- Expected non-goal list: at least `1` item.
|
||||
|
||||
If more than one independent architecture question remains, split campaigns. If a dirty file has unknown ownership, pause until its author or intent is known.
|
||||
|
||||
## Phase 1 — Build the decision corpus
|
||||
|
||||
Read the index and every focused architecture decision before designing:
|
||||
|
||||
```bash
|
||||
sed -n '1,240p' docs/prds/01-project-management.md
|
||||
while IFS= read -r ARCHIE_DOC; do sed -n '1,520p' "$ARCHIE_DOC"; done < /tmp/archie-architecture-docs.txt
|
||||
sed -n '1,360p' ARCHITECTURE.md
|
||||
sed -n '1,240p' CLAUDE.md
|
||||
```
|
||||
|
||||
Build a current-versus-target ledger with columns:
|
||||
|
||||
| Claim | Current evidence | Target decision | Status | Conflict or open decision |
|
||||
|---|---|---|---|---|
|
||||
|
||||
Give special attention to:
|
||||
|
||||
- `package-review.md` for the required investigation and decision set;
|
||||
- `migration-decisions.md` for unresolved destinations and cutover;
|
||||
- `organisation.md` and `dependencies-and-contracts.md` for ownership and dependency direction;
|
||||
- `configuration.md` for the required dissolution of `internal/config`;
|
||||
- `safe-change-and-recovery.md` for candidate promotion and rollback;
|
||||
- identity, agent, messaging, workflow, policy, plugin, and generated-doc documents whenever their vocabulary or contracts enter the change cone.
|
||||
|
||||
**Gate 1 — corpus**
|
||||
|
||||
- Expected decision-document review rows: `D`.
|
||||
- Expected documents with omitted status: `0`.
|
||||
- Expected target claims presented as current behavior: `0`.
|
||||
- Expected contradictions without an evidence link and disposition: `0`.
|
||||
|
||||
If live code contradicts an approved target, record migration work; do not silently redefine the target. If approved documents conflict, stop and request a decision instead of choosing the easier implementation.
|
||||
|
||||
## Phase 2 — Inventory the live change cone with syntax-aware tools
|
||||
|
||||
Do not start from package names. Start at production entry points and behavior.
|
||||
|
||||
```bash
|
||||
rg -n '^func main\\(' cmd
|
||||
rg -n 'flag\\.(String|Bool|Int|Int64|Duration|Var)' cmd --glob '*.go'
|
||||
rg --files cmd internal | sort
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-architecture-inventory-cache go run .claude/skills/archie-architecture-planning-campaign/scripts/go-inventory.go -root . -scope internal/<area> -include-tests=true
|
||||
```
|
||||
|
||||
Replace `<area>` with a real repository-relative directory. Run the inventory once per package in the change cone. It emits Go-parser-derived declarations as tab-separated columns:
|
||||
|
||||
| Column | Kind values | Meaning |
|
||||
|---|---|---|
|
||||
| `KIND` | `IMPORT`, `TYPE`, `FUNC`, `METHOD`, `VAR`, `CONST` | Go AST declaration kind |
|
||||
| `PACKAGE` | Directory path relative to `-root` | Package directory containing the declaration |
|
||||
| `FILE` | Filename within the package | Source file |
|
||||
| `LINE` | Positive integer | Declaration line number |
|
||||
| `NAME` | Identifier string | Exported or unexported name |
|
||||
| `DETAIL` | Short type/kind string | Receiver type for `METHOD`, underlying type for `TYPE`, signature summary for `FUNC` |
|
||||
|
||||
Empty output means no matching Go packages were found under `-scope`.
|
||||
Lines with empty `NAME` after the tab are parse-level artifacts; treat them
|
||||
as noise. The inventory does not infer runtime use, cross-package references,
|
||||
or dynamic registration.
|
||||
|
||||
Use gopls after the inventory:
|
||||
|
||||
- call `go_workspace` to confirm the module view;
|
||||
- call `go_package_api` for every package exposing a boundary;
|
||||
- call `go_search` for each domain term and competing synonym;
|
||||
- call `go_symbol_references` for every constructor, interface, state type, command, event, setting, and persistence method in scope.
|
||||
|
||||
If gopls is unavailable, use `go doc <package>`, `go list -json <package>`, and literal `rg` as a fallback. Label text-search counts approximate; do not claim typed coverage.
|
||||
|
||||
Count files before reading:
|
||||
|
||||
```bash
|
||||
rg --files internal/<area> -g '*.go' | sort | tee /tmp/archie-architecture-area-files.txt
|
||||
wc -l /tmp/archie-architecture-area-files.txt
|
||||
```
|
||||
|
||||
**Gate 2 — inventory**
|
||||
|
||||
- Expected files read: `F(area)`, the baseline line count.
|
||||
- Expected boundary packages with API summaries: all boundary packages; omitted count `0`.
|
||||
- Expected typed references traced for each selected symbol: `R(symbol)`; unexplained references `0`.
|
||||
- Expected discoverable facts deferred as user questions: `0`.
|
||||
|
||||
If gopls and text search disagree, inspect generated files, build tags, interfaces, reflection, Yaegi loading, and registration side effects. Do not infer “unused” from zero textual callers.
|
||||
|
||||
## Phase 3 — Establish vocabulary and ownership
|
||||
|
||||
Extract verbs, nouns, records, transitions, commands, events, settings, and failure outcomes from live behavior. Resolve overloaded terms rather than globally renaming `task`, `session`, `message`, `execution`, `identity`, or `plugin`.
|
||||
|
||||
Create this table:
|
||||
|
||||
| Term or behavior | Plain-language definition | Current locations | One owner | Competing meaning | Target contract |
|
||||
|---|---|---|---|---|---|
|
||||
|
||||
Use these ownership tests:
|
||||
|
||||
1. Name the cohesive job.
|
||||
2. Name the mutable records and transitions it governs.
|
||||
3. Name the policy consequences it decides.
|
||||
4. Name only the external services it requires.
|
||||
5. Explain why this code changes together.
|
||||
|
||||
Reject ceremonial `entities`, `services`, `helpers`, and `common` layers. A single-operation wrapper needs a boundary reason, a second genuine consumer, or removal/inlining.
|
||||
|
||||
For NellDB-related areas, inspect `internal/nell`, every consumer, persistence tests, and the pinned module before assigning semantics:
|
||||
|
||||
```bash
|
||||
go list -m -f '{{.Path}} {{.Version}}' github.com/samcharles93/NellDB
|
||||
rg -n 'nell\\.|NellDB|OpenStore|NewSessionStore' cmd internal --glob '*.go'
|
||||
```
|
||||
|
||||
Do not make NellDB records domain models merely because they persist current state.
|
||||
|
||||
**Gate 3 — vocabulary**
|
||||
|
||||
- Expected behaviors or records without one owner: `0`.
|
||||
- Expected unqualified terms with multiple meanings: `0`.
|
||||
- Expected domain owners chosen because of an existing directory name: `0`.
|
||||
- Expected boundaryless single-operation indirection: `0`, unless listed for deletion or justified by a tested contract.
|
||||
|
||||
If one candidate owner must know another domain's internal state, redesign the handoff as an owned command, event, or narrow shared contract.
|
||||
|
||||
## Phase 4 — Trace consumers, state, and failure semantics
|
||||
|
||||
Trace each behavior from input to observable outcome:
|
||||
|
||||
| Input/source | Entry point | Command/event | State mutation | Persistence | Side effect | Failure/retry | Output |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
|
||||
For every mutable record, produce a transition table:
|
||||
|
||||
| From | Command | Preconditions/version | To | Atomic event | Invalid result | Retry/idempotency |
|
||||
|---|---|---|---|---|---|---|
|
||||
|
||||
Inspect production construction in `cmd/archied/main.go` and `cmd/archie-agent/main.go`; constructors alone do not prove production use. Trace RPC, NATS, container, in-process, and subprocess paths separately. Trace tests after production; a mirrored fake can validate the same wrong assumption.
|
||||
|
||||
**Gate 4 — runtime trace**
|
||||
|
||||
- Expected production consumers reconciled per symbol: `R(symbol)`.
|
||||
- Expected mutable records without a complete transition table: `0`.
|
||||
- Expected state mutations without an identified transaction boundary: `0`.
|
||||
- Expected side effects without failure, timeout, retry, and idempotency evidence: `0`.
|
||||
- Expected competing authoritative write paths: `0`, or exactly `L` rows with cutover and deletion criteria.
|
||||
|
||||
If two paths create the same outcome, do not add a third abstraction over both. Decide authority and migration direction first.
|
||||
|
||||
## Phase 5 — Compare solutions and predict change locality
|
||||
|
||||
Use `archie-research-methodology`. Compare at least three explicit options:
|
||||
|
||||
| Rank | Approach | Normal use | Fence |
|
||||
|---|---|---|---|
|
||||
| 1 candidate default | Domain-first modular monolith with owner-defined contracts and composition in `internal/app` | Behavior and ownership are understood | Do not retain old technical ownership merely to reduce moves |
|
||||
| 2 migration tool | Strangler cutover through the narrowest compatibility adapter | Data or live callers require staged migration | Require owner, expiry trigger, metrics, rollback, and deletion test |
|
||||
| 3 conditional | Retain a process boundary or extract a service | Measured security isolation, failure containment, scaling, or independent-operation need exists | Future possibility is not evidence |
|
||||
| rejected | Rename a generic package, pass global config, add a service locator, or keep parallel implementations indefinitely | Never | Violates approved architecture |
|
||||
|
||||
Score each legitimate option on cohesion, dependency direction, state authority, contract size, configuration ownership, failure containment, migration risk, reversibility, deletion cost, and testability.
|
||||
|
||||
Before choosing, rehearse at least three representative future changes:
|
||||
|
||||
1. add a small behavior to the area;
|
||||
2. replace an infrastructure implementation;
|
||||
3. change one owned setting or policy.
|
||||
|
||||
Predict the packages, contracts, and tests each would touch. Prefer obvious ownership and exclusion of unrelated packages over the smallest immediate diff.
|
||||
|
||||
**Gate 5 — option decision**
|
||||
|
||||
- Expected compared options: at least `3`, including the current structure.
|
||||
- Expected selected option: `1`.
|
||||
- Expected approved-invariant violations in the winner: `0`.
|
||||
- Expected representative change rehearsals: at least `3`.
|
||||
- Expected unexplained unrelated packages per rehearsal: `0`.
|
||||
- Expected predictions without a measurement or later verification command: `0`.
|
||||
|
||||
If no option clears every invariant, leave the decision open. Do not downgrade a MUST to get a winner.
|
||||
|
||||
## Phase 6 — Complete the package destination matrix
|
||||
|
||||
For the architecture migration, create one row for every package in `P`. For a bounded change, cover the measured change cone and prove why other packages are outside it.
|
||||
|
||||
| Current package/behavior | Owner | Target path | Disposition | Dependencies to remove | State/contracts to preserve | Prerequisites | Deletion criterion | Decision status |
|
||||
|---|---|---|---|---|---|---|---|---|
|
||||
|
||||
Use only these dispositions: move, merge with named replacement, infrastructure adapter, application composition, approved shared contract, plugin/extra/deployment/example/generated artifact, or delete after proof.
|
||||
|
||||
**Gate 6 — destinations**
|
||||
|
||||
- Expected destination rows: `P` for the whole migration, otherwise every package in the recorded change cone.
|
||||
- Expected blank owner, disposition, or status cells: `0`.
|
||||
- Expected confirmed rows that still require an implementer to invent domain semantics: `0`.
|
||||
- Expected compatibility rows without deletion criteria: `0`.
|
||||
|
||||
An open row blocks that row, not an independent confirmed slice.
|
||||
|
||||
## Phase 7 — Dissolve configuration by ownership
|
||||
|
||||
Inventory both decoded fields and behavior-affecting literals:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-architecture-inventory-cache go run .claude/skills/archie-architecture-planning-campaign/scripts/go-inventory.go -root . -scope internal/config -include-tests=false
|
||||
rg -n '\\bconfig\\.' cmd internal --glob '*.go'
|
||||
rg -n 'time\\.(Second|Minute|Hour)|time\\.Duration|http\\.DefaultClient|0\\.0\\.0\\.0|localhost|/usr/share|/data/' cmd internal --glob '*.go'
|
||||
```
|
||||
|
||||
For each value, record external input, default/provenance, typed owner, validation, mutability, consumers, secrets, and migration. Keep the decoded document private to configuration infrastructure; never pass complete app configuration into a domain.
|
||||
|
||||
Classify every literal as invariant, owned setting/default, policy value, external constraint, or defect. One current value does not make an invariant.
|
||||
|
||||
**Gate 7 — configuration**
|
||||
|
||||
- Expected inventoried configuration items: `C`.
|
||||
- Expected items without exactly one runtime owner and classification: `0`.
|
||||
- Expected domains importing configuration infrastructure or full app config:
|
||||
`0` in the target.
|
||||
- Expected live-setting mutation paths omitted from the migration ledger: `0`.
|
||||
- Expected plugin settings added to an unrelated global model: `0`.
|
||||
|
||||
If an item cannot reload safely, mark it restart-required and design candidate
|
||||
validation, health observation, last-known-good preservation, and rollback.
|
||||
|
||||
## Phase 8 — Justify process and trust boundaries
|
||||
|
||||
Inventory current boundaries:
|
||||
|
||||
```bash
|
||||
rg -n 'Subprocess|NATS|nats\\.|RPC|rpc|container|Docker|Yaegi|plugin' cmd/archied cmd/archie-agent internal/{agentexec,container,nats,natsrpc,taskrun,forgerpc,storerpc,worktreerpc,plugin,yaegiutil} --glob '*.go'
|
||||
```
|
||||
|
||||
For each retained boundary, record purpose, trusted principal, secrets and
|
||||
resources exposed, protocol owner/version, failure containment, health,
|
||||
startup/shutdown order, retries, and operator burden.
|
||||
|
||||
Keep source ownership independent of deployment. Treat a subprocess as
|
||||
transport, not a security sandbox. Keep model-owned work away from git
|
||||
credentials and daemon authority. Give plugins narrow typed registrars, never
|
||||
daemon access or generic hooks.
|
||||
|
||||
**Gate 8 — boundaries**
|
||||
|
||||
- Expected retained boundaries with one concrete justification: all retained
|
||||
boundaries; unjustified count `0`.
|
||||
- Expected external or cross-process contracts without owner/version: `0`.
|
||||
- Expected boundaries described as isolation without an enforced isolation
|
||||
mechanism: `0`.
|
||||
- Expected domains split only for possible future deployment: `0`.
|
||||
|
||||
If removal of a boundary changes confidentiality, integrity, availability, or
|
||||
operations, return to Phase 5 with those constraints.
|
||||
|
||||
## Phase 9 — Plan deprecation, cutover, rollback, and deletion
|
||||
|
||||
Mine compatibility and prior replacement attempts:
|
||||
|
||||
```bash
|
||||
rg -n 'legacy|compat|deprecated|deprecat|TODO|FIXME|HACK|remove|delete' cmd internal docs --glob '*.go' --glob '*.md'
|
||||
git log --oneline --decorate --all -- cmd internal docs/prds/architecture
|
||||
git log -S'internal/config' --oneline --all
|
||||
```
|
||||
|
||||
For each legacy path, record predecessor, successor, parity evidence, data
|
||||
backfill, dual-read/write need, production switch, rollback trigger, observation
|
||||
window, deletion criterion, and regression test.
|
||||
|
||||
Require the production composition test to prove the successor is selected.
|
||||
Require a negative test or architecture check to prevent reintroduction after
|
||||
deletion. Time-box transitional duplication by an observable trigger, not a
|
||||
calendar promise alone.
|
||||
|
||||
**Gate 9 — cutover**
|
||||
|
||||
- Expected legacy paths inventoried: `L`.
|
||||
- Expected successor authorities per legacy behavior: exactly `1`.
|
||||
- Expected compatibility paths without owner, rollback, and deletion proof:
|
||||
`0`.
|
||||
- Expected permanent duplicate authoritative paths after cutover: `0`.
|
||||
- Expected old states/records without migration or explicit safe abandonment:
|
||||
`0`.
|
||||
|
||||
If parity cannot be measured, do not switch production wiring. Design the
|
||||
observable first.
|
||||
|
||||
## Phase 10 — Produce the ADR/PRD handoff
|
||||
|
||||
Write or propose the focused architecture document only where change control
|
||||
authorizes it. Include:
|
||||
|
||||
1. scope and non-goals;
|
||||
2. current-state trace with commit and dynamic baselines;
|
||||
3. vocabulary and ownership;
|
||||
4. current-versus-target ledger;
|
||||
5. considered options, predicted numbers, and rejection reasons;
|
||||
6. chosen owner, contracts, state machine, settings, policy, and boundaries;
|
||||
7. destination matrix;
|
||||
8. migration, compatibility, cutover, rollback, and deletion;
|
||||
9. implementation slices and dependencies;
|
||||
10. verification commands, expected evidence, unknowns, and named decisions
|
||||
still requiring the user.
|
||||
|
||||
Ask the user only questions whose answers materially change behavior or
|
||||
structure and cannot be discovered in the repository.
|
||||
|
||||
**Gate 10 — handoff**
|
||||
|
||||
- Expected discoverable facts presented as questions: `0`.
|
||||
- Expected undecided semantics delegated to implementers in a confirmed slice:
|
||||
`0`.
|
||||
- Expected claims without source evidence or explicit “candidate/open” status:
|
||||
`0`.
|
||||
- Expected unresolved normative contradictions: `0`.
|
||||
|
||||
If a decision remains open, isolate it from executable slices and name its
|
||||
owner. Never disguise it as an implementation detail.
|
||||
|
||||
## Phase 11 — Slice for short, artful successes
|
||||
|
||||
Route every slice through `archie-change-control`. Keep TDD and fresh
|
||||
adversarial review, but add architecture acceptance before code acceptance.
|
||||
|
||||
Each slice must:
|
||||
|
||||
- deliver one observable behavior or migration proof;
|
||||
- have one domain owner and a bounded change cone;
|
||||
- establish or consume the final contract rather than create another temporary
|
||||
model;
|
||||
- preserve a working application at its boundary;
|
||||
- remove a predecessor, or advance its recorded deletion criterion;
|
||||
- add deterministic conformance protection where mechanically possible;
|
||||
- state what becomes easier to change after the slice.
|
||||
|
||||
Order slices as: characterization and observability, final contract, adapter or
|
||||
data migration, production cutover, legacy deletion, architecture regression
|
||||
guard. Do not create all target folders as empty scaffolding.
|
||||
|
||||
**Gate 11 — executable plan**
|
||||
|
||||
- Expected observable outcome per slice: `1`.
|
||||
- Expected owner per slice: `1`.
|
||||
- Expected unrelated domains modified per slice: `0`.
|
||||
- Expected predecessors neither removed nor advanced toward deletion: `0`.
|
||||
- Expected implementation slices bypassing change control: `0`.
|
||||
|
||||
If a slice requires broad service-locator access or the full configuration
|
||||
document, return to ownership and contract design.
|
||||
|
||||
## Phase 12 — Re-measure after every slice
|
||||
|
||||
Run the repository gate selected by `archie-change-control`, then compare the
|
||||
slice against this packet. At minimum, re-run package inventory, typed
|
||||
references, production construction tracing, configuration inventory, and
|
||||
legacy-path search.
|
||||
|
||||
Use a fresh adversarial reviewer to inspect every changed non-test file for
|
||||
cohesion, hidden dead paths, duplicated authority, unchecked errors,
|
||||
hard-coded behavior, interface leakage, nil/race/goroutine risk, and production
|
||||
wiring. A green TDD suite proves required behavior; it does not prove the code
|
||||
is maintainable.
|
||||
|
||||
**Gate 12 — conformance**
|
||||
|
||||
- Expected unexplained package/reference/configuration deltas from baseline:
|
||||
`0`.
|
||||
- Expected new authoritative paths beyond the selected design: `0`.
|
||||
- Expected surviving reviewer findings: `0`.
|
||||
- Expected destination/cutover rows left stale by the slice: `0`.
|
||||
- Expected representative change rehearsals made harder without an accepted
|
||||
rationale: `0`.
|
||||
|
||||
If the slice passes tests but fails conformance, reject or redesign it. “Make it
|
||||
work and move on” is not completion.
|
||||
|
||||
## Fence off settled wrong paths
|
||||
|
||||
- Do not code before mapping ownership, consumers, state, and cutover.
|
||||
- Do not equate moving or renaming packages with architecture.
|
||||
- Do not centralize unrelated runtime settings in a renamed global config.
|
||||
- Do not add abstractions solely to wrap one operation or hide duplication.
|
||||
- Do not preserve old and new models indefinitely “for compatibility.”
|
||||
- Do not expose domain meaning through broker, database, SDK, or DTO types.
|
||||
- Do not use process splits as source boundaries or subprocesses as sandboxes.
|
||||
- Do not add capability methods to the generic plugin contract.
|
||||
- Do not ask the user to rediscover code facts the tools can establish.
|
||||
- Do not accept linter silence as dead-code evidence; inspect registration,
|
||||
reflection, build tags, generated code, and production composition.
|
||||
- Do not let a mirrored test fake become the sole proof of an external or
|
||||
cross-process contract.
|
||||
- Do not permit implementation difficulty to waive an approved invariant.
|
||||
|
||||
## Provenance and maintenance
|
||||
|
||||
Grounded on 2026-07-28 in the approved architecture index and every file under
|
||||
`docs/prds/architecture/`, plus live `cmd`, `internal`, tests, `Taskfile.yml`,
|
||||
and the user's quality requirements. Re-verify volatile facts before each use.
|
||||
|
||||
```bash
|
||||
sed -n '1,240p' docs/prds/01-project-management.md
|
||||
for ARCHIE_DOC in docs/prds/architecture/*.md; do sed -n '1,8p' "$ARCHIE_DOC"; done
|
||||
go list -f '{{.ImportPath}}' ./internal/... | sort
|
||||
rg -n '^func main\\(' cmd
|
||||
rg -n '\\bconfig\\.' cmd internal --glob '*.go'
|
||||
rg -n 'legacy|compat|deprecated|TODO|FIXME|HACK' cmd internal docs --glob '*.go' --glob '*.md'
|
||||
git log --oneline --decorate --all -- cmd internal docs/prds/architecture
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-architecture-inventory-cache go run .claude/skills/archie-architecture-planning-campaign/scripts/go-inventory.go -root . -scope internal/config -include-tests=false
|
||||
task --list
|
||||
```
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Archie Architecture Planning Campaign"
|
||||
short_description: "Plan maintainable Archie architecture before coding"
|
||||
default_prompt: "Use $archie-architecture-planning-campaign to design and gate an Archie architectural change before implementation."
|
||||
@@ -0,0 +1,231 @@
|
||||
// Command go-inventory emits a stable TSV inventory of Go declarations.
|
||||
//
|
||||
// It uses the Go parser instead of text matching, so architecture research can
|
||||
// enumerate imports, types, struct fields, functions, methods, variables, and
|
||||
// constants before tracing their references with gopls.
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"flag"
|
||||
"fmt"
|
||||
"go/ast"
|
||||
"go/format"
|
||||
"go/parser"
|
||||
"go/token"
|
||||
"io/fs"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"sort"
|
||||
"strconv"
|
||||
"strings"
|
||||
)
|
||||
|
||||
type record struct {
|
||||
kind string
|
||||
pkg string
|
||||
file string
|
||||
line int
|
||||
name string
|
||||
detail string
|
||||
sortKey string
|
||||
}
|
||||
|
||||
func main() {
|
||||
rootFlag := flag.String("root", ".", "repository root")
|
||||
scopeFlag := flag.String("scope", "internal", "repository-relative directory to inspect")
|
||||
includeTests := flag.Bool("include-tests", true, "include _test.go files")
|
||||
flag.Parse()
|
||||
|
||||
root, err := filepath.Abs(*rootFlag)
|
||||
if err != nil {
|
||||
fatalf("resolve root: %v", err)
|
||||
}
|
||||
scope, err := confinedPath(root, *scopeFlag)
|
||||
if err != nil {
|
||||
fatalf("resolve scope: %v", err)
|
||||
}
|
||||
|
||||
fset := token.NewFileSet()
|
||||
var records []record
|
||||
err = filepath.WalkDir(scope, func(path string, entry fs.DirEntry, walkErr error) error {
|
||||
if walkErr != nil {
|
||||
return walkErr
|
||||
}
|
||||
if entry.IsDir() {
|
||||
switch entry.Name() {
|
||||
case ".git", "node_modules", "testdata", "vendor":
|
||||
if path != scope {
|
||||
return filepath.SkipDir
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
if filepath.Ext(path) != ".go" || (!*includeTests && strings.HasSuffix(path, "_test.go")) {
|
||||
return nil
|
||||
}
|
||||
|
||||
parsed, parseErr := parser.ParseFile(fset, path, nil, 0)
|
||||
if parseErr != nil {
|
||||
return fmt.Errorf("parse %s: %w", path, parseErr)
|
||||
}
|
||||
relative, relErr := filepath.Rel(root, path)
|
||||
if relErr != nil {
|
||||
return relErr
|
||||
}
|
||||
relative = filepath.ToSlash(relative)
|
||||
pkg := filepath.ToSlash(filepath.Dir(relative))
|
||||
records = append(records, fileRecords(fset, parsed, pkg, relative)...)
|
||||
return nil
|
||||
})
|
||||
if err != nil {
|
||||
fatalf("inventory: %v", err)
|
||||
}
|
||||
|
||||
sort.Slice(records, func(i, j int) bool {
|
||||
return records[i].sortKey < records[j].sortKey
|
||||
})
|
||||
fmt.Println("KIND\tPACKAGE\tFILE\tLINE\tNAME\tDETAIL")
|
||||
for _, item := range records {
|
||||
fmt.Printf("%s\t%s\t%s\t%d\t%s\t%s\n",
|
||||
item.kind,
|
||||
item.pkg,
|
||||
item.file,
|
||||
item.line,
|
||||
sanitize(item.name),
|
||||
sanitize(item.detail),
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
func confinedPath(root, scope string) (string, error) {
|
||||
if filepath.IsAbs(scope) {
|
||||
return "", fmt.Errorf("scope must be repository-relative")
|
||||
}
|
||||
clean := filepath.Clean(scope)
|
||||
if clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator)) {
|
||||
return "", fmt.Errorf("scope escapes repository root")
|
||||
}
|
||||
path := filepath.Join(root, clean)
|
||||
info, err := os.Stat(path)
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
if !info.IsDir() {
|
||||
return "", fmt.Errorf("%s is not a directory", clean)
|
||||
}
|
||||
return path, nil
|
||||
}
|
||||
|
||||
func fileRecords(fset *token.FileSet, file *ast.File, pkg, relative string) []record {
|
||||
var records []record
|
||||
add := func(kind string, pos token.Pos, name, detail string) {
|
||||
line := fset.Position(pos).Line
|
||||
records = append(records, record{
|
||||
kind: kind,
|
||||
pkg: pkg,
|
||||
file: relative,
|
||||
line: line,
|
||||
name: name,
|
||||
detail: detail,
|
||||
sortKey: strings.Join([]string{pkg, relative, fmt.Sprintf("%09d", line), kind, name}, "\x00"),
|
||||
})
|
||||
}
|
||||
|
||||
for _, imported := range file.Imports {
|
||||
path, err := strconv.Unquote(imported.Path.Value)
|
||||
if err != nil {
|
||||
path = imported.Path.Value
|
||||
}
|
||||
name := ""
|
||||
if imported.Name != nil {
|
||||
name = imported.Name.Name
|
||||
}
|
||||
add("IMPORT", imported.Pos(), name, path)
|
||||
}
|
||||
|
||||
for _, declaration := range file.Decls {
|
||||
switch node := declaration.(type) {
|
||||
case *ast.FuncDecl:
|
||||
kind := "FUNC"
|
||||
name := node.Name.Name
|
||||
if node.Recv != nil && len(node.Recv.List) > 0 {
|
||||
kind = "METHOD"
|
||||
name = expression(node.Recv.List[0].Type) + "." + name
|
||||
}
|
||||
add(kind, node.Pos(), name, expression(node.Type))
|
||||
case *ast.GenDecl:
|
||||
for _, spec := range node.Specs {
|
||||
switch item := spec.(type) {
|
||||
case *ast.TypeSpec:
|
||||
detail := typeKind(item.Type)
|
||||
add("TYPE", item.Pos(), item.Name.Name, detail)
|
||||
structType, ok := item.Type.(*ast.StructType)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
for _, field := range structType.Fields.List {
|
||||
fieldNames := make([]string, 0, len(field.Names))
|
||||
for _, name := range field.Names {
|
||||
fieldNames = append(fieldNames, name.Name)
|
||||
}
|
||||
if len(fieldNames) == 0 {
|
||||
fieldNames = append(fieldNames, expression(field.Type))
|
||||
}
|
||||
for _, fieldName := range fieldNames {
|
||||
add("FIELD", field.Pos(), item.Name.Name+"."+fieldName, expression(field.Type))
|
||||
}
|
||||
}
|
||||
case *ast.ValueSpec:
|
||||
kind := "VAR"
|
||||
if node.Tok == token.CONST {
|
||||
kind = "CONST"
|
||||
}
|
||||
for _, name := range item.Names {
|
||||
add(kind, item.Pos(), name.Name, expression(item.Type))
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return records
|
||||
}
|
||||
|
||||
func expression(node ast.Node) string {
|
||||
if node == nil {
|
||||
return ""
|
||||
}
|
||||
var buffer bytes.Buffer
|
||||
if err := format.Node(&buffer, token.NewFileSet(), node); err != nil {
|
||||
return fmt.Sprintf("%T", node)
|
||||
}
|
||||
return buffer.String()
|
||||
}
|
||||
|
||||
func typeKind(node ast.Expr) string {
|
||||
switch node.(type) {
|
||||
case *ast.StructType:
|
||||
return "struct"
|
||||
case *ast.InterfaceType:
|
||||
return "interface"
|
||||
case *ast.FuncType:
|
||||
return "func"
|
||||
case *ast.ArrayType:
|
||||
return "array-or-slice"
|
||||
case *ast.MapType:
|
||||
return "map"
|
||||
case *ast.ChanType:
|
||||
return "chan"
|
||||
default:
|
||||
return expression(node)
|
||||
}
|
||||
}
|
||||
|
||||
func sanitize(value string) string {
|
||||
return strings.Join(strings.Fields(value), " ")
|
||||
}
|
||||
|
||||
func fatalf(format string, args ...any) {
|
||||
fmt.Fprintf(os.Stderr, format+"\n", args...)
|
||||
os.Exit(1)
|
||||
}
|
||||
@@ -0,0 +1,424 @@
|
||||
---
|
||||
name: archie-build-and-env
|
||||
description: Recreate, inspect, and troubleshoot Archie Core's development, build, test, documentation, and container toolchains. Use when onboarding a checkout; diagnosing Go, Task, golangci-lint, gofumpt, pnpm, VitePress, Docker/Compose, NATS, GPG, cache, temporary-directory, listener, or network failures; comparing local work with repository automation; or proving which build surfaces a command actually covers. Load this before running task check in an unfamiliar or restricted environment because that gate rewrites files and omits several independent surfaces.
|
||||
---
|
||||
|
||||
# Build and verify the Archie environment
|
||||
|
||||
Recreate the environment as independently verified surfaces. Do not turn a
|
||||
passing root-module command into a claim that the tools module, documentation
|
||||
site, race detector, linter, or container images also passed.
|
||||
|
||||
All volatile observations in this skill are snapshots from **2026-07-28**.
|
||||
Re-run the maintenance commands at the end before relying on a number or
|
||||
installed version.
|
||||
|
||||
## Keep the scope narrow
|
||||
|
||||
- Do not use this skill to decide whether evidence is sufficient for acceptance.
|
||||
Load `archie-validation-and-qa`.
|
||||
- Do not use it to start, stop, deploy, upgrade, or recover a running daemon.
|
||||
Load `archie-run-and-operate`.
|
||||
- Do not use it to interpret a product failure after the environment is known
|
||||
good. Load `archie-debugging-playbook`.
|
||||
- Do not use it to choose or wire runtime settings. Load
|
||||
`archie-config-and-flags`.
|
||||
- Do not use it to approve generated changes, dependency updates, cleanup, or
|
||||
gate changes. Load `archie-change-control`.
|
||||
- Do not use `docs-2/README.md` as onboarding documentation. It describes Tau,
|
||||
and VitePress excludes it through `srcExclude` in
|
||||
`docs-2/.vitepress/config.mts`.
|
||||
|
||||
## Name the surfaces
|
||||
|
||||
Use these terms consistently:
|
||||
|
||||
| Term | Meaning here |
|
||||
|---|---|
|
||||
| Repository root | The directory containing `go.mod`, `Taskfile.yml`, and `CLAUDE.md`. |
|
||||
| Runtime module | The root Go module, `github.com/samcharles93/archie-core`. It owns `cmd/`, `domain/`, and `internal/`. |
|
||||
| Tools module | The independent nested Go module under `tools/`. It currently owns `tools/docsgen`. |
|
||||
| Docs site | The pnpm/VitePress project under `docs-2/`. |
|
||||
| Cold cache | A dependency cache that does not yet contain the required modules or packages; filling it requires network access. |
|
||||
| Restricted sandbox | An environment that may allow file reads but deny loopback listeners, the container engine, or writes to default caches and temporary directories. |
|
||||
| Host run | A run on an environment that permits the listeners and process features used by the tests. |
|
||||
|
||||
No root `README*` or `CONTRIBUTING*` file exists as of the snapshot. Begin with:
|
||||
|
||||
```bash
|
||||
sed -n '1,240p' CLAUDE.md
|
||||
sed -n '1,240p' ARCHITECTURE.md
|
||||
task --list
|
||||
```
|
||||
|
||||
Treat `CLAUDE.md` and `Taskfile.yml` as the current workflow contract. Treat
|
||||
`ARCHITECTURE.md` as necessary design context, but verify implemented package
|
||||
claims against current code and tests.
|
||||
|
||||
## Inventory requirements before installing anything
|
||||
|
||||
Do not guess versions from the installed machine. Compare the checkout's
|
||||
declarations with the machine:
|
||||
|
||||
```bash
|
||||
go version
|
||||
go env GOTOOLCHAIN GOVERSION GOOS GOARCH CGO_ENABLED GOTMPDIR GOCACHE GOMODCACHE
|
||||
task --version
|
||||
gofumpt -version
|
||||
golangci-lint version
|
||||
node --version
|
||||
pnpm --version
|
||||
npm --version
|
||||
docker --version
|
||||
docker compose version
|
||||
git --version
|
||||
gpg --version
|
||||
```
|
||||
|
||||
Classify a missing command as an environment prerequisite, not a code failure.
|
||||
The repository has no bootstrap installer and does not pin every host tool.
|
||||
If you must bootstrap from scratch, the Dockerfiles provide a known-good
|
||||
starting point (verified 2026-07-28):
|
||||
|
||||
- Go ≥ 1.26.3 (Docker builder uses `golang:1.26-trixie`)
|
||||
- Task ≥ 3.x (`go install github.com/go-task/task/v3/cmd/task@latest`)
|
||||
- gofumpt (`go install mvdan.cc/gofumpt@latest`; unpinned in repo)
|
||||
- golangci-lint v2 (`go install github.com/golangci-lint/v2/cmd/golangci-lint@latest`; unpinned)
|
||||
- Node 24.x + pnpm ≥ 10 (see Dockerfile's `setup_24.x` and `npm install -g pnpm`)
|
||||
|
||||
Always verify each installed version against the table below and record the
|
||||
exact version in failure reports. The repository does not guarantee that
|
||||
`@latest` today matches what was tested on the snapshot date.
|
||||
|
||||
| Surface | Repository declaration | Installed snapshot | Interpretation |
|
||||
|---|---|---|---|
|
||||
| Runtime Go | `go 1.26.3` in `go.mod` | Go 1.26.5, linux/amd64 | The checkout requires at least the declared Go language/toolchain level. |
|
||||
| Tools Go | `go 1.26.4` in `tools/go.mod` | Same Go 1.26.5 binary | Use a toolchain that satisfies both modules. |
|
||||
| Task | Taskfile schema `version: "3"`; no executable version pin | Task 3.48.0 | Installed version is an environment fact, not a repo guarantee. |
|
||||
| gofumpt | Used by `task fmt`; agent image installs `@latest` | v0.7.0 | Unpinned by the repository. |
|
||||
| golangci-lint | v2 config in `.golangci.yml`; agent image installs `@latest` | 2.12.2 | Use the v2 CLI; exact release is unpinned. |
|
||||
| Node | Docs CI uses `node-version: latest`; agent image configures Node 24 | 24.18.0 | The docs project has no `engines` or `packageManager` field. |
|
||||
| pnpm | Docs CI selects major 10; agent image installs an unpinned global pnpm | 11.15.1 | Prefer CI's major 10 when reproducing CI. Do not call local 11 exact parity. |
|
||||
| VitePress | `^1.6.4`, locked to 1.6.4 | Resolved by `pnpm-lock.yaml` | Install with the frozen lockfile. |
|
||||
| Containers | Docker Compose commands in `Taskfile.yml` | `/usr/bin/docker` is a Podman-backed CLI that is unusable in this sandbox | Verify CLI, Compose plugin, daemon/socket, and privileges separately. |
|
||||
|
||||
The Docker builders use `golang:1.26-trixie` and
|
||||
`golang:1.26-bookworm`, while the agent runtime separately installs
|
||||
`GO_VERSION=1.26.5`. The builder tags float across patch/image rebuilds; they do
|
||||
not establish byte-for-byte reproducibility.
|
||||
|
||||
## Prepare writable caches in a restricted sandbox
|
||||
|
||||
First inspect the defaults:
|
||||
|
||||
```bash
|
||||
go env GOTMPDIR GOCACHE GOMODCACHE GOPATH
|
||||
df -T /tmp
|
||||
```
|
||||
|
||||
If any default is read-only, create task-specific paths. Do not repurpose
|
||||
`HOME`, `CODEX_HOME`, or another system variable:
|
||||
|
||||
```bash
|
||||
export ARCHIE_GOTMPDIR=/tmp/archie-core-gotmp
|
||||
export ARCHIE_GOCACHE=/tmp/archie-core-gocache
|
||||
export ARCHIE_GOMODCACHE=/tmp/archie-core-gomodcache
|
||||
export ARCHIE_GOPATH=/tmp/archie-core-gopath
|
||||
export ARCHIE_LINT_CACHE=/tmp/archie-core-golangci
|
||||
mkdir -p "$ARCHIE_GOTMPDIR" "$ARCHIE_GOCACHE" "$ARCHIE_GOMODCACHE" \
|
||||
"$ARCHIE_GOPATH" "$ARCHIE_LINT_CACHE"
|
||||
```
|
||||
|
||||
Prefix Go commands with:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR="$ARCHIE_GOTMPDIR" GOCACHE="$ARCHIE_GOCACHE" \
|
||||
GOMODCACHE="$ARCHIE_GOMODCACHE" GOPATH="$ARCHIE_GOPATH" \
|
||||
go test ./internal/config/... -count=1
|
||||
```
|
||||
|
||||
An empty `ARCHIE_GOMODCACHE` is a cold cache. Populate each module only when
|
||||
network access is authorized:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR="$ARCHIE_GOTMPDIR" GOCACHE="$ARCHIE_GOCACHE" \
|
||||
GOMODCACHE="$ARCHIE_GOMODCACHE" GOPATH="$ARCHIE_GOPATH" \
|
||||
go mod download
|
||||
env GOTMPDIR="$ARCHIE_GOTMPDIR" GOCACHE="$ARCHIE_GOCACHE" \
|
||||
GOMODCACHE="$ARCHIE_GOMODCACHE" GOPATH="$ARCHIE_GOPATH" \
|
||||
go -C tools mod download
|
||||
```
|
||||
|
||||
On this machine `/tmp` is tmpfs. Caches therefore consume memory-backed
|
||||
storage. Measure them instead of filling them blindly:
|
||||
|
||||
```bash
|
||||
du -sh "$ARCHIE_GOTMPDIR" "$ARCHIE_GOCACHE" "$ARCHIE_GOMODCACHE" \
|
||||
"$ARCHIE_GOPATH" "$ARCHIE_LINT_CACHE"
|
||||
```
|
||||
|
||||
## Recreate the root Go surface
|
||||
|
||||
Use this cold-start sequence from the repository root:
|
||||
|
||||
1. Confirm the module and entry points.
|
||||
2. Download dependencies if the cache is cold and network is allowed.
|
||||
3. Compile both binaries.
|
||||
4. Run a focused test before the full suite.
|
||||
5. Run vet and lint as separate facts.
|
||||
|
||||
```bash
|
||||
test -f go.mod
|
||||
test -f cmd/archied/main.go
|
||||
test -f cmd/archie-agent/main.go
|
||||
go list -m
|
||||
go build -o /tmp/archie-core-archied ./cmd/archied
|
||||
go build -o /tmp/archie-core-agent ./cmd/archie-agent
|
||||
go test ./internal/config/... -count=1
|
||||
go vet ./...
|
||||
golangci-lint run ./...
|
||||
```
|
||||
|
||||
Use the cache prefix from the previous section when defaults are read-only.
|
||||
Writing binaries to `/tmp` verifies compilation without changing `bin/` or
|
||||
Task's `.task/` checksum state. The equivalent repository task is:
|
||||
|
||||
```bash
|
||||
task build
|
||||
```
|
||||
|
||||
Expect `task build` to write `bin/archied`, `bin/archie-agent`, and Task cache
|
||||
state. Do not use it during a read-only review.
|
||||
|
||||
## Understand exactly what Task runs
|
||||
|
||||
Read `Taskfile.yml`; do not infer command graphs from task names.
|
||||
|
||||
| Task | Exact effect |
|
||||
|---|---|
|
||||
| `task fmt` | Runs `gofumpt -w .`, then `go fix ./...`; both may rewrite source. |
|
||||
| `task vet` | Runs `go vet ./...` in the runtime module. |
|
||||
| `task lint` | Runs `golangci-lint run ./...`; this is separate from `task check`. |
|
||||
| `task build` | Builds both commands into `bin/`. |
|
||||
| `task test` | Runs `go test ./... -count=1` in the runtime module. |
|
||||
| `task check` | Runs `fmt`, runs `go fix ./...` a second time, then `vet`, `build`, and `test`. |
|
||||
| `task clean` | Recursively removes `bin/`; treat it as destructive. |
|
||||
| `task docker-build` | Runs `docker compose build agent` only. |
|
||||
|
||||
Repository doctrine calls `task check` the definitive gate. Its current
|
||||
implementation is still only one surface: it omits `task lint`, race tests, the
|
||||
`tools/` module, docs generation drift, and the VitePress build.
|
||||
|
||||
Run `task check` only in an authorized writable worktree. Record its rewrites:
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
task check
|
||||
git status --short
|
||||
git diff --check
|
||||
```
|
||||
|
||||
Never claim that pre-existing changes were produced by the gate. Capture the
|
||||
first status before running it.
|
||||
|
||||
For a read-only formatting preview, avoid `task fmt`:
|
||||
|
||||
```bash
|
||||
gofumpt -l .
|
||||
```
|
||||
|
||||
As of the snapshot, this produced no output. `go fix ./...` has no equivalent
|
||||
read-only task in this repository, so `task fmt` and `task check` remain
|
||||
mutating commands even when the gofumpt preview is clean.
|
||||
|
||||
## Verify the tools module separately
|
||||
|
||||
The repository has no `go.work`. A root `go test ./...` does not enter
|
||||
`tools/`. The tools module uses:
|
||||
|
||||
```text
|
||||
module github.com/samcharles93/archie-core/tools
|
||||
replace github.com/samcharles93/archie-core => ../
|
||||
```
|
||||
|
||||
Run its tests explicitly:
|
||||
|
||||
```bash
|
||||
go -C tools test ./... -count=1
|
||||
```
|
||||
|
||||
Generate documentation data to a temporary file and compare it without
|
||||
rewriting the checkout:
|
||||
|
||||
```bash
|
||||
go -C tools run ./docsgen \
|
||||
-repo-root .. \
|
||||
-out /tmp/archie-core-contracts.json
|
||||
cmp --silent \
|
||||
docs-2/data/generated/contracts.json \
|
||||
/tmp/archie-core-contracts.json
|
||||
```
|
||||
|
||||
The 2026-07-28 run wrote 10 schemas, the comparison passed, and
|
||||
`go -C tools test ./... -count=1` passed. The planned `docsgen all` and
|
||||
`docsgen check` commands described in
|
||||
`docs/prds/architecture/generated-documentation.md` do **not** exist yet.
|
||||
The checkout's `docs-2/data/generated/contracts.json` exists but is untracked
|
||||
as of this snapshot. The comparison proves local generator parity, not
|
||||
version-controlled drift protection.
|
||||
|
||||
## Recreate and build the docs site
|
||||
|
||||
Treat dependency installation and site compilation as two separate gates:
|
||||
|
||||
```bash
|
||||
pnpm --dir docs-2 install --frozen-lockfile
|
||||
pnpm --dir docs-2 build
|
||||
```
|
||||
|
||||
The install needs registry access on a cold pnpm store. The build writes
|
||||
`docs-2/.vitepress/dist`. GitHub Pages CI uses pnpm major 10, Node `latest`,
|
||||
the frozen lockfile, then `pnpm build`; it does not run Go tests or docsgen.
|
||||
|
||||
The docs build could not be completed in the restricted 2026-07-28 session
|
||||
because missing packages required npm registry access and DNS returned
|
||||
`EAI_AGAIN`. Record that as an environment result, not a passing or failing
|
||||
site build.
|
||||
|
||||
Do not trust the checked-in `docs-2/node_modules` shape. It contains 237
|
||||
tracked symlink entries as of the snapshot, introduced by commit `308c199`.
|
||||
Detect the condition:
|
||||
|
||||
```bash
|
||||
git ls-files -s 'docs-2/node_modules/**' \
|
||||
| awk '$1 == "120000" {count++} END {print count+0}'
|
||||
git status --short -- docs-2
|
||||
```
|
||||
|
||||
Do not stage, normalize, or mass-delete that tree as incidental setup. Route
|
||||
its cleanup through `archie-change-control`. Commit `4cb0577` records a
|
||||
separate cleanup of accidentally committed `.gotmp` build/test artifacts;
|
||||
`.gotmp/` is now ignored.
|
||||
|
||||
## Treat container setup as a networked, privileged surface
|
||||
|
||||
Before building, inspect the context and pinning:
|
||||
|
||||
```bash
|
||||
test -e .dockerignore || echo ".dockerignore is absent"
|
||||
rg -n '^(FROM|[[:space:]]*image:)|@latest|:latest|setup_24.x' \
|
||||
Dockerfile Dockerfile.archied docker-compose.yml
|
||||
git status --short
|
||||
```
|
||||
|
||||
No `.dockerignore` exists as of the snapshot. Both Dockerfiles run
|
||||
`COPY . .`; `.gitignore` does not filter a Docker build context. Local ignored
|
||||
configuration, `.git`, caches, dependency trees, worktrees, and scratch data
|
||||
can therefore be sent to the builder. Stop and inspect the context before any
|
||||
build from a non-clean checkout.
|
||||
|
||||
The images also contain floating inputs:
|
||||
|
||||
- both Go builder image tags omit a patch version or digest;
|
||||
- Ubuntu base images omit digests;
|
||||
- the agent image installs multiple Go tools with `@latest`;
|
||||
- Node comes from the moving `setup_24.x` channel;
|
||||
- global npm tools are unpinned;
|
||||
- Compose consumes `archied:latest`, `archie-agent:latest`, and an untagged
|
||||
watchtower image.
|
||||
|
||||
Do not label a rebuild reproducible. Treat pinning or build-context changes as
|
||||
change-controlled work.
|
||||
|
||||
`task docker-build` needs registry/network access and a functioning Compose
|
||||
engine. `task docker-up` additionally pulls images, binds ports 4222, 8222, and
|
||||
8484, mounts host paths and the container socket, and consumes external
|
||||
configuration and credentials. Load `archie-run-and-operate` before using it.
|
||||
|
||||
## Separate environment failures from code failures
|
||||
|
||||
| Signature | Classify and branch |
|
||||
|---|---|
|
||||
| `go: creating work dir: mkdir /work/tmp/...: read-only file system` | `go env GOTMPDIR` points at a read-only path. Set task-specific `GOTMPDIR` under writable storage and retry. |
|
||||
| `open .../.cache/go-build/...: read-only file system` | Set a writable `GOCACHE`. |
|
||||
| `open .../pkg/mod/cache/...tmp: read-only file system` | Set writable `GOMODCACHE` and `GOPATH`; expect network access if the new cache is cold. |
|
||||
| `listen ...: socket: operation not permitted` | The sandbox denies local listeners. Re-run on a host that permits loopback sockets; do not delete the integration test. |
|
||||
| `Unable to start NATS Server in Go Routine` after about 10 seconds | First test whether local listeners are permitted. Embedded-NATS tests share this environmental requirement. |
|
||||
| `cannot auto-sign commit` | Ambient `commit.gpgSign=true` reached a go-git fixture. Current worktree code and fixtures explicitly set repository-local `gpgsign=false`; a recurrence may be a regression. |
|
||||
| `EAI_AGAIN` for `registry.npmjs.org` | Dependency retrieval failed. Do not diagnose VitePress until installation succeeds. |
|
||||
| `Failed to obtain podman configuration ... /run/user/.../libpod: read-only file system` | The Docker-compatible CLI cannot initialize its container backend in this sandbox. Move the container check to a suitable host. |
|
||||
| `TestRunWrapsExternalCommand ... Run() = "\n"` | This is a focused, listener-independent code failure in `internal/skillscript`, not an environment failure. |
|
||||
|
||||
For hermetic test diagnosis only, suppress ambient global Git configuration:
|
||||
|
||||
```bash
|
||||
env GIT_CONFIG_GLOBAL=/dev/null \
|
||||
go test ./internal/worktree/... ./internal/worktreerpc/... -count=1
|
||||
```
|
||||
|
||||
Do not apply `GIT_CONFIG_GLOBAL=/dev/null` to runtime or deployment commands
|
||||
that intentionally need host credentials or URL rewrites.
|
||||
|
||||
## Use the complete validation matrix
|
||||
|
||||
Choose rows by changed surface, then let `archie-validation-and-qa` decide the
|
||||
required acceptance set.
|
||||
|
||||
| Evidence | Command | Current snapshot |
|
||||
|---|---|---|
|
||||
| Focused Go behavior | `go test ./path/to/package/... -run '^TestName$' -count=1 -v` | Use first; distinguish a real failure from broad-suite noise. |
|
||||
| Root unit/integration suite | `go test ./... -count=1` | Restricted sandbox also fails listener-dependent packages. A focused `internal/skillscript` test has a genuine failure. |
|
||||
| Root race suite | `go test -race ./... -count=1` | Not run by `task check`; no current green claim. |
|
||||
| Vet | `go vet ./...` | Passed on 2026-07-28. |
|
||||
| Lint | `golangci-lint run ./...` | Failed with 54 findings on 2026-07-28; `task check` does not expose them. |
|
||||
| Build | `go build -o /tmp/archie-core-archied ./cmd/archied` and the analogous `archie-agent` command | Both passed on 2026-07-28. |
|
||||
| Tools tests | `go -C tools test ./... -count=1` | Passed on 2026-07-28. |
|
||||
| Local generated contract parity | Temporary docsgen output plus `cmp --silent` | Passed for 10 schemas on 2026-07-28; the checkout output is untracked. |
|
||||
| Docs install/build | `pnpm --dir docs-2 install --frozen-lockfile` then `pnpm --dir docs-2 build` | Blocked by restricted network; unknown, not failed. |
|
||||
| Container build | `task docker-build` | Not verified in the restricted container environment. |
|
||||
| Repository gate | `task check` | Currently non-green because the root suite reaches the genuine skillscript failure; it may also rewrite files first. |
|
||||
|
||||
Do not hide a baseline failure by reporting only a focused pass. Record the
|
||||
exact command, environment restrictions, exit status, and first actionable
|
||||
failure.
|
||||
|
||||
## Cold-start completion checklist
|
||||
|
||||
- [ ] Read `CLAUDE.md`, `ARCHITECTURE.md`, and `Taskfile.yml`.
|
||||
- [ ] Verify installed commands and compare them with repo declarations.
|
||||
- [ ] Confirm writable temp and cache paths without changing system variables.
|
||||
- [ ] Distinguish cold-cache network needs from compilation failures.
|
||||
- [ ] Build both Go commands.
|
||||
- [ ] Run a focused test, vet, lint, and the root suite.
|
||||
- [ ] Run the tools-module tests explicitly.
|
||||
- [ ] Generate docs contracts to `/tmp` and compare the checkout output.
|
||||
- [ ] Install and build docs only with authorized registry access.
|
||||
- [ ] Inspect Docker context and floating inputs before any image build.
|
||||
- [ ] Record sandbox listener/container restrictions.
|
||||
- [ ] Hand acceptance decisions to `archie-validation-and-qa`.
|
||||
|
||||
## Provenance and maintenance
|
||||
|
||||
Ground this skill in `CLAUDE.md`, `Taskfile.yml`, `.golangci.yml`, `go.mod`,
|
||||
`tools/go.mod`, `tools/docsgen/`, `docs-2/package.json`,
|
||||
`docs-2/pnpm-lock.yaml`, `.github/workflows/docs.yml`, both Dockerfiles,
|
||||
`docker-compose.yml`, `.gitea/workflows/deploy.yml`, `.gitignore`,
|
||||
`internal/worktree/`, and the tests named above.
|
||||
|
||||
Re-verify module/toolchain declarations:
|
||||
`sed -n '1,40p' go.mod; sed -n '1,40p' tools/go.mod; go version; task --version; gofumpt -version; golangci-lint version`
|
||||
|
||||
Re-verify Task coverage:
|
||||
`sed -n '1,180p' Taskfile.yml; rg -n 'task: lint|go test.*race|go -C tools|docsgen|pnpm' Taskfile.yml`
|
||||
|
||||
Re-verify docs and CI:
|
||||
`sed -n '1,120p' docs-2/package.json; sed -n '1,120p' .github/workflows/docs.yml; go -C tools test ./... -count=1`
|
||||
|
||||
Re-verify container inputs:
|
||||
`test -e .dockerignore || echo ABSENT; rg -n '^(FROM|[[:space:]]*image:)|@latest|:latest' Dockerfile Dockerfile.archied docker-compose.yml .gitea/workflows/deploy.yml`
|
||||
|
||||
Re-verify artifact counts:
|
||||
`git ls-files 'docs-2/node_modules/**' | wc -l; git ls-files '.gotmp/**' | wc -l`
|
||||
|
||||
Re-verify current failures:
|
||||
`go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v; golangci-lint run ./...`
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Archie Build and Environment"
|
||||
short_description: "Recreate and verify the Archie toolchain"
|
||||
default_prompt: "Use $archie-build-and-env to recreate a clean Archie development environment and verify every build surface."
|
||||
@@ -0,0 +1,411 @@
|
||||
---
|
||||
name: archie-change-control
|
||||
description: "Classify, investigate, plan, gate, review, and accept archie-core changes without trading maintainability for a passing test. Use before changing or approving architecture, Go source, configuration, runtime lifecycle, dependencies, protocols, persistence, security boundaries, deployments, generated documentation, or read-only designs; also use when deciding whether scoped evidence is sufficient, whether an old path must be deprecated or deleted, or whether a change is ready to close."
|
||||
---
|
||||
|
||||
# Archie change control
|
||||
|
||||
Protect Archie's quality, not merely its test result. Treat a passing test as
|
||||
necessary evidence for code changes, never as proof that the design is coherent,
|
||||
the old path is gone, or production selects the new path.
|
||||
|
||||
## Route to the right sibling
|
||||
|
||||
Use this skill to control a change from classification through acceptance.
|
||||
Load these siblings for the specialized work:
|
||||
|
||||
| Need | Load |
|
||||
|---|---|
|
||||
| Design or revise boundaries, ownership, package structure, or a migration | `archie-architecture-planning-campaign` |
|
||||
| Find duplication, hidden dead paths, poor names, misplaced responsibilities, or maintainability debt | `archie-technical-accountability` |
|
||||
| Design tests, reproduce a defect, select QA evidence, or run complete gates | `archie-validation-and-qa` |
|
||||
| Run, deploy, observe, recover, or roll back a live assembly | `archie-run-and-operate` |
|
||||
|
||||
Do **not** use this skill alone to:
|
||||
|
||||
- conduct an architecture campaign;
|
||||
- perform a deep code-quality or AST investigation;
|
||||
- invent a test strategy for a complex behaviour;
|
||||
- operate production;
|
||||
- replace the governing decision document for a domain.
|
||||
|
||||
## Use these terms consistently
|
||||
|
||||
| Term | Meaning here |
|
||||
|---|---|
|
||||
| Baseline | Recorded behaviour and gate output before the proposed change. |
|
||||
| Current state | Behaviour selected by the checked-out live code, not a PRD target or branch-only fix. |
|
||||
| Production wiring | The complete path by which a supported assembly selects, configures, runs, and observes an implementation. |
|
||||
| Authoritative contract | The source whose semantics the producer and consumer are required to obey; a projection or shared test fake is not authoritative. |
|
||||
| Compatibility adapter | Temporary code that preserves an older input or caller while migration proceeds, with explicit deletion criteria. |
|
||||
| Last-known-good | The previously active version proved healthy and retained for restoration. |
|
||||
| Evidence packet | Commands, outputs, traces, diffs, decisions, and reviews supporting acceptance. |
|
||||
| Acceptance | Permission to close the controlled work; it is not permission to push, deploy, migrate, or delete. |
|
||||
|
||||
## Apply the non-negotiables
|
||||
|
||||
| Rule | Why it is mandatory | Repository evidence or incident |
|
||||
|---|---|---|
|
||||
| Investigate the live call path before planning. | A constructor, registry entry, config field, or test can exist without production ever selecting it. | Missing Compose passthroughs in `22fc0ef` and `d0624b7` left configured secrets absent at runtime. |
|
||||
| Test the authoritative contract, not a convenient projection. | A best-effort or mirrored interface can pass while the real producer blocks or the peer rejects the exchange. | `6a0bd27`: consuming `TextStream` instead of draining authoritative `FullStream` deadlocked every streamed reply. `3ad57c9`: recreating a buffered reader dropped MCP messages; the harness also masked process-exit behaviour. |
|
||||
| Preserve compatibility deliberately. Never rely on a decoder ignoring old input. | Silent omission turns a schema edit into an outage. | `1f8588d`: removing `[forge].token_env` compatibility caused both production containers to crash-loop because TOML ignored the old key. |
|
||||
| Make deployment dependencies explicit and observable. | Hostname, network, secret, mount, and environment assumptions differ between tests and the running Compose assembly. | `37cf089` and `2ac306b`: failed Docker-network auto-detection put workers on the default bridge, so NATS returned “no responders.” |
|
||||
| Inspect every mechanical or generated edit semantically. Never accept a broad cleanup by count alone. | Formatting, autofix, rebasing, and three-way application can alter behaviour or erase concurrent work. | `9b44bac`: `golangci-lint --fix` introduced a bad `:=` that would have defeated a timeout if it compiled. `affc717`: worktree diffs were based on an older tree and required explicit survival checks. `308c199`: a broad cleanup changed the skillscript command so its test now emits only a newline. |
|
||||
| Enforce lifecycle transitions and audit atomically. | Ignoring expected state permits lost updates; splitting state and history permits contradictory evidence. | As of 2026-07-28, `internal/store.Store.Transition` ignores `from` and performs two writes. Fix `a7f294e` exists only on `origin/fix/48-transition-ignores-from-status-guard-allowing-lost-updates`, not on `main`; the Nell adapter also does not record equivalent transition history. |
|
||||
| Keep deterministic constraints outside the proposing model. | A prompt can be ignored to make a test pass. | `CLAUDE.md` requires gates, protected tests, and diff limits to be code-enforced; the model never owns git operations. |
|
||||
| Require a fresh adversarial reviewer after green. | The implementer is biased toward the path it just made pass. | `CLAUDE.md` makes a memory-independent review mandatory and blocks completion on surviving findings. |
|
||||
|
||||
## Classify the change
|
||||
|
||||
Classify every affected surface. For a composite change, apply the union of all
|
||||
required controls and use the highest-risk class.
|
||||
|
||||
| Class | Examples | Minimum control |
|
||||
|---|---|---|
|
||||
| Read-only investigation | Review, diagnosis, inventory, impact map | Do not mutate. Cite live code, tests, history, and unresolved uncertainty. |
|
||||
| Design or documentation | PRD, ADR-like decision, architecture guide, skill | Separate current facts from approved target and open candidates. Validate links/format. Do not imply implementation. |
|
||||
| Source | Go behaviour, refactor, API, workflow | Current-state map, red-green, scoped iteration, architecture and maintainability review, final relevant gates. |
|
||||
| Configuration | Decoder, default, env name, overlay, secret reference, setting owner | Old/new input fixtures, precedence/default proof, production composition trace, invalid-input behaviour, explicit rollback. |
|
||||
| Runtime lifecycle | Start, stop, reload, concurrency, stream, retry, health | Cancellation/backpressure/failure tests, race test, bounded retry, shutdown and rollback proof. |
|
||||
| Dependency | Root or `tools` module dependency/version | Adoption rationale, API/behaviour delta, both module manifests as applicable, transitive/security review, reverse plan. |
|
||||
| Protocol | MCP, NATS, RPC, subprocess, JSON/wire schema | Version and compatibility matrix, independent-peer or recorded-wire evidence, malformed/partial/multi-message tests. |
|
||||
| Persistence | SQLite, NellDB, schema, lifecycle state, migrations | Old-data fixture, legal-transition and concurrency tests, atomic state/audit proof, backup/rollback strategy. |
|
||||
| Security or trust boundary | Secret flow, plugins, tools, containers, identity, authorization | Threat/authority analysis, deny tests, deterministic enforcement, fresh security review, no “subprocess equals sandbox” claims. |
|
||||
| Deployment | Dockerfile, Compose, image/tag, env passthrough, volume/network | Exact assembly validation, secret-name-to-container trace, health observation, previous image/config recovery plan. |
|
||||
| Generated documentation | `tools/docsgen`, registries, generated JSON, VitePress | Generator tests, byte-for-byte drift check, site build, generated-vs-handwritten ownership check. |
|
||||
|
||||
Escalate the risk class when the change crosses a process boundary, changes
|
||||
stored or wire data, changes operator-visible defaults, alters authorization,
|
||||
removes compatibility, or can affect a live deployment.
|
||||
|
||||
## Execute the control loop
|
||||
|
||||
### 1. Establish authority and scope
|
||||
|
||||
For implementation work, start from the existing Beads issue and claim it.
|
||||
Create durable work before writing code if no issue exists. Do not create a
|
||||
Markdown task list.
|
||||
|
||||
```bash
|
||||
bd prime
|
||||
: "${BEADS_ISSUE_ID:?set BEADS_ISSUE_ID to the target issue}"
|
||||
bd show "$BEADS_ISSUE_ID"
|
||||
bd update "$BEADS_ISSUE_ID" --claim
|
||||
```
|
||||
|
||||
For a review or investigation, remain read-only unless the user separately
|
||||
authorizes implementation.
|
||||
|
||||
Record:
|
||||
|
||||
- the requested outcome and explicit non-goals;
|
||||
- every selected change class;
|
||||
- files and domains believed to be in scope;
|
||||
- user authority for source, config, deployment, dependency, and destructive
|
||||
operations;
|
||||
- whether another session owns overlapping files.
|
||||
|
||||
### 2. Protect concurrent work
|
||||
|
||||
Inspect before editing:
|
||||
|
||||
```sh
|
||||
git status --short
|
||||
git diff --stat
|
||||
git worktree list --porcelain
|
||||
```
|
||||
|
||||
Treat every pre-existing change as somebody else's. Stop before overlapping it
|
||||
unless ownership and integration order are known. Never discard, reset, or
|
||||
silently reformat unrelated changes.
|
||||
|
||||
Partition parallel work by non-overlapping file ownership. Before applying an
|
||||
agent result based on another tree, compare its base and verify that every
|
||||
intervening semantic fix survives. The `affc717` history demonstrates why a
|
||||
cleanly applied diff is not proof of preservation.
|
||||
|
||||
Do not run broad autofix against a shared dirty tree. `task check` and
|
||||
`task fmt` are broad mutators; isolate them and inspect their complete diff.
|
||||
|
||||
### 3. Map the current state before proposing a change
|
||||
|
||||
Read `CLAUDE.md`, `ARCHITECTURE.md`, `docs/prds/01-project-management.md`, and
|
||||
the focused decision document linked from the architecture index.
|
||||
|
||||
For the selected behaviour, trace all of:
|
||||
|
||||
- entry points under `cmd/` and application composition;
|
||||
- constructors, registries, interfaces, adapters, and concrete selection;
|
||||
- every caller and consumer, including RPC/process peers;
|
||||
- settings, defaults, overlays, secrets, and deployment passthrough;
|
||||
- state ownership, persistence, lifecycle, cancellation, and recovery;
|
||||
- tests and what they do **not** exercise;
|
||||
- duplicated implementations, compatibility adapters, generated copies, and
|
||||
apparently dead paths;
|
||||
- git history for rejected, stalled, reverted, or branch-only work;
|
||||
- documents that disagree with live code.
|
||||
|
||||
Use read-only evidence:
|
||||
|
||||
```bash
|
||||
# Guard: verify repository root first
|
||||
git rev-parse --show-toplevel >/dev/null || { echo 'run from repo root' >&2; exit 1; }
|
||||
: "${ARCHIE_SYMBOL:?set ARCHIE_SYMBOL to the symbol or config key}"
|
||||
rg -n "$ARCHIE_SYMBOL" cmd internal config*.toml docker-compose.yml docs
|
||||
: "${ARCHIE_PACKAGE:?set ARCHIE_PACKAGE to the package path relative to repo root}"
|
||||
go list -deps "./internal/$ARCHIE_PACKAGE/..."
|
||||
: "${ARCHIE_PATHS:?set ARCHIE_PATHS to the space-separated affected paths}"
|
||||
git log --all --oneline -- $ARCHIE_PATHS
|
||||
git blame -- $ARCHIE_PATHS
|
||||
```
|
||||
|
||||
Do not ask the user for a fact the repository can reveal. Ask only when a real
|
||||
product, compatibility, ownership, or risk decision remains.
|
||||
|
||||
### 4. Write the change brief
|
||||
|
||||
Do not begin implementation until the brief answers:
|
||||
|
||||
| Question | Required answer |
|
||||
|---|---|
|
||||
| What owns this behaviour? | One cohesive domain/capability and the governing decision document. |
|
||||
| Where does production select it? | Exact entry point-to-implementation path. “Registered” is insufficient. |
|
||||
| What changes and what stays stable? | Behavioural contract, invariants, non-goals, and affected consumers. |
|
||||
| What does this supersede? | Every older or parallel path, with keep/merge/deprecate/delete decision. |
|
||||
| What gets deleted? | Obsolete code, compatibility adapters, duplicated config, tests, and docs, or a justified reason to retain each. |
|
||||
| What proves failure first? | A behavioural red test that fails for the intended reason, not a compile error. |
|
||||
| What proves maintainability? | Ownership, dependency direction, naming, size, duplication, and dead-path checks. |
|
||||
| What is the compatibility plan? | Old/new config, protocol, data, caller, and rollout combinations. |
|
||||
| How is it reversed? | Last-known-good state and evidence that reversal preserves data and service. |
|
||||
| What remains uncertain? | Explicit open/candidate claims; never convert a hunch into a requirement. |
|
||||
|
||||
If adding a feature makes an existing path redundant, deletion is part of the
|
||||
feature unless compatibility has a named owner, deadline or deletion
|
||||
criterion, and test. Do not leave two active paths merely because deleting the
|
||||
old one is harder.
|
||||
|
||||
Route boundary or ownership uncertainty through
|
||||
`archie-architecture-planning-campaign` before coding. Route unlocatable impact,
|
||||
duplication, or dead-path uncertainty through `archie-technical-accountability`.
|
||||
|
||||
### 5. Capture a baseline
|
||||
|
||||
Run the narrowest non-mutating checks that exercise the affected area before
|
||||
the red test. Preserve exact command, exit status, and output.
|
||||
|
||||
Example for one Go package:
|
||||
|
||||
```sh
|
||||
go test ./internal/gateway/... -count=1
|
||||
go vet ./internal/gateway/...
|
||||
golangci-lint run ./internal/gateway/...
|
||||
gofumpt -l internal/gateway
|
||||
```
|
||||
|
||||
Distinguish:
|
||||
|
||||
- **clean baseline**: proceed;
|
||||
- **unrelated known failure**: preserve its exact signature and escalate;
|
||||
- **failure in the affected surface**: do not build on it; repair or split the
|
||||
work with explicit authority;
|
||||
- **environment failure**: prove it is environmental before classifying it as
|
||||
non-code.
|
||||
|
||||
Do not call a baseline green when a command was skipped.
|
||||
|
||||
### 6. Apply red-green without surrendering design
|
||||
|
||||
1. Add a behavioural test for the intended contract.
|
||||
2. Run it and capture a meaningful failure.
|
||||
3. Implement the smallest coherent design, not the smallest patch.
|
||||
4. Run the focused test until green.
|
||||
5. Add every relevant error, boundary, compatibility, cancellation, and
|
||||
concurrency case.
|
||||
6. Re-read every changed non-test file for ownership, clarity, duplication,
|
||||
unused branches, and superseded paths.
|
||||
|
||||
Load `archie-validation-and-qa` for the test design. Load
|
||||
`archie-technical-accountability` before accepting “works but ugly” code.
|
||||
|
||||
Never weaken or rewrite the red test merely to admit the implementation.
|
||||
Environmental test protection is preferable to a prompt-only prohibition.
|
||||
|
||||
### 7. Prove production wiring
|
||||
|
||||
Demonstrate all applicable links:
|
||||
|
||||
```text
|
||||
external input
|
||||
-> decoder/adapter
|
||||
-> application composition
|
||||
-> selected implementation
|
||||
-> state or external effect
|
||||
-> observable outcome
|
||||
```
|
||||
|
||||
Test at the highest practical seam. A package unit test does not prove that
|
||||
`cmd/archied` supplies the new setting, registers the implementation, forwards
|
||||
the environment variable, chooses the right mode, or exposes the result.
|
||||
|
||||
For configuration, test the deployed legacy form and the new form. Verify both
|
||||
the source environment and `docker-compose.yml` passthrough. For protocols,
|
||||
verify bytes/messages with an independently implemented peer or fixture rather
|
||||
than a client and server sharing the same wrong assumption.
|
||||
|
||||
### 8. Make rollback executable
|
||||
|
||||
Identify last-known-good **before** changing runtime state. Define the trigger,
|
||||
owner, commands or deterministic mechanism, data consequences, and health check
|
||||
for restoration.
|
||||
|
||||
| Change | Required rollback evidence |
|
||||
|---|---|
|
||||
| Source or dependency | Exact prior version plus proof that reverting does not leave incompatible data, config, or generated output. |
|
||||
| Configuration | Prior accepted input and effective values, secret-safe diff, reload/restart consequence, and health check. |
|
||||
| Protocol | Old/new peer matrix; retain the old path until mixed-version operation or coordinated cutover is proved. |
|
||||
| Persistence | Backup/restore or reversible migration rehearsal against an old-data fixture; never call a destructive forward-only migration rollback-safe. |
|
||||
| Deployment | Previous image digest and config, exact supported assembly, restoration command, and post-restore observation. |
|
||||
| Generated documentation | Regenerate from authoritative definitions; never recover by hand-editing generated JSON. |
|
||||
|
||||
The candidate-promotion and automatic last-known-good protocol in
|
||||
`docs/prds/architecture/safe-change-and-recovery.md` is an approved requirement,
|
||||
but its exact Go contracts and atomicity boundary are explicitly still under
|
||||
design as of 2026-07-28. Do not claim Archie currently provides it. For live
|
||||
work, route the concrete manual or implemented recovery procedure through
|
||||
`archie-run-and-operate`.
|
||||
|
||||
### 9. Run the required evidence set
|
||||
|
||||
Use scoped checks while iterating. Use a scoped final gate only for a genuinely
|
||||
isolated single-package change allowed by `CLAUDE.md`. Require full and
|
||||
class-specific checks for cross-package, configuration, runtime, dependency,
|
||||
protocol, persistence, security, deployment, or generated-documentation work.
|
||||
|
||||
`task check` is repository doctrine but is not the complete evidence set:
|
||||
|
||||
```sh
|
||||
task check
|
||||
golangci-lint run ./...
|
||||
go test -race ./... -count=1
|
||||
go -C tools test ./... -count=1
|
||||
go -C tools vet ./...
|
||||
```
|
||||
|
||||
For generated contracts and the site, run the current commands:
|
||||
|
||||
```sh
|
||||
go -C tools test ./docsgen -count=1
|
||||
go -C tools run ./docsgen --repo-root .. --out /tmp/archie-contracts.check.json
|
||||
cmp /tmp/archie-contracts.check.json docs-2/data/generated/contracts.json
|
||||
pnpm --dir docs-2 build
|
||||
```
|
||||
|
||||
Inspect the diff after any formatter, fixer, generator, or `task check`. A zero
|
||||
exit status does not authorize unrelated edits.
|
||||
|
||||
### 10. Run fresh adversarial review
|
||||
|
||||
Give a reviewer with no implementation memory the requirement, governing
|
||||
architecture, current diff, and raw validation output. Require findings first;
|
||||
do not let that pass silently fix its own findings.
|
||||
|
||||
Require review of:
|
||||
|
||||
- production selection and every affected consumer;
|
||||
- correctness and error propagation;
|
||||
- architecture ownership and dependency direction;
|
||||
- obsolete, duplicate, disconnected, or single-use paths;
|
||||
- config/default/identity hardcoding;
|
||||
- interface satisfaction and wire compatibility;
|
||||
- nil, cancellation, goroutine, race, transaction, and rollback hazards;
|
||||
- whether tests prove the contract rather than mirror the implementation.
|
||||
|
||||
Resolve every blocking and important finding, rerun affected checks, then use a
|
||||
fresh final pass if semantics changed. Surviving findings block acceptance.
|
||||
|
||||
### 11. Accept or stop
|
||||
|
||||
Accept only when the evidence packet contains:
|
||||
|
||||
- issue/scope and all change classes;
|
||||
- current-state impact map and governing decisions;
|
||||
- baseline, red, green, and final command outputs;
|
||||
- production-wiring proof;
|
||||
- compatibility, deprecation, deletion, and rollback decisions;
|
||||
- architecture and maintainability review;
|
||||
- fresh adversarial review with zero surviving blocking or important findings;
|
||||
- explicit uncertainties and follow-up ownership;
|
||||
- no unexplained diff.
|
||||
|
||||
Do not close a Beads issue until its acceptance criteria and the session close
|
||||
protocol are satisfied. Do not push, deploy, migrate, or delete data without
|
||||
separate authority.
|
||||
|
||||
## Know the current gate gaps
|
||||
|
||||
**Volatile snapshot: 2026-07-28. Re-verify before every acceptance decision.**
|
||||
|
||||
- `task check` runs `task fmt`, which executes `gofumpt -w .` and
|
||||
`go fix ./...`; it then executes `go fix ./...` a second time before vet,
|
||||
build, and root tests. It mutates source.
|
||||
- `task check` does not run `task lint`, race tests, the nested `tools` module,
|
||||
docsgen drift checks, or the VitePress build.
|
||||
- Root `go test ./...` does not cross the nested `tools/go.mod` boundary.
|
||||
- `.gitea/workflows/deploy.yml` builds and pushes images without a Go quality
|
||||
job. `.github/workflows/docs.yml` installs and builds VitePress but does not
|
||||
run the Go gate or docsgen.
|
||||
- `go test ./internal/skillscript -count=1` currently fails
|
||||
`TestRunWrapsExternalCommand`: `Run() = "\n"`.
|
||||
- The approved generated-documentation document describes future
|
||||
`task docs:*` and `docsgen check` commands, but neither exists in the current
|
||||
`Taskfile.yml`/CLI. Use the current commands above.
|
||||
- No `task deadcode` target exists. Never report it as executed.
|
||||
|
||||
Repository doctrine still requires a clean relevant gate. A known baseline
|
||||
failure is not permission to report completion. Either repair it under
|
||||
separately controlled scope or report the work blocked with scoped no-regression
|
||||
evidence.
|
||||
|
||||
## Escalate instead of improvising
|
||||
|
||||
Stop and obtain a decision when:
|
||||
|
||||
- a requested feature conflicts with an approved architecture decision;
|
||||
- ownership or the production selection path remains ambiguous after research;
|
||||
- a new path overlaps an existing feature and no deprecation/deletion decision
|
||||
exists;
|
||||
- compatibility requires supporting two behaviours with no sunset criterion;
|
||||
- a migration can lose data or cannot demonstrate restoration;
|
||||
- a runtime/config change cannot preserve last-known-good state;
|
||||
- a protocol change lacks an independent interoperability oracle;
|
||||
- a security rule exists only in a prompt;
|
||||
- a baseline failure touches the same surface;
|
||||
- concurrent work overlaps the files or semantics;
|
||||
- the required full gate cannot run or has an unexplained failure;
|
||||
- an adversarial finding survives.
|
||||
|
||||
Do not escalate discoverable facts or ordinary implementation choices. Bring
|
||||
the evidence, the smallest decision required, and the consequences of each
|
||||
option.
|
||||
|
||||
## Provenance and maintenance
|
||||
|
||||
Re-verify commands, gates, current defects, and incidents before updating this
|
||||
skill:
|
||||
|
||||
```sh
|
||||
sed -n '1,220p' Taskfile.yml
|
||||
sed -n '1,260p' CLAUDE.md
|
||||
find .gitea/workflows .github/workflows -maxdepth 1 -type f -print
|
||||
sed -n '1,140p' .gitea/workflows/deploy.yml
|
||||
sed -n '1,180p' .github/workflows/docs.yml
|
||||
sed -n '1,130p' docs/prds/architecture/safe-change-and-recovery.md
|
||||
sed -n '1,120p' docs/prds/architecture/package-review.md
|
||||
sed -n '300,350p' docs/prds/architecture/agent-system.md
|
||||
sed -n '255,280p' internal/store/store.go
|
||||
sed -n '270,305p' internal/nell/adapter.go
|
||||
go test ./internal/skillscript -count=1
|
||||
git log --all --format='%h %ad %s' --date=short --grep='FullStream\|MCP transport framing\|token_env\|container Docker network\|autofix\|Transition() ignores' -i
|
||||
git branch -a --contains a7f294e
|
||||
rg -n 'docs:|deadcode' Taskfile.yml
|
||||
```
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Archie Change Control"
|
||||
short_description: "Plan, gate, and accept Archie changes safely"
|
||||
default_prompt: "Use $archie-change-control to classify, plan, verify, review, and accept this archie-core change."
|
||||
@@ -0,0 +1,432 @@
|
||||
---
|
||||
name: archie-codebase-discovery
|
||||
description: "Trace Archie behavior and blast radius through Go source, types, state, persistence, transports, consumers, tests, configuration, production composition, and target architecture. Load before changing or planning a non-trivial feature, refactor, config field, interface, persistence path, workflow, channel, plugin, or agent execution path; also load to investigate duplicate behavior, hidden dead code, constructor bypasses, package dependencies, decoded-but-unwired configuration, or uncertainty about what a symbol actually affects."
|
||||
---
|
||||
|
||||
# Discover the Archie codebase
|
||||
|
||||
Use evidence from the current checkout to explain a behavior before changing it.
|
||||
Produce a trace that another engineer can reproduce. Do not stop at "tests pass"
|
||||
or "grep found one call."
|
||||
|
||||
Volatile tool facts below were verified on **2026-07-28**. Re-check them before
|
||||
depending on exact versions or subcommands.
|
||||
|
||||
## Scope and routing
|
||||
|
||||
This skill is read-only. Use it to establish what exists, who owns state, which
|
||||
paths are live, and what a proposed change would displace.
|
||||
|
||||
Do **not** use it as:
|
||||
|
||||
| Need | Load instead |
|
||||
|---|---|
|
||||
| Assign ownership, justify deletion, or record cleanup debt | `archie-technical-accountability` |
|
||||
| Design boundaries, packages, migrations, or a future architecture | `archie-architecture-planning-campaign` |
|
||||
| Collect runtime, coverage, complexity, latency, or production measurements | `archie-diagnostics-and-tooling` |
|
||||
| Turn a hypothesis into a controlled evidence campaign | `archie-research-methodology` |
|
||||
| Learn NellDB's API, document model, MVCC, HLC, or persistence semantics | `archie-nelldb` |
|
||||
| Implement or approve a behavior-changing patch | Route the resulting trace through `archie-change-control` |
|
||||
|
||||
Do not delete, move, or redesign code while running this skill. A discovery can
|
||||
recommend a next investigation, but an ownership or architecture decision needs
|
||||
the sibling skill named above.
|
||||
|
||||
## Define the evidence terms
|
||||
|
||||
- **Composition root:** executable code that selects concrete implementations
|
||||
and connects them. Archie's principal composition root is
|
||||
`cmd/archied/main.go`; the sandbox worker has its own root under
|
||||
`cmd/archie-agent/`.
|
||||
- **Production wiring:** a path selected by a shipped entrypoint under an actual
|
||||
config/mode branch. A constructor, decoder, or passing unit test is not wiring.
|
||||
- **State owner:** the component with authority to validate and persist a state
|
||||
transition, not every component that holds a copy.
|
||||
- **Target PRD:** an approved description under `docs/prds/` of where the system
|
||||
should go. It is not proof that current code works that way.
|
||||
- **Candidate:** a result from text or syntax search that still requires
|
||||
type-aware or composition-root confirmation.
|
||||
|
||||
## Establish a reproducible baseline
|
||||
|
||||
Run from the repository root:
|
||||
|
||||
```sh
|
||||
go version
|
||||
go env GOMOD GOWORK GOOS GOARCH
|
||||
gopls version
|
||||
golangci-lint version
|
||||
staticcheck -version
|
||||
rg --version | sed -n '1p'
|
||||
```
|
||||
|
||||
Record missing tools instead of silently substituting a weaker claim. As of
|
||||
2026-07-28 this checkout had Go 1.26.5, gopls 0.23.0,
|
||||
golangci-lint 2.12.2, staticcheck 2026.1 (v0.7.0), and `rg`. `go tool` listed
|
||||
no `callgraph` command. Do not write `go tool callgraph`; use
|
||||
`gopls call_hierarchy`.
|
||||
|
||||
Use writable caches when the host's default Go caches are read-only:
|
||||
|
||||
```sh
|
||||
export GOCACHE="${TMPDIR:-/tmp}/archie-discovery-gocache"
|
||||
export XDG_CACHE_HOME="${TMPDIR:-/tmp}/archie-discovery-xdg"
|
||||
export GOLANGCI_LINT_CACHE="${TMPDIR:-/tmp}/archie-discovery-lint"
|
||||
export GOTMPDIR="${TMPDIR:-/tmp}"
|
||||
export GOPROXY=off
|
||||
export GOFLAGS=-mod=readonly
|
||||
```
|
||||
|
||||
`GOPROXY=off` prevents discovery from fetching dependencies. If an uncached
|
||||
module is required, report that as an environment blocker; do not turn a
|
||||
read-only investigation into dependency mutation.
|
||||
|
||||
Inventory module boundaries before interpreting `./...`:
|
||||
|
||||
```sh
|
||||
find . \( -path './.git' -o -path './.references' -o -path './.claude/worktrees' -o -name node_modules \) -prune -o -name go.mod -print
|
||||
go list -m -f '{{.Path}} {{.GoVersion}}'
|
||||
go -C tools list -m -f '{{.Path}} {{.GoVersion}}'
|
||||
```
|
||||
|
||||
The root module and `tools/` are separate modules as of 2026-07-28. A root
|
||||
`go test ./...` or `go list ./...` does not validate `tools/`.
|
||||
|
||||
## Build the behavior trace
|
||||
|
||||
Write the question first:
|
||||
|
||||
```text
|
||||
Behavior:
|
||||
Observable input:
|
||||
Expected externally visible output:
|
||||
State that may change:
|
||||
Modes/configurations to compare:
|
||||
```
|
||||
|
||||
Then traverse every row in order. Mark a row `N/A` only with evidence.
|
||||
|
||||
| Step | Find | Required evidence |
|
||||
|---:|---|---|
|
||||
| 1 | Entrypoint | `main`, handler, poller, RPC subject, or tool registration that admits the input |
|
||||
| 2 | Construction | Constructor and every direct struct literal that can create the component |
|
||||
| 3 | Contract | Interface, wire type, command, event, or public method actually crossed |
|
||||
| 4 | Implementation | All type-valid implementations, then the one selected in each relevant mode |
|
||||
| 5 | State owner | The function that validates the transition and owns concurrency/transaction rules |
|
||||
| 6 | Persistence | Store adapter, schema/key/document, serialization, and reload/recovery path |
|
||||
| 7 | Event/transport | Publish/send and subscribe/receive sides, subject/framing, timeout, retry, and acknowledgement |
|
||||
| 8 | Consumer | Callers and downstream readers, including UI, channel, daemon, agent, and reconciliation paths |
|
||||
| 9 | Tests | Unit, integration, contract, architecture, and production-composition tests; identify absent layers |
|
||||
| 10 | Configuration | Decode, default, validation, normalization/copy, composition-root consumption, and deploy passthrough |
|
||||
| 11 | Target architecture | Current-to-target mapping in `docs/prds/`; label gaps instead of describing target text as current |
|
||||
|
||||
Start at these verified anchors:
|
||||
|
||||
| Concern | Current anchor |
|
||||
|---|---|
|
||||
| Resident daemon | `cmd/archied/main.go` → `run()` → `daemon.Daemon` |
|
||||
| Sandboxed worker | `cmd/archie-agent/main.go`, `cmd/archie-agent/taskrun.go` |
|
||||
| Task orchestration | `internal/daemon/daemon.go`, `internal/workflow/` |
|
||||
| Task contracts and SQLite | `internal/store/interface.go`, `internal/store/` |
|
||||
| Production task persistence | `internal/nell/adapter.go`; selected by `nell.OpenStore` in `cmd/archied/main.go` |
|
||||
| RPC split | `internal/{nats,taskrun,natsrpc,storerpc,forgerpc,worktreerpc}/` |
|
||||
| Chat and channels | `internal/gateway/`, `internal/channels/` |
|
||||
| Configuration | `internal/config/`, `config.example.toml`, `config.docker.toml` |
|
||||
| Production/deploy shape | `cmd/archied/main.go`, `docker-compose.yml`, `.gitea/workflows/deploy.yml` |
|
||||
| Target map | `docs/prds/01-project-management.md` and linked `docs/prds/architecture/*.md` |
|
||||
|
||||
Do not assume this table is complete after code moves. Re-find anchors with
|
||||
`go list` and `gopls`.
|
||||
|
||||
## Use syntax, type, and call evidence
|
||||
|
||||
### Map packages before reading files
|
||||
|
||||
List source and test files as the Go tool sees them:
|
||||
|
||||
```sh
|
||||
go list -f '{{.ImportPath}}|go={{join .GoFiles ","}}|tests={{join .TestGoFiles ","}}|imports={{join .Imports ","}}' ./internal/store
|
||||
go list -json ./internal/store
|
||||
```
|
||||
|
||||
Map internal dependency direction:
|
||||
|
||||
```sh
|
||||
.claude/skills/archie-codebase-discovery/scripts/package-edges.sh ./internal/...
|
||||
```
|
||||
|
||||
Treat imports as dependency evidence, not ownership proof. Compare the result
|
||||
with `docs/prds/architecture/dependencies-and-contracts.md` only after
|
||||
distinguishing current from target.
|
||||
|
||||
### Resolve symbols with gopls
|
||||
|
||||
Use a 1-indexed `file:line:column` position on the identifier:
|
||||
|
||||
```sh
|
||||
gopls symbols internal/store/interface.go
|
||||
gopls definition cmd/archied/main.go:154:18
|
||||
gopls references -d internal/store/interface.go:25:2
|
||||
gopls implementation internal/store/interface.go:16:6
|
||||
gopls call_hierarchy internal/store/interface.go:25:2
|
||||
```
|
||||
|
||||
Run all four queries together:
|
||||
|
||||
```sh
|
||||
.claude/skills/archie-codebase-discovery/scripts/trace-go-position.sh internal/store/interface.go:25:2
|
||||
```
|
||||
|
||||
Use `gopls implementation` on interfaces and interface methods. Use
|
||||
`gopls references -d` on struct fields, functions, constants, and types.
|
||||
`gopls call_hierarchy` exposes callers missed by a search for one textual call
|
||||
shape. Read the resolved bodies; tool output is an index, not the explanation.
|
||||
|
||||
Inspect exported contracts and available tests:
|
||||
|
||||
```sh
|
||||
go doc ./internal/store.TaskStore
|
||||
go test ./internal/store -list '.'
|
||||
rg -n '^func Test|^func Benchmark|^func Fuzz' internal/store
|
||||
```
|
||||
|
||||
`go test -list` compiles the package and lists matching top-level tests; it does
|
||||
not execute them.
|
||||
|
||||
### Generate AST candidates for construction
|
||||
|
||||
Find type declarations, direct composite literals, and functions returning a
|
||||
named type:
|
||||
|
||||
```sh
|
||||
.claude/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh Daemon .
|
||||
.claude/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh -tests Task .
|
||||
```
|
||||
|
||||
The helper parses Go ASTs; it does not infer the package identity of an
|
||||
unqualified name. Treat results as candidates, then confirm each with
|
||||
`gopls definition` or `gopls references`. Production-only output is the default;
|
||||
pass `-tests` to expose test-only construction.
|
||||
|
||||
## Run focused discovery recipes
|
||||
|
||||
### Find duplicate behavior paths
|
||||
|
||||
1. Run the configured duplicate-code detector:
|
||||
|
||||
```sh
|
||||
golangci-lint run --enable-only=dupl ./internal/...
|
||||
```
|
||||
|
||||
2. Search for the externally visible operation, status, subject, or log phrase:
|
||||
|
||||
```sh
|
||||
rg -n 'Transition\(|PublishTask\(|ClaimNext\(|StatusWaitingHuman' cmd internal
|
||||
```
|
||||
|
||||
3. Trace each candidate back to an entrypoint and forward to its state owner.
|
||||
4. Compare mode branches: in-process, subprocess, NATS/container,
|
||||
single-identity, and multi-identity where applicable.
|
||||
5. Report semantic duplicates even when the code is textually different.
|
||||
6. Do not call compatibility paths obsolete until production composition,
|
||||
deployed config, persistence compatibility, and target removal criteria agree.
|
||||
|
||||
`dupl` finds similar syntax, not two different implementations of one
|
||||
responsibility.
|
||||
|
||||
### Find unused-but-compiled code
|
||||
|
||||
Run the available unexported-code check:
|
||||
|
||||
```sh
|
||||
staticcheck -checks=U1000 ./internal/...
|
||||
```
|
||||
|
||||
For every suspect:
|
||||
|
||||
1. Run `gopls references -d` on the declaration.
|
||||
2. Search registration tables, `init`, reflection/Yaegi symbols, templates,
|
||||
JSON/TOML/YAML tags, RPC subjects, plugin manifests, and string dispatch.
|
||||
3. Check build tags and OS-specific files from `go list -json`.
|
||||
4. Search both executable composition roots.
|
||||
5. Separate production, test-only, compatibility, generated, and unreachable
|
||||
paths.
|
||||
|
||||
`U1000` does not prove exported code, reflection targets, wire names, or
|
||||
registrations are dead. Zero type references does not prove a string-addressed
|
||||
capability is dead. Route any deletion decision to
|
||||
`archie-technical-accountability`.
|
||||
|
||||
### Find interface implementations
|
||||
|
||||
1. Put the cursor position on the interface name and run
|
||||
`gopls implementation`.
|
||||
2. Put it on each important method and run `gopls implementation` again.
|
||||
3. Find compile-time assertions:
|
||||
|
||||
```sh
|
||||
rg -n 'var _ .*=' --glob '*.go' cmd internal
|
||||
```
|
||||
|
||||
4. Trace which implementation the composition root selects for each mode.
|
||||
5. Inspect test doubles separately; they establish substitutability only for
|
||||
exercised behavior.
|
||||
|
||||
An interface with three valid implementers still has only the implementation
|
||||
selected by `cmd/archied` on a given production branch.
|
||||
|
||||
### Find struct-field consumers
|
||||
|
||||
1. Run `gopls references -d` on the **field declaration**, not its common name.
|
||||
2. Trace assignments into the field and reads out of it separately.
|
||||
3. Follow copies and normalization methods such as `ForTask`/`ToConfig`.
|
||||
4. Check JSON/TOML/YAML tags and reflection separately; gopls cannot turn a
|
||||
decoder's string key into a field reference.
|
||||
5. Compare production and `_test.go` references.
|
||||
|
||||
A field read only while constructing an unused object is not an effective
|
||||
consumer.
|
||||
|
||||
### Detect constructor bypasses
|
||||
|
||||
1. Run `scan-go-type-syntax.sh Type .` without tests.
|
||||
2. Inspect every `literal` outside the owning package.
|
||||
3. Compare required validation/defaulting in constructors with direct literals.
|
||||
4. Repeat with `-tests`; record tests that exercise impossible production
|
||||
states.
|
||||
5. Use `gopls references` on the constructor and type to catch aliases and
|
||||
indirect uses the syntax helper cannot resolve.
|
||||
|
||||
Do not prohibit literals mechanically. Composition roots and test fixtures may
|
||||
need them, but bypassed invariants must be explicit.
|
||||
|
||||
### Prove package dependency direction
|
||||
|
||||
1. Run `package-edges.sh` for the smallest package pattern.
|
||||
2. Run `go list -deps -json <pattern>` when standard-library and third-party
|
||||
edges matter.
|
||||
3. Identify cycles prevented by interfaces, adapters, or RPC packages.
|
||||
4. Compare current edges with the target dependency rules.
|
||||
5. Treat a new shared package as an architecture decision, not a quick cycle fix.
|
||||
|
||||
### Find decoded-but-unused configuration
|
||||
|
||||
For each field, prove this chain:
|
||||
|
||||
```text
|
||||
file/key → decoder → default → validation → normalization/copy
|
||||
→ composition-root read → concrete component → observable behavior
|
||||
```
|
||||
|
||||
Use:
|
||||
|
||||
```sh
|
||||
rg -n 'toml:"|yaml:"|json:"' internal/config
|
||||
rg -n 'LoadOverlay|LoadDir|finalize|ForTask|ToConfig' internal/config cmd
|
||||
```
|
||||
|
||||
Then run `gopls references -d` on the exact field. Check
|
||||
`config.example.toml`, `config.docker.toml`, `docker-compose.yml`, config tests,
|
||||
and `cmd/archied/main.go`.
|
||||
|
||||
As of 2026-07-28 `cmd/archied` calls `config.LoadOverlay`; the separate
|
||||
`config.LoadDir` feature-file loader exists and has tests but was not selected
|
||||
by that production entrypoint. Re-verify this before using the fact. Decoder
|
||||
coverage proves accepted syntax, not deployed behavior.
|
||||
|
||||
### Prove production composition
|
||||
|
||||
1. Start at `cmd/archied/main.go:run`, not at the package under investigation.
|
||||
2. Record the config condition for each branch.
|
||||
3. Follow concrete construction into `daemon.Daemon` and gateway start
|
||||
functions.
|
||||
4. For container/NATS behavior, also trace `cmd/archie-agent`.
|
||||
5. Trace both sides of every RPC/transport and its error/timeout path.
|
||||
6. Read contract/architecture tests, including files matching
|
||||
`*contract_test.go` and `*architecture_test.go`.
|
||||
7. Confirm deploy inputs in Compose and CI; do not infer remote runtime state
|
||||
from repository files.
|
||||
|
||||
### Trace NellDB without guessing
|
||||
|
||||
Treat `internal/store` as the application contract and `internal/nell` as one
|
||||
adapter. Do not transfer SQLite behavior to NellDB by analogy.
|
||||
|
||||
```sh
|
||||
go doc github.com/samcharles93/NellDB.Store
|
||||
go doc github.com/samcharles93/NellDB/sdk.DocDB
|
||||
gopls implementation internal/store/interface.go:16:6
|
||||
rg -n 'sdk\.New|\.Get\(|\.Put\(|AllDocs|taskKey|docToTask|taskFields' internal/nell
|
||||
```
|
||||
|
||||
Trace `store.Task` field → `sdk.Doc` key → read/conversion → locking or MVCC
|
||||
around update/transition → reopen/recovery test. The adapter currently uses
|
||||
`tasks` and `events` collections and performs scans for several queries; verify
|
||||
those facts in `internal/nell/adapter.go` before relying on them. As of
|
||||
2026-07-28, `Adapter.Transition` neither locks nor checks its `from` argument;
|
||||
record that as observed current behavior, not a target promise. NellDB's
|
||||
`_id`/`_rev`, HLC, and conflict semantics come from the dependency API, while
|
||||
Archie's legal task transitions remain an Archie concern. Route deeper domain
|
||||
and persistence background to `archie-nelldb`.
|
||||
|
||||
## Reject false confidence
|
||||
|
||||
| Weak evidence | Why it fails | Required correction |
|
||||
|---|---|---|
|
||||
| One `rg` result | Misses interface dispatch, aliases, generated registration, reflection, and string-addressed protocols | Use gopls, AST candidates, package edges, and composition |
|
||||
| Green unit test | May construct a component directly and bypass actual config, lifecycle, or transport | Add or inspect composition/contract/integration evidence |
|
||||
| Fake client and fake server agree | Both sides can mirror the same wrong framing, subject, or state assumption | Compare an independent spec/implementation or real boundary fixture |
|
||||
| High coverage | Does not establish ownership, maintainability, deprecation, or correct mode selection | Trace authority and current production selection |
|
||||
| Constructor exists | Does not prove callers use it | Find struct literals and type-aware references |
|
||||
| Config field decodes | Does not prove the executable reads it | Complete the config-to-observable chain |
|
||||
| Target PRD says it | Describes required destination, not necessarily current code | Cite current implementation and label the gap |
|
||||
|
||||
## Produce the discovery handoff
|
||||
|
||||
End with these sections:
|
||||
|
||||
1. **Behavior trace:** one row per traversal step with `path:line`, symbol, and
|
||||
current responsibility.
|
||||
2. **Mode matrix:** mode/config branch → concrete implementation → state store
|
||||
→ transport → consumer.
|
||||
3. **State and authority:** owner, copies, persistence, transition rules, and
|
||||
recovery.
|
||||
4. **Blast radius:** callers, consumers, tests, config, deploy wiring, docs, and
|
||||
compatibility paths.
|
||||
5. **Duplication/deprecation ledger:** each candidate, evidence it is live or
|
||||
dead, replacement, and objective removal gate.
|
||||
6. **Current-to-target gap:** current fact, target PRD, migration implication;
|
||||
never blend the two.
|
||||
7. **Unknowns:** exact command attempted, output/blocker, and next evidence
|
||||
needed.
|
||||
|
||||
Do not propose implementation until the trace can answer:
|
||||
|
||||
- What entrypoint selects this path?
|
||||
- Which component owns the state and invariant?
|
||||
- Which parallel or older path would the feature replace or deprecate?
|
||||
- Which production modes and persisted data must remain compatible?
|
||||
- Which evidence would falsify the current understanding?
|
||||
|
||||
Short successes are acceptable, but complete one vertical trace rather than
|
||||
collecting many shallow search hits.
|
||||
|
||||
## Provenance and maintenance
|
||||
|
||||
Repository evidence verified on 2026-07-28:
|
||||
`cmd/archied/main.go`, `cmd/archie-agent/`, `internal/{config,daemon,nell,store,workflow,tools/mcp}/`,
|
||||
`Taskfile.yml`, `.golangci.yml`, `go.mod`, `tools/go.mod`,
|
||||
`docker-compose.yml`, `.gitea/workflows/deploy.yml`, `CLAUDE.md`,
|
||||
`ARCHITECTURE.md`, and `docs/prds/`.
|
||||
|
||||
Re-verify tools: `go version && gopls version && golangci-lint version && staticcheck -version && go tool`
|
||||
|
||||
Re-verify entrypoints: `rg -n '^func main|^func run' cmd/archied cmd/archie-agent`
|
||||
|
||||
Re-verify config selection: `rg -n 'config\.(Load|LoadOverlay|LoadDir)\(' cmd internal --glob '*.go'`
|
||||
|
||||
Re-verify modules: `find . \( -path './.git' -o -path './.references' -o -path './.claude/worktrees' -o -name node_modules \) -prune -o -name go.mod -print`
|
||||
|
||||
Re-verify production construction: `rg -n '&daemon\.Daemon\{|nell\.OpenStore|registerTaskRPCServers|startGateways' cmd/archied/main.go`
|
||||
|
||||
Re-verify contract tests: `find internal -type f \( -name '*contract_test.go' -o -name '*architecture_test.go' \) -print | sort`
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Archie Codebase Discovery"
|
||||
short_description: "Trace Archie behavior from entrypoint to production"
|
||||
default_prompt: "Use $archie-codebase-discovery to trace this behavior through production wiring before proposing a change."
|
||||
@@ -0,0 +1,36 @@
|
||||
#!/bin/sh
|
||||
set -eu
|
||||
|
||||
if [ "$#" -gt 1 ]; then
|
||||
printf '%s\n' "usage: $0 [go-package-pattern]" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
command -v go >/dev/null 2>&1 || {
|
||||
printf '%s\n' "error: go is required" >&2
|
||||
exit 127
|
||||
}
|
||||
|
||||
pattern=${1:-./...}
|
||||
cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"}
|
||||
mkdir -p "$cache_root/go-build" "$cache_root/tmp"
|
||||
|
||||
export GOCACHE="$cache_root/go-build"
|
||||
export GOTMPDIR="$cache_root/tmp"
|
||||
export GOPROXY=off
|
||||
export GOFLAGS=-mod=readonly
|
||||
|
||||
module_path=$(go list -m -f '{{.Path}}')
|
||||
|
||||
go list -f '{{.ImportPath}}{{range .Imports}}{{printf "\t%s" .}}{{end}}' "$pattern" |
|
||||
awk -F ' ' -v module="$module_path" '
|
||||
{
|
||||
from = $1
|
||||
for (i = 2; i <= NF; i++) {
|
||||
if ($i == module || index($i, module "/") == 1) {
|
||||
printf "%s -> %s\n", from, $i
|
||||
}
|
||||
}
|
||||
}
|
||||
' |
|
||||
LC_ALL=C sort -u
|
||||
@@ -0,0 +1,176 @@
|
||||
// Command scan-go-type-syntax reports syntax-level construction candidates for
|
||||
// a named Go type. It deliberately uses only the standard library and never
|
||||
// writes to the inspected tree.
|
||||
package main
|
||||
|
||||
import (
|
||||
"bufio"
|
||||
"flag"
|
||||
"fmt"
|
||||
"go/ast"
|
||||
"go/parser"
|
||||
"go/token"
|
||||
"io/fs"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"sort"
|
||||
"strings"
|
||||
)
|
||||
|
||||
type finding struct {
|
||||
path string
|
||||
line int
|
||||
column int
|
||||
kind string
|
||||
detail string
|
||||
}
|
||||
|
||||
func main() {
|
||||
includeTests := flag.Bool("tests", false, "include *_test.go files")
|
||||
flag.Usage = func() {
|
||||
fmt.Fprintf(flag.CommandLine.Output(), "usage: %s [-tests] TypeName [root]\n", os.Args[0])
|
||||
flag.PrintDefaults()
|
||||
}
|
||||
flag.Parse()
|
||||
if flag.NArg() < 1 || flag.NArg() > 2 {
|
||||
flag.Usage()
|
||||
os.Exit(2)
|
||||
}
|
||||
|
||||
typeName := flag.Arg(0)
|
||||
root := "."
|
||||
if flag.NArg() == 2 {
|
||||
root = flag.Arg(1)
|
||||
}
|
||||
if !token.IsIdentifier(typeName) {
|
||||
fmt.Fprintf(os.Stderr, "error: %q is not a Go identifier\n", typeName)
|
||||
os.Exit(2)
|
||||
}
|
||||
|
||||
results, err := scan(root, typeName, *includeTests)
|
||||
if err != nil {
|
||||
fmt.Fprintf(os.Stderr, "error: %v\n", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
|
||||
out := bufio.NewWriter(os.Stdout)
|
||||
defer out.Flush()
|
||||
fmt.Fprintln(out, "kind\tlocation\tdetail")
|
||||
for _, result := range results {
|
||||
fmt.Fprintf(out, "%s\t%s:%d:%d\t%s\n",
|
||||
result.kind, result.path, result.line, result.column, result.detail)
|
||||
}
|
||||
}
|
||||
|
||||
func scan(root, typeName string, includeTests bool) ([]finding, error) {
|
||||
fset := token.NewFileSet()
|
||||
var results []finding
|
||||
|
||||
err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
|
||||
if walkErr != nil {
|
||||
return walkErr
|
||||
}
|
||||
if entry.IsDir() {
|
||||
if path == root {
|
||||
return nil
|
||||
}
|
||||
name := entry.Name()
|
||||
if strings.HasPrefix(name, ".") || name == "node_modules" ||
|
||||
name == "vendor" || name == "bin" {
|
||||
return filepath.SkipDir
|
||||
}
|
||||
return nil
|
||||
}
|
||||
if filepath.Ext(path) != ".go" {
|
||||
return nil
|
||||
}
|
||||
if !includeTests && strings.HasSuffix(path, "_test.go") {
|
||||
return nil
|
||||
}
|
||||
|
||||
file, err := parser.ParseFile(fset, path, nil, 0)
|
||||
if err != nil {
|
||||
return fmt.Errorf("parse %s: %w", path, err)
|
||||
}
|
||||
|
||||
ast.Inspect(file, func(node ast.Node) bool {
|
||||
switch node := node.(type) {
|
||||
case *ast.TypeSpec:
|
||||
if node.Name.Name == typeName {
|
||||
results = appendFinding(results, fset, node.Name.Pos(),
|
||||
path, "declaration", "type "+node.Name.Name)
|
||||
}
|
||||
case *ast.CompositeLit:
|
||||
if matchesType(node.Type, typeName) {
|
||||
results = appendFinding(results, fset, node.Type.Pos(),
|
||||
path, "literal", "direct composite literal of "+typeName)
|
||||
}
|
||||
case *ast.FuncDecl:
|
||||
if returnsType(node.Type.Results, typeName) {
|
||||
results = appendFinding(results, fset, node.Name.Pos(),
|
||||
path, "returns-type", "func "+node.Name.Name)
|
||||
}
|
||||
}
|
||||
return true
|
||||
})
|
||||
return nil
|
||||
})
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
sort.Slice(results, func(i, j int) bool {
|
||||
left, right := results[i], results[j]
|
||||
if left.path != right.path {
|
||||
return left.path < right.path
|
||||
}
|
||||
if left.line != right.line {
|
||||
return left.line < right.line
|
||||
}
|
||||
if left.column != right.column {
|
||||
return left.column < right.column
|
||||
}
|
||||
return left.kind < right.kind
|
||||
})
|
||||
return results, nil
|
||||
}
|
||||
|
||||
func appendFinding(results []finding, fset *token.FileSet, pos token.Pos, path, kind, detail string) []finding {
|
||||
position := fset.Position(pos)
|
||||
return append(results, finding{
|
||||
path: filepath.ToSlash(path),
|
||||
line: position.Line,
|
||||
column: position.Column,
|
||||
kind: kind,
|
||||
detail: detail,
|
||||
})
|
||||
}
|
||||
|
||||
func returnsType(fields *ast.FieldList, typeName string) bool {
|
||||
if fields == nil {
|
||||
return false
|
||||
}
|
||||
for _, field := range fields.List {
|
||||
if matchesType(field.Type, typeName) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func matchesType(expr ast.Expr, typeName string) bool {
|
||||
switch expr := expr.(type) {
|
||||
case *ast.Ident:
|
||||
return expr.Name == typeName
|
||||
case *ast.SelectorExpr:
|
||||
return expr.Sel.Name == typeName
|
||||
case *ast.StarExpr:
|
||||
return matchesType(expr.X, typeName)
|
||||
case *ast.IndexExpr:
|
||||
return matchesType(expr.X, typeName)
|
||||
case *ast.IndexListExpr:
|
||||
return matchesType(expr.X, typeName)
|
||||
default:
|
||||
return false
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,13 @@
|
||||
#!/bin/sh
|
||||
set -eu
|
||||
|
||||
script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
|
||||
cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"}
|
||||
mkdir -p "$cache_root/go-build" "$cache_root/tmp"
|
||||
|
||||
export GOCACHE="$cache_root/go-build"
|
||||
export GOTMPDIR="$cache_root/tmp"
|
||||
export GOPROXY=off
|
||||
export GOFLAGS=-mod=readonly
|
||||
|
||||
exec go run "$script_dir/scan-go-type-syntax.go" "$@"
|
||||
@@ -0,0 +1,61 @@
|
||||
#!/bin/sh
|
||||
set -u
|
||||
|
||||
usage() {
|
||||
printf '%s\n' "usage: $0 file.go:line:column" >&2
|
||||
exit 2
|
||||
}
|
||||
|
||||
[ "$#" -eq 1 ] || usage
|
||||
position=$1
|
||||
|
||||
command -v go >/dev/null 2>&1 || {
|
||||
printf '%s\n' "error: go is required" >&2
|
||||
exit 127
|
||||
}
|
||||
command -v gopls >/dev/null 2>&1 || {
|
||||
printf '%s\n' "error: gopls is required" >&2
|
||||
exit 127
|
||||
}
|
||||
|
||||
case "$position" in
|
||||
*.go:[1-9]*:[1-9]*) ;;
|
||||
*) usage ;;
|
||||
esac
|
||||
|
||||
cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"}
|
||||
mkdir -p "$cache_root/go-build" "$cache_root/xdg" "$cache_root/tmp" || exit 1
|
||||
|
||||
export GOCACHE="$cache_root/go-build"
|
||||
export XDG_CACHE_HOME="$cache_root/xdg"
|
||||
export GOTMPDIR="$cache_root/tmp"
|
||||
export GOPROXY=off
|
||||
export GOFLAGS=-mod=readonly
|
||||
|
||||
gomod=$(go env GOMOD)
|
||||
if [ "$gomod" = "/dev/null" ] || [ -z "$gomod" ]; then
|
||||
printf '%s\n' "error: run from inside a Go module" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
run_query() {
|
||||
label=$1
|
||||
shift
|
||||
printf '\n== %s ==\n' "$label"
|
||||
if output=$(gopls "$@" 2>&1); then
|
||||
printf '%s\n' "$output"
|
||||
return 0
|
||||
else
|
||||
printf '%s\n' "$output"
|
||||
printf '%s\n' "(query is not applicable at this position, or failed)"
|
||||
return 1
|
||||
fi
|
||||
}
|
||||
|
||||
successful=0
|
||||
run_query "definition" definition "$position" && successful=$((successful + 1))
|
||||
run_query "references (including declaration)" references -d "$position" && successful=$((successful + 1))
|
||||
run_query "implementations" implementation "$position" && successful=$((successful + 1))
|
||||
run_query "call hierarchy" call_hierarchy "$position" && successful=$((successful + 1))
|
||||
|
||||
[ "$successful" -gt 0 ]
|
||||
@@ -0,0 +1,343 @@
|
||||
---
|
||||
name: archie-config-and-flags
|
||||
description: Trace, add, rename, deprecate, or debug Archie configuration and command-line flags from external input through defaults, validation, overlays, environment and secret handling, worker snapshots, deployment passthrough, and the production consumer. Use for internal/config, config.example.toml, config.docker.toml, docker-compose.yml, archied or archie-agent flags, multi-identity settings, mode-parity questions, and reports of a setting that parses but has no effect.
|
||||
---
|
||||
|
||||
# Trace Archie configuration and flags
|
||||
|
||||
Treat configuration as a dataflow, not as a struct inventory. Prove every
|
||||
claimed setting has an input, normalization path, composition seam, and runtime
|
||||
consumer.
|
||||
|
||||
Current evidence date: **2026-07-28**. Re-verify volatile defaults, deployment
|
||||
wiring, and status labels before changing behavior.
|
||||
|
||||
## Route work to the right skill
|
||||
|
||||
Do not use this skill to:
|
||||
|
||||
- choose a new architecture or owner; use
|
||||
`archie-architecture-planning-campaign` and `archie-architecture-contract`;
|
||||
- discover an unknown feature's whole blast radius; use
|
||||
`archie-codebase-discovery`, then return here for its configuration seam;
|
||||
- inspect live hosts, rotate secrets, deploy, or recover an instance; use
|
||||
`archie-run-and-operate`;
|
||||
- define NellDB settings or persistence semantics; use `archie-nelldb`;
|
||||
- approve a behavioral change or claim acceptance; use
|
||||
`archie-change-control` and `archie-validation-and-qa`.
|
||||
|
||||
Use these status terms exactly:
|
||||
|
||||
| Status | Meaning |
|
||||
| --- | --- |
|
||||
| **production-wired** | A real entrypoint decodes or accepts the value and a runtime consumer uses it. |
|
||||
| **partially-wired** | Some modes, scopes, or fields consume it, but parity is incomplete. |
|
||||
| **test/library-only** | An API and tests exist, but no current binary selects it. |
|
||||
| **decoded-but-unwired** | Decoding/defaulting succeeds, but no production consumer uses the effective value. |
|
||||
| **experimental/candidate** | Code exists, but operational correctness or the public contract is not established. |
|
||||
| **external-production-unknown** | The repository does not contain the deployed effective value. |
|
||||
|
||||
Never upgrade a status merely because decoding tests pass.
|
||||
|
||||
## Trace one setting before editing it
|
||||
|
||||
Perform this sequence:
|
||||
|
||||
1. Find every external spelling, Go field, flag, environment name, example, and
|
||||
deployment reference.
|
||||
2. Identify the selected loader or flag set. Do not assume every exported loader
|
||||
is used.
|
||||
3. Read `finalize` and any consumer-side defaults. Record zero, empty, negative,
|
||||
and sentinel semantics separately.
|
||||
4. Follow copies across `ForTask`, `ToConfig`, NATS messages, subprocess
|
||||
environment selection, container environment construction, and identity
|
||||
overlays.
|
||||
5. Find the production composition site and final behavior-changing read.
|
||||
6. Find a test for decoding, defaulting, invalid input, production composition,
|
||||
and mode parity. Record missing layers as gaps.
|
||||
7. Check `config.example.toml`, `config.docker.toml`, `docker-compose.yml`, and
|
||||
deployment environment passthrough.
|
||||
8. Assign one status from the table above and cite the exact evidence paths in
|
||||
the change record.
|
||||
|
||||
Start with:
|
||||
|
||||
```bash
|
||||
rg -n 'LoadOverlay|LoadDir|ForTask|ToConfig|flag\.' \
|
||||
internal/config cmd/archied cmd/archie-agent
|
||||
rg -n 'FIELD_NAME|external_key|ENV_NAME' \
|
||||
--glob '*.go' --glob '*.toml' --glob '*.yml' --glob '*.yaml' .
|
||||
```
|
||||
|
||||
Do not search only `internal/config`: a field with no reads outside that package
|
||||
is usually not production-wired.
|
||||
|
||||
## Select the real input path
|
||||
|
||||
| Input path | Current behavior | Status |
|
||||
| --- | --- | --- |
|
||||
| `archied -config PATH` | Defaults to `$XDG_CONFIG_HOME/archie/config.toml`, or `$HOME/.config/archie/config.toml`; `cmd/archied/main.go` calls `config.LoadOverlay`. | production-wired |
|
||||
| `archied -config-overlay PATH` | Decodes base TOML, then overlay TOML into the same `Config`, then calls `finalize` once. Omitted overlay fields retain base values. | production-wired |
|
||||
| `config.Load(PATH)` | Loads one TOML and finalizes it; no current binary calls it directly. | test/library-only |
|
||||
| `config.LoadDir(base, overlay)` | Supports main YAML/TOML plus feature YAML and `conf.d`; no current entrypoint calls it. | test/library-only |
|
||||
| `config.example.toml` | Load-tested example, not a deployed configuration. | test/library-only |
|
||||
| `config.docker.toml` | Repository overlay mounted by Compose; it still depends on the host base config. | production-wired |
|
||||
| Host base config and environment on `carina` | Mounted from `${HOME}/.config/archie/config.toml`; contents are absent from this repository. | external-production-unknown |
|
||||
|
||||
`LoadDir` recognizes `gateway`, `tools`, `memory`, `models`, and `identities`
|
||||
feature YAML. It rejects unknown `config.<feature>.yaml` names, but accepts
|
||||
unknown `conf.d/*.yaml` into `Config.Extra`. YAML takes precedence over TOML
|
||||
when both are present in one directory. None of this changes the current daemon
|
||||
path: `archied` selects TOML `LoadOverlay`, including during Telegram reload.
|
||||
|
||||
Both TOML and YAML decoding are non-strict at the field level: the loaders do
|
||||
not reject every unknown key. Add explicit compatibility and typo tests; never
|
||||
use “the file loaded” as evidence that a key took effect.
|
||||
|
||||
## Inventory CLI flags
|
||||
|
||||
### Public binaries
|
||||
|
||||
| Binary | Flag | Default and effect |
|
||||
| --- | --- | --- |
|
||||
| `archied` | `-config PATH` | Computed config path described above. |
|
||||
| `archied` | `-config-overlay PATH` | Empty; overlay only fields explicitly present in the second TOML. |
|
||||
| `archied` | `-once` | `false`; run one poll/process cycle and exit. |
|
||||
| `archied` | `-requeue ID` | `0`; values greater than zero requeue one parked/waiting task, then exit unless `-once` is also set. |
|
||||
| `archie-agent` | `-nats-url URL` | Empty; takes precedence over `NATS_URL`. Missing both is fatal. |
|
||||
| `archie-agent` | `-consumer NAME` | `archie-agent`; names the JetStream durable consumer. |
|
||||
| both | `-quickchecks N` | Incidental flag registered by `github.com/traefik/yaegi/stdlib` importing `testing/quick`; default `100`. Archie has no intentional consumer. Treat it as an unowned candidate defect, not supported configuration. |
|
||||
|
||||
The standalone agent always reads its token from `NATS_TOKEN`; there is no
|
||||
token flag.
|
||||
|
||||
### Internal codesearch helper
|
||||
|
||||
`archied workspace-codesearch` bypasses daemon configuration before normal flag
|
||||
parsing. It is an internal child-process contract:
|
||||
|
||||
| Subcommand | Required flags | Optional flags |
|
||||
| --- | --- | --- |
|
||||
| `build` | `--root`, `--index` | none |
|
||||
| `candidates` | `--index`, `--pattern` | `--literal`, `--case-sensitive` |
|
||||
|
||||
Do not expose these helper flags as daemon settings without an architecture and
|
||||
compatibility decision.
|
||||
|
||||
## Read the current wiring matrix
|
||||
|
||||
### Root daemon and capability settings
|
||||
|
||||
| Keys | Default, validation, and consumer | Status |
|
||||
| --- | --- | --- |
|
||||
| `work_dir`, `db_path` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; `work_dir` drives worktrees, memory, derived index paths, and state files, while `db_path` opens NellDB. Literal `~` in an explicit value is not expanded by the loader. | production-wired |
|
||||
| `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. The `skill_activate` catalog still reads `work_dir`, and a container rebuilds from its mounted worktree. | partially-wired |
|
||||
| `plugin_dir` | Empty disables daemon plugin loading; a configured directory is loaded in `cmd/archied`. | production-wired |
|
||||
| `poll_interval` | Defaults to `60s`; root poll loop uses it and identities may override only their interval. | production-wired |
|
||||
| `label` | No default or validation; used for `dispatch.trigger = "label"` or `"either"`. Empty therefore remains an accepted but likely ineffective pickup label. | production-wired |
|
||||
| `max_retries` | Defaults to `3`; a repository value greater than zero overrides it. | production-wired |
|
||||
| `bot_user`, `bot_email` | Single-identity mode requires `bot_user`; email defaults by forge type. `bot_user` drives assignment polling, store actor, sessions, and release state; both values form the Git signature. | production-wired |
|
||||
| `forge.type`, `host`, `token` | Type defaults `github`, host defaults `https://github.com`; only `github` and `gitea` validate. The root token resolves before daemon construction and must be non-empty. | production-wired |
|
||||
| `dispatch.trigger` | Defaults `assignee`; validates `assignee`, `label`, or `either`. | production-wired |
|
||||
| `dispatch.ack_reaction` | Defaults `eyes`; case-insensitive `off` normalizes to empty. | production-wired |
|
||||
| `dispatch.labels.*` | Missing `queued`, `working`, `waiting`, `pr`, `parked`, or `dead` keys default independently to `agent:*`. Used for forge state presentation. | production-wired |
|
||||
| `models.<role>` | Workflow stages read a requested role then fall back to `builder`; triage reply judging falls back from `triage` to `planner`. References are not validated at load time. | production-wired |
|
||||
| `providers.<name>.class`, `api_key_env`, `base_url` | Builds the ai-sdk catalog. `base_url` rejects parse errors, userinfo, query, and fragment; class/key/model compatibility is deferred. | production-wired |
|
||||
| `agent.mode` | Defaults to `nats` when containers are enabled, otherwise `inprocess`; validates `inprocess`, `subprocess`, or `nats`. Subprocess caveat follows this table. | production-wired |
|
||||
| `agent.command`, `agent.env` | Command defaults `archie-agent`; environment entries must be nonblank names without `=` and apply only to subprocess mode. | partially-wired |
|
||||
| `budgets.max_steps`, `max_tokens`, `wall_clock`, `gate_max_failures` | No loader defaults; `Budgets` documents zero as disabling the limit. Workflow agent requests and gates consume them. | production-wired |
|
||||
| `diff_cap_lines` | Zero is replaced by `400` in `finalize`; `StageDiffCap` treats values `<= 0` as disabled. Thus TOML zero cannot disable the cap, while an unvalidated negative value does. Do not use negative as a hidden operator contract. | production-wired |
|
||||
| `web.listen` | Empty becomes `127.0.0.1:8484`; literal `off` disables. The dashboard has no authentication. | production-wired |
|
||||
| `notify.webhook` | Empty disables; feasibility workflow POSTs human-decision notifications when set. Included in worker `TaskConfig`. | production-wired |
|
||||
| `nats.url`, `token_env` | Empty URL keeps the SQLite path. A configured token variable must be non-empty. NATS enables distributed queue/RPC composition. | production-wired |
|
||||
| `containers.*` | See the dedicated table below. Some values also control scheduling/storage outside the pool, demonstrating current cross-concern ownership. | production-wired |
|
||||
| `chat.*` | See the channel table below. Empty channel addresses/token names disable those channels. | production-wired |
|
||||
| `memory.provider`, `provider_config`, `session_ttl` | Feature YAML decodes and tests these fields, but `cmd/archied` always starts the built-in file provider at `work_dir/memory` and never reads them. | decoded-but-unwired |
|
||||
| `tools.mcp_servers` | `cmd/archied` registers daemon-side MCP providers. Empty transport becomes `stdio`; only `stdio` is accepted; name and command are required. Invalid entries warn and skip. `url` is decoded but unused. Worker parity is not established. | partially-wired |
|
||||
| `tools.tool_policy.*` | Feature YAML decodes `max_result_chars` and `parallel_execution`; no production read exists. | decoded-but-unwired |
|
||||
| `indexing.index_dir`, `indexing.db_path` | `finalize` derives paths under `work_dir`; no entrypoint constructs `internal/indexing.Manager` from them. The internal helper alone does not complete wiring. | decoded-but-unwired |
|
||||
| `extra` / unknown `conf.d` values | Test/library-only `LoadDir` stores untyped data, but core production has no consumer and the approved target forbids a core catch-all. | decoded-but-unwired |
|
||||
|
||||
The default `agent.command = "archie-agent"` is not verified subprocess
|
||||
operation. `SubprocessRunner` expects one JSON invocation on stdin and one JSON
|
||||
response on stdout; `cmd/archie-agent` is a long-running NATS worker that parses
|
||||
NATS flags. Treat subprocess mode with that command as an open incompatibility
|
||||
until an end-to-end test proves otherwise.
|
||||
|
||||
### Repository settings
|
||||
|
||||
| Keys | Effective behavior | Status |
|
||||
| --- | --- | --- |
|
||||
| `owner`, `name` | Required for every declared repo. A single-identity config with zero repos currently loads but polls nothing. | production-wired |
|
||||
| `base` | `BaseBranch()` maps empty to `main`, but `daemon.process` pre-clones with raw `repo.Base`. Set it explicitly: the advertised empty default is not honored on that production path. | partially-wired |
|
||||
| `gate` | Argv arrays run in order. Empty entries are skipped. TDD inverts the last non-empty command as the repro test by convention. No loader validates command meaning. | production-wired |
|
||||
| `protect` | Path suffixes are enforced by the agent runner; this is not a prompt-only rule. | production-wired |
|
||||
| `ecosystem`, `preflight`, `test_glob` | Resolved preflight/test-glob logic treats empty ecosystem as Go. Container storage receives the raw ecosystem, so empty gets no Go cache mounts. Go/Python/Node/Rust have defaults; `custom` or an unknown name yields none. Explicit test globs validate with `filepath.Match`. | partially-wired |
|
||||
| `persistent_storage` | Controls Docker-backed per-repo volume setup; it has no equivalent effect without container storage. | partially-wired |
|
||||
| `max_retries` | Values greater than zero override global retry count; zero or negative falls back to global. | production-wired |
|
||||
| `allow_concurrent` | Root repo entries affect the dispatcher. `allowConcurrentFor` does not inspect identity repo lists. | partially-wired |
|
||||
|
||||
### Container settings
|
||||
|
||||
| Key | Effective behavior |
|
||||
| --- | --- |
|
||||
| `enabled` | Requires non-empty `image`, `agent.mode = "nats"`, and non-empty `nats.url`. |
|
||||
| `image` | Required only when enabled. |
|
||||
| `max_concurrency` | Zero means no limit; used by the general task dispatcher and again by the container pool. |
|
||||
| `max_uptime` | Defaults to `60m` only when enabled; caps a container lifetime. |
|
||||
| `volume_ttl` | Defaults to `72h` only when enabled; negative is rejected; governs persistent-volume cleanup. |
|
||||
| `pull_policy` | Defaults to `missing` when enabled. Pool code recognizes `missing` and `always`; other strings are not rejected and silently skip pre-pull. |
|
||||
| `network` | Empty uses best-effort self-network detection. The repository overlay pins `archie-core_default`. |
|
||||
|
||||
### Channel settings
|
||||
|
||||
| Keys | Effective behavior |
|
||||
| --- | --- |
|
||||
| `chat.models` | Optional interactive catalog; empty falls back to distinct top-level workflow model references. |
|
||||
| `chat.telegram.token_env` | Empty disables Telegram; non-empty names an environment variable and an empty value is fatal. |
|
||||
| `chat.telegram.allowed_user_ids` | Empty denies every sender; IDs match Telegram sender IDs, not chat IDs. |
|
||||
| `chat.telegram.update_check_command`, `update_install_command` | Argv arrays; check enables update status, and install additionally enables approved installation. |
|
||||
| `chat.email.listen_addr`, `relay_addr` | Empty listen disables SMTP; relay configures outbound replies. |
|
||||
| `chat.webhook_addr` | Empty disables; malformed host/port input falls back inside `parseListenAddr` rather than failing config validation. |
|
||||
|
||||
Telegram `/restart` re-runs the same TOML overlay load, then replaces only the
|
||||
gateway token and allowed-user list. Every other file setting is startup-only
|
||||
in current composition. Active chat model/provider and persona selection are
|
||||
runtime state, not configuration-file reload.
|
||||
|
||||
## Treat multi-identity as partially wired
|
||||
|
||||
`finalize` requires each identity's `name`, `bot_user`, non-empty repos, forge
|
||||
type, and `SecretRef` token. It validates repository identity and test globs,
|
||||
and `cmd/archied` builds an identity forge client and worktree manager.
|
||||
|
||||
Do not infer complete isolation:
|
||||
|
||||
- `cmd/archied` still resolves and constructs the root forge client before all
|
||||
identity runners, so a config accepted without root fields can still fail in
|
||||
production composition.
|
||||
- Identity `name`, forge, repos, poll interval, bot user, and bot email have
|
||||
some production reads. Identity bot email is not defaulted despite its
|
||||
comment promising a fallback.
|
||||
- Identity `models`, `providers`, `dispatch`, `budgets`, `notify`, and
|
||||
`diff_cap_lines` decode but workflows still receive root `Config`.
|
||||
- Identity polling reads root `dispatch`, `label`, and `bot_user`.
|
||||
- Container task snapshots and provider maps come from root config; task RPC
|
||||
servers are root-forge/root-worktree; container identity isolation is
|
||||
explicitly incomplete in `internal/daemon/daemon.go`.
|
||||
- Root-only concurrency lookup ignores identity repo `allow_concurrent`.
|
||||
|
||||
Classify multi-identity changes field by field. Never label the aggregate
|
||||
`IdentityConfig` production-wired.
|
||||
|
||||
## Preserve worker and secret boundaries
|
||||
|
||||
`Config.ForTask` creates a detached root snapshot containing only models,
|
||||
budgets, dispatch, diff cap, notification, and forge host. `TaskConfig.ToConfig`
|
||||
reconstructs only those fields. Provider descriptions travel separately in the
|
||||
task-run request; forge tokens, provider values, NATS credential references,
|
||||
repos, and infrastructure settings do not enter `TaskConfig`.
|
||||
|
||||
At the top-level `[forge]`, prefer
|
||||
`token = {engine = "env", key = "NAME"}`. Legacy `token_env = "NAME"` is
|
||||
converted only when the structured reference is empty; the structured
|
||||
reference wins when both appear. This compatibility rule exists because an
|
||||
earlier migration silently dropped deployed `token_env` values and crash-looped
|
||||
the daemon. `finalize` does not apply that conversion inside each identity:
|
||||
identity forges require an explicit structured `token`.
|
||||
|
||||
Use this environment matrix:
|
||||
|
||||
| Source | Archied | Subprocess | Agent container / standalone worker |
|
||||
| --- | --- | --- | --- |
|
||||
| Forge `token = {engine="env", key="X"}` | Resolves `X`; empty is fatal. | Not forwarded unless explicitly abused through `agent.env`. | Not forwarded; forge operations proxy to daemon. |
|
||||
| Provider `api_key_env = "X"` | Runtime reads `X`. | Automatically allowlists the selected provider's `X`. | Daemon forwards each present provider variable under its original name. |
|
||||
| `nats.token_env = "X"` | Reads `X`; empty is fatal when configured. | Not an agent subprocess setting. | Daemon maps its value to fixed `NATS_TOKEN`; worker also reads `NATS_URL`. |
|
||||
| Telegram `token_env = "X"` | Reads `X`. | Not forwarded. | Not forwarded. |
|
||||
| `agent.env = ["X"]` | Names are validated. | Copies present `X` from daemon environment. | Not used by container construction. |
|
||||
|
||||
`cmd/archied` creates `secret.NewRegistry`, which registers only the `env`
|
||||
engine, and does not call `Registry.LoadDir`. Although plugin loading APIs and
|
||||
comments describe custom secret engines, non-env `SecretRef` values are not
|
||||
production-wired at token-resolution time.
|
||||
|
||||
Compose passes only `ARCHIE_GITEA_TOKEN`,
|
||||
`ARCHIE_GITEA_TOKEN_ARCHIE`, `HEYARCHIE_TELEGRAM_BOT_TOKEN`, and
|
||||
`DEEPSEEK_API_KEY` into `archied`. A config reference to any other environment
|
||||
name requires an explicit deployment passthrough change. The live base config
|
||||
is external, so do not assert which of these names it uses.
|
||||
|
||||
## Add, rename, or remove an axis
|
||||
|
||||
Use this checklist:
|
||||
|
||||
- [ ] Classify the value as invariant, runtime setting, policy, derived value,
|
||||
or runtime state.
|
||||
- [ ] Name one target capability owner and its scope: installation, identity,
|
||||
repository, workflow, channel, or plugin instance.
|
||||
- [ ] Prefer capability-owned settings. If a temporary `internal/config` field
|
||||
is unavoidable, record its target owner and deletion gate.
|
||||
- [ ] Add a failing decoder test for the production TOML path.
|
||||
- [ ] Add failing tests for default, explicit value, zero/empty/negative input,
|
||||
invalid syntax, semantic combination, and overlay inheritance.
|
||||
- [ ] Add a production-composition test that observes the final consumer; a
|
||||
struct equality test is insufficient.
|
||||
- [ ] Test single identity, multiple identities, and every affected execution
|
||||
mode separately.
|
||||
- [ ] Update `ForTask`/`ToConfig` only when the worker needs the value; prove
|
||||
maps are detached and secret values/references are absent.
|
||||
- [ ] Trace in-process, subprocess allowlisting, NATS payload, container
|
||||
environment, and RPC ownership. Fence unsupported modes explicitly.
|
||||
- [ ] Update `config.example.toml`, `config.docker.toml`, Compose environment
|
||||
passthrough, and generated/reference docs only where applicable.
|
||||
- [ ] For a rename, decode old and new spellings at the loader boundary, define
|
||||
precedence, and test old-only, new-only, and both. The `forge.token_env`
|
||||
crash-loop regression is the minimum compatibility standard.
|
||||
- [ ] For removal, prove no production consumer, external spelling, overlay,
|
||||
worker copy, deploy reference, or supported old config remains. Define a
|
||||
dated deprecation and deletion gate; do not leave a permanent alias.
|
||||
- [ ] Route behavior-changing acceptance through change control and validation.
|
||||
|
||||
Do not add a field that merely parses. Do not add arbitrary plugin fields to the
|
||||
global struct. Do not expose secret values in config dumps, logs, task payloads,
|
||||
or review evidence.
|
||||
|
||||
## Follow the approved target, not the current sprawl
|
||||
|
||||
Current code puts infrastructure paths, domain policy, channel settings,
|
||||
secrets, execution settings, repository associations, and extension data in one
|
||||
mutable `config.Config`. It passes that aggregate into `daemon.Daemon`,
|
||||
`workflow.TaskContext`, and a second worker DTO. Treat this as a current
|
||||
load-bearing weakness, not a pattern to copy.
|
||||
|
||||
`docs/prds/architecture/configuration.md` is approved as of 2026-07-28:
|
||||
|
||||
- move file/env/secret/overlay loading to a private
|
||||
`internal/infrastructure/configuration` input boundary;
|
||||
- translate inputs in `internal/app`;
|
||||
- give each domain/plugin typed owned settings and validation;
|
||||
- dissolve `internal/config` rather than rename the global model;
|
||||
- split `Repo` and `IdentityConfig` by actual capability ownership;
|
||||
- stage, validate, health-check, promote, audit, and roll back configuration
|
||||
candidates without replacing last-known-good settings.
|
||||
|
||||
Use `archie-architecture-planning-campaign` before moving ownership, and use
|
||||
`archie-change-control` for every behavior-changing migration slice. Keep each
|
||||
slice small enough to deliver a visible success while deleting one obsolete
|
||||
path.
|
||||
|
||||
## Provenance and maintenance
|
||||
|
||||
Re-verify declarations and defaults: `rg -n 'type (Config|IdentityConfig|Repo|Agent|ContainerConfig|ChatConfig|ToolsConfig)|func (Load|LoadOverlay|LoadDir|finalize|\(c Config\) ForTask|\(tc TaskConfig\) ToConfig)' internal/config`
|
||||
|
||||
Re-verify entrypoint and flag selection: `rg -n 'flag\.|LoadOverlay|LoadDir|ForTask|ToConfig|containerEnv' cmd/archied cmd/archie-agent internal/daemon`
|
||||
|
||||
Re-verify all exposed help: `env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-help-gocache go run ./cmd/archied -h`
|
||||
|
||||
Re-verify worker help: `env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-help-gocache go run ./cmd/archie-agent -h`
|
||||
|
||||
Re-verify config behavior: `env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-test-gocache go test ./internal/config -count=1`
|
||||
|
||||
Re-verify deployment passthrough: `rg -n 'command:|environment:|config\.toml|config\.docker\.toml|NATS_|TOKEN|API_KEY' docker-compose.yml config.docker.toml config.example.toml Dockerfile Dockerfile.archied`
|
||||
|
||||
Re-verify target doctrine: `rg -n 'Ownership|Dissolution|Current configuration migration ledger|Universal change protocol|Completion criteria' docs/prds/architecture/configuration.md`
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Archie Config and Flags"
|
||||
short_description: "Trace Archie configuration from input to runtime"
|
||||
default_prompt: "Use $archie-config-and-flags to trace this Archie setting or CLI flag from declaration through production wiring."
|
||||
@@ -0,0 +1,473 @@
|
||||
---
|
||||
name: archie-debugging-playbook
|
||||
description: Project-specific symptom-to-evidence triage for archie-core. Load this skill when Archied hangs, parks a task, loses or duplicates work, cannot reach NATS or an agent container, rejects configuration or secrets, shows stale Telegram or dashboard state, loses streamed text, fails MCP startup, reports NellDB state surprises, degrades an optional feature, or when Go tests disagree between a sandbox, editor, CI, and the host. Use it to separate environment failures from code regressions and to choose the next exact diagnostic.
|
||||
---
|
||||
|
||||
# Debug Archie from evidence
|
||||
|
||||
Use this runbook to identify the failing boundary. Stop after establishing the
|
||||
smallest reproducible symptom and its owner. Do not edit code while collecting
|
||||
the first evidence set.
|
||||
|
||||
Treat facts marked **current** as verified against the repository on
|
||||
2026-07-28. Treat facts marked **fixed history** as regression patterns, not
|
||||
claims that production is failing now. Treat **open** as a verified gap whose
|
||||
production impact still depends on deployment state.
|
||||
|
||||
Define these terms once:
|
||||
|
||||
- **Composition root**: `cmd/archied/main.go`, where decoded configuration
|
||||
becomes live services.
|
||||
- **Core NATS request/reply**: a request sent directly to a subject and answered
|
||||
through its reply inbox.
|
||||
- **JetStream**: the persisted NATS task/agent stream named `ARCHIE_TASKS`.
|
||||
- **Wiring**: construction and connection of an implemented package into the
|
||||
running daemon.
|
||||
- **Environment failure**: a test or process cannot use a host resource such as
|
||||
a listener, temp directory, Docker socket, or credential.
|
||||
- **Code regression**: the same focused behavior fails in an environment that
|
||||
provides its declared prerequisites.
|
||||
|
||||
## Do not use this skill for the wrong job
|
||||
|
||||
- For the incident timeline, rejected fixes, or reverts, load
|
||||
`archie-failure-archaeology`.
|
||||
- For AST traversal, callers, duplicate paths, or feature impact, load
|
||||
`archie-codebase-discovery`.
|
||||
- For repeatable inventories and measurements, load
|
||||
`archie-diagnostics-and-tooling`.
|
||||
- For installing tools or recreating the machine, load `archie-build-and-env`.
|
||||
- For live startup, Compose, deployment, logs, or rollback, load
|
||||
`archie-run-and-operate`.
|
||||
- For acceptance evidence after a fix, load `archie-validation-and-qa`, then
|
||||
route behavior-changing work through `archie-change-control`.
|
||||
- For NellDB design or persistence changes, load `archie-nelldb`.
|
||||
|
||||
## Run the first-ten-minutes protocol
|
||||
|
||||
1. Record the exact command, exit code, first causal error, working directory,
|
||||
configuration paths, execution mode, and whether the run was sandboxed.
|
||||
2. Reproduce one package or one process boundary. Do not begin with `task
|
||||
check`: it writes through `gofumpt -w .` and `go fix ./...`.
|
||||
3. Compile tests without running them:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-debug-gocache \
|
||||
GIT_CONFIG_GLOBAL=/dev/null go test ./PATH/TO/PACKAGE -run '^$' -count=1
|
||||
```
|
||||
|
||||
4. Run only the named test:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-debug-gocache \
|
||||
GIT_CONFIG_GLOBAL=/dev/null go test ./PATH/TO/PACKAGE \
|
||||
-run '^TestName$' -count=1 -v
|
||||
```
|
||||
|
||||
5. Classify the first failure:
|
||||
|
||||
- Compile-only failure: inspect code, generated inputs, build tags, and the
|
||||
actual Go toolchain.
|
||||
- `listen ... operation not permitted` or an embedded NATS panic: rerun in an
|
||||
environment that permits loopback listeners before blaming code.
|
||||
- `mkdir /work/tmp/...: read-only file system`: keep `GOTMPDIR=/tmp`; the
|
||||
repository code has not run yet.
|
||||
- Behavioral assertion with the prerequisite available: treat it as a code
|
||||
regression.
|
||||
6. Preserve the failing output. Predict the expected observation before trying
|
||||
a workaround.
|
||||
|
||||
Use this symptom index to select the detailed branch:
|
||||
|
||||
| Symptom | First boundary | Go to |
|
||||
|---|---|---|
|
||||
| `Run() = "\n"` in `TestRunWrapsExternalCommand` | Skill-script test command shape | Current known regression |
|
||||
| Embedded NATS panics before a test assertion | Listener permission | Test environment |
|
||||
| `nats: no responders available for request` | Core NATS subscription | NATS request/reply |
|
||||
| Agent reply timeout | JetStream request, inbox, or worker | NATS request/reply |
|
||||
| Queue looks empty while NATS reports an error | `Client.Fetch` batch error | NATS request/reply |
|
||||
| Config test passes but daemon ignores the field | Composition/wiring | Configuration |
|
||||
| Daemon has an env var but container does not | Compose or `containerEnv` | Configuration |
|
||||
| Telegram reply hangs on the first token | Stream consumer | Streaming |
|
||||
| MCP unit tests pass but a real server hangs | Framing mirror | MCP |
|
||||
| Telegram shows old commands | Token-scoped Telegram state | Telegram |
|
||||
| Transition succeeds from the wrong state | Store semantics | NellDB/state |
|
||||
| Dashboard skips events but task state is correct | Bounded event buffers | Events |
|
||||
| Search works but never becomes indexed | Missing production wiring | Optional features |
|
||||
| Agent container cannot resolve `nats` | Docker network | Containers |
|
||||
| `agent.mode = "subprocess"` fails at protocol startup | Worker binary mismatch | Subprocess mode |
|
||||
| IDE reports an error that CLI cannot reproduce | Editor/cache state | Test environment |
|
||||
|
||||
## Separate test-environment failures from regressions
|
||||
|
||||
Inspect the active Go paths before changing code:
|
||||
|
||||
```bash
|
||||
go version
|
||||
go env GOTMPDIR GOCACHE GOPATH GOMODCACHE GOENV
|
||||
```
|
||||
|
||||
This checkout can inherit `GOTMPDIR=/work/tmp`; that path is read-only in some
|
||||
sandboxes. Setting both `GOTMPDIR=/tmp` and a task-specific `GOCACHE` is a
|
||||
diagnostic isolation step, not a product fix.
|
||||
|
||||
Listener-dependent tests include embedded NATS, `httptest.NewServer`, and SMTP
|
||||
listeners. Locate them:
|
||||
|
||||
```bash
|
||||
rg -n 'httptest\.NewServer|net\.Listen|RunRandClientPortServer|RunServer' \
|
||||
--glob '*_test.go' cmd internal
|
||||
```
|
||||
|
||||
If a listener is forbidden, the characteristic evidence is a panic such as
|
||||
`Unable to start NATS Server in Go Routine` or
|
||||
`httptest: failed to listen on a port ... operation not permitted`. A
|
||||
listener-free package passing does not waive the blocked integration tests.
|
||||
|
||||
Do not attribute current go-git commit failures to GPG without checking the
|
||||
repository-local mitigation. `worktree.Manager.setIdentity` pins
|
||||
`commit.gpgsign=false`; its fixtures do the same. Isolate ambient global config:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-worktree-gocache \
|
||||
GIT_CONFIG_GLOBAL=/dev/null go test ./internal/worktree -count=1
|
||||
```
|
||||
|
||||
If this passes while an editor still reports compiler errors, record the CLI
|
||||
result as authoritative and restart the editor language server. Do not delete
|
||||
module caches merely to silence a diagnostic.
|
||||
|
||||
**Fixed history:** `.gotmp/` once held a workaround for tmpfs quota pressure and
|
||||
was accidentally committed by a broad add. It is ignored now. Keep diagnostics
|
||||
in `/tmp`, and never turn a local cache workaround into repository content.
|
||||
|
||||
## Confirm the current known regression
|
||||
|
||||
As of 2026-07-28, this focused test fails in an otherwise runnable package:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-skillscript-gocache \
|
||||
GIT_CONFIG_GLOBAL=/dev/null go test ./internal/skillscript \
|
||||
-run '^TestRunWrapsExternalCommand$' -count=1 -v
|
||||
```
|
||||
|
||||
Expected current failure:
|
||||
|
||||
```text
|
||||
Run() = "\n"
|
||||
```
|
||||
|
||||
The test constructs:
|
||||
|
||||
```go
|
||||
exec.CommandContext(ctx, "sh", "-c", "echo", "wrapped")
|
||||
```
|
||||
|
||||
For `sh -c`, the argument after the command string becomes shell `$0`;
|
||||
therefore the command string is only `echo`, which prints a newline. This is a
|
||||
test regression introduced by cleanup commit `308c199`, not proof that Yaegi
|
||||
cannot run external commands. Do not weaken the expected `"wrapped\n"` value.
|
||||
Route the fix and its acceptance evidence through `archie-change-control` and
|
||||
`archie-validation-and-qa`.
|
||||
|
||||
## Triage NATS request/reply and JetStream
|
||||
|
||||
Keep the two transports distinct:
|
||||
|
||||
| Surface | Subject or resource | Bound/current behavior |
|
||||
|---|---|---|
|
||||
| Task discovery | `archie.task.>` in `ARCHIE_TASKS` | Work-queue retention; daemon durable `archie-daemon`; max deliver 3 |
|
||||
| Legacy agent stage | `archie.agent.<task>.request` | Reply inbox in `X-Archie-Reply`; wall-clock budget or 30m |
|
||||
| Full task handoff | `archie.taskrun.<task-id>` | Core request/reply; no-responder retry defaults to 20s every 250ms |
|
||||
| Store RPC | `archie.store.update`, `.transition` | Client timeout set to 60s by `cmd/archie-agent/taskrun.go` |
|
||||
| Forge RPC | `archie.forge.*` | Error travels in a JSON envelope |
|
||||
| Worktree RPC | `archie.worktree.prepare`, `.push` | Server default handler bound is 15m |
|
||||
| Discovery deduplication | `Nats-Msg-Id: archie:<owner>/<repo>/<issue>` | JetStream duplicate window is 2m |
|
||||
|
||||
For any NATS failure, collect read-only deployment evidence:
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
docker compose logs --since=10m archied nats
|
||||
docker ps --filter label=archie-daemon=true \
|
||||
--format '{{.ID}}\t{{.Names}}\t{{.Networks}}\t{{.Status}}'
|
||||
docker compose exec -T nats wget -q -O - http://localhost:8222/healthz
|
||||
```
|
||||
|
||||
No stable container count exists; compare the task ID, agent container, and
|
||||
subscription timing rather than demanding a fixed number.
|
||||
|
||||
Branch on `no responders`:
|
||||
|
||||
1. If a responder appears within 20 seconds, classify it as container startup
|
||||
lag. `Daemon.requestTaskRun` deliberately retries only
|
||||
`nats.ErrNoResponders`.
|
||||
2. If every task exhausts the window, inspect the spawned agent's network and
|
||||
environment. The Compose overlay currently sets
|
||||
`containers.network = "archie-core_default"` and NATS URL
|
||||
`nats://nats:4222`.
|
||||
3. Look for agent logs `nats connected`, `taskrun: dedicated per-task
|
||||
subscription`, and `archie-agent ready`. Absence of all three points before
|
||||
workflow execution.
|
||||
4. If only store/forge/worktree calls time out, confirm the composition root
|
||||
reached `registerTaskRPCServers`; do not debug JetStream task discovery.
|
||||
|
||||
**Fixed history:** network auto-detection once silently put task containers on
|
||||
the default bridge, so `nats` never resolved and every request had no
|
||||
responders. Explicit `containers.network` plus warning logs now fence that
|
||||
path.
|
||||
|
||||
Check duplicate and error semantics before "fixing" them:
|
||||
|
||||
- Republishing the same owner/repo/issue within two minutes is intentionally
|
||||
deduplicated.
|
||||
- A reply inbox auto-unsubscribes after one response. Search for two handlers
|
||||
subscribed to the same request subject before assuming response loss.
|
||||
- `Client.Fetch` must inspect `batch.Error()` after the message channel closes;
|
||||
returning `(nil, nil)` would mask a JetStream failure as an empty queue.
|
||||
- `agentexec.runStages` returns a response envelope and a nil Go error for a
|
||||
stage failure. Returning both the envelope error and a Go error aborts the
|
||||
handler before it can publish the response.
|
||||
|
||||
Run listener-free regression coverage for the last two rules:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-nats-unit-gocache \
|
||||
go test ./internal/nats \
|
||||
-run '^TestFetchPropagatesBatchError' -count=1 -v
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-agent-unit-gocache \
|
||||
go test ./internal/agentexec \
|
||||
-run '^TestHandleMessage' -count=1 -v
|
||||
```
|
||||
|
||||
## Trace configuration from source to behavior
|
||||
|
||||
Never stop at "the field decoded." Trace this sequence:
|
||||
|
||||
1. `cmd/archied` reads `-config` and optional `-config-overlay`.
|
||||
2. `config.LoadOverlay` TOML-decodes and `finalize` defaults/validates.
|
||||
3. Secret references resolve or named environment variables are read.
|
||||
4. The composition root constructs a service from the field.
|
||||
5. Compose, subprocess allowlists, or `containerEnv` propagate needed values.
|
||||
6. A focused behavior test observes the value at its consumer.
|
||||
|
||||
Use these source checks:
|
||||
|
||||
```bash
|
||||
rg -n 'config\.LoadOverlay|config\.LoadDir' cmd/archied internal/config
|
||||
rg -n 'cfg\.[A-Za-z0-9_.]+' cmd/archied/main.go
|
||||
rg -n 'containerEnv|WorkerEnvironment|environment:' \
|
||||
cmd internal docker-compose.yml
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-gocache \
|
||||
go test ./internal/config \
|
||||
-run 'Test(LoadOverlay|LoadForgeToken|DockerConfig)' -count=1 -v
|
||||
```
|
||||
|
||||
Expected current observation: production `cmd/archied` calls
|
||||
`config.LoadOverlay`; feature-file `config.LoadDir` is covered by tests but has
|
||||
no `config.LoadDir` call in the composition root. A YAML feature field can
|
||||
therefore decode correctly without affecting the daemon. Classify that as a
|
||||
wiring gap, not a parser bug.
|
||||
|
||||
For environment failures, distinguish:
|
||||
|
||||
- Compose passes only the names listed under `archied.environment`.
|
||||
- `containerEnv` translates the configured NATS token name into `NATS_TOKEN`
|
||||
for `archie-agent` and forwards configured provider key variables.
|
||||
- `SubprocessRunner` forwards default compatibility variables, configured
|
||||
`[agent].env` names, and only the requested provider key.
|
||||
- The legacy top-level `[forge] token_env` is converted to an env `SecretRef`
|
||||
by `finalize`; explicit `[forge.token]` wins.
|
||||
|
||||
Do not print secret values. Record only the variable name and
|
||||
set/unset/propagated status.
|
||||
|
||||
## Diagnose streaming, MCP, and Telegram
|
||||
|
||||
### Streaming
|
||||
|
||||
If a Telegram draft shows an empty cursor, typing never clears, and the turn
|
||||
never completes, inspect the consumer in `cmd/archied/main.go`. Current code
|
||||
must drain `stream.FullStream`, collect only `core.StreamPartTextDelta`, then
|
||||
check `FinishReason`. `TextStream` is a best-effort view and cannot reconstruct
|
||||
the authoritative response.
|
||||
|
||||
**Fixed history:** consuming `TextStream` while leaving synchronous
|
||||
`FullStream` unread deadlocked every streamed reply. Do not add a second
|
||||
consumer or return before `FullStream` closes.
|
||||
|
||||
### MCP
|
||||
|
||||
Current stdio framing is one compact JSON-RPC object per line. Despite a stale
|
||||
package comment in `internal/tools/mcp/types.go`, `Content-Length` framing is
|
||||
not the implemented contract. Verify unit behavior:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-mcp-gocache \
|
||||
go test ./internal/tools/mcp \
|
||||
-run 'Test(ReadMessage|WriteMessage|StdioTransportBadFraming)' \
|
||||
-count=1 -v
|
||||
```
|
||||
|
||||
Do not accept this alone as protocol compatibility: the helper server in
|
||||
`transport_test.go` calls the same `readMessage` and `writeMessage` functions,
|
||||
so client and fake can mirror the same mistake. With network access and `npx`
|
||||
explicitly allowed, run the real-server test:
|
||||
|
||||
```bash
|
||||
ARCHIE_TEST_DESKTOP_COMMANDER=1 \
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-mcp-integration-gocache \
|
||||
go test ./internal/tools/provider/mcp \
|
||||
-run '^TestDesktopCommanderClientCompatibility$' -count=1 -v
|
||||
```
|
||||
|
||||
No stable tool count is asserted. The gate is non-empty discovery containing
|
||||
`start_process`, `interact_with_process`, and `read_process_output`.
|
||||
|
||||
### Telegram
|
||||
|
||||
If commands work when typed but the menu is stale, inspect all three command
|
||||
scopes in `internal/channels/telegram/commands.go`: default, all private chats,
|
||||
and all group chats. Telegram stores command menus outside this repository,
|
||||
keyed by bot token, and a narrower scope shadows the default.
|
||||
|
||||
If access is wrong, verify sender IDs, not chat IDs. Empty
|
||||
`allowed_user_ids` denies everyone; message, model, provider, and update
|
||||
callbacks each enforce sender authorization.
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-telegram-gocache \
|
||||
go test ./internal/channels/telegram \
|
||||
-run 'Test(SenderAllowlistFailsClosed|IsSenderAllowed|PublishedCommandsMatchExecutableCommandSurface)$' \
|
||||
-count=1 -v
|
||||
```
|
||||
|
||||
**Fixed history:** publishing only the default menu left roughly 60 commands
|
||||
from a previous bot implementation visible in narrower scopes. A successful
|
||||
single `SetMyCommands` call was insufficient evidence.
|
||||
|
||||
## Diagnose state, events, containers, and optional features
|
||||
|
||||
### NellDB and transitions
|
||||
|
||||
Current `internal/nell.Adapter.Transition` looks up the task, writes `to`, and
|
||||
does not compare `from` or persist `detail`. The legacy SQLite store also does
|
||||
not guard its update with `from`, although it records a transition row. Thus
|
||||
"transition returned nil" does not prove the source state matched.
|
||||
|
||||
When state is surprising:
|
||||
|
||||
1. Read `TaskByID` immediately before and after the caller.
|
||||
2. Trace every `Transition`, `Requeue`, `RecoverStale`, and `Update` call.
|
||||
3. Do not infer a valid state machine from the `from` argument.
|
||||
4. Run both backends' focused suites:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-state-gocache \
|
||||
GIT_CONFIG_GLOBAL=/dev/null go test \
|
||||
./internal/nell ./internal/store -count=1
|
||||
```
|
||||
|
||||
Route any semantic change to `archie-nelldb`, architecture planning, and change
|
||||
control; it is not a local error-message fix.
|
||||
|
||||
### Events
|
||||
|
||||
The in-process bus drops when a subscriber buffer is full. The composition
|
||||
root's database sink buffer is 256; SSE client buffers are 64. The sink's drop
|
||||
counter is not read in production, and per-client drops are not counted.
|
||||
Therefore a dashboard gap can coexist with correct task state.
|
||||
|
||||
```bash
|
||||
rg -n 'Subscribe\(256\)|make\(chan events\.Event, 64\)|Dropped\(\)' \
|
||||
cmd/archied/main.go internal/events internal/webui
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-events-gocache \
|
||||
go test ./internal/events -count=1
|
||||
```
|
||||
|
||||
No stable production drop count exists. Treat missing events as an
|
||||
observability defect only after comparing the persisted task document and
|
||||
event log.
|
||||
|
||||
### Containers, worktrees, and subprocess mode
|
||||
|
||||
- A container-mode task clones on the host, mounts it at `/data/worktree`,
|
||||
writes `task.json`, then uses a dedicated `archie.taskrun.<id>`
|
||||
subscription when that file parses.
|
||||
- The worktree manager uses go-git, pins signing off, stores its prepared
|
||||
sentinel under `.git`, and performs an independent full clone per task.
|
||||
- **Open:** container RPC registration is root-identity-bound; the comment in
|
||||
`Daemon.process` says non-root identity container calls can use the wrong
|
||||
forge/worktree clients.
|
||||
- **Open:** the default `archie-agent` binary is now a long-running NATS worker,
|
||||
while `SubprocessRunner` expects one JSON invocation on stdin and one JSON
|
||||
response on stdout. `agent.mode="subprocess"` remains accepted by config, so
|
||||
verify the configured command implements the old protocol before using it.
|
||||
|
||||
Confirm the binary shape without starting NATS:
|
||||
|
||||
```bash
|
||||
env -u NATS_URL -u NATS_TOKEN GOTMPDIR=/tmp \
|
||||
GOCACHE=/tmp/archie-agent-shape-gocache \
|
||||
go run ./cmd/archie-agent </dev/null
|
||||
```
|
||||
|
||||
Expected current observation: exit 1 with
|
||||
`-nats-url or NATS_URL is required`, not a decoded stdin invocation. Label a
|
||||
deployment using another compatible command separately.
|
||||
|
||||
### Optional feature degradation
|
||||
|
||||
Configuration is not capability evidence. Check startup logs and production
|
||||
construction:
|
||||
|
||||
| Feature | Current failure behavior |
|
||||
|---|---|
|
||||
| Daemon plugin adaptation/registration | Warn and skip that capability |
|
||||
| Invalid MCP server config | Warn `mcp tool provider skipped` and continue |
|
||||
| Skill catalog/activation registration | Warn and continue without the tool |
|
||||
| Worktree workflow augmentation | Log error, emit `registry_augment_failed`, use startup registry |
|
||||
| Workspace indexing | **Open:** config defaults and helper exist, but no production `indexing.NewManager` call |
|
||||
|
||||
Verify the indexing wiring gap:
|
||||
|
||||
```bash
|
||||
rg -n 'indexing\.NewManager|NewManager\(.*Index' \
|
||||
cmd internal --glob '*.go' --glob '!*_test.go'
|
||||
```
|
||||
|
||||
Expected current result: no production call. Do not diagnose slow unindexed
|
||||
search by tuning index paths until this wiring changes.
|
||||
|
||||
## Close the diagnostic
|
||||
|
||||
Record:
|
||||
|
||||
- the smallest failing command and its prerequisite;
|
||||
- the first causal error, not the final wrapper;
|
||||
- the boundary owner and current/fixed-history/open classification;
|
||||
- the expected observation and actual observation;
|
||||
- the source symbol and focused test that protect the behavior;
|
||||
- whether the result reproduces outside the sandbox;
|
||||
- the next sibling skill and change-control class.
|
||||
|
||||
Do not call a diagnosis complete because a workaround made the symptom vanish.
|
||||
Require a falsifiable cause: removing or restoring the suspected condition must
|
||||
toggle the failure.
|
||||
|
||||
## Provenance and maintenance
|
||||
|
||||
Repository state and volatile facts were re-verified on 2026-07-28. Re-run
|
||||
these one-line checks after changes:
|
||||
|
||||
```bash
|
||||
rg -n 'defaultTaskRunReadyTimeout|defaultTaskRunRetryBackoff' internal/daemon/daemon.go
|
||||
rg -n 'dedupWindow|pollTimeout|AckWait|MaxDeliver' internal/nats/client.go cmd/archie-agent/main.go
|
||||
rg -n 'FullStream|TextStream|FinishReason' cmd/archied/main.go
|
||||
rg -n 'Content-Length|newline-delimited' internal/tools/mcp
|
||||
rg -n 'commandScopes|AllowedUserIDs|isSenderAllowed' internal/channels/telegram
|
||||
rg -n 'func \(a \*Adapter\) Transition|func \(s \*Store\) Transition' internal/nell/adapter.go internal/store/store.go
|
||||
rg -n 'Subscribe\(256\)|Dropped\(\)' cmd/archied/main.go internal/events
|
||||
rg -n 'config\.LoadOverlay|config\.LoadDir|indexing\.NewManager' cmd internal --glob '*.go'
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-skillscript-gocache go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v
|
||||
```
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Archie Debugging Playbook"
|
||||
short_description: "Diagnose Archie failures from symptoms"
|
||||
default_prompt: "Use $archie-debugging-playbook to diagnose this Archie failure from symptoms and evidence."
|
||||
@@ -0,0 +1,429 @@
|
||||
---
|
||||
name: archie-diagnostics-and-tooling
|
||||
description: "Measure Archie codebase maintainability, Go package dependency shape, configuration consumption, production composition, test and delivery-gate drift, tracked-artifact hygiene, coverage, races, and runtime evidence. Load when establishing a dated baseline, finding large or complex functions, investigating duplicate or dead-path candidates, checking whether configuration reaches an entrypoint, comparing architecture before and after a refactor, or replacing an eyeballed quality claim with reproducible numbers."
|
||||
---
|
||||
|
||||
# Measure Archie instead of eyeballing it
|
||||
|
||||
Collect evidence before judging quality. Keep collection read-only, save raw
|
||||
output, state what each metric cannot prove, and route behavior-changing
|
||||
decisions through the appropriate gate.
|
||||
|
||||
Volatile facts and numeric snapshots below were verified on **2026-07-28**.
|
||||
Re-run the commands before using any number as a baseline.
|
||||
|
||||
## Scope and routing
|
||||
|
||||
Use this skill to answer measurable questions:
|
||||
|
||||
- Which production functions exceed the repository's size or complexity
|
||||
triage thresholds?
|
||||
- Which packages have high internal fan-in or fan-out?
|
||||
- Which tagged config fields have no syntax-level production or entrypoint
|
||||
selector evidence?
|
||||
- Which checks appear literally in Task, CI, docs, and deploy surfaces?
|
||||
- Did a refactor reduce a named hotspot without adding dependencies or losing
|
||||
validation coverage?
|
||||
|
||||
Do **not** use this skill as:
|
||||
|
||||
| Need | Load instead |
|
||||
|---|---|
|
||||
| Traverse an input through types, state, persistence, transports, consumers, and production composition | `archie-codebase-discovery` |
|
||||
| Turn a hunch into a decision-gated experiment | `archie-research-methodology` |
|
||||
| Decide package boundaries or run an architecture migration | `archie-architecture-planning-campaign` and `archie-architecture-contract` |
|
||||
| Approve a patch or define acceptance evidence | `archie-validation-and-qa` and `archie-change-control` |
|
||||
| Diagnose a live failure or operate a deployment | `archie-debugging-playbook` and `archie-run-and-operate` |
|
||||
| Assign an owner, prove supersession, or approve deletion | `archie-technical-accountability` |
|
||||
| Enumerate config defaults and supported axes | `archie-config-and-flags` |
|
||||
|
||||
Never call a path dead, a field unwired, or a package misplaced from one report.
|
||||
Use reports to prioritize exact semantic traversal.
|
||||
|
||||
## Define the measurement terms
|
||||
|
||||
- **Baseline:** dated raw output tied to a commit, toolchain, command, and
|
||||
environment.
|
||||
- **Candidate:** a machine-found item requiring semantic confirmation.
|
||||
- **Production composition:** concrete construction selected by a shipped
|
||||
entrypoint. Archie's principal composition root is `cmd/archied/main.go`.
|
||||
- **Fan-in:** number of packages in the same module that directly import a
|
||||
package.
|
||||
- **Fan-out:** number of packages in the same module that a package directly
|
||||
imports.
|
||||
- **Physical line:** a newline-delimited source line, including comments and
|
||||
blanks. It is not a statement count.
|
||||
- **Syntactic complexity:** this skill's approximation: one plus `if`, loop,
|
||||
non-default case, communication clause, `&&`, and `||` nodes. It is not
|
||||
`gocyclo`, `gocognit`, or `cyclop`.
|
||||
- **Acceptance evidence:** evidence sufficient to approve the intended
|
||||
behavior. Diagnostics are inputs to acceptance, not acceptance by themselves.
|
||||
|
||||
## Establish a reproducible snapshot
|
||||
|
||||
Run from the repository root. Keep caches and output outside the tree:
|
||||
|
||||
```sh
|
||||
export LC_ALL=C
|
||||
export GOCACHE=/tmp/archie-diagnostics-gocache
|
||||
export GOTMPDIR=/tmp
|
||||
export XDG_CACHE_HOME=/tmp/archie-diagnostics-xdg
|
||||
export GOLANGCI_LINT_CACHE=/tmp/archie-diagnostics-lint
|
||||
export GOPROXY=off
|
||||
export GOFLAGS=-mod=readonly
|
||||
|
||||
skill=.claude/skills/archie-diagnostics-and-tooling
|
||||
stamp=$(date -u +%Y%m%dT%H%M%SZ)
|
||||
evidence_dir=/tmp/archie-diagnostics-"$stamp"
|
||||
mkdir -p "$evidence_dir"
|
||||
|
||||
git rev-parse --verify HEAD >"$evidence_dir/revision.txt"
|
||||
git status --short >>"$evidence_dir/revision.txt"
|
||||
go version >"$evidence_dir/tools.txt"
|
||||
gopls version >>"$evidence_dir/tools.txt"
|
||||
golangci-lint version >>"$evidence_dir/tools.txt"
|
||||
staticcheck -version >>"$evidence_dir/tools.txt"
|
||||
|
||||
go run "$skill/scripts/source-metrics.go" -root . >"$evidence_dir/source.tsv"
|
||||
go run "$skill/scripts/config-use-candidates.go" -root . >"$evidence_dir/config.tsv"
|
||||
"$skill/scripts/package-shape.sh" . >"$evidence_dir/packages-root.tsv"
|
||||
"$skill/scripts/package-shape.sh" tools >"$evidence_dir/packages-tools.tsv"
|
||||
"$skill/scripts/delivery-snapshot.sh" >"$evidence_dir/delivery.tsv"
|
||||
```
|
||||
|
||||
`GOPROXY=off` and `-mod=readonly` prevent this evidence pass from fetching or
|
||||
changing dependencies. Report an uncached dependency as an environment blocker.
|
||||
The package helper preserves a harmless read-only module stat-cache warning but
|
||||
normalizes its random temporary suffix to `<TEMP>`; preserve stderr and the exit
|
||||
status with the report.
|
||||
|
||||
Write a measurement charter before interpreting output:
|
||||
|
||||
| Field | Required content |
|
||||
|---|---|
|
||||
| Question | One falsifiable maintainability, wiring, or delivery claim |
|
||||
| Scope | Exact packages, modes, config branches, and modules |
|
||||
| Predicted result | Expected baseline and before/after delta |
|
||||
| Collection command | Exact command and environment |
|
||||
| Branch condition | What contrary number triggers deeper discovery |
|
||||
| Decision owner | Skill or reviewer that may approve action |
|
||||
|
||||
Do not invent a composite “quality score.” Keep size, complexity, dependency,
|
||||
duplication, coverage, runtime, and ownership evidence separate.
|
||||
|
||||
## Use the bundled reports
|
||||
|
||||
### Measure source shape
|
||||
|
||||
Run:
|
||||
|
||||
```sh
|
||||
go run "$skill/scripts/source-metrics.go" -root . -top 30
|
||||
```
|
||||
|
||||
Read its tab-separated schema:
|
||||
|
||||
| Record | Columns after record name |
|
||||
|---|---|
|
||||
| `META` | key, value |
|
||||
| `METRIC` | module, metric, integer |
|
||||
| `PACKAGE` | module, directory, production files, test files, generated files, production lines, test lines, generated lines |
|
||||
| `HOTSPOT` | module, file, declaration line, symbol, body-span lines, statement nodes, approximate syntactic complexity |
|
||||
|
||||
The script:
|
||||
|
||||
- scans repository-owned Go files;
|
||||
- separates the root and `tools` modules;
|
||||
- separates production, test, and generated files;
|
||||
- excludes `.git`, `.claude`, `.references`, `node_modules`, `vendor`,
|
||||
`.gotmp`, and VitePress cache/output;
|
||||
- sorts output deterministically;
|
||||
- reports only production hotspots unless
|
||||
`-include-test-hotspots` is passed.
|
||||
|
||||
The defaults, 80 body lines and complexity 15, mirror two numeric triage points
|
||||
in `.golangci.yml`. They do **not** implement `funlen` or `cyclop`. Run the
|
||||
configured linters for authoritative linter findings:
|
||||
|
||||
```sh
|
||||
golangci-lint run --enable-only=funlen,gocognit,gocyclo,cyclop,maintidx,nestif ./internal/...
|
||||
```
|
||||
|
||||
If a hotspot shrinks, verify that responsibility moved to a cohesive owner.
|
||||
Moving the same work into unowned helpers is not improvement.
|
||||
|
||||
### Measure package shape
|
||||
|
||||
Run both module reports:
|
||||
|
||||
```sh
|
||||
"$skill/scripts/package-shape.sh" . >"$evidence_dir/packages-root.tsv"
|
||||
"$skill/scripts/package-shape.sh" tools >"$evidence_dir/packages-tools.tsv"
|
||||
awk -F ' ' '$1=="PACKAGE" {print $3 "\t" $4 "\t" $2}' "$evidence_dir/packages-root.tsv" |
|
||||
sort -nr -k1,1 -k2,2 |
|
||||
sed -n '1,20p'
|
||||
```
|
||||
|
||||
Read `PACKAGE package fan_in fan_out` and `EDGE from -> to` rows. The script
|
||||
reuses
|
||||
`.claude/skills/archie-codebase-discovery/scripts/package-edges.sh`; do not
|
||||
create a second package-edge implementation.
|
||||
|
||||
Interpret high fan-in as a change-risk signal and high fan-out as an
|
||||
orchestration signal, not as automatic defects. The report contains only
|
||||
direct, intra-module imports. It does not show `tools` importing the root
|
||||
module, interface dispatch, RPC relationships, string registrations, or state
|
||||
ownership. A successful `go list` rejects Go import cycles; it does not prove
|
||||
the target dependency doctrine.
|
||||
|
||||
When an edge looks wrong:
|
||||
|
||||
1. Run `archie-codebase-discovery` on the imported contract.
|
||||
2. Identify the concrete production consumer.
|
||||
3. Compare the current edge with `docs/prds/architecture/`.
|
||||
4. Route any boundary change through the architecture campaign.
|
||||
|
||||
### Find configuration-consumption candidates
|
||||
|
||||
Run:
|
||||
|
||||
```sh
|
||||
go run "$skill/scripts/config-use-candidates.go" -root . >"$evidence_dir/config.tsv"
|
||||
rg 'candidate-no-(selector-outside-config|entrypoint-selector)' "$evidence_dir/config.tsv"
|
||||
```
|
||||
|
||||
Read each `CONFIG_FIELD` row as:
|
||||
|
||||
```text
|
||||
path, line, Type.Field, tags, same-name definition count,
|
||||
config-package selector count, cmd selector count,
|
||||
other-production selector count, test selector count,
|
||||
generated selector count, candidate status
|
||||
```
|
||||
|
||||
The report finds named fields with `toml`, `yaml`, or `json` tags declared in
|
||||
`internal/config`, then counts selectors with the same **spelling**. It is
|
||||
deliberately fast and deliberately not type-aware.
|
||||
|
||||
For every candidate:
|
||||
|
||||
1. Inspect the declaration at the reported `path:line`.
|
||||
2. Run `gopls references -d` on that exact field identifier.
|
||||
3. Trace decode → default → validation → normalization/copy → composition-root
|
||||
read → concrete component → observable behavior.
|
||||
4. Check reflection, serialization tags, Yaegi, registries, and string keys.
|
||||
5. Separate feature-file tests from production selection.
|
||||
|
||||
Repeated names such as `Name`, `Command`, or `Budgets` have high false-positive
|
||||
rates; use the same-name count as a warning. A zero `cmd` count may be correct
|
||||
when the composition root passes an enclosing struct. A nonzero count may
|
||||
belong to an unrelated field. Only type-aware references plus composition prove
|
||||
wiring.
|
||||
|
||||
### Measure delivery and hygiene drift
|
||||
|
||||
Run:
|
||||
|
||||
```sh
|
||||
"$skill/scripts/delivery-snapshot.sh" >"$evidence_dir/delivery.tsv"
|
||||
```
|
||||
|
||||
Read:
|
||||
|
||||
- `SURFACE axis scope literal_count` as literal text evidence, not parsed YAML
|
||||
semantics;
|
||||
- `HYGIENE metric count` as tracked-path candidates;
|
||||
- `MODULE path` as discovered Go module boundaries.
|
||||
|
||||
The snapshot compares Task, GitHub docs CI, Gitea deploy CI, and selected
|
||||
composition-root anchors. A zero says the literal pattern was absent. It does
|
||||
not prove the behavior is absent from a called script or external system.
|
||||
|
||||
Inspect hygiene candidates directly:
|
||||
|
||||
```sh
|
||||
git ls-files |
|
||||
rg '(^|/)(node_modules|bin|dist|\.gotmp)(/|$)|\.(exe|test|out)$'
|
||||
git ls-files -s | awk '$1=="120000" {print}'
|
||||
```
|
||||
|
||||
Do not delete a tracked candidate from a metric alone. Establish ownership,
|
||||
generation source, consumers, deployment need, and a rollback path with
|
||||
`archie-technical-accountability`.
|
||||
|
||||
## Investigate duplication and hidden dead paths
|
||||
|
||||
Measure textual duplication:
|
||||
|
||||
```sh
|
||||
golangci-lint run --enable-only=dupl ./internal/...
|
||||
```
|
||||
|
||||
Measure unused unexported declarations:
|
||||
|
||||
```sh
|
||||
staticcheck -checks=U1000 ./internal/...
|
||||
```
|
||||
|
||||
On 2026-07-28, the focused `dupl` command reported zero issues. That does not
|
||||
contradict the known maintainability problem: two code paths can implement the
|
||||
same responsibility with different syntax.
|
||||
|
||||
For a duplicate or one-shot candidate:
|
||||
|
||||
1. Name the externally visible operation, state transition, event subject, or
|
||||
side effect.
|
||||
2. Search all entrypoints and modes for that operation.
|
||||
3. Use `gopls call_hierarchy`, `gopls references -d`, and the discovery skill's
|
||||
AST construction scan.
|
||||
4. Check interfaces, registrations, reflection, build tags, OS files, and wire
|
||||
names.
|
||||
5. Identify what a new feature supersedes and the objective removal gate.
|
||||
6. Record production-only, test-only, compatibility, generated, and
|
||||
unreachable paths separately.
|
||||
|
||||
As of 2026-07-28, `Taskfile.yml` defines no `deadcode` task and the installed
|
||||
`go tool` lists no dead-code analyzer. Archived PRDs mentioning
|
||||
`task deadcode` describe a desired or former command, not a live command.
|
||||
|
||||
## Collect test, race, coverage, and runtime evidence
|
||||
|
||||
Keep collection scoped to the hypothesis:
|
||||
|
||||
```sh
|
||||
go test ./internal/nell -count=1 -coverprofile=/tmp/archie-nell.cover
|
||||
go tool cover -func=/tmp/archie-nell.cover
|
||||
go test -race ./internal/nell -count=1
|
||||
```
|
||||
|
||||
These commands were verified on 2026-07-28; the package reported 65.2% statement
|
||||
coverage and passed its race run. The percentage is volatile and is not a
|
||||
quality threshold. Read uncovered functions and error paths.
|
||||
|
||||
`go test` can write CPU and memory profiles, but this checkout's `go tool`
|
||||
listed no `pprof` frontend on 2026-07-28. Do not promise profile inspection
|
||||
until `command -v pprof` or another approved viewer succeeds. Do not download a
|
||||
viewer during a read-only evidence pass.
|
||||
|
||||
Collect container logs without following indefinitely:
|
||||
|
||||
```sh
|
||||
docker compose logs archied >"$evidence_dir/archied.log"
|
||||
docker compose logs nats >"$evidence_dir/nats.log"
|
||||
curl -fsS http://localhost:8222/healthz >"$evidence_dir/nats-health.txt"
|
||||
```
|
||||
|
||||
Run those only when the local Compose stack is in scope. Repository files do
|
||||
not prove the remote `carina` instances match local Compose. `docker-compose.yml`
|
||||
publishes NATS monitoring on port 8222 and uses `/healthz` in its healthcheck;
|
||||
it does not establish a metrics endpoint contract. Route remote operations and
|
||||
log interpretation through `archie-run-and-operate` and
|
||||
`archie-debugging-playbook`.
|
||||
|
||||
Some tests bind loopback listeners, including email, forge, storage, Telegram,
|
||||
web UI, and MCP tests. A sandbox refusal to listen is environment evidence, not
|
||||
a code regression. Re-run in an allowed environment before classifying it.
|
||||
|
||||
## Compare before and after
|
||||
|
||||
Predict exact deltas before changing code. Example:
|
||||
|
||||
```text
|
||||
Prediction:
|
||||
- cmd/archied.run body span: 668 → below 350
|
||||
- root package count: unchanged
|
||||
- new internal package edges: zero unless named in the design
|
||||
- config candidate statuses: no regressions
|
||||
- Task/CI/docs surface counts: unchanged unless explicitly in scope
|
||||
```
|
||||
|
||||
Collect a second snapshot with the same script revision, flags, environment,
|
||||
and toolchain:
|
||||
|
||||
```sh
|
||||
after_dir=/tmp/archie-diagnostics-after
|
||||
mkdir -p "$after_dir"
|
||||
go run "$skill/scripts/source-metrics.go" -root . >"$after_dir/source.tsv"
|
||||
go run "$skill/scripts/config-use-candidates.go" -root . >"$after_dir/config.tsv"
|
||||
"$skill/scripts/package-shape.sh" . >"$after_dir/packages-root.tsv"
|
||||
"$skill/scripts/delivery-snapshot.sh" >"$after_dir/delivery.tsv"
|
||||
|
||||
diff -u "$evidence_dir/source.tsv" "$after_dir/source.tsv"
|
||||
diff -u "$evidence_dir/config.tsv" "$after_dir/config.tsv"
|
||||
diff -u "$evidence_dir/packages-root.tsv" "$after_dir/packages-root.tsv"
|
||||
diff -u "$evidence_dir/delivery.tsv" "$after_dir/delivery.tsv"
|
||||
```
|
||||
|
||||
If output differs from the prediction:
|
||||
|
||||
- confirm the checkout, dirty state, script revision, flags, and toolchain;
|
||||
- explain each delta from changed source;
|
||||
- branch to semantic discovery when a count cannot explain behavior;
|
||||
- reject a “better” metric that moved duplication, hid a path, or weakened a
|
||||
gate;
|
||||
- route the resulting change through validation and fresh adversarial review.
|
||||
|
||||
## Record the evidence packet
|
||||
|
||||
Report:
|
||||
|
||||
1. question and numeric prediction;
|
||||
2. revision, dirty state, date, tools, and environment constraints;
|
||||
3. exact commands and exit codes;
|
||||
4. raw evidence paths;
|
||||
5. before/after deltas by independent dimension;
|
||||
6. semantic confirmation for every candidate used in a decision;
|
||||
7. unexpected results and branch taken;
|
||||
8. acceptance owner and remaining unknowns.
|
||||
|
||||
Short wins count only when they leave a reproducible vertical slice: one
|
||||
measured problem, one explained change, and no displaced responsibility left
|
||||
unowned.
|
||||
|
||||
## Dated current snapshot
|
||||
|
||||
The bundled scripts measured this checkout on 2026-07-28:
|
||||
|
||||
| Observation | Unstable value |
|
||||
|---|---:|
|
||||
| Root production/test/generated Go files | 123 / 111 / 4 |
|
||||
| Root production/test/generated physical lines | 25,952 / 31,675 / 157 |
|
||||
| `cmd/archied.run` body span / approximate complexity | 668 / 96 |
|
||||
| `internal/config.finalize` body span / approximate complexity | 177 / 64 |
|
||||
| Root internal packages / direct internal edges | 51 / 129 |
|
||||
| Tagged config field rows | 110 |
|
||||
| Tracked paths / tracked `node_modules` paths / tracked symlinks | 558 / 237 / 238 |
|
||||
| `.dockerignore` present | 0 |
|
||||
|
||||
The delivery snapshot found no Taskfile literals for race, the `tools` module,
|
||||
or docs; no Go-gate literals in either workflow; a docs build in GitHub CI; and
|
||||
container build/push in Gitea CI. `task check` is mutating because it invokes
|
||||
`gofumpt -w .` and `go fix ./...`; do not run it as a read-only diagnostic.
|
||||
Route it to acceptance.
|
||||
|
||||
The focused test
|
||||
`go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v`
|
||||
failed on 2026-07-28 with `Run() = "\n"`. Preserve that known-red baseline; do
|
||||
not claim a clean full suite or attribute it to unrelated work.
|
||||
|
||||
## Provenance and maintenance
|
||||
|
||||
Ground truth verified on 2026-07-28:
|
||||
`Taskfile.yml`, `.golangci.yml`, `go.mod`, `tools/go.mod`,
|
||||
`cmd/{archied,archie-agent}/`, `internal/{config,nell,skillscript}/`,
|
||||
`.github/workflows/docs.yml`, `.gitea/workflows/deploy.yml`,
|
||||
`docker-compose.yml`, `docs-2/package.json`, and `tools/docsgen/`.
|
||||
|
||||
Re-verify scripts: `sh -n .claude/skills/archie-diagnostics-and-tooling/scripts/*.sh && go vet .claude/skills/archie-diagnostics-and-tooling/scripts/source-metrics.go && go vet .claude/skills/archie-diagnostics-and-tooling/scripts/config-use-candidates.go`
|
||||
|
||||
Re-verify source baseline: `GOCACHE=/tmp/archie-diagnostics-gocache GOTMPDIR=/tmp go run .claude/skills/archie-diagnostics-and-tooling/scripts/source-metrics.go -root . -top 12`
|
||||
|
||||
Re-verify config candidates: `GOCACHE=/tmp/archie-diagnostics-gocache GOTMPDIR=/tmp go run .claude/skills/archie-diagnostics-and-tooling/scripts/config-use-candidates.go -root .`
|
||||
|
||||
Re-verify package edges: `.claude/skills/archie-diagnostics-and-tooling/scripts/package-shape.sh .`
|
||||
|
||||
Re-verify delivery surfaces: `.claude/skills/archie-diagnostics-and-tooling/scripts/delivery-snapshot.sh`
|
||||
|
||||
Re-verify lint thresholds: `rg -n 'cyclop:|dupl:|funlen:|gocognit:|gocyclo:|maintidx:|nestif:' .golangci.yml`
|
||||
|
||||
Re-verify current test baseline: `GOCACHE=/tmp/archie-diagnostics-test-cache GOTMPDIR=/tmp GIT_CONFIG_GLOBAL=/dev/null GOPROXY=off GOFLAGS=-mod=readonly go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v`
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Archie Diagnostics and Tooling"
|
||||
short_description: "Measure maintainability, wiring, and delivery drift"
|
||||
default_prompt: "Use $archie-diagnostics-and-tooling to collect a dated, reproducible evidence baseline before changing Archie."
|
||||
+279
@@ -0,0 +1,279 @@
|
||||
// Command config-use-candidates reports syntax-level selector evidence for
|
||||
// tagged fields declared by internal/config. Results are candidates, not proof
|
||||
// that a field is wired, live, or dead.
|
||||
package main
|
||||
|
||||
import (
|
||||
"flag"
|
||||
"fmt"
|
||||
"go/ast"
|
||||
"go/parser"
|
||||
"go/token"
|
||||
"io/fs"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"reflect"
|
||||
"sort"
|
||||
"strconv"
|
||||
"strings"
|
||||
)
|
||||
|
||||
type fieldDefinition struct {
|
||||
path string
|
||||
line int
|
||||
typeName string
|
||||
fieldName string
|
||||
tags string
|
||||
duplicates int
|
||||
}
|
||||
|
||||
type referenceCounts struct {
|
||||
config int
|
||||
entrypoint int
|
||||
production int
|
||||
test int
|
||||
generated int
|
||||
}
|
||||
|
||||
func main() {
|
||||
root := flag.String("root", ".", "repository root to inspect")
|
||||
flag.Parse()
|
||||
|
||||
absoluteRoot, err := filepath.Abs(*root)
|
||||
if err != nil {
|
||||
fail(2, "resolve root: %v", err)
|
||||
}
|
||||
info, err := os.Stat(absoluteRoot)
|
||||
if err != nil {
|
||||
fail(2, "inspect root: %v", err)
|
||||
}
|
||||
if !info.IsDir() {
|
||||
fail(2, "root is not a directory: %s", absoluteRoot)
|
||||
}
|
||||
|
||||
fset := token.NewFileSet()
|
||||
fields, err := readFieldDefinitions(absoluteRoot, fset)
|
||||
if err != nil {
|
||||
fail(1, "%v", err)
|
||||
}
|
||||
if len(fields) == 0 {
|
||||
fail(1, "no tagged fields found under internal/config")
|
||||
}
|
||||
|
||||
nameCounts := map[string]int{}
|
||||
for _, field := range fields {
|
||||
nameCounts[field.fieldName]++
|
||||
}
|
||||
for index := range fields {
|
||||
fields[index].duplicates = nameCounts[fields[index].fieldName]
|
||||
}
|
||||
|
||||
references := map[string]*referenceCounts{}
|
||||
for name := range nameCounts {
|
||||
references[name] = &referenceCounts{}
|
||||
}
|
||||
if err := countSelectors(absoluteRoot, fset, references); err != nil {
|
||||
fail(1, "%v", err)
|
||||
}
|
||||
|
||||
sort.Slice(fields, func(i, j int) bool {
|
||||
if fields[i].typeName != fields[j].typeName {
|
||||
return fields[i].typeName < fields[j].typeName
|
||||
}
|
||||
if fields[i].fieldName != fields[j].fieldName {
|
||||
return fields[i].fieldName < fields[j].fieldName
|
||||
}
|
||||
if fields[i].path != fields[j].path {
|
||||
return fields[i].path < fields[j].path
|
||||
}
|
||||
return fields[i].line < fields[j].line
|
||||
})
|
||||
|
||||
fmt.Println("META\tschema\tarchie-config-use-candidates/v1")
|
||||
fmt.Println("META\tmeaning\tselector-name counts are heuristic candidates; confirm exact fields with gopls references and production composition")
|
||||
for _, field := range fields {
|
||||
count := references[field.fieldName]
|
||||
status := "candidate-selector-seen-in-entrypoint"
|
||||
switch {
|
||||
case count.production == 0 && count.entrypoint == 0:
|
||||
status = "candidate-no-selector-outside-config"
|
||||
case count.entrypoint == 0:
|
||||
status = "candidate-no-entrypoint-selector"
|
||||
}
|
||||
fmt.Printf(
|
||||
"CONFIG_FIELD\t%s\t%d\t%s.%s\t%s\t%d\t%d\t%d\t%d\t%d\t%d\t%s\n",
|
||||
field.path,
|
||||
field.line,
|
||||
field.typeName,
|
||||
field.fieldName,
|
||||
field.tags,
|
||||
field.duplicates,
|
||||
count.config,
|
||||
count.entrypoint,
|
||||
count.production,
|
||||
count.test,
|
||||
count.generated,
|
||||
status,
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
func readFieldDefinitions(root string, fset *token.FileSet) ([]fieldDefinition, error) {
|
||||
configDir := filepath.Join(root, "internal", "config")
|
||||
info, err := os.Stat(configDir)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("inspect internal/config: %w", err)
|
||||
}
|
||||
if !info.IsDir() {
|
||||
return nil, fmt.Errorf("internal/config is not a directory")
|
||||
}
|
||||
|
||||
var fields []fieldDefinition
|
||||
err = filepath.WalkDir(configDir, func(path string, entry fs.DirEntry, walkErr error) error {
|
||||
if walkErr != nil {
|
||||
return walkErr
|
||||
}
|
||||
if entry.IsDir() || filepath.Ext(entry.Name()) != ".go" || strings.HasSuffix(entry.Name(), "_test.go") {
|
||||
return nil
|
||||
}
|
||||
body, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
file, err := parser.ParseFile(fset, path, body, parser.ParseComments)
|
||||
if err != nil {
|
||||
return fmt.Errorf("parse %s: %w", path, err)
|
||||
}
|
||||
relative, err := filepath.Rel(root, path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
relative = filepath.ToSlash(relative)
|
||||
for _, declaration := range file.Decls {
|
||||
general, ok := declaration.(*ast.GenDecl)
|
||||
if !ok || general.Tok != token.TYPE {
|
||||
continue
|
||||
}
|
||||
for _, specification := range general.Specs {
|
||||
typeSpec, ok := specification.(*ast.TypeSpec)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
structType, ok := typeSpec.Type.(*ast.StructType)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
for _, field := range structType.Fields.List {
|
||||
tags, ok := configTags(field.Tag)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
for _, name := range field.Names {
|
||||
fields = append(fields, fieldDefinition{
|
||||
path: relative,
|
||||
line: fset.Position(name.Pos()).Line,
|
||||
typeName: typeSpec.Name.Name,
|
||||
fieldName: name.Name,
|
||||
tags: tags,
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return nil
|
||||
})
|
||||
return fields, err
|
||||
}
|
||||
|
||||
func configTags(literal *ast.BasicLit) (string, bool) {
|
||||
if literal == nil {
|
||||
return "", false
|
||||
}
|
||||
raw, err := strconv.Unquote(literal.Value)
|
||||
if err != nil {
|
||||
return "", false
|
||||
}
|
||||
tag := reflect.StructTag(raw)
|
||||
var parts []string
|
||||
for _, key := range []string{"toml", "yaml", "json"} {
|
||||
value, ok := tag.Lookup(key)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
parts = append(parts, key+"="+value)
|
||||
}
|
||||
return strings.Join(parts, ";"), len(parts) > 0
|
||||
}
|
||||
|
||||
func countSelectors(root string, fset *token.FileSet, references map[string]*referenceCounts) error {
|
||||
return filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
|
||||
if walkErr != nil {
|
||||
return walkErr
|
||||
}
|
||||
relative, err := filepath.Rel(root, path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
relative = filepath.ToSlash(relative)
|
||||
if entry.IsDir() {
|
||||
if relative != "." && excludedDirectory(relative, entry.Name()) {
|
||||
return filepath.SkipDir
|
||||
}
|
||||
return nil
|
||||
}
|
||||
if filepath.Ext(entry.Name()) != ".go" {
|
||||
return nil
|
||||
}
|
||||
body, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
file, err := parser.ParseFile(fset, path, body, parser.ParseComments)
|
||||
if err != nil {
|
||||
return fmt.Errorf("parse %s: %w", relative, err)
|
||||
}
|
||||
generated := ast.IsGenerated(file)
|
||||
isTest := strings.HasSuffix(entry.Name(), "_test.go")
|
||||
inConfig := strings.HasPrefix(relative, "internal/config/")
|
||||
inEntrypoint := strings.HasPrefix(relative, "cmd/")
|
||||
|
||||
ast.Inspect(file, func(node ast.Node) bool {
|
||||
selector, ok := node.(*ast.SelectorExpr)
|
||||
if !ok {
|
||||
return true
|
||||
}
|
||||
count := references[selector.Sel.Name]
|
||||
if count == nil {
|
||||
return true
|
||||
}
|
||||
switch {
|
||||
case generated:
|
||||
count.generated++
|
||||
case isTest:
|
||||
count.test++
|
||||
case inConfig:
|
||||
count.config++
|
||||
case inEntrypoint:
|
||||
count.entrypoint++
|
||||
default:
|
||||
count.production++
|
||||
}
|
||||
return true
|
||||
})
|
||||
return nil
|
||||
})
|
||||
}
|
||||
|
||||
func excludedDirectory(relative, name string) bool {
|
||||
switch name {
|
||||
case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp":
|
||||
return true
|
||||
}
|
||||
return strings.HasPrefix(relative, "docs-2/.vitepress/cache") ||
|
||||
strings.HasPrefix(relative, "docs-2/.vitepress/dist")
|
||||
}
|
||||
|
||||
func fail(code int, format string, arguments ...any) {
|
||||
fmt.Fprintf(os.Stderr, "config-use-candidates: "+format+"\n", arguments...)
|
||||
os.Exit(code)
|
||||
}
|
||||
@@ -0,0 +1,90 @@
|
||||
#!/bin/sh
|
||||
set -eu
|
||||
|
||||
if [ "$#" -ne 0 ]; then
|
||||
printf '%s\n' "usage: delivery-snapshot.sh" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
for tool in git rg sed wc; do
|
||||
command -v "$tool" >/dev/null 2>&1 || {
|
||||
printf 'delivery-snapshot: %s is required\n' "$tool" >&2
|
||||
exit 127
|
||||
}
|
||||
done
|
||||
|
||||
script_dir=$(CDPATH= cd "$(dirname "$0")" && pwd)
|
||||
repo_root=$(CDPATH= cd "$script_dir/../../../.." && pwd)
|
||||
if [ ! -f "$repo_root/go.mod" ] || [ ! -f "$repo_root/Taskfile.yml" ]; then
|
||||
printf 'delivery-snapshot: expected Archie repository root at %s\n' "$repo_root" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
temporary=$(mktemp -d "${TMPDIR:-/tmp}/archie-delivery-snapshot.XXXXXX")
|
||||
trap 'rm -rf "$temporary"' EXIT HUP INT TERM
|
||||
cd "$repo_root"
|
||||
|
||||
printf '%s\n' "META schema archie-delivery-snapshot/v1"
|
||||
|
||||
scan_literal() {
|
||||
axis=$1
|
||||
scope=$2
|
||||
pattern=$3
|
||||
shift 3
|
||||
result="$temporary/$axis"
|
||||
if rg -n --no-heading --color never -e "$pattern" "$@" >"$result"; then
|
||||
:
|
||||
else
|
||||
status=$?
|
||||
if [ "$status" -ne 1 ]; then
|
||||
printf 'delivery-snapshot: scan failed for %s\n' "$axis" >&2
|
||||
exit "$status"
|
||||
fi
|
||||
fi
|
||||
count=$(wc -l <"$result" | sed 's/[[:space:]]//g')
|
||||
printf 'SURFACE\t%s\t%s\t%s\n' "$axis" "$scope" "$count"
|
||||
}
|
||||
|
||||
scan_literal task_format taskfile 'gofumpt[[:space:]]+-w|go fix' Taskfile.yml
|
||||
scan_literal task_vet taskfile 'go vet' Taskfile.yml
|
||||
scan_literal task_build taskfile 'go build|task:[[:space:]]+build' Taskfile.yml
|
||||
scan_literal task_test taskfile 'go test|task:[[:space:]]+test' Taskfile.yml
|
||||
scan_literal task_lint taskfile 'golangci-lint|task:[[:space:]]+lint' Taskfile.yml
|
||||
scan_literal task_race taskfile 'go test[^#\n]*-race|-race[^#\n]*go test' Taskfile.yml
|
||||
scan_literal task_tools_module taskfile 'go -C tools|cd tools|task:[[:space:]]+tools' Taskfile.yml
|
||||
scan_literal task_docs taskfile 'docsgen|pnpm[^#\n]*build|docs:generate|docs:check' Taskfile.yml
|
||||
|
||||
scan_literal github_go_gate github-workflows 'go test|go vet|go build|golangci-lint|task[[:space:]]+check' .github/workflows
|
||||
scan_literal github_docs_build github-workflows 'pnpm[[:space:]]+build|vitepress[[:space:]]+build' .github/workflows
|
||||
scan_literal gitea_go_gate gitea-workflows 'go test|go vet|go build|golangci-lint|task[[:space:]]+check' .gitea/workflows
|
||||
scan_literal gitea_container_publish gitea-workflows 'docker build|docker push' .gitea/workflows
|
||||
|
||||
scan_literal production_load_overlay composition-root 'config\.LoadOverlay\(' cmd/archied/main.go
|
||||
scan_literal production_load_dir composition-root 'config\.LoadDir\(' cmd/archied/main.go
|
||||
scan_literal production_nell_store composition-root 'nell\.OpenStore\(' cmd/archied/main.go
|
||||
scan_literal production_daemon composition-root '&daemon\.Daemon\{' cmd/archied/main.go
|
||||
scan_literal production_rpc_servers composition-root 'registerTaskRPCServers\(' cmd/archied/main.go
|
||||
|
||||
git ls-files >"$temporary/tracked"
|
||||
tracked_total=$(wc -l <"$temporary/tracked" | sed 's/[[:space:]]//g')
|
||||
tracked_node_modules=$(rg -c '(^|/)node_modules(/|$)' "$temporary/tracked" || true)
|
||||
tracked_artifacts=$(rg -c '(^|/)(node_modules|bin|dist|\.gotmp)(/|$)|\.(exe|test|out)$' "$temporary/tracked" || true)
|
||||
tracked_symlinks=$(git ls-files -s | awk '$1 == "120000" {count++} END {print count + 0}')
|
||||
|
||||
printf 'HYGIENE\ttracked_paths\t%s\n' "$tracked_total"
|
||||
printf 'HYGIENE\ttracked_node_modules_paths\t%s\n' "${tracked_node_modules:-0}"
|
||||
printf 'HYGIENE\ttracked_artifact_candidates\t%s\n' "${tracked_artifacts:-0}"
|
||||
printf 'HYGIENE\ttracked_symlinks\t%s\n' "$tracked_symlinks"
|
||||
if [ -f .dockerignore ]; then
|
||||
printf '%s\n' "HYGIENE dockerignore_present 1"
|
||||
else
|
||||
printf '%s\n' "HYGIENE dockerignore_present 0"
|
||||
fi
|
||||
|
||||
find . \
|
||||
\( -path './.git' -o -path './.claude' -o -path './.references' -o -name node_modules \) -prune -o \
|
||||
-name go.mod -print |
|
||||
LC_ALL=C sort |
|
||||
while IFS= read -r module; do
|
||||
printf 'MODULE\t%s\n' "$module"
|
||||
done
|
||||
@@ -0,0 +1,86 @@
|
||||
#!/bin/sh
|
||||
set -eu
|
||||
|
||||
if [ "$#" -gt 1 ]; then
|
||||
printf '%s\n' "usage: $0 [module-directory-relative-to-repo]" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
command -v go >/dev/null 2>&1 || {
|
||||
printf '%s\n' "package-shape: go is required" >&2
|
||||
exit 127
|
||||
}
|
||||
command -v awk >/dev/null 2>&1 || {
|
||||
printf '%s\n' "package-shape: awk is required" >&2
|
||||
exit 127
|
||||
}
|
||||
|
||||
script_dir=$(CDPATH= cd "$(dirname "$0")" && pwd)
|
||||
repo_root=$(CDPATH= cd "$script_dir/../../../.." && pwd)
|
||||
module_relative=${1:-.}
|
||||
module_root="$repo_root/$module_relative"
|
||||
edge_helper="$repo_root/.claude/skills/archie-codebase-discovery/scripts/package-edges.sh"
|
||||
|
||||
if [ ! -f "$module_root/go.mod" ]; then
|
||||
printf 'package-shape: no go.mod at %s\n' "$module_root" >&2
|
||||
exit 2
|
||||
fi
|
||||
if [ ! -x "$edge_helper" ]; then
|
||||
printf 'package-shape: required sibling helper is missing or not executable: %s\n' "$edge_helper" >&2
|
||||
exit 2
|
||||
fi
|
||||
|
||||
temporary=$(mktemp -d "${TMPDIR:-/tmp}/archie-package-shape.XXXXXX")
|
||||
trap 'rm -rf "$temporary"' EXIT HUP INT TERM
|
||||
mkdir -p "$temporary/cache" "$temporary/build-tmp"
|
||||
|
||||
export GOCACHE="$temporary/cache"
|
||||
export GOTMPDIR="$temporary/build-tmp"
|
||||
export GOPROXY=off
|
||||
export GOFLAGS="-mod=readonly -buildvcs=false"
|
||||
export ARCHIE_DISCOVERY_CACHE="$temporary/discovery"
|
||||
|
||||
(
|
||||
cd "$module_root"
|
||||
go list ./... | LC_ALL=C sort
|
||||
) >"$temporary/packages"
|
||||
if (
|
||||
cd "$module_root"
|
||||
"$edge_helper" ./...
|
||||
) >"$temporary/edges" 2>"$temporary/edge-stderr"; then
|
||||
# The sibling helper sets its own GOFLAGS and can trigger a harmless,
|
||||
# nondeterministic temporary filename when GOMODCACHE is read-only.
|
||||
# Preserve the warning while normalizing only that filename suffix.
|
||||
sed 's/\.info[0-9][0-9]*\.tmp/.info<TEMP>.tmp/' "$temporary/edge-stderr" >&2
|
||||
else
|
||||
status=$?
|
||||
cat "$temporary/edge-stderr" >&2
|
||||
exit "$status"
|
||||
fi
|
||||
(
|
||||
cd "$module_root"
|
||||
go list -m -f '{{.Path}}'
|
||||
) >"$temporary/module"
|
||||
|
||||
module_path=$(sed -n '1p' "$temporary/module")
|
||||
printf '%s\n' "META schema archie-package-shape/v1"
|
||||
printf 'META\tmodule\t%s\n' "$module_path"
|
||||
|
||||
awk -F ' ' '
|
||||
NR == FNR {
|
||||
packages[$0] = 1
|
||||
next
|
||||
}
|
||||
{
|
||||
split($0, edge, " -> ")
|
||||
outbound[edge[1]]++
|
||||
inbound[edge[2]]++
|
||||
}
|
||||
END {
|
||||
for (packageName in packages) {
|
||||
printf "PACKAGE\t%s\t%d\t%d\n", packageName, inbound[packageName] + 0, outbound[packageName] + 0
|
||||
}
|
||||
}
|
||||
' "$temporary/packages" "$temporary/edges" | LC_ALL=C sort
|
||||
|
||||
awk '{printf "EDGE\t%s\n", $0}' "$temporary/edges"
|
||||
@@ -0,0 +1,352 @@
|
||||
// Command source-metrics emits deterministic, syntax-derived Go source metrics.
|
||||
// It never writes to the inspected tree and uses only the Go standard library.
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"flag"
|
||||
"fmt"
|
||||
"go/ast"
|
||||
"go/parser"
|
||||
"go/token"
|
||||
"io/fs"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"sort"
|
||||
"strings"
|
||||
)
|
||||
|
||||
type counts struct {
|
||||
productionFiles int
|
||||
testFiles int
|
||||
generatedFiles int
|
||||
productionLines int
|
||||
testLines int
|
||||
generatedLines int
|
||||
functions int
|
||||
methods int
|
||||
}
|
||||
|
||||
type packageCounts struct {
|
||||
module string
|
||||
path string
|
||||
productionFiles int
|
||||
testFiles int
|
||||
generatedFiles int
|
||||
productionLines int
|
||||
testLines int
|
||||
generatedLines int
|
||||
}
|
||||
|
||||
type hotspot struct {
|
||||
module string
|
||||
path string
|
||||
line int
|
||||
symbol string
|
||||
spanLines int
|
||||
statements int
|
||||
complexity int
|
||||
}
|
||||
|
||||
func main() {
|
||||
root := flag.String("root", ".", "repository root to inspect")
|
||||
top := flag.Int("top", 30, "maximum hotspot rows; zero means all")
|
||||
largeLines := flag.Int("large-lines", 80, "minimum body span for a hotspot")
|
||||
complexity := flag.Int("complexity", 15, "minimum approximate syntactic complexity for a hotspot")
|
||||
includeTests := flag.Bool("include-test-hotspots", false, "include test functions in hotspot rows")
|
||||
flag.Parse()
|
||||
|
||||
if *top < 0 || *largeLines < 1 || *complexity < 1 {
|
||||
fail(2, "top must be non-negative; thresholds must be positive")
|
||||
}
|
||||
|
||||
absoluteRoot, err := filepath.Abs(*root)
|
||||
if err != nil {
|
||||
fail(2, "resolve root: %v", err)
|
||||
}
|
||||
info, err := os.Stat(absoluteRoot)
|
||||
if err != nil {
|
||||
fail(2, "inspect root: %v", err)
|
||||
}
|
||||
if !info.IsDir() {
|
||||
fail(2, "root is not a directory: %s", absoluteRoot)
|
||||
}
|
||||
|
||||
modules := map[string]*counts{}
|
||||
packages := map[string]*packageCounts{}
|
||||
var hotspots []hotspot
|
||||
fset := token.NewFileSet()
|
||||
|
||||
err = filepath.WalkDir(absoluteRoot, func(path string, entry fs.DirEntry, walkErr error) error {
|
||||
if walkErr != nil {
|
||||
return walkErr
|
||||
}
|
||||
relative, err := filepath.Rel(absoluteRoot, path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
relative = filepath.ToSlash(relative)
|
||||
if entry.IsDir() {
|
||||
if relative != "." && excludedDirectory(relative, entry.Name()) {
|
||||
return filepath.SkipDir
|
||||
}
|
||||
return nil
|
||||
}
|
||||
if filepath.Ext(entry.Name()) != ".go" {
|
||||
return nil
|
||||
}
|
||||
|
||||
body, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
file, err := parser.ParseFile(fset, path, body, parser.ParseComments)
|
||||
if err != nil {
|
||||
return fmt.Errorf("parse %s: %w", relative, err)
|
||||
}
|
||||
|
||||
module := moduleFor(relative)
|
||||
moduleCounts := modules[module]
|
||||
if moduleCounts == nil {
|
||||
moduleCounts = &counts{}
|
||||
modules[module] = moduleCounts
|
||||
}
|
||||
dir := filepath.ToSlash(filepath.Dir(relative))
|
||||
packageKey := module + "\x00" + dir
|
||||
pkg := packages[packageKey]
|
||||
if pkg == nil {
|
||||
pkg = &packageCounts{module: module, path: dir}
|
||||
packages[packageKey] = pkg
|
||||
}
|
||||
|
||||
lines := physicalLines(body)
|
||||
generated := ast.IsGenerated(file)
|
||||
isTest := strings.HasSuffix(entry.Name(), "_test.go")
|
||||
switch {
|
||||
case generated:
|
||||
moduleCounts.generatedFiles++
|
||||
moduleCounts.generatedLines += lines
|
||||
pkg.generatedFiles++
|
||||
pkg.generatedLines += lines
|
||||
case isTest:
|
||||
moduleCounts.testFiles++
|
||||
moduleCounts.testLines += lines
|
||||
pkg.testFiles++
|
||||
pkg.testLines += lines
|
||||
default:
|
||||
moduleCounts.productionFiles++
|
||||
moduleCounts.productionLines += lines
|
||||
pkg.productionFiles++
|
||||
pkg.productionLines += lines
|
||||
}
|
||||
|
||||
for _, declaration := range file.Decls {
|
||||
function, ok := declaration.(*ast.FuncDecl)
|
||||
if !ok || function.Body == nil {
|
||||
continue
|
||||
}
|
||||
if function.Recv == nil {
|
||||
moduleCounts.functions++
|
||||
} else {
|
||||
moduleCounts.methods++
|
||||
}
|
||||
if generated || (isTest && !*includeTests) {
|
||||
continue
|
||||
}
|
||||
|
||||
start := fset.Position(function.Body.Lbrace).Line
|
||||
end := fset.Position(function.Body.Rbrace).Line
|
||||
row := hotspot{
|
||||
module: module,
|
||||
path: relative,
|
||||
line: fset.Position(function.Pos()).Line,
|
||||
symbol: symbolName(function),
|
||||
spanLines: end - start + 1,
|
||||
statements: statementNodes(function.Body),
|
||||
complexity: syntacticComplexity(function.Body),
|
||||
}
|
||||
if row.spanLines >= *largeLines || row.complexity >= *complexity {
|
||||
hotspots = append(hotspots, row)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
})
|
||||
if err != nil {
|
||||
fail(1, "%v", err)
|
||||
}
|
||||
|
||||
fmt.Println("META\tschema\tarchie-source-metrics/v1")
|
||||
fmt.Printf("META\tthresholds\tlarge_lines=%d;syntactic_complexity=%d;top=%d\n", *largeLines, *complexity, *top)
|
||||
|
||||
moduleNames := sortedKeys(modules)
|
||||
for _, module := range moduleNames {
|
||||
value := modules[module]
|
||||
emitMetric(module, "production_go_files", value.productionFiles)
|
||||
emitMetric(module, "test_go_files", value.testFiles)
|
||||
emitMetric(module, "generated_go_files", value.generatedFiles)
|
||||
emitMetric(module, "production_physical_lines", value.productionLines)
|
||||
emitMetric(module, "test_physical_lines", value.testLines)
|
||||
emitMetric(module, "generated_physical_lines", value.generatedLines)
|
||||
emitMetric(module, "functions", value.functions)
|
||||
emitMetric(module, "methods", value.methods)
|
||||
}
|
||||
|
||||
packageRows := make([]*packageCounts, 0, len(packages))
|
||||
for _, row := range packages {
|
||||
packageRows = append(packageRows, row)
|
||||
}
|
||||
sort.Slice(packageRows, func(i, j int) bool {
|
||||
if packageRows[i].module != packageRows[j].module {
|
||||
return packageRows[i].module < packageRows[j].module
|
||||
}
|
||||
return packageRows[i].path < packageRows[j].path
|
||||
})
|
||||
for _, row := range packageRows {
|
||||
fmt.Printf(
|
||||
"PACKAGE\t%s\t%s\t%d\t%d\t%d\t%d\t%d\t%d\n",
|
||||
row.module,
|
||||
row.path,
|
||||
row.productionFiles,
|
||||
row.testFiles,
|
||||
row.generatedFiles,
|
||||
row.productionLines,
|
||||
row.testLines,
|
||||
row.generatedLines,
|
||||
)
|
||||
}
|
||||
|
||||
sort.Slice(hotspots, func(i, j int) bool {
|
||||
if hotspots[i].spanLines != hotspots[j].spanLines {
|
||||
return hotspots[i].spanLines > hotspots[j].spanLines
|
||||
}
|
||||
if hotspots[i].complexity != hotspots[j].complexity {
|
||||
return hotspots[i].complexity > hotspots[j].complexity
|
||||
}
|
||||
if hotspots[i].path != hotspots[j].path {
|
||||
return hotspots[i].path < hotspots[j].path
|
||||
}
|
||||
if hotspots[i].line != hotspots[j].line {
|
||||
return hotspots[i].line < hotspots[j].line
|
||||
}
|
||||
return hotspots[i].symbol < hotspots[j].symbol
|
||||
})
|
||||
if *top > 0 && len(hotspots) > *top {
|
||||
hotspots = hotspots[:*top]
|
||||
}
|
||||
for _, row := range hotspots {
|
||||
fmt.Printf(
|
||||
"HOTSPOT\t%s\t%s\t%d\t%s\t%d\t%d\t%d\n",
|
||||
row.module,
|
||||
row.path,
|
||||
row.line,
|
||||
row.symbol,
|
||||
row.spanLines,
|
||||
row.statements,
|
||||
row.complexity,
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
func excludedDirectory(relative, name string) bool {
|
||||
switch name {
|
||||
case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp":
|
||||
return true
|
||||
}
|
||||
return strings.HasPrefix(relative, "docs-2/.vitepress/cache") ||
|
||||
strings.HasPrefix(relative, "docs-2/.vitepress/dist")
|
||||
}
|
||||
|
||||
func moduleFor(relative string) string {
|
||||
if relative == "tools" || strings.HasPrefix(relative, "tools/") {
|
||||
return "tools"
|
||||
}
|
||||
return "root"
|
||||
}
|
||||
|
||||
func physicalLines(body []byte) int {
|
||||
if len(body) == 0 {
|
||||
return 0
|
||||
}
|
||||
lines := bytes.Count(body, []byte{'\n'})
|
||||
if body[len(body)-1] != '\n' {
|
||||
lines++
|
||||
}
|
||||
return lines
|
||||
}
|
||||
|
||||
func symbolName(function *ast.FuncDecl) string {
|
||||
if function.Recv == nil || len(function.Recv.List) == 0 {
|
||||
return function.Name.Name
|
||||
}
|
||||
return receiverName(function.Recv.List[0].Type) + "." + function.Name.Name
|
||||
}
|
||||
|
||||
func receiverName(expression ast.Expr) string {
|
||||
switch value := expression.(type) {
|
||||
case *ast.Ident:
|
||||
return value.Name
|
||||
case *ast.StarExpr:
|
||||
return "*" + receiverName(value.X)
|
||||
case *ast.IndexExpr:
|
||||
return receiverName(value.X)
|
||||
case *ast.IndexListExpr:
|
||||
return receiverName(value.X)
|
||||
default:
|
||||
return "receiver"
|
||||
}
|
||||
}
|
||||
|
||||
func statementNodes(node ast.Node) int {
|
||||
count := 0
|
||||
ast.Inspect(node, func(candidate ast.Node) bool {
|
||||
statement, ok := candidate.(ast.Stmt)
|
||||
if !ok {
|
||||
return true
|
||||
}
|
||||
switch statement.(type) {
|
||||
case *ast.BlockStmt, *ast.EmptyStmt:
|
||||
default:
|
||||
count++
|
||||
}
|
||||
return true
|
||||
})
|
||||
return count
|
||||
}
|
||||
|
||||
func syntacticComplexity(node ast.Node) int {
|
||||
value := 1
|
||||
ast.Inspect(node, func(candidate ast.Node) bool {
|
||||
switch item := candidate.(type) {
|
||||
case *ast.IfStmt, *ast.ForStmt, *ast.RangeStmt, *ast.CommClause:
|
||||
value++
|
||||
case *ast.CaseClause:
|
||||
if len(item.List) > 0 {
|
||||
value++
|
||||
}
|
||||
case *ast.BinaryExpr:
|
||||
if item.Op == token.LAND || item.Op == token.LOR {
|
||||
value++
|
||||
}
|
||||
}
|
||||
return true
|
||||
})
|
||||
return value
|
||||
}
|
||||
|
||||
func sortedKeys(values map[string]*counts) []string {
|
||||
keys := make([]string, 0, len(values))
|
||||
for key := range values {
|
||||
keys = append(keys, key)
|
||||
}
|
||||
sort.Strings(keys)
|
||||
return keys
|
||||
}
|
||||
|
||||
func emitMetric(module, name string, value int) {
|
||||
fmt.Printf("METRIC\t%s\t%s\t%d\n", module, name, value)
|
||||
}
|
||||
|
||||
func fail(code int, format string, arguments ...any) {
|
||||
fmt.Fprintf(os.Stderr, "source-metrics: "+format+"\n", arguments...)
|
||||
os.Exit(code)
|
||||
}
|
||||
@@ -0,0 +1,350 @@
|
||||
---
|
||||
name: archie-docs-and-writing
|
||||
description: Maintain Archie's documentation of record and write durable architecture decisions, migration plans, parity matrices, incident and dead-end records, feature ownership and deprecation records, operational runbooks, and documentation reviews. Use when deciding where an Archie fact belongs; reconciling code with ARCHITECTURE.md, CLAUDE.md, docs/prds, docs/archive, generated contracts, or the docs-2 VitePress site; changing tools/docsgen; documenting a feature so future maintainers can find its owners, consumers, invariants, superseded paths, deletion gates, evidence, and rollback; or checking documentation authority, drift, links, copied content, and source-artifact hygiene.
|
||||
---
|
||||
|
||||
# Maintain Archie documentation
|
||||
|
||||
Write one durable record for each decision or behavior. Separate what runs now
|
||||
from what Archie has approved as its destination. Make a future feature change
|
||||
possible without rediscovering every code path.
|
||||
|
||||
## Route work before writing
|
||||
|
||||
Do not use this skill to make the underlying decision, investigate an incident,
|
||||
or certify a code change:
|
||||
|
||||
| Need | Load instead |
|
||||
|---|---|
|
||||
| Decide package ownership, boundaries, or migration order | `archie-architecture-planning-campaign` |
|
||||
| Check a load-bearing invariant | `archie-architecture-contract` |
|
||||
| Map live entry points, consumers, and call paths | `archie-codebase-discovery` |
|
||||
| Establish feature ownership, supersession, or deletion accountability | `archie-technical-accountability` |
|
||||
| Reconstruct an incident, revert, or rejected fix | `archie-failure-archaeology` |
|
||||
| Change configuration, build, deployment, or operations | `archie-config-and-flags`, `archie-build-and-env`, or `archie-run-and-operate` |
|
||||
| Gate or accept a change | `archie-change-control` and `archie-validation-and-qa` |
|
||||
| Turn an unproven hypothesis into evidence | `archie-research-methodology` |
|
||||
|
||||
Return here after those skills establish the facts or decision. Record their
|
||||
result without broadening it.
|
||||
|
||||
## Use the authority vocabulary
|
||||
|
||||
Define a **record of authority** as the one canonical location whose owner may
|
||||
change a claim. Label every material statement with one of these states:
|
||||
|
||||
| State | Meaning | Permitted wording |
|
||||
|---|---|---|
|
||||
| `CURRENT` | Verified behavior in the checked-out code, tests, composition, or executable config | “Currently does” |
|
||||
| `APPROVED TARGET` | Normative destination approved in the architecture index | “Must become”; never “currently does” |
|
||||
| `OPEN` | Investigation, candidate, or unresolved decision | “Candidate”, “unknown”, or “requires decision” |
|
||||
| `HISTORICAL` | Prior design, incident, dead end, or superseded choice | “Previously did”; never normative |
|
||||
| `GENERATED` | Derivative output produced from an owned source definition | “Generated from”; never hand-edit |
|
||||
| `EXTERNAL` | Fact held outside this repository, such as deployed config or host state | Date, name the verifier, and give a re-check command |
|
||||
|
||||
When `CURRENT` conflicts with `APPROVED TARGET`, preserve both and state the
|
||||
migration delta. Do not rewrite the target to match accidental code. Do not
|
||||
describe target behavior as implemented merely because a PRD uses normative
|
||||
language.
|
||||
|
||||
## Use the repository authority map
|
||||
|
||||
Treat this as a volatile map verified on 2026-07-28:
|
||||
|
||||
| Location | Role | Discipline |
|
||||
|---|---|---|
|
||||
| Live Go code, tests, `Taskfile.yml`, executable config parsing, and composition under `cmd/` | `CURRENT` execution evidence | Trace producers and consumers; tests prove only their asserted behavior |
|
||||
| `CLAUDE.md` | Current contributor and safety protocol plus a compact architecture orientation | Verify operational claims against code and `Taskfile.yml`; `AGENTS.md` is a symlink to this file |
|
||||
| `ARCHITECTURE.md` | Useful architecture history and partial current overview | Corroborate every inventory/status claim; its “Planned” list is stale for implemented skill support |
|
||||
| `docs/prds/01-project-management.md` | Index and approved foundation for the target architecture | Add or change target decisions in the focused document it names |
|
||||
| `docs/prds/architecture/*.md` | Focused target decisions, active review procedure, and migration inventory | Read each file's status; distinguish fixed decisions from explicitly remaining decisions |
|
||||
| `docs/prds/architecture/migration-decisions.md` | `OPEN` migration inventory constrained by approved decisions | Close a question only after code-grounded review and an approved record |
|
||||
| `docs/archive/` | `HISTORICAL` material | Mine rationale and failure evidence; never restore authority from a title such as “Final” |
|
||||
| `CHANGELOG.md`, `CHANGELOG.archied.md`, `CHANGELOG.archie.md` | Component release-note index and packaged runtime inputs | Keep gateway and agent-runtime entries separate; `internal/releaseannounce` parses the version headings |
|
||||
| `tools/docsgen` | Current, partial generator implementation in the nested `tools` Go module | Treat its flags and tests—not planned PRD commands—as executable truth |
|
||||
| `docs-2/data/generated/contracts.json` | Current working-tree `GENERATED` output | Regenerate; never edit by hand; re-check whether it is tracked |
|
||||
| `docs-2/` | Staging VitePress site | Do not treat a rendered summary as the architecture record |
|
||||
| `.github/workflows/docs.yml` | Current Pages build/deploy workflow | It builds the site; it does not currently run Go setup, generator tests, or drift checking |
|
||||
|
||||
The repository root has no `README.md` or `CONTRIBUTING.md` as of 2026-07-28.
|
||||
Record this as an onboarding coverage gap, not permission to invent a new
|
||||
authority. `docs-2/README.md` is excluded by VitePress and still contains copied
|
||||
Tau material; it is not a root onboarding guide.
|
||||
|
||||
## Choose one destination
|
||||
|
||||
1. State the reader's question in one sentence.
|
||||
2. Identify the owner of the behavior or decision.
|
||||
3. Find the existing record of authority.
|
||||
4. Extend that record or link to it. Do not make a second canonical table.
|
||||
5. If no owner exists, stop and route the ownership decision through
|
||||
`archie-technical-accountability` or the architecture campaign.
|
||||
6. If the fact is generated, change the owned source definition and generator;
|
||||
do not patch output.
|
||||
7. If the fact is external, date it and name the exact observation command.
|
||||
|
||||
Use this placement guide:
|
||||
|
||||
| Content | Destination |
|
||||
|---|---|
|
||||
| Cross-cutting approved architecture index | `docs/prds/01-project-management.md` |
|
||||
| Focused domain or requirement decision | The matching `docs/prds/architecture/*.md` file |
|
||||
| Unresolved migration question or cutover requirement | `docs/prds/architecture/migration-decisions.md` |
|
||||
| Contributor protocol that must load before work | `CLAUDE.md` |
|
||||
| Runtime/API/config reference derivable from code | Domain-owned registry/type, then `tools/docsgen` output |
|
||||
| User-facing staging site prose | `docs-2/`, linking back to its authority |
|
||||
| Shipped release behavior | The matching component changelog; keep `CHANGELOG.md` as the two-component index |
|
||||
| Superseded design retained only for context | `docs/archive/`, with historical status |
|
||||
| Incident or rejected approach | `archie-failure-archaeology`'s authoritative chronology |
|
||||
|
||||
Do not duplicate a package map in `CLAUDE.md`, `ARCHITECTURE.md`, a PRD, and the
|
||||
site. Name the authoritative map and link to it.
|
||||
|
||||
## Research before drafting
|
||||
|
||||
Run from the repository root:
|
||||
|
||||
```bash
|
||||
rg -n 'ExactTerm|RelatedTerm' --glob '*.go' --glob '*.md' --glob '*.toml' --glob '*.yml'
|
||||
rg -n 'type ExactType|func .*ExactMethod|ExactConfigField' cmd internal domain tools
|
||||
rg -n 'ExactType|ExactMethod' --glob '*_test.go'
|
||||
rg -n 'ExactTerm' docs/prds ARCHITECTURE.md CLAUDE.md docs/archive docs-2
|
||||
```
|
||||
|
||||
Then build a fact ledger:
|
||||
|
||||
| Claim | State | Owner | Evidence | Conflicts | Destination |
|
||||
|---|---|---|---|---|---|
|
||||
| One precise claim | `CURRENT` / `APPROVED TARGET` / `OPEN` | Domain or boundary | `path` + symbol/test/heading | Other path or none | Existing authority |
|
||||
|
||||
Investigate entry points, runtime composition, persistence, configuration,
|
||||
consumers, tests, failure behavior, duplicate implementations, and stale docs.
|
||||
Do not ask the user a question that repository evidence can answer.
|
||||
|
||||
## Write for future change
|
||||
|
||||
Every architecture, feature, or migration record must answer:
|
||||
|
||||
- **Responsibility:** What cohesive job exists?
|
||||
- **Owner:** Which domain, application boundary, or infrastructure adapter owns
|
||||
its meaning and mutable state?
|
||||
- **Boundaries:** What is explicitly inside and outside?
|
||||
- **Consumers:** Which entry points, interfaces, commands, events, config, and
|
||||
processes depend on it?
|
||||
- **Invariants:** What must remain true, and where is each invariant enforced?
|
||||
- **Superseded path:** Which older mechanism becomes redundant?
|
||||
- **Deletion gate:** What observable proof permits removal, and what temporary
|
||||
compatibility has an expiry condition?
|
||||
- **Evidence:** Which symbols, tests, commands, and runtime observations support
|
||||
the record?
|
||||
- **Rollback:** How can behavior and data return safely?
|
||||
- **Unresolved questions:** What remains `OPEN`, who owns the decision, and what
|
||||
evidence will close it?
|
||||
|
||||
Name one owner for every mutable record. Name every current code path that
|
||||
performs the same operation. A new path is incomplete until the document says
|
||||
whether each older path remains, delegates, migrates, or is deleted.
|
||||
|
||||
Use [references/templates.md](references/templates.md) when drafting an ADR,
|
||||
migration/parity plan, incident/dead-end record, feature ownership/deprecation
|
||||
record, operational runbook, or docs review. Copy only the matching template;
|
||||
delete prompts that do not apply rather than filling them with ceremony.
|
||||
|
||||
## Cite evidence without freezing line numbers
|
||||
|
||||
Prefer:
|
||||
|
||||
- repository-relative path plus exact Go symbol, test name, config key, workflow
|
||||
job/step, or Markdown heading;
|
||||
- a relative Markdown link to the record of authority;
|
||||
- the command that re-discovers the evidence.
|
||||
|
||||
Write `internal/agentexec.Request` and `tools/docsgen.currentContractTypes`, for
|
||||
example. Avoid permanent `file.go:123` citations: line numbers drift without
|
||||
changing meaning. Use line numbers in a time-bounded review comment only.
|
||||
|
||||
Distinguish evidence strength:
|
||||
|
||||
1. Runtime composition and executable behavior.
|
||||
2. Tests that exercise the relevant production seam.
|
||||
3. Approved target decision.
|
||||
4. Comments and summaries corroborated by the first three.
|
||||
5. Historical or external notes, explicitly dated.
|
||||
|
||||
## Maintain component changelogs
|
||||
|
||||
Keep gateway behavior in `CHANGELOG.archied.md` and agent-runtime behavior in
|
||||
`CHANGELOG.archie.md`; keep `CHANGELOG.md` as their index. The archied image
|
||||
copies both component files to `/usr/share/archie/`, and
|
||||
`internal/releaseannounce.changelogSection` parses a version heading to build
|
||||
Telegram update messages.
|
||||
|
||||
Do not copy the current heading format without investigation. A verified
|
||||
2026-07-28 contradiction is `OPEN`:
|
||||
|
||||
- `.gitea/workflows/deploy.yml` passes `vX.Y.Z` component versions.
|
||||
- `changelogSection` searches for `## [<version>]`, and its fixtures use
|
||||
`## [v0.1.0]`.
|
||||
- The two current component changelogs use headings such as `## [1.1.0]`
|
||||
without `v`.
|
||||
- `cmd/archied.TestChangelogsTrackGatewayAndRuntimeIndependently` explicitly
|
||||
expects the unprefixed current heading.
|
||||
|
||||
Resolve the parser, release metadata tests, and both documents atomically
|
||||
through `archie-change-control`; do not “fix” only the prose. Until resolved,
|
||||
do not claim that a current component entry is parseable by the deployed
|
||||
release announcer.
|
||||
|
||||
## Maintain generated contracts
|
||||
|
||||
The current implementation is smaller than the approved target in
|
||||
`docs/prds/architecture/generated-documentation.md`.
|
||||
|
||||
### Current behavior, verified 2026-07-28
|
||||
|
||||
- The tool path is `tools/docsgen`, not `tools/cmd/docsgen`.
|
||||
- It is a separate Go module that replaces the root module with `../`.
|
||||
- It accepts `--repo-root` and `--out`; it has no implemented `data`,
|
||||
`asyncapi`, `all`, or `check` subcommands.
|
||||
- `currentContractTypes` explicitly publishes three top-level contracts and
|
||||
collects their referenced schemas into one JSON object.
|
||||
- Its default output is `docs-2/data/generated/contracts.json`.
|
||||
- The current test proves byte-identical repeated output, expected top-level
|
||||
contracts, resolvable local references, duplicate/conflict rejection, and
|
||||
filesystem/source error reporting.
|
||||
- The output in this working tree matches a fresh temporary generation, but
|
||||
`git ls-files` reports it as untracked. Re-check before relying on it in CI.
|
||||
|
||||
Test and compare without changing the repository:
|
||||
|
||||
```bash
|
||||
GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools test ./docsgen -count=1
|
||||
docs_tmp="$(mktemp /tmp/archie-contracts.XXXXXX.json)"
|
||||
GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools run ./docsgen --repo-root .. --out "$docs_tmp"
|
||||
cmp "$docs_tmp" docs-2/data/generated/contracts.json
|
||||
```
|
||||
|
||||
Exit status `0` from `cmp` means the one current output matches. This is not a
|
||||
complete obsolete-file, site-route, or target-registry drift check.
|
||||
|
||||
Regenerate the working-tree output only when the change is classified and
|
||||
authorized:
|
||||
|
||||
```bash
|
||||
GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools run ./docsgen --repo-root ..
|
||||
```
|
||||
|
||||
Treat the PRD's `docsgen all`, `docsgen check`, and `task docs:*` commands as
|
||||
`APPROVED TARGET`. Do not run or document them as current until their CLI and
|
||||
Taskfile entries exist and tests prove them.
|
||||
|
||||
## Maintain the VitePress staging site
|
||||
|
||||
Current behavior, verified 2026-07-28:
|
||||
|
||||
| Surface | Current state |
|
||||
|---|---|
|
||||
| Package | `docs-2/package.json`; VitePress `^1.6.4`; pnpm lockfile resolves 1.6.4 |
|
||||
| Site config | Archie title, local search, clean URLs, last-updated metadata, output at `.vitepress/dist` |
|
||||
| Published prose | Handwritten home and architecture pages; no generated-data loader is present |
|
||||
| Copied content | `docs-2/README.md` describes Tau and is excluded by `srcExclude` |
|
||||
| Workflow | Frozen-lockfile install, `pnpm build`, Pages artifact upload/deploy |
|
||||
| Versioning | pnpm major `10`; Node is `latest`, so the Node input is volatile |
|
||||
| Missing gates | No Go setup, docsgen test, generator drift check, or root `task check` integration |
|
||||
|
||||
Run the implemented site commands for review and acceptance:
|
||||
|
||||
```bash
|
||||
pnpm --dir docs-2 install --frozen-lockfile
|
||||
pnpm --dir docs-2 build
|
||||
```
|
||||
|
||||
Use `build` for review evidence.
|
||||
|
||||
### Interactive authoring (not for automated acceptance)
|
||||
|
||||
```bash
|
||||
pnpm --dir docs-2 dev
|
||||
```
|
||||
|
||||
This starts a long-running dev server at `http://localhost:5173` (by default).
|
||||
Only use it for interactive authoring; stop it with `Ctrl-C` before proceeding.
|
||||
It is not an acceptance gate. Record the exact pnpm and Node
|
||||
versions in failure reports because CI currently permits version drift.
|
||||
|
||||
### Enforce source-artifact hygiene
|
||||
|
||||
As of 2026-07-28, Git tracks 237 `docs-2/node_modules` symlink entries.
|
||||
Neither `docs-2/node_modules` nor `docs-2/.vitepress/dist` is ignored by the
|
||||
root `.gitignore`. Treat cleanup and ignore changes as a classified repository
|
||||
change; route them through `archie-change-control`.
|
||||
|
||||
Before review, inspect rather than assuming:
|
||||
|
||||
```bash
|
||||
git ls-files -s 'docs-2/node_modules/**' | awk '$1 == 120000 { count++ } END { print count + 0 }'
|
||||
git ls-files 'docs-2/.vitepress/dist/**'
|
||||
git check-ignore -v docs-2/node_modules docs-2/.vitepress/dist || true
|
||||
rg -n -i 'tau|template|placeholder' docs-2 --glob '!node_modules/**'
|
||||
```
|
||||
|
||||
Never stage dependency installs, VitePress output, generator scratch files,
|
||||
credentials, absolute paths, wall-clock data, or machine-specific values.
|
||||
|
||||
## Review a documentation change
|
||||
|
||||
Require all of the following:
|
||||
|
||||
- [ ] The document names its state, date, scope, owner, and record of authority.
|
||||
- [ ] `CURRENT`, `APPROVED TARGET`, `OPEN`, `HISTORICAL`, `GENERATED`, and
|
||||
`EXTERNAL` claims are not blended.
|
||||
- [ ] Every code claim has a path plus symbol, test, config key, or workflow
|
||||
step that can be re-discovered.
|
||||
- [ ] The writer traced consumers and runtime composition, not just type
|
||||
declarations.
|
||||
- [ ] The document states boundaries, invariants, superseded paths, deletion
|
||||
gates, evidence, rollback, and unresolved questions where applicable.
|
||||
- [ ] No authoritative table or definition is copied from another owner.
|
||||
- [ ] Generated files were regenerated, not hand-edited.
|
||||
- [ ] Release notes use the correct component file, and release metadata,
|
||||
parser behavior, tests, and version headings agree.
|
||||
- [ ] Generator tests and a non-mutating drift comparison pass.
|
||||
- [ ] `pnpm --dir docs-2 build` passes for site changes.
|
||||
- [ ] Copied product text and tracked build/dependency artifacts are absent from
|
||||
the intended change.
|
||||
- [ ] Behavior-changing decisions passed `archie-change-control` and
|
||||
`archie-validation-and-qa`.
|
||||
|
||||
Reject “the code is self-explanatory,” “temporary compatibility” without a
|
||||
deletion gate, and status-free future tense. A durable record must let a new
|
||||
engineer determine what exists, what should replace it, and how to prove the
|
||||
transition.
|
||||
|
||||
## Provenance and maintenance
|
||||
|
||||
Last verified against the checked-out repository on 2026-07-28. Re-run these
|
||||
one-line checks before relying on volatile facts:
|
||||
|
||||
```bash
|
||||
test -L AGENTS.md && readlink AGENTS.md && test ! -e README.md && test ! -e CONTRIBUTING.md
|
||||
```
|
||||
|
||||
```bash
|
||||
rg -n '^\\*\\*Status:\\*\\*|^# ' docs/prds/01-project-management.md docs/prds/architecture/*.md docs/archive/*.md
|
||||
```
|
||||
|
||||
```bash
|
||||
rg -n 'docsgen|docs:|pnpm|vitepress|CHANGELOG' Taskfile.yml .github/workflows/docs.yml tools/docsgen docs-2/package.json docs-2/.vitepress/config.mts Dockerfile.archied internal/releaseannounce cmd/archied
|
||||
```
|
||||
|
||||
```bash
|
||||
GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools test ./docsgen -count=1
|
||||
```
|
||||
|
||||
```bash
|
||||
docs_tmp="$(mktemp /tmp/archie-contracts.XXXXXX.json)"; GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools run ./docsgen --repo-root .. --out "$docs_tmp" && cmp "$docs_tmp" docs-2/data/generated/contracts.json
|
||||
```
|
||||
|
||||
```bash
|
||||
git status --short -- docs-2 tools docs/prds/architecture/generated-documentation.md .github/workflows/docs.yml; git ls-files -s 'docs-2/node_modules/**' | awk '$1 == 120000 { count++ } END { print count + 0 }'
|
||||
```
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Archie Docs and Writing"
|
||||
short_description: "Maintain authoritative Archie documentation"
|
||||
default_prompt: "Use $archie-docs-and-writing to write or update an authoritative Archie design, migration, incident, ownership, or operations document."
|
||||
@@ -0,0 +1,364 @@
|
||||
# Archie durable-writing templates
|
||||
|
||||
Use one template at a time. Replace every angle-bracket prompt. Remove unused
|
||||
sections. Keep facts, decisions, and open questions visibly separate.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Architecture decision record](#architecture-decision-record)
|
||||
- [Migration plan and parity matrix](#migration-plan-and-parity-matrix)
|
||||
- [Incident or dead-end record](#incident-or-dead-end-record)
|
||||
- [Feature ownership and deprecation record](#feature-ownership-and-deprecation-record)
|
||||
- [Operational runbook](#operational-runbook)
|
||||
- [Documentation change review](#documentation-change-review)
|
||||
|
||||
## Architecture decision record
|
||||
|
||||
````markdown
|
||||
# <Decision title>
|
||||
|
||||
**Status:** Proposed | Approved | Superseded by <link>
|
||||
**Date:** YYYY-MM-DD
|
||||
**Owner:** <domain or application boundary>
|
||||
**Record of authority:** <this document or existing focused document>
|
||||
**Change-control reference:** <issue/review identifier>
|
||||
|
||||
## Decision
|
||||
|
||||
<One unambiguous normative statement.>
|
||||
|
||||
## Problem and scope
|
||||
|
||||
<Describe the problem, the included behavior, and explicit non-goals.>
|
||||
|
||||
## Current evidence
|
||||
|
||||
| Claim | Evidence |
|
||||
|---|---|
|
||||
| <CURRENT behavior> | `<path>` — `<symbol/test/config key>` |
|
||||
|
||||
## Constraints and invariants
|
||||
|
||||
- <Invariant and where it is enforced>
|
||||
|
||||
## Consumers and boundaries
|
||||
|
||||
| Consumer | Contract used | Failure effect |
|
||||
|---|---|---|
|
||||
| <entry point/package/process> | <interface/command/event/data> | <effect> |
|
||||
|
||||
## Options considered
|
||||
|
||||
| Option | Benefits | Costs and risks | Evidence | Result |
|
||||
|---|---|---|---|---|
|
||||
| <option> | <benefit> | <cost> | <measurement/source> | Accepted / Rejected |
|
||||
|
||||
## Consequences
|
||||
|
||||
<State new responsibilities, dependency direction, state ownership, and
|
||||
operational effects.>
|
||||
|
||||
## Supersession and deletion
|
||||
|
||||
- Superseded path: `<path/symbol>` or none
|
||||
- Compatibility owner: <owner or none>
|
||||
- Deletion gate: <observable proof>
|
||||
- Architecture test: <test or OPEN>
|
||||
|
||||
## Rollback
|
||||
|
||||
<State how code, behavior, and data return safely.>
|
||||
|
||||
## Open questions
|
||||
|
||||
| Question | Owner | Evidence required | Decision deadline/gate |
|
||||
|---|---|---|---|
|
||||
| <OPEN question> | <owner> | <measurement> | <gate> |
|
||||
|
||||
## Validation
|
||||
|
||||
- `<exact command>` — expected <observable result>
|
||||
````
|
||||
|
||||
## Migration plan and parity matrix
|
||||
|
||||
````markdown
|
||||
# <Capability> migration plan
|
||||
|
||||
**Status:** Proposed | Approved | In progress | Complete
|
||||
**Date:** YYYY-MM-DD
|
||||
**Owner:** <domain>
|
||||
**Source authority:** <approved target decision>
|
||||
**Current baseline:** <code paths and runtime composition>
|
||||
|
||||
## Outcome
|
||||
|
||||
<Describe the final single authoritative path and what becomes easier to
|
||||
change.>
|
||||
|
||||
## Current-path inventory
|
||||
|
||||
| Operation | Entry point | Owner today | State/data touched | Consumers | Disposition |
|
||||
|---|---|---|---|---|---|
|
||||
| <operation> | `<path.Symbol>` | <owner/none> | <state> | <consumers> | Keep / Adapt / Merge / Delete |
|
||||
|
||||
## Parity matrix
|
||||
|
||||
| Behavior | Current evidence | Target owner/path | Required parity | Test or observation | Status |
|
||||
|---|---|---|---|---|---|
|
||||
| <behavior> | `<test/symbol/log>` | <target> | <exact result> | `<command>` | OPEN |
|
||||
|
||||
Include success, validation failure, retry, cancellation, crash recovery,
|
||||
authorization, persistence, event emission, and shutdown where applicable.
|
||||
|
||||
## Dependency and data movement
|
||||
|
||||
| From | To | Adapter/backfill | Consistency rule | Rollback |
|
||||
|---|---|---|---|---|
|
||||
| <source> | <target> | <mechanism> | <invariant> | <method> |
|
||||
|
||||
## Slices and gates
|
||||
|
||||
### Slice 1 — <small vertical outcome>
|
||||
|
||||
- Change: <bounded change>
|
||||
- Expected evidence: <number/result predicted before implementation>
|
||||
- Command: `<exact command>`
|
||||
- Pass: <observable result>
|
||||
- Branch if not: <diagnostic route>
|
||||
- Legacy path after slice: Active / Delegating / Read-only / Removable
|
||||
|
||||
<Repeat for each independently reviewable slice.>
|
||||
|
||||
## Cutover
|
||||
|
||||
1. <Prepare compatibility/data>
|
||||
2. <Change production composition>
|
||||
3. <Observe explicit health/parity signals>
|
||||
4. <Disable legacy entry>
|
||||
5. <Delete only after the deletion gate>
|
||||
|
||||
## Deletion gates
|
||||
|
||||
| Legacy path | Replacement proof | Consumer-zero proof | Data proof | Removal test |
|
||||
|---|---|---|---|---|
|
||||
| `<path.Symbol>` | <proof> | <search/inventory> | <proof> | `<command>` |
|
||||
|
||||
## Rollback and stop conditions
|
||||
|
||||
- Roll back when: <condition>
|
||||
- Restore: <code/config/data sequence>
|
||||
- Preserve for diagnosis: <artifacts>
|
||||
|
||||
## Remaining open decisions
|
||||
|
||||
| Decision | Owner | Evidence needed | Blocks |
|
||||
|---|---|---|---|
|
||||
| <OPEN> | <owner> | <evidence> | <slice/cutover> |
|
||||
````
|
||||
|
||||
## Incident or dead-end record
|
||||
|
||||
````markdown
|
||||
# <Symptom or rejected approach>
|
||||
|
||||
**Status:** Resolved | Mitigated | Rejected | Reopened
|
||||
**Observed:** YYYY-MM-DD
|
||||
**Last verified:** YYYY-MM-DD
|
||||
**Owner:** <capability>
|
||||
**Related changes:** <commit/issue/PR identifiers>
|
||||
|
||||
## Symptom and impact
|
||||
|
||||
<State the observable failure, affected path, and cost. Do not begin with the
|
||||
proposed fix.>
|
||||
|
||||
## Reproduction
|
||||
|
||||
```text
|
||||
<exact non-secret command or event sequence>
|
||||
```
|
||||
|
||||
Expected: <result>
|
||||
Observed: <result>
|
||||
|
||||
## Investigation chronology
|
||||
|
||||
| Time/order | Hypothesis | Prediction | Evidence | Result |
|
||||
|---|---|---|---|---|
|
||||
| 1 | <hypothesis> | <expected observation> | `<command/log/test>` | Confirmed / Rejected |
|
||||
|
||||
## Root cause
|
||||
|
||||
<Name the owning code path and causal mechanism. Separate cause from trigger.>
|
||||
|
||||
## Attempted or rejected fixes
|
||||
|
||||
| Fix | Why plausible | Evidence against it | Status |
|
||||
|---|---|---|---|
|
||||
| <approach> | <reason> | <test/runtime evidence> | Rejected / Reverted |
|
||||
|
||||
## Resolution and invariant
|
||||
|
||||
- Resolution: <what changed>
|
||||
- Preserved invariant: <what must not regress>
|
||||
- Regression test: `<test name/path>`
|
||||
- Operational signal: <log/metric/state>
|
||||
|
||||
## Reopen condition
|
||||
|
||||
<State the evidence that would justify revisiting the settled result.>
|
||||
````
|
||||
|
||||
## Feature ownership and deprecation record
|
||||
|
||||
````markdown
|
||||
# <Feature/capability> ownership
|
||||
|
||||
**Status:** Current | Migrating | Deprecated | Removed
|
||||
**Date:** YYYY-MM-DD
|
||||
**Behavior owner:** <domain>
|
||||
**State owner:** <domain/repository>
|
||||
**Composition owner:** <application boundary>
|
||||
|
||||
## Responsibility and non-responsibilities
|
||||
|
||||
- Owns: <cohesive behavior>
|
||||
- Does not own: <adjacent concerns>
|
||||
|
||||
## Complete path
|
||||
|
||||
| Layer | Path/symbol | Responsibility |
|
||||
|---|---|---|
|
||||
| Entry | `<path.Symbol>` | <role> |
|
||||
| Domain | `<path.Symbol>` | <role> |
|
||||
| State | `<path.Symbol>` | <role> |
|
||||
| Adapter | `<path.Symbol>` | <role> |
|
||||
| Composition | `<path.Symbol>` | <role> |
|
||||
|
||||
## Consumers
|
||||
|
||||
| Consumer | Contract | Configuration | Test evidence |
|
||||
|---|---|---|---|
|
||||
| <consumer> | <interface/event/data> | <key or none> | `<test>` |
|
||||
|
||||
## Invariants and failures
|
||||
|
||||
| Invariant | Enforcement | Failure behavior | Test |
|
||||
|---|---|---|---|
|
||||
| <invariant> | `<path.Symbol>` | <result> | `<test>` |
|
||||
|
||||
## Duplicate and superseded paths
|
||||
|
||||
| Path | Same operation? | Disposition | Deletion gate |
|
||||
|---|---|---|---|
|
||||
| `<path.Symbol>` | Yes / No, because <reason> | Keep / Delegate / Migrate / Delete | <proof> |
|
||||
|
||||
## Change checklist
|
||||
|
||||
- [ ] Trace every entry point and consumer.
|
||||
- [ ] Decide whether the feature deprecates earlier work.
|
||||
- [ ] Keep one owner for mutable state.
|
||||
- [ ] Add failure-path and architecture tests.
|
||||
- [ ] Prove the replacement before deleting the old path.
|
||||
- [ ] Update generated reference from owned definitions.
|
||||
````
|
||||
|
||||
## Operational runbook
|
||||
|
||||
````markdown
|
||||
# Operate <service/capability>
|
||||
|
||||
**Status:** Current
|
||||
**Last verified:** YYYY-MM-DD
|
||||
**Environment:** <local/staging/production>
|
||||
**Owner:** <operator/capability>
|
||||
**External sources:** <host/config/dashboard; no secrets>
|
||||
|
||||
## Purpose and safety boundary
|
||||
|
||||
<State what this runbook operates and what requires separate authorization.>
|
||||
|
||||
## Preconditions
|
||||
|
||||
- <access/tool/config precondition>
|
||||
- Secret names only; never secret values
|
||||
|
||||
## Start or change
|
||||
|
||||
1. Run `<exact command>`.
|
||||
2. Expect `<observable output/state>` within `<bounded interval>`.
|
||||
3. If `<alternate result>`, stop and route to `<diagnostic branch>`.
|
||||
|
||||
## Health and outputs
|
||||
|
||||
| Signal | Location/command | Healthy result | Unhealthy branch |
|
||||
|---|---|---|---|
|
||||
| <signal> | `<command/path>` | <result> | <action> |
|
||||
|
||||
## Rollback
|
||||
|
||||
1. <Restore previous code/config/data>
|
||||
2. Run `<health command>`.
|
||||
3. Preserve <logs/artifacts> for incident review.
|
||||
|
||||
## Known failure modes
|
||||
|
||||
| Symptom | First measurement | Likely seam | Next runbook |
|
||||
|---|---|---|---|
|
||||
| <symptom> | `<command>` | <boundary> | <sibling skill/doc> |
|
||||
|
||||
## Provenance
|
||||
|
||||
- External fact observed by <who/how> on YYYY-MM-DD.
|
||||
- Re-check: `<one-line command>`
|
||||
````
|
||||
|
||||
## Documentation change review
|
||||
|
||||
````markdown
|
||||
# Documentation review: <scope>
|
||||
|
||||
**Date:** YYYY-MM-DD
|
||||
**Reviewer:** <name/session>
|
||||
**Changed authority:** <path or none>
|
||||
|
||||
## Classification
|
||||
|
||||
| Claim/change | State | Owner | Evidence |
|
||||
|---|---|---|---|
|
||||
| <claim> | CURRENT / APPROVED TARGET / OPEN / HISTORICAL / GENERATED / EXTERNAL | <owner> | `<path.Symbol/test/command>` |
|
||||
|
||||
## Findings
|
||||
|
||||
| Severity | Location | Problem | Evidence | Required correction |
|
||||
|---|---|---|---|---|
|
||||
| Blocking / Important / Minor | <heading/path> | <problem> | <evidence> | <fix> |
|
||||
|
||||
## Authority and duplication checks
|
||||
|
||||
- [ ] One record of authority owns each claim.
|
||||
- [ ] Current and target behavior are separated.
|
||||
- [ ] Open questions remain visibly open.
|
||||
- [ ] Historical material is not used normatively.
|
||||
- [ ] Generated output was not hand-edited.
|
||||
- [ ] Symbols and headings replace durable line-number citations.
|
||||
|
||||
## Maintainability checks
|
||||
|
||||
- [ ] Responsibility, owner, boundaries, consumers, and invariants are explicit.
|
||||
- [ ] Superseded paths and deletion gates are named.
|
||||
- [ ] Evidence, rollback, and unresolved questions are actionable.
|
||||
- [ ] A zero-context engineer can locate the complete feature path.
|
||||
|
||||
## Validation evidence
|
||||
|
||||
| Command | Expected | Observed |
|
||||
|---|---|---|
|
||||
| `<exact command>` | <result> | <result> |
|
||||
|
||||
## Residual uncertainty
|
||||
|
||||
<List unverified external facts, unavailable environments, or still-open
|
||||
decisions. Never convert them into implied acceptance.>
|
||||
````
|
||||
@@ -0,0 +1,380 @@
|
||||
---
|
||||
name: archie-domain-reference
|
||||
description: "Use when naming, designing, reviewing, documenting, tracing, or migrating Archie concepts such as Agent, Identity, user, Message, Conversation, work intake, WorkflowExecution, plugin engines, channels, events, policy, forge, worktrees, or gates; when current task/gateway/store vocabulary conflicts with the approved architecture; or when a feature risks crossing domain ownership boundaries. Provides project-specific current-to-target mappings, ownership rules, lifecycle language, and glossary checks. Do not use for NellDB API mechanics, general code tracing, config enumeration, debugging, or operations."
|
||||
---
|
||||
|
||||
# Archie Domain Reference
|
||||
|
||||
Use one meaning for each noun. Keep external-system words at adapters, keep
|
||||
domain meaning with its owner, and mark migration state explicitly.
|
||||
|
||||
## Route work to the right sibling
|
||||
|
||||
Do not use this skill as a substitute for:
|
||||
|
||||
| Need | Load instead |
|
||||
| --- | --- |
|
||||
| Decide or sequence an architectural migration | `archie-architecture-planning-campaign` and `archie-architecture-contract` |
|
||||
| Trace definitions, call sites, interfaces, or AST relationships | `archie-codebase-discovery` |
|
||||
| Understand NellDB documents, queries, adapters, or persistence behavior | `archie-nelldb` |
|
||||
| Enumerate or change TOML, environment, flag, or runtime-setting axes | `archie-config-and-flags` |
|
||||
| Prove supersession, remove a legacy path, or assign accountable ownership | `archie-technical-accountability` |
|
||||
| Classify and gate a proposed change | `archie-change-control` |
|
||||
| Diagnose a failing runtime or test symptom | `archie-debugging-playbook` |
|
||||
| Run or deploy the system | `archie-run-and-operate` |
|
||||
|
||||
Use this skill first when another task is blocked on the meaning or owner of a
|
||||
word.
|
||||
|
||||
## Classify every statement
|
||||
|
||||
As of 2026-07-28, Archie is between a technical-package implementation and an
|
||||
approved domain-oriented target. Never blend the two.
|
||||
|
||||
| Label | Meaning | Evidence rule |
|
||||
| --- | --- | --- |
|
||||
| **CURRENT** | Behavior or structure present in live code and tests | Cite the defining type/function and a production caller or test. |
|
||||
| **APPROVED TARGET** | A normative rule in an approved foundation document, or a confirmed constraint repeated in `migration-decisions.md` | Cite the exact PRD. Do not claim it is implemented. |
|
||||
| **OPEN/CANDIDATE** | A deferred API, owner, package destination, migration mechanism, or behavior still under investigation | Preserve the open question. Do not fill it with a plausible design. |
|
||||
| **ARCHIVED** | Historical context under `docs/archive/` | Use only for archaeology; reverify against live code and active PRDs. |
|
||||
|
||||
Start each design or review note with a status sentence:
|
||||
|
||||
```text
|
||||
CURRENT: store.Task persists one mutable Stage string.
|
||||
APPROVED TARGET: WorkflowExecution records StepExecution history.
|
||||
OPEN: the exact schema and Go API for that history.
|
||||
```
|
||||
|
||||
Read status markers and the architecture index before treating a statement as
|
||||
settled:
|
||||
|
||||
```bash
|
||||
sed -n '1,180p' docs/prds/01-project-management.md
|
||||
rg -n '^\*\*Status:\*\*|^## Decisions still required|^## Remaining migration decisions' docs/prds/architecture
|
||||
```
|
||||
|
||||
`docs/prds/architecture/agent-system.md` is marked current-state investigation
|
||||
in progress, and `messaging-and-work-intake.md` says foundation decisions are in
|
||||
progress. Treat only their constraints confirmed by approved documents or
|
||||
`migration-decisions.md` as settled target doctrine. Treat their explicit
|
||||
decision lists as open.
|
||||
|
||||
## Use the canonical actor vocabulary
|
||||
|
||||
| Term | Archie meaning | State and owner |
|
||||
| --- | --- | --- |
|
||||
| **Identity** | A durable actor reference used for ownership, attribution, routing, commands, events, and audit. Display names and external usernames are bindings, not IDs. Identity is not authentication or access control. | **APPROVED TARGET:** `internal/domain/identity`; see `identity.md`. **CURRENT:** configured names and empty strings act as identifiers. |
|
||||
| **User** | A person represented as the `user` kind of Identity, not a second foundational identity system. | **APPROVED TARGET:** Identity domain. User authentication and authorization remain separate capabilities if later justified. |
|
||||
| **Agent** | A persistent assistant with its own acting IdentityID, specialization, instructions, capability context, conversation continuity, and memory. It survives model/provider changes. | **CONFIRMED TARGET CONCEPT:** Agent and Identity are separate aggregates; `internal/domain/agent` is confirmed in `migration-decisions.md`. A complete Agent domain is not current. |
|
||||
| **Model invocation** | One call through an LLM provider/runtime. It is replaceable execution machinery, not an Agent. | **CURRENT:** runtime/agent execution packages perform calls. **TARGET:** infrastructure behind Agent-owned behavior. |
|
||||
| **System identity** | The one permanent actor for startup, migration, supervision, remediation, and rollback attribution. It is always active. | **APPROVED TARGET:** a real IdentityID; the current empty-string legacy path is not the system identity. |
|
||||
| **Service-account identity** | A durable non-Agent actor for an explicitly justified unattended use case. | **TARGET OPTION:** not the default Agent execution identity. Delegated run-as behavior is future work. |
|
||||
|
||||
Apply these rules:
|
||||
|
||||
- Record the acting Agent identity and initiating user identity separately.
|
||||
- Never authorize solely because two mutable identity-name strings match.
|
||||
- Never rename an Agent when only its model, provider, display name, or forge
|
||||
account changes.
|
||||
- Never pool two Agents' agent-wide memory because one user owns both.
|
||||
- Never pass a complete per-identity config bundle into a domain. Split settings
|
||||
by the capability that owns them.
|
||||
|
||||
Verify the current mismatch:
|
||||
|
||||
```bash
|
||||
rg -n 'type IdentityConfig|type IdentityRunner|Identity string|BotUser string|identity == ""|Identity != identity' internal/config internal/daemon internal/store internal/gateway
|
||||
```
|
||||
|
||||
## Use the canonical interaction vocabulary
|
||||
|
||||
| Term | Archie meaning | State and owner |
|
||||
| --- | --- | --- |
|
||||
| **Channel** | An external interaction source or delivery system such as Telegram, email, webhook, forge, or future Jira. Its native nouns remain valid inside its adapter. | **CURRENT:** `internal/channels` extends `gateway.Gateway`; forge polling bypasses it. **TARGET:** infrastructure adapter for Messaging. |
|
||||
| **Adapter** | Boundary code that translates an external payload, identifier, delivery result, or SDK type into an owned application contract and back. | **TARGET RULE:** infrastructure implements domain-owned interfaces. An adapter does not own domain state. |
|
||||
| **Gateway** | A current technical interface/router and package, not approved domain vocabulary. It currently combines channel lifecycle, commands, conversational routing, sessions, and task control. | **CURRENT ONLY:** `internal/gateway`, `internal/channels`, and `cmd/archied`. Do not make a new domain named Gateway by default. |
|
||||
| **ChannelBindingID** | Stable reference connecting a configured Agent to a particular external channel binding. | **APPROVED TARGET INPUT:** part of Conversation identity. Exact storage/API remains migration work. |
|
||||
| **Message** | An immutable application record with its own MessageID and typed content. Platform message IDs are external correlations. | **TARGET:** Messaging owns it. **CURRENT:** production adapters mostly use `gateway.Message`; the richer `MessageEvent` exists beside it. |
|
||||
| **Conversation** | Interaction history identified by AgentID + UserIdentityID + ChannelBindingID + ExternalConversationID + ThreadID. | **CONFIRMED TARGET:** Messaging. **CURRENT:** `gateway.SessionSource` has platform, bot user, channel, and thread, but lacks canonical Agent and user IDs. |
|
||||
| **Conversation branch** | A child conversation continuing from one exact immutable parent message, identified by ParentConversationID and ForkMessageID. | **CONFIRMED TARGET:** parent/child transcripts diverge after the fork. No current implementation provides this complete contract. |
|
||||
| **Work Intake** | The optional admission, validation, and deterministic routing boundary between an interaction and durable workflow-backed work. | **CONFIRMED TARGET DOMAIN:** `internal/domain/workintake`. It does not exist as a current package. |
|
||||
| **Accepted work request** | The channel-neutral handoff emitted after Work Intake accepts a proposed durable outcome. It carries source correlation, acting identity, requested outcome, inputs, and routing evidence. | **TARGET HANDOFF:** the Agent System consumes it, selects a Workflow version, and alone creates a WorkflowExecution. Exact minimal contract is open. |
|
||||
|
||||
Do not equate an inbound Message with work. An Agent may answer, use a
|
||||
capability, retain information, or propose durable work without creating a
|
||||
WorkflowExecution. Deterministic automation may enter Work Intake without an
|
||||
LLM turn only when its trigger and admission rule are unambiguous.
|
||||
|
||||
Use this target flow:
|
||||
|
||||
```text
|
||||
external payload
|
||||
-> channel adapter
|
||||
-> canonical Message and Conversation
|
||||
-> selected Agent turn
|
||||
-> optional proposed work
|
||||
-> Work Intake admission
|
||||
-> accepted work request
|
||||
-> Agent System selects Workflow version
|
||||
-> WorkflowExecution
|
||||
```
|
||||
|
||||
Do not describe the current `/spawn` path as this target. It directly creates a
|
||||
`store.Task` with a synthetic forge issue number.
|
||||
|
||||
Verify both current message contracts and the direct task path:
|
||||
|
||||
```bash
|
||||
rg -n 'type Message struct|type MessageEvent struct|ToLegacy|type SessionSource|CreateTask|EnqueueChatTask|synthetic' internal/gateway internal/store cmd/archied
|
||||
```
|
||||
|
||||
## Use the canonical execution vocabulary
|
||||
|
||||
| Term | Archie meaning | Current representation |
|
||||
| --- | --- | --- |
|
||||
| **Workflow** | Reusable, versioned definition of behavior. | `workflow.Workflow` is currently a named ordered `[]Stage` without a durable version model. |
|
||||
| **WorkflowExecution** | One durable execution of one specific Workflow version. | `store.Task` is the migration baseline, despite its name. |
|
||||
| **WorkflowStep** | One defined operation in a Workflow. | A current `workflow.Stage` is the closest definition, but migration is not a mechanical rename. |
|
||||
| **StepExecution** | Durable record of one WorkflowStep's execution and outcome. | Missing as an explicit current record; `store.Task.Stage` is one mutable string and event records are not authoritative history. |
|
||||
| **Attempt** | A retry within the same WorkflowExecution, not a new execution. | Current `Task.Attempt` and `RetryCount` must become explicit attempt history; worker-delivery retry is a different concern. |
|
||||
| **WorkflowExecution workspace** | Isolated mutable source workspace leased to one execution. | Current worktree, storage, container, branch, and cleanup behavior is spread across packages. |
|
||||
| **Agent step execution** | One bounded model-backed WorkflowStep invocation. | `agentexec.Request`/`Result` correlate current TaskID, Attempt, Stage, and protocol version. This serializable request/result pair is a data boundary. |
|
||||
|
||||
Use `WorkflowExecution` in domain contracts, architecture, generated reference,
|
||||
commands, and events. Qualify `workflow.Execution` in Go when useful. Never use
|
||||
bare `Execution` across domains.
|
||||
|
||||
Retain `task` only for:
|
||||
|
||||
- the external Task build tool in `Taskfile.yml`;
|
||||
- a forge/Jira product's own noun inside its adapter;
|
||||
- informal prose that unambiguously means external work.
|
||||
|
||||
Never globally replace `task`. Classify each occurrence first:
|
||||
|
||||
```bash
|
||||
rg -n '\b(Task|task|TaskID|task_id)\b' --glob '*.go' --glob '*.md' cmd internal docs/prds/architecture
|
||||
```
|
||||
|
||||
### Interpret the current lifecycle exactly
|
||||
|
||||
These are **CURRENT** `store.Task` states, not proof of an implemented target
|
||||
state machine:
|
||||
|
||||
```text
|
||||
queued -> running
|
||||
running -> waiting_human | pr_open | merged | parked | closed_wont_do
|
||||
waiting_human -> queued | closed_wont_do
|
||||
parked -> queued | dead
|
||||
pr_open -> merged | rejected
|
||||
running after crash -> queued
|
||||
```
|
||||
|
||||
Use `waiting_human` for a paused current execution awaiting correlated human
|
||||
input. Use `parked` for a current failure/manual-intervention state that may be
|
||||
retried; use `dead` after retry exhaustion. Treat `pr_open`, `merged`,
|
||||
`rejected`, and `closed_wont_do` as current delivery/outcome states.
|
||||
|
||||
Do not claim these transitions are enforced. `Store.Transition` writes the new
|
||||
status without comparing `from`, then inserts history in a separate statement.
|
||||
`internal/gateway/tasks.go` duplicates status strings locally.
|
||||
|
||||
Verify before changing lifecycle language:
|
||||
|
||||
```bash
|
||||
rg -n 'Status[A-Za-z]+|status[A-Za-z]+|func \(s \*Store\) Transition|func \(s \*Store\) Requeue|RecoverStale' internal/store internal/gateway
|
||||
```
|
||||
|
||||
## Keep memory scope separate from conversation scope
|
||||
|
||||
The following four scopes are fixed target constraints:
|
||||
|
||||
| Scope | Address and visibility |
|
||||
| --- | --- |
|
||||
| **Global shared** | Intentionally visible across the Archie application; retain provenance. |
|
||||
| **Agent-wide** | Owned by one Agent and private to that Agent by default, even across users. |
|
||||
| **User-wide** | Associated with one user and available only to authorized Agents serving that user. |
|
||||
| **Agent-user relationship** | Addressed by both AgentID and User IdentityID; private to that pair. |
|
||||
|
||||
A Conversation branch is not a fifth memory scope. Branches isolate immediate
|
||||
transcripts. A memory written from a branch follows the same selected durable
|
||||
scope as one written from its parent; provenance may retain ConversationID and
|
||||
MessageIDs.
|
||||
|
||||
Label scope mechanics **OPEN** beyond these constraints. The exact write-scope
|
||||
selection, grants, cross-scope sharing, record/revision model, and final memory
|
||||
package placement require a focused design.
|
||||
|
||||
Do not claim current scope enforcement. The current `MemoryProvider` initializes
|
||||
with a session ID and contains no explicit AgentID, User IdentityID, or scope
|
||||
parameter. The built-in provider separates `MEMORY.md` and `USER.md` under one
|
||||
configured directory, which is not the four-scope target model.
|
||||
|
||||
Verify that gap without entering NellDB mechanics:
|
||||
|
||||
```bash
|
||||
rg -n 'type MemoryProvider|Initialize\(|type Config struct|MEMORY.md|USER.md|AgentID|IdentityID|Scope' internal/memory
|
||||
```
|
||||
|
||||
## Distinguish extension terms
|
||||
|
||||
| Term | Meaning |
|
||||
| --- | --- |
|
||||
| **Plugin** | A removable module with identity, metadata, compatibility, discovery, and lifecycle mechanics. Generic `plugin.Plugin` must remain metadata-only. |
|
||||
| **Capability family** | One cohesive typed behavior owned by its domain or approved manager/registry, such as tools, channels, delivery, or Workflow extensions. |
|
||||
| **Engine** | A typed, lifecycle-managed capability family with one owning Registry or Manager that both registers and returns the typed engine. It is never an extra generic-plugin method. |
|
||||
| **Host** | Current cross-family lifecycle/manifest coordinator in `internal/plugin`. It must not become a daemon service locator. |
|
||||
|
||||
Give a plugin only narrow typed registrars and explicitly supplied contracts.
|
||||
Do not give it daemon internals, application composition, arbitrary
|
||||
infrastructure, or an untyped map of services. Keep Workflow plugin semantics
|
||||
owned by Workflow.
|
||||
|
||||
The current repository mechanically enforces the strict engine shape and
|
||||
metadata-only `Plugin{Name, Version}` contract:
|
||||
|
||||
```bash
|
||||
go test ./internal/plugin -run 'Test(GenericPluginContractRemainsMetadataOnly|EveryEngineInterfaceHasTypedCapabilityAndFamilyOwner)' -count=1
|
||||
```
|
||||
|
||||
## Distinguish ownership and boundary terms
|
||||
|
||||
| Term | Archie-specific rule |
|
||||
| --- | --- |
|
||||
| **Domain** | Own one cohesive application responsibility: vocabulary, state, rules, operations, commands, events, policy implementations, runtime settings, and required service contracts. Do not create ceremonial layers. |
|
||||
| **Command** | Request an action. The receiving domain owns the contract and decides the result. |
|
||||
| **Domain event** | Record something that happened. The publishing domain owns its schema and meaning. Consumers do not redefine it. |
|
||||
| **Event bus** | Broker-neutral delivery/lifecycle contract only. It transports domain-owned messages and does not own their meaning. `internal/eventbus` is an approved target package but is not current. |
|
||||
| **Observability event** | Current `internal/events.Event` projection input. Its bounded in-process bus may drop per-subscriber events. Do not treat it as authoritative state or as the target domain event bus. |
|
||||
| **Policy** | A typed rule evaluated through shared mechanics. The consuming domain owns vocabulary, inputs, evaluator, and consequence. `internal/policy` owns common evaluation mechanics, not all rules. Its exact API is open. |
|
||||
| **Infrastructure** | Implements domain-owned ports and translates databases, brokers, SDKs, files, networks, containers, or external services. External DTOs must not leak into domains. |
|
||||
| **Application composition** | Chooses implementations, translates external configuration into owned settings, connects contracts, orders startup/shutdown, and aggregates health. Target owner is `internal/app`; current substantive wiring remains in `cmd/archied`. |
|
||||
|
||||
As of 2026-07-28, `internal/domain`, `internal/eventbus`,
|
||||
`internal/policy`, `internal/infrastructure`, and `internal/app` do not exist.
|
||||
They are target paths, not current imports.
|
||||
|
||||
Verify the separation:
|
||||
|
||||
```bash
|
||||
for p in internal/domain internal/eventbus internal/policy internal/infrastructure internal/app; do test -d "$p" && echo "$p CURRENT" || echo "$p TARGET-ONLY"; done
|
||||
```
|
||||
|
||||
## Distinguish forge, repository, workspace, gate, and agent boundaries
|
||||
|
||||
| Term | Owns | Must not own |
|
||||
| --- | --- | --- |
|
||||
| **Forge** | External code-host operations: issues, comments, labels, pull requests, reactions, and external references. | Workflow lifecycle, canonical identity, or work admission. |
|
||||
| **Repository** | External source repository identity and repository-specific policy/settings. | A mutable execution workspace or a WorkflowExecution identity. |
|
||||
| **Worktree/workspace** | Isolated files, branch, diff, commit, push, retention, and cleanup for one execution. Current `internal/worktree` performs git deterministically. | Agent/domain identity or forge issue lifecycle. |
|
||||
| **Gate** | Deterministic evidence and constraints over an execution, including shell gates and custom findings. | Prompt advice that the model may waive. |
|
||||
| **Agent execution boundary** | Versioned, validated data entering and leaving one unprivileged autonomous stage. The stage `Request` excludes workspace layout; the outer `Invocation` supplies the worker-visible workspace. | Daemon internals, forge tokens, direct git ownership, or workflow orchestration. |
|
||||
|
||||
Preserve the current invariant that the model never runs git directly.
|
||||
Worktree operations are daemon-owned deterministic steps. Keep gates, protected
|
||||
paths, budgets, and result review outside the model's discretion.
|
||||
|
||||
Inspect the narrow current contracts before changing a boundary:
|
||||
|
||||
```bash
|
||||
sed -n '1,180p' internal/agentexec/protocol.go
|
||||
sed -n '1,140p' internal/forge/forge.go
|
||||
sed -n '1,120p' internal/worktree/worktree.go
|
||||
sed -n '1,120p' internal/gate/gate.go
|
||||
```
|
||||
|
||||
## Map current names before adding or migrating behavior
|
||||
|
||||
Use this map as a starting point, then trace actual consumers:
|
||||
|
||||
| Current name/path | Target meaning | Migration warning |
|
||||
| --- | --- | --- |
|
||||
| `config.IdentityConfig.Name` | Canonical IdentityID reference plus separate capability bindings | Do not preserve a mutable display name as the ID. |
|
||||
| `config.IdentityConfig.BotUser` | Forge/Git or channel external binding | Do not use it as Conversation or Agent identity. |
|
||||
| `daemon.IdentityRunner` | Composition of identity-correlated capabilities | It is currently a service bundle, not an Identity aggregate. |
|
||||
| `gateway.Message`, `MessageEvent` | Canonical Messaging Message | Choose one immutable typed contract; do not maintain indefinite parallel models. |
|
||||
| `gateway.SessionContext` | Conversation metadata | Add canonical Agent/user/binding ownership and exact branch lineage deliberately. |
|
||||
| forge `Issue` or future Jira item | Channel message or external artifact | Preserve native reference inside its adapter. |
|
||||
| gateway `/spawn` and `TaskCreator` | Proposed/accepted work handoff | Work Intake admits; Agent System alone creates execution. |
|
||||
| `store.Task` | WorkflowExecution | Preserve every field intentionally; do not rename blindly. |
|
||||
| `workflow.Workflow` | Versioned Workflow definition | Add identity/version ownership before claiming parity. |
|
||||
| `workflow.Stage` | WorkflowStep definition | A definition is not execution history. |
|
||||
| mutable `Task.Stage` | Derived position plus StepExecution records | Deletion requires proven history parity. |
|
||||
| `Task.Attempt`, `RetryCount` | Attempt history and retry evidence | Keep worker delivery retries distinct. |
|
||||
| `workflow.TaskContext` | Execution state plus narrow step ports | Remove the global config/service bag; do not reproduce it under a new name. |
|
||||
| `events.Event` and `Bus` | Projections fed by authoritative domain events | Current drops are acceptable for observability, not state. |
|
||||
| `cmd/archied` wiring | `internal/app/archied` composition | Keep `cmd/*` process-input-only in the target. |
|
||||
| NATS/RPC/store/forge/worktree implementations | Infrastructure adapters | Process boundaries do not decide domain ownership. |
|
||||
|
||||
Do not infer a final package destination for every current package from this
|
||||
table. `migration-decisions.md` explicitly leaves memory, tools, workspaces,
|
||||
gates, storage, events, web UI, containers, RPC, release management, and
|
||||
scheduling pending focused review.
|
||||
|
||||
## Recognize terminology-driven bugs
|
||||
|
||||
Use these examples during design and review:
|
||||
|
||||
| Incorrect shortcut | Resulting bug |
|
||||
| --- | --- |
|
||||
| “A forge issue is a Task, so persist its coordinates as execution identity.” | Chat work needs synthetic issue numbers; uniqueness and deduplication stay forge-shaped. This is a current hazard. |
|
||||
| “Agent and Identity are the same config object.” | Model/persona/capability changes can alter attribution, and mutable string equality becomes access control. |
|
||||
| “Every Message is work.” | Conversational turns and direct capabilities are forced through a durable workflow lifecycle. |
|
||||
| “An accepted request is already a WorkflowExecution.” | Intake can bypass Workflow version selection and construct invalid execution state. |
|
||||
| “Stage is StepExecution.” | Overwriting one stage string destroys durable step outcomes and audit history. |
|
||||
| “A NATS retry is another Attempt.” | Transport availability changes domain retry counts and can exhaust work incorrectly. |
|
||||
| “The event bus owns events.” | Broker subjects or a generic event envelope become domain vocabulary and state meaning drifts by consumer. |
|
||||
| “A branch is a memory scope.” | Returning to a parent hides or duplicates durable learning instead of isolating only transcript history. |
|
||||
| “Engine means another generic plugin hook.” | Capability ownership becomes untyped and plugins gain service-locator access. |
|
||||
| “Configuration owns the feature because it has the fields.” | A cross-concern config package becomes the de facto domain and every feature must traverse it. |
|
||||
|
||||
## Review a spec or change with the glossary
|
||||
|
||||
Complete this checklist before accepting a design:
|
||||
|
||||
- [ ] Label every material claim CURRENT, APPROVED TARGET, or OPEN/CANDIDATE.
|
||||
- [ ] Define every overloaded noun once; qualify `WorkflowExecution` and
|
||||
`StepExecution`.
|
||||
- [ ] Keep external issue/task/message vocabulary inside the relevant adapter.
|
||||
- [ ] Name one domain owner for each state mutation, command, event, and policy.
|
||||
- [ ] Identify both acting IdentityID and initiating user IdentityID where
|
||||
applicable.
|
||||
- [ ] Decide whether the interaction ends directly or enters Work Intake.
|
||||
- [ ] Let only the Agent System create a WorkflowExecution.
|
||||
- [ ] Separate a definition (`WorkflowStep`) from its record
|
||||
(`StepExecution`).
|
||||
- [ ] Separate workflow attempts, step attempts, and transport retries.
|
||||
- [ ] Keep domain event meaning outside event-bus and infrastructure packages.
|
||||
- [ ] Keep generic plugins metadata-only and capabilities typed.
|
||||
- [ ] Keep external DTOs and complete configuration objects out of domains.
|
||||
- [ ] Name the current path being superseded and its objective deletion
|
||||
criteria; route the proof to `archie-technical-accountability`.
|
||||
- [ ] Preserve unresolved questions rather than inventing an API.
|
||||
|
||||
During code review, reject:
|
||||
|
||||
- a second channel-neutral Message or execution model without a bounded cutover;
|
||||
- a new status string copied into a consumer;
|
||||
- a mutable display name used as a durable identifier;
|
||||
- a service bag passed into a domain, plugin, or WorkflowStep;
|
||||
- lifecycle state written by an adapter, UI, or transport;
|
||||
- a domain importing concrete persistence, NATS, forge SDK, container, or
|
||||
configuration DTO types;
|
||||
- a test that proves only the new path while leaving the old production path
|
||||
active.
|
||||
|
||||
## Provenance and maintenance
|
||||
|
||||
Volatile facts were verified against the working tree on 2026-07-28. Re-run
|
||||
these one-line commands before relying on this skill after architecture or
|
||||
package changes:
|
||||
|
||||
```bash
|
||||
rg -n '^\*\*Status:\*\*|^## (Confirmed|Decisions still required|Remaining migration decisions|Completion criteria)' docs/prds/01-project-management.md docs/prds/architecture/*.md
|
||||
rg -n '^type (Task|Workflow|Stage|TaskContext|Request|Result|Message|MessageEvent|SessionContext|Event|Plugin|Channel|BasePlatformAdapter)\b' internal
|
||||
rg -n 'Status[A-Za-z]+|status[A-Za-z]+|func \(s \*Store\) Transition' internal/store internal/gateway
|
||||
rg -n 'AgentID|IdentityID|ParentConversationID|ForkMessageID|WorkflowExecution|StepExecution|accepted work request' docs/prds/architecture
|
||||
for p in internal/domain internal/eventbus internal/policy internal/infrastructure internal/app; do test -d "$p" && echo "$p CURRENT" || echo "$p TARGET-ONLY"; done
|
||||
go test ./internal/plugin -run 'Test(GenericPluginContractRemainsMetadataOnly|EveryEngineInterfaceHasTypedCapabilityAndFamilyOwner)' -count=1
|
||||
```
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Archie Domain Reference"
|
||||
short_description: "Use Archie terminology without boundary mistakes"
|
||||
default_prompt: "Use $archie-domain-reference to classify these Archie concepts and map current code terms to their approved target owners."
|
||||
@@ -0,0 +1,269 @@
|
||||
---
|
||||
name: archie-failure-archaeology
|
||||
description: "Reconstruct archie-core failures, dead ends, reversals, rejected fixes, and branch-only repairs from read-only git history and live call sites. Use when a symptom resembles a past production outage, deadlock, retry loop, protocol mismatch, configuration regression, worktree/cache fault, unsafe cleanup, linter semantic change, artifact leak, or recurring baseline repair; also use before reviving an old approach, declaring a fix reverted, or deciding whether a repair is current, settled, conditional, superseded, open, or merely a candidate."
|
||||
---
|
||||
|
||||
# Archie failure archaeology
|
||||
|
||||
Stop the project from paying twice for the same lesson. Reconstruct what
|
||||
happened from the checked-out code, tests, configuration, and commit graph.
|
||||
Treat commit prose as a lead, not proof. Preserve uncertainty.
|
||||
|
||||
All volatile observations below are dated **2026-07-28**. Re-run the
|
||||
provenance commands before relying on a status.
|
||||
|
||||
## Route the work
|
||||
|
||||
| Need | Load instead or alongside |
|
||||
|---|---|
|
||||
| Triage an active symptom and choose the next diagnostic | `archie-debugging-playbook` |
|
||||
| Decide ownership, boundaries, migration, or a replacement design | `archie-architecture-planning-campaign` |
|
||||
| Accept, gate, review, or close a change | `archie-change-control` |
|
||||
| Traverse callers, ASTs, duplicate paths, or apparently dead code deeply | `archie-codebase-discovery` |
|
||||
|
||||
Do **not** use this skill:
|
||||
|
||||
- as permission to change code, configuration, git state, or production;
|
||||
- as a substitute for reproducing a current failure;
|
||||
- to promote a commit subject, old PRD, Beads record, or remote branch into
|
||||
current truth;
|
||||
- to call work “reverted” unless a revert commit or an inverse diff proves it;
|
||||
- to design the next architecture. Carry proven constraints into
|
||||
`archie-architecture-planning-campaign`.
|
||||
|
||||
## Use the status taxonomy exactly
|
||||
|
||||
| Status | Meaning |
|
||||
|---|---|
|
||||
| `settled` (`fixed`) | The failure, cause, resolution, and live replacement are proven. Preserve the resulting rule. |
|
||||
| `current` | The checked-out authoritative path still contains the behavior or contradiction. |
|
||||
| `open` | The defect is evidenced, but no accepted and integrated resolution is proven. |
|
||||
| `conditional` | A fix is proven only for the named configuration, execution mode, peer, or deployment assembly. |
|
||||
| `superseded` | A mechanism was intentionally replaced. Study it for constraints; do not restore it by default. |
|
||||
| `candidate` | A branch, proposal, or partial implementation may help, but is not accepted current behavior. |
|
||||
|
||||
Never use `settled` to mean “a fix commit exists.” Prove that the fix is an
|
||||
ancestor of the checkout and that live composition still selects it.
|
||||
|
||||
## Run the archaeology workflow
|
||||
|
||||
### 1. Freeze the observation point
|
||||
|
||||
Run only read-only git commands:
|
||||
|
||||
```sh
|
||||
git rev-parse HEAD
|
||||
git status --short
|
||||
git log -1 --date=iso-strict --format='%H %ad %s'
|
||||
git branch -a --no-color --no-merged HEAD
|
||||
```
|
||||
|
||||
Record the commit and dirty paths. A dirty live file may contain a repair that
|
||||
`HEAD` does not. Report both; do not silently choose one.
|
||||
|
||||
### 2. Name the exact symptom
|
||||
|
||||
Capture:
|
||||
|
||||
- the first wrong observable result;
|
||||
- the last confirmed-good boundary;
|
||||
- process mode (`inprocess`, `subprocess`, or NATS/container);
|
||||
- the active config and deployment assembly;
|
||||
- whether the failure is deterministic, load-dependent, or production-only.
|
||||
|
||||
Do not start with a preferred fix.
|
||||
|
||||
### 3. Trace current behavior before history
|
||||
|
||||
```sh
|
||||
rg -n '<symptom|symbol|setting|error>' cmd internal config*.toml docker-compose.yml docs
|
||||
git log --all --date=iso-strict --format='%H %ad %s' -- <affected-paths>
|
||||
git blame -L <start>,<end> -- <live-file>
|
||||
```
|
||||
|
||||
Trace entry point, caller, owner, adapter, peer, persistence, config decoder,
|
||||
environment passthrough, and tests. Use `archie-codebase-discovery` when that
|
||||
cone is not obvious.
|
||||
|
||||
### 4. Prove the historical transition
|
||||
|
||||
```sh
|
||||
git show --no-ext-diff --format=fuller --stat <commit>
|
||||
git show --no-ext-diff -U80 <commit> -- <affected-paths>
|
||||
git merge-base --is-ancestor <commit> HEAD
|
||||
git branch -a --contains <commit>
|
||||
```
|
||||
|
||||
Read the parent version when the failure is semantic:
|
||||
|
||||
```sh
|
||||
git show <commit>^:<path>
|
||||
git show <commit>:<path>
|
||||
```
|
||||
|
||||
Require all six fields in an incident packet:
|
||||
|
||||
| Field | Required content |
|
||||
|---|---|
|
||||
| Symptom | Operator, user, test, or protocol observation |
|
||||
| Attempted solution | What was tried before or during the failure |
|
||||
| Root cause | The violated contract or mistaken assumption |
|
||||
| Evidence | Commit, live path, test, trace, or production observation |
|
||||
| Current status | One taxonomy value, dated when volatile |
|
||||
| Settled rule | A constraint future work must preserve |
|
||||
|
||||
### 5. Reproduce narrowly, then route
|
||||
|
||||
Use a focused, non-mutating check where practical. Put Go caches in `/tmp`:
|
||||
|
||||
```sh
|
||||
env GOCACHE=/tmp/archie-archaeology-gocache GOTMPDIR=/tmp go test ./internal/<package> -run '^TestName$' -count=1 -v
|
||||
```
|
||||
|
||||
If current behavior differs from the chronicle, update the packet rather than
|
||||
forcing the symptom into an old story. Route a proposed correction through
|
||||
`archie-change-control`.
|
||||
|
||||
## Match symptoms to known incidents
|
||||
|
||||
| Symptom | Start with |
|
||||
|---|---|
|
||||
| `nats: no responders available for request` only from agent containers | Container network incident |
|
||||
| Daemon crash-loops after config/schema work | SecretRef compatibility and Compose passthrough incidents |
|
||||
| Stream shows an empty cursor or first token, then hangs | FullStream/TextStream incident |
|
||||
| MCP unit tests pass but a real SDK server hangs or rejects input | MCP framing and mirrored-peer incident |
|
||||
| Telegram shows old commands after a successful menu update | Telegram server-side scope incident |
|
||||
| Tool discovery deadlocks, aliases mutate, or one bad plugin hides the rest | Tool-registry adversarial findings |
|
||||
| Hidden `<memory>` content appears at end of a truncated stream | Scrubber `Flush` leak |
|
||||
| Broad lint cleanup compiles poorly or changes semantics while tests pass | Autofix, `nilerr`, and `308c199` incidents |
|
||||
| A reused worktree is stale, half-prepared, or coupled to expired objects | Worktree/askpass/cache history |
|
||||
| Repeated `fix: baseline gate repair` commits or parked tasks cycle | Baseline, no-op, and retry-loop incidents |
|
||||
| CI cannot resolve `/work/apps/...` | Local module replacement incident |
|
||||
| Build caches or dependency trees appear in the diff | `.gotmp` and `node_modules` incidents |
|
||||
| `diff_cap_lines = 0` still behaves as 400 | Diff-cap zero contradiction |
|
||||
|
||||
## Chronicle: work intake and retry loops
|
||||
|
||||
| Incident and date | Symptom | Attempted solution and root cause | Evidence and status | Settled rule |
|
||||
|---|---|---|---|---|
|
||||
| Label auto-claim, 2026-07-22 | More than 80 labelled issues were enrolled when the deployment used label polling. | **Attempt:** use the `archie` label as the work trigger. **Cause:** label polling means eligibility, not a hint; it selected every matching issue without explicit assignment. | `519882f` changes `config.docker.toml` from `label` to `assignee`; `docs/archive/decisions.md` records the 80+ issue incident. `internal/config/config.go` now defaults to `assignee` but still permits explicit `label` and `either`. **Status:** `settled`. | Default to assignee-driven pickup. Treat `label` or `either` as deliberate bulk enrollment and review their full candidate set first. |
|
||||
| Baseline-red park storm and repair churn, 2026-07-23 onward | A task repeatedly parks on a gate failure that existed before its feature work. History then accumulates unrelated baseline-repair commits. | **Attempt:** `b2482af` made `StageBaselineGate` launch the builder to repair a red baseline instead of parking. **Cause:** parking and retrying cannot change a pre-existing failure; auto-repair avoids that loop but mixes repository repair into feature scope. | `internal/workflow/implement.go`; `docs/archive/decisions.md`; `git log --all --grep='baseline gate repair'` returns nine repair commits in the recorded history. **Status:** `current` mitigation and architecture weak point. | Measure the untouched baseline first. Track baseline repair as an explicit change with its own evidence; never attribute its diff or success to the requested feature. |
|
||||
| Passed build with zero changes, 2026-07-23 | Commit-push reports “worktree has no changes,” parks, retries, and repeats even though the requested fix already exists. | **Attempt:** `62c0df1` introduced no-op detection; it was incomplete until `2bf42bd` set an `Outcome` so the workflow actually stopped. **Cause:** “passed with no changes” lacked a terminal domain outcome. | `TaskContext.BuildNoChanges`, build `OnResult`, and `StageCommitPush` in `internal/workflow`; `TestStageCommitPushClosesIssueWhenBuildNoChanges`. **Status:** `settled`. | Model no-op as an explicit terminal result. Test both the side effect and workflow termination. |
|
||||
| Infinite parked-task retry, 2026-07-23 | Removing the parked label repeatedly requeues a task with no terminal bound. | **Attempt:** requeue on label removal. **Cause:** retry count was not durable or capped. `a8fdb50` added persisted `retry_count`, global/per-repo `max_retries`, and `dead`. | `internal/daemon/daemon.go` (`maybeRetryParked`, `markDead`), `internal/store` retry tests, `config.example.toml`. Default is three in `finalize`. **Status:** `settled`. | Every autonomous retry needs durable attempt state, an explicit bound, a terminal state, and an operator-visible reason. |
|
||||
|
||||
## Chronicle: runtime and peer contracts
|
||||
|
||||
| Incident and date | Symptom | Attempted solution and root cause | Evidence and status | Settled rule |
|
||||
|---|---|---|---|---|
|
||||
| Container network auto-detection, 2026-07-27 | Every container-mode task returns `nats: no responders available for request`; workers never subscribe. | **Attempt:** `selfNetwork` inspected a container named after `os.Hostname` and silently fell back to the default bridge. **Cause:** the production hostname/container identity did not resolve to the running daemon, so spawned workers could not resolve `nats`. | `37cf089` records the production incident and adds `containers.network`; `2ac306b` pins `archie-core_default`; live `config.docker.toml` remains explicit and `internal/container/pool.go` warns on fallback. **Status:** `conditional`: fixed for the tracked Docker overlay; auto-detection remains a fallback elsewhere. | Make cross-container network membership explicit in deployment. Keep auto-detection diagnostic fallback only. |
|
||||
| SecretRef schema crash-loop, 2026-07-27 and again at current `HEAD` | Both production identities demand `ARCHIE_GITHUB_TOKEN` despite Gitea config, then crash-loop. | **Attempt:** replace flat `[forge].token_env` with `Forge.Token SecretRef`. **Cause:** removing the old field let TOML silently ignore deployed `token_env`; defaulting then selected the wrong secret. `1f8588d` restored precedence-compatible fallback. | `1f8588d` and `internal/config/config_test.go` document the outage. `308c199` removes the `Forge.TokenEnv` declaration while `finalize` still references it, so that commit's tree does not compile. As of 2026-07-28 the dirty worktree reintroduces the field, but `HEAD` does not. **Status:** `open` regression at `HEAD`; reverify. | Preserve decoded compatibility until deployed files are migrated and rejection of stale keys is observable. Never rely on permissive decoding. |
|
||||
| Repeated Compose secret omission, 2026-07-27 | Config names a valid env var, but the container sees it as empty and exits. | **Attempt:** define variables in the host environment/config only. **Cause:** Compose forwards only listed environment entries. `ARCHIE_GITEA_TOKEN_ARCHIE` and later `HEYARCHIE_TELEGRAM_BOT_TOKEN` were each omitted. | `22fc0ef`, `d0624b7`, live `docker-compose.yml`, and token resolution in `cmd/archied/main.go`. **Status:** `conditional`: fixed for these exact names in the tracked Compose assembly. | Trace every secret from config key to host value to Compose passthrough to process lookup. Add an assembly test or checklist whenever a secret name changes. |
|
||||
| FullStream/TextStream deadlock, 2026-07-27 | A streamed Telegram reply renders an empty cursor or first token, typing never clears, and the turn never completes. | **Attempt:** reconstruct replies from `TextStream`. **Cause:** ai-sdk makes `FullStream` authoritative and synchronously backpressured; leaving it unread blocks the producer. `TextStream` is best-effort and may drop deltas. | `6a0bd27` and the live loop in `cmd/archied/main.go`; current gateway tests exercise routing but do not directly recreate ai-sdk channel backpressure. **Status:** `settled` implementation with a regression-test gap. | Drain the authoritative stream through close, derive text from its typed parts, then inspect terminal error state. Do not validate with a convenience projection alone. |
|
||||
| MCP Content-Length framing and mirrored fake, 2026-07-26 to 2026-07-27 | Internal MCP tests pass while official-SDK servers do not understand the client. | **Attempt:** `f2768eb` implemented LSP-style `Content-Length`; `3ad57c9` strengthened that implementation. **Cause:** MCP stdio uses newline-delimited JSON. The test subprocess called the same `readMessage` and `writeMessage` helpers as the client, so both sides agreed on the same wrong protocol. | Compare `f2768eb:internal/tools/mcp/framing.go` with `dda4cde`; inspect `testMCPServer.serve` in `transport_test.go`; live opt-in independent peer is `TestDesktopCommanderClientCompatibility`. **Status:** `settled`. | For wire contracts, test raw canonical frames and an independently implemented peer. A mirrored fake proves internal symmetry, not interoperability. |
|
||||
| Telegram command scopes persist by bot token, 2026-07-27 | Startup reports eight commands published, but DMs still show roughly 60 old Hermes commands. | **Attempt:** call `SetMyCommands` for only the default scope. **Cause:** Telegram chooses the most specific scope, and older `all_private_chats`/`all_group_chats` state survives redeploys because it is server-side and keyed to the token. | `cec0f3e` adds the menu and deny-by-default sender allowlist; `576c7f5` records `getMyCommands` evidence and publishes all three scopes. Live command specs are centralized in `internal/channels/telegram`. **Status:** `settled`. | Inventory and overwrite every relevant server-side scope. A new process or code deploy does not reset remote token state. Authorize by sender identity, not group membership. |
|
||||
| NATS fetch error looked like an empty queue, 2026-07-27 | A consumer receives zero messages and treats a JetStream failure as “no work.” | **Attempt:** infer success from the message count alone. **Cause:** batch error state was not checked after the channel closed. | `0d09a2e` is the repro; `78a9145` is merged through `21ceef0`; `internal/nats/client_test.go` constructs zero messages plus a batch error. **Status:** `settled`. | Check terminal iterator/batch error state even when the data channel is empty. Empty is data, not proof of success. |
|
||||
|
||||
## Chronicle: implementation and tooling traps
|
||||
|
||||
| Incident and date | Symptom | Attempted solution and root cause | Evidence and status | Settled rule |
|
||||
|---|---|---|---|---|
|
||||
| Tool registry passed its first implementation but held eight defects, 2026-07-26 | Availability can deadlock; caller-owned schemas mutate after registration; discovery stops at the first bad source; Go-literal extraction accepts the wrong calls or loses values. | **Attempt:** implement the happy-path registry and source extractor. **Cause:** callbacks ran under `RLock`, copies were shallow/shared, literal parsing was partial, matching was broad, and discovery was fail-fast. | `9f6c36c` lists all eight fixes and regression tests in `internal/tools/registry_test.go` and `toolentry_test.go`. **Status:** `settled`. | Never call extension code under a registry lock. Clone nested caller data. Parse the complete supported literal grammar. Isolate discovery failures and match only the intended registration shape. |
|
||||
| Memory scrubber `Flush` leak, 2026-07-26 | A stream ending inside `...secret</mem` emits buffered hidden memory text to the visible response. | **Attempt:** flush every unresolved partial tag as literal text. **Cause:** pending bytes did not retain whether they were captured inside a `<memory>` block. | `b4aaaf0`, `internal/memory/scrubber/scrubber.go`, and truncated-close-tag tests. Found by adversarial review. **Status:** `settled`; implementation has since been simplified, so re-run tests before changing it. | Test every streaming state at EOF: outside block, inside block, nested block, and every partial open/close-tag prefix. Flush is a security boundary. |
|
||||
| Linter autofix shadowing, 2026-07-28 | A 24-file “style” pass stops compiling; one token away, a prefetch timeout would silently stop applying. | **Attempt:** run `golangci-lint --fix` plus formatters broadly. **Cause:** `gocritic` changed `ctx, cancel = context.WithTimeout(...)` to `:=` inside the conditional, shadowing the context. | `9b44bac`; live assignment in `internal/memory/manager.go`. **Status:** `settled` incident. | Treat autofix output as authored behavior. Inspect every semantic diff and preserve assignment-versus-declaration intent explicitly. |
|
||||
| All eleven `nilerr` findings were semantic false positives, 2026-07-28 | Mechanical “fixes” would return Go errors while tests could still pass, breaking model correction, chat usage feedback, NATS envelopes, clean shutdown, and best-effort indexing. | **Attempt:** classify all `nilerr` reports as bug candidates. **Cause:** the linter cannot see that failures are deliberately carried as text, envelopes, shutdown signals, or skipped entries. | `86cfc19` documents each site; live `//nolint:nilerr` comments state local intent. **Status:** `settled`. | Review semantic channels one site at a time. Suppress locally with the reason. Never fan out a rule-name cleanup without contract analysis. |
|
||||
| NellDB local replace broke delivery, 2026-07-26 to 2026-07-27 | Every CI Docker build fails `go mod download` on `/work/apps/nell-engine`, leaving production on an older image. | **Attempt:** point `github.com/samcharles93/NellDB v0.2.5` at a developer checkout in `d9d4822`. **Cause:** local module paths do not exist in CI/build contexts. | `07fb291` removes the replace after comparing local HEAD with published v0.2.5; live `go.mod` has the module and no replace. **Status:** `settled`. | Never commit machine-local `replace` directives. Prove the published version, checksum resolution, and container build path. |
|
||||
| Broad checkpoint hid an unresolved merge conflict, 2026-07-27 | A literal conflict marker reached committed source amid many unrelated epics. | **Attempt:** checkpoint broad concurrent in-flight work to avoid loss. **Cause:** unrelated surfaces were combined without a whole-diff conflict scan. | Commit message for `4429ae5` states that it fixed a previously committed conflict in `internal/memory/scrubber/scrubber.go`. **Status:** `settled` incident. | Keep commits cohesive. Before any checkpoint, scan the exact diff for conflict markers and run affected package tests. |
|
||||
|
||||
### Preserve the eight tool-registry review lessons
|
||||
|
||||
| Defect fixed in `9f6c36c` | Required review question |
|
||||
|---|---|
|
||||
| `Available` evaluated `CheckFn` under `RLock` | Can a callback re-enter or block while a lock is held? |
|
||||
| `Register` stored caller references | Can the caller mutate registered state afterward? |
|
||||
| `Clone` copied nested schema maps/slices shallowly | Is every mutable layer detached? |
|
||||
| `stringLit` mishandled escapes/backticks | Does parsing follow Go literal semantics? |
|
||||
| `intLit` omitted negative/hex/octal/binary forms | Are all supported numeric forms handled or rejected explicitly? |
|
||||
| `Discover` aborted on its first error | Can one bad extension hide healthy extensions? |
|
||||
| `isRegisterCall` matched too broadly | Is the exact receiver/call shape proven? |
|
||||
| `schemaLit` accepted only string values | Are booleans, integers, arrays, and nested maps preserved? |
|
||||
|
||||
## Chronicle: worktree and repository state reversals
|
||||
|
||||
Do not restore an intermediate mechanism just because one commit fixed it.
|
||||
Follow the whole chain.
|
||||
|
||||
| Step and date | Symptom and attempted solution | Root cause, evidence, and status | Settled rule |
|
||||
|---|---|---|---|
|
||||
| Existing worktree skipped, 2026-07-23 | `Prepare` returned when `.git` existed. `89530ad` added fetch/checkout/reset to refresh it. | Existence did not prove freshness or completed preparation. Later `5883568` replaced `.git` readiness with a sentinel. **Status:** `superseded` implementation, enduring lesson. | Define a completed-state marker and revalidate remote/base/branch state on reuse. |
|
||||
| Sentinel outside `.git`, 2026-07-24 | `.archie-prepared` marked successful setup and `.git/info/exclude` kept it untracked. | go-git `Add(All)` does not honor that exclude. `9c5f6a0` moved the sentinel to `.git/archie-prepared`. **Status:** `superseded` location. | Put orchestration metadata outside the tracked worktree by construction, not by ignore convention. |
|
||||
| Askpass rewritten each call, 2026-07-24 | The “writes once” helper rewrote a token-emitting shell script for every git command. `7f796b3` added `sync.Once`. | The comment was not an invariant and no test checked mtime. `9c5f6a0` later removed shell git and askpass entirely. **Status:** `superseded`. | Prefer in-process credentials. If a secret helper is unavoidable, test lifecycle, permissions, exposure, and cleanup. |
|
||||
| Bare object cache, 2026-07-24 | `4c1cfb1` added `--reference-if-able --dissociate` plus TTL to accelerate clones while keeping tasks independent. | go-git has shared alternates but no equivalent of `--dissociate`; expiring the cache would corrupt active worktrees. `9c5f6a0` intentionally dropped the Git cache and retained only persistent container volumes. **Status:** `superseded`, not proven “reverted.” | Never accept clone acceleration that makes task correctness depend on an expiring cache. Independence beats reuse. |
|
||||
| Shell git replaced by go-git, 2026-07-28 | `9c5f6a0` removed token-bearing child environments and no-context shell calls. Porting exposed host GPG inheritance, sentinel tracking, and merge-base diff semantics. | The port stopped at a compiling sibling package: `0a813fb` then found worktree RPC handlers using `context.Background`, making in-process clones unbounded. **Status:** `current` go-git design with settled follow-up. | Audit every adapter and cancellation boundary after replacing a killable subprocess with in-process I/O. Rebuild tests against the new implementation rather than letting old binaries skip them. |
|
||||
|
||||
## Chronicle: cleanup, artifacts, and contradictory policy
|
||||
|
||||
| Incident and date | Symptom | Attempted solution and root cause | Evidence and status | Settled rule |
|
||||
|---|---|---|---|---|
|
||||
| Tracked `.gotmp`, 2026-07-27 | Go build-cache binaries, generated `_testmain.go`, and `.git-askpass` appear in commits. | **Attempt:** use repo-local `.gotmp` to work around tmpfs quota, then broad `git add -A`. **Cause:** the workaround path was not ignored before use. | `da61e4e`/`f715db2` introduced artifacts; `4cb0577` removes them and adds `.gotmp/` to `.gitignore`. Live tracked count is zero. **Status:** `settled`. | Put caches outside the repo or ignore them before the first command. Scan tracked files before accepting a broad add. |
|
||||
| Tracked `docs-2/node_modules`, 2026-07-28 | Hundreds of pnpm symlink entries become repository content. | **Attempt:** broad `308c199` cleanup/documentation commit. **Cause:** `docs-2/node_modules` was neither ignored nor excluded from the commit. | `git ls-files 'docs-2/node_modules/**'` reports 237 entries at `HEAD`; `.gitignore` has no `node_modules` rule. **Status:** `current/open`. | Track lockfiles, never installed dependency trees. Add the ignore before installation and verify tracked counts are zero. |
|
||||
| `308c199` cleanup regression, 2026-07-28 | `TestRunWrapsExternalCommand` returns `"\n"` instead of `"wrapped\n"`; forge compatibility is removed again; dependency artifacts are added. | **Attempt:** a 311-file cleanup/source-reference purge changed `exec.Command("echo", "wrapped")` to `exec.CommandContext(ctx, "sh", "-c", "echo", "wrapped")`, where `"wrapped"` becomes shell `$0`, and removed `Forge.TokenEnv`. **Cause:** semantic edits were classified and reviewed as cleanup. | `git show 308c199`; focused skillscript test fails at current `HEAD`; compare `HEAD:internal/config/config.go` with the dirty worktree; tracked node_modules count above. **Status:** `current/open`; do not assume dirty repairs are accepted. | No commit is “cleanup” for gating purposes. Classify each changed behavior, inspect every non-test semantic diff, run the full relevant suite, and scan artifact/compatibility deltas. |
|
||||
| `diff_cap_lines = 0` contradiction, introduced at project start and exposed 2026-07-23 | Operators set zero expecting unlimited, but decoded config becomes 400. | **Attempt:** `5d60e75` made `StageDiffCap` treat `<=0` as disabled and later Docker config used zero. **Cause:** `finalize` has always converted zero to the default 400, so the same sentinel means both “unset” and “unlimited.” | `internal/config/config.go` defaults zero to 400; `internal/workflow/steps.go` treats zero as unlimited; `config.example.toml` advertises 400. **Status:** `current/open` contradiction. | Never overload a zero value with both defaulting and explicit policy. Use presence-aware decoding or a distinct explicit value, then test config-to-runtime behavior end to end. |
|
||||
|
||||
## Keep unmerged work as dated candidates
|
||||
|
||||
As of **2026-07-28**, these remote branches are not merged into the checked-out
|
||||
`HEAD`. Their subjects and diffs are evidence of proposed fixes, not proof that
|
||||
the live defect or exact patch remains valid.
|
||||
|
||||
| Candidate branch | Claimed concern | Required reconciliation |
|
||||
|---|---|---|
|
||||
| `origin/fix/43-loaddir-no-timeout-around-yaegi-eval-can-hang-daemon-startup` | Bound Yaegi evaluation during `LoadDir` | Compare current `internal/yaegiutil`, plugin startup, cancellation, and tests before adopting. |
|
||||
| `origin/fix/45-skillscriptrun-ignores-context-cannot-be-canceledtimed-out` | Make skill scripts cancellable | Reconcile with current `skillscript.Run` API and the `308c199` failing test. |
|
||||
| `origin/fix/48-transition-ignores-from-status-guard-allowing-lost-updates` | Enforce expected source state atomically | Compare both SQLite and NellDB transition/audit semantics; do not patch only one backend. |
|
||||
| `origin/fix/52-handlesse-silently-swallows-eventssince-backlog-fetch-errors` | Surface SSE backlog query errors | Recheck current web handler composition and observable HTTP behavior. |
|
||||
| `origin/feat/51-no-test-coverage-for-stagestats-query` | Add `StageStats` query coverage | Treat as test-only candidate; verify query/schema drift. |
|
||||
| `origin/feat/75-add-mcp-client-capabilities-to-archied-and-archie-agent` | Wire MCP through both execution modes | Live `HEAD` already contains later MCP/provider work; compare behavior, never cherry-pick the branch wholesale. |
|
||||
|
||||
Verify candidate state:
|
||||
|
||||
```sh
|
||||
git branch -r --no-merged HEAD
|
||||
git log -1 --date=iso-strict --format='%H %ad %s' <branch>
|
||||
git diff --stat HEAD...<branch>
|
||||
git merge-base --is-ancestor <branch> HEAD
|
||||
```
|
||||
|
||||
If equivalent behavior exists on `HEAD`, mark the branch `superseded`, not
|
||||
merged. If no current reproduction exists, leave it `candidate`.
|
||||
|
||||
## Produce the archaeology handoff
|
||||
|
||||
Return:
|
||||
|
||||
1. observation commit and dirty paths;
|
||||
2. exact symptom and current call path;
|
||||
3. the closest incident packet with all six fields;
|
||||
4. differences between the historical and current assemblies;
|
||||
5. status using the taxonomy;
|
||||
6. forbidden wrong paths derived from the settled rule;
|
||||
7. one focused reproduction command;
|
||||
8. the sibling skill that owns the next step.
|
||||
|
||||
Never end with “probably the same bug.” State what is proven, what is inferred,
|
||||
and what remains unknown.
|
||||
|
||||
## Provenance and maintenance
|
||||
|
||||
Re-verify the chronology: `git log --all --date=iso-strict --format='%H %ad %s' -- cmd internal config.docker.toml docker-compose.yml go.mod .gitignore`
|
||||
|
||||
Re-verify a transition: `git show --no-ext-diff --format=fuller --stat <commit> && git merge-base --is-ancestor <commit> HEAD`
|
||||
|
||||
Re-verify live incident anchors: `rg -n 'selfNetwork|TokenEnv|FullStream|readMessage|BuildNoChanges|maybeRetryParked|DiffCapLines|prefetchTimeout|nolint:nilerr' cmd internal`
|
||||
|
||||
Re-verify dependency locality: `rg -n '^replace|/work/apps|/work/projects' go.mod tools/go.mod`
|
||||
|
||||
Re-verify tracked artifact counts: `git ls-files '.gotmp/**' 'docs-2/node_modules/**'`
|
||||
|
||||
Re-verify branch-only candidates: `git branch -r --no-merged HEAD`
|
||||
|
||||
Re-verify the current cleanup regression: `env GOCACHE=/tmp/archie-archaeology-gocache GOTMPDIR=/tmp go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v`
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Archie Failure Archaeology"
|
||||
short_description: "Avoid repeating Archie failure history"
|
||||
default_prompt: "Use $archie-failure-archaeology to trace this symptom through Archies proven incidents before proposing a fix."
|
||||
@@ -0,0 +1,357 @@
|
||||
---
|
||||
name: archie-nelldb
|
||||
description: >-
|
||||
Maintain, debug, review, or migrate Archie's current NellDB-backed
|
||||
persistence. Load this skill when touching internal/nell, store.TaskStore,
|
||||
db_path, the tasks/events/sessions/messages collections, persisted task or
|
||||
event fields, document IDs, _rev or HLC conflicts, scans and ordering,
|
||||
restart recovery, SQLite-to-NellDB compatibility, backfills, or the pinned
|
||||
NellDB dependency; also load it when tasks, events, identities, or chat
|
||||
history disappear, duplicate, reorder, fail to transition, or fail to
|
||||
survive restart.
|
||||
---
|
||||
|
||||
# Archie NellDB
|
||||
|
||||
Treat Archie's database as domain state behind an application adapter. Do not
|
||||
treat it as a generic JSON map, a SQLite file with a new driver, or proof that
|
||||
the target persistence architecture already exists.
|
||||
|
||||
## Route before acting
|
||||
|
||||
Use this skill for NellDB mechanics and Archie's current adapter.
|
||||
|
||||
Do **not** use it alone to:
|
||||
|
||||
| Need | Load instead or as well |
|
||||
| --- | --- |
|
||||
| Define general Archie terms such as Identity, Agent, Message, or WorkflowExecution | `archie-domain-reference` |
|
||||
| Find every caller, data path, generated consumer, or dead adapter | `archie-codebase-discovery` |
|
||||
| Decide the target repository, state machine, event model, or migration boundary | `archie-architecture-planning-campaign` and `archie-architecture-contract` |
|
||||
| Add or reinterpret `db_path`, `bot_user`, or another setting | `archie-config-and-flags` |
|
||||
| Triage a running daemon, damaged deployment, or missing volume | `archie-debugging-playbook` and `archie-run-and-operate` |
|
||||
| Accept a storage change, migration, or dependency upgrade | `archie-validation-and-qa` and `archie-change-control` |
|
||||
|
||||
Stop and route to architecture planning when the requested change would define
|
||||
atomic state-plus-event persistence, WorkflowExecution storage, identity-aware
|
||||
keys, session/message migration, or a new process boundary. Those are OPEN
|
||||
migration decisions, not adapter cleanup.
|
||||
|
||||
## Use the vocabulary precisely
|
||||
|
||||
| Term | Meaning in this repository |
|
||||
| --- | --- |
|
||||
| `store.TaskStore` | Archie's current application-facing task, query, event, and lifecycle interface in `internal/store/interface.go`. |
|
||||
| NellDB engine | The pinned `github.com/samcharles93/NellDB` `Store` layer: records, collections, HLC ordering, conflict resolution, and storage backends. |
|
||||
| `LogStore` | NellDB's persistent append-only, Zstd-framed implementation opened by `logstore.OpenLog`. |
|
||||
| `sdk.DocDB` | NellDB's document adapter over one named collection. It maps `sdk.Doc` values to engine records and maintains `_rev` bookkeeping. |
|
||||
| Collection | A namespace in the engine. The engine key is `collection + ":" + record ID`. |
|
||||
| Document ID | The application key stored in reserved field `_id`; it is distinct from `store.Task.ID`. |
|
||||
| Revision (`_rev`) | An SDK MVCC token of form `<generation>-<sha1>`. It detects an explicitly stale local document write; it is not a domain version. |
|
||||
| HLC | NellDB's hybrid logical clock: Unix milliseconds plus a logical counter, used for engine ordering. |
|
||||
| Node ID | The writer string stamped into `UpdatedBy`. Archie currently passes `cfg.BotUser`; `LogStore` uses the value supplied at each open. |
|
||||
| LWW | Engine-level last-write-wins: higher HLC wins; equal HLC uses lexically larger `UpdatedBy`. |
|
||||
| Tombstone | A record with `Deleted=true`. Normal `Get`/`List` hides it, but it remains in the append-only log until compaction. |
|
||||
| Backfill | An explicit, restartable conversion of already-persisted data. Adding a decoder default is compatibility, not a backfill. |
|
||||
|
||||
Never transfer SQL transactions, constraints, `ORDER BY`, WAL, row counts, or
|
||||
index behavior to NellDB by analogy.
|
||||
|
||||
## Establish CURRENT production truth
|
||||
|
||||
The following snapshot was verified on **2026-07-28**:
|
||||
|
||||
```text
|
||||
config.LoadOverlay
|
||||
-> cfg.DBPath and cfg.BotUser
|
||||
-> nell.OpenStore
|
||||
-> logstore.OpenLog
|
||||
-> one underlying NellDB Store
|
||||
-> "tasks" DocDB
|
||||
-> "events" DocDB
|
||||
-> "sessions" DocDB when Telegram is configured
|
||||
-> "messages" DocDB when Telegram is configured
|
||||
```
|
||||
|
||||
| Fact | Current evidence | Consequence |
|
||||
| --- | --- | --- |
|
||||
| `cmd/archied/main.go` unconditionally opens `nell.OpenStore(cfg.DBPath, cfg.BotUser)`. | `cmd/archied/main.go` | NellDB is the production task/event backend. There is no runtime backend selector. |
|
||||
| `internal/store.Store` still implements `TaskStore` using SQLite. | `internal/store/{interface,store,events}.go` | SQLite remains a test/legacy implementation, not a production fallback. |
|
||||
| The same engine is lent to `gateway.NewSessionStore` only inside Telegram wiring. | `cmd/archied/main.go`; `internal/gateway/session_store.go` | Tasks/events always use NellDB; session/message collections exist only when that path writes them. |
|
||||
| `go.mod` pins `github.com/samcharles93/NellDB v0.2.5` with no `replace`. | `go.mod`; `go.sum` | Review behavior against the published v0.2.5 source, not a local Nell checkout. |
|
||||
| Archie does not call NellDB replication, compaction, changes-feed, or vector-search APIs. | No production matches for those APIs | Do not claim those engine features are active Archie behavior. |
|
||||
| Several comments and older architecture documents still say SQLite. | `cmd/archied/main.go`; `ARCHITECTURE.md` | Follow production construction and code, not stale storage nouns in prose. |
|
||||
|
||||
Verify the dependency without network access:
|
||||
|
||||
```bash
|
||||
go list -m -f '{{.Path}} {{.Version}}{{if .Replace}} => {{.Replace.Path}} {{.Replace.Version}}{{end}}' github.com/samcharles93/NellDB
|
||||
rg -n '^replace .*NellDB|github.com/samcharles93/NellDB' go.mod go.sum
|
||||
go list -m -f '{{.Dir}}' github.com/samcharles93/NellDB
|
||||
```
|
||||
|
||||
Expected first-line result on this snapshot:
|
||||
|
||||
```text
|
||||
github.com/samcharles93/NellDB v0.2.5
|
||||
```
|
||||
|
||||
If a `=> /local/path` suffix appears, stop. Commit `07fb291` removed exactly
|
||||
that failure mode after a local replace made the CI Docker build unable to
|
||||
resolve `/work/apps/nell-engine` and left deployment stale.
|
||||
|
||||
## Separate engine guarantees from Archie guarantees
|
||||
|
||||
| Concern | NellDB v0.2.5 proves | Archie currently adds or fails to add |
|
||||
| --- | --- | --- |
|
||||
| Concurrency | `MemoryStore`, `LogStore`, and `DocDB` protect individual calls with mutexes. | `Adapter.mu` serializes selected multi-call operations in one adapter instance only. It is not a file lock or distributed transaction. |
|
||||
| Document conflicts | Supplying stale `_rev` to `DocDB.Put` returns `sdk.ErrConflict`. Omitting `_rev` continues from the SDK's current local revision. | Adapter helpers usually re-read a current document before `Put`; this can avoid a conflict while still copying stale application fields. |
|
||||
| Cross-node conflict | Engine `Put` applies HLC LWW, then lexical `UpdatedBy` tie-break. | No Archie replication path is wired. Do not present LWW as an enforced task state machine. |
|
||||
| Persistence | Default `OpenLog` appends a frame and flushes the buffered writer on each write. `Close` flushes again. | Archie defers one adapter close. No application checkpoint, snapshot, or compaction service is wired. |
|
||||
| Crash behavior | Replay rebuilds the in-memory index. An incomplete tail frame is ignored. | `Daemon.Startup` separately calls `RecoverStale`, changing every `running` task to `queued`. |
|
||||
| Power loss | Neither default flush nor group commit calls `fsync`. | Archie adds no explicit sync. Do not promise power-loss durability. |
|
||||
| Deletes | `Remove` writes a tombstone; ordinary list/get operations hide it. | `ClearTerminalTasks` tombstones terminal task documents. File space is not reclaimed because Archie never calls compaction. |
|
||||
| Queries | The engine indexes collection membership and HLC changes. `Query` is a collection-list stub; vector search is a linear scan. | The adapter performs field queries by collection scans. Gateway message search uses substring matching, not NellDB vector search. |
|
||||
| Listing | `AllDocs` returns a snapshot filtered after `Store.List`; range results are not sorted by key. | Task/event methods sort when their contract needs it. Session/message code currently assumes ordering in places where the SDK does not guarantee it. |
|
||||
| Node identity | Records retain their `UpdatedBy`; conflict resolution uses it. | `LogStore.NodeID()` returns the value passed to the current open. Changing `bot_user` changes future writer identity. |
|
||||
|
||||
Do not open the same log file from multiple processes or adapter instances and
|
||||
assume `Adapter.mu` coordinates them. No cross-process lock or supported
|
||||
multi-writer assembly is proven in Archie or the pinned `LogStore`.
|
||||
|
||||
## Know the stored shapes
|
||||
|
||||
### Collections and keys
|
||||
|
||||
| Collection | Document ID | Application data | Read pattern |
|
||||
| --- | --- | --- | --- |
|
||||
| `tasks` | `<owner>:<repo>:<issue_number>` | Current `store.Task` fields plus `created_at` | Direct `Get` by forge coordinates; scans for numeric task ID, status, claims, counts, and stats |
|
||||
| `events` | `event:<numeric-id>` | `events.Event`; `data` is stored as a JSON string | Full scan, application filter, then explicit ID sort |
|
||||
| `sessions` | `SessionContext.SessionID` | platform, bot, channel, optional thread, timestamps | Direct `Get`; full scan for list/channel lookup |
|
||||
| `messages` | `<session-id>:<20-digit-sequence>` | session, sequence, sender, text, channel/thread, timestamp | Collection scan plus key-range filter |
|
||||
|
||||
Each `DocDB` may also contain SDK IDs `meta:clock` and `meta:vector`. Archie adds
|
||||
`meta:task_id_counter` and `meta:event_id_counter`. The adapters skip IDs with
|
||||
the `meta:` prefix.
|
||||
|
||||
Do not create an application ID beginning with `meta:`. As written,
|
||||
`isMetaKey` will also hide a legitimate task whose composite key begins
|
||||
`meta:` from scan-based claims and queries, even though direct `Get` can find
|
||||
it. Treat this as a CURRENT risk requiring a failing test before repair.
|
||||
|
||||
### Task document mapping
|
||||
|
||||
| Group | Fields |
|
||||
| --- | --- |
|
||||
| Reserved and local identity | `_id`, SDK-managed `_rev`, numeric `id`, `created_at` |
|
||||
| Source snapshot | `owner`, `repo`, `issue_number`, `title`, `body`, `labels`, `source`, `identity` |
|
||||
| Lifecycle | `status`, `attempt`, `retry_count`, `park_reason`, `watch_comment_id` |
|
||||
| Workflow/output | `workflow`, `stage`, `branch`, `plan`, `notes`, `pr_number`, `tokens_used`, `iterations` |
|
||||
|
||||
Apply these conversion rules:
|
||||
|
||||
- Store numeric fields as `int64`. `intField` accepts `float64`, `int64`,
|
||||
`int`, and `json.Number` because JSON document round trips may yield
|
||||
`float64`.
|
||||
- Treat a missing `source` as `forge`; `sourceOrDefault` preserves old
|
||||
documents.
|
||||
- Preserve `_id` and `_rev` by starting updates from `DocDB.Get`, not a fresh
|
||||
map.
|
||||
- Do not expect `created_at` in `store.Task`; `docToTask` currently discards it,
|
||||
and the Nell document has no `updated_at`.
|
||||
- Keep workflow `Update` restricted to its documented mutable subset. Do not
|
||||
silently let it rewrite identity, source coordinates, status, attempt, or
|
||||
retry state.
|
||||
|
||||
CURRENT defect: `EnqueueIssue` accepts `identity` but does not put `identity`
|
||||
into the Nell document. Forge tasks therefore read back with an empty identity.
|
||||
`EnqueueChatTask` does write both `source=chat` and `identity`, and subsequent
|
||||
helpers preserve those existing fields. Do not quote target identity
|
||||
documentation as proof that forge identity round-trips.
|
||||
|
||||
### Event document mapping
|
||||
|
||||
`InsertEvent` stores:
|
||||
|
||||
```text
|
||||
id, at, kind, task_id, repo, issue, workflow, stage, detail, data
|
||||
```
|
||||
|
||||
It clips `detail` to 4000 bytes without splitting a UTF-8 rune. It serializes
|
||||
`data` to a JSON string and substitutes a `marshal_error` object when
|
||||
marshalling fails. `docToEvent` ignores invalid timestamps and invalid `data`
|
||||
JSON rather than returning conversion errors.
|
||||
|
||||
Events are observability records, not atomic task-transition history. Nell
|
||||
`Transition` ignores `detail`, and the event sink writes asynchronously through
|
||||
the event bus. Never claim task state and its event were committed together.
|
||||
|
||||
## Audit lifecycle and atomicity before editing
|
||||
|
||||
| Operation | Current serialization | Important limit |
|
||||
| --- | --- | --- |
|
||||
| `ClaimNext`, `ClaimByIssue` | Entire scan/get plus task write under `Adapter.mu` | Atomic only against operations using the same mutex on the same adapter instance. |
|
||||
| Task/event ID allocation | Counter read-modify-write under `Adapter.mu` | Enqueue's duplicate check is outside the critical section; a duplicate concurrent enqueue is not proven idempotent. |
|
||||
| `RecoverStale`, `ClearTerminalTasks` | Full scan and writes under `Adapter.mu` | `Transition`, `Update`, and `Requeue` do not take this mutex. |
|
||||
| `Transition` | Find by numeric ID, set `Status`, put | Ignores `from` and `detail`; writes no transition record; has no adapter lock. |
|
||||
| `Requeue` | Find, mutate several fields, put | Ignores `fromStatus`; writes no transition record; has no adapter lock. |
|
||||
| `Update` | Get by composite key, replace allowed fields, put | One document write, but no domain state/event transaction. |
|
||||
| `IncrementRetryCount` | Find, increment, put | Multi-call read-modify-write without adapter lock. |
|
||||
| `InsertEvent` | ID allocation and put under `Adapter.mu` | Separate from the state mutation that caused the event. |
|
||||
|
||||
The method name `Transition` does not make a state machine. A correct target
|
||||
must compare expected state/version, enforce legal transitions, and commit the
|
||||
authoritative domain event with state at one proven atomic boundary. Design
|
||||
that through the architecture campaign; do not patch only one caller.
|
||||
|
||||
## Investigate without damaging the log
|
||||
|
||||
Start read-only:
|
||||
|
||||
```bash
|
||||
rg -n 'OpenStore|NewSessionStore|TaskStore|DBPath' cmd/archied internal
|
||||
rg -n 'func \\(a \\*Adapter\\)|sdk\\.New|AllDocs|FieldID|isMetaKey' internal/nell/adapter.go
|
||||
rg -n 'SaveMessage|RecentMessages|SearchMessages|sdk\\.New' internal/gateway/session_store.go
|
||||
rg -n 'store\\.Open\\(|nell\\.OpenStore\\(' --glob '*.go'
|
||||
```
|
||||
|
||||
Inspect a configured file without opening it through either database:
|
||||
|
||||
```bash
|
||||
# Assign from the approved effective config before running
|
||||
: "${DB_PATH:?set DB_PATH from the running config's db_path field}"
|
||||
test -r "$DB_PATH" || { echo "DB_PATH is not readable: $DB_PATH" >&2; exit 1; }
|
||||
test -f "$DB_PATH" || { echo "DB_PATH is not a regular file: $DB_PATH" >&2; exit 1; }
|
||||
file -- "$DB_PATH"
|
||||
od -An -tc -N16 -- "$DB_PATH"
|
||||
stat -- "$DB_PATH"
|
||||
```
|
||||
|
||||
Never run `sqlite3 "$DB_PATH"` merely because the name ends in `.db`. A current
|
||||
NellDB file is a Zstd-framed binary append log. Conversely, never pass a legacy
|
||||
SQLite file to `nell.OpenStore`; there is no format detector or automatic
|
||||
migration.
|
||||
|
||||
Use focused executable evidence:
|
||||
|
||||
```bash
|
||||
go test ./internal/nell -run '^(TestEnqueueIdempotent|TestChatTaskLifecyclePreservesRouting|TestPersistenceAcrossRestart|TestConcurrentEnqueueAndClaim)$' -count=1
|
||||
go test -race ./internal/nell ./internal/gateway -count=1
|
||||
go test ./internal/store ./internal/nell -count=1
|
||||
go test ./cmd/archied -run '^TestChatTaskCommandsEndToEnd$' -count=1
|
||||
```
|
||||
|
||||
As verified on 2026-07-28, those focused commands pass in an environment with
|
||||
writable Go caches. If the workspace points Go temporary files at a read-only
|
||||
directory, rerun without changing repository files:
|
||||
|
||||
```bash
|
||||
mkdir -p /tmp/archie-nelldb-gotmp /tmp/archie-nelldb-gocache
|
||||
env GOTMPDIR=/tmp/archie-nelldb-gotmp GOCACHE=/tmp/archie-nelldb-gocache go test -race ./internal/nell ./internal/gateway -count=1
|
||||
```
|
||||
|
||||
`internal/storerpc` tests also require a local NATS listener. A panic saying the
|
||||
embedded NATS server could not start is environment evidence until reproduced
|
||||
where listener creation is allowed.
|
||||
|
||||
## Change persisted data safely
|
||||
|
||||
Follow this checklist for every field, key, collection, or dependency change:
|
||||
|
||||
- [ ] Name the domain owner and distinguish CURRENT behavior from APPROVED
|
||||
TARGET and OPEN migration work.
|
||||
- [ ] Trace every producer, converter, reader, projection, RPC payload, JSON
|
||||
consumer, test backend, and production constructor.
|
||||
- [ ] State what the new data supersedes and when the old field/path is deleted.
|
||||
- [ ] Add a red test using an old document with the field absent.
|
||||
- [ ] Add red round-trip tests for both forge and chat sources when task data is
|
||||
involved.
|
||||
- [ ] Update every creation path, `docToTask`, `taskFields`, and the restricted
|
||||
`Update` set only when that operation owns the field.
|
||||
- [ ] Preserve `_id` and `_rev`; never “fix” conflicts by deleting `_rev`.
|
||||
- [ ] Give missing or legacy data an explicit compatibility rule. Label any
|
||||
guessed default OPEN.
|
||||
- [ ] Check the SQLite implementation deliberately: schema, additive migration,
|
||||
every `SELECT`/`Scan`, query projections, and tests. Either preserve contract
|
||||
parity or document and prove a completed cutover.
|
||||
- [ ] Test field preservation through claim, transition, requeue, retry,
|
||||
recovery, update, delete, close, and reopen as applicable.
|
||||
- [ ] Add stale-revision, concurrent-writer, cancellation, malformed-value, and
|
||||
restart cases. A race-clean engine call does not prove a multi-call
|
||||
application operation is atomic.
|
||||
- [ ] Measure scans at representative collection sizes before accepting another
|
||||
scan or claiming current scale makes it safe.
|
||||
- [ ] Run the focused tests, then route final evidence through
|
||||
`archie-validation-and-qa` and `archie-change-control`.
|
||||
|
||||
Use a shared backend contract test suite when changing `TaskStore`. Current
|
||||
tests are split between `internal/store` and `internal/nell`; there is no single
|
||||
factory-driven suite proving identical semantics.
|
||||
|
||||
## Gate migration and backfill explicitly
|
||||
|
||||
There is no repository-supported SQLite-to-NellDB migration or backfill command
|
||||
as of 2026-07-28. Do not invent an operator command in a runbook.
|
||||
|
||||
Require this sequence before any cutover:
|
||||
|
||||
1. Freeze the authoritative source or define a proven dual-write protocol.
|
||||
2. Keep the SQLite input and NellDB output at different paths. Never convert in
|
||||
place.
|
||||
3. Inventory task rows, numeric IDs, source coordinates, statuses, mutable
|
||||
fields, event IDs/timestamps/data, and SQLite transition history.
|
||||
4. Decide explicitly where transition history goes; the current Nell adapter
|
||||
has no equivalent collection.
|
||||
5. Include sessions/messages only if the chosen source actually contains them;
|
||||
current Nell gateway data has no SQLite equivalent in this repository.
|
||||
6. Build a dry-run exporter/importer with schema/version identification,
|
||||
deterministic IDs, idempotent writes, checkpoints, and rejection reporting.
|
||||
7. Compare counts by status/source/workflow plus stable content digests. Test
|
||||
close/reopen and crash-resume from every checkpoint.
|
||||
8. Quiesce, copy, convert, validate through public application reads, then
|
||||
switch `db_path` once.
|
||||
9. Retain the untouched source and a last-known-good binary/config until the
|
||||
observation window passes.
|
||||
10. Delete the old reader or compatibility path only after production wiring,
|
||||
rollback evidence, and change control prove the cutover complete.
|
||||
|
||||
Treat NellDB `PutMany` as sequential engine writes, not a crash-atomic
|
||||
transaction. Its SDK cache rollback does not undo records already written to
|
||||
`MemoryStore` or `LogStore`.
|
||||
|
||||
## Triage by symptom
|
||||
|
||||
| Symptom | Prove first | Likely CURRENT seam |
|
||||
| --- | --- | --- |
|
||||
| `nell: path is required` | Trace `cfg.DBPath` and the direct caller. | `OpenStore` rejects an empty path; normal config finalization supplies a default. |
|
||||
| `nell: open log: log: open ... no such file or directory` | Check the parent directory, mount, UID, and `db_path`. | `OpenStore` does not create the parent directory; unlike SQLite `store.Open`, it calls `os.OpenFile` directly. |
|
||||
| Old tasks vanish after the backend switch | Inspect file signature and exact configured path; do not start another writer. | No SQLite import or format check exists. |
|
||||
| Forge task identity is empty after reload | Compare enqueue arguments with the Nell document constructor. | `EnqueueIssue` currently drops `identity`; chat enqueue does not. |
|
||||
| A stale or illegal transition succeeds | Read `Transition` and capture before/after state. | `from` is currently unused in both Nell and SQLite implementations. |
|
||||
| State changed but no matching history/detail exists | Trace state write and event sink independently. | Nell transition history is absent; observability event persistence is asynchronous. |
|
||||
| A directly addressable queued task is never claimed | Check whether its document ID begins `meta:`. | Scan paths filter every `meta:` prefix as internal. |
|
||||
| Recent messages reorder or omit expected turns | Test more than one insertion order and restart. | `RecentMessages` assumes key-sorted `AllDocs`; v0.2.5 range results are not sorted. No message persistence tests exist. |
|
||||
| `sdk: revision conflict` | Preserve the conflicting docs/revisions and identify both writers. | A stale explicit `_rev` was supplied. Re-read and recompute only if the domain command is safe to retry. |
|
||||
| Database grows after updates/deletes | Compare file size with live document counts. | Append-only versions and tombstones accumulate; Archie wires no compaction. |
|
||||
| Data survives process restart but not host power loss | Separate close/replay evidence from storage durability evidence. | Default writes flush but do not `fsync`. |
|
||||
| NellDB SDK dependency tests fail on `server/webui/dist/nell.wasm` | Run Archie's focused packages and inspect the downloaded module archive. | Published v0.2.5 omits that embedded WASM asset; `go test github.com/samcharles93/NellDB/logstore` passes, while SDK tests cannot compile from the module cache. |
|
||||
| A fix exists on another branch but main still fails | Inspect current source and branch containment. | Candidate or branch-only code is not live behavior. Never document it as fixed until merged and reverified. |
|
||||
|
||||
Escalate damaged-file handling to `archie-run-and-operate`. The pinned engine
|
||||
proves incomplete-tail tolerance; it does not prove arbitrary corruption can be
|
||||
repaired or that silently skipped data is acceptable.
|
||||
|
||||
## Provenance and maintenance
|
||||
|
||||
Volatile facts and focused tests in this skill were reverified on 2026-07-28.
|
||||
Reverify after any change to `go.mod`, `cmd/archied/main.go`, `internal/nell`,
|
||||
`internal/store`, `internal/gateway/session_store.go`, or the NellDB version.
|
||||
|
||||
```bash
|
||||
go list -m -f '{{.Path}} {{.Version}}{{if .Replace}} => {{.Replace.Path}}{{end}}' github.com/samcharles93/NellDB
|
||||
rg -n 'nell\\.OpenStore|NewSessionStore|store\\.Open\\(' cmd internal --glob '*.go'
|
||||
rg -n 'func \\(a \\*Adapter\\)|sdk\\.New|AllDocs|isMetaKey|identity' internal/nell/adapter.go
|
||||
go test ./internal/nell ./internal/gateway -count=1
|
||||
go test -race ./internal/nell ./internal/gateway -count=1
|
||||
git log --all --oneline -- go.mod internal/nell internal/store internal/gateway/session_store.go
|
||||
```
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Archie NellDB"
|
||||
short_description: "Maintain Archie persistence on NellDB safely"
|
||||
default_prompt: "Use $archie-nelldb to inspect or change Archie persistence without importing SQLite assumptions."
|
||||
@@ -0,0 +1,359 @@
|
||||
---
|
||||
name: archie-research-methodology
|
||||
description: Turn an Archie architecture, maintainability, performance, persistence, configuration, protocol, concurrency, or migration hunch into reproducible evidence and an accountable decision. Use before advocating a redesign, accepting a surprising test result, claiming code is duplicate or dead, comparing execution modes or stores, measuring NellDB scans, validating an external protocol, or promoting a candidate fix; also use when a green TDD result does not prove production wiring or design quality.
|
||||
---
|
||||
|
||||
# Research Archie with falsifiable evidence
|
||||
|
||||
Use research to expose a decision, not to decorate a preferred answer. Ask one
|
||||
vertical question, predict an observable result before measuring, preserve
|
||||
failures and negative results, and hand any resulting change to Archie's change
|
||||
control. Optimize for a small meaningful answer that improves the architecture
|
||||
ledger.
|
||||
|
||||
All volatile repository observations in this skill were verified on
|
||||
**2026-07-28**. Re-run the provenance commands before treating them as current.
|
||||
|
||||
## Route the work
|
||||
|
||||
| Need | Load instead or alongside |
|
||||
|---|---|
|
||||
| Trace entry points, types, callers, registrations, and complete change cones | `archie-codebase-discovery` |
|
||||
| Collect repeatable counts, coverage, timings, profiles, or runtime diagnostics | `archie-diagnostics-and-tooling` |
|
||||
| Decide boundaries, ownership, target packages, and migration slices | `archie-architecture-planning-campaign` |
|
||||
| Reconstruct an earlier failure, rejected fix, revert, or branch-only candidate | `archie-failure-archaeology` |
|
||||
| Decide test sufficiency and acceptance thresholds | `archie-validation-and-qa` |
|
||||
| Classify, authorize, review, or accept a change | `archie-change-control` |
|
||||
| Assign ownership, supersession, deletion criteria, and maintainability debt | `archie-technical-accountability` |
|
||||
|
||||
Do **not** use this skill to implement the hypothesized fix, to operate
|
||||
production, or to replace NellDB domain knowledge. Use `archie-nelldb` for the
|
||||
database model and `archie-run-and-operate` for live operations. Stop the
|
||||
research pass before mutation.
|
||||
|
||||
## Define the terms once
|
||||
|
||||
- **Question**: one uncertainty whose answer changes a design or acceptance
|
||||
decision.
|
||||
- **Hypothesis**: a falsifiable explanation, written before the experiment.
|
||||
- **Prediction**: a number, relation, state, byte sequence, error, or call path
|
||||
that must be observed if the hypothesis is correct.
|
||||
- **Falsifier**: an observation that rejects the hypothesis. “The test fails”
|
||||
is too vague; name the failure that matters.
|
||||
- **Baseline**: the unchanged tree, environment, mode, data, and measurements
|
||||
against which a treatment is compared.
|
||||
- **Treatment**: the one intentional difference between baseline and
|
||||
comparison.
|
||||
- **Control**: an unchanged case that detects a broken fixture or measurement.
|
||||
- **Confounder**: another difference that could explain the result.
|
||||
- **Replication**: a repeat from the same frozen inputs.
|
||||
- **Triangulation**: evidence from a different mechanism that does not share
|
||||
the first mechanism's assumptions or helpers.
|
||||
- **Decision gate**: a predeclared rule that maps observed evidence to proceed,
|
||||
reject, redesign, or investigate.
|
||||
|
||||
## Keep current and target truth separate
|
||||
|
||||
Maintain two columns throughout the record:
|
||||
|
||||
| Ledger | Authority | Permitted conclusion |
|
||||
|---|---|---|
|
||||
| Current implementation | Checked-out production composition, source, tests, deployed assembly evidence, and captured runtime behavior | What this exact tree and assembly do now |
|
||||
| Approved target | `docs/prds/01-project-management.md` and status-qualified documents under `docs/prds/architecture/` | What the project requires or has deliberately left open |
|
||||
|
||||
Treat `ARCHITECTURE.md`, comments, commit messages, Beads history, unmerged
|
||||
branches, and proposals as leads until reconciled with those ledgers. An
|
||||
approved target is authoritative for direction but is never evidence that the
|
||||
live implementation already satisfies it.
|
||||
|
||||
Use these claim labels:
|
||||
|
||||
- `observed-current`: directly reproduced or traced in the frozen tree;
|
||||
- `approved-target`: required by a status-qualified target document;
|
||||
- `candidate`: plausible and worth testing, but not accepted;
|
||||
- `open`: evidence is insufficient or contradictory.
|
||||
|
||||
## Apply the evidence hierarchy
|
||||
|
||||
Match evidence to the claim. Do not add two correlated tests and call them
|
||||
independent.
|
||||
|
||||
| Rank | Evidence | What it can prove | Required caution |
|
||||
|---:|---|---|---|
|
||||
| 1 | Captured behavior from the exact binary/config/data plus a trace through live production composition and source | What the named assembly selected and did | Record version, mode, inputs, secrets redacted, and environment; one deployment is not universal |
|
||||
| 2 | Independent protocol peer, official SDK, published conformance vector, or raw fixture captured outside Archie's helpers | Interoperability at an external boundary | Pin peer/version and preserve bytes or messages |
|
||||
| 3 | Integration, composition, legal-transition, deterministic concurrency, cancellation, recovery, and race evidence | Behavior across real internal boundaries and schedules | Prove the test uses the production handoff rather than a parallel constructor |
|
||||
| 4 | Focused unit tests, benchmarks, AST/type queries, lint findings, coverage, and source inspection | Local behavior and structural candidates | Do not infer production use, ownership, absence, or protocol compatibility |
|
||||
| 5 | Current docs, history, incident reports, issue records, branches, and proposals | Intent, constraints, and candidate explanations | Reconcile with live code; never present a candidate as current |
|
||||
|
||||
For a current-code claim, include at least one live composition/source trace and
|
||||
one independently produced check. For an external protocol claim, include Rank
|
||||
2. For a concurrency claim, include deterministic ordering plus `-race`.
|
||||
|
||||
## Run the decision-gated method
|
||||
|
||||
### Gate 0 — Declare one vertical question
|
||||
|
||||
Write one sentence:
|
||||
|
||||
> Determine whether `<current mechanism>` causes `<observable outcome>` under
|
||||
> `<named mode/input/state>`, so we can decide `<specific architecture or
|
||||
> maintenance action>`.
|
||||
|
||||
Require:
|
||||
|
||||
- question count: exactly `1`;
|
||||
- named decision owner: exactly `1`;
|
||||
- implementation edits during research: `0`;
|
||||
- meaningful falsifiers: at least `1`;
|
||||
- explicit non-goals: at least `1`.
|
||||
|
||||
Split the work if the question contains “and” between independently testable
|
||||
behaviors. A short success must still traverse one complete path from real
|
||||
input through ownership and state to observable outcome.
|
||||
|
||||
### Gate 1 — Freeze the observation point
|
||||
|
||||
Run from the repository root before changing anything:
|
||||
|
||||
```bash
|
||||
git rev-parse HEAD
|
||||
git status --short
|
||||
go version
|
||||
go env GOMOD GOWORK GOOS GOARCH CGO_ENABLED GOTMPDIR GOCACHE
|
||||
go list -m -f '{{.Path}} {{.Version}} {{.GoVersion}}'
|
||||
find . \( -path './.git' -o -path './.references' -o -path './.claude/worktrees' -o -name node_modules \) -prune -o -name go.mod -print
|
||||
```
|
||||
|
||||
Record:
|
||||
|
||||
- commit and every dirty path;
|
||||
- Go/tool versions and module boundary;
|
||||
- operating system, architecture, sandbox/host, and resource restrictions;
|
||||
- execution mode and concrete implementation;
|
||||
- configuration source and relevant effective values, with secrets redacted;
|
||||
- data/fixture identity and size;
|
||||
- exact command, exit status, output, and run time.
|
||||
|
||||
The root and `tools/` directories are separate Go modules as of 2026-07-28.
|
||||
Never blend their results. Do not run `task check` to establish a read-only
|
||||
baseline: it runs `gofumpt -w`, `go fix`, and builds into `bin/`.
|
||||
|
||||
The focused command below currently fails with `Run() = "\n"`; preserve that
|
||||
signature as a real pre-existing code failure rather than an environmental
|
||||
confounder:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-research-gocache \
|
||||
GIT_CONFIG_GLOBAL=/dev/null go test ./internal/skillscript \
|
||||
-run '^TestRunWrapsExternalCommand$' -count=1 -v
|
||||
```
|
||||
|
||||
If the tree, dependency set, configuration, mode, fixture, or environment
|
||||
changes, invalidate the affected baseline and restart this gate.
|
||||
|
||||
### Gate 2 — Predict before measuring
|
||||
|
||||
State both the explanation and the null:
|
||||
|
||||
```text
|
||||
Hypothesis H1:
|
||||
Null H0:
|
||||
Mechanism:
|
||||
Primary metric/observable:
|
||||
Baseline prediction:
|
||||
Treatment prediction:
|
||||
Falsifier:
|
||||
Invariant predictions:
|
||||
```
|
||||
|
||||
Use numbers whenever the result is countable. If no dated baseline exists,
|
||||
write `predict before measurement`, choose the number or relation now, and only
|
||||
then run the command. Never backfill an “expected” value from the observed
|
||||
output.
|
||||
|
||||
Predict all of:
|
||||
|
||||
1. the primary result;
|
||||
2. one negative/control result;
|
||||
3. preserved behavior in every affected mode, adapter, or data form;
|
||||
4. the expected error or failure consequence;
|
||||
5. what result makes the experiment inconclusive.
|
||||
|
||||
### Gate 3 — Design independent controls
|
||||
|
||||
Build a matrix before execution:
|
||||
|
||||
| Variable | Baseline | Treatment | Held constant | Measurement |
|
||||
|---|---|---|---|---|
|
||||
| one intentional difference | exact value | exact value | commit, mode, data, tools, timeouts | exact command/output |
|
||||
|
||||
List confounders explicitly. Check at least:
|
||||
|
||||
- sandbox listener, process, keyring, Docker socket, and cache restrictions;
|
||||
- stale editor/compiler diagnostics versus a real `go build` or `go test`;
|
||||
- warm versus cold cache and network access;
|
||||
- test-only constructors versus production composition;
|
||||
- reused parsing, framing, constants, fixtures, or server helpers;
|
||||
- background goroutines, timing, retries, and global mutable state;
|
||||
- local module replacements and unpublished dependency checkouts;
|
||||
- dirty concurrent work and generated artifacts.
|
||||
|
||||
Require one control that would fail if the fixture or instrumentation were
|
||||
broken. For protocols, require an independently implemented peer. For
|
||||
architecture claims, require a source/type trace and a runtime or
|
||||
composition-level observation.
|
||||
|
||||
### Gate 4 — Execute without moving the target
|
||||
|
||||
Run the baseline first, then the treatment, then the baseline again when
|
||||
ordering or cache effects are plausible. Preserve raw output under a
|
||||
task-specific temporary path or in the controlled work artifact.
|
||||
|
||||
Do not:
|
||||
|
||||
- edit implementation, tests, config, fixtures, or success criteria mid-run;
|
||||
- discard outliers without a predeclared rule;
|
||||
- turn a failing hypothesis into a differently worded success;
|
||||
- replace a denied listener, missing peer, or cold dependency with a weaker
|
||||
test and claim equivalence.
|
||||
|
||||
If execution exposes a separate defect, freeze it as a new question. Do not
|
||||
fold its repair into the experiment.
|
||||
|
||||
### Gate 5 — Apply the predeclared decision
|
||||
|
||||
Classify the result exactly:
|
||||
|
||||
| Result | Action |
|
||||
|---|---|
|
||||
| Every prediction and invariant holds, controls work, and required evidence ranks are present | Mark `supported`, not “proven forever”; proceed to replication and change control |
|
||||
| A falsifier occurs with valid controls | Mark `falsified`; preserve the negative result and reject solutions depending on H1 |
|
||||
| Fixture, environment, baseline, independence, or statistical power is inadequate | Mark `inconclusive`; state the next evidence needed |
|
||||
| Current and target ledgers conflict | Record the migration gap; do not redefine either ledger |
|
||||
| Another mechanism explains the result equally well | Design a discriminating experiment; do not choose by preference |
|
||||
|
||||
Post-hoc success criteria count: `0`. Unexplained deviations count: `0`.
|
||||
|
||||
### Gate 6 — Replicate and triangulate
|
||||
|
||||
Repeat deterministic checks from a clean process. For variable measurements,
|
||||
declare the run count before starting and report every sample. Compare an
|
||||
independent mechanism:
|
||||
|
||||
- AST/type references versus runtime composition;
|
||||
- SQLite behavior versus NellDB behavior;
|
||||
- in-process behavior versus subprocess/NATS behavior;
|
||||
- raw protocol frames versus an official peer;
|
||||
- unit behavior versus race/integration behavior;
|
||||
- source expectation versus persisted reload/recovery.
|
||||
|
||||
If two checks share the same implementation helper, parser, mock, global, or
|
||||
fixture generator, treat them as one evidence source.
|
||||
|
||||
### Gate 7 — Preserve the reproducibility packet
|
||||
|
||||
Attach this compact record to the controlled issue, architecture handoff, or
|
||||
decision document selected by sibling skills. Do not create an orphan report.
|
||||
|
||||
```markdown
|
||||
## Research record R-<id>
|
||||
Question:
|
||||
Decision affected:
|
||||
Current claim / target claim:
|
||||
Tree: <commit>; dirty paths:
|
||||
Environment/mode/config/data:
|
||||
H1 / H0 / mechanism:
|
||||
Predictions: <metric | baseline | treatment | falsifier | invariants>
|
||||
Controls and confounders:
|
||||
Commands and raw-output locations:
|
||||
Observed results:
|
||||
Verdict: supported | falsified | inconclusive
|
||||
Independent evidence:
|
||||
Negative results and fenced paths:
|
||||
Open uncertainty:
|
||||
Owner and next gate:
|
||||
```
|
||||
|
||||
Preserve negative results with the same care as positive results. Route a
|
||||
recurring rejected approach to `archie-failure-archaeology`.
|
||||
|
||||
### Gate 8 — Hand off; do not self-approve
|
||||
|
||||
Send ownership/boundary conclusions to
|
||||
`archie-architecture-planning-campaign`. Send deprecation and deletion to
|
||||
`archie-technical-accountability`. Send tests and acceptance thresholds to
|
||||
`archie-validation-and-qa`, then route every behavior-changing proposal through
|
||||
`archie-change-control`.
|
||||
|
||||
Research acceptance does not authorize implementation, config mutation,
|
||||
dependency changes, deployment, data migration, or deletion. A fresh
|
||||
adversarial reviewer must be able to reproduce the packet without the
|
||||
researcher's unstated knowledge.
|
||||
|
||||
## Choose an Archie experiment
|
||||
|
||||
Write every `N`, `R`, `M`, latency, allocation, and ratio prediction before
|
||||
running its command.
|
||||
|
||||
| Question | Controlled method | Required prediction and falsifier |
|
||||
|---|---|---|
|
||||
| Are two paths duplicates? | Run `golangci-lint run --enable-only=dupl ./internal/<area>/...`; then trace both by domain effect, entrypoint, state mutation, mode, and consumer with `archie-codebase-discovery` | Predict textual candidates `N`, live authorities, and preserved differences. Falsify “one authority” with a second production-selected path that decides or mutates the same meaning. |
|
||||
| Is code dead or a one-shot abstraction? | Run `staticcheck -checks=U1000 ./internal/<area>/...`, `gopls references -d <file:line:column>`, and the discovery skill's AST construction scan; inspect registrations, Yaegi, tags, build variants, tests, and both binaries | Predict typed references `R`, production constructions, dynamic registrations, and compatibility consumers. Zero text hits alone is never the falsifier. |
|
||||
| Does configuration affect production? | Trace `key → decode → default → validate → translate → cmd/archied read → concrete component → observable`; inspect Compose passthrough separately | Predict exactly one effective owner and every production read. As of 2026-07-28, `cmd/archied` has two `config.LoadOverlay` call sites and no `LoadDir` call; `LoadDir` tests therefore do not prove production selection. |
|
||||
| Do execution modes have parity? | Enumerate the three accepted `agent.mode` values from `internal/config`; test the same input/error/cancel matrix through `inprocess`, `subprocess`, and `nats`; treat containers as a NATS deployment assembly, not a fourth mode | Predict `M` matrix rows and the exact outcome for every cell. One direct runner unit test cannot falsify a mode-wiring defect. |
|
||||
| Are persistence transitions correct? | Run shared legal/illegal transition cases against SQLite and `internal/nell`; include two stale-`from` contenders, state reload, and audit evidence under `-race` | Predict `2/2` adapters reject stale `from`, one winner, unchanged loser, and one matching audit record. Current `Store.Transition` and `Adapter.Transition` ignore `from`; classify that observation as current/open until corrected and accepted. |
|
||||
| Is a protocol compatible? | Preserve canonical bytes/messages; run malformed, partial, multi-message, timeout, EOF, and cancellation cases; then run an official or independent peer | Predict handshake/result bytes and error identity. A fake peer using Archie's `readMessage`/`writeMessage` cannot satisfy independence. |
|
||||
| Is cancellation/concurrency safe? | Use barriers/channels to force ordering; test cancel-before-start, cancel-while-blocked, close/send, retry, and shutdown; run `go test -race ./internal/<area>/... -count=1` | Predict terminal result, side-effect count, retry count, resource closure, and absence of races. Wall-clock sleep alone is not a schedule proof. |
|
||||
| Do NellDB scans meet a requirement? | Define fixture sizes `N` and `10N`; benchmark the exact adapter query with fixed data, cache state, and run count; capture `-benchmem` | Predict latency/allocation slope and acceptance bound before running. `internal/nell/adapter.go` has 14 `AllDocs` call sites as of 2026-07-28; that is structural evidence of scans, not a performance result. |
|
||||
| Did maintainability improve? | Compare owner count, production paths, package edges, public surface, config consumers, complexity findings, and files a future feature must understand; inspect every changed non-test file | Predict which counts fall, stay equal, or may rise with rationale. Linter silence and a lower aggregate score do not prove cohesion, readability, or artfulness. |
|
||||
| Is a migration parity-safe? | Build an old/new matrix across config forms, stored data, modes, peers, errors, restart/recovery, rollback, and deletion criteria; execute every supported row | Predict `M` rows and exact observable parity. A PRD or candidate branch cannot satisfy a live row. Permanent duplicate authoritative paths after cutover must be `0`. |
|
||||
|
||||
Replace `<area>` and `<file:line:column>` with concrete values recorded in the
|
||||
research packet. Use `archie-diagnostics-and-tooling` when a metric needs a
|
||||
repeatable helper rather than an ad hoc shell pipeline.
|
||||
|
||||
## Learn from settled failures
|
||||
|
||||
| Lesson | Archie evidence | Research rule |
|
||||
|---|---|---|
|
||||
| Mirrored peers can validate the same wrong protocol | MCP `Content-Length` work in `f2768eb`/`3ad57c9` passed a server using the same helpers; `dda4cde` moved live framing to newline-delimited JSON and `TestDesktopCommanderClientCompatibility` supplies an opt-in external peer | Require independent bytes or peer behavior before claiming compatibility. |
|
||||
| Green loader tests do not prove shipped wiring | `internal/config/feature_config_test.go` exercises `LoadDir`, while `cmd/archied/main.go` selects `LoadOverlay` as of the dated snapshot | Trace from a real entrypoint through the effect. |
|
||||
| A linter name is not a semantic verdict | `86cfc19` records eleven `nilerr` findings whose errors were deliberately carried through text, envelopes, shutdown, or best-effort behavior; live sites explain local suppressions | Predict the contract consequence per site before changing it. |
|
||||
| Diagnostics can measure the environment instead of the code | Listener-denied sandboxes, inherited GPG settings, read-only temp paths, and stale editor diagnostics have produced different failures from host runs | Freeze environment and confirm with real build/test output; never waive the blocked evidence. |
|
||||
| A local dependency can make a local result unreproducible | `07fb291` removed a machine-local NellDB `replace` that CI/container builds could not resolve | Use the published module and checksum path; label local-checkout evidence candidate. |
|
||||
| “Cleanup” can change behavior while looking mechanical | `308c199` changed the skillscript wrapper to `sh -c` with argument placement that now yields only a newline in the focused test | Treat every cleanup diff as authored semantics and keep the pre-change baseline. |
|
||||
|
||||
## Fence off wrong paths
|
||||
|
||||
- Do not choose success criteria after seeing output.
|
||||
- Do not let a client and fake server import the same framing, parser, or
|
||||
constants and call the result compatibility.
|
||||
- Do not change implementation, tests, config, or fixtures during baseline
|
||||
capture.
|
||||
- Do not treat a candidate branch, commit subject, comment, PRD, or old
|
||||
architecture document as live proof.
|
||||
- Do not infer dead code from text search or `U1000` alone.
|
||||
- Do not equate coverage, lint silence, or green TDD with production wiring,
|
||||
one coherent owner, or maintainability.
|
||||
- Do not suppress a negative result because the attempted slice was small.
|
||||
- Do not reduce artfulness to one complexity score; measure locality and then
|
||||
review names, ownership, cohesion, failure clarity, and deletion.
|
||||
|
||||
## Provenance and maintenance
|
||||
|
||||
Re-verify current versus target authority: `sed -n '1,180p' docs/prds/01-project-management.md && sed -n '1,180p' docs/prds/architecture/package-review.md`
|
||||
|
||||
Re-verify module and gate boundaries: `find . \( -path './.git' -o -path './.references' -o -path './.claude/worktrees' -o -name node_modules \) -prune -o -name go.mod -print && sed -n '1,180p' Taskfile.yml`
|
||||
|
||||
Re-verify configuration selection: `rg -n 'config\.(Load|LoadOverlay|LoadDir)\(' cmd internal --glob '*.go'`
|
||||
|
||||
Re-verify execution modes: `rg -n 'case "inprocess"|case "subprocess"|case "nats"|agent\.mode' cmd/archied internal/config --glob '*.go'`
|
||||
|
||||
Re-verify transition semantics: `sed -n '255,285p' internal/store/store.go && sed -n '268,290p' internal/nell/adapter.go`
|
||||
|
||||
Re-verify NellDB scan candidates: `rg -n 'AllDocs\(' internal/nell/adapter.go`
|
||||
|
||||
Re-verify protocol independence: `rg -n 'readMessage|writeMessage|TestDesktopCommanderClientCompatibility|newline-delimited|Content-Length' internal/tools --glob '*.go'`
|
||||
|
||||
Re-verify the cleanup regression: `env GOTMPDIR=/tmp GOCACHE=/tmp/archie-research-gocache GIT_CONFIG_GLOBAL=/dev/null go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v`
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Archie Research Methodology"
|
||||
short_description: "Turn Archie hunches into reproducible evidence"
|
||||
default_prompt: "Use $archie-research-methodology to design a falsifiable Archie experiment and decision record."
|
||||
@@ -0,0 +1,384 @@
|
||||
---
|
||||
name: archie-run-and-operate
|
||||
description: "Run and observe Archie safely from a local binary or the repository Docker Compose stack. Use when starting or stopping archied, running an archie-agent NATS worker, checking readiness, following logs, locating task state/worktrees/memory/container volumes, understanding inprocess/subprocess/NATS execution, inspecting the deployment watcher or image pipeline, or planning an operational rollback without changing architecture."
|
||||
---
|
||||
|
||||
# Run and operate Archie
|
||||
|
||||
Use this runbook to operate the implementation that exists on **2026-07-28**.
|
||||
Treat source and tests as current; treat `docs/archive/` as history, not an
|
||||
operational contract.
|
||||
|
||||
## Route work to the right skill
|
||||
|
||||
Do **not** use this skill to:
|
||||
|
||||
- install Go, Task, Docker, or project dependencies; use
|
||||
`archie-build-and-env`;
|
||||
- choose, add, or migrate flags and TOML fields; use
|
||||
`archie-config-and-flags`;
|
||||
- diagnose a failure beyond the first observations below; use
|
||||
`archie-debugging-playbook`;
|
||||
- inspect or repair NellDB data; use `archie-nelldb`;
|
||||
- decide whether a runtime or deployment change is acceptable; use
|
||||
`archie-change-control` and `archie-validation-and-qa`;
|
||||
- redesign process boundaries or deployment topology; use
|
||||
`archie-architecture-planning-campaign` and
|
||||
`archie-architecture-contract`.
|
||||
|
||||
## Define the process shapes
|
||||
|
||||
| Term | Meaning here |
|
||||
|---|---|
|
||||
| `archied` | Resident orchestrator. It owns config, forge credentials, the NellDB store, worktrees, gateways, the dashboard, and optional NATS/Docker orchestration. |
|
||||
| `archie-agent` | Current long-running NATS worker. It consumes legacy per-stage requests and full-task `archie.taskrun.>` requests. It is **not** a stdin/stdout worker. |
|
||||
| Stage request | One autonomous workflow stage sent on `archie.agent.<task-id>.request`. |
|
||||
| Full-task handoff | A whole workflow sent on core NATS subject `archie.taskrun.<task-id>` to a task container. |
|
||||
| Work directory | `work_dir`: task clones plus memory and candidate index artifacts. |
|
||||
| State database | `db_path`: the NellDB append-log file holding tasks, events, and Nell-backed chat sessions/messages. It is not SQLite despite the `.db` examples and stale comments. |
|
||||
|
||||
## Apply the operational safety boundary
|
||||
|
||||
Assume every daemon start can change local and external state.
|
||||
|
||||
- Obtain explicit authority for the config, forge identity, repositories, NATS
|
||||
account, Docker host, and deployment host before starting anything.
|
||||
- Never use production tokens for a smoke test.
|
||||
- Do not call `archied -once` as a dry run. It accepts invitations, verifies
|
||||
push access, polls the forge, enqueues/labels work, reconciles PRs, processes
|
||||
tasks, and then exits.
|
||||
- Do not call `archied -requeue` while observing. It mutates durable task state.
|
||||
- Do not start a standalone `archie-agent` against an unfamiliar NATS URL. It
|
||||
immediately joins the worker pool and may execute queued work.
|
||||
- Do not expose the dashboard publicly. It has no authentication, and
|
||||
`POST /api/tasks/clear` deletes terminal task records even though the package
|
||||
describes the dashboard as read-only.
|
||||
- Do not print secret values. Record environment-variable **names**, config
|
||||
checksums, image digests, and paths instead.
|
||||
- Stop with `Ctrl-C`, `SIGTERM`, or Compose. Do not use `SIGKILL` unless graceful
|
||||
shutdown has demonstrably failed.
|
||||
|
||||
There is no config-only or dry-run flag. Validate a candidate config through
|
||||
`archie-config-and-flags` and tests before allowing the daemon to open it.
|
||||
|
||||
## Know the command surfaces
|
||||
|
||||
### `archied`
|
||||
|
||||
| Flag | Exact behavior |
|
||||
|---|---|
|
||||
| `-config <path>` | Load base TOML. Default: `$XDG_CONFIG_HOME/archie/config.toml`, or `~/.config/archie/config.toml`. |
|
||||
| `-config-overlay <path>` | Decode a second TOML file into the base config before defaults and validation. |
|
||||
| `-once` | Run startup plus one poll/process cycle, then exit. This changes state. |
|
||||
| `-requeue <task-id>` | Requeue a parked/waiting task, then exit unless `-once` is also set. This changes state. |
|
||||
|
||||
### `archie-agent`
|
||||
|
||||
| Flag or environment | Exact behavior |
|
||||
|---|---|
|
||||
| `-nats-url <url>` | Select NATS; falls back to `NATS_URL`. One of them is required. |
|
||||
| `-consumer <name>` | Set the durable JetStream consumer name; default `archie-agent`. |
|
||||
| `NATS_TOKEN` | Optional NATS token read directly by the worker. |
|
||||
|
||||
Both linked binaries may also display Go's dependency-registered
|
||||
`-quickchecks` flag. It belongs to `testing/quick`; it is not an Archie
|
||||
operations control.
|
||||
|
||||
## Select the execution mode deliberately
|
||||
|
||||
| Config shape | What runs | Operational status on 2026-07-28 |
|
||||
|---|---|---|
|
||||
| `agent.mode = "inprocess"` and no `[nats]` | `archied` polls and claims from NellDB, then runs workflow stages and model tools in its own process. | **Production-wired candidate.** `config.production.toml` selects it, but live production was not inspected. No process or OS isolation. |
|
||||
| `agent.mode = "subprocess"` | `archied` starts `agent.command` per stage and expects one JSON invocation on stdin and one response on stdout. | **Open/broken with the default command.** `cmd/archie-agent` is a long-running NATS worker and never calls `agentexec.ServeOne`. No compatible repository entrypoint was found. |
|
||||
| `agent.mode = "nats"`, `[nats]`, containers disabled | `archied` still runs the workflow, but each autonomous stage goes to a separately started `archie-agent`. | **Implemented but operator-assembled.** The Compose `agent` service is not a running worker; launch and supervise a worker separately. |
|
||||
| `agent.mode = "nats"`, `[nats]`, `containers.enabled = true` | `archied` publishes task discovery through JetStream, prepares a worktree, spawns one agent container, and sends the whole workflow on `archie.taskrun.<id>`. | **Repository Compose path.** `config.docker.toml` wires it. Live production status is unknown, and the limitations below remain. |
|
||||
|
||||
Config validation requires containers to use NATS mode, a non-empty NATS URL,
|
||||
and a container image.
|
||||
|
||||
## Run a local foreground daemon
|
||||
|
||||
First build through `archie-build-and-env`. The non-mutating build commands in
|
||||
that skill write binaries to `/tmp/`; the commands below expect `task build` to
|
||||
have placed them in `bin/`. Either run `task build` first, or set explicit
|
||||
variables:
|
||||
|
||||
```bash
|
||||
# Either use task build (authorized writable worktree only):
|
||||
task build
|
||||
# …or point at the /tmp binaries from the build skill's cold-start sequence:
|
||||
# ARCHIE_DAEMON_BIN=/tmp/archie-core-archied
|
||||
# ARCHIE_AGENT_BIN=/tmp/archie-core-agent
|
||||
```
|
||||
|
||||
Then perform only read-only orientation:
|
||||
|
||||
```bash
|
||||
task --list
|
||||
./bin/archied -h
|
||||
./bin/archie-agent -h
|
||||
```
|
||||
|
||||
Choose an explicitly approved config; do not substitute
|
||||
`config.example.toml` blindly because its repository and forge values are
|
||||
examples:
|
||||
|
||||
```bash
|
||||
ARCHIE_CONFIG=/absolute/path/to/config.toml
|
||||
test -r "$ARCHIE_CONFIG"
|
||||
```
|
||||
|
||||
Start in the foreground only after the safety boundary is satisfied:
|
||||
|
||||
```bash
|
||||
./bin/archied -config "$ARCHIE_CONFIG"
|
||||
```
|
||||
|
||||
Apply an approved deployment overlay with:
|
||||
|
||||
```bash
|
||||
ARCHIE_OVERLAY=/absolute/path/to/config.overlay.toml
|
||||
test -r "$ARCHIE_OVERLAY"
|
||||
./bin/archied -config "$ARCHIE_CONFIG" -config-overlay "$ARCHIE_OVERLAY"
|
||||
```
|
||||
|
||||
Expect JSON logs on stderr. Require the following sequence as applicable:
|
||||
|
||||
1. `nats connected` when `[nats]` is configured.
|
||||
2. `workflow registry built`.
|
||||
3. `memory manager started`.
|
||||
4. `web ui listening` unless `web.listen = "off"`.
|
||||
5. gateway-start messages for configured Telegram, email, or webhook channels.
|
||||
6. `archied running` after startup verification and before the resident loop.
|
||||
|
||||
Absence of `archied running` means startup did not complete. The daemon has no
|
||||
HTTP health endpoint and no container healthcheck; a running process alone is
|
||||
not readiness evidence.
|
||||
|
||||
Stop the foreground process with `Ctrl-C`. The signal cancels active work,
|
||||
waits for dispatch goroutines, stops capability and memory managers, removes
|
||||
Archie-labelled containers, closes NATS, and closes the NellDB log. Allow the
|
||||
bounded cleanup calls to finish.
|
||||
|
||||
## Run a standalone NATS worker
|
||||
|
||||
Use this only for an approved NATS-without-containers deployment:
|
||||
|
||||
```bash
|
||||
NATS_URL=nats://127.0.0.1:4222 ./bin/archie-agent
|
||||
```
|
||||
|
||||
Require both `nats connected` and `archie-agent ready`. Stop with `Ctrl-C`.
|
||||
Assign a non-default `-consumer` only when the queue topology has been reviewed;
|
||||
consumer names define durable JetStream state.
|
||||
|
||||
Do not use this command to test subprocess mode. The worker requires NATS and
|
||||
does not speak the subprocess JSON protocol.
|
||||
|
||||
## Run the repository Compose stack
|
||||
|
||||
Read `docker-compose.yml` and the host base config before acting. Compose mounts
|
||||
`${HOME}/.config/archie/config.toml` as the base and
|
||||
`config.docker.toml` as the overlay. It also mounts the Docker socket and
|
||||
host data directories, so this is host-authoritative execution.
|
||||
|
||||
| Repository command | Actual scope |
|
||||
|---|---|
|
||||
| `task docker-build` | Build only the `agent` image from `Dockerfile`. It does not build `archied`. |
|
||||
| `task docker-up` | Run `docker compose up -d` for **all** services, including watchtower. |
|
||||
| `task docker-logs` | Follow only the `archied` service logs. |
|
||||
| `task docker-down` | Run `docker compose down`. It does not request volume deletion. |
|
||||
|
||||
Prefer the narrow start when a deployment watcher is not intended:
|
||||
|
||||
```bash
|
||||
docker compose up -d nats archied
|
||||
```
|
||||
|
||||
Use read-only observations:
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
docker compose logs --tail=200 archied
|
||||
docker compose logs --tail=200 nats
|
||||
docker compose exec -T nats wget -q -O - http://localhost:8222/healthz
|
||||
```
|
||||
|
||||
If a local HTTP client is installed, inspect only GET endpoints:
|
||||
|
||||
```bash
|
||||
curl -fsS http://127.0.0.1:8484/api/summary
|
||||
curl -fsS http://127.0.0.1:8484/api/tasks
|
||||
```
|
||||
|
||||
The NATS healthcheck must become healthy before Compose starts `archied`.
|
||||
Require `archied running` in logs as the daemon readiness gate. Do not invoke
|
||||
`POST /api/tasks/clear`.
|
||||
|
||||
Stop the repository stack with:
|
||||
|
||||
```bash
|
||||
task docker-down
|
||||
```
|
||||
|
||||
Never add `-v` during routine shutdown; `nats_data` and any Compose-managed
|
||||
volumes may contain durable state.
|
||||
|
||||
The Compose `agent` service is a build-only placeholder: it clears the image
|
||||
entrypoint and runs `true`. Actual task workers are spawned by `archied`
|
||||
through `/var/run/docker.sock`.
|
||||
|
||||
## Locate output and durable state
|
||||
|
||||
| Output or state | Current destination |
|
||||
|---|---|
|
||||
| Daemon logs | JSON on stderr; Docker's configured log driver captures them under Compose. The repository defines no log file or rotation policy. |
|
||||
| Agent logs | JSON on worker/container stderr. Task containers use `AutoRemove`; capture logs while the container exists because the repository defines no agent log archive. |
|
||||
| Tasks, events, chat sessions/messages | NellDB append log at `db_path`; default `~/.local/share/archie/archie.db`. |
|
||||
| Default task worktree | `<work_dir>/<owner>-<repo>/issue-<number>`; default root `~/.local/share/archie/work`. |
|
||||
| Identity worktree | `<work_dir>/identity-<identity>/<owner>-<repo>/issue-<number>`. |
|
||||
| Container worktree | Host worktree bind-mounted read/write at `/data/worktree`; `task.json` is written at its root and ignored by this repository's `.gitignore`. |
|
||||
| Built-in memory | `<work_dir>/memory/MEMORY.md` and `<work_dir>/memory/USER.md`. |
|
||||
| Telegram update state | `<work_dir>/telegram-update-deferrals.json` plus a hashed `release-announcements-*.json`. |
|
||||
| Codesearch candidates | Defaults derive as `<work_dir>/indexes` and `<work_dir>/workspace-indexes.db`; no `indexing.Manager` construction was found in the daemon composition root, so do not assume these artifacts are produced. |
|
||||
| Optional repository volume | `archie-repo-<owner>-<repo>` mounted at `/data/repo`. The workflow still runs in `/data/worktree`. |
|
||||
| Ecosystem cache volumes | `archie-cache-go`, `archie-cache-node`, `archie-cache-pnpm`, `archie-cache-deno`, `archie-cache-bun`, `archie-cache-pip`, or `archie-cache-cargo`, mounted below `/data/cache`. No code currently sets tool cache environment variables to those mount paths; a mount is not proof of cache use. |
|
||||
| NATS data | Compose declares `nats_data:/data`, while its NATS command does not set a store directory. Verify the live server's store directory before claiming this volume preserves JetStream data. |
|
||||
| Forge-visible output | Reactions, state labels, comments, pushed task branches, closed issues, and PRs. These are external mutations, not local logs. |
|
||||
|
||||
In Compose, the host paths are:
|
||||
|
||||
- `/var/lib/archie/work` for worktrees;
|
||||
- `/var/lib/archie/db/archie.db` for the container's
|
||||
`/var/lib/archie/archie.db`;
|
||||
- the repository checkout mounted at `/workspace`;
|
||||
- the host Docker socket mounted into `archied`.
|
||||
|
||||
Parked worktrees are retained for investigation. Terminal cleanup behavior is
|
||||
owned by the worktree/daemon lifecycle; do not delete paths manually while a
|
||||
task is active.
|
||||
|
||||
## Understand NATS and container observation
|
||||
|
||||
The `ARCHIE_TASKS` JetStream stream uses file storage and work-queue retention
|
||||
for `archie.task.>` and `archie.agent.>`.
|
||||
|
||||
| Plane | Subjects and behavior |
|
||||
|---|---|
|
||||
| Discovery | `archie.task.bug`, `.feature`, `.bootstrap`, or `.default`; daemon durable consumer `archie-daemon`, 5-minute ack wait, max 3 deliveries. |
|
||||
| Legacy stages | `archie.agent.<id>.request`; worker durable consumer defaults to `archie-agent`, 30-minute ack wait, max 3 deliveries; response address travels in `X-Archie-Reply`. |
|
||||
| Container task | Core NATS request/reply on `archie.taskrun.<id>`. A task container reads `/data/worktree/task.json` and creates a dedicated subscription; a shared worker uses queue group `archie-taskrun-workers`. |
|
||||
| Privileged RPC | Store, forge, and worktree operations return to `archied` over core NATS subjects in `internal/storerpc`, `internal/forgerpc`, and `internal/worktreerpc`. |
|
||||
|
||||
Set `containers.network` explicitly. `config.docker.toml` uses
|
||||
`archie-core_default`. Auto-detection inspects the daemon container; on failure,
|
||||
spawned workers join Docker's default bridge and cannot resolve `nats` by
|
||||
service name. An initial `ErrNoResponders` is retried for 20 seconds at 250 ms
|
||||
intervals; other request errors are not readiness retries.
|
||||
|
||||
If `nats.token_env` is configured, `archied` refuses startup when that variable
|
||||
is empty. It injects the resolved value as `NATS_TOKEN` into task containers.
|
||||
It also forwards only configured provider-key variables. Compose forwards a
|
||||
fixed environment list; adding a config reference without matching Compose
|
||||
passthrough leaves the container empty.
|
||||
|
||||
## Fence current operational limitations
|
||||
|
||||
Treat these as open until code and tests prove otherwise:
|
||||
|
||||
- `subprocess` plus default `archie-agent` is protocol-incompatible.
|
||||
- `config.production.toml` is not proof of a working deployment. Its identity
|
||||
uses legacy `token_env`, while current validation requires each identity's
|
||||
`forge.token` secret reference.
|
||||
- Container-mode RPC servers use root forge/worktree objects for every
|
||||
identity; non-root identity tasks can use the wrong authority.
|
||||
- Container orphan recovery and pool shutdown select every container labelled
|
||||
`archie-daemon=true`, without a daemon-instance label. One daemon can remove
|
||||
another daemon's workers on the same Docker host.
|
||||
- `containers.max_uptime` only bounds the create/start context in
|
||||
`Pool.Acquire`; no running-container timer enforces the advertised lifetime.
|
||||
- The container workflow builds `TaskContext` without an event bus. Do not
|
||||
expect in-process stage/agent event timelines to have container-mode parity.
|
||||
- Live SSE clients drop events when their channel is full. Reconnect with the
|
||||
last event ID to replay at most 200 stored events.
|
||||
- The dashboard binds `0.0.0.0:8484` in the Docker overlay and Compose publishes
|
||||
port 8484. It is unauthenticated and includes a mutating clear endpoint.
|
||||
|
||||
Route operational symptoms from these limitations to
|
||||
`archie-debugging-playbook`; route fixes through change control.
|
||||
|
||||
## Understand deployment and rollback seams
|
||||
|
||||
The repository Gitea workflow runs on pushes to `main` and component tags. It
|
||||
builds and pushes only:
|
||||
|
||||
- `git.catlow.cloud/sam/archied:latest`;
|
||||
- `git.catlow.cloud/sam/archie-agent:latest`.
|
||||
|
||||
It injects component versions into labels/binary metadata but does not publish
|
||||
versioned image tags. It runs no repository quality gate (`task check`, tests,
|
||||
lint, or vet) before Docker builds; the Docker builds themselves compile the
|
||||
binaries. Treat a successful workflow as image publication evidence only, not
|
||||
application acceptance evidence.
|
||||
|
||||
Compose watchtower polls every 60 seconds with `--cleanup` and names
|
||||
`archie-core-archied-1` plus `archie-core-archied-winter-1`. The workflow never
|
||||
contacts the host directly. Do not infer that watchtower found, restarted, or
|
||||
validated either live daemon.
|
||||
|
||||
Before any authorized promotion:
|
||||
|
||||
- record the running image IDs and immutable registry digests;
|
||||
- record config file checksums without printing secrets;
|
||||
- record task counts and active task IDs through safe GET observations;
|
||||
- establish a NellDB-consistent backup procedure with `archie-nelldb`;
|
||||
- define which prior digest will be restored and who may restart services.
|
||||
|
||||
The repository has no complete rollback command and publishes no versioned
|
||||
image tags. Do not improvise a production rollback from `latest`; route it
|
||||
through `archie-change-control`. Restoring a binary does not undo forge changes,
|
||||
task transitions, or data-format changes.
|
||||
|
||||
## Treat carina facts as unverified external state
|
||||
|
||||
Repository guidance dated 2026-07-28 says two live instances run on `carina`
|
||||
with distinct `bot_user` values. An archived PRD says this was confirmed on
|
||||
2026-07-25, while `config.production.toml` proposes replacing them with one
|
||||
multi-identity process and Compose watchtower still names two containers.
|
||||
|
||||
No live `carina` process list, config, image digest, service manager, or
|
||||
deployment success was verified for this skill. Do not invent SSH, systemd, or
|
||||
service commands. Query the approved operational source of truth under explicit
|
||||
production-read authority before acting.
|
||||
|
||||
## Use the operator checklist
|
||||
|
||||
- [ ] Confirm the target host, config paths, bot identity, repos, and authority.
|
||||
- [ ] Confirm secret variable names exist without printing values.
|
||||
- [ ] Select one execution row from the mode matrix.
|
||||
- [ ] Capture baseline logs, task summary, image digests, and config checksums.
|
||||
- [ ] Start only the required services; exclude watchtower unless intended.
|
||||
- [ ] Require NATS health when configured and `archied running` always.
|
||||
- [ ] Observe NellDB state and forge-visible effects, not process status alone.
|
||||
- [ ] Stop gracefully and allow deferred cleanup to finish.
|
||||
- [ ] Confirm no tasks remain `running`; startup will requeue stale ones.
|
||||
- [ ] Record open deviations and route behavior changes through validation and
|
||||
change control.
|
||||
|
||||
## Provenance and maintenance
|
||||
|
||||
Verified against repository state on **2026-07-28**. Re-run these one-line,
|
||||
read-only checks after changes:
|
||||
|
||||
```bash
|
||||
rg -n 'flag\.(String|Bool|Int64)' cmd/archied/main.go cmd/archie-agent/main.go
|
||||
sed -n '1,120p' Taskfile.yml
|
||||
sed -n '1,220p' docker-compose.yml
|
||||
sed -n '1,220p' config.docker.toml
|
||||
rg -n 'Mode|Command|NATS|Containers|WorkDir|DBPath|withDefaults|MaxUptime|PullPolicy' internal/config/config.go internal/config/indexer.go
|
||||
rg -n 'SubprocessRunner|ServeOne|taskRunSubjectWildcard|archie-agent ready' internal/agentexec cmd/archie-agent
|
||||
rg -n 'AutoRemove|archie-daemon|recoverOrphans|MaxUptime|NetworkMode' internal/container/pool.go
|
||||
rg -n 'WorktreeMountDir|archie-cache-|archie-repo-|CleanupExpired' internal/storage/storage.go
|
||||
rg -n 'HandleFunc|api/summary|api/tasks|events|ListenAndServe' internal/webui/webui.go
|
||||
sed -n '1,220p' .gitea/workflows/deploy.yml
|
||||
```
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Run and Operate Archie"
|
||||
short_description: "Run Archie safely and locate its operational state"
|
||||
default_prompt: "Use $archie-run-and-operate to start Archie locally, inspect its runtime state, and stop it safely."
|
||||
@@ -0,0 +1,400 @@
|
||||
---
|
||||
name: archie-technical-accountability
|
||||
description: Prove that an Archie change is maintainable, owned, reachable, reversible, and simpler than the code it replaces. Use when designing, implementing, reviewing, or accepting a feature, refactor, configuration path, registry, adapter, interface, or cleanup; when tests are green but code quality is uncertain; or when duplicate paths, dead code, one-use abstractions, supersession, production wiring, or concern ownership may be hidden.
|
||||
---
|
||||
|
||||
# Archie Technical Accountability
|
||||
|
||||
Accept behavior only after proving both correctness and maintainability. Treat a
|
||||
green test as evidence about the tested seam, never as proof that production
|
||||
uses the seam or that the design has one coherent owner.
|
||||
|
||||
Use imperative runbook voice in the resulting review. Mark every conclusion as
|
||||
`proven`, `candidate`, or `open`. Do not convert absence of evidence into proof.
|
||||
|
||||
## Route the work
|
||||
|
||||
Load the sibling skill named for each responsibility:
|
||||
|
||||
| Need | Load instead or next |
|
||||
| --- | --- |
|
||||
| Select domains, boundaries, ownership, or a migration shape | `archie-architecture-planning-campaign` first |
|
||||
| Traverse an unfamiliar area, its AST, consumers, runtime paths, or history | `archie-codebase-discovery` first |
|
||||
| Classify the change and determine required gates and reviewers | `archie-change-control` |
|
||||
| Prove tests, lint, formatting, race behavior, or acceptance thresholds | `archie-validation-and-qa` |
|
||||
| Triage an active failure or unexplained runtime symptom | `archie-debugging-playbook` first |
|
||||
| Reconstruct a historical failure, revert, rejected fix, or settled dead end | `archie-failure-archaeology` first |
|
||||
|
||||
Do **not** use this skill as:
|
||||
|
||||
- a substitute for architecture planning before ownership is decided;
|
||||
- a substitute for deep codebase discovery or AST-aware call-path analysis;
|
||||
- a debugging playbook for an active incident;
|
||||
- permission to implement before the repository's change-control and TDD rules;
|
||||
- a reason to keep an obsolete path "for safety"; define a real rollback and
|
||||
deletion plan instead.
|
||||
|
||||
## Define the evidence vocabulary
|
||||
|
||||
- **Owner**: the one domain or capability accountable for a behavior, its
|
||||
vocabulary, state, rules, settings, and required service contracts.
|
||||
- **Source of truth**: the only authoritative implementation or mutable record
|
||||
for one meaning. Adapters may translate it; they must not reimplement it.
|
||||
- **Consumer**: production code, test code, generated code, or an external
|
||||
process that calls, imports, decodes, registers, or depends on the subject.
|
||||
- **Production wiring**: the executable path from a real `cmd/*` entry point,
|
||||
configuration source, or inbound adapter through composition to an observable
|
||||
effect.
|
||||
- **Parallel path**: another implementation that can satisfy the same intent or
|
||||
mutate the same state, even when names and types differ.
|
||||
- **One-shot abstraction**: an interface, wrapper, registry, service, or helper
|
||||
introduced for one call or implementation without owning policy, lifecycle,
|
||||
translation, isolation, or a stable boundary.
|
||||
- **Deletion criterion**: an observable condition that permits removing a
|
||||
legacy or compatibility path.
|
||||
- **Archaeology**: history evidence explaining why a seam exists, what it
|
||||
replaced, and which failed approach must not be repeated.
|
||||
|
||||
## Produce one accountability record
|
||||
|
||||
Attach one record to the change artifact selected by
|
||||
`archie-change-control`. Do not create an ad hoc TODO document. Complete the
|
||||
record before implementation, then update it from the final diff.
|
||||
|
||||
### Header
|
||||
|
||||
| Field | Required content |
|
||||
| --- | --- |
|
||||
| Requested outcome | One behavior stated without naming an implementation |
|
||||
| Change class | Classification from `archie-change-control` |
|
||||
| Owner | One current owner and, during migration, one approved target owner |
|
||||
| Source of truth | Current authoritative code/state and the post-change authority |
|
||||
| Scope | Packages, entry points, settings, persisted records, and contracts touched |
|
||||
| Accountable actors | Implementer and independent adversarial reviewer |
|
||||
| Status | `proven`, `candidate`, or `open` |
|
||||
|
||||
### Consumer and path inventory
|
||||
|
||||
Record every row; use `none proven` rather than leaving a cell blank.
|
||||
|
||||
| Consumer/path | Entry | Dispatch or translation | Authority called | Effect | Evidence |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| Production | command, channel, worker, poller, or startup | exact functions | exact owner | state/output | file:line and test |
|
||||
| Alternate process | subprocess, NATS worker, container, or RPC | exact contract | exact owner | state/output | file:line and test |
|
||||
| Dynamic | registry, plugin, Yaegi, callback, reflection, or config | registration/load seam | exact owner | state/output | file:line and test |
|
||||
| Tests | focused, integration, contract, race | seam exercised | fake or real authority | assertion | test name |
|
||||
| Generated/docs | generator or schema consumer | source contract | owner | artifact | generator path |
|
||||
|
||||
Block acceptance if a production row stops at a constructor, parser, registry,
|
||||
schema, test fake, or helper subcommand without reaching the running
|
||||
composition path.
|
||||
|
||||
## Run the accountability workflow
|
||||
|
||||
### 1. Freeze the behavioral claim
|
||||
|
||||
Write one sentence:
|
||||
|
||||
> When `<real entry>` receives `<input>`, `<owner>` performs `<behavior>` and
|
||||
> produces `<observable result or failure>`.
|
||||
|
||||
Reject claims such as "add manager," "add interface," or "support YAML." Those
|
||||
name an implementation, not an outcome.
|
||||
|
||||
List the behavior that must remain unchanged. Include persistence, errors,
|
||||
timeouts, concurrency, process boundaries, authorization, and compatibility
|
||||
when applicable.
|
||||
|
||||
### 2. Establish the owner and source of truth
|
||||
|
||||
Read the approved architecture requirements and the live code. Keep the two
|
||||
states distinct. As of 2026-07-28:
|
||||
|
||||
- `docs/prds/architecture/organisation.md` defines the approved target
|
||||
organization.
|
||||
- `docs/prds/architecture/dependencies-and-contracts.md` defines strict target
|
||||
dependency direction and contract ownership.
|
||||
- `docs/prds/architecture/configuration.md` requires dissolution of the current
|
||||
shared `internal/config` model; this is an approved target, not completed
|
||||
live behavior.
|
||||
- `docs/prds/architecture/package-review.md` requires current-state research
|
||||
before package decisions.
|
||||
|
||||
Answer:
|
||||
|
||||
1. Which cohesive job owns this behavior?
|
||||
2. Which mutable record or function is authoritative now?
|
||||
3. Which authority will remain after the change?
|
||||
4. Is another package allowed to mutate the same meaning?
|
||||
5. Does the proposed location reduce or increase required knowledge?
|
||||
|
||||
Block if the answer is "shared," "config," "utils," "manager," or "registry"
|
||||
without naming the behavior owner. Mechanics may be shared; domain meaning may
|
||||
not.
|
||||
|
||||
### 3. Inventory all consumers and call paths
|
||||
|
||||
Start with text and package evidence:
|
||||
|
||||
```bash
|
||||
rg -n '\bMessageEvent\b' --glob '*.go' .
|
||||
rg -n '\bMessageEvent\b' --glob '*.go' --glob '!**/*_test.go' .
|
||||
go doc github.com/samcharles93/archie-core/internal/gateway.MessageEvent
|
||||
go list -f '{{.ImportPath}}: {{join .Imports " "}}' ./...
|
||||
go list -deps ./cmd/archied ./cmd/archie-agent
|
||||
go -C tools list ./...
|
||||
```
|
||||
|
||||
Replace `MessageEvent` and its package path with the subject under review.
|
||||
Separate production, test, generated, and documentation hits. An imported
|
||||
package proves only package reachability, not function reachability. The
|
||||
`tools` directory is a nested Go module, so root `go list ./...` does not include
|
||||
it; inspect it separately whenever the change touches generation tooling.
|
||||
|
||||
Trace each real path in both directions:
|
||||
|
||||
1. Start at `cmd/archied`, `cmd/archie-agent`, or an inbound adapter.
|
||||
2. Follow construction, registration, translation, dispatch, and callbacks.
|
||||
3. Continue through interfaces to every implementation.
|
||||
4. End at persisted state, outbound I/O, or a user-visible result.
|
||||
5. Walk backward from the effect to find alternate writers.
|
||||
|
||||
Use `archie-codebase-discovery` for AST traversal. `rg` cannot resolve
|
||||
interface dispatch, method expressions, callbacks, reflection, generated
|
||||
registries, Yaegi-loaded code, or config-selected implementations. Never declare
|
||||
code dead from text search alone.
|
||||
|
||||
### 4. Detect duplicate, parallel, and superseded paths
|
||||
|
||||
Search by domain language and effects, not only symbol names:
|
||||
|
||||
```bash
|
||||
rg -n -i 'message|conversation|session|reply|acknowledg' internal cmd --glob '*.go'
|
||||
rg -n -i 'insert|update|put|delete|transition|publish|enqueue' internal cmd --glob '*.go'
|
||||
rg -n 'TODO|FIXME|HACK|XXX' internal cmd docs --glob '*.go' --glob '*.md'
|
||||
```
|
||||
|
||||
Narrow those searches to the changed behavior. Compare:
|
||||
|
||||
- inputs and outputs;
|
||||
- state read and written;
|
||||
- retry, timeout, error, and fallback semantics;
|
||||
- authorization and identity;
|
||||
- startup, shutdown, and health behavior;
|
||||
- process-specific implementations;
|
||||
- test doubles that may mirror the implementation rather than the contract.
|
||||
|
||||
Complete this supersession table:
|
||||
|
||||
| Existing path | Proposed relation | Production caller | Parity needed | Deletion criterion |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| exact path | retain, adapt, merge, supersede, or delete | exact entry | named semantics | observable condition |
|
||||
|
||||
Block if new work overlaps an existing path without one explicit relation.
|
||||
Block any indefinite "temporary" compatibility path. A dual path requires a
|
||||
named cutover, authoritative side, observation method, and deletion criterion.
|
||||
|
||||
### 5. Prove production wiring
|
||||
|
||||
For every feature, prove this complete chain:
|
||||
|
||||
```text
|
||||
real input -> loader/adapter -> application composition -> owner
|
||||
-> side effect -> observable success/failure
|
||||
```
|
||||
|
||||
Require all of:
|
||||
|
||||
- a source citation at each handoff;
|
||||
- one focused behavior test;
|
||||
- one composition, integration, or contract test that crosses the handoff;
|
||||
- a negative test proving the old/unconfigured/failed path does not masquerade
|
||||
as success;
|
||||
- an operator- or caller-visible failure when silent fallback would hide loss.
|
||||
|
||||
A decode test proves decoding. A constructor test proves construction. A
|
||||
registry test proves registration. None proves production wiring.
|
||||
|
||||
For protocols, validate against an independent implementation, published
|
||||
fixture, or official SDK. A client tested only against a server using the same
|
||||
framing/parser proves self-consistency, not interoperability.
|
||||
|
||||
### 6. Hold configuration to concern ownership
|
||||
|
||||
Classify every behavioral value as the approved configuration requirements
|
||||
direct:
|
||||
|
||||
| Class | Meaning |
|
||||
| --- | --- |
|
||||
| Invariant | Changing it changes a domain concept or wire meaning |
|
||||
| Runtime setting | An installation, identity, domain, plugin, or deployment may choose it |
|
||||
| Policy value | It controls permission, limits, routing, retry, protection, or gates |
|
||||
| Derived value | It is computed and not independently mutable |
|
||||
| Runtime state | A domain command changes it during operation |
|
||||
|
||||
For each new or changed setting, require:
|
||||
|
||||
- one domain/plugin owner;
|
||||
- type, units, constraints, safe bounds, default, and derivation;
|
||||
- startup-only, reloadable, or restart-required semantics;
|
||||
- scope: installation, identity, repository, workflow, channel, or plugin;
|
||||
- secret/sensitive/reportable classification;
|
||||
- external DTO decoding separated from the owner's runtime settings;
|
||||
- composition translation and validation;
|
||||
- an exact production consumer;
|
||||
- compatibility and last-known-good behavior;
|
||||
- documentation and tests for invalid, omitted, and explicit values;
|
||||
- removal of any superseded field or a bounded migration plan.
|
||||
|
||||
Do not deepen `internal/config` merely because it is convenient. If migration
|
||||
timing forces a compatibility edit there, label it transitional and route the
|
||||
ownership decision through `archie-architecture-planning-campaign`.
|
||||
|
||||
### 7. Challenge every abstraction and dead-path candidate
|
||||
|
||||
Use this table during manual review:
|
||||
|
||||
| Signal | Required challenge | Accept only when |
|
||||
| --- | --- | --- |
|
||||
| Interface has one implementation and one consumer | Why is dynamic substitution required? | It owns a consumer need, stable boundary, or useful test seam |
|
||||
| Wrapper delegates one operation | What policy, translation, lifecycle, or isolation does it own? | The added responsibility is named and tested |
|
||||
| Manager/registry exists without lifecycle wiring | Who starts, uses, observes, and stops it? | Production composition and failure paths are proven |
|
||||
| Exported type appears only in tests/generation | Is it a contract or an abandoned future path? | A real external consumer is cited or it is removed/labeled candidate |
|
||||
| Config field is decoded but never consumed | What running behavior changes? | Exact constructor/operation use is cited and tested |
|
||||
| Branch/fallback has no constructible input | What reaches it? | A real path and negative test exist |
|
||||
| Replacement leaves old reads/writes | Which side is authoritative? | Cutover and deletion criteria are explicit |
|
||||
| Helper exists for one call | Would direct code be clearer? | The helper names a stable concept or removes real duplication |
|
||||
|
||||
Do not keep an abstraction for hypothetical reuse. Do not delete a dynamic path
|
||||
until AST, registry, plugin, configuration, and runtime evidence are checked.
|
||||
|
||||
### 8. Justify interfaces and locations
|
||||
|
||||
Require a one-paragraph location decision:
|
||||
|
||||
1. Name the behavior and owner.
|
||||
2. Name the dependencies it may import.
|
||||
3. Name the smallest contract it needs.
|
||||
4. State why the contract belongs with the domain/capability that defines its
|
||||
meaning.
|
||||
5. State why infrastructure representations do not leak through it.
|
||||
6. State what future change should remain local to this package.
|
||||
|
||||
Reject ceremonial `entities`, `repositories`, or `services` layers; the
|
||||
approved organization document prohibits them. Reject an interface that merely
|
||||
duplicates a concrete API without narrowing authority.
|
||||
|
||||
### 9. Review readability and artfulness
|
||||
|
||||
Treat artful code as code with an obvious owner, a small surface, explicit
|
||||
consequences, and no cleverness tax. Review every changed non-test file and
|
||||
answer:
|
||||
|
||||
- Can a zero-context mid-level engineer explain the behavior without traversing
|
||||
unrelated domains?
|
||||
- Do names use the domain vocabulary rather than `helper`, `manager`, `data`,
|
||||
`thing`, or transport vocabulary?
|
||||
- Does each function perform one coherent step at the right abstraction level?
|
||||
- Are error, rollback, cancellation, and shutdown paths adjacent and visible?
|
||||
- Do comments explain why a constraint exists rather than narrate syntax?
|
||||
- Can a reader distinguish authority from adapter, DTO, projection, and cache?
|
||||
- Did the change remove more accidental concepts than it added?
|
||||
|
||||
Block if the reviewer cannot summarize owner, input, decision, effect, and
|
||||
failure in five plain sentences. Simplify before adding comments that explain a
|
||||
convoluted path.
|
||||
|
||||
### 10. Prove reversibility and deletion
|
||||
|
||||
Do not use retained dead code as rollback. Record:
|
||||
|
||||
| Concern | Required proof |
|
||||
| --- | --- |
|
||||
| Source rollback | Known-good release/change and behavioral compatibility |
|
||||
| Data rollback | Migration direction, backup, forward/backward readability, and loss risk |
|
||||
| Runtime rollback | Health signal, observation period, bounded retry, and last-known-good behavior |
|
||||
| Compatibility | Authoritative path, expiry/cutover, and removal owner |
|
||||
| Deletion | No production/test/generated consumers, parity evidence, config/docs removal, regression guard |
|
||||
|
||||
The approved recovery requirements are in
|
||||
`docs/prds/architecture/safe-change-and-recovery.md`; exact runtime-supervision
|
||||
mechanics remain under design as of 2026-07-28. Label unimplemented mechanics
|
||||
`open`; do not describe them as available.
|
||||
|
||||
### 11. Perform post-change archaeology
|
||||
|
||||
Re-run discovery against the final diff:
|
||||
|
||||
```bash
|
||||
git diff --name-status
|
||||
git diff --stat
|
||||
git log --all --date=short --oneline -- internal/gateway
|
||||
git log -S'MessageEvent' --all --oneline -- internal/gateway
|
||||
git blame internal/gateway/messageevent.go
|
||||
rg -n '\bMessageEvent\b' --glob '*.go' .
|
||||
```
|
||||
|
||||
Replace the example path and symbol. Record:
|
||||
|
||||
- which historical decision the change preserves or overturns;
|
||||
- what old path became obsolete;
|
||||
- what was actually deleted;
|
||||
- what remains transitional and why;
|
||||
- which regression test or architecture check prevents reintroduction;
|
||||
- which uncertainty still requires production evidence.
|
||||
|
||||
Then route validation through `archie-validation-and-qa` and acceptance through
|
||||
`archie-change-control`. The implementer must not self-certify the adversarial
|
||||
maintainability review.
|
||||
|
||||
## Apply blocking acceptance rules
|
||||
|
||||
Return `BLOCK` when any row lacks evidence:
|
||||
|
||||
| Blocking proof | Minimum evidence |
|
||||
| --- | --- |
|
||||
| Owner | One behavior owner; current and target separated |
|
||||
| Source of truth | One authoritative implementation/record after cutover |
|
||||
| Consumers | Production, alternate-process, dynamic, test, and generated paths classified |
|
||||
| Wiring | Real entry-to-effect chain plus integration/contract evidence |
|
||||
| Supersession | Every overlap marked retain/adapt/merge/supersede/delete |
|
||||
| Deletion | Objective criteria for every legacy/compatibility path |
|
||||
| Configuration | Owner, translation, validation, consumer, reload, and compatibility semantics |
|
||||
| Boundary | Interface and package location justified |
|
||||
| Failure semantics | Errors, cancellation, rollback, health, and observability reviewed |
|
||||
| Readability | Independent reviewer can state the path plainly |
|
||||
| Reversibility | Source, state, runtime, and compatibility rollback addressed |
|
||||
| Archaeology | Relevant history and rejected paths recorded |
|
||||
| Validation | Required evidence from `archie-validation-and-qa` |
|
||||
|
||||
Return `ACCEPT` only when all rows are proven and the fresh adversarial reviewer
|
||||
reports no surviving blocking or important maintainability finding. Return
|
||||
`CANDIDATE` for an explicitly experimental seam that is not production-wired;
|
||||
never call it shipped or complete.
|
||||
|
||||
## Learn from repository incidents
|
||||
|
||||
Treat these as evidence patterns, not legends:
|
||||
|
||||
| Incident | Repository evidence | Accountability lesson |
|
||||
| --- | --- | --- |
|
||||
| Richer message path exists beside the live path | `internal/gateway/messageevent.go`; `docs/prds/architecture/messaging-and-work-intake.md` states that adapters use `gateway.Message` while richer `MessageEvent` is unused; production-only `rg` finds no concrete live adapter use as of 2026-07-28 | Tests and a rich contract do not establish adoption; inventory callers and delete or cut over the competing contract |
|
||||
| Feature YAML loader is not the daemon loader | `internal/config/feature_config.go` defines `LoadDir`; its hits are tests, while `cmd/archied/main.go` calls `config.LoadOverlay` as of 2026-07-28 | Parsed and heavily tested configuration can still be unwired |
|
||||
| Indexing arrived as an isolated feature/settings island | `ddf624d` added indexing; `f934ef5` records undiscoverable settings and silent degradation; as of 2026-07-28 `cmd/archied` uses indexing only in the helper subcommand and does not construct `indexing.Manager` | Prove configuration surface, running composition, and observable failure separately |
|
||||
| Mirrored MCP server validated the same wrong protocol | Before `dda4cde`, the test helper in `internal/tools/mcp/transport_test.go` called the same `readMessage`/`writeMessage` functions as the client; `dda4cde` replaced LSP-style `Content-Length` with MCP newline-delimited JSON for official-SDK interoperability | A mirrored fake can preserve a shared misconception; require independent contract evidence |
|
||||
| A green tool registry needed eight adversarial fixes | `9f6c36c` records deadlock, shared-reference mutation, shallow copies, incomplete AST literal parsing, abort-on-first-error, and an over-broad register-call matcher | Test reentrancy, ownership/aliasing, partial failure, and AST false positives—not only happy-path registration |
|
||||
| Mechanical cleanup broke a focused behavior | `308c199` changed `exec.Command("echo", "wrapped")` to `exec.CommandContext(ctx, "sh", "-c", "echo", "wrapped")`; `wrapped` became shell `$0`, and `TestRunWrapsExternalCommand` returns only `"\n"` as of 2026-07-28. The same commit added 237 tracked `docs-2/node_modules` symlinks | A broad cleanup needs semantic diff review, artifact review, and focused tests; "mechanical" is not a lower evidence class |
|
||||
| Autofix nearly changed timeout semantics | `9b44bac` records `golangci-lint --fix` changing an assignment to a shadowing declaration in `internal/memory/manager.go`; it was manually restored | Inspect every automated rewrite; compilation is necessary but does not prove preserved semantics |
|
||||
|
||||
Re-verify volatile status before reusing any "as of" claim.
|
||||
|
||||
## Provenance and maintenance
|
||||
|
||||
- Re-verify architecture status: `sed -n '1,180p' docs/prds/architecture/{package-review,organisation,configuration,dependencies-and-contracts,safe-change-and-recovery}.md`
|
||||
- Re-verify live entry points and config loaders: `rg -n 'func (main|run)\b|config\.(Load|LoadOverlay|LoadDir)\(' cmd internal --glob '*.go'`
|
||||
- Re-verify message-path consumers: `rg -n '\b(Message|MessageEvent)\b' cmd internal --glob '*.go'`
|
||||
- Re-verify indexing wiring: `rg -n 'indexing\.|IndexingConfig|cfg\.Indexing' cmd internal --glob '*.go'`
|
||||
- Re-verify incident commits: `git show -s --format='%H%n%B' 9f6c36c dda4cde f934ef5 9b44bac 308c199`
|
||||
- Re-verify cleanup regression: `go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1`
|
||||
- Re-verify repository gates: `sed -n '1,140p' Taskfile.yml && sed -n '90,145p' CLAUDE.md`
|
||||
- Re-verify this skill structurally with the skill validator available in the active agent environment.
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Archie Technical Accountability"
|
||||
short_description: "Prove maintainability before accepting changes"
|
||||
default_prompt: "Use $archie-technical-accountability to audit this Archie change for maintainability, ownership, supersession, production wiring, and dead paths."
|
||||
@@ -0,0 +1,397 @@
|
||||
---
|
||||
name: archie-validation-and-qa
|
||||
description: "Design, run, interpret, and review defensible validation evidence for archie-core. Use when adding or assessing Go tests, proving a red-then-green change, choosing focused versus repository-wide gates, validating production wiring or protocols, investigating race/cancellation/state-transition behavior, distinguishing sandbox failures from code regressions, or deciding whether an implementation has enough evidence to be accepted."
|
||||
---
|
||||
|
||||
# Archie validation and QA
|
||||
|
||||
Prove the behavior, integration, and maintainability claim. A passing unit test
|
||||
is necessary evidence; it is not proof that production selects the code, a
|
||||
protocol interoperates, concurrency is safe, or the superseded path is gone.
|
||||
|
||||
## Route work before testing
|
||||
|
||||
| Need | Load instead or alongside this skill |
|
||||
|---|---|
|
||||
| Classify risk, authorize mutation, choose mandatory gates, or accept/close work | `archie-change-control` |
|
||||
| Find duplicate, dead, misplaced, or unmaintainable code and test whether the change is locally comprehensible | `archie-technical-accountability` |
|
||||
| Triage an unexplained runtime or test symptom | `archie-debugging-playbook` |
|
||||
| Decide ownership, boundaries, migration, configuration responsibility, or deletion of competing paths | `archie-architecture-planning-campaign` |
|
||||
|
||||
Do **not** use this skill:
|
||||
|
||||
- to turn a design dispute into a test implementation;
|
||||
- to waive a gate because a focused test passes;
|
||||
- to diagnose an unfamiliar failure without the debugging playbook;
|
||||
- to certify maintainability without technical-accountability review;
|
||||
- to run `task check` during a read-only review or in a shared dirty tree: it
|
||||
rewrites Go files.
|
||||
|
||||
## Define the evidence terms
|
||||
|
||||
| Term | Meaning here |
|
||||
|---|---|
|
||||
| Right-reason red | The intended behavioral assertion fails against compiling code because the capability is absent or wrong. |
|
||||
| Focused test | One named test or one owning package used for fast iteration. |
|
||||
| Root suite | `go test ./... -count=1` in the repository root module. |
|
||||
| Tools suite | `go -C tools test ./... -count=1` in the separate `tools` Go module. |
|
||||
| Composition test | A test that crosses the real construction or dispatch handoff used by a binary. |
|
||||
| Independent peer | A protocol implementation, official SDK, executable, or conformance fixture that does not reuse the code under test. |
|
||||
| Environmental failure | The test cannot acquire a required host resource, such as a listener, writable keyring, executable, or cache. |
|
||||
| Code regression | The test reached the behavior under test and observed the wrong result. |
|
||||
| Evidence packet | The exact commands, outputs, tree identity, test design, integration proof, and independent review used for acceptance. |
|
||||
|
||||
## Recheck the volatile baseline
|
||||
|
||||
Treat this as a dated warning, not a permanent exception.
|
||||
|
||||
As of **2026-07-28**:
|
||||
|
||||
- A recorded unrestricted run of `go test ./... -count=1` has one code failure:
|
||||
`internal/skillscript.TestRunWrapsExternalCommand` gets `"\n"` instead of
|
||||
`"wrapped\n"`.
|
||||
- The root suite excludes `tools` because `tools/go.mod` starts a nested module.
|
||||
- No separate integration-test task or build tag exists. Embedded NATS servers,
|
||||
loopback HTTP/SMTP servers, and Git fixture commits run inside the ordinary
|
||||
root suite.
|
||||
- `TestDesktopCommanderClientCompatibility` is the one explicit external
|
||||
integration opt-in found; it skips unless
|
||||
`ARCHIE_TEST_DESKTOP_COMMANDER=1`.
|
||||
- `task check` runs `gofumpt -w .`, `go fix ./...` twice, `go vet ./...`,
|
||||
the two binary builds, and the root suite. It does **not** run
|
||||
`golangci-lint`, race tests, the `tools` module, docs generation, or the docs
|
||||
build.
|
||||
- The Gitea deploy workflow builds and pushes images, and the GitHub docs
|
||||
workflow builds VitePress. Neither workflow runs the Go quality gate.
|
||||
|
||||
This baseline means the repository-wide suite is not green. Prove local
|
||||
non-regression if work must continue, but never report the full gate as passing
|
||||
until the failure is fixed and the unrestricted suite is rerun. Route any
|
||||
acceptance decision through `archie-change-control`.
|
||||
|
||||
## Choose the required evidence surface
|
||||
|
||||
Apply every row that matches the change.
|
||||
|
||||
| Change surface | Minimum additional evidence |
|
||||
|---|---|
|
||||
| One genuinely isolated package | Right-reason red and green; whole-package test; scoped lint; formatting/fix check; prove no cross-package runtime contract changed. |
|
||||
| Cross-package behavior or shared contract | Root suite; full lint; vet/build; race suite; composition test at each changed handoff. |
|
||||
| `cmd/archied` or `cmd/archie-agent` wiring | Test from real configuration/construction through selected implementation and observable result; test missing/invalid wiring. |
|
||||
| Protocol, RPC, MCP, NATS, subprocess, or wire schema | Malformed, partial, multiple, out-of-order, timeout, cancellation, and peer-exit cases; at least one independent-peer or conformance test. |
|
||||
| Mutable shared state | Deterministic concurrency test plus `-race`; ownership/aliasing test; cancellation and shutdown proof. |
|
||||
| Store or lifecycle transition | Legal/illegal transition table; stale-`from` contenders; atomic state-and-audit proof; adapter parity where both SQLite and NellDB implement the contract. |
|
||||
| Configuration | Default, explicit, absent, invalid, compatibility, precedence, secret-reference, and production-passthrough tests. |
|
||||
| `tools/**` or generated contracts | Tools suite and lint; generator determinism/drift check; root consumer tests; docs build when rendered data changes. |
|
||||
| Docker/Compose/deployment | Configuration-to-container passthrough, network/volume/health behavior, failure visibility, and last-known-good recovery evidence. |
|
||||
| External integration | Hermetic tests first; then an explicitly authorized live compatibility run with version, environment, and observed output recorded. |
|
||||
|
||||
Do not call a change isolated merely because only one file changed. Trace its
|
||||
callers and consumers with the architecture campaign or technical-accountability
|
||||
skill first.
|
||||
|
||||
## Execute red then green
|
||||
|
||||
### 1. Freeze one behavioral claim
|
||||
|
||||
Write:
|
||||
|
||||
> Given `<input and state>`, when `<real entry point>` is called, `<owner>`
|
||||
> produces `<observable result or error>` while preserving `<invariants>`.
|
||||
|
||||
Name the failure surface, production consumer, and superseded behavior. If
|
||||
ownership or the affected paths are unclear, stop and run the architecture
|
||||
campaign.
|
||||
|
||||
### 2. Establish the pre-change baseline
|
||||
|
||||
Run the nearest existing tests before adding the repro. Record the current
|
||||
commit or supplied tree identity, existing dirty paths, command, exit status,
|
||||
and failures. Do not assign a concurrent or pre-existing failure to the change
|
||||
without a before/after comparison.
|
||||
|
||||
### 3. Write the test first
|
||||
|
||||
Make the test compile against the intended public or package contract. Exercise
|
||||
the behavior, not a private implementation sequence. Then run only the named
|
||||
test and prove:
|
||||
|
||||
- the assertion fails;
|
||||
- the failure message names the wrong behavior;
|
||||
- the fixture reached the intended branch;
|
||||
- the cause is not compilation, a missing executable, a listener denial, GPG,
|
||||
a timeout chosen too tightly, or stale generated data.
|
||||
|
||||
A compile error is not red. A test that panics in setup is not red. Deliberately
|
||||
corrupting unrelated code to manufacture red is not TDD.
|
||||
|
||||
For a behavior-preserving refactor, retain green characterization tests. Add a
|
||||
structural test only for a stable, load-bearing architecture constraint; do not
|
||||
invent a brittle implementation assertion merely to manufacture red. Have
|
||||
`archie-change-control` classify the work before proceeding.
|
||||
|
||||
### 4. Implement the smallest coherent change
|
||||
|
||||
Make the named test green, then run the owning package. “Smallest” does not mean
|
||||
leaving a second active implementation or a one-call wrapper with no boundary
|
||||
purpose. Use `archie-technical-accountability` to inspect deletion,
|
||||
supersession, dependency direction, and comprehensibility.
|
||||
|
||||
### 5. Complete the test matrix
|
||||
|
||||
Use table-driven cases. Put identities, repositories, configuration values,
|
||||
durations, states, and expected results in case fields or fixture builders.
|
||||
Never couple tests or implementation to live identities such as production bot
|
||||
names. Use named constants only when the value is itself a contract.
|
||||
|
||||
Test every reachable error path. At minimum consider:
|
||||
|
||||
- empty, malformed, duplicate, and boundary inputs;
|
||||
- missing configuration, environment references, credentials, and resources;
|
||||
- downstream returned errors, partial results, and peer exit;
|
||||
- timeout before work, cancellation during blocked work, and shutdown;
|
||||
- partial side effects, retry, idempotency, and recovery;
|
||||
- unauthorized identity or cross-scope access;
|
||||
- old configuration, stored data, or wire forms when compatibility is claimed.
|
||||
|
||||
Assert the result **and** the consequence: returned error identity/wrapping,
|
||||
persisted state, emitted event, audit entry, side-effect count, and absence of
|
||||
silent fallback.
|
||||
|
||||
## Test the seams models commonly miss
|
||||
|
||||
### Prove production wiring
|
||||
|
||||
Trace and test this chain:
|
||||
|
||||
```text
|
||||
real input -> decode/load -> binary composition -> selected owner
|
||||
-> state or side effect -> observable success/failure
|
||||
```
|
||||
|
||||
A decoder test proves decoding. A constructor test proves construction. A
|
||||
registry test proves registration. None proves that `cmd/archied` or
|
||||
`cmd/archie-agent` selects the implementation.
|
||||
|
||||
Add one test at the owning behavior and one composition/contract test across
|
||||
each changed handoff. Include a negative case showing that absent or failed
|
||||
wiring cannot report success. Structural source-string tests may protect an
|
||||
especially fragile seam, but they cannot be the only production-wiring proof.
|
||||
|
||||
### Test protocols independently
|
||||
|
||||
Do not validate a client only against a fake that calls the same framing,
|
||||
parser, constants, or helpers. That proves self-consistency.
|
||||
|
||||
Use, in ranked order:
|
||||
|
||||
1. the supported real peer pinned to an explicit version;
|
||||
2. an official SDK or independent reference implementation;
|
||||
3. published conformance vectors or captured wire fixtures;
|
||||
4. a deliberately independent minimal peer that encodes from the written
|
||||
contract without importing the implementation.
|
||||
|
||||
Keep fast in-process fakes for malformed and failure cases. Add boundaries for
|
||||
split/coalesced frames, multiple buffered messages, unknown fields, peer EOF,
|
||||
stderr noise, slow response, cancellation, and restart. For MCP, the live
|
||||
Desktop Commander opt-in is compatibility evidence; a helper server that uses
|
||||
Archie's own `readMessage`/`writeMessage` is not.
|
||||
|
||||
### Test aliasing and ownership
|
||||
|
||||
For maps, slices, schemas, options, registries, and configuration projections:
|
||||
|
||||
1. mutate the input after construction and prove owned state does not change;
|
||||
2. mutate the returned value and prove internal state does not change;
|
||||
3. mutate nested maps/slices, not only the top level;
|
||||
4. run concurrent readers/writers under `-race` when sharing is permitted.
|
||||
|
||||
### Test concurrency and cancellation deterministically
|
||||
|
||||
Use barriers, channels, fakes, and explicit clocks to force ordering. Do not use
|
||||
`time.Sleep` as the sole synchronization proof.
|
||||
|
||||
Cover:
|
||||
|
||||
- cancellation before work starts;
|
||||
- cancellation while blocked on I/O, a stream, child process, or queue;
|
||||
- child and grandchild termination for subprocesses;
|
||||
- no retry after caller cancellation;
|
||||
- start/stop and close/send races;
|
||||
- bounded drain and no goroutine leak;
|
||||
- same-repository serialization and permitted cross-repository overlap;
|
||||
- defensive copies around shared mutable state.
|
||||
|
||||
Run the race detector after deterministic tests pass. `-race` can reveal a race;
|
||||
it cannot prove the intended ordering or state machine.
|
||||
|
||||
### Test transitions as compare-and-set operations
|
||||
|
||||
For every state-changing method, table legal and illegal transitions. Assert
|
||||
that:
|
||||
|
||||
- the supplied `from` state or version is enforced;
|
||||
- two contenders starting from the same state cannot both succeed;
|
||||
- the new state and audit/event record are one atomic outcome;
|
||||
- retries are idempotent or explicitly rejected;
|
||||
- failure leaves neither partial state nor a false success record;
|
||||
- every live adapter preserves the same semantics.
|
||||
|
||||
Do not accept a test that only shows `queued -> running` succeeds. It misses
|
||||
lost updates, invalid transitions, and state/audit divergence.
|
||||
|
||||
## Run exact gates
|
||||
|
||||
Create writable, task-specific caches once:
|
||||
|
||||
```bash
|
||||
mkdir -p /tmp/archie-qa-tmp /tmp/archie-qa-gocache /tmp/archie-qa-lintcache
|
||||
```
|
||||
|
||||
### Iterate on one test and package
|
||||
|
||||
Replace the placeholders with real names:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go test ./internal/<package>/... -run '^TestName$' -count=1 -v
|
||||
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go test ./internal/<package>/... -count=1
|
||||
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache GOLANGCI_LINT_CACHE=/tmp/archie-qa-lintcache golangci-lint run ./internal/<package>/...
|
||||
```
|
||||
|
||||
Use the same command for red and green. Record both outputs.
|
||||
|
||||
### Run the root evidence
|
||||
|
||||
Run `task check` only in an authorized, isolated tree. It mutates source with
|
||||
`gofumpt -w .` and `go fix ./...`, and writes binaries under `bin/`. Inspect
|
||||
the complete before/after diff; never let its broad rewrite hide concurrent
|
||||
changes.
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache task check
|
||||
git status --short
|
||||
gofumpt -l .
|
||||
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go fix -diff ./...
|
||||
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache GOLANGCI_LINT_CACHE=/tmp/archie-qa-lintcache golangci-lint run ./...
|
||||
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go test -race ./... -count=1
|
||||
```
|
||||
|
||||
Expected acceptance output:
|
||||
|
||||
- `gofumpt -l .`: no paths;
|
||||
- `go fix -diff ./...`: no diff and exit zero;
|
||||
- lint: zero findings;
|
||||
- tests, vet, and builds: exit zero;
|
||||
- race suite: exit zero and no race report.
|
||||
|
||||
Do not say `task check` covers lint or race. It does not.
|
||||
|
||||
### Run the nested tools and documentation evidence
|
||||
|
||||
Run this when `tools/**`, published contracts, generated data, or their root
|
||||
consumers change:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go -C tools test ./... -count=1
|
||||
(cd tools && env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache GOLANGCI_LINT_CACHE=/tmp/archie-qa-lintcache golangci-lint run ./...)
|
||||
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go -C tools run ./docsgen
|
||||
git diff --exit-code -- docs-2/data/generated/contracts.json
|
||||
(cd docs-2 && pnpm install --frozen-lockfile)
|
||||
(cd docs-2 && pnpm build)
|
||||
```
|
||||
|
||||
The current docsgen command generates data only. Do not use target-only
|
||||
`docsgen all` or `docsgen check` commands from the architecture PRD until the
|
||||
live binary implements them.
|
||||
|
||||
## Separate environment failures from regressions
|
||||
|
||||
| Symptom | Classify first as | Required next action |
|
||||
|---|---|---|
|
||||
| `listen tcp ... operation not permitted`, `httptest: failed to listen`, or NATS “Unable to start” | Restricted sandbox lacks loopback/listener access | Rerun the same command in an environment that permits local listeners. Do not weaken or skip the test. |
|
||||
| Git fixture commit fails with GPG/keybox read-only errors | Inherited host `commit.gpgSign`, inaccessible keyring | Rerun with the temporary Git config override below; do not modify global Git configuration. |
|
||||
| Go or lint cache reports read-only/permission errors | Environment/cache | Use the writable cache paths above. If the module cache itself is read-only, use a prewarmed writable `GOMODCACHE`; a dependency-download failure is still environmental evidence, not a product result. |
|
||||
| Desktop Commander test is skipped | Expected default | Run the explicit opt-in only with authorization for `npx` network/download and external process execution. |
|
||||
| `TestRunWrapsExternalCommand` returns `"\n"` | Known 2026-07-28 code baseline | Treat as a real failure until fixed; do not group it with sandbox denials. |
|
||||
| Assertion reports wrong state/output after setup completed | Probable code regression | Minimize with the named test, compare pre-change baseline, and use `archie-debugging-playbook`. |
|
||||
|
||||
Use this non-persistent signing override for tests that spawn Git commits:
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=commit.gpgSign GIT_CONFIG_VALUE_0=false go test ./internal/workflow/... -count=1
|
||||
```
|
||||
|
||||
Run the external MCP compatibility check only when explicitly authorized:
|
||||
|
||||
```bash
|
||||
env ARCHIE_TEST_DESKTOP_COMMANDER=1 GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go test ./internal/tools/provider/mcp -run '^TestDesktopCommanderClientCompatibility$' -count=1 -v
|
||||
```
|
||||
|
||||
Record the external package version, network availability, platform, and
|
||||
whether the failure occurred during download/startup or after MCP exchange.
|
||||
|
||||
## Require adversarial review after green
|
||||
|
||||
Use a fresh reviewer with no implementation narrative. Give it the request,
|
||||
diff, governing contract, and raw gate outputs. Do not give it the author's
|
||||
defense of the design.
|
||||
|
||||
Require the reviewer to:
|
||||
|
||||
- rerun or inspect all applicable gates;
|
||||
- read every changed non-test file and its production callers/consumers;
|
||||
- find dead or duplicate paths and identify what the feature supersedes;
|
||||
- inspect unchecked errors, nil risks, hardcoded identity/config, and partial
|
||||
side effects;
|
||||
- inspect interface satisfaction, ownership, aliasing, cancellation,
|
||||
goroutine/process leaks, races, and state transitions;
|
||||
- verify real composition, protocol independence, deployment passthrough, and
|
||||
negative cases;
|
||||
- report findings without silently fixing them.
|
||||
|
||||
Fix blocking and important findings in a separate implementation pass. Rerun
|
||||
all affected gates, then have the reviewer verify that **zero surviving
|
||||
findings** remain. The implementer never self-certifies this pass.
|
||||
|
||||
## Enforce acceptance thresholds
|
||||
|
||||
Build this evidence packet:
|
||||
|
||||
| Evidence | Threshold |
|
||||
|---|---|
|
||||
| Scope and tree identity | Exact change claim, affected packages/processes, commit or supplied tree identity, and pre-existing dirty paths recorded. |
|
||||
| Red | Named test fails for the intended assertion; compile/setup/environment failures: `0`. |
|
||||
| Green | Named test and owning package pass; unexpected failures: `0`. |
|
||||
| Error behavior | Every reachable error path in scope has an assertion on error and consequence; unexplained paths: `0`. |
|
||||
| Wiring | At least one composition/contract test per changed handoff plus a negative wiring case. |
|
||||
| Protocol | At least one independent-peer/conformance result for changed protocol semantics. |
|
||||
| Concurrency/state | Deterministic ordering/transition tests pass; race reports: `0`; partial state/audit outcomes: `0`. |
|
||||
| Formatting/fix/lint | Formatter paths: `0`; fix diff: `0`; lint findings: `0`. |
|
||||
| Applicable suites | Scoped or root gate, race, tools, docs, and external checks selected by the matrix above; unexplained failures/skips: `0`. |
|
||||
| Maintainability | Superseded paths have keep/delete/cutover dispositions; unexplained duplicate or dead production paths: `0`. |
|
||||
| Review | Fresh adversarial reviewer has zero surviving blocking or important findings. |
|
||||
| Uncertainty | Every unproved claim is labeled `open` or `candidate`; hidden assumptions: `0`. |
|
||||
|
||||
Do not average evidence. One surviving race, wiring gap, unexplained skip,
|
||||
state-transition flaw, or blocking review finding blocks acceptance even when
|
||||
hundreds of unit tests pass. Route the completed packet through
|
||||
`archie-change-control`; testing does not itself authorize closure, deployment,
|
||||
or migration.
|
||||
|
||||
## Provenance and maintenance
|
||||
|
||||
Grounded on 2026-07-28 in `CLAUDE.md`, `Taskfile.yml`, root and `tools` module
|
||||
manifests, both workflow directories, the ordinary test suite, the Desktop
|
||||
Commander opt-in, and the live docsgen command. Recheck volatile facts before
|
||||
using them:
|
||||
|
||||
```bash
|
||||
sed -n '1,120p' Taskfile.yml
|
||||
find . -name go.mod -print | sort
|
||||
rg -n '^//go:build|ARCHIE_TEST_[A-Z0-9_]+' --glob '*_test.go' .
|
||||
rg -n 'task check|go test|golangci-lint|go vet|pnpm build' .github/workflows .gitea/workflows Taskfile.yml
|
||||
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go test ./... -count=1
|
||||
env GOTMPDIR=/tmp/archie-qa-tmp GOCACHE=/tmp/archie-qa-gocache go -C tools test ./... -count=1
|
||||
go -C tools run ./docsgen -h
|
||||
```
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Archie Validation and QA"
|
||||
short_description: "Build defensible test and quality evidence"
|
||||
default_prompt: "Use $archie-validation-and-qa to design and run the evidence needed to accept this archie-core change."
|
||||
@@ -157,3 +157,4 @@
|
||||
{"id":"int-e2b07b5c81dd19cabd9e2a18ff94f7f7","kind":"field_change","created_at":"2026-07-27T12:20:51.572157777Z","actor":"Sam Catlow","issue_id":"archie-core-sc5","extra":{"field":"status","new_value":"closed","old_value":"open","reason":"Implemented gateway.BuildSystemPrompt rendering internal/gateway/templates/archie.md.tpl: instruction precedence, core rules, communication rules, <tools> and <env> blocks, with PersonaRegistry kept as the style layer on top. Tool inventory is derived from the same core.ToolSet passed to the model (cmd/archied/toolSummaries) so prompt and reality cannot drift; empty toolset renders an explicit 'no tools are available'. Tool metadata is markup-escaped and whitespace-flattened against forged tags and forged list entries. task check clean: vet, full go test ./... , golangci-lint 0 issues on changed packages, gofumpt clean. Commit 7fde716. NOT yet deployed - not pushed."}}
|
||||
{"id":"int-c52b1ab5add5f30c8a63b5f03e5faff7","kind":"field_change","created_at":"2026-07-27T13:47:42.515040687Z","actor":"Sam Catlow","issue_id":"archie-core-4we","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Ported tau internal/indexing/codesearch.go @ 4893818d0c76 into archie-core internal/indexing. Mutations: global config path helpers replaced by explicit indexing.Config + DefaultConfig(workDir) (two archied instances share carina and must not share an index); child-process helper is archied's own 'workspace-codesearch' subcommand in cmd/archied/codesearch.go, dispatched from main() before flag parsing so it touches no config/store/NATS; deferred db.Close explicitly discarded for errcheck. Added dep github.com/google/codesearch v1.3.0-rc.1 (uuid and modernc sqlite already present). Verified E2E against the real repo: 2.2MB indexed in 0.05s, correct hits, [] for no match, corrupt index -> clean error exit 1 rather than process death. task check clean; golangci-lint 0 issues on both packages. Commit c924281. NOT pushed. Follow-up: nothing calls indexing.NewManager yet -- it is ported and proven but not wired into the agent's grep path."}}
|
||||
{"id":"int-eccef7ef7597bda3a8162e06651e8ea2","kind":"field_change","created_at":"2026-07-28T08:35:54.89529236Z","actor":"Sam Catlow","issue_id":"archie-core-6pp","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Removed all unauthorized source-project references and accompanying rationale; validation and independent review complete."}}
|
||||
{"id":"int-629331053ed3e16cfc7e4c66ec2dd88b","kind":"field_change","created_at":"2026-07-28T09:32:22.211586558Z","actor":"Sam Catlow","issue_id":"archie-core-5d7.1","extra":{"field":"status","new_value":"closed","old_value":"in_progress","reason":"Deterministic contract data JSON slice implemented test-first, validated, documented, and independently reviewed with zero surviving findings."}}
|
||||
+3
-2
@@ -53,8 +53,8 @@
|
||||
{"_type":"issue","id":"archie-core-abg.18","title":"[EPIC] Memory: pluggable provider architecture with file-backed persistence","description":"Pluggable memory system to match Hermes parity:\\n\\n1. **MemoryProvider interface**: Abstract interface with methods for initialize(), get_tool_schemas(), prefetch(), sync_turn(), and optional lifecycle hooks (on_session_end, on_session_switch, on_pre_compress, on_memory_write).\\n\\n2. **Built-in file-backed memory**: MEMORY.md and USER.md stored per-session/profile. LLM-callable memory tool with add/replace/remove actions. Frozen snapshot at session start (preserves prefix cache), immediate disk write on updates. Section-sign delimited entries with substring matching.\\n\\n3. **MemoryManager**: Orchestrates built-in + at most one external provider. Background serialized write executor. Prefetch with timeout (8s). Streaming context scrubber that strips injected memory spans from model output.\\n\\nRef: docs/prds/hermes-gap-analysis.md section 4","acceptance_criteria":"An external memory provider (e.g. Honcho, Mem0) can be plugged in via config. The built-in memory tool persists across sessions. Conversation context is recalled on session resume.","status":"open","priority":0,"issue_type":"epic","owner":"sam@catlow.tech","created_at":"2026-07-25T14:02:22Z","created_by":"Sam Catlow","updated_at":"2026-07-25T14:02:22Z","dependencies":[{"issue_id":"archie-core-abg.18","depends_on_id":"archie-core-abg","type":"parent-child","created_at":"2026-07-26T00:02:22Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
|
||||
{"_type":"issue","id":"archie-core-abg.16","title":"[EPIC] Gateway: rich message model, adapter lifecycle, session management","description":"Foundational gateway infrastructure to match Hermes parity. Three interdependent pieces:\\n\\n1. **Message model**: Replace the 3-field Message struct with a rich MessageEvent (MessageType enum: text/photo/video/audio/voice/document/sticker/command, media_urls, reply_to context, metadata dict, source). This is the wire type every adapter produces.\\n\\n2. **Adapter lifecycle**: Replace the 3-method Gateway interface with a BasePlatformAdapter interface: connect()/disconnect()/send() as required methods, plus optional overrides for typing indicators, edit/delete, image/voice/video/document send, interactive UX (clarify buttons, approval dialogs). Capability flags (supports_code_blocks, splits_long_messages, supports_async_delivery).\\n\\n3. **Session management**: SessionSource struct (platform, chat_id, chat_type, user_id, thread_id, guild_id, profile), AsyncSessionStore for persistent session storage, SessionContext for system prompt injection.\\n\\nAll three blocks together enable adding new platforms as plugins without touching core gateway code.\\n\\nRef: docs/prds/hermes-gap-analysis.md sections 1-2","acceptance_criteria":"New adapters can be added by implementing a Go interface with connect/disconnect/send + optional media methods. Messages carry full metadata through the pipeline. Sessions persist across gateway restarts.","status":"open","priority":0,"issue_type":"epic","owner":"sam@catlow.tech","created_at":"2026-07-25T14:02:21Z","created_by":"Sam Catlow","updated_at":"2026-07-25T14:02:21Z","dependencies":[{"issue_id":"archie-core-abg.16","depends_on_id":"archie-core-abg","type":"parent-child","created_at":"2026-07-26T00:02:21Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
|
||||
{"_type":"issue","id":"archie-core-jfg","title":"Spawned archie-agent containers not on daemon's docker network — can't reach NATS","description":"Root cause of 'agent still failing on the server': archied's container.Pool.Acquire creates archie-agent containers via the Docker SDK with no NetworkMode set, so Docker attaches them to the default bridge network. archied and nats run on the compose-created 'archie-core_default' network instead, so the spawned container's hostname resolution for 'nats' (from NATS_URL=nats://nats:4222) fails and archie-agent can't connect. Confirmed on carina host logs: archied logs show repeating 'taskrun request failed err=\"nats: no responders available for request\"' for every task, containers created and destroyed within ~1.5s (consistent with archie-agent's NATS client failing fast). Fixed by detecting the daemon's own container's network in NewPool (selfNetwork, via ContainerInspect on os.Hostname()) and setting HostConfig.NetworkMode on spawned containers to match.","status":"closed","priority":0,"issue_type":"bug","owner":"sam@catlow.tech","created_at":"2026-07-24T03:10:26Z","created_by":"Sam Catlow","updated_at":"2026-07-25T13:04:34Z","closed_at":"2026-07-25T13:04:34Z","close_reason":"Fix already implemented and verified: selfNetwork() in internal/container/pool.go detects the daemon's own container network via ContainerInspect(os.Hostname()) and Acquire() sets HostConfig.NetworkMode to match, so spawned archie-agent containers join the same compose network as nats. Build and internal/container tests pass.","dependency_count":0,"dependent_count":0,"comment_count":0}
|
||||
{"_type":"issue","id":"archie-core-6pp","title":"Remove source-project references from Archie","description":"Remove every tau reference outside the explicitly preserved Beads data and docs-2/README.md. Delete copied product-specific documentation and accompanied rationale rather than mechanically renaming it. Retain reusable documentation-generation and VitePress scaffolding only after removing source-specific coupling. Update code, tests, archives, and architecture documents so archie-core contains no unauthorized tau references.","acceptance_criteria":"rg 'tau' -ow excluding .beads/** and docs-2/README.md returns zero; retained tools and documentation scaffolding contain no source-project imports, paths, product claims, or rationale; relevant validation passes.","notes":"Complete. Exact case-insensitive whole-word scan excluding .git/**, .beads/**, and docs-2/README.md returns 0. Source-specific provenance and rationale removed, neutral fixtures preserve behavior, docs workflow/site build from docs-2, retained README excluded from publication, and Archie-owned docsgen generates current agent contracts without process-global cwd mutation. tools tests/vet pass; affected package tests pass; VitePress production build passes. Fresh adversarial review reports zero surviving findings. Full task check passes fmt/go-fix/vet/build and all packages except unrelated pre-existing internal/skillscript TestRunWrapsExternalCommand (Run returned newline).","status":"in_progress","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T08:00:32Z","created_by":"Sam Catlow","updated_at":"2026-07-28T08:35:54Z","started_at":"2026-07-28T08:00:37Z","dependency_count":0,"dependent_count":0,"comment_count":0}
|
||||
{"_type":"issue","id":"archie-core-5d7","title":"Define target project organisation and restructuring rules","description":"Run a package-by-package architecture grilling session, establish the target DDD and semi-microservice organisation, record strict restructuring requirements and package destinations, and produce docs/prds/01-project-management.md as the durable handoff.","acceptance_criteria":"The PRD records agreed project-wide organisation rules, bounded-context and service/plugin boundaries, dependency constraints, migration principles, and the destination of each reviewed package. Decisions are confirmed one at a time with the user before the document is finalized.","notes":"Corrected documentation-generation wording: removed repeated source-project provenance from the target architecture. The copied generator/site are now described only as an implementation baseline with concrete adaptation gaps; the architecture is expressed entirely in Archie terms. Updated generated-documentation.md and its migration-decisions.md reference.","status":"in_progress","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T00:00:36Z","created_by":"Sam Catlow","updated_at":"2026-07-28T07:27:47Z","started_at":"2026-07-28T00:00:42Z","dependency_count":0,"dependent_count":0,"comment_count":0}
|
||||
{"_type":"issue","id":"archie-core-6pp","title":"Remove source-project references from Archie","description":"Remove every tau reference outside the explicitly preserved Beads data and docs-2/README.md. Delete copied product-specific documentation and accompanied rationale rather than mechanically renaming it. Retain reusable documentation-generation and VitePress scaffolding only after removing source-specific coupling. Update code, tests, archives, and architecture documents so archie-core contains no unauthorized tau references.","acceptance_criteria":"rg 'tau' -ow excluding .beads/** and docs-2/README.md returns zero; retained tools and documentation scaffolding contain no source-project imports, paths, product claims, or rationale; relevant validation passes.","notes":"Complete. Exact case-insensitive whole-word scan excluding .git/**, .beads/**, and docs-2/README.md returns 0. Source-specific provenance and rationale removed, neutral fixtures preserve behavior, docs workflow/site build from docs-2, retained README excluded from publication, and Archie-owned docsgen generates current agent contracts without process-global cwd mutation. tools tests/vet pass; affected package tests pass; VitePress production build passes. Fresh adversarial review reports zero surviving findings. Full task check passes fmt/go-fix/vet/build and all packages except unrelated pre-existing internal/skillscript TestRunWrapsExternalCommand (Run returned newline).","status":"closed","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T08:00:32Z","created_by":"Sam Catlow","updated_at":"2026-07-28T08:35:55Z","started_at":"2026-07-28T08:00:37Z","closed_at":"2026-07-28T08:35:55Z","close_reason":"Removed all unauthorized source-project references and accompanying rationale; validation and independent review complete.","dependency_count":0,"dependent_count":0,"comment_count":0}
|
||||
{"_type":"issue","id":"archie-core-5d7","title":"Define target project organisation and restructuring rules","description":"Run a package-by-package architecture grilling session, establish the target DDD and semi-microservice organisation, record strict restructuring requirements and package destinations, and produce docs/prds/01-project-management.md as the durable handoff.","acceptance_criteria":"The PRD records agreed project-wide organisation rules, bounded-context and service/plugin boundaries, dependency constraints, migration principles, and the destination of each reviewed package. Decisions are confirmed one at a time with the user before the document is finalized.","notes":"Corrected generated-documentation.md to the agreed architecture: production code/registries/config/CLI are authoritative; docsgen emits deterministic JSON data and protocol schemas only; typed VitePress data loaders/components/templates own page rendering; generated Markdown is prohibited. First implementation slice tracked and completed as archie-core-5d7.1.","status":"in_progress","priority":1,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T00:00:36Z","created_by":"Sam Catlow","updated_at":"2026-07-28T09:32:22Z","started_at":"2026-07-28T00:00:42Z","dependency_count":0,"dependent_count":0,"comment_count":0}
|
||||
{"_type":"issue","id":"archie-core-qa4.4","title":"Phase 4: structural refactor (~28 issues)","description":"funlen, gocognit, cyclop, nestif, maintidx, interfacebloat. This IS the internal/config restructure already discussed (finalize at cognitive complexity 106, feature_config loadDirInto at 74) plus daemon process/checkWaiting. MUST BE LAST: refactoring moves line numbers and invalidates every other phase in flight. Fold into the config file-per-responsibility split rather than doing the same work twice.","status":"open","priority":1,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-07-27T15:23:01Z","created_by":"Sam Catlow","updated_at":"2026-07-27T15:23:01Z","dependencies":[{"issue_id":"archie-core-qa4.4","depends_on_id":"archie-core-qa4","type":"parent-child","created_at":"2026-07-28T01:23:00Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
|
||||
{"_type":"issue","id":"archie-core-qa4.3","title":"Phase 3: correctness findings needing judgement (~62 issues)","description":"nilerr (11: 6 in internal/agentexec inprocess.go/worker.go, 2 gateway), bodyclose (1), contextcheck (7), containedctx (2), fatcontext. SINGLE SESSION, sequential, no subagents: each nilerr site needs a read of whether the swallow is deliberate degradation or a real bug, and a context-free worker will silently convert deliberate behaviour into a change. Do nilerr FIRST -- highest bug probability in the whole set. BLOCKED on a policy decision for noctx (41 sites, mostly webui/worktree/store): fixing it means threading context through public APIs, which is an API change, not a lint fix.","status":"open","priority":1,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-07-27T15:23:00Z","created_by":"Sam Catlow","updated_at":"2026-07-27T15:23:00Z","dependencies":[{"issue_id":"archie-core-qa4.3","depends_on_id":"archie-core-qa4","type":"parent-child","created_at":"2026-07-28T01:23:00Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
|
||||
{"_type":"issue","id":"archie-core-qa4.1","title":"Phase 1: autofix pass (~35 issues)","description":"golangci-lint run --fix plus the formatters. Covers errorlint, fatcontext, gocritic, sloglint, usestdlibvars, usetesting, gci, gofumpt, goimports. Zero judgement. MUST run first: it touches formatting across every file and would conflict with anything in flight. Single command, single commit, verify with task check.","status":"open","priority":1,"issue_type":"task","owner":"sam@catlow.tech","created_at":"2026-07-27T15:22:59Z","created_by":"Sam Catlow","updated_at":"2026-07-27T15:22:59Z","dependencies":[{"issue_id":"archie-core-qa4.1","depends_on_id":"archie-core-qa4","type":"parent-child","created_at":"2026-07-28T01:22:58Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
|
||||
@@ -145,6 +145,7 @@
|
||||
{"_type":"issue","id":"archie-core-s1r","title":"Test forge fakes missing LinkBranch method broke go vet/test for whole module","description":"forge.Forge gained LinkBranch(ctx, owner, repo, issueNumber, branch) error in the branch-linking feature (ff4c51e) but the hand-rolled test doubles (stubForge in cmd/archied/main_test.go, prCapturingForge in cmd/archie-agent/taskrun_test.go, testForge in internal/daemon/daemon_test.go, fakeForge in internal/forgerpc/forgerpc_test.go) never got the method added, so they stopped satisfying forge.Forge. This broke go vet ./... and go test ./... for the entire module, not just those 4 packages, since go vet type-checks all test files as part of module vet. Fixed by adding LinkBranch stubs to all four fakes.","status":"closed","priority":1,"issue_type":"bug","owner":"sam@catlow.tech","created_at":"2026-07-24T03:04:53Z","created_by":"Sam Catlow","updated_at":"2026-07-24T03:04:58Z","closed_at":"2026-07-24T03:04:58Z","close_reason":"Added LinkBranch stub methods to stubForge, prCapturingForge, testForge, and fakeForge. go build/vet/test ./... now clean across the whole module.","dependency_count":0,"dependent_count":0,"comment_count":0}
|
||||
{"_type":"issue","id":"archie-core-633","title":"config.docker.toml missing required fields, no overlay merge implemented","description":"config.docker.toml was rewritten to be a docs-as-overlay file (comment says base+overlay merge) but internal/config.Load has no merge logic and docker-compose.yml mounts only config.docker.toml at /etc/archie/config.toml. It is missing bot_user, [forge], [dispatch], [models], [providers], [budgets] which Load requires -\u003e daemon fails to start in docker as currently configured. Implement real base+overlay config loading (or restore a full standalone docker config) so there is one source of truth.","status":"closed","priority":1,"issue_type":"bug","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-24T02:42:07Z","created_by":"Sam Catlow","updated_at":"2026-07-24T02:44:53Z","started_at":"2026-07-24T02:42:11Z","closed_at":"2026-07-24T02:44:53Z","close_reason":"Implemented config.LoadOverlay (base decode + overlay decode into same struct, then shared finalize/validate), wired -config-overlay flag in cmd/archied, fixed docker-compose.yml to mount both base config.toml and config.docker.toml overlay, minimized config.docker.toml to true diff-only overlay, added tests proving overlay-omitted required fields (bot_user, repos) still come from base.","dependency_count":0,"dependent_count":0,"comment_count":0}
|
||||
{"_type":"issue","id":"archie-core-u64","title":"Daemon: process multiple tasks concurrently (max_concurrency enforcement)","description":"Daemon currently processes one task at a time (docs/prds/archie-core-v2-architecture.md Phase 2). This is the core blocker between current state and any multi-agent scaling mode — needed before container max_concurrency or same-repo concurrency can matter. Wire the daemon's dispatch loop to run N tasks in parallel, respecting a configurable max_concurrency.","design":"internal/container/pool.go already enforces max_concurrency for container lifecycle — reuse that limit/pattern in the daemon's task dispatch rather than inventing a second concurrency control.","acceptance_criteria":"Daemon dispatch loop runs multiple tasks concurrently up to a configured max_concurrency limit; single-task-at-a-time behavior is gone.","status":"closed","priority":1,"issue_type":"feature","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-23T19:36:31Z","created_by":"Sam Catlow","updated_at":"2026-07-23T21:37:42Z","started_at":"2026-07-23T21:29:41Z","closed_at":"2026-07-23T21:37:42Z","close_reason":"Implemented concurrent SQLite and NATS task dispatch using containers.max_concurrency, with default same-repo serialization and race-tested dispatcher coverage.","dependency_count":0,"dependent_count":2,"comment_count":0}
|
||||
{"_type":"issue","id":"archie-core-5d7.1","title":"Docsgen: emit deterministic contract data JSON","description":"Begin the generated-documentation implementation with the smallest vertical slice: normalize the existing Archie contract schemas into deterministic JSON under docs-2/data/generated for VitePress consumption, without generating Markdown pages. Preserve the nested tools module and existing source-of-truth imports.","acceptance_criteria":"A failing test first proves docsgen emits valid generated JSON at the data path; repeated generation is byte-identical; tools tests and vet pass; generated-documentation.md reflects the agreed data-loader architecture.","notes":"Implemented the first docs generation slice test-first: docsgen now emits deterministic JSON contract data at docs-2/data/generated/contracts.json, carries generator provenance, rejects duplicate published names and conflicting definitions, validates resolved internal references in tests, and keeps the current hardcoded contract set as an explicit migration adapter with deletion criteria. Scoped tools tests, vet, and golangci-lint pass; repeated generation is byte-identical; adversarial review reports zero surviving findings.","status":"closed","priority":2,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-28T09:17:08Z","created_by":"Sam Catlow","updated_at":"2026-07-28T09:32:22Z","started_at":"2026-07-28T09:17:13Z","closed_at":"2026-07-28T09:32:22Z","close_reason":"Deterministic contract data JSON slice implemented test-first, validated, documented, and independently reviewed with zero surviving findings.","dependencies":[{"issue_id":"archie-core-5d7.1","depends_on_id":"archie-core-5d7","type":"parent-child","created_at":"2026-07-28T19:17:08Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
|
||||
{"_type":"issue","id":"archie-core-qfx","title":"Flaky: TestRunTaskExecutesBootstrapWorkflowEndToEnd races on NATS responders","description":"cmd/archie-agent. Intermittently fails with ParkReason 'stage prepare: archie.worktree.prepare: nats: no responders available for request'; passes on re-run (-count=3 clean). The test does not wait for the worktreerpc subscription to be established before dispatching. A flaky test in task check is poison: it trains everyone to re-run instead of read, which is how a real regression gets waved through.","status":"open","priority":2,"issue_type":"bug","owner":"sam@catlow.tech","created_at":"2026-07-27T15:27:55Z","created_by":"Sam Catlow","updated_at":"2026-07-27T15:27:55Z","dependency_count":0,"dependent_count":0,"comment_count":0}
|
||||
{"_type":"issue","id":"archie-core-5dn","title":"Document Hermes capabilities missing from Archie","description":"Investigate Hermes' available features and commands, compare them with Archie, and publish a simple Markdown TODO checklist excluding Kanban.","status":"closed","priority":2,"issue_type":"task","assignee":"Sam Catlow","owner":"sam@catlow.tech","created_at":"2026-07-27T12:09:56Z","created_by":"Sam Catlow","updated_at":"2026-07-27T12:11:14Z","started_at":"2026-07-27T12:10:00Z","closed_at":"2026-07-27T12:11:14Z","close_reason":"Investigated local Hermes CLI and current Archie implementation; added the requested parity TODO checklist.","dependency_count":0,"dependent_count":0,"comment_count":0}
|
||||
{"_type":"issue","id":"archie-core-alm.3","title":"Telegram: multi-home-channel command","description":"When multiple home channels are introduced, design /sethome with /set_home alias to set a chat as a home channel. Define identity ownership, overwrite/confirmation rules, group authorization, persistence, and relationship to sessions before implementation.","acceptance_criteria":"Blocked on the multiple-home-channel model; once unblocked, both aliases have identical safe behaviour, persist correctly, and are covered by authorization and migration tests.","status":"open","priority":2,"issue_type":"feature","owner":"sam@catlow.tech","created_at":"2026-07-27T08:56:50Z","created_by":"Sam Catlow","updated_at":"2026-07-27T08:56:50Z","dependencies":[{"issue_id":"archie-core-alm.3","depends_on_id":"archie-core-alm","type":"parent-child","created_at":"2026-07-27T18:56:49Z","created_by":"Sam Catlow","metadata":"{}"}],"dependency_count":0,"dependent_count":0,"comment_count":0}
|
||||
|
||||
@@ -0,0 +1,400 @@
|
||||
{
|
||||
"generatedBy": "tools/docsgen",
|
||||
"schemas": {
|
||||
"AgentExecutionRequest": {
|
||||
"additionalProperties": false,
|
||||
"description": "Request is the complete, serializable input for one agent stage.",
|
||||
"properties": {
|
||||
"attempt": {
|
||||
"type": "integer"
|
||||
},
|
||||
"budget": {
|
||||
"$ref": "#/schemas/Budget"
|
||||
},
|
||||
"capture_tools": {
|
||||
"items": {
|
||||
"$ref": "#/schemas/CaptureTool"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"extra_rules": {
|
||||
"type": "string"
|
||||
},
|
||||
"gate": {
|
||||
"$ref": "#/schemas/Gate"
|
||||
},
|
||||
"mission": {
|
||||
"type": "string"
|
||||
},
|
||||
"model": {
|
||||
"type": "string"
|
||||
},
|
||||
"notes": {
|
||||
"type": "string"
|
||||
},
|
||||
"plugins": {
|
||||
"description": "Plugins are bundled Yaegi plugins from the skill's plugins/\ndirectory. Each entry carries the name and source so the agent\ncan register them as tools. PRD section 5 Layer 1.",
|
||||
"items": {
|
||||
"$ref": "#/schemas/PluginSpec"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"preflight": {
|
||||
"items": {
|
||||
"$ref": "#/schemas/Command"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"protection": {
|
||||
"$ref": "#/schemas/Protection"
|
||||
},
|
||||
"read_only": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"stage": {
|
||||
"type": "string"
|
||||
},
|
||||
"task_id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"version": {
|
||||
"type": "integer"
|
||||
},
|
||||
"workflow": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"version",
|
||||
"task_id",
|
||||
"attempt",
|
||||
"stage",
|
||||
"model",
|
||||
"mission",
|
||||
"budget",
|
||||
"gate",
|
||||
"protection"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"AgentExecutionResult": {
|
||||
"additionalProperties": false,
|
||||
"description": "Result is the serializable outcome of one agent stage.",
|
||||
"properties": {
|
||||
"appended_notes": {
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"attempt": {
|
||||
"type": "integer"
|
||||
},
|
||||
"captures": {
|
||||
"additionalProperties": {
|
||||
"items": true,
|
||||
"type": "array"
|
||||
},
|
||||
"type": "object"
|
||||
},
|
||||
"changes": {
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"detail": {
|
||||
"type": "string"
|
||||
},
|
||||
"iterations": {
|
||||
"type": "integer"
|
||||
},
|
||||
"stage": {
|
||||
"type": "string"
|
||||
},
|
||||
"status": {
|
||||
"type": "string"
|
||||
},
|
||||
"stop_reason": {
|
||||
"type": "string"
|
||||
},
|
||||
"summary": {
|
||||
"type": "string"
|
||||
},
|
||||
"task_id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"tokens_used": {
|
||||
"type": "integer"
|
||||
},
|
||||
"version": {
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"version",
|
||||
"task_id",
|
||||
"attempt",
|
||||
"stage",
|
||||
"status"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"Budget": {
|
||||
"additionalProperties": false,
|
||||
"description": "Budget bounds one autonomous execution.",
|
||||
"properties": {
|
||||
"max_steps": {
|
||||
"type": "integer"
|
||||
},
|
||||
"max_tokens": {
|
||||
"type": "integer"
|
||||
},
|
||||
"wall_clock": {
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"type": "object"
|
||||
},
|
||||
"CaptureTool": {
|
||||
"additionalProperties": false,
|
||||
"description": "CaptureTool declares a structured-output tool whose calls are returned to the daemon as data.",
|
||||
"properties": {
|
||||
"boolean_fields": {
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"description": {
|
||||
"type": "string"
|
||||
},
|
||||
"max_calls": {
|
||||
"type": "integer"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"non_empty_strings": {
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"parameters": true,
|
||||
"required_fields": {
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"name"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"Command": {
|
||||
"additionalProperties": false,
|
||||
"description": "Command is one executable gate or preflight command.",
|
||||
"properties": {
|
||||
"argv": {
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"expect_failure": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"name": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"name",
|
||||
"argv"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"Gate": {
|
||||
"additionalProperties": false,
|
||||
"description": "Gate is the quality gate an agent must satisfy.",
|
||||
"properties": {
|
||||
"commands": {
|
||||
"items": {
|
||||
"$ref": "#/schemas/Command"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"max_consecutive_failures": {
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"type": "object"
|
||||
},
|
||||
"MediaAttachment": {
|
||||
"additionalProperties": false,
|
||||
"description": "MediaAttachment describes a file attached to a message.",
|
||||
"properties": {
|
||||
"duration": {
|
||||
"description": "Duration is the play time in seconds for audio and video.",
|
||||
"type": "integer"
|
||||
},
|
||||
"file_id": {
|
||||
"description": "FileID is the platform-assigned identifier for download APIs.",
|
||||
"type": "string"
|
||||
},
|
||||
"file_name": {
|
||||
"description": "FileName is the original file name when known.",
|
||||
"type": "string"
|
||||
},
|
||||
"file_size": {
|
||||
"description": "FileSize is the attachment size in bytes. nil means unknown.",
|
||||
"type": "integer"
|
||||
},
|
||||
"height": {
|
||||
"description": "Height is the pixel height for images and video.",
|
||||
"type": "integer"
|
||||
},
|
||||
"mime_type": {
|
||||
"description": "MIMEType is the content type (e.g. \"image/png\", \"audio/ogg\").",
|
||||
"type": "string"
|
||||
},
|
||||
"type": {
|
||||
"description": "Type is \"image\", \"video\", \"audio\", or \"document\".",
|
||||
"type": "string"
|
||||
},
|
||||
"url": {
|
||||
"description": "URL is a direct download URL when available. May be empty for\nplatforms that require a download API call.",
|
||||
"type": "string"
|
||||
},
|
||||
"width": {
|
||||
"description": "Width is the pixel width for images and video. nil means unknown\nor not applicable.",
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"type",
|
||||
"file_id"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"MessageEvent": {
|
||||
"additionalProperties": false,
|
||||
"description": "MessageEvent is the rich message model for all gateway channels.",
|
||||
"properties": {
|
||||
"callback_data": {
|
||||
"description": "CallbackData is the payload from a button or inline-keyboard\npress (Type == MsgCallback).",
|
||||
"type": "string"
|
||||
},
|
||||
"channel_id": {
|
||||
"description": "ChannelID identifies the conversation within the platform\n(chat ID, channel name, DM thread).",
|
||||
"type": "string"
|
||||
},
|
||||
"edited_from": {
|
||||
"description": "EditedFrom is the original text before the edit. Set only when\nType is MsgEdited.",
|
||||
"type": "string"
|
||||
},
|
||||
"id": {
|
||||
"description": "ID is the platform-assigned message identifier. Used for reply\nthreading, reactions, and edit/delete tracking.",
|
||||
"type": "string"
|
||||
},
|
||||
"media": {
|
||||
"description": "Media holds attached files. Nil for text-only messages.",
|
||||
"items": {
|
||||
"$ref": "#/schemas/MediaAttachment"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"platform": {
|
||||
"description": "Platform names the source adapter (\"telegram\", \"discord\",\n\"web\", \"slack\").",
|
||||
"type": "string"
|
||||
},
|
||||
"raw": {
|
||||
"description": "Raw is the original platform-specific payload. Adapters set\nthis for debug logging or handlers that need platform details\nnot captured by the generic fields.",
|
||||
"type": "object"
|
||||
},
|
||||
"reacted_to_id": {
|
||||
"description": "ReactedToID is the message being reacted to.",
|
||||
"type": "string"
|
||||
},
|
||||
"reaction": {
|
||||
"description": "Reaction is the emoji used when Type is MsgReaction.",
|
||||
"type": "string"
|
||||
},
|
||||
"reply_to_id": {
|
||||
"description": "ReplyToID is the platform message ID this message is in reply\nto. Empty for top-level messages.",
|
||||
"type": "string"
|
||||
},
|
||||
"sender_id": {
|
||||
"description": "SenderID is the platform-specific sender identifier.",
|
||||
"type": "string"
|
||||
},
|
||||
"sender_name": {
|
||||
"description": "SenderName is the display name when available.",
|
||||
"type": "string"
|
||||
},
|
||||
"text": {
|
||||
"description": "Text is the human-readable message body. It carries the caption\nfor media messages and the full content for text and system\nmessages.",
|
||||
"type": "string"
|
||||
},
|
||||
"thread_id": {
|
||||
"description": "ThreadID identifies the conversation thread for platforms that\nsupport threading (Slack, Discord forums).",
|
||||
"type": "string"
|
||||
},
|
||||
"timestamp": {
|
||||
"description": "Timestamp is the platform-assigned message time in Unix\nmilliseconds. Zero when unknown.",
|
||||
"type": "integer"
|
||||
},
|
||||
"type": {
|
||||
"description": "Type discriminates the message kind.",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"type",
|
||||
"channel_id",
|
||||
"platform",
|
||||
"sender_id"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"PluginSpec": {
|
||||
"additionalProperties": false,
|
||||
"description": "PluginSpec is a bundled Yaegi plugin passed from daemon to agent.",
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string"
|
||||
},
|
||||
"src": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"name",
|
||||
"src"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"Protection": {
|
||||
"additionalProperties": false,
|
||||
"description": "Protection describes paths the agent may read but not mutate.",
|
||||
"properties": {
|
||||
"globs": {
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"suffixes": {
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
}
|
||||
},
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -8,9 +8,12 @@
|
||||
|
||||
Archie's documentation-generation approach is:
|
||||
|
||||
- Go code and registries remain the source of truth for published contracts;
|
||||
- a repository-local Go generator produces schemas and reference pages;
|
||||
- VitePress renders handwritten and generated Markdown;
|
||||
- production Go code, registries, configuration, and CLI behaviour remain the
|
||||
source of truth for published contracts;
|
||||
- a repository-local Go generator extracts and normalizes documentation data;
|
||||
- the generator writes deterministic JSON/data files and protocol schemas;
|
||||
- VitePress data loaders, components, and templates render the generated data
|
||||
into reference pages;
|
||||
- GitHub Actions builds and publishes the static site.
|
||||
|
||||
Hugo is not part of the target architecture.
|
||||
@@ -90,8 +93,9 @@ authoritative tables.
|
||||
|
||||
## Target generation architecture
|
||||
|
||||
`tools/docsgen` is Archie's documentation generator. It produces protocol
|
||||
specifications and Markdown reference pages.
|
||||
`tools/docsgen` is Archie's documentation extractor and normalizer. It produces
|
||||
structured documentation data and protocol specifications. It does not own
|
||||
page layout and MUST NOT generate Markdown pages or fragments.
|
||||
|
||||
The generator is divided internally into reusable stages:
|
||||
|
||||
@@ -99,7 +103,7 @@ The generator is divided internally into reusable stages:
|
||||
load registries and types
|
||||
-> normalize documentation model
|
||||
-> validate ownership and identifiers
|
||||
-> render target artifacts
|
||||
-> serialize data and protocol artifacts
|
||||
-> compare or write output
|
||||
```
|
||||
|
||||
@@ -111,14 +115,14 @@ defaults, validation, secret classifications, and relationships.
|
||||
Initial generator targets:
|
||||
|
||||
```text
|
||||
docsgen data
|
||||
docsgen asyncapi
|
||||
docsgen pages
|
||||
docsgen all
|
||||
docsgen check
|
||||
```
|
||||
|
||||
- `data` writes the normalized JSON consumed by VitePress.
|
||||
- `asyncapi` writes protocol schemas and envelopes.
|
||||
- `pages` writes generated Markdown reference and its manifest.
|
||||
- `all` generates every committed artifact.
|
||||
- `check` generates into a temporary directory and fails on drift.
|
||||
|
||||
@@ -132,37 +136,48 @@ a visibly owned subtree:
|
||||
|
||||
```text
|
||||
docs-2/
|
||||
asyncapi/
|
||||
header.yaml
|
||||
archie.yaml
|
||||
reference/
|
||||
data/
|
||||
generated/
|
||||
_index.md
|
||||
cli/
|
||||
configuration/
|
||||
messaging/
|
||||
agents/
|
||||
workflows/
|
||||
policies/
|
||||
plugins/
|
||||
tools/
|
||||
manifest.json
|
||||
catalog.json
|
||||
contracts.json
|
||||
cli.json
|
||||
configuration.json
|
||||
messaging.json
|
||||
agents.json
|
||||
workflows.json
|
||||
policies.json
|
||||
plugins.json
|
||||
tools.json
|
||||
public/
|
||||
schemas/
|
||||
asyncapi-header.yaml
|
||||
archie.yaml
|
||||
.vitepress/
|
||||
config.mts
|
||||
generated-sidebar.mts
|
||||
data/
|
||||
reference.data.ts
|
||||
theme/
|
||||
components/
|
||||
.tmp/
|
||||
```
|
||||
|
||||
All files under `reference/generated/` carry a generated marker and MUST NOT be
|
||||
edited manually.
|
||||
All files under `data/generated/` and `public/schemas/` carry generated
|
||||
ownership metadata where their format permits it and MUST NOT be edited
|
||||
manually. `.tmp/` is generator-owned, ignored, and never committed.
|
||||
|
||||
`manifest.json` is the deterministic machine-readable index used for:
|
||||
`catalog.json` is the deterministic machine-readable index used for:
|
||||
|
||||
- generated sidebar and navigation entries;
|
||||
- reference navigation and route inputs;
|
||||
- duplicate-ID and duplicate-route validation;
|
||||
- coverage checks;
|
||||
- source-to-page drift diagnostics;
|
||||
- source-to-data drift diagnostics;
|
||||
- future external consumers.
|
||||
|
||||
VitePress loads these files at build time through a typed `.data.ts` loader.
|
||||
Pages and components import the loader's `data` export and render reference
|
||||
views. Archie uses a custom loader because the authoritative inputs are JSON;
|
||||
VitePress `createContentLoader` is reserved for Markdown content collections.
|
||||
|
||||
The final move from `docs-2/` to `docs/` occurs only after Archie content
|
||||
contains intentional Archie pages and the current architecture documents have an
|
||||
intentional destination. The staging name MUST NOT leak into public URLs.
|
||||
@@ -181,10 +196,12 @@ require github.com/samcharles93/archie-core v0.0.0-00010101000000-000000000000
|
||||
replace github.com/samcharles93/archie-core => ../
|
||||
```
|
||||
|
||||
Keep generator-only dependencies such as `invopop/jsonschema` and YAML in the
|
||||
nested tools module. They MUST NOT enter the root module.
|
||||
Keep generator-only dependencies such as `invopop/jsonschema` and any future
|
||||
protocol-schema serializer in the nested tools module. They MUST NOT enter the
|
||||
root module.
|
||||
|
||||
`docsgen` imports Archie-owned contracts and writes Archie reference artifacts.
|
||||
`docsgen` imports Archie-owned contracts and writes normalized Archie data and
|
||||
protocol artifacts.
|
||||
|
||||
### Step 2: establish authoritative registries
|
||||
|
||||
@@ -208,6 +225,10 @@ Where the migration has not yet created a final domain registry, the generator
|
||||
may use a narrow compatibility adapter over the current registry. That adapter
|
||||
has explicit deletion criteria.
|
||||
|
||||
The initial agent-execution and messaging schema set is such an adapter. It is
|
||||
deleted when those domains expose their production-owned documentation
|
||||
registries; adding another hardcoded type list to `docsgen` is prohibited.
|
||||
|
||||
### Step 3: generate AsyncAPI
|
||||
|
||||
Use Archie's messaging and worker wire registries as the authoritative inputs.
|
||||
@@ -232,15 +253,16 @@ The generator owns:
|
||||
The generated protocol artifact becomes:
|
||||
|
||||
```text
|
||||
docs-2/asyncapi/archie.yaml
|
||||
docs-2/public/schemas/archie.yaml
|
||||
```
|
||||
|
||||
The final owner of each wire registry is the domain or capability defining its
|
||||
meaning. `docsgen` renders the contract; it does not own the message semantics.
|
||||
|
||||
### Step 4: add Markdown page generation
|
||||
### Step 4: add generated documentation data
|
||||
|
||||
Add renderers for the missing reference categories one vertical slice at a time.
|
||||
Add extractors for the missing reference categories one vertical slice at a
|
||||
time.
|
||||
|
||||
Recommended implementation order:
|
||||
|
||||
@@ -253,29 +275,27 @@ Recommended implementation order:
|
||||
7. tools and capability contracts;
|
||||
8. worker and external wire contracts.
|
||||
|
||||
Each category renderer produces:
|
||||
Each category extractor contributes:
|
||||
|
||||
- a section index;
|
||||
- one stable page per published definition where useful;
|
||||
- field/type/default/validation tables;
|
||||
- source links;
|
||||
- stable IDs, owners, routes, and display ordering;
|
||||
- fields, types, defaults, and validation metadata;
|
||||
- source references;
|
||||
- version and deprecation information;
|
||||
- cross-links to related commands, events, policies, and contracts.
|
||||
- relationships to commands, events, policies, and contracts.
|
||||
|
||||
The first vertical slice proves the normalized model and templates. Later
|
||||
categories reuse them rather than introducing category-specific ad hoc
|
||||
generation.
|
||||
The first vertical slice proves the normalized model and deterministic JSON
|
||||
serialization. Later categories reuse it rather than introducing
|
||||
category-specific ad hoc output formats.
|
||||
|
||||
### Step 5: generate VitePress navigation
|
||||
### Step 5: render data with VitePress
|
||||
|
||||
Generate navigation data from `manifest.json`, not by manually duplicating every
|
||||
generated page in `.vitepress/config.mts`.
|
||||
Create typed data loaders, components, and page templates for the normalized
|
||||
data. The loaders watch `data/generated/*.json`, parse and validate the files,
|
||||
and return serializable data at build time.
|
||||
|
||||
Handwritten top-level navigation remains explicit. Generated reference sections
|
||||
are imported from `.vitepress/generated-sidebar.mts`.
|
||||
|
||||
The generated navigation file is deterministic and committed with the reference
|
||||
pages.
|
||||
Handwritten top-level navigation remains explicit. Reference navigation and
|
||||
routes derive from `catalog.json`; they are not emitted as generated TypeScript
|
||||
or duplicated manually in `.vitepress/config.mts`.
|
||||
|
||||
### Step 6: implement deterministic drift checking
|
||||
|
||||
@@ -283,7 +303,7 @@ pages.
|
||||
|
||||
1. generates all artifacts into a temporary directory;
|
||||
2. normalizes line endings and file modes;
|
||||
3. compares the complete expected tree with committed outputs;
|
||||
3. compares the complete expected data and schema trees with committed outputs;
|
||||
4. reports missing, changed, and obsolete files;
|
||||
5. identifies the authoritative definition associated with each mismatch;
|
||||
6. exits non-zero without modifying the working tree.
|
||||
@@ -415,7 +435,7 @@ CI:
|
||||
1. runs `task docs:check` without modifying committed output;
|
||||
2. builds the static site;
|
||||
3. publishes only from the approved branch or release;
|
||||
4. never treats generated reference as handwritten source.
|
||||
4. never treats generated data as handwritten source.
|
||||
|
||||
A commit MUST NOT be created while generated documentation is stale.
|
||||
|
||||
@@ -439,7 +459,7 @@ Site validation covers:
|
||||
- frozen dependency installation;
|
||||
- VitePress production build;
|
||||
- dead internal links;
|
||||
- generated navigation imports;
|
||||
- generated-data loader imports;
|
||||
- expected output routes;
|
||||
- absence of unrelated product names and URLs;
|
||||
- absence of committed build artifacts.
|
||||
@@ -453,8 +473,9 @@ The documentation migration is complete when:
|
||||
- `tools` belongs to Archie and builds against the working tree;
|
||||
- `docsgen` consumes Archie-owned registries and types;
|
||||
- AsyncAPI output describes Archie;
|
||||
- required reference categories are generated as committed Markdown;
|
||||
- generated navigation and manifest match generated pages;
|
||||
- required reference categories are generated as committed deterministic data;
|
||||
- `catalog.json` matches the generated definitions and rendered routes;
|
||||
- VitePress components and templates render the generated data;
|
||||
- two consecutive generations are byte-identical;
|
||||
- `docsgen check` detects changed, missing, and obsolete artifacts;
|
||||
- VitePress contains only intentional Archie content;
|
||||
|
||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -185,9 +185,10 @@ type Agent struct {
|
||||
|
||||
// Forge configures the code forge integration.
|
||||
type Forge struct {
|
||||
Type string `toml:"type" yaml:"type"`
|
||||
Host string `toml:"host" yaml:"host"`
|
||||
Token secret.SecretRef `toml:"token" yaml:"token"`
|
||||
Type string `toml:"type" yaml:"type"`
|
||||
Host string `toml:"host" yaml:"host"`
|
||||
Token secret.SecretRef `toml:"token" yaml:"token"`
|
||||
TokenEnv string `toml:"token_env" yaml:"token_env"`
|
||||
}
|
||||
|
||||
// Dispatch configures how archied discovers work and reflects task state
|
||||
@@ -578,8 +579,6 @@ func finalize(cfg Config) (Config, error) {
|
||||
if cfg.Forge.Token.Engine == "" && cfg.Forge.Token.Key == "" {
|
||||
if cfg.Forge.TokenEnv != "" {
|
||||
cfg.Forge.Token = secret.SecretRef{Engine: "env", Key: cfg.Forge.TokenEnv}
|
||||
} else {
|
||||
cfg.Forge.Token = secret.SecretRef{Engine: "env", Key: "ARCHIE_GITHUB_TOKEN"}
|
||||
}
|
||||
}
|
||||
if cfg.Agent.Mode == "" {
|
||||
|
||||
+32
-14
@@ -13,16 +13,16 @@ import (
|
||||
"strings"
|
||||
|
||||
"github.com/invopop/jsonschema"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/agentexec"
|
||||
"github.com/samcharles93/archie-core/internal/gateway"
|
||||
"gopkg.in/yaml.v3"
|
||||
)
|
||||
|
||||
func main() {
|
||||
repoRoot := flag.String("repo-root", "..", "path to the Archie repository root")
|
||||
out := flag.String(
|
||||
"out",
|
||||
"docs-2/reference/generated/agent-contracts.yaml",
|
||||
"docs-2/data/generated/contracts.json",
|
||||
"output path relative to the repository root",
|
||||
)
|
||||
flag.Parse()
|
||||
@@ -47,11 +47,7 @@ func run(repoRoot, outPath string) error {
|
||||
}
|
||||
|
||||
schemas := map[string]any{}
|
||||
types := map[string]reflect.Type{
|
||||
"AgentExecutionRequest": reflect.TypeFor[agentexec.Request](),
|
||||
"AgentExecutionResult": reflect.TypeFor[agentexec.Result](),
|
||||
"MessageEvent": reflect.TypeFor[gateway.MessageEvent](),
|
||||
}
|
||||
types := currentContractTypes()
|
||||
names := make([]string, 0, len(types))
|
||||
for name := range types {
|
||||
names = append(names, name)
|
||||
@@ -64,10 +60,17 @@ func run(repoRoot, outPath string) error {
|
||||
}
|
||||
rewriteDefRefs(schemas)
|
||||
|
||||
body, err := yaml.Marshal(map[string]any{"schemas": schemas})
|
||||
body, err := json.MarshalIndent(struct {
|
||||
GeneratedBy string `json:"generatedBy"`
|
||||
Schemas map[string]any `json:"schemas"`
|
||||
}{
|
||||
GeneratedBy: "tools/docsgen",
|
||||
Schemas: schemas,
|
||||
}, "", " ")
|
||||
if err != nil {
|
||||
return fmt.Errorf("marshal schemas: %w", err)
|
||||
return fmt.Errorf("marshal documentation data: %w", err)
|
||||
}
|
||||
body = append(body, '\n')
|
||||
|
||||
destination := outPath
|
||||
if !filepath.IsAbs(destination) {
|
||||
@@ -76,8 +79,7 @@ func run(repoRoot, outPath string) error {
|
||||
if err := os.MkdirAll(filepath.Dir(destination), 0o755); err != nil {
|
||||
return fmt.Errorf("create output directory: %w", err)
|
||||
}
|
||||
header := []byte("# Code generated by tools/docsgen. DO NOT EDIT.\n")
|
||||
if err := os.WriteFile(destination, append(header, body...), 0o644); err != nil {
|
||||
if err := os.WriteFile(destination, body, 0o644); err != nil {
|
||||
return fmt.Errorf("write %s: %w", destination, err)
|
||||
}
|
||||
|
||||
@@ -85,6 +87,18 @@ func run(repoRoot, outPath string) error {
|
||||
return nil
|
||||
}
|
||||
|
||||
// currentContractTypes adapts the pre-domain-registry contract set during the
|
||||
// architecture migration. Delete it when agent execution and messaging expose
|
||||
// domain-owned documentation registries; docsgen must then consume those
|
||||
// registries directly.
|
||||
func currentContractTypes() map[string]reflect.Type {
|
||||
return map[string]reflect.Type{
|
||||
"AgentExecutionRequest": reflect.TypeFor[agentexec.Request](),
|
||||
"AgentExecutionResult": reflect.TypeFor[agentexec.Result](),
|
||||
"MessageEvent": reflect.TypeFor[gateway.MessageEvent](),
|
||||
}
|
||||
}
|
||||
|
||||
func loadGoComments(reflector *jsonschema.Reflector, repoRoot string) error {
|
||||
const modulePath = "github.com/samcharles93/archie-core"
|
||||
if err := reflector.AddGoComments("", filepath.Join(repoRoot, "internal")); err != nil {
|
||||
@@ -108,7 +122,7 @@ func collectSchema(
|
||||
t reflect.Type,
|
||||
) error {
|
||||
if _, exists := schemas[name]; exists {
|
||||
return nil
|
||||
return fmt.Errorf("duplicate published schema name %q", name)
|
||||
}
|
||||
raw, err := json.Marshal(reflector.ReflectFromType(t))
|
||||
if err != nil {
|
||||
@@ -124,9 +138,13 @@ func collectSchema(
|
||||
delete(tree, "$id")
|
||||
schemas[name] = tree
|
||||
for defName, defSchema := range defs {
|
||||
if _, exists := schemas[defName]; !exists {
|
||||
schemas[defName] = defSchema
|
||||
if existing, exists := schemas[defName]; exists {
|
||||
if !reflect.DeepEqual(existing, defSchema) {
|
||||
return fmt.Errorf("conflicting schema definition %q", defName)
|
||||
}
|
||||
continue
|
||||
}
|
||||
schemas[defName] = defSchema
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
@@ -1,11 +1,75 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"reflect"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/invopop/jsonschema"
|
||||
)
|
||||
|
||||
type contractWithConflictingDefinition struct {
|
||||
Value conflictingDefinition `json:"value"`
|
||||
}
|
||||
|
||||
type conflictingDefinition struct {
|
||||
Value string `json:"value"`
|
||||
}
|
||||
|
||||
func TestRunWritesDeterministicContractData(t *testing.T) {
|
||||
repoRoot := filepath.Clean("../..")
|
||||
outputDir := t.TempDir()
|
||||
outputs := []string{
|
||||
filepath.Join(outputDir, "first.json"),
|
||||
filepath.Join(outputDir, "second.json"),
|
||||
}
|
||||
|
||||
for _, output := range outputs {
|
||||
if err := run(repoRoot, output); err != nil {
|
||||
t.Fatalf("run(%q) error = %v", output, err)
|
||||
}
|
||||
}
|
||||
|
||||
first, err := os.ReadFile(outputs[0])
|
||||
if err != nil {
|
||||
t.Fatalf("read first output: %v", err)
|
||||
}
|
||||
second, err := os.ReadFile(outputs[1])
|
||||
if err != nil {
|
||||
t.Fatalf("read second output: %v", err)
|
||||
}
|
||||
if !bytes.Equal(first, second) {
|
||||
t.Fatal("repeated generation produced different bytes")
|
||||
}
|
||||
|
||||
var data struct {
|
||||
GeneratedBy string `json:"generatedBy"`
|
||||
Schemas map[string]json.RawMessage `json:"schemas"`
|
||||
}
|
||||
if err := json.Unmarshal(first, &data); err != nil {
|
||||
t.Fatalf("decode generated data: %v", err)
|
||||
}
|
||||
if data.GeneratedBy != "tools/docsgen" {
|
||||
t.Fatalf("generatedBy = %q, want %q", data.GeneratedBy, "tools/docsgen")
|
||||
}
|
||||
for _, name := range []string{
|
||||
"AgentExecutionRequest",
|
||||
"AgentExecutionResult",
|
||||
"MessageEvent",
|
||||
} {
|
||||
if _, ok := data.Schemas[name]; !ok {
|
||||
t.Errorf("schemas[%q] is missing", name)
|
||||
}
|
||||
}
|
||||
for name, schema := range data.Schemas {
|
||||
assertSchemaRefsResolve(t, name, schema, data.Schemas)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunHonoursAbsoluteOutputPath(t *testing.T) {
|
||||
repoRoot := filepath.Clean("../..")
|
||||
outputDir := t.TempDir()
|
||||
@@ -31,3 +95,154 @@ func TestRunHonoursAbsoluteOutputPath(t *testing.T) {
|
||||
t.Fatalf("working directory = %q, want %q", currentDir, originalDir)
|
||||
}
|
||||
}
|
||||
|
||||
func TestCollectSchemaRejectsDuplicatePublishedName(t *testing.T) {
|
||||
reflector := &jsonschema.Reflector{ExpandedStruct: true}
|
||||
schemas := map[string]any{}
|
||||
const name = "PublishedContract"
|
||||
|
||||
if err := collectSchema(reflector, schemas, name, reflect.TypeFor[struct {
|
||||
First string `json:"first"`
|
||||
}]()); err != nil {
|
||||
t.Fatalf("collect first schema: %v", err)
|
||||
}
|
||||
err := collectSchema(reflector, schemas, name, reflect.TypeFor[struct {
|
||||
Second int `json:"second"`
|
||||
}]())
|
||||
if err == nil {
|
||||
t.Fatal("collect duplicate schema returned nil error")
|
||||
}
|
||||
}
|
||||
|
||||
func TestCollectSchemaRejectsConflictingDefinition(t *testing.T) {
|
||||
reflector := &jsonschema.Reflector{ExpandedStruct: true}
|
||||
schemas := map[string]any{
|
||||
"conflictingDefinition": map[string]any{"type": "integer"},
|
||||
}
|
||||
|
||||
err := collectSchema(
|
||||
reflector,
|
||||
schemas,
|
||||
"PublishedContract",
|
||||
reflect.TypeFor[contractWithConflictingDefinition](),
|
||||
)
|
||||
if err == nil {
|
||||
t.Fatal("collect conflicting definition returned nil error")
|
||||
}
|
||||
if !strings.Contains(err.Error(), `conflicting schema definition "conflictingDefinition"`) {
|
||||
t.Fatalf("collect conflicting definition error = %q", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunReportsFilesystemAndSourceErrors(t *testing.T) {
|
||||
repoRoot := filepath.Clean("../..")
|
||||
blocker := filepath.Join(t.TempDir(), "file")
|
||||
if err := os.WriteFile(blocker, []byte("occupied"), 0o600); err != nil {
|
||||
t.Fatalf("create blocker: %v", err)
|
||||
}
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
root string
|
||||
output string
|
||||
contains string
|
||||
}{
|
||||
{
|
||||
name: "missing source tree",
|
||||
root: t.TempDir(),
|
||||
output: filepath.Join(t.TempDir(), "contracts.json"),
|
||||
contains: "load Go comments",
|
||||
},
|
||||
{
|
||||
name: "output parent is a file",
|
||||
root: repoRoot,
|
||||
output: filepath.Join(blocker, "contracts.json"),
|
||||
contains: "create output directory",
|
||||
},
|
||||
{
|
||||
name: "output is a directory",
|
||||
root: repoRoot,
|
||||
output: t.TempDir(),
|
||||
contains: "write ",
|
||||
},
|
||||
}
|
||||
|
||||
for _, test := range tests {
|
||||
t.Run(test.name, func(t *testing.T) {
|
||||
err := run(test.root, test.output)
|
||||
if err == nil {
|
||||
t.Fatal("run() returned nil error")
|
||||
}
|
||||
if !bytes.Contains([]byte(err.Error()), []byte(test.contains)) {
|
||||
t.Fatalf("run() error = %q, want substring %q", err, test.contains)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestRewriteRef(t *testing.T) {
|
||||
tests := map[string]string{
|
||||
"definition": "#/schemas/Contract",
|
||||
"external": "https://example.com/schema.json",
|
||||
"empty name": "#/$defs/",
|
||||
}
|
||||
|
||||
for name, want := range tests {
|
||||
t.Run(name, func(t *testing.T) {
|
||||
input := want
|
||||
if name == "definition" {
|
||||
input = "#/$defs/Contract"
|
||||
}
|
||||
if got := rewriteRef(input); got != want {
|
||||
t.Fatalf("rewriteRef(%q) = %q, want %q", input, got, want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func assertSchemaRefsResolve(
|
||||
t *testing.T,
|
||||
name string,
|
||||
raw json.RawMessage,
|
||||
schemas map[string]json.RawMessage,
|
||||
) {
|
||||
t.Helper()
|
||||
|
||||
var value any
|
||||
if err := json.Unmarshal(raw, &value); err != nil {
|
||||
t.Fatalf("decode schema %q: %v", name, err)
|
||||
}
|
||||
walkJSON(value, func(ref string) {
|
||||
const prefix = "#/schemas/"
|
||||
if !strings.HasPrefix(ref, "#") {
|
||||
return
|
||||
}
|
||||
if !strings.HasPrefix(ref, prefix) {
|
||||
t.Errorf("schema %q contains unresolved local reference %q", name, ref)
|
||||
return
|
||||
}
|
||||
target := ref[len(prefix):]
|
||||
if _, ok := schemas[target]; !ok {
|
||||
t.Errorf("schema %q references missing schema %q", name, target)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
func walkJSON(value any, visitRef func(string)) {
|
||||
switch node := value.(type) {
|
||||
case map[string]any:
|
||||
for key, child := range node {
|
||||
if key == "$ref" {
|
||||
if ref, ok := child.(string); ok {
|
||||
visitRef(ref)
|
||||
}
|
||||
continue
|
||||
}
|
||||
walkJSON(child, visitRef)
|
||||
}
|
||||
case []any:
|
||||
for _, child := range node {
|
||||
walkJSON(child, visitRef)
|
||||
}
|
||||
}
|
||||
}
|
||||
+1
-1
@@ -5,7 +5,6 @@ go 1.26.4
|
||||
require (
|
||||
github.com/invopop/jsonschema v0.14.0
|
||||
github.com/samcharles93/archie-core v0.0.0-00010101000000-000000000000
|
||||
gopkg.in/yaml.v3 v3.0.1
|
||||
)
|
||||
|
||||
require (
|
||||
@@ -25,6 +24,7 @@ require (
|
||||
go.yaml.in/yaml/v4 v4.0.0-rc.2 // indirect
|
||||
golang.org/x/crypto v0.53.0 // indirect
|
||||
golang.org/x/sys v0.46.0 // indirect
|
||||
gopkg.in/yaml.v3 v3.0.1 // indirect
|
||||
)
|
||||
|
||||
replace github.com/samcharles93/archie-core => ../
|
||||
Reference in new issue
Block a user