Kjell Tore Guttormsen 15d172521d docs(claude-md): trim CLAUDE.md to invariants (always-loaded token trim, S53)

Relocate the verbose rationale/history from six always-loaded block-quote
notes (L5/L7/L9/L11/L56/L58) to the docs that already own it, leaving a terse
invariant + pointer in each. No invariant fact deleted — moved.

  L5  synthesis-PoC Δ≈0 caveat   → kept one clause; detail in T1-synthesis-poc-results.md
  L7  v3.0.0 architect note      → CHANGELOG.md [3.0.0]
  L9  Trinity Tier 2/3 detail    → HANDOVER-CONTRACTS.md §Handover 1 (added the producer-context para)
  L11 brief-framing 3-layer gate → HANDOVER-CONTRACTS.md §Handover 1 (already owned)
  L56 sonnet-downgrade rationale → voyage-vs-cc-balance-analysis.md §10 (D3)
  L58 per-agent effort table     → profiles.md §Model & effort axes

Measured (config-audit manifest scanner): voyage project CLAUDE.md
2261 → 1759 always-loaded tok (-502, -22%). Tables (Commands/Agents) left
byte-exact; doc-consistency pins (parallel wall-clock, 21 spawnable,
3 orchestrator reference docs, synthesis-agent dormant) preserved.

Docs-only: no version bump, no catalog ref. Suite 809 (807/0/2) green;
doc-consistency 87/0. Also tracks the task brief (provenance).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RZHLfnJXGx55G4euxPuxim

2026-06-29 14:49:32 +02:00

4.4 KiB

Raw Permalink Blame History

Brief — trim voyage CLAUDE.md to invariants (always-loaded token reduction)

Author: config-audit machine-tuning loop (KTG). Date: 2026-06-29. Why config-audit didn't do this directly: voyage is the operator's plugin — config-audit only writes briefs here, never code. Run this in a voyage session.

Goal

CLAUDE.md is injected every turn while working in the voyage repo (the whole per-repo always-loaded delta). Measured with config-audit manifest: 2,261 always-loaded tokens. The tables (commands, agents) are invariant; the cost sits in six design-history / context block-quote notes whose detail already lives in referenced docs. Moving them out (leaving a terse invariant + pointer) should cut ~900–1,200 tok (~40–50 %) with zero capability loss.

Hard constraints (do NOT break these)

tests/lib/doc-consistency.test.mjs reads CLAUDE.md. Keep the Commands table and the Agents table including the Model column and any count the test cross-checks. After editing, node --test 'tests/**/*.test.mjs' and bash verify.sh must stay green.
Keep every invariant fact — just relocate the verbose rationale/history to the doc that already owns it, and leave a one-line pointer. Don't delete facts; move them.
Docs-only change → no version bump / no catalog ref unless the doc-consistency test demands a badge sync (it shouldn't for a CLAUDE.md prose trim).

Trim targets (line numbers as of commit at brief time; match by content)

Block	~chars / ~tok	Action	Destination (already referenced)
L5 design-principle parenthetical (synthesis-PoC Δ≈0 caveat)	620 / ~155	Keep the honesty caveat in one short clause ("main-context relief is asserted-by-design, not measured — see doc"), move the PoC explanation out	`docs/T1-synthesis-poc-results.md`
L7 v3.0.0 architect-extraction note	376 / ~94	Replace with a one-liner: the plan command auto-discovers `architecture/overview.md` if present (migration history → CHANGELOG)	`CHANGELOG.md`
L9 Trinity context (Tier 1/2/3)	859 / ~215	Keep the asymmetry invariant terse ("Voyage stays unaware of Tier 2/3; Handover 1 = the only integration point; brief-schema changes are breaking"), move the Tier 2/3 description out	`docs/HANDOVER-CONTRACTS.md` §Handover 1
L11 brief-framing 3-layer gate	1,585 / ~396	Biggest. Keep one invariant line ("brief framing must match operator intent — enforced as the `brief_version 2.2` gate: `framing` frontmatter + memory-alignment dim 6 + `## TL;DR`; all BLOCKER for ≥2.2"), move the implementation detail out	`docs/HANDOVER-CONTRACTS.md` §Handover 1 (PUBLIC CONTRACT)
L56 S33 agent-inventory reconcile	740 / ~185	Keep the terse fact ("24 agent files = 21 spawnable + 3 orchestrator reference docs; `synthesis-agent` dormant; all `opus`"), move the sonnet-downgrade rationale out	`docs/voyage-vs-cc-balance-analysis.md` §10
L58 Model & effort axes	588 / ~147	Keep one line ("`opus`=Opus 4.8 / `high`; select agents carry native `effort:`; distinct from brief `phase_signals.effort`"), move the per-agent effort table + axes explanation out	`docs/profiles.md` §Model & effort axes

Net: ~2,261 → ~1,300 tok. (Verify the after-figure with node /path/to/config-audit/scanners/manifest.mjs <voyage-path> → the project claude-md source.)

Procedure

For each block above, confirm the destination doc already contains the detail (it's referenced, so it should) — if not, move the prose there first.
Replace each block-quote with its terse invariant + pointer.
Leave Commands/Agents tables byte-exact (counts + model column).
node --test 'tests/**/*.test.mjs' + bash verify.sh green; confirm doc-consistency passes.
Re-measure; commit docs(claude-md): trim CLAUDE.md to invariants to voyage's Forgejo. Δ lands on the machine after operator /exit + reload.

Notes

This mirrors the same trim already done directly in config-audit (−662 tok), linkedin-studio (−2,266), ms-ai-architect (−346), okr (−15), portfolio-optimiser (−93) — same principle: CLAUDE.md carries invariants for working on the plugin; history/rationale lives in CHANGELOG + docs/.
The voyage honesty culture (no overclaiming) is preserved, not trimmed: the synthesis-PoC Δ≈0 caveat stays as a one-liner; only the long-form explanation moves to its doc.

4.4 KiB Raw Permalink Blame History Unescape Escape