ADR 0003/0004: enforced verification ledger + measured 3-way benchmark

.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bun test
+      - run: bun run build
+      - run: git diff --check

.gitignore

@@ -5,4 +5,3 @@ task_plan.md
 node_modules/
 findings.md
 node-compile-cache
-bun.lock

AGENTS.md

@@ -147,7 +147,8 @@ Your Legion uses direct specialist routing rather than a category-first runtime.
 - Override or disable specific declared components with `domains.<domain-id>.<component>.<id>.path` or `false`.
 - A same-id override replaces the declared file path; overrides do not add components that are absent from `DOMAIN.md`.
 - Domain ids and component ids use the same kebab-case style as agent names.
-- `bunx @whchi/your-legion create-domain <domain-id>` creates `DOMAIN.md` only for a new custom id; pass `--components decisions,skills` to scaffold selected facets, and `--enable` to write it into `legionaries.yaml`. It must reject existing global domains and bundled domain ids.
+- `bunx @whchi/your-legion create-domain <domain-id>` creates `DOMAIN.md` and `updates.md` for a new custom id; pass `--components decisions,skills` to scaffold selected facets, and `--enable` to write it into `legionaries.yaml`. It must reject existing global domains and bundled domain ids.
+- `bunx @whchi/your-legion domain-update <domain-id> ...` appends pending reusable knowledge candidates to `updates.md`; promotion into runtime still requires moving accepted knowledge into `DOMAIN.md`-listed components.
 - Runtime evidence records `delegation` and `domain-read` events. Use `bunx @whchi/your-legion doctor --worktree .` for diagnostics; it fails when `DOMAIN.md` declarations are invalid or declared domain refs/skills were not read, and it reports domain usage stats.
 - Use `bunx @whchi/your-legion domain-scenarios` and `bunx @whchi/your-legion doctor --worktree . --scenarios` for the fixed coding, marketing, finance, accounting, and mixed-domain validation set.
 
@@ -157,6 +158,10 @@ Your Legion uses direct specialist routing rather than a category-first runtime.
 - A loop defines `description`, `objective`, `trigger`, `inbox_path`, optional domain evidence, agent roles, worktree policy, verification, and connector mode.
 - `inbox_path` must be repo-relative and points to the durable human-readable loop state file.
 - `builder` is the default maker and `verifier` is the default checker.
+- Loop invocation is explicit-only.
+- Start loop work only when the user names a configured loop id or provides a generated `loop-prompt` Task Context Envelope.
+- The orchestrator must not set `Loop` from task intent, topic, similarity, or the Loop Catalog alone.
+- If the user asks to use loop engineering without naming a configured loop id, ask which configured loop to run.
 - `create-loop <loop-id> --preset <id>` writes a loop config entry and creates `docs/legion-loops/<loop-id>.md` in the selected worktree.
 - `loop-presets`, `loop-prompt`, and `loop-runs` are the user-facing loop DX path.
 - `loops` lists configured loops.

README.md

@@ -1,25 +1,42 @@
 # Your Legion
 
+[![CI](https://github.com/whchi/your-legion/actions/workflows/ci.yml/badge.svg)](https://github.com/whchi/your-legion/actions/workflows/ci.yml)
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/whchi/your-legion)
 
-An OpenCode plugin that improves multi-agent and loop-oriented work with bounded specialists, per-agent provider/model mapping, structured context handoff, and evidence-backed diagnostics.
+An OpenCode plugin for multi-agent work you can audit. Most multi-agent setups let the agent that did the work also declare it done; Your Legion separates the maker (`builder`) from the checker (`verifier`), records what each delegation declared and what was actually read as trace events, and turns that evidence into pass/fail diagnostics.
 
-Your Legion keeps OpenCode as the execution harness. It injects a small protected agent set, routes each turn to the right specialist, and lets operators choose different providers or models for routing, planning, discovery, documentation lookup, and execution.
+The verification core is a completion ledger. A maker that changed files must report a `Verification status` block, an unverified claim routes through an independent `verifier` pass, and `trace-check` fails a run whose ledger says unverified file changes were shipped without one:
 
-Task Context Envelopes keep delegation explicit and compact. Domain Packs provide selective expert context. Legion Loops define recurring or goal-driven engineering workflows with durable inboxes and maker/checker verification. Trace and doctor commands validate domain and loop evidence after the fact.
+```text
+- Verification status:
+  - Files changed: yes
+  - Verifier pass: not-run
+  - Status: unverified
+  - Reason: test runner unavailable in this environment
+```
+
+```text
+$ bunx @whchi/your-legion trace-check --worktree .
+verification-report [unverified-file-changes]: maker reported file changes with status unverified and no verifier delegation followed
+```
+
+The per-agent provider/model map serves the same goal: the checker can run on a different model than the maker, so they do not share correlated blind spots (`doctor` warns when a loop's maker and verifier resolve to the same model).
+
+Around that core, Your Legion keeps OpenCode as the execution harness and adds a small protected specialist set with per-agent provider/model mapping, Task Context Envelopes for explicit compact delegation, Domain Packs for selective expert context, and Legion Loops for recurring maker/checker workflows with durable inboxes. The benchmark protocol is deliberately allowed to conclude that orchestration was not worth it — and the committed 2026-07-04 measured run says exactly that for small tasks (same-provider orchestration was +85–146% tokens for no quality gain; a cheaper mixed-provider map matched native cost once); see [`ORCHESTRATOR_BENCHMARK.md`](./docs/ORCHESTRATOR_BENCHMARK.md).
 
 ![](docs/architecture.svg)
 
 ## When To Use This
 
 Use Your Legion when:
 
-- You want OpenCode to route work across specialists more consistently.
-- You want a simple per-agent provider/model map instead of a role-play agent team.
-- You have project or domain knowledge that agents should use selectively.
-- You want recurring engineering loops with explicit state, maker/checker separation, and diagnostics.
+- You want completion claims backed by a maker/checker ledger and trace evidence, not self-reporting.
+- You want the checker on a different provider or model than the maker.
 - You want troubleshooting evidence when a domain-enabled task did not use the expected context.
-- You want to compare native OpenCode execution against an orchestrated multi-agent path.
+- You want recurring engineering loops with explicit state, maker/checker separation, and diagnostics.
+- You have project or domain knowledge that agents should use selectively.
+- You want OpenCode to route work across specialists more consistently.
+- You want to compare native OpenCode execution against an orchestrated multi-agent path, with the comparison allowed to go either way.
 
 It is not a standalone agent platform or a public domain-pack ecosystem. The goal is a lightweight plugin that improves OpenCode's multi-agent workflow.
 
@@ -50,6 +67,15 @@ Explore where Your Legion builds the runtime agent config.
 
 The `orchestrator` should route repo discovery requests to `explorer`. For a clear code change, ask for the change directly; the orchestrator should route execution to `builder`, and `builder` should gather the needed repo context itself.
 
+Then check the evidence trail instead of taking the transcript's word for it:
+
+```bash
+bunx @whchi/your-legion doctor --worktree .
+bunx @whchi/your-legion trace-check --worktree .
+```
+
+`doctor` validates domain declarations, loop catalogs, and runtime trace evidence, and prints usage stats. `trace-check` fails when a maker reported unverified file changes and no verifier pass followed.
+
 Use these docs next:
 
 - Install and uninstall details: [`INSTALLATION.md`](./docs/INSTALLATION.md)
@@ -61,6 +87,7 @@ Use these docs next:
 - Copy-paste examples: [`EXAMPLES.md`](./docs/EXAMPLES.md)
 - Development notes: [`DEVELOPMENT.md`](./docs/DEVELOPMENT.md)
 - Academic references behind the domain/runtime design: [`academic-papers-summary.md`](./docs/academic-papers-summary.md)
+- Essay influences behind loops and Domain Packs: [`design-influences.md`](./docs/design-influences.md)
 
 ## Install
 
@@ -157,7 +184,9 @@ Custom agent definitions are discovered from bundled package examples and from t
 
 Domain descriptions and skills are injected into agent prompts as a Domain Catalog with namespaced entries such as `marketing/campaign-brief`. Routing agents pass relevant `Domain refs` and `Domain skills` in the Task Context Envelope; target specialists read the exact configured paths. Your Legion does not register domain skills as top-level harness skills.
 
-Delegations use a compact Task Context Envelope with `Scenario`, `Loop`, `Loop run`, `Loop status`, `Objective`, `Active domains`, `Domain refs`, `Domain skills`, `Context refs`, `Constraints`, `Expected output`, `Verification`, `Completion claim`, `Verification commands`, and `Verification outcome`. The orchestrator compares the task with the Loop Catalog and Domain Catalog, then passes only the matching loop id, run id, and domain evidence. If no loop applies, it writes `Loop: none`. If no domain is configured or no domain description clearly matches, it should use no-domain delegation: `Active domains: none`, `Domain refs: none`, and `Domain skills: none`.
+Delegations use a compact Task Context Envelope with `Scenario`, `Loop`, `Loop run`, `Loop status`, `Objective`, `Active domains`, `Domain refs`, `Domain skills`, `Context refs`, `Constraints`, `Expected output`, `Verification`, `Completion claim`, `Verification commands`, and `Verification outcome`. The orchestrator uses loop context only for explicit loop runs, compares the task with the Domain Catalog, then passes only the selected loop id, run id, and domain evidence. If no loop applies, it writes `Loop: none`. If no domain is configured or no domain description clearly matches, it should use no-domain delegation: `Active domains: none`, `Domain refs: none`, and `Domain skills: none`.
+
+Loop invocation is explicit-only. Use `loop-prompt <loop-id>` or name a configured loop id for deliberate runs. The orchestrator should not set `Loop` from task intent, topic, similarity, or the Loop Catalog alone; all other requests use `Loop: none`.
 
 Your Legion records warn-only domain usage evidence under `~/.config/opencode/your-legion/traces/`. When troubleshooting domain setup, use `bunx @whchi/your-legion doctor --worktree .` for static domain catalog validation, runtime trace validation, and domain usage stats. Use `bunx @whchi/your-legion trace` when you need raw delegation and domain-read events, or `trace --summary` for grouped delegation evidence. See [`DOMAIN_OBSERVABILITY.md`](./docs/DOMAIN_OBSERVABILITY.md) for the full validation workflow.
 
@@ -173,7 +202,7 @@ For hands-on examples of custom agents, marketing domain packs, mixed coding plu
 
 ## Routing Model
 
-Your Legion uses direct specialist routing.
+Your Legion uses direct specialist routing along two orthogonal axes: **agents are work-mode boundaries** (how to work — route, plan, build, verify, explore, look up docs), and **Domain skills are capability boundaries** (what expertise the work needs — coding, marketing, finance, and so on). Agents stay domain-neutral; professional capability is injected as Domain skills, never baked into an agent. Add new expertise as a Domain Pack; reserve new agents for genuinely new work modes.
 
 - The `orchestrator` classifies each turn into one dominant intent and chooses a concrete subagent.
 - Those intents are routing heuristics, not runtime categories or model profiles.
@@ -184,15 +213,17 @@ Your Legion uses direct specialist routing.
 ## Commands
 
 - `bunx @whchi/your-legion install [--config-dir <path>] [--domains <ids>] [--add-domains <ids>]`: installs or refreshes the plugin registration. First install writes `legionaries.yaml` with `coding` enabled and materializes enabled bundled domain packs under `~/.config/opencode/your-legion/domains/`. Reinstall without domain flags preserves existing config. `--domains` replaces the enabled domain list; `--add-domains` merges into it.
-- `bunx @whchi/your-legion create-domain <domain-id> [--config-dir <path>] [--components workflows,decisions,examples,skills] [--enable]`: scaffolds a new global domain pack. By default it creates only `DOMAIN.md`; use `--components` to add selected optional folders and matching placeholder files, and `--enable` to write the domain into `legionaries.yaml`. Existing global domains and bundled domain ids are rejected.
+- `bunx @whchi/your-legion create-domain <domain-id> [--config-dir <path>] [--components workflows,decisions,examples,skills] [--enable]`: scaffolds a new global domain pack with `DOMAIN.md` and `updates.md`. Use `--components` to add selected optional folders and matching placeholder files, and `--enable` to write the domain into `legionaries.yaml`. Existing global domains and bundled domain ids are rejected.
+- `bunx @whchi/your-legion domain-update <domain-id> --type <decision|correction|workflow|verification|reusable> --title <text> [--config-dir <path>] [--promote-to <path>]`: appends a pending reusable knowledge candidate from stdin to the domain's `updates.md`.
 - `bunx @whchi/your-legion create-loop <loop-id> [--preset <id>] [--worktree <path>] [--config-dir <path>] [--description <text>] [--objective <text>] [--verification <commands>]`: creates a configured Legion Loop and repo-local inbox.
 - `bunx @whchi/your-legion loops [--config-dir <path>]`: lists configured Legion Loops.
 - `bunx @whchi/your-legion loop-presets`: lists quick-start templates such as `ci-triage`, `issue-triage`, `docs-refresh`, and `release-check`.
 - `bunx @whchi/your-legion loop-prompt <loop-id> [--worktree <path>] [--config-dir <path>] [--run-id <id>]`: generates a ready Task Context Envelope for a loop run.
 - `bunx @whchi/your-legion loop-runs [--worktree <path>] [--config-dir <path>] [--loop <loop-id>]`: groups loop run completion ledger evidence from trace events.
 - `bunx @whchi/your-legion doctor [--worktree <path>] [--config-dir <path>] [--scenarios]`: troubleshoots domain and loop setup. By default it validates `DOMAIN.md` declarations, loop catalogs, runtime trace evidence, and usage stats; `--scenarios` verifies the fixed domain scenario set.
 - `bunx @whchi/your-legion trace [--worktree <path>] [--config-dir <path>] [--limit <n>] [--summary]`: prints recent domain usage evidence for a workspace/project path; `--summary` groups declared refs, matching reads, and warnings by delegation.
-- `bunx @whchi/your-legion trace-check [--worktree <path>] [--config-dir <path>]`: low-level trace validation for contract warnings and declared domain refs or skills that were not read.
+- `bunx @whchi/your-legion trace-check [--worktree <path>] [--config-dir <path>] [--require-evidence]`: low-level trace validation for contract warnings, declared domain refs or skills that were not read, and maker/checker ledger integrity (unverified file changes without a following verifier pass fail). `--require-evidence` additionally fails when no delegation or loop-run-report evidence exists at all.
+- `bunx @whchi/your-legion benchmark-summarize --metrics <path>`: summarizes an exported benchmark metrics file (JSON array or JSONL of session metrics) into the quality-plus-token outcome taxonomy. See [`ORCHESTRATOR_BENCHMARK.md`](./docs/ORCHESTRATOR_BENCHMARK.md).
 - `bunx @whchi/your-legion domain-scenarios`: prints the fixed domain scenario prompts.
 - `bunx @whchi/your-legion domain-scenario-check [--worktree <path>] [--config-dir <path>]`: low-level fixed scenario validation; `doctor --scenarios` is the preferred entrypoint.
 

docs/CONFIGURATION.md

@@ -145,6 +145,19 @@ custom_agents:
 
 Custom agents run as `subagent`. Any permission key not listed in the YAML is set to `deny`. Custom agents cannot use system agent names such as `builder`, `planner`, or `explorer`. A worktree definition with the same name as a bundled custom agent overrides the bundled definition; the model mapping still comes from the global runtime config.
 
+## Verification
+
+Post-execution verification controls whether the orchestrator routes an independent `verifier` pass when `builder` reports file changes it did not verify.
+
+```yaml
+verification:
+  default_check: true
+```
+
+- `default_check` (boolean, default `true`): when `true`, the orchestrator routes a `verifier` pass before reporting completion for any `builder` deliverable that reports `Files changed: yes` with `Status: unverified`. Set it to `false` to keep verification opt-in (the previous behavior): the orchestrator then verifies only for loops or when the user explicitly asks.
+
+`builder` always returns a Verification status ledger (files changed; verifier pass ran or not-run; `verified` / `unverified` / `verification-skipped` with a reason), so the maker/checker split stays visible even when `default_check` is off. See [ADR 0003](./adr/0003-enforced-verification-and-maker-checker-integrity.md).
+
 ## Domain Packs
 
 Domain packs provide a shared Domain Catalog for the same system and custom agents. They are self-describing capabilities with reusable workflows, decisions, examples, and domain-local skills. They are not registered as harness-level skills and they are not automatically active task memory.