From 22058459f878cf7a28831d74fd7a163ebb857bf1 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Thu, 2 Jul 2026 17:14:35 +0200 Subject: [PATCH] docs(voyage): fable-aware allowlist prose in contracts, architecture, templates, CLAUDE.md --- CLAUDE.md | 4 ++-- docs/HANDOVER-CONTRACTS.md | 10 +++++++++- docs/architecture.md | 2 +- docs/command-modes.md | 2 +- templates/session-spec-template.md | 2 +- 5 files changed, 14 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b746629..ffac6fb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -55,13 +55,13 @@ Full flag reference for each command (modes, `--gates`, `--profile`, breaking ch > **Inventory (S33 reconcile).** 24 agent files = **21 spawnable** (one, `synthesis-agent`, ships **dormant** — Δ≈0, wired to nothing) **+ 3 orchestrator reference docs** (`planning-/research-/review-orchestrator` document the inline `/trek*` workflow, not spawnable capabilities). All 24 stay `model: opus` (operator pin `40d8742`); the glue/mechanical/retrieval/dormant roles were reconsidered for a sonnet downgrade and **kept opus** — decision record: `docs/voyage-vs-cc-balance-analysis.md` §10. -> **Model & effort.** `opus` = Opus 4.8 (default reasoning effort `high`); `sonnet` = Sonnet 4.6. Select agents carry native per-spawn `effort:` (retrieval → `medium`, adversarial-reasoning → `high`) — a different axis from brief `phase_signals.effort` (orchestration shape: which agents/passes run). Per-agent table + axes → `docs/profiles.md` §Model & effort axes. +> **Model & effort.** `opus` = Opus 4.8 (default reasoning effort `high`); `sonnet` = Sonnet 4.6; `fable` = Fable 5 (Mythos-class, above Opus — reasoning effort inherits from the session; xhigh requires a session-level setting). Select agents carry native per-spawn `effort:` (retrieval → `medium`, adversarial-reasoning → `high`) — a different axis from brief `phase_signals.effort` (orchestration shape: which agents/passes run). Per-agent table + axes → `docs/profiles.md` §Model & effort axes. ## Reference docs (read on demand) - **Architecture, workflows, project-directory contract, state, terminology:** `docs/architecture.md` - **Quality infrastructure (`lib/` validators, parsers, autonomy primitives, hooks):** `docs/architecture.md` §Quality infrastructure - **Autonomy gates (`--gates`), Path A/B/C decision:** `docs/operations.md` -- **Profile system (`--profile economy/balanced/premium`), lookup order, custom profiles:** `docs/operations.md` +- **Profile system (`--profile economy/balanced/premium/fable`), lookup order, custom profiles:** `docs/operations.md` - **Observability (Stop hook, OTLP/textfile export, SSRF mitigation):** `docs/operations.md` - **Handover contracts (the 7 pipeline handovers):** `docs/HANDOVER-CONTRACTS.md` diff --git a/docs/HANDOVER-CONTRACTS.md b/docs/HANDOVER-CONTRACTS.md index 92cde1b..79bdeef 100644 --- a/docs/HANDOVER-CONTRACTS.md +++ b/docs/HANDOVER-CONTRACTS.md @@ -115,9 +115,17 @@ Optional but standard sections: `## Non-Goals`, `## Constraints`, `## Preference - `BRIEF_INVALID_PHASE_SIGNALS` → strict halt; phase_signals must be a list of `{phase, effort?, model?}` entries. - `BRIEF_INVALID_PHASE_SIGNAL_PHASE` → strict halt; phase ∉ `[research, plan, execute, review]`. - `BRIEF_INVALID_EFFORT` → strict halt; effort ∉ `[low, standard, high]`. -- `BRIEF_INVALID_MODEL` → strict halt; model ∉ `BASE_ALLOWED_MODELS` (currently `[sonnet, opus]`). +- `BRIEF_INVALID_MODEL` → strict halt; model ∉ `BASE_ALLOWED_MODELS` (currently `[sonnet, opus, fable]`). - `BRIEF_SIGNALS_MUTUALLY_EXCLUSIVE` → strict halt; cannot set both `phase_signals` and `phase_signals_partial: true`. +**Compatibility direction of the v5.9 allowlist widening (`fable`):** enum +widening is safe for new readers of old data, not old readers of new data. +Existing sonnet/opus briefs stay valid under the v5.9+ validator (non-breaking, +no `brief_version` bump — value-space extension, not a schema change). The +reverse does NOT hold: a fable-bearing brief REQUIRES a v5.9+ validator — an +older cached brief-validator (e.g. a stale v5.8 marketplace clone) rejects it +with `BRIEF_INVALID_MODEL`. + --- ## Handover 2 — research/*.md → plan diff --git a/docs/architecture.md b/docs/architecture.md index 6d0a4f0..55beeb9 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -37,7 +37,7 @@ Doc-consistency test at `tests/lib/doc-consistency.test.mjs` pins agent-table co **Brief:** 7-phase workflow: Parse mode → Create project dir → Phase 3 completeness loop (section-driven, no question cap) → Phase 3.5 per-phase effort dialog (v5.1) → Phase 4 draft/review/revise with `brief-reviewer` as stop-gate (max 3 iterations; gate = all dimensions ≥ 4 and research plan = 5) → Finalize (`brief.md` on pass, or `brief_quality: partial` on cap/force-stop) → Manual/auto opt-in → Stats. Always interactive. Auto mode runs research + plan inline in the main context (v2.4.0). -**Phase 3.5 (v5.1) — adaptive-depth signals:** Between Phase 3 completeness exit and Phase 4 draft, the operator commits an effort level (`low | standard | high`) and an optional `model` (`sonnet | opus`) per downstream phase (`research`, `plan`, `execute`, `review`) via 4 tier-coupled `AskUserQuestion` calls. The choices land in `brief.md` frontmatter as `phase_signals:` (a list of `{phase, effort?, model?}` entries) when committed, or `phase_signals_partial: true` when the operator force-stops. `brief_version: 2.1` activates the **sequencing gate**: validator emits `BRIEF_V51_MISSING_SIGNALS` if a 2.1-versioned brief lacks both fields. Downstream commands surface a friendly hint pointing back to `/trekbrief` — enforcement is validator-only. Composition is documented prose in each downstream command's `## Composition rule (v5.1)` section: `brief.phase_signals[phase] > profile.phase_models[phase]`. The brief signal wins per-phase when present; the profile fills gaps. `effort == low` activates each command's existing `--quick`-equivalent code-path (`/trekexecute` low-effort = `--gates open` + sequential-only). High-effort behavior is deferred to v5.1.1 per brief Non-Goal. +**Phase 3.5 (v5.1) — adaptive-depth signals:** Between Phase 3 completeness exit and Phase 4 draft, the operator commits an effort level (`low | standard | high`) and an optional `model` (`sonnet | opus | fable`) per downstream phase (`research`, `plan`, `execute`, `review`) via 4 tier-coupled `AskUserQuestion` calls. The choices land in `brief.md` frontmatter as `phase_signals:` (a list of `{phase, effort?, model?}` entries) when committed, or `phase_signals_partial: true` when the operator force-stops. `brief_version: 2.1` activates the **sequencing gate**: validator emits `BRIEF_V51_MISSING_SIGNALS` if a 2.1-versioned brief lacks both fields. Downstream commands surface a friendly hint pointing back to `/trekbrief` — enforcement is validator-only. Composition is documented prose in each downstream command's `## Composition rule (v5.1)` section: `brief.phase_signals[phase] > profile.phase_models[phase]`. The brief signal wins per-phase when present; the profile fills gaps. `effort == low` activates each command's existing `--quick`-equivalent code-path (`/trekexecute` low-effort = `--gates open` + sequential-only). High-effort behavior is deferred to v5.1.1 per brief Non-Goal. **Research:** Foreground workflow (v2.4.0): Parse mode → Interview → Parallel research swarm (5 local + 4 external + 1 bridge, spawned from main context) → Follow-ups → Triangulation → Synthesis + brief → Stats. With `--project`, writes to `{dir}/research/NN-slug.md`. diff --git a/docs/command-modes.md b/docs/command-modes.md index 5390150..c414149 100644 --- a/docs/command-modes.md +++ b/docs/command-modes.md @@ -9,7 +9,7 @@ Per-command flag tables, imported from `CLAUDE.md` via pointer. | _(default)_ | Dynamic interview until quality gates pass → brief.md with research plan | | `--quick` | Compact start; still escalates if required sections are weak or the brief-review gate fails → brief.md with research plan | | `--gates {true\|false}` | (v3.4.0) Boolean autonomy-gate flag; present → gating on. Policy (`gates_mode`) detailed under `## Autonomy mode` in `docs/operations.md`. | -| `--profile ` | (v4.1.0) Model profile: `economy` / `balanced` / `premium` / ``. Sets `phase_models` for the brief phase. See `## Profile system` in `docs/operations.md`. | +| `--profile ` | (v4.1.0) Model profile: `economy` / `balanced` / `premium` / `fable` / ``. Sets `phase_models` for the brief phase. See `## Profile system` in `docs/operations.md`. | Always interactive. Phase 3 is a section-driven completeness loop (no hard cap on question count); Phase 4 runs a `brief-reviewer` stop-gate with max 3 review iterations. After writing the brief, asks the user to choose manual (print commands) or auto (Claude runs research + plan in foreground). diff --git a/templates/session-spec-template.md b/templates/session-spec-template.md index 7059e08..ee2099d 100644 --- a/templates/session-spec-template.md +++ b/templates/session-spec-template.md @@ -141,7 +141,7 @@ introduced. This section bridges sessions — it's the "baton" in a relay race.} - **Master plan:** `{plan file path}` - **Steps from plan:** {step N}–{step M} - **Estimated complexity:** {low | medium | high} -- **Model recommendation:** {opus | sonnet} — {rationale} +- **Model recommendation:** {opus | sonnet | fable} — {rationale} ## Recovery Metadata