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.