Kjell Tore Guttormsen
920fbd3c47
Wave 2, order 6. /trekexecute now: - refuses a plan whose logged approval does not cover its current sha256 (K2, approval-log verify --kind plan), before step 1; - runs the step check (K9) and the step's optional Regression: (K10, new lib/verification/regression-check.mjs through the criteria runner) at step end, before the checkpoint; exit 2 is "not measured", never green; - runs the architecture rules (K5) and the plan-file sweep (K6) after the last step; a violation or a file outside the plan turns completed into partial; - reviews by itself in the closing run (Phase 7.2): run the thing, /simplify, /trekreview, verdict-gate; a BLOCK adds the review's remediation steps after the plan validator accepts them and the operator re-approves the plan, capped at TREKEXECUTE_MAX_REVIEW_ROUNDS (3); - makes the main-merge gate a lock on the verdict: BLOCK or undecided keeps the merge closed; when open, the executor merges and the guard's question is the one question (operator decision 2026-10-08). The --gates pause before the wave merge-back is gone for the same reason. The guard refuses a merge into main and a push in the permission mode that shows no prompts, since no one can be asked (operator decision 2026-10-09; two mode-read exemptions approved by the operator). progress.json gains optional coupling fields (Handover 5); the validator rejects the runner's exitCode in plan_verification.failed_criteria (C15). Pointer lines name the skills test-first and debugging (S2). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
11 KiB
Voyage — Command flag reference
Per-command flag tables, imported from CLAUDE.md via pointer.
/trekbrief modes
| Flag | Behavior |
|---|---|
| (default) | Question round sized by class (small / bounded / architectural), brief-review gate, approval → brief.md with research plan |
--quick |
Proposes small as the class (still said aloud, overridable, raised when the task proves bigger) → 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 <name> |
(v4.1.0) Model profile: economy / balanced / premium / fable / <custom>. Sets phase_models for the brief phase. See ## Profile system in docs/operations.md. |
--approve <project-dir | brief-file> |
(veikart steg 1) No interview: show the existing brief's ## Intent + ## Goal verbatim, ask the operator to approve, and on "Approve" stamp intent_approved_hash + intent_approved_at, emit brief-approved, and write the trekbrief stats record ("mode": "approve"). The remedy /trekplan names when it halts on BRIEF_INTENT_NOT_APPROVED / BRIEF_INTENT_APPROVAL_STALE. |
Always interactive. Phase 3 puts the task in a size class (ceremony:, K1; heaviest in doubt, said aloud, overridable, only moved up) and asks one round of questions within the class budget (small 4, bounded 8, architectural 12 per round), recommendation first, facts looked up instead of asked, a visible Deferred list; it also asks where the brief is stored (artifact_store: git | local). Phase 4 runs a brief-reviewer stop-gate with 1 / 2 / 3 review iterations by class. Phase 4h takes only an explicit "Approve" («høres bra ut» and an empty answer are refused by lib/util/approval-log.mjs answer), stamps the brief, appends the approval to the target repo's log (approval-log.mjs append, K2) and commits it (lib/util/artifact-commit.mjs: the log always, the brief when git). After that, asks the user to choose manual (print commands) or auto (Claude runs research + plan in foreground).
/trekresearch modes
| Flag | Behavior |
|---|---|
| (default) | Interview + research (local + external) + synthesis + brief (foreground) |
--project <dir> |
Write brief to {dir}/research/{NN}-{slug}.md (auto-incremented) |
--quick |
Interview (short) + inline research (no agent swarm) |
--local |
Only codebase analysis agents (skip external research) |
--external |
Only external research agents (skip codebase analysis) |
--fg |
No-op alias (foreground is default since v2.4.0) |
--gates {true|false} |
(v3.4.0) Boolean autonomy-gate flag; present → gating on. Policy (gates_mode) detailed under ## Autonomy mode in docs/operations.md. |
--min-brief-version <ver> |
(S18) Warn — never block — if an attached --project brief declares a version below <ver> (e.g. 2.2), i.e. sidesteps framing enforcement |
--profile <name> |
(v4.1.0) Model profile for the research phase. |
--engine {swarm|deep-research} |
(deep-research-engine) Opt-in external-research engine; deep-research delegates the external phase to Claude Code's built-in /deep-research workflow, which only works on 2.1.154 <= CC < 2.1.218 — from 2.1.218 /deep-research is operator-invoked only (the Skill tool refuses with disable-model-invocation), so the engine always falls back to swarm. Never hard-fails. Default swarm. |
Flags combine: --project <dir> --local, --external --quick.
Bounded conversation loop (Phase 4.5 + Phase 5) — env-vars
Dimension discovery and the multi-turn follow-up loop are default-off and
have no flag; they are environment-gated, because turning them on costs turns.
They run only at effort: high (resolved from the brief's phase_signals).
| Env-var | Default | Behavior |
|---|---|---|
VOYAGE_STORM_ENABLED |
(unset — default-off) | =1 grants the Phase 5 loop a non-zero turn budget and is the second condition on Phase 4.5's skip-guard. Unset, research-loop-cap.mjs grants 0 turns and both phases are inert: doing nothing keeps the whole mechanism off. |
TREKRESEARCH_MAX_CONV_TURNS |
3 |
Max turns per under-illuminated dimension. Budget = this × maxDimensions (8, settings.json:16). Empty, non-numeric, zero, negative, Infinity, or any fraction that floors below 1 (0.5, 0.9) fall back to 3 — never to unbounded, and never to 0. A fraction at or above 1 floors (2.7 → 2). |
VOYAGE_DISABLE_CAP_HOOK |
(unset) | =1 disables hooks/scripts/pre-agent-cap.mjs, the PreToolUse enforcement of the turn budget. The cap primitive still applies; only the second gate is switched off. |
Adoption of the loop as a default is gated on a pre-registered measurement —
protocol, thresholds, and the exact commands in
docs/storm-measurement.md.
/trekplan modes
| Flag | Behavior |
|---|---|
--project <dir> |
Required path A — read {dir}/brief.md, auto-discover {dir}/research/*.md, write {dir}/plan.md |
--brief <path> |
Required path B — plan from a specific brief file; write to .claude/plans/trekplan-{date}-{slug}.md |
--research <brief> [brief2] |
Enrich with extra research briefs beyond what is in {project_dir}/research/ |
--fg |
No-op alias (foreground is default since v2.4.0) |
--quick |
Plan directly (no agent swarm) |
--min-brief-version <ver> |
(S18) Warn — never block — if the brief declares a version below <ver> (e.g. 2.2), i.e. sidesteps framing enforcement |
--export headless <plan> |
Legacy alias for --decompose — the only remaining export format (the pr / issue / markdown variants were removed; Claude reformats a plan ad-hoc on request) |
--decompose <plan> |
Split plan into self-contained session specs + orders.md (one starter line per session) |
--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 <name> |
(v4.1.0) Model profile for the plan phase (and others, since plan emits profile: to plan.md frontmatter). |
Breaking change (v2.0): one of --brief or --project is required. There is no interview inside /trekplan. The --spec flag has been removed — use /trekbrief to produce a brief instead.
Approval gates (no flag turns them off). Phase 1 halts unless the brief's intent marker is current (intent-approval.mjs --check) AND the target repo's approval log is intact and holds that intent (approval-log.mjs verify --kind intent; broken, diverged, not-logged or mismatch halt; remedy /trekbrief --approve). Phase 1 also reads ceremony (absent = architectural) and artifact_store (absent = local). Phase 11 asks for an explicit plan approval before any handoff, logs it bound to plan.md's sha256 and commits it (the plan itself only when artifact_store: git); "execute" does not start on "Not yet".
If {project_dir}/architecture/overview.md exists (typically produced by an opt-in upstream architect plugin, not bundled), the plan command auto-discovers it and treats cc_features_proposed as priors. Missing file is fine — discovery is additive, not required.
/trekexecute modes
| Flag | Behavior |
|---|---|
| (default) | Execute plan — auto-detects Execution Strategy for multi-session |
--project <dir> |
Read {dir}/plan.md, write {dir}/progress.json |
--resume |
Resume from last progress checkpoint |
--dry-run |
Validate plan structure without executing |
--validate |
Schema-only check — parse steps + manifests, report READY | FAIL, no execution |
--step N |
Execute only step N |
--fg |
Force foreground — run all steps sequentially, ignore Execution Strategy |
--session N |
Execute only session N from plan's Execution Strategy |
--gates {true|false} |
(v3.4.0) Boolean autonomy-gate flag; present → gating on. Policy (gates_mode) detailed under ## Autonomy mode in docs/operations.md. 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. |
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.
/trekreview modes
| Flag | Behavior |
|---|---|
| (default) | Claude Code /code-review + /security-review (engine, via the Skill tool, never --fix), then brief-conformance + code-correctness reviewers in parallel, coordinator dedup + verdict, write {project_dir}/review.md with the required verdict:, decide with lib/review/verdict-gate.mjs (0 ALLOW/WARN · 1 BLOCK · 2 never green), propose recurring finding classes as project memory (operator approves each line) |
--project <dir> |
Required. Path to trekplan project folder containing brief.md. Review is written to {dir}/review.md |
--since <ref> |
Override "before" SHA for the diff range. Validated via git rev-parse --verify |
--quick |
/code-review + code-correctness reviewer only; skip brief-conformance reviewer, /security-review and the coordinator's reasonableness filter — fast correctness-only pass |
--validate |
Schema-only check on existing {dir}/review.md plus the verdict gate. No LLM calls. A 1.0 review without verdict: fails here (it still seeds a plan in soft mode) |
--dry-run |
Print discovered scope + triage map; skip writes |
--fg |
No-op alias (foreground is default) |
--workflow |
(opt-in, NW2) Run Phase 5–6 on the bake-off-validated Workflow substrate (scripts/trekreview-armB.workflow.mjs) instead of the default prose path. Default stays prose; requires Claude Code 2.1.154+ (raises the consumer floor — opt-in for portability). Fidelity-equivalent per docs/T2-bakeoff-results.md |
--profile <name> |
(v4.1.0) Model profile for the review phase. |
/trekcontinue modes
| Flag | Behavior |
|---|---|
| (default) | Auto-discover active project's .session-state.local.json and resume |
<project-dir> |
Resume the next session of an explicit project directory |
--profile <name> |
(v4.1.0) Model profile for the resumed session. Inherited from the previous session's plan.md frontmatter when absent. |
The triage gate is deterministic — path-pattern classifier produces {file → deep-review|summary-only|skip}. Hard refuse-with-suggestion above 100 files / 100K diff tokens.