Kjell Tore Guttormsen fe97f6172c docs(voyage): S24 — autonomy-gate truth-pass + guard pin (S21b doc/code drift)

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

2026-06-19 21:36:15 +02:00

6.2 KiB

Raw Blame History

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.

6.2 KiB Raw Blame History Unescape Escape