voyage/docs/balance-backlog-plan.md

Balance Backlog — Implementation Plan (multi-session)

Status: Active plan, decisions RESOLVED 2026-06-20. Mandated by operator ("vi skal gjøre alle backlog items"). Source: the §6 backlog of docs/voyage-vs-cc-balance-analysis.md. Operating mode: ONE session per row → TDD (failing test first) → commit + push → update STATE → STOP. Direct surgical TDD, not Voyage-pipeline dogfood.

---

Decision Register — RESOLVED (operator 2026-06-20)

The analysis deferred three forks to the operator. All three resolved to the conservative option (preserve capability / security code / the deliberate pin):

#	Item	Resolution	Effect on plan
D1	V09 gemini-bridge	Keep it as an agent (count stays 24; model governed by D3)	No removal/rewiring. Model stays opus (D3).
D2	V32 observability export	Keep lib/exporters/* + otel-export.mjs; document the direct-export rationale	Doc-only, no deletion of S21 security code.
D3	24-agents model: opus pin (40d8742)	Keep the pin firm	V09/V35/V08/V11/V16 model changes → document-only (record considered-and-kept). No guard-test change.

Consequence: the model + observability work collapses from code-deletion to a documentation record. Real code remains in V15 (export trim) and V30 (economy calibration). The plan is now 4 sessions (2 code, 2 doc/audit).

---

Cross-cutting constraints (every session)

• No Handover-1 change. The brief schema is the public contract; nothing here touches it. (V05 memory-alignment, the lone breaking capability, is KEEP-as-is — out of scope.)
• Doc-consistency is guard-tested (tests/lib/doc-consistency.test.mjs, tests/lib/agent-frontmatter.test.mjs). Any inventory/count/model wording change must keep them green and stay coherent with README / CLAUDE.md + the "24 agents opus" references in docs/voyage-vs-cc-balance-analysis.md + STATE. Fix the SOURCE a pin guards, not the test.
• Test baseline: 729 (727/2/0, bar node --test). Each session re-baselines + states the new count. claude plugin validate stays green (1 accepted warning).
• Line numbers rot — re-grep the live file before editing.

---

Session sequence (finalized — 4 sessions)

S31 — V15: trim plan-export to its load-bearing variant · [CODE · non-breaking · no pin]

• Goal: drop the pr / issue / markdown export variants from trekplan --export (CC auto-mode reformats markdown ad-hoc equally well); keep --export headless and relabel it as the decomposition entry it actually is.
• Files: commands/trekplan.md (Phase 1.5 --export), docs/command-modes.md, export tests under tests/.
• TDD: failing test asserting pr|issue|markdown are gone and --export headless(decompose) still resolves → implement → green.
• Verify: node --test (new count); grep -c "export pr" commands/trekplan.md = 0; --export headless intact; plugin validate.
• Depends-on: none.

S32 — V01 + V07/V08/V11/V24: delegate-to-native hygiene · [CODE + AUDIT · non-breaking]

• Goal: (V01) delegate the literal brief-interview Q&A turn-taking to AskUserQuestion rather than a hand-rolled selection loop; (V07/V08/V11/V24) audit that the research/exploration/reviewer swarms ride native parallel Agent spawn + AskUserQuestion and re-implement no engine. Fix any real re-implementation; otherwise document the "delegate the engine, keep the policy" principle.
• Files: commands/trekbrief.md (Phase 3), commands/trekresearch.md, commands/trekplan.md, commands/trekreview.md, docs/architecture.md (principle note).
• TDD: where an edit is made, a test pinning the delegated behavior; the audit portion yields a documented finding (no code change if already native).
• Verify: node --test; plugin validate; principle note present in docs/architecture.md.
• Depends-on: none.

S33 — Documentation consolidation: record the considered-and-kept decisions · [DOC · non-breaking]

Bundles the three items that D1–D3 turned into documentation:

• V35 (doc half): relabel planning- / research- / review-orchestrator as reference docs, not spawnable capabilities; reconcile the "24 agents" framing (= 21 spawnable + 3 reference docs + 1 dormant synthesis-agent) across README / CLAUDE.md / docs.
• V32 rationale (D2): add to docs/observability.md why custom exporters + SSRF/path/field guards rather than a native collector (preserves S21 hardening; deliberate direct-export choice).
• Kept-opus rationale (D3): record that opus on V09 (glue), V35 (dormant), V08/V11/V16 (mechanical/retrieval) was reconsidered and kept (pin 40d8742 stands) — a short note in the analysis doc / CLAUDE.md, no frontmatter change.
• Files: README.md, CLAUDE.md, agents/*-orchestrator.md (header clarity), docs/observability.md, docs/voyage-vs-cc-balance-analysis.md (decision-record addendum), tests/lib/doc-consistency.test.mjs.
• TDD: doc-consistency pin updated to the reconciled inventory framing → green.
• Verify: node --test; counts/model claims coherent across all docs; agent-frontmatter.test.mjs unchanged + green (no model change).
• Depends-on: none (settles the inventory baseline).

S34 — V30: economy-profile Jaccard calibration · [CODE · non-breaking · pin-adjacent] ✅ DONE (2026-06-20)

• Goal: the economy-profile Jaccard floor (0.55) is grounded in parked synthetic fixtures (Step-17 calibration deferred). Either run the calibration against real fixtures and replace the floor, or clearly relabel economy as experimental/uncalibrated in docs + the profile.
• Resolution: Path B — label, not calibrate. The empirical run is v4.2-budget-gated ($60–120, unauthorized), so the fork is forced. lib/profiles/economy.yaml now carries experimental: true (validator type-checks the optional boolean); README + docs/operations.md + docs/profiles.md flag the economy row; the calibration doc cross-references the marker. (lib/parsers/profile-jaccard.mjs was untouched — it was listed for the calibration path only.)
• TDD: 5 tests — economy declares experimental: true, premium/balanced do not, validator rejects non-boolean experimental, every profile-doc economy row flagged experimental, and the flag tracks the calibration's parked-synthetic status. Baseline 739 → 744 (742/2/0).
• Verify: ✅ node --test green; ✅ claude plugin validate (1 accepted warning); economy's status now unambiguous + machine-checked.
• Depends-on: none (lowest urgency; placed last).

Backlog complete — 4/4 sessions shipped (S31–S34). All 8 §6 items disposed; 2 real code changes (V15 export-trim, V30 economy-label), the rest doc/audit.

---

Verification (plan-level)

• Every §6 backlog row maps to exactly one session: V15→S31; V01+V07/V08/V11/V24→S32; V35+V32+opus-pin record→S33; V30→S34. (8 items → 4 sessions after the conservative decisions.)
• No session changes Handover 1; no operator pin overridden (D3 kept firm).
• Each session ends green on node --test + claude plugin validate, doc-consistency reconciled.

Out of scope (explicitly NOT in this plan)

• No gemini-bridge removal (D1 keep); no exporter deletion (D2 keep); no model downgrades (D3 firm).
• No wholesale Workflow substrate swap (CC-27 DECLINED; V27 stays opt-in); no delegated-orchestration redesign (CC-26 lean-NO).
• No brief-schema (Handover-1) change; no reopening of premium-default / framing-gate pins.