voyage/docs/balance-backlog-plan.md

Balance Backlog — Implementation Plan (multi-session)

Status: Active plan. Mandated by operator 2026-06-20 ("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 (changes are small/surgical; flip if dogfooding is wanted).

---

Decision Register — resolve before the gated sessions

Three backlog items have genuine forks that change scope. The analysis explicitly deferred these to the operator; they are NOT presumed here.

#	Item	Options (recommendation first)	Governs
D1	V09 gemini-bridge capability	(a) keep it as an agent [REC — preserves the capability] · (b) remove the agent, call gemini-mcp inline from trekresearch/trekplan [agent count 24→23]	S35 scope
D2	V32 observability export	(a) keep exporters + document the direct-export rationale [REC — preserves S21 security-hardened SSRF/path/field guards; the code-verified pass defended them as net-new] · (b) drop lib/exporters/* + otel-export.mjs to native OTLP-collector passthrough [deletes tested security code]	S34 scope
D3	Opus-pin (24 agents model: opus, pinned 40d8742)	(a) keep the pin firm [REC for default safety — model items become document-only] · (b) downgrade glue/mechanical/retrieval agents to sonnet (V08 researchers, V11 retrieval, V16 decomposer, V35 dormant, + V09 if D1=keep) [aligns with your global model-policy, but overrides a deliberate pin + needs guard-test update]	S35 scope

Recommendation note (D3): the global model-policy ("match capability to complexity; retrieval/transform → Sonnet") argues for downgrade; the deliberate pin 40d8742 argues for firm. This is a real values-call only the operator should make — defaulted to "keep firm" so nothing pinned is silently overridden.

---

Cross-cutting constraints (apply to every session)

• No Handover-1 change. The brief schema is the public contract; nothing in this backlog touches it. (V05 memory-alignment, the one breaking-tagged capability, is KEEP-as-is — not in scope.)
• Doc-consistency is guard-tested. Any agent-count or model change must keep tests/lib/doc-consistency.test.mjs + tests/lib/agent-frontmatter.test.mjs green, and update README / CLAUDE.md agent table + the "24 agents opus" references in docs/voyage-vs-cc-balance-analysis.md + STATE env counts. Fix the SOURCE the pin guards, not the test (unless the pin guarded a stale value).
• Test baseline: 729 (727/2/0, bar node --test). Each session re-baselines and states the new count.
• claude plugin validate must still pass (1 accepted warning).
• Line numbers rot — re-grep against the live file before editing; never edit on a line number alone.

---

Session sequence

Clean (fork-free) sessions first for momentum; gated sessions slot in once D1–D3 land.

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

• 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 path intact.
• Depends-on: none.

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

• 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 do not re-implement an engine. Fix any actual re-implementation found; 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 produces a documented finding (no code change if already native).
• Verify: node --test, plugin validate; the principle note present in docs/architecture.md.
• Depends-on: none.

S33 — V35 (doc half): reclassify the orchestrator reference docs · [non-breaking, doc]

• Goal: relabel planning-orchestrator / research-orchestrator / review-orchestrator as reference docs, not spawnable capabilities in the agent inventory; reconcile the "24 agents" framing (3 non-spawned reference docs + 1 dormant) across README / CLAUDE.md / docs.
• Files: README.md, CLAUDE.md (agent table), agents/*-orchestrator.md (header clarity), tests/lib/doc-consistency.test.mjs.
• TDD: doc-consistency pin updated to the reconciled framing → green.
• Verify: node --test, counts coherent across all docs.
• Depends-on: none. Precedes S35 (settles the agent-count baseline before any model/count change).

S34 — V32: observability disposition · [GATED D2]

• IF D2(a) keep+document: add the direct-export rationale (why custom exporters + SSRF/path/field guards rather than a collector) to docs/observability.md. Small, doc-only.
• IF D2(b) drop-to-collector: remove lib/exporters/* + hooks/scripts/otel-export.mjs + their tests; document the native OTEL_* env-var → collector path; update docs/observability.md + Stop-hook wiring. Multi-file deletion; re-baseline tests.
• Verify: node --test, plugin validate; observability doc reflects the chosen path.
• Depends-on: D2.

S35 — Opus-pin / model revisit + V09 + V35 model half · [GATED D1 + D3; touches guard + doc counts]

• IF D3(a) keep-firm: document the kept-opus rationale for the flagged agents; no code. If D1(b) remove gemini-bridge: still delete the agent + wire gemini-mcp inline (count 24→23, update guard + docs).
• IF D3(b) downgrade: set model: sonnet on V08 researchers, V11 retrieval agents, V16 session-decomposer, V35 dormant synthesis-agent (+ V09 gemini-bridge if D1=keep); update tests/lib/agent-frontmatter.test.mjs (the 24-opus guard) + doc-consistency + README/CLAUDE.md model table + the analysis doc's "24 agents opus" lines + STATE.
• TDD: guard test updated to the new model map (failing first) → implement → green.
• Verify: node --test, plugin validate, agent count + model claims coherent everywhere.
• Depends-on: D1, D3, and S33 (count baseline).

S36 — V30: economy-profile Jaccard calibration · [non-breaking, pin-adjacent]

• 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.
• Files: lib/parsers/profile-jaccard.mjs, tests/synthetic/profile-jaccard-calibration.md, docs/profiles.md, docs/operations.md.
• TDD: a test pinning either the calibrated floor or the explicit experimental label.
• Verify: node --test, profile docs unambiguous about economy's status.
• Depends-on: none (can run any time; placed last as lowest-urgency).

---

Verification (plan-level)

• Every §6 backlog row maps to exactly one session: V15→S31, V01+V07/V08/V11/V24→S32, V35-doc→S33, V32→S34, V09+V35-model+opus-pin(V08/V11/V16)→S35, V30→S36. (8 items → 6 sessions.)
• No session changes Handover 1. The only breaking capability (V05) is out of scope (KEEP-as-is).
• Each session ends green on node --test + claude plugin validate, with doc-consistency reconciled.
• D1–D3 resolved before S34/S35 begin.

Out of scope (explicitly NOT in this plan)

• No wholesale Workflow substrate swap (CC-27 DECLINED stands; V27 stays opt-in).
• No delegated-orchestration redesign (CC-26 lean-NO; Δ=0).
• No brief-schema (Handover-1) change.
• No reopening of the premium-default-profile or framing-gate pins.