docs(skills): re-verify every .agents skill against the current tree
All ten `archie-*` skills carried claims that no longer matched the
checkout. Re-verified each against code, git history, and the shipped
configuration, then corrected the drift.
Structural changes the skills had not caught up with:
- Composition root moved: `cmd/archied/main.go` is a ~30-line dispatcher
into `internal/app/archied.Run()` with wiring in `bootstrap.go`. The
skills still described `cmd/archied` as the wiring site, which also
silently zeroed the diagnostics delivery snapshot.
- Config decoding moved out of `internal/config` into
`internal/infrastructure/configuration`. `config.Load` / `config.LoadDir`
no longer exist; the loader is `configuration.New` + `Loader.Resolve`.
- Task contract moved to `internal/domain/storecontract`, with
`internal/store/interface.go` holding aliases only. The task type is
`internal/domain/workflow/task.Task`.
- `internal/workflow` became `internal/domain/workflow`; `internal/storerpc`
became gRPC `internal/infrastructure/staterpc`; `internal/policy` does not
exist.
- `Store.Transition` now guards on `from` and writes status plus history in
one transaction. Three skills still described the old non-atomic behavior
as current and open.
- `internal/domain/{messaging,workflow,workintake}`, `internal/eventbus`,
`internal/app`, and `internal/infrastructure` now exist.
`internal/domain/{agent,identity}` and `internal/policy` remain target-only.
Tooling and environment facts:
- Go 1.27.0 (root and tools modules), golangci-lint 2.13.2, staticcheck
2026.2.1; snapshot dates and HEAD moved to 2026-09-18 / 2e1e1549.
- Re-ran the bundled diagnostics and re-baselined its snapshot table.
Confirmed 78.6% store coverage, a clean race run, and zero dupl findings.
- Corrected the claim that no `.dockerignore` exists; it does.
- Replaced skill script paths that pointed at the untracked `.claude/skills`
symlink with the canonical tracked `.agents/skills` location.
- Fixed the delivery-snapshot comment's wrong commit hash for the Gitea
workflow removal (dd9bddc2, not e539048).
Findings the verification closed:
- The VitePress site and `.github/workflows/docs.yml` were removed
(84b32694); the Gitea workflow was dropped (dd9bddc2).
- The changelog `vX.Y.Z`-vs-`X.Y.Z` contradiction is settled, not open: both
changelogs and the CI gate agree on `## [<version>]`.
- Tracked `docs/node_modules` and the skill-script test regression are
settled, not current.
- The six unmerged `origin/fix/*` and `origin/feat/*` candidate branches no
longer exist.
Also regenerates `docs/data/generated/contracts.json`, which the
verification found stale since 4b340d2b: docsgen emits 11 schemas now, and
`MediaAttachment.raw` plus an `AgentExecutionResult.required` field were
missing. `cmp` passes after regeneration.
Verified with `task check` (green).
This commit is contained in:
13 files changed
+251
-201
No files matched your search
@@ -22,14 +22,16 @@ owner and one production path for each behavior.
|
||||
|
||||
| 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 |
|
||||
| **CURRENT** | Behavior present in live code and production composition as of 2026-09-18. | Code, tests, and `internal/app/archied` wiring (`cmd/archied/main.go` is a thin dispatcher) |
|
||||
| **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/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. `internal/domain/` does not exist in the
|
||||
> CURRENT tree as of 2026-07-28.
|
||||
> used from a production entry point. As of 2026-09-18 `internal/domain/`,
|
||||
> `internal/eventbus/`, `internal/infrastructure/`, and `internal/app/` exist;
|
||||
> `internal/policy/` does not, and `internal/domain/{agent,identity}` remain
|
||||
> APPROVED TARGET only.
|
||||
|
||||
Resolve apparent disagreement in this order:
|
||||
|
||||
@@ -43,24 +45,31 @@ Resolve apparent disagreement in this order:
|
||||
Route to `archie-domain-reference` for glossary and
|
||||
`archie-config-and-flags` for config enumeration.
|
||||
|
||||
Two skills this document routes to are parked outside this checkout, under
|
||||
`/work/apps/archie-skills-parked/`: `archie-technical-accountability` and
|
||||
`archie-architecture-planning-campaign`. If your session has not loaded them,
|
||||
treat each routing target as a manual escalation step rather than a live skill.
|
||||
Also: `cmd/archied/main.go` is a thin dispatcher; the wiring lives in
|
||||
`internal/app/archied/`.
|
||||
|
||||
## Know the CURRENT system
|
||||
|
||||
Do not simplify these facts into the target model:
|
||||
|
||||
| Concern | CURRENT runtime truth on 2026-07-28 | Evidence |
|
||||
| Concern | CURRENT runtime truth on 2026-09-18 | Evidence |
|
||||
| --- | --- | --- |
|
||||
| Composition | `cmd/archied/main.go` performs substantial construction and wiring. | `cmd/archied/main.go`; current `internal/*` tree |
|
||||
| Durable work | `store.Task` combines forge/chat source data, workflow position, output, retry, identity, and PR state. | `internal/store/store.go` |
|
||||
| Workflow | `internal/workflow` routes a `store.Task` into a `map[string]Workflow`, mutates a broad `TaskContext` through sequential stages. | `internal/workflow/workflow.go` |
|
||||
| Composition | `cmd/archied/main.go` dispatches to `internal/app/archied.Run()`, which performs construction and wiring in `bootstrap.go`. | `cmd/archied/main.go`; `internal/app/archied/` |
|
||||
| Durable work | `task.Task` combines forge/chat source data, workflow position, output, retry, identity, and PR state. | `internal/domain/workflow/task/task.go`; `internal/domain/storecontract/storecontract.go` |
|
||||
| Workflow | `internal/domain/workflow` routes a `task.Task` into a `map[string]Workflow`, mutates a broad `TaskContext` through sequential stages. | `internal/domain/workflow/workflow.go` |
|
||||
| Agent-stage boundary | Versioned `agentexec.Request`/`Result` carries one autonomous stage; validation correlates task, attempt, and stage. | `internal/agentexec/protocol.go` |
|
||||
| Container handoff | `internal/taskrun` carries entire task plus `config.Repo` and `config.TaskConfig`; `internal/app/agentworker` owns routing and sequencing while its NATS adapter owns wire mechanics. | `internal/taskrun/taskrun.go`; `internal/app/agentworker/`; `internal/infrastructure/agenttransport/nats/` |
|
||||
| Git ownership | Daemon-owned worktree operations clone, commit, push, diff, and clean up. | `internal/worktree/`; `internal/workflow/steps.go`; `ARCHITECTURE.md` |
|
||||
| Enforcement | Gates, read-only/protected paths, TDD inverted test gates, and diff caps are represented outside prompt prose. | `internal/agentexec/inprocess.go`; `internal/workflow/{agent,tdd,steps}.go` |
|
||||
| Configuration | `internal/config.Config`, `IdentityConfig`, `Repo`, and task snapshots mix input decoding with runtime concerns. | `internal/config/config.go` |
|
||||
| Identity | Configured names and bot usernames act as process-local identity keys. There is no durable Identity domain. | `internal/daemon/daemon.go`; `internal/store/store.go`; `internal/gateway/session.go` |
|
||||
| Git ownership | Daemon-owned worktree operations clone, commit, push, diff, and clean up. | `internal/worktree/`; `internal/domain/workflow/steps.go`; `ARCHITECTURE.md` |
|
||||
| Enforcement | Gates, read-only/protected paths, TDD inverted test gates, and diff caps are represented outside prompt prose. | `internal/gate/`; `internal/domain/workflow/{agent,tdd,steps}.go` |
|
||||
| Configuration | `internal/config.Config`, `IdentityConfig`, `Repo`, and task snapshots mix input decoding with runtime concerns. Decoding itself lives in `internal/infrastructure/configuration`. | `internal/config/config.go`; `internal/infrastructure/configuration/` |
|
||||
| Identity | Configured names and bot usernames act as process-local identity keys. There is no durable Identity domain. | `internal/daemon/daemon.go`; `internal/domain/storecontract/storecontract.go`; `internal/gateway/session.go` |
|
||||
| Messaging | `internal/gateway` contains both the `Message` struct flow and richer `MessageEvent`; channel routing and task control are mixed with conversational behavior. | `internal/gateway/{gateway,messageevent,tasks}.go`; `internal/channels/` |
|
||||
| Plugins | `plugin.Plugin` exposes only `Name` and `Version`; current loading interprets operator-installed Go files with Yaegi. | `internal/plugin/plugin.go` |
|
||||
| Processes | Agent modes include in-process, subprocess, and NATS. Optional containers add a distinct boundary with known gaps. | `internal/config/config.go`; `cmd/archied/main.go`; `ARCHITECTURE.md` |
|
||||
| Processes | Agent modes include in-process, subprocess, and NATS. Optional containers add a distinct boundary with known gaps. | `internal/config/config.go`; `internal/app/archied/`; `ARCHITECTURE.md` |
|
||||
|
||||
### Interpret the current lifecycle honestly
|
||||
|
||||
@@ -73,24 +82,26 @@ 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.
|
||||
`internal/domain/workflow/task/task.go`, `internal/daemon/daemon.go`, and
|
||||
`internal/domain/workflow/workflow.go` before changing a transition.
|
||||
|
||||
Current `Store.Transition(ctx, taskID, from, to, detail)` does not include
|
||||
`from` in the update predicate; updates task state and inserts transition
|
||||
history in separate statements; can accept an illegal/stale transition or leave
|
||||
state and history inconsistent; is called from paths that sometimes discard its
|
||||
error. Treat atomic state plus event/history persistence as an OPEN migration
|
||||
design.
|
||||
`Store.Transition(ctx, taskID, from, to, detail)` now guards on `from`
|
||||
(`WHERE id=? AND status=?`, returning `store.ErrStaleTransition` on mismatch)
|
||||
and runs the status update plus the transition-history insert in one
|
||||
transaction (`internal/store/store.go`). The sentinel crosses the State Store
|
||||
gRPC boundary via `mapError`/`unmapError` in
|
||||
`internal/infrastructure/staterpc/values.go`; its canonical message string is
|
||||
part of the wire contract. Earlier non-atomic behavior is the settled fix,
|
||||
not an open design.
|
||||
|
||||
## Preserve the load-bearing invariants
|
||||
|
||||
| Invariant | Required action | Status and source |
|
||||
| --- | --- | --- |
|
||||
| The model never runs git | Keep clone, branch, commit, push, diff, and cleanup in deterministic workspace/worktree steps. | CURRENT: `ARCHITECTURE.md`; `internal/worktree/` |
|
||||
| Deterministic constraints outrank prompts | Enforce gates, protected paths, read-only stages, test protection, and change caps outside model instructions. | CURRENT: `ARCHITECTURE.md`; `internal/agentexec/inprocess.go`; `internal/workflow/` |
|
||||
| Deterministic constraints outrank prompts | Enforce gates, protected paths, read-only stages, test protection, and change caps outside model instructions. | CURRENT: `ARCHITECTURE.md`; `internal/gate/`; `internal/domain/workflow/` |
|
||||
| Agent execution is a data boundary | Send bounded, versioned input; validate correlated output before applying it. | CURRENT foundation: `internal/agentexec/protocol.go`; `ARCHITECTURE.md` |
|
||||
| Every workflow ends explicitly | Preserve terminal outcome or visible park. Preserve crash recovery of interrupted `running` work. | CURRENT: `internal/workflow/workflow.go`; `internal/store/store.go` |
|
||||
| Every workflow ends explicitly | Preserve terminal outcome or visible park. Preserve crash recovery of interrupted `running` work. | CURRENT: `internal/domain/workflow/workflow.go`; `internal/store/store.go` |
|
||||
| Generic plugins stay metadata-only | Keep `plugin.Plugin` at `Name()`/`Version()`. Behavior on typed capability interface with owning `Registry`/`Manager`. | CURRENT-enforced rule: `internal/plugin/architecture_test.go` |
|
||||
| Capability engines own lifecycle | Give resource-owning engines explicit start/health/stop semantics and failure isolation. | APPROVED rule: `ARCHITECTURE.md#plugin-engine-rule-strict` |
|
||||
| Trust is explicit | Treat trusted operator-installed in-process code, repository code, out-of-process integrations, and container-isolated code as different trust classes. | APPROVED rule: `ARCHITECTURE.md#plugin-engine-rule-strict` |
|
||||
@@ -190,7 +201,7 @@ Source: `docs/architecture/configuration.md`.
|
||||
| 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 consuming domain. |
|
||||
| Shared policy evaluation/evidence mechanics | No current package. `internal/policy` was the planned location; as of 2026-09-18 policy lives inside playbook bindings (`playbooks/`, `internal/domain/eda/playbook`) and `internal/gate/`. | Keep policy vocabulary, evaluators, and consequences with consuming domain. |
|
||||
| NATS, SQLite, 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. |
|
||||
| Deploy assembly | `deployments/<assembly>` | Do not move application behavior into deployment files. |
|
||||
@@ -198,17 +209,17 @@ Source: `docs/architecture/configuration.md`.
|
||||
|
||||
## Confront known weak points
|
||||
|
||||
| Weak point on 2026-07-28 | Required response |
|
||||
| Weak point on 2026-09-18 | Required response |
|
||||
| --- | --- |
|
||||
| `TaskContext` is a mutable service bag with config, services, policy, scratch state. | Design narrow step inputs and staged removal. |
|
||||
| Workflow lifecycle split across store, daemon, workflow, gateway, worker. | Trace every writer and reader before changing status. |
|
||||
| State changes and transition history non-atomic; `from` is advisory. | Treat as architecture migration, not local fix. |
|
||||
| State changes and transition history were non-atomic and `from` was advisory — **settled** in `internal/store`: `Transition` guards on `status=?` and writes status plus history in one transaction. | Keep every status writer behind `Transition`; do not reintroduce a raw `UPDATE tasks SET status`. |
|
||||
| In-process and container paths put orchestration on different sides of process boundary. | Decide which path survives before extending both. |
|
||||
| Identity uses strings; task uniqueness/NATS dedup omit identity. | Don't promise multi-identity ownership until canonical IDs migrate. |
|
||||
| Container RPC uses root forge/worktree, not task owner's identity. | Known trust/correctness defect — not identity-isolated. |
|
||||
| Missing `task.json` makes `archie-agent` join shared queue. | Fail closed before treating as isolated. |
|
||||
| Subprocess uses daemon user and host access. | Not a security boundary. |
|
||||
| Gateway duplicates lifecycle strings, competing message contracts. | No third contract or direct lifecycle mutation path. |
|
||||
| Gateway formerly duplicated lifecycle strings, competing message contracts. | No third contract or direct lifecycle mutation path; status constants live in `internal/domain/workflow`. |
|
||||
| Global config and `IdentityConfig` combine unrelated owners. | Don't rename global structure or add `Extra` map. |
|
||||
| Memory has fixed scope requirements but OPEN final placement/migration. | Preserve scope isolation; focused design before moving. |
|
||||
| Tests can make unused/duplicate code appear legitimate. | Prove production reachability from composition. |
|
||||
@@ -231,4 +242,5 @@ 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`.
|
||||
Trace from `cmd/archied/main.go` into `internal/app/archied.Run()`; the wiring
|
||||
itself is in `internal/app/archied/bootstrap.go`.
|
||||
@@ -9,7 +9,7 @@ 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 are snapshots from **2026-07-28**.
|
||||
All volatile observations are snapshots from **2026-09-18** (HEAD `2e1e1549`).
|
||||
|
||||
## Name the surfaces
|
||||
|
||||
@@ -42,17 +42,17 @@ git --version; gpg --version
|
||||
```
|
||||
|
||||
Classify a missing command as an environment prerequisite. Bootstrap (verified
|
||||
2026-07-28): Go ≥ 1.26.3, Task ≥ 3.x, gofumpt (unpinned), golangci-lint v2
|
||||
2026-09-18): Go ≥ 1.27.0, Task ≥ 3.x, gofumpt (unpinned), golangci-lint v2
|
||||
(unpinned), Node 24.x for the `ui/` frontend.
|
||||
|
||||
| Surface | Repository declaration | Installed snapshot | Interpretation |
|
||||
|---|---|---|---|
|
||||
| Runtime Go | `go 1.26.3` in `go.mod` | Go 1.26.5, linux/amd64 | Requires at least declared Go level. |
|
||||
| Tools Go | `go 1.26.4` in `tools/go.mod` | Same Go 1.26.5 binary | Toolchain must satisfy both modules. |
|
||||
| Runtime Go | `go 1.27.0` in `go.mod` | Go 1.27.0, linux/amd64 | Requires at least declared Go level. |
|
||||
| Tools Go | `go 1.27.0` in `tools/go.mod` | Same Go 1.27.0 binary | Toolchain must satisfy both modules. |
|
||||
| Task | Taskfile schema `version: "3"` | Task 3.48.0 | Installed version is environment fact. |
|
||||
| gofumpt | Used by `task fmt`; `@latest` install | v0.7.0 | Unpinned. |
|
||||
| golangci-lint | v2 config in `.golangci.yml`; `@latest` install | 2.12.2 | Use v2 CLI; exact release unpinned. |
|
||||
| Node | `ui/` frontend build | 24.18.0 | No `engines`/`packageManager` field. Docs need no Node. |
|
||||
| gofumpt | Used by `task fmt`; `@latest` install | v0.7.0 (built with go1.26.5) | Unpinned. |
|
||||
| golangci-lint | v2 config in `.golangci.yml`; `@latest` install | 2.13.2 | Use v2 CLI; exact release unpinned. |
|
||||
| Node | `ui/` frontend build | 24.18.1 / npm 11.8.0 | No `engines`/`packageManager` field. Docs need no Node. |
|
||||
| Containers | Compose commands in `Taskfile.yml` | Podman-backed, unusable in this sandbox | Verify CLI, Compose plugin, daemon/socket separately. |
|
||||
|
||||
## Prepare writable caches in a restricted sandbox
|
||||
@@ -147,8 +147,9 @@ go -C tools run -mod=readonly ./docsgen --repo-root .. --out /tmp/archie-core-co
|
||||
cmp --silent docs/data/generated/contracts.json /tmp/archie-core-contracts.json
|
||||
```
|
||||
|
||||
2026-07-28 run wrote 10 schemas; comparison passed. Planned `docsgen all` and
|
||||
`docsgen check` do **not** exist yet.
|
||||
2026-09-18 run wrote 11 schemas. The committed output was stale since
|
||||
`4b340d2b` and was regenerated the same day; `cmp` now passes. Planned
|
||||
`docsgen all` and `docsgen check` do **not** exist yet.
|
||||
|
||||
## Documentation needs no build
|
||||
|
||||
@@ -172,9 +173,12 @@ rg -n '^(FROM|[[:space:]]*image:)|@latest|:latest|setup_24.x' \
|
||||
Dockerfile Dockerfile.archied docker-compose.yml
|
||||
```
|
||||
|
||||
No `.dockerignore` exists. Both Dockerfiles run `COPY . .`. Floating inputs: Go
|
||||
builder tags omit patch/digest; Ubuntu base images omit digests; agent installs
|
||||
multiple `@latest` Go tools; Node from moving `setup_24.x` channel.
|
||||
`.dockerignore` exists (421 bytes) and excludes `.git`, `.task`, `.claude`,
|
||||
`.codex`, `.crew`, `.agents`, `.references`, `bin/`, `dist/`, `docs/`,
|
||||
`node_modules/`, root-built `archied`/`archie-agent`, and local config. Both
|
||||
Dockerfiles still run `COPY . .` on top of it. Floating inputs: Go builder tags
|
||||
omit patch/digest; Ubuntu base images omit digests; agent installs multiple
|
||||
`@latest` Go tools; Node from moving `setup_24.x` channel.
|
||||
|
||||
`task docker-build` needs registry/network and functioning Compose.
|
||||
`task docker-up` starts the Compose-managed NATS service and binds ports
|
||||
@@ -207,10 +211,10 @@ env GIT_CONFIG_GLOBAL=/dev/null go test ./internal/worktree/... ./internal/workt
|
||||
| Focused Go behavior | `go test ./pkg/... -run '^TestName$' -count=1 -v` | Use first. |
|
||||
| Root unit/integration suite | `go test ./... -count=1` | Restricted sandbox fails listener-dependent packages. |
|
||||
| Root race suite | `go test -race ./... -count=1` | Not run by `task check`. |
|
||||
| Vet | `go vet ./...` | Passed on 2026-07-28. |
|
||||
| Lint | `golangci-lint run ./...` | Failed with 54 findings on 2026-07-28. |
|
||||
| Build | `go build -o /tmp/... ./cmd/archied` and `cmd/archie-agent` | Both passed on 2026-07-28. |
|
||||
| Tools tests | `go -C tools test -mod=readonly ./... -count=1` | Passed on 2026-07-28. |
|
||||
| Generated contract parity | Temp docsgen output + `cmp --silent` | Passed for 10 schemas. |
|
||||
| Vet | `go vet ./...` | Passed on 2026-09-18. |
|
||||
| Lint | `golangci-lint run ./...` | Not re-run on 2026-09-18; a focused `--enable-only=dupl ./internal/...` run reported 0 issues. Re-run before quoting a total. |
|
||||
| Build | `go build -o /tmp/... ./cmd/archied` and `cmd/archie-agent` | Both passed on 2026-09-18. |
|
||||
| Tools tests | `go -C tools test -mod=readonly ./... -count=1` | Passed on 2026-09-18. |
|
||||
| Generated contract parity | Temp docsgen output + `cmp --silent` | Passed for 11 schemas on 2026-09-18, after regenerating a file stale since `4b340d2b`. |
|
||||
| Container build | `task docker-build` | Not verified in restricted environment. |
|
||||
| Repository gate | `task check` | Non-green; skillscript failure in root suite. |
|
||||
| Repository gate | `task check` | See `archie-diagnostics-and-tooling` for the dated snapshot. |
|
||||
@@ -6,10 +6,11 @@ description: "Trace Archie behavior and blast radius through Go source, types, s
|
||||
# Discover the Archie codebase
|
||||
|
||||
Use evidence from the current checkout to explain a behavior before changing it.
|
||||
Volatile tool facts below were verified on **2026-07-28**.
|
||||
Volatile tool facts below were verified on **2026-09-18**.
|
||||
|
||||
**Composition roots**: `cmd/archied/main.go` (legacy wiring) and
|
||||
`internal/app/agentworker` (invoked by `cmd/archie-agent/main.go`).
|
||||
**Composition roots**: `cmd/archied/main.go` (thin dispatcher) →
|
||||
`internal/app/archied.Run()`, and `internal/app/agentworker` (invoked by
|
||||
`cmd/archie-agent/main.go`). Do not treat `cmd/*` as the wiring site.
|
||||
**Production wiring**: a path selected by a shipped entrypoint — not a
|
||||
constructor, decoder, or passing unit test. **State owner**: component with
|
||||
authority to validate and persist a state transition.
|
||||
@@ -21,8 +22,9 @@ go version; go env GOMOD GOWORK GOOS GOARCH
|
||||
gopls version; golangci-lint version; staticcheck -version
|
||||
```
|
||||
|
||||
As of 2026-07-28: Go 1.26.5, gopls 0.23.0, golangci-lint 2.12.2,
|
||||
staticcheck 2026.1. Use `gopls call_hierarchy` (no `go tool callgraph`).
|
||||
As of 2026-09-18: Go 1.27.0, gopls 0.23.0, golangci-lint 2.13.2,
|
||||
staticcheck 2026.2.1. Use `gopls call_hierarchy` (no `go tool callgraph`;
|
||||
`go tool` lists only asm, cgo, compile, cover, fix, link, preprofile, vet).
|
||||
|
||||
Writable caches when defaults are read-only:
|
||||
|
||||
@@ -63,12 +65,12 @@ Start at these verified anchors:
|
||||
|
||||
| Concern | Current anchor |
|
||||
|---|---|
|
||||
| Resident daemon | `cmd/archied/main.go` → `run()` → `daemon.Daemon` |
|
||||
| Resident daemon | `cmd/archied/main.go` → `internal/app/archied.Run()` (`internal/app/archied/main.go`) → `daemon.Daemon` |
|
||||
| Sandboxed worker | `cmd/archie-agent/main.go` → `internal/app/agentworker/`; NATS boundary in `internal/infrastructure/agenttransport/nats/` |
|
||||
| Task orchestration | `internal/daemon/daemon.go`, `internal/workflow/` |
|
||||
| Task contracts and SQLite | `internal/store/interface.go`, `internal/store/` |
|
||||
| Production task persistence | `internal/store/`; `store.Open` in `cmd/archied/main.go` |
|
||||
| RPC split | `internal/{nats,taskrun,natsrpc,storerpc,forgerpc,worktreerpc}/` |
|
||||
| Task orchestration | `internal/daemon/daemon.go`, `internal/domain/workflow/` |
|
||||
| Task contracts | `internal/domain/storecontract/storecontract.go` (`TaskStore`); `internal/store/interface.go` holds compatibility aliases only |
|
||||
| Production task persistence | `internal/store/`; `openProductionTaskStore` reached via `internal/app/archied/state_store.go` |
|
||||
| RPC split | `internal/{taskrun,natsrpc,forgerpc,worktreerpc}/` plus `internal/infrastructure/staterpc/` (gRPC State Store) |
|
||||
| Chat and channels | `internal/gateway/`, `internal/channels/` |
|
||||
| Configuration | `internal/config/`, `internal/infrastructure/configuration/`, `config.example.toml`, `deployments/*.toml` |
|
||||
| Target map | `docs/prds/01-project-management.md` and linked `docs/architecture/*.md` |
|
||||
@@ -80,7 +82,7 @@ Start at these verified anchors:
|
||||
```sh
|
||||
go list -f '{{.ImportPath}}|go={{join .GoFiles ","}}|tests={{join .TestGoFiles ","}}' ./internal/store
|
||||
go list -json ./internal/store
|
||||
.claude/skills/archie-codebase-discovery/scripts/package-edges.sh ./internal/...
|
||||
.agents/skills/archie-codebase-discovery/scripts/package-edges.sh ./internal/...
|
||||
```
|
||||
|
||||
### Resolve symbols with gopls
|
||||
@@ -88,20 +90,20 @@ go list -json ./internal/store
|
||||
1-indexed `file:line:column`:
|
||||
|
||||
```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
|
||||
go doc ./internal/store.TaskStore
|
||||
gopls symbols internal/domain/storecontract/storecontract.go
|
||||
gopls definition cmd/archied/main.go:27:14
|
||||
gopls references -d internal/domain/storecontract/storecontract.go:33:2
|
||||
gopls implementation internal/domain/storecontract/storecontract.go:33:2
|
||||
gopls call_hierarchy internal/domain/storecontract/storecontract.go:33:2
|
||||
go doc ./internal/domain/storecontract.TaskStore
|
||||
go test ./internal/store -list '.'
|
||||
```
|
||||
|
||||
### Generate AST candidates for construction
|
||||
|
||||
```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 .
|
||||
.agents/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh Daemon .
|
||||
.agents/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh -tests Task .
|
||||
```
|
||||
|
||||
Confirms candidates with `gopls definition` or `gopls references`. Pass
|
||||
@@ -154,7 +156,7 @@ Use `gopls references` on constructor and type.
|
||||
### Prove package dependency direction
|
||||
|
||||
```sh
|
||||
.claude/skills/archie-codebase-discovery/scripts/package-edges.sh ./internal/...
|
||||
.agents/skills/archie-codebase-discovery/scripts/package-edges.sh ./internal/...
|
||||
go list -deps -json <pattern>
|
||||
```
|
||||
|
||||
@@ -165,16 +167,20 @@ composition-root read → concrete component → observable behavior`.
|
||||
|
||||
```sh
|
||||
rg -n 'toml:"|yaml:"|json:"' internal/config
|
||||
rg -n 'LoadOverlay|LoadDir|finalize|ForTask|ToConfig' internal/config cmd
|
||||
rg -n 'Resolve|Overlay|Dir|finalize|ForTask|ToConfig' internal/infrastructure/configuration internal/app/archied
|
||||
gopls references -d <exact-field>
|
||||
```
|
||||
|
||||
As of 2026-07-28 `cmd/archied` calls `config.LoadOverlay`; `config.LoadDir` is
|
||||
test-only.
|
||||
Decoding lives in `internal/infrastructure/configuration`, not `internal/config`.
|
||||
`configuration.New(log)` returns a `Loader`; the composition root in
|
||||
`internal/app/archied/bootstrap.go` calls `Loader.Resolve` (with `Loader.Overlay`
|
||||
and `Loader.Dir` for overlay/`conf.d` inputs). There is no `config.Load` or
|
||||
`config.LoadDir`.
|
||||
|
||||
### Prove production composition
|
||||
|
||||
1. Start at `cmd/archied/main.go:run`.
|
||||
1. Start at `internal/app/archied/main.go` (`Run`), entered from
|
||||
`cmd/archied/main.go`.
|
||||
2. Record config condition per branch.
|
||||
3. Follow concrete construction into `daemon.Daemon` and gateway start.
|
||||
4. For container/NATS behavior, trace `cmd/archie-agent/main.go` into
|
||||
@@ -185,10 +191,11 @@ test-only.
|
||||
|
||||
### Trace SQLite persistence
|
||||
|
||||
Treat `internal/store` as the application contract and production adapter.
|
||||
Treat `internal/domain/storecontract` as the application contract and
|
||||
`internal/store` as the production SQLite adapter behind it.
|
||||
|
||||
```sh
|
||||
gopls implementation internal/store/interface.go:16:6
|
||||
gopls implementation internal/domain/storecontract/storecontract.go:33:2
|
||||
rg -n 'CREATE TABLE|CREATE INDEX|QueryContext|ExecContext|BeginTx' internal/store
|
||||
```
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@ Treat configuration as a dataflow, not as a struct inventory. Prove every
|
||||
claimed setting has an input, normalization path, composition seam, and runtime
|
||||
consumer.
|
||||
|
||||
Current evidence date: **2026-07-28**.
|
||||
Current evidence date: **2026-09-18**.
|
||||
|
||||
Use these status terms exactly:
|
||||
|
||||
@@ -39,8 +39,8 @@ Never upgrade a status merely because decoding tests pass.
|
||||
8. Assign one status from the table above.
|
||||
|
||||
```bash
|
||||
rg -n 'LoadOverlay|LoadDir|ForTask|ToConfig|flag\.' \
|
||||
internal/config cmd/archied cmd/archie-agent
|
||||
rg -n 'Resolve|Overlay|Dir|ForTask|ToConfig|flag\.' \
|
||||
internal/infrastructure/configuration internal/config internal/app/archied cmd/archie-agent
|
||||
rg -n 'FIELD_NAME|external_key|ENV_NAME' \
|
||||
--glob '*.go' --glob '*.toml' --glob '*.yml' --glob '*.yaml' .
|
||||
```
|
||||
@@ -49,10 +49,10 @@ rg -n 'FIELD_NAME|external_key|ENV_NAME' \
|
||||
|
||||
| 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 `configuration.Loader.Resolve`. | production-wired |
|
||||
| `archied -config-overlay PATH` | Resolves a file or directory overlay through the same loader. 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 |
|
||||
| `archied -config PATH` | Defaults to `$XDG_CONFIG_HOME/archie/config.toml`, or `$HOME/.config/archie/config.toml`; `internal/app/archied/bootstrap.go` builds `configuration.New(log)` and calls `Loader.Resolve`. | production-wired |
|
||||
| `archied -config-overlay PATH` | Resolves a file or directory overlay through the same loader (`Loader.Overlay`/`ApplyOverlay`); the dashboard runtime overlay is layered from its own SQLite store. Omitted overlay fields retain base values. | production-wired |
|
||||
| `configuration.Loader.Dir(base, overlay)` | Supports main YAML/TOML plus feature YAML and `conf.d`; no current entrypoint calls it. | test/library-only |
|
||||
| `config.Load(path)`, `config.LoadDir(...)` | Removed. The old `internal/config` package-level helpers no longer exist; decoding is `Loader`-based. | not applicable |
|
||||
| `config.example.toml` | Load-tested example, not a deployed configuration. | test/library-only |
|
||||
| `deployments/docker-nats-stack.toml` | Complete host-daemon configuration for the Compose-managed NATS service. It is copied into the operator's config directory; Compose does not mount it. | supported-example |
|
||||
| Operator config and environment | Lives outside the repository; contents are deployment-specific. | external-production-unknown |
|
||||
@@ -98,7 +98,7 @@ Do not expose these helper flags as daemon settings.
|
||||
| --- | --- | --- |
|
||||
| `work_dir`, `db_path` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; explicit `~` paths are home-expanded. `db_path` is a prefix: tasks/events use `<db_path>-tasks.sqlite` and conversations use `<db_path>-conversations.sqlite`. | production-wired |
|
||||
| `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. | partially-wired |
|
||||
| `plugin_dir` | Empty disables daemon plugin loading; configured directory loaded in `cmd/archied`. | production-wired |
|
||||
| `plugin_dir` | Empty disables daemon plugin loading; configured directory loaded in `internal/app/archied`. | production-wired |
|
||||
| `poll_interval` | Default `60s`; root poll loop uses it, identities may override only interval. | production-wired |
|
||||
| `label` | No default or validation; used for `dispatch.trigger = "label"` or `"either"`. | production-wired |
|
||||
| `max_retries` | Default `3`; repository value greater than zero overrides. | production-wired |
|
||||
@@ -118,10 +118,10 @@ Do not expose these helper flags as daemon settings.
|
||||
| `nats.url`, `token_env` | Empty URL keeps SQLite path. Configured token variable must be non-empty. | production-wired |
|
||||
| `containers.*` | See dedicated table below. | production-wired |
|
||||
| `chat.*` | See channel table below. | production-wired |
|
||||
| `memory.provider`, `provider_config` | Feature YAML decodes these; `cmd/archied` always starts built-in file provider at `work_dir/memory`. | decoded-but-unwired |
|
||||
| `tools.mcp_servers` | `cmd/archied` registers daemon-side MCP providers. Empty transport becomes `stdio`; only `stdio` accepted. `url` decoded but unused. | partially-wired |
|
||||
| `indexing.index_dir`, `indexing.db_path` | `finalize` derives paths under `work_dir`; no entrypoint constructs `internal/indexing.Manager`. | decoded-but-unwired |
|
||||
| `extra` / unknown `conf.d` values | Test/library-only `LoadDir` stores untyped data; no core production consumer. | decoded-but-unwired |
|
||||
| `memory.provider`, `provider_config` | Feature YAML decodes these; `internal/app/archied` always starts built-in file provider at `work_dir/memory`. | decoded-but-unwired |
|
||||
| `tools.mcp_servers` | `internal/app/archied` registers daemon-side MCP providers. Empty transport becomes `stdio`; only `stdio` accepted. `url` decoded but unused. | partially-wired |
|
||||
| `indexing.index_dir`, `indexing.db_path` | `finalize` derives paths under `work_dir`; no entrypoint constructs `internal/indexing.Manager` (the exported `NewManager` exists but has no production caller). | decoded-but-unwired |
|
||||
| `extra` / unknown `conf.d` values | Test/library-only `Loader.Dir` stores untyped data; no core production consumer. | decoded-but-unwired |
|
||||
|
||||
The default `agent.command = "archie-agent"` is not verified subprocess
|
||||
operation. `SubprocessRunner` expects one JSON invocation on stdin and one JSON
|
||||
@@ -169,12 +169,12 @@ token and allowed-user list. Every other file setting is startup-only.
|
||||
## Treat multi-identity as partially wired
|
||||
|
||||
`finalize` requires each identity's `name`, `bot_user`, non-empty repos, forge
|
||||
type, and `SecretRef` token. `cmd/archied` builds an identity forge client and
|
||||
worktree manager.
|
||||
type, and `SecretRef` token. `internal/app/archied` builds an identity forge
|
||||
client and worktree manager.
|
||||
|
||||
Do not infer complete isolation:
|
||||
|
||||
- `cmd/archied` resolves root forge client before all identity runners.
|
||||
- `internal/app/archied` resolves root forge client before all identity runners.
|
||||
- Identity `name`, forge, repos, poll interval, bot user, bot email have
|
||||
production reads. Identity bot email not defaulted despite comment.
|
||||
- Identity `models`, `providers`, `dispatch`, `budgets`, `notify`, and
|
||||
@@ -209,8 +209,8 @@ identity: identity forges require explicit structured `token`.
|
||||
| Telegram `token_env = "X"` | Reads `X`. | Not forwarded. | Not forwarded. |
|
||||
| `agent.env = ["X"]` | Names validated. | Copies present `X` from daemon env. | Not used by container construction. |
|
||||
|
||||
`cmd/archied` creates `secret.NewRegistry`, which registers only the `env`
|
||||
engine. Non-env `SecretRef` values are not production-wired.
|
||||
`internal/app/archied` creates `secret.NewRegistry`, which registers only the
|
||||
`env` engine. Non-env `SecretRef` values are not production-wired.
|
||||
|
||||
The host supervisor or launch shell supplies daemon secrets. Compose supplies
|
||||
no `archied` environment because the daemon is not a Compose service.
|
||||
|
||||
@@ -5,11 +5,14 @@ description: Project-specific symptom-to-evidence triage for archie-core. Load t
|
||||
|
||||
# Debug Archie from evidence
|
||||
|
||||
**current** = 2026-07-28 verified; **fixed history** = regression patterns;
|
||||
**open** = verified gap.
|
||||
**current** = 2026-09-18 verified (HEAD `2e1e1549`); **fixed history** =
|
||||
regression patterns; **open** = verified gap.
|
||||
|
||||
**Composition root**: `cmd/archied/main.go`. **Core NATS request/reply**: direct
|
||||
subject + reply inbox. **JetStream**: persisted stream `ARCHIE_TASKS`.
|
||||
**Composition root**: `cmd/archied/main.go` → `internal/app/archied.Run()`;
|
||||
wiring lives in `internal/app/archied/bootstrap.go`. **Core NATS
|
||||
request/reply**: direct subject + reply inbox. **JetStream**: persisted stream
|
||||
`ARCHIE_TASKS`. **State Store**: gRPC (`internal/infrastructure/staterpc`), not
|
||||
NATS.
|
||||
**Environment failure**: test/process cannot use host resource (listener, tmp,
|
||||
Docker). **Code regression**: behavior fails where prerequisites available.
|
||||
|
||||
@@ -29,7 +32,7 @@ Use this symptom index:
|
||||
|
||||
| Symptom | First boundary | Go to |
|
||||
|---|---|---|
|
||||
| `Run() = "\n"` in `TestRunWrapsExternalCommand` | Skill-script test command shape | Current known regression |
|
||||
| `Run() = "\n"` in `TestRunWrapsExternalCommand` | Skill-script test command shape | Fixed history — passes since 2026-09-16 |
|
||||
| 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 |
|
||||
@@ -68,9 +71,13 @@ repository-local mitigation. `worktree.Manager.setIdentity` pins
|
||||
GIT_CONFIG_GLOBAL=/dev/null go test ./internal/worktree -count=1
|
||||
```
|
||||
|
||||
## Confirm the current known regression
|
||||
## Confirm the skill-script regression stays fixed
|
||||
|
||||
As of 2026-07-28:
|
||||
The `TestRunWrapsExternalCommand` failure (`Run() = "\n"`) was a test bug, not
|
||||
a product bug: `exec.CommandContext(ctx, "sh", "-c", "echo", "wrapped")`
|
||||
passes `wrapped` as shell `$0`, so only `echo` ran. It failed from commit
|
||||
`308c199` and **passes as of 2026-09-16**. Re-run it to confirm the fix has not
|
||||
regressed; a failure now is a new defect, not this one.
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-skillscript-gocache \
|
||||
@@ -78,12 +85,6 @@ env GOTMPDIR=/tmp GOCACHE=/tmp/archie-skillscript-gocache \
|
||||
-run '^TestRunWrapsExternalCommand$' -count=1 -v
|
||||
```
|
||||
|
||||
Expected current failure: `Run() = "\n"`. The test constructs
|
||||
`exec.CommandContext(ctx, "sh", "-c", "echo", "wrapped")`. For `sh -c`, the
|
||||
argument after the command string becomes shell `$0`; therefore the command
|
||||
string is only `echo`, which prints a newline. This is a test regression from
|
||||
commit `308c199`, not proof that Yaegi cannot run external commands.
|
||||
|
||||
## Triage NATS request/reply and JetStream
|
||||
|
||||
| Surface | Subject or resource | Bound/current behavior |
|
||||
@@ -91,7 +92,7 @@ commit `308c199`, not proof that Yaegi cannot run external commands.
|
||||
| Task discovery | `archie.task.>` in `ARCHIE_TASKS` | Work-queue retention; daemon durable `archie-daemon`; max deliver 3 |
|
||||
| Per-stage agent request | `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 20s every 250ms |
|
||||
| Store RPC | `archie.store.update`, `.transition` | Client timeout 60s composed by `internal/app/agentworker/worker.go` through the infrastructure transport |
|
||||
| Store RPC | gRPC State Store (`internal/infrastructure/staterpc`) | Client timeout 60s (`rpcTimeout` in `internal/app/agentworker/worker.go`); task-scoped grants for Update/Transition/InsertEvent only |
|
||||
| Forge RPC | `archie.forge.*` | Error travels in a JSON envelope |
|
||||
| Worktree RPC | `archie.worktree.prepare`, `.push` | Server default handler bound 15m |
|
||||
| Discovery dedup | `Nats-Msg-Id: archie:<owner>/<repo>/<issue>` | JetStream duplicate window 2m |
|
||||
@@ -111,31 +112,33 @@ explicit `containers.network` plus warning logs now fence that path.
|
||||
|
||||
Check semantics: republishing same owner/repo/issue within 2m is dedup'd; reply
|
||||
inbox auto-unsubscribes after one response; `Client.Fetch` must inspect
|
||||
`batch.Error()`; `agentexec.runStages` returns envelope and nil error for stage
|
||||
failure.
|
||||
`batch.Error()`; an empty poll reports `eventbus.ErrNoMessage` rather than
|
||||
`(nil, nil)`.
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-nats-unit-gocache \
|
||||
go test ./internal/nats -run '^TestFetchPropagatesBatchError' -count=1 -v
|
||||
go test ./internal/infrastructure/eventbus/nats -run 'TestPublishUniqueSuppressesDuplicateKeyOnWorkQueueStream' -count=1 -v
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-agent-unit-gocache \
|
||||
go test ./internal/agentexec -run '^TestHandleMessage' -count=1 -v
|
||||
go test ./internal/agentexec -run '^TestToolSetHandler' -count=1 -v
|
||||
```
|
||||
|
||||
## Trace configuration from source to behavior
|
||||
|
||||
Trace: `cmd/archied` reads `-config`/`-config-overlay` → `config.LoadOverlay`
|
||||
Trace: `cmd/archied` (`internal/app/archied/bootstrap.go`) reads
|
||||
`-config`/`-config-overlay` → `configuration.New(log)` + `Loader.Resolve`
|
||||
decodes, `finalize` defaults/validates → secrets resolve → composition root
|
||||
constructs service → Compose/subprocess/`containerEnv` propagate → consumer.
|
||||
|
||||
```bash
|
||||
rg -n 'config\.LoadOverlay|config\.LoadDir' cmd/archied internal/config
|
||||
rg -n 'Loader\.(Resolve|Overlay|Dir)|configuration\.' internal/app/archied internal/infrastructure/configuration
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-gocache \
|
||||
go test ./internal/config \
|
||||
-run 'Test(LoadOverlay|LoadForgeToken|DockerConfig)' -count=1 -v
|
||||
go test ./internal/infrastructure/configuration \
|
||||
-run 'Test(ResolveSelectsFileFormatsAndDirectories|LoadForgeTokenEnvBackwardCompat)' -count=1 -v
|
||||
```
|
||||
|
||||
`config.LoadDir` is test-only; a YAML field decoding correctly without
|
||||
composition-root read is a wiring gap, not a parser bug.
|
||||
The `config.Load`/`config.LoadDir` helpers are gone; decoding is
|
||||
`Loader`-based. A YAML field decoding correctly without a composition-root read
|
||||
is a wiring gap, not a parser bug.
|
||||
|
||||
For environment failures:
|
||||
- The host supervisor supplies the daemon environment; inspect its unit or
|
||||
@@ -188,7 +191,7 @@ bot token. Empty `allowed_user_ids` denies everyone.
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-telegram-gocache \
|
||||
go test ./internal/channels/telegram \
|
||||
-run 'Test(SenderAllowlistFailsClosed|IsSenderAllowed|PublishedCommandsMatchExecutableCommandSurface)$' \
|
||||
-run 'Test(SenderAllowlistFailsClosed|IsSenderAllowed|SessionManagementCommandsArePublished)$' \
|
||||
-count=1 -v
|
||||
```
|
||||
|
||||
@@ -197,9 +200,12 @@ env GOTMPDIR=/tmp GOCACHE=/tmp/archie-telegram-gocache \
|
||||
## Diagnose state, events, containers, and optional features
|
||||
|
||||
### SQLite and transitions
|
||||
`internal/store.Store.Transition` owns task state changes and transition history.
|
||||
`internal/store.Store.Transition` owns task state changes and transition
|
||||
history: it guards on `from` (`WHERE id=? AND status=?`, returning
|
||||
`store.ErrStaleTransition`) and writes status plus history in one transaction.
|
||||
When state is surprising: read `TaskByID` before/after caller; trace every
|
||||
`Transition`, `Requeue`, `RecoverStale`, `Update`.
|
||||
`Transition`, `Requeue`, `RecoverStale`, `Update` — and remember the daemon
|
||||
exposes these over the gRPC State Store, not NATS.
|
||||
|
||||
```bash
|
||||
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-state-gocache go test ./internal/store -count=1
|
||||
@@ -222,4 +228,4 @@ root-identity-bound; `SubprocessRunner` expects stdin JSON protocol.
|
||||
| Invalid MCP config | Warn and continue |
|
||||
| Skill catalog | Warn, continue without tool |
|
||||
| Worktree augmentation | Log error, use startup registry |
|
||||
| Workspace indexing | **Open:** no production `indexing.NewManager` call |
|
||||
| Workspace indexing | **Open:** `indexing.NewManager` exists but has no production caller in `internal/app/archied` |
|
||||
@@ -8,8 +8,8 @@ description: "Measure Archie codebase maintainability, Go package dependency sha
|
||||
Collect evidence before judging quality. Keep collection read-only, save raw
|
||||
output, state what each metric cannot prove.
|
||||
|
||||
Volatile facts and numeric snapshots below were verified on **2026-09-16**
|
||||
(HEAD `d565fb8`).
|
||||
Volatile facts and numeric snapshots below were verified on **2026-09-18**
|
||||
(HEAD `2e1e1549`).
|
||||
|
||||
Route to `archie-codebase-discovery` for semantic traces,
|
||||
`archie-config-and-flags` for config enumeration,
|
||||
@@ -21,7 +21,7 @@ Route to `archie-codebase-discovery` for semantic traces,
|
||||
environment.
|
||||
- **Candidate:** a machine-found item requiring semantic confirmation.
|
||||
- **Production composition:** concrete construction selected by a shipped
|
||||
entrypoint. Principal: `cmd/archied/main.go`.
|
||||
entrypoint. Principal: `cmd/archied/main.go` → `internal/app/archied.Run()`.
|
||||
- **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
|
||||
@@ -42,7 +42,7 @@ export GOLANGCI_LINT_CACHE=/tmp/archie-diagnostics-lint
|
||||
export GOPROXY=off
|
||||
export GOFLAGS=-mod=readonly
|
||||
|
||||
skill=.claude/skills/archie-diagnostics-and-tooling
|
||||
skill=.agents/skills/archie-diagnostics-and-tooling
|
||||
stamp=$(date -u +%Y%m%dT%H%M%SZ)
|
||||
evidence_dir=/tmp/archie-diagnostics-"$stamp"
|
||||
mkdir -p "$evidence_dir"
|
||||
@@ -173,7 +173,7 @@ golangci-lint run --enable-only=dupl ./internal/...
|
||||
staticcheck -checks=U1000 ./internal/...
|
||||
```
|
||||
|
||||
On 2026-09-16, the focused `dupl` command reported zero issues. Two code paths
|
||||
On 2026-09-18, the focused `dupl` command reported zero issues. Two code paths
|
||||
can implement the same responsibility with different syntax.
|
||||
|
||||
For every candidate: name the externally visible operation; search all
|
||||
@@ -183,7 +183,7 @@ OS files, and wire names; identify what a new feature supersedes; record
|
||||
production-only, test-only, compatibility, generated, and unreachable paths
|
||||
separately.
|
||||
|
||||
As of 2026-09-16, `Taskfile.yml` defines no `deadcode` task and `go tool` lists
|
||||
As of 2026-09-18, `Taskfile.yml` defines no `deadcode` task and `go tool` lists
|
||||
no dead-code analyzer.
|
||||
|
||||
## Collect test, race, coverage, and runtime evidence
|
||||
@@ -194,7 +194,7 @@ go tool cover -func=/tmp/archie-store.cover
|
||||
go test -race ./internal/store -count=1
|
||||
```
|
||||
|
||||
As of 2026-09-16, the package reported 78.6% statement coverage and passed its
|
||||
As of 2026-09-18, the package reported 78.6% statement coverage and passed its
|
||||
race run.
|
||||
|
||||
```sh
|
||||
@@ -231,26 +231,26 @@ duplication, hid a path, or weakened a gate.
|
||||
|
||||
## Dated current snapshot
|
||||
|
||||
The bundled scripts measured this checkout on 2026-09-16 (HEAD `d565fb8`).
|
||||
The bundled scripts measured this checkout on 2026-09-18 (HEAD `2e1e1549`).
|
||||
These are post-fix numbers: earlier runs of the same scripts reported roughly
|
||||
3x these file and line counts because they walked `.worktrees/`.
|
||||
|
||||
| Observation | Unstable value |
|
||||
|---|---:|
|
||||
| Root production/test/generated Go files | 408 / 397 / 9 |
|
||||
| Root production/test/generated physical lines | 73,729 / 93,572 / 12,237 |
|
||||
| Root production/test/generated Go files | 408 / 402 / 9 |
|
||||
| Root production/test/generated physical lines | 74,752 / 95,264 / 12,774 |
|
||||
| `internal/app/archied.Run` body span / approximate complexity | 97 / 19 |
|
||||
| Root internal packages / direct internal edges | 110 / 306 |
|
||||
| Tagged config field rows | 196 |
|
||||
| Tracked paths / tracked `node_modules` paths / tracked symlinks | 1,081 / 0 / 1 |
|
||||
| Root internal packages / direct internal edges | 110 / 316 |
|
||||
| Tagged config field rows | 194 |
|
||||
| Tracked paths / tracked `node_modules` paths / tracked symlinks | 1,087 / 0 / 1 |
|
||||
| `.dockerignore` present | 1 |
|
||||
|
||||
`source-metrics.go` and `git ls-files` reconcile exactly here: 408 + 9
|
||||
generated production files and 397 test files, plus the `tools` module's
|
||||
5 / 2 / 0, against 422 non-test and 398 test tracked files. The single extra
|
||||
file is an untracked probe under `.local/`.
|
||||
`source-metrics.go` and `git ls-files` reconcile here: 408 + 9 generated
|
||||
production files and 402 test files, plus the `tools` module's 5 / 2 / 0,
|
||||
against 422 non-test and 403 test tracked files. The single extra file is an
|
||||
untracked probe under `.local/issue-tracker/probes/`.
|
||||
|
||||
The scripts count themselves: the skill's own Go files contribute 816 of those
|
||||
The scripts count themselves: the skill's own Go files contribute 640 of those
|
||||
production lines. Editing a bundled script therefore moves
|
||||
`production_physical_lines` on its own, so re-baseline after any script change
|
||||
rather than reading the delta as a change in the product code.
|
||||
|
||||
@@ -54,7 +54,7 @@ scan_literal task_race taskfile 'go test[^#\n]*-race|-race[^#\n]*go test' Taskfi
|
||||
scan_literal task_tools_module taskfile 'go -C tools|cd tools|task:[[:space:]]+tools' Taskfile.yml
|
||||
scan_literal task_docs taskfile 'docsgen|docs:generate|docs:check' Taskfile.yml
|
||||
|
||||
# One CI surface: .github/workflows. The Gitea workflow was dropped in e539048
|
||||
# One CI surface: .github/workflows. The Gitea workflow was dropped in dd9bddc2
|
||||
# ("ci: build and push images to GHCR, drop the Gitea workflow"), so scanning
|
||||
# .gitea/workflows aborted the whole snapshot under `set -eu`.
|
||||
scan_literal github_go_gate github-workflows 'go test|go vet|go build|golangci-lint|task[[:space:]]+check' .github/workflows
|
||||
|
||||
@@ -19,7 +19,7 @@ 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"
|
||||
edge_helper="$repo_root/.agents/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
|
||||
|
||||
@@ -9,7 +9,9 @@ Write one durable record for each decision or behavior. Separate what runs now
|
||||
from what Archie has approved as its destination.
|
||||
|
||||
Route to `archie-architecture-planning-campaign` for ownership/boundary
|
||||
decisions, `archie-architecture-contract` for invariants,
|
||||
decisions (parked outside this checkout, under
|
||||
`/work/apps/archie-skills-parked/`),
|
||||
`archie-architecture-contract` for invariants,
|
||||
`archie-codebase-discovery` for live entry points,
|
||||
`archie-failure-archaeology` for incidents,
|
||||
`archie-config-and-flags`, `archie-build-and-env`, or `archie-run-and-operate`
|
||||
@@ -34,12 +36,12 @@ migration delta.
|
||||
|
||||
## Use the repository authority map
|
||||
|
||||
Verified on 2026-07-28:
|
||||
Verified on 2026-09-18:
|
||||
|
||||
| Location | Role | Discipline |
|
||||
|---|---|---|
|
||||
| Live Go code, tests, `Taskfile.yml`, executable config parsing, composition under `cmd/` | `CURRENT` execution evidence | Trace producers and consumers; tests prove only asserted behavior |
|
||||
| `CLAUDE.md` | Current contributor and safety protocol plus compact architecture orientation | Verify operational claims against code and `Taskfile.yml`; `AGENTS.md` is a symlink |
|
||||
| Live Go code, tests, `Taskfile.yml`, executable config parsing, composition under `internal/app/` (entered from `cmd/`) | `CURRENT` execution evidence | Trace producers and consumers; tests prove only asserted behavior |
|
||||
| `CLAUDE.md` | Current contributor and safety protocol plus compact architecture orientation | Verify operational claims against code and `Taskfile.yml`; `AGENTS.md` is a symlink to it |
|
||||
| `ARCHITECTURE.md` | Useful architecture history and partial current overview | Corroborate every inventory/status claim; its "Planned" list is stale for implemented skill support |
|
||||
| `docs/prds/01-project-management.md` | Index and approved foundation for target architecture | Add or change target decisions in the focused document it names |
|
||||
| `docs/architecture/*.md` | Focused target decisions, active review procedure, migration inventory | Read each file's status |
|
||||
@@ -50,7 +52,7 @@ Verified on 2026-07-28:
|
||||
| `docs/data/generated/contracts.json` | Current working-tree `GENERATED` output | Regenerate; never edit by hand |
|
||||
| `docs/` | Repository documentation only | Nothing builds, renders, or publishes it; Markdown is the artifact |
|
||||
|
||||
The repository root has no `README.md` or `CONTRIBUTING.md` as of 2026-07-28.
|
||||
The repository root has no `README.md` or `CONTRIBUTING.md` as of 2026-09-18.
|
||||
|
||||
## Choose one destination
|
||||
|
||||
@@ -117,26 +119,24 @@ Distinguish evidence strength:
|
||||
## 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
|
||||
`CHANGELOG.archie.md`; keep `CHANGELOG.md` as their index.
|
||||
`Dockerfile.archied` copies both component files to `/usr/share/archie/`, and
|
||||
`internal/releaseannounce.changelogSection` parses a version heading.
|
||||
|
||||
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` expects
|
||||
the unprefixed current heading.
|
||||
|
||||
Resolve parser, release metadata tests, and both documents atomically; do not
|
||||
"fix" only the prose.
|
||||
Version-heading format is settled as of 2026-09-18: both component changelogs
|
||||
use `## [1.27.0]` with no `v` prefix, `changelogSection` searches for
|
||||
`## [<version>]`, and `.github/workflows/deploy.yml` gates each release tag with
|
||||
`grep -q "^## \[$ver\]" CHANGELOG.<component>.md`. The earlier
|
||||
`vX.Y.Z`-vs-`X.Y.Z` contradiction involved `.gitea/workflows/deploy.yml`, which
|
||||
was dropped (`dd9bddc2 ci: build and push images to GHCR, drop the Gitea
|
||||
workflow`), so that question is `HISTORICAL`, not `OPEN`. The remaining guard is
|
||||
the CI shell gate plus `internal/releaseannounce`'s announcer tests
|
||||
(`TestAnnouncerReportsMissingReleaseSectionWithoutAdvancingState`); the old
|
||||
`cmd/archied.TestChangelogsTrackGatewayAndRuntimeIndependently` no longer exists.
|
||||
|
||||
## Maintain generated contracts
|
||||
|
||||
Current behavior, verified 2026-07-28:
|
||||
Current behavior, verified 2026-09-18:
|
||||
|
||||
- Tool path is `tools/docsgen`, not `tools/cmd/docsgen`.
|
||||
- Separate Go module replacing root module with `../`.
|
||||
@@ -170,7 +170,7 @@ step; the publishing surface is an open decision
|
||||
| Content | Markdown under `docs/`, including `docs/data/generated/contracts.json` |
|
||||
| Links | Repository-relative (`../architecture/organisation.md`); no root-absolute links |
|
||||
| Build | None. There is no site, no dev server, no link checker, no Pages deploy |
|
||||
| Nav | `docs/prds/01-project-management.md` |
|
||||
| Nav | `docs/prds/01-project-management.md` is the index; there is no site nav |
|
||||
|
||||
Because no build validates links, check them yourself or with a one-off script —
|
||||
nothing catches a dead link for you:
|
||||
|
||||
@@ -10,8 +10,12 @@ domain meaning with its owner, and mark migration state explicitly.
|
||||
|
||||
## Classify every statement
|
||||
|
||||
As of 2026-07-28, Archie is between technical-package implementation and
|
||||
approved domain-oriented target. Never blend the two.
|
||||
As of 2026-09-18, Archie is partway through the domain migration: some approved
|
||||
target packages now exist and are production-wired (`internal/domain/messaging`,
|
||||
`internal/domain/workflow`, `internal/domain/workintake`, `internal/app`,
|
||||
`internal/eventbus`, `internal/infrastructure`), while others remain target-only
|
||||
(`internal/domain/agent`, `internal/domain/identity`, `internal/policy`). Never
|
||||
blend the two.
|
||||
|
||||
| Label | Meaning | Evidence rule |
|
||||
| --- | --- | --- |
|
||||
@@ -23,7 +27,7 @@ approved domain-oriented target. Never blend the two.
|
||||
Start design notes with status sentences:
|
||||
|
||||
```text
|
||||
CURRENT: store.Task persists one mutable Stage string.
|
||||
CURRENT: task.Task persists one mutable Stage string.
|
||||
APPROVED TARGET: WorkflowExecution records StepExecution history.
|
||||
OPEN: the exact schema and Go API for that history.
|
||||
```
|
||||
@@ -61,10 +65,10 @@ rg -n 'type IdentityConfig|type IdentityRunner|Identity string|BotUser string' i
|
||||
| **Adapter** | Boundary code translating external payloads into owned contracts. | **TARGET RULE:** infrastructure implements domain-owned interfaces. |
|
||||
| **Gateway** | Current technical interface/router and package — not approved domain vocabulary. | **CURRENT ONLY:** `internal/gateway`, `internal/channels`. |
|
||||
| **ChannelBindingID** | Stable reference connecting Agent to channel binding. | **APPROVED TARGET INPUT:** part of Conversation identity. |
|
||||
| **Message** | Immutable application record with MessageID and typed content. Platform IDs are external correlations. | **TARGET:** Messaging. **CURRENT:** `gateway.Message`; richer `MessageEvent` exists beside it. |
|
||||
| **Conversation** | AgentID + UserIdentityID + ChannelBindingID + ExternalConversationID + ThreadID. | **CONFIRMED TARGET:** Messaging. **CURRENT:** `gateway.SessionSource` lacks canonical Agent/user IDs. |
|
||||
| **Message** | Immutable application record with MessageID and typed content. Platform IDs are external correlations. | **CURRENT:** `internal/domain/messaging.Message`/`MessageID`; `gateway.MessageEvent` is a richer event type beside it. |
|
||||
| **Conversation** | AgentID + UserIdentityID + ChannelBindingID + ExternalConversationID + ThreadID. | **CONFIRMED TARGET, partly current:** `internal/domain/messaging.Conversation`/`ConversationID` exist; the gateway session store still lacks canonical Agent/user IDs. |
|
||||
| **Conversation branch** | Child conversation from one immutable parent message. | **CONFIRMED TARGET.** No current implementation. |
|
||||
| **Work Intake** | Admission, validation, routing boundary between interaction and durable workflow-backed work. | **CONFIRMED TARGET:** `internal/domain/workintake`. Does not exist as current package. |
|
||||
| **Work Intake** | Admission, validation, routing boundary between interaction and durable workflow-backed work. | **CONFIRMED TARGET, current package:** `internal/domain/workintake` exists. |
|
||||
| **Accepted work request** | Channel-neutral handoff after Work Intake accepts proposed outcome. | **TARGET HANDOFF:** Agent System consumes it, selects Workflow version, creates WorkflowExecution. |
|
||||
|
||||
Do not equate an inbound Message with work. An Agent may answer, use
|
||||
@@ -80,10 +84,10 @@ external payload -> channel adapter -> canonical Message and Conversation
|
||||
```
|
||||
|
||||
Do not describe current `/spawn` as this target. It directly creates a
|
||||
`store.Task` with synthetic forge issue number.
|
||||
`task.Task` with synthetic forge issue number.
|
||||
|
||||
```bash
|
||||
rg -n 'type Message struct|type MessageEvent struct|ToLegacy|type SessionSource|CreateTask|EnqueueChatTask|synthetic' internal/gateway internal/store cmd/archied
|
||||
rg -n 'type Message struct|type MessageEvent struct|ToLegacy|type Conversation struct|CreateTask|EnqueueChatTask|synthetic' internal/domain/messaging internal/gateway internal/store internal/app/archied
|
||||
```
|
||||
|
||||
## Use the canonical execution vocabulary
|
||||
@@ -91,10 +95,10 @@ rg -n 'type Message struct|type MessageEvent struct|ToLegacy|type SessionSource|
|
||||
| Term | Archie meaning | Current representation |
|
||||
| --- | --- | --- |
|
||||
| **Workflow** | Reusable, versioned definition. | `workflow.Workflow` is named `[]Stage` without durable version model. |
|
||||
| **WorkflowExecution** | One durable execution of one Workflow version. | `store.Task` is migration baseline. |
|
||||
| **WorkflowExecution** | One durable execution of one Workflow version. | `task.Task` is migration baseline. |
|
||||
| **WorkflowStep** | One defined operation. | `workflow.Stage` is closest definition. |
|
||||
| **StepExecution** | Durable record of one step's execution and outcome. | Missing; `store.Task.Stage` is one mutable string. |
|
||||
| **Attempt** | Retry within same WorkflowExecution. | `Task.Attempt`/`RetryCount` must become explicit attempt history. |
|
||||
| **StepExecution** | Durable record of one step's execution and outcome. | Missing; `task.Task.Stage` is one mutable string. |
|
||||
| **Attempt** | Retry within same WorkflowExecution. | `task.Task.Attempt`/`RetryCount` must become explicit attempt history. |
|
||||
| **Agent step execution** | One bounded model-backed WorkflowStep invocation. | `agentexec.Request`/`Result` correlate TaskID, Attempt, Stage, protocol version. |
|
||||
|
||||
Use `WorkflowExecution` in domain contracts, architecture, generated reference.
|
||||
@@ -103,7 +107,7 @@ informal prose.
|
||||
|
||||
### Interpret the current lifecycle exactly
|
||||
|
||||
**CURRENT** `store.Task` states:
|
||||
**CURRENT** `task.Task` states:
|
||||
|
||||
```text
|
||||
queued -> running
|
||||
@@ -114,12 +118,13 @@ pr_open -> merged | rejected
|
||||
running after crash -> queued
|
||||
```
|
||||
|
||||
Do not claim enforced. `Store.Transition` writes new status without comparing
|
||||
`from`, inserts history separately. `internal/gateway/tasks.go` duplicates
|
||||
status strings locally.
|
||||
Do not claim enforced. `Store.Transition` now guards on `from`
|
||||
(`WHERE id=? AND status=?` → `store.ErrStaleTransition`) and writes status plus
|
||||
history in one transaction; the sentinel crosses the State Store gRPC boundary.
|
||||
See `internal/store/store.go`.
|
||||
|
||||
```bash
|
||||
rg -n 'Status[A-Za-z]+|func \(s \*Store\) Transition|func \(s \*Store\) Requeue|RecoverStale' internal/store internal/gateway
|
||||
rg -n 'Status[A-Za-z]+|func \(s \*Store\) Transition|func \(s \*Store\) Requeue|RecoverStale' internal/store internal/domain/workflow internal/gateway
|
||||
```
|
||||
|
||||
## Keep memory scope separate from conversation scope
|
||||
@@ -154,7 +159,7 @@ rg -n 'type MemoryProvider|Initialize\(|type Config struct|MEMORY.md|USER.md|Age
|
||||
Give plugin only narrow typed registrars and explicitly supplied contracts.
|
||||
|
||||
```bash
|
||||
go test ./internal/plugin -run 'Test(GenericPluginContractRemainsMetadataOnly|EveryEngineInterfaceHasTypedCapabilityAndFamilyOwner)' -count=1
|
||||
go test ./internal/plugin -run 'Test(EngineFamilyInspectionRejectsInvalidShapes|PluginInterfaceExists)' -count=1
|
||||
```
|
||||
|
||||
## Distinguish ownership and boundary terms
|
||||
@@ -164,14 +169,16 @@ go test ./internal/plugin -run 'Test(GenericPluginContractRemainsMetadataOnly|Ev
|
||||
| **Domain** | Own one cohesive responsibility: vocabulary, state, rules, operations, commands, events, policies, runtime settings, required service contracts. |
|
||||
| **Command** | Request an action. Receiving domain owns contract and decides result. |
|
||||
| **Domain event** | Record something that happened. Publishing domain owns schema. |
|
||||
| **Event bus** | Broker-neutral delivery/lifecycle contract. `internal/eventbus` is approved target, not current. |
|
||||
| **Event bus** | Broker-neutral delivery/lifecycle contract. `internal/eventbus` exists and is production-wired. |
|
||||
| **Observability event** | `internal/events.Event` projection input. Bounded in-process bus may drop. Not authoritative state. |
|
||||
| **Policy** | Typed rule evaluated through shared mechanics. Consuming domain owns vocabulary. |
|
||||
| **Infrastructure** | Implements domain-owned ports, translates DBs, brokers, SDKs, files, containers. |
|
||||
| **Application composition** | Chooses implementations, translates config, connects contracts, orders startup/shutdown. Target: `internal/app`; current wiring in `cmd/archied`. |
|
||||
| **Application composition** | Chooses implementations, translates config, connects contracts, orders startup/shutdown. Current and target: `internal/app`; `cmd/*` stays process-input-only. |
|
||||
|
||||
As of 2026-07-28, `internal/domain`, `internal/eventbus`, `internal/policy`,
|
||||
`internal/infrastructure`, `internal/app` do not exist. Target paths only.
|
||||
As of 2026-09-18, `internal/domain`, `internal/eventbus`,
|
||||
`internal/infrastructure`, and `internal/app` exist; only `internal/policy`
|
||||
does not. `internal/domain/agent` and `internal/domain/identity` are still
|
||||
target-only.
|
||||
|
||||
```bash
|
||||
for p in internal/domain internal/eventbus internal/policy internal/infrastructure internal/app; do test -d "$p" && echo "$p CURRENT" || echo "$p TARGET-ONLY"; done
|
||||
@@ -196,15 +203,15 @@ Model never runs git directly. Worktree operations are daemon-owned.
|
||||
| `config.IdentityConfig.Name` | Canonical IdentityID plus separate bindings | Do not preserve mutable display name as ID. |
|
||||
| `config.IdentityConfig.BotUser` | Forge/Git or channel external binding | Not Conversation or Agent identity. |
|
||||
| `daemon.IdentityRunner` | Composition of identity-correlated capabilities | Currently service bundle, not Identity aggregate. |
|
||||
| `gateway.Message`, `MessageEvent` | Canonical Messaging Message | Choose one immutable typed contract. |
|
||||
| `gateway.SessionContext` | Conversation metadata | Add canonical Agent/user/binding ownership. |
|
||||
| `gateway.MessageEvent` | Canonical Messaging Message | Choose one immutable typed contract; `internal/domain/messaging.Message` is the target. |
|
||||
| gateway session context | Conversation metadata | Add canonical Agent/user/binding ownership. |
|
||||
| forge `Issue` or future Jira item | Channel message or external artifact | Preserve native reference in adapter. |
|
||||
| gateway `/spawn` and `TaskCreator` | Proposed/accepted work handoff | Work Intake admits; Agent System creates execution. |
|
||||
| `store.Task` | WorkflowExecution | Preserve every field intentionally. |
|
||||
| `store.Task` | WorkflowExecution | Preserve every field intentionally; the type now lives at `internal/domain/workflow/task.Task`. |
|
||||
| `workflow.Workflow` | Versioned Workflow definition | Add identity/version ownership before parity. |
|
||||
| `workflow.Stage` | WorkflowStep definition | A definition is not execution history. |
|
||||
| mutable `Task.Stage` | Derived position plus StepExecution records | Deletion requires proven history parity. |
|
||||
| `Task.Attempt`, `RetryCount` | Attempt history and retry evidence | Keep worker delivery retries distinct. |
|
||||
| `task.Task.Attempt`, `RetryCount` | Attempt history and retry evidence | Keep worker delivery retries distinct. |
|
||||
| `workflow.TaskContext` | Execution state plus narrow step ports | Remove global config/service bag. |
|
||||
| `events.Event` and `Bus` | Projections fed by authoritative domain events | Current drops acceptable for observability, not state. |
|
||||
| `cmd/archied` wiring | `internal/app/archied` composition | Keep `cmd/*` process-input-only. |
|
||||
|
||||
@@ -9,7 +9,7 @@ Stop the project from paying twice for the same lesson. Reconstruct what
|
||||
happened from checked-out code, tests, configuration, and commit graph.
|
||||
Treat commit prose as a lead, not proof. Preserve uncertainty.
|
||||
|
||||
All volatile observations are dated **2026-07-28**.
|
||||
All volatile observations are dated **2026-09-18** (HEAD `2e1e1549`).
|
||||
|
||||
Route to `archie-debugging-playbook` for active symptoms,
|
||||
`archie-codebase-discovery` for deep caller tracing.
|
||||
@@ -109,7 +109,7 @@ If current behavior differs from chronicle, update the packet.
|
||||
|
||||
| Incident and date | Symptom | Root cause | Evidence and status | Settled rule |
|
||||
|---|---|---|---|---|
|
||||
| Label auto-claim, 2026-07-22 | >80 labelled issues enrolled under label polling. | Label polling means eligibility, not hint. | `519882f` changes `config.docker.toml` to `assignee`. `internal/config/config.go` defaults to `assignee` but permits `label` and `either`. **Status:** `settled`. | Default to assignee-driven pickup. Label/either are deliberate bulk enrollment. |
|
||||
| Label auto-claim, 2026-07-22 | >80 labelled issues enrolled under label polling. | Label polling means eligibility, not hint. | `519882f` changed the Compose profile to `assignee`; that file was deleted (`cbb7929e`) and survives as `deployments/docker-nats-stack.toml`, which sets `trigger = "assignee"`. `internal/config/config.go` defaults to `assignee` but permits `label` and `either`. **Status:** `settled`. | Default to assignee-driven pickup. Label/either are deliberate bulk enrollment. |
|
||||
| Baseline-red park storm, 2026-07-23 onward | Task parks on gate failure that existed before its feature work. | Parking/retrying cannot change pre-existing failure; auto-repair mixes repository repair into feature scope. | `b2482af` made `StageBaselineGate` launch builder instead of parking. Nine repair commits in history. **Status:** `current` mitigation and architecture weak point. | Measure untouched baseline first. Track baseline repair as explicit change. |
|
||||
| Passed build with zero changes, 2026-07-23 | Commit-push reports "no changes," parks, retries, repeats. | "Passed with no changes" lacked terminal domain outcome. | `62c0df1` introduced no-op detection; `2bf42bd` set `Outcome`. `TestStageCommitPushClosesIssueWhenBuildNoChanges`. **Status:** `settled`. | Model no-op as explicit terminal result. |
|
||||
| Infinite parked-task retry, 2026-07-23 | Removing parked label repeatedly requeues with no terminal bound. | Retry count not durable or capped. | `a8fdb50` added persisted `retry_count`, global/per-repo `max_retries`, and `dead`. **Status:** `settled`. | Every autonomous retry needs durable attempt state, explicit bound, terminal state, and operator-visible reason. |
|
||||
@@ -119,7 +119,7 @@ If current behavior differs from chronicle, update the packet.
|
||||
| Incident and date | Symptom | Root cause | Evidence and status | Settled rule |
|
||||
|---|---|---|---|---|
|
||||
| Container network auto-detection, 2026-07-27 | Every container task returns `nats: no responders`. | `selfNetwork` inspected hostnamed container, silently fell back to default bridge. | `37cf089` records incident, adds `containers.network`; `2ac306b` pins `archie-core_default`. **Status:** `conditional`. | Make cross-container network membership explicit in deployment. |
|
||||
| SecretRef schema crash-loop, 2026-07-27 and current `HEAD` | Both identities demand `ARCHIE_GITHUB_TOKEN` despite Gitea config. | Removing old `token_env` field let TOML ignore deployed value. `1f8588d` restored precedence-compatible fallback; `308c199` removed `Forge.TokenEnv` declaration while `finalize` still references it. **Status:** `open` regression at `HEAD`. | Preserve decoded compatibility until deployed files migrated and rejection of stale keys observable. |
|
||||
| SecretRef schema crash-loop, 2026-07-27 | Both identities demand `ARCHIE_GITHUB_TOKEN` despite Gitea config. | Removing old `token_env` field let TOML ignore deployed value. `1f8588d` restored precedence-compatible fallback; a later `308c199` removed the `Forge.TokenEnv` declaration while `finalize` still referenced it. | **Status: `settled`** as of 2026-09-18 — `config.Forge.TokenEnv` is declared (`internal/config/config.go`) and `configuration/defaults.go` converts it to an env `SecretRef` when the structured token is empty. | Preserve decoded compatibility until deployed files migrated and rejection of stale keys observable. |
|
||||
| Compose secret omission, 2026-07-27 | Config names valid env var, container sees it empty. | Compose forwards only listed environment entries. | `22fc0ef`, `d0624b7`. **Status:** `conditional`. | Trace every secret from config key to host value to Compose passthrough to process lookup. |
|
||||
| FullStream/TextStream deadlock, 2026-07-27 | Streamed Telegram reply renders empty cursor, typing never clears. | ai-sdk makes `FullStream` authoritative and backpressured; `TextStream` is best-effort. | `6a0bd27`. **Status:** `settled` with regression-test gap. | Drain authoritative stream through close. |
|
||||
| MCP Content-Length framing and mirrored fake, 2026-07-26 to 2026-07-27 | Internal MCP tests pass while official-SDK servers do not. | MCP stdio uses newline-delimited JSON. Test subprocess called same helpers, mirroring the same wrong protocol. | Compare `f2768eb:internal/tools/mcp/framing.go` with `dda4cde`. **Status:** `settled`. | For wire contracts, test raw canonical frames and independently implemented peer. |
|
||||
@@ -164,15 +164,18 @@ If current behavior differs from chronicle, update the packet.
|
||||
| Incident and date | Symptom | Root cause | Status | Settled rule |
|
||||
|---|---|---|---|---|
|
||||
| Tracked `.gotmp`, 2026-07-27 | Build-cache binaries, generated `_testmain.go`, `.git-askpass` appear in commits. | Workaround path not ignored before use. | `4cb0577` removes artifacts and adds `.gotmp/` to `.gitignore`. **Settled.** | Put caches outside repo or ignore before first command. |
|
||||
| Tracked `docs/node_modules`, 2026-07-28 | Hundreds of pnpm symlink entries become repository content. | `docs/node_modules` neither ignored nor excluded from commit. | 237 entries at `HEAD`; no `.gitignore` rule. **Current/open.** | Track lockfiles, never installed trees. |
|
||||
| `308c199` cleanup regression, 2026-07-28 | `TestRunWrapsExternalCommand` returns `"\n"` instead of `"wrapped\n"`; forge compatibility removed again; dependency artifacts added. | Semantic edits classified and reviewed as cleanup. | Focused skillscript test fails at `HEAD`. **Current/open.** | No commit is "cleanup" for gating purposes. |
|
||||
| Tracked `docs/node_modules`, 2026-07-28 | Hundreds of pnpm symlink entries become repository content. | `docs/node_modules` neither ignored nor excluded from commit. | 237 entries at that time; the VitePress site was removed (`84b32694`) and `git ls-files | grep -c node_modules` is now **0**. **Settled.** | Track lockfiles, never installed trees. |
|
||||
| `308c199` cleanup regression, 2026-07-28 | `TestRunWrapsExternalCommand` returns `"\n"` instead of `"wrapped\n"`; forge compatibility removed again; dependency artifacts added. | Semantic edits classified and reviewed as cleanup. | The focused skillscript test **passes** as of 2026-09-16. **Settled.** | No commit is "cleanup" for gating purposes. |
|
||||
| `diff_cap_lines = 0` contradiction, introduced at project start | Operators set zero expecting unlimited, but decoded config becomes 400. | `finalize` converts zero to default 400; same sentinel means both "unset" and "unlimited." | **Current/open** contradiction. | Never overload zero value with both defaulting and explicit policy. |
|
||||
|
||||
## Keep unmerged work as dated candidates
|
||||
|
||||
As of **2026-07-28**, these remote branches are not merged:
|
||||
As of **2026-09-18**, the six `fix/4x` and `feat/5x`/`feat/75` candidate
|
||||
branches recorded here on 2026-07-28 no longer exist on either remote —
|
||||
`git branch -r --no-merged HEAD` reports only `gitea/main` (and the Dolt helper
|
||||
ref). Treat their concerns as `superseded` unless a live branch re-raises one.
|
||||
|
||||
| Candidate branch | Claimed concern |
|
||||
| Former candidate branch | Claimed concern |
|
||||
|---|---|
|
||||
| `origin/fix/43-loaddir-no-timeout-around-yaegi-eval-can-hang-daemon-startup` | Bound Yaegi evaluation during `LoadDir` |
|
||||
| `origin/fix/45-skillscriptrun-ignores-context-cannot-be-canceledtimed-out` | Make skill scripts cancellable |
|
||||
|
||||
@@ -5,8 +5,9 @@ description: "Run and observe Archie safely with a host daemon and the repositor
|
||||
|
||||
# Run and operate Archie
|
||||
|
||||
Use this runbook to operate the implementation that exists on **2026-07-28**.
|
||||
Treat source and tests as current; treat `docs/archive/` as history.
|
||||
Use this runbook to operate the implementation that exists on **2026-09-18**
|
||||
(HEAD `2e1e1549`). Treat source and tests as current; treat `docs/archive/` as
|
||||
history.
|
||||
|
||||
## Define the process shapes
|
||||
|
||||
@@ -62,7 +63,7 @@ Both linked binaries may also display Go's `-quickchecks` flag from
|
||||
|
||||
## Select the execution mode deliberately
|
||||
|
||||
| Config shape | What runs | Operational status on 2026-07-28 |
|
||||
| Config shape | What runs | Operational status on 2026-09-18 |
|
||||
|---|---|---|
|
||||
| `agent.mode = "inprocess"` and no `[nats]` | `archied` polls and claims from SQLite, runs workflow stages and model tools in-process. | **Production-wired candidate.** No process or OS isolation. |
|
||||
| `agent.mode = "subprocess"` | `archied` starts `agent.command` per stage and expects one JSON invocation on stdin, one response on stdout. | **Open/broken with default command.** `cmd/archie-agent` is a long-running NATS worker and never calls `agentexec.ServeOne`. |
|
||||
@@ -179,7 +180,7 @@ for `archie.task.>` and `archie.agent.>`.
|
||||
| Discovery | `archie.task.bug`, `.feature`, `.bootstrap`, or `.default`; daemon durable consumer `archie-daemon`, 5-min ack wait, max 3 deliveries. |
|
||||
| Per-stage requests | `archie.agent.<id>.request`; worker durable consumer defaults to `archie-agent`, 30-min ack wait, max 3 deliveries; response address in `X-Archie-Reply`. |
|
||||
| Container task | Core NATS request/reply on `archie.taskrun.<id>`. Task container reads `/data/worktree/.git/task.json` and creates dedicated subscription; shared worker uses queue group `archie-taskrun-workers`. |
|
||||
| Privileged RPC | Store, forge, and worktree operations return to `archied` over core NATS subjects in `internal/storerpc`, `internal/forgerpc`, and `internal/worktreerpc`. |
|
||||
| Privileged RPC | Store operations go to the gRPC State Store (`internal/infrastructure/staterpc`, task-scoped grants); forge and worktree operations return to `archied` over core NATS subjects in `internal/forgerpc` and `internal/worktreerpc`. |
|
||||
|
||||
Set `containers.network` explicitly. `deployments/docker-nats-stack.toml` uses
|
||||
`archie-core_default`. Auto-detection inspects the daemon container; on failure,
|
||||
@@ -195,8 +196,10 @@ It forwards only configured provider-key variables.
|
||||
Open limitations until code/tests prove otherwise:
|
||||
|
||||
- `subprocess` + default `archie-agent` is protocol-incompatible.
|
||||
- `config.production.toml` uses legacy `token_env`; validation requires
|
||||
`forge.token` secret reference.
|
||||
- A deployed overlay previously using legacy `token_env` still converts: the
|
||||
structured `forge.token` secret reference wins when both are present and
|
||||
`config.Forge.TokenEnv` is otherwise converted by
|
||||
`internal/infrastructure/configuration/defaults.go`.
|
||||
- Container RPC uses root forge/worktree for every identity.
|
||||
- Container orphan recovery lacks daemon-instance label.
|
||||
- `max_uptime` only bounds `Pool.Acquire` create/start; no lifetime timer.
|
||||
@@ -206,9 +209,12 @@ Open limitations until code/tests prove otherwise:
|
||||
|
||||
## Understand deployment and rollback seams
|
||||
|
||||
The Gitea workflow builds/pushes only `archied:latest` and `archie-agent:latest`.
|
||||
It injects component versions into labels/metadata but publishes no versioned
|
||||
tags. It runs no quality gate before Docker builds.
|
||||
`.github/workflows/deploy.yml` gates on the release tags, then builds/pushes
|
||||
`archied:latest` and `archie-agent:latest` plus a versioned
|
||||
`linux/amd64` distribution zip attached to a GitHub Release. It injects
|
||||
component versions into labels/metadata and runs the quality gate before the
|
||||
Docker builds. The Gitea workflow that used to be the production build path was
|
||||
dropped (`dd9bddc2`); `deployments/*.toml` are the supported profiles.
|
||||
|
||||
Before promotion: record running image IDs/digests; config checksums (no
|
||||
secrets); task counts via safe GET; establish a SQLite backup procedure.
|
||||
@@ -218,6 +224,6 @@ does not undo forge changes, task transitions, or data-format changes.
|
||||
|
||||
## Treat carina facts as unverified external state
|
||||
|
||||
Repository guidance (2026-07-28): two instances on `carina` with distinct
|
||||
Repository guidance (2026-09-18): two instances on `carina` with distinct
|
||||
`bot_user` values. No live process list, config, image digest, service manager,
|
||||
or deployment was verified. Do not invent SSH, systemd, or service commands.
|
||||
@@ -142,7 +142,8 @@
|
||||
"task_id",
|
||||
"attempt",
|
||||
"stage",
|
||||
"status"
|
||||
"status",
|
||||
"usage"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
@@ -257,7 +258,7 @@
|
||||
"type": "integer"
|
||||
},
|
||||
"height": {
|
||||
"description": "Height is the pixel height for images and video.",
|
||||
"description": "Height is the pixel height for images and video. nil means unknown\nor not applicable.",
|
||||
"type": "integer"
|
||||
},
|
||||
"mime_type": {
|
||||
@@ -268,6 +269,10 @@
|
||||
"description": "Path is a local filesystem path on the host that produced the\nattachment. It is the alternative to URL for outbound delivery: a\nURL is fetched by the platform, a Path is uploaded by us. A file the\nagent wrote has no URL and never gets one -- publishing it would\ntrade a delivery problem for a hosting and access-control one -- so\nsenders that support upload must read this.\n\nExactly one of URL and Path is meaningful for an outbound send.",
|
||||
"type": "string"
|
||||
},
|
||||
"raw": {
|
||||
"description": "Raw carries platform-specific fields the common vocabulary does not\ncover, so adapters never need a second attachment type.",
|
||||
"type": "object"
|
||||
},
|
||||
"type": {
|
||||
"description": "Type is \"image\", \"video\", \"audio\", or \"document\".",
|
||||
"type": "string"
|
||||
|
||||
Reference in new issue
Block a user