From 71fcf6065af5eeeef2ffb985c761d7529e404e2a Mon Sep 17 00:00:00 2001
From: Kjell Tore Guttormsen <hello@fromaitochitta.com>
Date: Sat, 9 May 2026 09:38:36 +0200
Subject: [PATCH] =?UTF-8?q?feat(voyage):=20document=20--profile=20flag=20i?=
 =?UTF-8?q?n=20all=206=20commands=20=E2=80=94=20SC=20#4=20+=20arv-policy?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Step 7 av v4.1-execute (Wave 3, Session 4).

Legg ny "## Profile (v4.1)"-seksjon i hver kommando-fil rett før "## Hard rules":
- trekbrief.md: --profile + VOYAGE_PROFILE + premium default
- trekresearch.md: + economy/balanced auto-disable external_research_enabled
- trekplan.md: + plan.md frontmatter recording for inheritance
- trekexecute.md: + 4-step resolution (flag > env > inheritance > default)
- trekreview.md: + opus-default for review-deepening
- trekcontinue.md: spesiell — INHERITANCE er default (ikke premium), --profile
  overstyr emitter stderr-advarsel

Tester (13 nye, baseline 432 → 445):
- 6 commands × 2 (--profile + VOYAGE_PROFILE)
- trekcontinue.md "inheritance"-keyword

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 plugins/voyage/commands/trekbrief.md          | 19 +++++++++
 plugins/voyage/commands/trekcontinue.md       | 30 ++++++++++++++
 plugins/voyage/commands/trekexecute.md        | 23 +++++++++++
 plugins/voyage/commands/trekplan.md           | 25 +++++++++++
 plugins/voyage/commands/trekresearch.md       | 21 ++++++++++
 plugins/voyage/commands/trekreview.md         | 22 ++++++++++
 .../tests/lib/profile-flag-coverage.test.mjs  | 41 +++++++++++++++++++
 7 files changed, 181 insertions(+)
 create mode 100644 plugins/voyage/tests/lib/profile-flag-coverage.test.mjs

diff --git a/plugins/voyage/commands/trekbrief.md b/plugins/voyage/commands/trekbrief.md
index a9d7406..8ee392c 100644
--- a/plugins/voyage/commands/trekbrief.md
+++ b/plugins/voyage/commands/trekbrief.md
@@ -675,6 +675,25 @@ Append one record to `${CLAUDE_PLUGIN_DATA}/trekbrief-stats.jsonl`:
 If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip silently.
 Never let stats failures block the workflow.
 
+## Profile (v4.1)
+
+Accepts `--profile <name>` where `<name>` is one of `economy`, `balanced`,
+`premium`, or a custom profile under `voyage-profiles/`. Default: `premium`.
+
+Resolution order (per `lib/profiles/resolver.mjs`):
+1. `--profile` flag (source: `flag`)
+2. `VOYAGE_PROFILE` environment variable (source: `env`)
+3. `premium` default (source: `default`)
+
+Examples:
+```
+/trekbrief --profile economy
+VOYAGE_PROFILE=balanced /trekbrief
+```
+
+Stats records emit `profile`, `phase_models`, and `profile_source` so operators
+can audit which profile drove which session.
+
 ## Hard rules
 
 1. **Interactive only.** This command requires user input. There is no
diff --git a/plugins/voyage/commands/trekcontinue.md b/plugins/voyage/commands/trekcontinue.md
index 1d9fee3..f71f947 100644
--- a/plugins/voyage/commands/trekcontinue.md
+++ b/plugins/voyage/commands/trekcontinue.md
@@ -293,6 +293,36 @@ if the env var is set; silently skip otherwise.
 {"ts":"<iso-8601>","project":"<project>","next_session_label":"<label>","status":"<status>"}
 ```
 
+## Profile (v4.1) — inheritance from plan-frontmatter
+
+Accepts `--profile <name>` where `<name>` is `economy`, `balanced`, `premium`,
+or a custom profile under `voyage-profiles/`. Default: `premium`.
+
+Unlike the other voyage commands, `/trekcontinue` defaults to **inheritance**
+from the resumed plan's frontmatter `profile:` field rather than to `premium`.
+This keeps a multi-session run consistent across resumptions.
+
+Resolution order (per `lib/profiles/resolver.mjs` `resolveTrekcontinueProfile`):
+1. `--profile` flag (source: `flag`) — explicit override, emits stderr advisory
+   `[voyage] profile inheritance overridden by --profile flag: <plan-profile> → <flag-profile>`
+2. `VOYAGE_PROFILE` env-var (source: `env`)
+3. Plan-frontmatter `profile:` field (source: `inheritance`) — typical case
+4. `premium` default for v4.0-style plans without `profile:` (source: `default`)
+
+The inherited profile drives `phase_models.continue` for the next session's
+orchestration. Operators who explicitly want to switch profiles mid-run pass
+`--profile <name>` and accept the advisory (e.g. drop from `premium` to
+`balanced` mid-run to save cost on later sessions).
+
+Examples:
+```
+/trekcontinue                                  # inherits from plan.md
+/trekcontinue --profile balanced               # explicit override + advisory
+VOYAGE_PROFILE=economy /trekcontinue           # env-var override
+```
+
+Stats records emit `profile` and `profile_source` per Phase 5 record.
+
 ## Hard rules
 
 - **Idempotent.** Running `/trekcontinue` twice in the same Claude session
diff --git a/plugins/voyage/commands/trekexecute.md b/plugins/voyage/commands/trekexecute.md
index 82ad05c..27f1514 100644
--- a/plugins/voyage/commands/trekexecute.md
+++ b/plugins/voyage/commands/trekexecute.md
@@ -1496,6 +1496,29 @@ Append one record to `${CLAUDE_PLUGIN_DATA}/trekexecute-stats.jsonl`:
 If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip silently.
 Never let stats failures block the workflow.
 
+## Profile (v4.1)
+
+Accepts `--profile <name>` where `<name>` is `economy`, `balanced`, `premium`,
+or a custom profile under `voyage-profiles/`. Default: `premium`.
+
+Resolution order (per `lib/profiles/resolver.mjs`):
+1. `--profile` flag (source: `flag`)
+2. `VOYAGE_PROFILE` env-var (source: `env`)
+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.
+
+Examples:
+```
+/trekexecute --profile economy --project .claude/projects/2026-05-09-add-auth
+VOYAGE_PROFILE=balanced /trekexecute --project ...
+```
+
+Stats records emit `profile`, `phase_models`, and `profile_source` per
+Phase 9 record.
+
 ## Hard rules
 
 1. **No AskUserQuestion for execution decisions.** All execution decisions come
diff --git a/plugins/voyage/commands/trekplan.md b/plugins/voyage/commands/trekplan.md
index 0d38c3c..0be812b 100644
--- a/plugins/voyage/commands/trekplan.md
+++ b/plugins/voyage/commands/trekplan.md
@@ -829,6 +829,31 @@ Record format (one JSON line):
 If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip tracking silently.
 Never let tracking failures block the main workflow.
 
+## Profile (v4.1)
+
+Accepts `--profile <name>` where `<name>` is `economy`, `balanced`, `premium`,
+or a custom profile under `voyage-profiles/`. Default: `premium`.
+
+Resolution order (per `lib/profiles/resolver.mjs`):
+1. `--profile` flag (source: `flag`)
+2. `VOYAGE_PROFILE` env-var (source: `env`)
+3. `premium` default (source: `default`)
+
+The selected profile drives `phase_models.plan` (model used for the planning
+LLM), `parallel_agents_min`/`max` (the exploration swarm size), and is
+recorded in `plan.md` frontmatter so `/trekexecute` and `/trekcontinue` can
+inherit it across the pipeline.
+
+Examples:
+```
+/trekplan --profile economy --project .claude/projects/2026-05-09-add-auth
+/trekplan --profile balanced --brief brief.md
+VOYAGE_PROFILE=balanced /trekplan --project ...
+```
+
+Stats records emit `profile`, `phase_models`, `parallel_agents`, and
+`profile_source` so operators can audit which profile drove which session.
+
 ## Hard rules
 
 - **Brief-driven**: Every plan decision must trace back to a section of the
diff --git a/plugins/voyage/commands/trekresearch.md b/plugins/voyage/commands/trekresearch.md
index 33159fb..1af0522 100644
--- a/plugins/voyage/commands/trekresearch.md
+++ b/plugins/voyage/commands/trekresearch.md
@@ -410,6 +410,27 @@ Record format (one JSON line):
 
 If `${CLAUDE_PLUGIN_DATA}` is not set or not writable, skip tracking silently.
 
+## Profile (v4.1)
+
+Accepts `--profile <name>` where `<name>` is `economy`, `balanced`, `premium`,
+or a custom profile under `voyage-profiles/`. Default: `premium`.
+
+Resolution order (per `lib/profiles/resolver.mjs`):
+1. `--profile` flag (source: `flag`)
+2. `VOYAGE_PROFILE` env-var (source: `env`)
+3. `premium` default (source: `default`)
+
+The profile dictates `phase_models.research`, `parallel_agents`, and
+`external_research_enabled`. `economy` and `balanced` profiles auto-disable
+the external research swarm regardless of `--external` flag (operator
+override deferred to v4.2).
+
+Examples:
+```
+/trekresearch --profile economy --project .claude/projects/2026-05-09-add-auth
+VOYAGE_PROFILE=balanced /trekresearch
+```
+
 ## Hard rules
 
 - **No planning:** This command produces research briefs, not implementation plans.
diff --git a/plugins/voyage/commands/trekreview.md b/plugins/voyage/commands/trekreview.md
index ffef44d..94da08c 100644
--- a/plugins/voyage/commands/trekreview.md
+++ b/plugins/voyage/commands/trekreview.md
@@ -309,6 +309,28 @@ Per **Handover 6**, BLOCKER and MAJOR findings are consumed by
 review's frontmatter `findings:` list and the trailing JSON block are
 the contract for that handover (see `docs/HANDOVER-CONTRACTS.md`).
 
+## Profile (v4.1)
+
+Accepts `--profile <name>` where `<name>` is `economy`, `balanced`, `premium`,
+or a custom profile under `voyage-profiles/`. Default: `premium`.
+
+Resolution order (per `lib/profiles/resolver.mjs`):
+1. `--profile` flag (source: `flag`)
+2. `VOYAGE_PROFILE` env-var (source: `env`)
+3. `premium` default (source: `default`)
+
+The selected profile drives `phase_models.review` — `economy` uses sonnet
+for the brief-conformance + code-correctness reviewers; `balanced` and
+`premium` use opus (review benefits from deeper reasoning).
+
+Examples:
+```
+/trekreview --profile balanced --project .claude/projects/2026-05-09-add-auth
+VOYAGE_PROFILE=premium /trekreview --project ...
+```
+
+Stats records emit `profile` and `profile_source`.
+
 ## Hard rules
 
 - **Brief is the contract.** Every finding in the review traces to a
diff --git a/plugins/voyage/tests/lib/profile-flag-coverage.test.mjs b/plugins/voyage/tests/lib/profile-flag-coverage.test.mjs
new file mode 100644
index 0000000..0fc64fb
--- /dev/null
+++ b/plugins/voyage/tests/lib/profile-flag-coverage.test.mjs
@@ -0,0 +1,41 @@
+// tests/lib/profile-flag-coverage.test.mjs
+// SC #4 (docs side): every command file must document --profile + VOYAGE_PROFILE.
+// /trekcontinue.md must additionally describe profile-arv (inheritance) policy.
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const COMMANDS_DIR = join(__dirname, '..', '..', 'commands');
+
+const COMMAND_FILES = [
+  'trekbrief.md',
+  'trekresearch.md',
+  'trekplan.md',
+  'trekexecute.md',
+  'trekreview.md',
+  'trekcontinue.md',
+];
+
+for (const filename of COMMAND_FILES) {
+  test(`${filename} documents --profile flag`, () => {
+    const content = readFileSync(join(COMMANDS_DIR, filename), 'utf-8');
+    assert.match(content, /--profile/,
+      `${filename} must contain --profile flag documentation`);
+  });
+
+  test(`${filename} mentions VOYAGE_PROFILE env-var`, () => {
+    const content = readFileSync(join(COMMANDS_DIR, filename), 'utf-8');
+    assert.match(content, /VOYAGE_PROFILE/,
+      `${filename} must mention VOYAGE_PROFILE env-var (resolution order)`);
+  });
+}
+
+test('trekcontinue.md documents inheritance policy (profile arves fra plan-frontmatter)', () => {
+  const content = readFileSync(join(COMMANDS_DIR, 'trekcontinue.md'), 'utf-8');
+  assert.match(content, /inheritance/,
+    'trekcontinue.md must describe profile-arv (inheritance) policy from plan-frontmatter');
+});