docs(prds): remove session-bound writing from every PRD
183 findings across 28 of 46 PRDs, of which 150 were file:line citations. Two
were already hard-broken: one named a file that no longer exists, one pointed
past the end of its file. The rest resolved to a line that still exists,
which is the worse failure -- a citation that silently drifted onto unrelated
code still reads as authoritative.
Citations now name the file and the symbol. Dated status markers become the
decision they carried ("Status 2026-09-05: resolved" -> "Resolved"), since
whether a question is answered is design information and when it was answered
is not. Progress inventories become scope statements: mcp-tool-completion now
fences what is out of scope rather than reporting what shipped.
status-health-surface drops phase-completion from its headings and keeps the
rule that earned them, that a reported field must have a truthful source.
eda-playbook-engine.md was the worst file and my own t2db.23 status block was
part of why; it is rewritten as the resolution it records.
This commit is contained in:
27 files changed
+236
-248
No files matched your search
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -29,7 +29,7 @@ useful. Three verified reasons, in order of weight:
|
||||
rejects "a reflection-based schema over `config.Config`" because the struct is
|
||||
"scheduled for dissolution". A generator deriving the example from its struct
|
||||
tags would build on a foundation this repo has already decided to remove.
|
||||
3. **`docs/architecture/generated-documentation.md:225` prohibits it.** "Adding
|
||||
3. **`docs/architecture/generated-documentation.md` prohibits it.** "Adding
|
||||
another hardcoded type list to `docsgen` is prohibited" — so any generator
|
||||
must consume a domain-owned registry, which does not exist for configuration
|
||||
yet. Creating one is the config-domain migration's job, not this change's.
|
||||
@@ -42,7 +42,7 @@ machinery to remove duplication that largely is not there.
|
||||
## The gap that is real
|
||||
|
||||
**Unknown config keys are silently ignored.** Verified at
|
||||
`internal/infrastructure/configuration/decode.go:27`:
|
||||
`internal/infrastructure/configuration/decode.go`:
|
||||
|
||||
```go
|
||||
if _, err := toml.DecodeFile(path, target); err != nil {
|
||||
@@ -55,7 +55,7 @@ is also detectable **without any hand-maintained list**, because `BurntSushi/tom
|
||||
reports exactly which keys the target did not consume.
|
||||
|
||||
Note the second, separate gap already admitted in writing:
|
||||
`generated-documentation.md:331` — "`task check` does not run `docs:check`, so
|
||||
`generated-documentation.md` — "`task check` does not run `docs:check`, so
|
||||
generated drift is currently ungated."
|
||||
|
||||
## What to build
|
||||
@@ -68,7 +68,7 @@ keys, and expose it so tests can assert emptiness.
|
||||
startup policy is "a missing credential disables a capability; only an invalid
|
||||
config stops the daemon". A stray key is far more likely to be an operator typo
|
||||
in a file they are otherwise happy with than a reason to refuse to boot, and
|
||||
`[web]` is already documented as landing in a *different* binary
|
||||
`[web]` is documented as landing in a *different* binary
|
||||
(`internal/app/archieui`), so a key unknown to one process is legitimately known
|
||||
to another. Failing closed here would break working deployments on upgrade.
|
||||
|
||||
@@ -102,13 +102,13 @@ deferred, not rejected.
|
||||
|
||||
## A withdrawn premise, recorded so it is not reused
|
||||
|
||||
An earlier measurement in this session claimed 17 keys were "set by a profile
|
||||
but documented by no example", and used it to argue for generation. It was an
|
||||
An earlier measurement claimed 17 keys were "set by a profile but documented
|
||||
by no example", and used it to argue for generation. It was an
|
||||
artifact: the extractor stripped comment markers and tracked a single table
|
||||
variable, so commented blocks were mis-attributed. Re-checking refuted it —
|
||||
`providers.<name>.api_key_env` is a real, documented backwards-compatible field
|
||||
(`internal/config/config.go:180`, `config.example.toml:101`) and `[[identities]]`
|
||||
is documented at `config.example.toml:53`. The decision above does not rest on
|
||||
(`internal/config/config.go`, `config.example.toml`) and `[[identities]]`
|
||||
is documented at `config.example.toml`. The decision above does not rest on
|
||||
that measurement.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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 |
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
## Problem
|
||||
|
||||
Findings reach the operator only as a flat list in the PR body
|
||||
(`renderPRReviewSection`, h019.6): `` - `file.go:12` (confirmed, error): <defect>
|
||||
(`renderPRReviewSection`, h019.6): `` - `file.go` (confirmed, error): <defect>
|
||||
— <scenario> ``. That is a report *about* the code, not a review *of* it. A real
|
||||
reviewer anchors each finding to the line it is about, so the author sees it in
|
||||
context — and, when the fix is mechanical, attaches the replacement so it can be
|
||||
@@ -51,7 +51,7 @@ those line numbers were **measured on** (`TaskContext.ReviewedHeadSHA`,
|
||||
recorded when `StageOpenPR` opens the pull request), and the implementation
|
||||
posts only while the head it read still matches it — see §4.
|
||||
|
||||
Per-forge reality (verified against the SDKs, 2026-09-11):
|
||||
Per-forge reality, verified against the SDKs:
|
||||
|
||||
- **GitHub** — direct: `PullRequests.CreateComment` with
|
||||
`{Body, Path, Line, Side: "RIGHT", CommitID}`.
|
||||
|
||||
@@ -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`) |
|
||||
|
||||
@@ -18,11 +18,11 @@ writes them, and the chat turn reads neither.
|
||||
|
||||
| Family | Written by | Root | Format |
|
||||
|---|---|---|---|
|
||||
| `internal/memory` (`Manager`, `builtin.Provider`) | the chat agent's `memory_edit` tool via `memorytoolprovider` (`bootstrap.go:1198`) | `<workDir>/memory` | `MEMORY.md` / `USER.md` |
|
||||
| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go:163`) | `<workDir>/memory-engine` | identity-keyed blocks |
|
||||
| `internal/memory` (`Manager`, `builtin.Provider`) | the chat agent's `memory_edit` tool via `memorytoolprovider` (`bootstrap.go`) | `<workDir>/memory` | `MEMORY.md` / `USER.md` |
|
||||
| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go`) | `<workDir>/memory-engine` | identity-keyed blocks |
|
||||
|
||||
They share no code, no format and no scope vocabulary. Neither reaches a prompt:
|
||||
`Manager.SystemPromptBlock` (`internal/memory/manager.go:429`) has no production
|
||||
`Manager.SystemPromptBlock` (`internal/memory/manager.go`) has no production
|
||||
caller anywhere, so the agent can write memory through a tool and never read it
|
||||
back.
|
||||
|
||||
@@ -33,16 +33,16 @@ Three further defects fall out of the same split:
|
||||
*does* have `handleAdd`/`handleReplace`/`handleRemove`, so the family being
|
||||
deleted is operationally richer than its replacement.
|
||||
2. **There is no scope model.** The contract carries one opaque `Identity
|
||||
string`, and the curator fills it with a **session id** (`sessioncurator.go:164`)
|
||||
— which is none of the four scopes `docs/architecture/agent-system.md:69-78`
|
||||
string`, and the curator fills it with a **session id** (`sessioncurator.go`)
|
||||
— which is none of the four scopes `docs/architecture/agent-system.md`
|
||||
requires, and stops meaning anything when the session ends.
|
||||
3. **The chat turn has no user identity on half the channels.** `SenderID` is
|
||||
populated by Telegram and email (a person) and by webhook (a **route path**,
|
||||
`webhook.go:179`), and not at all by the dashboard, whose gateway wire message
|
||||
`webhook.go`), and not at all by the dashboard, whose gateway wire message
|
||||
carries no sender field. It is also never persisted: `sender_id` appears
|
||||
nowhere in `session_store_sqlite.go`.
|
||||
|
||||
`agent-system.md:100` says the write-scope selection and cross-scope sharing
|
||||
`agent-system.md` says the write-scope selection and cross-scope sharing
|
||||
rules "require a focused memory design decision". This is that decision.
|
||||
|
||||
## Decision
|
||||
@@ -93,7 +93,7 @@ exactly the scopes of the resolved `Subject`; the engine never unions beyond wha
|
||||
it is handed and applies no policy of its own. An engine that enforced policy
|
||||
would need to know about channels, sessions and bindings, and every backend would
|
||||
reimplement it. "Agent-wide is private to its owning Agent by default"
|
||||
(`agent-system.md:80-81`) falls out mechanically, because `ScopeAgent{a}` and
|
||||
(`agent-system.md`) falls out mechanically, because `ScopeAgent{a}` and
|
||||
`ScopeAgent{b}` are different storage keys.
|
||||
|
||||
`ScopeGlobal` is never model-writable. Writing it is an operator action; nothing
|
||||
@@ -114,10 +114,10 @@ type Store interface {
|
||||
```
|
||||
|
||||
`Get` and `Forget` take a scope. The current `Forget` scans every identity's
|
||||
store to find a marker (`builtin_engine.go:189-210`) purely because the contract
|
||||
store to find a marker (`builtin_engine.go`) purely because the contract
|
||||
gave it nothing better.
|
||||
|
||||
`Record` carries what `agent-system.md:97-99` requires be retained: `Scope`,
|
||||
`Record` carries what `agent-system.md` requires be retained: `Scope`,
|
||||
`Kind`, `Content`, `Revision`, `Author`, `OriginUser`, `Source`, `CreatedAt`,
|
||||
`UpdatedAt`. `Metadata` is dropped — nothing sets it and the parser never
|
||||
restores it, so it is currently a field that silently does not round-trip.
|
||||
@@ -150,19 +150,19 @@ UserIdentity func(msg messaging.Message) (IdentityID, bool)
|
||||
|
||||
This must be injectable rather than a blanket `channel + ":" + SenderID`
|
||||
concatenation, because a **webhook's `SenderID` is a route path**
|
||||
(`webhook.go:179`), not a person; treating it as one would give a URL an
|
||||
(`webhook.go`), not a person; treating it as one would give a URL an
|
||||
identity. Telegram and email supply their sender id; the dashboard and webhook
|
||||
resolve nothing.
|
||||
|
||||
**Fail closed.** When `UserID` is empty the turn proceeds with global and agent
|
||||
scopes only, and a write targeting `user` or `agent-user` fails with a clear
|
||||
error. `agent-system.md:92-94` forbids showing one user's memory to another, so
|
||||
error. `agent-system.md` forbids showing one user's memory to another, so
|
||||
"we do not know who this is" must mean "show none of it", never "fall back to a
|
||||
wider scope".
|
||||
|
||||
### 4. The chat read path
|
||||
|
||||
Synchronous and total. It runs inside `prepareTurn` (`turn.go:287`) before the
|
||||
Synchronous and total. It runs inside `prepareTurn` (`turn.go`) before the
|
||||
prompt is built, never returns an error to the caller, and degrades to an empty
|
||||
block on any engine failure or provider panic. A fire-and-forget hook would race
|
||||
the prompt build in the same turn, which is why this is not a lifecycle hook.
|
||||
@@ -172,7 +172,7 @@ search, which remains open in `migration-decisions.md#5`. A ranked read on the
|
||||
hot path with no ranking implementation would be a lie.
|
||||
|
||||
`SystemPromptConfig` gains a `Memory` field, rendered into
|
||||
`templates/archie.md.tpl` between `<tools>` (line 41) and `<env>` (line 50):
|
||||
`templates/archie.md.tpl` between the `<tools>` and `<env>` blocks:
|
||||
|
||||
```
|
||||
<memory purpose="durable_context" trust="data">
|
||||
@@ -188,8 +188,8 @@ Both a per-scope record limit and a byte cap on the rendered block are named
|
||||
constants. The cap is about size, not latency; a local read needs no timeout.
|
||||
|
||||
**Prerequisite:** `setupGateways` runs before `setupMemoryAll`
|
||||
(`main.go:414` vs `:428`), and `startGatewayRuntime` before `setupMemory`
|
||||
(`gateway.go:110` vs `:115`), so the engine is nil at every turn-runner
|
||||
(`main.go` vs `:428`), and `startGatewayRuntime` before `setupMemory`
|
||||
(`gateway.go` vs `:115`), so the engine is nil at every turn-runner
|
||||
construction site. The ordering is the root-cause fix and nothing in either
|
||||
memory step reads what those later steps produce.
|
||||
|
||||
@@ -208,7 +208,7 @@ must write into a scope derived from the turn's resolved subject:
|
||||
**The model chooses the scope kind; it never chooses the ids.** Agent and user
|
||||
ids come from the turn's resolution and there is no schema field to put anything
|
||||
else in — even a model that emits another user's id has nowhere to write it. That
|
||||
is the root-cause form of `agent-system.md:87-90`, matching this system's other
|
||||
is the root-cause form of `agent-system.md`, matching this system's other
|
||||
non-waivable boundaries (the model never runs git; gates cannot be waived by the
|
||||
agent). `global` is not offered at all.
|
||||
|
||||
@@ -240,7 +240,7 @@ curator's bad note becomes id-addressable and therefore correctable by the agent
|
||||
|
||||
### 7. The content scanner moves to the engine
|
||||
|
||||
`internal/memory/scanner.go` and its installation at `bootstrap.go:1045` are what
|
||||
`internal/memory/scanner.go` and its installation at `bootstrap.go` are what
|
||||
make `configuration.md`'s "Memory safety scanner" row describe a control that
|
||||
actually runs. Deleting the package would silently remove prompt-injection
|
||||
scanning on memory writes. The scanner moves into the engine and is applied in
|
||||
@@ -260,7 +260,7 @@ engine already parses that format.
|
||||
Also deleted: `internal/tools/provider/memory`'s manager wrapping (rewired to the
|
||||
engine), `config.Memory.{Provider,ProviderConfig}` and the
|
||||
`validateMemory` rejection that exists only to complain about `Provider`
|
||||
(`validate.go:143-154`), and `webui.MemoryStatus`/`MemoryProviderHandle` — never
|
||||
(`validate.go`), and `webui.MemoryStatus`/`MemoryProviderHandle` — never
|
||||
implemented in production, so `/api/memory` reports empty forever unless it is
|
||||
repointed at the engine registry.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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`).
|
||||
@@ -10,7 +10,7 @@ this document — it stays a thin Go interface shelling out to
|
||||
adapter scripts (`scripts/archie-update-{check,install,watchdog}`) and
|
||||
`install.sh` do behind that contract, and settles the one thing the epic's
|
||||
own description got wrong: the dist-zip **is** already attached to GitHub
|
||||
Releases (`.github/workflows/deploy.yml:283-316`, `gh release upload`), not
|
||||
Releases (`.github/workflows/deploy.yml`, `gh release upload`), not
|
||||
Actions-artifact-only. Artifact install is therefore a smaller change than
|
||||
the epic assumed — pointing the installer at an existing asset, not standing
|
||||
up new CI publishing. Topology migration and the journaled transaction are
|
||||
@@ -32,7 +32,7 @@ script not using it is a missed-reuse gap, not a missing-CI gap.
|
||||
deployment profile (`deployments/*.toml`) declares `[services.state]` and
|
||||
`[services.gateway]` sections needing their own units — a fresh install
|
||||
already reproduces the broken single-unit shape `deployment_contract_test.go`
|
||||
(lines 70-105) doesn't even catch, because that test only checks profile
|
||||
doesn't even catch, because that test only checks profile
|
||||
syntax, not installed topology. No code anywhere enumerates which systemd
|
||||
units exist on a host or compares that against what a release requires — the
|
||||
daemon fails at `bootstrap.go`'s `[services.state].target` check with no
|
||||
@@ -55,13 +55,13 @@ opt-in path selected by an explicit `--from-source` flag or
|
||||
every-host update is strictly slower and has a larger failure surface than
|
||||
downloading a signed asset that CI already produced.
|
||||
|
||||
**Call site.** `scripts/archie-update-install` — replace the body currently
|
||||
at lines 139-160 with a download-and-verify step; move the existing
|
||||
**Call site.** `scripts/archie-update-install` — replace the clone+compile
|
||||
body with a download-and-verify step; move the existing
|
||||
clone+compile body behind the opt-in flag rather than deleting it.
|
||||
`internal/releaseupdate/command.go:44-48` (`CommandInstaller`) is unchanged —
|
||||
`internal/releaseupdate/command.go` (`CommandInstaller`) is unchanged —
|
||||
it already just shells out.
|
||||
|
||||
**Reuse check.** `deploy.yml:265-316` already builds and publishes the
|
||||
**Reuse check.** `deploy.yml` already builds and publishes the
|
||||
archive and uploads it as both an Actions artifact and a release asset; no
|
||||
new CI work is needed, only pointing the installer at what exists.
|
||||
|
||||
@@ -118,7 +118,7 @@ needs a real systemd host; manual smoke test only.
|
||||
### Journaled transaction (`#804` item 3)
|
||||
|
||||
**Decision.** Replace `archie-update-install`'s copy-and-trap body with: (1)
|
||||
pre-flight (existing check at line 170, kept), (2) write an intent journal
|
||||
pre-flight (the existing check, kept), (2) write an intent journal
|
||||
to a path outside every directory the install touches — e.g.
|
||||
`${XDG_STATE_HOME:-~/.local/state}/archie/update.journal` — recording the
|
||||
candidate version, the topology plan (if any), and each binary's
|
||||
@@ -163,7 +163,7 @@ start/stop as part of rollback needs a real host; manual smoke command.
|
||||
**Decision.** Add `channel = "stable" | "next" | "<exact-version-pin>"`
|
||||
to whatever config section already governs update behavior (next to
|
||||
`ARCHIE_UPDATE_CHANNEL`'s existing chat-channel field in
|
||||
`internal/releaseupdate/command.go:62` — name this new field distinctly,
|
||||
`internal/releaseupdate/command.go` — name this new field distinctly,
|
||||
e.g. `ReleaseChannel`, to avoid colliding with the existing chat-notification
|
||||
channel of the same word). `Catalog.Check` filters candidate releases by
|
||||
this field before returning the newest match. Runtime image pinning: every
|
||||
@@ -191,12 +191,12 @@ is a shell-script unit test against a fixture profile.
|
||||
| concern | file | change |
|
||||
|---|---|---|
|
||||
| Update contract (Catalog/Installer interfaces) | `internal/releaseupdate/service.go` | none — already handles this |
|
||||
| Command adapters | `internal/releaseupdate/command.go:22,44-48,62` | new `ReleaseChannel` field distinct from existing chat-channel field |
|
||||
| Command adapters | `internal/releaseupdate/command.go` | new `ReleaseChannel` field distinct from existing chat-channel field |
|
||||
| Install script body | `scripts/archie-update-install:139-160,170,195-199` | replace clone+compile default with download+verify; add journal, lock, stage-then-rename, digest check |
|
||||
| CI release publishing | `.github/workflows/deploy.yml:265-316` | none — already handles this |
|
||||
| CI release publishing | `.github/workflows/deploy.yml` | none — already handles this |
|
||||
| Deployment profiles | `deployments/*.toml` | none — already digest-pinned |
|
||||
| First-install unit creation | `install.sh:414-445` | change — consume shared topology declaration |
|
||||
| Topology assertions | `deployment_contract_test.go:70-105` | new assertion: profile topology matches install.sh output |
|
||||
| Topology assertions | `deployment_contract_test.go` | new assertion: profile topology matches install.sh output |
|
||||
| Topology observation | `internal/app/archied/bootstrap.go` (new sibling code) | new |
|
||||
| Resume-on-boot rollback | `internal/app/archied` startup | new |
|
||||
| Health check reuse for candidate verification | `internal/domain/health` | reuse — confirm exact symbol before implementing |
|
||||
|
||||
@@ -1,9 +1,6 @@
|
||||
# Service decomposition -- decision
|
||||
|
||||
**Status:** Proposed -- not yet approved for implementation
|
||||
**Progress:** Phases 1 (Gateway), 2 (State Store) and 3 (UI) shipped; Phase 4
|
||||
(Messaging) is ready, Phase 5 (Execution/Runner/Scheduler) and Phase 6
|
||||
(Curator, optional) remain chained behind it.
|
||||
**Date:** 2026-09-05
|
||||
**Beads epic:** archie-core-8cda
|
||||
**Prior art:** `docs/inspiration/2026-09-05-awx-service-decomposition-and-ansible-task-model.md`,
|
||||
@@ -132,7 +129,7 @@ historical record rather than an outstanding gate.
|
||||
`ChatContract` should exist before UI Service is extracted, since UI is
|
||||
the most entangled consumer today. Not yet sequenced.
|
||||
|
||||
**RESOLVED (2026-09-05).** Gateway Service first, then State Store,
|
||||
**RESOLVED.** Gateway Service first, then State Store,
|
||||
then UI, then Messaging, then Execution/Runner/Scheduler, then Curator
|
||||
(optional) — preceded by an in-process "contract seams" (modular
|
||||
monolith) phase. Confirms the hypothesis and strengthens it: the
|
||||
@@ -145,7 +142,7 @@ historical record rather than an outstanding gate.
|
||||
need a home (a new `proto/` or `contracts/` tree, versioning scheme,
|
||||
codegen wiring into `Taskfile.yml`). Not yet designed.
|
||||
|
||||
**RESOLVED (2026-09-05).** buf v2 driving `protoc-gen-go` +
|
||||
**RESOLVED.** buf v2 driving `protoc-gen-go` +
|
||||
`protoc-gen-go-grpc` (grpc-go, not connect-go — connect-go's net/http
|
||||
client breaks the discovery research's gRPC resolver plumbing for K8s
|
||||
DNS and NATS-KV). One committed `proto/<service>/v1/` tree, generated
|
||||
@@ -164,7 +161,7 @@ historical record rather than an outstanding gate.
|
||||
one. Strongly recommend the former for a solo maintainer, but not
|
||||
decided here.
|
||||
|
||||
**RESOLVED (2026-09-05).** Multiplexed in-process is the migration
|
||||
**RESOLVED.** Multiplexed in-process is the migration
|
||||
default -- this is `docs/architecture/organisation.md`'s standing
|
||||
"Process boundaries" rule, not a new lean. Mechanism: one wire-safe Go
|
||||
contract interface per service; a local adapter and a generated gRPC
|
||||
@@ -194,7 +191,7 @@ historical record rather than an outstanding gate.
|
||||
State Store service's contract (less isolation, less migration risk).
|
||||
Not yet decided.
|
||||
|
||||
**RESOLVED (2026-09-05).** One State Store service owns the existing
|
||||
**RESOLVED.** One State Store service owns the existing
|
||||
single SQLite file behind narrow typed contracts (`TaskStore`,
|
||||
`CaptureStore`, `MappingStore`, `BindingStore`, `WorkflowStore`) over
|
||||
gRPC. *(Ratified 2026-09-06: the workflow contract is now the
|
||||
@@ -230,7 +227,7 @@ historical record rather than an outstanding gate.
|
||||
and a `docker-compose.yml`, not Kubernetes manifests). Scoping not yet
|
||||
started.
|
||||
|
||||
**RESOLVED (2026-09-05).** Three charts: an `archie-library` chart
|
||||
**RESOLVED.** Three charts: an `archie-library` chart
|
||||
(shared Deployment/Service templates, named ports), an `archie` chart
|
||||
for the 7 core services, and an `archie-curator` chart + Curator
|
||||
Operator (CRD, controller, RBAC). The Curator reconciler is a
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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`).
|
||||
|
||||
@@ -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()`.
|
||||
|
||||
@@ -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 |
|
||||
|
||||
|
||||
@@ -30,14 +30,14 @@ does not show up as a broken page.
|
||||
- [ ] **Mutation headers.** Every POST/PATCH/DELETE must send **both**
|
||||
`X-Archie-CSRF: 1` and `Content-Type: application/json`. The server
|
||||
returns 403 without the first and 415 without the second
|
||||
(`internal/webui/api_tasks.go:376`, `authorizeTaskMutation`). GET sends
|
||||
(`internal/webui/api_tasks.go`, `authorizeTaskMutation`). GET sends
|
||||
neither. This is the single most likely thing to silently break every
|
||||
write after the port.
|
||||
- [x] **History routing.** `createWebHistory`, `base: "/"`. Legacy `#/path`
|
||||
links are rewritten by `src/legacy-hash-redirect.ts`. The chat navigate
|
||||
chip should emit `/tasks`; the Go side already stores bare paths.
|
||||
- [ ] **Capability gating.** `GET /api/capabilities`
|
||||
(`internal/webui/api_capabilities.go:20`) returns a `sections` map of ten
|
||||
(`internal/webui/api_capabilities.go`) returns a `sections` map of ten
|
||||
booleans: chat, logs, skills, curators, channels, captures, mappings,
|
||||
bindings, and workflows/settings which are always true. A route whose
|
||||
section is false must be hidden, not rendered empty. **Fail open**: on a
|
||||
@@ -50,9 +50,9 @@ does not show up as a broken page.
|
||||
with no error.
|
||||
- [ ] **SSE lifecycle.** Three streams, all `id: <n>\ndata: <json>\n\n` except
|
||||
chat which omits the id:
|
||||
`/events` (task lifecycle, `sse.go:37`, supports `?since=` and
|
||||
`Last-Event-ID` resume), `/api/logs/stream` (`api_logs.go:80`, same
|
||||
resume protocol), `/api/chat/stream` (`api_chat.go:399`, frames typed
|
||||
`/events` (task lifecycle, `sse.go`, supports `?since=` and
|
||||
`Last-Event-ID` resume), `/api/logs/stream` (`api_logs.go`, same
|
||||
resume protocol), `/api/chat/stream` (`api_chat.go`, frames typed
|
||||
delta/tool/media/navigate). Each must be closed on unmount or the app
|
||||
leaks a connection per navigation. Preact used an `archie:teardown`
|
||||
event; Vue should use `onUnmounted`.
|
||||
@@ -210,9 +210,9 @@ port rather than porting the flat bar first.
|
||||
throughout; it is the check that a route cannot be added here and
|
||||
forgotten there.
|
||||
|
||||
## Phase 5 — Behaviour shipped today that a naive port loses
|
||||
## Phase 5 — Behaviour a naive port loses
|
||||
|
||||
All of this landed in the last few hours and exists only in the deleted tree.
|
||||
This behaviour exists only in the deleted tree.
|
||||
The implementation source for nearly all of it is
|
||||
`git show e18fb8b2^:ui/src/css/layout.css` plus `main.jsx` and `chat/chat.jsx`.
|
||||
|
||||
|
||||
Reference in new issue
Block a user