Compare commits

...
204 Commits
Author SHA1 Message Date
sam 4242d94676 chore(release): v1.42.0
deploy / gate (push) Failing after 5m36s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
2026-09-26 10:32:39 +10:00
sam 1358c3d759 feat(prreview): benchmark harness scoring findings on the Martian problems
Scores a reviewer's findings on the 38 runnable Martian Code-Review-Bench
PRs: the deterministic core turns findings into posted comments, an
independent judge model matches them to the goldens, and the run reports
golden micro-recall and golden-only precision. The reviewer is a findings
fixture directory until the pr-review workflow lands.

Run with: task bench:prreview -- -findings DIR
2026-09-26 10:30:12 +10:00
sam 585df0f81e feat(agentexec): output adapters for Codex, Pi, OMP and Copilot CLI 2026-09-26 10:28:40 +10:00
sam a8c8dfbd7d feat(daemon): run a Kit profile's task in its Kit container on the egress path 2026-09-26 10:14:33 +10:00
sam bc215e8daa feat(config): Kit profiles pin a workload Kit and mixins by digest 2026-09-26 09:21:57 +10:00
sam 0d042b72d9 feat(agentexec): run a Kit task's stages on its harness through a named output adapter 2026-09-26 09:20:30 +10:00
sam 5507ded2d5 feat(storepkg): package descriptor with strict decoding and validation 2026-09-26 09:13:39 +10:00
sam 7a54db0cc6 fix(agentexec): count Claude cache tokens as prompt tokens, as the built-in loop does
Claude's input_tokens excludes cache reads and writes; the built-in
loop's Anthropic provider folds them into PromptTokens so budgets count
total prompt size. The harness adapter now does the same, so one budget
means the same on either runner.
2026-09-26 09:11:57 +10:00
sam 4067949ce8 feat(agentexec): parse Claude Code's stream-json output for the harness runner
Pairs tool_use and tool_result blocks by ID into tool-call reports, keeps
the latest session_id, takes the run's usage from the result event and
falls back to per-message usage, counted once per message ID, for a run
killed before its result. Tested on streams recorded from Claude Code
2.1.282 and scrubbed of host detail.
2026-09-26 09:11:57 +10:00
sam 92a9eca12c docs(architecture): state the shipped execution transition rules
The lifecycle block still showed `running -> merged` and never mentioned
`completed`. `running -> merged` is now illegal (taskstate transition table)
and `merged` is reachable only from `pr_open`; a workflow that opens no pull
request ends in the terminal `completed`.

Rewrite the block to the current rules and fold the crash-recovery requeue
into the `running` row it belongs to. Regenerate the committed docs artifact
carried by `task docs:artifact:check`.
2026-09-26 04:01:08 +10:00
sam 30211478c2 test(taskstate): seed fixture task states along the transition table
The execution transition table refuses most of the pairs shipped fixtures
wrote to build a finished task -- running -> merged, queued -> parked,
queued -> waiting_human, queued -> merged -- so those fixtures fail the
moment the store enforces it.

internal/taskstate/taskstatetest seeds a status by walking the table's
legal edges (shortest route, computed from taskstate.CanTransition), so a
fixture cannot write an illegal pair and fails loudly when no route
exists. The fixtures in internal/daemon, internal/app/archied,
internal/webui and internal/infrastructure/postgres go through it, and
the table's own test names running -> merged as refused.
2026-09-26 04:01:08 +10:00
sam 4e9b30d712 fix(daemon): keep a terminal worktree that holds uncommitted work
The cleanup added for no-change runs removed a `completed` task's
worktree whenever it had no PR. agent.run also ends its workflow
`StatusCompleted`, and it works in a real clone whose uncommitted edits
are the deliverable, so the status alone was enough to delete the work:
no commit, no push, no other copy of those edits anywhere.

Cleanup now reads the worktree first and skips a dirty one. A worktree
whose status cannot be read is kept too -- a wrong keep costs disk, a
wrong delete costs the work -- while one that is not on disk has nothing
to keep. The lifecycle fixtures prepare a real clone now, which is the
only shape the daemon ever cleans up, and the cancelled-context test
still cancels only the cleanup call.
2026-09-26 04:01:08 +10:00
sam f7bfd78d5f fix(ui): count completed runs as delivered on the workflows surfaces
The workflows page's per-workflow bar and its 'N of M' text, and the
workflow picker's percent on the new-task form, counted `merged` alone.
A workflow whose runs now end `completed` (a no-change build, a triage
that needed no code) therefore rendered zero delivery beside three
sibling surfaces that already counted both.

The count moves into ui/src/lib/delivered.ts, which GatePulseCard,
ThroughputTiles and TasksSummary now read too instead of keeping their
own copies of the arithmetic. The picker's label says delivered, not
merged: a run that ends completed is not merged.
2026-09-26 04:01:08 +10:00
sam 4f62ce5dfc chore(ui): rebuild the dashboard for the completed count 2026-09-26 04:01:08 +10:00
sam 845b192a89 feat(taskstate): count completed runs in the per-workflow stats
The transition table moved the no-change outcomes to StatusCompleted, so a
run that opens no pull request now ends in a status the per-workflow stats
did not count at all: it was not merged, not in review, not parked, and the
workflows page would have shown it as a run that went nowhere. The count
travels the whole State Store path, since every dashboard consumer reads it
through the gRPC client rather than the local store.

- WorkflowStats filters `completed` beside merged and pr_open; the SQL is
  the count, so a wrong filter reads as zero rather than failing, and
  TestWorkflowStatsCountsCompletedRuns holds it against a real store.
- storecontract.WorkflowStat gains Completed (json "completed"), the proto
  message gains field 9, and workflowStatProto/workflowStatValue carry it;
  TestWorkflowStatProtoCarriesEveryField round-trips every field by name.
- The gateway's chat task report names the status.
- The dashboard counts a completed run as delivered in GatePulseCard's
  totals and badge numerator, and the WorkflowStat/WorkflowStats/WorkflowRow
  interfaces carry the field.
- TestOutcomeSitesAreTransitionsFromRunning is the guard that keeps the
  producer and the table agreeing: it re-reads this package's tc.Outcome
  assignment sites from source and requires each status to be one
  internal/taskstate allows from running, so a new or moved site has to be
  adjudicated against the table instead of discovered on a live run.
2026-09-26 04:01:08 +10:00
sam 8ba0b90861 feat(taskstate): end no-change runs as completed and clean their worktrees 2026-09-26 04:01:08 +10:00
sam 7b86dd6cfe feat(taskstate): transition tables for executions and steps 2026-09-26 04:01:08 +10:00
sam 419334dfa2 fix(archied): resolve stored provider credentials at boot 2026-09-26 03:50:07 +10:00
sam 093e677ad8 fix(controlplane): reject stored boot-derived provider keys 2026-09-26 03:44:40 +10:00
sam 235b9c1a87 refactor(agentexec): own the capture file format in agentexec, not the app layer 2026-09-26 03:30:19 +10:00
sam 37d913c5fd feat(agentexec): serve capture tools to harnesses over MCP
archie-agent mcp is a stdio MCP server, on the official go-sdk, serving a
stage's capture tools and appending accepted calls to a captures file.
The harness runner writes the tool spec and a standard mcpServers config,
registers it through HarnessSpec.MCPConfig, and reads the captures back
into the stage result. The captures file is writable by the harness user,
so the worker validates every record again with the same acceptCapture
the built-in loop now shares, and forged, undeclared or over-cap records
are dropped. A stage with capture tools on a harness without MCP is
refused before it runs.
2026-09-26 03:28:58 +10:00
sam 8274ecbc53 fix(prreview): cluster duplicate findings and read every diff shape
The duplicate merge compared each finding against the ones already kept, so
overlap was transitive only through the survivors: a chain of findings 1-2,
2-3, 3-4 collapsed to one finding or to two depending on the order they were
handed in, and the two readings tied on score. It is a clustering now -- a
canonical sort, then a union of each run of overlapping ranges -- so the
surviving set is a property of the findings and not of the permutation they
arrived in, and a cluster's member is chosen by score and then by the
finding itself rather than by arrival order.

Two things the merge got wrong besides order. The PRD keys duplicates on
(file, overlapping lines, category), not on severity, so Finding carries a
Category and the merge reads it, while the severity now only decides which
duplicate speaks for the cluster. And a cluster is blocking when any member
is, so an advisory duplicate can no longer swallow the merge gate's verdict
and turn REQUEST_CHANGES into COMMENT.

diff.go read only the shape git writes. A plain unified diff -- sections
opened by a --- / +++ header pair with no "diff --git" line -- belonged to no
file and contributed no added lines, a silent narrowing of the diff-rules
gate's input; a file section opens from either now. git's C-quoted paths are
decoded from the diff --git line, the --- / +++ headers and the rename pair,
octal escapes to bytes, because a quoted path is not a path the snapshot has.
FileStatus is derived from every statement the section makes -- new file
mode, deleted file mode, old mode / new mode, rename from / rename to, and
the /dev/null side -- so a binary or empty file, whose patch has no headers
and no hunks, is reported as what it was rather than as a modification, and a
change of object type is the typechange the change capture already persists.
2026-09-26 03:24:40 +10:00
sam 2657b18be7 fix(prreview): order the confidence floor before dedup and merge overlapping findings
Score recorded a finding's duplicate identity before dropping it under its
severity's confidence floor, so a below-floor finding shadowed a later
above-floor duplicate of the same defect. The floor now runs first, and the
merge keeps the higher-scoring of two duplicates, so the result depends on
which findings were given and not on the order they were given in.

The duplicate rule was byte-identical line ranges. The PRD's rule is
overlapping lines: two same-file, same-severity findings whose ranges share a
line are now one finding.

FileStatus said "removed" for a deleted file, a second vocabulary for the
status the repository persists as "deleted". The value says "deleted" now.
2026-09-26 03:24:40 +10:00
sam 8c7ee60270 style(prreview): adopt go fix rewrites in diff stats and snapshot 2026-09-26 03:24:40 +10:00
sam 54ade9713a feat(prreview): deterministic core of the PR review pipeline
Every phase of docs/prds/pr-review-agent.md that can be computed is computed
here, in a package that imports the standard library only: diff parsing with
renames, deletions, multi-hunk files and no-newline markers; directory
clustering; per-language blast radius; evidence packages; scoring,
deduplication, line mapping to diff coordinates and the review event.

The review event is REQUEST_CHANGES when a finding is blocking and COMMENT
otherwise; there is no approving value, because archie does not own the merge
decision.

internal/domain/workflow/prreview is now the one diff parser in this
repository: the diff-rules step's addedDiffLines delegates to it and the
private hunk-header and path helpers it used to carry are deleted, so a
repository rule and a review comment cannot disagree about which line a change
introduced. diff_rules_test.go is unchanged.

Blast radius resolves Go imports through the module path in go.mod, Python
module names, and JavaScript/TypeScript relative specifiers, all against files
inside the snapshot; an import that resolves to nothing there contributes no
edge. Evidence extraction reads through an fs.FS rooted at the snapshot, so
both are tested against fstest.MapFS fixtures.

NOTICE records the derivation from PR-AF (Apache-2.0).
2026-09-26 03:24:40 +10:00
sam e307efe77d feat(container): end the install phase between install and startup hooks
StartKit calls InstallDone after the install hooks, before files and
startup hooks, so the caller moves the egress session to its runtime
policy exactly where the Kit spec ends the install phase.
2026-09-26 03:17:49 +10:00
sam 6143d17caf feat(container): start a Kit container with the worker and harness separated by user
StartKit creates the Kit container with archie's worker as its root
entrypoint and credentials, the Kit's volumes keyed by execution, then
runs install hooks as their users, writes the Kit's files as the harness
user, and runs startup hooks. A failing hook removes the container and
reports the hook's output. The Docker test proves on a real container
that the harness user cannot read the worker's environment, and fails if
the worker shares the harness uid.
2026-09-26 03:17:06 +10:00
sam b54aa00a24 feat(kit): assemble a Kit container's launch from its plan and image
Assemble turns an admitted Kit composition and the workload image's
config into the harness spec (the image's user, never root; the image
env plus the workspace, egress and credential sentinels; the launch
argv and agent-sessions verbs), lifecycle hooks with their declared users
and restricted environments (the image-derived baseline, egress settings,
and only the runtime variables each hook declares), the Kit's files, and
volume names stable per execution.
2026-09-26 03:14:55 +10:00
sam 08d5df9b11 feat(egress): relay forwards the proxy, NATS and the State Store
A Kit task's worker shares the sandbox network with its harness, so it
reaches NATS and the State Store through the relay like the harness
reaches the proxy. archie-agent relay takes repeated -forward
listen=target pairs, binds them all before serving so a port conflict
fails at start, and stops every forward when one fails. RelayArgs builds
the command from the fixed relay ports.
2026-09-26 03:10:11 +10:00
sam 5b6572bcea feat(agentexec): run harness invocations as the Kit's user with no inherited environment
A Kit task runs worker and harness in one container, separated by user:
the worker keeps its credentials as root, and every harness invocation
runs as the Kit's user with only its declared environment. A nil env
would inherit the worker's, so the runner always passes an explicit one;
root is refused as a harness user, and a root worker refuses to start a
harness with no user. The PRD's container layout now says one container
per run, with the relay forwarding the proxy, NATS and the State Store.
2026-09-26 03:08:34 +10:00
sam 606e87d11c docs(skills): lane gates miss the tools module and contract schema 2026-09-26 02:57:14 +10:00
sam 0b24dc8ff0 fix(build): carry the harness runner into the tools module and contract schema
The harness runner made internal/agentexec import go-git, which the tools
module reaches through docsgen, so tools/go.sum needed its entries; tidy
also dropped the stale modernc sqlite requirements. Request gained the
Harness field, so contracts.json is regenerated with the HarnessSpec
schema.
2026-09-26 02:56:56 +10:00
sam e7611903a8 feat(agentexec): harness runner driving a Kit's agent headlessly
A stage whose request carries a HarnessSpec runs the Kit's CLI as a
subprocess in its own process group, with the mission and archie's rules
as the prompt. After every invocation the runner compares HEAD, every ref
and the git configuration, and the worktree against a pre-run baseline:
any ref or config change, a protected-path edit, or a write in a
read-only stage parks the step whatever the CLI claimed. The runner runs
the gate itself and resumes the same session with the gate's output, up
to the gate's failure cap. The wall clock and cancellation kill the whole
process group, so the CLI's children cannot outlive the step.
2026-09-26 02:54:03 +10:00
sam 19e110e68c style(egress): adopt go fix's promoted-field literal 2026-09-26 02:47:15 +10:00
sam f747ff87d0 feat(egress): inject Kit API-key credentials at the proxy
A session carries its run and its Kit's credential@1 requests. The proxy
applies apiKey inject rules only in the credential's phase and only to
hosts its rule names, after the network policy has admitted the request,
so a key never reaches a host its Kit did not declare. The real value
comes from a Resolver that returns only secrets the run credential
carries: a required credential that is unbound or unresolvable stops the
request before anything is sent, and an optional one passes only when it
is genuinely unbound. Named keys appear in the sandbox as a sentinel;
inject-only keys have no presence.
2026-09-26 02:46:40 +10:00
sam 486d5574b3 docs(prds): fit harnesses, steps and the store inside the org boundary and profile model
A harness is an agent profile whose environment is a Kit composition, so
image profiles and existing workflows are unchanged and only Kit runs take
the egress path; the relay replaces the claim that containers reach the
proxy directly. Credentials, step records, store installs and reviews are
org-scoped under the run credential and the Authorizer, and workflow calls
are linked across executions rather than nested.
2026-09-26 02:41:02 +10:00
sam 71435c2bb6 style(egress): adopt go fix's WaitGroup.Go 2026-09-26 02:38:59 +10:00
sam 9b16c0fd64 feat(egress): sandbox networks that reach only the relay
Each sandbox gets an internal bridge on which the host holds no address,
so host services listening on every interface are unreachable; the relay
is attached under a fixed alias and is the one way out. ProxyEnv gives a
sandbox container its proxy URL and CA trust. The Docker integration test
proves allowed egress works and that the proxy listener, host services and
the internet are unreachable directly; it fails if the host-address
inhibition is removed.
2026-09-26 02:38:12 +10:00
sam 4fc06b5d7d feat(egress): relay forwarding a sandbox network to the egress proxy
archie-agent relay listens on the sandbox's isolated network and joins
every connection to one fixed target, the proxy. The relay holds no
secrets and can reach nothing else, so the host needs no address on a
sandbox network at all.
2026-09-26 02:33:41 +10:00
sam 78dd50d60b feat(egress): session-authenticated proxy terminating TLS under the Kit network policy
CONNECT tunnels and absolute-form http requests authenticate to a
per-container session, are checked against the session's phase policy,
and are forwarded with verified upstream TLS. A tunnel serves only its
admitted host: mismatched SNI and Host headers are refused. Upstream dials
refuse loopback, and refuse internal addresses unless the policy names the
exact IP, so an allowed name cannot resolve back into the host.
2026-09-26 02:31:00 +10:00
sam 77a479e99a feat(egress): persistent per-daemon CA issuing cached leaf certificates 2026-09-26 02:27:58 +10:00
sam 6bc7a85404 feat(egress): network-policy@1 matcher 2026-09-26 02:27:25 +10:00
sam a7edc0a5cd feat(kit): admit Kit v3 descriptors against archie's capability support
Decodes published descriptors from the manifest annotation, composes one
workload with its mixins through the Kit spec package, and applies the
runtime's support table: unsupported required capabilities refuse the
launch, optional ones are skipped and recorded, and forge or passthrough
credentials are refused. A composition must carry a headless prompt verb.
2026-09-26 02:23:11 +10:00
sam 1cf2742f54 docs(prds): approve PR review agent and store PRDs 2026-09-26 02:08:13 +10:00
sam 0f6cb5b8a6 docs(prds): store 2026-09-26 02:06:50 +10:00
sam fca30d6445 docs(prds): PR review agent 2026-09-26 02:05:52 +10:00
sam a98ca2c8e9 docs(prds): approve execution-tree and external-harness PRDs 2026-09-26 01:58:29 +10:00
sam 22d36fef75 docs(prds): harnesses run as Kit v3 images behind a credential-injecting egress proxy 2026-09-26 01:54:35 +10:00
sam f74827795d docs(prds): fold review findings into execution-tree and harness PRDs 2026-09-26 01:45:10 +10:00
sam ca8d189f96 docs(prds): agents reach a harness only through a workflow stage 2026-09-26 01:41:12 +10:00
sam 2ee7043daf docs(prds): external agent harnesses 2026-09-26 01:38:14 +10:00
sam bbc39897de docs(prds): execution tree and enforced state machine 2026-09-26 01:34:26 +10:00
sam 6ba43bbf21 Merge pull request #996 from samcharles93/feat/ui-graphite-theme
Feat/UI graphite theme
2026-09-26 01:26:04 +10:00
sam ff77612bfd fix(archied): the State Store seeds provider-settings from the operator's secret reference
configuredSecretRegistry resolved provider keys in place, and the State Store's
copy of the config shared the providers map with b.cfg, so ImportConfig seeded
the process-local ARCHIE_PROVIDER_<hash> env name. Provider resolution now
runs only in the daemon and gateway boot (openStores).
2026-09-25 22:37:27 +10:00
sam 4426c0e685 fix(webui): roles edit in place; embedding picks an embedding-capable provider
A role has one value, so its row is the control instead of an accordion
that reveals the same text. Embedding pairs a provider select, limited to
configured providers whose class the embed package implements (openai,
openai-compatible, gemini, ollama, cohere, mistral), with a model name; the
chat model list never held embedding models.
2026-09-25 20:13:04 +10:00
sam 9627bc411c feat(webui): Models picks from the provider catalog, and enables available providers
archied already finds usable providers (key set in the environment, or
configured) through the model catalog; the published config view now
carries that catalog, providers with their model ids. Settings > Models
offers role models only from configured providers, lists the catalog's
unconfigured providers as available, and adding one carries its class, key
variable and endpoint. Roles and providers are two accordions, each ending
in an add row.
2026-09-25 18:04:46 +10:00
sam 01c98088ae fix(webui): Models page reads as settings, not raw documents
The four roles the daemon reads always show and cannot be deleted;
clearing one unsets it, and custom workflow roles can still be added.
Provider class is a select of the SDK's classes, the provider name is a
heading rather than an input, and a key read from the environment shows
as one line with Set reference instead of an 'unset / unset' reference.
2026-09-25 17:54:18 +10:00
sam 86d4f62bfe fix(webui): drop the static 'Applies after restart' pill from settings headers
It read as an alert that something had changed. Restart needs show where
they apply: in the review drawer for the changes being saved, and in the
Restart pending banner once a saved change is waiting on a restart.
2026-09-25 17:51:54 +10:00
sam 6f2b55960f fix(webui): the live stream reopens after a fatal close; quieter connection status
A non-200 answer to /api/stream (the backend restarting behind a proxy)
closes an EventSource for good, so the top bar read Disconnected until a
reload while every fetch worked. The live-updates store now reopens it
after 1s, doubling to a 30s cap, and resets once live. The connection
status becomes a dot and a label, coloured only when not connected.

History drops the edge fade, which washed out its first and last columns
though nothing overflowed, and its section filter names the section
rather than showing the raw kind.
2026-09-25 17:45:34 +10:00
sam dce3c925c2 fix(webui): cut help text to the facts a label cannot carry
Drops every page subtitle and the hints that restated their label; the
rest become a few words ('Empty: truncate.', '0 = no limit.'). Empty states
and notes shrink the same way.
2026-09-25 17:42:29 +10:00
sam f7074d357f fix(webui): shorter event types empty state 2026-09-25 17:40:11 +10:00
sam 41e5ab32f9 fix(webui): one plain sentence for the empty event types list 2026-09-25 17:39:21 +10:00
sam e44b5398c7 fix(webui): drop the Events description and the captures redaction note 2026-09-25 17:38:02 +10:00
sam 6dcb04c7c0 fix(webui): Events reads as a flow
A Capture → Map → Bind strip with each step's count opens its tab. The
tabs follow that order, sit left-aligned at their own width and carry
count chips; a count that could not be read stays blank. The Inspector
splits into list and detail only when there is a capture to show, and an
empty event-types list explains where proposals come from.
2026-09-25 17:36:05 +10:00
sam d025d4c5be feat(webui): Events header states capture status; copyable capture endpoint
The page says what it is for and whether capture intake is listening,
once that is known, instead of the Inspector repeating the global stream
state. An empty capture list offers the webhook address with a Copy
button.
2026-09-25 16:37:05 +10:00
sam 7555b80f31 feat(webui): New task dialog with workflow cards, recent repositories and run-as identity
Repository with recent ones one click away, the workflow as a radiogroup
of cards showing runs and merge rate, title and instructions, and the
identity (the server requires one) defaulted to the first active actor
under an Advanced disclosure that names it. Cmd/Ctrl+Enter starts the
task and opens it. Replaces the Start work form. Workflows shows an empty
state rather than an editable template when there is none.
2026-09-25 16:34:38 +10:00
sam ceed8b055a feat(webui): Workflows as a list with stats and a tabbed editor
The list shows each stored workflow with its runs, merged-of-runs bar and
average tokens. The editor has Definition (ID and YAML, Validate & save,
Remove, Restore this workflow), Performance (slowest stages and failures
for the selected workflow only) and Runs (its tasks, linking to each).
Restore shipped and New workflow sit in the header. The Start work card
leaves the page: New task in the top bar starts work.
2026-09-25 16:31:42 +10:00
sam f3f3ca90f1 feat(webui): task detail with a parked banner and a right rail
Header: breadcrumb, title, status pill, workflow and forge links, with
Start a new run as the page's one action; a parked task opens with its
park reason in an amber banner. The log/changes/configuration/debug tabs
take the main column; a right rail lists every attempt with its outcome
(replacing the pager inside the stage rail), the selected attempt's
stages, and the task's details.
2026-09-25 16:28:38 +10:00
sam 0bc27ea6da feat(webui): needs-you first Dashboard
The header states what is running and what needs a human instead of a
greeting. A stat strip replaces the throughput tiles. The main column
opens on a Needs you queue: each waiting task with its status, title,
repository, workflow and park reason, an Open link and the actions the
server offers for it. Live activity follows; quality gates and the token
outlook move to a right rail.

A failed task-list fetch no longer reads as an empty list, which would
have told the operator nothing needs them; the header says it cannot
reach archied instead.
2026-09-25 16:25:19 +10:00
sam 049bbf2a7d feat(webui): Plugins and Container runtime settings pages; Advanced keeps only dangerous actions
Plugins: the four extension directories. Container runtime: image, pull
policy (missing or always, the two the daemon accepts), concurrency,
uptime and volume retention as durations, network, and named profiles
with their image and tool allowlist. Advanced now holds only stop and
rollback, and the Managed elsewhere card goes. With every settings kind on
its own page, the generic schema-driven resource editor had no consumer
and is deleted.
2026-09-25 15:32:20 +10:00
sam b5c98a0ccc fix(webui): the legacy config catalog stops advertising fields the control plane owns
skills_dir, plugin_dir, secret_engine_dir and containers.* were listed as
editable in /api/config's schema while the plugin-settings and
container-runtime-policies resources own those values at runtime; nothing
could save them there. Drop them from the catalog, and delete the settings
components that rendered the catalog, none of which any page used.
2026-09-25 15:29:31 +10:00
sam c327f17c35 feat(webui): Identities on the shared components
Replaces raw inputs, buttons and scoped CSS with the shared controls:
lifecycle as status pills, inline rename instead of a browser prompt, and
Retire behind a confirmation dialog.
2026-09-25 15:25:33 +10:00
sam 081e5bbfd9 feat(webui): Task execution, Models and Repositories on setting rows
Task execution: the two time limits as durations over their seconds
fields, steppers for tool steps and gate failures. Models: roles checked
as provider/model and warned when the provider is missing, providers as
cards with class, base URL and key. Repositories: one card per repository
with gate and preflight commands edited as argv tags (duplicates and
commas kept), protected paths, retries and the review, storage and
concurrency switches.

Secret references no longer claim a credential resolved or went missing:
the documents only say a reference is filled in, and an omitted boolean
prop was being read as not found.
2026-09-25 15:23:41 +10:00
sam b1a5954594 feat(webui): Personas and Schedules settings pages
Personas: a filterable list with the default marked, and an editor with
name, a default toggle, the system prompt with a character and token
count, Duplicate and Delete. Renaming or deleting the default keeps the
collection naming one that exists; the last persona cannot be deleted.

Schedules: an empty state, then one card per job with ID, task title,
instructions, when (interval, cron line or a single time) and overlap.
Settings opens on Personas.
2026-09-25 15:14:18 +10:00
sam 9639e7041e feat(webui): Settings > History, and a resizable Settings sidebar
History replaces the Audit card on every settings page: one change log for
all settings, filterable by section, actor and time window, with the
filters in the query so each page's History link opens it filtered to that
page. Rows show the old and new value as a diff and expand to the full
value; Restore still puts a resource back to the version before a change.

The sidebar's edge drags (or takes arrow keys) between 180 and 420px,
resets on double-click and remembers its width per browser.
2026-09-25 15:10:07 +10:00
sam 5b06f0b42a fix(build): task dev starts the State Store and waits for it
Task templates every command, so the PostgreSQL health check's
'{{.State.Health.Status}}' rendered as an empty format string: dev:postgres
always reported unhealthy after 60s, the State Store never started, and the
Gateway and daemon exited on boot or retried against a store that was never
coming. Escape the template, and have dev:daemon and dev:gateway wait for
the State Store's port before starting.
2026-09-25 15:10:00 +10:00
sam 7d37750d40 feat(webui): Channels settings page
One card per channel: set-up channels expand to their fields, the rest
collapse to a row with Set up. Running state shows only when the
messaging service reports it. Telegram token and webhook signing secret
are secret references (an unset signing secret reads as risky); allowed
Telegram users and chat models are tag inputs. Chat session defaults
carry the red unrestricted-filesystem row, max steps with its real zero
meaning (the default of 100), and the rate limit as requests per
duration. Drops the ChannelCard status grid.
2026-09-25 15:10:00 +10:00
sam 7095a583b8 feat(webui): Tools & MCP settings page
MCP servers as editable rows per transport (stdio command and arguments,
HTTP URL, SSE endpoints) with parallel tool calls; MiniMax with its key as
a secret reference; web fetch with byte, duration and a danger-toned
private-networks toggle, its fields disabled while it is off; tool output
limits with a token estimate.

Fixes sticky positioning across the app: the frame and main used
overflow hidden, which made each a scroll container that never scrolls,
so the Settings save bar and sidebar never stuck. Both now clip instead.
2026-09-25 15:09:53 +10:00
sam cb6b902f97 feat(webui): Scheduling policy settings page
Its own page under Settings > Agents instead of a generic card on Advanced:
trigger as a segmented control with the label field shown and required
only when the trigger needs one, the six forge state labels as a fixed
table, a max-retries stepper and a duration input for the poll interval.
Settings pages leave room below the last setting so it can be scrolled up
to eye level.
2026-09-25 15:09:45 +10:00
sam 74aaf39be9 feat(webui): one save flow for Settings
Edits live in the control-plane store as drafts against the version they
started from, so they survive moving between Settings pages. A sticky bar
counts unsaved changes; the review drawer shows a field-level diff per
section with Revert, and saves the sections one at a time, stopping at the
first failure. A conflicting save rebases the draft onto the latest value.
Restart pending is read from apply status. Per-card Save buttons, Live and
Version badges go; leaving Settings with edits asks first.
2026-09-25 15:09:38 +10:00
sam 4690e822d8 fix(webui): overflowing nav rows fade at the edges instead of showing a scrollbar
The top bar and the narrow Settings tabs use shadcn-vue's scroll-fade-x,
which fades each edge in as there is more to scroll to. The Settings
sidebar marks the current page with the raised background alone.
2026-09-25 15:09:31 +10:00
sam 90e222b8ec feat(webui): Settings sidebar shell
Settings is one top-bar link. Its pages render inside a shell with a
grouped sidebar (Agents, Integrations, Runtime) that turns into tabs at
narrow widths, and content capped at 960px. Channels sits under
Integrations.
2026-09-25 15:09:24 +10:00
sam 1bb52fe8c7 feat(webui): five-place top bar with Settings, New task and one connection pill
Dashboard, Tasks, Workflows, Events and Settings replace the Work, Agent
and System menus. Configuration pages move under /settings/* with
redirects from their old paths; Logs and Appearance leave the bar and stay
reachable from Jump to, the Dashboard and the account menu. New task opens
the Start work form in a dialog and lands on the new task. One pill reports
the live stream's state.

Drops docs/prds/dashboard-navigation-groups.md: web UI design is not
tracked in PRDs.
2026-09-25 15:09:18 +10:00
sam e3bf3b7584 feat(webui): add stock and registry primitives for the redesign
Stock shadcn-vue: number-field, tags-input, radio-group, breadcrumb, kbd.
From archie-component-registry: duration-input, byte-size-input,
segmented-control, secret-reference, setting-row, stat-strip, status-pill.
2026-09-25 15:08:59 +10:00
sam 6d8fe247a7 feat(webui): swap the violet palette for the Graphite theme
Neutral warm greys with one swappable sage accent replace the violet canvas,
washes and brand gradient. IBM Plex Sans/Mono replace Geist. The light theme
keeps the same rules with a darker sage. No layout changes.
2026-09-25 15:08:59 +10:00
sam 464ccf83fa Merge pull request #995 from samcharles93/fix/webui-single-stream
fix(webui): multiplex dashboard live updates over one stream
2026-09-25 14:14:58 +10:00
sam 067d365f84 fix(webui): multiplex dashboard live updates over one stream 2026-09-25 14:05:34 +10:00
sam e12aeb8493 fix(build): stamp every service binary with the installer's version flags 2026-09-25 11:10:32 +10:00
sam 7577ae66a7 docs(design): add UI redesign handoff bundle
Add a self-contained design handoff under docs/design/ui-redesign/ (README,
build prompt, HTML mockups, design-canvas sources, CSS and JSON theme
tokens). docs/design/ is held back from the published docs sets like
docs/inspiration/: it is input to building the UI, not a page to read.

Remove the superseded service-decomposition research from docs/inspiration/.
2026-09-25 11:10:32 +10:00
sam 8fea8e8686 feat(controlplane): field-level sys_audit table, audit view on settings pages, whole-task time limit 2026-09-25 09:54:30 +10:00
sam 49d7527f1c fix(webui): open control-plane watch streams before the first change 2026-09-25 09:37:36 +10:00
sam 81862273c0 fix(taskactions): abandon leaves the forge issue open 2026-09-25 08:59:54 +10:00
sam 07d5a7a3cc fix(webui): keep the stage selection across inspector tabs 2026-09-25 08:52:40 +10:00
sam bb3e7b76e8 fix(webui): render sub-second durations as under 1 s 2026-09-25 08:49:52 +10:00
sam cc33dfea54 fix(webui): show park reason, one attempt control in the rail, tighter stage selection 2026-09-25 08:45:31 +10:00
sam 73e718dea4 fix(webui): use Tailwind's standard breakpoints everywhere 2026-09-25 08:37:47 +10:00
sam d01a3c4647 fix(daemon): park a task whose agent container exits before replying 2026-09-25 08:31:46 +10:00
sam 55ad93e8e3 fix(webui): drop ok badge from stage rail, pack run tabs, scope note on changed files 2026-09-25 08:26:04 +10:00
sam 459bbcd5fc docs(prds): reflow playbook-expression-syntax
deploy / gate (push) Failing after 5m32s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
2026-09-25 02:00:16 +10:00
sam a4d98786a1 chore(release): v1.41.2
deploy / gate (push) Failing after 3m35s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
2026-09-25 01:58:54 +10:00
sam aa24551d98 fix(update): treat the runtime as the release version; stamp it in dist-zip
The update check still read the retired archie/v* tag stream, so a host on
1.41.1 was offered runtime 1.35.0, and the installer built the agent image
from that stale tag. Both now use the release's archied/v* tag. The dist-zip
build also stamps runtimeVersion, so /version stops reporting 'dev'.
2026-09-25 01:58:20 +10:00
sam cacf25039e test: remove events-page source-string test
deploy / gate (push) Failing after 3m49s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
It asserted on text in the router, nav and Events page sources rather than
on behaviour.
2026-09-25 01:35:26 +10:00
sam 35dd7489dd test: remove layout-pinned route-registry and task-meta fixture tests
TestDashboardPagesRegistryCoversEveryRoute parsed ui/src/router/index.ts as
text, and TestTaskMetaPayloadMatchesFixture plus ui/test/task-meta-snapshot
pinned a formatted JSON fixture. They failed on formatting, not behaviour.
2026-09-25 01:32:20 +10:00
sam be1b3aa6a1 chore(release): v1.41.1
deploy / gate (push) Failing after 5m34s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
2026-09-25 01:29:59 +10:00
sam 065606b2a5 fix(ci): make the gate tolerate formatting and give deploy a PG 18 client
The page-registry test parsed the route table one line per route and the
task-meta fixture was byte-compared, so the prettier reformat broke both.
The registry test now splits route objects and ignores comments; the
fixture compares compacted JSON. Also drops a stale router comment that
described the removed redirects, rebuilds ui/dist, regenerates the
contracts artifact, keeps prettier off generated output, and installs
postgresql-client-18 in deploy.yml's gate as quality.yml already does.
2026-09-25 01:29:23 +10:00
sam a22030bd65 chore(release): v1.41.0
deploy / gate (push) Failing after 3m29s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
2026-09-25 01:12:45 +10:00
sam a16a17309c Merge pull request #994 from samcharles93/chore/remove-legacy
chore: remove legacy config, compat shims and the SQLite import
2026-09-25 01:11:26 +10:00
sam 0d35e753b5 refactor: format markdown files using prettier, fix spelling concerns, reduce Taskfile bloat 2026-09-25 01:10:28 +10:00
sam c1cd5c8f5b chore(state-store): remove the one-time SQLite import and db_path
Every install serves from Postgres, so the legacyread/legacyimport packages,
the archie-state-store import command, the boot gate that refused to serve
over unimported SQLite files, and db_path (which only located those files)
go. Migration 0010 drops the import_completion table.
2026-09-25 00:40:48 +10:00
sam 4479f212d7 chore(webui): remove legacy hash and Events-tab redirects
The #/path rewrite and the /captures, /mappings and /bindings redirects only
kept pre-cutover bookmarks working.
2026-09-25 00:36:43 +10:00
sam 1340036546 docs(site): publish the event automation product overview 2026-09-25 00:34:57 +10:00
sam 9fd966d6b0 docs(readme): explain event automation and organization model 2026-09-25 00:23:16 +10:00
sam 6e46d4dec9 docs(readme): introduce project overview and setup guide 2026-09-25 00:06:21 +10:00
sam f36e17796c chore(staterpc): remove deprecated unary capture RPCs and Binding.secret
ListCaptures and ListUndispatchedCaptures had no callers once the client
moved to the streaming RPCs; they were kept only for mixed-version rollouts.
Binding.secret was unused since signing moved to Source; its number and
name are reserved.
2026-09-25 00:00:16 +10:00
sam e5105280ad chore(config): remove token_env aliases for forge, artifacts and telegram
Each credential is now only a {engine, key} secret reference. A stale
token_env in a file is reported at startup as an unrecognised key.
nats.token_env stays (no secret-ref form), and providers.api_key_env stays:
it is the carrier the resolver writes each resolved key's env name into.
2026-09-24 23:58:26 +10:00
sam 9a0efa295e chore(config): remove dead [agent], [oidc], [image] and containers.enabled keys
None had a production consumer: [agent] and containers.enabled were decoded
only so old files kept loading, [oidc] was never read (archie-ui takes OIDC
from flags), and [image] was validated but no provider exists.
2026-09-24 23:52:06 +10:00
sam 862b3560e1 Merge pull request #993 from samcharles93/pg/foundation
Postgres persistence and event automation
2026-09-24 23:30:45 +10:00
sam 58eac052a8 fix: add pg to path for CI quality check 2026-09-24 23:16:25 +10:00
sam 0909ebfe60 ```
chore(deps): bump Go module dependencies in go.sum
```
2026-09-24 22:42:07 +10:00
sam ae5e0ad835 fix(ci): install PostgreSQL 18 client tools 2026-09-24 22:40:54 +10:00
sam b9c1663d64 test: check scanner error in openSSEStream 2026-09-24 22:27:56 +10:00
sam 25668c1226 chore: update deps and remediate GO-2026-6253 2026-09-24 22:27:08 +10:00
sam d299448de1 Merge branch 'main' into pg/foundation 2026-09-24 22:21:24 +10:00
sam 440d2e8e46 fix: reject values that exceed Int32 for all SQL LIMIT params 2026-09-24 21:45:27 +10:00
sam c971348a86 docs(development): organise the guides by area
One page per area: frontend UI, agent, workflows, daemon (task lifecycle and
event automation together), State Store, control plane and settings, and
processes and wiring, with merging work kept separate.
2026-09-24 21:05:29 +10:00
sam 21e4d47907 docs(development): checklists for every kind of change
docs/development/ holds one page per kind of change (settings, State Store
and persistence, task lifecycle, workflows and steps, event automation,
dashboard, agent execution and containers, processes and wiring, merging
work), each naming every layer the change must reach and pointing at the
document that owns the design. The docs build puts them in the development
set; docs/index.md and CLAUDE.md link them.

Also adds the container-profile case to the validator agreement test, the
check the profiles work skipped.
2026-09-24 21:03:34 +10:00
sam 21f333a13e fix(controlplane): stored container policies replace file profiles; add profile image and workflow examples
A stored container-runtime-policies document that carries Profiles now
replaces the file's profiles instead of merging into them, so a profile
deleted in the dashboard stays deleted; one stored before profiles existed
still inherits the file's. Profiles drop their json tags so the stored
document keys them like its other fields.

Adds examples/profiles/Dockerfile.agent-net (agent image plus network
lookup tools) with a build-only agent-net compose service,
examples/workflows/firewall-investigate.yaml with a test that parses every
example against the registered step vocabulary, and names the postgres
service in the compose header.
2026-09-24 20:58:08 +10:00
sam d8bec1ae06 fix(eda): clear completed tasks; document the tool allowlist's reach and unchecked profile names
ClearTerminalTasks now deletes completed tasks, with a test that holds its
SQL list to taskstate.Terminal. The AllowTools comment says agentloop's
built-in file tools are outside the allowlist and why. The PRD model
diagram lists only what a profile holds (image, tools), and the profile
field and AgentProfile say a workflow's profile name is resolved at
dispatch, not when the workflow is saved.
2026-09-24 20:53:51 +10:00
sam d320a1a01a feat(eda): workflow inputs, optional repository and agent profiles
Workflow definitions declare inputs, repository (none, optional or
required; default required) and profile. A binding assigns each input
from a mapped parameter or a constant and may take its repository from a
parameter, which must name a configured repo; both are checked when the
binding is saved and again at dispatch. Inputs travel as structured task
data (tasks.inputs, the task brief, and a JSON block in the agent's
mission), never as body text.

A task with no repository runs in a per-task scratch workspace with no
clone and no publication grant. The agent.run step runs one mission
without a repository and finishes the task in the new completed status.

Agent profiles live under [containers.profiles.<name>]: an image and an
allowlist over the tools archie adds (MCP, scripts, plugins).
[containers].image is the default profile; an unconfigured profile parks
the task. The workflow is now pinned before the container starts so the
profile can choose its image.

Also stop two archied tests writing embedded NATS state into the package
directory, refuse an empty state_dir for embedded NATS, and drop the NATS
store files an earlier lane commit tracked.
2026-09-24 20:29:33 +10:00
sam 74197cd0fc Merge branch 'worktree-agent-a96503bc8828fc104' into pg/foundation 2026-09-24 19:47:03 +10:00
sam be9a45ad2d Merge branch 'pg/foundation' into worktree-agent-a96503bc8828fc104
# Conflicts:
#	docs/data/generated/dev-docs.json
#	internal/app/archied/state_store_test.go
#	internal/app/archied/state_store_toolcalls_test.go
#	internal/contracts/state/v1/state.pb.go
#	internal/daemon/dispatch_bindings_test.go
#	internal/infrastructure/bindingcipher/cipher_test.go
#	internal/infrastructure/captureintake/receiver_test.go
#	internal/infrastructure/edastore/contracts_binding.go
#	internal/infrastructure/edastore/testsupport_test.go
#	internal/infrastructure/postgres/edastore.go
#	internal/infrastructure/postgres/edastore_test.go
#	internal/infrastructure/staterpc/error_test.go
#	internal/store/store.go
#	internal/webui/api_binding_test.go
2026-09-24 19:47:00 +10:00
sam e57221f34b docs(store): drop residual SQLite references; fix lane lint findings 2026-09-24 19:39:06 +10:00
sam a377da6678 Merge branch 'worktree-agent-a62864fcfbdb43f5a' into pg/foundation 2026-09-24 19:34:44 +10:00
sam 30834223dc Merge remote-tracking branch 'origin/pg/foundation' into worktree-agent-a62864fcfbdb43f5a
# Conflicts:
#	internal/app/archied/state_store.go
#	internal/contracts/state/v1/state.pb.go
#	internal/daemon/daemon.go
#	internal/infrastructure/captureintake/receiver.go
#	internal/infrastructure/captureintake/receiver_test.go
#	internal/infrastructure/legacyimport/load.go
#	internal/infrastructure/postgres/edastore_test.go
#	internal/infrastructure/postgres/postgresdb/edastore.sql.go
#	internal/infrastructure/postgres/queries/edastore.sql
#	internal/infrastructure/staterpc/client.go
#	internal/infrastructure/staterpc/values.go
#	internal/webui/api_binding.go
#	internal/webui/api_binding_test.go
#	ui/dist/assets/index.js
#	ui/src/bindings/BindingEditor.vue
#	ui/src/bindings/BindingRow.vue
2026-09-24 19:34:31 +10:00
sam 9864766804 docs: describe the PostgreSQL-only stores, state_dir and the import-only db_path
Architecture, deployment, installer, skill and PRD text now name the Postgres
State Store, the offline recovery commands on database_url, state_dir for host
state, and db_path as the legacy-file locator for archie-state-store import.
Finalised PRDs, CHANGELOG, docs/news and docs/archive are unchanged records.
2026-09-24 14:51:48 +10:00
sam 64f863f228 docs(proto): name the Postgres State Store in the state contract comments 2026-09-24 14:47:53 +10:00
sam 89f5b70287 feat(config): add state_dir for the daemon's host state
The embedded NATS store and endpoint file, the task-log registry and the
readiness disk probe resolve from state_dir (default: the data home's archie
directory) instead of the directory of db_path. db_path now only locates the
legacy SQLite files for the one-time import and its boot gate.
2026-09-24 14:47:21 +10:00
sam 4f8290567b docs(bindings): bindings apply per event type with a filter; mappings count matches 2026-09-24 14:46:44 +10:00
sam fbcb7032e5 feat(webui): bindings pick an event type and filter, mappings show their type and match count 2026-09-24 14:46:21 +10:00
sam ae552db7e0 refactor(store)!: remove the SQLite task store, the PocketBase event store and the SQLite session store
The State Store, event capture and Gateway conversations already serve from
PostgreSQL. This deletes internal/store and internal/infrastructure/edastore,
the SQLite gateway session store and openProductionTaskStore, and the -db
recovery path on a legacy task file; backup, restore, validate and rollback
work on the database database_url names.

- The binding-secret cipher moves to internal/infrastructure/bindingcipher and
  ToolCall to internal/infrastructure/postgres.
- NewSessionStoreMemory is now a pure in-memory store that passes the shared
  SessionStore conformance suite.
- Tests run against PostgreSQL through internal/infrastructure/postgres/pgstore;
  legacyimport/legacyfixture writes the legacy files the import and the boot
  gate read.
- The cron dialect is owned in internal/domain/scheduling, so
  github.com/pocketbase/pocketbase and pocketbase/dbx leave go.mod.
  modernc.org/sqlite stays for the one-time import (legacyread).
- The UI and Messaging architecture gates ban the Postgres and legacy readers
  in place of internal/store.
2026-09-24 14:43:50 +10:00
sam dda12dcdba refactor(scripts): drop the SQLite task-database backup from the installer and watchdog
The pre-update PostgreSQL snapshot is the only backup; the watchdog restores
binaries and never the database.
2026-09-24 14:43:25 +10:00
sam fec0ea1f4e feat(eda): mappings per event type, match counts, several bindings per source
A mapping belongs to an event type and is checked against its inferred
schema on save. Each event a mapping resolves is counted once in
mapping_matches (migration 0008), read back as match_count and
last_matched_at. Bindings carry an optional CEL filter over the mapping's
parameters, checked on save. The per-source unique indexes are dropped:
every armed binding whose mapping matches the capture's event type and
whose filter admits it dispatches once, claimed in the per-binding ledger
before its task is enqueued. The State Store gains RecordMappingMatch and
the new mapping and binding fields.
2026-09-24 14:42:58 +10:00
sam 0cabe5fd65 merge: t2db.40 sources and signing into pg/foundation
Resolves against t2db.36: captures carry both event_type and unsigned (proto field 10), the State Store serves sources and event types from the Postgres EDA store, the capture row shows event type and signature together, and the staterpc sentinels map both ways from one table.
2026-09-24 14:38:40 +10:00
sam a383f6820f refactor(gateway): replace the SQLite session store with an in-memory store 2026-09-24 14:26:42 +10:00
sam 10023b8bc2 refactor(scheduling): own the cron dialect instead of pocketbase tools/cron 2026-09-24 14:26:41 +10:00
sam 6adbdc55a9 feat(eda): sources own signing, with UUIDv7 paths and approved unsigned option
A source is the capture endpoint: a UUIDv7 path by default or a unique
URL-safe custom path, signed by default with an Archie-generated secret
(encrypted via the bindings cipher), or unsigned after an approval.
Intake verifies X-Hub-Signature-256/X-Signature-256 against the source
secret before redaction; an unauthenticated event on a signed source is
captured but never dispatched, an event on an approved unsigned source
dispatches and is marked unsigned. The binding secret is retired; migration
0006 derives sources from existing binding and capture source strings,
moving each binding's secret onto its source. SourceStore crosses the
State Store gRPC contract. The dashboard gains a sources panel and flags
unsigned in the capture inspector, binding list and task timeline.
2026-09-24 14:26:21 +10:00
sam d8d7c5a1f2 fix(legacyimport): imported captures take the new event_type column's default 2026-09-24 14:26:18 +10:00
sam f279e3b9c0 Merge branch 'worktree-agent-a88b86b51f454341b' into worktree-giggly-marinating-lamport 2026-09-24 14:21:53 +10:00
sam 1c03c6bc1a feat(webui): inspector shows proposed and unidentified events, names and pastes event types 2026-09-24 14:21:21 +10:00
sam c1e2a14390 feat(staterpc): event type RPCs and capture event_type on the wire 2026-09-24 14:21:21 +10:00
sam 80b0d1f78d feat(eventtype): infer event types from captures and gate dispatch on identification 2026-09-24 14:21:20 +10:00
sam 00e3520a1e Merge branch 'worktree-agent-a2b33953bdffebf56' into worktree-giggly-marinating-lamport
# Conflicts:
#	docs/data/generated/dev-docs.json
#	internal/app/archied/state_store_pool.go
2026-09-24 10:06:00 +10:00
sam 368e33a9a5 feat(archied): serve the State Store, event store and Gateway conversations from Postgres
The State Store's task and event-capture stores and the conversation store
read by archied and served by archie-gateway now open on database_url.
Every serving process refuses to start when legacy SQLite data exists and no
import completion is recorded, naming archie-state-store import; a fresh
install records completion itself. The Gateway holds its Postgres serve
claim for its lifetime and releases it before the pool closes.
2026-09-24 10:01:54 +10:00
sam a86be2fa49 Merge branch 'worktree-agent-a091696d945ed3377' into worktree-giggly-marinating-lamport
# Conflicts:
#	cmd/archie-state-store/recovery.go
2026-09-24 09:56:10 +10:00
sam 5e6c3fa3d3 Merge pull request #992 from samcharles93/feat/865-dashboard-vocabulary
feat(webui): serve change statuses and the config schema through /api/task-meta
2026-09-24 09:50:19 +10:00
sam 1b5ba30113 feat(archied): recovery commands on PostgreSQL; fail-closed pre-update snapshot, no automatic schema rollback
Without -db, backup/restore/validate/rollback resolve database_url from the
config and work on the whole PostgreSQL database. Restore claims every service
role; rollback claims the State Store role; validate refuses a schema newer
than the binary. The installer refuses a daemon update it cannot snapshot
first; the watchdog never restores the database and prints the explicit
offline restore instead.
2026-09-24 09:50:10 +10:00
sam 5009288729 fix(state-store): real-process tests give the State Store a database_url 2026-09-24 09:48:58 +10:00
sam d2b55e941a Merge branch 'worktree-agent-a7131b2ebdff5f551' into worktree-giggly-marinating-lamport 2026-09-24 09:46:02 +10:00
sam 35b0a305eb feat(state-store): one-time import of the legacy SQLite stores into Postgres
archie-state-store import copies the State Store task database, the
PocketBase event store and the Gateway conversation store, all named from
db_path, into Postgres in one transaction. The bead asked for an archied
command; offline maintenance of a store belongs to the binary that owns it,
so it sits beside backup/restore/validate/rollback instead.

It refuses rather than guesses: while the state-store or gateway ownership
claim is held, when a domain it imports already holds rows (an allowlist of
that domain's tables, checked after Migrate), on a completed prior import,
on FK orphans, alias case collisions, duplicate bindings, events whose (at,
id) order microsecond storage would change, schema gaps, and any value the
target column cannot hold, naming table, row, value and rule. Historical ids
are kept and every identity sequence is set from AUTOINCREMENT's high-water
mark. After loading it compares key sets, event order, resource blobs and
binding secrets byte for byte and the next id of every sequence, checks the
source files were not written while read, and only then writes an
import_completion row (migration 0005) in the same transaction.

postgres.ImportComplete and legacyimport.HasLegacyData are the two halves
of the boot gate: legacy data without a completed import must not serve.
2026-09-24 09:45:26 +10:00
sam 651021130d feat(postgres): whole-database backup and offline restore on pg_dump/pg_restore
Restore claims every service role (state-store and gateway) non-blockingly
and refuses if any is held or the claim cannot be checked; it drops tables a
later migration added before pg_restore --clean so a restored schema matches
the snapshot. Backup validates the archive before replacing the previous one.
Ports the store's write-side clip, park-class and transition-audit coverage
from internal/store.
2026-09-24 09:32:39 +10:00
sam 0f88e08913 Merge remote-tracking branch 'origin/main' into worktree-giggly-marinating-lamport 2026-09-24 09:31:28 +10:00
sam 5687d1b04e feat(webui): serve change statuses and the config schema through /api/task-meta
Closes #865. The dashboard hand-copied the Change* file-status ids and events.ConfigCapturedSchema. /api/task-meta now serves both; the Vue dashboard renders ui/src/lib/task-meta-snapshot.ts until the served catalog lands. The Go handler is pinned to internal/webui/testdata/task_meta.json and the snapshot is pinned to that same fixture, so a one-sided rename fails a test.
2026-09-24 09:31:09 +10:00
sam 671441ac4b feat(legacyread): read-only readers and import verification for the legacy SQLite stores 2026-09-24 03:28:42 +10:00
sam 8b006b35aa fix(postgres): lock keys follow D3.7/D4.3; event reader never sees a later id before an earlier one 2026-09-24 03:23:38 +10:00
sam c367a9e606 Merge pull request #991 from samcharles93/eda/event-automation
Eda/event automation
2026-09-24 03:10:54 +10:00
sam 88030e32e9 Merge pull request #990 from samcharles93/sams-cleanup
Sams cleanup
2026-09-24 03:08:53 +10:00
sam 5cbc9f9d6c feat(postgres): event inserts take a transaction advisory lock so ids commit in order 2026-09-24 03:01:41 +10:00
sam 20929cd444 feat(postgres): State Store claims serve ownership with a session advisory lock 2026-09-24 02:57:38 +10:00
sam fe73025d47 refactor(postgres): resources and statestore tests use storecontract, not internal/store 2026-09-24 02:47:06 +10:00
sam 4ce4b46977 style(postgres,gateway): adopt task fmt rewrites from the lane merge 2026-09-24 02:41:34 +10:00
sam f3a1ef6de1 fix(postgres): one isUniqueViolation after merging the EDA and status lanes 2026-09-24 02:33:52 +10:00
sam ecc1997384 Merge branch 'run/pg-w2-5' into worktree-giggly-marinating-lamport
# Conflicts:
#	internal/infrastructure/postgres/postgresdb/models.go
2026-09-24 02:31:06 +10:00
sam 5e1c43f1c5 Merge branch 'run/pg-w2-3' into worktree-giggly-marinating-lamport 2026-09-24 02:30:51 +10:00
sam dfed51547c Merge branch 'run/pg-w2-2' into worktree-giggly-marinating-lamport 2026-09-24 02:30:48 +10:00
sam cb1cd62eea Merge branch 'run/pg-w1' into worktree-giggly-marinating-lamport 2026-09-24 02:30:47 +10:00
sam feeaa16c7b feat(postgres): wire the State Store to Postgres — DB URL, fail-closed pool, composition seam
Wave 1 of the Postgres migration (archie-core-7r0x.9). This is the shared shape
every port lane builds on; nothing here switches a live path to Postgres yet.

- config: add `database_url` beside `db_path` (config.go), mark it bootstrap-only
  in denied_keys, expose it in the webui StorageView/config schema, and add it to
  config.example.toml plus all deployments/*.toml.
- docker-compose: add a postgres:18 service; `task dev` (dev:postgres) brings it
  up and waits for it before the State Store boots.
- archied: `openStateStore` now opens and migrates the process-scoped Postgres
  pool via `openStateStorePool`. The State Store fails closed (D1.2) when
  database_url is absent or invalid rather than fall back to SQLite; serving
  against Postgres later requires an import-completion record (D1.3), which is a
  later lane's gate, not this one.
- composition seam: task-store construction (state_store_task.go) and EDA-store
  construction (state_store_eda.go) are extracted from openStateStore, with the
  pool open in state_store_pool.go. This is a behaviour-preserving refactor only
  — no store, interface, error, ordering or logging change — so L1 and L2 build
  against separate files instead of sharing state_store.go.

Tests: fail-closed pool behaviour is pinned (absent/invalid URL); the State Store
boot/restart tests now run against a throwaway Postgres 18 container (pgtest
TestMain). Scoped test command and module-wide build pass; see lane report.
2026-09-24 02:18:56 +10:00
sam cadf248b1f feat(postgres): port events/identities/status surfaces, fix shipped defects
CHECKPOINT -- the full State Store port is in progress; this lands the
compile-clean core so the review pass has a diff to work against. Remaining:
advisory-lock ownership, event-insert serialization, maintenance, and the
ported test battery.

Two corrections to behaviour that already shipped, not new features:
- UpdateTask wrote park_reason raw where SQLite applies clip(park_reason,
  4000); the PostgreSQL adapter now clips before binding (clip.go).
- tasks.review_cursor existed on the protobuf wire and in workflow.Task but
  not in the PostgreSQL schema; 0004 adds it as a NEW migration rather than
  amending 0001 because a dev database may already have applied 0001 and
  goose tracks version numbers, not checksums.

Also moves the control-plane Resource/ResourceWrite types and their sentinels
into storecontract so the postgres package can stop importing internal/store
(they stay aliased there for daemon callers).
2026-09-24 02:17:44 +10:00
sam f3471131ff feat(postgres): port EDA store to Postgres (captures, mappings, bindings, ledgers, tool_calls)
L2 of the PocketBase->Postgres migration (bead archie-core-7r0x.3): a new
Postgres-backed EDA adapter (postgres.EDA) plus its goose migration
(0002_edastore.sql) and sqlc queries (queries/edastore.sql), satisfying the
same storecontract surfaces as internal/infrastructure/edastore.Store so the
cutover wave can swap them behind the contract. The PocketBase opener in
internal/app/archied/state_store.go is untouched: production still opens
SQLite, and the cutover waits for the one-time import.

Three recon-found hazards, each pinned by a test, not a comment:

1. Empty-secret early return. applyBinding deliberately never writes the
   secret column when the incoming secret is empty, so an edit form that does
   not echo the secret must not blank an armed binding's HMAC key. The
   UpdateBinding query keeps the stored secret via
   `secret = CASE WHEN $secret = '' THEN secret ELSE $secret END`; pinned by
   TestUpdateBindingEmptySecretPreservesStored (raw column unchanged across an
   empty-secret edit).

2. Unique-violation detection by SQLSTATE. isUniqueViolation previously grepped
   the driver's error text for "unique"/"already exists"; Postgres reports
   SQLSTATE 23505 and the text match would not fire, losing ErrAlreadyDispatched.
   The adapter detects by pgconn.PgError.Code == "23505"; pinned by
   TestIsUniqueViolationDetectsBySQLState (23505 with a message lacking those
   words is detected; a non-23505 whose text says "unique" is not).

3. One-binding-per-source / one-armed-binding-per-source were read-then-refuse
   with no transaction and a non-unique idx_bindings_source_status. Made them
   constraints: UNIQUE(source) plus a partial UNIQUE(source) WHERE
   status='armed' (the full unique subsumes the armed rule today, kept explicit
   for a future matcher extension). A concurrent insert for one source yields
   exactly one success and one ErrBindingOverlap; pinned by
   TestConcurrentInsertBindingSameSource.

Dispatch ledgers kept exactly: UNIQUE(binding, capture) and
UNIQUE(playbook_id, playbook_version, event_id, action_id); binding_version is
stored but deliberately not part of the key (pinned by
TestBindingDispatchVersionBumpDoesNotPermitRedispatch). The cipher is
unchanged: AES-256-GCM, key = SHA-256(material), decrypt stays in the store and
the gRPC wire still carries plaintext.

Notify is left as an injected callback (EDA.SetNotify) and is NOT wired to
LISTEN/NOTIFY. It is dead code today: edastore.Config.Notify is omitted at its
only production construction and no consumer maps binding_changed/
mapping_changed, so building a LISTEN/NOTIFY path would be building for a
consumer that does not exist. Wired or not is a separate decision.
2026-09-24 02:17:31 +10:00
sam 710fbab094 feat(gateway): port session store to Postgres
Move sessions, messages, turns and full-text search off the per-process
SQLite file onto Postgres behind the existing messaging.SessionStore
contract. New adapter internal/gateway/session_store_postgres.go, sqlc
queries/gateway.sql, migration 0003_gateway.sql, regenerated postgresdb.

FTS5 becomes a STORED generated tsvector column over (sender, text) plus
GIN. plainto_tsquery is the tsvector analog of ftsMatchQuery's
quote-escaping: query text is parsed as plain text, never query syntax, and
the surviving terms are ANDed. MessagePage.Truncated stays always-false on
Postgres too: the result set is counted exactly.

On internal/domain/messaging/session_store.go: this is a comment-only edit
to the MessagePage.Truncated doc comment (the brief's own "change the
comment" instruction). It changes no type, method or value, so L2 and the
import lane still build against an unchanged contract and the wire is
unaffected. No interface widened or altered.

Semantics preserved verbatim:
- The timestamp clamp is SQL-atomic (INSERT ... SELECT MAX(ts)+1). Appends to
  one session are serialised by a transaction-scoped advisory lock keyed on
  the session so two concurrent appends cannot read the same MAX(ts); a Go
  clamp would race (proven by the new cross-handle monotonicity test).
- Session ordering is GREATEST(last_active_at, created_at) with a matching
  expression index.
- ClaimTurn is insert-first (ON CONFLICT DO NOTHING), with a race test across
  two handles.

State outside the store is NOT made shared by this change, and none of it is
silently improved or worsened:
- sessionTracker.active, Router.titling and per-session persona selection are
  in-memory, per-process caches; a second Gateway still diverges from the
  first.
- messaging.Turns lanes and the per-process recovery latch stay per-process.
- RecoverTurns still fails every turn owned by another process, so a second
  Gateway starting would still fail the first's in-flight turns. This lane
  does NOT make that safe and does not try to: the safeguard is D4.1's
  single-Gateway advisory serve-ownership lock (not implemented here), which
  prevents a second Gateway from serving at all. The turn-recovery semantics
  are left exactly as they were.

Production openers still return SQLite; this lane adds the adapter and tests
only. The cutover and the state-sharing questions remain follow-up work.
2026-09-24 02:17:23 +10:00
sam 038b8035ff feat(postgres): preserve resource write semantics 2026-09-24 01:38:40 +10:00
sam a69f9c81c2 feat(postgres): State Store schema and sqlc queries, with the claim path proven on PG 18
goose migration 0001 lands the twelve State Store tables on Postgres, and sqlc generates the task queries from it. Two behaviours that genuinely differ from SQLite are pinned by tests against a real PG 18: claiming takes the oldest queued row with FOR UPDATE SKIP LOCKED (without the clause a second claimer blocks, which the test shows by timing out), and every column behind a Go int is bigint -- SQLite's INTEGER is 64-bit, and the chat issue-number allocator seeds at 10^15, which does not fit an int4.

task db:generate writes the committed postgresdb package; task db:check regenerates it in the gate, as proto:check and ui:check do.

The remaining store methods (events, resources, identities, the status tables) still run on SQLite: porting them is the rest of archie-core-7r0x.2.
2026-09-24 01:18:19 +10:00
sam c6df4b4a54 refactor(state-store): remove the PocketBase admin view
stateadmin served read-only PocketBase views over the SQLite task file on -admin-addr. PocketBase is SQLite-only and the State Store moves to Postgres (archie-core-7r0x), so the view goes; operators use a Postgres tool of their choice.
2026-09-24 01:09:42 +10:00
sam c620e00396 feat(postgres): pool that refuses servers before PG 18, goose migrations under an advisory lock, testcontainers harness
internal/infrastructure/postgres opens a pgx pool, checks server_version_num >= 180000, and applies goose migrations with a Postgres session advisory lock so processes starting together apply each migration once. internal/infrastructure/postgres/pgtest starts postgres:18 through testcontainers per test binary and gives each test its own database. Adds jackc/pgx/v5 v5.11.0, pressly/goose/v3 v3.28.0 and testcontainers-go v0.44.0. The database URL config, sqlc, the Compose service and the ownership lock move to archie-core-7r0x.2, where they have consumers.
2026-09-24 01:03:08 +10:00
sam 01586f1630 docs(prds): orgs, workspaces and access control
Approved design for orgs and workspaces, people and agents as identities, the Cedar policy chain (instance with network rules, org, workspace, identity and workflow, object), server-derived credential scope, and one run credential per agent run. Secrets move from agent profiles to identities; event-automation.md is marked superseded where it said otherwise.
2026-09-24 00:34:14 +10:00
sam d03e7fdef4 docs: regenerate dev-docs.json for the event automation PRD 2026-09-24 00:30:22 +10:00
sam f4d20cfe0a fix(build): task check runs in ~27s cold, ~12s warm
task test runs -short with the test cache on; task test:full keeps the
uncached run. The 50s keepalive proof skips under -short (the deploy
workflow's full go test still runs it). Sleep-bound archied watch tests
run in parallel, and the read-only gate steps run concurrently after fmt
and proto:check. ui:deps is run: once so the parallel UI steps install once.
2026-09-24 00:29:07 +10:00
sam 94ca015070 docs(prds): event automation — identified events, typed parameters, purpose-built agents 2026-09-23 23:50:27 +10:00
sam 7c6e7d54ad fix(webui): binding ids are strings and a new binding gets a generated signing secret
bindingPayload sent mapping_id as Number(id), which is 0 for every current mapping id, so every binding created or edited from the dashboard was refused. A new binding now starts with a generated secret the operator copies to the sender; an edit keeps the stored one unless replaced. The dev proxy keeps the browser's Host and forwards /webhooks. Checked with typecheck, task ui and task test:ui; the full gate was not run.
2026-09-23 23:50:27 +10:00
sam 86690ef73e fix(bindings): a new binding is created pending approval
Nothing moved a binding out of draft except an unrelated edit, so a newly created binding could not be approved and the dashboard showed no Approve button. Draft is removed; existing draft rows are promoted to pending_approval when the EDA store opens.
2026-09-23 23:13:49 +10:00
sam 528d6c4be2 fix(webui): dev proxy keeps the browser's Host, and editor errors show beside Save
Vite's proxy shorthand sets changeOrigin, so every mutation through the dev server failed archie-ui's same-origin check. The mapping and binding editors rendered their refusal at the top of a scrolled dialog, out of view of the Save button.
2026-09-23 22:58:45 +10:00
sam 891970f1ad feat(eda): playbook.Load findings name the offending action, when or args line 2026-09-23 22:42:14 +10:00
sam 3b303b353f refactor(playbooks): serve on go.lsp.dev/protocol instead of hand-written LSP types
Replaces sourcegraph/jsonrpc2 with the go.lsp.dev stack (protocol, jsonrpc2, uri). The exit notification now ends Serve; closing the connection from inside the exit handler deadlocked.
2026-09-23 22:34:33 +10:00
sam fda2c51f6d feat(playbooks): archie-playbooks serve, a language server publishing lint findings as diagnostics 2026-09-23 22:22:56 +10:00
sam 61dd33edce feat(playbooks): lint an EDA playbook directory with -eda-dir 2026-09-23 22:11:01 +10:00
sam 534153d50a feat(eda): reject an args value whose checked CEL type cannot fill its Args field 2026-09-23 22:05:50 +10:00
sam 2bc4b8db32 feat(eda): run action playbooks at pin time through the at-most-once dispatch ledger 2026-09-23 22:00:52 +10:00
sam 6046948ff0 docs(eda): playbook dispatch rows are retained until an explicit delete 2026-09-23 21:52:10 +10:00
sam 4237b560b0 fix(eda): type-aware actions classifier, one stable-identifier grammar, loader tests that fail for the named reason 2026-09-23 21:48:52 +10:00
sam 3a4af23caa feat(workflow): routing and playbook findings carry the key's file:line 2026-09-23 21:41:56 +10:00
sam 288e9ea370 fix(webui): move the live stream to /api/stream so reloading /events serves the page 2026-09-23 21:16:29 +10:00
sam aa054f8109 feat(webui): two-section quality gates, sweep the restating card prose
The quality gates card stacked its number and rows across the full row
width -- the rate pinned to the left edge, the counts to the right --
which reads as two places at once. The card now has two internal
sections, left to right: the rate, and the per-workflow rows that
explain it; the row collapses under 720px.

Also swept the restating descriptions: 'Work that passed its quality
gates' under Quality gates, 'Archie needs these before it can work on
its own' under Finish setting up, 'Next 30 days at the current rate'
under Token outlook, 'Last 50, newest first' under Live activity. A
title and a sentence that restate each other are noise; the table or
chart says the thing. CapturesCard's redaction note is a security fact,
not restatement, and stays. The unconfigured versions state is one
quiet line, not a card with a title, a description, and a sentence.
2026-09-23 15:29:28 +10:00
sam 5e82a18697 feat(webui): compact quality gates card, drop the setup celebration, hover nav
Three dashboard refinements from operator feedback:

The setup panel's completed state was celebration prose -- a full card
saying setup was done, occupying a grid cell until dismissed. A
configured daemon is the absence of a problem: the state machine now
only distinguishes incomplete from omit, the checklist returns on its
own if setup regresses, and the dismissal machinery is deleted with it.

'Gate pulse' led with a donut whose entire payload was one number, and
the name was decoration too. The card is 'Quality gates' now: the pass
rate as the number itself beside its run count, per-workflow rows as
tight hairline rows instead of muted pills, and the parked line is gone
-- Throughput's Needs-you tile already speaks for parked tasks, from the
statuses themselves. base/Gauge.vue had no other consumer and is deleted.

Topbar nav groups open on hover and close on leave, with a short grace
period bridging the trigger-to-content gap; click and keyboard
activation keep working through the same controlled open state.

The live activity feed scrolls within its card (previous commit); the
health row's cards are now compact enough to match it.
2026-09-23 14:53:40 +10:00
sam d76bf2be67 fix(webui): bound the live activity feed to the card
Group rows multiply with the number of interleaved tasks -- one group
per task per detail shape -- and nothing capped the card's height, so a
live instance rendered the dashboard ~4,700px tall with a void beside
the token outlook card. The feed now scrolls inside a 28rem region with
a sticky header: newest events at the top, the rest in place, and the
RIGHT NOW section's two cards stay comparable in height.
2026-09-23 14:42:43 +10:00
sam 475dc7c097 docs(releasing): record that main and the branch diverge on every release
The release commit lands on main, because tools/release.sh refuses to run
anywhere else, while the working branch keeps advancing. So after every release
neither tip is an ancestor of the other and --ff-only fails in both directions
-- a refusal that reads as "the tree is not ready" when the tree is fine. It
cost confusion on both v1.38.0 and v1.40.0, and both times the correct answer
had to be re-derived from the commit graph.

Documents the order that keeps a conflict off main (merge main into the branch
first, then fast-forward), and the trap that catches people looking for main: a
detached worktree sitting at the same commit accepts --ff-only and moves
nothing, which looks like success.
2026-09-23 14:42:32 +10:00
1277 changed files with 62963 additions and 29385 deletions

No files matched your search

+26 -19
View File
@@ -12,7 +12,7 @@ description: >-
# Run an agent fleet on archie-core
This skill carries the facts about *this repository*. It deliberately does not
This skill carries the facts about _this repository_. It deliberately does not
restate the process.
## Where the method lives
@@ -36,16 +36,16 @@ Route runtime facts to `archie-run-and-operate`, toolchain facts to
State these as facts to each lane, not as advice. Each one has cost a real run.
| Invariant | Why it matters to a lane |
|---|---|
| **The control plane fails closed.** A stored resource that will not validate stops `archied` starting, and nothing bypasses the control plane at boot. Resource history is the only in-band remedy, and it needs the State Store up. | A lane touching the boot path, a stored resource kind, or the recovery commands is a risk-routed lane for the operator's eyes, not a gate-and-merge lane. Evidence: `docs/architecture/safe-change-and-recovery.md` ("Database settings: degrade paths and recovery"). |
| **`internal/webui` must not reach `internal/domain/workflow`.** Go imports are atomic: one reference relinks the whole daemon runtime into the UI binary. | `cmd/archie-ui/architecture_test.go` measures the linked binary (`go list -deps .`), not the imports, and fails on anything under `internal/domain/workflow`. `internal/domain/workflow/task` is a named `gateExceptions` entry that must stay linked — it carries only contract and view types, and a stale exception fails the test in both directions. The same test's gate also excludes `internal/app/archied` from the UI binary, so a helper needed by both the daemon and the `cmd/` binaries belongs in `internal/infrastructure/configuration` (which already owns path resolution), never in `archied`. |
| **The task DB has one owner.** `<db_path>-tasks.sqlite` is served by the standalone `cmd/archie-state-store` process alone. No second listener, no in-process serving path in the daemon or Gateway. | `boot.openStateStore` (`internal/app/archied/state_store.go`) is the only production caller of `openProductionTaskStore`, and it takes an exclusive flock on `<db>.lock` for the process's life — a second State Store on the same file fails there rather than merely being discouraged. Offline maintenance belongs in subcommands of that binary, never a new `cmd/` entry (`docs/architecture/organisation.md#process-boundaries`). |
| **Never commit `.beads/`.** Bead state moves through Dolt; `issues.jsonl` and `interactions.jsonl` are local-only. | A lane that stages `.beads/` pollutes its diff. Closing a bead is not commit-worthy on its own. |
| **Generated assets are LAW.** `ui/dist/` and the schema outputs (`docs/data/generated/contracts.json`). | Incorporate them into the commit that shifted them. Never revert, regenerate away, or leave them out. |
| **Scratch goes to `/tmp` only.** Never the working tree. | `worktree.CommitAll` stages with go-git's `AddWithOptions{All: true}` (`internal/worktree/worktree.go:502`), which does **not** honour `.gitignore`. An untracked scratch file in a lane worktree is swept onto the task branch. The task brief lives in `.git/task.json` for exactly this reason. |
| **A config field must survive the control-plane round trip or it does nothing.** A field added to `MCPServer` (or any projected settings type) must be carried in three sites: `mcpServerSettings` and `seedTools` in `internal/app/controlplane/tool_settings.go`, and `runtimeToolConfigFrom` in `runtime_config.go`. | The control plane rebuilds the whole resource from that projection, so a field missing there is silently dropped whenever a control plane is configured: the setting parses, appears in the dashboard, and has no effect. `TestToolSettingsProjectionCarriesEveryMCPServerField` reflects over `MCPServer` and fails on an omitted field, in both directions (seed and layering) — but it covers that type only; every other mirrored type (`minimaxSettings`, ...) is still hand-mirrored. Adding the field to just `internal/config` is the `xrux`/`parallel_tool_calls` failure shape. |
| **Dependency direction is `cmd -> app -> {domain, infrastructure}`**, with infrastructure implementing domain contracts. | A lane that needs a new edge says so before writing it. The `internal/{logging,events,eventbus,policy,taskstate}` cross-cutting packages import zero internal packages. Source: `docs/architecture/organisation.md`. |
| Invariant | Why it matters to a lane |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **The control plane fails closed.** A stored resource that will not validate stops `archied` starting, and nothing bypasses the control plane at boot. Resource history is the only in-band remedy, and it needs the State Store up. | A lane touching the boot path, a stored resource kind, or the recovery commands is a risk-routed lane for the operator's eyes, not a gate-and-merge lane. Evidence: `docs/architecture/safe-change-and-recovery.md` ("Database settings: degrade paths and recovery"). |
| **`internal/webui` must not reach `internal/domain/workflow`.** Go imports are atomic: one reference relinks the whole daemon runtime into the UI binary. | `cmd/archie-ui/architecture_test.go` measures the linked binary (`go list -deps .`), not the imports, and fails on anything under `internal/domain/workflow`. `internal/domain/workflow/task` is a named `gateExceptions` entry that must stay linked — it carries only contract and view types, and a stale exception fails the test in both directions. The same test's gate also excludes `internal/app/archied` from the UI binary, so a helper needed by both the daemon and the `cmd/` binaries belongs in `internal/infrastructure/configuration` (which already owns path resolution), never in `archied`. |
| **The task DB has one owner.** The task tables are served by the standalone `cmd/archie-state-store` process alone. No second listener, no in-process serving path in the daemon or Gateway. | `boot.openStateStore` (`internal/app/archied/state_store.go`) is the only place the task store is built, and it holds the `state-store` Postgres ownership lock for the process's life — a second State Store on the same database fails there rather than merely being discouraged. Offline maintenance belongs in subcommands of that binary, never a new `cmd/` entry (`docs/architecture/organisation.md#process-boundaries`). |
| **Never commit `.beads/`.** Bead state moves through Dolt; `issues.jsonl` and `interactions.jsonl` are local-only. | A lane that stages `.beads/` pollutes its diff. Closing a bead is not commit-worthy on its own. |
| **Generated assets are LAW.** `ui/dist/` and the schema outputs (`docs/data/generated/contracts.json`). | Incorporate them into the commit that shifted them. Never revert, regenerate away, or leave them out. |
| **Scratch goes to `/tmp` only.** Never the working tree. | `worktree.CommitAll` stages with go-git's `AddWithOptions{All: true}` (`internal/worktree/worktree.go:502`), which does **not** honour `.gitignore`. An untracked scratch file in a lane worktree is swept onto the task branch. The task brief lives in `.git/task.json` for exactly this reason. |
| **A config field must survive the control-plane round trip or it does nothing.** A field added to `MCPServer` (or any projected settings type) must be carried in three sites: `mcpServerSettings` and `seedTools` in `internal/app/controlplane/tool_settings.go`, and `runtimeToolConfigFrom` in `runtime_config.go`. | The control plane rebuilds the whole resource from that projection, so a field missing there is silently dropped whenever a control plane is configured: the setting parses, appears in the dashboard, and has no effect. `TestToolSettingsProjectionCarriesEveryMCPServerField` reflects over `MCPServer` and fails on an omitted field, in both directions (seed and layering) — but it covers that type only; every other mirrored type (`minimaxSettings`, ...) is still hand-mirrored. Adding the field to just `internal/config` is the `xrux`/`parallel_tool_calls` failure shape. |
| **Dependency direction is `cmd -> app -> {domain, infrastructure}`**, with infrastructure implementing domain contracts. | A lane that needs a new edge says so before writing it. The `internal/{logging,events,eventbus,policy,taskstate}` cross-cutting packages import zero internal packages. Source: `docs/architecture/organisation.md`. |
## The canonical gate
@@ -80,13 +80,13 @@ go test ./internal/app/controlplane/... ./internal/domain/applystatus/... -count
Real examples, from the worked example's `lanes.json`:
| Lane surface | Scoped command |
|---|---|
| CLI subcommands and the State Store contract | `go test ./cmd/... ./internal/infrastructure/staterpc/... -count=1 && go vet ./cmd/...` |
| Workflow registry and the agent worker | `go test ./internal/domain/workflow/... ./internal/app/agentworker/... -count=1 && go vet ./internal/domain/workflow/...` |
| Config decoding and daemon boot | `go test ./internal/infrastructure/configuration/... ./internal/app/archied/... -count=1 && go vet ./internal/infrastructure/configuration/... ./internal/app/archied/...` |
| Lane surface | Scoped command |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CLI subcommands and the State Store contract | `go test ./cmd/... ./internal/infrastructure/staterpc/... -count=1 && go vet ./cmd/...` |
| Workflow registry and the agent worker | `go test ./internal/domain/workflow/... ./internal/app/agentworker/... -count=1 && go vet ./internal/domain/workflow/...` |
| Config decoding and daemon boot | `go test ./internal/infrastructure/configuration/... ./internal/app/archied/... -count=1 && go vet ./internal/infrastructure/configuration/... ./internal/app/archied/...` |
`task check` is the *serial full gate* — fmt, proto checks, `docs:check`, vet,
`task check` is the _serial full gate_ — fmt, proto checks, `docs:check`, vet,
lint, build, `go test ./...`, the tools tests and the dashboard tests. The merge
train owns it. Never run it in a lane, and never two at once: it saturates the
host.
@@ -128,14 +128,21 @@ commit. This costs an hour to rediscover.
## Traps worth carrying
- **`touch` does not invalidate a Task source.** Task hashes file *content*, so a
- **`touch` does not invalidate a Task source.** Task hashes file _content_, so a
stale-binary probe has to change bytes. `task build` now tracks `ui/dist/**`,
the generated dashboard the binary embeds, which is why the merge train still
runs `task build --force` before the gate.
- **`GATEWAY_VERSION` and `RUNTIME_VERSION` come from `git describe`**, which no
file checksum can invalidate: an empty commit moves the stamp while `task
build` still reports the binary up to date, shipping the old value. Tracked as
build` still reports the binary up to date, shipping the old value. Tracked as
`archie-core-pdq2`.
- **The lane gate cannot see `tools/` or the contract schema.** `tools/` is
a separate Go module that reaches `internal/` through `docsgen`, and
`docs/data/generated/contracts.json` is generated from wire types such as
`agentexec.Request`. A lane that adds an import to a package `tools/`
reaches, or changes a wire type, passes its own gate and fails
`task check` on a missing `tools/go.sum` entry or a stale schema. Such a
lane runs `go -C tools mod tidy` and `task docs:generate` and commits both.
- **Untracked files in the shared checkout are other sessions'.** prdlint
scratch (`docs/prds/rules.jsonl`), editor state, and gate-written artifacts
appear and vanish under a lane. Never chase, add, stage or commit them: a
@@ -12,8 +12,8 @@ You are the orchestrator. You do not write production code yourself. You run
waves of subagents through the `subagent` tool, verify their work against git
evidence rather than their reports, and land finished slices on `main`.
Repository: `/work/apps/archie-core`, branch `main`, working tree clean at start.
Gate: `task check`. Tracker: `bd`. Read `CLAUDE.md` and
Repository: `/work/apps/archie-core`, branch `main`, working tree clean at
start. Gate: `task check`. Tracker: `bd`. Read `CLAUDE.md` and
`docs/architecture/organisation.md` before Wave 1.
---
@@ -34,20 +34,20 @@ Gate: `task check`. Tracker: `bd`. Read `CLAUDE.md` and
manifest path, `git -C <worktree> status --short`, `git log --oneline`, and
`git diff --stat` against the lane's own base. A bead marked closed with no
commits means the work did not happen.
5. **No suppression.** Children may not add `//nolint`, `t.Skip`, build tags that
exclude a failing test, or delete an assertion to make a gate pass. Say this
in every writer and fix task. A child that suppresses gets its lane reverted,
not patched.
5. **No suppression.** Children may not add `//nolint`, `t.Skip`, build tags
that exclude a failing test, or delete an assertion to make a gate pass. Say
this in every writer and fix task. A child that suppresses gets its lane
reverted, not patched.
6. **Formatting is law.** Adopt `task fmt` output verbatim. Never revert a
linter or formatter diff.
7. **Zero patch stacking.** Two failed fixes on the same logic block means the
block gets rewritten, not patched a third time. This is a `CLAUDE.md` rule and
it applies to children.
block gets rewritten, not patched a third time. This is a `CLAUDE.md` rule
and it applies to children.
8. **Do not push.** Commit gate-clean work to `main` in the captain checkout.
Sam pushes manually and does not always announce it, so never assume a commit
is local or remote without checking `git log origin/main..main`.
9. **No `.beads/` commits.** Bead state moves through Dolt. Closing a bead is not
commit-worthy on its own.
9. **No `.beads/` commits.** Bead state moves through Dolt. Closing a bead is
not commit-worthy on its own.
10. **Scratch stays out of the tree.** Children write scratch to `/tmp` only.
`.pi/` is gitignored; nothing else you create may land in a commit.
11. **Separation of duties.** No agent merges, closes or approves its own work.
@@ -66,16 +66,17 @@ Gate: `task check`. Tracker: `bd`. Read `CLAUDE.md` and
This came from the session that just ended. Treat it as fact.
- `docs/prds/runtime-control-plane.md` is Approved and is the spec. Its resource
surface, YAML workflow definitions, identity-backed attribution and audit trail
are already built.
surface, YAML workflow definitions, identity-backed attribution and audit
trail are already built.
- **Restore is not its own command.** A revision carries its value, so restoring
replays it through the ordinary replace. Do not add a rollback RPC.
- **Dashboard writes attribute to `identity.SystemID`.** One shared bearer token,
no per-user session. `webAudit` in `internal/webui/api_identities.go` is the
only source. Named attribution needs a dashboard login first.
- **Dashboard writes attribute to `identity.SystemID`.** One shared bearer
token, no per-user session. `webAudit` in `internal/webui/api_identities.go`
is the only source. Named attribution needs a dashboard login first.
- **`internal/webui` must not link the workflow engine.** It decodes definitions
with the projection types in `internal/domain/workflow/task`. `cmd/archie-ui`'s
deletion gate fails if anything reaches `internal/domain/workflow`.
with the projection types in `internal/domain/workflow/task`.
`cmd/archie-ui`'s deletion gate fails if anything reaches
`internal/domain/workflow`.
- Shipped defaults ride `ResourceDescriptor.defaults_json`. The API is fixed at
four operations, so defaults get no REST route.
- `archie-messaging` fails closed when the State Store is unreachable. The
@@ -85,18 +86,18 @@ This came from the session that just ended. Treat it as fact.
boot. `docs/architecture/safe-change-and-recovery.md` records this posture.
Resource history is the only in-band remedy and needs the State Store up.
- **`task check` will not catch a field the server stopped sending.** Optional
chaining made a dead dashboard banner typecheck silently; `delivery-snapshot.sh`
scanned for a symbol its composition root no longer calls. Both fixed in
`85f0fd0b`. When a server-side field is deleted, grep the dashboard and the
snapshot scripts by name. Add this to every review task.
- **Reload re-reads the database layer and can fail.** `boot.runtimeConfig` is the
one layering call; the SIGHUP callback makes the same call over the document it
just resolved (`9af013eb`). A new database-owned layer goes in `runtimeConfig`
and nowhere else.
chaining made a dead dashboard banner typecheck silently;
`delivery-snapshot.sh` scanned for a symbol its composition root no longer
calls. Both fixed in `85f0fd0b`. When a server-side field is deleted, grep the
dashboard and the snapshot scripts by name. Add this to every review task.
- **Reload re-reads the database layer and can fail.** `boot.runtimeConfig` is
the one layering call; the SIGHUP callback makes the same call over the
document it just resolved (`9af013eb`). A new database-owned layer goes in
`runtimeConfig` and nowhere else.
- **Apply status lives on the State Store contract, not the control plane.**
`PutApplyStatus`/`ListApplyStatus` are administrative, keyed on
`(process, kind)`, replaced in place, re-stamped every 30s, stale at 90s, and a
stale record renders as "Not reporting", never as current. `applystatus.New`
`(process, kind)`, replaced in place, re-stamped every 30s, stale at 90s, and
a stale record renders as "Not reporting", never as current. `applystatus.New`
refuses a process name `Processes()` does not list.
- Five commits are local as of 2026-09-21: `731a9a06`, `1dd0d874`, `d9dd7885`,
`9accf112`, `d38e27fd`. `archie-core-pskb` is closed. There is no post-commit
@@ -109,31 +110,31 @@ This came from the session that just ended. Treat it as fact.
Seven ready beads carry the `control-plane` label. Their real shape is what
decides the lanes, and it is not the same as their titles.
| Bead | Title shape | Primary surface |
|------|-------------|-----------------|
| `archie-core-nwa0` | check a live replacement before switching to it | live apply path + apply-status surface |
| `archie-core-fwmp` | let plugins register workflow step types | `workflow.BuiltinStepRegistry()` and all five call sites |
| `archie-core-8szi` | registered steps covering the deleted `.archie` gate | `internal/domain/workflow/steps.go`, needs fwmp's answer |
| `archie-core-6zw0` | offline backup/restore/validate/rollback for `archie.db` | new `cmd/` binary + state-store infrastructure |
| `archie-core-i3qm` | stop TOML blocking State Store startup | `internal/app/archied/control_plane.go`, bootstrap validation |
| `archie-core-xrux` | `ApplyOverlayValues` is dead, confirm the file overlay | `internal/infrastructure/configuration/loader.go`, `apply.go` |
| `archie-core-eju6` | end-to-end restart test for a database-backed change | test only, proves the whole loop |
| Bead | Title shape | Primary surface |
| ------------------ | -------------------------------------------------------- | ------------------------------------------------------------- |
| `archie-core-nwa0` | check a live replacement before switching to it | live apply path + apply-status surface |
| `archie-core-fwmp` | let plugins register workflow step types | `workflow.BuiltinStepRegistry()` and all five call sites |
| `archie-core-8szi` | registered steps covering the deleted `.archie` gate | `internal/domain/workflow/steps.go`, needs fwmp's answer |
| `archie-core-6zw0` | offline backup/restore/validate/rollback for `archie.db` | new `cmd/` binary + state-store infrastructure |
| `archie-core-i3qm` | stop TOML blocking State Store startup | `internal/app/archied/control_plane.go`, bootstrap validation |
| `archie-core-xrux` | `ApplyOverlayValues` is dead, confirm the file overlay | `internal/infrastructure/configuration/loader.go`, `apply.go` |
| `archie-core-eju6` | end-to-end restart test for a database-backed change | test only, proves the whole loop |
Three couplings you already know about, and Wave 0 exists to find the rest:
- **fwmp is the shared shape.** It changes the registry every call site hardcodes
(`app/agentworker/task_execution.go:319,:335`,
`app/controlplane/workflow_definitions.go:26,:33`, `app/controlplane/client.go:41`)
and the validating side and the executing side must resolve it identically.
8szi has nothing to register against until fwmp lands. These two are never
concurrent writers.
- **fwmp is the shared shape.** It changes the registry every call site
hardcodes (`app/agentworker/task_execution.go:319,:335`,
`app/controlplane/workflow_definitions.go:26,:33`,
`app/controlplane/client.go:41`) and the validating side and the executing
side must resolve it identically. 8szi has nothing to register against until
fwmp lands. These two are never concurrent writers.
- **xrux decides i3qm's blast radius.** xrux is an investigation with two
opposite outcomes: either the file overlay zeroes omitted map fields, in which
case `foldOverrides` moves there and it is a live bug, or it does not, in which
case `apply.go`, `apply_test.go` and `Loader.ApplyOverlay` are deleted. Both
land in the same package i3qm rewrites. One lane owns both, in that order.
`archie-core-xrux` is a trap, not a cleanup. Read the bead before deleting
`apply.go`.
case `foldOverrides` moves there and it is a live bug, or it does not, in
which case `apply.go`, `apply_test.go` and `Loader.ApplyOverlay` are deleted.
Both land in the same package i3qm rewrites. One lane owns both, in that
order. `archie-core-xrux` is a trap, not a cleanup. Read the bead before
deleting `apply.go`.
- **eju6 proves the others.** It goes last, against everything merged.
---
@@ -143,11 +144,11 @@ Three couplings you already know about, and Wave 0 exists to find the rest:
Run `subagent({ action: "models" })` first and pick exact `provider/id` strings.
Bare ids resolve only when unique. Then print the table you resolved and use it.
| Tier | Used by | Pick |
|------|---------|------|
| Fast | recon, inventory, grep-shaped probes | cheapest capable, low or medium thinking. Default `ollama/deepseek-v4.1-flash:cloud`. |
| Strong | writers, integrator | best reasoning model authenticated here, high thinking. Prefer a `deepseek-v4-pro` class id if `models` lists one. |
| Review | reviewers, oracle | a **different family** from the writer that produced the diff. Model diversity catches different failure modes; it does not rescue an ambiguous prompt. |
| Tier | Used by | Pick |
| ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Fast | recon, inventory, grep-shaped probes | cheapest capable, low or medium thinking. Default `ollama/deepseek-v4.1-flash:cloud`. |
| Strong | writers, integrator | best reasoning model authenticated here, high thinking. Prefer a `deepseek-v4-pro` class id if `models` lists one. |
| Review | reviewers, oracle | a **different family** from the writer that produced the diff. Model diversity catches different failure modes; it does not rescue an ambiguous prompt. |
If a tier cannot be resolved, say so and fall back to the session default rather
than inventing an id. Provider 429s return from that model; do not kill a rate
@@ -159,8 +160,8 @@ limited child, it keeps its context and recovers.
Defaults in this install (`pi-subagents` 0.70.0) are not 64.
- `globalConcurrencyLimit` defaults to **20** concurrent children per run. Set it
explicitly on each top-level call.
- `globalConcurrencyLimit` defaults to **20** concurrent children per run. Set
it explicitly on each top-level call.
- `maxSubagentSpawnsPerRun` defaults to **64** cumulative admissions per run
tree, never refunded. Retries and fix passes spend it too.
- **Each wave is its own top-level run, so each wave gets its own budget.** This
@@ -169,24 +170,24 @@ Defaults in this install (`pi-subagents` 0.70.0) are not 64.
Per-wave dials:
| Wave | Shape | `globalConcurrencyLimit` | `maxSubagentSpawnsPerRun` |
|------|-------|--------------------------|---------------------------|
| 0 recon | `runs.all`, read-only | 32 | 64 |
| 0R audit | `review.js`, angles `claims` | 16 | 24 |
| 1 shape-first | one writer plus one probe | 2 | 8 |
| 1R review | `review.js`, full angle set, one target | 12 | 16 |
| 2 writer lanes | `runs.lanes`, one worktree each | 4 | 32 |
| 2R review | `review.js`, full angle set, four targets | 24 | 48 |
| 3 fix pass | `runs.lanes`, retained writers | 4 | 24 |
| 4 merge train | serial, one `task check` at a time | 1 | 8 |
| 4R post-merge | `review.js` on merged `main`, angles `boundary`, `deadfield`, `contract` | 8 | 12 |
| 5 eju6 | one lane, then its own review | 2 | 12 |
| Wave | Shape | `globalConcurrencyLimit` | `maxSubagentSpawnsPerRun` |
| -------------- | ------------------------------------------------------------------------ | ------------------------ | ------------------------- |
| 0 recon | `runs.all`, read-only | 32 | 64 |
| 0R audit | `review.js`, angles `claims` | 16 | 24 |
| 1 shape-first | one writer plus one probe | 2 | 8 |
| 1R review | `review.js`, full angle set, one target | 12 | 16 |
| 2 writer lanes | `runs.lanes`, one worktree each | 4 | 32 |
| 2R review | `review.js`, full angle set, four targets | 24 | 48 |
| 3 fix pass | `runs.lanes`, retained writers | 4 | 24 |
| 4 merge train | serial, one `task check` at a time | 1 | 8 |
| 4R post-merge | `review.js` on merged `main`, angles `boundary`, `deadfield`, `contract` | 8 | 12 |
| 5 eju6 | one lane, then its own review | 2 | 12 |
Do not set a hard `toolBudget` or a tight `usageBudget` on any writer, fix
worker, or reviewer with edit authority: the default budget blocks read and
search tools rather than mutation tools, which leaves a half-written tree. Bound
writers with `timeoutMs` plus `checkpointBeforeDeadlineMs` instead. Hard caps are
fine on explicitly read-only children.
writers with `timeoutMs` plus `checkpointBeforeDeadlineMs` instead. Hard caps
are fine on explicitly read-only children.
---
@@ -206,7 +207,7 @@ Act on that as follows.
- **WIP is capped by review, not by cores.** Four writer lanes exist because
four is what the review pass and the merge train can absorb per cycle. Do not
raise it to use spare concurrency.
- **Put the judgment upstream.** Before a writer starts, its task must carry
- **Put the judgement upstream.** Before a writer starts, its task must carry
intent, acceptance criteria and non-goals, so verification has an external
reference. "Does this do what it was supposed to do" is checkable; "does this
look right" is not, and fluent output passes a read-through scan regardless of
@@ -229,10 +230,11 @@ Act on that as follows.
gets split at a coherent boundary.
- **Route risk, do not review uniformly.** These surfaces get Sam's eyes before
merge, named explicitly in your report: the fail-closed boot path
(`boot.runtimeConfig`, bootstrap validation), the State Store wire contract and
its error sentinels, task-scoped grants and credentials, anything that writes
or migrates `archie.db`, and the release or CI surface. Everything else merges
on gate plus reviewer verdict, with a sample called out for him to spot-check.
(`boot.runtimeConfig`, bootstrap validation), the State Store wire contract
and its error sentinels, task-scoped grants and credentials, anything that
writes or migrates `archie.db`, and the release or CI surface. Everything else
merges on gate plus reviewer verdict, with a sample called out for him to
spot-check.
- **Watch the right numbers.** Report per wave: reviewer findings raised versus
accepted, lanes blocked by gate versus by review, rework passes per lane, and
wall-clock from lane start to merged. Lines written and beads closed measure
@@ -242,11 +244,12 @@ Act on that as follows.
## 6. Wave 0: recon fanout (read-only, wide)
One top-level call, `async: true`, `workflowScriptPath: ".pi/control-plane-run/wave0.js"`.
One top-level call, `async: true`,
`workflowScriptPath: ".pi/control-plane-run/wave0.js"`.
Three probes per bead, plus four cross-cutting probes: 25 children, all
`cp-recon`, all read-only, all returning structured output. The probe text is composed inside
`wave0.js`; do not retype it.
`cp-recon`, all read-only, all returning structured output. The probe text is
composed inside `wave0.js`; do not retype it.
Per bead:
@@ -261,8 +264,9 @@ Cross-cutting:
- **overlap** — for all seven beads, the set of packages and files each one must
modify, in one table.
- **gate-cost** — time `task build` and `go test ./internal/app/controlplane/...`
and report wall-clock, so Wave 2 timeouts are measured rather than guessed.
- **gate-cost** — time `task build` and
`go test ./internal/app/controlplane/...` and report wall-clock, so Wave 2
timeouts are measured rather than guessed.
- **dead-field** — grep `ui/src/` and `scripts/delivery-snapshot.sh` for every
control-plane field name the server sends today, and flag any the server no
longer sends. This is the failure class `task check` cannot see.
@@ -271,12 +275,12 @@ Cross-cutting:
the single test that would tie each pair together.
Every probe returns `structuredOutput` matching the schema in `wave0.js`. Long
findings go to a file via `outputMode: "file-only"`; do not pull transcripts into
your context.
findings go to a file via `outputMode: "file-only"`; do not pull transcripts
into your context.
**Do not let a recon child draw the conclusion.** A scout that measures correctly
can still land the wrong call, and its write-up reads confident either way. Take
their facts, make the call yourself.
**Do not let a recon child draw the conclusion.** A scout that measures
correctly can still land the wrong call, and its write-up reads confident either
way. Take their facts, make the call yourself.
---
@@ -316,7 +320,7 @@ Sub-prompts for both children are in `prompts/wave1.md`.
2. Merge fwmp through the Wave 4 train immediately, before Wave 2 starts. Wave 2
branches from the merged shape.
3. **xrux investigation** runs concurrently with fwmp, because it is read-only
until it has a verdict: one `cp-recon` writes a characterization test in a
until it has a verdict: one `cp-recon` writes a characterisation test in a
scratch worktree that answers the single question, does `Loader.overlayFile`
zero omitted fields of a map-valued entry. It returns the verdict and the
test, and nothing else. The verdict decides the i3qm lane's stages.
@@ -328,12 +332,12 @@ Sub-prompts for both children are in `prompts/wave1.md`.
One top-level call, `runs.lanes`, `worktree: true` on every writer stage,
`baseRef: "HEAD"` resolved after fwmp merged. Four lanes, concurrency 4.
| Lane | Beads | Stages |
|------|-------|--------|
| `live` | nwa0 | red, green, self-gate, challenge |
| `recovery` | 6zw0 | red, green, self-gate, challenge |
| `steps` | 8szi | red, green, self-gate, challenge |
| `config` | xrux then i3qm | verdict-apply, red, green, self-gate, challenge |
| Lane | Beads | Stages |
| ---------- | -------------- | ----------------------------------------------- |
| `live` | nwa0 | red, green, self-gate, challenge |
| `recovery` | 6zw0 | red, green, self-gate, challenge |
| `steps` | 8szi | red, green, self-gate, challenge |
| `config` | xrux then i3qm | verdict-apply, red, green, self-gate, challenge |
Stage contract, enforced by `wave2.js` and the `cp-writer` agent definition:
@@ -348,10 +352,10 @@ Stage contract, enforced by `wave2.js` and the `cp-writer` agent definition:
and tail, plus the gate-gaming counters. Never `task check`. The evidence
comes from the host, so a child cannot report a pass it did not get.
- **challenge**: `resume: "previous"` against the same writer, with the
adversarial prompt built into `wave2.js`'s challenge stage. The writer still holds the
context; a fresh child pays for that context twice. Only resume a child
`children.list` reports as `resumable`; otherwise start a same-role fallback
and label it a fallback.
adversarial prompt built into `wave2.js`'s challenge stage. The writer still
holds the context; a fresh child pays for that context twice. Only resume a
child `children.list` reports as `resumable`; otherwise start a same-role
fallback and label it a fallback.
Each lane's writer also returns the evidence handoff in `wave2.js`: intent,
non-goals, files with reasons, alternatives rejected, commands run with pasted
@@ -361,12 +365,14 @@ remains rather than growing further.
Every writer opens by printing `pwd`, `git branch --show-current` and
`git status --short`, and repeats that evidence in its final report. A worker
that finishes in the wrong checkout looks exactly like a worker that did nothing.
that finishes in the wrong checkout looks exactly like a worker that did
nothing.
A failed stage blocks only its lane. Do not repair a lane by hand and do not fall
back to running the work yourself, `pi -ne`, or an external CLI: a child launch
or tooling failure is a lane infrastructure blocker, so report the exact failure,
the run status, and the worktree state, then retry through the same path.
A failed stage blocks only its lane. Do not repair a lane by hand and do not
fall back to running the work yourself, `pi -ne`, or an external CLI: a child
launch or tooling failure is a lane infrastructure blocker, so report the exact
failure, the run status, and the worktree state, then retry through the same
path.
---
@@ -378,13 +384,13 @@ angles live in that script: `bead`, `invariant`, `contract`, `deadfield`,
`boundary`, `operator`, `tests`, `gaming`, `intent`, plus `claims` for auditing
recon findings.
| After | Targets | Angles |
|-------|---------|--------|
| Wave 0 | the recon findings themselves | `claims` |
| Wave 1 | `cp/shape` | full set |
| Wave 2 | the four lane branches | full set |
| Wave 4 | merged `main` | `boundary`, `deadfield`, `contract` |
| Wave 5 | the eju6 branch | `tests`, `operator`, `intent` |
| After | Targets | Angles |
| ------ | ----------------------------- | ----------------------------------- |
| Wave 0 | the recon findings themselves | `claims` |
| Wave 1 | `cp/shape` | full set |
| Wave 2 | the four lane branches | full set |
| Wave 4 | merged `main` | `boundary`, `deadfield`, `contract` |
| Wave 5 | the eju6 branch | `tests`, `operator`, `intent` |
The Wave 0 audit is the cheapest of these and catches the most: a recon child
that measures correctly can still carry a wrong conclusion into your lane plan,
@@ -425,22 +431,23 @@ One branch at a time, in dependency order, in the captain checkout at
`fix(config): ...`). Include generated assets under `ui/dist/` in the same
commit; they are LAW, never reverted or ignored.
6. `bd close <id>`. Do not stage `.beads/`.
7. Verify it landed: `git log --oneline -1`, then
`git branch --no-merged main`. Done has three states: no commits, committed
and unmerged, merged. Only the third counts.
7. Verify it landed: `git log --oneline -1`, then `git branch --no-merged main`.
Done has three states: no commits, committed and unmerged, merged. Only the
third counts.
Your own edits get the same gate as the children's. A coordinator `sed` broke the
build on this repo once and nobody else reviews your diffs.
Your own edits get the same gate as the children's. A coordinator `sed` broke
the build on this repo once and nobody else reviews your diffs.
---
## 12. Wave 5: eju6
Sub-prompt in `prompts/wave5-eju6.md`. Last, against merged `main`. One lane: an end-to-end test that drives a change
through the API, restarts a process, and asserts the change survived. Not a unit
test, and not a rewrite of `internal/app/controlplane/controlplane_test.go`,
which covers seeding and catalog only. This is the proof the whole feature works
across a restart, which nothing currently provides.
Sub-prompt in `prompts/wave5-eju6.md`. Last, against merged `main`. One lane: an
end-to-end test that drives a change through the API, restarts a process, and
asserts the change survived. Not a unit test, and not a rewrite of
`internal/app/controlplane/controlplane_test.go`, which covers seeding and
catalogue only. This is the proof the whole feature works across a restart,
which nothing currently provides.
If it fails, that is a finding about the feature, not about the test. Report it
and stop rather than weakening the assertion.
@@ -451,7 +458,7 @@ and stop rather than weakening the assertion.
- Beads closed, with the commit that closed each one.
- Beads deliberately not attempted, and why.
- `task check` result on final `main`, quoted, not summarized.
- `task check` result on final `main`, quoted, not summarised.
- Every branch still unmerged, and whether it holds work.
- Commits now local and unpushed (`git log --oneline origin/main..main`), stated
as fact without pushing.
@@ -22,13 +22,13 @@ briefs — none of the archie specifics here transfer.
Seven tracker items, one shared shape, four lanes, a review pass after every
wave, a serial merge train.
| File | Note |
|------|------|
| `00-orchestrator.md` | The filled orchestrator prompt. Section 2 is the project's ground truth, section 5a the review-is-the-constraint doctrine, section 10 the review cadence. |
| `lanes.json` | Lane briefs carrying intent, traps and `file:line` premises. Read one to see the level of detail a brief needs. |
| `prompts/wave1.md` | The shared shape, plus an investigation whose verdict gated another lane. |
| `prompts/wave4-merge-train.md` | The serial merge procedure with the project's own hazards in it. |
| `agents/` | The three agent definitions with project invariants inlined. |
| File | Note |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `00-orchestrator.md` | The filled orchestrator prompt. Section 2 is the project's ground truth, section 5a the review-is-the-constraint doctrine, section 10 the review cadence. |
| `lanes.json` | Lane briefs carrying intent, traps and `file:line` premises. Read one to see the level of detail a brief needs. |
| `prompts/wave1.md` | The shared shape, plus an investigation whose verdict gated another lane. |
| `prompts/wave4-merge-train.md` | The serial merge procedure with the project's own hazards in it. |
| `agents/` | The three agent definitions with project invariants inlined. |
No scripts are copied here. This run's `wave0.js`, `wave2.js`, `review.js` and
`gate-evidence.sh` became `templates/recon.js`, `templates/lanes.js`,
@@ -15,15 +15,15 @@ parent `archie-agent-fleet` skill. A run in another repository uses that skill's
## Files
| File | What it is |
|------|------------|
| `00-orchestrator.md` | The prompt you give pi. It owns the waves, the ceilings and the verification rules. |
| *(the scripts)* | This run's `wave0.js`, `wave2.js`, `review.js` and `gate-evidence.sh` are **not copied here**: they live on as `templates/recon.js`, `templates/lanes.js`, `templates/review.js` and `scripts/gate-evidence.sh` under `~/.agents/skills/high-throughput-programming/`, which are normative. The snapshot's copies were stale, so they were deleted rather than duplicated. |
| `lanes.json` | Lane definitions: worktree paths, branches, beads, scoped test commands, briefs. Fill in the model id. |
| `prompts/wave1.md` | fwmp shape-first writer, and the xrux verdict probe. |
| `prompts/wave4-merge-train.md` | The serial merge procedure and the landing checks. |
| `prompts/wave5-eju6.md` | The end-to-end restart test. |
| `agents/cp-recon.md`, `agents/cp-writer.md`, `agents/cp-reviewer.md` | Project-scope agent definitions, as the run used them from `.pi/agents/`; these committed copies sit beside this file. |
| File | What it is |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `00-orchestrator.md` | The prompt you give pi. It owns the waves, the ceilings and the verification rules. |
| _(the scripts)_ | This run's `wave0.js`, `wave2.js`, `review.js` and `gate-evidence.sh` are **not copied here**: they live on as `templates/recon.js`, `templates/lanes.js`, `templates/review.js` and `scripts/gate-evidence.sh` under `~/.agents/skills/high-throughput-programming/`, which are normative. The snapshot's copies were stale, so they were deleted rather than duplicated. |
| `lanes.json` | Lane definitions: worktree paths, branches, beads, scoped test commands, briefs. Fill in the model id. |
| `prompts/wave1.md` | fwmp shape-first writer, and the xrux verdict probe. |
| `prompts/wave4-merge-train.md` | The serial merge procedure and the landing checks. |
| `prompts/wave5-eju6.md` | The end-to-end restart test. |
| `agents/cp-recon.md`, `agents/cp-writer.md`, `agents/cp-reviewer.md` | Project-scope agent definitions, as the run used them from `.pi/agents/`; these committed copies sit beside this file. |
## Start it
@@ -94,7 +94,7 @@ writers here. Two limits bite first:
that has to land alone first. Five workers each adding a field to one struct
cost eight cleanup commits on this repo in July.
2. **The machine.** 16 cores, 117 Go packages, and `task check` also runs the
dashboard tests. One full gate saturates the host, so the gate is serialized
dashboard tests. One full gate saturates the host, so the gate is serialised
into the merge train and writers run package-scoped tests.
The throughput comes from recon and review: 25 recon children, then a review
@@ -1,6 +1,8 @@
---
name: cp-recon
description: Read-only recon on archie-core. Traces call sites, extracts spec clauses, inventories tests. Returns citations, never conclusions.
description:
Read-only recon on archie-core. Traces call sites, extracts spec clauses,
inventories tests. Returns citations, never conclusions.
tools: read, grep, find, ls, bash
excludeTools: write, edit
acceptanceRole: read-only
@@ -12,16 +14,26 @@ thinking: high
systemPromptMode: replace
---
You are a read-only investigator in the archie-core Go repository. You measure; you do not decide.
You are a read-only investigator in the archie-core Go repository. You measure;
you do not decide.
Rules:
- Never edit, write, stage, commit, or run anything that mutates the tree. `bash` is for `git log`, `grep`, `go list`, `bd show`, and timing commands only.
- Every claim carries `file:line`. A claim without a citation is not a finding, it is a guess.
- Report facts. The orchestrator draws the conclusion. Do not recommend a course of action unless you were asked for one, and never close or reopen a bead.
- Grep first, then read only the lines that matter. Do not pull whole packages into context.
- Never edit, write, stage, commit, or run anything that mutates the tree.
`bash` is for `git log`, `grep`, `go list`, `bd show`, and timing commands
only.
- Every claim carries `file:line`. A claim without a citation is not a finding,
it is a guess.
- Report facts. The orchestrator draws the conclusion. Do not recommend a course
of action unless you were asked for one, and never close or reopen a bead.
- Grep first, then read only the lines that matter. Do not pull whole packages
into context.
- Directory and bead names are not evidence of coupling. Check the imports.
- `ARCHITECTURE.md` and `CLAUDE.md` are stale by construction in this repo. The tree is the only evidence of current state; when a doc and the code disagree, report both and say which file you read.
- If your task's premise is false, say so plainly as your first line instead of answering the question you were asked.
- `ARCHITECTURE.md` and `CLAUDE.md` are stale by construction in this repo. The
tree is the only evidence of current state; when a doc and the code disagree,
report both and say which file you read.
- If your task's premise is false, say so plainly as your first line instead of
answering the question you were asked.
Finish with your structured output. Keep prose under 40 lines; long inventories belong in your output file.
Finish with your structured output. Keep prose under 40 lines; long inventories
belong in your output file.
@@ -1,6 +1,8 @@
---
name: cp-reviewer
description: Read-only adversarial reviewer for one archie-core lane and one angle. Evidence-labelled findings and a single merge verdict.
description:
Read-only adversarial reviewer for one archie-core lane and one angle.
Evidence-labelled findings and a single merge verdict.
tools: read, grep, find, ls, bash
excludeTools: write, edit
acceptanceRole: read-only
@@ -12,23 +14,35 @@ thinking: high
systemPromptMode: replace
---
You review one lane of archie-core work from one angle. You did not write this code and you do not fix it.
You review one lane of archie-core work from one angle. You did not write this
code and you do not fix it.
Start from `git diff main..<branch>` and `git diff --stat main..<branch>`. Review the diff, never the writer's transcript: the transcript costs context and carries almost no signal.
Start from `git diff main..<branch>` and `git diff --stat main..<branch>`.
Review the diff, never the writer's transcript: the transcript costs context and
carries almost no signal.
What you are looking for, in order:
1. Behaviour the change dropped while keeping the shape. Refactors lose guards. Read every new or changed doc comment: one that describes a silent fallback is usually a confession.
1. Behaviour the change dropped while keeping the shape. Refactors lose guards.
Read every new or changed doc comment: one that describes a silent fallback
is usually a confession.
2. A claim in the diff that the code does not support.
3. A test that restates an assignment or a constant instead of failing for an interesting reason.
3. A test that restates an assignment or a constant instead of failing for an
interesting reason.
4. Two sides that must agree and have no test tying them together.
Rules:
- Read-only. Do not edit, stage, commit, or fix. Propose the fix in words.
- Every finding carries `file:line` and a quoted proof.
- Label by evidence, not by how bad it sounds: P0 breaks a user-reachable path or an invariant, P1 is a real defect with a bounded blast radius, P2 is worth fixing but not now.
- "No finding" is a valid and useful answer. Do not manufacture findings to look thorough.
- `task check` passing is not evidence of correctness: it cannot see a field the server stopped sending, because optional chaining makes a dead dashboard binding typecheck.
- Label by evidence, not by how bad it sounds: P0 breaks a user-reachable path
or an invariant, P1 is a real defect with a bounded blast radius, P2 is worth
fixing but not now.
- "No finding" is a valid and useful answer. Do not manufacture findings to look
thorough.
- `task check` passing is not evidence of correctness: it cannot see a field the
server stopped sending, because optional chaining makes a dead dashboard
binding typecheck.
End with exactly one line: `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`.
End with exactly one line: `Merge verdict: BLOCK`, `Merge verdict: OK`, or
`Merge verdict: OK with notes`.
@@ -1,6 +1,8 @@
---
name: cp-writer
description: Implementation worker for archie-core lanes. Red-green TDD in an isolated worktree, package-scoped gate, no suppression.
description:
Implementation worker for archie-core lanes. Red-green TDD in an isolated
worktree, package-scoped gate, no suppression.
tools: read, write, edit, grep, find, ls, bash
acceptanceRole: writer
inheritProjectContext: true
@@ -11,28 +13,43 @@ timeoutMs: 5400000
systemPromptMode: replace
---
You implement one lane of work in the archie-core Go repository, inside your own git worktree.
You implement one lane of work in the archie-core Go repository, inside your own
git worktree.
Open every run by printing `pwd`, `git branch --show-current` and `git status --short`, and repeat all three in your final report. A worker that finishes in the wrong checkout looks exactly like one that did nothing.
Open every run by printing `pwd`, `git branch --show-current` and
`git status --short`, and repeat all three in your final report. A worker that
finishes in the wrong checkout looks exactly like one that did nothing.
Method:
1. Read the bead with `bd show <id>`, then `CLAUDE.md` and `docs/architecture/organisation.md`.
2. Red: write the failing table-driven test first. Run it. Paste the failure. Confirm it fails on an assertion, not a compile error. A test that cannot fail for an interesting reason is noise in the gate.
1. Read the bead with `bd show <id>`, then `CLAUDE.md` and
`docs/architecture/organisation.md`.
2. Red: write the failing table-driven test first. Run it. Paste the failure.
Confirm it fails on an assertion, not a compile error. A test that cannot
fail for an interesting reason is noise in the gate.
3. Green: the minimal implementation that satisfies the test.
4. Run your lane's scoped test command. Never run `task check`: it saturates the machine and the merge train owns it.
5. Commit on your lane branch with a conventional-commit subject scoped by package (`feat(controlplane): ...`).
4. Run your lane's scoped test command. Never run `task check`: it saturates the
machine and the merge train owns it.
5. Commit on your lane branch with a conventional-commit subject scoped by
package (`feat(controlplane): ...`).
Hard rules:
- Fix invalid state at the producer, not with a defensive check at the consumer.
- Never suppress: no `//nolint`, no `t.Skip`, no build tag that hides a failing test, no deleted assertion. If a lint is wrong, leave it failing and say why.
- Never suppress: no `//nolint`, no `t.Skip`, no build tag that hides a failing
test, no deleted assertion. If a lint is wrong, leave it failing and say why.
- Adopt `task fmt` output verbatim. Never revert a formatter or linter diff.
- Two failed fixes on the same logic block means you rewrite the block, not patch it a third time. Prefer a clean 20-line rewrite over a 5-line band-aid.
- Dependency flow is `cmd -> app -> {domain, infrastructure}`, with infrastructure implementing domain contracts. Nothing in `internal/webui` may reach `internal/domain/workflow`.
- Two failed fixes on the same logic block means you rewrite the block, not
patch it a third time. Prefer a clean 20-line rewrite over a 5-line band-aid.
- Dependency flow is `cmd -> app -> {domain, infrastructure}`, with
infrastructure implementing domain contracts. Nothing in `internal/webui` may
reach `internal/domain/workflow`.
- Do not widen scope. Work not asked for is a finding to report, not work to do.
- Do not merge, do not push, do not touch `.beads/`, do not edit the main checkout.
- Do not merge, do not push, do not touch `.beads/`, do not edit the main
checkout.
- Scratch files live in `/tmp`. Never in the working tree.
- If the bead describes a world the tree no longer has, stop and report that instead of implementing it.
- If the bead describes a world the tree no longer has, stop and report that
instead of implementing it.
Your final report states: the commit sha, changed files, the scoped test command and its result, what you deliberately did not do, and any residual risk.
Your final report states: the commit sha, changed files, the scoped test command
and its result, what you deliberately did not do, and any residual risk.
@@ -6,9 +6,7 @@
"key": "live",
"dir": "/work/apps/cp-live",
"branch": "cp/live",
"beads": [
"archie-core-nwa0"
],
"beads": ["archie-core-nwa0"],
"test": "go test ./internal/app/controlplane/... ./internal/domain/applystatus/... -count=1 && go vet ./internal/app/controlplane/... ./internal/domain/applystatus/...",
"brief": "Wave 0 and its claims audit corrected this bead's premise, and the correction is the work. There is not one live apply path, there are two, and the PRD clause (Archie starts and checks a replacement before switching, and if the check fails the old one keeps running) applies to both. (1) workflow-execution-settings is applied on a watch (internal/app/archied/control_plane.go:94) and reports apply status at :118. (2) personas is also watched and applied live in the same process (internal/app/archied/gateway_runtime.go:37 watch, :79-86 apply) and reports NO apply status at all, so personas is the live-watched kind that widens this bead. Correction to the earlier version of this brief: workflow-definitions is not applied by a daemon watch, but do not read that as \"no watch anywhere\" -- the webui streams it at internal/webui/api_control_plane.go:139, which is a generic SSE passthrough for any kind. That is a read path, not a component-replacement path, so it does not widen nwa0. What the audit also established: the hard-coded nil at control_plane.go:118 is inert (no path in applyWorkflowExecutionSettings can fail), so do not build the bead around \"the report path cannot carry a rejection\"; that framing is wrong. Order of work: add the build-and-probe step to the live apply path, retain the previous component when the check fails, and report the failure through the apply-status surface. Decide explicitly whether personas gets the same treatment in this bead or a follow-up bead; if it is a follow-up, file the bead rather than half-wiring it. Do NOT fix the watch-reconnect defect opportunistically: it is filed separately as archie-core-yrmr, and a defect found by a review pass must not be silently repaired inside another lane. Apply status is on the State Store contract, not the control plane: PutApplyStatus/ListApplyStatus are administrative, keyed on (process, kind), replaced in place, re-stamped every 30s, stale at 90s, and a stale record renders as \"Not reporting\", never as current. applystatus.New refuses a process name Processes() does not list, deliberately: an invented name would read as a process that is not running, which the PRD blesses as legitimate, so the failure would be invisible."
},
@@ -16,9 +14,7 @@
"key": "recovery",
"dir": "/work/apps/cp-recovery",
"branch": "cp/recovery",
"beads": [
"archie-core-6zw0"
],
"beads": ["archie-core-6zw0"],
"test": "go test ./cmd/... ./internal/infrastructure/staterpc/... -count=1 && go vet ./cmd/...",
"brief": "DECIDED: subcommands of cmd/archie-state-store (backup, restore, validate, rollback). Not a new binary. Sam's standing rule, restated 2026-09-21 and now recorded in docs/architecture/organisation.md#process-boundaries: a cmd/ entry is a process boundary, earned only when a surface fails independently of the rest of the fleet or when that process may need to run in more than one location (HA pair, NAT traversal, separate host). Operational commands over a surface an existing binary already owns are subcommands of it. Do not reopen this. Two premise corrections from Wave 0 that change the work. First, the file is <dir>/archie.db-tasks.sqlite (cmd/archie-state-store/main.go:290-292, asserted at main_test.go:435-439), not archie.db, so a command that operates on 'archie.db' by name operates on nothing. Second, part of this already exists in shell: scripts/archie-update-install:189 takes a sqlite3 .backup of the task database and describes it as the watchdog's only route back from a forward schema migration. That makes this bead partly consolidation. The subcommand becomes the one authoritative implementation and the install script calls it, rather than a Go path and a shell path that drift apart. Changing that script is in scope for this lane; the watchdog's refusal semantics (an update that cannot back up must not start) must survive the change unchanged. The command operates on the database file directly with the State Store stopped, refuses to run against a live store, and adds no rollback RPC: a revision carries its value and restoring replays it through the ordinary replace."
},
@@ -26,9 +22,7 @@
"key": "steps",
"dir": "/work/apps/cp-steps",
"branch": "cp/steps",
"beads": [
"archie-core-8szi"
],
"beads": ["archie-core-8szi"],
"test": "go test ./internal/domain/workflow/... ./internal/app/agentworker/... -count=1 && go vet ./internal/domain/workflow/...",
"brief": "internal/domain/workflow/steps.go:215 and :227 hard-error on legacy .archie/stages/*.go and .archie/gate.go and tell the operator to migrate to a registered YAML workflow step, but BuiltinStepRegistry() only exposes the six shipped workflows' own stages, so there is nothing to migrate to. Identify what the removed hooks actually did and land the equivalent as registered step types. This lane starts only after archie-core-fwmp has merged, and registers against the extension point fwmp created. Do not re-open the registry design."
},
@@ -36,10 +30,7 @@
"key": "config",
"dir": "/work/apps/cp-config",
"branch": "cp/config",
"beads": [
"archie-core-xrux",
"archie-core-i3qm"
],
"beads": ["archie-core-xrux", "archie-core-i3qm"],
"test": "go test ./internal/infrastructure/configuration/... ./internal/app/archied/... -count=1 && go vet ./internal/infrastructure/configuration/... ./internal/app/archied/...",
"brief": "Two beads in order, one package owner. First archie-core-xrux. The verdict is already measured with evidence (Wave 0R claims audit c6) and it is ZEROES: the -config-overlay file path silently drops every field a partial map-valued entry omits, which is exactly the archie-core-e2e2 hazard, and it is user-reachable because deployments/dev.toml is the documented -config-overlay argument and sets [services.state] target/listen, while the base config.toml is where [services.state].target_token lives -- so the overlay drops the token. The red stage is a committed characterization test through the production entry point (Loader.Resolve / -config-overlay) that loads a config with a populated map-valued entry, overlays a file setting one sibling key, and asserts the omitted keys survive; it fails today. Then move apply.go's foldOverrides (apply.go:60) onto the file overlay path (loader.go:161-194, decode at :176) so it passes. Do NOT delete apply.go, apply_test.go or Loader.ApplyOverlay: the hazard they were written for is live on that path. No dotted-path field merge is wanted beyond this guard, because the control plane replaces whole documents. Then archie-core-i3qm, whose anchor and scope the audit corrected. control_plane.go:13 is a blank line (the doc comment is :14-18); the calls moved to :20 (RuntimeConfig) and :27 (configuration.Validate) in 9accf112. More importantly the PRD clause names State Store startup, and state_store.go:75-104 never calls runtimeConfig: it reaches Loader.finalize via bootstrap.go:263 (the loader.Resolve call site, not finalize itself) and loader.go:341-346, where Validate runs. Scope correction: that file-only Validate runs before loadRuntimeConfig for ALL THREE binaries (main.go:358, gateway.go:61, state_store.go:78), so it is not state-store-specific; and a value that is valid alone but invalid only after the DB merge never blocks the state store at all, because it is imported unvalidated at state_store.go:104 and fails later in the daemon's loadRuntimeConfig (control_plane.go:27). Reduce the bootstrap document to the fields the PRD lists (database path, listen addresses, credentials, TLS, encryption-key references) and stop validating the migrated surface at startup, so a stale TOML value in a database-owned field cannot fail boot. boot.runtimeConfig is the one layering call and the SIGHUP callback makes the same call: if you add a database-owned layer, add it there and nowhere else."
}
@@ -1,19 +1,20 @@
# Wave 1 sub-prompt: shape first
**One child. fwmp alone.** Nothing else runs until it merges, and Wave 2 branches
from the merged shape.
**One child. fwmp alone.** Nothing else runs until it merges, and Wave 2
branches from the merged shape.
xrux is no longer a Wave 1 probe. Its verdict is already measured with evidence
(Wave 0R claims audit c6) and the answer is **ZEROES**. Re-measuring buys nothing,
so the characterization test is folded into the `config` lane's red stage, where
it is committed and the evidence lives in the tree rather than in a transcript.
See the `config` brief in `lanes.json`.
(Wave 0R claims audit c6) and the answer is **ZEROES**. Re-measuring buys
nothing, so the characterisation test is folded into the `config` lane's red
stage, where it is committed and the evidence lives in the tree rather than in a
transcript. See the `config` brief in `lanes.json`.
---
## fwmp: the shared shape (cp-writer, worktree `/work/apps/cp-shape`, branch `cp/shape`)
Gate: `go test ./internal/domain/workflow/... ./internal/app/controlplane/... ./internal/app/agentworker/... -count=1`
Gate:
`go test ./internal/domain/workflow/... ./internal/app/controlplane/... ./internal/app/agentworker/... -count=1`
```text
Bead archie-core-fwmp. Run `bd show archie-core-fwmp` first.
@@ -29,7 +29,11 @@ Then:
1. `git merge --no-ff $BR` (or apply the lane's handoff patch if the lane ran in
a managed worktree).
2. `task build --force`, then `task check`, once, alone. Nothing else runs on this machine while it does. The force-build is required until archie-core-hhgw lands: `task build`'s sources are Go-only (Taskfile.yml:325), so a ui/dist-only change does not retrigger it and a stale embedded dashboard would ship (Wave 0R audit c10).
2. `task build --force`, then `task check`, once, alone. Nothing else runs on
this machine while it does. The force-build is required until
archie-core-hhgw lands: `task build`'s sources are Go-only
(Taskfile.yml:325), so a ui/dist-only change does not retrigger it and a
stale embedded dashboard would ship (Wave 0R audit c10).
3. On failure: one fix pass back to that lane's retained writer with the real
output pasted in, not a summary. On a second failure, `git reset --hard` the
merge, requeue the lane, and move to the next branch. Do not stack a third
@@ -3,8 +3,8 @@
One lane, one `cp-writer`, against merged `main`. This is the only bead that
proves the feature rather than adding to it, so it runs last and alone.
Gate: `cd <worktree> && go test ./internal/app/controlplane/... -count=1`,
then `task check` through the merge train as usual.
Gate: `cd <worktree> && go test ./internal/app/controlplane/... -count=1`, then
`task check` through the merge train as usual.
```text
Bead archie-core-eju6. Run `bd show archie-core-eju6` first.
@@ -2,13 +2,13 @@
name: archie-architecture-contract
description: >-
Protect Archie's load-bearing architecture while placing, implementing, or
reviewing behavior. Load this skill before changing daemon composition,
reviewing behaviour. Load this skill before changing daemon composition,
domains, workflows, task lifecycle, agent execution, messaging, work intake,
identity, memory, configuration, plugins, policies, persistence, NATS/RPC,
containers, or process boundaries; use it when deciding where new code
belongs, enforcing dependency direction, separating current runtime truth
from the approved target and open migration decisions, or ensuring every
behavior has one authoritative path. Route proof of duplication, dead-code
behaviour has one authoritative path. Route proof of duplication, dead-code
disposition, production reachability, and maintainability to
archie-technical-accountability.
---
@@ -16,15 +16,15 @@ description: >-
# Archie Architecture Contract
Treat architecture as executable safety policy. Preserve one understandable
owner and one production path for each behavior.
owner and one production path for each behaviour.
## Read status before code
| Label | Meaning | Authority |
| --- | --- | --- |
| **CURRENT** | Behavior present in live code and production composition as of 2026-09-18. | Code, tests, and `internal/app/archied` wiring (`cmd/archied/main.go` is a thin dispatcher) |
| **APPROVED TARGET** | Direction an implementation must approach, but which may not exist on disk. | `docs/prds/01-project-management.md` and documents whose status says approved |
| **OPEN** | A migration or API decision no implementer may invent locally. | `docs/architecture/migration-decisions.md` and documents marked in progress or under design |
| Label | Meaning | Authority |
| ------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **CURRENT** | Behaviour present in live code and production composition as of 2026-09-18. | Code, tests, and `internal/app/archied` wiring (`cmd/archied/main.go` is a thin dispatcher) |
| **APPROVED TARGET** | Direction an implementation must approach, but which may not exist on disk. | `docs/prds/01-project-management.md` and documents whose status says approved |
| **OPEN** | A migration or API decision no implementer may invent locally. | `docs/architecture/migration-decisions.md` and documents marked in progress or under design |
> **Do not implement target prose as though it describes current code.**
> Before treating a target package as available, prove that it exists and is
@@ -35,9 +35,9 @@ owner and one production path for each behavior.
Resolve apparent disagreement in this order:
1. Read live code and production composition for CURRENT behavior.
1. Read live code and production composition for CURRENT behaviour.
2. Read `docs/prds/01-project-management.md` for APPROVED TARGET ownership.
3. Read the focused decision document for the selected behavior.
3. Read the focused decision document for the selected behaviour.
4. Read `docs/architecture/migration-decisions.md` for OPEN work.
5. Stop and use `archie-architecture-planning-campaign` if a required semantic
decision remains open.
@@ -56,20 +56,20 @@ Also: `cmd/archied/main.go` is a thin dispatcher; the wiring lives in
Do not simplify these facts into the target model:
| Concern | CURRENT runtime truth on 2026-09-18 | Evidence |
| --- | --- | --- |
| Composition | `cmd/archied/main.go` dispatches to `internal/app/archied.Run()`, which performs construction and wiring in `bootstrap.go`. | `cmd/archied/main.go`; `internal/app/archied/` |
| Durable work | `task.Task` combines forge/chat source data, workflow position, output, retry, identity, and PR state. | `internal/domain/workflow/task/task.go`; `internal/domain/storecontract/storecontract.go` |
| Workflow | `internal/domain/workflow` routes a `task.Task` into a `map[string]Workflow`, mutates a broad `TaskContext` through sequential stages. | `internal/domain/workflow/workflow.go` |
| Agent-stage boundary | Versioned `agentexec.Request`/`Result` carries one autonomous stage; validation correlates task, attempt, and stage. | `internal/agentexec/protocol.go` |
| Container handoff | `internal/taskrun` carries entire task plus `config.Repo` and `config.TaskConfig`; `internal/app/agentworker` owns routing and sequencing while its NATS adapter owns wire mechanics. | `internal/taskrun/taskrun.go`; `internal/app/agentworker/`; `internal/infrastructure/agenttransport/nats/` |
| Git ownership | Daemon-owned worktree operations clone, commit, push, diff, and clean up. | `internal/worktree/`; `internal/domain/workflow/steps.go`; `docs/architecture/agent-system.md` |
| Enforcement | Gates, read-only/protected paths, TDD inverted test gates, and diff caps are represented outside prompt prose. | `internal/gate/`; `internal/domain/workflow/{agent,tdd,steps}.go` |
| Configuration | `internal/config.Config`, `IdentityConfig`, `Repo`, and task snapshots mix input decoding with runtime concerns. Decoding itself lives in `internal/infrastructure/configuration`. | `internal/config/config.go`; `internal/infrastructure/configuration/` |
| Identity | Configured names and bot usernames act as process-local identity keys. There is no durable Identity domain. | `internal/daemon/daemon.go`; `internal/domain/storecontract/storecontract.go`; `internal/gateway/session.go` |
| Messaging | `internal/gateway` contains both the `Message` struct flow and richer `MessageEvent`; channel routing and task control are mixed with conversational behavior. | `internal/gateway/{gateway,messageevent,tasks}.go`; `internal/channels/` |
| Plugins | `plugin.Plugin` exposes only `Name` and `Version`; current loading interprets operator-installed Go files with Yaegi. | `internal/plugin/plugin.go` |
| Processes | Agent modes include in-process, subprocess, and NATS. Optional containers add a distinct boundary with known gaps. | `internal/config/config.go`; `internal/app/archied/`; `docs/architecture/organisation.md` |
| Concern | CURRENT runtime truth on 2026-09-18 | Evidence |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Composition | `cmd/archied/main.go` dispatches to `internal/app/archied.Run()`, which performs construction and wiring in `bootstrap.go`. | `cmd/archied/main.go`; `internal/app/archied/` |
| Durable work | `task.Task` combines forge/chat source data, workflow position, output, retry, identity, and PR state. | `internal/domain/workflow/task/task.go`; `internal/domain/storecontract/storecontract.go` |
| Workflow | `internal/domain/workflow` routes a `task.Task` into a `map[string]Workflow`, mutates a broad `TaskContext` through sequential stages. | `internal/domain/workflow/workflow.go` |
| Agent-stage boundary | Versioned `agentexec.Request`/`Result` carries one autonomous stage; validation correlates task, attempt, and stage. | `internal/agentexec/protocol.go` |
| Container handoff | `internal/taskrun` carries entire task plus `config.Repo` and `config.TaskConfig`; `internal/app/agentworker` owns routing and sequencing while its NATS adapter owns wire mechanics. | `internal/taskrun/taskrun.go`; `internal/app/agentworker/`; `internal/infrastructure/agenttransport/nats/` |
| Git ownership | Daemon-owned worktree operations clone, commit, push, diff, and clean up. | `internal/worktree/`; `internal/domain/workflow/steps.go`; `docs/architecture/agent-system.md` |
| Enforcement | Gates, read-only/protected paths, TDD inverted test gates, and diff caps are represented outside prompt prose. | `internal/gate/`; `internal/domain/workflow/{agent,tdd,steps}.go` |
| Configuration | `internal/config.Config`, `IdentityConfig`, `Repo`, and task snapshots mix input decoding with runtime concerns. Decoding itself lives in `internal/infrastructure/configuration`. | `internal/config/config.go`; `internal/infrastructure/configuration/` |
| Identity | Configured names and bot usernames act as process-local identity keys. There is no durable Identity domain. | `internal/daemon/daemon.go`; `internal/domain/storecontract/storecontract.go`; `internal/gateway/session.go` |
| Messaging | `internal/gateway` contains both the `Message` struct flow and richer `MessageEvent`; channel routing and task control are mixed with conversational behaviour. | `internal/gateway/{gateway,messageevent,tasks}.go`; `internal/channels/` |
| Plugins | `plugin.Plugin` exposes only `Name` and `Version`; current loading interprets operator-installed Go files with Yaegi. | `internal/plugin/plugin.go` |
| Processes | Agent modes include in-process, subprocess, and NATS. Optional containers add a distinct boundary with known gaps. | `internal/config/config.go`; `internal/app/archied/`; `docs/architecture/organisation.md` |
### Interpret the current lifecycle honestly
@@ -88,25 +88,25 @@ reconciliation, parking/retry/exhaustion, and crash recovery. Read
`Store.Transition(ctx, taskID, from, to, detail)` now guards on `from`
(`WHERE id=? AND status=?`, returning `store.ErrStaleTransition` on mismatch)
and runs the status update plus the transition-history insert in one
transaction (`internal/store/store.go`). The sentinel crosses the State Store
transaction (`internal/infrastructure/postgres/store.go`). The sentinel crosses the State Store
gRPC boundary via `mapError`/`unmapError` in
`internal/infrastructure/staterpc/values.go`; its canonical message string is
part of the wire contract. Earlier non-atomic behavior is the settled fix,
part of the wire contract. Earlier non-atomic behaviour is the settled fix,
not an open design.
## Preserve the load-bearing invariants
| Invariant | Required action | Status and source |
| --- | --- | --- |
| The model never runs git | Keep clone, branch, commit, push, diff, and cleanup in deterministic workspace/worktree steps. | CURRENT: `docs/architecture/agent-system.md`; `internal/worktree/` |
| Deterministic constraints outrank prompts | Enforce gates, protected paths, read-only stages, test protection, and change caps outside model instructions. | CURRENT: `docs/architecture/agent-system.md`; `internal/gate/`; `internal/domain/workflow/` |
| Agent execution is a data boundary | Send bounded, versioned input; validate correlated output before applying it. | CURRENT foundation: `internal/agentexec/protocol.go`; `docs/architecture/agent-system.md` |
| Every workflow ends explicitly | Preserve terminal outcome or visible park. Preserve crash recovery of interrupted `running` work. | CURRENT: `internal/domain/workflow/workflow.go`; `internal/store/store.go` |
| Generic plugins stay metadata-only | Keep `plugin.Plugin` at `Name()`/`Version()`. Behavior on typed capability interface with owning `Registry`/`Manager`. | CURRENT-enforced rule: `internal/plugin/architecture_test.go` |
| Capability engines own lifecycle | Give resource-owning engines explicit start/health/stop semantics and failure isolation. | APPROVED rule: `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict` |
| Trust is explicit | Treat trusted operator-installed in-process code, repository code, out-of-process integrations, and container-isolated code as different trust classes. | APPROVED rule: `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict` |
| Infrastructure stays replaceable | Keep forge, persistence, workspace, transport, container, and model details behind behavior-owned contracts. | APPROVED TARGET: `docs/architecture/dependencies-and-contracts.md` |
| Same-repository execution serializes by default | Preserve default unless explicit scheduling policy permits concurrency. | CURRENT: `internal/config/config.go`; `internal/daemon/daemon.go` |
| Invariant | Required action | Status and source |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| The model never runs git | Keep clone, branch, commit, push, diff, and cleanup in deterministic workspace/worktree steps. | CURRENT: `docs/architecture/agent-system.md`; `internal/worktree/` |
| Deterministic constraints outrank prompts | Enforce gates, protected paths, read-only stages, test protection, and change caps outside model instructions. | CURRENT: `docs/architecture/agent-system.md`; `internal/gate/`; `internal/domain/workflow/` |
| Agent execution is a data boundary | Send bounded, versioned input; validate correlated output before applying it. | CURRENT foundation: `internal/agentexec/protocol.go`; `docs/architecture/agent-system.md` |
| Every workflow ends explicitly | Preserve terminal outcome or visible park. Preserve crash recovery of interrupted `running` work. | CURRENT: `internal/domain/workflow/workflow.go`; `internal/infrastructure/postgres/store.go` |
| Generic plugins stay metadata-only | Keep `plugin.Plugin` at `Name()`/`Version()`. Behaviour on typed capability interface with owning `Registry`/`Manager`. | CURRENT-enforced rule: `internal/plugin/architecture_test.go` |
| Capability engines own lifecycle | Give resource-owning engines explicit start/health/stop semantics and failure isolation. | APPROVED rule: `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict` |
| Trust is explicit | Treat trusted operator-installed in-process code, repository code, out-of-process integrations, and container-isolated code as different trust classes. | APPROVED rule: `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict` |
| Infrastructure stays replaceable | Keep forge, persistence, workspace, transport, container, and model details behind behaviour-owned contracts. | APPROVED TARGET: `docs/architecture/dependencies-and-contracts.md` |
| Same-repository execution serialises by default | Preserve default unless explicit scheduling policy permits concurrency. | CURRENT: `internal/config/config.go`; `internal/daemon/daemon.go` |
Run the mechanical plugin guard after changing any plugin or `*Engine`
interface:
@@ -129,7 +129,7 @@ domain and shared application contracts <- infrastructure implementations
application composition
```
1. Put cohesive behavior, vocabulary, state, commands, events, policies,
1. Put cohesive behaviour, vocabulary, state, commands, events, policies,
runtime settings, and required service interfaces with its owning domain.
2. Make infrastructure implement domain-required interfaces and translate
external representations.
@@ -149,7 +149,7 @@ channel-neutral Message -> Agent turn -> optional proposed work
```
- **Messaging** owns canonical messages, conversations, branches, channel correlation, delivery.
- **Agent** owns persistent assistant, continuity, specialization, memory.
- **Agent** owns persistent assistant, continuity, specialisation, memory.
- **Work Intake** owns admission, validation, routing, accepted-work-request handoff.
- **Workflow** owns versioned definitions, steps, executions, attempts, outcomes.
@@ -164,12 +164,12 @@ Sources: `docs/architecture/migration-decisions.md`,
Use immutable `IdentityID` for target attribution. Keep Identity separate from
Agent. Four fixed memory scopes:
| Scope | Visibility |
| --- | --- |
| Global shared | Shared across Archie |
| Agent-wide | One Agent across users; private by default |
| User-wide | One user across authorized Agents |
| Agent-user relationship | Exactly one Agent and one user |
| Scope | Visibility |
| ----------------------- | ------------------------------------------ |
| Global shared | Shared across Archie |
| Agent-wide | One Agent across users; private by default |
| User-wide | One user across authorised Agents |
| Agent-user relationship | Exactly one Agent and one user |
Do not use conversation branching as a fifth memory scope.
@@ -184,53 +184,53 @@ Treat `internal/config` as migration source inventory:
- let each domain or plugin own typed runtime settings;
- translate external DTOs in `internal/app`;
- never pass complete application config into a domain;
- classify each behavioral value as invariant, runtime setting, policy value,
- classify each behavioural value as invariant, runtime setting, policy value,
derived value, or runtime state.
Source: `docs/architecture/configuration.md`.
## Place new behavior deliberately
## Place new behaviour deliberately
| Behavior | Target owner/location | Decision gate |
| --- | --- | --- |
| Persistent actor lifecycle and attribution | `internal/domain/identity` | Do not mix authentication/access policy into Identity. |
| Persistent assistant behavior and continuity | `internal/domain/agent` | Keep model/provider replaceable; do not fold Workflow into Agent. |
| Workflow definitions, steps, executions, attempts, outcomes | `internal/domain/workflow` | Preserve version ownership and one authoritative lifecycle. |
| Canonical messages, conversations, branches, delivery | `internal/domain/messaging` | Keep platform IDs as external correlation. |
| Admission and deterministic routing of proposed durable work | `internal/domain/workintake` | Emit an accepted request; do not construct execution state. |
| Generic plugin identity/discovery/compatibility/lifecycle | `internal/domain/plugin` | Keep generic contract metadata-only. |
| Capability-specific plugin behavior | Owning domain's typed registry/manager | Never add behavior to `plugin.Plugin`. |
| Broker-neutral publication/subscription mechanics | `internal/eventbus` | Keep message meaning and schemas with their domain. |
| Shared policy evaluation/evidence mechanics | No current package. `internal/policy` was the planned location; as of 2026-09-18 policy lives inside playbook bindings (`playbooks/`, `internal/domain/eda/playbook`) and `internal/gate/`. | Keep policy vocabulary, evaluators, and consequences with consuming domain. |
| NATS, SQLite, forge, config decoding, external SDK adapters | `internal/infrastructure/<capability>` | Implement a narrow owner-defined contract; translate at boundary. |
| Construction, cross-domain connection, startup/shutdown | `internal/app/archied` or `internal/app/agentworker` | Keep `cmd/*` thin; define health and shutdown order. |
| Deploy assembly | `deployments/<assembly>` | Do not move application behavior into deployment files. |
| Unreviewed memory/tools/workspace/gate/storage/web/RPC/scheduling | **OPEN** | Run `archie-architecture-planning-campaign`. |
| Behaviour | Target owner/location | Decision gate |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Persistent actor lifecycle and attribution | `internal/domain/identity` | Do not mix authentication/access policy into Identity. |
| Persistent assistant behaviour and continuity | `internal/domain/agent` | Keep model/provider replaceable; do not fold Workflow into Agent. |
| Workflow definitions, steps, executions, attempts, outcomes | `internal/domain/workflow` | Preserve version ownership and one authoritative lifecycle. |
| Canonical messages, conversations, branches, delivery | `internal/domain/messaging` | Keep platform IDs as external correlation. |
| Admission and deterministic routing of proposed durable work | `internal/domain/workintake` | Emit an accepted request; do not construct execution state. |
| Generic plugin identity/discovery/compatibility/lifecycle | `internal/domain/plugin` | Keep generic contract metadata-only. |
| Capability-specific plugin behaviour | Owning domain's typed registry/manager | Never add behaviour to `plugin.Plugin`. |
| Broker-neutral publication/subscription mechanics | `internal/eventbus` | Keep message meaning and schemas with their domain. |
| Shared policy evaluation/evidence mechanics | No current package. `internal/policy` was the planned location; as of 2026-09-18 policy lives inside playbook bindings (`playbooks/`, `internal/domain/eda/playbook`) and `internal/gate/`. | Keep policy vocabulary, evaluators, and consequences with consuming domain. |
| NATS, PostgreSQL, forge, config decoding, external SDK adapters | `internal/infrastructure/<capability>` | Implement a narrow owner-defined contract; translate at boundary. |
| Construction, cross-domain connection, startup/shutdown | `internal/app/archied` or `internal/app/agentworker` | Keep `cmd/*` thin; define health and shutdown order. |
| Deploy assembly | `deployments/<assembly>` | Do not move application behaviour into deployment files. |
| Unreviewed memory/tools/workspace/gate/storage/web/RPC/scheduling | **OPEN** | Run `archie-architecture-planning-campaign`. |
## Confront known weak points
| Weak point on 2026-09-18 | Required response |
| --- | --- |
| `TaskContext` is a mutable service bag with config, services, policy, scratch state. | Design narrow step inputs and staged removal. |
| Workflow lifecycle split across store, daemon, workflow, gateway, worker. | Trace every writer and reader before changing status. |
| State changes and transition history were non-atomic and `from` was advisory — **settled** in `internal/store`: `Transition` guards on `status=?` and writes status plus history in one transaction. | Keep every status writer behind `Transition`; do not reintroduce a raw `UPDATE tasks SET status`. |
| In-process and container paths put orchestration on different sides of process boundary. | Decide which path survives before extending both. |
| Identity uses strings; task uniqueness/NATS dedup omit identity. | Don't promise multi-identity ownership until canonical IDs migrate. |
| Container RPC uses root forge/worktree, not task owner's identity. | Known trust/correctness defect — not identity-isolated. |
| Missing `task.json` makes `archie-agent` join shared queue. | Fail closed before treating as isolated. |
| Subprocess uses daemon user and host access. | Not a security boundary. |
| Gateway formerly duplicated lifecycle strings, competing message contracts. | No third contract or direct lifecycle mutation path; status constants live in `internal/domain/workflow`. |
| Global config and `IdentityConfig` combine unrelated owners. | Don't rename global structure or add `Extra` map. |
| Memory has fixed scope requirements but OPEN final placement/migration. | Preserve scope isolation; focused design before moving. |
| Tests can make unused/duplicate code appear legitimate. | Prove production reachability from composition. |
| Weak point on 2026-09-18 | Required response |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `TaskContext` is a mutable service bag with config, services, policy, scratch state. | Design narrow step inputs and staged removal. |
| Workflow lifecycle split across store, daemon, workflow, gateway, worker. | Trace every writer and reader before changing status. |
| State changes and transition history were non-atomic and `from` was advisory — **settled** in `internal/infrastructure/postgres`: `Transition` guards on the current status and writes status plus history in one transaction. | Keep every status writer behind `Transition`; do not reintroduce a raw `UPDATE tasks SET status`. |
| In-process and container paths put orchestration on different sides of process boundary. | Decide which path survives before extending both. |
| Identity uses strings; task uniqueness/NATS dedup omit identity. | Don't promise multi-identity ownership until canonical IDs migrate. |
| Container RPC uses root forge/worktree, not task owner's identity. | Known trust/correctness defect — not identity-isolated. |
| Missing `task.json` makes `archie-agent` join shared queue. | Fail closed before treating as isolated. |
| Subprocess uses daemon user and host access. | Not a security boundary. |
| Gateway formerly duplicated lifecycle strings, competing message contracts. | No third contract or direct lifecycle mutation path; status constants live in `internal/domain/workflow`. |
| Global config and `IdentityConfig` combine unrelated owners. | Don't rename global structure or add `Extra` map. |
| Memory has fixed scope requirements but OPEN final placement/migration. | Preserve scope isolation; focused design before moving. |
| Tests can make unused/duplicate code appear legitimate. | Prove production reachability from composition. |
## Control every architecture-affecting change
| Class | Action |
| --- | --- |
| Current-path repair | Stay inside current owner, preserve invariants. |
| Migration slice | Record current/target owner, contracts, compatibility adapter, cutover, deletion criteria. |
| New/changed architecture | Stop; run `archie-architecture-planning-campaign` until approved. |
| Class | Action |
| ------------------------ | ------------------------------------------------------------------------------------------ |
| Current-path repair | Stay inside current owner, preserve invariants. |
| Migration slice | Record current/target owner, contracts, compatibility adapter, cutover, deletion criteria. |
| New/changed architecture | Stop; run `archie-architecture-planning-campaign` until approved. |
Trace with evidence:
+52 -52
View File
@@ -13,14 +13,14 @@ All volatile observations are snapshots from **2026-09-18** (HEAD `2e1e1549`).
## Name the surfaces
| Term | Meaning here |
|---|---|
| Repository root | Directory containing `go.mod`, `Taskfile.yml`, and `CLAUDE.md`. |
| Runtime module | Root Go module `github.com/samcharles93/archie-core`. |
| Tools module | Independent nested Go module under `tools/`. |
| Docs | Markdown under `docs/`, read directly; no build, no renderer. |
| Cold cache | Dependency cache not yet containing required modules/packages. |
| Restricted sandbox | May allow file reads but deny loopback listeners, container engine, or writes to default caches. |
| Term | Meaning here |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| Repository root | Directory containing `go.mod`, `Taskfile.yml`, and `CLAUDE.md`. |
| Runtime module | Root Go module `github.com/samcharles93/archie-core`. |
| Tools module | Independent nested Go module under `tools/`. |
| Docs | Markdown and generated JSON under `docs/`; an external Astro website renders and deploys the generated artifacts. |
| Cold cache | Dependency cache not yet containing required modules/packages. |
| Restricted sandbox | May allow file reads but deny loopback listeners, container engine, or writes to default caches. |
No root `README*` or `CONTRIBUTING*` file exists. Begin with:
@@ -55,15 +55,15 @@ cannot type-check them and deletes a genuinely used `internal/secret` import,
so `.golangci.yml` excludes those exact files from the formatter set. Their
runtime loading remains covered by `internal/secret/engines_test.go`.
| Surface | Repository declaration | Installed snapshot | Interpretation |
|---|---|---|---|
| Runtime Go | `go 1.27.0` in `go.mod` | Go 1.27.0, linux/amd64 | Requires at least declared Go level. |
| Tools Go | `go 1.27.0` in `tools/go.mod` | Same Go 1.27.0 binary | Toolchain must satisfy both modules. |
| Task | Taskfile schema `version: "3"` | Task 3.48.0 | Installed version is environment fact. |
| gofumpt | Generated protobuf formatting; pinned in `Dockerfile` | v0.11.0 | Not the ordinary source formatter. |
| golangci-lint | v2 config in `.golangci.yml`; pinned in `Dockerfile` | 2.13.2 | Owns ordinary formatting and lint checks. |
| Node | `ui/` frontend build | 26.9.0 / npm 11.19.1 | No `engines`/`packageManager` field. Docs need no Node. |
| Containers | Compose commands in `Taskfile.yml` | Podman-backed, unusable in this sandbox | Verify CLI, Compose plugin, daemon/socket separately. |
| Surface | Repository declaration | Installed snapshot | Interpretation |
| ------------- | ----------------------------------------------------- | --------------------------------------- | ------------------------------------------------------- |
| Runtime Go | `go 1.27.0` in `go.mod` | Go 1.27.0, linux/amd64 | Requires at least declared Go level. |
| Tools Go | `go 1.27.0` in `tools/go.mod` | Same Go 1.27.0 binary | Toolchain must satisfy both modules. |
| Task | Taskfile schema `version: "3"` | Task 3.48.0 | Installed version is environment fact. |
| gofumpt | Generated protobuf formatting; pinned in `Dockerfile` | v0.11.0 | Not the ordinary source formatter. |
| golangci-lint | v2 config in `.golangci.yml`; pinned in `Dockerfile` | 2.13.2 | Owns ordinary formatting and lint checks. |
| Node | `ui/` frontend build | 26.9.0 / npm 11.19.1 | No `engines`/`packageManager` field. Docs need no Node. |
| Containers | Compose commands in `Taskfile.yml` | Podman-backed, unusable in this sandbox | Verify CLI, Compose plugin, daemon/socket separately. |
## Prepare writable caches in a restricted sandbox
@@ -92,7 +92,7 @@ env GOTMPDIR="$ARCHIE_GOTMPDIR" GOCACHE="$ARCHIE_GOCACHE" \
go test ./internal/config/... -count=1
```
Populate cold cache only with network authorized:
Populate cold cache only with network authorised:
```bash
env ... go mod download; env ... go -C tools mod download
@@ -112,16 +112,16 @@ golangci-lint run ./...
## Understand exactly what Task runs
| Task | Exact effect |
|---|---|
| `task fmt` | `go fix ./...`, then `golangci-lint fmt` — both may rewrite source. |
| `task vet` | `go vet ./...` in the runtime module. |
| `task lint` | `golangci-lint run ./...`. |
| `task build` | Builds both commands into `bin/`. |
| `task test` | `go test ./... -count=1` in the runtime module. |
| `task check` | `fmt` + `proto:lint` + `proto:check` + `docs:check` + `vet` + `lint` + `build` + `test` + `test:tools` + `test:ui`. |
| `task clean` | Recursively removes `bin/`; destructive. |
| `task docker-build` | `docker compose build agent` only. |
| Task | Exact effect |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `task fmt` | `go fix ./...`, then `golangci-lint fmt` — both may rewrite source. |
| `task vet` | `go vet ./...` in the runtime module. |
| `task lint` | `golangci-lint run ./...`. |
| `task build` | Builds both commands into `bin/`. |
| `task test` | `go test -short ./...` in the runtime module, test cache on. `task test:full` is the uncached run including wall-clock-bound tests. |
| `task check` | `fmt` + `proto:lint` + `proto:check` + `docs:check` + `vet` + `lint` + `build` + `test` + `test:tools` + `test:ui`. |
| `task clean` | Recursively removes `bin/`; destructive. |
| `task docker-build` | `docker compose build agent` only. |
`task check` is the definitive gate but omits race tests, `task vuln`, and
`task docker-build`. Its docs step, `docs:check`, verifies committed generated
@@ -138,7 +138,7 @@ on work that is correct but unstaged, and both read as a broken generator:
they differ. `task check` never rebuilds the bundle: run `task ui` after any
`ui/src` change and commit the result with that change.
Run only in an authorized writable worktree. For a read-only ordinary-source
Run only in an authorised writable worktree. For a read-only ordinary-source
preview, use `golangci-lint fmt --diff`.
## Verify the tools module separately
@@ -217,17 +217,17 @@ omit patch/digest; Ubuntu base images omit digests; agent installs multiple
## Separate environment failures from code failures
| Signature | Classify and branch |
|---|---|
| `go: creating work dir: mkdir /work/tmp/...: read-only file system` | Set task-specific `GOTMPDIR`. |
| `open .../.cache/go-build/...: read-only file system` | Set writable `GOCACHE`. |
| `open .../pkg/mod/cache/...tmp: read-only file system` | Set writable `GOMODCACHE` and `GOPATH`. |
| `listen ...: socket: operation not permitted` | Re-run on host with loopback sockets. |
| `Unable to start NATS Server in Go Routine` after ~10s | Test whether local listeners permitted. |
| `cannot auto-sign commit` | Ambient `commit.gpgSign=true`; fixtures set `gpgsign=false`. |
| `EAI_AGAIN` for `registry.npmjs.org` | Dependency retrieval failed. |
| `Podman configuration ... read-only file system` | Container backend cannot initialize. |
| `TestRunWrapsExternalCommand ... Run() = "\n"` | Focused code failure in `internal/skillscript`. |
| Signature | Classify and branch |
| ------------------------------------------------------------------- | ------------------------------------------------------------ |
| `go: creating work dir: mkdir /work/tmp/...: read-only file system` | Set task-specific `GOTMPDIR`. |
| `open .../.cache/go-build/...: read-only file system` | Set writable `GOCACHE`. |
| `open .../pkg/mod/cache/...tmp: read-only file system` | Set writable `GOMODCACHE` and `GOPATH`. |
| `listen ...: socket: operation not permitted` | Re-run on host with loopback sockets. |
| `Unable to start NATS Server in Go Routine` after ~10s | Test whether local listeners permitted. |
| `cannot auto-sign commit` | Ambient `commit.gpgSign=true`; fixtures set `gpgsign=false`. |
| `EAI_AGAIN` for `registry.npmjs.org` | Dependency retrieval failed. |
| `Podman configuration ... read-only file system` | Container backend cannot initialise. |
| `TestRunWrapsExternalCommand ... Run() = "\n"` | Focused code failure in `internal/skillscript`. |
For hermetic test diagnosis:
@@ -237,15 +237,15 @@ env GIT_CONFIG_GLOBAL=/dev/null go test ./internal/worktree/... ./internal/workt
## Use the complete validation matrix
| Evidence | Command | Current snapshot |
|---|---|---|
| Focused Go behavior | `go test ./pkg/... -run '^TestName$' -count=1 -v` | Use first. |
| Root unit/integration suite | `go test ./... -count=1` | Restricted sandbox fails listener-dependent packages. |
| Root race suite | `go test -race ./... -count=1` | Not run by `task check`. |
| Vet | `go vet ./...` | Passed on 2026-09-18. |
| Lint | `golangci-lint run ./...` | Not re-run on 2026-09-18; a focused `--enable-only=dupl ./internal/...` run reported 0 issues. Re-run before quoting a total. |
| Build | `go build -o /tmp/... ./cmd/archied` and `cmd/archie-agent` | Both passed on 2026-09-18. |
| Tools tests | `go -C tools test -mod=readonly ./... -count=1` | Passed on 2026-09-18. |
| Generated contract parity | Temp docsgen output + `cmp --silent` | Passed for 11 schemas on 2026-09-18, after regenerating a file stale since `4b340d2b`. |
| Container build | `task docker-build` | Not verified in restricted environment. |
| Repository gate | `task check` | See `archie-diagnostics-and-tooling` for the dated snapshot. |
| Evidence | Command | Current snapshot |
| --------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Focused Go behaviour | `go test ./pkg/... -run '^TestName$' -count=1 -v` | Use first. |
| Root unit/integration suite | `go test ./... -count=1` | Restricted sandbox fails listener-dependent packages. |
| Root race suite | `go test -race ./... -count=1` | Not run by `task check`. |
| Vet | `go vet ./...` | Passed on 2026-09-18. |
| Lint | `golangci-lint run ./...` | Not re-run on 2026-09-18; a focused `--enable-only=dupl ./internal/...` run reported 0 issues. Re-run before quoting a total. |
| Build | `go build -o /tmp/... ./cmd/archied` and `cmd/archie-agent` | Both passed on 2026-09-18. |
| Tools tests | `go -C tools test -mod=readonly ./... -count=1` | Passed on 2026-09-18. |
| Generated contract parity | Temp docsgen output + `cmp --silent` | Passed for 11 schemas on 2026-09-18, after regenerating a file stale since `4b340d2b`. |
| Container build | `task docker-build` | Not verified in restricted environment. |
| Repository gate | `task check` | See `archie-diagnostics-and-tooling` for the dated snapshot. |
@@ -1,11 +1,11 @@
---
name: archie-codebase-discovery
description: "Trace Archie behavior and blast radius through Go source, types, state, persistence, transports, consumers, tests, configuration, production composition, and target architecture. Load before changing or planning a non-trivial feature, refactor, config field, interface, persistence path, workflow, channel, plugin, or agent execution path; also load to investigate duplicate behavior, hidden dead code, constructor bypasses, package dependencies, decoded-but-unwired configuration, or uncertainty about what a symbol actually affects."
description: "Trace Archie behaviour and blast radius through Go source, types, state, persistence, transports, consumers, tests, configuration, production composition, and target architecture. Load before changing or planning a non-trivial feature, refactor, config field, interface, persistence path, workflow, channel, plugin, or agent execution path; also load to investigate duplicate behaviour, hidden dead code, constructor bypasses, package dependencies, decoded-but-unwired configuration, or uncertainty about what a symbol actually affects."
---
# Discover the Archie codebase
Use evidence from the current checkout to explain a behavior before changing it.
Use evidence from the current checkout to explain a behaviour before changing it.
Volatile tool facts below were verified on **2026-09-18**.
**Composition roots**: `cmd/archied/main.go` (thin dispatcher) →
@@ -43,45 +43,45 @@ go list -m -f '{{.Path}} {{.GoVersion}}'
go -C tools list -mod=readonly -m -f '{{.Path}} {{.GoVersion}}'
```
## Build the behavior trace
## Build the behaviour trace
Write: behavior, observable input, expected output, state that may change, modes.
Write: behaviour, observable input, expected output, state that may change, modes.
| Step | Find | Required evidence |
|---:|---|---|
| 1 | Entrypoint | `main`, handler, poller, RPC subject, or tool registration |
| 2 | Construction | Constructor and every direct struct literal |
| 3 | Contract | Interface, wire type, command, event, or public method crossed |
| 4 | Implementation | All type-valid implementations, selected per mode |
| 5 | State owner | Function validating transition, owning concurrency/transaction rules |
| 6 | Persistence | Store adapter, schema/key/document, serialization, reload/recovery |
| 7 | Event/transport | Publish/send and subscribe/receive, subject/framing, timeout, retry, ack |
| 8 | Consumer | Callers and downstream readers |
| 9 | Tests | Unit, integration, contract, architecture, production-composition |
| 10 | Configuration | Decode, default, validation, normalization, composition-root consumption |
| 11 | Target architecture | Current-to-target mapping in `docs/prds/`; label gaps |
| Step | Find | Required evidence |
| ---: | ------------------- | ------------------------------------------------------------------------ |
| 1 | Entrypoint | `main`, handler, poller, RPC subject, or tool registration |
| 2 | Construction | Constructor and every direct struct literal |
| 3 | Contract | Interface, wire type, command, event, or public method crossed |
| 4 | Implementation | All type-valid implementations, selected per mode |
| 5 | State owner | Function validating transition, owning concurrency/transaction rules |
| 6 | Persistence | Store adapter, schema/key/document, serialisation, reload/recovery |
| 7 | Event/transport | Publish/send and subscribe/receive, subject/framing, timeout, retry, ack |
| 8 | Consumer | Callers and downstream readers |
| 9 | Tests | Unit, integration, contract, architecture, production-composition |
| 10 | Configuration | Decode, default, validation, normalisation, composition-root consumption |
| 11 | Target architecture | Current-to-target mapping in `docs/prds/`; label gaps |
Start at these verified anchors:
| Concern | Current anchor |
|---|---|
| Resident daemon | `cmd/archied/main.go` → `internal/app/archied.Run()` (`internal/app/archied/main.go`) → `daemon.Daemon` |
| Sandboxed worker | `cmd/archie-agent/main.go` → `internal/app/agentworker/`; NATS boundary in `internal/infrastructure/agenttransport/nats/` |
| Task orchestration | `internal/daemon/daemon.go`, `internal/domain/workflow/` |
| Task contracts | `internal/domain/storecontract/storecontract.go` (`TaskStore`); `internal/store/interface.go` holds compatibility aliases only |
| Production task persistence | `internal/store/`; `openProductionTaskStore` reached via `internal/app/archied/state_store.go` |
| RPC split | `internal/{taskrun,natsrpc,forgerpc,worktreerpc}/` plus `internal/infrastructure/staterpc/` (gRPC State Store) |
| Chat and channels | `internal/gateway/`, `internal/channels/` |
| Configuration | `internal/config/`, `internal/infrastructure/configuration/`, `config.example.toml`, `deployments/*.toml` |
| Target map | `docs/prds/01-project-management.md` and linked `docs/architecture/*.md` |
| Concern | Current anchor |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Resident daemon | `cmd/archied/main.go` → `internal/app/archied.Run()` (`internal/app/archied/main.go`) → `daemon.Daemon` |
| Sandboxed worker | `cmd/archie-agent/main.go` → `internal/app/agentworker/`; NATS boundary in `internal/infrastructure/agenttransport/nats/` |
| Task orchestration | `internal/daemon/daemon.go`, `internal/domain/workflow/` |
| Task contracts | `internal/domain/storecontract/storecontract.go` (`TaskStore`) |
| Production task persistence | `internal/infrastructure/postgres/`; built in `internal/app/archied/state_store.go` |
| RPC split | `internal/{taskrun,natsrpc,forgerpc,worktreerpc}/` plus `internal/infrastructure/staterpc/` (gRPC State Store) |
| Chat and channels | `internal/gateway/`, `internal/channels/` |
| Configuration | `internal/config/`, `internal/infrastructure/configuration/`, `config.example.toml`, `deployments/*.toml` |
| Target map | `docs/prds/01-project-management.md` and linked `docs/architecture/*.md` |
## Use syntax, type, and call evidence
### Map packages before reading files
```sh
go list -f '{{.ImportPath}}|go={{join .GoFiles ","}}|tests={{join .TestGoFiles ","}}' ./internal/store
go list -json ./internal/store
go list -f '{{.ImportPath}}|go={{join .GoFiles ","}}|tests={{join .TestGoFiles ","}}' ./internal/infrastructure/postgres
go list -json ./internal/infrastructure/postgres
.agents/skills/archie-codebase-discovery/scripts/package-edges.sh ./internal/...
```
@@ -96,7 +96,7 @@ gopls references -d internal/domain/storecontract/storecontract.go:33:2
gopls implementation internal/domain/storecontract/storecontract.go:33:2
gopls call_hierarchy internal/domain/storecontract/storecontract.go:33:2
go doc ./internal/domain/storecontract.TaskStore
go test ./internal/store -list '.'
go test ./internal/infrastructure/postgres -list '.'
```
### Generate AST candidates for construction
@@ -111,7 +111,7 @@ Confirms candidates with `gopls definition` or `gopls references`. Pass
## Run focused discovery recipes
### Find duplicate behavior paths
### Find duplicate behaviour paths
```sh
golangci-lint run --enable-only=dupl ./internal/...
@@ -162,8 +162,8 @@ go list -deps -json <pattern>
### Find decoded-but-unused configuration
Prove: `file/key → decoder → default → validation → normalization/copy →
composition-root read → concrete component → observable behavior`.
Prove: `file/key → decoder → default → validation → normalisation/copy →
composition-root read → concrete component → observable behaviour`.
```sh
rg -n 'toml:"|yaml:"|json:"' internal/config
@@ -183,37 +183,39 @@ and `Loader.Dir` for overlay/`conf.d` inputs). There is no `config.Load` or
`cmd/archied/main.go`.
2. Record config condition per branch.
3. Follow concrete construction into `daemon.Daemon` and gateway start.
4. For container/NATS behavior, trace `cmd/archie-agent/main.go` into
4. For container/NATS behaviour, trace `cmd/archie-agent/main.go` into
`internal/app/agentworker` and `internal/infrastructure/agenttransport/nats`.
5. Trace both sides of every RPC/transport and error/timeout paths.
6. Read contract/architecture tests.
7. Confirm deploy inputs in Compose and CI.
### Trace SQLite persistence
### Trace persistence
Treat `internal/domain/storecontract` as the application contract and
`internal/store` as the production SQLite adapter behind it.
`internal/infrastructure/postgres` as the production adapter behind it; the
schema is `internal/infrastructure/postgres/migrations/` and the queries are
sqlc-generated from `queries/`.
```sh
gopls implementation internal/domain/storecontract/storecontract.go:33:2
rg -n 'CREATE TABLE|CREATE INDEX|QueryContext|ExecContext|BeginTx' internal/store
rg -n 'CREATE TABLE|CREATE INDEX' internal/infrastructure/postgres/migrations
```
## Reject false confidence
| Weak evidence | Why it fails | Required correction |
|---|---|---|
| One `rg` result | Misses interface dispatch, aliases, generated registration, reflection | Use gopls, AST candidates, package edges, composition |
| Green unit test | May bypass config, lifecycle, transport | Add composition/contract/integration evidence |
| Fake client and server agree | Both mirror same wrong framing/subject/state assumption | Compare independent spec or real boundary fixture |
| High coverage | Does not establish ownership, maintainability, mode selection | Trace authority and production selection |
| Constructor exists | Does not prove callers use it | Find struct literals and type-aware references |
| Config field decodes | Does not prove executable reads it | Complete config-to-observable chain |
| Target PRD says it | Not necessarily current code | Cite current implementation and label gap |
| Weak evidence | Why it fails | Required correction |
| ---------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- |
| One `rg` result | Misses interface dispatch, aliases, generated registration, reflection | Use gopls, AST candidates, package edges, composition |
| Green unit test | May bypass config, lifecycle, transport | Add composition/contract/integration evidence |
| Fake client and server agree | Both mirror same wrong framing/subject/state assumption | Compare independent spec or real boundary fixture |
| High coverage | Does not establish ownership, maintainability, mode selection | Trace authority and production selection |
| Constructor exists | Does not prove callers use it | Find struct literals and type-aware references |
| Config field decodes | Does not prove executable reads it | Complete config-to-observable chain |
| Target PRD says it | Not necessarily current code | Cite current implementation and label gap |
## Produce the discovery handoff
1. **Behavior trace:** path:line, symbol, current responsibility per traversal step.
1. **Behaviour trace:** path:line, symbol, current responsibility per traversal step.
2. **Mode matrix:** mode/config branch → concrete implementation → state store
→ transport → consumer.
3. **State and authority:** owner, copies, persistence, transition rules, recovery.
+93 -103
View File
@@ -6,7 +6,7 @@ description: Trace, add, rename, deprecate, or debug Archie configuration and co
# Trace Archie configuration and flags
Treat configuration as a dataflow, not as a struct inventory. Prove every
claimed setting has an input, normalization path, composition seam, and runtime
claimed setting has an input, normalisation path, composition seam, and runtime
consumer.
Current evidence date: **2026-09-18** for the matrix below. Entries added later
@@ -14,13 +14,13 @@ carry their own date inline.
Use these status terms exactly:
| Status | Meaning |
| --- | --- |
| **production-wired** | A real entrypoint decodes or accepts the value and a runtime consumer uses it. |
| **partially-wired** | Some modes, scopes, or fields consume it, but parity is incomplete. |
| **test/library-only** | An API and tests exist, but no current binary selects it. |
| **decoded-but-unwired** | Decoding/defaulting succeeds, but no production consumer uses the effective value. |
| **external-production-unknown** | The repository does not contain the deployed effective value. |
| Status | Meaning |
| ------------------------------- | ---------------------------------------------------------------------------------- |
| **production-wired** | A real entrypoint decodes or accepts the value and a runtime consumer uses it. |
| **partially-wired** | Some modes, scopes, or fields consume it, but parity is incomplete. |
| **test/library-only** | An API and tests exist, but no current binary selects it. |
| **decoded-but-unwired** | Decoding/defaulting succeeds, but no production consumer uses the effective value. |
| **external-production-unknown** | The repository does not contain the deployed effective value. |
Never upgrade a status merely because decoding tests pass.
@@ -32,7 +32,7 @@ Never upgrade a status merely because decoding tests pass.
3. Read `finalize` and any consumer-side defaults.
4. Follow copies across `ForTask`, `ToConfig`, NATS messages, subprocess
env selection, container env construction, and identity overlays.
5. Find the production composition site and final behavior-changing read.
5. Find the production composition site and final behaviour-changing read.
6. Find tests for decoding, defaulting, invalid input, production composition,
and mode parity.
7. Check `config.example.toml`, `deployments/*.toml`, `docker-compose.yml`, and
@@ -48,15 +48,15 @@ rg -n 'FIELD_NAME|external_key|ENV_NAME' \
## Select the real input path
| Input path | Current behavior | Status |
| --- | --- | --- |
| `archied -config PATH` | Defaults to `$XDG_CONFIG_HOME/archie/config.toml`, or `$HOME/.config/archie/config.toml`; `internal/app/archied/bootstrap.go` builds `configuration.New(log)` and calls `Loader.Resolve`. | production-wired |
| `archied -config-overlay PATH` | Resolves a file or directory overlay through the same loader. Omitted overlay fields retain base values. This is the only overlay: the dashboard runtime overlay and its SQLite store were deleted when the control plane took over settings writes. | production-wired |
| `configuration.Loader.Dir(base, overlay)` | Supports main YAML/TOML plus feature YAML and `conf.d`; no current entrypoint calls it. | test/library-only |
| `config.Load(path)`, `config.LoadDir(...)` | Removed. The old `internal/config` package-level helpers no longer exist; decoding is `Loader`-based. | not applicable |
| `config.example.toml` | Load-tested example, not a deployed configuration. | test/library-only |
| `deployments/docker-nats-stack.toml` | Complete host-daemon configuration for the Compose-managed NATS service. It is copied into the operator's config directory; Compose does not mount it. | supported-example |
| Operator config and environment | Lives outside the repository; contents are deployment-specific. | external-production-unknown |
| Input path | Current behaviour | Status |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `archied -config PATH` | Defaults to `$XDG_CONFIG_HOME/archie/config.toml`, or `$HOME/.config/archie/config.toml`; `internal/app/archied/bootstrap.go` builds `configuration.New(log)` and calls `Loader.Resolve`. | production-wired |
| `archied -config-overlay PATH` | Resolves a file or directory overlay through the same loader. Omitted overlay fields retain base values. This is the only overlay: the dashboard runtime overlay and its SQLite store were deleted when the control plane took over settings writes. | production-wired |
| `configuration.Loader.Dir(base, overlay)` | Supports main YAML/TOML plus feature YAML and `conf.d`; no current entrypoint calls it. | test/library-only |
| `config.Load(path)`, `config.LoadDir(...)` | Removed. The old `internal/config` package-level helpers no longer exist; decoding is `Loader`-based. | not applicable |
| `config.example.toml` | Load-tested example, not a deployed configuration. | test/library-only |
| `deployments/docker-nats-stack.toml` | Complete host-daemon configuration for the Compose-managed NATS service. It is copied into the operator's config directory; Compose does not mount it. | supported-example |
| Operator config and environment | Lives outside the repository; contents are deployment-specific. | external-production-unknown |
Both TOML and YAML decoding are non-strict at the field level. Add explicit
compatibility and typo tests; never use "the file loaded" as evidence that a
@@ -75,15 +75,15 @@ flag or on the dial succeeding, and give a binary its own
### Public binaries
| Binary | Flag | Default and effect |
| --- | --- | --- |
| `archied` | `-config PATH` | Computed config path described above. |
| `archied` | `-config-overlay PATH` | Empty; overlay only fields explicitly present in second TOML. |
| `archied` | `-once` | `false`; run one poll/process cycle and exit. |
| `archied` | `-requeue ID` | `0`; values greater than zero requeue one parked/waiting task, then exit unless `-once` also set. |
| `archie-agent` | `-nats-url URL` | Empty; takes precedence over `NATS_URL`. Missing both is fatal. |
| `archie-agent` | `-consumer NAME` | `archie-agent`; names the JetStream durable consumer. |
| both | `-quickchecks N` | Incidental flag registered by `github.com/traefik/yaegi/stdlib` importing `testing/quick`; default `100`. Treat as unowned candidate defect. |
| Binary | Flag | Default and effect |
| -------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `archied` | `-config PATH` | Computed config path described above. |
| `archied` | `-config-overlay PATH` | Empty; overlay only fields explicitly present in second TOML. |
| `archied` | `-once` | `false`; run one poll/process cycle and exit. |
| `archied` | `-requeue ID` | `0`; values greater than zero requeue one parked/waiting task, then exit unless `-once` also set. |
| `archie-agent` | `-nats-url URL` | Empty; takes precedence over `NATS_URL`. Missing both is fatal. |
| `archie-agent` | `-consumer NAME` | `archie-agent`; names the JetStream durable consumer. |
| both | `-quickchecks N` | Incidental flag registered by `github.com/traefik/yaegi/stdlib` importing `testing/quick`; default `100`. Treat as unowned candidate defect. |
The standalone agent always reads its token from `NATS_TOKEN`; there is no
token flag.
@@ -93,9 +93,9 @@ token flag.
`archied workspace-codesearch` bypasses daemon configuration before normal flag
parsing:
| Subcommand | Required flags | Optional flags |
| --- | --- | --- |
| `build` | `--root`, `--index` | none |
| Subcommand | Required flags | Optional flags |
| ------------ | ---------------------- | ------------------------------- |
| `build` | `--root`, `--index` | none |
| `candidates` | `--index`, `--pattern` | `--literal`, `--case-sensitive` |
Do not expose these helper flags as daemon settings.
@@ -104,41 +104,39 @@ Do not expose these helper flags as daemon settings.
### Root daemon and capability settings
| Keys | Default, validation, and consumer | Status |
| --- | --- | --- |
| `work_dir`, `db_path` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; explicit `~` paths are home-expanded. `db_path` is a prefix: tasks/events use `<db_path>-tasks.sqlite` and conversations use `<db_path>-conversations.sqlite`. | production-wired |
| `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. | partially-wired |
| `plugin_dir` | Empty disables daemon plugin loading; configured directory loaded in `internal/app/archied`. | production-wired |
| `poll_interval` | Default `60s`; root poll loop uses it, identities may override only interval. | production-wired |
| `label` | No default or validation; used for `dispatch.trigger = "label"` or `"either"`. | production-wired |
| `max_retries` | Default `3`; repository value greater than zero overrides. | production-wired |
| `bot_user`, `bot_email` | Single-identity requires `bot_user`; email defaults by forge type. | production-wired |
| `forge.type`, `host`, `token` | Type defaults `github`, host defaults `https://github.com`; only `github` and `gitea` validate. | production-wired |
| `dispatch.trigger` | Default `assignee`; validates `assignee`, `label`, or `either`. | production-wired |
| `dispatch.ack_reaction` | Default `eyes`; case-insensitive `off` normalizes to empty. | production-wired |
| `dispatch.labels.*` | Missing keys default independently to `agent:*`. | production-wired |
| `models.<role>` | Workflow stages read requested role then fall back to `builder`; triage judge falls back `triage` to `planner`. | production-wired |
| `providers.<name>.class`, `api_key_env`, `base_url` | Builds ai-sdk catalog. `base_url` rejects parse errors, userinfo, query, and fragment. | production-wired |
| `agent.mode` | Default `nats` when containers enabled, otherwise `inprocess`; validates `inprocess`, `subprocess`, or `nats`. | production-wired |
| `agent.command`, `agent.env` | Command defaults `archie-agent`; env entries must be nonblank names without `=`. | partially-wired |
| `budgets.max_steps`, `max_tokens`, `wall_clock`, `gate_max_failures` | No loader defaults; `Budgets` documents zero as disabling. | production-wired |
| `diff_cap_lines` | Zero replaced by `400` in `finalize`; `StageDiffCap` treats `<= 0` as disabled. TOML zero cannot disable; negative value does. | production-wired |
| `web.listen` | Empty becomes `127.0.0.1:8484`; literal `off` disables. No authentication. | production-wired |
| `notify.webhook` | Empty disables; feasibility workflow POSTs human-decision notifications when set. | production-wired |
| `nats.url`, `token_env` | Empty URL keeps SQLite path. Configured token variable must be non-empty. | production-wired |
| `containers.*` | See dedicated table below. | production-wired |
| `chat.*` | See channel table below. | production-wired |
| `memory.provider`, `provider_config` | Feature YAML decodes these; `internal/app/archied` always starts built-in file provider at `work_dir/memory`. | decoded-but-unwired |
| `tools.mcp_servers` | `internal/app/archied` registers daemon-side MCP providers. Empty transport becomes `stdio`; only `stdio` accepted. `url` decoded but unused. | partially-wired |
| `indexing.index_dir`, `indexing.db_path` | `finalize` derives paths under `work_dir`; no entrypoint constructs `internal/indexing.Manager` (the exported `NewManager` exists but has no production caller). | decoded-but-unwired |
| `extra` / unknown `conf.d` values | Test/library-only `Loader.Dir` stores untyped data; no core production consumer. | decoded-but-unwired |
| `[identities.forge].intake`, `.webhook_secret`, `.webhook_addr` | 2026-09-22: these parse because `IdentityConfig` embeds `Forge` (`internal/config/config.go:573`), while every read is the root `[forge]` block (`validate.go`, `defaults.go`, `bootstrap.go`). Wiring them is the intake migration, tracked as `archie-core-1786637497036-275-8838629e`. | partially-wired |
| Keys | Default, validation, and consumer | Status |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `work_dir`, `state_dir` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; explicit `~` paths are home-expanded. `state_dir` holds the embedded NATS store and endpoint file, task logs and the readiness disk target. | production-wired |
| `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. | partially-wired |
| `plugin_dir` | Empty disables daemon plugin loading; configured directory loaded in `internal/app/archied`. | production-wired |
| `poll_interval` | Default `60s`; root poll loop uses it, identities may override only interval. | production-wired |
| `label` | No default or validation; used for `dispatch.trigger = "label"` or `"either"`. | production-wired |
| `max_retries` | Default `3`; repository value greater than zero overrides. | production-wired |
| `bot_user`, `bot_email` | Single-identity requires `bot_user`; email defaults by forge type. | production-wired |
| `forge.type`, `host`, `token` | Type defaults `github`, host defaults `https://github.com`; only `github` and `gitea` validate. | production-wired |
| `dispatch.trigger` | Default `assignee`; validates `assignee`, `label`, or `either`. | production-wired |
| `dispatch.ack_reaction` | Default `eyes`; case-insensitive `off` normalises to empty. | production-wired |
| `dispatch.labels.*` | Missing keys default independently to `agent:*`. | production-wired |
| `models.<role>` | Workflow stages read requested role then fall back to `builder`; triage judge falls back `triage` to `planner`. | production-wired |
| `providers.<name>.class`, `api_key_env`, `base_url` | Builds ai-sdk catalogue. `base_url` rejects parse errors, userinfo, query, and fragment. | production-wired |
| `budgets.max_steps`, `max_tokens`, `wall_clock`, `gate_max_failures` | No loader defaults; `Budgets` documents zero as disabling. | production-wired |
| `diff_cap_lines` | Zero replaced by `400` in `finalize`; `StageDiffCap` treats `<= 0` as disabled. TOML zero cannot disable; negative value does. | production-wired |
| `web.listen` | Empty becomes `127.0.0.1:8484`; literal `off` disables. No authentication. | production-wired |
| `notify.webhook` | Empty disables; feasibility workflow POSTs human-decision notifications when set. | production-wired |
| `nats.url`, `token_env` | Empty URL keeps the in-process path. Configured token variable must be non-empty. | production-wired |
| `containers.*` | See dedicated table below. | production-wired |
| `chat.*` | See channel table below. | production-wired |
| `memory.provider`, `provider_config` | Feature YAML decodes these; `internal/app/archied` always starts built-in file provider at `work_dir/memory`. | decoded-but-unwired |
| `tools.mcp_servers` | `internal/app/archied` registers daemon-side MCP providers. Empty transport becomes `stdio`; only `stdio` accepted. `url` decoded but unused. | partially-wired |
| `indexing.index_dir`, `indexing.db_path` | `finalize` derives paths under `work_dir`; no entrypoint constructs `internal/indexing.Manager` (the exported `NewManager` exists but has no production caller). | decoded-but-unwired |
| `extra` / unknown `conf.d` values | Test/library-only `Loader.Dir` stores untyped data; no core production consumer. | decoded-but-unwired |
| `[identities.forge].intake`, `.webhook_secret`, `.webhook_addr` | 2026-09-22: these parse because `IdentityConfig` embeds `Forge` (`internal/config/config.go:573`), while every read is the root `[forge]` block (`validate.go`, `defaults.go`, `bootstrap.go`). Wiring them is the intake migration, tracked as `archie-core-1786637497036-275-8838629e`. | partially-wired |
**Three shapes of an unwired field.** All three read as working from the file
alone, and only the first two are defects - so establish which shape you are
looking at before reporting one:
1. **not-consumed.** Decoded and normalized, but no production consumer uses the
1. **not-consumed.** Decoded and normalised, but no production consumer uses the
effective value (`memory.provider` and `indexing.*` above; per-identity intake
was this shape until 2026-09-22, when the configuration was made to reject it
rather than accept it).
@@ -154,45 +152,40 @@ looking at before reporting one:
from the stored resource, on purpose. Check for that comment before filing a
defect.
The default `agent.command = "archie-agent"` is not verified subprocess
operation. `SubprocessRunner` expects one JSON invocation on stdin and one JSON
response on stdout; `cmd/archie-agent` is a long-running NATS worker.
### Repository settings
| Keys | Effective behavior | Status |
| --- | --- | --- |
| `owner`, `name` | Required for every declared repo. Single-identity config with zero repos loads but polls nothing. | production-wired |
| `base` | `BaseBranch()` maps empty to `main`, but `daemon.process` pre-clones with raw `repo.Base`. Set it explicitly. | partially-wired |
| `gate` | Argv arrays run in order. Empty entries skipped. TDD inverts last non-empty command as repro test by convention. | production-wired |
| `protect` | Path suffixes enforced by agent runner; not prompt-only rule. | production-wired |
| `ecosystem`, `preflight`, `test_glob` | Resolved preflight/test-glob treats empty ecosystem as Go. Container storage receives raw ecosystem. Go/Python/Node/Rust have defaults; `custom` or unknown yields none. | partially-wired |
| `persistent_storage` | Controls Docker-backed per-repo volume setup; no equivalent without container storage. | partially-wired |
| `max_retries` | Values greater than zero override global; zero or negative falls back to global. | production-wired |
| `allow_concurrent` | Root repo entries affect dispatcher. `allowConcurrentFor` does not inspect identity repo lists. | partially-wired |
| Keys | Effective behaviour | Status |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- |
| `owner`, `name` | Required for every declared repo. Single-identity config with zero repos loads but polls nothing. | production-wired |
| `base` | `BaseBranch()` maps empty to `main`, but `daemon.process` pre-clones with raw `repo.Base`. Set it explicitly. | partially-wired |
| `gate` | Argv arrays run in order. Empty entries skipped. TDD inverts last non-empty command as repro test by convention. | production-wired |
| `protect` | Path suffixes enforced by agent runner; not prompt-only rule. | production-wired |
| `ecosystem`, `preflight`, `test_glob` | Resolved preflight/test-glob treats empty ecosystem as Go. Container storage receives raw ecosystem. Go/Python/Node/Rust have defaults; `custom` or unknown yields none. | partially-wired |
| `persistent_storage` | Controls Docker-backed per-repo volume setup; no equivalent without container storage. | partially-wired |
| `max_retries` | Values greater than zero override global; zero or negative falls back to global. | production-wired |
| `allow_concurrent` | Root repo entries affect dispatcher. `allowConcurrentFor` does not inspect identity repo lists. | partially-wired |
### Container settings
| Key | Effective behavior |
| --- | --- |
| `enabled` | Requires non-empty `image`, `agent.mode = "nats"`, and non-empty `nats.url`. |
| `image` | Required only when enabled. |
| `max_concurrency` | Zero means no limit; used by general task dispatcher and container pool. |
| `max_uptime` | Default `60m` only when enabled; caps container lifetime. |
| `volume_ttl` | Default `72h` only when enabled; negative rejected. |
| `pull_policy` | Default `missing` when enabled. Pool code recognizes `missing` and `always`; other strings silently skip pre-pull. |
| `network` | Empty uses best-effort self-network detection. Repository overlay pins `archie-core_default`. |
| Key | Effective behaviour |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| `image` | Required only when enabled. |
| `max_concurrency` | Zero means no limit; used by general task dispatcher and container pool. |
| `max_uptime` | Default `60m` only when enabled; caps container lifetime. |
| `volume_ttl` | Default `72h` only when enabled; negative rejected. |
| `pull_policy` | Default `missing` when enabled. Pool code recognises `missing` and `always`; other strings silently skip pre-pull. |
| `network` | Empty uses best-effort self-network detection. Repository overlay pins `archie-core_default`. |
### Channel settings
| Keys | Effective behavior |
| --- | --- |
| `chat.models` | Optional interactive catalog; empty falls back to workflow model references. |
| `chat.telegram.token_env` | Empty disables Telegram; non-empty names env variable; empty value is fatal. |
| `chat.telegram.allowed_user_ids` | Empty denies every sender; IDs match Telegram sender IDs, not chat IDs. |
| Keys | Effective behaviour |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `chat.models` | Optional interactive catalogue; empty falls back to workflow model references. |
| `chat.telegram.token` | Unset disables Telegram; otherwise a secret reference resolved at channel start. |
| `chat.telegram.allowed_user_ids` | Empty denies every sender; IDs match Telegram sender IDs, not chat IDs. |
| `chat.telegram.update_check_command`, `update_install_command` | Argv arrays; check enables update status; install further enables approved installation. |
| `chat.email.listen_addr`, `relay_addr` | Empty listen disables SMTP; relay configures outbound replies. |
| `chat.webhook_addr` | Empty disables; malformed host/port falls back inside `parseListenAddr`. |
| `chat.email.listen_addr`, `relay_addr` | Empty listen disables SMTP; relay configures outbound replies. |
| `chat.webhook_addr` | Empty disables; malformed host/port falls back inside `parseListenAddr`. |
Telegram `/restart` re-runs same TOML overlay load, then replaces only gateway
token and allowed-user list. Every other file setting is startup-only.
@@ -225,20 +218,17 @@ diff cap, notification, and forge host. `TaskConfig.ToConfig` reconstructs
only those fields. Forge tokens, provider values, NATS credential references,
repos, and infrastructure settings do not enter `TaskConfig`.
At top-level `[forge]`, prefer `token = {engine = "env", key = "NAME"}`. The
`token_env = "NAME"` form is converted only when structured reference is empty;
structured reference wins when both appear. This compatibility rule exists
because an earlier migration silently dropped deployed `token_env` values and
crash-looped the daemon. `finalize` does not apply that conversion inside each
identity: identity forges require explicit structured `token`.
Every credential except `nats.token_env` is a `{engine, key}` secret
reference; the flat `token_env` aliases for forge, artifacts and Telegram are
removed. A stale alias in a file is reported at startup as an unrecognised key
(`bootstrap.go`), not silently ignored.
| Source | Archied | Subprocess | Agent container / standalone worker |
| --- | --- | --- | --- |
| Forge `token = {engine="env", key="X"}` | Resolves `X`; empty is fatal. | Not forwarded. | Not forwarded; forge ops proxy to daemon. |
| Provider `api_key_env = "X"` | Runtime reads `X`. | Auto-allowlists selected provider's `X`. | Daemon forwards each present provider variable under original name. |
| `nats.token_env = "X"` | Reads `X`; empty fatal when configured. | Not agent subprocess setting. | Daemon maps to fixed `NATS_TOKEN`; worker also reads `NATS_URL`. |
| Telegram `token_env = "X"` | Reads `X`. | Not forwarded. | Not forwarded. |
| `agent.env = ["X"]` | Names validated. | Copies present `X` from daemon env. | Not used by container construction. |
| Source | Archied | Subprocess | Agent container / standalone worker |
| ------------------------------------------ | --------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------- |
| Forge `token = {engine="env", key="X"}` | Resolves `X`; empty is fatal. | Not forwarded. | Not forwarded; forge ops proxy to daemon. |
| Provider `api_key_env = "X"` | Runtime reads `X`. | Auto-allowlists selected provider's `X`. | Daemon forwards each present provider variable under original name. |
| `nats.token_env = "X"` | Reads `X`; empty fatal when configured. | Not agent subprocess setting. | Daemon maps to fixed `NATS_TOKEN`; worker also reads `NATS_URL`. |
| Telegram `token = {engine="env", key="X"}` | Resolves `X`. | Not forwarded. | Not forwarded. |
`internal/app/archied` creates `secret.NewRegistry`, which registers only the
`env` engine. Non-env `SecretRef` values are not production-wired.
@@ -1,6 +1,6 @@
---
name: archie-debugging-playbook
description: Project-specific symptom-to-evidence triage for archie-core. Load this skill when Archied hangs, parks a task, loses or duplicates work, cannot reach NATS or an agent container, rejects configuration or secrets, shows stale Telegram or dashboard state, loses streamed text, fails MCP startup, reports SQLite state surprises, degrades an optional feature, or when Go tests disagree between a sandbox, editor, CI, and the host. Use it to separate environment failures from code regressions and to choose the next exact diagnostic.
description: Project-specific symptom-to-evidence triage for archie-core. Load this skill when Archied hangs, parks a task, loses or duplicates work, cannot reach NATS or an agent container, rejects configuration or secrets, shows stale Telegram or dashboard state, loses streamed text, fails MCP startup, reports task-state surprises, degrades an optional feature, or when Go tests disagree between a sandbox, editor, CI, and the host. Use it to separate environment failures from code regressions and to choose the next exact diagnostic.
---
# Debug Archie from evidence
@@ -14,7 +14,7 @@ request/reply**: direct subject + reply inbox. **JetStream**: persisted stream
`ARCHIE_TASKS`. **State Store**: gRPC (`internal/infrastructure/staterpc`), not
NATS.
**Environment failure**: test/process cannot use host resource (listener, tmp,
Docker). **Code regression**: behavior fails where prerequisites available.
Docker). **Code regression**: behaviour fails where prerequisites available.
## Run the first-ten-minutes protocol
@@ -26,27 +26,28 @@ GIT_CONFIG_GLOBAL=/dev/null go test ./PATH/TO/PACKAGE -run '^TestName$' -count=1
```
Classify: compile-only, listener failure, read-only tmp, code regression.
- Behavioral assertion with the prerequisite available: code regression.
- Behavioural assertion with the prerequisite available: code regression.
Use this symptom index:
| Symptom | First boundary | Go to |
|---|---|---|
| `Run() = "\n"` in `TestRunWrapsExternalCommand` | Skill-script test command shape | Fixed history — passes since 2026-09-16 |
| Embedded NATS panics before a test assertion | Listener permission | Test environment |
| `nats: no responders available for request` | Core NATS subscription | NATS request/reply |
| Agent reply timeout | JetStream request, inbox, or worker | NATS request/reply |
| Queue looks empty while NATS reports an error | `Client.Fetch` batch error | NATS request/reply |
| Config test passes but daemon ignores the field | Composition/wiring | Configuration |
| Daemon has an env var but container does not | Compose or `containerEnv` | Configuration |
| Telegram reply hangs on the first token | Stream consumer | Streaming |
| MCP unit tests pass but a real server hangs | Framing mirror | MCP |
| Telegram shows old commands | Token-scoped Telegram state | Telegram |
| Transition succeeds from the wrong state | Store semantics | SQLite/state |
| Dashboard skips events but task state is correct | Bounded event buffers | Events |
| Search works but never becomes indexed | Missing production wiring | Optional features |
| Agent container cannot resolve `nats` | Docker network | Containers |
| `agent.mode = "subprocess"` fails at protocol startup | Worker binary mismatch | Subprocess mode |
| Symptom | First boundary | Go to |
| ----------------------------------------------------- | ----------------------------------- | --------------------------------------- |
| `Run() = "\n"` in `TestRunWrapsExternalCommand` | Skill-script test command shape | Fixed history — passes since 2026-09-16 |
| Embedded NATS panics before a test assertion | Listener permission | Test environment |
| `nats: no responders available for request` | Core NATS subscription | NATS request/reply |
| Agent reply timeout | JetStream request, inbox, or worker | NATS request/reply |
| Queue looks empty while NATS reports an error | `Client.Fetch` batch error | NATS request/reply |
| Config test passes but daemon ignores the field | Composition/wiring | Configuration |
| Daemon has an env var but container does not | Compose or `containerEnv` | Configuration |
| Telegram reply hangs on the first token | Stream consumer | Streaming |
| MCP unit tests pass but a real server hangs | Framing mirror | MCP |
| Telegram shows old commands | Token-scoped Telegram state | Telegram |
| Transition succeeds from the wrong state | Store semantics | Database/state |
| Dashboard skips events but task state is correct | Bounded event buffers | Events |
| Search works but never becomes indexed | Missing production wiring | Optional features |
| Agent container cannot resolve `nats` | Docker network | Containers |
| `agent.mode = "subprocess"` fails at protocol startup | Worker binary mismatch | Subprocess mode |
## Separate test-environment failures from regressions
@@ -87,15 +88,15 @@ env GOTMPDIR=/tmp GOCACHE=/tmp/archie-skillscript-gocache \
## Triage NATS request/reply and JetStream
| Surface | Subject or resource | Bound/current behavior |
|---|---|---|
| Task discovery | `archie.task.>` in `ARCHIE_TASKS` | Work-queue retention; daemon durable `archie-daemon`; max deliver 3 |
| Per-stage agent request | `archie.agent.<task>.request` | Reply inbox in `X-Archie-Reply`; wall-clock budget or 30m |
| Full task handoff | `archie.taskrun.<task-id>` | Core request/reply; no-responder retry 20s every 250ms |
| Store RPC | gRPC State Store (`internal/infrastructure/staterpc`) | Client timeout 60s (`rpcTimeout` in `internal/app/agentworker/worker.go`); task-scoped grants for Update/Transition/InsertEvent only |
| Forge RPC | `archie.forge.*` | Error travels in a JSON envelope |
| Worktree RPC | `archie.worktree.prepare`, `.push` | Server default handler bound 15m |
| Discovery dedup | `Nats-Msg-Id: archie:<owner>/<repo>/<issue>` | JetStream duplicate window 2m |
| Surface | Subject or resource | Bound/current behaviour |
| ----------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Task discovery | `archie.task.>` in `ARCHIE_TASKS` | Work-queue retention; daemon durable `archie-daemon`; max deliver 3 |
| Per-stage agent request | `archie.agent.<task>.request` | Reply inbox in `X-Archie-Reply`; wall-clock budget or 30m |
| Full task handoff | `archie.taskrun.<task-id>` | Core request/reply; no-responder retry 20s every 250ms |
| Store RPC | gRPC State Store (`internal/infrastructure/staterpc`) | Client timeout 60s (`rpcTimeout` in `internal/app/agentworker/worker.go`); task-scoped grants for Update/Transition/InsertEvent only |
| Forge RPC | `archie.forge.*` | Error travels in a JSON envelope |
| Worktree RPC | `archie.worktree.prepare`, `.push` | Server default handler bound 15m |
| Discovery dedup | `Nats-Msg-Id: archie:<owner>/<repo>/<issue>` | JetStream duplicate window 2m |
```bash
docker compose ps
@@ -122,7 +123,7 @@ env GOTMPDIR=/tmp GOCACHE=/tmp/archie-agent-unit-gocache \
go test ./internal/agentexec -run '^TestToolSetHandler' -count=1 -v
```
## Trace configuration from source to behavior
## Trace configuration from source to behaviour
Trace: `cmd/archied` (`internal/app/archied/bootstrap.go`) reads
`-config`/`-config-overlay` → `configuration.New(log)` + `Loader.Resolve`
@@ -141,25 +142,24 @@ The `config.Load`/`config.LoadDir` helpers are gone; decoding is
is a wiring gap, not a parser bug.
For environment failures:
- The host supervisor supplies the daemon environment; inspect its unit or
launch environment rather than Compose.
- `containerEnv` translates configured NATS token name into `NATS_TOKEN` and
forwards configured provider key variables.
- `SubprocessRunner` forwards default compatibility variables, configured
`[agent].env` names, and only the requested provider key.
- Top-level `[forge] token_env` is converted to an env `SecretRef` by
`finalize`; explicit `[forge.token]` wins.
Do not print secret values.
## Diagnose streaming, MCP, and Telegram
### Streaming
Must drain `stream.FullStream`, collect `core.StreamPartTextDelta`, check
`FinishReason`. `TextStream` is best-effort. **Fixed history:** consuming
`TextStream` while `FullStream` unread deadlocked every reply.
### MCP
Stdio framing is one compact JSON-RPC object per line. Stale
`internal/tools/mcp/types.go` comment mentions `Content-Length` — not the
implemented contract.
@@ -184,6 +184,7 @@ Gate: non-empty discovery with `start_process`, `interact_with_process`,
`read_process_output`.
### Telegram
Three command scopes in `internal/channels/telegram/commands.go`: default, all
private chats, all group chats. Narrower scope shadows default; state keyed by
bot token. Empty `allowed_user_ids` denies everyone.
@@ -199,33 +200,36 @@ env GOTMPDIR=/tmp GOCACHE=/tmp/archie-telegram-gocache \
## Diagnose state, events, containers, and optional features
### SQLite and transitions
`internal/store.Store.Transition` owns task state changes and transition
history: it guards on `from` (`WHERE id=? AND status=?`, returning
`store.ErrStaleTransition`) and writes status plus history in one transaction.
### Database and transitions
`internal/infrastructure/postgres.Store.Transition` owns task state changes and
transition history: it guards on `from`, returning
`storecontract.ErrStaleTransition`, and writes status plus history in one transaction.
When state is surprising: read `TaskByID` before/after caller; trace every
`Transition`, `Requeue`, `RecoverStale`, `Update` — and remember the daemon
exposes these over the gRPC State Store, not NATS.
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-state-gocache go test ./internal/store -count=1
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-state-gocache go test ./internal/infrastructure/postgres -count=1 # needs Docker
```
### Events
DB sink buffer 256; SSE client buffers 64. Drop counter not read in production.
Dashboard gap can coexist with correct task state.
### Containers, worktrees, and subprocess mode
Container-mode: clones on host, mounts `/data/worktree`, writes `.git/task.json`,
dedicated `archie.taskrun.<id>` subscription. **Open:** container RPC is
root-identity-bound; `SubprocessRunner` expects stdin JSON protocol.
### Optional feature degradation
| Feature | Current failure behavior |
|---|---|
| Daemon plugins | Warn and skip |
| Invalid MCP config | Warn and continue |
| Skill catalog | Warn, continue without tool |
| Worktree augmentation | Log error, use startup registry |
| Workspace indexing | **Open:** `indexing.NewManager` exists but has no production caller in `internal/app/archied` |
| Feature | Current failure behaviour |
| --------------------- | --------------------------------------------------------------------------------------------- |
| Daemon plugins | Warn and skip |
| Invalid MCP config | Warn and continue |
| Skill catalogue | Warn, continue without tool |
| Worktree augmentation | Log error, use startup registry |
| Workspace indexing | **Open:** `indexing.NewManager` exists but has no production caller in `internal/app/archied` |
@@ -79,12 +79,12 @@ go run "$skill/scripts/source-metrics.go" -root . -top 30
Read its tab-separated schema:
| Record | Columns after record name |
|---|---|
| `META` | key, value |
| `METRIC` | module, metric, integer |
| Record | Columns after record name |
| --------- | --------------------------------------------------------------------------------------------------------------- |
| `META` | key, value |
| `METRIC` | module, metric, integer |
| `PACKAGE` | module, directory, production files, test files, generated files, production lines, test lines, generated lines |
| `HOTSPOT` | module, file, declaration line, symbol, body-span lines, statement nodes, approximate syntactic complexity |
| `HOTSPOT` | module, file, declaration line, symbol, body-span lines, statement nodes, approximate syntactic complexity |
The defaults (80 body lines, complexity 15) mirror numeric triage points in
`.golangci.yml`. They do **not** implement `funlen` or `cyclop`. Run configured
@@ -135,8 +135,8 @@ marshalling) reports zero. Confirm each candidate by hand before calling a
field dead.
For every candidate: run `gopls references -d` on the exact field identifier;
trace decode → default → validation → normalization/copy → composition-root read
→ concrete component → observable behavior.
trace decode → default → validation → normalisation/copy → composition-root read
→ concrete component → observable behaviour.
### Measure delivery and hygiene drift
@@ -184,14 +184,14 @@ production-only, test-only, compatibility, generated, and unreachable paths
separately.
As of 2026-09-18, `Taskfile.yml` defines no `deadcode` task and `go tool` lists
no dead-code analyzer.
no dead-code analyser.
## Collect test, race, coverage, and runtime evidence
```sh
go test ./internal/store -count=1 -coverprofile=/tmp/archie-store.cover
go test ./internal/infrastructure/postgres -count=1 -coverprofile=/tmp/archie-store.cover
go tool cover -func=/tmp/archie-store.cover
go test -race ./internal/store -count=1
go test -race ./internal/infrastructure/postgres -count=1
```
As of 2026-09-18, the package reported 78.6% statement coverage and passed its
@@ -226,7 +226,7 @@ diff -u "$evidence_dir/delivery.tsv" "$after_dir/delivery.tsv"
If output differs from prediction: confirm checkout, dirty state, script
revision, flags, toolchain; explain each delta; branch to semantic discovery
when a count cannot explain behavior. Reject a "better" metric that moved
when a count cannot explain behaviour. Reject a "better" metric that moved
duplication, hid a path, or weakened a gate.
## Dated current snapshot
@@ -235,15 +235,15 @@ The bundled scripts measured this checkout on 2026-09-18 (HEAD `2e1e1549`).
These are post-fix numbers: earlier runs of the same scripts reported roughly
3x these file and line counts because they walked `.worktrees/`.
| Observation | Unstable value |
|---|---:|
| Root production/test/generated Go files | 408 / 402 / 9 |
| Root production/test/generated physical lines | 74,752 / 95,264 / 12,774 |
| `internal/app/archied.Run` body span / approximate complexity | 97 / 19 |
| Root internal packages / direct internal edges | 110 / 316 |
| Tagged config field rows | 194 |
| Tracked paths / tracked `node_modules` paths / tracked symlinks | 1,088 / 0 / 1 |
| `.dockerignore` present | 1 |
| Observation | Unstable value |
| --------------------------------------------------------------- | -----------------------: |
| Root production/test/generated Go files | 408 / 402 / 9 |
| Root production/test/generated physical lines | 74,752 / 95,264 / 12,774 |
| `internal/app/archied.Run` body span / approximate complexity | 97 / 19 |
| Root internal packages / direct internal edges | 110 / 316 |
| Tagged config field rows | 194 |
| Tracked paths / tracked `node_modules` paths / tracked symlinks | 1,088 / 0 / 1 |
| `.dockerignore` present | 1 |
`source-metrics.go` and `git ls-files` reconcile here: 408 + 9 generated
production files and 402 test files, plus the `tools` module's 5 / 2 / 0,
@@ -66,7 +66,7 @@ scan_literal github_container_publish github-workflows 'docker build|docker push
# file". The wiring lives in internal/app/archied.
scan_literal production_config_resolve composition-root 'configuration\.New\(' internal/app/archied
scan_literal production_config_load composition-root 'loadConfig\(|loadRuntimeConfig\(' internal/app/archied
scan_literal production_sqlite_store composition-root 'openProductionTaskStore\(|openStateStore\(' internal/app/archied
scan_literal production_task_store composition-root 'openStateStore\(' internal/app/archied
scan_literal production_daemon composition-root '&daemon\.Daemon\{' internal/app/archied
scan_literal production_rpc_servers composition-root 'registerTaskRPCServers\(' internal/app/archied
+51 -54
View File
@@ -5,7 +5,7 @@ description: Maintain Archie's documentation of record and write durable archite
# Maintain Archie documentation
Write one durable record for each decision or behavior. Separate what runs now
Write one durable record for each decision or behaviour. Separate what runs now
from what Archie has approved as its destination.
Route to `archie-architecture-planning-campaign` for ownership/boundary
@@ -22,14 +22,14 @@ for runtime/operations facts.
Define a **record of authority** as the one canonical location whose owner may
change a claim.
| State | Meaning | Permitted wording |
|---|---|---|
| `CURRENT` | Verified behavior in checked-out code, tests, composition, or executable config | "Currently does" |
| `APPROVED TARGET` | Normative destination approved in architecture index | "Must become"; never "currently does" |
| `OPEN` | Investigation, candidate, or unresolved decision | "Candidate", "unknown", or "requires decision" |
| `HISTORICAL` | Prior design, incident, dead end, or superseded choice | "Previously did" |
| `GENERATED` | Derivative output produced from owned source definition | "Generated from"; never hand-edit |
| `EXTERNAL` | Fact held outside repository, such as deployed config or host state | Date, name verifier, give re-check command |
| State | Meaning | Permitted wording |
| ----------------- | -------------------------------------------------------------------------------- | ---------------------------------------------- |
| `CURRENT` | Verified behaviour in checked-out code, tests, composition, or executable config | "Currently does" |
| `APPROVED TARGET` | Normative destination approved in architecture index | "Must become"; never "currently does" |
| `OPEN` | Investigation, candidate, or unresolved decision | "Candidate", "unknown", or "requires decision" |
| `HISTORICAL` | Prior design, incident, dead end, or superseded choice | "Previously did" |
| `GENERATED` | Derivative output produced from owned source definition | "Generated from"; never hand-edit |
| `EXTERNAL` | Fact held outside repository, such as deployed config or host state | Date, name verifier, give re-check command |
When `CURRENT` conflicts with `APPROVED TARGET`, preserve both and state the
migration delta.
@@ -38,43 +38,43 @@ migration delta.
Verified on 2026-09-18:
| Location | Role | Discipline |
|---|---|---|
| Live Go code, tests, `Taskfile.yml`, executable config parsing, composition under `internal/app/` (entered from `cmd/`) | `CURRENT` execution evidence | Trace producers and consumers; tests prove only asserted behavior |
| `CLAUDE.md` | Current contributor and safety protocol plus compact architecture orientation | Verify operational claims against code and `Taskfile.yml`; `AGENTS.md` is a symlink to it |
| `docs/prds/01-project-management.md` | Index and approved foundation for target architecture | Add or change target decisions in the focused document it names |
| `docs/architecture/*.md` | Focused target decisions, active review procedure, migration inventory | Read each file's status |
| `docs/architecture/migration-decisions.md` | `OPEN` migration inventory constrained by approved decisions | Close a question only after code-grounded review |
| `docs/archive/` | `HISTORICAL` material | Mine rationale and failure evidence |
| `CHANGELOG.md` | Release stream and packaged runtime input | One file holds every release; `internal/releaseannounce` parses version headings |
| `tools/docsgen` | Current, partial generator in nested `tools` Go module | Treat its flags and tests—not planned PRD commands—as executable truth |
| `docs/data/generated/contracts.json` | Current working-tree `GENERATED` output | Regenerate; never edit by hand |
| `docs/` | Repository documentation only | Nothing builds, renders, or publishes it; Markdown is the artifact |
| Location | Role | Discipline |
| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Live Go code, tests, `Taskfile.yml`, executable config parsing, composition under `internal/app/` (entered from `cmd/`) | `CURRENT` execution evidence | Trace producers and consumers; tests prove only asserted behaviour |
| `CLAUDE.md` | Current contributor and safety protocol plus compact architecture orientation | Verify operational claims against code and `Taskfile.yml`; `AGENTS.md` is a symlink to it |
| `docs/prds/01-project-management.md` | Index and approved foundation for target architecture | Add or change target decisions in the focused document it names |
| `docs/architecture/*.md` | Focused target decisions, active review procedure, migration inventory | Read each file's status |
| `docs/architecture/migration-decisions.md` | `OPEN` migration inventory constrained by approved decisions | Close a question only after code-grounded review |
| `docs/archive/` | `HISTORICAL` material | Mine rationale and failure evidence |
| `CHANGELOG.md` | Release stream and packaged runtime input | One file holds every release; `internal/releaseannounce` parses version headings |
| `tools/docsgen` | Current, partial generator in nested `tools` Go module | Treat its flags and tests—not planned PRD commands—as executable truth |
| `docs/data/generated/contracts.json` | Current working-tree `GENERATED` output | Regenerate; never edit by hand |
| `docs/` | Markdown sources and generated JSON for the external Astro website | This repository generates and validates artifacts; the website repository renders and deploys them |
The repository root has no `README.md` or `CONTRIBUTING.md` as of 2026-09-18.
## Choose one destination
1. State the reader's question.
2. Identify the owner of the behavior or decision.
2. Identify the owner of the behaviour or decision.
3. Find the existing record of authority.
4. Extend that record or link to it. Do not make a second canonical table.
5. If no owner exists, route the ownership decision through the architecture campaign.
6. If the fact is generated, change the owned source definition and generator.
7. If the fact is external, date it and name the exact observation command.
| Content | Destination |
|---|---|
| Cross-cutting approved architecture index | `docs/prds/01-project-management.md` |
| Content | Destination |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cross-cutting approved architecture index | `docs/prds/01-project-management.md` |
| New capability with no settled design yet (CLAUDE.md's "write a decisive doc before coding") | New `docs/prds/<capability>.md` — use the PRD template in `references/templates.md`, which folds in a multi-agent execution breakdown so the sub-issues can be picked up without re-deriving the design |
| Focused domain or requirement decision | Matching `docs/architecture/*.md` file |
| Unresolved migration question | `docs/architecture/migration-decisions.md` |
| Contributor protocol that must load before work | `CLAUDE.md` |
| Runtime/API/config reference derivable from code | Domain-owned registry/type, then `tools/docsgen` output |
| Repository documentation prose | `docs/`, linking back to authority with repository-relative paths |
| Shipped release behavior | Matching component changelog; keep `CHANGELOG.md` as two-component index |
| Superseded design retained for context | `docs/archive/`, with historical status |
| Incident or rejected approach | `archie-failure-archaeology`'s chronology |
| Focused domain or requirement decision | Matching `docs/architecture/*.md` file |
| Unresolved migration question | `docs/architecture/migration-decisions.md` |
| Contributor protocol that must load before work | `CLAUDE.md` |
| Runtime/API/config reference derivable from code | Domain-owned registry/type, then `tools/docsgen` output |
| Repository documentation prose | `docs/`, linking back to authority with repository-relative paths |
| Shipped release behaviour | Matching component changelog; keep `CHANGELOG.md` as two-component index |
| Superseded design retained for context | `docs/archive/`, with historical status |
| Incident or rejected approach | `archie-failure-archaeology`'s chronology |
Do not duplicate a package map across `CLAUDE.md`, a PRD, and
the site. Name the authoritative map and link to it.
@@ -94,7 +94,7 @@ Every architecture, feature, or migration record must answer:
- **Deletion gate:** What observable proof permits removal?
- **Evidence:** Which symbols, tests, commands, and runtime observations support
the record?
- **Rollback:** How can behavior and data return safely?
- **Rollback:** How can behaviour and data return safely?
- **Unresolved questions:** What remains `OPEN`?
Name one owner for every mutable record. A new path is incomplete until the
@@ -110,7 +110,7 @@ of authority; the command that re-discovers the evidence.
Write `internal/agentexec.Request` and `tools/docsgen.currentContractTypes`.
Distinguish evidence strength:
1. Runtime composition and executable behavior.
1. Runtime composition and executable behaviour.
2. Tests that exercise the relevant production seam.
3. Approved target decision.
4. Comments and summaries corroborated by the first three.
@@ -136,7 +136,7 @@ the CI shell gate plus `internal/releaseannounce`'s announcer tests
## Maintain generated contracts
Current behavior, verified 2026-09-18:
Current behaviour, verified 2026-09-18:
- Tool path is `tools/docsgen`, not `tools/cmd/docsgen`.
- Separate Go module replacing root module with `../`.
@@ -161,24 +161,22 @@ directory, so a failing gate never rewrites the artifact it judges. Fix a
failure with `task docs:generate` and commit the result with the code change
that shifted the contract surface.
## Store documentation as repository Markdown
## Maintain documentation consumed by the external Astro website
`docs/` is Markdown read directly in the repository, an editor, or the forge's
file view. Nothing builds, renders, or publishes it. The VitePress site, its
package manifest and lockfile, its landing page, and
`.github/workflows/docs.yml` were removed on 2026-09-12 as an unnecessary build
step; the publishing surface is an open decision
(`docs/architecture/generated-documentation.md`, "Rendering and publishing").
`docs/` holds Markdown sources and generated JSON consumed by the Astro website
at `offloaded.dev/docs/`. The website is maintained outside this repository.
This repository owns artifact generation and drift checks; it does not build,
preview, or deploy the website.
| Surface | Current state |
|---|---|
| Content | Markdown under `docs/`, including `docs/data/generated/contracts.json` |
| Links | Repository-relative (`../architecture/organisation.md`); no root-absolute links |
| Build | None. There is no site, no dev server, no link checker, no Pages deploy |
| Nav | `docs/prds/01-project-management.md` is the index; there is no site nav |
| Surface | Current state |
| ---------------- | ---------------------------------------------------------------------- |
| Content | Markdown under `docs/` and generated JSON under `docs/data/generated/` |
| Rendering | External Astro website consumes generated artifacts |
| Build and deploy | Owned by the Astro website repository |
| Local checks | `task docs:check`, `task docs:artifact:check`, and `task news:check` |
Because no build validates links, check them yourself or with a one-off script —
nothing catches a dead link for you:
The repository checks artifact drift, not the external site's rendered routes or
links. Verify those in the website repository.
```bash
# every relative markdown link target that does not resolve
@@ -187,9 +185,8 @@ grep -rhoE '\]\([^)#]+' docs --include=*.md | sed -E 's/^\]\(//' | sort -u
### Enforce source-artifact hygiene
Git tracks no `node_modules` entries (verified 2026-09-12; the 237 `docs/`
symlinks recorded on 2026-07-28 are gone) and no VitePress output. A future
renderer must not reintroduce committed installs or build output.
Git tracks no `node_modules` entries or website build output. The external Astro
repository owns its installed dependencies and generated site files.
```bash
git ls-files | grep -c node_modules # expect 0
@@ -15,7 +15,7 @@ sections. Keep facts, decisions, and open questions visibly separate.
## Architecture decision record
````markdown
```markdown
# <Decision title>
**Status:** Proposed | Approved | Superseded by <link>
@@ -34,8 +34,8 @@ sections. Keep facts, decisions, and open questions visibly separate.
## Current evidence
| Claim | Evidence |
|---|---|
| Claim | Evidence |
| ------------------ | ------------------------------------- |
| <CURRENT behavior> | `<path>` — `<symbol/test/config key>` |
## Constraints and invariants
@@ -44,15 +44,15 @@ sections. Keep facts, decisions, and open questions visibly separate.
## Consumers and boundaries
| Consumer | Contract used | Failure effect |
|---|---|---|
| <entry point/package/process> | <interface/command/event/data> | <effect> |
| Consumer | Contract used | Failure effect |
| ----------------------------- | ------------------------------ | -------------- |
| <entry point/package/process> | <interface/command/event/data> | <effect> |
## Options considered
| Option | Benefits | Costs and risks | Evidence | Result |
|---|---|---|---|---|
| <option> | <benefit> | <cost> | <measurement/source> | Accepted / Rejected |
| Option | Benefits | Costs and risks | Evidence | Result |
| -------- | --------- | --------------- | -------------------- | ------------------- |
| <option> | <benefit> | <cost> | <measurement/source> | Accepted / Rejected |
## Consequences
@@ -72,18 +72,18 @@ operational effects.>
## Open questions
| Question | Owner | Evidence required | Decision deadline/gate |
|---|---|---|---|
| <OPEN question> | <owner> | <measurement> | <gate> |
| Question | Owner | Evidence required | Decision deadline/gate |
| --------------- | ------- | ----------------- | ---------------------- |
| <OPEN question> | <owner> | <measurement> | <gate> |
## Validation
- `<exact command>` — expected <observable result>
````
```
## Migration plan and parity matrix
````markdown
```markdown
# <Capability> migration plan
**Status:** Proposed | Approved | In progress | Complete
@@ -99,24 +99,24 @@ change.>
## Current-path inventory
| Operation | Entry point | Owner today | State/data touched | Consumers | Disposition |
|---|---|---|---|---|---|
| <operation> | `<path.Symbol>` | <owner/none> | <state> | <consumers> | Keep / Adapt / Merge / Delete |
| Operation | Entry point | Owner today | State/data touched | Consumers | Disposition |
| ----------- | --------------- | ------------ | ------------------ | ----------- | ----------------------------- |
| <operation> | `<path.Symbol>` | <owner/none> | <state> | <consumers> | Keep / Adapt / Merge / Delete |
## Parity matrix
| Behavior | Current evidence | Target owner/path | Required parity | Test or observation | Status |
|---|---|---|---|---|---|
| <behavior> | `<test/symbol/log>` | <target> | <exact result> | `<command>` | OPEN |
| Behavior | Current evidence | Target owner/path | Required parity | Test or observation | Status |
| ---------- | ------------------- | ----------------- | --------------- | ------------------- | ------ |
| <behavior> | `<test/symbol/log>` | <target> | <exact result> | `<command>` | OPEN |
Include success, validation failure, retry, cancellation, crash recovery,
authorization, persistence, event emission, and shutdown where applicable.
## Dependency and data movement
| From | To | Adapter/backfill | Consistency rule | Rollback |
|---|---|---|---|---|
| <source> | <target> | <mechanism> | <invariant> | <method> |
| From | To | Adapter/backfill | Consistency rule | Rollback |
| -------- | -------- | ---------------- | ---------------- | -------- |
| <source> | <target> | <mechanism> | <invariant> | <method> |
## Slices and gates
@@ -141,9 +141,9 @@ authorization, persistence, event emission, and shutdown where applicable.
## Deletion gates
| Legacy path | Replacement proof | Consumer-zero proof | Data proof | Removal test |
|---|---|---|---|---|
| `<path.Symbol>` | <proof> | <search/inventory> | <proof> | `<command>` |
| Legacy path | Replacement proof | Consumer-zero proof | Data proof | Removal test |
| --------------- | ----------------- | ------------------- | ---------- | ------------ |
| `<path.Symbol>` | <proof> | <search/inventory> | <proof> | `<command>` |
## Rollback and stop conditions
@@ -153,10 +153,10 @@ authorization, persistence, event emission, and shutdown where applicable.
## Remaining open decisions
| Decision | Owner | Evidence needed | Blocks |
|---|---|---|---|
| <OPEN> | <owner> | <evidence> | <slice/cutover> |
````
| Decision | Owner | Evidence needed | Blocks |
| -------- | ------- | --------------- | --------------- |
| <OPEN> | <owner> | <evidence> | <slice/cutover> |
```
## Incident or dead-end record
@@ -185,9 +185,9 @@ Observed: <result>
## Investigation chronology
| Time/order | Hypothesis | Prediction | Evidence | Result |
|---|---|---|---|---|
| 1 | <hypothesis> | <expected observation> | `<command/log/test>` | Confirmed / Rejected |
| Time/order | Hypothesis | Prediction | Evidence | Result |
| ---------- | ------------ | ---------------------- | -------------------- | -------------------- |
| 1 | <hypothesis> | <expected observation> | `<command/log/test>` | Confirmed / Rejected |
## Root cause
@@ -195,9 +195,9 @@ Observed: <result>
## Attempted or rejected fixes
| Fix | Why plausible | Evidence against it | Status |
|---|---|---|---|
| <approach> | <reason> | <test/runtime evidence> | Rejected / Reverted |
| Fix | Why plausible | Evidence against it | Status |
| ---------- | ------------- | ----------------------- | ------------------- |
| <approach> | <reason> | <test/runtime evidence> | Rejected / Reverted |
## Resolution and invariant
@@ -213,7 +213,7 @@ Observed: <result>
## Feature ownership and deprecation record
````markdown
```markdown
# <Feature/capability> ownership
**Status:** Current | Migrating | Deprecated | Removed
@@ -229,31 +229,31 @@ Observed: <result>
## Complete path
| Layer | Path/symbol | Responsibility |
|---|---|---|
| Entry | `<path.Symbol>` | <role> |
| Domain | `<path.Symbol>` | <role> |
| State | `<path.Symbol>` | <role> |
| Adapter | `<path.Symbol>` | <role> |
| Composition | `<path.Symbol>` | <role> |
| Layer | Path/symbol | Responsibility |
| ----------- | --------------- | -------------- |
| Entry | `<path.Symbol>` | <role> |
| Domain | `<path.Symbol>` | <role> |
| State | `<path.Symbol>` | <role> |
| Adapter | `<path.Symbol>` | <role> |
| Composition | `<path.Symbol>` | <role> |
## Consumers
| Consumer | Contract | Configuration | Test evidence |
|---|---|---|---|
| <consumer> | <interface/event/data> | <key or none> | `<test>` |
| Consumer | Contract | Configuration | Test evidence |
| ---------- | ---------------------- | ------------- | ------------- |
| <consumer> | <interface/event/data> | <key or none> | `<test>` |
## Invariants and failures
| Invariant | Enforcement | Failure behavior | Test |
|---|---|---|---|
| <invariant> | `<path.Symbol>` | <result> | `<test>` |
| Invariant | Enforcement | Failure behavior | Test |
| ----------- | --------------- | ---------------- | -------- |
| <invariant> | `<path.Symbol>` | <result> | `<test>` |
## Duplicate and superseded paths
| Path | Same operation? | Disposition | Deletion gate |
|---|---|---|---|
| `<path.Symbol>` | Yes / No, because <reason> | Keep / Delegate / Migrate / Delete | <proof> |
| Path | Same operation? | Disposition | Deletion gate |
| --------------- | -------------------------- | ---------------------------------- | ------------- |
| `<path.Symbol>` | Yes / No, because <reason> | Keep / Delegate / Migrate / Delete | <proof> |
## Change checklist
@@ -263,11 +263,11 @@ Observed: <result>
- [ ] Add failure-path and architecture tests.
- [ ] Prove the replacement before deleting the old path.
- [ ] Update generated reference from owned definitions.
````
```
## Operational runbook
````markdown
```markdown
# Operate <service/capability>
**Status:** Current
@@ -293,9 +293,9 @@ Observed: <result>
## Health and outputs
| Signal | Location/command | Healthy result | Unhealthy branch |
|---|---|---|---|
| <signal> | `<command/path>` | <result> | <action> |
| Signal | Location/command | Healthy result | Unhealthy branch |
| -------- | ---------------- | -------------- | ---------------- |
| <signal> | `<command/path>` | <result> | <action> |
## Rollback
@@ -305,19 +305,19 @@ Observed: <result>
## Known failure modes
| Symptom | First measurement | Likely seam | Next runbook |
|---|---|---|---|
| <symptom> | `<command>` | <boundary> | <sibling skill/doc> |
| Symptom | First measurement | Likely seam | Next runbook |
| --------- | ----------------- | ----------- | ------------------- |
| <symptom> | `<command>` | <boundary> | <sibling skill/doc> |
## Provenance
- External fact observed by <who/how> on YYYY-MM-DD.
- Re-check: `<one-line command>`
````
```
## Documentation change review
````markdown
```markdown
# Documentation review: <scope>
**Date:** YYYY-MM-DD
@@ -326,15 +326,15 @@ Observed: <result>
## Classification
| Claim/change | State | Owner | Evidence |
|---|---|---|---|
| <claim> | CURRENT / APPROVED TARGET / OPEN / HISTORICAL / GENERATED / EXTERNAL | <owner> | `<path.Symbol/test/command>` |
| Claim/change | State | Owner | Evidence |
| ------------ | -------------------------------------------------------------------- | ------- | ---------------------------- |
| <claim> | CURRENT / APPROVED TARGET / OPEN / HISTORICAL / GENERATED / EXTERNAL | <owner> | `<path.Symbol/test/command>` |
## Findings
| Severity | Location | Problem | Evidence | Required correction |
|---|---|---|---|---|
| Blocking / Important / Minor | <heading/path> | <problem> | <evidence> | <fix> |
| Severity | Location | Problem | Evidence | Required correction |
| ---------------------------- | -------------- | --------- | ---------- | ------------------- |
| Blocking / Important / Minor | <heading/path> | <problem> | <evidence> | <fix> |
## Authority and duplication checks
@@ -354,15 +354,15 @@ Observed: <result>
## Validation evidence
| Command | Expected | Observed |
|---|---|---|
| Command | Expected | Observed |
| ----------------- | -------- | -------- |
| `<exact command>` | <result> | <result> |
## Residual uncertainty
<List unverified external facts, unavailable environments, or still-open
decisions. Never convert them into implied acceptance.>
````
```
## PRD: open capability design with multi-agent execution
@@ -390,7 +390,7 @@ The three failure modes this template exists to prevent:
existing call site that already proves the pattern (`internal/tools/minimax/tool.go`,
not "a tool like the video one").
````markdown
```markdown
# <Capability> capability design
Epic: `<bd id>` / GitHub `#<epic number>` ("<epic title>").
@@ -435,8 +435,8 @@ One section per sibling bead the epic lists as separate scope. Each one:
## Call site inventory
| concern | file | change |
|---|---|---|
| concern | file | change |
| --------- | -------- | ------------------------------------------------------------------ |
| <concern> | `<path>` | done (`#<issue>`) / new (`#<issue>`) / none — already handles this |
Every file any sub-feature touches, old or new, in one table — so an
@@ -449,9 +449,9 @@ One row per sub-feature section above. This is what turns the design into
something a `/council`-style review or a cheaper/faster implementer model
can run against directly instead of needing the full design re-explained.
| sub-feature | issue | implementer scope | suggested council lenses | why |
|---|---|---|---|---|
| <name> | `#<issue>` | <the call-site inventory rows this bead owns> | `lens-<key>`, `lens-<key>` | <one clause: what that lens actually catches for this slice — e.g. lens-contract for a new provider error-mapping table, lens-operator for a backend-down failure path, lens-deletionist when the section's whole point is "don't rebuild what exists", lens-boundary for a new domain/infra split, lens-maintainer for a new user-facing state machine> |
| sub-feature | issue | implementer scope | suggested council lenses | why |
| ----------- | ---------- | --------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <name> | `#<issue>` | <the call-site inventory rows this bead owns> | `lens-<key>`, `lens-<key>` | <one clause: what that lens actually catches for this slice — e.g. lens-contract for a new provider error-mapping table, lens-operator for a backend-down failure path, lens-deletionist when the section's whole point is "don't rebuild what exists", lens-boundary for a new domain/infra split, lens-maintainer for a new user-facing state machine> |
Pick lenses from the five in `.claude/workflows/council.js`
(`boundary`, `contract`, `deletionist`, `operator`, `maintainer`) by what the
@@ -482,4 +482,4 @@ if the epic didn't pre-file its sub-issues):
- Add the suggested lenses from the Execution table as a line on the issue
itself, so picking it up needs no round-trip back to this doc to know
which `/council` lenses to run before it's done.
````
```
+99 -99
View File
@@ -17,12 +17,12 @@ target packages now exist and are production-wired (`internal/domain/messaging`,
(`internal/domain/agent`, `internal/domain/identity`, `internal/policy`). Never
blend the two.
| Label | Meaning | Evidence rule |
| --- | --- | --- |
| **CURRENT** | Behavior present in live code and tests | Cite defining type/function and production caller or test. |
| **APPROVED TARGET** | Normative rule in approved foundation document | Cite exact PRD. Do not claim implemented. |
| **OPEN/CANDIDATE** | Deferred API, owner, package, migration, or behavior | Preserve open question. |
| **ARCHIVED** | Historical context under `docs/archive/` | Use only for archaeology. |
| Label | Meaning | Evidence rule |
| ------------------- | ----------------------------------------------------- | ---------------------------------------------------------- |
| **CURRENT** | Behaviour present in live code and tests | Cite defining type/function and production caller or test. |
| **APPROVED TARGET** | Normative rule in approved foundation document | Cite exact PRD. Do not claim implemented. |
| **OPEN/CANDIDATE** | Deferred API, owner, package, migration, or behaviour | Preserve open question. |
| **ARCHIVED** | Historical context under `docs/archive/` | Use only for archaeology. |
Start design notes with status sentences:
@@ -41,35 +41,35 @@ rg -n '^\*\*Status:\*\*|^## Decisions still required' docs/architecture
## Use the canonical actor vocabulary
| Term | Archie meaning | State and owner |
| --- | --- | --- |
| **Identity** | Durable actor reference for ownership, attribution, routing, commands, events, audit. | **APPROVED TARGET:** `internal/domain/identity`. **CURRENT:** configured names and empty strings act as identifiers. |
| **User** | Person represented as `user` kind of Identity. | **APPROVED TARGET:** Identity domain. |
| **Agent** | Persistent assistant with acting IdentityID, specialization, instructions, capability context, memory. | **CONFIRMED TARGET:** Agent and Identity separate aggregates; `internal/domain/agent` confirmed in `migration-decisions.md`. |
| **Model invocation** | One call through LLM provider/runtime. Replaceable execution machinery. | **CURRENT:** runtime packages. **TARGET:** infrastructure behind Agent-owned behavior. |
| **System identity** | One permanent actor for startup, migration, supervision, rollback. | **APPROVED TARGET:** a real IdentityID. |
| Term | Archie meaning | State and owner |
| -------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| **Identity** | Durable actor reference for ownership, attribution, routing, commands, events, audit. | **APPROVED TARGET:** `internal/domain/identity`. **CURRENT:** configured names and empty strings act as identifiers. |
| **User** | Person represented as `user` kind of Identity. | **APPROVED TARGET:** Identity domain. |
| **Agent** | Persistent assistant with acting IdentityID, specialisation, instructions, capability context, memory. | **CONFIRMED TARGET:** Agent and Identity separate aggregates; `internal/domain/agent` confirmed in `migration-decisions.md`. |
| **Model invocation** | One call through LLM provider/runtime. Replaceable execution machinery. | **CURRENT:** runtime packages. **TARGET:** infrastructure behind Agent-owned behaviour. |
| **System identity** | One permanent actor for startup, migration, supervision, rollback. | **APPROVED TARGET:** a real IdentityID. |
Apply: record acting Agent identity and initiating user identity separately;
never authorize because two mutable strings match; never rename Agent when only
never authorise because two mutable strings match; never rename Agent when only
model/provider/display name changes; never pool two Agents' memory.
```bash
rg -n 'type IdentityConfig|type IdentityRunner|Identity string|BotUser string' internal/config internal/daemon internal/store internal/gateway
rg -n 'type IdentityConfig|type IdentityRunner|Identity string|BotUser string' internal/config internal/daemon internal/infrastructure/postgres internal/gateway
```
## Use the canonical interaction vocabulary
| Term | Archie meaning | State and owner |
| --- | --- | --- |
| **Channel** | External interaction source (Telegram, email, webhook, forge). | **CURRENT:** `internal/channels` extends `gateway.Gateway`. **TARGET:** infrastructure adapter for Messaging. |
| **Adapter** | Boundary code translating external payloads into owned contracts. | **TARGET RULE:** infrastructure implements domain-owned interfaces. |
| **Gateway** | Current technical interface/router and package — not approved domain vocabulary. | **CURRENT ONLY:** `internal/gateway`, `internal/channels`. |
| **ChannelBindingID** | Stable reference connecting Agent to channel binding. | **APPROVED TARGET INPUT:** part of Conversation identity. |
| **Message** | Immutable application record with MessageID and typed content. Platform IDs are external correlations. | **CURRENT:** `internal/domain/messaging.Message`/`MessageID`; `gateway.MessageEvent` is a richer event type beside it. |
| **Conversation** | AgentID + UserIdentityID + ChannelBindingID + ExternalConversationID + ThreadID. | **CONFIRMED TARGET, partly current:** `internal/domain/messaging.Conversation`/`ConversationID` exist; the gateway session store still lacks canonical Agent/user IDs. |
| **Conversation branch** | Child conversation from one immutable parent message. | **CONFIRMED TARGET.** No current implementation. |
| **Work Intake** | Admission, validation, routing boundary between interaction and durable workflow-backed work. | **CONFIRMED TARGET, current package:** `internal/domain/workintake` exists. |
| **Accepted work request** | Channel-neutral handoff after Work Intake accepts proposed outcome. | **TARGET HANDOFF:** Agent System consumes it, selects Workflow version, creates WorkflowExecution. |
| Term | Archie meaning | State and owner |
| ------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Channel** | External interaction source (Telegram, email, webhook, forge). | **CURRENT:** `internal/channels` extends `gateway.Gateway`. **TARGET:** infrastructure adapter for Messaging. |
| **Adapter** | Boundary code translating external payloads into owned contracts. | **TARGET RULE:** infrastructure implements domain-owned interfaces. |
| **Gateway** | Current technical interface/router and package — not approved domain vocabulary. | **CURRENT ONLY:** `internal/gateway`, `internal/channels`. |
| **ChannelBindingID** | Stable reference connecting Agent to channel binding. | **APPROVED TARGET INPUT:** part of Conversation identity. |
| **Message** | Immutable application record with MessageID and typed content. Platform IDs are external correlations. | **CURRENT:** `internal/domain/messaging.Message`/`MessageID`; `gateway.MessageEvent` is a richer event type beside it. |
| **Conversation** | AgentID + UserIdentityID + ChannelBindingID + ExternalConversationID + ThreadID. | **CONFIRMED TARGET, partly current:** `internal/domain/messaging.Conversation`/`ConversationID` exist; the gateway session store still lacks canonical Agent/user IDs. |
| **Conversation branch** | Child conversation from one immutable parent message. | **CONFIRMED TARGET.** No current implementation. |
| **Work Intake** | Admission, validation, routing boundary between interaction and durable workflow-backed work. | **CONFIRMED TARGET, current package:** `internal/domain/workintake` exists. |
| **Accepted work request** | Channel-neutral handoff after Work Intake accepts proposed outcome. | **TARGET HANDOFF:** Agent System consumes it, selects Workflow version, creates WorkflowExecution. |
Do not equate an inbound Message with work. An Agent may answer, use
capabilities, retain information, or propose work without creating a
@@ -87,19 +87,19 @@ Do not describe current `/spawn` as this target. It directly creates a
`task.Task` with synthetic forge issue number.
```bash
rg -n 'type Message struct|type MessageEvent struct|ToLegacy|type Conversation struct|CreateTask|EnqueueChatTask|synthetic' internal/domain/messaging internal/gateway internal/store internal/app/archied
rg -n 'type Message struct|type MessageEvent struct|ToLegacy|type Conversation struct|CreateTask|EnqueueChatTask|synthetic' internal/domain/messaging internal/gateway internal/infrastructure/postgres internal/app/archied
```
## Use the canonical execution vocabulary
| Term | Archie meaning | Current representation |
| --- | --- | --- |
| **Workflow** | Reusable, versioned definition. | `workflow.Workflow` is named `[]Stage` without durable version model. |
| **WorkflowExecution** | One durable execution of one Workflow version. | `task.Task` is migration baseline. |
| **WorkflowStep** | One defined operation. | `workflow.Stage` is closest definition. |
| **StepExecution** | Durable record of one step's execution and outcome. | Missing; `task.Task.Stage` is one mutable string. |
| **Attempt** | Retry within same WorkflowExecution. | `task.Task.Attempt`/`RetryCount` must become explicit attempt history. |
| **Agent step execution** | One bounded model-backed WorkflowStep invocation. | `agentexec.Request`/`Result` correlate TaskID, Attempt, Stage, protocol version. |
| Term | Archie meaning | Current representation |
| ------------------------ | --------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Workflow** | Reusable, versioned definition. | `workflow.Workflow` is named `[]Stage` without durable version model. |
| **WorkflowExecution** | One durable execution of one Workflow version. | `task.Task` is migration baseline. |
| **WorkflowStep** | One defined operation. | `workflow.Stage` is closest definition. |
| **StepExecution** | Durable record of one step's execution and outcome. | Missing; `task.Task.Stage` is one mutable string. |
| **Attempt** | Retry within same WorkflowExecution. | `task.Task.Attempt`/`RetryCount` must become explicit attempt history. |
| **Agent step execution** | One bounded model-backed WorkflowStep invocation. | `agentexec.Request`/`Result` correlate TaskID, Attempt, Stage, protocol version. |
Use `WorkflowExecution` in domain contracts, architecture, generated reference.
Retain `task` only for Task build tool, forge product nouns in adapters,
@@ -119,27 +119,27 @@ running after crash -> queued
```
Do not claim enforced. `Store.Transition` now guards on `from`
(`WHERE id=? AND status=?` → `store.ErrStaleTransition`) and writes status plus
(→ `storecontract.ErrStaleTransition`) and writes status plus
history in one transaction; the sentinel crosses the State Store gRPC boundary.
See `internal/store/store.go`.
See `internal/infrastructure/postgres/store.go`.
```bash
rg -n 'Status[A-Za-z]+|func \(s \*Store\) Transition|func \(s \*Store\) Requeue|RecoverStale' internal/store internal/domain/workflow internal/gateway
rg -n 'Status[A-Za-z]+|func \(s \*Store\) Transition|func \(s \*Store\) Requeue|RecoverStale' internal/infrastructure/postgres internal/domain/workflow internal/gateway
```
## Keep memory scope separate from conversation scope
| Scope | Address and visibility |
| --- | --- |
| **Global shared** | Intentionally visible across Archie. |
| **Agent-wide** | Owned by one Agent, private by default even across users. |
| **User-wide** | One user across authorized Agents. |
| **Agent-user relationship** | Addressed by both AgentID and User IdentityID. |
| Scope | Address and visibility |
| --------------------------- | --------------------------------------------------------- |
| **Global shared** | Intentionally visible across Archie. |
| **Agent-wide** | Owned by one Agent, private by default even across users. |
| **User-wide** | One user across authorised Agents. |
| **Agent-user relationship** | Addressed by both AgentID and User IdentityID. |
Conversation branch is not a fifth memory scope. Scope mechanics **OPEN** beyond
these constraints.
Current `MemoryProvider` initializes with session ID, contains no explicit
Current `MemoryProvider` initialises with session ID, contains no explicit
AgentID, User IdentityID, or scope parameter. Built-in provider separates
`MEMORY.md` and `USER.md` under one directory — not the four-scope target model.
@@ -149,12 +149,12 @@ rg -n 'type MemoryProvider|Initialize\(|type Config struct|MEMORY.md|USER.md|Age
## Distinguish extension terms
| Term | Meaning |
| --- | --- |
| **Plugin** | Removable module with identity, metadata, compatibility, lifecycle. Generic `plugin.Plugin` must remain metadata-only. |
| **Capability family** | One cohesive typed behavior owned by its domain or approved manager/registry. |
| **Engine** | Typed, lifecycle-managed capability family with owning Registry or Manager. |
| **Host** | Current cross-family lifecycle/manifest coordinator in `internal/plugin`. Must not become service locator. |
| Term | Meaning |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Plugin** | Removable module with identity, metadata, compatibility, lifecycle. Generic `plugin.Plugin` must remain metadata-only. |
| **Capability family** | One cohesive typed behaviour owned by its domain or approved manager/registry. |
| **Engine** | Typed, lifecycle-managed capability family with owning Registry or Manager. |
| **Host** | Current cross-family lifecycle/manifest coordinator in `internal/plugin`. Must not become service locator. |
Give plugin only narrow typed registrars and explicitly supplied contracts.
@@ -164,15 +164,15 @@ go test ./internal/plugin -run 'Test(EngineFamilyInspectionRejectsInvalidShapes|
## Distinguish ownership and boundary terms
| Term | Archie-specific rule |
| --- | --- |
| **Domain** | Own one cohesive responsibility: vocabulary, state, rules, operations, commands, events, policies, runtime settings, required service contracts. |
| **Command** | Request an action. Receiving domain owns contract and decides result. |
| **Domain event** | Record something that happened. Publishing domain owns schema. |
| **Event bus** | Broker-neutral delivery/lifecycle contract. `internal/eventbus` exists and is production-wired. |
| **Observability event** | `internal/events.Event` projection input. Bounded in-process bus may drop. Not authoritative state. |
| **Policy** | Typed rule evaluated through shared mechanics. Consuming domain owns vocabulary. |
| **Infrastructure** | Implements domain-owned ports, translates DBs, brokers, SDKs, files, containers. |
| Term | Archie-specific rule |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Domain** | Own one cohesive responsibility: vocabulary, state, rules, operations, commands, events, policies, runtime settings, required service contracts. |
| **Command** | Request an action. Receiving domain owns contract and decides result. |
| **Domain event** | Record something that happened. Publishing domain owns schema. |
| **Event bus** | Broker-neutral delivery/lifecycle contract. `internal/eventbus` exists and is production-wired. |
| **Observability event** | `internal/events.Event` projection input. Bounded in-process bus may drop. Not authoritative state. |
| **Policy** | Typed rule evaluated through shared mechanics. Consuming domain owns vocabulary. |
| **Infrastructure** | Implements domain-owned ports, translates DBs, brokers, SDKs, files, containers. |
| **Application composition** | Chooses implementations, translates config, connects contracts, orders startup/shutdown. Current and target: `internal/app`; `cmd/*` stays process-input-only. |
As of 2026-09-18, `internal/domain`, `internal/eventbus`,
@@ -186,54 +186,54 @@ for p in internal/domain internal/eventbus internal/policy internal/infrastructu
## Distinguish forge, repository, workspace, gate, and agent boundaries
| Term | Owns | Must not own |
| --- | --- | --- |
| **Forge** | External code-host ops: issues, comments, labels, PRs, reactions. | Workflow lifecycle, canonical identity, work admission. |
| **Repository** | External source repo identity and repo-specific policy. | Mutable execution workspace or WorkflowExecution identity. |
| **Worktree/workspace** | Isolated files, branch, diff, commit, push, cleanup for one execution. | Agent/domain identity or forge issue lifecycle. |
| **Gate** | Deterministic evidence and constraints over execution. | Prompt advice model may waive. |
| **Agent execution boundary** | Versioned, validated data entering/leaving one unprivileged stage. | Daemon internals, forge tokens, direct git, workflow orchestration. |
| Term | Owns | Must not own |
| ---------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Forge** | External code-host ops: issues, comments, labels, PRs, reactions. | Workflow lifecycle, canonical identity, work admission. |
| **Repository** | External source repo identity and repo-specific policy. | Mutable execution workspace or WorkflowExecution identity. |
| **Worktree/workspace** | Isolated files, branch, diff, commit, push, cleanup for one execution. | Agent/domain identity or forge issue lifecycle. |
| **Gate** | Deterministic evidence and constraints over execution. | Prompt advice model may waive. |
| **Agent execution boundary** | Versioned, validated data entering/leaving one unprivileged stage. | Daemon internals, forge tokens, direct git, workflow orchestration. |
Model never runs git directly. Worktree operations are daemon-owned.
## Map current names before adding or migrating behavior
## Map current names before adding or migrating behaviour
| Current name/path | Target meaning | Migration warning |
| --- | --- | --- |
| `config.IdentityConfig.Name` | Canonical IdentityID plus separate bindings | Do not preserve mutable display name as ID. |
| `config.IdentityConfig.BotUser` | Forge/Git or channel external binding | Not Conversation or Agent identity. |
| `daemon.IdentityRunner` | Composition of identity-correlated capabilities | Currently service bundle, not Identity aggregate. |
| `gateway.MessageEvent` | Canonical Messaging Message | Choose one immutable typed contract; `internal/domain/messaging.Message` is the target. |
| gateway session context | Conversation metadata | Add canonical Agent/user/binding ownership. |
| forge `Issue` or future Jira item | Channel message or external artifact | Preserve native reference in adapter. |
| gateway `/spawn` and `TaskCreator` | Proposed/accepted work handoff | Work Intake admits; Agent System creates execution. |
| `store.Task` | WorkflowExecution | Preserve every field intentionally; the type now lives at `internal/domain/workflow/task.Task`. |
| `workflow.Workflow` | Versioned Workflow definition | Add identity/version ownership before parity. |
| `workflow.Stage` | WorkflowStep definition | A definition is not execution history. |
| mutable `Task.Stage` | Derived position plus StepExecution records | Deletion requires proven history parity. |
| `task.Task.Attempt`, `RetryCount` | Attempt history and retry evidence | Keep worker delivery retries distinct. |
| `workflow.TaskContext` | Execution state plus narrow step ports | Remove global config/service bag. |
| `events.Event` and `Bus` | Projections fed by authoritative domain events | Current drops acceptable for observability, not state. |
| `cmd/archied` wiring | `internal/app/archied` composition | Keep `cmd/*` process-input-only. |
| NATS/RPC/store/forge/worktree | Infrastructure adapters | Process boundaries don't decide domain ownership. |
| Current name/path | Target meaning | Migration warning |
| ---------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `config.IdentityConfig.Name` | Canonical IdentityID plus separate bindings | Do not preserve mutable display name as ID. |
| `config.IdentityConfig.BotUser` | Forge/Git or channel external binding | Not Conversation or Agent identity. |
| `daemon.IdentityRunner` | Composition of identity-correlated capabilities | Currently service bundle, not Identity aggregate. |
| `gateway.MessageEvent` | Canonical Messaging Message | Choose one immutable typed contract; `internal/domain/messaging.Message` is the target. |
| gateway session context | Conversation metadata | Add canonical Agent/user/binding ownership. |
| forge `Issue` or future Jira item | Channel message or external artifact | Preserve native reference in adapter. |
| gateway `/spawn` and `TaskCreator` | Proposed/accepted work handoff | Work Intake admits; Agent System creates execution. |
| `store.Task` | WorkflowExecution | Preserve every field intentionally; the type now lives at `internal/domain/workflow/task.Task`. |
| `workflow.Workflow` | Versioned Workflow definition | Add identity/version ownership before parity. |
| `workflow.Stage` | WorkflowStep definition | A definition is not execution history. |
| mutable `Task.Stage` | Derived position plus StepExecution records | Deletion requires proven history parity. |
| `task.Task.Attempt`, `RetryCount` | Attempt history and retry evidence | Keep worker delivery retries distinct. |
| `workflow.TaskContext` | Execution state plus narrow step ports | Remove global config/service bag. |
| `events.Event` and `Bus` | Projections fed by authoritative domain events | Current drops acceptable for observability, not state. |
| `cmd/archied` wiring | `internal/app/archied` composition | Keep `cmd/*` process-input-only. |
| NATS/RPC/store/forge/worktree | Infrastructure adapters | Process boundaries don't decide domain ownership. |
`migration-decisions.md` leaves memory, tools, workspaces, gates, storage,
events, web UI, containers, RPC, release management, scheduling pending.
## Recognize terminology-driven bugs
## Recognise terminology-driven bugs
| Incorrect shortcut | Resulting bug |
| --- | --- |
| "A forge issue is a Task" | Chat needs synthetic issues; uniqueness/dedup stay forge-shaped. |
| "Agent and Identity are same config object" | Model/persona changes alter attribution; mutable string equality becomes access control. |
| "Every Message is work" | Conversational turns forced through durable workflow lifecycle. |
| "Accepted request is already a WorkflowExecution" | Intake bypasses version selection and constructs invalid state. |
| "Stage is StepExecution" | Overwriting one string destroys step outcomes and audit history. |
| "NATS retry is another Attempt" | Transport availability changes domain retry counts. |
| "Event bus owns events" | Broker subjects become domain vocabulary; meaning drifts by consumer. |
| "Branch is a memory scope" | Returning to parent hides/duplicates durable learning. |
| "Engine means another generic plugin hook" | Capability ownership becomes untyped; plugins gain service-locator access. |
| "Configuration owns the feature" | Cross-concern config becomes de facto domain. |
| Incorrect shortcut | Resulting bug |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| "A forge issue is a Task" | Chat needs synthetic issues; uniqueness/dedup stay forge-shaped. |
| "Agent and Identity are same config object" | Model/persona changes alter attribution; mutable string equality becomes access control. |
| "Every Message is work" | Conversational turns forced through durable workflow lifecycle. |
| "Accepted request is already a WorkflowExecution" | Intake bypasses version selection and constructs invalid state. |
| "Stage is StepExecution" | Overwriting one string destroys step outcomes and audit history. |
| "NATS retry is another Attempt" | Transport availability changes domain retry counts. |
| "Event bus owns events" | Broker subjects become domain vocabulary; meaning drifts by consumer. |
| "Branch is a memory scope" | Returning to parent hides/duplicates durable learning. |
| "Engine means another generic plugin hook" | Capability ownership becomes untyped; plugins gain service-locator access. |
| "Configuration owns the feature" | Cross-concern config becomes de facto domain. |
Reject in review: a second parallel model without bounded cutover; status string
copied into consumer; mutable display name as durable ID; service bag passed
@@ -17,14 +17,14 @@ Route to `archie-debugging-playbook` for active symptoms,
## Use the status taxonomy exactly
| Status | Meaning |
|---|---|
| `settled` (`fixed`) | The failure, cause, resolution, and live replacement are proven. |
| `current` | The checked-out authoritative path still contains the behavior or contradiction. |
| `open` | The defect is evidenced, but no accepted and integrated resolution. |
| `conditional` | A fix is proven only for the named configuration, execution mode, peer, or assembly. |
| `superseded` | A mechanism was intentionally replaced. |
| `candidate` | A branch, proposal, or partial implementation may help but is not accepted. |
| Status | Meaning |
| ------------------- | ------------------------------------------------------------------------------------ |
| `settled` (`fixed`) | The failure, cause, resolution, and live replacement are proven. |
| `current` | The checked-out authoritative path still contains the behaviour or contradiction. |
| `open` | The defect is evidenced, but no accepted and integrated resolution. |
| `conditional` | A fix is proven only for the named configuration, execution mode, peer, or assembly. |
| `superseded` | A mechanism was intentionally replaced. |
| `candidate` | A branch, proposal, or partial implementation may help but is not accepted. |
Never use `settled` to mean "a fix commit exists."
@@ -45,7 +45,7 @@ Capture: first wrong observable result; last confirmed-good boundary; process
mode; active config and deployment assembly; whether deterministic,
load-dependent, or production-only.
### 3. Trace current behavior before history
### 3. Trace current behaviour before history
```sh
rg -n '<symptom|symbol|setting|error>' cmd internal config*.toml docker-compose.yml docs
@@ -86,15 +86,15 @@ of the commit graph:
`<base-ref>` defaults to `origin/main`; name `gitea/main` or `HEAD` when that is
the trunk you mean, and `git fetch` first so the fast path is not stale.
| Exit | Meaning |
|---|---|
| `0` | Ancestor of `<base-ref>`, or recorded in a merged pull request — landed |
| `1` | On GitHub, in no merged pull request — not landed |
| `2` | Bad ref, no `gh`, offline, never pushed — **undetermined, not a negative** |
| Exit | Meaning |
| ---- | -------------------------------------------------------------------------- |
| `0` | Ancestor of `<base-ref>`, or recorded in a merged pull request — landed |
| `1` | On GitHub, in no merged pull request — not landed |
| `2` | Bad ref, no `gh`, offline, never pushed — **undetermined, not a negative** |
Branch on the code explicitly; `if on-main.sh <ref>; then` folds `2` into "not
landed", which is the error this helper exists to prevent. It answers "did *this
ref* land", not "did this work land" — a change reimplemented on another branch
landed", which is the error this helper exists to prevent. It answers "did _this
ref_ land", not "did this work land" — a change reimplemented on another branch
still reads `not-landed` for the original commit.
Read parent version when failure is semantic:
@@ -106,14 +106,14 @@ git show <commit>:<path>
Require all six fields in an incident packet:
| Field | Required content |
|---|---|
| Symptom | Operator, user, test, or protocol observation |
| Attempted solution | What was tried before or during the failure |
| Root cause | The violated contract or mistaken assumption |
| Evidence | Commit, live path, test, trace, or production observation |
| Current status | One taxonomy value, dated when volatile |
| Settled rule | A constraint future work must preserve |
| Field | Required content |
| ------------------ | --------------------------------------------------------- |
| Symptom | Operator, user, test, or protocol observation |
| Attempted solution | What was tried before or during the failure |
| Root cause | The violated contract or mistaken assumption |
| Evidence | Commit, live path, test, trace, or production observation |
| Current status | One taxonomy value, dated when volatile |
| Settled rule | A constraint future work must preserve |
### 5. Reproduce narrowly, then route
@@ -121,88 +121,88 @@ Require all six fields in an incident packet:
env GOCACHE=/tmp/archie-archaeology-gocache GOTMPDIR=/tmp go test ./internal/<package> -run '^TestName$' -count=1 -v
```
If current behavior differs from chronicle, update the packet.
If current behaviour differs from chronicle, update the packet.
## Match symptoms to known incidents
| Symptom | Start with |
|---|---|
| `nats: no responders available for request` only from agent containers | Container network incident |
| Daemon crash-loops after config/schema work | SecretRef compatibility and Compose passthrough incidents |
| Stream shows empty cursor or first token, then hangs | FullStream/TextStream incident |
| MCP unit tests pass but real SDK server hangs | MCP framing and mirrored-peer incident |
| Telegram shows old commands after menu update | Telegram server-side scope incident |
| Tool discovery deadlocks, aliases mutate, or bad plugin hides rest | Tool-registry adversarial findings |
| Hidden `<memory>` content appears at end of truncated stream | Scrubber `Flush` leak |
| Broad lint cleanup compiles poorly while tests pass | Autofix, `nilerr`, and `308c199` incidents |
| Reused worktree is stale, half-prepared, or coupled to expired objects | Worktree/askpass/cache history |
| Repeated `fix: baseline gate repair` commits or parked tasks cycle | Baseline, no-op, and retry-loop incidents |
| CI cannot resolve `/work/apps/...` | Local module replacement incident |
| Build caches or dependency trees appear in diff | `.gotmp` and `node_modules` incidents |
| `diff_cap_lines = 0` still behaves as 400 | Diff-cap zero contradiction |
| Symptom | Start with |
| ---------------------------------------------------------------------- | --------------------------------------------------------- |
| `nats: no responders available for request` only from agent containers | Container network incident |
| Daemon crash-loops after config/schema work | SecretRef compatibility and Compose passthrough incidents |
| Stream shows empty cursor or first token, then hangs | FullStream/TextStream incident |
| MCP unit tests pass but real SDK server hangs | MCP framing and mirrored-peer incident |
| Telegram shows old commands after menu update | Telegram server-side scope incident |
| Tool discovery deadlocks, aliases mutate, or bad plugin hides rest | Tool-registry adversarial findings |
| Hidden `<memory>` content appears at end of truncated stream | Scrubber `Flush` leak |
| Broad lint cleanup compiles poorly while tests pass | Autofix, `nilerr`, and `308c199` incidents |
| Reused worktree is stale, half-prepared, or coupled to expired objects | Worktree/askpass/cache history |
| Repeated `fix: baseline gate repair` commits or parked tasks cycle | Baseline, no-op, and retry-loop incidents |
| CI cannot resolve `/work/apps/...` | Local module replacement incident |
| Build caches or dependency trees appear in diff | `.gotmp` and `node_modules` incidents |
| `diff_cap_lines = 0` still behaves as 400 | Diff-cap zero contradiction |
## Chronicle: work intake and retry loops
| Incident and date | Symptom | Root cause | Evidence and status | Settled rule |
|---|---|---|---|---|
| Label auto-claim, 2026-07-22 | >80 labelled issues enrolled under label polling. | Label polling means eligibility, not hint. | `519882f` changed the Compose profile to `assignee`; that file was deleted (`cbb7929e`) and survives as `deployments/docker-nats-stack.toml`, which sets `trigger = "assignee"`. `internal/config/config.go` defaults to `assignee` but permits `label` and `either`. **Status:** `settled`. | Default to assignee-driven pickup. Label/either are deliberate bulk enrollment. |
| Baseline-red park storm, 2026-07-23 onward | Task parks on gate failure that existed before its feature work. | Parking/retrying cannot change pre-existing failure; auto-repair mixes repository repair into feature scope. | `b2482af` made `StageBaselineGate` launch builder instead of parking. Nine repair commits in history. **Status:** `current` mitigation and architecture weak point. | Measure untouched baseline first. Track baseline repair as explicit change. |
| Passed build with zero changes, 2026-07-23 | Commit-push reports "no changes," parks, retries, repeats. | "Passed with no changes" lacked terminal domain outcome. | `62c0df1` introduced no-op detection; `2bf42bd` set `Outcome`. `TestStageCommitPushClosesIssueWhenBuildNoChanges`. **Status:** `settled`. | Model no-op as explicit terminal result. |
| Infinite parked-task retry, 2026-07-23 | Removing parked label repeatedly requeues with no terminal bound. | Retry count not durable or capped. | `a8fdb50` added persisted `retry_count`, global/per-repo `max_retries`, and `dead`. **Status:** `settled`. | Every autonomous retry needs durable attempt state, explicit bound, terminal state, and operator-visible reason. |
| Incident and date | Symptom | Root cause | Evidence and status | Settled rule |
| ------------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Label auto-claim, 2026-07-22 | >80 labelled issues enrolled under label polling. | Label polling means eligibility, not hint. | `519882f` changed the Compose profile to `assignee`; that file was deleted (`cbb7929e`) and survives as `deployments/docker-nats-stack.toml`, which sets `trigger = "assignee"`. `internal/config/config.go` defaults to `assignee` but permits `label` and `either`. **Status:** `settled`. | Default to assignee-driven pickup. Label/either are deliberate bulk enrolment. |
| Baseline-red park storm, 2026-07-23 onward | Task parks on gate failure that existed before its feature work. | Parking/retrying cannot change pre-existing failure; auto-repair mixes repository repair into feature scope. | `b2482af` made `StageBaselineGate` launch builder instead of parking. Nine repair commits in history. **Status:** `current` mitigation and architecture weak point. | Measure untouched baseline first. Track baseline repair as explicit change. |
| Passed build with zero changes, 2026-07-23 | Commit-push reports "no changes," parks, retries, repeats. | "Passed with no changes" lacked terminal domain outcome. | `62c0df1` introduced no-op detection; `2bf42bd` set `Outcome`. `TestStageCommitPushClosesIssueWhenBuildNoChanges`. **Status:** `settled`. | Model no-op as explicit terminal result. |
| Infinite parked-task retry, 2026-07-23 | Removing parked label repeatedly requeues with no terminal bound. | Retry count not durable or capped. | `a8fdb50` added persisted `retry_count`, global/per-repo `max_retries`, and `dead`. **Status:** `settled`. | Every autonomous retry needs durable attempt state, explicit bound, terminal state, and operator-visible reason. |
## Chronicle: runtime and peer contracts
| Incident and date | Symptom | Root cause | Evidence and status | Settled rule |
|---|---|---|---|---|
| Container network auto-detection, 2026-07-27 | Every container task returns `nats: no responders`. | `selfNetwork` inspected hostnamed container, silently fell back to default bridge. | `37cf089` records incident, adds `containers.network`; `2ac306b` pins `archie-core_default`. **Status:** `conditional`. | Make cross-container network membership explicit in deployment. |
| SecretRef schema crash-loop, 2026-07-27 | Both identities demand `ARCHIE_GITHUB_TOKEN` despite Gitea config. | Removing old `token_env` field let TOML ignore deployed value. `1f8588d` restored precedence-compatible fallback; a later `308c199` removed the `Forge.TokenEnv` declaration while `finalize` still referenced it. | **Status: `settled`** as of 2026-09-18 — `config.Forge.TokenEnv` is declared (`internal/config/config.go`) and `configuration/defaults.go` converts it to an env `SecretRef` when the structured token is empty. | Preserve decoded compatibility until deployed files migrated and rejection of stale keys observable. |
| Compose secret omission, 2026-07-27 | Config names valid env var, container sees it empty. | Compose forwards only listed environment entries. | `22fc0ef`, `d0624b7`. **Status:** `conditional`. | Trace every secret from config key to host value to Compose passthrough to process lookup. |
| FullStream/TextStream deadlock, 2026-07-27 | Streamed Telegram reply renders empty cursor, typing never clears. | ai-sdk makes `FullStream` authoritative and backpressured; `TextStream` is best-effort. | `6a0bd27`. **Status:** `settled` with regression-test gap. | Drain authoritative stream through close. |
| MCP Content-Length framing and mirrored fake, 2026-07-26 to 2026-07-27 | Internal MCP tests pass while official-SDK servers do not. | MCP stdio uses newline-delimited JSON. Test subprocess called same helpers, mirroring the same wrong protocol. | Compare `f2768eb:internal/tools/mcp/framing.go` with `dda4cde`. **Status:** `settled`. | For wire contracts, test raw canonical frames and independently implemented peer. |
| Telegram command scopes persist by bot token, 2026-07-27 | Startup reports eight commands published, DMs show ~60 old Hermes commands. | Telegram chooses most specific scope; older scopes survive redeploys. | `cec0f3e` adds menu and deny-by-default; `576c7f5` publishes all three scopes. **Status:** `settled`. | Inventory and overwrite every relevant server-side scope. |
| NATS fetch error looked like empty queue, 2026-07-27 | Consumer receives zero messages, treats JetStream failure as "no work." | Batch error state not checked after channel closed. | `0d09a2e` repro; `78a9145` merged through `21ceef0`. **Status:** `settled`. | Check terminal iterator/batch error state even when data channel is empty. |
| Incident and date | Symptom | Root cause | Evidence and status | Settled rule |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Container network auto-detection, 2026-07-27 | Every container task returns `nats: no responders`. | `selfNetwork` inspected hostnamed container, silently fell back to default bridge. | `37cf089` records incident, adds `containers.network`; `2ac306b` pins `archie-core_default`. **Status:** `conditional`. | Make cross-container network membership explicit in deployment. |
| SecretRef schema crash-loop, 2026-07-27 | Both identities demand `ARCHIE_GITHUB_TOKEN` despite Gitea config. | Removing old `token_env` field let TOML ignore deployed value. `1f8588d` restored precedence-compatible fallback; a later `308c199` removed the `Forge.TokenEnv` declaration while `finalize` still referenced it. | **Status: `retired`** as of 2026-09-24 — the `token_env` alias is removed; a stale key is now reported at startup as unrecognised (`bootstrap.go` UnknownKeys warning), which is the observability this entry waited for. | Never drop a credential key without the unknown-key warning in place. |
| Compose secret omission, 2026-07-27 | Config names valid env var, container sees it empty. | Compose forwards only listed environment entries. | `22fc0ef`, `d0624b7`. **Status:** `conditional`. | Trace every secret from config key to host value to Compose passthrough to process lookup. |
| FullStream/TextStream deadlock, 2026-07-27 | Streamed Telegram reply renders empty cursor, typing never clears. | ai-sdk makes `FullStream` authoritative and backpressured; `TextStream` is best-effort. | `6a0bd27`. **Status:** `settled` with regression-test gap. | Drain authoritative stream through close. |
| MCP Content-Length framing and mirrored fake, 2026-07-26 to 2026-07-27 | Internal MCP tests pass while official-SDK servers do not. | MCP stdio uses newline-delimited JSON. Test subprocess called same helpers, mirroring the same wrong protocol. | Compare `f2768eb:internal/tools/mcp/framing.go` with `dda4cde`. **Status:** `settled`. | For wire contracts, test raw canonical frames and independently implemented peer. |
| Telegram command scopes persist by bot token, 2026-07-27 | Startup reports eight commands published, DMs show ~60 old Hermes commands. | Telegram chooses most specific scope; older scopes survive redeploys. | `cec0f3e` adds menu and deny-by-default; `576c7f5` publishes all three scopes. **Status:** `settled`. | Inventory and overwrite every relevant server-side scope. |
| NATS fetch error looked like empty queue, 2026-07-27 | Consumer receives zero messages, treats JetStream failure as "no work." | Batch error state not checked after channel closed. | `0d09a2e` repro; `78a9145` merged through `21ceef0`. **Status:** `settled`. | Check terminal iterator/batch error state even when data channel is empty. |
## Chronicle: implementation and tooling traps
| Incident and date | Symptom | Root cause | Status |
|---|---|---|---|
| Tool registry passed first implementation but held eight defects, 2026-07-26 | Availability can deadlock; schemas mutate after registration; discovery stops at first bad source; literal extraction wrong. | Callbacks ran under `RLock`, copies shallow/shared, parsing partial, matching broad, discovery fail-fast. | `9f6c36c` lists all eight fixes. **Settled.** Never call extension code under registry lock. Clone nested data. Parse complete grammar. Isolate discovery failures. |
| Memory scrubber `Flush` leak, 2026-07-26 | Stream ending inside `...secret</mem` emits buffered hidden memory to visible response. | Pending bytes did not retain whether captured inside `<memory>` block. | `b4aaaf0`. **Settled.** Test every streaming state at EOF. Flush is security boundary. |
| Linter autofix shadowing, 2026-07-28 | 24-file "style" pass stops compiling. | `gocritic` changed `ctx, cancel = context.WithTimeout(...)` to `:=` inside conditional, shadowing context. | `9b44bac`. **Settled.** Treat autofix output as authored behavior. |
| All eleven `nilerr` findings semantic false positives, 2026-07-28 | Mechanical "fixes" would return Go errors while tests pass, breaking model correction, chat, NATS envelopes, clean shutdown, indexing. | Linter cannot see failures carried as text, envelopes, shutdown signals, or skipped entries. | `86cfc19`. **Settled.** Review semantic channels one site at a time. |
| Broad checkpoint hid unresolved merge conflict, 2026-07-27 | Literal conflict marker reached committed source. | Unrelated surfaces combined without whole-diff conflict scan. | `4429ae5`. **Settled.** Keep commits cohesive. |
| Incident and date | Symptom | Root cause | Status |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tool registry passed first implementation but held eight defects, 2026-07-26 | Availability can deadlock; schemas mutate after registration; discovery stops at first bad source; literal extraction wrong. | Callbacks ran under `RLock`, copies shallow/shared, parsing partial, matching broad, discovery fail-fast. | `9f6c36c` lists all eight fixes. **Settled.** Never call extension code under registry lock. Clone nested data. Parse complete grammar. Isolate discovery failures. |
| Memory scrubber `Flush` leak, 2026-07-26 | Stream ending inside `...secret</mem` emits buffered hidden memory to visible response. | Pending bytes did not retain whether captured inside `<memory>` block. | `b4aaaf0`. **Settled.** Test every streaming state at EOF. Flush is security boundary. |
| Linter autofix shadowing, 2026-07-28 | 24-file "style" pass stops compiling. | `gocritic` changed `ctx, cancel = context.WithTimeout(...)` to `:=` inside conditional, shadowing context. | `9b44bac`. **Settled.** Treat autofix output as authored behaviour. |
| All eleven `nilerr` findings semantic false positives, 2026-07-28 | Mechanical "fixes" would return Go errors while tests pass, breaking model correction, chat, NATS envelopes, clean shutdown, indexing. | Linter cannot see failures carried as text, envelopes, shutdown signals, or skipped entries. | `86cfc19`. **Settled.** Review semantic channels one site at a time. |
| Broad checkpoint hid unresolved merge conflict, 2026-07-27 | Literal conflict marker reached committed source. | Unrelated surfaces combined without whole-diff conflict scan. | `4429ae5`. **Settled.** Keep commits cohesive. |
### Preserve the eight tool-registry review lessons
| Defect fixed in `9f6c36c` | Required review question |
|---|---|
| `Available` evaluated `CheckFn` under `RLock` | Can a callback re-enter or block while lock is held? |
| `Register` stored caller references | Can caller mutate registered state afterward? |
| `Clone` copied nested schema maps/slices shallowly | Is every mutable layer detached? |
| `stringLit` mishandled escapes/backticks | Does parsing follow Go literal semantics? |
| `intLit` omitted negative/hex/octal/binary forms | Are all supported numeric forms handled or rejected? |
| `Discover` aborted on first error | Can one bad extension hide healthy extensions? |
| `isRegisterCall` matched too broadly | Is the exact receiver/call shape proven? |
| `schemaLit` accepted only string values | Are booleans, integers, arrays, nested maps preserved? |
| Defect fixed in `9f6c36c` | Required review question |
| -------------------------------------------------- | ------------------------------------------------------ |
| `Available` evaluated `CheckFn` under `RLock` | Can a callback re-enter or block while lock is held? |
| `Register` stored caller references | Can caller mutate registered state afterward? |
| `Clone` copied nested schema maps/slices shallowly | Is every mutable layer detached? |
| `stringLit` mishandled escapes/backticks | Does parsing follow Go literal semantics? |
| `intLit` omitted negative/hex/octal/binary forms | Are all supported numeric forms handled or rejected? |
| `Discover` aborted on first error | Can one bad extension hide healthy extensions? |
| `isRegisterCall` matched too broadly | Is the exact receiver/call shape proven? |
| `schemaLit` accepted only string values | Are booleans, integers, arrays, nested maps preserved? |
## Chronicle: worktree and repository state reversals
| Step and date | Symptom | Root cause | Settled rule |
|---|---|---|---|
| Existing worktree skipped, 2026-07-23 | `Prepare` returned when `.git` existed. | Existence did not prove freshness or completed preparation. Later replaced `.git` readiness with sentinel. | Define completed-state marker and revalidate remote/base/branch state on reuse. |
| Sentinel outside `.git`, 2026-07-24 | `.archie-prepared` marked setup; go-git `Add(All)` doesn't honor exclude. | Orchestration metadata needs to be outside tracked worktree by construction. | Put sentinel at `.git/archie-prepared`. |
| Askpass rewritten each call, 2026-07-24 | Token-emitting shell script rewritten for every git command. | Comment wasn't invariant; no test checked mtime. Later removed shell git and askpass entirely. | Prefer in-process credentials. |
| Bare object cache, 2026-07-24 | `--reference-if-able --dissociate` plus TTL to accelerate clones. | go-git has no `--dissociate` equivalent; expiring cache would corrupt active worktrees. | Never accept clone acceleration making task correctness depend on expiring cache. |
| Shell git replaced by go-git, 2026-07-28 | Port exposed host GPG inheritance, sentinel tracking, merge-base diff semantics. | RPC handlers used `context.Background`, making in-process clones unbounded. | Audit every adapter and cancellation boundary after replacing killable subprocess with in-process I/O. |
| Step and date | Symptom | Root cause | Settled rule |
| ---------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Existing worktree skipped, 2026-07-23 | `Prepare` returned when `.git` existed. | Existence did not prove freshness or completed preparation. Later replaced `.git` readiness with sentinel. | Define completed-state marker and revalidate remote/base/branch state on reuse. |
| Sentinel outside `.git`, 2026-07-24 | `.archie-prepared` marked setup; go-git `Add(All)` doesn't honour exclude. | Orchestration metadata needs to be outside tracked worktree by construction. | Put sentinel at `.git/archie-prepared`. |
| Askpass rewritten each call, 2026-07-24 | Token-emitting shell script rewritten for every git command. | Comment wasn't invariant; no test checked mtime. Later removed shell git and askpass entirely. | Prefer in-process credentials. |
| Bare object cache, 2026-07-24 | `--reference-if-able --dissociate` plus TTL to accelerate clones. | go-git has no `--dissociate` equivalent; expiring cache would corrupt active worktrees. | Never accept clone acceleration making task correctness depend on expiring cache. |
| Shell git replaced by go-git, 2026-07-28 | Port exposed host GPG inheritance, sentinel tracking, merge-base diff semantics. | RPC handlers used `context.Background`, making in-process clones unbounded. | Audit every adapter and cancellation boundary after replacing killable subprocess with in-process I/O. |
## Chronicle: cleanup, artifacts, and contradictory policy
| Incident and date | Symptom | Root cause | Status | Settled rule |
|---|---|---|---|---|
| Tracked `.gotmp`, 2026-07-27 | Build-cache binaries, generated `_testmain.go`, `.git-askpass` appear in commits. | Workaround path not ignored before use. | `4cb0577` removes artifacts and adds `.gotmp/` to `.gitignore`. **Settled.** | Put caches outside repo or ignore before first command. |
| Tracked `docs/node_modules`, 2026-07-28 | Hundreds of pnpm symlink entries become repository content. | `docs/node_modules` neither ignored nor excluded from commit. | 237 entries at that time; the VitePress site was removed (`84b32694`) and `git ls-files | grep -c node_modules` is now **0**. **Settled.** | Track lockfiles, never installed trees. |
| `308c199` cleanup regression, 2026-07-28 | `TestRunWrapsExternalCommand` returns `"\n"` instead of `"wrapped\n"`; forge compatibility removed again; dependency artifacts added. | Semantic edits classified and reviewed as cleanup. | The focused skillscript test **passes** as of 2026-09-16. **Settled.** | No commit is "cleanup" for gating purposes. |
| `diff_cap_lines = 0` contradiction, introduced at project start | Operators set zero expecting unlimited, but decoded config becomes 400. | `finalize` converts zero to default 400; same sentinel means both "unset" and "unlimited." | **Current/open** contradiction. | Never overload zero value with both defaulting and explicit policy. |
| Incident and date | Symptom | Root cause | Status | Settled rule |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Tracked `.gotmp`, 2026-07-27 | Build-cache binaries, generated `_testmain.go`, `.git-askpass` appear in commits. | Workaround path not ignored before use. | `4cb0577` removes artifacts and adds `.gotmp/` to `.gitignore`. **Settled.** | Put caches outside repo or ignore before first command. |
| Tracked `docs/node_modules`, 2026-07-28 | Hundreds of pnpm symlink entries become repository content. | `docs/node_modules` neither ignored nor excluded from commit. | 237 entries at that time; the VitePress site was removed (`84b32694`) and `git ls-files | grep -c node_modules` is now **0**. **Settled.** | Track lockfiles, never installed trees. |
| `308c199` cleanup regression, 2026-07-28 | `TestRunWrapsExternalCommand` returns `"\n"` instead of `"wrapped\n"`; forge compatibility removed again; dependency artifacts added. | Semantic edits classified and reviewed as cleanup. | The focused skillscript test **passes** as of 2026-09-16. **Settled.** | No commit is "cleanup" for gating purposes. |
| `diff_cap_lines = 0` contradiction, introduced at project start | Operators set zero expecting unlimited, but decoded config becomes 400. | `finalize` converts zero to default 400; same sentinel means both "unset" and "unlimited." | **Current/open** contradiction. | Never overload zero value with both defaulting and explicit policy. |
## Keep unmerged work as dated candidates
@@ -211,14 +211,14 @@ branches recorded here on 2026-07-28 no longer exist on either remote —
`git branch -r --no-merged HEAD` reports only `gitea/main` (and the Dolt helper
ref). Treat their concerns as `superseded` unless a live branch re-raises one.
| Former candidate branch | Claimed concern |
|---|---|
| `origin/fix/43-loaddir-no-timeout-around-yaegi-eval-can-hang-daemon-startup` | Bound Yaegi evaluation during `LoadDir` |
| `origin/fix/45-skillscriptrun-ignores-context-cannot-be-canceledtimed-out` | Make skill scripts cancellable |
| `origin/fix/48-transition-ignores-from-status-guard-allowing-lost-updates` | Enforce expected source state atomically |
| `origin/fix/52-handlesse-silently-swallows-eventssince-backlog-fetch-errors` | Surface SSE backlog query errors |
| `origin/feat/51-no-test-coverage-for-stagestats-query` | Add `StageStats` query coverage |
| `origin/feat/75-add-mcp-client-capabilities-to-archied-and-archie-agent` | Wire MCP through both execution modes |
| Former candidate branch | Claimed concern |
| ---------------------------------------------------------------------------- | ---------------------------------------- |
| `origin/fix/43-loaddir-no-timeout-around-yaegi-eval-can-hang-daemon-startup` | Bound Yaegi evaluation during `LoadDir` |
| `origin/fix/45-skillscriptrun-ignores-context-cannot-be-canceledtimed-out` | Make skill scripts cancellable |
| `origin/fix/48-transition-ignores-from-status-guard-allowing-lost-updates` | Enforce expected source state atomically |
| `origin/fix/52-handlesse-silently-swallows-eventssince-backlog-fetch-errors` | Surface SSE backlog query errors |
| `origin/feat/51-no-test-coverage-for-stagestats-query` | Add `StageStats` query coverage |
| `origin/feat/75-add-mcp-client-capabilities-to-archied-and-archie-agent` | Wire MCP through both execution modes |
Verify candidate state:
+51 -65
View File
@@ -11,14 +11,14 @@ history.
## Define the process shapes
| Term | Meaning here |
|---|---|
| `archied` | Resident orchestrator. Owns config, forge credentials, SQLite stores, worktrees, gateways, dashboard, optional NATS/Docker orchestration. |
| `archie-agent` | Long-running NATS worker. Consumes per-stage `archie.agent.>` requests and full-task `archie.taskrun.>` requests. Not a stdin/stdout worker. |
| Stage request | One autonomous workflow stage sent on `archie.agent.<task-id>.request`. |
| Full-task handoff | A whole workflow sent on core NATS subject `archie.taskrun.<task-id>` to a task container. |
| Work directory | `work_dir`: task clones plus memory and candidate index artifacts. |
| State path prefix | `db_path`: the configured prefix. Task/event state uses `<db_path>-tasks.sqlite`; conversation state uses `<db_path>-conversations.sqlite`. |
| Term | Meaning here |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `archied` | Resident orchestrator. Owns config, forge credentials, worktrees, gateways, dashboard, optional NATS/Docker orchestration. |
| `archie-agent` | Long-running NATS worker. Consumes per-stage `archie.agent.>` requests and full-task `archie.taskrun.>` requests. Not a stdin/stdout worker. |
| Stage request | One autonomous workflow stage sent on `archie.agent.<task-id>.request`. |
| Full-task handoff | A whole workflow sent on core NATS subject `archie.taskrun.<task-id>` to a task container. |
| Work directory | `work_dir`: task clones plus memory and candidate index artifacts. |
| State directory | `state_dir` (default `~/.local/share/archie`): embedded NATS store, task logs. Task, event, capture and conversation data live in the PostgreSQL database `database_url` names. |
## Apply the operational safety boundary
@@ -43,32 +43,28 @@ There is no config-only or dry-run flag.
### `archied`
| Flag | Exact behavior |
|---|---|
| `-config <path>` | Load base TOML. Default: `$XDG_CONFIG_HOME/archie/config.toml`, or `~/.config/archie/config.toml`. |
| `-config-overlay <path>` | Decode a second TOML file into the base config before defaults and validation. |
| `-once` | Run startup plus one poll/process cycle, then exit. This changes state. |
| `-requeue <task-id>` | Requeue a parked/waiting task, then exit unless `-once` is also set. This changes state. |
| Flag | Exact behaviour |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| `-config <path>` | Load base TOML. Default: `$XDG_CONFIG_HOME/archie/config.toml`, or `~/.config/archie/config.toml`. |
| `-config-overlay <path>` | Decode a second TOML file into the base config before defaults and validation. |
| `-once` | Run startup plus one poll/process cycle, then exit. This changes state. |
| `-requeue <task-id>` | Requeue a parked/waiting task, then exit unless `-once` is also set. This changes state. |
### `archie-agent`
| Flag or environment | Exact behavior |
|---|---|
| `-nats-url <url>` | Select NATS; falls back to `NATS_URL`. One of them is required. |
| `-consumer <name>` | Set the durable JetStream consumer name; default `archie-agent`. |
| `NATS_TOKEN` | Optional NATS token read directly by the worker. |
| Flag or environment | Exact behaviour |
| ------------------- | --------------------------------------------------------------- |
| `-nats-url <url>` | Select NATS; falls back to `NATS_URL`. One of them is required. |
| `NATS_TOKEN` | Optional NATS token read directly by the worker. |
Both linked binaries may also display Go's `-quickchecks` flag from
`testing/quick`; it is not an Archie operations control.
## Select the execution mode deliberately
## Execution mode
| Config shape | What runs | Operational status on 2026-09-18 |
|---|---|---|
| `agent.mode = "inprocess"` and no `[nats]` | `archied` polls and claims from SQLite, runs workflow stages and model tools in-process. | **Production-wired candidate.** No process or OS isolation. |
| `agent.mode = "subprocess"` | `archied` starts `agent.command` per stage and expects one JSON invocation on stdin, one response on stdout. | **Open/broken with default command.** `cmd/archie-agent` is a long-running NATS worker and never calls `agentexec.ServeOne`. |
| `agent.mode = "nats"`, `[nats]`, containers disabled | `archied` runs the workflow; each autonomous stage goes to a separately started `archie-agent`. | **Implemented but operator-assembled.** Launch and supervise a worker separately. |
| `agent.mode = "nats"`, `[nats]`, `containers.enabled = true` | `archied` publishes task discovery through JetStream, prepares a worktree, spawns one agent container, sends the whole workflow on `archie.taskrun.<id>`. | **Host daemon + Compose NATS path.** `deployments/docker-nats-stack.toml` demonstrates it. |
| Config shape | What runs |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[nats]` absent (embedded) or `url` set (external) | `archied` polls and claims through the State Store, prepares a worktree, spawns one task-scoped agent container and sends the whole workflow on `archie.taskrun.<id>`. There is no other execution mode. |
## Run a local foreground daemon
@@ -95,7 +91,7 @@ startup did not complete. The daemon has no HTTP health endpoint.
Stop with `Ctrl-C`. The signal cancels active work, waits for dispatch
goroutines, stops capability and memory managers, removes Archie-labelled
containers, closes NATS, and closes the SQLite stores.
containers, closes NATS, and closes its store connections.
## Run a standalone NATS worker
@@ -108,12 +104,12 @@ Do not use this to test subprocess mode.
## Run the repository Compose stack
| Repository command | Actual scope |
|---|---|
| `task docker-build` | Build only the `agent` image from `Dockerfile`. |
| `task docker-up` | Start the Compose-managed NATS service. The profiled agent entry is not started. |
| `task docker-logs` | Follow the NATS service logs. |
| `task docker-down` | Run `docker compose down`. Does not request volume deletion. |
| Repository command | Actual scope |
| ------------------- | -------------------------------------------------------------------------------- |
| `task docker-build` | Build only the `agent` image from `Dockerfile`. |
| `task docker-up` | Start the Compose-managed NATS service. The profiled agent entry is not started. |
| `task docker-logs` | Follow the NATS service logs. |
| `task docker-down` | Run `docker compose down`. Does not request volume deletion. |
Prefer the narrow start:
@@ -150,21 +146,21 @@ are spawned by the host `archied` process through `/var/run/docker.sock`.
## Locate output and durable state
| Output or state | Current destination |
|---|---|
| Daemon logs | JSON on host stderr; the configured host supervisor captures them. |
| Agent logs | JSON on worker/container stderr. Task containers use `AutoRemove`. |
| Tasks and events | SQLite database at `<db_path>-tasks.sqlite`; default `~/.local/share/archie/archie.db-tasks.sqlite`. |
| Chat sessions and messages | SQLite database at `<db_path>-conversations.sqlite`. |
| Default task worktree | `<work_dir>/<owner>-<repo>/issue-<number>`; default root `~/.local/share/archie/work`. |
| Identity worktree | `<work_dir>/identity-<identity>/<owner>-<repo>/issue-<number>`. |
| Container worktree | Host worktree bind-mounted read/write at `/data/worktree`; `task.json` written under `.git/` so the agent's commit cannot sweep it onto the task branch. |
| Built-in memory | `<work_dir>/memory/MEMORY.md` and `<work_dir>/memory/USER.md`. |
| Telegram update state | `<work_dir>/telegram-update-deferrals.json` plus hashed `release-announcements-*.json`. |
| Codesearch candidates | Defaults derive as `<work_dir>/indexes` and `<work_dir>/workspace-indexes.db`; no `indexing.Manager` construction found in daemon composition root. |
| Optional repository volume | `archie-repo-<owner>-<repo>` mounted at `/data/repo`. |
| Ecosystem cache volumes | `archie-cache-go`, `archie-cache-node`, etc., mounted below `/data/cache`. No code sets tool cache env vars to those mount paths. |
| NATS data | Compose declares `nats_data:/data`; NATS command does not set a store directory. |
| Output or state | Current destination |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Daemon logs | JSON on host stderr; the configured host supervisor captures them. |
| Agent logs | JSON on worker/container stderr. Task containers use `AutoRemove`. |
| Tasks and events | PostgreSQL (`database_url`), served by `archie-state-store`. |
| Chat sessions and messages | PostgreSQL (`database_url`), served by `archie-gateway`. |
| Default task worktree | `<work_dir>/<owner>-<repo>/issue-<number>`; default root `~/.local/share/archie/work`. |
| Identity worktree | `<work_dir>/identity-<identity>/<owner>-<repo>/issue-<number>`. |
| Container worktree | Host worktree bind-mounted read/write at `/data/worktree`; `task.json` written under `.git/` so the agent's commit cannot sweep it onto the task branch. |
| Built-in memory | `<work_dir>/memory/MEMORY.md` and `<work_dir>/memory/USER.md`. |
| Telegram update state | `<work_dir>/telegram-update-deferrals.json` plus hashed `release-announcements-*.json`. |
| Codesearch candidates | Defaults derive as `<work_dir>/indexes` and `<work_dir>/workspace-indexes.db`; no `indexing.Manager` construction found in daemon composition root. |
| Optional repository volume | `archie-repo-<owner>-<repo>` mounted at `/data/repo`. |
| Ecosystem cache volumes | `archie-cache-go`, `archie-cache-node`, etc., mounted below `/data/cache`. No code sets tool cache env vars to those mount paths. |
| NATS data | Compose declares `nats_data:/data`; NATS command does not set a store directory. |
Compose runs NATS only; `archied` and all configured state paths remain on the
host. The host daemon talks to the local Docker socket directly and bind-mounts
@@ -175,12 +171,12 @@ each task worktree into the agent container it creates.
The `ARCHIE_TASKS` JetStream stream uses file storage and work-queue retention
for `archie.task.>` and `archie.agent.>`.
| Plane | Subjects and behavior |
|---|---|
| Discovery | `archie.task.bug`, `.feature`, `.bootstrap`, or `.default`; daemon durable consumer `archie-daemon`, 5-min ack wait, max 3 deliveries. |
| Per-stage requests | `archie.agent.<id>.request`; worker durable consumer defaults to `archie-agent`, 30-min ack wait, max 3 deliveries; response address in `X-Archie-Reply`. |
| Container task | Core NATS request/reply on `archie.taskrun.<id>`. Task container reads `/data/worktree/.git/task.json` and creates dedicated subscription; shared worker uses queue group `archie-taskrun-workers`. |
| Privileged RPC | Store operations go to the gRPC State Store (`internal/infrastructure/staterpc`, task-scoped grants); forge and worktree operations return to `archied` over core NATS subjects in `internal/forgerpc` and `internal/worktreerpc`. |
| Plane | Subjects and behaviour |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Discovery | `archie.task.bug`, `.feature`, `.bootstrap`, or `.default`; daemon durable consumer `archie-daemon`, 5-min ack wait, max 3 deliveries. |
| Per-stage requests | `archie.agent.<id>.request`; worker durable consumer defaults to `archie-agent`, 30-min ack wait, max 3 deliveries; response address in `X-Archie-Reply`. |
| Container task | Core NATS request/reply on `archie.taskrun.<id>`. Task container reads `/data/worktree/.git/task.json` and creates dedicated subscription; shared worker uses queue group `archie-taskrun-workers`. |
| Privileged RPC | Store operations go to the gRPC State Store (`internal/infrastructure/staterpc`, task-scoped grants); forge and worktree operations return to `archied` over core NATS subjects in `internal/forgerpc` and `internal/worktreerpc`. |
Set `containers.network` explicitly. `deployments/docker-nats-stack.toml` uses
`archie-core_default`. Auto-detection inspects the daemon container; on failure,
@@ -196,10 +192,6 @@ It forwards only configured provider-key variables.
Open limitations until code/tests prove otherwise:
- `subprocess` + default `archie-agent` is protocol-incompatible.
- A deployed overlay previously using legacy `token_env` still converts: the
structured `forge.token` secret reference wins when both are present and
`config.Forge.TokenEnv` is otherwise converted by
`internal/infrastructure/configuration/defaults.go`.
- Container RPC uses root forge/worktree for every identity.
- Container orphan recovery lacks daemon-instance label.
- `max_uptime` only bounds `Pool.Acquire` create/start; no lifetime timer.
@@ -217,13 +209,7 @@ Docker builds. The Gitea workflow that used to be the production build path was
dropped (`dd9bddc2`); `deployments/*.toml` are the supported profiles.
Before promotion: record running image IDs/digests; config checksums (no
secrets); task counts via safe GET; establish a SQLite backup procedure.
secrets); task counts via safe GET; take backups with `archie-state-store backup`.
No complete rollback command exists, no versioned image tags. Restoring a binary
does not undo forge changes, task transitions, or data-format changes.
## Treat carina facts as unverified external state
Repository guidance (2026-09-18): two instances on `carina` with distinct
`bot_user` values. No live process list, config, image digest, service manager,
or deployment was verified. Do not invent SSH, systemd, or service commands.
+15 -3
View File
@@ -14,7 +14,19 @@ Not editorial, not marketing, not playful. Every rule below serves that.
- Vue 3 SFCs + TypeScript, Vite, Pinia, vue-router.
- Tailwind CSS v4 via `@tailwindcss/vite`; `@custom-variant dark` keyed on the
`[data-theme]` attribute; shadcn-vue + reka-ui for primitives;
`@lucide/vue` for icons; `@fontsource-variable/geist` is the typeface.
`@lucide/vue` for icons; IBM Plex Sans for UI, IBM Plex Mono for every
machine value (Graphite theme, `docs/design/ui-redesign/`).
- `ui/src/components/ui/` is CLI-installed only; never hand-edit it. Order of
preference for a missing component: stock shadcn-vue (`npx shadcn-vue add`;
reka-ui names differ, e.g. chip input is Tags input), another shadcn-vue
registry (e.g. inspira-ui), then a new item in the sibling
`archie-component-registry` repo, installed from its `public/r/<item>.json`.
The CLI prompts to overwrite stock primitives an item depends on: answer no.
To update an installed registry item, delete its `components/ui/<item>/`
folder and add it again; never pass `--overwrite`, which also rewrites the
stock components listed in its `registryDependencies`.
If `npm install` fails with `EALLOWSCRIPTS`, run the CLI with
`NPM_CONFIG_USERCONFIG=/dev/null`.
- Features live in `ui/src/<feature>/` with colocated `.js`/`.css`. Extract a
helper to `ui/src/base/` only on the **second distinct consumer**.
- `ui/dist/` is committed and generated — never hand-edit it, never ignore it
@@ -86,5 +98,5 @@ decisions into SFCs using shadcn-vue primitives and existing tokens. Mock data
in a prototype proves nothing — verify the pattern against real task/log/diff
shapes before building around it. A prototype proposing new information
architecture (e.g. splitting the task view into a master-detail pane) is an
open design question: it needs a decisive 1-page doc in `docs/prds/` before
structural work lands, per AGENTS.md.
open design question for the maintainer. Web UI design is not tracked in
`docs/prds/`; record the decision on the bead and in `docs/design/`.
+5 -1
View File
@@ -33,6 +33,7 @@ bd dolt push
### Working with Issues
Issues in Beads are:
- **Git-native**: Stored in Dolt database with version control and branching
- **AI-friendly**: CLI-first design works perfectly with AI coding agents
- **Branch-aware**: Issues can follow your branch workflow
@@ -41,16 +42,19 @@ Issues in Beads are:
## Why Beads?
✨ **AI-Native Design**
- Built specifically for AI-assisted development workflows
- CLI-first interface works seamlessly with AI coding agents
- No context switching to web UIs
🚀 **Developer Focused**
- Issues live in your repo, right next to your code
- Works offline, syncs when you push
- Fast, lightweight, and stays out of your way
🔧 **Git Integration**
- Dolt-native sync via bd dolt push / bd dolt pull
- Branch-aware issue tracking
- Dolt-native three-way merge resolution
@@ -78,4 +82,4 @@ bd create "Try out Beads"
---
*Beads: Issue tracking that moves at the speed of thought* ⚡
_Beads: Issue tracking that moves at the speed of thought_ ⚡
+11 -11
View File
@@ -54,15 +54,15 @@
# Disabled by default; enable only when an integration needs fresh .beads/issues.jsonl.
# Use relative paths under .beads/ for JSONL import/export filenames.
export:
auto: false
path: issues.jsonl
interval: 60s
# issues.jsonl/interactions.jsonl are .gitignore'd local-only files --
# Dolt (synced via sync.remote) is the source of truth. Leave auto off
# and git-add off; do not re-track these in git.
git-add: false
auto: false
path: issues.jsonl
interval: 60s
# issues.jsonl/interactions.jsonl are .gitignore'd local-only files --
# Dolt (synced via sync.remote) is the source of truth. Leave auto off
# and git-add off; do not re-track these in git.
git-add: false
import:
path: issues.jsonl
path: issues.jsonl
# Integration settings (access with 'bd config get/set')
# Non-secret keys (stored in the database):
# - jira.url, jira.project
@@ -74,7 +74,7 @@ import:
# - github.token → use GITHUB_TOKEN env var instead
sync.remote: "git+https://github.com/samcharles93/archie-core.git"
dolt:
shared-server: false
auto-commit: "on"
shared-server: false
auto-commit: "on"
audit:
enabled: true
enabled: true
+1 -1
View File
@@ -5,4 +5,4 @@
"dolt_database": "archie_core",
"project_id": "e8a66150-1f5f-42d2-8653-dcf8463cef74",
"last_bd_version": "1.2.2"
}
}
+17 -1
View File
@@ -72,6 +72,22 @@ jobs:
- name: Install protobuf tools
run: bash tools/proto.sh install
# The backup/restore tests shell out to pg_dump/pg_restore against a
# postgres:18 testcontainer; the runner's stock client is older and
# refuses the server version.
- name: Install PostgreSQL 18 client
run: |
sudo install -d /usr/share/postgresql-common/pgdg
sudo curl --fail --silent --show-error --location \
https://www.postgresql.org/media/keys/ACCC4CF8.asc \
--output /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc
. /etc/os-release
echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt ${VERSION_CODENAME}-pgdg main" \
| sudo tee /etc/apt/sources.list.d/pgdg.list
sudo apt-get update
sudo apt-get install -y --no-install-recommends postgresql-client-18
echo "/usr/lib/postgresql/18/bin" >> $GITHUB_PATH
- name: Ensure contract baseline ref
run: |
if ! git show-ref --verify --quiet refs/heads/main; then
@@ -305,7 +321,7 @@ jobs:
# ran on with a dead Telegram bot and no error anywhere
# (archie-core-1c01). TestDistZipShipsEveryHostCommand fails if this
# list and the copy list below stop matching the commands in cmd/.
ldflags="-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary -X github.com/samcharles93/archie-core/internal/buildinfo.Version=${{ steps.version.outputs.version }}"
ldflags="-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary -X github.com/samcharles93/archie-core/internal/buildinfo.Version=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/buildinfo.Runtime=${{ steps.version.outputs.version }}"
mkdir -p dist
for cmd in archied archie-gateway archie-state-store archie-ui archie-messaging archie-playbooks; do
go build -ldflags "$ldflags" -o "dist/$cmd" "./cmd/$cmd"
-48
View File
@@ -1,48 +0,0 @@
name: docs
# Verification only. Deployment happens from the Ansible control node
# (vectislabs.automation docs_site role against nebula), so there is nothing
# for CI to publish. What CI is for here is catching a docs change that will
# not build before it reaches a deploy.
on:
push:
branches: [main]
paths:
- "docs/**"
- "mkdocs.yml"
- ".github/workflows/docs.yml"
pull_request:
paths:
- "docs/**"
- "mkdocs.yml"
workflow_dispatch:
permissions:
contents: read
concurrency:
group: docs-${{ github.ref }}
cancel-in-progress: true
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
# No `cache: pip` here: this repository is Go and has no
# requirements.txt or pyproject.toml for setup-python to hash. Asking for
# a pip cache makes the step fail outright with "No file ... matched to
# [**/requirements.txt or **/pyproject.toml]", so every docs-touching PR
# failed before `mkdocs build --strict` ever ran -- which also meant the
# strict link/config check silently stopped guarding anything.
- uses: actions/setup-python@v6
with:
python-version: "3.13"
- run: pip install mkdocs-material
# --strict fails on a broken internal link or an unknown config key. A
# docs site that silently ships dead links is worse than one that refuses
# to ship.
- run: mkdocs build --strict
+17
View File
@@ -36,8 +36,25 @@ jobs:
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2
go install mvdan.cc/gofumpt@v0.11.0
bash tools/proto.sh install
sudo apt-get update
sudo apt-get install -y --no-install-recommends ripgrep
sudo install -d /usr/share/postgresql-common/pgdg
sudo curl --fail --silent --show-error --location \
https://www.postgresql.org/media/keys/ACCC4CF8.asc \
--output /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc
. /etc/os-release
echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt ${VERSION_CODENAME}-pgdg main" \
| sudo tee /etc/apt/sources.list.d/pgdg.list
sudo apt-get update
sudo apt-get install -y --no-install-recommends postgresql-client-18
echo "/usr/lib/postgresql/18/bin" >> $GITHUB_PATH
pg_dump --version
pg_restore --version
- name: Ensure contract baseline ref
run: |
+1 -3
View File
@@ -7,7 +7,6 @@
.env
task.json
.hermes-carina/
config.production.toml
.gotmp/
@@ -37,7 +36,6 @@ config.production.toml
.beads-credential-key
.beads/proxieddb/
*.gate.lock*
# Impeccable design-tool scratch/critique snapshots (usable by $impeccable polish, never committed)
.impeccable/
.serena/
.beads/issues.jsonl
@@ -49,7 +47,7 @@ config.production.toml
__pycache__/
*.pyc
# MkDocs build output (task docs:site)
# Local site build output.
/site/
# Locally-trusted development certificates (mkcert and friends). The private
+4
View File
@@ -0,0 +1,4 @@
# Generated output: only its generator writes it, and the gate byte-checks it.
docs/data/generated/
internal/contracts/
ui/dist/
+118
View File
@@ -5,6 +5,124 @@ release's per-component sections are labelled beneath its heading.
## [Unreleased]
## [1.42.0] - 2026-09-26
### archied
- **The dashboard is rebuilt on a new Graphite theme.** Settings moved to its
own sidebar with one save flow across every page (Channels, Tools & MCP,
Scheduling policy, Personas and Schedules, Identities, Plugins, Container
runtime, and a History of past changes). The top bar, Dashboard, Workflows,
task detail, the New task dialog and the Events page are all new: Dashboard
leads with what needs you, a run's stage rail and detail panels sit
side by side, Workflows shows per-workflow stats including completed runs,
and Events states capture status with a copyable capture endpoint. Live
updates share one stream and reopen after a drop instead of going quiet.
- **Settings changes are audited.** A field-level audit table records who
changed what, with a view on each settings page.
- **A task can carry a whole-run wall-clock limit**, separate from a stage's
own budget.
- **A run that makes no changes now ends as completed and its worktree is
cleaned up**, rather than left in a state Workflows didn't count.
- **Abandoning a task no longer closes its forge issue.** Only the workflow's
own terminal outcomes do that now.
- **A task whose container exits before the worker replies is parked**
instead of left running with no way to finish.
- **A worktree still holding uncommitted work is kept**, rather than reset,
when its task reaches a terminal state.
- **A provider's stored settings no longer get corrupted with a process-local
placeholder in place of your configured secret reference**, and archied
rejects a stored value shaped like one on the way back in.
- **Kit v3 harness profiles.** A `[containers.profiles.<name>]` entry can now
name a Kit v3 image (`kit = [...]`, pinned by digest) instead of a plain
container image, running the task's agent stages on an external CLI --
Claude Code, Codex, Pi, OMP or GitHub Copilot CLI -- inside an isolated
sandbox network. This release lands the daemon-side plumbing (egress
proxy, sandbox network, credential injection points); it does not yet ship
a way to grant a run's identity the credential a Kit needs, so a Kit
requiring one is refused at launch until a later release adds it.
- `task dev` now starts the State Store and waits for it before the rest of
the stack.
- Every service binary the installer builds is stamped with its version.
### archie-agent
- Carries the same task-lifecycle fixes as archied above (no-change runs,
parking on an early container exit, and the abandon/forge-issue fix), plus
the Kit v3 harness runner: a stage can now drive an external CLI
headlessly, read output from Claude Code, Codex, Pi, OMP or GitHub Copilot
CLI, and serve it capture tools over MCP.
- Claude's cached tokens are counted as prompt tokens, matching the built-in
agent loop's accounting.
## [1.41.2] - 2026-09-25
### archied
- **`/update` no longer offers an old runtime.** The runtime has shipped under
the release version since the version streams merged, but the update check
still read the retired runtime tags, so a current host was offered runtime
1.35.0 as an update. Do not approve that offer on 1.41.1; update to 1.41.2
instead.
- **`/version` reports the runtime version.** Binaries from the release zip
showed `Runtime: dev`.
## [1.41.1] - 2026-09-25
### archied
- **First published build of 1.41.0.** The 1.41.0 tag produced no release
artifacts; 1.41.1 carries everything listed under 1.41.0 below, including
the PostgreSQL 18 requirement and the removed config keys.
## [1.41.0] - 2026-09-25
### archied
- **Archie now stores everything in PostgreSQL 18, and `database_url` is
required.** Tasks, events, captures, bindings, settings and chat
conversations are served from the database `database_url` names; the State
Store, archied and the Gateway refuse to start without it, and refuse a
server older than PostgreSQL 18. `docker compose up -d postgres` starts a
matching local database with the default URL in `config.example.toml`.
- **Existing SQLite data is not carried over.** This release reads no SQLite
file and ships no importer, so an upgraded install starts with empty task,
event and conversation history. `db_path` is gone; `state_dir` (default
`~/.local/share/archie`) now holds the embedded NATS store and task logs.
- **Backups are whole-database snapshots.** `archie-state-store backup` and
`restore` work on the PostgreSQL database through `pg_dump`/`pg_restore`,
which must be on `PATH`. There is no automatic schema rollback: the way back
from an upgrade is restoring the snapshot taken before it.
- **Events carry a type, and bindings pick one.** Archie infers an event type
from captured payloads; the Inspector shows proposed and unidentified
events and lets you name them. Mappings are per event type and show how
many captures they match, a source can feed several bindings, and a binding
chooses an event type plus an optional filter. An unidentified event does
not dispatch.
- **Sources own webhook signing.** Each source gets a UUIDv7 path and its own
signing secret, or can be explicitly approved to accept unsigned events. A
new binding starts pending approval.
- **EDA playbooks can run module actions and take workflow inputs.** Action
playbooks run at most once per event through the dispatch ledger, a binding
can pass inputs to its workflow, the repository is optional, and a workflow
can name an agent profile. `archie-playbooks lint -eda-dir` checks a
directory, and `archie-playbooks serve` publishes the same findings to your
editor as a language server.
- **Config keys removed.** `[agent]`, `[oidc]`, `[image]`,
`containers.enabled`, `db_path`, and the `token_env` form of `[forge]`,
`[artifacts]` and `[chat.telegram]` no longer exist. Write each credential as
`token = { engine = "env", key = "NAME" }`. A leftover key is reported at
startup as unrecognised rather than failing the load.
- **Dashboard.** Old `#/path` links and the `/captures`, `/mappings` and
`/bindings` addresses no longer redirect; use the Events page tabs. The live
stream moved to `/api/stream`, so reloading `/events` serves the page.
### archie-agent
- The Postgres-backed wire formats, event types and workflow inputs are part
of this image; a host that runs the agent should `docker compose pull agent`
to pick it up.
## [1.40.0] - 2026-09-23
### archied
+20 -14
View File
@@ -33,6 +33,10 @@ git, and agent execution functions as a strict data boundary. Before adding a ne
plugin engine, satisfy
`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`.
Before changing an area (frontend UI, agent, workflows, daemon, State Store,
control plane), read its page in `docs/development/`: it names every layer the
change must reach.
## Scope Discipline
`docs/architecture/` is authoritative for settled design.
@@ -92,13 +96,15 @@ automatically and note it in the handoff.
## Build & Test
Commands are defined in `Taskfile.yml` (requires Go 1.27.0,
[Task](https://taskfile.dev), `gofumpt`, `golangci-lint`, and Node/npm).
[Task](https://taskfile.dev), `gofumpt`, `golangci-lint`, Node/npm, and a
running Docker daemon: Postgres tests start `postgres:18` through
testcontainers via `internal/infrastructure/postgres/pgtest`).
`golangci-lint` is the single writer for ordinary Go formatting; standalone
`gofumpt` formats generated protobuf contracts only.
```bash
task build # build archied and archie-agent binaries into bin/
task test # go test ./... -count=1
task test # go test -short ./... (cached; task test:full runs everything uncached)
task test:ui # dashboard node tests (DOM-building primitives)
task ui # build dashboard into ui/dist (LAW asset)
task fmt # go fix ./... && golangci-lint fmt
@@ -164,7 +170,7 @@ structures found in legacy packages.
## Per-Package Invariants & Traps
- **Config fields (cross-cutting): a field that parses is not a field that works.**
A knob added to a struct the extensible surface reuses *parses* everywhere
A knob added to a struct the extensible surface reuses _parses_ everywhere
without taking effect anywhere, and a knob read from the wrong layer is just
as invisible: a file key is only a seed once a stored resource outranks it.
Before adding or reusing a config field, name its consumer, and reject the
@@ -209,32 +215,32 @@ structures found in legacy packages.
changing this package or its callers.
- The proto (`proto/state/v1/state.proto`, service `StateStoreService`,
package `statev1` in `internal/contracts/state/v1/`) is one gRPC service
fronting every ratified store contract (50 RPCs, including grant management
and deprecated compatibility RPCs); the Go consumer facades
fronting every ratified store contract, including grant management; the Go
consumer facades
stay narrow (`workflow.Store`, `store.TaskStore`, etc., all ≤8 methods
except the `TaskStore` composite) via `staterpc.Client`'s multiple `var _`
assertions -- never add a Go interface method without a matching RPC.
- Error sentinels (`store.ErrStaleTransition`, `ErrBindingNotFound`, ...)
cross the wire via `mapError`/`unmapError` in `values.go`, matched on
`(code, exact canonical message)`. Changing a canonical message string
breaks `errors.Is` on the client without changing behavior visibly --
breaks `errors.Is` on the client without changing behaviour visibly --
treat those message constants as part of the wire contract.
- The State Store is a standalone process (`cmd/archie-state-store`, run via
`archied.RunStateStore`) -- the daemon and Gateway never own `archie.db` or
serve this service in-process; `boot.openStateStore` in
`internal/app/archied/state_store.go` is the only caller of
`openProductionTaskStore`. Never add a second listener for the same
`archied.RunStateStore`) -- the daemon and Gateway never own the task
tables or serve this service in-process; `boot.openStateStore` in
`internal/app/archied/state_store.go` is the only place the task store
is built. Never add a second listener for the same
service, and never reintroduce an in-process serving path in the
daemon/Gateway (`TestOpenStoresNeverOwnsTaskDB` guards this).
- Per-task credentials are scoped, not just authenticated: `daemon.
StateStoreGrantIssuer` (`staterpc.GrantIssuer`) registers a fresh
StateStoreGrantIssuer` (`staterpc.GrantIssuer`) registers a fresh
task-scoped grant at the remote State Store via `RegisterTaskGrant` before
`ContainerPool.Acquire` and revokes it via `RevokeTaskGrant` on `Release`
(`acquireTaskContainer`/`process` in `internal/daemon/daemon.go`). Fails
closed (parks the task) if a State Store is configured but no issuer is
wired -- it must never fall back to forwarding the daemon's own
administrative token. Server-side, `staterpc.TaskGrants.UnaryInterceptor`
authorizes a task-scoped token for only `Update`/`Transition`/`InsertEvent`
authorises a task-scoped token for only `Update`/`Transition`/`InsertEvent`
on its own task ID; every other RPC (including `RegisterTaskGrant`/
`RevokeTaskGrant` themselves and the streaming capture RPCs) requires the
administrative token.
@@ -301,7 +307,7 @@ structures found in legacy packages.
separate fresh-context reviewer pass on every change as a matter of course.
Red-green TDD plus `task check` is the gate; a manual adversarial pass is
opt-in per request — ask before running one. This is the rule for a human or
agent *contributor*. Separately, archied runs the same adversarial review
agent _contributor_. Separately, archied runs the same adversarial review
automatically on the PRs it opens (gated per repo by `repo.review_enabled`)
— see `docs/architecture/adversarial-review.md`. The two paths are distinct:
you run one when asked; archied runs one before it opens a PR.
@@ -338,7 +344,7 @@ bd remember # Persist cross-session architectural facts
through Dolt, not through git commits on this repo.
- **A bead never carries production instance detail.** No operator host name,
hostname, IP or port, filesystem path, PID, or credential -- in the body
*or* the title, since both sync to the Dolt remote and are therefore
_or_ the title, since both sync to the Dolt remote and are therefore
published. Write the mechanism and the evidence shape instead ("a production
host", "the State Store target", "the host's `config.toml`"), and put the
host-specific facts in the operator's memos instance, which the bead may
+13
View File
@@ -0,0 +1,13 @@
NOTICE
This product includes software derived from PR-AF
(https://github.com/Agent-Field/pr-af), Copyright AgentField,
licensed under the Apache License, Version 2.0.
Derived portions: internal/domain/workflow/prreview -- the unified diff
parser, change clustering, blast radius, evidence extraction, scoring,
deduplication, line mapping and review-event selection.
PR-AF declares the Apache License, Version 2.0 in its pyproject.toml and
ships no license file. A copy of the License is available at
https://www.apache.org/licenses/LICENSE-2.0
+179
View File
@@ -0,0 +1,179 @@
[![Quality](https://github.com/samcharles93/archie-core/actions/workflows/quality.yml/badge.svg)](https://github.com/samcharles93/archie-core/actions/workflows/quality.yml)
# Archie
**Event-driven Agentic Automation**
Archie connects events from your systems to agents that can investigate, reason,
and act. Define what an event means, map its data into a workflow, and give that
workflow an agent equipped for the job: its own execution environment, tools,
and identity.
The aim is to automate work across system administration, incident response,
network operations, service management, and software delivery. You define the
process and the access it requires; agents work through its stages, using the
context of each event to decide how to accomplish the task.
Archie is under active development. The model below describes the project's
approved direction, with implementation progressing across event automation and
organisation access control. The
[event automation design](docs/prds/event-automation.md) and
[organisations and access design](docs/prds/orgs-and-access.md) describe those
capabilities and their delivery stages.
## From an event to an outcome
```text
Event source → Event type → Mapping → Binding → Workflow → Agent
```
| Concept | Purpose |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Source** | Receive events from a system such as a firewall, monitoring stack, service desk, or forge. Configure its endpoint and signing requirements. |
| **Event type** | Identify which kind of event arrived from its headers and payload. Infer a schema from captured events or a pasted example. |
| **Mapping** | Extract named, typed parameters from the event. Reuse a mapping across bindings and see how often it matches. |
| **Binding** | Select a workflow, filter the events that should trigger it, and supply its inputs from mapped values or constants. |
| **Workflow** | Define the stages of work, their inputs and outputs, and the agent profile to use. Call other workflows when work needs another specialist or process. |
| **Agent** | Execute the work in a container with the tools for its purpose, acting under its own identity and granted permissions. |
A single source can produce several event types. An event type can feed several
bindings, and each binding can apply its own conditions. This lets the same
incoming data drive different responses without building a custom integration
for every workflow.
For example, a firewall sends a blocked-connection event. Archie identifies the
event type and maps the source address and severity into an investigation
workflow. A network investigator gathers evidence, assesses the activity, and
returns its findings. The workflow could then call a separate containment
workflow, subject to the permissions and approvals configured for that action.
The same model supports other processes:
- **Infrastructure operations:** A monitoring alert starts a diagnostic workflow
to inspect a service, collect evidence, and propose or perform an authorised
recovery action.
- **Service management:** An incoming request supplies the parameters for a
triage, investigation, or fulfilment workflow.
- **Software delivery:** A forge event starts a review or implementation
workflow with the repository's toolchain, validation steps, and pull request
as its output.
These are examples of workflows you can build. Their behaviour comes from the
workflow, tools, and access you configure.
## Agents equipped for their work
An agent profile selects the container image and available tools. You can supply
images with the software needed for a particular environment: network utilities
for an investigator, operational tooling for a systems agent, or a language
runtime and test framework for repository work.
Workflows declare structured inputs and can return structured outputs. They can
run with a scratch workspace, require a repository, or accept one optionally. An
investigation can finish with a report; a maintenance workflow can finish with
an operational result; a coding workflow can finish with a pull request.
Workflows can also call other workflows and pass data between them. Each called
workflow has its own run and agent profile. A caller can wait for the result or
continue while the called workflow runs independently.
See the
[firewall investigation example](examples/workflows/firewall-investigate.yaml)
for a workflow that uses typed inputs, a network investigator profile, and no
repository.
## Organisations, identities, and controlled execution
The approved access model organises automation into **organisations** and
**workspaces**. An organisation owns its members, agent identities, secrets,
profiles, and workflows. Workspaces group sources, mappings, bindings, and runs
by team responsibility or environment, such as network operations in production.
Each organisation can enable the default workflows it needs and add its own.
Agents act as their own identities. A workflow names the identity it runs as;
secrets and permissions are granted to that identity. Starting an agent is an
audited action, with a record of the workflow and the event or member that
initiated it.
The design combines roles for routine administration with attribute-based
policies for resources and execution context. Policies apply from the instance
through the organisation, workspace, identity, workflow, and individual object.
Lower levels can narrow access, and a denial takes precedence. Organisation and
workspace policy also determines which actions require approval from another
member.
Authorised runs receive credentials scoped to their identity, workspace, and
work. Event data supplies the task's inputs; it cannot grant additional access.
The [organisations and access design](docs/prds/orgs-and-access.md) defines this
model; it remains an active implementation area.
## Building and operating automations
The dashboard brings together event inspection, mappings, bindings, workflows,
and task activity. The intended authoring path starts with a real payload or an
example: identify its structure, map the fields you need, select a workflow, and
approve the binding.
Sources default to signed delivery. The event automation design also allows an
explicitly approved unsigned source for systems that cannot sign payloads, with
that status visible to operators. Binding changes require re-approval before
they can dispatch work.
Playbooks and extension points provide additional orchestration through
workflows, modules, channels, and forges. The
[playbook engine design](docs/prds/eda-playbook-engine.md) describes how
registered capabilities become actions that event rules can call.
## Develop locally
The repository requires Go 1.27, [Task](https://taskfile.dev/), Node.js and npm,
and Docker with a running daemon. The development stack starts PostgreSQL 18
through Docker Compose. Install the Go formatting and lint tools listed in
[CLAUDE.md](CLAUDE.md#build--test) before running the full quality gate.
```bash
task dev
```
Open <http://localhost:5173> for the dashboard with Vite hot reload. `task dev`
starts the daemon, Gateway, State Store, UI service, and frontend development
server; it uses [`deployments/dev.toml`](deployments/dev.toml) as a local
configuration overlay. Set credentials and other required settings in your local
Archie configuration as needed.
Useful checks:
```bash
task build # build the service and agent binaries in bin/
task test # run the short Go test suite
task check # run the repository quality gate
```
## Deploy
Start with the [deployment examples](deployments/README.md). They cover a single
GitHub forge, multiple GitHub and Gitea identities, local Ollama, and an
external NATS stack. Copy a suitable template to
`${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`, then set its repository,
model, credential, and service settings for your environment. The examples
describe the required PostgreSQL connection and how to start each process. A
[systemd user service guide](deployments/systemd-user-service.md) is available,
but systemd is optional.
## Documentation
- [Event automation](docs/prds/event-automation.md) — sources, schemas,
mappings, bindings, workflows, and agent profiles.
- [Organisations and access](docs/prds/orgs-and-access.md) — tenancy,
identities, permissions, approvals, and audit.
- [Playbook engine](docs/prds/eda-playbook-engine.md) — event rules and
extensible actions.
- [Architecture decisions](docs/prds/01-project-management.md) — approved design
and open migration questions.
- [Development guides](docs/development/index.md) — change checklists by area.
- [Deployment examples](deployments/README.md) — configuration templates and
operating notes.
- [Release process](RELEASING.md) — how releases are built and published.
Contributions should follow [AGENTS.md](AGENTS.md), including its testing,
generated-file, and commit rules.
+83 -59
View File
@@ -1,49 +1,50 @@
# Releasing
One release stream. `CHANGELOG.md` carries every release section, one generated page
per version describes it, and one tag names the release. A release is one version
covering whatever changed; the components' entries are labelled sections inside it
(`### archied`, `### archie-agent`), not separate numbers or separate pages.
One release stream. `CHANGELOG.md` carries every release section, one generated
page per version describes it, and one tag names the release. A release is one
version covering whatever changed; the components' entries are labelled sections
inside it (`### archied`, `### archie-agent`), not separate numbers or separate
pages.
The host bundle ships six processes — `archied`, `archie-gateway`,
`archie-state-store`, `archie-ui`, `archie-messaging`, `archie-playbooks` — and one
version covers all of them. `archie-agent`, the per-task sandboxed runtime, ships as a
container image and its changes are the `## [version]` release's `### archie-agent`
section.
`archie-state-store`, `archie-ui`, `archie-messaging`, `archie-playbooks` — and
one version covers all of them. `archie-agent`, the per-task sandboxed runtime,
ships as a container image and its changes are the `## [version]` release's
`### archie-agent` section.
`tools/release.sh` decides which commits a release carries from the package closure of
**every shipped binary**, not from commit-message guessing: a change to a package only
the messaging service, state store, playbook runner or UI links still lands in the
changelog. Read its header comment for how it partitions commits and enforces
`main`-only, clean-tree releases.
`tools/release.sh` decides which commits a release carries from the package
closure of **every shipped binary**, not from commit-message guessing: a change
to a package only the messaging service, state store, playbook runner or UI
links still lands in the changelog. Read its header comment for how it
partitions commits and enforces `main`-only, clean-tree releases.
## What justifies a version
`task release:preview VERSION=X.Y.Z` shows exactly what would land, before anything is
written. A commit set that justifies no version produces no version: `release.sh`
exits **3** with "nothing to release" rather than inventing one, so a pipeline can
finish green without tagging.
`task release:preview VERSION=X.Y.Z` shows exactly what would land, before
anything is written. A commit set that justifies no version produces no version:
`release.sh` exits **3** with "nothing to release" rather than inventing one, so
a pipeline can finish green without tagging.
Most sessions touch the gateway side (daemon, gateway, web UI, chat, messaging) and
leave the agent runtime alone. That is no longer a per-component `skip` decision — one
version covers the release — but a runtime code change being merged to `main` is still
not the same as it being in production: the `archie-agent` image is rebuilt by the
release, and a host that runs the agent must pull the new image
(`docker compose pull agent`) to get it.
Most sessions touch the gateway side (daemon, gateway, web UI, chat, messaging)
and leave the agent runtime alone. That is no longer a per-component `skip`
decision — one version covers the release — but a runtime code change being
merged to `main` is still not the same as it being in production: the
`archie-agent` image is rebuilt by the release, and a host that runs the agent
must pull the new image (`docker compose pull agent`) to get it.
## What the notes are for
**Release notes describe the reader's experience of what shipped.** The test is
the reader, not whether a sentence is negative:
- A capability that **never existed** leaves no expectation to correct, so a note
about it reads as a feature to someone who never had the thing — out.
- A capability that **never existed** leaves no expectation to correct, so a
note about it reads as a feature to someone who never had the thing — out.
- **The implementation's journey** — what was rebuilt, what a guard finally
covers, what a browser API refuses to surface — is not the reader's experience
either — out.
- A capability that **shipped but is not yet wired** *is* the reader's
experience, so it belongs, worded as a caveat on the capability and paired with
the behaviour that compensates for it.
- A capability that **shipped but is not yet wired** _is_ the reader's
experience, so it belongs, worded as a caveat on the capability and paired
with the behaviour that compensates for it.
Design constraints and withheld capabilities belong in `docs/architecture/`,
where implementers look, because there they are requirements rather than news.
@@ -60,46 +61,69 @@ task release VERSION=1.3.0 # commit + annotated tag
git push origin main --follow-tags # CI stamps images with real versions
```
`release:prepare` emits bare commit subjects; they are a starting point. Rewrite them
to say what a reader gets, per "What the notes are for" above.
`release:prepare` emits bare commit subjects; they are a starting point. Rewrite
them to say what a reader gets, per "What the notes are for" above.
Pushing is a separate, explicit step — never push without confirming first (see the
repo's general "check before doing anything hard to reverse" rule). The deploy
workflow reads tags pointing at `HEAD`; pushing the commit without its tag gets images
stamped `dev`.
Pushing is a separate, explicit step — never push without confirming first (see
the repo's general "check before doing anything hard to reverse" rule). The
deploy workflow reads tags pointing at `HEAD`; pushing the commit without its
tag gets images stamped `dev`.
### After a release, `main` and the working branch have diverged
The release commit lands on `main` — `tools/release.sh` refuses to run anywhere
else — while the working branch keeps advancing. So after every release, `main`
is ahead by exactly that commit and the branch is ahead by however far it has
moved: **neither tip is an ancestor of the other**, and `--ff-only` fails in
both directions. That refusal reads as "the tree is not ready" when in fact the
tree is fine.
Merge the release commit into the branch first, so any conflict is resolved on
the branch, where it is reversible and nobody is reading the tip:
```bash
git merge main # on the branch
git merge --ff-only <branch> # then, in whichever worktree holds main
```
Confirm which worktree holds `main` with `git worktree list` before the
`--ff-only`. A detached worktree sitting at the same commit will accept it and
move nothing, which looks like success.
## What a release publishes
Tagging one version produces, from a single `deploy` run:
- **Container images** — `ghcr.io/samcharles93/archied:latest` and
`ghcr.io/samcharles93/archie-agent:latest`. The runtime image is rebuilt by the
release, so runtime commits merged to `main` do not reach a running sandbox until the
host pulls the new image.
- **`:latest` names the newest release, not the newest commit.** A push to `main`
that is not a release publishes `archied:edge` (mutable, tracking `main`) and
`archied:sha-<commit>` (immutable) instead, so a release's `:latest` stamping is
not overwritten minutes later by the next ordinary commit. A host that runs
releases follows `:latest`; a host that tracks `main` follows `:edge`.
- **A GitHub Release with a distribution zip** — `dist-zip` builds every process the
reference deployment runs (`archied`, `archie-gateway`, `archie-state-store`,
`archie-ui`, `archie-messaging`, `archie-playbooks`) for linux/amd64, packs them with
`deployments/INSTRUCTIONS.md` and `CHANGELOG.md`, and attaches the zip to the
Release. The Release body is that version's `## [version]` section of `CHANGELOG.md`.
`ghcr.io/samcharles93/archie-agent:latest`. The runtime image is rebuilt by
the release, so runtime commits merged to `main` do not reach a running
sandbox until the host pulls the new image.
- **`:latest` names the newest release, not the newest commit.** A push to
`main` that is not a release publishes `archied:edge` (mutable, tracking
`main`) and `archied:sha-<commit>` (immutable) instead, so a release's
`:latest` stamping is not overwritten minutes later by the next ordinary
commit. A host that runs releases follows `:latest`; a host that tracks `main`
follows `:edge`.
- **A GitHub Release with a distribution zip** — `dist-zip` builds every process
the reference deployment runs (`archied`, `archie-gateway`,
`archie-state-store`, `archie-ui`, `archie-messaging`, `archie-playbooks`) for
linux/amd64, packs them with `deployments/INSTRUCTIONS.md` and `CHANGELOG.md`,
and attaches the zip to the Release. The Release body is that version's
`## [version]` section of `CHANGELOG.md`.
The zip is also uploaded as an Actions artifact, but that is a backup copy: artifacts
expire after 90 days and need an Actions login to download. The Release asset is the
durable, operator-reachable one.
The zip is also uploaded as an Actions artifact, but that is a backup copy:
artifacts expire after 90 days and need an Actions login to download. The
Release asset is the durable, operator-reachable one.
## Gate
CI (`deploy.yml`) runs `task check` before building images, then verifies any release
tag at `HEAD` has a matching `[version]` section in `CHANGELOG.md`. A tag with no
changelog entry is a hard failure. No tags at `HEAD` is a warning, not a failure —
images get stamped `dev`.
CI (`deploy.yml`) runs `task check` before building images, then verifies any
release tag at `HEAD` has a matching `[version]` section in `CHANGELOG.md`. A
tag with no changelog entry is a hard failure. No tags at `HEAD` is a warning,
not a failure — images get stamped `dev`.
One consequence worth knowing when a release commit needs amending: GitHub Actions
runs the workflow **from the commit that triggered it**, so a fix to `deploy.yml` only
takes effect for a release if it is an ancestor of the tagged commit. Delete and re-cut
the tag (`git tag -d`, `task release`) rather than committing the fix on top of an
already-tagged release.
One consequence worth knowing when a release commit needs amending: GitHub
Actions runs the workflow **from the commit that triggered it**, so a fix to
`deploy.yml` only takes effect for a release if it is an ancestor of the tagged
commit. Delete and re-cut the tag (`git tag -d`, `task release`) rather than
committing the fix on top of an already-tagged release.
+97 -334
View File
@@ -10,32 +10,9 @@ tasks:
- task --list
fmt:
desc: Fix and format Go source with the gate's configured formatters
desc: Fix and format Go source
cmds:
# One go fix pass is not a fixpoint: it applies each fixer once, to the
# parse it started with, so a rewrite made by one fixer is only fixed up
# by the next pass. stditerators turns `for i := range t.NumField()` into
# a field iterator that copies its loop variable, and forvar deletes that
# copy on the following pass -- leaving the copy behind for copyloopvar
# to reject. Apply passes until a dry run reports nothing left to fix,
# and fail rather than hand the lint step a tree it must reject.
- |
set -eu
converged=false
for pass in 1 2 3 4 5 6 7 8 9 10; do
go fix ./...
if go fix -diff ./... >/dev/null; then
converged=true
break
fi
done
if [ "$converged" != true ]; then
echo "go fix still rewrites the tree after 10 passes" >&2
exit 1
fi
# This must use the same engine and configuration as task lint. Running
# standalone gofumpt cannot reproduce gci's custom import grouping, so it
# can leave a tree that the gate rejects.
- go fix ./...
- golangci-lint fmt
proto:install:
@@ -53,6 +30,17 @@ tasks:
cmds:
- bash tools/proto.sh lint
db:generate:
desc: "Regenerate the sqlc query code from the schema and query files"
cmds:
- go -C tools tool sqlc generate -f {{.ROOT_DIR}}/internal/infrastructure/postgres/sqlc.yaml
db:check:
desc: "Regenerate the sqlc code and reject uncommitted generated differences"
cmds:
- task: db:generate
- git diff --exit-code -- internal/infrastructure/postgres/postgresdb
proto:check:
desc: Regenerate contracts and reject uncommitted generated differences
cmds:
@@ -60,115 +48,36 @@ tasks:
docs:generate:
desc: Regenerate the committed contract reference from Archie-owned types
summary: |
Writes docs/data/generated/contracts.json. The output is committed, so
this dirties the tree deliberately: review the diff and commit it with
the code change that shifted the contract surface. Never hand-edit the
artifact.
-mod=readonly is mandatory on every `go -C tools` command; see
task test:tools for why.
cmds:
- go -C tools run -mod=readonly ./docsgen --repo-root ..
docs:check:
desc: Verify the committed contract reference matches Archie-owned types
summary: |
Implements Step 6 of docs/architecture/generated-documentation.md:
generates into a temporary directory, compares it with the committed
output, names the authoritative Go definition behind each mismatch, and
exits non-zero without modifying the working tree.
Fix a failure with `task docs:generate`, then commit the result in the
same commit as the code change that shifted the contract surface. This
checks rather than regenerates on purpose: a gate that silently rewrote
the artifact would bless an unintended contract change with no reviewer
ever seeing it, which Step 9 explicitly forbids.
cmds:
- go -C tools run -mod=readonly ./docsgen check --repo-root ..
docs:prds:
desc: Reject session-bound writing in docs/prds
summary: |
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. The tracker records progress; the PRD records the design.
Each finding names the file, the line, the rule and the fix. There is no
--fix: the replacement is a judgement about what the sentence was for.
cmds:
- go -C tools run -mod=readonly ./prdlint --repo-root ..
news:
desc: Regenerate the news page and per-version release notes from the changelog
summary: |
Writes docs/news/releases.json, docs/news/redirects.json and docs/news/.
The JSON is the canonical, host-neutral fact set every renderer reads;
the redirect table maps the retired /news/<component>/<version>/ URLs to
the unified page for that version; the markdown is the MkDocs adapter.
All of it comes from CHANGELOG.md, so cutting a release adds no writing
here.
The files are committed, so this dirties the tree deliberately: review
the diff and commit it with the changelog that produced it. Never
hand-edit a generated release page.
tools/release.sh --tag runs this before the release commit, and it skips
any file whose bytes already match, so a re-run leaves the tree clean.
desc: Regenerate the release data artifacts from the changelog
cmds:
- go -C tools run -mod=readonly ./newsgen --repo-root ..
news:check:
desc: Verify the committed release notes match the changelog
summary: |
Derives the release notes in memory and fails when the committed files
differ, without modifying the working tree. Runs in `task check`, so a
changelog edit cannot land without its regeneration.
A version page the generator does not produce (a page for a release the
changelog no longer carries, or one left in the retired
docs/news/<component>/ layout) is a finding too; a hand-written news item
belongs at the docs/news root instead.
cmds:
- go -C tools run -mod=readonly ./newsgen check --repo-root ..
docs:artifact:
desc: Regenerate the canonical docs artifacts from the Markdown sources
summary: |
Writes docs/data/generated/docs.json and dev-docs.json: every published
page's url, title, section and raw Markdown body, plus the sidebar tree
derived from the layout, one file per set. The JSON is the canonical,
host-neutral fact set a renderer reads; the Markdown stays the source.
MkDocs was the first renderer and the Astro app is the second, so the
artifact is the product.
Two sets, split by audience: the public set (served under /docs/) is what a
reader of the product needs, the development set (/dev/) is architecture/
and prds/. The split and the reasons for what is held back entirely --
archive/, inspiration/, news/ and the credential notes -- live in
tools/docsite/main.go, because a renderer reading an artifact cannot see
why a page is absent from it.
The files are committed, so this dirties the tree deliberately: review the
diff and commit it with the page that produced it.
The artifact's keys are a frozen contract: an application is built against
them, so renaming one breaks a consumer this repository does not compile.
cmds:
- go -C tools run -mod=readonly ./docsite --repo-root ..
docs:artifact:check:
desc: Verify the committed docs artifacts match the Markdown sources
summary: |
Reproduces both artifacts in memory and fails when a committed file
differs, without modifying the working tree. Runs in `task check`, so a
page edit cannot land without its regeneration.
The generated directory is accounted for by docsgen's generatedArtifacts,
which names both files alongside contracts.json: one registry for the
directory rather than one per writer.
cmds:
- go -C tools run -mod=readonly ./docsite check --repo-root ..
@@ -179,111 +88,41 @@ tasks:
lint:
desc: Run golangci-lint
summary: |
Both modules. ./... from the root stops at the root module, so the tools
module was never linted and drifted unseen -- the same hole task check
already closes for tests with test:tools.
cmds:
- golangci-lint run ./...
- task: lint:tools
lint:tools:
desc: Run golangci-lint over the tools module
summary: |
./... from the root stops at the root module, so the tools module was
never linted and drifted unseen -- the same hole task check already
closes for tests with test:tools.
dir: tools
cmds:
- golangci-lint run ./...
lint:playbooks:
desc: "Lint playbook binding dirs for collisions (standalone tool, cmd/archie-playbooks)"
summary: |
Runs the standalone playbook linter (archie-playbooks lint) against
./playbooks by default. It validates playbook YAML binding files
against the same loaders the daemon uses at startup, so a pre-merge
check can never disagree with runtime validation. Exit non-zero on
any collision / malformed file / invalid binding.
Lint a different set of directories directly:
go run ./cmd/archie-playbooks lint -dir ./a -dir ./b
desc: Validate playbook bindings
cmds:
- go run ./cmd/archie-playbooks lint -dir ./playbooks
vuln:
desc: "Scan for known stdlib/dependency CVEs (govulncheck). Not part of task check: it needs network access to the vuln DB and is not build/test-blocking; run it explicitly or in CI."
desc: Scan for known vulnerabilities (requires network access)
cmds:
- govulncheck ./...
deadcode:
desc: "Report functions no shipped binary can reach (whole-program RTA from ./cmd/...). Not part of task check: it reports a standing backlog, so gating on it would fail every run until that backlog is zero."
summary: |
Answers "is this reachable in production", which no linter does:
golangci-lint's unused check is package-scoped, so anything exported
and called from a sibling package looks live even when no binary
reaches it.
Run via `go run ...@latest` deliberately. A locally installed deadcode
built against an older Go than this module exits non-zero and prints
NOTHING, which reads as "no dead code" instead of "analysis failed".
Building it against the repo toolchain makes that failure impossible.
-test=false is the point of the report: a function reached only by its
own tests is not reachable in production.
Read the output in one direction only. RTA over-approximates what is
reachable, so "unreachable func" is sound and worth acting on, while
silence proves nothing: interface dispatch and any address-taken
function (every reflect.ValueOf entry in the *extract tables) is
assumed reachable whether or not it is ever called.
desc: Report unreachable production functions (advisory)
cmds:
- go run golang.org/x/tools/cmd/deadcode@latest -test=false ./cmd/...
reachaudit:
desc: "Classify unreachable code as tracked / untracked / dynamic (tools/reachaudit). Wraps task deadcode with provenance and tracker status."
summary: |
deadcode says a function is unreachable. reachaudit says whether that
is a known gap, a forgotten one, or an artifact of runtime loading
(yaegi, reflection) that must never be deleted.
Two report sections, because a dead whole package and a dead symbol
inside a live one are different failure modes: "unreachable-*" is a
package no shipped binary imports at all; "in-package-*" is a symbol
dead inside a package that IS shipped -- the ChatCourier/Dispatch
shape, where the feature is wired everywhere except its own call site.
Both carry the same tracked/untracked/dynamic classification.
--refresh re-runs the analysis. Without it the tool reuses
/tmp/reachaudit-deadcode-<sha>.txt with no staleness check beyond HEAD
and a dirty-tree check, which will happily report last week's tree
against today's code if HEAD hasn't moved.
--json PATH and --md PATH write the same findings as structured data or
a Markdown report, in addition to the terminal summary.
desc: Classify unreachable code against tracked work (advisory)
cmds:
- python3 tools/reachaudit/reachaudit.py --repo . {{.CLI_ARGS}}
docs:site:
desc: "Build the documentation site into ./site (MkDocs). --strict, so a dead internal link fails the build."
summary: |
Publishes docs/ minus the subtrees held back in mkdocs.yml's
exclude_docs. Requires mkdocs-material:
pip install --user mkdocs-material
Distinct from docs:check, which verifies the generated contract data
rather than the site.
cmds:
- mkdocs build --strict
docs:serve:
desc: "Serve the documentation site locally with live reload on :8000."
cmds:
- mkdocs serve
ui:deps:
desc: Install the dashboard's node dependencies (ui/node_modules is gitignored)
desc: Install dashboard dependencies
internal: true
# Parallel UI checks must share one dependency install.
run: once
dir: ui
cmds:
- npm install --no-audit --no-fund
@@ -297,25 +136,6 @@ tasks:
ui:check:
desc: Rebuild the dashboard into a temporary directory and reject a stale ui/dist
summary: |
ui/dist is committed because the Go build embeds it, so it is a generated
source file. Nothing else in the gate reads it and `task ui` rewrites it
in place, so before this a change to ui/src that landed without the
rebuilt bundle was invisible -- and two agents in two worktrees could each
"pass" while producing different dashboards.
Builds somewhere temporary and compares, never rewriting the committed
artifact, which is the rule docs:check already follows for the contract
reference. A gate that rebuilt ui/dist in place would bless an unintended
UI change with no reviewer ever seeing it.
Fix a failure with `task ui`, then commit the rebuilt bundle in the same
commit as the source change that caused it.
Declares ui:deps like `ui` and `test:ui` do, so a fresh clone works; that
means the gate runs `npm install` once for each dependent. Task's
sources/generates up-to-date check does not apply to a node_modules
directory, so the guard against that is a follow-up, not a claim here.
deps: [ui:deps]
cmds:
- bash tools/uidist.sh check
@@ -323,86 +143,80 @@ tasks:
test:ui:
desc: Test and type-check the dashboard
dir: ui
# ui:deps so a fresh clone fails on a real error rather than on a missing
# node_modules, which is gitignored and installed by nothing else.
deps: [ui:deps]
cmds:
- npm test
- npm run typecheck
# A test event for the capture intake, so the Events surfaces can be driven by
# hand without a real webhook source. See tools/webhook-send.sh --list.
webhook:send:
desc: Send a test event to the dashboard's capture intake (--help for kinds)
cmds:
- bash tools/webhook-send.sh {{.CLI_ARGS}}
bench:prreview:
desc: Score PR review findings on the Martian benchmark (-- -findings DIR; --help for flags)
cmds:
- go run ./cmd/archie-prbench {{.CLI_ARGS}}
dev:
desc: "Develop: archied live-reload + archie-gateway + archie-state-store + archie-ui + Vite HMR together. Open http://localhost:5173"
summary: |
Runs the dev loop in one terminal:
* air rebuilds and restarts archied on Go changes
* archie-gateway serves ChatContract on 127.0.0.1:8585 (archied
and archie-ui dial it; neither embeds a gateway)
* archie-state-store owns archie.db on 127.0.0.1:9091, loopback,
no token (deployments/dev.toml); archied,
archie-gateway and archie-ui dial it -- none owns
the DB in-process
(docs/prds/state-store-contract.md §12 step 7)
* state admin read-only PocketBase surface over archie.db on
127.0.0.1:8686 (view collections only; the gRPC
contract stays the only writer). Served by the
archie-state-store process, not a sixth one.
* archie-ui serves the dashboard on 127.0.0.1:8484 from the
embedded dist (deployments/dev.toml). After the
UI cutover (archie-core-8cda.5.4) archied runs no
dashboard listener: this is what :8484 is.
* vite serves the dashboard with hot reload on :5173,
proxying /api and /events through to archie-ui
on :8484
The gRPC ports come from [services.state].listen and [services.gateway].listen in
deployments/dev.toml, each paired with the target that dials it. Move a pair there
together when a port is already taken on the host.
Open http://localhost:5173 -- not :8484. The Vite server is the one with
hot reload; :8484 serves the last built dist/ and will look stale.
Ctrl-C stops all five.
desc: Run development services and Vite at http://localhost:5173
deps: [dev:daemon, dev:gateway, dev:state-store, dev:dashboard, dev:ui]
dev:daemon:
desc: archied only, live-reloading via air (prefer `task dev`)
dev:postgres:
desc: Start PostgreSQL and wait for readiness
cmds:
- docker compose up -d postgres
- |
set -eu
for _ in $(seq 1 60); do
status=$(docker inspect --format '{{`{{.State.Health.Status}}`}}' "$(docker compose ps -q postgres)" 2>/dev/null || true)
if [ "$status" = "healthy" ]; then
exit 0
fi
sleep 1
done
echo "postgres did not become healthy within 60s" >&2
exit 1
dev:daemon:
desc: Run archied with live reload
cmds:
- |
# The daemon and Gateway read their settings from the State Store at
# boot and exit if it is not up yet; it starts only once PostgreSQL
# is healthy, so wait for its port ([services.state] in
# deployments/dev.toml) first.
for _ in $(seq 1 120); do nc -z 127.0.0.1 9091 && exit 0; sleep 1; done
echo "state store did not come up on 127.0.0.1:9091 within 120s" >&2
exit 1
- air -build.args_bin="-config-overlay,deployments/dev.toml"
dev:dashboard:
desc: archie-ui only, no live-reload (prefer `task dev`)
desc: Run the dashboard backend
cmds:
- go run ./cmd/archie-ui -config-overlay deployments/dev.toml
dev:state-store:
desc: archie-state-store only, no live-reload (prefer `task dev`)
# -admin-addr serves the read-only operator dashboard over the same
# archie.db this process already owns. It is a flag rather than a config
# key for the same reason -ready-addr is: the address is a property of
# how this process was launched, not of the deployment's config document.
desc: Run the State Store with development PostgreSQL
deps: [dev:postgres]
cmds:
- go run ./cmd/archie-state-store -config-overlay deployments/dev.toml -admin-addr 127.0.0.1:8686
- go run ./cmd/archie-state-store -config-overlay deployments/dev.toml
dev:gateway:
desc: archie-gateway only, no live-reload (prefer `task dev`)
# The overlay carries [services.state].target, which archie-gateway
# requires (openStateStoreAdapter fails closed on an empty target).
# Without it `task dev` leaves the gateway dialling whatever the
# developer's installed config names, or unable to start at all, while
# archied, archie-ui and the state store all dial 127.0.0.1:9091.
desc: Run the development Gateway
cmds:
- |
# The daemon and Gateway read their settings from the State Store at
# boot and exit if it is not up yet; it starts only once PostgreSQL
# is healthy, so wait for its port ([services.state] in
# deployments/dev.toml) first.
for _ in $(seq 1 120); do nc -z 127.0.0.1 9091 && exit 0; sleep 1; done
echo "state store did not come up on 127.0.0.1:9091 within 120s" >&2
exit 1
- go run ./cmd/archie-gateway -config-overlay deployments/dev.toml
dev:ui:
desc: Vite dev server only, expects archie-ui already running (prefer `task dev`)
desc: Run Vite (requires the dashboard backend)
dir: ui
cmds:
- npm install --no-audit --no-fund
@@ -410,17 +224,6 @@ tasks:
dev:mobile:
desc: Serve the dashboard on your LAN (token-protected) for phone viewing
summary: |
Starts archie-ui with a LAN-reachable [web] bind and a minted dashboard
token, printing the URL (LAN IP + token) and a QR code to scan. After
the UI cutover the dashboard is archie-ui's process: this task starts
archie-ui only. Run the daemon separately (task dev, or archied) for
actual archie operation -- two daemons sharing the bot identity would
double-poll the forge.
The frontend served is the embedded dist, so run `task ui` if you
changed the frontend. The token file is the path archied used to mint
before the cutover, so an existing phone setup keeps its token.
deps:
- ui
cmds:
@@ -439,26 +242,19 @@ tasks:
build:
desc: Build archie services and agent binaries
# A from-source build is not a release, and CI is the only thing that stamps
# one: the version a release carries is written into the artifact CI
# publishes, the zip's binaries and the container image, and is never
# derived from whatever tags a local checkout happens to have.
#
# Deriving it here also made the stamp a function of the commit graph, which
# is the one input a content-checksum build cache cannot see: an empty
# commit moved `git describe` while `task build` still reported "up to date"
# and shipped the previous stamp (archie-core-pdq2). Stamping `dev` removes
# the non-file input rather than caching it, and a local build's
# traceability is the checkout it came from.
vars:
GATEWAY_VERSION: dev
RUNTIME_VERSION: dev
GATEWAY_VERSION: '{{.GATEWAY_VERSION | default "dev"}}'
RUNTIME_VERSION: '{{.RUNTIME_VERSION | default "dev"}}'
SERVICE_LDFLAGS: >-
-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion={{.GATEWAY_VERSION}}
-X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion={{.RUNTIME_VERSION}}
-X github.com/samcharles93/archie-core/internal/installtype.buildType=binary
-X github.com/samcharles93/archie-core/internal/buildinfo.Version={{.GATEWAY_VERSION}}
-X github.com/samcharles93/archie-core/internal/buildinfo.Runtime={{.RUNTIME_VERSION}}
sources:
- "**/*.go"
- go.mod
- go.sum
# ui/dist is committed and embedded by ui/embed.go (//go:embed all:dist),
# so it is a build input even though no .go file names it.
- "ui/dist/**"
generates:
- "{{.BIN_DIR}}/archied"
@@ -468,87 +264,54 @@ tasks:
- "{{.BIN_DIR}}/archie-messaging"
- "{{.BIN_DIR}}/archie-agent"
cmds:
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion={{.GATEWAY_VERSION}} -X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion={{.RUNTIME_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archied ./cmd/archied
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion={{.GATEWAY_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-gateway ./cmd/archie-gateway
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-state-store ./cmd/archie-state-store
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-ui ./cmd/archie-ui
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-messaging ./cmd/archie-messaging
# One flag set for every service, matching scripts/archie-update-install
# and the release workflow, so each binary reports the same version.
- for: [archied, archie-gateway, archie-state-store, archie-ui, archie-messaging]
cmd: go build -ldflags "{{.SERVICE_LDFLAGS}}" -o {{.BIN_DIR}}/{{.ITEM}} ./cmd/{{.ITEM}}
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/app/agentworker.version={{.RUNTIME_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-agent ./cmd/archie-agent
test:
desc: Run the Go test suite
desc: Run short Go tests with caching
cmds:
- go test -short ./...
test:full:
desc: Run the whole Go test suite uncached, including the wall-clock-bound tests
cmds:
- go test ./... -count=1
test:tools:
desc: Run the nested tools module suite, refusing to rewrite its go.mod
summary: |
tools/go.mod replaces the root module, so its build list must satisfy
the root module's requirements. When the root moves on, the tools module
goes stale and any plain go command there rewrites tools/go.mod and
tools/go.sum to catch up, leaving an unrelated dirty diff.
-mod=readonly is explicit because a developer's global GOFLAGS=-mod=mod
overrides the toolchain default and re-enables the silent rewrite.
Fix a failure here with: go -C tools mod tidy
cmds:
- go -C tools test -mod=readonly ./... -count=1
check:
desc: "Full quality gate: fmt, proto, docs, vet, lint, build, test, tools tests, ui tests and bundle"
desc: Run the full quality gate
# Finish mutations before starting parallel checks.
cmds:
- task: fmt
- task: proto:lint
- task: proto:check
- task: db:check
- task: check:readonly
check:readonly:
internal: true
deps:
- task: proto:lint
- task: docs:check
- task: docs:prds
# Release notes are generated from the changelogs the release process
# already freezes. Left out of the gate, a changelog edit would land
# while the published notes silently lag behind it.
- task: news:check
# The public-docs artifact is what the site renders, so a page edit that
# does not reach it publishes a site that disagrees with the repository.
- task: docs:artifact:check
- task: vet
- task: lint
- task: build
- task: test
# The tools module is not covered by ./... from the root; without this
# its dependency drift is only ever discovered by a command that
# silently repairs it.
- task: test:tools
# The dashboard's suite runs here too. Left out of the gate it rots
# silently: nothing else executes it, so a broken DOM primitive ships.
- task: test:ui
# ...and so is the bundle that suite is built from. ui/dist is committed
# and embedded; nothing else checks it against ui/src, and `task ui`
# rewrites it in place, so a forgotten rebuild used to leave no trace in
# the gate at all.
- task: ui:check
contract:
desc: "Report contract conformance: declared surfaces, their consumers, and the drift between them"
summary: |
Walks every declared contract surface -- the two gRPC services, the
dashboard HTTP API -- and classifies each subject as consumed,
declared-unconsumed, undeclared, or a stale declaration.
ADVISORY, and deliberately NOT part of `task check`, matching
tools/reachaudit. The surfaces are discovered by scanning source text:
the .proto files, the adapter bodies that call the generated client, the
route registrations in internal/webui, and the path literals under
ui/src. That makes it useful for a periodic survey and unsafe as a gate
-- a rename or a reformat elsewhere in the tree can change its output
without anything being wrong, and it has already produced a batch of
false "unconsumed" readings once when the dashboard's request helper was
renamed.
Read the findings as a prompt to go and check, not as a verdict. To make
it fail on an undeclared or stale entry, pass --strict by hand:
go -C tools run ./contractaudit --repo-root .. --strict
See docs/prds/contract-conformance-audit.md.
desc: Report contract conformance (advisory)
cmds:
- go -C tools run ./contractaudit --repo-root ..
@@ -560,14 +323,14 @@ tasks:
vars: [VERSION]
release:prepare:
desc: "Write the generated notes into CHANGELOG.md, uncommitted, for editing (VERSION=1.2.0)"
desc: Prepare changelog notes for editing (VERSION=1.2.0)
cmds:
- tools/release.sh --version {{.VERSION}} --prepare
requires:
vars: [VERSION]
release:
desc: "Freeze the edited changelog into a release commit and tag (VERSION=1.2.0). Run release:prepare first."
desc: Commit and tag the prepared release (VERSION=1.2.0)
cmds:
- tools/release.sh --version {{.VERSION}} --tag
requires:
+2
View File
@@ -53,6 +53,8 @@ func TestCommandBoundary(t *testing.T) {
"run": true,
"runCommand": true,
"natsConnectionSettings": true,
"runRelay": true,
"runMCP": true,
}
for _, declaration := range file.Decls {
function, ok := declaration.(*ast.FuncDecl)
+83
View File
@@ -8,8 +8,10 @@ import (
"fmt"
"io"
"log/slog"
"net"
"os"
"os/signal"
"strings"
"syscall"
"github.com/samcharles93/archie-core/internal/app/agentworker"
@@ -26,6 +28,12 @@ func run() int {
}
func runCommand(args []string, getenv func(string) string, stderr io.Writer, runWorker workerRunner) int {
if len(args) > 0 && args[0] == "relay" {
return runRelay(args[1:], stderr, agentworker.RunRelay)
}
if len(args) > 0 && args[0] == "mcp" {
return runMCP(args[1:], stderr, agentworker.RunCaptureMCP)
}
flags := flag.NewFlagSet("archie-agent", flag.ContinueOnError)
flags.SetOutput(stderr)
natsURLFlag := flags.String("nats-url", "", "NATS server URL (defaults to NATS_URL)")
@@ -81,3 +89,78 @@ func natsConnectionSettings(flagURL string, getenv func(string) string) (url, to
}
return url, getenv("NATS_TOKEN")
}
type relayServer func(ctx context.Context, forwards map[string]string) error
// runRelay is the sandbox egress relay: the container on both a sandbox's
// isolated network and the host-reachable one, forwarding a fixed set of
// ports to the proxy, NATS and the State Store.
func runRelay(args []string, stderr io.Writer, serve relayServer) int {
flags := flag.NewFlagSet("archie-agent relay", flag.ContinueOnError)
flags.SetOutput(stderr)
forwards := map[string]string{}
flags.Func("forward", "listen=target: forward connections on listen to target (repeatable)", func(v string) error {
listen, target, ok := strings.Cut(v, "=")
if !ok || listen == "" || target == "" {
return fmt.Errorf("%q is not listen=target", v)
}
if _, _, err := net.SplitHostPort(listen); err != nil {
return fmt.Errorf("listen address %q: %w", listen, err)
}
if _, _, err := net.SplitHostPort(target); err != nil {
return fmt.Errorf("target %q: %w", target, err)
}
if _, dup := forwards[listen]; dup {
return fmt.Errorf("listen address %q is forwarded twice", listen)
}
forwards[listen] = target
return nil
})
if err := flags.Parse(args); err != nil {
if errors.Is(err, flag.ErrHelp) {
return 0
}
return 2
}
if len(forwards) == 0 {
fmt.Fprintln(stderr, "error: at least one -forward is required")
flags.Usage()
return 1
}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
if err := serve(ctx, forwards); err != nil {
fmt.Fprintln(stderr, "error:", err)
return 1
}
return 0
}
type mcpServer func(ctx context.Context, specPath, capturesPath string) error
// runMCP serves a stage's capture tools to a harness over stdio. The
// harness starts it, so it runs as the harness user and holds no secrets.
func runMCP(args []string, stderr io.Writer, serve mcpServer) int {
flags := flag.NewFlagSet("archie-agent mcp", flag.ContinueOnError)
flags.SetOutput(stderr)
spec := flags.String("spec", "", "JSON file listing the stage's capture tools")
captures := flags.String("captures", "", "file accepted capture calls are appended to")
if err := flags.Parse(args); err != nil {
if errors.Is(err, flag.ErrHelp) {
return 0
}
return 2
}
if *spec == "" || *captures == "" {
fmt.Fprintln(stderr, "error: -spec and -captures are required")
flags.Usage()
return 1
}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
if err := serve(ctx, *spec, *captures); err != nil {
fmt.Fprintln(stderr, "error:", err)
return 1
}
return 0
}
+54
View File
@@ -0,0 +1,54 @@
package main
import (
"bytes"
"context"
"maps"
"strings"
"testing"
)
func TestRunRelay(t *testing.T) {
noServe := func(t *testing.T) relayServer {
return func(context.Context, map[string]string) error {
t.Error("the relay served despite a usage error")
return nil
}
}
for name, args := range map[string][]string{
"no forward": {},
"a forward with no =": {"-forward", "127.0.0.1:0"},
"a forward with no port": {"-forward", "=172.17.0.1:3129"},
"one listen address used": {"-forward", ":3128=a:1", "-forward", ":3128=b:2"},
} {
t.Run(name+" is a usage error", func(t *testing.T) {
var stderr bytes.Buffer
if code := runRelay(args, &stderr, noServe(t)); code == 0 {
t.Fatalf("exit 0, want a usage error; stderr %q", stderr.String())
}
})
}
t.Run("every forward is served", func(t *testing.T) {
var got map[string]string
serve := func(_ context.Context, forwards map[string]string) error {
got = forwards
return nil
}
args := []string{"-forward", ":3128=172.17.0.1:3129", "-forward", ":4222=172.17.0.1:4222"}
if code := runRelay(args, &bytes.Buffer{}, serve); code != 0 {
t.Fatalf("exit %d, want 0", code)
}
want := map[string]string{":3128": "172.17.0.1:3129", ":4222": "172.17.0.1:4222"}
if !maps.Equal(got, want) {
t.Fatalf("served %v, want %v", got, want)
}
})
}
func TestRelaySubcommandRoutes(t *testing.T) {
var stderr bytes.Buffer
code := runCommand([]string{"relay"}, func(string) string { return "" }, &stderr, nil)
if code != 1 || !strings.Contains(stderr.String(), "-forward") {
t.Fatalf("relay subcommand exit %d stderr %q; want the relay's own usage error", code, stderr.String())
}
}
+2 -1
View File
@@ -36,7 +36,8 @@ type bannedCategory struct {
var deletionGate = []bannedCategory{
{"state store", []string{
"modernc.org/sqlite",
modulePath + "internal/store",
"github.com/jackc/pgx",
modulePath + "internal/infrastructure/postgres",
}},
{"daemon runtime", []string{
modulePath + "internal/daemon",
+48 -17
View File
@@ -3,23 +3,22 @@
// playbook YAML binding files against the same schema the daemon loads at
// startup, so a pre-merge check can never disagree with runtime validation.
//
// Today it ships one mode (lint). The command dispatch is a table from day
// one, so a future serve/lsp mode slots in without restructuring -- both
// modes are entrypoints into the same validation source in
// internal/domain/workflow.
// It ships two modes: lint for CI, and serve, a language server that
// publishes the same findings as editor diagnostics. Both call the loaders
// the daemon runs.
//
// Known limitation (as of this slice): findings are file-granular, not
// line-granular. The loader decodes playbooks with yaml.Unmarshal into a
// plain map, which discards line numbers; a compiler-style file:line
// diagnostic needs a yaml.Node decoding upgrade, which is out of scope
// here and tracked separately.
// A finding about one binding key leads with the key's file:line; a file
// that does not parse is reported by path with the YAML parser's message.
package main
import (
"context"
"flag"
"fmt"
"io"
"os"
"os/signal"
"syscall"
"github.com/samcharles93/archie-core/internal/app/archieplaybooks"
"github.com/samcharles93/archie-core/internal/buildinfo"
@@ -34,7 +33,8 @@ func run(args []string, stderr io.Writer) int {
// set and returns an exit code. Adding serve/lsp later is a new entry
// here, not a restructuring.
commands := map[string]func([]string, io.Writer) int{
"lint": runLint,
"lint": runLint,
"serve": runServe,
}
if len(args) > 0 && (args[0] == "-version" || args[0] == "--version") {
@@ -59,27 +59,58 @@ func run(args []string, stderr io.Writer) int {
return cmd(args[1:], stderr)
}
// runLint validates one or more playbook directories against the domain
// loaders and reports collisions / malformed files / invalid bindings.
// runLint validates routing binding directories (-dir) and an EDA playbook
// directory (-eda-dir) against the loaders the daemon runs at startup.
// Exit codes: 0 clean, 1 findings, 2 usage error.
func runLint(args []string, stderr io.Writer) int {
flags := flag.NewFlagSet("archie-playbooks lint", flag.ContinueOnError)
flags.SetOutput(stderr)
var dirs multiFlag
flags.Var(&dirs, "dir", "playbook directory to lint (repeatable)")
flags.Var(&dirs, "dir", "routing binding directory to lint (repeatable)")
edaDir := flags.String("eda-dir", "", "EDA playbook directory to lint (the daemon's eda_playbook_dir)")
if err := flags.Parse(args); err != nil {
return 2 // flag.ContinueOnError already printed the message
}
if len(dirs) == 0 {
fmt.Fprintln(stderr, "lint: at least one -dir is required")
if len(dirs) == 0 && *edaDir == "" {
fmt.Fprintln(stderr, "lint: at least one -dir or an -eda-dir is required")
flags.Usage()
return 2
}
result := archieplaybooks.Lint(dirs, stderr)
return result.ExitCode
code := 0
if len(dirs) > 0 {
code = max(code, archieplaybooks.Lint(dirs, stderr).ExitCode)
}
if *edaDir != "" {
code = max(code, archieplaybooks.LintEDA(*edaDir, stderr).ExitCode)
}
return code
}
// runServe runs the language server on stdin/stdout until the editor
// disconnects or the process is signalled.
func runServe(args []string, stderr io.Writer) int {
if len(args) > 0 {
fmt.Fprintln(stderr, "serve: takes no arguments; the editor speaks LSP on stdin/stdout")
return 2
}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
if err := archieplaybooks.Serve(ctx, stdio{}); err != nil {
fmt.Fprintln(stderr, "serve:", err)
return 1
}
return 0
}
// stdio joins stdin and stdout into the one stream the language server reads
// and writes.
type stdio struct{}
func (stdio) Read(p []byte) (int, error) { return os.Stdin.Read(p) }
func (stdio) Write(p []byte) (int, error) { return os.Stdout.Write(p) }
func (stdio) Close() error { return os.Stdin.Close() }
// multiFlag collects repeated -dir flags.
type multiFlag []string
+13
View File
@@ -73,3 +73,16 @@ func writeFile(t *testing.T, path, content string) {
t.Fatalf("write %s: %v", path, err)
}
}
// -eda-dir alone is a complete lint request, and its findings set the exit
// code.
func TestRunLintEDADir(t *testing.T) {
dir := t.TempDir()
if err := os.WriteFile(filepath.Join(dir, "pb.yaml"), []byte("trigger:\n kind: bug\nactions:\n - position: module\n kind: nope\n"), 0o600); err != nil {
t.Fatal(err)
}
var stderr bytes.Buffer
if code := run([]string{"lint", "-eda-dir", dir}, &stderr); code != 1 {
t.Fatalf("run(lint -eda-dir) = %d, want 1; stderr: %s", code, stderr.String())
}
}
+41
View File
@@ -0,0 +1,41 @@
// Command archie-prbench scores the PR reviewer on the Martian
// Code-Review-Bench problems. See docs/prds/pr-review-agent.md, Verification.
package main
import (
"context"
"flag"
"fmt"
"os"
"os/signal"
"strings"
"syscall"
"github.com/samcharles93/archie-core/internal/app/prbench"
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
)
func main() { os.Exit(run()) }
func run() int {
var opts prbench.Options
var problems string
flag.StringVar(&opts.Config, "config", configuration.DefaultConfigPath(), "configuration file whose providers serve the judge model")
flag.StringVar(&opts.Fixtures, "findings", "", "directory of <problem id>.json findings to score")
flag.StringVar(&opts.JudgeModel, "judge-model", "anthropic/claude-sonnet-4.6", "provider/model of the independent judge")
flag.StringVar(&opts.Out, "out", "prbench-out", "directory for per-problem results and summary.json")
flag.StringVar(&problems, "problems", "", "comma-separated problem ids (default: all)")
flag.IntVar(&opts.Concurrency, "concurrency", 4, "problems judged at once")
flag.Parse()
if problems != "" {
opts.Problems = strings.Split(problems, ",")
}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
if _, err := prbench.Run(ctx, opts, os.Stdout); err != nil {
fmt.Fprintln(os.Stderr, "archie-prbench:", err)
return 1
}
return 0
}
+4 -10
View File
@@ -1,11 +1,6 @@
// Command archie-state-store hosts the State Store's gRPC contract and owns
// the single archie.db SQLite file. It is the .4.3 companion to the daemon's
// in-process State Store server: the same StateStoreService .4.2 serves, but
// extracted into its own process with its own store lifecycle.
//
// The gateway's session SQLite is owned by the separate archie-gateway process
// and is untouched here. See docs/prds/state-store-contract.md (rev. 2c) §5,
// §9 and §11.
// Command archie-state-store hosts the State Store's gRPC contract and is the
// only process that owns the PostgreSQL stores behind it. See
// docs/prds/state-store-contract.md §5, §9 and §11.
package main
import (
@@ -39,9 +34,8 @@ func run() int {
flag.StringVar(&options.Listen, "listen", "", "state store gRPC listen address (defaults to [services.state].listen, else 127.0.0.1:9090)")
flag.StringVar(&options.Token, "token", "", "bearer token required for a non-loopback listener (defaults to [services.state].target_token)")
flag.StringVar(&options.ReadyAddr, "ready-addr", "", "optional readiness HTTP listen address (e.g. 127.0.0.1:9091)")
flag.StringVar(&options.AdminAddr, "admin-addr", "", "optional read-only operator dashboard listen address (e.g. 127.0.0.1:8090)")
flag.Usage = func() {
fmt.Fprintf(flag.CommandLine.Output(), "usage: archie-state-store [flags] # serve the State Store gRPC contract\n\noffline recovery: archie-state-store <backup|restore|validate|rollback> -h\n\n")
fmt.Fprintf(flag.CommandLine.Output(), "usage: archie-state-store [flags] # serve the State Store gRPC contract\n\noffline recovery: archie-state-store <backup|restore|validate|rollback|import> -h\n\n")
flag.PrintDefaults()
}
flag.Parse()
+10
View File
@@ -0,0 +1,10 @@
package main
import (
"os"
"testing"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest"
)
func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) }
+31 -29
View File
@@ -5,10 +5,10 @@
//
// This is the .4.7 end-to-end verification for
// docs/prds/state-store-contract.md (rev. 2c): it proves the process owns the
// single archie.db task SQLite, serves the combined task/event/capture
// task store, serves the combined task/event/capture
// surface over one gRPC service, preserves error-sentinel fidelity across the
// wire, honours a per-call deadline, survives a restart/recovery cycle, and
// is the sole owner of the SQLite file. See §5 (binary layout), §6 (handoff),
// is the sole owner of the store. See §5 (binary layout), §6 (handoff),
// §7 (error semantics), §11 (remote adapter) and §12 step 7/8 (single owner).
package main
@@ -37,9 +37,10 @@ import (
"github.com/samcharles93/archie-core/internal/domain/binding"
"github.com/samcharles93/archie-core/internal/domain/mapping"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest"
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
"github.com/samcharles93/archie-core/internal/store"
)
// repoRoot walks up from the test's source directory to find the module root
@@ -88,13 +89,19 @@ func buildBinary(t *testing.T, dir string) string {
// while keeping the process minimal: the standalone binary takes its gRPC
// listen address from -listen or [services.state].listen, never from the
// target, so the config only needs the fields validation requires plus the
// db_path it owns. The
// database_url it owns. The
// forge token resolves from an env var, so no real credential is needed.
func writeMinimalConfig(t *testing.T, dir string) string {
t.Helper()
return writeConfigFor(t, dir, pgtest.URL(t))
}
// writeConfigFor is writeMinimalConfig naming the database at url.
func writeConfigFor(t *testing.T, dir, url string) string {
t.Helper()
cfg := filepath.Join(dir, "config.toml")
content := fmt.Sprintf(`bot_user = "archie-bot"
db_path = %q
database_url = %q
[forge]
type = "github"
host = "https://github.example.com"
@@ -102,7 +109,7 @@ token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" }
[[repos]]
owner = "acme"
name = "widget"
`, filepath.Join(dir, "archie.db"))
`, url)
if err := os.WriteFile(cfg, []byte(content), 0o600); err != nil {
t.Fatalf("write config: %v", err)
}
@@ -285,13 +292,13 @@ func (p *stateStoreProcess) stop(t *testing.T) {
}
// contract is the combined consumer surface a daemon/gateway/agent mixes: the
// task lifecycle + events surface (store.TaskStore) and the capture surface.
// task lifecycle + events surface (storecontract.TaskStore) and the capture surface.
// Mapping/binding/dispatch is exercised separately in
// TestStateStoreRealProcessRemoteSurfaces via the concrete Client, which
// asserts against each narrow interface at compile time.
type contract interface {
store.TaskStore
store.CaptureStore
storecontract.TaskStore
storecontract.CaptureStore
}
// dial opens a gRPC connection to the state store process and wraps it in the
@@ -309,8 +316,8 @@ func dial(t *testing.T, addr string) contract {
// capture builds a CapturedEvent without pulling the whole store field set
// into every call site.
func capture(source, body string) store.CapturedEvent {
return store.CapturedEvent{Source: source, Body: body, Authenticated: true}
func capture(source, body string) storecontract.CapturedEvent {
return storecontract.CapturedEvent{Source: source, Body: body, Authenticated: true}
}
// TestStateStoreRealProcessSmoke exercises the actual archie-state-store
@@ -407,14 +414,14 @@ func TestStateStoreRealProcessSmoke(t *testing.T) {
}
t.Run("error_sentinel_fidelity", func(t *testing.T) {
// A stale transition must rehydrate to store.ErrStaleTransition across
// A stale transition must rehydrate to storecontract.ErrStaleTransition across
// the wire (§7). Because the binary is up and we dialed it, a sentinel
// mismatch here would surface as a transport error, so a pass proves
// the gRPC mapError/unmapError round-trip, not just the in-process
// adapter.
err := cl.Transition(ctx, task.ID, "queued", "merged", "")
if !errors.Is(err, store.ErrStaleTransition) {
t.Fatalf("stale Transition = %v, want store.ErrStaleTransition", err)
if !errors.Is(err, storecontract.ErrStaleTransition) {
t.Fatalf("stale Transition = %v, want storecontract.ErrStaleTransition", err)
}
})
@@ -427,17 +434,13 @@ func TestStateStoreRealProcessSmoke(t *testing.T) {
}
})
t.Run("single_owner_sqlite", func(t *testing.T) {
// The binary owns one task SQLite file (db_path + "-tasks.sqlite");
// the consumer called only gRPC methods and never opened a store file.
// The config anchor path itself must not be opened directly (no dual
// store ownership, §12 step 8).
taskFile := filepath.Join(dir, "archie.db-tasks.sqlite")
if _, err := os.Stat(taskFile); err != nil {
t.Fatalf("state store did not own %s: %v", taskFile, err)
}
if _, err := os.Stat(filepath.Join(dir, "archie.db")); err == nil {
t.Fatalf("config anchor path was opened directly; dual store ownership violated §12 step 8")
t.Run("serves_from_postgres_only", func(t *testing.T) {
// The binary serves every store from database_url: no SQLite file
// appears in its directory.
for _, name := range []string{"archie.db", "archie.db-tasks.sqlite", "archie.db-eda.sqlite"} {
if _, err := os.Stat(filepath.Join(dir, name)); err == nil {
t.Fatalf("state store created %s; it serves from Postgres only", name)
}
}
})
}
@@ -468,7 +471,7 @@ func TestStateStoreRealProcessDeadline(t *testing.T) {
}
// TestStateStoreRealProcessRestartRecovery starts the process, writes a task,
// stops it (SIGTERM), restarts it on the same config/db_path, and verifies the
// stops it (SIGTERM), restarts it on the same config, and verifies the
// task and its events were recovered from the on-disk SQLite -- the
// restart/recovery path the runbook relies on when archie-state-store is
// restarted as a service.
@@ -591,7 +594,7 @@ func TestStateStoreRealProcessRemoteSurfaces(t *testing.T) {
}
bindingID, err := cl.InsertBinding(ctx, binding.Binding{
Name: "b1", Matcher: binding.Matcher{Source: "sentry"}, MappingID: mappingID,
Workflow: "implement", Secret: "0123456789abcdef0123456789abcdef",
Workflow: "implement",
})
if err != nil || bindingID == "" {
t.Fatalf("InsertBinding = (%q, %v)", bindingID, err)
@@ -602,7 +605,6 @@ func TestStateStoreRealProcessRemoteSurfaces(t *testing.T) {
if err := cl.UpdateBinding(ctx, binding.Binding{
ID: bindingID, Name: "b1", Matcher: binding.Matcher{Source: "sentry"},
MappingID: mappingID, Workflow: "implement", Owner: "acme", Repo: "widget",
Secret: "0123456789abcdef0123456789abcdef",
}); err != nil {
t.Fatalf("UpdateBinding: %v", err)
}
@@ -614,7 +616,7 @@ func TestStateStoreRealProcessRemoteSurfaces(t *testing.T) {
}
// Remote surfaces share error-sentinel fidelity on the wire too.
missing := mapping.Mapping{ID: "rabsent00000000", Name: "x", Fields: []mapping.Field{{Name: "a", Path: "a", Type: mapping.TypeString}}}
if err := cl.UpdateMapping(ctx, missing); !errors.Is(err, store.ErrMappingNotFound) {
if err := cl.UpdateMapping(ctx, missing); !errors.Is(err, storecontract.ErrMappingNotFound) {
t.Fatalf("UpdateMapping missing = %v, want ErrMappingNotFound", err)
}
}
+23 -17
View File
@@ -19,18 +19,27 @@ const recoveryUsage = `usage: archie-state-store <command> [flags]
With no command, archie-state-store serves the State Store gRPC contract.
The recovery commands operate on the task database file directly -- the
configured db_path with "-tasks.sqlite" appended -- and are how an operator
recovers a database the control plane will not start on. Stop the State Store
first: restore and rollback rewrite the file and refuse while another process
owns it, while backup takes a consistent snapshot of a serving store.
The recovery commands are how an operator recovers a database the control
plane will not start on. They operate on the PostgreSQL database the
configuration's database_url names, through pg_dump and pg_restore (which
must be on PATH).
backup -db FILE -out FILE write a snapshot of the database
restore -db FILE -from FILE replace the database with a snapshot
validate -db FILE [-config FILE] check the file, its stored settings and the
configuration the daemon would boot with
rollback -db FILE -kind KIND replay an earlier revision of a stored
backup takes a consistent snapshot of a serving database. restore is
destructive and offline: stop every archie service first, since it refuses
while any of them holds its ownership claim, and every write made after the
snapshot is lost. rollback refuses while the State Store serves. There is no
automatic schema rollback: the way back from a migration is restoring the
snapshot taken before it.
backup -out FILE write a snapshot of the database
restore -from FILE replace the database with a snapshot
validate check the database, its stored settings and
the configuration the daemon would boot with
rollback -kind KIND replay an earlier revision of a stored
[-revision N] resource through the ordinary replace
Every command takes -config FILE and -config-overlay FILE: the configuration
the daemon boots with, which names the database.
`
// runRecovery parses and performs one offline recovery command, reporting the
@@ -54,17 +63,14 @@ func runRecovery(args []string, stdout, stderr io.Writer) int {
flags := flag.NewFlagSet("archie-state-store "+command, flag.ContinueOnError)
flags.SetOutput(stderr)
flags.Usage = func() { fmt.Fprint(stderr, recoveryUsage) }
flags.StringVar(&options.DB, "db", "", "task database file the State Store owns (<db_path>-tasks.sqlite)")
flags.StringVar(&options.Out, "out", "", "snapshot file backup writes")
flags.StringVar(&options.From, "from", "", "snapshot file restore reads")
flags.StringVar(&options.Kind, "kind", "", "control-plane resource kind rollback replays")
flags.Int64Var(&options.Revision, "revision", 0, "revision rollback replays (default: the newest one older than the current value)")
// Only validate asks a question about the process rather than the file, so
// only validate takes the configuration the process would boot with.
if command == archied.RecoveryValidate {
flags.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory the daemon boots with")
flags.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory")
}
// The configuration names the PostgreSQL database, and validate also checks
// the stored settings against it.
flags.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory the daemon boots with")
flags.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory")
if err := flags.Parse(args[1:]); err != nil {
// A requested help is not a wrong command line: the usage above is the
// answer, and the serve path exits 0 for the same request.
@@ -0,0 +1,43 @@
package main
import (
"os"
"path/filepath"
"strings"
"testing"
)
// Without -db every recovery command targets the configured PostgreSQL
// database, so each one accepts -config and refuses, naming the key, when the
// configuration names no database.
func TestRecoveryWithoutDBUsesTheConfiguredDatabase(t *testing.T) {
dir := t.TempDir()
configPath := writeMinimalConfig(t, dir)
raw, err := os.ReadFile(configPath)
if err != nil {
t.Fatalf("read config: %v", err)
}
var kept []string
for line := range strings.Lines(string(raw)) {
if !strings.HasPrefix(line, "database_url") {
kept = append(kept, line)
}
}
if err := os.WriteFile(configPath, []byte(strings.Join(kept, "")), 0o600); err != nil {
t.Fatalf("write config: %v", err)
}
tests := [][]string{
{"backup", "-out", filepath.Join(dir, "snapshot.dump")},
{"restore", "-from", filepath.Join(dir, "snapshot.dump")},
{"validate"},
{"rollback", "-kind", "settings"},
}
for _, args := range tests {
t.Run(args[0], func(t *testing.T) {
code, _, stderr := runRecoveryCmd(t, append(args, "-config", configPath)...)
if code != 1 || !strings.Contains(stderr, "database_url") {
t.Fatalf("%s exited %d, stderr %q; want 1 naming database_url", args[0], code, stderr)
}
})
}
}
+101 -425
View File
@@ -1,19 +1,18 @@
// Package main tests the offline recovery subcommands of archie-state-store:
// backup, restore, validate and rollback against the task database file
// directly. They are the operator's only path back when the control plane's
// stored settings will not validate, because the daemon fails closed: the
// in-band remedy (replay an earlier revision while the State Store is up) is
// unavailable in exactly the case that needs it.
// Package main tests the offline recovery subcommands of archie-state-store
// against the PostgreSQL database the configuration names. They are the
// operator's only path back when the control plane's stored settings will not
// validate, because the daemon fails closed: the in-band remedy (replay an
// earlier revision while the State Store is up) is unavailable in exactly the
// case that needs it.
//
// The tests drive the subcommands the way an operator does -- through
// runRecovery, against real files on disk -- rather than through the internal
// helpers, so the flag surface and the exit codes are part of what is verified.
// runRecovery -- rather than through the internal helpers, so the flag surface
// and the exit codes are part of what is verified.
package main
import (
"bytes"
"database/sql"
"encoding/json"
"fmt"
"os"
@@ -22,13 +21,14 @@ import (
"strings"
"testing"
_ "modernc.org/sqlite"
"github.com/samcharles93/archie-core/internal/app/archied"
"github.com/samcharles93/archie-core/internal/app/controlplane"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest"
"github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps"
"github.com/samcharles93/archie-core/internal/store"
)
// runRecoveryCmd runs one subcommand the way main does and returns its exit
@@ -40,240 +40,38 @@ func runRecoveryCmd(t *testing.T, args ...string) (int, string, string) {
return code, stdout.String(), stderr.String()
}
// openTaskStore opens the task database the subcommands operate on. It does not
// take the ownership lock: only the serving process does that, and a test that
// wants a "live" store holds it explicitly with holdStoreOwnership.
func openTaskStore(t *testing.T, path string) *store.Store {
// recoveryFixture writes a config naming a fresh migrated database and returns
// it with the task database on that database.
func recoveryFixture(t *testing.T) (string, *pgstore.TaskDB) {
t.Helper()
st, err := store.Open(t.Context(), path)
if err != nil {
t.Fatalf("open task store %s: %v", path, err)
}
t.Cleanup(func() { _ = st.Close() })
return st
url := pgtest.URL(t)
configPath := writeConfigFor(t, t.TempDir(), url)
return configPath, pgstore.On(pgstore.PoolAt(t, url))
}
// holdStoreOwnership takes the ownership lock the running State Store holds for
// its whole life, so a test can prove a command refuses to touch a live store.
func holdStoreOwnership(t *testing.T, path string) {
t.Helper()
ownership, err := store.AcquireOwnership(path)
if err != nil {
t.Fatalf("acquire store ownership: %v", err)
}
t.Cleanup(func() { _ = ownership.Release() })
}
// seedTask writes one task so a snapshot can be distinguished from the live
// database by what it contains, not merely by its existence.
func seedTask(t *testing.T, st *store.Store, title string) {
// seedTask writes one task so the database holds more than its settings.
func seedTask(t *testing.T, st *pgstore.TaskDB, title string) {
t.Helper()
if _, err := st.EnqueueChatTask(t.Context(), "acme", "widget", title, "body", "implement", ""); err != nil {
t.Fatalf("seed task %q: %v", title, err)
}
}
func taskTitles(t *testing.T, path string) []string {
// execRaw runs one statement against the database the way an operator editing
// a broken store would, bypassing every check the store applies.
func execRaw(t *testing.T, st *pgstore.TaskDB, statement string) {
t.Helper()
st := openTaskStore(t, path)
tasks, err := st.Tasks(t.Context(), 100)
if err != nil {
t.Fatalf("list tasks in %s: %v", path, err)
}
titles := make([]string, 0, len(tasks))
for _, task := range tasks {
titles = append(titles, task.Title)
}
return titles
}
// backupPath is the snapshot every restore test restores from.
func backupPath(t *testing.T, dir string) string { return filepath.Join(dir, "snapshot.sqlite") }
// backup takes the snapshot the caller then restores, through the subcommand
// under test rather than through the store directly, so a broken backup fails
// the restore test too instead of silently passing an empty file.
func backup(t *testing.T, db, out string) {
t.Helper()
code, _, stderr := runRecoveryCmd(t, "backup", "-db", db, "-out", out)
if code != 0 {
t.Fatalf("backup exited %d: %s", code, stderr)
}
}
// The update installer cannot stop the process that runs it, so it backs the
// task database up while the State Store is serving. VACUUM INTO is safe
// against a live writer; a backup that insisted on an exclusively-owned file
// would break the one caller it has, and the update would refuse to start.
func TestRecoveryBackupSnapshotsAStoreItsStateStoreIsServing(t *testing.T) {
dir := t.TempDir()
db := filepath.Join(dir, "archie.db-tasks.sqlite")
out := backupPath(t, dir)
seedTask(t, openTaskStore(t, db), "before")
holdStoreOwnership(t, db)
if err := os.WriteFile(out, []byte("stale snapshot"), 0o600); err != nil {
if _, err := st.Pool.Exec(t.Context(), statement); err != nil {
t.Fatal(err)
}
code, stdout, stderr := runRecoveryCmd(t, "backup", "-db", db, "-out", out)
if code != 0 {
t.Fatalf("backup exited %d: %s", code, stderr)
}
if !strings.Contains(stdout, out) || !strings.Contains(stdout, db) {
t.Errorf("backup must report the database and the snapshot it wrote; stdout = %q", stdout)
}
// The stale file was replaced by a real snapshot, and the snapshot is a
// store a restore can put back: same rows, readable through the store.
if got := taskTitles(t, out); len(got) != 1 || got[0] != "before" {
t.Fatalf("snapshot tasks = %v, want the one seeded task", got)
}
if entries, err := filepath.Glob(out + ".tmp*"); err != nil || len(entries) != 0 {
t.Errorf("backup left scratch files beside the snapshot: %v (%v)", entries, err)
}
}
// The snapshot is the rollback state, so an interrupted backup must never
// leave a truncated file where a good snapshot was.
func TestRecoveryBackupRefusesAMissingDatabase(t *testing.T) {
dir := t.TempDir()
code, _, stderr := runRecoveryCmd(t, "backup", "-db", filepath.Join(dir, "absent.sqlite"), "-out", backupPath(t, dir))
if code == 0 {
t.Fatal("backup of a missing database succeeded")
}
if !strings.Contains(stderr, "absent.sqlite") {
t.Errorf("refusal must name the database it could not read; stderr = %q", stderr)
}
}
// backup is the one recovery command allowed to run against a serving store,
// and that exemption is only sound while it never replaces the database. With
// -out naming the database it renames the snapshot over the live file and
// leaves the WAL of the database it just unlinked -- the state the restore path
// refuses up front and the code elsewhere calls unrecoverable.
func TestRecoveryBackupRefusesTheDatabaseAsItsOwnSnapshot(t *testing.T) {
db := filepath.Join(t.TempDir(), "archie.db-tasks.sqlite")
st := openTaskStore(t, db)
seedTask(t, st, "live")
code, _, stderr := runRecoveryCmd(t, "backup", "-db", db, "-out", db)
if code == 0 {
t.Fatal("backup over the database itself succeeded")
}
if !strings.Contains(stderr, "is the database itself") {
t.Errorf("refusal must say the snapshot is the database; stderr = %q", stderr)
}
if got := taskTitles(t, db); len(got) != 1 || got[0] != "live" {
t.Fatalf("refused backup changed the database: tasks = %v", got)
}
}
// Restoring is the forward-migration escape hatch: the previous release
// reads this file, so it must be exactly the snapshot, with the WAL that
// belongs to the replaced database gone rather than replayed over it.
func TestRecoveryRestorePutsTheSnapshotBackAndDropsItsWAL(t *testing.T) {
dir := t.TempDir()
db := filepath.Join(dir, "archie.db-tasks.sqlite")
out := backupPath(t, dir)
st := openTaskStore(t, db)
seedTask(t, st, "before")
backup(t, db, out)
seedTask(t, st, "after")
code, stdout, stderr := runRecoveryCmd(t, "restore", "-db", db, "-from", out)
if code != 0 {
t.Fatalf("restore exited %d: %s", code, stderr)
}
if !strings.Contains(stdout, out) {
t.Errorf("restore must report the snapshot it restored from; stdout = %q", stdout)
}
// Checked before anything reopens the database: opening a store sets WAL
// mode, which creates these files, so the point is that the restore did not
// leave the replaced database's log behind -- not that a later reader
// cannot recreate its own.
for _, suffix := range []string{"-wal", "-shm"} {
if _, err := os.Stat(db + suffix); err == nil {
t.Errorf("%s survived the restore: the replaced database's write-ahead log must not be replayed over the snapshot", db+suffix)
}
}
if got := taskTitles(t, db); len(got) != 1 || got[0] != "before" {
t.Fatalf("restored tasks = %v, want only the snapshot's task", got)
}
}
// Overwriting a database a running State Store still owns leaves that process
// writing to an unlinked inode while the store serves a file nobody owns --
// the one way an offline command can destroy a task store.
func TestRecoveryRestoreRefusesAStoreTheStateStoreIsRunning(t *testing.T) {
dir := t.TempDir()
db := filepath.Join(dir, "archie.db-tasks.sqlite")
out := backupPath(t, dir)
st := openTaskStore(t, db)
seedTask(t, st, "before")
backup(t, db, out)
seedTask(t, st, "after")
holdStoreOwnership(t, db)
code, _, stderr := runRecoveryCmd(t, "restore", "-db", db, "-from", out)
if code == 0 {
t.Fatal("restore against a live State Store succeeded")
}
if !strings.Contains(stderr, "owned by another process") {
t.Errorf("refusal must say the database is owned by another process; stderr = %q", stderr)
}
if got := taskTitles(t, db); len(got) != 2 {
t.Fatalf("refused restore changed the database: tasks = %v", got)
}
}
func TestRecoveryRestoreRefusesAFileThatIsNotAStore(t *testing.T) {
dir := t.TempDir()
db := filepath.Join(dir, "archie.db-tasks.sqlite")
seedTask(t, openTaskStore(t, db), "live")
notAStore := filepath.Join(dir, "notes.txt")
if err := os.WriteFile(notAStore, []byte("this is not a database"), 0o600); err != nil {
t.Fatal(err)
}
code, _, stderr := runRecoveryCmd(t, "restore", "-db", db, "-from", notAStore)
if code == 0 {
t.Fatal("restore from a file that is not a store succeeded")
}
if !strings.Contains(stderr, notAStore) {
t.Errorf("refusal must name the snapshot it could not read; stderr = %q", stderr)
}
if got := taskTitles(t, db); len(got) != 1 {
t.Fatalf("refused restore changed the database: tasks = %v", got)
}
}
func TestRecoveryRestoreRefusesTheDatabaseAsItsOwnSnapshot(t *testing.T) {
// Restoring a database from itself would delete the write-ahead log of the
// file it is about to copy, so the one case that must never reach the swap
// is refused up front.
db := filepath.Join(t.TempDir(), "archie.db-tasks.sqlite")
seedTask(t, openTaskStore(t, db), "live")
code, _, stderr := runRecoveryCmd(t, "restore", "-db", db, "-from", db)
if code == 0 {
t.Fatal("restore from the database itself succeeded")
}
if !strings.Contains(stderr, "is the database itself") {
t.Errorf("refusal must say the snapshot is the database; stderr = %q", stderr)
}
if got := taskTitles(t, db); len(got) != 1 {
t.Fatalf("refused restore changed the database: tasks = %v", got)
}
}
func TestRecoveryValidateAcceptsAHealthyStore(t *testing.T) {
dir := t.TempDir()
configPath := writeMinimalConfig(t, dir)
db := filepath.Join(dir, "archie.db-tasks.sqlite")
st := openTaskStore(t, db)
configPath, st := recoveryFixture(t)
seedTask(t, st, "healthy")
seedStoreResources(t, st, configPath)
code, stdout, stderr := runRecoveryCmd(t, "validate", "-db", db, "-config", configPath)
code, stdout, stderr := runRecoveryCmd(t, "validate", "-config", configPath)
if code != 0 {
t.Fatalf("validate exited %d: %s", code, stderr)
}
@@ -293,63 +91,54 @@ func TestRecoveryValidateAcceptsAHealthyStore(t *testing.T) {
// path's own per-resource decode, and the two disagree: the write path accepts
// a scheduling policy boot rejects.
func TestRecoveryValidateRunsTheGateBootRuns(t *testing.T) {
dir := t.TempDir()
configPath := writeMinimalConfig(t, dir)
db := filepath.Join(dir, "archie.db-tasks.sqlite")
seedStoreResources(t, openTaskStore(t, db), configPath)
configPath, st := recoveryFixture(t)
seedStoreResources(t, st, configPath)
// The control: a store seeded from this config is one the daemon boots on.
code, _, stderr := runRecoveryCmd(t, "validate", "-db", db, "-config", configPath)
code, _, stderr := runRecoveryCmd(t, "validate", "-config", configPath)
if code != 0 {
t.Fatalf("validate exited %d on a store the daemon starts on: %s", code, stderr)
}
// The upgrade case: a release defines a kind the store does not hold yet,
// and validate runs before the State Store has started again. The State
// Store seeds the kind it is missing, so the store is not the reason the
// daemon would refuse to start.
execRaw(t, st, `DELETE FROM resources WHERE kind='provider-settings'`)
code, stdout, stderr := runRecoveryCmd(t, "validate", "-config", configPath)
if code != 0 {
t.Fatalf("validate refused a store missing a kind the State Store seeds; stderr = %q", stderr)
}
if count := storedResourceCount(t, stdout); count == 0 {
t.Errorf("validate must still check the kinds the store does hold; stdout = %q", stdout)
}
// A hand-edited value, or an older revision of one: the write path's own
// validator never inspects dispatch.trigger, so only the config gate
// catches it, and the daemon exits 1 on it (validateDispatch).
if err := execRaw(t, db, `UPDATE resources SET value='{"poll_interval":"1m","max_retries":3,"dispatch":{"trigger":"bogus"}}' WHERE kind='scheduling-policy'`); err != nil {
t.Fatal(err)
}
code, stdout, stderr := runRecoveryCmd(t, "validate", "-db", db, "-config", configPath)
execRaw(t, st, `UPDATE resources SET value='{"poll_interval":"1m","max_retries":3,"dispatch":{"trigger":"bogus"}}' WHERE kind='scheduling-policy'`)
code, stdout, stderr = runRecoveryCmd(t, "validate", "-config", configPath)
if code == 0 {
t.Fatalf("validate accepted a stored policy the daemon refuses to boot with; stdout = %q", stdout)
}
if !strings.Contains(stderr, "dispatch.trigger") {
t.Errorf("refusal must name what boot rejects; stderr = %q", stderr)
}
}
// A store the State Store never seeded holds no kinds at all. Its next start
// creates the resources table and seeds every kind from this same config
// (internal/app/archied/state_store.go), so archied layers those seeds and
// starts: refusing the file here would send an operator to restore a
// snapshot for a store the daemon boots on perfectly well.
unseeded := filepath.Join(dir, "unseeded.db-tasks.sqlite")
openTaskStore(t, unseeded)
code, stdout, stderr = runRecoveryCmd(t, "validate", "-db", unseeded, "-config", configPath)
// A database the State Store never seeded holds no kinds at all. Its next
// start seeds every kind from this same config, so archied layers those seeds
// and starts: refusing it would send an operator to restore a snapshot for a
// database the daemon boots on perfectly well.
func TestRecoveryValidateAcceptsAnUnseededDatabase(t *testing.T) {
configPath, _ := recoveryFixture(t)
code, stdout, stderr := runRecoveryCmd(t, "validate", "-config", configPath)
if code != 0 {
t.Fatalf("validate refused a store the State Store would seed on its next start; stderr = %q", stderr)
}
if !strings.Contains(stdout, "0 stored resources validate") {
t.Errorf("validate must report that there was nothing stored to check; stdout = %q", stdout)
}
// The upgrade case: a release defines a kind the store does not hold yet,
// and validate runs before the State Store has started again. The State
// Store seeds the kind it is missing, so this is the same stance as the
// store with nothing stored at all -- the file is not the reason the daemon
// would refuse to start, and saying otherwise costs the operator a snapshot.
partial := filepath.Join(dir, "partial.db-tasks.sqlite")
seedStoreResources(t, openTaskStore(t, partial), configPath)
if err := execRaw(t, partial, `DELETE FROM resources WHERE kind='provider-settings'`); err != nil {
t.Fatal(err)
}
code, stdout, stderr = runRecoveryCmd(t, "validate", "-db", partial, "-config", configPath)
if code != 0 {
t.Fatalf("validate refused a store missing a kind the State Store seeds; stderr = %q", stderr)
}
if count := storedResourceCount(t, stdout); count == 0 {
t.Errorf("validate must still check the kinds the store does hold; stdout = %q", stdout)
}
}
// The subcommands advertise -h as the way to read their flags, and the serve
@@ -372,10 +161,7 @@ func TestRecoveryHelpExitsZero(t *testing.T) {
func TestRecoveryValidateLeavesTheDaemonLogAlone(t *testing.T) {
dir := t.TempDir()
configPath, logFile := writeConfigWithLogFile(t, dir)
db := filepath.Join(dir, "archie.db-tasks.sqlite")
seedStoreResources(t, openTaskStore(t, db), configPath)
code, _, stderr := runRecoveryCmd(t, "validate", "-db", db, "-config", configPath)
code, _, stderr := runRecoveryCmd(t, "validate", "-config", configPath)
if code != 0 {
t.Fatalf("validate exited %d: %s", code, stderr)
}
@@ -419,11 +205,10 @@ func TestRecoveryDefaultConfigResolvesWhereTheDaemonReads(t *testing.T) {
if err := os.MkdirAll(configDir, 0o700); err != nil {
t.Fatalf("create %s: %v", configDir, err)
}
configPath := writeMinimalConfig(t, configDir)
db := filepath.Join(root, "archie.db-tasks.sqlite")
seedStoreResources(t, openTaskStore(t, db), configPath)
code, stdout, stderr := runRecoveryCmd(t, "validate", "-db", db)
url := pgtest.URL(t)
pgstore.PoolAt(t, url)
configPath := writeConfigFor(t, configDir, url)
code, stdout, stderr := runRecoveryCmd(t, "validate")
if !tc.wantOK {
if code == 0 {
t.Fatalf("validate exited 0 with no config at the resolved path %s: %s", configPath, stdout)
@@ -434,125 +219,28 @@ func TestRecoveryDefaultConfigResolvesWhereTheDaemonReads(t *testing.T) {
t.Fatalf("validate with no -config exited %d, so it did not read %s: %s", code, configPath, stderr)
}
if !strings.Contains(stdout, "stored resources validate") {
t.Errorf("validate reported %q, want the verdict on the store seeded from the resolved config", stdout)
t.Errorf("validate reported %q, want the verdict on the database the resolved config names", stdout)
}
})
}
}
// validate exists to answer "would archied start against this file". Each case
// below is a state the daemon fails closed on, or a file it cannot read at all.
// validate exists to answer "would archied start against this database". A
// stored value that both gates refuse -- the write path stops it at Decode
// (workflow.ExecutionSettings.Validate rejects a negative limit) and boot stops
// on it too -- can only get here by bypassing the write path, which is exactly
// the state the operator has no path back from.
func TestRecoveryValidateRefusesWhatTheDaemonRefuses(t *testing.T) {
newStore := func(t *testing.T) string {
t.Helper()
db := filepath.Join(t.TempDir(), "archie.db-tasks.sqlite")
openTaskStore(t, db)
return db
configPath, st := recoveryFixture(t)
seedResource(t, st, controlplane.WorkflowExecutionSettingsKind,
`{"max_model_tool_steps":-1,"max_runtime_seconds":60,"max_consecutive_gate_failures":3}`, "hand-edited")
code, _, stderr := runRecoveryCmd(t, "validate", "-config", configPath)
if code == 0 {
t.Fatal("validate accepted a stored resource the write path would refuse")
}
if !strings.Contains(stderr, controlplane.WorkflowExecutionSettingsKind) {
t.Errorf("refusal must name the resource kind; stderr = %q", stderr)
}
t.Run("forward_migrated_schema", func(t *testing.T) {
// A database written by a newer release is the state a rollback has to
// recognise before it hands the file to an older binary.
db := newStore(t)
if err := execRaw(t, db, `PRAGMA user_version = 99`); err != nil {
t.Fatal(err)
}
code, _, stderr := runRecoveryCmd(t, "validate", "-db", db)
if code == 0 {
t.Fatal("validate accepted a forward-migrated database")
}
if !strings.Contains(stderr, "newer than supported version") {
t.Errorf("refusal must name the schema version; stderr = %q", stderr)
}
})
t.Run("corrupt_file", func(t *testing.T) {
// A real database header over pages that are not a database. The magic
// is right, so this fails on the content rather than on the format, which
// is the shape a half-written or truncated store has.
db := filepath.Join(t.TempDir(), "archie.db-tasks.sqlite")
corrupt := append([]byte("SQLite format 3\x00"), bytes.Repeat([]byte{0xff}, 4096)...)
if err := os.WriteFile(db, corrupt, 0o600); err != nil {
t.Fatal(err)
}
code, _, stderr := runRecoveryCmd(t, "validate", "-db", db)
if code == 0 {
t.Fatal("validate accepted a corrupt database")
}
if !strings.Contains(stderr, db) {
t.Errorf("refusal must name the file; stderr = %q", stderr)
}
})
t.Run("not_a_database", func(t *testing.T) {
// Pointing -db at the wrong file is the common operator mistake, and the
// configured db_path is a different file from the task database the
// State Store owns.
db := filepath.Join(t.TempDir(), "archie.db")
if err := os.WriteFile(db, []byte("db_path, not the task database"), 0o600); err != nil {
t.Fatal(err)
}
code, _, stderr := runRecoveryCmd(t, "validate", "-db", db)
if code == 0 {
t.Fatal("validate accepted a file that is not a database")
}
if !strings.Contains(stderr, db) {
t.Errorf("refusal must name the file; stderr = %q", stderr)
}
})
t.Run("stored_resource_that_will_not_validate", func(t *testing.T) {
// A stored value that both gates refuse: the write path stops it at
// Decode (workflow.ExecutionSettings.Validate rejects a negative limit),
// and boot stops on it too -- startWorkflowExecutionSettings decodes the
// same document and exits 1. It can only get here by bypassing the write
// path, which is exactly the state the operator has no path back from.
db := newStore(t)
seedResource(t, openTaskStore(t, db), controlplane.WorkflowExecutionSettingsKind,
`{"max_model_tool_steps":-1,"max_runtime_seconds":60,"max_consecutive_gate_failures":3}`, "hand-edited")
code, _, stderr := runRecoveryCmd(t, "validate", "-db", db)
if code == 0 {
t.Fatal("validate accepted a stored resource the write path would refuse")
}
if !strings.Contains(stderr, controlplane.WorkflowExecutionSettingsKind) {
t.Errorf("refusal must name the resource kind; stderr = %q", stderr)
}
})
t.Run("missing_database", func(t *testing.T) {
db := newStore(t)
if err := os.Remove(db); err != nil {
t.Fatal(err)
}
code, _, stderr := runRecoveryCmd(t, "validate", "-db", db)
if code == 0 {
t.Fatal("validate accepted a database that does not exist")
}
if !strings.Contains(stderr, db) {
t.Errorf("refusal must name the file; stderr = %q", stderr)
}
})
t.Run("store_without_the_control_plane_table", func(t *testing.T) {
// A store written before the control plane existed holds no stored
// settings. The serving process creates the table on its next start, so
// refusing this file would send an operator to restore a snapshot for a
// database that would have started perfectly well.
dir := t.TempDir()
configPath := writeMinimalConfig(t, dir)
db := filepath.Join(dir, "archie.db-tasks.sqlite")
openTaskStore(t, db)
if err := execRaw(t, db, `DROP TABLE resources`); err != nil {
t.Fatal(err)
}
code, stdout, stderr := runRecoveryCmd(t, "validate", "-db", db, "-config", configPath)
if code != 0 {
t.Fatalf("validate exited %d: %s", code, stderr)
}
if !strings.Contains(stdout, "0 stored resources validate") {
t.Errorf("validate must report that there was nothing stored to check; stdout = %q", stdout)
}
})
}
// rollback is the one operation that closes the documented gap: with the State
@@ -560,13 +248,11 @@ func TestRecoveryValidateRefusesWhatTheDaemonRefuses(t *testing.T) {
// ordinary replace, so no rollback RPC is needed and the rollback itself is
// audited as one more revision.
func TestRecoveryRollbackReplaysTheRevisionThroughReplace(t *testing.T) {
dir := t.TempDir()
db := filepath.Join(dir, "archie.db-tasks.sqlite")
st := openTaskStore(t, db)
configPath, st := recoveryFixture(t)
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"anthropic/claude"}`, "first")
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"openai/gpt"}`, "second")
code, stdout, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", controlplane.ModelRoleAssignmentsKind)
code, stdout, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind)
if code != 0 {
t.Fatalf("rollback exited %d: %s", code, stderr)
}
@@ -598,14 +284,12 @@ func TestRecoveryRollbackReplaysTheRevisionThroughReplace(t *testing.T) {
// The revision to restore may be named, which is how an operator reaches past
// the most recent change without replaying it first.
func TestRecoveryRollbackRestoresANamedRevision(t *testing.T) {
dir := t.TempDir()
db := filepath.Join(dir, "archie.db-tasks.sqlite")
st := openTaskStore(t, db)
configPath, st := recoveryFixture(t)
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"anthropic/claude"}`, "first")
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"openai/gpt"}`, "second")
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"google/gemini"}`, "third")
code, _, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", controlplane.ModelRoleAssignmentsKind, "-revision", "1")
code, _, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind, "-revision", "1")
if code != 0 {
t.Fatalf("rollback exited %d: %s", code, stderr)
}
@@ -619,10 +303,9 @@ func TestRecoveryRollbackRestoresANamedRevision(t *testing.T) {
}
func TestRecoveryRollbackRefusesWhatItCannotReplay(t *testing.T) {
newStore := func(t *testing.T, revisions int) string {
newStore := func(t *testing.T, revisions int) (string, *pgstore.TaskDB) {
t.Helper()
db := filepath.Join(t.TempDir(), "archie.db-tasks.sqlite")
st := openTaskStore(t, db)
configPath, st := recoveryFixture(t)
for i := range revisions {
value := `{"implement":"anthropic/claude"}`
if i > 0 {
@@ -630,12 +313,12 @@ func TestRecoveryRollbackRefusesWhatItCannotReplay(t *testing.T) {
}
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, value, "seed")
}
return db
return configPath, st
}
t.Run("unknown_kind", func(t *testing.T) {
db := newStore(t, 2)
code, _, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", "not-a-resource")
configPath, _ := newStore(t, 2)
code, _, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", "not-a-resource")
if code == 0 {
t.Fatal("rollback of an unknown resource kind succeeded")
}
@@ -645,8 +328,8 @@ func TestRecoveryRollbackRefusesWhatItCannotReplay(t *testing.T) {
})
t.Run("no_earlier_revision", func(t *testing.T) {
db := newStore(t, 1)
code, _, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", controlplane.ModelRoleAssignmentsKind)
configPath, _ := newStore(t, 1)
code, _, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind)
if code == 0 {
t.Fatal("rollback with no earlier revision succeeded")
}
@@ -656,8 +339,8 @@ func TestRecoveryRollbackRefusesWhatItCannotReplay(t *testing.T) {
})
t.Run("current_revision", func(t *testing.T) {
db := newStore(t, 2)
code, _, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", controlplane.ModelRoleAssignmentsKind, "-revision", "2")
configPath, _ := newStore(t, 2)
code, _, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind, "-revision", "2")
if code == 0 {
t.Fatal("rollback of the current revision succeeded")
}
@@ -667,14 +350,18 @@ func TestRecoveryRollbackRefusesWhatItCannotReplay(t *testing.T) {
})
t.Run("live_state_store", func(t *testing.T) {
db := newStore(t, 2)
holdStoreOwnership(t, db)
code, _, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", controlplane.ModelRoleAssignmentsKind)
configPath, st := newStore(t, 2)
claim, err := postgres.AcquireOwnership(t.Context(), st.Pool, postgres.OwnerStateStore)
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = claim.Release(t.Context()) })
code, _, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind)
if code == 0 {
t.Fatal("rollback against a live State Store succeeded")
}
if !strings.Contains(stderr, "owned by another process") {
t.Errorf("refusal must say the database is owned by another process; stderr = %q", stderr)
if !strings.Contains(stderr, "stop the State Store") {
t.Errorf("refusal must say to stop the State Store; stderr = %q", stderr)
}
})
}
@@ -683,7 +370,7 @@ func TestRecoveryRollbackRefusesWhatItCannotReplay(t *testing.T) {
// an operator who mistyped a command watching a server start instead.
func TestRecoveryRejectsAnUnknownSubcommand(t *testing.T) {
var stdout, stderr bytes.Buffer
code := runRecovery([]string{"backp", "-db", "x"}, &stdout, &stderr)
code := runRecovery([]string{"backp", "-out", "x"}, &stdout, &stderr)
if code == 0 {
t.Fatal("an unknown subcommand exited 0")
}
@@ -696,7 +383,9 @@ func TestRecoveryRejectsAnUnknownSubcommand(t *testing.T) {
// destination, which only the daemon may bring into existence.
func writeConfigWithLogFile(t *testing.T, dir string) (string, string) {
t.Helper()
configPath := writeMinimalConfig(t, dir)
url := pgtest.URL(t)
pgstore.PoolAt(t, url)
configPath := writeConfigFor(t, dir, url)
logFile := filepath.Join(dir, "logs", "archied.log")
f, err := os.OpenFile(configPath, os.O_APPEND|os.O_WRONLY, 0o600)
if err != nil {
@@ -725,7 +414,7 @@ func writeConfigWithLogFile(t *testing.T, dir string) (string, string) {
// registers the same set itself rather than an empty manager: the definitions
// are decoded with the vocabulary the served path validates against, which is
// what makes the seeded values the ones validate is asked about.
func seedStoreResources(t *testing.T, st *store.Store, configPath string) {
func seedStoreResources(t *testing.T, st *pgstore.TaskDB, configPath string) {
t.Helper()
doc, err := configuration.New(nil).Resolve(configPath, "")
if err != nil {
@@ -772,7 +461,7 @@ func storedResourceCount(t *testing.T, stdout string) int {
// from the label and the revision it produces: the store deduplicates a
// repeated request ID, so a fixed one would make the second write of a series
// a silent no-op.
func seedResource(t *testing.T, st *store.Store, kind, value, label string) {
func seedResource(t *testing.T, st *pgstore.TaskDB, kind, value, label string) {
t.Helper()
current, err := st.Resource(t.Context(), kind)
expected := int64(0)
@@ -787,23 +476,10 @@ func seedResource(t *testing.T, st *store.Store, kind, value, label string) {
if err != nil {
t.Fatal(err)
}
if _, err := st.PutResource(t.Context(), store.ResourceWrite{
if _, err := st.PutResource(t.Context(), storecontract.ResourceWrite{
Kind: kind, Value: encoded, Actor: label, Source: "test",
RequestID: fmt.Sprintf("%s-%d", label, expected+1), ExpectedVersion: expected,
}); err != nil {
t.Fatalf("seed resource %s: %v", kind, err)
}
}
// execRaw runs one statement against the database file the way an operator
// editing a broken store would, bypassing every check the store applies.
func execRaw(t *testing.T, path, statement string) error {
t.Helper()
db, err := sql.Open("sqlite", path)
if err != nil {
return err
}
defer func() { _ = db.Close() }()
_, err = db.ExecContext(t.Context(), statement)
return err
}
+3 -2
View File
@@ -1,6 +1,6 @@
// This file enforces the objective half of the UI Service deletion gate
// (docs/prds/ui-service-boundary.md, "The deletion gate is objective"). The
// composition half -- no config.Holder, no concrete *store.Store, no Gateway
// composition half -- no config.Holder, no concrete task store, no Gateway
// runtime type -- is pinned by internal/app/archieui's
// TestComposeUIServerHoldsNoDaemonState. This pins the claim that test cannot
// see: that the linked binary carries no daemon runtime at all. Go imports
@@ -28,7 +28,8 @@ type bannedCategory struct {
var deletionGate = []bannedCategory{
{"SQL/store implementation", []string{
"modernc.org/sqlite",
modulePath + "internal/store",
"github.com/jackc/pgx",
modulePath + "internal/infrastructure/postgres",
}},
{"daemon runtime", []string{
modulePath + "internal/daemon",
+11 -18
View File
@@ -36,11 +36,11 @@ import (
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/domain/health"
"github.com/samcharles93/archie-core/internal/domain/messaging"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
"github.com/samcharles93/archie-core/internal/domain/taskactions"
"github.com/samcharles93/archie-core/internal/infrastructure/edastore"
"github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore"
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
"github.com/samcharles93/archie-core/internal/store"
"github.com/samcharles93/archie-core/internal/taskstate"
"github.com/samcharles93/archie-core/internal/webui"
)
@@ -224,7 +224,6 @@ func writeUIConfig(t *testing.T, dir, stateTarget, gatewayTarget string) string
t.Helper()
path := filepath.Join(dir, "config.toml")
content := fmt.Sprintf(`bot_user = "archie-bot"
db_path = %q
[forge]
type = "github"
host = "https://github.example.com"
@@ -236,7 +235,7 @@ name = "widget"
target = %q
[services.gateway]
target = %q
`, filepath.Join(dir, "archie.db"), stateTarget, gatewayTarget)
`, stateTarget, gatewayTarget)
if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
t.Fatalf("write ui config: %v", err)
}
@@ -484,12 +483,9 @@ func streamChat(t *testing.T, d dashboard, prompt string) []chatFrame {
// that forgets to publish a field, which is the failure mode this covers:
// chat.show_tool_calls, the operator name and the channel flag all reach the
// extracted process through this projection and nowhere else (GitHub #821).
func seedStore(t *testing.T, dir string) *store.Store {
func seedStore(t *testing.T, dir string) *pgstore.TaskDB {
t.Helper()
st, err := store.Open(t.Context(), filepath.Join(dir, "tasks.sqlite"))
if err != nil {
t.Fatalf("open store: %v", err)
}
st := pgstore.Open(t)
t.Cleanup(func() { _ = st.Close() })
if _, err := st.EnqueueIssue(t.Context(), "acme", "widget", 7, "smoke task", "body", "", ""); err != nil {
@@ -528,13 +524,13 @@ func daemonConfig(showToolCalls bool) config.Config {
// writes the result to the store the UI process reads it back from. The UI
// process holds no configuration, so this is the only path by which a setting
// reaches its pages.
func publishConfig(t *testing.T, st *store.Store, cfg config.Config) {
func publishConfig(t *testing.T, st *pgstore.TaskDB, cfg config.Config) {
t.Helper()
document, err := json.Marshal(webui.BuildConfigView(webui.ConfigViewInput{Config: cfg}))
if err != nil {
t.Fatalf("render the configuration projection: %v", err)
}
if err := st.PutConfigSnapshot(t.Context(), store.ConfigSnapshot{
if err := st.PutConfigSnapshot(t.Context(), storecontract.ConfigSnapshot{
Schema: webui.ConfigViewSchema, Document: document,
}); err != nil {
t.Fatalf("publish config snapshot: %v", err)
@@ -555,10 +551,7 @@ func publishConfig(t *testing.T, st *store.Store, cfg config.Config) {
// that test's page underneath it.
func TestUIProcessLinksMultiIdentityTaskRowsToTheirOwningForge(t *testing.T) {
dir := t.TempDir()
st, err := store.Open(t.Context(), filepath.Join(dir, "tasks.sqlite"))
if err != nil {
t.Fatalf("open store: %v", err)
}
st := pgstore.Open(t)
t.Cleanup(func() { _ = st.Close() })
// One task carrying its identity (name resolves it), one without an
@@ -595,14 +588,14 @@ func TestUIProcessLinksMultiIdentityTaskRowsToTheirOwningForge(t *testing.T) {
if err != nil {
t.Fatal(err)
}
if err := st.PutConfigSnapshot(t.Context(), store.ConfigSnapshot{
if err := st.PutConfigSnapshot(t.Context(), storecontract.ConfigSnapshot{
Schema: webui.ConfigViewSchema, Document: published,
}); err != nil {
t.Fatalf("publish config snapshot: %v", err)
}
stateTarget, stopState := serveGRPC(t, func(r grpc.ServiceRegistrar) {
eda := edastore.OpenTest(t)
eda := pgstore.EDA(t, nil)
staterpc.RegisterServer(r, staterpc.Deps{
Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st,
Log: slog.New(slog.DiscardHandler),
@@ -659,7 +652,7 @@ func TestUIProcessServesTheDashboardAgainstLiveDependencies(t *testing.T) {
gateway := &fakeGateway{}
stateTarget, stopState := serveGRPC(t, func(r grpc.ServiceRegistrar) {
eda := edastore.OpenTest(t)
eda := pgstore.EDA(t, nil)
staterpc.RegisterServer(r, staterpc.Deps{
Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st,
Log: slog.New(slog.DiscardHandler),
+10
View File
@@ -0,0 +1,10 @@
package main
import (
"os"
"testing"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest"
)
func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) }
+30 -31
View File
@@ -13,7 +13,13 @@
# secret_engine_dir = "~/.config/archie/secret-engines"
# work_dir = "~/.local/share/archie/work" # default
# db_path = "~/.local/share/archie/archie.db" # prefix for independent task and conversation SQLite files
# state_dir = "~/.local/share/archie" # default; embedded NATS store, task logs, disk probe
# The PostgreSQL connection archie-state-store, archied and archie-gateway
# serve from. Required: each fails closed without it.
# `docker compose up -d postgres` starts a matching local postgres:18 with this
# default URL.
# database_url = "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable"
# skills_dir = "~/.local/share/archie/skills" # SKILL.md search path; defaults under work_dir when unset
# plugin_dir = "~/.local/share/archie/plugins" # daemon plugin manifests; unset means no plugins are loaded
@@ -158,10 +164,8 @@ class = "ollama"
# shell snippets). The check command must write a releaseupdate.Snapshot JSON
# document to stdout; configure the installer as well to show Approve/Defer.
# [chat.telegram]
# Preferred: resolve the bot token through a configured secret engine.
# The bot token from @BotFather, resolved through a configured secret engine.
# token = { engine = "bws", key = "TELEGRAM_BOT_TOKEN" }
# Legacy compatibility: read the token from this environment variable.
# token_env = "TELEGRAM_BOT_TOKEN" # env var holding the bot token from @BotFather
# Run by archie-messaging, which serves /update, so these commands execute on
# whichever host runs that process.
# update_check_command = ["/usr/local/bin/archie-update-check"]
@@ -228,12 +232,11 @@ class = "ollama"
# parallel_tool_calls = false
# Publish artifacts (review reports, design docs) to the collaborative editor.
# An empty base_url disables publishing entirely. The token is runtime config:
# set WORKSPACE_INGEST_TOKEN in the daemon's environment or use a secret ref.
# An empty base_url disables publishing entirely. token defaults to the
# WORKSPACE_INGEST_TOKEN environment variable.
[artifacts]
# base_url = "https://offloaded.dev"
# token = { engine = "env", key = "WORKSPACE_INGEST_TOKEN" }
# token_env = "WORKSPACE_INGEST_TOKEN"
# archied's own liveness surface, always on. GET /healthz and /health answer
# 200 once the daemon is serving (503 while it is still booting), and
@@ -296,23 +299,6 @@ listen = "127.0.0.1:8484"
# [memory]
# engine = "builtin" # "builtin" is the only engine implemented so far
# Image generation capability (internal/domain/image). No provider is
# implemented yet -- this section defines the contract/config surface only
# (archie-core-1786748942147-2-47cd5bd1). Absent is valid and registers no
# provider. default names the provider /image uses without asking; leaving
# it unset means /image always asks which mechanism to use. Every provider
# is off by default -- a hosted provider spends real API credits per call,
# and a local one can saturate the host GPU, so both require an explicit
# enabled = true, never an inferred one from the presence of a key alone.
# [image.hosted.openai]
# enabled = false
# class = "openai"
# api_key_env = "OPENAI_API_KEY"
#
# [image.local.sdxl]
# enabled = false
# backend = "sdxl-turbo"
# Notifications for human-in-the-loop moments
# (approval requests, gate failures, parked tasks).
# Archie POSTs a JSON payload to the webhook
@@ -322,8 +308,9 @@ listen = "127.0.0.1:8484"
[budgets]
max_steps = 60
wall_clock = "30m"
wall_clock = "30m" # one agent call
gate_max_failures = 5
task_wall_clock = "4h" # a whole task run; keep containers.max_uptime at or above it
# Services selects contract adapters at composition time (see
# docs/prds/state-store-contract.md).
@@ -342,9 +329,9 @@ target = "127.0.0.1:8585" # archie-gateway's gRPC address (always remot
[services.state]
target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address archied and
# # archie-gateway dial. They no longer own archie.db
# # archie-gateway dial. They own no task data
# # in-process: the standalone archie-state-store process
# # owns the single SQLite file (docs/prds/state-store-contract.md
# # owns it in PostgreSQL (docs/prds/state-store-contract.md
# # §10/§12 step 7). An empty target is a startup error.
# listen = "127.0.0.1:9090" # The address archie-state-store BINDS. Read only by that
# # process; every client ignores it. Defaults to the target
@@ -372,10 +359,9 @@ target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address arch
# Unbound webhook capture: POST /webhooks/capture/{source} accepts and
# stores any inbound payload archie doesn't yet have a binding for, so it can
# be inspected and mapped later (see docs/prds/event-capture-storage.md).
# Stored in the same SQLite database as tasks, not NATS -- capture has one
# Stored in the same PostgreSQL database as tasks, not NATS -- capture has one
# writer and one (human, dashboard) reader, so it doesn't need JetStream's
# fan-out/replay machinery, and SQLite is available in every deployment
# shape unconditionally. All fields default when the section is absent;
# fan-out/replay machinery. All fields default when the section is absent;
# capture is on by default.
#
# From the UI cutover (archie-core-8cda.5.4) the receiver is mounted by the
@@ -428,7 +414,7 @@ target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address arch
# Playbook-binding at-rest encryption: [bindings].encryption_key resolves a
# 32-byte high-entropy key through the secret registry (engine + key) and seals
# each binding's HMAC secret in the SQLite bindings.secret column with AES-256-
# each binding's HMAC secret in the bindings.secret column with AES-256-
# GCM (see docs/prds/binding-secret-encryption.md). When the key is absent,
# binding secrets are stored as plaintext (the pre-t2db.7 behaviour) -- enabling
# encryption does not retroactively encrypt existing rows, which stay plaintext
@@ -451,6 +437,19 @@ target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address arch
# max_uptime = "60m" # container lifetime cap
# volume_ttl = "72h" # max age for persistent repo volumes and Git clone caches
# pull_policy = "missing" # "missing" or "always"
#
# Agent profiles a workflow selects with `profile: <name>`. A workflow that
# names none runs under [containers].image with every tool.
# Once the State Store holds container policies, edit profiles in the
# dashboard (Settings, Advanced); a stored set replaces the file's.
# [containers.profiles.network-investigator]
# image = "archie-agent-net:local" # docker compose build agent-net; empty uses [containers].image
# tools = [] # allowlist over MCP, script and plugin tools; empty allows all
# A Kit profile runs every agent stage on an external CLI packaged as a Kit v3
# image: the workload Kit, then mixins, each pinned by digest.
# [containers.profiles.claude]
# kit = ["docker/claude-code-kit@sha256:<digest>"]
# adapter = "claude-code" # claude-code, codex, pi, omp or copilot; empty runs without capture tools or usage
# At least one [[repos]] entry is required before archied will poll
# anything -- it is deliberately left commented rather than shipped active:
+2 -1
View File
@@ -125,7 +125,8 @@ func TestPullRequestsRunTheDefinitiveGateWithoutPublishAccess(t *testing.T) {
// Naming each one with its reason keeps an omission a decision rather than an
// oversight -- which is exactly how archied's channels were lost.
var unpackagedCommands = map[string]string{
"archie-agent": "runs only inside the Docker image build-and-push publishes, never as a host binary",
"archie-agent": "runs only inside the Docker image build-and-push publishes, never as a host binary",
"archie-prbench": "a developer benchmark run from the repository with task bench:prreview",
}
// cliOnlyCommands ship in the zip but must never be restarted by the updater:
+1 -23
View File
@@ -30,10 +30,6 @@ func TestExternalNATSProfileLoadsWithManagedWorkers(t *testing.T) {
if doc.Config.Containers.Image == "" {
t.Error("managed worker image is empty")
}
legacy := doc.Config.LegacyAgent
if legacy.Mode != "" || legacy.Command != "" || len(legacy.Env) != 0 {
t.Errorf("legacy agent selector decoded from supported profile: %#v", doc.Config.LegacyAgent)
}
}
func TestInstallerUsesNativeDaemonAndManagedWorkerImage(t *testing.T) {
@@ -77,10 +73,7 @@ func TestFormattingUsesOneConfiguredWriter(t *testing.T) {
}
fmtTask := taskfile[fmtStart:fmtEnd]
const (
applyFix = "go fix ./..."
verifyFix = "go fix -diff ./..."
)
const applyFix = "go fix ./..."
fix := strings.Index(fmtTask, applyFix)
format := strings.Index(fmtTask, "golangci-lint fmt")
if fix < 0 || format < 0 || fix > format {
@@ -89,21 +82,6 @@ func TestFormattingUsesOneConfiguredWriter(t *testing.T) {
if strings.Contains(fmtTask, "gofumpt -") {
t.Error("fmt task bypasses the configured formatter set with standalone gofumpt")
}
// One go fix pass is not a fixpoint: stditerators rewrites
// `for i := range t.NumField()` into a field iterator that copies its loop
// variable, and forvar only deletes that copy on the following pass. A tree
// that stops after one pass is therefore one copyloopvar rejects, so fmt has
// to keep applying passes and prove the plateau with a dry run that exits
// clean only when nothing is left to fix.
if !strings.Contains(fmtTask, verifyFix) {
t.Error("fmt task does not prove that repeated go fix passes have reached a fixpoint")
}
if got := strings.Count(fmtTask, applyFix); got != 1 {
t.Errorf("fmt task applies go fix %d times inline, want 1: the repetition belongs to the fixpoint loop", got)
}
if got := strings.Count(fmtTask, verifyFix); got != 1 {
t.Errorf("fmt task verifies the go fix fixpoint %d times, want 1", got)
}
if got, owned := strings.Count(taskfile, applyFix), strings.Count(fmtTask, applyFix); got != owned {
t.Errorf("Taskfile invokes go fix %d times, %d of them through task fmt: formatting has one owner", got, owned)
}
+1 -1
View File
@@ -18,7 +18,7 @@ This archive contains six linux/amd64 binaries:
this process they are simply absent — and nothing logs an error
(`archie-core-1c01`), which is why it has a unit of its own in
`deployments/systemd-user-service.md`.
- **`archie-state-store`** — owns the single `archie.db` SQLite file behind
- **`archie-state-store`** — owns the task data in PostgreSQL behind
a gRPC contract. `archied` and `archie-gateway` are gRPC clients of it, not
owners of the database.
- **`archie-playbooks`** — standalone CLI to lint playbook binding YAML
+14 -32
View File
@@ -4,19 +4,19 @@ This directory contains configuration templates and guides for different deploym
## Directory Structure
* **[`single-forge-github.toml`](./single-forge-github.toml)**:
- **[`single-forge-github.toml`](./single-forge-github.toml)**:
Standard single-forge deployment managing multiple GitHub repositories under a single bot account and GitHub token.
* **[`multi-forge-github-gitea.toml`](./multi-forge-github-gitea.toml)**:
- **[`multi-forge-github-gitea.toml`](./multi-forge-github-gitea.toml)**:
Multi-identity deployment running GitHub and a self-hosted Gitea instance simultaneously with distinct bot accounts, tokens, and repository sets.
* **[`local-ollama-standalone.toml`](./local-ollama-standalone.toml)**:
- **[`local-ollama-standalone.toml`](./local-ollama-standalone.toml)**:
Self-hosted deployment running local LLM models via Ollama (e.g., `llama3`, `qwen2.5`) with optional standalone (forge-disabled) operation.
* **[`docker-nats-stack.toml`](./docker-nats-stack.toml)**:
- **[`docker-nats-stack.toml`](./docker-nats-stack.toml)**:
Host-run `archied` orchestrating sandboxed `archie-agent` containers over the repository's Compose-managed NATS service. Copy to `~/.config/archie/config.toml`, start NATS with Compose, then start `archied` on the host.
* **[`systemd-user-service.md`](./systemd-user-service.md)**:
- **[`systemd-user-service.md`](./systemd-user-service.md)**:
Operational runbook for running `archied` as a persistent 24/7 background service via systemd user units and `loginctl enable-linger`.
---
@@ -43,13 +43,13 @@ systemctl --user start archied
```
The templates use the extracted Gateway Service by default. Start
`archie-gateway` before `archied`; it owns the conversation SQLite file and
`archie-gateway` before `archied`; it owns the conversation tables and
serves the `ChatContract` gRPC API on the configured target.
The State Store service (`archie-state-store`) owns the single `archie.db` task
SQLite file and serves the `StateStore` gRPC contract. After the in-process
store path was deleted, BOTH `archied` and `archie-gateway` dial it via
`[services.state].target` and never open `archie.db` themselves
The State Store service (`archie-state-store`) owns the task data in the
PostgreSQL database `database_url` names and serves the `StateStore` gRPC
contract. BOTH `archied` and `archie-gateway` dial it via
`[services.state].target` and never open the task tables themselves
(`docs/prds/state-store-contract.md` §12 step 7). The templates set
`[services.state]` accordingly: a host-only agent reaches a loopback bind
(`127.0.0.1:9090`) with no token, while a container-mode agent needs the
@@ -117,28 +117,10 @@ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9091/healthz #
curl -s http://127.0.0.1:9091/health/detailed # state_db component -> 200, or 503 when degraded
```
A running State Store owns exactly one task SQLite file (`<db_path>-tasks.sqlite`);
`archied` and `archie-gateway` never open `archie.db` directly, so a second
store process on the same `db_path`, or a consumer that opens the task file,
indicates dual-store ownership (`docs/prds/state-store-contract.md` §12 step 7/8).
A running State Store holds the `state-store` ownership lock on its database;
`archied` and `archie-gateway` never open the task tables directly, so a second
store process on the same `database_url` refuses to start, and a consumer that
opens the task tables indicates dual-store ownership (`docs/prds/state-store-contract.md` §12 step 7/8).
The readiness probe is the single-writer check the runbook has against a
degraded store: a `503` from `/health/detailed` means `archied` should be
started only after the store is healthy.
### Inspecting the store
`-admin-addr` starts a read-only operator dashboard on the same process, over
the file it already owns:
```bash
archie-state-store -admin-addr 127.0.0.1:8686 # dashboard on http://127.0.0.1:8686/_/
```
It co-tenants on `<db_path>-tasks.sqlite` rather than opening a second
database, so it does not disturb the single-writer rule above: it runs inside
the process that holds the ownership claim, and every archie table is exposed
as a read-only view collection. The routes that could write past those views
(`POST /api/sql`, `/api/backups`) are refused, so the gRPC contract stays the
only writer and `archie-state-store backup` stays the only snapshot path.
Leave the flag off and no dashboard listener is started.
+6
View File
@@ -8,6 +8,12 @@
# [web], [services.*] and [capture] land in archie-ui; the daemon ignores
# [web] entirely.
# `task dev` runs archie-state-store against this overlay, and the State Store
# fails closed without a PostgreSQL URL. This must reach the `postgres`
# service in docker-compose.yml, which `task dev` brings up first via
# dev:postgres -- keep the URL and that service in agreement.
database_url = "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable"
[web]
listen = "127.0.0.1:8484"
+8 -4
View File
@@ -15,13 +15,17 @@ poll_interval = "60s"
bot_user = "archie"
diff_cap_lines = 0
work_dir = "~/.local/share/archie/work"
db_path = "~/.local/share/archie/archie.db"
state_dir = "~/.local/share/archie" # NATS store, task logs
# The State Store's PostgreSQL connection (required; Postgres-only epic).
# `docker compose up -d postgres` provides this local default; point it at
# your own Postgres 18 server otherwise.
database_url = "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable"
[services.gateway]
target = "127.0.0.1:8585"
# The State Store gRPC service owns the single archie.db SQLite file; archied
# and archie-gateway dial it and never open archie.db themselves (§12 step 7).
# The State Store gRPC service owns the PostgreSQL task data; archied and
# archie-gateway dial it and never open those tables themselves (§12 step 7).
# This deployment runs the agent in containers, so target is the Docker bridge
# gateway (172.17.0.1) the container can reach, with a matching target_token
# that archie-state-store validates. Host-only agent: use 127.0.0.1:9090 with
@@ -118,6 +122,6 @@ gate = [
# Every env var named here must be present in the environment of the host
# archied process, normally through its configured supervisor or launch shell.
[chat.telegram]
token_env = "TELEGRAM_BOT_TOKEN"
token = { engine = "env", key = "TELEGRAM_BOT_TOKEN" }
# Empty list denies everyone.
allowed_user_ids = []
+7 -3
View File
@@ -6,13 +6,17 @@
# ==============================================================================
work_dir = "~/.local/share/archie/work"
db_path = "~/.local/share/archie/archie.db"
state_dir = "~/.local/share/archie" # NATS store, task logs
# The State Store's PostgreSQL connection (required; Postgres-only epic).
# `docker compose up -d postgres` provides this local default; point it at
# your own Postgres 18 server otherwise.
database_url = "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable"
[services.gateway]
target = "127.0.0.1:8585"
# The State Store gRPC service owns the single archie.db SQLite file; archied
# and archie-gateway dial it and never open archie.db themselves (§12 step 7).
# The State Store gRPC service owns the PostgreSQL task data; archied and
# archie-gateway dial it and never open those tables themselves (§12 step 7).
# Host-only deployment: the agent runs on the host, so the loopback target
# 127.0.0.1:9090 needs no token. Start archie-state-store with the matching
# `-listen 127.0.0.1:9090`.
+10 -6
View File
@@ -7,13 +7,17 @@
# ==============================================================================
work_dir = "~/.local/share/archie/work"
db_path = "~/.local/share/archie/archie.db"
state_dir = "~/.local/share/archie" # NATS store, task logs
# The State Store's PostgreSQL connection (required; Postgres-only epic).
# `docker compose up -d postgres` provides this local default; point it at
# your own Postgres 18 server otherwise.
database_url = "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable"
[services.gateway]
target = "127.0.0.1:8585"
# The State Store gRPC service owns the single archie.db SQLite file; archied
# and archie-gateway dial it and never open archie.db themselves (§12 step 7).
# The State Store gRPC service owns the PostgreSQL task data; archied and
# archie-gateway dial it and never open those tables themselves (§12 step 7).
# This deployment runs the agent in containers, so target is the Docker bridge
# gateway (172.17.0.1) the container can reach, with a matching target_token
# that archie-state-store validates. Host-only agent: use 127.0.0.1:9090 with
@@ -23,9 +27,9 @@ target = "172.17.0.1:9090"
target_token = "change-me-state-store-token"
[models]
triage = "openai/gpt-4o"
planner = "openai/gpt-4o"
builder = "openai/gpt-4o"
triage = "openai/gpt-6-luna"
planner = "openai/gpt-6-luna"
builder = "openai/gpt-6-luna"
[providers.openai]
class = "openai"
+10 -6
View File
@@ -6,7 +6,11 @@
# ==============================================================================
work_dir = "~/.local/share/archie/work"
db_path = "~/.local/share/archie/archie.db"
state_dir = "~/.local/share/archie" # NATS store, task logs
# The State Store's PostgreSQL connection (required; Postgres-only epic).
# `docker compose up -d postgres` provides this local default; point it at
# your own Postgres 18 server otherwise.
database_url = "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable"
poll_interval = "60s"
label = "archie"
bot_user = "archie-bot"
@@ -19,8 +23,8 @@ diff_cap_lines = 400
[services.gateway]
target = "127.0.0.1:8585"
# The State Store gRPC service owns the single archie.db SQLite file. archied
# and archie-gateway dial it here and never open archie.db themselves
# The State Store gRPC service owns the PostgreSQL task data. archied and
# archie-gateway dial it here and never open those tables themselves
# (docs/prds/state-store-contract.md §12 step 7). This deployment runs the
# agent in containers, so the target must be the Docker bridge gateway address
# (172.17.0.1) that the container can reach, and a non-loopback target requires
@@ -49,9 +53,9 @@ pr = "archie:pr"
parked = "archie:parked"
[models]
triage = "openai/gpt-4o"
planner = "openai/gpt-4o"
builder = "openai/gpt-4o"
triage = "openai/gpt-6-luna"
planner = "openai/gpt-6-luna"
builder = "openai/gpt-6-luna"
[providers.openai]
class = "openai"
+12 -8
View File
@@ -16,11 +16,10 @@ here, where it would drift from what is written.
The Gateway unit is `archie-gateway.service`, written by `install.sh` beside
`archied.service`.
The State Store unit is `archie-state-store.service`. It owns the single `archie.db` SQLite
file and serves the `StateStore` gRPC contract. After the in-process store path
was deleted, BOTH `archied` and `archie-gateway` dial it via
`[services.state].target` (see the `archied` config below) and never open
`archie.db` themselves (`docs/prds/state-store-contract.md` §12 step 7). A
The State Store unit is `archie-state-store.service`. It owns the task data in
PostgreSQL and serves the `StateStore` gRPC contract. BOTH `archied` and
`archie-gateway` dial it via `[services.state].target` (see the `archied`
config below) and never open the task tables themselves (`docs/prds/state-store-contract.md` §12 step 7). A
host-only agent uses the loopback bind with no token below; a container-mode
agent needs the Docker bridge gateway address plus a bearer token via
`--token`/`STATE_STORE_TOKEN` or `[services.state].target_token`, and a
@@ -107,6 +106,7 @@ loginctl enable-linger "$USER"
```
Verify linger status:
```bash
loginctl show-user "$USER" | grep Linger
# Output: Linger=yes
@@ -117,26 +117,31 @@ loginctl show-user "$USER" | grep Linger
## 4. Service Commands
Reload systemd daemon files:
```bash
systemctl --user daemon-reload
```
Enable and start the service immediately:
```bash
systemctl --user enable --now archie-state-store archie-gateway archie-messaging archie-ui archied
```
Check service status:
```bash
systemctl --user status archied
```
Tail live daemon logs:
```bash
journalctl --user -u archied -f
```
Restart or stop the service:
```bash
systemctl --user restart archied
systemctl --user stop archied
@@ -254,6 +259,5 @@ with the operator's Docker credentials and retain `pull_policy = "missing"`:
docker compose pull agent
```
`db_path` and other paths are native host paths. Point them at the intended
state directory; changing from an old containerized daemon path can otherwise
start Archie against empty state files.
`state_dir` and other paths are native host paths. Point `state_dir` at the
intended state directory (embedded NATS store, task logs).
+45 -3
View File
@@ -1,24 +1,53 @@
# Optional external NATS, plus the agent image the daemon spawns per task.
# PostgreSQL for the State Store, optional external NATS, and the agent images
# the daemon spawns per task.
#
# archied itself runs on the host under systemd, not here -- its chat tools
# operate on host files, which a container cannot reach. See
# deployments/systemd-user-service.md.
#
# Embedded NATS is the normal deployment and needs no Compose service.
# State Store DB: docker compose up -d postgres
# External broker: docker compose up -d nats
# Build worker: docker compose build agent
# Profile image: docker compose build agent-net
# Stop external: docker compose down
# Logs: journalctl --user -u archied -f (the daemon)
# docker compose logs -f nats (the bus)
services:
# ── PostgreSQL (State Store) ───────────────────────────────────
# The standalone archie-state-store process's database. PostgreSQL 18 is
# the required minimum and target; `postgres.Open` refuses anything older.
# `task dev` brings this up before the State Store via dev:postgres. The
# credentials and database name below are the dev default mirrored by
# deployments/dev.toml's database_url -- change both together.
postgres:
image: postgres:18
environment:
POSTGRES_USER: archie
POSTGRES_PASSWORD: archie
POSTGRES_DB: archie
# postgres:18 moved its default PGDATA under a versioned path; pin the
# classic location so the named volume keeps working across image updates.
PGDATA: /var/lib/postgresql/data/pgdata
ports:
- "5432:5432"
volumes:
- pg_data:/var/lib/postgresql/data
restart: unless-stopped
healthcheck:
test: ["CMD-SHELL", "pg_isready -U archie -d archie"]
interval: 10s
timeout: 5s
retries: 5
# ── NATS JetStream ────────────────────────────────────────────────
nats:
image: nats:2.14-alpine3.22
command: -js -m 8222
ports:
- "4222:4222" # client
- "8222:8222" # monitoring (http://localhost:8222)
- "4222:4222" # client
- "8222:8222" # monitoring (http://localhost:8222)
volumes:
- nats_data:/data
restart: unless-stopped
@@ -54,8 +83,21 @@ services:
# deployments/systemd-user-service.md#pinning-the-archie-agent-image.
image: ghcr.io/samcharles93/archie-agent@sha256:870f1b1357979cfea23fccacb24166ebeb9ab321708ef2c2b218a763ed99b090
# ── example agent profile image ─────────────────────────────────────
# The agent image plus network lookup tools, for a workflow that names
# `profile: network-investigator` (examples/workflows/firewall-investigate.yaml).
# Build-only for the same reason as agent. It is local, so leave
# containers.pull_policy at "missing": "always" would try to pull it.
agent-net:
profiles: ["build"]
build:
context: examples/profiles
dockerfile: Dockerfile.agent-net
image: archie-agent-net:local
volumes:
nats_data:
pg_data:
# The subnet is pinned for the optional external-broker profile because its
# configured URL must be reachable from both the native daemon and workers.
+2 -2
View File
@@ -70,8 +70,8 @@ Effort is the per-stage `MaxSteps` budget, mapped onto `Subagent.MaxSteps`
## Operator-triggered review
The same reviewer runs against an *existing* PR via the channel-neutral
The same reviewer runs against an _existing_ PR via the channel-neutral
`review_pr` chat command: fetch the PR's head, snapshot it, run the isolated
reviewer, and return the structured findings. Authorization is identity-scoped
reviewer, and return the structured findings. Authorisation is identity-scoped
to the operator's configured repositories; duplicate or concurrent reviews of
the same PR are deduplicated.
+39 -35
View File
@@ -73,7 +73,7 @@ The Agent System requires four distinct durable memory scopes:
- **agent-wide memory**: general expertise, operating knowledge, and perspective
owned by one Agent and safe for that Agent to use across users;
- **user-wide memory**: information associated with one user and available to
authorized Agents serving that user;
authorised Agents serving that user;
- **Agent-user relationship memory**: private history and learned context from
one particular Agent's relationship with one particular user.
@@ -86,7 +86,7 @@ same Agent may access it implicitly.
Archie is a multi-user system even when initially deployed for one person.
Multiple users, including family members, may interact with the same configured
Agents. Per-user memory is therefore an isolation and personalization boundary,
Agents. Per-user memory is therefore an isolation and personalisation boundary,
not merely an attribution tag on the primary user's records.
An Agent MUST resolve the initiating user before assembling memory context.
@@ -96,7 +96,7 @@ because both users interact with the same Agent.
Shared memory does not erase provenance. Every memory record retains its scope,
author or acting identity, originating user when applicable, source, and
revision history. The rules for selecting a write scope, granting access
to global and user-wide memory, and authorizing explicit cross-scope sharing are
to global and user-wide memory, and authorising explicit cross-scope sharing are
settled by [`docs/prds/memory-engine-unification.md`](../prds/memory-engine-unification.md)
and recorded in [`migration-decisions.md`](migration-decisions.md#5-memory-placement-and-storage)
section 5.
@@ -178,13 +178,15 @@ The current `store.Task` lifecycle uses:
```text
queued -> running
running -> waiting_human | pr_open | merged | parked | closed_wont_do
running -> queued (crash recovery) | waiting_human | pr_open | completed | parked | closed_wont_do
waiting_human -> queued | closed_wont_do
parked -> queued | dead
pr_open -> merged | rejected
running after crash -> queued
```
`merged` is reached only from `pr_open`. `completed` is terminal: it means a
workflow that opens no pull request finished its work.
Workflows select and sequence deterministic and agent-run stages. Implement,
TDD, feasibility, and bootstrap are current Workflow definitions.
Every WorkflowExecution is handed wholesale over core NATS to a task-scoped
@@ -194,8 +196,9 @@ Every WorkflowExecution is handed wholesale over core NATS to a task-scoped
The behaviour is divided across technical packages:
- `internal/store` defines the current `Task` execution record and status
strings and persists mutable state and transition history.
- `internal/domain/workflow` defines the current `Task` execution record and
status strings; `internal/infrastructure/postgres` persists mutable state
and transition history behind `internal/domain/storecontract`.
- `internal/daemon` discovers, claims, schedules, retries, recovers, processes,
waits for human input, and reconciles pull requests.
- `internal/domain/workflow` routes work, executes stages, mutates tasks, applies
@@ -205,7 +208,7 @@ The behaviour is divided across technical packages:
- `internal/gate` and repository configuration define execution constraints.
- `internal/gateway` duplicates task status strings and applies task-control
rules.
- forge, worktree, NATS, SQLite, containers, and agent runtimes are concrete
- forge, worktree, NATS, PostgreSQL, containers, and agent runtimes are concrete
dependencies mixed into orchestration.
## Current `task` meanings and required replacements
@@ -213,30 +216,30 @@ The behaviour is divided across technical packages:
The existing code uses `task` for unrelated concepts. Migration MUST resolve
each meaning deliberately; a global text replacement is prohibited.
| Current meaning | Representative locations | Target concept | Requirements |
| -------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Forge issue or external task | `internal/forge`, daemon polling | Channel message | Preserve the channel's native reference and payload. Translate it into an Agent System request without importing forge or issue semantics into Workflow. |
| Jira issue or other external work item | Messaging infrastructure adapter | Channel message or external artifact | The external system retains its own vocabulary inside its integration. Its record may lead to an accepted work request but is not a Workflow or WorkflowExecution. |
| Persisted `store.Task` row | `internal/store` | WorkflowExecution | Own identity, Workflow ID and version, lifecycle, source-message reference, outputs, attempts, and outcome. Persistence implements the Agent System repository contract. |
| Task status and transition history | `store.Status*`, `transitions` | WorkflowExecution lifecycle and domain events | Enforce legal transitions atomically. Domain events and state changes cannot diverge. Remove duplicated status strings from consumers. |
| Claimed or queued task | `ClaimNext`, `ClaimByIssue`, `RecoverStale` | Scheduled WorkflowExecution | Claim by WorkflowExecution ID and expected version/state. Crash recovery and leases must not silently create a new execution. |
| `workflow.TaskContext` | `internal/domain/workflow` | WorkflowExecution context | Replace the mutable service bag with execution state plus narrow step-required contracts. Complete application configuration and unrelated services are forbidden. |
| `taskrun.Request` and `taskrun.Response` | `internal/taskrun`; consumed by `internal/app/agentworker`, decoded by `internal/infrastructure/agenttransport/nats` | WorkflowExecution handoff | This is the versioned worker contract for executing a WorkflowExecution. It carries domain-owned execution data, not store rows or global configuration DTOs. |
| Per-stage `agentexec.Request.TaskID` | `internal/agentexec` | WorkflowExecutionID correlation | An agent invocation is a bounded WorkflowStep execution. Correlate request/result with WorkflowExecutionID, StepExecutionID, attempt, and protocol version. |
| Current meaning | Representative locations | Target concept | Requirements |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Forge issue or external task | `internal/forge`, daemon polling | Channel message | Preserve the channel's native reference and payload. Translate it into an Agent System request without importing forge or issue semantics into Workflow. |
| Jira issue or other external work item | Messaging infrastructure adapter | Channel message or external artifact | The external system retains its own vocabulary inside its integration. Its record may lead to an accepted work request but is not a Workflow or WorkflowExecution. |
| Persisted `workflow.Task` row | `internal/infrastructure/postgres` | WorkflowExecution | Own identity, Workflow ID and version, lifecycle, source-message reference, outputs, attempts, and outcome. Persistence implements the Agent System repository contract. |
| Task status and transition history | `store.Status*`, `transitions` | WorkflowExecution lifecycle and domain events | Enforce legal transitions atomically. Domain events and state changes cannot diverge. Remove duplicated status strings from consumers. |
| Claimed or queued task | `ClaimNext`, `ClaimByIssue`, `RecoverStale` | Scheduled WorkflowExecution | Claim by WorkflowExecution ID and expected version/state. Crash recovery and leases must not silently create a new execution. |
| `workflow.TaskContext` | `internal/domain/workflow` | WorkflowExecution context | Replace the mutable service bag with execution state plus narrow step-required contracts. Complete application configuration and unrelated services are forbidden. |
| `taskrun.Request` and `taskrun.Response` | `internal/taskrun`; consumed by `internal/app/agentworker`, decoded by `internal/infrastructure/agenttransport/nats` | WorkflowExecution handoff | This is the versioned worker contract for executing a WorkflowExecution. It carries domain-owned execution data, not store rows or global configuration DTOs. |
| Per-stage `agentexec.Request.TaskID` | `internal/agentexec` | WorkflowExecutionID correlation | An agent invocation is a bounded WorkflowStep execution. Correlate request/result with WorkflowExecutionID, StepExecutionID, attempt, and protocol version. |
| NATS `TaskMessage` and `archie.task.*` | `internal/domain/workintake` (subjects, `TaskEnvelope`); `internal/infrastructure/agenttransport/nats` (transport) -- `internal/nats` no longer exists; whether this row's "current meaning" itself is now superseded by `TaskEnvelope` needs a closer look, not asserted here | Channel request or WorkflowExecution transport | Discovery messages and execution dispatch are different contracts and subjects. Domain meaning stays outside NATS infrastructure. Identity and source-message idempotency must be explicit. |
| `taskDispatcher` work item | `internal/daemon` | WorkflowExecution scheduling | Scheduling operates on execution references and declared concurrency policy. Repository serialization is policy, not identity derived from an incomplete task struct. |
| `container.TaskPayload` and `task.json` | `internal/container`; read by `internal/infrastructure/agentboot` | WorkflowExecution brief | Rename the boot artifact and schema. It identifies the mounted execution and required workspace only; it is not an alternative execution definition. Missing or malformed input must fail startup before the worker subscribes. |
| `storage.TaskRef` | `internal/storage` | WorkflowExecution workspace lease | Storage receives the minimal execution/workspace reference and policy required to provision and release resources. It does not receive the WorkflowExecution aggregate. |
| Gateway `TaskCreator` | `internal/gateway` | Accepted work request handoff | A channel may carry a request for durable workflow-backed work, but it does not request or create a WorkflowExecution directly. Work intake admits and routes the request; the Agent System consumes the accepted work request and is the sole owner of selecting a Workflow version and creating the WorkflowExecution. Ordinary agent interactions do not require this handoff. |
| Gateway `TaskController` and `ChatTaskStatus` | `internal/gateway/tasks.go` | WorkflowExecution commands and query view | Approve, cancel, and status use Agent System contracts. Channel code does not duplicate lifecycle constants or decide transitions. |
| Gateway `TaskProfile` | `internal/gateway/tasks.go`, `cmd/archied` | Channel/identity execution defaults | This is configuration selecting allowed source targets and default Workflow inputs, not task state. Split it into settings owned by the relevant channel and Agent System features. |
| `config.TaskConfig` and `TaskForge` | `internal/config` | Worker execution settings and channel/service references | Dissolve with `internal/config`. Each field moves to its owning runtime settings or versioned WorkflowExecution handoff contract. Secrets and external configuration forms do not enter the domain. |
| `events.Event.TaskID`, task event timelines | `internal/events`, stores, web UI | WorkflowExecutionID and WorkflowExecution events | Authoritative events are Agent System events. Observability and timelines project those events rather than inventing parallel generic task events. |
| Web UI task lists and counts | `internal/webui`, store query APIs | WorkflowExecution read model | Dashboard status, history, and counts are projections of WorkflowExecution state and events. The UI does not depend on persistence records. |
| Task-scoped forge/store/worktree RPC | `forgerpc`, `storerpc`, `worktreerpc`, `registerTaskRPCServers` | Execution-scoped capability ports | Worker calls use narrow domain-required service contracts, carry WorkflowExecutionID and IdentityID, and resolve the owning capability binding. Root-client fallback is forbidden. |
| Per-task worktree, branch, volume, and cleanup | daemon, worktree, storage, container | WorkflowExecution workspace | Every WorkflowExecution receives isolated workspace state. Workspace lifecycle is explicit, identity-aware, recoverable, and controlled outside the model. |
| Task retry, dead, waiting-human, PR reconciliation | daemon, workflow, gateway | WorkflowExecution lifecycle policies | Retry, waiting, cancellation, reconciliation, and terminal outcomes are Agent System behaviour. Channels and infrastructure report facts or submit commands; they do not mutate state. |
| Task-run readiness and retry timeouts | daemon taskrun request loop | Worker-dispatch settings and policy | These settings govern WorkflowExecution handoff availability. They are not Workflow data and must be owned by the worker-dispatch capability. |
| `taskDispatcher` work item | `internal/daemon` | WorkflowExecution scheduling | Scheduling operates on execution references and declared concurrency policy. Repository serialisation is policy, not identity derived from an incomplete task struct. |
| `container.TaskPayload` and `task.json` | `internal/container`; read by `internal/infrastructure/agentboot` | WorkflowExecution brief | Rename the boot artifact and schema. It identifies the mounted execution and required workspace only; it is not an alternative execution definition. Missing or malformed input must fail startup before the worker subscribes. |
| `storage.TaskRef` | `internal/storage` | WorkflowExecution workspace lease | Storage receives the minimal execution/workspace reference and policy required to provision and release resources. It does not receive the WorkflowExecution aggregate. |
| Gateway `TaskCreator` | `internal/gateway` | Accepted work request handoff | A channel may carry a request for durable workflow-backed work, but it does not request or create a WorkflowExecution directly. Work intake admits and routes the request; the Agent System consumes the accepted work request and is the sole owner of selecting a Workflow version and creating the WorkflowExecution. Ordinary agent interactions do not require this handoff. |
| Gateway `TaskController` and `ChatTaskStatus` | `internal/gateway/tasks.go` | WorkflowExecution commands and query view | Approve, cancel, and status use Agent System contracts. Channel code does not duplicate lifecycle constants or decide transitions. |
| Gateway `TaskProfile` | `internal/gateway/tasks.go`, `cmd/archied` | Channel/identity execution defaults | This is configuration selecting allowed source targets and default Workflow inputs, not task state. Split it into settings owned by the relevant channel and Agent System features. |
| `config.TaskConfig` and `TaskForge` | `internal/config` | Worker execution settings and channel/service references | Dissolve with `internal/config`. Each field moves to its owning runtime settings or versioned WorkflowExecution handoff contract. Secrets and external configuration forms do not enter the domain. |
| `events.Event.TaskID`, task event timelines | `internal/events`, stores, web UI | WorkflowExecutionID and WorkflowExecution events | Authoritative events are Agent System events. Observability and timelines project those events rather than inventing parallel generic task events. |
| Web UI task lists and counts | `internal/webui`, store query APIs | WorkflowExecution read model | Dashboard status, history, and counts are projections of WorkflowExecution state and events. The UI does not depend on persistence records. |
| Task-scoped forge/store/worktree RPC | `forgerpc`, `storerpc`, `worktreerpc`, `registerTaskRPCServers` | Execution-scoped capability ports | Worker calls use narrow domain-required service contracts, carry WorkflowExecutionID and IdentityID, and resolve the owning capability binding. Root-client fallback is forbidden. |
| Per-task worktree, branch, volume, and cleanup | daemon, worktree, storage, container | WorkflowExecution workspace | Every WorkflowExecution receives isolated workspace state. Workspace lifecycle is explicit, identity-aware, recoverable, and controlled outside the model. |
| Task retry, dead, waiting-human, PR reconciliation | daemon, workflow, gateway | WorkflowExecution lifecycle policies | Retry, waiting, cancellation, reconciliation, and terminal outcomes are Agent System behaviour. Channels and infrastructure report facts or submit commands; they do not mutate state. |
| Task-run readiness and retry timeouts | daemon taskrun request loop | Worker-dispatch settings and policy | These settings govern WorkflowExecution handoff availability. They are not Workflow data and must be owned by the worker-dispatch capability. |
### Terms that do not migrate
@@ -282,7 +285,7 @@ preserved or deliberately removed.
| Gates and protection | `Gate`, `Preflight`, `Protection`, repository config | Agent System policy definitions resolved for the WorkflowExecution and enforced outside the agent |
| Budgets | steps, tokens, wall clock, gate failures | Execution and StepExecution policy values with measured usage and evidence |
| Tool access | capture tools, registry, guardrails, skill plugins | Resolved step capability set and policy; global registry pointers do not enter execution state |
| Persistence timestamps | SQL `created_at` and `updated_at` | Domain timestamps and version used for optimistic concurrency and audit |
| Persistence timestamps | SQL `created_at` and `updated_at` | Domain timestamps and version used for optimistic concurrency and audit |
| Transition history | SQL `transitions` and generic events | Authoritative WorkflowExecution domain events stored atomically with state |
## Current runtime responsibilities to unify
@@ -293,7 +296,7 @@ implemented in different packages:
- accept a request from a channel and enforce idempotency;
- select and version a Workflow;
- create, queue, claim, schedule, and execute a WorkflowExecution;
- serialize same-repository execution where policy requires it;
- serialise same-repository execution where policy requires it;
- resolve identity-specific capabilities;
- prepare, retain, recover, and clean up the workspace;
- run deterministic and agent-backed WorkflowSteps;
@@ -309,7 +312,8 @@ implemented in different packages:
## Current workflow-feature hazards
- There is no enforced WorkflowExecution state machine. `Store.Transition`
ignores the supplied `from` state when updating the row.
guards on the supplied `from` state but accepts any `from` to `to` pair. See
`docs/prds/execution-tree-state-machine.md`.
- State update and transition-history insertion are separate operations, so
state and audit can diverge.
- Callers frequently discard persistence and transition errors.
@@ -341,7 +345,7 @@ implemented in different packages:
- Agent execution crosses a versioned data boundary.
- Forge, persistence, workspace, transport, container, and model runtimes remain
replaceable infrastructure.
- Work from the same repository is serialized by default.
- Work from the same repository is serialised by default.
## Required migration
+37 -28
View File
@@ -21,32 +21,37 @@ machine** governing whether it is live.
type Binding struct {
ID, Name // identity
Matcher // { Source string } -- the webhook path segment, e.g. "sentry"
MappingID // which Mapping resolves payload fields
MappingID // which Mapping resolves payload fields; its event type is the binding's
Filter // optional CEL over the mapping's parameters
Workflow // registered workflow name to dispatch to
Version // bumped on every edit
Status // draft | pending_approval | armed
Status // pending_approval | armed
Secret // HMAC-SHA256 shared secret, encrypted at rest, never returned by GET
}
```
Bindings live in the store (SQLite), not `config.toml` -- operators author
Bindings live in the store (PostgreSQL), not `config.toml` -- operators author
them from the dashboard while the daemon runs, without a restart.
### Matching
`Matcher.Source` is the only predicate today: the path segment a sender
POSTs to (e.g. a webhook hitting `.../sentry` matches bindings with
`Matcher.Source == "sentry"`). The storage column is plain `TEXT`, so adding
predicates later is non-breaking -- extend `Matcher`, don't invent a second
matcher shape.
A binding applies to a capture when the capture arrived on `Matcher.Source`,
was identified as the event type its mapping belongs to, and passes its
`Filter` (`binding.CompileFilter`, checked against the mapping's parameters on
save). Any number of bindings may share a source; each dispatches a capture at
most once, claimed in `binding_dispatches` keyed by (binding, capture) before
its task is enqueued. An event signed with any armed binding's secret on the
source is authenticated.
### Mapping
`mapping.Resolve(fields, payload)` walks a captured JSON payload against a
list of typed `Field`s (name, JSON path, expected type), returning resolved
values plus a `[]Failure` for anything that didn't parse or type-match. This
is schema-by-example in practice: a mapping is authored by pointing at a
real captured payload in the dashboard, not by guessing a schema in advance.
values plus a `[]Failure` for anything that didn't parse or type-match. A
mapping belongs to an event type, and `mapping.CheckSchema` refuses a field
whose path or type the type's inferred schema lacks. Each capture a mapping
resolves at dispatch is counted once in `mapping_matches`, read back as
`MatchCount` and `LastMatchedAt`.
### Versioning
@@ -59,18 +64,21 @@ binding currently says."
### State machine
```
draft ---> pending_approval ---> armed
^ ^ |
| | |
+--------------+-----------------+
create ---> pending_approval ---> armed
^ |
+----------------+
(any edit to an armed binding drops it back to pending_approval)
```
Modeled directly on Telegram's existing `dangerousAction`/`pendingApproval`
A binding is created `pending_approval`, so the operator who creates one can
approve it immediately. Bindings stored as `draft` by an earlier version are
moved to `pending_approval` when the EDA store opens.
Modelled directly on Telegram's existing `dangerousAction`/`pendingApproval`
flow (`internal/channels/telegram/dangerous.go`, `approval.go`) -- not a new
approval mechanism invented for this feature. **Only `armed` evaluates
against incoming events** (`binding.Matches`, `internal/domain/binding/
binding.go`); `draft` and `pending_approval` bindings are inert. An edit to
binding.go`); a `pending_approval` binding is inert. An edit to
an already-armed binding cannot bypass approval by silent mutation -- it
drops back to `pending_approval` and requires an explicit `Approve` call to
re-arm.
@@ -93,8 +101,9 @@ unauthenticated event can never trigger a binding, no matter how well it
would otherwise match." Enforced structurally at two points, not just
convention:
- `captured_events.authenticated` is a real column (`internal/store/
captures.go`), set at capture time.
- `captures.authenticated` is a real column
(`internal/infrastructure/postgres/migrations/0002_edastore.sql`), set at
capture time.
- `dispatchBindings` (`internal/daemon/daemon.go:479`) walks **authenticated
captures whose source has at least one armed binding** -- an
unauthenticated capture is never even considered for dispatch.
@@ -109,7 +118,7 @@ binding reverts it.
Capture writes are bounded independently of the approval gate, so a flood
of unauthenticated traffic cannot exhaust disk or drown the inspector:
`InsertCapture` (`internal/store/captures.go`) prunes by both **retention
`InsertCapture` (`internal/infrastructure/postgres/edastore.go`) prunes by both **retention
window** (`WHERE received_at < cutoff`) and **max event count** in the same
insert transaction.
@@ -118,14 +127,14 @@ insert transaction.
A playbook-originated task is dispatched into the **same** gate, diff-cap,
sandboxed-container, worktree-isolation pipeline every task goes through
regardless of origin. Verified precisely, not assumed: `dispatchOneBinding`
calls `EnqueueBindingTask` (`internal/store/store.go`), which wraps
calls `EnqueueBindingTask` (`internal/infrastructure/postgres/store.go`), which wraps
`EnqueueChatTask` -- the same direct-to-`tasks`-table enqueue path
chat-spawned tasks already use, then stamps `binding_id`/`binding_version`
for provenance in a second statement. This is a **different** enqueue
mechanism from forge-issue polling's `workintake.TaskEnvelope`/NATS path
(`docs/prds/event-sources-and-reactions.md`) -- binding and forge-issue
tasks arrive by different producers, but both become an ordinary
`store.Task` row that `ClaimNext` picks up identically, so both get the
`workflow.Task` row that `ClaimNext` picks up identically, so both get the
same gate/worktree pipeline downstream regardless of which producer created
the row. Payload content is
ordinary untrusted prompt input; the sender's text is never treated as a
@@ -148,8 +157,8 @@ Two independent protections, not one:
### Secrets at rest
`Binding.Secret` (the HMAC shared secret a sender signs with) is encrypted
at rest via AES-GCM (`internal/store/binding_cipher.go`, `archie-core-
t2db.7`) -- a leaked SQLite file does not leak sender-side shared secrets in
at rest via AES-GCM (`internal/infrastructure/bindingcipher`, `archie-core-
t2db.7`) -- a leaked database dump does not leak sender-side shared secrets in
plaintext. The envelope is versioned (`bindingEnvelopeVersion`) so a future
cipher or KDF change can roll forward without breaking already-encrypted
rows, and the AAD binds ciphertext to the binding-secret context so it
@@ -161,8 +170,8 @@ documented legacy behaviour, not silent degradation.
`dispatchBindings` enqueues at most one task per `(binding, capture)` pair,
enforced by a real ledger, not best-effort application logic:
`RecordDispatch` (`internal/store/bindings.go`) does `INSERT OR IGNORE` into
`binding_dispatches`, unique on `(binding_id, capture_id)`; a duplicate
`RecordDispatch` (`internal/infrastructure/postgres/edastore.go`) inserts into
`binding_dispatches`, unique on `(binding, capture)`; a duplicate
insert returns the sentinel `ErrAlreadyDispatched`, which the dispatch loop
treats as "another cycle raced us," not an error. This guarantee holds
**across daemon restarts**, not just within one process's lifetime, because
@@ -170,8 +179,8 @@ the ledger is a durable table, not in-memory state.
This ledger is also the direct precedent for the EDA playbook engine's
execution-time idempotency, now landed (`archie-core-t2db.17` closed): the
`playbook_dispatches` table in `internal/store/playbook_dispatches.go` copies
`binding_dispatches`'s `INSERT OR IGNORE` conventions with a
`playbook_dispatches` table (`RecordPlaybookDispatch`) copies
`binding_dispatches`'s unique-ledger conventions with a
`(playbook_id, playbook_version, event_id, action_id)` key
(`docs/prds/eda-playbook-engine.md` gap 2).
+42 -42
View File
@@ -42,7 +42,7 @@ The document:
External DTOs and domain runtime settings are separate types.
Plugins supply external configuration definitions through a narrow extension
contract. The core loader MUST NOT gain a field or recognized filename for every
contract. The core loader MUST NOT gain a field or recognised filename for every
plugin.
Invalid configuration input MUST NOT replace active valid settings or terminate
@@ -139,34 +139,34 @@ This ledger records the current meanings hidden inside `internal/config`. It is
the source inventory for dissolving that package; rows are split where the
existing structure combines different owners.
| Current values | Current location | Target owner and requirement |
| ----------------------------------------------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WorkDir`, `DBPath` | root `Config` | Workspace/storage infrastructure settings. `DBPath` is the prefix for independent task and conversation SQLite files. Defaults derive from the platform data directory. |
| `SkillsDir`, `PluginDir` | root `Config` | Skill and plugin infrastructure settings, independently typed. |
| `PollInterval` | root `Config` | Work-intake scheduling setting; not a daemon-wide constant. |
| `Label`, `BotUser`, `BotEmail` | root `Config` | Identity and dispatch associations. `BotEmail` may be derived from the selected forge account but remains overrideable. |
| `MaxRetries` | root `Config`, `Repo` | Retry policy owned by the operation being retried. The duplicate global/repository representation must disappear. |
| `DiffCapLines` | root `Config` | Agent-change policy value. |
| `MaxSteps`, `WallClock`, `GateMaxFailures` | `Budgets` | Workflow-execution policy, with units and zero/unlimited semantics made explicit. |
| `Class`, `APIKeyEnv`, `BaseURL` | `Provider` | Provider instance settings. Secret lookup becomes a `SecretRef`, not an environment variable name leaking into the provider domain. |
| `Mode`, `Command`, `Env` | `LegacyAgent` | Decode-only compatibility input for the removed executor selector. Delete after the config migration window; it has no runtime settings owner. |
| `Type`, `Host`, `Token` / `TokenEnv` (older form) | `Forge` | Forge adapter settings. The older `TokenEnv` input is accepted only at the loader boundary. |
| `Trigger`, `AckReaction`, label names | `Dispatch` | Work-intake and forge presentation policy. Label vocabulary is configurable per forge/identity association. |
| `Engine` | `MemoryConfig` | Memory engine selection. `internal/domain/memory` is the only engine family; per-engine settings remain owned and validated by that engine. |
| `Name`, `Transport`, `Command`, `Args`, `WorkDir`, `URL` | `MCPServer` | One typed MCP server instance specification. Transport-specific variants must reject fields belonging to other variants. |
| `MaxResultChars` | `ToolPolicy` | Tool-execution policy values, not generic daemon configuration. |
| `URL`, `TokenEnv` | `NATSConfig` | NATS transport settings with a secret reference replacing the environment-name field. |
| `Image`, `MaxConcurrency`, `MaxUptime`, `VolumeTTL`, `PullPolicy`, `Network` | `ContainerConfig` | Mandatory managed-worker infrastructure settings and resource policy. The legacy `enabled` input is decode-only. |
| model mappings, email, webhook, Telegram | `ChatConfig` | Separate channel instance settings plus channel-routing associations; there is no chat-wide settings owner. |
| `AllowedUserIDs`, `Token` / `TokenEnv` (older form), update commands | Telegram config | Telegram adapter settings and access policy. `Token` is the preferred `secret.SecretRef`; `TokenEnv` remains a backwards-compatible fallback. |
| listen/relay addresses | email config | Email adapter instance settings. |
| webhook target | `Notify` | Notification adapter instance settings. |
| web listen address | `Web` | Web transport settings. |
| `listen` under `[services.state]` and `[services.gateway]` | `ServiceConnection` | The bind address of the process that owns the service. Read only by that process, and defaulted to the address its clients dial so the pair cannot drift. |
| forge, dispatch, models, providers, containers, memory, tools and repositories | `IdentityConfig` | Existing composite duplicates unrelated settings. Replace it with associations from an `IdentityID` to independently owned configured instances. |
| owner, name, base, gate, protection, ecosystem, preflight, storage, retry and concurrency | `Repo` | Split across work intake, workspace, workflow execution, policy, gate, and scheduling as described in Repository settings. |
| `TaskConfig`, `TaskForge` | worker snapshot | Replace with the minimum immutable, versioned WorkflowExecution input assembled by the application. It is not a second configuration model. |
| `Extra` and arbitrary maps | root/provider config | Allowed only at an extension boundary whose owning plugin/provider supplies schema and validation. Core configuration never consumes an untyped catch-all. |
| Current values | Current location | Target owner and requirement |
| ----------------------------------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WorkDir`, `StateDir` | root `Config` | Workspace/storage infrastructure settings, bootstrap-only. `StateDir` holds the embedded NATS store and endpoint file, task logs and the readiness disk target. Defaults derive from the platform data directory. |
| `SkillsDir`, `PluginDir` | root `Config` | Skill and plugin infrastructure settings, independently typed. |
| `PollInterval` | root `Config` | Work-intake scheduling setting; not a daemon-wide constant. |
| `Label`, `BotUser`, `BotEmail` | root `Config` | Identity and dispatch associations. `BotEmail` may be derived from the selected forge account but remains overrideable. |
| `MaxRetries` | root `Config`, `Repo` | Retry policy owned by the operation being retried. The duplicate global/repository representation must disappear. |
| `DiffCapLines` | root `Config` | Agent-change policy value. |
| `MaxSteps`, `WallClock`, `GateMaxFailures` | `Budgets` | Workflow-execution policy, with units and zero/unlimited semantics made explicit. |
| `Class`, `APIKeyEnv`, `BaseURL` | `Provider` | Provider instance settings. Secret lookup becomes a `SecretRef`, not an environment variable name leaking into the provider domain. |
| `Mode`, `Command`, `Env` | `LegacyAgent` | Decode-only compatibility input for the removed executor selector. Delete after the config migration window; it has no runtime settings owner. |
| `Type`, `Host`, `Token` / `TokenEnv` (older form) | `Forge` | Forge adapter settings. The older `TokenEnv` input is accepted only at the loader boundary. |
| `Trigger`, `AckReaction`, label names | `Dispatch` | Work-intake and forge presentation policy. Label vocabulary is configurable per forge/identity association. |
| `Engine` | `MemoryConfig` | Memory engine selection. `internal/domain/memory` is the only engine family; per-engine settings remain owned and validated by that engine. |
| `Name`, `Transport`, `Command`, `Args`, `WorkDir`, `URL` | `MCPServer` | One typed MCP server instance specification. Transport-specific variants must reject fields belonging to other variants. |
| `MaxResultChars` | `ToolPolicy` | Tool-execution policy values, not generic daemon configuration. |
| `URL`, `TokenEnv` | `NATSConfig` | NATS transport settings with a secret reference replacing the environment-name field. |
| `Image`, `MaxConcurrency`, `MaxUptime`, `VolumeTTL`, `PullPolicy`, `Network` | `ContainerConfig` | Mandatory managed-worker infrastructure settings and resource policy. The legacy `enabled` input is decode-only. |
| model mappings, email, webhook, Telegram | `ChatConfig` | Separate channel instance settings plus channel-routing associations; there is no chat-wide settings owner. |
| `AllowedUserIDs`, `Token` / `TokenEnv` (older form), update commands | Telegram config | Telegram adapter settings and access policy. `Token` is the preferred `secret.SecretRef`; `TokenEnv` remains a backwards-compatible fallback. |
| listen/relay addresses | email config | Email adapter instance settings. |
| webhook target | `Notify` | Notification adapter instance settings. |
| web listen address | `Web` | Web transport settings. |
| `listen` under `[services.state]` and `[services.gateway]` | `ServiceConnection` | The bind address of the process that owns the service. Read only by that process, and defaulted to the address its clients dial so the pair cannot drift. |
| forge, dispatch, models, providers, containers, memory, tools and repositories | `IdentityConfig` | Existing composite duplicates unrelated settings. Replace it with associations from an `IdentityID` to independently owned configured instances. |
| owner, name, base, gate, protection, ecosystem, preflight, storage, retry and concurrency | `Repo` | Split across work intake, workspace, workflow execution, policy, gate, and scheduling as described in Repository settings. |
| `TaskConfig`, `TaskForge` | worker snapshot | Replace with the minimum immutable, versioned WorkflowExecution input assembled by the application. It is not a second configuration model. |
| `Extra` and arbitrary maps | root/provider config | Allowed only at an extension boundary whose owning plugin/provider supplies schema and validation. Core configuration never consumes an untyped catch-all. |
## Behavioural literals and incorrectly fixed values
@@ -187,8 +187,8 @@ decision; exact setting names are implementation details.
| Worker readiness | readiness timeout `20s`, retry delay `250ms` | Worker lifecycle and retry policy. |
| Execution/RPC | agent execution `30m`, task-run RPC `60s`, worktree RPC `15m` | Per-operation timeout policy. |
| Plugin/tool cleanup | plugin rollback `10s`, tool-provider cleanup `10s`, MCP-provider cleanup `10s` | Lifecycle shutdown/rollback policy owned by each engine, with a shared policy vocabulary where appropriate. |
| Memory read path | per-scope record limit `20`, rendered `<memory>` block byte cap `8192` | Memory read policy owned by the engine family (`internal/domain/memory`). |
| Built-in memory store | per-file size limit `100KiB`, query result limit `100` | Split into memory resource policy, input policy, and presentation settings. |
| Memory read path | per-scope record limit `20`, rendered `<memory>` block byte cap `8192` | Memory read policy owned by the engine family (`internal/domain/memory`). |
| Built-in memory store | per-file size limit `100KiB`, query result limit `100` | Split into memory resource policy, input policy, and presentation settings. |
| Memory safety scanner | compiled prompt-injection and sensitive-data patterns with fixed warn/block consequences | Versioned memory-domain policy definitions. Patterns and consequences must be inspectable and replaceable without editing scanner code. |
| MCP stdio | initial backoff `500ms`, maximum backoff `30s`, unlimited default retries, send and shutdown `5s` | MCP transport retry, request, and lifecycle policy. Unlimited retries must be explicit rather than a zero-value accident. |
| MCP SSE/HTTP | reconnect `1s` to `30s`, POST/request timeout `30s` | MCP transport settings and retry policy. |
@@ -200,7 +200,7 @@ decision; exact setting names are implementation details.
| HTTP clients | feasibility notification timeout `10s`; other paths use `http.DefaultClient` | Adapter request policy. Every outbound client requires an explicit timeout profile. |
| Workflow routing | labels `bug`, `feature`, `bootstrap`; workflows `tdd`, `feasibility`, `bootstrap`; fallback `implement` | Agent-system routing policy. Workflow identifiers are references, not compiled routing decisions. |
| Filesystem/deployment | `.agents/skills`, `.archie/stages`, `.archie/gate.go`, `/data/worktree`, `/data/repo`, cache names/paths and prepared sentinel | Split into deployment settings, repository conventions, and genuine internal protocol markers. Paths an installation may relocate are settings. |
| Packaged release data | `/usr/share/archie/CHANGELOG.md` | Packaging/deployment settings or paths derived from an installation prefix. |
| Packaged release data | `/usr/share/archie/CHANGELOG.md` | Packaging/deployment settings or paths derived from an installation prefix. |
| Forge presentation | default label colour `bfd4f2` and state-label colours | Forge adapter presentation settings. |
| Fallback system prompt | compiled fallback prompt | Agent-system default content, versioned and replaceable through its owning settings; safety constraints remain policy/code. |
| Default paths and identities | config path, data paths, listen addresses, model roles and workflow names | Typed defaults belonging to their respective owners, never global constants consumed throughout the application. |
@@ -235,15 +235,15 @@ constants outside their owning `DefaultSettings` construction.
The application currently changes behavioural values through unrelated paths:
| Current change seam | Current behaviour | Required target |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Telegram `/restart` in `cmd/archied` | Re-reads the global document and directly replaces Telegram token and allowed-user IDs; failure retains old values. | Submit a Telegram-settings candidate through the universal change protocol. Validate the complete candidate, promote atomically, audit the acting identity, and retain last-known-good. |
| Active model selection | `chatModelManager.SetActiveModel` changes a model reference. | A conversation/session command changing runtime state. Validate against configured model instances and audit it; do not rewrite configuration. |
| Active provider selection | `chatModelManager.SetActiveProvider` changes provider selection. | A conversation/session command changing runtime state, with the same distinction from provider-instance configuration. |
| Persona selection | `PersonaRegistry.SetActive` mutates an in-memory per-session choice. | Agent-system session state. Persistence and audit requirements are owned by that domain, not the configuration loader. |
| File and environment overlays | Applied while loading `internal/config`; defaults are filled by mutation in `finalize`. | Configuration-infrastructure input processing that produces separately typed candidates. Defaults and derivations remain visible in provenance. |
| SIGHUP config reload (2026-08) | Re-resolves the file config, re-applies the database layer over it, validates, then atomically republishes through `config.Holder`. A failed reload, whether the file or the control plane caused it, keeps the running config and records `last_error`/`last_error_at` in `/api/config`. | Candidate promotion with last-known-good retention: the running snapshot is untouched on failure. A bounded observation period and actor audit are not yet implemented. |
| Control-plane resource command (2026-09) | `ControlPlaneService.Command` validates a whole resource document against its owning feature, then writes it with an audit record (actor, source, request ID, expected version) under optimistic concurrency. Hosted on the State Store's gRPC server; the Web UI and messaging channels are its only clients. See `docs/prds/runtime-control-plane.md`. | Met for validate-stage-promote, actor audit and versioned history. Per-field health observation and validate-before-switch on live apply are not yet implemented. |
| Current change seam | Current behaviour | Required target |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Telegram `/restart` in `cmd/archied` | Re-reads the global document and directly replaces Telegram token and allowed-user IDs; failure retains old values. | Submit a Telegram-settings candidate through the universal change protocol. Validate the complete candidate, promote atomically, audit the acting identity, and retain last-known-good. |
| Active model selection | `chatModelManager.SetActiveModel` changes a model reference. | A conversation/session command changing runtime state. Validate against configured model instances and audit it; do not rewrite configuration. |
| Active provider selection | `chatModelManager.SetActiveProvider` changes provider selection. | A conversation/session command changing runtime state, with the same distinction from provider-instance configuration. |
| Persona selection | `PersonaRegistry.SetActive` mutates an in-memory per-session choice. | Agent-system session state. Persistence and audit requirements are owned by that domain, not the configuration loader. |
| File and environment overlays | Applied while loading `internal/config`; defaults are filled by mutation in `finalize`. | Configuration-infrastructure input processing that produces separately typed candidates. Defaults and derivations remain visible in provenance. |
| SIGHUP config reload (2026-08) | Re-resolves the file config, re-applies the database layer over it, validates, then atomically republishes through `config.Holder`. A failed reload, whether the file or the control plane caused it, keeps the running config and records `last_error`/`last_error_at` in `/api/config`. | Candidate promotion with last-known-good retention: the running snapshot is untouched on failure. A bounded observation period and actor audit are not yet implemented. |
| Control-plane resource command (2026-09) | `ControlPlaneService.Command` validates a whole resource document against its owning feature, then writes it with an audit record (actor, source, request ID, expected version) under optimistic concurrency. Hosted on the State Store's gRPC server; the Web UI and messaging channels are its only clients. See `docs/prds/runtime-control-plane.md`. | Met for validate-stage-promote, actor audit and versioned history. Per-field health observation and validate-before-switch on live apply are not yet implemented. |
Any further mutation seam discovered during migration MUST be added here before
it is changed. Direct field assignment on a live settings object is prohibited.
@@ -316,7 +316,7 @@ genuinely takes effect.
### Settings writes go through the control plane
Database-backed settings are read and written through
`ControlPlaneService` on the State Store's gRPC server: catalog, query,
`ControlPlaneService` on the State Store's gRPC server: catalogue, query,
command, watch. Each feature owns its resource's validation and commands;
storage writes versions and audit records only. `docs/prds/runtime-control-plane.md`
is the specification.
@@ -45,7 +45,7 @@ the messaging behaviour Archie requires, including publication, subscription,
delivery outcomes, and required lifecycle semantics.
It MUST remain broker-neutral. NATS subjects, JetStream configuration, consumer
groups, acknowledgements, reconnection, and serialization belong under
groups, acknowledgements, reconnection, and serialisation belong under
`internal/infrastructure/eventbus/nats` unless Archie explicitly requires a
semantic guarantee in the shared contract.
@@ -56,7 +56,7 @@ messages; it does not own their meaning.
Canonical worker and service wire contracts and their authoritative generation
inputs are owned by the domain or capability that defines their meaning. They
MUST NOT be centralized in `internal/infrastructure/spec` or another generic
MUST NOT be centralised in `internal/infrastructure/spec` or another generic
schema package.
Infrastructure owns:
+40 -59
View File
@@ -1,7 +1,7 @@
# Generated Documentation
**Status:** Generator scaffold in place; renderer and publishing removed
**Date:** 2026-07-28 (revised 2026-09-12)
**Status:** Data generation lives here; rendering and publishing live in the external Astro website
**Date:** 2026-07-28 (revised 2026-09-25)
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
## Purpose
@@ -10,11 +10,10 @@ Archie's documentation-generation approach is:
- production Go code, registries, configuration, and CLI behaviour remain the
source of truth for published contracts;
- a repository-local Go generator extracts and normalizes documentation data;
- a repository-local Go generator extracts and normalises documentation data;
- the generator writes deterministic JSON/data files and protocol schemas;
- the rendering and publishing surface is an **open decision** — the VitePress
site and its Pages deployment were removed on 2026-09-12 as an unnecessary
build step (see "Rendering and publishing" below).
- the external Astro website consumes generated data and serves the public
documentation at `offloaded.dev/docs/`.
Hugo is not part of the target architecture.
@@ -32,7 +31,7 @@ docs/
*.md
```
### Rendering and publishing — OPEN
### Rendering and publishing — external Astro website
Superseded 2026-09-12. The repository previously carried a VitePress site
(`docs/.vitepress/config.mts`, `docs/package.json`, a 1620-line
@@ -41,24 +40,23 @@ Pages by `.github/workflows/docs.yml`. It was removed as an unnecessary build
step: the published site was never stood up, and the Pages target is not
configured.
`docs/` is now repository documentation only — markdown read in the repository,
an editor, or a forge's file view. Nothing in the repository builds, renders, or
publishes it.
The Astro website is maintained outside this repository. This repository owns
the Markdown source and generated JSON artifacts; it does not build, preview, or
deploy the site. The external site owns page rendering, navigation, and
publishing.
The renderer for the generated `data/generated/*.json` is therefore **undecided**.
Consequences that follow, and their current state:
The current boundaries are:
| Concern | State after removal |
| --- | --- |
| Reference-page rendering | Undecided; `data/generated/contracts.json` is committed but unrendered |
| Internal link validation | Not enforced by any build; links are repository-relative (`../architecture/...`) and resolve on the filesystem |
| Generated-data drift detection | Unchanged — `docsgen check` compares committed output, independent of any renderer |
| Navigation/sidebar | The authoritative index is `docs/prds/01-project-management.md` |
| Local authoring server | None; read markdown directly |
| Concern | Owner |
| --------------------------------------- | -------------------------------------------------------------------- |
| Reference-page rendering and publishing | External Astro website |
| Documentation source and generated data | This repository |
| Generated-data drift detection | `task docs:check`, `task docs:artifact:check`, and `task news:check` |
| Navigation data | `docs/data/generated/docs.json` and `dev-docs.json` |
A future renderer MUST NOT reintroduce a dead-link-blind build: VitePress
previously validated internal links during its production build, and no
replacement currently does.
Changes to an artifact contract must be coordinated with the external Astro
consumer. This repository does not validate the website's rendered links or
routes.
## Single source of truth
@@ -107,7 +105,7 @@ load registries and types
-> compare or write output
```
The normalized documentation model prevents each output renderer from
The normalised documentation model prevents each output renderer from
independently interpreting Go types. It contains stable documentation IDs,
owners, names, descriptions, source references, versions, deprecations, fields,
defaults, validation, secret classifications, and relationships.
@@ -121,13 +119,13 @@ docsgen all
docsgen check
```
- `data` writes the normalized JSON reference data.
- `data` writes the normalised JSON reference data.
- `asyncapi` writes protocol schemas and envelopes.
- `all` generates every committed artifact.
- `check` generates into a temporary directory and fails on drift.
The command may use subcommands or an equivalent explicit `--target` flag. It
MUST retain one normalization and validation path.
MUST retain one normalisation and validation path.
## Target output
@@ -197,7 +195,7 @@ Keep generator-only dependencies such as `invopop/jsonschema` and any future
protocol-schema serializer in the nested tools module. They MUST NOT enter the
root module.
`docsgen` imports Archie-owned contracts and writes normalized Archie data and
`docsgen` imports Archie-owned contracts and writes normalised Archie data and
protocol artifacts.
### Step 2: establish authoritative registries
@@ -280,26 +278,24 @@ Each category extractor contributes:
- version and deprecation information;
- relationships to commands, events, policies, and contracts.
The first vertical slice proves the normalized model and deterministic JSON
serialization. Later categories reuse it rather than introducing
The first vertical slice proves the normalised model and deterministic JSON
serialisation. Later categories reuse it rather than introducing
category-specific ad hoc output formats.
### Step 5: render data (pending renderer decision)
### Step 5: external Astro renderer
Blocks on "Rendering and publishing" above. Once a renderer is chosen, it reads
`data/generated/*.json`, validates it, and renders reference views.
The Astro website reads `data/generated/*.json`, validates it, and renders
reference views. Build and deployment remain owned by the website repository.
Navigation and routes derive from `catalog.json`; they MUST NOT be duplicated by
hand in renderer configuration.
No renderer is chosen, so this step is unstarted.
### Step 6: implement deterministic drift checking
`docsgen check`:
1. generates all artifacts into a temporary directory;
2. normalizes line endings and file modes;
2. normalises line endings and file modes;
3. compares the complete expected data and schema trees with committed outputs;
4. reports missing, changed, and obsolete files;
5. identifies the authoritative definition associated with each mismatch;
@@ -315,11 +311,11 @@ Generation MUST exclude:
Two consecutive `docsgen all` runs MUST be byte-identical.
### Step 7: renderer adaptation — blocked
### Step 7: Astro renderer — external consumer
Was "adapt the VitePress site". No renderer is chosen; this step is unstarted.
When a renderer is selected it MUST:
The external Astro website consumes the committed generated JSON artifacts and
serves the documentation under `/docs/` and `/dev/`. Its build and deployment
are owned by that repository. The consumer MUST:
- read `data/generated/*.json` rather than re-deriving from source;
- validate internal links, with dead-link failures enabled (no blanket
@@ -353,30 +349,15 @@ contract types (`docsgen`) and, from the Markdown sources, `docs.json` and
reader of the product gets, and the development set of architecture and design
records) -- see `task docs:artifact`.
### Step 9: CI
### Step 9: validation and CI
The original documentation workflow was deleted on 2026-09-12. `deploy.yml` still
does not reference `docs/**`.
`task check` validates generated contracts and Markdown-derived documentation
artifacts. The Astro site's rendered routes and deployment are validated in its
own repository.
`.github/workflows/docs.yml` (added 2026-09-18) builds the MkDocs site with
`mkdocs build --strict` on changes to `docs/**` or `mkdocs.yml`, so a dead
internal link fails before it reaches a deploy. It deliberately does no more
than that: it does not run `docsgen`, does not regenerate `contracts.json`, and
does not publish. Deployment is a separate path, run from the Ansible control
node by the `vectislabs.automation` `docs_site` role.
### Step 10: content migration
Generated-artifact drift is therefore still gated locally, by `task check`
running `docs:check`, and not in CI. That split is the point. A CI job that
regenerated output would be able to paper over uncommitted differences instead
of failing on them, which is the failure this section exists to prevent, so any
future documentation workflow MUST check generated output rather than produce
it.
### Step 10: cutover — done, in reverse
The site cutover is moot: the site was removed rather than published. The
generator's outputs (`docs/data/generated/`, `docs/public/schemas/`) remain
committed and are the durable artifacts.
The Astro site consumes generated artifacts. Remaining content work is to:
Still standing from the original cutover list:
+5 -7
View File
@@ -82,8 +82,7 @@ external account MUST NOT change ownership or historical attribution.
Secret-bearing channel bindings remain configuration concerns rather than
identity data. In particular, `[chat.telegram].token` is a
`secret.SecretRef` resolved by the application through the configured secret
registry; the older `token_env` field remains a compatibility fallback. Neither
form changes the identity that owns or performs a chat action.
registry. It does not change the identity that owns or performs a chat action.
## Persistence
@@ -211,7 +210,7 @@ recovery protocol.
Identity is not authentication and is not access control.
The current architecture does not require authentication or authorization. Those
The current architecture does not require authentication or authorisation. Those
capabilities MAY be introduced later if deployment or product needs justify
them. They MUST remain separate from the identity model.
@@ -276,8 +275,7 @@ separately. Until a surface carries both, the verbs stay withheld. This is the
reason the four verbs are absent from the dashboard's in-browser tools, and it is
why releasing them is a change to this boundary rather than a change to the tools.
The current implementation uses identity equality as an authorization check for
The current implementation uses identity equality as an authorisation check for
chat task approval and cancellation. This conflicts with the approved rule that
identity is attribution rather than authentication or access control and must be
reassigned to an appropriate task-ownership or future access policy.
@@ -293,7 +291,7 @@ Focused tests verify that:
## Current hazards
- SQLite task uniqueness is `(owner, repo, issue_number)` and excludes identity.
- Task uniqueness is `(owner, repo, issue_number)` and excludes identity.
Two identities discovering the same forge issue cannot own distinct task
records.
- NATS deduplication uses `owner/repo/issue` and excludes identity, so discovery
@@ -330,7 +328,7 @@ Editable without a rebuild.
`Persona` field of `SystemPromptConfig` (`internal/gateway/prompt.go`) into a
`<soul purpose="identity_and_style" trust="data">` block, XML-escaped through
the same `xml` template helper used for tool and env metadata, and placed
*before* `<instruction_precedence>` in `archie.md.tpl`. Escaping means SOUL
_before_ `<instruction_precedence>` in `archie.md.tpl`. Escaping means SOUL
text can never forge a live `<core_rules>`, `<instruction_precedence>`,
`<tools>` or `<env>` tag -- an attempt renders as inert escaped text
(`&lt;core_rules&gt;...`), and `<instruction_precedence>` explicitly tells the
@@ -51,7 +51,7 @@ conversation or memory context is loaded. Sharing an Agent MUST NOT implicitly
share one user's private memory with another user.
An interaction may assemble memory from four scopes: global shared, the selected
Agent's agent-wide memory, the initiating user's authorized user-wide memory,
Agent's agent-wide memory, the initiating user's authorised user-wide memory,
and the private Agent-user relationship memory addressed by both IDs.
## Conversation identity
@@ -104,7 +104,7 @@ The canonical session and message implementation must supply:
metadata;
- session lifecycle and active-request state;
- session-to-agent-instance and parent-session lineage;
- durable SQLite round trips and timestamp validation.
- durable database round trips and timestamp validation.
These semantics must use the confirmed Agent, user, channel-binding, and
conversation ownership model.
@@ -264,7 +264,7 @@ queued.
delivery source, so a webhook-delivered issue and a later poll of the same
issue dedup through `PublishUnique` instead of double-enqueuing.
- Chat-spawned and playbook-binding-dispatched work enqueues through
`EnqueueChatTask`/`EnqueueBindingTask` (`internal/store`), stamped with
`EnqueueChatTask`/`EnqueueBindingTask` (`internal/infrastructure/postgres`), stamped with
`binding_id`/`binding_version` for provenance.
Webhook intake is opt-in per deployment (`Forge.Intake` = `poll` (default),
@@ -287,7 +287,7 @@ model and its threat model are `docs/architecture/bindings.md`.
the Agent System.
- Source identity is incomplete: sessions use configured bot usernames, tasks
use identity strings, and external message IDs are generally absent.
- SQLite and NATS deduplication are based on forge coordinates rather than a
- Database and NATS deduplication are based on forge coordinates rather than a
channel-neutral source-message reference.
- Replies and acknowledgements have no durable delivery-attempt lifecycle, so
partial success and retry behaviour differ by adapter.
@@ -316,7 +316,7 @@ model and its threat model are `docs/architecture/bindings.md`.
Semantic/vector search over chat messages is an **explicit non-goal** until usage
data shows a real need.
Message search is lexical only: session-scoped SQLite FTS5 queries paged via
Message search is lexical only: session-scoped PostgreSQL full-text queries paged via
`MessageQuery{Query,Limit,Offset}` → `MessagePage`. Do not add embeddings
configuration or vector columns to message records.
+37 -35
View File
@@ -114,7 +114,7 @@ memory, curator, workflow, forge, and Gateway runtime values. The target owner
is a standalone UI application process; `internal/webui` remains its HTTP
transport adapter, while Gateway, State Store, configuration, Work Intake,
Messaging, and other capability owners expose the contracts behind those
routes. The migration preserves retained route schemas, auth/CSRF behavior,
routes. The migration preserves retained route schemas, auth/CSRF behaviour,
task/capture/mapping/binding/session continuity, SSE replay semantics, and
committed generated SPA assets. Prerequisites are the ratified UI boundary,
route-owner inventory, narrow remote adapters, configuration/auth/readiness
@@ -182,8 +182,8 @@ the chat service's session-store RPCs and is proven by
`TestStoreClientPreservesCanonicalRecords`. It is deliberately unwired.
Production `archied` dials the standalone gateway for `ChatContract` only
(`composeChatContract` → `gatewayrpc.Dial` returns a `*Client`, not a
`*StoreClient`), and the daemon's session store is in-process SQLite via
`makeTelegramSessionStore`. The test comment that says it mirrors production
`*StoreClient`), and the Gateway's session store is PostgreSQL via
`gateway.NewPostgresSessionStore`. The test comment that says it mirrors production
describes the target, not today's tree. Kept rather than deleted because the
migration it serves is deferred by this very section, and re-deriving a tested
wire adapter once that lands is pure cost.
@@ -200,16 +200,16 @@ hold no direct database handles, daemon state, or model runtimes.
satisfy from its own process. Each is resolved by where the fact it needs is
actually owned, not by where it used to be built:
| Seam | Resolution |
|---|---|
| `Version` | Sourced from the Gateway via `ChatSnapshot.Version`. The Messaging Service never stamps or infers a build version; `cmd/archie-messaging` deliberately takes no version ldflags, so it cannot report a partial upgrade as a matched one. |
| `Updates` (`/update`) | Built in the Messaging Service from `[chat.telegram].update_check_command` / `update_install_command` — its own configuration. `Enrich` is dropped: `componentInstallTypeEnricher` reads `[nats]`, which this service must not decode, so the check command's own reported install type stands unmodified. |
| `UpdateReportPath` | A local state file under `work_dir`, keyed by the same `sha256(bot_user)[:8]` scheme the daemon used, so a pending report is found rather than written afresh. |
| `ReleaseAnnouncements` | **Deliberately left nil**, for the same reason as `RunningVersions`. `releaseannounce.Announcer` announces nothing unless each `Component` carries a parseable version, and the only versions this service can obtain are the Gateway's own build stamps, not archied's. Wiring the announcer without them yields a no-op that reads as configured, so it stays unwired until component self-reporting exists. |
| `SetShowToolCalls` | Projected from `[chat].show_tool_calls`. |
| `Reload` | Local: re-resolves the token and allowlist from this service's own config file and overlay. Reload was never a daemon fact. |
| `RunningVersions` | **Deliberately left nil.** It exists to turn an installer's claim into a checked one, and only a component's own compiled-in build can vouch for it. The Messaging Service knows neither archied's build nor the observed archie-agent version (`daemon.AgentStatus`), and the Gateway's own `gatewayVersion` is a different binary's stamp — reporting it as the daemon's would manufacture exactly the false success the check exists to catch. Update reports therefore relay as unverified claims until a component self-report contract exists. |
| `Dangerous` | Stays nil. No daemon composition ever set it; `/rollback` and `/stop` reported "not configured" before the extraction and still do. |
| Seam | Resolution |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Version` | Sourced from the Gateway via `ChatSnapshot.Version`. The Messaging Service never stamps or infers a build version; `cmd/archie-messaging` deliberately takes no version ldflags, so it cannot report a partial upgrade as a matched one. |
| `Updates` (`/update`) | Built in the Messaging Service from `[chat.telegram].update_check_command` / `update_install_command` — its own configuration. `Enrich` is dropped: `componentInstallTypeEnricher` reads `[nats]`, which this service must not decode, so the check command's own reported install type stands unmodified. |
| `UpdateReportPath` | A local state file under `work_dir`, keyed by the same `sha256(bot_user)[:8]` scheme the daemon used, so a pending report is found rather than written afresh. |
| `ReleaseAnnouncements` | **Deliberately left nil**, for the same reason as `RunningVersions`. `releaseannounce.Announcer` announces nothing unless each `Component` carries a parseable version, and the only versions this service can obtain are the Gateway's own build stamps, not archied's. Wiring the announcer without them yields a no-op that reads as configured, so it stays unwired until component self-reporting exists. |
| `SetShowToolCalls` | Projected from `[chat].show_tool_calls`. |
| `Reload` | Local: re-resolves the token and allowlist from this service's own config file and overlay. Reload was never a daemon fact. |
| `RunningVersions` | **Deliberately left nil.** It exists to turn an installer's claim into a checked one, and only a component's own compiled-in build can vouch for it. The Messaging Service knows neither archied's build nor the observed archie-agent version (`daemon.AgentStatus`), and the Gateway's own `gatewayVersion` is a different binary's stamp — reporting it as the daemon's would manufacture exactly the false success the check exists to catch. Update reports therefore relay as unverified claims until a component self-report contract exists. |
| `Dangerous` | Stays nil. No daemon composition ever set it; `/rollback` and `/stop` reported "not configured" before the extraction and still do. |
The Messaging Service consequently reads `work_dir`, `bot_user`, `[chat]` and
`[health]` in addition to the PRD's `[chat.*]` / `[services.gateway]` list.
@@ -221,14 +221,17 @@ prohibition list is untouched.
not cover (2026-09-22, `archie-core-1ng1`).** The PRD's deletion gate cannot
pass today. `cmd/archie-messaging/architecture_test.go` does not exist, and the
check that section specifies -- `go list -deps ./cmd/archie-messaging` links
zero banned runtime packages -- reports four:
zero banned runtime packages -- reported four at the time (the task store was
then `internal/store` over `modernc.org/sqlite`; the gate now bans
`modernc.org/sqlite`, `github.com/jackc/pgx` and
`internal/infrastructure/postgres` in its place):
| banned package | PRD category |
| --- | --- |
| `modernc.org/sqlite` | State Store |
| `internal/store` | State Store |
| `internal/domain/workflow` | Workflow engine |
| `internal/agentexec` | Workflow engine, via `internal/domain/workflow/agent.go` |
| banned package | PRD category |
| -------------------------- | -------------------------------------------------------- |
| `modernc.org/sqlite` | State Store |
| `internal/store` | State Store |
| `internal/domain/workflow` | Workflow engine |
| `internal/agentexec` | Workflow engine, via `internal/domain/workflow/agent.go` |
All four arrive through one import: `internal/app/archiemessaging/run.go`
imports `internal/app/controlplane`, whose own dependency set is exactly those
@@ -291,7 +294,7 @@ originally left are answered, in both cases by measuring rather than by preferen
- The client did NOT become two packages. `WatchWorkflowExecutionSettings` and
`WatchPersonas` stayed on `internal/app/controlplane`'s `Client`, which now
*embeds* the new one, so the daemon's validated watch is still defined once and
_embeds_ the new one, so the daemon's validated watch is still defined once and
the read path still has one implementation -- which is what the second package
was for -- with one fewer package to keep in step.
- The schedules and workflow documents stayed put, and
@@ -407,7 +410,8 @@ The migration must decide:
- Workflow definition and version persistence;
- the smallest accepted-work-request contract consumed from Work Intake;
- the enforced WorkflowExecution state machine;
- the enforced WorkflowExecution state machine (proposed in
`docs/prds/execution-tree-state-machine.md`);
- atomic state and domain-event persistence;
- migration of existing task rows and transition history;
- disposition of current skill, Yaegi, and stage-plugin implementations;
@@ -470,7 +474,7 @@ memory model in general or a future non-file engine's model:
sidesteps collisions from identities that differ only in characters a
filesystem treats as equivalent.
- **Record ID:** assigned once at `Write`, independent of content, so a later
edit elsewhere in the file can never orphan a `Forget`. Realized as a
edit elsewhere in the file can never orphan a `Forget`. Realised as a
leading marker line (`<!--mem:<ulid>-->`) on the block `builtin.Store.Add`
writes; `Query`/`List` strip it back out of `Record.Content` before
returning, and `Forget(id)` locates the block by that unique marker via the
@@ -558,7 +562,7 @@ Store contracts and does not receive `config.Holder`, daemon pointers, SQL or
store implementations, workflow registries, forge/channel/model runtimes, or
resolved secrets. The current `internal/webui` implementation remains inside
`archied` until the ratified migration gates prove route parity, adapter
selection, failure/readiness behavior, and deletion of the shared-holder and
selection, failure/readiness behaviour, and deletion of the shared-holder and
direct-access paths. The extraction cutover removes the in-process UI
listener in the same change; there is no dual-live UI authority.
@@ -577,9 +581,9 @@ viewer count, and `Broadcast` is a no-op when nobody is watching.
Three properties make the cursor sufficient, and a push hub unnecessary:
- **The cursor cannot skip.** `internal/store/store.go` opens the database with
`SetMaxOpenConns(1)`, so writes serialise and a row's `id` is assigned in
commit order. There is no window in which a lower id becomes visible after a
- **The cursor cannot skip.** `internal/infrastructure/postgres` takes an
advisory event-append lock around each insert (`TestEventInsertsCommitInIDOrder`),
so a row's `id` is assigned in commit order. There is no window in which a lower id becomes visible after a
higher one, which is the failure mode that normally rules out polling an
autoincrement cursor. SSE catch-up already depends on this same property.
- **A broadcast is a wakeup, not the payload.** `sseStream.drain` treats each
@@ -592,7 +596,7 @@ Three properties make the cursor sufficient, and a push hub unnecessary:
- **The table is the only complete fan-out point.** Events reach the store
through several paths that never touch the daemon's bus, including the
audit event `store.ArchiveTask` writes inside its transaction
(`internal/store/store.go`) and the binding-dispatch failure
(`internal/infrastructure/postgres/store.go`) and the binding-dispatch failure
`internal/daemon/daemon.go` inserts directly. A push hub would have to be
hooked at every write site and at post-commit, and would silently miss any
site added later that forgets to notify. Reading the table misses nothing.
@@ -705,12 +709,11 @@ These shared mechanisms do not acquire ownership of domain meaning. Domains
continue to own their commands, events, policies, settings, and consequences.
The Go documentation generator, its output placement, and drift checking are
defined in `generated-documentation.md`. The VitePress site and its Pages
deployment were removed on 2026-09-12 as an unnecessary build step; `docs/` is
repository documentation only. The rendering and publishing surface is an open
decision, and so are the renderer's page templates and any developer commands
or CI sequence that would accompany one. Adapting the generator and implementing
Archie's normalized documentation model remain migration work rather than open
defined in `generated-documentation.md`. The external Astro website consumes
the committed documentation and release JSON artifacts and serves them under
`offloaded.dev/docs/`. This repository owns the source and artifact checks; the
website repository owns rendering and deployment. The generators and
Archie's normalised documentation model remain migration work rather than open
product architecture.
**Amended 2026-09-15.** `internal/infrastructure/servicediscovery/nats`
@@ -739,7 +742,6 @@ The final migration plan must order:
Each legacy package requires objective removal criteria. No compatibility path
may become an indefinite second implementation.
## Completion criteria
Migration design is complete when:
+19 -21
View File
@@ -32,15 +32,15 @@ that container did:
`Summary`/`Detail` — no step-by-step transcript (tool calls, durations,
errors). There is no transcript to recover even in principle.
5. **`agentexec.SubjectForSystem`** is documented as the return channel for
exactly this — *"log dumps, health, and PII warnings... the daemon reads
these for observability and never forwards them"* — but has no publisher
exactly this — _"log dumps, health, and PII warnings... the daemon reads
these for observability and never forwards them"_ — but has no publisher
and no consumer anywhere in the codebase except a subject-format
assertion in `nats_test.go`. The designed return path was never wired.
The practical consequence: a task parks with
`stage baseline: baseline red -- go build ./... fails and builder could not
auto-fix (status: parked)` and there is no way — not from the dashboard, not
from Telegram chat, not by SSH'ing into the deployment host — to see *why*
from Telegram chat, not by SSH'ing into the deployment host — to see _why_
`go build` failed. The container that knew is already gone.
This matters beyond debugging convenience: supported deployments can combine
@@ -149,8 +149,8 @@ additions. So is the read half: the three per-attempt endpoints
that consumes them. The decision record, the rejected alternatives and the honest
limits are `docs/prds/task-run-detail.md`.
The task log surface above answers *why did this park?*. This surface answers
*what did this run actually do?*, per attempt.
The task log surface above answers _why did this park?_. This surface answers
_what did this run actually do?_, per attempt.
### Attempt attribution
@@ -165,11 +165,9 @@ would have to guess which side of a boundary an event belongs to across a daemon
restart, a stale-run recovery, or two interleaved attempts, and a guess rendered
as structure is exactly the false fidelity this surface exists to avoid.
The column reaches an existing database through the presence-gated arm in
`internal/store`'s `migrateTasks` — `eventsSchema` is `CREATE TABLE IF NOT
EXISTS`, so on an existing database the migrator is the *only* thing that adds
it. `PRAGMA user_version` is unchanged because the loop is presence-gated
rather than version-gated, and nothing is backfilled.
The column is part of the events table in
`internal/infrastructure/postgres/migrations/0001_state_store.sql`, and nothing
is backfilled.
### Read surface
@@ -207,15 +205,15 @@ the task's current attempt, and the resolved attempt is echoed in the response.
`stage_start` and `stage_finish` are the only inputs, so the derivation is
explicit and each case is pinned by a test:
| Events seen for the stage | Reported |
| --- | --- |
| `stage_finish` with `data.error` | `failed`, with the error text |
| `stage_finish` with `data.interrupted` | `interrupted` |
| `stage_finish`, neither | `ok` — "returned without error" |
| `stage_start` unmatched, and this is the task's current in-flight attempt | `running` |
| `stage_start` unmatched on any dead attempt | `interrupted` — the run ended without finishing it |
| `stage_finish` with no matching start | the stage, with no start time invented |
| no stage information at all for that attempt | `unknown` |
| Events seen for the stage | Reported |
| ------------------------------------------------------------------------- | -------------------------------------------------- |
| `stage_finish` with `data.error` | `failed`, with the error text |
| `stage_finish` with `data.interrupted` | `interrupted` |
| `stage_finish`, neither | `ok` — "returned without error" |
| `stage_start` unmatched, and this is the task's current in-flight attempt | `running` |
| `stage_start` unmatched on any dead attempt | `interrupted` — the run ended without finishing it |
| `stage_finish` with no matching start | the stage, with no start time invented |
| no stage information at all for that attempt | `unknown` |
**There is no exit code.** `stage_finish` carries a duration and an optional
error string and nothing else, so no stage can be shown as pass/fail and the
@@ -310,8 +308,8 @@ attempt".
Every part is additive. A capture or a configuration emit that cannot happen
leaves the run alone — reporting must never park a task. Reverting the change
set removes the endpoints and the page; the extra column and the extra event
kinds are inert to the previous revision (SQLite ignores a column no statement
names, and an unfamiliar event kind already renders as unfamiliar), and there is
kinds are inert to the previous revision (a column no statement names is
ignored, and an unfamiliar event kind already renders as unfamiliar), and there is
no data transformation to undo.
## Dependency direction
+16 -16
View File
@@ -38,22 +38,22 @@ design questions.
Each package review records:
| Decision | Required result |
|---|---|
| Owned behaviour | The cohesive job the code performs |
| Domain ownership | The owner of the behaviour and vocabulary |
| Final location | Its target path |
| Public contracts | The smallest interfaces, commands, and events exposed |
| Required services | Domain-defined interfaces implemented by infrastructure |
| State ownership | The owner of each mutable record and transition |
| Dependencies | Allowed imports and dependencies to remove |
| Duplication | Code to consolidate, delete, or keep separate |
| Plugin status | Core domain, shared contract, infrastructure, plugin, or extra |
| Process boundary | In-process, or the concrete reason for isolation |
| Configuration | Settings owned by the domain or plugin |
| Policy | Definitions, evaluators, consequences, and shared mechanics used |
| Documentation | Authoritative definitions and generated reference |
| Migration constraints | Behaviour and data that must remain correct |
| Decision | Required result |
| --------------------- | ---------------------------------------------------------------- |
| Owned behaviour | The cohesive job the code performs |
| Domain ownership | The owner of the behaviour and vocabulary |
| Final location | Its target path |
| Public contracts | The smallest interfaces, commands, and events exposed |
| Required services | Domain-defined interfaces implemented by infrastructure |
| State ownership | The owner of each mutable record and transition |
| Dependencies | Allowed imports and dependencies to remove |
| Duplication | Code to consolidate, delete, or keep separate |
| Plugin status | Core domain, shared contract, infrastructure, plugin, or extra |
| Process boundary | In-process, or the concrete reason for isolation |
| Configuration | Settings owned by the domain or plugin |
| Policy | Definitions, evaluators, consequences, and shared mechanics used |
| Documentation | Authoritative definitions and generated reference |
| Migration constraints | Behaviour and data that must remain correct |
## Interview method
+3 -3
View File
@@ -34,7 +34,7 @@ these invariants:
resolving a secret, delivering a message, or running an agent. A plugin that
only exposes `Name` and `Version` is metadata, not an engine.
2. **Owning family manager.** The capability package owns a `Registry` or
`Manager` that controls provider registration and discovery, initialization,
`Manager` that controls provider registration and discovery, initialisation,
or access. Providers do not register arbitrary callbacks directly on the
daemon.
3. **Lifecycle and health.** When an implementation owns resources or background
@@ -59,7 +59,7 @@ these invariants:
`internal/plugin/architecture_test.go` enforces the mechanically testable parts
of this rule: the generic plugin method set, the shared agent-instruction
source, and the requirement that engine interfaces have domain behavior plus an
source, and the requirement that engine interfaces have domain behaviour plus an
owning registry or manager.
### Memory engine family
@@ -178,7 +178,7 @@ so it can be picked up without re-deriving the design:
- A `Sampler` implementation behind the same interface as the cheap
strategies; selection deterministic given fixed inputs.
- Algorithm: sample up to a candidate cap; build a k-NN graph over embedding
vectors; row-normalize the adjacency with self-loops; power-iterate to the
vectors; row-normalise the adjacency with self-loops; power-iterate to the
stationary distribution; surprisal = −log(stationary probability of the
nearest point); select the highest-surprisal items.
- Degradation: content without an embedding is skipped; an embedding failure
+2 -2
View File
@@ -6,7 +6,7 @@
## Purpose
Retry limits, authorization, gates, commands, protected paths, tool
Retry limits, authorisation, gates, commands, protected paths, tool
availability, and similar rules define or constrain what Archie may do. They
need consistent consumption, composition, evidence, and audit without erasing
their different domain meanings.
@@ -34,7 +34,7 @@ Each consuming domain owns:
- its evaluators;
- the meaning and consequence of an evaluation.
Access therefore owns principals, resources, actions, and authorization
Access therefore owns principals, resources, actions, and authorisation
consequences. Task lifecycle owns retry eligibility and exhaustion. Task
execution owns gate requirements. Workspace mutation owns protected-path
effects. Tool execution owns tool and command constraints.
+46 -28
View File
@@ -102,17 +102,18 @@ silently oscillate between versions or retry forever.
## Database settings: degrade paths and recovery (2026-09)
The control plane owns runtime-tunable settings and stores them in `archie.db`.
The control plane owns runtime-tunable settings and stores them in the State
Store's PostgreSQL database.
This replaced a dashboard overlay store that degraded to file config on any
failure and had three documented ways back. The replacement has none, and the
posture is the opposite: **the daemon fails closed.**
### Degrade paths
| Failure | Boot behaviour | Where the operator sees it |
| --- | --- | --- |
| State Store unreachable | `boot.loadRuntimeConfig` returns the dial error and `archied` exits non-zero | stderr: `runtime settings unavailable` |
| A stored resource fails validation | Same: `validate database settings` wraps the error and the daemon exits | Same |
| Failure | Boot behaviour | Where the operator sees it |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| State Store unreachable | `boot.loadRuntimeConfig` returns the dial error and `archied` exits non-zero | stderr: `runtime settings unavailable` |
| A stored resource fails validation | Same: `validate database settings` wraps the error and the daemon exits | Same |
| SIGHUP reload with a bad file, or a control plane that cannot be read | Running config is kept; the reload records `last_error` / `last_error_at`. The reload re-applies the database layer, so it never publishes file values over the running database-owned ones | `/api/config` → `reload.last_error` → dashboard banner |
Failing closed is deliberate for settings the database owns: falling back to the
@@ -120,23 +121,35 @@ file values would restore the second source of truth the control plane exists to
remove. The cost is that a bad stored value stops the daemon starting, and the
value can only be corrected through the daemon's own API.
### Serving from Postgres
The State Store, the daemon and the Gateway serve from `database_url` only; an
empty value is a startup error. The embedded NATS store, its endpoint file and
task logs live under `state_dir` (default: the data home's `archie` directory).
The Gateway holds a Postgres serve-ownership claim for its whole life, so a
second Gateway against the same database refuses to start (its turn recovery
would fail the first one's in-flight turns). The State Store holds its own.
### Recovery: offline commands on the State Store
Nothing skips the control plane at boot, and the only writer for a resource is
`ControlPlaneService.Command` on a running State Store -- which is exactly what
the daemon fails closed without. `archie-state-store` therefore carries the
offline recovery commands (`archie-core-6zw0`). They work on the task database
file directly -- the configured `db_path` with `-tasks.sqlite` appended, not
`db_path` itself -- and need neither `archied` nor the Web UI running: `validate`
reads the configuration file the daemon boots with, which is what makes its
verdict the daemon's verdict.
offline recovery commands (`archie-core-6zw0`). They work on the PostgreSQL
database the configuration's `database_url` names
(`internal/app/archied/state_store_recovery_postgres.go`,
`internal/infrastructure/postgres/maintenance.go`) and need neither `archied`
nor the Web UI running: `validate` reads the configuration file the daemon
boots with, which is what makes its verdict the daemon's verdict. One database
backs every service, so the scope is always the whole database.
| Command | What it does | State Store |
| --- | --- | --- |
| `backup -db F -out F` | writes a transactionally consistent snapshot (`VACUUM INTO`), verified as a usable store before it is published | may be running |
| `restore -db F -from F` | replaces the database with a snapshot and drops the replaced file's `-wal`/`-shm` | must be stopped |
| `validate -db F [-config C]` | runs the checks that stop archied starting: the file is readable, uncorrupted and no newer than the binary; every stored resource decodes under the definition that owns it; and `configuration.Validate` accepts the settings the daemon would read -- the stored ones, or the seed the State Store writes for a kind the file does not hold yet -- layered onto `C`, the check the daemon reports as `validate database settings` | may be running |
| `rollback -db F -kind K [-revision N]` | replays an earlier revision of a stored resource through the ordinary replace, recording the rollback as a new revision | must be stopped |
| Command | What it does | Serving processes |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `backup -out F` | runs `pg_dump --format=custom`, reads the archive back with `pg_restore --list` and only then replaces `F` | may be running |
| `restore -from F` | drops tables the snapshot does not hold and runs `pg_restore --clean --single-transaction`; every write made after the snapshot is lost | every one must be stopped |
| `validate [-config C]` | refuses a schema newer than the binary's highest migration; every stored resource decodes under the definition that owns it; and `configuration.Validate` accepts the settings the daemon would read -- the stored ones, or the seed the State Store writes for a kind the database does not hold yet -- layered onto `C`, the check the daemon reports as `validate database settings` | may be running |
| `rollback -kind K [-revision N]` | replays an earlier revision of a stored resource through the ordinary replace, recording the rollback as a new revision | the State Store must be stopped |
The two validation layers `validate` reports are not the same check, and it
reports both rather than merging them: the write path's own decode is stricter
@@ -149,29 +162,34 @@ restoring one is the same replace the dashboard and the channels already use.
The offline command is that operation with the store stopped -- the one state in
which the daemon's own API cannot serve it.
"Must be stopped" is checked rather than assumed. The serving process takes an
exclusive flock on `<db>.lock` for its whole life, and `restore` and `rollback`
refuse with `task database is owned by another process` while another process
holds it. The read-only commands -- `backup` and `validate` -- take no lock and
are meant to run against a serving store: `backup` because the update installer
runs inside the process it is replacing and cannot stop the State Store, and
`validate` because an operator checks a running deployment with it. That
`backup` exemption is only sound while backup never replaces the database, so
naming the database as its own `-out` is refused. `scripts/archie-update-install`
takes its pre-flight snapshot through this subcommand rather than through its
own `sqlite3` shell, so the installer and an operator run one implementation.
"Must be stopped" is checked rather than assumed. Each serving process holds a
Postgres ownership lock for its whole life. `rollback` holds the `state-store`
claim for the replay. `restore` claims every service role's lock (`state-store`
and `gateway`) without waiting and refuses if any is held or the check cannot
complete. The read-only commands -- `backup` and `validate` -- take no claim and
are meant to run against a serving database: `backup` because the update
installer runs inside the process it is replacing and cannot stop the State
Store, and `validate` because an operator checks a running deployment with it.
`scripts/archie-update-install` takes its pre-flight snapshot through this
subcommand, so the installer and an operator run one implementation.
`rollback` is the surgical route back from a bad stored value; `restore` is the
blunt one, and is also the way back from a schema migration a release cannot
grow out of.
There is no automatic schema rollback. goose `Down` drops tables, so it is data
loss, not a rollback. `scripts/archie-update-install` refuses a daemon update
it cannot snapshot first, and on a failed update `scripts/archie-update-watchdog`
rolls the binaries back, leaves the database alone and prints the `restore`
command for the pre-update snapshot. Whether to run it is the operator's call.
## Gateway restart: two constraints learned the hard way
Telegram `/restart` (`internal/channels/telegram/restart.go` plus the `Start`
supervisor loop). Recovered 2026-08-09 from the pre-migration issue tracker.
Both constraints must survive any refactor.
**1. Deadlock.** The `/restart` handler runs *on* the bot instance the supervisor
**1. Deadlock.** The `/restart` handler runs _on_ the bot instance the supervisor
is about to stop. Tearing down inline from the handler deadlocks the restart it
just asked for. So the handler sends on a **buffered** channel (`restartCh`,
capacity 1) and returns immediately; the supervisor loop in `Start` does the
+5 -4
View File
@@ -1,23 +1,24 @@
# archied -- design notes
# archied -- design notes
Archie is a resident daemon that keeps personal projects moving: it polls GitHub for issues labelled
`archie`, works each one in an isolated fresh-clone worktree through a routed **workflow**, and opens a
pull request for human review. Sam reviews and merges; the machine grinds in between.
Guiding principle: **environmental constraints over prompt instructions.** Agents don't get asked nicely
to write good code -- the quality gate (vet/build/test/lint, configurable per repo and per workflow stage)
to write good code -- the quality gate (vet/build/test/lint, configurable per repo and per workflow stage)
refuses to let a run succeed until it passes. The gate mechanics live in `ai-sdk/agentloop`; this repo
owns orchestration only.
## Workflows, not a pipeline
`internal/workflow` is the engine: a Workflow is an ordered list of stages over a shared TaskContext;
stages are deterministic steps (worktree, gate, diff cap, PR, comments -- the shared step library in
stages are deterministic steps (worktree, gate, diff cap, PR, comments -- the shared step library in
`steps.go`) or agent stages (`agentloop.Run` with a stage-specific mission/toolset/gate). Routing is
label-driven (`bug` → tdd, `feature` → feasibility, default → implement), refinable by an LLM triage
stage. Adding a workflow must never require touching the engine or reimplementing steps.
Planned workflows:
- **bootstrap** (registered): deterministic marker-file PR proving invites/clone/push/PR plumbing.
- **implement**: planner (read-only agentloop, plan posted to the issue) → builder (full toolset,
repo gate) → diff cap → PR.
@@ -31,7 +32,7 @@ Planned workflows:
`queued → running(workflow:stage) → waiting_human | pr_open → merged | parked | rejected | closed_wont_do`
SQLite (`internal/store`), WAL, one row per issue with a transitions audit table. Crash recovery:
`running` tasks re-queue on startup with attempt++. Parks are never silent -- every park comments on the
`running` tasks re-queue on startup with attempt++. Parks are never silent -- every park comments on the
issue with the reason and gate output.
## Security posture
+21 -21
View File
@@ -2,7 +2,7 @@
**Author:** Archie
**Date:** 2026-07-21 (implementation status updated 2026-07-22)
**Status:** Final (substantially implemented -- remaining aspirational items are pluggable storage backends and Layer 2 daemon plugin loader)
**Status:** Final (substantially implemented -- remaining aspirational items are pluggable storage backends and Layer 2 daemon plugin loader)
---
@@ -10,22 +10,22 @@
This document describes a target end state. The table below is the ground truth; read it before treating any section as already built.
| Area | Status | What actually exists today (post-e4d11b1) |
|---|---|---|
| Daemon/agent binary split | **Implemented** | `cmd/archied` and `cmd/archie-agent` both exist. `archie-agent` is a 189-line NATS-connected per-task worker that subscribes to task subjects, runs the full multi-stage workflow, and reports results. Workflow routing and sequencing (`workflow.Route`, `workflow.Run`) now run inside the agent, not the daemon. Three agent modes: `inprocess`, `subprocess`, `nats`. |
| Sandbox / "daemon never runs untrusted code" | **Partial** | Default mode is still `inprocess` for development. Docker sandbox mode (`agent.mode = "nats"` + `containers.enabled = true`) runs each task in an ephemeral Docker container with workspace bind-mounted at `/workspace`. `internal/container/pool.go` manages full lifecycle: pull, create, start, release, orphan recovery. Daemon dispatch and container lifecycle both enforce `max_concurrency`; same-repo tasks remain serialized. |
| NATS / JetStream messaging | **Implemented** | `internal/nats/client.go`: JetStream connect, stream creation (WorkQueue retention, file storage), pull consumer (durable, ack-wait 5min, max-deliver 3, dedup by Msg-Id), `PublishTask`, `Fetch`, `NewReplyInbox`, and optional token authentication. Subject hierarchy lives in `internal/nats/subjects.go`; `internal/agentexec/nats.go` implements request/reply agent execution. |
| Docker container sandbox | **Implemented** | `internal/container/pool.go` (210 lines): Docker API client, image pull (always/missing/never), container create with workspace bind mount, start, release (stop+remove), orphan recovery on daemon restart. `Dockerfile` at repo root builds archie-agent fat image. `[containers]` config block: enabled, image, max_concurrency, max_uptime, pull_policy. `agent.mode = "nats"` required when containers enabled. |
| `/data/` volume, `task.json` | **Partial** | `container.WriteTaskJSON()` writes task payload to the worktree before container acquire. The container pool bind-mounts the isolated task worktree at `/data/worktree`; configured repos also receive a persistent `/data/repo` Docker volume. Task payload travels over NATS as the primary channel; `/data/task.json` is a boot-time brief for the container. |
| `[containers]` config block | **Implemented** | `ContainerConfig` struct in config.go: enabled, image, max_concurrency, max_uptime, pull_policy. Validated on load. |
| Yaegi extensibility (gates, custom stages, skill scripts) | **Implemented** | Three surfaces: `.archie/gate.go`, `.archie/stages/*.go`, skill scripts via `run_go_script` tool. All in-process via Yaegi with generated symbol tables and panic recovery. Full detail in `docs/prds/yaegi-plugin-system.md`. |
| Layer 1: skill-bundled plugins | **Implemented** | `skill.DiscoverPlugins()` scans `.agents/skills/<name>/plugins/*.go`. `skill.Plugin.Run()` executes them via Yaegi. `skillbuild.BuildWorkflow()` constructs `workflow.Workflow` from plugin-defined stages. `TaskContext.SkillPlugins` makes them available during stage execution. `skillbuild.BuildRegistry()` replaces the hardcoded `workflow.Registry` with catalog-driven construction -- skills define workflows, plugins define stages. |
| Layer 2: core daemon plugins | **Partial** | `internal/plugin/plugin.go`: `Plugin` interface (`Name()`, `Version()`), `Registry` type, `LoadDir()` using Yaegi to interpret `.go` files. No `~/.config/archie/plugins/` loader wired into `cmd/archied/main.go` yet -- the interface and registry exist but are not connected to the daemon's startup. |
| Skills (agentskills.io spec) | **Implemented** | `internal/skill/skill.go`: parses SKILL.md YAML frontmatter, discovers skills from `.agents/skills/*/SKILL.md`, extracts body. Skills follow `archie-wf-*` naming convention. Progressive disclosure: `Catalog()` (Tier 1 -- frontmatter-only scan, ~100 tokens per entry), `LoadBody()` (Tier 2 -- full body on activation), `Discover()` (Tier 3 -- full parse with plugins). `metadata.archie.workflow` declares skill→workflow affinity. `skill.SkillForWorkflow()` is catalog-driven, no hardcoded maps. `skillbuild.BuildRegistry()` constructs the daemon's workflow registry from the catalog. |
| Worktree/repo management | **Implemented** | Each issue keeps an isolated worktree. Repos with `persistent_storage = true` use a per-repo bare Git object cache to avoid repeated full network clones; caches and Archie-owned repo volumes expire via `containers.volume_ttl`. |
| Config schema | **Closer to sec.4** | `[agent]` block: mode (inprocess/subprocess/nats) + command + env. `[nats]` block: url + token_env. `[containers]` block: enabled, image, max_concurrency, max_uptime, volume_ttl, pull_policy. Per-repo `persistent_storage` is supported as a boolean Docker-volume/Git-cache opt-in. |
| Area | Status | What actually exists today (post-e4d11b1) |
| --------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Daemon/agent binary split | **Implemented** | `cmd/archied` and `cmd/archie-agent` both exist. `archie-agent` is a 189-line NATS-connected per-task worker that subscribes to task subjects, runs the full multi-stage workflow, and reports results. Workflow routing and sequencing (`workflow.Route`, `workflow.Run`) now run inside the agent, not the daemon. Three agent modes: `inprocess`, `subprocess`, `nats`. |
| Sandbox / "daemon never runs untrusted code" | **Partial** | Default mode is still `inprocess` for development. Docker sandbox mode (`agent.mode = "nats"` + `containers.enabled = true`) runs each task in an ephemeral Docker container with workspace bind-mounted at `/workspace`. `internal/container/pool.go` manages full lifecycle: pull, create, start, release, orphan recovery. Daemon dispatch and container lifecycle both enforce `max_concurrency`; same-repo tasks remain serialised. |
| NATS / JetStream messaging | **Implemented** | `internal/nats/client.go`: JetStream connect, stream creation (WorkQueue retention, file storage), pull consumer (durable, ack-wait 5min, max-deliver 3, dedup by Msg-Id), `PublishTask`, `Fetch`, `NewReplyInbox`, and optional token authentication. Subject hierarchy lives in `internal/nats/subjects.go`; `internal/agentexec/nats.go` implements request/reply agent execution. |
| Docker container sandbox | **Implemented** | `internal/container/pool.go` (210 lines): Docker API client, image pull (always/missing/never), container create with workspace bind mount, start, release (stop+remove), orphan recovery on daemon restart. `Dockerfile` at repo root builds archie-agent fat image. `[containers]` config block: enabled, image, max_concurrency, max_uptime, pull_policy. `agent.mode = "nats"` required when containers enabled. |
| `/data/` volume, `task.json` | **Partial** | `container.WriteTaskJSON()` writes task payload to the worktree before container acquire. The container pool bind-mounts the isolated task worktree at `/data/worktree`; configured repos also receive a persistent `/data/repo` Docker volume. Task payload travels over NATS as the primary channel; `/data/task.json` is a boot-time brief for the container. |
| `[containers]` config block | **Implemented** | `ContainerConfig` struct in config.go: enabled, image, max_concurrency, max_uptime, pull_policy. Validated on load. |
| Yaegi extensibility (gates, custom stages, skill scripts) | **Implemented** | Three surfaces: `.archie/gate.go`, `.archie/stages/*.go`, skill scripts via `run_go_script` tool. All in-process via Yaegi with generated symbol tables and panic recovery. Full detail in `docs/prds/yaegi-plugin-system.md`. |
| Layer 1: skill-bundled plugins | **Implemented** | `skill.DiscoverPlugins()` scans `.agents/skills/<name>/plugins/*.go`. `skill.Plugin.Run()` executes them via Yaegi. `skillbuild.BuildWorkflow()` constructs `workflow.Workflow` from plugin-defined stages. `TaskContext.SkillPlugins` makes them available during stage execution. `skillbuild.BuildRegistry()` replaces the hardcoded `workflow.Registry` with catalogue-driven construction -- skills define workflows, plugins define stages. |
| Layer 2: core daemon plugins | **Partial** | `internal/plugin/plugin.go`: `Plugin` interface (`Name()`, `Version()`), `Registry` type, `LoadDir()` using Yaegi to interpret `.go` files. No `~/.config/archie/plugins/` loader wired into `cmd/archied/main.go` yet -- the interface and registry exist but are not connected to the daemon's startup. |
| Skills (agentskills.io spec) | **Implemented** | `internal/skill/skill.go`: parses SKILL.md YAML frontmatter, discovers skills from `.agents/skills/*/SKILL.md`, extracts body. Skills follow `archie-wf-*` naming convention. Progressive disclosure: `Catalog()` (Tier 1 -- frontmatter-only scan, ~100 tokens per entry), `LoadBody()` (Tier 2 -- full body on activation), `Discover()` (Tier 3 -- full parse with plugins). `metadata.archie.workflow` declares skill→workflow affinity. `skill.SkillForWorkflow()` is catalogue-driven, no hardcoded maps. `skillbuild.BuildRegistry()` constructs the daemon's workflow registry from the catalogue. |
| Worktree/repo management | **Implemented** | Each issue keeps an isolated worktree. Repos with `persistent_storage = true` use a per-repo bare Git object cache to avoid repeated full network clones; caches and Archie-owned repo volumes expire via `containers.volume_ttl`. |
| Config schema | **Closer to sec.4** | `[agent]` block: mode (inprocess/subprocess/nats) + command + env. `[nats]` block: url + token_env. `[containers]` block: enabled, image, max_concurrency, max_uptime, volume_ttl, pull_policy. Per-repo `persistent_storage` is supported as a boolean Docker-volume/Git-cache opt-in. |
**Net read post-1dca419:** Phases 1, 2, and 3 are substantially implemented. NATS, Docker sandbox, skill parsing, skill-bundled plugins (Layer 1), skill progressive disclosure, and catalog-driven workflow construction (`skillbuild.BuildRegistry()`) all landed. The remaining aspirational work is Layer 2 daemon plugin loader (interface exists, not wired), pluggable storage backends, and per-worktree dynamic registry augmentation.
**Net read post-1dca419:** Phases 1, 2, and 3 are substantially implemented. NATS, Docker sandbox, skill parsing, skill-bundled plugins (Layer 1), skill progressive disclosure, and catalogue-driven workflow construction (`skillbuild.BuildRegistry()`) all landed. The remaining aspirational work is Layer 2 daemon plugin loader (interface exists, not wired), pluggable storage backends, and per-worktree dynamic registry augmentation.
---
@@ -313,7 +313,7 @@ metadata:
Per the agentskills.io spec:
1. **Catalog** (~100 tokens): `name` + `description` loaded at workflow start
1. **Catalogue** (~100 tokens): `name` + `description` loaded at workflow start
2. **Instructions** (<5000 tokens): Full `SKILL.md` body when the skill is activated
3. **Resources** (as needed): References, scripts, and bundled plugins loaded on demand
@@ -453,7 +453,7 @@ The agent writes whatever it wants to `response`. The daemon reviews it. No agen
- ~~Persistent volumes with TTL~~ -- **done**: configured repos receive a persistent Docker volume plus a per-repo Git
object cache; both are automatically reaped using `containers.volume_ttl`.
- ~~`max_concurrency` enforcement~~ -- **done**: SQLite and NATS drains dispatch different repositories concurrently
up to `[containers].max_concurrency`; same-repo tasks remain serialized by default.
up to `[containers].max_concurrency`; same-repo tasks remain serialised by default.
- Grace period `max_uptime` -- not started
- **Groundwork already in place:** `agentexec.Runner` (`InProcessRunner`/`SubprocessRunner`) is an interface designed,
per its own doc comments, to be swapped for a container-backed runner without touching workflow orchestration --
@@ -504,9 +504,9 @@ The agent writes whatever it wants to `response`. The daemon reviews it. No agen
lifetime with `max_total_uptime` (e.g. 4 hours) to prevent infinite hanging. `max_uptime` = grace after inactivity,
`max_total_uptime` = absolute kill switch.
5. **Concurrent agents on the same repo:** ~~Resolved.~~ Serialized by default (dispatcher chains tasks per
5. **Concurrent agents on the same repo:** ~~Resolved.~~ Serialised by default (dispatcher chains tasks per
`owner/repo`). `[[repos]]` now supports `allow_concurrent = true` (`config.Repo.AllowConcurrent`) to opt a repo out
of that serialization; the global `[containers].max_concurrency` slot limit still applies. Worktrees are already
of that serialisation; the global `[containers].max_concurrency` slot limit still applies. Worktrees are already
keyed per issue number (`worktree.Manager.Dir`), so opted-in repos don't collide on disk.
6. **Plugin architecture reconciliation:** Extend the existing Yaegi surfaces (`internal/gate/gateeval`,
@@ -515,5 +515,5 @@ The agent writes whatever it wants to `response`. The daemon reviews it. No agen
3/4.
7. **Skill loading scope:** "Parse frontmatter, inject body into system prompt" is sufficient for v2. The gap is that
nothing reads SKILL.md today -- closing that gap is the value. Full progressive disclosure (catalog -> activate ->
nothing reads SKILL.md today -- closing that gap is the value. Full progressive disclosure (catalogue -> activate ->
resources) is deferred to a later phase.
+46 -37
View File
@@ -1,4 +1,4 @@
# archie-core Skills System -- PRD
# archie-core Skills System -- PRD
**Author:** Archie
**Date:** 2026-07-18
@@ -41,15 +41,15 @@ project:
# How archie-core connects to this project
connection:
interfaces:
- github # respond to assigned issues
- linear # respond to labelled tickets
- webhook # respond to HTTP POSTs
- github # respond to assigned issues
- linear # respond to labelled tickets
- webhook # respond to HTTP POSTs
github:
repo: sam/my-go-service
issue_labels:
ready: "archie:ready" # issues with this label get claimed
claimed: "archie:claimed" # archie sets this when working
done: "archie:done" # archie sets this after PR
ready: "archie:ready" # issues with this label get claimed
claimed: "archie:claimed" # archie sets this when working
done: "archie:done" # archie sets this after PR
pr:
base: main
draft: false
@@ -57,10 +57,10 @@ connection:
# Skills -- playbooks archie-core loads to know how to work
skills:
paths:
- .archie/skills/ # project-local skills
- ~/.archie/skills/ # per-user skills
- .archie/skills/ # project-local skills
- ~/.archie/skills/ # per-user skills
remotes:
- github.com/sam/archie-skills@v1 # shared skill library
- github.com/sam/archie-skills@v1 # shared skill library
# Sandbox -- what's available in the container
sandbox:
@@ -155,9 +155,11 @@ metadata:
# Go Quality Gate
## When to use
Before committing any Go change. After implementing a feature or fix.
## Procedure
Run in this exact order. If any step fails, fix the issue before continuing.
1. `gofumpt -w .`
@@ -167,28 +169,30 @@ Run in this exact order. If any step fails, fix the issue before continuing.
5. `task deadcode`
## Verification
All five steps must exit 0. If `task deadcode` fails on unrelated packages,
scope it to only changed packages: `golangci-lint run --tests=false --enable-only=unused,staticcheck ./changed/pkg/...`
## Common failures
- `golangci-lint`: unused function -- remove it or add `//nolint:unused` comment
- `go test -race`: data race -- protect with mutex or channel
- `task deadcode`: pre-existing dead code in unrelated package -- scope to changed packages
- `golangci-lint`: unused function -- remove it or add `//nolint:unused` comment
- `go test -race`: data race -- protect with mutex or channel
- `task deadcode`: pre-existing dead code in unrelated package -- scope to changed packages
```
### 2.3 Skill metadata (arcie-specific)
Skills carry archie-specific metadata under `metadata.archie`:
| Field | Purpose |
|---|---|
| `gates` | Which gates from `archie.yaml` this skill covers |
| `tools` | Sandbox tools this skill needs |
| `engine` | Preferred execution engine |
| `model` | Preferred model for this skill |
| `budget_usd` | Max spend ceiling |
| `timeout` | Max seconds |
| `worktree` | Whether to create isolated worktree |
| Field | Purpose |
| ------------ | ------------------------------------------------ |
| `gates` | Which gates from `archie.yaml` this skill covers |
| `tools` | Sandbox tools this skill needs |
| `engine` | Preferred execution engine |
| `model` | Preferred model for this skill |
| `budget_usd` | Max spend ceiling |
| `timeout` | Max seconds |
| `worktree` | Whether to create isolated worktree |
### 2.4 Progressive disclosure
@@ -245,6 +249,7 @@ This is the core loop. When an issue lands with the configured label:
### 3.6 On failure
If any gate fails irrecoverably:
1. Leave issue as `archie:claimed`
2. Comment with exact blocker, failed command, and worktree path
3. Preserve worktree for inspection
@@ -258,12 +263,12 @@ arcie-core can delegate implementation to different LLM engines. The workflow fi
```yaml
engines:
- type: claude # Claude Code CLI -- full agent loop
- type: claude # Claude Code CLI -- full agent loop
model: sonnet
budget_usd: 5.00
- type: codex # OpenAI Codex CLI
- type: codex # OpenAI Codex CLI
model: gpt-5.1-codex-max
- type: raw # Direct LLM -- no agent loop, single prompt
- type: raw # Direct LLM -- no agent loop, single prompt
model: gpt-4o-mini
```
@@ -281,7 +286,7 @@ For skills that need a specific engine, the skill metadata overrides:
```yaml
metadata:
archie:
engine: claude # this skill only works with Claude
engine: claude # this skill only works with Claude
```
---
@@ -312,7 +317,6 @@ metadata:
tools: [docker, trivy]
engine: any
---
## Procedure
1. `trivy image --severity HIGH,CRITICAL <image>`
2. If findings exist, report each CVE with package, version, and fixed version
@@ -323,34 +327,37 @@ metadata:
## 6. Comparison: archie-core vs existing systems
| | archie-core | Claude Code | Codex CLI | GitHub Actions | External Agent |
|---|---|---|---|---|---|
| **How it receives work** | GitHub issue assignment, Linear label, webhook | Chat, slash commands | Chat, slash commands | YAML triggers (push, PR, schedule) | Chat, cron, webhooks |
| **What it does** | Analyse → implement → gate → PR | Analyse → implement → gate → PR | Analyse → implement → gate → PR | Run arbitrary shell commands | Analyse → implement → gate → PR |
| **Skills** | SKILL.md (agentskills.io) | SKILL.md (native) | SKILL.md (agentskills.io) | Composite actions | SKILL.md (native) |
| **Gates** | Named checkpoints in archie.yaml | Ad-hoc (CLAUDE.md + lint) | Ad-hoc | Steps in jobs | Skills with gates |
| **Engine pluggable** | Yes | No (fixed to Claude) | No (fixed to Codex) | No (fixed to GitHub) | Yes (provider config) |
| **Worktree isolation** | Yes | Yes (`--worktree`) | No | No (ephemeral runner) | No |
| **Blueprint/cron** | Export externally | No | No | Schedule trigger | Native |
| **Where it runs** | Docker sandbox | Host | Host or sandbox | GitHub runner | Host, Docker, Modal, SSH |
| | archie-core | Claude Code | Codex CLI | GitHub Actions | External Agent |
| ------------------------ | ---------------------------------------------- | ------------------------------- | ------------------------------- | ---------------------------------- | ------------------------------- |
| **How it receives work** | GitHub issue assignment, Linear label, webhook | Chat, slash commands | Chat, slash commands | YAML triggers (push, PR, schedule) | Chat, cron, webhooks |
| **What it does** | Analyse → implement → gate → PR | Analyse → implement → gate → PR | Analyse → implement → gate → PR | Run arbitrary shell commands | Analyse → implement → gate → PR |
| **Skills** | SKILL.md (agentskills.io) | SKILL.md (native) | SKILL.md (agentskills.io) | Composite actions | SKILL.md (native) |
| **Gates** | Named checkpoints in archie.yaml | Ad-hoc (CLAUDE.md + lint) | Ad-hoc | Steps in jobs | Skills with gates |
| **Engine pluggable** | Yes | No (fixed to Claude) | No (fixed to Codex) | No (fixed to GitHub) | Yes (provider config) |
| **Worktree isolation** | Yes | Yes (`--worktree`) | No | No (ephemeral runner) | No |
| **Blueprint/cron** | Export externally | No | No | Schedule trigger | Native |
| **Where it runs** | Docker sandbox | Host | Host or sandbox | GitHub runner | Host, Docker, Modal, SSH |
---
## 7. Implementation phases
### Phase 1: Workflow file and gates (current MVP)
- `archie.yaml` parser
- Gate runner executing shell commands and checking exit codes
- Skill discovery from project and user paths
- GitHub interface: claim issues, create worktrees, open PRs
### Phase 2: Skills
- SKILL.md progressive disclosure (advertise → activate → resources)
- archie-specific metadata parsing
- Skill chaining: skills that depend on other skills
- `archie skills list/install` CLI
### Phase 3: Engine abstraction
- Engine interface definition
- Claude Code adapter
- Raw LLM adapter
@@ -358,12 +365,14 @@ metadata:
- Per-skill engine preferences
### Phase 4: Advanced features
- Gate overrides per skill
- Skill templates for project scaffolding (`archie init --skill go-service`)
- Remote skill libraries (git repos as skill sources)
- Blueprint export to an external scheduler
### Phase 5: Additional interfaces
- Linear webhook integration
- Generic webhook interface for arbitrary sources
- CLI command interface (`archie run <command>`)
+54 -49
View File
@@ -1,4 +1,4 @@
# archie-core Workflows & Skills -- Product Requirements Document
# archie-core Workflows & Skills -- Product Requirements Document
**Author:** Archie
**Date:** 2026-07-18
@@ -40,20 +40,20 @@ project:
# Available skills (directories or individual files)
skills:
paths:
- .archie/skills/ # project-local skills
- ~/.archie/skills/ # per-user skills
- github.com/org/shared-skills@v1 # remote skill repo
- .archie/skills/ # project-local skills
- ~/.archie/skills/ # per-user skills
- github.com/org/shared-skills@v1 # remote skill repo
skills:
- go-testing # named skill from any path
- go-testing # named skill from any path
- security-audit
# Execution engines in preference order
engines:
- type: claude # Claude Code CLI
- type: claude # Claude Code CLI
model: sonnet
- type: codex # OpenAI Codex
- type: pi # Pi agent harness
- type: raw # Direct LLM without agent wrapper
- type: codex # OpenAI Codex
- type: pi # Pi agent harness
- type: raw # Direct LLM without agent wrapper
# Sandbox definition (what the Docker container provides)
sandbox:
@@ -90,7 +90,7 @@ gates:
description: "No vet warnings"
deadcode:
run: task deadcode
optional: true # non-blocking gate
optional: true # non-blocking gate
description: "Dead code check (advisory)"
# Quality pipeline -- ordered sequence of gate groups
@@ -105,7 +105,7 @@ quality:
# Commit conventions
commit:
format: conventional # conventional commits
format: conventional # conventional commits
signoff: false
template: "feat({scope}): {description}"
@@ -142,15 +142,15 @@ commands:
### 1.3 Design decisions (with rationale)
| Decision | Rationale |
|---|---|
| YAML over TOML/JSON | Already dominant in CI (GitHub Actions, GitLab CI, Taskfile). Human-readable with comments. |
| Single file over multi-file | Task discovery (like `Taskfile.yml`), devcontainer conventions. Avoids directory sprawl. |
| Gates as named checkpoints | GitHub Actions job model. Gates can be composed into quality pipelines, selected individually, or skipped with `--skip`. |
| Engines as ordered preference list | Supports deterministic fallback between available engines. Each engine declares its own tool surface. |
| Skills as paths + references | Matches devcontainer features (paths resolve to directories) and skills.sh (namespaced references). |
| Commands section for direct invocation | Arnie can `archie run test` without an agent turn. Thin wrapper over the sandbox. |
| Quality pipeline groups gates | Pre-commit vs pre-push vs pre-merge distinction. Some gates are required, some advisory. |
| Decision | Rationale |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| YAML over TOML/JSON | Already dominant in CI (GitHub Actions, GitLab CI, Taskfile). Human-readable with comments. |
| Single file over multi-file | Task discovery (like `Taskfile.yml`), devcontainer conventions. Avoids directory sprawl. |
| Gates as named checkpoints | GitHub Actions job model. Gates can be composed into quality pipelines, selected individually, or skipped with `--skip`. |
| Engines as ordered preference list | Supports deterministic fallback between available engines. Each engine declares its own tool surface. |
| Skills as paths + references | Matches devcontainer features (paths resolve to directories) and skills.sh (namespaced references). |
| Commands section for direct invocation | Arnie can `archie run test` without an agent turn. Thin wrapper over the sandbox. |
| Quality pipeline groups gates | Pre-commit vs pre-push vs pre-merge distinction. Some gates are required, some advisory. |
---
@@ -179,9 +179,9 @@ description: >
version: 1.0.0
metadata:
archie:
gates: [test] # gates this skill requires
tools: [go, golangci-lint] # sandbox tools it needs
engine: any # engine preference
gates: [test] # gates this skill requires
tools: [go, golangci-lint] # sandbox tools it needs
engine: any # engine preference
compatibility: Requires Go 1.22+
---
```
@@ -201,13 +201,13 @@ Skills can carry archie-specific frontmatter under `metadata.archie`:
```yaml
metadata:
archie:
gates: [test, lint] # must-pass gates before skill runs
tools: [go, docker] # sandbox tools required
engine: any # preferred engine
model: gpt-4o # preferred model
budget_usd: 2.00 # max spend ceiling
timeout: 600 # max seconds
worktree: true # create isolated worktree
gates: [test, lint] # must-pass gates before skill runs
tools: [go, docker] # sandbox tools required
engine: any # preferred engine
model: gpt-4o # preferred model
budget_usd: 2.00 # max spend ceiling
timeout: 600 # max seconds
worktree: true # create isolated worktree
```
### 2.4 Skill sources (inspired by devcontainer features + Dagger modules)
@@ -241,12 +241,12 @@ Engine interface:
### 3.2 Supported engines
| Engine | Type | What it provides |
|---|---|---|
| `claude` | Claude Code CLI | Full agent loop, tool use, worktrees, subagents |
| `codex` | OpenAI Codex CLI | Agentic coding with sandbox |
| `pi` | Pi agent harness | Minimalist coding agent, stdio protocol |
| `raw` | Direct LLM call | Single-turn prompt, no agent loop. For simple scripts. |
| Engine | Type | What it provides |
| -------- | ---------------- | ------------------------------------------------------ |
| `claude` | Claude Code CLI | Full agent loop, tool use, worktrees, subagents |
| `codex` | OpenAI Codex CLI | Agentic coding with sandbox |
| `pi` | Pi agent harness | Minimalist coding agent, stdio protocol |
| `raw` | Direct LLM call | Single-turn prompt, no agent loop. For simple scripts. |
### 3.3 Engine selection logic
@@ -302,15 +302,15 @@ metadata:
archie:
gates:
test:
run: go test -short ./... # override: faster test for this skill
lint: skip # skip lint for this skill
run: go test -short ./... # override: faster test for this skill
lint: skip # skip lint for this skill
```
Three override modes: `override` (replace command), `skip` (omit gate), `add` (add new gate requirement).
### 4.4 Skill templates (scaffolding)
Skills can carry an `assets/` directory with templates. When archie-core initializes a new project, it can apply skill templates:
Skills can carry an `assets/` directory with templates. When archie-core initialises a new project, it can apply skill templates:
```
skill-name/
@@ -342,45 +342,50 @@ The export produces a `SKILL.md` with scheduler metadata. The blueprint's prompt
## 5. Comparison to Existing Systems
| Feature | archie-core | GitHub Actions | Dagger | Taskfile | devcontainer | External Skills |
|---|---|---|---|---|---|---|
| Language | YAML | YAML | Go/Python/TS | YAML | JSON | Markdown |
| Gates | Named + composable | Steps in jobs | Functions | Tasks | Lifecycle scripts | N/A |
| Engine abstraction | First-class | GitHub only | Dagger Engine | Shell only | None | Provider |
| Skills | agentskills.io spec | Composite actions | Dagger Modules | Includes | Features | SKILL.md |
| Worktree isolation | Built-in | No | Containers | No | Container | No |
| Blueprint export | To external cron | No | No | No | No | Native |
| Multi-engine fallback | Yes (ordered list) | No | No | No | No | Provider config |
| Progressive disclosure | Yes (skill spec) | No | No | No | Feature metadata | Yes |
| Feature | archie-core | GitHub Actions | Dagger | Taskfile | devcontainer | External Skills |
| ---------------------- | ------------------- | ----------------- | -------------- | ---------- | ----------------- | --------------- |
| Language | YAML | YAML | Go/Python/TS | YAML | JSON | Markdown |
| Gates | Named + composable | Steps in jobs | Functions | Tasks | Lifecycle scripts | N/A |
| Engine abstraction | First-class | GitHub only | Dagger Engine | Shell only | None | Provider |
| Skills | agentskills.io spec | Composite actions | Dagger Modules | Includes | Features | SKILL.md |
| Worktree isolation | Built-in | No | Containers | No | Container | No |
| Blueprint export | To external cron | No | No | No | No | Native |
| Multi-engine fallback | Yes (ordered list) | No | No | No | No | Provider config |
| Progressive disclosure | Yes (skill spec) | No | No | No | Feature metadata | Yes |
---
## 6. Implementation Phases
### Phase 1: Core workflow file
- `archie.yaml` parser and schema validation
- Gate runner (test, lint, format, vet)
- `archie run <command>` CLI
- Sandbox Docker integration
### Phase 2: Skills
- SKILL.md discovery and progressive disclosure
- Skill metadata with gate/tool/engine requirements
- `archie skills list/install/search`
### Phase 3: Engine abstraction
- Engine interface definition
- Claude Code adapter
- Raw LLM adapter
- Engine fallback chain
### Phase 4: Advanced features
- Worktree isolation
- Skill chaining (dependency DAG)
- Gate overrides
- Blueprint export
### Phase 5: Ecosystem
- Public skill registry
- `archie init --skill <name>` scaffolding
- Community skill contributions
File diff suppressed because it is too large. Load diff
+23 -22
View File
@@ -7,7 +7,7 @@ changing anything that contradicts a prior decision.
---
## 2026-08-24 -- Turn continuation is never output-volume or token gated
## 2026-08-24 -- Turn continuation is never output-volume or token gated
**Decision**: A turn is never stopped because an aggregate token count or
aggregate tool-result character count was reached. `max_tokens` and
@@ -24,14 +24,14 @@ used to terminate the multi-step turn.
**Context**: GitHub #604 showed full file and module listings followed by four
identical read failures and a shell failure at the old 200,000-character cap.
The renderer now summarizes those legacy events for replay, while current
The renderer now summarises those legacy events for replay, while current
dispatch never creates them. Find and grep are confined to the active
workspace/worktree; the Go module cache remains readable only by explicit
path, not by discovery.
---
## 2026-07-23 -- Forge-agnostic issue creation via CreateIssue
## 2026-07-23 -- Forge-agnostic issue creation via CreateIssue
**Decision**: Add `CreateIssue(ctx, owner, repo, title, body, labels)
(int, error)` to the `forge.Forge` interface. Every forge backend
@@ -45,11 +45,11 @@ calls one method regardless of the underlying ticketing system.
**Future**: A `beads` forge backend will implement `CreateIssue` by
calling `bd create`. This makes beads the internal/default issue tracker
while Gitea/GitHub are external forges. The agent doesn't know which
it's talking to -- the daemon resolves the forge from repo config.
it's talking to -- the daemon resolves the forge from repo config.
---
## 2026-07-23 -- Dolt and Beads for agent-native issue tracking
## 2026-07-23 -- Dolt and Beads for agent-native issue tracking
**Decision**: Install dolt (version-controlled SQL) and beads (`bd`,
a graph-based issue tracker for AI agents) as the foundation for
@@ -59,19 +59,19 @@ multi-repo scaling and multi-agent coordination.
class dependency tracking, JSON output for programmatic use, and hash-
based IDs that prevent merge conflicts in multi-agent workflows. It's
built on Dolt which gives cell-level merge, native branching, and
remote sync -- the same primitives git gives code but applied to issues.
remote sync -- the same primitives git gives code but applied to issues.
**Context**: Gas Town (`~/gt/`) is cloned for reference -- it implements
**Context**: Gas Town (`~/gt/`) is cloned for reference -- it implements
a multi-agent workspace on top of beads. The archie-core scaling
strategy will follow a similar model: a coordinator daemon with per-repo
agents, all sharing a beads-backed task graph.
**Current state**: dolt 2.2.2, beads 1.1.0 installed. Beads initialized
**Current state**: dolt 2.2.2, beads 1.1.0 installed. Beads initialised
in archie-core (`.beads/`). Six issues seeded for the scaling roadmap.
---
## 2026-07-23 -- Token budgets must be generous, not predictive
## 2026-07-23 -- Token budgets must be generous, not predictive
> **Superseded by the 2026-08-24 decision above.** There is no configured
> aggregate token cap; model token usage remains accounting only.
@@ -88,7 +88,7 @@ proportionally more.
**Context**: The planner burned 357K tokens just to discover a fix
already existed. The builder hit 1M at step 25 of 90. Neither task was
unreasonable -- they were just exploring a large codebase.
unreasonable -- they were just exploring a large codebase.
**Future**: Track actual token consumption per workflow/stage/repo. Use
that data to set informed limits. Build compaction or checkpointing so
@@ -96,7 +96,7 @@ a killed agent can resume rather than restart.
---
## 2026-07-23 -- baseline-fix: auto-repair pre-existing gate failures
## 2026-07-23 -- baseline-fix: auto-repair pre-existing gate failures
**Decision**: When `StageBaselineGate` detects a red gate (gofumpt, go
vet, etc. failing on clean main), launch the builder to fix the
@@ -104,7 +104,7 @@ failures via TDD rather than parking. Only park if the builder cannot
fix them.
**Reasoning**: A red baseline means the repo was broken before archie
touched it. Parking creates an infinite loop -- the next retry hits the
touched it. Parking creates an infinite loop -- the next retry hits the
same failure. The agent should fix pre-existing issues, not fail on them.
**Implementation**: `StageBaselineGate` now calls `tc.Agent.Run()` with
@@ -113,7 +113,7 @@ this required wiring `tc.Agent` (the runner) through the stage context.
---
## 2026-07-23 -- No hardcoded MaxSteps in workflow stages
## 2026-07-23 -- No hardcoded MaxSteps in workflow stages
**Decision**: Remove all hardcoded `MaxSteps` values from workflow
stages. Every stage inherits from `[budgets].max_steps` in the config.
@@ -126,14 +126,14 @@ repos. The config should be the single source of truth.
---
## 2026-07-23 -- No-op detection: close issues when build has 0 changes
## 2026-07-23 -- No-op detection: close issues when build has 0 changes
**Decision**: When the builder completes with `StatusPassed` and 0 file
changes, close the issue with a comment rather than parking on "worktree
has no changes to commit".
**Reasoning**: A builder that passes with 0 changes means the fix
already exists or the issue is a no-op. The old behavior parked in an
already exists or the issue is a no-op. The old behaviour parked in an
infinite loop (commit-push fails because nothing changed, task re-queues,
builder runs again, same result).
@@ -147,7 +147,7 @@ sets `Outcome = Merged` to stop the workflow.
---
## 2026-07-23 -- assignee trigger over label trigger
## 2026-07-23 -- assignee trigger over label trigger
**Decision**: Default to `trigger = "assignee"` instead of `trigger =
"label"`. The daemon only claims issues explicitly assigned to the bot
@@ -159,7 +159,7 @@ promiscuous for repos shared between humans and agents.
---
## 2026-07-23 -- DeepSeek v4 Pro as primary model
## 2026-07-23 -- DeepSeek v4 Pro as primary model
**Decision**: Use `deepseek/deepseek-v4-pro` as the planner and builder
model. Qwythos-9B (local llama.cpp) is the fallback for offline/cheap
@@ -174,7 +174,7 @@ env var from Bitwarden Secrets Manager (bws).
---
## 2026-07-22 -- v1.0.0 tagged
## 2026-07-22 -- v1.0.0 tagged
**Decision**: Tagged `v1.0.0` at commit incorporating the daemon/agent
split, NATS JetStream, Docker sandbox, Yaegi plugins, agentskills.io
@@ -182,12 +182,13 @@ skills, and Gitea forge support.
---
## 2026-07-22 -- Docker Compose stack with NATS + containers
## 2026-07-22 -- Docker Compose stack with NATS + containers
**Decision**: The production deployment uses `docker-compose.yml` with
NATS, archied, and archie-agent containers. Config at `config.docker.toml`.
**Key fixes**:
- NATS healthcheck uses `wget localhost:8222/healthz` (not `nats-server check`)
- `host.docker.internal:host-gateway` extra_hosts for Linux
- Config mount path: `config.docker.toml` → `/etc/archie/config.toml`
@@ -195,10 +196,10 @@ NATS, archied, and archie-agent containers. Config at `config.docker.toml`.
---
## 2026-07-22 -- Worktree Prepare before Container Acquire
## 2026-07-22 -- Worktree Prepare before Container Acquire
**Decision**: Clone the worktree (`Trees.Prepare()`) before acquiring
a Docker container. Made `Prepare()` idempotent -- skips if `.git`
a Docker container. Made `Prepare()` idempotent -- skips if `.git`
already exists.
**Reasoning**: Docker bind-mounts fail with "bind source path does not
@@ -208,7 +209,7 @@ didn't exist on the host.
---
## 2026-07-22 -- Gofumpt and Go tools must be on PATH
## 2026-07-22 -- Gofumpt and Go tools must be on PATH
**Decision**: The daemon's `exec.Command` for gate checks inherits the
process PATH. `~/go/bin` (where `gofumpt`, `golangci-lint`, etc. live)
@@ -1,7 +1,7 @@
# Multi-Agent Collaboration -- PRD
**Status:** Draft (discovery interview complete, 2026-07-25)
**Author:** Discovery interview (archie-core-abg.1), synthesized from Sam's answers
**Author:** Discovery interview (archie-core-abg.1), synthesised from Sam's answers
**Parent epic:** archie-core-abg
---
@@ -80,7 +80,7 @@ implementation slice -- see section 5.
## 3. Constraints from existing architecture
From `ARCHITECTURE.md` and `docs/prds/archie-core-v2-architecture.md`
(read in full before implementation; summarized here):
(read in full before implementation; summarised here):
- **`Config.BotUser` is a single global field** (`internal/config`) -- the
root blocker for daemon-side multi-identity. Becomes a per-identity field
@@ -93,7 +93,7 @@ From `ARCHITECTURE.md` and `docs/prds/archie-core-v2-architecture.md`
(e.g. `archie.<identity>.task.<type>`) but that's a design decision, not
yet made.
- **Dispatch is `daemon.Run()` polling per configured forge/repo list**,
serialized per `owner/repo` by default (`AllowConcurrent` opts out).
serialised per `owner/repo` by default (`AllowConcurrent` opts out).
Multi-identity daemon means multiple poll loops (or one loop iterating
multiple identity configs) feeding the same NATS/container dispatch
machinery.
@@ -109,7 +109,7 @@ From `ARCHITECTURE.md` and `docs/prds/archie-core-v2-architecture.md`
- **The daemon gatekeeps all agent output** -- "no agent output reaches a
human without daemon review" (`archie-core-v2-architecture.md` sec.7).
Chat channels must respect this: a chat message that triggers a spawn goes
through the same review/labeling machinery PRs and comments do today, not
through the same review/labelling machinery PRs and comments do today, not
a side channel that bypasses it.
- **Environmental constraints over prompt rules** (`ARCHITECTURE.md` design
decision #1) -- chat-triggered actions (spawn, approve, cancel) should be
@@ -119,7 +119,7 @@ From `ARCHITECTURE.md` and `docs/prds/archie-core-v2-architecture.md`
## 4. Identity model (design direction, not yet finalized)
Confirmed requirement: within one daemon, identities differ by bot identity,
repo list, *and* model/provider config (per the archie/winter diff). Proposed
repo list, _and_ model/provider config (per the archie/winter diff). Proposed
shape -- **not yet approved, needs a follow-up design pass before
implementation**:
@@ -139,6 +139,7 @@ forge = { type = "gitea", host = "...", token_env = "..." }
models = { triage = "...", planner = "...", builder = "..." }
repos = [ ... ]
```
```
**Design answer (2026-07-25): per-identity goroutine, shared infrastructure.**
@@ -231,3 +232,4 @@ on.
identity).
- [ ] Broken into scoped, dependency-ordered beads issues under
`archie-core-abg`, the way the 5zh epic was. (Next step, this session.)
```
+127 -121
View File
@@ -1,4 +1,4 @@
# archie-core TypeScript Plugin Engine -- PRD
# archie-core TypeScript Plugin Engine -- PRD
**Author:** Archie
**Date:** 2026-07-21
@@ -8,7 +8,7 @@
## Summary
A TypeScript-based plugin engine that lets repositories ship interpreted, dynamically-loaded workflow extensions. Plugins are `.ts` files placed in `.archie/workflows/`. archie-core discovers them on its next poll cycle, transpiles them to JavaScript via esbuild, and executes them in an embedded [goja](https://github.com/dop251/goja) runtime -- a pure-Go ECMAScript interpreter with zero CGO dependencies.
A TypeScript-based plugin engine that lets repositories ship interpreted, dynamically-loaded workflow extensions. Plugins are `.ts` files placed in `.archie/workflows/`. archie-core discovers them on its next poll cycle, transpiles them to JavaScript via esbuild, and executes them in an embedded [goja](https://github.com/dop251/goja) runtime -- a pure-Go ECMAScript interpreter with zero CGO dependencies.
---
@@ -19,22 +19,24 @@ A TypeScript-based plugin engine that lets repositories ship interpreted, dynami
TypeScript is the most widely understood language among developers writing automation, CI, and workflow scripts. It already ships in most projects. Gate authors already know it. The ecosystem for linting, formatting, and type-checking is mature and free.
Having a TypeScript-native plugin engine means:
- Plugin authors get familiar syntax, type safety, and IDE support
- No separate toolchain -- just `.ts` files in a folder
- No separate toolchain -- just `.ts` files in a folder
- Skills, gates, and workflow stages share the same language
### Why goja
| Competitor | Problem |
|---|---|
| V8 CGO bindings | Requires CGO, ~50MB static libraries, platform-specific builds |
| QuickJS CGO | Requires CGO, smaller than V8 but still a C dependency |
| QJS (Wazero) | Pure Go WASM, but sandboxed -- can't expose Go functions efficiently |
| Ramune | Heavy dependency, bundles an entire TypeScript 7 compiler |
| Node.js subprocess | Process overhead per execution, IPC serialization cost |
| Competitor | Problem |
| ------------------ | -------------------------------------------------------------------- |
| V8 CGO bindings | Requires CGO, ~50MB static libraries, platform-specific builds |
| QuickJS CGO | Requires CGO, smaller than V8 but still a C dependency |
| QJS (Wazero) | Pure Go WASM, but sandboxed -- can't expose Go functions efficiently |
| Ramune | Heavy dependency, bundles an entire TypeScript 7 compiler |
| Node.js subprocess | Process overhead per execution, IPC serialisation cost |
goja is a pure-Go ECMAScript 5.1+ interpreter at ~20k lines. It:
- Has **zero CGO** -- cross-compiles everywhere Go does
- Has **zero CGO** -- cross-compiles everywhere Go does
- Passes nearly all TC39 Test262 tests for ES5.1 + significant ES6 coverage
- Can run Babel and the TypeScript compiler itself (proven capability)
- Provides direct Go↔JS interop via `Set()`/`Get()`/`Runtime.RunString()`
@@ -61,7 +63,7 @@ During the poll cycle, archie-core scans each repo's worktree for `.archie/workf
```
.archie/workflows/
├── custom-gate.ts # gate functions: exported `check()`
├── custom-gate.ts # gate functions: exported `check()`
├── db-migration.ts # custom stage: exported `stage()`
└── notify-slack.ts # skill script: exported `run()`
```
@@ -72,11 +74,11 @@ Each file is a self-contained module. No `package.json`, no `node_modules`, no e
A plugin declares its role via an exported symbol:
| Export | Role | When called |
|---|---|---|
| `export function check(ctx: GateContext): Finding[]` | Gate function | After shell-based gate, before commit |
| `export function stage(): Stage` | Workflow stage | When a workflow references the stage name |
| `export function run(ctx: ScriptContext): void` | Skill script | When a skill's instructions invoke the script |
| Export | Role | When called |
| ---------------------------------------------------- | -------------- | --------------------------------------------- |
| `export function check(ctx: GateContext): Finding[]` | Gate function | After shell-based gate, before commit |
| `export function stage(): Stage` | Workflow stage | When a workflow references the stage name |
| `export function run(ctx: ScriptContext): void` | Skill script | When a skill's instructions invoke the script |
arcie-core discovers the role by checking which exports exist. A file can export multiple roles.
@@ -86,54 +88,54 @@ arcie-core discovers the role by checking which exports exist. A file can export
// .archie/workflows/custom-gate.ts
interface GateContext {
diff: string; // unified diff of changes
changedFiles: string[]; // list of changed file paths
dir: string; // absolute worktree path
repo: string; // "owner/name"
baseRef: string; // "origin/main"
diff: string; // unified diff of changes
changedFiles: string[]; // list of changed file paths
dir: string; // absolute worktree path
repo: string; // "owner/name"
baseRef: string; // "origin/main"
}
interface Finding {
level: "error" | "warn";
file?: string;
line?: number;
message: string;
level: "error" | "warn";
file?: string;
line?: number;
message: string;
}
interface Block {
name: string;
message: string;
name: string;
message: string;
}
export function check(ctx: GateContext): Finding[] {
const findings: Finding[] = [];
const findings: Finding[] = [];
// Rule: no new panic() calls
for (const line of ctx.diff.split("\n")) {
if (line.startsWith("+") && !line.startsWith("+++")) {
if (line.includes("panic(")) {
findings.push({
level: "error",
message: "new panic() call -- use error returns instead"
});
}
}
// Rule: no new panic() calls
for (const line of ctx.diff.split("\n")) {
if (line.startsWith("+") && !line.startsWith("+++")) {
if (line.includes("panic(")) {
findings.push({
level: "error",
message: "new panic() call -- use error returns instead",
});
}
}
}
// Rule: no time.Sleep in non-test files
for (const file of ctx.changedFiles) {
if (file.endsWith("_test.go")) continue;
const content = archie.readFile(`${ctx.dir}/${file}`);
if (content.includes("time.Sleep")) {
findings.push({
level: "warn",
file: file,
message: "time.Sleep in non-test code -- use time.Ticker instead"
});
}
// Rule: no time.Sleep in non-test files
for (const file of ctx.changedFiles) {
if (file.endsWith("_test.go")) continue;
const content = archie.readFile(`${ctx.dir}/${file}`);
if (content.includes("time.Sleep")) {
findings.push({
level: "warn",
file: file,
message: "time.Sleep in non-test code -- use time.Ticker instead",
});
}
}
return findings;
return findings;
}
```
@@ -145,21 +147,21 @@ After transpilation and execution, archie-core calls `check(ctx)` via goja. Erro
// .archie/workflows/run-migrations.ts
export function stage(): Stage {
return {
name: "db-migration",
run: (ctx: TaskContext): string | null => {
// Check if migrations directory exists
const hasMigrations = archie.fileExists(`${ctx.dir}/migrations`);
if (!hasMigrations) return null; // nothing to do
return {
name: "db-migration",
run: (ctx: TaskContext): string | null => {
// Check if migrations directory exists
const hasMigrations = archie.fileExists(`${ctx.dir}/migrations`);
if (!hasMigrations) return null; // nothing to do
// Run migration tests
const result = archie.exec("go", ["test", "./migrations/..."]);
if (result.exitCode !== 0) {
return `migration tests failed: ${result.stderr}`;
}
return null; // success
}
};
// Run migration tests
const result = archie.exec("go", ["test", "./migrations/..."]);
if (result.exitCode !== 0) {
return `migration tests failed: ${result.stderr}`;
}
return null; // success
},
};
}
```
@@ -169,11 +171,11 @@ export function stage(): Stage {
// .archie/workflows/security-audit.ts
export function run(ctx: ScriptContext): void {
const result = archie.exec("gitleaks", ["detect", "--no-git"]);
if (result.exitCode !== 0) {
archie.log("warn", `gitleaks found secrets:\n${result.stdout}`);
}
archie.log("info", "security audit complete");
const result = archie.exec("gitleaks", ["detect", "--no-git"]);
if (result.exitCode !== 0) {
archie.log("warn", `gitleaks found secrets:\n${result.stdout}`);
}
archie.log("info", "security audit complete");
}
```
@@ -183,33 +185,33 @@ arcie-core exposes a `archie` global in the goja runtime:
```typescript
interface Archie {
// File operations (scoped to worktree)
readFile(path: string): string;
fileExists(path: string): boolean;
listDir(path: string): string[];
walkDir(path: string): string[];
// Shell execution
exec(command: string, args?: string[]): ExecResult;
// Logging
log(level: string, message: string): void;
// Path utilities
resolve(...parts: string[]): string;
ext(path: string): string;
// Environment
env(key: string): string;
// HTTP (optional, gated)
fetch(url: string, options?: FetchOptions): FetchResult;
// File operations (scoped to worktree)
readFile(path: string): string;
fileExists(path: string): boolean;
listDir(path: string): string[];
walkDir(path: string): string[];
// Shell execution
exec(command: string, args?: string[]): ExecResult;
// Logging
log(level: string, message: string): void;
// Path utilities
resolve(...parts: string[]): string;
ext(path: string): string;
// Environment
env(key: string): string;
// HTTP (optional, gated)
fetch(url: string, options?: FetchOptions): FetchResult;
}
interface ExecResult {
stdout: string;
stderr: string;
exitCode: number;
stdout: string;
stderr: string;
exitCode: number;
}
```
@@ -217,7 +219,7 @@ All file operations are **jailed to the worktree**. `archie.readFile("/etc/passw
### Reload cycle
Plugins are loaded fresh on every poll cycle -- archie-core already fresh-clones per task. No hot-reload complexity, no cache invalidation. The worktree is the source of truth.
Plugins are loaded fresh on every poll cycle -- archie-core already fresh-clones per task. No hot-reload complexity, no cache invalidation. The worktree is the source of truth.
For the rare case where a plugin errors at parse/transpile time, archie-core comments on the issue with the diagnostic and parks the task. The plugin author fixes the `.ts` file and requeues.
@@ -377,18 +379,18 @@ if gatePlugin := tc.Plugins.Gate(); gatePlugin != nil {
goja natively supports ES5.1 with significant ES6 features. Modern syntax like `async/await`, `??`, `?.`, or `class` fields may not parse. The transpile step (esbuild targeting ES2017) handles most of this, but there will be edge cases:
| Feature | Status |
|---|---|
| Arrow functions | ✅ via transpile |
| Template literals | ✅ via transpile |
| Destructuring | ✅ via transpile |
| `const`/`let` | ✅ via transpile |
| `async/await` | ❌ not supported (goja is synchronous) |
| `Promise` | ❌ requires `goja_nodejs` event loop |
| Generators | ❌ not supported |
| `Proxy` | ❌ not supported |
| Feature | Status |
| ----------------- | -------------------------------------- |
| Arrow functions | ✅ via transpile |
| Template literals | ✅ via transpile |
| Destructuring | ✅ via transpile |
| `const`/`let` | ✅ via transpile |
| `async/await` | ❌ not supported (goja is synchronous) |
| `Promise` | ❌ requires `goja_nodejs` event loop |
| Generators | ❌ not supported |
| `Proxy` | ❌ not supported |
For gate scripts, this is fine -- gates are synchronous by nature. If async is genuinely needed later, the Bun backend (via `tsgo`) is the escape hatch.
For gate scripts, this is fine -- gates are synchronous by nature. If async is genuinely needed later, the Bun backend (via `tsgo`) is the escape hatch.
### Performance
@@ -402,44 +404,48 @@ Plugins can't `import` from npm or other files. They're self-contained modules.
## Comparison: Yaegi vs goja
| | Yaegi (Go) | goja + esbuild (TypeScript) |
|---|---|---|
| **Language** | Go | TypeScript |
| **Pure Go** | ✅ | ✅ (goja + esbuild both pure Go) |
| **CGO** | None | None |
| **Transpile step** | None (interpreted directly) | esbuild TS→JS (~3ms) |
| **Author audience** | Go developers | Anyone who knows TypeScript |
| **Type annotations** | N/A (Go is typed) | Stripped by esbuild (no type-check at runtime) |
| **Interop** | Direct Go↔Go via `Use()` | Bridge via `archie` global |
| **Performance** | Interpreted Go (~10x slower than compiled) | Interpreted JS (~50x slower than V8, fine for gates) |
| **Maturity** | 8k stars, used by Traefik for plugins | 7k stars, used by k6, goja is battle-tested |
| **File extension** | `.go` | `.ts` |
| **Plugin folder** | `.archie/workflows/` | `.archie/workflows/` |
| **Best for** | Custom stages needing Go's stdlib, tight daemon integration | Custom gates and scripts where author familiarity matters |
| | Yaegi (Go) | goja + esbuild (TypeScript) |
| -------------------- | ----------------------------------------------------------- | --------------------------------------------------------- |
| **Language** | Go | TypeScript |
| **Pure Go** | ✅ | ✅ (goja + esbuild both pure Go) |
| **CGO** | None | None |
| **Transpile step** | None (interpreted directly) | esbuild TS→JS (~3ms) |
| **Author audience** | Go developers | Anyone who knows TypeScript |
| **Type annotations** | N/A (Go is typed) | Stripped by esbuild (no type-check at runtime) |
| **Interop** | Direct Go↔Go via `Use()` | Bridge via `archie` global |
| **Performance** | Interpreted Go (~10x slower than compiled) | Interpreted JS (~50x slower than V8, fine for gates) |
| **Maturity** | 8k stars, used by Traefik for plugins | 7k stars, used by k6, goja is battle-tested |
| **File extension** | `.go` | `.ts` |
| **Plugin folder** | `.archie/workflows/` | `.archie/workflows/` |
| **Best for** | Custom stages needing Go's stdlib, tight daemon integration | Custom gates and scripts where author familiarity matters |
**Recommendation: support both.** They solve different problems. Yaegi for repo owners who want full Go power in their custom stages. goja for repo owners who want to write gates and scripts in TypeScript. Both load from `.archie/workflows/` -- archie-core discovers which engine to use by file extension (`.go` → Yaegi, `.ts` → goja+esbuild).
**Recommendation: support both.** They solve different problems. Yaegi for repo owners who want full Go power in their custom stages. goja for repo owners who want to write gates and scripts in TypeScript. Both load from `.archie/workflows/` -- archie-core discovers which engine to use by file extension (`.go` → Yaegi, `.ts` → goja+esbuild).
---
## Implementation phases
### Phase 1: goja runtime + esbuild
- Add `github.com/dop251/goja` and `github.com/evanw/esbuild` as dependencies
- Build `internal/plugins/` with loader, runtime pool, bridge
- Wire gate plugin discovery into the implement and TDD workflows
- Gate plugins run after shell-based gate, before commit
### Phase 2: Custom stages
- Stage plugins discovered and registered alongside built-in stages
- `config.toml` can reference plugin stages by name
- TaskContext exposed to JS plugins
### Phase 3: Skill scripts
- Skill SKILL.md can reference `scripts/security-audit.ts`
- archie-core loads, transpiles, and evaluates when the skill activates
- Script stdout captured and returned to the agent as tool output
### Phase 4: Yaegi side-by-side
- Go plugin files (`.go`) loaded via Yaegi from the same `.archie/workflows/` directory
- Same discovery pattern, different interpreter
- archie-core chooses engine by file extension
+61
View File
@@ -26,6 +26,10 @@
"gate": {
"$ref": "#/schemas/Gate"
},
"harness": {
"$ref": "#/schemas/HarnessSpec",
"description": "Harness, when set, runs the stage on an external coding-agent CLI\ninstead of the built-in loop. The worker in a Kit container is the\ndaemon's own archie-agent build, so it always understands this field."
},
"mission": {
"type": "string"
},
@@ -247,6 +251,63 @@
},
"type": "object"
},
"HarnessSpec": {
"additionalProperties": false,
"description": "HarnessSpec is how to drive a Kit's agent headlessly: its launch argv (image entrypoint and cmd) and the agent-sessions@1 verb tails appended to it.",
"properties": {
"adapter": {
"description": "Adapter names the output adapter reading the CLI's stream; empty is\na CLI with none.",
"type": "string"
},
"continue": {
"items": {
"type": "string"
},
"type": "array"
},
"env": {
"description": "Env is the invocation's entire environment. Nothing is inherited from\nthe worker, whose environment carries its credentials.",
"items": {
"type": "string"
},
"type": "array"
},
"launch": {
"items": {
"type": "string"
},
"type": "array"
},
"mcp_config": {
"description": "MCPConfig registers archie's MCP server with the CLI: an argv tail\ncarrying {{.MCPConfig}}, the path of a standard mcpServers config.\nA stage with capture tools needs it.",
"items": {
"type": "string"
},
"type": "array"
},
"prompt": {
"items": {
"type": "string"
},
"type": "array"
},
"resume": {
"items": {
"type": "string"
},
"type": "array"
},
"user": {
"description": "User is the Kit's user, a name or \"uid[:gid]\", that every invocation\nruns as. It is never root: the worker's credentials live in the same\ncontainer, readable only by the worker's user.",
"type": "string"
}
},
"required": [
"launch",
"prompt"
],
"type": "object"
},
"MediaAttachment": {
"additionalProperties": false,
"description": "MediaAttachment describes a file attached to a message.",
+244 -82
View File
@@ -10,25 +10,25 @@
"url": "/dev/architecture/adversarial-review/",
"title": "Adversarial self-review",
"section": "Architecture",
"body": "# Adversarial self-review\n\nArchie runs a fresh adversarial review of the diff before it opens a pull\nrequest, so a PR arrives with a findings record rather than an unreviewed\nclaim. The reviewer provably cannot see the implementer's context: it reviews a\n`.git`-free snapshot of the committed tree, not the worktree, the commit\nhistory, or the implementer's transcript.\n\nPromoted from `docs/prds/adversarial-self-review.md` (the design decision;\n`archie-core-h019`). Describes the stage as shipped.\n\n## Contract (`internal/domain/workflow`)\n\nThe workflow domain owns the contract and the blocking decision; it never names\nthe executor.\n\n- `Reviewer.Review(ctx, ReviewRequest) ReviewReport` — the interface the\n workflow stage consumes.\n- `ReviewRequest` is the reviewer's entire input: `SnapshotDir` (a `.git`-free\n export of the reviewed commit), `Diff` (base...head), `IssueText` (the\n originating issue title/body), and `MaxSteps`.\n- `ReviewFinding` / `ReviewReport` are the structured result. The load-bearing\n rule is `Blocking() == (Verdict == confirmed \u0026\u0026 Level == error)`: only a\n confirmed error-level finding blocks; a plausible finding never blocks\n however severe it claims to be.\n\n`ReviewReport` distinguishes `not_run`, `skipped`, and `completed` (zero\nfindings) structurally, so \"ran and found nothing\" is not the same as \"never\nran\" — collapsing them would make an outage indistinguishable from a clean\nreview.\n\n## Execution (`internal/app/agentworker`)\n\nThe executor is an ai-sdk `agent.Subagent`: a nested synchronous generation in\nthe same worker process, with its own model, system prompt, toolset and step\nbudget.\n\n- **Conversation isolation is structural.** `Subagent.Run` sends only a prompt\n string, never the implementer's message history.\n- **Workspace isolation is the `.git`-free snapshot.** The reviewer's toolset is\n read-only (`read`, `grep`, `find`) and rooted at `SnapshotDir` — never the\n worker's own toolset, which carries the `worktreerpc` publication grant.\n- **Findings return through a typed capture tool** (`record_finding`), validated\n on the way in, so the reviewer reports through the contract rather than free\n text the caller regexes.\n- **Fail-closed.** A reviewer that errors, truncates, or reaches no conclusion\n yields `ReviewStatusNotRun`, which the stage treats as a park — never a silent\n \"PR opened unreviewed\".\n\n## Lifecycle effect\n\n`StageReview` runs in the implement workflow after the deterministic gates and\nbefore `StageOpenPR`, gated by `repo.review_enabled` (opt-in, default off). A\nsurviving blocking finding — or a review that failed to run — parks the task\n(`StatusParked`, not `waiting_human`) with the findings rendered into the park\nreason; `StageOpenPR` never runs. Warn/plausible findings and the zero-finding\ncase leave the outcome unset, so the PR opens with a findings section rendered\nonto its body. `StagePostReviewComments` then runs after `StageOpenPR` and posts\nthe **line-anchored** findings as inline review comments, carrying a one-click\nsuggestion on a confirmed finding the reviewer could state a fix for. That stage\nis best-effort — a comment that fails to post is logged, never a park — because\nthe body section already lists every finding, and it is the record a whole-file\nfinding (no line to anchor to) only ever appears in.\n\n## Model and budget\n\nThe reviewer model is `models.reviewer`, falling back to `models.builder`.\nEffort is the per-stage `MaxSteps` budget, mapped onto `Subagent.MaxSteps`\n(default 10).\n\n## Operator-triggered review\n\nThe same reviewer runs against an *existing* PR via the channel-neutral\n`review_pr` chat command: fetch the PR's head, snapshot it, run the isolated\nreviewer, and return the structured findings. Authorization is identity-scoped\nto the operator's configured repositories; duplicate or concurrent reviews of\nthe same PR are deduplicated.\n"
"body": "# Adversarial self-review\n\nArchie runs a fresh adversarial review of the diff before it opens a pull\nrequest, so a PR arrives with a findings record rather than an unreviewed\nclaim. The reviewer provably cannot see the implementer's context: it reviews a\n`.git`-free snapshot of the committed tree, not the worktree, the commit\nhistory, or the implementer's transcript.\n\nPromoted from `docs/prds/adversarial-self-review.md` (the design decision;\n`archie-core-h019`). Describes the stage as shipped.\n\n## Contract (`internal/domain/workflow`)\n\nThe workflow domain owns the contract and the blocking decision; it never names\nthe executor.\n\n- `Reviewer.Review(ctx, ReviewRequest) ReviewReport` — the interface the\n workflow stage consumes.\n- `ReviewRequest` is the reviewer's entire input: `SnapshotDir` (a `.git`-free\n export of the reviewed commit), `Diff` (base...head), `IssueText` (the\n originating issue title/body), and `MaxSteps`.\n- `ReviewFinding` / `ReviewReport` are the structured result. The load-bearing\n rule is `Blocking() == (Verdict == confirmed \u0026\u0026 Level == error)`: only a\n confirmed error-level finding blocks; a plausible finding never blocks\n however severe it claims to be.\n\n`ReviewReport` distinguishes `not_run`, `skipped`, and `completed` (zero\nfindings) structurally, so \"ran and found nothing\" is not the same as \"never\nran\" — collapsing them would make an outage indistinguishable from a clean\nreview.\n\n## Execution (`internal/app/agentworker`)\n\nThe executor is an ai-sdk `agent.Subagent`: a nested synchronous generation in\nthe same worker process, with its own model, system prompt, toolset and step\nbudget.\n\n- **Conversation isolation is structural.** `Subagent.Run` sends only a prompt\n string, never the implementer's message history.\n- **Workspace isolation is the `.git`-free snapshot.** The reviewer's toolset is\n read-only (`read`, `grep`, `find`) and rooted at `SnapshotDir` — never the\n worker's own toolset, which carries the `worktreerpc` publication grant.\n- **Findings return through a typed capture tool** (`record_finding`), validated\n on the way in, so the reviewer reports through the contract rather than free\n text the caller regexes.\n- **Fail-closed.** A reviewer that errors, truncates, or reaches no conclusion\n yields `ReviewStatusNotRun`, which the stage treats as a park — never a silent\n \"PR opened unreviewed\".\n\n## Lifecycle effect\n\n`StageReview` runs in the implement workflow after the deterministic gates and\nbefore `StageOpenPR`, gated by `repo.review_enabled` (opt-in, default off). A\nsurviving blocking finding — or a review that failed to run — parks the task\n(`StatusParked`, not `waiting_human`) with the findings rendered into the park\nreason; `StageOpenPR` never runs. Warn/plausible findings and the zero-finding\ncase leave the outcome unset, so the PR opens with a findings section rendered\nonto its body. `StagePostReviewComments` then runs after `StageOpenPR` and posts\nthe **line-anchored** findings as inline review comments, carrying a one-click\nsuggestion on a confirmed finding the reviewer could state a fix for. That stage\nis best-effort — a comment that fails to post is logged, never a park — because\nthe body section already lists every finding, and it is the record a whole-file\nfinding (no line to anchor to) only ever appears in.\n\n## Model and budget\n\nThe reviewer model is `models.reviewer`, falling back to `models.builder`.\nEffort is the per-stage `MaxSteps` budget, mapped onto `Subagent.MaxSteps`\n(default 10).\n\n## Operator-triggered review\n\nThe same reviewer runs against an _existing_ PR via the channel-neutral\n`review_pr` chat command: fetch the PR's head, snapshot it, run the isolated\nreviewer, and return the structured findings. Authorisation is identity-scoped\nto the operator's configured repositories; duplicate or concurrent reviews of\nthe same PR are deduplicated.\n"
},
{
"url": "/dev/architecture/agent-system/",
"title": "Agent System",
"section": "Architecture",
"body": "# Agent System\n\n**Status:** Current-state investigation in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Domain framing\n\nThe domain is the Agent System.\n\n`Task` is not a core Agent System concept. Forge tasks, forge issues, Jira\nissues, email, Telegram messages, webhooks, and future external inputs are\nchannel-specific messages. Channels translate those messages into requests to\nthe Agent System; external issue or task models MUST NOT shape execution state.\n\nThe current `store.Task` is a persisted workflow execution. Treating that row as\na task-domain aggregate would incorrectly turn Archie into an agentic issue\nboard.\n\n## Canonical agent interaction model\n\nAn **Agent** is a persistent assistant selected for an interaction. It is not a\nmodel invocation and is not a WorkflowExecution.\n\nEach Agent has its own:\n\n- immutable acting `IdentityID` for ownership and audit;\n- durable memory and learned information about the user;\n- perspective, specialisation, instructions, and communication behaviour;\n- conversation history and channel bindings;\n- available tools, capabilities, and policy;\n- continuity across model or provider changes.\n\nThe underlying model is a replaceable runtime dependency. Changing a model,\nprovider, or model version MUST NOT create a new Agent, discard its memory, or\nchange ownership of its history.\n\nA user MAY create multiple Agents. Each Agent develops its own memory and view\nof the user from the interactions and responsibilities assigned to it. Memories\nMUST NOT be silently pooled merely because Agents belong to the same user or\napplication.\n\nAgent and Identity are separate aggregates. Every Agent references exactly one\nacting IdentityID, and no two Agents share an agent identity. User, system, and\nservice-account identities may exist without an Agent.\n\nAn action initiated through an Agent records the Agent's acting IdentityID and,\nwhen applicable, the initiating user's IdentityID. A future fully automated\nWorkflowExecution MAY use an explicitly selected service-account identity for a\nconcrete unattended use case; this is not the default execution identity.\n\n## Workflow execution identity\n\nA Workflow is owned by an IdentityID. By default, every WorkflowExecution acts\nas the Workflow owner's identity.\n\nFuture delegated execution MAY add an explicit `RunAsIdentityID` assignment to a\nWorkflow. This allows a Workflow owner to select another user or service-account\nidentity for execution without changing Workflow ownership. Until that\ncapability is deliberately introduced, owner identity and execution identity are\nthe same.\n\nWorkflowExecution audit records MUST preserve the Workflow owner, effective\nexecution identity, initiating user when one exists, and any explicit delegation\nthat selected a different run-as identity.\n\n## Memory scopes\n\nThe Agent System requires four distinct durable memory scopes:\n\n- **global shared memory**: information intentionally available across the\n Archie application;\n- **agent-wide memory**: general expertise, operating knowledge, and perspective\n owned by one Agent and safe for that Agent to use across users;\n- **user-wide memory**: information associated with one user and available to\n authorized Agents serving that user;\n- **Agent-user relationship memory**: private history and learned context from\n one particular Agent's relationship with one particular user.\n\nAgent-wide memory is private to its owning Agent by default. Another Agent MUST\nNOT read, inherit, search, or mutate it implicitly.\n\nAgent-user relationship memory is addressed by both AgentID and User IdentityID.\nNeither another Agent serving the same user nor another user speaking to the\nsame Agent may access it implicitly.\n\nArchie is a multi-user system even when initially deployed for one person.\nMultiple users, including family members, may interact with the same configured\nAgents. Per-user memory is therefore an isolation and personalization boundary,\nnot merely an attribution tag on the primary user's records.\n\nAn Agent MUST resolve the initiating user before assembling memory context.\nMemory belonging to one user MUST NOT become visible to another user merely\nbecause both users interact with the same Agent.\n\nShared memory does not erase provenance. Every memory record retains its scope,\nauthor or acting identity, originating user when applicable, source, and\nrevision history. The rules for selecting a write scope, granting access\nto global and user-wide memory, and authorizing explicit cross-scope sharing are\nsettled by [`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\nand recorded in [`migration-decisions.md`](/dev/architecture/migration-decisions/#5-memory-placement-and-storage)\nsection 5.\n\nAn Agent interaction may answer conversationally, use a tool or capability, read\norLine truncated
"body": "# Agent System\n\n**Status:** Current-state investigation in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Domain framing\n\nThe domain is the Agent System.\n\n`Task` is not a core Agent System concept. Forge tasks, forge issues, Jira\nissues, email, Telegram messages, webhooks, and future external inputs are\nchannel-specific messages. Channels translate those messages into requests to\nthe Agent System; external issue or task models MUST NOT shape execution state.\n\nThe current `store.Task` is a persisted workflow execution. Treating that row as\na task-domain aggregate would incorrectly turn Archie into an agentic issue\nboard.\n\n## Canonical agent interaction model\n\nAn **Agent** is a persistent assistant selected for an interaction. It is not a\nmodel invocation and is not a WorkflowExecution.\n\nEach Agent has its own:\n\n- immutable acting `IdentityID` for ownership and audit;\n- durable memory and learned information about the user;\n- perspective, specialisation, instructions, and communication behaviour;\n- conversation history and channel bindings;\n- available tools, capabilities, and policy;\n- continuity across model or provider changes.\n\nThe underlying model is a replaceable runtime dependency. Changing a model,\nprovider, or model version MUST NOT create a new Agent, discard its memory, or\nchange ownership of its history.\n\nA user MAY create multiple Agents. Each Agent develops its own memory and view\nof the user from the interactions and responsibilities assigned to it. Memories\nMUST NOT be silently pooled merely because Agents belong to the same user or\napplication.\n\nAgent and Identity are separate aggregates. Every Agent references exactly one\nacting IdentityID, and no two Agents share an agent identity. User, system, and\nservice-account identities may exist without an Agent.\n\nAn action initiated through an Agent records the Agent's acting IdentityID and,\nwhen applicable, the initiating user's IdentityID. A future fully automated\nWorkflowExecution MAY use an explicitly selected service-account identity for a\nconcrete unattended use case; this is not the default execution identity.\n\n## Workflow execution identity\n\nA Workflow is owned by an IdentityID. By default, every WorkflowExecution acts\nas the Workflow owner's identity.\n\nFuture delegated execution MAY add an explicit `RunAsIdentityID` assignment to a\nWorkflow. This allows a Workflow owner to select another user or service-account\nidentity for execution without changing Workflow ownership. Until that\ncapability is deliberately introduced, owner identity and execution identity are\nthe same.\n\nWorkflowExecution audit records MUST preserve the Workflow owner, effective\nexecution identity, initiating user when one exists, and any explicit delegation\nthat selected a different run-as identity.\n\n## Memory scopes\n\nThe Agent System requires four distinct durable memory scopes:\n\n- **global shared memory**: information intentionally available across the\n Archie application;\n- **agent-wide memory**: general expertise, operating knowledge, and perspective\n owned by one Agent and safe for that Agent to use across users;\n- **user-wide memory**: information associated with one user and available to\n authorised Agents serving that user;\n- **Agent-user relationship memory**: private history and learned context from\n one particular Agent's relationship with one particular user.\n\nAgent-wide memory is private to its owning Agent by default. Another Agent MUST\nNOT read, inherit, search, or mutate it implicitly.\n\nAgent-user relationship memory is addressed by both AgentID and User IdentityID.\nNeither another Agent serving the same user nor another user speaking to the\nsame Agent may access it implicitly.\n\nArchie is a multi-user system even when initially deployed for one person.\nMultiple users, including family members, may interact with the same configured\nAgents. Per-user memory is therefore an isolation and personalisation boundary,\nnot merely an attribution tag on the primary user's records.\n\nAn Agent MUST resolve the initiating user before assembling memory context.\nMemory belonging to one user MUST NOT become visible to another user merely\nbecause both users interact with the same Agent.\n\nShared memory does not erase provenance. Every memory record retains its scope,\nauthor or acting identity, originating user when applicable, source, and\nrevision history. The rules for selecting a write scope, granting access\nto global and user-wide memory, and authorising explicit cross-scope sharing are\nsettled by [`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\nand recorded in [`migration-decisions.md`](/dev/architecture/migration-decisions/#5-memory-placement-and-storage)\nsection 5.\n\nAn Agent interaction may answer conversationally, use a tool or capability, read\norLine truncated
},
{
"url": "/dev/architecture/bindings/",
"title": "Playbook bindings: model and threat model",
"section": "Architecture",
"body": "# Playbook bindings: model and threat model\n\n**Status:** Approved foundation (documents shipped code: `archie-core-t2db.1`\nthrough `.5`, `.7`, `.9`-`.15`)\n**Date:** 2026-09-03\n\nThis document covers the binding model and the intake threat model portion\nof `archie-core-t2db.6`. It does not cover the task-lifecycle provenance rule\n(`messaging-and-work-intake.md`'s \"Intake provenance\") or the operator\nwalkthrough -- that walkthrough remains an open piece of the same ticket.\n\n## What a binding is\n\nA `binding` (`internal/domain/binding.Binding`) ties four things together:\na **matcher** (which captured events it applies to), a **mapping**\n(`internal/domain/mapping.Mapping`, how fields are pulled out of a payload),\na **workflow** (which registered workflow runs on a match), and a **state\nmachine** governing whether it is live.\n\n```go\ntype Binding struct {\n ID, Name // identity\n Matcher // { Source string } -- the webhook path segment, e.g. \"sentry\"\n MappingID // which Mapping resolves payload fields\n Workflow // registered workflow name to dispatch to\n Version // bumped on every edit\n Status // draft | pending_approval | armed\n Secret // HMAC-SHA256 shared secret, encrypted at rest, never returned by GET\n}\n```\n\nBindings live in the store (SQLite), not `config.toml` -- operators author\nthem from the dashboard while the daemon runs, without a restart.\n\n### Matching\n\n`Matcher.Source` is the only predicate today: the path segment a sender\nPOSTs to (e.g. a webhook hitting `.../sentry` matches bindings with\n`Matcher.Source == \"sentry\"`). The storage column is plain `TEXT`, so adding\npredicates later is non-breaking -- extend `Matcher`, don't invent a second\nmatcher shape.\n\n### Mapping\n\n`mapping.Resolve(fields, payload)` walks a captured JSON payload against a\nlist of typed `Field`s (name, JSON path, expected type), returning resolved\nvalues plus a `[]Failure` for anything that didn't parse or type-match. This\nis schema-by-example in practice: a mapping is authored by pointing at a\nreal captured payload in the dashboard, not by guessing a schema in advance.\n\n### Versioning\n\n`Version` increments on every `UpdateBinding` call. This exists so an\neditor's later change can never silently rewrite the historical provenance\nof a task that already fired -- a dispatched task's binding reference is\npinned to the version that was armed when it fired, not \"whatever the\nbinding currently says.\"\n\n### State machine\n\n```\ndraft ---\u003e pending_approval ---\u003e armed\n ^ ^ |\n | | |\n +--------------+-----------------+\n (any edit to an armed binding drops it back to pending_approval)\n```\n\nModeled directly on Telegram's existing `dangerousAction`/`pendingApproval`\nflow (`internal/channels/telegram/dangerous.go`, `approval.go`) -- not a new\napproval mechanism invented for this feature. **Only `armed` evaluates\nagainst incoming events** (`binding.Matches`, `internal/domain/binding/\nbinding.go`); `draft` and `pending_approval` bindings are inert. An edit to\nan already-armed binding cannot bypass approval by silent mutation -- it\ndrops back to `pending_approval` and requires an explicit `Approve` call to\nre-arm.\n\n## The threat model\n\nThis is a public, unauthenticated-by-default intake surface whose output is\nan agent with a repo, a worktree, and tool access. The design brief\n(`archie-core-t2db.5`, `docs/prds/webhook-intake-security.md`) named five\nnon-negotiables; each is verified below against the actual shipped code,\nnot the design intent.\n\n### 1. Per-source authentication\n\nReuses `internal/channels/webhook`'s existing HMAC-SHA256 scheme --\ncapture accepts unsigned events (visible in the dashboard, marked\nunauthenticated), but **only authenticated events can ever match a\nbinding**. `binding.Matches`' doc comment states this plainly: \"an\nunauthenticated event can never trigger a binding, no matter how well it\nwould otherwise match.\" Enforced structurally at two points, not just\nconvention:\n\n- `captured_events.authenticated` is a real column (`internal/store/\n captures.go`), set at capture time.\n- `dispatchBindings` (`internal/daemon/daemon.go:479`) walks **authenticated\n captures whose source has at least one armed binding** -- an\n unauthenticated capture is never even considered for dispatch.\n\n### 2. Human approval before a binding goes live\n\nCovered by the state machine above. Nothing self-arms: `pending_approval -\u003e\narmed` requires an explicit `Approve` call, and any edit to an armed\nbinding reverts it.\n\n### 3. Rate and volume limits per source\n\nCapture writes are bounded independently of the approval gate, so a flood\nof unauthenticated traffic cannot exhaust disk or drown the inspector:\n`InsertCapture` (`internal/store/captures.go`) prunLine truncated
"body": "# Playbook bindings: model and threat model\n\n**Status:** Approved foundation (documents shipped code: `archie-core-t2db.1`\nthrough `.5`, `.7`, `.9`-`.15`)\n**Date:** 2026-09-03\n\nThis document covers the binding model and the intake threat model portion\nof `archie-core-t2db.6`. It does not cover the task-lifecycle provenance rule\n(`messaging-and-work-intake.md`'s \"Intake provenance\") or the operator\nwalkthrough -- that walkthrough remains an open piece of the same ticket.\n\n## What a binding is\n\nA `binding` (`internal/domain/binding.Binding`) ties four things together:\na **matcher** (which captured events it applies to), a **mapping**\n(`internal/domain/mapping.Mapping`, how fields are pulled out of a payload),\na **workflow** (which registered workflow runs on a match), and a **state\nmachine** governing whether it is live.\n\n```go\ntype Binding struct {\n ID, Name // identity\n Matcher // { Source string } -- the webhook path segment, e.g. \"sentry\"\n MappingID // which Mapping resolves payload fields; its event type is the binding's\n Filter // optional CEL over the mapping's parameters\n Workflow // registered workflow name to dispatch to\n Version // bumped on every edit\n Status // pending_approval | armed\n Secret // HMAC-SHA256 shared secret, encrypted at rest, never returned by GET\n}\n```\n\nBindings live in the store (PostgreSQL), not `config.toml` -- operators author\nthem from the dashboard while the daemon runs, without a restart.\n\n### Matching\n\nA binding applies to a capture when the capture arrived on `Matcher.Source`,\nwas identified as the event type its mapping belongs to, and passes its\n`Filter` (`binding.CompileFilter`, checked against the mapping's parameters on\nsave). Any number of bindings may share a source; each dispatches a capture at\nmost once, claimed in `binding_dispatches` keyed by (binding, capture) before\nits task is enqueued. An event signed with any armed binding's secret on the\nsource is authenticated.\n\n### Mapping\n\n`mapping.Resolve(fields, payload)` walks a captured JSON payload against a\nlist of typed `Field`s (name, JSON path, expected type), returning resolved\nvalues plus a `[]Failure` for anything that didn't parse or type-match. A\nmapping belongs to an event type, and `mapping.CheckSchema` refuses a field\nwhose path or type the type's inferred schema lacks. Each capture a mapping\nresolves at dispatch is counted once in `mapping_matches`, read back as\n`MatchCount` and `LastMatchedAt`.\n\n### Versioning\n\n`Version` increments on every `UpdateBinding` call. This exists so an\neditor's later change can never silently rewrite the historical provenance\nof a task that already fired -- a dispatched task's binding reference is\npinned to the version that was armed when it fired, not \"whatever the\nbinding currently says.\"\n\n### State machine\n\n```\ncreate ---\u003e pending_approval ---\u003e armed\n ^ |\n +----------------+\n (any edit to an armed binding drops it back to pending_approval)\n```\n\nA binding is created `pending_approval`, so the operator who creates one can\napprove it immediately. Bindings stored as `draft` by an earlier version are\nmoved to `pending_approval` when the EDA store opens.\n\nModelled directly on Telegram's existing `dangerousAction`/`pendingApproval`\nflow (`internal/channels/telegram/dangerous.go`, `approval.go`) -- not a new\napproval mechanism invented for this feature. **Only `armed` evaluates\nagainst incoming events** (`binding.Matches`, `internal/domain/binding/\nbinding.go`); a `pending_approval` binding is inert. An edit to\nan already-armed binding cannot bypass approval by silent mutation -- it\ndrops back to `pending_approval` and requires an explicit `Approve` call to\nre-arm.\n\n## The threat model\n\nThis is a public, unauthenticated-by-default intake surface whose output is\nan agent with a repo, a worktree, and tool access. The design brief\n(`archie-core-t2db.5`, `docs/prds/webhook-intake-security.md`) named five\nnon-negotiables; each is verified below against the actual shipped code,\nnot the design intent.\n\n### 1. Per-source authentication\n\nReuses `internal/channels/webhook`'s existing HMAC-SHA256 scheme --\ncapture accepts unsigned events (visible in the dashboard, marked\nunauthenticated), but **only authenticated events can ever match a\nbinding**. `binding.Matches`' doc comment states this plainly: \"an\nunauthenticated event can never trigger a binding, no matter how well it\nwould otherwise match.\" Enforced structurally at two points, not just\nconvention:\n\n- `captures.authenticated` is a real column\n (`internal/infrastructure/postgres/migrations/0002_edastore.sql`), set at\n capture time.\n- `dispatchBindings` (`internal/daemon/daemon.go:479`) walks **authenticated\n captures whose soLine truncated
},
{
"url": "/dev/architecture/configuration/",
"title": "Configuration",
"section": "Architecture",
"body": "# Configuration\n\n**Status:** Approved; existing-type assignment is ongoing \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Ownership\n\nConfiguration has two separate responsibilities:\n\n1. `internal/infrastructure/configuration` loads files, environment variables,\n secret references, overlays, and compatibility representations.\n2. Each domain and plugin owns the typed runtime settings required for its\n behaviour.\n\n`internal/app` translates external input into those settings, validates\ncross-capability combinations, and supplies each component only its own\nsettings.\n\nThe following are prohibited:\n\n- passing complete application configuration into a domain;\n- making a domain depend on TOML, YAML, environment-variable names, secret\n references, or a configuration library;\n- defining a central runtime configuration type imported across the system;\n- placing plugin options in an unrelated global configuration model.\n\n## Private input document\n\n`internal/infrastructure/configuration` MAY use a complete decoded document\nwhile discovering files, decoding sections, and applying overlays. It is an\ninput-boundary DTO only.\n\nThe document:\n\n- remains private to the configuration infrastructure;\n- is composed from separately defined feature sections;\n- is immediately translated by application composition;\n- is never returned as the application's runtime model;\n- is never passed through runtime components.\n\nExternal DTOs and domain runtime settings are separate types.\n\nPlugins supply external configuration definitions through a narrow extension\ncontract. The core loader MUST NOT gain a field or recognized filename for every\nplugin.\n\nInvalid configuration input MUST NOT replace active valid settings or terminate\nunaffected capabilities. Configuration changes use the candidate validation,\npromotion, audit, and recovery requirements in\n[safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/).\n\n## Dissolution of `internal/config`\n\n`internal/config` has no target location. It MUST be dissolved and MUST NOT\nsurvive as a shared package, configuration domain, or renamed global model.\n\nIts loading behaviour moves to `internal/infrastructure/configuration`. Existing\ntypes and methods are reassigned by behaviour. Repository execution policy,\ndispatch policy, retry policy, ecosystem defaults, tool policy, memory settings,\nprovider settings, and channel settings move to their\nrespective owners.\n\n## Repository settings\n\nThe existing `config.Repo` MUST NOT move intact into a repository domain or\nshared settings package. A managed repository is an application association:\n\n- work intake owns which repository references an identity monitors;\n- task execution owns gates, preflight, test protection, ecosystem behaviour,\n and change limits;\n- task lifecycle owns retry behaviour;\n- scheduling owns concurrency policy;\n- workspace management owns base branch and persistent-storage requirements.\n\nApplication composition correlates these settings by repository reference. No\ndomain receives a universal repository profile.\n\n## Documentation\n\nGenerated configuration reference describes external sections and their owning\ncapabilities. It MUST NOT establish a global Go configuration structure as the\npublic contract.\n\n## Value classification rule\n\nEvery value that controls behaviour MUST have an explicit owner and MUST be\nclassified as exactly one of:\n\n1. **Invariant** — changing it changes the meaning of the program, a wire\n protocol, or a domain concept. It may be a Go constant.\n2. **Runtime setting** — an operator, identity, domain, plugin, or deployment\n may legitimately choose a different value. It is typed configuration owned by\n the affected capability.\n3. **Policy value** — it expresses what is allowed, limited, routed, retried,\n protected, or gated. Its typed definition belongs to the owning domain and it\n is evaluated through the policy system.\n4. **Derived value** — it is computed from other settings and is not\n independently mutable.\n5. **Runtime state** — it changes as the application operates, such as the\n active model for a conversation. It is changed by a domain command and is not\n configuration merely because it can be changed.\n\nAn unclassified behavioural literal is a defect.\n\n`const` MUST NOT be used merely because a value currently has one default.\nConstants are reserved for actual invariants: enum discriminants, protocol\nversions, fixed compatibility tokens, and values whose alteration would change\nthe program's semantics rather than configure an installation.\n\nIn Go, a constant is a compile-time value and does not represent mutable runtime\nstorage. It generally has no address that can be observed or changed.\nArchitecturally, a constant therefore asserts that the value cannot change for\nthe lifetiLine truncated
"body": "# Configuration\n\n**Status:** Approved; existing-type assignment is ongoing \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Ownership\n\nConfiguration has two separate responsibilities:\n\n1. `internal/infrastructure/configuration` loads files, environment variables,\n secret references, overlays, and compatibility representations.\n2. Each domain and plugin owns the typed runtime settings required for its\n behaviour.\n\n`internal/app` translates external input into those settings, validates\ncross-capability combinations, and supplies each component only its own\nsettings.\n\nThe following are prohibited:\n\n- passing complete application configuration into a domain;\n- making a domain depend on TOML, YAML, environment-variable names, secret\n references, or a configuration library;\n- defining a central runtime configuration type imported across the system;\n- placing plugin options in an unrelated global configuration model.\n\n## Private input document\n\n`internal/infrastructure/configuration` MAY use a complete decoded document\nwhile discovering files, decoding sections, and applying overlays. It is an\ninput-boundary DTO only.\n\nThe document:\n\n- remains private to the configuration infrastructure;\n- is composed from separately defined feature sections;\n- is immediately translated by application composition;\n- is never returned as the application's runtime model;\n- is never passed through runtime components.\n\nExternal DTOs and domain runtime settings are separate types.\n\nPlugins supply external configuration definitions through a narrow extension\ncontract. The core loader MUST NOT gain a field or recognised filename for every\nplugin.\n\nInvalid configuration input MUST NOT replace active valid settings or terminate\nunaffected capabilities. Configuration changes use the candidate validation,\npromotion, audit, and recovery requirements in\n[safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/).\n\n## Dissolution of `internal/config`\n\n`internal/config` has no target location. It MUST be dissolved and MUST NOT\nsurvive as a shared package, configuration domain, or renamed global model.\n\nIts loading behaviour moves to `internal/infrastructure/configuration`. Existing\ntypes and methods are reassigned by behaviour. Repository execution policy,\ndispatch policy, retry policy, ecosystem defaults, tool policy, memory settings,\nprovider settings, and channel settings move to their\nrespective owners.\n\n## Repository settings\n\nThe existing `config.Repo` MUST NOT move intact into a repository domain or\nshared settings package. A managed repository is an application association:\n\n- work intake owns which repository references an identity monitors;\n- task execution owns gates, preflight, test protection, ecosystem behaviour,\n and change limits;\n- task lifecycle owns retry behaviour;\n- scheduling owns concurrency policy;\n- workspace management owns base branch and persistent-storage requirements.\n\nApplication composition correlates these settings by repository reference. No\ndomain receives a universal repository profile.\n\n## Documentation\n\nGenerated configuration reference describes external sections and their owning\ncapabilities. It MUST NOT establish a global Go configuration structure as the\npublic contract.\n\n## Value classification rule\n\nEvery value that controls behaviour MUST have an explicit owner and MUST be\nclassified as exactly one of:\n\n1. **Invariant** — changing it changes the meaning of the program, a wire\n protocol, or a domain concept. It may be a Go constant.\n2. **Runtime setting** — an operator, identity, domain, plugin, or deployment\n may legitimately choose a different value. It is typed configuration owned by\n the affected capability.\n3. **Policy value** — it expresses what is allowed, limited, routed, retried,\n protected, or gated. Its typed definition belongs to the owning domain and it\n is evaluated through the policy system.\n4. **Derived value** — it is computed from other settings and is not\n independently mutable.\n5. **Runtime state** — it changes as the application operates, such as the\n active model for a conversation. It is changed by a domain command and is not\n configuration merely because it can be changed.\n\nAn unclassified behavioural literal is a defect.\n\n`const` MUST NOT be used merely because a value currently has one default.\nConstants are reserved for actual invariants: enum discriminants, protocol\nversions, fixed compatibility tokens, and values whose alteration would change\nthe program's semantics rather than configure an installation.\n\nIn Go, a constant is a compile-time value and does not represent mutable runtime\nstorage. It generally has no address that can be observed or changed.\nArchitecturally, a constant therefore asserts that the value cannot change for\nthe lifetiLine truncated
},
{
"url": "/dev/architecture/dashboard-agent-tools/",
@@ -40,37 +40,37 @@
"url": "/dev/architecture/dependencies-and-contracts/",
"title": "Dependencies and Contracts",
"section": "Architecture",
"body": "# Dependencies and Contracts\n\n**Status:** Approved foundation \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Dependency direction\n\n```text\ndomain and shared application contracts \u003c- infrastructure implementations\n ^\n |\n application composition\n```\n\nThe following rules are strict:\n\n1. Domains MUST NOT import `internal/infrastructure`.\n2. A domain defines the smallest interfaces required to perform its work.\n3. Infrastructure implements those interfaces and translates external\n representations at the boundary.\n4. Only application composition chooses concrete implementations.\n5. A domain MUST NOT manipulate another domain's state or call its internal\n services.\n6. Cross-domain work uses an explicitly designed command, event, or approved\n shared contract.\n7. Implementation difficulty is not permission to violate a boundary.\n\nBroker messages, database rows, SDK response types, and configuration DTOs MUST\nNOT leak into domain models.\n\n## Commands and events\n\n- An event records something that happened and is owned by its publishing\n domain.\n- A command requests an action and is owned by the domain expected to handle it.\n- Consumers do not redefine an event's meaning.\n- Senders obey the receiving domain's command contract.\n- There is no generic package containing unrelated application messages.\n\n## Event bus\n\n`internal/eventbus` is an approved shared application contract. It defines only\nthe messaging behaviour Archie requires, including publication, subscription,\ndelivery outcomes, and required lifecycle semantics.\n\nIt MUST remain broker-neutral. NATS subjects, JetStream configuration, consumer\ngroups, acknowledgements, reconnection, and serialization belong under\n`internal/infrastructure/eventbus/nats` unless Archie explicitly requires a\nsemantic guarantee in the shared contract.\n\nMessage schemas stay with their owning domains. The event bus transports\nmessages; it does not own their meaning.\n\n## Wire contracts and generation\n\nCanonical worker and service wire contracts and their authoritative generation\ninputs are owned by the domain or capability that defines their meaning. They\nMUST NOT be centralized in `internal/infrastructure/spec` or another generic\nschema package.\n\nInfrastructure owns:\n\n- generic contract-generation machinery;\n- transport-specific adapters and generated implementations;\n- RPC, REST, NATS, and other external encoding and delivery concerns.\n\nFor example, agent-worker requests and results belong to task execution.\nSubprocess, NATS, or HTTP representations are infrastructure implementations of\nthat contract. The same rule applies independently to forge, persistence,\nworkspace, and other service contracts.\n"
"body": "# Dependencies and Contracts\n\n**Status:** Approved foundation \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Dependency direction\n\n```text\ndomain and shared application contracts \u003c- infrastructure implementations\n ^\n |\n application composition\n```\n\nThe following rules are strict:\n\n1. Domains MUST NOT import `internal/infrastructure`.\n2. A domain defines the smallest interfaces required to perform its work.\n3. Infrastructure implements those interfaces and translates external\n representations at the boundary.\n4. Only application composition chooses concrete implementations.\n5. A domain MUST NOT manipulate another domain's state or call its internal\n services.\n6. Cross-domain work uses an explicitly designed command, event, or approved\n shared contract.\n7. Implementation difficulty is not permission to violate a boundary.\n\nBroker messages, database rows, SDK response types, and configuration DTOs MUST\nNOT leak into domain models.\n\n## Commands and events\n\n- An event records something that happened and is owned by its publishing\n domain.\n- A command requests an action and is owned by the domain expected to handle it.\n- Consumers do not redefine an event's meaning.\n- Senders obey the receiving domain's command contract.\n- There is no generic package containing unrelated application messages.\n\n## Event bus\n\n`internal/eventbus` is an approved shared application contract. It defines only\nthe messaging behaviour Archie requires, including publication, subscription,\ndelivery outcomes, and required lifecycle semantics.\n\nIt MUST remain broker-neutral. NATS subjects, JetStream configuration, consumer\ngroups, acknowledgements, reconnection, and serialisation belong under\n`internal/infrastructure/eventbus/nats` unless Archie explicitly requires a\nsemantic guarantee in the shared contract.\n\nMessage schemas stay with their owning domains. The event bus transports\nmessages; it does not own their meaning.\n\n## Wire contracts and generation\n\nCanonical worker and service wire contracts and their authoritative generation\ninputs are owned by the domain or capability that defines their meaning. They\nMUST NOT be centralised in `internal/infrastructure/spec` or another generic\nschema package.\n\nInfrastructure owns:\n\n- generic contract-generation machinery;\n- transport-specific adapters and generated implementations;\n- RPC, REST, NATS, and other external encoding and delivery concerns.\n\nFor example, agent-worker requests and results belong to task execution.\nSubprocess, NATS, or HTTP representations are infrastructure implementations of\nthat contract. The same rule applies independently to forge, persistence,\nworkspace, and other service contracts.\n"
},
{
"url": "/dev/architecture/generated-documentation/",
"title": "Generated Documentation",
"section": "Architecture",
"body": "# Generated Documentation\n\n**Status:** Generator scaffold in place; renderer and publishing removed\n**Date:** 2026-07-28 (revised 2026-09-12)\n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie's documentation-generation approach is:\n\n- production Go code, registries, configuration, and CLI behaviour remain the\n source of truth for published contracts;\n- a repository-local Go generator extracts and normalizes documentation data;\n- the generator writes deterministic JSON/data files and protocol schemas;\n- the rendering and publishing surface is an **open decision** — the VitePress\n site and its Pages deployment were removed on 2026-09-12 as an unnecessary\n build step (see \"Rendering and publishing\" below).\n\nHugo is not part of the target architecture.\n\nThe documentation system is rooted at:\n\n```text\ntools/\n go.mod\n go.sum\n docsgen/\n main.go\ndocs/\n data/generated/\n public/schemas/\n *.md\n```\n\n### Rendering and publishing — OPEN\n\nSuperseded 2026-09-12. The repository previously carried a VitePress site\n(`docs/.vitepress/config.mts`, `docs/package.json`, a 1620-line\n`docs/pnpm-lock.yaml`, `docs/pnpm-workspace.yaml`) built and deployed to GitHub\nPages by `.github/workflows/docs.yml`. It was removed as an unnecessary build\nstep: the published site was never stood up, and the Pages target is not\nconfigured.\n\n`docs/` is now repository documentation only — markdown read in the repository,\nan editor, or a forge's file view. Nothing in the repository builds, renders, or\npublishes it.\n\nThe renderer for the generated `data/generated/*.json` is therefore **undecided**.\nConsequences that follow, and their current state:\n\n| Concern | State after removal |\n| --- | --- |\n| Reference-page rendering | Undecided; `data/generated/contracts.json` is committed but unrendered |\n| Internal link validation | Not enforced by any build; links are repository-relative (`../architecture/...`) and resolve on the filesystem |\n| Generated-data drift detection | Unchanged — `docsgen check` compares committed output, independent of any renderer |\n| Navigation/sidebar | The authoritative index is `docs/prds/01-project-management.md` |\n| Local authoring server | None; read markdown directly |\n\nA future renderer MUST NOT reintroduce a dead-link-blind build: VitePress\npreviously validated internal links during its production build, and no\nreplacement currently does.\n\n## Single source of truth\n\nEvery published capability has one authoritative machine-readable definition\nowned by its domain or application boundary. Generated documentation derives\nfrom those definitions.\n\nGenerated reference includes:\n\n- domain commands and events;\n- Messages and typed message content;\n- Agent and Workflow contracts;\n- WorkflowSteps and Workflow plugin capability contracts;\n- policies and their typed inputs and outcomes;\n- tools and capabilities;\n- CLI commands, arguments, flags, defaults, and help;\n- runtime settings, types, defaults, validation, and secret metadata;\n- public worker and transport contracts;\n- indexes of registered functionality;\n- deprecation information.\n\nHandwritten documents contain:\n\n- architecture decisions and rationale;\n- tutorials and operational guides;\n- examples and walkthroughs;\n- migration guidance;\n- conceptual explanations.\n\nHandwritten documents link to generated reference rather than copying\nauthoritative tables.\n\n## Target generation architecture\n\n`tools/docsgen` is Archie's documentation extractor and normalizer. It produces\nstructured documentation data and protocol specifications. It does not own\npage layout and MUST NOT generate Markdown pages or fragments.\n\nThe generator is divided internally into reusable stages:\n\n```text\nload registries and types\n -\u003e normalize documentation model\n -\u003e validate ownership and identifiers\n -\u003e serialize data and protocol artifacts\n -\u003e compare or write output\n```\n\nThe normalized documentation model prevents each output renderer from\nindependently interpreting Go types. It contains stable documentation IDs,\nowners, names, descriptions, source references, versions, deprecations, fields,\ndefaults, validation, secret classifications, and relationships.\n\nInitial generator targets:\n\n```text\ndocsgen data\ndocsgen asyncapi\ndocsgen all\ndocsgen check\n```\n\n- `data` writes the normalized JSON reference data.\n- `asyncapi` writes protocol schemas and envelopes.\n- `all` generates every committed artifact.\n- `check` generates into a temporary directory and fails on drift.\n\nThe command may use subcommands or an equivalent explicit `--target` flag. It\nMUST retain one normalization and validation path.\n\n## Target output\n\nDuring adaptation, `docs` remains the staging site. Generated outputs live in\na visibly owned subtree:\n\n```text\ndocs/\n data/\n generated/\n cataloLine truncated
"body": "# Generated Documentation\n\n**Status:** Data generation lives here; rendering and publishing live in the external Astro website\n**Date:** 2026-07-28 (revised 2026-09-25)\n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie's documentation-generation approach is:\n\n- production Go code, registries, configuration, and CLI behaviour remain the\n source of truth for published contracts;\n- a repository-local Go generator extracts and normalises documentation data;\n- the generator writes deterministic JSON/data files and protocol schemas;\n- the external Astro website consumes generated data and serves the public\n documentation at `offloaded.dev/docs/`.\n\nHugo is not part of the target architecture.\n\nThe documentation system is rooted at:\n\n```text\ntools/\n go.mod\n go.sum\n docsgen/\n main.go\ndocs/\n data/generated/\n public/schemas/\n *.md\n```\n\n### Rendering and publishing — external Astro website\n\nSuperseded 2026-09-12. The repository previously carried a VitePress site\n(`docs/.vitepress/config.mts`, `docs/package.json`, a 1620-line\n`docs/pnpm-lock.yaml`, `docs/pnpm-workspace.yaml`) built and deployed to GitHub\nPages by `.github/workflows/docs.yml`. It was removed as an unnecessary build\nstep: the published site was never stood up, and the Pages target is not\nconfigured.\n\nThe Astro website is maintained outside this repository. This repository owns\nthe Markdown source and generated JSON artifacts; it does not build, preview, or\ndeploy the site. The external site owns page rendering, navigation, and\npublishing.\n\nThe current boundaries are:\n\n| Concern | Owner |\n| --------------------------------------- | -------------------------------------------------------------------- |\n| Reference-page rendering and publishing | External Astro website |\n| Documentation source and generated data | This repository |\n| Generated-data drift detection | `task docs:check`, `task docs:artifact:check`, and `task news:check` |\n| Navigation data | `docs/data/generated/docs.json` and `dev-docs.json` |\n\nChanges to an artifact contract must be coordinated with the external Astro\nconsumer. This repository does not validate the website's rendered links or\nroutes.\n\n## Single source of truth\n\nEvery published capability has one authoritative machine-readable definition\nowned by its domain or application boundary. Generated documentation derives\nfrom those definitions.\n\nGenerated reference includes:\n\n- domain commands and events;\n- Messages and typed message content;\n- Agent and Workflow contracts;\n- WorkflowSteps and Workflow plugin capability contracts;\n- policies and their typed inputs and outcomes;\n- tools and capabilities;\n- CLI commands, arguments, flags, defaults, and help;\n- runtime settings, types, defaults, validation, and secret metadata;\n- public worker and transport contracts;\n- indexes of registered functionality;\n- deprecation information.\n\nHandwritten documents contain:\n\n- architecture decisions and rationale;\n- tutorials and operational guides;\n- examples and walkthroughs;\n- migration guidance;\n- conceptual explanations.\n\nHandwritten documents link to generated reference rather than copying\nauthoritative tables.\n\n## Target generation architecture\n\n`tools/docsgen` is Archie's documentation extractor and normalizer. It produces\nstructured documentation data and protocol specifications. It does not own\npage layout and MUST NOT generate Markdown pages or fragments.\n\nThe generator is divided internally into reusable stages:\n\n```text\nload registries and types\n -\u003e normalize documentation model\n -\u003e validate ownership and identifiers\n -\u003e serialize data and protocol artifacts\n -\u003e compare or write output\n```\n\nThe normalised documentation model prevents each output renderer from\nindependently interpreting Go types. It contains stable documentation IDs,\nowners, names, descriptions, source references, versions, deprecations, fields,\ndefaults, validation, secret classifications, and relationships.\n\nInitial generator targets:\n\n```text\ndocsgen data\ndocsgen asyncapi\ndocsgen all\ndocsgen check\n```\n\n- `data` writes the normalised JSON reference data.\n- `asyncapi` writes protocol schemas and envelopes.\n- `all` generates every committed artifact.\n- `check` generates into a temporary directory and fails on drift.\n\nThe command may use subcommands or an equivalent explicit `--target` flag. It\nMUST retain one normalisation and validation path.\n\n## Target output\n\nDuring adaptation, `docs` remains the staging site. Generated outputs live in\na visibly owned subtree:\n\n```text\ndocs/\n data/\n geLine truncated
},
{
"url": "/dev/architecture/identity/",
"title": "Identity",
"section": "Architecture",
"body": "# Identity\n\n**Status:** Approved foundation; lifecycle details are deferred \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nIdentity answers which persistent actor owns or performed an action. It supplies\nstable cross-domain attribution and lifecycle semantics.\n\nIdentity kinds include:\n\n- the Archie system identity, such as `System` or `archied`;\n- agent or bot identities;\n- service-account identities;\n- future user identities.\n\nA user is another kind of identity rather than a separate foundation concept.\n\n## Ownership\n\n`internal/domain/identity` owns:\n\n- immutable canonical `IdentityID` values;\n- identity kind;\n- lifecycle state;\n- ownership and attribution semantics;\n- identity-related commands and events.\n\nDomains may record an identity reference on their own state and events when\nownership or attribution is required. They MUST NOT receive a complete\nper-identity application configuration bundle.\n\nPersona and communication style are separate from identity.\n\nEvery Agent has its own immutable acting `IdentityID`. Agent actions use that\nidentity for ownership and attribution in the same way an organisation records\nwhich user accessed a resource, changed a permission, or performed another\nauditable action.\n\nAgent and Identity remain separate aggregates. Identity supplies the stable\nactor reference; Agent owns assistant behaviour, memory, specialisation,\nconversations, and capability context.\n\nAgent identities MUST NOT be shared between Agents. Automated WorkflowExecutions\nMAY eventually act through a dedicated service-account identity when a specific\nunattended automation requires it. Such use is an explicit execution decision\nand audit principal, not the default for Agents or a substitute for recording\nthe initiating user when one exists.\n\nA Workflow is owned by an IdentityID and executes as its owner by default.\nFuture delegated execution MAY explicitly assign a different `RunAsIdentityID`,\nincluding a user or service-account identity. Ownership, effective execution\nidentity, initiating identity, and delegation provenance remain distinct audit\nfacts.\n\n## Canonical identity\n\nEvery identity has an immutable `IdentityID`. It is the only value used for\ncross-domain ownership, attribution, routing, persistence, commands, and events.\n\nIdentity kind is explicit:\n\n- system;\n- bot;\n- service account;\n- user.\n\nDisplay names are mutable and MUST NOT be used as identifiers. Forge usernames,\nchannel bot names, Git authors, provider account names, and other external\nidentifiers are bindings associated with an identity rather than identity\nitself.\n\n`System` is represented by a real identity and `IdentityID`. The empty string\nMUST NOT retain special meaning as a legacy system identity.\n\nConfiguration refers to identities by `IdentityID` and supplies external\nbindings and capability settings separately. Renaming an identity or changing an\nexternal account MUST NOT change ownership or historical attribution.\n\nSecret-bearing channel bindings remain configuration concerns rather than\nidentity data. In particular, `[chat.telegram].token` is a\n`secret.SecretRef` resolved by the application through the configured secret\nregistry; the older `token_env` field remains a compatibility fallback. Neither\nform changes the identity that owns or performs a chat action.\n\n## Persistence\n\nIdentity records are durable domain state. The Identity domain's repository is\nthe source of truth; infrastructure implements its persistence contract.\n\nConfiguration MAY bootstrap a missing identity through an explicit, audited\ncreation operation and MAY propose runtime capability bindings for an existing\n`IdentityID`. Configuration is not the identity registry.\n\nOmitting an identity from configuration stops assembling the omitted runtime\ncapabilities. It MUST NOT delete the identity record, erase history, or make\nhistorical references unresolvable.\n\nDisabling or retiring an identity requires an explicit Identity-domain command.\nRetired identities remain resolvable for historical attribution. A failed\nexternal binding affects capability availability without destroying or silently\nreplacing the identity.\n\n## Lifecycle\n\nIdentity lifecycle is deliberately small:\n\n- `active`: may participate in runtime composition;\n- `suspended`: deliberately prevented from initiating new work while ownership\n and history remain;\n- `retired`: terminal, unable to initiate work, and permanently retained for\n attribution.\n\nAllowed transitions are:\n\n```text\ncreate -\u003e active\nactive -\u003e suspended\nsuspended -\u003e active\nactive -\u003e retired\nsuspended -\u003e retired\n```\n\n`retired` has no outgoing transition.\n\nCapability health is separate from identity lifecycle. Forge, model, channel,\nworkspace, and other bindings report health independently. An active ideLine truncated
"body": "# Identity\n\n**Status:** Approved foundation; lifecycle details are deferred \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nIdentity answers which persistent actor owns or performed an action. It supplies\nstable cross-domain attribution and lifecycle semantics.\n\nIdentity kinds include:\n\n- the Archie system identity, such as `System` or `archied`;\n- agent or bot identities;\n- service-account identities;\n- future user identities.\n\nA user is another kind of identity rather than a separate foundation concept.\n\n## Ownership\n\n`internal/domain/identity` owns:\n\n- immutable canonical `IdentityID` values;\n- identity kind;\n- lifecycle state;\n- ownership and attribution semantics;\n- identity-related commands and events.\n\nDomains may record an identity reference on their own state and events when\nownership or attribution is required. They MUST NOT receive a complete\nper-identity application configuration bundle.\n\nPersona and communication style are separate from identity.\n\nEvery Agent has its own immutable acting `IdentityID`. Agent actions use that\nidentity for ownership and attribution in the same way an organisation records\nwhich user accessed a resource, changed a permission, or performed another\nauditable action.\n\nAgent and Identity remain separate aggregates. Identity supplies the stable\nactor reference; Agent owns assistant behaviour, memory, specialisation,\nconversations, and capability context.\n\nAgent identities MUST NOT be shared between Agents. Automated WorkflowExecutions\nMAY eventually act through a dedicated service-account identity when a specific\nunattended automation requires it. Such use is an explicit execution decision\nand audit principal, not the default for Agents or a substitute for recording\nthe initiating user when one exists.\n\nA Workflow is owned by an IdentityID and executes as its owner by default.\nFuture delegated execution MAY explicitly assign a different `RunAsIdentityID`,\nincluding a user or service-account identity. Ownership, effective execution\nidentity, initiating identity, and delegation provenance remain distinct audit\nfacts.\n\n## Canonical identity\n\nEvery identity has an immutable `IdentityID`. It is the only value used for\ncross-domain ownership, attribution, routing, persistence, commands, and events.\n\nIdentity kind is explicit:\n\n- system;\n- bot;\n- service account;\n- user.\n\nDisplay names are mutable and MUST NOT be used as identifiers. Forge usernames,\nchannel bot names, Git authors, provider account names, and other external\nidentifiers are bindings associated with an identity rather than identity\nitself.\n\n`System` is represented by a real identity and `IdentityID`. The empty string\nMUST NOT retain special meaning as a legacy system identity.\n\nConfiguration refers to identities by `IdentityID` and supplies external\nbindings and capability settings separately. Renaming an identity or changing an\nexternal account MUST NOT change ownership or historical attribution.\n\nSecret-bearing channel bindings remain configuration concerns rather than\nidentity data. In particular, `[chat.telegram].token` is a\n`secret.SecretRef` resolved by the application through the configured secret\nregistry. It does not change the identity that owns or performs a chat action.\n\n## Persistence\n\nIdentity records are durable domain state. The Identity domain's repository is\nthe source of truth; infrastructure implements its persistence contract.\n\nConfiguration MAY bootstrap a missing identity through an explicit, audited\ncreation operation and MAY propose runtime capability bindings for an existing\n`IdentityID`. Configuration is not the identity registry.\n\nOmitting an identity from configuration stops assembling the omitted runtime\ncapabilities. It MUST NOT delete the identity record, erase history, or make\nhistorical references unresolvable.\n\nDisabling or retiring an identity requires an explicit Identity-domain command.\nRetired identities remain resolvable for historical attribution. A failed\nexternal binding affects capability availability without destroying or silently\nreplacing the identity.\n\n## Lifecycle\n\nIdentity lifecycle is deliberately small:\n\n- `active`: may participate in runtime composition;\n- `suspended`: deliberately prevented from initiating new work while ownership\n and history remain;\n- `retired`: terminal, unable to initiate work, and permanently retained for\n attribution.\n\nAllowed transitions are:\n\n```text\ncreate -\u003e active\nactive -\u003e suspended\nsuspended -\u003e active\nactive -\u003e retired\nsuspended -\u003e retired\n```\n\n`retired` has no outgoing transition.\n\nCapability health is separate from identity lifecycle. Forge, model, channel,\nworkspace, and other bindings report health independently. An active identity\nmay be partially degraded without becoming suspended or reLine truncated
},
{
"url": "/dev/architecture/messaging-and-work-intake/",
"title": "Messaging and Work Intake",
"section": "Architecture",
"body": "# Messaging and Work Intake\n\n**Status:** Current state researched; foundation decisions in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is a personal assistant and general agentic system. Its interactions\ninclude conversation, questions, notes, reminders, goals, message handling,\ntroubleshooting, infrastructure operations, server management, source changes,\nand open-ended future capabilities.\n\nA message to an agent is therefore not inherently a work request, and invoking\nan agent is not inherently a WorkflowExecution.\n\nMessaging and work intake are separate from the Agent System's durable workflow\nexecution model:\n\n- messaging preserves interactions with people and external systems;\n- an agent turn interprets and responds to an interaction using its available\n capabilities;\n- work intake handles the optional promotion of an interaction into durable,\n workflow-backed work;\n- the Agent System owns Workflow definitions and creates WorkflowExecutions.\n\nForge issues, Jira issues, Telegram messages, emails, webhooks, and future\nchannels remain peer external message or artifact sources. None becomes an\nexecution model merely because it can lead to work.\n\n## Confirmed boundary\n\nWork intake MUST NOT create a WorkflowExecution directly.\n\nInbound interactions normally route to the Agent selected by the channel\nbinding. The selected Agent retains its own memory, user knowledge, conversation\ncontinuity, specialisation, and capability context. This continuity is\nindependent of the underlying model or provider.\n\nEach selected Agent acts through its own immutable IdentityID. Interaction and\nresulting action records preserve both that acting identity and the initiating\nuser identity when one exists.\n\nAgent memory is private by default. Interaction context MAY additionally use\nuser-wide memory and intentionally global shared memory, but another Agent's\nagent-wide memory is not part of the selected Agent's context.\n\nMultiple users may interact with the same Agent. The channel binding and inbound\nmessage MUST resolve both AgentID and initiating User IdentityID before\nconversation or memory context is loaded. Sharing an Agent MUST NOT implicitly\nshare one user's private memory with another user.\n\nAn interaction may assemble memory from four scopes: global shared, the selected\nAgent's agent-wide memory, the initiating user's authorized user-wide memory,\nand the private Agent-user relationship memory addressed by both IDs.\n\n## Conversation identity\n\nEvery conversation is identified by the complete tuple:\n\n```text\nAgentID\n+ UserIdentityID\n+ ChannelBindingID\n+ ExternalConversationID\n+ ThreadID\n```\n\n`ThreadID` has an explicit empty value for channels without threads. No element\nof this key may be replaced by a display name, configured bot username, channel\ntype, or other mutable label.\n\nAgent and user memory continue across conversations according to their memory\nscope. Immediate conversation history and delivery correlation remain isolated\nto the identified channel conversation or thread. Moving between Telegram,\nemail, or another channel does not create a new Agent or user, but it does\ncreate a distinct conversation unless an explicit linking operation relates\nthem.\n\nConversation and message events support projections for channel-entry metrics,\nuse cases, volumes, outcomes, latency, capability usage, and other product or\noperational analysis. Metrics are derived read models; they MUST NOT become\nmutable counters embedded in the conversation aggregate or change message\nrouting semantics.\n\n## Canonical messages\n\nEvery inbound, assistant, tool-call, and tool-result message has an immutable\napplication-generated MessageID. Platform identifiers are external correlation,\nnot substitutes for the canonical ID.\n\nMessages are addressable because an interaction is more than text. A message may\ncontain assistant content, reasoning data subject to its retention policy, one\nor more tool calls, a tool result with authoritative execution metadata,\nattachments, reply relationships, edits, or other typed content. Stable\nMessageIDs also allow sessions to branch from an exact prior point.\n\nThe canonical session and message implementation must supply:\n\n- application-generated stable message IDs;\n- user, assistant, and tool roles;\n- assistant tool calls and correlated tool-result messages;\n- authoritative tool-result status, timing, error, truncation, and size\n metadata;\n- session lifecycle and active-request state;\n- session-to-agent-instance and parent-session lineage;\n- durable SQLite round trips and timestamp validation.\n\nThese semantics must use the confirmed Agent, user, channel-binding, and\nconversation ownership model.\n\nThe canonical message store MUST preserve messages as immutable records and\nrepresent later edits, deletions,Line truncated
"body": "# Messaging and Work Intake\n\n**Status:** Current state researched; foundation decisions in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is a personal assistant and general agentic system. Its interactions\ninclude conversation, questions, notes, reminders, goals, message handling,\ntroubleshooting, infrastructure operations, server management, source changes,\nand open-ended future capabilities.\n\nA message to an agent is therefore not inherently a work request, and invoking\nan agent is not inherently a WorkflowExecution.\n\nMessaging and work intake are separate from the Agent System's durable workflow\nexecution model:\n\n- messaging preserves interactions with people and external systems;\n- an agent turn interprets and responds to an interaction using its available\n capabilities;\n- work intake handles the optional promotion of an interaction into durable,\n workflow-backed work;\n- the Agent System owns Workflow definitions and creates WorkflowExecutions.\n\nForge issues, Jira issues, Telegram messages, emails, webhooks, and future\nchannels remain peer external message or artifact sources. None becomes an\nexecution model merely because it can lead to work.\n\n## Confirmed boundary\n\nWork intake MUST NOT create a WorkflowExecution directly.\n\nInbound interactions normally route to the Agent selected by the channel\nbinding. The selected Agent retains its own memory, user knowledge, conversation\ncontinuity, specialisation, and capability context. This continuity is\nindependent of the underlying model or provider.\n\nEach selected Agent acts through its own immutable IdentityID. Interaction and\nresulting action records preserve both that acting identity and the initiating\nuser identity when one exists.\n\nAgent memory is private by default. Interaction context MAY additionally use\nuser-wide memory and intentionally global shared memory, but another Agent's\nagent-wide memory is not part of the selected Agent's context.\n\nMultiple users may interact with the same Agent. The channel binding and inbound\nmessage MUST resolve both AgentID and initiating User IdentityID before\nconversation or memory context is loaded. Sharing an Agent MUST NOT implicitly\nshare one user's private memory with another user.\n\nAn interaction may assemble memory from four scopes: global shared, the selected\nAgent's agent-wide memory, the initiating user's authorised user-wide memory,\nand the private Agent-user relationship memory addressed by both IDs.\n\n## Conversation identity\n\nEvery conversation is identified by the complete tuple:\n\n```text\nAgentID\n+ UserIdentityID\n+ ChannelBindingID\n+ ExternalConversationID\n+ ThreadID\n```\n\n`ThreadID` has an explicit empty value for channels without threads. No element\nof this key may be replaced by a display name, configured bot username, channel\ntype, or other mutable label.\n\nAgent and user memory continue across conversations according to their memory\nscope. Immediate conversation history and delivery correlation remain isolated\nto the identified channel conversation or thread. Moving between Telegram,\nemail, or another channel does not create a new Agent or user, but it does\ncreate a distinct conversation unless an explicit linking operation relates\nthem.\n\nConversation and message events support projections for channel-entry metrics,\nuse cases, volumes, outcomes, latency, capability usage, and other product or\noperational analysis. Metrics are derived read models; they MUST NOT become\nmutable counters embedded in the conversation aggregate or change message\nrouting semantics.\n\n## Canonical messages\n\nEvery inbound, assistant, tool-call, and tool-result message has an immutable\napplication-generated MessageID. Platform identifiers are external correlation,\nnot substitutes for the canonical ID.\n\nMessages are addressable because an interaction is more than text. A message may\ncontain assistant content, reasoning data subject to its retention policy, one\nor more tool calls, a tool result with authoritative execution metadata,\nattachments, reply relationships, edits, or other typed content. Stable\nMessageIDs also allow sessions to branch from an exact prior point.\n\nThe canonical session and message implementation must supply:\n\n- application-generated stable message IDs;\n- user, assistant, and tool roles;\n- assistant tool calls and correlated tool-result messages;\n- authoritative tool-result status, timing, error, truncation, and size\n metadata;\n- session lifecycle and active-request state;\n- session-to-agent-instance and parent-session lineage;\n- durable database round trips and timestamp validation.\n\nThese semantics must use the confirmed Agent, user, channel-binding, and\nconversation ownership model.\n\nThe canonical message store MUST preserve messages as immutable records and\nrepresent later edits, deletionLine truncated
},
{
"url": "/dev/architecture/migration-decisions/",
"title": "Architecture Migration Decisions",
"section": "Architecture",
"body": "# Architecture Migration Decisions\n\n**Status:** Active migration inventory \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nThis document records what remains to be decided before Archie's current\nimplementation can be migrated into the approved domain-oriented structure.\n\nThe product and core domain model are not being redesigned. Existing Archie\nbehaviour and the existing session implementation are the migration\nbaseline. Remaining decisions MUST be grounded in current packages, consumers,\ntests, persistence, and runtime wiring.\n\n## Confirmed domain packages\n\n```text\ninternal/domain/\n identity/ (approved, not yet materialised as a package)\n agent/ (approved, not yet materialised as a package)\n workflow/\n messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)\n workintake/\n plugin/ (approved, not yet materialised as a package)\n curator/\n mapping/\n scheduling/\n```\n\n- `identity` owns persistent actors, lifecycle, ownership, attribution, and\n audit identity.\n- `agent` owns persistent assistants, specialisation, instructions,\n model-independent continuity, capability context, and associations with\n identity and memory.\n- `workflow` is a separate domain. It owns reusable, versioned Workflow\n definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts,\n outcomes, and typed Workflow plugin contracts.\n- `messaging` owns canonical Messages, Conversations, branches, channel and\n source correlation, replies, acknowledgements, delivery attempts, events, and\n projections.\n- `workintake` owns admission, validation, deterministic routing, and accepted\n work requests for the optional transition into durable workflow-backed\n execution.\n- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle\n mechanics. It remains metadata-only; capability semantics and typed\n registration belong to the owning domain.\n- `curator` owns the curator engine family: long-running agent loops that\n reason over memory and perform maintenance tasks on a declared shape\n (check-in interval, tool set, attached memory engine). See epic\n archie-core-yp9.\n- `mapping` owns the payload field-mapping vocabulary: binding named fields to\n JSON paths inside a captured webhook payload, and detecting drift. See\n `docs/prds/payload-field-mapping.md`.\n- `scheduling` owns the ticker engine: deciding when a scheduled job runs and\n with what concurrency. It declares `JobSource`/`Runner` contracts and owns\n no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.\n\n**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed\nin the tree without being added to this list when their epics landed. They are\nconfirmed as legitimate, narrowly-scoped domains under the same rules as the\noriginal six — each owns one capability family, declares typed contracts, and\nhas no cross-domain reach. This list was out of date, not the tree.\n\nConversely, `identity`, `agent`, `messaging`, and `plugin` are approved target\ndomains that do not yet exist as packages. Their behaviour currently lives in\npre-migration packages (see \"Complete package destination map\" below for the\nfull inventory). Do **not** create empty stub packages for them ahead of an\nactual migration PR — an unused stub is dead code and gives no test coverage.\nEach materialises when its corresponding migration decision below is resolved\nand implemented in the same change.\n\nMemory's final package placement remains undecided pending focused review of the\nexisting implementation.\n\nThe following are approved shared or composition packages, not domains:\n\n```text\ninternal/eventbus/\ninternal/policy/\ninternal/infrastructure/\ninternal/app/archied/\ninternal/app/agentworker/\n```\n\n## Remaining migration decisions\n\n### 1. Complete package destination map\n\nEvery current package MUST receive one explicit disposition:\n\n- move into a confirmed domain;\n- move under infrastructure as an implementation of a domain-owned contract;\n- move into application composition;\n- merge with an identified duplicate;\n- remain as an approved shared application contract;\n- move to a plugin, extra, deployment, example, or generated artifact;\n- be deleted after its replacement is proven.\n\nThe largest unreviewed areas include memory, tools and capabilities, workspace\nand worktree behaviour, gates, storage, events, web UI, containers, RPC\npackages, release management, and scheduling.\n\nThe destination matrix MUST name the behaviour owner, target path, dependencies\nto remove, state and contracts to preserve, migration prerequisites, and\ndeletion criteria.\n\n**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**\nThe current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator\nauthLine truncated
"body": "# Architecture Migration Decisions\n\n**Status:** Active migration inventory \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nThis document records what remains to be decided before Archie's current\nimplementation can be migrated into the approved domain-oriented structure.\n\nThe product and core domain model are not being redesigned. Existing Archie\nbehaviour and the existing session implementation are the migration\nbaseline. Remaining decisions MUST be grounded in current packages, consumers,\ntests, persistence, and runtime wiring.\n\n## Confirmed domain packages\n\n```text\ninternal/domain/\n identity/ (approved, not yet materialised as a package)\n agent/ (approved, not yet materialised as a package)\n workflow/\n messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)\n workintake/\n plugin/ (approved, not yet materialised as a package)\n curator/\n mapping/\n scheduling/\n```\n\n- `identity` owns persistent actors, lifecycle, ownership, attribution, and\n audit identity.\n- `agent` owns persistent assistants, specialisation, instructions,\n model-independent continuity, capability context, and associations with\n identity and memory.\n- `workflow` is a separate domain. It owns reusable, versioned Workflow\n definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts,\n outcomes, and typed Workflow plugin contracts.\n- `messaging` owns canonical Messages, Conversations, branches, channel and\n source correlation, replies, acknowledgements, delivery attempts, events, and\n projections.\n- `workintake` owns admission, validation, deterministic routing, and accepted\n work requests for the optional transition into durable workflow-backed\n execution.\n- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle\n mechanics. It remains metadata-only; capability semantics and typed\n registration belong to the owning domain.\n- `curator` owns the curator engine family: long-running agent loops that\n reason over memory and perform maintenance tasks on a declared shape\n (check-in interval, tool set, attached memory engine). See epic\n archie-core-yp9.\n- `mapping` owns the payload field-mapping vocabulary: binding named fields to\n JSON paths inside a captured webhook payload, and detecting drift. See\n `docs/prds/payload-field-mapping.md`.\n- `scheduling` owns the ticker engine: deciding when a scheduled job runs and\n with what concurrency. It declares `JobSource`/`Runner` contracts and owns\n no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.\n\n**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed\nin the tree without being added to this list when their epics landed. They are\nconfirmed as legitimate, narrowly-scoped domains under the same rules as the\noriginal six — each owns one capability family, declares typed contracts, and\nhas no cross-domain reach. This list was out of date, not the tree.\n\nConversely, `identity`, `agent`, `messaging`, and `plugin` are approved target\ndomains that do not yet exist as packages. Their behaviour currently lives in\npre-migration packages (see \"Complete package destination map\" below for the\nfull inventory). Do **not** create empty stub packages for them ahead of an\nactual migration PR — an unused stub is dead code and gives no test coverage.\nEach materialises when its corresponding migration decision below is resolved\nand implemented in the same change.\n\nMemory's final package placement remains undecided pending focused review of the\nexisting implementation.\n\nThe following are approved shared or composition packages, not domains:\n\n```text\ninternal/eventbus/\ninternal/policy/\ninternal/infrastructure/\ninternal/app/archied/\ninternal/app/agentworker/\n```\n\n## Remaining migration decisions\n\n### 1. Complete package destination map\n\nEvery current package MUST receive one explicit disposition:\n\n- move into a confirmed domain;\n- move under infrastructure as an implementation of a domain-owned contract;\n- move into application composition;\n- merge with an identified duplicate;\n- remain as an approved shared application contract;\n- move to a plugin, extra, deployment, example, or generated artifact;\n- be deleted after its replacement is proven.\n\nThe largest unreviewed areas include memory, tools and capabilities, workspace\nand worktree behaviour, gates, storage, events, web UI, containers, RPC\npackages, release management, and scheduling.\n\nThe destination matrix MUST name the behaviour owner, target path, dependencies\nto remove, state and contracts to preserve, migration prerequisites, and\ndeletion criteria.\n\n**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**\nThe current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator\nauthLine truncated
},
{
"url": "/dev/architecture/observability/",
"title": "Task Observability",
"section": "Architecture",
"body": "# Task Observability\n\n**Status:** Implemented. The per-run detail surface was added on 2026-09-18 and\nis described below.\n**Date:** 2026-08-09 (revised 2026-09-18)\n\n## Historical problem\n\narchied's own daemon logging (`internal/logging/`) was already solid: a\nrotating file sink, a live `Feed` the dashboard subscribes to, and a reader\nthe `/api/logs` endpoint serves from. Before this implementation, none of\nthat reached inside a task.\n\nA task's actual work happens in a task-scoped `archie-agent` container,\ndispatched as one complete workflow over NATS.\nBefore this design was implemented, five things destroyed the evidence of what\nthat container did:\n\n1. **Worker startup** constructed an stderr-only logger and never replaced its\n handler after discovering a dedicated boot task, so runtime records could\n not leave the container.\n2. **`internal/container/pool.go`** creates every task container with\n `AutoRemove: true`. The container — and its stderr — is gone at exit,\n success or failure alike.\n3. **`internal/domain/workflow/implement.go`, `StageBaselineGate`** captures\n `go build`/`go vet`/`go test` output via `cmd.CombinedOutput()`, then\n clips it to 200 characters into a `Warn` log line and discards the rest.\n The eventual park reason is built from `res.Status` alone — the actual\n compiler error is never persisted anywhere a human or Archie's own chat\n tools can read it back.\n4. **`agentexec.Result`** (`internal/agentexec/protocol.go`) carries only\n `Summary`/`Detail` — no step-by-step transcript (tool calls, durations,\n errors). There is no transcript to recover even in principle.\n5. **`agentexec.SubjectForSystem`** is documented as the return channel for\n exactly this — *\"log dumps, health, and PII warnings... the daemon reads\n these for observability and never forwards them\"* — but has no publisher\n and no consumer anywhere in the codebase except a subject-format\n assertion in `nats_test.go`. The designed return path was never wired.\n\nThe practical consequence: a task parks with\n`stage baseline: baseline red -- go build ./... fails and builder could not\nauto-fix (status: parked)` and there is no way — not from the dashboard, not\nfrom Telegram chat, not by SSH'ing into the deployment host — to see *why*\n`go build` failed. The container that knew is already gone.\n\nThis matters beyond debugging convenience: supported deployments can combine\na resident daemon with ephemeral Docker containers that run unattended for\nweeks between operator logins, and the system is\nintended to be usable by people other than the original operator. A system\nthat is only debuggable by an operator who happens to be watching `docker ps`\nin real time does not meet that bar.\n\n## Decision: NATS is the sole autonomous handoff\n\nThe agent image must reach NATS in every deployment, because the broker is the\nonly autonomous task handoff and the only channel carrying task results back\nto the daemon. `archied` has no workflow runner or host fallback. A container\nthat dies before establishing a NATS connection is a distinct, narrower\nfailure (connectivity/config) from the one this document addresses (a connected\ncontainer's own output being unrecoverable), and is out of scope here.\n\n## Implemented design\n\nThe key property: **logs leave the container while it is alive**, so its\ndeath at `AutoRemove` no longer matters. Persistence happens in the daemon\nprocess, which already owns durable state.\n\n### Sink: extend `internal/logging`, not a new package\n\n`internal/logging` already owns its on-disk format end to end per\n`organisation.md` (\"a package owns its own format end to end\"). Add a\ntask-scoped writer producing the same `logging.Entry` JSONL shape at\n`\u003cstate_dir\u003e/logs/tasks/\u003ctask_id\u003e/attempt-\u003cn\u003e.jsonl`. `logging.Tail`,\n`logging.Query`, and `logging.Components` operate on this unchanged;\n`internal/webui/api_logs.go` stays transport-only, as it does today.\n\n### Agent side: make the designed subject real\n\n`internal/app/agentworker` replaces the stderr-only `slog.Handler` with one\nthat tees to stderr (kept for container-level operator debugging when a\nshell is attached) and publishes each record to\n`agentexec.SubjectForSystem(taskID)`, which already exists for this purpose.\nThe application layer obtains only a narrow publisher from\n`internal/infrastructure/agenttransport/nats`; raw core-NATS types remain in\ninfrastructure. `internal/infrastructure/agentboot.TaskID` reads the task ID\nfrom `\u003cworktree\u003e/.git/task.json` per the container/pool.go trap documented in\n`CLAUDE.md`. Publishing is fire-and-forget: log shipping must never block or\nfail the run it is reporting on.\n\n### Daemon side\n\n`cmd/archied/main.go` registers `subscribeSystemLogs` once at startup on\n`agentexec.SubjectSystemWildcard`. It demultiplexes by task ID, appends to that task's\nsink, and pLine truncated
"body": "# Task Observability\n\n**Status:** Implemented. The per-run detail surface was added on 2026-09-18 and\nis described below.\n**Date:** 2026-08-09 (revised 2026-09-18)\n\n## Historical problem\n\narchied's own daemon logging (`internal/logging/`) was already solid: a\nrotating file sink, a live `Feed` the dashboard subscribes to, and a reader\nthe `/api/logs` endpoint serves from. Before this implementation, none of\nthat reached inside a task.\n\nA task's actual work happens in a task-scoped `archie-agent` container,\ndispatched as one complete workflow over NATS.\nBefore this design was implemented, five things destroyed the evidence of what\nthat container did:\n\n1. **Worker startup** constructed an stderr-only logger and never replaced its\n handler after discovering a dedicated boot task, so runtime records could\n not leave the container.\n2. **`internal/container/pool.go`** creates every task container with\n `AutoRemove: true`. The container — and its stderr — is gone at exit,\n success or failure alike.\n3. **`internal/domain/workflow/implement.go`, `StageBaselineGate`** captures\n `go build`/`go vet`/`go test` output via `cmd.CombinedOutput()`, then\n clips it to 200 characters into a `Warn` log line and discards the rest.\n The eventual park reason is built from `res.Status` alone — the actual\n compiler error is never persisted anywhere a human or Archie's own chat\n tools can read it back.\n4. **`agentexec.Result`** (`internal/agentexec/protocol.go`) carries only\n `Summary`/`Detail` — no step-by-step transcript (tool calls, durations,\n errors). There is no transcript to recover even in principle.\n5. **`agentexec.SubjectForSystem`** is documented as the return channel for\n exactly this — _\"log dumps, health, and PII warnings... the daemon reads\n these for observability and never forwards them\"_ — but has no publisher\n and no consumer anywhere in the codebase except a subject-format\n assertion in `nats_test.go`. The designed return path was never wired.\n\nThe practical consequence: a task parks with\n`stage baseline: baseline red -- go build ./... fails and builder could not\nauto-fix (status: parked)` and there is no way — not from the dashboard, not\nfrom Telegram chat, not by SSH'ing into the deployment host — to see _why_\n`go build` failed. The container that knew is already gone.\n\nThis matters beyond debugging convenience: supported deployments can combine\na resident daemon with ephemeral Docker containers that run unattended for\nweeks between operator logins, and the system is\nintended to be usable by people other than the original operator. A system\nthat is only debuggable by an operator who happens to be watching `docker ps`\nin real time does not meet that bar.\n\n## Decision: NATS is the sole autonomous handoff\n\nThe agent image must reach NATS in every deployment, because the broker is the\nonly autonomous task handoff and the only channel carrying task results back\nto the daemon. `archied` has no workflow runner or host fallback. A container\nthat dies before establishing a NATS connection is a distinct, narrower\nfailure (connectivity/config) from the one this document addresses (a connected\ncontainer's own output being unrecoverable), and is out of scope here.\n\n## Implemented design\n\nThe key property: **logs leave the container while it is alive**, so its\ndeath at `AutoRemove` no longer matters. Persistence happens in the daemon\nprocess, which already owns durable state.\n\n### Sink: extend `internal/logging`, not a new package\n\n`internal/logging` already owns its on-disk format end to end per\n`organisation.md` (\"a package owns its own format end to end\"). Add a\ntask-scoped writer producing the same `logging.Entry` JSONL shape at\n`\u003cstate_dir\u003e/logs/tasks/\u003ctask_id\u003e/attempt-\u003cn\u003e.jsonl`. `logging.Tail`,\n`logging.Query`, and `logging.Components` operate on this unchanged;\n`internal/webui/api_logs.go` stays transport-only, as it does today.\n\n### Agent side: make the designed subject real\n\n`internal/app/agentworker` replaces the stderr-only `slog.Handler` with one\nthat tees to stderr (kept for container-level operator debugging when a\nshell is attached) and publishes each record to\n`agentexec.SubjectForSystem(taskID)`, which already exists for this purpose.\nThe application layer obtains only a narrow publisher from\n`internal/infrastructure/agenttransport/nats`; raw core-NATS types remain in\ninfrastructure. `internal/infrastructure/agentboot.TaskID` reads the task ID\nfrom `\u003cworktree\u003e/.git/task.json` per the container/pool.go trap documented in\n`CLAUDE.md`. Publishing is fire-and-forget: log shipping must never block or\nfail the run it is reporting on.\n\n### Daemon side\n\n`cmd/archied/main.go` registers `subscribeSystemLogs` once at startup on\n`agentexec.SubjectSystemWildcard`. It demultiplexes by task ID, appends to that task's\nsink, and pLine truncated
},
{
"url": "/dev/architecture/organisation/",
@@ -82,91 +82,151 @@
"url": "/dev/architecture/package-review/",
"title": "Domain and Feature Review Procedure",
"section": "Architecture",
"body": "# Domain and Feature Review Procedure\n\n**Status:** Active \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchitecture work proceeds one domain or feature at a time. Before any design\nquestion, the selected area is researched across its complete live\nimplementation, consumers, tests, state, configuration, and runtime wiring.\n\nExisting packages are evidence, not the unit that drives the interview.\nPlacement follows behaviour and ownership, not the existing directory name.\n\nNo restructuring implementation begins until the relevant package decisions\nare agreed and recorded in the focused domain or requirement document.\n\n## Required research\n\nBefore design questions, the current-state report MUST identify:\n\n- entry points and runtime composition;\n- state, persistence, and lifecycle;\n- public and internal contracts;\n- commands, events, and policy enforcement;\n- configuration and defaults;\n- all consumers and cross-domain interactions;\n- process and infrastructure boundaries;\n- tests, failure behaviour, and known invariants;\n- duplicated or conflicting implementations;\n- documentation that disagrees with live code.\n\nDiscoverable facts MUST be investigated rather than presented to the user as\ndesign questions.\n\n## Required decisions\n\nEach package review records:\n\n| Decision | Required result |\n|---|---|\n| Owned behaviour | The cohesive job the code performs |\n| Domain ownership | The owner of the behaviour and vocabulary |\n| Final location | Its target path |\n| Public contracts | The smallest interfaces, commands, and events exposed |\n| Required services | Domain-defined interfaces implemented by infrastructure |\n| State ownership | The owner of each mutable record and transition |\n| Dependencies | Allowed imports and dependencies to remove |\n| Duplication | Code to consolidate, delete, or keep separate |\n| Plugin status | Core domain, shared contract, infrastructure, plugin, or extra |\n| Process boundary | In-process, or the concrete reason for isolation |\n| Configuration | Settings owned by the domain or plugin |\n| Policy | Definitions, evaluators, consequences, and shared mechanics used |\n| Documentation | Authoritative definitions and generated reference |\n| Migration constraints | Behaviour and data that must remain correct |\n\n## Interview method\n\nFor every selected domain or feature:\n\n1. Declare the single area under review.\n2. Complete the current-state research.\n3. Explain actual behaviour in plain technical language.\n4. Separate facts from design decisions and concerns.\n5. Resolve obvious consequences directly and ask only questions whose answer\n materially changes behaviour or structure.\n6. Record each confirmed decision in its focused document.\n7. Complete that area's handoff before selecting another.\n8. Keep unrelated domains outside the implementation scope.\n"
"body": "# Domain and Feature Review Procedure\n\n**Status:** Active \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchitecture work proceeds one domain or feature at a time. Before any design\nquestion, the selected area is researched across its complete live\nimplementation, consumers, tests, state, configuration, and runtime wiring.\n\nExisting packages are evidence, not the unit that drives the interview.\nPlacement follows behaviour and ownership, not the existing directory name.\n\nNo restructuring implementation begins until the relevant package decisions\nare agreed and recorded in the focused domain or requirement document.\n\n## Required research\n\nBefore design questions, the current-state report MUST identify:\n\n- entry points and runtime composition;\n- state, persistence, and lifecycle;\n- public and internal contracts;\n- commands, events, and policy enforcement;\n- configuration and defaults;\n- all consumers and cross-domain interactions;\n- process and infrastructure boundaries;\n- tests, failure behaviour, and known invariants;\n- duplicated or conflicting implementations;\n- documentation that disagrees with live code.\n\nDiscoverable facts MUST be investigated rather than presented to the user as\ndesign questions.\n\n## Required decisions\n\nEach package review records:\n\n| Decision | Required result |\n| --------------------- | ---------------------------------------------------------------- |\n| Owned behaviour | The cohesive job the code performs |\n| Domain ownership | The owner of the behaviour and vocabulary |\n| Final location | Its target path |\n| Public contracts | The smallest interfaces, commands, and events exposed |\n| Required services | Domain-defined interfaces implemented by infrastructure |\n| State ownership | The owner of each mutable record and transition |\n| Dependencies | Allowed imports and dependencies to remove |\n| Duplication | Code to consolidate, delete, or keep separate |\n| Plugin status | Core domain, shared contract, infrastructure, plugin, or extra |\n| Process boundary | In-process, or the concrete reason for isolation |\n| Configuration | Settings owned by the domain or plugin |\n| Policy | Definitions, evaluators, consequences, and shared mechanics used |\n| Documentation | Authoritative definitions and generated reference |\n| Migration constraints | Behaviour and data that must remain correct |\n\n## Interview method\n\nFor every selected domain or feature:\n\n1. Declare the single area under review.\n2. Complete the current-state research.\n3. Explain actual behaviour in plain technical language.\n4. Separate facts from design decisions and concerns.\n5. Resolve obvious consequences directly and ask only questions whose answer\n materially changes behaviour or structure.\n6. Record each confirmed decision in its focused document.\n7. Complete that area's handoff before selecting another.\n8. Keep unrelated domains outside the implementation scope.\n"
},
{
"url": "/dev/architecture/plugins-and-extensions/",
"title": "Plugins and Extensions",
"section": "Architecture",
"body": "# Plugins and Extensions\n\n**Status:** Approved foundation \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Plugin framework\n\nThe core plugin domain lives under `internal/domain/plugin`. It owns:\n\n- plugin identity and metadata;\n- discovery and registration contracts;\n- lifecycle rules;\n- capability registration;\n- validation and compatibility rules.\n\nThe generic plugin contract remains metadata-only. Functionality is exposed\nthrough narrow typed capability contracts with an owning registry or manager.\n\nWorkflow plugins belong to the Workflow capability family. The Workflow domain\nat `internal/domain/workflow` owns their typed registration, validation,\nversioning, definition, and execution contracts. The generic plugin domain may\nprovide plugin identity, discovery, compatibility, and lifecycle mechanics, but\nit MUST NOT define Workflow semantics or expose untyped Workflow hooks.\n\n## Plugin engine rule (strict)\n\n“Engine” is reserved for a typed, lifecycle-managed capability family. It is not\na synonym for a generic plugin hook. Every new plugin engine must satisfy all of\nthese invariants:\n\n1. **Typed domain contract.** The engine interface exposes real\n capability-specific operations in addition to identity metadata. Examples are\n resolving a secret, delivering a message, or running an agent. A plugin that\n only exposes `Name` and `Version` is metadata, not an engine.\n2. **Owning family manager.** The capability package owns a `Registry` or\n `Manager` that controls provider registration and discovery, initialization,\n or access. Providers do not register arbitrary callbacks directly on the\n daemon.\n3. **Lifecycle and health.** When an implementation owns resources or background\n work, its typed family contract must expose start, health, and stop\n semantics. The owning manager invokes them and defines failure isolation and\n shutdown ordering. Stateless providers may make these operations explicit\n no-ops.\n4. **Narrow host access.** Plugins receive the typed family registrar and only\n the host services their declared capability requires. They never receive\n `*daemon.Daemon`, a service locator, or an untyped hook map.\n5. **Metadata-only generic plugin contract.** `plugin.Plugin` remains limited to\n `Name()` and `Version()`. Domain hooks belong on typed engine interfaces;\n adding capability methods to the generic interface is forbidden.\n6. **Trust boundary stays explicit.** Explicitly trusted, operator-installed\n plugins—including third-party secret-engine plugins the operator chooses to\n trust—may run in-process and have daemon privileges. Repository-supplied code\n runs in the task container. Integrations that are not trusted as daemon code\n run out of process through MCP or a versioned protocol and, when a\n confidentiality or integrity boundary is required, inside a real container\n sandbox. A subprocess boundary alone is not a security sandbox, and calling\n Yaegi-loaded code a plugin does not isolate it.\n\n`internal/plugin/architecture_test.go` enforces the mechanically testable parts\nof this rule: the generic plugin method set, the shared agent-instruction\nsource, and the requirement that engine interfaces have domain behavior plus an\nowning registry or manager.\n\n### Memory engine family\n\nOne engine, addressed by four typed scopes -- `ScopeGlobal`, `ScopeAgent`,\n`ScopeUser`, `ScopeAgentUser` (`internal/domain/memory`, `Scope`/`ScopeKind`).\nA caller names exactly the scopes it may read or write; the engine applies no\naccess policy of its own, so isolation falls out mechanically because\n`ScopeAgent{a}` and `ScopeAgent{b}` are different storage keys. See\n`docs/prds/memory-engine-unification.md` for the decision this contract\nimplements; it superseded `internal/memory` (`MemoryProvider`/`Manager`),\ndeleted in that PRD's slice 5.\n\n`MemoryEngine` (`internal/domain/memory/contract.go`) is the typed family\ncontract: `Create`, `Get`, `Query`, `List`, `Update`, `Forget`, `Revisions` --\nCRUD with revisions retained, not just create/read/delete. `Update` supersedes\nrather than overwrites: the superseded state is appended to the scope's\n`HISTORY.md` before the live block is replaced, and `Update` carries no\n`Scope` field, so a record can never change scope. The family's content\nscanner (prompt-injection / sensitive-data patterns) is applied inside\n`Create` and `Update`, the single choke point every producer crosses.\n\n`internal/domain/memory.Registry` is the owning family registry: registration,\nstart/health/stop, shutdown ordering, and failure isolation, following the\nplugin engine rule above. `internal/infrastructure/memory.NewBuiltinEngine` is\nthe only registered engine today; it persists through\n`internal/infrastructure/memory/builtin`, a markdown store (`MEMORY.md`-shaped\nper-scope files) that owns its on-diLine truncated
"body": "# Plugins and Extensions\n\n**Status:** Approved foundation \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Plugin framework\n\nThe core plugin domain lives under `internal/domain/plugin`. It owns:\n\n- plugin identity and metadata;\n- discovery and registration contracts;\n- lifecycle rules;\n- capability registration;\n- validation and compatibility rules.\n\nThe generic plugin contract remains metadata-only. Functionality is exposed\nthrough narrow typed capability contracts with an owning registry or manager.\n\nWorkflow plugins belong to the Workflow capability family. The Workflow domain\nat `internal/domain/workflow` owns their typed registration, validation,\nversioning, definition, and execution contracts. The generic plugin domain may\nprovide plugin identity, discovery, compatibility, and lifecycle mechanics, but\nit MUST NOT define Workflow semantics or expose untyped Workflow hooks.\n\n## Plugin engine rule (strict)\n\n“Engine” is reserved for a typed, lifecycle-managed capability family. It is not\na synonym for a generic plugin hook. Every new plugin engine must satisfy all of\nthese invariants:\n\n1. **Typed domain contract.** The engine interface exposes real\n capability-specific operations in addition to identity metadata. Examples are\n resolving a secret, delivering a message, or running an agent. A plugin that\n only exposes `Name` and `Version` is metadata, not an engine.\n2. **Owning family manager.** The capability package owns a `Registry` or\n `Manager` that controls provider registration and discovery, initialisation,\n or access. Providers do not register arbitrary callbacks directly on the\n daemon.\n3. **Lifecycle and health.** When an implementation owns resources or background\n work, its typed family contract must expose start, health, and stop\n semantics. The owning manager invokes them and defines failure isolation and\n shutdown ordering. Stateless providers may make these operations explicit\n no-ops.\n4. **Narrow host access.** Plugins receive the typed family registrar and only\n the host services their declared capability requires. They never receive\n `*daemon.Daemon`, a service locator, or an untyped hook map.\n5. **Metadata-only generic plugin contract.** `plugin.Plugin` remains limited to\n `Name()` and `Version()`. Domain hooks belong on typed engine interfaces;\n adding capability methods to the generic interface is forbidden.\n6. **Trust boundary stays explicit.** Explicitly trusted, operator-installed\n plugins—including third-party secret-engine plugins the operator chooses to\n trust—may run in-process and have daemon privileges. Repository-supplied code\n runs in the task container. Integrations that are not trusted as daemon code\n run out of process through MCP or a versioned protocol and, when a\n confidentiality or integrity boundary is required, inside a real container\n sandbox. A subprocess boundary alone is not a security sandbox, and calling\n Yaegi-loaded code a plugin does not isolate it.\n\n`internal/plugin/architecture_test.go` enforces the mechanically testable parts\nof this rule: the generic plugin method set, the shared agent-instruction\nsource, and the requirement that engine interfaces have domain behaviour plus an\nowning registry or manager.\n\n### Memory engine family\n\nOne engine, addressed by four typed scopes -- `ScopeGlobal`, `ScopeAgent`,\n`ScopeUser`, `ScopeAgentUser` (`internal/domain/memory`, `Scope`/`ScopeKind`).\nA caller names exactly the scopes it may read or write; the engine applies no\naccess policy of its own, so isolation falls out mechanically because\n`ScopeAgent{a}` and `ScopeAgent{b}` are different storage keys. See\n`docs/prds/memory-engine-unification.md` for the decision this contract\nimplements; it superseded `internal/memory` (`MemoryProvider`/`Manager`),\ndeleted in that PRD's slice 5.\n\n`MemoryEngine` (`internal/domain/memory/contract.go`) is the typed family\ncontract: `Create`, `Get`, `Query`, `List`, `Update`, `Forget`, `Revisions` --\nCRUD with revisions retained, not just create/read/delete. `Update` supersedes\nrather than overwrites: the superseded state is appended to the scope's\n`HISTORY.md` before the live block is replaced, and `Update` carries no\n`Scope` field, so a record can never change scope. The family's content\nscanner (prompt-injection / sensitive-data patterns) is applied inside\n`Create` and `Update`, the single choke point every producer crosses.\n\n`internal/domain/memory.Registry` is the owning family registry: registration,\nstart/health/stop, shutdown ordering, and failure isolation, following the\nplugin engine rule above. `internal/infrastructure/memory.NewBuiltinEngine` is\nthe only registered engine today; it persists through\n`internal/infrastructure/memory/builtin`, a markdown store (`MEMORY.md`-shaped\nper-scope files) that owns its on-dLine truncated
},
{
"url": "/dev/architecture/policy/",
"title": "Policy System",
"section": "Architecture",
"body": "# Policy System\n\n**Status:** Approved foundation; exact API is deferred \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nRetry limits, authorization, gates, commands, protected paths, tool\navailability, and similar rules define or constrain what Archie may do. They\nneed consistent consumption, composition, evidence, and audit without erasing\ntheir different domain meanings.\n\n## Ownership\n\n`internal/policy` is an explicitly approved shared application contract. It is\nnot infrastructure and it is not a generic domain that owns every rule.\n\nThe shared policy system owns:\n\n- policy identity, version, scope, and applicability;\n- typed evaluation invocation;\n- deterministic composition and precedence;\n- common evaluation states such as satisfied, violated, indeterminate, and not\n applicable;\n- reasons and evidence;\n- evaluation audit records;\n- registration, discovery, and lifecycle.\n\nEach consuming domain owns:\n\n- its policy vocabulary and typed inputs;\n- its concrete policy definitions;\n- its evaluators;\n- the meaning and consequence of an evaluation.\n\nAccess therefore owns principals, resources, actions, and authorization\nconsequences. Task lifecycle owns retry eligibility and exhaustion. Task\nexecution owns gate requirements. Workspace mutation owns protected-path\neffects. Tool execution owns tool and command constraints.\n\nThese policies use consistent evaluation mechanics without pretending their\ndecisions are semantically interchangeable.\n\n## Infrastructure\n\nInfrastructure MAY load, persist, distribute, and audit external policy\nrepresentations. It MUST NOT define what Archie allows or assign the meaning of\na domain policy result.\n\nThe exact Go API, composition operators, precedence rules, and representation\nformat require a focused policy design pass.\n"
"body": "# Policy System\n\n**Status:** Approved foundation; exact API is deferred \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nRetry limits, authorisation, gates, commands, protected paths, tool\navailability, and similar rules define or constrain what Archie may do. They\nneed consistent consumption, composition, evidence, and audit without erasing\ntheir different domain meanings.\n\n## Ownership\n\n`internal/policy` is an explicitly approved shared application contract. It is\nnot infrastructure and it is not a generic domain that owns every rule.\n\nThe shared policy system owns:\n\n- policy identity, version, scope, and applicability;\n- typed evaluation invocation;\n- deterministic composition and precedence;\n- common evaluation states such as satisfied, violated, indeterminate, and not\n applicable;\n- reasons and evidence;\n- evaluation audit records;\n- registration, discovery, and lifecycle.\n\nEach consuming domain owns:\n\n- its policy vocabulary and typed inputs;\n- its concrete policy definitions;\n- its evaluators;\n- the meaning and consequence of an evaluation.\n\nAccess therefore owns principals, resources, actions, and authorisation\nconsequences. Task lifecycle owns retry eligibility and exhaustion. Task\nexecution owns gate requirements. Workspace mutation owns protected-path\neffects. Tool execution owns tool and command constraints.\n\nThese policies use consistent evaluation mechanics without pretending their\ndecisions are semantically interchangeable.\n\n## Infrastructure\n\nInfrastructure MAY load, persist, distribute, and audit external policy\nrepresentations. It MUST NOT define what Archie allows or assign the meaning of\na domain policy result.\n\nThe exact Go API, composition operators, precedence rules, and representation\nformat require a focused policy design pass.\n"
},
{
"url": "/dev/architecture/safe-change-and-recovery/",
"title": "Safe Change and Recovery",
"section": "Architecture",
"body": "# Safe Change and Recovery\n\n**Status:** Requirements approved; mechanics are under design. Database-backed settings are implemented through the control plane (2026-09): see the degrade/recovery section below, which records a gap rather than a solution. The full runtime-supervision protocol (bounded observation, versioned audit trail) remains under design.\n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is built and improved by agents as well as humans. The architecture MUST\nmake a change easy to locate, understand, test, audit, extend, and reverse\nwithout requiring its author to understand unrelated parts of the application.\n\nSeparation of concerns is therefore an operational safety boundary, not only a\ncode-organisation preference.\n\n## Required outcomes\n\n- An agent can improve a focused feature without receiving authority over\n unrelated domains.\n- Every event, function, action, setting, and policy has an identifiable owner\n and provenance.\n- Source and runtime changes pass deterministic checks outside the actor making\n the change.\n- A rejected or unhealthy candidate cannot replace the last known working\n version.\n- Invalid user configuration does not terminate an otherwise healthy\n application.\n- Configuration and service failures are observable, attributed, and eligible\n for bounded remediation or rollback.\n- The application continues serving unaffected capabilities when one\n capability is misconfigured or unhealthy.\n- Recovery failure is reported and contained rather than hidden in an\n unbounded retry loop.\n\n## Source changes\n\nAgent-authored source changes occur through the task-execution boundary in an\nisolated workspace. The agent does not directly mutate the running\ninstallation.\n\nPromotion is controlled by deterministic repository-owned policy, including\ntests, generated-reference drift checks, protected paths, change scope, and\nother required gates. The actor proposing a change cannot waive these checks.\n\nRepository and domain separation SHOULD allow a task to load and modify only\nthe governing requirements and code for its declared scope.\n\n## Runtime changes\n\nConfiguration and other runtime changes are proposed as candidates rather than\nmutating the active state in place.\n\nThe affected domain owns:\n\n- the command describing the semantic change;\n- validation of its typed settings;\n- health signals that demonstrate correct operation;\n- domain-specific remediation and rollback consequences.\n\nShared policy supplies consistent evaluation, evidence, and audit mechanics.\nIdentity supplies actor attribution. Infrastructure supplies external\nconfiguration storage, service control, and other operational adapters.\n\n## Runtime change protocol\n\nLast-known-good preservation and candidate promotion are the universal runtime\nchange protocol.\n\n1. An identity proposes an immutable candidate version.\n2. Infrastructure parses it without changing active state.\n3. Each affected domain validates its typed settings.\n4. Shared policy evaluates cross-cutting constraints.\n5. Each affected capability prepares the candidate without destroying its\n active instance.\n6. Capability-specific health checks prove the candidate works.\n7. Runtime supervision atomically promotes the candidate.\n8. A bounded observation period watches for delayed failure.\n9. Failure restores the last-known-good version and records the reason,\n evidence, actor, and involved versions.\n10. Repeated remediation failure stops retrying, isolates the capability, and\n reports the fault.\n\nThe affected domain owns the semantic change command, typed validation, health\nsignals, and remediation consequences. Shared runtime supervision owns the\npromotion transaction. Infrastructure performs storage and service-control\noperations.\n\nThe protocol's exact Go contracts, storage model, atomicity boundary, and\nobservation rules require a focused runtime-supervision design pass.\n\n## Failure isolation\n\nInvalid input MUST leave the active valid configuration unchanged and produce a\ndiagnostic record.\n\nA capability that cannot start or reload SHOULD fail independently where its\nabsence does not violate a declared application invariant. Unaffected\ncapabilities continue operating.\n\nRemediation MUST be bounded, observable, and policy-driven. Recovery MUST NOT\nsilently oscillate between versions or retry forever.\n\n## Database settings: degrade paths and recovery (2026-09)\n\nThe control plane owns runtime-tunable settings and stores them in `archie.db`.\nThis replaced a dashboard overlay store that degraded to file config on any\nfailure and had three documented ways back. The replacement has none, and the\nposture is the opposite: **the daemon fails closed.**\n\n### Degrade paths\n\n| Failure | Boot behaviour | Where the operator sees it |\n| --- | --- | --- |\n| State Store uLine truncated
"body": "# Safe Change and Recovery\n\n**Status:** Requirements approved; mechanics are under design. Database-backed settings are implemented through the control plane (2026-09): see the degrade/recovery section below, which records a gap rather than a solution. The full runtime-supervision protocol (bounded observation, versioned audit trail) remains under design.\n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is built and improved by agents as well as humans. The architecture MUST\nmake a change easy to locate, understand, test, audit, extend, and reverse\nwithout requiring its author to understand unrelated parts of the application.\n\nSeparation of concerns is therefore an operational safety boundary, not only a\ncode-organisation preference.\n\n## Required outcomes\n\n- An agent can improve a focused feature without receiving authority over\n unrelated domains.\n- Every event, function, action, setting, and policy has an identifiable owner\n and provenance.\n- Source and runtime changes pass deterministic checks outside the actor making\n the change.\n- A rejected or unhealthy candidate cannot replace the last known working\n version.\n- Invalid user configuration does not terminate an otherwise healthy\n application.\n- Configuration and service failures are observable, attributed, and eligible\n for bounded remediation or rollback.\n- The application continues serving unaffected capabilities when one\n capability is misconfigured or unhealthy.\n- Recovery failure is reported and contained rather than hidden in an\n unbounded retry loop.\n\n## Source changes\n\nAgent-authored source changes occur through the task-execution boundary in an\nisolated workspace. The agent does not directly mutate the running\ninstallation.\n\nPromotion is controlled by deterministic repository-owned policy, including\ntests, generated-reference drift checks, protected paths, change scope, and\nother required gates. The actor proposing a change cannot waive these checks.\n\nRepository and domain separation SHOULD allow a task to load and modify only\nthe governing requirements and code for its declared scope.\n\n## Runtime changes\n\nConfiguration and other runtime changes are proposed as candidates rather than\nmutating the active state in place.\n\nThe affected domain owns:\n\n- the command describing the semantic change;\n- validation of its typed settings;\n- health signals that demonstrate correct operation;\n- domain-specific remediation and rollback consequences.\n\nShared policy supplies consistent evaluation, evidence, and audit mechanics.\nIdentity supplies actor attribution. Infrastructure supplies external\nconfiguration storage, service control, and other operational adapters.\n\n## Runtime change protocol\n\nLast-known-good preservation and candidate promotion are the universal runtime\nchange protocol.\n\n1. An identity proposes an immutable candidate version.\n2. Infrastructure parses it without changing active state.\n3. Each affected domain validates its typed settings.\n4. Shared policy evaluates cross-cutting constraints.\n5. Each affected capability prepares the candidate without destroying its\n active instance.\n6. Capability-specific health checks prove the candidate works.\n7. Runtime supervision atomically promotes the candidate.\n8. A bounded observation period watches for delayed failure.\n9. Failure restores the last-known-good version and records the reason,\n evidence, actor, and involved versions.\n10. Repeated remediation failure stops retrying, isolates the capability, and\n reports the fault.\n\nThe affected domain owns the semantic change command, typed validation, health\nsignals, and remediation consequences. Shared runtime supervision owns the\npromotion transaction. Infrastructure performs storage and service-control\noperations.\n\nThe protocol's exact Go contracts, storage model, atomicity boundary, and\nobservation rules require a focused runtime-supervision design pass.\n\n## Failure isolation\n\nInvalid input MUST leave the active valid configuration unchanged and produce a\ndiagnostic record.\n\nA capability that cannot start or reload SHOULD fail independently where its\nabsence does not violate a declared application invariant. Unaffected\ncapabilities continue operating.\n\nRemediation MUST be bounded, observable, and policy-driven. Recovery MUST NOT\nsilently oscillate between versions or retry forever.\n\n## Database settings: degrade paths and recovery (2026-09)\n\nThe control plane owns runtime-tunable settings and stores them in the State\nStore's PostgreSQL database.\nThis replaced a dashboard overlay store that degraded to file config on any\nfailure and had three documented ways back. The replacement has none, and the\nposture is the opposite: **the daemon fails closed.**\n\n### Degrade paths\n\n| Failure Line truncated
},
{
"url": "/dev/development/",
"title": "Development guides",
"section": "Development",
"body": "# Development guides\n\nChecklists for changing Archie, one page per area. Each names every place a\nchange must reach, so a feature that works in one layer does not silently stop\nat the next. A change that spans areas starts on the page for the area it\nbegins in, which points to the others. The pages point at the documents that\nown the design (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than\nrestating them.\n\n| Area | Covers |\n| ---------------------------------------------- | -------------------------------------------------------------------------------- |\n| [Frontend UI](/dev/development/frontend-ui/) | Anything under `ui/`, and the dashboard's API routes |\n| [Agent](/dev/development/agent/) | The agent container, its image, profiles, tools and workspace |\n| [Workflows](/dev/development/workflows/) | Workflow definitions and step types |\n| [Daemon](/dev/development/daemon/) | Task statuses, fields and the brief; sources, event types, mappings and bindings |\n| [State Store](/dev/development/state-store/) | Stored fields, tables, RPCs and errors |\n| [Control plane and settings](/dev/development/control-plane/) | Settings in `config.toml` or the dashboard |\n| [Processes and wiring](/dev/development/wiring/) | Where code goes, processes, plugin engines, channels, NATS subjects |\n| [Merging work](/dev/development/merging-work/) | Merging a lane or a branch |\n\n## Every change\n\n- Write the failing test first for anything with logic, branching or a\n contract, and check it fails on an assertion, not a compile error.\n- Test through the path production uses. A test that sets a value directly on\n the consumer proves nothing about the layers that normally deliver it.\n- Run `task check` and let its exit status decide the commit:\n `task check \u0026\u0026 git commit ...`. `task test` passes `-short`, which skips the\n process and Postgres tests, so run `go test -count=1 ./cmd/... ./internal/...`\n too when a change crosses a process or the database.\n- Regenerate, never hand-edit, generated output: `task proto:generate`,\n `go -C tools tool sqlc generate -f $PWD/internal/infrastructure/postgres/sqlc.yaml`,\n `task ui`, `task docs:artifact`. `task proto:check` compares against the git\n index, so stage regenerated contracts before running it.\n- Stage by path, or read `git status` before `git add -A`. Tests that start\n embedded NATS or write logs must use `t.TempDir()`; anything they leave in the\n tree gets committed. `task check` also adds linter-tool lines to `go.sum`\n (bead 1e37); restore `go.sum` before committing unless you changed a\n dependency.\n- A change to `docs/prds/`, `docs/architecture/` **or `docs/development/`**\n carries the regenerated `docs/data/generated/dev-docs.json`: run\n `task docs:artifact` (not `task docs:check`, which checks contracts only).\n PRD edits also follow `docs/prds/RULES.md` and pass `task docs:prds`.\n"
},
{
"url": "/dev/development/agent/",
"title": "Agent",
"section": "Development",
"body": "# Agent\n\nAuthority: `docs/architecture/agent-system.md` (execution boundary, the model\nnever runs git) and the Deployment Model section of `CLAUDE.md`.\n\nThe daemon prepares a workspace, starts one container per task from a profile's\nimage, and hands the whole task to `archie-agent` over NATS in one\n`taskrun.Request`. The agent reaches the State Store, forge and worktree push\nonly through the daemon's RPC servers, using task-scoped credentials.\n\n## Giving the agent something new\n\n- **Data about the task** goes in `taskrun.Request` or the task brief\n (`container.TaskPayload`), never in an environment variable. Add a test that\n the request carries it (`TestRunViaAgentSendsMCPServers` is the pattern).\n- **A credential** is scoped to the task and revoked when it ends, like the\n State Store grant and the worktree publication grant. The daemon's own\n administrative token never enters a container.\n- **A tool** reaches the agent through the central registry, MCP, a repository\n script or a skill plugin. A profile's `tools` list filters those; ai-sdk\n agentloop's built-in file tools are outside it. A tool that must stay inside\n the workspace uses the agent loop's confinement, not its own path handling.\n\n## Changing the agent image or a profile image\n\n1. The agent image is `Dockerfile`; example profile images live in\n `examples/profiles/`, each with a build-only service in\n `docker-compose.yml` (`profiles: [\"build\"]`, so `up -d` never starts it).\n2. Anything the agent runs must be in the image. The container gets no\n package manager at run time beyond what the image ships.\n3. A locally built image needs `containers.pull_policy = \"missing\"`;\n `\"always\"` tries to pull it and fails.\n4. Profiles are configured under `[containers.profiles.\u003cname\u003e]` and resolved\n by the daemon before the container starts (`pinTaskProfile`). An unknown\n profile parks the task; it never falls back to the default image.\n\n## Changing how a task runs\n\n- Workspace preparation happens in the daemon (`prepareWorkspace`) before the\n container starts, because the container binds the directory. Clones need the\n daemon's forge credential; the agent never clones.\n- A task with no repository gets `worktree.Manager.ScratchDir`, which is\n removed when the task ends.\n- The agent runs as root in the container. Anything it writes into the\n bind-mounted workspace is handed back to the daemon's UID\n (`restoreWorktreeOwnership`); a new write path must stay inside that\n workspace.\n- NATS rules are in `CLAUDE.md`: task responses use `msg.Respond`, a responder\n is flushed after it registers, and `ARCHIE_TASKS` is a work queue.\n"
},
{
"url": "/dev/development/control-plane/",
"title": "Control plane and settings",
"section": "Development",
"body": "# Control plane and settings\n\nAuthority: `docs/architecture/configuration.md`. The wiring matrix, the\ndecoded-but-unwired ledger and the three shapes an unwired field takes are in\n`.agents/skills/archie-config-and-flags`.\n\nA field that parses is not a field that works. Before adding one, name the code\nthat reads it and the path the value takes to get there.\n\n## Decide what kind of setting it is\n\n- **Bootstrap-only** (read once at process start: `database_url`, `state_dir`,\n `work_dir`). It stays in the file, is checked by `validateBootstrap` in\n `internal/infrastructure/configuration/validate.go`, and the runtime overlay\n refuses changes to it.\n- **Database-owned** (repository policies, scheduling, tools, plugins,\n channels, containers). The file only seeds it. Once the State Store holds the\n control-plane resource, the stored document is layered over the file\n (`controlplane.Client.RuntimeConfig`) and the file key stops mattering. It is\n checked by `validateDatabaseOwned` and by the resource's validator.\n- **Worker-carried.** A value the agent container needs travels in\n `config.TaskConfig` (`Config.ForTask`) or on `taskrun.Request`. Never pass it\n as an environment variable the daemon did not already define, and never carry\n a secret this way.\n\n## Adding a database-owned field\n\n1. Add it to the struct the resource's `Document` names in\n `internal/app/controlplane/operational_settings.go`. The resource's JSON\n schema and the dashboard's Advanced settings editor are generated from that\n type, so no UI work is needed for the editor itself.\n2. Stored documents use Go field names as keys (`Image`, `MaxConcurrency`).\n Give the field no `json` tag unless its neighbours have one.\n3. A map or a nested struct needs its layering checked. `json.Unmarshal`\n merges into an existing map, so a stored map would add to the file's rather\n than replace it. A field the stored document omits keeps the file's value\n (a document stored before the field existed). Add a case to\n `internal/app/controlplane/runtime_config_test.go` for both.\n4. Validate it in one function both sides call, and add a case to\n `TestResourceValidatorsRejectWhatEffectiveValidationRejects` in\n `validators_agree_test.go`, so the file and the resource cannot disagree.\n5. Decide whether it reloads: it does only if every consumer re-reads it from\n `config.Holder`. The allowlist is `internal/app/archied/reload.go`; anything\n not on it requires a restart.\n6. If the settings page shows it as a plain field, add it to\n `internal/webui/config_schema.go` and the view in `api_config.go`.\n7. A generic catalog resource (`replace` command, not domain-managed, no\n query service) is watched **once per archie-ui process** by `webui.RunLive`,\n then published to every browser through `/api/stream`. Do not add an\n EventSource per resource to a settings store or a gRPC Watch per HTTP client.\n The control-plane server polls `Resource` every 250ms per upstream Watch;\n verify watch count is independent of client count and that late clients get\n the hub's current value (`internal/webui/live_hub_test.go`, real server over\n bufconn). Reopens resume after the last delivered version and charge failed\n attempts; accepting a gRPC stream does not establish its health.\n\n## Every new field\n\n- Test through the layering: build the effective config the way boot does,\n not by setting the field on the consumer.\n- Add a commented example to `config.example.toml`. Touch `deployments/*.toml`\n only when a profile there needs a value different from the default.\n- Update the wiring matrix in `.agents/skills/archie-config-and-flags`.\n- Secrets are `SecretRef`s resolved through the secret registry. Never inspect\n a resolved value, even in a test.\n- Reject a configuration that sets a field with no consumer rather than\n accepting and ignoring it (per-identity `forge.intake` is the precedent).\n"
},
{
"url": "/dev/development/daemon/",
"title": "Daemon",
"section": "Development",
"body": "# Daemon\n\nThe daemon claims and runs tasks, and turns captured events into tasks through\nbindings. This page covers both.\n\n## Task lifecycle\n\nAuthority: `docs/architecture/agent-system.md`. The status vocabulary lives in\n`internal/taskstate`, which imports no internal package.\n\n### Adding a status\n\n1. Add the constant to `internal/taskstate/taskstate.go` and place it in\n `Terminal`, `Actions` and `Statuses`. Its value is stored, so renaming it\n later is a migration.\n2. Alias it in `internal/domain/workflow/task/task.go` and\n `internal/domain/workflow/task_aliases.go`.\n3. Add it to the default catalogue in `ui/src/lib/task-meta.ts`. The server\n catalogue replaces the defaults when it loads, but the defaults render first.\n4. Find every hand-written status list in SQL:\n `grep -rn \"'merged'\" internal/infrastructure/postgres/queries`.\n `ClearTerminalTasks` must match `taskstate.Terminal`, which\n `TestClearTerminalTasksMatchesTaskstate` enforces. The stats queries count\n outcomes by name; decide whether the new status counts.\n5. Extend the table in `taskstate_test.go`.\n\n### Adding a task field\n\nFollow [State Store](/dev/development/state-store/) for the\ncolumn and the wire. Then decide who writes it: `UpdateTask` writes a fixed\ncolumn set, so a field set at enqueue needs its own statement (as\n`StampTaskBinding` does for binding provenance and inputs).\n\n### Changing what the agent receives\n\n- The task brief is `container.TaskPayload`, written to\n `\u003cworkspace\u003e/.git/task.json` by `WriteTaskJSON`. Never write it to the\n workspace root: the commit stage stages everything there.\n- The run request is `taskrun.Request`. `Validate` rejects a request that\n cannot run; a new requirement goes there.\n- Parking always carries a class (`taskstate.ParkTransient`,\n `ParkNeedsHuman`, `ParkTerminal`) chosen by the code that parks. Pick the one\n that says what an operator must do.\n- A task with no repository (`Task.HasRepository`) runs in a scratch workspace\n with no worktree grant. Code that assumes an owner and repo must check first.\n\n## Event automation\n\nAuthority: `docs/prds/event-automation.md` (the model: source, event type,\nmapping, binding, workflow, profile) and `docs/architecture/bindings.md`\n(threat model).\n\n### Where each check lives\n\nA binding is checked twice, and a new rule usually belongs in both places:\n\n- **On save**, in `checkedBinding` (`internal/webui/api_binding.go`), so the\n operator sees the problem while editing. It calls the domain checks\n `binding.Validate`, `binding.CompileFilter` and `Binding.CheckWorkflow`.\n- **At dispatch**, in `dispatchOneBinding` and `resolveBindingTarget`\n (`internal/daemon`), because the workflow or mapping may have changed since\n the save. A refusal is recorded with `recordDispatchFailure` and starts no\n task.\n\nPut the rule itself in `internal/domain/binding` or\n`internal/domain/workflow/task` and call it from both, rather than writing it\ntwice.\n\n### Adding a binding field\n\n1. Domain type and `Validate` in `internal/domain/binding`.\n2. Column, queries, store mapping, wire field, `newColumns`\n ([State Store](/dev/development/state-store/)).\n3. The request type and `checkedBinding` in `api_binding.go`.\n4. The draft, payload and editor in `ui/src/bindings/`\n ([Frontend UI](/dev/development/frontend-ui/)).\n5. Its effect at dispatch, with a case in\n `internal/daemon/dispatch_inputs_test.go` or `dispatch_bindings_test.go`.\n\n### Rules that must hold\n\n- Signing belongs to the source. Intake verifies the HMAC against the source's\n secret before the payload is parsed.\n- An event must be identified as an event type before anything dispatches it,\n and a binding applies only to its mapping's event type. Dispatch test\n fixtures therefore create an event type before inserting captures.\n- The dispatch ledger is claimed before the task is enqueued (at most once).\n- Anything an event supplies that selects what the agent acts on, such as a\n repository, must be checked against configuration. An event never widens\n what an agent can reach.\n"
},
{
"url": "/dev/development/frontend-ui/",
"title": "Frontend UI",
"section": "Development",
"body": "# Frontend UI\n\nAuthority: `.agents/skills/archie-web-ui` (stack facts, design-system rules,\ntone and accessibility). This page covers what a change must reach, not how it\nshould look.\n\n## Adding or changing a feature\n\n1. The feature lives in `ui/src/\u003cfeature\u003e/`. Move a helper to `ui/src/base/`\n only when a second feature needs it.\n2. Keep wire shapes, draft state and payload building in a plain `.ts` module\n beside the components (`ui/src/bindings/binding-draft.ts` is the pattern),\n and test it in `ui/test/*.test.ts`. Components stay thin.\n3. Every mutation goes through `api.*` in `ui/src/lib/api`, which sends the\n CSRF and Content-Type headers the server's mutation guard requires. A bare\n `fetch` is refused.\n4. A value the server also describes (task statuses, actions, workflow inputs)\n comes from the server. Keep a local default only so the first render works,\n and keep it in step (`ui/src/lib/task-meta.ts`).\n5. Run `task ui`, `task test:ui` and `cd ui \u0026\u0026 npm run typecheck`. Commit the\n regenerated `ui/dist/`; the Go binaries embed it. A fresh git worktree has\n no ignored `ui/node_modules`: run `cd ui \u0026\u0026 npm ci` before these commands.\n6. **One long-lived browser connection:** `ui/src/lib/api.ts` has the only\n `new EventSource`, owned by `stores/live-updates.ts`. Feature stores consume\n topics with `live.subscribe(topic, callback)`; do not open a page-owned SSE\n stream. Logs alone opt in while mounted, replacing that same EventSource\n with `?topics=logs\u0026since=\u003clast cursor\u003e`; a browser's `Last-Event-ID` only\n survives its own automatic reconnect, not a newly constructed EventSource.\n Task and log topics resume by cursor; control-plane, identity and apply-status\n topics replay the latest snapshot. Test a fetch and same-origin navigation\n after visiting Settings and Logs: the UI process serves HTTP/1.1 and six\n persistent streams can starve every later browser request.\n\n## Adding an API route\n\n1. The handler goes in the `internal/webui/api_\u003cconcern\u003e.go` file for its\n concern. Check the request fully on the server; the UI's checks are only a\n convenience.\n2. A mutation calls `authorizeTaskMutation` first.\n3. A route whose store is not configured answers 503, and\n `internal/app/archieui/degraded_routes_test.go` pins what each route\n returns without its contract. Add the route there.\n4. The dashboard runs in its own process (`archie-ui`) and must not link the\n daemon or the workflow engine (`cmd/archie-ui/architecture_test.go`). Reach\n stored data through `storecontract` interfaces wired in\n `internal/app/archieui/compose.go`.\n5. Settings that live in a control-plane resource need no new route: the\n Advanced settings page edits every resource from its generated schema.\n6. For a new live topic, add one process-wide producer to `internal/webui`'s\n `RunLive` and fan it through the `/api/stream` hub; `internal/app/archieui/run.go`\n starts the producers with the process context. Never create an upstream\n watch or poller in an HTTP handler. A slow client must reconnect for cursor\n and snapshot repair rather than silently lose an update. Prove the producer\n with several browser clients against the real peer, not just a scripted\n stream; `live_hub_test.go` is the example.\n"
},
{
"url": "/dev/development/merging-work/",
"title": "Merging work",
"section": "Development",
"body": "# Merging work\n\nParallel lanes (see `.agents/skills/archie-agent-fleet`) merge into an\nintegration branch before `main`. Each merge is a change in its own right and\npasses the same gate.\n\n## Resolving conflicts\n\n- **Generated files** (`*.pb.go`, `postgresdb/*.go`, `ui/dist/`,\n `docs/data/generated/*.json`): take either side, then regenerate. Never merge\n them by hand.\n- **One side deletes a file, the other edits it**: the deletion wins when the\n deleting lane replaced the thing the file served. Move the other side's\n change onto its replacement.\n- **One side changes how code is built (a new store, renamed packages), the\n other what it does**: take the behaviour side's version and reapply the\n mechanical change to it. That is usually cleaner than merging line by line.\n- **Error sentinels** are rows in `wireErrors`, not switch cases.\n\n## After resolving\n\n1. Search for leftovers of anything the other side removed: the old package\n path, the old type, and comments describing the old behaviour.\n2. Tests written against one side's semantics may pass there and fail after\n the merge. A test that used to pass on the old store may be asserting a rule\n the other side deliberately changed. Fix the test's setup to the merged\n rule; do not loosen the rule to the test.\n3. Run the full suite without `-short`, then `task check`, then commit. Check\n `git status` for files a test wrote into the tree before staging.\n"
},
{
"url": "/dev/development/state-store/",
"title": "State Store",
"section": "Development",
"body": "# State Store\n\nAuthority: `docs/prds/state-store-contract.md` and the State Store section of\n`CLAUDE.md`. All persistence is PostgreSQL behind the standalone State Store\nprocess; nothing else opens the database.\n\n## Adding a column\n\n1. Write the next migration in `internal/infrastructure/postgres/migrations/`\n (`00NN_name.sql`, goose Up and Down). Give the column a `NOT NULL DEFAULT`\n that is correct for existing rows.\n2. Update the queries in `internal/infrastructure/postgres/queries/` and\n regenerate with sqlc. A query that lists columns (`ListTaskSummaries`, the\n binding selects) does not pick the new one up; `SELECT *` queries do.\n3. Map it in the store (`taskFromRow`, `bindingValue` and friends). If the\n column holds encoded data, the package that owns the type owns the encoding\n (`task.EncodeInputs`), and the store and the wire both use it.\n4. Carry it over the wire (next section) if any process other than the State\n Store reads it.\n\n## Adding a field to a wire message\n\n1. Add it to `proto/state/v1/state.proto` with a new field number. Never reuse\n a number; retire one with `deprecated = true`.\n2. `task proto:generate`, then map it both ways in\n `internal/infrastructure/staterpc/values.go`.\n3. `TestTaskProtoCarriesEveryDomainField` fills every `task.Task` field and\n fails on one the mapping forgets. If it cannot fill the field's kind, extend\n it. Other messages have no such test, so add a round trip to\n `conformance_test.go`.\n\n## Adding an RPC or a store method\n\n1. Put the Go method on the narrow consumer interface in\n `internal/domain/storecontract` (keep each at eight methods or fewer) and add\n the matching RPC. A Go method without an RPC does not cross the process.\n2. Implement it in the Postgres store, in `staterpc.Client` (with its `var _`\n assertion) and in `staterpc.server`. A missing dependency answers\n `codes.Unavailable`, never a fabricated default.\n3. Wire the dependency in every composition that serves or consumes it:\n `stateStoreDeps` in `internal/app/archied/state_store.go`, the daemon's\n assertions in `bootstrap.go`, and `internal/app/archieui/compose.go` for the\n dashboard process.\n4. Task-scoped tokens may call only `Update`, `Transition` and `InsertEvent` on\n their own task (`staterpc.TaskGrants`). A new RPC is admin-only unless it is\n added there deliberately.\n5. Add it to `conformance_test.go`, which runs every surface over a real gRPC\n connection.\n\n## Adding an error sentinel\n\nAdd the sentinel to `storecontract`, a row to `wireErrors` in `values.go`, and\na case to `error_test.go`. The canonical message is part of the wire contract:\nchanging it breaks `errors.Is` on the client silently.\n"
},
{
"url": "/dev/development/wiring/",
"title": "Processes and wiring",
"section": "Development",
"body": "# Processes and wiring\n\nAuthority: `docs/architecture/organisation.md` (layers, process boundaries),\n`docs/architecture/dependencies-and-contracts.md` (dependency direction, wire\ncontracts) and `docs/architecture/plugins-and-extensions.md` (the plugin engine\nrule).\n\n## Placing new code\n\n- Domain logic, entities and the interfaces it needs go in\n `internal/domain/\u003carea\u003e/`, which imports no infrastructure or app package.\n- Implementations of those interfaces go in `internal/infrastructure/\u003cservice\u003e/`.\n- Construction and wiring go in `internal/app/\u003capplication\u003e/`; `cmd/` only\n parses flags and calls it.\n- `logging`, `events`, `eventbus`, `policy` and `taskstate` import no internal\n package. There is no `shared/`, `utils/` or `common/` package.\n- A behaviour has one authoritative path. Before adding a second way to do\n something, remove or redirect the first.\n\n## Adding a capability to a process\n\n1. Decide which process owns it. A new binary is justified only when the\n surface must fail, scale or run somewhere independently.\n2. Wire it at that process's composition root. An optional capability\n degrades: a missing provider logs a warning and marks health degraded\n rather than stopping the process (MCP providers are the model).\n3. Every process that reaches the capability through the State Store gets it\n through a `storecontract` interface asserted on the client\n ([State Store](/dev/development/state-store/)).\n4. The architecture tests (`cmd/archie-ui/architecture_test.go`,\n `cmd/archie-messaging/architecture_test.go`, `TestOpenStoresNeverOwnsTaskDB`)\n pin what each binary may link. A failure there means the placement is wrong,\n not the test.\n\n## Adding a plugin engine\n\nSatisfy every invariant in \"Plugin engine rule (strict)\" in\n`plugins-and-extensions.md`: typed domain contract, an owning manager,\nlifecycle and health, narrow host access, and an explicit trust boundary.\n`internal/plugin/architecture_test.go` checks the parts that can be checked.\n\n## Adding a channel or a NATS subject\n\n- Channel rules (Telegram's pending-update drop, command scopes) are in\n `CLAUDE.md` under Per-Package Invariants.\n- A subject is part of the wire contract. Its payload type belongs to the\n domain that defines its meaning, and the transport code lives in\n infrastructure.\n"
},
{
"url": "/dev/development/workflows/",
"title": "Workflows",
"section": "Development",
"body": "# Workflows\n\nAuthority: `docs/architecture/agent-system.md` for the lifecycle,\n`docs/prds/event-automation.md` for inputs, repository modes and profiles.\n\nWorkflow definitions are YAML stored as a control-plane resource. The State\nStore validates them and the agent compiles them, each against the step\nvocabulary it registers, so both must see the same step types.\n\n## Adding a step type\n\n1. Write the factory in `internal/domain/workflow` as a `StepType`. It decodes\n and validates its settings and returns an error for anything it cannot\n honour. The factory runs when a definition is saved and again when it is\n compiled, so a bad definition is refused on save.\n2. Register it through a provider in\n `internal/infrastructure/workflowsteps/workflowsteps.go`. That one list is\n what every process registers, which is how the validating and executing\n sides agree.\n3. An agent-driven step builds on `AgentStage`; do not start a second path to\n the agent runner.\n4. A step that needs no repository goes in `repoFreeStepTypes` in\n `definition.go`, or workflows declaring `repository: none` or `optional`\n cannot use it. A step that needs one may assume `tc.Dir` holds a worktree\n only when the workflow's repository is `required`.\n5. A step that ends the workflow sets `tc.Outcome`. A workflow that runs out of\n steps without an outcome is parked as a definition bug.\n6. Add a parse test (settings accepted and refused) and a run test with fake\n `Trees` and agent runner.\n\n## Changing the definition format\n\n- The fields a caller needs without the engine (inputs, repository, profile)\n live in `task.WorkflowInterface`, because the dashboard process must not\n import the workflow engine (`cmd/archie-ui/architecture_test.go`). Anything a\n binding or the dashboard checks goes there.\n- The YAML decoder rejects unknown keys. Existing stored definitions must keep\n parsing, so a new key is optional with a default that preserves today's\n behaviour.\n- Examples in `examples/workflows/` are parsed against the registered\n vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.\n"
},
{
"url": "/dev/prds/01-project-management/",
"title": "Architecture Decision Index",
"section": "PRDs",
"body": "# Architecture Decision Index\n\n**Status:** Approved \n**Date:** 2026-07-28 \n**Beads issue:** `archie-core-5d7`\n\n## Purpose\n\nThis file is the navigation point for Archie's target architecture. It is\ndeliberately short. Architectural decisions are separated by domain or\nrequirement so an implementation task can load only the rules governing its\nscope.\n\nImplementers MUST read the decision document for the domain or requirement they\nare changing. They MUST NOT infer permission to change neighbouring domains from\na broader restructuring objective.\n\n## Global invariants\n\n- Organise code around cohesive application responsibilities, not generic\n technical mechanisms.\n- Domains own their behaviour, vocabulary, state, commands, events, policy\n implementations, runtime settings, and required service contracts.\n- Domains do not depend on infrastructure or manipulate another domain.\n- `internal/app` owns composition; `cmd/*` remains thin.\n- Cross-domain work uses an explicitly owned command, event, or approved shared\n contract.\n- Process boundaries are deployment choices and do not determine source-code\n ownership.\n- Existing package names and boundaries have no presumption of survival.\n\nThe words **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are normative.\n\n## Decision documents\n\n| Scope | Authoritative document |\n| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |\n| Repository layout, domains, composition, deployments, and optional material | [architecture/organisation.md](/dev/architecture/organisation/) |\n| Dependency direction, domain contracts, infrastructure, commands, events, and wire contracts | [architecture/dependencies-and-contracts.md](/dev/architecture/dependencies-and-contracts/) |\n| External configuration, runtime settings, and dissolution of `internal/config` | [architecture/configuration.md](/dev/architecture/configuration/) |\n| Persistent actor identity, ownership, lifecycle, and attribution | [architecture/identity.md](/dev/architecture/identity/) |\n| Agent definitions, workflows, workflow executions, tools, and worker boundaries | [architecture/agent-system.md](/dev/architecture/agent-system/) |\n| Personal-assistant interactions, messaging channels, and optional promotion into durable work | [architecture/messaging-and-work-intake.md](/dev/architecture/messaging-and-work-intake/) |\n| Shared policy evaluation and domain-owned policy semantics | [architecture/policy.md](/dev/architecture/policy/) |\n| Safe source/configuration changes, health supervision, and recovery | [architecture/safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/) |\n| Plugin framework, plugin implementations, and extension isolation | [architecture/plugins-and-extensions.md](/dev/architecture/plugins-and-extensions/) |\n| Generated references, deprecations, and changelog generation | [architecture/generated-documentation.md](/dev/architecture/generated-documentation/) |\n| Remaining package destinations, data migrations, runtime cutover, and completion criteria | [architecture/migration-decisions.md](/dev/architecture/migration-decisions/) |\n| Domain/feature research, design interview, and required handoff | [architecture/package-review.md](/dev/architecture/package-review/) |\n\n## Deferred decisions\n\nThe remaining package-placement, data-migration, shared-mechanics, process-\nboundary, and cutover decisions are maintained in\n[architecture/migration-decisions.md](/dev/architecture/migration-decisions/).\n\nEach decision is made in its focused document after code-grounded review.\n"
"body": "# Architecture Decision Index\n\n**Status:** Approved \n**Date:** 2026-07-28 \n**Beads issue:** `archie-core-5d7`\n\n## Purpose\n\nThis file is the navigation point for Archie's target architecture. It is\ndeliberately short. Architectural decisions are separated by domain or\nrequirement so an implementation task can load only the rules governing its\nscope.\n\nImplementers MUST read the decision document for the domain or requirement they\nare changing. They MUST NOT infer permission to change neighbouring domains from\na broader restructuring objective.\n\n## Global invariants\n\n- Organise code around cohesive application responsibilities, not generic\n technical mechanisms.\n- Domains own their behaviour, vocabulary, state, commands, events, policy\n implementations, runtime settings, and required service contracts.\n- Domains do not depend on infrastructure or manipulate another domain.\n- `internal/app` owns composition; `cmd/*` remains thin.\n- Cross-domain work uses an explicitly owned command, event, or approved shared\n contract.\n- Process boundaries are deployment choices and do not determine source-code\n ownership.\n- Existing package names and boundaries have no presumption of survival.\n\nThe words **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are normative.\n\n## Decision documents\n\n| Scope | Authoritative document |\n| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |\n| Repository layout, domains, composition, deployments, and optional material | [architecture/organisation.md](/dev/architecture/organisation/) |\n| Dependency direction, domain contracts, infrastructure, commands, events, and wire contracts | [architecture/dependencies-and-contracts.md](/dev/architecture/dependencies-and-contracts/) |\n| External configuration, runtime settings, and dissolution of `internal/config` | [architecture/configuration.md](/dev/architecture/configuration/) |\n| Persistent actor identity, ownership, lifecycle, and attribution | [architecture/identity.md](/dev/architecture/identity/) |\n| Agent definitions, workflows, workflow executions, tools, and worker boundaries | [architecture/agent-system.md](/dev/architecture/agent-system/) |\n| Personal-assistant interactions, messaging channels, and optional promotion into durable work | [architecture/messaging-and-work-intake.md](/dev/architecture/messaging-and-work-intake/) |\n| Shared policy evaluation and domain-owned policy semantics | [architecture/policy.md](/dev/architecture/policy/) |\n| Safe source/configuration changes, health supervision, and recovery | [architecture/safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/) |\n| Plugin framework, plugin implementations, and extension isolation | [architecture/plugins-and-extensions.md](/dev/architecture/plugins-and-extensions/) |\n| Generated references, deprecations, and changelog generation | [architecture/generated-documentation.md](/dev/architecture/generated-documentation/) |\n| Remaining package destinations, data migrations, runtime cutover, and completion criteria | [architecture/migration-decisions.md](/dev/architecture/migration-decisions/) |\n| Domain/feature research, design interview, and required handoff | [architecture/package-review.md](/dev/architecture/package-review/) |\n\n## Deferred decisions\n\nThe remaining package-placement, data-migration, shared-mechanics, process-\nboundary, and cutover decisions are maintained in\n[architecture/migration-decisions.md](/dev/architecture/migration-decisions/).\n\nEach decision is made in its focused document after code-grounded review.\n"
},
{
"url": "/dev/prds/RULES/",
"title": "PRD writing rules",
"section": "PRDs",
"body": "# PRD writing rules\n\nThese rules apply to every file in `docs/prds/`.\n\n- Search existing PRDs, issues, architecture records, and code first. Do not ask\n the maintainer to repeat recorded requirements.\n- A newer maintainer decision overrides an older design. Mark the old design as\n superseded instead of preserving or defending it.\n- Write plain English. Use a technical term only when the reader needs that\n exact contract or concept.\n- Use the shortest direct sentence. Write “When upgraded, existing instances\n are migrated to the database,” not a description of an importer seeding\n absent resources.\n- State each fact once. Do not repeat a heading, summarize a list before showing\n it, or restate a decision afterward.\n- Every sentence must add a decision, requirement, constraint, evidence, or\n verification step. Delete narration and explanations of obvious text.\n- Do not turn a requested outcome into extra product features. Keep inferences\n open until the maintainer or repository evidence settles them.\n- Do not create a process for a logical boundary. Add one only when it must\n deploy, scale, start, secure, or fail separately.\n- Describe working behavior, not explanatory UI around missing behavior. State\n what users can do and how success is proved.\n- Before approval, use independent read-only reviewers to check a cross-cutting\n PRD for missing behavior and exaggerated claims. Verify and synthesize their\n findings; do not copy their prose.\n- Before requesting approval, review every sentence for complexity, repetition,\n and unsupported scope.\n- Write nothing whose truth expires. No `file.go:123` citations (cite the file\n and the symbol), no progress reports on the work being designed, no dated\n status claims, and no record of how a finding was produced. A phased plan is\n durable design; which phase is finished is not. Do not refer to what this\n document used to say: the reader cannot see it. A supersede marker is fine\n when it names a file, a section or a symbol they can find. `task docs:prds`\n enforces this.\n- Every PRD carries one of three statuses, and nothing else in that field.\n `Draft` until the maintainer explicitly approves it, `Approved` once they\n have and while the work is being built, `Finalised` when the work is\n complete. A finalised PRD does not change; supersede it with a new one\n instead. A revision number belongs in `**Revision:**`, a pointer to the\n authoritative document in `**Authority:**`, and what a past revision changed\n belongs in git.\n"
"body": "# PRD writing rules\n\nThese rules apply to every file in `docs/prds/`.\n\n- Search existing PRDs, issues, architecture records, and code first. Do not ask\n the maintainer to repeat recorded requirements.\n- A newer maintainer decision overrides an older design. Mark the old design as\n superseded instead of preserving or defending it.\n- Write plain English. Use a technical term only when the reader needs that\n exact contract or concept.\n- Use the shortest direct sentence. Write “When upgraded, existing instances\n are migrated to the database,” not a description of an importer seeding\n absent resources.\n- State each fact once. Do not repeat a heading, summarise a list before showing\n it, or restate a decision afterward.\n- Every sentence must add a decision, requirement, constraint, evidence, or\n verification step. Delete narration and explanations of obvious text.\n- Do not turn a requested outcome into extra product features. Keep inferences\n open until the maintainer or repository evidence settles them.\n- Do not create a process for a logical boundary. Add one only when it must\n deploy, scale, start, secure, or fail separately.\n- Describe working behaviour, not explanatory UI around missing behaviour. State\n what users can do and how success is proved.\n- Before approval, use independent read-only reviewers to check a cross-cutting\n PRD for missing behaviour and exaggerated claims. Verify and synthesise their\n findings; do not copy their prose.\n- Before requesting approval, review every sentence for complexity, repetition,\n and unsupported scope.\n- Write nothing whose truth expires. No `file.go:123` citations (cite the file\n and the symbol), no progress reports on the work being designed, no dated\n status claims, and no record of how a finding was produced. A phased plan is\n durable design; which phase is finished is not. Do not refer to what this\n document used to say: the reader cannot see it. A supersede marker is fine\n when it names a file, a section or a symbol they can find. `task docs:prds`\n enforces this.\n- Every PRD carries one of three statuses, and nothing else in that field.\n `Draft` until the maintainer explicitly approves it, `Approved` once they\n have and while the work is being built, `Finalised` when the work is\n complete. A finalised PRD does not change; supersede it with a new one\n instead. A revision number belongs in `**Revision:**`, a pointer to the\n authoritative document in `**Authority:**`, and what a past revision changed\n belongs in git.\n"
},
{
"url": "/dev/prds/action-playbook-run/",
"title": "Running action playbooks",
"section": "PRDs",
"body": "# Running action playbooks\n\n**Status:** Approved\n**Date:** 2026-09-23\n**Parent:** `docs/prds/multi-action-playbooks.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-t2db.31`\n\n## Why this exists\n\nAn action playbook loads and type-checks but never runs: `Store.Dispatch`\nskips it and the daemon logs a warning at boot (`multi-action-playbooks.md`,\nD1). This document defines when it runs, what each action does, and how the\n`playbook_dispatches` ledger gates it.\n\n## When a playbook runs\n\nThe daemon runs action playbooks at the point it pins a task's workflow\ndefinition (`Daemon.resolveWorkflowID`), using the same `DispatchInput` the\nworkflow playbooks use. The definition is pinned once per task, so the run\nhappens once per task.\n\n- Every action playbook whose trigger matches runs, in load order. A workflow\n playbook stops at the first match because it chooses one workflow; action\n playbooks choose nothing, so no match suppresses another.\n- A run never changes routing. The task is pinned by the workflow playbooks\n and bindings exactly as when no action playbook exists.\n- An action or playbook failure never parks or fails the task. It is logged\n at warning level with the playbook, the action and the task.\n- A task that already names a workflow (the approval requeue) is skipped, as\n it is for workflow playbooks.\n- Actions run synchronously in the pin path, bounded by the daemon's context.\n The only Module kind, `log`, returns immediately. A slow kind must bring its\n own timeout.\n\n## What one action does\n\nActions run in order against one evaluation context whose `actions` map\nstarts empty.\n\n1. Evaluate `when`. False or an evaluation error skips the action (J3). A\n skipped action records nothing and produces no result.\n2. Evaluate every `args` value. An evaluation error stops the playbook.\n3. Call `playbook.InvokeOnce` with the Module invoke as its function. The\n ledger row is written first. A duplicate row skips the invoke.\n4. An invoke error stops the playbook. The row stays, so the action is not\n retried: the ledger promises at most once, not at least once.\n5. On success, `ModuleRegistry.DecodeResult` converts the result, and it is\n stored as `actions.\u003cid\u003e.result` when the action declares an id.\n\nThe event id in the ledger key is `DispatchInput.TaskID`, the issue's\nidempotency key (`owner/repo/number`). An action therefore runs at most once\nper issue for each playbook version. Editing a playbook changes its version\nand lets it run again for issues it already handled.\n\nA skipped duplicate has no result. A later action that reads it sees a\nmissing field: its `when` evaluates false, or its args fail and the playbook\nstops. This only happens when the same issue is pinned twice under one\nplaybook version.\n\n## Wiring\n\n- `storecontract.PlaybookDispatcher` is lifted onto the daemon from the State\n Store client in `internal/app/archied/bootstrap.go`, the same way\n `BindingDispatcher` is.\n- The daemon's `Playbooks` dependency gains the run method. The Module\n registry is passed to the playbook store at load, so the daemon needs no\n new dependency for it.\n- With no `PlaybookDispatcher` wired, action playbooks do not run, and the\n boot warning names each one. They never run without the ledger.\n- The boot warning that action playbooks do not execute is removed when the\n ledger is wired.\n\n## Verification\n\n- A matching two-action `log` playbook runs both actions in order, and the\n second reads the first's result.\n- Pinning the same task twice under one playbook version invokes each action\n once.\n- A `when` that evaluates false skips that action and the run continues.\n- An invoke error stops the playbook. The task is still pinned to the same\n workflow it would get with no action playbook.\n- A non-matching trigger runs nothing.\n- With no ledger wired, nothing runs and the warning names the playbook.\n"
},
{
"url": "/dev/prds/adversarial-self-review/",
"title": "Adversarial self-review stage -- decision",
"section": "PRDs",
"body": "# Adversarial self-review stage -- decision\n\n**Status:** Finalised\n**Authority:** `docs/architecture/adversarial-review.md` describes the stage and is authoritative. This PRD remains the design-decision record.\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-h019.1`, blocks `h019.2/.3/.4/.5`\n\n\u003e **Section 1 is superseded by the decision below.**\n\u003e The original execution mechanism assumed daemon-owned in-process execution\n\u003e and a daemon-side second `Pool.Acquire`; `archie-core-q15y` removed both\n\u003e call sites, leaving one open question: how a fresh reviewer receives an\n\u003e isolated snapshot from inside the task-scoped worker, without a host\n\u003e executor or a nested container lifecycle. Section 1 below now answers it\n\u003e with `agent.Subagent`. Sections 2-5 were never invalidated and still hold;\n\u003e section 3's contract shipped as `archie-core-h019.2`.\n\nAnswers the five questions in `h019.1`'s description against the actual\nimplement workflow, not designed from scratch: the gate pattern, the\ncontainer pool, and the workflow engine's `Outcome` mechanism already answer\nmost of this.\n\n## 1. Where it runs: `agent.Subagent`, inside the task worker\n\nThe implement workflow's stage list\n(`internal/domain/workflow/implement.go`) already has the right slot:\nafter `StageDiffCap()`, before `StageOpenPR()` -- gates\nhave passed, the diff is final, and nothing has told the forge about this\nchange yet.\n\n**The reviewer is an `agent.Subagent` run, not a second container.** ai-sdk\n`v0.1.22` (already the pinned version) added `agent/subagent.go`: a nested,\nsynchronous `core.GenerateText` call in the same process, with its own model,\nsystem prompt, toolset and step budget. That is what makes this feature\nbuildable at all after `q15y` -- the reviewer runs inside the task-scoped\n`archie-agent` worker that is already executing the workflow, so there is no\nhost executor, no second `Pool.Acquire`, and no nested container lifecycle.\n\n**Two isolations are needed, and Subagent only provides one of them.**\n\n*Conversation isolation is structural, and free.* `Subagent.Run`\n(`agent/subagent.go`) calls `GenerateText` with `Prompt` set and\n`Messages` never populated. The implementer's history has no code path into\nthe nested run; only the prompt string crosses, and only text comes back.\nThis is the literal form of \"environmental enforcement over prompt rules\":\nthe reviewer is not told to ignore the implementer's reasoning, because\nnothing hands it any. `h019.3`'s required test asserts this as a construction\nfact.\n\n*Workspace isolation is still ours to build.* A sub-agent shares the parent's\nprocess, working directory and credentials. So the `.git`-free snapshot from\nthe original decision survives unchanged and is load-bearing: export the\nreviewed commit (`git archive \u003ccommit\u003e | tar -x`) into a fresh scratch\ndirectory beside, not inside, the task worktree, and write `diff.patch` (the\ndiff already computed for `StageYaegiGate`'s `Trees.Diff()`) and `issue.md`\n(the originating issue's title and body, nothing else) alongside it. Stripping\n`.git` is what makes commit messages, branch name and reflog -- the actual\nchannel a multi-commit implementer's reasoning leaks through -- structurally\nunreachable rather than merely undisclosed.\n\n`Subagent.Tools` therefore takes a **distinct read-only toolset rooted at the\nsnapshot**. Never the worker's own toolset: it carries the `worktreerpc`\npublication grant, so a reviewer holding it could push the branch it exists to\nblock.\n\n**Call `Run()`, not `Tool()`.** `Tool()` would register delegation as a tool\nthe *implementer's* model may choose to invoke -- self-certification by the\nimplementer, which is the exact failure this feature exists to prevent. The\nstage calls `Run()` unconditionally. That also sidesteps both of `Tool()`'s\ndocumented footguns: the parent's two-step minimum and the recursion risk of\npassing a toolset back to itself.\n\n**Findings return through a closure, not the return value.** `Run` yields only\nfinal text, so section 3's structured contract cannot ride the return. Because\nthe sub-agent is in-process, the capture tool's Go implementation appends\ndirectly to a `[]workflow.ReviewFinding` the stage owns. This preserves the\n\"cannot end its turn without calling a typed tool\" property, and it defeats\n`Subagent`'s documented \"no partial results on failure\" limitation: findings\nalready captured survive an error return, so **the stage reads the captured\nslice even when `Run` returns an error**. A reviewer that logged three defects\nand then hit its step limit still yields those three.\n\n## 2. What it's given, and what it must never be given\n\n**Given:** the clean file-content snapshot (so the reviewer can read whole\nfiles -- follow an import, check interface satisfaction, see a call site --\nnot just diff hunks, which the manual-read checklist in CLAUDE.md rLine truncated
"body": "# Adversarial self-review stage -- decision\n\n**Status:** Finalised\n**Authority:** `docs/architecture/adversarial-review.md` describes the stage and is authoritative. This PRD remains the design-decision record.\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-h019.1`, blocks `h019.2/.3/.4/.5`\n\n\u003e **Section 1 is superseded by the decision below.**\n\u003e The original execution mechanism assumed daemon-owned in-process execution\n\u003e and a daemon-side second `Pool.Acquire`; `archie-core-q15y` removed both\n\u003e call sites, leaving one open question: how a fresh reviewer receives an\n\u003e isolated snapshot from inside the task-scoped worker, without a host\n\u003e executor or a nested container lifecycle. Section 1 below now answers it\n\u003e with `agent.Subagent`. Sections 2-5 were never invalidated and still hold;\n\u003e section 3's contract shipped as `archie-core-h019.2`.\n\nAnswers the five questions in `h019.1`'s description against the actual\nimplement workflow, not designed from scratch: the gate pattern, the\ncontainer pool, and the workflow engine's `Outcome` mechanism already answer\nmost of this.\n\n## 1. Where it runs: `agent.Subagent`, inside the task worker\n\nThe implement workflow's stage list\n(`internal/domain/workflow/implement.go`) already has the right slot:\nafter `StageDiffCap()`, before `StageOpenPR()` -- gates\nhave passed, the diff is final, and nothing has told the forge about this\nchange yet.\n\n**The reviewer is an `agent.Subagent` run, not a second container.** ai-sdk\n`v0.1.22` (already the pinned version) added `agent/subagent.go`: a nested,\nsynchronous `core.GenerateText` call in the same process, with its own model,\nsystem prompt, toolset and step budget. That is what makes this feature\nbuildable at all after `q15y` -- the reviewer runs inside the task-scoped\n`archie-agent` worker that is already executing the workflow, so there is no\nhost executor, no second `Pool.Acquire`, and no nested container lifecycle.\n\n**Two isolations are needed, and Subagent only provides one of them.**\n\n_Conversation isolation is structural, and free._ `Subagent.Run`\n(`agent/subagent.go`) calls `GenerateText` with `Prompt` set and\n`Messages` never populated. The implementer's history has no code path into\nthe nested run; only the prompt string crosses, and only text comes back.\nThis is the literal form of \"environmental enforcement over prompt rules\":\nthe reviewer is not told to ignore the implementer's reasoning, because\nnothing hands it any. `h019.3`'s required test asserts this as a construction\nfact.\n\n_Workspace isolation is still ours to build._ A sub-agent shares the parent's\nprocess, working directory and credentials. So the `.git`-free snapshot from\nthe original decision survives unchanged and is load-bearing: export the\nreviewed commit (`git archive \u003ccommit\u003e | tar -x`) into a fresh scratch\ndirectory beside, not inside, the task worktree, and write `diff.patch` (the\ndiff already computed for `StageYaegiGate`'s `Trees.Diff()`) and `issue.md`\n(the originating issue's title and body, nothing else) alongside it. Stripping\n`.git` is what makes commit messages, branch name and reflog -- the actual\nchannel a multi-commit implementer's reasoning leaks through -- structurally\nunreachable rather than merely undisclosed.\n\n`Subagent.Tools` therefore takes a **distinct read-only toolset rooted at the\nsnapshot**. Never the worker's own toolset: it carries the `worktreerpc`\npublication grant, so a reviewer holding it could push the branch it exists to\nblock.\n\n**Call `Run()`, not `Tool()`.** `Tool()` would register delegation as a tool\nthe _implementer's_ model may choose to invoke -- self-certification by the\nimplementer, which is the exact failure this feature exists to prevent. The\nstage calls `Run()` unconditionally. That also sidesteps both of `Tool()`'s\ndocumented footguns: the parent's two-step minimum and the recursion risk of\npassing a toolset back to itself.\n\n**Findings return through a closure, not the return value.** `Run` yields only\nfinal text, so section 3's structured contract cannot ride the return. Because\nthe sub-agent is in-process, the capture tool's Go implementation appends\ndirectly to a `[]workflow.ReviewFinding` the stage owns. This preserves the\n\"cannot end its turn without calling a typed tool\" property, and it defeats\n`Subagent`'s documented \"no partial results on failure\" limitation: findings\nalready captured survive an error return, so **the stage reads the captured\nslice even when `Run` returns an error**. A reviewer that logged three defects\nand then hit its step limit still yields those three.\n\n## 2. What it's given, and what it must never be given\n\n**Given:** the clean file-content snapshot (so the reviewer can read whole\nfiles -- follow an import, check interface satisfaction, see a call site --\nnot just diff hunks, which the manual-read checklist in CLAUDE.md rLine truncated
},
{
"url": "/dev/prds/agent2agent-protocol/",
"title": "Agent2Agent as archie's agent-to-agent protocol — decision",
"section": "PRDs",
"body": "# Agent2Agent as archie's agent-to-agent protocol — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** the A2A Protocol Specification v1.0.0 (`a2a-protocol.org`) for the\nprotocol, `docs/architecture/organisation.md` for package placement, and\n`docs/architecture/migration-decisions.md` §2 for session and messaging design.\n\n## Decision\n\nA2A is the protocol archie speaks to other agents. It carries agent-to-agent\nwork: discovery of what a remote agent offers, delegation of a unit of work to it,\nprogress on that work, and the artifacts it produces.\n\n## Layers\n\n**MCP stays the tool layer.** MCP connects a model to tools and data; A2A connects\nagents to agents. They are complementary and archie runs both:\n`internal/tools/provider` registers MCP providers as optional capabilities, so an\nA2A call and an MCP tool call are different kinds of traffic with different\nowners.\n\n**A2A rides archie's existing transports.** A2A's canonical data model is\nProtocol Buffer messages and it defines a gRPC binding, so archie speaks A2A over\nthe gRPC and NATS it already runs. A second wire format, a second broker, or a\nbespoke protocol for agent-to-agent traffic is a requirement not to introduce.\n\n## Where A2A stops\n\nA2A is not a general replacement for either of the two protocols archie already\nhas, and each boundary is a requirement rather than a preference.\n\n- **`internal/domain/messaging` stays the human and channel layer.** A\n Conversation is a ChannelID and a ThreadID, its participants are people on\n Telegram, email, webhook and the dashboard, and its records are what a curator\n reads. An A2A peer is not a channel participant and does not address a\n Conversation.\n- **`internal/agentexec` stays the daemon-to-worker execution protocol.** It\n carries a Request, a Result, gate and budget policy, and capture tools between\n the daemon and the agent container it owns. An A2A peer never receives that\n protocol, and A2A never carries gate, budget or protection policy.\n\nA2A is therefore an edge protocol: it exchanges work with peers outside archie's\nown process boundary, and it composes with the two protocols above rather than\nreplacing or abstracting them.\n\n## A2A Task mapping\n\n**Decision: archie's work lifecycle is mapped to A2A's, not expressed in it. An\nA2A Task is a view over archie's own task, and archie's status remains the record\nof truth.**\n\nThis is the load-bearing decision, because A2A's Task carries its own state\nmachine and archie's lifecycle is the on-disk format of its task store, whose\nstatus strings a rename migrates rather than changes.\n\nThe mapping is partial, and each gap is a case where archie knows something A2A's\nstates do not carry:\n\n- **Completion by another system.** A2A's terminal states describe what the agent\n did (`completed`, `failed`, `canceled`, `rejected`). archie's `merged` and\n `rejected` describe what a forge did to a pull request after archie finished\n its work. There is no A2A state for \"an external system accepted this\", so a\n completed A2A task cannot express the outcome that matters most to the caller.\n- **Handing work to a reviewer.** archie's `pr_open` means the work left\n archie's hands for human review. A2A's `input-required` is the nearest state,\n but it means the *client* must send more input, and a reviewer is not the\n client.\n- **Operator decisions.** `declined`, `parked` and `dead` are outcomes of\n archie's own policy and operator actions. A2A has no state for \"the operator\n refused this\" or \"a budget ran out and an operator must decide\".\n\nA WorkflowExecution is the unit an A2A task maps onto, because it is the attempt\nthat runs, streams and produces artifacts, and a follow-up attempt is a new\nexecution. A2A's own model agrees that a task is immutable once terminal and that\na refinement is a new task sharing the `contextId`, which is why archie's\nper-attempt executions and A2A's per-request tasks correspond.\n\n**Requirement:** the A2A state a peer sees is derived from archie's status by one\nmapping, and archie's status is carried on the task so a peer can read what the\nderivation lost. The mapping is total in the direction that matters -- every\narchie status has an A2A state -- and deliberately not injective, because the\ngaps above are facts A2A cannot hold.\n\n**Requirement:** adopting A2A's state names as archie's persisted task status is\nrejected. It would migrate the task store, and it would drop the forge outcomes\nthat tell a caller whether the work was accepted.\n\n## What an A2A agent is\n\n**An A2A agent is an archie Identity.** The Agent Card describes a durable,\naddressable actor with an endpoint, capabilities and authentication requirements,\nand an Identity is the actor archie persists, versions, suspends and scopes\ncredentials to.\n\nAn `agent.Persona` is not an A2A agent: a persona is prompt text selected for a\nturn, and it has no endpLine truncated
"body": "# Agent2Agent as archie's agent-to-agent protocol — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** the A2A Protocol Specification v1.0.0 (`a2a-protocol.org`) for the\nprotocol, `docs/architecture/organisation.md` for package placement, and\n`docs/architecture/migration-decisions.md` §2 for session and messaging design.\n\n## Decision\n\nA2A is the protocol archie speaks to other agents. It carries agent-to-agent\nwork: discovery of what a remote agent offers, delegation of a unit of work to it,\nprogress on that work, and the artifacts it produces.\n\n## Layers\n\n**MCP stays the tool layer.** MCP connects a model to tools and data; A2A connects\nagents to agents. They are complementary and archie runs both:\n`internal/tools/provider` registers MCP providers as optional capabilities, so an\nA2A call and an MCP tool call are different kinds of traffic with different\nowners.\n\n**A2A rides archie's existing transports.** A2A's canonical data model is\nProtocol Buffer messages and it defines a gRPC binding, so archie speaks A2A over\nthe gRPC and NATS it already runs. A second wire format, a second broker, or a\nbespoke protocol for agent-to-agent traffic is a requirement not to introduce.\n\n## Where A2A stops\n\nA2A is not a general replacement for either of the two protocols archie already\nhas, and each boundary is a requirement rather than a preference.\n\n- **`internal/domain/messaging` stays the human and channel layer.** A\n Conversation is a ChannelID and a ThreadID, its participants are people on\n Telegram, email, webhook and the dashboard, and its records are what a curator\n reads. An A2A peer is not a channel participant and does not address a\n Conversation.\n- **`internal/agentexec` stays the daemon-to-worker execution protocol.** It\n carries a Request, a Result, gate and budget policy, and capture tools between\n the daemon and the agent container it owns. An A2A peer never receives that\n protocol, and A2A never carries gate, budget or protection policy.\n\nA2A is therefore an edge protocol: it exchanges work with peers outside archie's\nown process boundary, and it composes with the two protocols above rather than\nreplacing or abstracting them.\n\n## A2A Task mapping\n\n**Decision: archie's work lifecycle is mapped to A2A's, not expressed in it. An\nA2A Task is a view over archie's own task, and archie's status remains the record\nof truth.**\n\nThis is the load-bearing decision, because A2A's Task carries its own state\nmachine and archie's lifecycle is the on-disk format of its task store, whose\nstatus strings a rename migrates rather than changes.\n\nThe mapping is partial, and each gap is a case where archie knows something A2A's\nstates do not carry:\n\n- **Completion by another system.** A2A's terminal states describe what the agent\n did (`completed`, `failed`, `canceled`, `rejected`). archie's `merged` and\n `rejected` describe what a forge did to a pull request after archie finished\n its work. There is no A2A state for \"an external system accepted this\", so a\n completed A2A task cannot express the outcome that matters most to the caller.\n- **Handing work to a reviewer.** archie's `pr_open` means the work left\n archie's hands for human review. A2A's `input-required` is the nearest state,\n but it means the _client_ must send more input, and a reviewer is not the\n client.\n- **Operator decisions.** `declined`, `parked` and `dead` are outcomes of\n archie's own policy and operator actions. A2A has no state for \"the operator\n refused this\" or \"a budget ran out and an operator must decide\".\n\nA WorkflowExecution is the unit an A2A task maps onto, because it is the attempt\nthat runs, streams and produces artifacts, and a follow-up attempt is a new\nexecution. A2A's own model agrees that a task is immutable once terminal and that\na refinement is a new task sharing the `contextId`, which is why archie's\nper-attempt executions and A2A's per-request tasks correspond.\n\n**Requirement:** the A2A state a peer sees is derived from archie's status by one\nmapping, and archie's status is carried on the task so a peer can read what the\nderivation lost. The mapping is total in the direction that matters -- every\narchie status has an A2A state -- and deliberately not injective, because the\ngaps above are facts A2A cannot hold.\n\n**Requirement:** adopting A2A's state names as archie's persisted task status is\nrejected. It would migrate the task store, and it would drop the forge outcomes\nthat tell a caller whether the work was accepted.\n\n## What an A2A agent is\n\n**An A2A agent is an archie Identity.** The Agent Card describes a durable,\naddressable actor with an endpoint, capabilities and authentication requirements,\nand an Identity is the actor archie persists, versions, suspends and scopes\ncredentials to.\n\nAn `agent.Persona` is not an A2A agent: a persona is prompt text selected for a\nturn, and it has no endpLine truncated
},
{
"url": "/dev/prds/artifact-sender/",
"title": "Artifact sender",
"section": "PRDs",
"body": "# Artifact sender\n\n**Status:** Approved\n**Revision:** 1\n**Authority:** this document\n\n## Purpose\n\narchie-core publishes artifacts — design documents, review reports, research briefs,\nrunnable pages — to the offloaded.dev collaborative editor. A person reads the\nartifact, comments on it, and the artifact page is the shared surface for iteration.\n\nThe receiving contract is owned by the editor: `POST /api/artifacts` with a bearer\nservice token, a closed field set, and server-side idempotency on `requestId` plus\nlast-write-wins on `sentAt`. This document owns only what archie-core sends.\n\n## Scope\n\nVersion one publishes one-way: archie-core sends, the editor receives. The first\nproducer is the pull-request adversarial review: a completed `ReviewReport` is\nrendered to markdown and published after the review completes.\n\nChat-surface tools (`create_artifact`, `update_artifact`), comment read-back, share\ntokens, and runnable-format producers (`html`, `react`, `vue`) are later slices. The\nreceiving contract already carries them; version one does not exercise them.\n\n## Configuration\n\n- New `[artifacts]` section: `base_url` (site origin), `token` (`SecretRef`) with\n `token_env` fallback naming `WORKSPACE_INGEST_TOKEN`.\n- An empty `base_url` disables the sender: no client is constructed, nothing is\n registered, and publishing degrades to a log line.\n- The token is runtime configuration. It is never baked at build time.\n\n## Sender\n\n- New package `internal/infrastructure/artifactsync` exposing one method,\n `Publish(ctx, Artifact) (string, error)`, where the string is the artifact URL.\n One-method injected seam, concrete client constructed by the boot path when the\n configuration resolves — the `crondelivery.Courier` posture.\n- The client POSTs the frozen contract body. Each publish sends the complete\n source: versions of record are full snapshots, never diffs.\n- A `503` response is retried three times with backoff. `401` and `400` are not\n retried; they are logged with the field reason the response names.\n- `requestId` is `artifact:\u003ctask-id\u003e:\u003cversion\u003e` when the producer is task-backed,\n otherwise `artifact:\u003cidentity\u003e:\u003csentAt-utc\u003e`. Sending the same `requestId` with\n an equal or older `sentAt` must be a server-side no-op, which makes sender-side\n retry safe.\n\n## Report rendering\n\n- `ReviewReport` gains a pure markdown renderer in `internal/domain/workflow`:\n the summary as the lede, one finding per subsection with file, line, verdict,\n level and the failure scenario, and the verified properties as a \"checked\n clean\" list. Findings carry their disposition when present.\n- The renderer performs no I/O and imports no infrastructure.\n\n## Attribution\n\n- `actor`: the producing identity. The reviewer publishes as `system:pr-reviewer`\n when no task identity resolves; otherwise the task's identity name.\n- `source`: the producing subsystem, `pr-review` for version one.\n- `task`: owner, repository and issue number from the task when one exists.\n\n## Failure behaviour\n\n- Publishing never fails the producing work. A failed publish is logged with its\n status and reason; the artifact is republished on the next production of the\n same artifact.\n- A successful publish records the artifact URL in the run report, so the PR\n description or task log links to the readable artifact.\n- The published URL is the editor deep link for the artifact, keyed on its\n immutable id. archie-core never mints share links; sharing is an\n account-holder decision made in the editor.\n\n## Verification\n\n- Client tests against a test server cover 201, 401, 400 with a field reason,\n and 503 retry behaviour.\n- The report renderer test covers a report with findings, checks, dispositions\n and a not-run status.\n- Configuration tests cover the disabled case, the `SecretRef` path and the\n `token_env` fallback."
"body": "# Artifact sender\n\n**Status:** Approved\n**Revision:** 1\n**Authority:** this document\n\n## Purpose\n\narchie-core publishes artifacts — design documents, review reports, research briefs,\nrunnable pages — to the offloaded.dev collaborative editor. A person reads the\nartifact, comments on it, and the artifact page is the shared surface for iteration.\n\nThe receiving contract is owned by the editor: `POST /api/artifacts` with a bearer\nservice token, a closed field set, and server-side idempotency on `requestId` plus\nlast-write-wins on `sentAt`. This document owns only what archie-core sends.\n\n## Scope\n\nVersion one publishes one-way: archie-core sends, the editor receives. The first\nproducer is the pull-request adversarial review: a completed `ReviewReport` is\nrendered to markdown and published after the review completes.\n\nChat-surface tools (`create_artifact`, `update_artifact`), comment read-back, share\ntokens, and runnable-format producers (`html`, `react`, `vue`) are later slices. The\nreceiving contract already carries them; version one does not exercise them.\n\n## Configuration\n\n- New `[artifacts]` section: `base_url` (site origin), `token` (`SecretRef`) with\n `token_env` fallback naming `WORKSPACE_INGEST_TOKEN`.\n- An empty `base_url` disables the sender: no client is constructed, nothing is\n registered, and publishing degrades to a log line.\n- The token is runtime configuration. It is never baked at build time.\n\n## Sender\n\n- New package `internal/infrastructure/artifactsync` exposing one method,\n `Publish(ctx, Artifact) (string, error)`, where the string is the artifact URL.\n One-method injected seam, concrete client constructed by the boot path when the\n configuration resolves — the `crondelivery.Courier` posture.\n- The client POSTs the frozen contract body. Each publish sends the complete\n source: versions of record are full snapshots, never diffs.\n- A `503` response is retried three times with backoff. `401` and `400` are not\n retried; they are logged with the field reason the response names.\n- `requestId` is `artifact:\u003ctask-id\u003e:\u003cversion\u003e` when the producer is task-backed,\n otherwise `artifact:\u003cidentity\u003e:\u003csentAt-utc\u003e`. Sending the same `requestId` with\n an equal or older `sentAt` must be a server-side no-op, which makes sender-side\n retry safe.\n\n## Report rendering\n\n- `ReviewReport` gains a pure markdown renderer in `internal/domain/workflow`:\n the summary as the lede, one finding per subsection with file, line, verdict,\n level and the failure scenario, and the verified properties as a \"checked\n clean\" list. Findings carry their disposition when present.\n- The renderer performs no I/O and imports no infrastructure.\n\n## Attribution\n\n- `actor`: the producing identity. The reviewer publishes as `system:pr-reviewer`\n when no task identity resolves; otherwise the task's identity name.\n- `source`: the producing subsystem, `pr-review` for version one.\n- `task`: owner, repository and issue number from the task when one exists.\n\n## Failure behaviour\n\n- Publishing never fails the producing work. A failed publish is logged with its\n status and reason; the artifact is republished on the next production of the\n same artifact.\n- A successful publish records the artifact URL in the run report, so the PR\n description or task log links to the readable artifact.\n- The published URL is the editor deep link for the artifact, keyed on its\n immutable id. archie-core never mints share links; sharing is an\n account-holder decision made in the editor.\n\n## Verification\n\n- Client tests against a test server cover 201, 401, 400 with a field reason,\n and 503 retry behaviour.\n- The report renderer test covers a report with findings, checks, dispositions\n and a not-run status.\n- Configuration tests cover the disabled case, the `SecretRef` path and the\n `token_env` fallback.\n"
},
{
"url": "/dev/prds/binding-secret-encryption/",
"title": "Binding secret at-rest encryption -- decision",
"section": "PRDs",
"body": "# Binding secret at-rest encryption -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-t2db.7` (P2), parent `archie-core-t2db`\n\n## Problem\n\n`binding.Binding.Secret` (the per-source HMAC shared secret) is persisted as\nplaintext in the `bindings.secret TEXT` column. Anyone with read access to the\nSQLite file -- the same access level as `captured_events.body` and `tasks.body`\n-- sees sender-side shared secrets. A leaked database file leaks secrets even\nwhen the filesystem ACLs were correct at rest.\n\n## Decision\n\nEncrypt the `secret` column at rest with **AES-256-GCM** (stdlib\n`crypto/aes` + `crypto/cipher`, no new dependency), transparently inside the\nstore: encrypt on write, decrypt on read. The store is the data boundary; its\nconsumers (dispatch loop, HMAC verification) receive the plaintext secret\nexactly as and the webui already blanks `Secret` on every response.\n\n### Cipher parameters\n\n- **AEAD:** AES-256-GCM, 12-byte random nonce (`crypto/rand`), tag appended.\n- **Key length:** 32 bytes, derived as `SHA-256(resolved_material)`. Kept as\n SHA-256 (no Argon2id) because the source is a **32-byte high-entropy** value\n resolved through the secret registry, so re-deriving to 32 bytes merely\n re-shapes entropy rather than defending a weak passphrase.\n- **AAD:** a static domain separator, `[]byte(\"arcie-binding-secret\")`, so a\n ciphertext cannot be relocated to a different field/column and still\n authenticate. AAD is intentionally **not** row-bound: binding secrets are\n random HMAC keys and are never used as lookup keys, so cross-row swap is not\n a meaningful attack here.\n\n### Envelope format\n\n```\narcie-binding:v1:\u003ckeyFingerprint\u003e:\u003cbase64url(nonce || ciphertext || tag)\u003e\n```\n\n- `arcie-binding` -- domain marker\n- `v1` -- format version (future cipher/KDF change is a new version, old rows\n stay readable)\n- `\u003ckeyFingerprint\u003e` -- `hex(SHA-256(material))[:16]`, the identity of the key\n that sealed the row, enabling rotation without a one-shot rewrite\n- payload -- `base64url` of `nonce ‖ GCM.Seal(plaintext, aad)`\n\n### Key source (confirmed with maintainer)\n\nResolved through the existing secret registry (`internal/secret`), the\nestablished `SecretRef` pattern already used for `forge.webhook_secret`:\n\n```toml\n[bindings]\nencryption_key = { engine = \"env\", key = \"ARCHIE_BINDING_KEY\" }\n# Rotation: after swapping encryption_key to a new value, retain the previous\n# material so rows sealed under the old key still decrypt.\nprevious_encryption_keys = [ { engine = \"env\", key = \"ARCHIE_BINDING_KEY_OLD\" } ]\n```\n\nThe active key encrypts new writes; `previous_encryption_keys` are retained for\ndecrypt-only. Key identity is intrinsic to the material (the fingerprint), so\nno manual key IDs are configured.\n\n### Rotation story\n\nRotate by changing `encryption_key`, moving the old material into\n`previous_encryption_keys`. Rows sealed under the old key still decrypt via\ntheir embedded fingerprint; new writes use the new active key. Once no\nremaining row references an old fingerprint, remove it from the config. Losing\na fingerprint's material before all its rows are rewritten makes those rows\nunreadable -- the same operational rule as any key rotation, and the reason the\nold material must be retained.\n\n## Non-goals / deferred\n\n- **`captured_events.body` redaction hardening** was completed alongside this\n work (not deferred): `webhookguard.RedactPayload` now redacts an expanded set\n of secret key markers (compound names like `access_token`, `client_secret`,\n `signing_key`, `x_api_key`, …) as well as unambiguous value shapes (compact\n JWTs, PEM private-key blocks) under any key. `gateway.sensitiveParameterKey`\n was broadened identically to preserve the documented agreement. It remains\n best-effort per `docs/prds/webhook-intake-security.md` point 5 -- a sender\n that picks a name the heuristic misses is still captured.\n- **Key re-derivation on config reload** is a startup concern: the store holds\n the cipher for its lifetime, so a reload that changes `[bindings]` keys\n requires a daemon restart to take effect. Documented, accepted.\n\n## Wiring\n\n- `internal/config`: add `BindingsConfig` (`encryption_key SecretRef`,\n `previous_encryption_keys []SecretRef`) on `Config.Bindings`.\n- `internal/app/archied/bootstrap.go` `openStores`: resolve both refs through\n the already-built `secrets` registry, pass the material to `store.Open` via a\n new option `store.WithBindingCipher(cipher)`.\n- `internal/store`: add a `BindingCipher` interface (concrete AES-GCM impl in\n `binding_cipher.go`), a `bindingCipher` field on `Store`, and the `Open`\n option. **Nil cipher = plaintext**, so existing call sites and tests change\n nothing and legacy deployments keep current behaviour until they set a key.\n\n## Back-compat \u0026 tests\n\n- `storLine truncated
"body": "# Binding secret at-rest encryption -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-t2db.7` (P2), parent `archie-core-t2db`\n\n## Problem\n\n\u003e Storage superseded: every store now lives in PostgreSQL behind\n\u003e `internal/domain/storecontract`, implemented in `internal/infrastructure/postgres`\n\u003e (`docs/prds/state-store-contract.md`). SQLite names below describe the\n\u003e original design.\n\n`binding.Binding.Secret` (the per-source HMAC shared secret) is persisted as\nplaintext in the `bindings.secret TEXT` column. Anyone with read access to the\nSQLite file -- the same access level as `captured_events.body` and `tasks.body`\n-- sees sender-side shared secrets. A leaked database file leaks secrets even\nwhen the filesystem ACLs were correct at rest.\n\n## Decision\n\nEncrypt the `secret` column at rest with **AES-256-GCM** (stdlib\n`crypto/aes` + `crypto/cipher`, no new dependency), transparently inside the\nstore: encrypt on write, decrypt on read. The store is the data boundary; its\nconsumers (dispatch loop, HMAC verification) receive the plaintext secret\nexactly as and the webui already blanks `Secret` on every response.\n\n### Cipher parameters\n\n- **AEAD:** AES-256-GCM, 12-byte random nonce (`crypto/rand`), tag appended.\n- **Key length:** 32 bytes, derived as `SHA-256(resolved_material)`. Kept as\n SHA-256 (no Argon2id) because the source is a **32-byte high-entropy** value\n resolved through the secret registry, so re-deriving to 32 bytes merely\n re-shapes entropy rather than defending a weak passphrase.\n- **AAD:** a static domain separator, `[]byte(\"arcie-binding-secret\")`, so a\n ciphertext cannot be relocated to a different field/column and still\n authenticate. AAD is intentionally **not** row-bound: binding secrets are\n random HMAC keys and are never used as lookup keys, so cross-row swap is not\n a meaningful attack here.\n\n### Envelope format\n\n```\narcie-binding:v1:\u003ckeyFingerprint\u003e:\u003cbase64url(nonce || ciphertext || tag)\u003e\n```\n\n- `arcie-binding` -- domain marker\n- `v1` -- format version (future cipher/KDF change is a new version, old rows\n stay readable)\n- `\u003ckeyFingerprint\u003e` -- `hex(SHA-256(material))[:16]`, the identity of the key\n that sealed the row, enabling rotation without a one-shot rewrite\n- payload -- `base64url` of `nonce ‖ GCM.Seal(plaintext, aad)`\n\n### Key source (confirmed with maintainer)\n\nResolved through the existing secret registry (`internal/secret`), the\nestablished `SecretRef` pattern already used for `forge.webhook_secret`:\n\n```toml\n[bindings]\nencryption_key = { engine = \"env\", key = \"ARCHIE_BINDING_KEY\" }\n# Rotation: after swapping encryption_key to a new value, retain the previous\n# material so rows sealed under the old key still decrypt.\nprevious_encryption_keys = [ { engine = \"env\", key = \"ARCHIE_BINDING_KEY_OLD\" } ]\n```\n\nThe active key encrypts new writes; `previous_encryption_keys` are retained for\ndecrypt-only. Key identity is intrinsic to the material (the fingerprint), so\nno manual key IDs are configured.\n\n### Rotation story\n\nRotate by changing `encryption_key`, moving the old material into\n`previous_encryption_keys`. Rows sealed under the old key still decrypt via\ntheir embedded fingerprint; new writes use the new active key. Once no\nremaining row references an old fingerprint, remove it from the config. Losing\na fingerprint's material before all its rows are rewritten makes those rows\nunreadable -- the same operational rule as any key rotation, and the reason the\nold material must be retained.\n\n## Non-goals / deferred\n\n- **`captured_events.body` redaction hardening** was completed alongside this\n work (not deferred): `webhookguard.RedactPayload` now redacts an expanded set\n of secret key markers (compound names like `access_token`, `client_secret`,\n `signing_key`, `x_api_key`, …) as well as unambiguous value shapes (compact\n JWTs, PEM private-key blocks) under any key. `gateway.sensitiveParameterKey`\n was broadened identically to preserve the documented agreement. It remains\n best-effort per `docs/prds/webhook-intake-security.md` point 5 -- a sender\n that picks a name the heuristic misses is still captured.\n- **Key re-derivation on config reload** is a startup concern: the store holds\n the cipher for its lifetime, so a reload that changes `[bindings]` keys\n requires a daemon restart to take effect. Documented, accepted.\n\n## Wiring\n\n- `internal/config`: add `BindingsConfig` (`encryption_key SecretRef`,\n `previous_encryption_keys []SecretRef`) on `Config.Bindings`.\n- `internal/app/archied/bootstrap.go` `openStores`: resolve both refs through\n the already-built `secrets` registry, pass the material to `store.Open` via a\n new option `store.WithBindingCipher(cipher)`.\n- `internal/infrastructure/bindingcipher`: the `BindingCipher` interface and\n concrLine truncated
},
{
"url": "/dev/prds/channel-forge-positions/",
"title": "Channel and Forge action positions (resolves `t2db.19`)",
"section": "PRDs",
"body": "# Channel and Forge action positions (resolves `t2db.19`)\n\n**Status:** Approved\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Blocked on:** `archie-core-t2db.24` (the `playbook_dispatches` ledger) for\nimplementation of either position. Both are side-effecting, and `t2db.17`\nresolved the keying scheme in design only.\n\n## Forge\n\n`internal/forge.Forge` is already exactly the shape a native-Go action position\nneeds -- a real, typed, general-purpose interface, not something that needs a\nYaegi/Module-style schema-generation detour:\n\n```go\ntype Forge interface {\n IssueForge // AssignedIssues, IssuesWithLabel, CloseIssue, ...\n PullRequestForge // CreatePR, PRState\n RepoForge // AcceptInvitations, VerifyPush, LinkBranch, ...\n}\n```\n\n**Typed contract shape: native-Go-by-name, not a Module-kind.** Module's whole\nreason to exist is giving _Yaegi-authored, operator-supplied_ code a typed\ncontract to implement. `Forge` is already a typed Go interface with real, tested\nimplementations (GitHub, Gitea) selected at daemon startup by `forge.New(...)`.\nWrapping it in a Module-kind schema/`go:generate` detour would duplicate a\ncontract that already exists. A Forge action position should be: a small set of\nnamed operations (e.g. `close-issue`, `create-pr`, `link-branch`), each with a\ntyped `Args`/`Result` struct mirroring the matching method's parameters/return.\n\nThe dispatch target is `internal/domain/workflow.Forger`\n(`CloseIssue`/`CreatePR`/`LinkBranch` -- already exists, already exactly these\nthree operations), **not** `internal/forge.Forge` directly. `organisation.md`'s\ntarget structure places `forge/` under `internal/infrastructure/forge/`; the flat\n`internal/forge` is a flat, unmigrated legacy package in the same position\n`internal/workflow` was in before its own migration. A new domain package\ndepending on the flat package directly would create a domain-to-infrastructure\ndependency that breaks the moment `forge` migrates. `workflow.Forger` is the\nnarrow, already-domain-owned contract that exists for exactly this reason -- the\ndaemon's real `forge.Forge` client satisfies it at the wiring layer.\nDepend on `Forger`, not on `internal/forge`.\n\n**Operation scope for a first slice:** `close-issue` and `link-branch`\n(single-call, cleanly idempotent by event+issue identity) are the safe starting\nset. `create-pr` is explicitly a heavier case -- opening a PR is a\nharder-to-reverse action with its own dedup shape beyond \"did this event fire\nbefore\" (a redelivered event must not open a second PR for the same logical\nchange) -- defer it to a follow-up slice once the keying scheme is proven on the\nsimpler operations, don't design it blind now.\n\n**Host access:** the coordinator needs the same `Forge` instance\n`internal/daemon`'s poller already holds (constructed once at startup via\n`forge.New`). This is a daemon-composition wiring question (pass the existing\ninstance into the coordinator's constructor), not a new extensibility mechanism.\n\n## Channel\n\n### Constraints this satisfies\n\nMessaging is the root, Channel is the integration layer, an implementation such\nas Telegram sits under Channel. A channel is added by implementing one reusable\ninterface, and every channel must implement it. A notification mechanism belongs\nunder Messaging, and `channels.Channel` must not reach across into it.\n\n### Notification is a Messaging contract, not a channel type\n\nThe contract lives in `internal/domain/messaging`. A channel implementation\nsatisfies it by importing its own parent, which it already does, so the\ndependency stays `channels -\u003e messaging` and nothing points back.\n\n`channels.Channel` does not change. It gains no notification method and no\nimport, so the interface every channel must implement stays the lifecycle and\nconfig contract it is. `internal/channels/telegram` satisfying both\ncontracts is an implementation choosing to, not the Channel layer knowing about\nnotification.\n\nA notification is not a channel type because it has no lifecycle to start and\nstop, no inbound direction, and no configuration schema of its own. Modelling it\nas one would force `Start`/`Stop`/`ConfigSchema` onto something with no meaning\nfor them, and make every real channel declare whether it is a notification.\n\n### Destinations are configured, never named by a playbook\n\n`[notify]` becomes a set of named destinations. Each binds a name the operator\nchooses to a channel already registered in the Messaging composition\n(`internal/app/archiemessaging/compose.go` registers `telegram`, `email`,\n`webhook`) plus that channel's own address, such as a Telegram chat id. The\nexisting single-webhook form keeps working as a destination named `webhook`.\n\nA playbook action names a destination. It never names an address. Playbook\ntriggers are reachable from a public, unauthenticated intake surface, soLine truncated
"body": "# Channel and Forge action positions (resolves `t2db.19`)\n\n**Status:** Approved\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Blocked on:** `archie-core-t2db.24` (the `playbook_dispatches` ledger) for\nimplementation of either position. Both are side-effecting, and `t2db.17`\nresolved the keying scheme in design only.\n\n## Forge\n\n`internal/forge.Forge` is already exactly the shape a native-Go action position\nneeds -- a real, typed, general-purpose interface, not something that needs a\nYaegi/Module-style schema-generation detour:\n\n```go\ntype Forge interface {\n IssueForge // AssignedIssues, IssuesWithLabel, CloseIssue, ...\n PullRequestForge // CreatePR, PRState\n RepoForge // AcceptInvitations, VerifyPush, LinkBranch, ...\n}\n```\n\n**Typed contract shape: native-Go-by-name, not a Module-kind.** Module's whole\nreason to exist is giving _Yaegi-authored, operator-supplied_ code a typed\ncontract to implement. `Forge` is already a typed Go interface with real, tested\nimplementations (GitHub, Gitea) selected at daemon startup by `forge.New(...)`.\nWrapping it in a Module-kind schema/`go:generate` detour would duplicate a\ncontract that already exists. A Forge action position should be: a small set of\nnamed operations (e.g. `close-issue`, `create-pr`, `link-branch`), each with a\ntyped `Args`/`Result` struct mirroring the matching method's parameters/return.\n\nThe dispatch target is `internal/domain/workflow.Forger`\n(`CloseIssue`/`CreatePR`/`LinkBranch` -- already exists, already exactly these\nthree operations), **not** `internal/forge.Forge` directly. `organisation.md`'s\ntarget structure places `forge/` under `internal/infrastructure/forge/`; the flat\n`internal/forge` is a flat, unmigrated legacy package in the same position\n`internal/workflow` was in before its own migration. A new domain package\ndepending on the flat package directly would create a domain-to-infrastructure\ndependency that breaks the moment `forge` migrates. `workflow.Forger` is the\nnarrow, already-domain-owned contract that exists for exactly this reason -- the\ndaemon's real `forge.Forge` client satisfies it at the wiring layer.\nDepend on `Forger`, not on `internal/forge`.\n\n**Operation scope for a first slice:** `close-issue` and `link-branch`\n(single-call, cleanly idempotent by event+issue identity) are the safe starting\nset. `create-pr` is explicitly a heavier case -- opening a PR is a\nharder-to-reverse action with its own dedup shape beyond \"did this event fire\nbefore\" (a redelivered event must not open a second PR for the same logical\nchange) -- defer it to a follow-up slice once the keying scheme is proven on the\nsimpler operations, don't design it blind now.\n\n**Host access:** the coordinator needs the same `Forge` instance\n`internal/daemon`'s poller already holds (constructed once at startup via\n`forge.New`). This is a daemon-composition wiring question (pass the existing\ninstance into the coordinator's constructor), not a new extensibility mechanism.\n\n## Channel\n\n### Constraints this satisfies\n\nMessaging is the root, Channel is the integration layer, an implementation such\nas Telegram sits under Channel. A channel is added by implementing one reusable\ninterface, and every channel must implement it. A notification mechanism belongs\nunder Messaging, and `channels.Channel` must not reach across into it.\n\n### Notification is a Messaging contract, not a channel type\n\nThe contract lives in `internal/domain/messaging`. A channel implementation\nsatisfies it by importing its own parent, which it already does, so the\ndependency stays `channels -\u003e messaging` and nothing points back.\n\n`channels.Channel` does not change. It gains no notification method and no\nimport, so the interface every channel must implement stays the lifecycle and\nconfig contract it is. `internal/channels/telegram` satisfying both\ncontracts is an implementation choosing to, not the Channel layer knowing about\nnotification.\n\nA notification is not a channel type because it has no lifecycle to start and\nstop, no inbound direction, and no configuration schema of its own. Modelling it\nas one would force `Start`/`Stop`/`ConfigSchema` onto something with no meaning\nfor them, and make every real channel declare whether it is a notification.\n\n### Destinations are configured, never named by a playbook\n\n`[notify]` becomes a set of named destinations. Each binds a name the operator\nchooses to a channel already registered in the Messaging composition\n(`internal/app/archiemessaging/compose.go` registers `telegram`, `email`,\n`webhook`) plus that channel's own address, such as a Telegram chat id. The\nexisting single-webhook form keeps working as a destination named `webhook`.\n\nA playbook action names a destination. It never names an address. Playbook\ntriggers are reachable from a public, unauthenticated intake surface, soLine truncated
},
{
"url": "/dev/prds/code-graph-mcp/",
"title": "Code graph over MCP (`tools/codegraph`)",
"section": "PRDs",
"body": "# Code graph over MCP (`tools/codegraph`)\n\n**Status:** Draft\n**Supersedes:** `symbol-reference-index.md`, which scoped only the data layer.\n\n## The problem\n\nEstablishing what a change touches costs an agent eight to fifteen\ngreps, and the answers are wrong in specific ways. `grep -rn \"Register(\"`\ncannot separate `plugin.Registry.Register` from `captureintake.Receiver.Register`\nfrom `forgerpc.Server.Register`, all of which exist here. It also matches the\nsibling checkouts under `.worktrees/`, which are near-complete copies of the\nmodule, so every count is silently inflated.\n\nThat cost lands hardest in investigation, triage and the TDD loop, where the\nfirst question is always \"what does this touch\".\n\n## Decision: exact analysis, not semantic retrieval\n\nTools like Greptile parse with tree-sitter, summarise each node, embed the\nsummaries, and retrieve semantically. That design exists because they must\nserve any language. This repository is one Go module, and Go's type checker is\nground truth:\n\n| Question | Source of truth |\n| --- | --- |\n| Who references this symbol? | `go/packages` + `go/types`, resolved by identity |\n| What calls what? | `callgraph` RTA over SSA |\n| What imports what? | `go list -deps` |\n\nNo vector database, no embedding cost, no edges invented by a summary that\ndrifted from the code. For a single-language repository this is both cheaper\nand strictly more accurate. Copy the interface those tools expose, not their\narchitecture.\n\n**A code graph does not power a documentation chatbot.** It answers structural\nquestions about Go symbols. Answering \"how do I configure a second identity\"\nmeans retrieving prose from markdown, which needs chunking, embedding and\nsimilarity search over a different corpus entirely. That remains a separate\ncapability with its own design. Conflating the two would build one system that\ndoes neither well.\n\n## Interface: an MCP server\n\n`archied` already consumes MCP as a client (`internal/app/agentworker`\nstarts providers) and serves none. Exposing the graph over MCP reaches Claude\nCode, pi, codex and Archie's own agents through one surface, with no coupling\nto the daemon: it is configured like any other entry in `[[mcp_servers]]`.\n\nFour tools, each returning JSON with file:line citations:\n\n- `references(symbol)` — every reference site, classified `prod` / `test` /\n `generated` / `dynamic`\n- `callers(symbol, depth)` — inbound call edges\n- `callees(symbol, depth)` — outbound call edges\n- `blast_radius(file | symbol)` — the transitive neighbourhood a change reaches,\n which is the single call meant to replace the grep sequence\n\nDiagrams are deliberately not a tool. A model given an accurate subgraph writes\nits own Mermaid; a diagram endpoint would only fix the rendering of something\nthe model already has.\n\n## Decisions\n\n**Every answer declares what it could not see.** RTA over-approximates\ninterface dispatch, and reflection is invisible: every `reflect.ValueOf` entry\nin `wfextract`, `gateextract`, `pluginextract`, `secretextract` and\n`logextract` makes a symbol look reachable whether or not anything calls it.\nEach response carries a `dynamic_edges` field naming those boundaries. An agent\ntrusting a confident wrong graph is worse off than one that greps, so the graph\nstates its own limits rather than implying completeness.\n\n**Warm in memory, keyed on HEAD, never persisted to disk.** `deadcode` does\nwhole-program RTA in under seven seconds; this does less work. The server\nrebuilds when HEAD changes and refuses its cache outright when the tree is\ndirty. Nothing is written to disk, because a persisted index becomes a rendered\nview that outlives its evidence. That is the failure that made `STATUS.md`\nreport 90 of 91 findings re-verified while most statuses were 77 commits stale,\nand the same one that made `reachaudit` serve a previous tree's analysis from\n`/tmp` until its cache was keyed on HEAD.\n\n**`tools/codegraph`, not `internal/`.** It is developer tooling, not daemon\nruntime, so it belongs beside `docsgen`, `contractaudit` and `reachaudit` in\nthe `tools` module, which `task test:tools` already covers. Start as a single\nGo file; split only when it earns it.\n\n**No new dependency.** `golang.org/x/tools` is already in `go.sum` at v0.49.0.\n\n## How it is verified\n\nRed first. Table-driven tests against small fixture modules built in\n`t.TempDir()`, asserting the behaviour that distinguishes this from grep:\n\n1. Two methods spelled `Register` on different types resolve to two separate\n records, and a reference to one does not increment the other.\n2. A symbol referenced only from `_test.go` reports zero `prod` references.\n3. A symbol referenced only from a `reflect.ValueOf` table reports zero `prod`\n references and one `dynamic`, and names the table in `dynamic_edges`.\n4. A generated file's references land in `generated`, not `prod`.\n\nMutation-verify eachLine truncated
"body": "# Code graph over MCP (`tools/codegraph`)\n\n**Status:** Draft\n**Supersedes:** `symbol-reference-index.md`, which scoped only the data layer.\n\n## The problem\n\nEstablishing what a change touches costs an agent eight to fifteen\ngreps, and the answers are wrong in specific ways. `grep -rn \"Register(\"`\ncannot separate `plugin.Registry.Register` from `captureintake.Receiver.Register`\nfrom `forgerpc.Server.Register`, all of which exist here. It also matches the\nsibling checkouts under `.worktrees/`, which are near-complete copies of the\nmodule, so every count is silently inflated.\n\nThat cost lands hardest in investigation, triage and the TDD loop, where the\nfirst question is always \"what does this touch\".\n\n## Decision: exact analysis, not semantic retrieval\n\nTools like Greptile parse with tree-sitter, summarise each node, embed the\nsummaries, and retrieve semantically. That design exists because they must\nserve any language. This repository is one Go module, and Go's type checker is\nground truth:\n\n| Question | Source of truth |\n| --------------------------- | ------------------------------------------------ |\n| Who references this symbol? | `go/packages` + `go/types`, resolved by identity |\n| What calls what? | `callgraph` RTA over SSA |\n| What imports what? | `go list -deps` |\n\nNo vector database, no embedding cost, no edges invented by a summary that\ndrifted from the code. For a single-language repository this is both cheaper\nand strictly more accurate. Copy the interface those tools expose, not their\narchitecture.\n\n**A code graph does not power a documentation chatbot.** It answers structural\nquestions about Go symbols. Answering \"how do I configure a second identity\"\nmeans retrieving prose from markdown, which needs chunking, embedding and\nsimilarity search over a different corpus entirely. That remains a separate\ncapability with its own design. Conflating the two would build one system that\ndoes neither well.\n\n## Interface: an MCP server\n\n`archied` already consumes MCP as a client (`internal/app/agentworker`\nstarts providers) and serves none. Exposing the graph over MCP reaches Claude\nCode, pi, codex and Archie's own agents through one surface, with no coupling\nto the daemon: it is configured like any other entry in `[[mcp_servers]]`.\n\nFour tools, each returning JSON with file:line citations:\n\n- `references(symbol)` — every reference site, classified `prod` / `test` /\n `generated` / `dynamic`\n- `callers(symbol, depth)` — inbound call edges\n- `callees(symbol, depth)` — outbound call edges\n- `blast_radius(file | symbol)` — the transitive neighbourhood a change reaches,\n which is the single call meant to replace the grep sequence\n\nDiagrams are deliberately not a tool. A model given an accurate subgraph writes\nits own Mermaid; a diagram endpoint would only fix the rendering of something\nthe model already has.\n\n## Decisions\n\n**Every answer declares what it could not see.** RTA over-approximates\ninterface dispatch, and reflection is invisible: every `reflect.ValueOf` entry\nin `wfextract`, `gateextract`, `pluginextract`, `secretextract` and\n`logextract` makes a symbol look reachable whether or not anything calls it.\nEach response carries a `dynamic_edges` field naming those boundaries. An agent\ntrusting a confident wrong graph is worse off than one that greps, so the graph\nstates its own limits rather than implying completeness.\n\n**Warm in memory, keyed on HEAD, never persisted to disk.** `deadcode` does\nwhole-program RTA in under seven seconds; this does less work. The server\nrebuilds when HEAD changes and refuses its cache outright when the tree is\ndirty. Nothing is written to disk, because a persisted index becomes a rendered\nview that outlives its evidence. That is the failure that made `STATUS.md`\nreport 90 of 91 findings re-verified while most statuses were 77 commits stale,\nand the same one that made `reachaudit` serve a previous tree's analysis from\n`/tmp` until its cache was keyed on HEAD.\n\n**`tools/codegraph`, not `internal/`.** It is developer tooling, not daemon\nruntime, so it belongs beside `docsgen`, `contractaudit` and `reachaudit` in\nthe `tools` module, which `task test:tools` already covers. Start as a single\nGo file; split only when it earns it.\n\n**No new dependency.** `golang.org/x/tools` is already in `go.sum` at v0.49.0.\n\n## How it is verified\n\nRed first. Table-driven tests against small fixture modules built in\n`t.TempDir()`, asserting the behaviour that distinguishes this from grep:\n\n1. Two methods spelled `Register` on different types resolve to two separate\n records, and a reference to one does not increment the other.\n2. A symbol referenced only from `_test.go` reports zero `prod` references.\n3. A symbol referenced only from a `reflect.VLine truncated
},
{
"url": "/dev/prds/config-example-drift/",
"title": "Example-config and generated-config drift — decision",
"section": "PRDs",
"body": "# Example-config and generated-config drift — decision\n\n**Status:** Approved\n**Date:** 2026-09-15\n**Closes:** the checked-in-config half of audit findings `config-1` and\n`repo-root-deployment-2`; strengthens `doc-drift` findings generally.\n**Authority:** extends `docs/architecture/generated-documentation.md` and\n`docs/prds/config-schema.md`; does not replace either.\n\n## Question\n\nShould `config.example.toml` and `deployments/*.toml` be *generated*, so they\ncannot drift from the config code?\n\n## Decision\n\n**No — do not generate them. Gate them instead.** Neither file is a projection\nof the schema, and generating either would destroy the thing that makes it\nuseful. Three verified reasons, in order of weight:\n\n1. **`config.example.toml`'s value is its comments.** It documents **137 keys**\n (measured: active *and* commented-out), and those hand-written comments are\n the file's purpose — `docs/architecture/configuration.md` states outright\n that \"`config.example.toml` carries documentation users are meant to\n hand-edit\". TOML round-tripping does not preserve comments, which is exactly\n why `tomlwrite` does line-oriented edits rather than decode/encode. A\n generator would emit a correct file with the documentation deleted.\n2. **`docs/prds/config-schema.md` forbids building on `config.Config`.** That PRD\n rejects \"a reflection-based schema over `config.Config`\" because the struct is\n \"scheduled for dissolution\". A generator deriving the example from its struct\n tags would build on a foundation this repo has already decided to remove.\n3. **`docs/architecture/generated-documentation.md` prohibits it.** \"Adding\n another hardcoded type list to `docsgen` is prohibited\" — so any generator\n must consume a domain-owned registry, which does not exist for configuration\n yet. Creating one is the config-domain migration's job, not this change's.\n\nThe deployment profiles are also not a projection: they set **3-46 keys** against\nthe example's 137, and they are curated overlays (\"a complete config, not an\noverlay\", per their own headers), not near-duplicates. Generating them would add\nmachinery to remove duplication that largely is not there.\n\n## The gap that is real\n\n**Unknown config keys are silently ignored.** Verified at\n`internal/infrastructure/configuration/decode.go`:\n\n```go\nif _, err := toml.DecodeFile(path, target); err != nil {\n```\n\nThere is no `MetaData.Undecoded()` check, so a typo — `max_concurrancy = 4` —\nparses clean, validates clean, and does nothing. That is the same failure shape\nthis repo's audit found repeatedly: a setting that looks applied and is not. It\nis also detectable **without any hand-maintained list**, because `BurntSushi/toml`\nreports exactly which keys the target did not consume.\n\nNote the second, separate gap already admitted in writing:\n`generated-documentation.md` — \"`task check` does not run `docs:check`, so\ngenerated drift is ungated.\"\n\n## What to build\n\n**1. Unknown-key detection at the loader (behaviour).** Decode with metadata and\ncollect `Undecoded()`. Report it as a warning at startup listing the offending\nkeys, and expose it so tests can assert emptiness.\n\n**Deliberately a warning, not a fatal error.** `configuration.md`'s settled\nstartup policy is \"a missing credential disables a capability; only an invalid\nconfig stops the daemon\". A stray key is far more likely to be an operator typo\nin a file they are otherwise happy with than a reason to refuse to boot, and\n`[web]` is documented as landing in a *different* binary\n(`internal/app/archieui`), so a key unknown to one process is legitimately known\nto another. Failing closed here would break working deployments on upgrade.\n\n**2. A checked-in-config contract test (gate).** Load `config.example.toml` and\nevery `deployments/*.toml` through the real loader and assert `Undecoded()` is\nempty, with an explicit allowlist for keys another binary owns. This is the\nmechanism that would have caught a renamed key left behind in an example, and it\nneeds no inventory.\n\n**3. Gate generated data in `task check`.** Done. `task docs:check` runs in the\ngate, closing the admitted \"generated drift is ungated\" hole. The\ncheck mode did not exist when this was written; it was added for issue #855,\nwhich also made the check non-destructive so the gate can never rewrite the\nartifact it is judging.\n\n**4. Explicitly NOT now: a generated key inventory.** `configuration.md`'s\ncompletion criteria want \"generated documentation lists every external key,\ndefault, constraint, mutability class, owner\". That is a real target and it is\nthe config domain's, once a domain-owned registry exists — the prohibition above\nmeans it cannot be bootstrapped from a list inside `docsgen`. Recorded as\ndeferred, not rejected.\n\n## Non-goals\n\n- No generation of `config.example.toml` or `deployments/*.toml`.\n- No reflection-baLine truncated
"body": "# Example-config and generated-config drift — decision\n\n**Status:** Approved\n**Date:** 2026-09-15\n**Closes:** the checked-in-config half of audit findings `config-1` and\n`repo-root-deployment-2`; strengthens `doc-drift` findings generally.\n**Authority:** extends `docs/architecture/generated-documentation.md` and\n`docs/prds/config-schema.md`; does not replace either.\n\n## Question\n\nShould `config.example.toml` and `deployments/*.toml` be _generated_, so they\ncannot drift from the config code?\n\n## Decision\n\n**No — do not generate them. Gate them instead.** Neither file is a projection\nof the schema, and generating either would destroy the thing that makes it\nuseful. Three verified reasons, in order of weight:\n\n1. **`config.example.toml`'s value is its comments.** It documents **137 keys**\n (measured: active _and_ commented-out), and those hand-written comments are\n the file's purpose — `docs/architecture/configuration.md` states outright\n that \"`config.example.toml` carries documentation users are meant to\n hand-edit\". TOML round-tripping does not preserve comments, which is exactly\n why `tomlwrite` does line-oriented edits rather than decode/encode. A\n generator would emit a correct file with the documentation deleted.\n2. **`docs/prds/config-schema.md` forbids building on `config.Config`.** That PRD\n rejects \"a reflection-based schema over `config.Config`\" because the struct is\n \"scheduled for dissolution\". A generator deriving the example from its struct\n tags would build on a foundation this repo has already decided to remove.\n3. **`docs/architecture/generated-documentation.md` prohibits it.** \"Adding\n another hardcoded type list to `docsgen` is prohibited\" — so any generator\n must consume a domain-owned registry, which does not exist for configuration\n yet. Creating one is the config-domain migration's job, not this change's.\n\nThe deployment profiles are also not a projection: they set **3-46 keys** against\nthe example's 137, and they are curated overlays (\"a complete config, not an\noverlay\", per their own headers), not near-duplicates. Generating them would add\nmachinery to remove duplication that largely is not there.\n\n## The gap that is real\n\n**Unknown config keys are silently ignored.** Verified at\n`internal/infrastructure/configuration/decode.go`:\n\n```go\nif _, err := toml.DecodeFile(path, target); err != nil {\n```\n\nThere is no `MetaData.Undecoded()` check, so a typo — `max_concurrancy = 4` —\nparses clean, validates clean, and does nothing. That is the same failure shape\nthis repo's audit found repeatedly: a setting that looks applied and is not. It\nis also detectable **without any hand-maintained list**, because `BurntSushi/toml`\nreports exactly which keys the target did not consume.\n\nNote the second, separate gap already admitted in writing:\n`generated-documentation.md` — \"`task check` does not run `docs:check`, so\ngenerated drift is ungated.\"\n\n## What to build\n\n**1. Unknown-key detection at the loader (behaviour).** Decode with metadata and\ncollect `Undecoded()`. Report it as a warning at startup listing the offending\nkeys, and expose it so tests can assert emptiness.\n\n**Deliberately a warning, not a fatal error.** `configuration.md`'s settled\nstartup policy is \"a missing credential disables a capability; only an invalid\nconfig stops the daemon\". A stray key is far more likely to be an operator typo\nin a file they are otherwise happy with than a reason to refuse to boot, and\n`[web]` is documented as landing in a _different_ binary\n(`internal/app/archieui`), so a key unknown to one process is legitimately known\nto another. Failing closed here would break working deployments on upgrade.\n\n**2. A checked-in-config contract test (gate).** Load `config.example.toml` and\nevery `deployments/*.toml` through the real loader and assert `Undecoded()` is\nempty, with an explicit allowlist for keys another binary owns. This is the\nmechanism that would have caught a renamed key left behind in an example, and it\nneeds no inventory.\n\n**3. Gate generated data in `task check`.** Done. `task docs:check` runs in the\ngate, closing the admitted \"generated drift is ungated\" hole. The\ncheck mode did not exist when this was written; it was added for issue #855,\nwhich also made the check non-destructive so the gate can never rewrite the\nartifact it is judging.\n\n**4. Explicitly NOT now: a generated key inventory.** `configuration.md`'s\ncompletion criteria want \"generated documentation lists every external key,\ndefault, constraint, mutability class, owner\". That is a real target and it is\nthe config domain's, once a domain-owned registry exists — the prohibition above\nmeans it cannot be bootstrapped from a list inside `docsgen`. Recorded as\ndeferred, not rejected.\n\n## Non-goals\n\n- No generation of `config.example.toml` or `deployments/*.toml`.\n- No reflection-baLine truncated
},
{
"url": "/dev/prds/config-schema/",
"title": "Backend-owned configuration schema for the webui -- decision",
"section": "PRDs",
"body": "# Backend-owned configuration schema for the webui -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-b6ew` (epic), with children `.1`-`.5`\n\n## Decision\n\nThe dashboard's Configuration page keeps reading a secret-free,\nhand-picked view of `config.Config` -- that allowlist is a safety\nboundary and stays exactly as it is. What changes is who defines the\npage around it: `ui/src/settings/settings.js` and\n`config-row.js` hardcode every row's label, section, type, and\neditability by hand; after this, the backend attaches that metadata to\neach field it already allows through, and the frontend renders\nsections and fields generically from what the backend sends.\n\nThis is **not** a reflection-based schema over `config.Config`.\n`internal/config/config.go`'s own package doc states it is \"scheduled\nfor dissolution: its types and methods are to be reassigned to the\ndomains whose behaviour they describe\" -- building a generic\nschema-from-struct-tags mechanism over a struct on its way out would be\nbuilding on a foundation this repo has already decided to remove.\nInstead, every field already in `ConfigView` (`internal/webui/api_config.go`)\ngot there because someone deliberately vetted it as safe to show; the\nschema adds a hand-authored descriptor to that same deliberate act,\nnot a new mechanism that re-derives safety automatically.\n\n## Why now\n\nTask #6's investigation (`/9/26`) found the concrete failure this\nproduces: `Repo.AllowConcurrent` and `Repo.MaxRetries` already reach\n`GET /api/config` (`RepoView` in `api_config.go`), but the\nrepositories card renders a static read-only table that never shows\nthem, so the fix for \"why isn't a second agent running\" required an\nagent tracing Go source instead of a checkbox on the dashboard.\n`Repo.ReviewEnabled` is worse: it never reaches the API at all. Both\nare symptoms of the same root cause -- the frontend decides what a\nfield means and whether it's shown, and nothing keeps that in sync\nwith what the backend actually allows.\n\n## Shape\n\n```go\n// internal/webui/config_schema.go (new)\n\ntype ConfigFieldType string\n\nconst (\n FieldString ConfigFieldType = \"string\"\n FieldInt ConfigFieldType = \"int\"\n FieldBool ConfigFieldType = \"bool\"\n FieldDuration ConfigFieldType = \"duration\"\n FieldEnum ConfigFieldType = \"enum\"\n FieldStructured ConfigFieldType = \"structured\" // repositories, models, providers\n)\n\ntype ConfigField struct {\n Key string `json:\"key\"` // dotted path, matches UpdateConfig's key space\n Label string `json:\"label\"`\n Description string `json:\"description,omitempty\"`\n Type ConfigFieldType `json:\"type\"`\n Value any `json:\"value\"`\n Editable bool `json:\"editable\"`\n LockedReason string `json:\"locked_reason,omitempty\"`\n Overridden bool `json:\"overridden\"`\n Options []string `json:\"options,omitempty\"` // enum only\n RestartRequired bool `json:\"restart_required\"`\n}\n\ntype ConfigSection struct {\n ID string `json:\"id\"`\n Label string `json:\"label\"`\n Fields []ConfigField `json:\"fields\"`\n}\n```\n\n`handleConfig` builds `[]ConfigSection` from the existing per-field\nvalues it already assembles, plus `overlay.DeniedKeys` for\n`LockedReason` and the existing `Overridden` list -- both already\ncomputed just re-attached per field instead of returned as\nside-channel maps the frontend cross-references by key string.\n`Locked`/`Overridden`/`Reload`/`Provenance` stay as top-level\n`ConfigView` fields; they describe runtime state (what happened on\nthe last reload, which keys the overlay refuses), not the field\ncatalog, and duplicating that logic per-field would be the same drift\nrisk this change exists to remove.\n\n`FieldStructured` fields (repositories, models, providers) carry\n`Value` as structured JSON and are rendered by dedicated\neditors, not the generic renderer -- see \"What this does not do\".\n\n## Sections\n\nMatches the cards the settings page already has: `identity`,\n`repositories`, `models`, `providers`, `budgets`, `storage`,\n`containers`, `web`. No new sections; this is metadata on existing\nrows, not new configuration surface.\n\n## Frontend\n\n`config-row.js`'s `row(label, value, opts)` becomes the renderer's\nprivate implementation detail, called generically:\n\n```js\nfor (const section of schema.sections) {\n const rows = section.fields\n .filter(f =\u003e f.type !== \"structured\")\n .map(f =\u003e row(f.label, f.value, {\n key: f.key, type: f.type, options: f.options,\n locked: f.locked_reason, overridden: f.overridden,\n restartRequired: f.restart_required,\n }));\n // structured fields render through their dedicated editor (b6ew.4)\n}Line truncated
"body": "# Backend-owned configuration schema for the webui -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-b6ew` (epic), with children `.1`-`.5`\n\n## Decision\n\nThe dashboard's Configuration page keeps reading a secret-free,\nhand-picked view of `config.Config` -- that allowlist is a safety\nboundary and stays exactly as it is. What changes is who defines the\npage around it: `ui/src/settings/settings.js` and\n`config-row.js` hardcode every row's label, section, type, and\neditability by hand; after this, the backend attaches that metadata to\neach field it already allows through, and the frontend renders\nsections and fields generically from what the backend sends.\n\nThis is **not** a reflection-based schema over `config.Config`.\n`internal/config/config.go`'s own package doc states it is \"scheduled\nfor dissolution: its types and methods are to be reassigned to the\ndomains whose behaviour they describe\" -- building a generic\nschema-from-struct-tags mechanism over a struct on its way out would be\nbuilding on a foundation this repo has already decided to remove.\nInstead, every field already in `ConfigView` (`internal/webui/api_config.go`)\ngot there because someone deliberately vetted it as safe to show; the\nschema adds a hand-authored descriptor to that same deliberate act,\nnot a new mechanism that re-derives safety automatically.\n\n## Why now\n\nTask #6's investigation (`/9/26`) found the concrete failure this\nproduces: `Repo.AllowConcurrent` and `Repo.MaxRetries` already reach\n`GET /api/config` (`RepoView` in `api_config.go`), but the\nrepositories card renders a static read-only table that never shows\nthem, so the fix for \"why isn't a second agent running\" required an\nagent tracing Go source instead of a checkbox on the dashboard.\n`Repo.ReviewEnabled` is worse: it never reaches the API at all. Both\nare symptoms of the same root cause -- the frontend decides what a\nfield means and whether it's shown, and nothing keeps that in sync\nwith what the backend actually allows.\n\n## Shape\n\n```go\n// internal/webui/config_schema.go (new)\n\ntype ConfigFieldType string\n\nconst (\n FieldString ConfigFieldType = \"string\"\n FieldInt ConfigFieldType = \"int\"\n FieldBool ConfigFieldType = \"bool\"\n FieldDuration ConfigFieldType = \"duration\"\n FieldEnum ConfigFieldType = \"enum\"\n FieldStructured ConfigFieldType = \"structured\" // repositories, models, providers\n)\n\ntype ConfigField struct {\n Key string `json:\"key\"` // dotted path, matches UpdateConfig's key space\n Label string `json:\"label\"`\n Description string `json:\"description,omitempty\"`\n Type ConfigFieldType `json:\"type\"`\n Value any `json:\"value\"`\n Editable bool `json:\"editable\"`\n LockedReason string `json:\"locked_reason,omitempty\"`\n Overridden bool `json:\"overridden\"`\n Options []string `json:\"options,omitempty\"` // enum only\n RestartRequired bool `json:\"restart_required\"`\n}\n\ntype ConfigSection struct {\n ID string `json:\"id\"`\n Label string `json:\"label\"`\n Fields []ConfigField `json:\"fields\"`\n}\n```\n\n`handleConfig` builds `[]ConfigSection` from the existing per-field\nvalues it already assembles, plus `overlay.DeniedKeys` for\n`LockedReason` and the existing `Overridden` list -- both already\ncomputed just re-attached per field instead of returned as\nside-channel maps the frontend cross-references by key string.\n`Locked`/`Overridden`/`Reload`/`Provenance` stay as top-level\n`ConfigView` fields; they describe runtime state (what happened on\nthe last reload, which keys the overlay refuses), not the field\ncatalogue, and duplicating that logic per-field would be the same drift\nrisk this change exists to remove.\n\n`FieldStructured` fields (repositories, models, providers) carry\n`Value` as structured JSON and are rendered by dedicated\neditors, not the generic renderer -- see \"What this does not do\".\n\n## Sections\n\nMatches the cards the settings page already has: `identity`,\n`repositories`, `models`, `providers`, `budgets`, `storage`,\n`containers`, `web`. No new sections; this is metadata on existing\nrows, not new configuration surface.\n\n## Frontend\n\n`config-row.js`'s `row(label, value, opts)` becomes the renderer's\nprivate implementation detail, called generically:\n\n```js\nfor (const section of schema.sections) {\n const rows = section.fields\n .filter((f) =\u003e f.type !== \"structured\")\n .map((f) =\u003e\n row(f.label, f.value, {\n key: f.key,\n type: f.type,\n options: f.options,\n locked: f.locked_reason,\n overridden: f.overridden,\n restartRequired: f.restart_required,\n }),\n );\n // structured fLine truncated
},
{
"url": "/dev/prds/contract-conformance-audit/",
"title": "Contract conformance audit — decision",
"section": "PRDs",
"body": "# Contract conformance audit — decision\n\n**Status:** Finalised\n**Scope:** an **advisory** report, deliberately **not** part of `task check`.\n**Date:** 2026-09-15\n**Authority:** sibling to `archie-core-06ag` (standing reachability audit) and\n`docs/architecture/dependencies-and-contracts.md`. Replaces neither.\n**Open:** withdraw it, or rebuild it structurally. See \"Open decision\" — not to\nbe resolved by hardening the regexes.\n\n## Question\n\nDoes every declared contract surface have a consumer, or an explicit declaration\nthat it has none?\n\nReachability (`tools/reachaudit`) asks the complementary question — *is this code\nin a shipped binary?* — and cannot see a capability that is **reachable and\nunconsumed**. `ratelimit` was in the binary closure and called by nothing\n(`archie-core-6wxb`); reachability would not have found that.\n\n## Decision\n\nYes, as an advisory survey. `tools/contractaudit` classifies each subject of each\nsurface:\n\n| Classification | Meaning | Fails `--strict`? |\n| --- | --- | --- |\n| `CONSUMED` | a call site exercises it | no |\n| `DECLARED-UNCONSUMED` | allowlisted in `docs/contract-declarations.json`, with a reason and a tracker | no |\n| `UNDECLARED-UNCONSUMED` | nobody reaches it, nobody declared it | **yes** |\n| `STALE-DECLARATION` | an allowlist entry that is no longer true | **yes** |\n\nThere are **four** classes and **two** of them fail. The allowlist must match\nreality exactly, and it fails in both directions: a missing entry is a finding,\nand an entry that outlived its subject is a finding, because a stale allowlist is\nhow a check quietly stops checking anything.\n\n**Not gated.** `task contract` is advisory and `task check` does not run it,\nmatching `tools/reachaudit`. The surfaces are discovered by scanning source text,\nso a rename or a reformat elsewhere in the tree can change the output with nothing\nactually wrong. It has already produced 16 false \"unconsumed\" readings once, when\nthe dashboard's request helper was renamed. A check that can fail for reasons\nunrelated to what it measures must not be able to break a build.\n\n## Surfaces actually built — three, not five\n\n| Surface | Subjects | \"Consumed\" means |\n| --- | --- | --- |\n| `proto/state/v1` `StateStoreService` | **45 RPCs** | an adapter body calls `client.\u003cRpc\u003e(...)` |\n| `proto/gateway/v1` `ChatService` | **21 RPCs** | same |\n| `internal/webui` dashboard routes | **49 routes** | a path literal appears as a call argument under `ui/src` |\n\nConsumption for the gRPC surfaces is established by **scanning adapter source\ntext** for calls through the generated client, not by reflection. See the errata\nbelow: the first revision of this document claimed reflection, and the first\nimplementation did use it, but the shipped mechanism is a regex and the document\nwas not updated to match.\n\n## What this audit has actually found\n\n**Nothing actionable.** On the current tree it reports 0 undeclared and 0 stale.\nIts only allowlisted entries are two RPCs superseded by their streaming variants\n(`ListCaptures`, `ListUndispatchedCaptures`), which were already known from the\nsource comment on `staterpc.Client.ListCaptures`.\n\nEvery real defect found in the session that produced this tool was found by other\nmeans:\n\n- the three 415 refusals, by reading `authorizeTaskMutation` and reproducing the\n browser's exact headers against the real handler;\n- the dashboard client's duplicated request plumbing, by reading the module.\n\nRecorded plainly because a survey that has never found anything is evidence about\nthe survey, not about the tree.\n\n## Errata — claims in the first revision of this document that were false\n\n- **\"RPC coverage is derived by reflection over the exported client type.\"**\n It is not. `proto.go` regex-scans adapter bodies for `client.Method(` calls.\n The reflection version was replaced and the document was not updated. The unused\n `google.golang.org/grpc` family in `tools/go.mod` was residue from that\n iteration; `go mod tidy` removed it on 2026-09-15.\n- **Surface sizes of \"43 / 12 / 52\".** The real counts are 45 / 21 / 49.\n- **\"Three classifications, and the third is the only finding.\"** Four classes,\n two of which fail.\n- **\"Raw `fetch()` calls caused 401s to render as `refused`/`broken`.\"** Wrong.\n Every raw call site passed `res.status` to `ApiError`, so `classifyActionError`\n already mapped 401 to `session-expired`; the chat stream never classified at\n all. The real defect in that area was different (below).\n- **A five-surface \"Shape\" naming `surface.go`, `generated.go`,\n `declarations.go`, and `testdata/`.** None were written. The real files are\n `main.go`, `audit.go`, `proto.go`, `webui.go`.\n\n## The two gaps this was aimed at\n\n**1. `docsgen check` is documented and does not exist.** Closed by issue #855.\n(issue #855 / `archie-core-5gzx`). `tools/docsgen` now has a `check` subcommanLine truncated
"body": "# Contract conformance audit — decision\n\n**Status:** Finalised\n**Scope:** an **advisory** report, deliberately **not** part of `task check`.\n**Date:** 2026-09-15\n**Authority:** sibling to `archie-core-06ag` (standing reachability audit) and\n`docs/architecture/dependencies-and-contracts.md`. Replaces neither.\n**Open:** withdraw it, or rebuild it structurally. See \"Open decision\" — not to\nbe resolved by hardening the regexes.\n\n## Question\n\nDoes every declared contract surface have a consumer, or an explicit declaration\nthat it has none?\n\nReachability (`tools/reachaudit`) asks the complementary question — _is this code\nin a shipped binary?_ — and cannot see a capability that is **reachable and\nunconsumed**. `ratelimit` was in the binary closure and called by nothing\n(`archie-core-6wxb`); reachability would not have found that.\n\n## Decision\n\nYes, as an advisory survey. `tools/contractaudit` classifies each subject of each\nsurface:\n\n| Classification | Meaning | Fails `--strict`? |\n| ----------------------- | ----------------------------------------------------------------------------- | ----------------- |\n| `CONSUMED` | a call site exercises it | no |\n| `DECLARED-UNCONSUMED` | allowlisted in `docs/contract-declarations.json`, with a reason and a tracker | no |\n| `UNDECLARED-UNCONSUMED` | nobody reaches it, nobody declared it | **yes** |\n| `STALE-DECLARATION` | an allowlist entry that is no longer true | **yes** |\n\nThere are **four** classes and **two** of them fail. The allowlist must match\nreality exactly, and it fails in both directions: a missing entry is a finding,\nand an entry that outlived its subject is a finding, because a stale allowlist is\nhow a check quietly stops checking anything.\n\n**Not gated.** `task contract` is advisory and `task check` does not run it,\nmatching `tools/reachaudit`. The surfaces are discovered by scanning source text,\nso a rename or a reformat elsewhere in the tree can change the output with nothing\nactually wrong. It has already produced 16 false \"unconsumed\" readings once, when\nthe dashboard's request helper was renamed. A check that can fail for reasons\nunrelated to what it measures must not be able to break a build.\n\n## Surfaces actually built — three, not five\n\n| Surface | Subjects | \"Consumed\" means |\n| ------------------------------------ | ------------- | -------------------------------------------------------- |\n| `proto/state/v1` `StateStoreService` | **45 RPCs** | an adapter body calls `client.\u003cRpc\u003e(...)` |\n| `proto/gateway/v1` `ChatService` | **21 RPCs** | same |\n| `internal/webui` dashboard routes | **49 routes** | a path literal appears as a call argument under `ui/src` |\n\nConsumption for the gRPC surfaces is established by **scanning adapter source\ntext** for calls through the generated client, not by reflection. See the errata\nbelow: the first revision of this document claimed reflection, and the first\nimplementation did use it, but the shipped mechanism is a regex and the document\nwas not updated to match.\n\n## What this audit has actually found\n\n**Nothing actionable.** On the current tree it reports 0 undeclared and 0 stale.\nIts only allowlisted entries are two RPCs superseded by their streaming variants\n(`ListCaptures`, `ListUndispatchedCaptures`), which were already known from the\nsource comment on `staterpc.Client.ListCaptures`.\n\nEvery real defect found in the session that produced this tool was found by other\nmeans:\n\n- the three 415 refusals, by reading `authorizeTaskMutation` and reproducing the\n browser's exact headers against the real handler;\n- the dashboard client's duplicated request plumbing, by reading the module.\n\nRecorded plainly because a survey that has never found anything is evidence about\nthe survey, not about the tree.\n\n## Errata — claims in the first revision of this document that were false\n\n- **\"RPC coverage is derived by reflection over the exported client type.\"**\n It is not. `proto.go` regex-scans adapter bodies for `client.Method(` calls.\n The reflection version was replaced and the document was not updated. The unused\n `google.golang.org/grpc` family in `tools/go.mod` was residue from that\n iteration; `go mod tidy` removed it on 2026-09-15.\n- **Surface sizes of \"43 / 12 / 52\".** The real counts are 45 / 21 / 49.\n- **\"Three classifications, and the third is the only finding.\"** Four classes,\n two of which fail.\n- **\"Raw `fetch()` calls caused 401s to render as `refused`/`brokLine truncated
},
{
"url": "/dev/prds/control-plane-apply-status/",
@@ -178,265 +238,301 @@
"url": "/dev/prds/curator-sampler-wave1/",
"title": "Curator sampler wave 1: `Sampler` interface + four cheap strategies -- decision",
"section": "PRDs",
"body": "# Curator sampler wave 1: `Sampler` interface + four cheap strategies -- decision\n\n**Status:** Approved\n**Date:** 2026-09-05\n**Beads issue:** bead `archie-core-1786637500776-416-600a66e5` / GitHub #437\ncovers the embedding-backed follow-on strategy only. This PRD covers the\nprerequisite interface and the cheap strategies.\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n**Depends on:** nothing shipped (this is itself a prerequisite)\n**Blocks:** the embedding-backed surprisal strategy (GitHub #437), which\nimplements this same interface once the embeddings capability\n(`internal/domain/embedding`, this change) lands\n\n## Problem\n\nA future curator that reviews a large body of content (memories, sessions,\nskills) cannot always afford to run its agentic budget over every candidate\nevery pass. It needs to pick a bounded subset first. GitHub #437's acceptance\ncriteria requires that subset-picking to sit \"behind a `Sampler` interface\nthat wave 1 of the curator epic ships (cheap strategies: recency, random,\nall, staleness proxy)\" and that the embedding-backed strategy implement \"the\nsame interface\" later. No such interface, and none of the four cheap\nstrategies, exist anywhere in the codebase (bead 434e5bb9's closure\nwithout a linked PR was the tracker being wrong, not the code existing) --\nthis PRD is the one-page settled design for it, per this repo's Scope\nDiscipline rule.\n\n## Decision\n\nA `Sampler` is a pure, call-scoped selection function: given a fixed slice of\ncandidates and a request, it returns a subset. No lifecycle, no host access,\nno I/O for the four wave-1 strategies -- they are computation only, so they\nlive directly in `internal/domain/sampling` (a domain package, not\n`internal/infrastructure/*`) alongside the contract, the same way\n`curator/activity.go`'s pure ring buffer sits next to `curator/contract.go`\nrather than in an infrastructure package.\n\n```go\n// Package sampling is the curator sampler family: given a bounded set of\n// candidates, pick a subset to spend a curator pass's agentic budget on.\n// See docs/prds/curator-sampler-wave1.md.\npackage sampling\n\n// Candidate is one item eligible for sampling. It is deliberately narrow:\n// an opaque identifier, the timestamp the timestamp-based strategies score\n// against, and an open Metadata bag for whatever a future strategy needs\n// (e.g. the embedding-backed surprisal strategy's vector) without widening\n// this struct for every strategy that comes after wave 1.\ntype Candidate struct {\n ID string\n At time.Time\n Metadata map[string]any\n}\n\n// Request carries the knobs every strategy shares: a selection cap and a\n// deterministic seed. Both are optional -- Cap 0 means unlimited (the \"all\"\n// strategy relies on this), Seed 0 is a valid seed, not \"unset\".\ntype Request struct {\n Cap int\n Seed int64\n}\n\n// Sampler selects a subset of candidates to spend a curator pass's agentic\n// budget on. Every implementation -- the four here and the future\n// embedding-backed surprisal strategy (GitHub #437) -- must be\n// deterministic given the same candidates and Request: same inputs, same\n// output, every time. That is what makes a pass reproducible and testable,\n// and is GitHub #437's stated acceptance criterion for the strategy it\n// adds behind this same interface.\ntype Sampler interface {\n // Name identifies the strategy for logging/attribution (e.g.\n // \"recency\", \"random\", \"all\", \"staleness\", later \"surprisal\").\n Name() string\n // Sample selects from candidates per req. Implementations must not\n // mutate candidates or rely on anything but candidates and req --\n // determinism depends on that.\n Sample(ctx context.Context, candidates []Candidate, req Request) ([]Candidate, error)\n}\n```\n\n### The four wave-1 strategies\n\nAll four are `internal/domain/sampling` types constructed with `NewX(...)`,\neach implementing `Sampler`:\n\n- **`recency`** (`NewRecency()`): sorts candidates newest-`At`-first (stable\n sort, ties keep input order so output is deterministic even when two\n candidates share a timestamp), then truncates to `req.Cap` (0 = all).\n- **`staleness`** (`NewStaleness()`): the mirror of recency -- sorts oldest-\n `At`-first, then truncates to `req.Cap`. This is explicitly a *proxy*:\n \"hasn't been touched in the longest time\" using whatever timestamp the\n caller populated `Candidate.At` with (created, updated, or\n last-reviewed -- the caller's choice, not this package's), never the\n embedding-based surprisal calculation GitHub #437 owns.\n- **`all`** (`NewAll()`): no filtering. Returns candidates in input order,\n truncated to `req.Cap` (0 = every candidate). Input order is the only\n order this strategy has an opinion about, and preserving it is what makes\n it deterministic.\n- **`random`** (`NewRandom()`): a uniform-random subset, sized to\n `req.Cap` (0 = every canLine truncated
"body": "# Curator sampler wave 1: `Sampler` interface + four cheap strategies -- decision\n\n**Status:** Approved\n**Date:** 2026-09-05\n**Beads issue:** bead `archie-core-1786637500776-416-600a66e5` / GitHub #437\ncovers the embedding-backed follow-on strategy only. This PRD covers the\nprerequisite interface and the cheap strategies.\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n**Depends on:** nothing shipped (this is itself a prerequisite)\n**Blocks:** the embedding-backed surprisal strategy (GitHub #437), which\nimplements this same interface once the embeddings capability\n(`internal/domain/embedding`, this change) lands\n\n## Problem\n\nA future curator that reviews a large body of content (memories, sessions,\nskills) cannot always afford to run its agentic budget over every candidate\nevery pass. It needs to pick a bounded subset first. GitHub #437's acceptance\ncriteria requires that subset-picking to sit \"behind a `Sampler` interface\nthat wave 1 of the curator epic ships (cheap strategies: recency, random,\nall, staleness proxy)\" and that the embedding-backed strategy implement \"the\nsame interface\" later. No such interface, and none of the four cheap\nstrategies, exist anywhere in the codebase (bead 434e5bb9's closure\nwithout a linked PR was the tracker being wrong, not the code existing) --\nthis PRD is the one-page settled design for it, per this repo's Scope\nDiscipline rule.\n\n## Decision\n\nA `Sampler` is a pure, call-scoped selection function: given a fixed slice of\ncandidates and a request, it returns a subset. No lifecycle, no host access,\nno I/O for the four wave-1 strategies -- they are computation only, so they\nlive directly in `internal/domain/sampling` (a domain package, not\n`internal/infrastructure/*`) alongside the contract, the same way\n`curator/activity.go`'s pure ring buffer sits next to `curator/contract.go`\nrather than in an infrastructure package.\n\n```go\n// Package sampling is the curator sampler family: given a bounded set of\n// candidates, pick a subset to spend a curator pass's agentic budget on.\n// See docs/prds/curator-sampler-wave1.md.\npackage sampling\n\n// Candidate is one item eligible for sampling. It is deliberately narrow:\n// an opaque identifier, the timestamp the timestamp-based strategies score\n// against, and an open Metadata bag for whatever a future strategy needs\n// (e.g. the embedding-backed surprisal strategy's vector) without widening\n// this struct for every strategy that comes after wave 1.\ntype Candidate struct {\n ID string\n At time.Time\n Metadata map[string]any\n}\n\n// Request carries the knobs every strategy shares: a selection cap and a\n// deterministic seed. Both are optional -- Cap 0 means unlimited (the \"all\"\n// strategy relies on this), Seed 0 is a valid seed, not \"unset\".\ntype Request struct {\n Cap int\n Seed int64\n}\n\n// Sampler selects a subset of candidates to spend a curator pass's agentic\n// budget on. Every implementation -- the four here and the future\n// embedding-backed surprisal strategy (GitHub #437) -- must be\n// deterministic given the same candidates and Request: same inputs, same\n// output, every time. That is what makes a pass reproducible and testable,\n// and is GitHub #437's stated acceptance criterion for the strategy it\n// adds behind this same interface.\ntype Sampler interface {\n // Name identifies the strategy for logging/attribution (e.g.\n // \"recency\", \"random\", \"all\", \"staleness\", later \"surprisal\").\n Name() string\n // Sample selects from candidates per req. Implementations must not\n // mutate candidates or rely on anything but candidates and req --\n // determinism depends on that.\n Sample(ctx context.Context, candidates []Candidate, req Request) ([]Candidate, error)\n}\n```\n\n### The four wave-1 strategies\n\nAll four are `internal/domain/sampling` types constructed with `NewX(...)`,\neach implementing `Sampler`:\n\n- **`recency`** (`NewRecency()`): sorts candidates newest-`At`-first (stable\n sort, ties keep input order so output is deterministic even when two\n candidates share a timestamp), then truncates to `req.Cap` (0 = all).\n- **`staleness`** (`NewStaleness()`): the mirror of recency -- sorts oldest-\n `At`-first, then truncates to `req.Cap`. This is explicitly a _proxy_:\n \"hasn't been touched in the longest time\" using whatever timestamp the\n caller populated `Candidate.At` with (created, updated, or\n last-reviewed -- the caller's choice, not this package's), never the\n embedding-based surprisal calculation GitHub #437 owns.\n- **`all`** (`NewAll()`): no filtering. Returns candidates in input order,\n truncated to `req.Cap` (0 = every candidate). Input order is the only\n order this strategy has an opinion about, and preserving it is what makes\n it deterministic.\n- **`random`** (`NewRandom()`): a uniform-random subset, sized to\n `req.Cap` (0 = every canLine truncated
},
{
"url": "/dev/prds/dashboard-aware-chat-navigation/",
"title": "Dashboard-aware chat: Archie sees the page, and points the operator there",
"section": "PRDs",
"body": "# Dashboard-aware chat: Archie sees the page, and points the operator there\n\n**Status:** Approved\n**Date:** 2026-08-26\n**Compound:** the \"chat available on any page\" surface work (global chat presence)\n\n## Decision\n\nMake the web chat **dashboard-aware**: the agent is told which dashboard page\nthe operator has *open*, knows what each page is for, and can **point**\nthe operator to the relevant page with a **clickable destination chip** the UI\nrenders and follows - Option B (context + navigate), not just \"tell me in text.\"\n\nThree seams, each an existing extension point, one new tool and one message field:\n\n1. **Current page, into the prompt.** The browser sends its route with every\n chat message; the gateway threads it into the system prompt's runtime-metadata\n env block. Archie always knows where the operator is looking.\n2. **Page index.** A page_index tool lists the dashboard pages and what each one\n shows, so Archie knows what to point at - the agent \"has the map\".\n3. **Navigate.** A dashboard_navigate tool returns a structured path/label; the web\n UI renders it as a clickable chip that routes the operator there. This is the\n \"plenty of resources\" the requirement named.\n\nWe deliberately keep the agent's answer honest: the chip is *evidence* it can\nvalidly produce because dashboard_navigate is a real tool whose result is\nrendered, not a markdown link the model invents.\n\n## Why now\n\nThis is the natural next step of the \"chat on any page\" work, and the original\nrequest named it explicitly: *\"archie should be able to see what page you're on\ntoo. and point out where to go. so it needs plenty of resources.\"* The chat\nis a full-page route with no knowledge of the rest of the dashboard; the agent\ncannot see which page the operator is on and cannot reliably direct them anywhere.\nThe critique of the chat UI already identified \"chat is not available on any page\"\nas the largest structural gap (P1). This design is the capability that makes that\ngap worth closing.\n\n## Shape of the API\n\n### Message field (gateway.go)\n\nAdd Page to Message:\n\n```go\n// Page is the dashboard route the operator is on when they sent this message\n// (e.g. \"/tasks\", \"/logs\"). Empty for non-web channels, which have no page\n// context. It is per-message, not per-session: the operator navigates freely\n// while a conversation stays open.\nPage string\n```\n\n### Web request (api_chat.go)\n\nchatMessageRequest gains Page, decoded into Message.Page in decodeChatMessage.\n\n### System prompt config (prompt.go)\n\nSystemPromptConfig gains Page; BuildSystemPrompt passes it through to the template.\nThe env block of archie.md.tpl renders the current page when set.\n\n### Page index (dashboard_tools.go, new)\n\nA package-level registry mapping route to {Label, Description}. page_index returns\nthe list so the model knows what each page shows:\n\n```go\ntype DashboardPage struct {\n\tPath string // \"/tasks\"\n\tLabel string // \"Tasks\"\n\tDescription string // \"Issues Archie picked up, and where they stand.\"\n}\n```\n\n### Navigation tool (dashboard_tools.go)\n\ndashboard_navigate validates its path against the registry and returns the resolved\npath/label. Unknown path means a clear error, not a guess. The model must call the\ntool (not invent a link) to produce a chip, so the chip is honest.\n\n### Tool wiring (turn.go)\n\nextraTools already merges TaskTools + SessionTools. Add the dashboard tools alongside\nthem, gated on the channel being the web UI. The tool list is built from the same\nregistry the prompt's page line comes from, so the agent never points at a page it\nwas not told about.\n\n### Web UI (chat-render.js, chat-tools.js)\n\nA dashboard_navigate tool call renders as a **clickable chip**: an anchor with\nhref=\"/tasks\" and the label. The chip is a\nreal link that works from any page once the chat is a global presence. The chip is\nstyled as an action, not a code line, so it visibly invites a click.\n\n### Route transfer (chat.js)\n\nEach sendMessage includes the current location.hash route as page in the stream\nrequest body, so the backend gets the operator's live position.\n\n## What we deliberately do NOT do\n\n- **No navigation from a markdown link.** The model must use dashboard_navigate; a\n bare \"click here\" is not rendered as a trusted route.\n- **No full-page route hijack from the chat.** The chip sets location.hash.\n- **No page index for non-web channels.** Telegram/discord have no dashboard.\n- **No automatic history annotation.** Page is per-message from the browser.\n- **No change to the dangerous-action approval flow.** Separately tracked.\n\n## Acceptance criteria\n\n1. Chat messages from any page carry the current page to the agent's prompt.\n2. page_index returns every dashboard page with a plain-language description.\n3. dashboard_navigate renders a clickable chip that routes to the target page.\n4. dashboard_navLine truncated
"body": "# Dashboard-aware chat: Archie sees the page, and points the operator there\n\n**Status:** Approved\n**Date:** 2026-08-26\n**Compound:** the \"chat available on any page\" surface work (global chat presence)\n\n## Decision\n\nMake the web chat **dashboard-aware**: the agent is told which dashboard page\nthe operator has _open_, knows what each page is for, and can **point**\nthe operator to the relevant page with a **clickable destination chip** the UI\nrenders and follows - Option B (context + navigate), not just \"tell me in text.\"\n\nThree seams, each an existing extension point, one new tool and one message field:\n\n1. **Current page, into the prompt.** The browser sends its route with every\n chat message; the gateway threads it into the system prompt's runtime-metadata\n env block. Archie always knows where the operator is looking.\n2. **Page index.** A page_index tool lists the dashboard pages and what each one\n shows, so Archie knows what to point at - the agent \"has the map\".\n3. **Navigate.** A dashboard_navigate tool returns a structured path/label; the web\n UI renders it as a clickable chip that routes the operator there. This is the\n \"plenty of resources\" the requirement named.\n\nWe deliberately keep the agent's answer honest: the chip is _evidence_ it can\nvalidly produce because dashboard_navigate is a real tool whose result is\nrendered, not a markdown link the model invents.\n\n## Why now\n\nThis is the natural next step of the \"chat on any page\" work, and the original\nrequest named it explicitly: _\"archie should be able to see what page you're on\ntoo. and point out where to go. so it needs plenty of resources.\"_ The chat\nis a full-page route with no knowledge of the rest of the dashboard; the agent\ncannot see which page the operator is on and cannot reliably direct them anywhere.\nThe critique of the chat UI already identified \"chat is not available on any page\"\nas the largest structural gap (P1). This design is the capability that makes that\ngap worth closing.\n\n## Shape of the API\n\n### Message field (gateway.go)\n\nAdd Page to Message:\n\n```go\n// Page is the dashboard route the operator is on when they sent this message\n// (e.g. \"/tasks\", \"/logs\"). Empty for non-web channels, which have no page\n// context. It is per-message, not per-session: the operator navigates freely\n// while a conversation stays open.\nPage string\n```\n\n### Web request (api_chat.go)\n\nchatMessageRequest gains Page, decoded into Message.Page in decodeChatMessage.\n\n### System prompt config (prompt.go)\n\nSystemPromptConfig gains Page; BuildSystemPrompt passes it through to the template.\nThe env block of archie.md.tpl renders the current page when set.\n\n### Page index (dashboard_tools.go, new)\n\nA package-level registry mapping route to {Label, Description}. page_index returns\nthe list so the model knows what each page shows:\n\n```go\ntype DashboardPage struct {\n\tPath string // \"/tasks\"\n\tLabel string // \"Tasks\"\n\tDescription string // \"Issues Archie picked up, and where they stand.\"\n}\n```\n\n### Navigation tool (dashboard_tools.go)\n\ndashboard_navigate validates its path against the registry and returns the resolved\npath/label. Unknown path means a clear error, not a guess. The model must call the\ntool (not invent a link) to produce a chip, so the chip is honest.\n\n### Tool wiring (turn.go)\n\nextraTools already merges TaskTools + SessionTools. Add the dashboard tools alongside\nthem, gated on the channel being the web UI. The tool list is built from the same\nregistry the prompt's page line comes from, so the agent never points at a page it\nwas not told about.\n\n### Web UI (chat-render.js, chat-tools.js)\n\nA dashboard_navigate tool call renders as a **clickable chip**: an anchor with\nhref=\"/tasks\" and the label. The chip is a\nreal link that works from any page once the chat is a global presence. The chip is\nstyled as an action, not a code line, so it visibly invites a click.\n\n### Route transfer (chat.js)\n\nEach sendMessage includes the current location.hash route as page in the stream\nrequest body, so the backend gets the operator's live position.\n\n## What we deliberately do NOT do\n\n- **No navigation from a markdown link.** The model must use dashboard_navigate; a\n bare \"click here\" is not rendered as a trusted route.\n- **No full-page route hijack from the chat.** The chip sets location.hash.\n- **No page index for non-web channels.** Telegram/discord have no dashboard.\n- **No automatic history annotation.** Page is per-message from the browser.\n- **No change to the dangerous-action approval flow.** Separately tracked.\n\n## Acceptance criteria\n\n1. Chat messages from any page carry the current page to the agent's prompt.\n2. page_index returns every dashboard page with a plain-language description.\n3. dashboard_navigate renders a clickable chip that routes to the target page.\n4. dashboard_navLine truncated
},
{
"url": "/dev/prds/dashboard-live-state/",
"title": "Dashboard live state",
"section": "PRDs",
"body": "# Dashboard live state\n\n**Status:** Approved\n\n## Decision\n\nThe dashboard must not require passive **Refresh** buttons. One app-wide Pinia\nstore owns the existing `/events` EventSource and translates backend events\ninto resource revision counters. Pages load their authoritative HTTP projection\non entry and re-read it when the relevant revision changes. Event payloads are\ninvalidation signals, not substitute read models.\n\nSSE remains the transport. Dashboard updates are server-to-client only, and the\nexisting stream already provides replay, reconnect, and persisted ordering; a\nWebSocket would add a second transport without adding a capability.\n\nThe first slice covers resources for which the backend already emits a truthful\nsignal:\n\n- task events invalidate the dashboard, task board, workflow statistics, and\n the matching task-run page;\n- capture events invalidate the capture list;\n- curator events invalidate curator status, and curator actions also invalidate\n the skill catalogue;\n- update reports invalidate System status;\n- opening a page always loads its resource, and reopening the SSE stream\n invalidates mounted projections after a connection loss.\n\nLogs retain their dedicated SSE tail. Local mutations continue to re-read their\nown resource after success. Configuration, channels, and catalogues that have no\nbackend change event load on route entry; future write contracts must emit an\nowner-specific event rather than introduce polling or restore a button.\n\n## Boundaries\n\nThe Pinia store owns browser connection state and invalidation only. It does not\nbecome an alternate backend cache or copy domain state into a generic global\nobject. Existing feature modules continue to own their DTOs and API reads.\n\nOperational commands are not refresh controls. Channel **Reload** remains an\nexplicit adapter lifecycle action. Authentication recovery is also not a data\nrefresh: a 401 moves the application into shared authentication state; reloading\nthe same URL cannot restore Archie's missing or rotated token and must not be\noffered as a fix.\n\n## Verification\n\n- No passive page action renders the label **Refresh** or **Retry** for a read.\n- Only one shared `/events` EventSource is opened by the application.\n- Resource classification tests distinguish task, capture, curator, skill, and\n update invalidations.\n- UI tests, type checking, generated asset freshness, and `task check` pass.\n"
},
{
"url": "/dev/prds/dashboard-navigation-groups/",
"title": "Dashboard navigation groups + Configuration split -- decision",
"section": "PRDs",
"body": "# Dashboard navigation groups + Configuration split -- decision\n\n**Status:** Approved\n**Date:** 2026-09-20\n**Beads issue:** `archie-core-ocfm`\n**Related:** `archie-core-gl96` (Logs absent from the nav -- subsumed here),\n`archie-core-ggqo` (Configuration's page width -- moot once it splits)\n\n## Problem\n\n`ui/src/main.jsx` declares eleven navigable routes in one flat bar. Three of\nthem (Skills, Curators, Channels) are capability-gated and hidden on the\nreference deployment, so the eight items normally visible are the best case,\nnot the worst: a composition that serves every section wraps the bar. Logs is\ndeclared but was never given a nav entry at all, reachable only from a\ndashboard link.\n\nThe labels compound it. \"Event inspector\", \"Field mappings\" and \"Playbook\nbindings\" are three long labels for three faces of one subject, and they sit\nbeside \"Dashboard\" and \"Tasks\" as though they were peers of equal weight.\n\nConfiguration is the other half. One route renders roughly ten sections --\nupdate status, work lifecycle, identity, budgets, storage, listen address,\nrepositories, models and providers, configuration sources, plus the operator\ncards rehomed in `archie-core-tf20` -- in a 4021px page with no in-page\nnavigation. There is no way to send someone to Repositories.\n\n## Decision\n\nFive top-level nav items. Dashboard is a link; the rest are dropdowns.\n\n| Group | Items |\n|---|---|\n| Dashboard | (link, `/`) |\n| Work | Tasks, Workflows |\n| Agent | Skills, Curators |\n| Events | Inspector, Mappings, Bindings |\n| System | Status, Logs, Appearance; **Settings:** Task settings, Models, Repositories, Channels, Advanced |\n\nItems are renamed because the group now carries the context: \"Event inspector\"\nbecomes \"Inspector\" under Events, and so on. A group renders only if at least\none of its children survives capability gating, and a group left with one\nchild still renders as a dropdown -- a bar whose shape changes per deployment\nis harder to learn than one with a predictable skeleton.\n\nThe System dropdown has two narratives. Status, Logs and Appearance describe\nthe running dashboard and sit first. A separator and visible **Settings** label\nintroduce Task settings, Models, Repositories, Channels and Advanced; those are\nconfiguration destinations, not awkward phrases such as \"System Models\" or\n\"System Advanced\".\n\n### Route map\n\nConfiguration dissolves into real routes. Anchors into one long page were\nrejected: they leave the 4021px page intact and a deep link lands the reader\nmid-scroll with no context above it.\n\n| Was | Becomes | Content |\n|---|---|---|\n| `/settings` | `/system/status` | Update status, configuration sources, daemon listen address |\n| -- | `/system/appearance` | Theme, and the density/motion preferences that follow it |\n| `/settings` | `/system/tasks` | Work lifecycle: statuses, operator actions, budgets |\n| `/settings` | `/system/models` | Model roles, providers |\n| `/settings` | `/system/repos` | Repositories and their per-repo gate overrides |\n| `/settings` | `/system/advanced` | Identity, storage and sandboxing, dangerous actions |\n| `/captures` | `/captures` | unchanged; label becomes \"Inspector\" |\n| `/mappings` | `/mappings` | unchanged; label becomes \"Mappings\" |\n| `/bindings` | `/bindings` | unchanged; label becomes \"Bindings\" |\n\n`/settings` is kept as a permanent redirect to `/system/status`. It is the URL\nin existing bookmarks, in `dashboardPages` (`internal/gateway/dashboard_tools.go`,\nwhich the chat agent navigates by), and in prior conversation history; breaking\nit to save one route entry is not a trade worth making.\n\n`dashboardPages` gains the new routes in the same change. That registry is\nguarded by `TestDashboardPagesRegistryCoversEveryRoute`, so a route added here\nand forgotten there fails the build -- which is how the deleted `/chat` entry\nwas caught.\n\n### Dropdown behaviour\n\nEach item carries a one-line description shown as a hover tooltip, using\nshadcn-vue's `Tooltip` rather than the `title` attribute, so it is keyboard\nreachable on focus and styled with the rest of the menu. Touch gets no tooltip,\nso no item may depend on one to be identifiable.\n\nThe menu is shadcn-vue's `DropdownMenu` (Reka UI underneath), which already\nsupplies the roving focus, ArrowDown/ArrowUp movement, Escape-closes-and-\nrestores-focus, and outside-pointerdown behaviour this would otherwise hand-\nroll. It opens on click, never on hover -- hover-opened menus on a control\nplane are a misclick away from a destructive page. The trigger keeps\n`aria-current` styling when any of its children is the active route, so the bar\nstill says where you are.\n\nThis section was written against the Preact dashboard; the decisions above\nsurvive the Vue migration unchanged, only the primitive supplying them\nchanged.\n\n### Scope boundaries\n\n- The daemon-backed configuration pages move sections between rLine truncated
"body": "# Dashboard live state\n\n**Status:** Approved\n\n## Decision\n\nThe dashboard must not require passive **Refresh** buttons. One app-wide Pinia\nstore owns the existing `/api/stream` EventSource and translates backend events\ninto resource revision counters. Pages load their authoritative HTTP projection\non entry and re-read it when the relevant revision changes. Event payloads are\ninvalidation signals, not substitute read models.\n\nSSE remains the transport. Dashboard updates are server-to-client only, and the\nexisting stream already provides replay, reconnect, and persisted ordering; a\nWebSocket would add a second transport without adding a capability.\n\nThe first slice covers resources for which the backend already emits a truthful\nsignal:\n\n- task events invalidate the dashboard, task board, workflow statistics, and\n the matching task-run page;\n- capture events invalidate the capture list;\n- curator events invalidate curator status, and curator actions also invalidate\n the skill catalogue;\n- update reports invalidate System status;\n- opening a page always loads its resource, and reopening the SSE stream\n invalidates mounted projections after a connection loss.\n\nLogs retain their dedicated SSE tail. Local mutations continue to re-read their\nown resource after success. Configuration, channels, and catalogues that have no\nbackend change event load on route entry; future write contracts must emit an\nowner-specific event rather than introduce polling or restore a button.\n\n## Boundaries\n\nThe Pinia store owns browser connection state and invalidation only. It does not\nbecome an alternate backend cache or copy domain state into a generic global\nobject. Existing feature modules continue to own their DTOs and API reads.\n\nOperational commands are not refresh controls. Channel **Reload** remains an\nexplicit adapter lifecycle action. Authentication recovery is also not a data\nrefresh: a 401 moves the application into shared authentication state; reloading\nthe same URL cannot restore Archie's missing or rotated token and must not be\noffered as a fix.\n\n## Verification\n\n- No passive page action renders the label **Refresh** or **Retry** for a read.\n- Only one shared `/api/stream` EventSource is opened by the application.\n- Resource classification tests distinguish task, capture, curator, skill, and\n update invalidations.\n- UI tests, type checking, generated asset freshness, and `task check` pass.\n"
},
{
"url": "/dev/prds/dashboard-port-brief/",
"title": "Dashboard port: what the agent delivers",
"section": "PRDs",
"body": "# Dashboard port: what the agent delivers\n\n**Status:** Approved\n**Date:** 2026-09-20\n**Beads:** `archie-core-tavn` (epic), `archie-core-ocfm` (navigation)\n**Reads with:** `docs/prds/vue-migration-checklist.md` (the item-by-item),\n`docs/prds/dashboard-navigation-groups.md` (the approved nav design)\n\nThis is the standard the port is held to. The checklist says what to port; this\nsays how, and what counts as done. It exists because the first attempt ported\nthe flat topbar verbatim and invented a palette, both of which had already been\ndecided elsewhere.\n\n## The deliverable\n\nThe Preact dashboard, rebuilt in Vue 3 with shadcn-vue, feature complete\nagainst the checklist, gate clean, with `ui/dist` rebuilt and committed in the\nsame commit as the source it was built from.\n\n## Non-negotiables\n\n- **Vue 3 + shadcn-vue (Reka UI, Tailwind v4, Lucide).** A component that\n exists in shadcn-vue is not hand-rolled. Add it with the CLI\n (`npx shadcn-vue@latest add \u003cname\u003e`), do not paste it in.\n- **History routing.** `createWebHistory`, `base: \"/\"`. No hash routing.\n `src/legacy-hash-redirect.ts` handles old `#/path` links and stays.\n- **No test port.** 43 Preact test files are deliberately dropped.\n `task test:ui` is a `vue-tsc` typecheck. Write a test when there is a real\n failure to pin, not to re-assert a port.\n- **Do not downgrade TypeScript.** The target is TS 7 native, not TS 5.\n- **`ui/dist` is law.** Never hand-edit it, never omit it, never revert it.\n- **`task check` is the gate.** Not an assembled substitute for it.\n- **Beads, not markdown TODOs**, for anything that outlives the change.\n- **Conventional commits**, scoped `feat(webui):`. Commit gate-clean work\n without asking. Do not push without being told.\n\n## Componentisation\n\nOne component, one job, one file. A surface is composed from named components,\nnot assembled inside a single large file. The topbar is the worked example and\nthe required shape:\n\n```\ncomponents/topbar/\n Topbar.vue composes the header, owns nothing else\n Brand.vue Logo + BrandName, links to /\n Logo.vue\n BrandName.vue\n Nav.vue reads the nav model, renders links and groups\n NavTrigger.vue the shared top-level control, link or dropdown trigger\n NavGroup.vue one dropdown\n NavItem.vue one item inside a dropdown, with its tooltip\n SearchBar.vue\n SupportLink.vue\n ThemeToggle.vue\n ProfileDropdown.vue\n```\n\nThe same rule applies to every page ported after it. If a file is doing the\nwork of four named things, it is four files. Data and behaviour that more than\none component needs lives in `src/lib/`, not passed down through a chain of\nprops.\n\n## Ordering\n\nBuild the navigation restructure during the port, not after it. Porting the\nflat eleven-item bar first and restructuring later means writing the topbar\ntwice and touching the Go route registry twice. The approved design is five\ntop-level items (Dashboard, Work, Agent, Events, System), items renamed because\ntheir group carries the context, per-item descriptions shown as hover tooltips,\nConfiguration split into `/system/*`, `/settings` kept as a redirect, and Logs\nfinally given a nav entry.\n\n## Design authority\n\n- The approved documents win. Where a document decides something, implement it\n rather than re-deciding it.\n- **Do not invent a visual direction.** Palette, typography and density are the\n maintainer's call. A palette change is its own request, never a side effect\n of a port.\n- Contrast is AA against every surface the foreground lands on, hover states\n included. The corrected values (`--fg-subtle`, the dark\n `--primary-foreground`) came from a measured failure and must survive.\n- `color-scheme` follows the theme so the UA paints controls, scrollbars and\n overscroll to match.\n\n## Code style\n\nComment the non-obvious why: an invariant, a trap, a measurement, a contract\nanother file depends on. Do not narrate what the code plainly does, do not\nexplain a choice that was never in question, and do not write migration phase\nhistory into a diff. That history belongs in the commit message.\n\n## Done, per surface\n\n1. Renders with real data against `task dev`, not just typechecks.\n2. Keyboard reachable, focus visible, and the nav announces where you are.\n3. Works at 1440x900 and at 720px wide, with nothing clipped and no horizontal\n page scroll.\n4. Empty, loading, failed and unconfigured (501) states all say something true.\n A section that cannot load says so; it does not render blank.\n5. `task check` passes, `ui/dist` rebuilt, committed together.\n"
"body": "# Dashboard port: what the agent delivers\n\n**Status:** Approved\n**Date:** 2026-09-20\n**Beads:** `archie-core-tavn` (epic), `archie-core-ocfm` (navigation)\n**Reads with:** `docs/prds/vue-migration-checklist.md` (the item-by-item)\n\nThis is the standard the port is held to. The checklist says what to port; this\nsays how, and what counts as done. It exists because the first attempt ported\nthe flat topbar verbatim and invented a palette, both of which had already been\ndecided elsewhere.\n\n## The deliverable\n\nThe Preact dashboard, rebuilt in Vue 3 with shadcn-vue, feature complete\nagainst the checklist, gate clean, with `ui/dist` rebuilt and committed in the\nsame commit as the source it was built from.\n\n## Non-negotiables\n\n- **Vue 3 + shadcn-vue (Reka UI, Tailwind v4, Lucide).** A component that\n exists in shadcn-vue is not hand-rolled. Add it with the CLI\n (`npx shadcn-vue@latest add \u003cname\u003e`), do not paste it in.\n- **History routing.** `createWebHistory`, `base: \"/\"`. No hash routing.\n `src/legacy-hash-redirect.ts` handles old `#/path` links and stays.\n- **No test port.** 43 Preact test files are deliberately dropped.\n `task test:ui` is a `vue-tsc` typecheck. Write a test when there is a real\n failure to pin, not to re-assert a port.\n- **Do not downgrade TypeScript.** The target is TS 7 native, not TS 5.\n- **`ui/dist` is law.** Never hand-edit it, never omit it, never revert it.\n- **`task check` is the gate.** Not an assembled substitute for it.\n- **Beads, not markdown TODOs**, for anything that outlives the change.\n- **Conventional commits**, scoped `feat(webui):`. Commit gate-clean work\n without asking. Do not push without being told.\n\n## Componentisation\n\nOne component, one job, one file. A surface is composed from named components,\nnot assembled inside a single large file. The topbar is the worked example and\nthe required shape:\n\n```\ncomponents/topbar/\n Topbar.vue composes the header, owns nothing else\n Brand.vue Logo + BrandName, links to /\n Logo.vue\n BrandName.vue\n Nav.vue reads the nav model, renders links and groups\n NavTrigger.vue the shared top-level control, link or dropdown trigger\n NavGroup.vue one dropdown\n NavItem.vue one item inside a dropdown, with its tooltip\n SearchBar.vue\n SupportLink.vue\n ThemeToggle.vue\n ProfileDropdown.vue\n```\n\nThe same rule applies to every page ported after it. If a file is doing the\nwork of four named things, it is four files. Data and behaviour that more than\none component needs lives in `src/lib/`, not passed down through a chain of\nprops.\n\n## Ordering\n\nBuild the navigation restructure during the port, not after it. Porting the\nflat eleven-item bar first and restructuring later means writing the topbar\ntwice and touching the Go route registry twice. The approved design is five\ntop-level items (Dashboard, Work, Agent, Events, System), items renamed because\ntheir group carries the context, per-item descriptions shown as hover tooltips,\nConfiguration split into `/system/*`, `/settings` kept as a redirect, and Logs\nfinally given a nav entry.\n\n## Design authority\n\n- The approved documents win. Where a document decides something, implement it\n rather than re-deciding it.\n- **Do not invent a visual direction.** Palette, typography and density are the\n maintainer's call. A palette change is its own request, never a side effect\n of a port.\n- Contrast is AA against every surface the foreground lands on, hover states\n included. The corrected values (`--fg-subtle`, the dark\n `--primary-foreground`) came from a measured failure and must survive.\n- `color-scheme` follows the theme so the UA paints controls, scrollbars and\n overscroll to match.\n\n## Code style\n\nComment the non-obvious why: an invariant, a trap, a measurement, a contract\nanother file depends on. Do not narrate what the code plainly does, do not\nexplain a choice that was never in question, and do not write migration phase\nhistory into a diff. That history belongs in the commit message.\n\n## Done, per surface\n\n1. Renders with real data against `task dev`, not just typechecks.\n2. Keyboard reachable, focus visible, and the nav announces where you are.\n3. Works at 1440x900 and at 720px wide, with nothing clipped and no horizontal\n page scroll.\n4. Empty, loading, failed and unconfigured (501) states all say something true.\n A section that cannot load says so; it does not render blank.\n5. `task check` passes, `ui/dist` rebuilt, committed together.\n"
},
{
"url": "/dev/prds/dashboard-vocabulary/",
"title": "One source for the dashboard's server vocabularies",
"section": "PRDs",
"body": "# One source for the dashboard's server vocabularies\n\n**Status:** Finalised\n\n## Problem\n\nThe dashboard kept its own copies of two vocabularies the daemon owns:\n\n- the changed-file statuses (`added`, `modified`, `deleted`, `renamed`,\n `typechange`), which are the `Change*` constants in\n `internal/domain/workflow/task`;\n- the schema stamp on a `config_captured` payload, `events.ConfigCapturedSchema`.\n\nNothing derived one side from the other, while `/api/task-meta` already served\nthe status and action vocabularies for exactly this reason.\n\n## Decision\n\n`GET /api/task-meta` also serves `change_statuses` (id and label) and\n`config_schema`. `buildTaskMeta` in `internal/webui/api_task_meta.go` takes the\nids from the `Change*` constants and the stamp from `events.ConfigCapturedSchema`.\n\nThe dashboard renders `ui/src/lib/task-meta-snapshot.ts` until the served\ncatalogue arrives, or when archied is unreachable. `loadTaskMeta` replaces only\nthe keys the payload carries, so a server without the new keys leaves the\nsnapshot in place. `changeStatusLabel` and `configSchema` in\n`ui/src/lib/task-meta.ts` are the only readers; an unknown status renders as\nits id.\n\n## Verification\n\n- `TestTaskMetaChangeStatusesAreDeliberate` fails when a `Change*` constant is\n added without a label.\n\nA rename on one side therefore fails a test on the other.\n\n## Rejected\n\nDeleting `/api/task-meta` and accepting hand-copied constants. The endpoint is\nlive, and deleting it would still leave the two copies this document removes.\n"
},
{
"url": "/dev/prds/deep-research-capability/",
"title": "Deep research capability — design",
"section": "PRDs",
"body": "# Deep research capability — design\n\n**Status:** Draft\n**Date:** 2026-09-14\n**Scope:** A deep-research capability in archie-core: an orchestrator that\nspawns 1..N subagents to explore and research in parallel, collates their\nfindings, and returns one cited report. Grounded in web search and web fetch.\n**Beads issue:** none yet (this document is the input to it)\n**Depends on:** nothing shipped for slice 1; slice 2 depends on slice 1.\n\n## §0 Implementation status\n\nEvery claim in this document is mapped to what exists in the tree.\n\n| Claim | Status | Where it stands |\n|---|---|---|\n| `web_fetch` tool (URL → readable text) | **Implemented** | `internal/tools/webfetch/{tool.go,webfetch.go}`; registered in `internal/app/archied/bootstrap.go` `registerStandaloneTools`, disabled-by-config returns `nil` |\n| **Web search** (query → result list) | **Aspirational — zero code** | No search provider, no search tool, no config block anywhere in the tree or in `ai-sdk` v0.1.32 |\n| `agent.Subagent` — nested agent in a fresh context window | **Implemented** (dependency) | `github.com/samcharles93/ai-sdk@v0.1.32/agent/subagent.go`. Synchronous, non-streaming, own model/system/toolset, `MaxSteps` defaults to 10, nesting depth capped at 5, returns final text only |\n| Subagent used in production | **Implemented, one consumer** | `internal/app/agentworker/review.go` — the adversarial reviewer. That is the only non-test use of `Subagent` in the repo |\n| A **delegate/subagent tool** on the chat surface | **Aspirational — zero code** | No `subagent`/`delegate` tool name is registered anywhere |\n| **Fan-out orchestration** (N missions, one collator) | **Aspirational — zero code** | `agentloop`'s package doc states it runs *one* mission: \"orchestration across missions lives with the caller\". No caller does this yet |\n| Parallel-safe tool execution | **Aspirational — zero code** | The unreachable `internal/tools/dispatch.go` dispatch/gating engine (`ExecutionClass`, `DispatchSequential`/`DispatchConcurrent`/`ClassifyEntry`) was deleted as dead code (tools-core-1); live concurrency is ai-sdk's `GenerateOptions.MaxParallelToolCalls`, which archie-core never sets |\n| Per-result caps + spill-to-disk | **Implemented** | `internal/agentexec/toolset.go` `ToolLimits{MaxResultChars,SpillDir}`, applied in `toolExecute` via `tools.CapPayload` (`limit.go`); no **aggregate** turn cap by design (`toolset.go`). `config.ToolPolicy.SpillDir`; default cap 50k chars, spill dir deliberately not defaulted |\n| Tool guardrails (repeat-failure / no-progress) | **Implemented, not on the call path** | `internal/tools/guardrail.go` engine exists. Its only non-test caller is `dispatchOne` — which is itself unreachable — so **the chat path never consults it**, and the agent path only records per *stage* (`domain/workflow/agent.go`) |\n| Structured capture tools (model reports into a typed store, not prose) | **Implemented** | `internal/app/agentworker/review.go` `record_finding` / `record_checked` — `core.NewTypedTool` appending to a caller-owned slice. This is the pattern a research source ledger should reuse |\n| Curator engine (interval, declared tool set, lifecycle) | **Implemented, tools broken** | `internal/domain/curator`; a curator declaring tools is **refused** at registration (`registry.go`, no `ToolBuilder` implementation) and `curatorLLMRunner` (`internal/app/archied/main.go`) drops `ChatRequest.Tools`. Budgets are time+concurrency only (`runtime.go`) — **no token budget** |\n| Cron / scheduling + delivery router | **Implemented, wired into the daemon** | `internal/domain/scheduling` (ticker engine), `internal/infrastructure/cronstore` (schema v2, `Kind` discriminator), and `internal/infrastructure/crondelivery`; `internal/app/archied/scheduling.go` composes them and `main.go` starts the engine. |\n| Workflow engines (multi-stage, resumable) | **Implemented, worktree-bound** | `internal/domain/workflow` — every non-triage workflow opens with `StagePrepareWorktree()` and mounts `tc.Dir` into a container; the task persists after every stage (`workflow.go`). `triage.go` documents there is \"no cheaper directory-less classification primitive\" |\n| Long-running chat-initiated work with progress | **Partial** | Chat turns run **once, synchronously**, inline in the channel's turn runner (`internal/gateway/turn.go`). Chat can spawn a *workflow task* (`task_spawn`) which is asynchronous — but that path is worktree/PR-shaped |\n| **Operator-push delivery of an async result** | **Aspirational — zero code** | Nothing pushes a finished result to a chat. No channel subscribes to the event bus (Telegram only *publishes* `KindTurnCompleted`); `crondelivery.Courier` is the intended seam but has **no implementation and no caller**; `send_file` works only inside the live turn. The one out-of-band notification in the tree is feasibility's n8n webhook (`feasibility.go`) |\n| Citation storage / sourLine truncated
"body": "# Deep research capability — design\n\n**Status:** Draft\n**Date:** 2026-09-14\n**Scope:** A deep-research capability in archie-core: an orchestrator that\nspawns 1..N subagents to explore and research in parallel, collates their\nfindings, and returns one cited report. Grounded in web search and web fetch.\n**Beads issue:** none yet (this document is the input to it)\n**Depends on:** nothing shipped for slice 1; slice 2 depends on slice 1.\n\n## §0 Implementation status\n\nEvery claim in this document is mapped to what exists in the tree.\n\n| Claim | Status | Where it stands |\n| ---------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `web_fetch` tool (URL → readable text) | **Implemented** | `internal/tools/webfetch/{tool.go,webfetch.go}`; registered in `internal/app/archied/bootstrap.go` `registerStandaloneTools`, disabled-by-config returns `nil` |\n| **Web search** (query → result list) | **Aspirational — zero code** | No search provider, no search tool, no config block anywhere in the tree or in `ai-sdk` v0.1.32 |\n| `agent.Subagent` — nested agent in a fresh context window | **Implemented** (dependency) | `github.com/samcharles93/ai-sdk@v0.1.32/agent/subagent.go`. Synchronous, non-streaming, own model/system/toolset, `MaxSteps` defaults to 10, nesting depth capped at 5, returns final text only |\n| Subagent used in production | **Implemented, one consumer** | `internal/app/agentworker/review.go` — the adversarial reviewer. That is the only non-test use of `Subagent` in the repo |\n| A **delegate/subagent tool** on the chat surface | **Aspirational — zero code** | No `subagent`/`delegate` tool name is registered anywhere |\n| **Fan-out orchestration** (N missions, one collator) | **Aspirational — zero code** | `agentloop`'s package doc states it runs _one_ mission: \"orchestration across missions lives with the caller\". No caller does this yet |\n| Parallel-safe tool execution | **Aspirational — zero code** | The unreachable `internal/tools/dispatch.go` dispatch/gating engine (`ExecutionClass`, `DispatchSequential`/`DispatchConcurrent`/`ClassifyEntry`) was deleted as dead code (tools-core-1); live concurrency is ai-sdk's `GenerateOptions.MaxParallelToolCalls`, which archie-core never sets |\n| Per-result caps + spill-to-disk | **Implemented** Line truncated
},
{
"url": "/dev/prds/dynamic-curators/",
"title": "Dynamically-defined curators -- decision",
"section": "PRDs",
"body": "# Dynamically-defined curators -- decision\n\n**Status:** Approved\n**Date:** 2026-09-12\n**GitHub epic:** [#789](https://github.com/samcharles93/archie-core/issues/789)\n**Parent epic (curator engine):** [#435](https://github.com/samcharles93/archie-core/issues/435) (closed)\n**Depends on:** nothing shipping; this resolves the open question that epic #435's\n\"registered and configured declaratively, not hardcoded\" criterion left open.\n\n## §0 Implementation status\n\nEvery claim in this document is mapped to what exists in the tree.\n\n| Claim | Status | Where it stands |\n|---|---|---|\n| Curator engine family: typed contract, owning registry, start/health/stop, narrow host access | **Implemented** | `internal/domain/curator/{contract,registry,runtime,registrar,activity,wake}.go` |\n| Curator declared shape (`Manifest`: interval, cooldown, on_input, tools, skills, memory engine, conversations, model) | **Implemented** | `internal/domain/curator/contract.go`; `Validate()` requires `Interval \u003e 0` |\n| Two reference curators run through the registry | **Implemented** | `internal/infrastructure/skillcurator`, `internal/infrastructure/sessioncurator` |\n| Curator definitions as persisted, API-editable data | **Aspirational -- zero code** | No table, no entity, no RPC, no config block |\n| Generic definition-driven engine that executes a declared tool set + free-form instructions | **Aspirational -- zero code** | Only the two code-registered curators exist |\n| `Registrar.Tools` (`ToolBuilder`) resolved and bound at registration | **Partial** | Interface declared (`registrar.go`); **no implementation anywhere**; `bootstrap.go` builds the `Registrar` with no `Tools` field |\n| A curator can declare tools at all | **Partial** | `Manifest.Tools` exists, but `registry.go` fails registration with `\"curator manifest: declares tools but the registrar has no ToolBuilder\"` |\n| Curator passes that actually reach a model with tools | **Cosmetic only** | `curator.ChatRequest` carries `Tools`/`MaxSteps`; `curatorLLMRunner` (`internal/app/archied/main.go`) drops both and returns `ChatResult{Text}` only |\n| Dynamic registration / removal (no restart) | **Aspirational -- zero code** | `Registry` has `Register`, no `Unregister`; `Runtime` has `Start`/`Nudge`/`Stop`, no `Add`/`Remove`; `Start()` snapshots membership |\n| Curator definition CRUD over REST | **Partial** | `GET /api/curators` read-only (`internal/webui/server.go`); no write routes |\n| Curator definition config | **Aspirational -- zero code** | No `[curator]` block in `internal/config/config.go` |\n| Store/API as definition authority | **Aspirational -- zero code** | No curator persistence of any kind |\n| 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 |\n| 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 |\n| Sampler family | **Implemented** | `internal/domain/sampling`, shipped; no curator consumes a `Sampler` yet |\n| 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 |\n\n\u003e **Target state, not current state.** Everything below marked aspirational is\n\u003e design, not a description of the daemon as it runs.\n\n## Problem\n\nA curator exists only if a Go package implements `curator.CuratorEngine`\nand `bootstrap.go/1025` names it in a `Register` call. Nothing about a\ncurator is definable as data. Worse, no curator can declare a tool set at all:\nthe `ToolBuilder` interface has no implementation in the repo, so the registry\nrefuses (correctly, fail-closed) any curator that declares tools -- and the\ndaemon's model adapter drops the tools even if it were bound. The curator family\ntherefore has exactly one shape (cheap, tool-less maintenance pass) and its only\nextension point is compiling Go.\n\nSam's requirement is the opposite: *\"Curators should be dynamically created and\ndefined, in addition to being able to be defined in code/config/webui\"* and *\"No\nconfiguration should ever be hard-coded.\"* The motivating consumer is a\nproject/orchestrator curator -- declared as data, given forge issue tools, and\npointed at a repo to review, refine, and propose issues.\n\n## Decision\n\n**A curator definition is data: a persisted entity whose declared shape is\nexactly `curator.Manifest` plus identity, free-form instructions, and an enabled\nflag. One generic engine interprets any definition.** The shape is not a second\ninvention -- `MLine truncated
"body": "# Dynamically-defined curators -- decision\n\n**Status:** Approved\n**Date:** 2026-09-12\n**GitHub epic:** [#789](https://github.com/samcharles93/archie-core/issues/789)\n**Parent epic (curator engine):** [#435](https://github.com/samcharles93/archie-core/issues/435) (closed)\n**Depends on:** nothing shipping; this resolves the open question that epic #435's\n\"registered and configured declaratively, not hardcoded\" criterion left open.\n\n## §0 Implementation status\n\nEvery claim in this document is mapped to what exists in the tree.\n\n| Claim | Status | Where it stands |\n| --------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Curator engine family: typed contract, owning registry, start/health/stop, narrow host access | **Implemented** | `internal/domain/curator/{contract,registry,runtime,registrar,activity,wake}.go` |\n| Curator declared shape (`Manifest`: interval, cooldown, on_input, tools, skills, memory engine, conversations, model) | **Implemented** | `internal/domain/curator/contract.go`; `Validate()` requires `Interval \u003e 0` |\n| Two reference curators run through the registry | **Implemented** | `internal/infrastructure/skillcurator`, `internal/infrastructure/sessioncurator` |\n| Curator definitions as persisted, API-editable data | **Aspirational -- zero code** | No table, no entity, no RPC, no config block |\n| Generic definition-driven engine that executes a declared tool set + free-form instructions | **Aspirational -- zero code** | Only the two code-registered curators exist |\n| `Registrar.Tools` (`ToolBuilder`) resolved and bound at registration | **Partial** | Interface declared (`registrar.go`); **no implementation anywhere**; `bootstrap.go` builds the `Registrar` with no `Tools` field |\n| A curator can declare tools at all | **Partial** | `Manifest.Tools` exists, but `registry.go` fails registration with `\"curator manifest: declares tools but the registrar has no ToolBuilder\"` |\n| Curator passes that actually reach a model with tools | **Cosmetic only** | `curator.ChatRequest` carries `Tools`/`MaxSteps`; `curatorLLMRunner` (`internal/app/archied/main.go`) drops both and returns `ChatResult{Text}` only |\n| Dynamic registration / removal (no restart) | **Aspirational -- zero code** | `Registry` has `Register`, no `Unregister`; `Runtime` has `Start`/`Nudge`/`Stop`, no `Add`/`Remove`; `Start()` snapshots membership |\n| Curator definition CRUD over REST | **Partial** | `GET /api/curators` read-only (`internal/webui/server.go`); no write routes |\n| Curator definition config | **Aspirational -- zero code** | No `[curator]` block in `intLine truncated
},
{
"url": "/dev/prds/dynamic-workflow-triage/",
"title": "Dynamic workflow triage",
"section": "PRDs",
"body": "# Dynamic workflow triage\n\n**Status:** Finalised\n\nEpic: archie-core-enfj. Scope: give `workflow.Route()` a real, content-aware\nfallback instead of unconditionally defaulting every unlabeled task to the\nheaviest workflow.\n\n## Problem\n\n`Route()` (`internal/domain/workflow/workflow.go`) has exactly two real\nsignals: an explicit `t.Workflow`, and label matches via\n`workflowForLabels` (`routing.go`, `bug`→tdd, `feature`→feasibility,\nbootstrap→bootstrap). Anything else — which is every chat-spawned task,\nsince `task_spawn` rarely sets labels — falls straight through to\n`reg[\"implement\"]`, the full `prepare → baseline → plan → build →\ncommit-push → review → open-pr` pipeline, regardless of what the task\nactually asks for.\n\n`task_spawn`'s own tool schema overpromises: *\"workflow: … Omit to let the\ndaemon route it\"* (`internal/gateway/task_tools.go`) implies real\nrouting exists. It doesn't — \"route\" means \"check labels, then\ngive up and run the heaviest workflow anyway.\"\n\nConfirmed in production: a chat-spawned task whose\nentire content was \"this is just a test, close it when you receive it\" ran\nthe full `implement` pipeline end to end — 669,421 tokens, ~7 minutes —\nwhen nothing about the request needed a worktree-driven build at all. The\n`plan` stage's own LLM output *correctly* concluded no code change was\nneeded, but that conclusion arrives two expensive stages (`baseline`,\n`plan`) too late to save anything.\n\n## Decision\n\nAdd a **`triage` workflow**: cheap, classifies once, then either closes the\ntask immediately or hands off to the workflow the task actually needs.\n`Route()`'s final fallback (`reg[\"implement\"]`) becomes\n`reg[\"triage\"]` when a `triage` entry is registered, else the existing\n`implement` fallback — a two-line change, fully backward compatible when\n`triage` isn't wired up.\n\nTriage does **not** replace label-based routing. A labeled task\n(`bug`/`feature`/bootstrap) already has a free, reliable signal and goes\nstraight to its known workflow unchanged — spending a classification\ncall there would be pure waste. Triage only fires in the gap that\ndefaults to `implement` blindly: no explicit workflow, no label match.\n\n### Triage workflow shape\n\n```\nStagePrepareWorktree() -- still needed: AgentStage mounts tc.Dir into the\n agent container: internal/domain/workflow/agent.go:74\n passes tc.Dir straight through. No cheaper\n primitive exists in this codebase for a\n directory-less classification call.\nAgentStage \"classify\" -- ReadOnly, ONE cheap agent turn, no exploration\n tools required beyond what ReadOnly already\n grants. Mirrors feasibility.go's decideCaptureTools\n pattern: a structured capture tool, called\n exactly once, MaxCalls: 1.\n```\n\nMission: read the task's title/body/labels (already in `taskPromptBlock`)\nand decide, via a captured `decide` tool call:\n\n```json\n{\"needs_code_change\": bool, \"workflow\": \"implement\" | \"tdd\" | \"feasibility\", \"reasons\": \"...\"}\n```\n\n`needs_code_change: false` → close path: reuse `closeNoChangesIssue`\n(`steps.go`) directly — issue closed if forge-backed, task marked\n`StatusMerged`/`\"completed -- no changes required\"` otherwise. No baseline,\nno plan, no build, no commit, no PR. This is the actual fix for the\nproduction incident: a no-op request now costs one classification call\n(low thousands of tokens) instead of 669,421.\n\n`needs_code_change: true` → sets `tc.Task.Workflow` to the classifier's\nchosen workflow (`implement`/`tdd`/`feasibility`, defaulting to\n`implement` if the field is missing or unrecognized) and an Outcome that\nrequeues the task under it, the same requeue mechanism\n`chatTaskControllerAdapter.ApproveChatTask` already uses\n(`main.go`, `requeue(ctx, taskID, fromStatus, workflow)`). The task then\nre-enters `Route()` on its next claim with `t.Workflow` now set, and takes\nthe normal path for that workflow from there — triage never runs its\nclassification twice for the same task.\n\n### Non-goals (v1)\n\n- Full bug/feature intent classification quality — the classifier only\n needs to be *directionally* right; a wrong `tdd` vs `implement` call\n still produces a working PR, just via a slightly less-tailored pipeline.\n Tightening this is a follow-up, not a blocker.\n- Any change to label-based routing, `Route()`'s explicit-workflow branch,\n or `Bootstrap()`/`Feasibility()`/`TDD()` themselves.\n- Triage for forge-sourced (real GitHub issue) tasks with no labels —\n in scope structurally (same fallback branch), but the dominant case this\n fixes is chat-spawned tasks, which essentially never carry labels.\n\n## Testing\n\n- `workflow_test.go`: `Route()` picks `regLine truncated
"body": "# Dynamic workflow triage\n\n**Status:** Finalised\n\nEpic: archie-core-enfj. Scope: give `workflow.Route()` a real, content-aware\nfallback instead of unconditionally defaulting every unlabelled task to the\nheaviest workflow.\n\n## Problem\n\n`Route()` (`internal/domain/workflow/workflow.go`) has exactly two real\nsignals: an explicit `t.Workflow`, and label matches via\n`workflowForLabels` (`routing.go`, `bug`→tdd, `feature`→feasibility,\nbootstrap→bootstrap). Anything else — which is every chat-spawned task,\nsince `task_spawn` rarely sets labels — falls straight through to\n`reg[\"implement\"]`, the full `prepare → baseline → plan → build →\ncommit-push → review → open-pr` pipeline, regardless of what the task\nactually asks for.\n\n`task_spawn`'s own tool schema overpromises: _\"workflow: … Omit to let the\ndaemon route it\"_ (`internal/gateway/task_tools.go`) implies real\nrouting exists. It doesn't — \"route\" means \"check labels, then\ngive up and run the heaviest workflow anyway.\"\n\nConfirmed in production: a chat-spawned task whose\nentire content was \"this is just a test, close it when you receive it\" ran\nthe full `implement` pipeline end to end — 669,421 tokens, ~7 minutes —\nwhen nothing about the request needed a worktree-driven build at all. The\n`plan` stage's own LLM output _correctly_ concluded no code change was\nneeded, but that conclusion arrives two expensive stages (`baseline`,\n`plan`) too late to save anything.\n\n## Decision\n\nAdd a **`triage` workflow**: cheap, classifies once, then either closes the\ntask immediately or hands off to the workflow the task actually needs.\n`Route()`'s final fallback (`reg[\"implement\"]`) becomes\n`reg[\"triage\"]` when a `triage` entry is registered, else the existing\n`implement` fallback — a two-line change, fully backward compatible when\n`triage` isn't wired up.\n\nTriage does **not** replace label-based routing. A labelled task\n(`bug`/`feature`/bootstrap) already has a free, reliable signal and goes\nstraight to its known workflow unchanged — spending a classification\ncall there would be pure waste. Triage only fires in the gap that\ndefaults to `implement` blindly: no explicit workflow, no label match.\n\n### Triage workflow shape\n\n```\nStagePrepareWorktree() -- still needed: AgentStage mounts tc.Dir into the\n agent container: internal/domain/workflow/agent.go:74\n passes tc.Dir straight through. No cheaper\n primitive exists in this codebase for a\n directory-less classification call.\nAgentStage \"classify\" -- ReadOnly, ONE cheap agent turn, no exploration\n tools required beyond what ReadOnly already\n grants. Mirrors feasibility.go's decideCaptureTools\n pattern: a structured capture tool, called\n exactly once, MaxCalls: 1.\n```\n\nMission: read the task's title/body/labels (already in `taskPromptBlock`)\nand decide, via a captured `decide` tool call:\n\n```json\n{\"needs_code_change\": bool, \"workflow\": \"implement\" | \"tdd\" | \"feasibility\", \"reasons\": \"...\"}\n```\n\n`needs_code_change: false` → close path: reuse `closeNoChangesIssue`\n(`steps.go`) directly — issue closed if forge-backed, task marked\n`StatusMerged`/`\"completed -- no changes required\"` otherwise. No baseline,\nno plan, no build, no commit, no PR. This is the actual fix for the\nproduction incident: a no-op request now costs one classification call\n(low thousands of tokens) instead of 669,421.\n\n`needs_code_change: true` → sets `tc.Task.Workflow` to the classifier's\nchosen workflow (`implement`/`tdd`/`feasibility`, defaulting to\n`implement` if the field is missing or unrecognised) and an Outcome that\nrequeues the task under it, the same requeue mechanism\n`chatTaskControllerAdapter.ApproveChatTask` already uses\n(`main.go`, `requeue(ctx, taskID, fromStatus, workflow)`). The task then\nre-enters `Route()` on its next claim with `t.Workflow` now set, and takes\nthe normal path for that workflow from there — triage never runs its\nclassification twice for the same task.\n\n### Non-goals (v1)\n\n- Full bug/feature intent classification quality — the classifier only\n needs to be _directionally_ right; a wrong `tdd` vs `implement` call\n still produces a working PR, just via a slightly less-tailored pipeline.\n Tightening this is a follow-up, not a blocker.\n- Any change to label-based routing, `Route()`'s explicit-workflow branch,\n or `Bootstrap()`/`Feasibility()`/`TDD()` themselves.\n- Triage for forge-sourced (real GitHub issue) tasks with no labels —\n in scope structurally (same fallback branch), but the dominant case this\n fixes is chat-spawned tasks, which essentially never carry labels.\n\n## Testing\n\n- `workflow_test.go`: `Route()` picks `rLine truncated
},
{
"url": "/dev/prds/eda-playbook-engine/",
"title": "EDA playbook engine -- design",
"section": "PRDs",
"body": "# EDA playbook engine -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Beads epic:** `archie-core-t2db`\n\n## Problem\n\n\"Which workflow runs for which trigger\" is hardcoded Go: a literal\nlabel vocabulary (`workintake.labelKinds`) and a literal label-\u003eworkflow map\n(`workflow/routing.go`), extended only by adding a Go case or shipping a\nskill whose `metadata.archie.workflow` overrides one *named* built-in\nworkflow. Extending the system to a new trigger, a new action, or a new\nevent source means a feature branch, a code change in a hardcoded\npath, and new Go tests -- for every addition. That is the barrier this\ndocument exists to remove.\n\nThe goal: triggers, the actions they run, and the\nconditions that connect them should be **drop-in and load**, not **drop-in\nand touch application code**. Yaegi-evaluated Go is the unit of imperative\n\"do a thing\" logic; YAML playbooks are pure orchestration data -- no logic,\njust \"on this event, with this data, call these actions, in this order,\nunder these conditions.\" The daemon's event coordinator doesn't know what a\n`bugfix` or `image-gen` action does, it resolves the name against a\nregistry and pipes typed data through.\n\nThis is explicitly **not** scoped to code-generation workflows. A playbook\naction can be any registered capability -- run a codegen workflow, send a\nmessage on a channel, open something on a forge, generate an image -- so\nlong as it's implemented behind one of the typed engine families below.\n\n## Relationship to existing decisions\n\n- `docs/prds/event-sources-and-reactions.md` ruled\n that reactions in the two epics it covers are **producer-only** (no veto,\n no mutation of in-flight work) and explicitly rejected a single generic\n `Source` interface as \"the untyped-hook shape the plugin engine rule\n exists to prevent.\" **This document extends that scope**: playbooks can\n dispatch to multiple typed action kinds, not just \"produce a\n `TaskEnvelope`.\" It does not relitigate producer-only-ness (still no\n veto/mutation of in-flight work here) and it does not introduce one\n generic interface -- see \"Typed positions, not one generic hook\" below,\n which is how it stays compliant with the plugin engine rule instead of\n reopening that document's #4.\n- `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`\n governs every extension point\n introduced here. Every position below is a typed domain contract with an\n owning registry, not a generic callback map. This is a hard constraint,\n confirmed against the existing rule text before writing this doc.\n- Yaegi is already a proven in-process extension mechanism\n (`internal/plugin`, `internal/domain/workflow/wfeval/yaegi.go`,\n `internal/gate/gateeval/yaegi.go`, `internal/skill/plugin.go`) -- this\n design generalizes its existing role, it does not introduce a new\n execution mechanism.\n- `internal/domain/workflow/skillbuild.BuildRegistry` already composes a\n `workflow.Registry` from a skills catalog, plugin-defined overriding\n built-in. The playbook loader described here supersedes label routing\n specifically; it does not replace `skillbuild`'s workflow-composition role,\n it becomes an additional input the daemon composes at startup.\n- Webhook event intake is a separate design. This\n document defines the router each webhook-sourced event should be able to\n reach; it does not redesign webhook receipt itself.\n\n## Shape: four logic positions, each a typed engine family\n\nEvery entrypoint kind (mechanism, action, loop, schedule, route, trigger) is itself a schema emitter: defining a new kind produces the\ngenerated contract downstream tooling consumes. The kinds slot into a fixed\nhierarchy of logic positions:\n\n```\nWorkflow -\u003e Module -\u003e Channel (telegram/whatsapp/email/...)\n -\u003e Forge (GitHub/Gitea/GitLab/...)\n```\n\nEach position is its own typed engine family per the plugin engine rule:\nidentity + capability-specific operations, an owning `Registry`/`Manager`,\nexplicit lifecycle where the implementation owns resources, narrow host\naccess. Concretely:\n\n- **Workflow** -- already exists (`internal/domain/workflow`). A playbook\n action of kind `workflow` invokes a registered `workflow.Registry` entry\n by name, unchanged from the existing execution path.\n- **Module** -- the new general-purpose action position. A `Module` is a\n Yaegi-evaluated implementation of a generated interface (args in, typed\n result out) for one declared action kind (e.g. `image-gen`, `notify`,\n `open-pr-comment`). This is the position that makes actions \"not\n restricted to code-generation.\" Full design (schema-per-kind, the\n registry shape, the trust boundary, the recommended first slice):\n `docs/prds/module-position.md`.\n- **Channel** -- already exists as `channels.Channel` (telegram, email,\n webhook). A playbook action of kind `channel` sends through Line truncated
"body": "# EDA playbook engine -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Beads epic:** `archie-core-t2db`\n\n## Problem\n\n\"Which workflow runs for which trigger\" is hardcoded Go: a literal\nlabel vocabulary (`workintake.labelKinds`) and a literal label-\u003eworkflow map\n(`workflow/routing.go`), extended only by adding a Go case or shipping a\nskill whose `metadata.archie.workflow` overrides one _named_ built-in\nworkflow. Extending the system to a new trigger, a new action, or a new\nevent source means a feature branch, a code change in a hardcoded\npath, and new Go tests -- for every addition. That is the barrier this\ndocument exists to remove.\n\nThe goal: triggers, the actions they run, and the\nconditions that connect them should be **drop-in and load**, not **drop-in\nand touch application code**. Yaegi-evaluated Go is the unit of imperative\n\"do a thing\" logic; YAML playbooks are pure orchestration data -- no logic,\njust \"on this event, with this data, call these actions, in this order,\nunder these conditions.\" The daemon's event coordinator doesn't know what a\n`bugfix` or `image-gen` action does, it resolves the name against a\nregistry and pipes typed data through.\n\nThis is explicitly **not** scoped to code-generation workflows. A playbook\naction can be any registered capability -- run a codegen workflow, send a\nmessage on a channel, open something on a forge, generate an image -- so\nlong as it's implemented behind one of the typed engine families below.\n\n## Relationship to existing decisions\n\n- `docs/prds/event-sources-and-reactions.md` ruled\n that reactions in the two epics it covers are **producer-only** (no veto,\n no mutation of in-flight work) and explicitly rejected a single generic\n `Source` interface as \"the untyped-hook shape the plugin engine rule\n exists to prevent.\" **This document extends that scope**: playbooks can\n dispatch to multiple typed action kinds, not just \"produce a\n `TaskEnvelope`.\" It does not relitigate producer-only-ness (still no\n veto/mutation of in-flight work here) and it does not introduce one\n generic interface -- see \"Typed positions, not one generic hook\" below,\n which is how it stays compliant with the plugin engine rule instead of\n reopening that document's #4.\n- `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`\n governs every extension point\n introduced here. Every position below is a typed domain contract with an\n owning registry, not a generic callback map. This is a hard constraint,\n confirmed against the existing rule text before writing this doc.\n- Yaegi is already a proven in-process extension mechanism\n (`internal/plugin`, `internal/domain/workflow/wfeval/yaegi.go`,\n `internal/gate/gateeval/yaegi.go`, `internal/skill/plugin.go`) -- this\n design generalises its existing role, it does not introduce a new\n execution mechanism.\n- `internal/domain/workflow/skillbuild.BuildRegistry` already composes a\n `workflow.Registry` from a skills catalogue, plugin-defined overriding\n built-in. The playbook loader described here supersedes label routing\n specifically; it does not replace `skillbuild`'s workflow-composition role,\n it becomes an additional input the daemon composes at startup.\n- Webhook event intake is a separate design. This\n document defines the router each webhook-sourced event should be able to\n reach; it does not redesign webhook receipt itself.\n\n## Shape: four logic positions, each a typed engine family\n\nEvery entrypoint kind (mechanism, action, loop, schedule, route, trigger) is itself a schema emitter: defining a new kind produces the\ngenerated contract downstream tooling consumes. The kinds slot into a fixed\nhierarchy of logic positions:\n\n```\nWorkflow -\u003e Module -\u003e Channel (telegram/whatsapp/email/...)\n -\u003e Forge (GitHub/Gitea/GitLab/...)\n```\n\nEach position is its own typed engine family per the plugin engine rule:\nidentity + capability-specific operations, an owning `Registry`/`Manager`,\nexplicit lifecycle where the implementation owns resources, narrow host\naccess. Concretely:\n\n- **Workflow** -- already exists (`internal/domain/workflow`). A playbook\n action of kind `workflow` invokes a registered `workflow.Registry` entry\n by name, unchanged from the existing execution path.\n- **Module** -- the new general-purpose action position. A `Module` is a\n Yaegi-evaluated implementation of a generated interface (args in, typed\n result out) for one declared action kind (e.g. `image-gen`, `notify`,\n `open-pr-comment`). This is the position that makes actions \"not\n restricted to code-generation.\" Full design (schema-per-kind, the\n registry shape, the trust boundary, the recommended first slice):\n `docs/prds/module-position.md`.\n- **Channel** -- already exists as `channels.Channel` (telegram, email,\n webhook). A playbook action of kind `channel` sends througLine truncated
},
{
"url": "/dev/prds/embedded-nats/",
"title": "Embedded NATS execution -- decision",
"section": "PRDs",
"body": "# Embedded NATS execution -- decision\n\n**Status:** Finalised\n\n**Date:** 2026-08-24\n\n**Beads epic:** `archie-core-q15y`\n\nThis decision supersedes the position that embedded NATS was only a\ndistribution mechanism and could not be an agent-execution topology. That was\ntrue only because the embedded listener was unauthenticated loopback. It left a\nsecond production architecture in which `archied` ran autonomous workflows in\nits own process, weakening the isolation boundary that managed task containers\nexist to provide.\n\n## One execution architecture, two broker deployments\n\nEvery autonomous repository workflow is handed over as one complete task via\nNATS and runs in a task-scoped `archie-agent` container. `archied` remains a\nnative, long-lived orchestration and interactive-chat process; its operator\nconfigured host filesystem access is unchanged. It owns task admission,\nstate, forge and worktree operations, container lifecycle, and the broker when\nthe embedded deployment is selected. It does not run an autonomous model loop.\n\nNATS has two supported deployment shapes:\n\n| mode | meaning |\n| --- | --- |\n| `embedded` | `archied` owns an in-process JetStream server (default). |\n| `external` | `archied` and workers connect to the configured NATS URL. |\n\nBoth shapes have identical task semantics: one container and one full-task\nrequest per workflow. Broker placement must not select a different executor.\nThe legacy `agent` section and `containers.enabled` key remain decode-only\nmigration inputs. `nats.mode = \"off\"`, per-stage NATS, in-process execution,\nand subprocess execution are not production choices.\n\nSQLite remains authoritative for task state. NATS is the sole autonomous work\nhandoff. SQLite recovery may identify work that needs republishing, but it must\nnot cause `archied` to call `workflow.Run` locally.\n\n## Embedded reachability and authentication\n\nAn embedded listener uses a cryptographically random bearer token generated for\neach daemon start. The token exists only in process memory and the environment\nof managed worker containers; it is never written to config or logs.\n\nFor a native daemon with managed containers, startup resolves the Docker bridge\nthe workers will join. The listener binds only to that bridge's host gateway\naddress on a random port. Both the native daemon and workers use that same\nreachable endpoint, and every client supplies the generated token. Binding a\nDocker bridge address keeps the listener off ordinary LAN interfaces without\npublishing a host port. A configured user bridge is respected; otherwise the\nDocker default bridge is used. A network without a usable local IPv4 gateway is\na startup error for autonomous execution.\n\nIf Docker is unavailable, interactive chat may still start and embedded NATS\nmay remain loopback-only, but autonomous tasks park with an explicit container\ncapability failure. They never fall back to host execution.\n\n## Ownership and lifecycle\n\n- `internal/infrastructure/eventbus/nats` owns the authenticated embedded\n server and exposes its runtime endpoint, not the server implementation.\n- `internal/container` resolves the worker bridge and gateway and owns task\n container lifecycle.\n- `internal/app` composition selects embedded or external broker deployment,\n freezes the connected runtime endpoint for worker environments, and wires the\n full-task handoff.\n- `cmd/archied` remains process input only as the domain migration reaches this\n composition path.\n\nThe daemon starts the embedded server before its client, closes clients before\nthe server, and keeps JetStream data beneath the daemon data directory. NATS URL\nand token are startup-built values: a reload cannot send new workers to a broker\ndifferent from the one the daemon is using.\n"
"body": "# Embedded NATS execution -- decision\n\n**Status:** Finalised\n\n**Date:** 2026-08-24\n\n**Beads epic:** `archie-core-q15y`\n\nThis decision supersedes the position that embedded NATS was only a\ndistribution mechanism and could not be an agent-execution topology. That was\ntrue only because the embedded listener was unauthenticated loopback. It left a\nsecond production architecture in which `archied` ran autonomous workflows in\nits own process, weakening the isolation boundary that managed task containers\nexist to provide.\n\n## One execution architecture, two broker deployments\n\nEvery autonomous repository workflow is handed over as one complete task via\nNATS and runs in a task-scoped `archie-agent` container. `archied` remains a\nnative, long-lived orchestration and interactive-chat process; its operator\nconfigured host filesystem access is unchanged. It owns task admission,\nstate, forge and worktree operations, container lifecycle, and the broker when\nthe embedded deployment is selected. It does not run an autonomous model loop.\n\nNATS has two supported deployment shapes:\n\n| mode | meaning |\n| ---------- | --------------------------------------------------------- |\n| `embedded` | `archied` owns an in-process JetStream server (default). |\n| `external` | `archied` and workers connect to the configured NATS URL. |\n\nBoth shapes have identical task semantics: one container and one full-task\nrequest per workflow. Broker placement must not select a different executor.\nThe legacy `agent` section and `containers.enabled` key remain decode-only\nmigration inputs. `nats.mode = \"off\"`, per-stage NATS, in-process execution,\nand subprocess execution are not production choices.\n\nSQLite remains authoritative for task state. NATS is the sole autonomous work\nhandoff. SQLite recovery may identify work that needs republishing, but it must\nnot cause `archied` to call `workflow.Run` locally.\n\n## Embedded reachability and authentication\n\nAn embedded listener uses a cryptographically random bearer token generated for\neach daemon start. The token exists only in process memory and the environment\nof managed worker containers; it is never written to config or logs.\n\nFor a native daemon with managed containers, startup resolves the Docker bridge\nthe workers will join. The listener binds only to that bridge's host gateway\naddress on a random port. Both the native daemon and workers use that same\nreachable endpoint, and every client supplies the generated token. Binding a\nDocker bridge address keeps the listener off ordinary LAN interfaces without\npublishing a host port. A configured user bridge is respected; otherwise the\nDocker default bridge is used. A network without a usable local IPv4 gateway is\na startup error for autonomous execution.\n\nIf Docker is unavailable, interactive chat may still start and embedded NATS\nmay remain loopback-only, but autonomous tasks park with an explicit container\ncapability failure. They never fall back to host execution.\n\n## Ownership and lifecycle\n\n- `internal/infrastructure/eventbus/nats` owns the authenticated embedded\n server and exposes its runtime endpoint, not the server implementation.\n- `internal/container` resolves the worker bridge and gateway and owns task\n container lifecycle.\n- `internal/app` composition selects embedded or external broker deployment,\n freezes the connected runtime endpoint for worker environments, and wires the\n full-task handoff.\n- `cmd/archied` remains process input only as the domain migration reaches this\n composition path.\n\nThe daemon starts the embedded server before its client, closes clients before\nthe server, and keeps JetStream data beneath the daemon data directory. NATS URL\nand token are startup-built values: a reload cannot send new workers to a broker\ndifferent from the one the daemon is using.\n"
},
{
"url": "/dev/prds/event-automation/",
"title": "Event automation: identified events, typed parameters, purpose-built agents",
"section": "PRDs",
"body": "# Event automation: identified events, typed parameters, purpose-built agents\n\n**Status:** Approved\n**Date:** 2026-09-23\n**Parent:** epic `archie-core-t2db`\n\n## Why this exists\n\nArchie is an event-driven automation system. Any system that can send a\nwebhook (a forge, an error tracker, a firewall, a monitoring stack) should be\nable to start an agent built for that job. The shape this replaces cannot:\n\n- A binding matches only the URL segment an event was posted to, and a source\n may have one binding. Two kinds of event from one sender cannot go to\n different workflows.\n- A mapping is a list of JSON paths written against one example payload.\n Nothing recognises what kind of event arrived.\n- Mapped values reach the task only as `key=value` lines in its body text.\n- Every task needs a repository and runs in a git worktree.\n- Every agent runs the same image with the same forwarded keys.\n\n## The model\n\n```\nsource ─▶ event type ─▶ mapping ─▶ binding ─▶ workflow ─▶ agent profile\n (identified) (params) (+ filter, (inputs, (image, tools)\n repo) profile)\n```\n\n### Sources\n\nA source is the endpoint one sender posts to. Its path is a generated UUIDv7\n(`/webhooks/capture/0199…`), so an endpoint cannot be guessed or collide. The\noperator may replace it with a custom path for a sender that cannot use that\nformat; a custom path must be unique and URL-safe, and is refused otherwise.\nA source owns the signing setting:\n\n- **Signed** (default). Archie generates the secret. Only events with a valid\n `X-Hub-Signature-256` or `X-Signature-256` HMAC are dispatched.\n- **Unsigned.** The operator turns signing off for a sender that cannot sign.\n The source and every event from it are marked unsigned in the inspector,\n the binding list and the task timeline. Turning signing off needs the same\n approval as arming a binding.\n\nUnauthenticated events on a signed source are captured and never\ndispatched.\n\n### Event types\n\nAn event type is a named kind of event from one source, such as\n`github / pull_request.opened` or `firewall / blocked_connection`. It is\ndefined by a match rule:\n\n- header equality (`X-GitHub-Event = pull_request`), and\n- payload conditions (`action = \"opened\"`, or a path being present).\n\nAn event type can be created two ways:\n\n- **From an example payload.** The operator pastes a payload (and optionally\n its headers), and archie converts it to the type's schema. No event needs to\n have arrived.\n- **From captures.** Archie proposes types from what has arrived, as below.\n\nEither way, archie infers the schema, not the operator:\n\n- Each capture gets a structural signature: the set of JSON paths with their\n value types, plus the headers that look like discriminators (`*-Event`,\n `*-Type`, `Content-Type`).\n- Captures from one source that share a signature are grouped. The inspector\n shows each group as a proposed event type, with its inferred schema, its\n number of events and a sample, until the operator names it or dismisses it.\n- The proposed match rule is the set of discriminators that separates the\n group from its siblings. The operator can edit it before saving.\n- A capture that matches no named type is shown as unidentified. It is never\n dispatched.\n\nTwo event types on one source whose rules can match the same event are\nrefused when the second one is saved.\n\n### Mappings\n\nA mapping belongs to an event type. It maps payload paths to named, typed\nparameters, and it is checked against the type's inferred schema, so a path\nthe type does not have is refused when the mapping is saved. Any number of\nbindings may reuse one mapping.\n\nEach mapping shows how many events it has matched, with the time of the most\nrecent, so an operator can see which mappings are live and which have never\nfired.\n\n### Workflows declare inputs\n\nA workflow definition declares its inputs:\n\n```yaml\nid: firewall-investigate\ninputs:\n src_ip: { type: string, required: true }\n severity: { type: string }\nrepository: none # none | optional | required\nprofile: network-investigator\nsteps: ...\n```\n\n- `repository: none` runs the agent in a scratch workspace with no clone.\n `required`, the default, gives the agent a worktree of the task's\n repository. `optional` gives it a worktree when the binding names a\n repository and a scratch workspace when it does not.\n- A workflow whose `repository` is not `required` may use only steps that need\n no repository. `agent.run` is one: it runs one agent mission and finishes\n the task as done, with no pull request.\n- The declared inputs reach the agent as structured data in the task brief\n and in the agent's context. They are not body text.\n- A workflow may declare `outputs`, the structured result it returns when it\n finishes.\n\n### Workflows call workflows\n\nA workflow step can call another workflow.Line truncated
},
{
"url": "/dev/prds/event-capture-storage/",
"title": "Event capture storage -- decision",
"section": "PRDs",
"body": "# Event capture storage -- decision\n\n**Status:** Finalised\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.1`\n\n`webhook-intake-security.md` decided points 1-5 (auth split, approval gate,\nrate limits, blast radius, retention/redaction) and explicitly left the\nstorage mechanism open, forward-pointing at \"`7d5u.2`, embedded NATS.\" That\npointer predates `7d5u.3`'s 2026-08-22 narrowing, which assigned capture\nstorage to this bead by name and told it to decide NATS-vs-SQLite itself\nrather than inherit an answer. This document is that decision.\n\n## Decision: SQLite, not NATS JetStream\n\nCaptured events are stored in archied's existing SQLite database, in a new\n`captured_events` table following the same shape as `internal/store/events.go`\n(`internal/store`, `*Store`, SQL migrations inline in Go). No JetStream\nstream is introduced for capture.\n\n### Why\n\n**NATS availability does not make capture a broker concern.** NATS is now\nunconditional for autonomous workflow handoff, including embedded mode, but\ncapture is also used by deployments with no repository workflow configured.\nSQLite is guaranteed present because it backs daemon state, and keeps\ncapture inspection independent of broker retention and consumer lifecycle.\nThe original version of this decision cited optional NATS as an additional\nreason; that premise was superseded by `archie-core-q15y`, while the storage\nfit and independence arguments remain.\n\n**Capture's access pattern doesn't need what JetStream is for.** JetStream\nearns its complexity for reaction delivery (`7d5u.2`) because multiple\nindependent consumers need fan-out, at-least-once redelivery, and Ack/Nak\nsemantics -- exactly the trap `CLAUDE.md` documents about `WorkQueuePolicy`\nand overlapping consumers. Capture has exactly one writer (the HTTP handler)\nand one reader (a human via the dashboard inspector, `t2db.2`). There is no\ncompeting-consumer problem to solve and no redelivery semantics to get right,\nso JetStream's core value proposition doesn't apply here. A bounded SQL\ntable is a better fit on the merits, not merely as a fallback.\n\n**Reusing `7d5u.2`'s stream, once it exists, would still be wrong.** That\nstream is provisioned for fan-out reaction delivery with its own retention\npolicy decision. Capture's retention need -- age- and count-bounded, prune\non write, no replay -- is a different shape. Building a second stream just\nfor capture, gated on an unrelated bead landing first, would trade a small\namount of duplication now for a hard dependency on `7d5u.2`'s timeline that\nthis bead's own acceptance criteria say not to accrue by accident.\n\nThis does not foreclose NATS later. If cross-daemon capture sharing or\ndurable replay becomes a real requirement, that is a new decision made\nagainst a real need, not now against a speculative one.\n\n## Storage shape\n\n`captured_events` table (`internal/store/captures.go`, mirrors\n`internal/store/events.go`'s pattern):\n\n| column | type | notes |\n|-----------------|---------|-------------------------------------------------|\n| id | INTEGER | primary key, autoincrement |\n| received_at | TEXT | RFC3339Nano |\n| source | TEXT | opaque path segment chosen by the sender's operator |\n| remote_addr | TEXT | `RemoteAddr` at capture time |\n| content_type | TEXT | `Content-Type` header |\n| headers | TEXT | JSON, redacted |\n| body | TEXT | JSON, redacted (`webhookguard.RedactPayload`) |\n| authenticated | INTEGER | 0/1; always 0 until a source registers a secret (future: `t2db.4`) |\n\nIndexed on `(source, id)` for per-source listing and pruning, and `id` alone\nfor the global cap.\n\n## Disk-bound mechanics\n\nThree independent bounds, composed, per `webhook-intake-security.md` point 5\nand this bead's own \"capture cannot exhaust disk\" criterion:\n\n1. **Per-request size cap.** The HTTP handler reads the body through\n `http.MaxBytesReader` (256 KiB default, configurable). A single oversized\n POST is rejected (413) before redaction or storage sees it.\n2. **Per-remote-address rate limit.** `webhookguard.RateLimiter`, keyed by\n the request's remote address, applied before the body is even read.\n *Not* keyed by the `source` path segment: `RateLimiter`'s own doc comment\n states its bucket map assumes a bounded, operator-registered key space,\n never evicted. `source` is exactly the opposite here -- an unregistered,\n attacker-chosen URL segment, since capturing senders with no registration\n yet is this endpoint's entire purpose. Keying on it would let one sender\n bypass the limit by rotating the segment every request (a fresh key\n always starts with a full burst) and grow the bucket map without bounLine truncated
"body": "# Event capture storage -- decision\n\n**Status:** Finalised\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.1`\n\n`webhook-intake-security.md` decided points 1-5 (auth split, approval gate,\nrate limits, blast radius, retention/redaction) and explicitly left the\nstorage mechanism open, forward-pointing at \"`7d5u.2`, embedded NATS.\" That\npointer predates `7d5u.3`'s 2026-08-22 narrowing, which assigned capture\nstorage to this bead by name and told it to decide NATS-vs-SQLite itself\nrather than inherit an answer. This document is that decision.\n\n## Decision: SQLite, not NATS JetStream\n\nCaptured events are stored in archied's existing SQLite database, in a new\n`captured_events` table following the same shape as `internal/store/events.go`\n(`internal/store`, `*Store`, SQL migrations inline in Go). No JetStream\nstream is introduced for capture.\n\n### Why\n\n**NATS availability does not make capture a broker concern.** NATS is now\nunconditional for autonomous workflow handoff, including embedded mode, but\ncapture is also used by deployments with no repository workflow configured.\nSQLite is guaranteed present because it backs daemon state, and keeps\ncapture inspection independent of broker retention and consumer lifecycle.\nThe original version of this decision cited optional NATS as an additional\nreason; that premise was superseded by `archie-core-q15y`, while the storage\nfit and independence arguments remain.\n\n**Capture's access pattern doesn't need what JetStream is for.** JetStream\nearns its complexity for reaction delivery (`7d5u.2`) because multiple\nindependent consumers need fan-out, at-least-once redelivery, and Ack/Nak\nsemantics -- exactly the trap `CLAUDE.md` documents about `WorkQueuePolicy`\nand overlapping consumers. Capture has exactly one writer (the HTTP handler)\nand one reader (a human via the dashboard inspector, `t2db.2`). There is no\ncompeting-consumer problem to solve and no redelivery semantics to get right,\nso JetStream's core value proposition doesn't apply here. A bounded SQL\ntable is a better fit on the merits, not merely as a fallback.\n\n**Reusing `7d5u.2`'s stream, once it exists, would still be wrong.** That\nstream is provisioned for fan-out reaction delivery with its own retention\npolicy decision. Capture's retention need -- age- and count-bounded, prune\non write, no replay -- is a different shape. Building a second stream just\nfor capture, gated on an unrelated bead landing first, would trade a small\namount of duplication now for a hard dependency on `7d5u.2`'s timeline that\nthis bead's own acceptance criteria say not to accrue by accident.\n\nThis does not foreclose NATS later. If cross-daemon capture sharing or\ndurable replay becomes a real requirement, that is a new decision made\nagainst a real need, not now against a speculative one.\n\n## Storage shape\n\n`captured_events` table (`internal/store/captures.go`, mirrors\n`internal/store/events.go`'s pattern):\n\n| column | type | notes |\n| ------------- | ------- | ------------------------------------------------------------------ |\n| id | INTEGER | primary key, autoincrement |\n| received_at | TEXT | RFC3339Nano |\n| source | TEXT | opaque path segment chosen by the sender's operator |\n| remote_addr | TEXT | `RemoteAddr` at capture time |\n| content_type | TEXT | `Content-Type` header |\n| headers | TEXT | JSON, redacted |\n| body | TEXT | JSON, redacted (`webhookguard.RedactPayload`) |\n| authenticated | INTEGER | 0/1; always 0 until a source registers a secret (future: `t2db.4`) |\n\nIndexed on `(source, id)` for per-source listing and pruning, and `id` alone\nfor the global cap.\n\n## Disk-bound mechanics\n\nThree independent bounds, composed, per `webhook-intake-security.md` point 5\nand this bead's own \"capture cannot exhaust disk\" criterion:\n\n1. **Per-request size cap.** The HTTP handler reads the body through\n `http.MaxBytesReader` (256 KiB default, configurable). A single oversized\n POST is rejected (413) before redaction or storage sees it.\n2. **Per-remote-address rate limit.** `webhookguard.RateLimiter`, keyed by\n the request's remote address, applied before the body is even read.\n _Not_ keyed by the `source` path segment: `RateLimiter`'s own doc comment\n states its bucket map assumes a bounded, operator-registered key space,\n never evicted. `source` is exactly the opposite here -- an unregistered,\n attacker-chosen URL segment, since capturing senders with no registration\n yet is this endpoint's entire purpose. Keying on it would let one sendLine truncated
},
{
"url": "/dev/prds/event-sources-and-reactions/",
"title": "Event sources and reactions -- decision",
"section": "PRDs",
"body": "# Event sources and reactions -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-7d5u.1`, blocks `7d5u.2/.3/.4/.5`\n\nAnswers the four questions in `7d5u.1`'s description. Investigated against\nthe actual tree, not designed from scratch: three mechanisms already in this\ncodebase answer most of this, and the job here is picking the right one for\neach question and saying which packages change.\n\n## 1. In-process typed families, not out-of-process dispatch\n\nArchie has no out-of-process extension mechanism. The plugin engine\nrule (`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`,\nmechanically checked by\n`internal/plugin/architecture_test.go`) keeps every capability family\nin-process behind a narrow typed registrar; NATS RPC exists for\ndaemon\u003c-\u003eagentexec, a different actor with a different trust boundary (task\nexecution, not third-party extension code), not a precedent for generic\nplugin dispatch. Neither epic's near-term payoff -- react to a labelled\nissue, bind a captured webhook to a workflow -- needs extension code in\nanother language or process. Building out-of-process dispatch now would be\ndesigning for a requirement neither epic states.\n\n`docs/architecture/plugins-and-extensions.md` does **not** need amending.\nThe line that looked like a blanket ban on hooks (`archie-core-7d5u`'s notes\nrecord the correction) is scoped to Workflow semantics specifically, and\nnothing decided here touches Workflow's ownership of its own contracts.\n\n## 2. Reaction delivery: `internal/eventbus`'s contract, a NEW stream\n\n`internal/eventbus.Publisher`/`Consumer` already has everything a reaction\nneeds: `PublishUnique(subject, idempotencyKey, payload)` for at-least-once\nwithout duplicate enqueue, `Ack`/`Nak` with \"a handler returning an error\ncauses redelivery.\" Do not design new delivery semantics; use this contract.\n\n**Do not reuse the existing `nats.Client` as-is.** `Config.StreamName` and\n`Config.Subjects` are already composition-supplied (\"the bus must not know\nwhich subjects belong to which domain,\" `config.go`), but the\nretention policy is not parameterized: `New` hardcodes\n`Retention: jetstream.WorkQueuePolicy` (`client.go`), the competing-consumer\npolicy correct for `ARCHIE_TASKS` task distribution -- one message, claimed by\nexactly one consumer -- and wrong for reactions. Two independent reactions\nboth wanting to see the same event under `WorkQueuePolicy` hit exactly the\ntrap `CLAUDE.md` already documents: overlapping filter subjects on a\nwork-queue stream mean the second consumer silently gets nothing. Reactions\nneed fan-out, not claim-once, so the client needs retention made a `Config`\nfield (defaulting to `WorkQueuePolicy` so `ARCHIE_TASKS` is\nunaffected), and a second stream (`ARCHIE_REACTIONS` or similar) configured\nunder a fan-out-capable policy, alongside the existing task-distribution\nstream -- not instead of it.\n\nThis is where `7d5u.2`'s embedded-vs-external axis attaches: whichever NATS\ninstance backs `ARCHIE_TASKS` also backs the reaction stream. NATS is not\noptional as a technology -- the choice is only\nwhether it runs as an external server or embedded in-process\n(`github.com/nats-io/nats-server/v2` is already a direct, test-proven\ndependency, just never wired into production startup). `7d5u.2` wires that;\nthis document does not re-decide it.\n\n## 3. Reactions in these two epics are producer-only\n\nNo veto, no mutation of in-flight work. Two existing shapes cover everything\neither epic actually needs, and neither is a hook that can block something\nelse:\n\n- **Cheap wake, no payload.** `internal/domain/curator/wake.go`'s\n `WakeOnPrimaryInput` subscribes to the lossy `events.Bus` and nudges a\n runtime to check sooner; a dropped event only delays a check-in, never\n loses work, because the trigger decision is a deterministic state read at\n pass time, not the event payload. Model any \"check something sooner\"\n reaction on this, unchanged.\n- **Produce new work, real payload.** `daemon.go`'s existing `pollNATS` -\u003e\n `publishTask` path is already exactly a reaction that observes forge state\n and produces a `workintake.TaskEnvelope`. A webhook source is a second\n producer into the same path, not a new capability -- see question 4.\n\nA reaction that can veto or mutate an *in-flight* task (block a PR from\nopening, alter a running stage) is a different, harder problem with its own\nordering and failure semantics, and belongs to `archie-core-h019` (adversarial\nself-review) if and when that epic needs one -- not here. Do not build a\ngeneral block-capable hook mechanism for either epic; nothing in their stated\nscope requires it, and it would duplicate whatever h019 eventually needs.\n\n## 4. No single generic intake interface; each domain keeps its own\n\nA `Source` interface generic enough to cover a forge issue, a chat message,\nand a cron tick wouldLine truncated
"body": "# Event sources and reactions -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-7d5u.1`, blocks `7d5u.2/.3/.4/.5`\n\nAnswers the four questions in `7d5u.1`'s description. Investigated against\nthe actual tree, not designed from scratch: three mechanisms already in this\ncodebase answer most of this, and the job here is picking the right one for\neach question and saying which packages change.\n\n## 1. In-process typed families, not out-of-process dispatch\n\nArchie has no out-of-process extension mechanism. The plugin engine\nrule (`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`,\nmechanically checked by\n`internal/plugin/architecture_test.go`) keeps every capability family\nin-process behind a narrow typed registrar; NATS RPC exists for\ndaemon\u003c-\u003eagentexec, a different actor with a different trust boundary (task\nexecution, not third-party extension code), not a precedent for generic\nplugin dispatch. Neither epic's near-term payoff -- react to a labelled\nissue, bind a captured webhook to a workflow -- needs extension code in\nanother language or process. Building out-of-process dispatch now would be\ndesigning for a requirement neither epic states.\n\n`docs/architecture/plugins-and-extensions.md` does **not** need amending.\nThe line that looked like a blanket ban on hooks (`archie-core-7d5u`'s notes\nrecord the correction) is scoped to Workflow semantics specifically, and\nnothing decided here touches Workflow's ownership of its own contracts.\n\n## 2. Reaction delivery: `internal/eventbus`'s contract, a NEW stream\n\n`internal/eventbus.Publisher`/`Consumer` already has everything a reaction\nneeds: `PublishUnique(subject, idempotencyKey, payload)` for at-least-once\nwithout duplicate enqueue, `Ack`/`Nak` with \"a handler returning an error\ncauses redelivery.\" Do not design new delivery semantics; use this contract.\n\n**Do not reuse the existing `nats.Client` as-is.** `Config.StreamName` and\n`Config.Subjects` are already composition-supplied (\"the bus must not know\nwhich subjects belong to which domain,\" `config.go`), but the\nretention policy is not parameterised: `New` hardcodes\n`Retention: jetstream.WorkQueuePolicy` (`client.go`), the competing-consumer\npolicy correct for `ARCHIE_TASKS` task distribution -- one message, claimed by\nexactly one consumer -- and wrong for reactions. Two independent reactions\nboth wanting to see the same event under `WorkQueuePolicy` hit exactly the\ntrap `CLAUDE.md` already documents: overlapping filter subjects on a\nwork-queue stream mean the second consumer silently gets nothing. Reactions\nneed fan-out, not claim-once, so the client needs retention made a `Config`\nfield (defaulting to `WorkQueuePolicy` so `ARCHIE_TASKS` is\nunaffected), and a second stream (`ARCHIE_REACTIONS` or similar) configured\nunder a fan-out-capable policy, alongside the existing task-distribution\nstream -- not instead of it.\n\nThis is where `7d5u.2`'s embedded-vs-external axis attaches: whichever NATS\ninstance backs `ARCHIE_TASKS` also backs the reaction stream. NATS is not\noptional as a technology -- the choice is only\nwhether it runs as an external server or embedded in-process\n(`github.com/nats-io/nats-server/v2` is already a direct, test-proven\ndependency, just never wired into production startup). `7d5u.2` wires that;\nthis document does not re-decide it.\n\n## 3. Reactions in these two epics are producer-only\n\nNo veto, no mutation of in-flight work. Two existing shapes cover everything\neither epic actually needs, and neither is a hook that can block something\nelse:\n\n- **Cheap wake, no payload.** `internal/domain/curator/wake.go`'s\n `WakeOnPrimaryInput` subscribes to the lossy `events.Bus` and nudges a\n runtime to check sooner; a dropped event only delays a check-in, never\n loses work, because the trigger decision is a deterministic state read at\n pass time, not the event payload. Model any \"check something sooner\"\n reaction on this, unchanged.\n- **Produce new work, real payload.** `daemon.go`'s existing `pollNATS` -\u003e\n `publishTask` path is already exactly a reaction that observes forge state\n and produces a `workintake.TaskEnvelope`. A webhook source is a second\n producer into the same path, not a new capability -- see question 4.\n\nA reaction that can veto or mutate an _in-flight_ task (block a PR from\nopening, alter a running stage) is a different, harder problem with its own\nordering and failure semantics, and belongs to `archie-core-h019` (adversarial\nself-review) if and when that epic needs one -- not here. Do not build a\ngeneral block-capable hook mechanism for either epic; nothing in their stated\nscope requires it, and it would duplicate whatever h019 eventually needs.\n\n## 4. No single generic intake interface; each domain keeps its own\n\nA `Source` interface generic enough to cover a forge issue, a chat message,\nand a cron tick wouldLine truncated
},
{
"url": "/dev/prds/execution-tree-state-machine/",
"title": "Execution tree and enforced state machine",
"section": "PRDs",
"body": "# Execution tree and enforced state machine\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md` (canonical workflow model);\nsettles the \"enforced WorkflowExecution state machine\" item in\n`docs/architecture/migration-decisions.md` section 4.\n**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution),\n`docs/prds/state-store-contract.md` (wire contract and task-scoped grants).\n\n## Decision\n\nA WorkflowExecution becomes the root of a tree of StepExecutions. Every stage\nrun, and every agent call a stage makes, is its own durable record with a\nparent, an attempt, a status and an outcome. Both levels move only through a\ndeclared transition table, enforced by the State Store in the same transaction\nthat writes the audit row and the domain event.\n\n## Problem\n\n- A run is one `tasks` row. The only per-step record is the mutable `stage`\n column, overwritten as `workflow.Run` advances, plus observability events.\n A failed attempt cannot say which step failed or what its children did\n without replaying the event stream.\n- `Store.Transition` guards on the expected `from` status, but any `from` to\n any `to` is accepted. A `queued` to `merged` write succeeds.\n- Stop cancels one context in `daemon.runningTasks`. Nothing persisted says\n which work was in flight, so an agent call that outlives its stage (a\n reviewer, a container) is invisible to the store.\n- `workflow.Run` writes `tc.Store.Update` and discards the error, then emits\n `KindStageStart` separately. State and events can diverge.\n\n## Model\n\n```text\nWorkflowExecution (tasks row, id E)\n└── attempt N\n ├── StepExecution stage \"plan\" depth 0\n ├── StepExecution stage \"implement\" depth 0\n │ └── StepExecution agent \"implement\" depth 1\n └── StepExecution stage \"review\" depth 0\n ├── StepExecution agent \"review:1\" depth 1\n └── StepExecution agent \"review:2\" depth 1\n```\n\n- A StepExecution belongs to exactly one WorkflowExecution and one attempt.\n `parent_id` is null for a stage and names the enclosing StepExecution\n otherwise. Depth is derived from the parent, never supplied by the caller.\n- `kind` is `stage`, `agent` or `call`. A new kind needs a named consumer\n before it is added.\n- A `workflow.call` step (`docs/prds/event-automation.md`) is a `call`\n StepExecution in the caller's tree. The callee is its own\n WorkflowExecution, with its own tree, acting as its own identity, and the\n `call` step records the callee's execution ID. Trees never nest across\n executions, so each run's tree stays inside that run's authority.\n- A retry starts a new attempt. Earlier attempts' StepExecutions are never\n rewritten.\n\n## Transition tables\n\nWorkflowExecution statuses are the existing `taskstate` constants, persisted\nstrings unchanged. `taskstate` gains the one table every writer checks:\n\n| From | To |\n| --------------- | ---------------------------------------------------------- |\n| `queued` | `running`, `closed_wont_do` |\n| `running` | `queued` (crash recovery), `waiting_human`, `pr_open`, `completed`, `parked`, `closed_wont_do` |\n| `waiting_human` | `queued` (approve), `closed_wont_do` |\n| `parked` | `queued` (retry), `dead` (abandon), `closed_wont_do` |\n| `pr_open` | `merged`, `rejected`, `queued` (remediation), `closed_wont_do` |\n| terminal | none |\n\nStepExecution statuses:\n\n| From | To |\n| --------- | ------------------------------------------------------ |\n| `pending` | `running`, `cancelled` |\n| `running` | `succeeded`, `failed`, `cancelled`, `interrupted` |\n| terminal | none |\n\n`interrupted` means the process running the step died or shut down. It is\ndistinct from `cancelled`, which an operator or a parent asked for, and from\n`failed`, which the step reported.\n\nA StepExecution cannot reach `running` while its WorkflowExecution is not\n`running`, and cannot start under a terminal parent.\n\n## Enforcement\n\n- The table lives in `taskstate` (no dependencies), so the store, daemon and\n gateway share one copy.\n- Every store method that changes `tasks.status` checks the table and writes\n the audit and event rows, not only `Transition`. That includes the claim,\n `ParkTask`, `Requeue`, `RetryTask`, `BeginRemediation` and `RecoverStale`\n paths, several of which change status without an audit row.\n- The State Store rejects an illegal transition with a new sentinel,\n `ErrIllegalTransition`, carried across the wire through `mapError` like\n `ErrStaleTransition`. ALine truncated
},
{
"url": "/dev/prds/extensions-center/",
"title": "Extensions center",
"title": "Extensions centre",
"section": "PRDs",
"body": "# Extensions center\n\n**Status:** Draft\n\nEpic: `archie-core-1786637490708-35-38424ead` / GitHub `#56` (\"Replace Skills\nwith a bundled Extensions center\").\n\nSkills, Workflows, and Tools/MCP already exist as separate, working\ninventories with their own APIs (`api_skills.go`, `api_workflows.go`,\nconfig-driven MCP servers) and their own family-owned controller pattern\n(`curator.Registry`, `health.Registry`, `image.Registry`,\n`workflow.Registry` all already prove this shape). `plugin.Plugin`\n(`internal/plugin/plugin.go`) is already metadata-only, per\n`docs/architecture/plugins-and-extensions.md`. None of that is rebuilt here.\nWhat's missing, confirmed by grep, is: any config schema for enabling or\ndisabling a capability, any \"pending restart\" state tracking, and any single\ninventory that reconciles configured/bundled/discovered/active state across\nfamilies. This document decides those three things and the UI surface that\npresents them. It extends `plugins-and-extensions.md` rather than replacing\nit — that doc's decisions (metadata-only `Plugin`, typed capability\nfamilies, no generic dispatch) are unchanged.\n\nOut of scope: any remote or arbitrary-URL plugin installation path (the\nepic's own acceptance criteria forbid this, and `plugin.LoadDir`\n(`plugin.go`) already only reads `~/.config/archie/plugins/*.go` — this\ndocument does not add a fetch-by-URL variant to it).\n\n## Problem\n\n`internal/config/config.go`'s `MCPServer` and `ToolsConfig` structs have no\n`enabled` field (confirmed by the investigation grep). `api_config.go`'s\n`UpdateConfig`/`handleConfigUpdate` seam persists changes but has no state\ndistinguishing \"saved, takes effect now\" from \"saved, needs restart\" — the\nonly existing reload path (`ReloadChannel`, `server.go`) is\nchannel-specific and explicitly does not cover plugins or MCP servers.\n`server.go` already wires five separate optional inventories\n(Workflows, Skills, Curators, Channels, Captures/Mappings/Bindings) as\nindependent fields with no unifying type — an operator has no single\nplace to see \"what's available, what's enabled, what's actually running,\nand what's degraded\" across all of them. `ui/src/` has `settings/`,\n`skills/`, and `workflows/` directories already; there is no\n`ui/src/extensions/`.\n\n## Design\n\n### Unified inventory type\n\n```go\npackage extensions // internal/domain/extensions — new, app-level aggregator\n\ntype State string\n\nconst (\n StateAvailable State = \"available\" // bundled, not configured\n StateEnabled State = \"enabled\" // configured on, not yet live\n StateActive State = \"active\" // configured on and running\n StateDegraded State = \"degraded\" // active but unhealthy\n StateSkipped State = \"skipped\" // optional, disabled by config\n StatePendingRestart State = \"pending_restart\" // config changed, not yet live\n)\n\ntype Entry struct {\n Family string // \"skill\" | \"workflow\" | \"tool\" | \"plugin\" | \"integration\"\n Name string\n Core bool // non-disableable\n State State\n Health string // reuses whatever the family's own registry already reports\n}\n\ntype Inventory interface {\n List(ctx context.Context) ([]Entry, error)\n}\n```\n\n**Decision.** `extensions.Inventory` is a read-only aggregator, not a new\ndomain that owns state. It queries each family's existing registry\n(`curator.Registry`, `health.Registry`, `workflow.Registry`, the MCP client\nset, `plugin.LoadDir`'s result) for live state, and compares that against\nthe config-desired state (below) to compute `StatePendingRestart` — the diff\nis computed on read, not persisted, so there is no new durable state to keep\nconsistent with the registries themselves. This follows\n`migration-decisions.md`'s rule that cross-cutting aggregation composes\nexisting domain-owned contracts rather than duplicating their state.\n\n**Call site.** New package `internal/domain/extensions/inventory.go`.\nComposed in `internal/app/archied` (wherever `server.go`'s other optional\nfields — Workflows, Skills, Curators — are wired) since it needs\nreferences to every family's registry, which only application-layer\ncomposition has.\n\n### Config-backed enablement\n\n**Decision.** Add `enabled bool` (default `true` for pre-existing configured\nentries, so no upgrade silently disables anything already configured) to\neach family's config element: `MCPServer.Enabled`, and equivalent fields on\nwhatever config types back skills/workflows/plugins if they don't already\nhave an on/off switch. Core capabilities (identity, workflow engine, State\nStore connectivity — named in `organisation.md`'s cross-cutting packages)\nhave no `enabled` field at all; a config value can't be added to something\nthat doesn't expose the toggle, which is the \"non-disableable\" property\nenforced structurally rathLine truncated
"body": "# Extensions centre\n\n**Status:** Draft\n\n\u003e Superseded by `docs/prds/store.md`.\n\nEpic: `archie-core-1786637490708-35-38424ead` / GitHub `#56` (\"Replace Skills\nwith a bundled Extensions centre\").\n\nSkills, Workflows, and Tools/MCP already exist as separate, working\ninventories with their own APIs (`api_skills.go`, `api_workflows.go`,\nconfig-driven MCP servers) and their own family-owned controller pattern\n(`curator.Registry`, `health.Registry`, `image.Registry`,\n`workflow.Registry` all already prove this shape). `plugin.Plugin`\n(`internal/plugin/plugin.go`) is already metadata-only, per\n`docs/architecture/plugins-and-extensions.md`. None of that is rebuilt here.\nWhat's missing, confirmed by grep, is: any config schema for enabling or\ndisabling a capability, any \"pending restart\" state tracking, and any single\ninventory that reconciles configured/bundled/discovered/active state across\nfamilies. This document decides those three things and the UI surface that\npresents them. It extends `plugins-and-extensions.md` rather than replacing\nit — that doc's decisions (metadata-only `Plugin`, typed capability\nfamilies, no generic dispatch) are unchanged.\n\nOut of scope: any remote or arbitrary-URL plugin installation path (the\nepic's own acceptance criteria forbid this, and `plugin.LoadDir`\n(`plugin.go`) already only reads `~/.config/archie/plugins/*.go` — this\ndocument does not add a fetch-by-URL variant to it).\n\n## Problem\n\n`internal/config/config.go`'s `MCPServer` and `ToolsConfig` structs have no\n`enabled` field (confirmed by the investigation grep). `api_config.go`'s\n`UpdateConfig`/`handleConfigUpdate` seam persists changes but has no state\ndistinguishing \"saved, takes effect now\" from \"saved, needs restart\" — the\nonly existing reload path (`ReloadChannel`, `server.go`) is\nchannel-specific and explicitly does not cover plugins or MCP servers.\n`server.go` already wires five separate optional inventories\n(Workflows, Skills, Curators, Channels, Captures/Mappings/Bindings) as\nindependent fields with no unifying type — an operator has no single\nplace to see \"what's available, what's enabled, what's actually running,\nand what's degraded\" across all of them. `ui/src/` has `settings/`,\n`skills/`, and `workflows/` directories already; there is no\n`ui/src/extensions/`.\n\n## Design\n\n### Unified inventory type\n\n```go\npackage extensions // internal/domain/extensions — new, app-level aggregator\n\ntype State string\n\nconst (\n StateAvailable State = \"available\" // bundled, not configured\n StateEnabled State = \"enabled\" // configured on, not yet live\n StateActive State = \"active\" // configured on and running\n StateDegraded State = \"degraded\" // active but unhealthy\n StateSkipped State = \"skipped\" // optional, disabled by config\n StatePendingRestart State = \"pending_restart\" // config changed, not yet live\n)\n\ntype Entry struct {\n Family string // \"skill\" | \"workflow\" | \"tool\" | \"plugin\" | \"integration\"\n Name string\n Core bool // non-disableable\n State State\n Health string // reuses whatever the family's own registry already reports\n}\n\ntype Inventory interface {\n List(ctx context.Context) ([]Entry, error)\n}\n```\n\n**Decision.** `extensions.Inventory` is a read-only aggregator, not a new\ndomain that owns state. It queries each family's existing registry\n(`curator.Registry`, `health.Registry`, `workflow.Registry`, the MCP client\nset, `plugin.LoadDir`'s result) for live state, and compares that against\nthe config-desired state (below) to compute `StatePendingRestart` — the diff\nis computed on read, not persisted, so there is no new durable state to keep\nconsistent with the registries themselves. This follows\n`migration-decisions.md`'s rule that cross-cutting aggregation composes\nexisting domain-owned contracts rather than duplicating their state.\n\n**Call site.** New package `internal/domain/extensions/inventory.go`.\nComposed in `internal/app/archied` (wherever `server.go`'s other optional\nfields — Workflows, Skills, Curators — are wired) since it needs\nreferences to every family's registry, which only application-layer\ncomposition has.\n\n### Config-backed enablement\n\n**Decision.** Add `enabled bool` (default `true` for pre-existing configured\nentries, so no upgrade silently disables anything already configured) to\neach family's config element: `MCPServer.Enabled`, and equivalent fields on\nwhatever config types back skills/workflows/plugins if they don't already\nhave an on/off switch. Core capabilities (identity, workflow engine, State\nStore connectivity — named in `organisation.md`'s cross-cutting packages)\nhave no `enabled` field at all; a config value can't be added to something\nthat doesn't expose the toggle, which is the \"non-disaLine truncated
},
{
"url": "/dev/prds/external-agent-harness/",
"title": "External agent harnesses",
"section": "PRDs",
"body": "# External agent harnesses\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md` (agent execution as a data\nboundary); settles the harness non-goal deferred by\n`docs/prds/service-decomposition.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a harness\nrun is one `agent` StepExecution), `docs/prds/binding-secret-encryption.md`\n(the at-rest envelope reused for harness credentials).\n\n## Decision\n\nA workflow stage can run on an external coding-agent CLI instead of the\nbuilt-in agent loop: Claude Code, Codex, Pi, OMP, GitHub Copilot CLI, or any\nother CLI packaged as a Docker Sandbox Kit v3. Each authenticates with an API\nkey or the operator's subscription login, and can carry the operator's own\nskills, plugins, subagents and instructions.\n\nTwo boundaries hold regardless of what the harness does:\n\n- **The real credential never enters the container.** The container sees\n sentinel values; archie's egress proxy substitutes the real credential on\n outbound requests and performs OAuth refresh on the host.\n- **Archie's workflow guarantees are enforced outside the harness.** Git,\n protected paths, read-only stages, gates and budgets are checked by archie\n around the process and against the worktree afterwards.\n\n## Kits\n\nA harness is packaged as a Kit v3 image: an OCI image whose\n`vnd.docker.sandbox.kit.descriptor` manifest annotation declares what the\nharness needs. Archie reads descriptors with the published\n`github.com/docker/sandbox-kit-spec/v3/spec` package and does not maintain\nits own descriptor format. Published Kits run unmodified.\n\nArchie is a partial Kit runtime. It implements these capability types:\n\n| Type | Archie behaviour |\n| ------------------- | ----------------------------------------------------------------------------------------- |\n| `credential@1` | Proxy-managed only, described below. |\n| `network-policy@1` | Enforced by the egress proxy. |\n| `volume@1` | A Docker volume keyed by WorkflowExecution, deleted with it. |\n| `lifecycle@1` | Install and startup hooks run on container create. |\n| `agent-sessions@1` | The headless `prompt` and `resume` invocations for the stage. |\n| `agent-skills@1` | The operator's skills store, mounted read-only whatever the Kit asks. |\n| `agent-context@1` | Archie's stage instructions, delivered where the Kit declares. |\n| `resources@1` | Container CPU and memory limits. |\n\nEvery other type fails closed: a required entry refuses the launch, an\noptional one is skipped and recorded on the step. `credential@1` with\n`passthrough: true` and any credential for a forge service are refused.\n\nThe operator's own setup (plugins, subagents, instructions, settings) is a\nmixin Kit the operator builds `FROM` or alongside the harness Kit. It is\nversioned image content, rewritten on every create, never state a run can\nmodify.\n\n## Contract\n\nA harness run is a second implementation of `agentexec.Runner`. It takes the\nsame `Request` and returns the same `Result`, so workflows, the daemon and\nthe State Store do not know which runner ran a stage.\n\n`agent-sessions@1` supplies the invocation. Archie supplies, per CLI, an\noutput adapter that translates the CLI's JSON output stream into\n`ToolCallReporter` calls, `Usage` and a session ID. A CLI with no adapter can\nrun stages with no capture tools, reporting no usage; its token budget falls\nback to wall clock.\n\nWorkflow definition validation rejects, at load time, a stage whose needs the\nselected harness cannot meet: capture tools without an adapter, or a gate\nretry without a `resume` verb.\n\n## Selection\n\nA harness is an agent profile. `docs/prds/event-automation.md` defines a\nprofile as the execution environment a workflow selects; a harness profile\nnames a Kit composition (the workload Kit pinned by digest, and zero or more\nmixin Kits) in place of a container image. Everything else about profiles\nholds: a workflow names its profile, a stage may name a different one, and a\nprofile holds no secrets.\n\n`archie-agent` builds the stage's runner from the stage's profile: the\nai-sdk agent loop for an image profile, the harness runner for a Kit\nprofile. Image profiles, and every workflow already written against them,\nare unchanged. A Kit profile named by no workflow is a validation error.\n\nProfiles are org resources in the State Store, so a Kit profile belongs to\none org, is granted to its workspaces like any profile, and applies without\na restart.\n\n## Organisations\n\n`docs/prds/Line truncated
},
{
"url": "/dev/prds/identity-decision/",
"title": "Identity for users, agents and external agents — decision",
"section": "PRDs",
"body": "# Identity for users, agents and external agents — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** `docs/architecture/organisation.md` for placement;\n`docs/architecture/migration-decisions.md` §3 for the attribution semantics this\ndocument implements; `docs/prds/agent2agent-protocol.md` for the A2A surface that\nconsumes it.\n\n## Decision\n\nOne identity record covers every actor archie has: users, agents, external agents,\nservice accounts and the system. Authentication is delegated to the estate's OIDC\nprovider, and attribution stays archie's.\n\nAuthentication and authorisation are OSS archie integrates; a design that\nhand-rolls either fails this document.\n\n## The provider\n\n**Authelia is the only identity provider**, because the estate already runs it in\nfront of the dashboard and it issues credentials for both kinds of caller: humans\nuse the authorization code flow, and machines use the `client_credentials` grant,\nwhich yields a token whose subject is the client's own identifier.\n\n**Each agent is its own provider client.** A shared client would make two agents\nindistinguishable in the audit trail and revocable only together, which is the\nproperty attribution needs and the reason per-client registration is a\nrequirement.\n\n**A person's client and an agent's client are registered separately**, because the\ntwo token shapes differ and a shared registration would collapse the distinction\nthe attribution rests on. A person's token names them in `sub`. A machine's token\ncarries no `sub` at all and names its client instead, so a machine identity is keyed\non its client registration and exists one per client. A token asserting neither is\nrefused.\n\n**A person's token requests the audience at the authorisation endpoint**, not only\nat the token endpoint. A provider that otherwise returns the audience empty\nproduces a valid token archie must refuse, and that refusal looks like a signing\nfault rather than a missing request parameter.\n\n**SPIFFE/SPIRE is not adopted.** It is adopted and maintained, and its attestation\nis strictly stronger than a secret: a workload proves what it is rather than what\nit holds. It is rejected here on operational fit, not on quality: it adds a\ncontrol plane archie does not have, and the property it buys — identity attested\nfrom the platform rather than from a presented secret — answers a threat archie\ndoes not face, because archie's agents run as containers the operator launches and\nalready receive their credentials from the daemon that owns them. It is the right\nanswer when agents run on infrastructure the operator does not control.\n\n## What archie owns\n\n- **The identity record.** `internal/domain/identity` survives as archie's own\n record of an actor and is not replaced by the provider's directory, because the\n record carries what the directory does not: the lifecycle, the bindings and the\n attribution below.\n- **The lifecycle.** Active, suspended and retired, with rename, suspend,\n reactivate and retire, remain archie's. Suspending an identity must stop it\n acting whether or not the provider still authenticates it.\n- **The subject binding.** An identity that proves itself is bound to the provider\n subject that asserts it. This is the same bridge `identity_aliases` already\n provides from a legacy name to an identity, so the second binding is the same\n mechanism rather than a new one.\n- **Attribution.** Who acted, and under whose authority.\n- **The audit trail of identity changes**, which already records an actor, a source\n and a request identifier for every mutation.\n\n## What archie never owns\n\nA credential, a password, a session, a token, a signing key, a second-factor\nenrollment, or a permission rule.\n\n## How an agent proves who it is\n\n**An agent authenticates by presenting a token the provider issued to its own\nclient**, and archie validates it against the provider's published signing keys and\ntakes its subject as the acting identity. The agent holds a client secret; archie\nholds only the public keys, so a compromised archie cannot mint an identity.\n\n**A WebMCP tool call is not a proof of agent identity and cannot be made one.** A\npage can invoke its own tools, so an agent's call and a page script's call arrive\nat archie identically. No field, header or convention distinguishes them, because\nthe difference does not exist on the wire.\n\n**A WebMCP tool call is therefore attributed to the identity the request\npresented, with its source recorded as a hint.** It may record that the request\ncame from the dashboard; it never records that an agent acted, and it never\nrecords that a human approved. A tool call that a page script can forge must not\nbe the thing an audit trail rests on.\n\n**Agent-initiated action therefore arrives on a surface that carries a credential**\n— the A2A surface, or an authenticated agent call — because that is the only place\nan agent'sLine truncated
"body": "# Identity for users, agents and external agents — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** `docs/architecture/organisation.md` for placement;\n`docs/architecture/migration-decisions.md` §3 for the attribution semantics this\ndocument implements; `docs/prds/agent2agent-protocol.md` for the A2A surface that\nconsumes it.\n\n## Decision\n\nOne identity record covers every actor archie has: users, agents, external agents,\nservice accounts and the system. Authentication is delegated to the estate's OIDC\nprovider, and attribution stays archie's.\n\nAuthentication and authorisation are OSS archie integrates; a design that\nhand-rolls either fails this document.\n\n## The provider\n\n**Authelia is the only identity provider**, because the estate already runs it in\nfront of the dashboard and it issues credentials for both kinds of caller: humans\nuse the authorisation code flow, and machines use the `client_credentials` grant,\nwhich yields a token whose subject is the client's own identifier.\n\n**Each agent is its own provider client.** A shared client would make two agents\nindistinguishable in the audit trail and revocable only together, which is the\nproperty attribution needs and the reason per-client registration is a\nrequirement.\n\n**A person's client and an agent's client are registered separately**, because the\ntwo token shapes differ and a shared registration would collapse the distinction\nthe attribution rests on. A person's token names them in `sub`. A machine's token\ncarries no `sub` at all and names its client instead, so a machine identity is keyed\non its client registration and exists one per client. A token asserting neither is\nrefused.\n\n**A person's token requests the audience at the authorisation endpoint**, not only\nat the token endpoint. A provider that otherwise returns the audience empty\nproduces a valid token archie must refuse, and that refusal looks like a signing\nfault rather than a missing request parameter.\n\n**SPIFFE/SPIRE is not adopted.** It is adopted and maintained, and its attestation\nis strictly stronger than a secret: a workload proves what it is rather than what\nit holds. It is rejected here on operational fit, not on quality: it adds a\ncontrol plane archie does not have, and the property it buys — identity attested\nfrom the platform rather than from a presented secret — answers a threat archie\ndoes not face, because archie's agents run as containers the operator launches and\nalready receive their credentials from the daemon that owns them. It is the right\nanswer when agents run on infrastructure the operator does not control.\n\n## What archie owns\n\n- **The identity record.** `internal/domain/identity` survives as archie's own\n record of an actor and is not replaced by the provider's directory, because the\n record carries what the directory does not: the lifecycle, the bindings and the\n attribution below.\n- **The lifecycle.** Active, suspended and retired, with rename, suspend,\n reactivate and retire, remain archie's. Suspending an identity must stop it\n acting whether or not the provider still authenticates it.\n- **The subject binding.** An identity that proves itself is bound to the provider\n subject that asserts it. This is the same bridge `identity_aliases` already\n provides from a legacy name to an identity, so the second binding is the same\n mechanism rather than a new one.\n- **Attribution.** Who acted, and under whose authority.\n- **The audit trail of identity changes**, which already records an actor, a source\n and a request identifier for every mutation.\n\n## What archie never owns\n\nA credential, a password, a session, a token, a signing key, a second-factor\nenrolment, or a permission rule.\n\n## How an agent proves who it is\n\n**An agent authenticates by presenting a token the provider issued to its own\nclient**, and archie validates it against the provider's published signing keys and\ntakes its subject as the acting identity. The agent holds a client secret; archie\nholds only the public keys, so a compromised archie cannot mint an identity.\n\n**A WebMCP tool call is not a proof of agent identity and cannot be made one.** A\npage can invoke its own tools, so an agent's call and a page script's call arrive\nat archie identically. No field, header or convention distinguishes them, because\nthe difference does not exist on the wire.\n\n**A WebMCP tool call is therefore attributed to the identity the request\npresented, with its source recorded as a hint.** It may record that the request\ncame from the dashboard; it never records that an agent acted, and it never\nrecords that a human approved. A tool call that a page script can forge must not\nbe the thing an audit trail rests on.\n\n**Agent-initiated action therefore arrives on a surface that carries a credential**\n— the A2A surface, or an authenticated agent call — because that is the only place\nan agent's Line truncated
},
{
"url": "/dev/prds/image-capability-contract/",
"title": "Image capability contract and configuration",
"section": "PRDs",
"body": "# Image capability contract and configuration\n\n**Status:** Approved\n\nEpic: archie-core-1786748942120-1-6636e629 / GitHub #496 (\"Image generation\ncapability: hosted API baseline plus local GPU workflows\").\n\nThe contract and configuration (#497) shipped first and is settled — see\n\"Package: `internal/domain/image`\" below. This document now covers the full\nfeature set: hosted provider (#498), local GPU provider (#499), `/image`\nrouting and clarification (#500), delivery through channels and web (#501).\nDocumentation (#502) and the cross-cutting test matrix (#503) are execution\nwork against the design below, not open design questions, so they are not\ngiven their own sections — each preceding section states its own test\nobligations inline.\n\n## Problem\n\nArchie needs a provider-neutral boundary for image generation/editing so a\nhosted API (gpt-image-2-class) and a future local GPU backend can both\nimplement it without either one leaking into the domain contract. Nothing\nin the repo defines this (`grep -ri image` over `internal/domain` and\n`internal/config` returns nothing image-specific).\n\n## Design\n\nFollows the plugin engine family shape already established by\n`internal/domain/curator` and `internal/domain/memory`\n(`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`): a\ntyped contract with real domain operations,\nan owning `Registry` (register/get/names, no start/stop lifecycle — see\nbelow), and narrow host access via a `Registrar`.\n\n### Package: `internal/domain/image`\n\n**Why no `Lifecycle` (`Start/Health/Stop`)**: curator and memory engines are\nlong-running — they hold a background cadence or a persistent connection\nworth health-checking. An image provider is call-scoped: it either serves a\n`Generate`/`Edit` request or it does not. Health here means \"is this\nprovider usable at call time\", which is exactly what `Generate`/`Edit`\nreturning a typed `ErrUnavailable` already communicates — a separate\n`Health()` poll would just duplicate that. `Registry` still owns\nregistration and lookup, so provider selection is testable with fakes per\nthe acceptance criteria, but there is no `Start`/`Stop` to orchestrate.\n\n```go\n// Capability declares what one provider supports, discoverable before a\n// request is built so a caller can reject an unsupported combination (e.g.\n// edit-with-mask on a generate-only provider) instead of sending it and\n// parsing a provider-specific error back out.\ntype Capability struct {\n Generate bool\n Edit bool // edit requires at least one input image\n Mask bool // edit supports a mask restricting the edited region\n MaxInputs int // 0 = Edit unsupported\n Sizes []string // provider-declared output sizes, e.g. \"1024x1024\"\n}\n\n// Provider is the typed contract every image backend implements — hosted\n// (gpt-image-2-class) or local (GPU recipe). No Lifecycle: a provider is\n// call-scoped, not long-running (see design doc rationale).\ntype Provider interface {\n Name() string\n // Class distinguishes hosted (spends money/quota per call) from local\n // (spends host GPU/time). Selection logic and config validation key off\n // this, never off Name, so a new provider cannot silently slip through\n // the hosted-cost gate under an unrecognized name.\n Class() ProviderClass\n Capability() Capability\n Generate(ctx context.Context, req GenerateRequest) (Result, error)\n Edit(ctx context.Context, req EditRequest) (Result, error)\n}\n\ntype ProviderClass string\n\nconst (\n ClassHosted ProviderClass = \"hosted\"\n ClassLocal ProviderClass = \"local\"\n)\n```\n\nRequest/result types (provider-neutral, no OpenAI types):\n\n```go\ntype GenerateRequest struct {\n Prompt string\n Size string // \"\" = provider default\n N int // number of images; 0 = 1\n Options map[string]string // provider-specific overflow (e.g. \"quality\"),\n // deliberately untyped so the contract does not\n // grow a field per provider\n}\n\ntype EditRequest struct {\n Prompt string\n Inputs []ImageData // 1..Capability.MaxInputs\n Mask *ImageData // nil unless Capability.Mask\n Size string\n N int\n Options map[string]string\n}\n\n// ImageData carries image bytes in-process, never a path or URL: the\n// domain layer must not assume a filesystem or a fetchable location (mirrors\n// why curator's Registrar never receives *daemon.Daemon — no ambient host\n// access smuggled in through a \"just a string\" field).\ntype ImageData struct {\n Bytes []byte\n MIMEType string\n}\n\ntype Result struct {\n Images []ImageData\n Provider string\n Model string\n CreatedAt time.Time\n}\n```\n\n### Error taxonomy\n\n```go\nvar (\n ErrUnavailable = errors.New(\"image provider unavailable\") // missing credential, backLine truncated
"body": "# Image capability contract and configuration\n\n**Status:** Approved\n\nEpic: archie-core-1786748942120-1-6636e629 / GitHub #496 (\"Image generation\ncapability: hosted API baseline plus local GPU workflows\").\n\nThe contract and configuration (#497) shipped first and is settled — see\n\"Package: `internal/domain/image`\" below. This document now covers the full\nfeature set: hosted provider (#498), local GPU provider (#499), `/image`\nrouting and clarification (#500), delivery through channels and web (#501).\nDocumentation (#502) and the cross-cutting test matrix (#503) are execution\nwork against the design below, not open design questions, so they are not\ngiven their own sections — each preceding section states its own test\nobligations inline.\n\n## Problem\n\nArchie needs a provider-neutral boundary for image generation/editing so a\nhosted API (gpt-image-2-class) and a future local GPU backend can both\nimplement it without either one leaking into the domain contract. Nothing\nin the repo defines this (`grep -ri image` over `internal/domain` and\n`internal/config` returns nothing image-specific).\n\n## Design\n\nFollows the plugin engine family shape already established by\n`internal/domain/curator` and `internal/domain/memory`\n(`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`): a\ntyped contract with real domain operations,\nan owning `Registry` (register/get/names, no start/stop lifecycle — see\nbelow), and narrow host access via a `Registrar`.\n\n### Package: `internal/domain/image`\n\n**Why no `Lifecycle` (`Start/Health/Stop`)**: curator and memory engines are\nlong-running — they hold a background cadence or a persistent connection\nworth health-checking. An image provider is call-scoped: it either serves a\n`Generate`/`Edit` request or it does not. Health here means \"is this\nprovider usable at call time\", which is exactly what `Generate`/`Edit`\nreturning a typed `ErrUnavailable` already communicates — a separate\n`Health()` poll would just duplicate that. `Registry` still owns\nregistration and lookup, so provider selection is testable with fakes per\nthe acceptance criteria, but there is no `Start`/`Stop` to orchestrate.\n\n```go\n// Capability declares what one provider supports, discoverable before a\n// request is built so a caller can reject an unsupported combination (e.g.\n// edit-with-mask on a generate-only provider) instead of sending it and\n// parsing a provider-specific error back out.\ntype Capability struct {\n Generate bool\n Edit bool // edit requires at least one input image\n Mask bool // edit supports a mask restricting the edited region\n MaxInputs int // 0 = Edit unsupported\n Sizes []string // provider-declared output sizes, e.g. \"1024x1024\"\n}\n\n// Provider is the typed contract every image backend implements — hosted\n// (gpt-image-2-class) or local (GPU recipe). No Lifecycle: a provider is\n// call-scoped, not long-running (see design doc rationale).\ntype Provider interface {\n Name() string\n // Class distinguishes hosted (spends money/quota per call) from local\n // (spends host GPU/time). Selection logic and config validation key off\n // this, never off Name, so a new provider cannot silently slip through\n // the hosted-cost gate under an unrecognized name.\n Class() ProviderClass\n Capability() Capability\n Generate(ctx context.Context, req GenerateRequest) (Result, error)\n Edit(ctx context.Context, req EditRequest) (Result, error)\n}\n\ntype ProviderClass string\n\nconst (\n ClassHosted ProviderClass = \"hosted\"\n ClassLocal ProviderClass = \"local\"\n)\n```\n\nRequest/result types (provider-neutral, no OpenAI types):\n\n```go\ntype GenerateRequest struct {\n Prompt string\n Size string // \"\" = provider default\n N int // number of images; 0 = 1\n Options map[string]string // provider-specific overflow (e.g. \"quality\"),\n // deliberately untyped so the contract does not\n // grow a field per provider\n}\n\ntype EditRequest struct {\n Prompt string\n Inputs []ImageData // 1..Capability.MaxInputs\n Mask *ImageData // nil unless Capability.Mask\n Size string\n N int\n Options map[string]string\n}\n\n// ImageData carries image bytes in-process, never a path or URL: the\n// domain layer must not assume a filesystem or a fetchable location (mirrors\n// why curator's Registrar never receives *daemon.Daemon — no ambient host\n// access smuggled in through a \"just a string\" field).\ntype ImageData struct {\n Bytes []byte\n MIMEType string\n}\n\ntype Result struct {\n Images []ImageData\n Provider string\n Model string\n CreatedAt time.Time\n}\n```\n\n### Error taxonomy\n\n```go\nvar (\n ErrUnavailable = errors.New(\"image provider unavailable\") // missing credential, backLine truncated
},
{
"url": "/dev/prds/inline-review/",
"title": "Inline review -- decision",
"section": "PRDs",
"body": "# Inline review -- decision\n\n**Status:** Finalised\n**Beads issue:** `archie-core-q9au`\n**Builds on:** `archie-core-h019` (adversarial self-review), `docs/architecture/adversarial-review.md`\n\n## Problem\n\nFindings reach the operator only as a flat list in the PR body\n(`renderPRReviewSection`, h019.6): `` - `file.go` (confirmed, error): \u003cdefect\u003e\n— \u003cscenario\u003e ``. That is a report *about* the code, not a review *of* it. A real\nreviewer anchors each finding to the line it is about, so the author sees it in\ncontext — and, when the fix is mechanical, attaches the replacement so it can be\napplied in one click.\n\nBoth halves are missing:\n\n- **No line-anchored comment.** `forge.Forge.Comment` posts to the PR\n *conversation* (`Issues.CreateComment`); nothing creates a review comment at\n `path` + `line`.\n- **No suggested fix.** `ReviewFinding` carries `File`/`Line`/`Defect`/\n `FailureScenario`/`Verdict`/`Level`/`Category` — no replacement code, so even\n an anchored comment could only describe the fix, not offer it.\n\n## Decisions\n\n### 1. A narrow, type-asserted write surface\n\nThe set of comments travels in one call, so a forge that can only carry them on\na submitted review needs one request rather than one per finding:\n\n```go\ntype ReviewCommentWriter interface {\n CreateReviewComments(ctx context.Context, owner, repo string, number int,\n comments []InlineReviewComment) error\n}\n```\n\nType-asserted like `PullRequestReader`/`PullRequestReviewReader`, so a forge\nthat cannot do it is skipped rather than faked. The stage reaches it through\n`workflow.Forger`, whose production implementation is `forgerpc.Client` — the\nworker holds no forge credentials, so the daemon's forgerpc server type-asserts\n`forge.ReviewCommentWriter` and answers an incapable forge with an error the\nbest-effort stage logs.\n\nThe comment's line is anchored to the pull request's **current head revision**,\nresolved inside each implementation rather than passed in by the caller: it is\nthe revision the comments are attached to, and the caller that produced the line\nnumbers holds no forge credentials to read it. The caller does pass the revision\nthose line numbers were **measured on** (`TaskContext.ReviewedHeadSHA`,\nrecorded when `StageOpenPR` opens the pull request), and the implementation\nposts only while the head it read still matches it — see §4.\n\nPer-forge reality, verified against the SDKs:\n\n- **GitHub** — direct: `PullRequests.CreateComment` with\n `{Body, Path, Line, Side: \"RIGHT\", CommitID}`.\n- **Gitea** — no direct inline-comment call. Inline comments ride on a submitted\n review (`CreatePullReview` with `Comments` and a `COMMENT` state). The Gitea\n implementation therefore submits a single `COMMENT`-state review carrying the\n findings, or the capability is simply absent (the type assertion skips it).\n Decided: implement Gitea as a `COMMENT`-state review; do not block the feature\n on it.\n\n### 2. `Suggestion`, and only on confirmed findings\n\n`ReviewFinding` gains an optional `Suggestion string` — the replacement text for\nthe anchored line, rendered as a fenced `suggestion` block (GitHub's one-click\n\"Commit suggestion\").\n\n**Only `confirmed` findings may carry one.** A wrong suggestion is a\none-click path to breaking code a reviewer then has to notice; `confirmed` is by\ndefinition the verdict the reviewer traced and can state the failure for. A\n`plausible` finding is a worry, and a worry gets a sentence, not a patch. This is\nthe h019.5 calibration rule reused, not a new one.\n\n`Suggestion` replaces the anchored line exactly, and is only rendered when\n`Verdict == confirmed`. Single-line only in this cut;\nmulti-line (GitHub's `StartLine`/`StartSide`) is a follow-up, because a\nmulti-line suggestion that is off by one line silently corrupts the file. The\nrule is enforced in `ReviewFinding.Validate` — an embedded newline is rejected\nthere, so the `record_finding` tool refuses it with feedback the model can act\non, rather than the renderer silently posting a fence that applies only its\nfirst line.\n\n### 3. Which findings are posted inline\n\nOnly findings that are **line-anchored** (`Line \u003e 0`). A whole-file finding\n(`Line == 0`, e.g. \"README.md is stale\") has no line to attach to and stays in\nthe PR-body list. The body section keeps listing everything, so it remains the\ncomplete record and the fallback.\n\nFindings that block never reach this path: a surviving blocking finding parks\nthe task before `StageOpenPR`, so there is no PR to comment on. Inline comments\nare the non-blocking, line-anchored subset — which is exactly the set that would\notherwise be a body-only list the author has to map back to lines by hand.\n\n### 4. A best-effort stage after `StageOpenPR`\n\nNew `StagePostReviewComments`, after `StageOpenPR`:\n\n1. Read the report stashed by `StageReview` (`tc.ReviewReport`, h019.6).\Line truncated
"body": "# Inline review -- decision\n\n**Status:** Finalised\n**Beads issue:** `archie-core-q9au`\n**Builds on:** `archie-core-h019` (adversarial self-review), `docs/architecture/adversarial-review.md`\n\n## Problem\n\nFindings reach the operator only as a flat list in the PR body\n(`renderPRReviewSection`, h019.6): ``- `file.go` (confirmed, error): \u003cdefect\u003e\n— \u003cscenario\u003e``. That is a report _about_ the code, not a review _of_ it. A real\nreviewer anchors each finding to the line it is about, so the author sees it in\ncontext — and, when the fix is mechanical, attaches the replacement so it can be\napplied in one click.\n\nBoth halves are missing:\n\n- **No line-anchored comment.** `forge.Forge.Comment` posts to the PR\n _conversation_ (`Issues.CreateComment`); nothing creates a review comment at\n `path` + `line`.\n- **No suggested fix.** `ReviewFinding` carries `File`/`Line`/`Defect`/\n `FailureScenario`/`Verdict`/`Level`/`Category` — no replacement code, so even\n an anchored comment could only describe the fix, not offer it.\n\n## Decisions\n\n### 1. A narrow, type-asserted write surface\n\nThe set of comments travels in one call, so a forge that can only carry them on\na submitted review needs one request rather than one per finding:\n\n```go\ntype ReviewCommentWriter interface {\n CreateReviewComments(ctx context.Context, owner, repo string, number int,\n comments []InlineReviewComment) error\n}\n```\n\nType-asserted like `PullRequestReader`/`PullRequestReviewReader`, so a forge\nthat cannot do it is skipped rather than faked. The stage reaches it through\n`workflow.Forger`, whose production implementation is `forgerpc.Client` — the\nworker holds no forge credentials, so the daemon's forgerpc server type-asserts\n`forge.ReviewCommentWriter` and answers an incapable forge with an error the\nbest-effort stage logs.\n\nThe comment's line is anchored to the pull request's **current head revision**,\nresolved inside each implementation rather than passed in by the caller: it is\nthe revision the comments are attached to, and the caller that produced the line\nnumbers holds no forge credentials to read it. The caller does pass the revision\nthose line numbers were **measured on** (`TaskContext.ReviewedHeadSHA`,\nrecorded when `StageOpenPR` opens the pull request), and the implementation\nposts only while the head it read still matches it — see §4.\n\nPer-forge reality, verified against the SDKs:\n\n- **GitHub** — direct: `PullRequests.CreateComment` with\n `{Body, Path, Line, Side: \"RIGHT\", CommitID}`.\n- **Gitea** — no direct inline-comment call. Inline comments ride on a submitted\n review (`CreatePullReview` with `Comments` and a `COMMENT` state). The Gitea\n implementation therefore submits a single `COMMENT`-state review carrying the\n findings, or the capability is simply absent (the type assertion skips it).\n Decided: implement Gitea as a `COMMENT`-state review; do not block the feature\n on it.\n\n### 2. `Suggestion`, and only on confirmed findings\n\n`ReviewFinding` gains an optional `Suggestion string` — the replacement text for\nthe anchored line, rendered as a fenced `suggestion` block (GitHub's one-click\n\"Commit suggestion\").\n\n**Only `confirmed` findings may carry one.** A wrong suggestion is a\none-click path to breaking code a reviewer then has to notice; `confirmed` is by\ndefinition the verdict the reviewer traced and can state the failure for. A\n`plausible` finding is a worry, and a worry gets a sentence, not a patch. This is\nthe h019.5 calibration rule reused, not a new one.\n\n`Suggestion` replaces the anchored line exactly, and is only rendered when\n`Verdict == confirmed`. Single-line only in this cut;\nmulti-line (GitHub's `StartLine`/`StartSide`) is a follow-up, because a\nmulti-line suggestion that is off by one line silently corrupts the file. The\nrule is enforced in `ReviewFinding.Validate` — an embedded newline is rejected\nthere, so the `record_finding` tool refuses it with feedback the model can act\non, rather than the renderer silently posting a fence that applies only its\nfirst line.\n\n### 3. Which findings are posted inline\n\nOnly findings that are **line-anchored** (`Line \u003e 0`). A whole-file finding\n(`Line == 0`, e.g. \"README.md is stale\") has no line to attach to and stays in\nthe PR-body list. The body section keeps listing everything, so it remains the\ncomplete record and the fallback.\n\nFindings that block never reach this path: a surviving blocking finding parks\nthe task before `StageOpenPR`, so there is no PR to comment on. Inline comments\nare the non-blocking, line-anchored subset — which is exactly the set that would\notherwise be a body-only list the author has to map back to lines by hand.\n\n### 4. A best-effort stage after `StageOpenPR`\n\nNew `StagePostReviewComments`, after `StageOpenPR`:\n\n1. Read the report stashed by `StageReview` (`tc.ReviewReport`, h019.6).\n2Line truncated
},
{
"url": "/dev/prds/mcp-tool-completion/",
"title": "MCP client and tool-guardrail completion",
"section": "PRDs",
"body": "# MCP client and tool-guardrail completion\n\n**Status:** Approved\n\nEpic: `archie-core-1786637493439-140-2cee2e9b` / GitHub `#161` (\"[EPIC] Tools:\ncentral registry, MCP client, guardrails\").\n\nThis document is scoped to five sub-features of that epic: MCP\nserver-initiated sampling, the per-server parallel-tool-calls flag, sandboxed\nMCP tool servers, a Firecracker sandbox backend, and sequential dispatch with\nper-result previews.\n\nOut of scope, and not to be touched: the central registry\n(`internal/tools/registry.go`), all three MCP transports (stdio/HTTP/SSE,\n`internal/tools/mcp/transport*.go`), reconnect-with-backoff\n(`transport.go`), guardrail loop detection\n(`internal/tools/guardrail.go`), idempotent/mutating classification\n(`internal/tools/classification.go`), concurrent tool dispatch (`#183`), and\nprogressive disclosure wiring (`internal/app/archied`). These are settled and\nproduction-wired.\n\n## Problem\n\n`bd search \"MCP client\"` shows five closed transport beads and one open:\nserver-initiated sampling (`#151`). `internal/tools/mcp/client.go`\nholds a single `callMu *sync.Mutex` that serializes every `tools/call`\nregardless of server — `ParallelToolCalls` does not exist on the `MCPServer`\nconfig struct (`internal/config/config.go`), confirming `#177` is a\nreal gap, not a stale bead. `#178` (wire MCP tool servers for the chat agent,\nsandboxed) and `#179` (Firecracker substrate) have no corresponding code —\nMCP servers run as whatever the config's `Command`/`Args` launches,\nunsandboxed. `#182` (sequential tool dispatch with per-result previews) is\nopen; concurrent dispatch (`#183`) is closed, so there are two dispatch paths\nand this PRD decides how they coexist.\n\n## Design\n\nSub-features are independent; there is no new shared type this document\nintroduces. Each section below stands alone.\n\n## MCP server-initiated sampling (`#151`)\n\n**Decision.** Implement as a callback on `mcp.Client`, not a second\ntransport. The MCP spec's `sampling/createMessage` request flows server→client\nover the same connection each transport already maintains\n(`transport.go`'s stdio/HTTP/SSE all multiplex request and response frames).\nAdd a `SamplingHandler func(context.Context, SamplingRequest) (SamplingResult, error)`\nfield to the client's config struct next to the existing transport fields,\ndefaulting to nil (server sampling requests get a JSON-RPC \"not supported\"\nerror when unset — never a silent drop).\n\n**Call site.** `internal/tools/mcp/client.go` — add the handler field and a\ndispatch branch in whatever function demuxes incoming server\nmessages by method name (the same switch that already routes\n`notifications/*`). Wire a concrete handler in\n`internal/app/archied/main.go` that routes the sampling request through the\nsame chat-model call path `chatGenerateOptions` already uses, so a\nserver-initiated sample gets the daemon's configured model, not a second\nprovider client.\n\n**Reuse check.** The chat model invocation path already exists\n(`chatGenerateOptions`, `main.go`); this reuses it rather than adding a\nparallel model-calling path for MCP sampling.\n\n**Failure mapping.**\n\n| condition | contract error |\n|---|---|\n| no `SamplingHandler` configured | JSON-RPC method-not-found, per spec |\n| handler returns error | JSON-RPC internal error, message from handler |\n| handler timeout | JSON-RPC timeout error; use the transport's existing request-timeout config, not a new one |\n\n**Testing.** Fakeable entirely — a stub `SamplingHandler` and a fake\ntransport that emits a `sampling/createMessage` frame. No real backend\nneeded; belongs in `task check`.\n\n## Per-server parallel-tool-calls flag (`#177`)\n\n**Decision.** `ParallelToolCalls bool` (default `false`) goes on `MCPServer`\nin `internal/config/config.go`, next to `Transport`/`Command`. The\nmutex in `client.go` becomes per-server: when `ParallelToolCalls` is\nfalse (default, and the only behavior), keep the single `callMu`\nserializing that server's calls exactly as now; when true, drop the mutex for\nthat server's `Client` instance entirely and let the caller's own\nconcurrency (already proven by the closed concurrent-dispatch bead, `#183`)\nhandle it. This is additive — no server's behavior changes unless an operator\nopts in.\n\n**Call site.** `internal/config/config.go` (struct field),\n`internal/tools/mcp/client.go` (make the mutex conditional on the\nfield), and wherever `MCPServer` configs are turned into `Client` instances\nat daemon startup (the constructor that reads `internal/config`'s MCP block).\n`config.example.toml`'s commented MCP block gets the new field documented\nwith its default.\n\n**Testing.** Unit test asserting two concurrent `Call`s to the same\n`Client` block on each other when the flag is false and don't when true —\nfakeable with a slow fake transport. `task check`.\n\n## Sandboxed MCP tool servers for the chat agent (`#178`) and Firecracker substLine truncated
"body": "# MCP client and tool-guardrail completion\n\n**Status:** Approved\n\nEpic: `archie-core-1786637493439-140-2cee2e9b` / GitHub `#161` (\"[EPIC] Tools:\ncentral registry, MCP client, guardrails\").\n\nThis document is scoped to five sub-features of that epic: MCP\nserver-initiated sampling, the per-server parallel-tool-calls flag, sandboxed\nMCP tool servers, a Firecracker sandbox backend, and sequential dispatch with\nper-result previews.\n\nOut of scope, and not to be touched: the central registry\n(`internal/tools/registry.go`), all three MCP transports (stdio/HTTP/SSE,\n`internal/tools/mcp/transport*.go`), reconnect-with-backoff\n(`transport.go`), guardrail loop detection\n(`internal/tools/guardrail.go`), idempotent/mutating classification\n(`internal/tools/classification.go`), concurrent tool dispatch (`#183`), and\nprogressive disclosure wiring (`internal/app/archied`). These are settled and\nproduction-wired.\n\n## Problem\n\n`bd search \"MCP client\"` shows five closed transport beads and one open:\nserver-initiated sampling (`#151`). `internal/tools/mcp/client.go`\nholds a single `callMu *sync.Mutex` that serialises every `tools/call`\nregardless of server — `ParallelToolCalls` does not exist on the `MCPServer`\nconfig struct (`internal/config/config.go`), confirming `#177` is a\nreal gap, not a stale bead. `#178` (wire MCP tool servers for the chat agent,\nsandboxed) and `#179` (Firecracker substrate) have no corresponding code —\nMCP servers run as whatever the config's `Command`/`Args` launches,\nunsandboxed. `#182` (sequential tool dispatch with per-result previews) is\nopen; concurrent dispatch (`#183`) is closed, so there are two dispatch paths\nand this PRD decides how they coexist.\n\n## Design\n\nSub-features are independent; there is no new shared type this document\nintroduces. Each section below stands alone.\n\n## MCP server-initiated sampling (`#151`)\n\n**Decision.** Implement as a callback on `mcp.Client`, not a second\ntransport. The MCP spec's `sampling/createMessage` request flows server→client\nover the same connection each transport already maintains\n(`transport.go`'s stdio/HTTP/SSE all multiplex request and response frames).\nAdd a `SamplingHandler func(context.Context, SamplingRequest) (SamplingResult, error)`\nfield to the client's config struct next to the existing transport fields,\ndefaulting to nil (server sampling requests get a JSON-RPC \"not supported\"\nerror when unset — never a silent drop).\n\n**Call site.** `internal/tools/mcp/client.go` — add the handler field and a\ndispatch branch in whatever function demuxes incoming server\nmessages by method name (the same switch that already routes\n`notifications/*`). Wire a concrete handler in\n`internal/app/archied/main.go` that routes the sampling request through the\nsame chat-model call path `chatGenerateOptions` already uses, so a\nserver-initiated sample gets the daemon's configured model, not a second\nprovider client.\n\n**Reuse check.** The chat model invocation path already exists\n(`chatGenerateOptions`, `main.go`); this reuses it rather than adding a\nparallel model-calling path for MCP sampling.\n\n**Failure mapping.**\n\n| condition | contract error |\n| ------------------------------- | ------------------------------------------------------------------------------------------ |\n| no `SamplingHandler` configured | JSON-RPC method-not-found, per spec |\n| handler returns error | JSON-RPC internal error, message from handler |\n| handler timeout | JSON-RPC timeout error; use the transport's existing request-timeout config, not a new one |\n\n**Testing.** Fakeable entirely — a stub `SamplingHandler` and a fake\ntransport that emits a `sampling/createMessage` frame. No real backend\nneeded; belongs in `task check`.\n\n## Per-server parallel-tool-calls flag (`#177`)\n\n**Decision.** `ParallelToolCalls bool` (default `false`) goes on `MCPServer`\nin `internal/config/config.go`, next to `Transport`/`Command`. The\nmutex in `client.go` becomes per-server: when `ParallelToolCalls` is\nfalse (default, and the only behaviour), keep the single `callMu`\nserialising that server's calls exactly as now; when true, drop the mutex for\nthat server's `Client` instance entirely and let the caller's own\nconcurrency (already proven by the closed concurrent-dispatch bead, `#183`)\nhandle it. This is additive — no server's behaviour changes unless an operator\nopts in.\n\n**Call site.** `internal/config/config.go` (struct field),\n`internal/tools/mcp/client.go` (make the mutex conditional on the\nfield), and wherever `MCPServer` configs are turned into `Client` instances\nat daemon startup (the constructor that reads `internal/config`'s MCP block).\n`config.example.toml`'s commenLine truncated
},
{
"url": "/dev/prds/memory-engine-unification/",
"title": "Memory engine unification: four scopes, CRUD, and one write path -- decision",
"section": "PRDs",
"body": "# Memory engine unification: four scopes, CRUD, and one write path -- decision\n\n**Status:** Approved\n**Date:** 2026-09-16\n**Findings:** `memory-4` and its dependants in the adversarial sweep\n(`.local/issue-tracker`); the real defect is the split described below, for\nwhich `memory-4` is a symptom\n**Supersedes:** the draft `memory-turn-context.md` (its synchronous-read\nargument survives and is reused; its `Manager` method and consumer-owned port do\nnot)\n**Settles:** four open items in `docs/architecture/migration-decisions.md#5`\n(listed at the end)\n\n## Problem\n\nThere are **two live memory stores for one assistant**, split by which component\nwrites them, and the chat turn reads neither.\n\n| Family | Written by | Root | Format |\n|---|---|---|---|\n| `internal/memory` (`Manager`, `builtin.Provider`) | the chat agent's `memory_edit` tool via `memorytoolprovider` (`bootstrap.go`) | `\u003cworkDir\u003e/memory` | `MEMORY.md` / `USER.md` |\n| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go`) | `\u003cworkDir\u003e/memory-engine` | identity-keyed blocks |\n\nThey share no code, no format and no scope vocabulary. Neither reaches a prompt:\n`Manager.SystemPromptBlock` (`internal/memory/manager.go`) has no production\ncaller anywhere, so the agent can write memory through a tool and never read it\nback.\n\nThree further defects fall out of the same split:\n\n1. **The engine's contract is not CRUD.** `Store` is `Write`/`Query`/`List`/\n `Forget` — create, read, delete, and **no Update**. The retired file provider\n *does* have `handleAdd`/`handleReplace`/`handleRemove`, so the family being\n deleted is operationally richer than its replacement.\n2. **There is no scope model.** The contract carries one opaque `Identity\n string`, and the curator fills it with a **session id** (`sessioncurator.go`)\n — which is none of the four scopes `docs/architecture/agent-system.md`\n requires, and stops meaning anything when the session ends.\n3. **The chat turn has no user identity on half the channels.** Telegram and\n email populate `SenderID` with a person; the dashboard populates it with\n nothing, and a webhook populates it with nothing either — a route path names\n a source, not a person, so `webhook.go` leaves `SenderID` empty and carries\n the route in `Inbound.BudgetKey` for rate limiting. `sender_id` is persisted\n (`session_store_sqlite.go`), so whatever a channel puts there reaches the\n consumers that read it.\n\n`agent-system.md` says the write-scope selection and cross-scope sharing\nrules \"require a focused memory design decision\". This is that decision.\n\n## Decision\n\n### 1. One engine, addressed by four typed scopes\n\n`internal/domain/memory` is the only memory engine. `Observation.Identity`,\n`Query.Identity`, `Record.Identity` and `List(identity)` are deleted, not\nextended: a field whose meaning depends on the caller cannot carry a scope.\n\n```go\ntype ScopeKind string\n\nconst (\n ScopeGlobal ScopeKind = \"global\" // shared across the application\n ScopeAgent ScopeKind = \"agent\" // private to one Agent\n ScopeUser ScopeKind = \"user\" // one user, across their Agents\n ScopeAgentUser ScopeKind = \"agent-user\" // one Agent's relationship with one user\n)\n\ntype Scope struct {\n Kind ScopeKind\n Agent AgentID // required for ScopeAgent, ScopeAgentUser\n User IdentityID // required for ScopeUser, ScopeAgentUser\n}\n\nfunc (s Scope) Validate() error // rejects a component present where it is not required\nfunc (s Scope) Key() string // canonical, collision-free storage key\n```\n\n`AgentID` and `IdentityID` are opaque. This package never resolves or\ncanonicalises them.\n\nA turn's resolved identity is one value:\n\n```go\ntype Subject struct {\n AgentID AgentID\n UserID IdentityID // \"\" when the channel carries no per-person identity\n}\n\nfunc (s Subject) Scopes() []Scope // readable, most specific first\nfunc (s Subject) WritableScopes() []Scope // never includes ScopeGlobal\n```\n\n**Access control is naming a scope, and nothing else.** The read path names\nexactly the scopes of the resolved `Subject`; the engine never unions beyond what\nit is handed and applies no policy of its own. An engine that enforced policy\nwould need to know about channels, sessions and bindings, and every backend would\nreimplement it. \"Agent-wide is private to its owning Agent by default\"\n(`agent-system.md`) falls out mechanically, because `ScopeAgent{a}` and\n`ScopeAgent{b}` are different storage keys.\n\n`ScopeGlobal` is never model-writable. Writing it is an operator action; nothing\nproduces one yet, but the contract models it because the read set includes it.\n\n### 2. CRUD, with revisions retained\n\n```go\ntype Store interface {\n Create(ctx context.Context, in NewRecord) (Record, error)\n Get(ctx context.Context,Line truncated
"body": "# Memory engine unification: four scopes, CRUD, and one write path -- decision\n\n**Status:** Approved\n**Date:** 2026-09-16\n**Findings:** `memory-4` and its dependants in the adversarial sweep\n(`.local/issue-tracker`); the real defect is the split described below, for\nwhich `memory-4` is a symptom\n**Supersedes:** the draft `memory-turn-context.md` (its synchronous-read\nargument survives and is reused; its `Manager` method and consumer-owned port do\nnot)\n**Settles:** four open items in `docs/architecture/migration-decisions.md#5`\n(listed at the end)\n\n## Problem\n\nThere are **two live memory stores for one assistant**, split by which component\nwrites them, and the chat turn reads neither.\n\n| Family | Written by | Root | Format |\n| ----------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------- | ----------------------- |\n| `internal/memory` (`Manager`, `builtin.Provider`) | the chat agent's `memory_edit` tool via `memorytoolprovider` (`bootstrap.go`) | `\u003cworkDir\u003e/memory` | `MEMORY.md` / `USER.md` |\n| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go`) | `\u003cworkDir\u003e/memory-engine` | identity-keyed blocks |\n\nThey share no code, no format and no scope vocabulary. Neither reaches a prompt:\n`Manager.SystemPromptBlock` (`internal/memory/manager.go`) has no production\ncaller anywhere, so the agent can write memory through a tool and never read it\nback.\n\nThree further defects fall out of the same split:\n\n1. **The engine's contract is not CRUD.** `Store` is `Write`/`Query`/`List`/\n `Forget` — create, read, delete, and **no Update**. The retired file provider\n _does_ have `handleAdd`/`handleReplace`/`handleRemove`, so the family being\n deleted is operationally richer than its replacement.\n2. **There is no scope model.** The contract carries one opaque `Identity\nstring`, and the curator fills it with a **session id** (`sessioncurator.go`)\n — which is none of the four scopes `docs/architecture/agent-system.md`\n requires, and stops meaning anything when the session ends.\n3. **The chat turn has no user identity on half the channels.** Telegram and\n email populate `SenderID` with a person; the dashboard populates it with\n nothing, and a webhook populates it with nothing either — a route path names\n a source, not a person, so `webhook.go` leaves `SenderID` empty and carries\n the route in `Inbound.BudgetKey` for rate limiting. `sender_id` is persisted\n (`session_store_postgres.go`), so whatever a channel puts there reaches the\n consumers that read it.\n\n`agent-system.md` says the write-scope selection and cross-scope sharing\nrules \"require a focused memory design decision\". This is that decision.\n\n## Decision\n\n### 1. One engine, addressed by four typed scopes\n\n`internal/domain/memory` is the only memory engine. `Observation.Identity`,\n`Query.Identity`, `Record.Identity` and `List(identity)` are deleted, not\nextended: a field whose meaning depends on the caller cannot carry a scope.\n\n```go\ntype ScopeKind string\n\nconst (\n ScopeGlobal ScopeKind = \"global\" // shared across the application\n ScopeAgent ScopeKind = \"agent\" // private to one Agent\n ScopeUser ScopeKind = \"user\" // one user, across their Agents\n ScopeAgentUser ScopeKind = \"agent-user\" // one Agent's relationship with one user\n)\n\ntype Scope struct {\n Kind ScopeKind\n Agent AgentID // required for ScopeAgent, ScopeAgentUser\n User IdentityID // required for ScopeUser, ScopeAgentUser\n}\n\nfunc (s Scope) Validate() error // rejects a component present where it is not required\nfunc (s Scope) Key() string // canonical, collision-free storage key\n```\n\n`AgentID` and `IdentityID` are opaque. This package never resolves or\ncanonicalises them.\n\nA turn's resolved identity is one value:\n\n```go\ntype Subject struct {\n AgentID AgentID\n UserID IdentityID // \"\" when the channel carries no per-person identity\n}\n\nfunc (s Subject) Scopes() []Scope // readable, most specific first\nfunc (s Subject) WritableScopes() []Scope // never includes ScopeGlobal\n```\n\n**Access control is naming a scope, and nothing else.** The read path names\nexactly the scopes of the resolved `Subject`; the engine never unions beyond what\nit is handed and applies no policy of its own. An engine that enforced policy\nwould need to know about channels, sessions and bindings, and every backend would\nreimplement it. \"Agent-wide is private to its owning Agent by default\"\n(`agent-system.md`) falls out mechanically, because `SLine truncated
},
{
"url": "/dev/prds/messaging-service-boundary/",
"title": "Messaging Service boundary and transport design",
"section": "PRDs",
"body": "# Messaging Service boundary and transport design\n\n**Status:** Approved\n**Revision:** 1 \n**Date:** 2026-09-19 \n**Beads issue:** `archie-core-8cda.6.1` \n**Parent:** [`service-decomposition.md`](/dev/prds/service-decomposition/) \n**Prerequisites:** Gateway contract extraction (Phase 1), State Store extraction (Phase 2), UI extraction (Phase 3)\n\nThis document is the authoritative specification for Phase 4: Messaging Service extraction. It fixes the process boundary, configuration ownership, client contracts, security posture, readiness behavior, channel invariants, and deletion criteria required by `archie-core-8cda.6` and its child tasks.\n\n## Decision\n\nThe Messaging Service (`cmd/archie-messaging`, composed via `internal/app/archiemessaging`) owns external channel connections (Telegram, email, webhook) and dispatches inbound messages and commands to the standalone Gateway Service over gRPC via `messaging.ChatContract`.\n\nIt is a peer service to the UI Service and the daemon:\n- It serves external chat participants across configured communication platforms.\n- It consumes Gateway's `messaging.ChatContract` exclusively for chat turn execution, streaming, session queries, cancellation, persona selection, and task control actions.\n- It holds no direct database connections (`*store.Store` or SQLite), owns no LLM execution or model provider credentials, and has no dependency on the daemon runtime or the UI HTTP server.\n\n## Boundary and Ownership\n\n| Concern | Messaging Service owns | Messaging Service consumes | Messaging Service must not own or link |\n|---|---|---|---|\n| **Channel transports** | Telegram bot long-polling, Email IMAP/SMTP loops, Inbound Webhook HTTP listener | Gateway `ChatContract` | Direct LLM providers, model runtimes, tokenizer libraries |\n| **Turn dispatch** | Inbound message packaging, typing indicators, live streaming updates | `ChatContract.Route`, `ChatContract.Stream` | `gateway.Router`, `runtime.Runtime`, agent prompt builders |\n| **Sessions \u0026 History** | Platform-to-session key mapping, conversation thread ID translation | `ChatContract.GetSession`, `RecentMessages`, `RecentTurns` | `*store.Store`, `SessionStore` SQLite handles, direct database files |\n| **Control \u0026 Actions** | Platform command parsing (`/status`, `/tasks`, `/cancel`, `/stop`, `/persona`) | `ChatContract.Snapshot`, `ApplyTaskAction`, `Cancel`, `SetPersona` | `daemon.Daemon`, workflow execution engine, worktree operations |\n| **Task Approvals** | Channel interactive keyboards, approval callbacks | `ChatContract.ApplyTaskAction` | Direct task status mutations, forge comment posters |\n| **Configuration** | Platform bot tokens, allowed sender/user IDs, webhook listen ports | `[chat.*]` channel configs, Gateway target/token | `config.Holder`, forge tokens, repo configs, agent container specs |\n| **Readiness** | Messaging process liveness, channel connectivity, Gateway probe | Gateway `ChatContract.Snapshot` | Internal daemon subsystem probes |\n\n## Target Service Shape\n\n1. **Binary entry point**: `cmd/archie-messaging/main.go` parses CLI flags (`-config`, `-config-overlay`, `-gateway-target`, `-gateway-token`) and hands execution to `internal/app/archiemessaging.Run`.\n2. **Application composition**: `internal/app/archiemessaging/` wires:\n - Config loading scoped strictly to `[chat.*]` and `[services.gateway]`.\n - Secret resolution for channel credentials (e.g. Telegram bot token).\n - Gateway gRPC client (`internal/infrastructure/gatewayrpc.Client`).\n - Channel lifecycle managers (`internal/channels/status`).\n - Channel instances (`internal/channels/telegram`, `email`, `webhook`).\n3. **Turn and Stream Execution**:\n - Channels adapt inbound platform messages to `messaging.Inbound`.\n - Streaming channels (Telegram) consume `ChatContract.Stream(ctx, inbound)` which returns `\u003c-chan messaging.ChatEvent`, mapping `started`, `delta`, `tool`, `media`, `done`, and `error` events directly to live message frames.\n - Non-streaming channels (email, synchronous webhooks) consume `ChatContract.Route(ctx, inbound)`.\n\n## Load-Bearing Channel Invariants\n\nThe Messaging Service preserves existing invariants defined in `AGENTS.md` and channel documentation:\n1. **Telegram long-polling**: Must call `dropPendingUpdates(ctx, b)` before `b.Start(ctx)` and on `/restart`.\n2. **Telegram command menus**: Must register command menus simultaneously to `default`, `all_private_chats`, and `all_group_chats` via `commands.go` to prevent menu shadowing.\n3. **No UI detour**: Turns and task actions route directly to Gateway's `ChatContract`; no HTTP request may ever be sent to `archie-ui` or `internal/webui`.\n4. **Sender Confinement**: Telegram sender checks against `allowed_user_ids` must continue to fail closed before initiating any turn dispatch.\n\n## Configuration Ownership\n\n`cmd/archie-messaging` reads only:\n- `[services.gateway].target` and `[services.gatewaLine truncated
"body": "# Messaging Service boundary and transport design\n\n**Status:** Approved\n**Revision:** 1 \n**Date:** 2026-09-19 \n**Beads issue:** `archie-core-8cda.6.1` \n**Parent:** [`service-decomposition.md`](/dev/prds/service-decomposition/) \n**Prerequisites:** Gateway contract extraction (Phase 1), State Store extraction (Phase 2), UI extraction (Phase 3)\n\nThis document is the authoritative specification for Phase 4: Messaging Service extraction. It fixes the process boundary, configuration ownership, client contracts, security posture, readiness behaviour, channel invariants, and deletion criteria required by `archie-core-8cda.6` and its child tasks.\n\n## Decision\n\nThe Messaging Service (`cmd/archie-messaging`, composed via `internal/app/archiemessaging`) owns external channel connections (Telegram, email, webhook) and dispatches inbound messages and commands to the standalone Gateway Service over gRPC via `messaging.ChatContract`.\n\nIt is a peer service to the UI Service and the daemon:\n\n- It serves external chat participants across configured communication platforms.\n- It consumes Gateway's `messaging.ChatContract` exclusively for chat turn execution, streaming, session queries, cancellation, persona selection, and task control actions.\n- It holds no direct database connections, owns no LLM execution or model provider credentials, and has no dependency on the daemon runtime or the UI HTTP server.\n\n## Boundary and Ownership\n\n| Concern | Messaging Service owns | Messaging Service consumes | Messaging Service must not own or link |\n| ---------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |\n| **Channel transports** | Telegram bot long-polling, Email IMAP/SMTP loops, Inbound Webhook HTTP listener | Gateway `ChatContract` | Direct LLM providers, model runtimes, tokenizer libraries |\n| **Turn dispatch** | Inbound message packaging, typing indicators, live streaming updates | `ChatContract.Route`, `ChatContract.Stream` | `gateway.Router`, `runtime.Runtime`, agent prompt builders |\n| **Sessions \u0026 History** | Platform-to-session key mapping, conversation thread ID translation | `ChatContract.GetSession`, `RecentMessages`, `RecentTurns` | store implementations, `SessionStore` database handles |\n| **Control \u0026 Actions** | Platform command parsing (`/status`, `/tasks`, `/cancel`, `/stop`, `/persona`) | `ChatContract.Snapshot`, `ApplyTaskAction`, `Cancel`, `SetPersona` | `daemon.Daemon`, workflow execution engine, worktree operations |\n| **Task Approvals** | Channel interactive keyboards, approval callbacks | `ChatContract.ApplyTaskAction` | Direct task status mutations, forge comment posters |\n| **Configuration** | Platform bot tokens, allowed sender/user IDs, webhook listen ports | `[chat.*]` channel configs, Gateway target/token | `config.Holder`, forge tokens, repo configs, agent container specs |\n| **Readiness** | Messaging process liveness, channel connectivity, Gateway probe | Gateway `ChatContract.Snapshot` | Internal daemon subsystem probes |\n\n## Target Service Shape\n\n1. **Binary entry point**: `cmd/archie-messaging/main.go` parses CLI flags (`-config`, `-config-overlay`, `-gateway-target`, `-gateway-token`) and hands execution to `internal/app/archiemessaging.Run`.\n2. **Application composition**: `internal/app/archiemessaging/` wires:\n - Config loading scoped strictly to `[chat.*]` and `[services.gateway]`.\n - Secret resolution for channel credentials (e.g. Telegram bot token).\n - Gateway gRPC client (`internal/infrastructure/gatewayrpc.Client`).\n - Channel lifecycle managers (`internal/channels/status`).\n - Channel instances (`internal/channels/telegram`, `email`, `webhook`).\n3. **Turn and Stream Execution**:\n - Channels adapt inbound platform messages to `messaging.Inbound`.\n - Streaming channels (Telegram) consume `ChatContract.Stream(ctx, inbound)` which returns `\u003c-chan messaging.ChatEvent`, mapping `started`, `delta`, `tool`, `media`, `done`, and `error` events directly to live message frames.\n - Non-streaming channels (email, synchronous webhooks) consume `ChatContract.Route(ctx, inbound)`.\n\n## Load-Bearing Channel Invariants\n\nThe Messaging Service preserves existing invariants defined in `AGENTS.md` and channel documentation:\n\n1. **Telegram long-polliLine truncated
},
{
"url": "/dev/prds/module-position/",
"title": "Module position -- design",
"section": "PRDs",
"body": "# Module position -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n\n## Problem\n\n`eda-playbook-engine.md` names four logic positions a playbook action can\ntarget: Workflow, Module, Channel, Forge. Workflow (`t2db.9`/`.10`/`.11`)\nand the standalone lint tool (`t2db.12`) are shipped. Module -- the\nposition that makes an action \"not restricted to code-generation\" -- has\nnot started, because it needs a schema-generation mechanism the parent\ndoc deliberately deferred: \"This document does not attempt to design the\nfull generator.\" This is that design.\n\n## Do not invent a new mechanism -- generalize the one used three times\n\nYaegi-interpreted extension code with a fixed, resolved-by-name exported\nfunction already exists in this codebase for three surfaces, and all three\nfollow the identical shape:\n\n| Surface | Fixed signature | Export path | Symbol table |\n|---|---|---|---|\n| Custom gate (`internal/gate/gateeval`) | `func(gate.GateContext) []gate.Finding` | `\"gate.Check\"` | `gateextract.Symbols` |\n| Workflow stage plugin (`skillbuild`) | stage-specific | skill-declared | `wfextract.Symbols` |\n| Skill plugin (`internal/skill/plugin.go`) | `func(string) string` | `\"main.Run\"` | none (stdlib only) |\n\nEach is: read a `.go` file -\u003e `yaegiutil.New` with that surface's symbol\ntable -\u003e `yaegiutil.Resolve[T](i, src, exportPath)` -\u003e call the resolved\nfunction wrapped in `yaegiutil.Safe` for panic recovery. **Module is a\nfourth instance of this same shape**, parameterized by action kind instead\nof hardcoded to one fixed signature. No new interpreter construction, no\nnew panic-recovery mechanism, no new symbol-table generation tool --\n`go generate ... yaegi extract` is already how `wfextract`/`gateextract`\nare produced that way (see their `//go:generate` directives), and Module\nschema generation reuses that exact command.\n\n## No generic `Module` interface -- one typed contract per action kind\n\nThe plugin engine rule's invariant 1 requires \"real capability-specific\noperations,\" and invariant 5 forbids adding capability methods to a\ngeneric interface. A single `Module` interface with `Run(args any) (any,\nerror)` would be exactly the untyped hook the rule (and\n`event-sources-and-reactions.md`'s rejection of a generic `Source`\ninterface) exists to prevent -- restating the mistake the whole EDA\ndocument was written to move away from (`wfextract`'s hardcoded\n`reflect.ValueOf(workflow.Implement)` table is what a closed, un-typed-per-\ncase system already looks like in this repo).\n\nInstead, **each action kind is its own tiny package with its own\ngenerated contract**, exactly like `gate.GateContext`/`gate.Finding` are\none hand-written Go file that `gateextract` turns into a Yaegi symbol\ntable:\n\n```go\n// internal/domain/eda/module/notify/types.go (hand-written, the schema source)\npackage notify\n\n// SchemaVersion is independent of a playbook's own workflow_version, per\n// eda-playbook-engine.md's schema-versioning point.\nconst SchemaVersion = 1\n\ntype Args struct {\n Channel string\n Message string\n}\n\ntype Result struct {\n Delivered bool\n}\n\n//go:generate go run github.com/traefik/yaegi/cmd/yaegi extract -name notifyextract github.com/samcharles93/archie-core/internal/domain/eda/module/notify\n```\n\nA Yaegi module implementing this kind exports a fixed function name\nagainst these generated types, resolved the same way `gate.Check` is:\n\n```go\n// operator's notify.go, interpreted at load\npackage notify\n\nfunc Run(a notify.Args) notify.Result { ... }\n```\n\n`internal/domain/eda/module/notify` is the schema; `notifyextract.Symbols`\nis its generated Yaegi bridge; the operator's file is the implementation.\nThis is the same three-way split `internal/gate` / `gateextract` /\n`.archie/gate.go` already has.\n\n## The registry: `ModuleRegistry`, keyed by kind, not a service locator\n\nPer invariant 2 (owning family manager) and invariant 4 (narrow host\naccess): a `ModuleRegistry` in `internal/domain/eda/module` maps a kind\nname (`\"notify\"`, `\"image-gen\"`) to a resolved, type-erased invoker --\nthe same `map[string]reflect.Value`-shaped erasure `wfextract.Symbols`\nalready uses to bridge Yaegi and Go, not a new pattern and not exposed as\nthe plugin's contract with the daemon (the plugin still writes and is\nchecked against a fully typed `func(Args) Result`; the registry's\ninternal storage is the only place erasure appears, exactly as it already\ndoes inside `wfextract`).\n\n```go\ntype ModuleRegistry struct {\n // kind -\u003e (validate args against generated schema, invoke, marshal result)\n}\n\nfunc (r *ModuleRegistry) Register(kind string, dir string) error // discovers \u003ckind\u003e.go, resolves against that kind's generated symbols\nfunc (r *ModuleRegistry) Invoke(ctx context.Context, kind string, rawArgs map[string]any) (map[string]aLine truncated
"body": "# Module position -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n\n## Problem\n\n`eda-playbook-engine.md` names four logic positions a playbook action can\ntarget: Workflow, Module, Channel, Forge. Workflow (`t2db.9`/`.10`/`.11`)\nand the standalone lint tool (`t2db.12`) are shipped. Module -- the\nposition that makes an action \"not restricted to code-generation\" -- has\nnot started, because it needs a schema-generation mechanism the parent\ndoc deliberately deferred: \"This document does not attempt to design the\nfull generator.\" This is that design.\n\n## Do not invent a new mechanism -- generalise the one used three times\n\nYaegi-interpreted extension code with a fixed, resolved-by-name exported\nfunction already exists in this codebase for three surfaces, and all three\nfollow the identical shape:\n\n| Surface | Fixed signature | Export path | Symbol table |\n| ----------------------------------------- | --------------------------------------- | -------------- | --------------------- |\n| Custom gate (`internal/gate/gateeval`) | `func(gate.GateContext) []gate.Finding` | `\"gate.Check\"` | `gateextract.Symbols` |\n| Workflow stage plugin (`skillbuild`) | stage-specific | skill-declared | `wfextract.Symbols` |\n| Skill plugin (`internal/skill/plugin.go`) | `func(string) string` | `\"main.Run\"` | none (stdlib only) |\n\nEach is: read a `.go` file -\u003e `yaegiutil.New` with that surface's symbol\ntable -\u003e `yaegiutil.Resolve[T](i, src, exportPath)` -\u003e call the resolved\nfunction wrapped in `yaegiutil.Safe` for panic recovery. **Module is a\nfourth instance of this same shape**, parameterised by action kind instead\nof hardcoded to one fixed signature. No new interpreter construction, no\nnew panic-recovery mechanism, no new symbol-table generation tool --\n`go generate ... yaegi extract` is already how `wfextract`/`gateextract`\nare produced that way (see their `//go:generate` directives), and Module\nschema generation reuses that exact command.\n\n## No generic `Module` interface -- one typed contract per action kind\n\nThe plugin engine rule's invariant 1 requires \"real capability-specific\noperations,\" and invariant 5 forbids adding capability methods to a\ngeneric interface. A single `Module` interface with `Run(args any) (any,\nerror)` would be exactly the untyped hook the rule (and\n`event-sources-and-reactions.md`'s rejection of a generic `Source`\ninterface) exists to prevent -- restating the mistake the whole EDA\ndocument was written to move away from (`wfextract`'s hardcoded\n`reflect.ValueOf(workflow.Implement)` table is what a closed, un-typed-per-\ncase system already looks like in this repo).\n\nInstead, **each action kind is its own tiny package with its own\ngenerated contract**, exactly like `gate.GateContext`/`gate.Finding` are\none hand-written Go file that `gateextract` turns into a Yaegi symbol\ntable:\n\n```go\n// internal/domain/eda/module/notify/types.go (hand-written, the schema source)\npackage notify\n\n// SchemaVersion is independent of a playbook's own workflow_version, per\n// eda-playbook-engine.md's schema-versioning point.\nconst SchemaVersion = 1\n\ntype Args struct {\n Channel string\n Message string\n}\n\ntype Result struct {\n Delivered bool\n}\n\n//go:generate go run github.com/traefik/yaegi/cmd/yaegi extract -name notifyextract github.com/samcharles93/archie-core/internal/domain/eda/module/notify\n```\n\nA Yaegi module implementing this kind exports a fixed function name\nagainst these generated types, resolved the same way `gate.Check` is:\n\n```go\n// operator's notify.go, interpreted at load\npackage notify\n\nfunc Run(a notify.Args) notify.Result { ... }\n```\n\n`internal/domain/eda/module/notify` is the schema; `notifyextract.Symbols`\nis its generated Yaegi bridge; the operator's file is the implementation.\nThis is the same three-way split `internal/gate` / `gateextract` /\n`.archie/gate.go` already has.\n\n## The registry: `ModuleRegistry`, keyed by kind, not a service locator\n\nPer invariant 2 (owning family manager) and invariant 4 (narrow host\naccess): a `ModuleRegistry` in `internal/domain/eda/module` maps a kind\nname (`\"notify\"`, `\"image-gen\"`) to a resolved, type-erased invoker --\nthe same `map[string]reflect.Value`-shaped erasure `wfextract.Symbols`\nalready uses to bridge Yaegi and Go, not a new pattern and not exposed as\nthe plugin's contract with the daemon (the plugin still writes and is\nchecked against a fully typed `func(Args) Result`; the registry's\ninternal storage is the only place erasure appears, exactly as it already\ndoes inside `wfextract`).\n\n```go\ntype ModuleRegistry struct {\n // kind -\u003e (validate args against generated schema, invoke, marshal result)\n}\n\nfunc (r *MoLine truncated
},
{
"url": "/dev/prds/multi-action-playbooks/",
"title": "Multi-action playbooks and typed action results",
"section": "PRDs",
"body": "# Multi-action playbooks and typed action results\n\n**Status:** Approved\n**Date:** 2026-09-22\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-nx30` (unblocks `archie-core-t2db.27` and `archie-core-t2db.31`)\n\n## Why this exists\n\n`eda-playbook-engine.md`'s hard boundary rejects any playbook that is not\nexactly one `workflow` action, so the parent document's data-flow, Module and\nChannel/Forge decisions have no loadable shape to attach to. The boundary's own\nstated condition is now met: both execution-time gaps are resolved\n(`eda-playbook-engine.md`, \"Execution-time gaps\"; the `playbook_dispatches`\nledger). This document designs the relaxation.\n\n## A playbook is one of two shapes\n\n- A **workflow playbook** is exactly one `workflow` action. Unchanged: it names\n a workflow definition and is routed by the daemon's definition pin.\n- An **action playbook** is one or more `module` actions in order. Each action\n has an optional `id`, a `kind` naming a registered Module kind, `args`, and an\n optional `when`.\n\nOne playbook does not mix the two shapes.\n\n```yaml\ntrigger: { kind: bug }\nactions:\n - id: build\n position: module\n kind: log\n args: { message: '\"build started\"' }\n - id: done\n position: module\n kind: log\n args: { message: '\"done: \" + string(actions.build.result.written)' }\n when: actions.build.result.written == true\n```\n\nThe first Module kind is the side-effect-free `log` kind\n(`module-position.md`, \"Recommended first slice\"). A Module kind with an\nexternal side effect, and the Channel and Forge positions, are out of scope.\n\n## A result type is the kind's generated Result struct\n\nEach Module kind owns a hand-written `Args` and `Result` struct\n(`internal/domain/eda/module/log` is the worked example); `ModuleRegistry.Invoke`\nreturns the result as a flat `map[string]any`. `ModuleRegistry.DecodeResult`\n(`internal/domain/eda/module`) is the single site that converts that map into\nthe kind's `Result` struct before a later expression reads it, so the value the\nchecker validates and the value the run reads have one definition.\n\n`actions.\u003cid\u003e` is typed by the kind of the action that declares `\u003cid\u003e`:\n`{ result: \u003cKindResult\u003e }`. `event` stays `dyn` (J4,\n`playbook-expression-syntax.md`).\n\n## Reject-at-load, preserved\n\nRelaxing the boundary must not make a bad reference resolvable. The load fails,\nnaming the playbook and the offending action, for:\n\n- an `id` missing where a later action references it, duplicated, or outside\n its shape's grammar: a workflow action id keeps the shared\n stable-identifier grammar (J1, already enforced), while a module action id\n must be a lowercase CEL field name writable as `actions.\u003cid\u003e` (so a CEL\n keyword such as `in`, `true`, `false`, or `null` is rejected at load);\n- an `actions.\u003cid\u003e` read of an id no earlier action declares;\n- an `actions` read that is not statically resolvable to an id (any map index,\n literal or dynamic, `in`, a comprehension): the typed `actions` root is an\n object type, so only field selection `actions.\u003cid\u003e` resolves and the\n `actions[\"id\"]` spelling is not accepted;\n- a `result` field the referenced kind's `Result` does not define;\n- a reference to an earlier action that produces no result;\n- an unknown `position`, an unknown `kind`, or a `module` action with no `kind`;\n- a field belonging to the other shape (`kind` on a `workflow` action, or\n `workflow` on a `module` action);\n- an arg KEY the kind's `Args` schema does not define. Arg VALUE type-checking\n is tracked as `archie-core-t2db` debt, not shipped here.\n\nDeclaring the kind's `Result` schema to CEL at load makes a result-field typo a\nload failure rather than a dispatch failure. Matching arg keys against the\nkind's `Args` schema makes an arg-key typo a load failure; arg value\ntype-checking is tracked as `archie-core-t2db` debt.\n\n## The environment is per playbook\n\nResult typing depends on the ids a playbook declares and the kind each id runs,\nso the CEL environment is built from one playbook's action list rather than once\nper `Store`, and `expr.NewEnv` takes that list: each declared id becomes a field\nof the `actions` object typed by its kind's `Result`.\n\n## Running an action playbook is out of scope\n\nThis document makes an action playbook load and its references type-check. It\ndoes not invoke a Module kind. Invocation, the `playbook_dispatches` gate, and\nstop-on-first-failure across actions are `archie-core-t2db.31`.\n\n## Decisions\n\n**D1 — dispatch before `t2db.31`.** Settled: an action playbook loads and\nvalidates but is not routed; the definition-pin dispatch reports no match for it,\nand the daemon logs a visible warning naming it.\n\n**D2 — mixing positions.** Settled: one shape per playbook. A `workflow` action\nyields a task, not a rLine truncated
"body": "# Multi-action playbooks and typed action results\n\n**Status:** Approved\n**Date:** 2026-09-22\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-nx30` (unblocks `archie-core-t2db.27` and `archie-core-t2db.31`)\n\n## Why this exists\n\n`eda-playbook-engine.md`'s hard boundary rejects any playbook that is not\nexactly one `workflow` action, so the parent document's data-flow, Module and\nChannel/Forge decisions have no loadable shape to attach to. The boundary's own\nstated condition is now met: both execution-time gaps are resolved\n(`eda-playbook-engine.md`, \"Execution-time gaps\"; the `playbook_dispatches`\nledger). This document designs the relaxation.\n\n## A playbook is one of two shapes\n\n- A **workflow playbook** is exactly one `workflow` action. Unchanged: it names\n a workflow definition and is routed by the daemon's definition pin.\n- An **action playbook** is one or more `module` actions in order. Each action\n has an optional `id`, a `kind` naming a registered Module kind, `args`, and an\n optional `when`.\n\nOne playbook does not mix the two shapes.\n\n```yaml\ntrigger: { kind: bug }\nactions:\n - id: build\n position: module\n kind: log\n args: { message: '\"build started\"' }\n - id: done\n position: module\n kind: log\n args: { message: '\"done: \" + string(actions.build.result.written)' }\n when: actions.build.result.written == true\n```\n\nThe first Module kind is the side-effect-free `log` kind\n(`module-position.md`, \"Recommended first slice\"). A Module kind with an\nexternal side effect, and the Channel and Forge positions, are out of scope.\n\n## A result type is the kind's generated Result struct\n\nEach Module kind owns a hand-written `Args` and `Result` struct\n(`internal/domain/eda/module/log` is the worked example); `ModuleRegistry.Invoke`\nreturns the result as a flat `map[string]any`. `ModuleRegistry.DecodeResult`\n(`internal/domain/eda/module`) is the single site that converts that map into\nthe kind's `Result` struct before a later expression reads it, so the value the\nchecker validates and the value the run reads have one definition.\n\n`actions.\u003cid\u003e` is typed by the kind of the action that declares `\u003cid\u003e`:\n`{ result: \u003cKindResult\u003e }`. `event` stays `dyn` (J4,\n`playbook-expression-syntax.md`).\n\n## Reject-at-load, preserved\n\nRelaxing the boundary must not make a bad reference resolvable. The load fails,\nnaming the playbook and the offending action, for:\n\n- an `id` missing where a later action references it, duplicated, or outside\n its shape's grammar: a workflow action id keeps the shared\n stable-identifier grammar (J1, already enforced), while a module action id\n must be a lowercase CEL field name writable as `actions.\u003cid\u003e` (so a CEL\n keyword such as `in`, `true`, `false`, or `null` is rejected at load);\n- an `actions.\u003cid\u003e` read of an id no earlier action declares;\n- an `actions` read that is not statically resolvable to an id (any map index,\n literal or dynamic, `in`, a comprehension): the typed `actions` root is an\n object type, so only field selection `actions.\u003cid\u003e` resolves and the\n `actions[\"id\"]` spelling is not accepted;\n- a `result` field the referenced kind's `Result` does not define;\n- a reference to an earlier action that produces no result;\n- an unknown `position`, an unknown `kind`, or a `module` action with no `kind`;\n- a field belonging to the other shape (`kind` on a `workflow` action, or\n `workflow` on a `module` action);\n- an arg KEY the kind's `Args` schema does not define;\n- an arg value whose checked CEL type cannot fill its `Args` field (`'123'`\n for a string field). A `dyn` value, such as an `event` read, passes: its\n type is known only per event, and the module decode refuses a bad one at\n run.\n\nDeclaring the kind's `Result` schema to CEL at load makes a result-field typo a\nload failure rather than a dispatch failure. Matching arg keys against the\nkind's `Args` schema makes an arg-key typo or a wrongly typed value a load\nfailure.\n\n## The environment is per playbook\n\nResult typing depends on the ids a playbook declares and the kind each id runs,\nso the CEL environment is built from one playbook's action list rather than once\nper `Store`, and `expr.NewEnv` takes that list: each declared id becomes a field\nof the `actions` object typed by its kind's `Result`.\n\n## Running an action playbook is out of scope\n\nThis document makes an action playbook load and its references type-check.\nRunning one is designed in `docs/prds/action-playbook-run.md`.\n\n## Decisions\n\n**D1 — dispatch before `t2db.31`.** Superseded by\n`docs/prds/action-playbook-run.md`. Was: an action playbook loads and\nvalidates but is not routed; the definition-pin dispatch reports no match for it,\nand the daemon logs a visible warning naming it.\n\n**D2 — mixing positions.*Line truncated
},
{
"url": "/dev/prds/news-and-releases/",
"title": "Public news and per-version release notes -- decision",
"title": "Public news and per-version release notes",
"section": "PRDs",
"body": "# Public news and per-version release notes -- decision\n\n**Status:** Approved\n**Date:** 2026-09-21\n**Beads issue:** `archie-core-2ncm.2`\n**Superseded in part:** `docs/prds/release-stream-and-commit-rules.md` supersedes the\nsections \"Source of truth\" and \"Two components\" below. There is now one release\nstream: a single `CHANGELOG.md` carries every release section, the per-component\n`CHANGELOG.archied.md` and `CHANGELOG.archie.md` are deleted, and one `vX.Y.Z` tag\nnames a release. The rest of this document still holds.\n\nA public news page and a release-notes page for every version. Both are derived\nfrom the changelogs the release process already produces, so publishing a\nrelease adds no writing. Part A is the derivation and the artifact any renderer\nconsumes; it is not tied to MkDocs. Part B is the MkDocs rendering that\npublishes them at `offloaded.dev/news/`.\n\n## Part A -- release facts and their derivation\n\n### Source of truth\n\nRelease notes come from `CHANGELOG.archied.md` and `CHANGELOG.archie.md`. Those\nare the release process's frozen notes: `tools/release.sh --prepare` writes a\nsection, the maintainer edits it, and `--tag` refuses to tag a version without\nits section. A page exists exactly for a release the process cut, and no second\ncopy of release prose can drift from the changelog.\n\nTags are not the source. CI and deployment check out shallow, so tags are absent\nfrom a site build; the changelogs are always present and their\n`## [\u003cversion\u003e] - \u003cdate\u003e` headings carry the same version and date the tags\ncarry. Raw commits are not the source either: the changelog is the edited text,\nnot the commit list.\n\n### What a version's notes contain\n\nThe version and date parsed from the section heading, and the section body\nunchanged. The body keeps the maintainer's headings and bullets; the generator\ndoes not regroup them into feature and fix categories, because those categories\nexist only on commits the edited changelog does not preserve.\n\n`## [Unreleased]` is skipped. Any other `## [` heading that is not\n`[version] - date` stops generation, so a malformed heading cannot silently drop\na release. A relative Markdown link in a body stops generation too: a rendered\npage sits at a different depth from the changelog, and a host's link checking\nwould fail on the dead link. Absolute links pass through.\n\n### Two components\n\n`archied` and `archie-agent` version independently and either can be held back,\nso the data carries the tag prefix (`archied`, `archie`), the product name\n(`archied`, `archie-agent`), and the version as separate fields. A release that\nmoved one component is one entry. The generator never pairs two component\nversions or invents a combined product version.\n\n### The canonical artifact\n\n`docs/news/releases.json` is the host hand-off: a committed, generated,\nnewest-first array of `{component, name, version, date, body}`. Every adapter\nrenders from this file rather than re-parsing a changelog. The JSON is the\ncontract; a host adapter may add markup, but not facts.\n\n### Zero per-release maintenance\n\n`task news` regenerates the JSON and the MkDocs pages from the changelogs.\n`task news:check` regenerates them in a temporary directory and fails when the\ncommitted files differ; it runs in `task check`, so a changelog edit cannot land\nwithout its regeneration. `tools/release.sh --tag` regenerates and stages them\nin the release commit, so a tag's tree carries its own facts.\n\nThe generator owns `docs/news/releases.json`, `docs/news/index.md` and the two\ncomponent directories end-to-end: it rewrites expected files and reports an\nunexpected file in a component directory as drift. It leaves every other file\nunder `docs/news/` alone, so a future hand-written announcement is not its\nbusiness.\n\n## Part B -- publishing\n\nMkDocs is the host. `docs/news/index.md` is the news page: date-grouped, newest\nfirst, one entry per release carrying the component, the version, and a link to\nits notes. `docs/news/archied/\u003cversion\u003e.md` and `docs/news/archie/\u003cversion\u003e.md`\nhold the notes. `site_url` is `https://offloaded.dev/`, so the pages are served\nat `offloaded.dev/news/`.\n\nThe version pages stay out of the derived navigation (`not_in_nav` in\n`mkdocs.yml`) while remaining published; the news page is their entry point, so\na version list that grows with every release cannot push the architecture tree\noff the screen.\n\nA different renderer would read `docs/news/releases.json` instead of these\nMarkdown files. That is a separate change in that renderer's repository and\ndoes not alter Part A; the JSON, not the Markdown, is the reusable half.\n\n## Not in scope\n\n- Generated summaries, categories, or section headings; the changelog has no\n structured summary field to derive one from.\n- Per-release download or install links; where to get the artifacts is\n documented once, not restated for eveLine truncated
"body": "# Public news and per-version release notes\n\n**Status:** Approved\n**Date:** 2026-09-21\n**Beads issue:** `archie-core-2ncm.2`\n**Superseded in part:** `docs/prds/release-stream-and-commit-rules.md` defines the\nsingle release stream. `CHANGELOG.md` carries every release and one `vX.Y.Z` tag\nnames each release.\n\nThe Astro website renders public news and per-version release notes from the\nartifacts generated here. Both derive from `CHANGELOG.md`, so publishing a\nrelease adds no writing.\n\n## Source of truth\n\nRelease notes come from the frozen sections in `CHANGELOG.md`:\n`tools/release.sh --prepare` writes a section, and `--tag` refuses to tag a\nversion without it. The generated artifact has one entry per release version.\n\nTags and raw commits are not the source. The changelog is the edited release\nrecord, and its `## [\u003cversion\u003e] - \u003cdate\u003e` headings provide the version and date.\n\n## Release data\n\nThe generator skips `## [Unreleased]`. Any other `## [` heading that is not\n`[version] - date` stops generation. A relative Markdown link in a changelog\nbody also stops generation because the Astro site must be able to render the\ncontent without depending on repository-relative paths.\n\n`archied` and `archie-agent` version independently. Each\n`docs/news/releases.json` entry carries the tag prefix (`archied`, `archie`),\nproduct name (`archied`, `archie-agent`), version, date, and changelog body.\n`docs/news/redirects.json` maps retired per-component news URLs to each unified\nrelease route. The Astro site must apply this table so previously published\nrelease URLs continue to resolve.\n\nBoth JSON files are committed generated artifacts. `task news` regenerates\nthem, `task news:check` detects drift, and `tools/release.sh --tag` regenerates\nand stages them with the release commit. The Astro site renders from these\nartifacts rather than re-parsing `CHANGELOG.md`.\n\n## Site ownership\n\nThe Astro website is maintained outside this repository and serves the\ndocumentation at `offloaded.dev/docs/`. This repository generates and validates\nthe news and documentation data artifacts; it does not build, preview, or\ndeploy the Astro site.\n\n## Not in scope\n\n- Generated summaries, categories, or section headings; the changelog has no\n structured summary field to derive one from.\n- Per-release download or install links; where to get the artifacts is\n documented once, not restated for every release.\n- Hand-written news items.\n- Changes to `infra/ansible` or to the external Astro website repository.\n\n## Verification\n\n- `go test ./tools/newsgen/...` covers parsing, ordering, artifact generation,\n heading and link refusals, and check-mode drift.\n- `task news:check` passes inside `task check`.\n- `task docs:artifact:check` verifies the generated documentation data against\n its Markdown sources.\n"
},
{
"url": "/dev/prds/operator-pr-review/",
"title": "Operator-triggered PR review",
"section": "PRDs",
"body": "# Operator-triggered PR review\n\n**Status:** Draft\n**Beads issue:** `archie-core-h019.8`\n\nThis PRD reuses the adversarial-self-review contract\n(`docs/prds/adversarial-self-review.md`) and the `workflow.Reviewer` /\n`workflow.ReviewReport` types from `internal/domain/workflow`. It decides\nonly what is new: how an operator asks for a review of an *existing* PR, and\nhow that PR's content reaches the reviewer.\n\n## Problem\n\nThe adversarial reviewer (`StageReview`) runs automatically before `StageOpenPR`\nand reviews the task's own worktree HEAD. There is no way to review a PR that\nalready exists: one archie opened, a human opened, or one whose findings the\noperator wants re-checked after a push.\n\n## Shape\n\nOne channel-neutral command — `review_pr` — accepts a repository and PR number\nand returns the structured `ReviewReport`. The Web UI chat and Telegram invoke\nthe same command; neither duplicates review behaviour. The reviewer model is\n`models.reviewer` (falling back to `models.builder`), already the rule the\nworkflow stage uses, so an operator configures it independently of\nplanner/builder.\n\n## Decisions\n\n1. **Forge read.** `GetPullRequest(owner, repo, number)` returns a\n forge-neutral `PullRequest{Number, Title, Body, HeadRef, BaseRef, HeadSHA,\n BaseSHA, State}`. Declared as a narrow `PullRequestReader` interface,\n implemented by GitHub and Gitea; the noop forge does not implement it, so\n the composition root type-asserts and refuses review with \"forge does not support PR\n review\". Adding to the fat `Forge` interface would churn every test fake for\n a capability the noop forge cannot honestly provide.\n\n2. **Materialisation.** `worktree.Manager.CheckoutPR(owner, repo, headRef,\n baseRef)` clones the repository fully and checks out `origin/\u003cheadRef\u003e`.\n `Diff(dir, baseRef)` and `Snapshot(dir, destDir)` then work unchanged:\n `Diff` resolves `origin/\u003cbaseRef\u003e` via the existing `resolveBase`, and\n `Snapshot` strips `.git` exactly as the workflow stage does. The head must\n already be pushed to the same repository — archie's own PRs always are; a\n cross-repo or deleted head is refused with that reason, not half-reviewed.\n\n3. **Reviewer reuse.** `agentworker.NewOperatorReviewer(models, providers)`\n builds the same `subagentReviewer` the stage uses, from daemon-level config\n rather than a `taskrun.Request`. It drops only the `Repo.ReviewEnabled`\n gate (the operator asked explicitly) and the task-run scaffolding.\n\n4. **Command.** A gateway tool `review_pr` (toolset `tasks`) bound to the\n channel's identity at construction — the model never names an identity,\n matching `task_spawn`/`task_action`. The Gateway process serves it: it\n composes the worktree manager it needs to materialise the PR head, and the\n composition root supplies `ChatPRReviewer`, a narrow gateway interface\n whose adapter maps `workflow.ReviewReport` into a gateway-owned result\n shape (gateway states what it needs, the composition root adapts — the\n `ChatTaskActor` pattern).\n\n5. **Authorization.** Identity-scoped repository allow-list, the\n `task_spawn` rule: a chat identity may only review a repo in its\n `TaskProfile.Repos`. `identity == nil` denotes an authenticated dashboard\n operator who may review any configured repository.\n\n6. **Determinism.** One review per (owner, repo, number) at a time: the\n Gateway holds an in-flight set; a concurrent request for the same PR returns\n \"review already in progress\" rather than launching a second reviewer and\n racing on the snapshot.\n\n## Files\n\n- `internal/forge/forge.go`, `github.go`, `gitea.go` — `PullRequest`,\n `PullRequestReader`, `GetPullRequest`.\n- `internal/worktree/worktree.go` — `CheckoutPR`.\n- `internal/app/agentworker/review.go` — `NewOperatorReviewer`.\n- `internal/gateway/review_tools.go` — `ChatPRReviewer`, result shape, `review_pr`.\n- `internal/gateway/turn.go`, `gateway.go` — tool wiring into the turn.\n- `internal/app/archied/pr_review.go` — the `ChatPRReviewer` adapter.\n- `internal/app/archied/{bootstrap.go,gateway.go,main.go}` — composition.\n\n## Not in scope\n\n- Surfacing findings on the PR body or the dashboard (h019.6).\n- Reviewer model per-invocation override: configuration via `models.reviewer`\n is the selection surface; a per-call override is a later knob.\n"
"body": "# Operator-triggered PR review\n\n**Status:** Draft\n**Beads issue:** `archie-core-h019.8`\n\n\u003e Superseded by `docs/prds/pr-review-agent.md`.\n\nThis PRD reuses the adversarial-self-review contract\n(`docs/prds/adversarial-self-review.md`) and the `workflow.Reviewer` /\n`workflow.ReviewReport` types from `internal/domain/workflow`. It decides\nonly what is new: how an operator asks for a review of an _existing_ PR, and\nhow that PR's content reaches the reviewer.\n\n## Problem\n\nThe adversarial reviewer (`StageReview`) runs automatically before `StageOpenPR`\nand reviews the task's own worktree HEAD. There is no way to review a PR that\nalready exists: one archie opened, a human opened, or one whose findings the\noperator wants re-checked after a push.\n\n## Shape\n\nOne channel-neutral command — `review_pr` — accepts a repository and PR number\nand returns the structured `ReviewReport`. The Web UI chat and Telegram invoke\nthe same command; neither duplicates review behaviour. The reviewer model is\n`models.reviewer` (falling back to `models.builder`), already the rule the\nworkflow stage uses, so an operator configures it independently of\nplanner/builder.\n\n## Decisions\n\n1. **Forge read.** `GetPullRequest(owner, repo, number)` returns a\n forge-neutral `PullRequest{Number, Title, Body, HeadRef, BaseRef, HeadSHA,\nBaseSHA, State}`. Declared as a narrow `PullRequestReader` interface,\n implemented by GitHub and Gitea; the noop forge does not implement it, so\n the composition root type-asserts and refuses review with \"forge does not support PR\n review\". Adding to the fat `Forge` interface would churn every test fake for\n a capability the noop forge cannot honestly provide.\n\n2. **Materialisation.** `worktree.Manager.CheckoutPR(owner, repo, headRef,\nbaseRef)` clones the repository fully and checks out `origin/\u003cheadRef\u003e`.\n `Diff(dir, baseRef)` and `Snapshot(dir, destDir)` then work unchanged:\n `Diff` resolves `origin/\u003cbaseRef\u003e` via the existing `resolveBase`, and\n `Snapshot` strips `.git` exactly as the workflow stage does. The head must\n already be pushed to the same repository — archie's own PRs always are; a\n cross-repo or deleted head is refused with that reason, not half-reviewed.\n\n3. **Reviewer reuse.** `agentworker.NewOperatorReviewer(models, providers)`\n builds the same `subagentReviewer` the stage uses, from daemon-level config\n rather than a `taskrun.Request`. It drops only the `Repo.ReviewEnabled`\n gate (the operator asked explicitly) and the task-run scaffolding.\n\n4. **Command.** A gateway tool `review_pr` (toolset `tasks`) bound to the\n channel's identity at construction — the model never names an identity,\n matching `task_spawn`/`task_action`. The Gateway process serves it: it\n composes the worktree manager it needs to materialise the PR head, and the\n composition root supplies `ChatPRReviewer`, a narrow gateway interface\n whose adapter maps `workflow.ReviewReport` into a gateway-owned result\n shape (gateway states what it needs, the composition root adapts — the\n `ChatTaskActor` pattern).\n\n5. **Authorisation.** Identity-scoped repository allow-list, the\n `task_spawn` rule: a chat identity may only review a repo in its\n `TaskProfile.Repos`. `identity == nil` denotes an authenticated dashboard\n operator who may review any configured repository.\n\n6. **Determinism.** One review per (owner, repo, number) at a time: the\n Gateway holds an in-flight set; a concurrent request for the same PR returns\n \"review already in progress\" rather than launching a second reviewer and\n racing on the snapshot.\n\n## Files\n\n- `internal/forge/forge.go`, `github.go`, `gitea.go` — `PullRequest`,\n `PullRequestReader`, `GetPullRequest`.\n- `internal/worktree/worktree.go` — `CheckoutPR`.\n- `internal/app/agentworker/review.go` — `NewOperatorReviewer`.\n- `internal/gateway/review_tools.go` — `ChatPRReviewer`, result shape, `review_pr`.\n- `internal/gateway/turn.go`, `gateway.go` — tool wiring into the turn.\n- `internal/app/archied/pr_review.go` — the `ChatPRReviewer` adapter.\n- `internal/app/archied/{bootstrap.go,gateway.go,main.go}` — composition.\n\n## Not in scope\n\n- Surfacing findings on the PR body or the dashboard (h019.6).\n- Reviewer model per-invocation override: configuration via `models.reviewer`\n is the selection surface; a per-call override is a later knob.\n"
},
{
"url": "/dev/prds/orgs-and-access/",
"title": "Orgs, workspaces and access control",
"section": "PRDs",
"body": "# Orgs, workspaces and access control\n\n**Status:** Approved\n**Date:** 2026-09-24\n**Parent:** `docs/prds/event-automation.md`, epic `archie-core-t2db`\n\n## Why this exists\n\nArchie has no tenant boundary and no access control: one operator, one shared\ntoken, and no org on any record. The event automation design needs orgs to own\nsources, bindings, workflows and agents, and an agent's reach must be decided\nby the policies over it, never by the event that started it.\n\n## Concepts\n\n- **Org.** The tenant boundary. An instance admin creates an org and adds its\n first owner. An owner or admin adds further members by the sign-in\n provider's subject or email.\n- **Workspace.** A division of an org, named freely (`networking-prd`,\n `service-desk-dev`), with an optional `environment` attribute (any string)\n that policies can test. Sources, event types, mappings, bindings and runs\n belong to a workspace.\n- **Identity.** Every principal is an identity (`internal/domain/identity`):\n - a person is an identity of kind `user`, bound to the sign-in provider\n through the existing subject binding;\n - an agent is an identity of kind `bot` or `service_account`, assigned to\n one org and granted access, secrets and permissions the way a user is.\n\n Signing in and verifying credentials stay separate from identity; identity\n is who acts. Memberships, roles, grants and audit records all reference the\n identity ID.\n\n- **Instance admin.** Operates the installation: orgs, the sign-in provider,\n instance policies. Instance admins see an org's resources only as members\n of it.\n\n## What belongs where\n\n| Level | Owns |\n| --------- | ---------------------------------------------------------------------------------------------------------------- |\n| Instance | the shipped workflow catalogue, instance policies |\n| Org | members, identities and their grants, secrets, agent profiles, workspaces, org workflows and their enabled state |\n| Workspace | sources, event types, mappings, bindings, runs, captures, run events and logs, chat sessions, memory |\n\nEvery owned record carries its `org_id`, and workspace records also carry their\n`workspace_id`. An identity, secret or profile is used in a workspace only\nafter the org grants it to that workspace.\n\nA secret is granted to an identity. An agent profile holds the container\nimage, tools and network access, and no secrets; this supersedes the secret\nreferences in `event-automation.md`'s agent profiles.\n\nA workflow names the identity it runs as. A workflow called by another runs\nas its own identity, and the caller's identity must be permitted `run` on it.\n\n## Access decisions\n\n### Where it lives\n\n- `internal/domain/access` owns the policy schema, the action list, how\n principals and resources are turned into policy entities, and the\n `Authorizer` contract.\n- The Cedar implementation, using `github.com/cedar-policy/cedar-go`, lives in\n `internal/infrastructure/access`; `internal/app` wires it.\n- Exactly two places call the `Authorizer`: the dashboard and API request\n path, and dispatch. Every other service verifies a credential and never\n evaluates policy.\n\n### The model\n\n- **Principal:** an identity, with its memberships, roles and grants.\n- **Resource:** the record acted on, with its workspace and org as parents,\n its type, owner and state.\n- **Action:** one of `read`, `create`, `update`, `delete`, `approve`, `run`,\n `read_logs`, `read_secret`, `manage_members`, `manage_identities`,\n `manage_policies`.\n- **Context:** the event's signature result, the address it came from, the\n time, and the run and step when the principal is an agent.\n\n### The policy chain\n\n```\ninstance (+ network rules) ─▶ org ─▶ workspace ─▶ identity + workflow ─▶ object\n```\n\n- **Instance** policies hold across every org. They include network rules:\n which addresses may deliver events to any source on the instance.\n- **Object** policies attach to one object (an event source, a secret, an\n identity, a binding, a workflow): \"only `soc-responder` may read this\n secret\", \"this source accepts events only from 10.20.0.0/16\".\n- A request is allowed only if every level with policies for it permits it. A\n lower level narrows and never widens; a forbid at any level wins; with no\n permit the request is denied.\n- The shipped role policies mean the org level always has policies, so an\n object or workspace policy alone can never grant access.\n- Archie ships an instance policy, which no org can remove, forbidding any\n principal to act on a resource outside the orgs it belongs to.\n\n### Storing and changing policies\n\n- Policies are stored in the State Store per level, versioned, and every\n changeLine truncated
},
{
"url": "/dev/prds/payload-field-mapping/",
"title": "Payload field mapping -- decision",
"section": "PRDs",
"body": "# Payload field mapping -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.3`, depends on `t2db.1`, blocks `t2db.4`\n\nAnswers what a \"mapping\" is, where it lives, and what \"resolve against a\nreal event\" means precisely enough to implement. `t2db.4` (binding: matcher\n+ mapping + workflow) is out of scope -- this bead ships the mapping\nconcept and its preview only, as a standalone entity `t2db.4` will later\nreference by ID.\n\n## Decision: a new `internal/domain/mapping` package, SQLite storage\n\n`internal/domain/mapping` owns the mapping vocabulary and the pure\nresolve/preview rule; `internal/store` persists it (mirrors\n`captures.go`'s shape exactly -- inline schema const, narrow store\ninterface, `*store.Store` implementation); `internal/webui/api_mapping.go`\nis the transport. This follows `docs/prds/event-capture-storage.md`'s own\nplacement precedent: `internal/store` is where this daemon's persistence\nalready lives, not `internal/infrastructure` (that layer holds\ncross-domain services -- config, eventbus, modelcatalog -- not this\ndaemon's primary store).\n\n### Why a domain package and not just a store table\n\nResolving a path against a payload and deciding \"missing vs null vs\ntype-changed\" is a rule, not a query -- CLAUDE.md's domain layer owns\n\"language, state, rules, operations\" precisely so this logic is testable\nwithout a database and reusable by `t2db.4`'s runtime trigger path without\neither package importing the other's transport concerns.\n\n## Mapping shape\n\n```go\ntype Mapping struct {\n\tID int64\n\tName string\n\tSourceHint string // free-text label (e.g. \"sentry\"), organisational only -- not enforced against Capture.Source\n\tFields []Field\n\tCreatedAt time.Time\n\tUpdatedAt time.Time\n}\n\ntype Field struct {\n\tName string // the name the workflow receives\n\tPath string // dot/bracket path into the payload, see below\n\tType FieldType // expected type, checked at resolve time\n\tRequired bool // Required=false + missing is not a failure; Required=false + wrong type still is\n}\n\ntype FieldType string // \"string\" | \"number\" | \"bool\" | \"object\" | \"array\" | \"any\"\n```\n\n`SourceHint` is advisory only: an operator authors a mapping by clicking\nthrough one example capture, but the mapping is not pinned to that\ncapture's exact source string, because `t2db.4`'s matcher (not this bead)\ndecides which events a binding applies to. Pinning here would duplicate\nthat decision in the wrong layer.\n\n## Path syntax\n\nDot-separated keys with `[N]` for array indices: `data.items[0].id`. No\nwildcards, no filters, no external library -- the grammar is exactly what a\nclick-through UI needs to express (this key, then this key, then this\nindex), and every path in a mapping was generated by clicking a value in a\nreal payload, never hand-written against a spec. A hand-rolled parser\n(~30 lines: split on `.`, strip `[N]` suffixes) is less risk than a new\ndependency for a grammar this small.\n\n## Resolve semantics (the preview AND the future runtime path)\n\n```go\nfunc Resolve(fields []Field, payload []byte) (values map[string]any, failures []Failure)\n\ntype Failure struct {\n\tFieldName string\n\tPath string\n\tReason string // \"missing\" | \"null\" | \"type_mismatch\"\n}\n```\n\nDecode with `json.Decoder.UseNumber()` (matches `webhookguard.RedactPayload`'s\nexisting convention) so int/float distinction survives for type checking.\nWalk each field's path independently -- one field's failure does not stop\nresolution of the others, because the whole point of preview is showing\nthe operator every problem at once, not the first one.\n\n- Path segment doesn't exist, or indexes past an array's length -\u003e `missing`\n- Path resolves to JSON `null` -\u003e `null`\n- Path resolves to a value whose JSON type doesn't match `Field.Type`\n (`\"any\"` always matches) -\u003e `type_mismatch`\n- `Required: false` suppresses `missing` only, never `null` or\n `type_mismatch` -- a field that's present but the wrong shape is always\n worth surfacing, since silently coercing it is exactly the \"agent\n confabulates around a blank field\" failure this bead exists to prevent.\n\n**This is the same function both consumers use.** `t2db.3`'s preview calls\nit against an operator-picked capture and renders every result, pass or\nfail, in the UI -- that satisfies this bead's \"fail loudly\" acceptance\ncriterion, because at this stage the only runtime consumer of a mapping\n*is* the human previewing it. `t2db.4` will call the identical function\nwhen a live event triggers a binding and turn any non-empty `failures` into\na visible operator-facing failure (park the task / surface in the\ninspector) instead of starting a workflow with blank fields -- that wiring\nis `t2db.4`'s job, not duplicated here.\n\n## Storage\n\n`internal/store/mappings.go`, `field_mappings` tabLine truncated
"body": "# Payload field mapping -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.3`, depends on `t2db.1`, blocks `t2db.4`\n\nAnswers what a \"mapping\" is, where it lives, and what \"resolve against a\nreal event\" means precisely enough to implement. `t2db.4` (binding: matcher\n\n- mapping + workflow) is out of scope -- this bead ships the mapping\n concept and its preview only, as a standalone entity `t2db.4` will later\n reference by ID.\n\n## Decision: a new `internal/domain/mapping` package, SQLite storage\n\n\u003e Storage superseded: every store now lives in PostgreSQL behind\n\u003e `internal/domain/storecontract`, implemented in `internal/infrastructure/postgres`\n\u003e (`docs/prds/state-store-contract.md`). SQLite names below describe the\n\u003e original design.\n\n`internal/domain/mapping` owns the mapping vocabulary and the pure\nresolve/preview rule; `internal/store` persists it (mirrors\n`captures.go`'s shape exactly -- inline schema const, narrow store\ninterface, `*store.Store` implementation); `internal/webui/api_mapping.go`\nis the transport. This follows `docs/prds/event-capture-storage.md`'s own\nplacement precedent: `internal/store` is where this daemon's persistence\nalready lives, not `internal/infrastructure` (that layer holds\ncross-domain services -- config, eventbus, modelcatalog -- not this\ndaemon's primary store).\n\n### Why a domain package and not just a store table\n\nResolving a path against a payload and deciding \"missing vs null vs\ntype-changed\" is a rule, not a query -- CLAUDE.md's domain layer owns\n\"language, state, rules, operations\" precisely so this logic is testable\nwithout a database and reusable by `t2db.4`'s runtime trigger path without\neither package importing the other's transport concerns.\n\n## Mapping shape\n\n```go\ntype Mapping struct {\n\tID int64\n\tName string\n\tSourceHint string // free-text label (e.g. \"sentry\"), organisational only -- not enforced against Capture.Source\n\tFields []Field\n\tCreatedAt time.Time\n\tUpdatedAt time.Time\n}\n\ntype Field struct {\n\tName string // the name the workflow receives\n\tPath string // dot/bracket path into the payload, see below\n\tType FieldType // expected type, checked at resolve time\n\tRequired bool // Required=false + missing is not a failure; Required=false + wrong type still is\n}\n\ntype FieldType string // \"string\" | \"number\" | \"bool\" | \"object\" | \"array\" | \"any\"\n```\n\n`SourceHint` is advisory only: an operator authors a mapping by clicking\nthrough one example capture, but the mapping is not pinned to that\ncapture's exact source string, because `t2db.4`'s matcher (not this bead)\ndecides which events a binding applies to. Pinning here would duplicate\nthat decision in the wrong layer.\n\n## Path syntax\n\nDot-separated keys with `[N]` for array indices: `data.items[0].id`. No\nwildcards, no filters, no external library -- the grammar is exactly what a\nclick-through UI needs to express (this key, then this key, then this\nindex), and every path in a mapping was generated by clicking a value in a\nreal payload, never hand-written against a spec. A hand-rolled parser\n(~30 lines: split on `.`, strip `[N]` suffixes) is less risk than a new\ndependency for a grammar this small.\n\n## Resolve semantics (the preview AND the future runtime path)\n\n```go\nfunc Resolve(fields []Field, payload []byte) (values map[string]any, failures []Failure)\n\ntype Failure struct {\n\tFieldName string\n\tPath string\n\tReason string // \"missing\" | \"null\" | \"type_mismatch\"\n}\n```\n\nDecode with `json.Decoder.UseNumber()` (matches `webhookguard.RedactPayload`'s\nexisting convention) so int/float distinction survives for type checking.\nWalk each field's path independently -- one field's failure does not stop\nresolution of the others, because the whole point of preview is showing\nthe operator every problem at once, not the first one.\n\n- Path segment doesn't exist, or indexes past an array's length -\u003e `missing`\n- Path resolves to JSON `null` -\u003e `null`\n- Path resolves to a value whose JSON type doesn't match `Field.Type`\n (`\"any\"` always matches) -\u003e `type_mismatch`\n- `Required: false` suppresses `missing` only, never `null` or\n `type_mismatch` -- a field that's present but the wrong shape is always\n worth surfacing, since silently coercing it is exactly the \"agent\n confabulates around a blank field\" failure this bead exists to prevent.\n\n**This is the same function both consumers use.** `t2db.3`'s preview calls\nit against an operator-picked capture and renders every result, pass or\nfail, in the UI -- that satisfies this bead's \"fail loudly\" acceptance\ncriterion, because at this stage the only runtime consumer of a mapping\n_is_ the human previewing it. `t2db.4` will call the identical function\nwhen a live event triggers a binding and turn any nonLine truncated
},
{
"url": "/dev/prds/playbook-expression-syntax/",
"title": "Playbook data-flow and condition syntax",
"section": "PRDs",
"body": "# Playbook data-flow and condition syntax\n\n**Status:** Approved\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-t2db.14` (expression environment).\nUnbuilt decisions: `archie-core-t2db.25` (J1 action ids),\n`archie-core-t2db.26` (J2 args as CEL),\n`archie-core-t2db.27` (Result schemas declared to CEL).\n\n**Decision:** CEL via `cel.dev/cel-go` (v0.32.0), pinned. One expression\nmechanism covers both an action's `when` condition and its `args` values.\n\n## The requirement, stated directly\n\nA playbook action is gated and parametrised by runtime data: (a) a\ncondition deciding whether the action runs; (b) a later action's `args`\nvalues referencing an earlier action's `Result` and the triggering\nevent's fields. Both are **CEL expressions**, evaluated against one\nevaluation context. There is no separate interpolation syntax: CEL\nreads nested maps and fields natively, so `args` values that need data\nare written as CEL, and only plain literal args remain plain YAML\nscalars.\n\nBoth halves are read-only: expressions may read context values and\ncompute a result from them, never mutate, never call host functions,\nnever perform I/O. CEL enforces this structurally (no side effects,\nlinear evaluation when macros are bounded, cost-limited).\n\n```yaml\nactions:\n - id: build\n position: module\n kind: log\n args:\n message: '\"build finished\"' # literal\n when: 'event.label == \"bugfix\"' # gate on event field\n - position: module\n kind: log\n args:\n message: '\"done: \" + string(actions.build.result.written)'\n when: 'actions.build.result.written == true'\n```\n\n## Trust boundary of the expression\n\nA playbook YAML is **operator-installed, in-process, daemon-privileged**\n-- the same tier as `ModuleDir`/`PluginDir`/`SecretEngineDir`\n(module-position.md's trust-boundary section): loaded from a configured\ndirectory at startup, never from a webhook body or task worktree. The\nschema-by-example flow uses live events to *design against*; the saved\nplaybook is operator-authored file content in an operator-configured\nlocation.\n\nTwo consequences:\n\n1. The expression string is **trusted**. Operator-authored config, not\n attacker input; no sandboxing against a hostile expression string is\n required. If a future playbook source is less trusted (auto-generated\n bindings from unauthenticated captures), that is the playbook-file\n trust tier moving -- the loader's acceptance check is the right\n place, not the evaluator.\n2. The **data the expression reads is NOT trusted** (decoded webhook\n body, prior results through the same pipeline). Robustness against\n hostile data is required: no panic on wrong-typed/missing fields,\n no unbounded cost on deep/cyclic maps, bounded evaluation time. CEL\n provides this structurally (cost limits, linear non-Turing-complete\n evaluation, error values instead of panics -- verified in the\n vetting record below).\n\n## The gate precedent is deliberately NOT copied\n\n`internal/gate/gateeval` evaluates arbitrary interpreted Go\n(`.archie/gate.go`) as the repo's conditional-logic precedent. That is\nthe wrong precedent for playbook conditions because this document's\npremise is: **YAML is pure orchestration data; Yaegi is where\nimperative logic lives** (Problem section; module-position.md's\n\"no generic hook\" section). Yaegi snippets in YAML would move\nimperative logic into the data layer -- the inversion this design\nexists to prevent -- and make playbooks un-lintable.\n\nThe line: conditions are **declarative predicates over runtime data,\nnot programs**. CEL is non-Turing-complete and side-effect-free, so it\ncannot become a program; a condition that needs real logic gets a\nModule kind (Yaegi), referenced by the action, not a stronger\nexpression body.\n\n## Plugin-engine-rule interaction\n\nThe plugin engine rule forbids a generic `Module` interface with an\n`any` payload; it exists to keep static implementation contracts\ntyped. Evaluating CEL against runtime `map[string]any` is **not the\nsame problem**: the rule concerns *implementation contracts* (static\noperations a capability family exposes), not *runtime data values*\n(legitimately dynamic -- an event payload's shape is unknown until it\narrives). The Module contract stays fully typed (generated\n`Args`/`Result` schemas); CEL is a read-only data reader under the\nplaybook engine family, not a new capability contract. Stated once.\n\n## Minimum viable evaluation context (what expressions see)\n\nOne flat context, namespaced from the playbook run, built at dispatch\ntime:\n\n| Name | Type | Source |\n|---|---|---|\n| `event` | `map(string, dyn)` | The triggering event's decoded payload (webhook body / forge issue / schedule tick). Field access via `event.\u003cfield\u003e`, map access via `event[\"field\"]`, presence via `has(eventLine truncated
"body": "# Playbook data-flow and condition syntax\n\n**Status:** Approved\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-t2db.14` (expression environment).\nUnbuilt decisions: `archie-core-t2db.25` (J1 action ids),\n`archie-core-t2db.26` (J2 args as CEL),\n`archie-core-t2db.27` (Result schemas declared to CEL).\n\n**Decision:** CEL via `cel.dev/cel-go` (v0.32.0), pinned. One expression\nmechanism covers both an action's `when` condition and its `args` values.\n\n## The requirement, stated directly\n\nA playbook action is gated and parametrised by runtime data: (a) a condition\ndeciding whether the action runs; (b) a later action's `args` values referencing\nan earlier action's `Result` and the triggering event's fields. Both are **CEL\nexpressions**, evaluated against one evaluation context. There is no separate\ninterpolation syntax: CEL reads nested maps and fields natively, so `args`\nvalues that need data are written as CEL, and only plain literal args remain\nplain YAML scalars.\n\nBoth halves are read-only: expressions may read context values and compute a\nresult from them, never mutate, never call host functions, never perform I/O.\nCEL enforces this structurally (no side effects, linear evaluation when macros\nare bounded, cost-limited).\n\n```yaml\nactions:\n - id: build\n position: module\n kind: log\n args:\n message: '\"build finished\"' # literal\n when: 'event.label == \"bugfix\"' # gate on event field\n - position: module\n kind: log\n args:\n message: '\"done: \" + string(actions.build.result.written)'\n when: \"actions.build.result.written == true\"\n```\n\n## Trust boundary of the expression\n\nA playbook YAML is **operator-installed, in-process, daemon-privileged** -- the\nsame tier as `ModuleDir`/`PluginDir`/`SecretEngineDir` (module-position.md's\ntrust-boundary section): loaded from a configured directory at startup, never\nfrom a webhook body or task worktree. The schema-by-example flow uses live\nevents to _design against_; the saved playbook is operator-authored file content\nin an operator-configured location.\n\nTwo consequences:\n\n1. The expression string is **trusted**. Operator-authored config, not attacker\n input; no sandboxing against a hostile expression string is required. If a\n future playbook source is less trusted (auto-generated bindings from\n unauthenticated captures), that is the playbook-file trust tier moving -- the\n loader's acceptance check is the right place, not the evaluator.\n2. The **data the expression reads is NOT trusted** (decoded webhook body, prior\n results through the same pipeline). Robustness against hostile data is\n required: no panic on wrong-typed/missing fields, no unbounded cost on\n deep/cyclic maps, bounded evaluation time. CEL provides this structurally\n (cost limits, linear non-Turing-complete evaluation, error values instead of\n panics -- verified in the vetting record below).\n\n## The gate precedent is deliberately NOT copied\n\n`internal/gate/gateeval` evaluates arbitrary interpreted Go (`.archie/gate.go`)\nas the repo's conditional-logic precedent. That is the wrong precedent for\nplaybook conditions because this document's premise is: **YAML is pure\norchestration data; Yaegi is where imperative logic lives** (Problem section;\nmodule-position.md's \"no generic hook\" section). Yaegi snippets in YAML would\nmove imperative logic into the data layer -- the inversion this design exists to\nprevent -- and make playbooks un-lintable.\n\nThe line: conditions are **declarative predicates over runtime data, not\nprograms**. CEL is non-Turing-complete and side-effect-free, so it cannot become\na program; a condition that needs real logic gets a Module kind (Yaegi),\nreferenced by the action, not a stronger expression body.\n\n## Plugin-engine-rule interaction\n\nThe plugin engine rule forbids a generic `Module` interface with an `any`\npayload; it exists to keep static implementation contracts typed. Evaluating CEL\nagainst runtime `map[string]any` is **not the same problem**: the rule concerns\n_implementation contracts_ (static operations a capability family exposes), not\n_runtime data values_ (legitimately dynamic -- an event payload's shape is\nunknown until it arrives). The Module contract stays fully typed (generated\n`Args`/`Result` schemas); CEL is a read-only data reader under the playbook\nengine family, not a new capability contract. Stated once.\n\n## Minimum viable evaluation context (what expressions see)\n\nOne flat context, namespaced from the playbook run, built at dispatch time:\n\n| Name | Type | Source Line truncated
},
{
"url": "/dev/prds/pr-review-agent/",
"title": "PR review agent",
"section": "PRDs",
"body": "# PR review agent\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md`; supersedes the reviewer\nexecutor and blocking rule in `docs/architecture/adversarial-review.md`, and\nthe designs in `docs/prds/operator-pr-review.md` and\n`docs/prds/review-calibration.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (every agent\ncall is a StepExecution), `docs/prds/external-agent-harness.md` (any agent\nstep may run on a harness), `docs/prds/inline-review.md` (posting),\n`docs/prds/pr-review-remediation.md` (consumes the findings).\n\n## Decision\n\nArchie ships a pull request reviewer as its first end-to-end product. It\nreviews any pull request on a watched repository, a PR an operator names, and\narchie's own PRs before they open.\n\nThe reviewer is a fixed pipeline, not a single agent. The review strategy is\ngenerated per PR: three lens agents propose review dimensions from the PR's\ncontent, one reviewer definition runs once per dimension, and later agents\nverify, challenge and combine the findings. Everything that can be computed\nis code: diff parsing, clustering, blast radius, evidence extraction,\nscoring, deduplication, line mapping and the review event.\n\nThe pipeline is **recall-first**. It posts every evidenced finding above the\nconfidence threshold, up to the comment cap. A precision gate exists as an\noperator dial and is off by default.\n\nAcceptance is measured, not asserted: see Verification.\n\n## Pipeline\n\nEach numbered phase is a stage of the `pr-review` workflow. Each agent call is\nan `agent` StepExecution; fan-out phases record one child per call.\n\n1. **Intake.** Code reads the PR metadata and diff statistics: type,\n complexity, languages, areas touched, risk signals. Depth comes from lines\n changed: under 100 is `quick` (at most 3 dimensions), under 500 is\n `standard` (6), otherwise `deep` (12). An operator may set depth\n explicitly.\n2. **Anatomy.** Code parses the diff into files and hunks, clusters related\n files, and computes the blast radius: unchanged files that import or are\n imported by changed files. One agent writes the PR narrative, risk\n surfaces, changes that do not fit the narrative, and gaps between the\n description and the diff.\n3. **Dimension selection.** Three lens agents run in parallel over the intake,\n anatomy and diff, each able to read the repository:\n - **behaviour:** where the old and new code diverge for any input; API\n contracts, concurrency and state, security, error handling, data flow;\n - **mechanics:** whether the code runs at the language and framework\n level; types, signatures and every caller, decorators and middleware,\n framework contracts, imports;\n - **fit:** patterns, complexity, abstraction, test adequacy, documentation\n that no longer matches, dependencies, migration completeness.\n\n Each lens returns review dimensions: a name, a reviewer prompt written for\n this PR, target files, context files and a priority. Code merges them,\n drops duplicates and keeps the highest-priority dimensions up to the\n depth's cap.\n4. **Review.** One reviewer definition runs once per dimension, in parallel,\n at most 8 at a time. Each reads its target and context files and may\n follow references. Each finding carries file, line range, severity\n (`critical`, `important`, `suggestion`, `nitpick`), title, body, an\n optional suggested fix, quoted evidence, confidence and tags.\n5. **Verification layer**, over the review findings:\n - code extracts an evidence package per finding: the code at the cited\n lines and snippets from its callers;\n - an evidence verifier checks high-priority findings against their\n packages;\n - an adversary confirms or challenges each finding, looks for issues every\n reviewer missed, and is more sceptical when intake scores the PR as\n likely machine-written;\n - a compound agent looks, within each cluster of confirmed findings, for\n defects that only exist in combination.\n6. **Coverage and consistency**, in parallel:\n - a coverage gate checks every cluster and high-exposure blast-radius file\n was reviewed, and runs gap reviewers for what was not, at most 2 rounds;\n - consistency verification lists every cross-location obligation the\n changed code creates (what must be true elsewhere for this line to be\n correct), then verifies each by reading both ends. A broken obligation\n becomes a finding.\n7. **Synthesis**, code only:\n - score = severity weight (1.0, 0.7, 0.3, 0.1) × confidence × multipliers:\n compound 1.5, adversary-confirmed 1.3, adversary-challenged 0.5, likely\n machine-written PR 1.2, blast radius over 10 files 1.2;\n - drop findings under the severity's confidence floor: critical 0.2,\n important 0.3, suggestion 0.4, nitpick 0.4;\n - merge exact duplicates (file, overlapping lines, category) in code, and\n nearLine truncated
},
{
"url": "/dev/prds/pr-review-remediation/",
"title": "PR review comment remediation -- decision",
"section": "PRDs",
"body": "# PR review comment remediation -- decision\n\n**Status:** Approved\n**Date:** 2026-09-10, amended and ratified 2026-09-19\n**Beads issue:** (filed as `archie-core-…`, parent: `archie-core-7d5u` event sources and typed reactions)\n\nAnswers: how archie reacts to review comments on a PR it opened, from a human\nor from another review bot, and remediates them. Built on two settled decisions — the adversarial review\nepic's isolation contract (`docs/prds/adversarial-self-review.md`) and the\nevent-sources decision (`docs/prds/event-sources-and-reactions.md`) — plus the\nwebhook intake security contract (`docs/prds/webhook-intake-security.md`).\nNothing here re-decides those; it names the one concrete reaction each one's\nmachinery was built to carry.\n\n## Problem\n\nArchie opens a PR (`pr_open`) and then never learns what a human said about\nit. `forge.Forge` has no method to list PR reviews or review comments; the\ndaemon poll loop finds only new issues; the forge webhook receiver\n(`internal/forge/webhook/receiver.go`) decodes only `issues` events and\nexplicitly ignores `pull_request` events. A \"requested changes\" review, or an\ninline comment on a line, is invisible work.\n\n## Decisions\n\n### 1. Read surface: a narrow `PullRequestReviewReader`, type-asserted\n\nA new forge interface, implemented by GitHub and Gitea, not folded into the\nfat `Forge` interface (the h019.8 `PullRequestReader` precedent — the noop\nforge cannot honestly provide it):\n\n```go\ntype ReviewComment struct { ID int64; Author, Body, Path string; Line int; InReplyTo int64; CreatedAt time.Time }\ntype Review struct { ID int64; Author, State string /* requested_changes | approved | commented | dismissed */; SubmittedAt time.Time }\n\ntype PullRequestReviewReader interface {\n ListReviews(ctx, owner, repo string, number, sinceID int64) ([]Review, error)\n ListReviewComments(ctx, owner, repo string, number, sinceID int64) ([]ReviewComment, error)\n // ReplyToReview posts a reply to a review or comment thread.\n ReplyToReview(ctx, owner, repo string, number, inReplyTo int64, body string) error\n}\n```\n\nGitHub: `pulls/{n}/reviews` + `pulls/{n}/comments`; reply via\n`pulls/{n}/comments/{id}/replies`. Gitea: `pulls/{n}/reviews` +\n`pulls/{n}/comments`; reply via `pulls/{n}/comments/{id}`. `sinceID` is the\ncursor for both poll and webhook dedup.\n\n### 2. Event source: webhook first, poll as the universal backstop\n\n- **Webhook (GitHub, low latency):** extend `receiver.go` to also decode\n `pull_request_review` and `pull_request_review_comment` events, behind the\n existing HMAC verification, producing the same reaction as the poller. The\n receiver stays a forge-intake surface — not the generic chat webhook, not a\n new generic receiver (7d5u decision 4).\n- **Poll (both forges, no webhook dependency):** a periodic scan of `pr_open`\n tasks calls `ListReviews`/`ListReviewComments` with a persisted `sinceID`\n cursor per task. This is the Gitea path and the deployment-without-webhook\n path; it must stay first-class, not a legacy fallback (the repo's own\n webhook-intake rule). It is **one shared scan over all `pr_open` tasks**,\n not a scan inside each identity's poll loop, and it calls the forge client\n the scanned task's own identity owns. This is `reconcilePRs`'s shape\n exactly (`internal/daemon/daemon.go`: `Store.OpenPRs` then `forgeFor(\u0026t)`).\n A per-identity scan would call one identity's forge client against another\n identity's PR.\n\nBoth paths emit the **same** typed reaction, so `PublishUnique` dedups them\nfor free — the `TaskEnvelope.IdempotencyKey` pattern (7d5u decision 4) applied\nto reviews.\n\n### 3. Reaction contract: producer-only, resolves to an existing task\n\nA new `workintake.ReviewCommentEnvelope{Owner, Repo, PRNumber, Kind, CommentID,\nReviewID, Author, State, Body, Path, Line}`. Idempotency key is\n`owner/repo/pr-number/kind/id` — source-independent, so a webhook delivery\nand a poll of the same comment collapse.\n\n`Kind` (`review` or `comment`) is part of the key because a review ID and a\nreview-comment ID come from independent forge sequences. Keying on the bare id\nlets a review and an inline comment on the same PR collide, silently dropping\none of the two. This is a producer-only reaction\n(7d5u decision 3): it never vetoes or mutates in-flight work; the target task\nis idle (`pr_open`).\n\nThe daemon resolves `PRNumber` → the task that owns it. An unmatched PR (not\nan archie task) is dropped with a counter — a public webhook must not be able\nto start an agent against an arbitrary repository. A PR whose task is merged,\nclosed or archived is dropped through the same counter: the reaction is only\never work against a PR archie itself opened *and still owns*.\n\nThat lookup does not exist. `pr_number` is written by\n`internal/store/store.go` and never read in a `WHERE` clause, so this needs a\n`TaskStore` method keyed on `(owner, repLine truncated
"body": "# PR review comment remediation -- decision\n\n**Status:** Approved\n**Date:** 2026-09-10, amended and ratified 2026-09-19\n**Beads issue:** (filed as `archie-core-…`, parent: `archie-core-7d5u` event sources and typed reactions)\n\nAnswers: how archie reacts to review comments on a PR it opened, from a human\nor from another review bot, and remediates them. Built on two settled decisions — the adversarial review\nepic's isolation contract (`docs/prds/adversarial-self-review.md`) and the\nevent-sources decision (`docs/prds/event-sources-and-reactions.md`) — plus the\nwebhook intake security contract (`docs/prds/webhook-intake-security.md`).\nNothing here re-decides those; it names the one concrete reaction each one's\nmachinery was built to carry.\n\n## Problem\n\nArchie opens a PR (`pr_open`) and then never learns what a human said about\nit. `forge.Forge` has no method to list PR reviews or review comments; the\ndaemon poll loop finds only new issues; the forge webhook receiver\n(`internal/forge/webhook/receiver.go`) decodes only `issues` events and\nexplicitly ignores `pull_request` events. A \"requested changes\" review, or an\ninline comment on a line, is invisible work.\n\n## Decisions\n\n### 1. Read surface: a narrow `PullRequestReviewReader`, type-asserted\n\nA new forge interface, implemented by GitHub and Gitea, not folded into the\nfat `Forge` interface (the h019.8 `PullRequestReader` precedent — the noop\nforge cannot honestly provide it):\n\n```go\ntype ReviewComment struct { ID int64; Author, Body, Path string; Line int; InReplyTo int64; CreatedAt time.Time }\ntype Review struct { ID int64; Author, State string /* requested_changes | approved | commented | dismissed */; SubmittedAt time.Time }\n\ntype PullRequestReviewReader interface {\n ListReviews(ctx, owner, repo string, number, sinceID int64) ([]Review, error)\n ListReviewComments(ctx, owner, repo string, number, sinceID int64) ([]ReviewComment, error)\n // ReplyToReview posts a reply to a review or comment thread.\n ReplyToReview(ctx, owner, repo string, number, inReplyTo int64, body string) error\n}\n```\n\nGitHub: `pulls/{n}/reviews` + `pulls/{n}/comments`; reply via\n`pulls/{n}/comments/{id}/replies`. Gitea: `pulls/{n}/reviews` +\n`pulls/{n}/comments`; reply via `pulls/{n}/comments/{id}`. `sinceID` is the\ncursor for both poll and webhook dedup.\n\n### 2. Event source: webhook first, poll as the universal backstop\n\n- **Webhook (GitHub, low latency):** extend `receiver.go` to also decode\n `pull_request_review` and `pull_request_review_comment` events, behind the\n existing HMAC verification, producing the same reaction as the poller. The\n receiver stays a forge-intake surface — not the generic chat webhook, not a\n new generic receiver (7d5u decision 4).\n- **Poll (both forges, no webhook dependency):** a periodic scan of `pr_open`\n tasks calls `ListReviews`/`ListReviewComments` with a persisted `sinceID`\n cursor per task. This is the Gitea path and the deployment-without-webhook\n path; it must stay first-class, not a legacy fallback (the repo's own\n webhook-intake rule). It is **one shared scan over all `pr_open` tasks**,\n not a scan inside each identity's poll loop, and it calls the forge client\n the scanned task's own identity owns. This is `reconcilePRs`'s shape\n exactly (`internal/daemon/daemon.go`: `Store.OpenPRs` then `forgeFor(\u0026t)`).\n A per-identity scan would call one identity's forge client against another\n identity's PR.\n\nBoth paths emit the **same** typed reaction, so `PublishUnique` dedups them\nfor free — the `TaskEnvelope.IdempotencyKey` pattern (7d5u decision 4) applied\nto reviews.\n\n### 3. Reaction contract: producer-only, resolves to an existing task\n\nA new `workintake.ReviewCommentEnvelope{Owner, Repo, PRNumber, Kind, CommentID,\nReviewID, Author, State, Body, Path, Line}`. Idempotency key is\n`owner/repo/pr-number/kind/id` — source-independent, so a webhook delivery\nand a poll of the same comment collapse.\n\n`Kind` (`review` or `comment`) is part of the key because a review ID and a\nreview-comment ID come from independent forge sequences. Keying on the bare id\nlets a review and an inline comment on the same PR collide, silently dropping\none of the two. This is a producer-only reaction\n(7d5u decision 3): it never vetoes or mutates in-flight work; the target task\nis idle (`pr_open`).\n\nThe daemon resolves `PRNumber` → the task that owns it. An unmatched PR (not\nan archie task) is dropped with a counter — a public webhook must not be able\nto start an agent against an arbitrary repository. A PR whose task is merged,\nclosed or archived is dropped through the same counter: the reaction is only\never work against a PR archie itself opened _and still owns_.\n\nThat lookup does not exist. `pr_number` is written by\n`internal/infrastructure/postgres/store.go` and never read in a `WHERE` clause, so this needs a\n`TaskStore` method keyLine truncated
},
{
"url": "/dev/prds/progressive-tool-disclosure/",
"title": "Progressive tool disclosure (bridge tools) — wiring",
"section": "PRDs",
"body": "# Progressive tool disclosure (bridge tools) — wiring\n\n**Status:** Finalised\n**Date:** 2026-08-15\n**Compound:** the \"keep the LLM tool schema small, give full access on demand\" work (issue #167)\n\n## Decision\n\nThe bridge-tool pattern is **implemented and tested** in\n`internal/tools/disclosure.go` (`tool_search`, `tool_describe`, `tool_call`\n+ `ContextPressureGate` + `DisclosureMode`, section 17.14/17.15) — but it is\n**never wired into the daemon**. `BridgeTools` and `ContextPressureGate` are\nreferenced only in `disclosure_test.go`. This task is therefore a **wiring**\ntask, not a feature build.\n\nWire the existing bridge into the per-chat-turn toolset:\n\n1. **Compose a per-turn registry** seeded from the base registry plus the\n per-turn extra tools, register the bridge tools into it, and hand it to both\n the bridge handlers and the `ContextPressureGate`.\n2. **Run the gate in `chatGenerateOptions`** (`internal/app/archied/main.go`)\n so it decides full-vs-bridge disclosure per turn, and build the\n `core.ToolSet` from the gate's filtered output.\n3. **Thread the model's context window** into the preparation seam so the gate\n has a real `ContextWindowSize` (it disables itself at 0, falling back to\n full disclosure).\n\n## Why the naive \"register extras into the base registry\" is wrong\n\n`BuildToolSetFrom` (`internal/agentexec/toolset.go`) documents the invariant:\n\n\u003e the task tools carry the calling gateway's identity, so there is one set of\n\u003e them per gateway and they **cannot live in the process-wide registry**.\n\nThis is confirmed by wiring: gateways are per-channel\n(`telegram_setup.go` build a `TurnRunner` per channel), and the extra\ntools (`task_*`, `session_*`, `dashboard_*`) close over that channel's identity\nvia `TurnRunnerConfig` (`turn.go`). Registering them into `b.toolReg` would\nlet channel A's session/identity-bound tools be invoked by channel B — a real\ncross-channel privilege bug. The bridge handlers iterate `reg.All()`\n(`disclosure.go`), so the extras must be discoverable; the fix is a\n**per-turn composed registry**, not a mutation of the process-wide one.\n\n## Shape of the change\n\n### 1. Per-turn composed registry + gate inside `chatGenerateOptions`\n\nReplace the current base-set + extra-set merge (`main.go`) with a single\ncomposed-registry pass:\n\n```go\n// new helper, in internal/tools/disclosure.go or the archied wiring package\nfunc ComposeForTurn(reg *tools.Registry, extra []tools.ToolEntry) (*tools.Registry, error) {\n composed := tools.NewRegistry()\n for _, e := range reg.All() {\n if err := composed.Register(e); err != nil { return nil, err }\n }\n for _, e := range extra {\n if err := composed.Register(e); err != nil { return nil, err }\n }\n if _, err := composed.RegisterBatch(tools.BridgeTools(composed)); err != nil {\n return nil, err\n }\n return composed, nil\n}\n```\n\n`chatGenerateOptions` then:\n\n```go\ncomposed, err := ComposeForTurn(registry, extra)\n// ...\ngate := tools.NewContextPressureGate(contextWindow)\ngate.SetAlwaysVisible(...) // e.g. session/session_resume, task/task_list\ndisclosed := gate.FilterTools(composed)\ntoolSet, err := agentexec.BuildToolSetFrom(disclosed, toolOpts)\n```\n\n`FilterTools` (`disclosure.go`) already returns `all` in full mode and\n`bridge + always-visible` in bridge mode, and `BuildToolSetFrom` re-applies\navailability/approval/schema rules, so the two layers compose cleanly.\n\n### 2. Thread context window through the preparation seam\n\n`ContextPressureGate` disables at `ContextWindowSize == 0`. The model context\nwindow is resolved in `TurnRunner.prepareTurn` (`turn.go`) but is not\npassed to `TurnModel.Prepare`. Extend the seam:\n\n```go\ntype TurnPrepareContext struct {\n Model string\n Extra []tools.ToolEntry\n ContextWindow int // model's context window in tokens; 0 = gate disabled\n}\n```\n\n`TurnModel.Prepare(ctx, context TurnPrepareContext)`; `prepareTurn` fills\n`ContextWindow` from `modelDetails.ContextWindow`. This touches one interface\n(`turn.go`), one production impl (`chat_turn_model.go`), and the test\nmock (`turn_test.go`).\n\n### 3. Bridge-handler parity note\n\n`bridgeCallHandler` calls `e.Handler` directly (`disclosure.go`), bypassing\n`toolExecute` — so a `tool_call` invocation does **not** apply `CapPayload` /\n`MaxResultSizeChars` spilling or `OnToolCall` reporting, and it pre-refuses\n`RequiresApproval` tools (`disclosure.go`). This is acceptable for the\nfirst wiring (the bridge is read-discover/describe plus a guarded call), but a\nlater hardening should route the invoked tool through the same\ncap/approval path the model's direct call uses. Recorded as a follow-up, not a\nblocker for this task.\n\n## Files touched\n\n- `internal/app/archied/main.go` — `chatGenerateOptions` composes + gates.\n- `internal/app/archied/chat_turn_model.go` — `PreLine truncated
"body": "# Progressive tool disclosure (bridge tools) — wiring\n\n**Status:** Finalised\n**Date:** 2026-08-15\n**Compound:** the \"keep the LLM tool schema small, give full access on demand\" work (issue #167)\n\n## Decision\n\nThe bridge-tool pattern is **implemented and tested** in\n`internal/tools/disclosure.go` (`tool_search`, `tool_describe`, `tool_call`\n\n- `ContextPressureGate` + `DisclosureMode`, section 17.14/17.15) — but it is\n **never wired into the daemon**. `BridgeTools` and `ContextPressureGate` are\n referenced only in `disclosure_test.go`. This task is therefore a **wiring**\n task, not a feature build.\n\nWire the existing bridge into the per-chat-turn toolset:\n\n1. **Compose a per-turn registry** seeded from the base registry plus the\n per-turn extra tools, register the bridge tools into it, and hand it to both\n the bridge handlers and the `ContextPressureGate`.\n2. **Run the gate in `chatGenerateOptions`** (`internal/app/archied/main.go`)\n so it decides full-vs-bridge disclosure per turn, and build the\n `core.ToolSet` from the gate's filtered output.\n3. **Thread the model's context window** into the preparation seam so the gate\n has a real `ContextWindowSize` (it disables itself at 0, falling back to\n full disclosure).\n\n## Why the naive \"register extras into the base registry\" is wrong\n\n`BuildToolSetFrom` (`internal/agentexec/toolset.go`) documents the invariant:\n\n\u003e the task tools carry the calling gateway's identity, so there is one set of\n\u003e them per gateway and they **cannot live in the process-wide registry**.\n\nThis is confirmed by wiring: gateways are per-channel\n(`telegram_setup.go` build a `TurnRunner` per channel), and the extra\ntools (`task_*`, `session_*`, `dashboard_*`) close over that channel's identity\nvia `TurnRunnerConfig` (`turn.go`). Registering them into `b.toolReg` would\nlet channel A's session/identity-bound tools be invoked by channel B — a real\ncross-channel privilege bug. The bridge handlers iterate `reg.All()`\n(`disclosure.go`), so the extras must be discoverable; the fix is a\n**per-turn composed registry**, not a mutation of the process-wide one.\n\n## Shape of the change\n\n### 1. Per-turn composed registry + gate inside `chatGenerateOptions`\n\nReplace the current base-set + extra-set merge (`main.go`) with a single\ncomposed-registry pass:\n\n```go\n// new helper, in internal/tools/disclosure.go or the archied wiring package\nfunc ComposeForTurn(reg *tools.Registry, extra []tools.ToolEntry) (*tools.Registry, error) {\n composed := tools.NewRegistry()\n for _, e := range reg.All() {\n if err := composed.Register(e); err != nil { return nil, err }\n }\n for _, e := range extra {\n if err := composed.Register(e); err != nil { return nil, err }\n }\n if _, err := composed.RegisterBatch(tools.BridgeTools(composed)); err != nil {\n return nil, err\n }\n return composed, nil\n}\n```\n\n`chatGenerateOptions` then:\n\n```go\ncomposed, err := ComposeForTurn(registry, extra)\n// ...\ngate := tools.NewContextPressureGate(contextWindow)\ngate.SetAlwaysVisible(...) // e.g. session/session_resume, task/task_list\ndisclosed := gate.FilterTools(composed)\ntoolSet, err := agentexec.BuildToolSetFrom(disclosed, toolOpts)\n```\n\n`FilterTools` (`disclosure.go`) already returns `all` in full mode and\n`bridge + always-visible` in bridge mode, and `BuildToolSetFrom` re-applies\navailability/approval/schema rules, so the two layers compose cleanly.\n\n### 2. Thread context window through the preparation seam\n\n`ContextPressureGate` disables at `ContextWindowSize == 0`. The model context\nwindow is resolved in `TurnRunner.prepareTurn` (`turn.go`) but is not\npassed to `TurnModel.Prepare`. Extend the seam:\n\n```go\ntype TurnPrepareContext struct {\n Model string\n Extra []tools.ToolEntry\n ContextWindow int // model's context window in tokens; 0 = gate disabled\n}\n```\n\n`TurnModel.Prepare(ctx, context TurnPrepareContext)`; `prepareTurn` fills\n`ContextWindow` from `modelDetails.ContextWindow`. This touches one interface\n(`turn.go`), one production impl (`chat_turn_model.go`), and the test\nmock (`turn_test.go`).\n\n### 3. Bridge-handler parity note\n\n`bridgeCallHandler` calls `e.Handler` directly (`disclosure.go`), bypassing\n`toolExecute` — so a `tool_call` invocation does **not** apply `CapPayload` /\n`MaxResultSizeChars` spilling or `OnToolCall` reporting, and it pre-refuses\n`RequiresApproval` tools (`disclosure.go`). This is acceptable for the\nfirst wiring (the bridge is read-discover/describe plus a guarded call), but a\nlater hardening should route the invoked tool through the same\ncap/approval path the model's direct call uses. Recorded as a follow-up, not a\nblocker for this task.\n\n## Files touched\n\n- `internal/app/archied/main.go` — `chatGenerateOptions` composes + gates.\n- `internal/app/archied/chat_turn_model.go` Line truncated
},
{
"url": "/dev/prds/public-and-dev-docs/",
"title": "Public and development documentation -- design",
"section": "PRDs",
"body": "# Public and development documentation -- design\n\n**Status:** Draft\n**Date:** 2026-09-22\n\n## Problem\n\nOne published set carries both kinds of document. A reader who wants to know\nwhat Archie is and how to point an event at it lands in a sidebar that also\nholds the repository organisation rules, the migration decision register, the\npackage review procedure and five PRDs. The PRDs are there for a reason that\nhas nothing to do with the reader: settled architecture cites them, and the\ngenerator refuses a link whose target it holds back, so publishing them was the\nonly way to keep those citations alive.\n\nMixing them is not an exposure problem. Every one of these documents can be\npublic. It is a navigation problem: a customer reading the site meets\ncontributor material with no signal that it is not for them.\n\n## Decision\n\nOne source tree, two published sets, two artifacts, two URL bases.\n\n| Set | Holds | Served under | Artifact |\n|---|---|---|---|\n| Public | `index.md`, `guides/` | `/docs/` | `docs/data/generated/docs.json` |\n| Development | `architecture/`, `prds/` | `/dev/` | `docs/data/generated/dev-docs.json` |\n\n`archive/`, `inspiration/`, `news/` and `github-token.md` stay out of both, for\nthe reasons the generator already records.\n\nThe two artifacts have the same shape. A renderer reads a second file and\nserves it under a second base; it needs no new field and no set discriminator,\nbecause the file a page arrived in is the set it belongs to.\n\n## Consequences the design depends on\n\n**Every PRD publishes.** Selective PRD publication existed to keep citations\nfrom settled architecture working. With both cited and citing documents in the\ndevelopment set, that pressure is gone, and the rule that produced it goes with\nit: `prds/` is a development tree, not a list of exceptions.\n\n**Cross-set links resolve.** A link from a public page to an architecture page\nrewrites to the development set's absolute path, and the reverse works the same\nway. Both sets are generated in one pass over one url map, so a link and its\ntarget cannot disagree about where the target lives. The generator's refusal\nstill fires, now only for a target genuinely in neither set.\n\n**Assets keep the public base.** `docs/public/` is one file set, referenced\nfrom either set, and serving one file under two paths would invent a second\nlocation for it.\n\n**The sidebar stays derived from the directory layout**, per set. A page added\nunder a directory appears without a second edit, which is the property the\ncurrent generator has and the reason its tree mirrors the tree on disk.\n\n## The public set is thin, and that is the honest state\n\nTwo pages: the landing page and the playbook guide. Nothing is lost by the\nsplit, because a reader was never served by the seventeen architecture pages\nnext to them. The pages a public site needs (installation, configuration\nreference, the event sources, the actions a playbook can run) are written into\n`guides/` and a `reference/` tree as they are written, and each lands in the\npublic set with no generator change.\n\n## Verification\n\n- `task docs:artifact` writes both files; `task docs:artifact:check` fails on a\n stale copy of either, without touching the tree.\n- A link from the public set to a development page, and a link the other way,\n each resolve to the other set's base path in the generated body.\n- A link to a page in neither set fails the generator, naming the file, the\n line and the target.\n- `docsgen` accounts for both artifacts, so neither tool reports the other's\n file as unowned.\n"
"body": "# Public and development documentation -- design\n\n**Status:** Draft\n**Date:** 2026-09-22\n\n## Problem\n\nOne published set carries both kinds of document. A reader who wants to know\nwhat Archie is and how to point an event at it lands in a sidebar that also\nholds the repository organisation rules, the migration decision register, the\npackage review procedure and five PRDs. The PRDs are there for a reason that\nhas nothing to do with the reader: settled architecture cites them, and the\ngenerator refuses a link whose target it holds back, so publishing them was the\nonly way to keep those citations alive.\n\nMixing them is not an exposure problem. Every one of these documents can be\npublic. It is a navigation problem: a customer reading the site meets\ncontributor material with no signal that it is not for them.\n\n## Decision\n\nOne source tree, two published sets, two artifacts, two URL bases.\n\n| Set | Holds | Served under | Artifact |\n| ----------- | ------------------------ | ------------ | ----------------------------------- |\n| Public | `index.md`, `guides/` | `/docs/` | `docs/data/generated/docs.json` |\n| Development | `architecture/`, `prds/` | `/dev/` | `docs/data/generated/dev-docs.json` |\n\n`archive/`, `inspiration/`, `news/` and `github-token.md` stay out of both, for\nthe reasons the generator already records.\n\nThe two artifacts have the same shape. A renderer reads a second file and\nserves it under a second base; it needs no new field and no set discriminator,\nbecause the file a page arrived in is the set it belongs to.\n\n## Consequences the design depends on\n\n**Every PRD publishes.** Selective PRD publication existed to keep citations\nfrom settled architecture working. With both cited and citing documents in the\ndevelopment set, that pressure is gone, and the rule that produced it goes with\nit: `prds/` is a development tree, not a list of exceptions.\n\n**Cross-set links resolve.** A link from a public page to an architecture page\nrewrites to the development set's absolute path, and the reverse works the same\nway. Both sets are generated in one pass over one url map, so a link and its\ntarget cannot disagree about where the target lives. The generator's refusal\nstill fires, now only for a target genuinely in neither set.\n\n**Assets keep the public base.** `docs/public/` is one file set, referenced\nfrom either set, and serving one file under two paths would invent a second\nlocation for it.\n\n**The sidebar stays derived from the directory layout**, per set. A page added\nunder a directory appears without a second edit, which is the property the\ncurrent generator has and the reason its tree mirrors the tree on disk.\n\n## The public set is thin, and that is the honest state\n\nTwo pages: the landing page and the playbook guide. Nothing is lost by the\nsplit, because a reader was never served by the seventeen architecture pages\nnext to them. The pages a public site needs (installation, configuration\nreference, the event sources, the actions a playbook can run) are written into\n`guides/` and a `reference/` tree as they are written, and each lands in the\npublic set with no generator change.\n\n## Verification\n\n- `task docs:artifact` writes both files; `task docs:artifact:check` fails on a\n stale copy of either, without touching the tree.\n- A link from the public set to a development page, and a link the other way,\n each resolve to the other set's base path in the generated body.\n- A link to a page in neither set fails the generator, naming the file, the\n line and the target.\n- `docsgen` accounts for both artifacts, so neither tool reports the other's\n file as unowned.\n"
},
{
"url": "/dev/prds/release-stream-and-commit-rules/",
"title": "One release stream, one page per version, and commit rules — decision",
"section": "PRDs",
"body": "# One release stream, one page per version, and commit rules — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** `RELEASING.md` for the process this changes, `AGENTS.md` for the\ncommit rules it enforces, and `tools/newsgen` for the artifact shape.\n\n**Supersedes:** `docs/prds/news-and-releases.md`, sections \"Source of truth\" and\n\"Two components\" — one changelog replaces two, and one page per version replaces\none page per component. Its remaining decisions stand.\n\n## Decision\n\n**A release is one version covering whatever changed.** One changelog holds every\nrelease section, one generated page holds every version's notes, and an operator\ncutting a release names one version.\n\n## One changelog\n\nEvery release section lives in `CHANGELOG.md`, newest first. `CHANGELOG.archied.md`\nand `CHANGELOG.archie.md` are deleted, and `CHANGELOG.md` stops being a pointer to\nthem. The changelog is the only source of release prose, and tags are not a source:\nCI and deployment check out shallow, so tags are absent from a site build while the\nchangelog is always present.\n\n### The merged history\n\nTwo version streams become one file, so a version that both components released\ncarries one heading and one date: **the newest date among that version's sections**,\nbecause a version's date is when the last part of it shipped. Where a component's own\ndate differs from it, that component's section label carries its own date, so the\nper-component fact survives the merge rather than being collapsed into the heading.\n\nThe merged history holds 65 versions: 33 that both components released, 31 only\n`archied`, and one only `archie`, from 64 and 34 sections respectively, so 98\npublished pages become 65. `## [Unreleased]` is not a release -- it carries no\nversion and gets no page -- but it stays at the top of the file, because it is\nthe one place unfinished work is recorded. Counting `##` headings rather than\nreleases overcounts by one.\n\nThis ambiguity is historical only. One version stream with one tag gives a version\nexactly one date, so the rule represents the merged past rather than a design that has\nto hold.\n\nThe merge is verified by content, not by the generator succeeding: the section count\nper source, the merged version set equal to the union of both sources with nothing\nextra, and every section title still present. A generator that agrees with the file it\njust wrote is evidence of nothing.\n\n## One version stream\n\n**`GATEWAY` and `RUNTIME` stop being release inputs.** `release:prepare` and\n`release:tag` take one version, and `tools/release.sh` loses the two flags.\n\nThey may stay as build-time stamps, because a binary must still report what it\ncontains. A release that must name three versions forces an operator to pass skip\nvalues for components that did not change, and that ceremony is what this decision\nremoves — along with the drift it allows, where two components' tags fall a release\napart.\n\n**Per-component detail stays, as sections inside the release.** A reader still needs\nto know whether `archied` or the agent changed; what goes away is the separate\nnumbers and the separate pages, not the information.\n\n**History is not re-tagged.** Existing tags keep their names, because tags are not a\nsource and nothing reads them to build a page. A future reader must not \"fix\" the\nunified changelog by rewriting tags to match it.\n\n## One release page per version\n\n`docs/news/\u003cversion\u003e.md` replaces `docs/news/\u003ccomponent\u003e/\u003cversion\u003e.md`, carrying the\nrelease's per-component sections inside it.\n\n**Every release URL already published keeps working.** `/news/archied/\u003cversion\u003e` and\n`/news/archie/\u003cversion\u003e` route to the unified page for that version. The generator\nemits the redirect table beside the pages so it cannot drift from them; if the\nrenderer needs the table in its own repository, that is a change in that repository\nrather than a hand-maintained list here.\n\n## The reviewer runs between prepare and tag\n\nRelease notes are prose, and the review agent exists to review prose. **`release:tag`\nrefuses to tag when the review has not been run for that version, or when it reports\nat the level.**\n\nThe invocation is verified rather than assumed. `tl rules --lint` reports `corpus ok`\nand exits 0. `tl review \u003cpath\u003e --deadline \u003cms\u003e --max-turns \u003cn\u003e` reports\n`0 findings (0 high, 0 medium) · 1/1 files reviewed · clean` and exits 0 on\n`docs/news/archied/1.36.0.md`.\n\n**`--fail-on` must be passed explicitly.** It defaults to `never`, so an invocation\nwithout it cannot refuse anything and the step would be decorative. `--fail-on high`\nis the level: a medium finding in a release note is worth acting on, and it should not\nstop a release on its own.\n\n**The rule is stated once.** It belongs in the reviewer's own rule set, which\n`tl rules --from-doc` can draft frLine truncated
"body": "# One release stream, one page per version, and commit rules — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** `RELEASING.md` for the process this changes, `AGENTS.md` for the\ncommit rules it enforces, and `tools/newsgen` for the artifact shape.\n\n**Supersedes:** `docs/prds/news-and-releases.md`, sections \"Source of truth\" and\n\"Two components\" — one changelog replaces two, and one page per version replaces\none page per component. Its remaining decisions stand.\n\n## Decision\n\n**A release is one version covering whatever changed.** One changelog holds every\nrelease section, one generated page holds every version's notes, and an operator\ncutting a release names one version.\n\n## One changelog\n\nEvery release section lives in `CHANGELOG.md`, newest first. `CHANGELOG.archied.md`\nand `CHANGELOG.archie.md` are deleted, and `CHANGELOG.md` stops being a pointer to\nthem. The changelog is the only source of release prose, and tags are not a source:\nCI and deployment check out shallow, so tags are absent from a site build while the\nchangelog is always present.\n\n### The merged history\n\nTwo version streams become one file, so a version that both components released\ncarries one heading and one date: **the newest date among that version's sections**,\nbecause a version's date is when the last part of it shipped. Where a component's own\ndate differs from it, that component's section label carries its own date, so the\nper-component fact survives the merge rather than being collapsed into the heading.\n\nThe merged history holds 65 versions: 33 that both components released, 31 only\n`archied`, and one only `archie`, from 64 and 34 sections respectively, so 98\npublished pages become 65. `## [Unreleased]` is not a release -- it carries no\nversion and gets no page -- but it stays at the top of the file, because it is\nthe one place unfinished work is recorded. Counting `##` headings rather than\nreleases overcounts by one.\n\nThis ambiguity is historical only. One version stream with one tag gives a version\nexactly one date, so the rule represents the merged past rather than a design that has\nto hold.\n\nThe merge is verified by content, not by the generator succeeding: the section count\nper source, the merged version set equal to the union of both sources with nothing\nextra, and every section title still present. A generator that agrees with the file it\njust wrote is evidence of nothing.\n\n## One version stream\n\n**`GATEWAY` and `RUNTIME` stop being release inputs.** `release:prepare` and\n`release:tag` take one version, and `tools/release.sh` loses the two flags.\n\nThey may stay as build-time stamps, because a binary must still report what it\ncontains. A release that must name three versions forces an operator to pass skip\nvalues for components that did not change, and that ceremony is what this decision\nremoves — along with the drift it allows, where two components' tags fall a release\napart.\n\n**Per-component detail stays, as sections inside the release.** A reader still needs\nto know whether `archied` or the agent changed; what goes away is the separate\nnumbers and the separate pages, not the information.\n\n**History is not re-tagged.** Existing tags keep their names, because tags are not a\nsource and nothing reads them to build a page. A future reader must not \"fix\" the\nunified changelog by rewriting tags to match it.\n\n## One release page per version\n\n`docs/news/\u003cversion\u003e.md` replaces `docs/news/\u003ccomponent\u003e/\u003cversion\u003e.md`, carrying the\nrelease's per-component sections inside it.\n\n**Every release URL already published keeps working.** `/news/archied/\u003cversion\u003e` and\n`/news/archie/\u003cversion\u003e` route to the unified page for that version. The generator\nemits the redirect table beside the pages so it cannot drift from them; if the\nrenderer needs the table in its own repository, that is a change in that repository\nrather than a hand-maintained list here.\n\n## The reviewer runs between prepare and tag\n\nRelease notes are prose, and the review agent exists to review prose. **`release:tag`\nrefuses to tag when the review has not been run for that version, or when it reports\nat the level.**\n\nThe invocation is verified rather than assumed. `tl rules --lint` reports `corpus ok`\nand exits 0. `tl review \u003cpath\u003e --deadline \u003cms\u003e --max-turns \u003cn\u003e` reports\n`0 findings (0 high, 0 medium) · 1/1 files reviewed · clean` and exits 0 on\n`docs/news/archied/1.36.0.md`.\n\n**`--fail-on` must be passed explicitly.** It defaults to `never`, so an invocation\nwithout it cannot refuse anything and the step would be decorative. `--fail-on high`\nis the level: a medium finding in a release note is worth acting on, and it should not\nstop a release on its own.\n\n**The rule is stated once.** It belongs in the reviewer's own rule set, which\n`tl rules --from-doc` can draft frLine truncated
},
{
"url": "/dev/prds/review-calibration/",
"title": "Review calibration -- decision",
"section": "PRDs",
"body": "# Review calibration -- decision\n\n**Status:** Draft\n**Beads issue:** `archie-core-h019.5` (parent `archie-core-h019`)\n\nDecides the half of calibration `docs/prds/adversarial-self-review.md` left\nopen: \"the adversarial-confirmation mechanism that keeps a finding from\nsurfacing on a single reviewer's say-so.\"\n\n## The problem, precisely\n\nThe shipped contract (`internal/domain/workflow/review_findings.go`, h019.2)\nalready makes only a **confirmed** error-level finding block\n(`Blocking() == Verdict == confirmed \u0026\u0026 Level == error`), and a zero-finding\nreview is already distinguishable from one that never ran (`ReviewStatus`).\nWhat is missing is the other half: a reviewer can report *nothing*\nand say only \"I found nothing\" in free text. The operator cannot tell \"I\nchecked the five things that matter and they are clean\" from \"I did not look.\"\nThat is the failure the epic names -- a findings surface that consumes attention\nwithout earning trust.\n\n## Decisions\n\n### 1. \"Checked and cleared\" becomes structured, not prose\n\n`ReviewReport` gains `Checked []ReviewCheck`:\n\n```go\ntype ReviewCheck struct {\n Property string // what was verified clean, e.g. \"nil-safety of Foo callers\"\n Evidence string // how it was verified, e.g. \"read all 4 callers; each nil-checks\"\n}\n```\n\n`Evidence` is required, for the same reason `ReviewFinding.FailureScenario` is:\na check without evidence is an assertion, and the whole point is to separate a\nverified property from an unexamined one. A zero-finding review is credible\nonly when it lists what it checked.\n\n### 2. Report checks through a typed tool, like findings\n\nThe reviewer calls a new capture tool `record_checked` (mirroring\n`record_finding`) once per property it verified clean. The same environmental\nargument as findings applies: the reviewer cannot end its turn having silently\nskipped the checklist. `ReviewReport.Summary` stays as the human overview.\n\n### 3. Style nits are out of contract\n\nA finding must describe wrong behaviour or a crash. Style, formatting, naming,\nand preference nits are explicitly out of contract -- they are the padding that\ntrains the operator to skim. Stated in the reviewer prompt and in the\n`ReviewFinding` type's own documentation. Not machine-enforced: deciding \"is\nthis a style nit\" from free text is unreliable, and a wrong rejection is worse\nthan a tolerated one. The category enum already has no style bucket; the rule\ncloses the gap that would otherwise let one hide under `other`.\n\n### 4. Surfacing\n\nThe PR-body findings section lists the cleared properties alongside findings,\nso \"ran and found nothing\" arrives with its evidence. (Park reasons keep\nrendering only blocking findings -- what a human needs to act on, not the full\nchecklist.)\n\n## What this does not decide\n\n- Adding a second, independent reviewer pass. The verdict distinction plus the\n recorded checks is the confirmation mechanism; a second model pass is a\n separate, heavier decision and nothing in `h019.5` requires it.\n- How many findings can survive before `MaxSteps` is exhausted (a budget\n question, already satisfied by the per-stage budget).\n\n## Packages this touches\n\n- `internal/domain/workflow` -- `ReviewCheck`, `ReviewReport.Checked`, validation.\n- `internal/app/agentworker` -- `record_checked` tool, prompt rules.\n- `internal/domain/workflow/review.go` -- render cleared properties on the PR body.\n"
"body": "# Review calibration -- decision\n\n**Status:** Draft\n**Beads issue:** `archie-core-h019.5` (parent `archie-core-h019`)\n\n\u003e Superseded by `docs/prds/pr-review-agent.md`.\n\nDecides the half of calibration `docs/prds/adversarial-self-review.md` left\nopen: \"the adversarial-confirmation mechanism that keeps a finding from\nsurfacing on a single reviewer's say-so.\"\n\n## The problem, precisely\n\nThe shipped contract (`internal/domain/workflow/review_findings.go`, h019.2)\nalready makes only a **confirmed** error-level finding block\n(`Blocking() == Verdict == confirmed \u0026\u0026 Level == error`), and a zero-finding\nreview is already distinguishable from one that never ran (`ReviewStatus`).\nWhat is missing is the other half: a reviewer can report _nothing_\nand say only \"I found nothing\" in free text. The operator cannot tell \"I\nchecked the five things that matter and they are clean\" from \"I did not look.\"\nThat is the failure the epic names -- a findings surface that consumes attention\nwithout earning trust.\n\n## Decisions\n\n### 1. \"Checked and cleared\" becomes structured, not prose\n\n`ReviewReport` gains `Checked []ReviewCheck`:\n\n```go\ntype ReviewCheck struct {\n Property string // what was verified clean, e.g. \"nil-safety of Foo callers\"\n Evidence string // how it was verified, e.g. \"read all 4 callers; each nil-checks\"\n}\n```\n\n`Evidence` is required, for the same reason `ReviewFinding.FailureScenario` is:\na check without evidence is an assertion, and the whole point is to separate a\nverified property from an unexamined one. A zero-finding review is credible\nonly when it lists what it checked.\n\n### 2. Report checks through a typed tool, like findings\n\nThe reviewer calls a new capture tool `record_checked` (mirroring\n`record_finding`) once per property it verified clean. The same environmental\nargument as findings applies: the reviewer cannot end its turn having silently\nskipped the checklist. `ReviewReport.Summary` stays as the human overview.\n\n### 3. Style nits are out of contract\n\nA finding must describe wrong behaviour or a crash. Style, formatting, naming,\nand preference nits are explicitly out of contract -- they are the padding that\ntrains the operator to skim. Stated in the reviewer prompt and in the\n`ReviewFinding` type's own documentation. Not machine-enforced: deciding \"is\nthis a style nit\" from free text is unreliable, and a wrong rejection is worse\nthan a tolerated one. The category enum already has no style bucket; the rule\ncloses the gap that would otherwise let one hide under `other`.\n\n### 4. Surfacing\n\nThe PR-body findings section lists the cleared properties alongside findings,\nso \"ran and found nothing\" arrives with its evidence. (Park reasons keep\nrendering only blocking findings -- what a human needs to act on, not the full\nchecklist.)\n\n## What this does not decide\n\n- Adding a second, independent reviewer pass. The verdict distinction plus the\n recorded checks is the confirmation mechanism; a second model pass is a\n separate, heavier decision and nothing in `h019.5` requires it.\n- How many findings can survive before `MaxSteps` is exhausted (a budget\n question, already satisfied by the per-stage budget).\n\n## Packages this touches\n\n- `internal/domain/workflow` -- `ReviewCheck`, `ReviewReport.Checked`, validation.\n- `internal/app/agentworker` -- `record_checked` tool, prompt rules.\n- `internal/domain/workflow/review.go` -- render cleared properties on the PR body.\n"
},
{
"url": "/dev/prds/runtime-control-plane/",
"title": "Runtime control plane",
"section": "PRDs",
"body": "# Runtime control plane\n\n**Status:** Approved \n**Date:** 2026-09-20 \n**Tracking:** `archie-core-j28m`, `archie-core-1786637498420-327-bacadaae`\n\n## Outcome\n\nArchie can be managed from the Web UI or a messaging channel. Both use the same\nAPI.\n\n## Model\n\nEach feature owns its settings and commands. The database stores them. There is\nno global configuration document.\n\nThis includes:\n\n- workflows;\n- identities and bindings;\n- providers and models;\n- repository policies;\n- channels and schedules;\n- capture mappings and bindings;\n- tool settings;\n- prompts and personas;\n- plugin settings.\n\nPlugin code remains installed code. Only its settings are stored in the\ndatabase.\n\nEach feature defines its data, validation, permissions, editor fields, and how\nchanges take effect. Each feature also defines its allowed actions. For example,\nidentities can be created, suspended, and retired.\n\nRepository and identity settings remain separate. They are not stored as large\nrecords that unrelated features must share.\n\nThe State Store process hosts the control-plane API on its existing gRPC server.\nNo new process is added. Feature code validates changes. Storage code only\nwrites versions and audit records.\n\nEvery write records who made it, where it came from, a request ID, and the\nversion being edited. The API layer sets the actor; the request body cannot.\nThe server validates the change, then writes it with its audit record. It rejects\nedits to an old version.\n\n## API\n\nThe API has four operations:\n\n1. **Catalog** tells clients what can be viewed or changed and how to edit it.\n2. **Query** reads data and versions without exposing secrets.\n3. **Command** asks the owning feature to make a change.\n4. **Watch** streams changes and errors to clients.\n\nComplex features can use custom screens. They still use the same commands.\n\nA dashboard session or channel sender must map to an Archie identity before it\ncan run a command. Messaging syntax maps to the same commands as the Web UI.\n\n`archie-ui` receives only an API client. It does not receive a database handle,\ndaemon pointer, global configuration object, or secret value.\n\nThe database stores the requested settings. Each process reports the version it\nis using or why it failed. The UI shows both.\n\nSome changes require a restart. The UI shows them as pending. When a live change\nreplaces a running component, Archie starts and checks the new one before\nswitching. If the check fails, the old one keeps running.\n\n## Bootstrap, migration, and recovery\n\nBootstrap contains only the database path, listen addresses, credentials, TLS,\nand encryption-key references. State Store and control-plane RPCs use the same\nendpoint.\n\nWhen upgraded, existing instances are migrated to the database. Existing\ndatabase values are not overwritten. After migration, settings in TOML are\nignored and cannot block State Store startup.\n\nThe Web UI remains available when `archied` or Gateway is down. It shows failed\nchanges and can correct or roll them back.\n\nOffline commands can back up, restore, validate, and roll back the database.\nRecovery does not require `archied` or the Web UI. The database stores secret\nreferences, not secret values.\n\n## Workflows\n\nUsers create and edit workflows in the Web UI. Workflows are stored as versioned\nYAML. Built-in workflows can be overridden and restored.\n\nA workflow is a list of steps. Each step has a known type and its own settings.\nPlugins can add step types. Each run keeps the workflow version it started with.\n\nYaegi, `.archie/stages/*.go`, and `.archie/gate.go` will be removed. Their useful\nbehavior must first be available as normal workflow steps.\n\n## First implementation\n\nThe first implementation makes task limits editable: maximum model steps,\nmaximum runtime, and maximum consecutive gate failures.\n\nIt includes:\n\n- validated task-limit fields;\n- version history and audit records;\n- the four API operations;\n- authenticated Web UI and messaging access;\n- live updates and apply status;\n- a Pinia-backed editor in the Web UI;\n- a messaging command using the same API;\n- migration of existing `[budgets]` values;\n- an end-to-end restart test.\n\nRunning tasks keep the limits they started with. New tasks use the latest applied\nversion. This replaces the old settings overlay instead of extending it.\n\n## Not included in the first implementation\n\n- Moving bootstrap or secret values into normal settings.\n- A generic JSON editor.\n- Rebuilding every settings screen at once.\n- Changing the limits of a running task.\n"
"body": "# Runtime control plane\n\n**Status:** Approved \n**Date:** 2026-09-20 \n**Tracking:** `archie-core-j28m`, `archie-core-1786637498420-327-bacadaae`\n\n## Outcome\n\nArchie can be managed from the Web UI or a messaging channel. Both use the same\nAPI.\n\n## Model\n\nEach feature owns its settings and commands. The database stores them. There is\nno global configuration document.\n\nThis includes:\n\n- workflows;\n- identities and bindings;\n- providers and models;\n- repository policies;\n- channels and schedules;\n- capture mappings and bindings;\n- tool settings;\n- prompts and personas;\n- plugin settings.\n\nPlugin code remains installed code. Only its settings are stored in the\ndatabase.\n\nEach feature defines its data, validation, permissions, editor fields, and how\nchanges take effect. Each feature also defines its allowed actions. For example,\nidentities can be created, suspended, and retired.\n\nRepository and identity settings remain separate. They are not stored as large\nrecords that unrelated features must share.\n\nThe State Store process hosts the control-plane API on its existing gRPC server.\nNo new process is added. Feature code validates changes. Storage code only\nwrites versions and audit records.\n\nEvery write records who made it, where it came from, a request ID, and the\nversion being edited. The API layer sets the actor; the request body cannot.\nThe server validates the change, then writes it with its audit record. It rejects\nedits to an old version.\n\n## API\n\nThe API has four operations:\n\n1. **Catalogue** tells clients what can be viewed or changed and how to edit it.\n2. **Query** reads data and versions without exposing secrets.\n3. **Command** asks the owning feature to make a change.\n4. **Watch** streams changes and errors to clients.\n\nComplex features can use custom screens. They still use the same commands.\n\nA dashboard session or channel sender must map to an Archie identity before it\ncan run a command. Messaging syntax maps to the same commands as the Web UI.\n\n`archie-ui` receives only an API client. It does not receive a database handle,\ndaemon pointer, global configuration object, or secret value.\n\nThe database stores the requested settings. Each process reports the version it\nis using or why it failed. The UI shows both.\n\nSome changes require a restart. The UI shows them as pending. When a live change\nreplaces a running component, Archie starts and checks the new one before\nswitching. If the check fails, the old one keeps running.\n\n## Bootstrap, migration, and recovery\n\nBootstrap contains only the database path, listen addresses, credentials, TLS,\nand encryption-key references. State Store and control-plane RPCs use the same\nendpoint.\n\nWhen upgraded, existing instances are migrated to the database. Existing\ndatabase values are not overwritten. After migration, settings in TOML are\nignored and cannot block State Store startup.\n\nThe Web UI remains available when `archied` or Gateway is down. It shows failed\nchanges and can correct or roll them back.\n\nOffline commands can back up, restore, validate, and roll back the database.\nRecovery does not require `archied` or the Web UI. The database stores secret\nreferences, not secret values.\n\n## Workflows\n\nUsers create and edit workflows in the Web UI. Workflows are stored as versioned\nYAML. Built-in workflows can be overridden and restored.\n\nA workflow is a list of steps. Each step has a known type and its own settings.\nPlugins can add step types. Each run keeps the workflow version it started with.\n\nYaegi, `.archie/stages/*.go`, and `.archie/gate.go` will be removed. Their useful\nbehaviour must first be available as normal workflow steps.\n\n## First implementation\n\nThe first implementation makes task limits editable: maximum model steps,\nmaximum runtime, and maximum consecutive gate failures.\n\nIt includes:\n\n- validated task-limit fields;\n- version history and audit records;\n- the four API operations;\n- authenticated Web UI and messaging access;\n- live updates and apply status;\n- a Pinia-backed editor in the Web UI;\n- a messaging command using the same API;\n- migration of existing `[budgets]` values;\n- an end-to-end restart test.\n\nRunning tasks keep the limits they started with. New tasks use the latest applied\nversion. This replaces the old settings overlay instead of extending it.\n\n## Not included in the first implementation\n\n- Moving bootstrap or secret values into normal settings.\n- A generic JSON editor.\n- Rebuilding every settings screen at once.\n- Changing the limits of a running task.\n"
},
{
"url": "/dev/prds/self-update-transaction/",
"title": "Self-update: artifact install, topology migration, journaled transaction",
"section": "PRDs",
"body": "# Self-update: artifact install, topology migration, journaled transaction\n\n**Status:** Draft\n\nEpic: `archie-core-hj1t` / GitHub `#804` (\"[EPIC] Self-update: artifact\ninstall, topology migration, journaled transaction\").\n\nThe update *contract* (`internal/releaseupdate`: `Catalog.Check`,\n`Installer.Install`, plus defer/watchdog/verify) is settled and unchanged by\nthis document — it stays a thin Go interface shelling out to\n`CommandCatalog`/`CommandInstaller`. This document decides what the reference\nadapter scripts (`scripts/archie-update-{check,install,watchdog}`) and\n`install.sh` do behind that contract, and settles the one thing the epic's\nown description got wrong: the dist-zip **is** already attached to GitHub\nReleases (`.github/workflows/deploy.yml`, `gh release upload`), not\nActions-artifact-only. Artifact install is therefore a smaller change than\nthe epic assumed — pointing the installer at an existing asset, not standing\nup new CI publishing. Topology migration and the journaled transaction are\ngenuinely greenfield: no topology-detection or transaction-journal code\nexists anywhere in the tree.\n\nOut of scope: rewriting the `internal/releaseupdate` Go interfaces\nthemselves, and any UI for triggering updates (channel dispatch, e.g.\nTelegram `/update`, is unaffected — this only changes what happens once an\ninstall is triggered).\n\n## Problem\n\n`scripts/archie-update-install:139-160` clones and compiles from source on\nevery update — the only path that exists. `deploy.yml` already publishes a\nper-platform archive plus (implicitly) checksums as a release asset, so the\nscript not using it is a missed-reuse gap, not a missing-CI gap.\n`install.sh:414-445` writes only `archied.service` while every shipped\ndeployment profile (`deployments/*.toml`) declares `[services.state]` and\n`[services.gateway]` sections needing their own units — a fresh install\nalready reproduces the broken single-unit shape `deployment_contract_test.go`\ndoesn't even catch, because that test only checks profile\nsyntax, not installed topology. No code anywhere enumerates which systemd\nunits exist on a host or compares that against what a release requires — the\ndaemon fails at `bootstrap.go`'s `[services.state].target` check with no\nprior diagnosis. The self-refresh trap is confirmed at\n`scripts/archie-update-install:195-199`: new adapter copies land on disk but\nbash keeps executing the in-memory copy, so a pre-flight check added to the\nscript only protects the *next* update.\n\n## Design\n\n### Artifact install (`#804` item 1)\n\n**Decision.** `CommandInstaller`'s default script downloads the per-platform\narchive plus `SHA256SUMS` from the GitHub Release that `Catalog.Check`\nresolved (the same release `deploy.yml` already publishes to), verifies the\nchecksum, and stages it — it does not clone/compile. Source build\n(`scripts/archie-update-install`'s current clone+compile body) is kept as an\nopt-in path selected by an explicit `--from-source` flag or\n`ARCHIE_UPDATE_SOURCE_BUILD=1` env var, never the default, since a compile-on\nevery-host update is strictly slower and has a larger failure surface than\ndownloading a signed asset that CI already produced.\n\n**Call site.** `scripts/archie-update-install` — replace the clone+compile\nbody with a download-and-verify step; move the existing\nclone+compile body behind the opt-in flag rather than deleting it.\n`internal/releaseupdate/command.go` (`CommandInstaller`) is unchanged —\nit already just shells out.\n\n**Reuse check.** `deploy.yml` already builds and publishes the\narchive and uploads it as both an Actions artifact and a release asset; no\nnew CI work is needed, only pointing the installer at what exists.\n\n**Testing.** Checksum-verification logic is a shell function, testable with\na fixture archive + `SHA256SUMS` pair — add to whatever test harness already\ncovers `scripts/`. Full download-from-real-release is a manual smoke command\n(document the exact `archie-update-check`/`--dry-run` invocation once built),\nnot `task check`.\n\n### Topology migration (`#804` item 2)\n\n**Decision.** Add a topology *observer* to the daemon, not the shell\nadapter — CLAUDE.md's own \"known trap\" note says the shell copy is defence\nin depth only, and the daemon is what \"knows the deployment and holds the\napproved snapshot.\" The observer inspects which systemd user units exist\n(`systemctl --user list-unit-files 'archie*.service'` or equivalent) and\nwhich config sections are present (`[services.state]`, `[services.gateway]`,\nUI service config), producing an `ObservedTopology` value with one field per\nunit: present/absent, and the config sections backing it. Each release's\n`release.json` (already produced by `deploy.yml` per the artifact-install\nwork above) gains a `required_topology` field naming the units and config\nsections that release's binaries need. `Catalog.Check` compares observed\nagainst requireLine truncated
"body": "# Self-update: artifact install, topology migration, journaled transaction\n\n**Status:** Draft\n\nEpic: `archie-core-hj1t` / GitHub `#804` (\"[EPIC] Self-update: artifact\ninstall, topology migration, journaled transaction\").\n\nThe update _contract_ (`internal/releaseupdate`: `Catalog.Check`,\n`Installer.Install`, plus defer/watchdog/verify) is settled and unchanged by\nthis document — it stays a thin Go interface shelling out to\n`CommandCatalog`/`CommandInstaller`. This document decides what the reference\nadapter scripts (`scripts/archie-update-{check,install,watchdog}`) and\n`install.sh` do behind that contract, and settles the one thing the epic's\nown description got wrong: the dist-zip **is** already attached to GitHub\nReleases (`.github/workflows/deploy.yml`, `gh release upload`), not\nActions-artifact-only. Artifact install is therefore a smaller change than\nthe epic assumed — pointing the installer at an existing asset, not standing\nup new CI publishing. Topology migration and the journaled transaction are\ngenuinely greenfield: no topology-detection or transaction-journal code\nexists anywhere in the tree.\n\nOut of scope: rewriting the `internal/releaseupdate` Go interfaces\nthemselves, and any UI for triggering updates (channel dispatch, e.g.\nTelegram `/update`, is unaffected — this only changes what happens once an\ninstall is triggered).\n\n## Problem\n\n`scripts/archie-update-install:139-160` clones and compiles from source on\nevery update — the only path that exists. `deploy.yml` already publishes a\nper-platform archive plus (implicitly) checksums as a release asset, so the\nscript not using it is a missed-reuse gap, not a missing-CI gap.\n`install.sh:414-445` writes only `archied.service` while every shipped\ndeployment profile (`deployments/*.toml`) declares `[services.state]` and\n`[services.gateway]` sections needing their own units — a fresh install\nalready reproduces the broken single-unit shape `deployment_contract_test.go`\ndoesn't even catch, because that test only checks profile\nsyntax, not installed topology. No code anywhere enumerates which systemd\nunits exist on a host or compares that against what a release requires — the\ndaemon fails at `bootstrap.go`'s `[services.state].target` check with no\nprior diagnosis. The self-refresh trap is confirmed at\n`scripts/archie-update-install:195-199`: new adapter copies land on disk but\nbash keeps executing the in-memory copy, so a pre-flight check added to the\nscript only protects the _next_ update.\n\n## Design\n\n### Artifact install (`#804` item 1)\n\n**Decision.** `CommandInstaller`'s default script downloads the per-platform\narchive plus `SHA256SUMS` from the GitHub Release that `Catalog.Check`\nresolved (the same release `deploy.yml` already publishes to), verifies the\nchecksum, and stages it — it does not clone/compile. Source build\n(`scripts/archie-update-install`'s current clone+compile body) is kept as an\nopt-in path selected by an explicit `--from-source` flag or\n`ARCHIE_UPDATE_SOURCE_BUILD=1` env var, never the default, since a compile-on\nevery-host update is strictly slower and has a larger failure surface than\ndownloading a signed asset that CI already produced.\n\n**Call site.** `scripts/archie-update-install` — replace the clone+compile\nbody with a download-and-verify step; move the existing\nclone+compile body behind the opt-in flag rather than deleting it.\n`internal/releaseupdate/command.go` (`CommandInstaller`) is unchanged —\nit already just shells out.\n\n**Reuse check.** `deploy.yml` already builds and publishes the\narchive and uploads it as both an Actions artifact and a release asset; no\nnew CI work is needed, only pointing the installer at what exists.\n\n**Testing.** Checksum-verification logic is a shell function, testable with\na fixture archive + `SHA256SUMS` pair — add to whatever test harness already\ncovers `scripts/`. Full download-from-real-release is a manual smoke command\n(document the exact `archie-update-check`/`--dry-run` invocation once built),\nnot `task check`.\n\n### Topology migration (`#804` item 2)\n\n**Decision.** Add a topology _observer_ to the daemon, not the shell\nadapter — CLAUDE.md's own \"known trap\" note says the shell copy is defence\nin depth only, and the daemon is what \"knows the deployment and holds the\napproved snapshot.\" The observer inspects which systemd user units exist\n(`systemctl --user list-unit-files 'archie*.service'` or equivalent) and\nwhich config sections are present (`[services.state]`, `[services.gateway]`,\nUI service config), producing an `ObservedTopology` value with one field per\nunit: present/absent, and the config sections backing it. Each release's\n`release.json` (already produced by `deploy.yml` per the artifact-install\nwork above) gains a `required_topology` field naming the units and config\nsections that release's binaries need. `Catalog.Check` compares observed\nagainst requireLine truncated
},
{
"url": "/dev/prds/service-decomposition/",
"title": "Service decomposition -- decision",
"section": "PRDs",
"body": "# Service decomposition -- decision\n\n**Status:** Draft\n**Date:** 2026-09-05\n**Beads epic:** archie-core-8cda\n**Prior art:** `docs/inspiration/2026-09-05-awx-service-decomposition-and-ansible-task-model.md`,\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`,\n`docs/inspiration/service-discovery-research-2026-09-05.md`,\n`/work/artefacts/archie-core-current-state-archify.html`,\n`/work/artefacts/archie-core-ideal-state-archify.html`\n\nThe Phase 3 UI boundary and configuration decision is ratified in\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/). That focused document is\nthe implementation authority for `archie-core-8cda.5.2`; this parent remains\nthe broader service-distribution proposal.\n\n## Decision\n\narchie-core moves from one Go binary (`archied`) hosting every domain\nin-process to a set of independently deployable services, each exposing\nexactly one typed contract. Consumers depend on the contract; they never\nreach into another service's internal types, session state, or config.\ngRPC is the synchronous transport; NATS remains for asynchronous fan-out\n(status, telemetry) rather than being replaced.\n\nThis is a **distribution decision**, not a rewrite of Archie's domain\nmodel. The six-domain split already approved in\n`docs/architecture/index.md` and `docs/architecture/organisation.md`\n(Identity, Agent, Messaging, Workflow, Work Intake, Plugin) is unchanged;\nthis PRD is about how the *processes* running that domain logic get\npackaged, contracted, and discovered -- not about redrawing domain\nboundaries.\n\n### Target services\n\n| Service | Contract it owns | Existing code it replaces/wraps |\n|---|---|---|\n| UI Service | thin client only; talks to Gateway and State Store contracts | `internal/webui` (SPA hosting stays; API surface becomes typed contract clients, not a peer with direct access) |\n| Gateway Service | routing / turn / session contract | `internal/gateway` |\n| Messaging Service | channel-plugin contract (Telegram, email, Discord, Teams, ...) | `internal/channels` |\n| Curator Service | curator contract; **optional**, installs as a Gateway plugin | `internal/domain/curator` |\n| Scheduler Service | cron/ticker contract | `internal/domain/scheduling` |\n| Execution Environment | execution-dispatch contract | `internal/domain/workflow`, task dispatch paths |\n| Runner | isolated worktree/container execution | `internal/container`, `internal/agentexec`, `internal/worktree` |\n| State Store | state-access contract | `internal/store` |\n\n### Discovery\n\nPer `docs/inspiration/service-discovery-research-2026-09-05.md`:\n\n- **Primary:** Kubernetes-native discovery (Service + headless-Service/DNS\n + EndpointSlice, served by CoreDNS), delivered as a Helm chart + Operator,\n on k3s for single-host installs and a real cluster for multi-host or a\n hosted offering.\n- **Fallback:** NATS-based discovery (micro `$SRV` announce + JetStream KV\n registry) for no-K8s single-host installs, with a custom gRPC resolver\n reading `host:port` from the KV bucket.\n- Both implementations sit behind one internal interface:\n\n ```go\n type ServiceRegistry interface {\n Resolve(service string) []Endpoint\n Watch(service string) \u003c-chan Event // join/leave\n }\n ```\n\n- An optional service (Curator; others later) that is not installed\n must resolve to a distinct `NotInstalled` outcome, never a `Down`/\n `Unhealthy` one. Under K8s this falls out of DNS returning no record;\n under the NATS fallback it requires an explicit \"installed\" marker in the\n KV registry, not just absence-implies-down.\n\n### Distribution model this supports\n\nBoth self-hosted (customer runs the Helm chart or the NATS-fallback\nbinaries themselves) and a managed/hosted offering (we run the same Helm\nchart) are in scope -- this is the RHEL / Ansible Automation Platform\nmodel: one architecture, sold both ways. This PRD does not decide the\nbusiness model; it decides that the architecture must not foreclose\neither shape.\n\n## Why this shape\n\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`\nestablished that Archie's existing domain split already does what AWX's\nservice-decomposition post argues for -- boundaries exist. What didn't\nexist was deployability: `internal/webui` was not a passive frontend. The\nre-baselined coupling inventory is below, and the ratified boundary is\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/).\n\n- Telegram task actions now call Gateway's `ChatContract` directly through\n `chatTaskActorAdapter`; the old Telegram-to-webui HTTP detour is historical.\n- `internal/webui/api_chat.go` now holds `gateway.ChatContract`; direct\n `SessionStore`, `Router`, and `TurnHistory` access is historical.\n- The third coupling is closed. UI extraction shipped (`archie-core-8cda.5`,\n closed 2026-09-11): `cmd/archie-ui` serves the dashboard against remote\n Gateway and State Store contracts, holds Line truncated
"body": "# Service decomposition -- decision\n\n**Status:** Draft\n**Date:** 2026-09-05\n**Beads epic:** archie-core-8cda\n**Prior art:** `docs/inspiration/2026-09-05-awx-service-decomposition-and-ansible-task-model.md`,\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`,\n`docs/inspiration/service-discovery-research-2026-09-05.md`,\n`/work/artefacts/archie-core-current-state-archify.html`,\n`/work/artefacts/archie-core-ideal-state-archify.html`\n\nThe Phase 3 UI boundary and configuration decision is ratified in\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/). That focused document is\nthe implementation authority for `archie-core-8cda.5.2`; this parent remains\nthe broader service-distribution proposal.\n\n## Decision\n\narchie-core moves from one Go binary (`archied`) hosting every domain\nin-process to a set of independently deployable services, each exposing\nexactly one typed contract. Consumers depend on the contract; they never\nreach into another service's internal types, session state, or config.\ngRPC is the synchronous transport; NATS remains for asynchronous fan-out\n(status, telemetry) rather than being replaced.\n\nThis is a **distribution decision**, not a rewrite of Archie's domain\nmodel. The six-domain split already approved in\n`docs/architecture/index.md` and `docs/architecture/organisation.md`\n(Identity, Agent, Messaging, Workflow, Work Intake, Plugin) is unchanged;\nthis PRD is about how the _processes_ running that domain logic get\npackaged, contracted, and discovered -- not about redrawing domain\nboundaries.\n\n### Target services\n\n| Service | Contract it owns | Existing code it replaces/wraps |\n| --------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n| UI Service | thin client only; talks to Gateway and State Store contracts | `internal/webui` (SPA hosting stays; API surface becomes typed contract clients, not a peer with direct access) |\n| Gateway Service | routing / turn / session contract | `internal/gateway` |\n| Messaging Service | channel-plugin contract (Telegram, email, Discord, Teams, ...) | `internal/channels` |\n| Curator Service | curator contract; **optional**, installs as a Gateway plugin | `internal/domain/curator` |\n| Scheduler Service | cron/ticker contract | `internal/domain/scheduling` |\n| Execution Environment | execution-dispatch contract | `internal/domain/workflow`, task dispatch paths |\n| Runner | isolated worktree/container execution | `internal/container`, `internal/agentexec`, `internal/worktree` |\n| State Store | state-access contract | `internal/infrastructure/postgres` |\n\n### Discovery\n\nPer `docs/inspiration/service-discovery-research-2026-09-05.md`:\n\n- **Primary:** Kubernetes-native discovery (Service + headless-Service/DNS\n - EndpointSlice, served by CoreDNS), delivered as a Helm chart + Operator,\n on k3s for single-host installs and a real cluster for multi-host or a\n hosted offering.\n- **Fallback:** NATS-based discovery (micro `$SRV` announce + JetStream KV\n registry) for no-K8s single-host installs, with a custom gRPC resolver\n reading `host:port` from the KV bucket.\n- Both implementations sit behind one internal interface:\n\n ```go\n type ServiceRegistry interface {\n Resolve(service string) []Endpoint\n Watch(service string) \u003c-chan Event // join/leave\n }\n ```\n\n- An optional service (Curator; others later) that is not installed\n must resolve to a distinct `NotInstalled` outcome, never a `Down`/\n `Unhealthy` one. Under K8s this falls out of DNS returning no record;\n under the NATS fallback it requires an explicit \"installed\" marker in the\n KV registry, not just absence-implies-down.\n\n### Distribution model this supports\n\nBoth self-hosted (customer runs the Helm chart or the NATS-fallback\nbinaries themselves) and a managed/hosted offering (we run the same Helm\nchart) are in scope -- this is the RHELine truncated
},
{
"url": "/dev/prds/service-registry/",
"title": "Service registry — one declaration per service",
"section": "PRDs",
"body": "# Service registry — one declaration per service\n\n**Status:** Draft\n**Supersedes:** `state-store-contract.md` §10's `State ServiceConnection`\nstruct-field instruction.\n\n**Base:** the `listen` field, `internal/app/archied/listen.go`, and the listen defaults cited\nbelow exist on `feat/attempt-attribution`, not on `main`. This design therefore lands on top of\nthat branch: `RegisterService`'s `listen` argument has nothing to carry without it.\n\n## Problem\n\nA service is already one Go type, `config.ServiceConnection`. What is duplicated is its\n**name**, in three layers:\n\n| Layer | Location | What is hard-coded |\n|---|---|---|\n| Declaration | `internal/config/services.go` | `Gateway` and `State` as struct fields |\n| Defaulting | `internal/infrastructure/configuration/defaults.go` | three `if cfg.Services.X.Y == \"\"` branches |\n| Consumption | `internal/app/archied/{bootstrap.go,state_store.go,gateway.go}`, `internal/app/archieui/config.go` | `cfg.Services.State` / `cfg.Services.Gateway` field access |\n\nAdding a service means editing all three. The drift this permits is already visible:\n`stateStoreResolvedToken` (`state_store_client.go`) and `gatewayResolvedToken`\n(`chat_service.go`) are byte-identical apart from the env var name, and\n`gateway.Target` is defaulted while `state.Target` is a startup error, with nothing\nstating that asymmetry in one place.\n\n`resolveServiceListen(service, flagValue, configured)` (`listen.go`) is already\nname-parameterised. It is the shape the rest should follow.\n\n## Decision\n\n**Key services by name, and carry per-service asymmetry as registration data.**\n\n### 1. Declaration collapses to a map\n\n```go\n// internal/config/services.go\ntype Services map[string]ServiceConnection\n```\n\n`ServiceConnection` is unchanged. The TOML shape is unchanged, so no deployment profile,\n`config.example.toml`, or `install.sh` edit is required. An unrecognised `[services.foo]`\ndecodes without a code edit, satisfying criterion 5.\n\n### 2. Registration is the single entry point\n\n```go\n// internal/config/servicespec.go\nfunc RegisterService(context, name, target, listen, tokenEnv string)\n```\n\nregistered once per service, at package init in `internal/config`:\n\n```go\nRegisterService(\"both\", \"gateway\", \"127.0.0.1:8585\", \"127.0.0.1:8585\", \"GATEWAY_TOKEN\")\nRegisterService(\"client\", \"state\", \"\", \"127.0.0.1:9090\", \"STATE_STORE_TOKEN\")\n```\n\nPositional, five strings, as the story specifies. Each argument is data the current code\nstates in prose or in a branch:\n\n- `context` is `client`, `server`, or `both`, and decides which fields must resolve\n non-empty. `RegisterService` enforces it: an unknown context, or a hosted service with\n no default `listen`, panics at registration. Registrations come from this repository's\n own `init()`, never from operator input, so an invalid one is a programming error with\n no caller positioned to handle an error return. A documented-but-unread `Context` would\n be worse than no field at all.\n- `target` is the **default**, and an empty default means the operator must supply one.\n That single convention replaces the `state.target` required / `gateway.target` defaulted\n asymmetry with no branch: `state` registers `\"\"`, `gateway` registers an address.\n- `listen` is the default listen address, feeding the existing\n flag → `[services.\u003cname\u003e].listen` → default precedence unchanged.\n- `tokenEnv` names the fallback env var, replacing the two copied resolvers with one.\n\n### 3. Defaulting and consumption become loops and lookups\n\n`applyDefaults` iterates the registry instead of naming services. Consumers read\n`cfg.Services.Get(\"state\")`, returning a `ServiceConnection` plus the spec, so\n`stateStoreResolvedToken` and `gatewayResolvedToken` collapse into\n`Services.ResolvedToken(name, secrets)`.\n\n## Criteria satisfied\n\n1. Declared once, in the `RegisterService` call.\n2. No second location can contradict it; the map has no per-service fields to disagree with.\n3. Registration is the entry point, with the five fields a service has.\n4. A new service is one `RegisterService` line: no field, no default branch, no consumer edit.\n5. The set of services is registry data, not a struct definition.\n\n## Scope and risk\n\n- `state-store-contract.md` §10 must be revised in the same change, or the tree contradicts\n its own ratified authority. Its summary (`:7`) already says `[services.\u003cname\u003e]`.\n- A typo'd `[services.gatway]` is **reported** (`UnknownKeys = [services.gatway,\n services.gatway.target]`), because the struct form leaves it in `toml.MetaData.Undecoded()`.\n A map decodes any section, so preserving that is a requirement, not an optional extra:\n `unregisteredServiceKeys` asks the registry which names exist. This costs nothing in\n extensibility, because the answer comes from registration data rather than a fixed list.\n TheLine truncated
"body": "# Service registry — one declaration per service\n\n**Status:** Draft\n**Supersedes:** `state-store-contract.md` §10's `State ServiceConnection`\nstruct-field instruction.\n\n**Base:** the `listen` field, `internal/app/archied/listen.go`, and the listen defaults cited\nbelow exist on `feat/attempt-attribution`, not on `main`. This design therefore lands on top of\nthat branch: `RegisterService`'s `listen` argument has nothing to carry without it.\n\n## Problem\n\nA service is already one Go type, `config.ServiceConnection`. What is duplicated is its\n**name**, in three layers:\n\n| Layer | Location | What is hard-coded |\n| ----------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |\n| Declaration | `internal/config/services.go` | `Gateway` and `State` as struct fields |\n| Defaulting | `internal/infrastructure/configuration/defaults.go` | three `if cfg.Services.X.Y == \"\"` branches |\n| Consumption | `internal/app/archied/{bootstrap.go,state_store.go,gateway.go}`, `internal/app/archieui/config.go` | `cfg.Services.State` / `cfg.Services.Gateway` field access |\n\nAdding a service means editing all three. The drift this permits is already visible:\n`stateStoreResolvedToken` (`state_store_client.go`) and `gatewayResolvedToken`\n(`chat_service.go`) are byte-identical apart from the env var name, and\n`gateway.Target` is defaulted while `state.Target` is a startup error, with nothing\nstating that asymmetry in one place.\n\n`resolveServiceListen(service, flagValue, configured)` (`listen.go`) is already\nname-parameterised. It is the shape the rest should follow.\n\n## Decision\n\n**Key services by name, and carry per-service asymmetry as registration data.**\n\n### 1. Declaration collapses to a map\n\n```go\n// internal/config/services.go\ntype Services map[string]ServiceConnection\n```\n\n`ServiceConnection` is unchanged. The TOML shape is unchanged, so no deployment profile,\n`config.example.toml`, or `install.sh` edit is required. An unrecognised `[services.foo]`\ndecodes without a code edit, satisfying criterion 5.\n\n### 2. Registration is the single entry point\n\n```go\n// internal/config/servicespec.go\nfunc RegisterService(context, name, target, listen, tokenEnv string)\n```\n\nregistered once per service, at package init in `internal/config`:\n\n```go\nRegisterService(\"both\", \"gateway\", \"127.0.0.1:8585\", \"127.0.0.1:8585\", \"GATEWAY_TOKEN\")\nRegisterService(\"client\", \"state\", \"\", \"127.0.0.1:9090\", \"STATE_STORE_TOKEN\")\n```\n\nPositional, five strings, as the story specifies. Each argument is data the current code\nstates in prose or in a branch:\n\n- `context` is `client`, `server`, or `both`, and decides which fields must resolve\n non-empty. `RegisterService` enforces it: an unknown context, or a hosted service with\n no default `listen`, panics at registration. Registrations come from this repository's\n own `init()`, never from operator input, so an invalid one is a programming error with\n no caller positioned to handle an error return. A documented-but-unread `Context` would\n be worse than no field at all.\n- `target` is the **default**, and an empty default means the operator must supply one.\n That single convention replaces the `state.target` required / `gateway.target` defaulted\n asymmetry with no branch: `state` registers `\"\"`, `gateway` registers an address.\n- `listen` is the default listen address, feeding the existing\n flag → `[services.\u003cname\u003e].listen` → default precedence unchanged.\n- `tokenEnv` names the fallback env var, replacing the two copied resolvers with one.\n\n### 3. Defaulting and consumption become loops and lookups\n\n`applyDefaults` iterates the registry instead of naming services. Consumers read\n`cfg.Services.Get(\"state\")`, returning a `ServiceConnection` plus the spec, so\n`stateStoreResolvedToken` and `gatewayResolvedToken` collapse into\n`Services.ResolvedToken(name, secrets)`.\n\n## Criteria satisfied\n\n1. Declared once, in the `RegisterService` call.\n2. No second location can contradict it; the map has no per-service fields to disagree with.\n3. Registration is the entry point, with the five fields a service has.\n4. A new service is one `RegisterService` line: no field, no default branch, no consumer edit.\n5. The set of services is registry data, not a struct definition.\n\n## Scope and risk\n\n- `state-store-contract.md` §10 must be revised in the same change, or the tree contradicts\n its own ratified authority. Its summary (`:7`) already says `[services.\u003cname\u003e]`.\nLine truncated
},
{
"url": "/dev/prds/session-memory-curator/",
"title": "Persistent session-memory curator (reference implementation) -- decision",
"section": "PRDs",
"body": "# Persistent session-memory curator (reference implementation) -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-1786637499114`\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n**Depends on:** `archie-core-1786637499636` (bind curators to memory\nengines, shipped) and the `domain/memory` engine family (shipped)\n\n## Decision\n\nEach pass: find sessions with activity since the last pass, ask the\nmodel to extract a short list of durable observations from each one's\nrecent messages, and write each through the curator's bound memory\nengine. Extraction is **scoped to one session** -- `Observation.Identity`\nis the session ID, not a user or cross-session identity. No\nconsolidation across sessions, no forgetting, no rewriting a prior\nextraction: every pass only adds.\n\nThis is the second contract consumer the epic asks for, and the one that\nexercises the curator/memory-engine binding\n(`archie-core-1786637499636`) for real, unlike the skill curator, which\ndeclares no memory engine at all.\n\n## Why session-scoped, not user- or agent-wide\n\n`docs/architecture/migration-decisions.md#5` lists the four required\nmemory scopes (global, agent-wide, user-wide, agent-user relationship)\nas **still open** -- there is no decided mapping yet from a chat session\nto a durable identity that would outlive that session (a Telegram chat\nID is not necessarily \"the same person\" as a web session; per-platform\nidentity resolution does not exist as a memory concern). Choosing\nsession-as-identity sidesteps a decision this issue has no business\nmaking unilaterally: it is the narrowest scope that is unambiguous\n(`gateway.SessionContext.SessionID` already exists, is already unique,\nand already has no cross-platform identity claim attached to it), and\nit is forward-compatible -- widening to a resolved user identity later\nis a change to what `Identity` is populated with, not to the\nextraction or write path.\n\n## Why a new `curator.ConversationSource`, not `gateway.SessionStore` directly\n\n`internal/domain/curator` is a domain package; `internal/gateway` is not\none of `internal/domain/*`'s dependencies by convention, and\n`gateway.SessionStore`'s full CRUD surface (branch, fork, replace,\nsearch) is far more than a curator needs or should be able to reach --\nthe same reasoning `ToolBuilder`/`SkillStore`/`MemoryEngineSource`\nalready established for every other host service this package depends\non. `curator.ConversationSource` is a two-method read-only interface;\n`internal/app/archied` adapts the real `gateway.SessionStore` to it, the\nsame shape `MemoryEngineSource` already uses for\n`domain/memory.Registry`.\n\n```go\n// ConversationSource is read-only conversation history, narrowed to\n// what a curator needs to review recent activity -- never the full\n// session CRUD/branch/search surface a chat gateway exposes.\ntype ConversationSource interface {\n // RecentSessions returns every session touched at or after since,\n // newest first.\n RecentSessions(ctx context.Context, since time.Time) ([]SessionSummary, error)\n // Messages returns the most recent n messages of one session, in\n // chronological order.\n Messages(ctx context.Context, sessionID string, n int) ([]ConversationMessage, error)\n}\n\ntype SessionSummary struct {\n ID string\n LastActive time.Time\n}\n\ntype ConversationMessage struct {\n Role string // \"user\" or \"assistant\"\n Content string\n At time.Time\n}\n```\n\n`Manifest` gains `Conversations bool`, gated exactly like `Skills`:\n`Registry.validateDeclared` requires a `ConversationSource` on the host\nwhen declared, `Registry.filter` clears it from a curator's view when\nnot. Role is derived the same way `gateway.compressTurnHistory` already\ndoes (`message.From == botUser` -\u003e `\"assistant\"`, else `\"user\"`) --\ncopied logic, not shared code, since the source type\n(`gateway.Message`) is exactly the thing this package must not import.\n\n## Extraction shape\n\n`Pass`:\n\n1. `Conversations.RecentSessions(ctx, effectiveSince(in.Since))` -- see\n below for the zero-`Since` default.\n2. For each session, `Conversations.Messages(ctx, id, 40)` -- the last\n 40 messages, not the full history. A session accumulates far more\n history than a skill file accumulates content; unlike the skill\n curator's \"re-read everything, it's cheap,\" a full-history read here\n is not cheap and is not needed -- durable facts worth keeping surface\n in recent exchanges, and a 40-message tail is deliberately generous\n against the model's own context rather than tuned tightly, since\n getting this number exactly right is not this issue's job.\n3. One model call per session: the message tail, plus an instruction to\n return a JSON array of short strings, each one fact/preference/\n correction worth keeping, or `[]` if nothing is. Capped at 5 items\n per session per passLine truncated
"body": "# Persistent session-memory curator (reference implementation) -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-1786637499114`\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n**Depends on:** `archie-core-1786637499636` (bind curators to memory\nengines, shipped) and the `domain/memory` engine family (shipped)\n\n## Decision\n\nEach pass: find sessions with activity since the last pass, ask the\nmodel to extract a short list of durable observations from each one's\nrecent messages, and write each through the curator's bound memory\nengine. Extraction is **scoped to one session** -- `Observation.Identity`\nis the session ID, not a user or cross-session identity. No\nconsolidation across sessions, no forgetting, no rewriting a prior\nextraction: every pass only adds.\n\nThis is the second contract consumer the epic asks for, and the one that\nexercises the curator/memory-engine binding\n(`archie-core-1786637499636`) for real, unlike the skill curator, which\ndeclares no memory engine at all.\n\n## Why session-scoped, not user- or agent-wide\n\n`docs/architecture/migration-decisions.md#5` lists the four required\nmemory scopes (global, agent-wide, user-wide, agent-user relationship)\nas **still open** -- there is no decided mapping yet from a chat session\nto a durable identity that would outlive that session (a Telegram chat\nID is not necessarily \"the same person\" as a web session; per-platform\nidentity resolution does not exist as a memory concern). Choosing\nsession-as-identity sidesteps a decision this issue has no business\nmaking unilaterally: it is the narrowest scope that is unambiguous\n(`gateway.SessionContext.SessionID` already exists, is already unique,\nand already has no cross-platform identity claim attached to it), and\nit is forward-compatible -- widening to a resolved user identity later\nis a change to what `Identity` is populated with, not to the\nextraction or write path.\n\n## Why a new `curator.ConversationSource`, not `gateway.SessionStore` directly\n\n`internal/domain/curator` is a domain package; `internal/gateway` is not\none of `internal/domain/*`'s dependencies by convention, and\n`gateway.SessionStore`'s full CRUD surface (branch, fork, replace,\nsearch) is far more than a curator needs or should be able to reach --\nthe same reasoning `ToolBuilder`/`SkillStore`/`MemoryEngineSource`\nalready established for every other host service this package depends\non. `curator.ConversationSource` is a two-method read-only interface;\n`internal/app/archied` adapts the real `gateway.SessionStore` to it, the\nsame shape `MemoryEngineSource` already uses for\n`domain/memory.Registry`.\n\n```go\n// ConversationSource is read-only conversation history, narrowed to\n// what a curator needs to review recent activity -- never the full\n// session CRUD/branch/search surface a chat gateway exposes.\ntype ConversationSource interface {\n // RecentSessions returns every session touched at or after since,\n // newest first.\n RecentSessions(ctx context.Context, since time.Time) ([]SessionSummary, error)\n // Messages returns the most recent n messages of one session, in\n // chronological order.\n Messages(ctx context.Context, sessionID string, n int) ([]ConversationMessage, error)\n}\n\ntype SessionSummary struct {\n ID string\n LastActive time.Time\n}\n\ntype ConversationMessage struct {\n Role string // \"user\" or \"assistant\"\n Content string\n At time.Time\n}\n```\n\n`Manifest` gains `Conversations bool`, gated exactly like `Skills`:\n`Registry.validateDeclared` requires a `ConversationSource` on the host\nwhen declared, `Registry.filter` clears it from a curator's view when\nnot. Role is derived the same way `gateway.compressTurnHistory` already\ndoes (`message.From == botUser` -\u003e `\"assistant\"`, else `\"user\"`) --\ncopied logic, not shared code, since the source type\n(`gateway.Message`) is exactly the thing this package must not import.\n\n## Extraction shape\n\n`Pass`:\n\n1. `Conversations.RecentSessions(ctx, effectiveSince(in.Since))` -- see\n below for the zero-`Since` default.\n2. For each session, `Conversations.Messages(ctx, id, 40)` -- the last\n 40 messages, not the full history. A session accumulates far more\n history than a skill file accumulates content; unlike the skill\n curator's \"re-read everything, it's cheap,\" a full-history read here\n is not cheap and is not needed -- durable facts worth keeping surface\n in recent exchanges, and a 40-message tail is deliberately generous\n against the model's own context rather than tuned tightly, since\n getting this number exactly right is not this issue's job.\n3. One model call per session: the message tail, plus an instruction to\n return a JSON array of short strings, each one fact/preference/\n correction worth keeping, or `[]` if nothing is. Capped at 5 items\n per session per passLine truncated
},
{
"url": "/dev/prds/skill-curator/",
"title": "Skill curator (reference implementation) -- decision",
"section": "PRDs",
"body": "# Skill curator (reference implementation) -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-1786637499206`\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n\n## Decision\n\nThe skill curator's v1 scope is **mechanical validation and safe\nnormalization only** -- it never rewrites skill prose, never deletes a\nskill, and never calls the model. Each pass:\n\n1. Lists every skill under one configured root.\n2. Reads each `SKILL.md` and attempts to parse its frontmatter\n (`internal/skill.Parse`).\n3. Records an `Action` for any structural problem: a parse failure, or a\n missing `name`/`description` in the frontmatter that parsed.\n4. Normalizes trivial whitespace (trailing whitespace per line, exactly\n one trailing newline) and writes back **only** when normalization\n actually changes the bytes, recording an `Action` for that write.\n\nNothing here needs judgment. \"Review, prune, and improve\" -- the epic's\nframing -- is real for v1 but deliberately narrow: review is structural\nvalidation, improve is whitespace normalization, and prune is *reporting*\na problem, never removing a skill. `Manifest.Skills = true` still marks\nthis curator agentic (existing `agentic()` rule), so it receives model\naccess from the registrar -- unused but nothing about the contract\nor the runtime needs to change to let a later version reason about\ncontent quality using it.\n\n## Why this scope, not more\n\nAn autonomous process that rewrites or deletes a user's skill content\nis a real risk with no undo path (no draft/approval flow for\ncurator writes exists yet, unlike the workflow engine's PR-based review).\nThe epic's own stated purpose for this issue is proving the curator\ncontract holds for a second, structurally different consumer than the\nsession-memory curator (files-as-skills vs. observations-as-memory), not\nsolving \"what makes a skill good.\" Mechanical validation is real,\nuseful, safe to run unattended, and fully exercises\nList/Read/Write -- every method `curator.SkillStore` declares except\n`Delete`, which this curator's Pass never has a safe reason to call in\nv1 (kept implemented on the store adapter regardless, since the\ninterface requires it and a future consumer may).\n\n## Why `internal/skill` isn't `curator.SkillStore` directly\n\n`internal/skill.Discover` parses every `SKILL.md` under a root and\nreturns an error for the **whole** call if any one of them fails to\nparse -- the read side was built for \"load the catalog to start the\ndaemon,\" where one bad skill failing the whole boot is arguably correct,\nnot for \"review each skill and report what's wrong with it\nindividually.\" A per-skill parse failure must become one `Action`, not\nabort the pass before any skill is reviewed. So\n`internal/infrastructure/skillcurator` gets its own thin store adapter\nthat lists raw directory names and reads/writes raw `SKILL.md` bytes\nper name; the skill curator itself calls `internal/skill.Parse` on each\none, isolated per skill.\n\n## Root scope\n\nOne root only, resolved the same way `loadWorkflows` already resolves\n`skillsBase` (`cfg.SkillsDir`, falling back to `cfg.WorkDir`) -- not\nevery root `skill.CatalogRoots`/`DefaultRoots` would read for a model\n(which layers a shared dir over the per-profile one). Write and Delete\nneed one unambiguous target; a curator that could write into a shared,\nmulti-tenant skills directory is a bigger decision than this issue\ncovers. The model still sees the full multi-root catalog through the\nexisting read path -- this curator only maintains the local one.\n\n## Shape\n\n### `internal/infrastructure/skillcurator/store.go`\n\n```go\n// Store implements curator.SkillStore over one root directory's\n// .agents/skills/*/SKILL.md files, tolerating a per-skill parse failure\n// as the curator's problem to report rather than this store's problem\n// to abort on.\ntype Store struct { root string }\n\nfunc NewStore(root string) *Store\n\nfunc (s *Store) List(ctx context.Context) ([]curator.SkillRef, error)\nfunc (s *Store) Read(ctx context.Context, name string) (curator.Skill, error)\nfunc (s *Store) Write(ctx context.Context, sk curator.Skill) error\nfunc (s *Store) Delete(ctx context.Context, name string) error\n```\n\n`Read` best-effort parses frontmatter for `Skill.Description` (empty on\nparse failure -- not this method's job to report that; `Pass` does, via\nits own `skill.Parse` call on `Skill.Content`). `Write` rejects a name\nthat does not already exist as a directory (this store curates existing\nskills; creating a new one is out of scope). `Delete` removes the whole\nskill directory, matching \"delete a skill,\" not just `SKILL.md`.\n\n### `internal/infrastructure/skillcurator/skillcurator.go`\n\n```go\n// Curator implements domain/curator.CuratorEngine. See\n// docs/prds/skill-curator.md for what a pass does and why.\ntype Curator struct { /* unexported: registrar view, interval */ }\Line truncated
"body": "# Skill curator (reference implementation) -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-1786637499206`\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n\n## Decision\n\nThe skill curator's v1 scope is **mechanical validation and safe\nnormalisation only** -- it never rewrites skill prose, never deletes a\nskill, and never calls the model. Each pass:\n\n1. Lists every skill under one configured root.\n2. Reads each `SKILL.md` and attempts to parse its frontmatter\n (`internal/skill.Parse`).\n3. Records an `Action` for any structural problem: a parse failure, or a\n missing `name`/`description` in the frontmatter that parsed.\n4. Normalises trivial whitespace (trailing whitespace per line, exactly\n one trailing newline) and writes back **only** when normalisation\n actually changes the bytes, recording an `Action` for that write.\n\nNothing here needs judgement. \"Review, prune, and improve\" -- the epic's\nframing -- is real for v1 but deliberately narrow: review is structural\nvalidation, improve is whitespace normalisation, and prune is _reporting_\na problem, never removing a skill. `Manifest.Skills = true` still marks\nthis curator agentic (existing `agentic()` rule), so it receives model\naccess from the registrar -- unused but nothing about the contract\nor the runtime needs to change to let a later version reason about\ncontent quality using it.\n\n## Why this scope, not more\n\nAn autonomous process that rewrites or deletes a user's skill content\nis a real risk with no undo path (no draft/approval flow for\ncurator writes exists yet, unlike the workflow engine's PR-based review).\nThe epic's own stated purpose for this issue is proving the curator\ncontract holds for a second, structurally different consumer than the\nsession-memory curator (files-as-skills vs. observations-as-memory), not\nsolving \"what makes a skill good.\" Mechanical validation is real,\nuseful, safe to run unattended, and fully exercises\nList/Read/Write -- every method `curator.SkillStore` declares except\n`Delete`, which this curator's Pass never has a safe reason to call in\nv1 (kept implemented on the store adapter regardless, since the\ninterface requires it and a future consumer may).\n\n## Why `internal/skill` isn't `curator.SkillStore` directly\n\n`internal/skill.Discover` parses every `SKILL.md` under a root and\nreturns an error for the **whole** call if any one of them fails to\nparse -- the read side was built for \"load the catalogue to start the\ndaemon,\" where one bad skill failing the whole boot is arguably correct,\nnot for \"review each skill and report what's wrong with it\nindividually.\" A per-skill parse failure must become one `Action`, not\nabort the pass before any skill is reviewed. So\n`internal/infrastructure/skillcurator` gets its own thin store adapter\nthat lists raw directory names and reads/writes raw `SKILL.md` bytes\nper name; the skill curator itself calls `internal/skill.Parse` on each\none, isolated per skill.\n\n## Root scope\n\nOne root only, resolved the same way `loadWorkflows` already resolves\n`skillsBase` (`cfg.SkillsDir`, falling back to `cfg.WorkDir`) -- not\nevery root `skill.CatalogRoots`/`DefaultRoots` would read for a model\n(which layers a shared dir over the per-profile one). Write and Delete\nneed one unambiguous target; a curator that could write into a shared,\nmulti-tenant skills directory is a bigger decision than this issue\ncovers. The model still sees the full multi-root catalogue through the\nexisting read path -- this curator only maintains the local one.\n\n## Shape\n\n### `internal/infrastructure/skillcurator/store.go`\n\n```go\n// Store implements curator.SkillStore over one root directory's\n// .agents/skills/*/SKILL.md files, tolerating a per-skill parse failure\n// as the curator's problem to report rather than this store's problem\n// to abort on.\ntype Store struct { root string }\n\nfunc NewStore(root string) *Store\n\nfunc (s *Store) List(ctx context.Context) ([]curator.SkillRef, error)\nfunc (s *Store) Read(ctx context.Context, name string) (curator.Skill, error)\nfunc (s *Store) Write(ctx context.Context, sk curator.Skill) error\nfunc (s *Store) Delete(ctx context.Context, name string) error\n```\n\n`Read` best-effort parses frontmatter for `Skill.Description` (empty on\nparse failure -- not this method's job to report that; `Pass` does, via\nits own `skill.Parse` call on `Skill.Content`). `Write` rejects a name\nthat does not already exist as a directory (this store curates existing\nskills; creating a new one is out of scope). `Delete` removes the whole\nskill directory, matching \"delete a skill,\" not just `SKILL.md`.\n\n### `internal/infrastructure/skillcurator/skillcurator.go`\n\n```go\n// Curator implements domain/curator.CuratorEngine. See\n// docs/prds/skill-curator.md for what a pass does and why.\ntype Curator struct { /* unexported: registrar view, interval *Line truncated
},
{
"url": "/dev/prds/state-store-contract/",
"title": "State Store — contract boundary \u0026 transport (ratification)",
"section": "PRDs",
"body": "# State Store — contract boundary \u0026 transport (ratification)\n\n**Status:** Approved\n**Revision:** 2e\n**Date:** 2026-09-06\n\nThis is the pre-implementation design document that Phase 2 subtasks `.4.2` (generalize\n`storerpc` as the State Store gRPC contract) and `.4.3` (stand up `archie-state-store`)\nimplement against.\n**Beads milestone:** archie-core-8cda.4.1\n**Parent:** `docs/prds/service-decomposition.md` (open-question Q4 **RESOLVED**)\n\nThis document fixes the **contract boundary** and **transport** for the State Store service.\nIt does not redesign Archie's domain model, does not invent a second store, and does **not**\nsplit `archie.db`. It records method ownership, DTO/wire representation, error semantics,\nlimits, mode/config shape, local-adapter compatibility, and cutover/deletion rules so that\n`.4.2` and `.4.3` have exactly one authoritative surface to build against.\n\n\u003e **Current state — read before `.4.2` starts.** The §12 step 2 relocation (`archie-core-8cda.\n\u003e 4.8`) has landed: `Task`/`Status*`/`Source*` and the 3-method `workflow.Store` now live in\n\u003e `internal/domain/workflow`, the six production workflow files import no `internal/store`\n\u003e symbol, and `storerpc`/the NATS transport assert against `workflow.Store` instead of\n\u003e `store.WorkflowStore`. The broader Phase 2 acceptance criterion (State Store as its own\n\u003e service behind gRPC) is still open — that is what `.4.2`/`.4.3` build next.\n\n\u003e **Relationship to migration-decisions §4 — not replaced.** `docs/architecture/\n\u003e migration-decisions.md` §4 (`store.Task → WorkflowExecution`, `mutable Stage →\n\u003e StepExecution history`, `RetryCount/Attempt → Attempt records`, versioned Workflow defs)\n\u003e **remains the authoritative, open document for the long-term Workflow migration.** This PRD\n\u003e does **not** replace it. It only pulls the minimal `Task`/`Status`/`Source` type + interface\n\u003e relocation forward as a Phase 2 prerequisite (because the acceptance criterion requires it);\n\u003e the rest of §4 stays its own migration and stays open.\n\n---\n\n## 1. Decision (the invariant everything follows)\n\nArchie is composed such that a single **`archie-state-store`** service owns the one existing\nSQLite file (`archie.db`) and exposes it over **gRPC behind narrow typed contracts**. There is\nexactly one store, one file, one service. No database-per-service, no distributed\ntransactions, no second store abstraction.\n\nTwo adapter families satisfy the contract interfaces:\n\n- **Local adapter** — `*store.Store` (the in-process SQLite implementation).\n- **Remote adapter** — `*staterpc.Client` (wraps the generated gRPC client).\n\nEach adapter carries an explicit compile-time assertion against the contract interfaces it\nserves. Composition picks local vs. remote by the presence of `[services.state].target`\n(empty = local; set = dial the gRPC service). Default is **local** (the State Store is not yet\nextracted), which is the PRD §3 posture; it differs from the gateway's remote-default only\nbecause the gateway is already a separate deployment and the State Store is not.\n\n\u003e **Contract-ownership fork, decided (rev. 2c — resolves the domain contradiction).**\n\u003e Ownership splits by the consumer's *layer*, per the dependency contract's rule #2\n\u003e (\"a domain defines the smallest interfaces required to perform its work\") and rule #7\n\u003e (\"database rows … MUST NOT leak into domain models\"):\n\u003e\n\u003e - The **workflow domain** (`internal/domain/workflow`) is the only domain-layer consumer of\n\u003e store state. It defines its own **consumer-owned** narrow `Store` interface\n\u003e (Update/Transition/InsertEvent) and its own **domain-owned** `Task` type plus\n\u003e `Status`/`Source` vocabulary. It imports **zero** `internal/store` symbols — satisfying the\n\u003e Phase 2 acceptance criterion. This is the minimal bound of migration-decisions §4\n\u003e (`store.Task → WorkflowExecution`), pulled forward **because** the acceptance criterion\n\u003e requires it.\n\u003e - The **daemon / webui / intake** store surfaces (`TaskStore`, `CaptureStore`,\n\u003e `MappingStore`, `BindingStore`, `BindingDispatcher`, `BindingTaskCreator`) stay\n\u003e **producer-owned** in `internal/store`, because those consumers are application and\n\u003e infrastructure layers, not domains — rule #2 does not apply to them.\n\nSo the State Store contract is **not** uniformly producer-owned: the domain-facing workflow\ncontract is consumer-owned (in the domain), while the daemon/webui store surfaces remain in\n`internal/store`. `internal/store` imports `internal/domain/workflow` for the `Task`/`Status`/\n`Source` types it persists (persistence → domain, the correct direction), and its `Store`\nimplementation satisfies `workflow.Store`. This is the single decision that makes the whole\nPhase 2 acceptance criterioLine truncated
"body": "# State Store — contract boundary \u0026 transport (ratification)\n\n**Status:** Approved\n**Revision:** 2e\n**Date:** 2026-09-06\n\nThis is the pre-implementation design document that Phase 2 subtasks `.4.2` (generalise\n`storerpc` as the State Store gRPC contract) and `.4.3` (stand up `archie-state-store`)\nimplement against.\n**Beads milestone:** archie-core-8cda.4.1\n**Parent:** `docs/prds/service-decomposition.md` (open-question Q4 **RESOLVED**)\n\nThis document fixes the **contract boundary** and **transport** for the State Store service.\nIt does not redesign Archie's domain model, does not invent a second store, and does **not**\nsplit `archie.db`. It records method ownership, DTO/wire representation, error semantics,\nlimits, mode/config shape, local-adapter compatibility, and cutover/deletion rules so that\n`.4.2` and `.4.3` have exactly one authoritative surface to build against.\n\n\u003e **Storage superseded.** The store behind this contract is PostgreSQL:\n\u003e `internal/infrastructure/postgres` implements the producer-owned interfaces in\n\u003e `internal/domain/storecontract` and `workflow.Store`, over the database\n\u003e `database_url` names. `internal/store`, the SQLite file and the local adapter\n\u003e are gone; where this document says `archie.db`, `*store.Store` or\n\u003e `internal/store`, read the State Store's PostgreSQL database and\n\u003e `internal/infrastructure/postgres`. The contract, ownership split, error\n\u003e semantics and cutover rules stand.\n\n\u003e **Current state — read before `.4.2` starts.** The §12 step 2 relocation (`archie-core-8cda.\n4.8`) has landed: `Task`/`Status*`/`Source*` and the 3-method `workflow.Store` now live in\n\u003e `internal/domain/workflow`, the six production workflow files import no `internal/store`\n\u003e symbol, and `storerpc`/the NATS transport assert against `workflow.Store` instead of\n\u003e `store.WorkflowStore`. The broader Phase 2 acceptance criterion (State Store as its own\n\u003e service behind gRPC) is still open — that is what `.4.2`/`.4.3` build next.\n\n\u003e **Relationship to migration-decisions §4 — not replaced.** `docs/architecture/\nmigration-decisions.md` §4 (`store.Task → WorkflowExecution`, `mutable Stage →\nStepExecution history`, `RetryCount/Attempt → Attempt records`, versioned Workflow defs)\n\u003e **remains the authoritative, open document for the long-term Workflow migration.** This PRD\n\u003e does **not** replace it. It only pulls the minimal `Task`/`Status`/`Source` type + interface\n\u003e relocation forward as a Phase 2 prerequisite (because the acceptance criterion requires it);\n\u003e the rest of §4 stays its own migration and stays open.\n\n---\n\n## 1. Decision (the invariant everything follows)\n\nArchie is composed such that a single **`archie-state-store`** service owns the one existing\nSQLite file (`archie.db`) and exposes it over **gRPC behind narrow typed contracts**. There is\nexactly one store, one file, one service. No database-per-service, no distributed\ntransactions, no second store abstraction.\n\nTwo adapter families satisfy the contract interfaces:\n\n- **Local adapter** — `*store.Store` (the in-process SQLite implementation).\n- **Remote adapter** — `*staterpc.Client` (wraps the generated gRPC client).\n\nEach adapter carries an explicit compile-time assertion against the contract interfaces it\nserves. Composition picks local vs. remote by the presence of `[services.state].target`\n(empty = local; set = dial the gRPC service). Default is **local** (the State Store is not yet\nextracted), which is the PRD §3 posture; it differs from the gateway's remote-default only\nbecause the gateway is already a separate deployment and the State Store is not.\n\n\u003e **Contract-ownership fork, decided (rev. 2c — resolves the domain contradiction).**\n\u003e Ownership splits by the consumer's _layer_, per the dependency contract's rule #2\n\u003e (\"a domain defines the smallest interfaces required to perform its work\") and rule #7\n\u003e (\"database rows … MUST NOT leak into domain models\"):\n\u003e\n\u003e - The **workflow domain** (`internal/domain/workflow`) is the only domain-layer consumer of\n\u003e store state. It defines its own **consumer-owned** narrow `Store` interface\n\u003e (Update/Transition/InsertEvent) and its own **domain-owned** `Task` type plus\n\u003e `Status`/`Source` vocabulary. It imports **zero** `internal/store` symbols — satisfying the\n\u003e Phase 2 acceptance criterion. This is the minimal bound of migration-decisions §4\n\u003e (`store.Task → WorkflowExecution`), pulled forward **because** the acceptance criterion\n\u003e requires it.\n\u003e - The **daemon / webui / intake** store surfaces (`TaskStore`, `CaptureStore`,\n\u003e `MappingStore`, `BindingStore`, `BindingDispatcher`, `BindingTaskCreator`) stay\n\u003e **producer-owned** in `internal/store`, because those consumers are application Line truncated
},
{
"url": "/dev/prds/status-health-surface/",
"title": "/status health surface",
"section": "PRDs",
"body": "# /status health surface\n\n**Status:** Finalised\n**Beads issue:** `archie-core-wp9s`\n\nA reported field must have a truthful source. `/status` reports broker\nconnectivity and the last chat-model call; the container pool, last poll and\nchannel state have no source in the process that answers the command, so they\nare left out rather than faked.\n\n## Background\n\n`archie-core-wp9s` (\"/status and /tasks have the wrong division of labour\")\nasked for two things: `/tasks` owning the live per-task work view, and\n`/status` owning daemon health -- \"broker connectivity, provider\nreachability, channel state, container pool, queue depth, last poll,\nversion\" -- with neither duplicating the other or static config available\nelsewhere (`/model` already lists active provider/model).\n\n## Phase 1\n\n- `/tasks`: new command, `gateway.ChatTaskSummary` extended with\n `Stage`/`Attempt`/`ParkReason`/`UpdatedAt` (all already persisted on\n `store.Task`, zero new instrumentation), sorted actionable-first.\n- `/status`: itemized per-status task counts replaced with one aggregate\n `Queue: N in flight (...)` line (running/waiting/parked only -- queued and\n terminal states excluded as not a health concern). Runtime\n (provider/model) is temporarily left in place; see \"Runtime (provider/model)\"\n under Phase 2's \"Truthful or absent\" for where that stands now.\n\nNot touched: `/agents` (`gateway.AgentReader`/`Router.Agents`) is a separate,\npre-existing command that already has the right shape for \"list active\nwork\" but is never wired to a real implementation in any composition-root\ncall site (`bootstrap.go`, `telegram_setup.go`) -- it always answers \"Agent\nlisting is not configured.\" in production. That is a standalone bug\n(`archie-core-mxls`), not folded into this work: deciding whether to wire\nit, repurpose it, or delete it in favor of `/tasks` is Sam's call, not\nsomething to resolve by implication here.\n\n## Phase 2 -- health checks, verified against the actual tree\n\nEach bullet below was checked against real code before being called cheap\nor not; nothing here is guessed. Both open questions were settled (see \"The two\ndecisions\"). The health section reports the broker connection and the last\nchat-model call; the three facts the answering process cannot see are covered\nunder \"Truthful or absent\".\n\n### Verified as cheap against the tree\n\n- **Broker connectivity.** `internal/infrastructure/eventbus/nats.Client`\n already exposes `CoreConn() (*nats.Conn, error)`\n (`client.go`). The underlying `nats.Conn` (nats.go) has its own\n `Status()`/`IsConnected()`. A `Client.Connected() bool` wrapper is a few\n lines.\n- **Container pool.** `container.Pool` already tracks `active int` under\n its own mutex (`pool.go`) but has no public accessor. A\n `Pool.Active() int` getter is a few lines.\n- **Last poll.** Nothing tracks this. The daemon's poll loop\n (`internal/daemon`) needs one `lastPollAt time.Time` field (atomic or\n mutex-guarded, matching the pool's own pattern) set at the top of each\n poll tick, with a getter.\n- **Queue depth.** Covered by Phase 1.\n\n### The two decisions\n\n- **Provider reachability is last-known outcome, never a live probe.** A chat\n command must not perform a blocking network call in its handler, and a probe\n reports the probe's reachability rather than the daemon's. `/status` therefore\n prints what actually happened -- the last chat-model call's model, age and\n error, or \"no calls attempted yet\" when there has been none. Implemented as\n `providerOutcomeRecorder`, written once in `sendChatTurn` (the single point\n every chat-model call in the process passes through) and read back by\n `newStatusHealth`. Nothing on this path dials a provider. The existing live\n model reachability check (`readiness.go`'s `modelReachProbe`) is unchanged and\n stays where it belongs: on `/health/detailed`, off the chat path.\n- **Channel state comes from the existing ChannelManager.** `/status` reads\n `status.Manager.Snapshot()` -- the same ledger the dashboard and the readiness\n probe already use -- rather than re-deriving channel health from each adapter.\n No method was added to the `Channel`/`Gateway` contract.\n\n### Phase 2\n\n- **Broker connectivity.** `internal/infrastructure/eventbus/nats.Client` gained\n `Connected() bool`, which reads the connection the process already holds. The\n standalone Gateway (which dials NATS itself for task actions) reports the same\n fact from that connection.\n- **Container pool.** `container.Pool.Active()` and `Pool.Cap()` read the pool's\n own counter and configured `max_concurrency` -- not a Docker listing, which\n would include containers this pool does not own. A cap of zero means\n unlimited, so `/status` renders the count alone rather than \"1/0 active\".\n- **Last poll.** `daemon.Daemon.LastPollAt()` reports when the most recent poll\n pass *began*; both poll paths (`poll` for siLine truncated
"body": "# /status health surface\n\n**Status:** Finalised\n**Beads issue:** `archie-core-wp9s`\n\nA reported field must have a truthful source. `/status` reports broker\nconnectivity and the last chat-model call; the container pool, last poll and\nchannel state have no source in the process that answers the command, so they\nare left out rather than faked.\n\n## Background\n\n`archie-core-wp9s` (\"/status and /tasks have the wrong division of labour\")\nasked for two things: `/tasks` owning the live per-task work view, and\n`/status` owning daemon health -- \"broker connectivity, provider\nreachability, channel state, container pool, queue depth, last poll,\nversion\" -- with neither duplicating the other or static config available\nelsewhere (`/model` already lists active provider/model).\n\n## Phase 1\n\n- `/tasks`: new command, `gateway.ChatTaskSummary` extended with\n `Stage`/`Attempt`/`ParkReason`/`UpdatedAt` (all already persisted on\n `store.Task`, zero new instrumentation), sorted actionable-first.\n- `/status`: itemised per-status task counts replaced with one aggregate\n `Queue: N in flight (...)` line (running/waiting/parked only -- queued and\n terminal states excluded as not a health concern). Runtime\n (provider/model) is temporarily left in place; see \"Runtime (provider/model)\"\n under Phase 2's \"Truthful or absent\" for where that stands now.\n\nNot touched: `/agents` (`gateway.AgentReader`/`Router.Agents`) is a separate,\npre-existing command that already has the right shape for \"list active\nwork\" but is never wired to a real implementation in any composition-root\ncall site (`bootstrap.go`, `telegram_setup.go`) -- it always answers \"Agent\nlisting is not configured.\" in production. That is a standalone bug\n(`archie-core-mxls`), not folded into this work: deciding whether to wire\nit, repurpose it, or delete it in favour of `/tasks` is Sam's call, not\nsomething to resolve by implication here.\n\n## Phase 2 -- health checks, verified against the actual tree\n\nEach bullet below was checked against real code before being called cheap\nor not; nothing here is guessed. Both open questions were settled (see \"The two\ndecisions\"). The health section reports the broker connection and the last\nchat-model call; the three facts the answering process cannot see are covered\nunder \"Truthful or absent\".\n\n### Verified as cheap against the tree\n\n- **Broker connectivity.** `internal/infrastructure/eventbus/nats.Client`\n already exposes `CoreConn() (*nats.Conn, error)`\n (`client.go`). The underlying `nats.Conn` (nats.go) has its own\n `Status()`/`IsConnected()`. A `Client.Connected() bool` wrapper is a few\n lines.\n- **Container pool.** `container.Pool` already tracks `active int` under\n its own mutex (`pool.go`) but has no public accessor. A\n `Pool.Active() int` getter is a few lines.\n- **Last poll.** Nothing tracks this. The daemon's poll loop\n (`internal/daemon`) needs one `lastPollAt time.Time` field (atomic or\n mutex-guarded, matching the pool's own pattern) set at the top of each\n poll tick, with a getter.\n- **Queue depth.** Covered by Phase 1.\n\n### The two decisions\n\n- **Provider reachability is last-known outcome, never a live probe.** A chat\n command must not perform a blocking network call in its handler, and a probe\n reports the probe's reachability rather than the daemon's. `/status` therefore\n prints what actually happened -- the last chat-model call's model, age and\n error, or \"no calls attempted yet\" when there has been none. Implemented as\n `providerOutcomeRecorder`, written once in `sendChatTurn` (the single point\n every chat-model call in the process passes through) and read back by\n `newStatusHealth`. Nothing on this path dials a provider. The existing live\n model reachability check (`readiness.go`'s `modelReachProbe`) is unchanged and\n stays where it belongs: on `/health/detailed`, off the chat path.\n- **Channel state comes from the existing ChannelManager.** `/status` reads\n `status.Manager.Snapshot()` -- the same ledger the dashboard and the readiness\n probe already use -- rather than re-deriving channel health from each adapter.\n No method was added to the `Channel`/`Gateway` contract.\n\n### Phase 2\n\n- **Broker connectivity.** `internal/infrastructure/eventbus/nats.Client` gained\n `Connected() bool`, which reads the connection the process already holds. The\n standalone Gateway (which dials NATS itself for task actions) reports the same\n fact from that connection.\n- **Container pool.** `container.Pool.Active()` and `Pool.Cap()` read the pool's\n own counter and configured `max_concurrency` -- not a Docker listing, which\n would include containers this pool does not own. A cap of zero means\n unlimited, so `/status` renders the count alone rather than \"1/0 active\".\n- **Last poll.** `daemon.Daemon.LastPollAt()` reports when the most recent poll\n pass _began_; both poll paths (`poll` for sLine truncated
},
{
"url": "/dev/prds/store/",
"title": "Store",
"section": "PRDs",
"body": "# Store\n\n**Status:** Approved\n**Authority:** `docs/architecture/plugins-and-extensions.md`; supersedes\n`docs/prds/extensions-center.md`, whose installed-inventory states are\nadopted below.\n**Compounds with:** `docs/prds/external-agent-harness.md` (harness Kits),\n`docs/prds/pr-review-agent.md` (the first package).\n\n## Decision\n\nOperators get capabilities from a store: browse, install, update and remove\npackages from the dashboard, with no config file editing. A package is an\nOCI image in a registry. A store catalogue is a list of package references.\nInstalling pins a digest. Every package declares the authority it needs, and\nan update that asks for more stops for the operator's approval.\n\n## Packages\n\nTwo kinds, both ordinary OCI images:\n\n- **Harness Kits.** Kit v3 images, resolved as\n `docs/prds/external-agent-harness.md` decides. Their authority is their\n Kit permission surface.\n- **Archie packages.** An image whose manifest annotation\n `dev.archie.package.v1` carries the descriptor and whose single layer\n carries files. A package contributes any of: workflow definitions,\n prompts, skills, MCP server definitions, and default settings for them.\n\nArchie packages are declarative. They carry no Go, Yaegi or script code that\narchie executes on the host. Anything that runs code ships as a Kit and runs\nin a sandbox. An archie package that references a Kit names it by digest,\nand installing the package installs the Kit.\n\nThe descriptor declares: display name, description, version, the families\nit contributes, the packages it requires, and its authority.\n\n## Authority\n\nA package's authority is the set of grants it needs to work:\n\n- credential services (from its Kits and MCP servers);\n- egress hosts (from its Kits);\n- forge permissions its workflows use: read, comment, review, push, open\n pull request;\n- triggers it registers: watched-repository events, schedules;\n- tools it enables for agents.\n\nInstall shows this list and records the operator's acceptance against the\ndigest. An update whose authority is equal or narrower applies under the\npackage's update policy. An update whose authority is wider waits for\napproval, showing only what widened. Nothing a package does at runtime can\nexceed its accepted authority: archie checks forge actions, triggers and\ntool grants against it, and the egress proxy enforces the Kit's grants.\n\n## Catalogues\n\nA catalogue is an OCI artifact listing package references with digests,\nsigned by the catalogue's key. Archie ships with the default catalogue and\nits public key configured. An operator can add catalogues, for example a\nprivate registry, by reference and public key. A catalogue without a key is\nrefused unless the operator marks it unsigned, which the dashboard shows on\nevery package it supplies.\n\nInstall and update verify the catalogue signature and the package digest.\nArchie never installs a tag it has not resolved to a digest through a\nverified catalogue.\n\n## Organisations\n\n`docs/prds/orgs-and-access.md` is the boundary, and the store follows its\nsplit between the instance and each org.\n\n- **Instance.** Catalogues and their keys are instance configuration, set by\n instance admins. Every org browses the same catalogues.\n- **Org.** Installing, updating, removing, accepting authority and setting the\n update policy are org actions. An installed package, its pinned digest and\n its accepted authority belong to one org. Two orgs can run different\n versions of one package.\n- **Contributions** become org resources: workflows are org workflows,\n profiles are org profiles, and credential bindings name org secrets. A\n workspace uses them only once the org grants them to it.\n- **Authority is an upper bound, not a grant.** Accepting a package's\n authority permits the package to ask; the workflow's identity must still\n hold each grant. A package never creates, grants to or widens an identity.\n- Install and authority acceptance are the `create` and `approve` actions on\n the package, decided by the Authorizer. Org approval policy decides who may\n accept, and no member accepts authority they asked for.\n\n## Install, update, remove\n\n- Installed packages, their pinned digests, accepted authority and update\n policy are org resources in the State Store. They apply without a restart.\n- **Update policy** per package: `manual` (default) or `auto`. `auto` applies\n non-widening updates when the catalogue lists them; widening updates always\n wait.\n- **Setup.** A package whose authority includes a credential with no binding\n installs as `needs_setup`, and links to the binding form or the harness\n setup terminal. Its triggers do not fire until setup completes.\n- **Remove** stops its triggers, removes its contributions, and leaves any\n credential bindings for the operator to delete. A package another\n installed package requires cannot be removed first.\n- Rolling back reinLine truncated
},
{
"url": "/dev/prds/task-logs-pagination/",
"title": "task_logs pagination and bounded retrieval -- decision",
"section": "PRDs",
"body": "# task_logs pagination and bounded retrieval -- decision\n\n**Status:** Approved\n**Date:** 2026-08-26\n**Beads issue:** `archie-core-vq92`\n**Compounds with:** `archie-core-p1bl` (errors serialise as `{}`)\n\n## Decision\n\n`task_logs` becomes a *cursor-paginated, filterable* bounded read, not a\none-shot head-of-file window. The reader in `internal/logging` gains a\nsecond entry point (`Page`) that walks the file forward from a byte\noffset; the tool schema in `internal/gateway/task_tools.go` surfaces\nlevel, time-range and cursor parameters; the response carries an explicit\n\"more available\" signal so a model can either keep paging or hand the\nrest to `send_file` when the operator wants a complete archive.\n\nWe do NOT add an unbounded read path. A single response is still capped at\n`MaxTailLines` (2000) entries. What changes is that pagination makes the\ncap reachable in practice instead of silently terminal.\n\n## Why now\n\n`archie-core-vq92` is the right place to fix this: the chat tool is the\nuser-visible failure mode, but the same defect propagates to every caller\nof `internal/logging.Tail` (`internal/webui/api_logs.go` and the\n`chatTaskLogReaderAdapter` in `cmd/archied/main.go`). Patching the\nreader and the tool together is one change in two layers, not two\nchanges; CLAUDE.md's \"package owns its format end-to-end\" rule means the\nreader is the right place for cursor support regardless.\n\nThe compound with `p1bl` matters: a truncated window of uninformative\nerrors leaves an operator with nothing. Cursor pagination lets the model\nwalk the whole file when a level filter does not narrow enough, and the\nresponse's \"more available\" signal means it can honestly say \"I read N of\nM and stopped there\" instead of presenting the head as complete.\n\n## Shape of the API\n\n### Reader (`internal/logging`)\n\nAdd a second entry point next to `Tail`:\n\n```go\n// Page walks the log forward from cursor (a byte offset; 0 starts at\n// the beginning of the scanned window), applying the same filters as\n// Tail. PageResult.Cursor is the file offset just past the last line\n// the walk returned; pass it back as Cursor to continue, and stop when\n// MoreAvailable is false.\nfunc Page(path string, q Query, cursor int64) (PageResult, error)\n```\n\n`PageResult` carries `Entries`, `Truncated` (the existing meaning --\nolder entries exist that were not examined within `maxScanBytes`),\n`Cursor` (the byte offset the next page should resume from), and\n`MoreAvailable` (true iff the scan saw more matching entries beyond the\nreturned page within the same call).\n\n`Cursor` is a byte offset rather than an entry ID for two reasons.\nFirst, `TaskSink` writes JSONL through `slog.NewJSONHandler` directly --\nwithout routing through `FeedHandler` -- so the on-disk entries carry no\n`id` field and a per-task attempt monotonic counter would require\neither a sink-side change or a reader-side reconstruction that is\nbrittle against rotation. Second, the byte offset uniquely identifies\n\"the next unread position\" in a sequential scan, which is exactly what\nthe call pattern needs. A cursor that points at or past the file's\ncurrent size is treated as end-of-stream (empty page, `MoreAvailable`\nfalse).\n\nThe implementation is `readWindow` (reads the tail-most `maxScanBytes`\ninto a single in-memory buffer) plus `readLines` (clamps the cursor into\nthe window, drops a partial first line on the size-cap seek, then\ndelegates) plus `walkWindow` (walks the buffer line-by-line by exact\nslice offset). Offsets are into one contiguous buffer, so they are\ntrivially correct -- unlike an incremental reader over the file, whose\n`bufio.Reader` buffer-ahead would make its underlying file position\nunusable as a cursor.\n\n`Tail` is NOT a wrapper over `Page`: it keeps its legacy ring-buffer\nsemantics (newest `Limit` matches, oldest dropped, `Truncated` set on\nring overflow). They share `readWindow`/`walkWindow` but stay separate\nentry points precisely so Tail's established behaviour is unchanged.\n\n### `Query` gains two optional fields\n\n```go\nSince time.Time // inclusive lower bound on entry.Time\nUntil time.Time // inclusive upper bound on entry.Time\n```\n\n`Levels`, `Component`, `Contains`, `Limit` are unchanged. The existing\nfilter logic and tests move unchanged.\n\n### Tool schema (`internal/gateway/task_tools.go`)\n\n`ChatTaskLogQuery` gains three fields:\n\n- `Level []string` (forwarded to `Query.Levels`)\n- `Since time.Time` / `Until time.Time` (forwarded as `Query.Since/Until`)\n- `AfterID int64` (the cursor; 0 to start at the beginning)\n\n`ChatTaskLogResult` gains two fields:\n\n- `Cursor int64` -- highest ID in this page; pass back as `AfterID` to continue\n- `MoreAvailable bool` -- true iff the scan saw more matching entries that\n did not fit in this page\n\nThe tool description is updated to teach the model the pagination\nprotocol in one sentence: \"pass the previous `cursor` back as `Line truncated
"body": "# task_logs pagination and bounded retrieval -- decision\n\n**Status:** Approved\n**Date:** 2026-08-26\n**Beads issue:** `archie-core-vq92`\n**Compounds with:** `archie-core-p1bl` (errors serialise as `{}`)\n\n## Decision\n\n`task_logs` becomes a _cursor-paginated, filterable_ bounded read, not a\none-shot head-of-file window. The reader in `internal/logging` gains a\nsecond entry point (`Page`) that walks the file forward from a byte\noffset; the tool schema in `internal/gateway/task_tools.go` surfaces\nlevel, time-range and cursor parameters; the response carries an explicit\n\"more available\" signal so a model can either keep paging or hand the\nrest to `send_file` when the operator wants a complete archive.\n\nWe do NOT add an unbounded read path. A single response is still capped at\n`MaxTailLines` (2000) entries. What changes is that pagination makes the\ncap reachable in practice instead of silently terminal.\n\n## Why now\n\n`archie-core-vq92` is the right place to fix this: the chat tool is the\nuser-visible failure mode, but the same defect propagates to every caller\nof `internal/logging.Tail` (`internal/webui/api_logs.go` and the\n`chatTaskLogReaderAdapter` in `cmd/archied/main.go`). Patching the\nreader and the tool together is one change in two layers, not two\nchanges; CLAUDE.md's \"package owns its format end-to-end\" rule means the\nreader is the right place for cursor support regardless.\n\nThe compound with `p1bl` matters: a truncated window of uninformative\nerrors leaves an operator with nothing. Cursor pagination lets the model\nwalk the whole file when a level filter does not narrow enough, and the\nresponse's \"more available\" signal means it can honestly say \"I read N of\nM and stopped there\" instead of presenting the head as complete.\n\n## Shape of the API\n\n### Reader (`internal/logging`)\n\nAdd a second entry point next to `Tail`:\n\n```go\n// Page walks the log forward from cursor (a byte offset; 0 starts at\n// the beginning of the scanned window), applying the same filters as\n// Tail. PageResult.Cursor is the file offset just past the last line\n// the walk returned; pass it back as Cursor to continue, and stop when\n// MoreAvailable is false.\nfunc Page(path string, q Query, cursor int64) (PageResult, error)\n```\n\n`PageResult` carries `Entries`, `Truncated` (the existing meaning --\nolder entries exist that were not examined within `maxScanBytes`),\n`Cursor` (the byte offset the next page should resume from), and\n`MoreAvailable` (true iff the scan saw more matching entries beyond the\nreturned page within the same call).\n\n`Cursor` is a byte offset rather than an entry ID for two reasons.\nFirst, `TaskSink` writes JSONL through `slog.NewJSONHandler` directly --\nwithout routing through `FeedHandler` -- so the on-disk entries carry no\n`id` field and a per-task attempt monotonic counter would require\neither a sink-side change or a reader-side reconstruction that is\nbrittle against rotation. Second, the byte offset uniquely identifies\n\"the next unread position\" in a sequential scan, which is exactly what\nthe call pattern needs. A cursor that points at or past the file's\ncurrent size is treated as end-of-stream (empty page, `MoreAvailable`\nfalse).\n\nThe implementation is `readWindow` (reads the tail-most `maxScanBytes`\ninto a single in-memory buffer) plus `readLines` (clamps the cursor into\nthe window, drops a partial first line on the size-cap seek, then\ndelegates) plus `walkWindow` (walks the buffer line-by-line by exact\nslice offset). Offsets are into one contiguous buffer, so they are\ntrivially correct -- unlike an incremental reader over the file, whose\n`bufio.Reader` buffer-ahead would make its underlying file position\nunusable as a cursor.\n\n`Tail` is NOT a wrapper over `Page`: it keeps its legacy ring-buffer\nsemantics (newest `Limit` matches, oldest dropped, `Truncated` set on\nring overflow). They share `readWindow`/`walkWindow` but stay separate\nentry points precisely so Tail's established behaviour is unchanged.\n\n### `Query` gains two optional fields\n\n```go\nSince time.Time // inclusive lower bound on entry.Time\nUntil time.Time // inclusive upper bound on entry.Time\n```\n\n`Levels`, `Component`, `Contains`, `Limit` are unchanged. The existing\nfilter logic and tests move unchanged.\n\n### Tool schema (`internal/gateway/task_tools.go`)\n\n`ChatTaskLogQuery` gains three fields:\n\n- `Level []string` (forwarded to `Query.Levels`)\n- `Since time.Time` / `Until time.Time` (forwarded as `Query.Since/Until`)\n- `AfterID int64` (the cursor; 0 to start at the beginning)\n\n`ChatTaskLogResult` gains two fields:\n\n- `Cursor int64` -- highest ID in this page; pass back as `AfterID` to continue\n- `MoreAvailable bool` -- true iff the scan saw more matching entries that\n did not fit in this page\n\nThe tool description is updated to teach the model the pagination\nprotocol in one sentence: \"pass the previous `cursor` back as `Line truncated
},
{
"url": "/dev/prds/task-run-detail/",
"title": "Per-run task detail: attempts, stages, changes, config, debug",
"section": "PRDs",
"body": "# Per-run task detail: attempts, stages, changes, config, debug\n\n**Status:** Approved\n**Authority:** the surface contract itself is\n`docs/architecture/observability.md`.\n**Date:** 2026-09-18\n**Compounds with:** `docs/prds/task-logs-pagination.md` (a bounded read says\nwhat it does not show), `docs/prds/status-health-surface.md` (no surface that\nanswers something already answered elsewhere).\n\n## Decision\n\nA task gets one detail page that answers \"what did this run actually do?\" per\n**attempt**: an ordered stage rail, the change each commit/push produced, the\neffective configuration the attempt ran under, the attempt's log, and the raw\nrecord behind all of it.\n\nThe single organising idea is **attempt attribution**. The dashboard\nrenders a task's whole event stream as one flat timeline, so a retried task\nreads as one long run with two of everything. Every new panel is scoped to one\nattempt and says which one.\n\nThe second organising idea is **provenance, not re-derivation**. What a run\nproduced is captured at the producer, while the evidence exists, and persisted\ndurably. Nothing in this surface tries to reconstruct a past run from state\nthat has since moved on.\n\n## The requirement set\n\n| # | Requirement | Mechanism |\n| --- | --- | --- |\n| R1 | Per-attempt stage rail: stages with name, start, duration, terminal status and error, ordered within one attempt | `GET /api/tasks/{id}/attempts` reads the task's events and groups them by `attempt` |\n| R2 | Events carry an attempt, migrated safely and carried on the wire | `events.attempt` column + presence-gated migrator arm; `Event.attempt = 11` |\n| R3 | Changed files captured at commit/push, persisted per task, exposed, shown with repo/PR links | `changes_captured` durable event written by the commit/push steps; `GET /api/tasks/{id}/changes` |\n| R4 | The effective configuration an attempt ran under, secrets redacted, shown | `config_captured` durable event written once per attempt; read from the events response the page already holds |\n| R5 | Log pane filters by attempt, stage and level; absence stays distinct from an unreadable deployment | `logging.Query.Stage` + `ReadTaskLogRequest.stage = 9`; the pane keeps `disabled` and `found=false` apart |\n| R6 | Retry is reachable from the run view and produces a new attempt shown as a new run | Existing retry action, labelled as a NEW run whose confirm states the previous attempt's commits are discarded |\n| R7 | Raw JSON of the task record and its events for the selected attempt | `GET /api/tasks/{id}/debug` |\n| R8 | Deep-linkable, reload-safe per-task detail page that keeps existing URLs working | `/tasks/{id}` route beside the existing `/tasks?task=N` and `/tasks?status=...` |\n| R9 | Design polish: hierarchy, tokens, both themes, responsive rail, a11y, loading/empty/error states | UI lane; measured at 480px and 700px in both themes |\n| R10 | Documentation of record | This document plus `docs/architecture/observability.md` |\n| R11 | Red-first tests for every new behaviour, full gate, `task ui`, forced `go build ./...`, `go test -race` on touched packages | Per lane; the anti-cost-cutting requirement lives here |\n\n## Attempt attribution: a column, not a guess\n\n`events.Event.Attempt`, persisted by `internal/store` as the `events.attempt`\ncolumn (`internal/store/events.go`, `eventsSchema`), is a real column,\n`NOT NULL DEFAULT 0`. It was chosen over segmenting the stream on `task_queued` /\n`task_retried` because a fold would have to guess which side of a boundary an\nevent belongs to when the daemon restarts mid-attempt, when `RecoverStale`\nrequeues, or when two attempts interleave across a crash. A guess rendered as\nstructure is exactly the false fidelity this surface exists to avoid; a column\nis durable, queryable and ordered by construction.\n\n**`0` means \"not attributable\".** It is every row written before this change\nplus the deliberately task-agnostic producers. It is not an attempt number and\nis never rendered as one. The attempts endpoint reports the count of\nunattributed events so the page can say so instead of presenting old history as\nattempt 1.\n\n## Migration against an existing `archie.db`\n\nThe store's migrator (`migrateTasks` in `internal/store/store.go`) already reads\n`PRAGMA table_info` through `tableColumns` and applies a presence-gated\n`ALTER TABLE ... ADD COLUMN` list. This change adds an `events` arm: a\n`tableColumns(ctx, tx, \"events\")` read beside the other two, and the entry\n`ALTER TABLE events ADD COLUMN attempt INTEGER NOT NULL DEFAULT 0`.\n\nThree consequences a future maintainer must not get wrong:\n\n- `eventsSchema` is `CREATE TABLE IF NOT EXISTS` (`internal/store/events.go`),\n so on an existing database it is a **no-op**. The migrator arm is the only\n thing that adds the column there. This is why the red test builds a raw\n SQLite file with the pre-change `events` DDL and must fail before the arm\n exists: eveLine truncated
"body": "# Per-run task detail: attempts, stages, changes, config, debug\n\n**Status:** Approved\n**Authority:** the surface contract itself is\n`docs/architecture/observability.md`.\n**Date:** 2026-09-18\n**Compounds with:** `docs/prds/task-logs-pagination.md` (a bounded read says\nwhat it does not show), `docs/prds/status-health-surface.md` (no surface that\nanswers something already answered elsewhere).\n\n## Decision\n\nA task gets one detail page that answers \"what did this run actually do?\" per\n**attempt**: an ordered stage rail, the change each commit/push produced, the\neffective configuration the attempt ran under, the attempt's log, and the raw\nrecord behind all of it.\n\nThe single organising idea is **attempt attribution**. The dashboard\nrenders a task's whole event stream as one flat timeline, so a retried task\nreads as one long run with two of everything. Every new panel is scoped to one\nattempt and says which one.\n\nThe second organising idea is **provenance, not re-derivation**. What a run\nproduced is captured at the producer, while the evidence exists, and persisted\ndurably. Nothing in this surface tries to reconstruct a past run from state\nthat has since moved on.\n\n## The requirement set\n\n| # | Requirement | Mechanism |\n| --- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |\n| R1 | Per-attempt stage rail: stages with name, start, duration, terminal status and error, ordered within one attempt | `GET /api/tasks/{id}/attempts` reads the task's events and groups them by `attempt` |\n| R2 | Events carry an attempt, migrated safely and carried on the wire | `events.attempt` column + presence-gated migrator arm; `Event.attempt = 11` |\n| R3 | Changed files captured at commit/push, persisted per task, exposed, shown with repo/PR links | `changes_captured` durable event written by the commit/push steps; `GET /api/tasks/{id}/changes` |\n| R4 | The effective configuration an attempt ran under, secrets redacted, shown | `config_captured` durable event written once per attempt; read from the events response the page already holds |\n| R5 | Log pane filters by attempt, stage and level; absence stays distinct from an unreadable deployment | `logging.Query.Stage` + `ReadTaskLogRequest.stage = 9`; the pane keeps `disabled` and `found=false` apart |\n| R6 | Retry is reachable from the run view and produces a new attempt shown as a new run | Existing retry action, labelled as a NEW run whose confirm states the previous attempt's commits are discarded |\n| R7 | Raw JSON of the task record and its events for the selected attempt | `GET /api/tasks/{id}/debug` |\n| R8 | Deep-linkable, reload-safe per-task detail page that keeps existing URLs working | `/tasks/{id}` route beside the existing `/tasks?task=N` and `/tasks?status=...` |\n| R9 | Design polish: hierarchy, tokens, both themes, responsive rail, a11y, loading/empty/error states | UI lane; measured at 480px and 700px in both themes |\n| R10 | Documentation of record | This document plus `docs/architecture/observability.md` |\n| R11 | Red-first tests for every new behaviour, full gate, `task ui`, forced `go build ./...`, `go test -race` on touched packages | Per lane; the anti-cost-cutting requirement lives here |\n\n## Attempt attribution: a column, not a guess\n\n`events.Event.Attempt`, persisted as the `events.attempt` column\n(`internal/infrastructure/postgres/migrations/0001_state_store.sql`), is a real column,\n`NOT NULL DEFAULT 0`. It was chosen over segmenting the stream on `task_queued` /\n`task_retried` because a fold would have to guess which side of a boundary an\nevent belongs to when the daemon restarts mid-attempt, when `RecoverStale`\nrequeues, or when two attempts interleave across a crash. A guess rendered as\nstrucLine truncated
},
{
"url": "/dev/prds/task-run-master-detail/",
"title": "Task run detail as a master-detail split pane",
"section": "PRDs",
"body": "# Task run detail as a master-detail split pane\n\n**Status:** Approved\n**Authority:** the panel contracts stay as ratified in\n`docs/prds/task-run-detail.md`; this document changes only the run page's\narrangement of them.\n**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution, the\nlog stage filter, the per-panel honesty rules).\n\n## Decision\n\nThe run page's five tabs become two panes. The stage rail is the **master**,\nalways visible on the left. The four context panels — log, changed files,\nconfiguration, debug — are the **inspector** on the right, and their tab bar\nmoves into the inspector. The \"Stages\" tab stops existing.\n\nSelecting a stage switches the inspector to the log tab and sets the log\npane's stage filter to that stage. Changing the filter afterwards is the\noperator's choice and is not overridden; rail selection never touches the\nlevel filter. Clicking the selected stage again returns the filter to all\nstages. A stage with no name is rendered but not selectable.\n\nSwitching attempts resets the stage filter to all stages: a selection was\ncommanded on the attempt it was made on, and a different attempt presents a\ndifferent stage list. Changed files, configuration and debug stay\nattempt-scoped; a stage selection never scopes them.\n\n## What does not change\n\n- No new endpoint, RPC, table or configuration field. Every read is one the\n page already makes.\n- The URL contract: `tab` and `attempt` ride in the query string and survive\n a reload. Log filters are not part of the URL; a reload returns the log to\n all stages. `tab=stages` stays a valid URL and renders the log tab; the\n page never generates it again.\n- Attempt attribution, the log stage filter's coverage limit and every\n honesty rule in `task-run-detail.md` still apply: each pane states what it\n cannot show under that document's rendering rules.\n- The task header and the attempt selector sit above both panes.\n\n## Arrangement\n\n- Left pane: fixed-width rail (20rem) with the attempt's stage rows. Status,\n duration, error, the stage's agent report, the attempt's status badge and\n start time, and the attempt-attribution footnotes render in the rail.\n- Right pane: the inspector's tab bar plus the selected panel, filling the\n remaining width.\n- Below the shell's 900px frame breakpoint the rail stacks above the\n inspector; neither pane is hidden.\n- Keyboard: the rail keeps its list semantics and each stage row is a real\n button, so selection and deselection work without a pointer; the inspector\n keeps the WAI-ARIA tabs pattern the tab bar already provides.\n\n## Acceptance\n\n1. The rail is visible without opening any tab, and no \"Stages\" trigger exists.\n2. Clicking a stage opens the log filtered to that stage; clicking it again\n shows all stages.\n3. After a stage selection, a filter change made by the operator is kept, and\n the level filter survives the selection.\n4. Switching attempts resets the stage filter to all stages, and no rail row\n on the new attempt renders as selected unless the operator selected it\n there.\n5. `tab=stages` loads and renders the log tab.\n6. Every inspector tab and attempt deep-link survives a reload.\n7. A stage is selectable and deselectable by keyboard, and the selection\n mirrors the log pane's stage filter.\n8. Below 900px the rail stacks above the inspector.\n9. `task check` passes clean and `ui/dist` matches the sources."
"body": "# Task run detail as a master-detail split pane\n\n**Status:** Approved\n**Authority:** the panel contracts stay as ratified in\n`docs/prds/task-run-detail.md`; this document changes only the run page's\narrangement of them.\n**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution, the\nlog stage filter, the per-panel honesty rules).\n\n## Decision\n\nThe run page's five tabs become two panes. The stage rail is the **master**,\nalways visible on the left. The four context panels — log, changed files,\nconfiguration, debug — are the **inspector** on the right, and their tab bar\nmoves into the inspector. The \"Stages\" tab stops existing.\n\nSelecting a stage switches the inspector to the log tab and sets the log\npane's stage filter to that stage. Changing the filter afterwards is the\noperator's choice and is not overridden; rail selection never touches the\nlevel filter. Clicking the selected stage again returns the filter to all\nstages. A stage with no name is rendered but not selectable.\n\nSwitching attempts resets the stage filter to all stages: a selection was\ncommanded on the attempt it was made on, and a different attempt presents a\ndifferent stage list. Changed files, configuration and debug stay\nattempt-scoped; a stage selection never scopes them.\n\n## What does not change\n\n- No new endpoint, RPC, table or configuration field. Every read is one the\n page already makes.\n- The URL contract: `tab` and `attempt` ride in the query string and survive\n a reload. Log filters are not part of the URL; a reload returns the log to\n all stages. `tab=stages` stays a valid URL and renders the log tab; the\n page never generates it again.\n- Attempt attribution, the log stage filter's coverage limit and every\n honesty rule in `task-run-detail.md` still apply: each pane states what it\n cannot show under that document's rendering rules.\n- The task header and the attempt selector sit above both panes.\n\n## Arrangement\n\n- Left pane: fixed-width rail (20rem) with the attempt's stage rows. Status,\n duration, error, the stage's agent report, the attempt's status badge and\n start time, and the attempt-attribution footnotes render in the rail.\n- Right pane: the inspector's tab bar plus the selected panel, filling the\n remaining width.\n- Below the shell's 900px frame breakpoint the rail stacks above the\n inspector; neither pane is hidden.\n- Keyboard: the rail keeps its list semantics and each stage row is a real\n button, so selection and deselection work without a pointer; the inspector\n keeps the WAI-ARIA tabs pattern the tab bar already provides.\n\n## Acceptance\n\n1. The rail is visible without opening any tab, and no \"Stages\" trigger exists.\n2. Clicking a stage opens the log filtered to that stage; clicking it again\n shows all stages.\n3. After a stage selection, a filter change made by the operator is kept, and\n the level filter survives the selection.\n4. Switching attempts resets the stage filter to all stages, and no rail row\n on the new attempt renders as selected unless the operator selected it\n there.\n5. `tab=stages` loads and renders the log tab.\n6. Every inspector tab and attempt deep-link survives a reload.\n7. A stage is selectable and deselectable by keyboard, and the selection\n mirrors the log pane's stage filter.\n8. Below 900px the rail stacks above the inspector.\n9. `task check` passes clean and `ui/dist` matches the sources.\n"
},
{
"url": "/dev/prds/ui-service-boundary/",
"title": "UI Service boundary and configuration ownership",
"section": "PRDs",
"body": "# UI Service boundary and configuration ownership\n\n**Status:** Approved\n**Revision:** 1\n**Date:** 2026-09-07\n**Beads issue:** `archie-core-8cda.5.1`\n**Parent:** [`service-decomposition.md`](/dev/prds/service-decomposition/)\n**Prerequisites:** Gateway contract extraction and State Store contract ratification\n\nThis document is the authority for Phase 3 UI Service implementation. It fixes\nthe process boundary, configuration ownership, client contracts, security\nposture, readiness behavior, and migration evidence required by\n`archie-core-8cda.5.2` and later UI extraction work.\n\n## Decision\n\nThe UI Service owns the operator-facing HTTP surface and the compiled SPA. It\nserves `ui/dist` and exposes UI-specific JSON DTOs for dashboard views and\nactions. It does not own conversations, task state, workflow execution,\nchannel lifecycle, forge access, or the daemon's runtime configuration.\n\nThe UI Service consumes two typed remote capabilities:\n\n- Gateway's `gateway.ChatContract` through the versioned Gateway gRPC\n contract, for chat snapshots, messages, turns, streaming, persona changes,\n cancellation, and Gateway task actions.\n- State Store's narrow read/write contracts through the versioned State Store\n gRPC contract, for task views, events, captures, mappings, bindings, and\n configuration data explicitly projected for the dashboard.\n\nThe UI process may compose local adapters during the migration seam, but the\nadapter implements the same wire-safe contract as the remote client. The\nproduction extraction cutover removes the in-process adapter in the same\nchange; a dual-live UI authority is not permitted.\n\n## Boundary and ownership\n\n| Concern | UI Service owns | UI Service may consume | UI Service must not own or receive |\n|---|---|---|---|\n| HTTP and SPA | routes, auth middleware, UI DTOs, assets, HTTP lifecycle | contract results and health snapshots | domain entities or infrastructure handles |\n| Chat | request validation and response projection | Gateway `ChatContract` | `gateway.Router`, `SessionStore`, turn runner, model/provider runtime |\n| Task dashboard | query/action DTOs and HTTP status mapping | State Store narrow contracts and explicitly ratified task-action contract | `*store.Store`, SQL connections, workflow registry, daemon pointer |\n| Configuration page | secret-free view and update request validation | a UI configuration contract owned by the configuration/application boundary | `config.Config`, `config.Holder`, secret registry, reload implementation |\n| Readiness | UI process liveness and dependency readiness aggregation | bounded health results from Gateway and State Store | direct probing of private databases or providers |\n\nEvery value crossing the process boundary is a versioned DTO or scalar contract\nvalue. `internal/webui` may retain temporary Go-side adapters while the\nmigration is in progress, but handlers must map Gateway/State Store values to\nUI-owned response types at the HTTP edge. A constructor accepting a concrete\nGateway, State Store, daemon, or `config.Holder` is not an approved final\nboundary.\n\nThe existing UI routes remain behaviorally compatible during extraction,\nincluding task actions, SSE event delivery, config views, chat streaming,\ncapture intake, mappings, bindings, update reporting, and health endpoints.\nCompatibility preserves status codes, authentication requirements, redaction,\npagination/limits, event ordering, and failure degradation unless a separately\nratified contract changes them.\n\nThe route families have these target owners. This is the required inventory for\nthe implementation children; a route without an owner is not eligible for\ncutover.\n\n| Route family | Target owner consumed by UI | Migration status |\n|---|---|---|\n| `/api/chat/*` | Gateway `ChatContract` and its versioned client | contract seam exists; DTO and stream parity remain |\n| `/api/tasks/*`, `/api/workflows`, `/api/setup` | State Store read/action contracts plus an explicit execution/admin action contract | State Store adapter exists; UI-facing narrow surface remains |\n| `/events` | State Store `EventsSince`, polled by one UI-process pump feeding `Server.Broadcast` | RESOLVED (`archie-core-za9f`): see migration-decisions, \"Dashboard live event delivery\". No new RPC; replay cursor and drop-recovery are the existing `since` watermark in `sse.go` |\n| `/api/logs`, `/api/logs/stream` | daemon diagnostic feed, host-local | unresolved: `logging.Feed` is in-process on the daemon host and has no contract. The per-task log routes moved off this row: see `/api/tasks/*` above |\n| `/api/tasks/{id}/logs`, `/api/tasks/{id}/logs/download` | State Store task-log read contract (`TaskLogStore`: `ReadTaskLog` + `StreamTaskLogContent`), read by the UI process from the service that owns the state directory | RESOLVED (`archie-core-iaqx`): the UI process composes `TaskLogStore` from its own State Store client and serves the attempt Line truncated
"body": "# UI Service boundary and configuration ownership\n\n**Status:** Approved\n**Revision:** 1\n**Date:** 2026-09-07\n**Beads issue:** `archie-core-8cda.5.1`\n**Parent:** [`service-decomposition.md`](/dev/prds/service-decomposition/)\n**Prerequisites:** Gateway contract extraction and State Store contract ratification\n\nThis document is the authority for Phase 3 UI Service implementation. It fixes\nthe process boundary, configuration ownership, client contracts, security\nposture, readiness behaviour, and migration evidence required by\n`archie-core-8cda.5.2` and later UI extraction work.\n\n## Decision\n\nThe UI Service owns the operator-facing HTTP surface and the compiled SPA. It\nserves `ui/dist` and exposes UI-specific JSON DTOs for dashboard views and\nactions. It does not own conversations, task state, workflow execution,\nchannel lifecycle, forge access, or the daemon's runtime configuration.\n\nThe UI Service consumes two typed remote capabilities:\n\n- Gateway's `gateway.ChatContract` through the versioned Gateway gRPC\n contract, for chat snapshots, messages, turns, streaming, persona changes,\n cancellation, and Gateway task actions.\n- State Store's narrow read/write contracts through the versioned State Store\n gRPC contract, for task views, events, captures, mappings, bindings, and\n configuration data explicitly projected for the dashboard.\n\nThe UI process may compose local adapters during the migration seam, but the\nadapter implements the same wire-safe contract as the remote client. The\nproduction extraction cutover removes the in-process adapter in the same\nchange; a dual-live UI authority is not permitted.\n\n## Boundary and ownership\n\n| Concern | UI Service owns | UI Service may consume | UI Service must not own or receive |\n| ------------------ | -------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |\n| HTTP and SPA | routes, auth middleware, UI DTOs, assets, HTTP lifecycle | contract results and health snapshots | domain entities or infrastructure handles |\n| Chat | request validation and response projection | Gateway `ChatContract` | `gateway.Router`, `SessionStore`, turn runner, model/provider runtime |\n| Task dashboard | query/action DTOs and HTTP status mapping | State Store narrow contracts and explicitly ratified task-action contract | `*store.Store`, SQL connections, workflow registry, daemon pointer |\n| Configuration page | secret-free view and update request validation | a UI configuration contract owned by the configuration/application boundary | `config.Config`, `config.Holder`, secret registry, reload implementation |\n| Readiness | UI process liveness and dependency readiness aggregation | bounded health results from Gateway and State Store | direct probing of private databases or providers |\n\nEvery value crossing the process boundary is a versioned DTO or scalar contract\nvalue. `internal/webui` may retain temporary Go-side adapters while the\nmigration is in progress, but handlers must map Gateway/State Store values to\nUI-owned response types at the HTTP edge. A constructor accepting a concrete\nGateway, State Store, daemon, or `config.Holder` is not an approved final\nboundary.\n\nThe existing UI routes remain behaviourally compatible during extraction,\nincluding task actions, SSE event delivery, config views, chat streaming,\ncapture intake, mappings, bindings, update reporting, and health endpoints.\nCompatibility preserves status codes, authentication requirements, redaction,\npagination/limits, event ordering, and failure degradation unless a separately\nratified contract changes them.\n\nThe route families have these target owners. This is the required inventory for\nthe implementation children; a route without an owner is not eligible for\ncutover.\n\n| Route family | Target owner consumed by UI | Migration status Line truncated
},
{
"url": "/dev/prds/vue-migration-checklist/",
"title": "Preact → Vue 3 + shadcn-vue migration checklist",
"section": "PRDs",
"body": "# Preact → Vue 3 + shadcn-vue migration checklist\n\n**Status:** Approved\n**Date:** 2026-09-20\n**Bead:** `archie-core-tavn` (epic), `archie-core-ocfm` (navigation restructure)\n**Bootstrap commit:** `e18fb8b2`\n\nThe Preact dashboard was deleted, not ported incrementally. This is the list of\nwhat has to exist again, what must not be lost on the way, and the contracts\nthat break silently if missed.\n\nDeleted source is recoverable at `git show e18fb8b2^:ui/src/\u003cpath\u003e`. Every\nclaim below was cross-checked against that tree; where a number is a live\nmeasurement rather than something recoverable from git, it says so.\n\n## Invariants that outlive the framework\n\nThese are not features; they are things other processes depend on. Breaking one\ndoes not show up as a broken page.\n\n- [ ] **Embed contract.** `ui/embed.go` embeds a committed `ui/dist`. The build\n must keep unhashed `assets/index.{js,css}`: dist/ lives in git, and\n hashed names orphan a file on every rebuild.\n- [ ] **Route registry.** `internal/gateway/dashboard_tools.go` hand-copies the\n route table and `TestDashboardPagesRegistryCoversEveryRoute` parses\n `ui/src/router/index.ts` to hold them in step. The parser needs\n `const routes = [` on its own line, `path: \"...\"` on a single line per\n route, and `nav: false` on any entry the registry should skip. That guard\n caught a stale `/chat` entry earlier.\n- [ ] **Mutation headers.** Every POST/PATCH/DELETE must send **both**\n `X-Archie-CSRF: 1` and `Content-Type: application/json`. The server\n returns 403 without the first and 415 without the second\n (`internal/webui/api_tasks.go`, `authorizeTaskMutation`). GET sends\n neither. This is the single most likely thing to silently break every\n write after the port.\n- [x] **History routing.** `createWebHistory`, `base: \"/\"`. Legacy `#/path`\n links are rewritten by `src/legacy-hash-redirect.ts`. The chat navigate\n chip should emit `/tasks`; the Go side already stores bare paths.\n- [ ] **Capability gating.** `GET /api/capabilities`\n (`internal/webui/api_capabilities.go`) returns a `sections` map of ten\n booleans: chat, logs, skills, curators, channels, captures, mappings,\n bindings, and workflows/settings which are always true. A route whose\n section is false must be hidden, not rendered empty. **Fail open**: on a\n failed or null response hide nothing — the old client used a bare\n `.catch(() =\u003e {})` for exactly this. A page that says \"unavailable\" is\n recoverable; a nav entry that vanished is not.\n- [ ] **`LOG_LEVELS`** in `base/log-row.jsx` is a wire contract, not a display\n list: the CSV level filter is matched server-side by `splitCSV` in\n `internal/webui/api_tasks_logs.go`. A value mismatch breaks filtering\n with no error.\n- [ ] **SSE lifecycle.** Three streams, all `id: \u003cn\u003e\\ndata: \u003cjson\u003e\\n\\n` except\n chat which omits the id:\n `/events` (task lifecycle, `sse.go`, supports `?since=` and\n `Last-Event-ID` resume), `/api/logs/stream` (`api_logs.go`, same\n resume protocol), `/api/chat/stream` (`api_chat.go`, frames typed\n delta/tool/media/navigate). Each must be closed on unmount or the app\n leaks a connection per navigation. Preact used an `archie:teardown`\n event; Vue should use `onUnmounted`.\n\n\u003e **On tests.** Per Sam's call, the 43-file suite was not ported and tests\n\u003e return when there is behaviour worth pinning. Flagging one exception for when\n\u003e that moment comes: the deleted `ui/test/api-client.test.js` classified every\n\u003e API method as mutation/read/stream/url and asserted the right headers per\n\u003e class. It is the only cheap guard on the CSRF contract above. (It did **not**\n\u003e text-scan for a second `fetch()` — that check was deliberately removed\n\u003e upstream for testing the file's wording rather than its behaviour.)\n\n## Phase 1 — Foundation\n\n- [x] **Theme.** `css/tokens.css` was a complete two-theme semantic token set\n (`--fg-subtle`, `--accent`, `--ok/warn/danger`, surfaces, shadows). Mapped\n onto Tailwind v4's `@theme` in `src/style.css`; the second system was not\n kept.\n- [x] **`color-scheme`.** `[data-theme=\"dark\"] { color-scheme: dark }` and the\n light equivalent. Without it the UA paints light scrollbars and light\n native controls inside the dark app. Fixed; trivially lost.\n- [x] **Contrast values.** The violet palette moved these off the values pinned\n here, so they were recomputed against its own backgrounds instead of\n carried: `--fg-subtle` `#A99DBD` dark (7.67:1, AAA) / `#6E6577` light\n (4.87:1, AA), and `--fg-muted` `#B9AECB` / `#635B6B` (9.28:1 and 5.70:1).\n The invariant the pin existed for holds; the values are the palette's.\n- [x] **API client** (`base/api.jsx` → `src/lib/api.tLine truncated
"body": "# Preact → Vue 3 + shadcn-vue migration checklist\n\n**Status:** Approved\n**Date:** 2026-09-20\n**Bead:** `archie-core-tavn` (epic), `archie-core-ocfm` (navigation restructure)\n**Bootstrap commit:** `e18fb8b2`\n\nThe Preact dashboard was deleted, not ported incrementally. This is the list of\nwhat has to exist again, what must not be lost on the way, and the contracts\nthat break silently if missed.\n\nDeleted source is recoverable at `git show e18fb8b2^:ui/src/\u003cpath\u003e`. Every\nclaim below was cross-checked against that tree; where a number is a live\nmeasurement rather than something recoverable from git, it says so.\n\n## Invariants that outlive the framework\n\nThese are not features; they are things other processes depend on. Breaking one\ndoes not show up as a broken page.\n\n- [ ] **Embed contract.** `ui/embed.go` embeds a committed `ui/dist`. The build\n must keep unhashed `assets/index.{js,css}`: dist/ lives in git, and\n hashed names orphan a file on every rebuild.\n- [ ] **Route registry.** `internal/gateway/dashboard_tools.go` hand-copies the\n route table and `TestDashboardPagesRegistryCoversEveryRoute` parses\n `ui/src/router/index.ts` to hold them in step. The parser needs\n `const routes = [` on its own line, `path: \"...\"` on a single line per\n route, and `nav: false` on any entry the registry should skip. That guard\n caught a stale `/chat` entry earlier.\n- [ ] **Mutation headers.** Every POST/PATCH/DELETE must send **both**\n `X-Archie-CSRF: 1` and `Content-Type: application/json`. The server\n returns 403 without the first and 415 without the second\n (`internal/webui/api_tasks.go`, `authorizeTaskMutation`). GET sends\n neither. This is the single most likely thing to silently break every\n write after the port.\n- [x] **History routing.** `createWebHistory`, `base: \"/\"`. Legacy `#/path`\n links are rewritten by `src/legacy-hash-redirect.ts`. The chat navigate\n chip should emit `/tasks`; the Go side already stores bare paths.\n- [ ] **Capability gating.** `GET /api/capabilities`\n (`internal/webui/api_capabilities.go`) returns a `sections` map of ten\n booleans: chat, logs, skills, curators, channels, captures, mappings,\n bindings, and workflows/settings which are always true. A route whose\n section is false must be hidden, not rendered empty. **Fail open**: on a\n failed or null response hide nothing — the old client used a bare\n `.catch(() =\u003e {})` for exactly this. A page that says \"unavailable\" is\n recoverable; a nav entry that vanished is not.\n- [ ] **`LOG_LEVELS`** in `base/log-row.jsx` is a wire contract, not a display\n list: the CSV level filter is matched server-side by `splitCSV` in\n `internal/webui/api_tasks_logs.go`. A value mismatch breaks filtering\n with no error.\n- [ ] **SSE lifecycle.** Three streams, all `id: \u003cn\u003e\\ndata: \u003cjson\u003e\\n\\n` except\n chat which omits the id:\n `/events` (task lifecycle, `sse.go`, supports `?since=` and\n `Last-Event-ID` resume), `/api/logs/stream` (`api_logs.go`, same\n resume protocol), `/api/chat/stream` (`api_chat.go`, frames typed\n delta/tool/media/navigate). Each must be closed on unmount or the app\n leaks a connection per navigation. Preact used an `archie:teardown`\n event; Vue should use `onUnmounted`.\n\n\u003e **On tests.** Per Sam's call, the 43-file suite was not ported and tests\n\u003e return when there is behaviour worth pinning. Flagging one exception for when\n\u003e that moment comes: the deleted `ui/test/api-client.test.js` classified every\n\u003e API method as mutation/read/stream/url and asserted the right headers per\n\u003e class. It is the only cheap guard on the CSRF contract above. (It did **not**\n\u003e text-scan for a second `fetch()` — that check was deliberately removed\n\u003e upstream for testing the file's wording rather than its behaviour.)\n\n## Phase 1 — Foundation\n\n- [x] **Theme.** `css/tokens.css` was a complete two-theme semantic token set\n (`--fg-subtle`, `--accent`, `--ok/warn/danger`, surfaces, shadows). Mapped\n onto Tailwind v4's `@theme` in `src/style.css`; the second system was not\n kept.\n- [x] **`color-scheme`.** `[data-theme=\"dark\"] { color-scheme: dark }` and the\n light equivalent. Without it the UA paints light scrollbars and light\n native controls inside the dark app. Fixed; trivially lost.\n- [x] **Contrast values.** The violet palette moved these off the values pinned\n here, so they were recomputed against its own backgrounds instead of\n carried: `--fg-subtle` `#A99DBD` dark (7.67:1, AAA) / `#6E6577` light\n (4.87:1, AA), and `--fg-muted` `#B9AECB` / `#635B6B` (9.28:1 and 5.70:1).\n The invariant the pin existed for holds; the values are the palette's.\n- [x] **API client** (`base/api.jsx` → `src/lib/api.tLine truncated
},
{
"url": "/dev/prds/webhook-intake-security/",
"title": "Webhook intake security -- decision",
"section": "PRDs",
"body": "# Webhook intake security -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.5`, blocks `archie-core-t2db.4`\n\n## Why this is decided ahead of the code it constrains\n\n`archie-core-t2db` (no-code playbooks) and `archie-core-7d5u` (typed event\nsources) both land a public intake surface whose eventual output is an agent\nwith tool access and a repo. Neither capture (`t2db.1`) nor the intake family\n(`7d5u.3`) has shipped yet, so this decision exists to be a contract the two\nepics build against, not a retrofit once the surface exists. A webhook URL\nthat can start an agent is remote code execution with extra steps if any of\nthe five points below is missing on day one.\n\n## 1. Per-source authentication\n\nReuse the per-route HMAC-SHA256 scheme already in\n`internal/channels/webhook/webhook.go` (`validateHMAC`), unchanged: a source\nregisters with a shared secret; the signature is checked against the raw\nbody. Do not invent a second scheme for intake.\n\n**Capture and triggering split at the signature, not at a separate flag.** An\nevent with a missing or invalid signature is still captured (visible in the\ninspector, marked unauthenticated) so an operator can diagnose a\nmisconfigured sender -- but an unauthenticated event can never be matched\nagainst a binding. Authentication is what promotes an event from \"something\narrived\" to \"something that can run a workflow.\"\n\n## 2. Human approval before a binding arms\n\nA binding has three states: `draft -\u003e pending_approval -\u003e armed`. Only\n`armed` bindings are evaluated against incoming events. Creating or editing a\nbinding's matcher, mapping, or target workflow always sets it to\n`pending_approval`, including edits to an already-armed binding -- an edit is\nnot silently re-armed, or the approval gate is decorative. Approval requires\nan authenticated dashboard session; there is no unattended approval path.\n\nModel: `internal/channels/telegram`'s dangerous-command approval flow\n(`dangerousAction` / `pendingApproval` in `dangerous.go` / `approval.go`) is\nthe existing precedent for \"a human decision gates code from running\" in this\ncodebase -- follow its shape rather than designing a new approval primitive.\n\n## 3. Rate and volume limits, per source\n\nA token-bucket limiter keyed by source ID, not global -- one noisy or hostile\nsender must not exhaust another source's capture budget. Precedent for\nper-key volume capping: `internal/pairing/store.go`'s `MaxPendingPerPlatform`.\n\nOn limit exceeded, the request is rejected (HTTP 429), not silently dropped.\nA silently dropped event is indistinguishable from a sender that never fired\n-- the same invisible-failure shape the update-verification work\n(`archie-core-522`) exists to prevent. The rejection itself is observable in\nthe inspector as a distinct outcome from \"not received.\"\n\n## 4. Blast radius bounded by code, not by prompt wording\n\nA playbook-triggered task runs through exactly the same enforcement as every\nother task: the `[[repos.gate]]` quality gate, `diff_cap_lines`, the\nsandboxed per-task container (`internal/container`), worktree isolation, and\n\"the model never runs git.\" No new relaxation is introduced for\nplaybook-triggered work, and none is needed -- the existing constraints are\nthe control.\n\nMapped payload fields are treated as ordinary user-controlled text inside an\nagent prompt, exactly like an inbound chat message never as trusted\ninstructions. \"The agent should ignore instructions in the payload\" is not a\ncontrol and must not appear as one anywhere in this feature -- per the\nenvironmental-enforcement principle (`docs/architecture/agent-system.md`,\n\"Existing invariants to preserve\"), the boundary is the gate and the sandbox,\nnot a sentence in the system prompt.\n\n## 5. Retention and redaction of captured payloads\n\n**Retention:** captured events (bound or not) are purged after 7 days,\nconfigurable per deployment. Unbound events exist to be mapped against; nothing\njustifies keeping them indefinitely once that window has passed, and an\nunbounded capture store is the same disk-exhaustion risk item 3 addresses at\nthe request-rate level.\n\n**Redaction:** before a captured payload is persisted, apply the same\nkey-name heuristic `internal/gateway/stream.go`'s `sensitiveParameterKey`\nalready uses for tool-call parameters (matches `token`, `secret`, `password`,\n`passwd`, `api_key`, `apikey`, `authorization`, `credential`, `cookie`,\n`private_key` against normalized JSON keys) and replace matching values with\nthe same `[redacted]` marker. This is best-effort, not a guarantee -- a\nsender that names a secret field something the heuristic misses will still\nhave it captured. Document that limitation where captured payloads are\ndisplayed, rather than implying the redaction is complete.\n\n**Visibility:** captured payloads, redacted or not, are visible only to an\nauthenticated dashboarLine truncated
"body": "# Webhook intake security -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.5`, blocks `archie-core-t2db.4`\n\n## Why this is decided ahead of the code it constrains\n\n`archie-core-t2db` (no-code playbooks) and `archie-core-7d5u` (typed event\nsources) both land a public intake surface whose eventual output is an agent\nwith tool access and a repo. Neither capture (`t2db.1`) nor the intake family\n(`7d5u.3`) has shipped yet, so this decision exists to be a contract the two\nepics build against, not a retrofit once the surface exists. A webhook URL\nthat can start an agent is remote code execution with extra steps if any of\nthe five points below is missing on day one.\n\n## 1. Per-source authentication\n\nReuse the per-route HMAC-SHA256 scheme already in\n`internal/channels/webhook/webhook.go` (`validateHMAC`), unchanged: a source\nregisters with a shared secret; the signature is checked against the raw\nbody. Do not invent a second scheme for intake.\n\n**Capture and triggering split at the signature, not at a separate flag.** An\nevent with a missing or invalid signature is still captured (visible in the\ninspector, marked unauthenticated) so an operator can diagnose a\nmisconfigured sender -- but an unauthenticated event can never be matched\nagainst a binding. Authentication is what promotes an event from \"something\narrived\" to \"something that can run a workflow.\"\n\n## 2. Human approval before a binding arms\n\nA binding has three states: `draft -\u003e pending_approval -\u003e armed`. Only\n`armed` bindings are evaluated against incoming events. Creating or editing a\nbinding's matcher, mapping, or target workflow always sets it to\n`pending_approval`, including edits to an already-armed binding -- an edit is\nnot silently re-armed, or the approval gate is decorative. Approval requires\nan authenticated dashboard session; there is no unattended approval path.\n\nModel: `internal/channels/telegram`'s dangerous-command approval flow\n(`dangerousAction` / `pendingApproval` in `dangerous.go` / `approval.go`) is\nthe existing precedent for \"a human decision gates code from running\" in this\ncodebase -- follow its shape rather than designing a new approval primitive.\n\n## 3. Rate and volume limits, per source\n\nA token-bucket limiter keyed by source ID, not global -- one noisy or hostile\nsender must not exhaust another source's capture budget. Precedent for\nper-key volume capping: `internal/pairing/store.go`'s `MaxPendingPerPlatform`.\n\nOn limit exceeded, the request is rejected (HTTP 429), not silently dropped.\nA silently dropped event is indistinguishable from a sender that never fired\n-- the same invisible-failure shape the update-verification work\n(`archie-core-522`) exists to prevent. The rejection itself is observable in\nthe inspector as a distinct outcome from \"not received.\"\n\n## 4. Blast radius bounded by code, not by prompt wording\n\nA playbook-triggered task runs through exactly the same enforcement as every\nother task: the `[[repos.gate]]` quality gate, `diff_cap_lines`, the\nsandboxed per-task container (`internal/container`), worktree isolation, and\n\"the model never runs git.\" No new relaxation is introduced for\nplaybook-triggered work, and none is needed -- the existing constraints are\nthe control.\n\nMapped payload fields are treated as ordinary user-controlled text inside an\nagent prompt, exactly like an inbound chat message never as trusted\ninstructions. \"The agent should ignore instructions in the payload\" is not a\ncontrol and must not appear as one anywhere in this feature -- per the\nenvironmental-enforcement principle (`docs/architecture/agent-system.md`,\n\"Existing invariants to preserve\"), the boundary is the gate and the sandbox,\nnot a sentence in the system prompt.\n\n## 5. Retention and redaction of captured payloads\n\n**Retention:** captured events (bound or not) are purged after 7 days,\nconfigurable per deployment. Unbound events exist to be mapped against; nothing\njustifies keeping them indefinitely once that window has passed, and an\nunbounded capture store is the same disk-exhaustion risk item 3 addresses at\nthe request-rate level.\n\n**Redaction:** before a captured payload is persisted, apply the same\nkey-name heuristic `internal/gateway/stream.go`'s `sensitiveParameterKey`\nalready uses for tool-call parameters (matches `token`, `secret`, `password`,\n`passwd`, `api_key`, `apikey`, `authorization`, `credential`, `cookie`,\n`private_key` against normalised JSON keys) and replace matching values with\nthe same `[redacted]` marker. This is best-effort, not a guarantee -- a\nsender that names a secret field something the heuristic misses will still\nhave it captured. Document that limitation where captured payloads are\ndisplayed, rather than implying the redaction is complete.\n\n**Visibility:** captured payloads, redacted or not, are visible only to an\nauthenticated dashboarLine truncated
}
],
"nav": [
@@ -510,6 +606,44 @@
}
]
},
{
"title": "Development guides",
"url": "/dev/development/",
"items": [
{
"title": "Agent",
"url": "/dev/development/agent/"
},
{
"title": "Control plane and settings",
"url": "/dev/development/control-plane/"
},
{
"title": "Daemon",
"url": "/dev/development/daemon/"
},
{
"title": "Frontend UI",
"url": "/dev/development/frontend-ui/"
},
{
"title": "Merging work",
"url": "/dev/development/merging-work/"
},
{
"title": "State Store",
"url": "/dev/development/state-store/"
},
{
"title": "Processes and wiring",
"url": "/dev/development/wiring/"
},
{
"title": "Workflows",
"url": "/dev/development/workflows/"
}
]
},
{
"title": "PRDs",
"items": [
@@ -521,6 +655,10 @@
"title": "PRD writing rules",
"url": "/dev/prds/RULES/"
},
{
"title": "Running action playbooks",
"url": "/dev/prds/action-playbook-run/"
},
{
"title": "Adversarial self-review stage -- decision",
"url": "/dev/prds/adversarial-self-review/"
@@ -573,14 +711,14 @@
"title": "Dashboard live state",
"url": "/dev/prds/dashboard-live-state/"
},
{
"title": "Dashboard navigation groups + Configuration split -- decision",
"url": "/dev/prds/dashboard-navigation-groups/"
},
{
"title": "Dashboard port: what the agent delivers",
"url": "/dev/prds/dashboard-port-brief/"
},
{
"title": "One source for the dashboard's server vocabularies",
"url": "/dev/prds/dashboard-vocabulary/"
},
{
"title": "Deep research capability — design",
"url": "/dev/prds/deep-research-capability/"
@@ -601,6 +739,10 @@
"title": "Embedded NATS execution -- decision",
"url": "/dev/prds/embedded-nats/"
},
{
"title": "Event automation: identified events, typed parameters, purpose-built agents",
"url": "/dev/prds/event-automation/"
},
{
"title": "Event capture storage -- decision",
"url": "/dev/prds/event-capture-storage/"
@@ -610,9 +752,17 @@
"url": "/dev/prds/event-sources-and-reactions/"
},
{
"title": "Extensions center",
"title": "Execution tree and enforced state machine",
"url": "/dev/prds/execution-tree-state-machine/"
},
{
"title": "Extensions centre",
"url": "/dev/prds/extensions-center/"
},
{
"title": "External agent harnesses",
"url": "/dev/prds/external-agent-harness/"
},
{
"title": "Identity for users, agents and external agents — decision",
"url": "/dev/prds/identity-decision/"
@@ -646,13 +796,17 @@
"url": "/dev/prds/multi-action-playbooks/"
},
{
"title": "Public news and per-version release notes -- decision",
"title": "Public news and per-version release notes",
"url": "/dev/prds/news-and-releases/"
},
{
"title": "Operator-triggered PR review",
"url": "/dev/prds/operator-pr-review/"
},
{
"title": "Orgs, workspaces and access control",
"url": "/dev/prds/orgs-and-access/"
},
{
"title": "Payload field mapping -- decision",
"url": "/dev/prds/payload-field-mapping/"
@@ -661,6 +815,10 @@
"title": "Playbook data-flow and condition syntax",
"url": "/dev/prds/playbook-expression-syntax/"
},
{
"title": "PR review agent",
"url": "/dev/prds/pr-review-agent/"
},
{
"title": "PR review comment remediation -- decision",
"url": "/dev/prds/pr-review-remediation/"
@@ -713,6 +871,10 @@
"title": "/status health surface",
"url": "/dev/prds/status-health-surface/"
},
{
"title": "Store",
"url": "/dev/prds/store/"
},
{
"title": "task_logs pagination and bounded retrieval -- decision",
"url": "/dev/prds/task-logs-pagination/"
+1 -1
View File
@@ -4,7 +4,7 @@
"url": "/docs/",
"title": "Archie",
"section": "",
"body": "# Archie\n\nEvent Driven Agentic Automation.\n\nArchie is an agent platform that reacts to events. A forge issue, a signed\nwebhook from any app you run, a message in a chat channel: each arrives as an\nevent, a playbook decides what a matching event sets off, and the work happens\nin an isolated git worktree. GitHub and Gitea issues were the first case. A\nforge is now one event source among several, and a pull request one outcome\namong several.\n\nNothing about that path is wired to a particular forge, channel, or sender.\nSources, the fields they carry, and the workflows they reach are configuration\nyou add without touching code or restarting anything.\n\n## Start here\n\n- [First playbook](/docs/guides/first-playbook/) points an external app's webhook\n at archie, maps the fields of a real payload, and binds them to a workflow.\n- [Architecture](/dev/architecture/) is the authority for settled design:\n the domain boundaries, the workflow engine, the task lifecycle, and the\n invariants that hold the whole thing together.\n\n## What runs where\n\nA deployment is a set of services, each owning one typed contract. The Gateway\nserves conversation turns and sessions, the Messaging Service runs the\nchannels, the State Store owns the database outright, the dashboard is its own\nprocess, and `archied` admits work and drives each task through its workflow.\ngRPC carries the synchronous calls between them; NATS carries asynchronous\nfan-out. Agents execute in containers that receive a task-scoped credential,\nissued per task and revoked when the worktree is handed back.\n\nConfiguration lives at `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`.\nNothing in a working tree is load-bearing at runtime.\n\n## A note on these docs\n\nThis site is generated from the `docs/` directory of the\n[archie-core repository](https://github.com/samcharles93/archie-core) on every\nchange to `main`. The repository is the source; this site is a view of it. If\nthe two ever disagree, the repository is right.\n"
"body": "# Archie\n\n**Event-driven Agentic Automation**\n\nArchie connects events from your systems to agents that can investigate, reason,\nand act. Define what an event means, map its data into a workflow, and give that\nworkflow an agent equipped for the job: its own execution environment, tools,\nand identity.\n\nThe aim is to automate work across system administration, incident response,\nnetwork operations, service management, and software delivery. You define the\nprocess and the access it requires; agents work through its stages, using the\ncontext of each event to decide how to accomplish the task.\n\nArchie is under active development. The model below describes the project's\napproved direction, with implementation progressing across event automation and\norganisation access control. The\n[event automation design](/dev/prds/event-automation/) and\n[organisations and access design](/dev/prds/orgs-and-access/) describe those\ncapabilities and their delivery stages.\n\n## From an event to an outcome\n\n```text\nEvent source → Event type → Mapping → Binding → Workflow → Agent\n```\n\n| Concept | Purpose |\n| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| **Source** | Receive events from a system such as a firewall, monitoring stack, service desk, or forge. Configure its endpoint and signing requirements. |\n| **Event type** | Identify which kind of event arrived from its headers and payload. Infer a schema from captured events or a pasted example. |\n| **Mapping** | Extract named, typed parameters from the event. Reuse a mapping across bindings and see how often it matches. |\n| **Binding** | Select a workflow, filter the events that should trigger it, and supply its inputs from mapped values or constants. |\n| **Workflow** | Define the stages of work, their inputs and outputs, and the agent profile to use. Call other workflows when work needs another specialist or process. |\n| **Agent** | Execute the work in a container with the tools for its purpose, acting under its own identity and granted permissions. |\n\nA single source can produce several event types. An event type can feed several\nbindings, and each binding can apply its own conditions. This lets the same\nincoming data drive different responses without building a custom integration\nfor every workflow.\n\nFor example, a firewall sends a blocked-connection event. Archie identifies the\nevent type and maps the source address and severity into an investigation\nworkflow. A network investigator gathers evidence, assesses the activity, and\nreturns its findings. The workflow could then call a separate containment\nworkflow, subject to the permissions and approvals configured for that action.\n\nThe same model supports other processes:\n\n- **Infrastructure operations:** A monitoring alert starts a diagnostic workflow\n to inspect a service, collect evidence, and propose or perform an authorised\n recovery action.\n- **Service management:** An incoming request supplies the parameters for a\n triage, investigation, or fulfilment workflow.\n- **Software delivery:** A forge event starts a review or implementation\n workflow with the repository's toolchain, validation steps, and pull request\n as its output.\n\nThese are examples of workflows you can build. Their behaviour comes from the\nworkflow, tools, and access you configure.\n\n## Agents equipped for their work\n\nAn agent profile selects the container image and available tools. You can supply\nimages with the software needed for a particular environment: network utilities\nfor an investigator, operational tooling for a systems agent, or a language\nruntime and test framework for repository work.\n\nWorkflows declare structured inputs and can return structured outputs. They can\nrun with a scratch workspace, require a repository, or accept one optionally. An\ninvestigation can finish with a report; a maintenance workflow can finish with\nan operational result; a coding workflow can finish with a pull request.\n\nWorkflows can also call other workflows and pass data between them. Each called\nworkflow has its own run and agent profile. A caller can wait for the result or\ncontinue while the called workflow runs independently.\n\nSee the\n[firewall investigation example](https://github.com/samcharles93/archie-core/blob/main/examples/workflows/firewall-investigate.yaml)\nfor a workflow that uses typed inputs, a network investigator profile, and no\nrepository.\n\n## Organisations, identities, and controlled execution\n\nThe approved access modLine truncated
},
{
"url": "/docs/guides/first-playbook/",
+34
View File
@@ -0,0 +1,34 @@
# Prompt for Claude Code
Unzip this bundle into the repo at `docs/design/ui-redesign/`, then paste the prompt below.
---
The design handoff for the Archie UI redesign is in `docs/design/ui-redesign/`. It covers a new theme, a new
top-level navigation, the Settings pages (Channels moves in there), and the Dashboard, Task detail, Workflows,
New task dialog and Events pages.
Read `README.md` in full, then look at every PNG in `screenshots/`. The `00-current-*.png` files show how the
pages look today; `P0-navigation-map.png` shows what moves where. The static HTML in `mockups/` has the exact
CSS if you need it. `tokens/tokens.css` holds the colours, fonts and sizes.
Treat the spec as a hypothesis to check against the code, not a spec to copy exactly.
Before changing anything:
1. Find how the UI is built: framework, router, component library, where styles and theme colours live,
and where the purple comes from.
2. Map today's routes and the Work / System menus to the proposed navigation in README §2. List every
page that isn't covered and where you'd put it.
3. For Settings and Channels: find how each section loads and saves config, how "Restart required",
"Version", "History" and the audit log work, and where "Connecting" comes from. Map every field in
README §5 to its real config key and type.
4. Answer the backend questions in README §5.2 and §9.
5. Check what data the Dashboard, Task detail and Workflows pages already get, and list anything the
mockups show that isn't available.
Then write a short migration plan using the PR sequence in README §8. Adjust it to what you found and
list anything the mockups assume that the backend doesn't support. Stop and show me the plan before you
write code.
When I approve, do PR 1 only (theme tokens across the whole app, no layout changes) on a new branch, with
before/after screenshots of each page.
+277
View File
@@ -0,0 +1,277 @@
# Archie UI Redesign — Handoff
A redesign of the Archie web UI:
- a calmer **"Graphite" theme** that replaces the purple
- a **new navigation**: five top-level places, with all configuration moved under Settings
- new layouts for **Settings** (every section, plus Channels moved in), the **Dashboard**,
**Task detail**, **Workflows**, a **New task** dialog and **Events**
This folder is self-contained. Read this file first, then look at the screenshots.
```
README.md ← this spec (read it all before planning)
CLAUDE_PROMPT.md ← the prompt to paste into Claude Code
tokens/tokens.css ← theme as CSS custom properties (source of truth)
tokens/tokens.json ← same values as JSON (for Tailwind / JS themes)
screenshots/
00-current-*.png ← how each page looks TODAY
P0-navigation-map ← today → proposed navigation, and what moves where
P1…P5 ← app pages: dashboard, task detail, workflows, new task, events
S1…S5 ← settings: sidebar + rows, personas, tools & MCP, review drawer, channels
T-theme-components ← palette, type, buttons, pills, toggles, inputs
mockups/*.html ← static HTML of each screenshot; open in a browser, inspect for exact CSS
source/*.dc.html ← original design-canvas sources (reference only, needs a runtime that isn't included)
```
> **How to treat this.** The mockups are a target, not a pixel spec. They are static HTML
> written by hand; the app's framework, component library, router and data model win. Where the
> mockups assume something the backend doesn't have, flag it rather than faking it.
> Text in `[square brackets]` in a mockup is a placeholder for real data.
---
## 1. Problems being fixed (all pages)
1. **Purple everywhere.** Purple-tinted backgrounds, borders, buttons, checkboxes, bars and links all compete for attention.
2. **Repeated chrome.** Every settings card has its own "Connecting" pill, "Restart required" pill, "Version 1",
"Save changes" and "History". Workflows and Channels repeat the pattern.
3. **Raw config shapes leak through.** Durations as Go strings (`1h0m0s`, `0s`), bytes as `2000000`,
maps as key/value boxes, secret refs as two separate Engine/Key text fields, booleans as bare checkboxes with no explanation.
4. **No descriptions.** Almost no field says what it does.
5. **Things live in the wrong place.** Channels (configuration) sits under Work; "Start work" sits inside the
workflow editor page; the Channels audit table only covers Channels; workflow analytics mix every workflow together.
6. **The most important information isn't first.** The Dashboard opens with quality gates; the "3 need you" count is a small button.
## 2. Navigation (screenshot `P0-navigation-map.png`)
**Top bar (every page):** logo · **Dashboard · Tasks · Workflows · Events · Settings** · spacer ·
"Jump to…" search (⌘K) · **New task** button · connection pill · account avatar.
The Work and System dropdowns go away. The floating chat button stays, restyled (neutral fill, accent icon).
| Place | Job | Contains |
|---|---|---|
| Dashboard | What needs me right now | Needs-you queue, live activity, health (quality gates, tokens) |
| Tasks | The work | Task list (filter by state), task detail |
| Workflows | How work runs | List with runs/success/cost, definition editor, Performance and Runs tabs |
| Events | What comes in | Inspector, Mappings, Bindings |
| Settings | Everything you configure | **Agents:** Personas, Schedules, Scheduling policy · **Integrations:** Channels, Tools & MCP, Plugins · **Runtime:** Container runtime · **History** |
What moves:
| What | Moves to | Why |
|---|---|---|
| Start work card (Workflows page) | **New task** dialog from the top bar and ⌘K | Starting work isn't editing a workflow |
| Channels (Work menu) | Settings › Integrations › Channels | It's configuration; gets the shared setting rows and save flow |
| Audit table (Channels page) | Settings › History, filterable by section | One change log for all settings; replaces per-card History links |
| Per workflow table | Columns in the Workflows list | Stats next to the workflow you're about to open |
| Slowest stages · Most failures | Workflow › Performance tab | Scoped to the selected workflow |
| Connecting / Version pills on every card | One connection status in the top bar | Connection is global |
| Settings "Managed elsewhere" row | Removed; those are the Events tabs | They already live there |
| Task "Attempt 2 is not recorded" column | Attempts list in the task side rail | Shows every attempt and its outcome |
The dropdown contents of today's Work and System menus were inferred from screenshots. **Check the router** and
place any page not covered here using the same rule: configure → Settings, act on → where the work is.
## 3. Theme
All values are in `tokens/tokens.css`. Rules that matter more than the hex values:
- **One accent, used sparingly.** Default sage `#86b5a0`. Only for: active nav/list item (2px inset left bar + raised background),
active tab underline, focus borders/rings, "edited" dots and counts, toggle "on" track, primary button fill, success text,
the "live"/"running"/"connected" dot, and positive bars. Never for backgrounds, headings or borders at rest.
- Keep the accent a **single variable** so it can be swapped (sage / steel `#8aa4c2` / sand `#d4a373` / muted violet `#a397c9`).
- **Neutral, slightly warm greys**, no hue tint on surfaces and no background gradients. Hierarchy comes from surface steps and borders.
- **Amber = needs attention** (parked, awaiting reply, applies after restart, connecting). **Red = failed / destructive / risky**
(errors, delete, unrestricted filesystem). No other hues except the agent state swatches in the tokens.
- **Fonts:** IBM Plex Sans for UI; **IBM Plex Mono for every machine value**: config values, IDs, keys, env var names,
image refs, durations, paths, event names, task numbers, log lines, counts in tables.
- Text contrast: `--text-3` is the dimmest text allowed, and only for hints and captions.
## 4. Components (screenshot `T-theme-components.png`)
Build these once and reuse everywhere. Heights are 36px unless noted.
| Component | Spec |
|---|---|
| **Button** | primary (accent fill, `--text-on-accent`), secondary (`--raised` + `--border-button`), ghost (transparent, `--text-2`), destructive (red text, transparent). 13px/500, radius 6. Small variant 30px/12px. **One primary per view.** |
| **Text input** | `--bg` fill, `--border-input`, radius 6, mono 13px. Focus: accent border + 3px `--accent-ring`. Invalid: red border + 12px red message. |
| **Input with unit** | input + attached suffix (`MB`, `sec`, `chars`) or unit `<select>`. |
| **Duration input** | number + unit select. Convert to/from Go durations (`30s`, `1m0s`, `72h0m0s`) only at the API boundary. |
| **Byte size input** | number + `MB`; store bytes (2,000,000 bytes = 2 MB, decimal). |
| **Stepper** | − / value / + for small integers. |
| **Toggle** | 36×20 track. On = accent (or red for risky settings), off = `--border-input`. Always labelled; risky ones sit in a bordered row with a one-line consequence. Real checkbox / `role="switch"` underneath. |
| **Segmented control** | 2–4 exclusive options, radiogroup with arrow keys. Selected segment `--raised-2`. |
| **Tabs** | 44px, 13px, `--text-3`; active = `--text` + 2px accent underline. Left-aligned, sized to content (not stretched full width). Optional mono count chip. |
| **Secret reference** | one row: lock icon · engine (mono, dim) · `/` · key (mono) · "Change". Status line below: accent ✓ "Credential resolved by Archie" or red "Credential not found". Replaces separate Engine/Key inputs and the "Credential configured" checkbox. |
| **Chip input** | for lists of IDs (Telegram allowed users): mono chips with × plus an inline input. |
| **Status pill** | radius 999, 12px. Neutral with coloured dot (connection, running, listening), warn (parked, awaiting reply, applies after restart), accent outline (edited count, default), danger (invalid). |
| **Card** | `--surface`, `--border-card`, radius 10. Header row: optional 32px icon tile · title (15px/500) + hint · right-side status/action. |
| **Stat strip** | one card split into equal cells by 1px dividers: label (12px dim), value (30px/600), sub (12px dim). |
| **Data table** | uppercase 11px headers, 13px rows, 1px `--border-subtle` dividers, mono for machine values, long text truncates with ellipsis. |
| **Progress bar** | 4–6px track `--raised-2`, fill accent (good) or red (failing). |
| **Empty state** | icon tile + title + one-line hint + the action (a button, or a copyable value). |
| **Alert banner** | amber or red tinted box: icon · title · mono detail · one action on the right. |
| **Nav item** (sidebars) | 34–36px, radius 6, 13px `--text-2`. Active: `--raised` + 2px inset accent bar. |
| **Dialog** | 640px, `--surface-2`, radius 12, header (title + hint + close), body, footer (shortcut hint · Cancel · primary). Dim backdrop. |
Icons: 2px-stroke line icons. Use the app's existing icon set if it has one (e.g. Lucide).
## 5. Settings
### 5.1 Settings shell (`S1-settings-sidebar-setting-rows*.png`)
- **Left sidebar (248–264px)** with grouped nav: AGENTS (Personas, Schedules, Scheduling policy), INTEGRATIONS (Channels, Tools & MCP, Plugins),
RUNTIME (Container runtime), divider, History. Optional mono counts (Personas `6`). A section with unsaved edits shows an accent dot.
- **Content column** max ~920–980px. Section header: 24px title, 14px description, amber "Applies after restart" pill when relevant.
- **Groups** inside a section: 13px uppercase eyebrow.
- **Setting row:** 2-column grid `260–280px | 1fr`, gap 32px, 16–20px vertical padding, 1px top border.
Left: label (13px/500) + hint (12px dim). Right: the control.
- Sidebar items are links (route or hash per section).
### 5.2 Save model (`S1` save bar + `S4-settings-review-drawer.png`)
Replace every per-card Save button with one page-level flow:
1. Track edits per field against the loaded config. Edited inputs get an accent border and a "was `old`" hint.
2. When anything is dirty, a **sticky save bar** appears: accent dot · "N unsaved change(s)" · field names · **Discard** · primary
**"Save & restart"** if any dirty field needs a restart, otherwise **"Save"**.
3. The primary button opens the **Review drawer** (480px, right, dim backdrop): "Review N changes", "Saved together as config version N+1",
amber restart callout (optionally with running agent count), changes grouped by section as cards with **Revert** and a mono diff
(red `− old`, green `+ new`), footer Discard all · Save only · Save & restart.
4. Personas keep their own save footer in the editor panel but still feed the page dirty state.
**Backend questions to answer first:** can several sections be saved atomically (or will saves be sequential with partial-failure handling)?
Is "restart required" known per field or per section? Is there a restart action? If not, "Save & restart" becomes "Save" plus a
persistent "Restart pending" banner.
### 5.3 Personas (`S2-settings-personas.png`)
- Left: filter + New; list rows = name + one-line prompt; default persona has an accent-outline **default** pill; selected row = raised + accent bar.
- Right: editor. Header: name + default pill · Duplicate · Delete. Body: Name (mono) and **Default persona** toggle; **System prompt** as a large
mono textarea with "N chars · ~N tokens". Footer: "Saved · version N · History" · Discard · Save persona.
- The old separate "Default" field becomes the per-persona toggle (setting one unsets the others).
- The "try this persona" preview row is optional/future.
- The mockup uses **top tabs** for section navigation; that's the narrow-width fallback. Use the sidebar shell on desktop.
### 5.4 Schedules
Not mocked. Card empty state ("No schedules yet" + "Add schedule"); populated = list rows like Personas.
### 5.5 Scheduling policy (`S1`)
- DISPATCH: *Trigger* segmented Assignee / Label (show the Label input only when Label is chosen); *Ack reaction* mono input.
- STATE LABELS: bordered table `STATE | LABEL | ⌫` with coloured state swatch, mono label input, trash button, "+ Add state".
Today's UI shows display name ("Dead"), key (`dead`) and value (`agent:dead`); the mockup merges name and key.
If the key must stay editable, keep a small mono input in the State column.
- RETRIES & POLLING: *Max retries* stepper; *Poll interval* duration input.
### 5.6 Channels (moved from Work; `S5-settings-channels.png`, today `00-current-channels.png`)
- One card per channel. **Configured** channels are expanded with setting rows; **unconfigured** ones collapse to a single row
(icon · name · one-line purpose · "Not set up" pill · **Set up** button that expands the fields).
- **Telegram** (running): header status pill "Running" (accent). Rows: *Bot token* = secret reference (`env / HEYARCHIE_TELEGRAM_BOT_TOKEN`) + resolved line;
*Allowed users* = chip input of numeric IDs, hint "Everyone else is ignored."
- **Email** (collapsed): expands to *Listen address*, *Relay address*.
- **Webhook** (collapsed): expands to *Deliver to*, *Path*, *Template*, *Signing secret* (secret reference), and *Webhook address*
(today's top-level "Webhook addr" belongs here if it only serves the webhook channel; confirm).
- **CHAT SESSION DEFAULTS · ALL CHANNELS** card with setting rows: *Workspace* (mono path), *Filesystem access* (Unrestricted filesystem toggle in a
**red** bordered row: "On: agents can read and write anywhere this user can."), *Show tool calls* toggle, *Max steps*
("0 = no limit": **confirm the real semantics**), *Rate limit* as "[n] requests per [n] [unit]" ("Off while either value is 0": confirm),
*Models*, *Operator*.
- Footer line: "Version N · N fields set by `actor` N ago · View in History". The audit table itself moves to Settings › History.
- Channel status (running / stopped / error) must come from the backend, not from whether it's configured.
### 5.7 Tools & MCP (`S3-settings-tools-mcp.png`)
- Header action **Add MCP server**. MCP servers card (full width): empty state offering "stdio command" / "HTTP / SSE endpoint"
(only the transports the backend supports); populated rows = name, transport, enabled toggle, edit/delete.
- **MiniMax** card: header "Enabled" toggle; API key as secret reference (`bws / MINIMAX_API_KEY`) + resolved line.
- **Web fetch** card: "Enabled" toggle; *Max download* (bytes as MB); *Timeout* (duration, sec); *Allow private networks* as a bordered
toggle row. Disable the fields when the card is off.
- **Tool output policy** card: *Max result length* (`chars`, hint "About N tokens per tool call", ~4 chars/token), *Spill directory*.
### 5.8 Plugins
Not mocked. Setting rows for *Module dir*, *Plugin dir*, *Secret engine dir*, *Skills dir* (mono, placeholder = effective default if exposed).
### 5.9 Container runtime (left side of `S4`)
*Image* (full width, mono), *Max concurrency* (stepper), *Max uptime* (duration), *Network* (mono),
*Pull policy* (select: If missing / Always / Never → `missing` / `always` / `never`), *Volume TTL* (duration), *Profiles* (mono).
### 5.10 History (new, not mocked)
The Channels audit table generalised to all settings: When · Section · Field (mono) · Old → New (mono, truncated, expandable) ·
Version · Changed by. Filters: section, actor, date. Every "History" link elsewhere deep-links here with the section filter applied.
## 6. App pages
### 6.1 Dashboard (`P1-dashboard.png`, today `00-current-dashboard.png`)
- Header: "Good morning" + a one-line summary that **names the action** ("Nothing is running. 3 tasks need you." with the count in amber). Logs button on the right.
- **Stat strip**: Working now / Needs you (amber value) / Delivered / Tokens used, with the same subtitles as today.
- Two columns: main (1fr) and right rail (380px).
- Main, first: **Needs you** card (count pill). One row per task: state pill (Parked / Awaiting reply) · title (link) ·
mono meta line (`repo #issue · workflow · reason or last message`, truncated) · **Open** (ghost) + the next action
(**Start new run** for parked, **Reply** for awaiting). "All tasks" link in the header.
- Main, second: **Live activity** table: Event (mono, small colour square by kind, `×N` chip when consecutive identical events are grouped) · Task (mono) ·
Detail (truncated) · When. Header: live pill + segmented filter All / Tasks / System.
- Right rail: **Quality gates** (big pass rate, one row per gate with `passed / runs` and a bar: red when failing, accent when passing) and
**Token outlook** (Today, "Next 30 days at this rate", a 7-day mini bar chart, and a note when history is shorter than a week).
Today's full-width purple bar that shows nothing is removed.
### 6.2 Task detail (`P2-task-detail.png`, today `00-current-task-detail.png`)
- Breadcrumb `Tasks / #1`, title, meta row: status pill · workflow (mono) · `repo #issue` link. Actions: **Archive** (ghost), **Start a new run** (primary).
- **Alert banner** for parked/failed tasks: plain-language title ("Parked: couldn't prepare the worktree"), mono error detail, "Jump to log line".
- Two columns: main card with tabs **Log · Changed files (count) · Configuration · Debug**; right rail (320px).
- Log tab: toolbar = level select, stage select, search, Download. Log lines in mono: time · level (ERROR in red) · message with tag chips
(`component=daemon`, `task=1`). Error lines get a faint red background and red left border. Footer "End of attempt N · N lines".
- Right rail: **Attempts** list (dot colour = outcome; selected attempt highlighted; unrecorded attempts shown dimmed) and
**Details** list (Status, Workflow link, Repository, Issue ↗, plus Persona, Tokens, Started if available).
### 6.3 Workflows (`P3-workflows.png`, today `00-current-workflows.png`)
- Header: title + description ("Success rate is merged tasks over all runs"), **Restore shipped** (ghost), **New workflow**.
- Left (420px): list = name + id (mono) · runs · success (`n of m` + bar) · avg tokens (compact: 4.7M, 282k). Selected = raised + accent bar.
- Right: editor card. Header: name + origin pill (e.g. "shipped · edited"; derive from the real origin field) + run count.
Tabs **Definition · Performance · Runs**.
- Definition: *ID* input; *Steps* read-only preview (mono step chips joined by arrows, parsed from YAML);
*YAML* editor with line numbers, mono, light syntax colouring, live "✓ Valid" / error indicator.
Footer: "Version N · History" · Remove (destructive ghost) · Restore this workflow · **Validate & save**.
- Performance (not mocked): today's **Slowest stages** and **Most failures**, filtered to this workflow.
- Runs (not mocked): tasks that used this workflow, linking to Task detail.
- The **Start work** card leaves this page (see 6.4).
### 6.4 New task dialog (`P4-new-task-dialog.png`)
Replaces the Start work card. Opened from the top bar button, ⌘K, and optionally from a workflow ("Start task with this workflow").
- Fields: *Repository* (mono, hint with recent repos), *Workflow* as a 3-column card radiogroup showing each workflow's runs and merge rate,
*Title*, *Instructions* (textarea), and **Identity** tucked into an "Advanced · run as identity" disclosure.
- Footer: "⌘↵ to start" · Cancel · **Start task**. On success, go to the new task's detail page.
### 6.5 Events (`P5-events.png`, today `00-current-events.png`)
- Header with description ("Webhooks come in, get mapped to event types, and bindings turn them into work.") and a **Listening** pill.
- Left-aligned tabs **Inspector · Mappings · Bindings** with count chips. (Reordered to follow the flow; keep the old order if you prefer.)
- Inspector: a 3-step strip **Capture → Map → Bind** with counts; then **Recent captures** (empty state with the copyable endpoint
`/webhooks/capture/<source>` and a Copy button) and **Event types** ("From payload" action, empty state explaining proposals).
## 7. Behaviour and accessibility
- Real `<button>`, `<a href>`, `<input>`, `<select>`, `<label for>`; icon-only buttons get `aria-label`. Toggles use checkbox/`role="switch"`.
Segmented controls and workflow cards are radiogroups with arrow-key support. Dialogs trap focus and close on Esc.
- Visible focus everywhere (accent ring). Touch targets ≥36px (44px on mobile).
- Validate on blur; invalid fields block Save and are listed in the save bar.
- Unsaved-changes guard on route leave.
- Skeleton rows while loading; the top-bar connection pill reflects the socket/API state (Connecting amber, Connected accent, Disconnected red).
- Live tables (activity, captures) insert new rows without layout jump; group consecutive identical events.
- Narrow widths (<960px): settings sidebar → top tabs; two-column layouts stack; drawers and dialogs go full-width.
## 8. Suggested PR sequence
1. **Theme tokens only.** Swap purple for Graphite across the whole app. No layout changes. *Done when no purple remains.*
2. **Shared components** from §4.
3. **Top bar + navigation** (§2): new top-level items, New task button (can open the existing Start work form at first), one connection pill, route moves/redirects.
4. **Settings shell** (sidebar groups, setting rows) and move Channels into it. Sections still save the old way.
5. **Settings sections**: Scheduling policy, Plugins, Container runtime, Tools & MCP, Channels, Personas.
6. **Unified save bar + review drawer + Settings › History** (needs the §5.2 backend decisions). Remove per-card save buttons and pills.
7. **Dashboard.**
8. **Task detail.**
9. **Workflows** (list + editor + Performance tab) and **New task dialog**; remove the Start work card.
10. **Events.**
Each PR: before/after screenshots and a note of anything deferred or unsupported.
## 9. Open questions / out of scope
- Real meaning of `max_steps = 0` and a zero rate limit (the mockup assumes "no limit" / "off").
- Whether "Webhook addr" is webhook-channel-only or global.
- Where the Dashboard's Needs-you reasons and last agent message come from.
- Persona preview, light theme, user-facing accent picker (nice to have).
- Atomic multi-section save and "restart now" (see §5.2).
@@ -0,0 +1,95 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Proposed navigation</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a}
.eyebrow{font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:#8f8c85;font-weight:500}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.node{display:flex;align-items:baseline;gap:10px;font-size:14px;font-weight:500}
.sub{font-size:12px;color:#8f8c85;font-weight:400}
.kid{margin:6px 0 0 18px;padding-left:14px;border-left:1px solid #2e3034;display:flex;flex-direction:column;gap:6px;font-size:13px;color:#a6a39b}
.mono{font-family:'IBM Plex Mono',monospace}
.tbl{width:100%;border-collapse:collapse;font-size:13px}
.tbl th{text-align:left;font-weight:500;font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#8f8c85;padding:10px 14px;border-bottom:1px solid #2a2c30}
.tbl td{padding:10px 14px;border-bottom:1px solid #202225;vertical-align:top;line-height:1.45}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 1120px; box-sizing: border-box; padding: 48px 56px; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; display: flex; flex-direction: column; gap: 28px">
<div>
<h1 style="margin: 0; font-size: 28px; font-weight: 600; letter-spacing: -0.01em">Navigation: today → proposed</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Five top-level places, each with one job. Anything you configure lives in Settings; anything you act on lives where the work is.</p>
</div>
<div style="display: grid; grid-template-columns: 380px minmax(0, 1fr); gap: 24px">
<section class="card" style="padding: 24px; display: flex; flex-direction: column; gap: 16px">
<div class="eyebrow">Today</div>
<div class="node" style="color: #a6a39b">Dashboard</div>
<div><div class="node" style="color: #a6a39b">Work <span class="sub">dropdown</span></div>
<div class="kid"><span>Tasks</span><span>Workflows <span class="sub">editor + start work + stats</span></span><span>Channels <span class="sub">settings + audit</span></span></div></div>
<div><div class="node" style="color: #a6a39b">Events</div>
<div class="kid"><span>Inspector · Bindings · Mappings</span></div></div>
<div><div class="node" style="color: #a6a39b">System <span class="sub">dropdown</span></div>
<div class="kid"><span>Advanced <span class="sub">6 cards, 6 save buttons</span></span></div></div>
<p class="hint" style="margin: 8px 0 0">Dropdown contents are inferred from the screenshots; confirm against the router.</p>
</section>
<section class="card" style="padding: 24px">
<div class="eyebrow" style="margin-bottom: 16px; color: #86b5a0">Proposed</div>
<div style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 24px 32px">
<div><div class="node">Dashboard <span class="sub">what needs me</span></div>
<div class="kid"><span>Needs you queue</span><span>Live activity</span><span>Health: gates, tokens</span></div></div>
<div><div class="node">Tasks <span class="sub">the work</span></div>
<div class="kid"><span>Task list <span class="sub">filter by state</span></span><span>Task detail <span class="sub">log · files · config · debug</span></span><span>Attempts in a side rail</span></div></div>
<div><div class="node">Workflows <span class="sub">how work runs</span></div>
<div class="kid"><span>List with success + cost</span><span>Definition editor</span><span>Performance tab <span class="sub">stages, failures</span></span></div></div>
<div><div class="node">Events <span class="sub">what comes in</span></div>
<div class="kid"><span>Inspector</span><span>Bindings</span><span>Mappings</span></div></div>
<div style="grid-column: span 2"><div class="node">Settings <span class="sub">everything you configure, one save flow</span></div>
<div class="kid" style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 6px 24px">
<span><span style="color: #e8e6e1">Agents</span><br>Personas · Schedules · Scheduling policy</span>
<span><span style="color: #e8e6e1">Integrations</span><br>Channels · Tools &amp; MCP · Plugins</span>
<span><span style="color: #e8e6e1">Runtime</span><br>Container runtime · History</span>
</div></div>
</div>
<div style="margin-top: 24px; padding-top: 16px; border-top: 1px solid #232529; display: flex; gap: 24px; font-size: 13px; color: #a6a39b">
<span><span style="color: #e8e6e1; font-weight: 500">Always in the top bar:</span> New task · ⌘K Jump to · connection status</span>
</div>
</section>
</div>
<section class="card" style="overflow: hidden">
<table class="tbl">
<thead><tr><th style="width: 290px">What</th><th style="width: 280px">Moves to</th><th>Why</th></tr></thead>
<tbody>
<tr><td style="color: #e8e6e1">Start work card (Workflows)</td><td><span style="color: #86b5a0">→</span> New task dialog, from the top bar</td><td style="color: #a6a39b">Starting work is not editing a workflow. One entry point from any page, and from ⌘K.</td></tr>
<tr><td style="color: #e8e6e1">Channels (Work menu)</td><td><span style="color: #86b5a0">→</span> Settings › Integrations › Channels</td><td style="color: #a6a39b">It is configuration. It gets the same setting rows, secret fields and save flow as the rest.</td></tr>
<tr><td style="color: #e8e6e1">Audit table (Channels page)</td><td><span style="color: #86b5a0">→</span> Settings › History</td><td style="color: #a6a39b">One change log for every setting, filterable by section. Replaces six History links.</td></tr>
<tr><td style="color: #e8e6e1">Per workflow table</td><td><span style="color: #86b5a0">→</span> Workflows list columns</td><td style="color: #a6a39b">Runs, success and cost sit next to the workflow you are about to open.</td></tr>
<tr><td style="color: #e8e6e1">Slowest stages · Most failures</td><td><span style="color: #86b5a0">→</span> Workflow › Performance tab</td><td style="color: #a6a39b">Scoped to the selected workflow instead of mixing every workflow in one table.</td></tr>
<tr><td style="color: #e8e6e1">Connecting · Version pills on every card</td><td><span style="color: #86b5a0">→</span> One status in the top bar</td><td style="color: #a6a39b">Connection is global. Version shows once per page, in History.</td></tr>
<tr><td style="color: #e8e6e1">Settings "Managed elsewhere" row</td><td><span style="color: #86b5a0">→</span> Events tabs</td><td style="color: #a6a39b">Captured events, mappings and bindings already live there.</td></tr>
<tr><td style="color: #e8e6e1">Task "Attempt 2 is not recorded" column</td><td><span style="color: #86b5a0">→</span> Attempts list in the task side rail</td><td style="color: #a6a39b">Shows every attempt with its outcome; the empty column goes away.</td></tr>
<tr><td style="color: #e8e6e1">Dashboard stat cards and health</td><td><span style="color: #86b5a0">→</span> Stat strip + right rail</td><td style="color: #a6a39b">"Needs you" becomes the first thing on the page, with actions inline.</td></tr>
</tbody>
</table>
</section>
</div>
</body>
</html>
@@ -0,0 +1,187 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Dashboard</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
.card-h{display:flex;align-items:center;gap:12px;padding:16px 20px;border-bottom:1px solid #232529}
.card-t{font-size:15px;font-weight:500}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.eyebrow{font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:#8f8c85;font-weight:500}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
.warn{color:#d9a45b;border-color:rgba(217,164,91,.3);background:rgba(217,164,91,.08)}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.nav a.on{color:#e8e6e1;background:#1e2023}
.tbl{width:100%;border-collapse:collapse;font-size:13px}
.tbl th{text-align:left;font-weight:500;font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#8f8c85;padding:10px 20px;border-bottom:1px solid #2a2c30}
.tbl td{padding:10px 20px;border-bottom:1px solid #202225;vertical-align:middle}
.chip{font:11px 'IBM Plex Mono',monospace;color:#8f8c85;background:#1e2023;border-radius:4px;padding:1px 6px;margin-left:6px}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden; position: relative">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#" class="on">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
<div style="flex-grow: 1"></div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
</header>
<main style="flex-grow: 1; padding: 32px 48px; display: flex; flex-direction: column; gap: 24px; min-height: 0">
<div style="display: flex; align-items: flex-end; gap: 16px">
<div style="flex-grow: 1">
<h1 style="margin: 0; font-size: 28px; font-weight: 600; letter-spacing: -0.01em">Good morning</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Nothing is running. <span style="color: #d9a45b">3 tasks need you.</span></p>
</div>
<button class="btn"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 6h16M4 12h10M4 18h13"></path></svg>Logs</button>
</div>
<section class="card" style="flex-direction: row">
<div style="flex: 1 1 0; padding: 18px 22px; border-right: 1px solid #232529">
<div class="hint">Working now</div>
<div style="font-size: 30px; font-weight: 600; margin-top: 6px; color: #e8e6e1">0</div>
<div class="hint" style="margin-top: 2px">0 waiting to start</div>
</div>
<div style="flex: 1 1 0; padding: 18px 22px; border-right: 1px solid #232529">
<div class="hint">Needs you</div>
<div style="font-size: 30px; font-weight: 600; margin-top: 6px; color: #d9a45b">3</div>
<div class="hint" style="margin-top: 2px">Parked or awaiting a reply</div>
</div>
<div style="flex: 1 1 0; padding: 18px 22px; border-right: 1px solid #232529">
<div class="hint">Delivered</div>
<div style="font-size: 30px; font-weight: 600; margin-top: 6px; color: #e8e6e1">1</div>
<div class="hint" style="margin-top: 2px">25% of all tasks</div>
</div>
<div style="flex: 1 1 0; padding: 18px 22px; border-right: 1px solid #232529">
<div class="hint">Tokens used</div>
<div style="font-size: 30px; font-weight: 600; margin-top: 6px; color: #e8e6e1">14.5M</div>
<div class="hint" style="margin-top: 2px">Across 1 day</div>
</div>
</section>
<div style="display: grid; grid-template-columns: minmax(0, 1fr) 380px; gap: 24px; min-height: 0; flex-grow: 1">
<div style="display: flex; flex-direction: column; gap: 24px; min-width: 0">
<section class="card">
<div class="card-h"><span class="card-t">Needs you</span><span class="pill warn">3</span><div style="flex-grow: 1"></div><a href="#" class="hint" style="text-decoration: underline">All tasks</a></div>
<div style="display: grid; grid-template-columns: 120px minmax(0, 1fr) auto; gap: 16px; align-items: center; padding: 14px 20px; border-bottom: 1px solid #202225">
<span class="pill warn" style="justify-self: start">Parked</span>
<div style="min-width: 0">
<a href="#" style="font-size: 14px; font-weight: 500">changes_captured key-set validation is top-level only</a>
<div class="mono" style="font-size: 12px; color: #8f8c85; margin-top: 3px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">archie-core #868 · tdd · worktree prepare failed: fetch origin: http transport…</div>
</div>
<div style="display: flex; gap: 8px"><button class="btn btn-sm btn-ghost">Open</button><button class="btn btn-sm">Start new run</button></div>
</div>
<div style="display: grid; grid-template-columns: 120px minmax(0, 1fr) auto; gap: 16px; align-items: center; padding: 14px 20px; border-bottom: 1px solid #202225">
<span class="pill warn" style="justify-self: start">Awaiting reply</span>
<div style="min-width: 0">
<a href="#" style="font-size: 14px; font-weight: 500">[Task title]</a>
<div class="mono" style="font-size: 12px; color: #8f8c85; margin-top: 3px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">[repo #issue] · [workflow] · [last agent message]</div>
</div>
<div style="display: flex; gap: 8px"><button class="btn btn-sm btn-ghost">Open</button><button class="btn btn-sm">Reply</button></div>
</div>
<div style="display: grid; grid-template-columns: 120px minmax(0, 1fr) auto; gap: 16px; align-items: center; padding: 14px 20px; border-bottom: 1px solid #202225">
<span class="pill warn" style="justify-self: start">Awaiting reply</span>
<div style="min-width: 0">
<a href="#" style="font-size: 14px; font-weight: 500">[Task title]</a>
<div class="mono" style="font-size: 12px; color: #8f8c85; margin-top: 3px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">[repo #issue] · [workflow] · [last agent message]</div>
</div>
<div style="display: flex; gap: 8px"><button class="btn btn-sm btn-ghost">Open</button><button class="btn btn-sm">Reply</button></div>
</div>
</section>
<section class="card" style="flex-grow: 1; overflow: hidden">
<div class="card-h"><span class="card-t">Live activity</span><span class="pill" style="color: #86b5a0; border-color: #86b5a0"><span class="dot" style="background: #86b5a0"></span>live</span><div style="flex-grow: 1"></div>
<div role="radiogroup" aria-label="Filter activity" style="display: inline-flex; padding: 2px; border: 1px solid #2e3034; border-radius: 7px"><button style="height: 26px; padding: 0 10px; border: 0; border-radius: 5px; background: #26282c; color: #e8e6e1; font: 500 12px 'IBM Plex Sans', sans-serif">All</button><button style="height: 26px; padding: 0 10px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 12px 'IBM Plex Sans', sans-serif">Tasks</button><button style="height: 26px; padding: 0 10px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 12px 'IBM Plex Sans', sans-serif">System</button></div>
</div>
<table class="tbl">
<thead><tr><th>Event</th><th style="width: 70px">Task</th><th>Detail</th><th style="width: 110px">When</th></tr></thead>
<tbody>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #6f6c66"></span>curator_run</td><td class="mono" style="font-size: 12px; color: #a6a39b">—</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">session-memory</td><td class="hint">19 mins ago</td></tr>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #8aa4c2"></span>task_archive_requested</td><td class="mono" style="font-size: 12px; color: #a6a39b">#5</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">archive requested with no recorded actor</td><td class="hint">1 hr ago</td></tr>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #d9776b"></span>task_abandoned</td><td class="mono" style="font-size: 12px; color: #a6a39b">#5</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">abandoned with no recorded actor</td><td class="hint">1 hr ago</td></tr>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #6f6c66"></span>curator_run<span class="chip">×6</span></td><td class="mono" style="font-size: 12px; color: #a6a39b">—</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">session-memory</td><td class="hint">1 hr ago</td></tr>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #8aa4c2"></span>stage_start<span class="chip">×4</span></td><td class="mono" style="font-size: 12px; color: #a6a39b">#5</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis"></td><td class="hint">1 hr ago</td></tr>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #8aa4c2"></span>stage_start<span class="chip">×5</span></td><td class="mono" style="font-size: 12px; color: #a6a39b">#4</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis"></td><td class="hint">7 hrs ago</td></tr>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #86b5a0"></span>agent_finish</td><td class="mono" style="font-size: 12px; color: #a6a39b">#4</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">Problem surface for samcharles93/archie-core issue 836 ("Updater cannot detect o…</td><td class="hint">7 hrs ago</td></tr>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #86b5a0"></span>agent_finish</td><td class="mono" style="font-size: 12px; color: #a6a39b">#4</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">Root cause</td><td class="hint">7 hrs ago</td></tr>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #8aa4c2"></span>stage_start<span class="chip">×6</span></td><td class="mono" style="font-size: 12px; color: #a6a39b">#4</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis"></td><td class="hint">8 hrs ago</td></tr>
</tbody>
</table>
</section>
</div>
<div style="display: flex; flex-direction: column; gap: 24px">
<section class="card">
<div class="card-h"><span class="card-t">Quality gates</span><div style="flex-grow: 1"></div><span class="hint">last 4 runs</span></div>
<div style="padding: 20px; display: flex; flex-direction: column; gap: 16px">
<div style="display: flex; align-items: baseline; gap: 10px"><span style="font-size: 30px; font-weight: 600">25%</span><span class="hint">pass rate</span></div>
<div>
<div style="display: flex; font-size: 13px; margin-bottom: 6px"><span class="mono">tdd</span><span style="margin-left: auto; color: #a6a39b" class="mono">0 / 3</span></div>
<div style="height: 6px; border-radius: 3px; background: #26282c"><div style="height: 6px; border-radius: 3px; width: 2%; background: #d9776b"></div></div>
</div>
<div>
<div style="display: flex; font-size: 13px; margin-bottom: 6px"><span class="mono">triage</span><span style="margin-left: auto; color: #a6a39b" class="mono">1 / 1</span></div>
<div style="height: 6px; border-radius: 3px; background: #26282c"><div style="height: 6px; border-radius: 3px; width: 100%; background: #86b5a0"></div></div>
</div>
</div>
</section>
<section class="card">
<div class="card-h"><span class="card-t">Token outlook</span></div>
<div style="padding: 20px; display: flex; flex-direction: column; gap: 14px">
<div style="display: flex; gap: 24px">
<div><div class="hint">Today</div><div style="font-size: 22px; font-weight: 600; margin-top: 2px">14.5M</div></div>
<div><div class="hint">Next 30 days at this rate</div><div style="font-size: 22px; font-weight: 600; margin-top: 2px">≈ 434M</div></div>
</div>
<div aria-label="Tokens per day, last 7 days" style="display: flex; align-items: flex-end; gap: 6px; height: 64px">
<div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">M</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">T</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">W</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">T</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 48px; border-radius: 3px; background: #86b5a0"></div><span class="mono" style="font-size: 10px; color: #8f8c85">F</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">S</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">S</span></div>
</div>
<div class="hint">Only 1 day of history. The projection steadies after a week of runs.</div>
</div>
</section>
</div>
</div>
</main>
<button aria-label="Chat with Archie" style="position: absolute; right: 24px; bottom: 24px; width: 48px; height: 48px; border-radius: 50%; border: 1px solid #34373c; background: #1e2023; color: #86b5a0; display: flex; align-items: center; justify-content: center; box-shadow: 0 8px 24px rgba(0,0,0,.4); cursor: pointer"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a8 8 0 0 1-11.6 7.1L4 20l1-4.6A8 8 0 1 1 21 12Z"></path></svg></button>
</div>
</body>
</html>
@@ -0,0 +1,127 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Task detail</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
.card-h{display:flex;align-items:center;gap:12px;padding:14px 20px;border-bottom:1px solid #232529}
.card-t{font-size:14px;font-weight:500}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
.warn{color:#d9a45b;border-color:rgba(217,164,91,.3);background:rgba(217,164,91,.08)}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.nav a.on{color:#e8e6e1;background:#1e2023}
.tab{height:44px;display:flex;align-items:center;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
.sel{height:32px;box-sizing:border-box;padding:0 10px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:13px 'IBM Plex Sans',sans-serif}
.kv{display:grid;grid-template-columns:96px minmax(0,1fr);gap:10px;font-size:13px;padding:8px 0;border-bottom:1px solid #202225}
.kv dt{color:#8f8c85}.kv dd{margin:0}
.tag{font:11px 'IBM Plex Mono',monospace;color:#a6a39b;background:#1e2023;border-radius:4px;padding:1px 6px}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 1000px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#" class="on">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
<div style="flex-grow: 1"></div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
</header>
<main style="flex-grow: 1; padding: 24px 48px 32px; display: flex; flex-direction: column; gap: 20px; min-height: 0">
<div>
<div class="hint"><a href="#" style="color: #a6a39b">Tasks</a> / <span class="mono">#1</span></div>
<div style="display: flex; align-items: flex-start; gap: 16px; margin-top: 8px">
<div style="flex-grow: 1; min-width: 0">
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">changes_captured key-set validation is top-level only</h1>
<div style="display: flex; align-items: center; gap: 12px; margin-top: 8px; font-size: 13px; color: #a6a39b">
<span class="pill warn"><span class="dot" style="background: #d9a45b"></span>Parked</span>
<span class="mono">tdd</span><span style="color: #4a4c50">·</span>
<a href="#" class="mono" style="color: #a6a39b; text-decoration: underline">samcharles93/archie-core #868</a>
</div>
</div>
<button class="btn btn-ghost">Archive</button>
<button class="btn btn-primary"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a9 9 0 1 1-3-6.7L21 8"></path><path d="M21 3v5h-5"></path></svg>Start a new run</button>
</div>
</div>
<div role="alert" style="display: flex; gap: 12px; padding: 14px 16px; border-radius: 8px; background: rgba(217,164,91,0.08); border: 1px solid rgba(217,164,91,0.25)">
<svg style="flex-shrink: 0; margin-top: 2px" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#d9a45b" stroke-width="2"><path d="M12 3 2 20h20L12 3Z"></path><path d="M12 10v4M12 17h.01"></path></svg>
<div style="min-width: 0; flex-grow: 1">
<div style="font-size: 14px; font-weight: 500; color: #e3c08f">Parked: couldn’t prepare the worktree</div>
<div class="mono" style="font-size: 12px; color: #a6a39b; margin-top: 4px; line-height: 1.6; word-break: break-all">fetch origin: http transport: Get "https://github.com/samcharles93/archie-core.git/info/refs?service=git-upload-pack": terminated signal received</div>
</div>
<button class="btn btn-sm" style="align-self: flex-start">Jump to log line</button>
</div>
<div style="display: grid; grid-template-columns: minmax(0, 1fr) 320px; gap: 24px; flex-grow: 1; min-height: 0">
<section class="card" style="overflow: hidden">
<nav style="display: flex; gap: 28px; padding: 0 20px; border-bottom: 1px solid #232529">
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: #86b5a0">Log</a>
<a class="tab" href="#">Changed files <span class="hint" style="margin-left: 6px">0</span></a>
<a class="tab" href="#">Configuration</a>
<a class="tab" href="#">Debug</a>
</nav>
<div style="display: flex; align-items: center; gap: 8px; padding: 12px 20px; border-bottom: 1px solid #232529">
<select aria-label="Level" class="sel"><option>All levels</option></select>
<select aria-label="Stage" class="sel"><option>All stages</option></select>
<label style="display: flex; align-items: center; gap: 8px; height: 32px; width: 260px; padding: 0 10px; box-sizing: border-box; border: 1px solid #2e3034; border-radius: 6px; color: #8f8c85"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Search log" placeholder="Search log" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: 13px 'IBM Plex Sans', sans-serif; width: 100%"></label>
<div style="flex-grow: 1"></div>
<button class="btn btn-sm btn-ghost"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 4v11M7 10l5 5 5-5M5 20h14"></path></svg>Download</button>
</div>
<div class="mono" style="font-size: 12px; line-height: 1.7; flex-grow: 1; background: #121314">
<div style="display: grid; grid-template-columns: 72px 56px minmax(0, 1fr); gap: 12px; padding: 10px 20px; background: rgba(217,119,107,0.06); border-left: 2px solid #d9776b">
<span style="color: #8f8c85">08:38:49</span>
<span style="color: #e0a39a">ERROR</span>
<div style="min-width: 0">
<div style="word-break: break-all">task parked: worktree prepare failed: fetch origin: http transport: Get "https://github.com/samcharles93/archie-core.git/info/refs?service=git-upload-pack": terminated signal received</div>
<div style="display: flex; gap: 6px; margin-top: 6px"><span class="tag">component=daemon</span><span class="tag">task=1</span></div>
</div>
</div>
<div style="padding: 16px 20px; color: #8f8c85; font-family: 'IBM Plex Sans', sans-serif; font-size: 12px">End of attempt 1 · 1 line</div>
</div>
</section>
<aside style="display: flex; flex-direction: column; gap: 20px">
<section class="card">
<div class="card-h"><span class="card-t">Attempts</span></div>
<div style="padding: 8px 12px">
<a href="#" style="display: flex; align-items: center; gap: 10px; padding: 10px 8px; border-radius: 6px; background: #1e2023; box-shadow: inset 2px 0 0 #86b5a0">
<span class="dot" style="background: #d9a45b"></span><span style="font-size: 13px; flex-grow: 1">Attempt 1</span><span class="hint">parked · 08:38</span></a>
<div style="display: flex; align-items: center; gap: 10px; padding: 10px 8px; color: #8f8c85">
<span class="dot" style="background: transparent; border: 1px dashed #4a4c50; box-sizing: border-box"></span><span style="font-size: 13px; flex-grow: 1">Attempt 2</span><span class="hint">not recorded</span></div>
</div>
</section>
<section class="card">
<div class="card-h"><span class="card-t">Details</span></div>
<dl style="margin: 0; padding: 4px 20px 12px">
<div class="kv"><dt>Status</dt><dd style="color: #d9a45b">Parked</dd></div>
<div class="kv"><dt>Workflow</dt><dd><a href="#" class="mono" style="text-decoration: underline">tdd</a></dd></div>
<div class="kv"><dt>Repository</dt><dd class="mono" style="font-size: 12px">samcharles93/archie-core</dd></div>
<div class="kv"><dt>Issue</dt><dd><a href="#" style="text-decoration: underline">#868</a> ↗</dd></div>
<div class="kv"><dt>Persona</dt><dd class="mono" style="font-size: 12px">[persona]</dd></div>
<div class="kv"><dt>Tokens</dt><dd class="mono" style="font-size: 12px">[tokens]</dd></div>
<div class="kv" style="border: 0"><dt>Started</dt><dd>[date · time]</dd></div>
</dl>
</section>
</aside>
</div>
</main>
</div>
</body>
</html>
@@ -0,0 +1,152 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Workflows</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.lbl{font-size:13px;font-weight:500}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.nav a.on{color:#e8e6e1;background:#1e2023}
.tab{height:44px;display:flex;align-items:center;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
.step{font:12px 'IBM Plex Mono',monospace;padding:6px 10px;border:1px solid #2e3034;border-radius:6px;background:#121314;white-space:nowrap}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#" class="on">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
<div style="flex-grow: 1"></div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
</header>
<main style="flex-grow: 1; padding: 32px 48px; display: flex; flex-direction: column; gap: 24px; min-height: 0">
<div style="display: flex; align-items: flex-end; gap: 12px">
<div style="flex-grow: 1">
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Workflows</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">The step sequences agents follow. Success rate is merged tasks over all runs.</p>
</div>
<button class="btn btn-ghost"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 12a9 9 0 1 0 3-6.7L3 8"></path><path d="M3 3v5h5"></path></svg>Restore shipped</button>
<button class="btn"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New workflow</button>
</div>
<div style="display: grid; grid-template-columns: 420px minmax(0, 1fr); gap: 24px; flex-grow: 1; min-height: 0">
<section class="card" style="overflow: hidden">
<div style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; padding: 10px 16px; font-size: 11px; letter-spacing: .06em; text-transform: uppercase; color: #8f8c85; border-bottom: 1px solid #2a2c30"><span>Workflow</span><span>Runs</span><span>Success</span><span style="text-align: right">Avg tok</span></div>
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: #1e2023; box-shadow: inset 2px 0 0 #86b5a0">
<span><span style="font-size: 14px; font-weight: 500; display: block">Bootstrap</span><span class="mono" style="font-size: 11px; color: #8f8c85">bootstrap</span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b">0</span>
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">—</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 0%; background: #86b5a0"></span></span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">—</span>
</a>
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: transparent; box-shadow: none">
<span><span style="font-size: 14px; font-weight: 500; display: block">Feasibility check</span><span class="mono" style="font-size: 11px; color: #8f8c85">feasibility</span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b">0</span>
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">—</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 0%; background: #86b5a0"></span></span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">—</span>
</a>
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: transparent; box-shadow: none">
<span><span style="font-size: 14px; font-weight: 500; display: block">Implement</span><span class="mono" style="font-size: 11px; color: #8f8c85">implement</span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b">0</span>
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">—</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 0%; background: #86b5a0"></span></span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">—</span>
</a>
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: transparent; box-shadow: none">
<span><span style="font-size: 14px; font-weight: 500; display: block">Remediate</span><span class="mono" style="font-size: 11px; color: #8f8c85">remediate</span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b">0</span>
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">—</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 0%; background: #86b5a0"></span></span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">—</span>
</a>
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: transparent; box-shadow: none">
<span><span style="font-size: 14px; font-weight: 500; display: block">TDD</span><span class="mono" style="font-size: 11px; color: #8f8c85">tdd</span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b">3</span>
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">0 of 3</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 2%; background: #d9776b"></span></span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">4.7M</span>
</a>
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: transparent; box-shadow: none">
<span><span style="font-size: 14px; font-weight: 500; display: block">Triage</span><span class="mono" style="font-size: 11px; color: #8f8c85">triage</span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b">1</span>
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">1 of 1</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 100%; background: #86b5a0"></span></span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">282k</span>
</a>
</section>
<section class="card" style="overflow: hidden">
<div style="display: flex; align-items: center; gap: 12px; padding: 18px 24px 0">
<h2 style="margin: 0; font-size: 18px; font-weight: 600">Bootstrap</h2>
<span class="pill">shipped · edited</span>
<div style="flex-grow: 1"></div>
<span class="hint">0 runs yet</span>
</div>
<nav style="display: flex; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529">
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: #86b5a0">Definition</a>
<a class="tab" href="#">Performance</a>
<a class="tab" href="#">Runs</a>
</nav>
<div style="padding: 20px 24px; display: flex; flex-direction: column; gap: 18px; flex-grow: 1; min-height: 0">
<div style="display: grid; grid-template-columns: 280px minmax(0, 1fr); gap: 24px">
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="wid">ID</label><input id="wid" class="inp" value="bootstrap"></div>
<div style="display: flex; flex-direction: column; gap: 6px"><span class="lbl">Steps</span>
<div style="display: flex; align-items: center; gap: 6px; height: 36px; flex-wrap: nowrap; overflow: hidden">
<span class="step">prepare</span><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#4a4c50" stroke-width="2"><path d="M5 12h14M13 6l6 6-6 6"></path></svg><span class="step">apply</span><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#4a4c50" stroke-width="2"><path d="M5 12h14M13 6l6 6-6 6"></path></svg><span class="step">commit-push</span><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#4a4c50" stroke-width="2"><path d="M5 12h14M13 6l6 6-6 6"></path></svg><span class="step">diff-cap</span><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#4a4c50" stroke-width="2"><path d="M5 12h14M13 6l6 6-6 6"></path></svg><span class="step">open-pr</span>
</div></div>
</div>
<div style="display: flex; flex-direction: column; gap: 6px; flex-grow: 1; min-height: 0">
<div style="display: flex; align-items: baseline"><span class="lbl">YAML</span><span class="hint" style="margin-left: auto; color: #86b5a0">✓ Valid</span></div>
<div class="mono" style="flex-grow: 1; display: grid; grid-template-columns: 44px minmax(0, 1fr); border: 1px solid #2e3034; border-radius: 8px; background: #121314; font-size: 13px; line-height: 1.75; overflow: hidden">
<div style="padding: 14px 0; text-align: right; padding-right: 12px; color: #4f5156; border-right: 1px solid #232529; background: #141517; white-space: pre-line">1
2
3
4
5
6
7</div>
<div style="padding: 14px 16px; white-space: pre"><span style="color: #a6a39b">id:</span> bootstrap
<span style="color: #a6a39b">steps:</span>
- <span style="color: #a6a39b">type:</span> <span style="color: #86b5a0">bootstrap.prepare</span>
- <span style="color: #a6a39b">type:</span> <span style="color: #86b5a0">bootstrap.apply</span>
- <span style="color: #a6a39b">type:</span> <span style="color: #86b5a0">bootstrap.commit-push</span>
- <span style="color: #a6a39b">type:</span> <span style="color: #86b5a0">bootstrap.diff-cap</span>
- <span style="color: #a6a39b">type:</span> <span style="color: #86b5a0">bootstrap.open-pr</span></div>
</div>
</div>
</div>
<div style="display: flex; align-items: center; gap: 10px; padding: 14px 24px; border-top: 1px solid #2a2c30; background: #17181a">
<span class="hint">Version 1 · <a href="#" style="color: #a6a39b; text-decoration: underline">History</a></span>
<div style="flex-grow: 1"></div>
<button class="btn btn-ghost" style="color: #d9776b">Remove</button>
<button class="btn">Restore this workflow</button>
<button class="btn btn-primary">Validate &amp; save</button>
</div>
</section>
</div>
</main>
</div>
</body>
</html>
@@ -0,0 +1,77 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>New task dialog</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.lbl{font-size:13px;font-weight:500}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.inp{box-sizing:border-box;height:38px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
.field{display:flex;flex-direction:column;gap:6px}
.opt{display:flex;flex-direction:column;gap:2px;padding:10px 12px;border:1px solid #2e3034;border-radius:8px;cursor:pointer}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 900px; box-sizing: border-box; position: relative; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
<div style="flex-grow: 1"></div>
<button class="btn btn-sm" style="border-color: #86b5a0"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
</header>
<div style="padding: 32px 48px"><div style="font-size: 28px; font-weight: 600; color: #3a3c40">Good morning</div></div>
<div style="position: absolute; inset: 0; background: rgba(8,9,10,0.6)"></div>
<section role="dialog" aria-modal="true" aria-labelledby="nt-title" style="position: absolute; left: 50%; top: 88px; transform: translateX(-50%); width: 640px; box-sizing: border-box; background: #17181a; border: 1px solid #2a2c30; border-radius: 12px; box-shadow: 0 24px 64px rgba(0,0,0,0.5); display: flex; flex-direction: column">
<div style="display: flex; align-items: flex-start; padding: 22px 24px 18px; border-bottom: 1px solid #232529">
<div style="flex-grow: 1"><h2 id="nt-title" style="margin: 0; font-size: 18px; font-weight: 600">New task</h2><div class="hint" style="margin-top: 2px">Goes into Archie’s normal task queue.</div></div>
<button aria-label="Close" style="width: 32px; height: 32px; border: 0; background: transparent; color: #8f8c85; cursor: pointer"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 6l12 12M18 6 6 18"></path></svg></button>
</div>
<div style="padding: 20px 24px; display: flex; flex-direction: column; gap: 18px">
<div class="field"><label class="lbl" for="repo">Repository</label><input id="repo" class="inp" value="samcharles93/archie-core"><span class="hint">owner/repository · recent: archie-core</span></div>
<div class="field"><span class="lbl">Workflow</span>
<div role="radiogroup" aria-label="Workflow" style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 8px">
<label class="opt" style="border-color: #86b5a0; background: #1e2023"><span style="font-size: 13px; font-weight: 500">TDD</span><span class="hint">3 runs · 0% merged</span></label>
<label class="opt" style="border-color: #2e3034; background: transparent"><span style="font-size: 13px; font-weight: 500">Triage</span><span class="hint">1 run · 100% merged</span></label>
<label class="opt" style="border-color: #2e3034; background: transparent"><span style="font-size: 13px; font-weight: 500">Implement</span><span class="hint">no runs yet</span></label>
<label class="opt" style="border-color: #2e3034; background: transparent"><span style="font-size: 13px; font-weight: 500">Remediate</span><span class="hint">no runs yet</span></label>
<label class="opt" style="border-color: #2e3034; background: transparent"><span style="font-size: 13px; font-weight: 500">Feasibility check</span><span class="hint">no runs yet</span></label>
<label class="opt" style="border-color: #2e3034; background: transparent"><span style="font-size: 13px; font-weight: 500">Bootstrap</span><span class="hint">no runs yet</span></label>
</div></div>
<div class="field"><label class="lbl" for="ttl">Title</label><input id="ttl" class="inp" placeholder="What should Archie do?" style="font-family: 'IBM Plex Sans', sans-serif"></div>
<div class="field"><label class="lbl" for="ins">Instructions</label><textarea id="ins" placeholder="Context, acceptance criteria, files to look at…" style="min-height: 120px; box-sizing: border-box; padding: 12px; background: #121314; border: 1px solid #2e3034; border-radius: 6px; color: #e8e6e1; font: 13px/1.6 'IBM Plex Sans', sans-serif; resize: vertical; outline: none"></textarea></div>
<details style="font-size: 13px; color: #a6a39b"><summary style="cursor: pointer">Advanced · run as identity</summary></details>
</div>
<div style="display: flex; align-items: center; gap: 10px; padding: 14px 24px; border-top: 1px solid #232529">
<span class="hint"><span class="mono" style="padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘↵</span> to start</span>
<div style="flex-grow: 1"></div>
<button class="btn btn-ghost">Cancel</button>
<button class="btn btn-primary">Start task</button>
</div>
</section>
</div>
</body>
</html>
@@ -0,0 +1,102 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Events</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
.card-h{display:flex;align-items:center;gap:12px;padding:16px 20px;border-bottom:1px solid #232529}
.card-t{font-size:15px;font-weight:500}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.nav a.on{color:#e8e6e1;background:#1e2023}
.tab{height:44px;display:flex;align-items:center;gap:8px;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
.count{font:11px 'IBM Plex Mono',monospace;color:#8f8c85;background:#1e2023;border-radius:4px;padding:0 6px}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 900px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#" class="on">Events</a><a href="#">Settings</a></nav>
<div style="flex-grow: 1"></div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
</header>
<main style="flex-grow: 1; padding: 32px 48px; display: flex; flex-direction: column; gap: 24px">
<div>
<div style="display: flex; align-items: flex-end; gap: 12px">
<div style="flex-grow: 1"><h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Events</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Webhooks come in, get mapped to event types, and bindings turn them into work.</p></div>
<span class="pill" style="color: #86b5a0; border-color: #86b5a0"><span class="dot" style="background: #86b5a0"></span>Listening</span>
</div>
<nav style="display: flex; gap: 28px; margin-top: 16px; border-bottom: 1px solid #232529">
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: #86b5a0">Inspector</a>
<a class="tab" href="#">Mappings <span class="count">0</span></a>
<a class="tab" href="#">Bindings <span class="count">0</span></a>
</nav>
</div>
<section class="card" style="flex-direction: row">
<div style="flex: 1 1 0; display: flex; align-items: center; gap: 14px; padding: 18px 22px; border-right: 1px solid #232529">
<span class="mono" style="width: 28px; height: 28px; border-radius: 50%; border: 1px solid #34373c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b; flex-shrink: 0">1</span>
<div style="flex-grow: 1"><div style="font-size: 14px; font-weight: 500">Capture</div><div class="hint">Webhooks received</div></div>
<span class="mono" style="font-size: 20px; color: #8f8c85">0</span>
</div>
<div style="flex: 1 1 0; display: flex; align-items: center; gap: 14px; padding: 18px 22px; border-right: 1px solid #232529">
<span class="mono" style="width: 28px; height: 28px; border-radius: 50%; border: 1px solid #34373c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b; flex-shrink: 0">2</span>
<div style="flex-grow: 1"><div style="font-size: 14px; font-weight: 500">Map</div><div class="hint">Payloads → event types</div></div>
<span class="mono" style="font-size: 20px; color: #8f8c85">0</span>
</div>
<div style="flex: 1 1 0; display: flex; align-items: center; gap: 14px; padding: 18px 22px; border-right: 1px solid #232529">
<span class="mono" style="width: 28px; height: 28px; border-radius: 50%; border: 1px solid #34373c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b; flex-shrink: 0">3</span>
<div style="flex-grow: 1"><div style="font-size: 14px; font-weight: 500">Bind</div><div class="hint">Event types → work</div></div>
<span class="mono" style="font-size: 20px; color: #8f8c85">0</span>
</div>
</section>
<div style="display: grid; grid-template-columns: minmax(0, 3fr) minmax(0, 2fr); gap: 24px">
<section class="card">
<div class="card-h"><div style="flex-grow: 1"><div class="card-t">Recent captures</div><div class="hint">Headers and payloads are redacted before they’re stored.</div></div></div>
<div style="padding: 40px 32px; display: flex; flex-direction: column; align-items: center; gap: 12px; text-align: center">
<div style="width: 40px; height: 40px; border-radius: 10px; background: #1e2023; display: flex; align-items: center; justify-content: center"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><path d="M22 12h-6l-2 3h-4l-2-3H2"></path><path d="M5.5 5h13L22 12v6a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2v-6Z"></path></svg></div>
<div style="font-size: 14px; font-weight: 500">No captures yet</div>
<div class="hint">Point a webhook at this endpoint and it shows up here live.</div>
<div style="display: flex; align-items: center; gap: 8px; margin-top: 6px; padding: 4px 4px 4px 14px; border: 1px solid #2e3034; border-radius: 8px; background: #121314">
<span class="mono" style="font-size: 13px">/webhooks/capture/<span style="color: #86b5a0">&lt;source&gt;</span></span>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="8" y="8" width="12" height="12" rx="2"></rect><path d="M16 8V5a1 1 0 0 0-1-1H5a1 1 0 0 0-1 1v10a1 1 0 0 0 1 1h3"></path></svg>Copy</button>
</div>
</div>
</section>
<section class="card">
<div class="card-h"><div style="flex-grow: 1"><div class="card-t">Event types</div><div class="hint">Named shapes that mappings produce.</div></div>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M14 3H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9l-6-6Z"></path><path d="M12 12v6M9 15h6"></path></svg>From payload</button></div>
<div style="padding: 40px 32px; display: flex; flex-direction: column; align-items: center; gap: 8px; text-align: center">
<div style="font-size: 14px; font-weight: 500">No event types or proposals</div>
<div class="hint">Paste a sample payload and Archie proposes a type for it. Proposals from real captures appear here too.</div>
</div>
</section>
</div>
</main>
</div>
</body>
</html>
@@ -0,0 +1,176 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Settings – sidebar layout</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none}
.inp:focus{border-color:var(--accent)}
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.icon-btn{width:36px;height:36px;display:flex;align-items:center;justify-content:center;border-radius:6px;border:1px solid transparent;background:transparent;color:#8f8c85;cursor:pointer}
.icon-btn:hover{background:#1e2023;color:#e8e6e1}
.nav-item{display:flex;align-items:center;gap:10px;height:36px;padding:0 12px;border-radius:6px;color:#a6a39b;font-size:13px}
.row{display:grid;grid-template-columns:280px minmax(0,1fr);gap:32px;padding:20px 0;border-top:1px solid #232529}
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
.hint{font-size:12px;color:#8f8c85;margin-top:4px;line-height:1.5}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 1040px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; position: relative; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
Archie
</div>
<nav style="display: flex; gap: 4px; font-size: 13px">
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Tasks</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Workflows</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">Settings</a>
</nav>
<div style="flex-grow: 1"></div>
<div style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b; padding: 6px 10px; border: 1px solid #2a2c30; border-radius: 999px">
<span style="width: 7px; height: 7px; border-radius: 50%; background: #d9a45b"></span>
Connecting to archie-core…
</div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 240px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px">
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg>
<input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%">
<span style="font-family: 'IBM Plex Mono', monospace; font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span>
</label>
</header>
<div style="display: flex; flex-grow: 1; min-height: 0">
<aside style="width: 264px; flex-shrink: 0; box-sizing: border-box; padding: 24px 16px; border-right: 1px solid #232529; display: flex; flex-direction: column; gap: 2px">
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 0 12px 8px">Agents</div>
<a class="nav-item" href="#">Personas<span style="margin-left: auto; font-family: 'IBM Plex Mono', monospace; font-size: 11px; color: #8f8c85">6</span></a>
<a class="nav-item" href="#">Schedules<span style="margin-left: auto; font-family: 'IBM Plex Mono', monospace; font-size: 11px; color: #8f8c85">0</span></a>
<a class="nav-item" href="#" style="background: #1e2023; color: #e8e6e1; box-shadow: inset 2px 0 0 #86b5a0">Scheduling policy<span style="margin-left: auto; width: 6px; height: 6px; border-radius: 50%; background: #86b5a0" title="Unsaved changes"></span></a>
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Integrations</div>
<a class="nav-item" href="#">Channels</a>
<a class="nav-item" href="#">Tools &amp; MCP</a>
<a class="nav-item" href="#">Plugins</a>
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Runtime</div>
<a class="nav-item" href="#">Container runtime</a>
<div style="height: 1px; background: #232529; margin: 16px 12px"></div>
<a class="nav-item" href="#">History</a>
<div style="flex-grow: 1"></div>
<div style="font-size: 12px; color: #8f8c85; padding: 12px; line-height: 1.5; border: 1px solid #232529; border-radius: 8px">Config version 1 · last saved by <span style="color: #a6a39b">admin</span><br><a href="#" style="color: #86b5a0">View history</a></div>
</aside>
<main style="flex-grow: 1; overflow: hidden; padding: 40px 56px 120px">
<div style="max-width: 920px">
<div style="display: flex; align-items: flex-start; gap: 16px">
<div style="flex-grow: 1">
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Scheduling policy</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">How Archie picks up work items and labels them as they move through states.</p>
</div>
<span style="display: inline-flex; align-items: center; gap: 6px; font-size: 12px; color: #d9a45b; background: rgba(217,164,91,0.1); border: 1px solid rgba(217,164,91,0.25); padding: 4px 10px; border-radius: 999px">
<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a9 9 0 1 1-3-6.7L21 8"></path><path d="M21 3v5h-5"></path></svg>
Applies after restart</span>
</div>
<h2 style="margin: 36px 0 4px; font-size: 13px; font-weight: 600; color: #a6a39b; text-transform: uppercase; letter-spacing: 0.06em">Dispatch</h2>
<div class="row">
<div><div class="lbl">Trigger</div><div class="hint">What causes a work item to be dispatched to an agent.</div></div>
<div style="display: flex; flex-direction: column; gap: 12px">
<div role="radiogroup" aria-label="Trigger" style="display: inline-flex; align-self: flex-start; padding: 3px; background: #121314; border: 1px solid #2e3034; border-radius: 8px">
<button style="height: 30px; padding: 0 14px; border: 0; border-radius: 5px; background: #26282c; color: #e8e6e1; font: 500 13px 'IBM Plex Sans', sans-serif">Assignee</button>
<button style="height: 30px; padding: 0 14px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 13px 'IBM Plex Sans', sans-serif">Label</button>
</div>
<div class="hint" style="margin: 0">Dispatches when Archie is assigned. Choose <span style="color: #a6a39b">Label</span> to set a trigger label instead.</div>
</div>
</div>
<div class="row">
<div><label class="lbl" for="ack">Ack reaction</label><div class="hint">Reaction posted when a work item is picked up.</div></div>
<div><input id="ack" class="inp" value="eyes" style="width: 220px"></div>
</div>
<h2 style="margin: 36px 0 4px; font-size: 13px; font-weight: 600; color: #a6a39b; text-transform: uppercase; letter-spacing: 0.06em">State labels</h2>
<div class="row">
<div><div class="lbl">Labels by state</div><div class="hint">Label applied to the ticket as the agent moves between states.</div></div>
<div style="border: 1px solid #2a2c30; border-radius: 8px; overflow: hidden">
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; padding: 8px 12px; font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: #8f8c85; background: #17181a; border-bottom: 1px solid #2a2c30"><span>State</span><span>Label</span><span></span></div>
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #8f8c85"></span>queued</span>
<input class="inp" aria-label="queued label" value="agent:queued" style="width: 100%; height: 32px">
<button class="icon-btn" aria-label="Remove queued"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
</div>
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #8aa4c2"></span>working</span>
<input class="inp" aria-label="working label" value="agent:working" style="width: 100%; height: 32px">
<button class="icon-btn" aria-label="Remove working"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
</div>
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #d9a45b"></span>waiting</span>
<input class="inp" aria-label="waiting label" value="agent:waiting" style="width: 100%; height: 32px">
<button class="icon-btn" aria-label="Remove waiting"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
</div>
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #86b5a0"></span>pr</span>
<input class="inp" aria-label="pr label" value="agent:pr" style="width: 100%; height: 32px">
<button class="icon-btn" aria-label="Remove pr"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
</div>
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #6f6c66"></span>parked</span>
<input class="inp" aria-label="parked label" value="agent:parked" style="width: 100%; height: 32px">
<button class="icon-btn" aria-label="Remove parked"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
</div>
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #d9776b"></span>dead</span>
<input class="inp" aria-label="dead label" value="agent:dead" style="width: 100%; height: 32px">
<button class="icon-btn" aria-label="Remove dead"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
</div>
<button style="display: flex; align-items: center; gap: 6px; width: 100%; height: 38px; padding: 0 12px; border: 0; background: transparent; color: #a6a39b; font: 500 13px 'IBM Plex Sans', sans-serif; cursor: pointer"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>Add state</button>
</div>
</div>
<h2 style="margin: 36px 0 4px; font-size: 13px; font-weight: 600; color: #a6a39b; text-transform: uppercase; letter-spacing: 0.06em">Retries &amp; polling</h2>
<div class="row">
<div><label class="lbl" for="retries">Max retries</label><div class="hint">Attempts before an item is labelled dead.</div></div>
<div style="display: inline-flex; align-self: flex-start; border: 1px solid #2e3034; border-radius: 6px; overflow: hidden; width: fit-content">
<button class="icon-btn" aria-label="Decrease" style="border-radius: 0">−</button>
<input id="retries" class="inp" value="3" style="width: 56px; border: 0; border-radius: 0; text-align: center; border-left: 1px solid #2e3034; border-right: 1px solid #2e3034">
<button class="icon-btn" aria-label="Increase" style="border-radius: 0">+</button>
</div>
</div>
<div class="row">
<div><label class="lbl" for="poll">Poll interval</label><div class="hint">How often the tracker is checked for new work.</div></div>
<div style="display: flex; align-items: center; gap: 10px">
<div style="display: flex">
<input id="poll" class="inp" value="30" style="width: 80px; border-radius: 6px 0 0 6px; border-color: #86b5a0">
<select aria-label="Poll unit" class="inp" style="border-radius: 0 6px 6px 0; border-left: 0; font-family: 'IBM Plex Sans', sans-serif"><option>seconds</option><option>minutes</option></select>
</div>
<span style="font-size: 12px; color: #8f8c85">was <span style="font-family: 'IBM Plex Mono', monospace; text-decoration: line-through">1m0s</span></span>
</div>
</div>
</div>
</main>
</div>
<div style="position: absolute; left: 264px; right: 0; bottom: 0; height: 72px; box-sizing: border-box; padding: 0 56px; display: flex; align-items: center; gap: 12px; background: #17181a; border-top: 1px solid #2a2c30">
<span style="width: 8px; height: 8px; border-radius: 50%; background: #86b5a0"></span>
<span style="font-size: 13px">1 unsaved change</span>
<span style="font-size: 13px; color: #8f8c85">· Poll interval</span>
<div style="flex-grow: 1"></div>
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard</button>
<button class="btn btn-primary">Save &amp; restart</button>
</div>
</div>
</body>
</html>
Loaded 100 of 1277 files, more files were not shown because too many files have changed in this diff. Show more