Commit Graph
222 Commits
Author SHA1 Message Date
sam c25f8d3956 chore(release): archied v1.36.0 2026-09-22 14:22:21 +10:00
sam 2cb2275eb6 docs(prds): settle identity for users, agents and external agents
One identity record covers users, agents, external agents, service accounts and the
system. Authentication is delegated to the estate's OIDC provider and attribution
stays archie's. Nothing that verifies a credential, issues a session, stores a
password or checks a permission is built here, per Sam's hard requirement that
authentication and authorisation are OSS archie integrates.

Authelia is the only provider, because the estate already runs it in front of the
dashboard and it issues credentials for both kinds of caller: authorization code
for humans and client_credentials for machines, whose subject is the client's own
identifier. Each agent is its own client, so two agents are distinguishable in the
audit trail and revocable separately. SPIFFE/SPIRE is rejected on operational fit
rather than quality: it is adopted and its attestation is strictly stronger, but it
adds a control plane archie does not have and answers a threat archie does not face
while its agents run in containers the operator launches.

internal/domain/identity survives and is not replaced by the provider's directory,
because it carries what the directory does not: lifecycle, bindings and
attribution. archie owns the subject binding that ties an identity to the provider
subject asserting it -- the same bridge identity_aliases already provides from a
legacy name -- plus the lifecycle, the attribution and the identity audit trail. It
owns no credential, password, session, token, signing key or permission rule.

How an agent proves who it is: it presents a token the provider issued to its own
client, archie validates it against the provider's published keys and takes the
subject as the acting identity, so an agent holds the secret and archie holds only
public keys. A WebMCP tool call cannot be a proof of agent identity and cannot be
made one -- a page can invoke its own tools, so an agent's call and a page script's
call arrive identically and the difference does not exist on the wire. It is
attributed to the identity the request presented with its source as a hint, and it
never records that an agent acted or that a human approved. Agent-initiated action
therefore arrives on a surface that carries a credential.

Task actions gain both attributions: the acting identity, derived from the
credential and never from a supplied string, and the authorising principal whose
authority the action used. The event kind describes the actor, so
KindHumanApproved is recorded only when a human acted; an agent acting under a
standing approval records itself as actor and the human as authorising principal.
An action with no authorising principal is unattributed rather than attributed to
the actor's own authority, and the review gate's approver is the approval's
authorising principal, not the surface they used.

External agents are first-class: the same record, kind service_account, bound to
its own provider client, at the cost of a client registration and a secret to
rotate per peer. Authorisation is deferred: no engine, no policy language, no
decision point, with the credential's scopes as the only input; the decision point
goes behind a single archie interface when per-skill limits are needed.

The PRD is a development-audience page, so it regenerates dev-docs.json to 69
pages. Verified: task check exit 0, including docs:prds.
2026-09-22 14:10:55 +10:00
sam 85e27e3778 docs(prds): cement A2A as the agent-to-agent protocol
Sam's decision, recorded as requirements rather than options. A2A carries
agent-to-agent work: discovery of what a remote agent offers, delegation of a unit
of work, progress on it, and the artifacts it produces. MCP stays the tool layer --
the two are complementary, and internal/tools/provider already registers MCP
providers as optional capabilities. A2A rides archie's existing transports, which
the protocol permits: its canonical data model is Protocol Buffer messages and it
defines a gRPC binding, so archie speaks it over the gRPC and NATS it already runs.

The boundaries are requirements. internal/domain/messaging stays the human and
channel layer, because a Conversation is a ChannelID and a ThreadID and its
participants are people. internal/agentexec stays the daemon-to-worker execution
protocol, whose Request, Result, gate and budget policy A2A never carries. A2A is
an edge protocol that composes with both.

The load-bearing decision, and the one that constrains everything downstream:
archie's work lifecycle is MAPPED to A2A's, not expressed in it. An A2A task is a
view over archie's own task, and archie's status stays the record of truth. Three
gaps make the mapping partial, and each is a fact A2A's states cannot hold: A2A's
terminal states describe what the agent did, while archie's merged and rejected
describe what a forge did afterwards; pr_open hands work to a human reviewer, while
A2A's input-required means the CLIENT must send more input; and declined, parked
and dead are outcomes of archie's own policy. Adopting A2A's state names as the
persisted task status is rejected outright -- it would migrate the task store and
drop the forge outcomes that tell a caller whether the work was accepted.

An A2A agent is an Identity: the actor archie persists, versions and scopes
credentials to. A persona is prompt text with no endpoint; an agent container is
task-scoped and ephemeral; the daemon is the process that serves the identity. The
Gateway serves the card for the identity it is configured as, over the gRPC
binding's Get Agent Card operation, and the card is derived -- skills from the
catalog, identity from configuration, capabilities from what the process already
advertises -- never hand-written, and carries no secret.

archie is a server first, because the work a peer would delegate exists only inside
archie. An inbound call is authenticated at the transport by the bearer-token
interceptor the Gateway already applies: A2A carries no identity in its payload, so
the transport credential is the identity. Authorization is per skill, which is
A2A's own model. Task-scoped grants are not A2A credentials -- reusing one would let
a peer act with a worker's authority -- and the dashboard's authentication gates an
operator interface, not an agent endpoint.

The new PRD is a development-audience page, so it regenerates the development
artifact rather than the public one: dev-docs.json goes to 68 pages and
docs.json is unchanged.

Verified: task check exit 0, including docs:prds, and both docsite checks.
2026-09-22 13:45:06 +10:00
sam a75df5eb0c feat(docs): split the published set by audience, public and development
The site's sidebar held the landing page and one guide next to seventeen
architecture records, the migration register, the review procedure and five
PRDs. Nothing there is secret -- every development page may be read by anyone --
but a reader who wants to know what Archie is and how to point an event at it
was meeting contributor material with no signal that it was not for them.

One source tree now yields two sets: public (index, guides/) under /docs/, and
development (architecture/, prds/) under /dev/, each with its own artifact and
its own derived sidebar. archive/, inspiration/, news/ and the credential notes
stay out of both, unchanged.

Selective PRD publication is gone rather than carried over. It existed only
because settled architecture cites PRDs and a link to a held-back target fails
the generator, so five PRDs published to keep those citations alive; with both
halves of every such citation in the development set, the exception has no work
left to do. Both sets are generated in one pass over one url map, so a citation
that crosses between them resolves to the base its target is served under, and
the refusal now fires only for a target genuinely in neither set.

Widening the set exposed a scanner bug worth its own note: the link regex
matched `Resolve[T](i, src, exportPath)` inside a code span and refused the page
for a link to `i,`. Code spans and fenced blocks are now skipped, because what a
renderer draws as a link is the only thing this tool may rewrite or refuse a
page for.

docs/prds/public-and-dev-docs.md records the decision. Draft: the three choices
in it are the maintainer's, the write-up is not yet reviewed.
2026-09-22 13:41:13 +10:00
sam 54ee79553f docs(site): describe archie as an event-driven agent platform
The landing page still opened with "archied is a resident daemon that polls a
forge", which is wrong twice over. A deployment is a set of contracted services,
not one process, and a forge is one event source among several: signed webhooks
from any sender and chat-channel messages reach the same playbook routing that a
GitHub or Gitea issue does. GitHub/Gitea was the first case, not the shape of the
product.

The intro now leads with the event path (event -> playbook -> workflow in an
isolated worktree) and says outright that sources, their fields, and the workflows
they reach are configuration rather than code. "What runs where" names the actual
services and which contract each owns. The stray "Work arrives as events." line
went with it, since the intro now states that.

Claims are held to what ships: module actions load and type-check but are not
dispatched yet, so the page promises one outcome per event, not a fan-out.
2026-09-22 13:24:23 +10:00
sam 457ad8843e docs(site): drop the internal-invariant clause from the landing intro
The intro stated per-task sandbox and credential isolation and daemon-owned
git to a reader who has no reason to act on it. Keep the event framing; the
enforcement detail stays in What runs where and ARCHITECTURE.md.

Regenerate docs/data/generated/docs.json with task docs:artifact.
2026-09-22 13:06:51 +10:00
sam 1b54a18e43 feat(docs): emit the canonical public-docs artifact the app renders
MkDocs retires and the Astro app becomes the only public site, so the artifact is
the product and the Markdown stays the source -- the split tools/newsgen already
states for releases. tools/docsite walks the published set and writes
docs/data/generated/docs.json: every page's directory-style url, title, section and
raw Markdown body, plus the sidebar tree derived from the layout.

Three things the artifact has to get right, each of which was wrong in a draft:

- LINKS. The published pages carry relative .md links that MkDocs rewrote at build
  time and nothing else will. Each is rewritten to the target page's url using the
  same function that builds urls, so a link and its target cannot disagree; anchors
  and scheme-qualified links pass through; assets resolve by the same rule and none
  are referenced.
- FRAGMENTS. A link can resolve to a page and still be broken, because a fragment
  matching no heading lands the reader at the top of a long document. Each is
  checked against the target's headings, by the slug rule a table of contents uses.
- REFUSAL. A link whose target the set holds back, or whose fragment matches no
  heading, fails the generator naming the file, the line and the target. This found
  three citations from settled architecture pointing at two PRDs the blanket prds/*
  exclusion withheld -- links that were already 404s on the published site, so the
  exclusion broke citations rather than withholding drafts. Both targets are now
  published, for a reason distinct from the three ratified PRDs already published.

The published set moves out of mkdocs.yml into the generator with its reasons: a
renderer reading the artifact cannot see why a page is absent. docs/data/generated
is accounted for by docsgen's generatedArtifacts, which now names this file beside
contracts.json -- one ownership registry for the directory rather than one per
writer, so neither tool reports the other's artifact as unaccounted.

docs:artifact regenerates; docs:artifact:check reproduces into memory and fails on
drift without touching the tree, wired into task check beside news:check. The
existing docs:site target is MkDocs and was left alone -- a first attempt at that
name silently ran MkDocs and produced nothing.

Verified: task check exit 0, docs:artifact:check reporting 23 pages. The artifact
carries 23 pages, no archive/ inspiration/ or news/ entry, and the five PRDs the
set declares. Coverage: the published set and its count, url derivation, the nav
tree, both refusal paths, and check's no-write guarantee.
2026-09-22 12:44:18 +10:00
sam 460722f251 chore(release): archied v1.35.0 archie v1.35.0 2026-09-22 09:52:14 +10:00
sam 3f2a3294d9 docs(eda): record the shipped action-playbook rules and stale claims 2026-09-22 09:51:40 +10:00
sam f498f593c9 fix(eda): authoritative module ids and stricter action load errors 2026-09-22 09:41:31 +10:00
sam 85a671491f fix(eda): tie module results to checker and tighten action ids 2026-09-22 09:22:45 +10:00
sam 966d587638 docs(prds): approve the multi-action playbooks design 2026-09-22 09:02:36 +10:00
sam bfdb88a60e docs(prds): design the first non-workflow position and typed action results 2026-09-22 08:28:26 +10:00
sam d6f526ce4f feat(state): carry channel lifecycle from the Messaging Service to the dashboard
archie-core-8cda.6.8's carrier. The service now records channel lifecycle and has
nowhere to put it: /api/channels answered with nothing because
webui.Server.Channels had no production source, and reload answered 501 for the
same reason. This adds the surface the register decided on, following the split
archie-core-ymut established for config snapshots -- a pair of administrative RPCs
whose writer is one process and whose reader is the UI -- and wires both ends.

Wire and store: PutChannelStatus / ListChannelStatus, with ChannelStatus carrying
id, name, state, detail, configured, reload_supported and observed_at. The store
holds one row per channel and replaces the reported set, so a channel the reporter
no longer mentions is deleted rather than left standing as a stale "running"; an
empty report clears the table, because hosting no channels is a fact worth
reporting. A row without an id is refused: it could never be replaced or removed
by a later report.

Writer: the service publishes on every lifecycle transition through a coalescing
signal -- a burst of transitions is one write, since a reader only wants the latest
state of every channel -- plus a start-up report and a final report after shutdown,
so a stopped service leaves the store honest. A failed write is logged and retried
on the next signal; the dashboard losing channel state is worth a warning and never
worth failing a channel start over.

Reader: webui.Server.Channels becomes a source rather than a concrete manager, and
webui.RemoteChannelStatus reads the store the way RemoteConfigView reads the config
snapshot. A store it cannot reach reports nothing rather than a stale "running",
and a state the reader does not recognise is carried through rather than dropped.

The contract's own index gains the group in the same change that adds the RPCs --
a surface the grouped table does not list is one nobody finds -- and the count moves
to 51. The register records why the surface is the State Store rather than a
resource kind, and why reload gets its own surface rather than a field here: reading
status must not be able to retrigger an action, a transient request is not
distinguishable from state once anything polls it, and it would invert the
writer/reader relationship the precedent establishes.

Verified: task check exit 0. New coverage: the store's replace-the-set semantics
and its refusal of an id-less row, the reader's mapping including an unknown state,
and the publisher's start-up, transition and final reports.
2026-09-22 08:04:44 +10:00
sam fb265f2ad0 feat(messaging): record channel lifecycle, and decide its surface
archie-core-8cda.6.8's producer half. The service handed every channel an empty
channels.Lifecycle{}, so starting, running, failed and stopped were recorded
nowhere and internal/channels/status.Manager -- which has had MarkStarting,
MarkRunning, MarkDegraded, MarkFailed, MarkStopped and Snapshot all along -- had no
production writer at all. The channels have always reported: all three call
ReportStarting and ReportRunning on whichever lifecycle they are given.

Each composed channel now gets its own report into a manager keyed by channel, so
one channel's failure marks only itself; a channel that cannot start is marked
failed with its reason rather than only logged, and a channel that returns is
marked stopped. Service.ChannelStatus is the producer a dashboard surface reads.

Left open deliberately: the cross-process carrier, and reload's direction.
docs/architecture/migration-decisions.md records the shape by the precedent the
contract already establishes -- archie-core-ymut's config snapshot is "the one
surface whose writer is the daemon and whose reader is the UI process", a pair of
administrative RPCs deny-by-default under authorizesTaskScopedCall -- and names
what that settles: channel state is runtime state rather than a settings document,
so it does not belong among the ControlPlaneService's validated resource kinds; the
UI already dials the State Store and pumps its cursor, so no new transport is
needed; and the contract PRD's grouped table gains a group in the same change that
adds the RPCs. Reload runs the other way and is left as a named open question
rather than decided by analogy with a status report, because a request queue and a
status report do not have the same lifetime. It also records that 8cda.6.9's
component self-report is the same shape, so the two do not become two homes for
"what a component reports about itself".

Red-proofed: restoring the empty lifecycle fails TestServiceRecordsChannelLifecycle
with "channel webhook never reached running; last report State:configured", so the
test pins the fix rather than the manager's existence.

Verified: task check exit 0.
2026-09-22 07:57:29 +10:00
sam f39fdd73a0 docs(architecture): record the messaging severance as it landed
The register described a design written before any measurement existed, and two of
its open questions were answered while landing archie-core-1ng1 -- both by
measuring rather than by preference. The client did not become two packages: the
workflow and persona watches stayed on internal/app/controlplane's Client, which
now embeds the new one, so the daemon's validated watch is still defined once and
the read path still has one implementation. And the vocabulary stayed in
internal/infrastructure/controlplanerpc rather than moving to a domain package,
because it has exactly one consumer and the store-backed side reads the same
definitions through type aliases rather than a copy.

It records what made that safe rather than asserting it: internal/app/controlplane
was the ONLY direct import of the Messaging Service that dragged a banned runtime
-- gatewayrpc, staterpc, applystatus, messaging, configuration, readiness and health
were all clean -- so severing that one dependency sufficed and no third package was
needed. The workflow/task exception the gate carries is recorded too, with the
verification that justifies it rather than the precedent alone.

Two questions stay open and named: whether the store-backed server also leaves
internal/app/ (archie-core-8f4n), and whether internal/domain/workflow's
contract/engine split happens (archie-core-inh6). Promoting the vocabulary to a
domain package is recorded for the day a second consumer appears.

Committed without pushing on purpose: a docs-only push to main republishes :latest
with a dev stamp for no benefit (archie-core-i5nb), so this rides with the next code
change.
2026-09-22 07:28:11 +10:00
sam 5adb19947c docs(architecture): record the Phase 4 messaging severance plan
archie-core-8cda.6's fourth criterion cannot pass: the PRD's deletion gate for the
Messaging Service does not exist, and the check it names reports four banned
packages linked -- modernc.org/sqlite, internal/store, internal/domain/workflow and
internal/agentexec -- all through one import, archiemessaging/run.go ->
internal/app/controlplane, from which the service uses three symbols. The decision
is to sever rather than amend the gate, because a boundary you whitelist around is
no longer a boundary.

This records the plan before any implementation: what moves (every kind constant,
the channel-settings vocabulary and its decode, the generic client, the persona
watch, the workflow-settings document), what stays and why (the store-backed server
and Definition registry, WorkflowDefinitionsClient and stepRegistry,
WatchWorkflowExecutionSettings because decodeSettings returns and validates
workflow.ExecutionSettings, the schedules document because a domain vocabulary may
not import infrastructure, the schema derivation), and where the pieces go
(internal/domain/controlplane for the vocabulary,
internal/infrastructure/controlplanerpc for the client, mirroring gatewayrpc and
staterpc).

Four decisions are named rather than taken, so archie-core-8cda.6.5 does not
inherit them: whether the server also leaves internal/app/; where
WatchWorkflowExecutionSettings lives, given it cannot share a package with the
client the Messaging Service imports; whether internal/domain/workflow's
contract/engine split happens and when; and whether archied's watches move with the
client. Both existing consumers keep compiling, and the Messaging Service's
dependency set loses all four banned packages.

Verified: task check exit 0, docs-only change, docs:check and docs:prds green.
2026-09-22 07:17:06 +10:00
sam 2ae831abd7 chore(release): archied v1.34.0 2026-09-22 07:14:25 +10:00
sam a8517c9d18 chore(release): archied v1.33.0 2026-09-22 05:59:16 +10:00
sam 0b05c2168e chore(release): archied v1.32.1 2026-09-22 05:43:46 +10:00
sam a02f7730f9 docs(site): state git ownership instead of positioning archied
The landing page opened by defining archied against a category the reader
never raised, then listed security features. State what the daemon does
and who owns git operations; drop the contrast.
2026-09-22 05:25:29 +10:00
sam 83e9c33282 feat(docs): publish generated news and per-version release notes
Derive a public news page and one release-notes page per component version
from CHANGELOG.archied.md and CHANGELOG.archie.md, the notes the release
process already freezes.

- tools/newsgen writes docs/news/releases.json, the canonical artifact a host
  renders from, plus the MkDocs pages. Check mode fails when the committed
  files lag a changelog edit, and runs in task check; tools/release.sh --tag
  regenerates and stages them in the release commit, skipping files already
  current.
- mkdocs.yml keeps the version pages out of the derived navigation without
  excluding them from the site.
2026-09-22 05:03:29 +10:00
sam 39ba283e47 test(eda): pin playbook dispatch ledger docs and regression gaps 2026-09-22 04:51:17 +10:00
sam 3be7e4cdb0 fix(eda): wire playbook dispatch ledger and validate its key 2026-09-22 04:36:28 +10:00
sam ca433865b0 fix(archied): build the Gateway's worktree manager so it serves review_pr
boot.prReviewer returns nil without a worktree manager, and a nil reviewer
omits review_pr from every channel's tool set. RunGateway never called
buildTreesAndIdentities, so the Gateway resolved a nil reviewer and no
channel could review a PR.

Extract the manager's construction into boot.buildWorktreeManager, called
by buildTreesAndIdentities (daemon, unchanged field-for-field) and by
startGatewayRuntime before setupGatewayChat. The Gateway does not call
buildTreesAndIdentities: that also registers daemon identity runners the
Gateway must not own, and PR review only needs a clone of the PR head,
which worktree.Manager.CheckoutPR does from the forge.

Pin the ordering by source position in composition_order_test.go, alongside
the memory-engine ordering the same function already carries, and pin both
compositions behaviourally in worktree_manager_composition_test.go: the
Gateway's step must yield a reviewer that advertises review_pr, and the
daemon must still build its root manager plus one runner per identity with
a distinct WorkDir.

Correct docs/prds/operator-pr-review.md, which still asserted the daemon
supplies ChatPRReviewer and holds the review in-flight set.
2026-09-22 03:44:45 +10:00
sam a73a33a997 docs(prds): correct the PR review PRD's stale owner and file list
Section 1 attributed the PullRequestReader type-assertion to the daemon while
section 4 now correctly says the Gateway serves review_pr, and the Files list
cited internal/app/archied/telegram_setup.go, which does not exist. Both found
by the cp-gwreview lane and left by it as out-of-scope staleness.
2026-09-22 03:38:49 +10:00
sam 1fe4691bd6 fix(webhook): keep a route path out of the sender identity
A webhook set SenderID to its configured route path. The turn path reads that
field through a per-channel resolver which refuses webhook, but the session
curator derives its participant from the raw field with no channel filter, so a
webhook session with exactly one distinct sender and one extracted fact wrote
agent-user memory addressed to User: "/hooks/...". Nothing reads it, and every
pass added more, because the facts are identical strings with no dedup.
docs/prds/memory-engine-unification.md criterion 7 requires that a route path
never become a user identity.

Clear it at the producer rather than teaching every consumer which channels are
lying: a route path is a source, not a person, so it no longer enters SenderID.
It still keys the inbound rate limit, where it is the documented per-source
budget for webhooks (config.RateLimitConfig), so it travels in the new
transport-only Inbound.BudgetKey -- carried on the wire beside Page, never
persisted, and never read as an identity.

pb.Message gains budget_key (field 9) for the same reason page (field 7) exists:
transport context that rides with an inbound message and is deliberately absent
from storedProto's rendering of a canonical record.

The curator needs no change. An empty SenderID already fails closed as an
unidentified user message, which is the path a dashboard session takes, and
sessionParticipant's existing skip covers it; the test name now says so.
2026-09-22 03:18:59 +10:00
sam 2e6540a838 fix(archied): serve only the health facts a /status reply can carry
setupGatewayChat is the only production constructor of a Router and it runs
in the Gateway, which owns no container pool, no poll loop and no channel
manager. The producers wired to those three built report sections no reply
could carry, and /status' own description of itself claimed all five fields.
The health source now carries the broker connection and the chat-model
outcome, the two facts the answering process holds.

The tests for the deleted producers go with them, replaced by one that pins
the served shape with a pool and a daemon present in the boot.

Corrects docs/prds/status-health-surface.md, where the intro, the Phase 2
summary and the rendering bullet all claimed the five-line surface.
2026-09-22 01:58:00 +10:00
sam 51524a8b83 docs(eda): point the expression PRD at its unbuilt decisions
Three of its decisions have no implementation: J1 action ids, J2 args as CEL,
and generated Result schemas declared to CEL for field-level result typing.
That is why it stays Approved rather than Finalised, so the header names the
beads that close the gap.
2026-09-22 01:57:00 +10:00
sam ac7ffe343a docs(eda): split the expression decision out and cut the playbook PRD to its design
The playbook engine PRD had grown to 972 lines against CLAUDE.md's one-page
bar, because four documents were living in it.

The expression decision was the worst of it: an H2 nested inside a numbered
list item, 270 lines with twelve H3s and its own Status and Date fields. That
broke the outline and gave the document a second, non-canonical status. It is
now docs/prds/playbook-expression-syntax.md, named flat and linked by a Parent
field the way module-position.md already relates to this epic. The parent
keeps the decision and a pointer.

Repetition, against the state-each-fact-once rule: reject-at-load was stated
ten times, the plugin engine rule nine, producer-only seven. The producer-only
argument ran 32 lines and closed by restating itself; it is eight lines and
stated once. One heading read "confirmed non-issue (stated once)" above the
third statement of the point.

Open question 3 was closed by module-position.md and still listed here as
open. The section holding four decisions and one note is no longer called
"Open questions", and the note is a standing constraint, which is what it is.

Also removed: two list summaries written before their lists, ten dated
attributions, two progress claims, three orphan line citations, and the
undefined { Call: ... } notation.

Five findings in other PRDs came from tightening the guard, not from this
split.
2026-09-22 01:07:05 +10:00
sam f600eb01aa docs(eda): approve the Channel and Forge positions PRD
Maintainer sign-off on the Channel resolution. Draft -> Approved.
2026-09-22 00:50:11 +10:00
sam e832b8ef0c 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.
2026-09-22 00:38:35 +10:00
sam edce8fa1d8 docs(prds): remove session-bound writing from every PRD
183 findings across 28 of 46 PRDs, of which 150 were file:line citations. Two
were already hard-broken: one named a file that no longer exists, one pointed
past the end of its file. The rest resolved to a line that still exists,
which is the worse failure -- a citation that silently drifted onto unrelated
code still reads as authoritative.

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

eda-playbook-engine.md was the worst file and my own t2db.23 status block was
part of why; it is rewritten as the resolution it records.
2026-09-22 00:21:28 +10:00
sam fd8f180715 build(docs): gate docs/prds against session-bound writing
A PRD states a decision, a requirement, a constraint or evidence. Those
survive the code moving underneath them. A line number, a progress report or
a dated status claim does not: it is true on the day it is written and
silently wrong a month later, while still reading as authoritative.

prdlint rejects five shapes: file:line citations (including a document citing
its own line numbers), dated status claims, progress reports on the work
being designed, phase-completion narration, and records of how a finding was
produced. Each finding names the file, line, rule and fix.

The rules target decay, not subject matter. A PRD may describe a phased plan,
name a dependency that exists, and carry its own Status and Date header
fields; what it may not do is assert the state of the tree on the day it was
written. Fenced blocks are skipped, since a listing may specify a line
reference as its literal content.

Wired into task check next to docs:check. A sweep alone would not stop the
class recurring.
2026-09-22 00:21:27 +10:00
sam 51ed7178e6 docs(eda): strip status and editing narration from the positions PRD
Headings carried scheduling status the Blocked-on line already states, and
two paragraphs narrated how the document was written rather than what was
decided. Both violate the PRD rule that every sentence adds a decision,
requirement, constraint, evidence or verification step.
2026-09-22 00:09:02 +10:00
sam 44dde18918 docs(eda): resolve the Channel action position
Notification is a contract in internal/domain/messaging, not a channel type.
A channel implementation satisfies it by importing its own parent, which it
already does, so channels.Channel gains no notification method and no import
and the dependency stays channels -> messaging. A notification has no
lifecycle, no inbound direction and no config schema, so modelling it as a
channel would force Start/Stop/ConfigSchema onto something with no meaning
for them.

Destinations are configured, never named by a playbook: [notify] grows from
one webhook URL into named destinations, each binding a name to a channel
already registered in the Messaging composition plus that channel's address.
An action names a destination. Playbook triggers are reachable from a public
intake surface, so an action that could address an arbitrary chat would be a
new exfiltration surface.

Host access needs no new process surface. archie-messaging dials out only and
deliberately has no NATS connection, so nothing can push to it today.
Delivery travels the Gateway connection every process already holds, as a new
server-streaming RPC on ChatService; the per-turn Stream RPC is not reused.

The 2026-09-03 section presenting two options is superseded. Its claim that no
send capability exists anywhere was too strong: telegram.SendPendingReport
already sends unsolicited to a stored chat id, with no interface for it.

Closes archie-core-t2db.19
2026-09-22 00:06:52 +10:00
sam 61887fd781 feat(eda): wire the playbook coordinator into production workflow selection
A loaded playbook now decides a real task's workflow. The wiring point is the
daemon's definition pin (Daemon.resolveWorkflowID, consumed by
pinWorkflowFromCollection), not pollNATS/publishTask as the design doc
assumed: routing moved out of the agent process when workflow definitions
became database rows pinned before dispatch, so the pin is the one place a
task's workflow is chosen.

Precedence: an explicit Task.Workflow (the waiting_human -> approved requeue)
still wins, then a matching playbook, then workflow.ResolveWorkflowID's
existing label/kind bindings. A playbook naming an undefined workflow is a
reported failure that parks the task rather than a silent fall-through to the
binding's choice -- the operator bound that trigger deliberately.

Store.Dispatch returns the selected workflow name plus the matching playbook's
id and version, instead of a compiled workflow.Workflow: the production caller
decides against the active definition collection, and the id/version are the
first two components of the resolved gap-2 idempotency key. The playbook
package no longer imports internal/domain/workflow.

The shipped example's `when` read event.priority, a field no intake supplies,
so it could never have fired once wired. Both examples now read the event
surface playbookInput really builds, and label-trigger.yaml documents the axis
an instance defines for itself: trigger.kind is the closed workintake
vocabulary because a kind addresses a NATS subject, while trigger.labels is
free-form and binds an operator's own taxonomy to a workflow.

Module/Channel/Forge positions stay rejected at load; they need the
playbook_dispatches ledger first (archie-core-t2db.24).

Closes archie-core-t2db.23
2026-09-21 23:47:06 +10:00
sam 08df95684c fix(statestore): read a kind the store does not hold as its seed, and stop validate touching the daemon's log
Four defects from the re-run contract review, all in the recovery path.

A store missing a control-plane kind was refused while a store with no
resources table at all was accepted -- two stances inside validateStore for
states the daemon cannot tell apart. The State Store seeds every kind from
its own config before it serves (RunStateStore -> ImportConfig), so a kind
the file does not hold yet is one archied reads the seed for: an upgrade that
adds a kind, and a validate before the State Store has started again, exited
1 with "read provider-settings: resource not found" for a store the daemon
boots on fine. StoredRuntimeConfig now reads a missing kind as the seed the
State Store would write for it (Definition.seededValue, shared with
ImportConfig so the two cannot drift), and the missing-table branch is the
same stance taken to its extreme.

defaultConfigPath() derived the daemon's config with os.UserConfigDir, which
disagrees with archied's configHome on darwin and rejects a relative
XDG_CONFIG_HOME outright -- leaving validate with an empty path and no
verdict, on a host where archied boots from relative-dir/archie/config.toml.
It is now the daemon's own rule, exported as archied.DefaultConfigPath and
used by the daemon's own -config default too, with a test pinning the
equality.

-h exited 2, the code documented as "the command line was wrong", while the
serve path in the same binary exits 0 and main.go advertises -h for these
subcommands. ErrHelp now returns 0.

validate resolved the boot config through loadConfig -> setupLogging, which
created cfg.Log.File's directory, opened the log, and wrote a line stamped
component="daemon" -- a diagnostic editing the deployment it inspects, and
rotating a log the daemon is writing. boot.stderrLog keeps setupLogging on
the stderr logger for the recovery path: no feed, no task-log registry, no
durable copy.

Tests: TestRecoveryValidateRunsTheGateBootRuns now asserts the unseeded and
the missing-kind stores are accepted (both exited 1 before), while the
bogus-policy case still refuses; TestRecoveryHelpExitsZero,
TestRecoveryValidateLeavesTheDaemonLogAlone and
TestRecoveryDefaultConfigFollowsTheDaemonsConfigHome are new. Each was run
red first, and the seed fallback and stderrLog were mutation-checked.
2026-09-21 22:04:42 +10:00
sam e7e5ddfba5 fix(statestore): make validate run boot's gate, and stop backup replacing the database
Two P1 findings from review, both about a claim outrunning the code.

validate answered a different question from boot's. Boot refuses on
configuration.Validate over the file config with every stored resource
layered onto it (internal/app/archied/control_plane.go:27), which is a
stricter check than the write path's per-resource Decode: validateScheduling
never inspects dispatch.trigger and explicitly permits "0s", while boot
rejects an unknown trigger and a non-positive poll interval. A store holding
such a value printed "is a valid store ... N stored resources validate" and
exited 0 while archied exited 1 on it -- a false green pushing an operator
toward the blunt restore instead of the surgical rollback.

validate now runs both layers and reports both, in boot's order:
store.ValidateFile, then the write path's ValidateStored, then the config
gate. The layering itself is now one implementation: controlplane's
runtimeConfigFrom takes a resourceReader, which the gRPC client and a new
Server.StoredRuntimeConfig (reading its own store) both provide, so the
offline check cannot drift from the daemon's. validate takes -config /
-config-overlay (default: the path the serve subcommand uses), because the
question is about the stored values layered onto that document.

backup had no guard against -out naming the database. It renames its
snapshot over the target, so `backup -db F -out F` replaced a database a
serving State Store may still have open and orphaned the WAL of the file it
just unlinked -- the state Restore refuses up front and maintenance.go's own
comment calls unrecoverable. backup now refuses with the same message
Restore uses, which is what makes its exemption from the ownership lock
sound.

Claims corrected where they ran ahead of the code: ValidateStored now says it
is the write path's check and not boot's, the Restore comment no longer
promises "never a mixture" for the sidecars it removes first, the usage text
advertises validate's -config, and the architecture table drops "must be
stopped" for validate (nothing enforces it; read-only opens skip the lock by
design) and states which two layers validate reports.

Tests: TestRecoveryValidateRunsTheGateBootRuns fails on the pre-fix code
("validate accepted a stored policy the daemon refuses to boot with") and
covers a store the State Store never seeded; TestRecoveryBackupRefuses-
TheDatabaseAsItsOwnSnapshot fails on the pre-fix code ("backup over the
database itself succeeded"). The validate-accept test now seeds the store
through ImportConfig and asserts the reported count is non-zero, and the
stored-resource case uses a value both gates refuse instead of one only the
write path does.
2026-09-21 22:04:42 +10:00
sam b8b477fb32 feat(statestore): offline backup, restore, validate and rollback
archie-state-store gains the offline recovery commands
docs/prds/runtime-control-plane.md ("Bootstrap, migration, and recovery")
asks for. They work on the task database file directly -- <db_path>-tasks.sqlite,
not db_path -- and need neither archied nor the Web UI, which matters because
the failure they exist for is the one that stops archied starting:

  backup   -db F -out F     consistent snapshot (VACUUM INTO), verified as a
                            usable store before it is published; safe against
                            a serving store
  restore  -db F -from F    replace the database with a snapshot, dropping the
                            replaced file's -wal/-shm
  validate -db F            readable, not corrupt, schema no newer than this
                            binary, every stored resource decoding under the
                            definition that owns it
  rollback -db F -kind K    replay an earlier revision of a stored resource
           [-revision N]    through the ordinary replace, recorded as a new
                            revision

No rollback RPC is added and none is needed: a revision carries its own value,
so restoring one is the same replace the dashboard and the channels already
use, by hand, with the store stopped.

"The State Store is stopped" is checked rather than assumed. The serving
process now takes an exclusive flock on <db>.lock for its whole life
(store.AcquireOwnership), and restore/rollback refuse with
`task database is owned by another process` while it holds it. backup is the
deliberate exception: the update installer runs inside the process it is
replacing and cannot stop the State Store.

scripts/archie-update-install takes its pre-flight snapshot through
`go run ./cmd/archie-state-store backup` from the release being installed
instead of its own sqlite3 shell, so the installer and an operator run one
implementation. The watchdog's refusal semantics are unchanged: an update that
cannot back up still must not start.

Docs: safe-change-and-recovery.md's "Recovery: not yet built" now describes
what exists.
2026-09-21 22:04:41 +10:00
sam 442368ff8b docs(architecture): a new command is not a reason for a new binary 2026-09-21 17:18:58 +10:00
sam d38e27fdf0 feat(webui): show which process is running which settings version
The settings page now reads apply status beside each resource: every known
process with the version it applied, its error if it rejected the edit, and
whether it is still reporting at all. It re-reads after each save, so the page
reflects what the processes did with an edit rather than what was stored.

The server derives liveness only, because it knows whether a record went stale
but not which version the page is showing. The client compares against the
resource it is rendering, which is what turns a live record on an older
version into a pending restart.

A process that stopped re-stamping and one that never reported are separate
rows with separate wording, and neither is an error: the setting may be fine
and the process simply absent, which an operator acts on differently. A failed
apply-status read leaves the previous rows rather than taking the settings
page down with it.

state-store-contract.md gains the pair in its inventory and its count moves
from 45 to 47, with the note that this read is a list rather than the
config-snapshot pair's found=false singleton.

Closes archie-core-pskb.
2026-09-21 15:57:46 +10:00
sam d9dd7885b7 feat(statestore): carry control-plane apply status on the store contract
Adds PutApplyStatus/ListApplyStatus so each process can report which version
of a control-plane resource it is running, and the UI can read it back.
docs/prds/control-plane-apply-status.md is the approved design.

It goes on the State Store contract rather than the control plane, whose
service is for editing a resource: a status report is not an edit. The
config-snapshot pair is the precedent, and the deny-by-default arm of
authorizesTaskScopedCall already refuses both new RPCs to a task grant, which
TestOnlyAdminReportsApplyStatus pins.

The row is keyed on (process, kind) and replaced in place, because a process
re-stamps on an interval and nothing reads a history of re-stamps. An error
leaves applied_version alone, so a rejected edit never erases the fact that an
older version is live. The read is a list and an empty one is not an error,
unlike the config snapshot's found=false singleton.

Contract PRD inventory and RPC count follow in the same series.

Relates to archie-core-pskb.
2026-09-21 15:44:31 +10:00
sam 1dd0d87466 docs(prds): leave apply-status liveness open instead of deciding it
RULES.md says not to turn a requested outcome into extra product features and
to keep inferences open until the maintainer or repository evidence settles
them. The first draft broke that: a reviewer found that a record replaced in
place lets a process that applied a version and then died keep reading as
current, and I answered it by adding a periodic re-stamp, a recurring write in
three processes that neither the tracking issue nor runtime-control-plane.md
asks for.

The hazard is real, so it stays in the document as an open question with three
options and a recommendation, for Sam to settle. The re-stamp and the instance
identity come out of the design.

Also the sentence pass RULES.md requires before approval, which had not been
done: the staleness rule was stated in three sections, and rationale stood
where a requirement belongs.

Relates to archie-core-pskb.
2026-09-21 15:33:14 +10:00
sam 731a9a06e6 docs(prds): decide where control-plane apply status is reported
runtime-control-plane.md requires each process to report the version it is
using or why it failed, and does not say where that report goes. It cannot be
a control-plane operation: that service is the surface for editing a resource,
and a status report is not an edit. It goes on the State Store contract,
following the config snapshot pair, whose administrative RPCs a task-scoped
grant already cannot reach.

Draft, pending approval. Reviewed by three independent lenses first, per
docs/prds/RULES.md. The operator lens opposed the first draft on two counts
now fixed: a record replaced in place with no re-stamp would let a process
that applied a version and then died keep asserting health, inverting the
choice status-health-surface.md made deliberately; and the dominant failure,
an unreachable State Store, can never report itself, because every apply point
is reached only after the store has answered. The draft now carries instance
identity and a re-stamp interval, says plainly which failures are reportable
at all, and gives the three kinds of absence distinct renderings.

The boundary lens required the surface be reconciled against ConfigView's
reload status rather than duplicating it; apply status covers resource kinds
and ReloadStatus stays the file document's only report. The contract lens
established that task-grant denial needs no new rule, that the read is a list
rather than a found=false singleton, and that the contract's RPC count moves
from 45 to 47 in two places.

Relates to archie-core-pskb.
2026-09-21 14:55:04 +10:00
sam 9af013eb3b fix(archied): re-apply database-owned settings on SIGHUP reload
The reload callback re-resolved the file document and republished it as the
running config. Every setting the control plane owns lives only in the
database, so a reload reverted providers, model roles, repository policies,
channel settings, scheduling policy, tool and plugin settings, container
policies and workflow execution budgets to their file values until the
process restarted, and logged "config reloaded" while doing it.

Boot's layering is now one call, boot.runtimeConfig, and the reload makes the
same call over the document it just resolved. Execution budgets arrive on a
watch rather than in a resource query, so boot records the last settings it
applied and the reload re-applies them from there.

apply gains an error return, which the controller records exactly like a bad
file: a control plane that cannot answer fails the reload and leaves the
running config alone, because it already holds the values the file does not.
The query is bounded at 10s so a State Store that stops answering surfaces as
a failed reload rather than a SIGHUP that never returns.

The callback also read the old config from b.d.Cfg, the same Holder as
b.cfgHolder; reading it from the Holder boot owns drops the daemon from this
path and makes it testable.

Closes archie-core-ju85.
2026-09-21 14:41:50 +10:00
sam 85f0fd0b28 docs(architecture): purge the deleted runtime config overlay
31622ec5 deleted the overlay but not its documentation of record, leaving
docs/architecture/ asserting a subsystem that no longer exists.

safe-change-and-recovery.md was the dangerous one. It listed three ways back
from a bad runtime setting, all of them gone, so its recovery section was a
dead end. The replacement records the posture honestly: the control plane
fails closed, a stored value that will not validate stops the daemon starting,
and there is no escape hatch until archie-core-6zw0 lands.

configuration.md's ledger rows for the overlay store and the two dashboard
write routes become one row for the control-plane command. migration-decisions
marks the config-write descope superseded rather than deleting it, per
docs/prds/RULES.md.

Also removes leftovers the gate could not catch: a dashboard banner bound to
ReloadStatus.overlay_unavailable, a field the server stopped sending, and a
delivery-snapshot scan pointed at ApplyOverlayValues in a composition root that
no longer calls it.

The reload trace behind this found archie-core-ju85: SIGHUP republishes the
file document alone, reverting every database-owned setting until restart.
Recorded in the ledger as current behaviour.
2026-09-21 12:30:24 +10:00
sam 71d7da219a docs(prds): define three PRD statuses and approve the control plane
PRD headers carry 26 distinct status strings across docs/prds/. Draft,
Approved and Finalised are the only three, and a finalised PRD is superseded
rather than edited.

runtime-control-plane.md still read "Draft -- not approved" after it was
approved to proceed.
2026-09-21 10:43:08 +10:00
sam 924b02a1b0 feat(controlplane): runtime administration over the State Store's gRPC server
The Web UI and messaging channels now read and write Archie's runtime
settings through one versioned, audited control-plane API hosted on the
State Store's existing gRPC server: catalog, query, command, watch. Each
feature owns its resource, validation and commands; storage only writes
versions and audit records.

Workflows move with it. Definitions become portable YAML compiled through
a closed, typed step registry and stored as a control-plane resource, so
the yaegi interpretation paths (internal/gate, wfeval, wfextract,
gateeval, gateextract, skillbuild) are deleted rather than carried.

The UI process reads definitions as data: the JSON projection lives in
internal/domain/workflow/task so a dashboard decodes the stored
collection without linking the workflow engine, which cmd/archie-ui's
deletion gate forbids. Shipped definitions ride the catalog descriptor
rather than a bespoke REST route, keeping the API to its four operations.

archie-messaging gains -state-store-target/-state-store-token and reads
channel settings from the database, failing closed when the State Store
is unreachable: the database is authoritative for those settings.
2026-09-21 08:17:42 +10:00
sam 2c3a47de68 feat(tools): a capture-intake sender for exercising the Events surfaces
Posts to /webhooks/capture/{source} with a realistic GitHub, Sentry, form or
large payload (or an exact body), reads the capture back so a silent drop is
visible immediately, and names the intake's rate and size limits when it
hits them. Wired as task webhook:send.
2026-09-21 01:10:30 +10:00