devrites 5.10.1 → 5.10.2

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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

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.1`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v5.10.1): 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.
 

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

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/usage.md

@@ -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())
+	}
+}