@multileaf/ai-workflow 0.8.0 → 0.10.0

package/docs/architecture.md

@@ -45,6 +45,56 @@ Project analysis is hybrid: deterministic detectors establish observable facts,
 
 ## Human workflow approvals
 
+Workflows run in one of two lanes. The **full lane** (default, and the only non-interactive default) is the staged approval sequence below. The **light lane** (`aiw task start --lane=light --lane-reason=...`, human-chosen via the resume test — work is small when it could be resumed from the request plus `git diff`) skips durable spec/plan artifacts: validation evidence is recorded per entry (`aiw task evidence`), completion requires at least one entry, and the lane plus rationale are written into the session and approval ledger for audit. Stage commands in the light lane block with a `lane_escalation_required` reason until `aiw task escalate --reason=...` moves the workflow to the full lane; recorded evidence is preserved and linked. Escalation is one-way; the full lane then runs the complete approval sequence.
+
+## Current flow
+
+```mermaid
+flowchart TD
+    REQ["Change request / ticket"] --> RA["aiw risk assess<br/>read-only · content-based · deterministic"]
+    RA -->|"passive — docs-only"| LANE
+    RA -->|"medium — plain code"| LANE
+    RA -->|"high — security · contracts · concurrency ·<br/>data · delivery · untested (risk due: yes)"| FS
+
+    LANE{"Human lane decision<br/>resume test: resumable from<br/>request + git diff?"}
+    LANE -->|"light — human chooses"| LS
+    LANE -->|"full — default"| FS
+
+    subgraph LIGHT["Light lane — no durable artifacts"]
+        LS["aiw task start --lane=light --lane-reason<br/>rationale into session + ledger"] --> LE["aiw task evidence --validation<br/>compact checkpoint"]
+        LE --> LC["aiw workflow complete<br/>requires at least one entry"]
+    end
+
+    subgraph FULL["Full lane — staged SDD, gate + human approve per stage"]
+        FS["workflow start"] --> BR["brainstorming"] --> SP["specification"] --> TD["technical-design<br/>optional, skip needs reason"] --> PL["plan"] --> IM["implementation<br/>TDD"] --> VE["verification"] --> RV["code review"] --> TR["traceability"] --> FC["workflow complete"]
+    end
+
+    LS -.->|"stage or approve attempted"| B1["Blocked<br/>reason: lane_escalation_required"]
+    B1 --> ESC["aiw task escalate --reason<br/>one-way · evidence preserved"]
+    ESC --> FS
+
+    RV -.->|"adversarial-review skills installed"| ADV["judge A + judge B — blind, independent<br/>refuter: corroborated severe blocks<br/>refuted / inconclusive → advisory<br/>unevidenced severe → advisory"]
+
+    LC --> AUD["Audit trail<br/>approvals ledger · checkpoints · light evidence"]
+    FC --> AUD
+
+    subgraph CI["CI enforcement layer"]
+        E1["OPP-004: every block prints a reason code<br/>plus an exact next_command — continuations<br/>are executed by tests before they ship"]
+        E2["OPP-006 ratchet: every aiw command named<br/>by skills and READMEs executes in tests"]
+        E3["OPP-005 friction benchmark:<br/>in-band / out-of-band / dead-end<br/>budget: zero dead ends"]
+    end
+
+    B1 -.-> E1
+    E1 -.-> E2 -.-> E3
+```
+
+Reading notes:
+
+- `aiw risk assess` is **advisory**: it informs the lane decision and flags risk due; it never forces a lane or bypasses approval.
+- The light lane is never agent-chosen: `resources/skills/ticket.md` routes it through the host's blocking question widget with the resume test stated verbatim.
+- Every blocking exit on the diagram prints `[reason: <code>]` and either `Next: run \`aiw ...\`` or an explicit terminal statement — the full mapping lives in [Continuation inventory](continuation-inventory.md).
+- A `high` risk assessment with an active workflow points at continuing the workflow (gate and approve); without one it names `aiw workflow start`.
+
 The SDD approval contract models the ordered stages brainstorming, specification, technical design, plan, implementation, verification, review, and traceability. Brainstorming and technical design are optional; skipping either requires a human-accepted reason. Every other stage must be approved. Automated quality-gate results are stored separately from human decisions and can only move an artifact to pending review, never directly to approved.
 
 Each approval is scoped to one workflow ID and bound to a SHA-256 fingerprint of the exact artifact reviewed, so a later feature cannot reuse earlier approvals. A content change or rejection makes that stage and its descendants stale. The CLI persists the versioned ledger in `.aiw/approvals.yml`, blocks stage commands when prerequisites are unresolved, and keeps passing quality gates distinct from human approval. The generated bootstrap and stage skills require the host's native blocking question widget for human decisions when available, with a waiting chat prompt as fallback. Approval records provide an audit trail but cannot prove the identity of a respondent or independently verify that the host widget was used.

package/docs/backlog.md

@@ -109,6 +109,19 @@ Priority levels: **P0** blocks the product or makes it unsafe; **P1** is require
 
 - [x] **ENG-001** Update GitHub Actions to Node 24-native versions. _Acceptance:_ `actions/checkout` and `actions/setup-node` upgraded past v4 so release workflows no longer emit Node.js 20 deprecation warnings; CI and Release workflows pass on `ubuntu-latest` before and after the October 19, 2026 Ubuntu 26 runner migration.
 
+## Workflow proportionality (ODD/RDD analysis) — P1–P3
+
+Derived from the Gentle-AI ODD/RDD analysis; scope and rejected alternatives recorded in [ADR-001](../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md). Each item links to a self-contained opportunity document under `docs/opportunities/` and can be implemented independently.
+
+- [x] **OPP-001** Add a light lane for small, understood work (proportional ceremony). _Acceptance:_ see [OPP-001](../opportunities/OPP-001-proportional-ceremony-light-lane.md); no durable spec/plan artifacts for light tasks, evidence and lane rationale still recorded, explicit escalation to the full lane on scope growth, full lane unchanged.
+- [x] **OPP-002** Add `aiw risk assess` — read-only, content-based risk classification with an exact runnable next command. _Acceptance:_ see [OPP-002](../opportunities/OPP-002-risk-assess-command.md); deterministic and offline by default, no `.aiw/` mutation, escalation raises and never lowers tier, `next_command` executes as printed.
+- [x] **OPP-003** Ship an optional `adversarial-review` package (blind judges + refuter with proof-carrying findings). _Acceptance:_ see [OPP-003](../opportunities/OPP-003-adversarial-review-package.md); severe findings without reproducible evidence degrade to advisory; refutation outcomes are corroborated/refuted/inconclusive with proof references; human acceptance still required.
+- [ ] **OPP-004** Emit typed reason codes and exact continuation commands on every blocking exit. _Acceptance:_ see [OPP-004](../opportunities/OPP-004-exact-continuation-commands.md); every block carries a reason code and either a tested runnable `next_command` or an explicit terminal statement; continuation inventory stays complete in CI.
+- [x] **OPP-005** Add a friction benchmark classifying blocks as in-band / out-of-band / dead-end over packaged-CLI journeys. _Acceptance:_ see [OPP-005](../opportunities/OPP-005-friction-benchmark.md); deterministic classification, continuations actually executed, CI fails on any dead end.
+- [x] **OPP-006** Adopt the emission ≠ usability test policy: messages naming a command must have a test executing it. _Acceptance:_ see [OPP-006](../opportunities/OPP-006-emission-usability-test-policy.md); extraction helper covers emitted and generated command mentions; generated `ai-init` skills' commands are executed in e2e tests.
+- [ ] **007-decision-findings-triage-scope-watch** Decision model — findings-evidence triage and lane scope-watch (advisory-only). _Acceptance:_ see [OPP-007](../opportunities/OPP-007-decision-findings-triage-scope-watch.md); unconfigured = byte-identical offline behavior; advisory flags never block, never lower tiers, never choose lanes.
+- [ ] **008-embedding-covering-tests-judge-context** Embedding retrieval — covering-test detection and judge context scoping. _Acceptance:_ see [OPP-008](../opportunities/OPP-008-embedding-covering-tests-judge-context.md); retrieval only prevents false `untested` flags (absence fails safe toward high); scoped judge prompts labeled as context aids within token ceilings.
+
 ## Backlog rules
 
 - [x] **FND-009** Add self-validation workflow. _Acceptance:_ changes affecting AIW behavior execute against this repository and record generated-output evidence.

package/docs/continuation-inventory.md

@@ -0,0 +1,21 @@
+# Continuation Inventory
+
+Every blocking `aiw` exit carries a stable reason code plus either an exact runnable continuation or an explicit terminal statement. A message may name a command only when running that command resolves the block it was printed for (OPP-004, [ADR-001](../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md)).
+
+- Codes are declared in `src/blocking-reasons.ts` (`BLOCKING_REASON_CODES`); adding a code requires a definition with a continuation producer and a test.
+- With `--json`, blocking exits return `{ "reason_code": ..., "next_command" | "next_action" | "terminal": ... }`.
+- The table below is generated from the registry; a test in `src/blocking-reasons.test.ts` fails CI when this page drifts from the code.
+
+| Reason code                     | Description                                                                                   | Continuation     |
+| ------------------------------- | --------------------------------------------------------------------------------------------- | ---------------- |
+| `gate_evidence_missing`         | The quality gate is blocked because the required evidence artifact is missing.                | explicit action  |
+| `gate_incomplete`               | The quality gate found completeness issues in the stage artifact.                             | explicit action  |
+| `stage_prerequisite_pending`    | A previous stage is awaiting human approval before this stage can start.                      | runnable command |
+| `stage_prerequisite_unresolved` | Previous stages need human approval or an accepted optional skip before this stage can start. | runnable command |
+| `stage_awaiting_approval`       | This stage is awaiting human approval; approve or reject it before continuing.                | runnable command |
+| `stage_already_approved`        | This stage is already approved; changed evidence requires rerunning its quality gate.         | runnable command |
+| `approval_evidence_missing`     | Approval cannot be recorded because the stage evidence artifact is missing.                   | explicit action  |
+| `approval_stale`                | The artifact changed after review; its approval is stale and the gate must run again.         | runnable command |
+| `approval_gate_missing`         | No passing quality gate is recorded for this stage; gate it before approving.                 | runnable command |
+| `lane_escalation_required`      | Light-lane workflows do not author stage artifacts; escalate to the full lane to continue.    | explicit action  |
+| `light_evidence_missing`        | A light-lane workflow cannot complete without at least one recorded validation entry.         | explicit action  |

package/docs/decision-model-evaluation.md

@@ -40,3 +40,7 @@ Observed behavior on real plans: an evidence-free plan scored `gate: ready` with
 ## Hard boundary (unchanged)
 
 Decision-model output is `inferred` evidence with confidence, never `confirmed`. It can move an artifact to _pending review_, never to _approved_, and cannot replace the fingerprinted human approval ledger. This matches the existing approval contract and keeps the audit trail human-owned.
+
+## Planned integration (OPP-007)
+
+The next planned decision-model roles follow the same contracts: findings-evidence triage for severe review findings (does the cited proof support the claim — advisory flag, the refuter still decides) and a lane scope-watch that flags mismatch between a chosen light lane and deterministic risk signals. Both stay advisory-only with the deterministic floor unchanged; unconfigured behavior is byte-identical. See [OPP-007](opportunities/OPP-007-decision-findings-triage-scope-watch.md).

package/docs/opportunities/OPP-001-proportional-ceremony-light-lane.md

@@ -0,0 +1,62 @@
+# OPP-001: Proportional ceremony — light lane for small, understood work
+
+- Status: Implemented (2026-10-30, plan Wave 4)
+- Priority: P2
+- Added: 2026-10-30
+- Decision: [ADR-001](../../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md), Decision A
+
+## Problem
+
+Every AI Workflow task, regardless of size or risk, traverses the same staged pipeline (brainstorm → specification → ADR → plan → implementation → verification → review → traceability), each stage producing durable artifacts under `.aiw/generated/`. For small, well-understood changes this generates artifacts nobody reads, and users bypass the workflow manually — which then produces no evidence at all. Gentle-AI retired SDD for exactly this reason; the market signal is that uniform ceremony causes abandonment in daily use.
+
+## Source concept (ODD)
+
+ODD classifies task size with the **resume test**: work is _small_ when it is understood, risk is contained, and the work could be resumed from the original request plus `git diff`. Small work creates **no durable task artifacts**; substantial work creates exactly one feature document before the first source write. ODD also holds that findings never silently expand authorization, and scope growth is an explicit event.
+
+References:
+
+- Gentle-AI `docs/usage.md`, section "Organic Driven Development (ODD)" — protocol steps 4 (Classify) and 5 (Track before the first write)
+- Gentle-AI `docs/intended-usage.md` — "Small, understood changes need no persistent task artifact"
+
+## Proposal
+
+Add a **light lane** alongside the existing full SDD lane:
+
+1. New flag `aiw task start --lane=light` (full lane remains the default).
+2. Entry criteria, evaluated and recorded at start — all must hold:
+   - the change is understood well enough to resume from the request plus `git diff` (the ODD resume test, stated verbatim in the command output so the human makes the call);
+   - expected blast radius is contained (no new requirement IDs, no architecture decision needed);
+   - TDD applies or an exception is recorded with reason.
+3. Light-lane behavior:
+   - No durable spec/plan/report artifacts are scaffolded.
+   - Evidence is still required: task validation commands run and completion evidence is recorded in `.aiw/checkpoints/` (compact form, linked to the ticket if present).
+   - The lane decision and its entry criteria are persisted, so audits can see why the light lane was used.
+4. Escalation: if scope grows beyond the entry criteria (new requirement, ADR needed, risk found), the task must escalate to the full lane; the escalation is an explicit recorded event, never a silent expansion. Escalation preserves already-recorded evidence.
+
+## Affected areas
+
+- `src/workflow.ts`, `src/types.ts` (lane state, escalation event)
+- CLI: task/workflow commands (`src/cli.ts`)
+- Stage skills and templates rendered through adapters (resources that describe the SDD sequence)
+- `docs/README.md` (main README workflow section), `docs/architecture.md` (approval contract description)
+- Checkpoint/evidence recording (`src/evidence.ts`, `src/human-approval.ts` interactions)
+
+## Acceptance criteria
+
+- Given a task started with `--lane=light`, when no scope growth occurs, then completion requires no `specification.md`/`implementation-plan.md` artifacts and records validation evidence plus the lane rationale in checkpoints.
+- Given a light-lane task, when scope growth is detected (or declared), then escalation to the full lane is required before further stage commands run, and prior evidence is preserved and linked.
+- Given the full lane (default), when a task starts, then behavior is unchanged from today.
+- Given a light-lane completion, when `.aiw/approvals.yml` is inspected, then the ledger shows the light-lane rationale, not a missing approval.
+- Non-interactive runs without an explicit lane default to the full lane.
+
+## Non-goals
+
+- No global "workflow off" switch (see ADR-001 Decision B).
+- No change to full-lane stage order, gates, or approval semantics.
+- No automatic lane detection that overrides the human's classification; automation may only suggest.
+
+## Open questions
+
+- Should the light lane allow skipping the brainstorm/spec stages only, or also merge implementation + verification evidence into a single checkpoint artifact?
+- Should escalation be self-declared by the agent, human-confirmed, or both (recommend both: agent proposes, human confirms)?
+- Does the lane need representation in `traceability` output (e.g., a light-lane marker on the ticket)?

package/docs/opportunities/OPP-002-risk-assess-command.md

@@ -0,0 +1,70 @@
+# OPP-002: `aiw risk assess` — content-based risk classification with an exact next command
+
+- Status: Implemented (2026-10-30, plan Wave 2); optional decision-model advisory refinement remains a follow-up
+- Priority: P2
+- Added: 2026-10-30
+- Decision: [ADR-001](../../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md), Decision A
+
+## Problem
+
+AI Workflow applies the same gate and review depth to every change. A two-line edit to authentication handling and a thousand-line documentation addition produce identical ceremony. There is no command that answers, before deciding how much process a change needs: _what is the risk of this change, why, and what should I run next?_
+
+## Source concept (RDD)
+
+RDD's `gentle-ai review assess` is a **read-only** risk classification that:
+
+- builds the same candidate a review would, without creating any authority or mutating state;
+- classifies risk by **what changed**, never by size — a README edit is `passive` (zero reviewers), two lines of login code is `high` (four reviewers);
+- reports a typed tier (`passive` / `medium` / `high`), machine-readable reasons with paths, and a **`next_transition.command`**: the exact, literally runnable next command, so callers never reconstruct invocations from prose;
+- supports agent escalation: an agent may raise (never lower) risk citing one of six high-risk items — 1 data/irreversible effects, 2 security, 3 contracts others consume, 4 concurrency, 5 delivery/environment, 6 no test would catch a regression.
+
+References:
+
+- Gentle-AI `docs/review-integration.md`, section "Read-only risk assessment (`gentle-ai review assess`)" — includes the `gentle-ai.review-assessment/v1` JSON envelope example
+- Gentle-AI `docs/architecture/organic-rdd.md` — risk tier → lens selection (low: structural readback, 0 lenses; medium: 1 lens; high: canonical 4R)
+
+## Proposal
+
+Add `aiw risk assess`:
+
+```bash
+aiw risk assess [--ticket=PROJ-142] [--base-ref <ref>] [--json]
+aiw risk assess --escalate-item <1-6> --escalate-reason "<one line>"
+```
+
+1. **Inputs**: working tree changes by default; or `--base-ref` for a committed base-to-HEAD comparison (mirroring RDD's `--base-ref --committed-only`).
+2. **Classification layers** (deterministic first, model optional):
+   - deterministic path/content rules for the six high-risk categories (auth/security surfaces, exported contracts, concurrency primitives, migrations/irreversible data ops, delivery/environment scripts, code with no covering test);
+   - the existing `decision` module (advisory) may refine reasons when enabled — output stays advisory and never changes evidence states or bypasses approval, consistent with the decision-model contract.
+3. **Output tiers**: `passive` (documentation-only or no risk category hit), `medium`, `high`, with typed reasons `[{"code": "...", "path": "..."}]` and, with `--json`, a schema-versioned envelope (e.g., `aiw.risk-assessment/v1`).
+4. **Exact continuation**: when the tier warrants more process, the output includes `next_command`: the literal runnable `aiw` command (e.g., start the full lane, or open a gate). Follows OPP-004's rule: a next command is printed only when running it resolves the decision at hand.
+5. **Escalation**: `--escalate-item`/`--escalate-reason` raise `passive`/`medium` to `high`, never lower a tier; both flags together, reason ≤ 500 bytes, one line.
+6. **Read-only guarantee**: no writes to `.aiw/`, no approval or gate state changes, works offline with no model configured.
+
+## Affected areas
+
+- New command module + tests (pattern: `src/decision.ts`, `src/evidence.ts`)
+- `src/quality-gates.ts` / `src/human-gates.test.ts` conventions for envelope schemas
+- `src/scanner.ts` reuse for change/path detection (ignore-aware)
+- CLI wiring (`src/cli.ts`), docs (`docs/README.md`, `docs/decision-model-evaluation.md` cross-link)
+
+## Acceptance criteria
+
+- Given a documentation-only diff, when `aiw risk assess --json` runs, then tier is `passive` and no reviewer escalation is suggested.
+- Given a diff touching an authentication module, when assessed, then tier is `high` with a reason naming the path and the security category.
+- Given any invocation, when it completes, then no file under `.aiw/` changed (read-only proof in tests).
+- Given `review_due`-style output, when a next step is warranted, then `next_command` executes successfully as printed (tested by executing it).
+- Given `--escalate-item 2 --escalate-reason "..."`, when the base tier is `medium`, then output tier is `high`; escalation never lowers a tier.
+- Given no decision model configured, when assessing, then classification is fully deterministic and offline.
+
+## Non-goals
+
+- No automatic gate skipping or approval bypass based on tier (tiers inform humans and agents; they do not decide).
+- No review lifecycle/authority machinery (RDD's lineages and burns are out of scope — see ADR-001 Decision B).
+- No model-only classification: deterministic rules are the floor; the model layer is optional refinement.
+
+## Open questions
+
+- Should `--ticket` bind the assessment into the checkpoint ledger for audit (write-only log, no approval state)?
+- Which concrete path rules seed the six categories for this repository's own stack (self-hosting dogfood)?
+- Should the light lane (OPP-001) consume `risk assess` output as an entry-criteria signal (advisory only)?

package/docs/opportunities/OPP-003-adversarial-review-package.md

@@ -0,0 +1,63 @@
+# OPP-003: Adversarial review package — blind judges and proof-carrying findings
+
+- Status: Implemented (2026-10-30, plan Wave 6): skills shipped in the self-hosting package with content-rule tests; runtime permission wiring rides the existing package permission model
+- Priority: P3
+- Added: 2026-10-30
+- Decision: [ADR-001](../../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md), Decision A
+
+## Problem
+
+AI Workflow's review stage uses the `code-review` skill when installed, but findings are accepted as written: nothing in the workflow attempts to _refute_ severe claims, no second independent reviewer cross-checks the first, and findings do not have to carry reproducing evidence. The result is both false positives (blocking work on an unreal defect) and unearned authority (a plausible-sounding severe finding with no proof).
+
+## Source concept (RDD / Judgment Day)
+
+Two Gentle-AI mechanisms address exactly this:
+
+1. **Refuter**: every severe (BLOCKER/CRITICAL) finding with candidate causality reaches an adversarial pass that may confirm or **drop** the claim. On runtimes that support isolation (e.g., Codex), the refuter may run one reproducing command per claim inside a disposable scratch directory (fresh `mktemp -d`, no network, sandboxed, destroyed afterwards); the finding must cite the command and its observed output. A refuted finding becomes an `advisory`; corroborated and inconclusive findings go forward. Non-severe findings never reach the refuter.
+2. **Judgment Day blind judges**: review by two independent judge agents (`jd-judge-a`, `jd-judge-b`) plus a fix agent (`jd-fix-agent`), so no single reviewer's output is authoritative.
+
+References:
+
+- Gentle-AI `docs/review-integration.md`, section "Refuter probe" (isolation matrix per runtime, proof requirements, `probe unavailable on <runtime>` honesty marker)
+- Gentle-AI `docs/kiro.md`, section "ODD Execution Model" — Judgment Day adversarial review agents
+
+## Proposal
+
+Ship an **optional versioned resource package** `adversarial-review` through the existing package model and registry:
+
+1. Package contents:
+   - `review-judge-a` and `review-judge-b` agent/skill definitions: two independent reviewers of the same diff, each reporting findings with severity and required evidence fields; neither sees the other's output (blind).
+   - `review-refuter` skill: takes severe findings and attempts to refute each — by reading cited code, and, where the host runtime supports safe isolation, by running the cited reproducing command in a disposable directory; marks each finding `corroborated` / `refuted` / `inconclusive` with proof references.
+   - Rules rendered into the workflow's review stage: a severe finding without a reproducing command or file:line evidence degrades to `advisory`; only `corroborated` severe findings can block.
+2. Integration points:
+   - Declared in the package manifest with permissions (needs command execution for the refuter — flagged as a sensitive capability through the existing package permission/policy model).
+   - The review stage template/skill references the package when installed; the existing rule applies that a human must still accept the review outcome.
+3. Honesty markers: when the host runtime cannot isolate command execution, the refuter marks results accordingly (the RDD pattern: state that no command ran, rather than implying verification).
+
+## Affected areas
+
+- `resources/` (new package), `resources/package.yaml` conventions
+- `src/package-audit.ts` / `src/policy-gate.ts` (refuter execution is a sensitive capability needing explicit permission)
+- Review-stage skill templates and `docs/README.md` review section (currently: "Code review is performed with the `code-review` skill when installed")
+- Registry listing (`src/registry.ts`)
+
+## Acceptance criteria
+
+- Given the package installed, when the review stage runs, then two blind judges receive the same diff independently and produce separately attributable findings.
+- Given a severe finding without a reproducing command or file:line evidence, when the refuter processes it, then it is downgraded to `advisory` with the reason recorded.
+- Given a severe finding whose cited command fails to reproduce the defect, when the refuter runs it (isolated runtime), then the finding is marked `refuted` and does not block.
+- Given a runtime without isolation support, when the refuter runs, then results carry an explicit "no command executed" marker rather than silent omission.
+- Given the package's execution permission, when it is not granted, then the refuter degrades to evidence-reading mode and the outcome states so.
+- Human acceptance of the review outcome remains required (package never auto-accepts).
+
+## Non-goals
+
+- No new CLI gate command for review (the existing contract stays: code review via skill, human accepts outcome).
+- No frozen synthetic trees or review authority machinery (ADR-001 Decision B); the package operates on the working diff/cited files.
+- No requirement that both judges agree: disagreement is reported, not averaged away.
+
+## Open questions
+
+- Should judge outputs be recorded under `.aiw/generated/artifacts/` as versioned review evidence for the traceability graph?
+- Which target adapters can safely host isolated command execution for the refuter (Codex sandbox vs Claude Code vs local-only)?
+- Package name and whether `code-review` (existing) becomes judge-a or stays separate.

package/docs/opportunities/OPP-004-exact-continuation-commands.md

@@ -0,0 +1,59 @@
+# OPP-004: Exact continuation commands — every block names a runnable way out
+
+- Status: Partially implemented (2026-10-30, plan Wave 1): workflow, gate, and approval paths emit typed reason codes, continuations, and `--json` envelopes; sync/apply conflicts and doctor diagnostics remain prose-only follow-up
+- Priority: P1 (small scope, high leverage)
+- Added: 2026-10-30
+- Decision: [ADR-001](../../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md), Decision A
+
+## Problem
+
+When an `aiw` command blocks (gate incomplete, stage prerequisite unresolved, conflict, stale artifact), the output explains the problem but does not always provide the exact command that resolves it. Users and agents then reconstruct invocations from prose — which is where drift, dead ends, and wrong flags are born. There is no inventory guaranteeing that every blocking path has a tested, runnable continuation.
+
+## Source concept (RDD)
+
+RDD's CLI is governed by one rule:
+
+> **"A message may name a command only if running that command resolves the block."**
+
+Mechanisms behind it:
+
+- Every blocking `stop` carries a typed **reason code** and, when a continuation exists, the **exact command** (provider-issued `next_transition.command`), with fixed argument order, runnable verbatim.
+- A complete, published **continuation inventory**: a table mapping every reason code to its continuation or an explicit `Terminal` marker when no in-lineage continuation exists — terminal states say so instead of implying an escape route that isn't there.
+- The rule was learned the hard way: an escalated review told operators to run `review.status`, which _looked_ like a command but was an internal routing name. And a fixed message named a continuation that, when finally executed, turned out not to resolve anything. "Naming a command that runs and does not help is more expensive than naming nothing, because now the person trusts it."
+
+References:
+
+- Gentle-AI `docs/review-integration.md` — "Continue after a stop reason code" table (complete continuation inventory)
+- Gentle-AI `docs/architecture/the-organic-rdd-story.md` — "the rule that ran over everything else: if you tell someone what to do, make sure it works"
+
+## Proposal
+
+1. **Typed reason codes**: every blocking exit in the CLI (gates, stage commands, conflicts, doctor diagnostics) emits a stable reason code (e.g., `gate_incomplete`, `stage_prerequisite_unresolved`, `artifact_conflict`, `approval_stale`).
+2. **Exact continuation**: when a continuation exists, the same output includes the literal runnable `aiw` command with all flags resolved (ticket, stage, path). When no continuation exists, the output says so explicitly (`terminal`) and names the human decision required.
+3. **Continuation inventory doc**: a generated or maintained table mapping every reason code → continuation / terminal, published under `docs/` (contract for users, agents, and OPP-005's benchmark).
+4. **Machine-readable form**: `--json` outputs carry `reason_code` and `next_command` fields so agents can chain without parsing prose (aligns with OPP-002's `next_command`).
+
+## Affected areas
+
+- `src/cli.ts` (error/blocking output paths), `src/quality-gates.ts`, `src/human-gates.test.ts` conventions
+- `src/human-approval.ts` (stale approval blocks), migration/conflict reporting paths (`src/migration.ts`, `src/files.ts`)
+- New reason-code registry module with the inventory table
+- OPP-006 test policy is the enforcement mechanism for this opportunity
+
+## Acceptance criteria
+
+- Given any blocking exit, when its output is parsed, then it contains a stable reason code and either an exact `next_command` or an explicit terminal statement.
+- Given an emitted `next_command`, when executed in the state that produced the block, then it resolves or advances that block (verified by test, per OPP-006).
+- Given the continuation inventory, when a new reason code is added without a mapped continuation, then CI fails (inventory completeness check).
+- Given `--json`, when a block occurs, then `reason_code` and `next_command` are machine-readable fields.
+- No output names a command that exists but does not resolve the block it was printed for (regression-tested via OPP-006).
+
+## Non-goals
+
+- No interactive wizard behavior: the command prints the way out; it does not run it automatically.
+- No changes to what blocks — only to what each block tells you.
+
+## Open questions
+
+- Should the reason-code registry live as code (single source, docs generated from it) or as docs with a CI check?
+- Do adapter-rendered skills need the same guarantee in their prompts (the generated skills also tell agents what to run next)?

package/docs/opportunities/OPP-005-friction-benchmark.md

@@ -0,0 +1,62 @@
+# OPP-005: Friction benchmark — measure how users get stuck
+
+- Status: Implemented (2026-10-30, plan Wave 5). Baseline: in-band=5, out-of-band=5, dead-end=0; out-of-band blocks (install-first, no-workflow, git-required, unknown-stage usage, approve-not-pending) are the typing backlog this benchmark exists to shrink
+- Priority: P3
+- Added: 2026-10-30
+- Decision: [ADR-001](../../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md), Decision A
+
+## Problem
+
+AI Workflow measures token efficiency (`src/context-benchmark.ts`, `docs/token-efficiency.md`) but not **friction**: how often the workflow stops a user, and — more importantly — _how_ it stops them. Without that measurement, ceremony changes (like OPP-001) can't be evaluated, and blocking regressions (a gate that strands the user with no way out) are only discovered by users.
+
+## Source concept (RDD)
+
+Gentle-AI ships a reproducible benchmark that classifies every block into:
+
+- **In band** — it stops you and tells you what to run;
+- **Out of band** — it stops you and tells you nothing;
+- **Dead end** — it stops you and there is nothing you can do.
+
+Key design points worth copying:
+
+- It measures friction, not speed ("speed depends on the provider and the day; friction is yours").
+- It drives the **real packaged binary**, not a mock ("a number I publish and you cannot reproduce is a claim about my honesty; a number you can run yourself is evidence").
+- The journey corpus includes adversarial states, not just the happy guide paths: bare repositories, half-finished migrations, empty files, mode flips mid-operation.
+- Its own history shows why: first measurement was "six blocks, every one out of band"; after fixes, blocks stayed at the same _count_ but all moved in band, with zero dead ends — the tool didn't stop users less, it started telling them how to get out.
+- The instrument must itself be suspect: one round measured a stale binary after a silent build failure; another counted the kill switch _working_ as tool-caused friction. Rule: point the instrument at itself first.
+
+References:
+
+- Gentle-AI `docs/architecture/the-organic-rdd-story.md`, section "The benchmark" and "The loop"
+
+## Proposal
+
+1. **Journey corpus**: scripted end-to-end journeys against the packaged CLI (`node dist/cli.js`), starting with the happy paths (install → scan → recommend → workflow start → task → gates → complete) and, critically, adversarial states: missing profile, stale approval, conflicting root context file, interrupted migration, empty repository, pre-existing `.aiw` state, gate failure mid-workflow.
+2. **Block classification**: every non-success exit is classified in-band / out-of-band / dead-end by the harness, using OPP-004's reason codes and `next_command` as the in-band contract (a block with a `next_command` that resolves it, when executed, is in-band; a block with no continuation information is out-of-band; a block whose named continuation does not resolve it is a dead end).
+3. **Reporting**: per-journey and aggregate counts; stored as a benchmark artifact so runs are comparable over time. CI budget: **zero dead ends allowed**; out-of-band count may not increase without an explicit waiver.
+4. **Reproducibility**: the harness runs the same way locally and in CI against the packaged output, no internal APIs.
+
+## Affected areas
+
+- New `scripts/bench`-style harness (pattern: `src/context-benchmark.ts`, `scripts/*.node-test.mjs`)
+- Depends on OPP-004 reason codes for classification (sequence OPP-004 → OPP-005)
+- CI workflow wiring (`.github/`)
+- `docs/quality.md` (completion criteria reference the friction budget)
+
+## Acceptance criteria
+
+- Given the journey corpus, when the benchmark runs against the packaged CLI, then every non-success exit is classified and counted.
+- Given a block whose printed continuation resolves it when executed, when classified, then it counts as in-band (the harness actually executes continuations).
+- Given a dead end, when detected, then CI fails with the journey name, reason code, and reproduction steps.
+- Given two runs on unchanged code, when compared, then results are deterministic (no flaky classification).
+- Given the happy-path journeys only, when run today, then the result is recorded as the baseline (expected: some out-of-band blocks; dead ends zero or explicitly waived).
+
+## Non-goals
+
+- No speed/latency benchmarking (explicitly excluded by the source concept; token efficiency is already covered).
+- No telemetry dependency: the benchmark is local and reproducible; it does not phone home.
+
+## Open questions
+
+- Corpus growth policy: should each new OPP/blocking feature be required to add its adversarial journeys (ratchet)?
+- Where do results live — `.aiw/` local state, CI artifacts, or a versioned `docs/benchmarks/` record?

package/docs/opportunities/OPP-006-emission-usability-test-policy.md

@@ -0,0 +1,57 @@
+# OPP-006: Emission ≠ usability — test that named commands actually work
+
+- Status: Implemented (2026-10-30, plan Wave 3)
+- Priority: P2
+- Added: 2026-10-30
+- Decision: [ADR-001](../../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md), Decision A
+
+## Problem
+
+AI Workflow's test suite is strong on behavior and contracts, but there is no explicit policy category for the failure mode where a user-facing message _names a command_ and that command is wrong, incomplete, or does not resolve the situation. A test can verify a message is emitted with exact text — all green — while the command it names has never been executed by anyone. That is a dead end shipped with green coverage.
+
+## Source concept (RDD)
+
+The founding anecdote of Gentle-AI's audit story:
+
+> There was a message telling you "to get out of this, run this command". There were tests. They verified the message was emitted, with its exact text. All green. **Nobody had ever run the command the message named.** When I ran it, it did not work. I had been sending people into a dead end, with green test coverage, for months.
+
+From this, the governing rule: a message may name a command only if running that command resolves the block. Related lessons from the same document that this policy should encode:
+
+- "A guard nobody calls is not a guard" — a correct, well-documented check wired to nothing reads like coverage and is more dangerous than missing code.
+- Guide steps written without running them failed three times when testers followed them; the rule that came out: _before naming a continuation, execute it_.
+- A changelog overclaiming a fix ("fixed the tool so it stopped _printing_ the broken form, not the parser so it would accept it") cost a user real time.
+
+References:
+
+- Gentle-AI `docs/architecture/the-organic-rdd-story.md` — "The audits: the ones that did not" and "The mistakes I made"
+
+## Proposal
+
+1. **Policy** (added to `docs/quality.md`, "Completion validation"): every user-facing message, gate output, skill instruction, or generated prompt that names an `aiw` command must be covered by a test that **executes that command** in the state the message describes and asserts it resolves or advances that state. Emission assertions alone are insufficient for messages that name commands.
+2. **Extraction helper**: a small test utility that scans emitted messages (and optionally generated skill artifacts) for `aiw ...` invocations and executes them against fixture repositories, so coverage is systematic rather than hand-picked. Feeds naturally from OPP-004's `next_command`/reason-code contract.
+3. **Guidance for generated artifacts**: the same rule applies to skills and rules rendered through adapters — if a generated skill tells the agent to run a command, a test executes that rendered command in a fixture. (The generated `ai-init` skill is the highest-value first target.)
+4. **Changelog/review discipline** (soft rule, docs-only): a fix is described as fixing the _parser_, not the _printing_ — i.e., the claim is bound to the behavior tested, not the symptom observed.
+
+## Affected areas
+
+- `docs/quality.md` (new policy section)
+- New test helper + fixtures (pattern: `src/fixtures/`, existing e2e tests for install/init/migration)
+- Existing message-emitting modules get incremental coverage as they are touched (no big-bang retrofit required)
+- Enforces OPP-004; the two share the reason-code/`next_command` contract
+
+## Acceptance criteria
+
+- Given a user-facing output that names an `aiw` command, when the policy applies, then a test executes that command in the described state and asserts progress (resolve or advance).
+- Given the extraction helper, when run over CLI outputs in fixtures, then every discovered `aiw` invocation either has executing coverage or is an allowlisted non-actionable mention.
+- Given the generated `ai-init` skill for each adapter, when rendered in tests, then every `aiw` command it instructs has been executed at least once in the e2e suite.
+- Given `docs/quality.md`, when a reviewer applies completion validation, then emission-only tests are explicitly insufficient for command-naming messages.
+
+## Non-goals
+
+- No retroactive mandate to fix every existing message in one pass: the policy applies to new and touched code (ratchet).
+- No enforcement inside the product at runtime — this is a development-time test policy, not a CLI feature.
+
+## Open questions
+
+- Allowlist format for legitimate _informational_ command mentions (e.g., docs examples that are not continuations)?
+- Should the extraction helper live as a vitest utility or a `scripts/` check runnable in CI independent of unit tests?

package/docs/opportunities/OPP-007-decision-findings-triage-scope-watch.md

@@ -0,0 +1,54 @@
+# OPP-007: Decision model — findings-evidence triage and lane scope-watch
+
+- Status: Proposed
+- Priority: P3
+- Added: 2026-10-30
+- Decision: [ADR-001](../../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md), Decision A (model-integration addendum)
+- Companion: [OPP-008](OPP-008-embedding-covering-tests-judge-context.md)
+
+## Problem
+
+Two implemented flows have deterministic guards with semantic blind spots:
+
+1. **Adversarial review (OPP-003)**: a severe finding can be structurally well-formed (has `file:line`, has a command) while the cited evidence does not actually support the claim. The refuter catches this only for findings it processes — and a weak first filter passes noise downstream.
+2. **Light lane (OPP-001)**: lane abuse (substantial work routed as light) is currently caught by deterministic mismatch signals only (`risk assess` tier vs lane). What deterministic rules cannot see: 80 lines spread across three subsystems _is_ substantial even when every path rule stays quiet.
+
+Meanwhile the existing `aiw decision triage` keeps serving full-lane artifacts but is not connected to either gap — and its cost profile is already proportional: light-lane tasks produce no artifacts, so there is nothing to triage and the model spend is zero by construction.
+
+## Source concept
+
+- Spec NFR-2/NFR-3 (odd-rdd-proportionality spec): deterministic floor first; models advisory-only, never change evidence states, gates, or approvals.
+- `buildEvidenceTriageRequest` (`src/decision.ts`) already asks "does this artifact include concrete verification evidence for every stated requirement" — the same pattern aimed at judge findings.
+- `src/model-routing.ts`: advisory per-category routing with named evidence — the natural assignment mechanism (categories such as `review.findings-triage`, `workflow.lane-watch`), no new machinery.
+- ADR-001 principle: ceremony scales with consequence — model spend scales the same way (where ceremony survived, value density is highest; where it shrank, cost is already zero).
+
+## Proposal
+
+1. **Findings triage** (pairs with OPP-003, prerequisite for the diversity-judge idea): a deterministic shape check always runs (severity present; proof references or `file:line` non-empty) — pure parse. When the decision model is enabled, each severe finding additionally gets one triage question ("does the cited evidence support the claim?") recorded as an advisory `evidence_supported: yes/no/unclear` flag next to the finding. The refuter still owns corroboration/refutation; degradation to advisory stays governed by OPP-003's rules; the flag never blocks by itself.
+2. **Lane scope-watch** (pairs with OPP-001): on light-lane `task start` when `risk assess` reports `high`, and on light-lane completion, a mismatch notice is recorded. The deterministic part (tier vs lane mismatch) runs always; the model adds the semantic dimension (multi-subsystem footprint) only when enabled. Recorded as an advisory note in the checkpoint/ledger; never blocks, never changes the lane.
+3. **Routing and settings**: new `routing.yml` categories with evidence links; everything gated by the existing `decision` settings section; unconfigured means zero behavior change and zero network (NFR-2).
+
+## Affected areas
+
+- `src/decision.ts` (new request builders: findings triage, lane watch)
+- `src/workflow.ts` (light-lane complete/escalate advisory notice), `src/risk-assess.ts` (mismatch signal hook)
+- OPP-003 integration point (review-refuter skill contract note; runtime wiring lands with OPP-003's runtime phase)
+- `src/model-routing.ts` categories; `docs/decision-model-evaluation.md`
+
+## Acceptance criteria
+
+- Given the decision model unconfigured, when review or lane flows run, then behavior is byte-identical to today and no network request is made.
+- Given a severe finding whose cited `file:line` does not support the claim, when triage runs enabled, then the finding carries the advisory flag and the refuter still decides corroboration.
+- Given a light-lane start or completion with a `high` deterministic risk signal, then a mismatch note is recorded even without any model.
+- Given any model output, then no evidence state, gate outcome, or approval changes (NFR-3); human acceptance is unchanged.
+- Given `routing.yml`, then the new categories carry evidence links; unevidenced rules are labeled `unevidenced-rule`.
+
+## Non-goals
+
+- The decision model never judges finding correctness (that is the refuter on the host agent's model), never lowers risk tiers, never chooses lanes, never blocks, never replaces human acceptance.
+- No new settings sections beyond the existing `decision` gate; no per-finding model calls without a batched alternative evaluated first.
+
+## Open questions
+
+- Per-finding triage (n calls, stronger isolation) vs one batched request (cheaper, weaker)? Measure on the self-hosting package's own review artifacts.
+- Does scope-watch belong only in `workflow complete` output, or also in `task status`?

package/docs/opportunities/OPP-008-embedding-covering-tests-judge-context.md

@@ -0,0 +1,52 @@
+# OPP-008: Embedding retrieval — covering-test detection and judge context scoping
+
+- Status: Proposed
+- Priority: P3
+- Added: 2026-10-30
+- Decision: [ADR-001](../../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md), Decision A (model-integration addendum)
+- Companion: [OPP-007](OPP-007-decision-findings-triage-scope-watch.md)
+
+## Problem
+
+Three implemented flows use weak approximations where the existing semantic index would materially sharpen results, and one new flow spends tokens where retrieval would save them:
+
+1. **`untested_regression` in `risk assess` (OPP-002)** uses a sibling-file heuristic (`src/x.ts` → `src/x.test.ts`). A test exercising the changed module from a differently named file (`integration.spec.ts` via the public API) is invisible → false `high` flags.
+2. **Adversarial judges (OPP-003)** receive the raw diff; related unchanged code (callers, consumed contracts) is missed or fetched ad hoc by the frontier model — the expensive way.
+3. The semantic index (SEM-001…006) already exists and proved the pattern (SEM-006: scoped context reduced tokens without quality regression), but nothing in the new flows consumes it.
+
+## Source concept
+
+- ODD token economics: ceremony shrank, so spend shifted from writing/reading artifacts to **reviewing changes** — retrieval should target the new spend.
+- Spec NFR-2: deterministic floor first — the sibling heuristic remains the exact no-model behavior; retrieval only _prevents false positives_ (retrieval absence never implies low risk: no covering test found → the flag stands).
+- SEM contract: retrieval results are aids, never confirmed facts; stale index fails safe toward `high`.
+
+## Proposal
+
+1. **Covering-test retrieval** (pairs with OPP-002): when semantic mapping is enabled and an index exists, for each high-risk-category source path run one scoped semantic query ("tests exercising this module/symbol"). Top-k test-chunk hits count as covering evidence; none found → `untested_regression` stands. Retrieval-aided verdicts are labeled in reasons (`covering: semantic-retrieval`) so audits can distinguish heuristic from retrieval. Unconfigured: sibling heuristic exactly as today.
+2. **Judge context scoping** (pairs with OPP-003): when rendering judge prompts with an index available, include the diff plus top-k retrieved chunks for changed symbols (callers, types, contracts) under a bounded token budget, labeled as context aids. Unconfigured: judges get the raw diff as today.
+3. Both flow through the existing `semantic` settings gate and the chunk index built by `aiw scan` — no new settings, no reindexing inside risk assess (freshness stays `scan`'s job; a stale index can only miss, which fails safe toward `high`).
+
+## Affected areas
+
+- `src/risk-assess.ts` (covering-test probe gains an optional retrieval provider; deterministic fallback unchanged)
+- `src/semantic.ts` (query reuse; symbol-aware scoped query helper)
+- OPP-003 judge skill rendering (`resources/skills/review-judge-a.md`, `review-judge-b.md`: context sections are retrieval aids, never facts)
+- `docs/semantic-mapping.md`; cross-links from [OPP-002](OPP-002-risk-assess-command.md) and [OPP-003](OPP-003-adversarial-review-package.md)
+
+## Acceptance criteria
+
+- Given no semantic config, when risk assess or judge prompts render, then behavior is byte-identical to today and offline.
+- Given an index and a test exercising the changed module from a differently named file, when risk assess runs, then `untested_regression` is not flagged and the reason records `covering: semantic-retrieval`.
+- Given retrieval finds no covering test, then `untested_regression` stands.
+- Given judge prompt rendering with an index, then prompts include bounded retrieved chunks labeled as context aids within existing token ceilings.
+- Given the embedding model unavailable at runtime, then flows degrade to deterministic behavior per the SEM contract.
+
+## Non-goals
+
+- No model-driven risk _tier_ changes: retrieval only prevents false `untested` flags; tiers stay rule-based.
+- No new providers or settings sections; no reindexing inside risk assess.
+
+## Open questions
+
+- Symbol extraction for queries: deterministic import/export parsing vs path-semantics-only queries?
+- Judge prompt budget: how to split the token ceiling between the diff and retrieved chunks?