voyage/docs/W1-narrow-wins-plan.md

# W1 narrow-wins — implementation plan (S9 →)

**Status:** Active plan. Operator decision (2026-06-18): **implement all narrow wins** surfaced by
the S7 (CC-26) and S8 (CC-27) gates. This doc sequences them session-by-session per the kjøremodus
(ONE task/session → commit + push → update STATE → STOP).
**Resolves the implementation half of:** decision-matrix §W1 (CC-26 + CC-27).
**Inputs:** `docs/T1-cc26-delegated-orchestration.md` (§6 synthesis-agent PoC), `docs/T2-cc27-workflow-substrate.md` (§5 bake-off, §6 schema contract), `commands/trekreview.md` Phase 5–6, `commands/trekplan.md` Phase 7, `lib/review/`, `lib/validators/review-validator.mjs`, `scripts/q3-cache-prefix-experiment.mjs` (harness pattern).

---

## The narrow wins (what "all" means)

| ID | Narrow win | Source | Gate (guard, not blocker — see §Posture) |
|----|-----------|--------|------------------------------------------|
| **NW1** | **Reviewer-output schema contract** — codify trekreview Phase 5 reviewer JSON as a validated schema; main validates each reviewer's output and re-asks on *schema* failure, not just parse failure. Retires the fragile contract at `trekreview.md:202–204`. **No Workflow dependency.** | S8 tier 1 (T2 §6) | Ungated — ship regardless. |
| **NW2** | **trekreview Phase 5–6 Workflow port** — `parallel([conformance, correctness], {schema})` → JS dedup-by-triplet → `agent(coordinator, {schema})`, as an opt-in path. Reuses NW1 schemas. | S8 tier 2 (T2 §5) | Bake-off must show **fidelity-equivalent** review.md + zero classifier interference + acceptable control/cost, else the port does not become reachable. |
| **NW3** | **trekplan Phase 7 synthesis-agent** — delegate the single heaviest inline read (6–10 agent outputs resident at once) to a `synthesis-agent`; main receives the digest. | S7 PoC (T1 §6) | Adopt only if measured **Δ main-context ≥ 30%** with no quality loss. |

**Excluded (declined, not narrow):** wholesale Workflow substrate swap (T2 tier 3); wholesale
delegated orchestrator→swarm (T1 §7). Not in scope.

## Cross-cutting constraints

- **Iron Law / TDD (global):** no production code without a failing test first. Every implementing
  session writes failing tests, then the minimal code to pass.
- **Don't ship a measured regression.** NW2 and NW3 carry numeric guards (fidelity / Δ-tokens). A
  guard failure is **surfaced to the operator**, not silently shipped — the intent is to implement,
  but not at the cost of a verdict-changing or quality-losing regression.
- **Classifier risk (S7+S8 open item).** trekreview's 2–3-agent fan-out is below the proliferation-
  classifier threshold (S8 F4). NW2's bake-off still checks it **under `auto`/`bypass`** because
  trekreview can run headless. The *large* fan-out case (trekplan swarm) is NOT touched by these
  narrow wins (NW3 delegates a single synthesis read, not a fan-out) and stays deferred.
- **One task per session.** Conditional sessions (S11, and the adopt-step inside S12) collapse to a
  short "declined per measurement" record if their guard fails.

## Session sequence

### S9 — NW1: reviewer-output schema contract (TDD, ungated)
1. **Failing tests first** (`tests/lib/` + `tests/parsers/`): a findings-schema validator that
   accepts a well-formed findings array and rejects each malformation (missing `rule_key`, bad
   `severity` enum, non-numeric `line`, missing `file`) with a stable error code.
2. Implement `lib/review/findings-schema.mjs` (schema + validator), reusing the
   `lib/validators/review-validator.mjs` error-shape conventions.
3. Wire into `commands/trekreview.md` Phase 5 prose: replace "collect trailing JSON block … on
   parse error ask the agent to re-emit" (`:202–204`) with "validate each reviewer's JSON against
   the findings schema; on schema failure re-ask for conforming JSON (bounded retries N=2)."
4. **Verifisering:** `node --test tests/lib/findings-schema.test.mjs` green; `grep -n "findings-schema" commands/trekreview.md` shows the wire-in; full suite still passes (`node --test`); `claude plugin validate` clean.
5. **Deliverable:** schema validator + tests + Phase 5 prose update. Test count rises by the new cases.

### S10 — NW2 part A: build the Workflow port + run the bake-off
1. Build the port as a Workflow script (the T2 §5 Arm B): `parallel([conformance, correctness])`
   with the NW1 findings schema → **plain-JS dedup by `(file,line,rule_key)`** (pattern ref:
   `lib/review/plan-review-dedup.mjs`) → `agent(review-coordinator)` with a verdict schema → return
   the review.md body. Keep Phases 1–4 + 7–8 in prose.
2. **Bake-off** (extend `scripts/q3-cache-prefix-experiment.mjs`): fixed real project (an existing
   `.claude/projects/*/` with a real diff + brief), `model: opus` / `--profile balanced`, ≥3 runs
   per arm. Capture the T2 §5 metrics: output fidelity (diff the two `review.md`), JSON-robustness,
   control/visibility (qualitative), classifier interference under `auto`, token cost, wall-time.
3. Compute verdict vs the T2 §5 thresholds (POSITIVE / NEGATIVE / INCONCLUSIVE); write a results doc
   `docs/T2-bakeoff-results.md`.
4. **Verifisering:** results doc written with a verdict line; fidelity diff command + its output
   recorded; classifier-interference count stated (target 0); ≥3 runs/arm present in the raw data.
5. **Deliverable:** Workflow port script + bake-off harness + results doc + verdict.

### S11 — NW2 part B: integrate or decline (gated on S10 verdict)
- **If S10 = POSITIVE:** make the Workflow path reachable as an **opt-in `--workflow` flag**
  (default stays prose — preserves the 2.1.154+ portability floor; see §Open decisions). TDD the
  flag routing in `commands/trekreview.md`. Document the opt-in + its CC-floor requirement.
- **If NEGATIVE / INCONCLUSIVE:** record "port declined per bake-off; NW1 schema win stands"; do not
  wire the flag. Short session.
- **Verifisering:** if integrated — `grep` shows the `--workflow` route; a smoke run produces a
  review.md fidelity-equal to the prose path on the bake-off project; full suite green. If declined
  — the decision + evidence are in `docs/T2-bakeoff-results.md` and STATE.
- **Deliverable:** `--workflow` opt-in (or a recorded decline).

### S12 — NW3: synthesis-agent measurement + adopt-if-it-pays
1. Build a `synthesis-agent` spec (`agents/synthesis-agent.md`) that ingests the trekplan Phase-5/7
   exploration outputs and emits the findings digest main currently writes inline.
2. **Measure Δ main-context** (q3 harness): inline baseline vs delegated, same exploration outputs,
   ≥3 runs; LLM-judge (or operator) checks digest quality ≥ inline.
3. **If Δ ≥ 30% and quality-equivalent:** wire `commands/trekplan.md` Phase 7 to delegate the digest
   to `synthesis-agent` (TDD the routing). **Else:** record "declined per measurement (Δ = X%)".
4. **Verifisering:** measurement results file with Δ%; if adopted — Phase 7 prose references the
   agent + a run shows the digest is produced out-of-main; full suite green. If declined — Δ% and
   reasoning recorded in STATE + a short `docs/T1-synthesis-poc-results.md`.
5. **Deliverable:** `synthesis-agent` + measurement results + (adopt wiring OR recorded decline).

### S13 — RELEASE (was the old S10)
CC-07 fallbackModel · CC-12/13 hooks · CC-08 GH#36071 · CC-29/31 verify · **plugin version bump +
CHANGELOG (now also covering NW1–NW3 changes) + version badge** + final `claude plugin validate` +
full `node --test`. The version bump is the coordinated release that also lands the brief-schema
2.2 badge held since S6.

## Posture on the guards (default — operator may override)

"Implement all narrow wins" is read as **pursue and ship all three**, with NW2/NW3's numeric guards
acting as **regression guards, not veto gates**: we build each win, measure, and ship when the
measurement confirms; a guard failure is surfaced for an operator call rather than silently shipped
or silently dropped. NW1 has no guard and ships outright. If the operator instead wants NW2/NW3
shipped **regardless** of their measurements, say so and S11/S12 drop the conditional branch.

## Open decisions (resolve in-session, recommendations given)

1. **NW2 integration posture (needed at S11, informed by S10):** opt-in `--workflow` flag (prose
   stays default) **[recommended]** vs Workflow-by-default. Recommendation preserves portability
   (T2's biggest structural con — raising the consumer CC floor to 2.1.154+ is outward-facing and
   should be opt-in until proven), and is reversible. The bake-off's control/visibility findings may
   strengthen the case either way.
2. **Guard-fail handling (NW2/NW3):** per §Posture — surface to operator. Confirm if the operator
   wants a different default.

## Verifisering (whole plan)

- Each session leaves the suite green (`node --test`) and `claude plugin validate` clean.
- NW1 done ⇔ findings-schema tests pass AND `trekreview.md:202–204` fragility is replaced.
- NW2 done ⇔ bake-off verdict recorded AND (`--workflow` route smoke-tested fidelity-equal) OR
  (decline recorded with evidence).
- NW3 done ⇔ Δ main-context measured AND (Phase 7 delegates AND digest produced out-of-main) OR
  (decline recorded with Δ%).
- Release (S13) ⇔ version bumped consistently across plugin manifest + CHANGELOG + badge; final
  validate + full suite green.