devrites 5.10.0 → 5.10.2

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [5.10.2](https://github.com/ViktorsBaikers/DevRites/compare/v5.10.1...v5.10.2) (2026-09-15)
+
+### Fixed
+
+* **ci:** stop gosec false positive on secret-scan help ([ac8ef15](https://github.com/ViktorsBaikers/DevRites/commit/ac8ef1530f5121cf192fb9e60acef781b0e3fbb8))
+* **rite:** honor --parallel over leftover AFK cap ([#78](https://github.com/ViktorsBaikers/DevRites/issues/78)) ([db6c299](https://github.com/ViktorsBaikers/DevRites/commit/db6c299e24be5e1b8c5739e45542f2ef8b572e3b))
+
+## [5.10.1](https://github.com/ViktorsBaikers/DevRites/compare/v5.10.0...v5.10.1) (2026-09-15)
+
+### Fixed
+
+* **rite:** auto-resolve recommended blocking questions in autocomplete ([#77](https://github.com/ViktorsBaikers/DevRites/issues/77)) ([cd11a59](https://github.com/ViktorsBaikers/DevRites/commit/cd11a59c01b9b1cd48df5a19a7b8ad3c4f1fb2d4))
+
 ## [5.10.0](https://github.com/ViktorsBaikers/DevRites/compare/v5.9.0...v5.10.0) (2026-09-15)
 
 ### Added

package/README.md

@@ -33,7 +33,7 @@ project-conventional push, tag, or PR action, and archive the workspace.
 Unattended runs may create local WIP checkpoint commits along the way, but they
 remain local unless Ship's disclosed plan includes an approved remote action.
 
-**Status:** [`v5.10.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v5.10.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v5.10.2`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v5.10.2): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 This is the latest published release; `main` may contain unreleased work.
 
@@ -252,7 +252,10 @@ ignored and never rewritten. Delete `.devrites/AFK` to
 return to HITL.
 
 AFK still pauses for product, scope, or policy choices, irreversible risk,
-and access or actions available only to a human. Agents use bounded recovery
+and access or actions available only to a human. `/rite-autocomplete` is the
+exception that auto-resolves blocking questions already naming a ranked
+recommended option; escalating, irreversible-risk, access, and blocking with
+no recommended option still pause. Agents use bounded recovery
 for red tests, type or lint errors, runtime failures, and missing technical
 coverage. If that recovery budget runs out, they record a technical blocker
 instead of asking a question. The full pause and gate contract is in

package/docs/architecture.md

@@ -39,7 +39,9 @@ cursor readers, traceability rules, and phase-relative completeness model, see
    through Seal GO and stops. Explicit `--ship` enters Ship preflight but still
    waits for a fresh literal `GO` and native approval before mutation. It
    chooses the recommended option at each soft gate and pauses for hard
-   irreversible-risk, blocking, or escalating gates, or a NO-GO. The
+   irreversible-risk, escalating, unanswered blocking with no recommended
+   option, or a remaining NO-GO. Open blocking questions that already name a
+   ranked recommended option auto-resolve; they are not a user handoff. The
    `devrites-` prefix prevents collisions with bundled Claude Code skill names
    such as `prototype`, `handoff`, `triage`, and `diagnose`; it does not mark
    visibility. `rite-pressure-test` needs no prefix because it does not collide.
@@ -336,9 +338,11 @@ workflow. It carries state through workspace files rather than chat. A vague
 prompt starts `devrites-interview`; `/rite-spec` and `/rite-clarify` then
 finish the only interactive window. After decision coverage is CLEAR it runs unattended,
 choosing the recommended option at each soft gate and recording the rationale
-in `decisions.md`. It does **not** weaken blocking/escalating or irreversible-risk
-gates: human-only access/actions, those gates, a NO-GO, or low confidence still
-pause. Temper expand, validating gates, and default slice/agent/time/review-queue
+in `decisions.md`. It does **not** weaken escalating or irreversible-risk
+gates: human-only access/actions, those gates, unanswered blocking with no
+recommended option, a remaining NO-GO, or low confidence still pause. Open
+blocking questions that already name a ranked recommended option auto-resolve
+through `devrites-engine state resolve`. Temper expand, validating gates, and default slice/agent/time/review-queue
 caps do not. `--max-slices` is ignored the same way. Agents use bounded recovery for red tests, runtime failures, and
 missing technical coverage. By default the workflow stops at Seal GO with `/rite-ship` as the next step.
 The `--ship` flag (alias `--yolo`) continues through Ship preflight, discloses

package/docs/cli.md

@@ -8,7 +8,10 @@ cross-host primitives; it never dispatches an agent or grades reviewer prose.
 ## Command surface
 
 `devrites-engine help` lists the exhaustive operational surface. Standard
-`help`, `-h`, `--help`, `version`, and `--version` forms also remain supported:
+`help`, `-h`, `--help`, `version`, and `--version` forms also remain supported.
+Each operational command and subcommand accepts `-h` / `--help` and prints that
+command's usage to stdout (exit 0) without requiring a workspace. Missing
+required arguments still print usage to stderr and exit 2.
 
 ```text
 devrites-engine install [flags]

package/docs/command-map.md

@@ -49,7 +49,8 @@ The Go surface is intentionally closed and deterministic:
 
 `devrites-engine help` exhaustively lists the operational engine commands.
 Standard `help`, `-h`, `--help`, `version`, and `--version` forms remain
-available; there are no legacy operational aliases. `check candidate <slug>`
+available; each operational command and subcommand also accepts `-h` / `--help`.
+There are no legacy operational aliases. `check candidate <slug>`
 prints exactly
 `candidate-sha256: <64 lowercase hex>` and `candidate-files: <row count>` on a
 pass; usage/root errors exit `2` and candidate blocks exit `3`. There are no
@@ -99,7 +100,7 @@ See [`cli.md`](cli.md).
 | [`/rite-review`](../pack/.claude/skills/rite-review/SKILL.md) | review | `[scope: slice N \| feature] [--full]` | Feature-scoped parallel Spec + Standards review of the closed candidate; binds `review.md` to its digest. | workspace + candidate | `review.md`, `evidence.md`, `state.md` |
 | [`/rite-seal`](../pack/.claude/skills/rite-seal/SKILL.md) | seal | `[feature-slug] [--full]` | Candidate-bound GO / NO-GO **decision**. Rechecks exact proof/review bindings and runs no git; on GO sets `Next step: /rite-ship`. | all artifacts + candidate | `seal.md`, `state.md` |
 | [`/rite-ship`](../pack/.claude/skills/rite-ship/SKILL.md) | ship | `[slug]` | Starts with a read-only Seal/candidate check and exact plan disclosure, then requires fresh literal `GO`. Only then may it collapse checkpoints, stage exact candidate paths, validate staged scope/bytes/bindings/secrets, commit and reverify, perform optional separately approved push/tag/PR actions, and archive/close. | `seal.md` + candidate + Git index | `ship.md`, `state.md`, archive |
-| [`/rite-autocomplete`](../pack/.claude/skills/rite-autocomplete/SKILL.md) | (orchestrator) | `[idea] [--ship\|--yolo] [--max-slices N] [--full] [--cross-model]` | Full lifecycle (spec → clarify → … → seal → ship). Spec + clarify form the one interactive window; AFK/checkpoint mode arms only after decision coverage is CLEAR. Pauses for irreversible risk, blocking/escalating, human-only access, or NO-GO — not temper expand, validating gates, `--max-slices`, or default resource caps. Objective red checks use bounded technical recovery. Default stops at Seal GO; `--ship` (`--yolo`) reaches Ship preflight but still requires fresh literal `GO` and native approval; `--full` selects the Full profile and `--cross-model` arms Vet's second opinion. | idea + workspace | whole workspace (drives every phase) |
+| [`/rite-autocomplete`](../pack/.claude/skills/rite-autocomplete/SKILL.md) | (orchestrator) | `[idea] [--ship\|--yolo] [--max-slices N] [--full] [--cross-model]` | Full lifecycle (spec → clarify → … → seal → ship). Spec + clarify form the one interactive window; AFK/checkpoint mode arms only after decision coverage is CLEAR. Pauses for irreversible risk, escalating, unanswered blocking with no recommended option, human-only access, or remaining NO-GO — not recommended-option blocking questions, temper expand, validating gates, `--max-slices`, or default resource caps. Objective red checks use bounded technical recovery. Default stops at Seal GO; `--ship` (`--yolo`) reaches Ship preflight but still requires fresh literal `GO` and native approval; `--full` selects the Full profile and `--cross-model` arms Vet's second opinion. | idea + workspace | whole workspace (drives every phase) |
 | [`/rite-quick`](../pack/.claude/skills/rite-quick/SKILL.md) | (express) | `<change>` | Express lane for a **small, reversible, unambiguous** change: one-line contract → TDD build → scoped prove → review-lite → ship, no full artifact tree. **Significance gate first**: auth / migration / public-API / destructive / multi-slice / ambiguous → escalates to `/rite-spec`. Triggers: "quick fix", "small change", "tiny tweak", "just do X". | the change + codebase | code + commit (optional `brief.md` / `evidence.md`) |
 | [`/rite-frame`](../pack/.claude/skills/rite-frame/SKILL.md) | lens | `[ask \| diff]` | Pre-flight + self-audit lens for ad-hoc work the lifecycle gates never see: **FRAME** turns an imperative ask into a falsifiable success criterion + verify command before code; **AUDIT** checks a raw diff against the four LLM coding failure modes (silent assumption / overcomplication / out-of-scope edit / unverifiable goal). Top of `/rite-quick` or before a plain "just do X". | the ask / a raw diff | success criterion + verify command (inline) |
 | [`/rite-adopt`](../pack/.claude/skills/rite-adopt/SKILL.md) | onboard | `[path or area to adopt] [+ what you want to build next]` | Reverse-derive the existing baseline and next objective; propose any durable project guidance in the nearest native instruction file. | codebase + project instructions | workspace spec/state artifacts + optional guidance proposal |

package/docs/engine/commands.md

@@ -27,11 +27,13 @@ workflow strategy.
 | `open-visual <path-or-name> [--slug <slug>] [--no-open]` | Resolve a local visual HTML file, optionally open it in the OS browser, warn if the sibling outline is missing or inventory ids are absent from HTML, and print agent path tips. No network. |
 | `version` | Print the engine version. |
 
-`help`, `-h`, and `--help` print this operational inventory. `version` and
-`--version` print the binary version. Other unlisted command forms are rejected
-as unknown; the engine has no compatibility aliases or tombstones. The
-`add`/`upgrade`/`remove` conveniences belong only to the `npx devrites` adapter,
-not to the engine command namespace.
+`help`, `-h`, and `--help` print this operational inventory. Each operational
+command and subcommand also accepts `-h` / `--help` and prints that command's
+usage to stdout without requiring a workspace. `version` and `--version` print
+the binary version. Other unlisted command forms are rejected as unknown; the
+engine has no compatibility aliases or tombstones. The `add`/`upgrade`/`remove`
+conveniences belong only to the `npx devrites` adapter, not to the engine
+command namespace.
 
 ## Check boundary
 

package/docs/orchestration.md

@@ -128,8 +128,11 @@ preserved. No ad hoc copy/cherry-pick/merge occurs from the read-only root.
 
 Isolation does not authorize same-worktree throughput. Parallel writers are allowed
 **only** under the `/rite-build` batch path when path-disjoint eligibility, abort-batch,
-and a control `parallel-lease.md` apply. `--parallel N` (or the AFK sentinel
-`max_parallel`, default cap 10 under `/rite-autocomplete`) is a **cap**: each round runs
+and a control `parallel-lease.md` apply. `--parallel N` on `/rite-autocomplete`
+or `/rite-build` is the batch cap for that run and wins over leftover sentinel
+`max_parallel`; `/rite-autocomplete --parallel N` also writes or replaces only
+that field. Absent the flag, the sentinel (default cap 10 under
+`/rite-autocomplete`) is a **cap**: each round runs
 the largest eligible set, recomputes after every completed round, and repeats until no
 pending slice remains; a one-slice round is serial for that round only (see
 [`parallel-batch.md`](../pack/.claude/skills/rite-build/reference/parallel-batch.md)).

package/docs/skills.md

@@ -222,7 +222,7 @@ and `Shipped`. Utility commands keep the same compact labels and one-next-action
 
 | Skill | What It Does | Use When |
 |---|---|---|
-| [`rite-autocomplete`](../pack/.claude/skills/rite-autocomplete/SKILL.md) | Runs the lifecycle unattended (spec → clarify → … → seal → ship), choosing the recommended option at each soft gate and recording the rationale in `decisions.md`.<br>A vague prompt gets one up-front spec/clarify window; after CLEAR it does not iterate per phase.<br>It pauses only for irreversible risk, blocking/escalating gates, human-only access, or NO-GO — not temper expand, validating gates, or default slice/agent/time/review-queue caps.<br>Objective red checks use bounded technical recovery, including cold-resume from retained one-shot evidence and one-time migration of stale missing-writer stops when an upgraded contract supplies the first supported writer. That migration applies once; the first real materializer failure is attempt one under normal bounded recovery. Internal `NEEDS_REPLAN` and new agent-owned review findings stay caller-owned backward edges, not user-facing stops. Spending an action authorization blocks another real execution, not offline repair.<br>Default stops at Seal GO. `--ship` (alias `--yolo`) reaches Ship preflight but still requires a fresh literal `GO` and native approval. | "Autocomplete", "do the whole thing", "run the full cycle", "one-shot this feature". |
+| [`rite-autocomplete`](../pack/.claude/skills/rite-autocomplete/SKILL.md) | Runs the lifecycle unattended (spec → clarify → … → seal → ship), choosing the recommended option at each soft gate and recording the rationale in `decisions.md`.<br>A vague prompt gets one up-front spec/clarify window; after CLEAR it does not iterate per phase.<br>It pauses only for irreversible risk, escalating gates, unanswered blocking with no recommended option, human-only access, or remaining NO-GO — not recommended-option blocking questions, temper expand, validating gates, or default slice/agent/time/review-queue caps.<br>Objective red checks use bounded technical recovery, including cold-resume from retained one-shot evidence and one-time migration of stale missing-writer stops when an upgraded contract supplies the first supported writer. That migration applies once; the first real materializer failure is attempt one under normal bounded recovery. Internal `NEEDS_REPLAN` and new agent-owned review findings stay caller-owned backward edges, not user-facing stops. Spending an action authorization blocks another real execution, not offline repair.<br>Default stops at Seal GO. `--ship` (alias `--yolo`) reaches Ship preflight but still requires a fresh literal `GO` and native approval. | "Autocomplete", "do the whole thing", "run the full cycle", "one-shot this feature". |
 | [`rite-zoom-out`](../pack/.claude/skills/rite-zoom-out/SKILL.md) | Map the modules, callers, callees, and decisions in an unfamiliar area using the project's domain glossary. | Explicit-only: `/rite-zoom-out` / `/rite zoom-out`. |
 | [`rite-prototype`](../pack/.claude/skills/rite-prototype/SKILL.md) | Throwaway code answering ONE design question: logic harness OR 2 to 4 UI variations on one route. | Explicit-only: `/rite-prototype` / `/rite prototype`. |
 | [`rite-handoff`](../pack/.claude/skills/rite-handoff/SKILL.md) | Compact chat session → handoff doc. References existing `.devrites/work/<slug>/` artifacts by path. | Explicit-only: `/rite-handoff` / `/rite handoff`. |

package/docs/usage.md

@@ -384,8 +384,8 @@ You: GO                        # → commit, optional approved push/tag/PR, then
 
 Add `--ship` (alias `--yolo`) to continue through `/rite-ship` preflight.
 Autocomplete discloses the exact Git plan, then still stops for a fresh literal
-`GO` and native host approval. It also pauses for irreversible risk, human-only access/actions, blocking or
-escalating gates, a NO-GO, or low confidence — not for temper expand, validating
+`GO` and native host approval. It also pauses for irreversible risk, human-only access/actions, escalating
+gates, unanswered blocking with no recommended option, a remaining NO-GO, or low confidence — not for recommended-option blocking questions, temper expand, validating
 gates, `--max-slices`, or default slice/agent/time/review-queue caps.
 Objective red checks use bounded recovery instead. Args:
 `[idea] [--ship|--yolo] [--max-slices N] [--full] [--cross-model]`.
@@ -413,7 +413,9 @@ remaining from the pending-slice count and ignores leftover remaining and
 - **`.devrites/AFK` is per-developer, not per-repo**: gitignore it (or commit
   it deliberately if the team agrees on AFK defaults). The sentinel is
   read-only config: it toggles your local session mode and sets the initial
-  `max_slices` budget; nothing else. The mutable remaining-slice count lives
+  `max_slices` budget. `/rite-autocomplete --parallel N` is the one exception:
+  it writes or replaces only `max_parallel: N` so a leftover `1` cannot keep
+  later ticks serial. The mutable remaining-slice count lives
   in `state.md` (`AFK slices remaining`), never in the sentinel. The root
   charges it once with each green pending → built transition and stops before
   another dispatch at zero; malformed values fail closed.

package/engine/commands.go

@@ -25,6 +25,9 @@ const (
 // workspace or Git state, which must never fall back after an unsafe root
 // selection.
 func rootModeFor(command string, args []string) rootMode {
+	if hasHelpFlag(args) || (len(args) > 0 && isHelpToken(args[0])) {
+		return rootUnused
+	}
 	subcommand := firstRootOperand(args)
 	switch command {
 	case "secret-scan", "open-visual":

package/engine/help.go

@@ -0,0 +1,190 @@
+package main
+
+import (
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/devrites/devrites/internal/parallel"
+)
+
+const (
+	checkUsage = `usage: devrites-engine check <candidate|readiness|seal|path-disjoint|task-graph|skill-trust|indexes> ...
+
+  check candidate <slug>
+  check readiness <slug>
+  check readiness --emit-binding <slug>
+  check seal <slug>
+  check path-disjoint [--root <dir>] [<json-file>|-]
+  check task-graph <slug>
+  check skill-trust <path>
+  check indexes [--root <dir>]
+`
+
+	stateUsage = `usage: devrites-engine state <resolve|merge-manifest|close> ...
+
+  state resolve <qid> "<answer>"
+  state resolve --drop <qid> ["<reason>"]
+  state resolve --batch <file>
+  state merge-manifest <slug> [<predecessor>...]
+  state close <slug>
+`
+
+	observeUsage = `usage: devrites-engine observe summary <slug> | observe slice <slug> <SLICE-ID>
+
+  observe summary [slug]
+  observe slice <slug> <SLICE-ID>
+`
+
+	orientUsage  = "usage: devrites-engine orient [slug]"
+	migrateUsage = "usage: devrites-engine migrate <slug> [--dry-run] [--answer id=choice]"
+	// scanCmdUsage is help text for `secret-scan`. The identifier must not
+	// contain "secret": gosec G101 treats secret* string consts as credentials.
+	scanCmdUsage        = "usage: devrites-engine secret-scan [--staged] [--stdin] [slug]"
+	openVisualUsage     = "usage: devrites-engine open-visual <path-or-name> [--slug <slug>] [--no-open]"
+	versionUsage        = "usage: devrites-engine version"
+	candidateUsage      = "usage: devrites-engine check candidate <slug>"
+	readinessUsage      = "usage: devrites-engine check readiness <slug>\n       devrites-engine check readiness --emit-binding <slug>"
+	sealUsage           = "usage: devrites-engine check seal <slug>"
+	taskGraphUsage      = "usage: devrites-engine check task-graph <slug>"
+	skillTrustUsage     = "usage: devrites-engine check skill-trust <path>"
+	indexesUsage        = "usage: devrites-engine check indexes [--root <dir>]"
+	resolveUsage        = `usage: devrites-engine state resolve <qid> "<answer>"  |  state resolve --drop <qid> ["<reason>"]  |  state resolve --batch <file>`
+	mergeManifestUsage  = "usage: devrites-engine state merge-manifest <slug> [<predecessor>...]"
+	closeUsage          = "usage: devrites-engine state close <slug>"
+	observeSliceUsage   = "usage: devrites-engine observe slice <slug> <SLICE-ID>"
+	observeSummaryUsage = "usage: devrites-engine observe summary [slug]"
+)
+
+func isHelpFlag(arg string) bool {
+	switch arg {
+	case "-h", "-help", "--help":
+		return true
+	default:
+		return false
+	}
+}
+
+func isHelpToken(arg string) bool {
+	return isHelpFlag(arg) || arg == "help"
+}
+
+func hasHelpFlag(args []string) bool {
+	for _, arg := range args {
+		if isHelpFlag(arg) {
+			return true
+		}
+	}
+	return false
+}
+
+func shouldPrintHelp(args []string) bool {
+	if len(args) == 0 {
+		return false
+	}
+	if isHelpToken(args[0]) {
+		return true
+	}
+	if hasHelpFlag(args) {
+		return true
+	}
+	switch args[0] {
+	case "check", "state", "observe", "parallel":
+		return len(args) >= 2 && args[1] == "help"
+	default:
+		return false
+	}
+}
+
+func firstNonHelp(args []string) string {
+	for _, arg := range args {
+		if isHelpToken(arg) || strings.HasPrefix(arg, "-") {
+			continue
+		}
+		return arg
+	}
+	return ""
+}
+
+func writeHelp(stdout io.Writer, text string) int {
+	fmt.Fprintln(stdout, strings.TrimRight(text, "\n"))
+	return exitOK
+}
+
+// commandHelp returns the usage text for a help request on a known command.
+// ok is false when args are not a help request, or the command is unknown so
+// the existing unknown-command path should run.
+func commandHelp(args []string) (string, bool) {
+	if !shouldPrintHelp(args) {
+		return "", false
+	}
+	switch args[0] {
+	case "-h", "-help", "--help", "help":
+		return usage, true
+	case "check":
+		return helpCheck(args[1:]), true
+	case "state":
+		return helpState(args[1:]), true
+	case "observe":
+		return helpObserve(args[1:]), true
+	case "orient":
+		return orientUsage, true
+	case "parallel":
+		return parallel.CommandUsage(firstNonHelp(args[1:])), true
+	case "migrate":
+		return migrateUsage, true
+	case "secret-scan":
+		return scanCmdUsage, true
+	case "open-visual":
+		return openVisualUsage, true
+	case "version", "--version":
+		return versionUsage, true
+	default:
+		return "", false
+	}
+}
+
+func helpCheck(rest []string) string {
+	switch firstNonHelp(rest) {
+	case "candidate":
+		return candidateUsage
+	case "readiness":
+		return readinessUsage
+	case "seal":
+		return sealUsage
+	case "path-disjoint":
+		return parallel.CommandUsage("path-disjoint")
+	case "task-graph":
+		return taskGraphUsage
+	case "skill-trust":
+		return skillTrustUsage
+	case "indexes":
+		return indexesUsage
+	default:
+		return checkUsage
+	}
+}
+
+func helpState(rest []string) string {
+	switch firstNonHelp(rest) {
+	case "resolve":
+		return resolveUsage
+	case "merge-manifest":
+		return mergeManifestUsage
+	case "close":
+		return closeUsage
+	default:
+		return stateUsage
+	}
+}
+
+func helpObserve(rest []string) string {
+	switch firstNonHelp(rest) {
+	case "summary":
+		return observeSummaryUsage
+	case "slice":
+		return observeSliceUsage
+	default:
+		return observeUsage
+	}
+}

package/engine/help_test.go

@@ -0,0 +1,98 @@
+package main
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+func TestCommandHelp(t *testing.T) {
+	t.Setenv("DEVRITES_ROOT", "")
+	tests := []struct {
+		args []string
+		want string
+	}{
+		{args: []string{"--help"}, want: "Usage:"},
+		{args: []string{"-h"}, want: "Usage:"},
+		{args: []string{"help"}, want: "Usage:"},
+		{args: []string{"check", "--help"}, want: "check candidate <slug>"},
+		{args: []string{"check", "help"}, want: "check <candidate|readiness|seal|path-disjoint|task-graph|skill-trust|indexes>"},
+		{args: []string{"check", "candidate", "--help"}, want: "check candidate <slug>"},
+		{args: []string{"check", "readiness", "-h"}, want: "check readiness --emit-binding <slug>"},
+		{args: []string{"check", "seal", "--help"}, want: "check seal <slug>"},
+		{args: []string{"check", "path-disjoint", "--help"}, want: "check path-disjoint"},
+		{args: []string{"check", "task-graph", "--help"}, want: "check task-graph <slug>"},
+		{args: []string{"check", "skill-trust", "--help"}, want: "check skill-trust <path>"},
+		{args: []string{"check", "indexes", "--help"}, want: "check indexes [--root <dir>]"},
+		{args: []string{"state", "--help"}, want: "state <resolve|merge-manifest|close>"},
+		{args: []string{"state", "-h"}, want: "state resolve"},
+		{args: []string{"state", "help"}, want: "state close <slug>"},
+		{args: []string{"state", "resolve", "--help"}, want: `state resolve <qid> "<answer>"`},
+		{args: []string{"state", "merge-manifest", "--help"}, want: "state merge-manifest <slug>"},
+		{args: []string{"state", "close", "--help"}, want: "state close <slug>"},
+		{args: []string{"parallel", "--help"}, want: "usage: parallel <subcommand>"},
+		{args: []string{"parallel", "create", "--help"}, want: "usage: parallel create --root --slug --batch --base --json"},
+		{args: []string{"parallel", "create", "-h"}, want: "parallel create"},
+		{args: []string{"parallel", "select", "--help"}, want: "parallel select --cap"},
+		{args: []string{"observe", "--help"}, want: "observe summary"},
+		{args: []string{"observe", "summary", "--help"}, want: "observe summary"},
+		{args: []string{"observe", "slice", "--help"}, want: "observe slice <slug> <SLICE-ID>"},
+		{args: []string{"orient", "--help"}, want: "orient [slug]"},
+		{args: []string{"migrate", "--help"}, want: "migrate <slug>"},
+		{args: []string{"secret-scan", "--help"}, want: "secret-scan [--staged] [--stdin]"},
+		{args: []string{"open-visual", "--help"}, want: "open-visual <path-or-name>"},
+		{args: []string{"version", "--help"}, want: "devrites-engine version"},
+		{args: []string{"install", "--help"}, want: "usage: devrites-engine install"},
+		{args: []string{"update", "--help"}, want: "usage: devrites-engine update"},
+		{args: []string{"uninstall", "--help"}, want: "usage: devrites-engine uninstall"},
+	}
+	for _, test := range tests {
+		t.Run(strings.Join(test.args, " "), func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			code := run(test.args, strings.NewReader(""), &stdout, &stderr)
+			if code != exitOK {
+				t.Fatalf("run(%q) = %d, want %d; stdout=%q stderr=%q", test.args, code, exitOK, stdout.String(), stderr.String())
+			}
+			if stderr.Len() != 0 {
+				t.Fatalf("run(%q) wrote stderr %q", test.args, stderr.String())
+			}
+			if !strings.Contains(stdout.String(), test.want) {
+				t.Fatalf("run(%q) stdout=%q, want %q", test.args, stdout.String(), test.want)
+			}
+			if strings.Contains(stdout.String(), "unknown") {
+				t.Fatalf("run(%q) treated help as unknown: %q", test.args, stdout.String())
+			}
+		})
+	}
+}
+
+func TestCommandHelpDoesNotRequireWorkspace(t *testing.T) {
+	t.Setenv("DEVRITES_ROOT", "")
+	for _, args := range [][]string{
+		{"state", "--help"},
+		{"check", "candidate", "--help"},
+		{"orient", "--help"},
+		{"migrate", "--help"},
+		{"parallel", "create", "--help"},
+	} {
+		var stdout, stderr bytes.Buffer
+		code := run(args, strings.NewReader(""), &stdout, &stderr)
+		if code != exitOK || stderr.Len() != 0 || !strings.Contains(stdout.String(), "usage:") {
+			t.Fatalf("run(%q) code=%d stdout=%q stderr=%q", args, code, stdout.String(), stderr.String())
+		}
+		if strings.Contains(stdout.String()+stderr.String(), "root selection") {
+			t.Fatalf("run(%q) required a workspace for help", args)
+		}
+	}
+}
+
+func TestUnknownCommandHelpStillUnknown(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	args := []string{"frobnicate", "--help"}
+	if code := run(args, strings.NewReader(""), &stdout, &stderr); code != exitUsage {
+		t.Fatalf("run(%q) = %d, want %d", args, code, exitUsage)
+	}
+	if !strings.Contains(stderr.String(), `unknown command "frobnicate"`) {
+		t.Fatalf("stderr = %q, want unknown-command diagnostic", stderr.String())
+	}
+}