Commit Graph
102 Commits
Author SHA1 Message Date
sam 4ffebb855d feat(webui): five-place top bar with Settings, New task and one connection pill
Dashboard, Tasks, Workflows, Events and Settings replace the Work, Agent
and System menus. Configuration pages move under /settings/* with
redirects from their old paths; Logs and Appearance leave the bar and stay
reachable from Jump to, the Dashboard and the account menu. New task opens
the Start work form in a dialog and lands on the new task. One pill reports
the live stream's state.

Drops docs/prds/dashboard-navigation-groups.md: web UI design is not
tracked in PRDs.
2026-09-25 15:09:18 +10:00
sam 9344647719 fix(webui): multiplex dashboard live updates over one stream 2026-09-25 14:05:34 +10:00
sam 2a8ac397df docs(prds): reflow playbook-expression-syntax 2026-09-25 02:00:16 +10:00
sam 5f915931ef test: remove layout-pinned route-registry and task-meta fixture tests
TestDashboardPagesRegistryCoversEveryRoute parsed ui/src/router/index.ts as
text, and TestTaskMetaPayloadMatchesFixture plus ui/test/task-meta-snapshot
pinned a formatted JSON fixture. They failed on formatting, not behaviour.
2026-09-25 01:32:20 +10:00
sam 5cd1079066 fix(ci): make the gate tolerate formatting and give deploy a PG 18 client
The page-registry test parsed the route table one line per route and the
task-meta fixture was byte-compared, so the prettier reformat broke both.
The registry test now splits route objects and ignores comments; the
fixture compares compacted JSON. Also drops a stale router comment that
described the removed redirects, rebuilds ui/dist, regenerates the
contracts artifact, keeps prettier off generated output, and installs
postgresql-client-18 in deploy.yml's gate as quality.yml already does.
2026-09-25 01:29:23 +10:00
sam 2e00777f07 refactor: format markdown files using prettier, fix spelling concerns, reduce Taskfile bloat 2026-09-25 01:10:28 +10:00
sam 2051ca94d2 chore(state-store): remove the one-time SQLite import and db_path
Every install serves from Postgres, so the legacyread/legacyimport packages,
the archie-state-store import command, the boot gate that refused to serve
over unimported SQLite files, and db_path (which only located those files)
go. Migration 0010 drops the import_completion table.
2026-09-25 00:40:48 +10:00
sam f624d23f3c chore(config): remove token_env aliases for forge, artifacts and telegram
Each credential is now only a {engine, key} secret reference. A stale
token_env in a file is reported at startup as an unrecognised key.
nats.token_env stays (no secret-ref form), and providers.api_key_env stays:
it is the carrier the resolver writes each resolved key's env name into.
2026-09-24 23:58:26 +10:00
sam 335fb4bb22 Merge branch 'main' into pg/foundation 2026-09-24 22:21:24 +10:00
sam aa8c4206df docs(development): organise the guides by area
One page per area: frontend UI, agent, workflows, daemon (task lifecycle and
event automation together), State Store, control plane and settings, and
processes and wiring, with merging work kept separate.
2026-09-24 21:05:29 +10:00
sam 6f3289fd33 docs(development): checklists for every kind of change
docs/development/ holds one page per kind of change (settings, State Store
and persistence, task lifecycle, workflows and steps, event automation,
dashboard, agent execution and containers, processes and wiring, merging
work), each naming every layer the change must reach and pointing at the
document that owns the design. The docs build puts them in the development
set; docs/index.md and CLAUDE.md link them.

Also adds the container-profile case to the validator agreement test, the
check the profiles work skipped.
2026-09-24 21:03:34 +10:00
sam f3b8ddecb0 fix(eda): clear completed tasks; document the tool allowlist's reach and unchecked profile names
ClearTerminalTasks now deletes completed tasks, with a test that holds its
SQL list to taskstate.Terminal. The AllowTools comment says agentloop's
built-in file tools are outside the allowlist and why. The PRD model
diagram lists only what a profile holds (image, tools), and the profile
field and AgentProfile say a workflow's profile name is resolved at
dispatch, not when the workflow is saved.
2026-09-24 20:53:51 +10:00
sam 47fae672f1 feat(eda): workflow inputs, optional repository and agent profiles
Workflow definitions declare inputs, repository (none, optional or
required; default required) and profile. A binding assigns each input
from a mapped parameter or a constant and may take its repository from a
parameter, which must name a configured repo; both are checked when the
binding is saved and again at dispatch. Inputs travel as structured task
data (tasks.inputs, the task brief, and a JSON block in the agent's
mission), never as body text.

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

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

Also stop two archied tests writing embedded NATS state into the package
directory, refuse an empty state_dir for embedded NATS, and drop the NATS
store files an earlier lane commit tracked.
2026-09-24 20:29:33 +10:00
sam 2393cade0f Merge branch 'pg/foundation' into worktree-agent-a96503bc8828fc104
# Conflicts:
#	docs/data/generated/dev-docs.json
#	internal/app/archied/state_store_test.go
#	internal/app/archied/state_store_toolcalls_test.go
#	internal/contracts/state/v1/state.pb.go
#	internal/daemon/dispatch_bindings_test.go
#	internal/infrastructure/bindingcipher/cipher_test.go
#	internal/infrastructure/captureintake/receiver_test.go
#	internal/infrastructure/edastore/contracts_binding.go
#	internal/infrastructure/edastore/testsupport_test.go
#	internal/infrastructure/postgres/edastore.go
#	internal/infrastructure/postgres/edastore_test.go
#	internal/infrastructure/staterpc/error_test.go
#	internal/store/store.go
#	internal/webui/api_binding_test.go
2026-09-24 19:47:00 +10:00
sam 35ebaa6ce4 docs: describe the PostgreSQL-only stores, state_dir and the import-only db_path
Architecture, deployment, installer, skill and PRD text now name the Postgres
State Store, the offline recovery commands on database_url, state_dir for host
state, and db_path as the legacy-file locator for archie-state-store import.
Finalised PRDs, CHANGELOG, docs/news and docs/archive are unchanged records.
2026-09-24 14:51:48 +10:00
sam 72be0049ed docs(bindings): bindings apply per event type with a filter; mappings count matches 2026-09-24 14:46:44 +10:00
sam 60b88ad6d3 Merge branch 'worktree-agent-a2b33953bdffebf56' into worktree-giggly-marinating-lamport
# Conflicts:
#	docs/data/generated/dev-docs.json
#	internal/app/archied/state_store_pool.go
2026-09-24 10:06:00 +10:00
sam cea88060b1 feat(archied): serve the State Store, event store and Gateway conversations from Postgres
The State Store's task and event-capture stores and the conversation store
read by archied and served by archie-gateway now open on database_url.
Every serving process refuses to start when legacy SQLite data exists and no
import completion is recorded, naming archie-state-store import; a fresh
install records completion itself. The Gateway holds its Postgres serve
claim for its lifetime and releases it before the pool closes.
2026-09-24 10:01:54 +10:00
sam d80c01b9fb feat(archied): recovery commands on PostgreSQL; fail-closed pre-update snapshot, no automatic schema rollback
Without -db, backup/restore/validate/rollback resolve database_url from the
config and work on the whole PostgreSQL database. Restore claims every service
role; rollback claims the State Store role; validate refuses a schema newer
than the binary. The installer refuses a daemon update it cannot snapshot
first; the watchdog never restores the database and prints the explicit
offline restore instead.
2026-09-24 09:50:10 +10:00
sam cb518e6f6d feat(webui): serve change statuses and the config schema through /api/task-meta
Closes #865. The dashboard hand-copied the Change* file-status ids and events.ConfigCapturedSchema. /api/task-meta now serves both; the Vue dashboard renders ui/src/lib/task-meta-snapshot.ts until the served catalog lands. The Go handler is pinned to internal/webui/testdata/task_meta.json and the snapshot is pinned to that same fixture, so a one-sided rename fails a test.
2026-09-24 09:31:09 +10:00
sam 902cfbeb61 feat(postgres): pool that refuses servers before PG 18, goose migrations under an advisory lock, testcontainers harness
internal/infrastructure/postgres opens a pgx pool, checks server_version_num >= 180000, and applies goose migrations with a Postgres session advisory lock so processes starting together apply each migration once. internal/infrastructure/postgres/pgtest starts postgres:18 through testcontainers per test binary and gives each test its own database. Adds jackc/pgx/v5 v5.11.0, pressly/goose/v3 v3.28.0 and testcontainers-go v0.44.0. The database URL config, sqlc, the Compose service and the ownership lock move to archie-core-7r0x.2, where they have consumers.
2026-09-24 01:03:08 +10:00
sam 61f19a2807 docs(prds): orgs, workspaces and access control
Approved design for orgs and workspaces, people and agents as identities, the Cedar policy chain (instance with network rules, org, workspace, identity and workflow, object), server-derived credential scope, and one run credential per agent run. Secrets move from agent profiles to identities; event-automation.md is marked superseded where it said otherwise.
2026-09-24 00:34:14 +10:00
sam 86dbe680e3 docs: regenerate dev-docs.json for the event automation PRD 2026-09-24 00:30:22 +10:00
sam d180e624d9 fix(bindings): a new binding is created pending approval
Nothing moved a binding out of draft except an unrelated edit, so a newly created binding could not be approved and the dashboard showed no Approve button. Draft is removed; existing draft rows are promoted to pending_approval when the EDA store opens.
2026-09-23 23:13:49 +10:00
sam 068d89ebb4 feat(eda): playbook.Load findings name the offending action, when or args line 2026-09-23 22:42:14 +10:00
sam ee16b8a711 feat(playbooks): archie-playbooks serve, a language server publishing lint findings as diagnostics 2026-09-23 22:22:56 +10:00
sam 69e6d276e6 feat(playbooks): lint an EDA playbook directory with -eda-dir 2026-09-23 22:11:01 +10:00
sam d01f7b3d3a feat(eda): reject an args value whose checked CEL type cannot fill its Args field 2026-09-23 22:05:50 +10:00
sam e867760711 feat(eda): run action playbooks at pin time through the at-most-once dispatch ledger 2026-09-23 22:00:52 +10:00
sam b2dbcda697 docs(eda): playbook dispatch rows are retained until an explicit delete 2026-09-23 21:52:10 +10:00
sam 6bba6f8070 fix(eda): type-aware actions classifier, one stable-identifier grammar, loader tests that fail for the named reason 2026-09-23 21:48:52 +10:00
sam 75454d22c1 feat(workflow): routing and playbook findings carry the key's file:line 2026-09-23 21:41:56 +10:00
sam e9c2c09b4b fix(webui): move the live stream to /api/stream so reloading /events serves the page 2026-09-23 21:16:29 +10:00
sam aac31b69ad docs(agents): a bead never carries production instance detail
Beads sync to a Dolt remote, so anything written into one is published.
Two beads filed earlier today named an operator host, its internal
address and its filesystem paths -- the tracker was treated as a private
store, which it is not.

The rule is stated where the tracker is described, next to the existing
one about .beads/ never reaching a commit, because it is the same class:
the tracker is not a private store. Host-specific facts belong in the
operator's memos instance, which a bead may point at.
2026-09-23 12:29:29 +10:00
sam cb8e4d0f13 docs(prds): approve the master-detail run page PRD
The maintainer approved task-run-master-detail.md after the
adversarial-review round; its status moves Draft -> Approved while the
work it describes is completed and verified.
2026-09-23 11:36:16 +10:00
sam 4573c27567 fix(webui): reset the stage filter on an attempt switch
A stage filter is a command scoped to the attempt it was made on: the
rail set it against that attempt's stage list. selectAttempt and
performRetry left filters untouched, so a stage selected on attempt 2
carried into attempt 1 -- a same-named stage there rendered as selected
without ever being commanded, or the log stayed narrowed to a stage the
new attempt does not have. The stage filter now resets when the selected
attempt changes; the level filter is attempt-agnostic and survives.

The master-detail PRD absorbs the adversarial review's verified findings:
the reload claim is narrowed to the URL contract (filters are not in the
URL), the unimplemented scroll and pinned claims are dropped, the
unnamed-stage and level-filter contracts are stated, the rail inventory
is corrected, and the acceptance list gains criteria for the
command-not-binding rule, attempt-switch reset, and keyboard selection.
2026-09-23 11:31:58 +10:00
sam 39ad75ac22 feat(webui): split the task run page into a master-detail pane
The five tabs gave the stage rail less than a third of the screen and
disconnected the log stream from the stage that produced it. The stage
rail is now the page's master pane, always visible; the four context
panels are the inspector and own the tab bar. Selecting a stage commands
the inspector to the log tab with that stage's filter set; clicking the
selected stage clears it. Selection is a command, not a binding -- the
operator can change the filter afterwards.

No endpoint, RPC or contract changed. tab=stages still resolves, to the
log tab; every inspector tab and attempt deep-link survives a reload.
Below the shell's 900px frame breakpoint the rail stacks above the
inspector. Design of record: docs/prds/task-run-master-detail.md (Draft,
per-run panel contracts unchanged from task-run-detail.md).
2026-09-23 11:20:45 +10:00
sam e231ef0786 merge(sams-cleanup): the PocketBase event-capture migration and its follow-ups
Moves event capture, mappings and bindings onto PocketBase-owned collections
in internal/infrastructure/edastore, and adds the read-only stateadmin
surface over the task database. Follow-ups included:

- the event feed cursor becomes a total order over a fixed-width timestamp
  with an opaque string cursor, so it no longer depends on rowid
  monotonicity;
- cron schedules get next-run arithmetic, so a cron job fires instead of
  returning ErrScheduleUnsupported;
- binding and mapping edits announce on the activity stream, so a dashboard
  edit is visible without a manual refresh;
- an unresolvable task identity fails closed rather than falling back to the
  root forge's credential;
- tool_call events project into the tool_calls collection, which had a
  schema and no writer.

Also: the branch is brought back to a passing task check, which it had not
been for the whole migration -- two pre-existing failures, an unrecorded
int64-to-string proto break and a stale generated docs artifact.
2026-09-23 03:33:49 +10:00
sam 236974fbae chore(docs): regenerate dev-docs.json for the artifact-sender PRD
e0becd52 added docs/prds/artifact-sender.md without regenerating the
artifact, so docs:artifact:check failed at that commit. Generated from a
clean worktree at e0becd52.
2026-09-23 03:16:35 +10:00
sam 05dfe00e31 chore(docs): regenerate dev-docs.json after the architecture doc move
docs:artifact:check has failed on this branch since 024dfbbe deleted
ARCHITECTURE.md and moved its normative content into docs/architecture;
the generated dev-docs artifact was never regenerated, so task check could
not pass. Regenerated from a clean tree (no untracked docs present).
2026-09-23 02:59:35 +10:00
sam 024dfbbe49 docs: delete ARCHITECTURE.md, move its normative content into docs/architecture
ARCHITECTURE.md duplicated the docs/architecture tree and had drifted badly
against it: "internal/ holds ~36" against 112 packages, two of the seven
binaries listed, a Forge table listing `RepliesAfter` (deleted from the tree),
and a stated invariant ("No daemon-internal cron") contradicted by the
scheduling engine that internal/app/archied/scheduling.go composes and
main.go starts.

It was also the sole home of three pieces of still-authoritative content, so
those move rather than disappear:

- plugin engine rule (strict), the memory engine family, and the
  internal/plugin/architecture_test.go enforcement note ->
  docs/architecture/plugins-and-extensions.md
- intake provenance: forge poll/webhook dedup through
  TaskEnvelope.IdempotencyKey, binding-stamped chat/playbook enqueue, and the
  single-identity webhook-intake rejection ->
  docs/architecture/messaging-and-work-intake.md

Live references are repointed from CLAUDE.md (AGENTS.md is a symlink to it),
docs/architecture, docs/guides, seven PRDs, and four .agents skills. The
heading "## Plugin engine rule (strict)" is preserved in its new home so the
existing #plugin-engine-rule-strict citations keep resolving. Generated docs
artifacts regenerated.
2026-09-22 23:49:53 +10:00
sam 1d31ab71e3 docs(release): record the one-stream process, and stop process scopes inflating versions
RELEASING.md still described two independently versioned components, GATEWAY
and RUNTIME release inputs, and a `task release:prepare` invocation that no
longer exists. It is the file someone reads to cut a release, so a stale one is
worse than none.

The PRD's version computation carried a real flaw: a commit whose scope is the
repository's own machinery could still bump the product's version, so the first
improvement anyone made to the release process would inflate it -- which is
exactly what `feat(release)` would have done to this cut. Non-product scopes
(`release`, `ci`, `docs`, `build`, `test`) now contribute no bump.
2026-09-22 21:43:10 +10:00
sam cd2ab7f2cb feat(release): one release stream, one version, one page per version
CHANGELOG.archied.md and CHANGELOG.archie.md were two version streams that
drifted: a release that moved both components had two numbers, two pages and
two tags, and a reader had to visit two files to learn what shipped.

The merged history holds 65 versions from 64 archied and 34 archie sections --
33 that both components released, 31 only archied, one only archie -- so 98
published pages become 65. A version's date is the newest of its sections'
dates, and a component whose own date differs carries it on its label, because
the history has two dates and the merge must not invent one. `## [Unreleased]`
is not a release: it gets no page, and it stays at the top of the file.

A level-two heading is where the merge could silently drop a section, so the
merge is verified by content rather than by the generator: section counts per
source, the merged version set against the exact union, and every source `###`
title present both as a substring and, after stripping the component prefix, as
an identical heading. Counting `##` headings rather than releases overcounts by
one here, which is how the empty `[Unreleased]` block was caught.

- newsgen reads one file and writes `docs/news/<version>.md`, the index, the
  canonical `releases.json`, and `docs/news/redirects.json`. The redirect table
  is what keeps the retired `/news/<component>/<version>/` URLs alive; it is
  generated beside the pages so it cannot drift from them.
- release.sh takes one `--version`, keeps commit and tag (the Woodpecker
  pipeline that will own them does not exist yet), and exits 3 when the commit
  set justifies no release, so a pipeline can finish green without tagging.
- The consumers of the two files follow: the deploy workflow's tag gate and
  release-notes extraction, the zip contents, the update check's changelog
  links, the packaged-path note, the docs skill, and newsgen's tests.

The per-component detail survives as labelled sections inside each release, so
a reader still learns whether archied or the agent changed; what goes away is
the separate numbers and the separate pages.
2026-09-22 17:18:06 +10:00
sam 10b755468e docs(prds): decide how the merged history represents two dates per version
A version both components released carries one heading and one date: the newest among
its sections, because a version's date is when its last part shipped. Where a
component's own date differs, that component's section label carries its own, so the
per-component fact survives the merge instead of being collapsed into the heading.

The ambiguity is historical only -- one version stream with one tag gives a version
exactly one date -- so the rule represents the merged past rather than a design that
must hold.

The same section records how the merge is verified: by content, not by the generator
exiting zero. The section count per source, the merged version set equal to the union
of both, and every title still present; a generator agreeing with the file it just
wrote is evidence of nothing.
2026-09-22 17:09:04 +10:00
sam c5885c0cb8 docs(prds): make the Woodpecker repository registration a prerequisite
Adding a release workflow to this repository and enabling the repository in
Woodpecker are two steps, and only the first is a file in this tree. A pipeline that
is correct and never runs is invisible until someone asks why no release happened, so
the second step is stated as a prerequisite of the design rather than left as an
assumption behind it.
2026-09-22 17:06:19 +10:00
sam e982d88dbf docs(prds): design the release pipeline and the script it calls
The unification in this PRD is what makes a release pipeline possible, so the
pipeline design belongs in the same document rather than a second one that would
have to agree with it.

The spine: a Woodpecker workflow gates, generates the release page, runs the reviewer
over it, commits the changelog and generated pages, tags, pushes, publishes images
and triggers the site's artifact sync -- with no operator step. It triggers on a push
to main rather than a manual run, which is both what "none of it done manually" asks
for and the only trigger this estate's Woodpecker configurations are proven on.

The version is computed from conventional commits since the last release, which is
what the commit rules in this document exist for, and "no release" is a legitimate
outcome rather than an invented version. One tag also removes two of the three builds
a release starts, because concurrency keyed on a commit identifier treats an
annotated tag as a distinct ref -- a consequence of one version stream, not a
separate fix.

The part that cannot be retrofitted cheaply is tools/release.sh, so its shape is
decided here: no prompts, a version that is an argument and a reported result, a
distinct exit code for "nothing to release", and no commit, tag or push of its own
because the pipeline owns those and the script runs on every push to main.

The three CI surfaces are assigned authorities here, so the pipeline is not built in
three places with one authority. The pipeline itself is implemented next; this commit
is the design it will be built from.

Verified: prdlint caught a temporal hedge in the first draft of this text and the
gate refused the commit -- the chain works, and the finding is fixed rather than
suppressed.
2026-09-22 17:02:50 +10:00
sam f711705a3a docs(prds): decide one release stream, one page per version, and commit rules
A decisive one-page PRD for the release-pipeline change, per AGENTS.md's rule that a
change to settled process starts with a decision rather than a refactor.

The load-bearing decision is one version stream: GATEWAY and RUNTIME stop being
release inputs, so an operator names one version and per-component detail survives as
sections inside the release rather than as separate numbers and pages. A three-way
release forces skip values for components that did not change and lets two
components' tags drift a release apart.

It supersedes the two-component sections of docs/prds/news-and-releases.md and says
so by name, rather than leaving two documents disagreeing about how many components
there are.

The reviewer step is written from a verified invocation, not from the help text: tl
rules --lint reports "corpus ok", and tl review on a generated page reports "0
findings (0 high, 0 medium) · 1/1 files reviewed · clean". --fail-on defaults to
never, so the PRD requires the level to be passed explicitly -- without it the step
cannot refuse anything.

Documented-but-unimplemented is the deliberate state: the PRD is the artifact this
change is required to start with, and the implementation follows separately.
2026-09-22 16:59:44 +10:00
sam 25c4822343 docs(news): state what a reader gets, and move the design where it is read
The v1.36.0 release note carried four things a reader cannot use. The dashboard's
seven in-browser tools and the installtype fix stay; the withheld judgement verbs,
the consequentialHint limitation and the two silent-failure notes are removed from
the release feed and moved to where an implementer looks.

  - The four verbs are withheld because an agent that can approve can approve its
    own work. That is settled design, so it now sits in docs/architecture/identity.md,
    beside the approval-path conflict it belongs with, stated as the constraint it is:
    attribution, not capability, is what releasing them depends on.
  - The browser-tool surface had no home in docs/architecture, so it has one now:
    docs/architecture/dashboard-agent-tools.md holds what a tool call can be
    attributed to, why confirmation is a signal rather than a control, and the two
    ways the surface fails silently.

Audited 1.35.0, 1.36.0 and 1.37.0 for the same class. 1.37.0 is clean. 1.35.0 carried
two build notes: a bullet recounting that a guard had never been written because it
failed, and a clause about a manager "finally" having a production writer. Both are
gone; the capabilities they were attached to remain.

RELEASING.md now carries the rule so the next release reads it: release notes state
what a reader gets, and design constraints, withheld capabilities and failure modes
belong in docs/architecture/, because a note about an absence reads as a feature to
someone who never had the thing.

docs/news/** is regenerated by task news, never hand-edited. task check passed before
this commit: the chain runs it, so a failing gate commits nothing.
2026-09-22 16:53:27 +10:00
sam 179c1c8e8f fix(identity): derive the caller the way the provider issues tokens
Infra decoded real tokens from both clients, and two of the three facts changed
this code.

A machine token carries NO sub at all: it names its caller by client_id, and the
identity is that client. A person's token carries sub, the provider's stable
identifier for the person. The subject is now derived explicitly -- sub when
present, else client_id -- and a verified token asserting neither is refused
rather than accepted as an anonymous caller, because accepting it would let any
token the provider ever signed act as whoever the binding happened to hold. A
machine identity is therefore per client registration, one identity per client,
which is what makes per-agent identity a configuration decision rather than a code
change.

Scopes are read from either claim shape. The standard is a space-delimited scope
string and this provider also emits an scp array; reading only one shape yields no
scopes at all, which is worse than reading none deliberately.

The audience-at-authorisation-endpoint trap is pinned by a test: a token minted
without the requested audience arrives with aud empty, and the audience check
refuses it. That refusal is correct and the fix is the request the human flow
builds, not a weaker check here -- a test now fails if anyone weakens it.

The PRD records both as constraints: a person's client and an agent's client are
registered separately because a shared registration collapses the distinction the
attribution rests on, and a person's token requests the audience at the
authorisation endpoint as well as the token endpoint.

Verified: task check exit 0; internal/infrastructure/oidc passes, including
subject derivation for both token shapes and every refusal.
2026-09-22 14:37:58 +10:00
sam 2cb2275eb6 docs(prds): settle identity for users, agents and external agents
One identity record covers users, agents, external agents, service accounts and the
system. Authentication is delegated to the estate's OIDC provider and attribution
stays archie's. Nothing that verifies a credential, issues a session, stores a
password or checks a permission is built here, per Sam's hard requirement that
authentication and authorisation are OSS archie integrates.

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

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

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

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

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

The PRD is a development-audience page, so it regenerates dev-docs.json to 69
pages. Verified: task check exit 0, including docs:prds.
2026-09-22 14:10:55 +10:00