Kjell Tore Guttormsen
f5dc08f660
Veikart steg 1, økt 1 av 2. The three holes measured in the grounds: (1) ## Intent / ## Goal were only checked for existence, (2) no approval marker existed, (3) brief-approved was emitted only on the auto path. - lib/validators/intent-approval.mjs: --check / --stamp. The marker is intent_approved_hash (sha256 over normalized ## Intent + ## Goal) + intent_approved_at. Editing either section after approval → STALE. - /trekplan Phase 1 (Read the brief, both --brief and --project): runs --check and HALTS on BRIEF_INTENT_NOT_APPROVED / _STALE / _INVALID with the remedy spelled out; an unrunnable check halts too. - /trekbrief Phase 4h (before the Phase 5 fork, asked even in --quick): shows Intent + Goal verbatim, AskUserQuestion Approve / Revise / Leave; only "Approve" runs --stamp. --stamp emits brief-approved, so the manual (default) path records it; the auto path's own emission is removed. New mode /trekbrief --approve <project-dir> = Phase 4h alone. - README, CLAUDE.md, command-modes, HANDOVER-CONTRACTS §Handover 1, jsonl-schemas (trekbrief-stats gains intent_approved). Valgt ingen brief_version-bump fordi skjemaendringen er rent additiv (to valgfrie felt) og kravet sitter i /trekplan — enhver produsents brief kan godkjennes via /trekbrief --approve uten produsentendring. Valgt eget --check-kall i stedet for et flagg på brief-validator fordi --brief-stien i dag ikke kjører validatoren i det hele tatt; et nytt validatorkall der ville også stoppe på andre feil. Valgt fallback-datamappe = målestokkens (plugins/data/voyage-…) fordi CLAUDE_PLUGIN_DATA er tom i Bash-miljøet og event-emits egen fallback er stille skip — slik ble brief-approved 0 records. What the marker does NOT prove (module header, command prose, contract): same user, same machine — any session can stamp. A trace, not a signature. Suite 1183 → 1201 (1199/0/2). Mutants M1–M5 (stale check off, check always valid, gate line removed, stamp emits nothing, no normalization) each fell ≥ 1 test. yardstick unchanged: RED, 1 of 3 countable. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
8.5 KiB
8.5 KiB
Voyage — Command flag reference
Per-command flag tables, imported from CLAUDE.md via pointer.
/trekbrief modes
| Flag | Behavior |
|---|---|
| (default) | Dynamic interview until quality gates pass → brief.md with research plan |
--quick |
Compact start; still escalates if required sections are weak or the brief-review gate fails → 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> |
(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 and emit brief-approved. The remedy /trekplan names when it halts on BRIEF_INTENT_NOT_APPROVED / BRIEF_INTENT_APPROVAL_STALE. |
Always interactive. Phase 3 is a section-driven completeness loop (no hard cap on question count); Phase 4 runs a brief-reviewer stop-gate with max 3 review iterations. After writing the brief, 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 headless sessions |
--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.
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. |
--profile <name> |
(v4.1.0) Model profile for the execute phase. Inherited from plan.md frontmatter profile: if present. |
/trekreview modes
| Flag | Behavior |
|---|---|
| (default) | Run brief-conformance + code-correctness reviewers in parallel, coordinator dedup + verdict, write {project_dir}/review.md |
--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 |
Skip brief-conformance reviewer; skip coordinator's reasonableness filter — fast correctness-only pass |
--validate |
Schema-only check on existing {dir}/review.md. No LLM calls |
--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.