fix(gate): part 2 verifier findings — non-object findings, carried backed copy, rule_keys, marks, approval prose, brief_path, engine put-back once

1. plan-review-dedup skips only a null or undefined finding; any other
   entry that is not an object (a string, a number, an array) goes on as
   before E, a finding with no valid severity that the plan gate counts as
   a blocker (it was dropped, so a string blocker recorded PASS).
2. plan-gate --record: a previous finding that rule A carried as counted and
   whose id is backed this round leaves the counted set, the counts, the
   verdict and the stop rule's summary (it was counted and listed in
   known_outside at once: BLOCK, not-fewer, and --accept-open refused).
3. A known_outside entry keeps rule_keys; extractVerdict accepts it (a list
   of strings), and the bare gate re-checks with the same keys the recorder
   used, so a merged finding whose security key is only in rule_keys is a
   WARN, not a STOP.
4. plan-critic, scope-guardian and /trekplan Phase 9's round-2 sentences say
   the Critic Verdict also lists known_outside and each is marked by id in
   previous. Code already accepts such a mark (dedup passes it; countRound
   ignores ids it does not carry; --record removes the entry on true);
   pinned in diff mode and full count.
5. The approval prose names ## Threat Model where it named only ## Intent +
   ## Goal: skills/annotating/SKILL.md (description, step 4, guard list),
   docs/command-modes.md, Handover 1's intent_approved_hash row, README
   (approval, Approve row, intent approval gate) and CLAUDE.md's /trekbrief
   row.
6. threat-model.mjs gains usableInRepo (a brief path relative to the repo
   top level) and repoRelativeBrief; --record stores brief_path relative to
   the top level, never absolute, and both gates read it from there, so the
   gate run from a subdirectory reads the same brief. reviewThreatModel
   uses usableInRepo. Handover 4 and the gate header say so.
7. review-finalize's outside pass puts an entry back only when no finding
   carries its row yet (engine-compare rowOf): an engine finding listed in
   known_outside while its payload is saved went back twice.
8. A test runs scripts/release-check.mjs on a review whose known_outside
   entry the brief does not back: exit 2 (control: backed passes the review
   check).

Existing tests changed: plan-gate-threat-model's entry-keys assertion now
expects rule_keys (item 3), and its planted non-security entry drops the
security key from rule_keys too, since the gate reads rule_keys (item 3).

Part 2 fix round of the E plan.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-11-08 10:50:20 +01:00

8.5 KiB

Raw Blame History

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\|closed\|open]`	(v3.4.0) Autonomy flag: bare, `true` or `closed` = on; `false` or `open` = off; any other next token is not its value. See `## Autonomy mode` in `docs/operations.md`.
`--approve <project-dir \| brief-file>`	(veikart steg 1) No interview: show the existing brief's `## Intent` + `## Goal` (+ `## Threat Model` when present) verbatim, ask the operator to approve, and on "Approve" stamp `intent_approved_hash` + `intent_approved_at`. 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\|closed\|open]`	(v3.4.0) Autonomy flag: bare, `true` or `closed` = on; `false` or `open` = off; any other next token is not its value. See `## 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

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 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\|closed\|open]`	(v3.4.0) Autonomy flag: bare, `true` or `closed` = on; `false` or `open` = off; any other next token is not its value. See `## Autonomy mode` in `docs/operations.md`.

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\|closed\|open]`	(v3.4.0) Autonomy flag: bare, `true` or `closed` = on; `false` or `open` = off; any other next token is not its value. See `## Autonomy mode` in `docs/operations.md`. `/trekexecute` accepts the flag and pauses on nothing; it adds no question of its own before a merge: the guard asks there (operator decision 2026-10-08).

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. MAX_REVIEW_ROUNDS in lib/review/review-rounds.mjs (3) caps the reviews per run; /trekreview refuses a fourth round.

/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, or WARN with every counting MAJOR answered · 1 BLOCK · 2 never green), the operator answers each counting MAJOR (Phase 8.8), 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 except the brief-conflict rule — fast correctness-only pass
`--answers`	Only the operator's answers to the counting MAJORs (Phase 8.8) on the existing `{dir}/review.md`, then the verdict gate. No reviewer and no write of findings: it opens no new round and counts nothing against the cap
`--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)

/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

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.

8.5 KiB Raw Blame History