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.
This commit is contained in:
sam committed 2026-10-03 21:47:46 +10:00
1 parent a45300d626
commit 42988970fe
190 files changed
+151 -31692

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,287 +0,0 @@
//go:build ignore
// 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. Run it by name: go run
// config-use-candidates.go. The directory holds several standalone programs, so
// each carries this constraint.
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,361 +0,0 @@
//go:build ignore
// Command source-metrics emits deterministic, syntax-derived Go source metrics.
// It never writes to the inspected tree and uses only the Go standard library.
// Run it by name: go run source-metrics.go. The directory holds several
// standalone programs, so each carries this constraint.
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/`.
+125 -392
View File
@@ -1,418 +1,151 @@
# 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 (a forge issue,
a webhook capture, a schedule, a chat message) is matched to a workflow,
the workflow runs an agent in an isolated container, and the result lands
somewhere a human reviews it. A repository is one 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`.
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.
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.
There are no PRDs, architecture docs or repo skills. Old ones live outside
the repo and are not guidance. Do not recreate them.
## Deployment Model
## How to decide
- **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.
- **Broken beats new.** A bug that blocks work gets fixed now, with the
smallest change that unblocks it. No design doc, no new mechanism.
- **Cheapest option first.** Before building anything, 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 present the cheap option to the maintainer first.
- **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.
- **No new binaries.** A new command is a subcommand of an existing binary.
A binary exists only for a real process boundary (separate deploy,
scaling, security or failure domain).
- **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.
## Release Process
## Code
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.
- Idiomatic Go. Small functions, explicit errors, no package-level mutable
state, no god objects. `internal/app/archied/bootstrap.go` is the
counter-example: never add to it. New wiring belongs to the feature that
needs it.
- 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.
## Build & Test
## Tests
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.
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. 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.
- 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`,
`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. `policy` is designed but not built
(`docs/architecture/policy.md`).
- **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 and the `repo.review_enabled` setting, both since
removed. 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.
+15 -54
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
@@ -82,30 +78,12 @@ See the
for 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,22 +92,15 @@ and task activity. The intended authoring path starts with a real payload or an
example: identify its structure, map the fields you need, select a workflow, and
approve the binding.
Sources default to signed delivery. The event automation design also allows an
explicitly approved unsigned source for systems that cannot sign payloads, with
that status visible to operators. Binding changes require re-approval before
they can dispatch work.
Playbooks and extension points provide additional orchestration through
workflows, modules, channels, and forges. The
[playbook engine design](docs/prds/eda-playbook-engine.md) describes how
registered capabilities become actions that event rules can call.
Sources default to signed delivery; an unsigned source must be explicitly
approved. Binding changes require re-approval before they can dispatch work.
## Develop locally
The repository requires Go 1.27, [Task](https://taskfile.dev/), Node.js and npm,
and Docker with a running daemon. The development stack starts PostgreSQL 18
through Docker Compose. Install the Go formatting and lint tools listed in
[CLAUDE.md](CLAUDE.md#build--test) before running the full quality gate.
through Docker Compose. See [AGENTS.md](AGENTS.md) for the tools the quality
gate needs.
```bash
task dev
@@ -162,21 +133,11 @@ but systemd is optional.
## Documentation
- [Event automation](docs/prds/event-automation.md) — sources, schemas,
mappings, bindings, workflows, and agent profiles.
- [Organisations and access](docs/prds/orgs-and-access.md) — tenancy,
identities, permissions, approvals, and audit.
- [Playbook engine](docs/prds/eda-playbook-engine.md) — event rules and
extensible actions.
- [Architecture decisions](docs/prds/01-project-management.md) — approved design
and open migration questions.
- [Development guides](docs/development/index.md) — change checklists by area.
- [Deployment examples](deployments/README.md) — configuration templates and
operating notes.
- [Release process](RELEASING.md) — how releases are built and published.
- [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
+1 -2
View File
@@ -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.
-50
View File
@@ -69,26 +69,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 ..
docs:drift:
desc: Reject docs that cite a repository path which no longer exists
cmds:
- go -C tools run -mod=readonly ./docdrift check --repo-root ..
news:
desc: Regenerate the release data artifacts from the changelog
cmds:
@@ -99,16 +79,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:
@@ -141,11 +111,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
@@ -308,11 +273,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.
@@ -326,24 +286,14 @@ tasks:
internal: true
deps:
- task: proto:lint
- task: docs:check
- task: docs:prds
- task: docs:drift
- 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:
-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.
@@ -1,71 +0,0 @@
# Dependencies and Contracts
**Status:** Approved foundation
**Date:** 2026-07-28
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
## Dependency direction
```text
domain and shared application contracts <- infrastructure implementations
^
|
application composition
```
The following rules are strict:
1. Domains MUST NOT import `internal/infrastructure`.
2. A domain defines the smallest interfaces required to perform its work.
3. Infrastructure implements those interfaces and translates external
representations at the boundary.
4. Only application composition chooses concrete implementations.
5. A domain MUST NOT manipulate another domain's state or call its internal
services.
6. Cross-domain work uses an explicitly designed command, event, or approved
shared contract.
7. Implementation difficulty is not permission to violate a boundary.
Broker messages, database rows, SDK response types, and configuration DTOs MUST
NOT leak into domain models.
## Commands and events
- An event records something that happened and is owned by its publishing
domain.
- A command requests an action and is owned by the domain expected to handle it.
- Consumers do not redefine an event's meaning.
- Senders obey the receiving domain's command contract.
- There is no generic package containing unrelated application messages.
## Event bus
`internal/eventbus` is an approved shared application contract. It defines only
the messaging behaviour Archie requires, including publication, subscription,
delivery outcomes, and required lifecycle semantics.
It MUST remain broker-neutral. NATS subjects, JetStream configuration, consumer
groups, acknowledgements, reconnection, and serialisation belong under
`internal/infrastructure/eventbus/nats` unless Archie explicitly requires a
semantic guarantee in the shared contract.
Message schemas stay with their owning domains. The event bus transports
messages; it does not own their meaning.
## Wire contracts and generation
Canonical worker and service wire contracts and their authoritative generation
inputs are owned by the domain or capability that defines their meaning. They
MUST NOT be centralised in `internal/infrastructure/spec` or another generic
schema package.
Infrastructure owns:
- generic contract-generation machinery;
- transport-specific adapters and generated implementations;
- RPC, REST, NATS, and other external encoding and delivery concerns.
For example, agent-worker requests and results belong to task execution.
Subprocess, NATS, or HTTP representations are infrastructure implementations of
that contract. The same rule applies independently to forge, persistence,
workspace, and other service contracts.
@@ -1,439 +0,0 @@
# Generated Documentation
**Status:** Data generation lives here; rendering and publishing live in the external Astro website
**Date:** 2026-07-28 (revised 2026-09-25)
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
## Purpose
Archie's documentation-generation approach is:
- production Go code, registries, configuration, and CLI behaviour remain the
source of truth for published contracts;
- a repository-local Go generator extracts and normalises documentation data;
- the generator writes deterministic JSON/data files and protocol schemas;
- the external Astro website consumes generated data and serves the public
documentation at `offloaded.dev/docs/`.
Hugo is not part of the target architecture.
The documentation system is rooted at:
```text
tools/
go.mod
go.sum
docsgen/
main.go
docs/
data/generated/
public/schemas/
*.md
```
### Rendering and publishing — external Astro website
Superseded 2026-09-12. The repository previously carried a VitePress site
(`docs/.vitepress/config.mts`, `docs/package.json`, a 1620-line
`docs/pnpm-lock.yaml`, `docs/pnpm-workspace.yaml`) built and deployed to GitHub
Pages by `.github/workflows/docs.yml`. It was removed as an unnecessary build
step: the published site was never stood up, and the Pages target is not
configured.
The Astro website is maintained outside this repository. This repository owns
the Markdown source and generated JSON artifacts; it does not build, preview, or
deploy the site. The external site owns page rendering, navigation, and
publishing.
The current boundaries are:
| Concern | Owner |
| --------------------------------------- | -------------------------------------------------------------------- |
| Reference-page rendering and publishing | External Astro website |
| Documentation source and generated data | This repository |
| Generated-data drift detection | `task docs:check`, `task docs:artifact:check`, and `task news:check` |
| Navigation data | `docs/data/generated/docs.json` and `dev-docs.json` |
Changes to an artifact contract must be coordinated with the external Astro
consumer. This repository does not validate the website's rendered links or
routes.
## Single source of truth
Every published capability has one authoritative machine-readable definition
owned by its domain or application boundary. Generated documentation derives
from those definitions.
Generated reference includes:
- domain commands and events;
- Messages and typed message content;
- Agent and Workflow contracts;
- WorkflowSteps and Workflow plugin capability contracts;
- policies and their typed inputs and outcomes;
- tools and capabilities;
- CLI commands, arguments, flags, defaults, and help;
- runtime settings, types, defaults, validation, and secret metadata;
- public worker and transport contracts;
- indexes of registered functionality;
- deprecation information.
Handwritten documents contain:
- architecture decisions and rationale;
- tutorials and operational guides;
- examples and walkthroughs;
- migration guidance;
- conceptual explanations.
Handwritten documents link to generated reference rather than copying
authoritative tables.
## Target generation architecture
`tools/docsgen` is Archie's documentation extractor and normalizer. It produces
structured documentation data and protocol specifications. It does not own
page layout and MUST NOT generate Markdown pages or fragments.
The generator is divided internally into reusable stages:
```text
load registries and types
-> normalize documentation model
-> validate ownership and identifiers
-> serialize data and protocol artifacts
-> compare or write output
```
The normalised documentation model prevents each output renderer from
independently interpreting Go types. It contains stable documentation IDs,
owners, names, descriptions, source references, versions, deprecations, fields,
defaults, validation, secret classifications, and relationships.
Initial generator targets:
```text
docsgen data
docsgen asyncapi
docsgen all
docsgen check
```
- `data` writes the normalised JSON reference data.
- `asyncapi` writes protocol schemas and envelopes.
- `all` generates every committed artifact.
- `check` generates into a temporary directory and fails on drift.
The command may use subcommands or an equivalent explicit `--target` flag. It
MUST retain one normalisation and validation path.
## Target output
During adaptation, `docs` remains the staging site. Generated outputs live in
a visibly owned subtree:
```text
docs/
data/
generated/
catalog.json
contracts.json
docs.json
dev-docs.json
cli.json
configuration.json
messaging.json
agents.json
workflows.json
policies.json
plugins.json
tools.json
public/
schemas/
asyncapi-header.yaml
archie.yaml
.tmp/
```
All files under `data/generated/` and `public/schemas/` carry generated
ownership metadata where their format permits it and MUST NOT be edited
manually. `.tmp/` is generator-owned, ignored, and never committed.
`catalog.json` is the deterministic machine-readable index used for:
- reference navigation and route inputs;
- duplicate-ID and duplicate-route validation;
- coverage checks;
- source-to-data drift diagnostics;
- future external consumers.
These files are consumed at render time by whichever renderer is chosen (see
"Rendering and publishing"); the generator's contract is the committed JSON, not
any particular loader. A renderer reads `data/generated/*.json` directly — Archie
does not use `createContentLoader`-style Markdown collection scanning, because
the authoritative inputs are JSON.
The final move from `docs/` to `docs/` occurs only after Archie content
contains intentional Archie pages and the current architecture documents have an
intentional destination. The staging name MUST NOT leak into public URLs.
## Generation steps
### Step 1: maintain the Archie tools module
Keep `tools/go.mod` isolated from the runtime module:
```go
module github.com/samcharles93/archie-core/tools
require github.com/samcharles93/archie-core v0.0.0-00010101000000-000000000000
replace github.com/samcharles93/archie-core => ../
```
Keep generator-only dependencies such as `invopop/jsonschema` and any future
protocol-schema serializer in the nested tools module. They MUST NOT enter the
root module.
`docsgen` imports Archie-owned contracts and writes normalised Archie data and
protocol artifacts.
### Step 2: establish authoritative registries
The generator consumes domain-owned registries rather than scanning arbitrary
packages for anything exported.
Each published definition supplies:
- stable documentation ID;
- owning domain or boundary;
- name and description;
- version when versioned;
- the Go type or declarative definition;
- lifecycle and deprecation metadata;
- source reference.
Registries remain executable application definitions used by production code. A
documentation-only duplicate registry is prohibited.
Where the migration has not yet created a final domain registry, the generator
may use a narrow compatibility adapter over the current registry. That adapter
has explicit deletion criteria.
The initial agent-execution and messaging schema set is such an adapter. It is
deleted when those domains expose their production-owned documentation
registries; adding another hardcoded type list to `docsgen` is prohibited.
### Step 3: generate AsyncAPI
Use Archie's messaging and worker wire registries as the authoritative inputs.
The static header continues to own:
- AsyncAPI version;
- service and protocol description;
- servers;
- channels;
- operations;
- message envelope placement.
The generator owns:
- component schemas;
- discriminated concrete message lists;
- generated envelopes;
- rewritten schema references;
- stable ordering.
The generated protocol artifact becomes:
```text
docs/public/schemas/archie.yaml
```
The final owner of each wire registry is the domain or capability defining its
meaning. `docsgen` renders the contract; it does not own the message semantics.
### Step 4: add generated documentation data
Add extractors for the missing reference categories one vertical slice at a
time.
Recommended implementation order:
1. CLI commands and flags;
2. runtime configuration/settings;
3. Messaging commands, events, and message types;
4. Agent definitions and public commands;
5. Workflow definitions, WorkflowSteps, lifecycle, and plugin contracts;
6. policy definitions and typed outcomes;
7. tools and capability contracts;
8. worker and external wire contracts.
Each category extractor contributes:
- stable IDs, owners, routes, and display ordering;
- fields, types, defaults, and validation metadata;
- source references;
- version and deprecation information;
- relationships to commands, events, policies, and contracts.
The first vertical slice proves the normalised model and deterministic JSON
serialisation. Later categories reuse it rather than introducing
category-specific ad hoc output formats.
### Step 5: external Astro renderer
The Astro website reads `data/generated/*.json`, validates it, and renders
reference views. Build and deployment remain owned by the website repository.
Navigation and routes derive from `catalog.json`; they MUST NOT be duplicated by
hand in renderer configuration.
### Step 6: implement deterministic drift checking
`docsgen check`:
1. generates all artifacts into a temporary directory;
2. normalises line endings and file modes;
3. compares the complete expected data and schema trees with committed outputs;
4. reports missing, changed, and obsolete files;
5. identifies the authoritative definition associated with each mismatch;
6. exits non-zero without modifying the working tree.
Generation MUST exclude:
- wall-clock timestamps;
- absolute filesystem paths;
- map iteration order;
- environment-specific values;
- secrets and resolved credentials.
Two consecutive `docsgen all` runs MUST be byte-identical.
### Step 7: Astro renderer — external consumer
The external Astro website consumes the committed generated JSON artifacts and
serves the documentation under `/docs/` and `/dev/`. Its build and deployment
are owned by that repository. The consumer MUST:
- read `data/generated/*.json` rather than re-deriving from source;
- validate internal links, with dead-link failures enabled (no blanket
ignore list);
- state its own local preview and build commands;
- keep `node_modules/` and any build output out of source control.
### Step 8: developer commands
`task docs:generate` writes the committed artifact; `task docs:check` verifies
it. `task check` runs `docs:check`, so generated drift is gated rather than
advisory: a stale artifact fails the gate and names the authoritative Go
definition behind each mismatch.
```sh
task docs:generate
task docs:check
```
Both wrap the generator, which can still be run directly:
```sh
go -C tools run -mod=readonly ./docsgen --repo-root ..
go -C tools run -mod=readonly ./docsgen check --repo-root ..
```
`docsgen all` is still target-only: `docsgen data` and `docsgen asyncapi` do not
exist. Two artifacts are generated today: `contracts.json` from the Go
contract types (`docsgen`) and, from the Markdown sources, `docs.json` and
`dev-docs.json` (`docsite`, one artifact per published set: the public set a
reader of the product gets, and the development set of architecture and design
records) -- see `task docs:artifact`.
### Step 9: validation and CI
`task check` validates generated contracts and Markdown-derived documentation
artifacts. The Astro site's rendered routes and deployment are validated in its
own repository.
### Step 10: content migration
The Astro site consumes generated artifacts. Remaining content work is to:
Still standing from the original cutover list:
- remove Markdown, examples, specs, generated schemas, and assets that do not
describe Archie;
- adapt retained content and prove it against Archie code;
- update `docs.go` and its tests to embed only intentional runtime
documentation;
- decide which current `docs/prds` remain published architecture pages and which
remain repository-only planning documents — all of them are repository-only
now, so the distinction is retired.
Documents MUST describe Archie. Publishing is a separate, undecided concern.
## Hook and CI policy
Generated documentation is committed.
No pre-commit hook is installed in this repository, and no CI step runs the
generator. Step 3 below is enforced by `task check`; steps 1, 2, and 4 still
rely on the author, because nothing observes a commit:
1. detects authoritative definition or generator changes;
2. runs the generator;
3. runs `docsgen check` — enforced by `task check`;
4. refuses the commit when generated changes are unstaged or validation fails.
A commit MUST NOT be created while generated documentation is stale.
## Validation requirements
Generator tests cover:
- stable ordering;
- schema reference rewriting;
- `$defs` flattening;
- duplicate IDs and routes;
- registry coverage;
- comments and descriptions;
- secret redaction;
- obsolete-file removal;
- byte-identical repeated generation;
- check-mode diagnostics.
Repository-documentation validation covers:
- internal links resolve on the filesystem (repository-relative paths);
- absence of unrelated product names and URLs;
- absence of committed build artifacts and installed dependencies.
Renderer validation (frozen dependency installation, production build, expected
output routes) is added with the renderer decision and is currently unenforced.
The root module remains free of generator-only dependencies.
## Completion criteria
The documentation migration is complete when:
- `tools` belongs to Archie and builds against the working tree;
- `docsgen` consumes Archie-owned registries and types;
- AsyncAPI output describes Archie;
- required reference categories are generated as committed deterministic data;
- `catalog.json` matches the generated definitions and rendered routes;
- two consecutive generations are byte-identical;
- `docsgen check` detects changed, missing, and obsolete artifacts;
- build artifacts and installed dependencies are absent from source control;
- `task docs:generate` and `task docs:check` work from a clean checkout;
- every document describes Archie and every internal link resolves.
Renderer-dependent criteria (rendered reference pages, local authoring server,
deployable build, published site) are removed pending the renderer decision.
## Implementation references
- [GitHub-flavoured Markdown specification](https://github.github.com/gfm/) —
the dialect repository documentation is written in
- [pnpm](https://pnpm.io/) — required only if a future renderer chooses a
Node-based toolchain
-352
View File
@@ -1,352 +0,0 @@
# Identity
**Status:** Approved foundation; lifecycle details are deferred
**Date:** 2026-07-28
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
## Purpose
Identity answers which persistent actor owns or performed an action. It supplies
stable cross-domain attribution and lifecycle semantics.
Identity kinds include:
- the Archie system identity, such as `System` or `archied`;
- agent or bot identities;
- service-account identities;
- future user identities.
A user is another kind of identity rather than a separate foundation concept.
## Ownership
`internal/domain/identity` owns:
- immutable canonical `IdentityID` values;
- identity kind;
- lifecycle state;
- ownership and attribution semantics;
- identity-related commands and events.
Domains may record an identity reference on their own state and events when
ownership or attribution is required. They MUST NOT receive a complete
per-identity application configuration bundle.
Persona and communication style are separate from identity.
Every Agent has its own immutable acting `IdentityID`. Agent actions use that
identity for ownership and attribution in the same way an organisation records
which user accessed a resource, changed a permission, or performed another
auditable action.
Agent and Identity remain separate aggregates. Identity supplies the stable
actor reference; Agent owns assistant behaviour, memory, specialisation,
conversations, and capability context.
Agent identities MUST NOT be shared between Agents. Automated WorkflowExecutions
MAY eventually act through a dedicated service-account identity when a specific
unattended automation requires it. Such use is an explicit execution decision
and audit principal, not the default for Agents or a substitute for recording
the initiating user when one exists.
A Workflow is owned by an IdentityID and executes as its owner by default.
Future delegated execution MAY explicitly assign a different `RunAsIdentityID`,
including a user or service-account identity. Ownership, effective execution
identity, initiating identity, and delegation provenance remain distinct audit
facts.
## Canonical identity
Every identity has an immutable `IdentityID`. It is the only value used for
cross-domain ownership, attribution, routing, persistence, commands, and events.
Identity kind is explicit:
- system;
- bot;
- service account;
- user.
Display names are mutable and MUST NOT be used as identifiers. Forge usernames,
channel bot names, Git authors, provider account names, and other external
identifiers are bindings associated with an identity rather than identity
itself.
`System` is represented by a real identity and `IdentityID`. The empty string
MUST NOT retain special meaning as a legacy system identity.
Configuration refers to identities by `IdentityID` and supplies external
bindings and capability settings separately. Renaming an identity or changing an
external account MUST NOT change ownership or historical attribution.
Secret-bearing channel bindings remain configuration concerns rather than
identity data. In particular, `[chat.telegram].token` is a
`secret.SecretRef` resolved by the application through the configured secret
registry. It does not change the identity that owns or performs a chat action.
## Persistence
Identity records are durable domain state. The Identity domain's repository is
the source of truth; infrastructure implements its persistence contract.
Configuration MAY bootstrap a missing identity through an explicit, audited
creation operation and MAY propose runtime capability bindings for an existing
`IdentityID`. Configuration is not the identity registry.
Omitting an identity from configuration stops assembling the omitted runtime
capabilities. It MUST NOT delete the identity record, erase history, or make
historical references unresolvable.
Disabling or retiring an identity requires an explicit Identity-domain command.
Retired identities remain resolvable for historical attribution. A failed
external binding affects capability availability without destroying or silently
replacing the identity.
## Lifecycle
Identity lifecycle is deliberately small:
- `active`: may participate in runtime composition;
- `suspended`: deliberately prevented from initiating new work while ownership
and history remain;
- `retired`: terminal, unable to initiate work, and permanently retained for
attribution.
Allowed transitions are:
```text
create -> active
active -> suspended
suspended -> active
active -> retired
suspended -> retired
```
`retired` has no outgoing transition.
Capability health is separate from identity lifecycle. Forge, model, channel,
workspace, and other bindings report health independently. An active identity
may be partially degraded without becoming suspended or retired. Runtime
supervision isolates and restores affected bindings through the safe-change and
recovery protocol.
## System identity
Archie has exactly one built-in system identity. It is created during initial
store bootstrap, is strictly always active, and cannot be suspended or retired.
Its `IdentityID` and kind are immutable.
Startup, migration, supervision, remediation, and rollback actions performed by
the application use the system identity. The system identity MUST NOT be
delegated to individual identities. Every user, bot, service account, or other
actor mutation records the identity that actually performed it.
System capabilities may independently become unhealthy or unavailable without
changing the system identity.
## Target placement and contracts
The Identity domain lives at `internal/domain/identity`.
It owns:
- `IdentityID`, identity kind, display name, lifecycle, version, and audit
timestamps;
- create, rename, suspend, reactivate, and retire commands;
- corresponding lifecycle events;
- the repository contract required for durable identity records;
- lookup of current and historical identities.
External account bindings and capability settings remain with the domains that
use them and reference `IdentityID`.
## Migration constraints
Migration from the current string model MUST:
- bootstrap the permanent system identity;
- assign stable IDs to configured identities without losing their names;
- replace empty-string legacy ownership with the system identity;
- migrate tasks and sessions to canonical identity references;
- include identity where task uniqueness and transport deduplication require
independent ownership;
- route container RPC through the task owner's capability bindings;
- retain historical resolution after rename, suspension, or retirement;
- remove identity-string equality from authentication or access semantics.
This completes the foundation required to restructure the current Identity
behaviour. Exact storage schemas and Go method signatures belong to
implementation design, not this architecture review.
## Lifecycle
Identity lifecycle is deliberately small:
- `active`: may participate in runtime composition;
- `suspended`: deliberately prevented from initiating new work while ownership
and history remain;
- `retired`: terminal, unable to initiate work, and permanently retained for
attribution.
Allowed transitions are:
```text
create -> active
active -> suspended
suspended -> active
active -> retired
suspended -> retired
```
`retired` has no outgoing transition.
Capability health is separate from identity lifecycle. Forge, model, channel,
workspace, and other bindings report health independently. An active identity
may be partially degraded without becoming suspended or retired. Runtime
supervision isolates and restores affected bindings through the safe-change and
recovery protocol.
## Explicit non-responsibilities
Identity is not authentication and is not access control.
The current architecture does not require authentication or authorisation. Those
capabilities MAY be introduced later if deployment or product needs justify
them. They MUST remain separate from the identity model.
An identity reference therefore proves attribution within Archie's trusted
system model; it does not by itself prove credentials or permission.
## Per-identity configuration
Values selected for an identity remain external configuration values. At
composition time they are split into the runtime settings owned by the affected
domains and correlated by identity reference.
The existing `IdentityConfig` aggregate MUST be dissolved. Forge accounts,
repositories, models, providers, workspace behaviour, polling, budgets,
notifications, and transport namespaces retain their respective owners.
## Audit
Configuration changes and other state changes are actions attributed to an
identity. System-initiated changes use the system identity. Their audit records
MUST preserve the acting identity, the target, and the resulting change.
The command ownership and persistence mechanism for configuration changes is a
separate configuration-management decision.
## Current implementation
Identity is not currently implemented as a domain. It is a collection of string
fields and process-local associations:
- `config.IdentityConfig.Name` is the daemon routing key.
- `config.IdentityConfig.BotUser` is the external forge and Git author name.
- `daemon.IdentityRunner` bundles the configured name with a forge client,
worktree manager, repository list, configuration subset, logger, and polling
goroutine.
- `store.Task.Identity` persists the configured name on tasks.
- NATS task messages copy the same configured name.
- gateway routing accepts an identity name and uses it to select a repository
profile.
- gateway sessions persist `BotUser`, not the configured identity name.
There is no identity registry, identity record, identity lifecycle state,
identity persistence, or identity command/event model. Removing an identity from
configuration makes existing task ownership unresolvable.
An empty identity string selects the legacy single-identity path. This gives the
empty string behavioural meaning rather than representing a real system
identity.
## Current enforcement and isolation
## Withheld judgement verbs
`approve`, `reject`, `abandon` and `archive` are not exposed to an agent. An agent
that can approve can approve its own work, and the one control this surface exists
to keep is a human accepting it.
The constraint is attribution, not capability: a task action records the acting
identity and the authorising principal, so exposing the verbs requires that an
agent's action be recorded as an agent's and the authority it used recorded
separately. Until a surface carries both, the verbs stay withheld. This is the
reason the four verbs are absent from the dashboard's in-browser tools, and it is
why releasing them is a change to this boundary rather than a change to the tools.
The current implementation uses identity equality as an authorisation check for
chat task approval and cancellation. This conflicts with the approved rule that
identity is attribution rather than authentication or access control and must be
reassigned to an appropriate task-ownership or future access policy.
Focused tests verify that:
- a task resolves the forge client and repository list associated with its
configured identity name;
- cross-identity repository profiles do not leak;
- chat task creation propagates the selected identity;
- task persistence retains the identity string;
- chat task control rejects a different identity string.
## Current hazards
- Task uniqueness is `(owner, repo, issue_number)` and excludes identity.
Two identities discovering the same forge issue cannot own distinct task
records.
- NATS deduplication uses `owner/repo/issue` and excludes identity, so discovery
by a second identity can be discarded as a duplicate.
- Container-mode forge and worktree RPC servers are wired to the root clients,
not the task owner's clients. The source documents this as an unresolved
identity leak.
- The shared task queue claims the oldest task without identity partitioning and
relies on later string lookup to recover the correct runner.
- Sessions use forge bot usernames where tasks use configured identity names, so
there is no canonical cross-domain identity reference.
- Identity lifecycle is process lifetime only; there is no disabled, degraded,
retired, or unavailable state and no audit history.
The focused identity tests pass. Broader daemon and NATS suites could not open
embedded listener ports in the current sandbox; their failures occurred before
identity behaviour executed.
## Three-layer identity model
Agreed 2026-07-30; the frame for SOUL
([#68](https://github.com/samcharles93/archie-core/issues/68)) and the curator
([#435](https://github.com/samcharles93/archie-core/issues/435)).
Recovered 2026-08-09 from the pre-migration issue tracker.
**Layer 1 — invariants.** Instruction precedence, core rules, and the `<tools>`
and `<env>` blocks live in `internal/gateway/templates/archie.md.tpl` and are
unreachable at runtime by anyone.
**Layer 2 — SOUL.** User-authored identity: agent name, register, warmth.
Editable without a rebuild.
**Enforcing the Layer 1 / Layer 2 boundary.** SOUL is rendered as the
`Persona` field of `SystemPromptConfig` (`internal/gateway/prompt.go`) into a
`<soul purpose="identity_and_style" trust="data">` block, XML-escaped through
the same `xml` template helper used for tool and env metadata, and placed
_before_ `<instruction_precedence>` in `archie.md.tpl`. Escaping means SOUL
text can never forge a live `<core_rules>`, `<instruction_precedence>`,
`<tools>` or `<env>` tag -- an attempt renders as inert escaped text
(`&lt;core_rules&gt;...`), and `<instruction_precedence>` explicitly tells the
model the `<soul>` block is reference data, not an authority. This is
guarded by `TestBuildSystemPromptSoulCannotOverrideInvariants` in
`internal/gateway/prompt_test.go`, which renders a hostile SOUL that attempts
to countermand `core_rules` and asserts the real invariant tags stay singular
and their text stays intact. Keep this test in sync if the template's escaping
or block structure changes -- do not relax it to make a future SOUL feature
(e.g. curator-proposed edits) fit.
**Layer 3 — representation.** Curator-derived knowledge about the user. It may
only **propose** changes to SOUL and never apply them. If derived conclusions can
silently rewrite tone, personality drifts and the user loses the control SOUL
exists to give them. A proposal queue also makes the visibility requirement fall
out for free, since pending conclusions are inherently reviewable.
**Why SOUL comes first:** tone currently lives in Go string constants
(`DefaultPersonas` in `internal/gateway/persona.go`), so fixing a rude reply on
2026-07-29 required editing Go and rebuilding. SOUL is small, fixes a real
defect, and defines the boundary the curator must respect.
-16
View File
@@ -1,16 +0,0 @@
# Architecture
Archie is a personal agent platform built around six domain boundaries:
- Identity tracks users and other actors responsible for actions.
- Agent owns persistent assistants, specialisation, and continuity.
- Messaging owns conversations, messages, branches, and channel correlation.
- Workflow owns reusable, versioned behaviour definitions and their executions.
- Work Intake admits optional durable work without constraining ordinary agent
conversation or direct capability use.
- Plugin owns generic extension discovery and lifecycle; each capability family
owns its typed plugin contract.
The detailed architecture and migration decisions are maintained under
`docs/architecture/` in the repository while this generated site is being
assembled.
@@ -1,334 +0,0 @@
# Messaging and Work Intake
**Status:** Current state researched; foundation decisions in progress
**Date:** 2026-07-28
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
## Purpose
Archie is a personal assistant and general agentic system. Its interactions
include conversation, questions, notes, reminders, goals, message handling,
troubleshooting, infrastructure operations, server management, source changes,
and open-ended future capabilities.
A message to an agent is therefore not inherently a work request, and invoking
an agent is not inherently a WorkflowExecution.
Messaging and work intake are separate from the Agent System's durable workflow
execution model:
- messaging preserves interactions with people and external systems;
- an agent turn interprets and responds to an interaction using its available
capabilities;
- work intake handles the optional promotion of an interaction into durable,
workflow-backed work;
- the Agent System owns Workflow definitions and creates WorkflowExecutions.
Forge issues, Jira issues, Telegram messages, emails, webhooks, and future
channels remain peer external message or artifact sources. None becomes an
execution model merely because it can lead to work.
## Confirmed boundary
Work intake MUST NOT create a WorkflowExecution directly.
Inbound interactions normally route to the Agent selected by the channel
binding. The selected Agent retains its own memory, user knowledge, conversation
continuity, specialisation, and capability context. This continuity is
independent of the underlying model or provider.
Each selected Agent acts through its own immutable IdentityID. Interaction and
resulting action records preserve both that acting identity and the initiating
user identity when one exists.
Agent memory is private by default. Interaction context MAY additionally use
user-wide memory and intentionally global shared memory, but another Agent's
agent-wide memory is not part of the selected Agent's context.
Multiple users may interact with the same Agent. The channel binding and inbound
message MUST resolve both AgentID and initiating User IdentityID before
conversation or memory context is loaded. Sharing an Agent MUST NOT implicitly
share one user's private memory with another user.
An interaction may assemble memory from four scopes: global shared, the selected
Agent's agent-wide memory, the initiating user's authorised user-wide memory,
and the private Agent-user relationship memory addressed by both IDs.
## Conversation identity
Every conversation is identified by the complete tuple:
```text
AgentID
+ UserIdentityID
+ ChannelBindingID
+ ExternalConversationID
+ ThreadID
```
`ThreadID` has an explicit empty value for channels without threads. No element
of this key may be replaced by a display name, configured bot username, channel
type, or other mutable label.
Agent and user memory continue across conversations according to their memory
scope. Immediate conversation history and delivery correlation remain isolated
to the identified channel conversation or thread. Moving between Telegram,
email, or another channel does not create a new Agent or user, but it does
create a distinct conversation unless an explicit linking operation relates
them.
Conversation and message events support projections for channel-entry metrics,
use cases, volumes, outcomes, latency, capability usage, and other product or
operational analysis. Metrics are derived read models; they MUST NOT become
mutable counters embedded in the conversation aggregate or change message
routing semantics.
## Canonical messages
Every inbound, assistant, tool-call, and tool-result message has an immutable
application-generated MessageID. Platform identifiers are external correlation,
not substitutes for the canonical ID.
Messages are addressable because an interaction is more than text. A message may
contain assistant content, reasoning data subject to its retention policy, one
or more tool calls, a tool result with authoritative execution metadata,
attachments, reply relationships, edits, or other typed content. Stable
MessageIDs also allow sessions to branch from an exact prior point.
The canonical session and message implementation must supply:
- application-generated stable message IDs;
- user, assistant, and tool roles;
- assistant tool calls and correlated tool-result messages;
- authoritative tool-result status, timing, error, truncation, and size
metadata;
- session lifecycle and active-request state;
- session-to-agent-instance and parent-session lineage;
- durable database round trips and timestamp validation.
These semantics must use the confirmed Agent, user, channel-binding, and
conversation ownership model.
The canonical message store MUST preserve messages as immutable records and
represent later edits, deletions, and branches through related records or
events.
Archie requires exact branch-point correlation using stable MessageIDs.
## Conversation branches
A branch is a continuation of a previous conversation at an exact message. A
child conversation records:
```text
ParentConversationID
ForkMessageID
```
Messages remain an append-only linear sequence within each conversation. The
child's effective initial context is the parent's history through
`ForkMessageID`; messages after that point in the parent are not inherited.
After the fork, parent and child are isolated:
- child messages, tool calls, tool results, capability actions, and errors do
not appear in the parent conversation;
- later parent messages do not silently enter the child;
- returning to the parent resumes its unchanged history;
- the child may itself be branched using the same rules;
- branch lineage remains queryable for navigation, audit, and metrics.
This supports building substantial context about a subject and then performing
one or more contextual subtasks without polluting the original conversation. For
example, a user may branch from a project discussion, create Jira issues in the
child using inherited context, and then return to the project discussion without
adding the Jira tool transcript to the parent.
Branching does not copy mutable message rows. History is resolved through the
immutable parent conversation and fork MessageID, followed by the child's own
message sequence.
Branch isolation applies to conversation history, not to Agent learning or
memory. A memory action performed in a branch has exactly the same semantics as
the same action performed in any other conversation. It writes to its selected
global, agent-wide, user-wide, or Agent-user relationship scope.
Memory provenance MAY retain the source ConversationID and MessageIDs for
explanation and audit. Retrieval and effect are determined by memory scope and
access rules, not by the conversation from which the memory originated.
Returning to a parent does not insert the child's tool transcript into the
parent history, but scoped memories learned in the child remain available to
future retrieval wherever that scope is visible.
Changing sessions or branching therefore controls immediate conversational
context without preventing the Agent from learning durable knowledge.
## Target ownership
The Messaging domain lives at `internal/domain/messaging`. It owns:
- canonical Messages and typed message content;
- Conversations, branches, and lineage;
- channel bindings and external source correlation;
- replies, acknowledgements, and outbound delivery attempts;
- message and conversation lifecycle events;
- domain-defined repository and delivery service contracts;
- projections required for conversation navigation and metrics.
Work intake is a separate cohesive domain at `internal/domain/workintake`. It
owns admission, validation, deterministic routing, and accepted work requests
for the optional transition into durable workflow-backed execution.
Telegram, email, webhook, forge, Jira, and future messaging systems are
infrastructure adapters implementing Messaging contracts. They are users of the
domain; they do not own Messages, Conversations, work admission, or
WorkflowExecution semantics.
The Agent decides whether an ordinary interaction is answered directly, uses a
capability, changes or retrieves Agent-owned information, or proposes durable
workflow-backed work.
Explicitly configured automation MAY enter work intake without a conversational
Agent turn when the external trigger and admission rule already unambiguously
request durable work. This avoids spending an LLM turn to rediscover a
deterministic routing decision.
When an interaction requires durable workflow-backed execution:
1. a channel adapter produces a channel-neutral inbound message;
2. the acting agent handles or interprets the interaction;
3. work intake validates, admits, and routes a proposed work request;
4. work intake emits an accepted work request with its source correlation,
acting identity, requested outcome, inputs, and routing evidence;
5. the Agent System consumes that request, selects a specific Workflow version,
and creates the WorkflowExecution.
The accepted work request is a cross-domain handoff, not an alternate execution
aggregate. The Agent System is the sole authority that creates a valid
WorkflowExecution.
An interaction MAY instead be completed directly by an agent turn, delegated to
a tool or capability, recorded as a note or reminder, answered conversationally,
or retained for later context. Those paths MUST NOT require a Workflow or
WorkflowExecution.
A Workflow MAY add reusable, versioned structure to any of those behaviours.
Scheduled personal-assistant routines, message triage, reminders, infrastructure
operations, and other capability sequences are valid Workflow definitions. The
distinction is whether durable structured execution is useful, not whether the
subject originated from a forge.
## Canonical execution language
- **Workflow**: reusable, versioned behaviour definition.
- **WorkflowExecution**: durable execution of a specific Workflow version.
- **WorkflowStep**: a defined operation in a Workflow.
- **StepExecution**: the recorded execution and outcome of a WorkflowStep.
- **Attempt**: a retry within the same WorkflowExecution.
External issues, messages, requests, goals, and notes are not synonyms for these
concepts.
## Current implementation
Current intake is fragmented:
- Telegram, email, and webhook adapters translate payloads into
`gateway.Message`, while an unused richer `MessageEvent` contract exists
alongside it.
- `gateway.Router` combines local channel commands, conversational LLM routing,
and direct task lifecycle operations.
- Telegram is the only channel with production LLM and durable conversation
wiring. Email and webhook free text currently have no LLM responder.
- Forge polling bypasses the gateway and directly enqueues store rows or NATS
task messages.
- Chat `/spawn` directly creates a `store.Task` and invents a synthetic forge
issue number to satisfy the existing persistence key.
- Forge replies and chat approval commands implement separate waiting-human
paths.
- Message delivery, acknowledgement, retry, deduplication, and source
correlation are platform-specific side effects rather than one durable model.
- `store.Task` collapses an external source reference and durable execution
state.
## Intake provenance
A task's origin determines which enqueue path created it, though every origin
converges on the same `tasks` table and the same `Route`/`Run` lifecycle once
queued.
- Forge-sourced work -- discovered by polling or, in single-identity
deployments, delivered by the forge webhook receiver (`internal/forge/webhook`)
-- enqueues through the same `workintake.TaskEnvelope` and `PublishTask` path.
`TaskEnvelope.IdempotencyKey` is keyed on `owner/repo/number` and not on the
delivery source, so a webhook-delivered issue and a later poll of the same
issue dedup through `PublishUnique` instead of double-enqueuing.
- Chat-spawned and playbook-binding-dispatched work enqueues through
`EnqueueChatTask`/`EnqueueBindingTask` (`internal/infrastructure/postgres`), stamped with
`binding_id`/`binding_version` for provenance.
Webhook intake is opt-in per deployment (`Forge.Intake` = `poll` (default),
`webhook`, or `both`) and single-identity only: a config naming
`webhook`/`both` alongside `[[identities]]`, or setting intake on a
`[identities.forge]` entry, is rejected at validation rather than started with
the setting ignored. One receiver binds one secret and one dispatch predicate,
so it cannot judge a second identity's events by the right rules. A
multi-identity deployment polls per identity until per-identity intake lands.
The decided contract is `docs/prds/event-sources-and-reactions.md`; the binding
model and its threat model are `docs/architecture/bindings.md`.
## Current hazards
- Treating every agent interaction as a work request would remove Archie's
personal-assistant role and force conversation and immediate capability use
through an inappropriate workflow lifecycle.
- Treating every accepted work request as a WorkflowExecution would let intake
or channel code select versions and construct invalid execution state outside
the Agent System.
- Source identity is incomplete: sessions use configured bot usernames, tasks
use identity strings, and external message IDs are generally absent.
- Database and NATS deduplication are based on forge coordinates rather than a
channel-neutral source-message reference.
- Replies and acknowledgements have no durable delivery-attempt lifecycle, so
partial success and retry behaviour differ by adapter.
- Production code has two competing channel-neutral message contracts.
- The existing Archie session implementation lacks the required tool-call
semantics and exact branch lineage and MUST be brought to the canonical
contract.
## Decisions still required
- the cohesive owner and final location of messaging behaviour;
- the cohesive owner and final location of work-intake admission and routing;
- the canonical inbound message, conversation, and source-correlation model;
- the boundary between an agent turn, direct capability use, and a proposed
durable work request;
- the exact relationship between an Agent, its acting IdentityID, its user, and
its channel bindings;
- outbound response, acknowledgement, delivery-attempt, retry, deduplication,
and failure semantics;
- the smallest accepted-work-request contract consumed by the Agent System;
- migration of forge polling, replies, chat commands, email, webhook, Telegram,
and Jira integrations.
## Non-goal: semantic search over chat messages
Semantic/vector search over chat messages is an **explicit non-goal** until usage
data shows a real need.
Message search is lexical only: session-scoped PostgreSQL full-text queries paged via
`MessageQuery{Query,Limit,Offset}` → `MessagePage`. Do not add embeddings
configuration or vector columns to message records.
The rationale is cost without a demonstrated use case. Measured 2026-08-03 with
`embeddinggemma:300m` — note this was never an infrastructure problem, the model
was already pulled and `ai-sdk/provider/ollama` already has `embed.go`:
- 121 ms median warm per message on the write path, 12.5 s cold;
- 768 dims = 3072 bytes per vector, roughly 15× a typical message payload;
- chronological reads would carry vector data they do not use on the hot path
of every turn;
- similarity search requires an explicit indexing and retention design.
If this is revisited, vectors belong in a sibling table so chronological reads
never load them.
-823
View File
@@ -1,823 +0,0 @@
# Architecture Migration Decisions
**Status:** Active migration inventory
**Date:** 2026-07-28
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
## Purpose
This document records what remains to be decided before Archie's current
implementation can be migrated into the approved domain-oriented structure.
The product and core domain model are not being redesigned. Existing Archie
behaviour and the existing session implementation are the migration
baseline. Remaining decisions MUST be grounded in current packages, consumers,
tests, persistence, and runtime wiring.
## Confirmed domain packages
```text
internal/domain/
identity/ (approved, not yet materialised as a package)
agent/ (approved, not yet materialised as a package)
workflow/
messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)
workintake/
plugin/ (approved, not yet materialised as a package)
curator/
mapping/
scheduling/
```
- `identity` owns persistent actors, lifecycle, ownership, attribution, and
audit identity.
- `agent` owns persistent assistants, specialisation, instructions,
model-independent continuity, capability context, and associations with
identity and memory.
- `workflow` is a separate domain. It owns reusable, versioned Workflow
definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts,
outcomes, and typed Workflow plugin contracts.
- `messaging` owns canonical Messages, Conversations, branches, channel and
source correlation, replies, acknowledgements, delivery attempts, events, and
projections.
- `workintake` owns admission, validation, deterministic routing, and accepted
work requests for the optional transition into durable workflow-backed
execution.
- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle
mechanics. It remains metadata-only; capability semantics and typed
registration belong to the owning domain.
- `curator` owns the curator engine family: long-running agent loops that
reason over memory and perform maintenance tasks on a declared shape
(check-in interval, tool set, attached memory engine). See epic
archie-core-yp9.
- `mapping` owns the payload field-mapping vocabulary: binding named fields to
JSON paths inside a captured webhook payload, and detecting drift. See
`docs/prds/payload-field-mapping.md`.
- `scheduling` owns the ticker engine: deciding when a scheduled job runs and
with what concurrency. It declares `JobSource`/`Runner` contracts and owns
no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.
**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed
in the tree without being added to this list when their epics landed. They are
confirmed as legitimate, narrowly-scoped domains under the same rules as the
original six — each owns one capability family, declares typed contracts, and
has no cross-domain reach. This list was out of date, not the tree.
Conversely, `identity`, `agent`, `messaging`, and `plugin` are approved target
domains that do not yet exist as packages. Their behaviour currently lives in
pre-migration packages (see "Complete package destination map" below for the
full inventory). Do **not** create empty stub packages for them ahead of an
actual migration PR — an unused stub is dead code and gives no test coverage.
Each materialises when its corresponding migration decision below is resolved
and implemented in the same change.
Memory's final package placement remains undecided pending focused review of the
existing implementation.
The following are approved shared or composition packages, not domains:
```text
internal/eventbus/
internal/policy/
internal/infrastructure/
internal/app/archied/
internal/app/agentworker/
```
## Remaining migration decisions
### 1. Complete package destination map
Every current package MUST receive one explicit disposition:
- move into a confirmed domain;
- move under infrastructure as an implementation of a domain-owned contract;
- move into application composition;
- merge with an identified duplicate;
- remain as an approved shared application contract;
- move to a plugin, extra, deployment, example, or generated artifact;
- be deleted after its replacement is proven.
The largest unreviewed areas include memory, tools and capabilities, workspace
and worktree behaviour, gates, storage, events, web UI, containers, RPC
packages, release management, and scheduling.
The destination matrix MUST name the behaviour owner, target path, dependencies
to remove, state and contracts to preserve, migration prerequisites, and
deletion criteria.
**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**
The current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator
authentication, UI response projection, configuration reads and mutations,
task/control APIs, and direct adapters to State Store, channel, event/log,
memory, curator, workflow, forge, and Gateway runtime values. The target owner
is a standalone UI application process; `internal/webui` remains its HTTP
transport adapter, while Gateway, State Store, configuration, Work Intake,
Messaging, and other capability owners expose the contracts behind those
routes. The migration preserves retained route schemas, auth/CSRF behaviour,
task/capture/mapping/binding/session continuity, SSE replay semantics, and
committed generated SPA assets. Prerequisites are the ratified UI boundary,
route-owner inventory, narrow remote adapters, configuration/auth/readiness
contracts, and process/conformance tests. Remove the shared live
`config.Holder`, direct event/log bus, daemon stopper, forge client, channel
manager, capability registries, composite store access, and in-process UI
listener only after the focused criteria in
[`docs/prds/ui-service-boundary.md`](../prds/ui-service-boundary.md) pass in
production composition. The old construction and listener are deleted in the
same cutover change; no second UI authority remains.
### 2. Session and Messaging migration
The existing session implementation is the migration baseline. The migration must
decide:
- which session and message components are retained or adapted;
- how Agent, user, channel, Conversation, and branch ownership are added;
- how Archie's parallel gateway session implementation is replaced;
- how canonical Messages become immutable persisted records;
- how existing sessions and messages are migrated;
- how outbound delivery, retry, acknowledgement, deduplication, and failure
semantics are represented;
- how current Telegram, email, webhook, forge, and Jira integrations migrate to
Messaging infrastructure adapters.
The following are already decided and MUST NOT be reopened without contradictory
implementation evidence:
- the composite Conversation identity;
- immutable MessageIDs;
- typed tool-call and tool-result messages;
- exact branch lineage through ParentConversationID and ForkMessageID;
- parent and child transcript isolation;
- normal scoped-memory behaviour regardless of the originating Conversation;
- Messaging and Work Intake ownership.
**Decision (2026-08-31), resolving the open questions above:**
`internal/gateway/` is the "parallel gateway session implementation" this
section names. It is retained as-is for now — a big-bang rewrite of live
session/compression/approval/branch logic across Telegram, web UI, email, and
webhook channels in one change is exactly the "convoluted to satisfy edge
cases" failure mode CLAUDE.md's Revert-on-Flail rule warns about, and would
risk silent behavioural regressions in the one path every user-facing message
travels through.
Instead, `internal/domain/messaging/` is materialised now with the pieces
that are already decided and don't require touching gateway: the canonical
`Message` and `Conversation` types (composite Conversation identity, immutable
`MessageID`, typed tool-call/tool-result message variants, branch lineage via
`ParentConversationID`/`ForkMessageID`). These are pure domain types with no
gateway dependency — a new package, not a rewrite of an existing one.
Migrating `internal/gateway/`'s session, compression, approval, and branch
logic onto these types is real, cross-channel-risk work and is **not** done in
this pass. It is tracked as separate, appropriately-scoped bd issues (see
`bd list --label messaging-migration`), sequenced channel-by-channel so each
lands with its own behavioural verification instead of one large diff no one
can safely review.
**Amended 2026-09-15.** `internal/infrastructure/gatewayrpc.StoreClient` is the
adapter this migration will need: it implements `messaging.SessionStore` over
the chat service's session-store RPCs and is proven by
`TestStoreClientPreservesCanonicalRecords`. It is deliberately unwired.
Production `archied` dials the standalone gateway for `ChatContract` only
(`composeChatContract` → `gatewayrpc.Dial` returns a `*Client`, not a
`*StoreClient`), and the Gateway's session store is PostgreSQL via
`gateway.NewPostgresSessionStore`. The test comment that says it mirrors production
describes the target, not today's tree. Kept rather than deleted because the
migration it serves is deferred by this very section, and re-deriving a tested
wire adapter once that lands is pure cost.
**Phase 4 Messaging Service extraction (2026-09-19, `archie-core-8cda.6.1`).**
The process boundary for external channels (Telegram, email, webhook) is ratified
in [`docs/prds/messaging-service-boundary.md`](../prds/messaging-service-boundary.md).
Messaging is extracted into `cmd/archie-messaging` / `internal/app/archiemessaging`,
calling Gateway's `messaging.ChatContract` exclusively over gRPC. Channel frontends
hold no direct database handles, daemon state, or model runtimes.
**Telegram operator surface after extraction (2026-09-19, `archie-core-8cda.6.6`).**
`setupTelegramGateway` wired eight `telegram.Gateway` seams the daemon could
satisfy from its own process. Each is resolved by where the fact it needs is
actually owned, not by where it used to be built:
| Seam | Resolution |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Version` | Sourced from the Gateway via `ChatSnapshot.Version`. The Messaging Service never renders its own build into `/version`; `cmd/archie-messaging` does carry a `buildinfo` release stamp (added by `archie-core-k94o`, see the amendment below) for the updater's skew check and update verification, but `/version` still shows the Gateway's block so a partially upgraded deployment cannot report itself as matched. |
| `Updates` (`/update`) | Built in the Messaging Service from `[chat.telegram].update_check_command` / `update_install_command` — its own configuration. `Enrich` is dropped: `componentInstallTypeEnricher` reads `[nats]`, which this service must not decode, so the check command's own reported install type stands unmodified. |
| `UpdateReportPath` | A local state file under `work_dir`, keyed by the same `sha256(bot_user)[:8]` scheme the daemon used, so a pending report is found rather than written afresh. |
| `ReleaseAnnouncements` | **Still left nil**, but no longer for the `RunningVersions` reason (that seam now self-reports — see the amendment below). `releaseannounce.Announcer` announces nothing unless each `Component` carries a parseable version, and the only version this process can vouch for is its own daemon-release stamp, not the agent's. Wiring the announcer without them yields a no-op that reads as configured, so it stays unwired until component self-reporting exists. |
| `SetShowToolCalls` | Projected from `[chat].show_tool_calls`. |
| `Reload` | Local: re-resolves the token and allowlist from this service's own config file and overlay. Reload was never a daemon fact. |
| `RunningVersions` | **Wired from this process's own release stamp** (`archie-core-ot33`; see the amendment below). `archie-messaging` is one of the processes in the archied release set (the installer's `GATEWAY_SERVICES`), built from the same `archied/v*` tag and stamped with `buildinfo.Version` by every build site, so its compiled-in build is evidence that the release the installer claims actually reached this host. It reports `daemon = buildinfo.Version` and reports nothing for `agent` (task-scoped, observed only through `daemon.AgentStatus`), leaving the agent Unverified. The Gateway's rendered block is deliberately not used: that is a different process's stamp. |
| `Dangerous` | Stays nil. No daemon composition ever set it; `/rollback` and `/stop` reported "not configured" before the extraction and still do. |
The Messaging Service consequently reads `work_dir`, `bot_user`, `[chat]` and
`[health]` in addition to the PRD's `[chat.*]` / `[services.gateway]` list.
`[health]` is the daemon's health URL, which `releaseupdate.CommandInstaller`
polls from outside to confirm an update came back up; the rest of the PRD's
prohibition list is untouched.
**Amended 2026-10-02 (`archie-core-ot33`, Telegram `RunningVersions`).** The
2026-09-19 decision left `RunningVersions` nil because it judged this process
could obtain only another binary's stamp. That was true when written and stopped
being true three days later: `ec0f17a7` (`archie-core-k94o`) gave every host
binary, `archie-messaging` included, a `buildinfo.Version` self-report so the
updater could detect per-binary skew. `cmd/archie-messaging` now registers
`buildinfo`'s `-version`, and every build site (`install.sh`,
`scripts/archie-update-install`, `.github/workflows/deploy.yml`, `Taskfile.yml`)
stamps it with the same `archied/v*` release as the rest of `GATEWAY_SERVICES`.
The messaging process therefore vouches for the `daemon` component from
`buildinfo.Version` — its own compiled-in build, never the Gateway's rendered
block — and reports nothing for the agent. A relayed update report can now
confirm the daemon and still names the agent as unchecked, while a binary the
update did not replace reads as drift. `ReleaseAnnouncements` stays nil: it needs
a version for every component, and this process can vouch only for itself.
**Phase 4 messaging severance: what must move, and the decision the PRD does
not cover (2026-09-22, `archie-core-1ng1`).** The PRD's deletion gate cannot
pass today. `cmd/archie-messaging/architecture_test.go` does not exist, and the
check that section specifies -- `go list -deps ./cmd/archie-messaging` links
zero banned runtime packages -- reported four at the time (the task store was
then `internal/store` over `modernc.org/sqlite`; the gate now bans
`modernc.org/sqlite`, `github.com/jackc/pgx` and
`internal/infrastructure/postgres` in its place):
| banned package | PRD category |
| -------------------------- | -------------------------------------------------------- |
| `modernc.org/sqlite` | State Store |
| `internal/store` | State Store |
| `internal/domain/workflow` | Workflow engine |
| `internal/agentexec` | Workflow engine, via `internal/domain/workflow/agent.go` |
All four arrive through one import: `internal/app/archiemessaging/run.go`
imports `internal/app/controlplane`, whose own dependency set is exactly those
four. The Messaging Service uses three symbols from that package
(`NewRPCClient`, `RuntimeChatConfig`, `ChannelSettingsKind`); the package also
carries the store-backed `ResourceStore` server, the `Definition` registry and
the workflow step vocabulary. Sever the package. Amending the gate to tolerate
`modernc.org/sqlite` and `internal/store` is rejected: a boundary you whitelist
around is no longer a boundary.
**What moves.**
- Every kind constant. They are strings with no dependency, and the client names
them.
- The channel-settings vocabulary and its decode: `channelSettings`,
`telegramSettings`, `webhookChannelSettings`, `emailSettings`,
`rateLimitSettings`, `channelDuration`, and `decodeRenamingLegacyKeys`.
- The generic client: `Client`, `NewRPCClient`, `RuntimeConfig` with
`runtimeConfigFrom`, `runtimeChatConfigFrom`, the other `runtime*From`
projections, and the `resourceReader` interface.
- The persona watch (`WatchPersonas`, `AppliedPersonas`), which needs only
`internal/domain/agent`.
- `executionSettingsDocument`, the document alone.
**What stays, and why.**
- The store-backed server: `Server`, `NewServer`, `ResourceStore`,
`ImportConfig`, `SeedSkip`, the `Definition` registry, and every other kind's
seed, validator and `Normalize` hook.
- `WorkflowDefinitionsClient` and `stepRegistry`, which decode through
`internal/domain/workflow`.
- `WatchWorkflowExecutionSettings` and `decodeSettings`: `decodeSettings`
returns and validates `workflow.ExecutionSettings`, so any package holding it
links the workflow domain and therefore `internal/agentexec`. This is why the
client cannot move as one package -- see open question 2.
- The schedules document, whose type is `scheduling.JobSpec` in
`internal/domain/scheduling` -- the vocabulary moved there when the legacy
file-backed cronstore was deleted, which is also what satisfies the rule
that a domain vocabulary package may not import infrastructure.
- The schema derivation, which describes the documents the server advertises.
**Placement as landed (2026-09-22, `archie-core-1ng1`).** One new package,
`internal/infrastructure/controlplanerpc`, holding both the vocabulary (kinds, the
channel-settings document and its decode) and the client
(`NewRPCClient`, `Query`, `RuntimeChatConfig`, the exported `ResourceReader`, the
wire sentinels and `ClientError`). A second `internal/domain/controlplane` package
for the vocabulary was planned and then measured out of the design: the vocabulary
has exactly one consumer, the client that projects it, and the store-backed side
reads the same definitions through type aliases rather than a copy -- so a separate
domain package would have been a package with one consumer and a second name for
one thing. What made that safe is a measurement, not a preference:
`internal/app/controlplane` was the ONLY direct import of the Messaging Service
that dragged a banned runtime (`gatewayrpc`, `staterpc`, `applystatus`, `messaging`,
`configuration`, `readiness` and `health` were all clean), so severing that one
dependency is sufficient, and the severance needed no third package. Promoting the
vocabulary to a domain package stays open for the day a second consumer appears.
**Settled by the implementation.** Two of the four open questions this decision
originally left are answered, in both cases by measuring rather than by preference:
- The client did NOT become two packages. `WatchWorkflowExecutionSettings` and
`WatchPersonas` stayed on `internal/app/controlplane`'s `Client`, which now
_embeds_ the new one, so the daemon's validated watch is still defined once and
the read path still has one implementation -- which is what the second package
was for -- with one fewer package to keep in step.
- The schedules and workflow documents stayed put, and
`internal/domain/workflow/task` is linked deliberately: it carries the Task
status and view vocabulary, its own dependency set holds none of the banned
runtimes, and `cmd/archie-messaging/architecture_test.go` carries it as an
exception checked in both directions (the same entry, for the same reason, as
`cmd/archie-ui/architecture_test.go`).
**Still open.**
1. Does the server also leave `internal/app/`? `organisation.md` reserves
`internal/app/` for wiring and composition, and a store-backed gRPC server is
infrastructure -- but the gate does not require the move, and it would multiply
the diff across archied's wiring and the State Store binary. Tracked as
`archie-core-8f4n`.
2. Does `internal/domain/workflow`'s contract/engine split happen, and when? A
contract type (`WorkflowDefinitionCollection`) drags `internal/agentexec` only
because `agent.go` sits beside it. Independent of this severance, tracked as
`archie-core-inh6`, and the shape `archie-core-8cda.7` will meet again.
3. Does the vocabulary move to a domain package when a second consumer appears?
**Both consumers keep compiling.** archied imports the new vocabulary for the
kinds it names and the new client package for `RuntimeConfig` and the persona
watch, and keeps `internal/app/controlplane` for the server, the registry,
`ErrVersionConflict` and the workflow-aware pieces. The State Store binary
continues to call `NewServer` and `ResourceStore` unchanged. The Messaging
Service then imports only `internal/infrastructure/controlplanerpc`,
`gatewayrpc` and `staterpc`, so `go list -deps ./cmd/archie-messaging` loses all
four banned packages and the gate can land green.
**Channel state to the dashboard: one administrative surface, following the
config-snapshot precedent (2026-09-22, `archie-core-8cda.6.8`).** The Messaging
Service now records its channels' lifecycle -- `internal/channels/status.Manager`,
one entry per composed channel, written by each channel's own report through
`channels.Lifecycle` -- and nothing reads that across a process boundary.
`/api/channels` answers with nothing because `webui.Server.Channels` has no
production source, and POST `/api/channels/{id}/reload` answers 501 for the same
reason. The carrier is the State Store, and the shape is the one
`archie-core-ymut` already established for config snapshots
(`docs/prds/state-store-contract.md`, "the one surface whose writer is the daemon
and whose reader is the UI process"): a pair of administrative RPCs, deny-by-default
under `authorizesTaskScopedCall`, so a task-scoped grant reaches neither.
What that decides, so the implementation need not invent it:
- A channel's state is **runtime** state, not a settings document. It does not
belong in the `ControlPlaneService` resource kinds, which are validated,
versioned documents seeded from config; a channel that is failed is not a
document anybody edits.
- The reader is the UI process, which already dials the State Store and pumps its
cursor, so the surface needs no new transport in either direction.
- Adding the pair changes the contract's RPC count, so
`docs/prds/state-store-contract.md`'s grouped table gains a group in the same
change that adds the RPCs -- the table is the contract's own index, and a
surface it does not list is a surface nobody finds.
**Reload gets its own surface, with its own lifetime (decided 2026-09-22).** Reload
runs the other way -- the UI asks the service to reload a channel -- and the two
candidates were a request surface the service observes and clears, or a field on
the status surface the service watches. It is the first. The reasoning, recorded
because it would look arbitrary later:
- A request queue and a status report do not share a lifetime, so they should not
share a surface. A pending request is transient and has an outcome; a channel's
state is durable and has a current value.
- A "please reload" field on the status resource makes READING status capable of
RETRIGGERING an action, and makes a transient request indistinguishable from
state the moment anything polls it.
- It would also invert the writer/reader relationship the precedent establishes:
the service would have to clear a field on an object whose whole contract is
that the service reports it.
So the status surface stays writer-is-service, and the request carrier is its own
object with its own states.
`archie-core-8cda.6.9`'s component self-report is the **same shape**: a process
reporting something about itself for the UI to read. Whether it shares this
surface or gets its own is a decision for `6.9`, and the one outcome to avoid is
two homes for "what a component reports about itself".
### 3. Identity data migration
The migration must define:
- the durable identity schema and repository implementation;
- bootstrap of the permanent system identity;
- stable IdentityIDs for existing configured Agents;
- migration from configured identity names, empty-string ownership, and bot
usernames;
- preservation of historical attribution;
- identity-aware uniqueness and transport deduplication;
- correction of container and RPC capability resolution so execution uses the
owning identity's bindings;
- removal of identity-string equality from access-control behaviour.
Exact schema and method signatures are implementation decisions. The approved
Identity lifecycle and attribution semantics are fixed migration constraints.
### 4. Workflow migration
The current implementation must be transformed deliberately:
```text
store.Task -> WorkflowExecution
mutable Stage -> StepExecution history
RetryCount / Attempt -> Attempt records
workflow.Registry -> versioned Workflow definitions
current stages -> WorkflowStep definitions or Workflow plugins
```
The migration must decide:
- Workflow definition and version persistence;
- the smallest accepted-work-request contract consumed from Work Intake;
- the enforced WorkflowExecution state machine (proposed in
`docs/prds/execution-tree-state-machine.md`);
- atomic state and domain-event persistence;
- migration of existing task rows and transition history;
- disposition of current skill, Yaegi, and stage-plugin implementations;
- the versioned worker-handoff contract;
- scheduler, claim, retry, crash-recovery, and waiting-human cutover.
Workflow remains a separate domain from Agent. A user or Agent may define or
invoke a Workflow, but Workflow semantics and plugins remain Workflow-owned.
### 5. Memory placement and storage
The four required scopes are fixed:
- global shared;
- Agent-wide;
- user-wide;
- Agent-user relationship.
A focused review of `internal/memory`, its providers, consumers, persistence,
and tests had these decisions:
- `internal/domain/memory` versus ownership within the Agent domain — settled
(2026-09-02, below);
- the authoritative memory record and revision model — settled by the PRD
(2026-09-16, below);
- provider and infrastructure boundaries — settled by the PRD (2026-09-16,
below);
- retrieval and access enforcement — settled by the PRD (2026-09-16, below);
ranked retrieval remains open (below);
- migration of existing memory data — open: existing data is not migrated;
- provenance representation — settled by the PRD (2026-09-16, below).
Conversation branches do not create another memory scope. A memory action has
the same scoped effect regardless of which Conversation originated it.
**`internal/domain/memory` ownership — DECIDED (2026-09-02).** The typed
engine family lives at `internal/domain/memory`
(archie-core-1786637490069-11-e245c170), mirroring `internal/domain/curator`'s
contract/registrar/registry split. Not owned within the Agent domain: memory
is consumed by more than agent turns (curators, per archie-core-1786637499636)
and the plugin engine rule requires its own family, not a capability bolted
onto another domain's contract.
**Authoritative record and revision model for the builtin engine — DECIDED
(2026-09-02),** scoped to unblock archie-core-1786637499480 (ship the
file-writing store as the default engine). This decides only the builtin
engine's mapping onto the new `Record{ID}`/`Forget(id)` contract, not the
memory model in general or a future non-file engine's model:
- `internal/memory/builtin.Store` is unchanged. It has no concept of a
stable per-block ID — blocks are addressed by content substring — and nothing
in this decision requires changing that; existing `internal/memory` tests
keep passing unmodified, per that issue's acceptance criteria.
- A new infrastructure adapter (`internal/infrastructure/memory`, per
`organisation.md`'s "infrastructure implements domain contracts" rule — not
under `internal/domain/memory`, which stays contract-only) wraps one
`builtin.Store` per identity.
- **Identity → directory:** `hex(sha256(identity))`, not the identity string
itself. Closes the path-traversal question without an allowlist regex, and
sidesteps collisions from identities that differ only in characters a
filesystem treats as equivalent.
- **Record ID:** assigned once at `Write`, independent of content, so a later
edit elsewhere in the file can never orphan a `Forget`. Realised as a
leading marker line (`<!--mem:<ulid>-->`) on the block `builtin.Store.Add`
writes; `Query`/`List` strip it back out of `Record.Content` before
returning, and `Forget(id)` locates the block by that unique marker via the
store's existing substring-based `Remove`. The marker is a pragmatic,
reversible choice — plain-text records stay human-readable and
human-editable, at the cost of one marker line an operator editing the file
by hand should leave alone. Revisit if/when provenance representation
(still open, below) settles on something richer.
- **Kind → section:** `Observation.Kind` (default `"general"` when empty) is
the section name, reusing `builtin.ValidateSectionName` — so an
invalid `Kind` fails `Write` with the same validation error `memory_edit`
already returns for an invalid section today, not a new error shape.
**Memory engine: scopes, CRUD with retained revisions, and store placement —
DECIDED (2026-09-16).** Supersedes the 2026-09-02 "Authoritative record and
revision model for the builtin engine" entry above, whose `<!--mem:<ulid>-->`
live marker cannot carry provenance. Authority:
[`docs/prds/memory-engine-unification.md`](../prds/memory-engine-unification.md)
(Approved); the contract is `internal/domain/memory/contract.go`. This register
supersedes; it does not erase.
- **Four typed scopes, caller-named.** `internal/domain/memory` is addressed by
`Scope{Kind, Agent, User}` over `global`, `agent`, `user` and `agent-user`,
with `Validate` rejecting a component present where it is not required. A
caller names the read and write sets (`Subject.Scopes()` /
`WritableScopes()`; global is never model-writable) and the engine applies no
policy of its own: **access control is naming a scope, and nothing else.** An
engine that enforced policy would need to know about channels, sessions and
bindings, and every backend would reimplement it. `Scope.Key()` length-prefixes
each component, so two scopes can never share a key even when an opaque
channel-native id embeds the separator.
- **The caller resolves identity; the engine never does.** Resolution happens in
the gateway turn path, where the native sender id and the session are both in
hand, and is supplied per channel by the composition. A webhook's sender id is
a route path, not a person, and treating it as one would give a URL an
identity. An absent user id yields global and agent scopes only: "show none of
it", never a wider fallback.
- **CRUD supersedes, never overwrites.** `Store` is `Create`/`Get`/`Query`/
`List`/`Update`/`Forget`/`Revisions` over the four scopes. `Update` appends the
superseded state to the scope's `HISTORY.md` before replacing the live block;
`Update.Expected` names the revision being replaced and returns
`ErrStaleRevision` on mismatch, making a lost update between two processes
sharing one scope file detectable. `Forget` records a deleted revision before
removing the live block, so a record's provenance outlives its content; `Get`
and `Forget` take a scope, because an id alone does not locate one.
- **Provenance representation.** The live marker becomes JSON, since a
`<!--mem:<ulid>-->` line cannot carry provenance, and `Record` retains the
provenance `agent-system.md` requires — scope, author, originating user,
source, and revision history. `Metadata` is dropped: it never round-tripped.
- **Store and scanner placement.** The markdown store relocates to
`internal/infrastructure/memory/builtin`, its correct home under
`organisation.md`'s "a package owns its on-disk format end-to-end". The content
scanner moves into `internal/domain/memory` and is applied in `Create` and
`Update` — the single choke point every producer crosses, so curator-extracted
content is covered too.
**Open in this section.** Ranked retrieval is deferred: `Query.Text` stays in
the contract, unused by the prompt path. Existing memory data is not migrated:
`<workDir>/memory` and `<workDir>/memory-engine` are left on disk, unreferenced.
The PRD leaves these undetermined and they remain open here: group-chat
extraction, where the curator fails closed on mixed-sender sessions; two
processes (`archied` and `archie-gateway`) holding one scope file, where
`Update.Expected` detects but does not prevent a lost block; unbounded
`HISTORY.md` with no compaction policy; whether the per-scope size bound is
right; and whether the dashboard should carry a user identity.
### 6. Runtime and process boundaries — DECIDED
`archied` is the native resident orchestration and interactive-chat process.
Every autonomous repository workflow crosses one full-task core-NATS handoff
into a task-scoped `archie-agent` container. Embedded versus external NATS
changes broker deployment only; it never selects an executor. The former host
in-process runner, per-stage NATS protocol, and subprocess runner are removed.
Forge, store, and worktree authority remains in `archied` and is exposed to the
task container through scoped RPC services. The worker runs the workflow and
its worker-local ai-sdk loop; it does not receive forge credentials or direct
store access. See `docs/prds/embedded-nats.md`.
**UI Service boundary — RATIFIED (2026-09-07).** Phase 3 has a focused
authority record in [`docs/prds/ui-service-boundary.md`](../prds/ui-service-boundary.md).
The UI Service owns HTTP/SPA delivery, UI DTOs, browser authentication, and
its own endpoint/credential/readiness settings. It consumes Gateway and State
Store contracts and does not receive `config.Holder`, daemon pointers, SQL or
store implementations, workflow registries, forge/channel/model runtimes, or
resolved secrets. The current `internal/webui` implementation remains inside
`archied` until the ratified migration gates prove route parity, adapter
selection, failure/readiness behaviour, and deletion of the shared-holder and
direct-access paths. The extraction cutover removes the in-process UI
listener in the same change; there is no dual-live UI authority.
**Dashboard live event delivery — DECIDED (2026-09-09, `archie-core-za9f`).**
The extracted UI receives live activity by polling the State Store's existing
`EventsSince` cursor, not by a new push-subscription RPC. No proto change, no
contract amendment beyond this record.
The UI process runs one event pump. It primes its watermark by paging
`EventsSince` to the end at startup without delivering, then polls
`EventsSince(watermark, limit)` on an interval and hands each new event to
`webui.Server.Broadcast`, exactly where `internal/app/archied/main.go`'s
`persistAndBroadcastEvents` hands events to it today. One pump serves every
connected browser, so cost is one indexed query per interval regardless of
viewer count, and `Broadcast` is a no-op when nobody is watching.
Three properties make the cursor sufficient, and a push hub unnecessary:
- **The cursor cannot skip.** `internal/infrastructure/postgres` takes an
advisory event-append lock around each insert (`TestEventInsertsCommitInIDOrder`),
so a row's `id` is assigned in commit order. There is no window in which a lower id becomes visible after a
higher one, which is the failure mode that normally rules out polling an
autoincrement cursor. SSE catch-up already depends on this same property.
- **A broadcast is a wakeup, not the payload.** `sseStream.drain` treats each
broadcast event as a signal to fill the persisted gap ahead of it via
`catchUp`, then delivers the event only if catch-up did not already cover
it, deduplicating on the `since` watermark. Substituting a poller for the
in-process bus therefore changes no SSE semantics, and needs no change to
`internal/webui/sse.go`. It also means a broadcast dropped to a stalled
client self-heals on the next one.
- **The table is the only complete fan-out point.** Events reach the store
through several paths that never touch the daemon's bus, including the
audit event `store.ArchiveTask` writes inside its transaction
(`internal/infrastructure/postgres/store.go`) and the binding-dispatch failure
`internal/daemon/daemon.go` inserts directly. A push hub would have to be
hooked at every write site and at post-commit, and would silently miss any
site added later that forgets to notify. Reading the table misses nothing.
The cost is one poll interval of latency on the activity feed, default 1s and
operator-tunable. That is accepted: the feed reports task lifecycle history,
and an operator action already gets its own synchronous HTTP response.
This resolves the `/events` row of the route-owner inventory in
[`ui-service-boundary.md`](../prds/ui-service-boundary.md). `/api/logs` and
`/api/logs/stream` are not resolved by it, they read the daemon's in-process
diagnostic feed and remain host-local (see `archie-core-8cda.5.4`).
Revisit only if sub-second feed latency becomes a requirement, or if a second
consumer needs the same stream, at which point the fan-out belongs in the State
Store process behind a `SubscribeEvents` RPC and this record is superseded.
**Dashboard configuration page — DECIDED (2026-09-09, `archie-core-ymut`).**
The configuration page becomes read-only in the UI process for Phase 3. Reads
cross the boundary as a published snapshot; writes are descoped, not
contracted. This amends the ratified boundary, which assumed a single admin
contract carrying both.
**Reads.** `webui.ConfigView` is already the whole answer. It is a UI-owned,
secret-free value projection built in `handleConfig`: `ProviderView` carries
the API key's environment variable name and a `Configured` boolean, never a
value, and `RepoView` is repository metadata only. It is already the exact
shape the browser receives. So the daemon publishes that projection, plus
provenance, reload status and the overridden-key list, as a snapshot the UI
reads; nothing new has to be designed, only moved. Two State Store RPCs carry
it, a `PutConfigSnapshot` restricted to the administrative token and a
`GetConfigSnapshot` the UI calls. The daemon republishes on boot and after
each successful reload, which is precisely when the projection changes.
The State Store is the right holder because a published configuration snapshot
is shared state, it is already dialled by the UI, and it costs no new listener,
port, token or interceptor. The alternative, a config admin service on
`archied`, would make the daemon a gRPC server for the first time. Today it is
purely a client of Gateway and State Store; `grpc.NewServer` appears only in
`RunGateway` and `RunStateStore`, which are the standalone binaries' entry
points, not the daemon's.
**Writes.** `PATCH /api/config`, `POST /api/config/reset` and
`PATCH /api/config/repos/{owner}/{name}` answer 503 in the UI process, and the
SPA hides those controls rather than offering a button that fails. Editing is
`config.toml` plus reload, which is already the only path for every setting
outside the runtime-tunable allowlist.
This is a deliberate feature reduction and worth naming as one. The write path
is not hard because of the transport; it is hard because the policy is
daemon-local and stays that way: `installUpdateConfigHandler` denies
non-runtime-tunable keys, applies a dotted overlay to a clone of the published
config, validates the materialised result, writes overlay rows, and rebuilds
provenance. Contracting that means either moving the policy, which the
boundary forbids, or exposing it verbatim as remote procedure calls, which
builds a Configuration Service inside a migration bead. Neither is work this
phase should be doing to keep one page's buttons alive.
Revisit when dashboard configuration editing is picked up as a feature in its
own right (`archie-core-1786637498420-327`, still open). At that point it gets
an admin contract designed as a feature, and the Configuration Service this
document already anticipates is its natural owner. Until then the UI renders
configuration and does not write it, which is what the boundary always said
about ownership even when it assumed a wider contract.
Amended 2026-09-11. This descope is a deferral, not a decision that the
dashboard should be read-only. Name it that way in review: the daemon-side
policy was built and tested, then deleted by the cutover (`e037b95` removed
`internal/app/archied/config_update.go` and its tests), so reviving it is
recoverable work, not a rewrite. `archie-core-j28m` carries the remaining
question -- which process serves the policy and what transport carries the
write -- and blocks the feature bead. The handlers, their error sentinels and
the `UpdateConfig`/`ResetConfig`/`UpdateRepoField` seams on `webui.Server` are
kept deliberately for it; `ConfigView.Editable` follows whichever process holds
`UpdateConfig`, so wiring that one field makes the page editable
(`archie-core-ml30`).
Implementation belongs to `archie-core-8cda.5.4`, the cutover that removes the
daemon's own dashboard. Nothing here is built yet.
**Superseded 2026-09-21 by the runtime control plane.** The open question this
descope left -- which process serves the policy and what transport carries the
write -- was answered by `docs/prds/runtime-control-plane.md`: neither a daemon
admin service nor a revival of the daemon-local policy. `ControlPlaneService` on
the State Store's existing gRPC server owns every database-backed setting, and
each feature validates its own resource, so there is no daemon-local policy left
to contract. `archie-core-j28m` is closed.
Consequently the three write seams described above no longer exist.
`PATCH /api/config`, `POST /api/config/reset` and
`PATCH /api/config/repos/{owner}/{name}`, the `UpdateConfig`/`ResetConfig`/
`UpdateRepoField` fields on `webui.Server`, and `ConfigView.Editable` were
deleted in `31622ec5` along with the runtime overlay store they wrote to.
`GET /api/config` remains a read of the published projection, as this decision
always intended.
### 7. Shared mechanics
The following cross-domain mechanics require exact contracts before dependent
packages migrate:
- event-bus delivery and failure semantics;
- policy evaluation API, composition, and precedence;
- configuration candidate preparation, health validation, atomic promotion,
observation, and rollback;
- service-specific health, bounded remediation, isolation, and escalation;
- changelog association and grouping.
These shared mechanisms do not acquire ownership of domain meaning. Domains
continue to own their commands, events, policies, settings, and consequences.
The Go documentation generator, its output placement, and drift checking are
defined in `generated-documentation.md`. The external Astro website consumes
the committed documentation and release JSON artifacts and serves them under
`offloaded.dev/docs/`. This repository owns the source and artifact checks; the
website repository owns rendering and deployment. The generators and
Archie's normalised documentation model remain migration work rather than open
product architecture.
**Amended 2026-09-15.** `internal/infrastructure/servicediscovery/nats`
implements the `servicediscovery.ServiceRegistry` contract (Connect, Register,
Resolve, Watch) over NATS KV and is fully tested, but no production code
constructs it and no config surface exposes it. This is a deliberate deferral,
not an oversight: service-to-service addressing belongs to the runtime and
process boundary work in section 6, which currently pins container addressing
by injecting the daemon's startup NATS URL rather than resolving through a
registry. The scaffold is kept for that work; re-derive it only if the
addressing model changes.
### 8. Cutover sequence
The final migration plan must order:
- compatibility adapters;
- schema migrations and data backfills;
- any required dual-read or transitional paths;
- domain-by-domain package replacement;
- production wiring changes;
- legacy package removal;
- architecture tests preventing dependency regression;
- focused, integration, race, and full quality gates.
Each legacy package requires objective removal criteria. No compatibility path
may become an indefinite second implementation.
## Completion criteria
Migration design is complete when:
- every current package has one approved owner and destination;
- every mutable record has one authoritative owner and migration path;
- all external and cross-process contracts have versioned owners;
- existing behaviour and data have explicit parity requirements;
- process boundaries have evidence-backed justification;
- the cutover order preserves a working application;
- legacy deletion criteria and deterministic architecture tests are defined;
- no unresolved decision requires an implementer to invent domain semantics.
Exact Go APIs, SQL statements, and mechanical refactoring steps MAY be finalized
during implementation when they do not change these semantics.
## Recorded migration position (2026-07-29)
Recovered 2026-08-09 from the pre-migration issue tracker. This section records
decisions the maintainer approved that the repository did not otherwise capture.
**Completed:** `internal/infrastructure/eventbus/nats` (rebuilt, not relocated);
`internal/infrastructure/configuration` (loading moved out of `internal/config`,
which is now types-only and does no I/O); `internal/eventbus` (broker-neutral
contract); `internal/domain/workintake` (the first `internal/domain/` package,
owning `TaskEnvelope`, the routing `Kind`, the label vocabulary, and task
subjects).
**DECISION — private input DTO deferred (approved).**
`configuration.Document.Config` is still `internal/config.Config` rather than the
private per-domain input DTO this document mandates. Building an ~800-line
parallel type tree while every consumer still reads `config.Config` would mean
two shapes kept in sync by hand, with no consumer for the new one. It is named as
a field so the compromise is visible at each use site, with the deletion
condition recorded in that package's `doc.go`. Do this **with** the
`internal/config` dissolution, not ahead of it.
**Agreed next: `internal/app/{archied,agentworker}`.** `run()` in
`cmd/archied/main.go` is ~460 lines, against `organisation.md`'s rule that
`cmd/*` must not contain substantive wiring or act as a service locator. It is
also the last non-infrastructure holder of the NATS SDK, and it is where the
config DTO translation will land, so it unblocks the dissolution above.
**Method constraint.** Do not write a separate recorded package-review document
per area when the decisions are already dictated by
`dependencies-and-contracts.md`. That is the ceremony pattern this project
deliberately avoids.
## OPEN — `[chat.*]` config section naming
`configuration.md:160` already states the position: `ChatConfig` holds "separate
channel instance settings... there is no chat-wide settings owner". The config
section name has not followed, so a settings block named for a product surface
owns what the architecture calls channel state.
Two candidates, neither settled: `[channel.*]` and `[messaging.channel.*]`. The
second reads as a domain path, and no config section in this repo is currently
named after a domain package, so adopting it sets a precedent for every other
section rather than fixing one name.
Blocked on a maintainer decision, not on evidence. This is a rename with an
operator-visible TOML break, so it should land with the `internal/config`
dissolution recorded above rather than on its own.
-337
View File
@@ -1,337 +0,0 @@
# Task Observability
**Status:** Implemented. The per-run detail surface was added on 2026-09-18 and
is described below.
**Date:** 2026-08-09 (revised 2026-09-18)
## Historical problem
archied's own daemon logging (`internal/logging/`) was already solid: a
rotating file sink, a live `Feed` the dashboard subscribes to, and a reader
the `/api/logs` endpoint serves from. Before this implementation, none of
that reached inside a task.
A task's actual work happens in a task-scoped `archie-agent` container,
dispatched as one complete workflow over NATS.
Before this design was implemented, five things destroyed the evidence of what
that container did:
1. **Worker startup** constructed an stderr-only logger and never replaced its
handler after discovering a dedicated boot task, so runtime records could
not leave the container.
2. **`internal/container/pool.go`** creates every task container with
`AutoRemove: true`. The container — and its stderr — is gone at exit,
success or failure alike.
3. **`internal/domain/workflow/implement.go`, `StageBaselineGate`** captures
`go build`/`go vet`/`go test` output via `cmd.CombinedOutput()`, then
clips it to 200 characters into a `Warn` log line and discards the rest.
The eventual park reason is built from `res.Status` alone — the actual
compiler error is never persisted anywhere a human or Archie's own chat
tools can read it back.
4. **`agentexec.Result`** (`internal/agentexec/protocol.go`) carries only
`Summary`/`Detail` — no step-by-step transcript (tool calls, durations,
errors). There is no transcript to recover even in principle.
5. **`agentexec.SubjectForSystem`** is documented as the return channel for
exactly this — _"log dumps, health, and PII warnings... the daemon reads
these for observability and never forwards them"_ — but has no publisher
and no consumer anywhere in the codebase except a subject-format
assertion in `nats_test.go`. The designed return path was never wired.
The practical consequence: a task parks with
`stage baseline: baseline red -- go build ./... fails and builder could not
auto-fix (status: parked)` and there is no way — not from the dashboard, not
from Telegram chat, not by SSH'ing into the deployment host — to see _why_
`go build` failed. The container that knew is already gone.
This matters beyond debugging convenience: supported deployments can combine
a resident daemon with ephemeral Docker containers that run unattended for
weeks between operator logins, and the system is
intended to be usable by people other than the original operator. A system
that is only debuggable by an operator who happens to be watching `docker ps`
in real time does not meet that bar.
## Decision: NATS is the sole autonomous handoff
The agent image must reach NATS in every deployment, because the broker is the
only autonomous task handoff and the only channel carrying task results back
to the daemon. `archied` has no workflow runner or host fallback. A container
that dies before establishing a NATS connection is a distinct, narrower
failure (connectivity/config) from the one this document addresses (a connected
container's own output being unrecoverable), and is out of scope here.
## Implemented design
The key property: **logs leave the container while it is alive**, so its
death at `AutoRemove` no longer matters. Persistence happens in the daemon
process, which already owns durable state.
### Sink: extend `internal/logging`, not a new package
`internal/logging` already owns its on-disk format end to end per
`organisation.md` ("a package owns its own format end to end"). Add a
task-scoped writer producing the same `logging.Entry` JSONL shape at
`<state_dir>/logs/tasks/<task_id>/attempt-<n>.jsonl`. `logging.Tail`,
`logging.Query`, and `logging.Components` operate on this unchanged;
`internal/webui/api_logs.go` stays transport-only, as it does today.
### Agent side: make the designed subject real
`internal/app/agentworker` replaces the stderr-only `slog.Handler` with one
that tees to stderr (kept for container-level operator debugging when a
shell is attached) and publishes each record to
`agentexec.SubjectForSystem(taskID)`, which already exists for this purpose.
The application layer obtains only a narrow publisher from
`internal/infrastructure/agenttransport/nats`; raw core-NATS types remain in
infrastructure. `internal/infrastructure/agentboot.TaskID` reads the task ID
from `<worktree>/.git/task.json` per the container/pool.go trap documented in
`CLAUDE.md`. Publishing is fire-and-forget: log shipping must never block or
fail the run it is reporting on.
### Daemon side
`cmd/archied/main.go` registers `subscribeSystemLogs` once at startup on
`agentexec.SubjectSystemWildcard`. It demultiplexes by task ID, appends to that task's
sink, and publishes into the existing `logging.Feed` so live task output
appears on the dashboard exactly like daemon output. The approved target is
for this composition to move to `internal/app/archied`; that package does not
yet exist, so this document does not claim the migration is complete.
The daemon is also a writer in its own right for the decisions only it makes.
Every park records its reason into that attempt's sink (`daemon.recordPark`),
on the daemon side after the guarded transition lands and in
`workflow.park` on the agent side, because "why did this park?" is the question
the log exists to answer and the container path cannot answer a run that never
reached a container. The entry is written only once the park actually
happened, so a transition another actor won does not leave a log claiming an
outcome the task board contradicts.
### Gate output: stop discarding it
`StageBaselineGate` and the equivalent TDD-stage gate runs write full
`cmd.CombinedOutput()` to the task's sink under a `gate` component, and put a
bounded tail (~2KB, not 200 bytes) into the park reason. This is the cheapest
fix and independently valuable — it alone would have made the `go build`
failure diagnosable without any NATS plumbing.
### Transcript
Step-level events (tool name, argument digest, duration, error) are emitted
as log entries on the same NATS system subject rather than added as new
fields on `agentexec.Result`. This keeps the wire protocol
(`internal/agentexec/protocol.go`) stable and the transcript lands in the
sink automatically, with no separate delivery path to keep consistent.
### Retention
Reuse the existing rotation (`MaxSizeMB`/`Keep`) semantics per task
directory. Prune a task's log directory when `store.ArchiveTask` archives
it, so task logs share the task's own
lifecycle rather than accumulating independently.
### Surfaces
- `/api/tasks/{id}/logs`, built on `logging.Reader` the same way
`/api/logs` is today.
- A chat tool so Archie can answer "why did task 4 park?" directly from
Telegram or the webui chat — this is the surface that actually matters
for the deployment model in `CLAUDE.md`, where an operator may not be
looking at a dashboard at all.
- The per-attempt read surface described in the next section, on top of the
same task-scoped stream.
## Per-run task detail (attempts, stages, changes, config)
**Status:** landed, together with the change set that carries this revision
(workflow run `76f8e877`). The provenance half is in the tree: `events.Event.Attempt`,
the `changes_captured` and `config_captured` event kinds, and the two protobuf field
additions. So is the read half: the three per-attempt endpoints
(`/api/tasks/{id}/attempts`, `/changes`, `/debug`) and the dashboard run-detail page
that consumes them. The decision record, the rejected alternatives and the honest
limits are `docs/prds/task-run-detail.md`.
The task log surface above answers _why did this park?_. This surface answers
_what did this run actually do?_, per attempt.
### Attempt attribution
One task can run many times, and the task's event stream is the durable record
of all of them. `events.Event.Attempt` attributes each event to one run; `0`
means **not attributable** — every event written before this change, plus the
deliberately task-agnostic producers. An unattributed event is reported as a
count and is never presented as an attempt.
Attribution is a column, not a fold over `task_queued`/`task_retried`: a fold
would have to guess which side of a boundary an event belongs to across a daemon
restart, a stale-run recovery, or two interleaved attempts, and a guess rendered
as structure is exactly the false fidelity this surface exists to avoid.
The column is part of the events table in
`internal/infrastructure/postgres/migrations/0001_state_store.sql`, and nothing
is backfilled.
### Read surface
The routes are registered beside the existing task routes in
`internal/webui`'s `registerTaskRoutes` and all resolve the task through the
store's `TaskByID`; a task that does not exist is a `404`, never a `200` with an
empty body.
- `GET /api/tasks/{id}/attempts` — every attempt with its stages inline, so the
rail and the attempt selector can never disagree. Stages are ordered by
occurrence within their attempt. An attempt with no stages is legitimate and
renders as "no stages recorded", never as an unexplained empty rail.
- `GET /api/tasks/{id}/changes?attempt=N` — the change captures for one
attempt, ordered by capture time; more than one per attempt is normal (a
mid-workflow commit such as TDD's `commit-repro`, then `commit-push`, then a
final `open-pr` capture that carries the pull-request number).
`found: false` means no capture was recorded for that attempt, which is
**not** "no files changed"; a capture that was recorded but could not be read
is reported as exactly that, and never as a diffstat of zeroes.
- `GET /api/tasks/{id}` — unchanged: the raw event array, each event now
carrying `attempt`. The per-attempt configuration is read from this response,
selected by kind **and** attempt.
- `GET /api/tasks/{id}/logs` — gains `stage` beside its existing filters. The
match is exact and case-insensitive, and an entry that records no stage never
matches (see `logging.Query.Stage`).
- `GET /api/tasks/{id}/debug?attempt=N` — the stored task record and the task's
events, deliberately unfiltered, so an operator can attribute everything the
task did even when a panel has nothing to show.
The `attempt` parameter follows one rule on every route: absent or `0` selects
the task's current attempt, and the resolved attempt is echoed in the response.
### Stage status
`stage_start` and `stage_finish` are the only inputs, so the derivation is
explicit and each case is pinned by a test:
| Events seen for the stage | Reported |
| ------------------------------------------------------------------------- | -------------------------------------------------- |
| `stage_finish` with `data.error` | `failed`, with the error text |
| `stage_finish` with `data.interrupted` | `interrupted` |
| `stage_finish`, neither | `ok` — "returned without error" |
| `stage_start` unmatched, and this is the task's current in-flight attempt | `running` |
| `stage_start` unmatched on any dead attempt | `interrupted` — the run ended without finishing it |
| `stage_finish` with no matching start | the stage, with no start time invented |
| no stage information at all for that attempt | `unknown` |
**There is no exit code.** `stage_finish` carries a duration and an optional
error string and nothing else, so no stage can be shown as pass/fail and the
page must not imply verification. A stage that finished cleanly and then parked
stays `ok` on a failed task, which is why the attempt status is read together
with the task status rather than on its own.
### Changed files
The change an attempt produced is read from the worktree at the moment it is
committed or pushed, and persisted as a `changes_captured` durable event — plus
one final capture when `OpenPR` records the pull-request number, which is the
only point at which a capture can carry one. It has to be captured there: the
worktree is deleted on merge, close and no-PR terminal states, a retry resets
the branch onto its base, and no forge contract exposes a changed-file read.
`internal/domain/workflow/task/changes.go` owns the value types and the status
strings they persist.
- One capture carries per-file `added`/`modified`/`deleted`/`renamed`/
`typechange` status with added and deleted line counts, and totals.
- Each capture names its schema (`archie/task-changes@1`, in `internal/events`)
and a reader refuses a payload whose schema or key set it does not know,
rather than rendering the zero value of every field it could not find. That
refusal surfaces as "a capture was recorded but could not be read", which is
a different statement from "no capture was recorded".
- `base_sha` is the merge base the file list was diffed against, not the base
branch's tip, so the pair describes one change set even when the base branch
moved during the run.
- `files` is capped; `totals` always covers the **full** set, and a truncated
capture says so rather than silently dropping entries.
- `binary` means "no textual hunks" — never a claim about the file's type on
disk — and a path the repository recorded as a rename pair is reported as the
repository recorded it.
- Capture **degrades and never parks**: an implementation without the capture
seam captures nothing, logs, and lets the run continue.
### Per-attempt configuration
The effective configuration an attempt ran under is persisted as a once-per-
attempt `config_captured` durable event carrying the schema constant
`archie/task-config@1` and the non-secret task-runtime subset from
`config.Config.ForTask()`. It is not stored in a table and has no endpoint of
its own: the dashboard reads it out of the events response it already fetches.
The single-row `config_snapshot` table is left alone — it answers what the
running configuration is now and is replaced on every publish.
Redaction is proven positively by a test that builds a full configuration
containing canary values and asserts none of them survive serialising, rather
than being inferred from the producer's contract. The timeline carries one
human line for this kind; the document itself is rendered by the panel.
**Trust boundary, stated honestly.** A task-scoped grant may insert events on
its own task ID — that is how `tool_call` and `agent_finish` already work — so a
task could in principle write its own `config_captured` event. This widens no
capability, because the grant could already insert arbitrary events on itself,
but it does mean this provenance is exactly as trustworthy as the rest of that
task's event stream, and no more. It is not tamper-proofing and must never be
described as such.
### The wire
The whole wire change is two fields on existing messages: `Event.attempt`
(field 11) and `ReadTaskLogRequest.stage` (field 9) in
`proto/state/v1/state.proto`. No RPC, no table and no configuration field was
added, so the ratified state-store contract in
`docs/prds/state-store-contract.md` rev 2c is unchanged.
Version skew degrades instead of failing, and each degrade is a statement the
page has to make rather than hide: an old server makes `attempt` read as `0` and
`stage` match nothing, so the page says it cannot attribute events to attempts
instead of labelling the whole stream "attempt 1"; an old client sees
`config_captured` as an unfamiliar kind, and the panel must then say it cannot
read per-run configuration — a different claim from "not captured for this
attempt".
### Rules the surface keeps
- "No record" and "this deployment cannot read this" stay different answers,
for logs and for configuration alike.
- No run-duration figure is shown. A run can spend days in `waiting_human`, so
one number would understate wall time; per-stage durations only.
- No duration is invented for a stage with no start; it reads "not recorded".
- The stage filter is a narrowing, not a coverage claim: agent and tool output
carries no stage and is never matched, and the pane says so beside the
control.
- An attempt predating the change shows "not captured for this run" for its
configuration and its change capture, never an empty view that implies
defaults applied or nothing changed.
### Failure and rollback
Every part is additive. A capture or a configuration emit that cannot happen
leaves the run alone — reporting must never park a task. Reverting the change
set removes the endpoints and the page; the extra column and the extra event
kinds are inert to the previous revision (a column no statement names is
ignored, and an unfamiliar event kind already renders as unfamiliar), and there is
no data transformation to undo.
## Dependency direction
`internal/logging` remains cross-cutting per `organisation.md` — it imports
no domain, infrastructure, or app package, so extending it to be task-scoped
does not change its classification. The workflow domain writes through the
cross-cutting logging contract. On the agent side,
`internal/app/agentworker` composes the narrow publisher supplied by
`internal/infrastructure/agenttransport/nats`. On the daemon side,
`cmd/archied/main.go` currently composes the NATS subscription with the task
sink until the approved `internal/app/archied` migration is implemented.
## Implementation sequence (completed)
1. Gate-output capture (~30 lines, no NATS changes) — fixes the immediate
symptom that prompted this document.
2. Task log sink in `internal/logging`.
3. Agent-side publisher on `SubjectForSystem`.
4. Daemon-side subscriber + `logging.Feed` integration + retention on
archive.
5. `/api/tasks/{id}/logs` + chat tool.
Tracked as GitHub epic/subtasks per the issue list linked from this
document's PR.
-101
View File
@@ -1,101 +0,0 @@
# Repository Organisation
**Status:** Approved
**Date:** 2026-07-28
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
## Target structure
Archie MUST be organised around cohesive application responsibilities:
```tree
cmd/
archied/
archie-agent/
internal/
domain/
<area>/
eventbus/
policy/
infrastructure/
configuration/
eventbus/
nats/
forge/
persistence/
<external-service>/
app/
archied/
agentworker/
plugins/
<plugin>/
deployments/
<supported-assembly>/
docs/
guides/
examples/
<copyable-example>/
extras/
<optional-extension>/
```
Domain names are chosen from application behaviour during package review.
Existing names MUST NOT be retained merely to reduce migration work.
## Domain areas
A domain owns one cohesive job performed by Archie. It contains that job's
language, state, rules, operations, commands, events, policy implementations,
runtime settings, and required service contracts.
Code that changes together SHOULD live together. Empty or ceremonial `entities`,
`repositories`, or `services` layers are prohibited.
## Application composition
`internal/app`:
- constructs domains and infrastructure implementations;
- translates external configuration into domain and plugin settings;
- connects commands, events, and shared contracts;
- starts services in dependency order;
- owns health aggregation and shutdown ordering.
`cmd/*` parses only process-level input and invokes the relevant application
composition package. It MUST NOT contain substantive wiring or act as a service
locator.
## Process boundaries
Archie begins as a modular monolith even when capabilities run in separate
processes. A domain becomes a separately deployed service only for a concrete
need such as security isolation, independent scaling, failure containment, or
independent operation.
Possible future extraction does not justify premature network protocols or
duplicated service scaffolding.
A new command is not a reason for a new binary. `cmd/` entries are process
boundaries: a binary earns its place when its surface fails independently of the
fleet, or when one process may need to run in more than one location, such as a
high-availability pair or across a NAT boundary. Operational commands over a
surface an existing binary already owns are subcommands of that binary. Offline
database maintenance belongs to `archie-state-store`, which owns the file and
its path layout, not to a new recovery binary.
## Optional and operational material
- `extras/<extension>` contains a maintained optional extension with real
behaviour. Core Archie MUST NOT import it, and removing `extras/` MUST NOT
prevent the core application from building or running.
- `deployments/<assembly>` contains a supported assembly, including deployment
definitions and concise operational instructions.
- `docs/guides/` contains handwritten explanation and links to generated
reference material.
- `examples/` contains copyable samples with explicit purpose, prerequisites,
and support expectations.
Supported assemblies SHOULD demonstrate that capabilities can be selected
independently.
-70
View File
@@ -1,70 +0,0 @@
# Domain and Feature Review Procedure
**Status:** Active
**Date:** 2026-07-28
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
## Purpose
Architecture work proceeds one domain or feature at a time. Before any design
question, the selected area is researched across its complete live
implementation, consumers, tests, state, configuration, and runtime wiring.
Existing packages are evidence, not the unit that drives the interview.
Placement follows behaviour and ownership, not the existing directory name.
No restructuring implementation begins until the relevant package decisions
are agreed and recorded in the focused domain or requirement document.
## Required research
Before design questions, the current-state report MUST identify:
- entry points and runtime composition;
- state, persistence, and lifecycle;
- public and internal contracts;
- commands, events, and policy enforcement;
- configuration and defaults;
- all consumers and cross-domain interactions;
- process and infrastructure boundaries;
- tests, failure behaviour, and known invariants;
- duplicated or conflicting implementations;
- documentation that disagrees with live code.
Discoverable facts MUST be investigated rather than presented to the user as
design questions.
## Required decisions
Each package review records:
| Decision | Required result |
| --------------------- | ---------------------------------------------------------------- |
| Owned behaviour | The cohesive job the code performs |
| Domain ownership | The owner of the behaviour and vocabulary |
| Final location | Its target path |
| Public contracts | The smallest interfaces, commands, and events exposed |
| Required services | Domain-defined interfaces implemented by infrastructure |
| State ownership | The owner of each mutable record and transition |
| Dependencies | Allowed imports and dependencies to remove |
| Duplication | Code to consolidate, delete, or keep separate |
| Plugin status | Core domain, shared contract, infrastructure, plugin, or extra |
| Process boundary | In-process, or the concrete reason for isolation |
| Configuration | Settings owned by the domain or plugin |
| Policy | Definitions, evaluators, consequences, and shared mechanics used |
| Documentation | Authoritative definitions and generated reference |
| Migration constraints | Behaviour and data that must remain correct |
## Interview method
For every selected domain or feature:
1. Declare the single area under review.
2. Complete the current-state research.
3. Explain actual behaviour in plain technical language.
4. Separate facts from design decisions and concerns.
5. Resolve obvious consequences directly and ask only questions whose answer
materially changes behaviour or structure.
6. Record each confirmed decision in its focused document.
7. Complete that area's handoff before selecting another.
8. Keep unrelated domains outside the implementation scope.
-188
View File
@@ -1,188 +0,0 @@
# Plugins and Extensions
**Status:** Approved foundation
**Date:** 2026-07-28
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
## Plugin framework
The core plugin domain lives under `internal/domain/plugin`. It owns:
- plugin identity and metadata;
- discovery and registration contracts;
- lifecycle rules;
- capability registration;
- validation and compatibility rules.
The generic plugin contract remains metadata-only. Functionality is exposed
through narrow typed capability contracts with an owning registry or manager.
Workflow plugins belong to the Workflow capability family. The Workflow domain
at `internal/domain/workflow` owns their typed registration, validation,
versioning, definition, and execution contracts. The generic plugin domain may
provide plugin identity, discovery, compatibility, and lifecycle mechanics, but
it MUST NOT define Workflow semantics or expose untyped Workflow hooks.
## Plugin engine rule (strict)
“Engine” is reserved for a typed, lifecycle-managed capability family. It is not
a synonym for a generic plugin hook. Every new plugin engine must satisfy all of
these invariants:
1. **Typed domain contract.** The engine interface exposes real
capability-specific operations in addition to identity metadata. Examples are
resolving a secret, delivering a message, or running an agent. A plugin that
only exposes `Name` and `Version` is metadata, not an engine.
2. **Owning family manager.** The capability package owns a `Registry` or
`Manager` that controls provider registration and discovery, initialisation,
or access. Providers do not register arbitrary callbacks directly on the
daemon.
3. **Lifecycle and health.** When an implementation owns resources or background
work, its typed family contract must expose start, health, and stop
semantics. The owning manager invokes them and defines failure isolation and
shutdown ordering. Stateless providers may make these operations explicit
no-ops.
4. **Narrow host access.** Plugins receive the typed family registrar and only
the host services their declared capability requires. They never receive
`*daemon.Daemon`, a service locator, or an untyped hook map.
5. **Metadata-only generic plugin contract.** `plugin.Plugin` remains limited to
`Name()` and `Version()`. Domain hooks belong on typed engine interfaces;
adding capability methods to the generic interface is forbidden.
6. **Trust boundary stays explicit.** Explicitly trusted, operator-installed
plugins—including third-party secret-engine plugins the operator chooses to
trust—may run in-process and have daemon privileges. Repository-supplied code
runs in the task container. Integrations that are not trusted as daemon code
run out of process through MCP or a versioned protocol and, when a
confidentiality or integrity boundary is required, inside a real container
sandbox. A subprocess boundary alone is not a security sandbox, and calling
Yaegi-loaded code a plugin does not isolate it.
`internal/plugin/architecture_test.go` enforces the mechanically testable parts
of this rule: the generic plugin method set, the shared agent-instruction
source, and the requirement that engine interfaces have domain behaviour plus an
owning registry or manager.
### Memory engine family
One engine, addressed by four typed scopes -- `ScopeGlobal`, `ScopeAgent`,
`ScopeUser`, `ScopeAgentUser` (`internal/domain/memory`, `Scope`/`ScopeKind`).
A caller names exactly the scopes it may read or write; the engine applies no
access policy of its own, so isolation falls out mechanically because
`ScopeAgent{a}` and `ScopeAgent{b}` are different storage keys. See
`docs/prds/memory-engine-unification.md` for the decision this contract
implements; it superseded `internal/memory` (`MemoryProvider`/`Manager`),
deleted in that PRD's slice 5.
`MemoryEngine` (`internal/domain/memory/contract.go`) is the typed family
contract: `Create`, `Get`, `Query`, `List`, `Update`, `Forget`, `Revisions` --
CRUD with revisions retained, not just create/read/delete. `Update` supersedes
rather than overwrites: the superseded state is appended to the scope's
`HISTORY.md` before the live block is replaced, and `Update` carries no
`Scope` field, so a record can never change scope. The family's content
scanner (prompt-injection / sensitive-data patterns) is applied inside
`Create` and `Update`, the single choke point every producer crosses.
`internal/domain/memory.Registry` is the owning family registry: registration,
start/health/stop, shutdown ordering, and failure isolation, following the
plugin engine rule above. `internal/infrastructure/memory.NewBuiltinEngine` is
the only registered engine today; it persists through
`internal/infrastructure/memory/builtin`, a markdown store (`MEMORY.md`-shaped
per-scope files) that owns its on-disk format end-to-end.
Two per-turn seams in `internal/gateway` connect a chat turn to the engine,
each narrowed to exactly the operations it needs:
- **Read** (`turn_memory.go`, `MemoryStore`): `prepareTurn` runs a
scope-only `Query` over the resolved `Subject`'s readable scopes,
synchronously and before the prompt is built. It never returns an error --
a panicking or failing engine degrades to an empty `<memory>` block rather
than failing the turn -- and is bounded by a per-scope record limit and a
byte cap on the rendered block.
- **Write** (`turn_memory_tool.go`, `MemoryWriteStore`): four tools --
`memory_create`, `memory_update`, `memory_delete`, `memory_list` -- built
per turn onto the resolved `Subject`'s writable scopes, not registered once
at boot. The model chooses the scope kind; it never chooses the agent or
user id, which come from the turn's resolved `Subject` and have no schema
field to override. `ScopeGlobal` is never model-writable.
`boot.setupMemoryEngine` (`internal/app/archied/bootstrap.go`) registers and
starts the engine and must run before `setupGatewayChat`, which constructs the
only chat turn runner in production and captures the engine at construction
time (`internal/app/archied/composition_order_test.go` pins the ordering), and
before `setupCurators`, whose `Registrar` captures the engine registry. The
session curator (`internal/infrastructure/sessioncurator`) writes derived
records onto `ScopeAgentUser`, making it the engine's other live producer
besides the chat write path.
## Plugin implementations
First-party plugins are self-contained vertical modules under
`plugins/<plugin>`.
A plugin:
- owns its implementation, settings, templates, assets, and tests;
- receives only explicitly supplied contracts and services;
- MUST NOT receive daemon internals, a service locator, or unrestricted
application access;
- MUST NOT import arbitrary infrastructure or application composition code;
- MAY use approved domain and shared application contracts;
- MUST remain removable without changes to unrelated domains.
Plugins may be internally cohesive like small services. They do not become
network services without a concrete security or operational reason.
## Event sources and reactions
`archie-core-7d5u.1` asked whether extensions should react to events
in-process through typed capability families (this document's model) or
out-of-process like a generic `DispatchEvent` dispatcher. Decided 2026-08-22
in `docs/prds/event-sources-and-reactions.md`: in-process typed families,
confirming this document's model rather than amending it. The forge webhook
receiver (`internal/forge/webhook`; see "Intake provenance" in
`docs/architecture/messaging-and-work-intake.md`) and the EDA playbook engine's
Module action position
(`docs/prds/eda-playbook-engine.md`, `internal/domain/eda/module`) are the
shipped instances of that decision -- each is a narrow typed contract with an
owning registry, not a generic event hook. The playbook engine's Channel and
Forge action positions are designed but not yet implemented (open
investigation `archie-core-t2db.19`); when they land they follow the same
model, not a new one.
## Curator surprisal sampling
**Decided 2026-08-05, wave 1 landed 2026-09-05** — the curator engine family
(epic [#435](https://github.com/samcharles93/archie-core/issues/435)) selects which memories deserve agentic attention via
surprisal-based sampling: score memories by how surprising they are and
spend the sampled reasoner's agentic budget on the most surprising items.
The prerequisites are built: the embeddings capability
([#436](https://github.com/samcharles93/archie-core/issues/436), `internal/domain/embedding` contract +
`internal/infrastructure/embedding` implementation, config-driven via
`models.embedding`) and the wave-1 `Sampler` strategy seam
(`internal/domain/sampling` -- not `internal/curator`, see
`docs/prds/curator-sampler-wave1.md` for the settled design and tracking)
with four
cheap, embedding-free strategies (recency, random, all, staleness proxy).
No curator consumes a `Sampler` yet, and the embeddings client is likewise
deliberately inert: `setupEmbeddings` constructs it at boot and holds it on
`b.embeddings`, but no production code reads that field yet, so a resolved
`models.embedding` role currently produces a client whose only observable
effect is a boot log line. Both are prerequisites waiting on #437, not
unwired defects.
Still deferred: [#437](https://github.com/samcharles93/archie-core/issues/437), the embedding-backed surprisal strategy, which
depends on the above and on [#407](https://github.com/samcharles93/archie-core/issues/407). Requirements for that deferred work,
so it can be picked up without re-deriving the design:
- A `Sampler` implementation behind the same interface as the cheap
strategies; selection deterministic given fixed inputs.
- Algorithm: sample up to a candidate cap; build a k-NN graph over embedding
vectors; row-normalise the adjacency with self-loops; power-iterate to the
stationary distribution; surprisal = −log(stationary probability of the
nearest point); select the highest-surprisal items.
- Degradation: content without an embedding is skipped; an embedding failure
aborts sampling and falls back to free exploration — a sampling failure
must never fail or crash a curator pass.
- Cost bound: the graph build is quadratic in the candidate cap; the cap must
be a named constant with a documented bound.
-52
View File
@@ -1,52 +0,0 @@
# Policy System
**Status:** Approved foundation; exact API is deferred
**Date:** 2026-07-28
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
## Purpose
Retry limits, authorisation, gates, commands, protected paths, tool
availability, and similar rules define or constrain what Archie may do. They
need consistent consumption, composition, evidence, and audit without erasing
their different domain meanings.
## Ownership
`internal/policy` is an explicitly approved shared application contract. It is
not infrastructure and it is not a generic domain that owns every rule.
The shared policy system owns:
- policy identity, version, scope, and applicability;
- typed evaluation invocation;
- deterministic composition and precedence;
- common evaluation states such as satisfied, violated, indeterminate, and not
applicable;
- reasons and evidence;
- evaluation audit records;
- registration, discovery, and lifecycle.
Each consuming domain owns:
- its policy vocabulary and typed inputs;
- its concrete policy definitions;
- its evaluators;
- the meaning and consequence of an evaluation.
Access therefore owns principals, resources, actions, and authorisation
consequences. Task lifecycle owns retry eligibility and exhaustion. Task
execution owns gate requirements. Workspace mutation owns protected-path
effects. Tool execution owns tool and command constraints.
These policies use consistent evaluation mechanics without pretending their
decisions are semantically interchangeable.
## Infrastructure
Infrastructure MAY load, persist, distribute, and audit external policy
representations. It MUST NOT define what Archie allows or assign the meaning of
a domain policy result.
The exact Go API, composition operators, precedence rules, and representation
format require a focused policy design pass.
@@ -1,213 +0,0 @@
# Safe Change and Recovery
**Status:** Requirements approved; mechanics are under design. Database-backed settings are implemented through the control plane (2026-09): see the degrade/recovery section below, which records a gap rather than a solution. The full runtime-supervision protocol (bounded observation, versioned audit trail) remains under design.
**Date:** 2026-07-28
**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)
## Purpose
Archie is built and improved by agents as well as humans. The architecture MUST
make a change easy to locate, understand, test, audit, extend, and reverse
without requiring its author to understand unrelated parts of the application.
Separation of concerns is therefore an operational safety boundary, not only a
code-organisation preference.
## Required outcomes
- An agent can improve a focused feature without receiving authority over
unrelated domains.
- Every event, function, action, setting, and policy has an identifiable owner
and provenance.
- Source and runtime changes pass deterministic checks outside the actor making
the change.
- A rejected or unhealthy candidate cannot replace the last known working
version.
- Invalid user configuration does not terminate an otherwise healthy
application.
- Configuration and service failures are observable, attributed, and eligible
for bounded remediation or rollback.
- The application continues serving unaffected capabilities when one
capability is misconfigured or unhealthy.
- Recovery failure is reported and contained rather than hidden in an
unbounded retry loop.
## Source changes
Agent-authored source changes occur through the task-execution boundary in an
isolated workspace. The agent does not directly mutate the running
installation.
Promotion is controlled by deterministic repository-owned policy, including
tests, generated-reference drift checks, protected paths, change scope, and
other required gates. The actor proposing a change cannot waive these checks.
Repository and domain separation SHOULD allow a task to load and modify only
the governing requirements and code for its declared scope.
## Runtime changes
Configuration and other runtime changes are proposed as candidates rather than
mutating the active state in place.
The affected domain owns:
- the command describing the semantic change;
- validation of its typed settings;
- health signals that demonstrate correct operation;
- domain-specific remediation and rollback consequences.
Shared policy supplies consistent evaluation, evidence, and audit mechanics.
Identity supplies actor attribution. Infrastructure supplies external
configuration storage, service control, and other operational adapters.
## Runtime change protocol
Last-known-good preservation and candidate promotion are the universal runtime
change protocol.
1. An identity proposes an immutable candidate version.
2. Infrastructure parses it without changing active state.
3. Each affected domain validates its typed settings.
4. Shared policy evaluates cross-cutting constraints.
5. Each affected capability prepares the candidate without destroying its
active instance.
6. Capability-specific health checks prove the candidate works.
7. Runtime supervision atomically promotes the candidate.
8. A bounded observation period watches for delayed failure.
9. Failure restores the last-known-good version and records the reason,
evidence, actor, and involved versions.
10. Repeated remediation failure stops retrying, isolates the capability, and
reports the fault.
The affected domain owns the semantic change command, typed validation, health
signals, and remediation consequences. Shared runtime supervision owns the
promotion transaction. Infrastructure performs storage and service-control
operations.
The protocol's exact Go contracts, storage model, atomicity boundary, and
observation rules require a focused runtime-supervision design pass.
## Failure isolation
Invalid input MUST leave the active valid configuration unchanged and produce a
diagnostic record.
A capability that cannot start or reload SHOULD fail independently where its
absence does not violate a declared application invariant. Unaffected
capabilities continue operating.
Remediation MUST be bounded, observable, and policy-driven. Recovery MUST NOT
silently oscillate between versions or retry forever.
## Database settings: degrade paths and recovery (2026-09)
The control plane owns runtime-tunable settings and stores them in the State
Store's PostgreSQL database.
This replaced a dashboard overlay store that degraded to file config on any
failure and had three documented ways back. The replacement has none, and the
posture is the opposite: **the daemon fails closed.**
### Degrade paths
| Failure | Boot behaviour | Where the operator sees it |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| State Store unreachable | `boot.loadRuntimeConfig` returns the dial error and `archied` exits non-zero | stderr: `runtime settings unavailable` |
| A stored resource fails validation | Same: `validate database settings` wraps the error and the daemon exits | Same |
| SIGHUP reload with a bad file, or a control plane that cannot be read | Running config is kept; the reload records `last_error` / `last_error_at`. The reload re-applies the database layer, so it never publishes file values over the running database-owned ones | `/api/config` → `reload.last_error` → dashboard banner |
Failing closed is deliberate for settings the database owns: falling back to the
file values would restore the second source of truth the control plane exists to
remove. The cost is that a bad stored value stops the daemon starting, and the
value can only be corrected through the daemon's own API.
### Serving from Postgres
The State Store, the daemon and the Gateway serve from `database_url` only; an
empty value is a startup error. The embedded NATS store, its endpoint file and
task logs live under `state_dir` (default: the data home's `archie` directory).
The Gateway holds a Postgres serve-ownership claim for its whole life, so a
second Gateway against the same database refuses to start (its turn recovery
would fail the first one's in-flight turns). The State Store holds its own.
### Recovery: offline commands on the State Store
Nothing skips the control plane at boot, and the only writer for a resource is
`ControlPlaneService.Command` on a running State Store -- which is exactly what
the daemon fails closed without. `archie-state-store` therefore carries the
offline recovery commands (`archie-core-6zw0`). They work on the PostgreSQL
database the configuration's `database_url` names
(`internal/app/archied/state_store_recovery_postgres.go`,
`internal/infrastructure/postgres/maintenance.go`) and need neither `archied`
nor the Web UI running: `validate` reads the configuration file the daemon
boots with, which is what makes its verdict the daemon's verdict. One database
backs every service, so the scope is always the whole database.
| Command | What it does | Serving processes |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `backup -out F` | runs `pg_dump --format=custom`, reads the archive back with `pg_restore --list` and only then replaces `F` | may be running |
| `restore -from F` | drops tables the snapshot does not hold and runs `pg_restore --clean --single-transaction`; every write made after the snapshot is lost | every one must be stopped |
| `validate [-config C]` | refuses a schema newer than the binary's highest migration; every stored resource decodes under the definition that owns it; and `configuration.Validate` accepts the settings the daemon would read -- the stored ones, or the seed the State Store writes for a kind the database does not hold yet -- layered onto `C`, the check the daemon reports as `validate database settings` | may be running |
| `rollback -kind K [-revision N]` | replays an earlier revision of a stored resource through the ordinary replace, recording the rollback as a new revision | the State Store must be stopped |
The two validation layers `validate` reports are not the same check, and it
reports both rather than merging them: the write path's own decode is stricter
about shape (it rejects unknown fields boot's decode ignores), while boot is
stricter about meaning (only boot checks `dispatch.trigger`, and a positive
`poll_interval`). Either one refusing is a store somebody has to look at.
No rollback RPC exists and none is needed: a revision carries its own value, so
restoring one is the same replace the dashboard and the channels already use.
The offline command is that operation with the store stopped -- the one state in
which the daemon's own API cannot serve it.
"Must be stopped" is checked rather than assumed. Each serving process holds a
Postgres ownership lock for its whole life. `rollback` holds the `state-store`
claim for the replay. `restore` claims every service role's lock (`state-store`
and `gateway`) without waiting and refuses if any is held or the check cannot
complete. The read-only commands -- `backup` and `validate` -- take no claim and
are meant to run against a serving database: `backup` because the update
installer runs inside the process it is replacing and cannot stop the State
Store, and `validate` because an operator checks a running deployment with it.
`scripts/archie-update-install` takes its pre-flight snapshot through this
subcommand, so the installer and an operator run one implementation.
`rollback` is the surgical route back from a bad stored value; `restore` is the
blunt one, and is also the way back from a schema migration a release cannot
grow out of.
There is no automatic schema rollback. goose `Down` drops tables, so it is data
loss, not a rollback. `scripts/archie-update-install` refuses a daemon update
it cannot snapshot first, and on a failed update `scripts/archie-update-watchdog`
rolls the binaries back, leaves the database alone and prints the `restore`
command for the pre-update snapshot. Whether to run it is the operator's call.
## Gateway restart: two constraints learned the hard way
Telegram `/restart` (`internal/channels/telegram/restart.go` plus the `Start`
supervisor loop). Recovered 2026-08-09 from the pre-migration issue tracker.
Both constraints must survive any refactor.
**1. Deadlock.** The `/restart` handler runs _on_ the bot instance the supervisor
is about to stop. Tearing down inline from the handler deadlocks the restart it
just asked for. So the handler sends on a **buffered** channel (`restartCh`,
capacity 1) and returns immediately; the supervisor loop in `Start` does the
teardown. Duplicate requests hit the default branch and are dropped, not queued.
**2. Lockout.** A failed config reload must **not** be fatal. It logs and
relaunches with the previous in-memory settings. If a bad config edit killed the
gateway, it would also destroy the only means of fixing it remotely — which is
the entire reason `/restart` exists.
**Scope is gateway-only by design.** The daemon keeps running so in-flight agent
tasks survive. Exiting the process would also restart under a `unless-stopped`
policy, but would kill running work. `Reload` (supplied by `cmd/archied/main.go`)
re-reads config from disk and refreshes **only** the token and `AllowedUserIDs`;
everything else is wired into the daemon at construction and still needs a full
restart.
**Authorisation is inherited:** `authorizedMessage` rejects non-allowlisted
senders before any handler runs, so all gateway commands are admin-only by
construction. Do not add per-command auth without checking that invariant still
holds.
-39
View File
@@ -1,39 +0,0 @@
{
"$comment": [
"Contract-conformance declarations. Every entry here is a declared-unconsumed",
"surface: a capability that exists, that no client reaches, and that is",
"deliberately left that way. It must match reality exactly -- a missing entry",
"is an undeclared finding and an entry that is no longer true is a stale one,",
"and both fail a -strict run. See docs/prds/contract-conformance-audit.md.",
"",
"Managed by tools/contractaudit, an ADVISORY report that task check does not",
"run. Reasons state the consequence, not 'TODO': this file is the only place",
"the debt is legible."
],
"surfaces": {
"proto/state/v1/state.proto": {
"StateStoreService/ListCaptures": {
"reason": "Superseded by StreamCaptures. The remote adapter's ListCaptures method (staterpc/client.go) calls StreamCaptures, not this unary RPC, so no production client reaches it. The server keeps it implemented as a compatibility surface for callers of the raw proto.",
"tracker": "archie-core-8cda.4"
},
"StateStoreService/ListUndispatchedCaptures": {
"reason": "Superseded by StreamUndispatchedCaptures, on the same terms as ListCaptures: the remote adapter's ListUndispatchedCaptures calls the streaming variant, leaving this unary RPC reachable only through the raw proto.",
"tracker": "archie-core-8cda.4"
}
}
},
"blindSpots": [
{
"surface": "internal/webui",
"reason": "Extraction is textual, which is why this report is not gated. A path counts as a consumer only when it is the first argument of a call in code, so a bare constant, a dead array, an object property, or a commented-out call does not count; the calling function need not be named, so a rename is survivable. Limits: a path passed as any argument other than the first is not seen (accepting a comma would start crediting array elements); a request inside a template-literal interpolation is not seen; a path built from a bare /api fragment is reported as unparsable rather than silently contributing nothing; and a route is credited to every HTTP verb, so a route whose specific verb has no caller reads as consumed. Routes whose consumer is outside the dashboard (the asset mount, the health probes, the capture-intake webhook) are excluded from this surface by design: they have different consumers and are not part of the dashboard API contract."
},
{
"surface": "proto/state/v1/state.proto",
"reason": "Consumption is derived by scanning adapter bodies for calls through the generated client, so an RPC reached only through runtime-loaded code (Yaegi) or reflection would read as unconsumed. The scan also keys on the generated client field being named 'client'; renaming that field would report every RPC as unconsumed. No such path exists today."
},
{
"surface": "proto/gateway/v1/chat.proto",
"reason": "As above. Note that gatewayrpc is served by archie-gateway and consumed by archied and archie-ui; a consumer living outside this repository would be invisible here."
}
]
}
-494
View File
@@ -1,494 +0,0 @@
{
"generatedBy": "tools/docsgen",
"schemas": {
"AgentExecutionRequest": {
"additionalProperties": false,
"description": "Request is the complete, serializable input for one agent stage.",
"properties": {
"attempt": {
"type": "integer"
},
"budget": {
"$ref": "#/schemas/Budget"
},
"capture_tools": {
"items": {
"$ref": "#/schemas/CaptureTool"
},
"type": "array"
},
"context_window": {
"type": "integer"
},
"extra_rules": {
"type": "string"
},
"gate": {
"$ref": "#/schemas/Gate"
},
"harness": {
"$ref": "#/schemas/HarnessSpec",
"description": "Harness, when set, runs the stage on an external coding-agent CLI\ninstead of the built-in loop. The worker in a Kit container is the\ndaemon's own archie-agent build, so it always understands this field."
},
"mission": {
"type": "string"
},
"model": {
"type": "string"
},
"notes": {
"type": "string"
},
"plugins": {
"description": "Plugins are bundled Yaegi plugins from the skill's plugins/\ndirectory. Each entry carries the name and source so the agent\ncan register them as tools. PRD section 5 Layer 1.",
"items": {
"$ref": "#/schemas/PluginSpec"
},
"type": "array"
},
"preflight": {
"items": {
"$ref": "#/schemas/Command"
},
"type": "array"
},
"protection": {
"$ref": "#/schemas/Protection"
},
"read_only": {
"type": "boolean"
},
"stage": {
"type": "string"
},
"task_id": {
"type": "integer"
},
"version": {
"type": "integer"
},
"workflow": {
"type": "string"
}
},
"required": [
"version",
"task_id",
"attempt",
"stage",
"model",
"mission",
"budget",
"gate",
"protection"
],
"type": "object"
},
"AgentExecutionResult": {
"additionalProperties": false,
"description": "Result is the serializable outcome of one agent stage.",
"properties": {
"appended_notes": {
"items": {
"type": "string"
},
"type": "array"
},
"attempt": {
"type": "integer"
},
"captures": {
"additionalProperties": {
"items": true,
"type": "array"
},
"type": "object"
},
"changes": {
"items": {
"type": "string"
},
"type": "array"
},
"detail": {
"type": "string"
},
"iterations": {
"type": "integer"
},
"stage": {
"type": "string"
},
"status": {
"type": "string"
},
"stop_reason": {
"type": "string"
},
"summary": {
"type": "string"
},
"task_id": {
"type": "integer"
},
"tokens_used": {
"type": "integer"
},
"usage": {
"$ref": "#/schemas/Usage"
},
"version": {
"type": "integer"
}
},
"required": [
"version",
"task_id",
"attempt",
"stage",
"status",
"usage"
],
"type": "object"
},
"Budget": {
"additionalProperties": false,
"description": "Budget bounds one autonomous execution.",
"properties": {
"max_steps": {
"type": "integer"
},
"wall_clock": {
"type": "integer"
}
},
"type": "object"
},
"CaptureTool": {
"additionalProperties": false,
"description": "CaptureTool declares a structured-output tool whose calls are returned to the daemon as data.",
"properties": {
"boolean_fields": {
"items": {
"type": "string"
},
"type": "array"
},
"description": {
"type": "string"
},
"max_calls": {
"type": "integer"
},
"name": {
"type": "string"
},
"non_empty_strings": {
"items": {
"type": "string"
},
"type": "array"
},
"parameters": true,
"required_fields": {
"items": {
"type": "string"
},
"type": "array"
},
"required_when_true": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "RequiredWhenTrue makes fields required only when a boolean field in\nthe same call is true, keyed by that boolean's name. It exists because\na flat RequiredFields entry cannot express \"name a workflow, but only\nwhen you have said one is needed\": the alternatives were forcing a\nmeaningless answer on the other branch, or accepting the omission and\ndefaulting it, which lets the model skip the decision entirely.\nA named field must also be a non-empty string when the trigger is true.",
"type": "object"
}
},
"required": [
"name"
],
"type": "object"
},
"Command": {
"additionalProperties": false,
"description": "Command is one executable gate or preflight command.",
"properties": {
"argv": {
"items": {
"type": "string"
},
"type": "array"
},
"expect_failure": {
"type": "boolean"
},
"name": {
"type": "string"
}
},
"required": [
"name",
"argv"
],
"type": "object"
},
"Gate": {
"additionalProperties": false,
"description": "Gate is the quality gate an agent must satisfy.",
"properties": {
"commands": {
"items": {
"$ref": "#/schemas/Command"
},
"type": "array"
},
"max_consecutive_failures": {
"type": "integer"
}
},
"type": "object"
},
"HarnessSpec": {
"additionalProperties": false,
"description": "HarnessSpec is how to drive a Kit's agent headlessly: its launch argv (image entrypoint and cmd) and the agent-sessions@1 verb tails appended to it.",
"properties": {
"adapter": {
"description": "Adapter names the output adapter reading the CLI's stream; empty is\na CLI with none.",
"type": "string"
},
"continue": {
"items": {
"type": "string"
},
"type": "array"
},
"env": {
"description": "Env is the invocation's entire environment. Nothing is inherited from\nthe worker, whose environment carries its credentials.",
"items": {
"type": "string"
},
"type": "array"
},
"launch": {
"items": {
"type": "string"
},
"type": "array"
},
"mcp_config": {
"description": "MCPConfig registers archie's MCP server with the CLI: an argv tail\ncarrying {{.MCPConfig}}, the path of a standard mcpServers config.\nA stage with capture tools needs it.",
"items": {
"type": "string"
},
"type": "array"
},
"prompt": {
"items": {
"type": "string"
},
"type": "array"
},
"resume": {
"items": {
"type": "string"
},
"type": "array"
},
"user": {
"description": "User is the Kit's user, a name or \"uid[:gid]\", that every invocation\nruns as. It is never root: the worker's credentials live in the same\ncontainer, readable only by the worker's user.",
"type": "string"
}
},
"required": [
"launch",
"prompt"
],
"type": "object"
},
"MediaAttachment": {
"additionalProperties": false,
"description": "MediaAttachment describes a file attached to a message.",
"properties": {
"data": {
"contentEncoding": "base64",
"description": "Data carries the attachment bytes in-process. An inbound path sets\nit after downloading the file; outbound senders never set it and\nread Path or URL instead. It crosses the wire in one direction only:\nthe inbound request from a channel frontend to the Gateway process\nthat runs the turn, because that process never holds the platform\ncredential. It is never persisted, and the stored-history and\noutbound-event directions strip it.",
"type": "string"
},
"duration": {
"description": "Duration is the play time in seconds for audio and video.",
"type": "integer"
},
"file_id": {
"description": "FileID is the platform-assigned identifier for download APIs.",
"type": "string"
},
"file_name": {
"description": "FileName is the original file name when known.",
"type": "string"
},
"file_size": {
"description": "FileSize is the attachment size in bytes. nil means unknown.",
"type": "integer"
},
"height": {
"description": "Height is the pixel height for images and video. nil means unknown\nor not applicable.",
"type": "integer"
},
"mime_type": {
"description": "MIMEType is the content type (e.g. \"image/png\", \"audio/ogg\").",
"type": "string"
},
"path": {
"description": "Path is a local filesystem path on the host that produced the\nattachment. It is the alternative to URL for outbound delivery: a\nURL is fetched by the platform, a Path is uploaded by us. A file the\nagent wrote has no URL and never gets one -- publishing it would\ntrade a delivery problem for a hosting and access-control one -- so\nsenders that support upload must read this.\n\nExactly one of URL and Path is meaningful for an outbound send.",
"type": "string"
},
"raw": {
"description": "Raw carries platform-specific fields the common vocabulary does not\ncover, so adapters never need a second attachment type.",
"type": "object"
},
"type": {
"description": "Type is \"image\", \"video\", \"audio\", \"voice\", or \"document\".",
"type": "string"
},
"url": {
"description": "URL is a direct download URL when available. May be empty for\nplatforms that require a download API call.",
"type": "string"
},
"width": {
"description": "Width is the pixel width for images and video. nil means unknown\nor not applicable.",
"type": "integer"
}
},
"required": [
"type",
"file_id"
],
"type": "object"
},
"MessageEvent": {
"additionalProperties": false,
"description": "MessageEvent is the rich message model for gateway channels.",
"properties": {
"callback_data": {
"type": "string"
},
"channel_id": {
"type": "string"
},
"edited_from": {
"type": "string"
},
"id": {
"type": "string"
},
"media": {
"items": {
"$ref": "#/schemas/MediaAttachment"
},
"type": "array"
},
"platform": {
"type": "string"
},
"raw": {
"type": "object"
},
"reacted_to_id": {
"type": "string"
},
"reaction": {
"type": "string"
},
"reply_to_id": {
"type": "string"
},
"sender_id": {
"type": "string"
},
"sender_name": {
"type": "string"
},
"text": {
"type": "string"
},
"thread_id": {
"type": "string"
},
"timestamp": {
"type": "integer"
},
"type": {
"type": "string"
}
},
"required": [
"type",
"channel_id",
"platform",
"sender_id"
],
"type": "object"
},
"PluginSpec": {
"additionalProperties": false,
"description": "PluginSpec is a bundled Yaegi plugin passed from daemon to agent.",
"properties": {
"name": {
"type": "string"
},
"src": {
"type": "string"
}
},
"required": [
"name",
"src"
],
"type": "object"
},
"Protection": {
"additionalProperties": false,
"description": "Protection describes paths the agent may read but not mutate.",
"properties": {
"globs": {
"items": {
"type": "string"
},
"type": "array"
},
"suffixes": {
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"Usage": {
"additionalProperties": false,
"description": "Usage preserves provider-reported token economics for evaluation.",
"properties": {
"cache_creation_tokens": {
"type": "integer"
},
"cached_tokens": {
"type": "integer"
},
"completion_tokens": {
"type": "integer"
},
"prompt_tokens": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
}
},
"type": "object"
}
}
}
-935
View File
@@ -1,935 +0,0 @@
{
"pages": [
{
"url": "/dev/architecture/",
"title": "Architecture",
"section": "Architecture",
"body": "# Architecture\n\nArchie is a personal agent platform built around six domain boundaries:\n\n- Identity tracks users and other actors responsible for actions.\n- Agent owns persistent assistants, specialisation, and continuity.\n- Messaging owns conversations, messages, branches, and channel correlation.\n- Workflow owns reusable, versioned behaviour definitions and their executions.\n- Work Intake admits optional durable work without constraining ordinary agent\n conversation or direct capability use.\n- Plugin owns generic extension discovery and lifecycle; each capability family\n owns its typed plugin contract.\n\nThe detailed architecture and migration decisions are maintained under\n`docs/architecture/` in the repository while this generated site is being\nassembled.\n"
},
{
"url": "/dev/architecture/agent-system/",
"title": "Agent System",
"section": "Architecture",
"body": "# Agent System\n\n**Status:** Current-state investigation in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Domain framing\n\nThe domain is the Agent System.\n\n`Task` is not a core Agent System concept. Forge tasks, forge issues, Jira\nissues, email, Telegram messages, webhooks, and future external inputs are\nchannel-specific messages. Channels translate those messages into requests to\nthe Agent System; external issue or task models MUST NOT shape execution state.\n\nThe current `store.Task` is a persisted workflow execution. Treating that row as\na task-domain aggregate would incorrectly turn Archie into an agentic issue\nboard.\n\n## Canonical agent interaction model\n\nAn **Agent** is a persistent assistant selected for an interaction. It is not a\nmodel invocation and is not a WorkflowExecution.\n\nEach Agent has its own:\n\n- immutable acting `IdentityID` for ownership and audit;\n- durable memory and learned information about the user;\n- perspective, specialisation, instructions, and communication behaviour;\n- conversation history and channel bindings;\n- available tools, capabilities, and policy;\n- continuity across model or provider changes.\n\nThe underlying model is a replaceable runtime dependency. Changing a model,\nprovider, or model version MUST NOT create a new Agent, discard its memory, or\nchange ownership of its history.\n\nA user MAY create multiple Agents. Each Agent develops its own memory and view\nof the user from the interactions and responsibilities assigned to it. Memories\nMUST NOT be silently pooled merely because Agents belong to the same user or\napplication.\n\nAgent and Identity are separate aggregates. Every Agent references exactly one\nacting IdentityID, and no two Agents share an agent identity. User, system, and\nservice-account identities may exist without an Agent.\n\nAn action initiated through an Agent records the Agent's acting IdentityID and,\nwhen applicable, the initiating user's IdentityID. A future fully automated\nWorkflowExecution MAY use an explicitly selected service-account identity for a\nconcrete unattended use case; this is not the default execution identity.\n\n## Workflow execution identity\n\nA Workflow is owned by an IdentityID. By default, every WorkflowExecution acts\nas the Workflow owner's identity.\n\nFuture delegated execution MAY add an explicit `RunAsIdentityID` assignment to a\nWorkflow. This allows a Workflow owner to select another user or service-account\nidentity for execution without changing Workflow ownership. Until that\ncapability is deliberately introduced, owner identity and execution identity are\nthe same.\n\nWorkflowExecution audit records MUST preserve the Workflow owner, effective\nexecution identity, initiating user when one exists, and any explicit delegation\nthat selected a different run-as identity.\n\n## Memory scopes\n\nThe Agent System requires four distinct durable memory scopes:\n\n- **global shared memory**: information intentionally available across the\n Archie application;\n- **agent-wide memory**: general expertise, operating knowledge, and perspective\n owned by one Agent and safe for that Agent to use across users;\n- **user-wide memory**: information associated with one user and available to\n authorised Agents serving that user;\n- **Agent-user relationship memory**: private history and learned context from\n one particular Agent's relationship with one particular user.\n\nAgent-wide memory is private to its owning Agent by default. Another Agent MUST\nNOT read, inherit, search, or mutate it implicitly.\n\nAgent-user relationship memory is addressed by both AgentID and User IdentityID.\nNeither another Agent serving the same user nor another user speaking to the\nsame Agent may access it implicitly.\n\nArchie is a multi-user system even when initially deployed for one person.\nMultiple users, including family members, may interact with the same configured\nAgents. Per-user memory is therefore an isolation and personalisation boundary,\nnot merely an attribution tag on the primary user's records.\n\nAn Agent MUST resolve the initiating user before assembling memory context.\nMemory belonging to one user MUST NOT become visible to another user merely\nbecause both users interact with the same Agent.\n\nShared memory does not erase provenance. Every memory record retains its scope,\nauthor or acting identity, originating user when applicable, source, and\nrevision history. The rules for selecting a write scope, granting access\nto global and user-wide memory, and authorising explicit cross-scope sharing are\nsettled by [`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\nand recorded in [`migration-decisions.md`](/dev/architecture/migration-decisions/#5-memory-placement-and-storage)\nsection 5.\n\nAn Agent interaction may answer conversationally, use a tool or capability, read\norLine truncated
},
{
"url": "/dev/architecture/bindings/",
"title": "Playbook bindings: model and threat model",
"section": "Architecture",
"body": "# Playbook bindings: model and threat model\n\n**Status:** Approved foundation (documents shipped code: `archie-core-t2db.1`\nthrough `.5`, `.7`, `.9`-`.15`)\n**Date:** 2026-09-03\n\nThis document covers the binding model and the intake threat model portion\nof `archie-core-t2db.6`. It does not cover the task-lifecycle provenance rule\n(`messaging-and-work-intake.md`'s \"Intake provenance\") or the operator\nwalkthrough -- that walkthrough remains an open piece of the same ticket.\n\n## What a binding is\n\nA `binding` (`internal/domain/binding.Binding`) ties four things together:\na **matcher** (which captured events it applies to), a **mapping**\n(`internal/domain/mapping.Mapping`, how fields are pulled out of a payload),\na **workflow** (which registered workflow runs on a match), and a **state\nmachine** governing whether it is live.\n\n```go\ntype Binding struct {\n ID, Name // identity\n Matcher // { Source string } -- the webhook path segment, e.g. \"sentry\"\n MappingID // which Mapping resolves payload fields; its event type is the binding's\n Filter // optional CEL over the mapping's parameters\n Workflow // registered workflow name to dispatch to\n Version // bumped on every edit\n Status // pending_approval | armed\n Secret // HMAC-SHA256 shared secret, encrypted at rest, never returned by GET\n}\n```\n\nBindings live in the store (PostgreSQL), not `config.toml` -- operators author\nthem from the dashboard while the daemon runs, without a restart.\n\n### Matching\n\nA binding applies to a capture when the capture arrived on `Matcher.Source`,\nwas identified as the event type its mapping belongs to, and passes its\n`Filter` (`binding.CompileFilter`, checked against the mapping's parameters on\nsave). Any number of bindings may share a source; each dispatches a capture at\nmost once, claimed in `binding_dispatches` keyed by (binding, capture) before\nits task is enqueued. An event signed with any armed binding's secret on the\nsource is authenticated.\n\n### Mapping\n\n`mapping.Resolve(fields, payload)` walks a captured JSON payload against a\nlist of typed `Field`s (name, JSON path, expected type), returning resolved\nvalues plus a `[]Failure` for anything that didn't parse or type-match. A\nmapping belongs to an event type, and `mapping.CheckSchema` refuses a field\nwhose path or type the type's inferred schema lacks. Each capture a mapping\nresolves at dispatch is counted once in `mapping_matches`, read back as\n`MatchCount` and `LastMatchedAt`.\n\n### Versioning\n\n`Version` increments on every `UpdateBinding` call. This exists so an\neditor's later change can never silently rewrite the historical provenance\nof a task that already fired -- a dispatched task's binding reference is\npinned to the version that was armed when it fired, not \"whatever the\nbinding currently says.\"\n\n### State machine\n\n```\ncreate ---\u003e pending_approval ---\u003e armed\n ^ |\n +----------------+\n (any edit to an armed binding drops it back to pending_approval)\n```\n\nA binding is created `pending_approval`, so the operator who creates one can\napprove it immediately. Bindings stored as `draft` by an earlier version are\nmoved to `pending_approval` when the EDA store opens.\n\nModelled directly on Telegram's existing `dangerousAction`/`pendingApproval`\nflow (`internal/channels/telegram/dangerous.go`, `approval.go`) -- not a new\napproval mechanism invented for this feature. **Only `armed` evaluates\nagainst incoming events** (`binding.Matches`, `internal/domain/binding/\nbinding.go`); a `pending_approval` binding is inert. An edit to\nan already-armed binding cannot bypass approval by silent mutation -- it\ndrops back to `pending_approval` and requires an explicit `Approve` call to\nre-arm.\n\n## The threat model\n\nThis is a public, unauthenticated-by-default intake surface whose output is\nan agent with a repo, a worktree, and tool access. The design brief\n(`archie-core-t2db.5`, `docs/prds/webhook-intake-security.md`) named five\nnon-negotiables; each is verified below against the actual shipped code,\nnot the design intent.\n\n### 1. Per-source authentication\n\nReuses `internal/channels/webhook`'s existing HMAC-SHA256 scheme --\ncapture accepts unsigned events (visible in the dashboard, marked\nunauthenticated), but **only authenticated events can ever match a\nbinding**. `binding.Matches`' doc comment states this plainly: \"an\nunauthenticated event can never trigger a binding, no matter how well it\nwould otherwise match.\" Enforced structurally at two points, not just\nconvention:\n\n- `captures.authenticated` is a real column\n (`internal/infrastructure/postgres/migrations/0002_edastore.sql`), set at\n capture time.\n- `dispatchBindings` (`internal/daemon/daemon.go:479`) walks **authenticated\n captures whose soLine truncated
},
{
"url": "/dev/architecture/configuration/",
"title": "Configuration",
"section": "Architecture",
"body": "# Configuration\n\n**Status:** Approved; existing-type assignment is ongoing \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Ownership\n\nConfiguration has two separate responsibilities:\n\n1. `internal/infrastructure/configuration` loads files, environment variables,\n secret references, overlays, and compatibility representations.\n2. Each domain and plugin owns the typed runtime settings required for its\n behaviour.\n\n`internal/app` translates external input into those settings, validates\ncross-capability combinations, and supplies each component only its own\nsettings.\n\nThe following are prohibited:\n\n- passing complete application configuration into a domain;\n- making a domain depend on TOML, YAML, environment-variable names, secret\n references, or a configuration library;\n- defining a central runtime configuration type imported across the system;\n- placing plugin options in an unrelated global configuration model.\n\n## Private input document\n\n`internal/infrastructure/configuration` MAY use a complete decoded document\nwhile discovering files, decoding sections, and applying overlays. It is an\ninput-boundary DTO only.\n\nThe document:\n\n- remains private to the configuration infrastructure;\n- is composed from separately defined feature sections;\n- is immediately translated by application composition;\n- is never returned as the application's runtime model;\n- is never passed through runtime components.\n\nExternal DTOs and domain runtime settings are separate types.\n\nPlugins supply external configuration definitions through a narrow extension\ncontract. The core loader MUST NOT gain a field or recognised filename for every\nplugin.\n\nInvalid configuration input MUST NOT replace active valid settings or terminate\nunaffected capabilities. Configuration changes use the candidate validation,\npromotion, audit, and recovery requirements in\n[safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/).\n\n## Dissolution of `internal/config`\n\n`internal/config` has no target location. It MUST be dissolved and MUST NOT\nsurvive as a shared package, configuration domain, or renamed global model.\n\nIts loading behaviour moves to `internal/infrastructure/configuration`. Existing\ntypes and methods are reassigned by behaviour. Repository execution policy,\ndispatch policy, retry policy, ecosystem defaults, tool policy, memory settings,\nprovider settings, and channel settings move to their\nrespective owners.\n\n## Repository settings\n\nThe existing `config.Repo` MUST NOT move intact into a repository domain or\nshared settings package. A managed repository is an application association:\n\n- work intake owns which repository references an identity monitors;\n- task execution owns gates, preflight, test protection, ecosystem behaviour,\n and change limits;\n- task lifecycle owns retry behaviour;\n- scheduling owns concurrency policy;\n- workspace management owns base branch and persistent-storage requirements.\n\nApplication composition correlates these settings by repository reference. No\ndomain receives a universal repository profile.\n\n## Documentation\n\nGenerated configuration reference describes external sections and their owning\ncapabilities. It MUST NOT establish a global Go configuration structure as the\npublic contract.\n\n## Value classification rule\n\nEvery value that controls behaviour MUST have an explicit owner and MUST be\nclassified as exactly one of:\n\n1. **Invariant** — changing it changes the meaning of the program, a wire\n protocol, or a domain concept. It may be a Go constant.\n2. **Runtime setting** — an operator, identity, domain, plugin, or deployment\n may legitimately choose a different value. It is typed configuration owned by\n the affected capability.\n3. **Policy value** — it expresses what is allowed, limited, routed, retried,\n protected, or gated. Its typed definition belongs to the owning domain and it\n is evaluated through the policy system.\n4. **Derived value** — it is computed from other settings and is not\n independently mutable.\n5. **Runtime state** — it changes as the application operates, such as the\n active model for a conversation. It is changed by a domain command and is not\n configuration merely because it can be changed.\n\nAn unclassified behavioural literal is a defect.\n\n`const` MUST NOT be used merely because a value currently has one default.\nConstants are reserved for actual invariants: enum discriminants, protocol\nversions, fixed compatibility tokens, and values whose alteration would change\nthe program's semantics rather than configure an installation.\n\nIn Go, a constant is a compile-time value and does not represent mutable runtime\nstorage. It generally has no address that can be observed or changed.\nArchitecturally, a constant therefore asserts that the value cannot change for\nthe lifetiLine truncated
},
{
"url": "/dev/architecture/dashboard-agent-tools/",
"title": "The dashboard's tools for an in-browser agent",
"section": "Architecture",
"body": "# The dashboard's tools for an in-browser agent\n\nThe dashboard registers in-browser tools an agent can call through the page's model\ncontext. Four are read-only — `list_tasks`, `get_task`, `recent_events`,\n`daemon_health` — and three recover stuck work: `retry_task`, `stop_task`,\n`cancel_task`. Each wraps the same `ui/src/lib/api.ts` client the dashboard itself\ncalls, so an agent and a person exercise one path rather than two.\n\nThe four judgement verbs are withheld for the reason `identity.md` gives: an agent\nthat can approve can approve its own work.\n\n## What a tool call can be attributed to\n\nA page can invoke its own tools, so an agent's call and a page script's call reach\nthe server identically — the difference does not exist on the wire, and no header\nrecovers it. A tool call is therefore attributed to the signed-in identity the\nrequest presented, with its source recorded as a hint; it never records that an\nagent acted, and it never records that a human approved. An agent's action is\nattributable only on a surface where the agent presents its own credential.\n\n## Confirmation is a signal, not a control\n\nThe three recovery tools require an explicit `confirm: true`, which makes a\nconsequential call deliberate rather than incidental. It is not a security control:\nan agent can trivially satisfy it, and the browser cannot enforce\n`consequentialHint` at all — Chrome accepts it at registration and omits it from\n`getTools()`, so no client can see what the browser does not surface.\n\nThe boundary that holds is the session. These tools cannot exceed what the operator\nsigned in at the provider is already permitted to do.\n\n## Two ways the surface fails silently\n\n- **A secure context is required.** On a plain-HTTP origin `document.modelContext` is\n absent even with the flag enabled, and nothing reports why. `mkcert` covers local\n development.\n- **The dashboard embeds `ui/dist` into its binary.** Rebuilding the distribution is\n not deploying it: a running process can serve a bundle without tools while the\n built one has them, or serve a bundle older than its own binary.\n"
},
{
"url": "/dev/architecture/dependencies-and-contracts/",
"title": "Dependencies and Contracts",
"section": "Architecture",
"body": "# Dependencies and Contracts\n\n**Status:** Approved foundation \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Dependency direction\n\n```text\ndomain and shared application contracts \u003c- infrastructure implementations\n ^\n |\n application composition\n```\n\nThe following rules are strict:\n\n1. Domains MUST NOT import `internal/infrastructure`.\n2. A domain defines the smallest interfaces required to perform its work.\n3. Infrastructure implements those interfaces and translates external\n representations at the boundary.\n4. Only application composition chooses concrete implementations.\n5. A domain MUST NOT manipulate another domain's state or call its internal\n services.\n6. Cross-domain work uses an explicitly designed command, event, or approved\n shared contract.\n7. Implementation difficulty is not permission to violate a boundary.\n\nBroker messages, database rows, SDK response types, and configuration DTOs MUST\nNOT leak into domain models.\n\n## Commands and events\n\n- An event records something that happened and is owned by its publishing\n domain.\n- A command requests an action and is owned by the domain expected to handle it.\n- Consumers do not redefine an event's meaning.\n- Senders obey the receiving domain's command contract.\n- There is no generic package containing unrelated application messages.\n\n## Event bus\n\n`internal/eventbus` is an approved shared application contract. It defines only\nthe messaging behaviour Archie requires, including publication, subscription,\ndelivery outcomes, and required lifecycle semantics.\n\nIt MUST remain broker-neutral. NATS subjects, JetStream configuration, consumer\ngroups, acknowledgements, reconnection, and serialisation belong under\n`internal/infrastructure/eventbus/nats` unless Archie explicitly requires a\nsemantic guarantee in the shared contract.\n\nMessage schemas stay with their owning domains. The event bus transports\nmessages; it does not own their meaning.\n\n## Wire contracts and generation\n\nCanonical worker and service wire contracts and their authoritative generation\ninputs are owned by the domain or capability that defines their meaning. They\nMUST NOT be centralised in `internal/infrastructure/spec` or another generic\nschema package.\n\nInfrastructure owns:\n\n- generic contract-generation machinery;\n- transport-specific adapters and generated implementations;\n- RPC, REST, NATS, and other external encoding and delivery concerns.\n\nFor example, agent-worker requests and results belong to task execution.\nSubprocess, NATS, or HTTP representations are infrastructure implementations of\nthat contract. The same rule applies independently to forge, persistence,\nworkspace, and other service contracts.\n"
},
{
"url": "/dev/architecture/generated-documentation/",
"title": "Generated Documentation",
"section": "Architecture",
"body": "# Generated Documentation\n\n**Status:** Data generation lives here; rendering and publishing live in the external Astro website\n**Date:** 2026-07-28 (revised 2026-09-25)\n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie's documentation-generation approach is:\n\n- production Go code, registries, configuration, and CLI behaviour remain the\n source of truth for published contracts;\n- a repository-local Go generator extracts and normalises documentation data;\n- the generator writes deterministic JSON/data files and protocol schemas;\n- the external Astro website consumes generated data and serves the public\n documentation at `offloaded.dev/docs/`.\n\nHugo is not part of the target architecture.\n\nThe documentation system is rooted at:\n\n```text\ntools/\n go.mod\n go.sum\n docsgen/\n main.go\ndocs/\n data/generated/\n public/schemas/\n *.md\n```\n\n### Rendering and publishing — external Astro website\n\nSuperseded 2026-09-12. The repository previously carried a VitePress site\n(`docs/.vitepress/config.mts`, `docs/package.json`, a 1620-line\n`docs/pnpm-lock.yaml`, `docs/pnpm-workspace.yaml`) built and deployed to GitHub\nPages by `.github/workflows/docs.yml`. It was removed as an unnecessary build\nstep: the published site was never stood up, and the Pages target is not\nconfigured.\n\nThe Astro website is maintained outside this repository. This repository owns\nthe Markdown source and generated JSON artifacts; it does not build, preview, or\ndeploy the site. The external site owns page rendering, navigation, and\npublishing.\n\nThe current boundaries are:\n\n| Concern | Owner |\n| --------------------------------------- | -------------------------------------------------------------------- |\n| Reference-page rendering and publishing | External Astro website |\n| Documentation source and generated data | This repository |\n| Generated-data drift detection | `task docs:check`, `task docs:artifact:check`, and `task news:check` |\n| Navigation data | `docs/data/generated/docs.json` and `dev-docs.json` |\n\nChanges to an artifact contract must be coordinated with the external Astro\nconsumer. This repository does not validate the website's rendered links or\nroutes.\n\n## Single source of truth\n\nEvery published capability has one authoritative machine-readable definition\nowned by its domain or application boundary. Generated documentation derives\nfrom those definitions.\n\nGenerated reference includes:\n\n- domain commands and events;\n- Messages and typed message content;\n- Agent and Workflow contracts;\n- WorkflowSteps and Workflow plugin capability contracts;\n- policies and their typed inputs and outcomes;\n- tools and capabilities;\n- CLI commands, arguments, flags, defaults, and help;\n- runtime settings, types, defaults, validation, and secret metadata;\n- public worker and transport contracts;\n- indexes of registered functionality;\n- deprecation information.\n\nHandwritten documents contain:\n\n- architecture decisions and rationale;\n- tutorials and operational guides;\n- examples and walkthroughs;\n- migration guidance;\n- conceptual explanations.\n\nHandwritten documents link to generated reference rather than copying\nauthoritative tables.\n\n## Target generation architecture\n\n`tools/docsgen` is Archie's documentation extractor and normalizer. It produces\nstructured documentation data and protocol specifications. It does not own\npage layout and MUST NOT generate Markdown pages or fragments.\n\nThe generator is divided internally into reusable stages:\n\n```text\nload registries and types\n -\u003e normalize documentation model\n -\u003e validate ownership and identifiers\n -\u003e serialize data and protocol artifacts\n -\u003e compare or write output\n```\n\nThe normalised documentation model prevents each output renderer from\nindependently interpreting Go types. It contains stable documentation IDs,\nowners, names, descriptions, source references, versions, deprecations, fields,\ndefaults, validation, secret classifications, and relationships.\n\nInitial generator targets:\n\n```text\ndocsgen data\ndocsgen asyncapi\ndocsgen all\ndocsgen check\n```\n\n- `data` writes the normalised JSON reference data.\n- `asyncapi` writes protocol schemas and envelopes.\n- `all` generates every committed artifact.\n- `check` generates into a temporary directory and fails on drift.\n\nThe command may use subcommands or an equivalent explicit `--target` flag. It\nMUST retain one normalisation and validation path.\n\n## Target output\n\nDuring adaptation, `docs` remains the staging site. Generated outputs live in\na visibly owned subtree:\n\n```text\ndocs/\n data/\n geLine truncated
},
{
"url": "/dev/architecture/identity/",
"title": "Identity",
"section": "Architecture",
"body": "# Identity\n\n**Status:** Approved foundation; lifecycle details are deferred \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nIdentity answers which persistent actor owns or performed an action. It supplies\nstable cross-domain attribution and lifecycle semantics.\n\nIdentity kinds include:\n\n- the Archie system identity, such as `System` or `archied`;\n- agent or bot identities;\n- service-account identities;\n- future user identities.\n\nA user is another kind of identity rather than a separate foundation concept.\n\n## Ownership\n\n`internal/domain/identity` owns:\n\n- immutable canonical `IdentityID` values;\n- identity kind;\n- lifecycle state;\n- ownership and attribution semantics;\n- identity-related commands and events.\n\nDomains may record an identity reference on their own state and events when\nownership or attribution is required. They MUST NOT receive a complete\nper-identity application configuration bundle.\n\nPersona and communication style are separate from identity.\n\nEvery Agent has its own immutable acting `IdentityID`. Agent actions use that\nidentity for ownership and attribution in the same way an organisation records\nwhich user accessed a resource, changed a permission, or performed another\nauditable action.\n\nAgent and Identity remain separate aggregates. Identity supplies the stable\nactor reference; Agent owns assistant behaviour, memory, specialisation,\nconversations, and capability context.\n\nAgent identities MUST NOT be shared between Agents. Automated WorkflowExecutions\nMAY eventually act through a dedicated service-account identity when a specific\nunattended automation requires it. Such use is an explicit execution decision\nand audit principal, not the default for Agents or a substitute for recording\nthe initiating user when one exists.\n\nA Workflow is owned by an IdentityID and executes as its owner by default.\nFuture delegated execution MAY explicitly assign a different `RunAsIdentityID`,\nincluding a user or service-account identity. Ownership, effective execution\nidentity, initiating identity, and delegation provenance remain distinct audit\nfacts.\n\n## Canonical identity\n\nEvery identity has an immutable `IdentityID`. It is the only value used for\ncross-domain ownership, attribution, routing, persistence, commands, and events.\n\nIdentity kind is explicit:\n\n- system;\n- bot;\n- service account;\n- user.\n\nDisplay names are mutable and MUST NOT be used as identifiers. Forge usernames,\nchannel bot names, Git authors, provider account names, and other external\nidentifiers are bindings associated with an identity rather than identity\nitself.\n\n`System` is represented by a real identity and `IdentityID`. The empty string\nMUST NOT retain special meaning as a legacy system identity.\n\nConfiguration refers to identities by `IdentityID` and supplies external\nbindings and capability settings separately. Renaming an identity or changing an\nexternal account MUST NOT change ownership or historical attribution.\n\nSecret-bearing channel bindings remain configuration concerns rather than\nidentity data. In particular, `[chat.telegram].token` is a\n`secret.SecretRef` resolved by the application through the configured secret\nregistry. It does not change the identity that owns or performs a chat action.\n\n## Persistence\n\nIdentity records are durable domain state. The Identity domain's repository is\nthe source of truth; infrastructure implements its persistence contract.\n\nConfiguration MAY bootstrap a missing identity through an explicit, audited\ncreation operation and MAY propose runtime capability bindings for an existing\n`IdentityID`. Configuration is not the identity registry.\n\nOmitting an identity from configuration stops assembling the omitted runtime\ncapabilities. It MUST NOT delete the identity record, erase history, or make\nhistorical references unresolvable.\n\nDisabling or retiring an identity requires an explicit Identity-domain command.\nRetired identities remain resolvable for historical attribution. A failed\nexternal binding affects capability availability without destroying or silently\nreplacing the identity.\n\n## Lifecycle\n\nIdentity lifecycle is deliberately small:\n\n- `active`: may participate in runtime composition;\n- `suspended`: deliberately prevented from initiating new work while ownership\n and history remain;\n- `retired`: terminal, unable to initiate work, and permanently retained for\n attribution.\n\nAllowed transitions are:\n\n```text\ncreate -\u003e active\nactive -\u003e suspended\nsuspended -\u003e active\nactive -\u003e retired\nsuspended -\u003e retired\n```\n\n`retired` has no outgoing transition.\n\nCapability health is separate from identity lifecycle. Forge, model, channel,\nworkspace, and other bindings report health independently. An active identity\nmay be partially degraded without becoming suspended or reLine truncated
},
{
"url": "/dev/architecture/messaging-and-work-intake/",
"title": "Messaging and Work Intake",
"section": "Architecture",
"body": "# Messaging and Work Intake\n\n**Status:** Current state researched; foundation decisions in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is a personal assistant and general agentic system. Its interactions\ninclude conversation, questions, notes, reminders, goals, message handling,\ntroubleshooting, infrastructure operations, server management, source changes,\nand open-ended future capabilities.\n\nA message to an agent is therefore not inherently a work request, and invoking\nan agent is not inherently a WorkflowExecution.\n\nMessaging and work intake are separate from the Agent System's durable workflow\nexecution model:\n\n- messaging preserves interactions with people and external systems;\n- an agent turn interprets and responds to an interaction using its available\n capabilities;\n- work intake handles the optional promotion of an interaction into durable,\n workflow-backed work;\n- the Agent System owns Workflow definitions and creates WorkflowExecutions.\n\nForge issues, Jira issues, Telegram messages, emails, webhooks, and future\nchannels remain peer external message or artifact sources. None becomes an\nexecution model merely because it can lead to work.\n\n## Confirmed boundary\n\nWork intake MUST NOT create a WorkflowExecution directly.\n\nInbound interactions normally route to the Agent selected by the channel\nbinding. The selected Agent retains its own memory, user knowledge, conversation\ncontinuity, specialisation, and capability context. This continuity is\nindependent of the underlying model or provider.\n\nEach selected Agent acts through its own immutable IdentityID. Interaction and\nresulting action records preserve both that acting identity and the initiating\nuser identity when one exists.\n\nAgent memory is private by default. Interaction context MAY additionally use\nuser-wide memory and intentionally global shared memory, but another Agent's\nagent-wide memory is not part of the selected Agent's context.\n\nMultiple users may interact with the same Agent. The channel binding and inbound\nmessage MUST resolve both AgentID and initiating User IdentityID before\nconversation or memory context is loaded. Sharing an Agent MUST NOT implicitly\nshare one user's private memory with another user.\n\nAn interaction may assemble memory from four scopes: global shared, the selected\nAgent's agent-wide memory, the initiating user's authorised user-wide memory,\nand the private Agent-user relationship memory addressed by both IDs.\n\n## Conversation identity\n\nEvery conversation is identified by the complete tuple:\n\n```text\nAgentID\n+ UserIdentityID\n+ ChannelBindingID\n+ ExternalConversationID\n+ ThreadID\n```\n\n`ThreadID` has an explicit empty value for channels without threads. No element\nof this key may be replaced by a display name, configured bot username, channel\ntype, or other mutable label.\n\nAgent and user memory continue across conversations according to their memory\nscope. Immediate conversation history and delivery correlation remain isolated\nto the identified channel conversation or thread. Moving between Telegram,\nemail, or another channel does not create a new Agent or user, but it does\ncreate a distinct conversation unless an explicit linking operation relates\nthem.\n\nConversation and message events support projections for channel-entry metrics,\nuse cases, volumes, outcomes, latency, capability usage, and other product or\noperational analysis. Metrics are derived read models; they MUST NOT become\nmutable counters embedded in the conversation aggregate or change message\nrouting semantics.\n\n## Canonical messages\n\nEvery inbound, assistant, tool-call, and tool-result message has an immutable\napplication-generated MessageID. Platform identifiers are external correlation,\nnot substitutes for the canonical ID.\n\nMessages are addressable because an interaction is more than text. A message may\ncontain assistant content, reasoning data subject to its retention policy, one\nor more tool calls, a tool result with authoritative execution metadata,\nattachments, reply relationships, edits, or other typed content. Stable\nMessageIDs also allow sessions to branch from an exact prior point.\n\nThe canonical session and message implementation must supply:\n\n- application-generated stable message IDs;\n- user, assistant, and tool roles;\n- assistant tool calls and correlated tool-result messages;\n- authoritative tool-result status, timing, error, truncation, and size\n metadata;\n- session lifecycle and active-request state;\n- session-to-agent-instance and parent-session lineage;\n- durable database round trips and timestamp validation.\n\nThese semantics must use the confirmed Agent, user, channel-binding, and\nconversation ownership model.\n\nThe canonical message store MUST preserve messages as immutable records and\nrepresent later edits, deletionLine truncated
},
{
"url": "/dev/architecture/migration-decisions/",
"title": "Architecture Migration Decisions",
"section": "Architecture",
"body": "# Architecture Migration Decisions\n\n**Status:** Active migration inventory \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nThis document records what remains to be decided before Archie's current\nimplementation can be migrated into the approved domain-oriented structure.\n\nThe product and core domain model are not being redesigned. Existing Archie\nbehaviour and the existing session implementation are the migration\nbaseline. Remaining decisions MUST be grounded in current packages, consumers,\ntests, persistence, and runtime wiring.\n\n## Confirmed domain packages\n\n```text\ninternal/domain/\n identity/ (approved, not yet materialised as a package)\n agent/ (approved, not yet materialised as a package)\n workflow/\n messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)\n workintake/\n plugin/ (approved, not yet materialised as a package)\n curator/\n mapping/\n scheduling/\n```\n\n- `identity` owns persistent actors, lifecycle, ownership, attribution, and\n audit identity.\n- `agent` owns persistent assistants, specialisation, instructions,\n model-independent continuity, capability context, and associations with\n identity and memory.\n- `workflow` is a separate domain. It owns reusable, versioned Workflow\n definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts,\n outcomes, and typed Workflow plugin contracts.\n- `messaging` owns canonical Messages, Conversations, branches, channel and\n source correlation, replies, acknowledgements, delivery attempts, events, and\n projections.\n- `workintake` owns admission, validation, deterministic routing, and accepted\n work requests for the optional transition into durable workflow-backed\n execution.\n- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle\n mechanics. It remains metadata-only; capability semantics and typed\n registration belong to the owning domain.\n- `curator` owns the curator engine family: long-running agent loops that\n reason over memory and perform maintenance tasks on a declared shape\n (check-in interval, tool set, attached memory engine). See epic\n archie-core-yp9.\n- `mapping` owns the payload field-mapping vocabulary: binding named fields to\n JSON paths inside a captured webhook payload, and detecting drift. See\n `docs/prds/payload-field-mapping.md`.\n- `scheduling` owns the ticker engine: deciding when a scheduled job runs and\n with what concurrency. It declares `JobSource`/`Runner` contracts and owns\n no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.\n\n**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed\nin the tree without being added to this list when their epics landed. They are\nconfirmed as legitimate, narrowly-scoped domains under the same rules as the\noriginal six — each owns one capability family, declares typed contracts, and\nhas no cross-domain reach. This list was out of date, not the tree.\n\nConversely, `identity`, `agent`, `messaging`, and `plugin` are approved target\ndomains that do not yet exist as packages. Their behaviour currently lives in\npre-migration packages (see \"Complete package destination map\" below for the\nfull inventory). Do **not** create empty stub packages for them ahead of an\nactual migration PR — an unused stub is dead code and gives no test coverage.\nEach materialises when its corresponding migration decision below is resolved\nand implemented in the same change.\n\nMemory's final package placement remains undecided pending focused review of the\nexisting implementation.\n\nThe following are approved shared or composition packages, not domains:\n\n```text\ninternal/eventbus/\ninternal/policy/\ninternal/infrastructure/\ninternal/app/archied/\ninternal/app/agentworker/\n```\n\n## Remaining migration decisions\n\n### 1. Complete package destination map\n\nEvery current package MUST receive one explicit disposition:\n\n- move into a confirmed domain;\n- move under infrastructure as an implementation of a domain-owned contract;\n- move into application composition;\n- merge with an identified duplicate;\n- remain as an approved shared application contract;\n- move to a plugin, extra, deployment, example, or generated artifact;\n- be deleted after its replacement is proven.\n\nThe largest unreviewed areas include memory, tools and capabilities, workspace\nand worktree behaviour, gates, storage, events, web UI, containers, RPC\npackages, release management, and scheduling.\n\nThe destination matrix MUST name the behaviour owner, target path, dependencies\nto remove, state and contracts to preserve, migration prerequisites, and\ndeletion criteria.\n\n**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**\nThe current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator\nauthLine truncated
},
{
"url": "/dev/architecture/observability/",
"title": "Task Observability",
"section": "Architecture",
"body": "# Task Observability\n\n**Status:** Implemented. The per-run detail surface was added on 2026-09-18 and\nis described below.\n**Date:** 2026-08-09 (revised 2026-09-18)\n\n## Historical problem\n\narchied's own daemon logging (`internal/logging/`) was already solid: a\nrotating file sink, a live `Feed` the dashboard subscribes to, and a reader\nthe `/api/logs` endpoint serves from. Before this implementation, none of\nthat reached inside a task.\n\nA task's actual work happens in a task-scoped `archie-agent` container,\ndispatched as one complete workflow over NATS.\nBefore this design was implemented, five things destroyed the evidence of what\nthat container did:\n\n1. **Worker startup** constructed an stderr-only logger and never replaced its\n handler after discovering a dedicated boot task, so runtime records could\n not leave the container.\n2. **`internal/container/pool.go`** creates every task container with\n `AutoRemove: true`. The container — and its stderr — is gone at exit,\n success or failure alike.\n3. **`internal/domain/workflow/implement.go`, `StageBaselineGate`** captures\n `go build`/`go vet`/`go test` output via `cmd.CombinedOutput()`, then\n clips it to 200 characters into a `Warn` log line and discards the rest.\n The eventual park reason is built from `res.Status` alone — the actual\n compiler error is never persisted anywhere a human or Archie's own chat\n tools can read it back.\n4. **`agentexec.Result`** (`internal/agentexec/protocol.go`) carries only\n `Summary`/`Detail` — no step-by-step transcript (tool calls, durations,\n errors). There is no transcript to recover even in principle.\n5. **`agentexec.SubjectForSystem`** is documented as the return channel for\n exactly this — _\"log dumps, health, and PII warnings... the daemon reads\n these for observability and never forwards them\"_ — but has no publisher\n and no consumer anywhere in the codebase except a subject-format\n assertion in `nats_test.go`. The designed return path was never wired.\n\nThe practical consequence: a task parks with\n`stage baseline: baseline red -- go build ./... fails and builder could not\nauto-fix (status: parked)` and there is no way — not from the dashboard, not\nfrom Telegram chat, not by SSH'ing into the deployment host — to see _why_\n`go build` failed. The container that knew is already gone.\n\nThis matters beyond debugging convenience: supported deployments can combine\na resident daemon with ephemeral Docker containers that run unattended for\nweeks between operator logins, and the system is\nintended to be usable by people other than the original operator. A system\nthat is only debuggable by an operator who happens to be watching `docker ps`\nin real time does not meet that bar.\n\n## Decision: NATS is the sole autonomous handoff\n\nThe agent image must reach NATS in every deployment, because the broker is the\nonly autonomous task handoff and the only channel carrying task results back\nto the daemon. `archied` has no workflow runner or host fallback. A container\nthat dies before establishing a NATS connection is a distinct, narrower\nfailure (connectivity/config) from the one this document addresses (a connected\ncontainer's own output being unrecoverable), and is out of scope here.\n\n## Implemented design\n\nThe key property: **logs leave the container while it is alive**, so its\ndeath at `AutoRemove` no longer matters. Persistence happens in the daemon\nprocess, which already owns durable state.\n\n### Sink: extend `internal/logging`, not a new package\n\n`internal/logging` already owns its on-disk format end to end per\n`organisation.md` (\"a package owns its own format end to end\"). Add a\ntask-scoped writer producing the same `logging.Entry` JSONL shape at\n`\u003cstate_dir\u003e/logs/tasks/\u003ctask_id\u003e/attempt-\u003cn\u003e.jsonl`. `logging.Tail`,\n`logging.Query`, and `logging.Components` operate on this unchanged;\n`internal/webui/api_logs.go` stays transport-only, as it does today.\n\n### Agent side: make the designed subject real\n\n`internal/app/agentworker` replaces the stderr-only `slog.Handler` with one\nthat tees to stderr (kept for container-level operator debugging when a\nshell is attached) and publishes each record to\n`agentexec.SubjectForSystem(taskID)`, which already exists for this purpose.\nThe application layer obtains only a narrow publisher from\n`internal/infrastructure/agenttransport/nats`; raw core-NATS types remain in\ninfrastructure. `internal/infrastructure/agentboot.TaskID` reads the task ID\nfrom `\u003cworktree\u003e/.git/task.json` per the container/pool.go trap documented in\n`CLAUDE.md`. Publishing is fire-and-forget: log shipping must never block or\nfail the run it is reporting on.\n\n### Daemon side\n\n`cmd/archied/main.go` registers `subscribeSystemLogs` once at startup on\n`agentexec.SubjectSystemWildcard`. It demultiplexes by task ID, appends to that task's\nsink, and pLine truncated
},
{
"url": "/dev/architecture/organisation/",
"title": "Repository Organisation",
"section": "Architecture",
"body": "# Repository Organisation\n\n**Status:** Approved \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Target structure\n\nArchie MUST be organised around cohesive application responsibilities:\n\n```tree\ncmd/\n archied/\n archie-agent/\n\ninternal/\n domain/\n \u003carea\u003e/\n eventbus/\n policy/\n infrastructure/\n configuration/\n eventbus/\n nats/\n forge/\n persistence/\n \u003cexternal-service\u003e/\n app/\n archied/\n agentworker/\n\nplugins/\n \u003cplugin\u003e/\ndeployments/\n \u003csupported-assembly\u003e/\ndocs/\n guides/\nexamples/\n \u003ccopyable-example\u003e/\nextras/\n \u003coptional-extension\u003e/\n```\n\nDomain names are chosen from application behaviour during package review.\nExisting names MUST NOT be retained merely to reduce migration work.\n\n## Domain areas\n\nA domain owns one cohesive job performed by Archie. It contains that job's\nlanguage, state, rules, operations, commands, events, policy implementations,\nruntime settings, and required service contracts.\n\nCode that changes together SHOULD live together. Empty or ceremonial `entities`,\n`repositories`, or `services` layers are prohibited.\n\n## Application composition\n\n`internal/app`:\n\n- constructs domains and infrastructure implementations;\n- translates external configuration into domain and plugin settings;\n- connects commands, events, and shared contracts;\n- starts services in dependency order;\n- owns health aggregation and shutdown ordering.\n\n`cmd/*` parses only process-level input and invokes the relevant application\ncomposition package. It MUST NOT contain substantive wiring or act as a service\nlocator.\n\n## Process boundaries\n\nArchie begins as a modular monolith even when capabilities run in separate\nprocesses. A domain becomes a separately deployed service only for a concrete\nneed such as security isolation, independent scaling, failure containment, or\nindependent operation.\n\nPossible future extraction does not justify premature network protocols or\nduplicated service scaffolding.\n\nA new command is not a reason for a new binary. `cmd/` entries are process\nboundaries: a binary earns its place when its surface fails independently of the\nfleet, or when one process may need to run in more than one location, such as a\nhigh-availability pair or across a NAT boundary. Operational commands over a\nsurface an existing binary already owns are subcommands of that binary. Offline\ndatabase maintenance belongs to `archie-state-store`, which owns the file and\nits path layout, not to a new recovery binary.\n\n## Optional and operational material\n\n- `extras/\u003cextension\u003e` contains a maintained optional extension with real\n behaviour. Core Archie MUST NOT import it, and removing `extras/` MUST NOT\n prevent the core application from building or running.\n- `deployments/\u003cassembly\u003e` contains a supported assembly, including deployment\n definitions and concise operational instructions.\n- `docs/guides/` contains handwritten explanation and links to generated\n reference material.\n- `examples/` contains copyable samples with explicit purpose, prerequisites,\n and support expectations.\n\nSupported assemblies SHOULD demonstrate that capabilities can be selected\nindependently.\n"
},
{
"url": "/dev/architecture/package-review/",
"title": "Domain and Feature Review Procedure",
"section": "Architecture",
"body": "# Domain and Feature Review Procedure\n\n**Status:** Active \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchitecture work proceeds one domain or feature at a time. Before any design\nquestion, the selected area is researched across its complete live\nimplementation, consumers, tests, state, configuration, and runtime wiring.\n\nExisting packages are evidence, not the unit that drives the interview.\nPlacement follows behaviour and ownership, not the existing directory name.\n\nNo restructuring implementation begins until the relevant package decisions\nare agreed and recorded in the focused domain or requirement document.\n\n## Required research\n\nBefore design questions, the current-state report MUST identify:\n\n- entry points and runtime composition;\n- state, persistence, and lifecycle;\n- public and internal contracts;\n- commands, events, and policy enforcement;\n- configuration and defaults;\n- all consumers and cross-domain interactions;\n- process and infrastructure boundaries;\n- tests, failure behaviour, and known invariants;\n- duplicated or conflicting implementations;\n- documentation that disagrees with live code.\n\nDiscoverable facts MUST be investigated rather than presented to the user as\ndesign questions.\n\n## Required decisions\n\nEach package review records:\n\n| Decision | Required result |\n| --------------------- | ---------------------------------------------------------------- |\n| Owned behaviour | The cohesive job the code performs |\n| Domain ownership | The owner of the behaviour and vocabulary |\n| Final location | Its target path |\n| Public contracts | The smallest interfaces, commands, and events exposed |\n| Required services | Domain-defined interfaces implemented by infrastructure |\n| State ownership | The owner of each mutable record and transition |\n| Dependencies | Allowed imports and dependencies to remove |\n| Duplication | Code to consolidate, delete, or keep separate |\n| Plugin status | Core domain, shared contract, infrastructure, plugin, or extra |\n| Process boundary | In-process, or the concrete reason for isolation |\n| Configuration | Settings owned by the domain or plugin |\n| Policy | Definitions, evaluators, consequences, and shared mechanics used |\n| Documentation | Authoritative definitions and generated reference |\n| Migration constraints | Behaviour and data that must remain correct |\n\n## Interview method\n\nFor every selected domain or feature:\n\n1. Declare the single area under review.\n2. Complete the current-state research.\n3. Explain actual behaviour in plain technical language.\n4. Separate facts from design decisions and concerns.\n5. Resolve obvious consequences directly and ask only questions whose answer\n materially changes behaviour or structure.\n6. Record each confirmed decision in its focused document.\n7. Complete that area's handoff before selecting another.\n8. Keep unrelated domains outside the implementation scope.\n"
},
{
"url": "/dev/architecture/plugins-and-extensions/",
"title": "Plugins and Extensions",
"section": "Architecture",
"body": "# Plugins and Extensions\n\n**Status:** Approved foundation \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Plugin framework\n\nThe core plugin domain lives under `internal/domain/plugin`. It owns:\n\n- plugin identity and metadata;\n- discovery and registration contracts;\n- lifecycle rules;\n- capability registration;\n- validation and compatibility rules.\n\nThe generic plugin contract remains metadata-only. Functionality is exposed\nthrough narrow typed capability contracts with an owning registry or manager.\n\nWorkflow plugins belong to the Workflow capability family. The Workflow domain\nat `internal/domain/workflow` owns their typed registration, validation,\nversioning, definition, and execution contracts. The generic plugin domain may\nprovide plugin identity, discovery, compatibility, and lifecycle mechanics, but\nit MUST NOT define Workflow semantics or expose untyped Workflow hooks.\n\n## Plugin engine rule (strict)\n\n“Engine” is reserved for a typed, lifecycle-managed capability family. It is not\na synonym for a generic plugin hook. Every new plugin engine must satisfy all of\nthese invariants:\n\n1. **Typed domain contract.** The engine interface exposes real\n capability-specific operations in addition to identity metadata. Examples are\n resolving a secret, delivering a message, or running an agent. A plugin that\n only exposes `Name` and `Version` is metadata, not an engine.\n2. **Owning family manager.** The capability package owns a `Registry` or\n `Manager` that controls provider registration and discovery, initialisation,\n or access. Providers do not register arbitrary callbacks directly on the\n daemon.\n3. **Lifecycle and health.** When an implementation owns resources or background\n work, its typed family contract must expose start, health, and stop\n semantics. The owning manager invokes them and defines failure isolation and\n shutdown ordering. Stateless providers may make these operations explicit\n no-ops.\n4. **Narrow host access.** Plugins receive the typed family registrar and only\n the host services their declared capability requires. They never receive\n `*daemon.Daemon`, a service locator, or an untyped hook map.\n5. **Metadata-only generic plugin contract.** `plugin.Plugin` remains limited to\n `Name()` and `Version()`. Domain hooks belong on typed engine interfaces;\n adding capability methods to the generic interface is forbidden.\n6. **Trust boundary stays explicit.** Explicitly trusted, operator-installed\n plugins—including third-party secret-engine plugins the operator chooses to\n trust—may run in-process and have daemon privileges. Repository-supplied code\n runs in the task container. Integrations that are not trusted as daemon code\n run out of process through MCP or a versioned protocol and, when a\n confidentiality or integrity boundary is required, inside a real container\n sandbox. A subprocess boundary alone is not a security sandbox, and calling\n Yaegi-loaded code a plugin does not isolate it.\n\n`internal/plugin/architecture_test.go` enforces the mechanically testable parts\nof this rule: the generic plugin method set, the shared agent-instruction\nsource, and the requirement that engine interfaces have domain behaviour plus an\nowning registry or manager.\n\n### Memory engine family\n\nOne engine, addressed by four typed scopes -- `ScopeGlobal`, `ScopeAgent`,\n`ScopeUser`, `ScopeAgentUser` (`internal/domain/memory`, `Scope`/`ScopeKind`).\nA caller names exactly the scopes it may read or write; the engine applies no\naccess policy of its own, so isolation falls out mechanically because\n`ScopeAgent{a}` and `ScopeAgent{b}` are different storage keys. See\n`docs/prds/memory-engine-unification.md` for the decision this contract\nimplements; it superseded `internal/memory` (`MemoryProvider`/`Manager`),\ndeleted in that PRD's slice 5.\n\n`MemoryEngine` (`internal/domain/memory/contract.go`) is the typed family\ncontract: `Create`, `Get`, `Query`, `List`, `Update`, `Forget`, `Revisions` --\nCRUD with revisions retained, not just create/read/delete. `Update` supersedes\nrather than overwrites: the superseded state is appended to the scope's\n`HISTORY.md` before the live block is replaced, and `Update` carries no\n`Scope` field, so a record can never change scope. The family's content\nscanner (prompt-injection / sensitive-data patterns) is applied inside\n`Create` and `Update`, the single choke point every producer crosses.\n\n`internal/domain/memory.Registry` is the owning family registry: registration,\nstart/health/stop, shutdown ordering, and failure isolation, following the\nplugin engine rule above. `internal/infrastructure/memory.NewBuiltinEngine` is\nthe only registered engine today; it persists through\n`internal/infrastructure/memory/builtin`, a markdown store (`MEMORY.md`-shaped\nper-scope files) that owns its on-dLine truncated
},
{
"url": "/dev/architecture/policy/",
"title": "Policy System",
"section": "Architecture",
"body": "# Policy System\n\n**Status:** Approved foundation; exact API is deferred \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nRetry limits, authorisation, gates, commands, protected paths, tool\navailability, and similar rules define or constrain what Archie may do. They\nneed consistent consumption, composition, evidence, and audit without erasing\ntheir different domain meanings.\n\n## Ownership\n\n`internal/policy` is an explicitly approved shared application contract. It is\nnot infrastructure and it is not a generic domain that owns every rule.\n\nThe shared policy system owns:\n\n- policy identity, version, scope, and applicability;\n- typed evaluation invocation;\n- deterministic composition and precedence;\n- common evaluation states such as satisfied, violated, indeterminate, and not\n applicable;\n- reasons and evidence;\n- evaluation audit records;\n- registration, discovery, and lifecycle.\n\nEach consuming domain owns:\n\n- its policy vocabulary and typed inputs;\n- its concrete policy definitions;\n- its evaluators;\n- the meaning and consequence of an evaluation.\n\nAccess therefore owns principals, resources, actions, and authorisation\nconsequences. Task lifecycle owns retry eligibility and exhaustion. Task\nexecution owns gate requirements. Workspace mutation owns protected-path\neffects. Tool execution owns tool and command constraints.\n\nThese policies use consistent evaluation mechanics without pretending their\ndecisions are semantically interchangeable.\n\n## Infrastructure\n\nInfrastructure MAY load, persist, distribute, and audit external policy\nrepresentations. It MUST NOT define what Archie allows or assign the meaning of\na domain policy result.\n\nThe exact Go API, composition operators, precedence rules, and representation\nformat require a focused policy design pass.\n"
},
{
"url": "/dev/architecture/safe-change-and-recovery/",
"title": "Safe Change and Recovery",
"section": "Architecture",
"body": "# Safe Change and Recovery\n\n**Status:** Requirements approved; mechanics are under design. Database-backed settings are implemented through the control plane (2026-09): see the degrade/recovery section below, which records a gap rather than a solution. The full runtime-supervision protocol (bounded observation, versioned audit trail) remains under design.\n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is built and improved by agents as well as humans. The architecture MUST\nmake a change easy to locate, understand, test, audit, extend, and reverse\nwithout requiring its author to understand unrelated parts of the application.\n\nSeparation of concerns is therefore an operational safety boundary, not only a\ncode-organisation preference.\n\n## Required outcomes\n\n- An agent can improve a focused feature without receiving authority over\n unrelated domains.\n- Every event, function, action, setting, and policy has an identifiable owner\n and provenance.\n- Source and runtime changes pass deterministic checks outside the actor making\n the change.\n- A rejected or unhealthy candidate cannot replace the last known working\n version.\n- Invalid user configuration does not terminate an otherwise healthy\n application.\n- Configuration and service failures are observable, attributed, and eligible\n for bounded remediation or rollback.\n- The application continues serving unaffected capabilities when one\n capability is misconfigured or unhealthy.\n- Recovery failure is reported and contained rather than hidden in an\n unbounded retry loop.\n\n## Source changes\n\nAgent-authored source changes occur through the task-execution boundary in an\nisolated workspace. The agent does not directly mutate the running\ninstallation.\n\nPromotion is controlled by deterministic repository-owned policy, including\ntests, generated-reference drift checks, protected paths, change scope, and\nother required gates. The actor proposing a change cannot waive these checks.\n\nRepository and domain separation SHOULD allow a task to load and modify only\nthe governing requirements and code for its declared scope.\n\n## Runtime changes\n\nConfiguration and other runtime changes are proposed as candidates rather than\nmutating the active state in place.\n\nThe affected domain owns:\n\n- the command describing the semantic change;\n- validation of its typed settings;\n- health signals that demonstrate correct operation;\n- domain-specific remediation and rollback consequences.\n\nShared policy supplies consistent evaluation, evidence, and audit mechanics.\nIdentity supplies actor attribution. Infrastructure supplies external\nconfiguration storage, service control, and other operational adapters.\n\n## Runtime change protocol\n\nLast-known-good preservation and candidate promotion are the universal runtime\nchange protocol.\n\n1. An identity proposes an immutable candidate version.\n2. Infrastructure parses it without changing active state.\n3. Each affected domain validates its typed settings.\n4. Shared policy evaluates cross-cutting constraints.\n5. Each affected capability prepares the candidate without destroying its\n active instance.\n6. Capability-specific health checks prove the candidate works.\n7. Runtime supervision atomically promotes the candidate.\n8. A bounded observation period watches for delayed failure.\n9. Failure restores the last-known-good version and records the reason,\n evidence, actor, and involved versions.\n10. Repeated remediation failure stops retrying, isolates the capability, and\n reports the fault.\n\nThe affected domain owns the semantic change command, typed validation, health\nsignals, and remediation consequences. Shared runtime supervision owns the\npromotion transaction. Infrastructure performs storage and service-control\noperations.\n\nThe protocol's exact Go contracts, storage model, atomicity boundary, and\nobservation rules require a focused runtime-supervision design pass.\n\n## Failure isolation\n\nInvalid input MUST leave the active valid configuration unchanged and produce a\ndiagnostic record.\n\nA capability that cannot start or reload SHOULD fail independently where its\nabsence does not violate a declared application invariant. Unaffected\ncapabilities continue operating.\n\nRemediation MUST be bounded, observable, and policy-driven. Recovery MUST NOT\nsilently oscillate between versions or retry forever.\n\n## Database settings: degrade paths and recovery (2026-09)\n\nThe control plane owns runtime-tunable settings and stores them in the State\nStore's PostgreSQL database.\nThis replaced a dashboard overlay store that degraded to file config on any\nfailure and had three documented ways back. The replacement has none, and the\nposture is the opposite: **the daemon fails closed.**\n\n### Degrade paths\n\n| Failure Line truncated
},
{
"url": "/dev/development/",
"title": "Development guides",
"section": "Development",
"body": "# Development guides\n\nChecklists for changing Archie, one page per area. Each names every place a\nchange must reach, so a feature that works in one layer does not silently stop\nat the next. A change that spans areas starts on the page for the area it\nbegins in, which points to the others. The pages point at the documents that\nown the design (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than\nrestating them.\n\n| Area | Covers |\n| ---------------------------------------------- | -------------------------------------------------------------------------------- |\n| [Frontend UI](/dev/development/frontend-ui/) | Anything under `ui/`, and the dashboard's API routes |\n| [Agent](/dev/development/agent/) | The agent container, its image, profiles, tools and workspace |\n| [Workflows](/dev/development/workflows/) | Workflow definitions and step types |\n| [Daemon](/dev/development/daemon/) | Task statuses, fields and the brief; sources, event types, mappings and bindings |\n| [State Store](/dev/development/state-store/) | Stored fields, tables, RPCs and errors |\n| [Control plane and settings](/dev/development/control-plane/) | Settings in `config.toml` or the dashboard |\n| [Processes and wiring](/dev/development/wiring/) | Where code goes, processes, plugin engines, channels, NATS subjects |\n| [Merging work](/dev/development/merging-work/) | Merging a lane or a branch |\n\n## Every change\n\n- Write the failing test first for anything with logic, branching or a\n contract, and check it fails on an assertion, not a compile error.\n- Test through the path production uses. A test that sets a value directly on\n the consumer proves nothing about the layers that normally deliver it.\n- Run `task check` and let its exit status decide the commit:\n `task check \u0026\u0026 git commit ...`. `task test` passes `-short`, which skips the\n process and Postgres tests, so run `go test -count=1 ./cmd/... ./internal/...`\n too when a change crosses a process or the database.\n- Regenerate, never hand-edit, generated output: `task proto:generate`,\n `go -C tools tool sqlc generate -f $PWD/internal/infrastructure/postgres/sqlc.yaml`,\n `task ui`, `task docs:artifact`. `task proto:check` compares against the git\n index, so stage regenerated contracts before running it.\n- Stage by path, or read `git status` before `git add -A`. Tests that start\n embedded NATS or write logs must use `t.TempDir()`; anything they leave in the\n tree gets committed. `task check` writes no module file on a consistent tree,\n root or `tools/` (verified at HEAD with `GOFLAGS` unset and with `-mod=mod`):\n a stale `go.mod` or `go.sum` fails it, with `missing go.sum entry` or\n `updates to go.mod needed`, rather than being repaired. Only a global\n `GOFLAGS=-mod=mod` in `go env` re-enables that repair, which is why the\n `go -C tools` steps pass `-mod=readonly`; if `go.sum` goes dirty, run\n `go mod tidy` and commit the result on its own.\n- A change to `docs/prds/`, `docs/architecture/` **or `docs/development/`**\n carries the regenerated `docs/data/generated/dev-docs.json`: run\n `task docs:artifact` (not `task docs:check`, which checks contracts only).\n PRD edits also follow `docs/prds/RULES.md` and pass `task docs:prds`.\n"
},
{
"url": "/dev/development/agent/",
"title": "Agent",
"section": "Development",
"body": "# Agent\n\nAuthority: `docs/architecture/agent-system.md` (execution boundary, the model\nnever runs git) and the Deployment Model section of `CLAUDE.md`.\n\nThe daemon prepares a workspace, starts one container per task from a profile's\nimage, and hands the whole task to `archie-agent` over NATS in one\n`taskrun.Request`. The agent reaches the State Store, forge and worktree push\nonly through the daemon's RPC servers, using task-scoped credentials.\n\n## Giving the agent something new\n\n- **Data about the task** goes in `taskrun.Request` or the task brief\n (`container.TaskPayload`), never in an environment variable. Add a test that\n the request carries it (`TestRunViaAgentSendsMCPServers` is the pattern).\n- **A credential** is scoped to the task and revoked when it ends, like the\n State Store grant and the worktree publication grant. The daemon's own\n administrative token never enters a container.\n- **A tool** reaches the agent through the central registry, MCP, a repository\n script or a skill plugin. A profile's `tools` list filters those; ai-sdk\n agentloop's built-in file tools are outside it. A tool that must stay inside\n the workspace uses the agent loop's confinement, not its own path handling.\n\n## Changing the agent image or a profile image\n\n1. The agent image is `Dockerfile`; example profile images live in\n `examples/profiles/`, each with a build-only service in\n `docker-compose.yml` (`profiles: [\"build\"]`, so `up -d` never starts it).\n2. Anything the agent runs must be in the image. The container gets no\n package manager at run time beyond what the image ships.\n3. A locally built image needs `containers.pull_policy = \"missing\"`;\n `\"always\"` tries to pull it and fails.\n4. Profiles are configured under `[containers.profiles.\u003cname\u003e]` and resolved\n by the daemon before the container starts (`pinTaskProfile`). An unknown\n profile parks the task; it never falls back to the default image.\n\n## Changing how a task runs\n\n- Workspace preparation happens in the daemon (`prepareWorkspace`) before the\n container starts, because the container binds the directory. Clones need the\n daemon's forge credential; the agent never clones.\n- A task with no repository gets `worktree.Manager.ScratchDir`, which is\n removed when the task ends.\n- The agent runs as root in the container. Anything it writes into the\n bind-mounted workspace is handed back to the daemon's UID\n (`restoreWorktreeOwnership`); a new write path must stay inside that\n workspace.\n- NATS rules are in `CLAUDE.md`: task responses use `msg.Respond`, a responder\n is flushed after it registers, and `ARCHIE_TASKS` is a work queue.\n"
},
{
"url": "/dev/development/control-plane/",
"title": "Control plane and settings",
"section": "Development",
"body": "# Control plane and settings\n\nAuthority: `docs/architecture/configuration.md`. The wiring matrix, the\ndecoded-but-unwired ledger and the three shapes an unwired field takes are in\n`.agents/skills/archie-config-and-flags`.\n\nA field that parses is not a field that works. Before adding one, name the code\nthat reads it and the path the value takes to get there.\n\n## Decide what kind of setting it is\n\n- **Bootstrap-only** (read once at process start: `database_url`, `state_dir`,\n `work_dir`). It stays in the file, is checked by `validateBootstrap` in\n `internal/infrastructure/configuration/validate.go`, and the runtime overlay\n refuses changes to it.\n- **Database-owned** (repository policies, scheduling, tools, plugins,\n channels, containers). The file only seeds it. Once the State Store holds the\n control-plane resource, the stored document is layered over the file\n (`controlplane.Client.RuntimeConfig`) and the file key stops mattering. It is\n checked by `validateDatabaseOwned` and by the resource's validator. A stored\n value is refreshed from the file only when the store has no value for the kind\n at all; a kind that ships a document of its own (workflow definitions,\n personas) is refreshed whenever the seed itself wrote the stored copy, since\n that copy is a previous release's document rather than an operator's\n (`controlplane.Server.seedKind`).\n- **Worker-carried.** A value the agent container needs travels in\n `config.TaskConfig` (`Config.ForTask`) or on `taskrun.Request`. Never pass it\n as an environment variable the daemon did not already define, and never carry\n a secret this way.\n\n## Adding a database-owned field\n\n1. Add it to the wire-shape type the resource's `Document` names — a dedicated\n struct in `internal/app/controlplane/` with explicit snake_case json tags\n (`channel_settings.go`, `tool_settings.go`, `container_settings.go` are the\n precedents), never the internal config struct itself. A struct fed straight\n into the document falls back to Go field names (`Window`, `MaxRequests`),\n and a bare `time.Duration` marshals as nanoseconds — both render unusable\n in the Web UI. The resource's JSON schema and the dashboard's Advanced\n settings editor are generated from that type, so no UI work is needed for\n the editor itself.\n2. Map to and from the internal config type at the resource boundary (`Seed`,\n the layering in `runtime_config.go`, and the validator all use the same\n mapping). Durations in the document are a string-marshalling type\n (`config.Duration` or a document-local one), never a bare `time.Duration`.\n3. A document stored before the shape existed carries Go-cased keys. Read them\n with `controlplanerpc.DecodeRenamingLegacyKeys` (an `UnmarshalJSON` on the\n wire type) while keeping `DisallowUnknownFields` — dropping unknown keys\n would decode a misspelling as \"unset\" — and register a `Normalize` on the\n `Definition` that re-encodes the document, so a legacy document converges\n the next time it is written. A map or a nested struct needs its layering\n checked: a stored map replaces the file's, not merges into it, and a field\n the stored document omits keeps the file's value. Add a case to\n `internal/app/controlplane/runtime_config_test.go` for both.\n4. Validate it in one function both sides call, and add a case to\n `TestResourceValidatorsRejectWhatEffectiveValidationRejects` in\n `validators_agree_test.go`, so the file and the resource cannot disagree.\n5. Decide whether it reloads: it does only if every consumer re-reads it from\n `config.Holder`. The allowlist is `internal/app/archied/reload.go`; anything\n not on it requires a restart.\n6. If the settings page shows it as a plain field, add it to\n `internal/webui/config_schema.go` and the view in `api_config.go`.\n7. A generic catalog resource (`replace` command, not domain-managed, no\n query service) is watched **once per archie-ui process** by `webui.RunLive`,\n then published to every browser through `/api/stream`. Do not add an\n EventSource per resource to a settings store or a gRPC Watch per HTTP client.\n The control-plane server polls `Resource` every 250ms per upstream Watch;\n verify watch count is independent of client count and that late clients get\n the hub's current value (`internal/webui/live_hub_test.go`, real server over\n bufconn). Reopens resume after the last delivered version and charge failed\n attempts; accepting a gRPC stream does not establish its health.\n\n## Every new field\n\n- Test through the layering: build the effective config the way boot does,\n not by setting the field on the consumer.\n- Add a commented example to `config.example.toml`. Touch `deployments/*.toml`\n only when a profile there needs a value different from the default.\n- Update the wiring matrix in `.agents/skills/archie-config-and-flags`.\n- Secrets are `SecretRef`s resolved throLine truncated
},
{
"url": "/dev/development/daemon/",
"title": "Daemon",
"section": "Development",
"body": "# Daemon\n\nThe daemon claims and runs tasks, and turns captured events into tasks through\nbindings. This page covers both.\n\n## Task lifecycle\n\nAuthority: `docs/architecture/agent-system.md`. The status vocabulary lives in\n`internal/taskstate`, which imports no internal package.\n\n### Adding a status\n\n1. Add the constant to `internal/taskstate/taskstate.go` and place it in\n `Terminal`, `Actions` and `Statuses`. Its value is stored, so renaming it\n later is a migration.\n2. Alias it in `internal/domain/workflow/task/task.go` and\n `internal/domain/workflow/task_aliases.go`.\n3. Add it to the default catalogue in `ui/src/lib/task-meta.ts`. The server\n catalogue replaces the defaults when it loads, but the defaults render first.\n4. Find every hand-written status list in SQL:\n `grep -rn \"'merged'\" internal/infrastructure/postgres/queries`.\n `ClearTerminalTasks` must match `taskstate.Terminal`, which\n `TestClearTerminalTasksMatchesTaskstate` enforces. The stats queries count\n outcomes by name; decide whether the new status counts.\n5. Extend the table in `taskstate_test.go`.\n\n### Adding a task field\n\nFollow [State Store](/dev/development/state-store/) for the\ncolumn and the wire. Then decide who writes it: `UpdateTask` writes a fixed\ncolumn set, so a field set at enqueue belongs in the insert that creates the\nrow (as `InsertChatTask` does for inputs), or in its own statement when only\nsome producers set it (as `StampTaskBinding` does for binding provenance).\n\n### Changing what the agent receives\n\n- The task brief is `container.TaskPayload`, written to\n `\u003cworkspace\u003e/.git/task.json` by `WriteTaskJSON`. Never write it to the\n workspace root: the commit stage stages everything there.\n- The run request is `taskrun.Request`. `Validate` rejects a request that\n cannot run; a new requirement goes there.\n- Parking always carries a class (`taskstate.ParkTransient`,\n `ParkNeedsHuman`, `ParkTerminal`) chosen by the code that parks. Pick the one\n that says what an operator must do.\n- A task with no repository (`Task.HasRepository`) runs in a scratch workspace\n with no worktree grant. Code that assumes an owner and repo must check first.\n\n## Event automation\n\nAuthority: `docs/prds/event-automation.md` (the model: source, event type,\nmapping, binding, workflow, profile) and `docs/architecture/bindings.md`\n(threat model).\n\n### Where each check lives\n\nA binding is checked twice, and a new rule usually belongs in both places:\n\n- **On save**, in `checkedBinding` (`internal/webui/api_binding.go`), so the\n operator sees the problem while editing. It calls the domain checks\n `binding.Validate`, `binding.CompileFilter` and `Binding.CheckWorkflow`.\n- **At dispatch**, in `dispatchOneBinding` and `resolveBindingTarget`\n (`internal/daemon`), because the workflow or mapping may have changed since\n the save. A refusal is recorded with `recordDispatchFailure` and starts no\n task.\n\nPut the rule itself in `internal/domain/binding` or\n`internal/domain/workflow/task` and call it from both, rather than writing it\ntwice.\n\n### Adding a binding field\n\n1. Domain type and `Validate` in `internal/domain/binding`.\n2. Column, queries, store mapping, wire field, `newColumns`\n ([State Store](/dev/development/state-store/)).\n3. The request type and `checkedBinding` in `api_binding.go`.\n4. The draft, payload and editor in `ui/src/bindings/`\n ([Frontend UI](/dev/development/frontend-ui/)).\n5. Its effect at dispatch, with a case in\n `internal/daemon/dispatch_inputs_test.go` or `dispatch_bindings_test.go`.\n\n### Rules that must hold\n\n- Signing belongs to the source. Intake verifies the HMAC against the source's\n secret before the payload is parsed.\n- An event must be identified as an event type before anything dispatches it,\n and a binding applies only to its mapping's event type. Dispatch test\n fixtures therefore create an event type before inserting captures.\n- The dispatch ledger is claimed before the task is enqueued (at most once).\n- Anything an event supplies that selects what the agent acts on, such as a\n repository, must be checked against configuration. An event never widens\n what an agent can reach.\n"
},
{
"url": "/dev/development/frontend-ui/",
"title": "Frontend UI",
"section": "Development",
"body": "# Frontend UI\n\nAuthority: `.agents/skills/archie-web-ui` (stack facts, design-system rules,\ntone and accessibility). This page covers what a change must reach, not how it\nshould look.\n\n## Adding or changing a feature\n\n1. The feature lives in `ui/src/\u003cfeature\u003e/`. Move a helper to `ui/src/base/`\n only when a second feature needs it.\n2. Keep wire shapes, draft state and payload building in a plain `.ts` module\n beside the components (`ui/src/bindings/binding-draft.ts` is the pattern),\n and test it in `ui/test/*.test.ts`. Components stay thin.\n3. Every mutation goes through `api.*` in `ui/src/lib/api`, which sends the\n CSRF and Content-Type headers the server's mutation guard requires. A bare\n `fetch` is refused.\n4. A value the server also describes (task statuses, actions, workflow inputs)\n comes from the server. Keep a local default only so the first render works,\n and keep it in step (`ui/src/lib/task-meta.ts`).\n5. Run `task ui`, `task test:ui` and `cd ui \u0026\u0026 npm run typecheck`. Commit the\n regenerated `ui/dist/`; the Go binaries embed it. A fresh git worktree has\n no ignored `ui/node_modules`: run `cd ui \u0026\u0026 npm ci` before these commands.\n6. **One long-lived browser connection:** `ui/src/lib/api.ts` has the only\n `new EventSource`, owned by `stores/live-updates.ts`. Feature stores consume\n topics with `live.subscribe(topic, callback)`; do not open a page-owned SSE\n stream. Logs alone opt in while mounted, replacing that same EventSource\n with `?topics=logs\u0026since=\u003clast cursor\u003e`; a browser's `Last-Event-ID` only\n survives its own automatic reconnect, not a newly constructed EventSource.\n Task and log topics resume by cursor; control-plane, identity and apply-status\n topics replay the latest snapshot. Test a fetch and same-origin navigation\n after visiting Settings and Logs: the UI process serves HTTP/1.1 and six\n persistent streams can starve every later browser request.\n\n## Testing the dashboard\n\nAuthority: the runner itself is `ui/package.json`'s `test` script: `node --test\n--experimental-strip-types test/*.test.ts` over `ui/test/*.test.ts`. It runs\npure TypeScript modules with `node`'s type stripping — no SFC loader, no DOM,\nno second dependency beyond what the app already carries. That is the standard,\nand a decision record for when it is deliberately not enough:\n\n- **Test archie's logic in a module; leave SFC wiring alone.** Wire shapes,\n draft state, copy conditions, filters and payload building live in plain\n `.ts` files beside the components and are tested in `ui/test/`. Components\n stay thin, so there is normally nothing in an SFC that is archie logic.\n- **A dashboard rule that mirrors a server rule is pinned by a shared\n fixture, not two independent tests.** `ui/src/settings/validation.ts`\n hand-mirrors three control-plane validators, and the model-role rule had\n already drifted because nothing tied the two sides together. Each case now\n lives once in `internal/app/controlplane/testdata/dashboard-validators.json`:\n a Go test in that package runs the real server validators over it, and\n `ui/test/control-plane-validator-parity.test.ts` runs the real dashboard\n validators over the same cases. Changing one rule alone fails the other\n side's test. Add a case to the fixture, never to one side only.\n- **Installed primitives are upstream-tested, not re-tested here.**\n `reka-ui` (2.10.5 here) maintains colocated tests per component in its own\n repo (Vitest/jsdom + axe: Switch, TagsInput, NumberField, Select, the\n arrow-navigation composables). The npm package ships none of those files, so\n this coverage is inherited through the version bound, not the tarball —\n `grep -l test node_modules/reka-ui` finds nothing. Duplicating them as local\n mount tests would test a dependency.\n- **A `.vue` import cannot run under the module runner.** `node --test` fails\n such a module with `ERR_UNKNOWN_FILE_EXTENSION: .vue` and the runner has no\n built-in loader for SFCs. A file under `ui/test/` that imports a `.vue` is\n therefore a broken test, not a weak one.\n- **If a DOM mount harness is ever needed** (a page-level accessibility\n contract, cross-component interaction, focus behaviour): `happy-dom` +\n `@vue/test-utils` + `vitest` scoped to a separate DOM test glob, keeping the\n module runner for everything else. Measured on the ui tree (vitest 5.0.2,\n happy-dom 20.14.5, @vue/test-utils 2.5.1): they add 24 top-level\n `node_modules` entries and 27 MB on a 296 MB install, a working 2-test mount\n suite (role=radiogroup vs role=switch, aria-label, click activation against\n the real SFCs) runs in 1.2 s on top of the current 0.5 s module suite, and\n `vue-tsc` (7.4 s) dominates `task test:ui` either way. The single-runner\n alternative (absorbing the existing suite into vitest) was measured\n infeasible as-is: all 29 existing files impLine truncated
},
{
"url": "/dev/development/merging-work/",
"title": "Merging work",
"section": "Development",
"body": "# Merging work\n\nParallel lanes (see `.agents/skills/archie-agent-fleet`) merge into an\nintegration branch before `main`. Each merge is a change in its own right and\npasses the same gate.\n\n## Resolving conflicts\n\n- **Generated files** (`*.pb.go`, `postgresdb/*.go`, `ui/dist/`,\n `docs/data/generated/*.json`): take either side, then regenerate. Never merge\n them by hand.\n- **One side deletes a file, the other edits it**: the deletion wins when the\n deleting lane replaced the thing the file served. Move the other side's\n change onto its replacement.\n- **One side changes how code is built (a new store, renamed packages), the\n other what it does**: take the behaviour side's version and reapply the\n mechanical change to it. That is usually cleaner than merging line by line.\n- **Error sentinels** are rows in `wireErrors`, not switch cases.\n\n## After resolving\n\n1. Search for leftovers of anything the other side removed: the old package\n path, the old type, and comments describing the old behaviour.\n2. Tests written against one side's semantics may pass there and fail after\n the merge. A test that used to pass on the old store may be asserting a rule\n the other side deliberately changed. Fix the test's setup to the merged\n rule; do not loosen the rule to the test.\n3. Run the full suite without `-short`, then `task check`, then commit. Check\n `git status` for files a test wrote into the tree before staging.\n4. **A merge can surface a bug neither lane's own tests exposed alone.** Two\n real cases from 2026-09-26: a test that dialled no NATS URL passed on a\n machine with an ambient dev server running and failed the moment it landed\n on a clean CI runner (start an ephemeral server per test, never rely on a\n default port resolving to something); and a cycle-detector that walked a\n Go map in range order reported the same cycle two different ways from run\n to run, invisible until enough fresh (uncached) runs hit the unlucky\n ordering. Both looked like \"the merge broke a passing test\" but were\n latent defects the merge only had the opportunity to expose. Fix the\n defect the failure is pointing at, not the assertion that caught it — see\n CLAUDE.md's test-quality bar before writing the replacement.\n5. `go test`'s cache reuses a package's last result when nothing in its\n dependency graph changed. A merge that touches one package can leave a\n sibling's flaky test silently cached \"pass\" locally while CI runs it\n fresh. `task check` passing on your machine is not proof a merge is\n clean — rerun anything nondeterminism-prone with `-count=1` before\n trusting it, and let CI's from-scratch run be the tiebreaker it is.\n"
},
{
"url": "/dev/development/state-store/",
"title": "State Store",
"section": "Development",
"body": "# State Store\n\nAuthority: `docs/prds/state-store-contract.md` and the State Store section of\n`CLAUDE.md`. All persistence is PostgreSQL behind the standalone State Store\nprocess; nothing else opens the database.\n\n## Adding a column\n\n1. Write the next migration in `internal/infrastructure/postgres/migrations/`\n (`00NN_name.sql`, goose Up and Down). Give the column a `NOT NULL DEFAULT`\n that is correct for existing rows.\n2. Update the queries in `internal/infrastructure/postgres/queries/` and\n regenerate with sqlc. A query that lists columns (`ListTaskSummaries`, the\n binding selects) does not pick the new one up; `SELECT *` queries do.\n3. Map it in the store (`taskFromRow`, `bindingValue` and friends). If the\n column holds encoded data, the package that owns the type owns the encoding\n (`task.EncodeInputs`), and the store and the wire both use it.\n4. Carry it over the wire (next section) if any process other than the State\n Store reads it.\n\n## Adding a field to a wire message\n\n1. Add it to `proto/state/v1/state.proto` with a new field number. Never reuse\n a number; retire one with `deprecated = true`.\n2. `task proto:generate`, then map it both ways in\n `internal/infrastructure/staterpc/values.go`.\n3. `TestTaskProtoCarriesEveryDomainField` fills every `task.Task` field and\n fails on one the mapping forgets. If it cannot fill the field's kind, extend\n it. Other messages have no such test, so add a round trip to\n `conformance_test.go`.\n\n## Adding an RPC or a store method\n\n1. Put the Go method on the narrow consumer interface in\n `internal/domain/storecontract` (keep each at eight methods or fewer) and add\n the matching RPC. A Go method without an RPC does not cross the process.\n2. Implement it in the Postgres store, in `staterpc.Client` (with its `var _`\n assertion) and in `staterpc.server`. A missing dependency answers\n `codes.Unavailable`, never a fabricated default.\n3. Wire the dependency in every composition that serves or consumes it:\n `stateStoreDeps` in `internal/app/archied/state_store.go`, the daemon's\n assertions in `bootstrap.go`, and `internal/app/archieui/compose.go` for the\n dashboard process.\n4. Task-scoped tokens may call only `Update`, `Transition` and `InsertEvent` on\n their own task (`staterpc.TaskGrants`). A new RPC is admin-only unless it is\n added there deliberately.\n5. Add it to `conformance_test.go`, which runs every surface over a real gRPC\n connection.\n\n## Adding an error sentinel\n\nAdd the sentinel to `storecontract`, a row to `wireErrors` in `values.go`, and\na case to `error_test.go`. The canonical message is part of the wire contract:\nchanging it breaks `errors.Is` on the client silently.\n\n## Harness OAuth secrets\n\n`HarnessSecretStore` stores token sets by org and credential service through\nadmin-only State Store RPCs. The EDA store seals them with the binding cipher's\nkeyring and a separate `HarnessSecretDomain`. OAuth writes require a configured\nbinding encryption key; the legacy binding plaintext fallback does not apply.\nThe daemon's egress proxy (`internal/infrastructure/egress/oauth.go`) is the\nonly daemon consumer: for a run granted the service it swaps sentinels for the\nstored tokens and writes every refresh back. The setup terminal is a separate\nharness slice.\n"
},
{
"url": "/dev/development/wiring/",
"title": "Processes and wiring",
"section": "Development",
"body": "# Processes and wiring\n\nAuthority: `docs/architecture/organisation.md` (layers, process boundaries),\n`docs/architecture/dependencies-and-contracts.md` (dependency direction, wire\ncontracts) and `docs/architecture/plugins-and-extensions.md` (the plugin engine\nrule).\n\n## Placing new code\n\n- Domain logic, entities and the interfaces it needs go in\n `internal/domain/\u003carea\u003e/`, which imports no infrastructure or app package.\n- Implementations of those interfaces go in `internal/infrastructure/\u003cservice\u003e/`.\n- Construction and wiring go in `internal/app/\u003capplication\u003e/`; `cmd/` only\n parses flags and calls it.\n- `logging`, `events`, `eventbus`, `policy` and `taskstate` import no internal\n package. There is no `shared/`, `utils/` or `common/` package.\n- A behaviour has one authoritative path. Before adding a second way to do\n something, remove or redirect the first.\n\n## Adding a capability to a process\n\n1. Decide which process owns it. A new binary is justified only when the\n surface must fail, scale or run somewhere independently.\n2. Wire it at that process's composition root. An optional capability\n degrades: a missing provider logs a warning and marks health degraded\n rather than stopping the process (MCP providers are the model).\n3. Every process that reaches the capability through the State Store gets it\n through a `storecontract` interface asserted on the client\n ([State Store](/dev/development/state-store/)).\n4. The architecture tests (`cmd/archie-ui/architecture_test.go`,\n `cmd/archie-messaging/architecture_test.go`, `TestOpenStoresNeverOwnsTaskDB`)\n pin what each binary may link. A failure there means the placement is wrong,\n not the test.\n\n## Adding a plugin engine\n\nSatisfy every invariant in \"Plugin engine rule (strict)\" in\n`plugins-and-extensions.md`: typed domain contract, an owning manager,\nlifecycle and health, narrow host access, and an explicit trust boundary.\n`internal/plugin/architecture_test.go` checks the parts that can be checked.\n\n## Adding a channel or a NATS subject\n\n- Channel rules (Telegram's pending-update drop, command scopes) are in\n `CLAUDE.md` under Per-Package Invariants.\n- A subject is part of the wire contract. Its payload type belongs to the\n domain that defines its meaning, and the transport code lives in\n infrastructure.\n"
},
{
"url": "/dev/development/workflows/",
"title": "Workflows",
"section": "Development",
"body": "# Workflows\n\nAuthority: `docs/architecture/agent-system.md` for the lifecycle,\n`docs/prds/event-automation.md` for inputs, repository modes and profiles.\n\nWorkflow definitions are YAML stored as a control-plane resource. The State\nStore validates them and the agent compiles them, each against the step\nvocabulary it registers, so both must see the same step types.\n\n## Adding a step type\n\n1. Write the factory in `internal/domain/workflow` as a `StepType`. It decodes\n and validates its settings and returns an error for anything it cannot\n honour. The factory runs when a definition is saved and again when it is\n compiled, so a bad definition is refused on save.\n2. Register it through a provider in\n `internal/infrastructure/workflowsteps/workflowsteps.go`. That one list is\n what every process registers, which is how the validating and executing\n sides agree.\n3. An agent-driven step builds on `AgentStage`; do not start a second path to\n the agent runner.\n4. A step that needs no repository goes in `repoFreeStepTypes` in\n `definition.go`, or workflows declaring `repository: none` or `optional`\n cannot use it. A step that needs one may assume `tc.Dir` holds a worktree\n only when the workflow's repository is `required`.\n5. A step that ends the workflow sets `tc.Outcome`. A workflow that runs out of\n steps without an outcome is parked as a definition bug.\n6. Add a parse test (settings accepted and refused) and a run test with fake\n `Trees` and agent runner.\n\n## Retiring a step type\n\nA step word cannot simply be deleted. A stored or pinned definition is\nvalidated as a whole collection, so one unknown word fails EVERY workflow's\ndefinition to decode and the workflow-definitions resource becomes unreadable.\nRetire a stage by removing it from its workflow's `Stages` and adding it to\n`retiredSteps` in `definition.go`, which keeps the word resolving as an inert\nstage. The retired stage must do nothing: the behaviour it used to perform now\nbelongs to whatever layer took it over (the remediate workflow's in-container\nresume moved to daemon worktree preparation, `archie-core-866m`; the workflow\nstill binds the daemon-prepared directory and the PR branch in a `prepare`\nstage before any agent work).\n\n## Changing the definition format\n\n- The fields a caller needs without the engine (inputs, repository, profile)\n live in `task.WorkflowInterface`, because the dashboard process must not\n import the workflow engine (`cmd/archie-ui/architecture_test.go`). Anything a\n binding or the dashboard checks goes there.\n- The YAML decoder rejects unknown keys. Existing stored definitions must keep\n parsing, so a new key is optional with a default that preserves today's\n behaviour.\n- A declared `outputs:` entry is written through a capture tool, so it forces\n the captures need: `task.WorkflowInterface.Needs` resolves that from the\n declaration rather than the author also writing `needs.captures`. A Kit\n profile whose harness serves no capture tools is refused before dispatch.\n- Examples in `examples/workflows/` are parsed against the registered\n vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.\n\n## Enabling and disabling\n\nThe `workflow-enablement` control-plane resource lists, per org, the workflows\nthat org has disabled; anything unlisted is enabled. Its readers are the\ndaemon's binding dispatch (a disabled workflow's binding is skipped like an\nunarmed one), the dashboard's binding save (refused) and binding list\n(`workflow_disabled`), and work requests. A new reader of \"may this org run\nthis workflow\" goes through `task.WorkflowEnablement.Enabled`, never a second\nlist. The dashboard acts in the default org until access resolves a caller's\nown.\n\n## Starting a workflow from chat\n\n`task_spawn` accepts `workflow` and an `inputs` object. The gateway forwards\ninputs through the task creation contract; it does not interpret individual\nworkflows. The daemon checks inputs against the pinned `WorkflowInterface`\nbefore acquiring a container and parks invalid requests with the reason.\n"
},
{
"url": "/dev/prds/01-project-management/",
"title": "Architecture Decision Index",
"section": "PRDs",
"body": "# Architecture Decision Index\n\n**Status:** Approved \n**Date:** 2026-07-28 \n**Beads issue:** `archie-core-5d7`\n\n## Purpose\n\nThis file is the navigation point for Archie's target architecture. It is\ndeliberately short. Architectural decisions are separated by domain or\nrequirement so an implementation task can load only the rules governing its\nscope.\n\nImplementers MUST read the decision document for the domain or requirement they\nare changing. They MUST NOT infer permission to change neighbouring domains from\na broader restructuring objective.\n\n## Global invariants\n\n- Organise code around cohesive application responsibilities, not generic\n technical mechanisms.\n- Domains own their behaviour, vocabulary, state, commands, events, policy\n implementations, runtime settings, and required service contracts.\n- Domains do not depend on infrastructure or manipulate another domain.\n- `internal/app` owns composition; `cmd/*` remains thin.\n- Cross-domain work uses an explicitly owned command, event, or approved shared\n contract.\n- Process boundaries are deployment choices and do not determine source-code\n ownership.\n- Existing package names and boundaries have no presumption of survival.\n\nThe words **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are normative.\n\n## Decision documents\n\n| Scope | Authoritative document |\n| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |\n| Repository layout, domains, composition, deployments, and optional material | [architecture/organisation.md](/dev/architecture/organisation/) |\n| Dependency direction, domain contracts, infrastructure, commands, events, and wire contracts | [architecture/dependencies-and-contracts.md](/dev/architecture/dependencies-and-contracts/) |\n| External configuration, runtime settings, and dissolution of `internal/config` | [architecture/configuration.md](/dev/architecture/configuration/) |\n| Persistent actor identity, ownership, lifecycle, and attribution | [architecture/identity.md](/dev/architecture/identity/) |\n| Agent definitions, workflows, workflow executions, tools, and worker boundaries | [architecture/agent-system.md](/dev/architecture/agent-system/) |\n| Personal-assistant interactions, messaging channels, and optional promotion into durable work | [architecture/messaging-and-work-intake.md](/dev/architecture/messaging-and-work-intake/) |\n| Shared policy evaluation and domain-owned policy semantics | [architecture/policy.md](/dev/architecture/policy/) |\n| Safe source/configuration changes, health supervision, and recovery | [architecture/safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/) |\n| Plugin framework, plugin implementations, and extension isolation | [architecture/plugins-and-extensions.md](/dev/architecture/plugins-and-extensions/) |\n| Generated references, deprecations, and changelog generation | [architecture/generated-documentation.md](/dev/architecture/generated-documentation/) |\n| Remaining package destinations, data migrations, runtime cutover, and completion criteria | [architecture/migration-decisions.md](/dev/architecture/migration-decisions/) |\n| Domain/feature research, design interview, and required handoff | [architecture/package-review.md](/dev/architecture/package-review/) |\n\n## Deferred decisions\n\nThe remaining package-placement, data-migration, shared-mechanics, process-\nboundary, and cutover decisions are maintained in\n[architecture/migration-decisions.md](/dev/architecture/migration-decisions/).\n\nEach decision is made in its focused document after code-grounded review.\n"
},
{
"url": "/dev/prds/RULES/",
"title": "PRD writing rules",
"section": "PRDs",
"body": "# PRD writing rules\n\nThese rules apply to every file in `docs/prds/`.\n\n- Search existing PRDs, issues, architecture records, and code first. Do not ask\n the maintainer to repeat recorded requirements.\n- A newer maintainer decision overrides an older design. Mark the old design as\n superseded instead of preserving or defending it.\n- Write plain English. Use a technical term only when the reader needs that\n exact contract or concept.\n- Use the shortest direct sentence. Write “When upgraded, existing instances\n are migrated to the database,” not a description of an importer seeding\n absent resources.\n- State each fact once. Do not repeat a heading, summarise a list before showing\n it, or restate a decision afterward.\n- Every sentence must add a decision, requirement, constraint, evidence, or\n verification step. Delete narration and explanations of obvious text.\n- Do not turn a requested outcome into extra product features. Keep inferences\n open until the maintainer or repository evidence settles them.\n- Do not create a process for a logical boundary. Add one only when it must\n deploy, scale, start, secure, or fail separately.\n- Describe working behaviour, not explanatory UI around missing behaviour. State\n what users can do and how success is proved.\n- Before approval, use independent read-only reviewers to check a cross-cutting\n PRD for missing behaviour and exaggerated claims. Verify and synthesise their\n findings; do not copy their prose.\n- Before requesting approval, review every sentence for complexity, repetition,\n and unsupported scope.\n- Write nothing whose truth expires. No `file.go:123` citations (cite the file\n and the symbol), no progress reports on the work being designed, no dated\n status claims, and no record of how a finding was produced. A phased plan is\n durable design; which phase is finished is not. Do not refer to what this\n document used to say: the reader cannot see it. A supersede marker is fine\n when it names a file, a section or a symbol they can find. `task docs:prds`\n enforces this.\n- Every PRD carries one of three statuses, and nothing else in that field.\n `Draft` until the maintainer explicitly approves it, `Approved` once they\n have and while the work is being built, `Finalised` when the work is\n complete. A finalised PRD does not change; supersede it with a new one\n instead. A revision number belongs in `**Revision:**`, a pointer to the\n authoritative document in `**Authority:**`, and what a past revision changed\n belongs in git.\n"
},
{
"url": "/dev/prds/action-playbook-run/",
"title": "Running action playbooks",
"section": "PRDs",
"body": "# Running action playbooks\n\n**Status:** Approved\n**Date:** 2026-09-23\n**Parent:** `docs/prds/multi-action-playbooks.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-t2db.31`\n\n## Why this exists\n\nAn action playbook loads and type-checks but never runs: `Store.Dispatch`\nskips it and the daemon logs a warning at boot (`multi-action-playbooks.md`,\nD1). This document defines when it runs, what each action does, and how the\n`playbook_dispatches` ledger gates it.\n\n## When a playbook runs\n\nThe daemon runs action playbooks at the point it pins a task's workflow\ndefinition (`Daemon.resolveWorkflowID`), using the same `DispatchInput` the\nworkflow playbooks use. The definition is pinned once per task, so the run\nhappens once per task.\n\n- Every action playbook whose trigger matches runs, in load order. A workflow\n playbook stops at the first match because it chooses one workflow; action\n playbooks choose nothing, so no match suppresses another.\n- A run never changes routing. The task is pinned by the workflow playbooks\n and bindings exactly as when no action playbook exists.\n- An action or playbook failure never parks or fails the task. It is logged\n at warning level with the playbook, the action and the task.\n- A task that already names a workflow (the approval requeue) is skipped, as\n it is for workflow playbooks.\n- Actions run synchronously in the pin path, bounded by the daemon's context.\n The only Module kind, `log`, returns immediately. A slow kind must bring its\n own timeout.\n\n## What one action does\n\nActions run in order against one evaluation context whose `actions` map\nstarts empty.\n\n1. Evaluate `when`. False or an evaluation error skips the action (J3). A\n skipped action records nothing and produces no result.\n2. Evaluate every `args` value. An evaluation error stops the playbook.\n3. Call `playbook.InvokeOnce` with the Module invoke as its function. The\n ledger row is written first. A duplicate row skips the invoke.\n4. An invoke error stops the playbook. The row stays, so the action is not\n retried: the ledger promises at most once, not at least once.\n5. On success, `ModuleRegistry.DecodeResult` converts the result, and it is\n stored as `actions.\u003cid\u003e.result` when the action declares an id.\n\nThe event id in the ledger key is `DispatchInput.TaskID`, the issue's\nidempotency key (`owner/repo/number`). An action therefore runs at most once\nper issue for each playbook version. Editing a playbook changes its version\nand lets it run again for issues it already handled.\n\nA skipped duplicate has no result. A later action that reads it sees a\nmissing field: its `when` evaluates false, or its args fail and the playbook\nstops. This only happens when the same issue is pinned twice under one\nplaybook version.\n\n## Wiring\n\n- `storecontract.PlaybookDispatcher` is lifted onto the daemon from the State\n Store client in `internal/app/archied/bootstrap.go`, the same way\n `BindingDispatcher` is.\n- The daemon's `Playbooks` dependency gains the run method. The Module\n registry is passed to the playbook store at load, so the daemon needs no\n new dependency for it.\n- With no `PlaybookDispatcher` wired, action playbooks do not run, and the\n boot warning names each one. They never run without the ledger.\n- The boot warning that action playbooks do not execute is removed when the\n ledger is wired.\n\n## Verification\n\n- A matching two-action `log` playbook runs both actions in order, and the\n second reads the first's result.\n- Pinning the same task twice under one playbook version invokes each action\n once.\n- A `when` that evaluates false skips that action and the run continues.\n- An invoke error stops the playbook. The task is still pinned to the same\n workflow it would get with no action playbook.\n- A non-matching trigger runs nothing.\n- With no ledger wired, nothing runs and the warning names the playbook.\n"
},
{
"url": "/dev/prds/agent2agent-protocol/",
"title": "Agent2Agent as archie's agent-to-agent protocol — decision",
"section": "PRDs",
"body": "# Agent2Agent as archie's agent-to-agent protocol — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** the A2A Protocol Specification v1.0.0 (`a2a-protocol.org`) for the\nprotocol, `docs/architecture/organisation.md` for package placement, and\n`docs/architecture/migration-decisions.md` §2 for session and messaging design.\n\n## Decision\n\nA2A is the protocol archie speaks to other agents. It carries agent-to-agent\nwork: discovery of what a remote agent offers, delegation of a unit of work to it,\nprogress on that work, and the artifacts it produces.\n\n## Layers\n\n**MCP stays the tool layer.** MCP connects a model to tools and data; A2A connects\nagents to agents. They are complementary and archie runs both:\n`internal/tools/provider` registers MCP providers as optional capabilities, so an\nA2A call and an MCP tool call are different kinds of traffic with different\nowners.\n\n**A2A rides archie's existing transports.** A2A's canonical data model is\nProtocol Buffer messages and it defines a gRPC binding, so archie speaks A2A over\nthe gRPC and NATS it already runs. A second wire format, a second broker, or a\nbespoke protocol for agent-to-agent traffic is a requirement not to introduce.\n\n## Where A2A stops\n\nA2A is not a general replacement for either of the two protocols archie already\nhas, and each boundary is a requirement rather than a preference.\n\n- **`internal/domain/messaging` stays the human and channel layer.** A\n Conversation is a ChannelID and a ThreadID, its participants are people on\n Telegram, email, webhook and the dashboard, and its records are what a curator\n reads. An A2A peer is not a channel participant and does not address a\n Conversation.\n- **`internal/agentexec` stays the daemon-to-worker execution protocol.** It\n carries a Request, a Result, gate and budget policy, and capture tools between\n the daemon and the agent container it owns. An A2A peer never receives that\n protocol, and A2A never carries gate, budget or protection policy.\n\nA2A is therefore an edge protocol: it exchanges work with peers outside archie's\nown process boundary, and it composes with the two protocols above rather than\nreplacing or abstracting them.\n\n## A2A Task mapping\n\n**Decision: archie's work lifecycle is mapped to A2A's, not expressed in it. An\nA2A Task is a view over archie's own task, and archie's status remains the record\nof truth.**\n\nThis is the load-bearing decision, because A2A's Task carries its own state\nmachine and archie's lifecycle is the on-disk format of its task store, whose\nstatus strings a rename migrates rather than changes.\n\nThe mapping is partial, and each gap is a case where archie knows something A2A's\nstates do not carry:\n\n- **Completion by another system.** A2A's terminal states describe what the agent\n did (`completed`, `failed`, `canceled`, `rejected`). archie's `merged` and\n `rejected` describe what a forge did to a pull request after archie finished\n its work. There is no A2A state for \"an external system accepted this\", so a\n completed A2A task cannot express the outcome that matters most to the caller.\n- **Handing work to a reviewer.** archie's `pr_open` means the work left\n archie's hands for human review. A2A's `input-required` is the nearest state,\n but it means the _client_ must send more input, and a reviewer is not the\n client.\n- **Operator decisions.** `declined`, `parked` and `dead` are outcomes of\n archie's own policy and operator actions. A2A has no state for \"the operator\n refused this\" or \"a budget ran out and an operator must decide\".\n\nA WorkflowExecution is the unit an A2A task maps onto, because it is the attempt\nthat runs, streams and produces artifacts, and a follow-up attempt is a new\nexecution. A2A's own model agrees that a task is immutable once terminal and that\na refinement is a new task sharing the `contextId`, which is why archie's\nper-attempt executions and A2A's per-request tasks correspond.\n\n**Requirement:** the A2A state a peer sees is derived from archie's status by one\nmapping, and archie's status is carried on the task so a peer can read what the\nderivation lost. The mapping is total in the direction that matters -- every\narchie status has an A2A state -- and deliberately not injective, because the\ngaps above are facts A2A cannot hold.\n\n**Requirement:** adopting A2A's state names as archie's persisted task status is\nrejected. It would migrate the task store, and it would drop the forge outcomes\nthat tell a caller whether the work was accepted.\n\n## What an A2A agent is\n\n**An A2A agent is an archie Identity.** The Agent Card describes a durable,\naddressable actor with an endpoint, capabilities and authentication requirements,\nand an Identity is the actor archie persists, versions, suspends and scopes\ncredentials to.\n\nAn `agent.Persona` is not an A2A agent: a persona is prompt text selected for a\nturn, and it has no endpLine truncated
},
{
"url": "/dev/prds/artifact-sender/",
"title": "Artifact sender",
"section": "PRDs",
"body": "# Artifact sender\n\n**Status:** Approved\n**Revision:** 1\n**Authority:** this document\n\n## Purpose\n\narchie-core publishes artifacts — design documents, review reports, research briefs,\nrunnable pages — to the offloaded.dev collaborative editor. A person reads the\nartifact, comments on it, and the artifact page is the shared surface for iteration.\n\nThe receiving contract is owned by the editor: `POST /api/artifacts` with a bearer\nservice token, a closed field set, and server-side idempotency on `requestId` plus\nlast-write-wins on `sentAt`. This document owns only what archie-core sends.\n\n## Scope\n\nVersion one publishes one-way: archie-core sends, the editor receives. The first\nproducer is the pull-request adversarial review: a completed `ReviewReport` is\nrendered to markdown and published after the review completes.\n\nChat-surface tools (`create_artifact`, `update_artifact`), comment read-back, share\ntokens, and runnable-format producers (`html`, `react`, `vue`) are later slices. The\nreceiving contract already carries them; version one does not exercise them.\n\n## Configuration\n\n- New `[artifacts]` section: `base_url` (site origin), `token` (`SecretRef`) with\n `token_env` fallback naming `WORKSPACE_INGEST_TOKEN`.\n- An empty `base_url` disables the sender: no client is constructed, nothing is\n registered, and publishing degrades to a log line.\n- The token is runtime configuration. It is never baked at build time.\n\n## Sender\n\n- New package `internal/infrastructure/artifactsync` exposing one method,\n `Publish(ctx, Artifact) (string, error)`, where the string is the artifact URL.\n One-method injected seam, concrete client constructed by the boot path when the\n configuration resolves — the `crondelivery.Courier` posture.\n- The client POSTs the frozen contract body. Each publish sends the complete\n source: versions of record are full snapshots, never diffs.\n- A `503` response is retried three times with backoff. `401` and `400` are not\n retried; they are logged with the field reason the response names.\n- `requestId` is `artifact:\u003ctask-id\u003e:\u003cversion\u003e` when the producer is task-backed,\n otherwise `artifact:\u003cidentity\u003e:\u003csentAt-utc\u003e`. Sending the same `requestId` with\n an equal or older `sentAt` must be a server-side no-op, which makes sender-side\n retry safe.\n\n## Report rendering\n\n- `ReviewReport` gains a pure markdown renderer in `internal/domain/workflow`:\n the summary as the lede, one finding per subsection with file, line, verdict,\n level and the failure scenario, and the verified properties as a \"checked\n clean\" list. Findings carry their disposition when present.\n- The renderer performs no I/O and imports no infrastructure.\n\n## Attribution\n\n- `actor`: the producing identity. The reviewer publishes as `system:pr-reviewer`\n when no task identity resolves; otherwise the task's identity name.\n- `source`: the producing subsystem, `pr-review` for version one.\n- `task`: owner, repository and issue number from the task when one exists.\n\n## Failure behaviour\n\n- Publishing never fails the producing work. A failed publish is logged with its\n status and reason; the artifact is republished on the next production of the\n same artifact.\n- A successful publish records the artifact URL in the run report, so the PR\n description or task log links to the readable artifact.\n- The published URL is the editor deep link for the artifact, keyed on its\n immutable id. archie-core never mints share links; sharing is an\n account-holder decision made in the editor.\n\n## Verification\n\n- Client tests against a test server cover 201, 401, 400 with a field reason,\n and 503 retry behaviour.\n- The report renderer test covers a report with findings, checks, dispositions\n and a not-run status.\n- Configuration tests cover the disabled case, the `SecretRef` path and the\n `token_env` fallback.\n"
},
{
"url": "/dev/prds/binding-secret-encryption/",
"title": "Binding secret at-rest encryption -- decision",
"section": "PRDs",
"body": "# Binding secret at-rest encryption -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-t2db.7` (P2), parent `archie-core-t2db`\n\n## Problem\n\n\u003e Storage superseded: every store now lives in PostgreSQL behind\n\u003e `internal/domain/storecontract`, implemented in `internal/infrastructure/postgres`\n\u003e (`docs/prds/state-store-contract.md`). SQLite names below describe the\n\u003e original design.\n\n`binding.Binding.Secret` (the per-source HMAC shared secret) is persisted as\nplaintext in the `bindings.secret TEXT` column. Anyone with read access to the\nSQLite file -- the same access level as `captured_events.body` and `tasks.body`\n-- sees sender-side shared secrets. A leaked database file leaks secrets even\nwhen the filesystem ACLs were correct at rest.\n\n## Decision\n\nEncrypt the `secret` column at rest with **AES-256-GCM** (stdlib\n`crypto/aes` + `crypto/cipher`, no new dependency), transparently inside the\nstore: encrypt on write, decrypt on read. The store is the data boundary; its\nconsumers (dispatch loop, HMAC verification) receive the plaintext secret\nexactly as and the webui already blanks `Secret` on every response.\n\n### Cipher parameters\n\n- **AEAD:** AES-256-GCM, 12-byte random nonce (`crypto/rand`), tag appended.\n- **Key length:** 32 bytes, derived as `SHA-256(resolved_material)`. Kept as\n SHA-256 (no Argon2id) because the source is a **32-byte high-entropy** value\n resolved through the secret registry, so re-deriving to 32 bytes merely\n re-shapes entropy rather than defending a weak passphrase.\n- **AAD:** a static domain separator, `[]byte(\"arcie-binding-secret\")`, so a\n ciphertext cannot be relocated to a different field/column and still\n authenticate. AAD is intentionally **not** row-bound: binding secrets are\n random HMAC keys and are never used as lookup keys, so cross-row swap is not\n a meaningful attack here.\n\n### Envelope format\n\n```\narcie-binding:v1:\u003ckeyFingerprint\u003e:\u003cbase64url(nonce || ciphertext || tag)\u003e\n```\n\n- `arcie-binding` -- domain marker\n- `v1` -- format version (future cipher/KDF change is a new version, old rows\n stay readable)\n- `\u003ckeyFingerprint\u003e` -- `hex(SHA-256(material))[:16]`, the identity of the key\n that sealed the row, enabling rotation without a one-shot rewrite\n- payload -- `base64url` of `nonce ‖ GCM.Seal(plaintext, aad)`\n\n### Key source (confirmed with maintainer)\n\nResolved through the existing secret registry (`internal/secret`), the\nestablished `SecretRef` pattern already used for `forge.webhook_secret`:\n\n```toml\n[bindings]\nencryption_key = { engine = \"env\", key = \"ARCHIE_BINDING_KEY\" }\n# Rotation: after swapping encryption_key to a new value, retain the previous\n# material so rows sealed under the old key still decrypt.\nprevious_encryption_keys = [ { engine = \"env\", key = \"ARCHIE_BINDING_KEY_OLD\" } ]\n```\n\nThe active key encrypts new writes; `previous_encryption_keys` are retained for\ndecrypt-only. Key identity is intrinsic to the material (the fingerprint), so\nno manual key IDs are configured.\n\n### Rotation story\n\nRotate by changing `encryption_key`, moving the old material into\n`previous_encryption_keys`. Rows sealed under the old key still decrypt via\ntheir embedded fingerprint; new writes use the new active key. Once no\nremaining row references an old fingerprint, remove it from the config. Losing\na fingerprint's material before all its rows are rewritten makes those rows\nunreadable -- the same operational rule as any key rotation, and the reason the\nold material must be retained.\n\n## Non-goals / deferred\n\n- **`captured_events.body` redaction hardening** was completed alongside this\n work (not deferred): `webhookguard.RedactPayload` now redacts an expanded set\n of secret key markers (compound names like `access_token`, `client_secret`,\n `signing_key`, `x_api_key`, …) as well as unambiguous value shapes (compact\n JWTs, PEM private-key blocks) under any key. `gateway.sensitiveParameterKey`\n was broadened identically to preserve the documented agreement. It remains\n best-effort per `docs/prds/webhook-intake-security.md` point 5 -- a sender\n that picks a name the heuristic misses is still captured.\n- **Key re-derivation on config reload** is a startup concern: the store holds\n the cipher for its lifetime, so a reload that changes `[bindings]` keys\n requires a daemon restart to take effect. Documented, accepted.\n\n## Wiring\n\n- `internal/config`: add `BindingsConfig` (`encryption_key SecretRef`,\n `previous_encryption_keys []SecretRef`) on `Config.Bindings`.\n- `internal/app/archied/bootstrap.go` `openStores`: resolve both refs through\n the already-built `secrets` registry, pass the material to `store.Open` via a\n new option `store.WithBindingCipher(cipher)`.\n- `internal/infrastructure/bindingcipher`: the `BindingCipher` interface and\n concrLine truncated
},
{
"url": "/dev/prds/channel-forge-positions/",
"title": "Channel and Forge action positions (resolves `t2db.19`)",
"section": "PRDs",
"body": "# Channel and Forge action positions (resolves `t2db.19`)\n\n**Status:** Approved\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Blocked on:** `archie-core-t2db.24` (the `playbook_dispatches` ledger) for\nimplementation of either position. Both are side-effecting, and `t2db.17`\nresolved the keying scheme in design only.\n\n## Forge\n\n`internal/forge.Forge` is already exactly the shape a native-Go action position\nneeds -- a real, typed, general-purpose interface, not something that needs a\nYaegi/Module-style schema-generation detour:\n\n```go\ntype Forge interface {\n IssueForge // AssignedIssues, IssuesWithLabel, CloseIssue, ...\n PullRequestForge // CreatePR, PRState\n RepoForge // AcceptInvitations, VerifyPush, LinkBranch, ...\n}\n```\n\n**Typed contract shape: native-Go-by-name, not a Module-kind.** Module's whole\nreason to exist is giving _Yaegi-authored, operator-supplied_ code a typed\ncontract to implement. `Forge` is already a typed Go interface with real, tested\nimplementations (GitHub, Gitea) selected at daemon startup by `forge.New(...)`.\nWrapping it in a Module-kind schema/`go:generate` detour would duplicate a\ncontract that already exists. A Forge action position should be: a small set of\nnamed operations (e.g. `close-issue`, `create-pr`, `link-branch`), each with a\ntyped `Args`/`Result` struct mirroring the matching method's parameters/return.\n\nThe dispatch target is `internal/domain/workflow.Forger`\n(`CloseIssue`/`CreatePR`/`LinkBranch` -- already exists, already exactly these\nthree operations), **not** `internal/forge.Forge` directly. `organisation.md`'s\ntarget structure places `forge/` under `internal/infrastructure/forge/`; the flat\n`internal/forge` is a flat, unmigrated legacy package in the same position\n`internal/workflow` was in before its own migration. A new domain package\ndepending on the flat package directly would create a domain-to-infrastructure\ndependency that breaks the moment `forge` migrates. `workflow.Forger` is the\nnarrow, already-domain-owned contract that exists for exactly this reason -- the\ndaemon's real `forge.Forge` client satisfies it at the wiring layer.\nDepend on `Forger`, not on `internal/forge`.\n\n**Operation scope for a first slice:** `close-issue` and `link-branch`\n(single-call, cleanly idempotent by event+issue identity) are the safe starting\nset. `create-pr` is explicitly a heavier case -- opening a PR is a\nharder-to-reverse action with its own dedup shape beyond \"did this event fire\nbefore\" (a redelivered event must not open a second PR for the same logical\nchange) -- defer it to a follow-up slice once the keying scheme is proven on the\nsimpler operations, don't design it blind now.\n\n**Host access:** the coordinator needs the same `Forge` instance\n`internal/daemon`'s poller already holds (constructed once at startup via\n`forge.New`). This is a daemon-composition wiring question (pass the existing\ninstance into the coordinator's constructor), not a new extensibility mechanism.\n\n## Channel\n\n### Constraints this satisfies\n\nMessaging is the root, Channel is the integration layer, an implementation such\nas Telegram sits under Channel. A channel is added by implementing one reusable\ninterface, and every channel must implement it. A notification mechanism belongs\nunder Messaging, and `channels.Channel` must not reach across into it.\n\n### Notification is a Messaging contract, not a channel type\n\nThe contract lives in `internal/domain/messaging`. A channel implementation\nsatisfies it by importing its own parent, which it already does, so the\ndependency stays `channels -\u003e messaging` and nothing points back.\n\n`channels.Channel` does not change. It gains no notification method and no\nimport, so the interface every channel must implement stays the lifecycle and\nconfig contract it is. `internal/channels/telegram` satisfying both\ncontracts is an implementation choosing to, not the Channel layer knowing about\nnotification.\n\nA notification is not a channel type because it has no lifecycle to start and\nstop, no inbound direction, and no configuration schema of its own. Modelling it\nas one would force `Start`/`Stop`/`ConfigSchema` onto something with no meaning\nfor them, and make every real channel declare whether it is a notification.\n\n### Destinations are configured, never named by a playbook\n\n`[notify]` becomes a set of named destinations. Each binds a name the operator\nchooses to a channel already registered in the Messaging composition\n(`internal/app/archiemessaging/compose.go` registers `telegram`, `email`,\n`webhook`) plus that channel's own address, such as a Telegram chat id. The\nexisting single-webhook form keeps working as a destination named `webhook`.\n\nA playbook action names a destination. It never names an address. Playbook\ntriggers are reachable from a public, unauthenticated intake surface, soLine truncated
},
{
"url": "/dev/prds/code-graph-mcp/",
"title": "Code graph over MCP (`tools/codegraph`)",
"section": "PRDs",
"body": "# Code graph over MCP (`tools/codegraph`)\n\n**Status:** Draft\n**Supersedes:** `symbol-reference-index.md`, which scoped only the data layer.\n\n## The problem\n\nEstablishing what a change touches costs an agent eight to fifteen\ngreps, and the answers are wrong in specific ways. `grep -rn \"Register(\"`\ncannot separate `plugin.Registry.Register` from `captureintake.Receiver.Register`\nfrom `forgerpc.Server.Register`, all of which exist here. It also matches the\nsibling checkouts under `.worktrees/`, which are near-complete copies of the\nmodule, so every count is silently inflated.\n\nThat cost lands hardest in investigation, triage and the TDD loop, where the\nfirst question is always \"what does this touch\".\n\n## Decision: exact analysis, not semantic retrieval\n\nTools like Greptile parse with tree-sitter, summarise each node, embed the\nsummaries, and retrieve semantically. That design exists because they must\nserve any language. This repository is one Go module, and Go's type checker is\nground truth:\n\n| Question | Source of truth |\n| --------------------------- | ------------------------------------------------ |\n| Who references this symbol? | `go/packages` + `go/types`, resolved by identity |\n| What calls what? | `callgraph` RTA over SSA |\n| What imports what? | `go list -deps` |\n\nNo vector database, no embedding cost, no edges invented by a summary that\ndrifted from the code. For a single-language repository this is both cheaper\nand strictly more accurate. Copy the interface those tools expose, not their\narchitecture.\n\n**A code graph does not power a documentation chatbot.** It answers structural\nquestions about Go symbols. Answering \"how do I configure a second identity\"\nmeans retrieving prose from markdown, which needs chunking, embedding and\nsimilarity search over a different corpus entirely. That remains a separate\ncapability with its own design. Conflating the two would build one system that\ndoes neither well.\n\n## Interface: an MCP server\n\n`archied` already consumes MCP as a client (`internal/app/agentworker`\nstarts providers) and serves none. Exposing the graph over MCP reaches Claude\nCode, pi, codex and Archie's own agents through one surface, with no coupling\nto the daemon: it is configured like any other entry in `[[mcp_servers]]`.\n\nFour tools, each returning JSON with file:line citations:\n\n- `references(symbol)` — every reference site, classified `prod` / `test` /\n `generated` / `dynamic`\n- `callers(symbol, depth)` — inbound call edges\n- `callees(symbol, depth)` — outbound call edges\n- `blast_radius(file | symbol)` — the transitive neighbourhood a change reaches,\n which is the single call meant to replace the grep sequence\n\nDiagrams are deliberately not a tool. A model given an accurate subgraph writes\nits own Mermaid; a diagram endpoint would only fix the rendering of something\nthe model already has.\n\n## Decisions\n\n**Every answer declares what it could not see.** RTA over-approximates\ninterface dispatch, and reflection is invisible: every `reflect.ValueOf` entry\nin `wfextract`, `gateextract`, `pluginextract`, `secretextract` and\n`logextract` makes a symbol look reachable whether or not anything calls it.\nEach response carries a `dynamic_edges` field naming those boundaries. An agent\ntrusting a confident wrong graph is worse off than one that greps, so the graph\nstates its own limits rather than implying completeness.\n\n**Warm in memory, keyed on HEAD, never persisted to disk.** `deadcode` does\nwhole-program RTA in under seven seconds; this does less work. The server\nrebuilds when HEAD changes and refuses its cache outright when the tree is\ndirty. Nothing is written to disk, because a persisted index becomes a rendered\nview that outlives its evidence. That is the failure that made `STATUS.md`\nreport 90 of 91 findings re-verified while most statuses were 77 commits stale,\nand the same one that made `reachaudit` serve a previous tree's analysis from\n`/tmp` until its cache was keyed on HEAD.\n\n**`tools/codegraph`, not `internal/`.** It is developer tooling, not daemon\nruntime, so it belongs beside `docsgen`, `contractaudit` and `reachaudit` in\nthe `tools` module, which `task test:tools` already covers. Start as a single\nGo file; split only when it earns it.\n\n**No new dependency.** `golang.org/x/tools` is already in `go.sum` at v0.49.0.\n\n## How it is verified\n\nRed first. Table-driven tests against small fixture modules built in\n`t.TempDir()`, asserting the behaviour that distinguishes this from grep:\n\n1. Two methods spelled `Register` on different types resolve to two separate\n records, and a reference to one does not increment the other.\n2. A symbol referenced only from `_test.go` reports zero `prod` references.\n3. A symbol referenced only from a `reflect.VLine truncated
},
{
"url": "/dev/prds/config-example-drift/",
"title": "Example-config and generated-config drift — decision",
"section": "PRDs",
"body": "# Example-config and generated-config drift — decision\n\n**Status:** Approved\n**Date:** 2026-09-15\n**Closes:** the checked-in-config half of audit findings `config-1` and\n`repo-root-deployment-2`; strengthens `doc-drift` findings generally.\n**Authority:** extends `docs/architecture/generated-documentation.md` and\n`docs/prds/config-schema.md`; does not replace either.\n\n## Question\n\nShould `config.example.toml` and `deployments/*.toml` be _generated_, so they\ncannot drift from the config code?\n\n## Decision\n\n**No — do not generate them. Gate them instead.** Neither file is a projection\nof the schema, and generating either would destroy the thing that makes it\nuseful. Three verified reasons, in order of weight:\n\n1. **`config.example.toml`'s value is its comments.** It documents **137 keys**\n (measured: active _and_ commented-out), and those hand-written comments are\n the file's purpose — `docs/architecture/configuration.md` states outright\n that \"`config.example.toml` carries documentation users are meant to\n hand-edit\". TOML round-tripping does not preserve comments, which is exactly\n why `tomlwrite` does line-oriented edits rather than decode/encode. A\n generator would emit a correct file with the documentation deleted.\n2. **`docs/prds/config-schema.md` forbids building on `config.Config`.** That PRD\n rejects \"a reflection-based schema over `config.Config`\" because the struct is\n \"scheduled for dissolution\". A generator deriving the example from its struct\n tags would build on a foundation this repo has already decided to remove.\n3. **`docs/architecture/generated-documentation.md` prohibits it.** \"Adding\n another hardcoded type list to `docsgen` is prohibited\" — so any generator\n must consume a domain-owned registry, which does not exist for configuration\n yet. Creating one is the config-domain migration's job, not this change's.\n\nThe deployment profiles are also not a projection: they set **3-46 keys** against\nthe example's 137, and they are curated overlays (\"a complete config, not an\noverlay\", per their own headers), not near-duplicates. Generating them would add\nmachinery to remove duplication that largely is not there.\n\n## The gap that is real\n\n**Unknown config keys are silently ignored.** Verified at\n`internal/infrastructure/configuration/decode.go`:\n\n```go\nif _, err := toml.DecodeFile(path, target); err != nil {\n```\n\nThere is no `MetaData.Undecoded()` check, so a typo — `max_concurrancy = 4` —\nparses clean, validates clean, and does nothing. That is the same failure shape\nthis repo's audit found repeatedly: a setting that looks applied and is not. It\nis also detectable **without any hand-maintained list**, because `BurntSushi/toml`\nreports exactly which keys the target did not consume.\n\nNote the second, separate gap already admitted in writing:\n`generated-documentation.md` — \"`task check` does not run `docs:check`, so\ngenerated drift is ungated.\"\n\n## What to build\n\n**1. Unknown-key detection at the loader (behaviour).** Decode with metadata and\ncollect `Undecoded()`. Report it as a warning at startup listing the offending\nkeys, and expose it so tests can assert emptiness.\n\n**Deliberately a warning, not a fatal error.** `configuration.md`'s settled\nstartup policy is \"a missing credential disables a capability; only an invalid\nconfig stops the daemon\". A stray key is far more likely to be an operator typo\nin a file they are otherwise happy with than a reason to refuse to boot, and\n`[web]` is documented as landing in a _different_ binary\n(`internal/app/archieui`), so a key unknown to one process is legitimately known\nto another. Failing closed here would break working deployments on upgrade.\n\n**2. A checked-in-config contract test (gate).** Load `config.example.toml` and\nevery `deployments/*.toml` through the real loader and assert `Undecoded()` is\nempty, with an explicit allowlist for keys another binary owns. This is the\nmechanism that would have caught a renamed key left behind in an example, and it\nneeds no inventory.\n\n**3. Gate generated data in `task check`.** Done. `task docs:check` runs in the\ngate, closing the admitted \"generated drift is ungated\" hole. The\ncheck mode did not exist when this was written; it was added for issue #855,\nwhich also made the check non-destructive so the gate can never rewrite the\nartifact it is judging.\n\n**4. Explicitly NOT now: a generated key inventory.** `configuration.md`'s\ncompletion criteria want \"generated documentation lists every external key,\ndefault, constraint, mutability class, owner\". That is a real target and it is\nthe config domain's, once a domain-owned registry exists — the prohibition above\nmeans it cannot be bootstrapped from a list inside `docsgen`. Recorded as\ndeferred, not rejected.\n\n## Non-goals\n\n- No generation of `config.example.toml` or `deployments/*.toml`.\n- No reflection-baLine truncated
},
{
"url": "/dev/prds/config-schema/",
"title": "Backend-owned configuration schema for the webui -- decision",
"section": "PRDs",
"body": "# Backend-owned configuration schema for the webui -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-b6ew` (epic), with children `.1`-`.5`\n\n## Decision\n\nThe dashboard's Configuration page keeps reading a secret-free,\nhand-picked view of `config.Config` -- that allowlist is a safety\nboundary and stays exactly as it is. What changes is who defines the\npage around it: `ui/src/settings/settings.js` and\n`config-row.js` hardcode every row's label, section, type, and\neditability by hand; after this, the backend attaches that metadata to\neach field it already allows through, and the frontend renders\nsections and fields generically from what the backend sends.\n\nThis is **not** a reflection-based schema over `config.Config`.\n`internal/config/config.go`'s own package doc states it is \"scheduled\nfor dissolution: its types and methods are to be reassigned to the\ndomains whose behaviour they describe\" -- building a generic\nschema-from-struct-tags mechanism over a struct on its way out would be\nbuilding on a foundation this repo has already decided to remove.\nInstead, every field already in `ConfigView` (`internal/webui/api_config.go`)\ngot there because someone deliberately vetted it as safe to show; the\nschema adds a hand-authored descriptor to that same deliberate act,\nnot a new mechanism that re-derives safety automatically.\n\n## Why now\n\nTask #6's investigation (`/9/26`) found the concrete failure this\nproduces: `Repo.AllowConcurrent` and `Repo.MaxRetries` already reach\n`GET /api/config` (`RepoView` in `api_config.go`), but the\nrepositories card renders a static read-only table that never shows\nthem, so the fix for \"why isn't a second agent running\" required an\nagent tracing Go source instead of a checkbox on the dashboard.\n`Repo.ReviewEnabled` is worse: it never reaches the API at all. Both\nare symptoms of the same root cause -- the frontend decides what a\nfield means and whether it's shown, and nothing keeps that in sync\nwith what the backend actually allows.\n\n## Shape\n\n```go\n// internal/webui/config_schema.go (new)\n\ntype ConfigFieldType string\n\nconst (\n FieldString ConfigFieldType = \"string\"\n FieldInt ConfigFieldType = \"int\"\n FieldBool ConfigFieldType = \"bool\"\n FieldDuration ConfigFieldType = \"duration\"\n FieldEnum ConfigFieldType = \"enum\"\n FieldStructured ConfigFieldType = \"structured\" // repositories, models, providers\n)\n\ntype ConfigField struct {\n Key string `json:\"key\"` // dotted path, matches UpdateConfig's key space\n Label string `json:\"label\"`\n Description string `json:\"description,omitempty\"`\n Type ConfigFieldType `json:\"type\"`\n Value any `json:\"value\"`\n Editable bool `json:\"editable\"`\n LockedReason string `json:\"locked_reason,omitempty\"`\n Overridden bool `json:\"overridden\"`\n Options []string `json:\"options,omitempty\"` // enum only\n RestartRequired bool `json:\"restart_required\"`\n}\n\ntype ConfigSection struct {\n ID string `json:\"id\"`\n Label string `json:\"label\"`\n Fields []ConfigField `json:\"fields\"`\n}\n```\n\n`handleConfig` builds `[]ConfigSection` from the existing per-field\nvalues it already assembles, plus `overlay.DeniedKeys` for\n`LockedReason` and the existing `Overridden` list -- both already\ncomputed just re-attached per field instead of returned as\nside-channel maps the frontend cross-references by key string.\n`Locked`/`Overridden`/`Reload`/`Provenance` stay as top-level\n`ConfigView` fields; they describe runtime state (what happened on\nthe last reload, which keys the overlay refuses), not the field\ncatalogue, and duplicating that logic per-field would be the same drift\nrisk this change exists to remove.\n\n`FieldStructured` fields (repositories, models, providers) carry\n`Value` as structured JSON and are rendered by dedicated\neditors, not the generic renderer -- see \"What this does not do\".\n\n## Sections\n\nMatches the cards the settings page already has: `identity`,\n`repositories`, `models`, `providers`, `budgets`, `storage`,\n`containers`, `web`. No new sections; this is metadata on existing\nrows, not new configuration surface.\n\n## Frontend\n\n`config-row.js`'s `row(label, value, opts)` becomes the renderer's\nprivate implementation detail, called generically:\n\n```js\nfor (const section of schema.sections) {\n const rows = section.fields\n .filter((f) =\u003e f.type !== \"structured\")\n .map((f) =\u003e\n row(f.label, f.value, {\n key: f.key,\n type: f.type,\n options: f.options,\n locked: f.locked_reason,\n overridden: f.overridden,\n restartRequired: f.restart_required,\n }),\n );\n // structured fLine truncated
},
{
"url": "/dev/prds/contract-conformance-audit/",
"title": "Contract conformance audit — decision",
"section": "PRDs",
"body": "# Contract conformance audit — decision\n\n**Status:** Finalised\n**Scope:** an **advisory** report, deliberately **not** part of `task check`.\n**Date:** 2026-09-15\n**Authority:** sibling to `archie-core-06ag` (standing reachability audit) and\n`docs/architecture/dependencies-and-contracts.md`. Replaces neither.\n**Open:** withdraw it, or rebuild it structurally. See \"Open decision\" — not to\nbe resolved by hardening the regexes.\n\n## Question\n\nDoes every declared contract surface have a consumer, or an explicit declaration\nthat it has none?\n\nReachability (`tools/reachaudit`) asks the complementary question — _is this code\nin a shipped binary?_ — and cannot see a capability that is **reachable and\nunconsumed**. `ratelimit` was in the binary closure and called by nothing\n(`archie-core-6wxb`); reachability would not have found that.\n\n## Decision\n\nYes, as an advisory survey. `tools/contractaudit` classifies each subject of each\nsurface:\n\n| Classification | Meaning | Fails `--strict`? |\n| ----------------------- | ----------------------------------------------------------------------------- | ----------------- |\n| `CONSUMED` | a call site exercises it | no |\n| `DECLARED-UNCONSUMED` | allowlisted in `docs/contract-declarations.json`, with a reason and a tracker | no |\n| `UNDECLARED-UNCONSUMED` | nobody reaches it, nobody declared it | **yes** |\n| `STALE-DECLARATION` | an allowlist entry that is no longer true | **yes** |\n\nThere are **four** classes and **two** of them fail. The allowlist must match\nreality exactly, and it fails in both directions: a missing entry is a finding,\nand an entry that outlived its subject is a finding, because a stale allowlist is\nhow a check quietly stops checking anything.\n\n**Not gated.** `task contract` is advisory and `task check` does not run it,\nmatching `tools/reachaudit`. The surfaces are discovered by scanning source text,\nso a rename or a reformat elsewhere in the tree can change the output with nothing\nactually wrong. It has already produced 16 false \"unconsumed\" readings once, when\nthe dashboard's request helper was renamed. A check that can fail for reasons\nunrelated to what it measures must not be able to break a build.\n\n## Surfaces actually built — three, not five\n\n| Surface | Subjects | \"Consumed\" means |\n| ------------------------------------ | ------------- | -------------------------------------------------------- |\n| `proto/state/v1` `StateStoreService` | **45 RPCs** | an adapter body calls `client.\u003cRpc\u003e(...)` |\n| `proto/gateway/v1` `ChatService` | **21 RPCs** | same |\n| `internal/webui` dashboard routes | **49 routes** | a path literal appears as a call argument under `ui/src` |\n\nConsumption for the gRPC surfaces is established by **scanning adapter source\ntext** for calls through the generated client, not by reflection. See the errata\nbelow: the first revision of this document claimed reflection, and the first\nimplementation did use it, but the shipped mechanism is a regex and the document\nwas not updated to match.\n\n## What this audit has actually found\n\n**Nothing actionable.** On the current tree it reports 0 undeclared and 0 stale.\nIts only allowlisted entries are two RPCs superseded by their streaming variants\n(`ListCaptures`, `ListUndispatchedCaptures`), which were already known from the\nsource comment on `staterpc.Client.ListCaptures`.\n\nEvery real defect found in the session that produced this tool was found by other\nmeans:\n\n- the three 415 refusals, by reading `authorizeTaskMutation` and reproducing the\n browser's exact headers against the real handler;\n- the dashboard client's duplicated request plumbing, by reading the module.\n\nRecorded plainly because a survey that has never found anything is evidence about\nthe survey, not about the tree.\n\n## Errata — claims in the first revision of this document that were false\n\n- **\"RPC coverage is derived by reflection over the exported client type.\"**\n It is not. `proto.go` regex-scans adapter bodies for `client.Method(` calls.\n The reflection version was replaced and the document was not updated. The unused\n `google.golang.org/grpc` family in `tools/go.mod` was residue from that\n iteration; `go mod tidy` removed it on 2026-09-15.\n- **Surface sizes of \"43 / 12 / 52\".** The real counts are 45 / 21 / 49.\n- **\"Three classifications, and the third is the only finding.\"** Four classes,\n two of which fail.\n- **\"Raw `fetch()` calls caused 401s to render as `refused`/`brokLine truncated
},
{
"url": "/dev/prds/control-plane-apply-status/",
"title": "Control-plane apply status",
"section": "PRDs",
"body": "# Control-plane apply status\n\n**Status:** Approved\n**Date:** 2026-09-21\n**Tracking:** `archie-core-pskb`, and `archie-core-nwa0` which depends on it\n\n## Outcome\n\nAn operator who edits a control-plane resource can see which processes are\nrunning that version, which are still on an older one, which rejected it, and\nwhich have stopped reporting.\n\n`docs/prds/runtime-control-plane.md` requires this and does not say where the\nreport goes. This decides that.\n\n## Where the report goes\n\nApply status is a State Store contract surface. `ControlPlaneService` is the\nsurface for editing a resource, and a status report is not an edit. The\nprecedent is the config snapshot pair: a process publishes what it knows, the\nUI process reads it, and both RPCs are administrative, so a task-scoped grant\nreaches neither. That denial needs no new rule: `authorizesTaskScopedCall`\nnames three methods and denies everything else.\n\n`docs/prds/state-store-contract.md` gains the pair in its inventory, and its\nRPC count at two places moves from 45 to 47.\n\nThe read returns all records as a list, including an empty one. The\n`found=false` convention for absent single rows does not apply.\n\n## What is reported\n\nOne record per process and resource kind, replaced in place. It holds the\nprocess name, the resource kind, the version applied, the error if the process\ncould not apply it, and the time it reported.\n\nEach process re-stamps its records every 30 seconds. A record is stale once it\nis older than 90 seconds, and a stale record means the process that wrote it is\nno longer running. The report time is therefore a liveness signal, not only a\nwrite timestamp.\n\nA process reports at the point it applies a resource, so the record says what\nhappened rather than what was intended. Nothing probes.\n\nProcess names come from one shared constant naming `archied`, `archie-gateway`\nand `archie-messaging`. A deployment runs at most one of each. Writer and\nreader are bound to that constant by test, because a drifted name is\nindistinguishable from a process that never reported.\n\n## Which processes report\n\n- `archied` and `archie-gateway` apply every restart-required kind through\n `boot.runtimeConfig`, at boot and on SIGHUP.\n- `archied` also applies the live kinds it watches, and reports each update it\n applies.\n- `archie-messaging` applies channel settings at startup and reports that kind.\n\n## What can be reported, and what cannot\n\nA process reaches its apply point only after the State Store has answered it.\nAt startup, when the State Store is unreachable, the process exits or refuses\nto start and writes no record. A live watcher that loses its established\ncontrol-plane stream reports the connection failure against its last applied\nversion while it retries. Re-establishing the stream clears that outage record\nwithout clearing a versioned document rejection. A transport failure is not a\ndocument rejection; it reports that live delivery is unavailable.\n\nAbsence has two meanings and the UI never collapses them: no process applies\nthis kind, or a process that applies other kinds has not reported this one.\n\n## Relationship to the reload status\n\nApply status covers control-plane resource kinds. `ReloadStatus` covers the\nfile document and stays the only report for a SIGHUP that failed to resolve or\nvalidate it. Neither is derived from the other.\n\nWriting a record is best-effort. On the SIGHUP path it takes its own bounded\ncontext, separate from the budget the reload spends reading the control plane,\nand a failed write is logged rather than turned into a failed reload.\n\n## What the UI shows\n\nThe settings page shows, per resource, the stored version beside each process's\napplied version, error, and report time. A process on an older version of a\nrestart-required resource is pending a restart. A process with an error is\nfailed, with the error beside it. A process whose record is stale is unknown,\nnever current.\n\n## A record outlives the process that wrote it\n\nRecords are replaced in place, so a process that applies a version and then\nstops would otherwise leave a record asserting that version indefinitely, and\nthe settings page would show a dead process as current.\n`docs/prds/status-health-surface.md` faced the same choice and stamped the start\nof a poll pass so a wedged poller reads as stale rather than healthy.\n\nSettled: the re-stamp above. The alternatives considered were\ncarrying the instance identity generated at process start, which detects a\nrestart but not a death, and accepting the limitation with the page saying so.\n\n## Verification\n\n- A process that applies a resource writes a record carrying that version.\n- A process whose apply fails validation writes a record carrying the error and\n no new version.\n- A live watch outage is reported against the last applied version until the\n stream is re-established; re-establishment preserves any outstanLine truncated
},
{
"url": "/dev/prds/curator-sampler-wave1/",
"title": "Curator sampler wave 1: `Sampler` interface + four cheap strategies -- decision",
"section": "PRDs",
"body": "# Curator sampler wave 1: `Sampler` interface + four cheap strategies -- decision\n\n**Status:** Approved\n**Date:** 2026-09-05\n**Beads issue:** bead `archie-core-1786637500776-416-600a66e5` / GitHub #437\ncovers the embedding-backed follow-on strategy only. This PRD covers the\nprerequisite interface and the cheap strategies.\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n**Depends on:** nothing shipped (this is itself a prerequisite)\n**Blocks:** the embedding-backed surprisal strategy (GitHub #437), which\nimplements this same interface once the embeddings capability\n(`internal/domain/embedding`, this change) lands\n\n## Problem\n\nA future curator that reviews a large body of content (memories, sessions,\nskills) cannot always afford to run its agentic budget over every candidate\nevery pass. It needs to pick a bounded subset first. GitHub #437's acceptance\ncriteria requires that subset-picking to sit \"behind a `Sampler` interface\nthat wave 1 of the curator epic ships (cheap strategies: recency, random,\nall, staleness proxy)\" and that the embedding-backed strategy implement \"the\nsame interface\" later. No such interface, and none of the four cheap\nstrategies, exist anywhere in the codebase (bead 434e5bb9's closure\nwithout a linked PR was the tracker being wrong, not the code existing) --\nthis PRD is the one-page settled design for it, per this repo's Scope\nDiscipline rule.\n\n## Decision\n\nA `Sampler` is a pure, call-scoped selection function: given a fixed slice of\ncandidates and a request, it returns a subset. No lifecycle, no host access,\nno I/O for the four wave-1 strategies -- they are computation only, so they\nlive directly in `internal/domain/sampling` (a domain package, not\n`internal/infrastructure/*`) alongside the contract, the same way\n`curator/activity.go`'s pure ring buffer sits next to `curator/contract.go`\nrather than in an infrastructure package.\n\n```go\n// Package sampling is the curator sampler family: given a bounded set of\n// candidates, pick a subset to spend a curator pass's agentic budget on.\n// See docs/prds/curator-sampler-wave1.md.\npackage sampling\n\n// Candidate is one item eligible for sampling. It is deliberately narrow:\n// an opaque identifier, the timestamp the timestamp-based strategies score\n// against, and an open Metadata bag for whatever a future strategy needs\n// (e.g. the embedding-backed surprisal strategy's vector) without widening\n// this struct for every strategy that comes after wave 1.\ntype Candidate struct {\n ID string\n At time.Time\n Metadata map[string]any\n}\n\n// Request carries the knobs every strategy shares: a selection cap and a\n// deterministic seed. Both are optional -- Cap 0 means unlimited (the \"all\"\n// strategy relies on this), Seed 0 is a valid seed, not \"unset\".\ntype Request struct {\n Cap int\n Seed int64\n}\n\n// Sampler selects a subset of candidates to spend a curator pass's agentic\n// budget on. Every implementation -- the four here and the future\n// embedding-backed surprisal strategy (GitHub #437) -- must be\n// deterministic given the same candidates and Request: same inputs, same\n// output, every time. That is what makes a pass reproducible and testable,\n// and is GitHub #437's stated acceptance criterion for the strategy it\n// adds behind this same interface.\ntype Sampler interface {\n // Name identifies the strategy for logging/attribution (e.g.\n // \"recency\", \"random\", \"all\", \"staleness\", later \"surprisal\").\n Name() string\n // Sample selects from candidates per req. Implementations must not\n // mutate candidates or rely on anything but candidates and req --\n // determinism depends on that.\n Sample(ctx context.Context, candidates []Candidate, req Request) ([]Candidate, error)\n}\n```\n\n### The four wave-1 strategies\n\nAll four are `internal/domain/sampling` types constructed with `NewX(...)`,\neach implementing `Sampler`:\n\n- **`recency`** (`NewRecency()`): sorts candidates newest-`At`-first (stable\n sort, ties keep input order so output is deterministic even when two\n candidates share a timestamp), then truncates to `req.Cap` (0 = all).\n- **`staleness`** (`NewStaleness()`): the mirror of recency -- sorts oldest-\n `At`-first, then truncates to `req.Cap`. This is explicitly a _proxy_:\n \"hasn't been touched in the longest time\" using whatever timestamp the\n caller populated `Candidate.At` with (created, updated, or\n last-reviewed -- the caller's choice, not this package's), never the\n embedding-based surprisal calculation GitHub #437 owns.\n- **`all`** (`NewAll()`): no filtering. Returns candidates in input order,\n truncated to `req.Cap` (0 = every candidate). Input order is the only\n order this strategy has an opinion about, and preserving it is what makes\n it deterministic.\n- **`random`** (`NewRandom()`): a uniform-random subset, sized to\n `req.Cap` (0 = every canLine truncated
},
{
"url": "/dev/prds/dashboard-aware-chat-navigation/",
"title": "Dashboard-aware chat: Archie sees the page, and points the operator there",
"section": "PRDs",
"body": "# Dashboard-aware chat: Archie sees the page, and points the operator there\n\n**Status:** Approved\n**Date:** 2026-08-26\n**Compound:** the \"chat available on any page\" surface work (global chat presence)\n\n## Decision\n\nMake the web chat **dashboard-aware**: the agent is told which dashboard page\nthe operator has _open_, knows what each page is for, and can **point**\nthe operator to the relevant page with a **clickable destination chip** the UI\nrenders and follows - Option B (context + navigate), not just \"tell me in text.\"\n\nThree seams, each an existing extension point, one new tool and one message field:\n\n1. **Current page, into the prompt.** The browser sends its route with every\n chat message; the gateway threads it into the system prompt's runtime-metadata\n env block. Archie always knows where the operator is looking.\n2. **Page index.** A page_index tool lists the dashboard pages and what each one\n shows, so Archie knows what to point at - the agent \"has the map\".\n3. **Navigate.** A dashboard_navigate tool returns a structured path/label; the web\n UI renders it as a clickable chip that routes the operator there. This is the\n \"plenty of resources\" the requirement named.\n\nWe deliberately keep the agent's answer honest: the chip is _evidence_ it can\nvalidly produce because dashboard_navigate is a real tool whose result is\nrendered, not a markdown link the model invents.\n\n## Why now\n\nThis is the natural next step of the \"chat on any page\" work, and the original\nrequest named it explicitly: _\"archie should be able to see what page you're on\ntoo. and point out where to go. so it needs plenty of resources.\"_ The chat\nis a full-page route with no knowledge of the rest of the dashboard; the agent\ncannot see which page the operator is on and cannot reliably direct them anywhere.\nThe critique of the chat UI already identified \"chat is not available on any page\"\nas the largest structural gap (P1). This design is the capability that makes that\ngap worth closing.\n\n## Shape of the API\n\n### Message field (gateway.go)\n\nAdd Page to Message:\n\n```go\n// Page is the dashboard route the operator is on when they sent this message\n// (e.g. \"/tasks\", \"/logs\"). Empty for non-web channels, which have no page\n// context. It is per-message, not per-session: the operator navigates freely\n// while a conversation stays open.\nPage string\n```\n\n### Web request (api_chat.go)\n\nchatMessageRequest gains Page, decoded into Message.Page in decodeChatMessage.\n\n### System prompt config (prompt.go)\n\nSystemPromptConfig gains Page; BuildSystemPrompt passes it through to the template.\nThe env block of archie.md.tpl renders the current page when set.\n\n### Page index (dashboard_tools.go, new)\n\nA package-level registry mapping route to {Label, Description}. page_index returns\nthe list so the model knows what each page shows:\n\n```go\ntype DashboardPage struct {\n\tPath string // \"/tasks\"\n\tLabel string // \"Tasks\"\n\tDescription string // \"Issues Archie picked up, and where they stand.\"\n}\n```\n\n### Navigation tool (dashboard_tools.go)\n\ndashboard_navigate validates its path against the registry and returns the resolved\npath/label. Unknown path means a clear error, not a guess. The model must call the\ntool (not invent a link) to produce a chip, so the chip is honest.\n\n### Tool wiring (turn.go)\n\nextraTools already merges TaskTools + SessionTools. Add the dashboard tools alongside\nthem, gated on the channel being the web UI. The tool list is built from the same\nregistry the prompt's page line comes from, so the agent never points at a page it\nwas not told about.\n\n### Web UI (chat-render.js, chat-tools.js)\n\nA dashboard_navigate tool call renders as a **clickable chip**: an anchor with\nhref=\"/tasks\" and the label. The chip is a\nreal link that works from any page once the chat is a global presence. The chip is\nstyled as an action, not a code line, so it visibly invites a click.\n\n### Route transfer (chat.js)\n\nEach sendMessage includes the current location.hash route as page in the stream\nrequest body, so the backend gets the operator's live position.\n\n## What we deliberately do NOT do\n\n- **No navigation from a markdown link.** The model must use dashboard_navigate; a\n bare \"click here\" is not rendered as a trusted route.\n- **No full-page route hijack from the chat.** The chip sets location.hash.\n- **No page index for non-web channels.** Telegram/discord have no dashboard.\n- **No automatic history annotation.** Page is per-message from the browser.\n- **No change to the dangerous-action approval flow.** Separately tracked.\n\n## Acceptance criteria\n\n1. Chat messages from any page carry the current page to the agent's prompt.\n2. page_index returns every dashboard page with a plain-language description.\n3. dashboard_navigate renders a clickable chip that routes to the target page.\n4. dashboard_navLine truncated
},
{
"url": "/dev/prds/dashboard-live-state/",
"title": "Dashboard live state",
"section": "PRDs",
"body": "# Dashboard live state\n\n**Status:** Approved\n\n## Decision\n\nThe dashboard must not require passive **Refresh** buttons. One app-wide Pinia\nstore owns the existing `/api/stream` EventSource and translates backend events\ninto resource revision counters. Pages load their authoritative HTTP projection\non entry and re-read it when the relevant revision changes. Event payloads are\ninvalidation signals, not substitute read models.\n\nSSE remains the transport. Dashboard updates are server-to-client only, and the\nexisting stream already provides replay, reconnect, and persisted ordering; a\nWebSocket would add a second transport without adding a capability.\n\nThe first slice covers resources for which the backend already emits a truthful\nsignal:\n\n- task events invalidate the dashboard, task board, workflow statistics, and\n the matching task-run page;\n- capture events invalidate the capture list;\n- curator events invalidate curator status, and curator actions also invalidate\n the skill catalogue;\n- update reports invalidate System status;\n- opening a page always loads its resource, and reopening the SSE stream\n invalidates mounted projections after a connection loss.\n\nLogs retain their dedicated SSE tail. Local mutations continue to re-read their\nown resource after success. Configuration, channels, and catalogues that have no\nbackend change event load on route entry; future write contracts must emit an\nowner-specific event rather than introduce polling or restore a button.\n\n## Boundaries\n\nThe Pinia store owns browser connection state and invalidation only. It does not\nbecome an alternate backend cache or copy domain state into a generic global\nobject. Existing feature modules continue to own their DTOs and API reads.\n\nOperational commands are not refresh controls. Channel **Reload** remains an\nexplicit adapter lifecycle action. Authentication recovery is also not a data\nrefresh: a 401 moves the application into shared authentication state; reloading\nthe same URL cannot restore Archie's missing or rotated token and must not be\noffered as a fix.\n\n## Verification\n\n- No passive page action renders the label **Refresh** or **Retry** for a read.\n- Only one shared `/api/stream` EventSource is opened by the application.\n- Resource classification tests distinguish task, capture, curator, skill, and\n update invalidations.\n- UI tests, type checking, generated asset freshness, and `task check` pass.\n"
},
{
"url": "/dev/prds/dashboard-port-brief/",
"title": "Dashboard port: what the agent delivers",
"section": "PRDs",
"body": "# Dashboard port: what the agent delivers\n\n**Status:** Approved\n**Date:** 2026-09-20\n**Beads:** `archie-core-tavn` (epic), `archie-core-ocfm` (navigation)\n**Reads with:** `docs/prds/vue-migration-checklist.md` (the item-by-item)\n\nThis is the standard the port is held to. The checklist says what to port; this\nsays how, and what counts as done. It exists because the first attempt ported\nthe flat topbar verbatim and invented a palette, both of which had already been\ndecided elsewhere.\n\n## The deliverable\n\nThe Preact dashboard, rebuilt in Vue 3 with shadcn-vue, feature complete\nagainst the checklist, gate clean, with `ui/dist` rebuilt and committed in the\nsame commit as the source it was built from.\n\n## Non-negotiables\n\n- **Vue 3 + shadcn-vue (Reka UI, Tailwind v4, Lucide).** A component that\n exists in shadcn-vue is not hand-rolled. Add it with the CLI\n (`npx shadcn-vue@latest add \u003cname\u003e`), do not paste it in.\n- **History routing.** `createWebHistory`, `base: \"/\"`. No hash routing.\n `src/legacy-hash-redirect.ts` handles old `#/path` links and stays.\n- **No test port.** 43 Preact test files are deliberately dropped.\n `task test:ui` is a `vue-tsc` typecheck. Write a test when there is a real\n failure to pin, not to re-assert a port.\n- **Do not downgrade TypeScript.** The target is TS 7 native, not TS 5.\n- **`ui/dist` is law.** Never hand-edit it, never omit it, never revert it.\n- **`task check` is the gate.** Not an assembled substitute for it.\n- **Beads, not markdown TODOs**, for anything that outlives the change.\n- **Conventional commits**, scoped `feat(webui):`. Commit gate-clean work\n without asking. Do not push without being told.\n\n## Componentisation\n\nOne component, one job, one file. A surface is composed from named components,\nnot assembled inside a single large file. The topbar is the worked example and\nthe required shape:\n\n```\ncomponents/topbar/\n Topbar.vue composes the header, owns nothing else\n Brand.vue Logo + BrandName, links to /\n Logo.vue\n BrandName.vue\n Nav.vue reads the nav model, renders links and groups\n NavTrigger.vue the shared top-level control, link or dropdown trigger\n NavGroup.vue one dropdown\n NavItem.vue one item inside a dropdown, with its tooltip\n SearchBar.vue\n SupportLink.vue\n ThemeToggle.vue\n ProfileDropdown.vue\n```\n\nThe same rule applies to every page ported after it. If a file is doing the\nwork of four named things, it is four files. Data and behaviour that more than\none component needs lives in `src/lib/`, not passed down through a chain of\nprops.\n\n## Ordering\n\nBuild the navigation restructure during the port, not after it. Porting the\nflat eleven-item bar first and restructuring later means writing the topbar\ntwice and touching the Go route registry twice. The approved design is five\ntop-level items (Dashboard, Work, Agent, Events, System), items renamed because\ntheir group carries the context, per-item descriptions shown as hover tooltips,\nConfiguration split into `/system/*`, `/settings` kept as a redirect, and Logs\nfinally given a nav entry.\n\n## Design authority\n\n- The approved documents win. Where a document decides something, implement it\n rather than re-deciding it.\n- **Do not invent a visual direction.** Palette, typography and density are the\n maintainer's call. A palette change is its own request, never a side effect\n of a port.\n- Contrast is AA against every surface the foreground lands on, hover states\n included. The corrected values (`--fg-subtle`, the dark\n `--primary-foreground`) came from a measured failure and must survive.\n- `color-scheme` follows the theme so the UA paints controls, scrollbars and\n overscroll to match.\n\n## Code style\n\nComment the non-obvious why: an invariant, a trap, a measurement, a contract\nanother file depends on. Do not narrate what the code plainly does, do not\nexplain a choice that was never in question, and do not write migration phase\nhistory into a diff. That history belongs in the commit message.\n\n## Done, per surface\n\n1. Renders with real data against `task dev`, not just typechecks.\n2. Keyboard reachable, focus visible, and the nav announces where you are.\n3. Works at 1440x900 and at 720px wide, with nothing clipped and no horizontal\n page scroll.\n4. Empty, loading, failed and unconfigured (501) states all say something true.\n A section that cannot load says so; it does not render blank.\n5. `task check` passes, `ui/dist` rebuilt, committed together.\n"
},
{
"url": "/dev/prds/dashboard-vocabulary/",
"title": "One source for the dashboard's server vocabularies",
"section": "PRDs",
"body": "# One source for the dashboard's server vocabularies\n\n**Status:** Finalised\n\n## Problem\n\nThe dashboard kept its own copies of two vocabularies the daemon owns:\n\n- the changed-file statuses (`added`, `modified`, `deleted`, `renamed`,\n `typechange`), which are the `Change*` constants in\n `internal/domain/workflow/task`;\n- the schema stamp on a `config_captured` payload, `events.ConfigCapturedSchema`.\n\nNothing derived one side from the other, while `/api/task-meta` already served\nthe status and action vocabularies for exactly this reason.\n\n## Decision\n\n`GET /api/task-meta` also serves `change_statuses` (id and label) and\n`config_schema`. `buildTaskMeta` in `internal/webui/api_task_meta.go` takes the\nids from the `Change*` constants and the stamp from `events.ConfigCapturedSchema`.\n\nThe dashboard renders `ui/src/lib/task-meta-snapshot.ts` until the served\ncatalogue arrives, or when archied is unreachable. `loadTaskMeta` replaces only\nthe keys the payload carries, so a server without the new keys leaves the\nsnapshot in place. `changeStatusLabel` and `configSchema` in\n`ui/src/lib/task-meta.ts` are the only readers; an unknown status renders as\nits id.\n\n## Verification\n\n- `TestTaskMetaChangeStatusesAreDeliberate` fails when a `Change*` constant is\n added without a label.\n\nA rename on one side therefore fails a test on the other.\n\n## Rejected\n\nDeleting `/api/task-meta` and accepting hand-copied constants. The endpoint is\nlive, and deleting it would still leave the two copies this document removes.\n"
},
{
"url": "/dev/prds/deep-research-capability/",
"title": "Deep research capability — design",
"section": "PRDs",
"body": "# Deep research capability — design\n\n**Status:** Draft\n**Date:** 2026-09-14\n**Scope:** A deep-research capability in archie-core: an orchestrator that\nspawns 1..N subagents to explore and research in parallel, collates their\nfindings, and returns one cited report. Grounded in web search and web fetch.\n**Beads issue:** none yet (this document is the input to it)\n**Depends on:** nothing shipped for slice 1; slice 2 depends on slice 1.\n\n## §0 Implementation status\n\nEvery claim in this document is mapped to what exists in the tree.\n\n| Claim | Status | Where it stands |\n| ---------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `web_fetch` tool (URL → readable text) | **Implemented** | `internal/tools/webfetch/{tool.go,webfetch.go}`; registered in `internal/app/archied/bootstrap.go` `registerStandaloneTools`, disabled-by-config returns `nil` |\n| **Web search** (query → result list) | **Aspirational — zero code** | No search provider, no search tool, no config block anywhere in the tree or in `ai-sdk` v0.1.32 |\n| `agent.Subagent` — nested agent in a fresh context window | **Implemented** (dependency) | `github.com/samcharles93/ai-sdk@v0.1.32/agent/subagent.go`. Synchronous, non-streaming, own model/system/toolset, `MaxSteps` defaults to 10, nesting depth capped at 5, returns final text only |\n| Subagent used in production | **Implemented, one consumer** | `internal/app/agentworker/review.go` — the adversarial reviewer. That is the only non-test use of `Subagent` in the repo |\n| A **delegate/subagent tool** on the chat surface | **Aspirational — zero code** | No `subagent`/`delegate` tool name is registered anywhere |\n| **Fan-out orchestration** (N missions, one collator) | **Aspirational — zero code** | `agentloop`'s package doc states it runs _one_ mission: \"orchestration across missions lives with the caller\". No caller does this yet |\n| Parallel-safe tool execution | **Aspirational — zero code** | The unreachable `internal/tools/dispatch.go` dispatch/gating engine (`ExecutionClass`, `DispatchSequential`/`DispatchConcurrent`/`ClassifyEntry`) was deleted as dead code (tools-core-1); live concurrency is ai-sdk's `GenerateOptions.MaxParallelToolCalls`, which archie-core never sets |\n| Per-result caps + spill-to-disk | **Implemented** Line truncated
},
{
"url": "/dev/prds/dynamic-curators/",
"title": "Dynamically-defined curators -- decision",
"section": "PRDs",
"body": "# Dynamically-defined curators -- decision\n\n**Status:** Approved\n**Date:** 2026-09-12\n**GitHub epic:** [#789](https://github.com/samcharles93/archie-core/issues/789)\n**Parent epic (curator engine):** [#435](https://github.com/samcharles93/archie-core/issues/435) (closed)\n**Depends on:** nothing shipping; this resolves the open question that epic #435's\n\"registered and configured declaratively, not hardcoded\" criterion left open.\n\n## §0 Implementation status\n\nEvery claim in this document is mapped to what exists in the tree.\n\n| Claim | Status | Where it stands |\n| --------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Curator engine family: typed contract, owning registry, start/health/stop, narrow host access | **Implemented** | `internal/domain/curator/{contract,registry,runtime,registrar,activity,wake}.go` |\n| Curator declared shape (`Manifest`: interval, cooldown, on_input, tools, skills, memory engine, conversations, model) | **Implemented** | `internal/domain/curator/contract.go`; `Validate()` requires `Interval \u003e 0` |\n| Two reference curators run through the registry | **Implemented** | `internal/infrastructure/skillcurator`, `internal/infrastructure/sessioncurator` |\n| Curator definitions as persisted, API-editable data | **Aspirational -- zero code** | No table, no entity, no RPC, no config block |\n| Generic definition-driven engine that executes a declared tool set + free-form instructions | **Aspirational -- zero code** | Only the two code-registered curators exist |\n| `Registrar.Tools` (`ToolBuilder`) resolved and bound at registration | **Partial** | Interface declared (`registrar.go`); **no implementation anywhere**; `bootstrap.go` builds the `Registrar` with no `Tools` field |\n| A curator can declare tools at all | **Partial** | `Manifest.Tools` exists, but `registry.go` fails registration with `\"curator manifest: declares tools but the registrar has no ToolBuilder\"` |\n| Curator passes that actually reach a model with tools | **Cosmetic only** | `curator.ChatRequest` carries `Tools`/`MaxSteps`; `curatorLLMRunner` (`internal/app/archied/main.go`) drops both and returns `ChatResult{Text}` only |\n| Dynamic registration / removal (no restart) | **Aspirational -- zero code** | `Registry` has `Register`, no `Unregister`; `Runtime` has `Start`/`Nudge`/`Stop`, no `Add`/`Remove`; `Start()` snapshots membership |\n| Curator definition CRUD over REST | **Partial** | `GET /api/curators` read-only (`internal/webui/server.go`); no write routes |\n| Curator definition config | **Aspirational -- zero code** | No `[curator]` block in `intLine truncated
},
{
"url": "/dev/prds/dynamic-workflow-triage/",
"title": "Dynamic workflow triage",
"section": "PRDs",
"body": "# Dynamic workflow triage\n\n**Status:** Finalised\n\nEpic: archie-core-enfj. Scope: give `workflow.Route()` a real, content-aware\nfallback instead of unconditionally defaulting every unlabelled task to the\nheaviest workflow.\n\n## Problem\n\n`Route()` (`internal/domain/workflow/workflow.go`) has exactly two real\nsignals: an explicit `t.Workflow`, and label matches via\n`workflowForLabels` (`routing.go`, `bug`→tdd, `feature`→feasibility,\nbootstrap→bootstrap). Anything else — which is every chat-spawned task,\nsince `task_spawn` rarely sets labels — falls straight through to\n`reg[\"implement\"]`, the full `prepare → baseline → plan → build →\ncommit-push → review → open-pr` pipeline, regardless of what the task\nactually asks for.\n\n`task_spawn`'s own tool schema overpromises: _\"workflow: … Omit to let the\ndaemon route it\"_ (`internal/gateway/task_tools.go`) implies real\nrouting exists. It doesn't — \"route\" means \"check labels, then\ngive up and run the heaviest workflow anyway.\"\n\nConfirmed in production: a chat-spawned task whose\nentire content was \"this is just a test, close it when you receive it\" ran\nthe full `implement` pipeline end to end — 669,421 tokens, ~7 minutes —\nwhen nothing about the request needed a worktree-driven build at all. The\n`plan` stage's own LLM output _correctly_ concluded no code change was\nneeded, but that conclusion arrives two expensive stages (`baseline`,\n`plan`) too late to save anything.\n\n## Decision\n\nAdd a **`triage` workflow**: cheap, classifies once, then either closes the\ntask immediately or hands off to the workflow the task actually needs.\n`Route()`'s final fallback (`reg[\"implement\"]`) becomes\n`reg[\"triage\"]` when a `triage` entry is registered, else the existing\n`implement` fallback — a two-line change, fully backward compatible when\n`triage` isn't wired up.\n\nTriage does **not** replace label-based routing. A labelled task\n(`bug`/`feature`/bootstrap) already has a free, reliable signal and goes\nstraight to its known workflow unchanged — spending a classification\ncall there would be pure waste. Triage only fires in the gap that\ndefaults to `implement` blindly: no explicit workflow, no label match.\n\n### Triage workflow shape\n\n```\nStagePrepareWorktree() -- still needed: AgentStage mounts tc.Dir into the\n agent container: internal/domain/workflow/agent.go:74\n passes tc.Dir straight through. No cheaper\n primitive exists in this codebase for a\n directory-less classification call.\nAgentStage \"classify\" -- ReadOnly, ONE cheap agent turn, no exploration\n tools required beyond what ReadOnly already\n grants. Mirrors feasibility.go's decideCaptureTools\n pattern: a structured capture tool, called\n exactly once, MaxCalls: 1.\n```\n\nMission: read the task's title/body/labels (already in `taskPromptBlock`)\nand decide, via a captured `decide` tool call:\n\n```json\n{\"needs_code_change\": bool, \"workflow\": \"implement\" | \"tdd\" | \"feasibility\", \"reasons\": \"...\"}\n```\n\n`needs_code_change: false` → close path: reuse `closeNoChangesIssue`\n(`steps.go`) directly — issue closed if forge-backed, task marked\n`StatusMerged`/`\"completed -- no changes required\"` otherwise. No baseline,\nno plan, no build, no commit, no PR. This is the actual fix for the\nproduction incident: a no-op request now costs one classification call\n(low thousands of tokens) instead of 669,421.\n\n`needs_code_change: true` → sets `tc.Task.Workflow` to the classifier's\nchosen workflow (`implement`/`tdd`/`feasibility`, defaulting to\n`implement` if the field is missing or unrecognised) and an Outcome that\nrequeues the task under it, the same requeue mechanism\n`chatTaskControllerAdapter.ApproveChatTask` already uses\n(`main.go`, `requeue(ctx, taskID, fromStatus, workflow)`). The task then\nre-enters `Route()` on its next claim with `t.Workflow` now set, and takes\nthe normal path for that workflow from there — triage never runs its\nclassification twice for the same task.\n\n### Non-goals (v1)\n\n- Full bug/feature intent classification quality — the classifier only\n needs to be _directionally_ right; a wrong `tdd` vs `implement` call\n still produces a working PR, just via a slightly less-tailored pipeline.\n Tightening this is a follow-up, not a blocker.\n- Any change to label-based routing, `Route()`'s explicit-workflow branch,\n or `Bootstrap()`/`Feasibility()`/`TDD()` themselves.\n- Triage for forge-sourced (real GitHub issue) tasks with no labels —\n in scope structurally (same fallback branch), but the dominant case this\n fixes is chat-spawned tasks, which essentially never carry labels.\n\n## Testing\n\n- `workflow_test.go`: `Route()` picks `rLine truncated
},
{
"url": "/dev/prds/eda-playbook-engine/",
"title": "EDA playbook engine -- design",
"section": "PRDs",
"body": "# EDA playbook engine -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Beads epic:** `archie-core-t2db`\n\n## Problem\n\n\"Which workflow runs for which trigger\" is hardcoded Go: a literal\nlabel vocabulary (`workintake.labelKinds`) and a literal label-\u003eworkflow map\n(`workflow/routing.go`), extended only by adding a Go case or shipping a\nskill whose `metadata.archie.workflow` overrides one _named_ built-in\nworkflow. Extending the system to a new trigger, a new action, or a new\nevent source means a feature branch, a code change in a hardcoded\npath, and new Go tests -- for every addition. That is the barrier this\ndocument exists to remove.\n\nThe goal: triggers, the actions they run, and the\nconditions that connect them should be **drop-in and load**, not **drop-in\nand touch application code**. Yaegi-evaluated Go is the unit of imperative\n\"do a thing\" logic; YAML playbooks are pure orchestration data -- no logic,\njust \"on this event, with this data, call these actions, in this order,\nunder these conditions.\" The daemon's event coordinator doesn't know what a\n`bugfix` or `image-gen` action does, it resolves the name against a\nregistry and pipes typed data through.\n\nThis is explicitly **not** scoped to code-generation workflows. A playbook\naction can be any registered capability -- run a codegen workflow, send a\nmessage on a channel, open something on a forge, generate an image -- so\nlong as it's implemented behind one of the typed engine families below.\n\n## Relationship to existing decisions\n\n- `docs/prds/event-sources-and-reactions.md` ruled\n that reactions in the two epics it covers are **producer-only** (no veto,\n no mutation of in-flight work) and explicitly rejected a single generic\n `Source` interface as \"the untyped-hook shape the plugin engine rule\n exists to prevent.\" **This document extends that scope**: playbooks can\n dispatch to multiple typed action kinds, not just \"produce a\n `TaskEnvelope`.\" It does not relitigate producer-only-ness (still no\n veto/mutation of in-flight work here) and it does not introduce one\n generic interface -- see \"Typed positions, not one generic hook\" below,\n which is how it stays compliant with the plugin engine rule instead of\n reopening that document's #4.\n- `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`\n governs every extension point\n introduced here. Every position below is a typed domain contract with an\n owning registry, not a generic callback map. This is a hard constraint,\n confirmed against the existing rule text before writing this doc.\n- Yaegi is already a proven in-process extension mechanism\n (`internal/plugin`, `internal/domain/workflow/wfeval/yaegi.go`,\n `internal/gate/gateeval/yaegi.go`, `internal/skill/plugin.go`) -- this\n design generalises its existing role, it does not introduce a new\n execution mechanism.\n- `internal/domain/workflow/skillbuild.BuildRegistry` already composes a\n `workflow.Registry` from a skills catalogue, plugin-defined overriding\n built-in. The playbook loader described here supersedes label routing\n specifically; it does not replace `skillbuild`'s workflow-composition role,\n it becomes an additional input the daemon composes at startup.\n- Webhook event intake is a separate design. This\n document defines the router each webhook-sourced event should be able to\n reach; it does not redesign webhook receipt itself.\n\n## Shape: four logic positions, each a typed engine family\n\nEvery entrypoint kind (mechanism, action, loop, schedule, route, trigger) is itself a schema emitter: defining a new kind produces the\ngenerated contract downstream tooling consumes. The kinds slot into a fixed\nhierarchy of logic positions:\n\n```\nWorkflow -\u003e Module -\u003e Channel (telegram/whatsapp/email/...)\n -\u003e Forge (GitHub/Gitea/GitLab/...)\n```\n\nEach position is its own typed engine family per the plugin engine rule:\nidentity + capability-specific operations, an owning `Registry`/`Manager`,\nexplicit lifecycle where the implementation owns resources, narrow host\naccess. Concretely:\n\n- **Workflow** -- already exists (`internal/domain/workflow`). A playbook\n action of kind `workflow` invokes a registered `workflow.Registry` entry\n by name, unchanged from the existing execution path.\n- **Module** -- the new general-purpose action position. A `Module` is a\n Yaegi-evaluated implementation of a generated interface (args in, typed\n result out) for one declared action kind (e.g. `image-gen`, `notify`,\n `open-pr-comment`). This is the position that makes actions \"not\n restricted to code-generation.\" Full design (schema-per-kind, the\n registry shape, the trust boundary, the recommended first slice):\n `docs/prds/module-position.md`.\n- **Channel** -- already exists as `channels.Channel` (telegram, email,\n webhook). A playbook action of kind `channel` sends througLine truncated
},
{
"url": "/dev/prds/embedded-nats/",
"title": "Embedded NATS execution -- decision",
"section": "PRDs",
"body": "# Embedded NATS execution -- decision\n\n**Status:** Finalised\n\n**Date:** 2026-08-24\n\n**Beads epic:** `archie-core-q15y`\n\nThis decision supersedes the position that embedded NATS was only a\ndistribution mechanism and could not be an agent-execution topology. That was\ntrue only because the embedded listener was unauthenticated loopback. It left a\nsecond production architecture in which `archied` ran autonomous workflows in\nits own process, weakening the isolation boundary that managed task containers\nexist to provide.\n\n## One execution architecture, two broker deployments\n\nEvery autonomous repository workflow is handed over as one complete task via\nNATS and runs in a task-scoped `archie-agent` container. `archied` remains a\nnative, long-lived orchestration and interactive-chat process; its operator\nconfigured host filesystem access is unchanged. It owns task admission,\nstate, forge and worktree operations, container lifecycle, and the broker when\nthe embedded deployment is selected. It does not run an autonomous model loop.\n\nNATS has two supported deployment shapes:\n\n| mode | meaning |\n| ---------- | --------------------------------------------------------- |\n| `embedded` | `archied` owns an in-process JetStream server (default). |\n| `external` | `archied` and workers connect to the configured NATS URL. |\n\nBoth shapes have identical task semantics: one container and one full-task\nrequest per workflow. Broker placement must not select a different executor.\nThe legacy `agent` section and `containers.enabled` key remain decode-only\nmigration inputs. `nats.mode = \"off\"`, per-stage NATS, in-process execution,\nand subprocess execution are not production choices.\n\nSQLite remains authoritative for task state. NATS is the sole autonomous work\nhandoff. SQLite recovery may identify work that needs republishing, but it must\nnot cause `archied` to call `workflow.Run` locally.\n\n## Embedded reachability and authentication\n\nAn embedded listener uses a cryptographically random bearer token generated for\neach daemon start. The token exists only in process memory and the environment\nof managed worker containers; it is never written to config or logs.\n\nFor a native daemon with managed containers, startup resolves the Docker bridge\nthe workers will join. The listener binds only to that bridge's host gateway\naddress on a random port. Both the native daemon and workers use that same\nreachable endpoint, and every client supplies the generated token. Binding a\nDocker bridge address keeps the listener off ordinary LAN interfaces without\npublishing a host port. A configured user bridge is respected; otherwise the\nDocker default bridge is used. A network without a usable local IPv4 gateway is\na startup error for autonomous execution.\n\nIf Docker is unavailable, interactive chat may still start and embedded NATS\nmay remain loopback-only, but autonomous tasks park with an explicit container\ncapability failure. They never fall back to host execution.\n\n## Ownership and lifecycle\n\n- `internal/infrastructure/eventbus/nats` owns the authenticated embedded\n server and exposes its runtime endpoint, not the server implementation.\n- `internal/container` resolves the worker bridge and gateway and owns task\n container lifecycle.\n- `internal/app` composition selects embedded or external broker deployment,\n freezes the connected runtime endpoint for worker environments, and wires the\n full-task handoff.\n- `cmd/archied` remains process input only as the domain migration reaches this\n composition path.\n\nThe daemon starts the embedded server before its client, closes clients before\nthe server, and keeps JetStream data beneath the daemon data directory. NATS URL\nand token are startup-built values: a reload cannot send new workers to a broker\ndifferent from the one the daemon is using.\n"
},
{
"url": "/dev/prds/event-automation/",
"title": "Event automation: identified events, typed parameters, purpose-built agents",
"section": "PRDs",
"body": "# Event automation: identified events, typed parameters, purpose-built agents\n\n**Status:** Approved\n**Date:** 2026-09-23\n**Parent:** epic `archie-core-t2db`\n\n## Why this exists\n\nArchie is an event-driven automation system. Any system that can send a\nwebhook (a forge, an error tracker, a firewall, a monitoring stack) should be\nable to start an agent built for that job. The shape this replaces cannot:\n\n- A binding matches only the URL segment an event was posted to, and a source\n may have one binding. Two kinds of event from one sender cannot go to\n different workflows.\n- A mapping is a list of JSON paths written against one example payload.\n Nothing recognises what kind of event arrived.\n- Mapped values reach the task only as `key=value` lines in its body text.\n- Every task needs a repository and runs in a git worktree.\n- Every agent runs the same image with the same forwarded keys.\n\n## The model\n\n```\nsource ─▶ event type ─▶ mapping ─▶ binding ─▶ workflow ─▶ agent profile\n (identified) (params) (+ filter, (inputs, (image, tools)\n repo) profile)\n```\n\n### Sources\n\nA source is the endpoint one sender posts to. Its path is a generated UUIDv7\n(`/webhooks/capture/0199…`), so an endpoint cannot be guessed or collide. The\noperator may replace it with a custom path for a sender that cannot use that\nformat; a custom path must be unique and URL-safe, and is refused otherwise.\nA source owns the signing setting:\n\n- **Signed** (default). Archie generates the secret. Only events with a valid\n `X-Hub-Signature-256` or `X-Signature-256` HMAC are dispatched.\n- **Unsigned.** The operator turns signing off for a sender that cannot sign.\n The source and every event from it are marked unsigned in the inspector,\n the binding list and the task timeline. Turning signing off needs the same\n approval as arming a binding.\n\nUnauthenticated events on a signed source are captured and never\ndispatched.\n\n### Event types\n\nAn event type is a named kind of event from one source, such as\n`github / pull_request.opened` or `firewall / blocked_connection`. It is\ndefined by a match rule:\n\n- header equality (`X-GitHub-Event = pull_request`), and\n- payload conditions (`action = \"opened\"`, or a path being present).\n\nAn event type can be created two ways:\n\n- **From an example payload.** The operator pastes a payload (and optionally\n its headers), and archie converts it to the type's schema. No event needs to\n have arrived.\n- **From captures.** Archie proposes types from what has arrived, as below.\n\nEither way, archie infers the schema, not the operator:\n\n- Each capture gets a structural signature: the set of JSON paths with their\n value types, plus the headers that look like discriminators (`*-Event`,\n `*-Type`, `Content-Type`).\n- Captures from one source that share a signature are grouped. The inspector\n shows each group as a proposed event type, with its inferred schema, its\n number of events and a sample, until the operator names it or dismisses it.\n- The proposed match rule is the set of discriminators that separates the\n group from its siblings. The operator can edit it before saving.\n- A capture that matches no named type is shown as unidentified. It is never\n dispatched.\n\nTwo event types on one source whose rules can match the same event are\nrefused when the second one is saved.\n\n### Mappings\n\nA mapping belongs to an event type. It maps payload paths to named, typed\nparameters, and it is checked against the type's inferred schema, so a path\nthe type does not have is refused when the mapping is saved. Any number of\nbindings may reuse one mapping.\n\nEach mapping shows how many events it has matched, with the time of the most\nrecent, so an operator can see which mappings are live and which have never\nfired.\n\n### Workflows declare inputs\n\nA workflow definition declares its inputs:\n\n```yaml\nid: firewall-investigate\ninputs:\n src_ip: { type: string, required: true }\n severity: { type: string }\nrepository: none # none | optional | required\nprofile: network-investigator\nsteps: ...\n```\n\n- `repository: none` runs the agent in a scratch workspace with no clone.\n `required`, the default, gives the agent a worktree of the task's\n repository. `optional` gives it a worktree when the binding names a\n repository and a scratch workspace when it does not.\n- A workflow whose `repository` is not `required` may use only steps that need\n no repository. `agent.run` is one: it runs one agent mission and finishes\n the task as done, with no pull request.\n- The declared inputs reach the agent as structured data in the task brief\n and in the agent's context. They are not body text.\n- A workflow may declare `outputs`, the structured result it returns when it\n finishes.\n\n### Workflows call workflows\n\nA workflow step can call another workflow.Line truncated
},
{
"url": "/dev/prds/event-capture-storage/",
"title": "Event capture storage -- decision",
"section": "PRDs",
"body": "# Event capture storage -- decision\n\n**Status:** Finalised\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.1`\n\n`webhook-intake-security.md` decided points 1-5 (auth split, approval gate,\nrate limits, blast radius, retention/redaction) and explicitly left the\nstorage mechanism open, forward-pointing at \"`7d5u.2`, embedded NATS.\" That\npointer predates `7d5u.3`'s 2026-08-22 narrowing, which assigned capture\nstorage to this bead by name and told it to decide NATS-vs-SQLite itself\nrather than inherit an answer. This document is that decision.\n\n## Decision: SQLite, not NATS JetStream\n\nCaptured events are stored in archied's existing SQLite database, in a new\n`captured_events` table following the same shape as `internal/store/events.go`\n(`internal/store`, `*Store`, SQL migrations inline in Go). No JetStream\nstream is introduced for capture.\n\n### Why\n\n**NATS availability does not make capture a broker concern.** NATS is now\nunconditional for autonomous workflow handoff, including embedded mode, but\ncapture is also used by deployments with no repository workflow configured.\nSQLite is guaranteed present because it backs daemon state, and keeps\ncapture inspection independent of broker retention and consumer lifecycle.\nThe original version of this decision cited optional NATS as an additional\nreason; that premise was superseded by `archie-core-q15y`, while the storage\nfit and independence arguments remain.\n\n**Capture's access pattern doesn't need what JetStream is for.** JetStream\nearns its complexity for reaction delivery (`7d5u.2`) because multiple\nindependent consumers need fan-out, at-least-once redelivery, and Ack/Nak\nsemantics -- exactly the trap `CLAUDE.md` documents about `WorkQueuePolicy`\nand overlapping consumers. Capture has exactly one writer (the HTTP handler)\nand one reader (a human via the dashboard inspector, `t2db.2`). There is no\ncompeting-consumer problem to solve and no redelivery semantics to get right,\nso JetStream's core value proposition doesn't apply here. A bounded SQL\ntable is a better fit on the merits, not merely as a fallback.\n\n**Reusing `7d5u.2`'s stream, once it exists, would still be wrong.** That\nstream is provisioned for fan-out reaction delivery with its own retention\npolicy decision. Capture's retention need -- age- and count-bounded, prune\non write, no replay -- is a different shape. Building a second stream just\nfor capture, gated on an unrelated bead landing first, would trade a small\namount of duplication now for a hard dependency on `7d5u.2`'s timeline that\nthis bead's own acceptance criteria say not to accrue by accident.\n\nThis does not foreclose NATS later. If cross-daemon capture sharing or\ndurable replay becomes a real requirement, that is a new decision made\nagainst a real need, not now against a speculative one.\n\n## Storage shape\n\n`captured_events` table (`internal/store/captures.go`, mirrors\n`internal/store/events.go`'s pattern):\n\n| column | type | notes |\n| ------------- | ------- | ------------------------------------------------------------------ |\n| id | INTEGER | primary key, autoincrement |\n| received_at | TEXT | RFC3339Nano |\n| source | TEXT | opaque path segment chosen by the sender's operator |\n| remote_addr | TEXT | `RemoteAddr` at capture time |\n| content_type | TEXT | `Content-Type` header |\n| headers | TEXT | JSON, redacted |\n| body | TEXT | JSON, redacted (`webhookguard.RedactPayload`) |\n| authenticated | INTEGER | 0/1; always 0 until a source registers a secret (future: `t2db.4`) |\n\nIndexed on `(source, id)` for per-source listing and pruning, and `id` alone\nfor the global cap.\n\n## Disk-bound mechanics\n\nThree independent bounds, composed, per `webhook-intake-security.md` point 5\nand this bead's own \"capture cannot exhaust disk\" criterion:\n\n1. **Per-request size cap.** The HTTP handler reads the body through\n `http.MaxBytesReader` (256 KiB default, configurable). A single oversized\n POST is rejected (413) before redaction or storage sees it.\n2. **Per-remote-address rate limit.** `webhookguard.RateLimiter`, keyed by\n the request's remote address, applied before the body is even read.\n _Not_ keyed by the `source` path segment: `RateLimiter`'s own doc comment\n states its bucket map assumes a bounded, operator-registered key space,\n never evicted. `source` is exactly the opposite here -- an unregistered,\n attacker-chosen URL segment, since capturing senders with no registration\n yet is this endpoint's entire purpose. Keying on it would let one sendLine truncated
},
{
"url": "/dev/prds/event-sources-and-reactions/",
"title": "Event sources and reactions -- decision",
"section": "PRDs",
"body": "# Event sources and reactions -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-7d5u.1`, blocks `7d5u.2/.3/.4/.5`\n\nAnswers the four questions in `7d5u.1`'s description. Investigated against\nthe actual tree, not designed from scratch: three mechanisms already in this\ncodebase answer most of this, and the job here is picking the right one for\neach question and saying which packages change.\n\n## 1. In-process typed families, not out-of-process dispatch\n\nArchie has no out-of-process extension mechanism. The plugin engine\nrule (`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`,\nmechanically checked by\n`internal/plugin/architecture_test.go`) keeps every capability family\nin-process behind a narrow typed registrar; NATS RPC exists for\ndaemon\u003c-\u003eagentexec, a different actor with a different trust boundary (task\nexecution, not third-party extension code), not a precedent for generic\nplugin dispatch. Neither epic's near-term payoff -- react to a labelled\nissue, bind a captured webhook to a workflow -- needs extension code in\nanother language or process. Building out-of-process dispatch now would be\ndesigning for a requirement neither epic states.\n\n`docs/architecture/plugins-and-extensions.md` does **not** need amending.\nThe line that looked like a blanket ban on hooks (`archie-core-7d5u`'s notes\nrecord the correction) is scoped to Workflow semantics specifically, and\nnothing decided here touches Workflow's ownership of its own contracts.\n\n## 2. Reaction delivery: `internal/eventbus`'s contract, a NEW stream\n\n`internal/eventbus.Publisher`/`Consumer` already has everything a reaction\nneeds: `PublishUnique(subject, idempotencyKey, payload)` for at-least-once\nwithout duplicate enqueue, `Ack`/`Nak` with \"a handler returning an error\ncauses redelivery.\" Do not design new delivery semantics; use this contract.\n\n**Do not reuse the existing `nats.Client` as-is.** `Config.StreamName` and\n`Config.Subjects` are already composition-supplied (\"the bus must not know\nwhich subjects belong to which domain,\" `config.go`), but the\nretention policy is not parameterised: `New` hardcodes\n`Retention: jetstream.WorkQueuePolicy` (`client.go`), the competing-consumer\npolicy correct for `ARCHIE_TASKS` task distribution -- one message, claimed by\nexactly one consumer -- and wrong for reactions. Two independent reactions\nboth wanting to see the same event under `WorkQueuePolicy` hit exactly the\ntrap `CLAUDE.md` already documents: overlapping filter subjects on a\nwork-queue stream mean the second consumer silently gets nothing. Reactions\nneed fan-out, not claim-once, so the client needs retention made a `Config`\nfield (defaulting to `WorkQueuePolicy` so `ARCHIE_TASKS` is\nunaffected), and a second stream (`ARCHIE_REACTIONS` or similar) configured\nunder a fan-out-capable policy, alongside the existing task-distribution\nstream -- not instead of it.\n\nThis is where `7d5u.2`'s embedded-vs-external axis attaches: whichever NATS\ninstance backs `ARCHIE_TASKS` also backs the reaction stream. NATS is not\noptional as a technology -- the choice is only\nwhether it runs as an external server or embedded in-process\n(`github.com/nats-io/nats-server/v2` is already a direct, test-proven\ndependency, just never wired into production startup). `7d5u.2` wires that;\nthis document does not re-decide it.\n\n## 3. Reactions in these two epics are producer-only\n\nNo veto, no mutation of in-flight work. Two existing shapes cover everything\neither epic actually needs, and neither is a hook that can block something\nelse:\n\n- **Cheap wake, no payload.** `internal/domain/curator/wake.go`'s\n `WakeOnPrimaryInput` subscribes to the lossy `events.Bus` and nudges a\n runtime to check sooner; a dropped event only delays a check-in, never\n loses work, because the trigger decision is a deterministic state read at\n pass time, not the event payload. Model any \"check something sooner\"\n reaction on this, unchanged.\n- **Produce new work, real payload.** `daemon.go`'s existing `pollNATS` -\u003e\n `publishTask` path is already exactly a reaction that observes forge state\n and produces a `workintake.TaskEnvelope`. A webhook source is a second\n producer into the same path, not a new capability -- see question 4.\n\nA reaction that can veto or mutate an _in-flight_ task (block a PR from\nopening, alter a running stage) is a different, harder problem with its own\nordering and failure semantics, and belongs to `archie-core-h019` (adversarial\nself-review) if and when that epic needs one -- not here. Do not build a\ngeneral block-capable hook mechanism for either epic; nothing in their stated\nscope requires it, and it would duplicate whatever h019 eventually needs.\n\n## 4. No single generic intake interface; each domain keeps its own\n\nA `Source` interface generic enough to cover a forge issue, a chat message,\nand a cron tick wouldLine truncated
},
{
"url": "/dev/prds/execution-tree-state-machine/",
"title": "Execution tree and enforced state machine",
"section": "PRDs",
"body": "# Execution tree and enforced state machine\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md` (canonical workflow model);\nsettles the \"enforced WorkflowExecution state machine\" item in\n`docs/architecture/migration-decisions.md` section 4.\n**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution),\n`docs/prds/state-store-contract.md` (wire contract and task-scoped grants).\n\n## Decision\n\nA WorkflowExecution becomes the root of a tree of StepExecutions. Every stage\nrun, and every agent call a stage makes, is its own durable record with a\nparent, an attempt, a status and an outcome. Both levels move only through a\ndeclared transition table, enforced by the State Store in the same transaction\nthat writes the audit row and the domain event.\n\n## Problem\n\n- A run is one `tasks` row. The only per-step record is the mutable `stage`\n column, overwritten as `workflow.Run` advances, plus observability events.\n A failed attempt cannot say which step failed or what its children did\n without replaying the event stream.\n- `Store.Transition` guards on the expected `from` status, but any `from` to\n any `to` is accepted. A `queued` to `merged` write succeeds.\n- Stop cancels one context in `daemon.runningTasks`. Nothing persisted says\n which work was in flight, so an agent call that outlives its stage (a\n reviewer, a container) is invisible to the store.\n- `workflow.Run` writes `tc.Store.Update` and discards the error, then emits\n `KindStageStart` separately. State and events can diverge.\n\n## Model\n\n```text\nWorkflowExecution (tasks row, id E)\n└── attempt N\n ├── StepExecution stage \"plan\" depth 0\n ├── StepExecution stage \"implement\" depth 0\n │ └── StepExecution agent \"implement\" depth 1\n └── StepExecution stage \"review\" depth 0\n ├── StepExecution agent \"review:1\" depth 1\n └── StepExecution agent \"review:2\" depth 1\n```\n\n- A StepExecution belongs to exactly one WorkflowExecution and one attempt.\n `parent_id` is null for a stage and names the enclosing StepExecution\n otherwise. Depth is derived from the parent, never supplied by the caller.\n- `kind` is `stage`, `agent` or `call`. A new kind needs a named consumer\n before it is added.\n- A `workflow.call` step (`docs/prds/event-automation.md`) is a `call`\n StepExecution in the caller's tree. The callee is its own\n WorkflowExecution, with its own tree, acting as its own identity, and the\n `call` step records the callee's execution ID. Trees never nest across\n executions, so each run's tree stays inside that run's authority.\n- A retry starts a new attempt. Earlier attempts' StepExecutions are never\n rewritten.\n\n## Transition tables\n\nWorkflowExecution statuses are the existing `taskstate` constants, persisted\nstrings unchanged. `taskstate` gains the one table every writer checks:\n\n| From | To |\n| --------------- | ---------------------------------------------------------- |\n| `queued` | `running`, `closed_wont_do` |\n| `running` | `queued` (crash recovery), `waiting_human`, `pr_open`, `completed`, `parked`, `closed_wont_do` |\n| `waiting_human` | `queued` (approve), `closed_wont_do` |\n| `parked` | `queued` (retry), `dead` (abandon), `closed_wont_do` |\n| `pr_open` | `merged`, `rejected`, `queued` (remediation), `closed_wont_do` |\n| terminal | none |\n\nStepExecution statuses:\n\n| From | To |\n| --------- | ------------------------------------------------------ |\n| `pending` | `running`, `cancelled` |\n| `running` | `succeeded`, `failed`, `cancelled`, `interrupted` |\n| terminal | none |\n\n`interrupted` means the process running the step died or shut down. It is\ndistinct from `cancelled`, which an operator or a parent asked for, and from\n`failed`, which the step reported.\n\nA StepExecution cannot reach `running` while its WorkflowExecution is not\n`running`, and cannot start under a terminal parent.\n\n## Enforcement\n\n- The table lives in `taskstate` (no dependencies), so the store, daemon and\n gateway share one copy.\n- Every store method that changes `tasks.status` checks the table and writes\n the audit and event rows, not only `Transition`. That includes the claim,\n `ParkTask`, `Requeue`, `RetryTask`, `BeginRemediation` and `RecoverStale`\n paths, several of which change status without an audit row.\n- The State Store rejects an illegal transition with a new sentinel,\n `ErrIllegalTransition`, carried across the wire through `mapError` like\n `ErrStaleTransition`. ALine truncated
},
{
"url": "/dev/prds/extensions-center/",
"title": "Extensions centre",
"section": "PRDs",
"body": "# Extensions centre\n\n**Status:** Draft\n\n\u003e Superseded by `docs/prds/store.md`.\n\nEpic: `archie-core-1786637490708-35-38424ead` / GitHub `#56` (\"Replace Skills\nwith a bundled Extensions centre\").\n\nSkills, Workflows, and Tools/MCP already exist as separate, working\ninventories with their own APIs (`api_skills.go`, `api_workflows.go`,\nconfig-driven MCP servers) and their own family-owned controller pattern\n(`curator.Registry`, `health.Registry`, `image.Registry`,\n`workflow.Registry` all already prove this shape). `plugin.Plugin`\n(`internal/plugin/plugin.go`) is already metadata-only, per\n`docs/architecture/plugins-and-extensions.md`. None of that is rebuilt here.\nWhat's missing, confirmed by grep, is: any config schema for enabling or\ndisabling a capability, any \"pending restart\" state tracking, and any single\ninventory that reconciles configured/bundled/discovered/active state across\nfamilies. This document decides those three things and the UI surface that\npresents them. It extends `plugins-and-extensions.md` rather than replacing\nit — that doc's decisions (metadata-only `Plugin`, typed capability\nfamilies, no generic dispatch) are unchanged.\n\nOut of scope: any remote or arbitrary-URL plugin installation path (the\nepic's own acceptance criteria forbid this, and `plugin.LoadDir`\n(`plugin.go`) already only reads `~/.config/archie/plugins/*.go` — this\ndocument does not add a fetch-by-URL variant to it).\n\n## Problem\n\n`internal/config/config.go`'s `MCPServer` and `ToolsConfig` structs have no\n`enabled` field (confirmed by the investigation grep). `api_config.go`'s\n`UpdateConfig`/`handleConfigUpdate` seam persists changes but has no state\ndistinguishing \"saved, takes effect now\" from \"saved, needs restart\" — the\nonly existing reload path (`ReloadChannel`, `server.go`) is\nchannel-specific and explicitly does not cover plugins or MCP servers.\n`server.go` already wires five separate optional inventories\n(Workflows, Skills, Curators, Channels, Captures/Mappings/Bindings) as\nindependent fields with no unifying type — an operator has no single\nplace to see \"what's available, what's enabled, what's actually running,\nand what's degraded\" across all of them. `ui/src/` has `settings/`,\n`skills/`, and `workflows/` directories already; there is no\n`ui/src/extensions/`.\n\n## Design\n\n### Unified inventory type\n\n```go\npackage extensions // internal/domain/extensions — new, app-level aggregator\n\ntype State string\n\nconst (\n StateAvailable State = \"available\" // bundled, not configured\n StateEnabled State = \"enabled\" // configured on, not yet live\n StateActive State = \"active\" // configured on and running\n StateDegraded State = \"degraded\" // active but unhealthy\n StateSkipped State = \"skipped\" // optional, disabled by config\n StatePendingRestart State = \"pending_restart\" // config changed, not yet live\n)\n\ntype Entry struct {\n Family string // \"skill\" | \"workflow\" | \"tool\" | \"plugin\" | \"integration\"\n Name string\n Core bool // non-disableable\n State State\n Health string // reuses whatever the family's own registry already reports\n}\n\ntype Inventory interface {\n List(ctx context.Context) ([]Entry, error)\n}\n```\n\n**Decision.** `extensions.Inventory` is a read-only aggregator, not a new\ndomain that owns state. It queries each family's existing registry\n(`curator.Registry`, `health.Registry`, `workflow.Registry`, the MCP client\nset, `plugin.LoadDir`'s result) for live state, and compares that against\nthe config-desired state (below) to compute `StatePendingRestart` — the diff\nis computed on read, not persisted, so there is no new durable state to keep\nconsistent with the registries themselves. This follows\n`migration-decisions.md`'s rule that cross-cutting aggregation composes\nexisting domain-owned contracts rather than duplicating their state.\n\n**Call site.** New package `internal/domain/extensions/inventory.go`.\nComposed in `internal/app/archied` (wherever `server.go`'s other optional\nfields — Workflows, Skills, Curators — are wired) since it needs\nreferences to every family's registry, which only application-layer\ncomposition has.\n\n### Config-backed enablement\n\n**Decision.** Add `enabled bool` (default `true` for pre-existing configured\nentries, so no upgrade silently disables anything already configured) to\neach family's config element: `MCPServer.Enabled`, and equivalent fields on\nwhatever config types back skills/workflows/plugins if they don't already\nhave an on/off switch. Core capabilities (identity, workflow engine, State\nStore connectivity — named in `organisation.md`'s cross-cutting packages)\nhave no `enabled` field at all; a config value can't be added to something\nthat doesn't expose the toggle, which is the \"non-disaLine truncated
},
{
"url": "/dev/prds/external-agent-harness/",
"title": "External agent harnesses",
"section": "PRDs",
"body": "# External agent harnesses\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md` (agent execution as a data\nboundary); settles the harness non-goal deferred by\n`docs/prds/service-decomposition.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a harness\nrun is one `agent` StepExecution), `docs/prds/binding-secret-encryption.md`\n(the at-rest envelope reused for harness credentials).\n\n## Decision\n\nA workflow stage can run on an external coding-agent CLI instead of the\nbuilt-in agent loop: Claude Code, Codex, Pi, OMP, GitHub Copilot CLI, or any\nother CLI packaged as a Docker Sandbox Kit v3. Each authenticates with an API\nkey or the operator's subscription login, and can carry the operator's own\nskills, plugins, subagents and instructions.\n\nTwo boundaries hold regardless of what the harness does:\n\n- **The real credential never enters the container.** The container sees\n sentinel values; archie's egress proxy substitutes the real credential on\n outbound requests and performs OAuth refresh on the host.\n- **Archie's workflow guarantees are enforced outside the harness.** Git,\n protected paths, read-only stages, gates and budgets are checked by archie\n around the process and against the worktree afterwards.\n\n## Kits\n\nA harness is packaged as a Kit v3 image: an OCI image whose\n`vnd.docker.sandbox.kit.descriptor` manifest annotation declares what the\nharness needs. Archie reads descriptors with the published\n`github.com/docker/sandbox-kit-spec/v3/spec` package and does not maintain\nits own descriptor format. Published Kits run unmodified.\n\nArchie is a partial Kit runtime. It implements these capability types:\n\n| Type | Archie behaviour |\n| ------------------- | ----------------------------------------------------------------------------------------- |\n| `credential@1` | Proxy-managed only, described below. |\n| `network-policy@1` | Enforced by the egress proxy. |\n| `volume@1` | A Docker volume keyed by WorkflowExecution, deleted with it. |\n| `lifecycle@1` | Install and startup hooks run on container create. |\n| `agent-sessions@1` | The headless `prompt` and `resume` invocations for the stage. |\n| `agent-skills@1` | The operator's skills store (`skills_dir`), mounted read-only whatever the Kit asks. |\n| `agent-context@1` | The workload's profile file beside the workspace, indexing each Kit's guidance. |\n| `resources@1` | Container CPU and memory limits. |\n\nEvery other type fails closed: a required entry refuses the launch, an\noptional one is skipped and recorded on the step. `credential@1` with\n`passthrough: true` and any credential for a forge service are refused.\n\nThe operator's own setup (plugins, subagents, instructions, settings) is a\nmixin Kit, published with the harness Kit as a Kit set: the set merges their\nlayers into one image. It is versioned image content, rewritten on every\ncreate, never state a run can modify.\n\n## Contract\n\nA harness run is a second implementation of `agentexec.Runner`. It takes the\nsame `Request` and returns the same `Result`, so workflows, the daemon and\nthe State Store do not know which runner ran a stage.\n\n`agent-sessions@1` supplies the invocation. Archie supplies, per CLI, an\noutput adapter that translates the CLI's JSON output stream into\n`ToolCallReporter` calls, `Usage` and a session ID. A CLI with no adapter can\nrun stages with no capture tools, reporting no usage; its token budget falls\nback to wall clock.\n\nWorkflow definition validation rejects, at load time, a stage whose needs the\nselected harness cannot meet: capture tools without an adapter, or a gate\nretry without a `resume` verb.\n\n## Selection\n\nA harness is an agent profile. `docs/prds/event-automation.md` defines a\nprofile as the execution environment a workflow selects; a harness profile\nnames one Kit pinned by digest, a workload Kit or a published Kit set, in\nplace of a container image. Archie runs that Kit's image and composes no Kits\nitself; a bare mixin is refused. Everything else about profiles\nholds: a workflow names its profile, a stage may name a different one, and a\nprofile holds no secrets.\n\n`archie-agent` builds the stage's runner from the stage's profile: the\nai-sdk agent loop for an image profile, the harness runner for a Kit\nprofile. Image profiles, and every workflow already written against them,\nare unchanged. A Kit profile named by no workflow is a validation error.\n\nA stage naming a different profile than its workflow's is a separate run,\nnot a mid-container runnLine truncated
},
{
"url": "/dev/prds/identity-decision/",
"title": "Identity for users, agents and external agents — decision",
"section": "PRDs",
"body": "# Identity for users, agents and external agents — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** `docs/architecture/organisation.md` for placement;\n`docs/architecture/migration-decisions.md` §3 for the attribution semantics this\ndocument implements; `docs/prds/agent2agent-protocol.md` for the A2A surface that\nconsumes it.\n\n## Decision\n\nOne identity record covers every actor archie has: users, agents, external agents,\nservice accounts and the system. Authentication is delegated to the estate's OIDC\nprovider, and attribution stays archie's.\n\nAuthentication and authorisation are OSS archie integrates; a design that\nhand-rolls either fails this document.\n\n## The provider\n\n**Authelia is the only identity provider**, because the estate already runs it in\nfront of the dashboard and it issues credentials for both kinds of caller: humans\nuse the authorisation code flow, and machines use the `client_credentials` grant,\nwhich yields a token whose subject is the client's own identifier.\n\n**Each agent is its own provider client.** A shared client would make two agents\nindistinguishable in the audit trail and revocable only together, which is the\nproperty attribution needs and the reason per-client registration is a\nrequirement.\n\n**A person's client and an agent's client are registered separately**, because the\ntwo token shapes differ and a shared registration would collapse the distinction\nthe attribution rests on. A person's token names them in `sub`. A machine's token\ncarries no `sub` at all and names its client instead, so a machine identity is keyed\non its client registration and exists one per client. A token asserting neither is\nrefused.\n\n**A person's token requests the audience at the authorisation endpoint**, not only\nat the token endpoint. A provider that otherwise returns the audience empty\nproduces a valid token archie must refuse, and that refusal looks like a signing\nfault rather than a missing request parameter.\n\n**SPIFFE/SPIRE is not adopted.** It is adopted and maintained, and its attestation\nis strictly stronger than a secret: a workload proves what it is rather than what\nit holds. It is rejected here on operational fit, not on quality: it adds a\ncontrol plane archie does not have, and the property it buys — identity attested\nfrom the platform rather than from a presented secret — answers a threat archie\ndoes not face, because archie's agents run as containers the operator launches and\nalready receive their credentials from the daemon that owns them. It is the right\nanswer when agents run on infrastructure the operator does not control.\n\n## What archie owns\n\n- **The identity record.** `internal/domain/identity` survives as archie's own\n record of an actor and is not replaced by the provider's directory, because the\n record carries what the directory does not: the lifecycle, the bindings and the\n attribution below.\n- **The lifecycle.** Active, suspended and retired, with rename, suspend,\n reactivate and retire, remain archie's. Suspending an identity must stop it\n acting whether or not the provider still authenticates it.\n- **The subject binding.** An identity that proves itself is bound to the provider\n subject that asserts it. This is the same bridge `identity_aliases` already\n provides from a legacy name to an identity, so the second binding is the same\n mechanism rather than a new one.\n- **Attribution.** Who acted, and under whose authority.\n- **The audit trail of identity changes**, which already records an actor, a source\n and a request identifier for every mutation.\n\n## What archie never owns\n\nA credential, a password, a session, a token, a signing key, a second-factor\nenrolment, or a permission rule.\n\n## How an agent proves who it is\n\n**An agent authenticates by presenting a token the provider issued to its own\nclient**, and archie validates it against the provider's published signing keys and\ntakes its subject as the acting identity. The agent holds a client secret; archie\nholds only the public keys, so a compromised archie cannot mint an identity.\n\n**A WebMCP tool call is not a proof of agent identity and cannot be made one.** A\npage can invoke its own tools, so an agent's call and a page script's call arrive\nat archie identically. No field, header or convention distinguishes them, because\nthe difference does not exist on the wire.\n\n**A WebMCP tool call is therefore attributed to the identity the request\npresented, with its source recorded as a hint.** It may record that the request\ncame from the dashboard; it never records that an agent acted, and it never\nrecords that a human approved. A tool call that a page script can forge must not\nbe the thing an audit trail rests on.\n\n**Agent-initiated action therefore arrives on a surface that carries a credential**\n— the A2A surface, or an authenticated agent call — because that is the only place\nan agent's Line truncated
},
{
"url": "/dev/prds/image-capability-contract/",
"title": "Image capability contract and configuration",
"section": "PRDs",
"body": "# Image capability contract and configuration\n\n**Status:** Approved\n\nEpic: archie-core-1786748942120-1-6636e629 / GitHub #496 (\"Image generation\ncapability: hosted API baseline plus local GPU workflows\").\n\nThe contract and configuration (#497) shipped first and is settled — see\n\"Package: `internal/domain/image`\" below. This document now covers the full\nfeature set: hosted provider (#498), local GPU provider (#499), `/image`\nrouting and clarification (#500), delivery through channels and web (#501).\nDocumentation (#502) and the cross-cutting test matrix (#503) are execution\nwork against the design below, not open design questions, so they are not\ngiven their own sections — each preceding section states its own test\nobligations inline.\n\n## Problem\n\nArchie needs a provider-neutral boundary for image generation/editing so a\nhosted API (gpt-image-2-class) and a future local GPU backend can both\nimplement it without either one leaking into the domain contract. Nothing\nin the repo defines this (`grep -ri image` over `internal/domain` and\n`internal/config` returns nothing image-specific).\n\n## Design\n\nFollows the plugin engine family shape already established by\n`internal/domain/curator` and `internal/domain/memory`\n(`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`): a\ntyped contract with real domain operations,\nan owning `Registry` (register/get/names, no start/stop lifecycle — see\nbelow), and narrow host access via a `Registrar`.\n\n### Package: `internal/domain/image`\n\n**Why no `Lifecycle` (`Start/Health/Stop`)**: curator and memory engines are\nlong-running — they hold a background cadence or a persistent connection\nworth health-checking. An image provider is call-scoped: it either serves a\n`Generate`/`Edit` request or it does not. Health here means \"is this\nprovider usable at call time\", which is exactly what `Generate`/`Edit`\nreturning a typed `ErrUnavailable` already communicates — a separate\n`Health()` poll would just duplicate that. `Registry` still owns\nregistration and lookup, so provider selection is testable with fakes per\nthe acceptance criteria, but there is no `Start`/`Stop` to orchestrate.\n\n```go\n// Capability declares what one provider supports, discoverable before a\n// request is built so a caller can reject an unsupported combination (e.g.\n// edit-with-mask on a generate-only provider) instead of sending it and\n// parsing a provider-specific error back out.\ntype Capability struct {\n Generate bool\n Edit bool // edit requires at least one input image\n Mask bool // edit supports a mask restricting the edited region\n MaxInputs int // 0 = Edit unsupported\n Sizes []string // provider-declared output sizes, e.g. \"1024x1024\"\n}\n\n// Provider is the typed contract every image backend implements — hosted\n// (gpt-image-2-class) or local (GPU recipe). No Lifecycle: a provider is\n// call-scoped, not long-running (see design doc rationale).\ntype Provider interface {\n Name() string\n // Class distinguishes hosted (spends money/quota per call) from local\n // (spends host GPU/time). Selection logic and config validation key off\n // this, never off Name, so a new provider cannot silently slip through\n // the hosted-cost gate under an unrecognized name.\n Class() ProviderClass\n Capability() Capability\n Generate(ctx context.Context, req GenerateRequest) (Result, error)\n Edit(ctx context.Context, req EditRequest) (Result, error)\n}\n\ntype ProviderClass string\n\nconst (\n ClassHosted ProviderClass = \"hosted\"\n ClassLocal ProviderClass = \"local\"\n)\n```\n\nRequest/result types (provider-neutral, no OpenAI types):\n\n```go\ntype GenerateRequest struct {\n Prompt string\n Size string // \"\" = provider default\n N int // number of images; 0 = 1\n Options map[string]string // provider-specific overflow (e.g. \"quality\"),\n // deliberately untyped so the contract does not\n // grow a field per provider\n}\n\ntype EditRequest struct {\n Prompt string\n Inputs []ImageData // 1..Capability.MaxInputs\n Mask *ImageData // nil unless Capability.Mask\n Size string\n N int\n Options map[string]string\n}\n\n// ImageData carries image bytes in-process, never a path or URL: the\n// domain layer must not assume a filesystem or a fetchable location (mirrors\n// why curator's Registrar never receives *daemon.Daemon — no ambient host\n// access smuggled in through a \"just a string\" field).\ntype ImageData struct {\n Bytes []byte\n MIMEType string\n}\n\ntype Result struct {\n Images []ImageData\n Provider string\n Model string\n CreatedAt time.Time\n}\n```\n\n### Error taxonomy\n\n```go\nvar (\n ErrUnavailable = errors.New(\"image provider unavailable\") // missing credential, backLine truncated
},
{
"url": "/dev/prds/inline-review/",
"title": "Inline review -- decision",
"section": "PRDs",
"body": "# Inline review -- decision\n\n**Status:** Finalised\n**Beads issue:** `archie-core-q9au`\n**Builds on:** `archie-core-h019` (adversarial self-review)\n\n## Problem\n\nFindings reach the operator only as a flat list in the PR body\n(`renderPRReviewSection`, h019.6): ``- `file.go` (confirmed, error): \u003cdefect\u003e\n— \u003cscenario\u003e``. That is a report _about_ the code, not a review _of_ it. A real\nreviewer anchors each finding to the line it is about, so the author sees it in\ncontext — and, when the fix is mechanical, attaches the replacement so it can be\napplied in one click.\n\nBoth halves are missing:\n\n- **No line-anchored comment.** `forge.Forge.Comment` posts to the PR\n _conversation_ (`Issues.CreateComment`); nothing creates a review comment at\n `path` + `line`.\n- **No suggested fix.** `ReviewFinding` carries `File`/`Line`/`Defect`/\n `FailureScenario`/`Verdict`/`Level`/`Category` — no replacement code, so even\n an anchored comment could only describe the fix, not offer it.\n\n## Decisions\n\n### 1. A narrow, type-asserted write surface\n\nThe set of comments travels in one call, so a forge that can only carry them on\na submitted review needs one request rather than one per finding:\n\n```go\ntype ReviewCommentWriter interface {\n CreateReviewComments(ctx context.Context, owner, repo string, number int,\n comments []InlineReviewComment) error\n}\n```\n\nType-asserted like `PullRequestReader`/`PullRequestReviewReader`, so a forge\nthat cannot do it is skipped rather than faked. The stage reaches it through\n`workflow.Forger`, whose production implementation is `forgerpc.Client` — the\nworker holds no forge credentials, so the daemon's forgerpc server type-asserts\n`forge.ReviewCommentWriter` and answers an incapable forge with an error the\nbest-effort stage logs.\n\nThe comment's line is anchored to the pull request's **current head revision**,\nresolved inside each implementation rather than passed in by the caller: it is\nthe revision the comments are attached to, and the caller that produced the line\nnumbers holds no forge credentials to read it. The caller does pass the revision\nthose line numbers were **measured on** (`TaskContext.ReviewedHeadSHA`,\nrecorded when `StageOpenPR` opens the pull request), and the implementation\nposts only while the head it read still matches it — see §4.\n\nPer-forge reality, verified against the SDKs:\n\n- **GitHub** — direct: `PullRequests.CreateComment` with\n `{Body, Path, Line, Side: \"RIGHT\", CommitID}`.\n- **Gitea** — no direct inline-comment call. Inline comments ride on a submitted\n review (`CreatePullReview` with `Comments` and a `COMMENT` state). The Gitea\n implementation therefore submits a single `COMMENT`-state review carrying the\n findings, or the capability is simply absent (the type assertion skips it).\n Decided: implement Gitea as a `COMMENT`-state review; do not block the feature\n on it.\n\n### 2. `Suggestion`, and only on confirmed findings\n\n`ReviewFinding` gains an optional `Suggestion string` — the replacement text for\nthe anchored line, rendered as a fenced `suggestion` block (GitHub's one-click\n\"Commit suggestion\").\n\n**Only `confirmed` findings may carry one.** A wrong suggestion is a\none-click path to breaking code a reviewer then has to notice; `confirmed` is by\ndefinition the verdict the reviewer traced and can state the failure for. A\n`plausible` finding is a worry, and a worry gets a sentence, not a patch. This is\nthe h019.5 calibration rule reused, not a new one.\n\n`Suggestion` replaces the anchored line exactly, and is only rendered when\n`Verdict == confirmed`. Single-line only in this cut;\nmulti-line (GitHub's `StartLine`/`StartSide`) is a follow-up, because a\nmulti-line suggestion that is off by one line silently corrupts the file. The\nrule is enforced in `ReviewFinding.Validate` — an embedded newline is rejected\nthere, so the `record_finding` tool refuses it with feedback the model can act\non, rather than the renderer silently posting a fence that applies only its\nfirst line.\n\n### 3. Which findings are posted inline\n\nOnly findings that are **line-anchored** (`Line \u003e 0`). A whole-file finding\n(`Line == 0`, e.g. \"README.md is stale\") has no line to attach to and stays in\nthe PR-body list. The body section keeps listing everything, so it remains the\ncomplete record and the fallback.\n\nFindings that block never reach this path: a surviving blocking finding parks\nthe task before `StageOpenPR`, so there is no PR to comment on. Inline comments\nare the non-blocking, line-anchored subset — which is exactly the set that would\notherwise be a body-only list the author has to map back to lines by hand.\n\n### 4. A best-effort stage after `StageOpenPR`\n\nNew `StagePostReviewComments`, after `StageOpenPR`:\n\n1. Read the report stashed by `StageReview` (`tc.ReviewReport`, h019.6).\n2. Post each line-anchored finding as an inlLine truncated
},
{
"url": "/dev/prds/mcp-tool-completion/",
"title": "MCP client and tool-guardrail completion",
"section": "PRDs",
"body": "# MCP client and tool-guardrail completion\n\n**Status:** Approved\n\nEpic: `archie-core-1786637493439-140-2cee2e9b` / GitHub `#161` (\"[EPIC] Tools:\ncentral registry, MCP client, guardrails\").\n\nThis document is scoped to five sub-features of that epic: MCP\nserver-initiated sampling, the per-server parallel-tool-calls flag, sandboxed\nMCP tool servers, a Firecracker sandbox backend, and sequential dispatch with\nper-result previews.\n\nOut of scope, and not to be touched: the central registry\n(`internal/tools/registry.go`), all three MCP transports (stdio/HTTP/SSE,\n`internal/tools/mcp/transport*.go`), reconnect-with-backoff\n(`transport.go`), guardrail loop detection\n(`internal/tools/guardrail.go`), idempotent/mutating classification\n(`internal/tools/classification.go`), concurrent tool dispatch (`#183`), and\nprogressive disclosure wiring (`internal/app/archied`). These are settled and\nproduction-wired.\n\n## Problem\n\n`bd search \"MCP client\"` shows five closed transport beads and one open:\nserver-initiated sampling (`#151`). `internal/tools/mcp/client.go`\nholds a single `callMu *sync.Mutex` that serialises every `tools/call`\nregardless of server — `ParallelToolCalls` does not exist on the `MCPServer`\nconfig struct (`internal/config/config.go`), confirming `#177` is a\nreal gap, not a stale bead. `#178` (wire MCP tool servers for the chat agent,\nsandboxed) and `#179` (Firecracker substrate) have no corresponding code —\nMCP servers run as whatever the config's `Command`/`Args` launches,\nunsandboxed. `#182` (sequential tool dispatch with per-result previews) is\nopen; concurrent dispatch (`#183`) is closed, so there are two dispatch paths\nand this PRD decides how they coexist.\n\n## Design\n\nSub-features are independent; there is no new shared type this document\nintroduces. Each section below stands alone.\n\n## MCP server-initiated sampling (`#151`)\n\n**Decision.** Implement as a callback on `mcp.Client`, not a second\ntransport. The MCP spec's `sampling/createMessage` request flows server→client\nover the same connection each transport already maintains\n(`transport.go`'s stdio/HTTP/SSE all multiplex request and response frames).\nAdd a `SamplingHandler func(context.Context, SamplingRequest) (SamplingResult, error)`\nfield to the client's config struct next to the existing transport fields,\ndefaulting to nil (server sampling requests get a JSON-RPC \"not supported\"\nerror when unset — never a silent drop).\n\n**Call site.** `internal/tools/mcp/client.go` — add the handler field and a\ndispatch branch in whatever function demuxes incoming server\nmessages by method name (the same switch that already routes\n`notifications/*`). Wire a concrete handler in\n`internal/app/archied/main.go` that routes the sampling request through the\nsame chat-model call path `chatGenerateOptions` already uses, so a\nserver-initiated sample gets the daemon's configured model, not a second\nprovider client. The agent worker hosts the same configured MCP servers on the\ntask path and runs its own model runtime, so `internal/app/agentworker` wires\nthe same seam from the task's builder model: a server that samples succeeds\ninside a chat turn and inside a task, never one and not the other. The message\nmapping and the token bound are shared (`internal/agentexec`, next to the\nruntime both paths call models through) so both paths bound a sample\nidentically.\n\n**Reuse check.** The chat model invocation path already exists\n(`chatGenerateOptions`, `main.go`) and the task model path already exists\n(`agentexec.NewRuntime`, the runtime an agent stage runs on); this reuses both\nrather than adding a parallel model-calling path for MCP sampling.\n\n**Failure mapping.**\n\n| condition | contract error |\n| ------------------------------- | ------------------------------------------------------------------------------------------ |\n| no `SamplingHandler` configured | JSON-RPC method-not-found, per spec |\n| handler returns error | JSON-RPC internal error, message from handler |\n| handler timeout | JSON-RPC timeout error; use the transport's existing request-timeout config, not a new one |\n\n**Testing.** Fakeable entirely — a stub `SamplingHandler` and a fake\ntransport that emits a `sampling/createMessage` frame. No real backend\nneeded; belongs in `task check`.\n\n## Per-server parallel-tool-calls flag (`#177`)\n\n**Decision.** `ParallelToolCalls bool` (default `false`) goes on `MCPServer`\nin `internal/config/config.go`, next to `Transport`/`Command`. The\nmutex in `client.go` becomes per-server: when `ParallelToolCalls` is\nfalse (default, and the only behaviour), keep the single `callMu`\nserialising that server's calls exactly as now; when true, drop the muLine truncated
},
{
"url": "/dev/prds/memory-engine-unification/",
"title": "Memory engine unification: four scopes, CRUD, and one write path -- decision",
"section": "PRDs",
"body": "# Memory engine unification: four scopes, CRUD, and one write path -- decision\n\n**Status:** Approved\n**Date:** 2026-09-16\n**Findings:** `memory-4` and its dependants in the adversarial sweep\n(`.local/issue-tracker`); the real defect is the split described below, for\nwhich `memory-4` is a symptom\n**Supersedes:** the draft `memory-turn-context.md` (its synchronous-read\nargument survives and is reused; its `Manager` method and consumer-owned port do\nnot)\n**Settles:** four open items in `docs/architecture/migration-decisions.md#5`\n(listed at the end)\n\n## Problem\n\nThere are **two live memory stores for one assistant**, split by which component\nwrites them, and the chat turn reads neither.\n\n| Family | Written by | Root | Format |\n| ----------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------- | ----------------------- |\n| `internal/memory` (`Manager`, `builtin.Provider`) | the chat agent's `memory_edit` tool via `memorytoolprovider` (`bootstrap.go`) | `\u003cworkDir\u003e/memory` | `MEMORY.md` / `USER.md` |\n| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go`) | `\u003cworkDir\u003e/memory-engine` | identity-keyed blocks |\n\nThey share no code, no format and no scope vocabulary. Neither reaches a prompt:\n`Manager.SystemPromptBlock` (`internal/memory/manager.go`) has no production\ncaller anywhere, so the agent can write memory through a tool and never read it\nback.\n\nThree further defects fall out of the same split:\n\n1. **The engine's contract is not CRUD.** `Store` is `Write`/`Query`/`List`/\n `Forget` — create, read, delete, and **no Update**. The retired file provider\n _does_ have `handleAdd`/`handleReplace`/`handleRemove`, so the family being\n deleted is operationally richer than its replacement.\n2. **There is no scope model.** The contract carries one opaque `Identity\nstring`, and the curator fills it with a **session id** (`sessioncurator.go`)\n — which is none of the four scopes `docs/architecture/agent-system.md`\n requires, and stops meaning anything when the session ends.\n3. **The chat turn has no user identity on half the channels.** Telegram and\n email populate `SenderID` with a person; the dashboard populates it with\n nothing, and a webhook populates it with nothing either — a route path names\n a source, not a person, so `webhook.go` leaves `SenderID` empty and carries\n the route in `Inbound.BudgetKey` for rate limiting. `sender_id` is persisted\n (`session_store_postgres.go`), so whatever a channel puts there reaches the\n consumers that read it.\n\n`agent-system.md` says the write-scope selection and cross-scope sharing\nrules \"require a focused memory design decision\". This is that decision.\n\n## Decision\n\n### 1. One engine, addressed by four typed scopes\n\n`internal/domain/memory` is the only memory engine. `Observation.Identity`,\n`Query.Identity`, `Record.Identity` and `List(identity)` are deleted, not\nextended: a field whose meaning depends on the caller cannot carry a scope.\n\n```go\ntype ScopeKind string\n\nconst (\n ScopeGlobal ScopeKind = \"global\" // shared across the application\n ScopeAgent ScopeKind = \"agent\" // private to one Agent\n ScopeUser ScopeKind = \"user\" // one user, across their Agents\n ScopeAgentUser ScopeKind = \"agent-user\" // one Agent's relationship with one user\n)\n\ntype Scope struct {\n Kind ScopeKind\n Agent AgentID // required for ScopeAgent, ScopeAgentUser\n User IdentityID // required for ScopeUser, ScopeAgentUser\n}\n\nfunc (s Scope) Validate() error // rejects a component present where it is not required\nfunc (s Scope) Key() string // canonical, collision-free storage key\n```\n\n`AgentID` and `IdentityID` are opaque. This package never resolves or\ncanonicalises them.\n\nA turn's resolved identity is one value:\n\n```go\ntype Subject struct {\n AgentID AgentID\n UserID IdentityID // \"\" when the channel carries no per-person identity\n}\n\nfunc (s Subject) Scopes() []Scope // readable, most specific first\nfunc (s Subject) WritableScopes() []Scope // never includes ScopeGlobal\n```\n\n**Access control is naming a scope, and nothing else.** The read path names\nexactly the scopes of the resolved `Subject`; the engine never unions beyond what\nit is handed and applies no policy of its own. An engine that enforced policy\nwould need to know about channels, sessions and bindings, and every backend would\nreimplement it. \"Agent-wide is private to its owning Agent by default\"\n(`agent-system.md`) falls out mechanically, because `SLine truncated
},
{
"url": "/dev/prds/messaging-service-boundary/",
"title": "Messaging Service boundary and transport design",
"section": "PRDs",
"body": "# Messaging Service boundary and transport design\n\n**Status:** Approved\n**Revision:** 1 \n**Date:** 2026-09-19 \n**Beads issue:** `archie-core-8cda.6.1` \n**Parent:** [`service-decomposition.md`](/dev/prds/service-decomposition/) \n**Prerequisites:** Gateway contract extraction (Phase 1), State Store extraction (Phase 2), UI extraction (Phase 3)\n\nThis document is the authoritative specification for Phase 4: Messaging Service extraction. It fixes the process boundary, configuration ownership, client contracts, security posture, readiness behaviour, channel invariants, and deletion criteria required by `archie-core-8cda.6` and its child tasks.\n\n## Decision\n\nThe Messaging Service (`cmd/archie-messaging`, composed via `internal/app/archiemessaging`) owns external channel connections (Telegram, email, webhook) and dispatches inbound messages and commands to the standalone Gateway Service over gRPC via `messaging.ChatContract`.\n\nIt is a peer service to the UI Service and the daemon:\n\n- It serves external chat participants across configured communication platforms.\n- It consumes Gateway's `messaging.ChatContract` exclusively for chat turn execution, streaming, session queries, cancellation, persona selection, and task control actions.\n- It holds no direct database connections, owns no LLM execution or model provider credentials, and has no dependency on the daemon runtime or the UI HTTP server.\n\n## Boundary and Ownership\n\n| Concern | Messaging Service owns | Messaging Service consumes | Messaging Service must not own or link |\n| ---------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |\n| **Channel transports** | Telegram bot long-polling, Email IMAP/SMTP loops, Inbound Webhook HTTP listener | Gateway `ChatContract` | Direct LLM providers, model runtimes, tokenizer libraries |\n| **Turn dispatch** | Inbound message packaging, typing indicators, live streaming updates | `ChatContract.Route`, `ChatContract.Stream` | `gateway.Router`, `runtime.Runtime`, agent prompt builders |\n| **Sessions \u0026 History** | Platform-to-session key mapping, conversation thread ID translation | `ChatContract.GetSession`, `RecentMessages`, `RecentTurns` | store implementations, `SessionStore` database handles |\n| **Control \u0026 Actions** | Platform command parsing (`/status`, `/tasks`, `/cancel`, `/stop`, `/persona`) | `ChatContract.Snapshot`, `ApplyTaskAction`, `Cancel`, `SetPersona` | `daemon.Daemon`, workflow execution engine, worktree operations |\n| **Task Approvals** | Channel interactive keyboards, approval callbacks | `ChatContract.ApplyTaskAction` | Direct task status mutations, forge comment posters |\n| **Configuration** | Platform bot tokens, allowed sender/user IDs, webhook listen ports | `[chat.*]` channel configs, Gateway target/token | `config.Holder`, forge tokens, repo configs, agent container specs |\n| **Readiness** | Messaging process liveness, channel connectivity, Gateway probe | Gateway `ChatContract.Snapshot` | Internal daemon subsystem probes |\n\n## Target Service Shape\n\n1. **Binary entry point**: `cmd/archie-messaging/main.go` parses CLI flags (`-config`, `-config-overlay`, `-gateway-target`, `-gateway-token`) and hands execution to `internal/app/archiemessaging.Run`.\n2. **Application composition**: `internal/app/archiemessaging/` wires:\n - Config loading scoped strictly to `[chat.*]` and `[services.gateway]`.\n - Secret resolution for channel credentials (e.g. Telegram bot token).\n - Gateway gRPC client (`internal/infrastructure/gatewayrpc.Client`).\n - Channel lifecycle managers (`internal/channels/status`).\n - Channel instances (`internal/channels/telegram`, `email`, `webhook`).\n3. **Turn and Stream Execution**:\n - Channels adapt inbound platform messages to `messaging.Inbound`.\n - Streaming channels (Telegram) consume `ChatContract.Stream(ctx, inbound)` which returns `\u003c-chan messaging.ChatEvent`, mapping `started`, `delta`, `tool`, `media`, `done`, and `error` events directly to live message frames.\n - Non-streaming channels (email, synchronous webhooks) consume `ChatContract.Route(ctx, inbound)`.\n\n## Load-Bearing Channel Invariants\n\nThe Messaging Service preserves existing invariants defined in `AGENTS.md` and channel documentation:\n\n1. **Telegram long-polliLine truncated
},
{
"url": "/dev/prds/module-position/",
"title": "Module position -- design",
"section": "PRDs",
"body": "# Module position -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n\n## Problem\n\n`eda-playbook-engine.md` names four logic positions a playbook action can\ntarget: Workflow, Module, Channel, Forge. Workflow (`t2db.9`/`.10`/`.11`)\nand the standalone lint tool (`t2db.12`) are shipped. Module -- the\nposition that makes an action \"not restricted to code-generation\" -- has\nnot started, because it needs a schema-generation mechanism the parent\ndoc deliberately deferred: \"This document does not attempt to design the\nfull generator.\" This is that design.\n\n## Do not invent a new mechanism -- generalise the one used three times\n\nYaegi-interpreted extension code with a fixed, resolved-by-name exported\nfunction already exists in this codebase for three surfaces, and all three\nfollow the identical shape:\n\n| Surface | Fixed signature | Export path | Symbol table |\n| ----------------------------------------- | --------------------------------------- | -------------- | --------------------- |\n| Custom gate (`internal/gate/gateeval`) | `func(gate.GateContext) []gate.Finding` | `\"gate.Check\"` | `gateextract.Symbols` |\n| Workflow stage plugin (`skillbuild`) | stage-specific | skill-declared | `wfextract.Symbols` |\n| Skill plugin (`internal/skill/plugin.go`) | `func(string) string` | `\"main.Run\"` | none (stdlib only) |\n\nEach is: read a `.go` file -\u003e `yaegiutil.New` with that surface's symbol\ntable -\u003e `yaegiutil.Resolve[T](i, src, exportPath)` -\u003e call the resolved\nfunction wrapped in `yaegiutil.Safe` for panic recovery. **Module is a\nfourth instance of this same shape**, parameterised by action kind instead\nof hardcoded to one fixed signature. No new interpreter construction, no\nnew panic-recovery mechanism, no new symbol-table generation tool --\n`go generate ... yaegi extract` is already how `wfextract`/`gateextract`\nare produced that way (see their `//go:generate` directives), and Module\nschema generation reuses that exact command.\n\n## No generic `Module` interface -- one typed contract per action kind\n\nThe plugin engine rule's invariant 1 requires \"real capability-specific\noperations,\" and invariant 5 forbids adding capability methods to a\ngeneric interface. A single `Module` interface with `Run(args any) (any,\nerror)` would be exactly the untyped hook the rule (and\n`event-sources-and-reactions.md`'s rejection of a generic `Source`\ninterface) exists to prevent -- restating the mistake the whole EDA\ndocument was written to move away from (`wfextract`'s hardcoded\n`reflect.ValueOf(workflow.Implement)` table is what a closed, un-typed-per-\ncase system already looks like in this repo).\n\nInstead, **each action kind is its own tiny package with its own\ngenerated contract**, exactly like `gate.GateContext`/`gate.Finding` are\none hand-written Go file that `gateextract` turns into a Yaegi symbol\ntable:\n\n```go\n// internal/domain/eda/module/notify/types.go (hand-written, the schema source)\npackage notify\n\n// SchemaVersion is independent of a playbook's own workflow_version, per\n// eda-playbook-engine.md's schema-versioning point.\nconst SchemaVersion = 1\n\ntype Args struct {\n Channel string\n Message string\n}\n\ntype Result struct {\n Delivered bool\n}\n\n//go:generate go run github.com/traefik/yaegi/cmd/yaegi extract -name notifyextract github.com/samcharles93/archie-core/internal/domain/eda/module/notify\n```\n\nA Yaegi module implementing this kind exports a fixed function name\nagainst these generated types, resolved the same way `gate.Check` is:\n\n```go\n// operator's notify.go, interpreted at load\npackage notify\n\nfunc Run(a notify.Args) notify.Result { ... }\n```\n\n`internal/domain/eda/module/notify` is the schema; `notifyextract.Symbols`\nis its generated Yaegi bridge; the operator's file is the implementation.\nThis is the same three-way split `internal/gate` / `gateextract` /\n`.archie/gate.go` already has.\n\n## The registry: `ModuleRegistry`, keyed by kind, not a service locator\n\nPer invariant 2 (owning family manager) and invariant 4 (narrow host\naccess): a `ModuleRegistry` in `internal/domain/eda/module` maps a kind\nname (`\"notify\"`, `\"image-gen\"`) to a resolved, type-erased invoker --\nthe same `map[string]reflect.Value`-shaped erasure `wfextract.Symbols`\nalready uses to bridge Yaegi and Go, not a new pattern and not exposed as\nthe plugin's contract with the daemon (the plugin still writes and is\nchecked against a fully typed `func(Args) Result`; the registry's\ninternal storage is the only place erasure appears, exactly as it already\ndoes inside `wfextract`).\n\n```go\ntype ModuleRegistry struct {\n // kind -\u003e (validate args against generated schema, invoke, marshal result)\n}\n\nfunc (r *MoLine truncated
},
{
"url": "/dev/prds/multi-action-playbooks/",
"title": "Multi-action playbooks and typed action results",
"section": "PRDs",
"body": "# Multi-action playbooks and typed action results\n\n**Status:** Approved\n**Date:** 2026-09-22\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-nx30` (unblocks `archie-core-t2db.27` and `archie-core-t2db.31`)\n\n## Why this exists\n\n`eda-playbook-engine.md`'s hard boundary rejects any playbook that is not\nexactly one `workflow` action, so the parent document's data-flow, Module and\nChannel/Forge decisions have no loadable shape to attach to. The boundary's own\nstated condition is now met: both execution-time gaps are resolved\n(`eda-playbook-engine.md`, \"Execution-time gaps\"; the `playbook_dispatches`\nledger). This document designs the relaxation.\n\n## A playbook is one of two shapes\n\n- A **workflow playbook** is exactly one `workflow` action. Unchanged: it names\n a workflow definition and is routed by the daemon's definition pin.\n- An **action playbook** is one or more `module` actions in order. Each action\n has an optional `id`, a `kind` naming a registered Module kind, `args`, and an\n optional `when`.\n\nOne playbook does not mix the two shapes.\n\n```yaml\ntrigger: { kind: bug }\nactions:\n - id: build\n position: module\n kind: log\n args: { message: '\"build started\"' }\n - id: done\n position: module\n kind: log\n args: { message: '\"done: \" + string(actions.build.result.written)' }\n when: actions.build.result.written == true\n```\n\nThe first Module kind is the side-effect-free `log` kind\n(`module-position.md`, \"Recommended first slice\"). A Module kind with an\nexternal side effect, and the Channel and Forge positions, are out of scope.\n\n## A result type is the kind's generated Result struct\n\nEach Module kind owns a hand-written `Args` and `Result` struct\n(`internal/domain/eda/module/log` is the worked example); `ModuleRegistry.Invoke`\nreturns the result as a flat `map[string]any`. `ModuleRegistry.DecodeResult`\n(`internal/domain/eda/module`) is the single site that converts that map into\nthe kind's `Result` struct before a later expression reads it, so the value the\nchecker validates and the value the run reads have one definition.\n\n`actions.\u003cid\u003e` is typed by the kind of the action that declares `\u003cid\u003e`:\n`{ result: \u003cKindResult\u003e }`. `event` stays `dyn` (J4,\n`playbook-expression-syntax.md`).\n\n## Reject-at-load, preserved\n\nRelaxing the boundary must not make a bad reference resolvable. The load fails,\nnaming the playbook and the offending action, for:\n\n- an `id` missing where a later action references it, duplicated, or outside\n its shape's grammar: a workflow action id keeps the shared\n stable-identifier grammar (J1, already enforced), while a module action id\n must be a lowercase CEL field name writable as `actions.\u003cid\u003e` (so a CEL\n keyword such as `in`, `true`, `false`, or `null` is rejected at load);\n- an `actions.\u003cid\u003e` read of an id no earlier action declares;\n- an `actions` read that is not statically resolvable to an id (any map index,\n literal or dynamic, `in`, a comprehension): the typed `actions` root is an\n object type, so only field selection `actions.\u003cid\u003e` resolves and the\n `actions[\"id\"]` spelling is not accepted;\n- a `result` field the referenced kind's `Result` does not define;\n- a reference to an earlier action that produces no result;\n- an unknown `position`, an unknown `kind`, or a `module` action with no `kind`;\n- a field belonging to the other shape (`kind` on a `workflow` action, or\n `workflow` on a `module` action);\n- an arg KEY the kind's `Args` schema does not define;\n- an arg value whose checked CEL type cannot fill its `Args` field (`'123'`\n for a string field). A `dyn` value, such as an `event` read, passes: its\n type is known only per event, and the module decode refuses a bad one at\n run.\n\nDeclaring the kind's `Result` schema to CEL at load makes a result-field typo a\nload failure rather than a dispatch failure. Matching arg keys against the\nkind's `Args` schema makes an arg-key typo or a wrongly typed value a load\nfailure.\n\n## The environment is per playbook\n\nResult typing depends on the ids a playbook declares and the kind each id runs,\nso the CEL environment is built from one playbook's action list rather than once\nper `Store`, and `expr.NewEnv` takes that list: each declared id becomes a field\nof the `actions` object typed by its kind's `Result`.\n\n## Running an action playbook is out of scope\n\nThis document makes an action playbook load and its references type-check.\nRunning one is designed in `docs/prds/action-playbook-run.md`.\n\n## Decisions\n\n**D1 — dispatch before `t2db.31`.** Superseded by\n`docs/prds/action-playbook-run.md`. Was: an action playbook loads and\nvalidates but is not routed; the definition-pin dispatch reports no match for it,\nand the daemon logs a visible warning naming it.\n\n**D2 — mixing positions.*Line truncated
},
{
"url": "/dev/prds/news-and-releases/",
"title": "Public news and per-version release notes",
"section": "PRDs",
"body": "# Public news and per-version release notes\n\n**Status:** Approved\n**Date:** 2026-09-21\n**Beads issue:** `archie-core-2ncm.2`\n**Superseded in part:** `docs/prds/release-stream-and-commit-rules.md` defines the\nsingle release stream. `CHANGELOG.md` carries every release and one `vX.Y.Z` tag\nnames each release.\n\nThe Astro website renders public news and per-version release notes from the\nartifacts generated here. Both derive from `CHANGELOG.md`, so publishing a\nrelease adds no writing.\n\n## Source of truth\n\nRelease notes come from the frozen sections in `CHANGELOG.md`:\n`tools/release.sh --prepare` writes a section, and `--tag` refuses to tag a\nversion without it. The generated artifact has one entry per release version.\n\nTags and raw commits are not the source. The changelog is the edited release\nrecord, and its `## [\u003cversion\u003e] - \u003cdate\u003e` headings provide the version and date.\n\n## Release data\n\nThe generator skips `## [Unreleased]`. Any other `## [` heading that is not\n`[version] - date` stops generation. A relative Markdown link in a changelog\nbody also stops generation because the Astro site must be able to render the\ncontent without depending on repository-relative paths.\n\n`archied` and `archie-agent` version independently. Each\n`docs/news/releases.json` entry carries the tag prefix (`archied`, `archie`),\nproduct name (`archied`, `archie-agent`), version, date, and changelog body.\n`docs/news/redirects.json` maps retired per-component news URLs to each unified\nrelease route. The Astro site must apply this table so previously published\nrelease URLs continue to resolve.\n\nBoth JSON files are committed generated artifacts. `task news` regenerates\nthem, `task news:check` detects drift, and `tools/release.sh --tag` regenerates\nand stages them with the release commit. The Astro site renders from these\nartifacts rather than re-parsing `CHANGELOG.md`.\n\n## Site ownership\n\nThe Astro website is maintained outside this repository and serves the\ndocumentation at `offloaded.dev/docs/`. This repository generates and validates\nthe news and documentation data artifacts; it does not build, preview, or\ndeploy the Astro site.\n\n## Not in scope\n\n- Generated summaries, categories, or section headings; the changelog has no\n structured summary field to derive one from.\n- Per-release download or install links; where to get the artifacts is\n documented once, not restated for every release.\n- Hand-written news items.\n- Changes to `infra/ansible` or to the external Astro website repository.\n\n## Verification\n\n- `go test ./tools/newsgen/...` covers parsing, ordering, artifact generation,\n heading and link refusals, and check-mode drift.\n- `task news:check` passes inside `task check`.\n- `task docs:artifact:check` verifies the generated documentation data against\n its Markdown sources.\n"
},
{
"url": "/dev/prds/orgs-and-access/",
"title": "Orgs, workspaces and access control",
"section": "PRDs",
"body": "# Orgs, workspaces and access control\n\n**Status:** Approved\n**Date:** 2026-09-24\n**Parent:** `docs/prds/event-automation.md`, epic `archie-core-t2db`\n\n## Why this exists\n\nArchie has no tenant boundary and no access control: one operator, one shared\ntoken, and no org on any record. The event automation design needs orgs to own\nsources, bindings, workflows and agents, and an agent's reach must be decided\nby the policies over it, never by the event that started it.\n\n## Concepts\n\n- **Org.** The tenant boundary. An instance admin creates an org and adds its\n first owner. An owner or admin adds further members by the sign-in\n provider's subject or email.\n- **Workspace.** A division of an org, named freely (`networking-prd`,\n `service-desk-dev`), with an optional `environment` attribute (any string)\n that policies can test. Sources, event types, mappings, bindings and runs\n belong to a workspace.\n- **Identity.** Every principal is an identity (`internal/domain/identity`):\n - a person is an identity of kind `user`, bound to the sign-in provider\n through the existing subject binding;\n - an agent is an identity of kind `bot` or `service_account`, assigned to\n one org and granted access, secrets and permissions the way a user is.\n\n Signing in and verifying credentials stay separate from identity; identity\n is who acts. Memberships, roles, grants and audit records all reference the\n identity ID.\n\n- **Instance admin.** Operates the installation: orgs, the sign-in provider,\n instance policies. Instance admins see an org's resources only as members\n of it.\n\n## What belongs where\n\n| Level | Owns |\n| --------- | ---------------------------------------------------------------------------------------------------------------- |\n| Instance | the shipped workflow catalogue, instance policies |\n| Org | members, identities and their grants, secrets, agent profiles, workspaces, org workflows and their enabled state |\n| Workspace | sources, event types, mappings, bindings, runs, captures, run events and logs, chat sessions, memory |\n\nEvery owned record carries its `org_id`, and workspace records also carry their\n`workspace_id`. An identity, secret or profile is used in a workspace only\nafter the org grants it to that workspace.\n\nA secret is granted to an identity. An agent profile holds the container\nimage, tools and network access, and no secrets; this supersedes the secret\nreferences in `event-automation.md`'s agent profiles.\n\nA workflow names the identity it runs as. A workflow called by another runs\nas its own identity, and the caller's identity must be permitted `run` on it.\n\n## Access decisions\n\n### Where it lives\n\n- `internal/domain/access` owns the policy schema, the action list, how\n principals and resources are turned into policy entities, and the\n `Authorizer` contract.\n- The Cedar implementation, using `github.com/cedar-policy/cedar-go`, lives in\n `internal/infrastructure/access`; `internal/app` wires it.\n- Exactly two places call the `Authorizer`: the dashboard and API request\n path, and dispatch. Every other service verifies a credential and never\n evaluates policy.\n\n### The model\n\n- **Principal:** an identity, with its memberships, roles and grants.\n- **Resource:** the record acted on, with its workspace and org as parents,\n its type, owner and state.\n- **Action:** one of `read`, `create`, `update`, `delete`, `approve`, `run`,\n `read_logs`, `read_secret`, `manage_members`, `manage_identities`,\n `manage_policies`.\n- **Context:** the event's signature result, the address it came from, the\n time, and the run and step when the principal is an agent.\n\n### The policy chain\n\n```\ninstance (+ network rules) ─▶ org ─▶ workspace ─▶ identity + workflow ─▶ object\n```\n\n- **Instance** policies hold across every org. They include network rules:\n which addresses may deliver events to any source on the instance.\n- **Object** policies attach to one object (an event source, a secret, an\n identity, a binding, a workflow): \"only `soc-responder` may read this\n secret\", \"this source accepts events only from 10.20.0.0/16\".\n- A request is allowed only if every level with policies for it permits it. A\n lower level narrows and never widens; a forbid at any level wins; with no\n permit the request is denied.\n- The shipped role policies mean the org level always has policies, so an\n object or workspace policy alone can never grant access.\n- Archie ships an instance policy, which no org can remove, forbidding any\n principal to act on a resource outside the orgs it belongs to.\n\n### Storing and changing policies\n\n- Policies are stored in the State Store per level, versioned, and every\n changeLine truncated
},
{
"url": "/dev/prds/payload-field-mapping/",
"title": "Payload field mapping -- decision",
"section": "PRDs",
"body": "# Payload field mapping -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.3`, depends on `t2db.1`, blocks `t2db.4`\n\nAnswers what a \"mapping\" is, where it lives, and what \"resolve against a\nreal event\" means precisely enough to implement. `t2db.4` (binding: matcher\n\n- mapping + workflow) is out of scope -- this bead ships the mapping\n concept and its preview only, as a standalone entity `t2db.4` will later\n reference by ID.\n\n## Decision: a new `internal/domain/mapping` package, SQLite storage\n\n\u003e Storage superseded: every store now lives in PostgreSQL behind\n\u003e `internal/domain/storecontract`, implemented in `internal/infrastructure/postgres`\n\u003e (`docs/prds/state-store-contract.md`). SQLite names below describe the\n\u003e original design.\n\n`internal/domain/mapping` owns the mapping vocabulary and the pure\nresolve/preview rule; `internal/store` persists it (mirrors\n`captures.go`'s shape exactly -- inline schema const, narrow store\ninterface, `*store.Store` implementation); `internal/webui/api_mapping.go`\nis the transport. This follows `docs/prds/event-capture-storage.md`'s own\nplacement precedent: `internal/store` is where this daemon's persistence\nalready lives, not `internal/infrastructure` (that layer holds\ncross-domain services -- config, eventbus, modelcatalog -- not this\ndaemon's primary store).\n\n### Why a domain package and not just a store table\n\nResolving a path against a payload and deciding \"missing vs null vs\ntype-changed\" is a rule, not a query -- CLAUDE.md's domain layer owns\n\"language, state, rules, operations\" precisely so this logic is testable\nwithout a database and reusable by `t2db.4`'s runtime trigger path without\neither package importing the other's transport concerns.\n\n## Mapping shape\n\n```go\ntype Mapping struct {\n\tID int64\n\tName string\n\tSourceHint string // free-text label (e.g. \"sentry\"), organisational only -- not enforced against Capture.Source\n\tFields []Field\n\tCreatedAt time.Time\n\tUpdatedAt time.Time\n}\n\ntype Field struct {\n\tName string // the name the workflow receives\n\tPath string // dot/bracket path into the payload, see below\n\tType FieldType // expected type, checked at resolve time\n\tRequired bool // Required=false + missing is not a failure; Required=false + wrong type still is\n}\n\ntype FieldType string // \"string\" | \"number\" | \"bool\" | \"object\" | \"array\" | \"any\"\n```\n\n`SourceHint` is advisory only: an operator authors a mapping by clicking\nthrough one example capture, but the mapping is not pinned to that\ncapture's exact source string, because `t2db.4`'s matcher (not this bead)\ndecides which events a binding applies to. Pinning here would duplicate\nthat decision in the wrong layer.\n\n## Path syntax\n\nDot-separated keys with `[N]` for array indices: `data.items[0].id`. No\nwildcards, no filters, no external library -- the grammar is exactly what a\nclick-through UI needs to express (this key, then this key, then this\nindex), and every path in a mapping was generated by clicking a value in a\nreal payload, never hand-written against a spec. A hand-rolled parser\n(~30 lines: split on `.`, strip `[N]` suffixes) is less risk than a new\ndependency for a grammar this small.\n\n## Resolve semantics (the preview AND the future runtime path)\n\n```go\nfunc Resolve(fields []Field, payload []byte) (values map[string]any, failures []Failure)\n\ntype Failure struct {\n\tFieldName string\n\tPath string\n\tReason string // \"missing\" | \"null\" | \"type_mismatch\"\n}\n```\n\nDecode with `json.Decoder.UseNumber()` (matches `webhookguard.RedactPayload`'s\nexisting convention) so int/float distinction survives for type checking.\nWalk each field's path independently -- one field's failure does not stop\nresolution of the others, because the whole point of preview is showing\nthe operator every problem at once, not the first one.\n\n- Path segment doesn't exist, or indexes past an array's length -\u003e `missing`\n- Path resolves to JSON `null` -\u003e `null`\n- Path resolves to a value whose JSON type doesn't match `Field.Type`\n (`\"any\"` always matches) -\u003e `type_mismatch`\n- `Required: false` suppresses `missing` only, never `null` or\n `type_mismatch` -- a field that's present but the wrong shape is always\n worth surfacing, since silently coercing it is exactly the \"agent\n confabulates around a blank field\" failure this bead exists to prevent.\n\n**This is the same function both consumers use.** `t2db.3`'s preview calls\nit against an operator-picked capture and renders every result, pass or\nfail, in the UI -- that satisfies this bead's \"fail loudly\" acceptance\ncriterion, because at this stage the only runtime consumer of a mapping\n_is_ the human previewing it. `t2db.4` will call the identical function\nwhen a live event triggers a binding and turn any nonLine truncated
},
{
"url": "/dev/prds/playbook-expression-syntax/",
"title": "Playbook data-flow and condition syntax",
"section": "PRDs",
"body": "# Playbook data-flow and condition syntax\n\n**Status:** Approved\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-t2db.14` (expression environment).\n\n**Decision:** CEL via `cel.dev/cel-go` (v0.32.0), pinned. One expression\nmechanism covers both an action's `when` condition and its `args` values.\n\n## The requirement, stated directly\n\nA playbook action is gated and parametrised by runtime data: (a) a condition\ndeciding whether the action runs; (b) a later action's `args` values referencing\nan earlier action's `Result` and the triggering event's fields. Both are **CEL\nexpressions**, evaluated against one evaluation context. There is no separate\ninterpolation syntax: CEL reads nested maps and fields natively, so `args`\nvalues that need data are written as CEL, and only plain literal args remain\nplain YAML scalars.\n\nBoth halves are read-only: expressions may read context values and compute a\nresult from them, never mutate, never call host functions, never perform I/O.\nCEL enforces this structurally (no side effects, linear evaluation when macros\nare bounded, cost-limited).\n\n```yaml\nactions:\n - id: build\n position: module\n kind: log\n args:\n message: '\"build finished\"' # literal\n when: 'event.label == \"bugfix\"' # gate on event field\n - position: module\n kind: log\n args:\n message: '\"done: \" + string(actions.build.result.written)'\n when: \"actions.build.result.written == true\"\n```\n\n## Trust boundary of the expression\n\nA playbook YAML is **operator-installed, in-process, daemon-privileged** -- the\nsame tier as `ModuleDir`/`PluginDir`/`SecretEngineDir` (module-position.md's\ntrust-boundary section): loaded from a configured directory at startup, never\nfrom a webhook body or task worktree. The schema-by-example flow uses live\nevents to _design against_; the saved playbook is operator-authored file content\nin an operator-configured location.\n\nTwo consequences:\n\n1. The expression string is **trusted**. Operator-authored config, not attacker\n input; no sandboxing against a hostile expression string is required. If a\n future playbook source is less trusted (auto-generated bindings from\n unauthenticated captures), that is the playbook-file trust tier moving -- the\n loader's acceptance check is the right place, not the evaluator.\n2. The **data the expression reads is NOT trusted** (decoded webhook body, prior\n results through the same pipeline). Robustness against hostile data is\n required: no panic on wrong-typed/missing fields, no unbounded cost on\n deep/cyclic maps, bounded evaluation time. CEL provides this structurally\n (cost limits, linear non-Turing-complete evaluation, error values instead of\n panics -- verified in the vetting record below).\n\n## The gate precedent is deliberately NOT copied\n\n`internal/gate/gateeval` evaluates arbitrary interpreted Go (`.archie/gate.go`)\nas the repo's conditional-logic precedent. That is the wrong precedent for\nplaybook conditions because this document's premise is: **YAML is pure\norchestration data; Yaegi is where imperative logic lives** (Problem section;\nmodule-position.md's \"no generic hook\" section). Yaegi snippets in YAML would\nmove imperative logic into the data layer -- the inversion this design exists to\nprevent -- and make playbooks un-lintable.\n\nThe line: conditions are **declarative predicates over runtime data, not\nprograms**. CEL is non-Turing-complete and side-effect-free, so it cannot become\na program; a condition that needs real logic gets a Module kind (Yaegi),\nreferenced by the action, not a stronger expression body.\n\n## Plugin-engine-rule interaction\n\nThe plugin engine rule forbids a generic `Module` interface with an `any`\npayload; it exists to keep static implementation contracts typed. Evaluating CEL\nagainst runtime `map[string]any` is **not the same problem**: the rule concerns\n_implementation contracts_ (static operations a capability family exposes), not\n_runtime data values_ (legitimately dynamic -- an event payload's shape is\nunknown until it arrives). The Module contract stays fully typed (generated\n`Args`/`Result` schemas); CEL is a read-only data reader under the playbook\nengine family, not a new capability contract. Stated once.\n\n## Minimum viable evaluation context (what expressions see)\n\nOne flat context, namespaced from the playbook run, built at dispatch time:\n\n| Name | Type | Source |\n| --------- | ------------------------ | ---------------------------------------------------------------------------------Line truncated
},
{
"url": "/dev/prds/plugin-settings-live/",
"title": "Plugin settings reconcile live",
"section": "PRDs",
"body": "# Plugin settings reconcile live\n\n**Status:** Draft\n**Revision:** 2\n**Tracking:** GitHub [#1154](https://github.com/samcharles93/archie-core/issues/1154), epic [#998](https://github.com/samcharles93/archie-core/issues/998)\n**Authority:** `docs/prds/runtime-control-plane.md` decides each feature owns how\nits changes take effect; `docs/architecture/plugins-and-extensions.md` owns the\nplugin engine rule; `docs/prds/control-plane-apply-status.md` owns where apply\nreports go.\n\n## Outcome\n\nAn operator drops a plugin, module or secret-engine file into a configured\ndirectory while archied runs, and the daemon loads it without a restart. An\nedit to an installed file replaces what is running. A delete never stops running\ncode; apply status says so. A stored `plugin-settings` change applies live for\n`plugin_dir`, `module_dir` and `secret_engine_dir`; a change to `skills_dir` is\nrefused.\n\n## Triggers\n\n`PluginSettingsKind` joins `runtimeResourceKinds` in\n`internal/app/archied/control_plane.go`, and its descriptor `ApplyMode` becomes\n`live` in `internal/app/controlplane/operational_settings.go`.\n\nA poller reconciles on the apply-status restamp interval, so a dropped file\nloads without a filesystem watch. Each tick re-runs both halves the boot path\nruns, against the directories in the running config: the directory loads\n(`secret.Registry.LoadDir`, `ModuleRegistry.Register`, `plugin.LoadDir`) and the\nlayering (`boot.runtimeConfig`), which re-resolves provider credentials. A\nprovider disabled at boot for an unresolvable engine is re-resolved on the first\ntick that finds it; a changed directory retargets the next tick without a\nrestart.\n\n## Rules\n\n- Adding and changing load; removing never unloads. Yaegi interpreters are not\n reclaimed while a caller still exists and there is no unload path; the running\n set can only grow. A removal stays outstanding in the apply-status error until\n the process restarts.\n- Each file is loaded through a fresh interpreter (the boot pattern) and\n content-hashed, so only new and changed files load.\n- A file that fails to load is skipped and reported; already-running code keeps\n running, the degrade-and-skip convention `plugin.LoadDir` and\n `Registry.LoadDir` already apply at boot. Boot keeps its reject-at-load rule\n for the module directory; a broken file at runtime skips without aborting.\n- A directory that does not exist reconciles to an empty set.\n\n## The three registries\n\n- **Secret engines** (`internal/secret`). Reconciliation re-runs\n `Registry.LoadDir` against the live directory. `Register` replaces by name, so\n an edited engine takes effect for the next resolution and a dropped engine\n resolves on the next tick. A deleted engine stays registered: existing\n references keep resolving through it until restart. Engines are stateless\n resolvers, so a swap needs no lifecycle step.\n- **Modules** (`internal/domain/eda/module`). Reconciliation re-runs\n `ModuleRegistry.Register` for the kind's file. Playbook dispatch resolves\n through the registry at invoke time, so the swap reaches a running playbook\n store unchanged; a deleted file leaves the old invoker in place, running.\n- **Plugins** (`internal/plugin`). `Host` grows running-state operations beside\n `Register`, `Start` and `Stop`, and `Register` keeps its rule that\n registration is allowed only before the first `Start`, so these are new host\n methods rather than a relaxed `Register`. One adds a single module while the\n host is running: inserted in dependency order, started alone, and rolled back\n alone on failure, leaving every previously started module running. The other\n replaces a module whose manifest id matches: stop it, start the new one, and\n restart the old one when the new start fails; replacing a module another\n running module depends on is refused. A module's `Start` is its only check\n (`plugin.Module` has no probe, and one manifest id cannot be registered\n twice), so a replacement checks by starting and keeps a rollback rather than\n switching first. These operations obey the plugin engine rule: the host\n invokes start and stop itself and isolates the failure to one module. A\n deleted file makes no host call: the module runs on.\n\n## `skills_dir`\n\n`skills_dir` is not part of this change. The daemon refuses a `plugin-settings`\ndocument whose `skills_dir` differs from the value in force. The check is a\npre-layer comparison on the live path (`boot.applyRuntimeResourceUpdate` in\n`internal/app/archied/control_plane.go`), not an addition to\n`validatePluginSettings` in `internal/app/controlplane/operational_settings.go`,\nwhich stays value-agnostic per the #1143 decision recorded there: a\nchange-immutability rule needs the running config, and #1143's validates-nothing\nstill holds for values. The write lands, the store keeps the version, the daemon\npublishes nothing, the refusal is reported against that stored versLine truncated
},
{
"url": "/dev/prds/pr-review-agent/",
"title": "PR review agent",
"section": "PRDs",
"body": "# PR review agent\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md`; supersedes the earlier\nreviewer executor and blocking rule.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (every agent\ncall is a StepExecution), `docs/prds/external-agent-harness.md` (any agent\nstep may run on a harness), `docs/prds/inline-review.md` (posting),\n`docs/prds/pr-review-remediation.md` (consumes the findings).\n\n## Decision\n\nArchie ships a pull request reviewer as its first end-to-end product. It\nreviews any pull request on a watched repository, a PR an operator names, and\narchie's own PRs before they open.\n\nThe reviewer is a fixed pipeline, not a single agent. The review strategy is\ngenerated per PR: three lens agents propose review dimensions from the PR's\ncontent, one reviewer definition runs once per dimension, and later agents\nverify, challenge and combine the findings. Everything that can be computed\nis code: diff parsing, clustering, blast radius, evidence extraction,\nscoring, deduplication, line mapping and the review event.\n\nThe pipeline is **recall-first**. It posts every evidenced finding above the\nconfidence threshold, up to the comment cap. A precision gate exists as an\noperator dial and is off by default.\n\nAcceptance is measured, not asserted: see Verification.\n\n## Pipeline\n\nEach numbered phase is a stage of the `pr-review` workflow. Each agent call is\nan `agent` StepExecution; fan-out phases record one child per call.\n\n1. **Intake.** Code reads the PR metadata and diff statistics: type,\n complexity, languages, areas touched, risk signals. Depth comes from lines\n changed: under 100 is `quick` (at most 3 dimensions), under 500 is\n `standard` (6), otherwise `deep` (12). An operator may set depth\n explicitly.\n2. **Anatomy.** Code parses the diff into files and hunks, clusters related\n files, and computes the blast radius: unchanged files that import or are\n imported by changed files. One agent writes the PR narrative, risk\n surfaces, changes that do not fit the narrative, and gaps between the\n description and the diff.\n3. **Dimension selection.** Three lens agents run in parallel over the intake\n (including its machine-written score), anatomy and diff, each able to read\n the repository. A PR that intake scores as likely machine-written adds a\n hallucination-check dimension: claims, citations and behaviour the diff\n does not actually implement.\n - **behaviour:** where the old and new code diverge for any input; API\n contracts, concurrency and state, security, error handling, data flow;\n - **mechanics:** whether the code runs at the language and framework\n level; types, signatures and every caller, decorators and middleware,\n framework contracts, imports;\n - **fit:** patterns, complexity, abstraction, test adequacy, documentation\n that no longer matches, dependencies, migration completeness.\n\n Each lens returns review dimensions: a name, a reviewer prompt written for\n this PR, target files, context files and a priority. Code merges them,\n drops duplicates and keeps the highest-priority dimensions up to the\n depth's cap.\n4. **Review.** One reviewer definition runs once per dimension, in parallel,\n at most 8 at a time. Each reads its target and context files and may\n follow references. Each finding carries file, line range, severity\n (`critical`, `important`, `suggestion`, `nitpick`), title, body, an\n optional suggested fix, quoted evidence, confidence and tags. A reviewer\n that exhausts its turn cap or deadline before its terminal tool call\n records a distinct StepExecution status from a reviewer that completed\n and found nothing; synthesis and the posted review treat the two\n differently (the former is unreviewed, the latter is reviewed-clean).\n5. **Verification layer**, over the review findings:\n - code extracts an evidence package per finding: the code at the cited\n lines and snippets from its callers;\n - an evidence verifier checks high-priority findings against their\n packages;\n - an adversary confirms or challenges each finding, looks for issues every\n reviewer missed, and is more sceptical when intake scores the PR as\n likely machine-written;\n - a compound agent looks, within each cluster of confirmed findings, for\n defects that only exist in combination.\n6. **Coverage and consistency**, in parallel:\n - a coverage gate checks every cluster and high-exposure blast-radius file\n was reviewed, and runs gap reviewers for what was not, at most 2 rounds;\n - consistency verification lists every cross-location obligation the\n changed code creates (what must be true elsewhere for this line to be\n correct), then verifies each by reading both ends. A broken obligation\n becomes a finding.\n7. **Synthesis**, code only:\n - score = severity weight (1.0, 0.7, 0.3, 0.1) ×Line truncated
},
{
"url": "/dev/prds/pr-review-operator-response/",
"title": "PR review: the operator's answer to the approval gate",
"section": "PRDs",
"body": "# PR review: the operator's answer to the approval gate\n\n**Status:** Draft\n**Authority:** `docs/prds/pr-review-agent.md` (\"Operator approval\") for the gate, and `docs/prds/state-store-contract.md` (rev. 2e) for every task field that crosses the State Store.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a run cannot resume partway through its stage list).\n\n## Decision 1 — where the operator answers\n\nThe dashboard's `POST /api/tasks/{id}/action` (`internal/webui/api_tasks.go`, `handleTaskAction`) is the authoritative surface: the only one that resolves the actor from a credential and can carry a payload. Chat is a shortcut, not a second authority — `/approve` (`internal/gateway/gateway.go`, `Router.handleApprove`) answers the post decision with every offered finding selected, and gains no instruction or selection syntax.\n\n`taskstate.Action` gains `rereview`, and `taskstate.Actions` returns `approve`, `reject` and `rereview` for `WaitingHuman`. `approve` posts the review, `reject` discards it through the existing terminal decline, `rereview` reruns the review phases with instructions. The action body carries `instructions`, required by `rereview`, and `findings`, the finding keys `approve` posts; an absent selection means all of them.\n\nThe path is `handleTaskAction` → `applyOperatorTaskAction` → `Chat.Contract.ApplyOperatorTaskAction` → the daemon's `LocalChatAdapter` → `taskactions.Client` (NATS `archie.gateway.task-action`) → `taskactions.Service.Apply` → one guarded store write that records the decision and requeues. Chat's `/approve` path (`StoreTaskController.Approve` → `chatTaskControllerAdapter.ApproveChatTask`) must reach that same write through the same function, so the two surfaces cannot record different decisions for one operator intent.\n\nA requeue resumes the workflow the waiting state names, never a name the handler hardcodes. `taskactions.Service.apply` and `chatTaskControllerAdapter.ApproveChatTask` requeue with an empty workflow, which `Requeue` reads as \"keep the task's\", so neither surface hardcodes a workflow name: an approval whose wait recorded `pr-review` resumes `pr-review`. The feasibility handoff therefore has to name `implement` on the task before it enters the wait, which is the invariant the handler relies on — the workflow a task carries is the workflow it runs next. `Requeue` treats an empty workflow as \"keep the task's\".\n\n### The review the operator answers\n\nThe gate writes the review it is holding onto the task before it ends the run: one JSON column, `review_gate`, a sibling of `review_payload`, holding the scored findings, the head SHA, the pull request's identity and the workflow the wait resumes. The run's existing `Store.Update` persists it. The same column carries the answer back: the response path's guarded write fills in the outcome, the selection and the instructions, and clears the offer for a re-review.\n\nThe operator reads the offer through the existing task read — `taskView.Task` on `GET /api/tasks` and `GET /api/tasks/{id}/debug` — so no new read endpoint is needed.\n\nThis record is load-bearing because the run that computed the findings ends at the gate and the engine cannot resume it partway. Without it, \"post the selected findings\" cannot mean the findings the operator saw: the resumed run recomputes them with agent calls. An `approve` resume therefore posts the recorded review filtered by the selection, and the review the resumed phases recompute never reaches the output.\n\n## Decision 2 — the cap\n\nThe cap is a column: `rereview_rounds` on `tasks`, `bigint NOT NULL DEFAULT 0`, read by the response path and incremented in the same guarded write that requeues a re-review. A re-review at the cap is refused with the conflict sentinel the dashboard answers 409 with, and nothing is requeued. Two is a constant in the domain, not a config knob: the PRD fixes it.\n\n`Task.Attempt` cannot carry the count, because it counts every requeue. The two alternatives are worse.\n\n- The execution tree measures passes through the gate, not operator requests. A crash recovery (`RecoverStale`) or an operator retry re-runs the pipeline to the gate and would consume the cap; and a stage has no step read (`task.Store` carries none), so this route needs a new interface method anyway.\n- `Task.Notes` is the agent memory ledger, not scratch. `AgentStage.buildRequest` passes it into every generic agent request, `agentexec` renders it as a prompt section, and `persistAppendedNotes` appends to it. A counter parsed out of a field agents write to is the encoded-state defect this repository rejects, and instructions parked there would reach every unrelated workflow's agents.\n\n`RemediationRounds` is the precedent: one writer, one reader, one meaning, kept separate from `RetryCount` so unrelated retries cannot draw a budget down.\n\nThe write crosses the State Store. A goose migration adds the column; `Line truncated
},
{
"url": "/dev/prds/pr-review-remediation/",
"title": "PR review comment remediation -- decision",
"section": "PRDs",
"body": "# PR review comment remediation -- decision\n\n**Status:** Approved\n**Date:** 2026-09-10, amended and ratified 2026-09-19\n**Beads issue:** (filed as `archie-core-…`, parent: `archie-core-7d5u` event sources and typed reactions)\n\nAnswers: how archie reacts to review comments on a PR it opened, from a human\nor from another review bot, and remediates them. Built on two settled decisions — the review pipeline's\nisolation contract (`docs/prds/pr-review-agent.md`, \"Isolation\") and the\nevent-sources decision (`docs/prds/event-sources-and-reactions.md`) — plus the\nwebhook intake security contract (`docs/prds/webhook-intake-security.md`).\nNothing here re-decides those; it names the one concrete reaction each one's\nmachinery was built to carry.\n\n## Problem\n\nArchie opens a PR (`pr_open`) and then never learns what a human said about\nit. `forge.Forge` has no method to list PR reviews or review comments; the\ndaemon poll loop finds only new issues; the forge webhook receiver\n(`internal/forge/webhook/receiver.go`) decodes only `issues` events and\nexplicitly ignores `pull_request` events. A \"requested changes\" review, or an\ninline comment on a line, is invisible work.\n\n## Decisions\n\n### 1. Read surface: a narrow `PullRequestReviewReader`, type-asserted\n\nA new forge interface, implemented by GitHub and Gitea, not folded into the\nfat `Forge` interface (the h019.8 `PullRequestReader` precedent — the noop\nforge cannot honestly provide it):\n\n```go\ntype ReviewComment struct { ID int64; Author, Body, Path string; Line int; InReplyTo int64; CreatedAt time.Time }\ntype Review struct { ID int64; Author, State string /* requested_changes | approved | commented | dismissed */; SubmittedAt time.Time }\n\ntype PullRequestReviewReader interface {\n ListReviews(ctx, owner, repo string, number, sinceID int64) ([]Review, error)\n ListReviewComments(ctx, owner, repo string, number, sinceID int64) ([]ReviewComment, error)\n // ReplyToReview posts a reply to a review or comment thread.\n ReplyToReview(ctx, owner, repo string, number, inReplyTo int64, body string) error\n}\n```\n\nGitHub: `pulls/{n}/reviews` + `pulls/{n}/comments`; reply via\n`pulls/{n}/comments/{id}/replies`. Gitea: `pulls/{n}/reviews` +\n`pulls/{n}/comments`; reply via `pulls/{n}/comments/{id}`. `sinceID` is the\ncursor for both poll and webhook dedup.\n\n### 2. Event source: webhook first, poll as the universal backstop\n\n- **Webhook (GitHub, low latency):** extend `receiver.go` to also decode\n `pull_request_review` and `pull_request_review_comment` events, behind the\n existing HMAC verification, producing the same reaction as the poller. The\n receiver stays a forge-intake surface — not the generic chat webhook, not a\n new generic receiver (7d5u decision 4).\n- **Poll (both forges, no webhook dependency):** a periodic scan of `pr_open`\n tasks calls `ListReviews`/`ListReviewComments` with a persisted `sinceID`\n cursor per task. This is the Gitea path and the deployment-without-webhook\n path; it must stay first-class, not a legacy fallback (the repo's own\n webhook-intake rule). It is **one shared scan over all `pr_open` tasks**,\n not a scan inside each identity's poll loop, and it calls the forge client\n the scanned task's own identity owns. This is `reconcilePRs`'s shape\n exactly (`internal/daemon/daemon.go`: `Store.OpenPRs` then `forgeFor(\u0026t)`).\n A per-identity scan would call one identity's forge client against another\n identity's PR.\n\nBoth paths emit the **same** typed reaction, so `PublishUnique` dedups them\nfor free — the `TaskEnvelope.IdempotencyKey` pattern (7d5u decision 4) applied\nto reviews.\n\n### 3. Reaction contract: producer-only, resolves to an existing task\n\nA new `workintake.ReviewCommentEnvelope{Owner, Repo, PRNumber, Kind, CommentID,\nReviewID, Author, State, Body, Path, Line}`. Idempotency key is\n`owner/repo/pr-number/kind/id` — source-independent, so a webhook delivery\nand a poll of the same comment collapse.\n\n`Kind` (`review` or `comment`) is part of the key because a review ID and a\nreview-comment ID come from independent forge sequences. Keying on the bare id\nlets a review and an inline comment on the same PR collide, silently dropping\none of the two. This is a producer-only reaction\n(7d5u decision 3): it never vetoes or mutates in-flight work; the target task\nis idle (`pr_open`).\n\nThe daemon resolves `PRNumber` → the task that owns it. An unmatched PR (not\nan archie task) is dropped with a counter — a public webhook must not be able\nto start an agent against an arbitrary repository. A PR whose task is merged,\nclosed or archived is dropped through the same counter: the reaction is only\never work against a PR archie itself opened _and still owns_.\n\nThat lookup does not exist. `pr_number` is written by\n`internal/infrastructure/postgres/store.go` and never read in a `WHERE` clause, so this needs a\n`TaskStore` method keyeLine truncated
},
{
"url": "/dev/prds/progressive-tool-disclosure/",
"title": "Progressive tool disclosure (bridge tools) — wiring",
"section": "PRDs",
"body": "# Progressive tool disclosure (bridge tools) — wiring\n\n**Status:** Finalised\n**Date:** 2026-08-15\n**Compound:** the \"keep the LLM tool schema small, give full access on demand\" work (issue #167)\n\n## Decision\n\nThe bridge-tool pattern is **implemented and tested** in\n`internal/tools/disclosure.go` (`tool_search`, `tool_describe`, `tool_call`\n\n- `ContextPressureGate` + `DisclosureMode`, section 17.14/17.15) — but it is\n **never wired into the daemon**. `BridgeTools` and `ContextPressureGate` are\n referenced only in `disclosure_test.go`. This task is therefore a **wiring**\n task, not a feature build.\n\nWire the existing bridge into the per-chat-turn toolset:\n\n1. **Compose a per-turn registry** seeded from the base registry plus the\n per-turn extra tools, register the bridge tools into it, and hand it to both\n the bridge handlers and the `ContextPressureGate`.\n2. **Run the gate in `chatGenerateOptions`** (`internal/app/archied/main.go`)\n so it decides full-vs-bridge disclosure per turn, and build the\n `core.ToolSet` from the gate's filtered output.\n3. **Thread the model's context window** into the preparation seam so the gate\n has a real `ContextWindowSize` (it disables itself at 0, falling back to\n full disclosure).\n\n## Why the naive \"register extras into the base registry\" is wrong\n\n`BuildToolSetFrom` (`internal/agentexec/toolset.go`) documents the invariant:\n\n\u003e the task tools carry the calling gateway's identity, so there is one set of\n\u003e them per gateway and they **cannot live in the process-wide registry**.\n\nThis is confirmed by wiring: gateways are per-channel\n(`telegram_setup.go` build a `TurnRunner` per channel), and the extra\ntools (`task_*`, `session_*`, `dashboard_*`) close over that channel's identity\nvia `TurnRunnerConfig` (`turn.go`). Registering them into `b.toolReg` would\nlet channel A's session/identity-bound tools be invoked by channel B — a real\ncross-channel privilege bug. The bridge handlers iterate `reg.All()`\n(`disclosure.go`), so the extras must be discoverable; the fix is a\n**per-turn composed registry**, not a mutation of the process-wide one.\n\n## Shape of the change\n\n### 1. Per-turn composed registry + gate inside `chatGenerateOptions`\n\nReplace the current base-set + extra-set merge (`main.go`) with a single\ncomposed-registry pass:\n\n```go\n// new helper, in internal/tools/disclosure.go or the archied wiring package\nfunc ComposeForTurn(reg *tools.Registry, extra []tools.ToolEntry) (*tools.Registry, error) {\n composed := tools.NewRegistry()\n for _, e := range reg.All() {\n if err := composed.Register(e); err != nil { return nil, err }\n }\n for _, e := range extra {\n if err := composed.Register(e); err != nil { return nil, err }\n }\n if _, err := composed.RegisterBatch(tools.BridgeTools(composed)); err != nil {\n return nil, err\n }\n return composed, nil\n}\n```\n\n`chatGenerateOptions` then:\n\n```go\ncomposed, err := ComposeForTurn(registry, extra)\n// ...\ngate := tools.NewContextPressureGate(contextWindow)\ngate.SetAlwaysVisible(...) // e.g. session/session_resume, task/task_list\ndisclosed := gate.FilterTools(composed)\ntoolSet, err := agentexec.BuildToolSetFrom(disclosed, toolOpts)\n```\n\n`FilterTools` (`disclosure.go`) already returns `all` in full mode and\n`bridge + always-visible` in bridge mode, and `BuildToolSetFrom` re-applies\navailability/approval/schema rules, so the two layers compose cleanly.\n\n### 2. Thread context window through the preparation seam\n\n`ContextPressureGate` disables at `ContextWindowSize == 0`. The model context\nwindow is resolved in `TurnRunner.prepareTurn` (`turn.go`) but is not\npassed to `TurnModel.Prepare`. Extend the seam:\n\n```go\ntype TurnPrepareContext struct {\n Model string\n Extra []tools.ToolEntry\n ContextWindow int // model's context window in tokens; 0 = gate disabled\n}\n```\n\n`TurnModel.Prepare(ctx, context TurnPrepareContext)`; `prepareTurn` fills\n`ContextWindow` from `modelDetails.ContextWindow`. This touches one interface\n(`turn.go`), one production impl (`chat_turn_model.go`), and the test\nmock (`turn_test.go`).\n\n### 3. Bridge-handler parity note\n\n`bridgeCallHandler` calls `e.Handler` directly (`disclosure.go`), bypassing\n`toolExecute` — so a `tool_call` invocation does **not** apply `CapPayload` /\n`MaxResultSizeChars` spilling or `OnToolCall` reporting, and it pre-refuses\n`RequiresApproval` tools (`disclosure.go`). This is acceptable for the\nfirst wiring (the bridge is read-discover/describe plus a guarded call), but a\nlater hardening should route the invoked tool through the same\ncap/approval path the model's direct call uses. Recorded as a follow-up, not a\nblocker for this task.\n\n## Files touched\n\n- `internal/app/archied/main.go` — `chatGenerateOptions` composes + gates.\n- `internal/app/archied/chat_turn_model.go` Line truncated
},
{
"url": "/dev/prds/public-and-dev-docs/",
"title": "Public and development documentation -- design",
"section": "PRDs",
"body": "# Public and development documentation -- design\n\n**Status:** Draft\n**Date:** 2026-09-22\n\n## Problem\n\nOne published set carries both kinds of document. A reader who wants to know\nwhat Archie is and how to point an event at it lands in a sidebar that also\nholds the repository organisation rules, the migration decision register, the\npackage review procedure and five PRDs. The PRDs are there for a reason that\nhas nothing to do with the reader: settled architecture cites them, and the\ngenerator refuses a link whose target it holds back, so publishing them was the\nonly way to keep those citations alive.\n\nMixing them is not an exposure problem. Every one of these documents can be\npublic. It is a navigation problem: a customer reading the site meets\ncontributor material with no signal that it is not for them.\n\n## Decision\n\nOne source tree, two published sets, two artifacts, two URL bases.\n\n| Set | Holds | Served under | Artifact |\n| ----------- | ------------------------ | ------------ | ----------------------------------- |\n| Public | `index.md`, `guides/` | `/docs/` | `docs/data/generated/docs.json` |\n| Development | `architecture/`, `prds/` | `/dev/` | `docs/data/generated/dev-docs.json` |\n\n`archive/`, `inspiration/`, `news/` and `github-token.md` stay out of both, for\nthe reasons the generator already records.\n\nThe two artifacts have the same shape. A renderer reads a second file and\nserves it under a second base; it needs no new field and no set discriminator,\nbecause the file a page arrived in is the set it belongs to.\n\n## Consequences the design depends on\n\n**Every PRD publishes.** Selective PRD publication existed to keep citations\nfrom settled architecture working. With both cited and citing documents in the\ndevelopment set, that pressure is gone, and the rule that produced it goes with\nit: `prds/` is a development tree, not a list of exceptions.\n\n**Cross-set links resolve.** A link from a public page to an architecture page\nrewrites to the development set's absolute path, and the reverse works the same\nway. Both sets are generated in one pass over one url map, so a link and its\ntarget cannot disagree about where the target lives. The generator's refusal\nstill fires, now only for a target genuinely in neither set.\n\n**Assets keep the public base.** `docs/public/` is one file set, referenced\nfrom either set, and serving one file under two paths would invent a second\nlocation for it.\n\n**The sidebar stays derived from the directory layout**, per set. A page added\nunder a directory appears without a second edit, which is the property the\ncurrent generator has and the reason its tree mirrors the tree on disk.\n\n## The public set is thin, and that is the honest state\n\nTwo pages: the landing page and the playbook guide. Nothing is lost by the\nsplit, because a reader was never served by the seventeen architecture pages\nnext to them. The pages a public site needs (installation, configuration\nreference, the event sources, the actions a playbook can run) are written into\n`guides/` and a `reference/` tree as they are written, and each lands in the\npublic set with no generator change.\n\n## Verification\n\n- `task docs:artifact` writes both files; `task docs:artifact:check` fails on a\n stale copy of either, without touching the tree.\n- A link from the public set to a development page, and a link the other way,\n each resolve to the other set's base path in the generated body.\n- A link to a page in neither set fails the generator, naming the file, the\n line and the target.\n- `docsgen` accounts for both artifacts, so neither tool reports the other's\n file as unowned.\n"
},
{
"url": "/dev/prds/release-stream-and-commit-rules/",
"title": "One release stream, one page per version, and commit rules — decision",
"section": "PRDs",
"body": "# One release stream, one page per version, and commit rules — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** `RELEASING.md` for the process this changes, `AGENTS.md` for the\ncommit rules it enforces, and `tools/newsgen` for the artifact shape.\n\n**Supersedes:** `docs/prds/news-and-releases.md`, sections \"Source of truth\" and\n\"Two components\" — one changelog replaces two, and one page per version replaces\none page per component. Its remaining decisions stand.\n\n## Decision\n\n**A release is one version covering whatever changed.** One changelog holds every\nrelease section, one generated page holds every version's notes, and an operator\ncutting a release names one version.\n\n## One changelog\n\nEvery release section lives in `CHANGELOG.md`, newest first. `CHANGELOG.archied.md`\nand `CHANGELOG.archie.md` are deleted, and `CHANGELOG.md` stops being a pointer to\nthem. The changelog is the only source of release prose, and tags are not a source:\nCI and deployment check out shallow, so tags are absent from a site build while the\nchangelog is always present.\n\n### The merged history\n\nTwo version streams become one file, so a version that both components released\ncarries one heading and one date: **the newest date among that version's sections**,\nbecause a version's date is when the last part of it shipped. Where a component's own\ndate differs from it, that component's section label carries its own date, so the\nper-component fact survives the merge rather than being collapsed into the heading.\n\nThe merged history holds 65 versions: 33 that both components released, 31 only\n`archied`, and one only `archie`, from 64 and 34 sections respectively, so 98\npublished pages become 65. `## [Unreleased]` is not a release -- it carries no\nversion and gets no page -- but it stays at the top of the file, because it is\nthe one place unfinished work is recorded. Counting `##` headings rather than\nreleases overcounts by one.\n\nThis ambiguity is historical only. One version stream with one tag gives a version\nexactly one date, so the rule represents the merged past rather than a design that has\nto hold.\n\nThe merge is verified by content, not by the generator succeeding: the section count\nper source, the merged version set equal to the union of both sources with nothing\nextra, and every section title still present. A generator that agrees with the file it\njust wrote is evidence of nothing.\n\n## One version stream\n\n**`GATEWAY` and `RUNTIME` stop being release inputs.** `release:prepare` and\n`release:tag` take one version, and `tools/release.sh` loses the two flags.\n\nThey may stay as build-time stamps, because a binary must still report what it\ncontains. A release that must name three versions forces an operator to pass skip\nvalues for components that did not change, and that ceremony is what this decision\nremoves — along with the drift it allows, where two components' tags fall a release\napart.\n\n**Per-component detail stays, as sections inside the release.** A reader still needs\nto know whether `archied` or the agent changed; what goes away is the separate\nnumbers and the separate pages, not the information.\n\n**History is not re-tagged.** Existing tags keep their names, because tags are not a\nsource and nothing reads them to build a page. A future reader must not \"fix\" the\nunified changelog by rewriting tags to match it.\n\n## One release page per version\n\n`docs/news/\u003cversion\u003e.md` replaces `docs/news/\u003ccomponent\u003e/\u003cversion\u003e.md`, carrying the\nrelease's per-component sections inside it.\n\n**Every release URL already published keeps working.** `/news/archied/\u003cversion\u003e` and\n`/news/archie/\u003cversion\u003e` route to the unified page for that version. The generator\nemits the redirect table beside the pages so it cannot drift from them; if the\nrenderer needs the table in its own repository, that is a change in that repository\nrather than a hand-maintained list here.\n\n## The reviewer runs between prepare and tag\n\nRelease notes are prose, and the review agent exists to review prose. **`release:tag`\nrefuses to tag when the review has not been run for that version, or when it reports\nat the level.**\n\nThe invocation is verified rather than assumed. `tl rules --lint` reports `corpus ok`\nand exits 0. `tl review \u003cpath\u003e --deadline \u003cms\u003e --max-turns \u003cn\u003e` reports\n`0 findings (0 high, 0 medium) · 1/1 files reviewed · clean` and exits 0 on\n`docs/news/archied/1.36.0.md`.\n\n**`--fail-on` must be passed explicitly.** It defaults to `never`, so an invocation\nwithout it cannot refuse anything and the step would be decorative. `--fail-on high`\nis the level: a medium finding in a release note is worth acting on, and it should not\nstop a release on its own.\n\n**The rule is stated once.** It belongs in the reviewer's own rule set, which\n`tl rules --from-doc` can draft frLine truncated
},
{
"url": "/dev/prds/review-settings-resource/",
"title": "Review settings resource",
"section": "PRDs",
"body": "# Review settings resource\n\n**Status:** Draft\n**Beads issue:** `archie-core-0ry6`\n**Authority:** `docs/prds/runtime-control-plane.md` for the resource model,\n`docs/architecture/configuration.md` for ownership, and\n`docs/prds/pr-review-agent.md` for what the two dials do.\n\n## Decision\n\n`review.precision_gate` and `review.approve_before_post` are one control-plane\nresource, `review-settings`. The file's `[review]` section seeds it, the stored\ndocument outranks the file from then on, and the dashboard writes it through the\nsame settings machinery as every other resource.\n\nThe resource is deployment-wide, like every definition the State Store seeds\n(`storecontract.DefaultOrgID`): not per-repository, per-identity, or per-run.\n\n## Why its own kind\n\nThe two dials are pr-review policy — what a review may post, and whether a human\ndecides — not a limit on a task run. The document that carries task limits\nbelongs to that feature. `runtime-control-plane.md` splits settings by feature\nand refuses documents unrelated features share; `configuration.md` puts a typed\nruntime setting with the domain whose behaviour it describes. One document per\nfeature is the rule, not one document per settings page.\n\nA new kind also has no legacy documents. Its first value is the seed derived\nfrom the file, so \"the store outranks the file\" begins from an explicit copy of\nboth fields rather than from a document that predates them.\n\n## Document\n\nNew file `internal/app/controlplane/review_settings.go`:\n\n```go\nconst ReviewSettingsKind = \"review-settings\"\n\ntype reviewSettings struct {\n PrecisionGate bool `json:\"precision_gate\"`\n ApproveBeforePost bool `json:\"approve_before_post\"`\n}\n```\n\nIts `Definition` sets `ApplyMode: \"live\"`, `Document: reviewSettings{}`, and a\n`Seed` returning `reviewSettings{cfg.Review.PrecisionGate, cfg.Review.ApproveBeforePost}`,\nand a `Validate` wrapping `validateAs`: both fields are free booleans with no cross-field\nrule, so the validator is a named place to put one rather than an inline no-op\n(`validatePluginSettings` is the precedent). No `Normalize`, because the kind\nhas no second wire shape to converge.\n\n## Seeding\n\n`ImportConfig`/`seededValues` write the seed for a kind the store does not hold,\nso a deployment that never edited the dials runs the values in `[review]`. Once\na document is stored, the file key stops mattering, which is the rule for every\ndatabase-owned setting.\n\n## Apply\n\n`runtimeConfigFrom` in `internal/app/controlplane/runtime_config.go` layers the\nstored document over the file's `Review`, assigning `out.Review.PrecisionGate`\nand `out.Review.ApproveBeforePost` field by field. Field-by-field, not\n`out.Review = ...`: a field added to `config.Review` later keeps the file's value\nuntil the document carries it.\n\n`ReviewSettingsKind` joins `runtimeResourceKinds` in\n`internal/app/archied/control_plane.go`, so a new stored version re-runs the\nlayering and republishes through `config.Holder`. Live rather than\nrestart-required, because every consumer re-reads it: `Review` is on\n`reloadableFields` in `internal/app/archied/reload.go`, and the value reaches a\nrun through `Daemon.configFor` → `Config.ForTask` → `TaskConfig.ToConfig` →\n`TaskContext.Cfg`, which `stagePRPrecisionGate` and `stagePROperatorApproval`\nread. The next task run uses the new value; a run in flight keeps the value it\nstarted with.\n\n## Projection and page\n\n`BuildConfigView` gains a plain `Review` field carrying both values out of\n`cfg.Review`, the way `BudgetsView` carries the layered budgets, so the published\nconfig snapshot tells any reader what is in force. The Review page renders the\ntwo toggles from the control-plane store's draft for `review-settings` — the\nshape `SystemTasksPage.vue` uses for `workflow-execution-settings` — and shows\nthe projected value beside them; a Settings route plus a `PAGE_RESOURCES` entry\n(`ui/src/stores/control-plane.ts`) bind the page to the kind.\n\nNothing else re-advertises them. `configFieldDescriptors` and `ConfigView.Schema`\ngain no `review.*` row: the config catalog's generic renderer was deleted, so a\ndescriptor row adds a field nothing can edit, which is the shape `becb0b5e`\nremoved.\n\n## What the test proves\n\n`internal/app/controlplane/runtime_config_test.go` adds the round trip that\nbuilds the effective config the way boot does: seed the kind from a file config\nwith both dials set one way, store a document with both flipped, layer it\nthrough `runtimeConfigFrom`, and assert the effective `cfg.Review` equals the\nstored document. A second case covers the absent kind, where the file's values\nstay in effect. The assertion is on `cfg.Review` — the value `TaskContext.Cfg`\ncarries into the two stages — not on a struct the test set directly.\n`TestRuntimeResourceKindsApplyLive` gains `review-settings` as live. The\nvalidator needs no `validators_agree_test.goLine truncated
},
{
"url": "/dev/prds/runtime-control-plane/",
"title": "Runtime control plane",
"section": "PRDs",
"body": "# Runtime control plane\n\n**Status:** Approved \n**Date:** 2026-09-20 \n**Tracking:** `archie-core-j28m`, `archie-core-1786637498420-327-bacadaae`\n\n## Outcome\n\nArchie can be managed from the Web UI or a messaging channel. Both use the same\nAPI.\n\n## Model\n\nEach feature owns its settings and commands. The database stores them. There is\nno global configuration document.\n\nThis includes:\n\n- workflows;\n- identities and bindings;\n- providers and models;\n- repository policies;\n- channels and schedules;\n- capture mappings and bindings;\n- tool settings;\n- prompts and personas;\n- plugin settings.\n\nPlugin code remains installed code. Only its settings are stored in the\ndatabase.\n\nEach feature defines its data, validation, permissions, editor fields, and how\nchanges take effect. Each feature also defines its allowed actions. For example,\nidentities can be created, suspended, and retired.\n\nRepository and identity settings remain separate. They are not stored as large\nrecords that unrelated features must share.\n\nThe State Store process hosts the control-plane API on its existing gRPC server.\nNo new process is added. Feature code validates changes. Storage code only\nwrites versions and audit records.\n\nEvery write records who made it, where it came from, a request ID, and the\nversion being edited. The API layer sets the actor; the request body cannot.\nThe server validates the change, then writes it with its audit record. It rejects\nedits to an old version.\n\nThe request ID is the write's idempotency key, and it is scoped per org and\nper kind, never global. The key is `(org_id, kind, request_id)` — the unique\nindex `idx_resource_history_org_kind_request` (migration `0021_resources_per_org.sql`)\n— so replaying a request ID is the same org's prior write of the same kind, and\na request ID reused across orgs or across kinds is a separate write. This is the\nsame scoping as the task idempotency key `org/identity/owner/repo/number`\n(`docs/prds/orgs-and-access.md`).\n\n## API\n\nThe API has four operations:\n\n1. **Catalogue** tells clients what can be viewed or changed and how to edit it.\n2. **Query** reads data and versions without exposing secrets.\n3. **Command** asks the owning feature to make a change.\n4. **Watch** streams changes and errors to clients.\n\nComplex features can use custom screens. They still use the same commands.\n\nA dashboard session or channel sender must map to an Archie identity before it\ncan run a command. Messaging syntax maps to the same commands as the Web UI.\n\n`archie-ui` receives only an API client. It does not receive a database handle,\ndaemon pointer, global configuration object, or secret value.\n\nThe database stores the requested settings. Each process reports the version it\nis using or why it failed. The UI shows both.\n\nSome changes require a restart. The UI shows them as pending. When a live change\nreplaces a running component, Archie starts and checks the new one before\nswitching. If the check fails, the old one keeps running.\n\n## Bootstrap, migration, and recovery\n\nBootstrap contains only the database path, listen addresses, credentials, TLS,\nand encryption-key references. State Store and control-plane RPCs use the same\nendpoint.\n\nWhen upgraded, existing instances are migrated to the database. Existing\ndatabase values are not overwritten, with one exception: a resource whose\ndocument the build ships is refreshed when the seed itself wrote the stored\ncopy, because that copy is a previous release's document rather than an\noperator's. After migration, settings in TOML are ignored and cannot block\nState Store startup.\n\nThe Web UI remains available when `archied` or Gateway is down. It shows failed\nchanges and can correct or roll them back.\n\nOffline commands can back up, restore, validate, and roll back the database.\nRecovery does not require `archied` or the Web UI. The database stores secret\nreferences, not secret values.\n\n## Workflows\n\nUsers create and edit workflows in the Web UI. Workflows are stored as versioned\nYAML. Built-in workflows can be overridden and restored.\n\nA workflow is a list of steps. Each step has a known type and its own settings.\nA step type is part of the build's step vocabulary, contributed as a provider at\nthe composition root; interpreted plugins contribute none\n(`docs/prds/workflow-step-vocabulary.md`). Each run keeps the workflow version it\nstarted with.\n\nYaegi, `.archie/stages/*.go`, and `.archie/gate.go` will be removed. Their useful\nbehaviour must first be available as normal workflow steps.\n\n## First implementation\n\nThe first implementation makes task limits editable: maximum model steps,\nmaximum runtime, and maximum consecutive gate failures.\n\nIt includes:\n\n- validated task-limit fields;\n- version history and audit records;\n- the four API operations;\n- authenticated Web UI and messaging access;\n- live updates and apply status;\n- a PiLine truncated
},
{
"url": "/dev/prds/self-update-transaction/",
"title": "Self-update: artifact install, topology migration, journaled transaction",
"section": "PRDs",
"body": "# Self-update: artifact install, topology migration, journaled transaction\n\n**Status:** Draft\n\nEpic: `archie-core-hj1t` / GitHub `#804` (\"[EPIC] Self-update: artifact\ninstall, topology migration, journaled transaction\").\n\nThe update _contract_ (`internal/releaseupdate`: `Catalog.Check`,\n`Installer.Install`, plus defer/watchdog/verify) is settled and unchanged by\nthis document — it stays a thin Go interface shelling out to\n`CommandCatalog`/`CommandInstaller`. This document decides what the reference\nadapter scripts (`scripts/archie-update-{check,install,watchdog}`) and\n`install.sh` do behind that contract, and settles the one thing the epic's\nown description got wrong: the dist-zip **is** already attached to GitHub\nReleases (`.github/workflows/deploy.yml`, `gh release upload`), not\nActions-artifact-only. Artifact install is therefore a smaller change than\nthe epic assumed — pointing the installer at an existing asset, not standing\nup new CI publishing. Topology migration and the journaled transaction are\ngenuinely greenfield: no topology-detection or transaction-journal code\nexists anywhere in the tree.\n\nOut of scope: rewriting the `internal/releaseupdate` Go interfaces\nthemselves, and any UI for triggering updates (channel dispatch, e.g.\nTelegram `/update`, is unaffected — this only changes what happens once an\ninstall is triggered).\n\n## Problem\n\n`scripts/archie-update-install:139-160` clones and compiles from source on\nevery update — the only path that exists. `deploy.yml` already publishes a\nper-platform archive plus (implicitly) checksums as a release asset, so the\nscript not using it is a missed-reuse gap, not a missing-CI gap.\n`install.sh:414-445` writes only `archied.service` while every shipped\ndeployment profile (`deployments/*.toml`) declares `[services.state]` and\n`[services.gateway]` sections needing their own units — a fresh install\nalready reproduces the broken single-unit shape `deployment_contract_test.go`\ndoesn't even catch, because that test only checks profile\nsyntax, not installed topology. No code anywhere enumerates which systemd\nunits exist on a host or compares that against what a release requires — the\ndaemon fails at `bootstrap.go`'s `[services.state].target` check with no\nprior diagnosis. The self-refresh trap is confirmed at\n`scripts/archie-update-install:195-199`: new adapter copies land on disk but\nbash keeps executing the in-memory copy, so a pre-flight check added to the\nscript only protects the _next_ update.\n\n## Design\n\n### Artifact install (`#804` item 1)\n\n**Decision.** `CommandInstaller`'s default script downloads the per-platform\narchive plus `SHA256SUMS` from the GitHub Release that `Catalog.Check`\nresolved (the same release `deploy.yml` already publishes to), verifies the\nchecksum, and stages it — it does not clone/compile. Source build\n(`scripts/archie-update-install`'s current clone+compile body) is kept as an\nopt-in path selected by an explicit `--from-source` flag or\n`ARCHIE_UPDATE_SOURCE_BUILD=1` env var, never the default, since a compile-on\nevery-host update is strictly slower and has a larger failure surface than\ndownloading a signed asset that CI already produced.\n\n**Call site.** `scripts/archie-update-install` — replace the clone+compile\nbody with a download-and-verify step; move the existing\nclone+compile body behind the opt-in flag rather than deleting it.\n`internal/releaseupdate/command.go` (`CommandInstaller`) is unchanged —\nit already just shells out.\n\n**Reuse check.** `deploy.yml` already builds and publishes the\narchive and uploads it as both an Actions artifact and a release asset; no\nnew CI work is needed, only pointing the installer at what exists.\n\n**Testing.** Checksum-verification logic is a shell function, testable with\na fixture archive + `SHA256SUMS` pair — add to whatever test harness already\ncovers `scripts/`. Full download-from-real-release is a manual smoke command\n(document the exact `archie-update-check`/`--dry-run` invocation once built),\nnot `task check`.\n\n### Topology migration (`#804` item 2)\n\n**Decision.** Add a topology _observer_ to the daemon, not the shell\nadapter — CLAUDE.md's own \"known trap\" note says the shell copy is defence\nin depth only, and the daemon is what \"knows the deployment and holds the\napproved snapshot.\" The observer inspects which systemd user units exist\n(`systemctl --user list-unit-files 'archie*.service'` or equivalent) and\nwhich config sections are present (`[services.state]`, `[services.gateway]`,\nUI service config), producing an `ObservedTopology` value with one field per\nunit: present/absent, and the config sections backing it. Each release's\n`release.json` (already produced by `deploy.yml` per the artifact-install\nwork above) gains a `required_topology` field naming the units and config\nsections that release's binaries need. `Catalog.Check` compares observed\nagainst requireLine truncated
},
{
"url": "/dev/prds/service-decomposition/",
"title": "Service decomposition -- decision",
"section": "PRDs",
"body": "# Service decomposition -- decision\n\n**Status:** Draft\n**Date:** 2026-09-05\n**Beads epic:** archie-core-8cda\n**Prior art:** `docs/inspiration/2026-09-05-awx-service-decomposition-and-ansible-task-model.md`,\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`,\n`docs/inspiration/service-discovery-research-2026-09-05.md`,\n`/work/artefacts/archie-core-current-state-archify.html`,\n`/work/artefacts/archie-core-ideal-state-archify.html`\n\nThe Phase 3 UI boundary and configuration decision is ratified in\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/). That focused document is\nthe implementation authority for `archie-core-8cda.5.2`; this parent remains\nthe broader service-distribution proposal.\n\n## Decision\n\narchie-core moves from one Go binary (`archied`) hosting every domain\nin-process to a set of independently deployable services, each exposing\nexactly one typed contract. Consumers depend on the contract; they never\nreach into another service's internal types, session state, or config.\ngRPC is the synchronous transport; NATS remains for asynchronous fan-out\n(status, telemetry) rather than being replaced.\n\nThis is a **distribution decision**, not a rewrite of Archie's domain\nmodel. The six-domain split already approved in\n`docs/architecture/index.md` and `docs/architecture/organisation.md`\n(Identity, Agent, Messaging, Workflow, Work Intake, Plugin) is unchanged;\nthis PRD is about how the _processes_ running that domain logic get\npackaged, contracted, and discovered -- not about redrawing domain\nboundaries.\n\n### Target services\n\n| Service | Contract it owns | Existing code it replaces/wraps |\n| --------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n| UI Service | thin client only; talks to Gateway and State Store contracts | `internal/webui` (SPA hosting stays; API surface becomes typed contract clients, not a peer with direct access) |\n| Gateway Service | routing / turn / session contract | `internal/gateway` |\n| Messaging Service | channel-plugin contract (Telegram, email, Discord, Teams, ...) | `internal/channels` |\n| Curator Service | curator contract; **optional**, installs as a Gateway plugin | `internal/domain/curator` |\n| Scheduler Service | cron/ticker contract | `internal/domain/scheduling` |\n| Execution Environment | execution-dispatch contract | `internal/domain/workflow`, task dispatch paths |\n| Runner | isolated worktree/container execution | `internal/container`, `internal/agentexec`, `internal/worktree` |\n| State Store | state-access contract | `internal/infrastructure/postgres` |\n\n### Discovery\n\nPer `docs/inspiration/service-discovery-research-2026-09-05.md`:\n\n- **Primary:** Kubernetes-native discovery (Service + headless-Service/DNS\n - EndpointSlice, served by CoreDNS), delivered as a Helm chart + Operator,\n on k3s for single-host installs and a real cluster for multi-host or a\n hosted offering.\n- **Fallback:** NATS-based discovery (micro `$SRV` announce + JetStream KV\n registry) for no-K8s single-host installs, with a custom gRPC resolver\n reading `host:port` from the KV bucket.\n- Both implementations sit behind one internal interface:\n\n ```go\n type ServiceRegistry interface {\n Resolve(service string) []Endpoint\n Watch(service string) \u003c-chan Event // join/leave\n }\n ```\n\n- An optional service (Curator; others later) that is not installed\n must resolve to a distinct `NotInstalled` outcome, never a `Down`/\n `Unhealthy` one. Under K8s this falls out of DNS returning no record;\n under the NATS fallback it requires an explicit \"installed\" marker in the\n KV registry, not just absence-implies-down.\n\n### Distribution model this supports\n\nBoth self-hosted (customer runs the Helm chart or the NATS-fallback\nbinaries themselves) and a managed/hosted offering (we run the same Helm\nchart) are in scope -- this is the RHELine truncated
},
{
"url": "/dev/prds/service-registry/",
"title": "Service registry — one declaration per service",
"section": "PRDs",
"body": "# Service registry — one declaration per service\n\n**Status:** Draft\n**Supersedes:** `state-store-contract.md` §10's `State ServiceConnection`\nstruct-field instruction.\n\n**Base:** the `listen` field, `internal/app/archied/listen.go`, and the listen defaults cited\nbelow exist on `feat/attempt-attribution`, not on `main`. This design therefore lands on top of\nthat branch: `RegisterService`'s `listen` argument has nothing to carry without it.\n\n## Problem\n\nA service is already one Go type, `config.ServiceConnection`. What is duplicated is its\n**name**, in three layers:\n\n| Layer | Location | What is hard-coded |\n| ----------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |\n| Declaration | `internal/config/services.go` | `Gateway` and `State` as struct fields |\n| Defaulting | `internal/infrastructure/configuration/defaults.go` | three `if cfg.Services.X.Y == \"\"` branches |\n| Consumption | `internal/app/archied/{bootstrap.go,state_store.go,gateway.go}`, `internal/app/archieui/config.go` | `cfg.Services.State` / `cfg.Services.Gateway` field access |\n\nAdding a service means editing all three. The drift this permits is already visible:\n`stateStoreResolvedToken` (`state_store_client.go`) and `gatewayResolvedToken`\n(`chat_service.go`) are byte-identical apart from the env var name, and\n`gateway.Target` is defaulted while `state.Target` is a startup error, with nothing\nstating that asymmetry in one place.\n\n`resolveServiceListen(service, flagValue, configured)` (`listen.go`) is already\nname-parameterised. It is the shape the rest should follow.\n\n## Decision\n\n**Key services by name, and carry per-service asymmetry as registration data.**\n\n### 1. Declaration collapses to a map\n\n```go\n// internal/config/services.go\ntype Services map[string]ServiceConnection\n```\n\n`ServiceConnection` is unchanged. The TOML shape is unchanged, so no deployment profile,\n`config.example.toml`, or `install.sh` edit is required. An unrecognised `[services.foo]`\ndecodes without a code edit, satisfying criterion 5.\n\n### 2. Registration is the single entry point\n\n```go\n// internal/config/servicespec.go\nfunc RegisterService(context, name, target, listen, tokenEnv string)\n```\n\nregistered once per service, at package init in `internal/config`:\n\n```go\nRegisterService(\"both\", \"gateway\", \"127.0.0.1:8585\", \"127.0.0.1:8585\", \"GATEWAY_TOKEN\")\nRegisterService(\"client\", \"state\", \"\", \"127.0.0.1:9090\", \"STATE_STORE_TOKEN\")\n```\n\nPositional, five strings, as the story specifies. Each argument is data the current code\nstates in prose or in a branch:\n\n- `context` is `client`, `server`, or `both`, and decides which fields must resolve\n non-empty. `RegisterService` enforces it: an unknown context, or a hosted service with\n no default `listen`, panics at registration. Registrations come from this repository's\n own `init()`, never from operator input, so an invalid one is a programming error with\n no caller positioned to handle an error return. A documented-but-unread `Context` would\n be worse than no field at all.\n- `target` is the **default**, and an empty default means the operator must supply one.\n That single convention replaces the `state.target` required / `gateway.target` defaulted\n asymmetry with no branch: `state` registers `\"\"`, `gateway` registers an address.\n- `listen` is the default listen address, feeding the existing\n flag → `[services.\u003cname\u003e].listen` → default precedence unchanged.\n- `tokenEnv` names the fallback env var, replacing the two copied resolvers with one.\n\n### 3. Defaulting and consumption become loops and lookups\n\n`applyDefaults` iterates the registry instead of naming services. Consumers read\n`cfg.Services.Get(\"state\")`, returning a `ServiceConnection` plus the spec, so\n`stateStoreResolvedToken` and `gatewayResolvedToken` collapse into\n`Services.ResolvedToken(name, secrets)`.\n\n## Criteria satisfied\n\n1. Declared once, in the `RegisterService` call.\n2. No second location can contradict it; the map has no per-service fields to disagree with.\n3. Registration is the entry point, with the five fields a service has.\n4. A new service is one `RegisterService` line: no field, no default branch, no consumer edit.\n5. The set of services is registry data, not a struct definition.\n\n## Scope and risk\n\n- `state-store-contract.md` §10 must be revised in the same change, or the tree contradicts\n its own ratified authority. Its summary (`:7`) already says `[services.\u003cname\u003e]`.\nLine truncated
},
{
"url": "/dev/prds/session-memory-curator/",
"title": "Persistent session-memory curator (reference implementation) -- decision",
"section": "PRDs",
"body": "# Persistent session-memory curator (reference implementation) -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-1786637499114`\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n**Depends on:** `archie-core-1786637499636` (bind curators to memory\nengines, shipped) and the `domain/memory` engine family (shipped)\n\n## Decision\n\nEach pass: find sessions with activity since the last pass, ask the\nmodel to extract a short list of durable observations from each one's\nrecent messages, and write each through the curator's bound memory\nengine. Extraction is **scoped to one session** -- `Observation.Identity`\nis the session ID, not a user or cross-session identity. No\nconsolidation across sessions, no forgetting, no rewriting a prior\nextraction: every pass only adds.\n\nThis is the second contract consumer the epic asks for, and the one that\nexercises the curator/memory-engine binding\n(`archie-core-1786637499636`) for real, unlike the skill curator, which\ndeclares no memory engine at all.\n\n## Why session-scoped, not user- or agent-wide\n\n`docs/architecture/migration-decisions.md#5` lists the four required\nmemory scopes (global, agent-wide, user-wide, agent-user relationship)\nas **still open** -- there is no decided mapping yet from a chat session\nto a durable identity that would outlive that session (a Telegram chat\nID is not necessarily \"the same person\" as a web session; per-platform\nidentity resolution does not exist as a memory concern). Choosing\nsession-as-identity sidesteps a decision this issue has no business\nmaking unilaterally: it is the narrowest scope that is unambiguous\n(`gateway.SessionContext.SessionID` already exists, is already unique,\nand already has no cross-platform identity claim attached to it), and\nit is forward-compatible -- widening to a resolved user identity later\nis a change to what `Identity` is populated with, not to the\nextraction or write path.\n\n## Why a new `curator.ConversationSource`, not `gateway.SessionStore` directly\n\n`internal/domain/curator` is a domain package; `internal/gateway` is not\none of `internal/domain/*`'s dependencies by convention, and\n`gateway.SessionStore`'s full CRUD surface (branch, fork, replace,\nsearch) is far more than a curator needs or should be able to reach --\nthe same reasoning `ToolBuilder`/`SkillStore`/`MemoryEngineSource`\nalready established for every other host service this package depends\non. `curator.ConversationSource` is a two-method read-only interface;\n`internal/app/archied` adapts the real `gateway.SessionStore` to it, the\nsame shape `MemoryEngineSource` already uses for\n`domain/memory.Registry`.\n\n```go\n// ConversationSource is read-only conversation history, narrowed to\n// what a curator needs to review recent activity -- never the full\n// session CRUD/branch/search surface a chat gateway exposes.\ntype ConversationSource interface {\n // RecentSessions returns every session touched at or after since,\n // newest first.\n RecentSessions(ctx context.Context, since time.Time) ([]SessionSummary, error)\n // Messages returns the most recent n messages of one session, in\n // chronological order.\n Messages(ctx context.Context, sessionID string, n int) ([]ConversationMessage, error)\n}\n\ntype SessionSummary struct {\n ID string\n LastActive time.Time\n}\n\ntype ConversationMessage struct {\n Role string // \"user\" or \"assistant\"\n Content string\n At time.Time\n}\n```\n\n`Manifest` gains `Conversations bool`, gated exactly like `Skills`:\n`Registry.validateDeclared` requires a `ConversationSource` on the host\nwhen declared, `Registry.filter` clears it from a curator's view when\nnot. Role is derived the same way `gateway.compressTurnHistory` already\ndoes (`message.From == botUser` -\u003e `\"assistant\"`, else `\"user\"`) --\ncopied logic, not shared code, since the source type\n(`gateway.Message`) is exactly the thing this package must not import.\n\n## Extraction shape\n\n`Pass`:\n\n1. `Conversations.RecentSessions(ctx, effectiveSince(in.Since))` -- see\n below for the zero-`Since` default.\n2. For each session, `Conversations.Messages(ctx, id, 40)` -- the last\n 40 messages, not the full history. A session accumulates far more\n history than a skill file accumulates content; unlike the skill\n curator's \"re-read everything, it's cheap,\" a full-history read here\n is not cheap and is not needed -- durable facts worth keeping surface\n in recent exchanges, and a 40-message tail is deliberately generous\n against the model's own context rather than tuned tightly, since\n getting this number exactly right is not this issue's job.\n3. One model call per session: the message tail, plus an instruction to\n return a JSON array of short strings, each one fact/preference/\n correction worth keeping, or `[]` if nothing is. Capped at 5 items\n per session per passLine truncated
},
{
"url": "/dev/prds/skill-curator/",
"title": "Skill curator (reference implementation) -- decision",
"section": "PRDs",
"body": "# Skill curator (reference implementation) -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-1786637499206`\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n\n## Decision\n\nThe skill curator's v1 scope is **mechanical validation and safe\nnormalisation only** -- it never rewrites skill prose, never deletes a\nskill, and never calls the model. Each pass:\n\n1. Lists every skill under one configured root.\n2. Reads each `SKILL.md` and attempts to parse its frontmatter\n (`internal/skill.Parse`).\n3. Records an `Action` for any structural problem: a parse failure, or a\n missing `name`/`description` in the frontmatter that parsed.\n4. Normalises trivial whitespace (trailing whitespace per line, exactly\n one trailing newline) and writes back **only** when normalisation\n actually changes the bytes, recording an `Action` for that write.\n\nNothing here needs judgement. \"Review, prune, and improve\" -- the epic's\nframing -- is real for v1 but deliberately narrow: review is structural\nvalidation, improve is whitespace normalisation, and prune is _reporting_\na problem, never removing a skill. `Manifest.Skills = true` still marks\nthis curator agentic (existing `agentic()` rule), so it receives model\naccess from the registrar -- unused but nothing about the contract\nor the runtime needs to change to let a later version reason about\ncontent quality using it.\n\n## Why this scope, not more\n\nAn autonomous process that rewrites or deletes a user's skill content\nis a real risk with no undo path (no draft/approval flow for\ncurator writes exists yet, unlike the workflow engine's PR-based review).\nThe epic's own stated purpose for this issue is proving the curator\ncontract holds for a second, structurally different consumer than the\nsession-memory curator (files-as-skills vs. observations-as-memory), not\nsolving \"what makes a skill good.\" Mechanical validation is real,\nuseful, safe to run unattended, and fully exercises\nList/Read/Write -- every method `curator.SkillStore` declares except\n`Delete`, which this curator's Pass never has a safe reason to call in\nv1 (kept implemented on the store adapter regardless, since the\ninterface requires it and a future consumer may).\n\n## Why `internal/skill` isn't `curator.SkillStore` directly\n\n`internal/skill.Discover` parses every `SKILL.md` under a root and\nreturns an error for the **whole** call if any one of them fails to\nparse -- the read side was built for \"load the catalogue to start the\ndaemon,\" where one bad skill failing the whole boot is arguably correct,\nnot for \"review each skill and report what's wrong with it\nindividually.\" A per-skill parse failure must become one `Action`, not\nabort the pass before any skill is reviewed. So\n`internal/infrastructure/skillcurator` gets its own thin store adapter\nthat lists raw directory names and reads/writes raw `SKILL.md` bytes\nper name; the skill curator itself calls `internal/skill.Parse` on each\none, isolated per skill.\n\n## Root scope\n\nOne root only, resolved the same way `loadWorkflows` already resolves\n`skillsBase` (`cfg.SkillsDir`, falling back to `cfg.WorkDir`) -- not\nevery root `skill.CatalogRoots`/`DefaultRoots` would read for a model\n(which layers a shared dir over the per-profile one). Write and Delete\nneed one unambiguous target; a curator that could write into a shared,\nmulti-tenant skills directory is a bigger decision than this issue\ncovers. The model still sees the full multi-root catalogue through the\nexisting read path -- this curator only maintains the local one.\n\n## Shape\n\n### `internal/infrastructure/skillcurator/store.go`\n\n```go\n// Store implements curator.SkillStore over one root directory's\n// .agents/skills/*/SKILL.md files, tolerating a per-skill parse failure\n// as the curator's problem to report rather than this store's problem\n// to abort on.\ntype Store struct { root string }\n\nfunc NewStore(root string) *Store\n\nfunc (s *Store) List(ctx context.Context) ([]curator.SkillRef, error)\nfunc (s *Store) Read(ctx context.Context, name string) (curator.Skill, error)\nfunc (s *Store) Write(ctx context.Context, sk curator.Skill) error\nfunc (s *Store) Delete(ctx context.Context, name string) error\n```\n\n`Read` best-effort parses frontmatter for `Skill.Description` (empty on\nparse failure -- not this method's job to report that; `Pass` does, via\nits own `skill.Parse` call on `Skill.Content`). `Write` rejects a name\nthat does not already exist as a directory (this store curates existing\nskills; creating a new one is out of scope). `Delete` removes the whole\nskill directory, matching \"delete a skill,\" not just `SKILL.md`.\n\n### `internal/infrastructure/skillcurator/skillcurator.go`\n\n```go\n// Curator implements domain/curator.CuratorEngine. See\n// docs/prds/skill-curator.md for what a pass does and why.\ntype Curator struct { /* unexported: registrar view, interval *Line truncated
},
{
"url": "/dev/prds/soul/",
"title": "SOUL: an agent's user-authored personality",
"section": "PRDs",
"body": "# SOUL: an agent's user-authored personality\n\n**Status:** Draft\n**Authority:** `docs/architecture/identity.md`, “Three-layer identity model”;\n`docs/prds/orgs-and-access.md` for identity and org ownership.\n\n## Decision\n\nSOUL supplies an agent's name, register and warmth. It belongs to the agent's\nimmutable `IdentityID`, not its session, model, installation or container\nprofile. Rename preserves it; changing a profile does not change who acts.\nSOUL never changes attribution, credentials, grants or identity lifecycle.\n`config.AgentProfile` remains an execution environment, not another identity.\n\nUse the existing three layers: invariants, user-authored SOUL, and curator-derived\nrepresentation. Curators may propose SOUL changes but never apply them.\n\n## Files and ownership\n\nThe config directory is `${XDG_CONFIG_HOME:-~/.config}/archie`, or the directory\nof an explicitly selected config file. The default/root agent uses `SOUL.md`\ndirectly there; additional agents use `agents/\u003cidentity-id\u003e/SOUL.md`. The root is\nthe identity selected by application composition, never the initiating user or\na session's personality selection. No file creates or selects an identity.\n\nThe common case keeps a human-friendly filename; additional agents get separate\nasset directories, following `.agents/skills/\u003cname\u003e/SKILL.md` without confusing\nthese directories with `[containers.profiles.\u003cname\u003e]`. Reject display-name or\nslug directories: rename and same-name agents across orgs would require another\nname-resolution rule. Immutable IDs avoid both problems without an org directory.\n\nWhen a file-owned agent's file is absent, create the shipped default with\nexclusive creation. Never overwrite an existing file, including an empty one.\nA creation failure still permits the turn using the embedded shipped default.\nShip that document independently of `agent.ShippedPersonas`, so deleting personas\ncannot delete the fallback.\n\nResolve once at the start of every new generation:\n\n1. A stored SOUL entry for the acting identity is authoritative.\n2. Without an entry, read that identity's file again.\n3. An absent, empty, unreadable or invalid selected source uses the shipped default.\n\nThe first explicit dashboard/API save takes ownership permanently. Thereafter\nfile edits are ignored: emit one ownership notice and show the owning stored\nversion in the dashboard. Restoring the shipped default writes a stored value;\nit does not remove ownership. Refuse writes that remove an owned entry.\n\nThis ownership boundary is the design's one stateful rule. Files seed the\neditable value, not an automatic durable import. Reject seed-once import because\nit breaks next-message file editing; reject file-always-wins because it makes\ndashboard saves ineffective. Neither a restart nor an upgrade overwrites an\nowned value, following the precedence of `controlplane.AgentProfileKind` without\ncopying its startup import timing.\n\n## Prompt and failure contract\n\nKeep `archie.md.tpl`'s XML-escaped\n`\u003csoul purpose=\"identity_and_style\" trust=\"data\"\u003e` block before\n`\u003cinstruction_precedence\u003e`. SOUL is style reference data; the invariant sections,\ntool inventory and runtime metadata remain authoritative and uneditable.\nPreserve `TestBuildSystemPromptSoulCannotOverrideInvariants`.\n\nAccept UTF-8 plain Markdown with at most 8 KiB in its XML-escaped body. This bounds\npersonality to a small prompt contribution; count the complete rendered prompt\nin the turn's context budget and never truncate invariant sections. Bound file\nreads before decoding; reject oversize input rather than truncating instructions.\nFile and stored writes use the same validator; an invalid save leaves the stored\nversion unchanged. The shipped default must pass that validator.\n\nRead and creation errors never fail a turn. Log once per identity/source failure\nepisode, retry on the next turn, and allow a new warning after recovery. If the\nstore cannot establish whether an owned entry exists, use the shipped default,\nnot a potentially shadowed file. Do not log SOUL text. Each turn keeps its resolved\nsnapshot; edits affect the next generation without restart or SIGHUP.\n\n## Cross-layer delivery\n\n- `internal/domain/agent` owns SOUL content validation and the identity-keyed read\n contract; `internal/domain/identity` remains the actor/lifecycle authority.\n- The configuration infrastructure resolves the config directory and handles\n file discovery, exclusive default creation and bounded per-turn reads.\n Application composition resolves the acting `IdentityID` through the existing\n identity repository/bindings and supplies it to the gateway.\n- Register `SoulKind` (`agent-souls`) in the control plane with a live descriptor\n and an org-scoped document mapping identity IDs to `{text}`. Persist it through\n the State Store's existing resource/history contracts, not a new table,\nLine truncated
},
{
"url": "/dev/prds/state-store-contract/",
"title": "State Store — contract boundary \u0026 transport (ratification)",
"section": "PRDs",
"body": "# State Store — contract boundary \u0026 transport (ratification)\n\n**Status:** Approved\n**Revision:** 2e\n**Date:** 2026-09-06\n\nThis is the pre-implementation design document that Phase 2 subtasks `.4.2` (generalise\n`storerpc` as the State Store gRPC contract) and `.4.3` (stand up `archie-state-store`)\nimplement against.\n**Beads milestone:** archie-core-8cda.4.1\n**Parent:** `docs/prds/service-decomposition.md` (open-question Q4 **RESOLVED**)\n\nThis document fixes the **contract boundary** and **transport** for the State Store service.\nIt does not redesign Archie's domain model, does not invent a second store, and does **not**\nsplit `archie.db`. It records method ownership, DTO/wire representation, error semantics,\nlimits, mode/config shape, local-adapter compatibility, and cutover/deletion rules so that\n`.4.2` and `.4.3` have exactly one authoritative surface to build against.\n\n\u003e **Storage superseded.** The store behind this contract is PostgreSQL:\n\u003e `internal/infrastructure/postgres` implements the producer-owned interfaces in\n\u003e `internal/domain/storecontract` and `workflow.Store`, over the database\n\u003e `database_url` names. `internal/store`, the SQLite file and the local adapter\n\u003e are gone; where this document says `archie.db`, `*store.Store` or\n\u003e `internal/store`, read the State Store's PostgreSQL database and\n\u003e `internal/infrastructure/postgres`. The contract, ownership split, error\n\u003e semantics and cutover rules stand.\n\n\u003e **Current state — read before `.4.2` starts.** The §12 step 2 relocation (`archie-core-8cda.\n4.8`) has landed: `Task`/`Status*`/`Source*` and the 3-method `workflow.Store` now live in\n\u003e `internal/domain/workflow`, the six production workflow files import no `internal/store`\n\u003e symbol, and `storerpc`/the NATS transport assert against `workflow.Store` instead of\n\u003e `store.WorkflowStore`. The broader Phase 2 acceptance criterion (State Store as its own\n\u003e service behind gRPC) is still open — that is what `.4.2`/`.4.3` build next.\n\n\u003e **Relationship to migration-decisions §4 — not replaced.** `docs/architecture/\nmigration-decisions.md` §4 (`store.Task → WorkflowExecution`, `mutable Stage →\nStepExecution history`, `RetryCount/Attempt → Attempt records`, versioned Workflow defs)\n\u003e **remains the authoritative, open document for the long-term Workflow migration.** This PRD\n\u003e does **not** replace it. It only pulls the minimal `Task`/`Status`/`Source` type + interface\n\u003e relocation forward as a Phase 2 prerequisite (because the acceptance criterion requires it);\n\u003e the rest of §4 stays its own migration and stays open.\n\n---\n\n## 1. Decision (the invariant everything follows)\n\nArchie is composed such that a single **`archie-state-store`** service owns the one existing\nSQLite file (`archie.db`) and exposes it over **gRPC behind narrow typed contracts**. There is\nexactly one store, one file, one service. No database-per-service, no distributed\ntransactions, no second store abstraction.\n\nTwo adapter families satisfy the contract interfaces:\n\n- **Local adapter** — `*store.Store` (the in-process SQLite implementation).\n- **Remote adapter** — `*staterpc.Client` (wraps the generated gRPC client).\n\nEach adapter carries an explicit compile-time assertion against the contract interfaces it\nserves. Composition picks local vs. remote by the presence of `[services.state].target`\n(empty = local; set = dial the gRPC service). Default is **local** (the State Store is not yet\nextracted), which is the PRD §3 posture; it differs from the gateway's remote-default only\nbecause the gateway is already a separate deployment and the State Store is not.\n\n\u003e **Contract-ownership fork, decided (rev. 2c — resolves the domain contradiction).**\n\u003e Ownership splits by the consumer's _layer_, per the dependency contract's rule #2\n\u003e (\"a domain defines the smallest interfaces required to perform its work\") and rule #7\n\u003e (\"database rows … MUST NOT leak into domain models\"):\n\u003e\n\u003e - The **workflow domain** (`internal/domain/workflow`) is the only domain-layer consumer of\n\u003e store state. It defines its own **consumer-owned** narrow `Store` interface\n\u003e (Update/Transition/InsertEvent) and its own **domain-owned** `Task` type plus\n\u003e `Status`/`Source` vocabulary. It imports **zero** `internal/store` symbols — satisfying the\n\u003e Phase 2 acceptance criterion. This is the minimal bound of migration-decisions §4\n\u003e (`store.Task → WorkflowExecution`), pulled forward **because** the acceptance criterion\n\u003e requires it.\n\u003e - The **daemon / webui / intake** store surfaces (`TaskStore`, `CaptureStore`,\n\u003e `MappingStore`, `BindingStore`, `BindingDispatcher`, `BindingTaskCreator`) stay\n\u003e **producer-owned** in `internal/store`, because those consumers are application Line truncated
},
{
"url": "/dev/prds/status-health-surface/",
"title": "/status health surface",
"section": "PRDs",
"body": "# /status health surface\n\n**Status:** Finalised\n**Beads issue:** `archie-core-wp9s`\n\nA reported field must have a truthful source. `/status` reports broker\nconnectivity and the last chat-model call; the container pool, last poll and\nchannel state have no source in the process that answers the command, so they\nare left out rather than faked.\n\n## Background\n\n`archie-core-wp9s` (\"/status and /tasks have the wrong division of labour\")\nasked for two things: `/tasks` owning the live per-task work view, and\n`/status` owning daemon health -- \"broker connectivity, provider\nreachability, channel state, container pool, queue depth, last poll,\nversion\" -- with neither duplicating the other or static config available\nelsewhere (`/model` already lists active provider/model).\n\n## Phase 1\n\n- `/tasks`: new command, `gateway.ChatTaskSummary` extended with\n `Stage`/`Attempt`/`ParkReason`/`UpdatedAt` (all already persisted on\n `store.Task`, zero new instrumentation), sorted actionable-first.\n- `/status`: itemised per-status task counts replaced with one aggregate\n `Queue: N in flight (...)` line (running/waiting/parked only -- queued and\n terminal states excluded as not a health concern). Runtime\n (provider/model) is temporarily left in place; see \"Runtime (provider/model)\"\n under Phase 2's \"Truthful or absent\" for where that stands now.\n\nNot touched: `/agents` (`gateway.AgentReader`/`Router.Agents`) is a separate,\npre-existing command that already has the right shape for \"list active\nwork\" but is never wired to a real implementation in any composition-root\ncall site (`bootstrap.go`, `telegram_setup.go`) -- it always answers \"Agent\nlisting is not configured.\" in production. That is a standalone bug\n(`archie-core-mxls`), not folded into this work: deciding whether to wire\nit, repurpose it, or delete it in favour of `/tasks` is Sam's call, not\nsomething to resolve by implication here.\n\n## Phase 2 -- health checks, verified against the actual tree\n\nEach bullet below was checked against real code before being called cheap\nor not; nothing here is guessed. Both open questions were settled (see \"The two\ndecisions\"). The health section reports the broker connection and the last\nchat-model call; the three facts the answering process cannot see are covered\nunder \"Truthful or absent\".\n\n### Verified as cheap against the tree\n\n- **Broker connectivity.** `internal/infrastructure/eventbus/nats.Client`\n already exposes `CoreConn() (*nats.Conn, error)`\n (`client.go`). The underlying `nats.Conn` (nats.go) has its own\n `Status()`/`IsConnected()`. A `Client.Connected() bool` wrapper is a few\n lines.\n- **Container pool.** `container.Pool` already tracks `active int` under\n its own mutex (`pool.go`) but has no public accessor. A\n `Pool.Active() int` getter is a few lines.\n- **Last poll.** Nothing tracks this. The daemon's poll loop\n (`internal/daemon`) needs one `lastPollAt time.Time` field (atomic or\n mutex-guarded, matching the pool's own pattern) set at the top of each\n poll tick, with a getter.\n- **Queue depth.** Covered by Phase 1.\n\n### The two decisions\n\n- **Provider reachability is last-known outcome, never a live probe.** A chat\n command must not perform a blocking network call in its handler, and a probe\n reports the probe's reachability rather than the daemon's. `/status` therefore\n prints what actually happened -- the last chat-model call's model, age and\n error, or \"no calls attempted yet\" when there has been none. Implemented as\n `providerOutcomeRecorder`, written once in `sendChatTurn` (the single point\n every chat-model call in the process passes through) and read back by\n `newStatusHealth`. Nothing on this path dials a provider. The existing live\n model reachability check (`readiness.go`'s `modelReachProbe`) is unchanged and\n stays where it belongs: on `/health/detailed`, off the chat path.\n- **Channel state comes from the existing ChannelManager.** `/status` reads\n `status.Manager.Snapshot()` -- the same ledger the dashboard and the readiness\n probe already use -- rather than re-deriving channel health from each adapter.\n No method was added to the `Channel`/`Gateway` contract.\n\n### Phase 2\n\n- **Broker connectivity.** `internal/infrastructure/eventbus/nats.Client` gained\n `Connected() bool`, which reads the connection the process already holds. The\n standalone Gateway (which dials NATS itself for task actions) reports the same\n fact from that connection.\n- **Container pool.** `container.Pool.Active()` and `Pool.Cap()` read the pool's\n own counter and configured `max_concurrency` -- not a Docker listing, which\n would include containers this pool does not own. A cap of zero means\n unlimited, so `/status` renders the count alone rather than \"1/0 active\".\n- **Last poll.** `daemon.Daemon.LastPollAt()` reports when the most recent poll\n pass _began_; both poll paths (`poll` for sLine truncated
},
{
"url": "/dev/prds/store/",
"title": "Store",
"section": "PRDs",
"body": "# Store\n\n**Status:** Approved\n**Authority:** `docs/architecture/plugins-and-extensions.md`; supersedes\n`docs/prds/extensions-center.md`, whose installed-inventory states are\nadopted below.\n**Compounds with:** `docs/prds/external-agent-harness.md` (harness Kits),\n`docs/prds/pr-review-agent.md` (the first package).\n\n## Decision\n\nOperators get capabilities from a store: browse, install, update and remove\npackages from the dashboard, with no config file editing. A package is an\nOCI image in a registry. A store catalogue is a list of package references.\nInstalling pins a digest. Every package declares the authority it needs, and\nan update that asks for more stops for the operator's approval.\n\n## Packages\n\nTwo kinds, both ordinary OCI images:\n\n- **Harness Kits.** Kit v3 images, resolved as\n `docs/prds/external-agent-harness.md` decides. Their authority is their\n Kit permission surface.\n- **Archie packages.** An image whose manifest annotation\n `dev.archie.package.v1` carries the descriptor and whose single layer\n carries files. A package contributes any of: workflow definitions,\n prompts, skills, MCP server definitions, and default settings for them.\n\nArchie packages are declarative. They carry no Go, Yaegi or script code that\narchie executes on the host. Anything that runs code ships as a Kit and runs\nin a sandbox. An archie package that references a Kit names it by digest,\nand installing the package installs the Kit.\n\nThe descriptor declares: display name, description, version, the families\nit contributes, the packages it requires, and its authority.\n\n## Authority\n\nA package's authority is the set of grants it needs to work:\n\n- credential services (from its Kits and MCP servers);\n- egress hosts (from its Kits);\n- forge permissions its workflows use: read, comment, review, push, open\n pull request;\n- triggers it registers: watched-repository events, schedules;\n- tools it enables for agents.\n\nInstall shows this list and records the operator's acceptance against the\ndigest. An update whose authority is equal or narrower applies under the\npackage's update policy. An update whose authority is wider waits for\napproval, showing only what widened. Nothing a package does at runtime can\nexceed its accepted authority: archie checks forge actions, triggers and\ntool grants against it, and the egress proxy enforces the Kit's grants.\n\n## Catalogues\n\nA catalogue is an OCI artifact listing package references with digests,\nsigned by the catalogue's key. Archie ships with the default catalogue and\nits public key configured. An operator can add catalogues, for example a\nprivate registry, by reference and public key. A catalogue without a key is\nrefused unless the operator marks it unsigned, which the dashboard shows on\nevery package it supplies.\n\nInstall and update verify the catalogue signature and the package digest.\nArchie never installs a tag it has not resolved to a digest through a\nverified catalogue.\n\n## Organisations\n\n`docs/prds/orgs-and-access.md` is the boundary, and the store follows its\nsplit between the instance and each org.\n\n- **Instance.** Catalogues and their keys are instance configuration, set by\n instance admins. Every org browses the same catalogues.\n- **Org.** Installing, updating, removing, accepting authority and setting the\n update policy are org actions. An installed package, its pinned digest and\n its accepted authority belong to one org. Two orgs can run different\n versions of one package.\n- **Contributions** become org resources: workflows are org workflows,\n profiles are org profiles, and credential bindings name org secrets. A\n workspace uses them only once the org grants them to it.\n- **Authority is an upper bound, not a grant.** Accepting a package's\n authority permits the package to ask; the workflow's identity must still\n hold each grant. A package never creates, grants to or widens an identity.\n- Install and authority acceptance are the `create` and `approve` actions on\n the package, decided by the Authorizer. Org approval policy decides who may\n accept, and no member accepts authority they asked for.\n\n## Install, update, remove\n\n- Installed packages, their pinned digests, accepted authority and update\n policy are org resources in the State Store. They apply without a restart.\n- **Update policy** per package: `manual` (default) or `auto`. `auto` applies\n non-widening updates when the catalogue lists them; widening updates always\n wait.\n- **Setup.** A package whose authority includes a credential with no binding\n installs as `needs_setup`, and links to the binding form or the harness\n setup terminal. Its triggers do not fire until setup completes.\n- **Remove** stops its triggers, removes its contributions, and leaves any\n credential bindings for the operator to delete. A package another\n installed package requires cannot be removed first.\n- Rolling back reinLine truncated
},
{
"url": "/dev/prds/task-logs-pagination/",
"title": "task_logs pagination and bounded retrieval -- decision",
"section": "PRDs",
"body": "# task_logs pagination and bounded retrieval -- decision\n\n**Status:** Approved\n**Date:** 2026-08-26\n**Beads issue:** `archie-core-vq92`\n**Compounds with:** `archie-core-p1bl` (errors serialise as `{}`)\n\n## Decision\n\n`task_logs` becomes a _cursor-paginated, filterable_ bounded read, not a\none-shot head-of-file window. The reader in `internal/logging` gains a\nsecond entry point (`Page`) that walks the file forward from a byte\noffset; the tool schema in `internal/gateway/task_tools.go` surfaces\nlevel, time-range and cursor parameters; the response carries an explicit\n\"more available\" signal so a model can either keep paging or hand the\nrest to `send_file` when the operator wants a complete archive.\n\nWe do NOT add an unbounded read path. A single response is still capped at\n`MaxTailLines` (2000) entries. What changes is that pagination makes the\ncap reachable in practice instead of silently terminal.\n\n## Why now\n\n`archie-core-vq92` is the right place to fix this: the chat tool is the\nuser-visible failure mode, but the same defect propagates to every caller\nof `internal/logging.Tail` (`internal/webui/api_logs.go` and the\n`chatTaskLogReaderAdapter` in `cmd/archied/main.go`). Patching the\nreader and the tool together is one change in two layers, not two\nchanges; CLAUDE.md's \"package owns its format end-to-end\" rule means the\nreader is the right place for cursor support regardless.\n\nThe compound with `p1bl` matters: a truncated window of uninformative\nerrors leaves an operator with nothing. Cursor pagination lets the model\nwalk the whole file when a level filter does not narrow enough, and the\nresponse's \"more available\" signal means it can honestly say \"I read N of\nM and stopped there\" instead of presenting the head as complete.\n\n## Shape of the API\n\n### Reader (`internal/logging`)\n\nAdd a second entry point next to `Tail`:\n\n```go\n// Page walks the log forward from cursor (a byte offset; 0 starts at\n// the beginning of the scanned window), applying the same filters as\n// Tail. PageResult.Cursor is the file offset just past the last line\n// the walk returned; pass it back as Cursor to continue, and stop when\n// MoreAvailable is false.\nfunc Page(path string, q Query, cursor int64) (PageResult, error)\n```\n\n`PageResult` carries `Entries`, `Truncated` (the existing meaning --\nolder entries exist that were not examined within `maxScanBytes`),\n`Cursor` (the byte offset the next page should resume from), and\n`MoreAvailable` (true iff the scan saw more matching entries beyond the\nreturned page within the same call).\n\n`Cursor` is a byte offset rather than an entry ID for two reasons.\nFirst, `TaskSink` writes JSONL through `slog.NewJSONHandler` directly --\nwithout routing through `FeedHandler` -- so the on-disk entries carry no\n`id` field and a per-task attempt monotonic counter would require\neither a sink-side change or a reader-side reconstruction that is\nbrittle against rotation. Second, the byte offset uniquely identifies\n\"the next unread position\" in a sequential scan, which is exactly what\nthe call pattern needs. A cursor that points at or past the file's\ncurrent size is treated as end-of-stream (empty page, `MoreAvailable`\nfalse).\n\nThe implementation is `readWindow` (reads the tail-most `maxScanBytes`\ninto a single in-memory buffer) plus `readLines` (clamps the cursor into\nthe window, drops a partial first line on the size-cap seek, then\ndelegates) plus `walkWindow` (walks the buffer line-by-line by exact\nslice offset). Offsets are into one contiguous buffer, so they are\ntrivially correct -- unlike an incremental reader over the file, whose\n`bufio.Reader` buffer-ahead would make its underlying file position\nunusable as a cursor.\n\n`Tail` is NOT a wrapper over `Page`: it keeps its legacy ring-buffer\nsemantics (newest `Limit` matches, oldest dropped, `Truncated` set on\nring overflow). They share `readWindow`/`walkWindow` but stay separate\nentry points precisely so Tail's established behaviour is unchanged.\n\n### `Query` gains two optional fields\n\n```go\nSince time.Time // inclusive lower bound on entry.Time\nUntil time.Time // inclusive upper bound on entry.Time\n```\n\n`Levels`, `Component`, `Contains`, `Limit` are unchanged. The existing\nfilter logic and tests move unchanged.\n\n### Tool schema (`internal/gateway/task_tools.go`)\n\n`ChatTaskLogQuery` gains three fields:\n\n- `Level []string` (forwarded to `Query.Levels`)\n- `Since time.Time` / `Until time.Time` (forwarded as `Query.Since/Until`)\n- `AfterID int64` (the cursor; 0 to start at the beginning)\n\n`ChatTaskLogResult` gains two fields:\n\n- `Cursor int64` -- highest ID in this page; pass back as `AfterID` to continue\n- `MoreAvailable bool` -- true iff the scan saw more matching entries that\n did not fit in this page\n\nThe tool description is updated to teach the model the pagination\nprotocol in one sentence: \"pass the previous `cursor` back as `Line truncated
},
{
"url": "/dev/prds/task-run-detail/",
"title": "Per-run task detail: attempts, stages, changes, config, debug",
"section": "PRDs",
"body": "# Per-run task detail: attempts, stages, changes, config, debug\n\n**Status:** Approved\n**Authority:** the surface contract itself is\n`docs/architecture/observability.md`.\n**Date:** 2026-09-18\n**Compounds with:** `docs/prds/task-logs-pagination.md` (a bounded read says\nwhat it does not show), `docs/prds/status-health-surface.md` (no surface that\nanswers something already answered elsewhere).\n\n## Decision\n\nA task gets one detail page that answers \"what did this run actually do?\" per\n**attempt**: an ordered stage rail, the change each commit/push produced, the\neffective configuration the attempt ran under, the attempt's log, and the raw\nrecord behind all of it.\n\nThe single organising idea is **attempt attribution**. The dashboard\nrenders a task's whole event stream as one flat timeline, so a retried task\nreads as one long run with two of everything. Every new panel is scoped to one\nattempt and says which one.\n\nThe second organising idea is **provenance, not re-derivation**. What a run\nproduced is captured at the producer, while the evidence exists, and persisted\ndurably. Nothing in this surface tries to reconstruct a past run from state\nthat has since moved on.\n\n## The requirement set\n\n| # | Requirement | Mechanism |\n| --- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |\n| R1 | Per-attempt stage rail: stages with name, start, duration, terminal status and error, ordered within one attempt | `GET /api/tasks/{id}/attempts` reads the task's events and groups them by `attempt` |\n| R2 | Events carry an attempt, migrated safely and carried on the wire | `events.attempt` column + presence-gated migrator arm; `Event.attempt = 11` |\n| R3 | Changed files captured at commit/push, persisted per task, exposed, shown with repo/PR links | `changes_captured` durable event written by the commit/push steps; `GET /api/tasks/{id}/changes` |\n| R4 | The effective configuration an attempt ran under, secrets redacted, shown | `config_captured` durable event written once per attempt; read from the events response the page already holds |\n| R5 | Log pane filters by attempt, stage and level; absence stays distinct from an unreadable deployment | `logging.Query.Stage` + `ReadTaskLogRequest.stage = 9`; the pane keeps `disabled` and `found=false` apart |\n| R6 | Retry is reachable from the run view and produces a new attempt shown as a new run | Existing retry action, labelled as a NEW run whose confirm states the previous attempt's commits are discarded |\n| R7 | Raw JSON of the task record and its events for the selected attempt | `GET /api/tasks/{id}/debug` |\n| R8 | Deep-linkable, reload-safe per-task detail page that keeps existing URLs working | `/tasks/{id}` route beside the existing `/tasks?task=N` and `/tasks?status=...` |\n| R9 | Design polish: hierarchy, tokens, both themes, responsive rail, a11y, loading/empty/error states | UI lane; measured at 480px and 700px in both themes |\n| R10 | Documentation of record | This document plus `docs/architecture/observability.md` |\n| R11 | Red-first tests for every new behaviour, full gate, `task ui`, forced `go build ./...`, `go test -race` on touched packages | Per lane; the anti-cost-cutting requirement lives here |\n\n## Attempt attribution: a column, not a guess\n\n`events.Event.Attempt`, persisted as the `events.attempt` column\n(`internal/infrastructure/postgres/migrations/0001_state_store.sql`), is a real column,\n`NOT NULL DEFAULT 0`. It was chosen over segmenting the stream on `task_queued` /\n`task_retried` because a fold would have to guess which side of a boundary an\nevent belongs to when the daemon restarts mid-attempt, when `RecoverStale`\nrequeues, or when two attempts interleave across a crash. A guess rendered as\nstrucLine truncated
},
{
"url": "/dev/prds/task-run-master-detail/",
"title": "Task run detail as a master-detail split pane",
"section": "PRDs",
"body": "# Task run detail as a master-detail split pane\n\n**Status:** Approved\n**Authority:** the panel contracts stay as ratified in\n`docs/prds/task-run-detail.md`; this document changes only the run page's\narrangement of them.\n**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution, the\nlog stage filter, the per-panel honesty rules).\n\n## Decision\n\nThe run page's five tabs become two panes. The stage rail is the **master**,\nalways visible on the left. The four context panels — log, changed files,\nconfiguration, debug — are the **inspector** on the right, and their tab bar\nmoves into the inspector. The \"Stages\" tab stops existing.\n\nSelecting a stage switches the inspector to the log tab and sets the log\npane's stage filter to that stage. Changing the filter afterwards is the\noperator's choice and is not overridden; rail selection never touches the\nlevel filter. Clicking the selected stage again returns the filter to all\nstages. A stage with no name is rendered but not selectable.\n\nSwitching attempts resets the stage filter to all stages: a selection was\ncommanded on the attempt it was made on, and a different attempt presents a\ndifferent stage list. Changed files, configuration and debug stay\nattempt-scoped; a stage selection never scopes them.\n\n## What does not change\n\n- No new endpoint, RPC, table or configuration field. Every read is one the\n page already makes.\n- The URL contract: `tab` and `attempt` ride in the query string and survive\n a reload. Log filters are not part of the URL; a reload returns the log to\n all stages. `tab=stages` stays a valid URL and renders the log tab; the\n page never generates it again.\n- Attempt attribution, the log stage filter's coverage limit and every\n honesty rule in `task-run-detail.md` still apply: each pane states what it\n cannot show under that document's rendering rules.\n- The task header and the attempt selector sit above both panes.\n\n## Arrangement\n\n- Left pane: fixed-width rail (20rem) with the attempt's stage rows. Status,\n duration, error, the stage's agent report, the attempt's status badge and\n start time, and the attempt-attribution footnotes render in the rail.\n- Right pane: the inspector's tab bar plus the selected panel, filling the\n remaining width.\n- Below the shell's 900px frame breakpoint the rail stacks above the\n inspector; neither pane is hidden.\n- Keyboard: the rail keeps its list semantics and each stage row is a real\n button, so selection and deselection work without a pointer; the inspector\n keeps the WAI-ARIA tabs pattern the tab bar already provides.\n\n## Acceptance\n\n1. The rail is visible without opening any tab, and no \"Stages\" trigger exists.\n2. Clicking a stage opens the log filtered to that stage; clicking it again\n shows all stages.\n3. After a stage selection, a filter change made by the operator is kept, and\n the level filter survives the selection.\n4. Switching attempts resets the stage filter to all stages, and no rail row\n on the new attempt renders as selected unless the operator selected it\n there.\n5. `tab=stages` loads and renders the log tab.\n6. Every inspector tab and attempt deep-link survives a reload.\n7. A stage is selectable and deselectable by keyboard, and the selection\n mirrors the log pane's stage filter.\n8. Below 900px the rail stacks above the inspector.\n9. `task check` passes clean and `ui/dist` matches the sources.\n"
},
{
"url": "/dev/prds/ui-service-boundary/",
"title": "UI Service boundary and configuration ownership",
"section": "PRDs",
"body": "# UI Service boundary and configuration ownership\n\n**Status:** Approved\n**Revision:** 1\n**Date:** 2026-09-07\n**Beads issue:** `archie-core-8cda.5.1`\n**Parent:** [`service-decomposition.md`](/dev/prds/service-decomposition/)\n**Prerequisites:** Gateway contract extraction and State Store contract ratification\n\nThis document is the authority for Phase 3 UI Service implementation. It fixes\nthe process boundary, configuration ownership, client contracts, security\nposture, readiness behaviour, and migration evidence required by\n`archie-core-8cda.5.2` and later UI extraction work.\n\n## Decision\n\nThe UI Service owns the operator-facing HTTP surface and the compiled SPA. It\nserves `ui/dist` and exposes UI-specific JSON DTOs for dashboard views and\nactions. It does not own conversations, task state, workflow execution,\nchannel lifecycle, forge access, or the daemon's runtime configuration.\n\nThe UI Service consumes two typed remote capabilities:\n\n- Gateway's `gateway.ChatContract` through the versioned Gateway gRPC\n contract, for chat snapshots, messages, turns, streaming, persona changes,\n cancellation, and Gateway task actions.\n- State Store's narrow read/write contracts through the versioned State Store\n gRPC contract, for task views, events, captures, mappings, bindings, and\n configuration data explicitly projected for the dashboard.\n\nThe UI process may compose local adapters during the migration seam, but the\nadapter implements the same wire-safe contract as the remote client. The\nproduction extraction cutover removes the in-process adapter in the same\nchange; a dual-live UI authority is not permitted.\n\n## Boundary and ownership\n\n| Concern | UI Service owns | UI Service may consume | UI Service must not own or receive |\n| ------------------ | -------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |\n| HTTP and SPA | routes, auth middleware, UI DTOs, assets, HTTP lifecycle | contract results and health snapshots | domain entities or infrastructure handles |\n| Chat | request validation and response projection | Gateway `ChatContract` | `gateway.Router`, `SessionStore`, turn runner, model/provider runtime |\n| Task dashboard | query/action DTOs and HTTP status mapping | State Store narrow contracts and explicitly ratified task-action contract | `*store.Store`, SQL connections, workflow registry, daemon pointer |\n| Configuration page | secret-free view and update request validation | a UI configuration contract owned by the configuration/application boundary | `config.Config`, `config.Holder`, secret registry, reload implementation |\n| Readiness | UI process liveness and dependency readiness aggregation | bounded health results from Gateway and State Store | direct probing of private databases or providers |\n\nEvery value crossing the process boundary is a versioned DTO or scalar contract\nvalue. `internal/webui` may retain temporary Go-side adapters while the\nmigration is in progress, but handlers must map Gateway/State Store values to\nUI-owned response types at the HTTP edge. A constructor accepting a concrete\nGateway, State Store, daemon, or `config.Holder` is not an approved final\nboundary.\n\nThe existing UI routes remain behaviourally compatible during extraction,\nincluding task actions, SSE event delivery, config views, chat streaming,\ncapture intake, mappings, bindings, update reporting, and health endpoints.\nCompatibility preserves status codes, authentication requirements, redaction,\npagination/limits, event ordering, and failure degradation unless a separately\nratified contract changes them.\n\nThe route families have these target owners. This is the required inventory for\nthe implementation children; a route without an owner is not eligible for\ncutover.\n\n| Route family | Target owner consumed by UI | Migration status Line truncated
},
{
"url": "/dev/prds/vue-migration-checklist/",
"title": "Preact → Vue 3 + shadcn-vue migration checklist",
"section": "PRDs",
"body": "# Preact → Vue 3 + shadcn-vue migration checklist\n\n**Status:** Approved\n**Date:** 2026-09-20\n**Bead:** `archie-core-tavn` (epic), `archie-core-ocfm` (navigation restructure)\n**Bootstrap commit:** `e18fb8b2`\n\nThe Preact dashboard was deleted, not ported incrementally. This is the list of\nwhat has to exist again, what must not be lost on the way, and the contracts\nthat break silently if missed.\n\nDeleted source is recoverable at `git show e18fb8b2^:ui/src/\u003cpath\u003e`. Every\nclaim below was cross-checked against that tree; where a number is a live\nmeasurement rather than something recoverable from git, it says so.\n\n## Invariants that outlive the framework\n\nThese are not features; they are things other processes depend on. Breaking one\ndoes not show up as a broken page.\n\n- [ ] **Embed contract.** `ui/embed.go` embeds a committed `ui/dist`. The build\n must keep unhashed `assets/index.{js,css}`: dist/ lives in git, and\n hashed names orphan a file on every rebuild.\n- [ ] **Route registry.** `internal/gateway/dashboard_tools.go` hand-copies the\n route table and `TestDashboardPagesRegistryCoversEveryRoute` parses\n `ui/src/router/index.ts` to hold them in step. The parser needs\n `const routes = [` on its own line, `path: \"...\"` on a single line per\n route, and `nav: false` on any entry the registry should skip. That guard\n caught a stale `/chat` entry earlier.\n- [ ] **Mutation headers.** Every POST/PATCH/DELETE must send **both**\n `X-Archie-CSRF: 1` and `Content-Type: application/json`. The server\n returns 403 without the first and 415 without the second\n (`internal/webui/api_tasks.go`, `authorizeTaskMutation`). GET sends\n neither. This is the single most likely thing to silently break every\n write after the port.\n- [x] **History routing.** `createWebHistory`, `base: \"/\"`. Legacy `#/path`\n links are rewritten by `src/legacy-hash-redirect.ts`. The chat navigate\n chip should emit `/tasks`; the Go side already stores bare paths.\n- [ ] **Capability gating.** `GET /api/capabilities`\n (`internal/webui/api_capabilities.go`) returns a `sections` map of ten\n booleans: chat, logs, skills, curators, channels, captures, mappings,\n bindings, and workflows/settings which are always true. A route whose\n section is false must be hidden, not rendered empty. **Fail open**: on a\n failed or null response hide nothing — the old client used a bare\n `.catch(() =\u003e {})` for exactly this. A page that says \"unavailable\" is\n recoverable; a nav entry that vanished is not.\n- [ ] **`LOG_LEVELS`** in `base/log-row.jsx` is a wire contract, not a display\n list: the CSV level filter is matched server-side by `splitCSV` in\n `internal/webui/api_tasks_logs.go`. A value mismatch breaks filtering\n with no error.\n- [ ] **SSE lifecycle.** Three streams, all `id: \u003cn\u003e\\ndata: \u003cjson\u003e\\n\\n` except\n chat which omits the id:\n `/events` (task lifecycle, `sse.go`, supports `?since=` and\n `Last-Event-ID` resume), `/api/logs/stream` (`api_logs.go`, same\n resume protocol), `/api/chat/stream` (`api_chat.go`, frames typed\n delta/tool/media/navigate). Each must be closed on unmount or the app\n leaks a connection per navigation. Preact used an `archie:teardown`\n event; Vue should use `onUnmounted`.\n\n\u003e **On tests.** Per Sam's call, the 43-file suite was not ported and tests\n\u003e return when there is behaviour worth pinning. Flagging one exception for when\n\u003e that moment comes: the deleted `ui/test/api-client.test.js` classified every\n\u003e API method as mutation/read/stream/url and asserted the right headers per\n\u003e class. It is the only cheap guard on the CSRF contract above. (It did **not**\n\u003e text-scan for a second `fetch()` — that check was deliberately removed\n\u003e upstream for testing the file's wording rather than its behaviour.)\n\n## Phase 1 — Foundation\n\n- [x] **Theme.** `css/tokens.css` was a complete two-theme semantic token set\n (`--fg-subtle`, `--accent`, `--ok/warn/danger`, surfaces, shadows). Mapped\n onto Tailwind v4's `@theme` in `src/style.css`; the second system was not\n kept.\n- [x] **`color-scheme`.** `[data-theme=\"dark\"] { color-scheme: dark }` and the\n light equivalent. Without it the UA paints light scrollbars and light\n native controls inside the dark app. Fixed; trivially lost.\n- [x] **Contrast values.** The violet palette moved these off the values pinned\n here, so they were recomputed against its own backgrounds instead of\n carried: `--fg-subtle` `#A99DBD` dark (7.67:1, AAA) / `#6E6577` light\n (4.87:1, AA), and `--fg-muted` `#B9AECB` / `#635B6B` (9.28:1 and 5.70:1).\n The invariant the pin existed for holds; the values are the palette's.\n- [x] **API client** (`base/api.jsx` → `src/lib/api.tLine truncated
},
{
"url": "/dev/prds/webhook-intake-security/",
"title": "Webhook intake security -- decision",
"section": "PRDs",
"body": "# Webhook intake security -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.5`, blocks `archie-core-t2db.4`\n\n## Why this is decided ahead of the code it constrains\n\n`archie-core-t2db` (no-code playbooks) and `archie-core-7d5u` (typed event\nsources) both land a public intake surface whose eventual output is an agent\nwith tool access and a repo. Neither capture (`t2db.1`) nor the intake family\n(`7d5u.3`) has shipped yet, so this decision exists to be a contract the two\nepics build against, not a retrofit once the surface exists. A webhook URL\nthat can start an agent is remote code execution with extra steps if any of\nthe five points below is missing on day one.\n\n## 1. Per-source authentication\n\nReuse the per-route HMAC-SHA256 scheme already in\n`internal/channels/webhook/webhook.go` (`validateHMAC`), unchanged: a source\nregisters with a shared secret; the signature is checked against the raw\nbody. Do not invent a second scheme for intake.\n\n**Capture and triggering split at the signature, not at a separate flag.** An\nevent with a missing or invalid signature is still captured (visible in the\ninspector, marked unauthenticated) so an operator can diagnose a\nmisconfigured sender -- but an unauthenticated event can never be matched\nagainst a binding. Authentication is what promotes an event from \"something\narrived\" to \"something that can run a workflow.\"\n\n## 2. Human approval before a binding arms\n\nA binding has three states: `draft -\u003e pending_approval -\u003e armed`. Only\n`armed` bindings are evaluated against incoming events. Creating or editing a\nbinding's matcher, mapping, or target workflow always sets it to\n`pending_approval`, including edits to an already-armed binding -- an edit is\nnot silently re-armed, or the approval gate is decorative. Approval requires\nan authenticated dashboard session; there is no unattended approval path.\n\nModel: `internal/channels/telegram`'s dangerous-command approval flow\n(`dangerousAction` / `pendingApproval` in `dangerous.go` / `approval.go`) is\nthe existing precedent for \"a human decision gates code from running\" in this\ncodebase -- follow its shape rather than designing a new approval primitive.\n\n## 3. Rate and volume limits, per source\n\nA token-bucket limiter keyed by source ID, not global -- one noisy or hostile\nsender must not exhaust another source's capture budget. Precedent for\nper-key volume capping: `internal/pairing/store.go`'s `MaxPendingPerPlatform`.\n\nOn limit exceeded, the request is rejected (HTTP 429), not silently dropped.\nA silently dropped event is indistinguishable from a sender that never fired\n-- the same invisible-failure shape the update-verification work\n(`archie-core-522`) exists to prevent. The rejection itself is observable in\nthe inspector as a distinct outcome from \"not received.\"\n\n## 4. Blast radius bounded by code, not by prompt wording\n\nA playbook-triggered task runs through exactly the same enforcement as every\nother task: the `[[repos.gate]]` quality gate, `diff_cap_lines`, the\nsandboxed per-task container (`internal/container`), worktree isolation, and\n\"the model never runs git.\" No new relaxation is introduced for\nplaybook-triggered work, and none is needed -- the existing constraints are\nthe control.\n\nMapped payload fields are treated as ordinary user-controlled text inside an\nagent prompt, exactly like an inbound chat message never as trusted\ninstructions. \"The agent should ignore instructions in the payload\" is not a\ncontrol and must not appear as one anywhere in this feature -- per the\nenvironmental-enforcement principle (`docs/architecture/agent-system.md`,\n\"Existing invariants to preserve\"), the boundary is the gate and the sandbox,\nnot a sentence in the system prompt.\n\n## 5. Retention and redaction of captured payloads\n\n**Retention:** captured events (bound or not) are purged after 7 days,\nconfigurable per deployment. Unbound events exist to be mapped against; nothing\njustifies keeping them indefinitely once that window has passed, and an\nunbounded capture store is the same disk-exhaustion risk item 3 addresses at\nthe request-rate level.\n\n**Redaction:** before a captured payload is persisted, apply the same\nkey-name heuristic `internal/gateway/stream.go`'s `sensitiveParameterKey`\nalready uses for tool-call parameters (matches `token`, `secret`, `password`,\n`passwd`, `api_key`, `apikey`, `authorization`, `credential`, `cookie`,\n`private_key` against normalised JSON keys) and replace matching values with\nthe same `[redacted]` marker. This is best-effort, not a guarantee -- a\nsender that names a secret field something the heuristic misses will still\nhave it captured. Document that limitation where captured payloads are\ndisplayed, rather than implying the redaction is complete.\n\n**Visibility:** captured payloads, redacted or not, are visible only to an\nauthenticated dashboarLine truncated
},
{
"url": "/dev/prds/workflow-call-outputs/",
"title": "Declared outputs of a workflow run",
"section": "PRDs",
"body": "# Declared outputs of a workflow run\n\n**Status:** Draft\n**Date:** 2026-09-30\n**Bead:** `archie-core-t2db.43`\n**Authority:** `docs/prds/event-automation.md` for what a declared output is,\n`docs/prds/workflow-calls.md` for the call and its grants,\n`docs/prds/state-store-contract.md` for the State Store contract the wire\nchange must satisfy.\n**Supersedes:** `docs/prds/workflow-calls.md`, \"Waiting on the callee\": the\ncallee's transition detail is the human summary, not the stand-in for\nstructured outputs.\n\nA workflow declares named, typed outputs. A run writes each one once. A\n`wait: true` caller receives them, and may publish one as its own.\n\n## Where outputs are declared\n\n`outputs:` on the workflow definition, beside `inputs:`, decoded into\n`task.WorkflowInterface.Outputs map[string]OutputSpec` where\n`OutputSpec{Type, Required}`:\n\n```yaml\nid: firewall-contain\noutputs:\n contained: { type: bool, required: true }\n summary: { type: string }\n```\n\nNames and types are the input grammar: the same identifier shape, the same\ntype set, and the same check in `WorkflowInterface.Validate`, which both\n`ParseDefinition` and `ParseWorkflowInterface` call.\n\n**Forced by:** `ParseDefinition` decodes with `KnownFields(true)`, so a key no\ndecoded struct declares is refused — the declaration must live on\n`WorkflowInterface` for an author to write it at all, and that is where\n`docs/development/workflows.md` puts every field a process without the engine\nmust read. The type set is the shared value vocabulary: `TypeAccepts` and\n`ValueType` already check a mapped parameter and an input with it. `required`\ndefaults to false, and the generated YAML for a builtin that declares no\noutputs is unchanged, because a definition's digest pins a run.\n\n**Rejected:** outputs per step, or per call step, because a workflow returns a\nresult as itself rather than as one of its stages. Also `task.Definition`\ngaining outputs: no reader needs them — a binding offers inputs, and a call's\noutputs assignment is checked against the callee's YAML in the same\ncollection — and a declared field with no reader parses and does nothing.\n\n## How a run writes one\n\nEach declared output is offered to the run's agent stages as a capture tool\nnamed after the output, whose arguments are `{\"value\": ...}`; the accepted\ncall's `value` member is the output's value. The engine holds the accepted\nvalues on the task context and writes them into its own task row in the\n`Store.Update` call the run already makes. A deterministic stage may set the\nsame values in Go, and the run's finish check validates them identically.\n\n**Forced by:** a run's only structured results are capture calls\n(`agentexec.CaptureTool`, `Result.Captures`), and the workflow interface\nalready declares when a stage needs them (`task.WorkflowNeeds.Captures`).\n`WorkflowInterface.Needs` reports `captures` for a non-empty `Outputs`, so\ndeclaring an output alone requires the capability and a Kit profile that\nserves no capture tools is refused before dispatch.\nDeriving the tools from the declaration means an output cannot be written\nunder a name nobody declared, and it keeps one route to structured agent\noutput rather than adding a second beside the capture path. The row write is\nthe run's existing write: the task row is where a run's own state lives, and\nthe container already holds `Update` on its own row.\n\nThe tool is offered with `MaxCalls: 1`, and a stage is not offered an output\nthe run has written, so a run writes each output once: a repeat within a stage\nis answered with the tool's rejection and the agent carries on, and a later\nstage cannot overwrite a value. A stage's own capture tool may not share a\nname with a declared output, because the value would otherwise be ambiguous.\n\n**Rejected:** a `workflow.output` step type, because assigning the run's\nresult from a step needs a grammar for \"the previous stage's result\" that does\nnot exist, and a step that reaches the agent would be the second path\n`docs/development/workflows.md` forbids. Also a write RPC of its own: the\ncontainer's `Update` already reaches its own row, and a second write verb for\none column is a second thing to keep in step.\n\n## How a caller receives one\n\nOn a successful `wait: true` call the caller's stage holds the callee's\noutputs as a `map[string]any`. A call step's `outputs:` setting publishes one\nas one of the caller's own outputs:\n\n```yaml\nsteps:\n - type: workflow.call\n workflow: firewall-contain\n wait: true\n inputs: { src_ip: inputs.src_ip }\n outputs: { contained: outputs.contained }\n```\n\nThe key names the callee's declared name; the value names one of the caller's\nown with the prefix the call's `inputs:` already uses. A published value joins\nthe caller's output set for its run, so a caller returns its callee's result to\nits own caller, and a run may publish a callee's output and write its own\notheLine truncated
},
{
"url": "/dev/prds/workflow-calls/",
"title": "Workflows calling workflows",
"section": "PRDs",
"body": "# Workflows calling workflows\n\n**Status:** Draft\n**Date:** 2026-09-26\n**Bead:** `archie-core-t2db.41`\n**Extends:** `docs/prds/event-automation.md` (workflow/binding/profile model), `docs/prds/state-store-contract.md` (two new RPCs), `docs/prds/execution-tree-state-machine.md` (call kind)\n\n## The call, end to end\n\n```\ncaller run (in agent container)\n workflow.call step ──StartCall──▶ State Store EnqueueCallTask(caller, workflow, inputs)\n │ callee task row: org/identity/owner/repo\n │ derived from the caller row server-side\n ▼\n callee task (queued, org of the caller)\n │ daemon claims, pins the callee's OWN\n │ definition → its OWN agent profile\n ▼\n callee run (its own container, own tree)\n wait: true ──poll──▶ State Store WorkflowCallStatus(caller, callee)\n wait: false ──continue\n```\n\nA `workflow.call` step starts the callee as a first-class task and, with\n`wait: true`, waits for its terminal state. The callee is never run \"inside\"\nthe caller: it gets its own task row, its own pinned definition, its own\nprofile, its own container, and its own outcome on its own run\n(`execution-tree-state-machine.md`).\n\n## Save-time checks (the collection is the authority)\n\nAll semantic checks run in `workflow.ValidateDefinitionCollection`, the gate\nevery save and load of the `workflow-definitions` resource passes through.\nA single-definition parse cannot see callees, so it validates shape only.\n\n- **Callee exists.** A call to a workflow outside the collection is refused.\n- **Inputs checked.** A call value is a literal or a reference\n (`inputs.\u003cname\u003e`) to the calling workflow's declared input. References must\n name a declared input; the resolved type must satisfy the callee's declared\n type; unknown callee inputs are refused; a required callee input must be\n assigned.\n- **Self-calls refused.** The call graph over the collection is walked from\n every workflow; a workflow that reaches itself, directly or through other\n workflows, is refused with the cycle path. (Cycles can otherwise deadlock:\n `wait: true` callers hold their containers.)\n- **Repository.** `workflow.call` needs no repository, so it is legal in a\n `repository: none` workflow: the callee inherits the caller's task record\n (owner/repo/identity/org), and the callee's own `repository` mode decides\n whether its run clones.\n- **Org enablement** (bead `archie-core-t2db.42`): the single\n instance-wide collection the current model serves is what \"enabled for\n the caller's org\" resolves against — an undefined callee parks. The\n callee's org is derived from the caller's row, so a callee is never\n visible outside its caller's org. The per-org enable/disable catalogue\n lands with `archie-core-t2db.42` and becomes the one source of this\n predicate.\n\n## Runtime\n\n**Depth limit.** `workflow.MaxCallDepth` (5). The calling stage refuses a call\nthat would exceed it; the store re-checks on insert (callee depth = caller\ndepth + 1), so no path can enqueue past the limit.\n\n**Starting the callee.** The caller runs inside a container whose task-scoped\nState Store grant authorizes only `Update`/`Transition`/`InsertEvent` on its\nown task — it can neither enqueue a task nor read another one. One new\ncontract RPC starts the callee:\n\n- `EnqueueCallTask(caller_task_id, workflow, inputs_json) → task`\n — the store reads the caller row, refuses a caller that is not `running`,\n refuses past the depth limit, and inserts the callee row deriving org,\n workspace, identity, owner, repo and a fresh synthetic issue number from\n the caller (the same org COALESCE `EnqueueIssue`/`InsertChatTask` use). The\n callee row carries `call_parent_task_id` and `call_depth`.\n\n**Waiting on the callee.** One new read RPC returns a call's callee:\n\n- `WorkflowCallStatus(caller_task_id, call_task_id) → (status, detail)` — the\n handler verifies `call_parent_task_id` matches, so a caller reads only its\n own callees, and returns the callee's status plus its latest transition\n detail (the callee's summary — the wait:true \"outputs\" until a structured\n outputs model lands).\n\nBoth RPCs are admitted to task-scoped grants on `caller_task_id == granted\ntask ID` (`authorizesTaskScopedCall` gains two request-shape cases). This is\nthe one sanctioned widening of a task grant: the callee is the caller's child,\nand starting it is the mechanism by which one event becomes several runs. The\nwidenings stay request-shape checks; the parent-child authorization is a\nhandler-side row check, so the interceptor never reads the database.\n\n**Schema.** `tasks` gains Line truncated
},
{
"url": "/dev/prds/workflow-step-vocabulary/",
"title": "Workflow step vocabulary: what a step type is and how binaries agree on it",
"section": "PRDs",
"body": "# Workflow step vocabulary: what a step type is and how binaries agree on it\n\n**Status:** Draft\n**Date:** 2026-09-29\n**Beads:** `archie-core-m7oc` (agreement between separately deployed binaries), `archie-core-ze7y` (the deleted `.archie/stages/*.go` equivalent)\n**Extends:** `docs/architecture/plugins-and-extensions.md` (plugin engine rule), `docs/prds/event-automation.md` (the workflow model step types serve)\n\n**Authority:** `docs/architecture/plugins-and-extensions.md` — the workflow step vocabulary is a Workflow capability family, and its extension point follows the plugin engine rule.\n\n## Decision\n\nA workflow step type is a named Go factory: the word a YAML workflow writes in\na step's `type` field, plus the factory that builds its stage. The name is a\nstable identifier; the identity also declares what plugin family claims it,\nso a contribution that shadows a shipped stage is refused instead of\noverriding it.\n\nThe Workflow domain owns the typed family contract — `StepTypeProvider` for a\ncontribution and `Manager` as the owning registry. A provider contributes a\nwhole set of step types under its own stable-identifier name; the manager\nvalidates the entire contribution before applying any of it (named provider,\nwell-formed step-type names, non-nil factories, no step type claimed twice,\nno claim on a name another provider holds) and applies it atomically. The\ngeneric `plugin.Plugin` contract stays metadata-only.\n\nThe vocabulary is a compiled-in, closed set. `internal/infrastructure/workflowsteps`\nis the one place a step type is bundled into any binary that resolves one: the\nshipped workflow stages, the repository-hook replacements (`gate.diff-rules`)\nand the repository-free event steps each arrive as one provider, and adding a\nstep type means adding a provider to that set. Interpreted plugin sources\ncannot contribute step types: the Yaegi plugin host satisfies only the\nmetadata contract, and no bridge to `StepFactory` exists.\n\nEvery binary that resolves a step type builds its manager from that same\nprovider set at its composition root, before its first resolution, and\ninjects the manager everywhere it resolves definitions. Agreement is per\nbuild: the State Store, the daemon's workflow-definitions client and the agent\nworker built from the same source register identical vocabularies by\nconstruction; binaries built from different sources can disagree, and only a\nmatching deploy fixes that.\n\nAn unknown step type is refused twice, and never degraded. The validator\n`ParseDefinition` refuses a definition naming an unregistered type at save\ntime, on the validating side the composition root built (the State Store's\nworkflow-definitions resource validates there before anything is stored). The\ncompiler refuses the same definition at run, so a binary handed a definition\nwritten against a vocabulary it does not have fails that run loudly instead of\nsilently skipping steps. Both checks live in the Workflow domain against the\ninjected manager, which is why no binary can opt out of the check by\nsubstituting its own registry.\n\n## Relationship between the questions\n\n`archie-core-ze7y` is the same question seen from the deleted\nrepository-authored stages: those `.archie/stages/*.go` files held arbitrary\nstages, and their gate half landed as `gate.diff-rules` settings rather\nthan interpreted Go. No interpreted-Go stage type is built, and nothing\napproximates one: the maintainer's trust decision (`archie-core-ndm8`) allows a\ncommand step type instead, and it arrives as a provider in the compiled-in set\nunder the rules above — a new contributor of exactly one step type at a named\nprovider (`command.run`, contributed by `command`). It is not a plugin\ncontribution mechanism and it changes no other answer in this document. The\nrefusal of `.archie/stages/*.go` therefore names `command.run` as its migration\ntarget, and each command it runs is the operator's own repository policy\nexpressed as argv.\n\n## Rejected alternatives\n\n- **A vocabulary version or hash on the wire.** The executing side already\n refuses an unknown step type at its first compile, which is the mismatch\n detector, and it fails closed. A wire field would only narrow the\n deploy-skew window that a matching deploy closes, at the cost of a new\n contract field.\n- **A Yaegi-plugin-to-`StepFactory` bridge.** It would run repository-supplied\n interpreted code inside the daemon's process with daemon privileges. The\n trust boundary invariant requires repository-authored code to run in the\n task container, not in an interpreter embeddable into any binary.\n- **A package-level process-global registrar.** Global mutable registry state\n is unreadable at the composition root, collides with itself when one\n process builds the vocabulary twice, and is what made the first attempt at\n this question worse instead of better.\n- **Degrading on an unknown step type.** A run that Line truncated
}
],
"nav": [
{
"title": "Architecture",
"url": "/dev/architecture/",
"items": [
{
"title": "Agent System",
"url": "/dev/architecture/agent-system/"
},
{
"title": "Playbook bindings: model and threat model",
"url": "/dev/architecture/bindings/"
},
{
"title": "Configuration",
"url": "/dev/architecture/configuration/"
},
{
"title": "The dashboard's tools for an in-browser agent",
"url": "/dev/architecture/dashboard-agent-tools/"
},
{
"title": "Dependencies and Contracts",
"url": "/dev/architecture/dependencies-and-contracts/"
},
{
"title": "Generated Documentation",
"url": "/dev/architecture/generated-documentation/"
},
{
"title": "Identity",
"url": "/dev/architecture/identity/"
},
{
"title": "Messaging and Work Intake",
"url": "/dev/architecture/messaging-and-work-intake/"
},
{
"title": "Architecture Migration Decisions",
"url": "/dev/architecture/migration-decisions/"
},
{
"title": "Task Observability",
"url": "/dev/architecture/observability/"
},
{
"title": "Repository Organisation",
"url": "/dev/architecture/organisation/"
},
{
"title": "Domain and Feature Review Procedure",
"url": "/dev/architecture/package-review/"
},
{
"title": "Plugins and Extensions",
"url": "/dev/architecture/plugins-and-extensions/"
},
{
"title": "Policy System",
"url": "/dev/architecture/policy/"
},
{
"title": "Safe Change and Recovery",
"url": "/dev/architecture/safe-change-and-recovery/"
}
]
},
{
"title": "Development guides",
"url": "/dev/development/",
"items": [
{
"title": "Agent",
"url": "/dev/development/agent/"
},
{
"title": "Control plane and settings",
"url": "/dev/development/control-plane/"
},
{
"title": "Daemon",
"url": "/dev/development/daemon/"
},
{
"title": "Frontend UI",
"url": "/dev/development/frontend-ui/"
},
{
"title": "Merging work",
"url": "/dev/development/merging-work/"
},
{
"title": "State Store",
"url": "/dev/development/state-store/"
},
{
"title": "Processes and wiring",
"url": "/dev/development/wiring/"
},
{
"title": "Workflows",
"url": "/dev/development/workflows/"
}
]
},
{
"title": "PRDs",
"items": [
{
"title": "Architecture Decision Index",
"url": "/dev/prds/01-project-management/"
},
{
"title": "PRD writing rules",
"url": "/dev/prds/RULES/"
},
{
"title": "Running action playbooks",
"url": "/dev/prds/action-playbook-run/"
},
{
"title": "Agent2Agent as archie's agent-to-agent protocol — decision",
"url": "/dev/prds/agent2agent-protocol/"
},
{
"title": "Artifact sender",
"url": "/dev/prds/artifact-sender/"
},
{
"title": "Binding secret at-rest encryption -- decision",
"url": "/dev/prds/binding-secret-encryption/"
},
{
"title": "Channel and Forge action positions (resolves `t2db.19`)",
"url": "/dev/prds/channel-forge-positions/"
},
{
"title": "Code graph over MCP (`tools/codegraph`)",
"url": "/dev/prds/code-graph-mcp/"
},
{
"title": "Example-config and generated-config drift — decision",
"url": "/dev/prds/config-example-drift/"
},
{
"title": "Backend-owned configuration schema for the webui -- decision",
"url": "/dev/prds/config-schema/"
},
{
"title": "Contract conformance audit — decision",
"url": "/dev/prds/contract-conformance-audit/"
},
{
"title": "Control-plane apply status",
"url": "/dev/prds/control-plane-apply-status/"
},
{
"title": "Curator sampler wave 1: `Sampler` interface + four cheap strategies -- decision",
"url": "/dev/prds/curator-sampler-wave1/"
},
{
"title": "Dashboard-aware chat: Archie sees the page, and points the operator there",
"url": "/dev/prds/dashboard-aware-chat-navigation/"
},
{
"title": "Dashboard live state",
"url": "/dev/prds/dashboard-live-state/"
},
{
"title": "Dashboard port: what the agent delivers",
"url": "/dev/prds/dashboard-port-brief/"
},
{
"title": "One source for the dashboard's server vocabularies",
"url": "/dev/prds/dashboard-vocabulary/"
},
{
"title": "Deep research capability — design",
"url": "/dev/prds/deep-research-capability/"
},
{
"title": "Dynamically-defined curators -- decision",
"url": "/dev/prds/dynamic-curators/"
},
{
"title": "Dynamic workflow triage",
"url": "/dev/prds/dynamic-workflow-triage/"
},
{
"title": "EDA playbook engine -- design",
"url": "/dev/prds/eda-playbook-engine/"
},
{
"title": "Embedded NATS execution -- decision",
"url": "/dev/prds/embedded-nats/"
},
{
"title": "Event automation: identified events, typed parameters, purpose-built agents",
"url": "/dev/prds/event-automation/"
},
{
"title": "Event capture storage -- decision",
"url": "/dev/prds/event-capture-storage/"
},
{
"title": "Event sources and reactions -- decision",
"url": "/dev/prds/event-sources-and-reactions/"
},
{
"title": "Execution tree and enforced state machine",
"url": "/dev/prds/execution-tree-state-machine/"
},
{
"title": "Extensions centre",
"url": "/dev/prds/extensions-center/"
},
{
"title": "External agent harnesses",
"url": "/dev/prds/external-agent-harness/"
},
{
"title": "Identity for users, agents and external agents — decision",
"url": "/dev/prds/identity-decision/"
},
{
"title": "Image capability contract and configuration",
"url": "/dev/prds/image-capability-contract/"
},
{
"title": "Inline review -- decision",
"url": "/dev/prds/inline-review/"
},
{
"title": "MCP client and tool-guardrail completion",
"url": "/dev/prds/mcp-tool-completion/"
},
{
"title": "Memory engine unification: four scopes, CRUD, and one write path -- decision",
"url": "/dev/prds/memory-engine-unification/"
},
{
"title": "Messaging Service boundary and transport design",
"url": "/dev/prds/messaging-service-boundary/"
},
{
"title": "Module position -- design",
"url": "/dev/prds/module-position/"
},
{
"title": "Multi-action playbooks and typed action results",
"url": "/dev/prds/multi-action-playbooks/"
},
{
"title": "Public news and per-version release notes",
"url": "/dev/prds/news-and-releases/"
},
{
"title": "Orgs, workspaces and access control",
"url": "/dev/prds/orgs-and-access/"
},
{
"title": "Payload field mapping -- decision",
"url": "/dev/prds/payload-field-mapping/"
},
{
"title": "Playbook data-flow and condition syntax",
"url": "/dev/prds/playbook-expression-syntax/"
},
{
"title": "Plugin settings reconcile live",
"url": "/dev/prds/plugin-settings-live/"
},
{
"title": "PR review agent",
"url": "/dev/prds/pr-review-agent/"
},
{
"title": "PR review: the operator's answer to the approval gate",
"url": "/dev/prds/pr-review-operator-response/"
},
{
"title": "PR review comment remediation -- decision",
"url": "/dev/prds/pr-review-remediation/"
},
{
"title": "Progressive tool disclosure (bridge tools) — wiring",
"url": "/dev/prds/progressive-tool-disclosure/"
},
{
"title": "Public and development documentation -- design",
"url": "/dev/prds/public-and-dev-docs/"
},
{
"title": "One release stream, one page per version, and commit rules — decision",
"url": "/dev/prds/release-stream-and-commit-rules/"
},
{
"title": "Review settings resource",
"url": "/dev/prds/review-settings-resource/"
},
{
"title": "Runtime control plane",
"url": "/dev/prds/runtime-control-plane/"
},
{
"title": "Self-update: artifact install, topology migration, journaled transaction",
"url": "/dev/prds/self-update-transaction/"
},
{
"title": "Service decomposition -- decision",
"url": "/dev/prds/service-decomposition/"
},
{
"title": "Service registry — one declaration per service",
"url": "/dev/prds/service-registry/"
},
{
"title": "Persistent session-memory curator (reference implementation) -- decision",
"url": "/dev/prds/session-memory-curator/"
},
{
"title": "Skill curator (reference implementation) -- decision",
"url": "/dev/prds/skill-curator/"
},
{
"title": "SOUL: an agent's user-authored personality",
"url": "/dev/prds/soul/"
},
{
"title": "State Store — contract boundary \u0026 transport (ratification)",
"url": "/dev/prds/state-store-contract/"
},
{
"title": "/status health surface",
"url": "/dev/prds/status-health-surface/"
},
{
"title": "Store",
"url": "/dev/prds/store/"
},
{
"title": "task_logs pagination and bounded retrieval -- decision",
"url": "/dev/prds/task-logs-pagination/"
},
{
"title": "Per-run task detail: attempts, stages, changes, config, debug",
"url": "/dev/prds/task-run-detail/"
},
{
"title": "Task run detail as a master-detail split pane",
"url": "/dev/prds/task-run-master-detail/"
},
{
"title": "UI Service boundary and configuration ownership",
"url": "/dev/prds/ui-service-boundary/"
},
{
"title": "Preact → Vue 3 + shadcn-vue migration checklist",
"url": "/dev/prds/vue-migration-checklist/"
},
{
"title": "Webhook intake security -- decision",
"url": "/dev/prds/webhook-intake-security/"
},
{
"title": "Declared outputs of a workflow run",
"url": "/dev/prds/workflow-call-outputs/"
},
{
"title": "Workflows calling workflows",
"url": "/dev/prds/workflow-calls/"
},
{
"title": "Workflow step vocabulary: what a step type is and how binaries agree on it",
"url": "/dev/prds/workflow-step-vocabulary/"
}
]
}
]
}
-41
View File
@@ -1,41 +0,0 @@
{
"pages": [
{
"url": "/docs/",
"title": "Archie",
"section": "",
"body": "# Archie\n\n**Event-driven Agentic Automation**\n\nArchie connects events from your systems to agents that can investigate, reason,\nand act. Define what an event means, map its data into a workflow, and give that\nworkflow an agent equipped for the job: its own execution environment, tools,\nand identity.\n\nThe aim is to automate work across system administration, incident response,\nnetwork operations, service management, and software delivery. You define the\nprocess and the access it requires; agents work through its stages, using the\ncontext of each event to decide how to accomplish the task.\n\nArchie is under active development. The model below describes the project's\napproved direction, with implementation progressing across event automation and\norganisation access control. The\n[event automation design](/dev/prds/event-automation/) and\n[organisations and access design](/dev/prds/orgs-and-access/) describe those\ncapabilities and their delivery stages.\n\n## From an event to an outcome\n\n```text\nEvent source → Event type → Mapping → Binding → Workflow → Agent\n```\n\n| Concept | Purpose |\n| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| **Source** | Receive events from a system such as a firewall, monitoring stack, service desk, or forge. Configure its endpoint and signing requirements. |\n| **Event type** | Identify which kind of event arrived from its headers and payload. Infer a schema from captured events or a pasted example. |\n| **Mapping** | Extract named, typed parameters from the event. Reuse a mapping across bindings and see how often it matches. |\n| **Binding** | Select a workflow, filter the events that should trigger it, and supply its inputs from mapped values or constants. |\n| **Workflow** | Define the stages of work, their inputs and outputs, and the agent profile to use. Call other workflows when work needs another specialist or process. |\n| **Agent** | Execute the work in a container with the tools for its purpose, acting under its own identity and granted permissions. |\n\nA single source can produce several event types. An event type can feed several\nbindings, and each binding can apply its own conditions. This lets the same\nincoming data drive different responses without building a custom integration\nfor every workflow.\n\nFor example, a firewall sends a blocked-connection event. Archie identifies the\nevent type and maps the source address and severity into an investigation\nworkflow. A network investigator gathers evidence, assesses the activity, and\nreturns its findings. The workflow could then call a separate containment\nworkflow, subject to the permissions and approvals configured for that action.\n\nThe same model supports other processes:\n\n- **Infrastructure operations:** A monitoring alert starts a diagnostic workflow\n to inspect a service, collect evidence, and propose or perform an authorised\n recovery action.\n- **Service management:** An incoming request supplies the parameters for a\n triage, investigation, or fulfilment workflow.\n- **Software delivery:** A forge event starts a review or implementation\n workflow with the repository's toolchain, validation steps, and pull request\n as its output.\n\nThese are examples of workflows you can build. Their behaviour comes from the\nworkflow, tools, and access you configure.\n\n## Agents equipped for their work\n\nAn agent profile selects the container image and available tools. You can supply\nimages with the software needed for a particular environment: network utilities\nfor an investigator, operational tooling for a systems agent, or a language\nruntime and test framework for repository work.\n\nWorkflows declare structured inputs and can return structured outputs. They can\nrun with a scratch workspace, require a repository, or accept one optionally. An\ninvestigation can finish with a report; a maintenance workflow can finish with\nan operational result; a coding workflow can finish with a pull request.\n\nWorkflows can also call other workflows and pass data between them. Each called\nworkflow has its own run and agent profile. A caller can wait for the result or\ncontinue while the called workflow runs independently.\n\nSee the\n[firewall investigation example](https://github.com/samcharles93/archie-core/blob/main/examples/workflows/firewall-investigate.yaml)\nfor a workflow that uses typed inputs, a network investigator profile, and no\nrepository.\n\n## Organisations, identities, and controlled execution\n\nThe approved access modLine truncated
},
{
"url": "/docs/guides/first-playbook/",
"title": "Building your first playbook binding",
"section": "Guides",
"body": "# Building your first playbook binding\n\nThis walks through the whole no-code path the event-capture epic promises:\npoint an external app's webhook at archie, see the real payload it sends,\nmap the fields you care about, bind them to a workflow, and watch the next\nmatching event turn into a task -- no code, no redeploy, no restart. See\n`docs/architecture/bindings.md` for the model and threat model behind each\nstep below.\n\n## 1. Send a test event\n\nPoint whatever external app you want archie to react to at:\n\n```\nPOST http://\u003cyour-archied-host\u003e:8484/webhooks/capture/\u003csource\u003e\n```\n\n`\u003csource\u003e` is a name you choose for this sender (e.g. `sentry`, `github-ci`,\n`stripe`) -- it's just a URL path segment, not a preset list. Send one real\nevent however is easiest for a first test, e.g.:\n\n```bash\ncurl -X POST http://localhost:8484/webhooks/capture/sentry \\\n -H \"Content-Type: application/json\" \\\n -d '{\"issue\": {\"title\": \"NullPointerException in checkout\"}, \"level\": \"error\"}'\n```\n\nThis event isn't signed yet, so it's captured but marked **unauthenticated**\n-- visible for you to design against, but incapable of triggering anything\n(`docs/architecture/bindings.md`'s threat-model section explains why: an\nunauthenticated event can never match a binding, no matter how it looks).\n\n## 2. Inspect the captured payload\n\nOpen the dashboard's **Event inspector** (`/captures`). Your test event\nappears there with its real body -- this is schema-by-example: you're\nlooking at an actual payload from the actual sender, not guessing at a\nschema in advance.\n\n## 3. Map the fields you care about\n\nOpen **Field mappings** (`/mappings`) → **New mapping**. Pick your captured\nevent from the dropdown, then click through its payload tree on the right --\nevery key and value is clickable. Clicking a value binds it as a field\n(name, JSON path, and an inferred type you can change). Add whichever fields\nyour workflow needs (e.g. the issue title), mark the ones that must be\npresent as **Required**, hit **Preview** to confirm they resolve correctly\nagainst the real payload, then **Save**.\n\n## 4. Create the binding\n\nOpen **Playbook bindings** (`/bindings`) → **New binding**:\n\n- **Name** -- anything descriptive.\n- **Source** -- the same `\u003csource\u003e` segment from step 1 (e.g. `sentry`).\n- **Field mapping** -- the one you just saved.\n- **Workflow** -- which registered workflow should run on a match.\n- **Repo pin** (optional) -- leave both blank to use the single configured\n repo; set owner/repo explicitly if you run a multi-repo deployment.\n- **Shared secret** -- a real secret (16+ bytes), never `test1234`. The\n sender signs every request body with this via HMAC-SHA256 so archie can\n tell a genuine event from anyone who finds the URL.\n\nSave. The binding starts in **draft** -- nothing fires yet.\n\n## 5. Approve it\n\nA **draft** or freshly-**edited** binding needs an explicit human approval\nbefore it can ever match a live event -- this is deliberate, not a missing\nstep: an operator authoring a binding is a considered act, an event arriving\nis not, and nothing should self-arm (`docs/architecture/bindings.md`'s\nthreat-model section, point 2). Click **Approve**. Status becomes **armed**.\n\n## 6. Fire it for real\n\nSend the same kind of event again, this time **signed** with the binding's\nsecret:\n\n```bash\nBODY='{\"issue\": {\"title\": \"NullPointerException in checkout\"}, \"level\": \"error\"}'\nSECRET=\"the-secret-you-set-in-step-4\"\nSIG=$(printf '%s' \"$BODY\" | openssl dgst -sha256 -hmac \"$SECRET\" | sed 's/^.* //')\n\ncurl -X POST http://localhost:8484/webhooks/capture/sentry \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Hub-Signature-256: sha256=$SIG\" \\\n -d \"$BODY\"\n```\n\nThis event is captured as **authenticated**, matched against your armed\nbinding, and dispatched into a new task through the exact same\ngate/worktree/sandbox pipeline every other task goes through -- see\n`docs/architecture/messaging-and-work-intake.md`'s \"Intake provenance\". Check\nthe **Tasks** page; a new task should appear, its body built from the fields\nyour mapping resolved.\n\n## Editing a live binding\n\nAny edit to an armed binding -- even a typo fix -- drops it back to\n**pending_approval** automatically. This can't be bypassed by editing; it\nhas to be re-approved. When editing, leave the **Shared secret** field blank\nto keep the existing secret; only fill it in if you're deliberately\nrotating it.\n"
},
{
"url": "/docs/guides/pr-review-benchmark/",
"title": "PR review benchmark",
"section": "Guides",
"body": "# PR review benchmark\n\nRun `scripts/pr-review-benchmark.sh` with `PRBENCH_REVIEW_MODEL` and\n`PRBENCH_CLASSIFICATION_MODEL` set to configured `provider/model` references.\nThe judge defaults to `anthropic/claude-sonnet-4.6`; set\n`PRBENCH_JUDGE_MODEL` to another configured model when needed. The script uses\n`~/.config/archie/config.toml` for providers and `GH_TOKEN` or `GITHUB_TOKEN`\nfor read access to the benchmark pull requests. It posts no forge review.\n\nThe default run reviews the 38 runnable Martian pull requests once each at\n`deep`, judges the comments against 102 golden comments, and writes\n`bin/prbench-results/run.json`, `summary.json`, and one JSON result per pull\nrequest. That output directory is ignored by git. A completed full run fails\nwhen any problem fails or golden micro-recall is below 0.70. Golden-only\nprecision is reported alongside recall. Set `PRBENCH_OUT` to keep separate\nruns; `-problems ID` limits a smoke run to one pull request. Completed results\nare saved as each PR finishes. Pass `-resume DIR` to reuse completed results\nfrom a run with the same models; each reused problem must match the current\nbenchmark entry, and failed problems are rerun.\nA smoke run alone is not the acceptance run.\n\nThe benchmark passes only each problem's ID and pull request URL to the\nreviewer. The judge receives the golden comments after the review has ended.\nThe runner uses the production decision phases through the merge gate,\nincluding scoring and the 25-comment cap, then stops before polish and forge\nposting. A reviewer that fails to finish makes that problem fail. The results\nrecord budget-skipped phases and the selected models. Model substitutions do\nnot satisfy the PRD's named-model criterion even if recall clears the threshold.\n"
}
],
"nav": [
{
"title": "Archie",
"url": "/docs/"
},
{
"title": "Guides",
"items": [
{
"title": "Building your first playbook binding",
"url": "/docs/guides/first-playbook/"
},
{
"title": "PR review benchmark",
"url": "/docs/guides/pr-review-benchmark/"
}
]
}
]
}
-34
View File
@@ -1,34 +0,0 @@
# Prompt for Claude Code
Unzip this bundle into the repo at `docs/design/ui-redesign/`, then paste the prompt below.
---
The design handoff for the Archie UI redesign is in `docs/design/ui-redesign/`. It covers a new theme, a new
top-level navigation, the Settings pages (Channels moves in there), and the Dashboard, Task detail, Workflows,
New task dialog and Events pages.
Read `README.md` in full, then look at every PNG in `screenshots/`. The `00-current-*.png` files show how the
pages look today; `P0-navigation-map.png` shows what moves where. The static HTML in `mockups/` has the exact
CSS if you need it. `tokens/tokens.css` holds the colours, fonts and sizes.
Treat the spec as a hypothesis to check against the code, not a spec to copy exactly.
Before changing anything:
1. Find how the UI is built: framework, router, component library, where styles and theme colours live,
and where the purple comes from.
2. Map today's routes and the Work / System menus to the proposed navigation in README §2. List every
page that isn't covered and where you'd put it.
3. For Settings and Channels: find how each section loads and saves config, how "Restart required",
"Version", "History" and the audit log work, and where "Connecting" comes from. Map every field in
README §5 to its real config key and type.
4. Answer the backend questions in README §5.2 and §9.
5. Check what data the Dashboard, Task detail and Workflows pages already get, and list anything the
mockups show that isn't available.
Then write a short migration plan using the PR sequence in README §8. Adjust it to what you found and
list anything the mockups assume that the backend doesn't support. Stop and show me the plan before you
write code.
When I approve, do PR 1 only (theme tokens across the whole app, no layout changes) on a new branch, with
before/after screenshots of each page.
-277
View File
@@ -1,277 +0,0 @@
# Archie UI Redesign — Handoff
A redesign of the Archie web UI:
- a calmer **"Graphite" theme** that replaces the purple
- a **new navigation**: five top-level places, with all configuration moved under Settings
- new layouts for **Settings** (every section, plus Channels moved in), the **Dashboard**,
**Task detail**, **Workflows**, a **New task** dialog and **Events**
This folder is self-contained. Read this file first, then look at the screenshots.
```
README.md ← this spec (read it all before planning)
CLAUDE_PROMPT.md ← the prompt to paste into Claude Code
tokens/tokens.css ← theme as CSS custom properties (source of truth)
tokens/tokens.json ← same values as JSON (for Tailwind / JS themes)
screenshots/
00-current-*.png ← how each page looks TODAY
P0-navigation-map ← today → proposed navigation, and what moves where
P1…P5 ← app pages: dashboard, task detail, workflows, new task, events
S1…S5 ← settings: sidebar + rows, personas, tools & MCP, review drawer, channels
T-theme-components ← palette, type, buttons, pills, toggles, inputs
mockups/*.html ← static HTML of each screenshot; open in a browser, inspect for exact CSS
source/*.dc.html ← original design-canvas sources (reference only, needs a runtime that isn't included)
```
> **How to treat this.** The mockups are a target, not a pixel spec. They are static HTML
> written by hand; the app's framework, component library, router and data model win. Where the
> mockups assume something the backend doesn't have, flag it rather than faking it.
> Text in `[square brackets]` in a mockup is a placeholder for real data.
---
## 1. Problems being fixed (all pages)
1. **Purple everywhere.** Purple-tinted backgrounds, borders, buttons, checkboxes, bars and links all compete for attention.
2. **Repeated chrome.** Every settings card has its own "Connecting" pill, "Restart required" pill, "Version 1",
"Save changes" and "History". Workflows and Channels repeat the pattern.
3. **Raw config shapes leak through.** Durations as Go strings (`1h0m0s`, `0s`), bytes as `2000000`,
maps as key/value boxes, secret refs as two separate Engine/Key text fields, booleans as bare checkboxes with no explanation.
4. **No descriptions.** Almost no field says what it does.
5. **Things live in the wrong place.** Channels (configuration) sits under Work; "Start work" sits inside the
workflow editor page; the Channels audit table only covers Channels; workflow analytics mix every workflow together.
6. **The most important information isn't first.** The Dashboard opens with quality gates; the "3 need you" count is a small button.
## 2. Navigation (screenshot `P0-navigation-map.png`)
**Top bar (every page):** logo · **Dashboard · Tasks · Workflows · Events · Settings** · spacer ·
"Jump to…" search (⌘K) · **New task** button · connection pill · account avatar.
The Work and System dropdowns go away. The floating chat button stays, restyled (neutral fill, accent icon).
| Place | Job | Contains |
|---|---|---|
| Dashboard | What needs me right now | Needs-you queue, live activity, health (quality gates, tokens) |
| Tasks | The work | Task list (filter by state), task detail |
| Workflows | How work runs | List with runs/success/cost, definition editor, Performance and Runs tabs |
| Events | What comes in | Inspector, Mappings, Bindings |
| Settings | Everything you configure | **Agents:** Personas, Schedules, Scheduling policy · **Integrations:** Channels, Tools & MCP, Plugins · **Runtime:** Container runtime · **History** |
What moves:
| What | Moves to | Why |
|---|---|---|
| Start work card (Workflows page) | **New task** dialog from the top bar and ⌘K | Starting work isn't editing a workflow |
| Channels (Work menu) | Settings › Integrations › Channels | It's configuration; gets the shared setting rows and save flow |
| Audit table (Channels page) | Settings › History, filterable by section | One change log for all settings; replaces per-card History links |
| Per workflow table | Columns in the Workflows list | Stats next to the workflow you're about to open |
| Slowest stages · Most failures | Workflow › Performance tab | Scoped to the selected workflow |
| Connecting / Version pills on every card | One connection status in the top bar | Connection is global |
| Settings "Managed elsewhere" row | Removed; those are the Events tabs | They already live there |
| Task "Attempt 2 is not recorded" column | Attempts list in the task side rail | Shows every attempt and its outcome |
The dropdown contents of today's Work and System menus were inferred from screenshots. **Check the router** and
place any page not covered here using the same rule: configure → Settings, act on → where the work is.
## 3. Theme
All values are in `tokens/tokens.css`. Rules that matter more than the hex values:
- **One accent, used sparingly.** Default sage `#86b5a0`. Only for: active nav/list item (2px inset left bar + raised background),
active tab underline, focus borders/rings, "edited" dots and counts, toggle "on" track, primary button fill, success text,
the "live"/"running"/"connected" dot, and positive bars. Never for backgrounds, headings or borders at rest.
- Keep the accent a **single variable** so it can be swapped (sage / steel `#8aa4c2` / sand `#d4a373` / muted violet `#a397c9`).
- **Neutral, slightly warm greys**, no hue tint on surfaces and no background gradients. Hierarchy comes from surface steps and borders.
- **Amber = needs attention** (parked, awaiting reply, applies after restart, connecting). **Red = failed / destructive / risky**
(errors, delete, unrestricted filesystem). No other hues except the agent state swatches in the tokens.
- **Fonts:** IBM Plex Sans for UI; **IBM Plex Mono for every machine value**: config values, IDs, keys, env var names,
image refs, durations, paths, event names, task numbers, log lines, counts in tables.
- Text contrast: `--text-3` is the dimmest text allowed, and only for hints and captions.
## 4. Components (screenshot `T-theme-components.png`)
Build these once and reuse everywhere. Heights are 36px unless noted.
| Component | Spec |
|---|---|
| **Button** | primary (accent fill, `--text-on-accent`), secondary (`--raised` + `--border-button`), ghost (transparent, `--text-2`), destructive (red text, transparent). 13px/500, radius 6. Small variant 30px/12px. **One primary per view.** |
| **Text input** | `--bg` fill, `--border-input`, radius 6, mono 13px. Focus: accent border + 3px `--accent-ring`. Invalid: red border + 12px red message. |
| **Input with unit** | input + attached suffix (`MB`, `sec`, `chars`) or unit `<select>`. |
| **Duration input** | number + unit select. Convert to/from Go durations (`30s`, `1m0s`, `72h0m0s`) only at the API boundary. |
| **Byte size input** | number + `MB`; store bytes (2,000,000 bytes = 2 MB, decimal). |
| **Stepper** | − / value / + for small integers. |
| **Toggle** | 36×20 track. On = accent (or red for risky settings), off = `--border-input`. Always labelled; risky ones sit in a bordered row with a one-line consequence. Real checkbox / `role="switch"` underneath. |
| **Segmented control** | 2–4 exclusive options, radiogroup with arrow keys. Selected segment `--raised-2`. |
| **Tabs** | 44px, 13px, `--text-3`; active = `--text` + 2px accent underline. Left-aligned, sized to content (not stretched full width). Optional mono count chip. |
| **Secret reference** | one row: lock icon · engine (mono, dim) · `/` · key (mono) · "Change". Status line below: accent ✓ "Credential resolved by Archie" or red "Credential not found". Replaces separate Engine/Key inputs and the "Credential configured" checkbox. |
| **Chip input** | for lists of IDs (Telegram allowed users): mono chips with × plus an inline input. |
| **Status pill** | radius 999, 12px. Neutral with coloured dot (connection, running, listening), warn (parked, awaiting reply, applies after restart), accent outline (edited count, default), danger (invalid). |
| **Card** | `--surface`, `--border-card`, radius 10. Header row: optional 32px icon tile · title (15px/500) + hint · right-side status/action. |
| **Stat strip** | one card split into equal cells by 1px dividers: label (12px dim), value (30px/600), sub (12px dim). |
| **Data table** | uppercase 11px headers, 13px rows, 1px `--border-subtle` dividers, mono for machine values, long text truncates with ellipsis. |
| **Progress bar** | 4–6px track `--raised-2`, fill accent (good) or red (failing). |
| **Empty state** | icon tile + title + one-line hint + the action (a button, or a copyable value). |
| **Alert banner** | amber or red tinted box: icon · title · mono detail · one action on the right. |
| **Nav item** (sidebars) | 34–36px, radius 6, 13px `--text-2`. Active: `--raised` + 2px inset accent bar. |
| **Dialog** | 640px, `--surface-2`, radius 12, header (title + hint + close), body, footer (shortcut hint · Cancel · primary). Dim backdrop. |
Icons: 2px-stroke line icons. Use the app's existing icon set if it has one (e.g. Lucide).
## 5. Settings
### 5.1 Settings shell (`S1-settings-sidebar-setting-rows*.png`)
- **Left sidebar (248–264px)** with grouped nav: AGENTS (Personas, Schedules, Scheduling policy), INTEGRATIONS (Channels, Tools & MCP, Plugins),
RUNTIME (Container runtime), divider, History. Optional mono counts (Personas `6`). A section with unsaved edits shows an accent dot.
- **Content column** max ~920–980px. Section header: 24px title, 14px description, amber "Applies after restart" pill when relevant.
- **Groups** inside a section: 13px uppercase eyebrow.
- **Setting row:** 2-column grid `260–280px | 1fr`, gap 32px, 16–20px vertical padding, 1px top border.
Left: label (13px/500) + hint (12px dim). Right: the control.
- Sidebar items are links (route or hash per section).
### 5.2 Save model (`S1` save bar + `S4-settings-review-drawer.png`)
Replace every per-card Save button with one page-level flow:
1. Track edits per field against the loaded config. Edited inputs get an accent border and a "was `old`" hint.
2. When anything is dirty, a **sticky save bar** appears: accent dot · "N unsaved change(s)" · field names · **Discard** · primary
**"Save & restart"** if any dirty field needs a restart, otherwise **"Save"**.
3. The primary button opens the **Review drawer** (480px, right, dim backdrop): "Review N changes", "Saved together as config version N+1",
amber restart callout (optionally with running agent count), changes grouped by section as cards with **Revert** and a mono diff
(red `− old`, green `+ new`), footer Discard all · Save only · Save & restart.
4. Personas keep their own save footer in the editor panel but still feed the page dirty state.
**Backend questions to answer first:** can several sections be saved atomically (or will saves be sequential with partial-failure handling)?
Is "restart required" known per field or per section? Is there a restart action? If not, "Save & restart" becomes "Save" plus a
persistent "Restart pending" banner.
### 5.3 Personas (`S2-settings-personas.png`)
- Left: filter + New; list rows = name + one-line prompt; default persona has an accent-outline **default** pill; selected row = raised + accent bar.
- Right: editor. Header: name + default pill · Duplicate · Delete. Body: Name (mono) and **Default persona** toggle; **System prompt** as a large
mono textarea with "N chars · ~N tokens". Footer: "Saved · version N · History" · Discard · Save persona.
- The old separate "Default" field becomes the per-persona toggle (setting one unsets the others).
- The "try this persona" preview row is optional/future.
- The mockup uses **top tabs** for section navigation; that's the narrow-width fallback. Use the sidebar shell on desktop.
### 5.4 Schedules
Not mocked. Card empty state ("No schedules yet" + "Add schedule"); populated = list rows like Personas.
### 5.5 Scheduling policy (`S1`)
- DISPATCH: *Trigger* segmented Assignee / Label (show the Label input only when Label is chosen); *Ack reaction* mono input.
- STATE LABELS: bordered table `STATE | LABEL | ⌫` with coloured state swatch, mono label input, trash button, "+ Add state".
Today's UI shows display name ("Dead"), key (`dead`) and value (`agent:dead`); the mockup merges name and key.
If the key must stay editable, keep a small mono input in the State column.
- RETRIES & POLLING: *Max retries* stepper; *Poll interval* duration input.
### 5.6 Channels (moved from Work; `S5-settings-channels.png`, today `00-current-channels.png`)
- One card per channel. **Configured** channels are expanded with setting rows; **unconfigured** ones collapse to a single row
(icon · name · one-line purpose · "Not set up" pill · **Set up** button that expands the fields).
- **Telegram** (running): header status pill "Running" (accent). Rows: *Bot token* = secret reference (`env / HEYARCHIE_TELEGRAM_BOT_TOKEN`) + resolved line;
*Allowed users* = chip input of numeric IDs, hint "Everyone else is ignored."
- **Email** (collapsed): expands to *Listen address*, *Relay address*.
- **Webhook** (collapsed): expands to *Deliver to*, *Path*, *Template*, *Signing secret* (secret reference), and *Webhook address*
(today's top-level "Webhook addr" belongs here if it only serves the webhook channel; confirm).
- **CHAT SESSION DEFAULTS · ALL CHANNELS** card with setting rows: *Workspace* (mono path), *Filesystem access* (Unrestricted filesystem toggle in a
**red** bordered row: "On: agents can read and write anywhere this user can."), *Show tool calls* toggle, *Max steps*
("0 = no limit": **confirm the real semantics**), *Rate limit* as "[n] requests per [n] [unit]" ("Off while either value is 0": confirm),
*Models*, *Operator*.
- Footer line: "Version N · N fields set by `actor` N ago · View in History". The audit table itself moves to Settings › History.
- Channel status (running / stopped / error) must come from the backend, not from whether it's configured.
### 5.7 Tools & MCP (`S3-settings-tools-mcp.png`)
- Header action **Add MCP server**. MCP servers card (full width): empty state offering "stdio command" / "HTTP / SSE endpoint"
(only the transports the backend supports); populated rows = name, transport, enabled toggle, edit/delete.
- **MiniMax** card: header "Enabled" toggle; API key as secret reference (`bws / MINIMAX_API_KEY`) + resolved line.
- **Web fetch** card: "Enabled" toggle; *Max download* (bytes as MB); *Timeout* (duration, sec); *Allow private networks* as a bordered
toggle row. Disable the fields when the card is off.
- **Tool output policy** card: *Max result length* (`chars`, hint "About N tokens per tool call", ~4 chars/token), *Spill directory*.
### 5.8 Plugins
Not mocked. Setting rows for *Module dir*, *Plugin dir*, *Secret engine dir*, *Skills dir* (mono, placeholder = effective default if exposed).
### 5.9 Container runtime (left side of `S4`)
*Image* (full width, mono), *Max concurrency* (stepper), *Max uptime* (duration), *Network* (mono),
*Pull policy* (select: If missing / Always / Never → `missing` / `always` / `never`), *Volume TTL* (duration), *Profiles* (mono).
### 5.10 History (new, not mocked)
The Channels audit table generalised to all settings: When · Section · Field (mono) · Old → New (mono, truncated, expandable) ·
Version · Changed by. Filters: section, actor, date. Every "History" link elsewhere deep-links here with the section filter applied.
## 6. App pages
### 6.1 Dashboard (`P1-dashboard.png`, today `00-current-dashboard.png`)
- Header: "Good morning" + a one-line summary that **names the action** ("Nothing is running. 3 tasks need you." with the count in amber). Logs button on the right.
- **Stat strip**: Working now / Needs you (amber value) / Delivered / Tokens used, with the same subtitles as today.
- Two columns: main (1fr) and right rail (380px).
- Main, first: **Needs you** card (count pill). One row per task: state pill (Parked / Awaiting reply) · title (link) ·
mono meta line (`repo #issue · workflow · reason or last message`, truncated) · **Open** (ghost) + the next action
(**Start new run** for parked, **Reply** for awaiting). "All tasks" link in the header.
- Main, second: **Live activity** table: Event (mono, small colour square by kind, `×N` chip when consecutive identical events are grouped) · Task (mono) ·
Detail (truncated) · When. Header: live pill + segmented filter All / Tasks / System.
- Right rail: **Quality gates** (big pass rate, one row per gate with `passed / runs` and a bar: red when failing, accent when passing) and
**Token outlook** (Today, "Next 30 days at this rate", a 7-day mini bar chart, and a note when history is shorter than a week).
Today's full-width purple bar that shows nothing is removed.
### 6.2 Task detail (`P2-task-detail.png`, today `00-current-task-detail.png`)
- Breadcrumb `Tasks / #1`, title, meta row: status pill · workflow (mono) · `repo #issue` link. Actions: **Archive** (ghost), **Start a new run** (primary).
- **Alert banner** for parked/failed tasks: plain-language title ("Parked: couldn't prepare the worktree"), mono error detail, "Jump to log line".
- Two columns: main card with tabs **Log · Changed files (count) · Configuration · Debug**; right rail (320px).
- Log tab: toolbar = level select, stage select, search, Download. Log lines in mono: time · level (ERROR in red) · message with tag chips
(`component=daemon`, `task=1`). Error lines get a faint red background and red left border. Footer "End of attempt N · N lines".
- Right rail: **Attempts** list (dot colour = outcome; selected attempt highlighted; unrecorded attempts shown dimmed) and
**Details** list (Status, Workflow link, Repository, Issue ↗, plus Persona, Tokens, Started if available).
### 6.3 Workflows (`P3-workflows.png`, today `00-current-workflows.png`)
- Header: title + description ("Success rate is merged tasks over all runs"), **Restore shipped** (ghost), **New workflow**.
- Left (420px): list = name + id (mono) · runs · success (`n of m` + bar) · avg tokens (compact: 4.7M, 282k). Selected = raised + accent bar.
- Right: editor card. Header: name + origin pill (e.g. "shipped · edited"; derive from the real origin field) + run count.
Tabs **Definition · Performance · Runs**.
- Definition: *ID* input; *Steps* read-only preview (mono step chips joined by arrows, parsed from YAML);
*YAML* editor with line numbers, mono, light syntax colouring, live "✓ Valid" / error indicator.
Footer: "Version N · History" · Remove (destructive ghost) · Restore this workflow · **Validate & save**.
- Performance (not mocked): today's **Slowest stages** and **Most failures**, filtered to this workflow.
- Runs (not mocked): tasks that used this workflow, linking to Task detail.
- The **Start work** card leaves this page (see 6.4).
### 6.4 New task dialog (`P4-new-task-dialog.png`)
Replaces the Start work card. Opened from the top bar button, ⌘K, and optionally from a workflow ("Start task with this workflow").
- Fields: *Repository* (mono, hint with recent repos), *Workflow* as a 3-column card radiogroup showing each workflow's runs and merge rate,
*Title*, *Instructions* (textarea), and **Identity** tucked into an "Advanced · run as identity" disclosure.
- Footer: "⌘↵ to start" · Cancel · **Start task**. On success, go to the new task's detail page.
### 6.5 Events (`P5-events.png`, today `00-current-events.png`)
- Header with description ("Webhooks come in, get mapped to event types, and bindings turn them into work.") and a **Listening** pill.
- Left-aligned tabs **Inspector · Mappings · Bindings** with count chips. (Reordered to follow the flow; keep the old order if you prefer.)
- Inspector: a 3-step strip **Capture → Map → Bind** with counts; then **Recent captures** (empty state with the copyable endpoint
`/webhooks/capture/<source>` and a Copy button) and **Event types** ("From payload" action, empty state explaining proposals).
## 7. Behaviour and accessibility
- Real `<button>`, `<a href>`, `<input>`, `<select>`, `<label for>`; icon-only buttons get `aria-label`. Toggles use checkbox/`role="switch"`.
Segmented controls and workflow cards are radiogroups with arrow-key support. Dialogs trap focus and close on Esc.
- Visible focus everywhere (accent ring). Touch targets ≥36px (44px on mobile).
- Validate on blur; invalid fields block Save and are listed in the save bar.
- Unsaved-changes guard on route leave.
- Skeleton rows while loading; the top-bar connection pill reflects the socket/API state (Connecting amber, Connected accent, Disconnected red).
- Live tables (activity, captures) insert new rows without layout jump; group consecutive identical events.
- Narrow widths (<960px): settings sidebar → top tabs; two-column layouts stack; drawers and dialogs go full-width.
## 8. Suggested PR sequence
1. **Theme tokens only.** Swap purple for Graphite across the whole app. No layout changes. *Done when no purple remains.*
2. **Shared components** from §4.
3. **Top bar + navigation** (§2): new top-level items, New task button (can open the existing Start work form at first), one connection pill, route moves/redirects.
4. **Settings shell** (sidebar groups, setting rows) and move Channels into it. Sections still save the old way.
5. **Settings sections**: Scheduling policy, Plugins, Container runtime, Tools & MCP, Channels, Personas.
6. **Unified save bar + review drawer + Settings › History** (needs the §5.2 backend decisions). Remove per-card save buttons and pills.
7. **Dashboard.**
8. **Task detail.**
9. **Workflows** (list + editor + Performance tab) and **New task dialog**; remove the Start work card.
10. **Events.**
Each PR: before/after screenshots and a note of anything deferred or unsupported.
## 9. Open questions / out of scope
- Real meaning of `max_steps = 0` and a zero rate limit (the mockup assumes "no limit" / "off").
- Whether "Webhook addr" is webhook-channel-only or global.
- Where the Dashboard's Needs-you reasons and last agent message come from.
- Persona preview, light theme, user-facing accent picker (nice to have).
- Atomic multi-section save and "restart now" (see §5.2).
@@ -1,95 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Proposed navigation</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a}
.eyebrow{font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:#8f8c85;font-weight:500}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.node{display:flex;align-items:baseline;gap:10px;font-size:14px;font-weight:500}
.sub{font-size:12px;color:#8f8c85;font-weight:400}
.kid{margin:6px 0 0 18px;padding-left:14px;border-left:1px solid #2e3034;display:flex;flex-direction:column;gap:6px;font-size:13px;color:#a6a39b}
.mono{font-family:'IBM Plex Mono',monospace}
.tbl{width:100%;border-collapse:collapse;font-size:13px}
.tbl th{text-align:left;font-weight:500;font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#8f8c85;padding:10px 14px;border-bottom:1px solid #2a2c30}
.tbl td{padding:10px 14px;border-bottom:1px solid #202225;vertical-align:top;line-height:1.45}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 1120px; box-sizing: border-box; padding: 48px 56px; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; display: flex; flex-direction: column; gap: 28px">
<div>
<h1 style="margin: 0; font-size: 28px; font-weight: 600; letter-spacing: -0.01em">Navigation: today → proposed</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Five top-level places, each with one job. Anything you configure lives in Settings; anything you act on lives where the work is.</p>
</div>
<div style="display: grid; grid-template-columns: 380px minmax(0, 1fr); gap: 24px">
<section class="card" style="padding: 24px; display: flex; flex-direction: column; gap: 16px">
<div class="eyebrow">Today</div>
<div class="node" style="color: #a6a39b">Dashboard</div>
<div><div class="node" style="color: #a6a39b">Work <span class="sub">dropdown</span></div>
<div class="kid"><span>Tasks</span><span>Workflows <span class="sub">editor + start work + stats</span></span><span>Channels <span class="sub">settings + audit</span></span></div></div>
<div><div class="node" style="color: #a6a39b">Events</div>
<div class="kid"><span>Inspector · Bindings · Mappings</span></div></div>
<div><div class="node" style="color: #a6a39b">System <span class="sub">dropdown</span></div>
<div class="kid"><span>Advanced <span class="sub">6 cards, 6 save buttons</span></span></div></div>
<p class="hint" style="margin: 8px 0 0">Dropdown contents are inferred from the screenshots; confirm against the router.</p>
</section>
<section class="card" style="padding: 24px">
<div class="eyebrow" style="margin-bottom: 16px; color: #86b5a0">Proposed</div>
<div style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 24px 32px">
<div><div class="node">Dashboard <span class="sub">what needs me</span></div>
<div class="kid"><span>Needs you queue</span><span>Live activity</span><span>Health: gates, tokens</span></div></div>
<div><div class="node">Tasks <span class="sub">the work</span></div>
<div class="kid"><span>Task list <span class="sub">filter by state</span></span><span>Task detail <span class="sub">log · files · config · debug</span></span><span>Attempts in a side rail</span></div></div>
<div><div class="node">Workflows <span class="sub">how work runs</span></div>
<div class="kid"><span>List with success + cost</span><span>Definition editor</span><span>Performance tab <span class="sub">stages, failures</span></span></div></div>
<div><div class="node">Events <span class="sub">what comes in</span></div>
<div class="kid"><span>Inspector</span><span>Bindings</span><span>Mappings</span></div></div>
<div style="grid-column: span 2"><div class="node">Settings <span class="sub">everything you configure, one save flow</span></div>
<div class="kid" style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 6px 24px">
<span><span style="color: #e8e6e1">Agents</span><br>Personas · Schedules · Scheduling policy</span>
<span><span style="color: #e8e6e1">Integrations</span><br>Channels · Tools &amp; MCP · Plugins</span>
<span><span style="color: #e8e6e1">Runtime</span><br>Container runtime · History</span>
</div></div>
</div>
<div style="margin-top: 24px; padding-top: 16px; border-top: 1px solid #232529; display: flex; gap: 24px; font-size: 13px; color: #a6a39b">
<span><span style="color: #e8e6e1; font-weight: 500">Always in the top bar:</span> New task · ⌘K Jump to · connection status</span>
</div>
</section>
</div>
<section class="card" style="overflow: hidden">
<table class="tbl">
<thead><tr><th style="width: 290px">What</th><th style="width: 280px">Moves to</th><th>Why</th></tr></thead>
<tbody>
<tr><td style="color: #e8e6e1">Start work card (Workflows)</td><td><span style="color: #86b5a0">→</span> New task dialog, from the top bar</td><td style="color: #a6a39b">Starting work is not editing a workflow. One entry point from any page, and from ⌘K.</td></tr>
<tr><td style="color: #e8e6e1">Channels (Work menu)</td><td><span style="color: #86b5a0">→</span> Settings › Integrations › Channels</td><td style="color: #a6a39b">It is configuration. It gets the same setting rows, secret fields and save flow as the rest.</td></tr>
<tr><td style="color: #e8e6e1">Audit table (Channels page)</td><td><span style="color: #86b5a0">→</span> Settings › History</td><td style="color: #a6a39b">One change log for every setting, filterable by section. Replaces six History links.</td></tr>
<tr><td style="color: #e8e6e1">Per workflow table</td><td><span style="color: #86b5a0">→</span> Workflows list columns</td><td style="color: #a6a39b">Runs, success and cost sit next to the workflow you are about to open.</td></tr>
<tr><td style="color: #e8e6e1">Slowest stages · Most failures</td><td><span style="color: #86b5a0">→</span> Workflow › Performance tab</td><td style="color: #a6a39b">Scoped to the selected workflow instead of mixing every workflow in one table.</td></tr>
<tr><td style="color: #e8e6e1">Connecting · Version pills on every card</td><td><span style="color: #86b5a0">→</span> One status in the top bar</td><td style="color: #a6a39b">Connection is global. Version shows once per page, in History.</td></tr>
<tr><td style="color: #e8e6e1">Settings "Managed elsewhere" row</td><td><span style="color: #86b5a0">→</span> Events tabs</td><td style="color: #a6a39b">Captured events, mappings and bindings already live there.</td></tr>
<tr><td style="color: #e8e6e1">Task "Attempt 2 is not recorded" column</td><td><span style="color: #86b5a0">→</span> Attempts list in the task side rail</td><td style="color: #a6a39b">Shows every attempt with its outcome; the empty column goes away.</td></tr>
<tr><td style="color: #e8e6e1">Dashboard stat cards and health</td><td><span style="color: #86b5a0">→</span> Stat strip + right rail</td><td style="color: #a6a39b">"Needs you" becomes the first thing on the page, with actions inline.</td></tr>
</tbody>
</table>
</section>
</div>
</body>
</html>
@@ -1,187 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Dashboard</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
.card-h{display:flex;align-items:center;gap:12px;padding:16px 20px;border-bottom:1px solid #232529}
.card-t{font-size:15px;font-weight:500}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.eyebrow{font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:#8f8c85;font-weight:500}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
.warn{color:#d9a45b;border-color:rgba(217,164,91,.3);background:rgba(217,164,91,.08)}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.nav a.on{color:#e8e6e1;background:#1e2023}
.tbl{width:100%;border-collapse:collapse;font-size:13px}
.tbl th{text-align:left;font-weight:500;font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#8f8c85;padding:10px 20px;border-bottom:1px solid #2a2c30}
.tbl td{padding:10px 20px;border-bottom:1px solid #202225;vertical-align:middle}
.chip{font:11px 'IBM Plex Mono',monospace;color:#8f8c85;background:#1e2023;border-radius:4px;padding:1px 6px;margin-left:6px}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden; position: relative">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#" class="on">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
<div style="flex-grow: 1"></div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
</header>
<main style="flex-grow: 1; padding: 32px 48px; display: flex; flex-direction: column; gap: 24px; min-height: 0">
<div style="display: flex; align-items: flex-end; gap: 16px">
<div style="flex-grow: 1">
<h1 style="margin: 0; font-size: 28px; font-weight: 600; letter-spacing: -0.01em">Good morning</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Nothing is running. <span style="color: #d9a45b">3 tasks need you.</span></p>
</div>
<button class="btn"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 6h16M4 12h10M4 18h13"></path></svg>Logs</button>
</div>
<section class="card" style="flex-direction: row">
<div style="flex: 1 1 0; padding: 18px 22px; border-right: 1px solid #232529">
<div class="hint">Working now</div>
<div style="font-size: 30px; font-weight: 600; margin-top: 6px; color: #e8e6e1">0</div>
<div class="hint" style="margin-top: 2px">0 waiting to start</div>
</div>
<div style="flex: 1 1 0; padding: 18px 22px; border-right: 1px solid #232529">
<div class="hint">Needs you</div>
<div style="font-size: 30px; font-weight: 600; margin-top: 6px; color: #d9a45b">3</div>
<div class="hint" style="margin-top: 2px">Parked or awaiting a reply</div>
</div>
<div style="flex: 1 1 0; padding: 18px 22px; border-right: 1px solid #232529">
<div class="hint">Delivered</div>
<div style="font-size: 30px; font-weight: 600; margin-top: 6px; color: #e8e6e1">1</div>
<div class="hint" style="margin-top: 2px">25% of all tasks</div>
</div>
<div style="flex: 1 1 0; padding: 18px 22px; border-right: 1px solid #232529">
<div class="hint">Tokens used</div>
<div style="font-size: 30px; font-weight: 600; margin-top: 6px; color: #e8e6e1">14.5M</div>
<div class="hint" style="margin-top: 2px">Across 1 day</div>
</div>
</section>
<div style="display: grid; grid-template-columns: minmax(0, 1fr) 380px; gap: 24px; min-height: 0; flex-grow: 1">
<div style="display: flex; flex-direction: column; gap: 24px; min-width: 0">
<section class="card">
<div class="card-h"><span class="card-t">Needs you</span><span class="pill warn">3</span><div style="flex-grow: 1"></div><a href="#" class="hint" style="text-decoration: underline">All tasks</a></div>
<div style="display: grid; grid-template-columns: 120px minmax(0, 1fr) auto; gap: 16px; align-items: center; padding: 14px 20px; border-bottom: 1px solid #202225">
<span class="pill warn" style="justify-self: start">Parked</span>
<div style="min-width: 0">
<a href="#" style="font-size: 14px; font-weight: 500">changes_captured key-set validation is top-level only</a>
<div class="mono" style="font-size: 12px; color: #8f8c85; margin-top: 3px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">archie-core #868 · tdd · worktree prepare failed: fetch origin: http transport…</div>
</div>
<div style="display: flex; gap: 8px"><button class="btn btn-sm btn-ghost">Open</button><button class="btn btn-sm">Start new run</button></div>
</div>
<div style="display: grid; grid-template-columns: 120px minmax(0, 1fr) auto; gap: 16px; align-items: center; padding: 14px 20px; border-bottom: 1px solid #202225">
<span class="pill warn" style="justify-self: start">Awaiting reply</span>
<div style="min-width: 0">
<a href="#" style="font-size: 14px; font-weight: 500">[Task title]</a>
<div class="mono" style="font-size: 12px; color: #8f8c85; margin-top: 3px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">[repo #issue] · [workflow] · [last agent message]</div>
</div>
<div style="display: flex; gap: 8px"><button class="btn btn-sm btn-ghost">Open</button><button class="btn btn-sm">Reply</button></div>
</div>
<div style="display: grid; grid-template-columns: 120px minmax(0, 1fr) auto; gap: 16px; align-items: center; padding: 14px 20px; border-bottom: 1px solid #202225">
<span class="pill warn" style="justify-self: start">Awaiting reply</span>
<div style="min-width: 0">
<a href="#" style="font-size: 14px; font-weight: 500">[Task title]</a>
<div class="mono" style="font-size: 12px; color: #8f8c85; margin-top: 3px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">[repo #issue] · [workflow] · [last agent message]</div>
</div>
<div style="display: flex; gap: 8px"><button class="btn btn-sm btn-ghost">Open</button><button class="btn btn-sm">Reply</button></div>
</div>
</section>
<section class="card" style="flex-grow: 1; overflow: hidden">
<div class="card-h"><span class="card-t">Live activity</span><span class="pill" style="color: #86b5a0; border-color: #86b5a0"><span class="dot" style="background: #86b5a0"></span>live</span><div style="flex-grow: 1"></div>
<div role="radiogroup" aria-label="Filter activity" style="display: inline-flex; padding: 2px; border: 1px solid #2e3034; border-radius: 7px"><button style="height: 26px; padding: 0 10px; border: 0; border-radius: 5px; background: #26282c; color: #e8e6e1; font: 500 12px 'IBM Plex Sans', sans-serif">All</button><button style="height: 26px; padding: 0 10px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 12px 'IBM Plex Sans', sans-serif">Tasks</button><button style="height: 26px; padding: 0 10px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 12px 'IBM Plex Sans', sans-serif">System</button></div>
</div>
<table class="tbl">
<thead><tr><th>Event</th><th style="width: 70px">Task</th><th>Detail</th><th style="width: 110px">When</th></tr></thead>
<tbody>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #6f6c66"></span>curator_run</td><td class="mono" style="font-size: 12px; color: #a6a39b">—</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">session-memory</td><td class="hint">19 mins ago</td></tr>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #8aa4c2"></span>task_archive_requested</td><td class="mono" style="font-size: 12px; color: #a6a39b">#5</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">archive requested with no recorded actor</td><td class="hint">1 hr ago</td></tr>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #d9776b"></span>task_abandoned</td><td class="mono" style="font-size: 12px; color: #a6a39b">#5</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">abandoned with no recorded actor</td><td class="hint">1 hr ago</td></tr>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #6f6c66"></span>curator_run<span class="chip">×6</span></td><td class="mono" style="font-size: 12px; color: #a6a39b">—</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">session-memory</td><td class="hint">1 hr ago</td></tr>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #8aa4c2"></span>stage_start<span class="chip">×4</span></td><td class="mono" style="font-size: 12px; color: #a6a39b">#5</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis"></td><td class="hint">1 hr ago</td></tr>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #8aa4c2"></span>stage_start<span class="chip">×5</span></td><td class="mono" style="font-size: 12px; color: #a6a39b">#4</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis"></td><td class="hint">7 hrs ago</td></tr>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #86b5a0"></span>agent_finish</td><td class="mono" style="font-size: 12px; color: #a6a39b">#4</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">Problem surface for samcharles93/archie-core issue 836 ("Updater cannot detect o…</td><td class="hint">7 hrs ago</td></tr>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #86b5a0"></span>agent_finish</td><td class="mono" style="font-size: 12px; color: #a6a39b">#4</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">Root cause</td><td class="hint">7 hrs ago</td></tr>
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #8aa4c2"></span>stage_start<span class="chip">×6</span></td><td class="mono" style="font-size: 12px; color: #a6a39b">#4</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis"></td><td class="hint">8 hrs ago</td></tr>
</tbody>
</table>
</section>
</div>
<div style="display: flex; flex-direction: column; gap: 24px">
<section class="card">
<div class="card-h"><span class="card-t">Quality gates</span><div style="flex-grow: 1"></div><span class="hint">last 4 runs</span></div>
<div style="padding: 20px; display: flex; flex-direction: column; gap: 16px">
<div style="display: flex; align-items: baseline; gap: 10px"><span style="font-size: 30px; font-weight: 600">25%</span><span class="hint">pass rate</span></div>
<div>
<div style="display: flex; font-size: 13px; margin-bottom: 6px"><span class="mono">tdd</span><span style="margin-left: auto; color: #a6a39b" class="mono">0 / 3</span></div>
<div style="height: 6px; border-radius: 3px; background: #26282c"><div style="height: 6px; border-radius: 3px; width: 2%; background: #d9776b"></div></div>
</div>
<div>
<div style="display: flex; font-size: 13px; margin-bottom: 6px"><span class="mono">triage</span><span style="margin-left: auto; color: #a6a39b" class="mono">1 / 1</span></div>
<div style="height: 6px; border-radius: 3px; background: #26282c"><div style="height: 6px; border-radius: 3px; width: 100%; background: #86b5a0"></div></div>
</div>
</div>
</section>
<section class="card">
<div class="card-h"><span class="card-t">Token outlook</span></div>
<div style="padding: 20px; display: flex; flex-direction: column; gap: 14px">
<div style="display: flex; gap: 24px">
<div><div class="hint">Today</div><div style="font-size: 22px; font-weight: 600; margin-top: 2px">14.5M</div></div>
<div><div class="hint">Next 30 days at this rate</div><div style="font-size: 22px; font-weight: 600; margin-top: 2px">≈ 434M</div></div>
</div>
<div aria-label="Tokens per day, last 7 days" style="display: flex; align-items: flex-end; gap: 6px; height: 64px">
<div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">M</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">T</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">W</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">T</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 48px; border-radius: 3px; background: #86b5a0"></div><span class="mono" style="font-size: 10px; color: #8f8c85">F</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">S</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">S</span></div>
</div>
<div class="hint">Only 1 day of history. The projection steadies after a week of runs.</div>
</div>
</section>
</div>
</div>
</main>
<button aria-label="Chat with Archie" style="position: absolute; right: 24px; bottom: 24px; width: 48px; height: 48px; border-radius: 50%; border: 1px solid #34373c; background: #1e2023; color: #86b5a0; display: flex; align-items: center; justify-content: center; box-shadow: 0 8px 24px rgba(0,0,0,.4); cursor: pointer"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a8 8 0 0 1-11.6 7.1L4 20l1-4.6A8 8 0 1 1 21 12Z"></path></svg></button>
</div>
</body>
</html>
@@ -1,127 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Task detail</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
.card-h{display:flex;align-items:center;gap:12px;padding:14px 20px;border-bottom:1px solid #232529}
.card-t{font-size:14px;font-weight:500}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
.warn{color:#d9a45b;border-color:rgba(217,164,91,.3);background:rgba(217,164,91,.08)}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.nav a.on{color:#e8e6e1;background:#1e2023}
.tab{height:44px;display:flex;align-items:center;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
.sel{height:32px;box-sizing:border-box;padding:0 10px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:13px 'IBM Plex Sans',sans-serif}
.kv{display:grid;grid-template-columns:96px minmax(0,1fr);gap:10px;font-size:13px;padding:8px 0;border-bottom:1px solid #202225}
.kv dt{color:#8f8c85}.kv dd{margin:0}
.tag{font:11px 'IBM Plex Mono',monospace;color:#a6a39b;background:#1e2023;border-radius:4px;padding:1px 6px}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 1000px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#" class="on">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
<div style="flex-grow: 1"></div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
</header>
<main style="flex-grow: 1; padding: 24px 48px 32px; display: flex; flex-direction: column; gap: 20px; min-height: 0">
<div>
<div class="hint"><a href="#" style="color: #a6a39b">Tasks</a> / <span class="mono">#1</span></div>
<div style="display: flex; align-items: flex-start; gap: 16px; margin-top: 8px">
<div style="flex-grow: 1; min-width: 0">
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">changes_captured key-set validation is top-level only</h1>
<div style="display: flex; align-items: center; gap: 12px; margin-top: 8px; font-size: 13px; color: #a6a39b">
<span class="pill warn"><span class="dot" style="background: #d9a45b"></span>Parked</span>
<span class="mono">tdd</span><span style="color: #4a4c50">·</span>
<a href="#" class="mono" style="color: #a6a39b; text-decoration: underline">samcharles93/archie-core #868</a>
</div>
</div>
<button class="btn btn-ghost">Archive</button>
<button class="btn btn-primary"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a9 9 0 1 1-3-6.7L21 8"></path><path d="M21 3v5h-5"></path></svg>Start a new run</button>
</div>
</div>
<div role="alert" style="display: flex; gap: 12px; padding: 14px 16px; border-radius: 8px; background: rgba(217,164,91,0.08); border: 1px solid rgba(217,164,91,0.25)">
<svg style="flex-shrink: 0; margin-top: 2px" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#d9a45b" stroke-width="2"><path d="M12 3 2 20h20L12 3Z"></path><path d="M12 10v4M12 17h.01"></path></svg>
<div style="min-width: 0; flex-grow: 1">
<div style="font-size: 14px; font-weight: 500; color: #e3c08f">Parked: couldn’t prepare the worktree</div>
<div class="mono" style="font-size: 12px; color: #a6a39b; margin-top: 4px; line-height: 1.6; word-break: break-all">fetch origin: http transport: Get "https://github.com/samcharles93/archie-core.git/info/refs?service=git-upload-pack": terminated signal received</div>
</div>
<button class="btn btn-sm" style="align-self: flex-start">Jump to log line</button>
</div>
<div style="display: grid; grid-template-columns: minmax(0, 1fr) 320px; gap: 24px; flex-grow: 1; min-height: 0">
<section class="card" style="overflow: hidden">
<nav style="display: flex; gap: 28px; padding: 0 20px; border-bottom: 1px solid #232529">
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: #86b5a0">Log</a>
<a class="tab" href="#">Changed files <span class="hint" style="margin-left: 6px">0</span></a>
<a class="tab" href="#">Configuration</a>
<a class="tab" href="#">Debug</a>
</nav>
<div style="display: flex; align-items: center; gap: 8px; padding: 12px 20px; border-bottom: 1px solid #232529">
<select aria-label="Level" class="sel"><option>All levels</option></select>
<select aria-label="Stage" class="sel"><option>All stages</option></select>
<label style="display: flex; align-items: center; gap: 8px; height: 32px; width: 260px; padding: 0 10px; box-sizing: border-box; border: 1px solid #2e3034; border-radius: 6px; color: #8f8c85"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Search log" placeholder="Search log" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: 13px 'IBM Plex Sans', sans-serif; width: 100%"></label>
<div style="flex-grow: 1"></div>
<button class="btn btn-sm btn-ghost"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 4v11M7 10l5 5 5-5M5 20h14"></path></svg>Download</button>
</div>
<div class="mono" style="font-size: 12px; line-height: 1.7; flex-grow: 1; background: #121314">
<div style="display: grid; grid-template-columns: 72px 56px minmax(0, 1fr); gap: 12px; padding: 10px 20px; background: rgba(217,119,107,0.06); border-left: 2px solid #d9776b">
<span style="color: #8f8c85">08:38:49</span>
<span style="color: #e0a39a">ERROR</span>
<div style="min-width: 0">
<div style="word-break: break-all">task parked: worktree prepare failed: fetch origin: http transport: Get "https://github.com/samcharles93/archie-core.git/info/refs?service=git-upload-pack": terminated signal received</div>
<div style="display: flex; gap: 6px; margin-top: 6px"><span class="tag">component=daemon</span><span class="tag">task=1</span></div>
</div>
</div>
<div style="padding: 16px 20px; color: #8f8c85; font-family: 'IBM Plex Sans', sans-serif; font-size: 12px">End of attempt 1 · 1 line</div>
</div>
</section>
<aside style="display: flex; flex-direction: column; gap: 20px">
<section class="card">
<div class="card-h"><span class="card-t">Attempts</span></div>
<div style="padding: 8px 12px">
<a href="#" style="display: flex; align-items: center; gap: 10px; padding: 10px 8px; border-radius: 6px; background: #1e2023; box-shadow: inset 2px 0 0 #86b5a0">
<span class="dot" style="background: #d9a45b"></span><span style="font-size: 13px; flex-grow: 1">Attempt 1</span><span class="hint">parked · 08:38</span></a>
<div style="display: flex; align-items: center; gap: 10px; padding: 10px 8px; color: #8f8c85">
<span class="dot" style="background: transparent; border: 1px dashed #4a4c50; box-sizing: border-box"></span><span style="font-size: 13px; flex-grow: 1">Attempt 2</span><span class="hint">not recorded</span></div>
</div>
</section>
<section class="card">
<div class="card-h"><span class="card-t">Details</span></div>
<dl style="margin: 0; padding: 4px 20px 12px">
<div class="kv"><dt>Status</dt><dd style="color: #d9a45b">Parked</dd></div>
<div class="kv"><dt>Workflow</dt><dd><a href="#" class="mono" style="text-decoration: underline">tdd</a></dd></div>
<div class="kv"><dt>Repository</dt><dd class="mono" style="font-size: 12px">samcharles93/archie-core</dd></div>
<div class="kv"><dt>Issue</dt><dd><a href="#" style="text-decoration: underline">#868</a> ↗</dd></div>
<div class="kv"><dt>Persona</dt><dd class="mono" style="font-size: 12px">[persona]</dd></div>
<div class="kv"><dt>Tokens</dt><dd class="mono" style="font-size: 12px">[tokens]</dd></div>
<div class="kv" style="border: 0"><dt>Started</dt><dd>[date · time]</dd></div>
</dl>
</section>
</aside>
</div>
</main>
</div>
</body>
</html>
@@ -1,152 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Workflows</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.lbl{font-size:13px;font-weight:500}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.nav a.on{color:#e8e6e1;background:#1e2023}
.tab{height:44px;display:flex;align-items:center;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
.step{font:12px 'IBM Plex Mono',monospace;padding:6px 10px;border:1px solid #2e3034;border-radius:6px;background:#121314;white-space:nowrap}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#" class="on">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
<div style="flex-grow: 1"></div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
</header>
<main style="flex-grow: 1; padding: 32px 48px; display: flex; flex-direction: column; gap: 24px; min-height: 0">
<div style="display: flex; align-items: flex-end; gap: 12px">
<div style="flex-grow: 1">
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Workflows</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">The step sequences agents follow. Success rate is merged tasks over all runs.</p>
</div>
<button class="btn btn-ghost"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 12a9 9 0 1 0 3-6.7L3 8"></path><path d="M3 3v5h5"></path></svg>Restore shipped</button>
<button class="btn"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New workflow</button>
</div>
<div style="display: grid; grid-template-columns: 420px minmax(0, 1fr); gap: 24px; flex-grow: 1; min-height: 0">
<section class="card" style="overflow: hidden">
<div style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; padding: 10px 16px; font-size: 11px; letter-spacing: .06em; text-transform: uppercase; color: #8f8c85; border-bottom: 1px solid #2a2c30"><span>Workflow</span><span>Runs</span><span>Success</span><span style="text-align: right">Avg tok</span></div>
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: #1e2023; box-shadow: inset 2px 0 0 #86b5a0">
<span><span style="font-size: 14px; font-weight: 500; display: block">Bootstrap</span><span class="mono" style="font-size: 11px; color: #8f8c85">bootstrap</span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b">0</span>
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">—</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 0%; background: #86b5a0"></span></span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">—</span>
</a>
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: transparent; box-shadow: none">
<span><span style="font-size: 14px; font-weight: 500; display: block">Feasibility check</span><span class="mono" style="font-size: 11px; color: #8f8c85">feasibility</span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b">0</span>
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">—</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 0%; background: #86b5a0"></span></span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">—</span>
</a>
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: transparent; box-shadow: none">
<span><span style="font-size: 14px; font-weight: 500; display: block">Implement</span><span class="mono" style="font-size: 11px; color: #8f8c85">implement</span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b">0</span>
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">—</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 0%; background: #86b5a0"></span></span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">—</span>
</a>
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: transparent; box-shadow: none">
<span><span style="font-size: 14px; font-weight: 500; display: block">Remediate</span><span class="mono" style="font-size: 11px; color: #8f8c85">remediate</span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b">0</span>
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">—</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 0%; background: #86b5a0"></span></span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">—</span>
</a>
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: transparent; box-shadow: none">
<span><span style="font-size: 14px; font-weight: 500; display: block">TDD</span><span class="mono" style="font-size: 11px; color: #8f8c85">tdd</span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b">3</span>
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">0 of 3</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 2%; background: #d9776b"></span></span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">4.7M</span>
</a>
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: transparent; box-shadow: none">
<span><span style="font-size: 14px; font-weight: 500; display: block">Triage</span><span class="mono" style="font-size: 11px; color: #8f8c85">triage</span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b">1</span>
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">1 of 1</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 100%; background: #86b5a0"></span></span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">282k</span>
</a>
</section>
<section class="card" style="overflow: hidden">
<div style="display: flex; align-items: center; gap: 12px; padding: 18px 24px 0">
<h2 style="margin: 0; font-size: 18px; font-weight: 600">Bootstrap</h2>
<span class="pill">shipped · edited</span>
<div style="flex-grow: 1"></div>
<span class="hint">0 runs yet</span>
</div>
<nav style="display: flex; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529">
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: #86b5a0">Definition</a>
<a class="tab" href="#">Performance</a>
<a class="tab" href="#">Runs</a>
</nav>
<div style="padding: 20px 24px; display: flex; flex-direction: column; gap: 18px; flex-grow: 1; min-height: 0">
<div style="display: grid; grid-template-columns: 280px minmax(0, 1fr); gap: 24px">
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="wid">ID</label><input id="wid" class="inp" value="bootstrap"></div>
<div style="display: flex; flex-direction: column; gap: 6px"><span class="lbl">Steps</span>
<div style="display: flex; align-items: center; gap: 6px; height: 36px; flex-wrap: nowrap; overflow: hidden">
<span class="step">prepare</span><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#4a4c50" stroke-width="2"><path d="M5 12h14M13 6l6 6-6 6"></path></svg><span class="step">apply</span><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#4a4c50" stroke-width="2"><path d="M5 12h14M13 6l6 6-6 6"></path></svg><span class="step">commit-push</span><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#4a4c50" stroke-width="2"><path d="M5 12h14M13 6l6 6-6 6"></path></svg><span class="step">diff-cap</span><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#4a4c50" stroke-width="2"><path d="M5 12h14M13 6l6 6-6 6"></path></svg><span class="step">open-pr</span>
</div></div>
</div>
<div style="display: flex; flex-direction: column; gap: 6px; flex-grow: 1; min-height: 0">
<div style="display: flex; align-items: baseline"><span class="lbl">YAML</span><span class="hint" style="margin-left: auto; color: #86b5a0">✓ Valid</span></div>
<div class="mono" style="flex-grow: 1; display: grid; grid-template-columns: 44px minmax(0, 1fr); border: 1px solid #2e3034; border-radius: 8px; background: #121314; font-size: 13px; line-height: 1.75; overflow: hidden">
<div style="padding: 14px 0; text-align: right; padding-right: 12px; color: #4f5156; border-right: 1px solid #232529; background: #141517; white-space: pre-line">1
2
3
4
5
6
7</div>
<div style="padding: 14px 16px; white-space: pre"><span style="color: #a6a39b">id:</span> bootstrap
<span style="color: #a6a39b">steps:</span>
- <span style="color: #a6a39b">type:</span> <span style="color: #86b5a0">bootstrap.prepare</span>
- <span style="color: #a6a39b">type:</span> <span style="color: #86b5a0">bootstrap.apply</span>
- <span style="color: #a6a39b">type:</span> <span style="color: #86b5a0">bootstrap.commit-push</span>
- <span style="color: #a6a39b">type:</span> <span style="color: #86b5a0">bootstrap.diff-cap</span>
- <span style="color: #a6a39b">type:</span> <span style="color: #86b5a0">bootstrap.open-pr</span></div>
</div>
</div>
</div>
<div style="display: flex; align-items: center; gap: 10px; padding: 14px 24px; border-top: 1px solid #2a2c30; background: #17181a">
<span class="hint">Version 1 · <a href="#" style="color: #a6a39b; text-decoration: underline">History</a></span>
<div style="flex-grow: 1"></div>
<button class="btn btn-ghost" style="color: #d9776b">Remove</button>
<button class="btn">Restore this workflow</button>
<button class="btn btn-primary">Validate &amp; save</button>
</div>
</section>
</div>
</main>
</div>
</body>
</html>
@@ -1,77 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>New task dialog</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.lbl{font-size:13px;font-weight:500}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.inp{box-sizing:border-box;height:38px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
.field{display:flex;flex-direction:column;gap:6px}
.opt{display:flex;flex-direction:column;gap:2px;padding:10px 12px;border:1px solid #2e3034;border-radius:8px;cursor:pointer}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 900px; box-sizing: border-box; position: relative; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
<div style="flex-grow: 1"></div>
<button class="btn btn-sm" style="border-color: #86b5a0"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
</header>
<div style="padding: 32px 48px"><div style="font-size: 28px; font-weight: 600; color: #3a3c40">Good morning</div></div>
<div style="position: absolute; inset: 0; background: rgba(8,9,10,0.6)"></div>
<section role="dialog" aria-modal="true" aria-labelledby="nt-title" style="position: absolute; left: 50%; top: 88px; transform: translateX(-50%); width: 640px; box-sizing: border-box; background: #17181a; border: 1px solid #2a2c30; border-radius: 12px; box-shadow: 0 24px 64px rgba(0,0,0,0.5); display: flex; flex-direction: column">
<div style="display: flex; align-items: flex-start; padding: 22px 24px 18px; border-bottom: 1px solid #232529">
<div style="flex-grow: 1"><h2 id="nt-title" style="margin: 0; font-size: 18px; font-weight: 600">New task</h2><div class="hint" style="margin-top: 2px">Goes into Archie’s normal task queue.</div></div>
<button aria-label="Close" style="width: 32px; height: 32px; border: 0; background: transparent; color: #8f8c85; cursor: pointer"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 6l12 12M18 6 6 18"></path></svg></button>
</div>
<div style="padding: 20px 24px; display: flex; flex-direction: column; gap: 18px">
<div class="field"><label class="lbl" for="repo">Repository</label><input id="repo" class="inp" value="samcharles93/archie-core"><span class="hint">owner/repository · recent: archie-core</span></div>
<div class="field"><span class="lbl">Workflow</span>
<div role="radiogroup" aria-label="Workflow" style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 8px">
<label class="opt" style="border-color: #86b5a0; background: #1e2023"><span style="font-size: 13px; font-weight: 500">TDD</span><span class="hint">3 runs · 0% merged</span></label>
<label class="opt" style="border-color: #2e3034; background: transparent"><span style="font-size: 13px; font-weight: 500">Triage</span><span class="hint">1 run · 100% merged</span></label>
<label class="opt" style="border-color: #2e3034; background: transparent"><span style="font-size: 13px; font-weight: 500">Implement</span><span class="hint">no runs yet</span></label>
<label class="opt" style="border-color: #2e3034; background: transparent"><span style="font-size: 13px; font-weight: 500">Remediate</span><span class="hint">no runs yet</span></label>
<label class="opt" style="border-color: #2e3034; background: transparent"><span style="font-size: 13px; font-weight: 500">Feasibility check</span><span class="hint">no runs yet</span></label>
<label class="opt" style="border-color: #2e3034; background: transparent"><span style="font-size: 13px; font-weight: 500">Bootstrap</span><span class="hint">no runs yet</span></label>
</div></div>
<div class="field"><label class="lbl" for="ttl">Title</label><input id="ttl" class="inp" placeholder="What should Archie do?" style="font-family: 'IBM Plex Sans', sans-serif"></div>
<div class="field"><label class="lbl" for="ins">Instructions</label><textarea id="ins" placeholder="Context, acceptance criteria, files to look at…" style="min-height: 120px; box-sizing: border-box; padding: 12px; background: #121314; border: 1px solid #2e3034; border-radius: 6px; color: #e8e6e1; font: 13px/1.6 'IBM Plex Sans', sans-serif; resize: vertical; outline: none"></textarea></div>
<details style="font-size: 13px; color: #a6a39b"><summary style="cursor: pointer">Advanced · run as identity</summary></details>
</div>
<div style="display: flex; align-items: center; gap: 10px; padding: 14px 24px; border-top: 1px solid #232529">
<span class="hint"><span class="mono" style="padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘↵</span> to start</span>
<div style="flex-grow: 1"></div>
<button class="btn btn-ghost">Cancel</button>
<button class="btn btn-primary">Start task</button>
</div>
</section>
</div>
</body>
</html>
@@ -1,102 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Events</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
.card-h{display:flex;align-items:center;gap:12px;padding:16px 20px;border-bottom:1px solid #232529}
.card-t{font-size:15px;font-weight:500}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.nav a.on{color:#e8e6e1;background:#1e2023}
.tab{height:44px;display:flex;align-items:center;gap:8px;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
.count{font:11px 'IBM Plex Mono',monospace;color:#8f8c85;background:#1e2023;border-radius:4px;padding:0 6px}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 900px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#" class="on">Events</a><a href="#">Settings</a></nav>
<div style="flex-grow: 1"></div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
</header>
<main style="flex-grow: 1; padding: 32px 48px; display: flex; flex-direction: column; gap: 24px">
<div>
<div style="display: flex; align-items: flex-end; gap: 12px">
<div style="flex-grow: 1"><h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Events</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Webhooks come in, get mapped to event types, and bindings turn them into work.</p></div>
<span class="pill" style="color: #86b5a0; border-color: #86b5a0"><span class="dot" style="background: #86b5a0"></span>Listening</span>
</div>
<nav style="display: flex; gap: 28px; margin-top: 16px; border-bottom: 1px solid #232529">
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: #86b5a0">Inspector</a>
<a class="tab" href="#">Mappings <span class="count">0</span></a>
<a class="tab" href="#">Bindings <span class="count">0</span></a>
</nav>
</div>
<section class="card" style="flex-direction: row">
<div style="flex: 1 1 0; display: flex; align-items: center; gap: 14px; padding: 18px 22px; border-right: 1px solid #232529">
<span class="mono" style="width: 28px; height: 28px; border-radius: 50%; border: 1px solid #34373c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b; flex-shrink: 0">1</span>
<div style="flex-grow: 1"><div style="font-size: 14px; font-weight: 500">Capture</div><div class="hint">Webhooks received</div></div>
<span class="mono" style="font-size: 20px; color: #8f8c85">0</span>
</div>
<div style="flex: 1 1 0; display: flex; align-items: center; gap: 14px; padding: 18px 22px; border-right: 1px solid #232529">
<span class="mono" style="width: 28px; height: 28px; border-radius: 50%; border: 1px solid #34373c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b; flex-shrink: 0">2</span>
<div style="flex-grow: 1"><div style="font-size: 14px; font-weight: 500">Map</div><div class="hint">Payloads → event types</div></div>
<span class="mono" style="font-size: 20px; color: #8f8c85">0</span>
</div>
<div style="flex: 1 1 0; display: flex; align-items: center; gap: 14px; padding: 18px 22px; border-right: 1px solid #232529">
<span class="mono" style="width: 28px; height: 28px; border-radius: 50%; border: 1px solid #34373c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b; flex-shrink: 0">3</span>
<div style="flex-grow: 1"><div style="font-size: 14px; font-weight: 500">Bind</div><div class="hint">Event types → work</div></div>
<span class="mono" style="font-size: 20px; color: #8f8c85">0</span>
</div>
</section>
<div style="display: grid; grid-template-columns: minmax(0, 3fr) minmax(0, 2fr); gap: 24px">
<section class="card">
<div class="card-h"><div style="flex-grow: 1"><div class="card-t">Recent captures</div><div class="hint">Headers and payloads are redacted before they’re stored.</div></div></div>
<div style="padding: 40px 32px; display: flex; flex-direction: column; align-items: center; gap: 12px; text-align: center">
<div style="width: 40px; height: 40px; border-radius: 10px; background: #1e2023; display: flex; align-items: center; justify-content: center"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><path d="M22 12h-6l-2 3h-4l-2-3H2"></path><path d="M5.5 5h13L22 12v6a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2v-6Z"></path></svg></div>
<div style="font-size: 14px; font-weight: 500">No captures yet</div>
<div class="hint">Point a webhook at this endpoint and it shows up here live.</div>
<div style="display: flex; align-items: center; gap: 8px; margin-top: 6px; padding: 4px 4px 4px 14px; border: 1px solid #2e3034; border-radius: 8px; background: #121314">
<span class="mono" style="font-size: 13px">/webhooks/capture/<span style="color: #86b5a0">&lt;source&gt;</span></span>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="8" y="8" width="12" height="12" rx="2"></rect><path d="M16 8V5a1 1 0 0 0-1-1H5a1 1 0 0 0-1 1v10a1 1 0 0 0 1 1h3"></path></svg>Copy</button>
</div>
</div>
</section>
<section class="card">
<div class="card-h"><div style="flex-grow: 1"><div class="card-t">Event types</div><div class="hint">Named shapes that mappings produce.</div></div>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M14 3H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9l-6-6Z"></path><path d="M12 12v6M9 15h6"></path></svg>From payload</button></div>
<div style="padding: 40px 32px; display: flex; flex-direction: column; align-items: center; gap: 8px; text-align: center">
<div style="font-size: 14px; font-weight: 500">No event types or proposals</div>
<div class="hint">Paste a sample payload and Archie proposes a type for it. Proposals from real captures appear here too.</div>
</div>
</section>
</div>
</main>
</div>
</body>
</html>
@@ -1,176 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Settings – sidebar layout</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none}
.inp:focus{border-color:var(--accent)}
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.icon-btn{width:36px;height:36px;display:flex;align-items:center;justify-content:center;border-radius:6px;border:1px solid transparent;background:transparent;color:#8f8c85;cursor:pointer}
.icon-btn:hover{background:#1e2023;color:#e8e6e1}
.nav-item{display:flex;align-items:center;gap:10px;height:36px;padding:0 12px;border-radius:6px;color:#a6a39b;font-size:13px}
.row{display:grid;grid-template-columns:280px minmax(0,1fr);gap:32px;padding:20px 0;border-top:1px solid #232529}
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
.hint{font-size:12px;color:#8f8c85;margin-top:4px;line-height:1.5}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 1040px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; position: relative; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
Archie
</div>
<nav style="display: flex; gap: 4px; font-size: 13px">
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Tasks</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Workflows</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">Settings</a>
</nav>
<div style="flex-grow: 1"></div>
<div style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b; padding: 6px 10px; border: 1px solid #2a2c30; border-radius: 999px">
<span style="width: 7px; height: 7px; border-radius: 50%; background: #d9a45b"></span>
Connecting to archie-core…
</div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 240px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px">
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg>
<input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%">
<span style="font-family: 'IBM Plex Mono', monospace; font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span>
</label>
</header>
<div style="display: flex; flex-grow: 1; min-height: 0">
<aside style="width: 264px; flex-shrink: 0; box-sizing: border-box; padding: 24px 16px; border-right: 1px solid #232529; display: flex; flex-direction: column; gap: 2px">
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 0 12px 8px">Agents</div>
<a class="nav-item" href="#">Personas<span style="margin-left: auto; font-family: 'IBM Plex Mono', monospace; font-size: 11px; color: #8f8c85">6</span></a>
<a class="nav-item" href="#">Schedules<span style="margin-left: auto; font-family: 'IBM Plex Mono', monospace; font-size: 11px; color: #8f8c85">0</span></a>
<a class="nav-item" href="#" style="background: #1e2023; color: #e8e6e1; box-shadow: inset 2px 0 0 #86b5a0">Scheduling policy<span style="margin-left: auto; width: 6px; height: 6px; border-radius: 50%; background: #86b5a0" title="Unsaved changes"></span></a>
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Integrations</div>
<a class="nav-item" href="#">Channels</a>
<a class="nav-item" href="#">Tools &amp; MCP</a>
<a class="nav-item" href="#">Plugins</a>
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Runtime</div>
<a class="nav-item" href="#">Container runtime</a>
<div style="height: 1px; background: #232529; margin: 16px 12px"></div>
<a class="nav-item" href="#">History</a>
<div style="flex-grow: 1"></div>
<div style="font-size: 12px; color: #8f8c85; padding: 12px; line-height: 1.5; border: 1px solid #232529; border-radius: 8px">Config version 1 · last saved by <span style="color: #a6a39b">admin</span><br><a href="#" style="color: #86b5a0">View history</a></div>
</aside>
<main style="flex-grow: 1; overflow: hidden; padding: 40px 56px 120px">
<div style="max-width: 920px">
<div style="display: flex; align-items: flex-start; gap: 16px">
<div style="flex-grow: 1">
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Scheduling policy</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">How Archie picks up work items and labels them as they move through states.</p>
</div>
<span style="display: inline-flex; align-items: center; gap: 6px; font-size: 12px; color: #d9a45b; background: rgba(217,164,91,0.1); border: 1px solid rgba(217,164,91,0.25); padding: 4px 10px; border-radius: 999px">
<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a9 9 0 1 1-3-6.7L21 8"></path><path d="M21 3v5h-5"></path></svg>
Applies after restart</span>
</div>
<h2 style="margin: 36px 0 4px; font-size: 13px; font-weight: 600; color: #a6a39b; text-transform: uppercase; letter-spacing: 0.06em">Dispatch</h2>
<div class="row">
<div><div class="lbl">Trigger</div><div class="hint">What causes a work item to be dispatched to an agent.</div></div>
<div style="display: flex; flex-direction: column; gap: 12px">
<div role="radiogroup" aria-label="Trigger" style="display: inline-flex; align-self: flex-start; padding: 3px; background: #121314; border: 1px solid #2e3034; border-radius: 8px">
<button style="height: 30px; padding: 0 14px; border: 0; border-radius: 5px; background: #26282c; color: #e8e6e1; font: 500 13px 'IBM Plex Sans', sans-serif">Assignee</button>
<button style="height: 30px; padding: 0 14px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 13px 'IBM Plex Sans', sans-serif">Label</button>
</div>
<div class="hint" style="margin: 0">Dispatches when Archie is assigned. Choose <span style="color: #a6a39b">Label</span> to set a trigger label instead.</div>
</div>
</div>
<div class="row">
<div><label class="lbl" for="ack">Ack reaction</label><div class="hint">Reaction posted when a work item is picked up.</div></div>
<div><input id="ack" class="inp" value="eyes" style="width: 220px"></div>
</div>
<h2 style="margin: 36px 0 4px; font-size: 13px; font-weight: 600; color: #a6a39b; text-transform: uppercase; letter-spacing: 0.06em">State labels</h2>
<div class="row">
<div><div class="lbl">Labels by state</div><div class="hint">Label applied to the ticket as the agent moves between states.</div></div>
<div style="border: 1px solid #2a2c30; border-radius: 8px; overflow: hidden">
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; padding: 8px 12px; font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: #8f8c85; background: #17181a; border-bottom: 1px solid #2a2c30"><span>State</span><span>Label</span><span></span></div>
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #8f8c85"></span>queued</span>
<input class="inp" aria-label="queued label" value="agent:queued" style="width: 100%; height: 32px">
<button class="icon-btn" aria-label="Remove queued"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
</div>
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #8aa4c2"></span>working</span>
<input class="inp" aria-label="working label" value="agent:working" style="width: 100%; height: 32px">
<button class="icon-btn" aria-label="Remove working"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
</div>
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #d9a45b"></span>waiting</span>
<input class="inp" aria-label="waiting label" value="agent:waiting" style="width: 100%; height: 32px">
<button class="icon-btn" aria-label="Remove waiting"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
</div>
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #86b5a0"></span>pr</span>
<input class="inp" aria-label="pr label" value="agent:pr" style="width: 100%; height: 32px">
<button class="icon-btn" aria-label="Remove pr"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
</div>
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #6f6c66"></span>parked</span>
<input class="inp" aria-label="parked label" value="agent:parked" style="width: 100%; height: 32px">
<button class="icon-btn" aria-label="Remove parked"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
</div>
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #d9776b"></span>dead</span>
<input class="inp" aria-label="dead label" value="agent:dead" style="width: 100%; height: 32px">
<button class="icon-btn" aria-label="Remove dead"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
</div>
<button style="display: flex; align-items: center; gap: 6px; width: 100%; height: 38px; padding: 0 12px; border: 0; background: transparent; color: #a6a39b; font: 500 13px 'IBM Plex Sans', sans-serif; cursor: pointer"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>Add state</button>
</div>
</div>
<h2 style="margin: 36px 0 4px; font-size: 13px; font-weight: 600; color: #a6a39b; text-transform: uppercase; letter-spacing: 0.06em">Retries &amp; polling</h2>
<div class="row">
<div><label class="lbl" for="retries">Max retries</label><div class="hint">Attempts before an item is labelled dead.</div></div>
<div style="display: inline-flex; align-self: flex-start; border: 1px solid #2e3034; border-radius: 6px; overflow: hidden; width: fit-content">
<button class="icon-btn" aria-label="Decrease" style="border-radius: 0">−</button>
<input id="retries" class="inp" value="3" style="width: 56px; border: 0; border-radius: 0; text-align: center; border-left: 1px solid #2e3034; border-right: 1px solid #2e3034">
<button class="icon-btn" aria-label="Increase" style="border-radius: 0">+</button>
</div>
</div>
<div class="row">
<div><label class="lbl" for="poll">Poll interval</label><div class="hint">How often the tracker is checked for new work.</div></div>
<div style="display: flex; align-items: center; gap: 10px">
<div style="display: flex">
<input id="poll" class="inp" value="30" style="width: 80px; border-radius: 6px 0 0 6px; border-color: #86b5a0">
<select aria-label="Poll unit" class="inp" style="border-radius: 0 6px 6px 0; border-left: 0; font-family: 'IBM Plex Sans', sans-serif"><option>seconds</option><option>minutes</option></select>
</div>
<span style="font-size: 12px; color: #8f8c85">was <span style="font-family: 'IBM Plex Mono', monospace; text-decoration: line-through">1m0s</span></span>
</div>
</div>
</div>
</main>
</div>
<div style="position: absolute; left: 264px; right: 0; bottom: 0; height: 72px; box-sizing: border-box; padding: 0 56px; display: flex; align-items: center; gap: 12px; background: #17181a; border-top: 1px solid #2a2c30">
<span style="width: 8px; height: 8px; border-radius: 50%; background: #86b5a0"></span>
<span style="font-size: 13px">1 unsaved change</span>
<span style="font-size: 13px; color: #8f8c85">· Poll interval</span>
<div style="flex-grow: 1"></div>
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard</button>
<button class="btn btn-primary">Save &amp; restart</button>
</div>
</div>
</body>
</html>
@@ -1,154 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Settings – personas</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none}
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.tab{height:44px;display:flex;align-items:center;padding:0 2px;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 1040px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
Archie
</div>
<nav style="display: flex; gap: 4px; font-size: 13px">
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Work</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">System</a>
</nav>
<div style="flex-grow: 1"></div>
<div style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b; padding: 6px 10px; border: 1px solid #2a2c30; border-radius: 999px">
<span style="width: 7px; height: 7px; border-radius: 50%; background: #86b5a0"></span>
Connected · v1
</div>
</header>
<div style="padding: 32px 48px 0; border-bottom: 1px solid #232529; flex-shrink: 0">
<div style="font-size: 12px; color: #8f8c85">System / Advanced</div>
<h1 style="margin: 6px 0 20px; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Advanced settings</h1>
<nav style="display: flex; gap: 28px">
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: #86b5a0">Personas</a>
<a class="tab" href="#">Schedules</a>
<a class="tab" href="#">Scheduling policy</a>
<a class="tab" href="#">Tools &amp; MCP</a>
<a class="tab" href="#">Plugins</a>
<a class="tab" href="#">Container runtime</a>
</nav>
</div>
<div style="display: flex; flex-grow: 1; min-height: 0; padding: 32px 48px 40px; gap: 32px">
<section aria-label="Persona list" style="width: 340px; flex-shrink: 0; display: flex; flex-direction: column; gap: 12px">
<div style="display: flex; align-items: center; gap: 8px">
<label style="flex-grow: 1; display: flex; align-items: center; gap: 8px; height: 36px; padding: 0 12px; border: 1px solid #2e3034; border-radius: 6px; color: #8f8c85">
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg>
<input aria-label="Filter personas" placeholder="Filter personas" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: 13px 'IBM Plex Sans', sans-serif; width: 100%">
</label>
<button class="btn" aria-label="New persona" style="padding: 0 12px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New</button>
</div>
<div style="border: 1px solid #2a2c30; border-radius: 10px; overflow: hidden; background: #16171a">
<a href="#" style="display: flex; flex-direction: column; gap: 4px; padding: 14px 16px; border-bottom: 1px solid #222428; background: #1e2023; box-shadow: inset 2px 0 0 #86b5a0">
<span style="display: flex; align-items: center; gap: 8px; font-size: 14px; font-weight: 500">archie
<span style="font-size: 11px; font-weight: 500; color: #86b5a0; border: 1px solid #86b5a0; border-radius: 999px; padding: 1px 8px">default</span>
</span>
<span style="font-size: 12px; color: #8f8c85; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">You are Archie, a capable coding and project assistant. Be direct without being brusque…</span>
</a>
<a href="#" style="display: flex; flex-direction: column; gap: 4px; padding: 14px 16px; border-bottom: 1px solid #222428; background: transparent; box-shadow: none">
<span style="display: flex; align-items: center; gap: 8px; font-size: 14px; font-weight: 500">helpful
</span>
<span style="font-size: 12px; color: #8f8c85; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">You are a helpful, friendly AI assistant.</span>
</a>
<a href="#" style="display: flex; flex-direction: column; gap: 4px; padding: 14px 16px; border-bottom: 1px solid #222428; background: transparent; box-shadow: none">
<span style="display: flex; align-items: center; gap: 8px; font-size: 14px; font-weight: 500">concise
</span>
<span style="font-size: 12px; color: #8f8c85; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">You are a concise assistant. Keep responses brief and to the point.</span>
</a>
<a href="#" style="display: flex; flex-direction: column; gap: 4px; padding: 14px 16px; border-bottom: 1px solid #222428; background: transparent; box-shadow: none">
<span style="display: flex; align-items: center; gap: 8px; font-size: 14px; font-weight: 500">technical
</span>
<span style="font-size: 12px; color: #8f8c85; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">You are a technical expert. Provide detailed, accurate technical information.</span>
</a>
<a href="#" style="display: flex; flex-direction: column; gap: 4px; padding: 14px 16px; border-bottom: 1px solid #222428; background: transparent; box-shadow: none">
<span style="display: flex; align-items: center; gap: 8px; font-size: 14px; font-weight: 500">creative
</span>
<span style="font-size: 12px; color: #8f8c85; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">You are a creative assistant. Think outside the box and offer innovative solutions.</span>
</a>
<a href="#" style="display: flex; flex-direction: column; gap: 4px; padding: 14px 16px; border-bottom: 1px solid #222428; background: transparent; box-shadow: none">
<span style="display: flex; align-items: center; gap: 8px; font-size: 14px; font-weight: 500">teacher
</span>
<span style="font-size: 12px; color: #8f8c85; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">You are a patient teacher. Explain concepts clearly with examples.</span>
</a>
</div>
<div class="hint">Personas are system prompts an agent can adopt. The default is used when a work item doesn't specify one.</div>
</section>
<section aria-label="Edit persona" style="flex-grow: 1; display: flex; flex-direction: column; border: 1px solid #2a2c30; border-radius: 10px; background: #16171a; overflow: hidden">
<div style="display: flex; align-items: center; gap: 12px; padding: 18px 24px; border-bottom: 1px solid #2a2c30">
<h2 style="margin: 0; font-size: 18px; font-weight: 600">archie</h2>
<span style="font-size: 11px; color: #86b5a0; border: 1px solid #86b5a0; border-radius: 999px; padding: 1px 8px">default</span>
<div style="flex-grow: 1"></div>
<button class="btn" style="background: transparent">Duplicate</button>
<button class="btn" style="background: transparent; color: #d9776b; border-color: #3a2a28">Delete</button>
</div>
<div style="display: flex; flex-direction: column; gap: 24px; padding: 24px; flex-grow: 1">
<div style="display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 24px">
<div style="display: flex; flex-direction: column; gap: 8px">
<label class="lbl" for="pname">Name</label>
<input id="pname" class="inp" value="archie">
<span class="hint">Lowercase, used as the persona key.</span>
</div>
<div style="display: flex; flex-direction: column; gap: 8px">
<span class="lbl">Default persona</span>
<label style="display: flex; align-items: center; gap: 10px; height: 36px; font-size: 13px; color: #a6a39b">
<span style="width: 36px; height: 20px; border-radius: 999px; background: #86b5a0; position: relative; display: inline-block"><span style="position: absolute; right: 2px; top: 2px; width: 16px; height: 16px; border-radius: 50%; background: #121314"></span></span>
Use when no persona is specified
</label>
</div>
</div>
<div style="display: flex; flex-direction: column; gap: 8px; flex-grow: 1">
<div style="display: flex; align-items: baseline"><label class="lbl" for="prompt">System prompt</label><span class="hint" style="margin-left: auto; font-family: 'IBM Plex Mono', monospace">312 chars · ~70 tokens</span></div>
<textarea id="prompt" style="flex-grow: 1; min-height: 320px; box-sizing: border-box; padding: 16px; background: #121314; border: 1px solid #2e3034; border-radius: 8px; color: #e8e6e1; font: 400 13px/1.7 'IBM Plex Mono', monospace; resize: vertical; outline: none">You are Archie, a capable coding and project assistant. Be direct without being brusque, grounded in the actual workspace state, and use available tools when asked. Do not claim tools, files, memories, actions, or results you have not verified. Do not impersonate another assistant, provider, or vendor.</textarea>
</div>
<div style="display: flex; align-items: center; gap: 12px; padding: 14px 16px; border: 1px dashed #2e3034; border-radius: 8px">
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><path d="M4 12h12M12 6l6 6-6 6"></path></svg>
<span style="font-size: 13px; color: #a6a39b; flex-grow: 1">Try this persona against a sample message before saving</span>
<button class="btn">Open preview</button>
</div>
</div>
<div style="display: flex; align-items: center; gap: 12px; padding: 16px 24px; border-top: 1px solid #2a2c30; background: #17181a">
<span style="font-size: 12px; color: #8f8c85">Saved · version 1 · <a href="#" style="color: #a6a39b; text-decoration: underline">History</a></span>
<div style="flex-grow: 1"></div>
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard</button>
<button class="btn btn-primary">Save persona</button>
</div>
</section>
</div>
</div>
</body>
</html>
@@ -1,144 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Settings – tools and MCP</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column}
.card-h{display:flex;align-items:center;gap:12px;padding:18px 20px;border-bottom:1px solid #232529}
.card-b{padding:20px;display:flex;flex-direction:column;gap:18px}
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.field{display:flex;flex-direction:column;gap:6px}
.sw{width:36px;height:20px;border-radius:999px;position:relative;display:inline-block;flex-shrink:0}
.sw i{position:absolute;top:2px;width:16px;height:16px;border-radius:50%}
.nav-item{display:flex;align-items:center;gap:10px;height:36px;padding:0 12px;border-radius:6px;color:#a6a39b;font-size:13px}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
Archie
</div>
<nav style="display: flex; gap: 4px; font-size: 13px">
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Tasks</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Workflows</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">Settings</a>
</nav>
<div style="flex-grow: 1"></div>
<div style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b; padding: 6px 10px; border: 1px solid #2a2c30; border-radius: 999px">
<span style="width: 7px; height: 7px; border-radius: 50%; background: #86b5a0"></span>
Connected · v1
</div>
</header>
<div style="display: flex; flex-grow: 1; min-height: 0">
<aside style="width: 232px; flex-shrink: 0; box-sizing: border-box; padding: 24px 12px; border-right: 1px solid #232529; display: flex; flex-direction: column; gap: 2px">
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 0 12px 8px">Agents</div>
<a class="nav-item" href="#">Personas</a>
<a class="nav-item" href="#">Schedules</a>
<a class="nav-item" href="#">Scheduling policy</a>
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Integrations</div>
<a class="nav-item" href="#">Channels</a>
<a class="nav-item" href="#" style="background: #1e2023; color: #e8e6e1; box-shadow: inset 2px 0 0 #86b5a0">Tools &amp; MCP</a>
<a class="nav-item" href="#">Plugins</a>
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Runtime</div>
<a class="nav-item" href="#">Container runtime</a>
<div style="height: 1px; background: #232529; margin: 16px 12px"></div>
<a class="nav-item" href="#">History</a>
</aside>
<main style="flex-grow: 1; padding: 36px 48px; overflow: hidden">
<div style="display: flex; align-items: flex-end; gap: 16px; margin-bottom: 28px">
<div style="flex-grow: 1">
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Tools &amp; MCP</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">External tools, model providers and fetch limits available to agents.</p>
</div>
<button class="btn btn-primary"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>Add MCP server</button>
</div>
<div style="display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 20px">
<section class="card" style="grid-column: span 2">
<div class="card-h">
<div style="width: 32px; height: 32px; border-radius: 8px; background: #1e2023; display: flex; align-items: center; justify-content: center"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><rect x="3" y="4" width="18" height="6" rx="1"></rect><rect x="3" y="14" width="18" height="6" rx="1"></rect><path d="M7 7h.01M7 17h.01"></path></svg></div>
<div style="flex-grow: 1"><div class="lbl" style="font-size: 15px">MCP servers</div><div class="hint">Model Context Protocol servers agents can call.</div></div>
</div>
<div style="display: flex; align-items: center; gap: 20px; padding: 28px 20px">
<div style="flex-grow: 1">
<div style="font-size: 14px; color: #e8e6e1">No MCP servers yet</div>
<div class="hint" style="margin-top: 4px">Add a stdio command or an HTTP endpoint. Agents see its tools on next restart.</div>
</div>
<button class="btn">stdio command</button>
<button class="btn">HTTP / SSE endpoint</button>
</div>
</section>
<section class="card">
<div class="card-h">
<div style="width: 32px; height: 32px; border-radius: 8px; background: #1e2023; display: flex; align-items: center; justify-content: center; font: 600 13px 'IBM Plex Mono', monospace; color: #a6a39b">Mx</div>
<div style="flex-grow: 1"><div class="lbl" style="font-size: 15px">MiniMax</div><div class="hint">Model provider</div></div>
<label style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b">Enabled<span class="sw" style="background: #86b5a0"><i style="right: 2px; background: #121314"></i></span></label>
</div>
<div class="card-b">
<div class="field">
<span class="lbl">API key</span>
<div style="display: flex; align-items: center; gap: 10px; height: 40px; padding: 0 12px; border: 1px solid #2e3034; border-radius: 6px; background: #121314">
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><rect x="4" y="10" width="16" height="10" rx="2"></rect><path d="M8 10V7a4 4 0 0 1 8 0v3"></path></svg>
<span style="font: 12px 'IBM Plex Mono', monospace; color: #8f8c85">bws</span>
<span style="color: #4a4c50">/</span>
<span style="font: 13px 'IBM Plex Mono', monospace">MINIMAX_API_KEY</span>
<div style="flex-grow: 1"></div>
<button class="btn" style="height: 28px; padding: 0 10px; font-size: 12px; background: transparent">Change</button>
</div>
<div style="display: flex; align-items: center; gap: 6px; font-size: 12px; color: #86b5a0"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2"><path d="m5 12 5 5 9-10"></path></svg>Credential resolved by Archie</div>
</div>
</div>
</section>
<section class="card">
<div class="card-h">
<div style="width: 32px; height: 32px; border-radius: 8px; background: #1e2023; display: flex; align-items: center; justify-content: center"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><circle cx="12" cy="12" r="9"></circle><path d="M3 12h18M12 3c3 3 3 15 0 18M12 3c-3 3-3 15 0 18"></path></svg></div>
<div style="flex-grow: 1"><div class="lbl" style="font-size: 15px">Web fetch</div><div class="hint">Let agents download pages and files</div></div>
<label style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b">Enabled<span class="sw" style="background: #86b5a0"><i style="right: 2px; background: #121314"></i></span></label>
</div>
<div class="card-b">
<div style="display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 16px">
<div class="field"><label class="lbl" for="mb">Max download</label><div style="display: flex"><input id="mb" class="inp" value="2" style="border-radius: 6px 0 0 6px"><span style="display: flex; align-items: center; padding: 0 12px; border: 1px solid #2e3034; border-left: 0; border-radius: 0 6px 6px 0; font-size: 12px; color: #8f8c85">MB</span></div></div>
<div class="field"><label class="lbl" for="to">Timeout</label><div style="display: flex"><input id="to" class="inp" value="30" style="border-radius: 6px 0 0 6px"><span style="display: flex; align-items: center; padding: 0 12px; border: 1px solid #2e3034; border-left: 0; border-radius: 0 6px 6px 0; font-size: 12px; color: #8f8c85">sec</span></div></div>
</div>
<label style="display: flex; align-items: flex-start; gap: 12px; padding: 12px; border: 1px solid #2a2c30; border-radius: 8px">
<span class="sw" style="background: #2e3034; margin-top: 2px"><i style="left: 2px; background: #8f8c85"></i></span>
<span><span class="lbl">Allow private networks</span><span class="hint" style="display: block">Off: requests to 10.x, 192.168.x and localhost are blocked.</span></span>
</label>
</div>
</section>
<section class="card" style="grid-column: span 2">
<div class="card-h">
<div style="flex-grow: 1"><div class="lbl" style="font-size: 15px">Tool output policy</div><div class="hint">Large tool results are truncated or spilled to disk.</div></div>
</div>
<div class="card-b" style="display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 24px">
<div class="field"><label class="lbl" for="mrc">Max result length</label><div style="display: flex"><input id="mrc" class="inp" value="50,000" style="border-radius: 6px 0 0 6px"><span style="display: flex; align-items: center; padding: 0 12px; border: 1px solid #2e3034; border-left: 0; border-radius: 0 6px 6px 0; font-size: 12px; color: #8f8c85; white-space: nowrap">chars</span></div><span class="hint">About 12k tokens per tool call.</span></div>
<div class="field"><label class="lbl" for="spill">Spill directory</label><input id="spill" class="inp" placeholder="Not set — results over the limit are truncated"><span class="hint">Full output is written here and the agent gets a path.</span></div>
</div>
</section>
</div>
</main>
</div>
</div>
</body>
</html>
@@ -1,124 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Settings – review changes</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.acc{display:flex;align-items:center;gap:14px;padding:16px 20px;border:1px solid #2a2c30;border-radius:10px;background:#16171a}
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.sum{font:12px 'IBM Plex Mono',monospace;color:#8f8c85}
.field{display:flex;flex-direction:column;gap:6px}
.chev{color:#8f8c85}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden; position: relative">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
Archie
</div>
<nav style="display: flex; gap: 4px; font-size: 13px">
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Work</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">System</a>
</nav>
</header>
<main style="width: 880px; padding: 36px 0 0 64px; display: flex; flex-direction: column; gap: 12px">
<h1 style="margin: 0 0 4px; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Advanced settings</h1>
<p style="margin: 0 0 16px; font-size: 14px; color: #a6a39b">Collapsed sections show their current values at a glance.</p>
<div class="acc"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Personas</span><span class="sum" style="flex-grow: 1">6 personas · default archie</span></div>
<div class="acc"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Schedules</span><span class="sum" style="flex-grow: 1">none</span></div>
<div class="acc" style="border-color: #3a3f3c"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Scheduling policy</span><span class="sum" style="flex-grow: 1">trigger assignee · 3 retries · poll 30s</span><span style="font-size: 11px; color: #86b5a0">1 edited</span></div>
<div class="acc"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Tools &amp; MCP</span><span class="sum" style="flex-grow: 1">0 MCP · MiniMax on · web fetch on</span></div>
<div class="acc"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Plugins</span><span class="sum" style="flex-grow: 1">all directories default</span></div>
<section style="border: 1px solid #3a3f3c; border-radius: 10px; background: #16171a">
<div style="display: flex; align-items: center; gap: 14px; padding: 16px 20px; border-bottom: 1px solid #232529">
<svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 9 6 6 6-6"></path></svg>
<span class="lbl" style="flex-grow: 1">Container runtime</span>
<span style="font-size: 11px; color: #86b5a0">2 edited</span>
</div>
<div style="padding: 20px; display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 18px 24px">
<div class="field" style="grid-column: span 2"><label class="lbl" for="img">Image</label><input id="img" class="inp" value="ghcr.io/samcharles93/archie-agent:latest"></div>
<div class="field"><label class="lbl" for="mc">Max concurrency</label><input id="mc" class="inp" value="6" style="border-color: #86b5a0"></div>
<div class="field"><label class="lbl" for="mu">Max uptime</label><input id="mu" class="inp" value="2h" style="border-color: #86b5a0"></div>
<div class="field"><label class="lbl" for="net">Network</label><input id="net" class="inp" value="archie-core_default"></div>
<div class="field"><label class="lbl" for="pp">Pull policy</label><select id="pp" class="inp" style="font-family: 'IBM Plex Sans', sans-serif"><option>If missing</option><option>Always</option><option>Never</option></select></div>
<div class="field"><label class="lbl" for="vt">Volume TTL</label><input id="vt" class="inp" value="72h"></div>
<div class="field"><label class="lbl" for="pr">Profiles</label><input id="pr" class="inp" placeholder="None"></div>
</div>
</section>
</main>
<div style="position: absolute; left: 0; top: 56px; right: 0; bottom: 0; background: rgba(8,9,10,0.55)"></div>
<aside aria-label="Review changes" style="position: absolute; top: 56px; right: 0; bottom: 0; width: 480px; box-sizing: border-box; background: #17181a; border-left: 1px solid #2a2c30; display: flex; flex-direction: column; box-shadow: -24px 0 48px rgba(0,0,0,0.35)">
<div style="display: flex; align-items: center; padding: 20px 24px; border-bottom: 1px solid #2a2c30">
<div style="flex-grow: 1"><h2 style="margin: 0; font-size: 17px; font-weight: 600">Review 3 changes</h2><div class="hint" style="margin-top: 2px">Saved together as config version 2</div></div>
<button aria-label="Close" style="width: 36px; height: 36px; border: 0; background: transparent; color: #8f8c85; cursor: pointer"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 6l12 12M18 6 6 18"></path></svg></button>
</div>
<div style="flex-grow: 1; padding: 20px 24px; display: flex; flex-direction: column; gap: 20px">
<div style="display: flex; gap: 10px; padding: 12px 14px; border-radius: 8px; background: rgba(217,164,91,0.08); border: 1px solid rgba(217,164,91,0.25); color: #e3c08f; font-size: 13px; line-height: 1.5">
<svg style="flex-shrink: 0; margin-top: 2px" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a9 9 0 1 1-3-6.7L21 8"></path><path d="M21 3v5h-5"></path></svg>
<span>All three need an archie-core restart. 2 agents are running; they'll finish before the restart.</span>
</div>
<div style="display: flex; flex-direction: column; gap: 8px">
<div style="font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: #8f8c85">Scheduling policy</div>
<div style="border: 1px solid #2a2c30; border-radius: 8px; overflow: hidden">
<div style="display: flex; align-items: center; padding: 10px 14px; font-size: 13px; font-weight: 500"><span style="flex-grow: 1">Poll interval</span><a href="#" style="font-size: 12px; font-weight: 400; color: #8f8c85; text-decoration: underline">Revert</a></div>
<div style="font: 12px/1.9 'IBM Plex Mono', monospace; border-top: 1px solid #232529">
<div style="padding: 0 14px; background: rgba(217,119,107,0.08); color: #e0a39a">− 1m0s</div>
<div style="padding: 0 14px; background: rgba(134,181,160,0.10); color: #a9d1bf">+ 30s</div>
</div>
</div>
</div>
<div style="display: flex; flex-direction: column; gap: 8px">
<div style="font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: #8f8c85">Container runtime</div>
<div style="border: 1px solid #2a2c30; border-radius: 8px; overflow: hidden">
<div style="display: flex; align-items: center; padding: 10px 14px; font-size: 13px; font-weight: 500"><span style="flex-grow: 1">Max concurrency</span><a href="#" style="font-size: 12px; font-weight: 400; color: #8f8c85; text-decoration: underline">Revert</a></div>
<div style="font: 12px/1.9 'IBM Plex Mono', monospace; border-top: 1px solid #232529">
<div style="padding: 0 14px; background: rgba(217,119,107,0.08); color: #e0a39a">− 4</div>
<div style="padding: 0 14px; background: rgba(134,181,160,0.10); color: #a9d1bf">+ 6</div>
</div>
</div>
<div style="border: 1px solid #2a2c30; border-radius: 8px; overflow: hidden">
<div style="display: flex; align-items: center; padding: 10px 14px; font-size: 13px; font-weight: 500"><span style="flex-grow: 1">Max uptime</span><a href="#" style="font-size: 12px; font-weight: 400; color: #8f8c85; text-decoration: underline">Revert</a></div>
<div style="font: 12px/1.9 'IBM Plex Mono', monospace; border-top: 1px solid #232529">
<div style="padding: 0 14px; background: rgba(217,119,107,0.08); color: #e0a39a">− 1h0m0s</div>
<div style="padding: 0 14px; background: rgba(134,181,160,0.10); color: #a9d1bf">+ 2h0m0s</div>
</div>
</div>
</div>
</div>
<div style="display: flex; align-items: center; gap: 12px; padding: 16px 24px; border-top: 1px solid #2a2c30">
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard all</button>
<div style="flex-grow: 1"></div>
<button class="btn">Save only</button>
<button class="btn btn-primary">Save &amp; restart</button>
</div>
</aside>
</div>
</body>
</html>
@@ -1,155 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Settings – channels</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
.card-h{display:flex;align-items:center;gap:12px;padding:16px 20px;border-bottom:1px solid #232529}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.lbl{font-size:13px;font-weight:500}
.eyebrow{font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:#8f8c85;font-weight:500}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.nav a.on{color:#e8e6e1;background:#1e2023}
.nav-item{display:flex;align-items:center;gap:10px;height:34px;padding:0 12px;border-radius:6px;color:#a6a39b;font-size:13px}
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
.row{display:grid;grid-template-columns:260px minmax(0,1fr);gap:32px;padding:16px 20px;border-top:1px solid #232529}
.sw{width:36px;height:20px;border-radius:999px;position:relative;display:inline-block;flex-shrink:0}
.sw i{position:absolute;top:2px;width:16px;height:16px;border-radius:50%}
.icon{width:32px;height:32px;border-radius:8px;background:#1e2023;display:flex;align-items:center;justify-content:center;flex-shrink:0}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 1300px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#" class="on">Settings</a></nav>
<div style="flex-grow: 1"></div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
</header>
<div style="display: flex; flex-grow: 1; min-height: 0">
<aside style="width: 248px; flex-shrink: 0; box-sizing: border-box; padding: 24px 14px; border-right: 1px solid #232529; display: flex; flex-direction: column; gap: 2px">
<div class="eyebrow" style="padding: 0 12px 8px">Agents</div>
<a class="nav-item" href="#">Personas</a><a class="nav-item" href="#">Schedules</a><a class="nav-item" href="#">Scheduling policy</a>
<div class="eyebrow" style="padding: 18px 12px 8px">Integrations</div>
<a class="nav-item" href="#" style="background: #1e2023; color: #e8e6e1; box-shadow: inset 2px 0 0 #86b5a0">Channels<span class="dot" style="margin-left: auto; background: #86b5a0" title="1 running"></span></a>
<a class="nav-item" href="#">Tools &amp; MCP</a><a class="nav-item" href="#">Plugins</a>
<div class="eyebrow" style="padding: 18px 12px 8px">Runtime</div>
<a class="nav-item" href="#">Container runtime</a>
<div style="height: 1px; background: #232529; margin: 16px 12px"></div>
<a class="nav-item" href="#"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="9"></circle><path d="M12 7v5l3 2"></path></svg>History</a>
</aside>
<main style="flex-grow: 1; padding: 36px 56px; display: flex; flex-direction: column; gap: 24px; min-width: 0">
<div style="display: flex; align-items: flex-start; gap: 16px; max-width: 980px">
<div style="flex-grow: 1">
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Channels</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Where you talk to Archie, and how chat sessions behave.</p>
</div>
<span class="pill" style="color: #d9a45b; border-color: rgba(217,164,91,.3); background: rgba(217,164,91,.08)">Applies after restart</span>
</div>
<div style="max-width: 980px; display: flex; flex-direction: column; gap: 16px">
<section class="card">
<div class="card-h">
<div class="icon"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><path d="m22 3-9.5 18-2.5-8-8-2.5L22 3Z"></path></svg></div>
<div style="flex-grow: 1"><div style="font-size: 15px; font-weight: 500">Telegram</div><div class="hint">Talk to Archie and approve its work from your phone.</div></div>
<span class="pill" style="color: #86b5a0; border-color: #86b5a0"><span class="dot" style="background: #86b5a0"></span>Running</span>
</div>
<div class="row" style="border-top: 0">
<div><div class="lbl">Bot token</div><div class="hint">Secret reference for the Telegram bot.</div></div>
<div>
<div style="display: flex; align-items: center; gap: 10px; height: 38px; padding: 0 12px; border: 1px solid #2e3034; border-radius: 6px; background: #121314">
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><rect x="4" y="10" width="16" height="10" rx="2"></rect><path d="M8 10V7a4 4 0 0 1 8 0v3"></path></svg>
<span class="mono" style="font-size: 12px; color: #8f8c85">env</span><span style="color: #4a4c50">/</span><span class="mono" style="font-size: 13px">HEYARCHIE_TELEGRAM_BOT_TOKEN</span>
<div style="flex-grow: 1"></div><button class="btn btn-sm" style="height: 26px; background: transparent">Change</button>
</div>
<div style="display: flex; align-items: center; gap: 6px; font-size: 12px; color: #86b5a0; margin-top: 6px"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2"><path d="m5 12 5 5 9-10"></path></svg>Credential resolved by Archie</div>
</div>
</div>
<div class="row">
<div><div class="lbl">Allowed users</div><div class="hint">Telegram user IDs that may talk to Archie. Everyone else is ignored.</div></div>
<div style="display: flex; flex-wrap: wrap; align-items: center; gap: 8px; padding: 6px; border: 1px solid #2e3034; border-radius: 6px; background: #121314; min-height: 38px; box-sizing: border-box">
<span style="display: inline-flex; align-items: center; gap: 6px; height: 26px; padding: 0 6px 0 10px; border-radius: 4px; background: #1e2023; font: 12px 'IBM Plex Mono', monospace">1312197967<button aria-label="Remove 1312197967" style="width: 20px; height: 20px; border: 0; background: transparent; color: #8f8c85; cursor: pointer">×</button></span>
<input aria-label="Add user ID" placeholder="Add user ID…" style="flex-grow: 1; min-width: 140px; background: transparent; border: 0; outline: none; color: #e8e6e1; font: 12px 'IBM Plex Mono', monospace">
</div>
</div>
</section>
<section class="card" style="flex-direction: row; align-items: center; gap: 12px; padding: 16px 20px">
<div class="icon"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><path d="M3 6h18v12H3zM3 6l9 7 9-7"></path></svg></div>
<div style="flex-grow: 1"><div style="font-size: 15px; font-weight: 500">Email</div><div class="hint">Listen for mail and relay replies.</div></div>
<span class="pill">Not set up</span>
<button class="btn btn-sm">Set up</button>
</section>
<section class="card" style="flex-direction: row; align-items: center; gap: 12px; padding: 16px 20px">
<div class="icon"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><path d="M10 13a5 5 0 0 0 7 0l3-3a5 5 0 0 0-7-7l-1 1M14 11a5 5 0 0 0-7 0l-3 3a5 5 0 0 0 7 7l1-1"></path></svg></div>
<div style="flex-grow: 1"><div style="font-size: 15px; font-weight: 500">Webhook</div><div class="hint">Deliver agent output to a URL, with a signing secret and template.</div></div>
<span class="pill">Not set up</span>
<button class="btn btn-sm">Set up</button>
</section>
<div class="eyebrow" style="margin-top: 16px">Chat session defaults · all channels</div>
<section class="card">
<div class="row" style="border-top: 0">
<div><label class="lbl" for="ws">Workspace</label><div class="hint">Directory chat sessions start in.</div></div>
<input id="ws" class="inp" value="/home/sam">
</div>
<div class="row">
<div><div class="lbl">Filesystem access</div><div class="hint">Outside the workspace.</div></div>
<div style="display: flex; align-items: flex-start; gap: 12px; padding: 12px; border: 1px solid rgba(217,119,107,.35); background: rgba(217,119,107,.06); border-radius: 8px">
<span class="sw" style="background: #d9776b; margin-top: 2px"><i style="right: 2px; background: #121314"></i></span>
<span><span class="lbl">Unrestricted filesystem</span><span class="hint" style="display: block; color: #e0a39a">On: agents can read and write anywhere this user can.</span></span>
</div>
</div>
<div class="row">
<div><div class="lbl">Show tool calls</div><div class="hint">Post each tool call into the chat.</div></div>
<label style="display: flex; align-items: center; gap: 10px; font-size: 13px; color: #a6a39b"><span class="sw" style="background: #86b5a0"><i style="right: 2px; background: #121314"></i></span>On</label>
</div>
<div class="row">
<div><label class="lbl" for="ms">Max steps</label><div class="hint">Per chat turn. 0 = no limit.</div></div>
<input id="ms" class="inp" value="0" style="width: 120px">
</div>
<div class="row">
<div><div class="lbl">Rate limit</div><div class="hint">Off while either value is 0.</div></div>
<div style="display: flex; align-items: center; gap: 10px; font-size: 13px; color: #a6a39b"><input aria-label="Max requests" class="inp" value="0" style="width: 90px"> requests per <input aria-label="Window" class="inp" value="0" style="width: 80px"><select aria-label="Window unit" class="inp" style="width: 110px; font-family: 'IBM Plex Sans', sans-serif"><option>minutes</option></select></div>
</div>
<div class="row">
<div><label class="lbl" for="md">Models</label><div class="hint">Models chat sessions may use.</div></div>
<input id="md" class="inp" placeholder="Default">
</div>
<div class="row">
<div><label class="lbl" for="op">Operator</label><div class="hint">Who Archie treats as its operator.</div></div>
<input id="op" class="inp" placeholder="Not set">
</div>
</section>
<div style="display: flex; align-items: center; gap: 10px; font-size: 12px; color: #8f8c85">
<svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="9"></circle><path d="M12 7v5l3 2"></path></svg>
Version 1 · 11 fields set by <span class="mono">system:migration</span> 8 hrs ago · <a href="#" style="color: #a6a39b; text-decoration: underline">View in History</a>
</div>
</div>
</main>
</div>
</div>
</body>
</html>
@@ -1,138 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Theme and components</title>
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.h{font-size:11px;text-transform:uppercase;letter-spacing:0.08em;color:#8f8c85;margin:0 0 14px;font-weight:500}
.panel{border:1px solid #2a2c30;border-radius:10px;background:#16171a;padding:24px}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:4px 10px;border-radius:999px;border:1px solid}
.dot{width:7px;height:7px;border-radius:50%}
.sw{width:36px;height:20px;border-radius:999px;position:relative;display:inline-block}
.sw i{position:absolute;top:2px;width:16px;height:16px;border-radius:50%}
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
.hint{font-size:12px;color:#8f8c85}
</style>
</head>
<body>
<div style="--accent: #86b5a0; width: 1440px; height: 980px; box-sizing: border-box; padding: 48px 56px; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; display: flex; flex-direction: column; gap: 24px">
<div>
<h1 style="margin: 0; font-size: 28px; font-weight: 600; letter-spacing: -0.01em">Graphite theme</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Warm neutral greys carry the page; one low-chroma accent marks the active item, focus and primary action.</p>
</div>
<div style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 24px">
<section class="panel">
<h2 class="h">Palette</h2>
<div style="display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 10px">
<div style="display: flex; flex-direction: column; gap: 6px">
<div style="height: 44px; border-radius: 6px; background: #121314; border: 1px solid #2e3034"></div>
<span style="font-size: 12px">Ground</span>
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">#121314</span>
</div>
<div style="display: flex; flex-direction: column; gap: 6px">
<div style="height: 44px; border-radius: 6px; background: #16171a; border: 1px solid #2e3034"></div>
<span style="font-size: 12px">Surface</span>
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">#16171a</span>
</div>
<div style="display: flex; flex-direction: column; gap: 6px">
<div style="height: 44px; border-radius: 6px; background: #1e2023; border: 1px solid #2e3034"></div>
<span style="font-size: 12px">Raised</span>
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">#1e2023</span>
</div>
<div style="display: flex; flex-direction: column; gap: 6px">
<div style="height: 44px; border-radius: 6px; background: #2a2c30; border: 1px solid #2e3034"></div>
<span style="font-size: 12px">Border</span>
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">#2a2c30</span>
</div>
<div style="display: flex; flex-direction: column; gap: 6px">
<div style="height: 44px; border-radius: 6px; background: #e8e6e1; border: 1px solid #2e3034"></div>
<span style="font-size: 12px">Text</span>
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">#e8e6e1</span>
</div>
<div style="display: flex; flex-direction: column; gap: 6px">
<div style="height: 44px; border-radius: 6px; background: #8f8c85; border: 1px solid #2e3034"></div>
<span style="font-size: 12px">Muted</span>
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">#8f8c85</span>
</div>
<div style="display: flex; flex-direction: column; gap: 6px">
<div style="height: 44px; border-radius: 6px; background: #86b5a0; border: 1px solid #2e3034"></div>
<span style="font-size: 12px">Accent</span>
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">#86b5a0</span>
</div>
<div style="display: flex; flex-direction: column; gap: 6px">
<div style="height: 44px; border-radius: 6px; background: #d9a45b; border: 1px solid #2e3034"></div>
<span style="font-size: 12px">Warn</span>
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">#d9a45b</span>
</div>
</div>
<h2 class="h" style="margin-top: 24px">Type</h2>
<div style="display: flex; flex-direction: column; gap: 8px">
<span style="font-size: 24px; font-weight: 600">IBM Plex Sans 600 · 24</span>
<span style="font-size: 14px; color: #a6a39b">IBM Plex Sans 400 · 14 body</span>
<span style="font: 13px 'IBM Plex Mono', monospace">IBM Plex Mono · values, keys, durations</span>
</div>
</section>
<section class="panel">
<h2 class="h">Buttons</h2>
<div style="display: flex; gap: 10px; flex-wrap: wrap">
<button class="btn btn-primary">Save &amp; restart</button>
<button class="btn">Secondary</button>
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard</button>
<button class="btn" style="background: transparent; color: #d9776b; border-color: #3a2a28">Delete</button>
</div>
<h2 class="h" style="margin-top: 24px">Status</h2>
<div style="display: flex; gap: 8px; flex-wrap: wrap">
<span class="pill" style="color: #a6a39b; border-color: #2e3034"><span class="dot" style="background: #86b5a0"></span>Connected</span>
<span class="pill" style="color: #a6a39b; border-color: #2e3034"><span class="dot" style="background: #d9a45b"></span>Connecting…</span>
<span class="pill" style="color: #d9a45b; border-color: rgba(217,164,91,0.3); background: rgba(217,164,91,0.08)">Applies after restart</span>
<span class="pill" style="color: #86b5a0; border-color: #86b5a0">2 edited</span>
<span class="pill" style="color: #e0a39a; border-color: rgba(217,119,107,0.35); background: rgba(217,119,107,0.08)">Invalid duration</span>
</div>
<h2 class="h" style="margin-top: 24px">Toggles &amp; choice</h2>
<div style="display: flex; align-items: center; gap: 20px">
<label style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span class="sw" style="background: #86b5a0"><i style="right: 2px; background: #121314"></i></span>On</label>
<label style="display: flex; align-items: center; gap: 8px; font-size: 13px; color: #a6a39b"><span class="sw" style="background: #2e3034"><i style="left: 2px; background: #8f8c85"></i></span>Off</label>
<div style="display: inline-flex; padding: 3px; background: #121314; border: 1px solid #2e3034; border-radius: 8px">
<button style="height: 28px; padding: 0 12px; border: 0; border-radius: 5px; background: #26282c; color: #e8e6e1; font: 500 12px 'IBM Plex Sans', sans-serif">Assignee</button>
<button style="height: 28px; padding: 0 12px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 12px 'IBM Plex Sans', sans-serif">Label</button>
</div>
</div>
</section>
<section class="panel" style="display: flex; flex-direction: column; gap: 16px">
<h2 class="h" style="margin: 0">Inputs</h2>
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="c1">Text</label><input id="c1" class="inp" value="archie-core_default"></div>
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="c2">Focused</label><input id="c2" class="inp" value="ghcr.io/…/archie-agent:latest" style="border-color: #86b5a0; box-shadow: 0 0 0 3px rgba(134,181,160,0.15)"></div>
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="c3">Duration with unit</label>
<div style="display: flex"><input id="c3" class="inp" value="72" style="border-radius: 6px 0 0 6px"><select aria-label="Unit" class="inp" style="width: 110px; border-radius: 0 6px 6px 0; border-left: 0; font-family: 'IBM Plex Sans', sans-serif"><option>hours</option></select></div></div>
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="c4">Error</label><input id="c4" class="inp" value="1hr" style="border-color: #d9776b"><span style="font-size: 12px; color: #e0a39a">Use a number and a unit, e.g. 1h or 90m</span></div>
<div style="display: flex; flex-direction: column; gap: 6px"><span class="lbl">Secret reference</span>
<div style="display: flex; align-items: center; gap: 8px; height: 36px; padding: 0 12px; border: 1px solid #2e3034; border-radius: 6px">
<svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><rect x="4" y="10" width="16" height="10" rx="2"></rect><path d="M8 10V7a4 4 0 0 1 8 0v3"></path></svg>
<span style="font: 12px 'IBM Plex Mono', monospace; color: #8f8c85">bws /</span><span style="font: 13px 'IBM Plex Mono', monospace">MINIMAX_API_KEY</span>
<span style="margin-left: auto; font-size: 12px; color: #86b5a0">resolved</span>
</div></div>
</section>
</div>
</div>
</body>
</html>
@@ -1,103 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Proposed navigation</title>
<script src="./support.js"></script>
</head>
<body>
<x-dc>
<helmet>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a}
.eyebrow{font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:#8f8c85;font-weight:500}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.node{display:flex;align-items:baseline;gap:10px;font-size:14px;font-weight:500}
.sub{font-size:12px;color:#8f8c85;font-weight:400}
.kid{margin:6px 0 0 18px;padding-left:14px;border-left:1px solid #2e3034;display:flex;flex-direction:column;gap:6px;font-size:13px;color:#a6a39b}
.mono{font-family:'IBM Plex Mono',monospace}
.tbl{width:100%;border-collapse:collapse;font-size:13px}
.tbl th{text-align:left;font-weight:500;font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#8f8c85;padding:10px 14px;border-bottom:1px solid #2a2c30}
.tbl td{padding:10px 14px;border-bottom:1px solid #202225;vertical-align:top;line-height:1.45}
</style>
</helmet>
<div style="--accent: {{accent}}; width: 1440px; height: 1120px; box-sizing: border-box; padding: 48px 56px; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; display: flex; flex-direction: column; gap: 28px">
<div>
<h1 style="margin: 0; font-size: 28px; font-weight: 600; letter-spacing: -0.01em">Navigation: today → proposed</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Five top-level places, each with one job. Anything you configure lives in Settings; anything you act on lives where the work is.</p>
</div>
<div style="display: grid; grid-template-columns: 380px minmax(0, 1fr); gap: 24px">
<section class="card" style="padding: 24px; display: flex; flex-direction: column; gap: 16px">
<div class="eyebrow">Today</div>
<div class="node" style="color: #a6a39b">Dashboard</div>
<div><div class="node" style="color: #a6a39b">Work <span class="sub">dropdown</span></div>
<div class="kid"><span>Tasks</span><span>Workflows <span class="sub">editor + start work + stats</span></span><span>Channels <span class="sub">settings + audit</span></span></div></div>
<div><div class="node" style="color: #a6a39b">Events</div>
<div class="kid"><span>Inspector · Bindings · Mappings</span></div></div>
<div><div class="node" style="color: #a6a39b">System <span class="sub">dropdown</span></div>
<div class="kid"><span>Advanced <span class="sub">6 cards, 6 save buttons</span></span></div></div>
<p class="hint" style="margin: 8px 0 0">Dropdown contents are inferred from the screenshots; confirm against the router.</p>
</section>
<section class="card" style="padding: 24px">
<div class="eyebrow" style="margin-bottom: 16px; color: {{accent}}">Proposed</div>
<div style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 24px 32px">
<div><div class="node">Dashboard <span class="sub">what needs me</span></div>
<div class="kid"><span>Needs you queue</span><span>Live activity</span><span>Health: gates, tokens</span></div></div>
<div><div class="node">Tasks <span class="sub">the work</span></div>
<div class="kid"><span>Task list <span class="sub">filter by state</span></span><span>Task detail <span class="sub">log · files · config · debug</span></span><span>Attempts in a side rail</span></div></div>
<div><div class="node">Workflows <span class="sub">how work runs</span></div>
<div class="kid"><span>List with success + cost</span><span>Definition editor</span><span>Performance tab <span class="sub">stages, failures</span></span></div></div>
<div><div class="node">Events <span class="sub">what comes in</span></div>
<div class="kid"><span>Inspector</span><span>Bindings</span><span>Mappings</span></div></div>
<div style="grid-column: span 2"><div class="node">Settings <span class="sub">everything you configure, one save flow</span></div>
<div class="kid" style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 6px 24px">
<span><span style="color: #e8e6e1">Agents</span><br>Personas · Schedules · Scheduling policy</span>
<span><span style="color: #e8e6e1">Integrations</span><br>Channels · Tools &amp; MCP · Plugins</span>
<span><span style="color: #e8e6e1">Runtime</span><br>Container runtime · History</span>
</div></div>
</div>
<div style="margin-top: 24px; padding-top: 16px; border-top: 1px solid #232529; display: flex; gap: 24px; font-size: 13px; color: #a6a39b">
<span><span style="color: #e8e6e1; font-weight: 500">Always in the top bar:</span> New task · ⌘K Jump to · connection status</span>
</div>
</section>
</div>
<section class="card" style="overflow: hidden">
<table class="tbl">
<thead><tr><th style="width: 290px">What</th><th style="width: 280px">Moves to</th><th>Why</th></tr></thead>
<tbody>
<sc-for list="{{moves}}" as="m" hint-placeholder-count="9">
<tr><td style="color: #e8e6e1">{{m.what}}</td><td><span style="color: {{accent}}">→</span> {{m.to}}</td><td style="color: #a6a39b">{{m.why}}</td></tr>
</sc-for>
</tbody>
</table>
</section>
</div>
</x-dc>
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1120}}'>
class Component extends DCLogic {
renderVals() {
return {
accent: this.props.accent ?? '#86b5a0',
moves: [
{ what: 'Start work card (Workflows)', to: 'New task dialog, from the top bar', why: 'Starting work is not editing a workflow. One entry point from any page, and from ⌘K.' },
{ what: 'Channels (Work menu)', to: 'Settings › Integrations › Channels', why: 'It is configuration. It gets the same setting rows, secret fields and save flow as the rest.' },
{ what: 'Audit table (Channels page)', to: 'Settings › History', why: 'One change log for every setting, filterable by section. Replaces six History links.' },
{ what: 'Per workflow table', to: 'Workflows list columns', why: 'Runs, success and cost sit next to the workflow you are about to open.' },
{ what: 'Slowest stages · Most failures', to: 'Workflow › Performance tab', why: 'Scoped to the selected workflow instead of mixing every workflow in one table.' },
{ what: 'Connecting · Version pills on every card', to: 'One status in the top bar', why: 'Connection is global. Version shows once per page, in History.' },
{ what: 'Settings "Managed elsewhere" row', to: 'Events tabs', why: 'Captured events, mappings and bindings already live there.' },
{ what: 'Task "Attempt 2 is not recorded" column', to: 'Attempts list in the task side rail', why: 'Shows every attempt with its outcome; the empty column goes away.' },
{ what: 'Dashboard stat cards and health', to: 'Stat strip + right rail', why: '"Needs you" becomes the first thing on the page, with actions inline.' }
]
};
}
}
</script>
</body>
</html>
@@ -1,172 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Dashboard</title>
<script src="./support.js"></script>
</head>
<body>
<x-dc>
<helmet>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
.card-h{display:flex;align-items:center;gap:12px;padding:16px 20px;border-bottom:1px solid #232529}
.card-t{font-size:15px;font-weight:500}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.eyebrow{font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:#8f8c85;font-weight:500}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
.warn{color:#d9a45b;border-color:rgba(217,164,91,.3);background:rgba(217,164,91,.08)}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.nav a.on{color:#e8e6e1;background:#1e2023}
.tbl{width:100%;border-collapse:collapse;font-size:13px}
.tbl th{text-align:left;font-weight:500;font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#8f8c85;padding:10px 20px;border-bottom:1px solid #2a2c30}
.tbl td{padding:10px 20px;border-bottom:1px solid #202225;vertical-align:middle}
.chip{font:11px 'IBM Plex Mono',monospace;color:#8f8c85;background:#1e2023;border-radius:4px;padding:1px 6px;margin-left:6px}
</style>
</helmet>
<div style="--accent: {{accent}}; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden; position: relative">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#" class="on">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
<div style="flex-grow: 1"></div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: {{accent}}"></span>Connected</span>
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
</header>
<main style="flex-grow: 1; padding: 32px 48px; display: flex; flex-direction: column; gap: 24px; min-height: 0">
<div style="display: flex; align-items: flex-end; gap: 16px">
<div style="flex-grow: 1">
<h1 style="margin: 0; font-size: 28px; font-weight: 600; letter-spacing: -0.01em">Good morning</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Nothing is running. <span style="color: #d9a45b">3 tasks need you.</span></p>
</div>
<button class="btn"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 6h16M4 12h10M4 18h13"></path></svg>Logs</button>
</div>
<section class="card" style="flex-direction: row">
<sc-for list="{{stats}}" as="s" hint-placeholder-count="4">
<div style="flex: 1 1 0; padding: 18px 22px; border-right: 1px solid #232529">
<div class="hint">{{s.label}}</div>
<div style="font-size: 30px; font-weight: 600; margin-top: 6px; color: {{s.color}}">{{s.value}}</div>
<div class="hint" style="margin-top: 2px">{{s.sub}}</div>
</div>
</sc-for>
</section>
<div style="display: grid; grid-template-columns: minmax(0, 1fr) 380px; gap: 24px; min-height: 0; flex-grow: 1">
<div style="display: flex; flex-direction: column; gap: 24px; min-width: 0">
<section class="card">
<div class="card-h"><span class="card-t">Needs you</span><span class="pill warn">3</span><div style="flex-grow: 1"></div><a href="#" class="hint" style="text-decoration: underline">All tasks</a></div>
<sc-for list="{{needs}}" as="n" hint-placeholder-count="3">
<div style="display: grid; grid-template-columns: 120px minmax(0, 1fr) auto; gap: 16px; align-items: center; padding: 14px 20px; border-bottom: 1px solid #202225">
<span class="pill warn" style="justify-self: start">{{n.state}}</span>
<div style="min-width: 0">
<a href="#" style="font-size: 14px; font-weight: 500">{{n.title}}</a>
<div class="mono" style="font-size: 12px; color: #8f8c85; margin-top: 3px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">{{n.meta}}</div>
</div>
<div style="display: flex; gap: 8px"><button class="btn btn-sm btn-ghost">Open</button><button class="btn btn-sm">{{n.action}}</button></div>
</div>
</sc-for>
</section>
<section class="card" style="flex-grow: 1; overflow: hidden">
<div class="card-h"><span class="card-t">Live activity</span><span class="pill" style="color: {{accent}}; border-color: {{accent}}"><span class="dot" style="background: {{accent}}"></span>live</span><div style="flex-grow: 1"></div>
<div role="radiogroup" aria-label="Filter activity" style="display: inline-flex; padding: 2px; border: 1px solid #2e3034; border-radius: 7px"><button style="height: 26px; padding: 0 10px; border: 0; border-radius: 5px; background: #26282c; color: #e8e6e1; font: 500 12px 'IBM Plex Sans', sans-serif">All</button><button style="height: 26px; padding: 0 10px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 12px 'IBM Plex Sans', sans-serif">Tasks</button><button style="height: 26px; padding: 0 10px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 12px 'IBM Plex Sans', sans-serif">System</button></div>
</div>
<table class="tbl">
<thead><tr><th>Event</th><th style="width: 70px">Task</th><th>Detail</th><th style="width: 110px">When</th></tr></thead>
<tbody>
<sc-for list="{{activity}}" as="a" hint-placeholder-count="8">
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: {{a.color}}"></span>{{a.event}}<sc-if value="{{a.count}}" hint-placeholder-val="{{false}}"><span class="chip">×{{a.count}}</span></sc-if></td><td class="mono" style="font-size: 12px; color: #a6a39b">{{a.task}}</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">{{a.detail}}</td><td class="hint">{{a.when}}</td></tr>
</sc-for>
</tbody>
</table>
</section>
</div>
<div style="display: flex; flex-direction: column; gap: 24px">
<section class="card">
<div class="card-h"><span class="card-t">Quality gates</span><div style="flex-grow: 1"></div><span class="hint">last 4 runs</span></div>
<div style="padding: 20px; display: flex; flex-direction: column; gap: 16px">
<div style="display: flex; align-items: baseline; gap: 10px"><span style="font-size: 30px; font-weight: 600">25%</span><span class="hint">pass rate</span></div>
<sc-for list="{{gates}}" as="g" hint-placeholder-count="2">
<div>
<div style="display: flex; font-size: 13px; margin-bottom: 6px"><span class="mono">{{g.name}}</span><span style="margin-left: auto; color: #a6a39b" class="mono">{{g.score}}</span></div>
<div style="height: 6px; border-radius: 3px; background: #26282c"><div style="height: 6px; border-radius: 3px; width: {{g.pct}}; background: {{g.color}}"></div></div>
</div>
</sc-for>
</div>
</section>
<section class="card">
<div class="card-h"><span class="card-t">Token outlook</span></div>
<div style="padding: 20px; display: flex; flex-direction: column; gap: 14px">
<div style="display: flex; gap: 24px">
<div><div class="hint">Today</div><div style="font-size: 22px; font-weight: 600; margin-top: 2px">14.5M</div></div>
<div><div class="hint">Next 30 days at this rate</div><div style="font-size: 22px; font-weight: 600; margin-top: 2px">≈ 434M</div></div>
</div>
<div aria-label="Tokens per day, last 7 days" style="display: flex; align-items: flex-end; gap: 6px; height: 64px">
<sc-for list="{{days}}" as="d" hint-placeholder-count="7"><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: {{d.h}}; border-radius: 3px; background: {{d.color}}"></div><span class="mono" style="font-size: 10px; color: #8f8c85">{{d.label}}</span></div></sc-for>
</div>
<div class="hint">Only 1 day of history. The projection steadies after a week of runs.</div>
</div>
</section>
</div>
</div>
</main>
<button aria-label="Chat with Archie" style="position: absolute; right: 24px; bottom: 24px; width: 48px; height: 48px; border-radius: 50%; border: 1px solid #34373c; background: #1e2023; color: {{accent}}; display: flex; align-items: center; justify-content: center; box-shadow: 0 8px 24px rgba(0,0,0,.4); cursor: pointer"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a8 8 0 0 1-11.6 7.1L4 20l1-4.6A8 8 0 1 1 21 12Z"></path></svg></button>
</div>
</x-dc>
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1080}}'>
class Component extends DCLogic {
renderVals() {
const accent = this.props.accent ?? '#86b5a0';
const sys = '#6f6c66', task = '#8aa4c2', bad = '#d9776b', ok = accent;
return {
accent,
stats: [
{ label: 'Working now', value: '0', sub: '0 waiting to start', color: '#e8e6e1' },
{ label: 'Needs you', value: '3', sub: 'Parked or awaiting a reply', color: '#d9a45b' },
{ label: 'Delivered', value: '1', sub: '25% of all tasks', color: '#e8e6e1' },
{ label: 'Tokens used', value: '14.5M', sub: 'Across 1 day', color: '#e8e6e1' }
],
needs: [
{ state: 'Parked', title: 'changes_captured key-set validation is top-level only', meta: 'archie-core #868 · tdd · worktree prepare failed: fetch origin: http transport…', action: 'Start new run' },
{ state: 'Awaiting reply', title: '[Task title]', meta: '[repo #issue] · [workflow] · [last agent message]', action: 'Reply' },
{ state: 'Awaiting reply', title: '[Task title]', meta: '[repo #issue] · [workflow] · [last agent message]', action: 'Reply' }
],
activity: [
{ event: 'curator_run', task: '—', detail: 'session-memory', when: '19 mins ago', color: sys, count: 0 },
{ event: 'task_archive_requested', task: '#5', detail: 'archive requested with no recorded actor', when: '1 hr ago', color: task, count: 0 },
{ event: 'task_abandoned', task: '#5', detail: 'abandoned with no recorded actor', when: '1 hr ago', color: bad, count: 0 },
{ event: 'curator_run', task: '—', detail: 'session-memory', when: '1 hr ago', color: sys, count: 6 },
{ event: 'stage_start', task: '#5', detail: '', when: '1 hr ago', color: task, count: 4 },
{ event: 'stage_start', task: '#4', detail: '', when: '7 hrs ago', color: task, count: 5 },
{ event: 'agent_finish', task: '#4', detail: 'Problem surface for samcharles93/archie-core issue 836 ("Updater cannot detect o…', when: '7 hrs ago', color: ok, count: 0 },
{ event: 'agent_finish', task: '#4', detail: 'Root cause', when: '7 hrs ago', color: ok, count: 0 },
{ event: 'stage_start', task: '#4', detail: '', when: '8 hrs ago', color: task, count: 6 }
],
gates: [
{ name: 'tdd', score: '0 / 3', pct: '2%', color: '#d9776b' },
{ name: 'triage', score: '1 / 1', pct: '100%', color: accent }
],
days: ['M','T','W','T','F','S','S'].map((l, i) => ({ label: l, h: i === 4 ? '48px' : '3px', color: i === 4 ? accent : '#26282c' }))
};
}
}
</script>
</body>
</html>
@@ -1,138 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Task detail</title>
<script src="./support.js"></script>
</head>
<body>
<x-dc>
<helmet>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
.card-h{display:flex;align-items:center;gap:12px;padding:14px 20px;border-bottom:1px solid #232529}
.card-t{font-size:14px;font-weight:500}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
.warn{color:#d9a45b;border-color:rgba(217,164,91,.3);background:rgba(217,164,91,.08)}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.nav a.on{color:#e8e6e1;background:#1e2023}
.tab{height:44px;display:flex;align-items:center;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
.sel{height:32px;box-sizing:border-box;padding:0 10px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:13px 'IBM Plex Sans',sans-serif}
.kv{display:grid;grid-template-columns:96px minmax(0,1fr);gap:10px;font-size:13px;padding:8px 0;border-bottom:1px solid #202225}
.kv dt{color:#8f8c85}.kv dd{margin:0}
.tag{font:11px 'IBM Plex Mono',monospace;color:#a6a39b;background:#1e2023;border-radius:4px;padding:1px 6px}
</style>
</helmet>
<div style="--accent: {{accent}}; width: 1440px; height: 1000px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#" class="on">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
<div style="flex-grow: 1"></div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: {{accent}}"></span>Connected</span>
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
</header>
<main style="flex-grow: 1; padding: 24px 48px 32px; display: flex; flex-direction: column; gap: 20px; min-height: 0">
<div>
<div class="hint"><a href="#" style="color: #a6a39b">Tasks</a> / <span class="mono">#1</span></div>
<div style="display: flex; align-items: flex-start; gap: 16px; margin-top: 8px">
<div style="flex-grow: 1; min-width: 0">
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">changes_captured key-set validation is top-level only</h1>
<div style="display: flex; align-items: center; gap: 12px; margin-top: 8px; font-size: 13px; color: #a6a39b">
<span class="pill warn"><span class="dot" style="background: #d9a45b"></span>Parked</span>
<span class="mono">tdd</span><span style="color: #4a4c50">·</span>
<a href="#" class="mono" style="color: #a6a39b; text-decoration: underline">samcharles93/archie-core #868</a>
</div>
</div>
<button class="btn btn-ghost">Archive</button>
<button class="btn btn-primary"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a9 9 0 1 1-3-6.7L21 8"></path><path d="M21 3v5h-5"></path></svg>Start a new run</button>
</div>
</div>
<div role="alert" style="display: flex; gap: 12px; padding: 14px 16px; border-radius: 8px; background: rgba(217,164,91,0.08); border: 1px solid rgba(217,164,91,0.25)">
<svg style="flex-shrink: 0; margin-top: 2px" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#d9a45b" stroke-width="2"><path d="M12 3 2 20h20L12 3Z"></path><path d="M12 10v4M12 17h.01"></path></svg>
<div style="min-width: 0; flex-grow: 1">
<div style="font-size: 14px; font-weight: 500; color: #e3c08f">Parked: couldn’t prepare the worktree</div>
<div class="mono" style="font-size: 12px; color: #a6a39b; margin-top: 4px; line-height: 1.6; word-break: break-all">fetch origin: http transport: Get "https://github.com/samcharles93/archie-core.git/info/refs?service=git-upload-pack": terminated signal received</div>
</div>
<button class="btn btn-sm" style="align-self: flex-start">Jump to log line</button>
</div>
<div style="display: grid; grid-template-columns: minmax(0, 1fr) 320px; gap: 24px; flex-grow: 1; min-height: 0">
<section class="card" style="overflow: hidden">
<nav style="display: flex; gap: 28px; padding: 0 20px; border-bottom: 1px solid #232529">
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: {{accent}}">Log</a>
<a class="tab" href="#">Changed files <span class="hint" style="margin-left: 6px">0</span></a>
<a class="tab" href="#">Configuration</a>
<a class="tab" href="#">Debug</a>
</nav>
<div style="display: flex; align-items: center; gap: 8px; padding: 12px 20px; border-bottom: 1px solid #232529">
<select aria-label="Level" class="sel"><option>All levels</option></select>
<select aria-label="Stage" class="sel"><option>All stages</option></select>
<label style="display: flex; align-items: center; gap: 8px; height: 32px; width: 260px; padding: 0 10px; box-sizing: border-box; border: 1px solid #2e3034; border-radius: 6px; color: #8f8c85"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Search log" placeholder="Search log" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: 13px 'IBM Plex Sans', sans-serif; width: 100%"></label>
<div style="flex-grow: 1"></div>
<button class="btn btn-sm btn-ghost"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 4v11M7 10l5 5 5-5M5 20h14"></path></svg>Download</button>
</div>
<div class="mono" style="font-size: 12px; line-height: 1.7; flex-grow: 1; background: #121314">
<div style="display: grid; grid-template-columns: 72px 56px minmax(0, 1fr); gap: 12px; padding: 10px 20px; background: rgba(217,119,107,0.06); border-left: 2px solid #d9776b">
<span style="color: #8f8c85">08:38:49</span>
<span style="color: #e0a39a">ERROR</span>
<div style="min-width: 0">
<div style="word-break: break-all">task parked: worktree prepare failed: fetch origin: http transport: Get "https://github.com/samcharles93/archie-core.git/info/refs?service=git-upload-pack": terminated signal received</div>
<div style="display: flex; gap: 6px; margin-top: 6px"><span class="tag">component=daemon</span><span class="tag">task=1</span></div>
</div>
</div>
<div style="padding: 16px 20px; color: #8f8c85; font-family: 'IBM Plex Sans', sans-serif; font-size: 12px">End of attempt 1 · 1 line</div>
</div>
</section>
<aside style="display: flex; flex-direction: column; gap: 20px">
<section class="card">
<div class="card-h"><span class="card-t">Attempts</span></div>
<div style="padding: 8px 12px">
<a href="#" style="display: flex; align-items: center; gap: 10px; padding: 10px 8px; border-radius: 6px; background: #1e2023; box-shadow: inset 2px 0 0 {{accent}}">
<span class="dot" style="background: #d9a45b"></span><span style="font-size: 13px; flex-grow: 1">Attempt 1</span><span class="hint">parked · 08:38</span></a>
<div style="display: flex; align-items: center; gap: 10px; padding: 10px 8px; color: #8f8c85">
<span class="dot" style="background: transparent; border: 1px dashed #4a4c50; box-sizing: border-box"></span><span style="font-size: 13px; flex-grow: 1">Attempt 2</span><span class="hint">not recorded</span></div>
</div>
</section>
<section class="card">
<div class="card-h"><span class="card-t">Details</span></div>
<dl style="margin: 0; padding: 4px 20px 12px">
<div class="kv"><dt>Status</dt><dd style="color: #d9a45b">Parked</dd></div>
<div class="kv"><dt>Workflow</dt><dd><a href="#" class="mono" style="text-decoration: underline">tdd</a></dd></div>
<div class="kv"><dt>Repository</dt><dd class="mono" style="font-size: 12px">samcharles93/archie-core</dd></div>
<div class="kv"><dt>Issue</dt><dd><a href="#" style="text-decoration: underline">#868</a> ↗</dd></div>
<div class="kv"><dt>Persona</dt><dd class="mono" style="font-size: 12px">[persona]</dd></div>
<div class="kv"><dt>Tokens</dt><dd class="mono" style="font-size: 12px">[tokens]</dd></div>
<div class="kv" style="border: 0"><dt>Started</dt><dd>[date · time]</dd></div>
</dl>
</section>
</aside>
</div>
</main>
</div>
</x-dc>
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1000}}'>
class Component extends DCLogic {
renderVals() {
return { accent: this.props.accent ?? '#86b5a0' };
}
}
</script>
</body>
</html>
@@ -1,142 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Workflows</title>
<script src="./support.js"></script>
</head>
<body>
<x-dc>
<helmet>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.lbl{font-size:13px;font-weight:500}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.nav a.on{color:#e8e6e1;background:#1e2023}
.tab{height:44px;display:flex;align-items:center;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
.step{font:12px 'IBM Plex Mono',monospace;padding:6px 10px;border:1px solid #2e3034;border-radius:6px;background:#121314;white-space:nowrap}
</style>
</helmet>
<div style="--accent: {{accent}}; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#" class="on">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
<div style="flex-grow: 1"></div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: {{accent}}"></span>Connected</span>
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
</header>
<main style="flex-grow: 1; padding: 32px 48px; display: flex; flex-direction: column; gap: 24px; min-height: 0">
<div style="display: flex; align-items: flex-end; gap: 12px">
<div style="flex-grow: 1">
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Workflows</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">The step sequences agents follow. Success rate is merged tasks over all runs.</p>
</div>
<button class="btn btn-ghost"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 12a9 9 0 1 0 3-6.7L3 8"></path><path d="M3 3v5h5"></path></svg>Restore shipped</button>
<button class="btn"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New workflow</button>
</div>
<div style="display: grid; grid-template-columns: 420px minmax(0, 1fr); gap: 24px; flex-grow: 1; min-height: 0">
<section class="card" style="overflow: hidden">
<div style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; padding: 10px 16px; font-size: 11px; letter-spacing: .06em; text-transform: uppercase; color: #8f8c85; border-bottom: 1px solid #2a2c30"><span>Workflow</span><span>Runs</span><span>Success</span><span style="text-align: right">Avg tok</span></div>
<sc-for list="{{flows}}" as="f" hint-placeholder-count="6">
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: {{f.bg}}; box-shadow: {{f.shadow}}">
<span><span style="font-size: 14px; font-weight: 500; display: block">{{f.name}}</span><span class="mono" style="font-size: 11px; color: #8f8c85">{{f.id}}</span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b">{{f.runs}}</span>
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">{{f.rate}}</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: {{f.pct}}; background: {{f.barColor}}"></span></span></span>
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">{{f.tokens}}</span>
</a>
</sc-for>
</section>
<section class="card" style="overflow: hidden">
<div style="display: flex; align-items: center; gap: 12px; padding: 18px 24px 0">
<h2 style="margin: 0; font-size: 18px; font-weight: 600">Bootstrap</h2>
<span class="pill">shipped · edited</span>
<div style="flex-grow: 1"></div>
<span class="hint">0 runs yet</span>
</div>
<nav style="display: flex; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529">
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: {{accent}}">Definition</a>
<a class="tab" href="#">Performance</a>
<a class="tab" href="#">Runs</a>
</nav>
<div style="padding: 20px 24px; display: flex; flex-direction: column; gap: 18px; flex-grow: 1; min-height: 0">
<div style="display: grid; grid-template-columns: 280px minmax(0, 1fr); gap: 24px">
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="wid">ID</label><input id="wid" class="inp" value="bootstrap"></div>
<div style="display: flex; flex-direction: column; gap: 6px"><span class="lbl">Steps</span>
<div style="display: flex; align-items: center; gap: 6px; height: 36px; flex-wrap: nowrap; overflow: hidden">
<sc-for list="{{steps}}" as="s" hint-placeholder-count="5"><span class="step">{{s.name}}</span><sc-if value="{{s.more}}" hint-placeholder-val="{{true}}"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#4a4c50" stroke-width="2"><path d="M5 12h14M13 6l6 6-6 6"></path></svg></sc-if></sc-for>
</div></div>
</div>
<div style="display: flex; flex-direction: column; gap: 6px; flex-grow: 1; min-height: 0">
<div style="display: flex; align-items: baseline"><span class="lbl">YAML</span><span class="hint" style="margin-left: auto; color: {{accent}}">✓ Valid</span></div>
<div class="mono" style="flex-grow: 1; display: grid; grid-template-columns: 44px minmax(0, 1fr); border: 1px solid #2e3034; border-radius: 8px; background: #121314; font-size: 13px; line-height: 1.75; overflow: hidden">
<div style="padding: 14px 0; text-align: right; padding-right: 12px; color: #4f5156; border-right: 1px solid #232529; background: #141517; white-space: pre-line">{{lineNos}}</div>
<div style="padding: 14px 16px; white-space: pre"><span style="color: #a6a39b">id:</span> bootstrap
<span style="color: #a6a39b">steps:</span>
- <span style="color: #a6a39b">type:</span> <span style="color: {{accent}}">bootstrap.prepare</span>
- <span style="color: #a6a39b">type:</span> <span style="color: {{accent}}">bootstrap.apply</span>
- <span style="color: #a6a39b">type:</span> <span style="color: {{accent}}">bootstrap.commit-push</span>
- <span style="color: #a6a39b">type:</span> <span style="color: {{accent}}">bootstrap.diff-cap</span>
- <span style="color: #a6a39b">type:</span> <span style="color: {{accent}}">bootstrap.open-pr</span></div>
</div>
</div>
</div>
<div style="display: flex; align-items: center; gap: 10px; padding: 14px 24px; border-top: 1px solid #2a2c30; background: #17181a">
<span class="hint">Version 1 · <a href="#" style="color: #a6a39b; text-decoration: underline">History</a></span>
<div style="flex-grow: 1"></div>
<button class="btn btn-ghost" style="color: #d9776b">Remove</button>
<button class="btn">Restore this workflow</button>
<button class="btn btn-primary">Validate &amp; save</button>
</div>
</section>
</div>
</main>
</div>
</x-dc>
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1080}}'>
class Component extends DCLogic {
renderVals() {
const accent = this.props.accent ?? '#86b5a0';
const rows = [
['Bootstrap', 'bootstrap', '0', '—', '0%', '—'],
['Feasibility check', 'feasibility', '0', '—', '0%', '—'],
['Implement', 'implement', '0', '—', '0%', '—'],
['Remediate', 'remediate', '0', '—', '0%', '—'],
['TDD', 'tdd', '3', '0 of 3', '2%', '4.7M'],
['Triage', 'triage', '1', '1 of 1', '100%', '282k']
];
const steps = ['prepare', 'apply', 'commit-push', 'diff-cap', 'open-pr'];
return {
accent,
flows: rows.map(([name, id, runs, rate, pct, tokens], i) => ({
name, id, runs, rate, pct, tokens,
barColor: rate === '0 of 3' ? '#d9776b' : accent,
bg: i === 0 ? '#1e2023' : 'transparent',
shadow: i === 0 ? 'inset 2px 0 0 ' + accent : 'none'
})),
steps: steps.map((name, i) => ({ name, more: i < steps.length - 1 })),
lineNos: '1\n2\n3\n4\n5\n6\n7'
};
}
}
</script>
</body>
</html>
@@ -1,83 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>New task dialog</title>
<script src="./support.js"></script>
</head>
<body>
<x-dc>
<helmet>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.lbl{font-size:13px;font-weight:500}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.inp{box-sizing:border-box;height:38px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
.field{display:flex;flex-direction:column;gap:6px}
.opt{display:flex;flex-direction:column;gap:2px;padding:10px 12px;border:1px solid #2e3034;border-radius:8px;cursor:pointer}
</style>
</helmet>
<div style="--accent: {{accent}}; width: 1440px; height: 900px; box-sizing: border-box; position: relative; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
<div style="flex-grow: 1"></div>
<button class="btn btn-sm" style="border-color: {{accent}}"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: {{accent}}"></span>Connected</span>
</header>
<div style="padding: 32px 48px"><div style="font-size: 28px; font-weight: 600; color: #3a3c40">Good morning</div></div>
<div style="position: absolute; inset: 0; background: rgba(8,9,10,0.6)"></div>
<section role="dialog" aria-modal="true" aria-labelledby="nt-title" style="position: absolute; left: 50%; top: 88px; transform: translateX(-50%); width: 640px; box-sizing: border-box; background: #17181a; border: 1px solid #2a2c30; border-radius: 12px; box-shadow: 0 24px 64px rgba(0,0,0,0.5); display: flex; flex-direction: column">
<div style="display: flex; align-items: flex-start; padding: 22px 24px 18px; border-bottom: 1px solid #232529">
<div style="flex-grow: 1"><h2 id="nt-title" style="margin: 0; font-size: 18px; font-weight: 600">New task</h2><div class="hint" style="margin-top: 2px">Goes into Archie’s normal task queue.</div></div>
<button aria-label="Close" style="width: 32px; height: 32px; border: 0; background: transparent; color: #8f8c85; cursor: pointer"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 6l12 12M18 6 6 18"></path></svg></button>
</div>
<div style="padding: 20px 24px; display: flex; flex-direction: column; gap: 18px">
<div class="field"><label class="lbl" for="repo">Repository</label><input id="repo" class="inp" value="samcharles93/archie-core"><span class="hint">owner/repository · recent: archie-core</span></div>
<div class="field"><span class="lbl">Workflow</span>
<div role="radiogroup" aria-label="Workflow" style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 8px">
<sc-for list="{{flows}}" as="f" hint-placeholder-count="6">
<label class="opt" style="border-color: {{f.border}}; background: {{f.bg}}"><span style="font-size: 13px; font-weight: 500">{{f.name}}</span><span class="hint">{{f.sub}}</span></label>
</sc-for>
</div></div>
<div class="field"><label class="lbl" for="ttl">Title</label><input id="ttl" class="inp" placeholder="What should Archie do?" style="font-family: 'IBM Plex Sans', sans-serif"></div>
<div class="field"><label class="lbl" for="ins">Instructions</label><textarea id="ins" placeholder="Context, acceptance criteria, files to look at…" style="min-height: 120px; box-sizing: border-box; padding: 12px; background: #121314; border: 1px solid #2e3034; border-radius: 6px; color: #e8e6e1; font: 13px/1.6 'IBM Plex Sans', sans-serif; resize: vertical; outline: none"></textarea></div>
<details style="font-size: 13px; color: #a6a39b"><summary style="cursor: pointer">Advanced · run as identity</summary></details>
</div>
<div style="display: flex; align-items: center; gap: 10px; padding: 14px 24px; border-top: 1px solid #232529">
<span class="hint"><span class="mono" style="padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘↵</span> to start</span>
<div style="flex-grow: 1"></div>
<button class="btn btn-ghost">Cancel</button>
<button class="btn btn-primary">Start task</button>
</div>
</section>
</div>
</x-dc>
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":900}}'>
class Component extends DCLogic {
renderVals() {
const accent = this.props.accent ?? '#86b5a0';
const list = [['TDD', '3 runs · 0% merged'], ['Triage', '1 run · 100% merged'], ['Implement', 'no runs yet'], ['Remediate', 'no runs yet'], ['Feasibility check', 'no runs yet'], ['Bootstrap', 'no runs yet']];
return {
accent,
flows: list.map(([name, sub], i) => ({ name, sub, border: i === 0 ? accent : '#2e3034', bg: i === 0 ? '#1e2023' : 'transparent' }))
};
}
}
</script>
</body>
</html>
@@ -1,108 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Events</title>
<script src="./support.js"></script>
</head>
<body>
<x-dc>
<helmet>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
.card-h{display:flex;align-items:center;gap:12px;padding:16px 20px;border-bottom:1px solid #232529}
.card-t{font-size:15px;font-weight:500}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.nav a.on{color:#e8e6e1;background:#1e2023}
.tab{height:44px;display:flex;align-items:center;gap:8px;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
.count{font:11px 'IBM Plex Mono',monospace;color:#8f8c85;background:#1e2023;border-radius:4px;padding:0 6px}
</style>
</helmet>
<div style="--accent: {{accent}}; width: 1440px; height: 900px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#" class="on">Events</a><a href="#">Settings</a></nav>
<div style="flex-grow: 1"></div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: {{accent}}"></span>Connected</span>
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
</header>
<main style="flex-grow: 1; padding: 32px 48px; display: flex; flex-direction: column; gap: 24px">
<div>
<div style="display: flex; align-items: flex-end; gap: 12px">
<div style="flex-grow: 1"><h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Events</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Webhooks come in, get mapped to event types, and bindings turn them into work.</p></div>
<span class="pill" style="color: {{accent}}; border-color: {{accent}}"><span class="dot" style="background: {{accent}}"></span>Listening</span>
</div>
<nav style="display: flex; gap: 28px; margin-top: 16px; border-bottom: 1px solid #232529">
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: {{accent}}">Inspector</a>
<a class="tab" href="#">Mappings <span class="count">0</span></a>
<a class="tab" href="#">Bindings <span class="count">0</span></a>
</nav>
</div>
<section class="card" style="flex-direction: row">
<sc-for list="{{flow}}" as="f" hint-placeholder-count="3">
<div style="flex: 1 1 0; display: flex; align-items: center; gap: 14px; padding: 18px 22px; border-right: 1px solid #232529">
<span class="mono" style="width: 28px; height: 28px; border-radius: 50%; border: 1px solid #34373c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b; flex-shrink: 0">{{f.n}}</span>
<div style="flex-grow: 1"><div style="font-size: 14px; font-weight: 500">{{f.title}}</div><div class="hint">{{f.sub}}</div></div>
<span class="mono" style="font-size: 20px; color: #8f8c85">{{f.count}}</span>
</div>
</sc-for>
</section>
<div style="display: grid; grid-template-columns: minmax(0, 3fr) minmax(0, 2fr); gap: 24px">
<section class="card">
<div class="card-h"><div style="flex-grow: 1"><div class="card-t">Recent captures</div><div class="hint">Headers and payloads are redacted before they’re stored.</div></div></div>
<div style="padding: 40px 32px; display: flex; flex-direction: column; align-items: center; gap: 12px; text-align: center">
<div style="width: 40px; height: 40px; border-radius: 10px; background: #1e2023; display: flex; align-items: center; justify-content: center"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><path d="M22 12h-6l-2 3h-4l-2-3H2"></path><path d="M5.5 5h13L22 12v6a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2v-6Z"></path></svg></div>
<div style="font-size: 14px; font-weight: 500">No captures yet</div>
<div class="hint">Point a webhook at this endpoint and it shows up here live.</div>
<div style="display: flex; align-items: center; gap: 8px; margin-top: 6px; padding: 4px 4px 4px 14px; border: 1px solid #2e3034; border-radius: 8px; background: #121314">
<span class="mono" style="font-size: 13px">/webhooks/capture/<span style="color: {{accent}}">&lt;source&gt;</span></span>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="8" y="8" width="12" height="12" rx="2"></rect><path d="M16 8V5a1 1 0 0 0-1-1H5a1 1 0 0 0-1 1v10a1 1 0 0 0 1 1h3"></path></svg>Copy</button>
</div>
</div>
</section>
<section class="card">
<div class="card-h"><div style="flex-grow: 1"><div class="card-t">Event types</div><div class="hint">Named shapes that mappings produce.</div></div>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M14 3H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9l-6-6Z"></path><path d="M12 12v6M9 15h6"></path></svg>From payload</button></div>
<div style="padding: 40px 32px; display: flex; flex-direction: column; align-items: center; gap: 8px; text-align: center">
<div style="font-size: 14px; font-weight: 500">No event types or proposals</div>
<div class="hint">Paste a sample payload and Archie proposes a type for it. Proposals from real captures appear here too.</div>
</div>
</section>
</div>
</main>
</div>
</x-dc>
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":900}}'>
class Component extends DCLogic {
renderVals() {
return {
accent: this.props.accent ?? '#86b5a0',
flow: [
{ n: '1', title: 'Capture', sub: 'Webhooks received', count: '0' },
{ n: '2', title: 'Map', sub: 'Payloads → event types', count: '0' },
{ n: '3', title: 'Bind', sub: 'Event types → work', count: '0' }
]
};
}
}
</script>
</body>
</html>
@@ -1,167 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Settings – sidebar layout</title>
<script src="./support.js"></script>
</head>
<body>
<x-dc>
<helmet>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none}
.inp:focus{border-color:var(--accent)}
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.icon-btn{width:36px;height:36px;display:flex;align-items:center;justify-content:center;border-radius:6px;border:1px solid transparent;background:transparent;color:#8f8c85;cursor:pointer}
.icon-btn:hover{background:#1e2023;color:#e8e6e1}
.nav-item{display:flex;align-items:center;gap:10px;height:36px;padding:0 12px;border-radius:6px;color:#a6a39b;font-size:13px}
.row{display:grid;grid-template-columns:280px minmax(0,1fr);gap:32px;padding:20px 0;border-top:1px solid #232529}
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
.hint{font-size:12px;color:#8f8c85;margin-top:4px;line-height:1.5}
</style>
</helmet>
<div style="--accent: {{accent}}; width: 1440px; height: 1040px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; position: relative; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
Archie
</div>
<nav style="display: flex; gap: 4px; font-size: 13px">
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Tasks</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Workflows</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">Settings</a>
</nav>
<div style="flex-grow: 1"></div>
<div style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b; padding: 6px 10px; border: 1px solid #2a2c30; border-radius: 999px">
<span style="width: 7px; height: 7px; border-radius: 50%; background: #d9a45b"></span>
Connecting to archie-core…
</div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 240px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px">
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg>
<input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%">
<span style="font-family: 'IBM Plex Mono', monospace; font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span>
</label>
</header>
<div style="display: flex; flex-grow: 1; min-height: 0">
<aside style="width: 264px; flex-shrink: 0; box-sizing: border-box; padding: 24px 16px; border-right: 1px solid #232529; display: flex; flex-direction: column; gap: 2px">
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 0 12px 8px">Agents</div>
<a class="nav-item" href="#">Personas<span style="margin-left: auto; font-family: 'IBM Plex Mono', monospace; font-size: 11px; color: #8f8c85">6</span></a>
<a class="nav-item" href="#">Schedules<span style="margin-left: auto; font-family: 'IBM Plex Mono', monospace; font-size: 11px; color: #8f8c85">0</span></a>
<a class="nav-item" href="#" style="background: #1e2023; color: #e8e6e1; box-shadow: inset 2px 0 0 {{accent}}">Scheduling policy<span style="margin-left: auto; width: 6px; height: 6px; border-radius: 50%; background: {{accent}}" title="Unsaved changes"></span></a>
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Integrations</div>
<a class="nav-item" href="#">Channels</a>
<a class="nav-item" href="#">Tools &amp; MCP</a>
<a class="nav-item" href="#">Plugins</a>
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Runtime</div>
<a class="nav-item" href="#">Container runtime</a>
<div style="height: 1px; background: #232529; margin: 16px 12px"></div>
<a class="nav-item" href="#">History</a>
<div style="flex-grow: 1"></div>
<div style="font-size: 12px; color: #8f8c85; padding: 12px; line-height: 1.5; border: 1px solid #232529; border-radius: 8px">Config version 1 · last saved by <span style="color: #a6a39b">admin</span><br><a href="#" style="color: {{accent}}">View history</a></div>
</aside>
<main style="flex-grow: 1; overflow: hidden; padding: 40px 56px 120px">
<div style="max-width: 920px">
<div style="display: flex; align-items: flex-start; gap: 16px">
<div style="flex-grow: 1">
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Scheduling policy</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">How Archie picks up work items and labels them as they move through states.</p>
</div>
<span style="display: inline-flex; align-items: center; gap: 6px; font-size: 12px; color: #d9a45b; background: rgba(217,164,91,0.1); border: 1px solid rgba(217,164,91,0.25); padding: 4px 10px; border-radius: 999px">
<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a9 9 0 1 1-3-6.7L21 8"></path><path d="M21 3v5h-5"></path></svg>
Applies after restart</span>
</div>
<h2 style="margin: 36px 0 4px; font-size: 13px; font-weight: 600; color: #a6a39b; text-transform: uppercase; letter-spacing: 0.06em">Dispatch</h2>
<div class="row">
<div><div class="lbl">Trigger</div><div class="hint">What causes a work item to be dispatched to an agent.</div></div>
<div style="display: flex; flex-direction: column; gap: 12px">
<div role="radiogroup" aria-label="Trigger" style="display: inline-flex; align-self: flex-start; padding: 3px; background: #121314; border: 1px solid #2e3034; border-radius: 8px">
<button style="height: 30px; padding: 0 14px; border: 0; border-radius: 5px; background: #26282c; color: #e8e6e1; font: 500 13px 'IBM Plex Sans', sans-serif">Assignee</button>
<button style="height: 30px; padding: 0 14px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 13px 'IBM Plex Sans', sans-serif">Label</button>
</div>
<div class="hint" style="margin: 0">Dispatches when Archie is assigned. Choose <span style="color: #a6a39b">Label</span> to set a trigger label instead.</div>
</div>
</div>
<div class="row">
<div><label class="lbl" for="ack">Ack reaction</label><div class="hint">Reaction posted when a work item is picked up.</div></div>
<div><input id="ack" class="inp" value="eyes" style="width: 220px"></div>
</div>
<h2 style="margin: 36px 0 4px; font-size: 13px; font-weight: 600; color: #a6a39b; text-transform: uppercase; letter-spacing: 0.06em">State labels</h2>
<div class="row">
<div><div class="lbl">Labels by state</div><div class="hint">Label applied to the ticket as the agent moves between states.</div></div>
<div style="border: 1px solid #2a2c30; border-radius: 8px; overflow: hidden">
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; padding: 8px 12px; font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: #8f8c85; background: #17181a; border-bottom: 1px solid #2a2c30"><span>State</span><span>Label</span><span></span></div>
<sc-for list="{{labels}}" as="l" hint-placeholder-count="6">
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: {{l.color}}"></span>{{l.state}}</span>
<input class="inp" aria-label="{{l.state}} label" value="{{l.label}}" style="width: 100%; height: 32px">
<button class="icon-btn" aria-label="Remove {{l.state}}"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
</div>
</sc-for>
<button style="display: flex; align-items: center; gap: 6px; width: 100%; height: 38px; padding: 0 12px; border: 0; background: transparent; color: #a6a39b; font: 500 13px 'IBM Plex Sans', sans-serif; cursor: pointer"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>Add state</button>
</div>
</div>
<h2 style="margin: 36px 0 4px; font-size: 13px; font-weight: 600; color: #a6a39b; text-transform: uppercase; letter-spacing: 0.06em">Retries &amp; polling</h2>
<div class="row">
<div><label class="lbl" for="retries">Max retries</label><div class="hint">Attempts before an item is labelled dead.</div></div>
<div style="display: inline-flex; align-self: flex-start; border: 1px solid #2e3034; border-radius: 6px; overflow: hidden; width: fit-content">
<button class="icon-btn" aria-label="Decrease" style="border-radius: 0">−</button>
<input id="retries" class="inp" value="3" style="width: 56px; border: 0; border-radius: 0; text-align: center; border-left: 1px solid #2e3034; border-right: 1px solid #2e3034">
<button class="icon-btn" aria-label="Increase" style="border-radius: 0">+</button>
</div>
</div>
<div class="row">
<div><label class="lbl" for="poll">Poll interval</label><div class="hint">How often the tracker is checked for new work.</div></div>
<div style="display: flex; align-items: center; gap: 10px">
<div style="display: flex">
<input id="poll" class="inp" value="30" style="width: 80px; border-radius: 6px 0 0 6px; border-color: {{accent}}">
<select aria-label="Poll unit" class="inp" style="border-radius: 0 6px 6px 0; border-left: 0; font-family: 'IBM Plex Sans', sans-serif"><option>seconds</option><option>minutes</option></select>
</div>
<span style="font-size: 12px; color: #8f8c85">was <span style="font-family: 'IBM Plex Mono', monospace; text-decoration: line-through">1m0s</span></span>
</div>
</div>
</div>
</main>
</div>
<div style="position: absolute; left: 264px; right: 0; bottom: 0; height: 72px; box-sizing: border-box; padding: 0 56px; display: flex; align-items: center; gap: 12px; background: #17181a; border-top: 1px solid #2a2c30">
<span style="width: 8px; height: 8px; border-radius: 50%; background: {{accent}}"></span>
<span style="font-size: 13px">1 unsaved change</span>
<span style="font-size: 13px; color: #8f8c85">· Poll interval</span>
<div style="flex-grow: 1"></div>
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard</button>
<button class="btn btn-primary">Save &amp; restart</button>
</div>
</div>
</x-dc>
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1040}}'>
class Component extends DCLogic {
renderVals() {
return {
accent: this.props.accent ?? '#86b5a0',
labels: [
{ state: 'queued', label: 'agent:queued', color: '#8f8c85' },
{ state: 'working', label: 'agent:working', color: '#8aa4c2' },
{ state: 'waiting', label: 'agent:waiting', color: '#d9a45b' },
{ state: 'pr', label: 'agent:pr', color: '#86b5a0' },
{ state: 'parked', label: 'agent:parked', color: '#6f6c66' },
{ state: 'dead', label: 'agent:dead', color: '#d9776b' }
]
};
}
}
</script>
</body>
</html>
@@ -1,146 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Settings – personas</title>
<script src="./support.js"></script>
</head>
<body>
<x-dc>
<helmet>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none}
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.tab{height:44px;display:flex;align-items:center;padding:0 2px;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
</style>
</helmet>
<div style="--accent: {{accent}}; width: 1440px; height: 1040px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
Archie
</div>
<nav style="display: flex; gap: 4px; font-size: 13px">
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Work</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">System</a>
</nav>
<div style="flex-grow: 1"></div>
<div style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b; padding: 6px 10px; border: 1px solid #2a2c30; border-radius: 999px">
<span style="width: 7px; height: 7px; border-radius: 50%; background: {{accent}}"></span>
Connected · v1
</div>
</header>
<div style="padding: 32px 48px 0; border-bottom: 1px solid #232529; flex-shrink: 0">
<div style="font-size: 12px; color: #8f8c85">System / Advanced</div>
<h1 style="margin: 6px 0 20px; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Advanced settings</h1>
<nav style="display: flex; gap: 28px">
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: {{accent}}">Personas</a>
<a class="tab" href="#">Schedules</a>
<a class="tab" href="#">Scheduling policy</a>
<a class="tab" href="#">Tools &amp; MCP</a>
<a class="tab" href="#">Plugins</a>
<a class="tab" href="#">Container runtime</a>
</nav>
</div>
<div style="display: flex; flex-grow: 1; min-height: 0; padding: 32px 48px 40px; gap: 32px">
<section aria-label="Persona list" style="width: 340px; flex-shrink: 0; display: flex; flex-direction: column; gap: 12px">
<div style="display: flex; align-items: center; gap: 8px">
<label style="flex-grow: 1; display: flex; align-items: center; gap: 8px; height: 36px; padding: 0 12px; border: 1px solid #2e3034; border-radius: 6px; color: #8f8c85">
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg>
<input aria-label="Filter personas" placeholder="Filter personas" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: 13px 'IBM Plex Sans', sans-serif; width: 100%">
</label>
<button class="btn" aria-label="New persona" style="padding: 0 12px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New</button>
</div>
<div style="border: 1px solid #2a2c30; border-radius: 10px; overflow: hidden; background: #16171a">
<sc-for list="{{personas}}" as="p" hint-placeholder-count="6">
<a href="#" style="display: flex; flex-direction: column; gap: 4px; padding: 14px 16px; border-bottom: 1px solid #222428; background: {{p.bg}}; box-shadow: {{p.shadow}}">
<span style="display: flex; align-items: center; gap: 8px; font-size: 14px; font-weight: 500">{{p.name}}
<sc-if value="{{p.isDefault}}" hint-placeholder-val="{{false}}"><span style="font-size: 11px; font-weight: 500; color: {{accent}}; border: 1px solid {{accent}}; border-radius: 999px; padding: 1px 8px">default</span></sc-if>
</span>
<span style="font-size: 12px; color: #8f8c85; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">{{p.prompt}}</span>
</a>
</sc-for>
</div>
<div class="hint">Personas are system prompts an agent can adopt. The default is used when a work item doesn't specify one.</div>
</section>
<section aria-label="Edit persona" style="flex-grow: 1; display: flex; flex-direction: column; border: 1px solid #2a2c30; border-radius: 10px; background: #16171a; overflow: hidden">
<div style="display: flex; align-items: center; gap: 12px; padding: 18px 24px; border-bottom: 1px solid #2a2c30">
<h2 style="margin: 0; font-size: 18px; font-weight: 600">archie</h2>
<span style="font-size: 11px; color: {{accent}}; border: 1px solid {{accent}}; border-radius: 999px; padding: 1px 8px">default</span>
<div style="flex-grow: 1"></div>
<button class="btn" style="background: transparent">Duplicate</button>
<button class="btn" style="background: transparent; color: #d9776b; border-color: #3a2a28">Delete</button>
</div>
<div style="display: flex; flex-direction: column; gap: 24px; padding: 24px; flex-grow: 1">
<div style="display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 24px">
<div style="display: flex; flex-direction: column; gap: 8px">
<label class="lbl" for="pname">Name</label>
<input id="pname" class="inp" value="archie">
<span class="hint">Lowercase, used as the persona key.</span>
</div>
<div style="display: flex; flex-direction: column; gap: 8px">
<span class="lbl">Default persona</span>
<label style="display: flex; align-items: center; gap: 10px; height: 36px; font-size: 13px; color: #a6a39b">
<span style="width: 36px; height: 20px; border-radius: 999px; background: {{accent}}; position: relative; display: inline-block"><span style="position: absolute; right: 2px; top: 2px; width: 16px; height: 16px; border-radius: 50%; background: #121314"></span></span>
Use when no persona is specified
</label>
</div>
</div>
<div style="display: flex; flex-direction: column; gap: 8px; flex-grow: 1">
<div style="display: flex; align-items: baseline"><label class="lbl" for="prompt">System prompt</label><span class="hint" style="margin-left: auto; font-family: 'IBM Plex Mono', monospace">312 chars · ~70 tokens</span></div>
<textarea id="prompt" style="flex-grow: 1; min-height: 320px; box-sizing: border-box; padding: 16px; background: #121314; border: 1px solid #2e3034; border-radius: 8px; color: #e8e6e1; font: 400 13px/1.7 'IBM Plex Mono', monospace; resize: vertical; outline: none">You are Archie, a capable coding and project assistant. Be direct without being brusque, grounded in the actual workspace state, and use available tools when asked. Do not claim tools, files, memories, actions, or results you have not verified. Do not impersonate another assistant, provider, or vendor.</textarea>
</div>
<div style="display: flex; align-items: center; gap: 12px; padding: 14px 16px; border: 1px dashed #2e3034; border-radius: 8px">
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><path d="M4 12h12M12 6l6 6-6 6"></path></svg>
<span style="font-size: 13px; color: #a6a39b; flex-grow: 1">Try this persona against a sample message before saving</span>
<button class="btn">Open preview</button>
</div>
</div>
<div style="display: flex; align-items: center; gap: 12px; padding: 16px 24px; border-top: 1px solid #2a2c30; background: #17181a">
<span style="font-size: 12px; color: #8f8c85">Saved · version 1 · <a href="#" style="color: #a6a39b; text-decoration: underline">History</a></span>
<div style="flex-grow: 1"></div>
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard</button>
<button class="btn btn-primary">Save persona</button>
</div>
</section>
</div>
</div>
</x-dc>
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1040}}'>
class Component extends DCLogic {
renderVals() {
const accent = this.props.accent ?? '#86b5a0';
const list = [
['archie', 'You are Archie, a capable coding and project assistant. Be direct without being brusque…', true],
['helpful', 'You are a helpful, friendly AI assistant.', false],
['concise', 'You are a concise assistant. Keep responses brief and to the point.', false],
['technical', 'You are a technical expert. Provide detailed, accurate technical information.', false],
['creative', 'You are a creative assistant. Think outside the box and offer innovative solutions.', false],
['teacher', 'You are a patient teacher. Explain concepts clearly with examples.', false]
];
return {
accent,
personas: list.map(([name, prompt, isDefault], i) => ({
name, prompt, isDefault,
bg: i === 0 ? '#1e2023' : 'transparent',
shadow: i === 0 ? 'inset 2px 0 0 ' + accent : 'none'
}))
};
}
}
</script>
</body>
</html>
@@ -1,155 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Settings – tools and MCP</title>
<script src="./support.js"></script>
</head>
<body>
<x-dc>
<helmet>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column}
.card-h{display:flex;align-items:center;gap:12px;padding:18px 20px;border-bottom:1px solid #232529}
.card-b{padding:20px;display:flex;flex-direction:column;gap:18px}
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.field{display:flex;flex-direction:column;gap:6px}
.sw{width:36px;height:20px;border-radius:999px;position:relative;display:inline-block;flex-shrink:0}
.sw i{position:absolute;top:2px;width:16px;height:16px;border-radius:50%}
.nav-item{display:flex;align-items:center;gap:10px;height:36px;padding:0 12px;border-radius:6px;color:#a6a39b;font-size:13px}
</style>
</helmet>
<div style="--accent: {{accent}}; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
Archie
</div>
<nav style="display: flex; gap: 4px; font-size: 13px">
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Tasks</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Workflows</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">Settings</a>
</nav>
<div style="flex-grow: 1"></div>
<div style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b; padding: 6px 10px; border: 1px solid #2a2c30; border-radius: 999px">
<span style="width: 7px; height: 7px; border-radius: 50%; background: {{accent}}"></span>
Connected · v1
</div>
</header>
<div style="display: flex; flex-grow: 1; min-height: 0">
<aside style="width: 232px; flex-shrink: 0; box-sizing: border-box; padding: 24px 12px; border-right: 1px solid #232529; display: flex; flex-direction: column; gap: 2px">
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 0 12px 8px">Agents</div>
<a class="nav-item" href="#">Personas</a>
<a class="nav-item" href="#">Schedules</a>
<a class="nav-item" href="#">Scheduling policy</a>
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Integrations</div>
<a class="nav-item" href="#">Channels</a>
<a class="nav-item" href="#" style="background: #1e2023; color: #e8e6e1; box-shadow: inset 2px 0 0 {{accent}}">Tools &amp; MCP</a>
<a class="nav-item" href="#">Plugins</a>
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Runtime</div>
<a class="nav-item" href="#">Container runtime</a>
<div style="height: 1px; background: #232529; margin: 16px 12px"></div>
<a class="nav-item" href="#">History</a>
</aside>
<main style="flex-grow: 1; padding: 36px 48px; overflow: hidden">
<div style="display: flex; align-items: flex-end; gap: 16px; margin-bottom: 28px">
<div style="flex-grow: 1">
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Tools &amp; MCP</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">External tools, model providers and fetch limits available to agents.</p>
</div>
<button class="btn btn-primary"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>Add MCP server</button>
</div>
<div style="display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 20px">
<section class="card" style="grid-column: span 2">
<div class="card-h">
<div style="width: 32px; height: 32px; border-radius: 8px; background: #1e2023; display: flex; align-items: center; justify-content: center"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><rect x="3" y="4" width="18" height="6" rx="1"></rect><rect x="3" y="14" width="18" height="6" rx="1"></rect><path d="M7 7h.01M7 17h.01"></path></svg></div>
<div style="flex-grow: 1"><div class="lbl" style="font-size: 15px">MCP servers</div><div class="hint">Model Context Protocol servers agents can call.</div></div>
</div>
<div style="display: flex; align-items: center; gap: 20px; padding: 28px 20px">
<div style="flex-grow: 1">
<div style="font-size: 14px; color: #e8e6e1">No MCP servers yet</div>
<div class="hint" style="margin-top: 4px">Add a stdio command or an HTTP endpoint. Agents see its tools on next restart.</div>
</div>
<button class="btn">stdio command</button>
<button class="btn">HTTP / SSE endpoint</button>
</div>
</section>
<section class="card">
<div class="card-h">
<div style="width: 32px; height: 32px; border-radius: 8px; background: #1e2023; display: flex; align-items: center; justify-content: center; font: 600 13px 'IBM Plex Mono', monospace; color: #a6a39b">Mx</div>
<div style="flex-grow: 1"><div class="lbl" style="font-size: 15px">MiniMax</div><div class="hint">Model provider</div></div>
<label style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b">Enabled<span class="sw" style="background: {{accent}}"><i style="right: 2px; background: #121314"></i></span></label>
</div>
<div class="card-b">
<div class="field">
<span class="lbl">API key</span>
<div style="display: flex; align-items: center; gap: 10px; height: 40px; padding: 0 12px; border: 1px solid #2e3034; border-radius: 6px; background: #121314">
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><rect x="4" y="10" width="16" height="10" rx="2"></rect><path d="M8 10V7a4 4 0 0 1 8 0v3"></path></svg>
<span style="font: 12px 'IBM Plex Mono', monospace; color: #8f8c85">bws</span>
<span style="color: #4a4c50">/</span>
<span style="font: 13px 'IBM Plex Mono', monospace">MINIMAX_API_KEY</span>
<div style="flex-grow: 1"></div>
<button class="btn" style="height: 28px; padding: 0 10px; font-size: 12px; background: transparent">Change</button>
</div>
<div style="display: flex; align-items: center; gap: 6px; font-size: 12px; color: {{accent}}"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2"><path d="m5 12 5 5 9-10"></path></svg>Credential resolved by Archie</div>
</div>
</div>
</section>
<section class="card">
<div class="card-h">
<div style="width: 32px; height: 32px; border-radius: 8px; background: #1e2023; display: flex; align-items: center; justify-content: center"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><circle cx="12" cy="12" r="9"></circle><path d="M3 12h18M12 3c3 3 3 15 0 18M12 3c-3 3-3 15 0 18"></path></svg></div>
<div style="flex-grow: 1"><div class="lbl" style="font-size: 15px">Web fetch</div><div class="hint">Let agents download pages and files</div></div>
<label style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b">Enabled<span class="sw" style="background: {{accent}}"><i style="right: 2px; background: #121314"></i></span></label>
</div>
<div class="card-b">
<div style="display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 16px">
<div class="field"><label class="lbl" for="mb">Max download</label><div style="display: flex"><input id="mb" class="inp" value="2" style="border-radius: 6px 0 0 6px"><span style="display: flex; align-items: center; padding: 0 12px; border: 1px solid #2e3034; border-left: 0; border-radius: 0 6px 6px 0; font-size: 12px; color: #8f8c85">MB</span></div></div>
<div class="field"><label class="lbl" for="to">Timeout</label><div style="display: flex"><input id="to" class="inp" value="30" style="border-radius: 6px 0 0 6px"><span style="display: flex; align-items: center; padding: 0 12px; border: 1px solid #2e3034; border-left: 0; border-radius: 0 6px 6px 0; font-size: 12px; color: #8f8c85">sec</span></div></div>
</div>
<label style="display: flex; align-items: flex-start; gap: 12px; padding: 12px; border: 1px solid #2a2c30; border-radius: 8px">
<span class="sw" style="background: #2e3034; margin-top: 2px"><i style="left: 2px; background: #8f8c85"></i></span>
<span><span class="lbl">Allow private networks</span><span class="hint" style="display: block">Off: requests to 10.x, 192.168.x and localhost are blocked.</span></span>
</label>
</div>
</section>
<section class="card" style="grid-column: span 2">
<div class="card-h">
<div style="flex-grow: 1"><div class="lbl" style="font-size: 15px">Tool output policy</div><div class="hint">Large tool results are truncated or spilled to disk.</div></div>
</div>
<div class="card-b" style="display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 24px">
<div class="field"><label class="lbl" for="mrc">Max result length</label><div style="display: flex"><input id="mrc" class="inp" value="50,000" style="border-radius: 6px 0 0 6px"><span style="display: flex; align-items: center; padding: 0 12px; border: 1px solid #2e3034; border-left: 0; border-radius: 0 6px 6px 0; font-size: 12px; color: #8f8c85; white-space: nowrap">chars</span></div><span class="hint">About 12k tokens per tool call.</span></div>
<div class="field"><label class="lbl" for="spill">Spill directory</label><input id="spill" class="inp" placeholder="Not set — results over the limit are truncated"><span class="hint">Full output is written here and the agent gets a path.</span></div>
</div>
</section>
</div>
</main>
</div>
</div>
</x-dc>
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1080}}'>
class Component extends DCLogic {
renderVals() {
return { accent: this.props.accent ?? '#86b5a0' };
}
}
</script>
</body>
</html>
@@ -1,123 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Settings – review changes</title>
<script src="./support.js"></script>
</head>
<body>
<x-dc>
<helmet>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.acc{display:flex;align-items:center;gap:14px;padding:16px 20px;border:1px solid #2a2c30;border-radius:10px;background:#16171a}
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.sum{font:12px 'IBM Plex Mono',monospace;color:#8f8c85}
.field{display:flex;flex-direction:column;gap:6px}
.chev{color:#8f8c85}
</style>
</helmet>
<div style="--accent: {{accent}}; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden; position: relative">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
Archie
</div>
<nav style="display: flex; gap: 4px; font-size: 13px">
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Work</a>
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">System</a>
</nav>
</header>
<main style="width: 880px; padding: 36px 0 0 64px; display: flex; flex-direction: column; gap: 12px">
<h1 style="margin: 0 0 4px; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Advanced settings</h1>
<p style="margin: 0 0 16px; font-size: 14px; color: #a6a39b">Collapsed sections show their current values at a glance.</p>
<div class="acc"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Personas</span><span class="sum" style="flex-grow: 1">6 personas · default archie</span></div>
<div class="acc"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Schedules</span><span class="sum" style="flex-grow: 1">none</span></div>
<div class="acc" style="border-color: #3a3f3c"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Scheduling policy</span><span class="sum" style="flex-grow: 1">trigger assignee · 3 retries · poll 30s</span><span style="font-size: 11px; color: {{accent}}">1 edited</span></div>
<div class="acc"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Tools &amp; MCP</span><span class="sum" style="flex-grow: 1">0 MCP · MiniMax on · web fetch on</span></div>
<div class="acc"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Plugins</span><span class="sum" style="flex-grow: 1">all directories default</span></div>
<section style="border: 1px solid #3a3f3c; border-radius: 10px; background: #16171a">
<div style="display: flex; align-items: center; gap: 14px; padding: 16px 20px; border-bottom: 1px solid #232529">
<svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 9 6 6 6-6"></path></svg>
<span class="lbl" style="flex-grow: 1">Container runtime</span>
<span style="font-size: 11px; color: {{accent}}">2 edited</span>
</div>
<div style="padding: 20px; display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 18px 24px">
<div class="field" style="grid-column: span 2"><label class="lbl" for="img">Image</label><input id="img" class="inp" value="ghcr.io/samcharles93/archie-agent:latest"></div>
<div class="field"><label class="lbl" for="mc">Max concurrency</label><input id="mc" class="inp" value="6" style="border-color: {{accent}}"></div>
<div class="field"><label class="lbl" for="mu">Max uptime</label><input id="mu" class="inp" value="2h" style="border-color: {{accent}}"></div>
<div class="field"><label class="lbl" for="net">Network</label><input id="net" class="inp" value="archie-core_default"></div>
<div class="field"><label class="lbl" for="pp">Pull policy</label><select id="pp" class="inp" style="font-family: 'IBM Plex Sans', sans-serif"><option>If missing</option><option>Always</option><option>Never</option></select></div>
<div class="field"><label class="lbl" for="vt">Volume TTL</label><input id="vt" class="inp" value="72h"></div>
<div class="field"><label class="lbl" for="pr">Profiles</label><input id="pr" class="inp" placeholder="None"></div>
</div>
</section>
</main>
<div style="position: absolute; left: 0; top: 56px; right: 0; bottom: 0; background: rgba(8,9,10,0.55)"></div>
<aside aria-label="Review changes" style="position: absolute; top: 56px; right: 0; bottom: 0; width: 480px; box-sizing: border-box; background: #17181a; border-left: 1px solid #2a2c30; display: flex; flex-direction: column; box-shadow: -24px 0 48px rgba(0,0,0,0.35)">
<div style="display: flex; align-items: center; padding: 20px 24px; border-bottom: 1px solid #2a2c30">
<div style="flex-grow: 1"><h2 style="margin: 0; font-size: 17px; font-weight: 600">Review 3 changes</h2><div class="hint" style="margin-top: 2px">Saved together as config version 2</div></div>
<button aria-label="Close" style="width: 36px; height: 36px; border: 0; background: transparent; color: #8f8c85; cursor: pointer"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 6l12 12M18 6 6 18"></path></svg></button>
</div>
<div style="flex-grow: 1; padding: 20px 24px; display: flex; flex-direction: column; gap: 20px">
<div style="display: flex; gap: 10px; padding: 12px 14px; border-radius: 8px; background: rgba(217,164,91,0.08); border: 1px solid rgba(217,164,91,0.25); color: #e3c08f; font-size: 13px; line-height: 1.5">
<svg style="flex-shrink: 0; margin-top: 2px" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a9 9 0 1 1-3-6.7L21 8"></path><path d="M21 3v5h-5"></path></svg>
<span>All three need an archie-core restart. 2 agents are running; they'll finish before the restart.</span>
</div>
<sc-for list="{{groups}}" as="g" hint-placeholder-count="2">
<div style="display: flex; flex-direction: column; gap: 8px">
<div style="font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: #8f8c85">{{g.section}}</div>
<sc-for list="{{g.items}}" as="c" hint-placeholder-count="2">
<div style="border: 1px solid #2a2c30; border-radius: 8px; overflow: hidden">
<div style="display: flex; align-items: center; padding: 10px 14px; font-size: 13px; font-weight: 500"><span style="flex-grow: 1">{{c.field}}</span><a href="#" style="font-size: 12px; font-weight: 400; color: #8f8c85; text-decoration: underline">Revert</a></div>
<div style="font: 12px/1.9 'IBM Plex Mono', monospace; border-top: 1px solid #232529">
<div style="padding: 0 14px; background: rgba(217,119,107,0.08); color: #e0a39a">− {{c.from}}</div>
<div style="padding: 0 14px; background: rgba(134,181,160,0.10); color: #a9d1bf">+ {{c.to}}</div>
</div>
</div>
</sc-for>
</div>
</sc-for>
</div>
<div style="display: flex; align-items: center; gap: 12px; padding: 16px 24px; border-top: 1px solid #2a2c30">
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard all</button>
<div style="flex-grow: 1"></div>
<button class="btn">Save only</button>
<button class="btn btn-primary">Save &amp; restart</button>
</div>
</aside>
</div>
</x-dc>
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1080}}'>
class Component extends DCLogic {
renderVals() {
return {
accent: this.props.accent ?? '#86b5a0',
groups: [
{ section: 'Scheduling policy', items: [{ field: 'Poll interval', from: '1m0s', to: '30s' }] },
{ section: 'Container runtime', items: [
{ field: 'Max concurrency', from: '4', to: '6' },
{ field: 'Max uptime', from: '1h0m0s', to: '2h0m0s' }
] }
]
};
}
}
</script>
</body>
</html>
@@ -1,165 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Settings – channels</title>
<script src="./support.js"></script>
</head>
<body>
<x-dc>
<helmet>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
.btn-sm{height:30px;padding:0 10px;font-size:12px}
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
.card-h{display:flex;align-items:center;gap:12px;padding:16px 20px;border-bottom:1px solid #232529}
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
.lbl{font-size:13px;font-weight:500}
.eyebrow{font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:#8f8c85;font-weight:500}
.mono{font-family:'IBM Plex Mono',monospace}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
.nav a.on{color:#e8e6e1;background:#1e2023}
.nav-item{display:flex;align-items:center;gap:10px;height:34px;padding:0 12px;border-radius:6px;color:#a6a39b;font-size:13px}
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
.row{display:grid;grid-template-columns:260px minmax(0,1fr);gap:32px;padding:16px 20px;border-top:1px solid #232529}
.sw{width:36px;height:20px;border-radius:999px;position:relative;display:inline-block;flex-shrink:0}
.sw i{position:absolute;top:2px;width:16px;height:16px;border-radius:50%}
.icon{width:32px;height:32px;border-radius:8px;background:#1e2023;display:flex;align-items:center;justify-content:center;flex-shrink:0}
</style>
</helmet>
<div style="--accent: {{accent}}; width: 1440px; height: 1300px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#" class="on">Settings</a></nav>
<div style="flex-grow: 1"></div>
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
<span class="pill"><span class="dot" style="background: {{accent}}"></span>Connected</span>
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
</header>
<div style="display: flex; flex-grow: 1; min-height: 0">
<aside style="width: 248px; flex-shrink: 0; box-sizing: border-box; padding: 24px 14px; border-right: 1px solid #232529; display: flex; flex-direction: column; gap: 2px">
<div class="eyebrow" style="padding: 0 12px 8px">Agents</div>
<a class="nav-item" href="#">Personas</a><a class="nav-item" href="#">Schedules</a><a class="nav-item" href="#">Scheduling policy</a>
<div class="eyebrow" style="padding: 18px 12px 8px">Integrations</div>
<a class="nav-item" href="#" style="background: #1e2023; color: #e8e6e1; box-shadow: inset 2px 0 0 {{accent}}">Channels<span class="dot" style="margin-left: auto; background: {{accent}}" title="1 running"></span></a>
<a class="nav-item" href="#">Tools &amp; MCP</a><a class="nav-item" href="#">Plugins</a>
<div class="eyebrow" style="padding: 18px 12px 8px">Runtime</div>
<a class="nav-item" href="#">Container runtime</a>
<div style="height: 1px; background: #232529; margin: 16px 12px"></div>
<a class="nav-item" href="#"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="9"></circle><path d="M12 7v5l3 2"></path></svg>History</a>
</aside>
<main style="flex-grow: 1; padding: 36px 56px; display: flex; flex-direction: column; gap: 24px; min-width: 0">
<div style="display: flex; align-items: flex-start; gap: 16px; max-width: 980px">
<div style="flex-grow: 1">
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Channels</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Where you talk to Archie, and how chat sessions behave.</p>
</div>
<span class="pill" style="color: #d9a45b; border-color: rgba(217,164,91,.3); background: rgba(217,164,91,.08)">Applies after restart</span>
</div>
<div style="max-width: 980px; display: flex; flex-direction: column; gap: 16px">
<section class="card">
<div class="card-h">
<div class="icon"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><path d="m22 3-9.5 18-2.5-8-8-2.5L22 3Z"></path></svg></div>
<div style="flex-grow: 1"><div style="font-size: 15px; font-weight: 500">Telegram</div><div class="hint">Talk to Archie and approve its work from your phone.</div></div>
<span class="pill" style="color: {{accent}}; border-color: {{accent}}"><span class="dot" style="background: {{accent}}"></span>Running</span>
</div>
<div class="row" style="border-top: 0">
<div><div class="lbl">Bot token</div><div class="hint">Secret reference for the Telegram bot.</div></div>
<div>
<div style="display: flex; align-items: center; gap: 10px; height: 38px; padding: 0 12px; border: 1px solid #2e3034; border-radius: 6px; background: #121314">
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><rect x="4" y="10" width="16" height="10" rx="2"></rect><path d="M8 10V7a4 4 0 0 1 8 0v3"></path></svg>
<span class="mono" style="font-size: 12px; color: #8f8c85">env</span><span style="color: #4a4c50">/</span><span class="mono" style="font-size: 13px">HEYARCHIE_TELEGRAM_BOT_TOKEN</span>
<div style="flex-grow: 1"></div><button class="btn btn-sm" style="height: 26px; background: transparent">Change</button>
</div>
<div style="display: flex; align-items: center; gap: 6px; font-size: 12px; color: {{accent}}; margin-top: 6px"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2"><path d="m5 12 5 5 9-10"></path></svg>Credential resolved by Archie</div>
</div>
</div>
<div class="row">
<div><div class="lbl">Allowed users</div><div class="hint">Telegram user IDs that may talk to Archie. Everyone else is ignored.</div></div>
<div style="display: flex; flex-wrap: wrap; align-items: center; gap: 8px; padding: 6px; border: 1px solid #2e3034; border-radius: 6px; background: #121314; min-height: 38px; box-sizing: border-box">
<span style="display: inline-flex; align-items: center; gap: 6px; height: 26px; padding: 0 6px 0 10px; border-radius: 4px; background: #1e2023; font: 12px 'IBM Plex Mono', monospace">1312197967<button aria-label="Remove 1312197967" style="width: 20px; height: 20px; border: 0; background: transparent; color: #8f8c85; cursor: pointer">×</button></span>
<input aria-label="Add user ID" placeholder="Add user ID…" style="flex-grow: 1; min-width: 140px; background: transparent; border: 0; outline: none; color: #e8e6e1; font: 12px 'IBM Plex Mono', monospace">
</div>
</div>
</section>
<sc-for list="{{inactive}}" as="c" hint-placeholder-count="2">
<section class="card" style="flex-direction: row; align-items: center; gap: 12px; padding: 16px 20px">
<div class="icon"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><path d="{{c.icon}}"></path></svg></div>
<div style="flex-grow: 1"><div style="font-size: 15px; font-weight: 500">{{c.name}}</div><div class="hint">{{c.sub}}</div></div>
<span class="pill">Not set up</span>
<button class="btn btn-sm">Set up</button>
</section>
</sc-for>
<div class="eyebrow" style="margin-top: 16px">Chat session defaults · all channels</div>
<section class="card">
<div class="row" style="border-top: 0">
<div><label class="lbl" for="ws">Workspace</label><div class="hint">Directory chat sessions start in.</div></div>
<input id="ws" class="inp" value="/home/sam">
</div>
<div class="row">
<div><div class="lbl">Filesystem access</div><div class="hint">Outside the workspace.</div></div>
<div style="display: flex; align-items: flex-start; gap: 12px; padding: 12px; border: 1px solid rgba(217,119,107,.35); background: rgba(217,119,107,.06); border-radius: 8px">
<span class="sw" style="background: #d9776b; margin-top: 2px"><i style="right: 2px; background: #121314"></i></span>
<span><span class="lbl">Unrestricted filesystem</span><span class="hint" style="display: block; color: #e0a39a">On: agents can read and write anywhere this user can.</span></span>
</div>
</div>
<div class="row">
<div><div class="lbl">Show tool calls</div><div class="hint">Post each tool call into the chat.</div></div>
<label style="display: flex; align-items: center; gap: 10px; font-size: 13px; color: #a6a39b"><span class="sw" style="background: {{accent}}"><i style="right: 2px; background: #121314"></i></span>On</label>
</div>
<div class="row">
<div><label class="lbl" for="ms">Max steps</label><div class="hint">Per chat turn. 0 = no limit.</div></div>
<input id="ms" class="inp" value="0" style="width: 120px">
</div>
<div class="row">
<div><div class="lbl">Rate limit</div><div class="hint">Off while either value is 0.</div></div>
<div style="display: flex; align-items: center; gap: 10px; font-size: 13px; color: #a6a39b"><input aria-label="Max requests" class="inp" value="0" style="width: 90px"> requests per <input aria-label="Window" class="inp" value="0" style="width: 80px"><select aria-label="Window unit" class="inp" style="width: 110px; font-family: 'IBM Plex Sans', sans-serif"><option>minutes</option></select></div>
</div>
<div class="row">
<div><label class="lbl" for="md">Models</label><div class="hint">Models chat sessions may use.</div></div>
<input id="md" class="inp" placeholder="Default">
</div>
<div class="row">
<div><label class="lbl" for="op">Operator</label><div class="hint">Who Archie treats as its operator.</div></div>
<input id="op" class="inp" placeholder="Not set">
</div>
</section>
<div style="display: flex; align-items: center; gap: 10px; font-size: 12px; color: #8f8c85">
<svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="9"></circle><path d="M12 7v5l3 2"></path></svg>
Version 1 · 11 fields set by <span class="mono">system:migration</span> 8 hrs ago · <a href="#" style="color: #a6a39b; text-decoration: underline">View in History</a>
</div>
</div>
</main>
</div>
</div>
</x-dc>
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1300}}'>
class Component extends DCLogic {
renderVals() {
return {
accent: this.props.accent ?? '#86b5a0',
inactive: [
{ name: 'Email', sub: 'Listen for mail and relay replies.', icon: 'M3 6h18v12H3zM3 6l9 7 9-7' },
{ name: 'Webhook', sub: 'Deliver agent output to a URL, with a signing secret and template.', icon: 'M10 13a5 5 0 0 0 7 0l3-3a5 5 0 0 0-7-7l-1 1M14 11a5 5 0 0 0-7 0l-3 3a5 5 0 0 0 7 7l1-1' }
]
};
}
}
</script>
</body>
</html>
@@ -1,120 +0,0 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Theme and components</title>
<script src="./support.js"></script>
</head>
<body>
<x-dc>
<helmet>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&amp;family=IBM+Plex+Sans:wght@400;500;600&amp;display=swap" rel="stylesheet">
<style>
body{margin:0;background:#121314}
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px}
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
.h{font-size:11px;text-transform:uppercase;letter-spacing:0.08em;color:#8f8c85;margin:0 0 14px;font-weight:500}
.panel{border:1px solid #2a2c30;border-radius:10px;background:#16171a;padding:24px}
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:4px 10px;border-radius:999px;border:1px solid}
.dot{width:7px;height:7px;border-radius:50%}
.sw{width:36px;height:20px;border-radius:999px;position:relative;display:inline-block}
.sw i{position:absolute;top:2px;width:16px;height:16px;border-radius:50%}
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
.hint{font-size:12px;color:#8f8c85}
</style>
</helmet>
<div style="--accent: {{accent}}; width: 1440px; height: 980px; box-sizing: border-box; padding: 48px 56px; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; display: flex; flex-direction: column; gap: 24px">
<div>
<h1 style="margin: 0; font-size: 28px; font-weight: 600; letter-spacing: -0.01em">Graphite theme</h1>
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Warm neutral greys carry the page; one low-chroma accent marks the active item, focus and primary action.</p>
</div>
<div style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 24px">
<section class="panel">
<h2 class="h">Palette</h2>
<div style="display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 10px">
<sc-for list="{{swatches}}" as="s" hint-placeholder-count="8">
<div style="display: flex; flex-direction: column; gap: 6px">
<div style="height: 44px; border-radius: 6px; background: {{s.hex}}; border: 1px solid #2e3034"></div>
<span style="font-size: 12px">{{s.name}}</span>
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">{{s.hex}}</span>
</div>
</sc-for>
</div>
<h2 class="h" style="margin-top: 24px">Type</h2>
<div style="display: flex; flex-direction: column; gap: 8px">
<span style="font-size: 24px; font-weight: 600">IBM Plex Sans 600 · 24</span>
<span style="font-size: 14px; color: #a6a39b">IBM Plex Sans 400 · 14 body</span>
<span style="font: 13px 'IBM Plex Mono', monospace">IBM Plex Mono · values, keys, durations</span>
</div>
</section>
<section class="panel">
<h2 class="h">Buttons</h2>
<div style="display: flex; gap: 10px; flex-wrap: wrap">
<button class="btn btn-primary">Save &amp; restart</button>
<button class="btn">Secondary</button>
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard</button>
<button class="btn" style="background: transparent; color: #d9776b; border-color: #3a2a28">Delete</button>
</div>
<h2 class="h" style="margin-top: 24px">Status</h2>
<div style="display: flex; gap: 8px; flex-wrap: wrap">
<span class="pill" style="color: #a6a39b; border-color: #2e3034"><span class="dot" style="background: {{accent}}"></span>Connected</span>
<span class="pill" style="color: #a6a39b; border-color: #2e3034"><span class="dot" style="background: #d9a45b"></span>Connecting…</span>
<span class="pill" style="color: #d9a45b; border-color: rgba(217,164,91,0.3); background: rgba(217,164,91,0.08)">Applies after restart</span>
<span class="pill" style="color: {{accent}}; border-color: {{accent}}">2 edited</span>
<span class="pill" style="color: #e0a39a; border-color: rgba(217,119,107,0.35); background: rgba(217,119,107,0.08)">Invalid duration</span>
</div>
<h2 class="h" style="margin-top: 24px">Toggles &amp; choice</h2>
<div style="display: flex; align-items: center; gap: 20px">
<label style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span class="sw" style="background: {{accent}}"><i style="right: 2px; background: #121314"></i></span>On</label>
<label style="display: flex; align-items: center; gap: 8px; font-size: 13px; color: #a6a39b"><span class="sw" style="background: #2e3034"><i style="left: 2px; background: #8f8c85"></i></span>Off</label>
<div style="display: inline-flex; padding: 3px; background: #121314; border: 1px solid #2e3034; border-radius: 8px">
<button style="height: 28px; padding: 0 12px; border: 0; border-radius: 5px; background: #26282c; color: #e8e6e1; font: 500 12px 'IBM Plex Sans', sans-serif">Assignee</button>
<button style="height: 28px; padding: 0 12px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 12px 'IBM Plex Sans', sans-serif">Label</button>
</div>
</div>
</section>
<section class="panel" style="display: flex; flex-direction: column; gap: 16px">
<h2 class="h" style="margin: 0">Inputs</h2>
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="c1">Text</label><input id="c1" class="inp" value="archie-core_default"></div>
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="c2">Focused</label><input id="c2" class="inp" value="ghcr.io/…/archie-agent:latest" style="border-color: {{accent}}; box-shadow: 0 0 0 3px rgba(134,181,160,0.15)"></div>
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="c3">Duration with unit</label>
<div style="display: flex"><input id="c3" class="inp" value="72" style="border-radius: 6px 0 0 6px"><select aria-label="Unit" class="inp" style="width: 110px; border-radius: 0 6px 6px 0; border-left: 0; font-family: 'IBM Plex Sans', sans-serif"><option>hours</option></select></div></div>
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="c4">Error</label><input id="c4" class="inp" value="1hr" style="border-color: #d9776b"><span style="font-size: 12px; color: #e0a39a">Use a number and a unit, e.g. 1h or 90m</span></div>
<div style="display: flex; flex-direction: column; gap: 6px"><span class="lbl">Secret reference</span>
<div style="display: flex; align-items: center; gap: 8px; height: 36px; padding: 0 12px; border: 1px solid #2e3034; border-radius: 6px">
<svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><rect x="4" y="10" width="16" height="10" rx="2"></rect><path d="M8 10V7a4 4 0 0 1 8 0v3"></path></svg>
<span style="font: 12px 'IBM Plex Mono', monospace; color: #8f8c85">bws /</span><span style="font: 13px 'IBM Plex Mono', monospace">MINIMAX_API_KEY</span>
<span style="margin-left: auto; font-size: 12px; color: {{accent}}">resolved</span>
</div></div>
</section>
</div>
</div>
</x-dc>
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":980}}'>
class Component extends DCLogic {
renderVals() {
const accent = this.props.accent ?? '#86b5a0';
return {
accent,
swatches: [
{ name: 'Ground', hex: '#121314' },
{ name: 'Surface', hex: '#16171a' },
{ name: 'Raised', hex: '#1e2023' },
{ name: 'Border', hex: '#2a2c30' },
{ name: 'Text', hex: '#e8e6e1' },
{ name: 'Muted', hex: '#8f8c85' },
{ name: 'Accent', hex: accent },
{ name: 'Warn', hex: '#d9a45b' }
]
};
}
}
</script>
</body>
</html>
-84
View File
@@ -1,84 +0,0 @@
/*
* Archie "Graphite" theme tokens.
* Warm neutral greys carry the page; ONE low-chroma accent marks the active
* nav item, focus rings, "edited" markers and the primary action. Nothing else
* uses the accent. Map these onto whatever styling system the app already uses
* (Tailwind theme, CSS modules, styled-components…) rather than adding a
* parallel system.
*/
@import url("https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap");
:root {
/* Surfaces (darkest → lightest) */
--bg: #121314; /* page ground, input fill */
--bg-header: #151618; /* app top bar */
--surface: #16171a; /* cards, panels, list containers */
--surface-2: #17181a; /* sticky save bar, drawer, table header */
--raised: #1e2023; /* active nav item, secondary button, hover */
--raised-2: #26282c; /* selected segment in a segmented control */
/* Lines */
--border-subtle: #202225; /* row dividers inside tables */
--border: #232529; /* section dividers, header/sidebar edges */
--border-card: #2a2c30; /* card and panel outlines */
--border-input: #2e3034; /* inputs, toggles off-track */
--border-button: #34373c; /* secondary button outline */
--border-edited: #3a3f3c; /* outline of a section with unsaved edits */
/* Text */
--text: #e8e6e1; /* primary */
--text-2: #a6a39b; /* secondary, nav items, descriptions of sections */
--text-3: #8f8c85; /* hints, captions, placeholders, table headers (≥4.5:1 on --surface) */
--text-on-accent:#101412; /* text on accent-filled buttons */
/* Accent — one at a time. Default sage; alternatives kept for a theme picker. */
--accent: #86b5a0; /* sage (default) */
--accent-ring: rgba(134, 181, 160, 0.15); /* focus halo */
/* --accent: #8aa4c2; steel */
/* --accent: #d4a373; sand */
/* --accent: #a397c9; muted violet (closest to the old purple) */
/* Status */
--warn: #d9a45b; /* "applies after restart", "connecting" dot */
--warn-text: #e3c08f;
--warn-bg: rgba(217, 164, 91, 0.08);
--warn-border: rgba(217, 164, 91, 0.25);
--danger: #d9776b; /* delete, invalid input border, dead state */
--danger-text: #e0a39a;
--danger-bg: rgba(217, 119, 107, 0.08);
--danger-border: #3a2a28;
--diff-add-bg: rgba(134, 181, 160, 0.10);
--diff-add-text: #a9d1bf;
--diff-del-bg: rgba(217, 119, 107, 0.08);
--diff-del-text: #e0a39a;
/* Agent state colours (label table swatches, and anywhere states are shown) */
--state-queued: #8f8c85;
--state-working: #8aa4c2;
--state-waiting: #d9a45b;
--state-pr: #86b5a0;
--state-parked: #6f6c66;
--state-dead: #d9776b;
/* Type */
--font-sans: "IBM Plex Sans", system-ui, sans-serif;
--font-mono: "IBM Plex Mono", ui-monospace, monospace; /* ALL config values, keys, durations, image refs */
--fs-page-title: 24px; /* weight 600, letter-spacing -0.01em */
--fs-card-title: 15px; /* weight 500 */
--fs-body: 14px;
--fs-control: 13px; /* inputs, buttons, nav, labels (label weight 500) */
--fs-hint: 12px; /* line-height 1.5 */
--fs-eyebrow: 11px; /* uppercase, letter-spacing 0.06–0.08em, --text-3 */
/* Shape & spacing */
--radius-sm: 4px; /* kbd hints */
--radius: 6px; /* inputs, buttons, nav items */
--radius-md: 8px; /* segmented control, callouts, diff cards */
--radius-lg: 10px; /* cards, panels */
--radius-pill: 999px;
--control-h: 36px; /* inputs, buttons, nav items */
--header-h: 56px;
--sidebar-w: 264px;
--content-max: 920px;
--row-label-w: 280px; /* left column of a setting row */
}
@@ -1,45 +0,0 @@
{
"name": "Archie Graphite",
"color": {
"bg": "#121314",
"bgHeader": "#151618",
"surface": "#16171a",
"surface2": "#17181a",
"raised": "#1e2023",
"raised2": "#26282c",
"borderSubtle": "#202225",
"border": "#232529",
"borderCard": "#2a2c30",
"borderInput": "#2e3034",
"borderButton": "#34373c",
"borderEdited": "#3a3f3c",
"text": "#e8e6e1",
"text2": "#a6a39b",
"text3": "#8f8c85",
"textOnAccent": "#101412",
"accent": "#86b5a0",
"accentRing": "rgba(134,181,160,0.15)",
"accentAlternatives": { "sage": "#86b5a0", "steel": "#8aa4c2", "sand": "#d4a373", "mutedViolet": "#a397c9" },
"warn": "#d9a45b",
"warnText": "#e3c08f",
"warnBg": "rgba(217,164,91,0.08)",
"warnBorder": "rgba(217,164,91,0.25)",
"danger": "#d9776b",
"dangerText": "#e0a39a",
"dangerBg": "rgba(217,119,107,0.08)",
"dangerBorder": "#3a2a28",
"diffAddBg": "rgba(134,181,160,0.10)",
"diffAddText": "#a9d1bf",
"diffDelBg": "rgba(217,119,107,0.08)",
"diffDelText": "#e0a39a",
"state": { "queued": "#8f8c85", "working": "#8aa4c2", "waiting": "#d9a45b", "pr": "#86b5a0", "parked": "#6f6c66", "dead": "#d9776b" }
},
"font": {
"sans": "\"IBM Plex Sans\", system-ui, sans-serif",
"mono": "\"IBM Plex Mono\", ui-monospace, monospace",
"size": { "pageTitle": 24, "cardTitle": 15, "body": 14, "control": 13, "hint": 12, "eyebrow": 11 },
"weight": { "regular": 400, "medium": 500, "semibold": 600 }
},
"radius": { "sm": 4, "base": 6, "md": 8, "lg": 10, "pill": 999 },
"size": { "controlHeight": 36, "headerHeight": 56, "sidebarWidth": 264, "contentMax": 920, "rowLabelWidth": 280 }
}
-49
View File
@@ -1,49 +0,0 @@
# Agent
Authority: `docs/architecture/agent-system.md` (execution boundary, the model
never runs git) and the Deployment Model section of `CLAUDE.md`.
The daemon prepares a workspace, starts one container per task from a profile's
image, and hands the whole task to `archie-agent` over NATS in one
`taskrun.Request`. The agent reaches the State Store, forge and worktree push
only through the daemon's RPC servers, using task-scoped credentials.
## Giving the agent something new
- **Data about the task** goes in `taskrun.Request` or the task brief
(`container.TaskPayload`), never in an environment variable. Add a test that
the request carries it (`TestRunViaAgentSendsMCPServers` is the pattern).
- **A credential** is scoped to the task and revoked when it ends, like the
State Store grant and the worktree publication grant. The daemon's own
administrative token never enters a container.
- **A tool** reaches the agent through the central registry, MCP, a repository
script or a skill plugin. A profile's `tools` list filters those; ai-sdk
agentloop's built-in file tools are outside it. A tool that must stay inside
the workspace uses the agent loop's confinement, not its own path handling.
## Changing the agent image or a profile image
1. The agent image is `Dockerfile`; example profile images live in
`examples/profiles/`, each with a build-only service in
`docker-compose.yml` (`profiles: ["build"]`, so `up -d` never starts it).
2. Anything the agent runs must be in the image. The container gets no
package manager at run time beyond what the image ships.
3. A locally built image needs `containers.pull_policy = "missing"`;
`"always"` tries to pull it and fails.
4. Profiles are configured under `[containers.profiles.<name>]` and resolved
by the daemon before the container starts (`pinTaskProfile`). An unknown
profile parks the task; it never falls back to the default image.
## Changing how a task runs
- Workspace preparation happens in the daemon (`prepareWorkspace`) before the
container starts, because the container binds the directory. Clones need the
daemon's forge credential; the agent never clones.
- A task with no repository gets `worktree.Manager.ScratchDir`, which is
removed when the task ends.
- The agent runs as root in the container. Anything it writes into the
bind-mounted workspace is handed back to the daemon's UID
(`restoreWorktreeOwnership`); a new write path must stay inside that
workspace.
- NATS rules are in `CLAUDE.md`: task responses use `msg.Respond`, a responder
is flushed after it registers, and `ARCHIE_TASKS` is a work queue.
-83
View File
@@ -1,83 +0,0 @@
# Control plane and settings
Authority: `docs/architecture/configuration.md`. The wiring matrix, the
decoded-but-unwired ledger and the three shapes an unwired field takes are in
`.agents/skills/archie-config-and-flags`.
A field that parses is not a field that works. Before adding one, name the code
that reads it and the path the value takes to get there.
## Decide what kind of setting it is
- **Bootstrap-only** (read once at process start: `database_url`, `state_dir`,
`work_dir`). It stays in the file, is checked by `validateBootstrap` in
`internal/infrastructure/configuration/validate.go`, and the runtime overlay
refuses changes to it.
- **Database-owned** (repository policies, scheduling, tools, plugins,
channels, containers). The file only seeds it. Once the State Store holds the
control-plane resource, the stored document is layered over the file
(`controlplane.Client.RuntimeConfig`) and the file key stops mattering. It is
checked by `validateDatabaseOwned` and by the resource's validator. A stored
value is refreshed from the file only when the store has no value for the kind
at all; a kind that ships a document of its own (workflow definitions,
personas) is refreshed whenever the seed itself wrote the stored copy, since
that copy is a previous release's document rather than an operator's
(`controlplane.Server.seedKind`).
- **Worker-carried.** A value the agent container needs travels in
`config.TaskConfig` (`Config.ForTask`) or on `taskrun.Request`. Never pass it
as an environment variable the daemon did not already define, and never carry
a secret this way.
## Adding a database-owned field
1. Add it to the wire-shape type the resource's `Document` names — a dedicated
struct in `internal/app/controlplane/` with explicit snake_case json tags
(`channel_settings.go`, `tool_settings.go`, `container_settings.go` are the
precedents), never the internal config struct itself. A struct fed straight
into the document falls back to Go field names (`Window`, `MaxRequests`),
and a bare `time.Duration` marshals as nanoseconds — both render unusable
in the Web UI. The resource's JSON schema and the dashboard's Advanced
settings editor are generated from that type, so no UI work is needed for
the editor itself.
2. Map to and from the internal config type at the resource boundary (`Seed`,
the layering in `runtime_config.go`, and the validator all use the same
mapping). Durations in the document are a string-marshalling type
(`config.Duration` or a document-local one), never a bare `time.Duration`.
3. A document stored before the shape existed carries Go-cased keys. Read them
with `controlplanerpc.DecodeRenamingLegacyKeys` (an `UnmarshalJSON` on the
wire type) while keeping `DisallowUnknownFields` — dropping unknown keys
would decode a misspelling as "unset" — and register a `Normalize` on the
`Definition` that re-encodes the document, so a legacy document converges
the next time it is written. A map or a nested struct needs its layering
checked: a stored map replaces the file's, not merges into it, and a field
the stored document omits keeps the file's value. Add a case to
`internal/app/controlplane/runtime_config_test.go` for both.
4. Validate it in one function both sides call, and add a case to
`TestResourceValidatorsRejectWhatEffectiveValidationRejects` in
`validators_agree_test.go`, so the file and the resource cannot disagree.
5. Decide whether it reloads: it does only if every consumer re-reads it from
`config.Holder`. The allowlist is `internal/app/archied/reload.go`; anything
not on it requires a restart.
6. If the settings page shows it as a plain field, add it to
`internal/webui/config_schema.go` and the view in `api_config.go`.
7. A generic catalog resource (`replace` command, not domain-managed, no
query service) is watched **once per archie-ui process** by `webui.RunLive`,
then published to every browser through `/api/stream`. Do not add an
EventSource per resource to a settings store or a gRPC Watch per HTTP client.
The control-plane server polls `Resource` every 250ms per upstream Watch;
verify watch count is independent of client count and that late clients get
the hub's current value (`internal/webui/live_hub_test.go`, real server over
bufconn). Reopens resume after the last delivered version and charge failed
attempts; accepting a gRPC stream does not establish its health.
## Every new field
- Test through the layering: build the effective config the way boot does,
not by setting the field on the consumer.
- Add a commented example to `config.example.toml`. Touch `deployments/*.toml`
only when a profile there needs a value different from the default.
- Update the wiring matrix in `.agents/skills/archie-config-and-flags`.
- Secrets are `SecretRef`s resolved through the secret registry. Never inspect
a resolved value, even in a test.
- Reject a configuration that sets a field with no consumer rather than
accepting and ignoring it (per-identity `forge.intake` is the precedent).
-91
View File
@@ -1,91 +0,0 @@
# Daemon
The daemon claims and runs tasks, and turns captured events into tasks through
bindings. This page covers both.
## Task lifecycle
Authority: `docs/architecture/agent-system.md`. The status vocabulary lives in
`internal/taskstate`, which imports no internal package.
### Adding a status
1. Add the constant to `internal/taskstate/taskstate.go` and place it in
`Terminal`, `Actions` and `Statuses`. Its value is stored, so renaming it
later is a migration.
2. Alias it in `internal/domain/workflow/task/task.go` and
`internal/domain/workflow/task_aliases.go`.
3. Add it to the default catalogue in `ui/src/lib/task-meta.ts`. The server
catalogue replaces the defaults when it loads, but the defaults render first.
4. Find every hand-written status list in SQL:
`grep -rn "'merged'" internal/infrastructure/postgres/queries`.
`ClearTerminalTasks` must match `taskstate.Terminal`, which
`TestClearTerminalTasksMatchesTaskstate` enforces. The stats queries count
outcomes by name; decide whether the new status counts.
5. Extend the table in `taskstate_test.go`.
### Adding a task field
Follow [State Store](state-store.md) for the
column and the wire. Then decide who writes it: `UpdateTask` writes a fixed
column set, so a field set at enqueue belongs in the insert that creates the
row (as `InsertChatTask` does for inputs), or in its own statement when only
some producers set it (as `StampTaskBinding` does for binding provenance).
### Changing what the agent receives
- The task brief is `container.TaskPayload`, written to
`<workspace>/.git/task.json` by `WriteTaskJSON`. Never write it to the
workspace root: the commit stage stages everything there.
- The run request is `taskrun.Request`. `Validate` rejects a request that
cannot run; a new requirement goes there.
- Parking always carries a class (`taskstate.ParkTransient`,
`ParkNeedsHuman`, `ParkTerminal`) chosen by the code that parks. Pick the one
that says what an operator must do.
- A task with no repository (`Task.HasRepository`) runs in a scratch workspace
with no worktree grant. Code that assumes an owner and repo must check first.
## Event automation
Authority: `docs/prds/event-automation.md` (the model: source, event type,
mapping, binding, workflow, profile) and `docs/architecture/bindings.md`
(threat model).
### Where each check lives
A binding is checked twice, and a new rule usually belongs in both places:
- **On save**, in `checkedBinding` (`internal/webui/api_binding.go`), so the
operator sees the problem while editing. It calls the domain checks
`binding.Validate`, `binding.CompileFilter` and `Binding.CheckWorkflow`.
- **At dispatch**, in `dispatchOneBinding` and `resolveBindingTarget`
(`internal/daemon`), because the workflow or mapping may have changed since
the save. A refusal is recorded with `recordDispatchFailure` and starts no
task.
Put the rule itself in `internal/domain/binding` or
`internal/domain/workflow/task` and call it from both, rather than writing it
twice.
### Adding a binding field
1. Domain type and `Validate` in `internal/domain/binding`.
2. Column, queries, store mapping, wire field, `newColumns`
([State Store](state-store.md)).
3. The request type and `checkedBinding` in `api_binding.go`.
4. The draft, payload and editor in `ui/src/bindings/`
([Frontend UI](frontend-ui.md)).
5. Its effect at dispatch, with a case in
`internal/daemon/dispatch_inputs_test.go` or `dispatch_bindings_test.go`.
### Rules that must hold
- Signing belongs to the source. Intake verifies the HMAC against the source's
secret before the payload is parsed.
- An event must be identified as an event type before anything dispatches it,
and a binding applies only to its mapping's event type. Dispatch test
fixtures therefore create an event type before inserting captures.
- The dispatch ledger is claimed before the task is enqueued (at most once).
- Anything an event supplies that selects what the agent acts on, such as a
repository, must be checked against configuration. An event never widens
what an agent can reach.
-108
View File
@@ -1,108 +0,0 @@
# Frontend UI
Authority: `.agents/skills/archie-web-ui` (stack facts, design-system rules,
tone and accessibility). This page covers what a change must reach, not how it
should look.
## Adding or changing a feature
1. The feature lives in `ui/src/<feature>/`. Move a helper to `ui/src/base/`
only when a second feature needs it.
2. Keep wire shapes, draft state and payload building in a plain `.ts` module
beside the components (`ui/src/bindings/binding-draft.ts` is the pattern),
and test it in `ui/test/*.test.ts`. Components stay thin.
3. Every mutation goes through `api.*` in `ui/src/lib/api`, which sends the
CSRF and Content-Type headers the server's mutation guard requires. A bare
`fetch` is refused.
4. A value the server also describes (task statuses, actions, workflow inputs)
comes from the server. Keep a local default only so the first render works,
and keep it in step (`ui/src/lib/task-meta.ts`).
5. Run `task ui`, `task test:ui` and `cd ui && npm run typecheck`. Commit the
regenerated `ui/dist/`; the Go binaries embed it. A fresh git worktree has
no ignored `ui/node_modules`: run `cd ui && npm ci` before these commands.
6. **One long-lived browser connection:** `ui/src/lib/api.ts` has the only
`new EventSource`, owned by `stores/live-updates.ts`. Feature stores consume
topics with `live.subscribe(topic, callback)`; do not open a page-owned SSE
stream. Logs alone opt in while mounted, replacing that same EventSource
with `?topics=logs&since=<last cursor>`; a browser's `Last-Event-ID` only
survives its own automatic reconnect, not a newly constructed EventSource.
Task and log topics resume by cursor; control-plane, identity and apply-status
topics replay the latest snapshot. Test a fetch and same-origin navigation
after visiting Settings and Logs: the UI process serves HTTP/1.1 and six
persistent streams can starve every later browser request.
## Testing the dashboard
Authority: the runner itself is `ui/package.json`'s `test` script: `node --test
--experimental-strip-types test/*.test.ts` over `ui/test/*.test.ts`. It runs
pure TypeScript modules with `node`'s type stripping — no SFC loader, no DOM,
no second dependency beyond what the app already carries. That is the standard,
and a decision record for when it is deliberately not enough:
- **Test archie's logic in a module; leave SFC wiring alone.** Wire shapes,
draft state, copy conditions, filters and payload building live in plain
`.ts` files beside the components and are tested in `ui/test/`. Components
stay thin, so there is normally nothing in an SFC that is archie logic.
- **A dashboard rule that mirrors a server rule is pinned by a shared
fixture, not two independent tests.** `ui/src/settings/validation.ts`
hand-mirrors three control-plane validators, and the model-role rule had
already drifted because nothing tied the two sides together. Each case now
lives once in `internal/app/controlplane/testdata/dashboard-validators.json`:
a Go test in that package runs the real server validators over it, and
`ui/test/control-plane-validator-parity.test.ts` runs the real dashboard
validators over the same cases. Changing one rule alone fails the other
side's test. Add a case to the fixture, never to one side only.
- **Installed primitives are upstream-tested, not re-tested here.**
`reka-ui` (2.10.5 here) maintains colocated tests per component in its own
repo (Vitest/jsdom + axe: Switch, TagsInput, NumberField, Select, the
arrow-navigation composables). The npm package ships none of those files, so
this coverage is inherited through the version bound, not the tarball —
`grep -l test node_modules/reka-ui` finds nothing. Duplicating them as local
mount tests would test a dependency.
- **A `.vue` import cannot run under the module runner.** `node --test` fails
such a module with `ERR_UNKNOWN_FILE_EXTENSION: .vue` and the runner has no
built-in loader for SFCs. A file under `ui/test/` that imports a `.vue` is
therefore a broken test, not a weak one.
- **If a DOM mount harness is ever needed** (a page-level accessibility
contract, cross-component interaction, focus behaviour): `happy-dom` +
`@vue/test-utils` + `vitest` scoped to a separate DOM test glob, keeping the
module runner for everything else. Measured on the ui tree (vitest 5.0.2,
happy-dom 20.14.5, @vue/test-utils 2.5.1): they add 24 top-level
`node_modules` entries and 27 MB on a 296 MB install, a working 2-test mount
suite (role=radiogroup vs role=switch, aria-label, click activation against
the real SFCs) runs in 1.2 s on top of the current 0.5 s module suite, and
`vue-tsc` (7.4 s) dominates `task test:ui` either way. The single-runner
alternative (absorbing the existing suite into vitest) was measured
infeasible as-is: all 29 existing files import `node:test`, which vitest
cannot collect ("No test suite found in file" for every one), so it would be
a rewrite of the whole suite, and its runtime was not measured. Nothing in
`ui/dist` or CI changes either way; happy-dom is pure JS, no browser binary.
- **What the module standard does not verify:** whether a call site passes an
`aria-label` or which `v-if` branch shows. Those live in SFC templates and
are only visible with a mount. If a page's accessible-name wiring is the
risk, say so in the page's task and reach for the harness decision above
rather than quietly growing mount tests. Never suppress a lint rule or a
test to keep SFC behaviour out of the gate.
## Adding an API route
1. The handler goes in the `internal/webui/api_<concern>.go` file for its
concern. Check the request fully on the server; the UI's checks are only a
convenience.
2. A mutation calls `authorizeTaskMutation` first.
3. A route whose store is not configured answers 503, and
`internal/app/archieui/degraded_routes_test.go` pins what each route
returns without its contract. Add the route there.
4. The dashboard runs in its own process (`archie-ui`) and must not link the
daemon or the workflow engine (`cmd/archie-ui/architecture_test.go`). Reach
stored data through `storecontract` interfaces wired in
`internal/app/archieui/compose.go`.
5. Settings that live in a control-plane resource need no new route: the
Advanced settings page edits every resource from its generated schema.
6. For a new live topic, add one process-wide producer to `internal/webui`'s
`RunLive` and fan it through the `/api/stream` hub; `internal/app/archieui/run.go`
starts the producers with the process context. Never create an upstream
watch or poller in an HTTP handler. A slow client must reconnect for cursor
and snapshot repair rather than silently lose an update. Prove the producer
with several browser clients against the real peer, not just a scripted
stream; `live_hub_test.go` is the example.
-47
View File
@@ -1,47 +0,0 @@
# Development guides
Checklists for changing Archie, one page per area. Each names every place a
change must reach, so a feature that works in one layer does not silently stop
at the next. A change that spans areas starts on the page for the area it
begins in, which points to the others. The pages point at the documents that
own the design (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than
restating them.
| Area | Covers |
| ---------------------------------------------- | -------------------------------------------------------------------------------- |
| [Frontend UI](frontend-ui.md) | Anything under `ui/`, and the dashboard's API routes |
| [Agent](agent.md) | The agent container, its image, profiles, tools and workspace |
| [Workflows](workflows.md) | Workflow definitions and step types |
| [Daemon](daemon.md) | Task statuses, fields and the brief; sources, event types, mappings and bindings |
| [State Store](state-store.md) | Stored fields, tables, RPCs and errors |
| [Control plane and settings](control-plane.md) | Settings in `config.toml` or the dashboard |
| [Processes and wiring](wiring.md) | Where code goes, processes, plugin engines, channels, NATS subjects |
| [Merging work](merging-work.md) | Merging a lane or a branch |
## Every change
- Write the failing test first for anything with logic, branching or a
contract, and check it fails on an assertion, not a compile error.
- Test through the path production uses. A test that sets a value directly on
the consumer proves nothing about the layers that normally deliver it.
- Run `task check` and let its exit status decide the commit:
`task check && git commit ...`. `task test` passes `-short`, which skips the
process and Postgres tests, so run `go test -count=1 ./cmd/... ./internal/...`
too when a change crosses a process or the database.
- Regenerate, never hand-edit, generated output: `task proto:generate`,
`go -C tools tool sqlc generate -f $PWD/internal/infrastructure/postgres/sqlc.yaml`,
`task ui`, `task docs:artifact`. `task proto:check` compares against the git
index, so stage regenerated contracts before running it.
- Stage by path, or read `git status` before `git add -A`. Tests that start
embedded NATS or write logs must use `t.TempDir()`; anything they leave in the
tree gets committed. `task check` writes no module file on a consistent tree,
root or `tools/` (verified at HEAD with `GOFLAGS` unset and with `-mod=mod`):
a stale `go.mod` or `go.sum` fails it, with `missing go.sum entry` or
`updates to go.mod needed`, rather than being repaired. Only a global
`GOFLAGS=-mod=mod` in `go env` re-enables that repair, which is why the
`go -C tools` steps pass `-mod=readonly`; if `go.sum` goes dirty, run
`go mod tidy` and commit the result on its own.
- A change to `docs/prds/`, `docs/architecture/` **or `docs/development/`**
carries the regenerated `docs/data/generated/dev-docs.json`: run
`task docs:artifact` (not `task docs:check`, which checks contracts only).
PRD edits also follow `docs/prds/RULES.md` and pass `task docs:prds`.
Loaded 100 of 190 files, more files were not shown because too many files have changed in this diff. Show more