From 95743b60cc32551687ff87e4caa1283fae27ab2f Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 22 Sep 2026 00:21:28 +1000 Subject: [PATCH] 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. --- docs/prds/adversarial-self-review.md | 20 ++-- docs/prds/channel-forge-positions.md | 8 +- docs/prds/config-example-drift.md | 16 +-- docs/prds/contract-conformance-audit.md | 2 +- docs/prds/control-plane-apply-status.md | 2 +- docs/prds/curator-sampler-wave1.md | 7 +- docs/prds/deep-research-capability.md | 30 +++--- docs/prds/dynamic-curators.md | 14 +-- docs/prds/dynamic-workflow-triage.md | 10 +- docs/prds/eda-playbook-engine.md | 131 +++++++++++------------ docs/prds/event-capture-storage.md | 2 +- docs/prds/event-sources-and-reactions.md | 4 +- docs/prds/extensions-center.md | 12 +-- docs/prds/image-capability-contract.md | 2 +- docs/prds/inline-review.md | 4 +- docs/prds/mcp-tool-completion.md | 38 +++---- docs/prds/memory-engine-unification.md | 38 +++---- docs/prds/module-position.md | 4 +- docs/prds/progressive-tool-disclosure.md | 28 ++--- docs/prds/self-update-transaction.md | 22 ++-- docs/prds/service-decomposition.md | 13 +-- docs/prds/service-registry.md | 16 +-- docs/prds/skill-curator.md | 2 +- docs/prds/state-store-contract.md | 6 +- docs/prds/status-health-surface.md | 33 +++--- docs/prds/ui-service-boundary.md | 6 +- docs/prds/vue-migration-checklist.md | 14 +-- 27 files changed, 236 insertions(+), 248 deletions(-) diff --git a/docs/prds/adversarial-self-review.md b/docs/prds/adversarial-self-review.md index ea56d983b..321ded028 100644 --- a/docs/prds/adversarial-self-review.md +++ b/docs/prds/adversarial-self-review.md @@ -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 diff --git a/docs/prds/channel-forge-positions.md b/docs/prds/channel-forge-positions.md index 72076f54a..f77d0ef55 100644 --- a/docs/prds/channel-forge-positions.md +++ b/docs/prds/channel-forge-positions.md @@ -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 diff --git a/docs/prds/config-example-drift.md b/docs/prds/config-example-drift.md index b549338f0..a392af8cd 100644 --- a/docs/prds/config-example-drift.md +++ b/docs/prds/config-example-drift.md @@ -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..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 diff --git a/docs/prds/contract-conformance-audit.md b/docs/prds/contract-conformance-audit.md index 1f4afcb24..16f39a059 100644 --- a/docs/prds/contract-conformance-audit.md +++ b/docs/prds/contract-conformance-audit.md @@ -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 diff --git a/docs/prds/control-plane-apply-status.md b/docs/prds/control-plane-apply-status.md index af77b5b9f..5424b0e45 100644 --- a/docs/prds/control-plane-apply-status.md +++ b/docs/prds/control-plane-apply-status.md @@ -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. diff --git a/docs/prds/curator-sampler-wave1.md b/docs/prds/curator-sampler-wave1.md index 335d875c0..b1e702186 100644 --- a/docs/prds/curator-sampler-wave1.md +++ b/docs/prds/curator-sampler-wave1.md @@ -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 diff --git a/docs/prds/deep-research-capability.md b/docs/prds/deep-research-capability.md index dc6010e96..5d08763f9 100644 --- a/docs/prds/deep-research-capability.md +++ b/docs/prds/deep-research-capability.md @@ -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 diff --git a/docs/prds/dynamic-curators.md b/docs/prds/dynamic-curators.md index 09f282b9f..20cca7fa6 100644 --- a/docs/prds/dynamic-curators.md +++ b/docs/prds/dynamic-curators.md @@ -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 diff --git a/docs/prds/dynamic-workflow-triage.md b/docs/prds/dynamic-workflow-triage.md index ae3823d6e..18769324f 100644 --- a/docs/prds/dynamic-workflow-triage.md +++ b/docs/prds/dynamic-workflow-triage.md @@ -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. diff --git a/docs/prds/eda-playbook-engine.md b/docs/prds/eda-playbook-engine.md index 55e15b8a5..f5501d441 100644 --- a/docs/prds/eda-playbook-engine.md +++ b/docs/prds/eda-playbook-engine.md @@ -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 diff --git a/docs/prds/event-capture-storage.md b/docs/prds/event-capture-storage.md index 7cf04f852..c065bbfe3 100644 --- a/docs/prds/event-capture-storage.md +++ b/docs/prds/event-capture-storage.md @@ -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 diff --git a/docs/prds/event-sources-and-reactions.md b/docs/prds/event-sources-and-reactions.md index bf9226d81..5338674b6 100644 --- a/docs/prds/event-sources-and-reactions.md +++ b/docs/prds/event-sources-and-reactions.md @@ -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 diff --git a/docs/prds/extensions-center.md b/docs/prds/extensions-center.md index 1b61f7fc2..adb987841 100644 --- a/docs/prds/extensions-center.md +++ b/docs/prds/extensions-center.md @@ -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 | diff --git a/docs/prds/image-capability-contract.md b/docs/prds/image-capability-contract.md index 08ee57eb1..902cc1d71 100644 --- a/docs/prds/image-capability-contract.md +++ b/docs/prds/image-capability-contract.md @@ -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 | diff --git a/docs/prds/inline-review.md b/docs/prds/inline-review.md index 6df6f3548..d382beec7 100644 --- a/docs/prds/inline-review.md +++ b/docs/prds/inline-review.md @@ -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): +(`renderPRReviewSection`, h019.6): `` - `file.go` (confirmed, error): — ``. 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}`. diff --git a/docs/prds/mcp-tool-completion.md b/docs/prds/mcp-tool-completion.md index a9fabef39..18dfdfe6b 100644 --- a/docs/prds/mcp-tool-completion.md +++ b/docs/prds/mcp-tool-completion.md @@ -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`) | diff --git a/docs/prds/memory-engine-unification.md b/docs/prds/memory-engine-unification.md index 5e7642861..2ebe8e6cb 100644 --- a/docs/prds/memory-engine-unification.md +++ b/docs/prds/memory-engine-unification.md @@ -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`) | `/memory` | `MEMORY.md` / `USER.md` | -| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go:163`) | `/memory-engine` | identity-keyed blocks | +| `internal/memory` (`Manager`, `builtin.Provider`) | the chat agent's `memory_edit` tool via `memorytoolprovider` (`bootstrap.go`) | `/memory` | `MEMORY.md` / `USER.md` | +| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go`) | `/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 `` (line 41) and `` (line 50): +`templates/archie.md.tpl` between the `` and `` blocks: ``` @@ -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. diff --git a/docs/prds/module-position.md b/docs/prds/module-position.md index 3492c9035..5461ddc95 100644 --- a/docs/prds/module-position.md +++ b/docs/prds/module-position.md @@ -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 diff --git a/docs/prds/progressive-tool-disclosure.md b/docs/prds/progressive-tool-disclosure.md index fa234001c..79daf41d9 100644 --- a/docs/prds/progressive-tool-disclosure.md +++ b/docs/prds/progressive-tool-disclosure.md @@ -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`). diff --git a/docs/prds/self-update-transaction.md b/docs/prds/self-update-transaction.md index 3195b878e..24452a420 100644 --- a/docs/prds/self-update-transaction.md +++ b/docs/prds/self-update-transaction.md @@ -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" | ""` 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 | diff --git a/docs/prds/service-decomposition.md b/docs/prds/service-decomposition.md index 09df40867..c444e7f1c 100644 --- a/docs/prds/service-decomposition.md +++ b/docs/prds/service-decomposition.md @@ -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//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 diff --git a/docs/prds/service-registry.md b/docs/prds/service-registry.md index 6afe622fc..11a4256fd 100644 --- a/docs/prds/service-registry.md +++ b/docs/prds/service-registry.md @@ -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. diff --git a/docs/prds/skill-curator.md b/docs/prds/skill-curator.md index 41c4a3203..27bcdcad4 100644 --- a/docs/prds/skill-curator.md +++ b/docs/prds/skill-curator.md @@ -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. diff --git a/docs/prds/state-store-contract.md b/docs/prds/state-store-contract.md index 20f1a6daf..7f55a2b48 100644 --- a/docs/prds/state-store-contract.md +++ b/docs/prds/state-store-contract.md @@ -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`). diff --git a/docs/prds/status-health-surface.md b/docs/prds/status-health-surface.md index 08899fe84..97510c76f 100644 --- a/docs/prds/status-health-surface.md +++ b/docs/prds/status-health-surface.md @@ -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()`. diff --git a/docs/prds/ui-service-boundary.md b/docs/prds/ui-service-boundary.md index a9b68c716..ffe7b28a9 100644 --- a/docs/prds/ui-service-boundary.md +++ b/docs/prds/ui-service-boundary.md @@ -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 | diff --git a/docs/prds/vue-migration-checklist.md b/docs/prds/vue-migration-checklist.md index d7ea535d1..ffa33f223 100644 --- a/docs/prds/vue-migration-checklist.md +++ b/docs/prds/vue-migration-checklist.md @@ -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: \ndata: \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`.