qaas-python 1.0.0__tar.gz → 2.0.0__tar.gz

{qaas_python-1.0.0 → qaas_python-2.0.0}/ARCHITECTURE.md

@@ -64,7 +64,7 @@ Start with `qaas validate`, then `qaas run --dry-run`. Neither calls the API.
 ```
 src/qaas/
 ├── cli.py          866  entry point; every command above
-├── conductor.py    452  THE STATE MACHINE — phases, budget, concurrency, loops
+├── router.py    452  THE STATE MACHINE — phases, budget, concurrency, loops
 ├── runner.py       118  invokes ONE agent, records what it cost
 ├── registry.py     275  turns an agent's YAML into SDK options
 ├── guardrails.py   413  the permission matrix, enforced in code
@@ -81,18 +81,18 @@ src/qaas/
 └── adapters/           tracker (local | jira), vcs (local | github)
 ```
 
-If you read three files, read `conductor.py`, `envelope.py`, `guardrails.py`.
+If you read three files, read `router.py`, `envelope.py`, `guardrails.py`.
 Everything else is in service of those.
 
 ---
 
 ## 4. The two decisions that explain everything else
 
-**CONDUCTOR is Python, not a prompt.** The original design has an orchestrator
+**ROUTER is Python, not a prompt.** The original design has an orchestrator
 agent. It is implemented as an ordinary state machine instead, because *a model
 cannot enforce a budget it is itself spending*. Phase ordering, concurrency,
 retries, escalation and the budget governor are all plain code in
-`conductor.py`. This also makes runs reproducible and cheap to unit-test — 547
+`router.py`. This also makes runs reproducible and cheap to unit-test — 547
 tests run offline with no API calls.
 
 **Each agent is its own top-level `query()`.** Not SDK subagents of a shared
@@ -114,34 +114,34 @@ $ qaas run --mode full-loop
     cli.py  ── loads config/system.yaml + config/agents/*.yaml + the target profile
         │
         ▼
- conductor.py  ── runs five phases in order, in-process
+ router.py  ── runs five phases in order, in-process
         │
-        ├── PHASE 1  map        CARTOGRAPHER      → system-map.json (versioned, pinned)
-        ├── PHASE 2  discover   CONDUIT, SURFACE  → DefectEnvelopes   [concurrent]
-        ├── PHASE 3  reproduce  FORGE             → failing test per finding
-        ├── PHASE 4  file       CLERK             → tickets
-        └── PHASE 5  verify     PROOF ⇄ MENDER ⇄ ARBITER   [bounded loop]
+        ├── PHASE 1  map        MAPPER                    → system-map.json (versioned, pinned)
+        ├── PHASE 2  discover   API, BROWSER, …           → DefectEnvelopes   [concurrent]
+        ├── PHASE 3  reproduce  REPRODUCER                → failing test per finding
+        ├── PHASE 4  file       TRIAGE                    → tickets
+        └── PHASE 5  verify     VERIFIER ⇄ FIXER ⇄ REVIEWER   [bounded loop]
 ```
 
-Each phase is a method on `Conductor`: `_phase_map`, `_phase_discover`,
+Each phase is a method on `Router`: `_phase_map`, `_phase_discover`,
 `_phase_reproduce`, `_phase_file`, `_phase_verify`.
 
 Which agents run is **config, not code** — `run_modes` in `config/system.yaml`:
 
 ```yaml
-pr-check:   [CARTOGRAPHER, CONDUIT, SURFACE, FORGE, CLERK]        $16
-nightly:    [CARTOGRAPHER, CONDUIT, SURFACE, FORGE, CLERK]        $40
-fix-cycle:  [PROOF, MENDER, ARBITER]                              $20
+pr-check:   [MAPPER, API, BROWSER, REPRODUCER, TRIAGE]        $16
+nightly:    [MAPPER, API, BROWSER, REPRODUCER, TRIAGE]        $40
+fix-cycle:  [VERIFIER, FIXER, REVIEWER]                              $20
 full-loop:  all eight                                             $60
 ```
 
-Note the shape: **FORGE runs once per finding**, in a fresh context each time. So
+Note the shape: **REPRODUCER runs once per finding**, in a fresh context each time. So
 cost scales with how much was found, not with how many agents exist.
 
 ### 5.2 Dispatching one agent
 
 ```
-conductor._dispatch(spec, task)
+router._dispatch(spec, task)
         │
         ├── Budget.check()          raises BudgetExceeded → a control working, not an error
         │
@@ -164,7 +164,7 @@ conductor._dispatch(spec, task)
 ```
 
 Failures are **captured, not raised**. One agent falling over costs the run that
-agent's findings, not the whole run; the conductor decides whether to retry, skip
+agent's findings, not the whole run; the router decides whether to retry, skip
 or escalate.
 
 ### 5.3 The remediation loop (phase 5)
@@ -175,7 +175,7 @@ explicit bounds:
 ```
         ┌─────────────────────────────────────────────┐
         ▼                                             │
-      PROOF ──VERIFIED──▶ done                        │
+      VERIFIER ──VERIFIED──▶ done                        │
         │                                             │
         ├──REGRESSED──▶ escalate to a human           │
         │                                             │
@@ -183,9 +183,9 @@ explicit bounds:
         │                                             │
         ├─ reopens ≥ max_proof_reopens ─▶ escalate    │
         ▼                                             │
-      MENDER ──▶ ARBITER ──APPROVE────────────────────┘
+      FIXER ──▶ REVIEWER ──APPROVE────────────────────┘
                     │
-                    ├─ REQUEST_CHANGES ─▶ back to MENDER (capped at 2 trips)
+                    ├─ REQUEST_CHANGES ─▶ back to FIXER (capped at 2 trips)
                     └─ ESCALATE_TO_HUMAN ─▶ stop
 ```
 
@@ -194,7 +194,7 @@ defect cycles until the budget is gone and the run ends with no verdict and no
 money left to reach one. Escalating after one reopen costs a human five minutes;
 not escalating costs the whole run.
 
-PROOF's verdict is a **typed ledger entry** written through a tool
+VERIFIER's verdict is a **typed ledger entry** written through a tool
 (`record_verdict`), never parsed out of the agent's prose.
 
 ---
@@ -279,11 +279,11 @@ Playwright is the one exception — a real stdio subprocess, declared in
 An agent is **a prompt plus a YAML file**. Nothing else.
 
 ```
-src/qaas/prompts/CONDUIT.md      role, standards, what good looks like
-config/agents/conduit.yaml       model, budget, tools, skills, policy
+src/qaas/prompts/API.md      role, standards, what good looks like
+config/agents/api.yaml       model, budget, tools, skills, policy
 ```
 
-Adding an agent should require **no change** to `conductor.py`, `runner.py`,
+Adding an agent should require **no change** to `router.py`, `runner.py`,
 `registry.py` or `guardrails.py`. A change to those files while adding an agent
 is a sign something is wrong.
 
@@ -305,23 +305,23 @@ that mentions one repo's layout or one app's seeded users works exactly once.
 
 | agent | layer | does |
 |---|---|---|
-| CARTOGRAPHER | map | services, routes, schema, ownership → `system-map.json` |
-| KEYSTONE | discovery | circular deps, layering violations, god modules, dead code |
-| CONDUIT | discovery | API contract drift; ships a failing contract test |
-| SURFACE | discovery | drives the UI through real journeys |
-| VAULT | discovery | schema constraints the code assumes and the database does not enforce |
-| WARDEN | discovery | missing authorization, secrets, vulnerable dependencies, leaked internals |
-| PULSE | discovery | WebSocket auth, reconnect, ordering, backpressure |
-| USHER | discovery | whether a person can *find* a feature, not just whether it works |
-| GAUGE | discovery | N+1 queries, unindexed hot paths, unbounded results, bundle outliers |
-| FORGE | triage | reproduces, minimises, measures flake, commits a failing test |
-| CLERK | triage | dedupes, scores severity, routes, files — the only tracker writer |
-| MENDER | remediation | the minimal fix, on a `fix/*` branch |
-| ARBITER | remediation | adversarial review: APPROVE / REQUEST_CHANGES / ESCALATE |
-| PROOF | verify | re-runs the original test → VERIFIED / NOT_FIXED / REGRESSED |
-| CHRONICLE | reporting | what the run found, what recurred, and what it could not reach |
-
-CONDUCTOR is the sixteenth. It is the Python state machine in `conductor.py`
+| MAPPER | map | services, routes, schema, ownership → `system-map.json` |
+| ARCHITECT | discovery | circular deps, layering violations, god modules, dead code |
+| API | discovery | API contract drift; ships a failing contract test |
+| BROWSER | discovery | drives the UI through real journeys |
+| DBA | discovery | schema constraints the code assumes and the database does not enforce |
+| AUDITOR | discovery | missing authorization, secrets, vulnerable dependencies, leaked internals |
+| SOCKET | discovery | WebSocket auth, reconnect, ordering, backpressure |
+| GUIDE | discovery | whether a person can *find* a feature, not just whether it works |
+| LOAD | discovery | N+1 queries, unindexed hot paths, unbounded results, bundle outliers |
+| REPRODUCER | triage | reproduces, minimises, measures flake, commits a failing test |
+| TRIAGE | triage | dedupes, scores severity, routes, files — the only tracker writer |
+| FIXER | remediation | the minimal fix, on a `fix/*` branch |
+| REVIEWER | remediation | adversarial review: APPROVE / REQUEST_CHANGES / ESCALATE |
+| VERIFIER | verify | re-runs the original test → VERIFIED / NOT_FIXED / REGRESSED |
+| REPORTER | reporting | what the run found, what recurred, and what it could not reach |
+
+ROUTER is the sixteenth. It is the Python state machine in `router.py`
 rather than an agent, because a model cannot enforce a budget it is spending.
 
 ---
@@ -340,16 +340,16 @@ second layer for calls the allowlist did not auto-approve. Both call one
 
 What is enforced:
 
-- **Path scoping** — writes resolved and checked against `write_paths`. FORGE and
-  MENDER only; everyone else denied.
+- **Path scoping** — writes resolved and checked against `write_paths`. REPRODUCER and
+  FIXER only; everyone else denied.
 - **Branch scoping** — git writes matched against branch patterns
   (`qa/repro/*`, `fix/*`). `main` and force-push denied outright.
 - **Ticket rate limit** — `max_tickets_per_run: 10`; over cap the call is denied
-  and the conductor escalates instead of filing.
+  and the router escalates instead of filing.
 - **Forbidden path classes** — migrations, auth, payment, secrets, infra, CI stop
   at a human however small the change looks.
 - **Diff budget** — counted per distinct file.
-- **Immutable test** — MENDER may not edit the test recorded on the envelope.
+- **Immutable test** — FIXER may not edit the test recorded on the envelope.
 
 Denials **return a reason and are logged**; they never kill the turn. The agent
 reads the denial and adapts.
@@ -366,7 +366,7 @@ drafts. Merging is a human decision.
 ### Hooks enforce the output contract
 
 - **`Stop`** blocks an agent that has not called its `must_call` tools, *while it
-  still has a turn to fix it* — the conductor would only find out afterwards. It
+  still has a turn to fix it* — the router would only find out afterwards. It
   honours `stop_hook_active`; blocking twice burns budget.
 - **`PostToolUse`** tells an agent immediately when an emitted envelope was
   **held** rather than filed, since discovering that at the end is too late to
@@ -453,8 +453,8 @@ Four tiers, cheapest first:
 1. `qaas validate` then `qaas run --mode pr-check --dry-run` — see the machine
    describe itself, for free
 2. `envelope.py` — the contract everything else moves
-3. `conductor.py::run` — the five phases
-4. `config/agents/conduit.yaml` + `prompts/CONDUIT.md` — what an agent *is*
+3. `router.py::run` — the five phases
+4. `config/agents/api.yaml` + `prompts/API.md` — what an agent *is*
 5. `guardrails.py::check` — the one function both enforcement points call
 6. `.qaas/runs/<id>/ledger.jsonl` from a real run — what actually happened
 
@@ -464,8 +464,8 @@ Four tiers, cheapest first:
 
 Honesty about what is *not* proven, so nobody inherits a false impression:
 
-- **Eight of sixteen agents.** KEYSTONE, VAULT, PULSE, USHER, WARDEN, GAUGE and
-  CHRONICLE are designed but not built.
+- **Eight of sixteen agents.** ARCHITECT, DBA, SOCKET, GUIDE, AUDITOR, LOAD and
+  REPORTER are designed but not built.
 - **The extensibility claim is untested.** "A new agent needs only a prompt and a
   YAML" is the architecture's central promise, and no one has added a ninth agent
   to check it.

{qaas_python-1.0.0 → qaas_python-2.0.0}/BUILD_PLAN.md

@@ -6,8 +6,8 @@
 
 This plan turns that design into a running system. Per the answers given:
 
-- **Runtime** — a Python service on the **Claude Agent SDK** (`claude-agent-sdk`). CONDUCTOR is a real state machine in code; each agent is a `query()` invocation with a hard tool allowlist.
-- **Scope** — the doc's own Phase 1 loop (CARTOGRAPHER, SURFACE, CONDUIT, FORGE, CLERK, PROOF), genuinely end-to-end, on a framework where agents 7–15 are config rather than code.
+- **Runtime** — a Python service on the **Claude Agent SDK** (`claude-agent-sdk`). ROUTER is a real state machine in code; each agent is a `query()` invocation with a hard tool allowlist.
+- **Scope** — the doc's own Phase 1 loop (MAPPER, BROWSER, API, REPRODUCER, TRIAGE, VERIFIER), genuinely end-to-end, on a framework where agents 7–15 are config rather than code.
 - **Target** — a bundled, deliberately-buggy demo app as the system under test, with a golden defect ledger so precision/recall is measurable, not asserted.
 - **Integrations** — every external system behind an adapter with a local fake. The loop runs offline; real Jira/GitHub is a config swap.
 
@@ -19,9 +19,9 @@ Status: plan approved, no code written yet. The milestone table below is the wor
 
 ## Two design decisions that shape everything
 
-**1. CONDUCTOR is Python, not a prompt.** §4.1 says "keep its reasoning shallow — routing, not analysis," and §10 makes it the enforcement point for budget and concurrency. A model cannot enforce a budget it is spending. So the run state machine, dispatch, retries, dead-letter queue, and the §8.3 loop breakers are ordinary code. This also makes runs reproducible and cheap to test.
+**1. ROUTER is Python, not a prompt.** §4.1 says "keep its reasoning shallow — routing, not analysis," and §10 makes it the enforcement point for budget and concurrency. A model cannot enforce a budget it is spending. So the run state machine, dispatch, retries, dead-letter queue, and the §8.3 loop breakers are ordinary code. This also makes runs reproducible and cheap to test.
 
-**2. Every agent is its own top-level `query()`, not a subagent of a parent.** The SDK's `agents=` parameter nests subagents under one conversation; that blurs the per-agent tool allowlist §5.3 depends on and pools cost into one number. Running each agent as a separate `query()` gives a genuine context boundary (design principle §2), an enforceable per-agent allowlist, and per-agent `total_cost_usd` from its `ResultMessage`. `AgentDefinition`/`agents=` stays available for *intra-agent* fan-out (e.g. SURFACE exploring several routes in parallel).
+**2. Every agent is its own top-level `query()`, not a subagent of a parent.** The SDK's `agents=` parameter nests subagents under one conversation; that blurs the per-agent tool allowlist §5.3 depends on and pools cost into one number. Running each agent as a separate `query()` gives a genuine context boundary (design principle §2), an enforceable per-agent allowlist, and per-agent `total_cost_usd` from its `ResultMessage`. `AgentDefinition`/`agents=` stays available for *intra-agent* fan-out (e.g. BROWSER exploring several routes in parallel).
 
 ---
 
@@ -39,7 +39,7 @@ qa-multi-agent-system/
 ├── src/qaas/
 │   ├── envelope.py        # Pydantic DefectEnvelope v1.0 (§6) — the only inter-agent type
 │   ├── registry.py        # AgentSpec (YAML) -> ClaudeAgentOptions
-│   ├── conductor.py       # run state machine, budget governor, concurrency, dead-letter
+│   ├── router.py       # run state machine, budget governor, concurrency, dead-letter
 │   ├── runner.py          # invoke one agent, stream messages, record cost/usage/artifacts
 │   ├── guardrails.py      # can_use_tool + hooks = the §8.1 permission matrix, in code
 │   ├── store.py           # run ledger, artifact store, versioned system-map
@@ -70,22 +70,22 @@ qa-multi-agent-system/
 | `contract_diff` | `diff_openapi`, `classify_breaking`, `find_consumers`, `generate_contract_test` | `openapi.yaml` vs. live routes |
 | `tracker` | `create_issue`, `transition`, `link`, `search` | adapter: local JSON tickets or Atlassian |
 
-WebSocket Harness MCP is deferred — PULSE is Phase 2. Off-the-shelf servers (Playwright, Filesystem, GitHub) are declared as stdio configs in `config/agents/*.yaml`, so adding one is a YAML edit.
+WebSocket Harness MCP is deferred — SOCKET is Phase 2. Off-the-shelf servers (Playwright, Filesystem, GitHub) are declared as stdio configs in `config/agents/*.yaml`, so adding one is a YAML edit.
 
 ### Guardrails are code, not prompting
 
 §8.1's matrix becomes a `Policy` per agent, enforced in `can_use_tool` and a `preToolUse` hook — both of which see the tool name and arguments before execution:
 
-- **Path scoping** — Filesystem/Edit/Write calls resolved and checked against the agent's allowed roots. FORGE and MENDER only; everyone else denied.
+- **Path scoping** — Filesystem/Edit/Write calls resolved and checked against the agent's allowed roots. REPRODUCER and FIXER only; everyone else denied.
 - **Branch scoping** — git writes matched against the agent's branch regex (`qa/repro/*`, `fix/*`); `main` and any force-push denied outright.
-- **Ticket rate limit** — `tracker.create_issue` counted per run/project/day; over cap the call is denied with a reason and CONDUCTOR escalates instead of filing (§4.12).
-- **Immutable test** — MENDER (Phase 3) denied any edit to the test path recorded on the envelope (§10).
+- **Ticket rate limit** — `tracker.create_issue` counted per run/project/day; over cap the call is denied with a reason and ROUTER escalates instead of filing (§4.12).
+- **Immutable test** — FIXER (Phase 3) denied any edit to the test path recorded on the envelope (§10).
 
 Denials return `PermissionResultDeny` with a message, so the agent gets feedback and adapts rather than dying. Every denial is written to the run ledger — that log is the audit trail the doc asks for.
 
 ### The envelope is the only contract
 
-`envelope.py` is a Pydantic model of §6, and agents cannot emit anything else: their sole write path is `envelope.emit_envelope`, which validates and rejects with field-level errors on failure. Prose never crosses an agent boundary. `confidence < 0.6` routes to a human queue instead of CLERK (§7).
+`envelope.py` is a Pydantic model of §6, and agents cannot emit anything else: their sole write path is `envelope.emit_envelope`, which validates and rejects with field-level errors on failure. Prose never crosses an agent boundary. `confidence < 0.6` routes to a human queue instead of TRIAGE (§7).
 
 ---
 
@@ -105,21 +105,21 @@ FastAPI + Postgres + React UI + one WS endpoint. Seed ~14 defects spanning the P
 The six servers above plus local tracker/vcs adapters.
 **Verify:** `pytest tests/mcp` — every tool exercised directly, zero API calls. `defect_memory` proven to dedupe two differently-worded reports of the same defect.
 
-### M3 — Agent runtime + CARTOGRAPHER ✅ done
-`registry.py`, `runner.py`, `guardrails.py`, then the first real agent. CARTOGRAPHER goes first because §4.2 is right that everything downstream gets cheaper once the map exists.
-**Verify:** `qaas run --agent CARTOGRAPHER` writes a versioned `system-map.json` covering the target app's services, routes, schema, and ownership; schema-validated. Guardrail tests assert a write attempt from a read-only agent is denied and logged.
+### M3 — Agent runtime + MAPPER ✅ done
+`registry.py`, `runner.py`, `guardrails.py`, then the first real agent. MAPPER goes first because §4.2 is right that everything downstream gets cheaper once the map exists.
+**Verify:** `qaas run --agent MAPPER` writes a versioned `system-map.json` covering the target app's services, routes, schema, and ownership; schema-validated. Guardrail tests assert a write attempt from a read-only agent is denied and logged.
 
-### M4 — Discovery: CONDUIT + SURFACE ✅ done
-CONDUIT gets `contract_diff` and ships a failing contract test as evidence (§4.5). SURFACE runs scripted journeys first, then exploratory from the Cartographer task graph.
+### M4 — Discovery: API + BROWSER ✅ done
+API gets `contract_diff` and ships a failing contract test as evidence (§4.5). BROWSER runs scripted journeys first, then exploratory from the Mapper task graph.
 **Verify:** `qaas run --mode pr-check` emits envelopes; `qaas score` reports how many golden defects in those two domains were found and how many findings were not in the ledger.
 
-### M5 — Triage: FORGE + CLERK ✅ done
-FORGE reproduces, minimizes, runs N times for flake rate, and commits a failing test to `qa/repro/*`. CLERK dedupes, scores against the rubric, resolves owner from the map, routes, and files — the only agent holding tracker write.
+### M5 — Triage: REPRODUCER + TRIAGE ✅ done
+REPRODUCER reproduces, minimizes, runs N times for flake rate, and commits a failing test to `qa/repro/*`. TRIAGE dedupes, scores against the rubric, resolves owner from the map, routes, and files — the only agent holding tracker write.
 **Verify:** full discovery→triage run produces local tickets with real repro steps and attached failing tests; a second run on the same code files **zero** new tickets and increments occurrence counts instead.
 
-### M6 — Close the loop: PROOF + CONDUCTOR run modes ✅ done, verified live
-PROOF re-runs FORGE's test against a patched build and returns `VERIFIED`/`NOT_FIXED`/`REGRESSED`. CONDUCTOR gains all five discovery run modes, budget governor, concurrency caps, and escalation.
-**Verify:** the acceptance test for the whole system — fix one seeded defect by hand on a branch, run `qaas run --mode fix-cycle --ticket <id>`, and PROOF returns `VERIFIED`; revert the fix and it returns `NOT_FIXED`. Then `qaas run --mode nightly && qaas score` prints the §12 scorecard: acceptance rate, duplicate rate, false-positive rate, cost per accepted ticket.
+### M6 — Close the loop: VERIFIER + ROUTER run modes ✅ done, verified live
+VERIFIER re-runs REPRODUCER's test against a patched build and returns `VERIFIED`/`NOT_FIXED`/`REGRESSED`. ROUTER gains all five discovery run modes, budget governor, concurrency caps, and escalation.
+**Verify:** the acceptance test for the whole system — fix one seeded defect by hand on a branch, run `qaas run --mode fix-cycle --ticket <id>`, and VERIFIER returns `VERIFIED`; revert the fix and it returns `NOT_FIXED`. Then `qaas run --mode nightly && qaas score` prints the §12 scorecard: acceptance rate, duplicate rate, false-positive rate, cost per accepted ticket.
 
 ### Skills, hooks and loops ✅ done
 
@@ -141,17 +141,17 @@ that nothing counted. `Stop` blocks an agent that skipped its declared
 deliverable (`must_call` in its config), honouring `stop_hook_active` so a
 genuinely stuck agent cannot loop the budget away.
 
-**Loops** — `_phase_verify` is now a bounded remediation loop: PROOF → NOT_FIXED
-→ MENDER → ARBITER → PROOF, enforcing `max_proof_reopens` and
-`max_mender_arbiter_round_trips` from §8.3. PROOF's verdict is a typed ledger
-entry (`record_verdict`), never parsed from prose. With no MENDER in the Phase 1
-roster a NOT_FIXED escalates immediately instead of re-running PROOF against
+**Loops** — `_phase_verify` is now a bounded remediation loop: VERIFIER → NOT_FIXED
+→ FIXER → REVIEWER → VERIFIER, enforcing `max_proof_reopens` and
+`max_mender_arbiter_round_trips` from §8.3. VERIFIER's verdict is a typed ledger
+entry (`record_verdict`), never parsed from prose. With no FIXER in the Phase 1
+roster a NOT_FIXED escalates immediately instead of re-running VERIFIER against
 unchanged code. `qaas sweep` is the cron entry point: run, score, and exit
 non-zero below the §11 precision gate.
 
 ### M7 — Phase 3: the fix loop (beyond the original plan)
 
-MENDER and ARBITER, with the §8.2 autonomy envelope enforced in `guardrails.py`
+FIXER and REVIEWER, with the §8.2 autonomy envelope enforced in `guardrails.py`
 rather than requested in a prompt: a diff budget counted per distinct file, and
 forbidden path classes (migrations, auth, payment, secrets, infrastructure, CI)
 that stop at a human however small the change looks. `record_review` refuses a
@@ -161,8 +161,8 @@ review. Two new run modes: `fix-cycle` and `full-loop`.
 Merge remains impossible by construction: no merge method exists anywhere in the
 codebase, `gh pr merge` is refused, and pull requests open as drafts.
 
-**Verify:** conductor tests prove the bounded loop (PROOF → MENDER → ARBITER →
-PROOF, capped by `max_mender_arbiter_round_trips` and `max_proof_reopens`), and
+**Verify:** router tests prove the bounded loop (VERIFIER → FIXER → REVIEWER →
+VERIFIER, capped by `max_mender_arbiter_round_trips` and `max_proof_reopens`), and
 guardrail tests prove every forbidden class and the diff budget. Live: a
 `full-loop` run on the demo app that ends in a VERIFIED ticket.
 
@@ -175,9 +175,9 @@ turned up two defects in this system rather than one in the target:
    reporting no fixture and no way to pin a reproduction's environment. It
    truncates first now.
 2. `_verify_loop` re-read the branch off the envelope on every pass. That is the
-   *repro* branch, written before a fix exists, so PROOF was sent back to the
+   *repro* branch, written before a fix exists, so VERIFIER was sent back to the
    unfixed branch it had just failed on. VERIFIED was unreachable by
-   construction. The loop now reads MENDER's branch out of the ledger, scoped to
+   construction. The loop now reads FIXER's branch out of the ledger, scoped to
    the entries one remediation round appended.
 
 Both are the point of running the thing live: neither was visible to 528 offline
@@ -185,10 +185,10 @@ tests, and (2) meant no `full-loop` run could ever have closed.
 
 **A third defect, found only by re-running.** CORVID-7 then escalated twice with
 a correct one-line fix sitting on the branch, because two rules in this repo
-contradicted each other: `CLAUDE.md` required MENDER to retire the seeded
-defect's ledger entry in the same commit, and `mender.yaml`'s `write_paths`
-forbade it. MENDER tried and the guardrail refused
-(`Edit  write refused: target-app/defects.yaml is outside MENDER's sandbox`).
+contradicted each other: `CLAUDE.md` required FIXER to retire the seeded
+defect's ledger entry in the same commit, and `fixer.yaml`'s `write_paths`
+forbade it. FIXER tried and the guardrail refused
+(`Edit  write refused: target-app/defects.yaml is outside FIXER's sandbox`).
 Every seeded defect has a ledger entry, so this deadlocked *any* fix to any of
 them. The sandbox was right and the rule was wrong: the ledger is the answer key
 and must stay unwritable by the agents it scores, so the same-commit obligation
@@ -198,16 +198,16 @@ lesson — never request a change the author is not permitted to make.
 **Closed live on CORVID-8**, 2026-09-08, `fix-cycle`, $6.84, zero escalations:
 
 ```
-PROOF   NOT_FIXED   defect confirmed present
-MENDER              currency: str added to InvoiceOut (1 line of product code)
-ARBITER APPROVE
-PROOF   VERIFIED    re-verified on MENDER's branch
+VERIFIER   NOT_FIXED   defect confirmed present
+FIXER              currency: str added to InvoiceOut (1 line of product code)
+REVIEWER APPROVE
+VERIFIER   VERIFIED    re-verified on FIXER's branch
 ```
 
-PROOF ran the original failing test 5 of 5 times for flake, then the full 22-test
+VERIFIER ran the original failing test 5 of 5 times for flake, then the full 22-test
 `qa/repro` suite, and correctly attributed all 11 failures to other open tickets
 (CORVID-7, CORVID-SEC-6) with source confirmation rather than to the diff. The
-second PROOF dispatch is the hop the branch-selection fix above made reachable at
+second VERIFIER dispatch is the hop the branch-selection fix above made reachable at
 all. Verified independently afterwards: the diff is one product line and the live
 endpoint returns `currency`.
 
@@ -235,13 +235,13 @@ verdicts, no escalations, no tickets. The audit trail existed; the audit did not
   call instead of inventing a 29th kind no reader looks for.
 - **Two provenance gaps closed.** `agent_started` recorded `task_chars=len(task)`
   — the length of the prompt, not the prompt — so the instruction an agent
-  actually received was unrecoverable and five FORGE dispatches differed only by
+  actually received was unrecoverable and five REPRODUCER dispatches differed only by
   character count; the task now goes to the artifact store with a preview inline.
   And `run_started` recorded no commit, so a run was not pinned to the code it
   examined; it now carries the target's sha, branch and dirty flag.
 
 **Verify:** `pytest tests/test_trace.py` — 29 tests over a synthetic ledger and a
-scripted conductor, offline. Includes an AST sweep asserting every literal passed
+scripted router, offline. Includes an AST sweep asserting every literal passed
 to `store.log()` anywhere in `src/qaas/**` is a `LedgerKind` member, so the next
 kind added cannot go missing from the readers.
 
@@ -251,7 +251,7 @@ kind added cannot go missing from the readers.
 test", through `ToolContext.repo_root` and `SystemConfig.target_app`. That is
 true of exactly one target — the bundled demo, which happens to sit inside this
 checkout — and false for every other. `ToolContext.target_root` now comes from
-`profile.root_path()`, `SystemConfig.target_app` is gone, and MENDER's
+`profile.root_path()`, `SystemConfig.target_app` is gone, and FIXER's
 `write_paths` are target-relative (`api/app`, not `target-app/api/app`).
 
 `qaas run --repo <path-or-url>` follows from the split: it clones into
@@ -270,7 +270,7 @@ rather than layered by filename, so the first generated profile hid every
 hand-written one.
 
 ### Adding agents 7–15 afterwards
-A new discovery agent should be a prompt file plus a `config/agents/<NAME>.yaml` naming its allowlist — no changes to conductor, runner, or guardrails. Whether that holds is the real test of M3, so the first Phase-2 agent (VAULT) will be added as a smoke test of the extension path before this build is called done.
+A new discovery agent should be a prompt file plus a `config/agents/<NAME>.yaml` naming its allowlist — no changes to router, runner, or guardrails. Whether that holds is the real test of M3, so the first Phase-2 agent (DBA) will be added as a smoke test of the extension path before this build is called done.
 
 ---
 
@@ -278,7 +278,7 @@ A new discovery agent should be a prompt file plus a `config/agents/<NAME>.yaml`
 
 Every run spends real money, and a nightly sweep is the expensive one. Controls, from the start:
 
-- Per-agent and per-run `max_budget_usd` on `ClaudeAgentOptions`; CONDUCTOR aborts the run at the cap and records partial results.
+- Per-agent and per-run `max_budget_usd` on `ClaudeAgentOptions`; ROUTER aborts the run at the cap and records partial results.
 - `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` and `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` set via `env` — Opus 5 delegates readily, and an unbounded subagent tree is the fastest way to a surprise bill.
 - `--dry-run` renders each agent's exact options and prompt without calling the API; used in unit tests.
 - A cheap CI profile (lower effort, smaller model for the mechanical agents) separate from the full profile.
@@ -286,7 +286,7 @@ Every run spends real money, and a nightly sweep is the expensive one. Controls,
 
 Auth: no `ANTHROPIC_API_KEY` is set here, but the Claude Code CLI (v2.1.263) is installed and authenticated, and the Agent SDK drives it — so it works as-is. `ANTHROPIC_API_KEY` remains the CI path.
 
-Model default is `claude-opus-5` for judgment-heavy agents (CONDUIT, SURFACE, ARBITER later) and a cheaper model for mechanical ones (CARTOGRAPHER extraction, CLERK composition), set per agent in `config/agents/*.yaml`.
+Model default is `claude-opus-5` for judgment-heavy agents (API, BROWSER, REVIEWER later) and a cheaper model for mechanical ones (MAPPER extraction, TRIAGE composition), set per agent in `config/agents/*.yaml`.
 
 ---
 
@@ -302,5 +302,5 @@ Four tiers, cheapest first:
 ## Risks
 
 - **Hook event names.** The SDK's `HookEvent` literals differ between docs and releases (`preToolUse` vs `PreToolUse`). M3 pins them by introspecting the installed `claude_agent_sdk` rather than trusting the docs, and `can_use_tool` carries the guardrails so a hook-name regression degrades logging, not enforcement.
-- **Exploratory SURFACE is the noisiest agent.** It ships behind the confidence gate and the per-run finding cap from day one; if its false-positive rate is bad in M4, it runs scripted-only until the ledger says otherwise.
+- **Exploratory BROWSER is the noisiest agent.** It ships behind the confidence gate and the per-run finding cap from day one; if its false-positive rate is bad in M4, it runs scripted-only until the ledger says otherwise.
 - **Seeded defects are easier than real ones.** The golden ledger measures whether the loop works, not whether it is good at finding hard bugs. Treat 100% recall on `defects.yaml` as a floor, never as evidence the system is ready for a real codebase.