diff --git a/docs/prds/01-project-management.md b/docs/prds/01-project-management.md index a519747e9..739fb6a1c 100644 --- a/docs/prds/01-project-management.md +++ b/docs/prds/01-project-management.md @@ -1,6 +1,6 @@ # Architecture Decision Index -**Status:** Approved foundation; domain and package reviews are ongoing +**Status:** Approved **Date:** 2026-07-28 **Beads issue:** `archie-core-5d7` diff --git a/docs/prds/RULES.md b/docs/prds/RULES.md index 2190bc6d7..4d1ec5f82 100644 --- a/docs/prds/RULES.md +++ b/docs/prds/RULES.md @@ -29,9 +29,14 @@ These rules apply to every file in `docs/prds/`. - Write nothing whose truth expires. No `file.go:123` citations (cite the file and the symbol), no progress reports on the work being designed, no dated status claims, and no record of how a finding was produced. A phased plan is - durable design; which phase is finished is not. `task docs:prds` enforces - this. -- Every PRD carries one of three statuses. `Draft` until the maintainer - explicitly approves it, `Approved` once they have and while the work is being - built, `Finalised` when the work is complete. A finalised PRD does not change; - supersede it with a new one instead. + durable design; which phase is finished is not. Do not refer to what this + document used to say: the reader cannot see it. A supersede marker is fine + when it names a file, a section or a symbol they can find. `task docs:prds` + enforces this. +- Every PRD carries one of three statuses, and nothing else in that field. + `Draft` until the maintainer explicitly approves it, `Approved` once they + have and while the work is being built, `Finalised` when the work is + complete. A finalised PRD does not change; supersede it with a new one + instead. A revision number belongs in `**Revision:**`, a pointer to the + authoritative document in `**Authority:**`, and what a past revision changed + belongs in git. diff --git a/docs/prds/adversarial-self-review.md b/docs/prds/adversarial-self-review.md index 321ded028..4a6b0386b 100644 --- a/docs/prds/adversarial-self-review.md +++ b/docs/prds/adversarial-self-review.md @@ -1,7 +1,8 @@ # Adversarial self-review stage -- decision -**Status:** Promoted to `docs/architecture/adversarial-review.md` (h019.7) — that document describes the stage as shipped and is authoritative. This PRD remains as the design-decision record. -**Date:** 2026-08-22, section 1 replaced 2026-08-25 +**Status:** Finalised +**Authority:** `docs/architecture/adversarial-review.md` describes the stage and is authoritative. This PRD remains the design-decision record. +**Date:** 2026-08-22 **Beads issue:** `archie-core-h019.1`, blocks `h019.2/.3/.4/.5` > **Section 1 is superseded by the decision below.** diff --git a/docs/prds/binding-secret-encryption.md b/docs/prds/binding-secret-encryption.md index a6533e184..bd9c7c4b9 100644 --- a/docs/prds/binding-secret-encryption.md +++ b/docs/prds/binding-secret-encryption.md @@ -1,6 +1,6 @@ # Binding secret at-rest encryption -- decision -**Status:** Decided, to be implemented +**Status:** Approved **Date:** 2026-09-02 **Beads issue:** `archie-core-t2db.7` (P2), parent `archie-core-t2db` @@ -18,7 +18,7 @@ Encrypt the `secret` column at rest with **AES-256-GCM** (stdlib `crypto/aes` + `crypto/cipher`, no new dependency), transparently inside the store: encrypt on write, decrypt on read. The store is the data boundary; its consumers (dispatch loop, HMAC verification) receive the plaintext secret -exactly as today, and the webui already blanks `Secret` on every response. +exactly as and the webui already blanks `Secret` on every response. ### Cipher parameters diff --git a/docs/prds/channel-forge-positions.md b/docs/prds/channel-forge-positions.md index f77d0ef55..6119cc84c 100644 --- a/docs/prds/channel-forge-positions.md +++ b/docs/prds/channel-forge-positions.md @@ -1,7 +1,7 @@ # Channel and Forge action positions (resolves `t2db.19`) **Status:** Draft -**Date:** 2026-09-03, Channel resolved 2026-09-22 +**Date:** 2026-09-03 **Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db` **Blocked on:** `archie-core-t2db.24` (the `playbook_dispatches` ledger) for implementation of either position. Both are side-effecting, and `t2db.17` @@ -9,9 +9,9 @@ resolved the keying scheme in design only. ## Forge -`internal/forge.Forge` is already exactly the shape a native-Go action -position needs -- a real, typed, general-purpose interface, not something -that needs a Yaegi/Module-style schema-generation detour: +`internal/forge.Forge` is already exactly the shape a native-Go action position +needs -- a real, typed, general-purpose interface, not something that needs a +Yaegi/Module-style schema-generation detour: ```go type Forge interface { @@ -21,54 +21,48 @@ type Forge interface { } ``` -**Typed contract shape: native-Go-by-name, not a Module-kind.** Module's -whole reason to exist is giving *Yaegi-authored, operator-supplied* code a -typed contract to implement. `Forge` is already a typed Go interface with -real, tested implementations (GitHub, Gitea) selected at daemon startup by -`forge.New(...)`. Wrapping it in a Module-kind schema/`go:generate` detour -would duplicate a contract that already exists. A Forge action position -should be: a small set of named operations (e.g. `close-issue`, `create-pr`, -`link-branch`), each with a typed `Args`/`Result` struct mirroring the -matching method's parameters/return. +**Typed contract shape: native-Go-by-name, not a Module-kind.** Module's whole +reason to exist is giving _Yaegi-authored, operator-supplied_ code a typed +contract to implement. `Forge` is already a typed Go interface with real, tested +implementations (GitHub, Gitea) selected at daemon startup by `forge.New(...)`. +Wrapping it in a Module-kind schema/`go:generate` detour would duplicate a +contract that already exists. A Forge action position should be: a small set of +named operations (e.g. `close-issue`, `create-pr`, `link-branch`), each with a +typed `Args`/`Result` struct mirroring the matching method's parameters/return. The dispatch target is `internal/domain/workflow.Forger` -(`CloseIssue`/`CreatePR`/`LinkBranch` -- already exists, already exactly -these three operations), **not** `internal/forge.Forge` directly. -`organisation.md`'s target structure places `forge/` under -`internal/infrastructure/forge/`; today's `internal/forge` is a flat, -unmigrated legacy package in the same position `internal/workflow` was in -before its own migration. A new domain package depending on the flat -package directly would create a domain-to-infrastructure dependency that -breaks the moment `forge` migrates. `workflow.Forger` is the narrow, -already-domain-owned contract that exists for exactly this reason -- the -daemon's real `forge.Forge` client already satisfies it at the wiring -layer today. Depend on `Forger`, not on `internal/forge`. +(`CloseIssue`/`CreatePR`/`LinkBranch` -- already exists, already exactly these +three operations), **not** `internal/forge.Forge` directly. `organisation.md`'s +target structure places `forge/` under `internal/infrastructure/forge/`; the flat +`internal/forge` is a flat, unmigrated legacy package in the same position +`internal/workflow` was in before its own migration. A new domain package +depending on the flat package directly would create a domain-to-infrastructure +dependency that breaks the moment `forge` migrates. `workflow.Forger` is the +narrow, already-domain-owned contract that exists for exactly this reason -- the +daemon's real `forge.Forge` client satisfies it at the wiring layer. +Depend on `Forger`, not on `internal/forge`. **Operation scope for a first slice:** `close-issue` and `link-branch` -(single-call, cleanly idempotent by event+issue identity) are the safe -starting set. `create-pr` is explicitly a heavier case -- opening a PR is a -harder-to-reverse action with its own dedup shape beyond "did this event -fire before" (a redelivered event must not open a second PR for the same -logical change) -- defer it to a follow-up slice once the keying scheme is -proven on the simpler operations, don't design it blind now. +(single-call, cleanly idempotent by event+issue identity) are the safe starting +set. `create-pr` is explicitly a heavier case -- opening a PR is a +harder-to-reverse action with its own dedup shape beyond "did this event fire +before" (a redelivered event must not open a second PR for the same logical +change) -- defer it to a follow-up slice once the keying scheme is proven on the +simpler operations, don't design it blind now. **Host access:** the coordinator needs the same `Forge` instance `internal/daemon`'s poller already holds (constructed once at startup via -`forge.New`). This is a daemon-composition wiring question (pass the -existing instance into the coordinator's constructor), not a new -extensibility mechanism. +`forge.New`). This is a daemon-composition wiring question (pass the existing +instance into the coordinator's constructor), not a new extensibility mechanism. ## Channel -Supersedes the 2026-09-03 open question on this position. - ### Constraints this satisfies -Messaging is the root, Channel is the integration layer, an implementation -such as Telegram sits under Channel. A channel is added by implementing one -reusable interface, and every channel must implement it. A notification -mechanism belongs under Messaging, and `channels.Channel` must not reach -across into it. +Messaging is the root, Channel is the integration layer, an implementation such +as Telegram sits under Channel. A channel is added by implementing one reusable +interface, and every channel must implement it. A notification mechanism belongs +under Messaging, and `channels.Channel` must not reach across into it. ### Notification is a Messaging contract, not a channel type @@ -78,30 +72,27 @@ dependency stays `channels -> messaging` and nothing points back. `channels.Channel` does not change. It gains no notification method and no import, so the interface every channel must implement stays the lifecycle and -config contract it is today. `internal/channels/telegram` satisfying both -contracts is an implementation choosing to, not the Channel layer knowing -about notification. +config contract it is. `internal/channels/telegram` satisfying both +contracts is an implementation choosing to, not the Channel layer knowing about +notification. A notification is not a channel type because it has no lifecycle to start and -stop, no inbound direction, and no configuration schema of its own. Modelling -it as one would force `Start`/`Stop`/`ConfigSchema` onto something with no -meaning for them, and make every real channel declare whether it is a -notification. +stop, no inbound direction, and no configuration schema of its own. Modelling it +as one would force `Start`/`Stop`/`ConfigSchema` onto something with no meaning +for them, and make every real channel declare whether it is a notification. ### Destinations are configured, never named by a playbook -`[notify]` today is one webhook URL, read in one place -(`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, -such as a Telegram chat id. The existing single-webhook form keeps working as -a destination named `webhook`. +`[notify]` 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, such as a Telegram chat id. The +existing single-webhook form keeps working as a destination named `webhook`. A playbook action names a destination. It never names an address. Playbook triggers are reachable from a public, unauthenticated intake surface, so an -action that could address an arbitrary chat would be a new exfiltration -surface; a destination the operator configured once is not. +action that could address an arbitrary chat would be a new exfiltration surface; +a destination the operator configured once is not. ### Args and Result @@ -122,21 +113,20 @@ reject-at-load rule. ### Host access: no new process surface -`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` -records that it "must not decode" the daemon's `[nats]` config. So a -notification cannot be pushed into it today by any route. +`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` records +that it "must not decode" the daemon's `[nats]` config. So a notification cannot +be pushed into it 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`), `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 -`Service.channels`. No new listener, no NATS in Messaging, no change to how -any process is reached. +(`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 `Service.channels`. No +new listener, no NATS in Messaging, no change to how any process is reached. The existing `Stream` RPC is not reused: it streams one chat turn's events for one inbound message (`internal/infrastructure/gatewayrpc/server.go:Stream`). @@ -144,25 +134,25 @@ one inbound message (`internal/infrastructure/gatewayrpc/server.go:Stream`). ### Out of scope Giving playbook-originated sends the session and approval scoping the -interactive channels use. Configured destinations carry the address, so there -is no conversation to anchor to and no scoping mechanism to generalize. +interactive channels use. Configured destinations carry the address, so there is +no conversation to anchor to and no scoping mechanism to generalize. ## Packages this touches - `internal/domain/eda` (or a new sibling package, e.g. - `internal/domain/eda/forgeaction`): typed `Args`/`Result` per operation, - a small registry keyed by operation name, dispatched against a + `internal/domain/eda/forgeaction`): typed `Args`/`Result` per operation, a + small registry keyed by operation name, dispatched against a `workflow.Forger`-typed value -- not `internal/forge.Forge` directly (see correction above). -- `internal/app/archied`: wiring the coordinator's constructor to receive - the daemon's already-built `forge.Forge` client, passed in as the - `workflow.Forger` it already satisfies -- no new lifecycle to manage, - and no change to `internal/forge` itself. +- `internal/app/archied`: wiring the coordinator's constructor to receive the + daemon's already-built `forge.Forge` client, passed in as the + `workflow.Forger` it already satisfies -- no new lifecycle to manage, and no + change to `internal/forge` itself. - `internal/domain/messaging`: the notification contract and its `NotifyArgs`/`NotifyResult`. - `internal/config`: `[notify]` becomes named destinations. - `proto/gateway/v1` and `internal/infrastructure/gatewayrpc`: the server-streaming notification RPC. -- `internal/app/archiemessaging`: subscribe at startup, resolve a destination - to a registered channel instance, deliver. +- `internal/app/archiemessaging`: subscribe at startup, resolve a destination to + a registered channel instance, deliver. diff --git a/docs/prds/code-graph-mcp.md b/docs/prds/code-graph-mcp.md index 9627ce15f..08ba19720 100644 --- a/docs/prds/code-graph-mcp.md +++ b/docs/prds/code-graph-mcp.md @@ -1,11 +1,11 @@ # Code graph over MCP (`tools/codegraph`) -Status: proposed. Supersedes `symbol-reference-index.md`, which scoped only the -data layer. +**Status:** Draft +**Supersedes:** `symbol-reference-index.md`, which scoped only the data layer. ## The problem -Establishing what a change touches currently costs an agent eight to fifteen +Establishing what a change touches costs an agent eight to fifteen greps, and the answers are wrong in specific ways. `grep -rn "Register("` cannot separate `plugin.Registry.Register` from `captureintake.Receiver.Register` from `forgerpc.Server.Register`, all of which exist here. It also matches the diff --git a/docs/prds/config-example-drift.md b/docs/prds/config-example-drift.md index a392af8cd..97d52017c 100644 --- a/docs/prds/config-example-drift.md +++ b/docs/prds/config-example-drift.md @@ -1,6 +1,6 @@ # Example-config and generated-config drift — decision -**Status:** Decided, not yet implemented +**Status:** Approved **Date:** 2026-09-15 **Closes:** the checked-in-config half of audit findings `config-1` and `repo-root-deployment-2`; strengthens `doc-drift` findings generally. @@ -56,7 +56,7 @@ reports exactly which keys the target did not consume. Note the second, separate gap already admitted in writing: `generated-documentation.md` — "`task check` does not run `docs:check`, so -generated drift is currently ungated." +generated drift is ungated." ## What to build @@ -79,7 +79,7 @@ mechanism that would have caught a renamed key left behind in an example, and it needs no inventory. **3. Gate generated data in `task check`.** Done. `task docs:check` runs in the -gate, closing the admitted "generated drift is currently ungated" hole. The +gate, closing the admitted "generated drift is ungated" hole. The check mode did not exist when this was written; it was added for issue #855, which also made the check non-destructive so the gate can never rewrite the artifact it is judging. diff --git a/docs/prds/config-schema.md b/docs/prds/config-schema.md index f87151c9e..fa7996a83 100644 --- a/docs/prds/config-schema.md +++ b/docs/prds/config-schema.md @@ -1,6 +1,6 @@ # Backend-owned configuration schema for the webui -- decision -**Status:** Approved for `archie-core-b6ew` implementation +**Status:** Approved **Date:** 2026-09-02 **Beads issue:** `archie-core-b6ew` (epic), with children `.1`-`.5` @@ -9,7 +9,7 @@ The dashboard's Configuration page keeps reading a secret-free, hand-picked view of `config.Config` -- that allowlist is a safety boundary and stays exactly as it is. What changes is who defines the -page around it: today `ui/src/settings/settings.js` and +page around it: `ui/src/settings/settings.js` and `config-row.js` hardcode every row's label, section, type, and editability by hand; after this, the backend attaches that metadata to each field it already allows through, and the frontend renders @@ -78,7 +78,7 @@ type ConfigSection struct { `handleConfig` builds `[]ConfigSection` from the existing per-field values it already assembles, plus `overlay.DeniedKeys` for `LockedReason` and the existing `Overridden` list -- both already -computed today, just re-attached per field instead of returned as +computed just re-attached per field instead of returned as side-channel maps the frontend cross-references by key string. `Locked`/`Overridden`/`Reload`/`Provenance` stay as top-level `ConfigView` fields; they describe runtime state (what happened on @@ -87,7 +87,7 @@ catalog, and duplicating that logic per-field would be the same drift risk this change exists to remove. `FieldStructured` fields (repositories, models, providers) carry -`Value` as today's structured JSON and are rendered by dedicated +`Value` as structured JSON and are rendered by dedicated editors, not the generic renderer -- see "What this does not do". ## Sections @@ -126,7 +126,7 @@ restart. It knows how to render a section and a field of a given type. adds a label next to a value that was already being shown. - **Does not make every backend field appear automatically.** A field still requires someone to write its descriptor, same as it requires - someone to add it to `ConfigView` today -- the fix is one + someone to add it to `ConfigView` -- the fix is one source of truth instead of two, not zero review. - **Does not solve structured editing generically.** Repositories and maps get their own typed editor (`archie-core-b6ew.4`), not a @@ -140,7 +140,7 @@ restart. It knows how to render a section and a field of a given type. ## Acceptance criteria (epic-level; see child issues for per-task detail) -1. Every field currently rendered as a hardcoded row in `settings.js` +1. Every field rendered as a hardcoded row in `settings.js` has a backend-authored descriptor with type, label, and section. 2. `Repo.ReviewEnabled` reaches the API and the dashboard, alongside `AllowConcurrent` and `MaxRetries`. diff --git a/docs/prds/contract-conformance-audit.md b/docs/prds/contract-conformance-audit.md index 16f39a059..4c4d780b3 100644 --- a/docs/prds/contract-conformance-audit.md +++ b/docs/prds/contract-conformance-audit.md @@ -1,7 +1,7 @@ # Contract conformance audit — decision -**Status:** Implemented as an **advisory** report. Deliberately **not** part of -`task check`. +**Status:** Finalised +**Scope:** an **advisory** report, deliberately **not** part of `task check`. **Date:** 2026-09-15 **Authority:** sibling to `archie-core-06ag` (standing reachability audit) and `docs/architecture/dependencies-and-contracts.md`. Replaces neither. diff --git a/docs/prds/curator-sampler-wave1.md b/docs/prds/curator-sampler-wave1.md index b1e702186..98f6d6279 100644 --- a/docs/prds/curator-sampler-wave1.md +++ b/docs/prds/curator-sampler-wave1.md @@ -1,6 +1,6 @@ # Curator sampler wave 1: `Sampler` interface + four cheap strategies -- decision -**Status:** Approved for implementation +**Status:** Approved **Date:** 2026-09-05 **Beads issue:** bead `archie-core-1786637500776-416-600a66e5` / GitHub #437 covers the embedding-backed follow-on strategy only. This PRD covers the @@ -20,7 +20,7 @@ criteria requires that subset-picking to sit "behind a `Sampler` interface that wave 1 of the curator epic ships (cheap strategies: recency, random, all, staleness proxy)" and that the embedding-backed strategy implement "the same interface" later. No such interface, and none of the four cheap -strategies, exist anywhere in the codebase today (bead 434e5bb9's closure +strategies, exist anywhere in the codebase (bead 434e5bb9's closure without a linked PR was the tracker being wrong, not the code existing) -- this PRD is the one-page settled design for it, per this repo's Scope Discipline rule. @@ -130,7 +130,7 @@ like `image.GenerateRequest.Options` and `curator.Action.Detail`'s existing - **No curator-family wiring.** `curator.Registrar` gains no `Sampler` field and no curator declares one in this change. Nothing in `internal/domain/curator` consumes `sampling.Sampler` yet -- there is no - curator that samples anything today. Wiring a sampler into a real + curator that samples anything. Wiring a sampler into a real curator's `Pass` is that future curator's job, not this prerequisite's. - **No embedding-backed strategy.** That is GitHub #437, explicitly deferred behind the embeddings capability this same change also adds diff --git a/docs/prds/dashboard-aware-chat-navigation.md b/docs/prds/dashboard-aware-chat-navigation.md index 9d06ff90a..1afeeddb4 100644 --- a/docs/prds/dashboard-aware-chat-navigation.md +++ b/docs/prds/dashboard-aware-chat-navigation.md @@ -1,13 +1,13 @@ # Dashboard-aware chat: Archie sees the page, and points the operator there -**Status:** Design decision (before implementation) +**Status:** Approved **Date:** 2026-08-26 **Compound:** the "chat available on any page" surface work (global chat presence) ## Decision Make the web chat **dashboard-aware**: the agent is told which dashboard page -the operator is on *right now*, knows what each page is for, and can **point** +the operator has *open*, knows what each page is for, and can **point** the operator to the relevant page with a **clickable destination chip** the UI renders and follows - Option B (context + navigate), not just "tell me in text." @@ -30,7 +30,7 @@ rendered, not a markdown link the model invents. This is the natural next step of the "chat on any page" work, and the original request named it explicitly: *"archie should be able to see what page you're on -too. and point out where to go. so it needs plenty of resources."* Today the chat +too. and point out where to go. so it needs plenty of resources."* The chat is a full-page route with no knowledge of the rest of the dashboard; the agent cannot see which page the operator is on and cannot reliably direct them anywhere. The critique of the chat UI already identified "chat is not available on any page" diff --git a/docs/prds/dashboard-live-state.md b/docs/prds/dashboard-live-state.md index 83c9e081f..486c8432b 100644 --- a/docs/prds/dashboard-live-state.md +++ b/docs/prds/dashboard-live-state.md @@ -1,6 +1,6 @@ # Dashboard live state -**Status:** approved for implementation (2026-09-20) +**Status:** Approved ## Decision diff --git a/docs/prds/dashboard-navigation-groups.md b/docs/prds/dashboard-navigation-groups.md index 12057eeda..9e28f4dfe 100644 --- a/docs/prds/dashboard-navigation-groups.md +++ b/docs/prds/dashboard-navigation-groups.md @@ -1,6 +1,6 @@ # Dashboard navigation groups + Configuration split -- decision -**Status:** Approved for implementation +**Status:** Approved **Date:** 2026-09-20 **Beads issue:** `archie-core-ocfm` **Related:** `archie-core-gl96` (Logs absent from the nav -- subsumed here), diff --git a/docs/prds/dashboard-port-brief.md b/docs/prds/dashboard-port-brief.md index 5c61902b4..963a4241c 100644 --- a/docs/prds/dashboard-port-brief.md +++ b/docs/prds/dashboard-port-brief.md @@ -1,6 +1,6 @@ # Dashboard port: what the agent delivers -**Status:** Active working agreement +**Status:** Approved **Date:** 2026-09-20 **Beads:** `archie-core-tavn` (epic), `archie-core-ocfm` (navigation) **Reads with:** `docs/prds/vue-migration-checklist.md` (the item-by-item), diff --git a/docs/prds/deep-research-capability.md b/docs/prds/deep-research-capability.md index 5d08763f9..ac7a383a8 100644 --- a/docs/prds/deep-research-capability.md +++ b/docs/prds/deep-research-capability.md @@ -1,6 +1,6 @@ # Deep research capability — design -**Status:** Draft for review, not yet decided +**Status:** Draft **Date:** 2026-09-14 **Scope:** A deep-research capability in archie-core: an orchestrator that spawns 1..N subagents to explore and research in parallel, collates their @@ -10,7 +10,7 @@ findings, and returns one cited report. Grounded in web search and web fetch. ## §0 Implementation status -Every claim in this document is mapped to what exists in the tree today. +Every claim in this document is mapped to what exists in the tree. | Claim | Status | Where it stands | |---|---|---| @@ -32,7 +32,7 @@ Every claim in this document is mapped to what exists in the tree today. | 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 -> design, not a description of the daemon as it runs today. +> design, not a description of the daemon as it runs. ## Problem @@ -41,7 +41,7 @@ exploration or research work. And they should collate all findings, they should use web search/fetch features."* None of the three primitives that sentence needs can be assembled from what -ships today: +ships: 1. **Web search does not exist.** `web_fetch` reads a URL you already have. A research loop's first act is to *discover* URLs from a query, and there is diff --git a/docs/prds/dynamic-curators.md b/docs/prds/dynamic-curators.md index 20cca7fa6..81b91cb51 100644 --- a/docs/prds/dynamic-curators.md +++ b/docs/prds/dynamic-curators.md @@ -1,6 +1,6 @@ # Dynamically-defined curators -- decision -**Status:** Decided, to be implemented +**Status:** Approved **Date:** 2026-09-12 **GitHub epic:** [#789](https://github.com/samcharles93/archie-core/issues/789) **Parent epic (curator engine):** [#435](https://github.com/samcharles93/archie-core/issues/435) (closed) @@ -9,7 +9,7 @@ ## §0 Implementation status -Every claim in this document is mapped to what exists in the tree today. +Every claim in this document is mapped to what exists in the tree. | Claim | Status | Where it stands | |---|---|---| @@ -28,14 +28,14 @@ Every claim in this document is mapped to what exists in the tree today. | 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` 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 | +| 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. Dedicated tools (#161) are convenience, not a blocker | > **Target state, not current state.** Everything below marked aspirational is -> design, not a description of the daemon as it runs today. +> design, not a description of the daemon as it runs. ## Problem -A curator exists today only if a Go package implements `curator.CuratorEngine` +A curator exists only if a Go package implements `curator.CuratorEngine` 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 @@ -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` guard). + can declare tools at all (the `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 @@ -117,7 +117,7 @@ the escape hatch, not the mode: the mode is tools + instructions as data. ## Dynamic registration and mutation A definition change must apply without a daemon restart, which the runtime -cannot do today (`Start()` snapshots membership into one goroutine per curator; +cannot do (`Start()` snapshots membership into one goroutine per curator; no `Unregister`, no `Add`/`Remove`). - `Registry.Unregister(name)` -- valid while running, same failure isolation as diff --git a/docs/prds/dynamic-workflow-triage.md b/docs/prds/dynamic-workflow-triage.md index 18769324f..10bb327e0 100644 --- a/docs/prds/dynamic-workflow-triage.md +++ b/docs/prds/dynamic-workflow-triage.md @@ -1,5 +1,7 @@ # Dynamic workflow triage +**Status:** Finalised + Epic: archie-core-enfj. Scope: give `workflow.Route()` a real, content-aware fallback instead of unconditionally defaulting every unlabeled task to the heaviest workflow. @@ -7,7 +9,7 @@ heaviest workflow. ## Problem `Route()` (`internal/domain/workflow/workflow.go`) has exactly two real -signals today: an explicit `t.Workflow`, and label matches via +signals: 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, since `task_spawn` rarely sets labels — falls straight through to @@ -17,7 +19,7 @@ actually asks for. `task_spawn`'s own tool schema overpromises: *"workflow: … Omit to let the daemon route it"* (`internal/gateway/task_tools.go`) implies real -routing exists. It doesn't — "route" currently means "check labels, then +routing exists. It doesn't — "route" means "check labels, then give up and run the heaviest workflow anyway." Confirmed in production: a chat-spawned task whose @@ -32,15 +34,15 @@ needed, but that conclusion arrives two expensive stages (`baseline`, Add a **`triage` workflow**: cheap, classifies once, then either closes the task immediately or hands off to the workflow the task actually needs. -`Route()`'s final fallback (currently `reg["implement"]`) becomes +`Route()`'s final fallback (`reg["implement"]`) becomes `reg["triage"]` when a `triage` entry is registered, else the existing `implement` fallback — a two-line change, fully backward compatible when `triage` isn't wired up. Triage does **not** replace label-based routing. A labeled task (`bug`/`feature`/bootstrap) already has a free, reliable signal and goes -straight to its known workflow exactly as today — spending a classification -call there would be pure waste. Triage only fires in the gap that currently +straight to its known workflow unchanged — spending a classification +call there would be pure waste. Triage only fires in the gap that defaults to `implement` blindly: no explicit workflow, no label match. ### Triage workflow shape @@ -92,7 +94,7 @@ classification twice for the same task. or `Bootstrap()`/`Feasibility()`/`TDD()` themselves. - Triage for forge-sourced (real GitHub issue) tasks with no labels — in scope structurally (same fallback branch), but the dominant case this - fixes is chat-spawned tasks, which essentially never carry labels today. + fixes is chat-spawned tasks, which essentially never carry labels. ## Testing diff --git a/docs/prds/eda-playbook-engine.md b/docs/prds/eda-playbook-engine.md index f5501d441..d8eb20a3b 100644 --- a/docs/prds/eda-playbook-engine.md +++ b/docs/prds/eda-playbook-engine.md @@ -1,16 +1,16 @@ # EDA playbook engine -- design -**Status:** Draft, awaiting sign-off (not yet in `docs/architecture/`) +**Status:** Draft **Date:** 2026-09-03 ## Problem -Today, "which workflow runs for which trigger" is hardcoded Go: a literal +"Which workflow runs for which trigger" is hardcoded Go: a literal label vocabulary (`workintake.labelKinds`) and a literal label->workflow map (`workflow/routing.go`), extended only by adding a Go case or shipping a skill whose `metadata.archie.workflow` overrides one *named* built-in workflow. Extending the system to a new trigger, a new action, or a new -event source today means a feature branch, a code change in a hardcoded +event source means a feature branch, a code change in a hardcoded path, and new Go tests -- for every addition. That is the barrier this document exists to remove. @@ -78,7 +78,7 @@ access. Concretely: - **Workflow** -- already exists (`internal/domain/workflow`). A playbook action of kind `workflow` invokes a registered `workflow.Registry` entry - by name, unchanged from today's execution path. + by name, unchanged from the existing execution path. - **Module** -- the new general-purpose action position. A `Module` is a Yaegi-evaluated implementation of a generated interface (args in, typed result out) for one declared action kind (e.g. `image-gen`, `notify`, @@ -123,7 +123,7 @@ position, and they drive code generation from the start. - Schema versioning is explicit per position, independent of a playbook's own workflow version (see collision handling below). -This document does not attempt to design the full generator today. It +This document does not attempt to design the full generator. It records the constraint (schema-first, `go:generate`-driven, per logic position) so the first implementation slice builds toward it instead of away from it. @@ -224,7 +224,7 @@ require its own decision. Gap 2 below is resolved by `archie-core-t2db.17`. A playbook is an ordered action list with data flowing between steps. If 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 +403s), the run needs a defined outcome. 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`) @@ -359,9 +359,8 @@ mechanism rather than designing a new one. #### Decision **Granularity: per-action-per-event -- one dedup record per -(action, event) pair, not per playbook run.** This supersedes the -earlier draft's whole-run default. Whole-run keying has two crash -windows: the run row is written when the run starts, so a crash mid-run +(action, event) pair, not per playbook run.** Whole-run keying, the +obvious alternative, has two crash windows: the run row is written when the run starts, so a crash mid-run leaves the run "started" and a redelivery skips *every remaining action* (work silently lost); a crash before the row write re-runs *every already-fired action* (duplicate side effects -- the exact harm @@ -369,7 +368,7 @@ this gap exists to prevent). Per-action keys collapse both into one window and one behavior: an action's record is written immediately before that action's side effect is invoked, so an action fires iff its own record is absent, no fired action ever re-fires, and a redelivered -event resumes at the first unrecorded action. For today's shipped +event resumes at the first unrecorded action. For the shipped single-action playbooks the two granularities are equivalent in effect; the difference starts with multi-action runs -- where whole-run keying would already be wrong. @@ -462,7 +461,7 @@ computed by the coordinator -- not a CEL expression.** The key is the and stable-identifier-shaped, validated at load (the CEL resolution's J1 and its context table above in this document). For an action declaring no `id` (permitted by J1 while unreferenced), the key uses the action's 1-based - position in the playbook: deterministic and stable for today's + position in the playbook: deterministic and stable for the single-action playbooks, and a later reorder is a file edit whose content hash changes `playbook_version` with it, so a positional fallback cannot silently collide with a prior definition. @@ -913,7 +912,7 @@ are unblocked on the execution-time questions. from a task," but this should be stated explicitly before Modules ship, not assumed. 4. **First implementation slice.** Recommend: Module position + the - playbook loader + trigger-to-workflow dispatch only (subsuming today's + playbook loader + trigger-to-workflow dispatch only (subsuming the existing label routing) first, proving the schema-gen -> Yaegi -> playbook path end to end on the smallest useful case, before adding Channel/Forge action kinds or the linter/LSP. @@ -926,8 +925,8 @@ are unblocked on the execution-time questions. **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 + `internal/daemon`), not `pollNATS`/`publishTask`. 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 → diff --git a/docs/prds/embedded-nats.md b/docs/prds/embedded-nats.md index bdf2dabcc..bdc90c691 100644 --- a/docs/prds/embedded-nats.md +++ b/docs/prds/embedded-nats.md @@ -1,12 +1,12 @@ # Embedded NATS execution -- decision -**Status:** Implemented +**Status:** Finalised **Date:** 2026-08-24 **Beads epic:** `archie-core-q15y` -This decision supersedes the 2026-08-22 position that embedded NATS was only a +This decision supersedes the position that embedded NATS was only a distribution mechanism and could not be an agent-execution topology. That was true only because the embedded listener was unauthenticated loopback. It left a second production architecture in which `archied` ran autonomous workflows in diff --git a/docs/prds/event-capture-storage.md b/docs/prds/event-capture-storage.md index c065bbfe3..4832f8825 100644 --- a/docs/prds/event-capture-storage.md +++ b/docs/prds/event-capture-storage.md @@ -1,6 +1,6 @@ # Event capture storage -- decision -**Status:** Implemented +**Status:** Finalised **Date:** 2026-08-22 **Beads issue:** `archie-core-t2db.1` diff --git a/docs/prds/event-sources-and-reactions.md b/docs/prds/event-sources-and-reactions.md index 5338674b6..6a4fb4519 100644 --- a/docs/prds/event-sources-and-reactions.md +++ b/docs/prds/event-sources-and-reactions.md @@ -1,6 +1,6 @@ # Event sources and reactions -- decision -**Status:** Decided, not yet implemented +**Status:** Approved **Date:** 2026-08-22 **Beads issue:** `archie-core-7d5u.1`, blocks `7d5u.2/.3/.4/.5` @@ -11,7 +11,7 @@ each question and saying which packages change. ## 1. In-process typed families, not out-of-process dispatch -Archie has no out-of-process extension mechanism today. The plugin engine +Archie has no out-of-process extension mechanism. The plugin engine rule (`ARCHITECTURE.md#plugin-engine-rule-strict`, mechanically checked by `internal/plugin/architecture_test.go`) keeps every capability family in-process behind a narrow typed registrar; NATS RPC exists for @@ -45,7 +45,7 @@ both wanting to see the same event under `WorkQueuePolicy` hit exactly the trap `CLAUDE.md` already documents: overlapping filter subjects on a work-queue stream mean the second consumer silently gets nothing. Reactions need fan-out, not claim-once, so the client needs retention made a `Config` -field (defaulting to today's `WorkQueuePolicy` so `ARCHIE_TASKS` is +field (defaulting to `WorkQueuePolicy` so `ARCHIE_TASKS` is unaffected), and a second stream (`ARCHIE_REACTIONS` or similar) configured under a fan-out-capable policy, alongside the existing task-distribution stream -- not instead of it. diff --git a/docs/prds/extensions-center.md b/docs/prds/extensions-center.md index adb987841..173dd61ef 100644 --- a/docs/prds/extensions-center.md +++ b/docs/prds/extensions-center.md @@ -1,5 +1,7 @@ # Extensions center +**Status:** Draft + Epic: `archie-core-1786637490708-35-38424ead` / GitHub `#56` ("Replace Skills with a bundled Extensions center"). @@ -33,7 +35,7 @@ only existing reload path (`ReloadChannel`, `server.go`) is channel-specific and explicitly does not cover plugins or MCP servers. `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 +independent fields with no unifying type — an operator has no single place to see "what's available, what's enabled, what's actually running, and what's degraded" across all of them. `ui/src/` has `settings/`, `skills/`, and `workflows/` directories already; there is no @@ -114,7 +116,7 @@ adds fields to existing structs, it does not add a second config-write path. **Decision.** No new "pending restart" flag is persisted. `Inventory.List` computes `StatePendingRestart` by comparing the config's `Enabled` value -against whether the family's registry currently reports that entry as +against whether the family's registry reports that entry as live — if they disagree, the entry is pending restart. This is simpler than tracking a flag through a save-then-restart cycle and can never go stale, because it's recomputed on every read. diff --git a/docs/prds/image-capability-contract.md b/docs/prds/image-capability-contract.md index 902cc1d71..c9399e445 100644 --- a/docs/prds/image-capability-contract.md +++ b/docs/prds/image-capability-contract.md @@ -1,5 +1,7 @@ # Image capability contract and configuration +**Status:** Approved + Epic: archie-core-1786748942120-1-6636e629 / GitHub #496 ("Image generation capability: hosted API baseline plus local GPU workflows"). @@ -17,7 +19,7 @@ obligations inline. Archie needs a provider-neutral boundary for image generation/editing so a hosted API (gpt-image-2-class) and a future local GPU backend can both implement it without either one leaking into the domain contract. Nothing -in the repo defines this today (`grep -ri image` over `internal/domain` and +in the repo defines this (`grep -ri image` over `internal/domain` and `internal/config` returns nothing image-specific). ## Design @@ -34,7 +36,7 @@ below), and narrow host access via a `Registrar`. long-running — they hold a background cadence or a persistent connection worth health-checking. An image provider is call-scoped: it either serves a `Generate`/`Edit` request or it does not. Health here means "is this -provider usable right now", which is exactly what `Generate`/`Edit` +provider usable at call time", which is exactly what `Generate`/`Edit` returning a typed `ErrUnavailable` already communicates — a separate `Health()` poll would just duplicate that. `Registry` still owns registration and lookup, so provider selection is testable with fakes per @@ -245,7 +247,7 @@ provider-agnostic image facility: `image.Provider` (`Name`, `GenerateImage(ctx, GenerateImageRequest) (GenerateImageResponse, error)`), `image.Client`, and `registry.Registry.RegisterImage`/`.Image(name)` — the same shape chat model registration already uses. Three backends implement it -today (azure, togetherai, xai); OpenAI does not yet. +(azure, togetherai, xai); OpenAI does not. `internal/infrastructure/image.Provider` wraps an `ai-sdk/image.Provider` behind this package's `Provider` interface, the same way `curatorLLMRunner` @@ -259,7 +261,7 @@ Blocking the entire hosted provider on an upstream ai-sdk change is not this epic's call to make on someone else's project's timeline. Instead: - `Generate` wraps `ai-sdk/image.Client.GenerateImage` against whichever - backend `ImageHostedProvider.Class` names (azure/togetherai/xai today). + backend `ImageHostedProvider.Class` names (azure/togetherai/xai). - `Edit` is a direct HTTP client hitting the OpenAI-compatible `/images/edits` multipart endpoint, built the same way `minimax.Client` (`internal/tools/minimax/minimax.go`) is a direct client for an API @@ -356,7 +358,7 @@ already use — not a new gating convention). The epic allows "a remembered preference only where existing session/config conventions support it" — and checking `Router`'s actual fields (`ModelPersist`, `Identity`, the rest) shows there is no generic per-session -key/value store the neutral command path can lean on today; `/model`'s own +key/value store the neutral command path can lean on; `/model`'s own `--session`/`--global` scoping lives entirely in `internal/channels/telegram/model.go`, a Telegram-specific enrichment, not something `Router` provides generically. Inventing a new generic @@ -397,7 +399,7 @@ adapter tests only for wiring, not for re-testing the state machine. This is the smallest section because most of the delivery path **already exists and is already proven** — by `generate_video` -(`internal/tools/minimax`), which ships today. Do not rebuild it. +(`internal/tools/minimax`), which ships. Do not rebuild it. The existing pipeline: a result carrying media returns `tools.MultimodalResult{IsMultimodal: true, URLs: []tools.MediaRef{{Type: "image", ...}}}` @@ -413,7 +415,7 @@ video-specific. |---|---|---| | 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`'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 | +| 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 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 | **The only new work `internal/tools/minimax` didn't already need**: the diff --git a/docs/prds/inline-review.md b/docs/prds/inline-review.md index d382beec7..5cd039981 100644 --- a/docs/prds/inline-review.md +++ b/docs/prds/inline-review.md @@ -1,6 +1,6 @@ # Inline review -- decision -**Status:** Implemented +**Status:** Finalised **Beads issue:** `archie-core-q9au` **Builds on:** `archie-core-h019` (adversarial self-review), `docs/architecture/adversarial-review.md` @@ -13,7 +13,7 @@ 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 applied in one click. -Both halves are missing today: +Both halves are missing: - **No line-anchored comment.** `forge.Forge.Comment` posts to the PR *conversation* (`Issues.CreateComment`); nothing creates a review comment at @@ -122,7 +122,7 @@ failed to post must not park a task whose actual work succeeded, and the body section already carries every finding. This mirrors `OpenPR`'s existing best-effort `LinkBranch` call. -### 5. No separate opt-in flag (for now) +### 5. No separate opt-in flag Inline comments are posted whenever a review ran and produced line-anchored findings — the same `repo.review_enabled` gate already covers it. A second flag diff --git a/docs/prds/mcp-tool-completion.md b/docs/prds/mcp-tool-completion.md index 18dfdfe6b..c795fbf7c 100644 --- a/docs/prds/mcp-tool-completion.md +++ b/docs/prds/mcp-tool-completion.md @@ -1,5 +1,7 @@ # MCP client and tool-guardrail completion +**Status:** Approved + Epic: `archie-core-1786637493439-140-2cee2e9b` / GitHub `#161` ("[EPIC] Tools: central registry, MCP client, guardrails"). @@ -26,7 +28,7 @@ regardless of server — `ParallelToolCalls` does not exist on the `MCPServer` 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, +MCP servers run as whatever the config's `Command`/`Args` launches, unsandboxed. `#182` (sequential tool dispatch with per-result previews) is open; concurrent dispatch (`#183`) is closed, so there are two dispatch paths and this PRD decides how they coexist. @@ -48,9 +50,9 @@ defaulting to nil (server sampling requests get a JSON-RPC "not supported" error when unset — never a silent drop). **Call site.** `internal/tools/mcp/client.go` — add the handler field and a -dispatch branch in whatever function currently demuxes incoming server +dispatch branch in whatever function demuxes incoming server messages by method name (the same switch that already routes -`notifications/*` today). Wire a concrete handler in +`notifications/*`). Wire a concrete handler in `internal/app/archied/main.go` that routes the sampling request through the same chat-model call path `chatGenerateOptions` already uses, so a server-initiated sample gets the daemon's configured model, not a second @@ -77,7 +79,7 @@ needed; belongs in `task check`. **Decision.** `ParallelToolCalls bool` (default `false`) goes on `MCPServer` 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` +false (default, and the only behavior), 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 concurrency (already proven by the closed concurrent-dispatch bead, `#183`) @@ -122,7 +124,7 @@ CLAUDE.md's Architectural Simplicity rule. client constructor (route sandboxed servers' process launch through `container.Pool.Acquire` instead of `os/exec` directly), and `internal/container/pool.go` (confirm its `Acquire` contract accepts a -stdio-piped, non-worktree workload — if it currently assumes a git worktree +stdio-piped, non-worktree workload — if it assumes a git worktree per CLAUDE.md's `WriteTaskJSON` note, add the narrower entrypoint variant there rather than duplicating the pool). @@ -146,8 +148,8 @@ dispatch is for independent tool calls in one turn; sequential-with-preview is for a turn where each result should be surfaced to the operator (or the next tool call) before the next call fires — e.g. a mutating tool chain where showing intermediate state matters. Add a `DispatchMode` enum -(`Concurrent`/`Sequential`) to whatever type currently selects the closed -`#183` concurrent path, defaulting to `Concurrent` (today's only behavior). +(`Concurrent`/`Sequential`) to whatever type selects the closed +`#183` concurrent path, defaulting to `Concurrent` (its only behavior). **Call site.** The tool-dispatch entry point that `#183`'s closed implementation lives in (grep the concurrent-dispatch symbol added for diff --git a/docs/prds/memory-engine-unification.md b/docs/prds/memory-engine-unification.md index 2ebe8e6cb..23a47ecda 100644 --- a/docs/prds/memory-engine-unification.md +++ b/docs/prds/memory-engine-unification.md @@ -1,6 +1,6 @@ # Memory engine unification: four scopes, CRUD, and one write path -- decision -**Status:** Approved for implementation +**Status:** Approved **Date:** 2026-09-16 **Findings:** `memory-4` and its dependants in the adversarial sweep (`.local/issue-tracker`); the real defect is the split described below, for @@ -120,7 +120,7 @@ gave it nothing better. `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. +restores it, so it is a field that silently does not round-trip. `Update` supersedes rather than overwrites. The superseded state is appended to the scope's `HISTORY.md` **before** the live block is replaced, so a crash @@ -227,7 +227,7 @@ and would leak user A's extracted facts to user B through the same agent; user-wide would pool facts across agents; and a session id cannot survive the session ending, which is the whole requirement. -This needs data the tree does not persist today: the SQLite `messages` table +This needs data the tree does not persist: the SQLite `messages` table gains `sender_id`, and `curator.SessionSummary` / `ConversationMessage` gain the agent and participant. The participant is derived from the session's own user-role messages: exactly one distinct non-empty sender writes; zero (a @@ -276,11 +276,11 @@ Existing data at `/memory` is left on disk, unreferenced. No migration. - **No canonical user identity.** `SenderID` is channel-native, so one person on Telegram and email is two identities. Unifying needs an Identity aggregate that does not exist (`internal/domain` has no identity package and `IdentityID` - appears nowhere in Go today). The contract does not change when it lands. + appears nowhere in Go). The contract does not change when it lands. - **No ranked retrieval.** `Query.Text` stays, unused by the prompt path. - **No data migration**, per the decision above. - **No prompt-memory timeout mechanism.** The read is bounded by construction. -- **No `Metadata` field.** It is write-only today; a caller needing it later +- **No `Metadata` field.** It is write-only; a caller needing it later needs one field, not a speculative contract. ## Acceptance criteria diff --git a/docs/prds/messaging-service-boundary.md b/docs/prds/messaging-service-boundary.md index a7d4ae5f2..7387d3acb 100644 --- a/docs/prds/messaging-service-boundary.md +++ b/docs/prds/messaging-service-boundary.md @@ -1,6 +1,7 @@ # Messaging Service boundary and transport design -**Status:** Ratified (rev. 1) +**Status:** Approved +**Revision:** 1 **Date:** 2026-09-19 **Beads issue:** `archie-core-8cda.6.1` **Parent:** [`service-decomposition.md`](service-decomposition.md) diff --git a/docs/prds/module-position.md b/docs/prds/module-position.md index 5461ddc95..53068518b 100644 --- a/docs/prds/module-position.md +++ b/docs/prds/module-position.md @@ -1,6 +1,6 @@ # Module position -- design -**Status:** Draft, awaiting sign-off (not yet in `docs/architecture/`) +**Status:** Draft **Date:** 2026-09-03 **Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db` @@ -12,7 +12,7 @@ and the standalone lint tool (`t2db.12`) are shipped. Module -- the position that makes an action "not restricted to code-generation" -- has 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. +full generator." This is that design. ## Do not invent a new mechanism -- generalize the one used three times @@ -33,7 +33,7 @@ fourth instance of this same shape**, parameterized by action kind instead of hardcoded to one fixed signature. No new interpreter construction, no new panic-recovery mechanism, no new symbol-table generation tool -- `go generate ... yaegi extract` is already how `wfextract`/`gateextract` -are produced today (see their `//go:generate` directives), and Module +are produced that way (see their `//go:generate` directives), and Module schema generation reuses that exact command. ## No generic `Module` interface -- one typed contract per action kind @@ -131,7 +131,7 @@ repository-supplied code that must run in a container. Module code is **operator-installed, in-process, daemon-privileged** -- the same trust tier as `PluginDir` (daemon plugins) and `SecretEngineDir` (secret engine plugins) already occupy, both Yaegi-interpreted and already running -in-process today. It is **not** repository-supplied code from a task +in-process. It is **not** repository-supplied code from a task (that stays containerized, unchanged). A Module directory is therefore a new config field the operator points at their own trusted directory, mirroring `PluginDir`'s shape exactly -- not something a forge webhook or diff --git a/docs/prds/operator-pr-review.md b/docs/prds/operator-pr-review.md index d8bc79584..c83337468 100644 --- a/docs/prds/operator-pr-review.md +++ b/docs/prds/operator-pr-review.md @@ -1,8 +1,11 @@ # Operator-triggered PR review -Status: proposed (h019.8). Reuses the shipped adversarial-self-review contract +**Status:** Draft +**Beads issue:** `archie-core-h019.8` + +This PRD reuses the adversarial-self-review contract (`docs/prds/adversarial-self-review.md`) and the `workflow.Reviewer` / -`workflow.ReviewReport` types from `internal/domain/workflow`. This PRD decides +`workflow.ReviewReport` types from `internal/domain/workflow`. It decides only what is new: how an operator asks for a review of an *existing* PR, and how that PR's content reaches the reviewer. diff --git a/docs/prds/payload-field-mapping.md b/docs/prds/payload-field-mapping.md index 0aa7ceef4..9074aca42 100644 --- a/docs/prds/payload-field-mapping.md +++ b/docs/prds/payload-field-mapping.md @@ -1,6 +1,6 @@ # Payload field mapping -- decision -**Status:** Decided, not yet implemented +**Status:** Approved **Date:** 2026-08-22 **Beads issue:** `archie-core-t2db.3`, depends on `t2db.1`, blocks `t2db.4` @@ -18,7 +18,7 @@ resolve/preview rule; `internal/store` persists it (mirrors interface, `*store.Store` implementation); `internal/webui/api_mapping.go` is the transport. This follows `docs/prds/event-capture-storage.md`'s own placement precedent: `internal/store` is where this daemon's persistence -already lives, not `internal/infrastructure` (that layer today holds +already lives, not `internal/infrastructure` (that layer holds cross-domain services -- config, eventbus, modelcatalog -- not this daemon's primary store). @@ -110,7 +110,7 @@ is `t2db.4`'s job, not duplicated here. `internal/store/mappings.go`, `field_mappings` table: `id, name, source_hint, fields_json, created_at, updated_at`. `fields_json` is the `[]Field` slice JSON-encoded into one column -- fields have no independent -query need (nothing filters "mappings with a field named X" today), so a +query need (nothing filters "mappings with a field named X"), so a join table would be structure with no consumer, the same failure mode `organisation.md` bans for empty layering. diff --git a/docs/prds/pr-review-remediation.md b/docs/prds/pr-review-remediation.md index fa95e4f49..8ed42548a 100644 --- a/docs/prds/pr-review-remediation.md +++ b/docs/prds/pr-review-remediation.md @@ -1,6 +1,6 @@ # PR review comment remediation -- decision -**Status:** Decided, not yet implemented +**Status:** Approved **Date:** 2026-09-10, amended and ratified 2026-09-19 **Beads issue:** (filed as `archie-core-…`, parent: `archie-core-7d5u` event sources and typed reactions) diff --git a/docs/prds/progressive-tool-disclosure.md b/docs/prds/progressive-tool-disclosure.md index 79daf41d9..1fd38aa6e 100644 --- a/docs/prds/progressive-tool-disclosure.md +++ b/docs/prds/progressive-tool-disclosure.md @@ -1,6 +1,6 @@ # Progressive tool disclosure (bridge tools) — wiring -**Status:** Implemented (wiring landed) +**Status:** Finalised **Date:** 2026-08-15 **Compound:** the "keep the LLM tool schema small, give full access on demand" work (issue #167) diff --git a/docs/prds/review-calibration.md b/docs/prds/review-calibration.md index 45c07ac72..c340596d5 100644 --- a/docs/prds/review-calibration.md +++ b/docs/prds/review-calibration.md @@ -1,6 +1,6 @@ # Review calibration -- decision -**Status:** Proposed +**Status:** Draft **Beads issue:** `archie-core-h019.5` (parent `archie-core-h019`) Decides the half of calibration `docs/prds/adversarial-self-review.md` left @@ -13,7 +13,7 @@ The shipped contract (`internal/domain/workflow/review_findings.go`, h019.2) already makes only a **confirmed** error-level finding block (`Blocking() == Verdict == confirmed && Level == error`), and a zero-finding review is already distinguishable from one that never ran (`ReviewStatus`). -What is missing is the other half: a reviewer can currently report *nothing* +What is missing is the other half: a reviewer can report *nothing* and say only "I found nothing" in free text. The operator cannot tell "I checked the five things that matter and they are clean" from "I did not look." That is the failure the epic names -- a findings surface that consumes attention diff --git a/docs/prds/self-update-transaction.md b/docs/prds/self-update-transaction.md index 24452a420..966d57574 100644 --- a/docs/prds/self-update-transaction.md +++ b/docs/prds/self-update-transaction.md @@ -1,5 +1,7 @@ # Self-update: artifact install, topology migration, journaled transaction +**Status:** Draft + Epic: `archie-core-hj1t` / GitHub `#804` ("[EPIC] Self-update: artifact install, topology migration, journaled transaction"). @@ -15,7 +17,7 @@ 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 genuinely greenfield: no topology-detection or transaction-journal code -exists anywhere in the tree today. +exists anywhere in the tree. Out of scope: rewriting the `internal/releaseupdate` Go interfaces themselves, and any UI for triggering updates (channel dispatch, e.g. @@ -174,7 +176,7 @@ digest from the active profile's config rather than falling back to `:latest` when none is configured; refuse the update (don't silently pull `:latest`) if no digest is resolvable and the profile requires a pinned image. Opt-in auto-update refuses to start when the daemon reports work in -flight (reuse whatever "tasks currently running" signal the daemon already +flight (reuse whatever "tasks running" signal the daemon already exposes for graceful shutdown — do not add a second in-flight tracker). **Call site.** `internal/config/config.go` (new `ReleaseChannel` field), diff --git a/docs/prds/service-decomposition.md b/docs/prds/service-decomposition.md index c444e7f1c..c5d9819bc 100644 --- a/docs/prds/service-decomposition.md +++ b/docs/prds/service-decomposition.md @@ -1,6 +1,6 @@ # Service decomposition -- decision -**Status:** Proposed -- not yet approved for implementation +**Status:** Draft **Date:** 2026-09-05 **Beads epic:** archie-core-8cda **Prior art:** `docs/inspiration/2026-09-05-awx-service-decomposition-and-ansible-task-model.md`, @@ -64,7 +64,7 @@ Per `docs/inspiration/service-discovery-research-2026-09-05.md`: } ``` -- An optional service (Curator today; others later) that is not installed +- An optional service (Curator; others later) that is not installed must resolve to a distinct `NotInstalled` outcome, never a `Down`/ `Unhealthy` one. Under K8s this falls out of DNS returning no record; under the NATS fallback it requires an explicit "installed" marker in the @@ -127,7 +127,7 @@ historical record rather than an outstanding gate. 1. **Extraction order.** Which service gets pulled out of the monolith first? The webui entanglement findings above suggest Gateway Service's `ChatContract` should exist before UI Service is extracted, since UI is - the most entangled consumer today. Not yet sequenced. + the most entangled consumer. Not yet sequenced. **RESOLVED.** Gateway Service first, then State Store, then UI, then Messaging, then Execution/Runner/Scheduler, then Curator @@ -223,7 +223,7 @@ historical record rather than an outstanding gate. Capture -> Mapping -> Binding -> TaskStore`. `.4.2` and `.4.3` implement against that doc. 5. **Helm chart / Operator ownership.** Net-new work with no existing - analog in this repository (`deployments/` currently holds TOML profiles + analog in this repository (`deployments/` holds TOML profiles and a `docker-compose.yml`, not Kubernetes manifests). Scoping not yet started. diff --git a/docs/prds/service-registry.md b/docs/prds/service-registry.md index 11a4256fd..7db80e5fc 100644 --- a/docs/prds/service-registry.md +++ b/docs/prds/service-registry.md @@ -1,7 +1,8 @@ # Service registry — one declaration per service -**Status:** Design, pre-implementation. Supersedes `state-store-contract.md` §10's -`State ServiceConnection` struct-field instruction (revised to rev. 2d in the same change). +**Status:** Draft +**Supersedes:** `state-store-contract.md` §10's `State ServiceConnection` +struct-field instruction. **Base:** the `listen` field, `internal/app/archied/listen.go`, and the listen defaults cited below exist on `feat/attempt-attribution`, not on `main`. This design therefore lands on top of @@ -91,13 +92,12 @@ states in prose or in a branch: - `state-store-contract.md` §10 must be revised in the same change, or the tree contradicts its own ratified authority. Its summary (`:7`) already says `[services.]`. -- A typo'd `[services.gatway]` is **reported today** (`UnknownKeys = [services.gatway, +- A typo'd `[services.gatway]` is **reported** (`UnknownKeys = [services.gatway, services.gatway.target]`), because the struct form leaves it in `toml.MetaData.Undecoded()`. A map decodes any section, so preserving that is a requirement, not an optional extra: `unregisteredServiceKeys` asks the registry which names exist. This costs nothing in 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.) + The typo is not silently ignored either way; the behaviour was measured. - 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 diff --git a/docs/prds/session-memory-curator.md b/docs/prds/session-memory-curator.md index 46b4f3e7b..f717ec84b 100644 --- a/docs/prds/session-memory-curator.md +++ b/docs/prds/session-memory-curator.md @@ -1,6 +1,6 @@ # Persistent session-memory curator (reference implementation) -- decision -**Status:** Approved for archie-core-1786637499114 implementation +**Status:** Approved **Date:** 2026-09-02 **Beads issue:** `archie-core-1786637499114` **Parent epic:** `archie-core-1786637500725` (curator engine) @@ -29,7 +29,7 @@ memory scopes (global, agent-wide, user-wide, agent-user relationship) as **still open** -- there is no decided mapping yet from a chat session to a durable identity that would outlive that session (a Telegram chat ID is not necessarily "the same person" as a web session; per-platform -identity resolution does not exist as a memory concern today). Choosing +identity resolution does not exist as a memory concern). Choosing session-as-identity sidesteps a decision this issue has no business making unilaterally: it is the narrowest scope that is unambiguous (`gateway.SessionContext.SessionID` already exists, is already unique, @@ -139,7 +139,7 @@ honestly rather than always returning true. dedup index. - **No `Forget`.** Nothing here decides a memory is stale; that is a different, harder judgment call than "is this worth keeping," and nothing - currently reads these observations back into a chat turn to notice if + reads these observations back into a chat turn to notice if one turned out wrong. - **No tool declarations.** `Manifest.Tools` is empty; the model call is a plain completion (`ChatRequest.Tools` left nil), not agentic diff --git a/docs/prds/skill-curator.md b/docs/prds/skill-curator.md index 27bcdcad4..b0285aa92 100644 --- a/docs/prds/skill-curator.md +++ b/docs/prds/skill-curator.md @@ -1,6 +1,6 @@ # Skill curator (reference implementation) -- decision -**Status:** Approved for archie-core-1786637499206 implementation +**Status:** Approved **Date:** 2026-09-02 **Beads issue:** `archie-core-1786637499206` **Parent epic:** `archie-core-1786637500725` (curator engine) @@ -25,14 +25,14 @@ framing -- is real for v1 but deliberately narrow: review is structural validation, improve is whitespace normalization, and prune is *reporting* a problem, never removing a skill. `Manifest.Skills = true` still marks this curator agentic (existing `agentic()` rule), so it receives model -access from the registrar -- unused today, but nothing about the contract +access from the registrar -- unused but nothing about the contract or the runtime needs to change to let a later version reason about content quality using it. ## Why this scope, not more An autonomous process that rewrites or deletes a user's skill content -is a real risk with no undo path today (no draft/approval flow for +is a real risk with no undo path (no draft/approval flow for curator writes exists yet, unlike the workflow engine's PR-based review). The epic's own stated purpose for this issue is proving the curator contract holds for a second, structurally different consumer than the @@ -123,7 +123,7 @@ func (c *Curator) Pass(ctx context.Context, in curator.PassInput) (curator.PassR - **clean** -- no action recorded (a pass with nothing to report is not an error, and not every skill needs an entry every time) -One pass reviews every skill currently on disk; there is no +One pass reviews every skill on disk; there is no per-skill "already reviewed, skip" state; this errs toward re-checking over missing a regression, and the cost is cheap (no model calls, just file reads). diff --git a/docs/prds/state-store-contract.md b/docs/prds/state-store-contract.md index 7f55a2b48..125d91409 100644 --- a/docs/prds/state-store-contract.md +++ b/docs/prds/state-store-contract.md @@ -1,19 +1,12 @@ # State Store — contract boundary & transport (ratification) -**Status:** Ratified (rev. 2e). Rev. 2e adds the `OpenTaskByPR` authorization lookup required -by the ratified PR-review remediation contract. Rev. 2d revised §10 only: the -`State ServiceConnection` struct-field instruction was withdrawn in favour of name-keyed -services (`docs/prds/service-registry.md`). Rev. 1 was marked *conditionally ratified*; the three -reviewer conditions it raised are resolved (rev. 2), and the two third-pass findings are -resolved here: (a) the stale Q3 migration wording in `service-decomposition.md` -(`store.WorkflowStore`, `mode = "inproc" | "remote"`) now matches the ratified ownership split -and presence-based `[services.].target`; (b) the State Store listener topology is a -single explicit rule (bridge address + token when agent containers consume it, loopback-only -for a daemon-local-only consumer) instead of the contradictory loopback-vs-bridge wording. +**Status:** Approved +**Revision:** 2e +**Date:** 2026-09-06 + This is the pre-implementation design document that Phase 2 subtasks `.4.2` (generalize `storerpc` as the State Store gRPC contract) and `.4.3` (stand up `archie-state-store`) implement against. -**Date:** 2026-09-06 (rev. 2c) **Beads milestone:** archie-core-8cda.4.1 **Parent:** `docs/prds/service-decomposition.md` (open-question Q4 **RESOLVED**) @@ -143,7 +136,7 @@ the same `Update`/`Transition`/`InsertEvent` RPCs. `*Store` remains the single implementation of the daemon/webui store surfaces and of `workflow.Store`. Ownership below is about which **process** is the primary consumer of each -method today, and therefore which methods are genuinely cross-process on the wire today vs. +method and therefore which methods are genuinely cross-process on the wire vs. daemon-internal. Process legend: **DAEMON** = `archied` (incl. in-process webui + gateway runtime + @@ -157,7 +150,7 @@ access through daemon-side narrow adapter interfaces. | `TaskRetryer` (1) | DAEMON (`taskactions` retry) | not yet | | `TaskQueries` (7) | DAEMON + GATEWAY (status/list adapters) | not yet (`OpenPRs`/`Tasks`/`StatusCounts` cross to gateway adapters in-process) | | `TaskEvents` (7) | DAEMON + **AGENT** (`InsertEvent` via storerpc) | `InsertEvent` = **YES** (agent); rest DAEMON | -| `workflow.Store` (3) | **AGENT** only | **YES** (the sole genuinely remote consumer today) | +| `workflow.Store` (3) | **AGENT** only | **YES** (the sole genuinely remote consumer) | | `CaptureStore` (2) | DAEMON (webhook intake + mapping editor) | not yet | | `MappingStore` (5) | DAEMON (dashboard editor + dispatch loop) | not yet | | `BindingStore` (6) | DAEMON (dashboard editor + dispatch loop) | not yet | @@ -165,7 +158,7 @@ access through daemon-side narrow adapter interfaces. | `BindingTaskCreator` (1) | DAEMON (dispatch loop) | not yet | **Consequence for migration order:** the **agent's `workflow.Store` is already cross-process -today** (via the NATS `storerpc` surrogate), so it is the first contract to move to gRPC. The +already** (via the NATS `storerpc` surrogate), so it is the first contract to move to gRPC. The daemon-internal surfaces (`Capture`/`Mapping`/`Binding`) stay in-process until the daemon itself points at `archie-state-store`. `TaskStore` (the large composite) moves last. @@ -329,7 +322,7 @@ Production never opens the explicit transaction. **Decision:** the contract drops `*sql.Tx` from `RecordDispatch` (the method becomes `RecordDispatch(ctx, bindingID, bindingVersion, captureID, taskID) error`). The store service -owns any transaction boundary internally when atomicity is wanted; today the at-most-once +owns any transaction boundary internally when atomicity is wanted; the at-most-once guarantee is the `INSERT OR IGNORE` dedup row, which is already transactionless in production. `TestRecordDispatchViaExplicitTx` is superseded by the store service's own internal-transaction test. **This is a required interface migration that must land before or with `.4.2`** (the @@ -356,7 +349,7 @@ same seam. **Wiring change in the transport façade:** - `internal/infrastructure/agenttransport/nats.Transport` — `Store(timeout) store.WorkflowStore` - currently returns `&storerpc.Client{Conn: t.conn, Timeout: timeout}`. It becomes + returns `&storerpc.Client{Conn: t.conn, Timeout: timeout}`. It becomes `Store(timeout) workflow.Store` and returns a *single long-lived* `staterpc.Client` dialed to `settings.StateStoreTarget` (with the token interceptor and per-call timeout). - `internal/app/agentworker/worker.go` `Settings` gains the three fields above; `taskServiceTransport` @@ -402,7 +395,7 @@ across a single agent process, which is either NATS-backed or gRPC-backed, never `err.Error()` string and rehydrates a fresh `errors.New(string)`. The original type, `%w` chain, and sentinel identity are lost → `errors.Is(err, store.ErrStaleTransition)` is **false** across the boundary. -- **gRPC `gatewayrpc`** currently returns raw `err` from handlers; gRPC-Go converts to +- **gRPC `gatewayrpc`** 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`). No status-code mapping for store errors exists. @@ -411,7 +404,7 @@ across a single agent process, which is either NATS-backed or gRPC-backed, never The `StateStore` service must map the store's sentinel errors to canonical gRPC codes and rehydrate them to the *same* sentinels on the client, so consumer `errors.Is` checks keep -working — an improvement over today's flattening, not a regression. +working — an improvement over the flattening it replaces, not a regression. | Store sentinel / outcome | gRPC code | Client rehydrates to | |---|---|---| @@ -497,7 +490,7 @@ stated explicitly rather than left implicit. token**. `127.0.0.1` is reserved for the daemon-local-only case. - **Agent access → the container bridge.** The agent runs in a task-scoped container on the host and reaches the State Store over the Docker bridge gateway (the bind address from the - topology rule above), exactly as it reaches the daemon's NATS today. To close the "any host + topology rule above), exactly as it reaches the daemon's NATS. To close the "any host process could reach the store" gap, the agent **authenticates with a per-task bearer token** carried in gRPC metadata by a client interceptor (`StateStoreToken`, §6). Network reachability + the token is the trust boundary for the default bridge topology. @@ -548,20 +541,18 @@ an explicit operator decision. **Follow the gateway's presence-based `target` seam, not the NATS `mode` enum.** -- **Revised (rev. 2d).** This section previously instructed that - `internal/config/services.go` gain a `State ServiceConnection` *struct field*. That - instruction is withdrawn: naming each service as a field is the duplication - `docs/prds/service-registry.md` removes, and this document's own summary (`:7`) already - describes the seam as `[services.]`. Services are keyed by name: +- **Services are keyed by name, not named as struct fields.** A + `State ServiceConnection` field per service is the duplication + `docs/prds/service-registry.md` removes, and this document's summary describes + the seam as `[services.]`: ```go type Services map[string]ServiceConnection ``` registered once via `RegisterService(context, name, target, listen, tokenEnv)`. The TOML shape below is unchanged, so nothing else in this section is affected; read `cfg.Services.Get("state")` wherever it says `cfg.Services.State`. -- **Empty `Target` → startup error** (corrected in rev. 2d). This bullet previously said an - empty `Target` opens a local `*store.Store` adapter. That default was withdrawn when the - State Store was extracted (§12 step 7): the standalone `archie-state-store` process +- **Empty `Target` → startup error.** The local `*store.Store` adapter default was + withdrawn when the State Store was extracted (§12 step 7): the standalone `archie-state-store` process exclusively owns `archie.db`, so both `archied` and `archie-gateway` now reject an empty target (`internal/app/archied/bootstrap.go` and `state_store_client.go`: `services.state.target is required`). **Set `Target` → dial gRPC** with `*staterpc.Client`; no client opens the @@ -679,7 +670,7 @@ an explicit operator decision. - **Domain type relocation** (`Task`/`Status`/`Source` → `internal/domain/workflow`) is a Phase 2 prerequisite, pulled forward from migration-decisions §4 (minimal bound, `Task → WorkflowExecution`); the rest of §4 stays a separate migration. -- **`RecordDispatch` drops `*sql.Tx`** (wire-blocker; production passes `nil` today) — a +- **`RecordDispatch` drops `*sql.Tx`** (wire-blocker; production passes `nil`) — a required interface migration landing before/with `.4.2`. - **`Close()` not on the wire**; remote client `Close()` is a no-op. - **Structured gRPC error codes** with client rehydration to store sentinels (preserves diff --git a/docs/prds/status-health-surface.md b/docs/prds/status-health-surface.md index 97510c76f..3dc673649 100644 --- a/docs/prds/status-health-surface.md +++ b/docs/prds/status-health-surface.md @@ -52,7 +52,7 @@ decisions") and all five fields shipped. - **Container pool.** `container.Pool` already tracks `active int` under 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 +- **Last poll.** Nothing tracks this. 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. @@ -132,7 +132,7 @@ decisions") and all five fields shipped. 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 +- **`/agents` copy.** The menu still advertises "List tasks being worked" while `Router.Agents` is never wired (`archie-core-mxls`), so that one 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. diff --git a/docs/prds/task-logs-pagination.md b/docs/prds/task-logs-pagination.md index 625565c26..b228cf0b3 100644 --- a/docs/prds/task-logs-pagination.md +++ b/docs/prds/task-logs-pagination.md @@ -1,6 +1,6 @@ # task_logs pagination and bounded retrieval -- decision -**Status:** Approved for vq92 implementation +**Status:** Approved **Date:** 2026-08-26 **Beads issue:** `archie-core-vq92` **Compounds with:** `archie-core-p1bl` (errors serialise as `{}`) @@ -59,7 +59,7 @@ returned page within the same call). `Cursor` is a byte offset rather than an entry ID for two reasons. First, `TaskSink` writes JSONL through `slog.NewJSONHandler` directly -- without routing through `FeedHandler` -- so the on-disk entries carry no -`id` field today, and a per-task attempt monotonic counter would require +`id` field and a per-task attempt monotonic counter would require either a sink-side change or a reader-side reconstruction that is brittle against rotation. Second, the byte offset uniquely identifies "the next unread position" in a sequential scan, which is exactly what diff --git a/docs/prds/task-run-detail.md b/docs/prds/task-run-detail.md index dc131d64b..b7ec0a080 100644 --- a/docs/prds/task-run-detail.md +++ b/docs/prds/task-run-detail.md @@ -1,9 +1,7 @@ # Per-run task detail: attempts, stages, changes, config, debug -**Status:** Settled design, landing with this change set (workflow run -`76f8e877`). The persistence foundation is already in the tree -(`events.attempt`, the two new event kinds, the two proto fields); the read -endpoints and the page land with it. The surface contract itself is +**Status:** Approved +**Authority:** the surface contract itself is `docs/architecture/observability.md`. **Date:** 2026-09-18 **Compounds with:** `docs/prds/task-logs-pagination.md` (a bounded read says @@ -17,7 +15,7 @@ A task gets one detail page that answers "what did this run actually do?" per effective configuration the attempt ran under, the attempt's log, and the raw record behind all of it. -The single organising idea is **attempt attribution**. Today the dashboard +The single organising idea is **attempt attribution**. The dashboard renders a task's whole event stream as one flat timeline, so a retried task reads as one long run with two of everything. Every new panel is scoped to one attempt and says which one. @@ -96,7 +94,7 @@ Both alternatives were rejected on evidence, not taste: called from the daemon's terminal paths) and a retry resets the branch onto its base (`internal/worktree.(*Manager).refresh` → `resetOnto`). There is nothing left to read. -- **Reading it from the forge** is impossible today. The forge contract exposes +- **Reading it from the forge** is impossible. The forge contract exposes no changed-file capability, and adding one would cost three implementations plus an RPC and would still fail for chat-sourced tasks with no PR. diff --git a/docs/prds/ui-service-boundary.md b/docs/prds/ui-service-boundary.md index ffe7b28a9..5f4b726d0 100644 --- a/docs/prds/ui-service-boundary.md +++ b/docs/prds/ui-service-boundary.md @@ -1,6 +1,7 @@ # UI Service boundary and configuration ownership -**Status:** Ratified (rev. 1) +**Status:** Approved +**Revision:** 1 **Date:** 2026-09-07 **Beads issue:** `archie-core-8cda.5.1` **Parent:** [`service-decomposition.md`](service-decomposition.md) @@ -114,8 +115,8 @@ is gone. `webui.Server` has no holder field, so the sharing this paragraph describes cannot be reintroduced by wiring; the daemon owns one Holder and publishes a rendered projection. -Amended 2026-09-09 by `archie-core-ymut`: this section previously assumed one -narrow admin contract carrying both the read and the write. It does not. The +There is no single narrow admin contract carrying both the read and the write +(`archie-core-ymut`). The read crosses as a daemon-published `ConfigView` snapshot over the State Store contract, and the write is descoped for Phase 3 rather than contracted, on the reasoning recorded in migration-decisions under "Dashboard configuration diff --git a/docs/prds/vue-migration-checklist.md b/docs/prds/vue-migration-checklist.md index ffa33f223..1956aa4c4 100644 --- a/docs/prds/vue-migration-checklist.md +++ b/docs/prds/vue-migration-checklist.md @@ -1,6 +1,6 @@ # Preact → Vue 3 + shadcn-vue migration checklist -**Status:** In progress +**Status:** Approved **Date:** 2026-09-20 **Bead:** `archie-core-tavn` (epic), `archie-core-ocfm` (navigation restructure) **Bootstrap commit:** `e18fb8b2` @@ -26,7 +26,7 @@ does not show up as a broken page. `ui/src/router/index.ts` to hold them in step. The parser needs `const routes = [` on its own line, `path: "..."` on a single line per route, and `nav: false` on any entry the registry should skip. That guard - caught a stale `/chat` entry earlier today. + caught a stale `/chat` entry earlier. - [ ] **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 @@ -73,7 +73,7 @@ does not show up as a broken page. kept. - [x] **`color-scheme`.** `[data-theme="dark"] { color-scheme: dark }` and the light equivalent. Without it the UA paints light scrollbars and light - native controls inside the dark app. Fixed today; trivially lost. + native controls inside the dark app. Fixed; trivially lost. - [x] **Contrast values.** The violet palette moved these off the values pinned here, so they were recomputed against its own backgrounds instead of carried: `--fg-subtle` `#A99DBD` dark (7.67:1, AAA) / `#6E6577` light diff --git a/docs/prds/webhook-intake-security.md b/docs/prds/webhook-intake-security.md index 346a35f52..c2e36ded3 100644 --- a/docs/prds/webhook-intake-security.md +++ b/docs/prds/webhook-intake-security.md @@ -1,6 +1,6 @@ # Webhook intake security -- decision -**Status:** Decided, not yet implemented +**Status:** Approved **Date:** 2026-08-22 **Beads issue:** `archie-core-t2db.5`, blocks `archie-core-t2db.4` @@ -64,7 +64,7 @@ playbook-triggered work, and none is needed -- the existing constraints are the control. Mapped payload fields are treated as ordinary user-controlled text inside an -agent prompt, exactly like an inbound chat message today, never as trusted +agent prompt, exactly like an inbound chat message never as trusted instructions. "The agent should ignore instructions in the payload" is not a control and must not appear as one anywhere in this feature -- per `ARCHITECTURE.md`'s environmental-enforcement-over-prompt-rules principle, diff --git a/tools/prdlint/lint.go b/tools/prdlint/lint.go index 63b68cfba..eca88ef7f 100644 --- a/tools/prdlint/lint.go +++ b/tools/prdlint/lint.go @@ -37,7 +37,7 @@ var rules = []rule{ }, { name: "dated-status", - pattern: regexp.MustCompile(`(?i)\b(status|resolved|settled|decided|agreed|approved|shipped|landed|complete|completed|done|wired|verified|corrected|confirmed)\b[^.\n]{0,30}\b20\d\d-\d\d-\d\d\b`), + pattern: regexp.MustCompile(`(?i)\b(status|resolved|settled|decided|agreed|approved|supersedes|superseded|withdrawn|shipped|landed|complete|completed|done|wired|verified|corrected|confirmed)\b[^.\n]{0,30}\b20\d\d-\d\d-\d\d\b`), remedy: "drop the date and the state. A PRD says what the design is; the tracker and git history say when it happened.", }, { @@ -50,6 +50,16 @@ var rules = []rule{ pattern: regexp.MustCompile(`(?i)\bphases?\s+\d[^.\n]{0,40}\b(complete|completed|done|shipped|landed|in progress|underway|remaining)\b|\b(complete|completed|done|shipped|landed|in progress)\b[^.\n]{0,20}\bphases?\s+\d`), remedy: "a phased plan is durable design; which phase is finished is not. Name the phases, not their state.", }, + { + name: "temporal-hedge", + pattern: regexp.MustCompile(`(?i)\b(today|currently|right now|at present|at the moment|as things stand|for now)\b`), + remedy: "\"today\" dates the sentence to the day it was written, so the claim it qualifies is false the moment the design lands. Describe the shape being replaced without asserting it is the present.", + }, + { + name: "stale-cross-reference", + pattern: regexp.MustCompile(`(?i)\bthis (bullet|section|document|doc|paragraph|note) (previously|originally|earlier)\b|\b(an?|the) earlier (draft|note|version|section) of this\b|\bthe earlier (draft|note|version)\b|\bpreviously said\b|\bused to say\b`), + remedy: "a reader cannot see what the document used to say, so the reference resolves to nothing. State the current decision; git history holds the rest. A supersede marker is fine when it names a file, a section or a symbol the reader can find.", + }, { name: "session-artefact", pattern: regexp.MustCompile(`(?i)\b(crew investigation|investigation pass|not committed|caught in review|this session|at time of writing|in this session)\b`), @@ -62,12 +72,33 @@ var rules = []rule{ // content being specified. var codeFence = regexp.MustCompile("^\\s*```") -// headerField matches the leading metadata block's own fields. A PRD records -// its own status and date there by design (RULES.md gives three statuses), so -// those lines are the one place a date and a status belong. -var headerField = regexp.MustCompile(`^\*\*(Status|Date|Parent|Blocked on|Supersedes|Superseded by):\*\*`) +// exemptHeader matches the two metadata fields that carry a status and a date +// by design (RULES.md gives three statuses). The match is deliberately narrow: +// a Date field holding only a date, and a Status field holding only one of the +// three. A wider exemption let "**Date:** 2026-09-03, Channel resolved +// 2026-09-22" smuggle a dated status into the one line the rules did not read. +var exemptHeader = regexp.MustCompile(`^\*\*Date:\*\*\s*20\d\d-\d\d-\d\d\s*$|^\*\*Status:\*\*\s*(Draft|Approved|Finalised)\s*$`) -// Lint reports every rule violation in one document. +// statusField matches the document's own status line, whatever it holds. +var statusField = regexp.MustCompile(`^\*\*Status:\*\*\s*(.*)$`) + +// statuses is the closed set from RULES.md. A status outside it is how a +// progress report gets into the one field the rules cannot read: "Implemented +// (wiring landed)" and "Ratified (rev. 2e). Rev. 2e adds..." were both really +// changelogs. +var statuses = map[string]bool{"Draft": true, "Approved": true, "Finalised": true} + +// statusRemedy is the status rule's fix. It is not in rules because the check +// is document-level: a missing field has no line to point at. +const statusRemedy = "every PRD carries exactly one of Draft, Approved or Finalised. Anything else is a progress report in the one field the other rules exempt." + +// LintDocument reports every violation in a whole document: the status the +// document must declare, then each line. +func LintDocument(name, content string) []Finding { + return append(lintStatus(name, content), Lint(name, content)...) +} + +// Lint reports every line-level rule violation in one document. func Lint(name, content string) []Finding { var findings []Finding inFence := false @@ -76,7 +107,7 @@ func Lint(name, content string) []Finding { inFence = !inFence continue } - if inFence || headerField.MatchString(line) { + if inFence || exemptHeader.MatchString(line) { continue } for _, r := range rules { @@ -87,3 +118,19 @@ func Lint(name, content string) []Finding { } return findings } + +// lintStatus checks the one status line RULES.md requires, since a missing or +// free-text status is not a line-level violation any pattern above would see. +func lintStatus(name, content string) []Finding { + for i, line := range strings.Split(content, "\n") { + m := statusField.FindStringSubmatch(line) + if m == nil { + continue + } + if statuses[strings.TrimSpace(m[1])] { + return nil + } + return []Finding{{File: name, Line: i + 1, Rule: "status", Text: line}} + } + return []Finding{{File: name, Line: 1, Rule: "status", Text: "no **Status:** field"}} +} diff --git a/tools/prdlint/lint_test.go b/tools/prdlint/lint_test.go index dfbe6fbf8..9dac19b45 100644 --- a/tools/prdlint/lint_test.go +++ b/tools/prdlint/lint_test.go @@ -56,6 +56,11 @@ func TestLintRejectsSessionBoundWriting(t *testing.T) { doc: "Phase 2 is complete and Phase 3 starts next.", rule: "phase-progress", }, + { + name: "temporal hedge", + doc: "`[notify]` today is one webhook URL, read in one place.", + rule: "temporal-hedge", + }, { name: "session artefact", doc: "Grounded by a crew investigation pass.", @@ -95,6 +100,35 @@ func TestLintAcceptsDurableWriting(t *testing.T) { } } +// TestLintRequiresACanonicalStatus: RULES.md gives three statuses, and a +// free-text one is where "Implemented (wiring landed)" hid a progress report. +func TestLintRequiresACanonicalStatus(t *testing.T) { + for _, tc := range []struct { + name string + doc string + want bool + }{ + {"draft", "# T\n\n**Status:** Draft\n", false}, + {"approved", "# T\n\n**Status:** Approved\n", false}, + {"finalised", "# T\n\n**Status:** Finalised\n", false}, + {"free text", "# T\n\n**Status:** Implemented (wiring landed)\n", true}, + {"status with a changelog", "# T\n\n**Status:** Ratified (rev. 2e). Rev. 2e adds a lookup\n", true}, + {"missing entirely", "# T\n\nBody.\n", true}, + } { + t.Run(tc.name, func(t *testing.T) { + var got bool + for _, f := range LintDocument("x.md", tc.doc) { + if f.Rule == "status" { + got = true + } + } + if got != tc.want { + t.Fatalf("status finding = %v, want %v", got, tc.want) + } + }) + } +} + // TestLintSkipsFencedBlocks: a code listing may legitimately contain a line // reference or a status string as the content being specified. func TestLintSkipsFencedBlocks(t *testing.T) { diff --git a/tools/prdlint/main.go b/tools/prdlint/main.go index c5141da11..ee2f4490a 100644 --- a/tools/prdlint/main.go +++ b/tools/prdlint/main.go @@ -79,7 +79,7 @@ func lintDir(dir string) ([]Finding, error) { if err != nil { return nil, err } - findings = append(findings, Lint(name, string(data))...) + findings = append(findings, LintDocument(name, string(data))...) } return findings, nil } @@ -89,6 +89,12 @@ func lintDir(dir string) ([]Finding, error) { func remedies(findings []Finding) []string { seen := map[string]bool{} var out []string + for _, f := range findings { + if f.Rule == "status" && !seen["status"] { + seen["status"] = true + out = append(out, " status: "+statusRemedy) + } + } for _, r := range rules { for _, f := range findings { if f.Rule == r.name && !seen[r.name] {