From 6c00df573b8fd537a43b7b73b846c26ad6dfd97e Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Sat, 20 Jun 2026 09:11:08 +0200 Subject: [PATCH] =?UTF-8?q?docs(voyage):=20S30b=20=E2=80=94=20resolve=20ba?= =?UTF-8?q?cklog-plan=20decisions=20(D1-D3=20conservative)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Operator resolved the 3 forks to the conservative option: D1 keep gemini-bridge as an agent, D2 keep observability exporters + document the direct-export rationale, D3 keep the 24-opus pin firm. Model + observability work collapses from code-deletion to a documentation record; real code remains in V15 (export trim) and V30 (economy calibration). Plan finalized to 4 sessions (S31-S34). Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01LqBYc8Ltrk7LipyJmGxXiB --- docs/balance-backlog-plan.md | 97 +++++++++++++++--------------------- 1 file changed, 41 insertions(+), 56 deletions(-) diff --git a/docs/balance-backlog-plan.md b/docs/balance-backlog-plan.md index 4736a2c..0c64a6e 100644 --- a/docs/balance-backlog-plan.md +++ b/docs/balance-backlog-plan.md @@ -1,92 +1,77 @@ # Balance Backlog — Implementation Plan (multi-session) -**Status:** Active plan. Mandated by operator 2026-06-20 ("vi skal gjøre alle backlog items"). +**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 (changes are small/surgical; flip if dogfooding is wanted). +**Operating mode:** ONE session per row → TDD (failing test first) → commit + push → update STATE → STOP. Direct surgical TDD, **not** Voyage-pipeline dogfood. --- -## Decision Register — resolve before the gated sessions +## Decision Register — RESOLVED (operator 2026-06-20) -Three backlog items have genuine forks that change scope. **The analysis explicitly deferred these to the operator; they are NOT presumed here.** +The analysis deferred three forks to the operator. All three resolved to the conservative option (preserve capability / security code / the deliberate pin): -| # | 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 | +| # | 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. | -> **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. +**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 (apply to every session) +## Cross-cutting constraints (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. +- **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 +## Session sequence (finalized — 4 sessions) -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] +### 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` path intact. +- **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 · [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. +### 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 produces a documented finding (no code change if already native). -- **Verify:** `node --test`, plugin validate; the principle note present in `docs/architecture.md`. +- **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 — 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). +### 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 — 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] +### S34 — V30: economy-profile Jaccard calibration · [CODE · 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). +- **Verify:** `node --test`; profile docs unambiguous about economy's status. +- **Depends-on:** none (lowest urgency; placed last). --- ## 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. +- 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 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. +- 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.