Kjell Tore Guttormsen
15d172521d
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
40 lines
4.4 KiB
Markdown
40 lines
4.4 KiB
Markdown
# 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
|
||
|
||
1. 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.
|
||
2. Replace each block-quote with its terse invariant + pointer.
|
||
3. Leave Commands/Agents tables byte-exact (counts + model column).
|
||
4. `node --test 'tests/**/*.test.mjs'` + `bash verify.sh` green; confirm `doc-consistency` passes.
|
||
5. 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.
|