diff --git a/docs/W1-narrow-wins-plan.md b/docs/W1-narrow-wins-plan.md new file mode 100644 index 0000000..31afc79 --- /dev/null +++ b/docs/W1-narrow-wins-plan.md @@ -0,0 +1,121 @@ +# 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.