Kjell Tore Guttormsen
fe97f6172c
operations.md:15 + command-modes.md described an autonomy surface that does
not exist in code. Truth-pass against lib/util/autonomy-gate.mjs (the source
of truth) closes three false claims found while auditing the autonomy surface
in S21 (devils-advocate-results.md S21b forward-pointer):
F1 (MAJOR) — fabricated state machine. operations.md claimed
`idle → approved → executing → merge-pending → main-merged`; only `idle`
exists. Real states: idle → gates_on|auto_running → paused_for_gate →
completed (events: start/phase_boundary/resume/finish).
F2 (MINOR) — event-emit.mjs does NOT "record each transition"; it emits 3
named lifecycle events (brief-approved, main-merge-gate, user_input) and
is decoupled from the pure, no-I/O autonomy-gate.
F3 — `--gates {open|closed|adaptive}` is false: the CLI shim + all 4 command
docs take a BOOLEAN `--gates {true|false}`. open/closed/adaptive is a
DERIVED gates_mode policy, /trekexecute-only, mapped from the brief effort
signal (low→open, standard→adaptive, high→closed; trekexecute.md:1562/74/75).
Operator-chosen fix (S24): boolean-true representation + a gates_mode policy
note, applied to BOTH operations.md and command-modes.md (4 rows) — same
false-claim class, fixed in one pass (fix-errors-found-in-scope).
TDD: doc-pin in doc-consistency.test.mjs imports STATES from autonomy-gate.mjs,
forbids the fabricated names + the flag-enum, requires the real states. Red
first (failed on "merge-pending"), green after the truth-pass.
Tests: 725 (723 pass / 2 skip / 0 fail). plugin validate passes (1 accepted
CLAUDE.md-at-root warning).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqBYc8Ltrk7LipyJmGxXiB
88 lines
6.2 KiB
Markdown
88 lines
6.2 KiB
Markdown
# 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` / `<custom>`. Sets `phase_models` for the brief phase. See `## Profile system` in `docs/operations.md`. |
|
||
|
||
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 + Gemini) |
|
||
| `--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. |
|
||
|
||
Flags combine: `--project <dir> --local`, `--external --quick`.
|
||
|
||
## /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 <pr\|issue\|markdown\|headless> <plan>` | Generate shareable output from existing plan |
|
||
| `--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.
|