docs(prds): remove session-bound writing from every PRD

183 findings across 28 of 46 PRDs, of which 150 were file:line citations. Two
were already hard-broken: one named a file that no longer exists, one pointed
past the end of its file. The rest resolved to a line that still exists,
which is the worse failure -- a citation that silently drifted onto unrelated
code still reads as authoritative.

Citations now name the file and the symbol. Dated status markers become the
decision they carried ("Status 2026-09-05: resolved" -> "Resolved"), since
whether a question is answered is design information and when it was answered
is not. Progress inventories become scope statements: mcp-tool-completion now
fences what is out of scope rather than reporting what shipped.
status-health-surface drops phase-completion from its headings and keeps the
rule that earned them, that a reported field must have a truthful source.

eda-playbook-engine.md was the worst file and my own t2db.23 status block was
part of why; it is rewritten as the resolution it records.
This commit is contained in:
sam committed 2026-09-22 00:21:28 +10:00
1 parent fd8f180715
commit edce8fa1d8
27 files changed
+236 -248

No files matched your search

+10 -10
View File
@@ -4,7 +4,7 @@
**Date:** 2026-08-22, section 1 replaced 2026-08-25
**Beads issue:** `archie-core-h019.1`, blocks `h019.2/.3/.4/.5`
> **Section 1 was superseded on 2026-08-24 and re-decided on 2026-08-25.**
> **Section 1 is superseded by the decision below.**
> The original execution mechanism assumed daemon-owned in-process execution
> and a daemon-side second `Pool.Acquire`; `archie-core-q15y` removed both
> call sites, leaving one open question: how a fresh reviewer receives an
@@ -21,8 +21,8 @@ most of this.
## 1. Where it runs: `agent.Subagent`, inside the task worker
The implement workflow's stage list
(`internal/domain/workflow/implement.go:110-185`) already has the right slot:
after `StageDiffCap()` (line 178), before `StageOpenPR()` (line 179) -- gates
(`internal/domain/workflow/implement.go`) already has the right slot:
after `StageDiffCap()`, before `StageOpenPR()` -- gates
have passed, the diff is final, and nothing has told the forge about this
change yet.
@@ -37,7 +37,7 @@ host executor, no second `Pool.Acquire`, and no nested container lifecycle.
**Two isolations are needed, and Subagent only provides one of them.**
*Conversation isolation is structural, and free.* `Subagent.Run`
(`agent/subagent.go:76-96`) calls `GenerateText` with `Prompt` set and
(`agent/subagent.go`) calls `GenerateText` with `Prompt` set and
`Messages` never populated. The implementer's history has no code path into
the nested run; only the prompt string crosses, and only text comes back.
This is the literal form of "environmental enforcement over prompt rules":
@@ -95,7 +95,7 @@ no code path that hands it any.
## 3. Findings contract: `workflow.ReviewFinding`, workflow domain owns it
Not a reuse of `internal/gate.Finding` (`gate.go:22-31`), despite the similar
Not a reuse of `internal/gate.Finding` (`gate.go`), despite the similar
shape. That type belongs to the Yaegi gate contract (`.archie/gate.go`,
repo-owner-authored checks); coupling the review stage's blocking contract to
gate's evolution would violate "a domain declares the interface it needs, it
@@ -132,9 +132,9 @@ being asked to format its answer as JSON and trusted to comply.
The epic's acceptance criteria say a surviving finding "parks the task as
`waiting_human`," which names two different states in the actual machine
(`internal/taskstate/taskstate.go:44-59`). This decides between them:
(`internal/taskstate/taskstate.go`). This decides between them:
**`store.StatusParked`**, following `StageDiffCap`'s existing precedent
(`steps.go:91-94`) exactly -- a stage-computed policy stop with a `Detail`
(`steps.go`) exactly -- a stage-computed policy stop with a `Detail`
explaining why, before PR open. `Parked`'s available actions, retry and
abandon, are the right shape here: fix the flagged code and retry, or
abandon/override if a finding is a false positive. `WaitingHuman`'s
@@ -149,7 +149,7 @@ returns `nil`, so `StageOpenPR` runs next. Attaching warn-level findings to
the task record for PR-body/dashboard display is `h019.6`'s job, not decided
here.
**A review that fails to run is fail-closed** (decided 2026-08-25). The
**A review that fails to run is fail-closed.** The
blocking rule is `Verdict == confirmed && Level == error`, so only a confirmed
finding blocks -- but that governs findings, not the reviewer's own failure. A
sub-agent that errors, is truncated, or produces no conclusion yields
@@ -170,14 +170,14 @@ indistinguishable from a clean review, and fail-closed unimplementable.
**Model:** a new `"reviewer"` key in the existing `Config.Models` map (already
a generic `map[string]string`, no schema change) with the same single-level
fallback precedent `agent.go:68-73` already uses for planner->builder:
fallback precedent `agent.go` already uses for planner->builder:
`Models["reviewer"]`, falling back to `Models["builder"]` if unset. Operators
who want a genuinely independent second opinion configure a distinct model;
nothing forces one, because CLAUDE.md's project scope is "smallest change
that works," not a mandated model-diversity policy.
**Effort/budget:** reuse the per-stage budget override `AgentStage` already
supports (`agent.go:35`), not a new config surface -- a repo wanting a
supports (`agent.go`), not a new config surface -- a repo wanting a
cheaper or more thorough reviewer sets `MaxSteps` the same way
the plan stage already can. Map that budget onto `Subagent.MaxSteps` and
`Subagent.MaxTokens` deliberately: **`MaxTokens` is a per-call ceiling, not a
+4 -4
View File
@@ -91,7 +91,7 @@ notification.
### Destinations are configured, never named by a playbook
`[notify]` today is one webhook URL, read in one place
(`internal/domain/workflow/feasibility.go:134`). It becomes a set of named
(`internal/domain/workflow/feasibility.go`). It becomes a set of named
destinations. Each binds a name the operator chooses to a channel already
registered in the Messaging composition (`internal/app/archiemessaging/compose.go`
registers `telegram`, `email`, `webhook`) plus that channel's own address,
@@ -124,14 +124,14 @@ reject-at-load rule.
`archie-messaging` is its own process (`cmd/archie-messaging`). It dials out
to the Gateway and the State Store and serves nothing, and it deliberately
has no NATS connection: `internal/app/archiemessaging/telegram_features.go:65`
has no NATS connection: `internal/app/archiemessaging/telegram_features.go`
records that it "must not decode" the daemon's `[nats]` config. So a
notification cannot be pushed into it today by any route.
Delivery therefore travels the connection that already exists. Every process
that needs Messaging already dials the Gateway: `archied`
(`internal/app/archied/chat_service.go:25`), `archie-messaging`
(`internal/app/archiemessaging/run.go:26`) and `archie-ui`. The Gateway is the
(`internal/app/archied/chat_service.go`), `archie-messaging`
(`internal/app/archiemessaging/run.go`) and `archie-ui`. The Gateway is the
hub. A new server-streaming RPC on `ChatService` lets `archie-messaging`
subscribe at startup and receive notifications the daemon publishes; Messaging
then delivers through the named channel instance it already holds in
+8 -8
View File
@@ -29,7 +29,7 @@ useful. Three verified reasons, in order of weight:
rejects "a reflection-based schema over `config.Config`" because the struct is
"scheduled for dissolution". A generator deriving the example from its struct
tags would build on a foundation this repo has already decided to remove.
3. **`docs/architecture/generated-documentation.md:225` prohibits it.** "Adding
3. **`docs/architecture/generated-documentation.md` prohibits it.** "Adding
another hardcoded type list to `docsgen` is prohibited" — so any generator
must consume a domain-owned registry, which does not exist for configuration
yet. Creating one is the config-domain migration's job, not this change's.
@@ -42,7 +42,7 @@ machinery to remove duplication that largely is not there.
## The gap that is real
**Unknown config keys are silently ignored.** Verified at
`internal/infrastructure/configuration/decode.go:27`:
`internal/infrastructure/configuration/decode.go`:
```go
if _, err := toml.DecodeFile(path, target); err != nil {
@@ -55,7 +55,7 @@ is also detectable **without any hand-maintained list**, because `BurntSushi/tom
reports exactly which keys the target did not consume.
Note the second, separate gap already admitted in writing:
`generated-documentation.md:331` — "`task check` does not run `docs:check`, so
`generated-documentation.md` — "`task check` does not run `docs:check`, so
generated drift is currently ungated."
## What to build
@@ -68,7 +68,7 @@ keys, and expose it so tests can assert emptiness.
startup policy is "a missing credential disables a capability; only an invalid
config stops the daemon". A stray key is far more likely to be an operator typo
in a file they are otherwise happy with than a reason to refuse to boot, and
`[web]` is already documented as landing in a *different* binary
`[web]` is documented as landing in a *different* binary
(`internal/app/archieui`), so a key unknown to one process is legitimately known
to another. Failing closed here would break working deployments on upgrade.
@@ -102,13 +102,13 @@ deferred, not rejected.
## A withdrawn premise, recorded so it is not reused
An earlier measurement in this session claimed 17 keys were "set by a profile
but documented by no example", and used it to argue for generation. It was an
An earlier measurement claimed 17 keys were "set by a profile but documented
by no example", and used it to argue for generation. It was an
artifact: the extractor stripped comment markers and tracked a single table
variable, so commented blocks were mis-attributed. Re-checking refuted it —
`providers.<name>.api_key_env` is a real, documented backwards-compatible field
(`internal/config/config.go:180`, `config.example.toml:101`) and `[[identities]]`
is documented at `config.example.toml:53`. The decision above does not rest on
(`internal/config/config.go`, `config.example.toml`) and `[[identities]]`
is documented at `config.example.toml`. The decision above does not rest on
that measurement.
## Acceptance criteria
+1 -1
View File
@@ -131,7 +131,7 @@ text into fixtures, two that asserted on a source file's contents). All six were
deleted on 2026-09-15. The dashboard suite's "api.jsx holds exactly one fetch
call" check was deleted for the same reason: it broke on a reformat and on a
comment that mentioned `fetch`, and it was patched with a comment-stripper instead
of being removed. Every `api.*` method is now covered behaviourally instead, by
of being removed. Every `api.*` method is covered behaviourally instead, by
asserting the headers and body each one sends.
## Open decision
+1 -1
View File
@@ -92,7 +92,7 @@ the settings page would show a dead process as current.
`docs/prds/status-health-surface.md` faced the same choice and stamped the start
of a poll pass so a wedged poller reads as stale rather than healthy.
Settled 2026-09-21: the re-stamp above. The alternatives considered were
Settled: the re-stamp above. The alternatives considered were
carrying the instance identity generated at process start, which detects a
restart but not a death, and accepting the limitation with the page saying so.
+3 -4
View File
@@ -2,10 +2,9 @@
**Status:** Approved for implementation
**Date:** 2026-09-05
**Beads issue:** none yet at time of writing (bead `archie-core-1786637500776-416-600a66e5`
/ GitHub #437 covers the embedding-backed follow-on strategy only; this PRD
covers the prerequisite interface + cheap strategies, tracked by the new
issue this change files, see `new-issues.jsonl`)
**Beads issue:** bead `archie-core-1786637500776-416-600a66e5` / GitHub #437
covers the embedding-backed follow-on strategy only. This PRD covers the
prerequisite interface and the cheap strategies.
**Parent epic:** `archie-core-1786637500725` (curator engine)
**Depends on:** nothing shipped (this is itself a prerequisite)
**Blocks:** the embedding-backed surprisal strategy (GitHub #437), which
+15 -15
View File
@@ -17,18 +17,18 @@ Every claim in this document is mapped to what exists in the tree today.
| `web_fetch` tool (URL → readable text) | **Implemented** | `internal/tools/webfetch/{tool.go,webfetch.go}`; registered in `internal/app/archied/bootstrap.go` `registerStandaloneTools`, disabled-by-config returns `nil` |
| **Web search** (query → result list) | **Aspirational — zero code** | No search provider, no search tool, no config block anywhere in the tree or in `ai-sdk` v0.1.32 |
| `agent.Subagent` — nested agent in a fresh context window | **Implemented** (dependency) | `github.com/samcharles93/ai-sdk@v0.1.32/agent/subagent.go`. Synchronous, non-streaming, own model/system/toolset, `MaxSteps` defaults to 10, nesting depth capped at 5, returns final text only |
| Subagent used in production | **Implemented, one consumer** | `internal/app/agentworker/review.go:112` — the adversarial reviewer. That is the only non-test use of `Subagent` in the repo |
| Subagent used in production | **Implemented, one consumer** | `internal/app/agentworker/review.go` — the adversarial reviewer. That is the only non-test use of `Subagent` in the repo |
| A **delegate/subagent tool** on the chat surface | **Aspirational — zero code** | No `subagent`/`delegate` tool name is registered anywhere |
| **Fan-out orchestration** (N missions, one collator) | **Aspirational — zero code** | `agentloop`'s package doc states it runs *one* mission: "orchestration across missions lives with the caller". No caller does this yet |
| Parallel-safe tool execution | **Aspirational — zero code** | The unreachable `internal/tools/dispatch.go` dispatch/gating engine (`ExecutionClass`, `DispatchSequential`/`DispatchConcurrent`/`ClassifyEntry`) was deleted as dead code (tools-core-1); live concurrency is ai-sdk's `GenerateOptions.MaxParallelToolCalls`, which archie-core never sets |
| Per-result caps + spill-to-disk | **Implemented** | `internal/agentexec/toolset.go` `ToolLimits{MaxResultChars,SpillDir}`, applied in `toolExecute` via `tools.CapPayload` (`limit.go:44`); no **aggregate** turn cap by design (`toolset.go:62`). `config.ToolPolicy.SpillDir`; default cap 50k chars, spill dir deliberately not defaulted |
| Tool guardrails (repeat-failure / no-progress) | **Implemented, not on the call path** | `internal/tools/guardrail.go` engine exists. Its only non-test caller is `dispatchOne` — which is itself unreachable — so **the chat path never consults it**, and the agent path only records per *stage* (`domain/workflow/agent.go:199`) |
| Structured capture tools (model reports into a typed store, not prose) | **Implemented** | `internal/app/agentworker/review.go:247` `record_finding` / `record_checked` — `core.NewTypedTool` appending to a caller-owned slice. This is the pattern a research source ledger should reuse |
| Curator engine (interval, declared tool set, lifecycle) | **Implemented, tools broken** | `internal/domain/curator`; a curator declaring tools is **refused** at registration (`registry.go:123`, no `ToolBuilder` implementation) and `curatorLLMRunner` (`internal/app/archied/main.go:551`) drops `ChatRequest.Tools`. Budgets are time+concurrency only (`runtime.go:14,64`) — **no token budget** |
| Cron / scheduling + delivery router | **Implemented, wired into no binary** | `internal/domain/scheduling`, `internal/infrastructure/cronstore` (schema v2, `Kind` discriminator), `internal/infrastructure/crondelivery` — all present and green, but `go list -deps` for every `cmd/` contains none of them, and `cron`-expression firing arithmetic is unimplemented (`schedule.go:110`, "slice 2"). `ARCHITECTURE.md:397` still asserts "**No daemon-internal cron.**" |
| Workflow engines (multi-stage, resumable) | **Implemented, worktree-bound** | `internal/domain/workflow` — every non-triage workflow opens with `StagePrepareWorktree()` and mounts `tc.Dir` into a container; the task persists after every stage (`workflow.go:295`). `triage.go:33` documents there is "no cheaper directory-less classification primitive" |
| Long-running chat-initiated work with progress | **Partial** | Chat turns run **once, synchronously**, inline in the channel's turn runner (`internal/gateway/turn.go:357`). Chat can spawn a *workflow task* (`task_spawn`) which is asynchronous — but that path is worktree/PR-shaped |
| **Operator-push delivery of an async result** | **Aspirational — zero code** | Nothing pushes a finished result to a chat. No channel subscribes to the event bus (Telegram only *publishes* `KindTurnCompleted`); `crondelivery.Courier` is the intended seam but has **no implementation and no caller**; `send_file` works only inside the live turn. The one out-of-band notification in the tree is feasibility's n8n webhook (`feasibility.go:133`) |
| Per-result caps + spill-to-disk | **Implemented** | `internal/agentexec/toolset.go` `ToolLimits{MaxResultChars,SpillDir}`, applied in `toolExecute` via `tools.CapPayload` (`limit.go`); no **aggregate** turn cap by design (`toolset.go`). `config.ToolPolicy.SpillDir`; default cap 50k chars, spill dir deliberately not defaulted |
| Tool guardrails (repeat-failure / no-progress) | **Implemented, not on the call path** | `internal/tools/guardrail.go` engine exists. Its only non-test caller is `dispatchOne` — which is itself unreachable — so **the chat path never consults it**, and the agent path only records per *stage* (`domain/workflow/agent.go`) |
| Structured capture tools (model reports into a typed store, not prose) | **Implemented** | `internal/app/agentworker/review.go` `record_finding` / `record_checked` — `core.NewTypedTool` appending to a caller-owned slice. This is the pattern a research source ledger should reuse |
| Curator engine (interval, declared tool set, lifecycle) | **Implemented, tools broken** | `internal/domain/curator`; a curator declaring tools is **refused** at registration (`registry.go`, no `ToolBuilder` implementation) and `curatorLLMRunner` (`internal/app/archied/main.go`) drops `ChatRequest.Tools`. Budgets are time+concurrency only (`runtime.go`) — **no token budget** |
| Cron / scheduling + delivery router | **Implemented, wired into no binary** | `internal/domain/scheduling`, `internal/infrastructure/cronstore` (schema v2, `Kind` discriminator), `internal/infrastructure/crondelivery` — all present and green, but `go list -deps` for every `cmd/` contains none of them, and `cron`-expression firing arithmetic is unimplemented (`schedule.go`, "slice 2"). `ARCHITECTURE.md` still asserts "**No daemon-internal cron.**" |
| Workflow engines (multi-stage, resumable) | **Implemented, worktree-bound** | `internal/domain/workflow` — every non-triage workflow opens with `StagePrepareWorktree()` and mounts `tc.Dir` into a container; the task persists after every stage (`workflow.go`). `triage.go` documents there is "no cheaper directory-less classification primitive" |
| Long-running chat-initiated work with progress | **Partial** | Chat turns run **once, synchronously**, inline in the channel's turn runner (`internal/gateway/turn.go`). Chat can spawn a *workflow task* (`task_spawn`) which is asynchronous — but that path is worktree/PR-shaped |
| **Operator-push delivery of an async result** | **Aspirational — zero code** | Nothing pushes a finished result to a chat. No channel subscribes to the event bus (Telegram only *publishes* `KindTurnCompleted`); `crondelivery.Courier` is the intended seam but has **no implementation and no caller**; `send_file` works only inside the live turn. The one out-of-band notification in the tree is feasibility's n8n webhook (`feasibility.go`) |
| Citation storage / source ledger | **Aspirational — zero code** | No source, citation, or provenance store exists for research output |
> **Target state, not current state.** Everything marked aspirational below is
@@ -199,7 +199,7 @@ Reusing it would mean every ad-hoc research run leaves a permanent job row.
| Report renderer | `internal/domain/research` | Markdown + numbered citation list rendered **from the store** |
| Chat trigger | slice 2: `internal/tools/research`; slice 3: gateway tool + courier in `internal/app/archied` | — |
| Durable run + delivery (slice 3) | `internal/domain/research` + `internal/infrastructure/research` + `internal/app/archied` wiring | Follows the strict plugin-engine rule in `ARCHITECTURE.md` ("Plugin engine
rule (strict)", line 293): typed contract, owning registry with start/health/stop, narrow typed registrar |
rule (strict)"): typed contract, owning registry with start/health/stop, narrow typed registrar |
### Why not the curator
@@ -209,7 +209,7 @@ Two facts rule it out as the host for *this*:
- **Its tool path does not work.** A curator declaring tools is refused
registration because `ToolBuilder` has no implementation, and even if it were
bound, `curatorLLMRunner` drops `ChatRequest.Tools` (`main.go:551`). Fixing
bound, `curatorLLMRunner` drops `ChatRequest.Tools` (`main.go`). Fixing
that is `archie-core-trnd.1`, an independent piece of work.
- **Its contract is maintenance, not requests.** The isolation invariant
(`docs/architecture/agent-system.md`, "Curator isolation invariant") defines
@@ -224,7 +224,7 @@ weekly" — but it is a consumer of this capability, not its foundation.
### D1. Citations come from a store, never from prose
Each subagent gets a `record_source` typed tool (the `record_finding` pattern,
`review.go:247`) whose handler canonicalises the URL, deduplicates against the
`review.go`) whose handler canonicalises the URL, deduplicates against the
store, marks which sub-question recorded it, and appends. The collator may
*select and order* sources; it may not author them. Rendering the reference
list is then a pure function of the store.
@@ -254,7 +254,7 @@ benefit does not.
Fan-out width and per-child `MaxSteps` are enforced by the orchestrator, not
requested in a prompt, against a whole-run wall clock and token ceiling.
`agentloop.Budget` already carries `MaxSteps`, `MaxTokens`, `WallClock`, and
`TokenBudgetIs(maxTokens)` exists as a stop condition (`agentloop.go:373`) —
`TokenBudgetIs(maxTokens)` exists as a stop condition (`agentloop.go`) —
the shape exists, the fan-out owner does not.
**Fan out retrieval aggressively and generation sparingly.** Web search is 73%
@@ -281,7 +281,7 @@ effective capacity without a bigger context window.
`web_search` is registered only when a provider resolves, following two
existing conventions: return `nil` for a disabled capability
(`webfetch/tool.go:18` — "an advertised tool that never works costs a round
(`webfetch/tool.go` — "an advertised tool that never works costs a round
trip") and resolve the credential *before* registering
(`registerMinimaxTool`, `bootstrap.go`). At least two implementations are
wanted — a self-hosted meta-search endpoint (no per-query cost, no data egress)
@@ -359,7 +359,7 @@ evidence-supported trade.
- **Collator degradation.** If the collator call fails or truncates, the report
must still be rendered from the source store and the child conclusions —
degraded, not empty. This mirrors the reviewer's rule that findings captured
before a failed run are still real (`review.go:129`).
before a failed run are still real (`review.go`).
## Slices
+7 -7
View File
@@ -18,15 +18,15 @@ Every claim in this document is mapped to what exists in the tree today.
| Two reference curators run through the registry | **Implemented** | `internal/infrastructure/skillcurator`, `internal/infrastructure/sessioncurator` |
| Curator definitions as persisted, API-editable data | **Aspirational -- zero code** | No table, no entity, no RPC, no config block |
| Generic definition-driven engine that executes a declared tool set + free-form instructions | **Aspirational -- zero code** | Only the two code-registered curators exist |
| `Registrar.Tools` (`ToolBuilder`) resolved and bound at registration | **Partial** | Interface declared (`registrar.go:86`); **no implementation anywhere**; `bootstrap.go` builds the `Registrar` with no `Tools` field |
| A curator can declare tools at all | **Partial** | `Manifest.Tools` exists, but `registry.go:123` fails registration with `"curator manifest: declares tools but the registrar has no ToolBuilder"` |
| Curator passes that actually reach a model with tools | **Cosmetic only** | `curator.ChatRequest` carries `Tools`/`MaxSteps`; `curatorLLMRunner` (`internal/app/archied/main.go:551`) drops both and returns `ChatResult{Text}` only |
| `Registrar.Tools` (`ToolBuilder`) resolved and bound at registration | **Partial** | Interface declared (`registrar.go`); **no implementation anywhere**; `bootstrap.go` builds the `Registrar` with no `Tools` field |
| A curator can declare tools at all | **Partial** | `Manifest.Tools` exists, but `registry.go` fails registration with `"curator manifest: declares tools but the registrar has no ToolBuilder"` |
| Curator passes that actually reach a model with tools | **Cosmetic only** | `curator.ChatRequest` carries `Tools`/`MaxSteps`; `curatorLLMRunner` (`internal/app/archied/main.go`) drops both and returns `ChatResult{Text}` only |
| Dynamic registration / removal (no restart) | **Aspirational -- zero code** | `Registry` has `Register`, no `Unregister`; `Runtime` has `Start`/`Nudge`/`Stop`, no `Add`/`Remove`; `Start()` snapshots membership |
| Curator definition CRUD over REST | **Partial** | `GET /api/curators` read-only (`internal/webui/server.go:226`); no write routes |
| Curator definition CRUD over REST | **Partial** | `GET /api/curators` read-only (`internal/webui/server.go`); no write routes |
| Curator definition config | **Aspirational -- zero code** | No `[curator]` block in `internal/config/config.go` |
| Store/API as definition authority | **Aspirational -- zero code** | No curator persistence of any kind |
| No live-path defaults for interval/cooldown/tools/model/memory engine | **Partial** | `skillcurator.DefaultInterval` / `sessioncurator.DefaultInterval` are Go consts read at registration; `curator.NewRuntime(..., RuntimeConfig{})` uses code defaults for pass timeout and concurrency |
| Idle curators are observable in logs | **Partial** | `runtime.go:202-211` logs nothing when `Check` reports not-due; the session-memory curator's hourly pass is the only curator activity ever logged |
| Idle curators are observable in logs | **Partial** | `runtime.go` logs nothing when `Check` reports not-due; the session-memory curator's hourly pass is the only curator activity ever logged |
| Sampler family | **Implemented** | `internal/domain/sampling`, shipped; no curator consumes a `Sampler` yet |
| Forge/issue reach from chat | **Implemented** (via `shell`) | No dedicated issue tool exists, but the chat agent's `shell` is unconfined (`chat.unrestricted_filesystem = true`), so `gh issue edit|comment|create|close` works today. Dedicated tools (#161) are convenience, not a blocker |
@@ -36,7 +36,7 @@ Every claim in this document is mapped to what exists in the tree today.
## Problem
A curator exists today only if a Go package implements `curator.CuratorEngine`
and `bootstrap.go:1022/1025` names it in a `Register` call. Nothing about a
and `bootstrap.go/1025` names it in a `Register` call. Nothing about a
curator is definable as data. Worse, no curator can declare a tool set at all:
the `ToolBuilder` interface has no implementation in the repo, so the registry
refuses (correctly, fail-closed) any curator that declares tools -- and the
@@ -99,7 +99,7 @@ record actions.
implementation fails the pass rather than silently running with fewer tools.
This is the enforcement point, and it is why the `ToolBuilder` binding is
load-bearing rather than a convenience: without an implementation, no curator
can declare tools at all (today's `registry.go:123` guard).
can declare tools at all (today's `registry.go` guard).
2. **Tool-carrying model call.** `curator.ChatRequest` already carries
`Tools []tools.ToolEntry` and `MaxSteps`; `curatorLLMRunner` must pass them
into `core.GenerateOptions` (which has `Tools`, `ToolChoice`, `MaxSteps`, and
+5 -5
View File
@@ -6,7 +6,7 @@ heaviest workflow.
## Problem
`Route()` (`internal/domain/workflow/workflow.go:254`) has exactly two real
`Route()` (`internal/domain/workflow/workflow.go`) has exactly two real
signals today: an explicit `t.Workflow`, and label matches via
`workflowForLabels` (`routing.go`, `bug`→tdd, `feature`→feasibility,
bootstrap→bootstrap). Anything else — which is every chat-spawned task,
@@ -16,11 +16,11 @@ commit-push → review → open-pr` pipeline, regardless of what the task
actually asks for.
`task_spawn`'s own tool schema overpromises: *"workflow: … Omit to let the
daemon route it"* (`internal/gateway/task_tools.go:240`) implies real
daemon route it"* (`internal/gateway/task_tools.go`) implies real
routing exists. It doesn't — "route" currently means "check labels, then
give up and run the heaviest workflow anyway."
Confirmed in production (task 6, 2026-09-02): a chat-spawned task whose
Confirmed in production: a chat-spawned task whose
entire content was "this is just a test, close it when you receive it" ran
the full `implement` pipeline end to end — 669,421 tokens, ~7 minutes —
when nothing about the request needed a worktree-driven build at all. The
@@ -66,7 +66,7 @@ and decide, via a captured `decide` tool call:
```
`needs_code_change: false` → close path: reuse `closeNoChangesIssue`
(`steps.go:67`) directly — issue closed if forge-backed, task marked
(`steps.go`) directly — issue closed if forge-backed, task marked
`StatusMerged`/`"completed -- no changes required"` otherwise. No baseline,
no plan, no build, no commit, no PR. This is the actual fix for the
production incident: a no-op request now costs one classification call
@@ -77,7 +77,7 @@ chosen workflow (`implement`/`tdd`/`feasibility`, defaulting to
`implement` if the field is missing or unrecognized) and an Outcome that
requeues the task under it, the same requeue mechanism
`chatTaskControllerAdapter.ApproveChatTask` already uses
(`main.go:529`, `requeue(ctx, taskID, fromStatus, workflow)`). The task then
(`main.go`, `requeue(ctx, taskID, fromStatus, workflow)`). The task then
re-enters `Route()` on its next claim with `t.Workflow` now set, and takes
the normal path for that workflow from there — triage never runs its
classification twice for the same task.
+61 -70
View File
@@ -163,7 +163,7 @@ a case that should just be visible and fixed by a human. Instead:
flags duplicate or conflicting trigger definitions *within* a single
maintained tree before merge.
**Status 2026-09-03: lint mode shipped (t2db.12).** A standalone
**Resolved** (`archie-core-t2db.12`). A standalone
gopls-shaped binary (`cmd/archie-playbooks`, lint subcommand) validates
playbook directories against the exact loaders the daemon uses
(`LoadPlaybookDirs`/`LoadKindWorkflowsYAML`/`LoadLabelWorkflowsYAML`),
@@ -210,7 +210,7 @@ rule's spirit of narrow capability families -- so the answer is not
"bundle or don't," it's "don't duplicate the logic, and pick the thinnest
consumer for each caller's actual constraint."
## Execution-time gaps (identified 2026-09-03; both resolved 2026-09-05)
## Execution-time gaps (both resolved)
Everything above covers *loading* a playbook. Nothing above covers what
happens while one *runs*. Two gaps, both load-bearing enough to resolve
@@ -218,7 +218,7 @@ before implementation, not defer:
### 1. Mid-playbook action failure
**Status 2026-09-05: resolved by archie-core-t2db.18.** The default below
**Resolved** (`archie-core-t2db.18`). The default below
is a committed decision, not a candidate list; changing it later would
require its own decision. Gap 2 below is resolved by `archie-core-t2db.17`.
@@ -227,7 +227,7 @@ action 2 of 4 fails at runtime (an image-gen API times out, a forge call
403s), the doc previously said nothing about what happens next. This
codebase already answers a structurally identical question for its
existing workflow engine, precisely enough to reuse rather than
re-derive: `workflow.Run` (`internal/domain/workflow/workflow.go:294`)
re-derive: `workflow.Run` (`internal/domain/workflow/workflow.go`)
draws a three-way distinction on a stage failure, and a playbook run
draws the same one on an action failure.
@@ -245,7 +245,7 @@ are the complete decision; reasoning and evidence follow each.
as a background log line only (this document's Dedup section, lines
155-159, the t2db.9-12 drop-and-report rule). `Run` is the mechanical
precedent for the stop itself: a stage error sets the park reason and
returns without running further stages (`workflow.go:324-326`). This
returns without running further stages (`workflow.go`). This
is stop-on-first-failure, matching the document's existing bias
against clever automatic recovery, and it is now a stated decision
rather than a nobody-chose default.
@@ -253,7 +253,7 @@ are the complete decision; reasoning and evidence follow each.
!= nil`) is explicitly **not** a failure. `Run` already treats this
case specially -- "Daemon shutdown is not a workflow failure. Leave
the task running ...; parking here would publish a false failure and
require manual intervention" (`workflow.go:317-323`) -- and the same
require manual intervention" (`workflow.go`) -- and the same
reasoning applies to a playbook run: an in-flight dispatch interrupted
by restart must not be recorded as a broken playbook. What "leave it
alone for restart" means for a playbook run (there is no `store.Task`
@@ -264,7 +264,7 @@ are the complete decision; reasoning and evidence follow each.
error, but nothing was assigned to happen) is itself an error
condition, matching `Run`'s own "a workflow must end with an explicit
outcome; not doing so is a definition bug, which still must not vanish
silently" (`workflow.go:336`). A playbook with actions that all ran
silently" (`workflow.go`). A playbook with actions that all ran
but never reached a coherent terminal state is a definition bug in the
playbook, reported as such.
@@ -278,10 +278,10 @@ undo.
**Producer-only interaction, stated explicitly -- why this decision does
not violate the rule.** `event-sources-and-reactions.md`'s producer-only
rule is "no veto, no mutation of in-flight work"
(`event-sources-and-reactions.md:61-63`), and it explicitly routes any
(`event-sources-and-reactions.md`), and it explicitly routes any
reaction that "can veto or mutate an *in-flight* task (block a PR from
opening, alter a running stage)" away from this epic to the
adversarial-self-review one (`event-sources-and-reactions.md:78-81`).
adversarial-self-review one (`event-sources-and-reactions.md`).
This decision touches neither half of that boundary:
- **The rule constrains what an event source may do to *someone else's*
@@ -294,12 +294,12 @@ This decision touches neither half of that boundary:
- **Everything after the stop is still producer-only.** The failed run is
reported to its caller per the collision precedent, the same way `Run`
records the failure on its own unit -- park reason set and the task
transitioned to `StatusParked` (`workflow.go:324-326`, `park` at
`workflow.go:351-357`) -- never on someone else's in-flight work. A
transitioned to `StatusParked` (`workflow.go`, `park` at
`workflow.go`) -- never on someone else's in-flight work. A
future compensating action (e.g. "if the notify action failed, also
log an incident") would be **producing new work** -- new events, new
dispatches -- which is exactly the already-permitted shape
(`event-sources-and-reactions.md:73-76`). No playbook syntax for "on
(`event-sources-and-reactions.md`). No playbook syntax for "on
failure, also run X" is designed here; this resolution only confirms
that if that syntax is added later, it stays inside the producer-only
boundary rather than requiring a new exception.
@@ -321,7 +321,7 @@ action-invocation code path and show they use different outcomes.
### 2. Idempotency at execution time
**Status 2026-09-05: resolved** (per bead `archie-core-t2db.17`, a
**Resolved** (`archie-core-t2db.17`, a
design-investigation ticket: resolve, do not implement). The decision
below is the answer; the keying scheme itself is separate follow-up work
and is intentionally not built here. It **extends**
@@ -341,13 +341,13 @@ One correction to the problem statement, checked against the code rather
than assumed, because it changes what the answer must be:
**`PublishUnique`'s dedup is not a consumer-redelivery guard at all.**
`PublishUnique` only sets the JetStream `Nats-Msg-Id` header on the
outgoing message (`internal/infrastructure/eventbus/nats/publisher.go:18-23`;
key constant `message.go:11-13`); JetStream suppresses *republished*
outgoing message (`internal/infrastructure/eventbus/nats/publisher.go`;
key constant `message.go`); JetStream suppresses *republished*
messages carrying a repeated key inside `Config.DedupWindow`
(`client.go:67`, `Duplicates: cfg.DedupWindow`), default 2 minutes
(`config.go:15`, `DefaultDedupWindow = 2 * time.Minute`). A consumer
(`client.go`, `Duplicates: cfg.DedupWindow`), default 2 minutes
(`config.go`, `DefaultDedupWindow = 2 * time.Minute`). A consumer
redelivery is the same *stored* message re-delivered on Nak or
acknowledge-timeout (`internal/eventbus/eventbus.go:64-65`: "a handler
acknowledge-timeout (`internal/eventbus/eventbus.go`: "a handler
returning an error causes redelivery") -- not a republish; its
`Nats-Msg-Id` is never re-firewalled, and even if it were, two minutes is
not an at-most-once guarantee for a side effect that must never repeat.
@@ -377,7 +377,7 @@ would already be wrong.
**Storage/lookup: a new durable ledger table `playbook_dispatches` in
`internal/store`, copying `binding_dispatches`'s conventions exactly**
(durable table, `INSERT OR IGNORE`, sentinel error, rows freed with
their parent, survives daemon restarts -- `internal/store/bindings.go:31-37`,
their parent, survives daemon restarts -- `internal/store/bindings.go`,
`355-382`):
```sql
@@ -392,21 +392,21 @@ CREATE TABLE playbook_dispatches (
```
Written with the same `INSERT OR IGNORE` + sentinel-error convention
(`ErrAlreadyDispatched`, `bindings.go:59-63`), so a duplicate is a no-op
(`ErrAlreadyDispatched`, `bindings.go`), so a duplicate is a no-op
write rather than a constraint error, and the caller matches it with
`errors.Is` the way the binding dispatch loop already does
(`internal/daemon/daemon.go:591-597` -- "another cycle already won this
(`internal/daemon/daemon.go` -- "another cycle already won this
race," not an error to surface). The record is consumed by the playbook
coordinator at dispatch time through a domain-side interface implemented
by `internal/store` -- the same shape as `BindingDispatcher`
(`internal/store/interface.go:123-139`) -- and the table lands in the
store's schema application (`internal/store/store.go:137-139`). No change
(`internal/store/interface.go`) -- and the table lands in the
store's schema application (`internal/store/store.go`). No change
to `internal/eventbus`; no per-message dedup state on the client.
**Lifetime: no time-based expiry.** Rows live as long as their playbook
exists; when a playbook is removed from the configured directories, the
coordinator deletes its rows -- mirroring binding-dispatches-rows-deleted-
with-binding (`bindings.go:204-214`, same transaction as the delete). The
with-binding (`bindings.go`, same transaction as the delete). The
at-most-once guarantee must not silently decay, which is exactly the
property that disqualifies `DedupWindow` above; table growth is bounded
by distinct (playbook, event, action) pairs over the playbook's lifetime
@@ -417,7 +417,7 @@ A detected duplicate is not re-invoked, is not reported to the caller as
an error, and is logged at debug level rather than as a warning -- this
is the expected, correct behavior of at-least-once delivery, not an
anomaly (same treatment as `ErrAlreadyDispatched` at
`daemon.go:592-597`).
`daemon.go`).
The run continues with the next action (or ends, for a single-action
playbook whose one action is recorded), which is what makes a redelivery
a resume rather than a dead restart.
@@ -428,32 +428,27 @@ computed by the coordinator -- not a CEL expression.** The key is the
- `playbook_id` is `Playbook.ID` -- the playbook file's path relative to
its configured directory root, slash-normalized, unique within the load
composition by construction (`internal/domain/eda/playbook/playbook.go:39-45`,
`149-155`). Note this prerequisite already landed in code: the earlier
draft's "not yet decided in code" paragraphs are stale --
`edd689e` (`feat(eda): thread Playbook ID/Version and DispatchInput task
identity (gap-2 prereqs)`) shipped `Playbook.ID`/`Version` and
`DispatchInput.TaskID`.
composition by construction (`internal/domain/eda/playbook`).
- `playbook_version` is `Playbook.Version` -- a SHA-256 of the loaded
file, recomputed on every load (`playbook.go:46-49`, `154-155`),
file, recomputed on every load (`playbook.go`, `154-155`),
mirroring `Binding.Version`'s provenance-pinning purpose: the dispatch
is pinned to the exact definition that was active when it fired. A
changed playbook definition is a different key and may fire again for
the same event -- deliberate, not a bug.
- `event_id` is `DispatchInput.TaskID` (`playbook.go:214-222`), which
- `event_id` is `DispatchInput.TaskID` (`playbook.go`), which
carries the `TaskEnvelope.IdempotencyKey()` value
(`"archie:" + owner/repo/number`,
`internal/domain/workintake/envelope.go:105-107`). It is chosen over
`internal/domain/workintake/envelope.go`). It is chosen over
`store.Task.ID` because the trigger vocabulary is issue-level
workintake label/kind, dispatched at discovery time (pollNATS, forge
webhook receiver), where no task row exists yet (`playbook.go:214-222`
comment; `playbook_test.go:338-345`: "the value available at the
webhook receiver), where no task row exists yet (`playbook.go`
comment; `playbook_test.go`: "the value available at the
discovery/dispatch point... NOT a store.Task.ID int64"). Keying on the
issue identity rather than the delivery source is the load-bearing
property the existing contract already established for `TaskEnvelope`
(`event-sources-and-reactions.md` question 4: a webhook-sourced
envelope for the same issue produces the *same* idempotency key as a
poll-discovered one; `internal/forge/webhook/receiver.go:14-20` --
poll-discovered one; `internal/forge/webhook/receiver.go` --
"Idempotency is not this package's job"); this resolution inherits that
property rather than re-deciding it. Consequence, stated explicitly:
same-issue re-discoveries (a re-label that re-triggers the same kind)
@@ -498,10 +493,10 @@ identity, per the per-trigger-type rule. }
**Record-before-invoke -- one deliberate divergence from
`binding_dispatches`, justified by the harm profile.** The binding
dispatch loop enqueues the task first and records the ledger row after
(`daemon.go:585-599`), accepting that racing cycles may both enqueue
(`daemon.go`), accepting that racing cycles may both enqueue
("the duplicate task remains queued... delete-on-races is its own can of
worms"); the selection query excludes already-dispatched captures
(`bindings.go:395-399`), but the race window remains. That ordering is
(`bindings.go`), but the race window remains. That ordering is
correct there because the duplicate artifact is an internal task row --
recoverable, low-harm. The playbook ledger's ordering is reversed on
purpose: **the row is written and committed before the action's side
@@ -566,7 +561,7 @@ document's sections:
**Scope: this is the `channel`/`forge`/`module` decision, not a
`workflow`-position change.** Workflow-kind actions keep their existing
keying claim unchanged -- the `TaskEnvelope` path that this document
already inherits for free (`daemon.go:858-869`, `PublishTask` publishes
already inherits for free (`daemon.go`, `PublishTask` publishes
with `task.IdempotencyKey()`), with its cross-poll/webhook property
untouched. The ledger gate applies to the side-effecting positions
(channel, forge, module), which is why the closing statement below
@@ -591,7 +586,7 @@ are unblocked on the execution-time questions.
checking, e.g. anything backing gate conditions), or a bespoke minimal
grammar? Not decided here.
**Status 2026-09-03: resolved.** CEL (cel.dev/cel-go) is the single
**Resolved.** CEL (cel.dev/cel-go) is the single
mechanism for both halves. The resolution below replaces this entry
and is not an open question. Judgment calls are flagged inline.
@@ -856,7 +851,7 @@ are unblocked on the execution-time questions.
imports; owned by the playbook engine family. One new dependency:
`cel.dev/cel-go` (pinned), `go.mod` otherwise unchanged.
- Consumption: the playbook event coordinator (open question 4's
loader, not yet built) evaluates `when` before dispatch and
loader) evaluates `when` before dispatch and
evaluates `args` values before `Module.Invoke`; the lint tool
(t2db.12) shares the same compile/validate path for author-time
diagnostics.
@@ -871,7 +866,7 @@ are unblocked on the execution-time questions.
directory or a list (mirroring `SkillsDir`'s shape) -- follow existing
config precedent, not invented fresh.
**Status 2026-09-03: partially resolved.** The label-vocabulary slice
**Partially resolved.** The label-vocabulary slice
landed with a single-file shape (`workflow_labels_file`, mirroring
`workflow_routing_file` and `SkillsDir`'s single-path precedent) rather
than a directory, because it is the smallest useful case. A directory
@@ -879,7 +874,7 @@ are unblocked on the execution-time questions.
single-file shape does not preclude it -- a future `workflow_dir` would
compose `workflow_labels_file`'s role into a loader.
**Status 2026-09-03: resolved by t2db.11 (corrected).** The directory
**Resolved** (`archie-core-t2db.11`). The directory
shape landed as `playbook_dirs` (a LIST of directories of
`*.yaml`/`*.yml` binding files), loaded at startup as an additional
input to the two single-file fields, which remain supported unchanged.
@@ -923,42 +918,38 @@ are unblocked on the execution-time questions.
end to end on the smallest useful case, before adding Channel/Forge
action kinds or the linter/LSP.
**Status 2026-09-03: resolved across t2db.13-15.** The Module position
**Resolved** (`archie-core-t2db.13`, `.14`, `.15`). The Module position
(registry + log kind, t2db.13), the CEL expression environment
(t2db.14), and the playbook document + event coordinator with
single-action workflow-kind dispatch (t2db.15) are shipped.
**Status 2026-09-21: wired into production intake (t2db.23).** The
coordinator decides a real task's workflow. The wiring point is the
daemon's definition pin (`Daemon.resolveWorkflowID`, consumed by
`pinWorkflowFromCollection` in `internal/daemon/daemon.go`), not
`pollNATS`/`publishTask` as the earlier note assumed: routing moved out
of the agent process when workflow definitions became database rows
pinned before dispatch, so the pin is now the one place a task's
workflow is chosen. Precedence there is explicit `Task.Workflow` (the
waiting_human -> approved requeue) → matching playbook →
**Resolved** (`archie-core-t2db.23`): the coordinator selects a real
task's workflow. The wiring point is the daemon's definition pin
(`Daemon.resolveWorkflowID`, consumed by `pinWorkflowFromCollection` in
`internal/daemon`), not `pollNATS`/`publishTask` as the earlier note
assumed. Routing belongs to the pin because a workflow definition is a
database row pinned before dispatch, which makes the pin the one place a
task's workflow is chosen. Precedence there is explicit `Task.Workflow`
(the waiting_human -> approved requeue) → matching playbook →
`workflow.ResolveWorkflowID`'s label binding → kind binding → triage →
implement. A playbook naming an undefined workflow is a reported
failure that parks the task rather than a silent fall-through to the
binding's choice.
implement. A playbook naming an undefined workflow is a reported failure
that parks the task rather than a silent fall-through to the binding's
choice.
`Store.Dispatch` returns the selected workflow *name* and the matching
playbook's id/version, not a compiled `workflow.Workflow`: the
playbook's id and version, not a compiled `workflow.Workflow`: the
production caller decides against the active definition collection, and
the returned id/version are the first two components of the gap-2
idempotency key. The playbook package no longer imports
`internal/domain/workflow`.
the id and version are the first two components of the gap-2 idempotency
key. The playbook package does not import `internal/domain/workflow`.
The `event` surface a `when` condition reads at this point is what the
intake actually knows about the originating issue: `kind`, `labels`,
`owner`, `repo`, `number`, `title`, `body`, `source`
(`playbookInput` in `internal/daemon/daemon.go`).
A `when` condition at this point reads what the intake knows about the
originating issue: `kind`, `labels`, `owner`, `repo`, `number`, `title`,
`body`, `source`, built by `playbookInput` in `internal/daemon`.
The trigger shape reuses the existing workintake kind/label vocabulary;
multi-action and non-workflow-position playbooks remain rejected at
load (hard boundary). Module/Channel/Forge action positions therefore
still have no production dispatch path: the resolved gap-2 scheme's
`playbook_dispatches` ledger is design-only and must land before a
The trigger shape reuses the existing workintake kind/label vocabulary.
Multi-action and non-workflow-position playbooks are rejected at load
(hard boundary), so Module/Channel/Forge positions have no production
dispatch path: the gap-2 `playbook_dispatches` ledger must land before a
side-effecting position can fire.
5. **Monetization boundary.** Sam has flagged this may be commercialized,
and explicitly wants it discerned from other OSS event-driven-automation
+1 -1
View File
@@ -23,7 +23,7 @@ stream is introduced for capture.
**NATS availability does not make capture a broker concern.** NATS is now
unconditional for autonomous workflow handoff, including embedded mode, but
capture is also used by deployments with no repository workflow configured.
SQLite is already guaranteed present because it backs daemon state, and keeps
SQLite is guaranteed present because it backs daemon state, and keeps
capture inspection independent of broker retention and consumer lifecycle.
The original version of this decision cited optional NATS as an additional
reason; that premise was superseded by `archie-core-q15y`, while the storage
+2 -2
View File
@@ -36,9 +36,9 @@ causes redelivery." Do not design new delivery semantics; use this contract.
**Do not reuse the existing `nats.Client` as-is.** `Config.StreamName` and
`Config.Subjects` are already composition-supplied ("the bus must not know
which subjects belong to which domain," `config.go:35-38`), but the
which subjects belong to which domain," `config.go`), but the
retention policy is not parameterized: `New` hardcodes
`Retention: jetstream.WorkQueuePolicy` (`client.go:65`), the competing-consumer
`Retention: jetstream.WorkQueuePolicy` (`client.go`), the competing-consumer
policy correct for `ARCHIE_TASKS` task distribution -- one message, claimed by
exactly one consumer -- and wrong for reactions. Two independent reactions
both wanting to see the same event under `WorkQueuePolicy` hit exactly the
+6 -6
View File
@@ -8,7 +8,7 @@ inventories with their own APIs (`api_skills.go`, `api_workflows.go`,
config-driven MCP servers) and their own family-owned controller pattern
(`curator.Registry`, `health.Registry`, `image.Registry`,
`workflow.Registry` all already prove this shape). `plugin.Plugin`
(`internal/plugin/plugin.go:24-27`) is already metadata-only, per
(`internal/plugin/plugin.go`) is already metadata-only, per
`docs/architecture/plugins-and-extensions.md`. None of that is rebuilt here.
What's missing, confirmed by grep, is: any config schema for enabling or
disabling a capability, any "pending restart" state tracking, and any single
@@ -20,7 +20,7 @@ families, no generic dispatch) are unchanged.
Out of scope: any remote or arbitrary-URL plugin installation path (the
epic's own acceptance criteria forbid this, and `plugin.LoadDir`
(`plugin.go:51-91`) already only reads `~/.config/archie/plugins/*.go` — this
(`plugin.go`) already only reads `~/.config/archie/plugins/*.go` — this
document does not add a fetch-by-URL variant to it).
## Problem
@@ -29,9 +29,9 @@ document does not add a fetch-by-URL variant to it).
`enabled` field (confirmed by the investigation grep). `api_config.go`'s
`UpdateConfig`/`handleConfigUpdate` seam persists changes but has no state
distinguishing "saved, takes effect now" from "saved, needs restart" — the
only existing reload path (`ReloadChannel`, `server.go:85`) is
only existing reload path (`ReloadChannel`, `server.go`) is
channel-specific and explicitly does not cover plugins or MCP servers.
`server.go:28-147` already wires five separate optional inventories
`server.go` already wires five separate optional inventories
(Workflows, Skills, Curators, Channels, Captures/Mappings/Bindings) as
independent fields with no unifying type — an operator today has no single
place to see "what's available, what's enabled, what's actually running,
@@ -82,7 +82,7 @@ existing domain-owned contracts rather than duplicating their state.
**Call site.** New package `internal/domain/extensions/inventory.go`.
Composed in `internal/app/archied` (wherever `server.go`'s other optional
fields — Workflows, Skills, Curators — are already wired) since it needs
fields — Workflows, Skills, Curators — are wired) since it needs
references to every family's registry, which only application-layer
composition has.
@@ -140,7 +140,7 @@ pages remain where they inspect a family's own detail.
| concern | file | change |
|---|---|---|
| Plugin metadata type | `internal/plugin/plugin.go:24-27` | none — already handles this |
| Plugin metadata type | `internal/plugin/plugin.go` | none — already handles this |
| Family controllers (curator/health/image/workflow registries) | `internal/domain/curator/registry.go`, `internal/domain/health/health.go`, etc. | none — pattern already proven, reused not rewritten |
| Unified inventory | `internal/domain/extensions/inventory.go` | new |
| Composition wiring | `internal/app/archied/server.go` (near existing optional fields) | new |
+1 -1
View File
@@ -412,7 +412,7 @@ video-specific.
| channel | image delivery | evidence |
|---|---|---|
| Telegram | **already works** | `internal/channels/telegram/media.go`'s `telegramMediaSender.dispatch` already branches on `att.Type` and calls `bot.SendPhoto` for `"image"` (`SendVideo` for `"video"` is the same function) |
| Dashboard (webui) | **tracked gap, not new** | `internal/webui/api_chat.go:355`'s `chatStreamSink.Media` has no inline rendering path yet and degrades to a link/error string — already tracked as archie-core-1786748942243-6-f109697e. This epic does not need to fix it, but #501's acceptance criterion ("unsupported paths report a clear limitation") is already met by the existing degrade-to-text behavior; closing the dashboard gap is that bead's job, not this one's |
| Dashboard (webui) | **tracked gap, not new** | `internal/webui/api_chat.go`'s `chatStreamSink.Media` has no inline rendering path yet and degrades to a link/error string — already tracked as archie-core-1786748942243-6-f109697e. This epic does not need to fix it, but #501's acceptance criterion ("unsupported paths report a clear limitation") is already met by the existing degrade-to-text behavior; closing the dashboard gap is that bead's job, not this one's |
| Email | **no attachment sender exists** | `grep MediaAttachment internal/channels/email` returns nothing. Out of scope for this epic per #496's non-goals (no channel-abstraction rework) — email delivery of a generated image degrades the same way the dashboard does today, which is acceptable under #501's "or unsupported paths report a clear limitation" clause |
| Webhook | not applicable | webhook is an inbound intake channel (`internal/channels/webhook`), not an outbound chat reply target — no `/image` command can originate there in the first place |
+2 -2
View File
@@ -7,7 +7,7 @@
## Problem
Findings reach the operator only as a flat list in the PR body
(`renderPRReviewSection`, h019.6): `` - `file.go:12` (confirmed, error): <defect>
(`renderPRReviewSection`, h019.6): `` - `file.go` (confirmed, error): <defect>
— <scenario> ``. That is a report *about* the code, not a review *of* it. A real
reviewer anchors each finding to the line it is about, so the author sees it in
context — and, when the fix is mechanical, attaches the replacement so it can be
@@ -51,7 +51,7 @@ those line numbers were **measured on** (`TaskContext.ReviewedHeadSHA`,
recorded when `StageOpenPR` opens the pull request), and the implementation
posts only while the head it read still matches it — see §4.
Per-forge reality (verified against the SDKs, 2026-09-11):
Per-forge reality, verified against the SDKs:
- **GitHub** — direct: `PullRequests.CreateComment` with
`{Body, Path, Line, Side: "RIGHT", CommitID}`.
+19 -19
View File
@@ -3,27 +3,27 @@
Epic: `archie-core-1786637493439-140-2cee2e9b` / GitHub `#161` ("[EPIC] Tools:
central registry, MCP client, guardrails").
Most of this epic already shipped. The central registry
This document is scoped to five sub-features of that epic: MCP
server-initiated sampling, the per-server parallel-tool-calls flag, sandboxed
MCP tool servers, a Firecracker sandbox backend, and sequential dispatch with
per-result previews.
Out of scope, and not to be touched: the central registry
(`internal/tools/registry.go`), all three MCP transports (stdio/HTTP/SSE,
`internal/tools/mcp/transport*.go`), reconnect-with-backoff
(`transport.go:43-71,530-580`), guardrail loop detection
(`transport.go`), guardrail loop detection
(`internal/tools/guardrail.go`), idempotent/mutating classification
(`internal/tools/classification.go`), concurrent tool dispatch (closed
`#183`), and progressive disclosure wiring
(`internal/app/archied/main.go:72-99`, confirmed production-wired, not just
tested) are settled and correct. Do not touch them. This document covers only
the five sub-features still open under the epic: MCP server-initiated
sampling, the per-server parallel-tool-calls flag, sandboxed MCP tool
servers, a Firecracker sandbox backend, and sequential dispatch with
per-result previews.
(`internal/tools/classification.go`), concurrent tool dispatch (`#183`), and
progressive disclosure wiring (`internal/app/archied`). These are settled and
production-wired.
## Problem
`bd search "MCP client"` shows five closed transport beads and one open:
server-initiated sampling (`#151`). `internal/tools/mcp/client.go:34-37`
server-initiated sampling (`#151`). `internal/tools/mcp/client.go`
holds a single `callMu *sync.Mutex` that serializes every `tools/call`
regardless of server — `ParallelToolCalls` does not exist on the `MCPServer`
config struct (`internal/config/config.go:168-186`), confirming `#177` is a
config struct (`internal/config/config.go`), confirming `#177` is a
real gap, not a stale bead. `#178` (wire MCP tool servers for the chat agent,
sandboxed) and `#179` (Firecracker substrate) have no corresponding code —
MCP servers today run as whatever the config's `Command`/`Args` launches,
@@ -57,7 +57,7 @@ server-initiated sample gets the daemon's configured model, not a second
provider client.
**Reuse check.** The chat model invocation path already exists
(`chatGenerateOptions`, `main.go:72-99`); this reuses it rather than adding a
(`chatGenerateOptions`, `main.go`); this reuses it rather than adding a
parallel model-calling path for MCP sampling.
**Failure mapping.**
@@ -75,8 +75,8 @@ needed; belongs in `task check`.
## Per-server parallel-tool-calls flag (`#177`)
**Decision.** `ParallelToolCalls bool` (default `false`) goes on `MCPServer`
in `internal/config/config.go:168-186`, next to `Transport`/`Command`. The
mutex in `client.go:34-37` becomes per-server: when `ParallelToolCalls` is
in `internal/config/config.go`, next to `Transport`/`Command`. The
mutex in `client.go` becomes per-server: when `ParallelToolCalls` is
false (default, and the only behavior today), keep the single `callMu`
serializing that server's calls exactly as now; when true, drop the mutex for
that server's `Client` instance entirely and let the caller's own
@@ -85,7 +85,7 @@ handle it. This is additive — no server's behavior changes unless an operator
opts in.
**Call site.** `internal/config/config.go` (struct field),
`internal/tools/mcp/client.go:34-37` (make the mutex conditional on the
`internal/tools/mcp/client.go` (make the mutex conditional on the
field), and wherever `MCPServer` configs are turned into `Client` instances
at daemon startup (the constructor that reads `internal/config`'s MCP block).
`config.example.toml`'s commented MCP block gets the new field documented
@@ -131,7 +131,7 @@ there rather than duplicating the pool).
| condition | contract error |
|---|---|
| pool exhausted (no container slot) | MCP client returns connection-refused equivalent; server marked unavailable in the registry until retried |
| container fails health/start | same as `#151`'s handler-error path — surfaced through the client's existing reconnect/backoff (`transport.go:530-580`), not a new retry loop |
| container fails health/start | same as `#151`'s handler-error path — surfaced through the client's existing reconnect/backoff (`transport.go`), not a new retry loop |
**Testing.** `Sandboxed=false` path is the existing, already-tested
unsandboxed flow — no change. `Sandboxed=true` needs a real
@@ -165,8 +165,8 @@ preview callbacks fire in order before the next call starts. `task check`.
| concern | file | change |
|---|---|---|
| MCP client transports (stdio/HTTP/SSE) | `internal/tools/mcp/transport*.go` | none — already handles this |
| MCP client call serialization | `internal/tools/mcp/client.go:34-37` | change (`#177`) |
| MCP server config | `internal/config/config.go:168-186` | new fields: `ParallelToolCalls`, `Sandboxed` |
| MCP client call serialization | `internal/tools/mcp/client.go` | change (`#177`) |
| MCP server config | `internal/config/config.go` | new fields: `ParallelToolCalls`, `Sandboxed` |
| Sampling dispatch | `internal/tools/mcp/client.go` | new (`#151`) |
| Sampling handler wiring | `internal/app/archied/main.go` | new (`#151`), reuses `chatGenerateOptions` |
| Sandboxed MCP launch | MCP client constructor + `internal/container/pool.go` | new (`#178`/`#179`) |
+19 -19
View File
@@ -18,11 +18,11 @@ writes them, and the chat turn reads neither.
| Family | Written by | Root | Format |
|---|---|---|---|
| `internal/memory` (`Manager`, `builtin.Provider`) | the chat agent's `memory_edit` tool via `memorytoolprovider` (`bootstrap.go:1198`) | `<workDir>/memory` | `MEMORY.md` / `USER.md` |
| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go:163`) | `<workDir>/memory-engine` | identity-keyed blocks |
| `internal/memory` (`Manager`, `builtin.Provider`) | the chat agent's `memory_edit` tool via `memorytoolprovider` (`bootstrap.go`) | `<workDir>/memory` | `MEMORY.md` / `USER.md` |
| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go`) | `<workDir>/memory-engine` | identity-keyed blocks |
They share no code, no format and no scope vocabulary. Neither reaches a prompt:
`Manager.SystemPromptBlock` (`internal/memory/manager.go:429`) has no production
`Manager.SystemPromptBlock` (`internal/memory/manager.go`) has no production
caller anywhere, so the agent can write memory through a tool and never read it
back.
@@ -33,16 +33,16 @@ Three further defects fall out of the same split:
*does* have `handleAdd`/`handleReplace`/`handleRemove`, so the family being
deleted is operationally richer than its replacement.
2. **There is no scope model.** The contract carries one opaque `Identity
string`, and the curator fills it with a **session id** (`sessioncurator.go:164`)
— which is none of the four scopes `docs/architecture/agent-system.md:69-78`
string`, and the curator fills it with a **session id** (`sessioncurator.go`)
— which is none of the four scopes `docs/architecture/agent-system.md`
requires, and stops meaning anything when the session ends.
3. **The chat turn has no user identity on half the channels.** `SenderID` is
populated by Telegram and email (a person) and by webhook (a **route path**,
`webhook.go:179`), and not at all by the dashboard, whose gateway wire message
`webhook.go`), and not at all by the dashboard, whose gateway wire message
carries no sender field. It is also never persisted: `sender_id` appears
nowhere in `session_store_sqlite.go`.
`agent-system.md:100` says the write-scope selection and cross-scope sharing
`agent-system.md` says the write-scope selection and cross-scope sharing
rules "require a focused memory design decision". This is that decision.
## Decision
@@ -93,7 +93,7 @@ exactly the scopes of the resolved `Subject`; the engine never unions beyond wha
it is handed and applies no policy of its own. An engine that enforced policy
would need to know about channels, sessions and bindings, and every backend would
reimplement it. "Agent-wide is private to its owning Agent by default"
(`agent-system.md:80-81`) falls out mechanically, because `ScopeAgent{a}` and
(`agent-system.md`) falls out mechanically, because `ScopeAgent{a}` and
`ScopeAgent{b}` are different storage keys.
`ScopeGlobal` is never model-writable. Writing it is an operator action; nothing
@@ -114,10 +114,10 @@ type Store interface {
```
`Get` and `Forget` take a scope. The current `Forget` scans every identity's
store to find a marker (`builtin_engine.go:189-210`) purely because the contract
store to find a marker (`builtin_engine.go`) purely because the contract
gave it nothing better.
`Record` carries what `agent-system.md:97-99` requires be retained: `Scope`,
`Record` carries what `agent-system.md` requires be retained: `Scope`,
`Kind`, `Content`, `Revision`, `Author`, `OriginUser`, `Source`, `CreatedAt`,
`UpdatedAt`. `Metadata` is dropped — nothing sets it and the parser never
restores it, so it is currently a field that silently does not round-trip.
@@ -150,19 +150,19 @@ UserIdentity func(msg messaging.Message) (IdentityID, bool)
This must be injectable rather than a blanket `channel + ":" + SenderID`
concatenation, because a **webhook's `SenderID` is a route path**
(`webhook.go:179`), not a person; treating it as one would give a URL an
(`webhook.go`), not a person; treating it as one would give a URL an
identity. Telegram and email supply their sender id; the dashboard and webhook
resolve nothing.
**Fail closed.** When `UserID` is empty the turn proceeds with global and agent
scopes only, and a write targeting `user` or `agent-user` fails with a clear
error. `agent-system.md:92-94` forbids showing one user's memory to another, so
error. `agent-system.md` forbids showing one user's memory to another, so
"we do not know who this is" must mean "show none of it", never "fall back to a
wider scope".
### 4. The chat read path
Synchronous and total. It runs inside `prepareTurn` (`turn.go:287`) before the
Synchronous and total. It runs inside `prepareTurn` (`turn.go`) before the
prompt is built, never returns an error to the caller, and degrades to an empty
block on any engine failure or provider panic. A fire-and-forget hook would race
the prompt build in the same turn, which is why this is not a lifecycle hook.
@@ -172,7 +172,7 @@ search, which remains open in `migration-decisions.md#5`. A ranked read on the
hot path with no ranking implementation would be a lie.
`SystemPromptConfig` gains a `Memory` field, rendered into
`templates/archie.md.tpl` between `<tools>` (line 41) and `<env>` (line 50):
`templates/archie.md.tpl` between the `<tools>` and `<env>` blocks:
```
<memory purpose="durable_context" trust="data">
@@ -188,8 +188,8 @@ Both a per-scope record limit and a byte cap on the rendered block are named
constants. The cap is about size, not latency; a local read needs no timeout.
**Prerequisite:** `setupGateways` runs before `setupMemoryAll`
(`main.go:414` vs `:428`), and `startGatewayRuntime` before `setupMemory`
(`gateway.go:110` vs `:115`), so the engine is nil at every turn-runner
(`main.go` vs `:428`), and `startGatewayRuntime` before `setupMemory`
(`gateway.go` vs `:115`), so the engine is nil at every turn-runner
construction site. The ordering is the root-cause fix and nothing in either
memory step reads what those later steps produce.
@@ -208,7 +208,7 @@ must write into a scope derived from the turn's resolved subject:
**The model chooses the scope kind; it never chooses the ids.** Agent and user
ids come from the turn's resolution and there is no schema field to put anything
else in — even a model that emits another user's id has nowhere to write it. That
is the root-cause form of `agent-system.md:87-90`, matching this system's other
is the root-cause form of `agent-system.md`, matching this system's other
non-waivable boundaries (the model never runs git; gates cannot be waived by the
agent). `global` is not offered at all.
@@ -240,7 +240,7 @@ curator's bad note becomes id-addressable and therefore correctable by the agent
### 7. The content scanner moves to the engine
`internal/memory/scanner.go` and its installation at `bootstrap.go:1045` are what
`internal/memory/scanner.go` and its installation at `bootstrap.go` are what
make `configuration.md`'s "Memory safety scanner" row describe a control that
actually runs. Deleting the package would silently remove prompt-injection
scanning on memory writes. The scanner moves into the engine and is applied in
@@ -260,7 +260,7 @@ engine already parses that format.
Also deleted: `internal/tools/provider/memory`'s manager wrapping (rewired to the
engine), `config.Memory.{Provider,ProviderConfig}` and the
`validateMemory` rejection that exists only to complain about `Provider`
(`validate.go:143-154`), and `webui.MemoryStatus`/`MemoryProviderHandle` — never
(`validate.go`), and `webui.MemoryStatus`/`MemoryProviderHandle` — never
implemented in production, so `/api/memory` reports empty forever unless it is
repointed at the engine registry.
+2 -2
View File
@@ -14,7 +14,7 @@ not started, because it needs a schema-generation mechanism the parent
doc deliberately deferred: "This document does not attempt to design the
full generator today." This is that design.
## Do not invent a new mechanism -- generalize the one already shipped three times
## Do not invent a new mechanism -- generalize the one used three times
Yaegi-interpreted extension code with a fixed, resolved-by-name exported
function already exists in this codebase for three surfaces, and all three
@@ -183,7 +183,7 @@ side effect. Concretely:
4. Do **not** implement `notify` or any side-effecting kind in this slice
-- that is explicitly gated on the execution-time gaps above.
**Status 2026-09-03: first slice shipped (t2db.13).** The schema-gen ->
**Resolved** (`archie-core-t2db.13`). The schema-gen ->
go:generate -> Yaegi load -> registry mechanism is proven end to end with
`internal/domain/eda/module/log` (hand-written schema + `logextract`
generated symbols) and `ModuleRegistry` (Register/Invoke, strict arg
+14 -14
View File
@@ -6,7 +6,7 @@
## Decision
The bridge-tool pattern is **already implemented and tested** in
The bridge-tool pattern is **implemented and tested** in
`internal/tools/disclosure.go` (`tool_search`, `tool_describe`, `tool_call`
+ `ContextPressureGate` + `DisclosureMode`, section 17.14/17.15) — but it is
**never wired into the daemon**. `BridgeTools` and `ContextPressureGate` are
@@ -18,7 +18,7 @@ Wire the existing bridge into the per-chat-turn toolset:
1. **Compose a per-turn registry** seeded from the base registry plus the
per-turn extra tools, register the bridge tools into it, and hand it to both
the bridge handlers and the `ContextPressureGate`.
2. **Run the gate in `chatGenerateOptions`** (`internal/app/archied/main.go:69`)
2. **Run the gate in `chatGenerateOptions`** (`internal/app/archied/main.go`)
so it decides full-vs-bridge disclosure per turn, and build the
`core.ToolSet` from the gate's filtered output.
3. **Thread the model's context window** into the preparation seam so the gate
@@ -27,25 +27,25 @@ Wire the existing bridge into the per-chat-turn toolset:
## Why the naive "register extras into the base registry" is wrong
`BuildToolSetFrom` (`internal/agentexec/toolset.go:170`) documents the invariant:
`BuildToolSetFrom` (`internal/agentexec/toolset.go`) documents the invariant:
> the task tools carry the calling gateway's identity, so there is one set of
> them per gateway and they **cannot live in the process-wide registry**.
This is confirmed by wiring: gateways are per-channel
(`telegram_setup.go:291,308` build a `TurnRunner` per channel), and the extra
(`telegram_setup.go` build a `TurnRunner` per channel), and the extra
tools (`task_*`, `session_*`, `dashboard_*`) close over that channel's identity
via `TurnRunnerConfig` (`turn.go:66`). Registering them into `b.toolReg` would
via `TurnRunnerConfig` (`turn.go`). Registering them into `b.toolReg` would
let channel A's session/identity-bound tools be invoked by channel B — a real
cross-channel privilege bug. The bridge handlers iterate `reg.All()`
(`disclosure.go:53,107,146`), so the extras must be discoverable; the fix is a
(`disclosure.go`), so the extras must be discoverable; the fix is a
**per-turn composed registry**, not a mutation of the process-wide one.
## Shape of the change
### 1. Per-turn composed registry + gate inside `chatGenerateOptions`
Replace the current base-set + extra-set merge (`main.go:90-100`) with a single
Replace the current base-set + extra-set merge (`main.go`) with a single
composed-registry pass:
```go
@@ -76,14 +76,14 @@ disclosed := gate.FilterTools(composed)
toolSet, err := agentexec.BuildToolSetFrom(disclosed, toolOpts)
```
`FilterTools` (`disclosure.go:327`) already returns `all` in full mode and
`FilterTools` (`disclosure.go`) already returns `all` in full mode and
`bridge + always-visible` in bridge mode, and `BuildToolSetFrom` re-applies
availability/approval/schema rules, so the two layers compose cleanly.
### 2. Thread context window through the preparation seam
`ContextPressureGate` disables at `ContextWindowSize == 0`. The model context
window is resolved in `TurnRunner.prepareTurn` (`turn.go:303-306`) but is not
window is resolved in `TurnRunner.prepareTurn` (`turn.go`) but is not
passed to `TurnModel.Prepare`. Extend the seam:
```go
@@ -96,15 +96,15 @@ type TurnPrepareContext struct {
`TurnModel.Prepare(ctx, context TurnPrepareContext)`; `prepareTurn` fills
`ContextWindow` from `modelDetails.ContextWindow`. This touches one interface
(`turn.go:18`), one production impl (`chat_turn_model.go:40`), and the test
mock (`turn_test.go:21`).
(`turn.go`), one production impl (`chat_turn_model.go`), and the test
mock (`turn_test.go`).
### 3. Bridge-handler parity note
`bridgeCallHandler` calls `e.Handler` directly (`disclosure.go:158`), bypassing
`bridgeCallHandler` calls `e.Handler` directly (`disclosure.go`), bypassing
`toolExecute` — so a `tool_call` invocation does **not** apply `CapPayload` /
`MaxResultSizeChars` spilling or `OnToolCall` reporting, and it pre-refuses
`RequiresApproval` tools (`disclosure.go:150-152`). This is acceptable for the
`RequiresApproval` tools (`disclosure.go`). This is acceptable for the
first wiring (the bridge is read-discover/describe plus a guarded call), but a
later hardening should route the invoked tool through the same
cap/approval path the model's direct call uses. Recorded as a follow-up, not a
@@ -124,4 +124,4 @@ blocker for this task.
- Cover the compose-and-gate path with tests (compressed footprint under a
small window; always-visible minus bridge margin).
- Reconcile any `ContextPressureGate` mode with the compression budget already
computed in `prepareTurn` (`turn.go:311-315`).
computed in `prepareTurn` (`turn.go`).
+11 -11
View File
@@ -10,7 +10,7 @@ this document — it stays a thin Go interface shelling out to
adapter scripts (`scripts/archie-update-{check,install,watchdog}`) and
`install.sh` do behind that contract, and settles the one thing the epic's
own description got wrong: the dist-zip **is** already attached to GitHub
Releases (`.github/workflows/deploy.yml:283-316`, `gh release upload`), not
Releases (`.github/workflows/deploy.yml`, `gh release upload`), not
Actions-artifact-only. Artifact install is therefore a smaller change than
the epic assumed — pointing the installer at an existing asset, not standing
up new CI publishing. Topology migration and the journaled transaction are
@@ -32,7 +32,7 @@ script not using it is a missed-reuse gap, not a missing-CI gap.
deployment profile (`deployments/*.toml`) declares `[services.state]` and
`[services.gateway]` sections needing their own units — a fresh install
already reproduces the broken single-unit shape `deployment_contract_test.go`
(lines 70-105) doesn't even catch, because that test only checks profile
doesn't even catch, because that test only checks profile
syntax, not installed topology. No code anywhere enumerates which systemd
units exist on a host or compares that against what a release requires — the
daemon fails at `bootstrap.go`'s `[services.state].target` check with no
@@ -55,13 +55,13 @@ opt-in path selected by an explicit `--from-source` flag or
every-host update is strictly slower and has a larger failure surface than
downloading a signed asset that CI already produced.
**Call site.** `scripts/archie-update-install` — replace the body currently
at lines 139-160 with a download-and-verify step; move the existing
**Call site.** `scripts/archie-update-install` — replace the clone+compile
body with a download-and-verify step; move the existing
clone+compile body behind the opt-in flag rather than deleting it.
`internal/releaseupdate/command.go:44-48` (`CommandInstaller`) is unchanged —
`internal/releaseupdate/command.go` (`CommandInstaller`) is unchanged —
it already just shells out.
**Reuse check.** `deploy.yml:265-316` already builds and publishes the
**Reuse check.** `deploy.yml` already builds and publishes the
archive and uploads it as both an Actions artifact and a release asset; no
new CI work is needed, only pointing the installer at what exists.
@@ -118,7 +118,7 @@ needs a real systemd host; manual smoke test only.
### Journaled transaction (`#804` item 3)
**Decision.** Replace `archie-update-install`'s copy-and-trap body with: (1)
pre-flight (existing check at line 170, kept), (2) write an intent journal
pre-flight (the existing check, kept), (2) write an intent journal
to a path outside every directory the install touches — e.g.
`${XDG_STATE_HOME:-~/.local/state}/archie/update.journal` — recording the
candidate version, the topology plan (if any), and each binary's
@@ -163,7 +163,7 @@ start/stop as part of rollback needs a real host; manual smoke command.
**Decision.** Add `channel = "stable" | "next" | "<exact-version-pin>"`
to whatever config section already governs update behavior (next to
`ARCHIE_UPDATE_CHANNEL`'s existing chat-channel field in
`internal/releaseupdate/command.go:62` — name this new field distinctly,
`internal/releaseupdate/command.go` — name this new field distinctly,
e.g. `ReleaseChannel`, to avoid colliding with the existing chat-notification
channel of the same word). `Catalog.Check` filters candidate releases by
this field before returning the newest match. Runtime image pinning: every
@@ -191,12 +191,12 @@ is a shell-script unit test against a fixture profile.
| concern | file | change |
|---|---|---|
| Update contract (Catalog/Installer interfaces) | `internal/releaseupdate/service.go` | none — already handles this |
| Command adapters | `internal/releaseupdate/command.go:22,44-48,62` | new `ReleaseChannel` field distinct from existing chat-channel field |
| Command adapters | `internal/releaseupdate/command.go` | new `ReleaseChannel` field distinct from existing chat-channel field |
| Install script body | `scripts/archie-update-install:139-160,170,195-199` | replace clone+compile default with download+verify; add journal, lock, stage-then-rename, digest check |
| CI release publishing | `.github/workflows/deploy.yml:265-316` | none — already handles this |
| CI release publishing | `.github/workflows/deploy.yml` | none — already handles this |
| Deployment profiles | `deployments/*.toml` | none — already digest-pinned |
| First-install unit creation | `install.sh:414-445` | change — consume shared topology declaration |
| Topology assertions | `deployment_contract_test.go:70-105` | new assertion: profile topology matches install.sh output |
| Topology assertions | `deployment_contract_test.go` | new assertion: profile topology matches install.sh output |
| Topology observation | `internal/app/archied/bootstrap.go` (new sibling code) | new |
| Resume-on-boot rollback | `internal/app/archied` startup | new |
| Health check reuse for candidate verification | `internal/domain/health` | reuse — confirm exact symbol before implementing |
+5 -8
View File
@@ -1,9 +1,6 @@
# Service decomposition -- decision
**Status:** Proposed -- not yet approved for implementation
**Progress:** Phases 1 (Gateway), 2 (State Store) and 3 (UI) shipped; Phase 4
(Messaging) is ready, Phase 5 (Execution/Runner/Scheduler) and Phase 6
(Curator, optional) remain chained behind it.
**Date:** 2026-09-05
**Beads epic:** archie-core-8cda
**Prior art:** `docs/inspiration/2026-09-05-awx-service-decomposition-and-ansible-task-model.md`,
@@ -132,7 +129,7 @@ historical record rather than an outstanding gate.
`ChatContract` should exist before UI Service is extracted, since UI is
the most entangled consumer today. Not yet sequenced.
**RESOLVED (2026-09-05).** Gateway Service first, then State Store,
**RESOLVED.** Gateway Service first, then State Store,
then UI, then Messaging, then Execution/Runner/Scheduler, then Curator
(optional) — preceded by an in-process "contract seams" (modular
monolith) phase. Confirms the hypothesis and strengthens it: the
@@ -145,7 +142,7 @@ historical record rather than an outstanding gate.
need a home (a new `proto/` or `contracts/` tree, versioning scheme,
codegen wiring into `Taskfile.yml`). Not yet designed.
**RESOLVED (2026-09-05).** buf v2 driving `protoc-gen-go` +
**RESOLVED.** buf v2 driving `protoc-gen-go` +
`protoc-gen-go-grpc` (grpc-go, not connect-go — connect-go's net/http
client breaks the discovery research's gRPC resolver plumbing for K8s
DNS and NATS-KV). One committed `proto/<service>/v1/` tree, generated
@@ -164,7 +161,7 @@ historical record rather than an outstanding gate.
one. Strongly recommend the former for a solo maintainer, but not
decided here.
**RESOLVED (2026-09-05).** Multiplexed in-process is the migration
**RESOLVED.** Multiplexed in-process is the migration
default -- this is `docs/architecture/organisation.md`'s standing
"Process boundaries" rule, not a new lean. Mechanism: one wire-safe Go
contract interface per service; a local adapter and a generated gRPC
@@ -194,7 +191,7 @@ historical record rather than an outstanding gate.
State Store service's contract (less isolation, less migration risk).
Not yet decided.
**RESOLVED (2026-09-05).** One State Store service owns the existing
**RESOLVED.** One State Store service owns the existing
single SQLite file behind narrow typed contracts (`TaskStore`,
`CaptureStore`, `MappingStore`, `BindingStore`, `WorkflowStore`) over
gRPC. *(Ratified 2026-09-06: the workflow contract is now the
@@ -230,7 +227,7 @@ historical record rather than an outstanding gate.
and a `docker-compose.yml`, not Kubernetes manifests). Scoping not yet
started.
**RESOLVED (2026-09-05).** Three charts: an `archie-library` chart
**RESOLVED.** Three charts: an `archie-library` chart
(shared Deployment/Service templates, named ports), an `archie` chart
for the 7 core services, and an `archie-curator` chart + Curator
Operator (CRD, controller, RBAC). The Curator reconciler is a
+8 -8
View File
@@ -14,17 +14,17 @@ A service is already one Go type, `config.ServiceConnection`. What is duplicated
| Layer | Location | What is hard-coded |
|---|---|---|
| Declaration | `internal/config/services.go:4-14` | `Gateway` and `State` as struct fields |
| Defaulting | `internal/infrastructure/configuration/defaults.go:74-82` | three `if cfg.Services.X.Y == ""` branches |
| Consumption | `internal/app/archied/{bootstrap.go,state_store.go,gateway.go}`, `internal/app/archieui/config.go:80-81` | `cfg.Services.State` / `cfg.Services.Gateway` field access |
| Declaration | `internal/config/services.go` | `Gateway` and `State` as struct fields |
| Defaulting | `internal/infrastructure/configuration/defaults.go` | three `if cfg.Services.X.Y == ""` branches |
| Consumption | `internal/app/archied/{bootstrap.go,state_store.go,gateway.go}`, `internal/app/archieui/config.go` | `cfg.Services.State` / `cfg.Services.Gateway` field access |
Adding a service means editing all three. The drift this permits is already visible:
`stateStoreResolvedToken` (`state_store_client.go:17-23`) and `gatewayResolvedToken`
(`chat_service.go:20-26`) are byte-identical apart from the env var name, and
`stateStoreResolvedToken` (`state_store_client.go`) and `gatewayResolvedToken`
(`chat_service.go`) are byte-identical apart from the env var name, and
`gateway.Target` is defaulted while `state.Target` is a startup error, with nothing
stating that asymmetry in one place.
`resolveServiceListen(service, flagValue, configured)` (`listen.go:24-34`) is already
`resolveServiceListen(service, flagValue, configured)` (`listen.go`) is already
name-parameterised. It is the shape the rest should follow.
## Decision
@@ -98,8 +98,8 @@ states in prose or in a branch:
extensibility, because the answer comes from registration data rather than a fixed list.
(An earlier draft of this document claimed the typo was silently ignored either way. It
was not; the behaviour was measured.)
- Existing tests reference `cfg.Services.State` directly (`state_store_client_test.go:82`,
`setup_test.go:278`, and others). They move to `Get`, mechanically.
- Existing tests reference `cfg.Services.State` directly (`state_store_client_test.go`,
`setup_test.go`, and others). They move to `Get`, mechanically.
- No wire contract, no RPC, and no persisted format is touched. The 42-RPC State Store
contract is unaffected.
+1 -1
View File
@@ -148,7 +148,7 @@ file reads).
chat turn sees.
- **No new curator-specific webui or chat surface.** Activity is visible
through the existing curator observability surface
(`archie-core-1786637489932`, already shipped) -- `/api/curators` and
(`archie-core-1786637489932`) -- `/api/curators` and
the dashboard Curators page already show any registered curator's
recent actions.
+3 -3
View File
@@ -322,7 +322,7 @@ persists the domain type).
captureID int64, taskID int64) error` takes a **`*sql.Tx`** that cannot cross a gRPC boundary.
**Evidence that the `*sql.Tx` is removable:** the dispatch loop calls `RecordDispatch(ctx, nil,
…)` (`internal/daemon/daemon.go:591`). The implementation falls back to the store's own
…)` (`internal/daemon/daemon.go`). The implementation falls back to the store's own
`*sql.DB` when `tx == nil` ("best-effort, not atomic"; the comment and the
`TestRecordDispatchViaExplicitTx` test are the only consumers of the non-nil `tx` path).
Production never opens the explicit transaction.
@@ -404,7 +404,7 @@ across a single agent process, which is either NATS-backed or gRPC-backed, never
**false** across the boundary.
- **gRPC `gatewayrpc`** currently returns raw `err` from handlers; gRPC-Go converts to
`codes.Unknown` with only the message. The **only** explicit code in the repo is
`codes.Unavailable` for a missing session store (`server.go:31`). No status-code mapping for
`codes.Unavailable` for a missing session store (`server.go`). No status-code mapping for
store errors exists.
### Decision — structured mapping so `errors.Is` survives
@@ -448,7 +448,7 @@ paths, provider/forge details, secrets, and stack traces are sensitive internals
## 8. Limits
**Interface bloat (`interfacebloat` cap = 8)** — `.golangci.yml:89` `interfacebloat: max: 8`,
**Interface bloat (`interfacebloat` cap = 8)** — `.golangci.yml` `interfacebloat: max: 8`,
which overrides the upstream default of 10. The Go consumer facades must stay ≤8 methods.
`TaskLifecycle` is exactly 8 (at the cap); `TaskStore` is the 24-method composite that the cap
is why it is decomposed; proto services bypass the cap (like `ChatContract`).
+17 -16
View File
@@ -1,10 +1,11 @@
# /status health surface -- what's shipped, what's proposed
# /status health surface
**Status:** Phase 1 shipped 2026-09-03 (archie-core-wp9s). Phase 2 shipped
2026-09-19: broker connectivity, container pool, last poll, provider
reachability and channel state are implemented on the decisions recorded below,
with the fields that had no truthful source left out rather than faked (see
"Phase 2 -- shipped").
**Status:** Finalised
**Beads issue:** `archie-core-wp9s`
A reported field must have a truthful source. Broker connectivity, container
pool, last poll, provider reachability and channel state are reported; a field
with no truthful source is left out rather than faked.
## Background
@@ -15,7 +16,7 @@ reachability, channel state, container pool, queue depth, last poll,
version" -- with neither duplicating the other or static config available
elsewhere (`/model` already lists active provider/model).
## Phase 1 -- shipped
## Phase 1
- `/tasks`: new command, `gateway.ChatTaskSummary` extended with
`Stage`/`Attempt`/`ParkReason`/`UpdatedAt` (all already persisted on
@@ -45,19 +46,19 @@ decisions") and all five fields shipped.
- **Broker connectivity.** `internal/infrastructure/eventbus/nats.Client`
already exposes `CoreConn() (*nats.Conn, error)`
(`client.go:134`). The underlying `nats.Conn` (nats.go) has its own
(`client.go`). The underlying `nats.Conn` (nats.go) has its own
`Status()`/`IsConnected()`. A `Client.Connected() bool` wrapper is a few
lines.
- **Container pool.** `container.Pool` already tracks `active int` under
its own mutex (`pool.go:90`) but has no public accessor. A
its own mutex (`pool.go`) but has no public accessor. A
`Pool.Active() int` getter is a few lines.
- **Last poll.** Nothing tracks this today. The daemon's poll loop
(`internal/daemon`) needs one `lastPollAt time.Time` field (atomic or
mutex-guarded, matching the pool's own pattern) set at the top of each
poll tick, with a getter.
- **Queue depth.** Already shipped in Phase 1.
- **Queue depth.** Covered by Phase 1.
### The two decisions (settled 2026-09-19, decided by position)
### The two decisions
- **Provider reachability is last-known outcome, never a live probe.** A chat
command must not perform a blocking network call in its handler, and a probe
@@ -74,7 +75,7 @@ decisions") and all five fields shipped.
probe already use -- rather than re-deriving channel health from each adapter.
No method was added to the `Channel`/`Gateway` contract.
### Phase 2 -- shipped
### Phase 2
- **Broker connectivity.** `internal/infrastructure/eventbus/nats.Client` gained
`Connected() bool`, which reads the connection the process already holds. The
@@ -89,7 +90,7 @@ decisions") and all five fields shipped.
`pollForIdentity` for `runIdentities`) stamp it. A pass that hangs leaves the
stamp stale, which is the signal -- stamping completion instead would leave a
wedged poller looking healthy.
- **Queue depth.** Already shipped in Phase 1.
- **Queue depth.** Covered by Phase 1.
- **Rendering.** `gateway.formatHealth` renders one line per reported fact
(`Broker:`, `Containers:`, `Channels:`, `Chat model:`, `Last poll:`) between
the queue line and the runtime block. The sources it reads are functions, not
@@ -110,7 +111,7 @@ decisions") and all five fields shipped.
here. For the same reason the chat-model line is per process: the daemon
records the turns it runs (Telegram, email, webhook), the Gateway records the
web chat's, and the two do not pool outcomes. Each line is true of the process
answering the command. **Decided 2026-09-19: they stay per-process.** Pooling
answering the command. **Decided: they stay per-process.** Pooling
them would mean a new daemon↔gateway health RPC for one status line, and a
per-process line is true where an aggregate would be a claim about a process
the answering one cannot see.
@@ -128,7 +129,7 @@ decisions") and all five fields shipped.
the only line in `/status` that this ticket's own rule says should not be
there -- but the maintainer reads `/status` daily to see the active model at a
glance, and one command answering both "is archie well" and "what is it
running on" is worth that duplication. **Decided 2026-09-19: keep it.** It is
running on" is worth that duplication. **Decided: keep it.** It is
a settled product decision, not an oversight; do not remove it as a
mechanical follow-up.
- **`/agents` copy.** The menu still advertises "List tasks currently being
@@ -136,7 +137,7 @@ decisions") and all five fields shipped.
published description does not match what its command does. Deleting,
rewiring or redefining `/agents` is that bead's call and is not folded in here.
## Packages this touches (Phase 2, as shipped)
## Packages this touches (Phase 2)
- `internal/infrastructure/eventbus/nats`: `Client.Connected()`.
- `internal/container`: `Pool.Active()`, `Pool.Cap()`.
+3 -3
View File
@@ -210,14 +210,14 @@ yet satisfy this boundary. This document is the ratified target; the
implementation child must prove each migration gate before claiming Phase 3
complete.
### Phase 3 complete (2026-09-11)
### Phase 3 gates
Phase 3 is closed. Every gate below is proven by test, not by inspection:
Every gate below is proven by test, not by inspection:
| Gate | Evidence |
| --- | --- |
| Deletion | `cmd/archie-ui/architecture_test.go` re-runs `go list -deps` on every `task check` and fails on any banned package, checked in both directions against its two exceptions |
| Composition | `internal/app/archieui/TestComposeUIServerHoldsNoDaemonState` fails on a concrete `*store.Store` or a Gateway that is not the gRPC client. The holder clause it also carried is now enforced by the type: `webui.Server` has no `config.Holder` field (`archie-core-ml30`) |
| Composition | `internal/app/archieui/TestComposeUIServerHoldsNoDaemonState` fails on a concrete `*store.Store` or a Gateway that is not the gRPC client. The holder clause it also carried is enforced by the type: `webui.Server` has no `config.Holder` field (`archie-core-ml30`) |
| End-to-end | `cmd/archie-ui/main_test.go` builds the binary and drives it over HTTP against a live Gateway and State Store |
| No dual authority | The dashboard HTTP listener is `internal/app/archieui/run.go` only; the daemon's two `http.Server`s are its own health endpoint and the forge webhook receiver |
+7 -7
View File
@@ -30,14 +30,14 @@ does not show up as a broken page.
- [ ] **Mutation headers.** Every POST/PATCH/DELETE must send **both**
`X-Archie-CSRF: 1` and `Content-Type: application/json`. The server
returns 403 without the first and 415 without the second
(`internal/webui/api_tasks.go:376`, `authorizeTaskMutation`). GET sends
(`internal/webui/api_tasks.go`, `authorizeTaskMutation`). GET sends
neither. This is the single most likely thing to silently break every
write after the port.
- [x] **History routing.** `createWebHistory`, `base: "/"`. Legacy `#/path`
links are rewritten by `src/legacy-hash-redirect.ts`. The chat navigate
chip should emit `/tasks`; the Go side already stores bare paths.
- [ ] **Capability gating.** `GET /api/capabilities`
(`internal/webui/api_capabilities.go:20`) returns a `sections` map of ten
(`internal/webui/api_capabilities.go`) returns a `sections` map of ten
booleans: chat, logs, skills, curators, channels, captures, mappings,
bindings, and workflows/settings which are always true. A route whose
section is false must be hidden, not rendered empty. **Fail open**: on a
@@ -50,9 +50,9 @@ does not show up as a broken page.
with no error.
- [ ] **SSE lifecycle.** Three streams, all `id: <n>\ndata: <json>\n\n` except
chat which omits the id:
`/events` (task lifecycle, `sse.go:37`, supports `?since=` and
`Last-Event-ID` resume), `/api/logs/stream` (`api_logs.go:80`, same
resume protocol), `/api/chat/stream` (`api_chat.go:399`, frames typed
`/events` (task lifecycle, `sse.go`, supports `?since=` and
`Last-Event-ID` resume), `/api/logs/stream` (`api_logs.go`, same
resume protocol), `/api/chat/stream` (`api_chat.go`, frames typed
delta/tool/media/navigate). Each must be closed on unmount or the app
leaks a connection per navigation. Preact used an `archie:teardown`
event; Vue should use `onUnmounted`.
@@ -210,9 +210,9 @@ port rather than porting the flat bar first.
throughout; it is the check that a route cannot be added here and
forgotten there.
## Phase 5 — Behaviour shipped today that a naive port loses
## Phase 5 — Behaviour a naive port loses
All of this landed in the last few hours and exists only in the deleted tree.
This behaviour exists only in the deleted tree.
The implementation source for nearly all of it is
`git show e18fb8b2^:ui/src/css/layout.css` plus `main.jsx` and `chat/chat.jsx`.