docs(prds): normalise statuses and remove writing dated to its own day

Three defects the first sweep left behind, each caught by a rule the guard
did not yet have.

Statuses. RULES.md gives three; the tree had 25 values, and the free-text ones
were carrying progress. "Implemented (wiring landed)" and "Ratified (rev. 2e).
Rev. 2e adds the OpenTaskByPR lookup. Rev. 2d revised section 10..." were both
changelogs living in the one field the other rules exempt. Every PRD now
declares Draft, Approved or Finalised and nothing else; five that declared
nothing now declare one. A revision number moves to **Revision:**, a pointer
to the authoritative document to **Authority:**, and what a past revision
changed to git. CLAUDE.md's citation of state-store-contract rev. 2e still
resolves.

Stale cross-references. "Supersedes the 2026-09-03 open question", "this
bullet previously said", "an earlier draft of this document claimed" all point
at text the reader cannot see, because it was replaced. A supersede marker
survives only when it names a file, a section or a symbol that can be found.

Temporal hedges. 100 uses of today, currently and right now across 31 files.
Each dates its sentence to the day it was written: "[notify] today is one
webhook URL, read in one place" stops being true the moment this design lands,
while still reading as the premise it rests on.

The header-field exemption was also too wide. "**Date:** 2026-09-03, Channel
resolved 2026-09-22" smuggled a dated status into the one line the rules did
not read; the exemption is now a Date holding only a date and a Status holding
only one of the three.
This commit is contained in:
sam committed 2026-09-22 00:38:35 +10:00
1 parent 2eba3487a8
commit fcde69c76c
48 files changed
+344 -258

No files matched your search

+1 -1
View File
@@ -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`
+11 -6
View File
@@ -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.
+3 -2
View File
@@ -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.**
+2 -2
View File
@@ -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
+67 -77
View File
@@ -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.
+3 -3
View File
@@ -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
+3 -3
View File
@@ -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.
+6 -6
View File
@@ -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`.
+2 -2
View File
@@ -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.
+3 -3
View File
@@ -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
+3 -3
View File
@@ -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"
+1 -1
View File
@@ -1,6 +1,6 @@
# Dashboard live state
**Status:** approved for implementation (2026-09-20)
**Status:** Approved
## Decision
+1 -1
View File
@@ -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),
+1 -1
View File
@@ -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),
+4 -4
View File
@@ -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
+7 -7
View File
@@ -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
+8 -6
View File
@@ -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
+13 -14
View File
@@ -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 →
+2 -2
View File
@@ -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
+1 -1
View File
@@ -1,6 +1,6 @@
# Event capture storage -- decision
**Status:** Implemented
**Status:** Finalised
**Date:** 2026-08-22
**Beads issue:** `archie-core-t2db.1`
+3 -3
View File
@@ -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.
+4 -2
View File
@@ -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.
+9 -7
View File
@@ -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.<name>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
+3 -3
View File
@@ -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
+9 -7
View File
@@ -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
+5 -5
View File
@@ -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 `<workDir>/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
+2 -1
View File
@@ -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)
+4 -4
View File
@@ -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
+5 -2
View File
@@ -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.
+3 -3
View File
@@ -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.
+1 -1
View File
@@ -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)
+1 -1
View File
@@ -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)
+2 -2
View File
@@ -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
+4 -2
View File
@@ -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),
+4 -4
View File
@@ -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.
+5 -5
View File
@@ -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.<name>]`.
- 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
+3 -3
View File
@@ -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
+4 -4
View File
@@ -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).
+19 -28
View File
@@ -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.<name>].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.<name>]`. 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.<name>]`:
```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
+2 -2
View File
@@ -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.
+2 -2
View File
@@ -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
+4 -6
View File
@@ -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.
+4 -3
View File
@@ -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
+3 -3
View File
@@ -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
+2 -2
View File
@@ -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,
+54 -7
View File
@@ -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"}}
}
+34
View File
@@ -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) {
+7 -1
View File
@@ -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] {