open/voyage
1
0
Fork 0
Code Issues Releases 2 Activity

docs(claude-md): trim CLAUDE.md to invariants (always-loaded token trim, S53)

Browse source 
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
This commit is contained in:
Kjell Tore Guttormsen 2026-06-29 14:49:32 +02:00
commit 15d172521d
3 changed files with 48 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/HANDOVER-CONTRACTS.md
View file

@ -45,6 +45,8 @@ Every validator exposes a CLI: `node lib/validators/<name>.mjs --json <path>` re
**Stability tier: PUBLIC CONTRACT.** Handover 1 is the *only* public integration boundary of the pipeline: `brief.md` is what an upstream producer hands to Voyage, and Voyage consumes it without any knowledge of who produced it. This asymmetry is a hard invariant (see `CLAUDE.md` §Trinity context) — the interactive `/trekbrief` interview is just one producer; a `manual` brief, or an external per-app / per-portfolio producer, is equally valid as long as the artifact conforms to the schema below. No producer is privileged. The consequence: changing this schema — renaming or removing a field, narrowing an enum, or promoting an optional field to required — is a **breaking change for every downstream consumer** and MUST follow the [breaking-change protocol](#breaking-change-protocol) (version bump + N-1 compatibility window). Additive *optional* fields are non-breaking by design: the validator tolerates unknown frontmatter keys silently (forward-compat), so a newer brief still validates against an older consumer. The v5.5.0 contract formalization established `brief_version` **2.1** as the public-contract baseline and, in the same coordinated release, **evolved it to `2.2`** under the breaking-change protocol — adding the required `framing` field + `## TL;DR` section gated at ≥ 2.2 (existing 2.0/2.1 briefs stay valid). See the Versioning paragraph below for the 2.2 details.
**Trinity producer context (informational).** In the author's private three-tier design, Voyage is **Tier 1** (per-task). Its upstream producers are **Tier 2 `app-creator`** (per-app — "what does the app need, what's the next brief?") and **Tier 3 `app-factory`** (per-portfolio — "which app needs me now?"), both pre-implementation and bound for Forgejo when ready. None is privileged: any schema-conforming producer is equally valid, and Voyage stays unaware of Tier 2/3 — this Handover is the only coupling.
**Producer:** `/trekbrief` Phase 4g (after `brief-reviewer` stop-gate passes or iteration cap is hit).
**Consumer:** `/trekresearch` Phase 1 (mode parse + brief validation).