docs(voyage): record S3 (W2) effort/model decision — option C, freeze brief-effort, keep field name

S3 was a decision-gate. Two-track evidence (codebase map of phase_signals/
phase_models/profiles/resolver + verbatim-cited CC native-effort: semantics)
overturned CC-22's framing and the operator confirmed the path.

Load-bearing finding: Voyage phase_signals.effort (low/standard/high) is an
ORCHESTRATION-SHAPE axis consumed by command prose (which agents/passes/gates
run), while CC native effort: is a per-spawn REASONING budget. Same name,
different axes. A remap would conflate them and silently delete orchestration
behavior, and would not remove the resolver (it also carries the model half).

Operator decisions (2026-06-18):
- CC-22 -> option C: freeze phase_signals.effort 3-level as-is (unblocks the
  v5.4 brief-schema freeze); adopt native effort: additively at the
  agent/profile layer, OUTSIDE the brief contract.
- Keep field name `effort` (no breaking rename); document the
  orchestration-vs-reasoning distinction loudly instead.

Dispositions: CC-21 DECIDED (Opus-4.8-high baseline accepted; native effort:
is the moderation lever; doc-truth follow-up). CC-24/CC-25 DEFER confirmed
(availableModels constrains model only, not effort; MAX_THINKING_TOKENS=0 is
an economy lever). Resolver MAJOR (phase-signal-resolver.mjs:40 ungated model)
stays on S4 — independent of the effort decision.

Matrix: CC-21/CC-22 rows flipped to DECIDED + new "S3 resolutions" section with
S4 scope and the non-blocking open (per-spawn effort param unverified).
Tests 578 pass / 0 fail / 2 skip.

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

docs/cc-upgrade-2.1.181-decision-matrix.md

@@ -82,14 +82,32 @@ S2 shipped the mechanical W3 items and recorded the two W3 decisions. Schemas ve
 
 | ID | Change (version) | Type | Voyage relevance | Decision | Rationale |
 |----|------------------|------|------------------|----------|-----------|
-| **CC-21** | **Opus 4.8** available; `opus` defaults to high/xhigh effort (**2.1.154**, verified) | NEW | All 23 agents + 7 commands pin `model: opus` → now resolve to 4.8 at a higher default effort | **EVALUATE** | Voyage's reasoning changed under it. Confirm behavior, update model references in docs (`CLAUDE.md`, `docs/profiles.md`, README still say things tied to older model assumptions), and decide whether the default-high-effort interacts with the `phase_signals` effort tiers. |
-| **CC-22** | Native `effort:` frontmatter on agents/skills/commands + 5 levels low/medium/high/xhigh/max (**2.1.149/154**, verified) | NEW | Voyage **reinvented** effort as `phase_signals` (low/standard/high) + the `phase-signal-resolver.mjs`/`resolver.mjs` system (which carries the MAJOR doc/code-inconsistency finding) | **EVALUATE** (core W2) | **The pivotal decision.** Options: (a) map `phase_signals` effort → native `effort:` and let the harness apply it (simplifies/possibly removes resolver code); (b) keep the bespoke system; (c) hybrid. This **must resolve before v5.4 freezes the brief schema as a public contract** — freezing `phase_signals` shape now risks freezing something about to change. Absorbs/retires the resolver MAJOR finding. |
+| **CC-21** | **Opus 4.8** available; `opus` defaults to high/xhigh effort (**2.1.154**, verified) | NEW | All 23 agents + 7 commands pin `model: opus` → now resolve to 4.8 at a higher default effort | **DECIDED (S3)** | Accept Opus-4.8-`high` as the new baseline (verified: opus default = `high`). The moderation lever is native `effort:` (CC-22 option C). Doc follow-up: update model/effort references in `CLAUDE.md`/`docs/profiles.md`/README. See §S3 resolutions. |
+| **CC-22** | Native `effort:` frontmatter on agents/skills/commands + 5 levels low/medium/high/xhigh/max (**2.1.149/154**, verified) | NEW | Voyage **reinvented** effort as `phase_signals` (low/standard/high) + the `phase-signal-resolver.mjs`/`resolver.mjs` system (which carries the MAJOR doc/code-inconsistency finding) | **DECIDED (S3): option C** | **Resolved.** The (a)-map premise was false: Voyage `effort` = *orchestration-shape* (which agents/passes/gates run, consumed by command prose), native `effort:` = *per-spawn reasoning budget* — **different axes, same name.** Decision: **freeze `phase_signals.effort` 3-level (low/standard/high) as-is** (unblocks v5.4) and adopt native `effort:` **additively at the agent/profile layer, outside the brief contract.** Field name kept `effort` (no breaking rename) + distinction documented. Does NOT retire the resolver MAJOR (that's model-gating, independent — S4). See §S3 resolutions. |
 | **CC-23** | Claude Fable 5 (Mythos-class) GA (2.1.170) | NEW | Voyage is a planning/reasoning pipeline; Fable is a different model class | **SKIP** (revisit) | Not an obvious fit for deep-planning agents. Note as an option if a future profile wants a distinct model class for a specific phase. |
 | **CC-24** | `enforceAvailableModels` managed setting (2.1.175); `availableModels` now constrains Default + subagent overrides (2.1.172/176) | CHANGE | enterprise deployments could constrain Voyage's `opus`/`sonnet` picks | **DEFER** | Document that profile model picks must live within any managed `availableModels` allowlist. Relevant for enterprise consumers post-open-release. |
 | **CC-25** | `MAX_THINKING_TOKENS=0` / `--thinking disabled` disables thinking on think-by-default models (2.1.166) | NEW | could gate thinking in cheap `economy`-profile phases | **DEFER** | Minor cost lever; fold into W2 profile design if useful. |
 
 ---
 
+## S3 resolutions (W2 effort/model alignment — 2026-06-18, operator-gated)
+
+S3 was a decision-gate. Two-track evidence (codebase map of `phase_signals`/`phase_models`/profiles/resolver + verbatim-cited CC native-`effort:` semantics) overturned CC-22's framing hypothesis and the operator confirmed the path.
+
+**The load-bearing finding — two axes, one name.** Voyage's `phase_signals.effort` (low/standard/high) is consumed only by **command prose** to pick *orchestration shape*: skip/add swarm passes, gate strictness, sequential-vs-parallel (`trekplan.md:925–957`, `trekresearch.md:472–503`, `trekreview.md:385–417`, `trekexecute.md:1542–1577`). CC native `effort:` (low/medium/high/xhigh/max) is a *per-spawn reasoning-token budget* applied by the harness. `low` in Voyage means "run fewer agents," not "think less." A remap (option a) would conflate the two and silently delete orchestration behavior — and would **not** remove the resolver (it also carries the model half). Verified native semantics: `effort:` settable in agent/skill/command frontmatter; precedence env (`CLAUDE_CODE_EFFORT_LEVEL`) > frontmatter > session > model default; Opus 4.8 default = `high`.
+
+**Operator decisions (2026-06-18):**
+1. **CC-22 → option C.** Freeze `phase_signals.effort` 3-level as-is (it is an orchestration axis, deliberately not the native 5-level vocab) → **unblocks the v5.4 brief-schema freeze**. Adopt native `effort:` additively, at the agent/profile layer, outside the brief contract.
+2. **Field name kept `effort`** (no breaking rename at v5.4); the orchestration-vs-reasoning distinction is documented loudly instead.
+
+**Dispositions feeding S4 / v5.4 / profile design:**
+- **CC-21 — DECIDED.** Opus-4.8-`high` is the accepted baseline; native `effort:` is the moderation lever. Doc-truth follow-up: model/effort references in `CLAUDE.md`/`docs/profiles.md`/README.
+- **CC-24 — DEFER (confirmed).** `availableModels`/`enforceAvailableModels` constrains **model only**, not effort (verified). Document that profile model picks must stay within any enterprise allowlist.
+- **CC-25 — DEFER (confirmed).** `MAX_THINKING_TOKENS=0` overrides effort (disables thinking) — the most aggressive `economy` cost lever; fold into profile design.
+- **Resolver MAJOR (S4, unchanged).** `phase-signal-resolver.mjs:40` copies `model` ungated while `:39` gates `effort`. Independent of the effort decision; option C keeps `phase_signals.model`, so the fix (import + apply `BASE_ALLOWED_MODELS`) stays on S4.
+
+**S4 scope (now unblocked):** (1) resolver MAJOR model-gate fix; (2) additive native `effort:` — verified-safe minimum is static per-agent frontmatter (retrieval agents `task-finder`/`git-historian`/`dependency-tracer`/`architecture-mapper` lower; reasoning agents `plan-critic`/`risk-assessor`/`contrarian-researcher`/`review-coordinator` stay high); (3) doc-truth model/effort updates; (4) document the effort-axis distinction. **Open (non-blocking):** profile-driven *dynamic* effort needs verification — per-spawn `effort` param is **unverified** (only `model` is documented per-spawn); dynamic would otherwise need env-var injection.
+
 ## W1 — Orchestration architecture (multi-week, empirical)
 
 | ID | Change (version) | Type | Voyage relevance | Decision | Rationale |