fix(execute): name and read --profile and --gates in the hint, the usage block and Phase 1

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

README.md

@@ -390,7 +390,7 @@ Borrowed: the order from Cherny; the gate on a verdict in a file from Kiro; the
 | **Single step** | `/trekexecute --project <dir> --step 3` | Execute only step 3 |
 | **Foreground** | `/trekexecute --project <dir> --fg` | Force sequential, ignore Execution Strategy |
 | **Single session** | `/trekexecute --project <dir> --session 2` | Execute only session 2 from Execution Strategy |
-| **Profile** | `/trekexecute --profile <name> --project <dir>` | (v4.1.0) Pin model profile for execution. Plan-frontmatter `profile:` is honored when this flag is omitted. See [Profile system](#profile-system-v410). |
+| **Profile** | `/trekexecute --profile <name> --project <dir>` | (v4.1.0) Profile for this run's resolver; the step helper and the controller stay on opus. Plan-frontmatter `profile:` is honored when this flag is omitted. See [Profile system](#profile-system-v410). |
 
 ### Multi-session execution through session orders (worktree-isolated)
 

commands/trekexecute.md

@@ -1,7 +1,7 @@
 ---
 name: trekexecute
 description: Disciplined plan executor — single-session, or multi-session through session orders the user starts, with failure recovery
-argument-hint: "[--project <dir>] [--fg | --resume | --dry-run | --validate | --step N | --session N] [plan.md]"
+argument-hint: "[--project <dir>] [--profile <name>] [--gates [true|false|closed|open]] [--fg | --resume | --dry-run | --validate | --step N | --session N] [plan.md]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent, Skill
 disallowed-tools: TeamCreate
 ---
@@ -79,7 +79,9 @@ Parse `$ARGUMENTS` for mode flags:
    (operator decision 2026-10-08: two questions for one merge became one). The
    MAIN_MERGE_GATE in Phase 8 is always on, regardless of `gates_mode`: it is
    a lock, and the guard's question is the one question.
-9. Otherwise: the entire argument string is the file path. Set **mode = execute**.
+9. If arguments contain `--profile <name>`: set `profile = {name}`; strip both tokens.
+10. Otherwise: the arguments left after every flag above is stripped are the file path.
+    Set **mode = execute**.
 
 If no path is provided (and `--project` was not used to derive one), output
 usage and stop:
@@ -93,6 +95,7 @@ Usage: /trekexecute <plan.md>
        /trekexecute --validate <plan.md>
        /trekexecute --step N <plan.md>
        /trekexecute --session N <plan.md>
+       /trekexecute --profile <name> <plan.md>
        /trekexecute --project <dir> --resume
        /trekexecute --project <dir> --session N
 
@@ -106,6 +109,8 @@ Modes:
   --validate     Schema-only check — parse steps + manifests, no security scan, no execution
   --step N       Execute only step N (foreground)
   --session N    Execute only session N from the plan's Execution Strategy
+  --profile      Profile for this run's resolver; the step helper and the controller stay on opus
+  --gates        Record gates_mode: bare, true or closed = on; false or open = off
 
 Examples:
   /trekexecute .claude/plans/trekplan-2026-04-06-auth-refactor.md
@@ -2959,8 +2964,8 @@ Resolution order (per `lib/profiles/resolver.mjs`):
 3. Inherited from `plan.md` frontmatter `profile:` field (source: `inheritance`)
 4. `premium` default for v4.0-style plans without `profile:` (source: `default`)
 
-The selected profile drives `phase_models.execute` (model for execution
-orchestrator) and `parallel_agents` for wave-parallel sessions.
+The selected profile goes to the resolver. It changes no model here: the step helper and the
+controller run opus (Composition rule below), and nothing in this command reads `parallel_agents`.
 
 Examples:
 ```

docs/command-modes.md

@@ -81,7 +81,7 @@ If `{project_dir}/architecture/overview.md` exists (typically produced by an opt
 | `--fg` | Force foreground — run all steps sequentially, ignore Execution Strategy |
 | `--session N` | Execute only session N from plan's Execution Strategy |
 | `--gates [true\|false\|closed\|open]` | (v3.4.0) Autonomy flag: bare, `true` or `closed` = on; `false` or `open` = off; any other next token is not its value. See `## Autonomy mode` in `docs/operations.md`. `/trekexecute` records `gates_mode` and pauses on nothing; it adds no question of its own before a merge: the guard asks there (operator decision 2026-10-08). |
-| `--profile <name>` | (v4.1.0) Model profile for the execute phase. Inherited from plan.md frontmatter `profile:` if present. |
+| `--profile <name>` | (v4.1.0) Profile for this run's resolver; the step helper and the controller stay on opus. Inherited from plan.md frontmatter `profile:` if present. |
 
 Every mode that executes refuses a plan whose approval in the approval log does not cover its current sha256 (K2). A run ends with the review it starts by itself (`/simplify` → `/trekreview` → verdict gate); a BLOCK or an undecided verdict keeps the merge into main closed. `TREKEXECUTE_MAX_REVIEW_ROUNDS` (default 3) caps the reviews per run.
 

tests/fixtures/jsonl-schemas.md

@@ -22,7 +22,7 @@
 | trekbrief-stats | ts, task, slug, mode, interview_turns, review_iterations, brief_quality, research_topics, auto_research, auto_result, intent_approved, project_dir, order_id, order_claimed_at, order_reason | commands/trekbrief.md (orchestrator-emit Phase 7; order_* added by lib/stats/stats-append.mjs) | trekbrief.md:1140-1164 | profile, phase_models, profile_source | none |
 | trekresearch-stats | ts, question, mode, scope, engine, slug, project_dir, brief_path, dimensions, dimensions_baseline, dimensions_baseline_preserved, effort, conv_turns, empty_turns, unique_sources, agents_local, agents_external, gemini_used, confidence, contradictions, open_questions | lib/stats/stats-append.mjs (trekresearch.md Stats tracking) | trekresearch.md:806-839 | profile, phase_models, parallel_agents, external_research_enabled, profile_source | none |
 | trekplan-stats | ts, task, mode, slug, brief_path, project_dir, codebase_size, codebase_files, agents_deployed, deep_dives, research_briefs_used, research_scout_used, critic_verdict, guardian_verdict, outcome | lib/stats/stats-append.mjs (trekplan.md Phase 12) | trekplan.md:1305-1333 | profile, phase_models, parallel_agents, profile_source | none |
-| trekexecute-stats (Phase 9 record) | ts, plan, plan_type, mode, result, steps_total, steps_passed, steps_failed, steps_skipped, failed_at_step | lib/stats/stats-append.mjs (trekexecute.md Phase 9) | trekexecute.md:2921-2943 | profile, phase_models, profile_source | none |
+| trekexecute-stats (Phase 9 record) | ts, plan, plan_type, mode, result, steps_total, steps_passed, steps_failed, steps_skipped, failed_at_step | lib/stats/stats-append.mjs (trekexecute.md Phase 9) | trekexecute.md:2926-2948 | profile, phase_models, profile_source | none |
 | trekexecute-stats (autonomy events) | ts, event, known_event, payload | lib/stats/event-emit.mjs `emit()` | event-emit.mjs:78-99 | payload.profile, payload.phase_models, payload.profile_source | none |
 | trekexecute-stats (PostToolUse Bash) | ts, session_id, command_excerpt, duration_ms, success | hooks/scripts/post-bash-stats.mjs (Bash PostToolUse) | post-bash-stats.mjs:42-54 | none (hook is plugin-level, not profile-aware) | command_excerpt (CWE-212) |
 | trekreview-stats | ts, slug, verdict, counts (BLOCKER/MAJOR/MINOR/SUGGESTION), reviewed_files_count, mode, duration_ms | lib/stats/stats-append.mjs (trekreview.md Phase 8) | trekreview.md:636-686 | profile, phase_models, profile_source | none |

tests/lib/fix-round-4-5a-prose.test.mjs

@@ -628,3 +628,73 @@ test('[#1] sibling: README.md gives the four values, and no strictness table', (
   assert.doesNotMatch(sec, /`adaptive` \(default\)/);
   assert.match(sec, /accept `--gates \[true\|false\|closed\|open\]`/);
 });
+
+// --- #30 ---------------------------------------------------------------------------
+
+const EXEC = 'commands/trekexecute.md';
+const SAME_ON_OPUS = 'the step helper and the controller stay on opus';
+
+/** Phase 1's top-level numbered rules, each as [number, text of its first line]. */
+function phase1Rules() {
+  const sec = section(read(EXEC), '## Phase 1 — Parse mode and validate input').split('\n');
+  const stop = sec.findIndex((l) => l.startsWith('If no path is provided'));
+  assert.ok(stop !== -1, 'Phase 1 must still say what happens when no path is provided');
+  return sec.slice(0, stop)
+    .map((l) => l.match(/^(\d+)\. (.*)$/))
+    .filter(Boolean)
+    .map((m) => [Number(m[1]), m[2]]);
+}
+
+test('[#30] the frontmatter hint names --profile <name> and --gates', () => {
+  const m = read(EXEC).match(/^argument-hint: (.*)$/m);
+  assert.ok(m, 'trekexecute has no argument-hint');
+  assert.ok(m[1].includes('[--profile <name>]'), `the hint does not name --profile <name>: ${m[1]}`);
+  assert.ok(m[1].includes('[--gates [true|false|closed|open]]'), `the hint does not name --gates: ${m[1]}`);
+  assert.equal(m[1],
+    '"[--project <dir>] [--profile <name>] [--gates [true|false|closed|open]] [--fg | --resume | --dry-run | --validate | --step N | --session N] [plan.md]"');
+});
+
+test('[#30] Phase 1 strips --profile <name>, and its last rule reads what is left after the flags are stripped', () => {
+  const f = flat(section(read(EXEC), '## Phase 1 — Parse mode and validate input'));
+  assert.doesNotMatch(f, /the entire argument string is the file path/i,
+    'Phase 1 still reads the whole argument string as the file path');
+  const rules = phase1Rules();
+  assert.deepEqual(rules.map(([n]) => n), rules.map((_, i) => i + 1), 'Phase 1 rules are not numbered 1..n');
+  const [last, profile] = [rules[rules.length - 1][1], rules[rules.length - 2][1]];
+  assert.ok(last.startsWith('Otherwise: the arguments left after every flag above is stripped are the file path.'),
+    `the last rule does not read what is left after the flags: ${last}`);
+  assert.ok(profile.includes('`--profile <name>`: set `profile = {name}`; strip both tokens'),
+    `the rule before the last one is not the --profile strip rule: ${profile}`);
+});
+
+test('[#30] the usage block names --profile and --gates, and its --profile line keeps the helper and the controller on opus', () => {
+  const usage = partAt(EXEC, 'Usage: /trekexecute <plan.md>', (l) => l.startsWith('```'));
+  assert.ok(usage.includes('/trekexecute --profile <name> <plan.md>'), 'the usage block has no --profile line');
+  assert.ok(usage.includes(`--profile Profile for this run's resolver; ${SAME_ON_OPUS}`),
+    'the Modes list has no --profile line, or it does not keep the helper and the controller on opus');
+  assert.ok(usage.includes('--gates Record gates_mode: bare, true or closed = on; false or open = off'),
+    'the Modes list has no --gates line');
+});
+
+test('[#30] sibling: Profile section says the profile changes no model here', () => {
+  const f = flat(section(read(EXEC), '## Profile (v4.1)'));
+  assert.doesNotMatch(f, /drives `phase_models\.execute`/, 'the Profile section still says the profile drives the execute model');
+  assert.ok(f.includes('The selected profile goes to the resolver. It changes no model here: the step helper and the '
+    + 'controller run opus (Composition rule below), and nothing in this command reads `parallel_agents`.'),
+    'the Profile section does not say the profile changes no model here');
+});
+
+test('[#30] sibling: docs/command-modes.md /trekexecute --profile row keeps the helper and the controller on opus', () => {
+  const sec = section(read('docs/command-modes.md'), '## /trekexecute modes');
+  const rows = sec.split('\n').filter((l) => l.startsWith('| `--profile <name>` |'));
+  assert.equal(rows.length, 1, 'expected one --profile row under /trekexecute modes');
+  assert.doesNotMatch(rows[0], /Model profile for the execute phase/);
+  assert.ok(rows[0].includes(`| (v4.1.0) Profile for this run's resolver; ${SAME_ON_OPUS}.`), rows[0]);
+});
+
+test('[#30] sibling: README.md /trekexecute Profile row keeps the helper and the controller on opus', () => {
+  const rows = read('README.md').split('\n').filter((l) => l.startsWith('| **Profile** | `/trekexecute '));
+  assert.equal(rows.length, 1, 'expected one /trekexecute Profile row in README.md');
+  assert.doesNotMatch(rows[0], /Pin model profile for execution/);
+  assert.ok(rows[0].includes(`| (v4.1.0) Profile for this run's resolver; ${SAME_ON_OPUS}.`), rows[0]);
+});