Compare commits

...
457 Commits
Author SHA1 Message Date
sam f8b061c314 chore(release): v1.54.3
deploy / gate (push) Canceled after 0s
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
2026-10-16 03:46:35 +11:00
sam c5158edb6c feat(gateway): chat reads workflows and validates drafts
workflow_list, workflow_get and workflow_step_types read the org's
definitions and step catalog; workflow_validate runs the editor's save
check on a proposed definition without saving it.
2026-10-16 03:46:27 +11:00
sam 9ad270b9a4 chore(release): v1.54.2
deploy / gate (push) Canceled after 0s
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
2026-10-16 03:33:58 +11:00
sam 51328c9585 fix(deps): ai-sdk v0.3.1 so Gemini Interactions tool calls get valid arguments 2026-10-16 03:33:49 +11:00
sam aa1ca9e653 chore(release): v1.54.1
deploy / gate (push) Canceled after 0s
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
2026-10-16 03:11:22 +11:00
sam cb29967e7b fix(releaseupdate): find releases in the public releases repository
The source repository is private, so the updater and install.sh got 404.
Releases are now published to samcharles93/archie-releases by
task release:publish.
2026-10-16 03:11:14 +11:00
sam 474fd59759 chore(release): v1.54.0
deploy / gate (push) Canceled after 0s
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
2026-10-16 03:00:32 +11:00
sam 40ee9ffafa fix(rpc): bound gRPC servers and return listener failures
Cap concurrent streams, the handshake and dead peers' streams on every
service, drain shutdown for at most 10s, and stop messaging when its
listener dies instead of running on without Deliver.
2026-10-16 02:57:26 +11:00
sam 939b912889 refactor(ui): unify account administration under Access 2026-10-16 02:57:13 +11:00
sam 83aa17cf8b feat(identity): add browser setup and user accounts 2026-10-16 02:41:24 +11:00
sam 9cdae5642e feat(rpc): mTLS between services from operator-issued certificates
Replace the service bearer tokens with [tls] ca_file and cert_dir. Caller
identity comes from the verified certificate, not metadata. Without TLS,
services listen and dial on loopback only. Task containers get only the CA
and keep their grant.
2026-10-16 02:37:51 +11:00
sam dcf2972f26 feat(ui): start tasks from the dashboard and slim it to activity and setup 2026-10-14 23:28:37 +11:00
sam f96c44d092 refactor(scheduling): remove unused engine accessors 2026-10-14 23:10:35 +11:00
sam f537d5f8cd refactor: delete wrappers superseded by live entry points
Remove controlplanerpc.NewClient (superseded by NewRPCClient), Loader.Overlay
(-config-overlay reaches Resolve directly), and setup.Run (RunParams is
the live entry point). Move ResolverFunc into a test file, since only
tests adapt functions to the egress Resolver.
2026-10-14 23:10:35 +11:00
sam c833b651a9 fix(workflow): set BuildNoChanges from writable stages and clear it on commit
A writable agent stage that passes now marks BuildNoChanges; repo.commit
clears it when the stage commits changes. The flag had no setter, so the
signal was lost in the YAML migration. The outcome of an empty commit
stays with if_empty: unset still fails, complete closes the issue, skip
moves on.
2026-10-14 23:10:34 +11:00
sam 062f5332a0 refactor(gateway): delete unused wrappers and in-memory session store
Remove gateway re-exports of messaging helpers with no callers, the
unused DeltaFunc adapter, DefaultPersonas, NewStoreTaskCreator, the
SortBySeq stub, and the in-memory session store that nothing constructs.
2026-10-14 23:10:34 +11:00
sam d9fe384fd9 build(deps): bump ai-sdk v0.1.43 -> v0.3.0 and update dependencies
Gemini 3.x/4 chat now routes through the Interactions API transport, which
replays thought signatures on tool turns; long decode stays opt-in. Also
takes go get -u updates (x/*, genproto, goose, nats-server, modernc sqlite).
2026-10-14 23:10:34 +11:00
sam 8a7220f5e9 fix(gateway): isolate model selections by org 2026-10-14 21:19:34 +11:00
sam 5b9ff6fa47 fix(gateway): restore provider model selection in chat
Restore provider groups and concrete model references in chat snapshots. Permit catalog selections while retaining named aliases and tenant model restrictions. Show the active model in /profile without requiring a task identity.

Refs: archie-core-mvek6
2026-10-14 21:03:30 +11:00
sam 66b22f4833 build: trim filesystem paths from service and agent binaries 2026-10-14 03:49:31 +11:00
sam acec5d392d feat(archied): read-only run-scoped sandbox view over the harness contract (#1662)
* feat(archied): read-only run-scoped sandbox view over the harness contract

Serve RunTarget: the daemon resolves a running task and attempt to its Kit
container and follows its output, refusing a finished or unknown task with a
stated reason. The dashboard adds a Sandbox tab behind the task log's read
authority. Takeover stays out of scope until the sod1 authority is wired.

* fix(archied): scope and close sandbox views correctly

Forward harness activity into container output, bind containers and dashboard views to their attempt, enforce the asserted org, and report unavailable dependencies and interrupted streams accurately.

Refs: archie-core-qi91, archie-core-252tj
2026-10-14 02:57:32 +11:00
sam 59be81c7f6 fix(webui): an absent setting equals its zero value in drafts; setting rows get roomier padding 2026-10-13 20:20:03 +11:00
sam c0ac39b8da fix(webui): the danger setting row tints without shifting its content 2026-10-13 19:55:05 +11:00
sam 7b19935a14 build(webui): add the CardAccordion chunk missing from the bundle 2026-10-13 19:49:25 +11:00
sam fa7d0d83c1 fix(archied): report schedules apply status at start and on a timer 2026-10-13 19:08:55 +11:00
sam 7542e3b15e fix(archied): report workflow definitions apply status at start and on a timer 2026-10-13 19:06:53 +11:00
sam 6412e6d116 feat(webui): settings lists share a card accordion that opens the new item and blocks adding while unsaved 2026-10-13 19:06:01 +11:00
sam b1dbe519b0 feat(webui): repositories list is an accordion; adding opens the new one and waits for save 2026-10-13 19:04:14 +11:00
sam 3103f87b71 fix(applystatus): the gateway no longer owes an apply status for channel and plugin settings 2026-10-13 19:00:52 +11:00
sam 8664e8cd97 fix(webui): drop settings hints that restate their label 2026-10-13 18:11:12 +11:00
sam 9e566e7278 fix(webui): shorten route descriptions, setup steps, alerts and panel errors 2026-10-13 18:10:39 +11:00
sam f02a3b6d02 fix(agent): drop the one-question cap from the chat prompt and SOUL 2026-10-13 17:49:35 +11:00
sam bf6f3512b1 feat(agent): default persona and SOUL share a reporting-focused identity prompt 2026-10-13 17:47:46 +11:00
sam 00112ae205 fix(webui): attention vocabulary no longer addresses a single user 2026-10-13 17:42:11 +11:00
sam 8001c893bd fix(webui): cut tutorial and marketing prose from labels, hints, empty states and confirms 2026-10-13 17:37:53 +11:00
sam 0e25291d47 fix(webui): review settings drop the in-force echo and rewrite the approval hint 2026-10-13 17:28:31 +11:00
sam 68fb3a7e19 fix(webui): form fields sit on the card colour so they no longer read as disabled 2026-10-13 17:24:48 +11:00
sam 541575a073 fix(archied): load and report EDA playbooks at start instead of at the first dispatch 2026-10-13 17:22:01 +11:00
sam d4d24cb1db fix(webui): default-alias warning states the action only 2026-10-13 17:17:06 +11:00
sam 20cb2fd99d fix(webui): task page drops filler copy, the unattributed-events note and the New run tooltip 2026-10-13 17:16:25 +11:00
sam 4fd6efb7f0 fix(webui): alerts drop UI-explaining prose and align Dismiss with the title 2026-10-13 17:14:43 +11:00
sam 9eabc624ee fix(config): a task snapshot carries only the model limits its aliases resolve to 2026-10-13 17:07:40 +11:00
sam 01418b7e81 fix(webui): harness terminal-unavailable message says what the operator can do 2026-10-13 17:02:45 +11:00
sam cac763a339 feat(webui): finish redesign dashboard task and secret settings 2026-10-13 16:41:35 +11:00
sam 0dde93e57e fix(taskactions): a failed callee cancel no longer leaves the caller's run going
Issue: archie-core-kig5j
2026-10-13 16:22:40 +11:00
sam 7435b6efe5 fix(eda): the undispatched-capture batch lists only captures an enabled binding still owes
Issue: archie-core-kfjz1
2026-10-13 16:21:21 +11:00
sam 796c7a711b fix(postgres): age retention spares captures still waiting to be dispatched
Issue: archie-core-jrh2m
2026-10-13 16:19:12 +11:00
sam 4ac9fd852f fix(postgres): assign bootstrapped agent identities to the default org on every start
Issue: archie-core-n5yj5
2026-10-13 16:18:19 +11:00
sam 06d6293a9d fix(controlplane): instance settings are written by the system org only
Issue: archie-core-f5zso
2026-10-13 16:17:38 +11:00
sam 0c904fb9ef fix(controlplane): playbook dispatch resolves and caches per the task's org
Issue: archie-core-5t4z7
2026-10-13 16:16:31 +11:00
sam 59645969ee fix(e2e): repository policy applies live, so seeding no longer restarts archied
Issue: archie-core-m5aqb
2026-10-13 16:15:07 +11:00
sam acacdfdab5 fix(statestore): an invalid stored policy raises an alert and resolves when it validates
Issue: archie-core-kgxw.16
2026-10-13 16:14:16 +11:00
sam 2090c41960 fix(ops): external NATS needs a token and publishes monitoring on loopback only
Issue: archie-core-ov11
2026-10-13 16:09:23 +11:00
sam e5a67b8ff0 fix(webui): a source create is authorized against the workspace it names
Issue: archie-core-ed8tw
2026-10-13 16:00:37 +11:00
sam 8e6dfd785f fix(webui): channel reload route is authorized as the channel action
Issue: archie-core-4laa1
2026-10-13 15:59:36 +11:00
sam b9547b01a8 fix(staterpc): an org-scoped caller cannot read or write another org's harness secret
Issue: archie-core-jo15w
2026-10-13 15:58:51 +11:00
sam 0720e9629c fix(statestore): a restart never resolves a service alert still inside its grace
Issue: archie-core-07lyl
2026-10-13 15:56:23 +11:00
sam bb67bd77f1 fix(statestore): service-unhealthy grace counts from the last stored report and covers silent services
Issue: archie-core-07lyl
2026-10-13 15:29:29 +11:00
sam 8ecda341e0 fix(servicekit): report apply status only for kinds the process re-applies live
Issue: archie-core-mt91
2026-10-13 15:28:43 +11:00
sam dee78a876a fix(postgres): clamp event, token and denial limits to int32
Issue: archie-core-g14d
2026-10-13 15:27:36 +11:00
sam 33ccfb2505 fix(daemon): run-time workflow check sees the binding event's signature and address
Issue: archie-core-bmro8
2026-10-13 15:10:31 +11:00
sam 0330a65054 fix(postgres): confine identity writes and GetPrincipal to the caller's org
Issue: archie-core-wkey2
2026-10-13 15:07:48 +11:00
sam 4eb9c20c0c fix(workflows): callees of a test run inherit the test source 2026-10-13 12:46:48 +11:00
sam 1f4910a651 feat(workflows): test-run unsaved drafts and browse workflow version history
A test run pins a validated draft, runs with forge and push writes
suppressed and recorded per step, and is excluded from workflow stats.
The History tab lists revisions that changed a workflow, diffs them as
YAML and on the canvas, restores into the editor, and ties runs to the
revision they used.
2026-10-13 12:27:40 +11:00
sam 150bfd4605 fix(postgres): quote the alert lock key so a NUL cannot reach Postgres text 2026-10-13 03:15:06 +11:00
sam 3bf64933b0 fix(ui/topbar): replace Jump to with a command palette, drop filler chrome (#1650)
* fix(ui/topbar): replace Jump to with a command palette, drop filler chrome

Jump to opens a shadcn-vue Command dialog that finds pages, tasks and
workflows by name. The connection indicator shows only when the stream is
lost, the dead documentation link is gone, and the profile menu label has
no stray whitespace.

* fix(ui): trim stray whitespace from template text and drop em dashes from copy

Element text that started or ended with a line break rendered with leading
and trailing spaces. Also removes the unused 'soon' nav state and the nav
group components no route reaches.

* fix(ui): drop the space a hidden spinner left before button text

* fix(ui/status): one dense Status page, full-width settings, problems-only apply status

Status drops its tabs and the duplicate health card; services list only
what is wrong. Settings pages use the full width, the resizable sidebar
handle is gone, and apply status shows only processes that have not
applied a change. PageHeader puts the title and actions on one line.

* refactor(ui): use shadcn ToggleGroup and Badge, drop SegmentedControl and StatusPill

Status badges show only when a state needs attention: no Running, Enabled,
Active, Listening or live pills next to healthy rows. Removes the unused
pagination, radio-group and scroll-area components.

* fix(ui/history): use the shadcn Table with fixed columns so nothing is clipped

* fix(ui/workflows): apply ?workflow= only once the workflow is listed

Selecting it before the definitions loaded opened an empty canvas.

* refactor(ui/workflows): use shadcn Input, NativeSelect, Checkbox and Button in editors

Replaces hand-rolled inputs, selects, the repository mode switch and icon
buttons in the workflow editor, bind dialog, harness page, sources panel
and review gate. Adds the upstream shadcn-vue NativeSelect.

* style(ui): rounded-rectangle controls instead of pills

Halves the radius scale so inputs, selects and buttons stop reading as
pills, and badges and chips lose their full rounding.

* fix(ui/alerts): centre the bell's failed state and stop it contradicting Needs you

* fix(ui/tasks): one header line, aligned columns, no placeholder issue numbers

Tasks puts its filters beside the title and drops the stat tiles the
dashboard already shows. Sort headers align with their cells, chat tasks
no longer show their synthetic issue number, and Logs and the task
not-found page use the shared header.

* fix(ui/dashboard): shared header and cards, empty cards stay silent

Needs you uses the shadcn Card and drops its duplicate Open button; quality
gates and token outlook render only when there is something to show; the
throughput strip moves into the dashboard, its only user.

* refactor(ui/stores): one Pinia store per feature

Splits the site-wide control-plane store and the module-level refs into
settings, workflows, tasks, events, org and session stores. Identity
requests move into lib/api. Drops store fields nothing read: per-resource
stream state, the states map and loadApplyStatus.

* fix(ui/org): one header for the org area, sections drop their repeated titles

The org name is the page title with the admin's org switcher and New org
beside it; Members and Workspaces tables sit in cards like other pages.

* fix(ui/events): shadcn Tabs for the capture, map and bind steps

Replaces the numbered step strip with line tabs that carry each step's
count; the Listening pill is gone and Capture off shows only when it is.

* fix(ui/workflows): confirm a workflow delete in an AlertDialog, not window.confirm

* style(ui/settings): denser setting rows
2026-10-12 04:40:21 +11:00
sam 94d2f98cc0 feat(e2e): local stack, seed and browser checks for release validation 2026-10-12 04:28:26 +11:00
sam 2df2f72fc2 fix(ci): guard apparmor userns sysctl in deploy workflow 2026-10-12 04:17:11 +11:00
sam 8a3ba32c5a Feat/operator alerts (#1635)
* feat(state): durable operator alerts owned by the State Store

Alerts dedup on org+kind+subject, resolve themselves when a condition
clears, and are raised, resolved, dismissed and listed through the state
contract. Task transitions raise needs-human and failed alerts in the same
transaction; the store checks service health and prunes closed alerts.
Each raise and resolve queues a webhook delivery whose attempts are kept.

* feat(notify): deliver operator alerts to the webhook; raise config and release alerts

notify.webhook now receives raised and resolved alerts above a severity
threshold with HMAC-signed payloads, bounded retry and every attempt recorded
on the alert. archied raises model alias, provider and credential-binding
alerts from the effective configuration, an update alert from the release
channel, and a credential-rejected alert from the egress resolver. The
dashboard API lists and dismisses the caller's org's alerts.

* feat(ui): alert bell in the top bar and webhook alert settings

The bell lists the org's open alerts by severity with dismiss and a link per
alert, and refreshes from the event stream. The task settings page gains the
webhook severity threshold and signing secret. ui/dist rebuilt.
2026-10-12 03:30:46 +11:00
sam f34f60f9c7 Feat/org epic (#1634)
* fix(postgres): scope OpenPRs to the caller's org

A principal-carrying caller read every org's pr_open tasks. The query now
honours the request scope; the daemon's unscoped review scan still sees all
orgs.

Issue: archie-core-kgxw.23

* fix(statestore): serve task logs only to the task's org

ReadTaskLog and StreamTaskLogContent took a task ID and read the file with
no org check. The State Store's task-log reader now confirms the task is
visible under the caller's scope first; unscoped services read as before.

Issue: archie-core-kgxw.24

* fix(postgres): scope ListPolicies to the caller's org

Every org's policy text reached any principal-carrying caller. A scoped read
now sees its own org's policies, plus instance policies when scoped to the
system org. The engines and the lockout guard decide for every org, so they
read the full chain unscoped: the dashboard engine loads without the
request's principal and the guard lifts the caller's scope.

Issue: archie-core-kgxw.25

* fix(postgres): scope identity reads to the caller's org

ListIdentities and GetIdentity (and its alias fallback) returned every
identity to any caller. A caller scoped to an org now sees only that org's
members and assigned agents; the system org and unscoped services still see
the whole instance.

Issue: archie-core-kgxw.26

* fix(postgres): hide instance status from other orgs

ListPresence, ListChannelStatus, ListApplyStatus and GetConfigSnapshot
answered any org principal with instance-wide state. They now return nothing
unless the request is unscoped or scoped to the system org. The dashboard
reads the published config as itself, since its handlers project it for
callers of every org.

Issue: archie-core-kgxw.27

* feat(postgres): assign new agents an org and role at creation

A bot or service account created through the API served no org until the
next State Store boot granted it one. Create now assigns it to the org the
request acts in with the developer role in the same transaction, so it is
authorized immediately.

Issue: archie-core-kgxw.14

* feat(edastore): create event records in a chosen workspace

Sources are created in a workspace of the caller's org, the default one when
none is named; event types and bindings take their source's workspace and
mappings their event type's, the same rule the org backfill applied. The
binding, mapping and event type contracts carry the workspace, the four list
endpoints accept ?workspace=, and the Events page has a workspace selector
that filters every step and picks where a new source goes.

Issue: archie-core-kgxw.11

* feat(webui): authorize a record in its workspace

The API built every access request with no workspace, so workspace
policies and per-workspace roles never applied. A request naming a source,
binding, mapping, event type or task now reads the record's workspace under
the caller's scope and authorizes in it; tasks carry their workspace on the
State Store contract for this.

Issue: archie-core-kgxw.9

* feat(access): expose workspace environment to policies

Policies can test resource.workspace.environment. The workspace attribute
is the workspace entity, which carries its environment; the principal
brings its org's workspaces from the State Store, so the dashboard and the
daemon's run checks describe a resource's workspace without another lookup,
and the daemon now authorizes runs in the task's or binding's workspace.

Issue: archie-core-kgxw.10

* fix(webui): ask read_secret when a source secret is read

Rotating a source's secret returns its value, but the route asked update,
which every developer holds, so no policy could narrow who reads a secret.
It now asks read_secret on the secret, which the shipped roles give admins
and an object policy can narrow further.

Issue: archie-core-kgxw.17

* refactor(org): delete the unused upgrade-incomplete sentinel

Nothing returns org.ErrUpgradeIncomplete: the State Store finishes the org
upgrade before it serves.

Issue: archie-core-kgxw.18
2026-10-12 03:24:04 +11:00
sam 8540c9f7c8 feat(releaseupdate): transactional self-update through archied (#1633)
archied update install verifies the release zip, checks every binary
reports the release, pulls the agent image by digest, backs up the
database in-process and stages the binaries before handing off to
archied update watchdog in its own process. The watchdog restarts units
in release order, requires archied healthy for 120s and otherwise rolls
back binaries and image policy, restoring the database only when a
migration ran. Boot recovery resumes the frozen watchdog.

Deletes scripts/archie-update-install, scripts/archie-update-watchdog,
the updater's --from-source and --auto, CommandInstaller,
ScriptInstaller and the update-image and update-topology subcommands.
2026-10-12 03:21:02 +11:00
sam 3014db85e7 Fix/workflow eda audit (#1627)
* fix(webui): accept the merge task action

The action whitelist omitted merge, so the dashboard's Merge button on a
pr_open task was refused with 400 unknown action.

Closes: archie-core-slpoz

* fix(workflow): give each parallel branch its own outputs

Branches shared the task's Outputs map, so concurrent declared-output
writes raced (or were lost when the map started nil). Each branch now
writes a copy; join merges new outputs in branch-name order and refuses
one written by two branches as a second write.

Closes: archie-core-3a7w2

* fix(postgres): dispatch captures oldest first and keep pending ones

ListUndispatchedCaptures ordered newest first and listed captures no
binding can match (failed HMAC), so sustained intake starved older work
and bad signatures held the batch. It is now oldest first and lists only
dispatchable captures. Count retention no longer evicts a capture that
is still pending for an armed binding. The daemon lists only sources
with an enabled workflow, so captures waiting on a disabled one do not
hold the oldest-first batch.

Closes: archie-core-2et4b, archie-core-o0s0z

* fix(ui): refuse renaming a workflow onto an existing id

Saving upserts by id, so editing a workflow's id to another workflow's
id removed the open one and overwrote the other. The editor now refuses
that save and says why.

Closes: archie-core-wpoz8

* fix(workflow): reject unknown step settings at save

Step factories decoded settings with yaml.Node.Decode, which drops keys
it does not know, and settings-less steps ignored settings entirely, so a
misspelt key (readOnly for read_only) saved and silently did nothing.
Every factory now decodes strictly and settings-less steps refuse
settings; ParseDefinition runs the factories, so the save refuses them.

Closes: archie-core-8b5nk

* fix(postgres): keep a stored capture when its prune fails

InsertCapture committed the capture, then returned the prune's error, so
intake answered 500 and a sender without a delivery header retried into
a duplicate capture and a duplicate dispatch. A failed prune is now
logged and the stored capture's id returned.

Closes: archie-core-3miuh

* fix(crondelivery): fail and advance a job no runner can deliver

Router.Run returned nil for a kind with no runner, so the engine reported
a successful run while the schedule never advanced and the job fired on
every tick. The run now fails with the refusal, which the engine reports,
and the schedule advances (a one-shot is removed). The router's own
refusal event is gone with it.

Closes: archie-core-s6ahh

* fix(taskactions): stop the runs of cancelled callees

CancelExecution cancelled a caller's waited-on callees in the store, but
only the caller's run was stopped, so callee containers ran to the end.
CancelExecution now returns the callees it cancelled (nested included)
in place of the step ids nobody read, and every cancelling action stops
their runs too.

Closes: archie-core-9labz

* fix(workflow): treat a zero json.Number as false in when

Task inputs and step results decode numbers as json.Number, which truthy
did not unpack, so when: inputs.count held for a count of 0.

Closes: archie-core-uv270

* fix(webui): read a workflow's runs with a workflow-filtered page

The workflows page and the canvas run picker filtered the newest 100
tasks of every workflow client-side, so on a busy instance a workflow's
older runs were invisible. GET /api/tasks takes a workflow filter, carried
through the State Store's Tasks request to the query, and both views ask
for the selected workflow's runs.

Closes: archie-core-tpiw1

* fix(ui): load the restored workflow into the editor

Restore Defaults saved the shipped definition but left the open draft in
the editor, still marked unsaved, so a later save re-applied it. The
editor now reloads the restored definition.

Closes: archie-core-85e7w
2026-10-12 03:20:00 +11:00
sam aea7c5c9f1 build(tools): provision PostgreSQL 18 in the cloud setup for full checks 2026-10-12 03:00:46 +11:00
sam c792c552cf build(tools): link cloud setup tools onto the default PATH 2026-10-12 02:44:11 +11:00
sam a71f1e0817 ci: drop the Postgres client from the deploy gate 2026-10-12 02:19:51 +11:00
sam 76905c8ec6 ci: run every job on the self-hosted runner 2026-10-12 02:10:14 +11:00
sam 85d8b771f0 Merge pull request #1602 from samcharles93/feat/workflow-runs-as
Feat/workflow runs as
2026-10-12 02:08:30 +11:00
sam d31a950daa feat(workflow): shipped workflows run as the instance root 2026-10-12 01:53:55 +11:00
sam f765e23812 feat(daemon): run each workflow as its declared identity
Every attempt checks that the identity that started the task and the
identity the workflow declares may both run it, recording a denial for
either. A workflow that declares no identity is refused rather than
running as its starter or the root. A workflow.call callee is started by
its caller's declared identity instead of inheriting the caller's row.
The workflow settings panel marks the identity as required and offers
the agent identities.
2026-10-11 14:49:38 +00:00
sam d66dca44e0 Merge pull request #1601 from samcharles93/fix/atomic-dispatch
Fix/atomic dispatch
2026-10-12 01:29:16 +11:00
sam b8f8f9a272 fix(postgres): allocate synthetic issue numbers from a per-repo counter
InsertChatTask and EnqueueCallTask computed MAX(issue_number)+1, so
concurrent inserts in one repository took the same number and the second
failed on the unique key. Both now bump a chat_issue_numbers row, seeded
from the existing maxima, whose row lock serializes allocation.
2026-10-11 14:21:27 +00:00
sam e128f82e11 build(ui): install dashboard deps from the lockfile without rewriting it 2026-10-12 01:21:16 +11:00
sam daab5732e8 fix(daemon): claim binding dispatch and enqueue its task atomically
EnqueueBindingTask now takes the capture and claims the ledger row,
inserts the task, stamps its provenance and links the ledger row in one
State Store transaction. A failure anywhere leaves the delivery
undispatched for the next cycle; a replay or concurrent claim is refused
by the ledger's unique index. SetDispatchTask is removed.
2026-10-11 14:19:43 +00:00
sam eb5703b7dd ci: drop the Postgres client the removed tests needed 2026-10-12 01:17:11 +11:00
sam ce5fc3e226 test(postgres): remove database-backed tests and the testcontainers harness 2026-10-12 01:17:02 +11:00
sam c2a649ded4 docs(agents): forbid database-backed tests 2026-10-12 01:15:19 +11:00
sam 1b0a89ca2e fix(tools): keep bd hook setup out of the checkout 2026-10-12 01:14:38 +11:00
sam 1441585e06 chore: reindent beads config and add agent profile 2026-10-12 01:01:19 +11:00
sam f3576342b6 chore(tools): rely on preinstalled gh in cloud setup 2026-10-12 00:46:51 +11:00
sam ede2102c60 chore(tools): install gh in cloud setup 2026-10-12 00:43:37 +11:00
sam 16d98dd47c chore(tools): install bd via upstream installer and disable attribution in cloud setup 2026-10-12 00:41:07 +11:00
sam 7aca31b18f chore(tools): add Claude cloud environment setup script 2026-10-12 00:12:18 +11:00
sam e97f1fa609 fix(ci): limit gate concurrency to runner memory 2026-10-11 22:28:11 +11:00
sam 62f0baba36 fix(ci): use repository-scoped quality runner 2026-10-11 22:10:52 +11:00
sam 40fa6f9d7d fix(ci): check namespace support before installing tools 2026-10-11 21:33:56 +11:00
sam 6ce605d6ea fix(ci): allow extension namespaces in quality container 2026-10-11 21:30:43 +11:00
sam feba855326 style(ui): tidy org page layouts and empty states
Members and Workspaces get fixed column widths and their add forms move
into labelled sections. Agents lists agents first and moves credential
grants below. Access puts New policy in the card header. Tokens states
when none exist.
2026-10-11 15:59:30 +11:00
sam 47f75f71a7 docs: remove incorrect notice 2026-10-11 12:17:31 +11:00
sam 4e060ce5ef fix(ui): stage history restore as a draft applied from the save bar 2026-10-11 11:35:02 +11:00
sam e2e24f9d56 ci(deploy): pull the container image the uncached test suite needs
deploy / gate (push) Canceled after 0s
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
2026-10-11 04:26:08 +11:00
sam 5aa5c2a6c8 chore(release): v1.53.0 2026-10-11 04:23:10 +11:00
sam 41b2daed0c Merge branch 'work/53jc' 2026-10-11 04:11:43 +11:00
sam e0a79b3990 Merge branch 'work/ry4k' 2026-10-11 04:11:43 +11:00
sam e2d6b75b10 fix(prreview): restore the benchmark runner on configured models and public PRs 2026-10-11 04:11:40 +11:00
sam b4be999777 fix(gateway): remove the web /restart command that no process could serve 2026-10-11 04:11:37 +11:00
sam 5c3bf0b642 feat(storepkg): auto-update policy, applied by a State Store ticker 2026-10-11 04:10:53 +11:00
sam be2b897149 refactor(servicediscovery): delete unreachable contract and NATS implementation 2026-10-11 04:09:56 +11:00
sam f5a39cfb9b fix(daemon): bound a package workflow's triggers by its accepted authority 2026-10-11 04:08:02 +11:00
sam f5a6fa5b32 fix(postgres): number the outcome-posted migration after package updates 2026-10-11 04:04:45 +11:00
sam 93ec6d916b Merge branch 'work/mt9xo' 2026-10-11 04:03:52 +11:00
sam c36fb29683 Merge branch 'work/zcg8' 2026-10-11 04:03:52 +11:00
sam cac0f43b58 Merge branch 'work/mqti13'
# Conflicts:
#	internal/contracts/state/v1/state.pb.go
2026-10-11 04:03:52 +11:00
sam 805364f201 feat(archied): post a chat task's outcome back to its chat 2026-10-11 04:03:30 +11:00
sam 3b2a3a7630 fix(webui): the setup checklist and skill catalogue are system-org only 2026-10-11 04:01:46 +11:00
sam bf29d3640e fix(daemon): reown worktrees a killed container left root-owned 2026-10-11 04:01:19 +11:00
sam de15bffc2f fix(telegram): publish /approve, which the router already serves 2026-10-11 03:57:10 +11:00
sam 1377e7ebf2 feat(webui): add a member by provider subject or email
POST /api/orgs/{id}/members binds a person by subject, or by email as a
placeholder. The first sign-in whose provider vouches for that email
claims it: the State Store moves the binding onto the provider's subject
in one statement, so a second account with the same address finds
nothing to claim and later sign-ins rest on the subject alone.
2026-10-11 03:54:49 +11:00
sam d53ebbda95 fix(daemon): last poll reports the least recently polled loop 2026-10-11 03:53:11 +11:00
sam b227df3c3f feat(storepkg): widening updates wait for approval, rollback restores the previous pin 2026-10-11 03:48:31 +11:00
sam a3e0e5c1bb fix(daemon): bound a package workflow's tools by its accepted authority 2026-10-11 03:48:31 +11:00
sam 116f8a10fb style(webui): rewrap the assets comment 2026-10-11 03:48:17 +11:00
sam 116b03534f fix(staterpc): a task's own credential cannot replace its workflow pin
The pinned definition carries the package a run's authority is read
from. A task-scoped Update now reaches the store without a definition,
and UpdateTask keeps the stored pin when none is sent; the workflow name
still moves for handoffs and the daemon re-pins it.
2026-10-11 03:47:17 +11:00
sam b697a12b89 fix(webui): an unserved /api path is a 404, not the dashboard page 2026-10-11 03:46:40 +11:00
sam 7b64699ff1 refactor(workflow): delete routing overrides nothing applied 2026-10-11 03:43:25 +11:00
sam 1598b3cc74 docs(agents): extend the finish-and-shrink rule to 2026-10-20 2026-10-11 03:39:31 +11:00
sam 212742e880 feat(forgerpc): bound a package workflow's forge calls by its accepted authority 2026-10-11 03:37:16 +11:00
sam 6693e60f6f fix(access): an unloaded chain is a refusing engine, not nil
Webhook intake answers 503 and counts no refusal while the chain loads.
The readiness probe reads the chain on every check. The UI never exits on
a first-load failure. An invalid instance policy closes the instance but
lets an instance admin repair policies. Outage pages are 503, and the
health detail names the unloaded chain.
2026-10-10 22:19:02 +11:00
sam c097e50405 fix(archieui): warn when the dashboard is reachable off-host over plain HTTP
The dashboard serves plain HTTP, so a non-loopback bind carries the
session cookie and provider token in clear unless TLS terminates in front.
Warn at startup unless the operator declares a proxy with
[web].trust_forwarded_headers, and record the choice in deployments/README
where the dashboard is deployed. Point the non-loopback token error at
that surviving doc, not the deleted UI-boundary PRD.
2026-10-10 22:09:05 +11:00
sam ccbc9c7844 fix(webui): the wildcard listen address is not loopback
IsLoopback(":8484") returned true: the empty host fell through the
switch as loopback, so a wildcard bind skipped the non-loopback token
requirement and served every interface unauthenticated. An empty host is
the wildcard, not loopback.
2026-10-10 22:09:05 +11:00
sam 948a8d34fd test(worktree): give each transport its own branch
The four subtests share one bare repo but pushed the same feat/1-test
branch. Their commits have the same tree, message, author and parent, so
two commits in the same second hash identically and the second push is a
no-op -- passing by luck -- while a second of clock drift makes it a
non-fast-forward failure. One issue per subtest gives each its own branch.
2026-10-10 22:05:22 +11:00
sam e078b5c4bc fix(webui): refuse API requests until the access chain loads
A State Store that was unreachable at startup left the access chain nil,
and authorize treated nil as no chain at all: every request passed the
credential check, no principal or org reached the context, the State Store
defaulted each call to org-sys, and the instance-only surfaces were served.
The dashboard stayed open until a restart.

Build a chain with no engine when the first load is Unavailable; it refuses
every request with 503 (or the notice page for a browser) until the first
load succeeds, and Run keeps retrying so the dashboard recovers without a
restart. A denial is not recorded, because nothing was evaluated.
2026-10-10 21:55:02 +11:00
sam 4a24c0b31f fix(memory): each org's agent memory is its own 2026-10-10 21:20:37 +11:00
sam e988d3cc40 fix: close cross-org writes and move existing rows into their owner's org 2026-10-10 20:31:54 +11:00
sam cd20aeadad fix(webui): instance health, logs, config and identities are system-org only 2026-10-10 20:20:07 +11:00
sam 1bb7ba1248 fix(postgres): tasks, events, steps and run stats stay in their org 2026-10-10 20:18:29 +11:00
sam fdafec3d9d fix(postgres): event sources, types, mappings and bindings stay in their org 2026-10-10 20:14:23 +11:00
sam 0fcf792db3 feat(gateway): chat sessions belong to one org
Sessions carry an org; listing, reading and writing a session, its
messages and its turns are limited to the caller's org. Another org's
session reads as not found and cannot be overwritten or appended to.
Sessions from before orgs belong to the system org.
2026-10-10 18:57:26 +11:00
sam 9cd52dd9aa feat(archiegateway): chat resolves models in the caller's org and bills it
The State Store answers the calling principal's org aliases
(CallerModels) and bills chat usage to that org; usage records no longer
carry a caller-named org. Chat lists and resolves aliases for the
caller's org and fails rather than substitute one it may not use.
2026-10-10 18:53:57 +11:00
sam 5290dab199 feat(controlplane): per-org model access, org aliases and org providers
The system org sets each org's allowed models and whether it may add its
own providers (org-model-policy); an org with no entry may use nothing.
An org's aliases and providers are checked against that policy on save
and filtered by it at resolution. Tasks get their org's providers, keyed
by the org's credential binding through the egress proxy. Org Settings
gains a Models tab; instance Models gains Org access.
2026-10-10 18:48:40 +11:00
sam e17c7895e4 feat(daemon): resolve a task's models and credentials in the task's own org
The State Store answers a task's effective model aliases (instance aliases
with the task org's own over them), deriving the org from the task. Model
egress and the run credential resolver use the task's stored org instead
of the identity mapping in config.
2026-10-10 18:40:53 +11:00
sam e4ea2eaabc feat(statestore): record a usage row for every model call
Task agent runs and MCP sampling record against their task (billed to the
task's org); gateway chat turns, titles, sampling and curators record
against the system org. Rows carry source, workflow, step, alias,
provider/model and tokens for later chargeback.
2026-10-10 18:32:43 +11:00
sam 12b9a57404 feat(config): model aliases replace model roles, resolved by one resolver
Agent steps, implement, pr-review, MCP sampling, chat, embedding and
transcription resolve a model alias (empty means the purpose's default)
and fail on an unknown alias instead of falling back. The step editor and
chat pick aliases; workflow definitions naming an unknown alias are
refused on save.
2026-10-10 17:29:52 +11:00
sam 514c6cf61c fix(daemon): keep model provider keys out of agent containers via the egress proxy 2026-10-10 17:12:09 +11:00
sam bef0ecea3a feat(ui): workflow list shows running count and latest run result 2026-10-10 11:50:27 +11:00
sam 5bb5d9b660 feat(ui): quieter workflows page: hover data edges, apply chip, restore behind confirm 2026-10-10 11:49:32 +11:00
sam f30405ea2b fix(ui): input group addon no longer steals clicks from its select 2026-10-10 11:26:42 +11:00
sam f9efae8a5e fix(archiegateway): keep the chat model list non-nil when empty 2026-10-10 11:17:37 +11:00
sam 819cfc655b refactor: slices.Sorted over map keys and one shared IsNil check 2026-10-10 11:14:36 +11:00
sam 5afe5bcf99 refactor: use slices.Index/Delete and slices.Clone for small copies 2026-10-10 11:14:36 +11:00
sam 0c25b2f4a6 refactor(workflow): decodeSettings returns a typed value 2026-10-10 11:14:36 +11:00
sam 252895e01c refactor(staterpc): use mapValues for proto list conversions 2026-10-10 11:05:59 +11:00
sam 3ea49c7e07 refactor(gateway): drop duplicate string arg helpers 2026-10-10 11:05:59 +11:00
sam 66a27bd7ef refactor(controlplane): make layerResource decode into a typed value 2026-10-10 11:05:59 +11:00
sam b070ce4715 refactor(eda): use slices.Sorted over maps.Keys for ordered keys 2026-10-10 11:05:58 +11:00
sam 84b581fde6 refactor(webui): decode JSON request bodies with generic decodeBody 2026-10-10 11:05:58 +11:00
sam af5e11a734 refactor(domain): share one generic lifecycle registry for curators and memory engines 2026-10-10 11:05:58 +11:00
sam 522ced45ff feat(ui): lanes for parallel and switch steps on the workflow canvas 2026-10-10 10:52:52 +11:00
sam 79d7f2fa68 feat(workflow): switch step runs the case matching a reference 2026-10-10 10:52:52 +11:00
sam eb3ee14a0e feat(ui): step roles, numbers and run trace on workflow canvas 2026-10-10 10:37:47 +11:00
sam 6ed6b28d02 build(ui): refresh dashboard bundle 2026-10-09 20:06:01 +11:00
sam 2f4e9bbe14 Merge branch 'main' into codex/control-plane-4q28 2026-10-09 20:03:52 +11:00
sam 3057f054b2 style: remove space between icons and labels 2026-10-09 19:56:27 +11:00
sam a4e7ea8cc3 fix(kit): migrate runtime to sandbox kit m8 2026-10-09 18:31:56 +11:00
sam c812192800 feat(ui): author parallel workflow branches on canvas 2026-10-09 18:18:45 +11:00
sam 81121d03b0 docs(agents): omit status the maintainer can already see 2026-10-09 18:16:45 +11:00
sam e5f03587c9 docs(agents): post externally only when told 2026-10-09 18:09:11 +11:00
sam c25e70a588 docs(agents): act on clear direction and keep replies short 2026-10-09 18:04:38 +11:00
sam b97c79aa0b feat(ui): edit workflow call interfaces on the canvas 2026-10-09 18:04:08 +11:00
sam 2d2c39f9e5 fix(daemon): reconcile call waits from durable steps 2026-10-09 17:56:15 +11:00
sam 673a5bc2ce chore(release): v1.52.0
deploy / gate (push) Canceled after 0s
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
2026-10-09 13:09:59 +11:00
sam df5ee243b1 feat(harness): create the setup PTY at the browser's size
The setup terminal created its PTY at a fixed 24x80 while the browser
measured its own box and threw the measurement away, so a full-screen CLI
login drew into a corner of a much larger xterm.

OpenRequest now carries a ConsoleSize with the target frame; the route
reads cols/rows from the WebSocket URL, falling back to 24x80 when they
are absent or out of range, and the daemon creates the PTY at that
geometry. The component sends the size it measured before connecting.

Live resize is the follow-on: it needs a control channel on the WebSocket,
which today is a raw byte copy.
2026-10-09 13:07:29 +11:00
sam 71fa670512 fix(harness): keep the setup container alive with archie's own binary
A setup session started its container with "sleep infinity" and opened the
PTY with "sh -l". Neither binary is guaranteed: the spec capability whose
floor is a shell and bash is com.docker.sandbox/sbx@1, and archie's
supported map does not list it, so a Kit image need not provide either. A
missing sleep killed the container at start and a missing sh failed the
exec, both as an opaque error.

The container now runs archie-agent hold as its entrypoint. The agent
binary is archie's own and already mounted into every Kit, so the
keepalive needs nothing the image may lack and the container env stays
empty. Before opening the PTY, harnesssession probes for bash then sh and
returns ErrNoShell naming the Kit reference when neither is present.

Test: TestPickShell covers bash-preferred, sh-only, neither, and a probe
that cannot run.
2026-10-09 13:05:05 +11:00
sam d91ab1ab0f fix(channels): normalize stored settings and deduplicate save errors 2026-10-09 13:02:23 +11:00
sam 1eb05f0d24 test(ui): prune brittle checks and document agent rules 2026-10-09 12:51:57 +11:00
sam a49e939609 fix(ui): clean dependencies and add task table sorting 2026-10-09 12:46:05 +11:00
sam e76e2fd317 chore(lint): pin the linter to 2.14.0
The setup task is the only installer, so the pin follows the version in
use rather than holding it back, and CI follows the pin.
2026-10-09 12:32:05 +11:00
sam 2418a81a9e fix(egress): use context-aware dial and request in the token-endpoint test
net.Dial and httptest.NewRequest fail the noctx linter, so the gate was red
on the commit that added the test.
2026-10-09 12:27:45 +11:00
sam c4a441d1c3 chore(task): install the pinned tooling with task setup
task setup installs the golangci-lint CI pins, the protobuf generators and
the dashboard dependencies, and warns by name about the tools it cannot
install (Go, Task, Node, Docker).

The linter version now lives in one file read by both the setup task and
both workflows, so a local checkout and the gate cannot run different
linters.
2026-10-09 12:27:45 +11:00
sam c5c145f325 test(archieui): restore the archie-ui import-boundary check
Only the daemon owns containers, and the dashboard consumes a harness
session over its gRPC contract. Go imports are atomic, so a single
reference relinks a runtime, and the boundary holds only while something
re-measures it. cmd/archie-ui/architecture_test.go enforced this until it
was purged with the test suite; nothing enforced it since.

The restored check runs go list -deps . and fails if the dashboard links
internal/container, internal/app/archied or internal/agentexec. It is
transitive, which is what "links" means, and runs in the existing test
step.
2026-10-09 11:42:39 +11:00
sam 3683ce9082 fix(egress): refuse a token endpoint the run is not granted
forward intercepted a declared OAuth credential's token endpoint only when
the run was granted the service. For an optional credential it fell
through to the reverse proxy, so the provider's real access and refresh
tokens reached the container un-sentinelized, contradicting the harness
contract's "the real credential never enters the container".

A matched token endpoint is now refused when the service is not granted
(403 for an optional credential; a required one keeps its existing 502).
The table test drives forward against a recording upstream and asserts
both the status and that the upstream was never contacted.
2026-10-09 11:42:39 +11:00
sam 80dc6ec8d0 fix(deps): pin sandbox-kit-spec to the API the code is written against
The dependency bump moved sandbox-kit-spec from v3.0.0-m.6 to m.8 without
adapting the code, so the tree no longer builds: CredentialCapability.Phase
is now spec.Phases, not a string (internal/infrastructure/egress), and
Client.Assemble became a package-level fetch.Assemble that takes a Loader
and a LayerValidator instead of spec.MergeOptions (internal/infrastructure/
kitrun).

Migrating to m.8 is not a version-string change: m.8 pushes kit integrity,
safe layer extraction and resource limits onto the caller, so it is
security-relevant work, not an unblock. Pin back to m.6, which the code is
written against, and leave the migration to a deliberate change.

Verified: go build ./..., go vet ./..., go test -short ./... all pass with
this pin. The gate's ui:check and lint steps fail for unrelated
toolchain reasons recorded separately.
2026-10-09 11:42:33 +11:00
sam 12d6585586 ```
chore: update ui dependencies
```
2026-10-09 11:27:48 +11:00
sam 53916b0f96 chore: bump Go dependencies and toolchain 2026-10-09 11:23:04 +11:00
sam badbbf84bd fix(config): normalize default org for harness credentials 2026-10-09 10:01:35 +11:00
sam d98352d003 feat(settings): classify startup and live runtime settings 2026-10-09 09:57:57 +11:00
sam 542bd88040 feat(logging): aggregate recent service logs in dashboard 2026-10-09 09:57:57 +11:00
sam 81384939a2 fix(gateway): attribute chat settings to signed-in users 2026-10-09 09:57:57 +11:00
sam c8ed5619c6 fix(webui): explain personal token availability 2026-10-09 09:57:57 +11:00
sam 3b79155602 refactor(webui): remove unused configuration schema 2026-10-09 09:57:57 +11:00
sam 552ee93a47 fix(settings): show configuration reload failures 2026-10-09 09:57:57 +11:00
sam 7bf429b599 fix(gateway): read task logs through state store 2026-10-09 09:57:57 +11:00
sam 0792f0ba84 fix(ui): render unknown routes and correct status description 2026-10-09 09:57:56 +11:00
sam 02ab747ca9 fix(configuration): reject unknown conf.d files 2026-10-09 09:57:56 +11:00
sam c53a98ee87 feat(curators): edit and apply definitions live 2026-10-09 09:57:56 +11:00
sam 1e4aa8badc feat(settings): edit profiles bindings and playbooks 2026-10-09 09:57:56 +11:00
sam 1e76c99b48 feat(settings): show resource consumers and apply status 2026-10-09 09:57:56 +11:00
sam ff9b6c7196 feat(presence): report workers and broker on status 2026-10-09 09:57:56 +11:00
sam 7680dc5079 feat(presence): expose service dependency checks 2026-10-09 09:57:56 +11:00
sam d0370ed9f7 fix(daemon): inherit live settings for identity tasks 2026-10-09 09:57:56 +11:00
sam 7e3b3dbd78 test: verify enablement reports channel running 2026-10-09 02:24:47 +11:00
sam 6b71dc8108 fix(workflow): enforce optional result booleans only when required 2026-10-09 02:22:19 +11:00
sam 307f2fc9e2 fix(messaging): refuse failed channels as enablement success 2026-10-09 02:22:19 +11:00
sam 455de3d799 fix(workflow): retry a transient read while awaiting a callee 2026-10-09 02:21:49 +11:00
sam 4e74ed37b4 fix(workflow): preserve a reference's type between steps 2026-10-09 02:10:43 +11:00
sam 7ef58293be feat(harness): serve a daemon-side setup session to the dashboard
The dashboard's setup terminal was a 503: it had a WebSocket route, an
authorizer and an xterm.js surface, but nothing owned a container. The
daemon owns containers, so the session contract lands there and the
dashboard consumes it over a new gRPC contract.

One session concept, two targets. A setup session is addressed by Kit
profile and is ephemeral; a run session (archie-core-qi91) is addressed by
task and attempt and is bounded by the task. This slice serves setup and
answers Unimplemented for run.

The contract, the authorisation, the lifetime and the egress phase are
settled in docs/prds/external-agent-harness.md, "Session contract". The
short version: the daemon serves harness.v1.HarnessService; the dashboard
authorizes the operator as an update on the secret and then dials the
daemon with the harness service token, required even on loopback because a
session is a shell holding an org's credential; the setup container runs
no worker, mounts no worktree, holds a keepalive, and carries an empty
container environment. Install hooks run at the install phase and the
session enters runtime before the shell, so a runtime-phase credential's
token endpoint is the one the proxy intercepts.

Capture is gated by the egress proxy on a granted service, and a setup
session has no task, so the daemon registers a session grant: the
session's proxy token resolves to the org's bindings for the Kit's
declared services. The real token never enters the container: the token
endpoint response is sentinelized and stored as the org's harness secret.

Every teardown path releases the pool slot, revokes the egress session and
the grant, removes the sandbox network, and removes the session's volumes.
The listener requires HARNESS_TOKEN and stops with a 10s grace before
Stop, so an open session cannot hold shutdown to the watchdog leash.
2026-10-09 01:38:41 +11:00
sam 27c9647a13 fix(container): reap orphaned processes in Kit containers 2026-10-09 01:37:57 +11:00
sam 89541eb3b0 chore(lint): drop nolint directives that suppress nothing
29 of 59 directives did nothing. Removing each one individually and
re-running the gate revealed no issue from any of them: 20 named gosec,
which is not enabled in .golangci.yml and never has been, plus 4 nilerr
in functions that return no error, 2 dupl where dupl reports nothing
repo-wide, and one each of contextcheck, nestif and unused. The funlen
name on settings.go:147 is gone for the same reason; its gocyclo and
cyclop names are both live.

The unused directive in webui/authorize.go sat on `var _ = slog.Default`,
a statement that only existed to keep the log/slog import alive. Both go.

The 30 remaining directives all suppress a real issue.
2026-10-08 23:29:19 +11:00
sam 3a3a714cc4 fix(modelcatalog): never serve a disabled provider from the ambient key
disableProvider already cleared a failed provider's credential, but that
made it indistinguishable from a provider nobody configured, so
usableProvider fell back to the catalog's ambient env var (e.g.
OPENAI_API_KEY) and sent turns with a key the operator did not choose.
Mark the provider Disabled when its key fails to resolve, refuse it in
usableProvider, and carry the flag through mergeProviders so a catalog
refresh cannot resurrect it.
2026-10-08 22:59:23 +11:00
sam b107e4452a fix(webui): keep the dashboard token out of the startup log
DashboardURL no longer takes a token, so the startup line cannot embed
?t=<token> in the printed URL. The log now names the token file instead.
2026-10-08 22:57:28 +11:00
sam 2b514cb526 feat(scheduling): refuse a job payload that names a dangerous command
A scheduled job runs unattended, so a payload that restarts the daemon,
formats a disk or powers the machine down is refused when the job is
created rather than when it fires. scheduling.RefuseDangerousJob is the
one rule every creation path reaches: the dashboard, any control-plane
client and the config seed all replace the schedules document through the
same validator, so a new token is added in one place.
2026-10-08 22:45:28 +11:00
sam 630c30de79 fix(archiemessaging): apply channel enablement live 2026-10-08 22:44:15 +11:00
sam a69b3455d3 refactor(tools): back generate_video with ai-sdk's minimax video provider
Delete the hand-rolled MiniMax HTTP/poll client; ai-sdk v0.1.43 already
ships provider/minimax implementing video.Provider with the same endpoints,
defaults and poll semantics. The tool now takes a video.Provider and the
composition root builds it, matching the transcription and embedding
capabilities.
2026-10-08 22:42:49 +11:00
sam ddf8383784 fix(archiemessaging): recover a channel that fails on its own 2026-10-08 22:36:09 +11:00
sam c1bbeba18f fix(archied): wait for in-flight tasks on a single-cycle run
A drain pass no longer waits for the tasks it submitted, so -once (the
systemd timer and test invocation) returned while their containers were
still running and the process then tore them down. Wait for the pass's
tasks here, restoring what the flag means.
2026-10-08 22:31:07 +11:00
sam 1f99fb592e fix(daemon): let a run waiting on a callee release its capacity
A wait:true workflow.call run held its global slot and its repo's place for
the callee's whole life, and the drain pass waited for its own tasks, so a
callee queued by that pass was never claimed. With containers.max_concurrency
saturated, or a repo that does not allow concurrency, the wait could not end.

A drain pass now returns once the stream and the claim fallback are empty, and
shutdown waits for in-flight work once. Suspend/Resume give a run's slot and
repo place back while it waits on a callee, driven by the workflow call events
on the daemon's bus; a hold records one slot and one place, so a second
re-acquire gives back what it took.
2026-10-08 22:31:07 +11:00
sam aae01431b4 refactor(workflow): keep the call key change inside the lint gate
golangci-lint failed on the change and had not before: gofumpt wants
StartCall's same-typed parameters grouped, and runWorkflowCall reached a
cyclomatic complexity of 16. The unwaited call's early close moves into
closeUnwaitedCall on *TaskContext -- it needs only the call step, the
callee and the settings -- which leaves runWorkflowCall below the limit
with its behaviour unchanged.

The walk's id-less call case is deleted: ParseDefinition now refuses that
definition before validateWorkflowCalls runs, so it passed for the wrong
reason. The refusal is pinned where it happens instead, by the compile
case in TestWorkflowCallKeyIsTheDeclaredPath, now asserting the whole
message so it still names the step it refused.
2026-10-08 22:31:07 +11:00
sam 3c99f69fee fix(workflow): key a call on its callee, and free a terminal child's key
A call's key was the step's declared path alone, so one task running a
second definition at a colliding path -- workflow.handoff, human.approve
and a definition re-pin all change it -- was handed the first callee's
child, waited on the wrong workflow and published its outputs. The key
now carries the callee too, while the step row and the call's events stay
named and staged for the call site, so a rail pairing an event with its
step still attaches them.

A child that reached dead or closed_wont_do can never do the work and
holds no result the caller can use, so it leaves the call key's index and
frees the key for the caller's retry to start a fresh child. parked and
rejected keep theirs: a parked child is recoverable by retrying it, and a
rejected child ran.

The id a call step must declare is now refused where the definition is
compiled, which is also the path a pinned definition takes, so an id that
spells a step type is accepted again and no stage needs a heuristic.
2026-10-08 22:31:07 +11:00
sam b7fd13923a fix(workflow): key a workflow.call on its declared step path
A call site had no durable identity, so any retry of it -- a lost
EnqueueCallTask reply, a failed call-step record, a requeued attempt that
re-runs the stage -- started a second child and its work happened twice.

The call step's declared path within the run is that identity: wrapStep
sets it (branch-qualified, restored on return), a workflow.call step must
declare an id so two call sites cannot share one, and the key crosses
EnqueueCallTaskRequest.call_key into tasks.call_key, which EnqueueCallTask
upserts on so the retry returns the child already started.
2026-10-08 22:31:07 +11:00
sam 0a47a95cc3 fix(agentexec): enforce capture tool result schemas 2026-10-08 22:30:12 +11:00
sam ef8d9af469 fix(workflow): apply step retry and on_failure to command.run 2026-10-08 22:22:13 +11:00
sam 549f36a1f2 fix(ui): stop the command palette scrolling sideways 2026-10-08 21:58:22 +11:00
sam 187e6e81ee fix(ui): anchor the command palette and stop scroll stealing its highlight 2026-10-08 21:57:20 +11:00
sam e60ad551f0 fix(webhook): authorize delivery against the source's org 2026-10-08 21:43:28 +11:00
sam a0617ad437 test(postgres): derive the org fixture source from its insert 2026-10-08 21:40:24 +11:00
sam 411736fdaa fix(captures): keep count-retention inside the inserted capture's org 2026-10-08 21:27:54 +11:00
sam bea6567933 fix(captures): scope the capture list to the acting org 2026-10-08 21:26:07 +11:00
sam d6b693a9b2 fix(sources): store the acting org on source creation 2026-10-08 21:25:49 +11:00
sam b8bedf4d7b fix(capture): inherit source org on ingestion 2026-10-08 21:02:21 +11:00
sam 5c53dfb91b fix(workflow): resolve definitions in the owning org 2026-10-08 20:41:08 +11:00
sam e0cbbc0895 chore(release): v1.51.1
deploy / gate (push) Canceled after 0s
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
2026-10-08 01:42:29 +11:00
sam 40dd546564 fix(release): a dependency bump is releasable for every binary 2026-10-08 01:42:27 +11:00
sam b89d8cbab2 fix(deps): ai-sdk v0.1.43 sends gpt-6 tool calls through the Responses API 2026-10-08 01:41:44 +11:00
sam 4b62912343 chore(release): v1.51.0
deploy / gate (push) Canceled after 0s
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
2026-10-08 01:37:28 +11:00
sam 8a8c8cf7e9 feat(chat): the dashboard chat records voice, downloads files a turn sends, and offers /model and /personality choices 2026-10-08 01:37:21 +11:00
sam 201529414b fix(gateway): providers resolve again when a secret engine starts after boot 2026-10-08 01:34:55 +11:00
sam 3da1f918a4 chore(release): v1.50.1
deploy / gate (push) Canceled after 0s
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
2026-10-08 00:40:03 +11:00
sam f8d8e5b1e2 fix(update): the watchdog logs the health report it rolled back on 2026-10-08 00:39:57 +11:00
sam 826d4849df chore(release): v1.50.0
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
deploy / gate (push) Canceled after 33s
2026-10-08 00:25:35 +11:00
sam 0a18bfe21b feat(chat): the dashboard chat answers tool approvals and questions, and /update offers Install 2026-10-08 00:25:23 +11:00
sam 5976b94fbc fix(gatewayrpc): carry tool approvals and ask_user questions between a channel and the gateway turn 2026-10-08 00:22:37 +11:00
sam 698548d6ef chore(release): v1.49.4
deploy / gate (push) Canceled after 0s
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
2026-10-07 23:58:52 +11:00
sam d0584279e5 fix(ui): tabbed Status and Extensions, one Add MCP server, repos page renders without repos, save bar rests at the viewport edge 2026-10-07 23:46:34 +11:00
sam 62f248fd2c fix(ui): the Versions table's status column ends at the card's edge 2026-10-07 23:35:12 +11:00
sam 8f2750a266 chore(release): v1.49.3
deploy / gate (push) Canceled after 0s
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
2026-10-07 23:34:21 +11:00
sam 2ea7f7cd38 fix(ui): the release channel control sits at the Updates card's edge, not mid-row 2026-10-07 23:34:13 +11:00
sam 75b3810856 fix(archieui): the Versions card compares against the running daemon, so an available update can be installed 2026-10-07 23:29:03 +11:00
sam 30419532ba chore(release): v1.49.2
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
deploy / gate (push) Canceled after 1m51s
2026-10-07 23:18:11 +11:00
sam fff67838e0 fix(releaseupdate): read GitHub releases directly; drop go-selfupdate and its openpgp dependency 2026-10-07 23:18:03 +11:00
sam 15ebe24927 chore(release): v1.49.1
deploy / gate (push) Failing after 3m43s
deploy / archied-image (push) Skipped
deploy / agent-image (push) Skipped
deploy / dist-zip (push) Skipped
2026-10-07 23:10:38 +11:00
sam b2c1629925 fix(ui): an expired session reloads to the sign-in page instead of showing a banner 2026-10-07 23:05:52 +11:00
sam 0e8fcf70a0 chore(release): v1.49.0
deploy / gate (push) Failing after 5m18s
deploy / archied-image (push) Skipped
deploy / agent-image (push) Skipped
deploy / dist-zip (push) Skipped
2026-10-07 22:17:00 +11:00
sam 4673b435b7 fix(extension): confine egress only for packages that declare egress hosts 2026-10-07 22:15:06 +11:00
sam 1e062fd7f0 fix(releaseupdate): reuse a found release for ten minutes to stay under GitHub's unauthenticated rate limit 2026-10-07 01:17:21 +11:00
sam 74a3ec925c feat(releaseupdate): archied update check finds releases through go-selfupdate; archie-update-check is deleted 2026-10-07 01:12:11 +11:00
sam 4944ec8473 chore(release): v1.48.1
deploy / gate (push) Failing after 3m28s
deploy / archied-image (push) Skipped
deploy / agent-image (push) Skipped
deploy / dist-zip (push) Skipped
2026-10-07 01:00:30 +11:00
sam 204b65a0e3 fix(controlplane): update-settings selects a release channel; services run only the installed update scripts 2026-10-07 01:00:28 +11:00
sam cbedb8a504 chore(release): v1.48.0
deploy / gate (push) Failing after 5m4s
deploy / archied-image (push) Skipped
deploy / agent-image (push) Skipped
deploy / dist-zip (push) Skipped
2026-10-07 00:57:07 +11:00
sam a8dbab0cff feat(controlplane): update commands are an update-settings kind edited on Status, defaulting to the installed scripts 2026-10-07 00:57:01 +11:00
sam 789ff73fe9 fix(scripts): archie-update-install loads the archie env file so a shell run can back up the bundled database 2026-10-07 00:53:23 +11:00
sam 5176938e95 ci(deploy): build the archied and agent images in parallel so the release zip waits only on the agent image 2026-10-07 00:35:13 +11:00
sam 69a1ee677d chore(release): v1.47.3
deploy / gate (push) Failing after 3m29s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
2026-10-07 00:33:23 +11:00
sam b3cf2c59a8 fix(webui): extension Accept and Remove dialogs act on the selected extension 2026-10-07 00:32:44 +11:00
sam 8ebaeb6d38 chore(release): v1.47.2
deploy / gate (push) Failing after 5m8s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
2026-10-06 03:25:44 +11:00
sam ce58768e6b fix(webui): show real source endpoints and New source on the Inspector tab instead of a placeholder 2026-10-06 03:25:12 +11:00
sam d49918ae76 chore(release): v1.47.1
deploy / gate (push) Failing after 5m40s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
2026-10-06 03:05:39 +11:00
sam 8cb5391035 docs(news): regenerate for the corrected 1.47.0 notes 2026-10-06 03:04:35 +11:00
sam ab9db7cfe3 feat(install): bundled PostgreSQL has no network and is reached by Unix socket; print an AppArmor profile instead of disabling the userns restriction 2026-10-06 03:04:12 +11:00
sam 3d02d1d2d9 fix(install): do not start the services when the bundled PostgreSQL failed to start 2026-10-06 02:38:56 +11:00
sam e503263317 chore(release): v1.47.0
deploy / gate (push) Failing after 4m11s
deploy / build-and-push (push) Skipped
deploy / dist-zip (push) Skipped
2026-10-06 02:03:15 +11:00
sam a012f1ad37 feat(install): install from a verified release with curl | bash; ship docker-compose.yml in the release 2026-10-06 01:55:37 +11:00
sam 17b6fa7245 fix(setup): keep the generated database password out of config.toml 2026-10-06 01:55:37 +11:00
sam 1d02c7e3e6 ci: allow unprivileged user namespaces for extension confinement 2026-10-06 01:55:37 +11:00
sam 7892c927ce feat(setup): one guided flow; ask for PostgreSQL and generate the bundled database's password 2026-10-06 01:49:34 +11:00
sam 209f2b4adb docs: server quickstart, standalone template first, install starts PostgreSQL 2026-10-06 01:43:16 +11:00
sam 28bb4b4483 feat(storepkg): install packages from a signed default catalogue, listed on the Extensions page 2026-10-06 01:18:25 +11:00
sam 8d73280633 feat(telegram): /stop stops the chat agent, else the tasks it created, or one task; delete the dead approval actions 2026-10-06 01:12:28 +11:00
sam c654ba7cd1 fix(modelloop): mark reasoning models from the carried model limits, in the gateway and the agent worker 2026-10-06 00:57:20 +11:00
sam 0fc8535d87 fix(eda): name a source's delivery header in the dashboard instead of a built-in sender list 2026-10-06 00:54:20 +11:00
sam a355f13a03 fix(eda): dispatch each webhook delivery once, however often the sender retries it 2026-10-06 00:51:45 +11:00
sam cf34d03476 fix(release): push the release commit and its tag atomically 2026-10-06 00:50:12 +11:00
sam f9896f509d fix(webui): list services with the State Store marked down when it is unreachable 2026-10-06 00:48:45 +11:00
sam 9f3ad773cd fix(modelloop): feed the cached model catalog to the runtime so reasoning models get the right token parameter 2026-10-06 00:45:09 +11:00
sam c0586e465c fix(captureintake): decode any form-encoded webhook body to JSON 2026-10-06 00:37:20 +11:00
sam 4fd53d3f44 Reapply "fix(captureintake): unwrap form-encoded webhook payloads"
This reverts commit a9991f6d91.
2026-10-06 00:36:52 +11:00
sam a9991f6d91 Revert "fix(captureintake): unwrap form-encoded webhook payloads"
This reverts commit 378797ef6e.
2026-10-06 00:35:50 +11:00
sam e20860fcab chore(deps): bump ai-sdk to v0.1.42
Picks up the class-scoped request shaping fix: openai-compatible
transports keep max_tokens instead of receiving max_completion_tokens.
2026-10-06 00:24:55 +11:00
sam 378797ef6e fix(captureintake): unwrap form-encoded webhook payloads 2026-10-06 00:10:43 +11:00
sam f555b9171b fix(extension): confine each extension's network to its accepted egress hosts 2026-10-05 23:30:52 +11:00
sam 9c20a8f2e0 feat(ui): org switcher and new org for instance admins 2026-10-05 23:18:50 +11:00
sam 84050080a7 fix(archiegateway,agentexec,agentworker): rely on ai-sdk reasoning token selection
Bump github.com/samcharles93/ai-sdk v0.1.40 -> v0.1.41. ai-sdk now sends
max_completion_tokens for reasoning models and omits temperature when the
model rejects it, so the max_tokens workarounds are no longer needed: the
chat-turn bound is set directly and MCP sampling loses its reasoning
branch. Classic models keep their existing bounds.
2026-10-05 22:56:48 +11:00
sam 7a6603078a fix(ui): trim filler prose and expose appearance in settings nav 2026-10-05 22:20:16 +11:00
sam 07adab1eda feat(ui): org area with members, agents, workspaces, access and tokens 2026-10-05 22:09:42 +11:00
sam 7f2fd08840 feat(org): instance admins manage every org 2026-10-05 22:08:01 +11:00
sam 2d55f9ead2 fix(daemon): withdraw only issues the same dispatch rule found eligible and then lost 2026-10-05 22:04:41 +11:00
sam 9431201d32 feat(taskactions): merge pull request action from the task 2026-10-05 21:40:25 +11:00
sam 3a90225da1 fix(controlplane): report watch outages and align live/restart kind labels 2026-10-05 21:39:07 +11:00
sam 68d0fe9055 feat(ui): edit retry backoff and needs on the canvas 2026-10-05 21:32:30 +11:00
sam 0f0795e6f1 feat(eda): name and delete capture sources; an armed binding blocks the delete 2026-10-05 21:05:58 +11:00
sam 1628cbc312 chore(ui): rebuild dist after merging task log paging 2026-10-05 21:03:53 +11:00
sam b26de90e38 feat(webui): page through task logs 2026-10-05 21:03:08 +11:00
sam 087ce10b86 feat(webui): run details show inputs, outputs and workflow.call links both ways 2026-10-05 21:01:39 +11:00
sam 799632339f fix(ui): show step retries as archie's record, not the agent's report 2026-10-05 21:00:25 +11:00
sam bf73f96de5 feat(workflow): each remediation round names its number, cap and the review it answers 2026-10-05 20:58:05 +11:00
sam bfebdec1bf feat(daemon): record an approving review on the task's timeline 2026-10-05 20:56:13 +11:00
sam e084c55fcc feat(workflow): record each failed attempt of a retried step 2026-10-05 20:54:38 +11:00
sam 2998a2ed13 feat(workflow): later steps read a waited workflow.call's outputs as its result 2026-10-05 20:52:58 +11:00
sam 34077cb4ca feat(daemon): withdrawing an issue declines its queued or running work 2026-10-05 20:50:57 +11:00
sam 4295bf6e46 fix(webui): member changes need the admin grant and owner changes an owner 2026-10-05 20:49:58 +11:00
sam 955e366b9c fix(webui): the org-sys owner is the instance owner 2026-10-05 20:47:52 +11:00
sam d4d3a1ea7e chore(ui): rebuild dist after merging the org API 2026-10-05 20:45:36 +11:00
sam 2f8a91010f feat(org): org, workspace and membership API 2026-10-05 20:44:49 +11:00
sam 9f3e8285b5 feat(eda): pause and resume a binding; resuming goes back through approval 2026-10-05 20:44:25 +11:00
sam add33fb3d9 feat(daemon): the timeline names and links the binding and capture that started a task 2026-10-05 20:39:26 +11:00
sam 0df1c41362 fix(ui): offer resume only where the server accepts it 2026-10-05 20:37:38 +11:00
sam 35a23d5ca1 fix(workflow): refuse undeclared inputs and result fields at save 2026-10-05 20:35:50 +11:00
sam 0acf7981d9 feat(access): the dashboard operator is a person owning org-sys 2026-10-05 20:33:22 +11:00
sam abf3ae0ff9 refactor(archied): drop the unreachable multi-identity webhook skip; validation refuses it 2026-10-05 20:32:43 +11:00
sam 65fbb3e1aa fix(daemon): webhook forge intake does not poll for issues 2026-10-05 20:31:39 +11:00
sam 24c5fc86db fix(postgres): collect inline comments on a review queued behind a running remediation 2026-10-05 20:30:25 +11:00
sam 794b818f4c refactor(org): rename the default org to org-sys 2026-10-05 20:27:46 +11:00
sam 57660a19b5 fix(ui): restoring shipped workflows keeps custom ones 2026-10-05 20:27:38 +11:00
sam de6497dd14 fix(webui): admit dashboard work requests through the State Store and honour the workflow's repository mode 2026-10-05 20:25:20 +11:00
sam dd8729bcf7 feat(webui): page and filter the task list on the server 2026-10-05 20:21:51 +11:00
sam 8c81661e01 chore(ui): rebuild dist after merging workflow step recording 2026-10-05 20:20:40 +11:00
sam 261a50bc40 feat(workflow): record steps skipped by when as skipped 2026-10-05 20:20:23 +11:00
sam cf8868b744 feat(workflow): record parallel branch steps as their own steps 2026-10-05 20:20:22 +11:00
sam dff26fe98b feat(eda): record every terminal binding outcome and flag failing bindings 2026-10-05 20:17:52 +11:00
sam 83cc810e94 feat(eda): link binding dispatches to the captures and tasks they started 2026-10-05 20:16:02 +11:00
sam 1a26bf06b5 feat(taskactions): rejecting a pr_open task closes its pull request 2026-10-05 20:11:38 +11:00
sam 24df173a31 fix(workflow): validate handoff and approve targets at save 2026-10-05 20:09:59 +11:00
sam b38b3f6961 fix(workflow): validate workflow.call inside parallel branches 2026-10-05 20:09:59 +11:00
sam 47558078ce fix(daemon): refuse a disabled workflow on every start path 2026-10-05 20:08:18 +11:00
sam 2f6c53090e fix(daemon): record terminal non-dispatch outcomes so a capture is evaluated once 2026-10-05 20:06:45 +11:00
sam 01f9b5986b refactor(configuration): delete the dead runtime config overlay
The file overlay path has folded partial map-valued entries since
a9029411, answering xrux's open question: a decode that zeroes omitted
fields is the old behaviour, kept only by the now callerless runtime
overlay. Loader.ApplyOverlay, ApplyOverlayValues and
applySchedulingOverlay had no callers anywhere in the tree, so the fold
machinery stays and the dead runtime path goes.
2026-10-05 19:21:05 +11:00
sam d5e07333fa refactor(gateway)!: drop budget_key with the webhook chat channel 2026-10-05 18:10:41 +11:00
sam 515c2edf2f feat(messaging): serve MessagingService.Deliver and deliver chat schedules through it 2026-10-05 18:01:33 +11:00
sam 77723baf75 refactor(config): drop the unwired artifact sender and [artifacts] config
The artifactsync client had no importer and [artifacts] parsed but was never
read, so the capability was dead. Remove the package, the config field and
type, the token defaulting, and the example section. A leftover [artifacts]
key now reports as unrecognised, like any other removed key.
2026-10-05 17:16:32 +11:00
sam b9787cebbe feat(gateway): load SOUL into the chat prompt per turn
SOUL now owns the prompt identity slot via a per-turn source: a stored soul
resource wins once saved, otherwise the identity's SOUL file, then the
shipped default. The gateway watches the resource so a dashboard edit
reaches the next turn without a restart; a file read error degrades to the
default and logs once.

The persona prompt plumbing is replaced by the SOUL source; the persona
surface itself (registry, wire, page, commands) stays for archie-core-7ftt.
2026-10-05 17:14:20 +11:00
sam 9e4ec516c9 feat(releaseupdate): install from release artifacts with journaled rollback, topology check and channels 2026-10-05 17:02:29 +11:00
sam add2546e54 refactor(archieui): leave channel reload unserved by the gateway 2026-10-05 15:15:44 +11:00
sam 3f494b4247 feat(gateway): serve the dashboard skills and curators over ChatService
Add ListSkills, CuratorHealth and ReloadChannel to the gateway chat contract. The
Gateway process supplies its live skill catalogue and curator registry through a
Catalog seam; archie-ui adapts the RPCs to the webui view interfaces and wires
them in compose. The Gateway hosts no channels, so ReloadChannel answers
Unavailable here; the channel request surface is archie-core-np7l.
2026-10-05 15:05:09 +11:00
sam c73ff313ea refactor(config): drop unused dispatch state labels
The daemon stopped setting forge state labels when label-driven retry was removed; the config field, helpers and defaults had no consumer. Remove them and the Scheduling policy page's State labels section.
2026-10-05 15:05:06 +11:00
sam 886a151341 fix(webui): stop returning database_url from /api/config 2026-10-05 15:04:51 +11:00
sam 8ba067ce32 fix(ui): keep JSON copy inline on hover 2026-10-05 14:58:36 +11:00
sam e0db40963e fix(postgres): queue a review that arrives during a remediation
A review reaction that landed while a remediate run owned the task failed the
pr_open guard, was acked and dropped, and the poll cursor advanced past it.
Runs against one task are serialised, so the unit is appended to
tasks.pending_reviews instead; the transition that returns the task to pr_open
promotes the oldest waiting review back to queued. A re-delivered unit is
absorbed by payload equality, never queued twice.
2026-10-05 14:58:14 +11:00
sam 70322bd5fb fix(ui): load task debug reliably and copy JSON output 2026-10-05 14:54:12 +11:00
sam fe30a02072 feat(ui): select review gate findings before approval 2026-10-05 14:43:07 +11:00
sam 6a8481f203 fix(ui): reveal signing secret in canvas source creation 2026-10-05 14:33:27 +11:00
sam 22a4dcf46a feat(ui): bind an event to a workflow from its Start node
Pick a source and one of its captured events, map each declared input to a
payload path or a fixed value with a live preview, and save the mapping and
binding together. Existing bindings open from Starts when for editing and
approval; the Start node updates at once.
2026-10-05 13:20:55 +11:00
sam 6ee7321e6b feat(workflow): resume a parked run from a chosen step
Each finished stage records the run's step results; a retry may name a resume
point, and the next attempt skips the steps before it with their results
loaded. A run with a repository resumes only on its pushed branch. The canvas
offers Resume/Re-run from here on parked runs.
2026-10-05 13:06:30 +11:00
sam 1510c41254 feat(ui): inspect workflow step runs from canvas 2026-10-05 12:53:34 +11:00
sam 895a04047d feat(ui): drive workflows from the canvas: run a workflow, act on the watched run, edit workflow settings from the Start node; the canvas fills the viewport 2026-10-05 11:45:50 +11:00
sam c9099e6f04 docs: WORKFLOWS.md documents the workflow definition schema and step vocabulary 2026-10-05 11:37:51 +11:00
sam c76b973ea8 fix(ui): workflow page header is one tab row with save and a more menu; drop the ID field, step list, version footer and the meaningless origin pill 2026-10-05 11:29:16 +11:00
sam a8d0c82da7 feat(ui): canvas authoring by right-click menu and + insertion points; steps edit in a slide-in panel and show what they do 2026-10-05 01:23:58 +11:00
sam d12e46dc38 feat(ui): the canvas Start node lists what starts the workflow: issue routes, event bindings, playbooks and other workflows 2026-10-05 00:48:08 +11:00
sam e46eeb67dd feat(ui): build workflows on the canvas: step palette, schema-driven settings forms, references to earlier results, reorder and remove 2026-10-05 00:44:22 +11:00
sam 3072ba595f feat(controlplane): serve each step type's settings schema; the workflow editor checks settings before save 2026-10-05 00:39:47 +11:00
sam 720cd7a6f0 feat(ui): the workflow canvas watches a run live: each step shows its state, duration and error, and the view follows the step in progress 2026-10-05 00:34:06 +11:00
sam dfff9f6b11 feat(ui): workflow canvas renders each definition as a step graph with data edges, parallel branches and conditions 2026-10-05 00:27:32 +11:00
sam ae99b47581 feat(workflow): retries, parallel branches, review steps; every shipped workflow is YAML and the per-workflow step types are gone 2026-10-05 00:10:04 +11:00
sam eeccb2e995 feat(workflow): when conditions, handoff, human approval and forge steps; feasibility and triage ship as YAML 2026-10-05 00:06:35 +11:00
sam 4efb835eed feat(workflow): repository step types; implement and tdd ship as YAML in general steps 2026-10-05 00:04:34 +11:00
sam 880a898ecb feat(workflow): step ids, {{ }} references to earlier results, agent.run result schemas, workflow.finish and on_failure 2026-10-05 00:02:07 +11:00
sam fba2d4ee09 refactor(workflow): delete the bootstrap smoke-test workflow and its intake kind 2026-10-04 23:41:52 +11:00
sam 666a034202 fix(ui): drop the topbar nav's edge fade that clipped the first item 2026-10-04 23:13:07 +11:00
sam a5279bb187 feat(controlplane): serve the step vocabulary in the workflow-definitions schema; the editor checks step types against it 2026-10-04 23:00:14 +11:00
sam c885eb5bec fix(webui): drop the repository review switch the server no longer accepts 2026-10-04 21:01:52 +11:00
sam e45d69ef58 fix(webui): bind the container runtime document's keys, drop the blank Advanced page
ContainerRuntimePage still bound the Go field names the document carried
before archie-core-qna6 gave container-runtime-policies its own snake_case
shape. Every control read a key the document does not hold, so the fields
rendered empty and DurationInput warned on each mount; the page's Profiles
section wrote to a key the decoder drops. Bind image, max_concurrency,
max_uptime, volume_ttl, pull_policy and network, drop the dead Profiles
section (named profiles live in the agent-profiles resource, filed as
archie-core-x0wk), and pin the key list in a test the migration lacked.

Settings -> Advanced rendered nothing in any deployment: its only card needs
the sandbox dangerous-command authority, which has no implementation
(archie-core-sod1). Drop it from the sidebar, the router and the gateway's
dashboard page index; the page and its components stay in the tree for sod1.

Register CardAction in SetupPanel and EmptyDescription in TaskLogs, which Vue
was resolving to nothing, so the setup percentage and the log empty-state
descriptions render again.
2026-10-04 20:51:57 +11:00
sam a2a6ab3dfb feat(egress): the run credential is the proxy login; Kit secrets resolve per request from live grants 2026-10-04 19:35:26 +11:00
sam a5d747df72 fix(nats): containers log in with their run credential and reach only their task's subjects 2026-10-04 19:33:14 +11:00
sam 2aea980a01 refactor(forgerpc): identity RPC subjects are keyed by identity ID 2026-10-04 18:58:10 +11:00
sam 0e45001b2e feat(staterpc): every run start is audited by the State Store, or the run credential is withdrawn 2026-10-04 18:57:19 +11:00
sam e192308c90 feat(daemon): a workflow that names an identity runs as it; the dispatcher needs run on the workflow 2026-10-04 18:55:37 +11:00
sam 06b8aeebeb feat(controlplane): identity credential grants edited from the dashboard and applied live 2026-10-04 18:53:32 +11:00
sam cc5e0076af fix(forgerpc): forge calls need the run credential and reach only the run's own repository 2026-10-04 18:34:16 +11:00
sam 40d1062e08 feat(staterpc): one run credential per task, kept in the State Store, authorizes its store calls and its push 2026-10-04 18:32:45 +11:00
sam 56f2bf8a5d fix(archieui): a sign-in provider outage is a health issue, not a startup failure 2026-10-04 18:12:23 +11:00
sam 90399f5025 feat(identity): personal API tokens, created and revoked from the dashboard, act as their owner 2026-10-04 18:10:28 +11:00
sam b5edf2986e feat(contracts)!: requests no longer name their org; the State Store derives it from the caller 2026-10-04 17:28:31 +11:00
sam 1f01293f8c fix(controlplane): change history names kinds and reads only the caller's org 2026-10-04 17:25:47 +11:00
sam 7efc96bf70 fix(gatewayrpc): sender_id and rate_limited cross the chat wire 2026-10-04 17:18:38 +11:00
sam 5b3441c553 chore: delete the orphaned PR review benchmark 2026-10-04 17:17:20 +11:00
sam 5a3a693582 feat(skills): skill packages project into a skills resource the gateway reads live 2026-10-04 17:08:50 +11:00
sam 55bb4223c2 refactor(channels): webhook and email run only as extensions; their channel settings go 2026-10-04 17:04:21 +11:00
sam 0e580dd979 feat(channelext): chat channels served by extensions; messaging runs the enabled ones 2026-10-04 15:56:05 +11:00
sam 9ccfc020f7 feat(staterpc): the State Store derives org and actor from the principal archie-ui forwards 2026-10-04 15:54:22 +11:00
sam 755f367ca0 refactor(forge): github and gitea leave core; webhooks parse in the forge extension 2026-10-04 14:26:27 +11:00
sam 153dfc094c feat(forgeext): forge surface served by extensions; forge.type names the installed package 2026-10-04 13:56:32 +11:00
sam 37c6a71343 feat(controlplane): playbooks and agent profiles install from packages; the daemon reads eda-playbooks live 2026-10-04 13:49:03 +11:00
sam 9d7b8d9814 feat(staterpc): attribute State Store calls to the calling service; policy audit records it 2026-10-04 13:48:37 +11:00
sam b693065d09 style(access): adopt task fmt output 2026-10-04 13:44:04 +11:00
sam 3433bc7068 feat(access): instance network rules at the capture receiver; policies reload without a restart 2026-10-04 12:58:00 +11:00
sam be541d6aee feat(access): edit org, workspace and object policies from the dashboard; refuse owner lockout 2026-10-04 11:02:42 +11:00
sam 3a8879e6e9 fix(configuration): an overlay stands in for a missing config file; dev overlay is complete 2026-10-04 03:47:17 +11:00
sam b47e3a0b70 feat(archiemessaging): verify update reports against archied's presence and restore release announcements 2026-10-04 03:39:47 +11:00
sam 9a8c5722fa build(dev): task dev runs archie-messaging 2026-10-04 03:37:22 +11:00
sam 3b07bcb19f feat(presence): services card on the status page and archied status 2026-10-04 03:29:05 +11:00
sam d82651222a refactor(examples): the firewall workflow moves to archipelago 2026-10-04 03:10:23 +11:00
sam 647b9bcce7 chore: remove Yaegi
yaegiutil, the go.mod dependency, the .yaegi host-code entry and the legacy
guard stages for .archie/gate.go and .archie/stages are gone.
2026-10-04 03:08:46 +11:00
sam 2ae46582a8 refactor(skill): delete Yaegi skill scripts and the run_go_script tool
No shipped skill used plugins/. The agent request drops its Plugins field with
the staging code behind it.
2026-10-04 03:07:39 +11:00
sam 38219a7035 refactor(module): the log action is built in; delete the module loader and reconciler
module_dir, logextract and examples/modules go with the Yaegi loader. The plugin
reconciler had only the module directory left to watch, so it goes too.
2026-10-04 03:06:20 +11:00
sam 510172480b refactor(plugin): delete Yaegi daemon plugins and plugin_dir
Nothing consumed plugin.Plugin. The daemon's capability host held only those
plugins, so it goes too. The lint fix to the extensions access test rides along.
2026-10-04 03:04:35 +11:00
sam 785053c470 feat(presence): every service re-stamps a presence record in the State Store 2026-10-04 01:57:13 +10:00
sam f27aafbd66 feat(webui): install, accept and enable extensions from the dashboard 2026-10-04 01:56:10 +10:00
sam 5b42e4cba9 feat(storepkg): fetch packages from any registry, plain HTTP on loopback only 2026-10-04 01:53:00 +10:00
sam 1e435e9224 style: adopt task fmt output; regenerate contracts and sqlc code; gateway cleanup derives its context
goimports during the service refactors rewrote generated files; they are
restored from their generators.
2026-10-04 01:48:32 +10:00
sam a4317f2660 fix(configuration): bindings encryption keys must use the env engine 2026-10-04 01:46:16 +10:00
sam 7c011e8bf7 build(modelcatalog): read catalog metadata from ai-sdk/catalog
ai-sdk v0.1.40 moves the models.dev types into a dependency-free package, so
archied no longer links every provider client for catalog metadata.
2026-10-04 01:39:02 +10:00
sam 07d4fcb627 refactor(agentexec): model loop moves to agentexec/modelloop
agentexec's wire contract, harness adapters and log forwarding no longer
import the AI SDK; the in-process model loop, runtime, tool set and sampling
helpers that do now live in agentexec/modelloop, used by the Gateway and
archie-agent only.
2026-10-04 01:36:13 +10:00
sam 81f430de58 ```
chore: remove inline comments from update script
```
2026-10-04 01:33:18 +10:00
sam bf33ec9535 refactor(agentrun): agent stage contract moves to the domain layer
internal/domain/workflow imported internal/agentexec for its protocol types,
pulling the AI runtime into every binary that touches workflow types. The
request, result and runner contract now live in internal/domain/agentrun;
agentexec keeps the runtime. The model catalog cache moves from servicekit
into modelcatalog and WaitForPeer into staterpc, so archie-state-store and
archie-messaging no longer link the AI runtime.
2026-10-04 01:33:00 +10:00
sam c486fe291c refactor(archieplaybooks): fold archie-playbooks into archied playbooks lint|serve 2026-10-04 01:20:33 +10:00
sam 7d795fdd4f docs(deployments): service data ownership; start order no longer matters 2026-10-04 01:17:48 +10:00
sam 794c7ac8c6 fix(services): services wait for peers instead of exiting; restarted broker keeps its endpoint
State Store calls from the daemon, Gateway and Messaging wait for the store to
come up, so start order no longer matters; the daemon's state_db probe carries
its own deadline so an outage reports degraded instead of hanging. The
Gateway retries its first NATS connect. A restarted daemon reuses the embedded
broker's previous port and token, so the Gateway reconnects instead of
holding a dead address. Fixes a nil catalog the catalog move introduced.
2026-10-04 01:15:11 +10:00
sam d8d6d7318b chore(lint): depguard keeps each service's packages to its own composition 2026-10-04 00:59:54 +10:00
sam e0701b18a3 refactor(archiegateway): own package for the Gateway service
archie-gateway no longer links the daemon, the web UI or archied. Shared
runtime layering, watches, catalog, NATS discovery and the State Store client
live in servicekit; chat task profiles in chattask. The Gateway waits for the
daemon's NATS endpoint instead of starting a second broker, and chat
approvals go through the task-action client instead of a local service with
no daemon behind it. Version stamping uses buildinfo only.
2026-10-04 00:59:02 +10:00
sam 9dd39c9d24 refactor(archied): gateway owns model work; daemon drops chat runtime, tools, memory and curators
The gateway now applies provider, model-role and tool settings live and
runs the curators, which wake on its turns and read its conversations.
2026-10-04 00:48:28 +10:00
sam bf1a4ec6d7 refactor(statestore): own package for the State Store service; access reset moves to archie-state-store 2026-10-04 00:46:11 +10:00
sam 0754c5e0da docs(archied): drop secret engines from the plugin reconciler comment 2026-10-04 00:43:59 +10:00
sam 1936d9c353 feat(secretengine): serve secret engines as go-plugin extensions
A secret engine is now a subprocess serving secretengine.v1, installed through
the package store's new extensions family and enabled by extension-settings.
bws leaves the binary, as do the Yaegi engine loader and its examples.
2026-10-04 00:40:23 +10:00
sam 44695b1846 docs: services own contracts; failure stays local 2026-10-04 00:32:58 +10:00
sam 35e72d81ff chore: ignore archipelago marketplace symlink 2026-10-03 23:20:13 +10:00
sam 7e98ca254c chore: remove obsolete gitignore entries
The diff only trims three ignore rules (`.impeccable/`, `.serena/`, `/site/`) and their associated comment from `.gitignore`, so a single subject line captures the whole change.
2026-10-03 23:07:24 +10:00
sam 6078dc1565 docs: constitution review edits; state the wiring rule without naming a file 2026-10-03 22:38:44 +10:00
sam 75988204d5 docs: strip doc and issue references from config, deployments and examples 2026-10-03 22:27:08 +10:00
sam 1a3fbe042e docs: remove verbose comments from Dockerfiles 2026-10-03 22:19:49 +10:00
sam cb6b8618c2 refactor: cut remaining long comments down to what the code does 2026-10-03 22:06:57 +10:00
sam 0cbb65c684 refactor(setup,messaging,container,agentworker,discovery,memory,eventbus): cut comments down to what the code does 2026-10-03 22:02:57 +10:00
sam e10980dc33 refactor(postgres,mcp,archieui,task,prreview,playbook): cut comments down to what the code does 2026-10-03 22:01:54 +10:00
sam 3360cddb5a refactor(staterpc,releaseupdate,agentexec,storecontract,worktree): cut comments down to what the code does 2026-10-03 22:00:43 +10:00
sam c30844180b refactor(controlplane,messaging,logging): cut comments down to what the code does 2026-10-03 21:59:35 +10:00
sam 4ebde6b315 refactor(configuration,builtin): cut comments down to what the code does 2026-10-03 21:58:23 +10:00
sam 58150a920d refactor(daemon): cut comments down to what the code does 2026-10-03 21:57:24 +10:00
sam 5719cd51cb refactor(config): cut comments down to what the code does 2026-10-03 21:56:41 +10:00
sam d0fd78e6a9 fix(archied): restore contextcheck directives and drop unused adapter 2026-10-03 21:55:48 +10:00
sam c167358118 refactor(telegram): cut comments down to what the code does 2026-10-03 21:55:00 +10:00
sam 7cf0db7e9a refactor(webui): cut comments down to what the code does 2026-10-03 21:54:14 +10:00
sam 4d00884ea5 refactor(gateway): cut comments down to what the code does 2026-10-03 21:53:24 +10:00
sam 239cde9c2b refactor(workflow): cut comments down to what the code does 2026-10-03 21:52:21 +10:00
sam 030b4ed176 refactor: strip doc and issue narration from code comments
Remove PRD/doc paths, bead IDs, phase notes and deleted-test references
from comments; drop test-only hooks left by the test deletion. Includes
in-progress archied bootstrap, gateway and query changes.
2026-10-03 21:47:46 +10:00
sam a8a118c1b8 chore: cut agent governance to a single constitution
Replace CLAUDE.md with a short decision-rule constitution; move PRDs,
architecture, development and design docs and repo skills out of the tree;
delete the docs tooling (docsgen, prdlint, docdrift, docsite, contractaudit,
reachaudit) and its gate steps; stop install.sh copying repo skills into
runtime skills.
2026-10-03 21:47:46 +10:00
sam 780bc44d82 refactor: testing from the beginning. a journey in 150k lines of tests to none 2026-10-03 21:16:25 +10:00
sam f0fe550a35 fix(build): restore the go fix fixpoint, and give the formatter one owner
A "reduce Taskfile bloat" refactor (0d35e753) removed the fixpoint loop from
task fmt and deleted the guard test that proved it, putting the tree back to a
single go fix pass with nothing left to notice. One pass is not a fixpoint:
stditerators rewrites `for i := range t.NumFields()` into a field iterator that
copies its loop variable, and forvar only deletes that copy on the following
pass, leaving a tree copyloopvar rejects. archie-core-wwho regressed silently.

Restore the loop and the guard. The deploy workflow has always inlined its own
single `go fix ./...`, which is how the same hazard reached CI as a spurious
git-diff failure rather than a lint error (archie-core-6kda); it now calls task
fmt, the one owner of the formatter sequence, and its guard rejects an inline
copy so the split cannot come back.
2026-10-03 02:28:33 +10:00
sam 152c8b85a2 fix(tools): resolve docdrift citations against the tracked tree
The gate resolved a citation with a filesystem stat, so a directory left behind
by a checkout that removed its files -- internal/gate and internal/gate/gateeval
among them -- resolved on the developer's machine and did not exist in CI. The
baseline was generated that way, so it passed locally and failed CI on the same
commit, which is the state a gate must never be in.

Read the tracked tree from git ls-files and resolve against that: a tracked
file, a directory containing tracked files, or a file-shape template matched
against tracked siblings. Failing to read git is fatal rather than a fallback to
the filesystem, because the fallback is the bug being fixed.

Regenerate the baseline, which now records the citations the filesystem check
was masking. Verified by running the tool in a clean worktree at HEAD: identical
counts to the working tree, exit 0.
2026-10-03 02:24:01 +10:00
sam 0d3ec4f127 fix(controlplane): an absent MCP server field inherits the file value
The layering rebuilds cfg.Tools from the control plane's projection wholesale,
and ParallelToolCalls was a plain bool. A tool-settings resource seeded before
the field existed therefore carried no key for it, the zero value replaced the
operator's file-level parallel_tool_calls = true, and the setting was inert --
on exactly the stores that cannot be re-seeded, which is the case a new field
has to reach.

Make it a *bool: the shape schedulingPolicy.Label documents, and the shape the
mcp headers in this same function already use. Absent now means "leave the
file's value in force", an explicit stored value still outranks the file, and a
server with no file entry has nothing to inherit and keeps the zero value.
2026-10-03 02:20:06 +10:00
sam 703692ca7a feat(workflow): add the command.run step type
archie-core-ndm8 accepted the command-step trust decision, so a stored
workflow definition may run operator argv. The workflow engine has exactly one
call site -- agentworker, which is what the container agent serves -- so the
step runs on the container path by construction. A non-zero exit parks the run;
level: warn makes it advisory.

Settings mirror the repository gate's command shape (name, argv,
expect_failure) so a command means the same thing in both places. The settings
type is local rather than agentexec.Command because that struct carries JSON
wire tags only, and YAML decoding silently dropped expect_failure -- a command
declared to fail would have been reported as passing. A reflection test holds
the two shapes together.
2026-10-03 02:07:45 +10:00
sam 8f8e732b3a fix(configuration): make bot_user required, defaulted, and named
bot_user names the agent that chat turns and the session curator attribute memory
to. The loader requires it of a single-identity deployment, but nothing covered
the two paths between that requirement and the consumers.

local-ollama-standalone.toml set no bot_user and defined no [[identities]], so a
profile AGENTS.md lists as supported could not load at all (archie-core-cx0d).
Give the profile the field, and make the regression guard enumerate
deployments/*.toml through the production loader instead of naming two files, so
a profile added later is covered the moment it is committed. dev.toml is
excluded because it is a development overlay layered over an installed config
rather than a standalone profile, and the exclusion is itself checked so a
renamed overlay is noticed instead of silently widening the rule.

The root BotUser was validated only when no [[identities]] block was present, so
a config with exactly one identity left it empty: the curator then skipped every
session with "no agent id" while the chat turn path ran with the same empty agent
(archie-core-4slp). applyIdentityDefaults now adopts a sole identity as the root
single-identity values -- which is what those fields mean -- and leaves the root
alone when two or more identities leave no single answer. The skip reason now
names bot_user, so the remaining case reads as configuration rather than as a
data problem.

Both regressions were red-first: the enumerated profile test failed on
local-ollama-standalone.toml before the profile was fixed, and the sole-identity
test failed before applyIdentityDefaults adopted it.
2026-10-03 01:48:28 +10:00
sam 61ecc14327 fix(webhookguard): verify uppercase-hex HMAC signatures
VerifyHMAC compared the supplied signature against the computed digest as
case-sensitive hex text, so a sender that emits an uppercase digest failed
verification -- and the failure is indistinguishable from a wrong secret. The
helper is shared by all three inbound surfaces (forge intake, the chat webhook
gateway, capture intake), so one such sender breaks whichever surface it
targets.

Decode both sides to raw bytes and compare those. hex.DecodeString accepts
either case, and comparing digests rather than their text keeps the comparison
constant-time -- strings.EqualFold over the encoded text would not be. A
signature that is not valid hex is rejected outright, and a digest of the
wrong length simply does not match.

archie-core-rl04
2026-10-03 01:44:17 +10:00
sam 66167571cb feat(tools): fail the gate when docs cite a path that no longer exists
docs/architecture is declared authoritative for settled design, so a page that
cites code which has moved actively misleads every session and every subagent
brief that reads it. Nothing in the gate compared a prose citation against the
tree: docsgen checks the contract schema against Go types, docsite checks
generated artifacts against their Markdown sources, prdlint checks PRD writing
style. All three verify internal consistency, so a page can describe a package
deleted months ago and every check stays green -- which is how a page describing
a removed system survives behind a hand-written "removed" banner.

Add tools/docdrift. It resolves every internal/... citation under docs/ against
the tree and fails on one that dangles, handling the shapes prose actually uses:
a package with a symbol (internal/config.Config), a test with its package
(internal/app/archieui/TestFoo), a file-shape template
(internal/webui/api_<concern>.go), and a Go package pattern (internal/...).
Generated artifacts are skipped so embedded page bodies are not double-counted.

The baseline is a burn-down list of the 48 citations already broken -- packages
that moved (internal/store, internal/memory, internal/nats) and ones never built
(internal/policy, the image and research capability docs). It is not a licence:
the check also fails when an allowlisted citation starts resolving again, so an
exemption cannot outlive its reason. Regenerate with `docdrift list`.

Wire it into `task check` as docs:drift.

Also correct AGENTS.md, which listed `policy` among the cross-cutting packages
sitting under internal/. No such package has ever existed in this tree; the
design is approved and unbuilt (docs/architecture/policy.md). That is exactly
the class of stale claim this check now catches.
2026-10-03 00:31:06 +10:00
sam aacec67c24 docs: delete the superseded adversarial review document family
The adversarial self-review system was removed in 625ead95, but four pages
describing it survived: the architecture page, its design-decision PRD, and the
two superseded calibration/operator PRDs. The architecture page carried a
hand-written "removed, not shipped" banner and was kept only because live PRDs
linked to it, so every reader paid for a system the tree no longer has.

Delete all four and repoint the live referrers at the authority that replaced
them (docs/prds/pr-review-agent.md): inline-review.md's Builds-on line,
pr-review-remediation.md's isolation-contract citation, pr-review-agent.md's
supersede clause, CLAUDE.md's contributor rule, and three Go comments that cited
the deleted paths. Regenerate docs/data/generated/dev-docs.json.

History stays in git; the tree stops describing a system it does not have.
2026-10-03 00:01:42 +10:00
sam 0adc165c4c fix(webui): navigate the Events chain once, not twice
The page drew the same three panels twice: a numbered Capture/Map/Bind
strip and, directly under it, a tab list naming Inspector/Mappings/
Bindings. Both drove the same `?tab=` through the same handler, so the
page read as one wizard drawn twice and named the same three panels with
two different vocabularies in a single view.

The strip survives. It names each step for what the operator does to it
rather than for what the panel holds, and it is the one that reads as a
chain. The step words move to tab-selection.ts as stepsFor(), beside the
rules they belong to; the URL keeps its ids.

Making the strip the only navigation also fixes a latent fault. It
listed all three steps unconditionally, so a composition the server
refuses `mappings` still drew a Map step with no panel behind it, and
clicking it fell back to the first available tab, which did nothing.
stepsFor() returns exactly the tabs this composition can back, and the
page renders an empty state when that is none of them.

ui/dist rebuilt in the same commit: the Go build embeds it.
2026-10-02 23:08:41 +10:00
sam 483f50d030 fix(storepkg): mask the tar mode to the permission bits before narrowing
The conversion is now exact rather than a truncation: the low nine bits are the permission bits whatever the tar header's width.
2026-10-02 22:45:07 +10:00
sam 27d9d7b397 fix(forge): refuse a review line number that does not fit an int
Gitea reports a review comment position as a uint64. Past the int range the conversion wrapped negative and would reach a reviewer as a line that cannot exist. Refused instead, with a test that fails when the guard is made inert.
2026-10-02 22:45:06 +10:00
sam eb624e53c6 fix(webhook): set a ReadHeaderTimeout on the forge webhook receivers
Both listen on the network without a header-read bound, the slowloris surface. Matches the timeout the other daemon servers already carry.
2026-10-02 22:45:02 +10:00
sam 9d7a7df496 fix(app): assign the temp-file close result on the error path
Each atomic-write helper returned the write error while silently dropping the close result. The success path already checks it.
2026-10-02 22:45:02 +10:00
sam c4b2bf5db7 chore(skills): give the diagnostics scripts their own build constraints
Both are standalone programs run by name from one directory, so the package could never build as a unit. The diagnostics skill invokes each file explicitly.
2026-10-02 22:45:01 +10:00
2132 changed files with 83526 additions and 221050 deletions

No files matched your search

-247
View File
@@ -1,247 +0,0 @@
---
name: archie-agent-fleet
description: >-
Run a bounded fleet of coding agents across archie-core's backlog without
flooding review. Load when fanning work out into parallel lanes, waves,
worktrees or subagents on this repository; when a lane worktree dies with the
unknown-agent error for `cp-writer`; or when deciding what every lane call must
carry, which gate evidence to demand, and how a lane's scoped test command
should be shaped here. Carries archie-specific fleet facts only; the method
lives in the user-scope high-throughput-programming skill.
---
# Run an agent fleet on archie-core
This skill carries the facts about _this repository_. It deliberately does not
restate the process.
## Where the method lives
The how is the user-scope skill `high-throughput-programming` at
`~/.agents/skills/high-throughput-programming/`: doctrine, pipeline shape, the
interview that scaffolds a run, the pi-subagents ceilings and traps, `scripts/`,
`templates/` and `references/`. Read its `INTERVIEW.md` before scaffolding a run;
never scaffold one from memory.
**Precedence.** That skill is normative for method; this one is normative for
archie's facts. If they disagree about the process, it wins. If they disagree
about this repository — a path, an invariant, a gate — this one wins, because the
method skill is repository-agnostic by construction.
Route runtime facts to `archie-run-and-operate`, toolchain facts to
`archie-build-and-env`, and dependency/boundary rules to
`archie-architecture-contract`.
## Invariants every lane call must carry
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.** 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
```bash
~/.agents/skills/high-throughput-programming/scripts/gate-evidence.sh \
<worktree> '<scoped test cmd>' <base>
```
Run it on the host, per lane. It executes the scoped tests, then a module-wide
build (`go build ./...`) and the linter (`golangci-lint run ./...`), and emits
JSON for the harness to use as the child's structured output.
The two extra checks are required, not optional. `go test ./pkg/...` compiles
only that package, so a changed constructor signature or interface passes its own
lane and breaks the next package to merge. That shape has bitten twice here: one
lane changed a constructor's signature, passed its own gate, and failed three
packages the moment it merged; formatting and lint drifted the same way, and only
the repository gate saw it. Both failures are paid for inside the lane when the
gate runs the build and the linter, and at merge when it does not.
Gate the **candidate** before `main` moves. Check the merge candidate out
detached — or gate the lane branch — and advance the ref only on a green result:
gating after a fast-forward lands the failure on the branch of record and leaves
only fix-forward or reset as exits. The lane brief must name the linter as well,
`golangci-lint run ./<package>/...` beside the scoped tests, because a scoped
test run cannot see a complexity or style limit and `task check` is where that
failure otherwise surfaces — once it is already merged.
A copy of the script under `.pi/control-plane-run/` is that run's disposable
state and may lag the skill's version. The skill's copy is the one to trust.
## Shape a lane's test command like this
Name every package the change can reach, plus `go vet` on the same set:
```bash
go test ./internal/app/controlplane/... ./internal/domain/applystatus/... -count=1 \
&& go vet ./internal/app/controlplane/... ./internal/domain/applystatus/...
```
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/...` |
`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.
"Never two at once" includes gates you did not start. More than one agent session
works in this checkout, so before the merge train gates, check who holds it:
```bash
ps -ef | grep -E '[t]ask check|[t]ask ' | grep -v grep
```
A concurrent gate is not merely slow. Both runs regenerate
`docs/data/generated/contracts.json` and `ui/dist`, so a contended result is
worthless in either direction — neither run's verdict tells you anything about
the tree. Wait for the host to be quiet and bound the wait: still held after
about twenty minutes means report the contention rather than gate anyway.
The train integrates **local** `main`. Nothing in the gate consults `origin`, and
the version stamp comes from `git describe --tags` against local tags, so
unpushed commits neither block nor invalidate a gate run — the remote can lag
and does, since the maintainer pushes when inclined.
## The agent-discovery trap
A lane worktree is a **sibling** of the repository (`/work/apps/cp-<lane>`), not a
directory inside it. pi discovers project-scope agents under `<cwd>/.pi/agents/`,
so a child launched in a lane worktree does not see them and dies with
`Unknown agent: cp-writer`.
Fix it once per worktree:
```bash
mkdir -p /work/apps/cp-<lane>/.pi
ln -sfn /work/apps/archie-core/.pi/agents /work/apps/cp-<lane>/.pi/agents
```
`.pi/` is gitignored, so the worktree stays clean and the symlink cannot reach a
commit. This costs an hour to rediscover.
## Peer sessions over intercom
A fleet here can also run as **sibling sessions** coordinated over `intercom` —
a peer per lane — rather than pi-subagents children under one orchestrator.
These facts are peer-specific, and each has cost a real run.
- **Name the channel in the brief.** A peer's knowledge of how to report lives in
its context, not its configuration. Write "report to <peer> over intercom" as
an instruction; a convention that is only assumed evaporates.
- **A compaction erases conventions, not just facts.** A peer that compacts
mid-task keeps its task state and loses its transport: it reverts to
addressing its operator, and the coordinator reads that as idleness or death.
**Peer silence is not evidence of either** — ask for a one-line ack over the
channel before concluding anything. Re-priming restores the channel; the
transport itself survives compaction intact.
- **Match the task's shape to the session's window, not its strength.** A sweep
over hundreds of items needs the largest window available; a bounded hard
artifact (a PRD, a conformance review, a design decision) belongs in a smaller,
reasoning-strong session. A wide task in a small window stalls the task — too
wide is not the same as too hard, and it is the coordinator's assignment error,
not the peer's failure.
- **Checkpoint at ~70%, never compact mid-task.** A terse ledger sent to the
coordinator before the window fills survives; one reconstructed afterwards
loses exactly the identifiers — bead IDs, exact counts — that made it worth
having. Instruct every long-running peer to report and stop there.
- **One writer per resource.** Exactly one session writes the tracker. Two
writers produce double-closes, contradictory verdicts, and counts nobody can
reconcile. When a sweep changes hands, the successor re-derives them rather
than inheriting the predecessor's ledger as fact.
## Traps worth carrying
- **`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
`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.
Adding or editing a page under `docs/` — a PRD included — changes
`docs/data/generated/dev-docs.json`, which gains or loses a page: regenerate it
and commit it in the same commit, or `docs:artifact:check` fails. That failure
lands on `main`, not in the lane, if the ref moves first.
- **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
merge train's scope is its own lanes' files, and nothing else.
## codegraph answers symbol questions cheaply
The maintainer's `codegraph` MCP server indexes this repository. Prefer it to
grep or whole-file reading for "who calls X", "is this dead", "what does this
change touch": it enumerates call sites that a grep only summarises, and labels
each caller's confidence so interface fan-out is not mistaken for direct calls.
- **`pr_impact <base> <head>`** lists changed symbols with per-symbol caller and
test counts. Read `interface_dispatch` and the inferred tests alongside
`test_count`: a method reached through an interface reports a low direct test
count while many indirect tests reach it, and the compact line alone invites
the wrong conclusion.
- **It is a derived cache.** `scip-go` and tree-sitter rebuild it, and a query
indexes the revisions it names, so a cold query is slow and losing the index
costs a rebuild rather than data. `list_repositories` reports the indexed
revision — compare it with the tree before trusting a default-revision answer.
- **Stagger heavy queries.** Concurrent sessions share one instance, and
**name-based** `symbol_context` is what locks: it returns `database is locked`
or times out, while the same symbol **by id** returns immediately. Query
serially and retry rather than assuming a hang.
- **Report problems one line at a time** in
`/work/apps/codegraph/data/feedback.jsonl` — one JSON object per line, keys
`date`, `repo`, `task`, `tools`, `helped`, `missed`, `wrong`, `slow`. A raw
newline inside a string makes the line invalid and breaks every reader; a
multi-line entry corrupted that file once. Validate, append, never rewrite.
## Tracker conventions
`bd` is the only tracker; no markdown TODO lists, no local trackers.
```bash
bd show <id> # before working an item — the brief may describe a tree that has moved
bd update <id> --claim
bd close <id> # after the work lands, not when it commits
```
Bead state moves through Dolt, never through git commits on this repository. The
Dolt remote is pushed explicitly (`bd dolt push`) and never assumed to be in sync.
## Run artifacts are evidence, not documentation
`.pi/control-plane-run/` holds a run's scaffold, lane plan, prompts, scripts and
gate output. It is gitignored and disposable. Treat it as run evidence only: a
fact worth keeping goes into this skill or `docs/`, not into a
run directory the next clean deletes.
## Worked example
`references/worked-example/` is the control-plane backlog run of September 2026,
committed verbatim: the filled orchestrator prompt, four lane briefs, three
sub-prompts, and the three agent definitions with their project invariants
inlined. Read it for the level of detail a good brief carries.
Its scripts are the snapshot's, not the current ones. The user-scope skill's
`scripts/` and `templates/` are normative and win any disagreement.
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Agent Fleet"
short_description: "Run bounded agent fleets on archie-core"
default_prompt: "Use $archie-agent-fleet to fan work out across lanes on this repository, carrying the fleet invariants, the gate evidence it needs, and the worktree agent-discovery fix."
@@ -1,474 +0,0 @@
# Mission: clear the archie-core control-plane backlog with a bounded high-throughput fleet
> **Where this file's paths point.** This is the committed copy of a live run.
> Paths under `.pi/control-plane-run/` (sections 6, 9, 10) name that run's own
> disposable copies of `wave0.js`, `wave2.js`, `review.js` and
> `gate-evidence.sh`; they are gitignored run state and may lag the skill's
> normative versions in `~/.agents/skills/high-throughput-programming/`. The
> skill is the one to trust. Paths under `/work/apps/archie-core` and
> repo-relative source paths are unchanged.
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
`docs/architecture/organisation.md` before Wave 1.
---
## 1. Hard rules
1. **One top-level `subagent` call per wave.** Every child launches inside that
call's `workflowScript`. Never open a second top-level orchestration while a
wave is running.
2. **Read-only fans out wide. Writers do not.** Recon and review children are
cheap and parallel. Writer children are bounded by file overlap and by this
machine (16 cores), not by the spawn budget.
3. **At most one `task check` at a time, ever.** It compiles 117 Go packages,
runs the full test suite and the Node dashboard tests, and saturates the
machine. Writer children run package-scoped tests only. The full gate belongs
to the merge train in Wave 4, which is strictly serial.
4. **A worker's report is not evidence.** Accept a lane only on: the handoff
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.
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.
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.
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.
Writers write, reviewers review, and you alone run the merge train. You do
not write production code; if you find yourself editing a lane's files, the
lane was scoped wrong.
12. **Every wave ends with an adversarial review pass** before the next wave
starts. Reviewers are read-only, parallel and cheap; a defect caught at the
end of the wave that produced it costs one lane, and the same defect caught
three waves later costs the tree.
---
## 2. Ground truth: do not spend agents rediscovering this
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.
- **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.
- **`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`.
- 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
database is authoritative for channel settings. File config is not a fallback.
- **The control plane fails closed with no way back.** A stored value that will
not validate stops `archied` starting. Nothing bypasses the control plane at
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.
- **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`
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
hook; `core.hooksPath` is `.beads/hooks` and those are beads shims.
---
## 3. The backlog
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 |
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.
- **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`.
- **eju6 proves the others.** It goes last, against everything merged.
---
## 4. Models: resolve before Wave 0
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. |
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
limited child, it keeps its context and recovers.
---
## 5. Concurrency: the numbers that actually bind
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.
- `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
is why the mission is split into waves rather than one giant script.
- `runs.lanes` is capped at 32 lanes, 16 stages per lane, 64 stages total.
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 |
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.
---
## 5a. The constraint is review, not generation
Generation is no longer the bottleneck and has not been for a while. The
measured evidence is consistent: agent-authored changes take far longer to reach
a first review, merge at a lower rate than human-authored ones, and raise more
issues per change; one randomized study found experienced developers 19% slower
with agent tooling while expecting to be faster. Feature-branch throughput rises
while main-branch throughput falls. Adding writer lanes past what review can
absorb does not raise throughput, it grows a queue, and queued work ages badly
because the tree moves underneath it.
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 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
whether it is correct.
- **Spend the effort on the verifier, not the prompt.** A parallel fleet is only
as good as the check that decides whether its output is right. A better test
is worth more than a better instruction.
- **Every handoff carries evidence.** Intent, non-goals, files touched with a
reason each, alternatives rejected, commands actually run with pasted output,
the test that would fail first, and known limitations. A report that only
describes its own diff is not evidence.
- **Deterministic gates run before any reviewer looks.** `gate-evidence.sh` runs
the lane's tests on the host and emits JSON that becomes the child's
structured output, and it fails the lane on added `//nolint`, `t.Skip`, ignore
build tags, removed tests or removed assertions. Gate gaming is cheap to
detect and expensive to miss, so detect it mechanically rather than asking a
reviewer to notice.
- **Keep batches small.** Generation being cheap is a reason for smaller
changes, not bigger ones. A lane whose diff passes roughly 400 changed lines
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.
- **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
how fast the queue fills.
---
## 6. Wave 0: recon fanout (read-only, wide)
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.
Per bead:
- **spec** — extract the exact PRD clauses the bead must satisfy, with line
anchors, and the acceptance criteria the gate can actually check.
- **blast** — trace every call site, consumer and test of the symbols the bead
names. Return package paths and file paths, not prose.
- **tests** — inventory the tests that already cover this surface and name the
one test that would fail first if the change were wrong.
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.
- **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.
- **contract-pairs** — find every place the validating side (State Store) and
the executing side (archie-agent) must agree on the same vocabulary, and name
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.
**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.
---
## 7. Checkpoint A: lane plan, then stop
Build the conflict matrix from the `overlap` probe and the per-bead `blast`
results. Two beads may be concurrent writers only if their file sets are
disjoint. Directory names are not evidence of disjointness: check the imports.
Then report to Sam, in under 30 lines:
- the matrix, as bead by bead package intersections;
- the proposed lanes, and which beads you are deliberately serializing;
- any bead whose description no longer matches the tree, with the commit that
moved underneath it;
- the measured gate cost and the timeouts you derived from it;
- anything in Wave 0 that contradicts section 2.
Wait for approval before Wave 1. This is the only mandatory stop.
---
## 8. Wave 1: shape-first, serial
Land the shared shape before anything forks against it. Five workers each adding
a field to one struct produced eight cleanup commits on this repo in July; the
merge cost scales with shared-file overlap, not worker count.
Sub-prompts for both children are in `prompts/wave1.md`.
1. **fwmp** alone: one `cp-writer`, `worktree: true`, red-green, gate
`go test ./internal/domain/workflow/... ./internal/app/controlplane/... ./internal/app/agentworker/...`.
Requirement: one contract test asserting the validating registry and the
executing registry resolve the same step vocabulary. Two sides that each pass
their own tests and disagree with each other is the exact failure this bead
exists to prevent.
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 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.
---
## 9. Wave 2: bounded writer lanes
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 |
Stage contract, enforced by `wave2.js` and the `cp-writer` agent definition:
- **red**: write the failing table-driven test first, run it, and paste the
failure. Verify the failure comes from an assertion, not a compile error. A
test that cannot fail for an interesting reason is noise in the gate.
- **green**: minimal implementation that satisfies the failing test.
- **self-gate**: a typed `gate` pointed at
`.pi/control-plane-run/gate-evidence.sh`, which runs the lane's package-scoped
test command on the host and returns JSON that becomes the child's
`structuredOutput`: branch, sha, changed files, uncommitted files, test exit
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.
Each lane's writer also returns the evidence handoff in `wave2.js`: intent,
non-goals, files with reasons, alternatives rejected, commands run with pasted
output, the test that would fail first, and known limitations. A lane whose diff
passes roughly 400 changed lines stops at a coherent boundary and reports what
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.
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.
---
## 10. Review after every wave
`.pi/control-plane-run/review.js`, read-only `cp-reviewer` children on a
different model family from the producer, one child per angle per target. The
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` |
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,
and its write-up reads confident either way. Feed the audit the claims your lane
plan is about to rest on, and check the load-bearing ones before Checkpoint A,
not after.
Reviewers label findings P0/P1/P2 by evidence, not by severity language, carry
`file:line` with a quoted proof, and end with one of `Merge verdict: BLOCK`,
`Merge verdict: OK`, `Merge verdict: OK with notes`. Prose is never parsed for
control flow: you decide the lane's fate from the findings.
Fixes go back to that lane's retained writer, batched into one pass, not one
child per finding. Resume only a writer `children.list` reports as `resumable`;
otherwise start a same-role fallback and label it as a fallback. A second failed
fix on the same logic block means the lane is reverted and requeued, not patched
again.
Count the pass as complete only when every angle returned. A missing angle is an
unreviewed axis, not a clean one.
---
## 11. Wave 4: merge train, strictly serial
The procedure, with the exact commands, is in `prompts/wave4-merge-train.md`.
One branch at a time, in dependency order, in the captain checkout at
`/work/apps/archie-core`. Per branch:
1. `git merge-base --is-ancestor main <branch>`. A stale branch computed its
deletions against code that has since changed; rebase or re-derive, never
merge it as is.
2. Apply the lane's handoff patch.
3. `task check`, once, alone. Nothing else runs while it does.
4. On failure: one fix pass through the lane's writer with the real output. On a
second failure, revert the lane and requeue it; do not stack a third patch.
5. Commit with a conventional scope (`feat(controlplane): ...`,
`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.
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
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.
---
## 13. Final report
- Beads closed, with the commit that closed each one.
- Beads deliberately not attempted, and why.
- `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.
- Anything you found that contradicts `docs/prds/runtime-control-plane.md` or
section 2 of this prompt, filed as a new bead.
- New beads for identified debt or follow-ups, filed via `bd`.
- The wave metrics: per wave, reviewer findings raised versus accepted, lanes
blocked by the gate versus by review, rework passes per lane, and wall-clock
from lane start to merged. Say which stage was the constraint in practice and
whether it matched the prediction that review would be.
- The risk-routed surfaces that changed and need Sam's eyes: the fail-closed
boot path, the State Store wire contract and error sentinels, grants and
credentials, anything touching `archie.db`, and the release or CI surface.
@@ -1,43 +0,0 @@
# Worked example: archie-core control plane, September 2026
A real run, frozen partway through, kept verbatim so the shapes can be read
rather than re-derived. It is repository-specific on purpose: the value is in
seeing how much project knowledge a good brief carries.
**Its scripts are the snapshot's, not the current ones.** This directory was
captured mid-run, so the scripts in it predate fixes the skill's own lessons
describe — the typed-gate boolean trap, the post-fix re-gate and re-review, the
P2 handling, the build and lint checks in the gate.
`~/.agents/skills/high-throughput-programming/scripts/` and
`~/.agents/skills/high-throughput-programming/templates/` are normative; if this
directory disagrees with them, they win. Read the briefs, the lane plan and the
merge-train procedure here. Do not copy the scripts.
The method this run followed lives in the user-scope skill
`~/.agents/skills/high-throughput-programming/`; it is normative for method. This
repository's `archie-agent-fleet` skill is normative for facts about archie-core.
A run in another repository uses that skill's `templates/` plus its own filled-in
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. |
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`,
`templates/review.js` and `scripts/gate-evidence.sh` in the user-scope skill;
those are normative, and this directory's stale copies were deleted so there is
exactly one of each to keep current.
What this run's Wave 0 actually caught, which is the argument for recon before
fanout: three of the seven items had premises that no longer matched the tree,
including one whose target file did not exist under the name the item used, one
whose anchor had moved commits earlier, and one whose scope could not reach the
clause it cited. All three would have produced confidently wrong lanes.
@@ -1,105 +0,0 @@
# Control-plane backlog run: how to drive it
This is the committed copy of a real run. Its originals lived in
`/work/apps/archie-core/.pi/control-plane-run/`, which is gitignored, disposable
run state whose live copies may have moved on since. Nothing here is load
bearing at runtime.
The method is not here. The pipeline shape, the concurrency ceilings, the
pi-subagents traps, and the `scripts/` and `templates/` this file names all live
in the user-scope skill `~/.agents/skills/high-throughput-programming/`, and that
skill is normative for method. This copy is normative only for what the run
looked like on this repository; the archie-specific facts themselves live in the
parent `archie-agent-fleet` skill. A run in another repository uses that skill's
`templates/` plus its own filled-in briefs.
## 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. |
## Start it
```fish
cd /work/apps/archie-core
pi "$(cat .pi/control-plane-run/00-orchestrator.md)"
```
The `.pi/control-plane-run/` path is the run's own state directory, not this
copy. Interactive is the right mode here: Checkpoint A after Wave 0 is a real
stop and wants you in the loop. `/subagents-fleet` opens the live inspector,
`/subagents-doctor` checks the install.
## Before Wave 2
Create the durable worktrees yourself. Managed `worktree: true` children capture
a patch and then remove the worktree, which a resumed challenge stage cannot
edit, so the lanes use operator-created worktrees plus per-child `cwd`.
```fish
for lane in live recovery steps config
git -C /work/apps/archie-core worktree add ../cp-$lane -b cp/$lane
end
```
A lane worktree is a **sibling** of the repository, so `.pi/agents/` inside the
repository is not discovered from it. Link it per worktree or the children fail
with `Unknown agent: cp-writer`:
```fish
for lane in live recovery steps config
mkdir -p /work/apps/cp-$lane/.pi
ln -sfn /work/apps/archie-core/.pi/agents /work/apps/cp-$lane/.pi/agents
end
```
Then fill `model` in `lanes.json` from what `subagent({ action: "models" })`
resolves, and pass it as `args`.
## Ceilings worth knowing before you tune anything
This install is `pi-subagents` **0.70.0**, matching your clone except for four
doc files. Two 0.69/0.70 features are load bearing here: typed gates
(`gate: { command, output: "json" }` turns a host command's JSON stdout into the
child's `structuredOutput`) and `allowedAgents`, which can stop a reviewer
launching a writer if you want separation of duties enforced rather than
instructed.
- `globalConcurrencyLimit` defaults to **20**, not 64. Set it per top-level call.
- `maxSubagentSpawnsPerRun` defaults to **64** cumulative admissions per run
tree, never refunded, so retries spend it. Each wave is a separate top-level
run precisely so each gets its own budget.
- `runs.lanes` caps at 32 lanes, 16 stages per lane, 64 stages total.
- `gate` is rejected on a retained `resume` item, which is why the challenge
stage runs its tests through `bash` instead.
- A typed gate cannot be combined with `outputSchema` on the same child, so the
writer stages carry the gate and the reviewers carry the schema.
- Host steps have no per-step `cwd`, which is why `gate-evidence.sh` takes the
worktree path as its first argument instead of relying on one.
## Why the fleet is not 64 writers
64 concurrent children is comfortable for read-only work and pointless for
writers here. Two limits bite first:
1. **Overlap.** Merge cost scales with shared file overlap, not worker count.
Seven beads reduce to four genuinely disjoint lanes plus one shared shape
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 serialised
into the merge train and writers run package-scoped tests.
The throughput comes from recon and review: 25 recon children, then a review
pass after every wave at up to 36 children, all read-only, all cheap, all
genuinely parallel. The writers stay at four because that is what the
repository's coupling and the review pass can absorb. The measured literature is
consistent that review, not generation, is where agent-heavy pipelines stall, so
spare concurrency goes into checking rather than into more lanes.
@@ -1,39 +0,0 @@
---
name: cp-recon
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
completionGuard: false
inheritProjectContext: true
inheritGlobalContext: false
inheritSkills: false
thinking: high
systemPromptMode: replace
---
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.
- 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.
Finish with your structured output. Keep prose under 40 lines; long inventories
belong in your output file.
@@ -1,48 +0,0 @@
---
name: cp-reviewer
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
completionGuard: false
inheritProjectContext: true
inheritGlobalContext: false
inheritSkills: false
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.
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.
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.
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.
End with exactly one line: `Merge verdict: BLOCK`, `Merge verdict: OK`, or
`Merge verdict: OK with notes`.
@@ -1,55 +0,0 @@
---
name: cp-writer
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
inheritGlobalContext: false
inheritSkills: false
thinking: high
timeoutMs: 5400000
systemPromptMode: replace
---
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.
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.
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): ...`).
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.
- 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`.
- 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.
- 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.
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.
@@ -1,38 +0,0 @@
{
"model": "REPLACE_WITH_STRONG_TIER_ID",
"timeoutMs": 5400000,
"lanes": [
{
"key": "live",
"dir": "/work/apps/cp-live",
"branch": "cp/live",
"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."
},
{
"key": "recovery",
"dir": "/work/apps/cp-recovery",
"branch": "cp/recovery",
"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."
},
{
"key": "steps",
"dir": "/work/apps/cp-steps",
"branch": "cp/steps",
"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."
},
{
"key": "config",
"dir": "/work/apps/cp-config",
"branch": "cp/config",
"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,73 +0,0 @@
# Wave 1 sub-prompt: shape first
**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 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`
```text
Bead archie-core-fwmp. Run `bd show archie-core-fwmp` first.
docs/prds/runtime-control-plane.md:95 says plugins can add step types. Today every
call site hardcodes workflow.BuiltinStepRegistry():
internal/app/agentworker/task_execution.go:319 and :335,
internal/app/controlplane/workflow_definitions.go:26 and :33, and
internal/app/controlplane/client.go:41. The step vocabulary is closed to the six
shipped workflows.
Verified by the Wave 0 claims audit, so treat as fact and do not re-derive:
- Those are exactly five non-test call sites, plus five test call sites.
- BuiltinStepRegistry() is defined at internal/domain/workflow/definition.go:149 and
is built only from legacyBuiltinWorkflows() (definition.go:181).
- StepRegistry is a plain `map[string]StepFactory` (definition.go:32). There is no
merge/widen function; BuiltinStepRegistry() is itself the only registration site.
- All five production call sites pass the identical function, so nothing diverges
today. The gap is the absence of a guard, not a live defect.
Deliver: a registry assembled from the plugin set, resolved identically on both
sides.
The load-bearing constraint is not the extension point, it is agreement. The
validating side is the State Store; the executing side is archie-agent. A
definition that validates and then fails to compile at run time is the failure
this bead exists to prevent, and it is exactly the failure two packages that each
pass their own tests produce. No test today ties the two sides: no test file
imports both internal/app/controlplane and internal/app/agentworker. Your change
is not done until one test asserts that both sides resolve the same step
vocabulary from the same plugin set. Write that test first and let it fail for the
right reason.
Do NOT edit internal/domain/workflow/definition_test.go:8
TestParseDefinitionRejectsUnsafeDefinitions. The audit established it is not an
obstacle: its pin is name-exact ("shell" at :11, implement.prepare's own factory at
:12), so a settings-bearing plugin step type under any other name passes it
unchanged. Adding a step type is archie-core-8szi's lane, not this one.
Do NOT fix the workflow-version pin opportunistically. The audit found it is never
persisted over gRPC and its digest guard is dead in production; that is filed as
archie-core-zf8h and gets its own lane and Sam's eyes. Report it if you touch it,
do not repair it here.
Before adding a plugin engine surface, satisfy
ARCHITECTURE.md#plugin-engine-rule-strict.
This is the shape every other lane branches from, so it lands alone and it lands
first. Do not implement any step type; archie-core-8szi does that afterwards
against what you build. Do not widen scope to the .archie gate behaviour.
Working contract: print pwd, git branch --show-current and git status --short
before editing and repeat them in your report. Red then green. Package-scoped
tests only, never `task check`. No //nolint, no t.Skip, no deleted assertions.
Adopt `task fmt` verbatim. Commit on cp/shape with a conventional subject.
```
@@ -1,66 +0,0 @@
# Wave 4: merge train
Serial. You run this yourself in the captain checkout at
`/work/apps/archie-core`. No subagent owns `main`, and only one `task check`
exists at a time.
Order: `cp/shape` (already merged in Wave 1), then `cp/config`, `cp/live`,
`cp/recovery`, `cp/steps`. Config goes early because it owns the bootstrap path
the others boot through.
## Per branch
```bash
BR=cp/live
git -C /work/apps/archie-core status --short # must be clean
git merge-base --is-ancestor main $BR && echo "stale: rebase required"
git log --oneline main..$BR
git diff --stat main..$BR
```
A branch that predates a merge computed its deletions against code that has
since changed. On this repo a stale branch's diff deleted 460 lines of
`internal/config` that read as tidy relocation and would have reverted another
lane's decomposition. Rebase it or re-derive the work. Never merge a diff whose
deletions were computed against code that has moved.
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).
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
patch, and do not fix it yourself unless the fix is one line and obvious.
4. Commit generated assets in the same commit. `ui/dist/` and schema outputs are
LAW: never regenerated away, never reverted, never left out.
5. `bd close <id>` for each bead the branch delivered. Do not stage `.beads/`,
and never create a commit whose only content is beads bookkeeping.
## Landing check, every time
```bash
git log --oneline -3
git branch --no-merged main
git log --oneline origin/main..main
```
Done has three states: no commits, committed and unmerged, merged. Only the
third counts. A closed bead is what a worker believed, not what landed.
## Your own edits
A coordinator `sed` rename on this repo once produced `&fakeStore{fakeStore{` in
six places and broke the build. Your edits get the same gate as the children's,
and nobody else reviews them.
## Do not push
Sam pushes manually and does not always announce it. Report what is unpushed as
fact. If `git log origin/main..main` is long, say how long; do not act on it.
@@ -1,53 +0,0 @@
# Wave 5: eju6, the end-to-end restart test
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.
```text
Bead archie-core-eju6. Run `bd show archie-core-eju6` first.
docs/prds/runtime-control-plane.md ("First implementation") lists an end-to-end
restart test as a deliverable and there is none.
internal/app/controlplane/controlplane_test.go covers seeding and catalog only.
No test drives a change through the API, restarts a process, and asserts the
change survived.
Deliver that test: a real end-to-end check, not a unit test, and not a rewrite
of the existing file.
It must, in one test:
1. write a settings change through the control-plane API, as the dashboard
would, attributing to identity.SystemID;
2. observe the change land in the audit trail as an ordinary edit;
3. restart the process that consumes it;
4. assert the process came back on the stored value, not the file value;
5. assert the apply-status row for that process reports the version it
applied, and that a record older than 90 seconds reads as "not reporting"
rather than as current.
Facts you need and must not re-derive:
- boot.runtimeConfig is the single layering call, and the SIGHUP reload makes
the same call over the document it just resolved (9af013eb). A reload cannot
revert a database-owned setting to its file value, and that is the property
under test.
- Execution budgets arrive on a watch, not a resource query, so boot records
the last settings it applied and the reload re-applies them from there.
- PutApplyStatus/ListApplyStatus are administrative on the State Store
contract: a task-scoped grant is denied both by the deny-by-default arm of
authorizesTaskScopedCall. Your harness needs the administrative token.
- Rows are keyed on (process, kind) and replaced in place; every process
re-stamps every 30 seconds.
- The control plane fails closed: a stored value that will not validate stops
archied starting.
If the test fails, that is a finding about the feature, not about the test.
Report the failure with the output and stop. Do not weaken an assertion, do not
add a retry loop to paper over a race, and do not mark it t.Skip.
If a real end-to-end restart cannot be driven in-process, say so explicitly and
describe what harness it would need, rather than substituting a unit test that
asserts less and claims the bead.
```
@@ -1,246 +0,0 @@
---
name: archie-architecture-contract
description: >-
Protect Archie's load-bearing architecture while placing, implementing, or
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
behaviour has one authoritative path. Route proof of duplication, dead-code
disposition, production reachability, and maintainability to
archie-technical-accountability.
---
# Archie Architecture Contract
Treat architecture as executable safety policy. Preserve one understandable
owner and one production path for each behaviour.
## Read status before code
| 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
> used from a production entry point. As of 2026-09-18 `internal/domain/`,
> `internal/eventbus/`, `internal/infrastructure/`, and `internal/app/` exist;
> `internal/policy/` does not, and `internal/domain/{agent,identity}` remain
> APPROVED TARGET only.
Resolve apparent disagreement in this order:
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 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.
Route to `archie-domain-reference` for glossary and
`archie-config-and-flags` for config enumeration.
Two skills this document routes to are parked outside this checkout, under
`/work/apps/archie-skills-parked/`: `archie-technical-accountability` and
`archie-architecture-planning-campaign`. If your session has not loaded them,
treat each routing target as a manual escalation step rather than a live skill.
Also: `cmd/archied/main.go` is a thin dispatcher; the wiring lives in
`internal/app/archied/`.
## Know the CURRENT system
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 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
Use these CURRENT status values:
```text
queued, running, waiting_human, pr_open, merged,
parked, dead, rejected, closed_wont_do
```
The intended flow includes queue/claim, workflow stages, human wait/resume, PR
reconciliation, parking/retry/exhaustion, and crash recovery. Read
`internal/domain/workflow/task/task.go`, `internal/daemon/daemon.go`, and
`internal/domain/workflow/workflow.go` before changing a transition.
`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/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 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/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:
```bash
go test ./internal/plugin -count=1
```
## Apply the APPROVED TARGET
Apply ownership rules to migration plans and new seams. Not CURRENT until
production wiring proves the cutover.
### Keep dependency direction inward
```text
domain and shared application contracts <- infrastructure implementations
^
|
application composition
```
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.
3. Let only `internal/app` choose concrete implementations and connect domains.
4. Keep `cmd/*` limited to process input and invoking composition.
5. Use an owned command, event, or approved shared contract across domains.
6. Never let one domain mutate another domain's state or call its internals.
Sources: `docs/architecture/organisation.md`,
`docs/architecture/dependencies-and-contracts.md`.
### Separate interaction, admission, assistance, and execution
```text
channel-neutral Message -> Agent turn -> optional proposed work
-> Work Intake -> AcceptedWorkRequest -> Workflow selects version -> WorkflowExecution
```
- **Messaging** owns canonical messages, conversations, branches, channel correlation, delivery.
- **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.
Do not equate external issue/message with WorkflowExecution; do not let Work
Intake create one directly.
Sources: `docs/architecture/migration-decisions.md`,
`docs/architecture/agent-system.md`, `docs/architecture/messaging-and-work-intake.md`.
### Separate identity, Agent, conversation, and memory
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 authorised Agents |
| Agent-user relationship | Exactly one Agent and one user |
Do not use conversation branching as a fifth memory scope.
Sources: `docs/architecture/identity.md`, `docs/architecture/agent-system.md`,
`docs/architecture/migration-decisions.md`.
### Dissolve global runtime configuration
Treat `internal/config` as migration source inventory:
- move file/env/overlay/secret decoding to `internal/infrastructure/configuration`;
- 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 behavioural value as invariant, runtime setting, policy value,
derived value, or runtime state.
Source: `docs/architecture/configuration.md`.
## Place new behaviour deliberately
| 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/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. |
Trace with evidence:
```bash
rg -n '<constructor>|<interface>|<method>' cmd internal
go list -deps ./cmd/archied | rg 'github.com/samcharles93/archie-core/internal/'
gopls references path/to/file.go:<line>:<column>
```
Use `gopls references` or another AST-aware reference query when interfaces,
embedding, generated symbols, or same-named methods make text search ambiguous.
Trace from `cmd/archied/main.go` into `internal/app/archied.Run()`; the wiring
itself is in `internal/app/archied/bootstrap.go`.
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Architecture Contract"
short_description: "Protect Archie load-bearing architecture decisions"
default_prompt: "Use $archie-architecture-contract to place and review this change without violating current or target architecture."
@@ -1,251 +0,0 @@
---
name: archie-build-and-env
description: Recreate, inspect, and troubleshoot Archie Core's development, build, test, documentation, and container toolchains. Use when onboarding a checkout; diagnosing Go, Task, golangci-lint, gofumpt, Docker/Compose, NATS, GPG, cache, temporary-directory, listener, or network failures; comparing local work with repository automation; or proving which build surfaces a command actually covers. Load this before running task check in an unfamiliar or restricted environment because that gate rewrites files and omits several independent surfaces.
---
# Build and verify the Archie environment
Recreate the environment as independently verified surfaces. Do not turn a
passing root-module command into a claim that the tools module, documentation
site, race detector, linter, or container images also passed.
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 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:
```bash
sed -n '1,240p' CLAUDE.md
ls docs/architecture/
task --list
```
## Inventory requirements before installing anything
```bash
go version
go env GOTOOLCHAIN GOVERSION GOOS GOARCH CGO_ENABLED GOTMPDIR GOCACHE GOMODCACHE
task --version; golangci-lint version; gofumpt -version
node --version; npm --version # UI only; docs need no Node toolchain
docker --version; docker compose version
git --version; gpg --version
```
Classify a missing command as an environment prerequisite. Bootstrap (verified
2026-09-19): Go ≥ 1.27.0, Task ≥ 3.x, gofumpt v0.11.0, golangci-lint 2.13.2,
Node 24.x for the `ui/` frontend.
`task fmt` runs `go fix` and then `golangci-lint fmt`; `task lint` uses the
same binary and `.golangci.yml`, so its gofumpt, goimports, and gci rules have
one owner and the writer converges the checker. Standalone `gofumpt` remains
only for generated protobuf contracts in `tools/proto.sh`.
The three Yaegi secret-engine examples carry `//go:build ignore`. goimports
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. |
## Prepare writable caches in a restricted sandbox
```bash
go env GOTMPDIR GOCACHE GOMODCACHE GOPATH
df -T /tmp
```
If any default is read-only:
```bash
export ARCHIE_GOTMPDIR=/tmp/archie-core-gotmp
export ARCHIE_GOCACHE=/tmp/archie-core-gocache
export ARCHIE_GOMODCACHE=/tmp/archie-core-gomodcache
export ARCHIE_GOPATH=/tmp/archie-core-gopath
export ARCHIE_LINT_CACHE=/tmp/archie-core-golangci
mkdir -p "$ARCHIE_GOTMPDIR" "$ARCHIE_GOCACHE" "$ARCHIE_GOMODCACHE" \
"$ARCHIE_GOPATH" "$ARCHIE_LINT_CACHE"
```
Prefix Go commands:
```bash
env GOTMPDIR="$ARCHIE_GOTMPDIR" GOCACHE="$ARCHIE_GOCACHE" \
GOMODCACHE="$ARCHIE_GOMODCACHE" GOPATH="$ARCHIE_GOPATH" \
go test ./internal/config/... -count=1
```
Populate cold cache only with network authorised:
```bash
env ... go mod download; env ... go -C tools mod download
```
## Recreate the root Go surface
```bash
test -f go.mod && test -f cmd/archied/main.go && test -f cmd/archie-agent/main.go
go list -m
go build -o /tmp/archie-core-archied ./cmd/archied
go build -o /tmp/archie-core-agent ./cmd/archie-agent
go test ./internal/config/... -count=1
go vet ./...
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 -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
data and never renders anything: there is still no documentation build.
Two of its steps check committed artifacts rather than the build, so both fail
on work that is correct but unstaged, and both read as a broken generator:
- `proto:check` regenerates, then runs `git diff --exit-code -- internal/contracts`
and rejects untracked files there. After any `.proto` edit,
`git add internal/contracts proto` before the gate. The failure prints the
regenerated diff, which looks like generation produced something unexpected.
- `ui:check` compares `ui/dist` against a fresh build of `ui/src` and fails when
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 authorised writable worktree. For a read-only ordinary-source
preview, use `golangci-lint fmt --diff`.
## Verify the tools module separately
No `go.work`. Root `go test ./...` does not enter `tools/`.
```text
module github.com/samcharles93/archie-core/tools
replace github.com/samcharles93/archie-core => ../
```
```bash
go -C tools test -mod=readonly ./... -count=1
```
`-mod=readonly` is mandatory on every `go -C tools` command. The `replace`
forces the tools build list to satisfy the root module's requirements, so a
root dependency bump leaves tools stale, and a writable command repairs
`tools/go.mod` and `tools/go.sum` in place, dirtying the tree with an
unrelated diff. Pass the flag explicitly: a global `GOFLAGS=-mod=mod` in
`go env` beats the toolchain default. A failure here means run
`go -C tools mod tidy` and commit that on its own. `task check` runs this via
`task test:tools`.
Generate documentation to temp file:
```bash
go -C tools run -mod=readonly ./docsgen --repo-root .. --out /tmp/archie-core-contracts.json
cmp --silent docs/data/generated/contracts.json /tmp/archie-core-contracts.json
```
2026-09-18 run wrote 11 schemas. The committed output was stale since
`4b340d2b` and was regenerated the same day; `cmp` now passes. `task docs:check`
now runs inside `task check`, so this drift fails the gate instead of waiting to
be found by hand. `docsgen all` does not exist yet.
Prefer the task over the raw commands:
```bash
task docs:check # non-destructive; fails loudly and names the Go type
task docs:generate # rewrites the committed artifact; review the diff
```
## Documentation needs no build
`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 (`docs/.vitepress/`, `docs/package.json`, the pnpm lockfile),
its landing page, and `.github/workflows/docs.yml` were removed on 2026-09-12 as
an unnecessary build step. Git no longer tracks any `docs/node_modules` entries.
Do not `pnpm install` under `docs/`; it has no package manifest. See
`docs/architecture/generated-documentation.md`, "Rendering and publishing".
Commit `4cb0577` cleaned up accidentally committed `.gotmp`; `.gotmp/` now ignored.
## Treat container setup as a networked, privileged surface
```bash
test -e .dockerignore || echo ".dockerignore is absent"
rg -n '^(FROM|[[:space:]]*image:)|@latest|:latest|setup_24.x' \
Dockerfile Dockerfile.archied docker-compose.yml
```
`.dockerignore` exists (421 bytes) and excludes `.git`, `.task`, `.claude`,
`.codex`, `.crew`, `.agents`, `.references`, `bin/`, `dist/`, `docs/`,
`node_modules/`, root-built `archied`/`archie-agent`, and local config. Both
Dockerfiles still run `COPY . .` on top of it. Floating inputs: Go builder tags
omit patch/digest; Ubuntu base images omit digests; agent installs multiple
`@latest` Go tools; Node from moving `setup_24.x` channel.
`task docker-build` needs registry/network and functioning Compose.
`task docker-up` starts the Compose-managed NATS service and binds ports
4222/8222. The host daemon and its Docker-socket access are outside Compose.
## 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 initialise. |
| `TestRunWrapsExternalCommand ... Run() = "\n"` | Focused code failure in `internal/skillscript`. |
For hermetic test diagnosis:
```bash
env GIT_CONFIG_GLOBAL=/dev/null go test ./internal/worktree/... ./internal/worktreerpc/... -count=1
```
## Use the complete validation matrix
| 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,4 +0,0 @@
interface:
display_name: "Archie Build and Environment"
short_description: "Recreate and verify the Archie toolchain"
default_prompt: "Use $archie-build-and-env to recreate a clean Archie development environment and verify every build surface."
@@ -1,232 +0,0 @@
---
name: archie-codebase-discovery
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 behaviour before changing it.
Volatile tool facts below were verified on **2026-09-18**.
**Composition roots**: `cmd/archied/main.go` (thin dispatcher) →
`internal/app/archied.Run()`, and `internal/app/agentworker` (invoked by
`cmd/archie-agent/main.go`). Do not treat `cmd/*` as the wiring site.
**Production wiring**: a path selected by a shipped entrypoint — not a
constructor, decoder, or passing unit test. **State owner**: component with
authority to validate and persist a state transition.
## Establish a reproducible baseline
```sh
go version; go env GOMOD GOWORK GOOS GOARCH
gopls version; golangci-lint version; staticcheck -version
```
As of 2026-09-18: Go 1.27.0, gopls 0.23.0, golangci-lint 2.13.2,
staticcheck 2026.2.1. Use `gopls call_hierarchy` (no `go tool callgraph`;
`go tool` lists only asm, cgo, compile, cover, fix, link, preprofile, vet).
Writable caches when defaults are read-only:
```sh
export GOCACHE="${TMPDIR:-/tmp}/archie-discovery-gocache"
export GOLANGCI_LINT_CACHE="${TMPDIR:-/tmp}/archie-discovery-lint"
export GOTMPDIR="${TMPDIR:-/tmp}"
export GOPROXY=off GOFLAGS=-mod=readonly
```
Module boundaries (root and `tools/` are separate):
```sh
find . -name go.mod -not -path './.git/*' -not -path './node_modules/*'
go list -m -f '{{.Path}} {{.GoVersion}}'
go -C tools list -mod=readonly -m -f '{{.Path}} {{.GoVersion}}'
```
## Build the behaviour trace
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, 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`) |
| 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/infrastructure/postgres
go list -json ./internal/infrastructure/postgres
.agents/skills/archie-codebase-discovery/scripts/package-edges.sh ./internal/...
```
### Resolve symbols with gopls
1-indexed `file:line:column`:
```sh
gopls symbols internal/domain/storecontract/storecontract.go
gopls definition cmd/archied/main.go:27:14
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/infrastructure/postgres -list '.'
```
### Generate AST candidates for construction
```sh
.agents/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh Daemon .
.agents/skills/archie-codebase-discovery/scripts/scan-go-type-syntax.sh -tests Task .
```
Confirms candidates with `gopls definition` or `gopls references`. Pass
`-tests` to expose test-only construction.
## Run focused discovery recipes
### Find duplicate behaviour paths
```sh
golangci-lint run --enable-only=dupl ./internal/...
rg -n 'Transition\(|PublishTask\(|ClaimNext\(|StatusWaitingHuman' cmd internal
```
Trace each candidate to entrypoint and state owner. `dupl` finds similar syntax,
not two different implementations of one responsibility.
### Find unused-but-compiled code
```sh
staticcheck -checks=U1000 ./internal/...
```
For every suspect: `gopls references -d`; search init, reflection/Yaegi, tags,
RPC subjects, plugin manifests, string dispatch; check build tags/OS files;
search both composition roots. `U1000` does not prove exported/reflection/wire
targets are dead.
### Find interface implementations
```sh
gopls implementation
rg -n 'var _ .*=' --glob '*.go' cmd internal
```
Trace which implementation the composition root selects for each mode.
### Find struct-field consumers
`gopls references -d` on field declaration, not common name. Trace assignments
and reads separately. Follow `ForTask`/`ToConfig` copies. Check JSON/TOML/YAML
tags. Compare production and `_test.go` references.
### Detect constructor bypasses
Run `scan-go-type-syntax.sh Type .`. Inspect struct literals outside owning
package. Compare validation/defaulting in constructors with direct literals.
Use `gopls references` on constructor and type.
### Prove package dependency direction
```sh
.agents/skills/archie-codebase-discovery/scripts/package-edges.sh ./internal/...
go list -deps -json <pattern>
```
### Find decoded-but-unused configuration
Prove: `file/key → decoder → default → validation → normalisation/copy →
composition-root read → concrete component → observable behaviour`.
```sh
rg -n 'toml:"|yaml:"|json:"' internal/config
rg -n 'Resolve|Overlay|Dir|finalize|ForTask|ToConfig' internal/infrastructure/configuration internal/app/archied
gopls references -d <exact-field>
```
Decoding lives in `internal/infrastructure/configuration`, not `internal/config`.
`configuration.New(log)` returns a `Loader`; the composition root in
`internal/app/archied/bootstrap.go` calls `Loader.Resolve` (with `Loader.Overlay`
and `Loader.Dir` for overlay/`conf.d` inputs). There is no `config.Load` or
`config.LoadDir`.
### Prove production composition
1. Start at `internal/app/archied/main.go` (`Run`), entered from
`cmd/archied/main.go`.
2. Record config condition per branch.
3. Follow concrete construction into `daemon.Daemon` and gateway start.
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 persistence
Treat `internal/domain/storecontract` as the application contract and
`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' 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 |
## Produce the discovery handoff
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.
4. **Blast radius:** callers, consumers, tests, config, deploy wiring, docs,
compatibility paths.
5. **Duplication/deprecation ledger:** each candidate, live/dead evidence,
replacement, objective removal gate.
6. **Current-to-target gap:** current fact, target PRD, migration implication.
7. **Unknowns:** exact command, output/blocker, next evidence needed.
Do not propose implementation until the trace answers: what entrypoint selects
this path, which component owns state, which parallel/older path the feature
replaces, which production modes and persisted data must remain compatible,
which evidence would falsify current understanding.
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Codebase Discovery"
short_description: "Trace Archie behavior from entrypoint to production"
default_prompt: "Use $archie-codebase-discovery to trace this behavior through production wiring before proposing a change."
@@ -1,36 +0,0 @@
#!/bin/sh
set -eu
if [ "$#" -gt 1 ]; then
printf '%s\n' "usage: $0 [go-package-pattern]" >&2
exit 2
fi
command -v go >/dev/null 2>&1 || {
printf '%s\n' "error: go is required" >&2
exit 127
}
pattern=${1:-./...}
cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"}
mkdir -p "$cache_root/go-build" "$cache_root/tmp"
export GOCACHE="$cache_root/go-build"
export GOTMPDIR="$cache_root/tmp"
export GOPROXY=off
export GOFLAGS=-mod=readonly
module_path=$(go list -m -f '{{.Path}}')
go list -f '{{.ImportPath}}{{range .Imports}}{{printf "\t%s" .}}{{end}}' "$pattern" |
awk -F ' ' -v module="$module_path" '
{
from = $1
for (i = 2; i <= NF; i++) {
if ($i == module || index($i, module "/") == 1) {
printf "%s -> %s\n", from, $i
}
}
}
' |
LC_ALL=C sort -u
@@ -1,176 +0,0 @@
// Command scan-go-type-syntax reports syntax-level construction candidates for
// a named Go type. It deliberately uses only the standard library and never
// writes to the inspected tree.
package main
import (
"bufio"
"flag"
"fmt"
"go/ast"
"go/parser"
"go/token"
"io/fs"
"os"
"path/filepath"
"sort"
"strings"
)
type finding struct {
path string
line int
column int
kind string
detail string
}
func main() {
includeTests := flag.Bool("tests", false, "include *_test.go files")
flag.Usage = func() {
fmt.Fprintf(flag.CommandLine.Output(), "usage: %s [-tests] TypeName [root]\n", os.Args[0])
flag.PrintDefaults()
}
flag.Parse()
if flag.NArg() < 1 || flag.NArg() > 2 {
flag.Usage()
os.Exit(2)
}
typeName := flag.Arg(0)
root := "."
if flag.NArg() == 2 {
root = flag.Arg(1)
}
if !token.IsIdentifier(typeName) {
fmt.Fprintf(os.Stderr, "error: %q is not a Go identifier\n", typeName)
os.Exit(2)
}
results, err := scan(root, typeName, *includeTests)
if err != nil {
fmt.Fprintf(os.Stderr, "error: %v\n", err)
os.Exit(1)
}
out := bufio.NewWriter(os.Stdout)
defer out.Flush()
fmt.Fprintln(out, "kind\tlocation\tdetail")
for _, result := range results {
fmt.Fprintf(out, "%s\t%s:%d:%d\t%s\n",
result.kind, result.path, result.line, result.column, result.detail)
}
}
func scan(root, typeName string, includeTests bool) ([]finding, error) {
fset := token.NewFileSet()
var results []finding
err := filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
if entry.IsDir() {
if path == root {
return nil
}
name := entry.Name()
if strings.HasPrefix(name, ".") || name == "node_modules" ||
name == "vendor" || name == "bin" {
return filepath.SkipDir
}
return nil
}
if filepath.Ext(path) != ".go" {
return nil
}
if !includeTests && strings.HasSuffix(path, "_test.go") {
return nil
}
file, err := parser.ParseFile(fset, path, nil, 0)
if err != nil {
return fmt.Errorf("parse %s: %w", path, err)
}
ast.Inspect(file, func(node ast.Node) bool {
switch node := node.(type) {
case *ast.TypeSpec:
if node.Name.Name == typeName {
results = appendFinding(results, fset, node.Name.Pos(),
path, "declaration", "type "+node.Name.Name)
}
case *ast.CompositeLit:
if matchesType(node.Type, typeName) {
results = appendFinding(results, fset, node.Type.Pos(),
path, "literal", "direct composite literal of "+typeName)
}
case *ast.FuncDecl:
if returnsType(node.Type.Results, typeName) {
results = appendFinding(results, fset, node.Name.Pos(),
path, "returns-type", "func "+node.Name.Name)
}
}
return true
})
return nil
})
if err != nil {
return nil, err
}
sort.Slice(results, func(i, j int) bool {
left, right := results[i], results[j]
if left.path != right.path {
return left.path < right.path
}
if left.line != right.line {
return left.line < right.line
}
if left.column != right.column {
return left.column < right.column
}
return left.kind < right.kind
})
return results, nil
}
func appendFinding(results []finding, fset *token.FileSet, pos token.Pos, path, kind, detail string) []finding {
position := fset.Position(pos)
return append(results, finding{
path: filepath.ToSlash(path),
line: position.Line,
column: position.Column,
kind: kind,
detail: detail,
})
}
func returnsType(fields *ast.FieldList, typeName string) bool {
if fields == nil {
return false
}
for _, field := range fields.List {
if matchesType(field.Type, typeName) {
return true
}
}
return false
}
func matchesType(expr ast.Expr, typeName string) bool {
switch expr := expr.(type) {
case *ast.Ident:
return expr.Name == typeName
case *ast.SelectorExpr:
return expr.Sel.Name == typeName
case *ast.StarExpr:
return matchesType(expr.X, typeName)
case *ast.IndexExpr:
return matchesType(expr.X, typeName)
case *ast.IndexListExpr:
return matchesType(expr.X, typeName)
default:
return false
}
}
@@ -1,13 +0,0 @@
#!/bin/sh
set -eu
script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"}
mkdir -p "$cache_root/go-build" "$cache_root/tmp"
export GOCACHE="$cache_root/go-build"
export GOTMPDIR="$cache_root/tmp"
export GOPROXY=off
export GOFLAGS=-mod=readonly
exec go run "$script_dir/scan-go-type-syntax.go" "$@"
@@ -1,61 +0,0 @@
#!/bin/sh
set -u
usage() {
printf '%s\n' "usage: $0 file.go:line:column" >&2
exit 2
}
[ "$#" -eq 1 ] || usage
position=$1
command -v go >/dev/null 2>&1 || {
printf '%s\n' "error: go is required" >&2
exit 127
}
command -v gopls >/dev/null 2>&1 || {
printf '%s\n' "error: gopls is required" >&2
exit 127
}
case "$position" in
*.go:[1-9]*:[1-9]*) ;;
*) usage ;;
esac
cache_root=${ARCHIE_DISCOVERY_CACHE:-"${TMPDIR:-/tmp}/archie-codebase-discovery"}
mkdir -p "$cache_root/go-build" "$cache_root/xdg" "$cache_root/tmp" || exit 1
export GOCACHE="$cache_root/go-build"
export XDG_CACHE_HOME="$cache_root/xdg"
export GOTMPDIR="$cache_root/tmp"
export GOPROXY=off
export GOFLAGS=-mod=readonly
gomod=$(go env GOMOD)
if [ "$gomod" = "/dev/null" ] || [ -z "$gomod" ]; then
printf '%s\n' "error: run from inside a Go module" >&2
exit 1
fi
run_query() {
label=$1
shift
printf '\n== %s ==\n' "$label"
if output=$(gopls "$@" 2>&1); then
printf '%s\n' "$output"
return 0
else
printf '%s\n' "$output"
printf '%s\n' "(query is not applicable at this position, or failed)"
return 1
fi
}
successful=0
run_query "definition" definition "$position" && successful=$((successful + 1))
run_query "references (including declaration)" references -d "$position" && successful=$((successful + 1))
run_query "implementations" implementation "$position" && successful=$((successful + 1))
run_query "call hierarchy" call_hierarchy "$position" && successful=$((successful + 1))
[ "$successful" -gt 0 ]
@@ -1,266 +0,0 @@
---
name: archie-config-and-flags
description: Trace, add, rename, deprecate, or debug Archie configuration and command-line flags from external input through defaults, validation, overlays, environment and secret handling, worker snapshots, deployment passthrough, and the production consumer. Use for internal/config, config.example.toml, deployments/*.toml, docker-compose.yml, archied or archie-agent flags, multi-identity settings, mode-parity questions, and reports of a setting that parses but has no effect.
---
# Trace Archie configuration and flags
Treat configuration as a dataflow, not as a struct inventory. Prove every
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
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. |
Never upgrade a status merely because decoding tests pass.
## Trace one setting before editing it
1. Find every external spelling, Go field, flag, environment name, example, and
deployment reference.
2. Identify the selected loader or flag set.
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 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
deployment environment passthrough.
8. Assign one status from the table above.
```bash
rg -n 'Resolve|Overlay|Dir|ForTask|ToConfig|flag\.' \
internal/infrastructure/configuration internal/config internal/app/archied cmd/archie-agent
rg -n 'FIELD_NAME|external_key|ENV_NAME' \
--glob '*.go' --glob '*.toml' --glob '*.yml' --glob '*.yaml' .
```
## Select the real input path
| 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
key took effect.
A registered service client always resolves to a non-empty target, so
`Services.Get(name).Target != ""` proves nothing. `RegisterService` in
`internal/config/servicespec.go` supplies the fallback (`127.0.0.1:9090` for
the State Store, `127.0.0.1:8585` for the Gateway), which means a guard written
as "only dial when configured" dials always, and a test that sets no target
reaches for a real process on the developer's machine. Gate on an explicit
flag or on the dial succeeding, and give a binary its own
`-<service>-target` flag so tests can point it at a fake.
## Inventory CLI flags
### 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. |
The standalone agent always reads its token from `NATS_TOKEN`; there is no
token flag.
### Internal codesearch helper
`archied workspace-codesearch` bypasses daemon configuration before normal flag
parsing:
| Subcommand | Required flags | Optional flags |
| ------------ | ---------------------- | ------------------------------- |
| `build` | `--root`, `--index` | none |
| `candidates` | `--index`, `--pattern` | `--literal`, `--case-sensitive` |
Do not expose these helper flags as daemon settings.
## Read the current wiring matrix
### Root daemon and capability settings
| 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. Also the skills store `kitrun.Launcher` mounts read-only at a Kit's `agent-skills@1` path, read live per launch; empty withholds the mount. | 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 |
| `review.precision_gate`, `review.approve_before_post` | 2026-10-02: one control-plane resource `review-settings` (`internal/app/controlplane/review_settings.go`), seeded from `[review]`; the stored document outranks the file, layers field-by-field into `cfg.Review` (`runtimeConfigFrom`), and is watched live (`archie/control_plane.go`). Reaches a run through `Daemon.configFor` → `ForTask` → `TaskContext.Cfg`; the dashboard writes it on the Review settings page. | 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 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).
2. **not-projected.** A read exists, but at a layer that does not own the
effective copy, so editing the wrong layer does nothing. Direction matters as
much as presence: for most `[chat.*]` keys the stored resource outranks the
file, so writing a new file value is a no-op once a resource exists. A file
key in that position is a **seed**, not the contract.
3. **deliberately-not-projected.** File-only by design and therefore
indistinguishable from a dropped field to an auditor unless the projection
says so in a comment. `runtimeChatConfigFrom` reads
`Telegram.UpdateCheckCommand`/`UpdateInstallCommand` from `base` rather than
from the stored resource, on purpose. Check for that comment before filing a
defect.
### Repository settings
| 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 behaviour |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| `image` | Required at boot. Read by the container pool on every acquire (`containerLiveSettings` -> `Pool.current`, archie-core-zfb0.2), so a stored change applies without a restart. |
| `max_concurrency` | Zero means no limit. Read by the pool per acquire and applied to the daemon's running task dispatcher on publish (`ResizeTaskDispatcher`). |
| `max_uptime` | Default `60m` at boot; caps container lifetime. Read by the pool per acquire, so a stored change reaps the next container under the new cap. |
| `volume_ttl` | Default `72h` only when enabled; negative rejected. Re-read per cleanup cycle. |
| `pull_policy` | Default `missing` at boot. Pool code recognises `missing` and `always`; other strings silently skip pre-pull. Read by the pool per acquire. |
| `registry_auth` | `SecretRef` (file-owned, `json:"-"`). Resolved at boot by `archied`'s `resolveRegistryAuth` and passed to `container.Config.RegistryAuth`; the pool base64url-encodes it into the `X-Registry-Auth` header (`internal/container/pool.go`'s `registryAuthHeader`). Zero ref = anonymous pull. Unresolvable/empty credential or an unencodable one warns and pulls anonymously rather than failing the pool. A half-named ref is refused by `configuration.validateContainers`. `container-runtime-policies` cannot carry a secret ref, so this stays boot-resolved and requires-restart, unlike `image`/`pull_policy`. |
| `network` | Empty uses best-effort self-network detection at boot; the repository overlay pins `archie-core_default`. Read by the pool per acquire, falling back to the boot-resolved network when the live value is empty. |
| `profiles` | Named agent execution environments (image or Kit); resolved per task dispatch (`ContainerConfig.Profile`). Own control-plane resource `agent-profiles` (`json:"-"` on the field so `container-runtime-policies` never carries it), `ApplyMode: live`. |
| `credentials` | Maps a Kit `credential@1` service to a secret (`config.CredentialBinding`). Own control-plane resource `credential-bindings`, `ApplyMode: live`, `json:"-"` on the field. `kitrun.Launcher` reads it fresh from the live `config.Holder` on every `Launch`, never a value captured at boot -- see `internal/infrastructure/kitrun/launcher.go`'s `resolveCredentials`. A binding alone grants nothing; see `org`/`granted_credentials` below. |
| `org` / `granted_credentials` (root and per-identity) | An identity's org and the `credentials` service names it may resolve. `daemon.runKitTask` reads both fresh per dispatch (`d.configFor(task)`) and passes them to `kitrun.Request`; `config.ContainerConfig.BoundCredentials` computes the declared (Kit) ∩ granted (identity) ∩ org-matched intersection -- neither declared nor granted widens the other. |
### Channel settings
| 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`. |
Telegram `/restart` re-runs same TOML overlay load, then replaces only gateway
token and allowed-user list. Every other file setting is startup-only.
A stored `channel-settings` change is reconciled live by `archie-messaging`:
on a new version it re-resolves the file, layers the store over it, and restarts
only the channel whose transport settings changed (Telegram token/allowlist,
email relay, webhook route/secret). `chat.email.listen_addr` and
`chat.webhook_addr` are bound listen addresses, so those changes, and enabling
or disabling a channel, are reported outstanding and take effect on restart.
## Treat multi-identity as partially wired
`finalize` requires each identity's `name`, `bot_user`, non-empty repos, forge
type, and `SecretRef` token. `internal/app/archied` builds an identity forge
client and worktree manager.
Do not infer complete isolation:
- `internal/app/archied` resolves root forge client before all identity runners.
- Identity `name`, forge, repos, poll interval, bot user, bot email have
production reads. Identity bot email not defaulted despite comment.
- Identity `models`, `providers`, `dispatch`, `budgets`, `notify`, and
`diff_cap_lines` decode but workflows still receive root `Config`.
- Identity polling reads root `dispatch`, `label`, and `bot_user`.
- Container task snapshots and provider maps come from root config; task RPC
servers are root-forge/root-worktree.
- Root-only concurrency lookup ignores identity repo `allow_concurrent`.
Classify multi-identity changes field by field. Never label aggregate
`IdentityConfig` production-wired.
## Preserve worker and secret boundaries
`Config.ForTask` creates a detached root snapshot: models, budgets, the
retry/remediation cap (`MaxRetries`), dispatch, 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`.
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 = {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.
The host supervisor or launch shell supplies daemon secrets. Compose supplies
no `archied` environment because the daemon is not a Compose service.
## Follow the approved target
Current code puts infrastructure paths, domain policy, channel settings,
secrets, execution settings, repository associations, and extension data in one
mutable `config.Config`. Treat this as a current load-bearing weakness, not a
pattern to copy.
`docs/architecture/configuration.md` is approved as of 2026-07-28:
- move file/env/secret/overlay loading to private
`internal/infrastructure/configuration` input boundary;
- translate inputs in `internal/app`;
- give each domain/plugin typed owned settings and validation;
- dissolve `internal/config` rather than rename the global model;
- split `Repo` and `IdentityConfig` by actual capability ownership.
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Config and Flags"
short_description: "Trace Archie configuration from input to runtime"
default_prompt: "Use $archie-config-and-flags to trace this Archie setting or CLI flag from declaration through production wiring."
@@ -1,235 +0,0 @@
---
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 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
**current** = 2026-09-18 verified (HEAD `2e1e1549`); **fixed history** =
regression patterns; **open** = verified gap.
**Composition root**: `cmd/archied/main.go` → `internal/app/archied.Run()`;
wiring lives in `internal/app/archied/bootstrap.go`. **Core NATS
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**: behaviour fails where prerequisites available.
## Run the first-ten-minutes protocol
Do not begin with `task check` (mutates via `gofumpt -w .`/`go fix ./...`).
Compile, then run:
```bash
GIT_CONFIG_GLOBAL=/dev/null go test ./PATH/TO/PACKAGE -run '^TestName$' -count=1 -v
```
Classify: compile-only, listener failure, read-only tmp, 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 | 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
```bash
go version
go env GOTMPDIR GOCACHE GOPATH GOMODCACHE GOENV
```
Listener-dependent tests include embedded NATS, `httptest.NewServer`, and SMTP
listeners:
```bash
rg -n 'httptest\.NewServer|net\.Listen|RunRandClientPortServer|RunServer' \
--glob '*_test.go' cmd internal
```
Do not attribute go-git commit failures to GPG without checking the
repository-local mitigation. `worktree.Manager.setIdentity` pins
`commit.gpgsign=false`. Isolate ambient global config:
```bash
GIT_CONFIG_GLOBAL=/dev/null go test ./internal/worktree -count=1
```
## Confirm the skill-script regression stays fixed
The `TestRunWrapsExternalCommand` failure (`Run() = "\n"`) was a test bug, not
a product bug: `exec.CommandContext(ctx, "sh", "-c", "echo", "wrapped")`
passes `wrapped` as shell `$0`, so only `echo` ran. It failed from commit
`308c199` and **passes as of 2026-09-16**. Re-run it to confirm the fix has not
regressed; a failure now is a new defect, not this one.
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-skillscript-gocache \
GIT_CONFIG_GLOBAL=/dev/null go test ./internal/skillscript \
-run '^TestRunWrapsExternalCommand$' -count=1 -v
```
## Triage NATS request/reply and JetStream
| 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
docker compose logs --since=10m nats
docker compose exec -T nats wget -q -O - http://localhost:8222/healthz
```
Branch on `no responders`: container startup lag if responder appears within 20s;
inspect agent's network/environment if every task exhausts window; confirm
`registerTaskRPCServers` if only RPC calls time out.
**Fixed history:** auto-detection once put task containers on default bridge;
explicit `containers.network` plus warning logs now fence that path.
Check semantics: republishing same owner/repo/issue within 2m is dedup'd; reply
inbox auto-unsubscribes after one response; `Client.Fetch` must inspect
`batch.Error()`; an empty poll reports `eventbus.ErrNoMessage` rather than
`(nil, nil)`.
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-nats-unit-gocache \
go test ./internal/infrastructure/eventbus/nats -run 'TestPublishUniqueSuppressesDuplicateKeyOnWorkQueueStream' -count=1 -v
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-agent-unit-gocache \
go test ./internal/agentexec -run '^TestToolSetHandler' -count=1 -v
```
## Trace configuration from source to behaviour
Trace: `cmd/archied` (`internal/app/archied/bootstrap.go`) reads
`-config`/`-config-overlay` → `configuration.New(log)` + `Loader.Resolve`
decodes, `finalize` defaults/validates → secrets resolve → composition root
constructs service → Compose/subprocess/`containerEnv` propagate → consumer.
```bash
rg -n 'Loader\.(Resolve|Overlay|Dir)|configuration\.' internal/app/archied internal/infrastructure/configuration
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-config-gocache \
go test ./internal/infrastructure/configuration \
-run 'Test(ResolveSelectsFileFormatsAndDirectories|LoadForgeTokenEnvBackwardCompat)' -count=1 -v
```
The `config.Load`/`config.LoadDir` helpers are gone; decoding is
`Loader`-based. A YAML field decoding correctly without a composition-root read
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.
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.
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-mcp-gocache \
go test ./internal/tools/mcp \
-run 'Test(ReadMessage|WriteMessage|StdioTransportBadFraming)' -count=1 -v
```
Test helper and client share the same `readMessage`/`writeMessage` — can mirror
mistakes. With `npx`:
```bash
ARCHIE_TEST_DESKTOP_COMMANDER=1 env GOTMPDIR=/tmp \
GOCACHE=/tmp/archie-mcp-integration-gocache \
go test ./internal/tools/provider/mcp \
-run '^TestDesktopCommanderClientCompatibility$' -count=1 -v
```
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.
```bash
env GOTMPDIR=/tmp GOCACHE=/tmp/archie-telegram-gocache \
go test ./internal/channels/telegram \
-run 'Test(SenderAllowlistFailsClosed|IsSenderAllowed|SessionManagementCommandsArePublished)$' \
-count=1 -v
```
**Fixed history:** publishing only default left ~60 old Hermes commands visible.
## Diagnose state, events, containers, and optional features
### 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/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 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` |
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Debugging Playbook"
short_description: "Diagnose Archie failures from symptoms"
default_prompt: "Use $archie-debugging-playbook to diagnose this Archie failure from symptoms and evidence."
@@ -1,265 +0,0 @@
---
name: archie-diagnostics-and-tooling
description: "Measure Archie codebase maintainability, Go package dependency shape, configuration consumption, production composition, test and delivery-gate drift, tracked-artifact hygiene, coverage, races, and runtime evidence. Load when establishing a dated baseline, finding large or complex functions, investigating duplicate or dead-path candidates, checking whether configuration reaches an entrypoint, comparing architecture before and after a refactor, or replacing an eyeballed quality claim with reproducible numbers."
---
# Measure Archie instead of eyeballing it
Collect evidence before judging quality. Keep collection read-only, save raw
output, state what each metric cannot prove.
Volatile facts and numeric snapshots below were verified on **2026-09-18**
(HEAD `2e1e1549`).
Route to `archie-codebase-discovery` for semantic traces,
`archie-config-and-flags` for config enumeration,
`archie-debugging-playbook` for live failures.
## Define the measurement terms
- **Baseline:** dated raw output tied to a commit, toolchain, command, and
environment.
- **Candidate:** a machine-found item requiring semantic confirmation.
- **Production composition:** concrete construction selected by a shipped
entrypoint. Principal: `cmd/archied/main.go` → `internal/app/archied.Run()`.
- **Fan-in:** number of packages in the same module that directly import a
package.
- **Fan-out:** number of packages in the same module that a package directly
imports.
- **Physical line:** a newline-delimited source line, including comments and
blanks.
- **Syntactic complexity:** this skill's approximation: one plus `if`, loop,
non-default case, communication clause, `&&`, and `||` nodes.
## Establish a reproducible snapshot
```sh
export LC_ALL=C
export GOCACHE=/tmp/archie-diagnostics-gocache
export GOTMPDIR=/tmp
export XDG_CACHE_HOME=/tmp/archie-diagnostics-xdg
export GOLANGCI_LINT_CACHE=/tmp/archie-diagnostics-lint
export GOPROXY=off
export GOFLAGS=-mod=readonly
skill=.agents/skills/archie-diagnostics-and-tooling
stamp=$(date -u +%Y%m%dT%H%M%SZ)
evidence_dir=/tmp/archie-diagnostics-"$stamp"
mkdir -p "$evidence_dir"
git rev-parse --verify HEAD >"$evidence_dir/revision.txt"
git status --short >>"$evidence_dir/revision.txt"
go version >"$evidence_dir/tools.txt"
gopls version >>"$evidence_dir/tools.txt"
golangci-lint version >>"$evidence_dir/tools.txt"
staticcheck -version >>"$evidence_dir/tools.txt"
go run "$skill/scripts/source-metrics.go" -root . >"$evidence_dir/source.tsv"
go run "$skill/scripts/config-use-candidates.go" -root . >"$evidence_dir/config.tsv"
"$skill/scripts/package-shape.sh" . >"$evidence_dir/packages-root.tsv"
"$skill/scripts/package-shape.sh" tools >"$evidence_dir/packages-tools.tsv"
"$skill/scripts/delivery-snapshot.sh" >"$evidence_dir/delivery.tsv"
```
Both filesystem-walking scripts (`source-metrics.go`,
`config-use-candidates.go`) skip `.worktrees/`, which holds live git worktrees
nested inside the repo root. Each is a near-complete copy of the module, so
walking them multiplies every count by the number of checkout worktrees. If a
new nested-checkout convention appears, extend `excludedDirectory` in both;
`.git/info/exclude` does not help, because the scripts walk the filesystem
rather than `git ls-files`. `package-shape.sh` reads `go list`, so it is immune.
## Use the bundled reports
### Measure source shape
```sh
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 |
| `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 |
The defaults (80 body lines, complexity 15) mirror numeric triage points in
`.golangci.yml`. They do **not** implement `funlen` or `cyclop`. Run configured
linters for authoritative findings:
```sh
golangci-lint run --enable-only=funlen,gocognit,gocyclo,cyclop,maintidx,nestif ./internal/...
```
If a hotspot shrinks, verify that responsibility moved to a cohesive owner.
Moving the same work into unowned helpers is not improvement.
### Measure package shape
```sh
"$skill/scripts/package-shape.sh" . >"$evidence_dir/packages-root.tsv"
"$skill/scripts/package-shape.sh" tools >"$evidence_dir/packages-tools.tsv"
awk -F ' ' '$1=="PACKAGE" {print $3 "\t" $4 "\t" $2}' "$evidence_dir/packages-root.tsv" |
sort -nr -k1,1 -k2,2 |
sed -n '1,20p'
```
Read `PACKAGE package fan_in fan_out` and `EDGE from -> to` rows. High fan-in
signals change risk; high fan-out signals orchestration. The report contains
only direct, intra-module imports.
### Find configuration-consumption candidates
```sh
go run "$skill/scripts/config-use-candidates.go" -root . >"$evidence_dir/config.tsv"
rg 'candidate-no-(selector-outside-config|entrypoint-selector)' "$evidence_dir/config.tsv"
```
Read each `CONFIG_FIELD` row as path, line, Type.Field, tags, same-name
definition count, config-package selectors, cmd selectors, other-production
selectors, test selectors, generated selectors, candidate status. The report
finds named fields with `toml`/`yaml`/`json` tags in `internal/config`, then
counts selectors with the same **spelling**. It is deliberately fast and not
type-aware.
Only `candidate-no-selector-outside-config` is a signal.
`candidate-no-entrypoint-selector` fires for ~180 of 196 rows because the
script looks for selectors only in `cmd/`, and most fields are read from the
composition root under `internal/app/archied`. Even the signal row has false
positives: a field consumed by **spelling** rather than by a Go selector
(`LegacyEnabled` via the reload allowlist map, `ReloadStatus.*` via JSON
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 → normalisation/copy → composition-root read
→ concrete component → observable behaviour.
### Measure delivery and hygiene drift
```sh
"$skill/scripts/delivery-snapshot.sh" >"$evidence_dir/delivery.tsv"
```
Read: `SURFACE axis scope literal_count` as literal text evidence;
`HYGIENE metric count` as tracked-path candidates; `MODULE path` as discovered
Go module boundaries. The snapshot compares Task, GitHub CI, and
composition-root anchors under `internal/app/archied`.
Composition-root anchors must name the file that actually does the wiring.
`cmd/archied/main.go` is a thin dispatcher that routes to
`internal/app/archied`; anchoring on it yields a silent `0` for every row,
which reads as "no composition root" rather than "wrong file". A zero here is
evidence about the anchor, not about production.
Inspect hygiene candidates directly:
```sh
git ls-files |
rg '(^|/)(node_modules|bin|dist|\.gotmp)(/|$)|\.(exe|test|out)$'
git ls-files -s | awk '$1=="120000" {print}'
```
## Investigate duplication and hidden dead paths
```sh
golangci-lint run --enable-only=dupl ./internal/...
```
```sh
staticcheck -checks=U1000 ./internal/...
```
On 2026-09-18, the focused `dupl` command reported zero issues. Two code paths
can implement the same responsibility with different syntax.
For every candidate: name the externally visible operation; search all
entrypoints and modes; use `gopls call_hierarchy`, `gopls references -d`, and
AST construction scan; check interfaces, registrations, reflection, build tags,
OS files, and wire names; identify what a new feature supersedes; record
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 analyser.
## Collect test, race, coverage, and runtime evidence
```sh
go test ./internal/infrastructure/postgres -count=1 -coverprofile=/tmp/archie-store.cover
go tool cover -func=/tmp/archie-store.cover
go test -race ./internal/infrastructure/postgres -count=1
```
As of 2026-09-18, the package reported 78.6% statement coverage and passed its
race run.
```sh
docker compose logs nats >"$evidence_dir/nats.log"
journalctl --user -u archied >"$evidence_dir/archied.log"
curl -fsS http://localhost:8222/healthz >"$evidence_dir/nats-health.txt"
```
Run only when local Compose stack is in scope.
## Compare before and after
Predict exact deltas before changing code. Collect a second snapshot with the
same script revision, flags, environment, and toolchain:
```sh
after_dir=/tmp/archie-diagnostics-after
mkdir -p "$after_dir"
go run "$skill/scripts/source-metrics.go" -root . >"$after_dir/source.tsv"
go run "$skill/scripts/config-use-candidates.go" -root . >"$after_dir/config.tsv"
"$skill/scripts/package-shape.sh" . >"$after_dir/packages-root.tsv"
"$skill/scripts/delivery-snapshot.sh" >"$after_dir/delivery.tsv"
diff -u "$evidence_dir/source.tsv" "$after_dir/source.tsv"
diff -u "$evidence_dir/config.tsv" "$after_dir/config.tsv"
diff -u "$evidence_dir/packages-root.tsv" "$after_dir/packages-root.tsv"
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 behaviour. Reject a "better" metric that moved
duplication, hid a path, or weakened a gate.
## Dated current snapshot
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 |
`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,
against 422 non-test and 403 test tracked files. The single extra file is an
untracked probe under `.local/issue-tracker/probes/`.
The scripts count themselves: the skill's own Go files contribute 640 of those
production lines. Editing a bundled script therefore moves
`production_physical_lines` on its own, so re-baseline after any script change
rather than reading the delta as a change in the product code.
The delivery snapshot found no Taskfile literals for race; docs now has 6 and
the `tools` module 7, both grown by wiring `task docs:check` into the gate;
GitHub `go gate` 4 and container publish 3; and non-zero literals for all five
composition-root anchors under `internal/app/archied`.
The focused test
`go test ./internal/skillscript -run '^TestRunWrapsExternalCommand$' -count=1 -v`
failed on 2026-07-28 with `Run() = "\n"` and **passes** as of 2026-09-16.
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Diagnostics and Tooling"
short_description: "Measure maintainability, wiring, and delivery drift"
default_prompt: "Use $archie-diagnostics-and-tooling to collect a dated, reproducible evidence baseline before changing Archie."
@@ -1,283 +0,0 @@
// Command config-use-candidates reports syntax-level selector evidence for
// tagged fields declared by internal/config. Results are candidates, not proof
// that a field is wired, live, or dead.
package main
import (
"flag"
"fmt"
"go/ast"
"go/parser"
"go/token"
"io/fs"
"os"
"path/filepath"
"reflect"
"sort"
"strconv"
"strings"
)
type fieldDefinition struct {
path string
line int
typeName string
fieldName string
tags string
duplicates int
}
type referenceCounts struct {
config int
entrypoint int
production int
test int
generated int
}
func main() {
root := flag.String("root", ".", "repository root to inspect")
flag.Parse()
absoluteRoot, err := filepath.Abs(*root)
if err != nil {
fail(2, "resolve root: %v", err)
}
info, err := os.Stat(absoluteRoot)
if err != nil {
fail(2, "inspect root: %v", err)
}
if !info.IsDir() {
fail(2, "root is not a directory: %s", absoluteRoot)
}
fset := token.NewFileSet()
fields, err := readFieldDefinitions(absoluteRoot, fset)
if err != nil {
fail(1, "%v", err)
}
if len(fields) == 0 {
fail(1, "no tagged fields found under internal/config")
}
nameCounts := map[string]int{}
for _, field := range fields {
nameCounts[field.fieldName]++
}
for index := range fields {
fields[index].duplicates = nameCounts[fields[index].fieldName]
}
references := map[string]*referenceCounts{}
for name := range nameCounts {
references[name] = &referenceCounts{}
}
if err := countSelectors(absoluteRoot, fset, references); err != nil {
fail(1, "%v", err)
}
sort.Slice(fields, func(i, j int) bool {
if fields[i].typeName != fields[j].typeName {
return fields[i].typeName < fields[j].typeName
}
if fields[i].fieldName != fields[j].fieldName {
return fields[i].fieldName < fields[j].fieldName
}
if fields[i].path != fields[j].path {
return fields[i].path < fields[j].path
}
return fields[i].line < fields[j].line
})
fmt.Println("META\tschema\tarchie-config-use-candidates/v1")
fmt.Println("META\tmeaning\tselector-name counts are heuristic candidates; confirm exact fields with gopls references and production composition")
for _, field := range fields {
count := references[field.fieldName]
status := "candidate-selector-seen-in-entrypoint"
switch {
case count.production == 0 && count.entrypoint == 0:
status = "candidate-no-selector-outside-config"
case count.entrypoint == 0:
status = "candidate-no-entrypoint-selector"
}
fmt.Printf(
"CONFIG_FIELD\t%s\t%d\t%s.%s\t%s\t%d\t%d\t%d\t%d\t%d\t%d\t%s\n",
field.path,
field.line,
field.typeName,
field.fieldName,
field.tags,
field.duplicates,
count.config,
count.entrypoint,
count.production,
count.test,
count.generated,
status,
)
}
}
func readFieldDefinitions(root string, fset *token.FileSet) ([]fieldDefinition, error) {
configDir := filepath.Join(root, "internal", "config")
info, err := os.Stat(configDir)
if err != nil {
return nil, fmt.Errorf("inspect internal/config: %w", err)
}
if !info.IsDir() {
return nil, fmt.Errorf("internal/config is not a directory")
}
var fields []fieldDefinition
err = filepath.WalkDir(configDir, func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
if entry.IsDir() || filepath.Ext(entry.Name()) != ".go" || strings.HasSuffix(entry.Name(), "_test.go") {
return nil
}
body, err := os.ReadFile(path)
if err != nil {
return err
}
file, err := parser.ParseFile(fset, path, body, parser.ParseComments)
if err != nil {
return fmt.Errorf("parse %s: %w", path, err)
}
relative, err := filepath.Rel(root, path)
if err != nil {
return err
}
relative = filepath.ToSlash(relative)
for _, declaration := range file.Decls {
general, ok := declaration.(*ast.GenDecl)
if !ok || general.Tok != token.TYPE {
continue
}
for _, specification := range general.Specs {
typeSpec, ok := specification.(*ast.TypeSpec)
if !ok {
continue
}
structType, ok := typeSpec.Type.(*ast.StructType)
if !ok {
continue
}
for _, field := range structType.Fields.List {
tags, ok := configTags(field.Tag)
if !ok {
continue
}
for _, name := range field.Names {
fields = append(fields, fieldDefinition{
path: relative,
line: fset.Position(name.Pos()).Line,
typeName: typeSpec.Name.Name,
fieldName: name.Name,
tags: tags,
})
}
}
}
}
return nil
})
return fields, err
}
func configTags(literal *ast.BasicLit) (string, bool) {
if literal == nil {
return "", false
}
raw, err := strconv.Unquote(literal.Value)
if err != nil {
return "", false
}
tag := reflect.StructTag(raw)
var parts []string
for _, key := range []string{"toml", "yaml", "json"} {
value, ok := tag.Lookup(key)
if !ok {
continue
}
parts = append(parts, key+"="+value)
}
return strings.Join(parts, ";"), len(parts) > 0
}
func countSelectors(root string, fset *token.FileSet, references map[string]*referenceCounts) error {
return filepath.WalkDir(root, func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
relative, err := filepath.Rel(root, path)
if err != nil {
return err
}
relative = filepath.ToSlash(relative)
if entry.IsDir() {
if relative != "." && excludedDirectory(relative, entry.Name()) {
return filepath.SkipDir
}
return nil
}
if filepath.Ext(entry.Name()) != ".go" {
return nil
}
body, err := os.ReadFile(path)
if err != nil {
return err
}
file, err := parser.ParseFile(fset, path, body, parser.ParseComments)
if err != nil {
return fmt.Errorf("parse %s: %w", relative, err)
}
generated := ast.IsGenerated(file)
isTest := strings.HasSuffix(entry.Name(), "_test.go")
inConfig := strings.HasPrefix(relative, "internal/config/")
inEntrypoint := strings.HasPrefix(relative, "cmd/")
ast.Inspect(file, func(node ast.Node) bool {
selector, ok := node.(*ast.SelectorExpr)
if !ok {
return true
}
count := references[selector.Sel.Name]
if count == nil {
return true
}
switch {
case generated:
count.generated++
case isTest:
count.test++
case inConfig:
count.config++
case inEntrypoint:
count.entrypoint++
default:
count.production++
}
return true
})
return nil
})
}
// excludedDirectory reports whether a walked directory is outside the module.
//
// ".worktrees" holds live git worktrees of this same repository, nested inside
// the root. countSelectors walks the whole root, so without this every selector
// count is multiplied by the number of checkout worktrees.
func excludedDirectory(_, name string) bool {
switch name {
case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp", ".worktrees":
return true
}
return false
}
func fail(code int, format string, arguments ...any) {
fmt.Fprintf(os.Stderr, "config-use-candidates: "+format+"\n", arguments...)
os.Exit(code)
}
@@ -1,95 +0,0 @@
#!/bin/sh
set -eu
if [ "$#" -ne 0 ]; then
printf '%s\n' "usage: delivery-snapshot.sh" >&2
exit 2
fi
for tool in git rg sed wc; do
command -v "$tool" >/dev/null 2>&1 || {
printf 'delivery-snapshot: %s is required\n' "$tool" >&2
exit 127
}
done
script_dir=$(CDPATH= cd "$(dirname "$0")" && pwd)
repo_root=$(CDPATH= cd "$script_dir/../../../.." && pwd)
if [ ! -f "$repo_root/go.mod" ] || [ ! -f "$repo_root/Taskfile.yml" ]; then
printf 'delivery-snapshot: expected Archie repository root at %s\n' "$repo_root" >&2
exit 2
fi
temporary=$(mktemp -d "${TMPDIR:-/tmp}/archie-delivery-snapshot.XXXXXX")
trap 'rm -rf "$temporary"' EXIT HUP INT TERM
cd "$repo_root"
printf '%s\n' "META schema archie-delivery-snapshot/v1"
scan_literal() {
axis=$1
scope=$2
pattern=$3
shift 3
result="$temporary/$axis"
if rg -n --no-heading --color never -e "$pattern" "$@" >"$result"; then
:
else
status=$?
if [ "$status" -ne 1 ]; then
printf 'delivery-snapshot: scan failed for %s\n' "$axis" >&2
exit "$status"
fi
fi
count=$(wc -l <"$result" | sed 's/[[:space:]]//g')
printf 'SURFACE\t%s\t%s\t%s\n' "$axis" "$scope" "$count"
}
scan_literal task_format taskfile 'gofumpt[[:space:]]+-w|go fix' Taskfile.yml
scan_literal task_vet taskfile 'go vet' Taskfile.yml
scan_literal task_build taskfile 'go build|task:[[:space:]]+build' Taskfile.yml
scan_literal task_test taskfile 'go test|task:[[:space:]]+test' Taskfile.yml
scan_literal task_lint taskfile 'golangci-lint|task:[[:space:]]+lint' Taskfile.yml
scan_literal task_race taskfile 'go test[^#\n]*-race|-race[^#\n]*go test' Taskfile.yml
scan_literal task_tools_module taskfile 'go -C tools|cd tools|task:[[:space:]]+tools' Taskfile.yml
scan_literal task_docs taskfile 'docsgen|docs:generate|docs:check' Taskfile.yml
# One CI surface: .github/workflows. The Gitea workflow was dropped in dd9bddc2
# ("ci: build and push images to GHCR, drop the Gitea workflow"), so scanning
# .gitea/workflows aborted the whole snapshot under `set -eu`.
scan_literal github_go_gate github-workflows 'go test|go vet|go build|golangci-lint|task[[:space:]]+check' .github/workflows
scan_literal github_container_publish github-workflows 'docker build|docker push|docker/build-push-action|docker login' .github/workflows
# Composition root. cmd/archied/main.go is now a ~30-line dispatcher that only
# routes to internal/app/archied, so anchoring on it reported a silent zero for
# every row below -- which reads as "no composition root" rather than "wrong
# 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_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
git ls-files >"$temporary/tracked"
tracked_total=$(wc -l <"$temporary/tracked" | sed 's/[[:space:]]//g')
tracked_node_modules=$(rg -c '(^|/)node_modules(/|$)' "$temporary/tracked" || true)
tracked_artifacts=$(rg -c '(^|/)(node_modules|bin|dist|\.gotmp)(/|$)|\.(exe|test|out)$' "$temporary/tracked" || true)
tracked_symlinks=$(git ls-files -s | awk '$1 == "120000" {count++} END {print count + 0}')
printf 'HYGIENE\ttracked_paths\t%s\n' "$tracked_total"
printf 'HYGIENE\ttracked_node_modules_paths\t%s\n' "${tracked_node_modules:-0}"
printf 'HYGIENE\ttracked_artifact_candidates\t%s\n' "${tracked_artifacts:-0}"
printf 'HYGIENE\ttracked_symlinks\t%s\n' "$tracked_symlinks"
if [ -f .dockerignore ]; then
printf '%s\n' "HYGIENE dockerignore_present 1"
else
printf '%s\n' "HYGIENE dockerignore_present 0"
fi
find . \
\( -path './.git' -o -path './.claude' -o -path './.references' -o -name node_modules -o -name .worktrees \) -prune -o \
-name go.mod -print |
LC_ALL=C sort |
while IFS= read -r module; do
printf 'MODULE\t%s\n' "$module"
done
@@ -1,86 +0,0 @@
#!/bin/sh
set -eu
if [ "$#" -gt 1 ]; then
printf '%s\n' "usage: $0 [module-directory-relative-to-repo]" >&2
exit 2
fi
command -v go >/dev/null 2>&1 || {
printf '%s\n' "package-shape: go is required" >&2
exit 127
}
command -v awk >/dev/null 2>&1 || {
printf '%s\n' "package-shape: awk is required" >&2
exit 127
}
script_dir=$(CDPATH= cd "$(dirname "$0")" && pwd)
repo_root=$(CDPATH= cd "$script_dir/../../../.." && pwd)
module_relative=${1:-.}
module_root="$repo_root/$module_relative"
edge_helper="$repo_root/.agents/skills/archie-codebase-discovery/scripts/package-edges.sh"
if [ ! -f "$module_root/go.mod" ]; then
printf 'package-shape: no go.mod at %s\n' "$module_root" >&2
exit 2
fi
if [ ! -x "$edge_helper" ]; then
printf 'package-shape: required sibling helper is missing or not executable: %s\n' "$edge_helper" >&2
exit 2
fi
temporary=$(mktemp -d "${TMPDIR:-/tmp}/archie-package-shape.XXXXXX")
trap 'rm -rf "$temporary"' EXIT HUP INT TERM
mkdir -p "$temporary/cache" "$temporary/build-tmp"
export GOCACHE="$temporary/cache"
export GOTMPDIR="$temporary/build-tmp"
export GOPROXY=off
export GOFLAGS="-mod=readonly -buildvcs=false"
export ARCHIE_DISCOVERY_CACHE="$temporary/discovery"
(
cd "$module_root"
go list ./... | LC_ALL=C sort
) >"$temporary/packages"
if (
cd "$module_root"
"$edge_helper" ./...
) >"$temporary/edges" 2>"$temporary/edge-stderr"; then
# The sibling helper sets its own GOFLAGS and can trigger a harmless,
# nondeterministic temporary filename when GOMODCACHE is read-only.
# Preserve the warning while normalizing only that filename suffix.
sed 's/\.info[0-9][0-9]*\.tmp/.info<TEMP>.tmp/' "$temporary/edge-stderr" >&2
else
status=$?
cat "$temporary/edge-stderr" >&2
exit "$status"
fi
(
cd "$module_root"
go list -m -f '{{.Path}}'
) >"$temporary/module"
module_path=$(sed -n '1p' "$temporary/module")
printf '%s\n' "META schema archie-package-shape/v1"
printf 'META\tmodule\t%s\n' "$module_path"
awk -F ' ' '
NR == FNR {
packages[$0] = 1
next
}
{
split($0, edge, " -> ")
outbound[edge[1]]++
inbound[edge[2]]++
}
END {
for (packageName in packages) {
printf "PACKAGE\t%s\t%d\t%d\n", packageName, inbound[packageName] + 0, outbound[packageName] + 0
}
}
' "$temporary/packages" "$temporary/edges" | LC_ALL=C sort
awk '{printf "EDGE\t%s\n", $0}' "$temporary/edges"
@@ -1,357 +0,0 @@
// Command source-metrics emits deterministic, syntax-derived Go source metrics.
// It never writes to the inspected tree and uses only the Go standard library.
package main
import (
"bytes"
"flag"
"fmt"
"go/ast"
"go/parser"
"go/token"
"io/fs"
"os"
"path/filepath"
"sort"
"strings"
)
type counts struct {
productionFiles int
testFiles int
generatedFiles int
productionLines int
testLines int
generatedLines int
functions int
methods int
}
type packageCounts struct {
module string
path string
productionFiles int
testFiles int
generatedFiles int
productionLines int
testLines int
generatedLines int
}
type hotspot struct {
module string
path string
line int
symbol string
spanLines int
statements int
complexity int
}
func main() {
root := flag.String("root", ".", "repository root to inspect")
top := flag.Int("top", 30, "maximum hotspot rows; zero means all")
largeLines := flag.Int("large-lines", 80, "minimum body span for a hotspot")
complexity := flag.Int("complexity", 15, "minimum approximate syntactic complexity for a hotspot")
includeTests := flag.Bool("include-test-hotspots", false, "include test functions in hotspot rows")
flag.Parse()
if *top < 0 || *largeLines < 1 || *complexity < 1 {
fail(2, "top must be non-negative; thresholds must be positive")
}
absoluteRoot, err := filepath.Abs(*root)
if err != nil {
fail(2, "resolve root: %v", err)
}
info, err := os.Stat(absoluteRoot)
if err != nil {
fail(2, "inspect root: %v", err)
}
if !info.IsDir() {
fail(2, "root is not a directory: %s", absoluteRoot)
}
modules := map[string]*counts{}
packages := map[string]*packageCounts{}
var hotspots []hotspot
fset := token.NewFileSet()
err = filepath.WalkDir(absoluteRoot, func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
relative, err := filepath.Rel(absoluteRoot, path)
if err != nil {
return err
}
relative = filepath.ToSlash(relative)
if entry.IsDir() {
if relative != "." && excludedDirectory(relative, entry.Name()) {
return filepath.SkipDir
}
return nil
}
if filepath.Ext(entry.Name()) != ".go" {
return nil
}
body, err := os.ReadFile(path)
if err != nil {
return err
}
file, err := parser.ParseFile(fset, path, body, parser.ParseComments)
if err != nil {
return fmt.Errorf("parse %s: %w", relative, err)
}
module := moduleFor(relative)
moduleCounts := modules[module]
if moduleCounts == nil {
moduleCounts = &counts{}
modules[module] = moduleCounts
}
dir := filepath.ToSlash(filepath.Dir(relative))
packageKey := module + "\x00" + dir
pkg := packages[packageKey]
if pkg == nil {
pkg = &packageCounts{module: module, path: dir}
packages[packageKey] = pkg
}
lines := physicalLines(body)
generated := ast.IsGenerated(file)
isTest := strings.HasSuffix(entry.Name(), "_test.go")
switch {
case generated:
moduleCounts.generatedFiles++
moduleCounts.generatedLines += lines
pkg.generatedFiles++
pkg.generatedLines += lines
case isTest:
moduleCounts.testFiles++
moduleCounts.testLines += lines
pkg.testFiles++
pkg.testLines += lines
default:
moduleCounts.productionFiles++
moduleCounts.productionLines += lines
pkg.productionFiles++
pkg.productionLines += lines
}
for _, declaration := range file.Decls {
function, ok := declaration.(*ast.FuncDecl)
if !ok || function.Body == nil {
continue
}
if function.Recv == nil {
moduleCounts.functions++
} else {
moduleCounts.methods++
}
if generated || (isTest && !*includeTests) {
continue
}
start := fset.Position(function.Body.Lbrace).Line
end := fset.Position(function.Body.Rbrace).Line
row := hotspot{
module: module,
path: relative,
line: fset.Position(function.Pos()).Line,
symbol: symbolName(function),
spanLines: end - start + 1,
statements: statementNodes(function.Body),
complexity: syntacticComplexity(function.Body),
}
if row.spanLines >= *largeLines || row.complexity >= *complexity {
hotspots = append(hotspots, row)
}
}
return nil
})
if err != nil {
fail(1, "%v", err)
}
fmt.Println("META\tschema\tarchie-source-metrics/v1")
fmt.Printf("META\tthresholds\tlarge_lines=%d;syntactic_complexity=%d;top=%d\n", *largeLines, *complexity, *top)
moduleNames := sortedKeys(modules)
for _, module := range moduleNames {
value := modules[module]
emitMetric(module, "production_go_files", value.productionFiles)
emitMetric(module, "test_go_files", value.testFiles)
emitMetric(module, "generated_go_files", value.generatedFiles)
emitMetric(module, "production_physical_lines", value.productionLines)
emitMetric(module, "test_physical_lines", value.testLines)
emitMetric(module, "generated_physical_lines", value.generatedLines)
emitMetric(module, "functions", value.functions)
emitMetric(module, "methods", value.methods)
}
packageRows := make([]*packageCounts, 0, len(packages))
for _, row := range packages {
packageRows = append(packageRows, row)
}
sort.Slice(packageRows, func(i, j int) bool {
if packageRows[i].module != packageRows[j].module {
return packageRows[i].module < packageRows[j].module
}
return packageRows[i].path < packageRows[j].path
})
for _, row := range packageRows {
fmt.Printf(
"PACKAGE\t%s\t%s\t%d\t%d\t%d\t%d\t%d\t%d\n",
row.module,
row.path,
row.productionFiles,
row.testFiles,
row.generatedFiles,
row.productionLines,
row.testLines,
row.generatedLines,
)
}
sort.Slice(hotspots, func(i, j int) bool {
if hotspots[i].spanLines != hotspots[j].spanLines {
return hotspots[i].spanLines > hotspots[j].spanLines
}
if hotspots[i].complexity != hotspots[j].complexity {
return hotspots[i].complexity > hotspots[j].complexity
}
if hotspots[i].path != hotspots[j].path {
return hotspots[i].path < hotspots[j].path
}
if hotspots[i].line != hotspots[j].line {
return hotspots[i].line < hotspots[j].line
}
return hotspots[i].symbol < hotspots[j].symbol
})
if *top > 0 && len(hotspots) > *top {
hotspots = hotspots[:*top]
}
for _, row := range hotspots {
fmt.Printf(
"HOTSPOT\t%s\t%s\t%d\t%s\t%d\t%d\t%d\n",
row.module,
row.path,
row.line,
row.symbol,
row.spanLines,
row.statements,
row.complexity,
)
}
}
// excludedDirectory reports whether a walked directory is outside the module.
//
// ".worktrees" holds live git worktrees of this same repository, nested inside
// the root. Each is a near-complete copy of the module, so walking them
// multiplies every count by the number of checkout worktrees and floods the
// HOTSPOT and PACKAGE rows with duplicates of the same declarations.
func excludedDirectory(_, name string) bool {
switch name {
case ".git", ".claude", ".references", "node_modules", "vendor", ".gotmp", ".worktrees":
return true
}
return false
}
func moduleFor(relative string) string {
if relative == "tools" || strings.HasPrefix(relative, "tools/") {
return "tools"
}
return "root"
}
func physicalLines(body []byte) int {
if len(body) == 0 {
return 0
}
lines := bytes.Count(body, []byte{'\n'})
if body[len(body)-1] != '\n' {
lines++
}
return lines
}
func symbolName(function *ast.FuncDecl) string {
if function.Recv == nil || len(function.Recv.List) == 0 {
return function.Name.Name
}
return receiverName(function.Recv.List[0].Type) + "." + function.Name.Name
}
func receiverName(expression ast.Expr) string {
switch value := expression.(type) {
case *ast.Ident:
return value.Name
case *ast.StarExpr:
return "*" + receiverName(value.X)
case *ast.IndexExpr:
return receiverName(value.X)
case *ast.IndexListExpr:
return receiverName(value.X)
default:
return "receiver"
}
}
func statementNodes(node ast.Node) int {
count := 0
ast.Inspect(node, func(candidate ast.Node) bool {
statement, ok := candidate.(ast.Stmt)
if !ok {
return true
}
switch statement.(type) {
case *ast.BlockStmt, *ast.EmptyStmt:
default:
count++
}
return true
})
return count
}
func syntacticComplexity(node ast.Node) int {
value := 1
ast.Inspect(node, func(candidate ast.Node) bool {
switch item := candidate.(type) {
case *ast.IfStmt, *ast.ForStmt, *ast.RangeStmt, *ast.CommClause:
value++
case *ast.CaseClause:
if len(item.List) > 0 {
value++
}
case *ast.BinaryExpr:
if item.Op == token.LAND || item.Op == token.LOR {
value++
}
}
return true
})
return value
}
func sortedKeys(values map[string]*counts) []string {
keys := make([]string, 0, len(values))
for key := range values {
keys = append(keys, key)
}
sort.Strings(keys)
return keys
}
func emitMetric(module, name string, value int) {
fmt.Printf("METRIC\t%s\t%s\t%d\n", module, name, value)
}
func fail(code int, format string, arguments ...any) {
fmt.Fprintf(os.Stderr, "source-metrics: "+format+"\n", arguments...)
os.Exit(code)
}
@@ -1,201 +0,0 @@
---
name: archie-docs-and-writing
description: Maintain Archie's documentation of record and write durable architecture decisions, migration plans, parity matrices, incident and dead-end records, feature ownership and deprecation records, operational runbooks, and documentation reviews. Use when deciding where an Archie fact belongs; reconciling code with `CLAUDE.md`, `docs/architecture`, `docs/prds`, `docs/archive`, or generated contracts; changing `tools/docsgen`; documenting a feature so future maintainers can find its owners, consumers, invariants, superseded paths, deletion gates, evidence, and rollback; or checking documentation authority, drift, links, copied content, and source-artifact hygiene.
---
# Maintain Archie documentation
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
decisions (parked outside this checkout, under
`/work/apps/archie-skills-parked/`),
`archie-architecture-contract` for invariants,
`archie-codebase-discovery` for live entry points,
`archie-failure-archaeology` for incidents,
`archie-config-and-flags`, `archie-build-and-env`, or `archie-run-and-operate`
for runtime/operations facts.
## Use the authority vocabulary
Define a **record of authority** as the one canonical location whose owner may
change a claim.
| 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.
## Use the repository authority map
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 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 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` |
| 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 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.
## Write for future change
Every architecture, feature, or migration record must answer:
- **Responsibility:** What cohesive job exists?
- **Owner:** Which domain, application boundary, or infrastructure adapter owns
its meaning and mutable state?
- **Boundaries:** What is explicitly inside and outside?
- **Consumers:** Which entry points, interfaces, commands, events, config, and
processes depend on it?
- **Invariants:** What must remain true, and where is each enforced?
- **Superseded path:** Which older mechanism becomes redundant?
- **Deletion gate:** What observable proof permits removal?
- **Evidence:** Which symbols, tests, commands, and runtime observations support
the record?
- **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
document says whether each older path remains, delegates, migrates, or is
deleted.
## Cite evidence without freezing line numbers
Prefer: repository-relative path plus exact Go symbol, test name, config key,
workflow job/step, or Markdown heading; a relative Markdown link to the record
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 behaviour.
2. Tests that exercise the relevant production seam.
3. Approved target decision.
4. Comments and summaries corroborated by the first three.
5. Historical or external notes, explicitly dated.
## Maintain component changelogs
Keep every release's notes in `CHANGELOG.md`; a release is one version, and
the components' entries are labelled sections inside it.
`Dockerfile.archied` copies it to `/usr/share/archie/`, and
`internal/releaseannounce.changelogSection` parses a version heading.
Version-heading format is settled as of 2026-09-18: the changelog uses
`## [1.27.0]` with no `v` prefix, `changelogSection` searches for
`## [<version>]`, and `.github/workflows/deploy.yml` gates each release tag with
`grep -q "^## \[$ver\]" CHANGELOG.md`. The earlier
`vX.Y.Z`-vs-`X.Y.Z` contradiction involved `.gitea/workflows/deploy.yml`, which
was dropped (`dd9bddc2 ci: build and push images to GHCR, drop the Gitea
workflow`), so that question is `HISTORICAL`, not `OPEN`. The remaining guard is
the CI shell gate plus `internal/releaseannounce`'s announcer tests
(`TestAnnouncerReportsMissingReleaseSectionWithoutAdvancingState`); the old
`cmd/archied.TestChangelogsTrackGatewayAndRuntimeIndependently` no longer exists.
## Maintain generated contracts
Current behaviour, verified 2026-09-18:
- Tool path is `tools/docsgen`, not `tools/cmd/docsgen`.
- Separate Go module replacing root module with `../`.
- Accepts `--repo-root` and `--out`, plus a `check` subcommand that compares
against the committed artifact without writing. No implemented `data`,
`asyncapi`, or `all` subcommands.
- `currentContractTypes` publishes three top-level contracts and collects
referenced schemas into one JSON object.
- Default output is `docs/data/generated/contracts.json`.
```bash
GOTMPDIR=/tmp GOCACHE=/tmp/archie-docsgen-gocache go -C tools test -mod=readonly ./docsgen -count=1
task docs:check # fails loudly, and names the Go type behind each mismatch
```
`docsgen check` and the `docs:generate`/`docs:check` tasks are implemented, and
`task check` runs `docs:check` — generated drift is gated. `docsgen data`,
`docsgen asyncapi`, and `docsgen all` remain `APPROVED TARGET`.
The check is deliberately non-destructive: it generates into a temporary
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.
## Maintain documentation consumed by the external Astro website
`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/` 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` |
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
grep -rhoE '\]\([^)#]+' docs --include=*.md | sed -E 's/^\]\(//' | sort -u
```
### Enforce source-artifact hygiene
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
ls docs/package.json docs/pnpm-lock.yaml 2>&1 # expect: No such file
ls .github/workflows/ # expect deploy.yml only
```
Historical mentions of VitePress in `docs/architecture/` are deliberate — they
record what was removed. A grep for the word alone is not a failure signal.
Never stage dependency installs, renderer output, generator scratch files,
credentials, absolute paths, wall-clock data, or machine-specific values.
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Docs and Writing"
short_description: "Maintain authoritative Archie documentation"
default_prompt: "Use $archie-docs-and-writing to write or update an authoritative Archie design, migration, incident, ownership, or operations document."
@@ -1,485 +0,0 @@
# Archie durable-writing templates
Use one template at a time. Replace every angle-bracket prompt. Remove unused
sections. Keep facts, decisions, and open questions visibly separate.
## Contents
- [Architecture decision record](#architecture-decision-record)
- [Migration plan and parity matrix](#migration-plan-and-parity-matrix)
- [Incident or dead-end record](#incident-or-dead-end-record)
- [Feature ownership and deprecation record](#feature-ownership-and-deprecation-record)
- [Operational runbook](#operational-runbook)
- [Documentation change review](#documentation-change-review)
- [PRD: open capability design with multi-agent execution](#prd-open-capability-design-with-multi-agent-execution)
## Architecture decision record
```markdown
# <Decision title>
**Status:** Proposed | Approved | Superseded by <link>
**Date:** YYYY-MM-DD
**Owner:** <domain or application boundary>
**Record of authority:** <this document or existing focused document>
**Change-control reference:** <issue/review identifier>
## Decision
<One unambiguous normative statement.>
## Problem and scope
<Describe the problem, the included behavior, and explicit non-goals.>
## Current evidence
| Claim | Evidence |
| ------------------ | ------------------------------------- |
| <CURRENT behavior> | `<path>` — `<symbol/test/config key>` |
## Constraints and invariants
- <Invariant and where it is enforced>
## Consumers and boundaries
| 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 |
## Consequences
<State new responsibilities, dependency direction, state ownership, and
operational effects.>
## Supersession and deletion
- Superseded path: `<path/symbol>` or none
- Compatibility owner: <owner or none>
- Deletion gate: <observable proof>
- Architecture test: <test or OPEN>
## Rollback
<State how code, behavior, and data return safely.>
## Open questions
| Question | Owner | Evidence required | Decision deadline/gate |
| --------------- | ------- | ----------------- | ---------------------- |
| <OPEN question> | <owner> | <measurement> | <gate> |
## Validation
- `<exact command>` — expected <observable result>
```
## Migration plan and parity matrix
```markdown
# <Capability> migration plan
**Status:** Proposed | Approved | In progress | Complete
**Date:** YYYY-MM-DD
**Owner:** <domain>
**Source authority:** <approved target decision>
**Current baseline:** <code paths and runtime composition>
## Outcome
<Describe the final single authoritative path and what becomes easier to
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 |
## Parity matrix
| 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> |
## Slices and gates
### Slice 1 — <small vertical outcome>
- Change: <bounded change>
- Expected evidence: <number/result predicted before implementation>
- Command: `<exact command>`
- Pass: <observable result>
- Branch if not: <diagnostic route>
- Legacy path after slice: Active / Delegating / Read-only / Removable
<Repeat for each independently reviewable slice.>
## Cutover
1. <Prepare compatibility/data>
2. <Change production composition>
3. <Observe explicit health/parity signals>
4. <Disable legacy entry>
5. <Delete only after the deletion gate>
## Deletion gates
| Legacy path | Replacement proof | Consumer-zero proof | Data proof | Removal test |
| --------------- | ----------------- | ------------------- | ---------- | ------------ |
| `<path.Symbol>` | <proof> | <search/inventory> | <proof> | `<command>` |
## Rollback and stop conditions
- Roll back when: <condition>
- Restore: <code/config/data sequence>
- Preserve for diagnosis: <artifacts>
## Remaining open decisions
| Decision | Owner | Evidence needed | Blocks |
| -------- | ------- | --------------- | --------------- |
| <OPEN> | <owner> | <evidence> | <slice/cutover> |
```
## Incident or dead-end record
````markdown
# <Symptom or rejected approach>
**Status:** Resolved | Mitigated | Rejected | Reopened
**Observed:** YYYY-MM-DD
**Last verified:** YYYY-MM-DD
**Owner:** <capability>
**Related changes:** <commit/issue/PR identifiers>
## Symptom and impact
<State the observable failure, affected path, and cost. Do not begin with the
proposed fix.>
## Reproduction
```text
<exact non-secret command or event sequence>
```
Expected: <result>
Observed: <result>
## Investigation chronology
| Time/order | Hypothesis | Prediction | Evidence | Result |
| ---------- | ------------ | ---------------------- | -------------------- | -------------------- |
| 1 | <hypothesis> | <expected observation> | `<command/log/test>` | Confirmed / Rejected |
## Root cause
<Name the owning code path and causal mechanism. Separate cause from trigger.>
## Attempted or rejected fixes
| Fix | Why plausible | Evidence against it | Status |
| ---------- | ------------- | ----------------------- | ------------------- |
| <approach> | <reason> | <test/runtime evidence> | Rejected / Reverted |
## Resolution and invariant
- Resolution: <what changed>
- Preserved invariant: <what must not regress>
- Regression test: `<test name/path>`
- Operational signal: <log/metric/state>
## Reopen condition
<State the evidence that would justify revisiting the settled result.>
````
## Feature ownership and deprecation record
```markdown
# <Feature/capability> ownership
**Status:** Current | Migrating | Deprecated | Removed
**Date:** YYYY-MM-DD
**Behavior owner:** <domain>
**State owner:** <domain/repository>
**Composition owner:** <application boundary>
## Responsibility and non-responsibilities
- Owns: <cohesive behavior>
- Does not own: <adjacent concerns>
## 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> |
## Consumers
| 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>` |
## Duplicate and superseded paths
| Path | Same operation? | Disposition | Deletion gate |
| --------------- | -------------------------- | ---------------------------------- | ------------- |
| `<path.Symbol>` | Yes / No, because <reason> | Keep / Delegate / Migrate / Delete | <proof> |
## Change checklist
- [ ] Trace every entry point and consumer.
- [ ] Decide whether the feature deprecates earlier work.
- [ ] Keep one owner for mutable state.
- [ ] Add failure-path and architecture tests.
- [ ] Prove the replacement before deleting the old path.
- [ ] Update generated reference from owned definitions.
```
## Operational runbook
```markdown
# Operate <service/capability>
**Status:** Current
**Last verified:** YYYY-MM-DD
**Environment:** <local/staging/production>
**Owner:** <operator/capability>
**External sources:** <host/config/dashboard; no secrets>
## Purpose and safety boundary
<State what this runbook operates and what requires separate authorization.>
## Preconditions
- <access/tool/config precondition>
- Secret names only; never secret values
## Start or change
1. Run `<exact command>`.
2. Expect `<observable output/state>` within `<bounded interval>`.
3. If `<alternate result>`, stop and route to `<diagnostic branch>`.
## Health and outputs
| Signal | Location/command | Healthy result | Unhealthy branch |
| -------- | ---------------- | -------------- | ---------------- |
| <signal> | `<command/path>` | <result> | <action> |
## Rollback
1. <Restore previous code/config/data>
2. Run `<health command>`.
3. Preserve <logs/artifacts> for incident review.
## Known failure modes
| 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
# Documentation review: <scope>
**Date:** YYYY-MM-DD
**Reviewer:** <name/session>
**Changed authority:** <path or none>
## Classification
| 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> |
## Authority and duplication checks
- [ ] One record of authority owns each claim.
- [ ] Current and target behavior are separated.
- [ ] Open questions remain visibly open.
- [ ] Historical material is not used normatively.
- [ ] Generated output was not hand-edited.
- [ ] Symbols and headings replace durable line-number citations.
## Maintainability checks
- [ ] Responsibility, owner, boundaries, consumers, and invariants are explicit.
- [ ] Superseded paths and deletion gates are named.
- [ ] Evidence, rollback, and unresolved questions are actionable.
- [ ] A zero-context engineer can locate the complete feature path.
## Validation evidence
| 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
For `docs/prds/*.md` — CLAUDE.md's "no settled design exists" doc. The point
of this template is that a cheaper/faster model can implement straight from
it without re-deriving architecture: every decision the epic left open gets
made here, not deferred again, and every file an implementer touches is
named before any bead is picked up. `docs/prds/image-capability-contract.md`
is the worked example this template was extracted from — read it once for
the shape before writing a new PRD from a blank page.
The three failure modes this template exists to prevent:
- **Deferred decisions posing as scope.** "Hosted provider implementation is
a separate bead" is not a design decision, it's a missing one. If an open
question blocks an implementer, decide it here, in the PRD — not "this bead
will decide it later," which is how the same question gets re-opened by
every bead that touches it.
- **Assumed gaps.** Before writing a section for "what's missing," grep for
it. `image-capability-contract.md`'s delivery section exists mostly because
the pipeline it needed already shipped for video — the section reports
that, instead of specifying new plumbing nothing required.
- **Task lists a model can't execute standalone.** A subtask is not "wire the
delivery path"; it's the file, the interface it must satisfy, and the
existing call site that already proves the pattern (`internal/tools/minimax/tool.go`,
not "a tool like the video one").
```markdown
# <Capability> capability design
Epic: `<bd id>` / GitHub `#<epic number>` ("<epic title>").
<One paragraph: what shipped already and is settled (link its section
below), what this document newly decides, and what stays explicitly
out of scope. If a prior narrower doc already covers part of this
capability, say so and extend it — do not start a second document for
the same epic.>
## Problem
<What's missing today, with the exact "grep and found nothing" evidence,
not an assertion.>
## Design
<The settled contract/type shape. Code blocks over prose where a type
signature says more than describing it would.>
## <Sub-feature N> (`#<issue>`)
One section per sibling bead the epic lists as separate scope. Each one:
- **Decision, not a deferral.** If the epic or a prior doc left this open,
decide it here and say why in one paragraph, citing what's actually in
the tree (a similar client already in the codebase, an existing config
convention, an interface already proven by another feature). "Decide and
record which at that bead's own design-doc step" is the sentence this
template exists to stop someone from writing twice.
- **Call site**, named exactly: `<package/file>`, the function/type it adds
or extends, and the existing analogous call site it follows (never "a
handler like the others" — name the actual one).
- **Reuse check.** Grep before specifying new plumbing. State what already
exists and what's actually new, the way a delivery pipeline already
proven by one media type doesn't need re-inventing for a second.
- **Error/failure mapping**, as a table, when the sub-feature crosses a
provider/backend boundary: condition → contract error, so an implementer
never invents a new sentinel mid-way through.
- **Testing.** What's fakeable vs. what needs a real backend, and which
gate (`task check` vs. a documented manual smoke command) each belongs to.
## Call site inventory
| 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
implementer greps this instead of re-deriving it, and a reviewer can tell
at a glance whether a PR touched something the design didn't name.
## Execution: multi-agent team breakdown
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> |
Pick lenses from the five in `.claude/workflows/council.js`
(`boundary`, `contract`, `deletionist`, `operator`, `maintainer`) by what the
slice actually risks getting wrong, not all five by default — a
generate-and-poll HTTP client mostly risks failure-mode gaps
(`lens-operator`), not domain-boundary violations. Run `/council` with
`--lenses <picked>` once the implementation is gate-clean, before opening
the PR for human review, same as any other open-decision residue at the
end of a session.
An implementer working one row needs only: this doc's matching sub-feature
section, the call-site inventory, and the linked issue's acceptance
criteria. It should not need the rest of the epic's history — that's the
signal the PRD is thorough enough to hand to a faster/cheaper model.
## File and link the beads
For each sub-feature issue already filed against the epic (or newly filed
if the epic didn't pre-file its sub-issues):
- Issue body links back to this doc's matching section by heading, not by
restating the design — `bd update <id> --description` and, if the issue
also lives on the forge, keep both current (check whether this repo's
sync command actually propagates a description edit before trusting it
updated both; direct edit on both sides is the fallback).
- Issue keeps its own acceptance criteria as the authoritative "done"
check — the PRD section is how, the issue's criteria are whether.
- 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.
```
@@ -1,242 +0,0 @@
---
name: archie-domain-reference
description: "Use when naming, designing, reviewing, documenting, tracing, or migrating Archie concepts such as Agent, Identity, user, Message, Conversation, work intake, WorkflowExecution, plugin engines, channels, events, policy, forge, worktrees, or gates; when current task/gateway/store vocabulary conflicts with the approved architecture; or when a feature risks crossing domain ownership boundaries. Provides project-specific current-to-target mappings, ownership rules, lifecycle language, and glossary checks. Do not use for database API mechanics, general code tracing, config enumeration, debugging, or operations."
---
# Archie Domain Reference
Use one meaning for each noun. Keep external-system words at adapters, keep
domain meaning with its owner, and mark migration state explicitly.
## Classify every statement
As of 2026-09-18, Archie is partway through the domain migration: some approved
target packages now exist and are production-wired (`internal/domain/messaging`,
`internal/domain/workflow`, `internal/domain/workintake`, `internal/app`,
`internal/eventbus`, `internal/infrastructure`), while others remain target-only
(`internal/domain/agent`, `internal/domain/identity`, `internal/policy`). Never
blend the two.
| 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:
```text
CURRENT: task.Task persists one mutable Stage string.
APPROVED TARGET: WorkflowExecution records StepExecution history.
OPEN: the exact schema and Go API for that history.
```
Read status markers:
```bash
sed -n '1,180p' docs/prds/01-project-management.md
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, 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 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/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. |
Do not equate an inbound Message with work. An Agent may answer, use
capabilities, retain information, or propose work without creating a
WorkflowExecution.
Target flow:
```text
external payload -> channel adapter -> canonical Message and Conversation
-> selected Agent turn -> optional proposed work -> Work Intake admission
-> accepted work request -> Agent System selects Workflow version -> WorkflowExecution
```
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/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. |
Use `WorkflowExecution` in domain contracts, architecture, generated reference.
Retain `task` only for Task build tool, forge product nouns in adapters,
informal prose.
### Interpret the current lifecycle exactly
**CURRENT** `task.Task` states:
```text
queued -> running
running -> waiting_human | pr_open | merged | parked | closed_wont_do
waiting_human -> queued | closed_wont_do
parked -> queued | dead
pr_open -> merged | rejected
running after crash -> queued
```
Do not claim enforced. `Store.Transition` now guards on `from`
(→ `storecontract.ErrStaleTransition`) and writes status plus
history in one transaction; the sentinel crosses the State Store gRPC boundary.
See `internal/infrastructure/postgres/store.go`.
```bash
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 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` 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.
```bash
rg -n 'type MemoryProvider|Initialize\(|type Config struct|MEMORY.md|USER.md|AgentID|IdentityID|Scope' internal/memory
```
## 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 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.
```bash
go test ./internal/plugin -run 'Test(EngineFamilyInspectionRejectsInvalidShapes|PluginInterfaceExists)' -count=1
```
## 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. |
| **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`,
`internal/infrastructure`, and `internal/app` exist; only `internal/policy`
does not. `internal/domain/agent` and `internal/domain/identity` are still
target-only.
```bash
for p in internal/domain internal/eventbus internal/policy internal/infrastructure internal/app; do test -d "$p" && echo "$p CURRENT" || echo "$p TARGET-ONLY"; done
```
## 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. |
Model never runs git directly. Worktree operations are daemon-owned.
## 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. |
`migration-decisions.md` leaves memory, tools, workspaces, gates, storage,
events, web UI, containers, RPC, release management, scheduling pending.
## 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. |
Reject in review: a second parallel model without bounded cutover; status string
copied into consumer; mutable display name as durable ID; service bag passed
into domain/plugin/WorkflowStep; lifecycle state written by adapter/UI/transport;
domain importing concrete persistence/NATS/forge SDK/container/config DTO types;
test proving only new path while old production path remains active.
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Domain Reference"
short_description: "Use Archie terminology without boundary mistakes"
default_prompt: "Use $archie-domain-reference to classify these Archie concepts and map current code terms to their approved target owners."
@@ -1,230 +0,0 @@
---
name: archie-failure-archaeology
description: "Reconstruct archie-core failures, dead ends, reversals, rejected fixes, and branch-only repairs from read-only git history and live call sites. Use when a symptom resembles a past production outage, deadlock, retry loop, protocol mismatch, configuration regression, worktree/cache fault, unsafe cleanup, linter semantic change, artifact leak, or recurring baseline repair; also use before reviving an old approach, declaring a fix reverted, or deciding whether a repair is current, settled, conditional, superseded, open, or merely a candidate."
---
# Archie failure archaeology
Stop the project from paying twice for the same lesson. Reconstruct what
happened from checked-out code, tests, configuration, and commit graph.
Treat commit prose as a lead, not proof. Preserve uncertainty.
All volatile observations are dated **2026-09-18** (HEAD `2e1e1549`); the merge-shape
section under Step 4 is dated **2026-09-20** (HEAD `1b0133d7`).
Route to `archie-debugging-playbook` for active symptoms,
`archie-codebase-discovery` for deep caller tracing.
## 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 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."
## Run the archaeology workflow
### 1. Freeze the observation point
```sh
git rev-parse HEAD
git status --short
git log -1 --date=iso-strict --format='%H %ad %s'
git branch -a --no-color --no-merged HEAD
```
### 2. Name the exact symptom
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 behaviour before history
```sh
rg -n '<symptom|symbol|setting|error>' cmd internal config*.toml docker-compose.yml docs
git log --all --date=iso-strict --format='%H %ad %s' -- <affected-paths>
git blame -L <start>,<end> -- <live-file>
```
### 4. Prove the historical transition
```sh
git show --no-ext-diff --format=fuller --stat <commit>
git show --no-ext-diff -U80 <commit> -- <affected-paths>
.agents/skills/archie-failure-archaeology/scripts/on-main.sh <commit>
git branch -a --contains <commit>
```
#### `--is-ancestor` is blind to squash and rebase merges
`git merge-base --is-ancestor` answers a topology question: is this exact commit
object an ancestor. **Squash and merge** always mints a new commit, and **Rebase
and merge** mints new ones whenever the branch had to be replayed, so both
orphan the SHA a branch holds. `git branch -a --contains` and
`git branch -r --no-merged` are blind in the same way.
As of **2026-09-20** (`origin/main` `1b0133d7`) this repository squash-merges —
the last fifteen merged pull requests are all squashes, so the raw check is a
false negative for every one of them. It was sound for everything merged up to
**2026-09-18**, which used merge commits.
Use `scripts/on-main.sh`, which keeps `--is-ancestor` as the offline fast path
and otherwise asks the GitHub API, where merge state is recorded independently
of the commit graph:
```sh
.agents/skills/archie-failure-archaeology/scripts/on-main.sh <ref> [base-ref]
```
`<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** |
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
still reads `not-landed` for the original commit.
Read parent version when failure is semantic:
```sh
git show <commit>^:<path>
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 |
### 5. Reproduce narrowly, then route
```sh
env GOCACHE=/tmp/archie-archaeology-gocache GOTMPDIR=/tmp go test ./internal/<package> -run '^TestName$' -count=1 -v
```
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 |
## 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 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: `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 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? |
## 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 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. |
## Keep unmerged work as dated candidates
As of **2026-09-18**, the six `fix/4x` and `feat/5x`/`feat/75` candidate
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 |
Verify candidate state:
```sh
git branch -r --no-merged HEAD
git log -1 --date=iso-strict --format='%H %ad %s' <branch>
git diff --stat HEAD...<branch>
.agents/skills/archie-failure-archaeology/scripts/on-main.sh <branch> HEAD
```
@@ -1,4 +0,0 @@
interface:
display_name: "Archie Failure Archaeology"
short_description: "Avoid repeating Archie failure history"
default_prompt: "Use $archie-failure-archaeology to trace this symptom through Archies proven incidents before proposing a fix."
@@ -1,113 +0,0 @@
#!/bin/sh
# on-main.sh -- did this ref land on the trunk, even when it was squash- or
# rebase-merged?
#
# `git merge-base --is-ancestor` answers a topology question: is this exact
# commit object an ancestor. GitHub's "Squash and merge" always mints a new
# commit, and "Rebase and merge" mints new commits whenever the branch had to
# be replayed, so both orphan the SHA your branch holds. The raw check then
# reports a landed repair as never-landed, and `git branch -a --contains` is
# blind in exactly the same way.
#
# This wrapper keeps `--is-ancestor` as the offline fast path and falls back to
# the GitHub API, which records merge state independently of the commit graph.
#
# usage: on-main.sh [-q] <ref> [base-ref]
#
# <ref> commit, tag, or branch to test
# [base-ref] trunk to test against (default: origin/main)
# -q print nothing; report through the exit code only
#
# exit 0 landed on <base-ref>, by ancestry or by a merged pull request
# exit 1 not landed: known to GitHub, but in no merged pull request
# exit 2 undetermined: bad ref, no gh, offline, or never pushed to GitHub
# exit 127 git is missing
#
# exit 2 is not a negative. Branch on the code explicitly; `if on-main.sh <ref>`
# folds it into "not landed", which is the error this helper exists to prevent.
set -eu
quiet=0
while [ "$#" -gt 0 ]; do
case "$1" in
-q | --quiet)
quiet=1
shift
;;
--)
shift
break
;;
-*)
printf 'on-main: unknown option %s\n' "$1" >&2
printf '%s\n' 'usage: on-main.sh [-q] <ref> [base-ref]' >&2
exit 2
;;
*)
break
;;
esac
done
if [ "$#" -lt 1 ] || [ "$#" -gt 2 ]; then
printf '%s\n' 'usage: on-main.sh [-q] <ref> [base-ref]' >&2
exit 2
fi
ref=$1
base=${2:-origin/main}
say() {
[ "$quiet" -eq 1 ] || printf '%s\n' "$1"
}
command -v git >/dev/null 2>&1 || {
printf '%s\n' 'on-main: git is required' >&2
exit 127
}
sha=$(git rev-parse --verify --quiet "${ref}^{commit}") || {
say "undetermined: $ref does not resolve to a commit in this repository"
exit 2
}
git rev-parse --verify --quiet "${base}^{commit}" >/dev/null 2>&1 || {
say "undetermined: base ref $base does not resolve; fetch it, or name the trunk explicitly"
exit 2
}
if git merge-base --is-ancestor "$sha" "$base" 2>/dev/null; then
say "landed: $sha is an ancestor of $base (topology)"
exit 0
fi
# Not an ancestor. The SHA may still have landed if GitHub rewrote it at merge
# time, so ask the service that recorded the merge rather than the commit graph.
command -v gh >/dev/null 2>&1 || {
say "undetermined: $sha is not an ancestor of $base, and gh is absent, so a squash or rebase merge cannot be ruled out"
exit 2
}
merged=$(
gh api "repos/{owner}/{repo}/commits/$sha/pulls" \
--jq '[.[] | select(.merged_at != null)] | length' 2>/dev/null
) || {
say "undetermined: $sha is not an ancestor of $base, and GitHub could not answer for it (offline, unauthenticated, or never pushed)"
exit 2
}
case "$merged" in
'' | *[!0-9]*)
say "undetermined: GitHub returned an unreadable answer for $sha"
exit 2
;;
0)
say "not-landed: $sha is not an ancestor of $base and belongs to no merged pull request"
exit 1
;;
*)
say "landed: $sha is not an ancestor of $base, but GitHub records it in $merged merged pull request(s) -- a squash or rebase merge rewrote the SHA"
exit 0
;;
esac
@@ -1,215 +0,0 @@
---
name: archie-run-and-operate
description: "Run and observe Archie safely with a host daemon and the repository's Docker Compose NATS service. Use when starting or stopping archied, running an archie-agent NATS worker, checking readiness, following logs, locating task state/worktrees/memory/container volumes, understanding inprocess/subprocess/NATS execution, inspecting the image pipeline, or planning an operational rollback without changing architecture."
---
# Run and operate Archie
Use this runbook to operate the implementation that exists on **2026-09-18**
(HEAD `2e1e1549`). Treat source and tests as current; treat `docs/archive/` as
history.
## Define the process shapes
| 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
Assume every daemon start can change local and external state.
- Obtain explicit authority for config, forge identity, repositories, NATS
account, Docker host, and deployment host before starting.
- Never use production tokens for a smoke test.
- Do not call `archied -once` as a dry run. It accepts invitations, verifies
push access, polls the forge, enqueues/labels work, reconciles PRs, processes
tasks, and then exits.
- Do not expose the dashboard publicly. It has no authentication, and
`POST /api/tasks/clear` deletes terminal task records.
- Do not print secret values. Record environment-variable **names**, config
checksums, image digests, and paths instead.
- Stop with `Ctrl-C`, `SIGTERM`, or Compose. Do not use `SIGKILL` unless graceful
shutdown has demonstrably failed.
There is no config-only or dry-run flag.
## Know the command surfaces
### `archied`
| 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 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.
## Execution mode
| 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
```bash
task build
task --list
./bin/archied -h
./bin/archie-agent -h
```
Choose an explicitly approved config:
```bash
ARCHIE_CONFIG=/absolute/path/to/config.toml
test -r "$ARCHIE_CONFIG"
./bin/archied -config "$ARCHIE_CONFIG"
```
Expect JSON logs on stderr. Require: `nats connected` when `[nats]` configured;
`workflow registry built`; `memory manager started`; `web ui listening` unless
`web.listen = "off"`; gateway-start messages for configured channels;
`archied running` after startup verification. Absence of `archied running` means
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 its store connections.
## Run a standalone NATS worker
```bash
NATS_URL=nats://127.0.0.1:4222 ./bin/archie-agent
```
Require both `nats connected` and `archie-agent ready`. Stop with `Ctrl-C`.
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. |
Prefer the narrow start:
```bash
docker compose up -d nats
```
Read-only observations:
```bash
docker compose ps
docker compose logs --tail=200 nats
docker compose exec -T nats wget -q -O - http://localhost:8222/healthz
```
```bash
curl -fsS http://127.0.0.1:8484/api/summary
curl -fsS http://127.0.0.1:8484/api/tasks
```
Wait for the NATS healthcheck, then start `archied` on the host. Require the
configured host supervisor to report it running and verify the dashboard API
as the daemon readiness gate.
Stop with:
```bash
task docker-down
```
Never add `-v` during routine shutdown. The Compose `agent` service is a
build-profile image definition, not a long-running service. Actual task workers
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 | 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
each task worktree into the agent container it creates.
## Understand NATS and container observation
The `ARCHIE_TASKS` JetStream stream uses file storage and work-queue retention
for `archie.task.>` and `archie.agent.>`.
| 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,
workers join Docker's default bridge and cannot resolve `nats`. Initial
`ErrNoResponders` is retried for 20s at 250ms intervals.
If `nats.token_env` is configured, `archied` refuses startup when that variable
is empty. It injects the resolved value as `NATS_TOKEN` into task containers.
It forwards only configured provider-key variables.
## Fence current operational limitations
Open limitations until code/tests prove otherwise:
- `subprocess` + default `archie-agent` is protocol-incompatible.
- 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.
- Container workflow builds `TaskContext` without event bus.
- SSE clients drop when channel full; replay at most 200 events.
- Dashboard unauthenticated, includes mutating clear endpoint.
## Understand deployment and rollback seams
`.github/workflows/deploy.yml` gates on the release tags, then builds/pushes
`archied:latest` and `archie-agent:latest` plus a versioned
`linux/amd64` distribution zip attached to a GitHub Release. It injects
component versions into labels/metadata and runs the quality gate before the
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; 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.
@@ -1,4 +0,0 @@
interface:
display_name: "Run and Operate Archie"
short_description: "Run Archie safely and locate its operational state"
default_prompt: "Use $archie-run-and-operate to start Archie locally, inspect its runtime state, and stop it safely."
-102
View File
@@ -1,102 +0,0 @@
---
name: archie-web-ui
description: "Develop, review, or redesign archie-core's dashboard web UI (ui/). Load when adding or changing Vue components, pages, views, styling, theming, layout, or interaction patterns under ui/src; when auditing UI accessibility or contrast; or when porting design prototypes (e.g. React mockups) into the Vue dashboard. Carries stack facts, design-system rules, and the operational-tool tone required here."
---
# Web UI development (ui/)
Archie's dashboard is an **operational supervision tool** for senior developers
watching an autonomous orchestrator: quiet, dense, scannable, work-focused.
Not editorial, not marketing, not playful. Every rule below serves that.
## Stack facts (do not fight these)
- 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; 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
(see the header comment in `ui/src/style.css` for why builds are
content-coupled to the bundle).
- Gates: `task ui` (build), `task test:ui` (node --test over DOM-building
primitives in `ui/test/`), `vue-tsc` via `npm run typecheck`. `task check`
includes all of them.
- The dashboard is a LAW asset built from `ui/dist` — a Go-side embed. A UI
change is not done until `task ui` regenerates it and the commit carries it.
## Design-system rules
- **Tokens only.** Semantic CSS variables from `ui/src/style.css`
(`--primary`, `--ok`, `--muted`, ...). Never a raw hex in a component, never
a hue-named token. Dark is default; light defines the same variable set and
is a first-class theme, not an afterthought. Density is a single knob
(`[data-density="compact"]` tightens the spacing scale) — do not add
per-component density conditionals.
- **Icons, not text-as-decoration.** Buttons for clear commands use lucide
icons (icon-only where the symbol is familiar, with a tooltip naming it);
segmented controls for modes, toggles/checkboxes for binary settings,
selects/menus for option sets, tabs for views.
- **Cards 8px radius or less; no cards inside cards;** page sections are
full-width bands or unframed layouts, not floating cards. No gradient orbs,
bokeh blobs, or decorative backgrounds.
- **Stable dimensions.** Tables, tiles, toolbars, sparklines, and icon buttons
get fixed/constrained sizing so dynamic content (long titles, loading
states, big numbers) cannot shift layout. Text never overflows its
container on any viewport; wrap or downsize before it can.
- **No viewport-scaled font sizes, no negative letter-spacing.**
- **No one-note palettes.** If a screen reads as a single hue family
(e.g. all-violet), rebalance with neutrals and status colours rather than
more of the accent.
- **No in-app prose explaining the app** — no help text describing features,
keyboard shortcuts, or how to use a control. If a control needs explaining,
redesign the control.
- **No landing pages.** Every route opens the working experience directly.
## Tone & content
- Match copy to the domain: state names, gate results, timings, token counts —
concrete operational nouns, not conversational flourishes. A header states
system status ("Cluster operational · 4 awaiting intervention"), not a
greeting.
- Every human-actionable state (parked, gate failed, needs review) shows the
reason inline and links to the exact place to act on it (the failing log,
the gate output) — never just a status label.
- High-frequency background telemetry is grouped/summarised in activity feeds
("session-memory · 24 background cycles"), with high-signal events
(stage finished, gate failure, task parked) visually elevated.
## Accessibility bar
- WCAG AA minimum on all text: secondary/metadata labels must clear 4.5:1
against their actual background — audit the token, not the element. If a
muted token fails, fix the token value (one file), not individual spots.
- Log output, hashes, and code are monospace in a strict grid; do not put
rounded pill badges inside raw log lines (breaks monospace alignment).
Truncated stack traces fold into expandable blocks.
- Controls that filter or toggle (log level, wrap, follow, search) live in a
sticky toolbar inside the pane they affect.
## Porting design prototypes
External mockups (Gemini, Figma, React `.tsx` prototypes) are **specs, not
code**. This app is Vue; translate layout, hierarchy, and interaction
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 for the maintainer. Web UI design is not tracked in
`docs/prds/`; record the decision on the bead and in `docs/design/`.
+13 -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,9 @@ 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
agent:
profile: team-maintainer
+99 -48
View File
@@ -15,11 +15,11 @@ on:
# last one's images matter (each job pushes its image tags), so cancel a
# superseded run rather than let it fight for resources it can't use.
#
# Keyed on the commit, not github.ref: `git push --follow-tags` pushes
# main plus both archied/v* and archie/v* tags in one go, and all three
# refs point at the same commit -- on.push matches branches and tags
# both, so a single release push otherwise fires three redundant builds
# of identical content that a ref-keyed group can't see as the same work.
# Keyed on the commit, not github.ref: a release push lands main and its
# tag in one go, both pointing at the same commit -- on.push matches
# branches and tags both, so a single release push otherwise fires
# redundant builds of identical content that a ref-keyed group can't see
# as the same work.
concurrency:
group: deploy-${{ github.sha }}
cancel-in-progress: true
@@ -30,7 +30,7 @@ permissions:
jobs:
gate:
runs-on: ubuntu-latest
runs-on: self-hosted
outputs:
archied_version: ${{ steps.release_tag.outputs.archied_version }}
steps:
@@ -66,28 +66,13 @@ jobs:
- name: Install quality tools
run: |
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(cat .golangci-version)
go install mvdan.cc/gofumpt@v0.11.0
go install github.com/go-task/task/v3/cmd/task@v3.48.0
- 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
@@ -97,10 +82,30 @@ jobs:
- name: Install ripgrep
run: sudo apt-get update && sudo apt-get install -y --no-install-recommends ripgrep
# Extensions run in an unprivileged user and network namespace, which
# Ubuntu 24.04 runners forbid through AppArmor by default.
- name: Allow unprivileged user namespaces
run: |
if [ -e /proc/sys/kernel/apparmor_restrict_unprivileged_userns ]; then
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
fi
unshare --user --map-root-user --net true
# The gate's uncached `go test ./...` runs the Docker-backed tests that
# -short skips, and those start a container from alpine:3. A fresh runner
# has no such image, so the suite failed on "No such image: alpine:3".
- name: Pull test container images
run: docker pull alpine:3
- name: Quality gate
run: |
go fix ./...
golangci-lint fmt
# The formatter sequence has one owner: task fmt, which drives go fix
# to a fixpoint and then the configured lint formatters. This step
# used to inline its own single `go fix ./...`, which leaves the
# redundant loop-variable copy that copyloopvar rejects -- the hazard
# of archie-core-wwho, surfacing here as a spurious git-diff failure
# (archie-core-6kda).
task fmt
git diff --exit-code
bash tools/proto.sh lint
bash tools/proto.sh check
@@ -159,9 +164,9 @@ jobs:
echo "This commit is not a release, so the images are published as :edge and sha-<sha>; :latest keeps naming the newest release."
fi
build-and-push:
archied-image:
needs: gate
runs-on: ubuntu-latest
runs-on: self-hosted
steps:
- name: Checkout
uses: actions/checkout@v4
@@ -251,7 +256,45 @@ jobs:
cache-from: type=gha,scope=archied
cache-to: type=gha,mode=max,scope=archied
agent-image:
outputs:
agent_digest: ${{ steps.agent.outputs.digest }}
needs: gate
runs-on: self-hosted
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
# Annotated tags: dereference to the commit, as archied-image does.
- name: Resolve the commit this ref points at
id: commit
run: |
sha="$(git rev-parse "${GITHUB_REF}^{commit}")"
echo "sha=$sha" >> "$GITHUB_OUTPUT"
echo "short=${sha:0:12}" >> "$GITHUB_OUTPUT"
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to GHCR
run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
- name: Resolve runtime version
id: versions
run: |
RUNTIME_TAG="$(git tag --points-at HEAD --list 'archie/v*' | sort -V | tail -1)"
RELEASE_TAG="$(git tag --points-at HEAD --list 'v*' | sort -V | tail -1)"
RUNTIME_VERSION="${RUNTIME_TAG#archie/}"
[ -n "$RUNTIME_VERSION" ] || RUNTIME_VERSION="${RELEASE_TAG#v}"
echo "runtime_tag=$RUNTIME_TAG" >> "$GITHUB_OUTPUT"
echo "release_tag=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
echo "runtime=$RUNTIME_VERSION" >> "$GITHUB_OUTPUT"
- name: Build and push archie-agent
id: agent
if: steps.versions.outputs.runtime_tag != '' || steps.versions.outputs.release_tag != ''
uses: docker/build-push-action@v6
with:
@@ -267,16 +310,12 @@ jobs:
cache-to: type=gha,mode=max,scope=archie-agent
# Packages every host-run binary (archied, archie-gateway,
# archie-state-store, archie-ui, archie-messaging, archie-playbooks) as a
# archie-state-store, archie-ui, archie-messaging) as a
# linux/amd64 zip for a
# non-Docker install. Independent of build-and-push: it never touches the
# archied/archie-agent image jobs, and a gateway-only release (no
# archie/v* tag) still produces this zip -- it's keyed to the archied tag
# alone. archie-agent is deliberately excluded: it only ever runs inside
# the Docker image build-and-push already publishes, never as a host
# binary (archie-core-8cda.4.7.1).
# non-Docker install. It waits only for the agent image, whose digest
# release.json pins; archie-agent itself never ships as a host binary.
dist-zip:
needs: gate
needs: [gate, agent-image]
# Not gated on github.ref. A release is pushed as main plus both tags at
# one SHA, the concurrency group below collapses those into a single run,
# and the survivor is whichever ref happened to start last -- for
@@ -285,7 +324,7 @@ jobs:
# the ref that won the race, and skip only when there is genuinely no
# archied tag at HEAD.
if: needs.gate.outputs.archied_version != ''
runs-on: ubuntu-latest
runs-on: self-hosted
# Least privilege: the workflow default is contents:read, and only this
# job needs to write, to create the Release and attach the zip to it.
permissions:
@@ -321,9 +360,9 @@ 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/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 }}"
ldflags="-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
for cmd in $(jq -r '.required_topology.units[]' release.json); do
go build -ldflags "$ldflags" -o "dist/$cmd" "./cmd/$cmd"
done
@@ -333,19 +372,27 @@ jobs:
set -e
name="archie-core-archied-v${{ steps.version.outputs.version }}-linux-amd64"
mkdir -p "$name"
cp dist/archied dist/archie-gateway dist/archie-state-store dist/archie-ui dist/archie-messaging dist/archie-playbooks "$name/"
for cmd in $(jq -r '.required_topology.units[]' release.json); do
cp "dist/$cmd" "$name/"
done
cp deployments/INSTRUCTIONS.md CHANGELOG.md "$name/"
digest='${{ needs.agent-image.outputs.agent_digest }}'
test -n "$digest"
jq --arg image "ghcr.io/samcharles93/archie-agent@$digest" '. + {agent_image: $image}' release.json > "$name/release.json"
# README.md doesn't exist yet in this repo; include it once it does
# rather than fail the release on its absence.
[ -f README.md ] && cp README.md "$name/"
zip -r "$name.zip" "$name"
sha256sum "$name.zip" > SHA256SUMS
echo "name=$name" >> "$GITHUB_OUTPUT"
- name: Upload distribution zip
uses: actions/upload-artifact@v4
with:
name: ${{ steps.zip.outputs.name }}
path: ${{ steps.zip.outputs.name }}.zip
path: |
${{ steps.zip.outputs.name }}.zip
SHA256SUMS
retention-days: 90
# A Release is what an operator can actually download from; the
@@ -354,17 +401,21 @@ jobs:
# zip was produced and then stranded -- the only Release on this repo
# (archied/v1.22.0) was created by hand and carries no asset at all.
#
# Attached to the *archied* tag because the zip is named and versioned
# for archied, and `--follow-tags` pushes both tags at one commit.
# Attached to the release's v* tag, or the archied tag for a release
# cut before the single release stream.
# --generate-notes is deliberately not used: the changelog section is
# the release's own reviewed prose, and the tag/changelog gate above
# already guarantees it describes this version.
- name: Publish GitHub Release with the distribution zip
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# GITHUB_TOKEN cannot write to another repository.
GH_TOKEN: ${{ secrets.RELEASES_TOKEN }}
run: |
set -e
tag="archied/v${{ steps.version.outputs.version }}"
tag="v${{ steps.version.outputs.version }}"
if ! git ls-remote --exit-code --tags origin "refs/tags/$tag" >/dev/null; then
tag="archied/v${{ steps.version.outputs.version }}"
fi
version="${{ steps.version.outputs.version }}"
# The release body is this version's changelog section, not the whole
# file: from its "## [x.y.z]" heading to the next "## [" heading.
@@ -384,12 +435,12 @@ jobs:
# Idempotent: --clobber replaces the asset and leaves the notes
# alone, so a re-run of this job (a retried or superseded deploy)
# cannot fail on an existing Release or duplicate the zip.
if gh release view "$tag" >/dev/null 2>&1; then
gh release upload "$tag" "${{ steps.zip.outputs.name }}.zip" --clobber
if gh release view "$tag" -R samcharles93/archie-releases >/dev/null 2>&1; then
gh release upload "$tag" -R samcharles93/archie-releases "${{ steps.zip.outputs.name }}.zip" SHA256SUMS install.sh --clobber
else
gh release create "$tag" \
gh release create "$tag" -R samcharles93/archie-releases \
--title "archied v$version" \
--notes-file "$notes" \
"${{ steps.zip.outputs.name }}.zip"
"${{ steps.zip.outputs.name }}.zip" SHA256SUMS install.sh
fi
echo "published $tag with ${{ steps.zip.outputs.name }}.zip"
+10 -19
View File
@@ -14,12 +14,19 @@ concurrency:
jobs:
check:
runs-on: ubuntu-latest
runs-on: self-hosted
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Verify extension namespace support
run: |
if [ -e /proc/sys/kernel/apparmor_restrict_unprivileged_userns ]; then
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
fi
unshare --user --map-root-user --net true
- uses: actions/setup-go@v5
with:
go-version-file: go.mod
@@ -33,28 +40,12 @@ jobs:
- name: Install quality tools
run: |
go install github.com/go-task/task/v3/cmd/task@v3.48.0
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(cat .golangci-version)
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: |
@@ -64,5 +55,5 @@ jobs:
- name: Run definitive gate
run: |
task check
task --concurrency 1 check
git diff --exit-code
+3 -5
View File
@@ -36,8 +36,6 @@ config.production.toml
.beads-credential-key
.beads/proxieddb/
*.gate.lock*
.impeccable/
.serena/
.beads/issues.jsonl
.beads/interactions.jsonl
.mcp.json
@@ -47,10 +45,10 @@ config.production.toml
__pycache__/
*.pyc
# Local site build output.
/site/
# Locally-trusted development certificates (mkcert and friends). The private
# key is generated per machine and must never be committed.
*.pem
*.key
# Local symlink to the archipelago marketplace repo
/archipelago
+1
View File
@@ -0,0 +1 @@
v2.14.0
+29 -6
View File
@@ -29,6 +29,7 @@ linters:
- nestif
# Architecture
- depguard
- importas
- interfacebloat
@@ -61,6 +62,34 @@ linters:
- usetesting
settings:
# Each service links only its own composition: services reach each other
# through their gRPC contracts, never another service's packages.
depguard:
rules:
gateway-service:
files: ["**/internal/app/archiegateway/**"]
deny:
- {pkg: "github.com/samcharles93/archie-core/internal/daemon", desc: "the daemon is another service"}
- {pkg: "github.com/samcharles93/archie-core/internal/webui", desc: "the web UI is another service"}
- {pkg: "github.com/samcharles93/archie-core/internal/app/archied", desc: "the daemon is another service"}
- {pkg: "github.com/samcharles93/archie-core/internal/app/statestore", desc: "reach the State Store through its contract"}
state-store-service:
files: ["**/internal/app/statestore/**"]
deny:
- {pkg: "github.com/samcharles93/archie-core/internal/daemon", desc: "the daemon is another service"}
- {pkg: "github.com/samcharles93/archie-core/internal/webui", desc: "the web UI is another service"}
- {pkg: "github.com/samcharles93/archie-core/internal/gateway", desc: "the Gateway is another service"}
- {pkg: "github.com/samcharles93/archie-core/internal/app/archied", desc: "the daemon is another service"}
- {pkg: "github.com/samcharles93/archie-core/internal/app/archiegateway", desc: "the Gateway is another service"}
- {pkg: "github.com/nats-io", desc: "the State Store serves gRPC only"}
shared:
files: ["**/internal/app/servicekit/**", "**/internal/app/chattask/**"]
deny:
- {pkg: "github.com/samcharles93/archie-core/internal/daemon", desc: "shared code must not pull in a service"}
- {pkg: "github.com/samcharles93/archie-core/internal/webui", desc: "shared code must not pull in a service"}
- {pkg: "github.com/samcharles93/archie-core/internal/app/archied", desc: "shared code must not pull in a service"}
- {pkg: "github.com/samcharles93/archie-core/internal/app/archiegateway", desc: "shared code must not pull in a service"}
- {pkg: "github.com/samcharles93/archie-core/internal/app/statestore", desc: "shared code must not pull in a service"}
cyclop:
max-complexity: 15
dupl:
@@ -142,12 +171,6 @@ formatters:
custom-order: true
exclusions:
generated: strict
# These Yaegi programs sit behind //go:build ignore, so a formatter cannot
# type-check them: rewriting their imports deletes the genuinely used
# internal/secret import and the interpreter can no longer load them.
# Excluded from every formatter so adding one cannot reintroduce that.
paths:
- ^examples/secret-engines/(age|sops|vault)\.go$
issues:
# 0 = report everything. The defaults (50 per linter, 3 per message)
+442
View File
@@ -5,6 +5,448 @@ release's per-component sections are labelled beneath its heading.
## [Unreleased]
## [1.54.3] - 2026-10-16
### archied
- Chat can help write a workflow: it reads your workflows and the step catalog, writes a definition, and checks it the same way saving does, fixing what the check reports. It does not save; paste the YAML it gives you into the editor's YAML view and save there.
## [1.54.2] - 2026-10-16
### archied
- Tool calls from Gemini models (Interactions API) receive their arguments intact. Any tool that takes arguments, such as `dashboard_navigate` in chat, failed with "invalid character '{' after top-level value".
### archie-agent
- Agent steps on Gemini models (Interactions API) pass tools their arguments intact instead of failing to decode them.
## [1.54.1] - 2026-10-16
### archied
- Update checks, `archied update install` and `install.sh` find releases at `github.com/samcharles93/archie-releases`, so a host can update again. A host on 1.54.0 or earlier still looks in the old place and has to be upgraded to 1.54.1 by hand once.
## [1.54.0] - 2026-10-16
**Upgrade note:** services now authenticate each other with TLS certificates from your own CA instead of shared tokens. Before upgrading a host whose services listen on anything but loopback (any host running agent containers), issue a certificate per service (`archied`, `archie-gateway`, `archie-messaging`, `archie-state-store`, `archie-ui`, each with its name as the DNS SAN and both server and client auth), add `[tls] ca_file` and `cert_dir` to `config.toml`, and remove every `target_token`, the `*_TOKEN` service variables and the `--token`/`--*-token` flags, including archie-ui's `-token` and `-token-file`. A unit that still passes a removed flag fails to start. See `config.example.toml`.
### archied
- Services authenticate each other with mutual TLS. Each process presents `<cert_dir>/<service>.pem`, peers must chain to `ca_file`, and a caller is identified by its certificate rather than by what it claims. Renewed certificates are picked up without a restart. Without `[tls]`, services listen on and dial loopback only. The harness setup terminal requires `[tls]`.
- Every gRPC service caps the streams a connection holds, times out stalled handshakes, releases a dead client's streams, and drains for at most 10 seconds on shutdown. Messaging exits when its listener fails instead of staying up without delivering.
- The dashboard has user accounts. First run opens browser setup for the organisation, workspace and first administrator; people then sign in with a password, a passkey or your identity provider, and account administration lives under Access. The shared dashboard token is gone; reach the dashboard remotely through an HTTPS reverse proxy.
- `archied update install` updates a host in one transaction: it verifies the release, stages every binary, pulls the agent image by digest and backs up the database, then restarts the services in order and rolls everything back if archied is not healthy for two minutes.
- Each workflow runs as the identity it declares, checked on every attempt along with the identity that started it. A workflow that declares none is refused, a called workflow runs as its caller's declared identity, and shipped workflows run as the instance root.
- Test-run a workflow draft before saving it, with forge and push writes suppressed and recorded per step. The History tab lists a workflow's revisions, diffs them as YAML and on the canvas, restores one into the editor, and shows which revision each run used.
- Start a task from the dashboard. The dashboard home shows activity and setup, and a running task has a read-only Sandbox tab that follows its container.
- The topbar's Jump to is a command palette, settings lists open as accordions that wait for a new item to be saved, and history restores land as a draft applied from the save bar.
- Labels, hints, alerts and empty states say what is wrong and what to do, without tutorial or marketing prose.
- Org isolation is tighter: harness secrets, identity writes, principals, playbook dispatch and model selections in chat stay in the caller's org, instance settings are written by the system org only, and creating a source or reloading a channel is authorized against the target.
- Binding dispatch claims its capture and enqueues the task atomically, so a capture cannot start two runs, and the run-time workflow check sees the binding event's signature and address.
- Service-unhealthy alerts count their grace from the last report and also cover a service that went silent, and a restart no longer clears an alert still inside its grace. An invalid stored access policy raises an alert until it validates.
- A failed cancel of a called workflow no longer leaves the caller running, retention spares captures still waiting to be dispatched, and EDA playbooks load and report at start instead of on first dispatch.
- Chat model selection works again for provider models.
### archie-agent
- Each run acts as its workflow's declared identity.
- A task snapshot carries only the model limits its aliases resolve to.
- A build step's "no changes" result comes from its writable stages and clears once a commit lands.
- Test runs suppress forge and push writes and record what they would have done.
- The default persona is a reporting-focused identity prompt, without the one-question limit in chat.
## [1.53.0] - 2026-10-11
### archied
- Every organisation's data is its own. Chats, tasks, events, transitions, steps, tool calls, run statistics, event sources, event types, mappings, bindings and agent memory are read and written in the org that owns them, and a request can no longer write into another org. Rows written before orgs existed move to their owner's org on upgrade.
- An instance admin decides what each org may reach: the models it can use, and whether it may register providers under its own credentials. Org Settings gains a Models tab and instance Models gains Org access. The system org is never restricted; another org uses nothing until it is granted.
- Models are addressed by alias. Aliases replace model roles, one resolver serves every purpose (agent steps, implement, PR review, MCP sampling, chat, embedding, transcription), and an unknown alias fails instead of falling back to a default. The step editor and the chat picker offer aliases, and a workflow naming one that does not exist is refused when saved.
- Chat sessions belong to one org; a chat resolves its models in the caller's org and is billed to it, and a task run from chat posts its outcome back to that chat.
- Add a member by provider subject, or by email as a placeholder that the first sign-in the provider vouches for claims.
- The workflow canvas authors parallel branches as lanes, adds a switch step that runs the case matching a reference, and edits a call's interface. A step shows its role, its number and its run trace.
- The workflows list shows each workflow's running count and latest run result, the canvas reveals its data-edge handles on hover, and restoring a version asks for confirmation.
- Store packages can auto-update: a package given the policy is moved to the catalogue's newest digest by a State Store ticker. An update asking for more authority than was accepted waits as a pending update with the running version untouched; approving it accepts the new authority, and a rollback restores the previous version with the authority accepted against it.
- Model provider keys never enter an agent container: the runtime reaches its providers through the egress proxy, which holds the keys. A task's own credential can no longer replace the workflow definition its run is pinned to, and a package workflow's triggers, tools and forge calls are bounded by the authority accepted for the package.
- The dashboard warns when it is reachable from off-host over plain HTTP, and the wildcard listen address counts as off-host rather than loopback. Instance health, logs, config and identities, the setup checklist and the skill catalogue are system-org only, and API requests are refused until the access chain has loaded.
- `/approve` reaches Telegram; the router served it but nothing published it.
- A worktree a killed container left root-owned is taken back by the daemon, and a PR review's benchmark runner works again on configured models and public PRs.
- An unserved `/api` path returns 404 instead of the dashboard page, and an input group's select no longer loses clicks to its addon.
### archie-agent
- The runtime reaches model providers through the egress proxy, so provider keys stay out of the container.
- Agent steps resolve model aliases and their own org's models and credentials, failing on an unknown alias instead of falling back.
- A switch step runs the case matching its reference.
- A call waiting on another step is reconciled from durable steps, so it resumes after a daemon restart rather than stranding.
## [1.52.0] - 2026-10-09
### archied
- The harness page's setup terminal opens a real session: it starts an ephemeral container from a Kit profile, runs the CLI's own login and captures the OAuth tokens at the provider's token endpoint. Point the dashboard at the daemon with `[services.harness].target` and a `HARNESS_TOKEN` and it stops answering 503; the terminal is created at your browser's size. Takeover of a live task is not in this release.
- A credential's token endpoint is refused when the run is not granted that service, instead of proxy-ing the provider's real tokens into the container.
- Settings → Profiles, Credential bindings and Playbooks are editable from the dashboard, and curator definitions can be changed and applied without a restart.
- Settings say whether each one applies live or needs a restart, show what is consuming resources, and report whether an apply landed.
- Status shows each service's dependency checks, the agent workers and the broker.
- The Logs page reads recent logs from every service, not just the daemon.
- Captures and webhook sources are scoped to the org that owns them: the list, retention and delivery authorization all act in the right org, and a workflow definition resolves in its own org.
- Chat settings are attributed to the signed-in user, and Settings → Tokens explains when a personal token cannot be created.
- A channel enabled after Archie started works immediately; a channel that fails on its own recovers; a failed channel is no longer reported as enabled, and stored channel settings no longer save duplicate or unnormalized values.
- The task table sorts, the command palette no longer scrolls sideways or loses its highlight, unknown routes render a not-found page, and configuration reload failures are shown instead of passing silently.
- A scheduled job whose payload names a dangerous command is refused.
- A disabled model provider is never served from the ambient API key.
- `generate_video` is backed by ai-sdk's MiniMax video provider.
- A dashboard token is no longer written to the startup log.
### archie-agent
- `workflow.call`: a call is keyed on its declared step path, its key is freed once the callee reaches a terminal state, and a caller waiting on a callee releases its capacity instead of holding it.
- `command.run` honours step retry and `on_failure`.
- A value passed between steps keeps its declared type, and optional result booleans are enforced only when the workflow declares them.
- Capture tools have their results checked against the declared schema.
- A single-cycle run waits for its in-flight tasks before exiting, and identity tasks inherit live settings.
- Kit containers run Docker's init as PID 1, so orphaned processes are reaped instead of accumulating inside a long task.
## [1.51.1] - 2026-10-08
### archied
- Chat with OpenAI's gpt-6 models (gpt-6-luna and the rest) works with tools; a turn failed with "Function tools with reasoning_effort are not supported".
## [1.51.0] - 2026-10-08
### archied
- A secret engine enabled after Archie started (Bitwarden, for example) now supplies its keys straight away; providers that depended on it no longer stay disabled until a restart.
- The dashboard chat has a microphone button: record a voice message and it is transcribed like a Telegram voice note. It shows only when a `transcription` model role is set under Settings → Models.
- A file Archie sends in the dashboard chat is a download link for an hour, instead of a note that it can't be delivered.
- Typing `/model` or `/personality` on its own in the dashboard chat offers the choices as buttons.
## [1.50.1] - 2026-10-08
### archied
- When an update is rolled back, the log names the health check that failed instead of only "unhealthy".
## [1.50.0] - 2026-10-08
### archied
- Tools that need your approval ask for it again, and Archie can ask you a question or offer choices mid-reply. Since the services were split these never reached Telegram or the dashboard: approval-gated tools failed and questions were never asked.
- The dashboard chat shows approvals as Approve / Always this session / Deny, choices as buttons, and questions with a reply field.
- `/update` in the dashboard chat lists what's available with Install and Not now.
- Settings → Status → Versions installs the update it shows; its Install button sent an empty request.
## [1.49.4] - 2026-10-07
### archied
- Settings → Status and Settings → Extensions are split into tabs instead of one long page; the Versions table's status column ends at the card's edge.
- Tools & MCP has one "Add MCP server" button; the transport is chosen in the form, and an unnamed new server is not an unsaved change.
- Settings → Repositories shows the add field when no repositories are configured, instead of a blank page.
- The unsaved-changes bar always rests at the bottom of the window.
## [1.49.3] - 2026-10-07
### archied
- Settings → Status → Versions shows the Gateway as "Update available" with an Install button when a newer release exists; it read "Unknown" with no way to install. The Runtime row stays "Unknown" until an agent task has run.
- The release channel buttons sit at the Updates card's right edge instead of mid-row.
## [1.49.2] - 2026-10-07
### archied
- Carries the 1.49.0 and 1.49.1 changes, whose builds were never published. The update check reads GitHub releases directly and still offers only releases with a verifiable linux-amd64 zip.
## [1.49.1] - 2026-10-07
### archied
- When the dashboard session expires, the page returns to the sign-in screen instead of showing errors on every page until a manual refresh.
## [1.49.0] - 2026-10-07
### archied
- Extensions that declare no egress hosts (vault, email, gitea) reach the network again; only packages that declare their hosts are confined to them. The Accept dialog shows "network: unrestricted" for the rest.
- The update check finds releases itself, and reuses a found release for ten minutes so repeated checks stay under GitHub's rate limit.
## [1.48.1] - 2026-10-07
### archied
- **Settings → Status → Updates** now chooses only the release channel (stable, prereleases, or a pinned version). Update checks and installs always run the `archie-update-*` scripts installed beside the binaries; the dashboard can no longer set the command that runs.
## [1.48.0] - 2026-10-07
### archied
- **Settings → Status → Updates** edits the update check and install commands. They default to the `archie-update-*` scripts installed beside the binaries, so a zip install shows **Install** on the Versions card with nothing configured. The `update_check_command` and `update_install_command` keys under `[chat.telegram]` are no longer read; remove them from `config.toml`.
- `archie-update-install` run from a shell now reads `~/.config/archie/env`, so the pre-update backup of the bundled database no longer fails with `no password supplied`. Run it with `--auto` to install the newest release.
## [1.47.3] - 2026-10-07
### archied
- **Settings → Extensions**: **Accept** in the authority review now accepts the extension, and **Remove** removes it. Both previously closed the dialog without doing anything.
## [1.47.2] - 2026-10-06
### archied
- **Events → Inspector** now lists your capture sources with their real URLs and a **New source** button, replacing the `/webhooks/capture/<source>` placeholder. Sources no longer sit on the Bindings tab.
## [1.47.1] - 2026-10-06
### archied
- The bundled PostgreSQL has no network and publishes no port: the services reach it through its Unix socket under `~/.local/share/archie/postgres`, so it no longer collides with another PostgreSQL on 5432. Leaving the database question blank in `archied setup` selects it.
- The installer does not start the services when the bundled PostgreSQL fails to start; it names the command to read its logs.
- On hosts that restrict unprivileged user namespaces (Ubuntu 23.10+), the installer prints an AppArmor profile allowing them for the Archie binaries only.
## [1.47.0] - 2026-10-06
### archied
- Install with one command: `curl -fsSL https://raw.githubusercontent.com/samcharles93/archie-core/main/install.sh | bash` downloads this release, verifies its checksum and runs `archied setup`. `--from-source` builds a checkout instead.
- `archied setup` asks for the PostgreSQL URL. Left blank, it uses the bundled Compose database with a generated password stored in `~/.config/archie/env` as `PGPASSWORD`, not in `config.toml`.
- The bundled PostgreSQL listens on 127.0.0.1 only. A database created before this release keeps its old `archie` password; enter its URL at setup or recreate the volume.
- The release zip carries `docker-compose.yml`.
- Extensions need unprivileged user namespaces, which Ubuntu 23.10 and later restrict. Allow them for the Archie binaries with an AppArmor profile; from the next release the installer prints it. Do not disable the restriction system-wide.
- fix(app): assign the temp-file close result on the error path
- fix(webhook): set a ReadHeaderTimeout on the forge webhook receivers
- fix(forge): refuse a review line number that does not fit an int
- fix(storepkg): mask the tar mode to the permission bits before narrowing
- fix(webui): navigate the Events chain once, not twice
- feat(tools): fail the gate when docs cite a path that no longer exists
- fix(webhookguard): verify uppercase-hex HMAC signatures
- fix(configuration): make bot_user required, defaulted, and named
- feat(workflow): add the command.run step type
- fix(controlplane): an absent MCP server field inherits the file value
- fix(build): restore the go fix fixpoint, and give the formatter one owner
- fix(archied): restore contextcheck directives and drop unused adapter
- feat(secretengine): serve secret engines as go-plugin extensions
- refactor(statestore): own package for the State Store service; access reset moves to archie-state-store
- refactor(archied): gateway owns model work; daemon drops chat runtime, tools, memory and curators
- refactor(archiegateway): own package for the Gateway service
- fix(services): services wait for peers instead of exiting; restarted broker keeps its endpoint
- refactor(archieplaybooks): fold archie-playbooks into archied playbooks lint|serve
- refactor(agentrun): agent stage contract moves to the domain layer
- refactor(agentexec): model loop moves to agentexec/modelloop
- fix(configuration): bindings encryption keys must use the env engine
- feat(storepkg): fetch packages from any registry, plain HTTP on loopback only
- feat(webui): install, accept and enable extensions from the dashboard
- feat(presence): every service re-stamps a presence record in the State Store
- refactor(plugin): delete Yaegi daemon plugins and plugin_dir
- refactor(module): the log action is built in; delete the module loader and reconciler
- refactor(skill): delete Yaegi skill scripts and the run_go_script tool
- refactor(examples): the firewall workflow moves to archipelago
- feat(presence): services card on the status page and archied status
- feat(archiemessaging): verify update reports against archied's presence and restore release announcements
- fix(configuration): an overlay stands in for a missing config file; dev overlay is complete
- feat(access): edit org, workspace and object policies from the dashboard; refuse owner lockout
- feat(access): instance network rules at the capture receiver; policies reload without a restart
- feat(staterpc): attribute State Store calls to the calling service; policy audit records it
- feat(controlplane): playbooks and agent profiles install from packages; the daemon reads eda-playbooks live
- feat(forgeext): forge surface served by extensions; forge.type names the installed package
- refactor(forge): github and gitea leave core; webhooks parse in the forge extension
- feat(staterpc): the State Store derives org and actor from the principal archie-ui forwards
- feat(channelext): chat channels served by extensions; messaging runs the enabled ones
- refactor(channels): webhook and email run only as extensions; their channel settings go
- feat(skills): skill packages project into a skills resource the gateway reads live
- fix(gatewayrpc): sender_id and rate_limited cross the chat wire
- fix(controlplane): change history names kinds and reads only the caller's org
- feat(contracts)!: requests no longer name their org; the State Store derives it from the caller
- feat(identity): personal API tokens, created and revoked from the dashboard, act as their owner
- fix(archieui): a sign-in provider outage is a health issue, not a startup failure
- feat(staterpc): one run credential per task, kept in the State Store, authorizes its store calls and its push
- fix(forgerpc): forge calls need the run credential and reach only the run's own repository
- feat(controlplane): identity credential grants edited from the dashboard and applied live
- feat(daemon): a workflow that names an identity runs as it; the dispatcher needs run on the workflow
- feat(staterpc): every run start is audited by the State Store, or the run credential is withdrawn
- refactor(forgerpc): identity RPC subjects are keyed by identity ID
- fix(nats): containers log in with their run credential and reach only their task's subjects
- feat(egress): the run credential is the proxy login; Kit secrets resolve per request from live grants
- fix(webui): bind the container runtime document's keys, drop the blank Advanced page
- fix(webui): drop the repository review switch the server no longer accepts
- feat(controlplane): serve the step vocabulary in the workflow-definitions schema; the editor checks step types against it
- fix(ui): drop the topbar nav's edge fade that clipped the first item
- refactor(workflow): delete the bootstrap smoke-test workflow and its intake kind
- feat(workflow): step ids, {{ }} references to earlier results, agent.run result schemas, workflow.finish and on_failure
- feat(workflow): repository step types; implement and tdd ship as YAML in general steps
- feat(workflow): when conditions, handoff, human approval and forge steps; feasibility and triage ship as YAML
- feat(workflow): retries, parallel branches, review steps; every shipped workflow is YAML and the per-workflow step types are gone
- feat(ui): workflow canvas renders each definition as a step graph with data edges, parallel branches and conditions
- feat(ui): the workflow canvas watches a run live: each step shows its state, duration and error, and the view follows the step in progress
- feat(controlplane): serve each step type's settings schema; the workflow editor checks settings before save
- feat(ui): build workflows on the canvas: step palette, schema-driven settings forms, references to earlier results, reorder and remove
- feat(ui): the canvas Start node lists what starts the workflow: issue routes, event bindings, playbooks and other workflows
- feat(ui): canvas authoring by right-click menu and + insertion points; steps edit in a slide-in panel and show what they do
- fix(ui): workflow page header is one tab row with save and a more menu; drop the ID field, step list, version footer and the meaningless origin pill
- feat(ui): drive workflows from the canvas: run a workflow, act on the watched run, edit workflow settings from the Start node; the canvas fills the viewport
- feat(ui): inspect workflow step runs from canvas
- feat(workflow): resume a parked run from a chosen step
- feat(ui): bind an event to a workflow from its Start node
- fix(ui): reveal signing secret in canvas source creation
- feat(ui): select review gate findings before approval
- fix(ui): load task debug reliably and copy JSON output
- fix(postgres): queue a review that arrives during a remediation
- fix(ui): keep JSON copy inline on hover
- fix(webui): stop returning database_url from /api/config
- refactor(config): drop unused dispatch state labels
- feat(gateway): serve the dashboard skills and curators over ChatService
- refactor(archieui): leave channel reload unserved by the gateway
- feat(releaseupdate): install from release artifacts with journaled rollback, topology check and channels
- feat(gateway): load SOUL into the chat prompt per turn
- refactor(config): drop the unwired artifact sender and [artifacts] config
- feat(messaging): serve MessagingService.Deliver and deliver chat schedules through it
- refactor(gateway)!: drop budget_key with the webhook chat channel
- refactor(configuration): delete the dead runtime config overlay
- fix(daemon): record terminal non-dispatch outcomes so a capture is evaluated once
- fix(daemon): refuse a disabled workflow on every start path
- fix(workflow): validate workflow.call inside parallel branches
- fix(workflow): validate handoff and approve targets at save
- feat(taskactions): rejecting a pr_open task closes its pull request
- feat(eda): link binding dispatches to the captures and tasks they started
- feat(eda): record every terminal binding outcome and flag failing bindings
- feat(workflow): record parallel branch steps as their own steps
- feat(workflow): record steps skipped by when as skipped
- feat(webui): page and filter the task list on the server
- fix(webui): admit dashboard work requests through the State Store and honour the workflow's repository mode
- fix(ui): restoring shipped workflows keeps custom ones
- refactor(org): rename the default org to org-sys
- fix(postgres): collect inline comments on a review queued behind a running remediation
- fix(daemon): webhook forge intake does not poll for issues
- refactor(archied): drop the unreachable multi-identity webhook skip; validation refuses it
- feat(access): the dashboard operator is a person owning org-sys
- fix(workflow): refuse undeclared inputs and result fields at save
- fix(ui): offer resume only where the server accepts it
- feat(daemon): the timeline names and links the binding and capture that started a task
- feat(eda): pause and resume a binding; resuming goes back through approval
- feat(org): org, workspace and membership API
- fix(webui): the org-sys owner is the instance owner
- fix(webui): member changes need the admin grant and owner changes an owner
- feat(daemon): withdrawing an issue declines its queued or running work
- feat(workflow): later steps read a waited workflow.call's outputs as its result
- feat(workflow): record each failed attempt of a retried step
- feat(daemon): record an approving review on the task's timeline
- feat(workflow): each remediation round names its number, cap and the review it answers
- fix(ui): show step retries as archie's record, not the agent's report
- feat(webui): run details show inputs, outputs and workflow.call links both ways
- feat(webui): page through task logs
- feat(eda): name and delete capture sources; an armed binding blocks the delete
- feat(ui): edit retry backoff and needs on the canvas
- fix(controlplane): report watch outages and align live/restart kind labels
- feat(taskactions): merge pull request action from the task
- fix(daemon): withdraw only issues the same dispatch rule found eligible and then lost
- feat(org): instance admins manage every org
- feat(ui): org area with members, agents, workspaces, access and tokens
- fix(ui): trim filler prose and expose appearance in settings nav
- fix(archiegateway,agentexec,agentworker): rely on ai-sdk reasoning token selection
- feat(ui): org switcher and new org for instance admins
- fix(extension): confine each extension's network to its accepted egress hosts
- fix(captureintake): unwrap form-encoded webhook payloads
- fix(captureintake): decode any form-encoded webhook body to JSON
- fix(modelloop): feed the cached model catalog to the runtime so reasoning models get the right token parameter
- fix(webui): list services with the State Store marked down when it is unreachable
- fix(release): push the release commit and its tag atomically
- fix(eda): dispatch each webhook delivery once, however often the sender retries it
- fix(eda): name a source's delivery header in the dashboard instead of a built-in sender list
- fix(modelloop): mark reasoning models from the carried model limits, in the gateway and the agent worker
- feat(telegram): /stop stops the chat agent, else the tasks it created, or one task; delete the dead approval actions
- feat(storepkg): install packages from a signed default catalogue, listed on the Extensions page
- feat(setup): one guided flow; ask for PostgreSQL and generate the bundled database's password
- fix(setup): keep the generated database password out of config.toml
- feat(install): install from a verified release with curl | bash; ship docker-compose.yml in the release
### archie-agent
- fix(forge): refuse a review line number that does not fit an int
- fix(webhookguard): verify uppercase-hex HMAC signatures
- feat(workflow): add the command.run step type
- feat(secretengine): serve secret engines as go-plugin extensions
- refactor(statestore): own package for the State Store service; access reset moves to archie-state-store
- fix(services): services wait for peers instead of exiting; restarted broker keeps its endpoint
- refactor(agentrun): agent stage contract moves to the domain layer
- refactor(agentexec): model loop moves to agentexec/modelloop
- fix(configuration): bindings encryption keys must use the env engine
- feat(presence): every service re-stamps a presence record in the State Store
- refactor(plugin): delete Yaegi daemon plugins and plugin_dir
- refactor(module): the log action is built in; delete the module loader and reconciler
- refactor(skill): delete Yaegi skill scripts and the run_go_script tool
- feat(access): edit org, workspace and object policies from the dashboard; refuse owner lockout
- feat(access): instance network rules at the capture receiver; policies reload without a restart
- feat(staterpc): attribute State Store calls to the calling service; policy audit records it
- feat(controlplane): playbooks and agent profiles install from packages; the daemon reads eda-playbooks live
- feat(forgeext): forge surface served by extensions; forge.type names the installed package
- refactor(forge): github and gitea leave core; webhooks parse in the forge extension
- feat(staterpc): the State Store derives org and actor from the principal archie-ui forwards
- feat(channelext): chat channels served by extensions; messaging runs the enabled ones
- refactor(channels): webhook and email run only as extensions; their channel settings go
- feat(skills): skill packages project into a skills resource the gateway reads live
- fix(controlplane): change history names kinds and reads only the caller's org
- feat(contracts)!: requests no longer name their org; the State Store derives it from the caller
- feat(identity): personal API tokens, created and revoked from the dashboard, act as their owner
- fix(archieui): a sign-in provider outage is a health issue, not a startup failure
- feat(staterpc): one run credential per task, kept in the State Store, authorizes its store calls and its push
- fix(forgerpc): forge calls need the run credential and reach only the run's own repository
- feat(daemon): a workflow that names an identity runs as it; the dispatcher needs run on the workflow
- feat(staterpc): every run start is audited by the State Store, or the run credential is withdrawn
- refactor(forgerpc): identity RPC subjects are keyed by identity ID
- fix(nats): containers log in with their run credential and reach only their task's subjects
- feat(egress): the run credential is the proxy login; Kit secrets resolve per request from live grants
- feat(controlplane): serve the step vocabulary in the workflow-definitions schema; the editor checks step types against it
- refactor(workflow): delete the bootstrap smoke-test workflow and its intake kind
- feat(workflow): step ids, {{ }} references to earlier results, agent.run result schemas, workflow.finish and on_failure
- feat(workflow): repository step types; implement and tdd ship as YAML in general steps
- feat(workflow): when conditions, handoff, human approval and forge steps; feasibility and triage ship as YAML
- feat(workflow): retries, parallel branches, review steps; every shipped workflow is YAML and the per-workflow step types are gone
- feat(controlplane): serve each step type's settings schema; the workflow editor checks settings before save
- feat(ui): the canvas Start node lists what starts the workflow: issue routes, event bindings, playbooks and other workflows
- feat(ui): inspect workflow step runs from canvas
- feat(workflow): resume a parked run from a chosen step
- fix(postgres): queue a review that arrives during a remediation
- refactor(config): drop unused dispatch state labels
- refactor(config): drop the unwired artifact sender and [artifacts] config
- feat(messaging): serve MessagingService.Deliver and deliver chat schedules through it
- refactor(gateway)!: drop budget_key with the webhook chat channel
- fix(daemon): record terminal non-dispatch outcomes so a capture is evaluated once
- fix(workflow): validate workflow.call inside parallel branches
- fix(workflow): validate handoff and approve targets at save
- feat(taskactions): rejecting a pr_open task closes its pull request
- feat(eda): link binding dispatches to the captures and tasks they started
- feat(workflow): record parallel branch steps as their own steps
- feat(workflow): record steps skipped by when as skipped
- feat(webui): page and filter the task list on the server
- refactor(org): rename the default org to org-sys
- fix(postgres): collect inline comments on a review queued behind a running remediation
- feat(access): the dashboard operator is a person owning org-sys
- fix(workflow): refuse undeclared inputs and result fields at save
- feat(daemon): the timeline names and links the binding and capture that started a task
- feat(eda): pause and resume a binding; resuming goes back through approval
- feat(org): org, workspace and membership API
- feat(daemon): withdrawing an issue declines its queued or running work
- feat(workflow): later steps read a waited workflow.call's outputs as its result
- feat(workflow): record each failed attempt of a retried step
- feat(daemon): record an approving review on the task's timeline
- feat(workflow): each remediation round names its number, cap and the review it answers
- feat(webui): run details show inputs, outputs and workflow.call links both ways
- feat(webui): page through task logs
- feat(eda): name and delete capture sources; an armed binding blocks the delete
- feat(taskactions): merge pull request action from the task
- feat(org): instance admins manage every org
- fix(archiegateway,agentexec,agentworker): rely on ai-sdk reasoning token selection
- fix(extension): confine each extension's network to its accepted egress hosts
- fix(modelloop): feed the cached model catalog to the runtime so reasoning models get the right token parameter
- fix(eda): dispatch each webhook delivery once, however often the sender retries it
- fix(eda): name a source's delivery header in the dashboard instead of a built-in sender list
- fix(modelloop): mark reasoning models from the carried model limits, in the gateway and the agent worker
- feat(telegram): /stop stops the chat agent, else the tasks it created, or one task; delete the dead approval actions
- feat(storepkg): install packages from a signed default catalogue, listed on the Extensions page
## [1.46.0] - 2026-10-02
### archied
+141 -391
View File
@@ -1,417 +1,167 @@
# AGENTS.md
Guidance for any coding agent working in this repository.
Keep every rule here harness-agnostic: name the required behaviour, not the tool
that provides it (e.g. "spawn a fresh reviewer that did not write the code", not
a specific sub-command).
## Code Quality & Refactoring Standards
- **Zero Patch Stacking:** Never apply more than two sequential fixes to the
same logic block. If a solution fails twice, scrap the block and rewrite it
cleanly.
- **Root-Cause Fixes:** Fix invalid state at the producer, not via defensive
checks at the consumer.
- **Architectural Simplicity:** Prefer a complete 20-line rewrite over a 5-line
band-aid that adds conditional complexity or obscures intent.
- **Revert on Flail:** If an implementation becomes convoluted to satisfy edge
cases, discard the approach and select a simpler design.
Rules for any agent working in this repository. Short on purpose: every rule
here changes a decision. If a rule stops changing decisions, delete it.
## What this is
**archied** is a resident daemon that polls a forge (GitHub, Gitea) for issues
assigned/labelled to it, works each one in an isolated git worktree through a
routed workflow (bootstrap / implement / TDD / feasibility), and opens pull
requests for human review.
**archie-core** is event-driven agentic automation. An event (an issue, PR,
webhook, schedule, chat message) is matched to a workflow, the workflow runs an
agent or tool in an isolated container, and the result lands somewhere for
review or action. A repository is an optional input to a workflow, not the point
of the product.
Architecture of record lives in `docs/architecture/` -- `organisation.md` for
the package map, `agent-system.md` for the workflow-execution lifecycle and its
invariants, `plugins-and-extensions.md` for engine families. Read it before
making non-trivial changes. Key invariants: env-enforced gates, model never runs
git, and agent execution functions as a strict data boundary. Before adding a new
plugin engine, satisfy
`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`.
<temporary - this statement must be removed on 2026-10-20"> The product is
unfinished. Many features are half-built, and the codebase carries far more
code, binaries, docs and tooling than it delivers. The job right now is to
finish features and shrink the codebase, not to extend it. </temporary>
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. This is not optional colour reading -- archie-core is built
as an extensible, customisable surface, not a fixed product, so a change that
looks complete inside one package routinely is not: a new setting that never
reaches the control-plane schema descriptor and dashboard parses but never
renders, is never editable, and never live-applies, exactly like a config
field with no consumer. The dev-docs page for the area is where that
cross-layer reach is written down; read it before starting, not after
something downstream turns out silently unwired. This applies whether the
work is yours directly or handed to a subagent or crew worker -- carry the
relevant docs/development page into their prompt, the same way a bead ID is
carried; "figure out what else needs updating" left implicit is exactly the
gap this note exists to close.
## Authority
## Scope Discipline
When sources disagree, the higher one wins:
`docs/architecture/` is authoritative for settled design.
`docs/architecture/migration-decisions.md` is the open decision register for the
domain migration.
1. The maintainer's instruction in this session.
2. This file.
3. The code as it is in the tree.
4. Beads issues (`bd show <id>`): the plan for a piece of work.
5. Everything else (memories, comments, old docs) is a hint. Verify it against
the code before acting on it.
- **Settled design exists** → Implement it immediately with a diff. Do not
produce design prose. If a small detail is missing, ask the maintainer
directly.
- **No settled design exists (or open in `migration-decisions.md`)** → Write a
decisive, 1-page design doc before coding. Land new capabilities in
`docs/prds/` and migration questions in
`docs/architecture/migration-decisions.md`. Promote to `docs/architecture/`
only after implementation lands.
- **Strictly Prohibited:** Ownership ledgers, field-level inventories,
current-state traces, parity matrices for their own sake, and
planning/refactor tracking issues.
- **Solo Project Context:** Prefer the smallest workable change over extensive
defensive scaffolding.
- **Verify handed-over input before acting on it.** An export, transcript, or
artifact that is empty, missing, or truncated is a blocking fact: report it
before starting work that assumes its contents. Never reconstruct the intent
from the working tree instead.
- **PRD writing:** Read and follow `docs/prds/RULES.md` before creating or
editing a PRD.
## Working with the maintainer
## Deployment Model
- **A clear direction is the go-ahead.** Do it in the same turn. Do not restate
the plan, offer options, or ask "shall I proceed?". Stop only for destructive
or outward-facing actions (deleting data, pushing, touching a live host).
- **Post outside the repo only when told.** Chat, tickets and any external
service get a message only on the maintainer's instruction.
- **Report, don't narrate.** Final replies say what changed, what was verified,
and anything blocked, in a few lines. No preamble, no recap of the request, no
closing offers of more help. Leave out what the maintainer can see or infer:
a clean tree, unpushed commits, a passing gate (commits imply it), and steps
skipped that the task never asked for. Name a skipped step only when the
task required it.
- **Systemd is optional:** `deployments/` holds supported profiles
(`single-forge-github.toml`, `multi-forge-github-gitea.toml`,
`local-ollama-standalone.toml`, `docker-nats-stack.toml`,
`systemd-user-service.md`). Never assume a systemd unit exists.
- **Chat filesystem confinement:** Builtin tools default to workspace jail via
`SetPathConfinement(!unrestricted)`. Unrestricted access requires
`[chat] unrestricted_filesystem = true`.
- **NATS endpoint immutability:** The daemon passes agent containers its startup
connection URL (`d.ConnectedNATS.URL`). Containers and daemon must resolve
this address. Embedded mode binds to the Docker bridge gateway. A SIGHUP
reload of `nats.url` logs an error requiring restart to prevent split-brain
delivery.
- **Container pull policy:** `containers.pull_policy` must be `"missing"`
(default) or `"always"`. Private registries need `containers.registry_auth`
(a `SecretRef` resolving to a `registry.AuthConfig` JSON document); without it
the pull is anonymous and a private registry answers 401. Refresh explicitly
via `docker compose pull agent`.
- **Docker Compose:** `docker-compose.yml` carries optional external NATS and
the `agent` build stanza. The agent uses a `build` profile so `up -d nats`
never starts it as a persistent service.
- **Config path:** Runtime configuration lives at
`${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`. Nothing in the working
tree is load-bearing at runtime.
## How to decide
## Release Process
- **Broken beats new.** A bug that blocks work gets fixed now, with the smallest
change that unblocks it. No design docs and no new mechanism.
- **Cheapest option first.** Before building, name the smallest change that
solves the problem, including changing configuration or deleting something. If
your plan adds a new mechanism (RPC, process, binary, abstraction, config
field, tool) or grows past about 100 lines, stop and assess whether you're
taking the path of least resistance.
- **Delete before adding.** Unused code, dead paths, fallbacks nobody takes and
features nobody runs get removed, not maintained. Solo project, single user:
breaking changes need no compatibility shims.
- **Finish before starting.** Prefer completing a half-built feature end to end
over starting a new one.
- **Services own contracts.** A service is a gRPC contract in
`proto/<service>/v1` and one binary that serves it. Services reach each other
only through those contracts, never through another service's tables or
packages. A new command is a subcommand of an existing binary. A new binary
exists only for a new service or a real process boundary.
- **No compensating tools.** Do not write a linter, checker or generator to
enforce something a simpler design would make unnecessary. Fix the design.
- **A setting must work end to end.** A config field that parses but has no
consumer is a bug. Settings are edited through the control plane (API and
dashboard), never by requiring a server login.
- **Ask only for real decisions.** Product direction and trade-offs the
maintainer owns are questions. Everything with a conventional answer is not:
decide, do it, say what you chose.
See `RELEASING.md`. Most sessions touch only `archied`, making releases
gateway-only (`RUNTIME=skip`) by default. Skip untouched components
automatically and note it in the handoff.
## Code
## Build & Test
- Idiomatic Go. Small functions, explicit errors, no package-level mutable
state, no god objects. Each feature wires itself; a composition root only
calls those constructors in order.
- Dependencies point inward: `cmd → app → {domain, infrastructure}`,
`infrastructure` implements `domain` interfaces, `domain` imports neither.
`cmd/` parses flags and calls `app`, nothing else.
- Fix invalid state where it is produced, not with checks where it is consumed.
- If a fix fails twice, throw the block away and rewrite it simply.
- Comments say why, briefly. No migration history, phase names or issue
narration in code.
- Generated files (`ui/dist/`, protobuf, sqlc) are regenerated and committed
with the change that caused them, never hand-edited.
Commands are defined in `Taskfile.yml` (requires Go 1.27.0,
[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.
## Tests
The default for a change is no new test. Write one only when:
- something actually broke: write the test that reproduces it, see it fail on
the assertion, then fix; or
- the change alters one of these seams: State Store SQL semantics (transition
guards, idempotent dispatch, cancellation), security boundaries (HMAC, grants,
path confinement, egress, secrets), the workflow step contract, or the
import-boundary rules.
A test that exists must catch a real regression, survive refactoring, run fast,
and be cheap to keep. Never test wiring, constants, defaults, struct shapes,
fakes, or call order. No test opens a real database or needs Docker; test
SQL semantics at the interceptor or domain level with fakes. One table-driven test per behaviour; extend the table
instead of adding a second test. Prefer making an invalid state unrepresentable
to testing that it is rejected. Test helpers live in `_test.go` files only.
## Invariants
These protect users. Do not weaken them without the maintainer's say-so.
- Failure stays local. Any service may crash, restart or be absent without
losing accepted work or taking another service down. Callers retry, degrade
and report the dependency as unhealthy; they never exit because a peer is
missing, and work is acknowledged only once it is durable.
- The model never runs git. Commits and pushes go through the daemon.
- The daemon's own credentials never enter an agent container. Containers get
task-scoped grants that are revoked when the task ends.
- Webhook HMAC is verified before the payload is parsed.
- Task briefs go in `<worktree>/.git/task.json`, never the worktree root.
- NATS: task and RPC replies use `msg.Respond`; flush after registering a
responder; `ARCHIE_TASKS` is a work queue, so never bind overlapping
consumers.
- `ai-sdk` `FullStream` must be drained completely.
## Build and gate
```bash
task build # build archied and archie-agent binaries into bin/
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
task vet # go vet ./...
task lint # golangci-lint run ./...
task check # fmt + proto:lint + proto:check + docs:check + vet + lint + build + test + test:tools + test:ui (The Definitive Gate)
task dev # archied live-reload + Vite HMR together on :5173
task build # binaries into bin/
task test # go test -short ./...
task ui # dashboard into ui/dist
task check # the gate
```
Single package/test runs:
Requires Go 1.27, Task, golangci-lint, Node/npm and Docker. Adopt `task fmt` and
`go fix` output as-is.
- `task check` gates the commit: `task check && git commit ...`. Never claim a
gate result you did not just produce on that exact tree; if the gate could not
run, say what you did verify.
- Commit finished work without asking. Stage only your own paths and commit in
the same command. Conventional Commits scoped by package, short messages. Push
only when told.
- Never commit binaries, build output, scratch files or `.references/`. Scratch
goes in `/tmp`.
- Runtime config lives at `${XDG_CONFIG_HOME:-~/.config}/archie/config.toml`.
Nothing in the working tree is read at runtime. Systemd is optional.
- Releases: `RELEASING.md`.
## Issues (beads)
Work is tracked in `bd`, never in Markdown TODO files.
```bash
go test ./internal/domain/workflow/... -run TestName -v -count=1
bd ready | bd show <id> | bd update <id> --claim | bd close <id>
```
## Repository Hygiene
- An issue is the plan: what is wrong or wanted, and how you know it is done.
Keep it to that.
- Bead state syncs through Dolt (`bd dolt push/pull`, only when told), not git.
Never commit `.beads/` exports.
- No host names, IPs, paths, PIDs or credentials in any bead: they are
published.
- File follow-up work you find as a bead. Do not fix it in passing.
- **Generated assets are LAW:** Never modify, revert, or ignore generated files
in `ui/dist/` or schema outputs. Incorporate them into relevant commits.
- **Ignored paths:** Never commit build artifacts, binaries (`/bin/`,
`/archied`), DB files, working screenshots, `.references/`, or
`node_modules/`.
- **Scratch files:** Place scratch files strictly in `/tmp` or the harness
scratch space. Never put scratch files in the working tree
(`worktree.CommitAll` will stage them).
- **Conventional Commits:** Scope by package: `feat(webui): ...`,
`fix(build): ...`, `chore(release): ...`.
- **Commit policy:** Commit finished, gate-clean changes (`task check`
passing) without asking. Push only when instructed.
## Changing this file
## Organisation (Strict Domain-Driven Architecture)
`docs/architecture/organisation.md` is authoritative. Do not follow flat
structures found in legacy packages.
### Layers and Ownership
- `internal/domain/<area>/`: Domain logic, entities, state machines, commands,
events, and required contracts (interfaces). Never imports infrastructure or
app.
- `internal/infrastructure/<service>/`: Implementations of domain contracts
(persistence, forge clients, external transports, config loading).
- `internal/app/<application>/`: Dependency injection, wiring domain to
infrastructure, lifecycle management, and shutdown ordering.
- `cmd/<binary>/`: CLI flag parsing, OS signal traps, and entry point routing
only. No domain wiring.
### Invariants
- **Dependency Flow:** `cmd → app → {domain, infrastructure}`, with
`infrastructure → domain` implementing contracts. Downward/inward dependencies
only.
- **Cross-Cutting Packages:** `logging`, `events`, `eventbus`, `policy`,
`taskstate` sit directly under `internal/`. They may be imported by any layer,
but **must import zero internal packages**. No `shared/`, `utils/`, or
`common/` catch-alls.
- **File Layout:** One file per API concern (`api_tasks.go`, `api_logs.go`). A
package owns its on-disk format end-to-end (e.g. `internal/logging` defines
and reads its format; transport layers do not parse).
- **Frontend:** Features live in `ui/src/<feature>/` with colocated `.js` and
`.css`. Extract to `ui/src/base/` only on the second distinct consumer.
## 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
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
configuration when there is none - which is what this repo now does for
per-identity `forge.intake`. Two documents carry the detail:
`.agents/skills/archie-config-and-flags` holds the wiring matrix, the
decoded-but-unwired ledger and the three shapes an unwired field can take;
`docs/architecture/configuration.md` is the authority on the config model and
its reloadability criterion.
- **`internal/channels/telegram/`:**
- The long-polling worker must call `dropPendingUpdates(ctx, b)` before
`b.Start(ctx)` and on `/restart`.
- Always publish command menus to `default`, `all_private_chats`, and
`all_group_chats` simultaneously via `commands.go` to avoid scope shadowing
from legacy registrations.
- **`ai-sdk` Streaming:** `FullStream` writes synchronously and MUST be drained
completely to prevent producer deadlocks. Do not rely on `TextStream` (drops
deltas).
- **NATS Invariants:**
- `ARCHIE_TASKS` uses `jetstream.WorkQueuePolicy`. Do not bind overlapping
consumer filters; use `Fetch` on existing durables instead of new `Subscribe`
calls.
- RPC and task responses must use core NATS `msg.Respond` to write to ephemeral
`_INBOX.*` subjects, not `eventbus.Publisher`.
- Always flush connections (`nc.Flush()`) immediately after registering
responders to avoid race conditions on initial requests.
- **`internal/gateway/` Chat Prompt:** System prompt `<tools>` blocks are
rendered strictly from the active `core.ToolSet`. Never decouple prompt tool
definitions from passed runtime tools.
- **`internal/container/pool.go` (`WriteTaskJSON`):** Write task briefs to
`<worktree>/.git/task.json`. Never place them in the worktree root (`go-git`
`Add{All:true}` ignores `.gitignore` and leaks root files into branch
commits).
- **MCP Providers:** Daemon registers providers as optional via
`providerRegistry.RegisterOptional`. Missing or failed providers log warnings
and degrade health without terminating the process.
- **`internal/infrastructure/staterpc/` (State Store gRPC contract):**
Authority is `docs/prds/state-store-contract.md` (rev. 2e) -- read it before
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, 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 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 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
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`
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.
- `archie-agent` has exactly one `workflow.Store` path: gRPC via
`staterpc.Client` (`agenttransport/nats.Transport.Store`), using the
`STATE_STORE_URL`/`STATE_STORE_TOKEN` env the daemon injects. The legacy
NATS `storerpc` transport is deleted (`internal/storerpc` no longer
exists); do not reintroduce a dual-path selection.
- `store.BindingDispatcher.RecordDispatch` takes no `*sql.Tx` (dropped in
`.4.2` -- it cannot cross a gRPC boundary; production always passed `nil`).
Do not reintroduce a transaction parameter on a producer-owned store
interface that a remote adapter must also implement.
- **`internal/forge/webhook/` (forge webhook receiver):**
- Verify HMAC (`webhookguard.VerifyHMAC` against `X-Hub-Signature-256`) before
parsing the payload, never after -- an unverified body must not reach
`github.ParseWebHook`.
- Do not give the webhook-built `workintake.TaskEnvelope` a delivery-source-
specific idempotency key. `IdempotencyKey()` is keyed on `owner/repo/number`
only so a webhook-delivered issue and a later poll of the same issue dedup
against each other via `PublishUnique`; adding an event ID or timestamp to
the key defeats that and reintroduces poll/webhook double-dispatch.
- Webhook intake refuses to start when `[[identities]]` is configured (one
receiver, one dispatch config). Do not silently enable it for multi-identity
deployments without first building per-identity routing -- see
`docs/architecture/messaging-and-work-intake.md`'s "Intake provenance"
section.
- **`internal/domain/embedding/` + `internal/infrastructure/embedding/`:**
Embedding client contract + implementation. Config-driven exactly like chat
model roles: `models.embedding = "provider/model"` plus a `[providers.*]`
entry. `infrastructure/embedding.New` degrades to `(nil, false)` -- never an
error -- for a missing role, unknown provider, unsupported class, or
unresolved credential; wired as an optional capability in
`bootstrap.go`'s `setupEmbeddings`. Only provider classes matching
`config.Provider`'s shape are supported (openai, gemini, ollama, cohere,
mistral) -- azure needs a `Deployment` field this config type doesn't have.
- **`internal/domain/sampling/`:** The curator `Sampler` interface (see
`docs/prds/curator-sampler-wave1.md`) plus four pure, deterministic
strategies (recency, staleness, random, all). No curator consumes a
`Sampler` yet -- `curator.Registrar` is untouched by this package.
## Development Protocol
1. **Red (Failing Test):** For behaviour with real logic, branching, or a
contract, write failing table-driven tests first against target behaviour.
Verify the failure originates from test assertions, not compilation errors.
Do not write tests that restate an assignment or a constant: a test that
cannot fail for an interesting reason is noise in the gate.
- **A test is a maintenance liability, not free insurance.** Every test
added is code the project now carries forever: it must compile, it must
keep passing as the code around it changes, and someone reads it during
every future change to that area. Write one because a real regression
would slip through without it, not because the function was touched.
- **Never pin a literal end-user config value, database row, or settings
document as the thing under test.** Test the validation rule, the
migration's shape, or the round-trip contract -- not one operator's
specific `config.toml` value, a hand-picked DB fixture that mirrors real
data, or a setting's current default. Those change for reasons that have
nothing to do with a regression, and a test pinned to one breaks on
every such change, which is cost with no signal.
- **Test-only helpers, fakes and fixtures live in `_test.go` files (or a
package no production `.go` file imports), never in a file the binary
ships.** `go build` does not compile `_test.go` files into the binary,
but an exported "test helper" living in a regular source file compiles
into every binary that imports the package, whether or not a test ever
runs. If a helper must be shared across packages, put it behind a
build-tagged or `_test.go`-suffixed file in an `xtest`-style package,
not behind a normal export.
- **Coverage is not the goal.** A codebase that grows mostly because tests
multiplied faster than the feature they cover is a symptom, not
progress -- prefer fewer, sharper tests over one per line changed.
2. **Green (Implementation):** Implement minimal code to satisfy the failing
tests.
3. **Quality Gate:** Run `task check`.
- **The gate gates the commit.** Let the gate's exit status decide whether
the commit runs, as one conditional chain (`check && commit && push`).
Writing them as separate statements on one command line makes the gate
decorative: nothing reads its status but the operator, and a failure is
discovered after it has already been pushed.
- **Never assert a gate result you have not just produced on that exact
tree.** A commit message outlives the tree it describes, and "verified"
is read by people who were not there. If the tree moved, describe the
change and let the run speak.
4. **Formatting is LAW:** Adopt all formatting and simplification changes from
`task fmt` (`go fix` + the configured golangci-lint formatters) verbatim.
Never revert or fight canonical linter/formatter diffs.
5. **No standing adversarial-review pass (for contributors):** Do not spawn a
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 its own PR review pipeline
(`docs/prds/pr-review-agent.md`) before it opens a PR of its own — see that
PRD's Triggers section ("archie's own PRs"). It supersedes the older
single-reviewer stage `docs/architecture/adversarial-review.md` described
(`repo.review_enabled` no longer exists). The two paths are distinct: you
run a manual pass when asked; archied runs its own before it opens a PR.
6. **Linter Guard:**
- When using `errorlint` fixes, ensure boolean predicates (e.g.
`exitErr.ExitCode() == 1`) are retained alongside `errors.As`.
- When extracting loops/conditionals, verify slice mutations and pointer
semantics do not duplicate elements.
## Issue Tracking (Beads)
All task management is tracked via **bd (beads)**. Do not write local Markdown
TODO lists or use non-Beads trackers.
### Commands
```bash
bd ready # List unclaimed work
bd show <id> # View issue details
bd update <id> --claim # Claim an issue
bd close <id> # Mark issue complete
bd remember # Persist cross-session architectural facts
```
- Run `bd prime` to inspect full engine context.
- Use `bd remember` for knowledge retention. Do not write to root `MEMORY.md`
files.
- Issues live in a local Dolt DB, synced to its own `git+` remote via
`bd dolt push`/`bd dolt pull`. `.beads/issues.jsonl` and
`.beads/interactions.jsonl` are local-only export/audit files
(`.gitignore`d, `export.auto: false`) -- never `git add` them and never
create a commit whose only content is beads bookkeeping. Bead state moves
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
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
point at. This is the same class of rule as never committing a credential:
the tracker is not a private store.
## Session Completion Protocol
1. **Log remaining work:** File new items via `bd` for identified debt or
follow-up tasks.
2. **Run gate:** Verify `task check` passes completely clean.
3. **Update tracker:** Close finished issues via `bd close <id>`. This alone
is not commit-worthy -- do not stage or commit `.beads/` for it.
4. **Commit:** Only for actual code/doc changes, scoped to the files that
changed.
```bash
git add <scoped-files>
git commit -m "feat(scope): description"
```
5. **Sync & Push Policy:** Do not push to git remotes or run `bd dolt push`
unless explicitly instructed.
6. **Handoff:** Report changed files, gate verification results, and active
issue states.
## Maintaining this file
Keep this file for knowledge useful to almost every future agent session in this project.
Do not repeat what the codebase already shows; point to the authoritative file or command instead.
Prefer rewriting or pruning existing entries over appending new ones.
When updating this file, preserve this bar for all agents and keep entries concise.
A rule is added only after a real failure it would have prevented, and it must
say which decision it changes. Remove rules that no longer change decisions.
Keep it short enough to read in full every session.
+4 -16
View File
@@ -3,10 +3,8 @@
# Language packages are installed at runtime via uv/npm/go.
#
# Build: docker build -t archie-agent:latest .
# This image is launched only by archied with a daemon-written task brief,
# task worktree mount, and authenticated NATS environment.
# ── builder ───────────────────────────────────────────────────────────
# ── builder ──
FROM golang:1.27-trixie AS builder
ARG RUNTIME_VERSION=dev
WORKDIR /src
@@ -17,17 +15,15 @@ RUN CGO_ENABLED=0 go build \
-ldflags "-X github.com/samcharles93/archie-core/internal/app/agentworker.version=${RUNTIME_VERSION} -X github.com/samcharles93/archie-core/internal/installtype.buildType=container" \
-o /usr/local/bin/archie-agent ./cmd/archie-agent/
# Same Debian release as the runtime, so glibc matches.
FROM node:24-trixie-slim AS node
# ── runtime ───────────────────────────────────────────────────────────
# ── runtime ──
FROM debian:trixie-slim
ARG RUNTIME_VERSION=dev
LABEL org.opencontainers.image.version="${RUNTIME_VERSION}"
ENV DEBIAN_FRONTEND=noninteractive
# build-essential is for agents building native npm/Python extensions.
RUN apt-get update && apt-get install -y --no-install-recommends \
ca-certificates \
curl \
@@ -41,7 +37,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
openssh-client \
&& rm -rf /var/lib/apt/lists/*
# ── Node.js 24 ────────────────────────────────────────────────────────
# ── Node.js 24 ──
COPY --from=node /usr/local/bin/node /usr/local/bin/node
COPY --from=node /usr/local/include/node /usr/local/include/node
COPY --from=node /usr/local/lib/node_modules /usr/local/lib/node_modules
@@ -50,7 +46,7 @@ RUN ln -s ../lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm && \
npm install -g pnpm typescript tsx esbuild stylelint htmlhint && \
npm cache clean --force
# ── Go ────────────────────────────────────────────────────────────────
# ── Go ──
# Reuse the builder's toolchain so the runtime Go can't drift from the one
# archie-agent was compiled with.
COPY --from=builder /usr/local/go /usr/local/go
@@ -58,12 +54,6 @@ ENV GOPATH="/go"
# /go/bin must be on PATH or anything `go install` puts there is unreachable.
ENV PATH="/usr/local/go/bin:/go/bin:${PATH}"
# Pinned release binaries. Building these with `go install` pulled ~2GB of
# module and build cache into the image. delve is omitted because it ships no
# prebuilt binary; `go install ...@latest` at runtime if an agent needs it.
#
# golangci-lint owns ordinary source formatting and lint checks. Standalone
# gofumpt is retained for generated protobuf contracts in tools/proto.sh.
ARG GOLANGCI_LINT_VERSION=2.13.2
ARG GOFUMPT_VERSION=0.11.0
ARG BUF_VERSION=1.72.0
@@ -78,8 +68,6 @@ RUN curl -fsSL "https://github.com/golangci/golangci-lint/releases/download/v${G
chmod +x /usr/local/bin/gofumpt /usr/local/bin/buf
# ── Python via uv ─────────────────────────────────────────────────────
# uv manages its own interpreters — no apt Python, no deadsnakes PPA. One
# version is the default; agents can `uv python install <other>` on demand.
ARG PYTHON_VERSION=3.14
RUN curl -fsSL https://astral.sh/uv/install.sh | sh
ENV PATH="/root/.local/bin:${PATH}"
+5 -18
View File
@@ -1,4 +1,4 @@
# archied — the archie daemon, built as a standalone container.
# archied — the archie daemon
# Run via docker compose alongside NATS.
FROM golang:1.27-trixie AS builder
@@ -9,21 +9,9 @@ COPY . .
ARG GATEWAY_VERSION=dev
ARG RUNTIME_VERSION=dev
RUN CGO_ENABLED=0 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=container" \
-ldflags "-X github.com/samcharles93/archie-core/internal/buildinfo.Version=${GATEWAY_VERSION} -X github.com/samcharles93/archie-core/internal/buildinfo.Runtime=${RUNTIME_VERSION} -X github.com/samcharles93/archie-core/internal/installtype.buildType=container" \
-o /usr/local/bin/archied ./cmd/archied/
# archied is static, but this can't be scratch: in inprocess mode the daemon
# runs agent tools itself, and the shell tool invokes bash; codesearch shells
# to git. Worktrees don't count — internal/worktree uses go-git. This image
# is not part of the current deployment (docker-compose.yml only builds
# Dockerfile, the agent image; archied runs on the host under systemd), but
# if it's ever used in inprocess mode, grep needs ripgrep on PATH -- it is
# no longer embedded in the binary.
#
# No Node: the builtin tools (read/write/edit/find/grep/shell/test) cover what
# desktop-commander did. Any npx-launched MCP stdio server will now fail to
# start, and a failed provider rolls back the tool-provider family and exits
# the daemon — so remove tools.mcp_servers entries needing npx before
# deploying this image.
FROM debian:trixie-slim
RUN apt-get update && apt-get install -y --no-install-recommends \
ca-certificates git && \
@@ -33,8 +21,7 @@ ARG GATEWAY_VERSION=dev
ARG RUNTIME_VERSION=dev
LABEL org.opencontainers.image.version="${GATEWAY_VERSION}"
LABEL cloud.catlow.archie.runtime-version="${RUNTIME_VERSION}"
# One release stream: CHANGELOG.md carries every release section, with each
# component's detail as a labelled section inside it. The per-component files
# this used to copy were deleted with the split release.
COPY CHANGELOG.md /usr/share/archie/CHANGELOG.md
ENTRYPOINT ["archied"]
-12
View File
@@ -1,17 +1,5 @@
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
This product includes software from the Cedar project
(https://github.com/cedar-policy/cedar), Copyright Amazon.com, Inc. or its
affiliates, licensed under the Apache License, Version 2.0, as implemented by
+59 -82
View File
@@ -14,12 +14,8 @@ 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.
Archie is under active development and not every capability below is
finished.
## From an event to an outcome
@@ -77,35 +73,16 @@ 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
The archipelago marketplace's `workflows/firewall` package is an example of a
workflow that uses typed inputs, a network investigator profile, and no
repository.
## Organisations, identities, and controlled execution
## 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.
Agents act as their own identities, with secrets and permissions granted to
that identity. Runs receive credentials scoped to their task; event data
supplies inputs and cannot grant access. Organisations, workspaces and
policy-based access control are in progress.
## Building and operating automations
@@ -114,69 +91,69 @@ 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.
Sources default to signed delivery; an unsigned source must be explicitly
approved. 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.
## Run it on a server
## Develop locally
You need x86_64 Linux with curl and unzip, Docker (agents and the bundled
PostgreSQL run in containers) and a model: local [Ollama](https://ollama.com)
or a hosted provider API key.
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.
1. **Install.**
```bash
task dev
```
```bash
curl -fsSL https://raw.githubusercontent.com/samcharles93/archie-core/main/install.sh | bash
```
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.
It downloads the latest release, verifies its checksum, installs the five
services into `~/.local/bin` and runs `archied setup`. Setup asks for the
PostgreSQL URL (leave it blank for a bundled database with a generated
password), a model provider and key, and a forge (choose **none** for
event-driven automation only). Answers go to `~/.config/archie/config.toml`
and secrets to `~/.config/archie/env`. The installer then starts the
bundled PostgreSQL with Docker Compose and installs and starts systemd user
units. Pass options with `| bash -s -- --help`; `--from-source` builds a
checkout instead. Re-run `archied setup` at any time to change the answers.
Useful checks:
Extensions run in an unprivileged user namespace. Ubuntu 23.10 and later
block these by default; on such a host the installer prints an AppArmor
profile that allows them for the Archie binaries only, to install with
`sudo`.
```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
```
2. **Check it is up.**
## Deploy
```bash
systemctl --user status archied archie-state-store archie-gateway archie-ui archie-messaging
curl -s http://127.0.0.1:8485/health/detailed
```
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.
3. **Open the dashboard** at <http://127.0.0.1:8484>. It binds loopback by
default; tunnel to it (`ssh -L 8484:127.0.0.1:8484 server`) or see
[deployments](deployments/README.md#running-the-dashboard) to expose it
with a token.
4. **Automate your first event** with
[Your first playbook](docs/guides/first-playbook.md): send a webhook, map
its fields, bind it to a workflow and watch the task run.
To write the config by hand instead, start from
[`deployments/standalone.toml`](deployments/standalone.toml) (no forge) or
another [deployment template](deployments/README.md).
## Develop
`task dev` starts every service with Vite hot reload at
<http://localhost:5173>, using [`deployments/dev.toml`](deployments/dev.toml).
`task check` is the quality gate; [AGENTS.md](AGENTS.md) lists its tools.
## 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.
- [Your first playbook](docs/guides/first-playbook.md)
- [Deployment examples](deployments/README.md)
- [Release process](RELEASING.md)
Contributions should follow [AGENTS.md](AGENTS.md), including its testing,
generated-file, and commit rules.
Contributions follow [AGENTS.md](AGENTS.md).
## License
+14 -7
View File
@@ -6,8 +6,8 @@ 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
The host bundle ships five processes (`archied`, `archie-gateway`,
`archie-state-store`, `archie-ui`, `archie-messaging`), 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.
@@ -46,8 +46,7 @@ the reader, not whether a sentence is negative:
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.
Design constraints and withheld capabilities are not release news.
Do not apply this mechanically: deleting a caveat a reader needs misleads them,
which is the failure this rule exists to prevent.
@@ -58,16 +57,24 @@ task release:preview VERSION=1.3.0 # preview what would land
task release:prepare VERSION=1.3.0 # write the section into CHANGELOG.md, uncommitted
# edit CHANGELOG.md -- generated notes are a starting point, not the release
task release VERSION=1.3.0 # commit + annotated tag
git push origin main --follow-tags # CI stamps images with real versions
git push --atomic origin main v1.3.0 # both refs or neither
task release:publish VERSION=1.3.0 # images to GHCR, zip to archie-releases
```
The source repository is private, so releases are published to the public
`samcharles93/archie-releases` repository, where `install.sh` and the
updater find them. `release:publish` builds from a clean worktree of the tag
and needs `gh` and `docker` logged in with write access to that repository
and to GHCR.
`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`.
tag gets images stamped `dev`, which is why the push names the tag and is
`--atomic`.
### After a release, `main` and the working branch have diverged
@@ -106,7 +113,7 @@ Tagging one version produces, from a single `deploy` run:
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
`archie-state-store`, `archie-ui`, `archie-messaging`) 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`.
+93 -62
View File
@@ -9,10 +9,62 @@ tasks:
cmds:
- task --list
fmt:
desc: Fix and format Go source
setup:
desc: Install the pinned tooling and dependencies a checkout needs
cmds:
- go fix ./...
# Report what this task cannot install for you, so a missing Go, Node or
# Docker fails here by name rather than somewhere inside the gate.
- |
set -eu
missing=
for tool in go task node npm docker; do
command -v "$tool" >/dev/null 2>&1 || missing="$missing $tool"
done
if [ -n "$missing" ]; then
echo "warning: not installed (AGENTS.md, Build and gate):$missing" >&2
fi
# The pin is one file, read here and by .github/workflows, so the linter
# running locally and the one running the gate cannot drift apart.
- |
set -eu
want=$(cat {{.ROOT_DIR}}/.golangci-version)
have=$(golangci-lint --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || true)
if [ "$have" = "${want#v}" ]; then
echo "golangci-lint $want already installed"
else
echo "installing golangci-lint $want (have: ${have:-none})"
GOBIN="$(go env GOPATH)/bin" go install "github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$want"
fi
- task: proto:install
- task: ui:deps
fmt:
desc: Fix and format Go source with the gate's configured formatters
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.
- golangci-lint fmt
proto:install:
@@ -46,21 +98,6 @@ tasks:
cmds:
- bash tools/proto.sh check
docs:generate:
desc: Regenerate the committed contract reference from Archie-owned types
cmds:
- go -C tools run -mod=readonly ./docsgen --repo-root ..
docs:check:
desc: Verify the committed contract reference matches Archie-owned types
cmds:
- go -C tools run -mod=readonly ./docsgen check --repo-root ..
docs:prds:
desc: Reject session-bound writing in docs/prds
cmds:
- go -C tools run -mod=readonly ./prdlint --repo-root ..
news:
desc: Regenerate the release data artifacts from the changelog
cmds:
@@ -71,16 +108,6 @@ tasks:
cmds:
- go -C tools run -mod=readonly ./newsgen check --repo-root ..
docs:artifact:
desc: Regenerate the canonical docs artifacts from the Markdown sources
cmds:
- go -C tools run -mod=readonly ./docsite --repo-root ..
docs:artifact:check:
desc: Verify the committed docs artifacts match the Markdown sources
cmds:
- go -C tools run -mod=readonly ./docsite check --repo-root ..
vet:
desc: Run go vet
cmds:
@@ -98,11 +125,6 @@ tasks:
cmds:
- golangci-lint run ./...
lint:playbooks:
desc: Validate playbook bindings
cmds:
- go run ./cmd/archie-playbooks lint -dir ./playbooks
vuln:
desc: Scan for known vulnerabilities (requires network access)
cmds:
@@ -113,11 +135,6 @@ tasks:
cmds:
- go run golang.org/x/tools/cmd/deadcode@latest -test=false ./cmd/...
reachaudit:
desc: Classify unreachable code against tracked work (advisory)
cmds:
- python3 tools/reachaudit/reachaudit.py --repo . {{.CLI_ARGS}}
ui:deps:
desc: Install dashboard dependencies
internal: true
@@ -125,7 +142,7 @@ tasks:
run: once
dir: ui
cmds:
- npm install --no-audit --no-fund
- npm ci --no-audit --no-fund
ui:
desc: Build the dashboard into ui/dist (committed; the Go build embeds it)
@@ -154,13 +171,13 @@ tasks:
- bash tools/webhook-send.sh {{.CLI_ARGS}}
bench:prreview:
desc: Review or rescore the Martian benchmark (-- -review-model PROVIDER/MODEL -classification-model PROVIDER/MODEL; --help for flags)
desc: Run the PR review benchmark on the configured models and write docs/benchmarks/pr-review-*.md (-- -model ALIAS -judge-model REF; --help for flags)
cmds:
- go run ./cmd/archie-prbench {{.CLI_ARGS}}
- go run ./cmd/archied prbench {{.CLI_ARGS}}
dev:
desc: Run development services and Vite at http://localhost:5173
deps: [dev:daemon, dev:gateway, dev:state-store, dev:dashboard, dev:ui]
deps: [dev:daemon, dev:gateway, dev:messaging, dev:state-store, dev:dashboard, dev:ui]
dev:postgres:
desc: Start PostgreSQL and wait for readiness
@@ -215,6 +232,12 @@ tasks:
exit 1
- go run ./cmd/archie-gateway -config-overlay deployments/dev.toml
dev:messaging:
desc: Run the development Messaging Service
cmds:
- 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-messaging -config-overlay deployments/dev.toml
dev:ui:
desc: Run Vite (requires the dashboard backend)
dir: ui
@@ -222,6 +245,22 @@ tasks:
- npm install --no-audit --no-fund
- npm run dev
e2e:up:
desc: Start the local stack without Docker (PostgreSQL 18, services, Vite) and seed it
cmds:
- bash e2e/stack.sh start
- bash e2e/seed.sh
e2e:down:
desc: Stop the local e2e stack
cmds:
- bash e2e/stack.sh stop
e2e:check:
desc: Run the browser checks against the running e2e stack (-- --record VERSION for release evidence)
cmds:
- node e2e/run.cjs {{.CLI_ARGS}}
dev:mobile:
desc: Serve the dashboard on your LAN (token-protected) for phone viewing
deps:
@@ -246,12 +285,11 @@ tasks:
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:
- Taskfile.yml
- "**/*.go"
- go.mod
- go.sum
@@ -264,11 +302,11 @@ tasks:
- "{{.BIN_DIR}}/archie-messaging"
- "{{.BIN_DIR}}/archie-agent"
cmds:
# One flag set for every service, matching scripts/archie-update-install
# and the release workflow, so each binary reports the same version.
# One flag set for every service, matching 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
cmd: go build -trimpath -ldflags "{{.SERVICE_LDFLAGS}}" -o {{.BIN_DIR}}/{{.ITEM}} ./cmd/{{.ITEM}}
- go build -trimpath -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 short Go tests with caching
@@ -280,11 +318,6 @@ tasks:
cmds:
- go test ./... -count=1
test:tools:
desc: Run the nested tools module suite, refusing to rewrite its go.mod
cmds:
- go -C tools test -mod=readonly ./... -count=1
check:
desc: Run the full quality gate
# Finish mutations before starting parallel checks.
@@ -298,23 +331,14 @@ tasks:
internal: true
deps:
- task: proto:lint
- task: docs:check
- task: docs:prds
- task: news:check
- task: docs:artifact:check
- task: vet
- task: lint
- task: build
- task: test
- task: test:tools
- task: test:ui
- task: ui:check
contract:
desc: Report contract conformance (advisory)
cmds:
- go -C tools run ./contractaudit --repo-root ..
release:preview:
desc: "Show the release notes that would be generated (VERSION=1.2.0)"
cmds:
@@ -336,6 +360,13 @@ tasks:
requires:
vars: [VERSION]
release:publish:
desc: Push the images and publish the pushed tag to the public releases repository (VERSION=1.2.0)
cmds:
- tools/publish.sh {{.VERSION}}
requires:
vars: [VERSION]
clean:
desc: Remove build artifacts
cmds:
+296
View File
@@ -0,0 +1,296 @@
# Workflow definitions
A workflow is a YAML document: an id, what it declares to whatever starts it,
and an ordered list of steps. Definitions are stored in the control plane's
`workflow-definitions` resource and edited on the dashboard's Workflows page
(the Canvas and YAML tabs edit the same document). The shipped workflows are in
`internal/domain/workflow/shipped/`.
The server is the authority. It serves the step vocabulary, including each step
type's settings schema, in the `workflow-definitions` catalog entry
(`x-step-types`), and validates every definition when it is saved. This file
describes that vocabulary; when they disagree, the catalog wins.
```yaml
id: implement
repository: required
inputs:
pr_number: {type: number, required: true}
steps:
- type: repo.prepare
- id: plan
type: agent.run
settings:
read_only: true
mission: |
Plan this change: {{ task.prompt }}
- id: build
type: agent.run
settings:
gate: repository
mission: "Implement it following this plan: {{ steps.plan.summary }}"
- type: repo.commit
settings: {message: "{{ task.title }}", push: true, if_empty: complete}
- type: repo.open-pr
settings: {body: "{{ steps.build.summary }}"}
```
## The workflow
| Field | Type | Meaning |
|---|---|---|
| `id` | text | The workflow's name. Required, unique. |
| `steps` | list | The steps, run in order. At least one. |
| `repository` | `required` \| `optional` \| `none` | `required` (the default) clones the task's repository into a worktree. `optional` clones one when the run names a repository and uses a scratch workspace otherwise. `none` never clones; only steps that run without a repository may be used. |
| `inputs` | mapping | Named, typed values whatever starts the run must supply: `{type, required}`, where type is `string`, `number`, `bool`, `object`, `array` or `any`. Steps read them as `{{ inputs.<name> }}`. |
| `outputs` | mapping | Named, typed results the run writes once each (same shape as inputs). A required output the run never writes parks it. A calling workflow reads them. |
| `profile` | text | The container profile (`[containers.profiles]`) the run's agents use. Resolved when the task is dispatched. |
| `identity` | text | The identity every run acts as, whatever started it. Empty runs as the starter. |
| `needs` | mapping | Harness capabilities the run requires: `captures` (bool), `gate_retries` (number). Declared outputs imply `captures`. |
## A step
| Field | Type | Meaning |
|---|---|---|
| `type` | text | The step type (below). |
| `id` | text | Names the step so later steps can read its result. Unique in the workflow; letters, digits, `-` and `_`. The run records the step under this name. |
| `settings` | mapping | The step type's settings. String settings may contain references. |
| `when` | condition | Skip the step unless the condition holds. |
| `on_failure` | `park` \| `continue` | `park` (the default) stops the run for an operator. `continue` records the failure and moves on. |
| `retry` | mapping | `attempts` (1 to 10) and `backoff` (a duration such as `30s`). A failed step runs again before `on_failure` applies. |
| `parallel` | mapping | Instead of `type`: named branches, each a list of steps, run at the same time. |
### References
Any string setting may contain `{{ path }}`, replaced when the step runs:
| Path | Value |
|---|---|
| `task.title`, `task.body` | The issue or chat request. |
| `task.prompt` | The title and body framed for an agent mission. |
| `task.repository` | `owner/name`. |
| `task.kind` | What the task came from, as prose: `GitHub issue` or `chat-originated task`. |
| `task.issue`, `task.pr` | Issue and pull request numbers. |
| `task.plan` | The plan a `human.approve` step handed over (an approved PRD). |
| `task.review` | The review comments a remediation round addresses. |
| `inputs.<name>` | A declared input; an undeclared one is refused at save. |
| `steps.<id>.summary` | What an earlier step reported, e.g. an agent's finish summary or a gate's output. |
| `steps.<id>.result.<field>` | A field of an earlier agent's structured result, or an output of an earlier `workflow.call` that waits. A field the agent's `result` schema or the callee's `outputs` does not declare is refused at save. |
Only earlier steps may be referenced; a reference to a later or unknown step is
refused when the definition is saved. A value that does not exist at run time
(for instance, a step that was skipped) renders empty.
### Conditions
`when` is a reference path, written without braces:
- `steps.assess.result.fit` holds when the value is true, a non-empty string other than `false`, or a non-zero number.
- `!steps.assess.result.fit` holds when it does not.
- `steps.classify.result.workflow == tdd` and `!=` compare the value as text.
### Parallel branches
```yaml
- id: research
parallel:
code: [{id: code, type: agent.run, settings: {mission: ..., read_only: true}}]
docs: [{id: docs, type: agent.run, settings: {mission: ..., read_only: true}}]
- type: agent.run
settings: {mission: "{{ steps.code.summary }} {{ steps.docs.summary }}"}
```
Branches share one worktree, so only read-only `agent.run` and `workflow.call`
steps may run in them. A branch sees the steps before the parallel step and its
own earlier steps, never a sibling's. Every branch's results are visible after
it. Parallel steps do not nest, and need at least two branches.
### How a run ends
A run ends at the first step that sets an outcome: `workflow.finish`,
`workflow.handoff`, `human.approve`, `repo.open-pr`, `repo.commit` with
`if_empty: complete`, or `review.reply`. A run that reaches the end of its steps
completes, with the last step's summary as its detail. A step that fails parks
the run unless it continues on failure.
A parked run can be retried from a top-level step instead of from the start.
The steps before it are skipped and their results stay available to
references. The resume point is named by the step's id (else its type), so
give an id to any step whose type appears twice. A run with a repository
resumes only on its pushed branch: work an earlier step did not push is not
there.
## Step types
### `agent.run`
_runs without a repository._
| Setting | Type | Meaning |
|---|---|---|
| `extra_rules` | text | Appended to the agent system prompt. |
| `gate` | `repository` \| `test-failure` | Hold the agent to the repository gate before it may finish; test-failure requires the tests to fail. |
| `mission` | text | What the agent is asked to do. May reference {{ task.* }}, {{ inputs.* }} and {{ steps.<id>.* }}. |
| `protect_tests` | bool | Write-block the repository test files. |
| `read_only` | bool | Restrict the agent to read-only tools. |
| `result` | mapping | A JSON Schema object the agent must return; later steps read it as steps.<id>.result. |
| `model` | text | The model alias that runs the agent, e.g. default or fast. Empty means default. |
### `command.run`
_needs a repository._
| Setting | Type | Meaning |
|---|---|---|
| `level` | `error` \| `warn` | error stops the run on a failing command; warn reports it and continues. |
| `run` | list of mapping | The commands to run in order; the first failure ends the step. |
### `repo.commit`
_needs a repository._
| Setting | Type | Meaning |
|---|---|---|
| `if_empty` | `fail` \| `skip` \| `complete` | fail stops the run, skip moves on, complete closes the issue and ends the run. |
| `message` | text | The commit message. |
| `push` | bool | Push the branch after committing. |
| `reference` | `Fixes` \| `Implements` \| `Refs` | How the commit links to the task issue. |
### `repo.open-pr`
_needs a repository._
| Setting | Type | Meaning |
|---|---|---|
| `body` | text | The pull request description. |
| `review` | bool | Review the change first; a blocking finding parks the task instead of opening the PR. |
### `repo.prepare`
_needs a repository._
| Setting | Type | Meaning |
|---|---|---|
| `branch` | `fresh` \| `task` | fresh starts a new branch from the base; task resumes the branch this task pushed. |
### `gate.diff-rules`
_needs a repository._
| Setting | Type | Meaning |
|---|---|---|
| `rules` | list of mapping | Patterns the change must not match. |
### `gate.diff-size`
_needs a repository._
No settings.
### `gate.repository`
_needs a repository._
| Setting | Type | Meaning |
|---|---|---|
| `expect` | `pass` \| `test-failure` | pass requires every gate command to pass; test-failure requires the test command to fail. |
| `repair` | bool | Let the builder fix a failing gate before the step fails. |
### `forge.close-issue`
_runs without a repository._
No settings.
### `forge.comment`
_runs without a repository._
| Setting | Type | Meaning |
|---|---|---|
| `body` | text | The comment text. |
| `on` | `issue` \| `pr` | Comment on the issue or the pull request. Empty means issue. |
### `human.approve`
_runs without a repository._
| Setting | Type | Meaning |
|---|---|---|
| `plan` | text | What the human decides on; the next workflow reads it as task.plan. |
| `then` | text | The workflow the task runs once approved. |
### `review.pr`
_needs a repository._
No settings.
### `review.reply`
_needs a repository._
| Setting | Type | Meaning |
|---|---|---|
| `body` | text | The reply to the review. |
### `review.start-round`
_needs a repository._
No settings.
### `workflow.call`
_runs without a repository._
| Setting | Type | Meaning |
|---|---|---|
| `inputs` | mapping | Callee input names mapped to scalar literals or `inputs.<name>` references to caller inputs. |
| `outputs` | mapping | Callee output names mapped to `outputs.<name>` references to caller outputs; requires `wait: true`. |
| `wait` | bool | Wait for the child run to finish before continuing. |
| `workflow` | text | The workflow to start as a child run. |
The step must declare an `id`: the step's id is the key of the call it starts,
so a retry of that call site returns the child already started instead of
starting a second one.
### `workflow.finish`
_runs without a repository._
| Setting | Type | Meaning |
|---|---|---|
| `detail` | text | What the operator reads about the outcome. |
| `status` | `completed` \| `parked` \| `waiting_human` \| `declined` | How the run ends. Empty means completed. |
### `workflow.handoff`
_runs without a repository._
| Setting | Type | Meaning |
|---|---|---|
| `detail` | text | Why the task was handed off. |
| `workflow` | text | The workflow the task is requeued under. |
`command.run` commands are `{name, argv, expect_failure}`: `argv` is the
program and its arguments, and `expect_failure` requires a non-zero exit.
`gate.diff-rules` rules are `{id, level, pattern, path, exclude_path, message}`:
`level` (`error` blocks, `warn` reports) and `pattern` (an RE2 expression matched
against each added line) are required; `path` and `exclude_path` are RE2
expressions that limit which files the rule applies to.
## What starts a workflow
- **Issues**, by label: `bug` runs `tdd`, `feature` runs `feasibility`, anything
else runs `triage`, which classifies it and hands off.
- **Event bindings**: a webhook source mapped onto a workflow and its inputs
(Events page).
- **Playbooks**: a trigger (issue kind and labels) and actions that dispatch
workflows.
- **Other workflows**: `workflow.call` (a child run), `workflow.handoff` (the
same task, requeued), `human.approve` (once approved).
- **By hand**: the New task form, or Run on the Workflows page.
The canvas Start node lists the triggers of each workflow.
+9
View File
@@ -0,0 +1,9 @@
package configtemplate
import _ "embed"
// Changelog is the verbatim contents of CHANGELOG.md, so a binary carries the
// release notes for the version it was built as.
//
//go:embed CHANGELOG.md
var Changelog string
-110
View File
@@ -1,110 +0,0 @@
package main
import (
"go/ast"
"go/parser"
"go/token"
"path/filepath"
"strconv"
"strings"
"testing"
)
func TestCommandBoundary(t *testing.T) {
paths, err := filepath.Glob("*.go")
if err != nil {
t.Fatal(err)
}
for _, path := range paths {
if !strings.HasSuffix(path, "_test.go") && path != "main.go" {
t.Errorf("cmd/archie-agent contains substantive production file %q; runtime ownership belongs in internal/app/agentworker", path)
}
}
file, err := parser.ParseFile(token.NewFileSet(), "main.go", nil, 0)
if err != nil {
t.Fatal(err)
}
const (
projectInternal = "github.com/samcharles93/archie-core/internal/"
appImport = projectInternal + "app/agentworker"
)
appIdent := "agentworker"
for _, imported := range file.Imports {
path, err := strconv.Unquote(imported.Path.Value)
if err != nil {
t.Fatal(err)
}
if strings.HasPrefix(path, projectInternal) && path != appImport {
t.Errorf("cmd/archie-agent imports substantive internal package %q; only %q is allowed", path, appImport)
}
if path == appImport && imported.Name != nil {
if imported.Name.Name == "." || imported.Name.Name == "_" {
t.Errorf("cmd/archie-agent imports %q with unsupported alias %q", appImport, imported.Name.Name)
} else {
appIdent = imported.Name.Name
}
}
}
allowedFunctions := map[string]bool{
"main": true,
"run": true,
"runCommand": true,
"natsConnectionSettings": true,
"runRelay": true,
"runMCP": true,
}
for _, declaration := range file.Decls {
function, ok := declaration.(*ast.FuncDecl)
if !ok {
continue
}
if function.Recv != nil || !allowedFunctions[function.Name.Name] {
t.Errorf("cmd/archie-agent main.go declares unexpected function %q; orchestration belongs in internal/app/agentworker", function.Name.Name)
}
delete(allowedFunctions, function.Name.Name)
}
for name := range allowedFunctions {
t.Errorf("cmd/archie-agent main.go is missing intended process function %q", name)
}
var runFunction *ast.FuncDecl
for _, declaration := range file.Decls {
function, ok := declaration.(*ast.FuncDecl)
if ok && function.Name.Name == "run" {
runFunction = function
break
}
}
if runFunction == nil {
t.Fatal("cmd/archie-agent has no run function")
}
workerCalls := 0
ast.Inspect(runFunction.Body, func(node ast.Node) bool {
call, ok := node.(*ast.CallExpr)
if !ok {
return true
}
callee, ok := call.Fun.(*ast.Ident)
if !ok || callee.Name != "runCommand" {
return true
}
for _, argument := range call.Args {
selector, ok := argument.(*ast.SelectorExpr)
if !ok || selector.Sel.Name != "Run" {
continue
}
pkg, ok := selector.X.(*ast.Ident)
if ok && pkg.Name == appIdent {
workerCalls++
}
}
return true
})
if workerCalls != 1 {
t.Fatalf("cmd/archie-agent run passes agentworker.Run to runCommand %d times, want exactly 1", workerCalls)
}
}
+19
View File
@@ -15,10 +15,22 @@ import (
"syscall"
"github.com/samcharles93/archie-core/internal/app/agentworker"
"github.com/samcharles93/archie-core/internal/infrastructure/egress"
)
type workerRunner func(context.Context, agentworker.Settings, *slog.Logger) error
// runHold blocks until signalled and exits 0. It is the keepalive for a Kit
// container that runs no worker: the agent binary is archie's own and is
// mounted into every Kit, so the container needs no binary the image may not
// ship, and holds no environment of its own.
func runHold() int {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
<-ctx.Done()
return 0
}
func main() {
os.Exit(run())
}
@@ -28,6 +40,9 @@ func run() int {
}
func runCommand(args []string, getenv func(string) string, stderr io.Writer, runWorker workerRunner) int {
if len(args) > 0 && args[0] == "hold" {
return runHold()
}
if len(args) > 0 && args[0] == "relay" {
return runRelay(args[1:], stderr, agentworker.RunRelay)
}
@@ -76,6 +91,10 @@ func runCommand(args []string, getenv func(string) string, stderr io.Writer, run
NATSToken: natsToken,
StateStoreTarget: stateStoreURL,
StateStoreToken: stateStoreToken,
StateStoreCA: []byte(getenv("STATE_STORE_CA")),
ModelProxy: getenv(egress.ModelProxyEnv),
ModelProxyHosts: egress.ParseHosts(getenv(egress.ModelProxyHostsEnv)),
ModelProxyCA: getenv(egress.ModelProxyCAEnv),
}, log); err != nil {
return 1
}
-54
View File
@@ -1,54 +0,0 @@
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())
}
}
-134
View File
@@ -1,134 +0,0 @@
package main
import (
"bytes"
"context"
"errors"
"log/slog"
"strings"
"testing"
"github.com/samcharles93/archie-core/internal/app/agentworker"
)
func TestRunCommandPreservesCLIExitSemantics(t *testing.T) {
tests := []struct {
name string
args []string
getenv func(string) string
worker workerRunner
wantCode int
}{
{name: "help", args: []string{"-h"}},
{name: "flag parse error", args: []string{"-unknown"}, wantCode: 2},
{name: "removed consumer flag", args: []string{"-consumer", "legacy"}, wantCode: 2},
{name: "missing NATS URL", wantCode: 1},
{name: "missing state store URL", args: []string{"-nats-url", "nats://test"}, wantCode: 1},
{
name: "worker failure",
args: []string{"-nats-url", "nats://test", "-state-store-url", "127.0.0.1:9090"},
worker: func(context.Context, agentworker.Settings, *slog.Logger) error {
return errors.New("worker failed")
},
wantCode: 1,
},
{
name: "success",
args: []string{"-nats-url", "nats://test", "-state-store-url", "127.0.0.1:9090"},
worker: func(context.Context, agentworker.Settings, *slog.Logger) error {
return nil
},
},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
getenv := test.getenv
if getenv == nil {
getenv = func(string) string { return "" }
}
worker := test.worker
if worker == nil {
worker = func(context.Context, agentworker.Settings, *slog.Logger) error {
t.Fatal("worker called")
return nil
}
}
if got := runCommand(test.args, getenv, &bytes.Buffer{}, worker); got != test.wantCode {
t.Fatalf("runCommand() = %d, want %d", got, test.wantCode)
}
})
}
}
func TestRunCommandRequiresNATSURL(t *testing.T) {
var stderr bytes.Buffer
called := false
code := runCommand(nil, func(string) string { return "" }, &stderr, func(context.Context, agentworker.Settings, *slog.Logger) error {
called = true
return nil
})
if code != 1 || called {
t.Fatalf("(code, worker called) = (%d, %v), want (1, false)", code, called)
}
for _, want := range []string{"error: -nats-url or NATS_URL is required", "Usage of archie-agent:"} {
if !strings.Contains(stderr.String(), want) {
t.Fatalf("stderr %q does not contain %q", stderr.String(), want)
}
}
}
func TestRunCommandMapsWorkerOutcomeToExitStatus(t *testing.T) {
workerErr := errors.New("startup failed")
tests := []struct {
name string
workerErr error
wantCode int
}{
{name: "success"},
{name: "worker failure", workerErr: workerErr, wantCode: 1},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
var stderr bytes.Buffer
code := runCommand([]string{"-nats-url", "nats://flag"}, func(string) string { return "token" }, &stderr, func(_ context.Context, settings agentworker.Settings, _ *slog.Logger) error {
if settings.NATSURL != "nats://flag" || settings.NATSToken != "token" {
t.Fatalf("settings = %#v", settings)
}
return test.workerErr
})
if code != test.wantCode {
t.Fatalf("code = %d, want %d", code, test.wantCode)
}
if test.workerErr != nil && stderr.Len() != 0 {
t.Fatalf("stderr = %q, want command not to duplicate application logging", stderr.String())
}
})
}
}
func TestNATSConnectionSettings(t *testing.T) {
getenv := func(name string) string {
switch name {
case "NATS_URL":
return "nats://nats.example:4222"
case "NATS_TOKEN":
return "test-nats-token"
default:
return ""
}
}
t.Run("container environment", func(t *testing.T) {
url, token := natsConnectionSettings("", getenv)
if url != "nats://nats.example:4222" || token != "test-nats-token" {
t.Fatalf("natsConnectionSettings() = (%q, %q)", url, token)
}
})
t.Run("flag URL takes precedence", func(t *testing.T) {
url, token := natsConnectionSettings("nats://flag.example:4222", getenv)
if url != "nats://flag.example:4222" || token != "test-nats-token" {
t.Fatalf("natsConnectionSettings() = (%q, %q)", url, token)
}
})
}
+3 -4
View File
@@ -9,7 +9,7 @@ import (
"os/signal"
"syscall"
"github.com/samcharles93/archie-core/internal/app/archied"
"github.com/samcharles93/archie-core/internal/app/archiegateway"
"github.com/samcharles93/archie-core/internal/buildinfo"
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
)
@@ -17,17 +17,16 @@ import (
func main() { os.Exit(run()) }
func run() int {
var options archied.GatewayOptions
var options archiegateway.Options
showVersion := buildinfo.RegisterVersionFlag("archie-gateway")
flag.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory")
flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory")
flag.StringVar(&options.Listen, "listen", "", "gateway gRPC listen address (defaults to [services.gateway].listen, else 127.0.0.1:8585)")
flag.StringVar(&options.Token, "token", "", "Bearer [REDACTED] required for a non-loopback listener (defaults to [services.gateway].target_token)")
flag.Parse()
showVersion()
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
if err := archied.RunGateway(ctx, options); err != nil {
if err := archiegateway.Run(ctx, options); err != nil {
fmt.Fprintln(os.Stderr, err)
return 1
}
-163
View File
@@ -1,163 +0,0 @@
// This file enforces the objective half of the Messaging Service deletion gate
// (docs/prds/messaging-service-boundary.md, "Deletion Gate and Verification"): the
// linked binary carries no state-store, daemon, workflow, forge, gateway or
// dashboard runtime. Go imports are atomic, so a single reference to a type living
// beside a runtime relinks the runtime, and the severance holds only while
// something re-measures it. That is exactly how this package came to link the
// SQLite driver, the workflow engine and agentexec through one import of
// internal/app/controlplane (archie-core-1ng1).
package main
import (
"os/exec"
"strings"
"testing"
)
const modulePath = "github.com/samcharles93/archie-core/"
// bannedCategory is one class of runtime the Messaging Service must not link.
// The names are the PRD's wording; the prefixes are how that class appears in
// this module.
type bannedCategory struct {
name string
prefixes []string
}
// deletionGate is the PRD's list, one entry per category it names. Two deliberate
// absences:
//
// - internal/channels is NOT here. The Messaging Service hosts those adapters;
// it is the process they live in, not a consumer of them.
// - internal/gatewayrpc needs no exception. It is the Gateway's contract, not
// its runtime, and it does not sit under the internal/gateway prefix -- the
// check below would catch it if it ever did.
var deletionGate = []bannedCategory{
{"state store", []string{
"modernc.org/sqlite",
"github.com/jackc/pgx",
modulePath + "internal/infrastructure/postgres",
}},
{"daemon runtime", []string{
modulePath + "internal/daemon",
modulePath + "internal/app/archied",
modulePath + "internal/container",
modulePath + "internal/worktree",
}},
{"workflow engine", []string{
modulePath + "internal/domain/workflow",
modulePath + "internal/agentexec",
modulePath + "internal/taskrun",
}},
{"forge client", []string{
modulePath + "internal/forge",
modulePath + "internal/forgerpc",
}},
{"gateway runtime", []string{
modulePath + "internal/gateway",
}},
// The PRD names "Direct LLM providers, model runtimes" among what the
// Messaging Service must not own or link. These are the in-module
// infrastructure packages that construct one; building either here means
// a model-provider credential is in the messaging process.
{"model providers", []string{
modulePath + "internal/infrastructure/transcription",
modulePath + "internal/infrastructure/embedding",
}},
{"dashboard", []string{
modulePath + "internal/webui",
}},
}
// gateExceptions are packages under a banned prefix that carry only contract,
// vocabulary or view types, so linking them is the intended end state rather
// than a tolerated leak. internal/domain/workflow/task is the Task status and
// view vocabulary the Messaging Service renders; its own dependency set holds
// none of the banned runtimes, which is what makes the exception defensible
// rather than a hole. cmd/archie-ui/architecture_test.go carries the same entry
// for the same reason.
//
// Each one must stay linked: an exception nothing needs any more is a hole in
// the fence, so this list is checked in both directions.
var gateExceptions = []string{
modulePath + "internal/domain/workflow/task",
}
// under reports whether importPath is prefix or a package below it.
func under(importPath, prefix string) bool {
return importPath == prefix || strings.HasPrefix(importPath, prefix+"/")
}
func TestMessagingProcessLinksNoRuntimeItOnlyDials(t *testing.T) {
listed, err := exec.CommandContext(t.Context(), "go", "list", "-deps", ".").CombinedOutput()
if err != nil {
t.Fatalf("go list -deps .: %v\n%s", err, listed)
}
linked := make(map[string]bool, len(gateExceptions))
for importPath := range strings.FieldsSeq(string(listed)) {
if excepted(importPath, linked) {
continue
}
if category, banned := bannedLink(importPath); banned {
t.Errorf("archie-messaging links %s (%s); the Messaging Service reaches that capability over a contract, never in-process (docs/prds/messaging-service-boundary.md, deletion gate)", importPath, category)
}
}
for _, exception := range gateExceptions {
if !linked[exception] {
t.Errorf("%s is excepted from the deletion gate but is no longer linked; drop the exception instead of leaving its prefix open", exception)
}
}
// A gate that cannot fail, and a `go list` that returns nothing usable, both
// read as a pass. This pins the one thing the loop above assumes.
if !strings.Contains(string(listed), modulePath+"cmd/archie-messaging") {
t.Fatal("go list -deps returned a list that does not even name this package: the gate asserted nothing")
}
}
// bannedLink reports the deletion-gate category importPath falls under, or
// ("", false). Classifying a single package is the rule the unit test below
// pins, so the gate can be exercised without a live `go list`.
func bannedLink(importPath string) (category string, banned bool) {
for _, c := range deletionGate {
for _, prefix := range c.prefixes {
if under(importPath, prefix) {
return c.name, true
}
}
}
return "", false
}
// TestDeletionGateBansModelProviderCapabilities pins the PRD category that the
// voice-transcription violation slipped past: the link gate would not flag
// anything merely because the process built an LLM client, so the capability
// packages are named explicitly. gatewayrpc is checked as the negative, since
// it is the permitted contract and must not be swept up by the internal/
// infrastructure/ prefix.
func TestDeletionGateBansModelProviderCapabilities(t *testing.T) {
for _, pkg := range []string{
modulePath + "internal/infrastructure/transcription",
modulePath + "internal/infrastructure/embedding",
} {
if _, banned := bannedLink(pkg); !banned {
t.Errorf("bannedLink(%q) = not banned; the Messaging Service must not construct a model-provider capability in-process", pkg)
}
}
if category, banned := bannedLink(modulePath + "internal/infrastructure/gatewayrpc"); banned {
t.Errorf("bannedLink(gatewayrpc) = %q; the Gateway contract is permitted", category)
}
}
// excepted reports whether importPath sits under an excepted package, recording
// the ones actually linked so a stale exception fails.
func excepted(importPath string, linked map[string]bool) bool {
for _, exception := range gateExceptions {
if under(importPath, exception) {
linked[exception] = true
return true
}
}
return false
}
-433
View File
@@ -1,433 +0,0 @@
// The link gate in architecture_test.go measures which packages the Messaging
// binary links. It cannot see a process that links nothing new but still reads
// a decoded configuration value it is not allowed to own -- which is exactly
// how voice transcription was wired into the Messaging Service while a green
// link gate watched: internal/app/archiemessaging/config.go built an LLM
// transcriber from [models].transcription and [providers.*], both of which
// docs/prds/messaging-service-boundary.md reserves to the model-owning process.
//
// This file closes that shape of hole: it scans the Messaging Service's own
// production sources for a read of a top-level config section the PRD forbids,
// so re-adding the projection field fails here rather than shipping green.
package main
import (
"go/ast"
"go/parser"
"go/token"
"os"
"path/filepath"
"strings"
"testing"
)
// messagingAppDir is the Messaging Service's application package, relative to
// this package's directory (go test runs with the package dir as cwd).
const messagingAppDir = "../../internal/app/archiemessaging"
// bannedConfigFields are the top-level config.Config fields the Messaging
// Service must never read, by Go field name. The PRD's "Configuration
// Ownership" section permits [chat.*], [services.*], [secrets] and the
// path/identity keys the process needs to locate itself; every entry here is a
// capability another process owns. internal/config's field names are the
// concrete keys, because that is what a Go read names.
var bannedConfigFields = map[string]bool{
"Forge": true, // [forge]
"Repos": true, // [repos]
"Models": true, // [models]
"Providers": true, // [providers]
"Containers": true, // [containers]
"NATS": true, // [nats]
// [runners] has no top-level field in internal/config today; if one is
// added its own name must be listed here with it.
}
// configReadOffenders returns the banned "<holder>.<Field>" config reads in
// src, in source order. A holder is anything the file gives the
// internal/config.Config type: an explicitly typed parameter, var, receiver or
// struct field, a short variable declaration or inferred var whose right-hand
// side resolves to one ("cfg := doc.Config"), or a range variable over a slice
// of them. The type is tracked by name because a name is what a Go read
// selects on. A config value returned by a call this file does not declare is
// outside a syntactic rule and stays untracked.
func configReadOffenders(src []byte) []string {
fset := token.NewFileSet()
file, err := parser.ParseFile(fset, "config.go", src, parser.SkipObjectResolution)
if err != nil {
// A file that does not parse is reported as an offender rather than
// ignored: silently skipping it would make this gate blind exactly
// when the tree is broken.
return []string{"parse error: " + err.Error()}
}
kinds := configKinds(file)
var offenders []string
ast.Inspect(file, func(n ast.Node) bool {
sel, ok := n.(*ast.SelectorExpr)
if !ok || !bannedConfigFields[sel.Sel.Name] {
return true
}
switch base := sel.X.(type) {
case *ast.Ident:
if kinds[base.Name] == configValue {
offenders = append(offenders, base.Name+"."+sel.Sel.Name)
}
case *ast.SelectorExpr:
// doc.Config, or the config-typed struct field h.cfg. Config is
// named by configuration.Document in another package, so it
// cannot come out of the kinds map; treat a selected Config as
// a config holder unconditionally.
if base.Sel.Name == "Config" || kinds[base.Sel.Name] == configValue {
offenders = append(offenders, base.Sel.Name+"."+sel.Sel.Name)
}
}
return true
})
return offenders
}
// configKind is how an identifier or expression reaches a config.Config value.
type configKind int
const (
notConfig configKind = iota // not a config value
configValue // config.Config
configSlice // []config.Config, [N]config.Config or map[K]config.Config
)
// configKinds resolves the identifiers in file that hold a config.Config, in
// two passes because an inferred holder's source must be classified before the
// holder's own name can be.
func configKinds(file *ast.File) map[string]configKind {
kinds := map[string]configKind{}
ast.Inspect(file, func(n ast.Node) bool {
switch node := n.(type) {
case *ast.FuncDecl:
classifyFields(node.Recv, kinds)
classifyFields(node.Type.Params, kinds)
case *ast.ValueSpec:
classifyNames(node.Type, node.Names, kinds)
case *ast.StructType:
for _, field := range node.Fields.List {
classifyNames(field.Type, field.Names, kinds)
}
}
return true
})
// Inferred holders: a single source-order pass suffices because Go
// requires a name to be declared before it is referenced.
ast.Inspect(file, func(n ast.Node) bool {
switch node := n.(type) {
case *ast.AssignStmt:
if node.Tok != token.DEFINE {
return true
}
classifyValues(node.Lhs, node.Rhs, kinds)
case *ast.ValueSpec:
// An explicit type was handled above; here only "var cfg =
// doc.Config", which infers the same way a := does.
if node.Type != nil {
return true
}
names := make([]ast.Expr, len(node.Names))
for i, name := range node.Names {
names[i] = name
}
classifyValues(names, node.Values, kinds)
case *ast.RangeStmt:
if exprKind(node.X, kinds) != configSlice {
return true
}
if id, ok := node.Value.(*ast.Ident); ok {
kinds[id.Name] = configValue
}
}
return true
})
return kinds
}
// classifyValues records each lhs identifier that resolves to a config kind of
// the rhs expression in the same position. A shorter lhs or rhs is fine;
// position is what pairs a name with its value.
func classifyValues(lhs, rhs []ast.Expr, kinds map[string]configKind) {
for i, target := range lhs {
if i >= len(rhs) {
return
}
id, ok := target.(*ast.Ident)
if !ok {
continue
}
if kind := exprKind(rhs[i], kinds); kind != notConfig {
kinds[id.Name] = kind
}
}
}
// classifyFields records every named field in fields whose type holds a
// config.Config.
func classifyFields(fields *ast.FieldList, kinds map[string]configKind) {
if fields == nil {
return
}
for _, field := range fields.List {
classifyNames(field.Type, field.Names, kinds)
}
}
// classifyNames records names as holding the config kind of typ.
func classifyNames(typ ast.Expr, names []*ast.Ident, kinds map[string]configKind) {
kind := typeKind(typ)
if kind == notConfig {
return
}
for _, name := range names {
kinds[name.Name] = kind
}
}
// exprKind resolves the config kind of an expression from the identifiers
// already classified in kinds.
func exprKind(expr ast.Expr, kinds map[string]configKind) configKind {
switch e := expr.(type) {
case *ast.Ident:
return kinds[e.Name]
case *ast.SelectorExpr:
// doc.Config of a configuration.Document, or a struct field the file
// declared as config.Config.
if e.Sel.Name == "Config" {
return configValue
}
return kinds[e.Sel.Name]
case *ast.CompositeLit:
return typeKind(e.Type)
case *ast.StarExpr:
return exprKind(e.X, kinds)
case *ast.UnaryExpr:
return exprKind(e.X, kinds)
case *ast.ParenExpr:
return exprKind(e.X, kinds)
case *ast.IndexExpr:
if exprKind(e.X, kinds) == configSlice {
return configValue
}
}
return notConfig
}
// typeKind reports the config kind a type expression names: config.Config, or
// a slice, array or map whose element is one.
func typeKind(expr ast.Expr) configKind {
switch t := expr.(type) {
case *ast.ArrayType:
if isConfigType(t.Elt) {
return configSlice
}
case *ast.MapType:
// A map's range value is its element; classify the map itself as a
// slice-like source so a range over it yields config values.
if isConfigType(t.Value) {
return configSlice
}
case *ast.StarExpr:
return typeKind(t.X)
case *ast.ParenExpr:
return typeKind(t.X)
}
if isConfigType(expr) {
return configValue
}
return notConfig
}
// isConfigType reports whether expr names internal/config's Config type,
// directly or behind a pointer.
func isConfigType(expr ast.Expr) bool {
switch t := expr.(type) {
case *ast.SelectorExpr:
id, ok := t.X.(*ast.Ident)
return ok && id.Name == "config" && t.Sel.Name == "Config"
case *ast.StarExpr:
return isConfigType(t.X)
}
return false
}
// TestMessagingReadsNoBannedConfigSection is the live gate: every production
// source file in the Messaging Service's application package is scanned, and a
// read of a PRD-forbidden section fails the build.
func TestMessagingReadsNoBannedConfigSection(t *testing.T) {
entries, err := os.ReadDir(messagingAppDir)
if err != nil {
t.Fatalf("read %s: %v", messagingAppDir, err)
}
scanned := 0
for _, entry := range entries {
name := entry.Name()
if entry.IsDir() || !strings.HasSuffix(name, ".go") || strings.HasSuffix(name, "_test.go") {
continue
}
src, err := os.ReadFile(filepath.Join(messagingAppDir, name))
if err != nil {
t.Fatalf("read %s: %v", name, err)
}
scanned++
for _, offender := range configReadOffenders(src) {
t.Errorf("%s reads %s; the Messaging Service must not read or decode that section (docs/prds/messaging-service-boundary.md, Configuration Ownership) -- the capability belongs to the model-owning process, reached over a contract", name, offender)
}
}
// A gate that read no files would pass silently. Pin that it scanned the
// package it names.
if scanned == 0 {
t.Fatalf("no production .go files found in %s: the gate asserted nothing", messagingAppDir)
}
}
// TestConfigReadRuleCatchesTheOldWiring proves the rule fails on a synthetic
// copy of the shape that shipped: a projection built by reading
// [models].transcription and [providers.*]. Without this, the live gate's rule
// could rot into a no-op and still report a pass.
func TestConfigReadRuleCatchesTheOldWiring(t *testing.T) {
const reverted = `package archiemessaging
import (
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/infrastructure/transcription"
)
func project(cfg config.Config) projection {
return projection{
models: cfg.Models,
providers: cfg.Providers,
}
}
func setupTranscriber(cfg config.Config) {
_, _ = transcription.New(cfg.Models, cfg.Providers, transcription.Options{})
}
`
got := configReadOffenders([]byte(reverted))
want := []string{"cfg.Models", "cfg.Providers", "cfg.Models", "cfg.Providers"}
if strings.Join(got, ",") != strings.Join(want, ",") {
t.Fatalf("configReadOffenders() = %v, want %v", got, want)
}
}
// TestConfigReadRuleCatchesInferredHolders covers the holder shapes the first
// cut of this rule missed. It only saw a config.Config written out as a
// parameter or var type, so a value reached through an inferred short
// variable declaration ("cfg := doc.Config") or held in a struct field
// ("h.cfg.Models") left the forbidden [models]/[providers] read intact while
// the rule saw no holder to blame. Each case here fails red against that rule:
// the live gate would have reported a pass with the violation still shipping.
func TestConfigReadRuleCatchesInferredHolders(t *testing.T) {
cases := []struct {
name string
src string
want []string
}{
{
name: "short var decl from a Document's Config field",
src: `package archiemessaging
import "github.com/samcharles93/archie-core/internal/infrastructure/configuration"
func f(doc configuration.Document) {
cfg := doc.Config
_ = cfg.Models
}
`,
want: []string{"cfg.Models"},
},
{
name: "inferred var without an explicit type",
src: `package archiemessaging
import "github.com/samcharles93/archie-core/internal/infrastructure/configuration"
func f(doc configuration.Document) {
var cfg = doc.Config
_ = cfg.Models
}
`,
want: []string{"cfg.Models"},
},
{
name: "short var decl inherits config type from another holder",
src: `package archiemessaging
import "github.com/samcharles93/archie-core/internal/config"
func f(cfg config.Config) {
other := cfg
_ = other.Providers
}
`,
want: []string{"other.Providers"},
},
{
name: "config held in a struct field",
src: `package archiemessaging
import "github.com/samcharles93/archie-core/internal/config"
type holder struct {
cfg config.Config
}
func f(h holder) {
_ = h.cfg.Providers
}
`,
want: []string{"cfg.Providers"},
},
{
name: "range variable over a slice of config",
src: `package archiemessaging
import "github.com/samcharles93/archie-core/internal/config"
func f(cfgs []config.Config) {
for _, cfg := range cfgs {
_ = cfg.Models
}
}
`,
want: []string{"cfg.Models"},
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
got := configReadOffenders([]byte(tc.src))
if strings.Join(got, ",") != strings.Join(tc.want, ",") {
t.Fatalf("configReadOffenders() = %v, want %v", got, tc.want)
}
})
}
}
// TestConfigReadRuleAllowsThePermittedKeys proves the rule is not a blanket
// ban on config access: the sections the PRD does permit keep passing, and a
// nested chat field is not mistaken for a top-level one.
func TestConfigReadRuleAllowsThePermittedKeys(t *testing.T) {
const permitted = `package archiemessaging
import "github.com/samcharles93/archie-core/internal/config"
func project(cfg config.Config) projection {
return projection{
telegram: cfg.Chat.Telegram,
email: cfg.Chat.Email,
gateway: cfg.Services.Get("gateway").Target,
workDir: cfg.WorkDir,
botUser: cfg.BotUser,
healthURL: cfg.Health.URL(),
}
}
`
if got := configReadOffenders([]byte(permitted)); len(got) != 0 {
t.Fatalf("configReadOffenders(permitted) = %v, want none", got)
}
}
+1 -2
View File
@@ -23,9 +23,8 @@ func run() int {
flag.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory")
flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory")
flag.StringVar(&options.Gateway.Target, "gateway-target", "", "archie-gateway gRPC address (defaults to [services.gateway].target, else 127.0.0.1:8585)")
flag.StringVar(&options.Gateway.Token, "gateway-token", "", "bearer token presented to archie-gateway")
flag.StringVar(&options.StateStore.Target, "state-store-target", "", "archie-state-store gRPC address (defaults to [services.state].target)")
flag.StringVar(&options.StateStore.Token, "state-store-token", "", "bearer token presented to archie-state-store")
flag.StringVar(&options.Listen, "listen", "", "MessagingService gRPC listen address (defaults to [services.messaging].listen)")
flag.DurationVar(&options.DependencyTimeout, "dependency-timeout", 0, "readiness probe timeout (default 5s)")
flag.DurationVar(&options.ShutdownTimeout, "shutdown-timeout", 0, "shutdown timeout (default 5s)")
flag.Parse()
-153
View File
@@ -1,153 +0,0 @@
package main
import (
"context"
"net"
"os"
"os/exec"
"path/filepath"
"runtime"
"strings"
"syscall"
"testing"
"time"
"google.golang.org/grpc"
controlpb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1"
"github.com/samcharles93/archie-core/internal/domain/messaging"
"github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc"
)
func repoRoot(t *testing.T) string {
t.Helper()
_, file, _, ok := runtime.Caller(0)
if !ok {
t.Fatal("runtime.Caller failed")
}
dir := filepath.Dir(file)
for {
if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {
return dir
}
parent := filepath.Dir(dir)
if parent == dir {
t.Fatal("could not find repo root")
}
dir = parent
}
}
func buildBinary(t *testing.T) string {
t.Helper()
bin := filepath.Join(t.TempDir(), "archie-messaging")
cmd := exec.CommandContext(t.Context(), "go", "build", "-o", bin, "./cmd/archie-messaging")
cmd.Dir = repoRoot(t)
if out, err := cmd.CombinedOutput(); err != nil {
t.Fatalf("go build archie-messaging: %v\n%s", err, string(out))
}
return bin
}
type fakeChatServer struct {
messaging.ChatContract
}
func (f *fakeChatServer) Snapshot(ctx context.Context) (messaging.ChatSnapshot, error) {
return messaging.ChatSnapshot{}, nil
}
func startTestGateway(t *testing.T) (target string, cleanup func()) {
t.Helper()
lis, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", "127.0.0.1:0")
if err != nil {
t.Fatalf("net.Listen: %v", err)
}
srv := grpc.NewServer()
gatewayrpc.RegisterServer(srv, &fakeChatServer{})
go func() {
_ = srv.Serve(lis)
}()
return lis.Addr().String(), func() {
srv.GracefulStop()
_ = lis.Close()
}
}
// fakeControlPlane serves the empty channel-settings resource the Messaging
// Service reads at startup. The database is authoritative for channel
// settings, so the process refuses to start without a State Store to read.
type fakeControlPlane struct {
controlpb.UnimplementedControlPlaneServiceServer
}
func (f *fakeControlPlane) Catalog(context.Context, *controlpb.CatalogRequest) (*controlpb.CatalogResponse, error) {
return &controlpb.CatalogResponse{}, nil
}
func (f *fakeControlPlane) Query(_ context.Context, request *controlpb.QueryRequest) (*controlpb.QueryResponse, error) {
return &controlpb.QueryResponse{Resource: &controlpb.Resource{Kind: request.GetKind(), Version: 1, ValueJson: []byte("{}")}}, nil
}
func startTestStateStore(t *testing.T) (target string, cleanup func()) {
t.Helper()
lis, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", "127.0.0.1:0")
if err != nil {
t.Fatalf("net.Listen: %v", err)
}
srv := grpc.NewServer()
controlpb.RegisterControlPlaneServiceServer(srv, &fakeControlPlane{})
go func() {
_ = srv.Serve(lis)
}()
return lis.Addr().String(), func() {
srv.GracefulStop()
_ = lis.Close()
}
}
func TestBinaryHelp(t *testing.T) {
bin := buildBinary(t)
cmd := exec.CommandContext(t.Context(), bin, "-help")
out, err := cmd.CombinedOutput()
// flag.ExitOnError or flag help returns exit 0 or 2 depending on standard library
if !strings.Contains(string(out), "gateway-target") {
t.Fatalf("help output missing gateway-target flag: %v\n%s", err, string(out))
}
}
func TestBinaryStartsAndShutsDownCleanly(t *testing.T) {
bin := buildBinary(t)
gatewayTarget, cleanup := startTestGateway(t)
defer cleanup()
stateStoreTarget, stopStateStore := startTestStateStore(t)
defer stopStateStore()
cmd := exec.CommandContext(t.Context(), bin, "-gateway-target", gatewayTarget, "-state-store-target", stateStoreTarget)
if err := cmd.Start(); err != nil {
t.Fatalf("cmd.Start: %v", err)
}
// Allow the process to start up.
time.Sleep(200 * time.Millisecond)
// Send SIGTERM to shut down gracefully.
if err := cmd.Process.Signal(syscall.SIGTERM); err != nil {
t.Fatalf("send SIGTERM: %v", err)
}
errCh := make(chan error, 1)
go func() {
errCh <- cmd.Wait()
}()
select {
case err := <-errCh:
if err != nil {
t.Fatalf("process exited with error on SIGTERM: %v", err)
}
case <-time.After(3 * time.Second):
_ = cmd.Process.Kill()
t.Fatal("process did not exit in time after SIGTERM")
}
}
-122
View File
@@ -1,122 +0,0 @@
// Command archie-playbooks is the standalone playbook tool for archie-core,
// shaped like gopls: one binary, multiple invocation modes. It validates
// playbook YAML binding files against the same schema the daemon loads at
// startup, so a pre-merge check can never disagree with runtime validation.
//
// 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.
//
// 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"
)
func main() {
os.Exit(run(os.Args[1:], os.Stderr))
}
func run(args []string, stderr io.Writer) int {
// Subcommand table from day one (gopls shape): each mode owns its flag
// 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,
"serve": runServe,
}
if len(args) > 0 && (args[0] == "-version" || args[0] == "--version") {
buildinfo.Print("archie-playbooks")
return 0
}
if len(args) == 0 {
fmt.Fprintln(stderr, "usage: archie-playbooks <command> [args]")
fmt.Fprintln(stderr, "commands:")
for name := range commands {
fmt.Fprintf(stderr, " %s\n", name)
}
return 2
}
cmd, ok := commands[args[0]]
if !ok {
fmt.Fprintf(stderr, "archie-playbooks: unknown command %q\n", args[0])
return 2
}
return cmd(args[1:], stderr)
}
// 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", "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 && *edaDir == "" {
fmt.Fprintln(stderr, "lint: at least one -dir or an -eda-dir is required")
flags.Usage()
return 2
}
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
func (m *multiFlag) String() string { return fmt.Sprint([]string(*m)) }
func (m *multiFlag) Set(v string) error {
*m = append(*m, v)
return nil
}
-88
View File
@@ -1,88 +0,0 @@
package main
import (
"bytes"
"os"
"path/filepath"
"strings"
"testing"
)
// TestRunUnknownCommandExits2: an unrecognised subcommand is a usage error.
func TestRunUnknownCommandExits2(t *testing.T) {
var stderr bytes.Buffer
if code := run([]string{"frobnicate"}, &stderr); code != 2 {
t.Fatalf("run(unknown) = %d, want 2", code)
}
if !strings.Contains(stderr.String(), "unknown command") {
t.Fatalf("stderr = %q, want unknown-command message", stderr.String())
}
}
// TestRunNoCommandExits2: no subcommand is a usage error with the command
// table printed (the gopls-shaped dispatch surface).
func TestRunNoCommandExits2(t *testing.T) {
var stderr bytes.Buffer
if code := run(nil, &stderr); code != 2 {
t.Fatalf("run(nil) = %d, want 2", code)
}
if !strings.Contains(stderr.String(), "lint") {
t.Fatalf("stderr = %q, want lint listed in usage", stderr.String())
}
}
// TestRunLintCleanExits0: lint over a valid directory exits 0.
func TestRunLintCleanExits0(t *testing.T) {
dir := t.TempDir()
writeFile(t, filepath.Join(dir, "routes.yaml"), "bug: tdd\n")
var stderr bytes.Buffer
if code := run([]string{"lint", "-dir", dir}, &stderr); code != 0 {
t.Fatalf("run(lint clean) = %d, want 0; stderr=%q", code, stderr.String())
}
}
// TestRunLintCollisionExits1: a cross-directory collision exits 1 and names
// the colliding key.
func TestRunLintCollisionExits1(t *testing.T) {
dirA := t.TempDir()
dirB := t.TempDir()
writeFile(t, filepath.Join(dirA, "a.yaml"), "security: security-review\n")
writeFile(t, filepath.Join(dirB, "b.yaml"), "security: other-security\n")
var stderr bytes.Buffer
if code := run([]string{"lint", "-dir", dirA, "-dir", dirB}, &stderr); code != 1 {
t.Fatalf("run(lint collision) = %d, want 1; stderr=%q", code, stderr.String())
}
if !strings.Contains(stderr.String(), "security") {
t.Fatalf("stderr = %q, want the colliding label named", stderr.String())
}
}
// TestRunLintNoDirsExits2: lint without any -dir is a usage error.
func TestRunLintNoDirsExits2(t *testing.T) {
var stderr bytes.Buffer
if code := run([]string{"lint"}, &stderr); code != 2 {
t.Fatalf("run(lint no dirs) = %d, want 2", code)
}
}
func writeFile(t *testing.T, path, content string) {
t.Helper()
if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
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())
}
}
-48
View File
@@ -1,48 +0,0 @@
// 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 reviewer and judge")
flag.StringVar(&opts.Fixtures, "findings", "", "directory of <problem id>.json findings to rescore; omit to review live")
flag.StringVar(&opts.ReviewModel, "review-model", "", "provider/model for the review role in live runs")
flag.StringVar(&opts.ClassifyModel, "classification-model", "", "provider/model for the classification role in live runs")
flag.StringVar(&opts.JudgeModel, "judge-model", "anthropic/claude-sonnet-4.6", "provider/model of the independent judge")
flag.StringVar(&opts.Out, "out", "bin/prbench-results", "directory for per-problem results and summary.json")
flag.StringVar(&opts.Resume, "resume", "", "reuse complete results from a previous run with the same models")
flag.StringVar(&problems, "problems", "", "comma-separated problem ids (default: all)")
flag.IntVar(&opts.Concurrency, "concurrency", 4, "problems judged at once")
flag.Parse()
opts.GitHubToken = os.Getenv("GH_TOKEN")
if opts.GitHubToken == "" {
opts.GitHubToken = os.Getenv("GITHUB_TOKEN")
}
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
}
+8 -7
View File
@@ -1,6 +1,5 @@
// 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.
// only process that owns the PostgreSQL stores behind it.
package main
import (
@@ -12,7 +11,7 @@ import (
"strings"
"syscall"
"github.com/samcharles93/archie-core/internal/app/archied"
"github.com/samcharles93/archie-core/internal/app/statestore"
"github.com/samcharles93/archie-core/internal/buildinfo"
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
)
@@ -24,25 +23,27 @@ func run() int {
// including no arguments at all, serves the State Store contract. An
// unrecognised word is refused rather than ignored, so a mistyped recovery
// command never leaves an operator watching a server start instead.
if args := os.Args[1:]; statestore.IsAccessResetArgs(args) {
return statestore.RunAccessReset(context.Background(), args[2:], os.Stderr)
}
if args := os.Args[1:]; len(args) > 0 && !strings.HasPrefix(args[0], "-") {
return runRecovery(args, os.Stdout, os.Stderr)
}
var options archied.StateStoreOptions
var options statestore.Options
showVersion := buildinfo.RegisterVersionFlag("archie-state-store")
flag.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory")
flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory")
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.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|import> -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> -h | access reset -h\n\n")
flag.PrintDefaults()
}
flag.Parse()
showVersion()
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
if err := archied.RunStateStore(ctx, options); err != nil {
if err := statestore.Run(ctx, options); err != nil {
fmt.Fprintln(os.Stderr, err)
return 1
}
-10
View File
@@ -1,10 +0,0 @@
package main
import (
"os"
"testing"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest"
)
func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) }
-627
View File
@@ -1,627 +0,0 @@
// Package main smoke-tests the standalone archie-state-store process by
// building the real binary, running it against a minimal config on the
// loopback interface, and driving it through the State Store gRPC contract
// exactly the way a consumer (archied, archie-gateway, archie-agent) does.
//
// This is the .4.7 end-to-end verification for
// docs/prds/state-store-contract.md (rev. 2c): it proves the process owns the
// 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 store. See §5 (binary layout), §6 (handoff),
// §7 (error semantics), §11 (remote adapter) and §12 step 7/8 (single owner).
package main
import (
"bufio"
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"net"
"net/http"
"os"
"os/exec"
"path/filepath"
"runtime"
"strings"
"sync"
"syscall"
"testing"
"time"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials/insecure"
"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"
)
// repoRoot walks up from the test's source directory to find the module root
// (where go.mod lives). The test runs in the package directory
// (cmd/archie-state-store), so the module root is above it; walking keeps the
// result correct regardless of the harness working directory.
func repoRoot(t *testing.T) string {
t.Helper()
_, file, _, ok := runtime.Caller(0)
if !ok {
t.Fatal("cannot determine test source path")
}
dir := filepath.Dir(file)
for {
if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {
return dir
}
parent := filepath.Dir(dir)
if parent == dir {
t.Fatal("go.mod not found above test source")
}
dir = parent
}
}
// buildBinary compiles ./cmd/archie-state-store into dir and returns the path.
// This is the real binary the smoke test exercises, not a test double -- the
// point of .4.7 is to verify the actual process.
func buildBinary(t *testing.T, dir string) string {
t.Helper()
bin := filepath.Join(dir, "archie-state-store")
cmd := exec.CommandContext(t.Context(), "go", "build", "-o", bin, "./cmd/archie-state-store")
cmd.Dir = repoRoot(t)
cmd.Env = os.Environ()
out, err := cmd.CombinedOutput()
if err != nil {
t.Fatalf("go build archie-state-store: %v\n%s", err, out)
}
if _, err := os.Stat(bin); err != nil {
t.Fatalf("built binary not found: %v", err)
}
return bin
}
// writeMinimalConfig writes a config.toml that passes configuration.Validate
// 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
// 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"
database_url = %q
[forge]
type = "github"
host = "https://github.example.com"
token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" }
[[repos]]
owner = "acme"
name = "widget"
`, url)
if err := os.WriteFile(cfg, []byte(content), 0o600); err != nil {
t.Fatalf("write config: %v", err)
}
return cfg
}
// writeConfigWithServiceListen is writeMinimalConfig plus the
// [services.state] block that lets a test supply the listen address through
// configuration instead of the -listen flag.
func writeConfigWithServiceListen(t *testing.T, dir string) string {
t.Helper()
cfg := writeMinimalConfig(t, dir)
f, err := os.OpenFile(cfg, os.O_APPEND|os.O_WRONLY, 0o600)
if err != nil {
t.Fatalf("open config to append: %v", err)
}
defer func() {
if err := f.Close(); err != nil {
t.Fatalf("close config: %v", err)
}
}()
if _, err := f.WriteString("\n[services.state]\nlisten = \"127.0.0.1:0\"\n"); err != nil {
t.Fatalf("append [services.state]: %v", err)
}
return cfg
}
// syncBuffer is a concurrency-safe buffer for a subprocess's stdout/stderr:
// the os/exec goroutine writes while the test goroutine reads (to parse the
// log and to report it on failure). A plain strings.Builder races under
// -race, so both paths take the mutex.
type syncBuffer struct {
mu sync.Mutex
b bytes.Buffer
}
func (s *syncBuffer) Write(p []byte) (int, error) {
s.mu.Lock()
defer s.mu.Unlock()
return s.b.Write(p)
}
func (s *syncBuffer) String() string {
s.mu.Lock()
defer s.mu.Unlock()
return s.b.String()
}
// stateStoreProcess wraps a running archie-state-store subprocess plus the
// addresses it bound. addr is the gRPC listen address; readyAddr is the
// readiness HTTP surface. It is stopped gracefully on cleanup by SIGTERM, the
// signal the systemd unit ("Restart=on-failure") and the daemon use to drain
// the server.
type stateStoreProcess struct {
cmd *exec.Cmd
addr string
readyAddr string
log *syncBuffer
}
// startStateStoreProcess starts bin with config, waiting for the gRPC listener
// to come up and the readiness surface to answer /healthz. It parses the
// binary's stderr log for the bound addresses because --listen 127.0.0.1:0
// lets the process choose ephemeral ports, and the real address (not the
// configured one) is what a consumer must dial.
func startStateStoreProcess(t *testing.T, bin, cfg string) *stateStoreProcess {
t.Helper()
return startStateStore(t, bin, cfg, "127.0.0.1:0", "")
}
// startStateStore is startStateStoreProcess with the listener topology and
// bearer token exposed: the token-protected, non-loopback listener is the
// topology every container-mode deployment profile uses
// (docs/prds/state-store-contract.md §9), where the server installs the
// credential interceptors on both the unary and the streaming surface.
func startStateStore(t *testing.T, bin, cfg, listen, token string) *stateStoreProcess {
t.Helper()
args := []string{"-config", cfg, "-ready-addr", "127.0.0.1:0"}
if listen != "" {
// An empty listen means "pass no -listen at all". A test uses that to
// prove the bound address came from [services.state].listen.
args = append(args, "-listen", listen)
}
if token != "" {
// An explicit -token wins over [services.state].target_token and the
// STATE_STORE_TOKEN secret, so the process authenticates callers with
// exactly this value.
args = append(args, "-token", token)
}
cmd := exec.CommandContext(t.Context(), bin, args...)
cmd.Env = append(os.Environ(), "ARCHIE_GITHUB_TOKEN=test-token")
var log syncBuffer
cmd.Stderr = &log
cmd.Stdout = &log
if err := cmd.Start(); err != nil {
t.Fatalf("start state store: %v", err)
}
p := &stateStoreProcess{cmd: cmd, log: &log}
t.Cleanup(func() { p.stop(t) })
// Recover the ephemeral ports from the JSON log lines the binary emits.
deadline := time.Now().Add(15 * time.Second)
for time.Now().Before(deadline) {
if p.parseAddrs() {
break
}
if cmd.ProcessState != nil {
t.Fatalf("state store exited early:\n%s", log.String())
}
time.Sleep(25 * time.Millisecond)
}
if p.addr == "" || p.readyAddr == "" {
t.Fatalf("did not recover bound addresses from log:\n%s", log.String())
}
// The readiness surface is the liveness signal the runbook uses; poll it
// until it answers (the gRPC listener may come up a tick ahead of it).
deadline = time.Now().Add(15 * time.Second)
req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, "http://"+p.readyAddr+"/healthz", nil)
if err != nil {
t.Fatalf("build readiness request: %v", err)
}
for time.Now().Before(deadline) {
if resp, err := http.DefaultClient.Do(req); err == nil {
_ = resp.Body.Close()
if resp.StatusCode == http.StatusOK {
return p
}
}
time.Sleep(25 * time.Millisecond)
}
t.Fatalf("readiness /healthz never became healthy:\n%s", log.String())
return nil
}
// parseAddrs scans the captured log for the bound gRPC and readiness
// addresses. The binary logs "archie-state-store running" with the gRPC addr
// and "state store readiness listening" with the HTTP addr.
func (p *stateStoreProcess) parseAddrs() bool {
if p.addr != "" && p.readyAddr != "" {
return true
}
scanner := bufio.NewScanner(strings.NewReader(p.log.String()))
for scanner.Scan() {
line := scanner.Text()
var rec map[string]any
if err := json.Unmarshal([]byte(line), &rec); err != nil {
continue
}
if msg, _ := rec["msg"].(string); msg == "archie-state-store running" {
if addr, ok := rec["addr"].(string); ok && addr != "" && p.addr == "" {
p.addr = addr
}
}
if msg, _ := rec["msg"].(string); msg == "state store readiness listening" {
if addr, ok := rec["addr"].(string); ok && addr != "" && p.readyAddr == "" {
p.readyAddr = strings.TrimPrefix(addr, "http://")
}
}
}
return p.addr != "" && p.readyAddr != ""
}
// stop drains the process with SIGTERM and waits for it to exit. This is the
// same graceful-stop path serveStateStore's signal handling implements.
func (p *stateStoreProcess) stop(t *testing.T) {
t.Helper()
if p.cmd.Process == nil {
return
}
_ = p.cmd.Process.Signal(syscall.SIGTERM)
done := make(chan struct{})
go func() { _ = p.cmd.Wait(); close(done) }()
select {
case <-done:
case <-time.After(10 * time.Second):
_ = p.cmd.Process.Kill()
<-done
}
}
// contract is the combined consumer surface a daemon/gateway/agent mixes: the
// 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 {
storecontract.TaskStore
storecontract.CaptureStore
}
// dial opens a gRPC connection to the state store process and wraps it in the
// remote contract adapter, exactly as the daemon/gateway/agent consumer does
// (internal/infrastructure/staterpc.Client).
func dial(t *testing.T, addr string) contract {
t.Helper()
conn, err := grpc.NewClient("passthrough:///"+addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
t.Fatalf("dial %s: %v", addr, err)
}
t.Cleanup(func() { _ = conn.Close() })
return staterpc.NewClient(conn)
}
// capture builds a CapturedEvent without pulling the whole store field set
// into every call site.
func capture(source, body string) storecontract.CapturedEvent {
return storecontract.CapturedEvent{Source: source, Body: body, Authenticated: true}
}
// TestStateStoreRealProcessSmoke exercises the actual archie-state-store
// binary end-to-end: the combined task/event/capture view through one consumer
// adapter, error-sentinel fidelity across the wire, the not-found-as-(nil,nil)
// convention, and single-owner SQLite (the binary owns the one archie.db file
// and the consumer dials gRPC without opening any store file).
//
// It also takes its listen address from [services.state].listen rather than
// -listen, so the startup path every deployment uses is covered by the process
// that exercises the most: before that key existed the address came from a flag
// default with no config key, so a host whose port was already taken could
// only be retargeted by passing -listen and
// hand-writing an overlay whose target matched -- and the failure read as a
// code fault, "address already in use" in the store and a gRPC handshake error
// in every client.
func TestStateStoreRealProcessSmoke(t *testing.T) {
if testing.Short() {
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
}
t.Parallel()
dir := t.TempDir()
bin := buildBinary(t, dir)
cfg := writeConfigWithServiceListen(t, dir)
st := startStateStore(t, bin, cfg, "", "")
if st.addr == "" {
t.Fatalf("no bound gRPC address in the log:\n%s", st.log.String())
}
if !strings.Contains(st.log.String(), `"listen":"127.0.0.1:0"`) {
t.Fatalf("the resolved listen was not the configured address:\n%s", st.log.String())
}
cl := dial(t, st.addr)
ctx := t.Context()
// Combined task/event/capture view: a task, an event on that task, and an
// unrelated capture written through one consumer, read back across all
// three surfaces in a single pass (the dashboard/observability read path).
task, err := cl.EnqueueChatTask(ctx, "acme", "widget", "verify state store", "body", "implement", "", nil)
if err != nil || task == nil {
t.Fatalf("EnqueueChatTask = %+v, %v", task, err)
}
if err := cl.Transition(ctx, task.ID, task.Status, "running", "smoke started"); err != nil {
t.Fatalf("Transition: %v", err)
}
if _, err := cl.InsertEvent(ctx, events.Event{Kind: "stage_finish", TaskID: task.ID, Attempt: 1, Data: map[string]any{"duration_ms": 12.0}}); err != nil {
t.Fatalf("InsertEvent: %v", err)
}
// R4's document is stored as an event, so the real process must round-trip
// it with its nested structure and its attempt key intact: the standalone
// State Store owns the only copy, and a lost field here is a Config tab
// that reads a run it cannot describe. The key is the daemon's own
// (internal/daemon/daemon.go writes "document"), asserted by name below.
if _, err := cl.InsertEvent(ctx, events.Event{
Kind: events.KindConfigCaptured, TaskID: task.ID, Attempt: 1,
Data: map[string]any{
"schema": events.ConfigCapturedSchema,
"document": map[string]any{"bot_user": "archie", "models": map[string]any{"implement": "anthropic/claude"}},
},
}); err != nil {
t.Fatalf("InsertEvent config_captured: %v", err)
}
if capID, err := cl.InsertCapture(ctx, capture("sentry", `{"id":1}`), 0, 0); err != nil || capID == "" {
t.Fatalf("InsertCapture = (%q, %v)", capID, err)
}
got, err := cl.TaskByID(ctx, task.ID)
if err != nil || got == nil || got.ID != task.ID || got.Status != "running" {
t.Fatalf("TaskByID after transition = %+v, %v", got, err)
}
evs, err := cl.TaskEvents(ctx, task.ID)
if err != nil || len(evs) != 2 || evs[0].Kind != "stage_finish" {
t.Fatalf("TaskEvents = %+v, %v", evs, err)
}
if evs[0].Attempt != 1 {
t.Errorf("TaskEvents attempt = %d, want 1 across the real process", evs[0].Attempt)
}
if evs[1].Kind != events.KindConfigCaptured || evs[1].Attempt != 1 || evs[1].Data["schema"] != events.ConfigCapturedSchema {
t.Errorf("config_captured event = %+v, want its kind, attempt and schema preserved", evs[1])
}
if _, renamed := evs[1].Data["config"]; renamed {
t.Error(`the document crossed under "config"; the producer writes it under "document"`)
}
if len(evs[1].Data) != 2 {
t.Errorf("config_captured data keys = %v, want exactly schema and document", evs[1].Data)
}
if doc, ok := evs[1].Data["document"].(map[string]any); !ok || doc["bot_user"] != "archie" {
t.Errorf("config_captured payload = %#v, want the decoded document under its own key", evs[1].Data)
}
if caps, err := cl.ListCaptures(ctx, 10); err != nil || len(caps) != 1 || caps[0].Source != "sentry" {
t.Fatalf("ListCaptures = %+v, %v", caps, err)
}
if counts, err := cl.StatusCounts(ctx); err != nil || counts["running"] != 1 {
t.Fatalf("StatusCounts = %+v, %v", counts, err)
}
t.Run("error_sentinel_fidelity", func(t *testing.T) {
// 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, storecontract.ErrStaleTransition) {
t.Fatalf("stale Transition = %v, want storecontract.ErrStaleTransition", err)
}
})
t.Run("not_found_is_not_error", func(t *testing.T) {
// Reading a missing task returns (nil, nil), never a NotFound gRPC
// error (§7's found=false-not-error convention).
missing, err := cl.TaskByID(ctx, task.ID+999999)
if err != nil || missing != nil {
t.Fatalf("TaskByID missing = (%+v, %v), want (nil, nil)", missing, err)
}
})
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)
}
}
})
}
// TestStateStoreRealProcessDeadline verifies the per-call deadline behaviour
// the state store contract requires (§6 StoreTimeout): a consumer context that
// is cancelled before the call completes must surface a deadline/cancel error
// rather than hang or silently succeed.
func TestStateStoreRealProcessDeadline(t *testing.T) {
if testing.Short() {
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
}
t.Parallel()
dir := t.TempDir()
bin := buildBinary(t, dir)
cfg := writeMinimalConfig(t, dir)
st := startStateStoreProcess(t, bin, cfg)
cl := dial(t, st.addr)
ctx, cancel := context.WithCancel(t.Context())
cancel()
_, err := cl.StatusCounts(ctx)
if err == nil {
t.Fatal("StatusCounts on a cancelled context returned nil; expected a deadline/cancel error")
}
if !errors.Is(err, context.Canceled) && !errors.Is(err, context.DeadlineExceeded) {
t.Fatalf("StatusCounts cancelled = %v, want context.Canceled or DeadlineExceeded", err)
}
}
// TestStateStoreRealProcessRestartRecovery starts the process, writes a task,
// 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.
func TestStateStoreRealProcessRestartRecovery(t *testing.T) {
if testing.Short() {
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
}
t.Parallel()
dir := t.TempDir()
bin := buildBinary(t, dir)
cfg := writeMinimalConfig(t, dir)
first := startStateStoreProcess(t, bin, cfg)
s1 := dial(t, first.addr)
task, err := s1.EnqueueChatTask(t.Context(), "acme", "widget", "survive restart", "body", "implement", "", nil)
if err != nil || task == nil {
t.Fatalf("first EnqueueChatTask = %+v, %v", task, err)
}
if _, err := s1.InsertEvent(t.Context(), events.Event{Kind: "run_started", TaskID: task.ID}); err != nil {
t.Fatalf("first InsertEvent: %v", err)
}
first.stop(t)
// Restart on the same config; the SQLite file persists on disk.
second := startStateStoreProcess(t, bin, cfg)
s2 := dial(t, second.addr)
got, err := s2.TaskByID(t.Context(), task.ID)
if err != nil || got == nil || got.Title != "survive restart" {
t.Fatalf("TaskByID after restart = %+v, %v", got, err)
}
if evs, err := s2.TaskEvents(t.Context(), task.ID); err != nil || len(evs) != 1 {
t.Fatalf("TaskEvents after restart = %+v, %v", evs, err)
}
// Stale-running work reopened on a fresh process is recovered by
// RecoverStale, which must return without error on the restarted store.
if _, err := s2.RecoverStale(t.Context()); err != nil {
t.Fatalf("RecoverStale after restart: %v", err)
}
}
// TestStateStoreRealProcessTokenProtectedCaptureStream is the capture-batch
// regression against the real binary: the token-protected, non-loopback
// listener topology a container-mode deployment uses, read through the
// production client wiring (staterpc.Dial) the daemon and the dashboard both
// use. The reads the batch needs are server-streaming RPCs, whose metadata
// the unary-only client interceptor never saw -- so before the fix this
// failed with PermissionDenied, and no unary fallback existed to take. 20 x
// 256 KiB is 5 MiB, past gRPC's 4 MiB unary cap, so the batch also proves the
// streams still carry it.
func TestStateStoreRealProcessTokenProtectedCaptureStream(t *testing.T) {
if testing.Short() {
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
}
t.Parallel()
const token = "operator-secret-token"
dir := t.TempDir()
bin := buildBinary(t, dir)
cfg := writeMinimalConfig(t, dir)
st := startStateStore(t, bin, cfg, "0.0.0.0:0", token)
// The listener advertises the wildcard address it bound; a consumer dials
// the host address it can reach, which is this host's loopback.
_, port, err := net.SplitHostPort(st.addr)
if err != nil {
t.Fatalf("parse bound address %q: %v", st.addr, err)
}
cl, cleanup, err := staterpc.Dial("127.0.0.1:"+port, token)
if err != nil {
t.Fatalf("dial token-protected state store: %v", err)
}
t.Cleanup(cleanup)
ctx := t.Context()
body := strings.Repeat("x", 256<<10)
for range 20 {
if _, err := cl.InsertCapture(ctx, capture("large", body), 0, 0); err != nil {
t.Fatalf("InsertCapture: %v", err)
}
}
captures, err := cl.ListCaptures(ctx, 20)
if err != nil {
t.Fatalf("ListCaptures over a token-protected listener: %v", err)
}
if len(captures) != 20 {
t.Fatalf("got %d captures, want 20", len(captures))
}
for _, c := range captures {
if c.Body != body {
t.Fatal("capture body truncated")
}
}
}
// TestStateStoreRealProcessRemoteSurfaces exercises the capture/mapping/
// binding surfaces the standalone process fronts (the daemon/webui surfaces
// swapped to the adapter in .4.4/.4.5), proving one process serves the full
// combined contract a consumer mixes.
func TestStateStoreRealProcessRemoteSurfaces(t *testing.T) {
if testing.Short() {
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
}
t.Parallel()
dir := t.TempDir()
bin := buildBinary(t, dir)
cfg := writeMinimalConfig(t, dir)
st := startStateStoreProcess(t, bin, cfg)
conn, err := grpc.NewClient("passthrough:///"+st.addr, grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
t.Fatalf("dial: %v", err)
}
t.Cleanup(func() { _ = conn.Close() })
cl := staterpc.NewClient(conn)
ctx := t.Context()
mappingID, err := cl.InsertMapping(ctx, mapping.Mapping{Name: "m1", Fields: []mapping.Field{{Name: "a", Path: "a", Type: mapping.TypeString}}})
if err != nil || mappingID == "" {
t.Fatalf("InsertMapping = (%q, %v)", mappingID, err)
}
if got, err := cl.GetMapping(ctx, mappingID); err != nil || got == nil || got.Name != "m1" {
t.Fatalf("GetMapping = %+v, %v", got, err)
}
bindingID, err := cl.InsertBinding(ctx, binding.Binding{
Name: "b1", Matcher: binding.Matcher{Source: "sentry"}, MappingID: mappingID,
Workflow: "implement",
})
if err != nil || bindingID == "" {
t.Fatalf("InsertBinding = (%q, %v)", bindingID, err)
}
// A binding starts as draft and must be edited (draft -> pending_approval)
// then approved (pending_approval -> armed) before it is armed for a
// source. Drive the state machine so ArmedBindingsForSource returns it.
if err := cl.UpdateBinding(ctx, binding.Binding{
ID: bindingID, Name: "b1", Matcher: binding.Matcher{Source: "sentry"},
MappingID: mappingID, Workflow: "implement", Owner: "acme", Repo: "widget",
}); err != nil {
t.Fatalf("UpdateBinding: %v", err)
}
if err := cl.ApproveBinding(ctx, bindingID); err != nil {
t.Fatalf("ApproveBinding: %v", err)
}
if armed, err := cl.ArmedBindingsForSource(ctx, "sentry"); err != nil || len(armed) != 1 || armed[0].ID != bindingID {
t.Fatalf("ArmedBindingsForSource = %+v, %v", armed, err)
}
// 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, storecontract.ErrMappingNotFound) {
t.Fatalf("UpdateMapping missing = %v, want ErrMappingNotFound", err)
}
}
+5 -5
View File
@@ -7,14 +7,14 @@ import (
"fmt"
"io"
"github.com/samcharles93/archie-core/internal/app/archied"
"github.com/samcharles93/archie-core/internal/app/statestore"
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
)
// recoveryUsage is the whole flag surface of the offline recovery commands.
// They are subcommands of this binary rather than a recovery binary of their
// own: offline database maintenance belongs to the process that owns the file
// and its path layout (docs/architecture/organisation.md#process-boundaries).
// and its path layout.
const recoveryUsage = `usage: archie-state-store <command> [flags]
With no command, archie-state-store serves the State Store gRPC contract.
@@ -51,9 +51,9 @@ func runRecovery(args []string, stdout, stderr io.Writer) int {
return 2
}
command := args[0]
options := archied.StateStoreRecoveryOptions{Operation: command}
options := statestore.RecoveryOptions{Operation: command}
switch command {
case archied.RecoveryBackup, archied.RecoveryRestore, archied.RecoveryValidate, archied.RecoveryRollback:
case statestore.RecoveryBackup, statestore.RecoveryRestore, statestore.RecoveryValidate, statestore.RecoveryRollback:
default:
fmt.Fprintf(stderr, "archie-state-store: unknown command %q\n\n", command)
fmt.Fprint(stderr, recoveryUsage)
@@ -84,7 +84,7 @@ func runRecovery(args []string, stdout, stderr io.Writer) int {
return 2
}
summary, err := archied.RunStateStoreRecovery(context.Background(), options)
summary, err := statestore.RunRecovery(context.Background(), options)
if err != nil {
fmt.Fprintf(stderr, "archie-state-store %s: %v\n", command, err)
return 1
@@ -1,43 +0,0 @@
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)
}
})
}
}
-486
View File
@@ -1,486 +0,0 @@
// 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 -- rather than through the internal helpers, so the flag surface
// and the exit codes are part of what is verified.
package main
import (
"bytes"
"encoding/json"
"fmt"
"os"
"path/filepath"
"strconv"
"strings"
"testing"
"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"
)
// runRecoveryCmd runs one subcommand the way main does and returns its exit
// code with both streams captured.
func runRecoveryCmd(t *testing.T, args ...string) (int, string, string) {
t.Helper()
var stdout, stderr bytes.Buffer
code := runRecovery(args, &stdout, &stderr)
return code, stdout.String(), stderr.String()
}
// 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()
url := pgtest.URL(t)
configPath := writeConfigFor(t, t.TempDir(), url)
return configPath, pgstore.On(pgstore.PoolAt(t, url))
}
// 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", "", nil); err != nil {
t.Fatalf("seed task %q: %v", title, err)
}
}
// 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()
if _, err := st.Pool.Exec(t.Context(), statement); err != nil {
t.Fatal(err)
}
}
func TestRecoveryValidateAcceptsAHealthyStore(t *testing.T) {
configPath, st := recoveryFixture(t)
seedTask(t, st, "healthy")
seedStoreResources(t, st, configPath)
code, stdout, stderr := runRecoveryCmd(t, "validate", "-config", configPath)
if code != 0 {
t.Fatalf("validate exited %d: %s", code, stderr)
}
if !strings.Contains(stdout, "schema version") {
t.Errorf("validate must report the schema version it verified; stdout = %q", stdout)
}
// The count is part of what the operator reads, and a check that reports
// "0 stored resources" for a store full of them is worse than no check.
if count := storedResourceCount(t, stdout); count == 0 {
t.Errorf("validate reported no stored resources for a seeded store; stdout = %q", stdout)
}
}
// validate's verdict is only useful if it is the daemon's verdict. Boot refuses
// on configuration.Validate over the file config with every stored resource
// layered onto it (internal/app/archied/control_plane.go), not on the write
// path's own per-resource decode, and the two disagree: the write path accepts
// a scheduling policy boot rejects.
func TestRecoveryValidateRunsTheGateBootRuns(t *testing.T) {
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", "-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).
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 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 subcommands advertise -h as the way to read their flags, and the serve
// path in the same binary exits 0 for the same request, so a script probing the
// recovery surface must not read a requested help as a failure.
func TestRecoveryHelpExitsZero(t *testing.T) {
commands := []string{archied.RecoveryBackup, archied.RecoveryRestore, archied.RecoveryValidate, archied.RecoveryRollback}
for _, command := range commands {
code, _, stderr := runRecoveryCmd(t, command, "-h")
if code != 0 {
t.Errorf("%s -h exited %d, want 0; stderr = %q", command, code, stderr)
}
}
}
// validate diagnoses a deployment; it is not the deployment. Resolving the boot
// config must not create, append to, or rotate the daemon's log file or the
// directory it lives in: a line stamped component="daemon" in archied's log is
// indistinguishable from the daemon having written it.
func TestRecoveryValidateLeavesTheDaemonLogAlone(t *testing.T) {
dir := t.TempDir()
configPath, logFile := writeConfigWithLogFile(t, dir)
code, _, stderr := runRecoveryCmd(t, "validate", "-config", configPath)
if code != 0 {
t.Fatalf("validate exited %d: %s", code, stderr)
}
if _, err := os.Stat(logFile); !os.IsNotExist(err) {
t.Fatalf("validate touched the daemon's log file %s (stat err = %v)", logFile, err)
}
if _, err := os.Stat(filepath.Dir(logFile)); !os.IsNotExist(err) {
t.Errorf("validate created the log directory %s (stat err = %v)", filepath.Dir(logFile), err)
}
}
// validate's verdict is the daemon's verdict only if it reads the configuration
// the daemon reads, and with no -config it reads whatever the one shared
// helper resolves. The resolution rule itself is pinned where it lives
// (internal/infrastructure/configuration); what only this test can pin is that
// the command takes its default from that helper rather than deriving it.
//
// A relative XDG_CONFIG_HOME is the case that separates the two: the command
// has to resolve ${XDG_CONFIG_HOME}/archie/config.toml relative to its working
// directory, and a second derivation through os.UserConfigDir rejects a
// relative value outright, leaving the command with no config to answer about.
func TestRecoveryDefaultConfigResolvesWhereTheDaemonReads(t *testing.T) {
// The second layout is the teeth: the command has to read the config at the
// resolved path, not merely find some config somewhere under the config home.
// A resolution that drifts finds nothing and validate has no verdict.
tests := []struct {
name string
configDir string // relative to $XDG_CONFIG_HOME
wantOK bool
}{
{name: "$XDG_CONFIG_HOME/archie/config.toml", configDir: "archie", wantOK: true},
{name: "a config elsewhere in the config home is not the default", configDir: "wrong-place"},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
root := t.TempDir()
t.Chdir(root)
t.Setenv("XDG_CONFIG_HOME", "xdg")
configDir := filepath.Join(root, "xdg", tc.configDir)
if err := os.MkdirAll(configDir, 0o700); err != nil {
t.Fatalf("create %s: %v", configDir, err)
}
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)
}
return
}
if code != 0 {
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 database the resolved config names", stdout)
}
})
}
}
// 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) {
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)
}
}
// rollback is the one operation that closes the documented gap: with the State
// Store stopped, it replays the value an earlier revision recorded through the
// ordinary replace, so no rollback RPC is needed and the rollback itself is
// audited as one more revision.
func TestRecoveryRollbackReplaysTheRevisionThroughReplace(t *testing.T) {
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", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind)
if code != 0 {
t.Fatalf("rollback exited %d: %s", code, stderr)
}
if !strings.Contains(stdout, controlplane.ModelRoleAssignmentsKind) {
t.Errorf("rollback must name the resource it replayed; stdout = %q", stdout)
}
resource, err := st.Resource(t.Context(), storecontract.DefaultOrgID, controlplane.ModelRoleAssignmentsKind)
if err != nil {
t.Fatal(err)
}
if string(resource.Value) != `{"implement":"anthropic/claude"}` {
t.Errorf("resource value = %s, want the first revision's value", resource.Value)
}
if resource.Version != 3 {
t.Errorf("resource version = %d, want a new revision (3) rather than a rewrite of the old one", resource.Version)
}
history, err := st.ResourceHistory(t.Context(), storecontract.DefaultOrgID, controlplane.ModelRoleAssignmentsKind, 0)
if err != nil {
t.Fatal(err)
}
if len(history) != 3 {
t.Fatalf("history has %d revisions, want the rollback recorded as the third", len(history))
}
if history[0].Source != archied.OfflineRollbackSource {
t.Errorf("newest revision source = %q, want %q so the rollback is auditable", history[0].Source, archied.OfflineRollbackSource)
}
}
// 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) {
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", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind, "-revision", "1")
if code != 0 {
t.Fatalf("rollback exited %d: %s", code, stderr)
}
resource, err := st.Resource(t.Context(), storecontract.DefaultOrgID, controlplane.ModelRoleAssignmentsKind)
if err != nil {
t.Fatal(err)
}
if string(resource.Value) != `{"implement":"anthropic/claude"}` {
t.Errorf("resource value = %s, want the value recorded at revision 1", resource.Value)
}
}
func TestRecoveryRollbackRefusesWhatItCannotReplay(t *testing.T) {
newStore := func(t *testing.T, revisions int) (string, *pgstore.TaskDB) {
t.Helper()
configPath, st := recoveryFixture(t)
for i := range revisions {
value := `{"implement":"anthropic/claude"}`
if i > 0 {
value = `{"implement":"openai/gpt"}`
}
seedResource(t, st, controlplane.ModelRoleAssignmentsKind, value, "seed")
}
return configPath, st
}
t.Run("unknown_kind", func(t *testing.T) {
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")
}
if !strings.Contains(stderr, "not-a-resource") {
t.Errorf("refusal must name the kind; stderr = %q", stderr)
}
})
t.Run("no_earlier_revision", func(t *testing.T) {
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")
}
if !strings.Contains(stderr, "no earlier revision") {
t.Errorf("refusal must say there is nothing to roll back to; stderr = %q", stderr)
}
})
t.Run("current_revision", func(t *testing.T) {
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")
}
if !strings.Contains(stderr, "is the current version") {
t.Errorf("refusal must say the revision is already the current value; stderr = %q", stderr)
}
})
t.Run("live_state_store", func(t *testing.T) {
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, "stop the State Store") {
t.Errorf("refusal must say to stop the State Store; stderr = %q", stderr)
}
})
}
// A positional argument that is not a subcommand used to be ignored, leaving
// 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", "-out", "x"}, &stdout, &stderr)
if code == 0 {
t.Fatal("an unknown subcommand exited 0")
}
if !strings.Contains(stderr.String(), "backp") {
t.Errorf("refusal must name the unknown subcommand; stderr = %q", stderr.String())
}
}
// writeConfigWithLogFile is writeMinimalConfig plus the daemon's durable log
// destination, which only the daemon may bring into existence.
func writeConfigWithLogFile(t *testing.T, dir string) (string, string) {
t.Helper()
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 {
t.Fatalf("open config to append: %v", err)
}
defer func() {
if err := f.Close(); err != nil {
t.Fatalf("close config: %v", err)
}
}()
if _, err := fmt.Fprintf(f, "\n[log]\nfile = %q\n", logFile); err != nil {
t.Fatalf("append [log]: %v", err)
}
return configPath, logFile
}
// seedStoreResources seeds the store the way the State Store seeds it at boot,
// from the same config file the operator hands validate: the command's verdict
// is about the pair, and a store whose settings never matched the config is a
// state boot does not recognise either.
//
// The seeding builds its control-plane server from the shared provider set
// (internal/infrastructure/workflowsteps), which is what every composition root
// registers -- including openStateStoreControlPlane, the root helper the
// recovery path uses. This test cannot call that unexported helper, so it
// 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 *pgstore.TaskDB, configPath string) {
t.Helper()
doc, err := configuration.New(nil).Resolve(configPath, "")
if err != nil {
t.Fatalf("resolve %s: %v", configPath, err)
}
steps, err := workflowsteps.NewManager()
if err != nil {
t.Fatalf("register workflow step vocabulary: %v", err)
}
server, err := controlplane.NewServer(st, steps)
if err != nil {
t.Fatalf("build control plane server: %v", err)
}
_, skipped, err := server.ImportConfig(t.Context(), doc.Config)
if err != nil {
t.Fatalf("seed store resources: %v", err)
}
if len(skipped) > 0 {
// This helper stands in for the State Store's own seeding, which seeds
// every kind it can and leaves the rest absent. A skipped kind here
// would mean the fixture store is missing a resource it claims to hold,
// and the verdict under test would be about a different store.
t.Fatalf("seed store resources: %d kind(s) refused: %+v", len(skipped), skipped)
}
}
// storedResourceCount reads the count validate reports out of its summary line.
func storedResourceCount(t *testing.T, stdout string) int {
t.Helper()
before, found := strings.CutSuffix(stdout, " stored resources validate\n")
if !found {
t.Fatalf("no resource count in %q", stdout)
}
fields := strings.Fields(before)
count, err := strconv.Atoi(fields[len(fields)-1])
if err != nil {
t.Fatalf("resource count in %q: %v", stdout, err)
}
return count
}
// seedResource writes one revision of a control-plane resource through the
// store, the way the control plane's replace does. The request ID is derived
// 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 *pgstore.TaskDB, kind, value, label string) {
t.Helper()
current, err := st.Resource(t.Context(), storecontract.DefaultOrgID, kind)
expected := int64(0)
if err == nil {
expected = current.Version
}
var document any
if err := json.Unmarshal([]byte(value), &document); err != nil {
t.Fatal(err)
}
encoded, err := json.Marshal(document)
if err != nil {
t.Fatal(err)
}
if _, err := st.PutResource(t.Context(), storecontract.ResourceWrite{
OrgID: storecontract.DefaultOrgID,
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)
}
}
+27 -139
View File
@@ -1,153 +1,41 @@
// 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 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
// are atomic, so a single reference to a type living beside a runtime relinks
// the runtime, and the severance holds only while something re-measures it.
// This file enforces the dashboard's process boundary
// (docs/prds/external-agent-harness.md, "Session contract", Transport): the
// dashboard must not link the container or daemon internals, because only the
// daemon owns containers. Go imports are atomic, so a single reference
// relinks a runtime, and the boundary holds only while something re-measures
// it. archie-core-h3s0 names this check; it was purged with the test suite and
// is restored here.
package main
import (
"context"
"os/exec"
"strings"
"testing"
"time"
)
const modulePath = "github.com/samcharles93/archie-core/"
// bannedCategory is one class of runtime the UI process must not link. The
// names are the PRD's wording; the prefixes are how that class appears in
// this module.
type bannedCategory struct {
name string
prefixes []string
}
var deletionGate = []bannedCategory{
{"SQL/store implementation", []string{
"modernc.org/sqlite",
"github.com/jackc/pgx",
modulePath + "internal/infrastructure/postgres",
}},
{"daemon runtime", []string{
modulePath + "internal/daemon",
modulePath + "internal/app/archied",
modulePath + "internal/container",
modulePath + "internal/worktree",
modulePath + "internal/worktreerpc",
}},
{"workflow engine", []string{
modulePath + "internal/domain/workflow",
modulePath + "internal/taskrun",
modulePath + "internal/agentexec",
}},
{"forge client", []string{
modulePath + "internal/forge",
modulePath + "internal/forgerpc",
}},
{"channel runtime", []string{
modulePath + "internal/channels",
}},
{"model runtime", []string{
modulePath + "internal/gateway",
modulePath + "internal/infrastructure/modelcatalog",
modulePath + "internal/domain/embedding",
modulePath + "internal/infrastructure/embedding",
}},
{"secret runtime", []string{
modulePath + "internal/secret",
}},
{"agent tooling", []string{
modulePath + "internal/tools",
modulePath + "internal/skill",
modulePath + "internal/skillscript",
modulePath + "internal/yaegiutil",
modulePath + "internal/plugin",
}},
{"memory and curator runtime", []string{
modulePath + "internal/domain/memory",
modulePath + "internal/infrastructure/memory",
modulePath + "internal/domain/curator",
modulePath + "internal/infrastructure/sessioncurator",
modulePath + "internal/infrastructure/skillcurator",
}},
{"broker transport", []string{
modulePath + "internal/eventbus",
modulePath + "internal/infrastructure/eventbus",
modulePath + "internal/natsrpc",
}},
}
// bannedExact is banned as a package rather than as a subtree. Nothing may
// reach the database through the UI process, but database/sql/driver and its
// support package arrive from github.com/google/uuid's Valuer/Scanner methods
// and bring no driver with them.
var bannedExact = map[string]string{
"database/sql": "SQL/store implementation",
}
// gateExceptions are packages under a banned prefix that carry only contract,
// vocabulary or view types. The severance moved the UI's references here so
// the parent runtime would stop linking, which makes them the intended end
// state rather than a tolerated leak.
//
// Each one must stay linked. An exception the UI no longer needs is a hole in
// the fence, so this list is checked in both directions.
var gateExceptions = []string{
modulePath + "internal/channels/status",
modulePath + "internal/domain/workflow/task",
}
// under reports whether importPath is prefix or a package below it.
func under(importPath, prefix string) bool {
return importPath == prefix || strings.HasPrefix(importPath, prefix+"/")
}
func TestUIProcessLinksNoDaemonRuntime(t *testing.T) {
listed, err := exec.CommandContext(t.Context(), "go", "list", "-deps", ".").CombinedOutput()
func TestDashboardDoesNotLinkContainerRuntime(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
out, err := exec.CommandContext(ctx, "go", "list", "-deps", ".").Output()
if err != nil {
t.Fatalf("go list -deps .: %v\n%s", err, listed)
t.Fatalf("go list -deps .: %v", err)
}
linkedExceptions := make(map[string]bool, len(gateExceptions))
for importPath := range strings.FieldsSeq(string(listed)) {
if excepted(importPath, linkedExceptions) {
continue
}
if category, banned := bannedExact[importPath]; banned {
reportLink(t, importPath, category)
}
for _, category := range deletionGate {
for _, prefix := range category.prefixes {
if under(importPath, prefix) {
reportLink(t, importPath, category.name)
}
linked := map[string]bool{}
for line := range strings.SplitSeq(strings.TrimSpace(string(out)), "\n") {
linked[line] = true
}
for _, pkg := range []string{
"github.com/samcharles93/archie-core/internal/container",
"github.com/samcharles93/archie-core/internal/app/archied",
"github.com/samcharles93/archie-core/internal/agentexec",
} {
t.Run(pkg, func(t *testing.T) {
if linked[pkg] {
t.Errorf("cmd/archie-ui links %s: only the daemon owns containers", pkg)
}
}
}
for _, exception := range gateExceptions {
if !linkedExceptions[exception] {
t.Errorf("%s is excepted from the deletion gate but is no longer linked; drop the exception instead of leaving its prefix open", exception)
}
})
}
}
func reportLink(t *testing.T, importPath, category string) {
t.Helper()
t.Errorf("archie-ui links %s (%s); the UI process reaches that capability over a contract, never in-process (docs/prds/ui-service-boundary.md, deletion gate)", importPath, category)
}
// excepted reports whether importPath is allowed past the gate, recording
// which exception admitted it so a stale one is reported.
func excepted(importPath string, linked map[string]bool) bool {
for _, exception := range gateExceptions {
if under(importPath, exception) {
linked[exception] = true
return true
}
}
return false
}
+1 -6
View File
@@ -3,8 +3,6 @@
// contracts. It is the .5.2 companion to archie-gateway and
// archie-state-store: a thin main that parses process inputs and hands them
// to archieui.Run.
//
// See docs/prds/ui-service-boundary.md for the ratified boundary.
package main
import (
@@ -29,17 +27,14 @@ func run() int {
flag.StringVar(&options.Config, "config", configuration.DefaultConfigPath(), "configuration file or directory (only [services.*] targets and [web] are read)")
flag.StringVar(&options.Overlay, "config-overlay", "", "configuration overlay file or directory")
flag.StringVar(&options.Listen, "listen", "", "dashboard HTTP listen address (defaults to [web].listen, else 127.0.0.1:8484)")
flag.StringVar(&options.Token, "token", "", "dashboard token; required for a non-loopback listener")
flag.StringVar(&options.TokenFile, "token-file", "", "file holding the dashboard token, minted on first use")
flag.StringVar(&options.OidcIssuer, "oidc-issuer", "", "identity provider issuer URL; requests must then carry a token it signed")
flag.StringVar(&options.OidcAudience, "oidc-audience", "", "audience (resource identifier) this dashboard accepts tokens for; required with -oidc-issuer")
flag.StringVar(&options.OidcClientID, "oidc-client-id", "", "provider client id for browser sign-in; omitted means no sign-in flow")
flag.StringVar(&options.OidcClientSecretEnv, "oidc-client-secret-env", "", "name of the environment variable holding the sign-in client secret")
flag.StringVar(&options.OidcRedirectURL, "oidc-redirect-url", "", "callback URL registered at the provider (path must be /oauth2/callback)")
flag.StringVar(&options.Gateway.Target, "gateway-target", "", "archie-gateway gRPC address (defaults to [services.gateway].target)")
flag.StringVar(&options.Gateway.Token, "gateway-token", "", "bearer token presented to archie-gateway")
flag.StringVar(&options.State.Target, "state-target", "", "archie-state-store gRPC address (defaults to [services.state].target)")
flag.StringVar(&options.State.Token, "state-token", "", "bearer token presented to archie-state-store")
flag.StringVar(&options.Harness.Target, "harness-target", "", "archied harness session gRPC address (defaults to [services.harness].target); empty leaves the setup terminal unwired")
flag.DurationVar(&options.DependencyTimeout, "dependency-timeout", 0, "per-dependency readiness probe timeout (default 5s)")
flag.DurationVar(&options.EventPollInterval, "event-poll-interval", 0, "how often the activity feed polls the State Store for new events (default 1s)")
// BoolFunc rather than BoolVar so an unset flag stays distinguishable
-960
View File
@@ -1,960 +0,0 @@
// Package main's smoke test runs the real archie-ui binary against a State
// Store and a Gateway reached over loopback gRPC, and drives it through HTTP
// the way an operator's browser does.
//
// The in-process suite (internal/app/archieui) proves the composition; this
// proves the process: flags and configuration file, listener bind, dashboard
// token, SPA assets, streamed chat, an operator task action crossing to the
// Gateway, the degradations the PRD ratified, dependency loss while running,
// and a clean SIGTERM. See docs/prds/ui-service-boundary.md, migration
// sequence step 6.
package main
import (
"bufio"
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"log/slog"
"net"
"net/http"
"os"
"os/exec"
"path/filepath"
"runtime"
"strings"
"sync"
"syscall"
"testing"
"time"
"google.golang.org/grpc"
"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/gatewayrpc"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore"
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
"github.com/samcharles93/archie-core/internal/taskstate"
"github.com/samcharles93/archie-core/internal/webui"
)
const dashboardToken = "smoke-token"
// fakeGateway stands in for the archie-gateway process. The dashboard only
// needs the Gateway to answer, stream, and accept an operator action, so the
// rest satisfy messaging.ChatContract without pretending to do more.
type fakeGateway struct {
mu sync.Mutex
actions []string
}
func (f *fakeGateway) Snapshot(context.Context) (messaging.ChatSnapshot, error) {
return messaging.ChatSnapshot{
Sessions: []messaging.SessionContext{{
SessionID: "s1",
Source: messaging.SessionSource{Platform: "web", ChannelID: "dash"},
}},
Models: []string{"test/model"},
ActiveModel: "test/model",
ActivePersonas: map[string]string{},
CancellationAvailable: true,
}, nil
}
func (f *fakeGateway) GetSession(context.Context, string) (messaging.SessionContext, bool, error) {
return messaging.SessionContext{}, false, nil
}
func (f *fakeGateway) RecentMessages(context.Context, string, int) ([]messaging.Message, error) {
return nil, nil
}
func (f *fakeGateway) RecentTurns(context.Context, string, int) ([]messaging.TurnRecord, error) {
return nil, nil
}
func (f *fakeGateway) Route(context.Context, messaging.Inbound) (messaging.ChatReply, error) {
return messaging.ChatReply{Text: "routed", SessionID: "s1"}, nil
}
// Stream emits the contract's documented order: started, a delta, then done.
//
// A turn that used a tool emits its tool event between the delta and the done,
// which is where the Gateway's own stream reports completed tool activity.
// Whether the dashboard renders it is the operator's setting, carried to this
// process only by the published configuration projection (GitHub #821).
func (f *fakeGateway) Stream(ctx context.Context, in messaging.Inbound) (<-chan messaging.ChatEvent, error) {
events := make(chan messaging.ChatEvent, 4)
go func() {
defer close(events)
turn := []messaging.ChatEvent{
{Kind: "started", SessionID: "s1"},
{Kind: "delta", Text: "hello " + in.Message.Text, SessionID: "s1"},
{Kind: "done", SessionID: "s1"},
}
if in.Message.Text == toolCallPrompt {
turn = []messaging.ChatEvent{
{Kind: "started", SessionID: "s1"},
{Kind: "tool", SessionID: "s1", Tool: messaging.ToolCallEvent{
ID: "call-1", Name: "read_file", Parameters: `{"path":"main.go"}`,
Output: "package main",
}},
{Kind: "delta", Text: "read it", SessionID: "s1"},
{Kind: "done", SessionID: "s1"},
}
}
for _, event := range turn {
select {
case events <- event:
case <-ctx.Done():
return
}
}
}()
return events, nil
}
// toolCallPrompt is the message this suite sends when it wants the fake
// Gateway to report a completed tool call in the turn.
const toolCallPrompt = "read main.go"
func (f *fakeGateway) Cancel(context.Context, string) (messaging.ChatCancellation, error) {
return messaging.ChatCancellation{Cancelled: true}, nil
}
func (f *fakeGateway) SetPersona(context.Context, string, string) (bool, error) { return false, nil }
func (f *fakeGateway) ApplyTaskAction(context.Context, string, int64, taskstate.Action, taskactions.ActionPayload) (messaging.TaskActionResult, error) {
return messaging.TaskActionResult{}, nil
}
func (f *fakeGateway) ApplyOperatorTaskAction(_ context.Context, actor taskactions.Actor, id int64, action taskstate.Action, _ taskactions.ActionPayload) (messaging.TaskActionResult, error) {
f.mu.Lock()
defer f.mu.Unlock()
f.actions = append(f.actions, fmt.Sprintf("%d:%s", id, action))
return messaging.TaskActionResult{TaskID: id, Action: string(action)}, nil
}
func (f *fakeGateway) applied() []string {
f.mu.Lock()
defer f.mu.Unlock()
return append([]string(nil), f.actions...)
}
// repoRoot walks up from this test's source directory to the module root, so
// the build works regardless of the harness working directory.
func repoRoot(t *testing.T) string {
t.Helper()
_, file, _, ok := runtime.Caller(0)
if !ok {
t.Fatal("cannot determine test source path")
}
dir := filepath.Dir(file)
for {
if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {
return dir
}
parent := filepath.Dir(dir)
if parent == dir {
t.Fatal("go.mod not found above test source")
}
dir = parent
}
}
func buildUIBinary(t *testing.T, dir string) string {
t.Helper()
bin := filepath.Join(dir, "archie-ui")
cmd := exec.CommandContext(t.Context(), "go", "build", "-o", bin, "./cmd/archie-ui")
cmd.Dir = repoRoot(t)
cmd.Env = os.Environ()
if out, err := cmd.CombinedOutput(); err != nil {
t.Fatalf("go build archie-ui: %v\n%s", err, out)
}
return bin
}
// syncBuffer is a concurrency-safe sink for the subprocess's stderr: the
// os/exec goroutine writes while the test reads it to recover the bound
// address and to report it on failure.
type syncBuffer struct {
mu sync.Mutex
b bytes.Buffer
}
func (s *syncBuffer) Write(p []byte) (int, error) {
s.mu.Lock()
defer s.mu.Unlock()
return s.b.Write(p)
}
func (s *syncBuffer) String() string {
s.mu.Lock()
defer s.mu.Unlock()
return s.b.String()
}
// serveGRPC runs register against a fresh loopback listener, returning the
// dial target and a stop func so a test can take the dependency away.
func serveGRPC(t *testing.T, register func(grpc.ServiceRegistrar)) (target string, stop func()) {
t.Helper()
listener, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", "127.0.0.1:0")
if err != nil {
t.Fatalf("listen: %v", err)
}
server := grpc.NewServer()
register(server)
go func() { _ = server.Serve(listener) }()
t.Cleanup(server.Stop)
return listener.Addr().String(), server.Stop
}
// writeUIConfig writes the config.toml an operator would keep: the service
// endpoints the UI dials live in it, so the process is started without
// -gateway-target or -state-target and has to read them itself. The rest is
// what configuration validation requires of any archie config file.
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"
[forge]
type = "github"
host = "https://github.example.com"
token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" }
[[repos]]
owner = "acme"
name = "widget"
[services.state]
target = %q
[services.gateway]
target = %q
`, stateTarget, gatewayTarget)
if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
t.Fatalf("write ui config: %v", err)
}
return path
}
// uiProcess is a running archie-ui, plus the address it actually bound.
type uiProcess struct {
cmd *exec.Cmd
addr string
log *syncBuffer
}
func startUIProcess(t *testing.T, bin, cfg string) *uiProcess {
t.Helper()
// The process outlives t.Context() deliberately: that context is
// cancelled just before cleanups run, which would SIGKILL archie-ui out
// from under the graceful-shutdown check in stop. Cancelling this one is
// registered first, so it runs last and only backstops a process that
// ignored SIGTERM.
ctx, cancel := context.WithCancel(context.WithoutCancel(t.Context()))
t.Cleanup(cancel)
cmd := exec.CommandContext(
ctx, bin,
"-config", cfg,
"-listen", "127.0.0.1:0",
"-token", dashboardToken,
)
cmd.Env = append(os.Environ(), "ARCHIE_GITHUB_TOKEN=test-token")
var log syncBuffer
cmd.Stderr = &log
cmd.Stdout = &log
if err := cmd.Start(); err != nil {
t.Fatalf("start archie-ui: %v", err)
}
p := &uiProcess{cmd: cmd, log: &log}
t.Cleanup(func() { p.stop(t) })
// -listen 127.0.0.1:0 means the kernel picks the port, so the bound
// address comes back out of the process's own startup log.
deadline := time.Now().Add(20 * time.Second)
for time.Now().Before(deadline) && p.addr == "" {
if cmd.ProcessState != nil {
t.Fatalf("archie-ui exited early:\n%s", log.String())
}
p.parseAddr()
if p.addr == "" {
time.Sleep(25 * time.Millisecond)
}
}
if p.addr == "" {
t.Fatalf("did not recover the bound address from the log:\n%s", log.String())
}
waitHealthy(t, p)
return p
}
func (p *uiProcess) parseAddr() {
scanner := bufio.NewScanner(strings.NewReader(p.log.String()))
for scanner.Scan() {
var record map[string]any
if err := json.Unmarshal(scanner.Bytes(), &record); err != nil {
continue
}
if msg, _ := record["msg"].(string); msg != "archie-ui running" {
continue
}
if addr, ok := record["addr"].(string); ok && addr != "" {
p.addr = addr
return
}
}
}
func waitHealthy(t *testing.T, p *uiProcess) {
t.Helper()
deadline := time.Now().Add(20 * time.Second)
for time.Now().Before(deadline) {
req, err := http.NewRequestWithContext(t.Context(), http.MethodGet, "http://"+p.addr+"/healthz", nil)
if err != nil {
t.Fatalf("build liveness request: %v", err)
}
if resp, err := http.DefaultClient.Do(req); err == nil {
_ = resp.Body.Close()
if resp.StatusCode == http.StatusOK {
return
}
}
time.Sleep(25 * time.Millisecond)
}
t.Fatalf("/healthz never answered:\n%s", p.log.String())
}
// stop ends the process the way a service manager does and reports a
// non-graceful exit, which is how a shutdown-ordering regression surfaces.
func (p *uiProcess) stop(t *testing.T) {
t.Helper()
if p.cmd.Process == nil || p.cmd.ProcessState != nil {
return
}
if err := p.cmd.Process.Signal(syscall.SIGTERM); err != nil {
t.Errorf("SIGTERM archie-ui: %v", err)
return
}
done := make(chan error, 1)
go func() { done <- p.cmd.Wait() }()
select {
case err := <-done:
if err != nil {
t.Errorf("archie-ui exited %v after SIGTERM, want a clean shutdown:\n%s", err, p.log.String())
}
case <-time.After(20 * time.Second):
_ = p.cmd.Process.Kill()
t.Errorf("archie-ui did not exit within 20s of SIGTERM:\n%s", p.log.String())
}
}
// reply is one dashboard response, already read and closed. The assertions
// want the status and the bytes rather than a live body, and handing back a
// closed value keeps the close where the read is.
type reply struct {
status int
header http.Header
body []byte
}
func (r reply) cookies() []*http.Cookie {
return (&http.Response{Header: r.header}).Cookies()
}
// dashboard is a browser-shaped client for the running process.
type dashboard struct {
t *testing.T
base string
client *http.Client
}
// noRedirect returns a dashboard that reports a redirect rather than
// following it, so an exchange can be inspected instead of chased. Following
// it here would land on the clean URL without the cookie jar a browser has.
func (d dashboard) noRedirect() dashboard {
d.client = &http.Client{CheckRedirect: func(*http.Request, []*http.Request) error {
return http.ErrUseLastResponse
}}
return d
}
func (d dashboard) do(req *http.Request) reply {
d.t.Helper()
client := d.client
if client == nil {
client = http.DefaultClient
}
resp, err := client.Do(req)
if err != nil {
d.t.Fatalf("%s %s: %v", req.Method, req.URL.Path, err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
d.t.Fatalf("read %s: %v", req.URL.Path, err)
}
return reply{status: resp.StatusCode, header: resp.Header, body: body}
}
func (d dashboard) request(method, path, body string, authorized bool) *http.Request {
d.t.Helper()
var reader io.Reader = http.NoBody
if body != "" {
reader = strings.NewReader(body)
}
req, err := http.NewRequestWithContext(d.t.Context(), method, d.base+path, reader)
if err != nil {
d.t.Fatalf("build %s %s: %v", method, path, err)
}
if authorized {
req.Header.Set("Authorization", "Bearer "+dashboardToken)
}
if body != "" {
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Archie-CSRF", "1")
}
return req
}
func (d dashboard) get(path string) reply {
d.t.Helper()
return d.do(d.request(http.MethodGet, path, "", true))
}
// chatFrame is one `data: {...}` frame of the chat stream, decoded into the
// fields this suite reads. The UI process only ever receives these over HTTP,
// so asserting on them is asserting on what the browser is handed.
type chatFrame struct {
Type string `json:"type"`
Text string `json:"text"`
Tool string `json:"tool"`
}
// streamChat runs one chat turn over the real HTTP stream and returns every
// frame up to and including the terminating done.
func streamChat(t *testing.T, d dashboard, prompt string) []chatFrame {
t.Helper()
body, err := json.Marshal(map[string]string{"text": prompt, "channel_id": "dash"})
if err != nil {
t.Fatalf("encode the chat turn: %v", err)
}
resp, err := http.DefaultClient.Do(d.request(http.MethodPost, "/api/chat/stream", string(body), true))
if err != nil {
t.Fatalf("POST /api/chat/stream: %v", err)
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
t.Fatalf("POST /api/chat/stream = %d, want 200", resp.StatusCode)
}
var frames []chatFrame
scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
payload, ok := strings.CutPrefix(scanner.Text(), "data: ")
if !ok {
continue
}
var frame chatFrame
if err := json.Unmarshal([]byte(payload), &frame); err != nil {
t.Fatalf("decode stream frame %q: %v", payload, err)
}
frames = append(frames, frame)
if frame.Type == "done" {
break
}
}
if err := scanner.Err(); err != nil {
t.Fatalf("read the chat stream: %v", err)
}
return frames
}
// seedStore fills a real task database and publishes the configuration
// projection, so everything the dashboard renders arrives over the wire from
// a store this process never opens.
//
// The document is rendered by webui.BuildConfigView -- the same function the
// daemon calls -- from a config.Config rather than hand-written as a
// ConfigView. A suite that hand-writes the document cannot catch a producer
// 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) *pgstore.TaskDB {
t.Helper()
st := pgstore.Open(t)
t.Cleanup(func() { _ = st.Close() })
if _, err := st.EnqueueIssue(t.Context(), "acme", "widget", 7, "smoke task", "body", "", ""); err != nil {
t.Fatalf("seed task: %v", err)
}
tasks, err := st.Tasks(t.Context(), 10)
if err != nil || len(tasks) != 1 {
t.Fatalf("seeded tasks = %d (%v), want 1", len(tasks), err)
}
seeded := tasks[0]
seeded.PRNumber = 34
if err := st.Update(t.Context(), &seeded); err != nil {
t.Fatalf("record PR number: %v", err)
}
publishConfig(t, st, daemonConfig(true))
return st
}
// daemonConfig is the configuration the daemon would hold for this smoke run.
// showToolCalls is the setting the chat page's expansion is gated on.
func daemonConfig(showToolCalls bool) config.Config {
return config.Config{
BotUser: "archie-bot",
Forge: config.Forge{Type: "github", Host: "https://github.example.com"},
Repos: []config.Repo{{Owner: "acme", Name: "widget", Base: "main"}},
Chat: config.ChatConfig{
ShowToolCalls: showToolCalls,
Operator: "Sam",
WebhookAddr: "127.0.0.1:9099",
},
}
}
// publishConfig renders cfg the way the daemon's configuration owner does and
// 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 *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(), storecontract.ConfigSnapshot{
Schema: webui.ConfigViewSchema, Document: document,
}); err != nil {
t.Fatalf("publish config snapshot: %v", err)
}
}
// TestUIProcessLinksMultiIdentityTaskRowsToTheirOwningForge drives the real
// binary against a State Store holding a multi-identity deployment's
// projection. Task rows in such a deployment used to render no link at all:
// the projection carried the default identity's forge alone, so the renderer
// withheld rather than pointing every row at the wrong forge
// (archie-core-pv6t). With per-identity forges published, each row is
// attributed to the identity that owns it, by identity name first and repo
// ownership second.
//
// Its own store and process: it publishes a different projection than the
// single-identity smoke test, and republishing over a shared one would rewire
// that test's page underneath it.
func TestUIProcessLinksMultiIdentityTaskRowsToTheirOwningForge(t *testing.T) {
dir := t.TempDir()
st := pgstore.Open(t)
t.Cleanup(func() { _ = st.Close() })
// One task carrying its identity (name resolves it), one without an
// identity but on a repo only the Gitea identity owns (ownership
// resolves it), and one on a repo both identities claim (ambiguous, so
// it falls back to the default forge).
for _, seed := range []struct {
owner, repo, identity string
number int
}{
{owner: "acme", repo: "widget", identity: "gitea-bot", number: 7},
{owner: "beta", repo: "svc", number: 8},
{owner: "acme", repo: "shared", number: 9},
} {
if _, err := st.EnqueueIssue(t.Context(), seed.owner, seed.repo, seed.number, "seeded", "body", "", seed.identity); err != nil {
t.Fatalf("seed %s/%s: %v", seed.owner, seed.repo, err)
}
}
published, err := json.Marshal(webui.ConfigView{
Identity: webui.IdentityView{BotUser: "archie-bot", ForgeType: "github", ForgeHost: "https://github.example.com"},
MultiIdentity: true,
Identities: []webui.ForgeIdentityView{
{
Name: "gitea-bot", ForgeType: "gitea", ForgeHost: "https://gitea.example.com",
Repos: []webui.ForgeRepoView{{Owner: "acme", Name: "widget"}, {Owner: "acme", Name: "shared"}},
},
{
Name: "github-bot", ForgeType: "github", ForgeHost: "https://github.example.com",
Repos: []webui.ForgeRepoView{{Owner: "beta", Name: "svc"}, {Owner: "acme", Name: "shared"}},
},
},
})
if err != nil {
t.Fatal(err)
}
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 := pgstore.EDA(t, nil)
staterpc.RegisterServer(r, staterpc.Deps{
Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st,
Log: slog.New(slog.DiscardHandler),
})
})
defer stopState()
gatewayTarget, stopGateway := serveGRPC(t, func(r grpc.ServiceRegistrar) {
gatewayrpc.RegisterServer(r, &fakeGateway{})
})
defer stopGateway()
ui := startUIProcess(t, buildUIBinary(t, dir), writeUIConfig(t, dir, stateTarget, gatewayTarget))
d := dashboard{t: t, base: "http://" + ui.addr}
got := d.get("/api/tasks")
if got.status != http.StatusOK {
t.Fatalf("GET /api/tasks = %d (%s), want 200", got.status, got.body)
}
var rows []struct {
Owner string `json:"owner"`
Repo string `json:"repo"`
IssueNumber int `json:"issue_number"`
RepoURL string `json:"repo_url"`
IssueURL string `json:"issue_url"`
}
if err := json.Unmarshal(got.body, &rows); err != nil {
t.Fatalf("decode task rows: %v (%s)", err, got.body)
}
if len(rows) != 3 {
t.Fatalf("task rows = %d, want the 3 seeded behind the State Store (%s)", len(rows), got.body)
}
want := map[string]string{
"acme/widget#7": "https://gitea.example.com/acme/widget/issues/7",
"beta/svc#8": "https://github.example.com/beta/svc/issues/8",
"acme/shared#9": "https://github.example.com/acme/shared/issues/9",
}
for _, row := range rows {
key := fmt.Sprintf("%s/%s#%d", row.Owner, row.Repo, row.IssueNumber)
expected, ok := want[key]
if !ok {
t.Errorf("unexpected row %q (%s)", key, got.body)
continue
}
if row.RepoURL == "" || row.IssueURL != expected {
t.Errorf("row %s links = %q, %q; want %q", key, row.RepoURL, row.IssueURL, expected)
}
}
}
func TestUIProcessServesTheDashboardAgainstLiveDependencies(t *testing.T) {
dir := t.TempDir()
st := seedStore(t, dir)
gateway := &fakeGateway{}
stateTarget, stopState := serveGRPC(t, func(r grpc.ServiceRegistrar) {
eda := pgstore.EDA(t, nil)
staterpc.RegisterServer(r, staterpc.Deps{
Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st,
Log: slog.New(slog.DiscardHandler),
})
})
gatewayTarget, _ := serveGRPC(t, func(r grpc.ServiceRegistrar) {
gatewayrpc.RegisterServer(r, gateway)
})
ui := startUIProcess(t, buildUIBinary(t, dir), writeUIConfig(t, dir, stateTarget, gatewayTarget))
d := dashboard{t: t, base: "http://" + ui.addr}
t.Run("liveness stays unauthenticated", func(t *testing.T) {
for _, path := range []string{"/healthz", "/health"} {
if got := d.do(d.request(http.MethodGet, path, "", false)); got.status != http.StatusOK {
t.Errorf("GET %s = %d without a token, want 200: probes must not need the dashboard token", path, got.status)
}
}
})
t.Run("an unauthenticated API request is refused", func(t *testing.T) {
if got := d.do(d.request(http.MethodGet, "/api/tasks", "", false)); got.status != http.StatusUnauthorized {
t.Errorf("GET /api/tasks = %d without a token, want 401", got.status)
}
wrong := d.request(http.MethodGet, "/api/tasks", "", false)
wrong.Header.Set("Authorization", "Bearer not-the-token")
if got := d.do(wrong); got.status != http.StatusUnauthorized {
t.Errorf("GET /api/tasks = %d with a wrong token, want 401", got.status)
}
})
t.Run("the token in the URL is exchanged for a cookie", func(t *testing.T) {
got := d.noRedirect().do(d.request(http.MethodGet, "/?t="+dashboardToken, "", false))
if got.status != http.StatusSeeOther {
t.Fatalf("GET /?t=<token> = %d, want 303 onto the clean URL", got.status)
}
var carried bool
for _, cookie := range got.cookies() {
if cookie.Value == dashboardToken && cookie.HttpOnly {
carried = true
}
}
if !carried {
t.Errorf("no HttpOnly cookie carried the token; it would stay in browser history (%v)", got.cookies())
}
})
t.Run("task rows carry forge links from the published projection", func(t *testing.T) {
got := d.get("/api/tasks")
if got.status != http.StatusOK {
t.Fatalf("GET /api/tasks = %d (%s), want 200", got.status, got.body)
}
var rows []struct {
ID int64 `json:"id"`
RepoURL string `json:"repo_url"`
IssueURL string `json:"issue_url"`
PRURL string `json:"pr_url"`
}
if err := json.Unmarshal(got.body, &rows); err != nil {
t.Fatalf("decode task rows: %v (%s)", err, got.body)
}
if len(rows) != 1 {
t.Fatalf("task rows = %d, want the 1 seeded behind the State Store (%s)", len(rows), got.body)
}
const repoURL = "https://github.example.com/acme/widget"
if rows[0].RepoURL != repoURL || rows[0].IssueURL != repoURL+"/issues/7" || rows[0].PRURL != repoURL+"/pull/34" {
t.Errorf("forge links = %q, %q, %q; want them built from the daemon's published projection, since this process holds no configuration of its own",
rows[0].RepoURL, rows[0].IssueURL, rows[0].PRURL)
}
})
t.Run("the SPA and its assets are served", func(t *testing.T) {
index := d.get("/")
if index.status != http.StatusOK || !bytes.Contains(bytes.ToLower(index.body), []byte("<!doctype html")) {
t.Errorf("GET / = %d serving %d bytes; want the embedded index.html", index.status, len(index.body))
}
for path, wantType := range map[string]string{
"/assets/index.js": "javascript",
"/assets/index.css": "css",
} {
asset := d.get(path)
if asset.status != http.StatusOK {
t.Errorf("GET %s = %d, want the embedded asset", path, asset.status)
continue
}
if contentType := asset.header.Get("Content-Type"); !strings.Contains(contentType, wantType) {
t.Errorf("GET %s Content-Type = %q, want %s", path, contentType, wantType)
}
if len(asset.body) == 0 {
t.Errorf("GET %s served an empty body", path)
}
}
})
t.Run("chat streams over the Gateway contract", func(t *testing.T) {
req := d.request(http.MethodPost, "/api/chat/stream", `{"text":"there","channel_id":"dash"}`, true)
resp, err := http.DefaultClient.Do(req)
if err != nil {
t.Fatalf("POST /api/chat/stream: %v", err)
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
t.Fatalf("POST /api/chat/stream = %d, want 200", resp.StatusCode)
}
if contentType := resp.Header.Get("Content-Type"); !strings.Contains(contentType, "text/event-stream") {
t.Fatalf("stream Content-Type = %q, want text/event-stream", contentType)
}
var kinds []string
var text string
scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
payload, ok := strings.CutPrefix(scanner.Text(), "data: ")
if !ok {
continue
}
var frame struct {
Type string `json:"type"`
Text string `json:"text"`
}
if err := json.Unmarshal([]byte(payload), &frame); err != nil {
t.Fatalf("decode stream frame %q: %v", payload, err)
}
kinds = append(kinds, frame.Type)
if frame.Type == "delta" {
text += frame.Text
}
if frame.Type == "done" {
break
}
}
if strings.Join(kinds, ",") != "started,delta,done" {
t.Errorf("stream frames = %v, want started,delta,done in order", kinds)
}
if text != "hello there" {
t.Errorf("streamed text = %q, want the Gateway's reply relayed verbatim", text)
}
})
t.Run("the daemon's show_tool_calls setting decides whether tool calls reach the chat page", func(t *testing.T) {
// The chat page expands a completed tool call only when the frame
// arrives, and this process has no [chat] section of its own: the
// setting reaches it through the published projection alone. A turn
// streamed with the setting off must carry no tool frame, and one
// streamed with it on must carry the tool the Gateway reported
// (GitHub #821).
//
// Each case republishes before streaming, the way a config reload
// does; the default is restored afterwards so a later subtest does
// not inherit whichever case ran last.
tests := []struct {
name string
showTools bool
wantFrame bool
}{
{name: "off", showTools: false, wantFrame: false},
{name: "on", showTools: true, wantFrame: true},
}
for _, tc := range tests {
t.Run(tc.name, func(t *testing.T) {
publishConfig(t, st, daemonConfig(tc.showTools))
frames := streamChat(t, d, toolCallPrompt)
var sawTool bool
for _, frame := range frames {
if frame.Tool == "read_file" {
sawTool = true
}
if frame.Type == "done" {
break
}
}
if sawTool != tc.wantFrame {
t.Errorf("show_tool_calls=%v produced tool frame = %v, want %v; frames = %+v",
tc.showTools, sawTool, tc.wantFrame, frames)
}
})
}
publishConfig(t, st, daemonConfig(true))
})
t.Run("an operator task action crosses to the Gateway", func(t *testing.T) {
listed := d.get("/api/tasks")
var rows []struct {
ID int64 `json:"id"`
}
if err := json.Unmarshal(listed.body, &rows); err != nil || len(rows) != 1 {
t.Fatalf("decode task rows: %v (%s)", err, listed.body)
}
path := fmt.Sprintf("/api/tasks/%d/action", rows[0].ID)
action := string(taskstate.ActionCancel)
if got := d.do(d.request(http.MethodPost, path, `{"action":"`+action+`"}`, true)); got.status != http.StatusOK {
t.Fatalf("POST %s = %d (%s), want 200", path, got.status, got.body)
}
want := fmt.Sprintf("%d:%s", rows[0].ID, action)
if applied := gateway.applied(); len(applied) != 1 || applied[0] != want {
t.Errorf("Gateway saw %v, want exactly [%s]: the UI must not mutate task state itself", applied, want)
}
// The same action without the CSRF header is refused, so a
// cross-site form post cannot drive the daemon.
noCSRF := d.request(http.MethodPost, path, "", true)
noCSRF.Body = io.NopCloser(strings.NewReader(`{"action":"` + action + `"}`))
noCSRF.Header.Set("Content-Type", "application/json")
if got := d.do(noCSRF); got.status != http.StatusForbidden {
t.Errorf("POST %s without the CSRF header = %d, want 403", path, got.status)
}
})
t.Run("capture intake is served without the dashboard token", func(t *testing.T) {
accepted := d.do(d.request(http.MethodPost, "/webhooks/capture/demo", "", false))
if accepted.status != http.StatusAccepted {
t.Fatalf("POST /webhooks/capture/demo = %d (%s), want 202: this process is the only listener serving intake after the cutover", accepted.status, accepted.body)
}
listed := d.get("/api/captures")
if listed.status != http.StatusOK || !strings.Contains(string(listed.body), `"enabled":true`) {
t.Errorf("GET /api/captures = %d (%s), want the capture list over the State Store", listed.status, listed.body)
}
})
t.Run("routes with no owner degrade explicitly", func(t *testing.T) {
// The daemon's log feed is host-local and has no contract, so the
// page reports itself off rather than erroring
// (docs/prds/ui-service-boundary.md, route family table).
logs := d.get("/api/logs")
if logs.status != http.StatusOK || !strings.Contains(string(logs.body), `"disabled":true`) {
t.Errorf("GET /api/logs = %d (%s), want an explicit disabled report", logs.status, logs.body)
}
if version := d.get("/api/version"); version.status != http.StatusNotImplemented {
t.Errorf("GET /api/version = %d, want 501: host-local update reporting stays with the daemon", version.status)
}
// Configuration renders from the published snapshot, and this
// process is not a second writer.
rendered := d.get("/api/config")
if rendered.status != http.StatusOK {
t.Fatalf("GET /api/config = %d (%s), want 200", rendered.status, rendered.body)
}
var view webui.ConfigView
if err := json.Unmarshal(rendered.body, &view); err != nil {
t.Fatalf("decode config view: %v (%s)", err, rendered.body)
}
if view.Identity.BotUser != "archie-bot" {
t.Errorf("config view = %s, want the published projection rendered read-only", rendered.body)
}
if got := d.do(d.request(http.MethodPatch, "/api/config", `{}`, true)); got.status != http.StatusMethodNotAllowed {
t.Errorf("PATCH /api/config = %d, want 405: configuration is read here and written through the control plane", got.status)
}
// The setup checklist reads the same projection. It reported
// nothing here while it needed a live config.Holder this process
// never receives (archie-core-ml30).
setup := d.get("/api/setup")
if setup.status != http.StatusOK {
t.Fatalf("GET /api/setup = %d (%s), want 200", setup.status, setup.body)
}
var checklist struct {
Steps []struct {
Title string `json:"title"`
Done bool `json:"done"`
} `json:"steps"`
Operator string `json:"operator"`
}
if err := json.Unmarshal(setup.body, &checklist); err != nil {
t.Fatalf("decode setup checklist: %v (%s)", err, setup.body)
}
if len(checklist.Steps) == 0 {
t.Errorf("setup checklist is empty; the published projection carries what it reads (%s)", setup.body)
}
if checklist.Operator != "Sam" {
t.Errorf("setup operator = %q, want the published name", checklist.Operator)
}
for _, step := range checklist.Steps {
if step.Title == "Connect a repository" && !step.Done {
t.Errorf("checklist says no repository is connected; the projection publishes one (%s)", setup.body)
}
}
})
// Last: taking the State Store away is not reversible for this process.
t.Run("losing a dependency degrades readiness without failing liveness", func(t *testing.T) {
healthy := d.get("/health/detailed")
if healthy.status != http.StatusOK {
t.Fatalf("GET /health/detailed = %d (%s), want 200", healthy.status, healthy.body)
}
var report health.Report
if err := json.Unmarshal(healthy.body, &report); err != nil {
t.Fatalf("decode readiness: %v (%s)", err, healthy.body)
}
if report.Status != health.StatusOK {
t.Fatalf("readiness = %s with both dependencies up, want ok (%s)", report.Status, healthy.body)
}
stopState()
degraded := d.get("/health/detailed")
if err := json.Unmarshal(degraded.body, &report); err != nil {
t.Fatalf("decode readiness after outage: %v (%s)", err, degraded.body)
}
if report.Status == health.StatusOK {
t.Errorf("readiness stayed ok with the State Store stopped (%s)", degraded.body)
}
if live := d.do(d.request(http.MethodGet, "/healthz", "", false)); live.status != http.StatusOK {
t.Errorf("GET /healthz = %d during a dependency outage, want 200: liveness must not imply dependency readiness", live.status)
}
})
}
-10
View File
@@ -1,10 +0,0 @@
package main
import (
"os"
"testing"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest"
)
func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) }
+13 -5
View File
@@ -2,10 +2,11 @@
package main
import (
"context"
"os"
"github.com/samcharles93/archie-core/internal/app/archied"
"github.com/samcharles93/archie-core/internal/app/archieplaybooks"
"github.com/samcharles93/archie-core/internal/app/prbench"
)
func main() {
@@ -16,10 +17,17 @@ func main() {
if archied.IsSetupArgs(args) {
os.Exit(archied.RunSetup(args[1:], os.Stdin, os.Stdout, os.Stderr))
}
// The access recovery command runs before the daemon's flags are parsed:
// it is a State Store host operation, not a daemon run.
if archied.IsAccessResetArgs(args) {
os.Exit(archied.RunAccessReset(context.Background(), args[2:], os.Stderr))
if len(args) > 0 && args[0] == "update" {
os.Exit(archied.RunUpdate(args[1:], os.Stdout, os.Stderr))
}
if len(args) > 0 && args[0] == "status" {
os.Exit(archied.RunStatus(args[1:], os.Stdout, os.Stderr))
}
if len(args) > 0 && args[0] == "prbench" {
os.Exit(prbench.Main(args[1:], os.Stdout, os.Stderr))
}
if len(args) > 0 && args[0] == "playbooks" {
os.Exit(archieplaybooks.Run(args[1:], os.Stderr))
}
os.Exit(archied.Run())
}
+50 -103
View File
@@ -3,14 +3,9 @@
#
# Secrets are NOT stored here: each one is a {engine, key}
# reference resolved through a secrets engine at startup.
# The built-in "env" engine reads key as an environment variable name;
# "bws" (Bitwarden Secrets Manager) is compiled in. Custom engines are
# Yaegi plugins loaded from this directory -- reference implementations
# for sops, vault/openbao and age ship in examples/secret-engines/ and
# each needs its CLI on PATH plus engine-specific env (sops: SOPS_FILE;
# vault: VAULT_ADDR, VAULT_TOKEN, optional VAULT_SECRET_PATH;
# age: AGE_FILE, AGE_IDENTITY).
# secret_engine_dir = "~/.config/archie/secret-engines"
# The built-in "env" engine reads key as an environment variable name.
# Every other engine (bws, sops, vault, age) is an extension installed from
# the archipelago marketplace and enabled through the control plane.
# work_dir = "~/.local/share/archie/work" # default
# state_dir = "~/.local/share/archie" # default; embedded NATS store, task logs, disk probe
@@ -22,12 +17,6 @@
# 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
# module_dir = "~/.local/share/archie/modules" # EDA playbook Module action kinds (log.go etc.); unset means no modules loaded
# workflow_routing_file = "~/.local/share/archie/workflow-routing.yaml" # kind->workflow rebinding (bug/feature/bootstrap)
# workflow_labels_file = "~/.local/share/archie/workflow-labels.yaml" # arbitrary forge label -> workflow (EDA playbook slice 2)
# playbook_dirs = ["~/.local/share/archie/workflows"] # list of dirs of *.yaml binding files, merged with the two above (slice 3); a key bound twice across sources is a load failure
# eda_playbook_dir = "~/.local/share/archie/eda-playbooks" # rich EDA playbook documents (one trigger; either a CEL-gated workflow action or a list of module actions); a matching workflow playbook decides the task's workflow ahead of the three binding sources above; distinct from playbook_dirs
poll_interval = "60s"
label = "archie"
@@ -43,6 +32,8 @@ diff_cap_lines = 400
# max_retries = 3
[forge]
# The name of an installed, enabled forge package (archipelago: forge/github, forge/gitea), or "none".
# Install and enable it from the Extensions page, then restart archied.
type = "github"
host = "https://github.com"
token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" }
@@ -69,10 +60,10 @@ token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" }
# intake per identity is a pending migration, not a setting.
# [[identities]] runs more than one bot identity from a single daemon, each
# with its own forge/dispatch/models/providers/budgets/notify -- see
# docs/architecture/identity.md for the full design and constraints (e.g.
# intake settings are rejected per identity, and [forge].intake =
# "webhook"/"both" is rejected alongside [[identities]]). Minimal shape:
# with its own forge account and repository membership. Runtime settings
# are shared and edited through the control plane. Intake
# settings are rejected per identity, and [forge].intake = "webhook"/"both"
# is rejected alongside [[identities]]. Minimal shape:
# [[identities]]
# name = "personal" # required; namespaces logs/events/NATS subjects
# bot_user = "your-bot" # required
@@ -89,21 +80,6 @@ trigger = "assignee"
# setting this to "off" disables the pickup reactions.
ack_reaction = "eyes"
# dispatch.labels maps each task lifecycle state to the label
# Archie applies on the issue.
# You can rename labels to match your project's conventions,
# or comment one out to skip that transition.
# The labels are the *source of truth* for the dispatch loop: Archie
# scans for issues bearing queued, then moves them through working →
# waiting → pr → parked (→ dead when max_retries is exhausted).
[dispatch.labels]
queued = "archie:queued"
working = "archie:working"
waiting = "archie:waiting"
pr = "archie:pr"
parked = "archie:parked"
# dead = "archie:dead" # state label for a task that exhausted max_retries
[models] # role -> ai-sdk runtime ref (used by agent workflows)
triage = "openai/gpt-5.4"
planner = "openai/gpt-5.4"
@@ -121,10 +97,9 @@ builder = "openai/gpt-5.4"
# voice note as its media placeholder -- the turn still runs.
# transcription = "openai/whisper-1"
[providers.openai]
class = "openai"
api_key = { engine = "bws", key = "OPENAI_API_KEY" }
# api_key_env = "OPENAI_API_KEY" # backwards-compatible environment form
# [providers.openai]
# class = "openai"
# api_key = { engine = "env", key = "OPENAI_API_KEY" }
[providers.ollama]
class = "ollama"
@@ -169,43 +144,13 @@ class = "ollama"
# "openrouter/openai/gpt-5.6-sol",
# ]
# Optional self-hosted update adapter. Both values are argv arrays (never
# 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]
# The bot token from @BotFather, resolved through a configured secret engine.
# token = { engine = "bws", key = "TELEGRAM_BOT_TOKEN" }
# 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"]
# update_install_command = ["/usr/local/bin/archie-update-install"]
# Inbound email as a chat channel, via SMTP. Empty listen_addr disables it.
# [chat.email]
# listen_addr = "0.0.0.0:2525" # inbound SMTP server
# relay_addr = "smtp.example.com:587" # outbound relay for replies
# Generic inbound webhook gateway: external services push messages into
# chat for LLM processing. This is a distinct surface from
# [forge].webhook_addr (forge issue events) and [capture] (unbound event
# storage for later binding) -- three different inbound HTTP concerns that
# happen to share the word "webhook".
# webhook_addr = "0.0.0.0:8646" # under [chat], not [chat.telegram]
#
# [chat.webhook] configures the single route the gateway serves. Every
# field is optional; an absent section runs with the pre-existing
# behaviour: path "/webhook", no signature validation, raw body as message
# text, no reply.
# [chat.webhook]
# path = "/webhook"
# secret = { engine = "bws", key = "CHAT_WEBHOOK_SECRET" } # verifies
# # X-Hub-Signature-256 on inbound payloads. Empty (the default) accepts
# # any unsigned POST -- set this to make the gateway actually verify
# # what it claims to.
# template = "issue.title" # dot-notation extraction of the message text
# # from the JSON payload. Empty uses the raw body.
# deliver_to = "origin" # "origin" writes the reply as the HTTP
# # response; empty (the default) sends no reply.
# Email and the generic inbound webhook are archipelago channel extensions
# (channels/email, channels/webhook): install, accept and enable them from the
# Extensions page, with their settings there.
# Per-(channel, sender) inbound rate limiting, shared by every chat channel:
# Telegram keys by numeric user ID, email by SMTP from address, webhook by
@@ -240,13 +185,6 @@ class = "ollama"
# work_dir = "/path/to/workspace"
# parallel_tool_calls = false
# Publish artifacts (review reports, design docs) to the collaborative editor.
# 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" }
# 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
# /health/detailed reports the readiness probes. This is what the update
@@ -267,7 +205,7 @@ listen = "127.0.0.1:8485"
# and streaming API. Auth is token-based for non-loopback addresses;
# loopback binds (127.0.0.1, ::1, localhost) skip auth automatically.
#
# From the UI cutover (archie-core-8cda.5.4) the dashboard is served by the
# The dashboard is served by the
# standalone archie-ui process, not by archied: this listen address is what
# archie-ui binds, and archied runs no dashboard listener at all. Run
# `archie-ui -config <same config.toml>` alongside the other services.
@@ -308,12 +246,14 @@ listen = "127.0.0.1:8484"
# [memory]
# engine = "builtin" # "builtin" is the only engine implemented so far
# Notifications for human-in-the-loop moments
# (approval requests, gate failures, parked tasks).
# Archie POSTs a JSON payload to the webhook
# wire it to n8n, email, Slack, or any HTTP endpoint.
# Operator alerts (parked tasks, failed runs, unhealthy services, missing
# credentials) are listed in the dashboard. Archie also POSTs each raised and
# resolved alert as JSON to the webhook: wire it to n8n, email, Slack, or any
# HTTP endpoint. Failed deliveries are retried and recorded on the alert.
[notify]
# webhook = "https://n8n.example.com/webhook/archie"
# min_severity = "warning" # info, warning or action: the lowest severity delivered
# secret = {engine = "env", key = "ARCHIE_NOTIFY_SECRET"} # signs X-Archie-Signature (HMAC-SHA256)
[budgets]
max_steps = 60
@@ -321,8 +261,19 @@ 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).
# TLS: every gRPC hop between services uses certificates from your own CA
# (step-ca, cert-manager, Vault, openssl). Each process loads
# cert_dir/<service>.pem and cert_dir/<service>-key.pem, whose DNS SAN is its
# service name: archied, archie-gateway, archie-messaging, archie-state-store,
# archie-ui. Every peer must chain to ca_file. Certificates are reloaded when
# they change. Without [tls], services may only listen on and dial loopback
# addresses, task containers cannot reach the State Store, and the harness
# setup terminal is off.
# [tls]
# ca_file = "/etc/archie/tls/ca.pem"
# cert_dir = "/etc/archie/tls"
# Services selects contract adapters at composition time.
[services.gateway]
target = "127.0.0.1:8585" # archie-gateway's gRPC address (always remote once set)
# listen = "127.0.0.1:8585" # The address archie-gateway BINDS. Read only by the
@@ -330,30 +281,26 @@ target = "127.0.0.1:8585" # archie-gateway's gRPC address (always remot
# # to the target above, so a default deployment's client and
# # server cannot drift onto different ports. Set it when the
# # host already owns that port.
# target_token = "..." # Bearer [REDACTED] for a NON-loopback listener. A loopback listener
# # (127.0.0.1/::1/localhost) needs no token. A non-loopback
# # listener without a token fails closed, as does a
# # non-loopback dial without one. The same token is
# # presented as GATEWAY_TOKEN by remote consumers.
[services.state]
target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address archied and
# # archie-gateway dial. They own no task data
# # in-process: the standalone archie-state-store process
# # owns it in PostgreSQL (docs/prds/state-store-contract.md
# # §10/§12 step 7). An empty target is a startup error.
# # owns it in PostgreSQL. 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
# # above, so a default deployment's client and server cannot
# # drift onto different ports. Move it when a port is already
# # taken on the host.
# target_token = "..." # bearer token for a NON-loopback target. A loopback target
# # (127.0.0.1/::1/localhost) needs no token. A non-loopback
# # target without a token fails closed (docs/prds/state-store-contract.md
# # §9). The same token is injected as STATE_STORE_TOKEN into
# # archie-agent containers so the agent authenticates to the
# # same remote store. See deployments/README.md for how to
# # start archie-state-store.
# The daemon's harness session contract: the dashboard's setup terminal opens
# a PTY into an ephemeral Kit container over it. Both ends are optional and
# the dashboard's setup terminal degrades to 503 without them: the daemon
# serves the contract only when [tls] is configured, and archie-ui dials it
# only when a target is set.
# [services.harness]
# target = "127.0.0.1:8587" # The address archie-ui dials. Empty leaves the
# # setup terminal unwired.
# NATS is the sole autonomous workflow handoff. mode changes only where the
# broker runs; every workflow still runs in a managed task container:
@@ -367,13 +314,13 @@ 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).
# be inspected and mapped later.
# 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. 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
# The receiver is mounted by the
# archie-ui process, which projects these same values from this file; the
# daemon's binding-dispatch loop consumes captures from the shared State
# Store. Leave this section here even if you do not edit it: both processes
@@ -424,7 +371,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 bindings.secret column with AES-256-
# GCM (see docs/prds/binding-secret-encryption.md). When the key is absent,
# GCM. 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
# until they are edited. Rotation: after changing encryption_key, retain the
@@ -472,8 +419,8 @@ target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address arch
#
# Credential bindings map a Kit's credential@1 service name to a secret. A
# binding alone grants nothing -- an identity resolves it only when its own
# org matches and the service is in its granted_credentials (see
# [[identities]] above). Once the State Store holds it, edit bindings in the
# org matches and the service is in its granted_credentials
# ([[identities]] above). Once the State Store holds it, edit bindings in the
# dashboard (Settings, Advanced); a stored set replaces the file's.
# [[containers.credentials]]
# service = "openai"
+2 -9
View File
@@ -1,12 +1,5 @@
// Package configtemplate embeds config.example.toml so archied setup can
// generate a first-run config.toml from the exact file operators already
// read as documentation, instead of a second copy that can drift from it.
//
// It lives at the module root, rather than under internal/, because embed
// patterns cannot reach outside the directory of the .go file that declares
// them, and config.example.toml is kept at the root where it is easy to
// find and hand-edit. (Written without the directive prefix on purpose:
// staticcheck reads "// go:embed" in prose as a malformed directive.)
// Package configtemplate embeds config.example.toml for archied setup. It
// sits at the module root because embed cannot reach parent directories.
package configtemplate
import _ "embed"
-352
View File
@@ -1,352 +0,0 @@
package configtemplate
import (
"os"
"path/filepath"
"sort"
"strings"
"testing"
)
func TestDeployWorkflowOnlyPublishesRuntimeImageForTaggedRelease(t *testing.T) {
source := readDeploymentFile(t, ".github/workflows/deploy.yml")
// The fallback remains necessary because Dockerfile.archied accepts a
// runtime version, but it must not be used as the image-publish selector.
for _, required := range []string{
`RUNTIME_TAG="$(git tag --points-at HEAD --list 'archie/v*' | sort -V | tail -1)"`,
`RELEASE_TAG="$(git tag --points-at HEAD --list 'v*' | sort -V | tail -1)"`,
`echo "runtime_tag=$RUNTIME_TAG" >> "$GITHUB_OUTPUT"`,
`echo "release_tag=$RELEASE_TAG" >> "$GITHUB_OUTPUT"`,
} {
if !strings.Contains(source, required) {
t.Errorf("deploy workflow is missing runtime-image guard %q", required)
}
}
// The gateway build remains unconditional, while the runtime build is
// guarded. Both selectors are required. A one-stream release creates only a
// `v*` tag -- release.sh has no archie/v* arm any more -- so a
// runtime_tag-only condition would mean the agent image is never rebuilt
// again, and `docker compose pull agent` would fetch an ancient image
// forever. The legacy archie/v* arm stays because history is not re-tagged.
agentMarker := " - name: Build and push archie-agent\n"
agentStart := strings.Index(source, agentMarker)
if agentStart < 0 {
t.Fatal("deploy workflow has no archie-agent build step")
}
agentIf := " if: steps.versions.outputs.runtime_tag != '' || steps.versions.outputs.release_tag != ''\n"
if !strings.Contains(source[agentStart:], agentMarker+agentIf) {
t.Fatal("archie-agent build step is not conditionally enabled")
}
gatewayMarker := " - name: Build and push archied\n"
gatewayStart := strings.Index(source, gatewayMarker)
if gatewayStart < 0 {
t.Fatal("deploy workflow has no archied build step")
}
if strings.Contains(source[gatewayStart:agentStart], "\n if:") {
t.Fatal("archied build step is unexpectedly conditional")
}
}
// TestDeployWorkflowPublishesLatestOnlyFromARelease pins the rule that keeps a
// release's :latest stamping from being overwritten by the next ordinary commit.
//
// build-and-push runs on any push to main and used to always push :latest, so a
// release's own stamping survived only until the next commit — minutes, in an
// active repo — and a host deploying :latest reported dev, leaving the update
// path unable to tell current from stale (archie-core-i5nb). :latest now moves
// only from a commit that IS a release; everything else publishes :edge and an
// immutable sha-<commit>.
func TestDeployWorkflowPublishesLatestOnlyFromARelease(t *testing.T) {
source := readDeploymentFile(t, ".github/workflows/deploy.yml")
for _, required := range []string{
`if [ -n "$RELEASE_TAG" ]; then`,
`echo "ghcr.io/samcharles93/archied:latest"`,
`echo "ghcr.io/samcharles93/archied:edge"`,
`archied_tags<<EOF`,
`tags: ${{ steps.versions.outputs.archied_tags }}`,
} {
if !strings.Contains(source, required) {
t.Errorf("deploy workflow is missing the release-only :latest guard %q", required)
}
}
// One occurrence: the guard above, not a second unconditional copy that would
// undo it.
if got := strings.Count(source, "ghcr.io/samcharles93/archied:latest"); got != 1 {
t.Errorf("archied :latest appears %d times, want exactly 1 inside the release-tag guard", got)
}
}
func TestDeployWorkflowUsesConfiguredFormatters(t *testing.T) {
source := readDeploymentFile(t, ".github/workflows/deploy.yml")
for _, required := range []string{
"github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2",
"golangci-lint fmt",
"git diff --exit-code",
"golangci-lint run ./...",
} {
if !strings.Contains(source, required) {
t.Errorf("deploy workflow is missing formatter gate %q", required)
}
}
if strings.Contains(source, "gofumpt -w .") {
t.Error("deploy workflow bypasses the configured formatter set")
}
}
func TestPullRequestsRunTheDefinitiveGateWithoutPublishAccess(t *testing.T) {
source := readDeploymentFile(t, ".github/workflows/quality.yml")
for _, required := range []string{
"pull_request:",
"contents: read",
"task check",
"git diff --exit-code",
} {
if !strings.Contains(source, required) {
t.Errorf("quality workflow is missing %q", required)
}
}
for _, forbidden := range []string{
"packages: write",
"docker/login-action",
"docker/build-push-action",
} {
if strings.Contains(source, forbidden) {
t.Errorf("quality workflow has publishing capability %q", forbidden)
}
}
}
// unpackagedCommands are commands that deliberately never ship as a host binary.
// 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-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:
// they are not services.
var cliOnlyCommands = map[string]bool{"archie-playbooks": true}
// TestDistZipShipsEveryHostCommand is why archie-core-1c01 went unnoticed for
// two days. The v1.30.0 extraction moved Telegram, email and webhook out of
// archied into a new cmd/archie-messaging that nothing packaged: the release zip
// omitted it, scripts/archie-update-install omitted it from both of its lists,
// and install.sh's build loop omitted it too, so a host install ran on with a
// dead Telegram bot and no error logged anywhere. The daemon looked healthy
// throughout.
//
// The host component set was enumerated independently in four places (the zip's
// build loop, the zip's copy list, install.sh's build loop, and the updater's
// two lists), so two coordinated edits would have drifted again. Every list is
// pinned to cmd/ here instead: adding a command fails this test until it is
// packaged, and extracting one fails it until the previous command is removed.
// The updater's service list is separately required to have a documented unit,
// and its runtime guard refuses a host unit the list omits.
func TestDistZipShipsEveryHostCommand(t *testing.T) {
workflow := readDeploymentFile(t, ".github/workflows/deploy.yml")
installer := readDeploymentFile(t, filepath.Join("scripts", "archie-update-install"))
installSh := readDeploymentFile(t, "install.sh")
want := hostRunCommands(t)
wantBinaries := want
wantServices := withoutCLIOnly(want)
built := wordsAfter(t, workflow, "for cmd in ", "; do", nil)
// The marker consumes the prefix of the first word only, so restore it for
// whichever word the marker ended inside.
var shipped []string
for _, word := range wordsAfter(t, workflow, "cp dist/", ` "$name/"`, nil) {
if !strings.HasPrefix(word, "dist/") {
word = "dist/" + word
}
shipped = append(shipped, strings.TrimPrefix(word, "dist/"))
}
services := wordsAfter(t, installer, `GATEWAY_SERVICES="`, `"`, nil)
binaries := wordsAfter(t, installer, `GATEWAY_BINARIES="`, `"`, map[string][]string{"$GATEWAY_SERVICES": services})
installBuilt := installBuildCommands(t, installSh)
for _, list := range []struct {
name string
got []string
want []string
}{
{"deploy.yml dist-zip build loop", built, wantBinaries},
{"deploy.yml dist-zip copy list", shipped, wantBinaries},
{"install.sh build loop", installBuilt, wantBinaries},
{"archie-update-install GATEWAY_BINARIES", binaries, wantBinaries},
{"archie-update-install GATEWAY_SERVICES", services, wantServices},
} {
if diff := setDifference(list.want, list.got); diff != "" {
t.Errorf("%s does not match the host-run commands in cmd/: %s", list.name, diff)
}
}
// The installer now REFUSES an update when a service unit is missing and
// tells the operator to create it from this runbook, so a service the
// runbook never shows is a dead end rather than a documentation gap.
// Stamping is its own list, and a third build site made it three: the zip,
// install.sh and the updater each build the host binaries. A binary that
// cannot say what it is cannot be compared (archie-core-k94o), so a seventh
// command added unstamped fails here rather than waiting to be noticed.
for name, source := range map[string]string{
"deploy.yml": workflow,
"install.sh": installSh,
"archie-update-install": installer,
} {
if !strings.Contains(source, "internal/buildinfo.Version=") {
t.Errorf("%s does not stamp internal/buildinfo.Version", name)
}
}
for _, command := range wantBinaries {
// archied's flag lives in the app package it delegates to, not its thin
// cmd main; the rest report through buildinfo in their own main.
source := filepath.Join("cmd", command, "main.go")
if command == "archied" {
source = filepath.Join("internal", "app", "archied", "main.go")
}
main := readDeploymentFile(t, source)
if !strings.Contains(main, "buildinfo") && !strings.Contains(main, "-version") && !strings.Contains(main, "\"version\"") {
t.Errorf("%s has no way to report its version", source)
}
}
// The installer writes the units, so the runbook no longer carries their
// contents; it must still name each unit, or an operator cannot find one to
// inspect or override.
runbook := readDeploymentFile(t, filepath.Join("deployments", "systemd-user-service.md"))
var undocumented []string
for _, service := range wantServices {
if !strings.Contains(runbook, service+".service") {
undocumented = append(undocumented, service)
}
}
if len(undocumented) > 0 {
t.Errorf("deployments/systemd-user-service.md names no unit for: %s", strings.Join(undocumented, " "))
}
}
// installBuildCommands reads install.sh's build loop. The file has a second
// `for cmd in` (the git/go preflight), so the loop is located by the go build it
// drives rather than by the first marker -- and read from the real list, so a
// missing command is named instead of the marker merely going absent.
func installBuildCommands(t *testing.T, source string) []string {
t.Helper()
before, _, ok := strings.Cut(source, `go build -ldflags "${LDFLAGS}"`)
if !ok {
t.Fatal("install.sh has no go build loop to read")
}
prefix := before
start := strings.LastIndex(prefix, "for cmd in ")
if start < 0 {
t.Fatal("install.sh build loop has no for cmd list")
}
rest := prefix[start+len("for cmd in "):]
before0, _, ok0 := strings.Cut(rest, "; do")
if !ok0 {
t.Fatal("install.sh build loop is unterminated")
}
return strings.Fields(before0)
}
// hostRunCommands is every command under cmd/, minus the deliberately
// unpackaged ones. Deriving it is the point: a list written out here would drift
// from cmd/ exactly as the packaged lists did.
func hostRunCommands(t *testing.T) []string {
t.Helper()
entries, err := os.ReadDir("cmd")
if err != nil {
t.Fatalf("read cmd/: %v", err)
}
var commands []string
for _, entry := range entries {
if !entry.IsDir() {
continue
}
if _, skip := unpackagedCommands[entry.Name()]; skip {
continue
}
commands = append(commands, entry.Name())
}
if len(commands) == 0 {
t.Fatal("cmd/ holds no commands: this guard would assert nothing")
}
sort.Strings(commands)
return commands
}
func withoutCLIOnly(commands []string) []string {
out := make([]string, 0, len(commands))
for _, command := range commands {
if cliOnlyCommands[command] {
continue
}
out = append(out, command)
}
return out
}
// wordsAfter returns the whitespace-separated words between two markers on the
// same line. expand maps a word to the words it stands for, which is how the
// installer's "$GATEWAY_SERVICES" reference is followed to what it names.
func wordsAfter(t *testing.T, source, marker, terminator string, expand map[string][]string) []string {
t.Helper()
start := strings.Index(source, marker)
if start < 0 {
t.Fatalf("no %q in the file under test", marker)
}
rest := source[start+len(marker):]
end := strings.Index(rest, terminator)
if end < 0 {
t.Fatalf("no %q after %q", terminator, marker)
}
var words []string
for word := range strings.FieldsSeq(rest[:end]) {
if replacement, ok := expand[word]; ok {
words = append(words, replacement...)
continue
}
words = append(words, word)
}
return words
}
// setDifference names what is missing from and extra in got, so a failure says
// which side moved rather than that two lists differ.
func setDifference(want, got []string) string {
present := make(map[string]bool, len(got))
for _, item := range got {
present[item] = true
}
var missing []string
for _, item := range want {
if !present[item] {
missing = append(missing, item)
}
}
expected := make(map[string]bool, len(want))
for _, item := range want {
expected[item] = true
}
var extra []string
for _, item := range got {
if !expected[item] {
extra = append(extra, item)
}
}
sort.Strings(missing)
sort.Strings(extra)
var problems []string
if len(missing) > 0 {
problems = append(problems, "missing "+strings.Join(missing, " "))
}
if len(extra) > 0 {
problems = append(problems, "unexpected "+strings.Join(extra, " "))
}
return strings.Join(problems, "; ")
}
-247
View File
@@ -1,247 +0,0 @@
package configtemplate
import (
"os"
"regexp"
"strings"
"testing"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
)
func readDeploymentFile(t *testing.T, path string) string {
t.Helper()
data, err := os.ReadFile(path)
if err != nil {
t.Fatal(err)
}
return string(data)
}
func TestExternalNATSProfileLoadsWithManagedWorkers(t *testing.T) {
doc, err := configuration.New(nil).File("deployments/docker-nats-stack.toml")
if err != nil {
t.Fatalf("load external NATS deployment: %v", err)
}
if doc.Config.NATS.Mode != config.NATSModeExternal {
t.Errorf("NATS mode = %q, want %q", doc.Config.NATS.Mode, config.NATSModeExternal)
}
if doc.Config.Containers.Image == "" {
t.Error("managed worker image is empty")
}
}
func TestInstallerUsesNativeDaemonAndManagedWorkerImage(t *testing.T) {
source := readDeploymentFile(t, "install.sh")
for _, forbidden := range []string{
"[agent]",
`go build -o "${ARCHIE_BIN_DIR}/archie-agent"`,
`- archie-agent`,
"required only for NATS container mode",
} {
if strings.Contains(source, forbidden) {
t.Errorf("install.sh contains removed deployment behavior %q", forbidden)
}
}
for _, required := range []string{
`ExecStart=${ARCHIE_BIN_DIR}/archied`,
"Docker is required for autonomous workflows",
} {
if !strings.Contains(source, required) {
t.Errorf("install.sh is missing deployment contract %q", required)
}
}
}
func TestWorkerImageIsNotDocumentedAsAStandaloneExecutor(t *testing.T) {
source := readDeploymentFile(t, "Dockerfile")
if strings.Contains(source, "docker run -e NATS_URL") {
t.Error("Dockerfile documents an unsupported manually started worker")
}
if !strings.Contains(source, "launched only by archied") {
t.Error("Dockerfile does not state that archied owns worker lifecycle")
}
}
func TestFormattingUsesOneConfiguredWriter(t *testing.T) {
taskfile := readDeploymentFile(t, "Taskfile.yml")
fmtStart := strings.Index(taskfile, " fmt:\n")
fmtEnd := strings.Index(taskfile, " proto:install:\n")
if fmtStart < 0 || fmtEnd < fmtStart {
t.Fatal("Taskfile has no bounded fmt task")
}
fmtTask := taskfile[fmtStart:fmtEnd]
const applyFix = "go fix ./..."
fix := strings.Index(fmtTask, applyFix)
format := strings.Index(fmtTask, "golangci-lint fmt")
if fix < 0 || format < 0 || fix > format {
t.Error("fmt task must run go fix before the configured golangci-lint formatters")
}
if strings.Contains(fmtTask, "gofumpt -") {
t.Error("fmt task bypasses the configured formatter set with standalone gofumpt")
}
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)
}
}
func TestBuildTaskSourcesTrackEmbeddedAssets(t *testing.T) {
taskfile := readDeploymentFile(t, "Taskfile.yml")
start := strings.Index(taskfile, "\n build:\n")
end := strings.Index(taskfile, "\n test:\n")
if start < 0 || end < start {
t.Fatal("Taskfile has no bounded build task")
}
build := taskfile[start:end]
sourcesAt := strings.Index(build, "sources:")
generatesAt := strings.Index(build, "generates:")
if sourcesAt < 0 || generatesAt < sourcesAt {
t.Fatal("build task has no bounded sources block")
}
sources := build[sourcesAt:generatesAt]
for _, tc := range []struct {
name string
path string
reason string
}{
{
name: "embedded dashboard",
path: "ui/dist/**",
reason: "ui/embed.go embeds it with //go:embed all:dist, so a dashboard changing with no .go file changing must still rebuild the binaries",
},
} {
if !strings.Contains(sources, tc.path) {
t.Errorf("build sources do not track %s: %s", tc.name, tc.reason)
}
}
}
func TestBuildTaskStampsInstallTypeOnEveryCommand(t *testing.T) {
taskfile := readDeploymentFile(t, "Taskfile.yml")
start := strings.Index(taskfile, "\n build:\n")
end := strings.Index(taskfile, "\n test:\n")
if start < 0 || end < start {
t.Fatal("Taskfile has no bounded build task")
}
build := taskfile[start:end]
cmdsAt := strings.Index(build, "\n cmds:\n")
if cmdsAt < 0 {
t.Fatal("build task has no cmds block")
}
cmds := build[cmdsAt:]
buildLine := regexp.MustCompile(`^ - go build .*\./cmd/([a-z0-9-]+)`)
found := 0
for line := range strings.SplitSeq(cmds, "\n") {
m := buildLine.FindStringSubmatch(line)
if m == nil {
continue
}
found++
if !strings.Contains(line, "internal/installtype.buildType=") {
t.Errorf("build task does not stamp installtype.buildType on %s: %s", m[1], strings.TrimSpace(line))
}
}
if found == 0 {
t.Fatal("build task has no go build commands under ./cmd/: this guard would assert nothing")
}
}
func TestFormattersExcludeInterpretedSecretEngines(t *testing.T) {
config := readDeploymentFile(t, ".golangci.yml")
if !strings.Contains(config, `^examples/secret-engines/(age|sops|vault)\.go$`) {
t.Fatal("formatter config does not protect the interpreted secret engines")
}
}
func TestSupportedProfilesUseOneExecutionTopology(t *testing.T) {
profiles := []string{
"deployments/single-forge-github.toml",
"deployments/multi-forge-github-gitea.toml",
"deployments/local-ollama-standalone.toml",
"deployments/docker-nats-stack.toml",
}
for _, path := range profiles {
source := readDeploymentFile(t, path)
if strings.Contains(source, "\n[agent]\n") {
t.Errorf("%s still selects a legacy agent executor", path)
}
}
for _, path := range profiles[:2] {
source := readDeploymentFile(t, path)
for _, required := range []string{`mode = "embedded"`, "[containers]"} {
if !strings.Contains(source, required) {
t.Errorf("%s is missing default topology marker %q", path, required)
}
}
}
external := readDeploymentFile(t, "deployments/docker-nats-stack.toml")
if !strings.Contains(external, `mode = "external"`) {
t.Error("docker-nats-stack.toml does not explicitly select external NATS")
}
systemd := readDeploymentFile(t, "deployments/systemd-user-service.md")
if !strings.Contains(systemd, "Embedded NATS is the default") {
t.Error("systemd runbook does not identify embedded NATS as the default")
}
if strings.Contains(systemd, "still needs NATS") {
t.Error("systemd runbook still requires an external Compose NATS service")
}
}
// TestInstallerDelegatesConfigGenerationToArchiedSetup pins the contract the
// installer already drifted from once: it hand-rolled a config.toml, hardcoded
// the GitHub token key and the Gitea host, and choosing Gitea then produced a
// config naming a token it never wrote. The durable fix is that the code writing
// the config is the code reading it -- archied setup renders it, archied loads it
// (docs/architecture/configuration.md) -- and nothing stopped the generating
// branch growing back until this.
func TestInstallerDelegatesConfigGenerationToArchiedSetup(t *testing.T) {
source := readDeploymentFile(t, "install.sh")
for _, required := range []string{
// It runs the binary it just built, so the installer cannot hold a
// second idea of what a valid config looks like.
`"${ARCHIE_BIN_DIR}/archied" setup`,
// For a fresh install only: an existing config is the operator's.
`if [ ! -f "${ARCHIE_CONFIG_DIR}/config.toml" ]; then`,
"already exists (preserving user config)",
// The setup run is allowed to fail, and a failure is loud. A config that
// never gets written is the only honest outcome after that.
"could not generate",
} {
if !strings.Contains(source, required) {
t.Errorf("install.sh is missing %q", required)
}
}
// Nothing here renders TOML or splices it afterwards. The splice check is
// per line so a legitimate sed/awk elsewhere in the installer stays allowed.
if strings.Contains(source, "forge_block") {
t.Error("install.sh still carries the forge_block helper: it is what hardcoded the GitHub token key and Gitea host")
}
redirection := regexp.MustCompile(`>>?\s*"?[^"'\s]*config\.toml`)
for index, line := range strings.Split(source, "\n") {
if !strings.Contains(line, "config.toml") {
continue
}
if strings.Contains(line, "sed ") || strings.Contains(line, "awk ") {
t.Errorf("install.sh:%d splices config.toml (%s)", index+1, strings.TrimSpace(line))
}
if redirection.MatchString(line) {
t.Errorf("install.sh:%d writes config.toml itself (%s)", index+1, strings.TrimSpace(line))
}
}
// A TOML table header in the installer is a template by definition. The
// systemd unit it also writes is INI, whose only sections are Unit/Service/
// Install, so those are no part of this list.
template := regexp.MustCompile(`(?m)^\s*\[(forge|models|providers|runners|containers|nats|web|budgets|notify|identit|chat)\]`)
if found := template.FindString(source); found != "" {
t.Errorf("install.sh carries a TOML template (%q): the installer must not hold its own idea of the config schema", strings.TrimSpace(found))
}
}
+79 -41
View File
@@ -1,28 +1,23 @@
# Running this distribution
This archive contains six linux/amd64 binaries:
This archive contains five linux/amd64 binaries:
- **`archied`** — the resident daemon: polls your forge for assigned issues
and dispatches them into sandboxed `archie-agent` containers. It serves no
dashboard: the web UI is `archie-ui`'s process (UI cutover,
`archie-core-8cda.5.4`).
- **`archie-ui`** — serves the operator dashboard and the webhook capture
receiver, dialing the Gateway and State Store gRPC contracts. Reads only
`[services.*]`, `[web]` and `[capture]` from the shared `config.toml`.
- **`archie-gateway`** — serves the chat (`ChatContract`) surface `archied`,
`archie-ui` and `archie-messaging` dial. Runs as its own process; `archied`
never embeds a gateway.
- **`archie-messaging`** — serves the Telegram, email and webhook channels,
dialing the Gateway for the chat contract and the State Store for the stored
channel settings. `archied` runs no gateway for those channels, so without
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 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
before it reaches `archied`.
Each service owns its data and reaches the others only through their gRPC
contracts (or NATS, for task actions):
| Service | Owns | Reaches |
|---|---|---|
| `archie-state-store` | tasks, events, control-plane settings, identities and access policies, installed packages (PostgreSQL) | nothing |
| `archie-gateway` | conversations (PostgreSQL, its own tables) and every model call: chat turns, curators, MCP tools and sampling | State Store; daemon over NATS for task actions |
| `archied` | dispatch: forge polling, the task queue, the embedded NATS broker, agent containers | State Store; Gateway |
| `archie-messaging` | the Telegram, email and webhook channel connections | Gateway; State Store for channel settings |
| `archie-ui` | the dashboard and the webhook capture receiver | Gateway; State Store |
`archied playbooks lint` checks playbook binding YAML before it reaches the
daemon, and `archied playbooks serve` is its language server for editors.
Without `archie-messaging` the channels are simply absent, so it needs a unit
of its own (`deployments/systemd-user-service.md`).
`archie-agent` (the per-task sandboxed runtime) is **not** in this archive —
it only ever runs inside the Docker container `archied` spawns per task, never
@@ -33,9 +28,10 @@ as a host binary. Pull it from GHCR: `ghcr.io/samcharles93/archie-agent`.
1. Pick a starting configuration. The full set of annotated templates lives
in this repository's `deployments/` directory on GitHub
(<https://github.com/samcharles93/archie-core/tree/main/deployments>) —
`single-forge-github.toml`, `multi-forge-github-gitea.toml`,
`local-ollama-standalone.toml`, and `docker-nats-stack.toml` cover the
common cases. Copy whichever fits to:
`standalone.toml` (no forge, the simplest start),
`single-forge-github.toml`, `multi-forge-github-gitea.toml` and
`docker-nats-stack.toml` cover the common cases. Every one needs
PostgreSQL 18 at `database_url`. Copy whichever fits to:
```bash
mkdir -p ~/.config/archie
@@ -46,9 +42,10 @@ as a host binary. Pull it from GHCR: `ghcr.io/samcharles93/archie-agent`.
providers) and place any secrets in `~/.config/archie/env` or referenced
`secret://` locations.
3. Start the five processes, in order (`archie-state-store` and
`archie-gateway` first — `archied`, `archie-ui` and `archie-messaging` dial
both at startup):
3. Start the five processes. Order does not matter: a service whose peer is
not up yet waits for it and reports it as degraded on its health surface
meanwhile. The Gateway waits for the daemon's NATS endpoint when the broker
is embedded.
```bash
./archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090 &
@@ -58,14 +55,9 @@ as a host binary. Pull it from GHCR: `ghcr.io/samcharles93/archie-agent`.
./archied -config ~/.config/archie/config.toml
```
Dashboard reachability comes from `[web].listen` (default
`127.0.0.1:8484`, which needs no dashboard token). For a non-loopback
bind pass `-listen` with `-token` or `-token-file` to mint and persist
one. `archie-ui` reads `GATEWAY_TOKEN` / `STATE_STORE_TOKEN` from its
process environment only — it has no secret registry, so when those
tokens live in a secret manager, whatever starts `archie-ui` must export
them into its environment (the `[services.*].target_token` values in
`config.toml` are the other supported source).
Open `[web].listen` (default `127.0.0.1:8484`) to configure the organisation,
workspace and first administrator account. Remote access requires an HTTPS
reverse proxy. Complete setup before exposing the dashboard publicly.
4. For a persistent, 24/7 deployment instead of a foreground run, follow the
systemd user-unit runbook:
@@ -73,15 +65,15 @@ as a host binary. Pull it from GHCR: `ghcr.io/samcharles93/archie-agent`.
## Verifying an install
`archie-playbooks lint -dir <playbooks-dir>` validates playbook binding YAML
`archied playbooks lint -dir <playbooks-dir>` validates playbook binding YAML
against the same schema `archied` loads at startup — run it against your
playbooks directory before pointing `archied` at it.
## Version
This archive's binaries are built from the `archied` release tag in its
filename; `archie-ui`, `archie-gateway`, `archie-state-store`,
`archie-messaging` and `archie-playbooks` ship at that same version rather than
filename; `archie-ui`, `archie-gateway`, `archie-state-store` and
`archie-messaging` ship at that same version rather than
being independently tagged (see `RELEASING.md` in the source repository for why
only `archied` and `archie-agent` are independently versioned).
@@ -89,5 +81,51 @@ only `archied` and `archie-agent` are independently versioned).
`archied` are services that must be running and addressable; `archie-messaging`
carries the Telegram, email and webhook channels since the v1.30.0 extraction, so
an install (or an upgrade across v1.30.0) needs its unit as well -- see
`deployments/systemd-user-service.md`. `archie-playbooks` is a CLI and runs on
demand.
`deployments/systemd-user-service.md`.
### Native self-update
Install on Settings → Status runs `archied update install -version X`, which
downloads the release's Linux/amd64 zip and verifies it against `SHA256SUMS`
before unpacking it. Every host binary in the zip must report `X`. It then pulls
the agent image `release.json` pins by digest, backs up the database to
`db.pre-update.dump` in the state directory, stages the new binaries beside the
live ones and hands the transaction to `archied update watchdog` in a process of
its own (a transient systemd user unit). Nothing that runs changes until the
watchdog takes over.
`archied update check` finds the newest GitHub release with a linux-amd64 zip on
the channel chosen under Settings → Status → Updates: stable, next (includes
prereleases) or a pinned version. From a shell it reads
`ARCHIE_UPDATE_RELEASE_CHANNEL` and `ARCHIE_UPDATE_PIN`, or `-channel` and `-pin`.
The notification destination remains separate from the release channel.
`release.json` supplies the service order and required config sections to both
first-install and self-update. A missing unit or config section produces an
ordered migration plan and refuses installation. Apply that plan before retrying.
Automatic topology edits are intentionally unsupported.
The watchdog stops the units in reverse `release.json` order, switches the
staged executables by rename, switches the control-plane image policy (only the
image field, with conflict detection), and restarts the units in order through
`systemctl --user`. archied must report the new version and stay healthy for
120 seconds. Otherwise the watchdog restores the previous binaries and image
policy. Data is not rolled back unless the new release migrated the database:
then the previous binaries cannot serve it, so the pre-update backup is restored
and the outcome report says that every write since the update began is gone.
Without a systemd user manager the watchdog switches binaries and image policy
but restarts nothing, and the install reports that the services need a manual
restart.
Transactions live in `${XDG_STATE_HOME:-~/.local/state}/archie/update`, outside
the binary directory: `transaction/journal.json`, `transaction/previous/`, and
`transaction/archied`, the frozen copy of the archied that wrote the journal. On
daemon boot, an interrupted transaction is
handed to that frozen watchdog with `-recover` before normal startup: a
transaction that never started is discarded, one that was switching or observing
is rolled back, and a decided one is finished. To recover manually, run
`transaction/archied update watchdog -recover -bin-dir ~/.local/bin` from that
state directory. A failed recovery keeps the journal for another attempt.
The database backup stays in the state directory after a committed update for
manual recovery with `archie-state-store restore`.
+27 -22
View File
@@ -10,8 +10,9 @@ This directory contains configuration templates and guides for different deploym
- **[`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)**:
Self-hosted deployment running local LLM models via Ollama (e.g., `llama3`, `qwen2.5`) with optional standalone (forge-disabled) operation.
- **[`standalone.toml`](./standalone.toml)**: start here. Event-driven
automation with no forge or repositories, local Ollama models, loopback
services and no tokens.
- **[`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.
@@ -42,25 +43,24 @@ archied -config ~/.config/archie/config.toml
systemctl --user start archied
```
The templates use the extracted Gateway Service by default. Start
`archie-gateway` before `archied`; it owns the conversation tables and
serves the `ChatContract` gRPC API on the configured target.
Start order does not matter: a service waits for its peers and reports them as
degraded meanwhile. Every template needs PostgreSQL 18 at `database_url`;
`docker compose up -d postgres` provides the default one.
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].target` and never open the task tables themselves. 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
Docker bridge gateway address plus a matching bearer token (`target_token` /
`--token` / `STATE_STORE_TOKEN`), because a container cannot reach the host's
loopback.
(`127.0.0.1:9090`), while a container-mode agent needs the Docker bridge
gateway address, because a container cannot reach the host's loopback. A
non-loopback address needs `[tls]` certificates from your own CA; see
`config.example.toml`.
## Running the dashboard
The dashboard is served by the standalone UI Service (`archie-ui`), not by
`archied` (UI cutover, `archie-core-8cda.5.4`; `docs/prds/ui-service-boundary.md`).
`archied`.
It reads the same `config.toml`, dials the Gateway and State Store targets
already configured there, and binds `[web].listen` (`127.0.0.1:8484` by
default). Start it after the Gateway and the State Store:
@@ -69,24 +69,29 @@ default). Start it after the Gateway and the State Store:
archie-ui -config ~/.config/archie/config.toml
```
A non-loopback `[web].listen` requires a dashboard token (`-token`, or
`-token-file` to mint and persist one); a loopback bind needs none.
Open the dashboard to configure the organisation, workspace and first administrator account.
Use HTTPS through a reverse proxy for remote access, and complete setup before exposing it publicly.
`archied` runs no dashboard listener at all, so webhook capture
(`POST /webhooks/capture/{source}`) is received by archie-ui and the
binding-dispatch loop in `archied` consumes what arrives from the shared
State Store.
Auth note: unlike `archied`, archie-ui has no secret registry --
`GATEWAY_TOKEN`/`STATE_STORE_TOKEN` resolve from its process environment
only (or from `[services.*].target_token` in `config.toml`), so whatever
starts archie-ui must export those tokens into its environment. See the UI
Service unit in `systemd-user-service.md` for the worked example.
The dashboard speaks plain HTTP. A non-loopback bind therefore carries the
session cookie and the provider token in clear over the network, and
archie-ui warns about exactly that at startup. Terminate TLS in front of it
(a reverse proxy or the tunnel itself) and set
`[web].trust_forwarded_headers = true` to declare the proxy and silence the
warning; leaving it off while exposing the port directly is the case the
warning names.
Auth note: archie-ui authenticates to its dependencies with its `[tls]`
certificate (`archie-ui.pem`).
```bash
# loopback (host-only agent)
archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090
# or container-mode: bind the bridge gateway with a token
archie-state-store -config ~/.config/archie/config.toml -listen 172.17.0.1:9090 -token <token>
# or container-mode: bind the bridge gateway ([tls] required)
archie-state-store -config ~/.config/archie/config.toml -listen 172.17.0.1:9090
```
## Verifying the daemon
@@ -120,7 +125,7 @@ curl -s http://127.0.0.1:9091/health/detailed # s
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).
opens the task tables indicates dual-store ownership.
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.
+3 -2
View File
@@ -1,7 +1,7 @@
# Development overlay for `task dev` and `task dev:dashboard`.
#
# Match Vite's API/event proxy without changing the installed configuration.
# After the UI cutover (archie-core-8cda.5.4) the dashboard on :8484 is the
# The dashboard on :8484 is the
# archie-ui process's listener, not archied's; this overlay is what both
# `go run ./cmd/archied -config-overlay deployments/dev.toml` and
# `go run ./cmd/archie-ui -config-overlay deployments/dev.toml` read. Only
@@ -12,6 +12,8 @@
# 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.
bot_user = "archie-dev"
database_url = "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable"
[web]
@@ -23,7 +25,6 @@ listen = "127.0.0.1:8484"
# when a port is already taken on the host -- before the
# listen key existed the collision could only be worked around by hand-writing
# a matching target and passing -listen, and it read as a code fault.
# (docs/prds/state-store-contract.md §12 step 7).
[services.state]
target = "127.0.0.1:9091"
listen = "127.0.0.1:9091"
+10 -16
View File
@@ -16,7 +16,7 @@ bot_user = "archie"
diff_cap_lines = 0
work_dir = "~/.local/share/archie/work"
state_dir = "~/.local/share/archie" # NATS store, task logs
# The State Store's PostgreSQL connection (required; Postgres-only epic).
# The State Store's PostgreSQL connection (PostgreSQL 18, required).
# `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"
@@ -25,14 +25,16 @@ database_url = "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable"
target = "127.0.0.1:8585"
# 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
# no token.
# archie-gateway dial it and never open those tables themselves.
# This deployment runs the agent in containers, so the target is the Docker
# bridge gateway (172.17.0.1) the container can reach. A non-loopback address
# needs [tls]; see config.example.toml.
[services.state]
target = "172.17.0.1:9090"
target_token = "change-me-state-store-token"
[tls]
ca_file = "/etc/archie/tls/ca.pem"
cert_dir = "/etc/archie/tls"
[forge]
type = "gitea"
@@ -46,13 +48,6 @@ key = "ARCHIE_GITEA_TOKEN"
trigger = "assignee"
ack_reaction = "eyes"
[dispatch.labels]
queued = "agent:queued"
working = "agent:working"
waiting = "agent:waiting"
pr = "agent:pr"
parked = "agent:parked"
# Stages run in sandboxed archie-agent containers over NATS. archied only
# orchestrates: the agent image carries the toolchain and makes the model
# calls, so gate commands resolve there, not in the native daemon.
@@ -78,8 +73,7 @@ max_uptime = "60m"
pull_policy = "missing"
[web]
# Bound by the archie-ui process (the host-run dashboard after the UI
# cutover, archie-core-8cda.5.4); it dials the [services.*] targets above --
# Bound by the archie-ui process; it dials the [services.*] targets above --
# the bridge-gateway State Store address works from the host too.
listen = "127.0.0.1:8484"
# Trust X-Forwarded-Proto when fronted by a reverse proxy (e.g. Traefik)
+5 -7
View File
@@ -8,7 +8,7 @@
work_dir = "~/.local/share/archie/work"
state_dir = "~/.local/share/archie" # NATS store, task logs
# The State Store's PostgreSQL connection (required; Postgres-only epic).
# The State Store's PostgreSQL connection (PostgreSQL 18, required).
# `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"
@@ -17,14 +17,12 @@ database_url = "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable"
target = "127.0.0.1:8585"
# 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
# no token.
# archie-gateway dial it and never open those tables themselves.
# This deployment runs the agent in containers, so the target is the Docker
# bridge gateway (172.17.0.1) the container can reach. A non-loopback address
# needs [tls]; see config.example.toml.
[services.state]
target = "172.17.0.1:9090"
target_token = "change-me-state-store-token"
[models]
triage = "openai/gpt-6-luna"
+5 -17
View File
@@ -7,7 +7,7 @@
work_dir = "~/.local/share/archie/work"
state_dir = "~/.local/share/archie" # NATS store, task logs
# The State Store's PostgreSQL connection (required; Postgres-only epic).
# The State Store's PostgreSQL connection (PostgreSQL 18, required).
# `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"
@@ -24,17 +24,12 @@ diff_cap_lines = 400
target = "127.0.0.1:8585"
# 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
# a matching target_token that archie-state-store validates -- start it with the
# same token (e.g. `archie-state-store ... -listen 172.17.0.1:9090 -token
# change-me-state-store-token`). For a host-only agent (no [containers]) use the
# loopback target 127.0.0.1:9090 with no token.
# archie-gateway dial it here and never open those tables themselves.
# This deployment runs the agent in containers, so the target is the Docker
# bridge gateway (172.17.0.1) the container can reach. A non-loopback address
# needs [tls]; see config.example.toml.
[services.state]
target = "172.17.0.1:9090"
target_token = "change-me-state-store-token"
[forge]
type = "github"
@@ -45,13 +40,6 @@ token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" }
trigger = "assignee" # "assignee", "label", or "either"
ack_reaction = "eyes" # Emoji reaction on issue pickup
[dispatch.labels]
queued = "archie:queued"
working = "archie:working"
waiting = "archie:waiting"
pr = "archie:pr"
parked = "archie:parked"
[models]
triage = "openai/gpt-6-luna"
planner = "openai/gpt-6-luna"
@@ -1,13 +1,20 @@
# ==============================================================================
# Self-Hosted Ollama + Standalone Mode Deployment Example
# Minimal event-driven deployment: no forge, no repositories
#
# Runs local open-weights models via Ollama (e.g. llama3, qwen2.5) with forge
# polling disabled (standalone execution mode).
# Events arrive as webhooks at the dashboard and run workflows. Models run
# locally through Ollama; for a hosted provider replace [providers.ollama] with
# e.g. [providers.openai] class = "openai", api_key_env = "OPENAI_API_KEY"
# and change the model names to "openai/<model>".
# ==============================================================================
# Standalone still needs a bot identity: it names the agent that chat turns and
# the session curator attribute memory to, and it becomes the seeded identity's
# display name when there is no [[identities]] block.
bot_user = "archie"
work_dir = "~/.local/share/archie/work"
state_dir = "~/.local/share/archie" # NATS store, task logs
# The State Store's PostgreSQL connection (required; Postgres-only epic).
# PostgreSQL 18 connection (required).
# `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"
@@ -16,7 +23,7 @@ database_url = "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable"
target = "127.0.0.1:8585"
# 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).
# archie-gateway dial it and never open those tables themselves.
# 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`.
+21 -45
View File
@@ -19,11 +19,10 @@ The Gateway unit is `archie-gateway.service`, written by `install.sh` beside
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
non-loopback bind fails closed without one:
config below) and never open the task tables themselves. A
host-only agent uses the loopback bind below; a container-mode agent needs the
Docker bridge gateway address, and a non-loopback bind needs `[tls]` (see
`config.example.toml`):
`install.sh` writes `archie-state-store.service` with that loopback bind.
@@ -35,65 +34,42 @@ The Telegram, email and webhook channels are served by `archie-messaging`, not
by `archied`, since the v1.30.0 extraction. `archied` starts no gateway for them
and logs nothing when one is absent, so a host that updates across v1.30.0
without this unit runs on with dead channels and a daemon that looks perfectly
healthy -- that was `archie-core-1c01`, found after two days of a silently dead
Telegram bot. `install.sh` writes this unit on a fresh install;
`scripts/archie-update-install` refuses an
healthy. `install.sh` writes this unit on a fresh install;
`archied update install` refuses an
update when a host is missing a unit and names what is missing, which now fires
for a host that drifted or predates this release rather than the normal path.
It dials the Gateway for the chat contract and the State Store for the stored
channel settings, and reads the same `config.toml`. Like `archie-ui` it resolves
`GATEWAY_TOKEN` and `STATE_STORE_TOKEN` from its process environment, hence the
`EnvironmentFile`:
channel settings, and reads the same `config.toml`, including `[tls]`.
`install.sh` writes `archie-messaging.service`, whose `After=` and `Wants=`
lines preserve that store-then-gateway order.
`install.sh` writes `archie-messaging.service`. Its `After=` and `Wants=`
lines only tidy the start sequence: nothing depends on that order, because
each service waits for the peers it needs.
## 2. UI Service Unit (`~/.config/systemd/user/archie-ui.service`)
The dashboard is served by the standalone UI Service, not by `archied`
(UI cutover, `archie-core-8cda.5.4`). It reads the same `config.toml`, dials
The dashboard is served by the standalone UI Service, not by `archied`. It reads the same `config.toml`, dials
the Gateway and State Store targets already in it, and binds `[web].listen`.
A non-loopback bind requires a dashboard token (`-token`, or `-token-file` to
mint and persist one);
Open the dashboard to configure the organisation, workspace and first administrator account.
Complete setup before exposing it publicly; remote access requires an HTTPS reverse proxy.
**Auth note (deliberate design, `archie-core-8cda.5.5`):** unlike `archied`,
`archie-ui` has no secret registry — it resolves `GATEWAY_TOKEN` and
`STATE_STORE_TOKEN` from its **process environment only** (or from the
`target_token` values in `config.toml`). Whatever starts `archie-ui` is
therefore responsible for exporting those tokens into its environment: keep
them in `~/.config/archie/env` (loaded by the `EnvironmentFile` line below),
not only in a secret manager. A deployment that authenticates `archied`
through bws/Vault but exports nothing for `archie-ui` leaves the dashboard
unable to dial its dependencies.
**Auth note:** `archie-ui` authenticates to the Gateway, State Store and
harness with its `[tls]` certificate (`archie-ui.pem`) from `config.toml`.
For supervision, `GET /healthz` on `[web].listen` is the process's liveness
probe (token-free by design); the authenticated readiness surface lives at
the dashboard's health endpoint behind the token. A watchdog can curl
the dashboard's health endpoint behind account authentication. A watchdog can curl
`/healthz` without credentials.
`install.sh` writes `archie-ui.service`. It has no secret registry of its own,
so its token handling is the `EnvironmentFile` note above.
Concretely, for a deployment whose dependency tokens live outside
`config.toml`, `~/.config/archie/env` carries the two names and the unit
loads it; the dashboard token itself comes from `-token-file` (there is no
environment variable for it):
```bash
# ~/.config/archie/env
GATEWAY_TOKEN=... # presented to archie-gateway
STATE_STORE_TOKEN=... # presented to archie-state-store
```
`install.sh` writes `archie-ui.service`. Browser accounts are configured through the dashboard.
`After=` orders the start, it does not wait for the store to bind. The UI
process closes that gap itself: its event pump retries priming with backoff
until the State Store answers, so the activity feed goes live once the store
is up rather than staying history-only until the next restart.
For a non-loopback bind, override the installed unit's `ExecStart` with
`-token-file %h/.local/share/archie/web-token` (or `-token`) in a drop-in rather
than editing the installer's copy in place.
For remote access, configure a TLS reverse proxy and the instance public URL in
Access → Authentication. Enrol passkeys from Your account on HTTPS or localhost.
---
@@ -193,8 +169,8 @@ fall back to a host model loop.
## 6. Pinning the archie-agent Image
`ghcr.io/samcharles93/archie-agent:latest` is a moving target: every push to
`main` that touches the runtime's package closure re-publishes it (see
`.github/workflows/deploy.yml`), so `latest` can change under a running
`main` that touches the runtime's package closure re-publishes it
(`.github/workflows/deploy.yml`), so `latest` can change under a running
deployment with no warning and no way to reproduce a prior build.
As of this writing, `archie-agent` has **no published semantic-version tag**
+12 -4
View File
@@ -31,7 +31,7 @@ services:
# classic location so the named volume keeps working across image updates.
PGDATA: /var/lib/postgresql/data/pgdata
ports:
- "5432:5432"
- "127.0.0.1:5432:5432"
volumes:
- pg_data:/var/lib/postgresql/data
restart: unless-stopped
@@ -44,10 +44,18 @@ services:
# ── NATS JetStream ────────────────────────────────────────────────
nats:
image: nats:2.14-alpine3.22
command: -js -m 8222
# The client port is published on every interface (agent containers reach
# it over the bridge), so it refuses to start without a token. Set
# NATS_TOKEN here and name the same value in [nats] token_env.
entrypoint:
- sh
- -c
- '[ -n "$$NATS_TOKEN" ] || { echo "NATS_TOKEN is required" >&2; exit 1; }; exec nats-server -js -m 8222 --auth "$$NATS_TOKEN"'
environment:
NATS_TOKEN: ${NATS_TOKEN:-}
ports:
- "4222:4222" # client
- "8222:8222" # monitoring (http://localhost:8222)
- "127.0.0.1:8222:8222" # monitoring (http://localhost:8222)
volumes:
- nats_data:/data
restart: unless-stopped
@@ -85,7 +93,7 @@ services:
# ── example agent profile image ─────────────────────────────────────
# The agent image plus network lookup tools, for a workflow that names
# `profile: network-investigator` (examples/workflows/firewall-investigate.yaml).
# `profile: network-investigator` (archipelago: workflows/firewall).
# 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:
-100
View File
@@ -1,100 +0,0 @@
# Adversarial self-review
> **Removed, not shipped (2026-09-28, `d73e0748`). This page records a system
> that no longer exists in the tree.**
>
> `d73e0748` ("remove the superseded adversarial-self-review system") deleted the
> stage and its contract: `workflow.Reviewer`, `ReviewRequest`, `ReviewReport`
> and `StageReview` are gone from `internal/domain/workflow`, so everything under
> "Contract" below describes types that cannot be found.
>
> The authority is `docs/prds/pr-review-agent.md`, which says so itself: it
> "supersedes the reviewer executor and blocking rule in
> `docs/architecture/adversarial-review.md`". archied now runs its PR review
> pipeline before it opens a pull request; there is no separate adversarial
> self-review pass and no `repo.review_enabled` setting.
>
> The page is kept rather than deleted because PRDs link to it
> (`docs/prds/adversarial-self-review.md`, `docs/prds/inline-review.md`,
> `docs/prds/pr-review-agent.md`). Read it as history.
>
> One section is stale in a second, older way: "Operator-triggered review" below
> describes the synchronous `review_pr` (fetch the head, snapshot it, run the
> reviewer, return findings), which `archie-core-afbk.14` replaced with a queued
> pr-review task.
Archie ran a fresh adversarial review of the diff before it opened a pull
request, so a PR arrives with a findings record rather than an unreviewed
claim. The reviewer provably cannot see the implementer's context: it reviews a
`.git`-free snapshot of the committed tree, not the worktree, the commit
history, or the implementer's transcript.
Promoted from `docs/prds/adversarial-self-review.md` (the design decision;
`archie-core-h019`). Describes the stage as shipped.
## Contract (`internal/domain/workflow`)
The workflow domain owns the contract and the blocking decision; it never names
the executor.
- `Reviewer.Review(ctx, ReviewRequest) ReviewReport` — the interface the
workflow stage consumes.
- `ReviewRequest` is the reviewer's entire input: `SnapshotDir` (a `.git`-free
export of the reviewed commit), `Diff` (base...head), `IssueText` (the
originating issue title/body), and `MaxSteps`.
- `ReviewFinding` / `ReviewReport` are the structured result. The load-bearing
rule is `Blocking() == (Verdict == confirmed && Level == error)`: only a
confirmed error-level finding blocks; a plausible finding never blocks
however severe it claims to be.
`ReviewReport` distinguishes `not_run`, `skipped`, and `completed` (zero
findings) structurally, so "ran and found nothing" is not the same as "never
ran" — collapsing them would make an outage indistinguishable from a clean
review.
## Execution (`internal/app/agentworker`)
The executor is an ai-sdk `agent.Subagent`: a nested synchronous generation in
the same worker process, with its own model, system prompt, toolset and step
budget.
- **Conversation isolation is structural.** `Subagent.Run` sends only a prompt
string, never the implementer's message history.
- **Workspace isolation is the `.git`-free snapshot.** The reviewer's toolset is
read-only (`read`, `grep`, `find`) and rooted at `SnapshotDir` — never the
worker's own toolset, which carries the `worktreerpc` publication grant.
- **Findings return through a typed capture tool** (`record_finding`), validated
on the way in, so the reviewer reports through the contract rather than free
text the caller regexes.
- **Fail-closed.** A reviewer that errors, truncates, or reaches no conclusion
yields `ReviewStatusNotRun`, which the stage treats as a park — never a silent
"PR opened unreviewed".
## Lifecycle effect
`StageReview` runs in the implement workflow after the deterministic gates and
before `StageOpenPR`, gated by `repo.review_enabled` (opt-in, default off). A
surviving blocking finding — or a review that failed to run — parks the task
(`StatusParked`, not `waiting_human`) with the findings rendered into the park
reason; `StageOpenPR` never runs. Warn/plausible findings and the zero-finding
case leave the outcome unset, so the PR opens with a findings section rendered
onto its body. `StagePostReviewComments` then runs after `StageOpenPR` and posts
the **line-anchored** findings as inline review comments, carrying a one-click
suggestion on a confirmed finding the reviewer could state a fix for. That stage
is best-effort — a comment that fails to post is logged, never a park — because
the body section already lists every finding, and it is the record a whole-file
finding (no line to anchor to) only ever appears in.
## Model and budget
The reviewer model is `models.reviewer`, falling back to `models.builder`.
Effort is the per-stage `MaxSteps` budget, mapped onto `Subagent.MaxSteps`
(default 10).
## Operator-triggered review
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. Authorisation is identity-scoped
to the operator's configured repositories; duplicate or concurrent reviews of
the same PR are deduplicated.
-389
View File
@@ -1,389 +0,0 @@
# Agent System
**Status:** Current-state investigation in progress
**Date:** 2026-07-28
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
## Domain framing
The domain is the Agent System.
`Task` is not a core Agent System concept. Forge tasks, forge issues, Jira
issues, email, Telegram messages, webhooks, and future external inputs are
channel-specific messages. Channels translate those messages into requests to
the Agent System; external issue or task models MUST NOT shape execution state.
The current `store.Task` is a persisted workflow execution. Treating that row as
a task-domain aggregate would incorrectly turn Archie into an agentic issue
board.
## Canonical agent interaction model
An **Agent** is a persistent assistant selected for an interaction. It is not a
model invocation and is not a WorkflowExecution.
Each Agent has its own:
- immutable acting `IdentityID` for ownership and audit;
- durable memory and learned information about the user;
- perspective, specialisation, instructions, and communication behaviour;
- conversation history and channel bindings;
- available tools, capabilities, and policy;
- continuity across model or provider changes.
The underlying model is a replaceable runtime dependency. Changing a model,
provider, or model version MUST NOT create a new Agent, discard its memory, or
change ownership of its history.
A user MAY create multiple Agents. Each Agent develops its own memory and view
of the user from the interactions and responsibilities assigned to it. Memories
MUST NOT be silently pooled merely because Agents belong to the same user or
application.
Agent and Identity are separate aggregates. Every Agent references exactly one
acting IdentityID, and no two Agents share an agent identity. User, system, and
service-account identities may exist without an Agent.
An action initiated through an Agent records the Agent's acting IdentityID and,
when applicable, the initiating user's IdentityID. A future fully automated
WorkflowExecution MAY use an explicitly selected service-account identity for a
concrete unattended use case; this is not the default execution identity.
## Workflow execution identity
A Workflow is owned by an IdentityID. By default, every WorkflowExecution acts
as the Workflow owner's identity.
Future delegated execution MAY add an explicit `RunAsIdentityID` assignment to a
Workflow. This allows a Workflow owner to select another user or service-account
identity for execution without changing Workflow ownership. Until that
capability is deliberately introduced, owner identity and execution identity are
the same.
WorkflowExecution audit records MUST preserve the Workflow owner, effective
execution identity, initiating user when one exists, and any explicit delegation
that selected a different run-as identity.
## Memory scopes
The Agent System requires four distinct durable memory scopes:
- **global shared memory**: information intentionally available across the
Archie application;
- **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
authorised Agents serving that user;
- **Agent-user relationship memory**: private history and learned context from
one particular Agent's relationship with one particular user.
Agent-wide memory is private to its owning Agent by default. Another Agent MUST
NOT read, inherit, search, or mutate it implicitly.
Agent-user relationship memory is addressed by both AgentID and User IdentityID.
Neither another Agent serving the same user nor another user speaking to the
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 personalisation boundary,
not merely an attribution tag on the primary user's records.
An Agent MUST resolve the initiating user before assembling memory context.
Memory belonging to one user MUST NOT become visible to another user merely
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 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.
An Agent interaction may answer conversationally, use a tool or capability, read
or send messages, retain information, or propose durable workflow-backed work.
None of these operations inherently requires a WorkflowExecution.
## Agent and Workflow domain boundary
Agent and Workflow are separate domains:
```text
internal/domain/agent
internal/domain/workflow
```
The Agent domain owns persistent assistants, their specialisation, instructions,
model-independent continuity, capability context, and associations with identity
and memory.
The Workflow domain owns reusable, user- or Agent-defined behaviour and every
durable execution of that behaviour. An Agent may invoke or define a Workflow,
but the Workflow is not part of the Agent aggregate and does not require a
conversational Agent interaction to execute.
## Canonical workflow model
The Workflow feature uses these canonical terms:
- **Workflow**: a reusable, versioned definition of how an agent behaves and
performs a kind of work.
- **WorkflowExecution**: one durable execution of a specific Workflow version.
- **WorkflowStep**: one defined operation in a Workflow.
- **StepExecution**: the recorded execution and outcome of one WorkflowStep.
- **Attempt**: a retry of the same WorkflowExecution, not a new execution.
A Workflow MAY structure any repeatable agent behaviour, including personal
assistance and scheduled routines. For example, a morning email review may
combine a schedule event, message retrieval tool, LLM classification and
summarisation, and delivery of the resulting rundown. Workflow is therefore not
restricted to forge work, source changes, or requests submitted by a user at
execution time.
Workflows are extensible through Workflow-owned plugins. The Workflow domain
defines the typed plugin registration, definition, validation, versioning, and
execution contracts. Users and Agents may define reusable Workflows through
those contracts.
The generic plugin contract remains metadata-only. It MUST NOT own Workflow
semantics or replace the Workflow registry with generic hooks.
`Workflow` and `WorkflowExecution` are the names used in architecture, generated
reference, configuration, commands, events, and external contracts. The
implementation MAY use package qualification to remain concise:
```go
workflow.Definition
workflow.Execution
workflow.Step
workflow.StepExecution
```
The unqualified name `Execution` MUST NOT be used in cross-domain contracts or
documentation because it is ambiguous among workflow, tool, command, policy, and
service execution.
## Current workflow-execution feature
The current feature takes a channel request through agent execution and a
durable outcome.
Current execution state includes source-message references, owning identity,
repository, selected workflow and stage, agent output, branch and pull-request
references, token and iteration counts, retry information, human-wait
information, and failure details.
The current `store.Task` lifecycle uses:
```text
queued -> running
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
```
`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
`archie-agent` container, which owns the workflow stage loop.
## Current workflow-feature placement
The behaviour is divided across technical packages:
- `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
outcomes, parks failures, and performs forge/worktree operations.
- `internal/agentexec` defines and runs individual autonomous-stage protocols.
- `internal/taskrun` hands a complete WorkflowExecution to a container worker.
- `internal/gate` and repository configuration define execution constraints.
- `internal/gateway` duplicates task status strings and applies task-control
rules.
- forge, worktree, NATS, PostgreSQL, containers, and agent runtimes are concrete
dependencies mixed into orchestration.
## Current `task` meanings and required replacements
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 `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 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
- The `task` command in `Taskfile.yml` is the external Task build tool and keeps
its name.
- A forge may call its own records issues or tasks inside its channel adapter.
- General prose may use “task” informally only when it clearly refers to an
external system. Agent System contracts and generated reference MUST use the
canonical Workflow vocabulary.
## Current WorkflowExecution data inventory
This inventory is the migration ledger for data currently spread across
`store.Task`, database-only columns, `workflow.TaskContext`, worker messages,
and surrounding configuration. Implementation SHOULD NOT require another
repository-wide search to determine what existing execution data must be
preserved or deliberately removed.
| Current data | Current representation | Required target |
| ---------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Execution identity | `Task.ID`, `task_id`, NATS subjects, logs | Immutable WorkflowExecutionID used consistently by state, events, workers, projections, and capability calls |
| Owning actor | `Task.Identity` string | Canonical IdentityID |
| Source type | `Task.Source` (`forge` or `chat`) | Typed channel and SourceMessageReference; no closed source enum in WorkflowExecution |
| Source address | `Owner`, `Repo`, `IssueNumber`; synthetic chat issue number | Channel-owned source reference with native message/thread/object identifiers; synthetic identifiers removed |
| Requested work | `Title`, `Body`, `Labels` | Immutable execution input captured from the source request; channel-specific metadata retained in the source envelope |
| Workflow selection | `Workflow` string | Immutable WorkflowID plus selected WorkflowVersion |
| Lifecycle | `Status` string | Enforced WorkflowExecution state |
| Current position | mutable `Stage` string | Derived current WorkflowStep reference plus durable StepExecution history |
| Attempts | `Attempt`, `RetryCount` | Execution attempt history and retry-policy evidence; distinguish worker delivery retry from workflow retry |
| Failure | `ParkReason`, transition detail, response errors | Typed failure classification, evidence, retryability, and resulting lifecycle event |
| Human wait | `WatchCommentID`, `waiting_human` | Channel-neutral wait condition and correlation reference; forge comment IDs stay in the forge channel |
| Workspace | `Dir`, `Branch`, worktree path, `task.json` | Execution workspace reference and independently managed workspace lifecycle |
| Change outcome | `BuildSummary`, `BuildNoChanges`, changed files | Step outputs and final WorkflowExecution outcome |
| Reproduction evidence | `ReproProof` | Typed TDD step evidence retained with the StepExecution and final outcome |
| Planning output | `Plan` | Typed step output referenced by later steps rather than a special aggregate field |
| Notes | `Notes`, appended agent notes | Ordered execution annotations with actor, source step, and timestamp |
| Pull request | `PRNumber`, forge host/repository assumptions | Forge-channel delivery reference and reconciliation state |
| Agent usage | `TokensUsed`, `Iterations` | StepExecution usage measurements aggregated into execution projections |
| Decision capture | private feasibility `decision`, capture-tool output | Typed WorkflowStep output defined by that Workflow version |
| Terminal outcome | mutable `Outcome{Status, Detail}` | Explicit WorkflowExecution outcome command/event validated by the state machine |
| Skill context | `SkillBody`, `SkillPlugins` | Resolved Workflow version dependencies or execution inputs, with provenance |
| Agent prompt context | `SystemPrompt`, `ExtraRules`, mission strings | Versioned WorkflowStep definition plus resolved execution context; mutable global prompt callbacks 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 |
| Transition history | SQL `transitions` and generic events | Authoritative WorkflowExecution domain events stored atomically with state |
## Current runtime responsibilities to unify
The following behaviours currently act on the same WorkflowExecution but are
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;
- 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;
- enforce gates, budgets, protected paths, tool constraints, and result review;
- persist state and StepExecution outputs;
- publish authoritative lifecycle events;
- wait for channel input and resume;
- classify failure, retry, park, mark exhausted, cancel, or recover after crash;
- deliver and reconcile forge changes;
- project status, history, counts, and audit for channels and the web UI;
- hand execution to a worker without moving domain ownership to the worker.
## Current workflow-feature hazards
- State update and transition-history insertion are separate operations, so
state and audit can diverge.
- Callers frequently discard persistence and transition errors.
- Gateway task control duplicates lifecycle status constants by hand.
- `workflow.TaskContext` is a mutable service bag containing complete
configuration plus forge, store, worktree, agent, event bus, logging, memory,
guardrails, skills, and scratch state.
- Lifecycle changes occur in both daemon and workflow code.
- Workflow orchestration runs inside task-scoped agent containers while the
daemon retains lifecycle, admission, and authority-bearing RPC ownership.
- Forge-backed and chat-created work share one record through source flags and
synthetic issue numbers.
- Repository labels currently select workflows and mirror task state, coupling
domain transitions to forge presentation.
- Failure generally becomes `parked`, and the failure's classification is no
longer implicit: the persisted execution record carries the class the code
that parks recorded (the vocabulary lives in `internal/taskstate`), and
retryability is read from it rather than inferred from reason text.
- Generic observability events are emitted alongside state changes rather than
being the authoritative domain events.
## Existing invariants to preserve
- The model never performs git operations directly.
- Deterministic policy and gates cannot be waived by the agent.
- TDD captures a failing reproduction before implementation and protects the
test during the fix.
- Every run ends in an explicit outcome; definition errors and stage errors do
not disappear silently.
- Crash recovery requeues interrupted work.
- Agent execution crosses a versioned data boundary.
- Forge, persistence, workspace, transport, container, and model runtimes remain
replaceable infrastructure.
- Work from the same repository is serialised by default.
## Required migration
- Rename the current persisted `store.Task` concept to WorkflowExecution.
- Replace task lifecycle terminology in core commands, events, persistence,
worker contracts, logs, and generated reference.
- Preserve external source terminology only inside its channel adapter.
- Replace synthetic issue numbers with explicit source-message references.
- Associate every WorkflowExecution with an immutable Workflow identifier and
version.
- Record StepExecutions explicitly rather than treating one mutable `stage`
field as complete execution history.
- Keep Attempt as retry state within the same WorkflowExecution.
## Curator isolation invariant
Decided 2026-08-05
([#435](https://github.com/samcharles93/archie-core/issues/435) epic,
[#98](https://github.com/samcharles93/archie-core/issues/98) runtime).
Recovered 2026-08-09 from the pre-migration issue tracker.
**Curators are peers, not dependencies.** They must never block, delay, or take
down chat turns, agent runs, or the daemon.
1. Registry-owned goroutines, one per curator, with per-pass `recover()`,
per-pass budgets (max steps, tokens, timeout), and a configurable maximum of
concurrent passes (default 1) so curators cannot saturate the shared LLM
runtime against chat.
2. Wake events ride the in-process `events.Bus`, which is mutex fan-out with
bounded per-subscriber buffers that **drop** on overflow
(`internal/events/events.go`). A slow curator can never backpressure the chat
publisher.
3. Wake is a best-effort nudge. The trigger is a deterministic read of persisted
primary-input state at pass time, so a dropped wake only delays a run to the
next check-in and never corrupts trigger accounting
([#22](https://github.com/samcharles93/archie-core/issues/22)).
4. The curator registry lifecycle is independent of the agent loop. Daemon
shutdown cancels in-flight passes and waits bounded.
Chat turns keep their per-session lanes; agent runs keep their workflow
goroutines and containers. Rule of thumb: **no code path a curator executes may
ever appear on a chat turn's critical path.**
-195
View File
@@ -1,195 +0,0 @@
# Playbook bindings: model and threat model
**Status:** Approved foundation (documents shipped code: `archie-core-t2db.1`
through `.5`, `.7`, `.9`-`.15`)
**Date:** 2026-09-03
This document covers the binding model and the intake threat model portion
of `archie-core-t2db.6`. It does not cover the task-lifecycle provenance rule
(`messaging-and-work-intake.md`'s "Intake provenance") or the operator
walkthrough -- that walkthrough remains an open piece of the same ticket.
## What a binding is
A `binding` (`internal/domain/binding.Binding`) ties four things together:
a **matcher** (which captured events it applies to), a **mapping**
(`internal/domain/mapping.Mapping`, how fields are pulled out of a payload),
a **workflow** (which registered workflow runs on a match), and a **state
machine** governing whether it is live.
```go
type Binding struct {
ID, Name // identity
Matcher // { Source string } -- the webhook path segment, e.g. "sentry"
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 // pending_approval | armed
Secret // HMAC-SHA256 shared secret, encrypted at rest, never returned by GET
}
```
Bindings live in the store (PostgreSQL), not `config.toml` -- operators author
them from the dashboard while the daemon runs, without a restart.
### Matching
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. 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
`Version` increments on every `UpdateBinding` call. This exists so an
editor's later change can never silently rewrite the historical provenance
of a task that already fired -- a dispatched task's binding reference is
pinned to the version that was armed when it fired, not "whatever the
binding currently says."
### State machine
```
create ---> pending_approval ---> armed
^ |
+----------------+
(any edit to an armed binding drops it back to pending_approval)
```
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`); 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.
## The threat model
This is a public, unauthenticated-by-default intake surface whose output is
an agent with a repo, a worktree, and tool access. The design brief
(`archie-core-t2db.5`, `docs/prds/webhook-intake-security.md`) named five
non-negotiables; each is verified below against the actual shipped code,
not the design intent.
### 1. Per-source authentication
Reuses `internal/channels/webhook`'s existing HMAC-SHA256 scheme --
capture accepts unsigned events (visible in the dashboard, marked
unauthenticated), but **only authenticated events can ever match a
binding**. `binding.Matches`' doc comment states this plainly: "an
unauthenticated event can never trigger a binding, no matter how well it
would otherwise match." Enforced structurally at two points, not just
convention:
- `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.
### 2. Human approval before a binding goes live
Covered by the state machine above. Nothing self-arms: `pending_approval ->
armed` requires an explicit `Approve` call, and any edit to an armed
binding reverts it.
### 3. Rate and volume limits per source
Capture writes are bounded independently of the approval gate, so a flood
of unauthenticated traffic cannot exhaust disk or drown the inspector:
`InsertCapture` (`internal/infrastructure/postgres/edastore.go`) prunes by both **retention
window** (`WHERE received_at < cutoff`) and **max event count** in the same
insert transaction.
### 4. Blast radius bounded by the same code-level controls every task gets
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/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
`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
trusted instruction (Archie's environmental-enforcement principle: "the
agent should ignore instructions in the payload" is not itself a control,
the surrounding sandbox is).
### 5. Captured payloads may contain secrets from the sending system
Two independent protections, not one:
- **Redaction before persistence**: `webhookguard.RedactPayload` walks the
decoded JSON and redacts recognised sensitive keys before the row is
written -- the raw, unredacted payload is never durably stored.
- **Retention**: a configurable window (`InsertCapture`'s `retention`
parameter) prunes old captures automatically; visibility of what remains
is gated by the same dashboard authentication as every other webui
surface, not a separate, weaker path.
### Secrets at rest
`Binding.Secret` (the HMAC shared secret a sender signs with) is encrypted
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
cannot be relocated to another field/column and still authenticate. A `nil`
cipher (no encryption key configured) leaves secrets as plaintext --
documented legacy behaviour, not silent degradation.
### At-most-once dispatch
`dispatchBindings` enqueues at most one task per `(binding, capture)` pair,
enforced by a real ledger, not best-effort application logic:
`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
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 (`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).
## What this document does not cover
- An end-to-end operator walkthrough (point an external app at archie,
build a first playbook) -- open, part of `archie-core-t2db.6`.
- The playbook YAML / CEL / Module/Channel/Forge action-position work
(`docs/prds/eda-playbook-engine.md`, `module-position.md`,
`channel-forge-positions.md`) -- a different, newer mechanism than the
binding model described here; the two are related but not the same
system, and this document does not attempt to unify them.
-435
View File
@@ -1,435 +0,0 @@
# Configuration
**Status:** Approved; existing-type assignment is ongoing
**Date:** 2026-07-28
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
## Ownership
Configuration has two separate responsibilities:
1. `internal/infrastructure/configuration` loads files, environment variables,
secret references, overlays, and compatibility representations.
2. Each domain and plugin owns the typed runtime settings required for its
behaviour.
`internal/app` translates external input into those settings, validates
cross-capability combinations, and supplies each component only its own
settings.
The following are prohibited:
- passing complete application configuration into a domain;
- making a domain depend on TOML, YAML, environment-variable names, secret
references, or a configuration library;
- defining a central runtime configuration type imported across the system;
- placing plugin options in an unrelated global configuration model.
## Private input document
`internal/infrastructure/configuration` MAY use a complete decoded document
while discovering files, decoding sections, and applying overlays. It is an
input-boundary DTO only.
The document:
- remains private to the configuration infrastructure;
- is composed from separately defined feature sections;
- is immediately translated by application composition;
- is never returned as the application's runtime model;
- is never passed through runtime components.
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 recognised filename for every
plugin.
Invalid configuration input MUST NOT replace active valid settings or terminate
unaffected capabilities. Configuration changes use the candidate validation,
promotion, audit, and recovery requirements in
[safe-change-and-recovery.md](safe-change-and-recovery.md).
## Dissolution of `internal/config`
`internal/config` has no target location. It MUST be dissolved and MUST NOT
survive as a shared package, configuration domain, or renamed global model.
Its loading behaviour moves to `internal/infrastructure/configuration`. Existing
types and methods are reassigned by behaviour. Repository execution policy,
dispatch policy, retry policy, ecosystem defaults, tool policy, memory settings,
provider settings, and channel settings move to their
respective owners.
## Repository settings
The existing `config.Repo` MUST NOT move intact into a repository domain or
shared settings package. A managed repository is an application association:
- work intake owns which repository references an identity monitors;
- task execution owns gates, preflight, test protection, ecosystem behaviour,
and change limits;
- task lifecycle owns retry behaviour;
- scheduling owns concurrency policy;
- workspace management owns base branch and persistent-storage requirements.
Application composition correlates these settings by repository reference. No
domain receives a universal repository profile.
## Documentation
Generated configuration reference describes external sections and their owning
capabilities. It MUST NOT establish a global Go configuration structure as the
public contract.
## Value classification rule
Every value that controls behaviour MUST have an explicit owner and MUST be
classified as exactly one of:
1. **Invariant** — changing it changes the meaning of the program, a wire
protocol, or a domain concept. It may be a Go constant.
2. **Runtime setting** — an operator, identity, domain, plugin, or deployment
may legitimately choose a different value. It is typed configuration owned by
the affected capability.
3. **Policy value** — it expresses what is allowed, limited, routed, retried,
protected, or gated. Its typed definition belongs to the owning domain and it
is evaluated through the policy system.
4. **Derived value** — it is computed from other settings and is not
independently mutable.
5. **Runtime state** — it changes as the application operates, such as the
active model for a conversation. It is changed by a domain command and is not
configuration merely because it can be changed.
An unclassified behavioural literal is a defect.
`const` MUST NOT be used merely because a value currently has one default.
Constants are reserved for actual invariants: enum discriminants, protocol
versions, fixed compatibility tokens, and values whose alteration would change
the program's semantics rather than configure an installation.
In Go, a constant is a compile-time value and does not represent mutable runtime
storage. It generally has no address that can be observed or changed.
Architecturally, a constant therefore asserts that the value cannot change for
the lifetime of the application. Any value that may legitimately change while
the application is running, between application instances, or between
deployments is not a constant.
A runtime setting may have a default, but the default is not its only access
path. The owner exposes a typed settings structure, validation, and a
`DefaultSettings` constructor or equivalent. Private constants used to implement
defaults do not turn those defaults into invariants and MUST NOT be consumed
directly by runtime code.
Each runtime setting and policy value MUST declare:
- its owner;
- type, units, validation constraints, and safe bounds;
- default and derivation, if any;
- whether it is startup-only, live-reloadable, or restart-required;
- whether it may differ by installation, identity, repository, workflow,
channel, or plugin instance;
- whether it is secret, sensitive, or safe to report;
- its current source, effective value, version, and last-known-good version;
- the command and identity required to change it.
## Current configuration migration ledger
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`, `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
The following current values affect useful behaviour but are not represented as
owned typed settings or policy. They MUST be classified and migrated before the
old configuration package is removed. The listed target is the architectural
decision; exact setting names are implementation details.
| Capability | Values fixed in current code | Required classification |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Chat agent | maximum steps `8` in `cmd/archied` | Workflow/chat execution policy. |
| Context compression | enabled, threshold `0.5`, context size `128000`, protect first `3` and last `20`, compression marker, token estimate of four characters per token | Model/context runtime settings. The marker is presentation; the estimate is provider/model strategy, not a universal truth. |
| Tool guardrails | escalation thresholds `3`, `5`, `10`, `2` | Tool-use policy with named meanings and bounded defaults. |
| Tool output | per-result cap `50000` characters, no aggregate turn cap, preview `500` characters | Tool-execution resource and presentation settings. Per-result spill/truncation remains; turn continuation is not character- or token-gated. |
| Pairing/access | code TTL `1h`, maximum pending `3`, rate window `10m`, failures `5`, lockout `1h`, maximum lockout `24h` | Access policy. Code length/alphabet and salt length require an explicit security-constraint decision; they are not automatically valid constants. |
| NATS daemon consumer | stream `ARCHIE_TASKS`, consumer `archie-daemon`, deduplication `2m`, poll `2s`, deliveries `3`, acknowledgement wait `5m`, inactive threshold `24h`, subjects | NATS topology settings plus delivery policy. Subject grammar or protocol headers may be invariants only if declared as versioned wire contracts. |
| NATS worker consumer | stream `ARCHIE_TASKS`, consumer `archie-agent`, deduplication `2m`, poll `5s`, acknowledgement wait `30m`, deliveries `3`, inactive threshold `24h`, queue group and retry delay `1s` | Worker transport settings and delivery/retry policy. Shared stream defaults must have one owner rather than two copies. |
| 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 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. |
| Message framing | MCP frame `4MiB`, worker protocol frame `8MiB`, diagnostic `64KiB`, media/base64 `64MiB` | Resource/security policy unless a published wire protocol mandates the limit. Limits must be configurable only within safe bounds. |
| Webhooks and web UI | webhook bind `0.0.0.0:8644`, webhook shutdown `5s`, web read-header `5s`, web shutdown `2s` | Transport instance and lifecycle settings. |
| Telegram | typing refresh `4s`, draft interval `700ms`, update-action TTL `10m` | Telegram adapter presentation and lifecycle settings. |
| Telegram limits | message length `4000` and callback/update prefixes | Record the upstream platform constraint and version it as an adapter compatibility limit; prefixes may remain wire constants when changing them would invalidate outstanding callbacks. |
| Containers | stop and pull timeouts `10s` and `30s` | Container lifecycle policy. |
| 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. |
| 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. |
This inventory is intentionally broader than exported Go `const` declarations. A
literal hidden in a constructor, timeout, switch, retry loop, path join, prompt,
label map, or client setup restricts behaviour just as effectively as an
incorrectly used constant.
## Constants that may remain
A value may remain constant only when its owner documents why runtime variation
would be invalid. Typical valid cases are:
- domain enum values and state names;
- a versioned wire-protocol version or framing token;
- reserved internal headers and callback prefixes that peers must interpret
identically;
- compile-time mathematical relationships;
- sentinel errors and internal type identifiers.
Names such as a stream, consumer, label, workflow, file, directory, network,
model role, timeout, retry count, capacity, size limit, colour, prompt, command,
or executable are not invariants merely because the current application has only
one of them.
Architecture tests SHOULD reject exported behavioural constants outside approved
invariant packages and SHOULD detect direct consumption of private default
constants outside their owning `DefaultSettings` construction.
## Current mutation and reload ledger
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. |
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.
## Universal change protocol
Changing configuration is an application command performed by an identity. It
MUST:
1. resolve the target owner and current version;
2. parse into that owner's typed settings;
3. validate syntax, semantic constraints, policy, references, and safe bounds;
4. stage a candidate without altering the active value;
5. run owner-defined readiness and health checks;
6. atomically promote the candidate and record actor, source, reason, diff,
prior version, and new version;
7. observe the affected capability for a bounded period;
8. retain the new version on success, or automatically restore last-known-good
on failure;
9. report the rejected or rolled-back candidate without terminating unaffected
capabilities.
Startup loading uses the same candidate rules. A bad user value therefore does
not partially mutate the application or make a previously healthy capability
unavailable.
Settings that cannot safely reload in-process are marked restart-required. The
change may still be validated and versioned immediately, but promotion occurs
through a controlled restart with the same health and rollback semantics.
## Implemented runtime reload and settings writes (2026-09)
Two mechanisms change behavioural values at runtime: SIGHUP re-reads the file
config, and the control plane owns every database-backed setting. The dashboard
runtime overlay that used to sit between them was deleted once the control plane
covered its surface; `-config-overlay` names a file overlay and is unrelated.
### Published snapshot: `config.Holder`
The running configuration is a published snapshot held in `config.Holder`
(`internal/config/holder.go`). Get returns a value under RLock; Set replaces the
whole snapshot. A published Config is immutable: reload constructs a fresh one
and calls Set. `config.Clone` deep-copies every reference-type field so a failed
decode cannot mutate the published snapshot's shared maps. `Holder.Get` panics
on a nil receiver — a forgotten `NewHolder` must fail loudly, not boot a daemon
that silently runs on an empty config.
### The reloadable-field criterion
The diff-and-warn on reload asks whether a changed field takes effect without a
restart. The criterion is: **a field is reloadable when every consumer re-reads
it.** That question read as "what does the daemon re-read" while the daemon owned
the only Holder; it stopped being sufficient when webui began sharing that
Holder, because webui handlers re-read on every request. The allowlist lives in
`cmd/archied/reload.go` and is deliberately a deny-by-default list: a field added
to Config later defaults to requires-restart, forcing whoever adds it to decide
deliberately. A reload that changes any non-allowlisted field logs
"requires a restart" with the field names; a fully-applied reload logs Info.
### SIGHUP reload
SIGHUP re-resolves the file config, re-applies the database layer over it
(`boot.runtimeConfig`, the same call boot makes), validates, and atomically
republishes through the shared Holder. A failed reload keeps the running config
and records `last_error`/`last_error_at` in `/api/config` so the stale state is
visible where the operator is looking. The three poll tickers re-read
`PollInterval` per iteration and reset on change, so a reloaded interval
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: 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.
Two properties matter to anyone changing this area:
- **Bootstrap stays file-owned.** The daemon reads the file config first and
layers database resources over it at boot (`boot.loadRuntimeConfig`). Values
the daemon needs before it can reach the State Store — the database path,
listen addresses, credentials — stay file-only by design.
- **Reload re-reads them.** SIGHUP resolves the file document and then runs the
same `boot.runtimeConfig` layering boot does, so a reload cannot revert a
database-owned setting to its file value. A control plane that cannot answer
fails the reload rather than publishing the file's values over the running
ones. Workflow execution budgets arrive on a watch rather than in a resource
query, so boot records the last published settings and the reload re-applies
them from there.
- **Live kinds arrive on a watch.** Provider settings, model role assignments,
repository policies, scheduling policy, tool settings, plugin settings,
review settings, channel settings and container runtime policies are
`ApplyMode: live`: the daemon keeps a watch per kind
(`boot.startRuntimeResourceWatches`, `runtimeResourceKinds`) and, on a new
version, re-runs `boot.runtimeConfig` over the published snapshot and
republishes through `config.Holder`. A candidate the layered document cannot
run is refused before it is published — last-known-good keeps running and
the refusal is reported through apply status. Tool settings reconcile in this
process: the daemon diffs the stored MCP server set against the running
providers — connecting added servers, disconnecting removed ones and
reconnecting changed ones while an unchanged server keeps running — and
rebuilds the `web_fetch` and `minimax` entries, whose config was captured at
construction (`boot.reconcileToolSettings`). Container runtime policies
join the live set because their consumers re-read the published config: the
container pool reads image, pull policy, network, max uptime and concurrency
cap on every acquire and the daemon resizes its running task dispatcher from
the same publish; the fields the document cannot carry, `registry_auth`
above all, stay boot-resolved and remain requires-restart. A kind whose
consumer lives in another process reconciles there too: `archie-messaging`
re-reads the stored channel settings on the apply-status restamp interval
and restarts only the channel whose transport settings changed, while the
listen addresses it has bound and the set of channels it composed stay
process bindings that take effect on restart. A kind joins the live list
only with a consumer that re-reads it; one whose startup-built consumer
never does stays restart-required, and the model/provider half of the live
set also rebuilds the gateway chat runtime's provider set and the chat model
list the chat surfaces offer.
## Completion criteria
The configuration rearchitecture is complete only when:
- `internal/config` no longer exists;
- every behavioural value has one classification and owner;
- every current field and hard-coded value in the ledgers has a recorded
disposition;
- domains and plugins receive only their typed settings;
- all changes use semantic commands and the universal change protocol;
- active, candidate, rejected, rolled-back, and last-known-good versions are
queryable with secret-safe provenance;
- generated documentation lists every external key, default, constraint,
mutability class, owner, and deprecation;
- architecture tests prevent a new central runtime configuration model, direct
live-setting mutation, and incorrectly fixed behavioural values.
## Startup policy: missing credential degrades, invalid config is fatal
Decided 2026-07-30. Recovered 2026-08-09 from the pre-migration issue tracker.
A missing **credential** disables a capability. Only an **invalid config** stops
the daemon. "Forge is a feature, not a requirement."
Before `518a1a0`, an unresolvable forge token did `return 1` in
`cmd/archied/main.go`, so a chat-only user who never configured GitHub got no
chat, no gateway, nothing — and under a systemd unit with `Restart=on-failure`
and no start limit it crash-looped every five seconds with the error scrolling
past unread. Forge construction now lives in `resolveForge`, shared by the
primary forge and every configured identity, and degrades to `forge.NewNoop`
with a warning. The identity path had the same defect and was worse: one
identity's missing credential killed all the others.
Malformed configuration still fails fast in `configuration.Validate`, well
before this point. That distinction is the whole design.
Apply the same reasoning to any future capability credential, LLM keys
especially: start, report the capability as unavailable, let the operator see it.
Guarded by `TestResolveForgeDegradesInsteadOfFailing`.
**Known consequence, tracked separately:** `worktree.Manager` still receives the
empty token, so pushes fail late rather than at startup.
## Config generation belongs to `archied setup`, not `install.sh`
Decided 2026-07-30 ([#368](https://github.com/samcharles93/archie-core/issues/368)).
Recovered 2026-08-09 from the pre-migration issue tracker.
`install.sh` must stop generating `config.toml`; `archied setup` owns it. The
installer hand-rolling TOML has already drifted from the schema once: the
generated-config branch hardcoded `key = ARCHIE_GITHUB_TOKEN` and
`host = ${GITEA_URL}` regardless of the answers given, so choosing Gitea produced
a config naming a token the installer never wrote (archied then exited 1), and
choosing GitHub pointed `host` at `gitea.example.com`. `61a5b35` patched this
with a `forge_block` shell helper shared by both config paths — that helper is a
**workaround**, deleted by
[#72](https://github.com/samcharles93/archie-core/issues/72). The durable fix is
that the code writing the config is the code that reads it.
Why Go and not Python: the installer must run where nothing is installed yet, and
`python3` with `tomllib` means 3.11+, which is not safe on LTS distros. `archied`
is already being built two steps earlier.
**Key constraint for the port:** `BurntSushi/toml` does **not** survive a
decode/encode round trip with comments intact, and `config.example.toml` carries
documentation users are meant to hand-edit. Decide the write strategy
([#412](https://github.com/samcharles93/archie-core/issues/412)) before writing
any prompting code. Do not port a separate `config.yaml`/`auth.yaml` secret
split — Archie already has `secret.SecretRef{engine,key}`, so setup writes the
reference to TOML and the value to the secret engine.
@@ -1,39 +0,0 @@
# The dashboard's tools for an in-browser agent
The dashboard registers in-browser tools an agent can call through the page's model
context. Four are read-only — `list_tasks`, `get_task`, `recent_events`,
`daemon_health` — and three recover stuck work: `retry_task`, `stop_task`,
`cancel_task`. Each wraps the same `ui/src/lib/api.ts` client the dashboard itself
calls, so an agent and a person exercise one path rather than two.
The four judgement verbs are withheld for the reason `identity.md` gives: an agent
that can approve can approve its own work.
## What a tool call can be attributed to
A page can invoke its own tools, so an agent's call and a page script's call reach
the server identically — the difference does not exist on the wire, and no header
recovers it. A tool call is therefore attributed to the signed-in identity the
request presented, with its source recorded as a hint; it never records that an
agent acted, and it never records that a human approved. An agent's action is
attributable only on a surface where the agent presents its own credential.
## Confirmation is a signal, not a control
The three recovery tools require an explicit `confirm: true`, which makes a
consequential call deliberate rather than incidental. It is not a security control:
an agent can trivially satisfy it, and the browser cannot enforce
`consequentialHint` at all — Chrome accepts it at registration and omits it from
`getTools()`, so no client can see what the browser does not surface.
The boundary that holds is the session. These tools cannot exceed what the operator
signed in at the provider is already permitted to do.
## Two ways the surface fails silently
- **A secure context is required.** On a plain-HTTP origin `document.modelContext` is
absent even with the flag enabled, and nothing reports why. `mkcert` covers local
development.
- **The dashboard embeds `ui/dist` into its binary.** Rebuilding the distribution is
not deploying it: a running process can serve a bundle without tools while the
built one has them, or serve a bundle older than its own binary.
Loaded 100 of 2132 files, more files were not shown because too many files have changed in this diff. Show more