fix(agents): no agent is pinned below the high floor

Operator rule (2026-10-05): standard is Opus 5.5 at reasoning effort High. Four retrieval agents (architecture-mapper, dependency-tracer, git-historian, task-finder) pinned effort: medium in frontmatter, which overrides the session level, so every /trekplan exploration ran part of its swarm below the floor. They came from fdd3ad8 on the premise that unpinned agents inherit high; e4e37f9 corrected that (unpinned inherits the session; Opus 5.5 defaults to medium), so the reason for medium was already gone. All four now pin high; the other agents keep following the session (operator's choice). docs/profiles.md (one bullet for the eight pinned agents), CLAUDE.md and README.md updated; the model-default sentence stays. Dated decision records and CHANGELOG untouched.

Red: 4 of 5 new tests fail on the pre-fix files - effort floor over all agents (offenders: the four), the four pin exactly high, no live doc says retrieval runs at medium (hits docs/profiles.md:76, CLAUDE.md:85, README.md:806), profiles.md names the four as high. Known-positive control green on arrival.
Verify 153/153 (agent-frontmatter, doc-consistency). SC9 probe: npm test green under a scratch HOME with CLAUDE_PLUGIN_DATA empty, nothing under its plugin data dir. Suite 1393 (1391/0/2).

The change is repo-true, not installed-true, until a release.

Voyage order 20261005T104513Z-1250514346, plan step 5/5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

CLAUDE.md

@@ -82,7 +82,7 @@ Full flag reference for each command (modes, `--gates`, `--profile`, breaking ch
 
 > **Inventory (S33 reconcile, updated v5.10.1).** 23 agent files = **20 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 23 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.** On the Anthropic API, `opus` = Opus 5.5 and `sonnet` = Sonnet 5.5 (both default reasoning effort `medium`); `fable` = Fable 5.1 (the most capable model in Claude Code; default `high`, so xhigh must be chosen explicitly). An agent without `effort:` inherits the session level. 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.** On the Anthropic API, `opus` = Opus 5.5 and `sonnet` = Sonnet 5.5 (both default reasoning effort `medium`); `fable` = Fable 5.1 (the most capable model in Claude Code; default `high`, so xhigh must be chosen explicitly). An agent without `effort:` inherits the session level. Eight agents pin native per-spawn `effort: high` and the rest follow the session; none pins below `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)
 

README.md

@@ -803,7 +803,7 @@ Default JSONL stats stream (`${CLAUDE_PLUGIN_DATA}/trek*-stats.jsonl`) is unchan
 
 The default `premium` profile runs **Opus on every phase** of the pipeline's agent work — the exploration and review swarms (5–10 sub-agents per command; spawn sites inject the composed brief > profile > frontmatter resolution, with `agents/*.md` `model: opus` pins as the fallback) and the executor (one per plan session). The command orchestrator itself is not profile-controlled: as of v5.9, command frontmatter omits `model:`, so the orchestrator follows the session model. For cheaper runs, opt into `--profile balanced` (Sonnet on brief/research/execute/continue, Opus on plan + review) or `--profile economy` (Sonnet everywhere); for maximum quality, `--profile fable` (Fable 5.1 on every phase). Per-command cost is published in `${CLAUDE_PLUGIN_DATA}/trek*-stats.jsonl` if you want exact numbers.
 
-On the Anthropic API the `opus` alias resolves to **Opus 5.5** and `sonnet` to **Sonnet 5.5** (both default to reasoning effort `medium`), and `fable` to **Fable 5.1** (the most capable model in Claude Code; default reasoning effort `high` — xhigh must be chosen explicitly, see [`docs/profiles.md`](docs/profiles.md)). Other providers resolve `opus` and `sonnet` to other versions. Note two distinct effort axes that share the word "effort": brief `phase_signals.effort` (low/standard/high) tunes *orchestration shape* — how many agents and passes run — while native `effort:` on selected agents (retrieval at `medium`, adversarial-reasoning at `high`) tunes the *per-spawn reasoning budget*. See [`docs/profiles.md`](docs/profiles.md) § Model & effort axes.
+On the Anthropic API the `opus` alias resolves to **Opus 5.5** and `sonnet` to **Sonnet 5.5** (both default to reasoning effort `medium`), and `fable` to **Fable 5.1** (the most capable model in Claude Code; default reasoning effort `high` — xhigh must be chosen explicitly, see [`docs/profiles.md`](docs/profiles.md)). Other providers resolve `opus` and `sonnet` to other versions. Note two distinct effort axes that share the word "effort": brief `phase_signals.effort` (low/standard/high) tunes *orchestration shape* — how many agents and passes run — while native `effort:` (eight agents pin `high`; the rest follow the session) tunes the *per-spawn reasoning budget*. See [`docs/profiles.md`](docs/profiles.md) § Model & effort axes.
 
 For per-profile cost estimates, see [`docs/profiles.md`](docs/profiles.md).
 

agents/architecture-mapper.md

@@ -4,7 +4,7 @@ description: |
   Use this agent when you need deep architecture analysis of a codebase — structure,
   tech stack, patterns, anti-patterns, and key abstractions.
 model: opus
-effort: medium
+effort: high
 color: cyan
 tools: ["Read", "Glob", "Grep", "Bash"]
 ---

agents/dependency-tracer.md

@@ -4,7 +4,7 @@ description: |
   Use this agent when you need to trace import chains, map data flow, or understand
   how modules connect and what side effects they produce.
 model: opus
-effort: medium
+effort: high
 color: blue
 tools: ["Read", "Glob", "Grep", "Bash"]
 ---

agents/git-historian.md

@@ -4,7 +4,7 @@ description: |
   Use this agent to analyze git history for planning context — recent changes,
   code ownership, hot files, and active branches relevant to the task.
 model: opus
-effort: medium
+effort: high
 color: yellow
 tools: ["Bash", "Read", "Glob", "Grep"]
 ---

agents/task-finder.md

@@ -5,7 +5,7 @@ description: |
   related to the planning task. Replaces generic Explore agents with targeted,
   structured code discovery.
 model: opus
-effort: medium
+effort: high
 color: green
 tools: ["Read", "Glob", "Grep", "Bash"]
 ---

docs/profiles.md

@@ -73,12 +73,11 @@ native `effort:`.
 **Native `effort:` on agents.** Voyage sets the reasoning axis statically on
 selected agents, overriding the session level:
 
-- **Retrieval agents → `medium`:** `task-finder`, `git-historian`,
+- **Eight agents pin `high`:** the retrieval agents `task-finder`,
-  `dependency-tracer`, `architecture-mapper` (structured discovery, not deep
+  `git-historian`, `dependency-tracer`, `architecture-mapper`, and the
-  multi-step reasoning).
+  adversarial-reasoning agents `plan-critic`, `risk-assessor`,
-- **Adversarial-reasoning agents → `high`:** `plan-critic`, `risk-assessor`,
+  `contrarian-researcher`, `review-coordinator`. No agent pins below `high`
-  `contrarian-researcher`, `review-coordinator` (synthesis and stress-testing
+  (operator rule, 2026-10-05: standard is Opus 5.5 at effort High).
-  where reasoning depth pays off).
 - **All other agents:** unset → inherits the session's effort level (a session
   that nothing sets runs at its model's default — `medium` on Opus 5.5).
 

tests/lib/agent-frontmatter.test.mjs

@@ -167,3 +167,24 @@ test('agent bodies retain at least 32 <example> blocks (M4: relocation moves, ne
     `— examples may have been deleted instead of relocated (M4)`,
   );
 });
+
+// Operator rule (2026-10-05): "standard" is Opus 5.5 at reasoning effort High. A pinned
+// `effort:` overrides the session level, so a pin below `high` runs that agent below the
+// floor whatever the session is set to. Unpinned agents follow the session.
+const EFFORT_FLOOR = new Set(['high', 'xhigh', 'max']);
+const RETRIEVAL_AGENTS = ['architecture-mapper.md', 'dependency-tracer.md', 'git-historian.md', 'task-finder.md'];
+
+test('no agents/*.md pins a reasoning effort below high', () => {
+  const pinned = agentFiles
+    .map((f) => [f, getTopLevelValue(extractFrontmatter(read(`agents/${f}`)) || '', 'effort')])
+    .filter(([, v]) => v !== null);
+  assert.ok(pinned.length > 0, 'no agent carries effort: - the check would prove nothing');
+  const below = pinned.filter(([, v]) => !EFFORT_FLOOR.has(v)).map(([f, v]) => `agents/${f}: effort: ${v}`);
+  assert.deepEqual(below, [], 'fix the agent file - the floor is the operator\'s rule');
+});
+
+test('the four retrieval agents pin effort: high', () => {
+  for (const f of RETRIEVAL_AGENTS) {
+    assert.equal(getTopLevelValue(extractFrontmatter(read(`agents/${f}`)), 'effort'), 'high', `agents/${f}`);
+  }
+});

tests/lib/doc-consistency.test.mjs

@@ -2111,3 +2111,31 @@ test('/trekbrief --approve: CLAUDE.md, README.md and docs/command-modes.md say t
     assert.match(line, /trekbrief (stats )?record/, `${rel}: the --approve row must say it writes the trekbrief record`);
   }
 });
+
+// --- effort floor: no live doc claims retrieval agents run at medium ------------
+// Operator rule (2026-10-05): no agent is pinned below `high`. The model DEFAULT
+// sentence ("Opus 5.5 ... default reasoning effort `medium`") stays true and is not a pin.
+const RETRIEVAL_MEDIUM = /retrieval(?: agents)?\s*(?:→|->|at)\s*`medium`/i;
+
+test('effort floor: no live doc claims retrieval agents run at medium', () => {
+  const hits = [];
+  for (const f of ['docs/profiles.md', 'CLAUDE.md', 'README.md']) {
+    read(f).split('\n').forEach((l, i) => { if (RETRIEVAL_MEDIUM.test(l)) hits.push(`${f}:${i + 1}`); });
+  }
+  assert.deepEqual(hits, [], 'the four retrieval agents pin `high` now');
+});
+
+test('effort floor: known-positive control — the query finds the old phrases, not the model default', () => {
+  for (const phrase of ['**Retrieval agents → `medium`:**', '(retrieval → `medium`, adversarial', 'retrieval at `medium`, adversarial']) {
+    assert.match(phrase, RETRIEVAL_MEDIUM, phrase);
+  }
+  assert.doesNotMatch('both with default reasoning effort `medium`', RETRIEVAL_MEDIUM);
+});
+
+test('effort floor: profiles.md names the four retrieval agents as high', () => {
+  const axes = (read('docs/profiles.md').split('\n## Model & effort axes\n')[1] || '').split('\n## ')[0];
+  const bullet = axes.split('\n- ').find((b) => ['task-finder', 'git-historian', 'dependency-tracer', 'architecture-mapper'].every((a) => b.includes(a)));
+  assert.ok(bullet, 'one bullet in §Model & effort axes names all four retrieval agents');
+  assert.match(bullet, /`high`/);
+  assert.doesNotMatch(bullet, /`medium`/);
+});