devrites 5.10.0 → 5.10.2

package/engine/internal/parallel/cli.go

@@ -37,13 +37,13 @@ func runPathDisjoint(args []string, stdin io.Reader, stdout, stderr io.Writer) i
 		switch args[i] {
 		case "--root":
 			if i+1 >= len(args) {
-				fmt.Fprintln(stderr, "usage: check path-disjoint [--root <dir>] [<json-file>|-]")
+				fmt.Fprintln(stderr, usagePathDisjoint)
 				return ExitUsage
 			}
 			i++
 			root = args[i]
-		case "-h", "--help":
-			fmt.Fprintln(stdout, "usage: check path-disjoint [--root <dir>] [<json-file>|-]")
+		case "-h", "-help", "--help":
+			fmt.Fprintln(stdout, usagePathDisjoint)
 			return ExitOK
 		default:
 			if args[i] != "-" && strings.HasPrefix(args[i], "-") {
@@ -73,7 +73,6 @@ func runPathDisjoint(args []string, stdin io.Reader, stdout, stderr io.Writer) i
 }
 
 func cmdSelect(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
-	const usage = "usage: parallel select --cap <1-10> [--root <dir>] [<json-file>|-]"
 	root := ""
 	jsonPath := "-"
 	capN := 0
@@ -82,14 +81,14 @@ func cmdSelect(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 		switch args[i] {
 		case "--root":
 			if i+1 >= len(args) {
-				fmt.Fprintln(stderr, usage)
+				fmt.Fprintln(stderr, usageSelect)
 				return ExitUsage
 			}
 			i++
 			root = args[i]
 		case "--cap":
 			if i+1 >= len(args) {
-				fmt.Fprintln(stderr, usage)
+				fmt.Fprintln(stderr, usageSelect)
 				return ExitUsage
 			}
 			i++
@@ -100,8 +99,8 @@ func cmdSelect(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 			}
 			capN = n
 			sawCap = true
-		case "-h", "--help":
-			fmt.Fprintln(stdout, usage)
+		case "-h", "-help", "--help":
+			fmt.Fprintln(stdout, usageSelect)
 			return ExitOK
 		default:
 			if args[i] != "-" && strings.HasPrefix(args[i], "-") {
@@ -112,7 +111,7 @@ func cmdSelect(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 		}
 	}
 	if !sawCap {
-		fmt.Fprintln(stderr, usage)
+		fmt.Fprintln(stderr, usageSelect)
 		return ExitUsage
 	}
 	data, err := readJSONInput(jsonPath, stdin)
@@ -166,7 +165,7 @@ func runParallel(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 		return runPathDisjoint(rest, stdin, stdout, stderr)
 	case "select":
 		return cmdSelect(rest, stdin, stdout, stderr)
-	case "-h", "--help", "help":
+	case "-h", "-help", "--help", "help":
 		fmt.Fprintln(stdout, parallelUsage())
 		return ExitOK
 	default:
@@ -175,6 +174,20 @@ func runParallel(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 	}
 }
 
+const (
+	usageCreate       = "usage: parallel create --root --slug --batch --base --json"
+	usageRecordGreen  = "usage: parallel record-green --root --slug --slice --commit"
+	usageAbort        = "usage: parallel abort --root --slug"
+	usageIntegrate    = "usage: parallel integrate --root --slug [--apply-to-control]"
+	usageCleanup      = "usage: parallel cleanup --root --slug [--force]"
+	usageStatus       = "usage: parallel status --root --slug"
+	usageLeaseWrite   = "usage: parallel lease-write --root --slug --json"
+	usageLeaseRead    = "usage: parallel lease-read --root --slug [--field name]"
+	usageLeaseClear   = "usage: parallel lease-clear --root --slug"
+	usagePathDisjoint = "usage: check path-disjoint [--root <dir>] [<json-file>|-]"
+	usageSelect       = "usage: parallel select --cap <1-10> [--root <dir>] [<json-file>|-]"
+)
+
 func parallelUsage() string {
 	return strings.TrimSpace(`usage: parallel <subcommand> [options]
 
@@ -194,9 +207,40 @@ Subcommands:
 Exit codes: 0 ok, 2 usage, 3 blocked`)
 }
 
+// CommandUsage is the usage text for `parallel <name>`. An empty or unknown
+// name returns the family usage.
+func CommandUsage(name string) string {
+	switch name {
+	case "create":
+		return usageCreate
+	case "record-green":
+		return usageRecordGreen
+	case "abort":
+		return usageAbort
+	case "integrate":
+		return usageIntegrate
+	case "cleanup":
+		return usageCleanup
+	case "status":
+		return usageStatus
+	case "lease-write", "write-lease":
+		return usageLeaseWrite
+	case "lease-read", "read-lease":
+		return usageLeaseRead
+	case "lease-clear", "clear-lease":
+		return usageLeaseClear
+	case "check-disjoint", "path-disjoint":
+		return usagePathDisjoint
+	case "select":
+		return usageSelect
+	default:
+		return parallelUsage()
+	}
+}
+
 type flagSet struct {
 	Root, Slug, Batch, Base, Slice, Commit, JSON, Field, Session string
-	ApplyToControl, Force                                        bool
+	ApplyToControl, Force, Help                                  bool
 }
 
 func parseFlags(args []string, stderr io.Writer) (flagSet, []string, int) {
@@ -271,6 +315,8 @@ func parseFlags(args []string, stderr io.Writer) (flagSet, []string, int) {
 			f.ApplyToControl = true
 		case "--force":
 			f.Force = true
+		case "-h", "-help", "--help":
+			f.Help = true
 		default:
 			// No parallel subcommand takes positional args; anything
 			// unrecognized (typo'd flag, stray word) is a usage error, not
@@ -283,6 +329,18 @@ func parseFlags(args []string, stderr io.Writer) (flagSet, []string, int) {
 	return f, nil, ExitOK
 }
 
+func parseFlagsOrHelp(args []string, stdout, stderr io.Writer, usage string) (flagSet, int, bool) {
+	f, _, code := parseFlags(args, stderr)
+	if code != ExitOK {
+		return f, code, true
+	}
+	if f.Help {
+		fmt.Fprintln(stdout, usage)
+		return f, ExitOK, true
+	}
+	return f, ExitOK, false
+}
+
 func requireRootSlug(f flagSet, stderr io.Writer) int {
 	if f.Root == "" || f.Slug == "" {
 		fmt.Fprintln(stderr, "parallel: --root and --slug are required")
@@ -303,8 +361,8 @@ func readJSONInput(path string, stdin io.Reader) ([]byte, error) {
 }
 
 func cmdCreate(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
-	f, _, code := parseFlags(args, stderr)
-	if code != ExitOK {
+	f, code, done := parseFlagsOrHelp(args, stdout, stderr, usageCreate)
+	if done {
 		return code
 	}
 	if code := requireRootSlug(f, stderr); code != ExitOK {
@@ -314,7 +372,7 @@ func cmdCreate(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 		return code
 	}
 	if f.Batch == "" || f.Base == "" || f.JSON == "" {
-		fmt.Fprintln(stderr, "usage: parallel create --root --slug --batch --base --json")
+		fmt.Fprintln(stderr, usageCreate)
 		return ExitUsage
 	}
 	data, err := readJSONInput(f.JSON, stdin)
@@ -359,8 +417,8 @@ func rejectUnsupportedFlags(f flagSet, stderr io.Writer, force, applyToControl b
 }
 
 func cmdRecordGreen(args []string, stdout, stderr io.Writer) int {
-	f, _, code := parseFlags(args, stderr)
-	if code != ExitOK {
+	f, code, done := parseFlagsOrHelp(args, stdout, stderr, usageRecordGreen)
+	if done {
 		return code
 	}
 	if code := requireRootSlug(f, stderr); code != ExitOK {
@@ -370,7 +428,7 @@ func cmdRecordGreen(args []string, stdout, stderr io.Writer) int {
 		return code
 	}
 	if f.Slice == "" || f.Commit == "" {
-		fmt.Fprintln(stderr, "usage: parallel record-green --root --slug --slice --commit")
+		fmt.Fprintln(stderr, usageRecordGreen)
 		return ExitUsage
 	}
 	lease, err := RecordGreen(f.Root, f.Slug, f.Slice, f.Commit)
@@ -383,8 +441,8 @@ func cmdRecordGreen(args []string, stdout, stderr io.Writer) int {
 }
 
 func cmdAbort(args []string, stdout, stderr io.Writer) int {
-	f, _, code := parseFlags(args, stderr)
-	if code != ExitOK {
+	f, code, done := parseFlagsOrHelp(args, stdout, stderr, usageAbort)
+	if done {
 		return code
 	}
 	if code := requireRootSlug(f, stderr); code != ExitOK {
@@ -403,8 +461,8 @@ func cmdAbort(args []string, stdout, stderr io.Writer) int {
 }
 
 func cmdIntegrate(args []string, stdout, stderr io.Writer) int {
-	f, _, code := parseFlags(args, stderr)
-	if code != ExitOK {
+	f, code, done := parseFlagsOrHelp(args, stdout, stderr, usageIntegrate)
+	if done {
 		return code
 	}
 	if code := requireRootSlug(f, stderr); code != ExitOK {
@@ -427,8 +485,8 @@ func cmdIntegrate(args []string, stdout, stderr io.Writer) int {
 }
 
 func cmdCleanup(args []string, stdout, stderr io.Writer) int {
-	f, _, code := parseFlags(args, stderr)
-	if code != ExitOK {
+	f, code, done := parseFlagsOrHelp(args, stdout, stderr, usageCleanup)
+	if done {
 		return code
 	}
 	if code := requireRootSlug(f, stderr); code != ExitOK {
@@ -454,8 +512,8 @@ func cmdCleanup(args []string, stdout, stderr io.Writer) int {
 }
 
 func cmdStatus(args []string, stdout, stderr io.Writer) int {
-	f, _, code := parseFlags(args, stderr)
-	if code != ExitOK {
+	f, code, done := parseFlagsOrHelp(args, stdout, stderr, usageStatus)
+	if done {
 		return code
 	}
 	if code := requireRootSlug(f, stderr); code != ExitOK {
@@ -474,15 +532,15 @@ func cmdStatus(args []string, stdout, stderr io.Writer) int {
 }
 
 func cmdLeaseWrite(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
-	f, _, code := parseFlags(args, stderr)
-	if code != ExitOK {
+	f, code, done := parseFlagsOrHelp(args, stdout, stderr, usageLeaseWrite)
+	if done {
 		return code
 	}
 	if code := requireRootSlug(f, stderr); code != ExitOK {
 		return code
 	}
 	if f.JSON == "" {
-		fmt.Fprintln(stderr, "usage: parallel lease-write --root --slug --json")
+		fmt.Fprintln(stderr, usageLeaseWrite)
 		return ExitUsage
 	}
 	data, err := readJSONInput(f.JSON, stdin)
@@ -516,8 +574,8 @@ func cmdLeaseWrite(args []string, stdin io.Reader, stdout, stderr io.Writer) int
 }
 
 func cmdLeaseRead(args []string, stdout, stderr io.Writer) int {
-	f, _, code := parseFlags(args, stderr)
-	if code != ExitOK {
+	f, code, done := parseFlagsOrHelp(args, stdout, stderr, usageLeaseRead)
+	if done {
 		return code
 	}
 	if code := requireRootSlug(f, stderr); code != ExitOK {
@@ -567,8 +625,8 @@ func cmdLeaseRead(args []string, stdout, stderr io.Writer) int {
 }
 
 func cmdLeaseClear(args []string, stdout, stderr io.Writer) int {
-	f, _, code := parseFlags(args, stderr)
-	if code != ExitOK {
+	f, code, done := parseFlagsOrHelp(args, stdout, stderr, usageLeaseClear)
+	if done {
 		return code
 	}
 	if code := requireRootSlug(f, stderr); code != ExitOK {

package/engine/internal/parallel/cli_test.go

@@ -0,0 +1,32 @@
+package parallel
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+func TestParallelCreateHelp(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	code := Run("parallel", []string{"create", "--help"}, strings.NewReader(""), &stdout, &stderr)
+	if code != ExitOK {
+		t.Fatalf("code=%d stderr=%q", code, stderr.String())
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr=%q", stderr.String())
+	}
+	if got := stdout.String(); !strings.Contains(got, usageCreate) {
+		t.Fatalf("stdout=%q, want %q", got, usageCreate)
+	}
+}
+
+func TestParallelCreateUnknownArgumentStillErrors(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	code := Run("parallel", []string{"create", "--nope"}, strings.NewReader(""), &stdout, &stderr)
+	if code != ExitUsage {
+		t.Fatalf("code=%d, want %d", code, ExitUsage)
+	}
+	if !strings.Contains(stderr.String(), `unknown argument "--nope"`) {
+		t.Fatalf("stderr=%q", stderr.String())
+	}
+}

package/engine/main.go

@@ -71,6 +71,9 @@ func run(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 		fmt.Fprint(stderr, usage)
 		return exitUsage
 	}
+	if text, ok := commandHelp(args); ok {
+		return writeHelp(stdout, text)
+	}
 	root, rootExit, err := resolveRootFor(args[0], args[1:])
 	if err != nil {
 		fmt.Fprintf(stderr, "devrites: root selection: %v\n", err)
@@ -113,7 +116,7 @@ func run(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 
 func cmdCheck(root string, args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 	if len(args) == 0 {
-		fmt.Fprintln(stderr, "usage: devrites-engine check <candidate|readiness|seal|path-disjoint|task-graph|skill-trust|indexes> ...")
+		fmt.Fprint(stderr, checkUsage)
 		return exitUsage
 	}
 	sub, rest := args[0], args[1:]
@@ -138,7 +141,7 @@ func cmdCheck(root string, args []string, stdin io.Reader, stdout, stderr io.Wri
 
 func cmdCandidate(root string, args []string, stdout, stderr io.Writer) int {
 	if len(args) != 1 {
-		fmt.Fprintln(stderr, "usage: devrites-engine check candidate <slug>")
+		fmt.Fprintln(stderr, candidateUsage)
 		return exitUsage
 	}
 	digest, files, err := lib.CandidateIdentity(root, args[0])
@@ -156,7 +159,7 @@ func cmdCandidate(root string, args []string, stdout, stderr io.Writer) int {
 
 func cmdState(root string, args []string, stdout, stderr io.Writer) int {
 	if len(args) == 0 {
-		fmt.Fprintln(stderr, "usage: devrites-engine state <resolve|merge-manifest|close> ...")
+		fmt.Fprint(stderr, stateUsage)
 		return exitUsage
 	}
 	switch args[0] {
@@ -178,7 +181,11 @@ func cmdState(root string, args []string, stdout, stderr io.Writer) int {
 func cmdGate(root string, kind gate.Kind, args []string, stdout, stderr io.Writer) int {
 	emitBinding := kind == gate.Readiness && len(args) == 2 && args[0] == "--emit-binding"
 	if !emitBinding && len(args) != 1 {
-		fmt.Fprintf(stderr, "usage: devrites-engine check %s <slug>\n", kind)
+		if kind == gate.Readiness {
+			fmt.Fprintln(stderr, readinessUsage)
+		} else {
+			fmt.Fprintln(stderr, sealUsage)
+		}
 		return exitUsage
 	}
 	if emitBinding {
@@ -219,7 +226,7 @@ func cmdGate(root string, kind gate.Kind, args []string, stdout, stderr io.Write
 
 func cmdTaskGraph(root string, args []string, stdout, stderr io.Writer) int {
 	if len(args) != 1 {
-		fmt.Fprintln(stderr, "usage: devrites-engine check task-graph <slug>")
+		fmt.Fprintln(stderr, taskGraphUsage)
 		return exitUsage
 	}
 	return lib.RunTaskGraphCheck(root, args[0], stdout, stderr)
@@ -227,7 +234,7 @@ func cmdTaskGraph(root string, args []string, stdout, stderr io.Writer) int {
 
 func cmdSkillTrust(args []string, stdout, stderr io.Writer) int {
 	if len(args) != 1 {
-		fmt.Fprintln(stderr, "usage: devrites-engine check skill-trust <path>")
+		fmt.Fprintln(stderr, skillTrustUsage)
 		return exitUsage
 	}
 	return lib.RunSkillTrustCheck(args[0], stdout, stderr)
@@ -235,7 +242,7 @@ func cmdSkillTrust(args []string, stdout, stderr io.Writer) int {
 
 func cmdObserve(root string, args []string, stdout, stderr io.Writer) int {
 	if len(args) == 0 {
-		fmt.Fprintln(stderr, "usage: devrites-engine observe summary <slug> | observe slice <slug> <SLICE-ID>")
+		fmt.Fprint(stderr, observeUsage)
 		return exitUsage
 	}
 	switch args[0] {
@@ -251,7 +258,7 @@ func cmdObserve(root string, args []string, stdout, stderr io.Writer) int {
 		return lib.RunObserveSummary(root, slug, stdout, stderr)
 	case "slice":
 		if len(args) != 3 {
-			fmt.Fprintln(stderr, "usage: devrites-engine observe slice <slug> <SLICE-ID>")
+			fmt.Fprintln(stderr, observeSliceUsage)
 			return exitUsage
 		}
 		return lib.RunObserveSlice(root, args[1], args[2], stdout, stderr)

package/engine/root_routing_test.go

@@ -25,6 +25,10 @@ func TestRootModeForCoversReadAndWriteSurfaces(t *testing.T) {
 		{name: "observe summary", command: "observe", args: []string{"summary"}, want: rootStrictUsage},
 		{name: "observe slice", command: "observe", args: []string{"slice"}, want: rootStrictUsage},
 		{name: "orient", command: "orient", want: rootStrictUsage},
+		{name: "orient help", command: "orient", args: []string{"--help"}, want: rootUnused},
+		{name: "check candidate help", command: "check", args: []string{"candidate", "--help"}, want: rootUnused},
+		{name: "state help flag", command: "state", args: []string{"--help"}, want: rootUnused},
+		{name: "migrate help", command: "migrate", args: []string{"--help"}, want: rootUnused},
 		{name: "check indexes", command: "check", args: []string{"indexes"}, want: rootLenient},
 		{name: "resolve", command: "state", args: []string{"resolve"}, want: rootStrict},
 		{name: "close", command: "state", args: []string{"close"}, want: rootStrict},

package/pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md

@@ -56,14 +56,14 @@ max_minutes: 120                     # wall-clock minutes in one host activation
 max_review_queue: 8                  # unresolved review/gate items admitted before fan-out stops
 # max_tokens: 200000                 # optional stricter host-observed token cap
 # max_cost_usd: 10                   # optional stricter host-observed cost cap
-notify: "ntfy.sh/my-topic"           # shell command; examples: rite-build/reference/afk-discipline.md
+notify: "ntfy.sh/my-topic"           # shell command; examples: .claude/skills/rite-build/reference/afk-discipline.md
 allow_gates: [advisory, validating]  # gate severities AFK auto-handles (auto-picks the recommended option)
 continue_sequence: true              # after Seal GO, open the next recorded continuation
 max_workspaces: 5                    # workspaces one armed sequence may open
-max_parallel: 10                     # cap on eligible path-disjoint Build batches (1 = serial)
+max_parallel: 10                     # unattended default cap; `--parallel N` on this invocation wins and may rewrite only this field
 ```
 
-The file is **read-only config**: never rewritten in place. `max_slices` is the initial
+The file is **read-only config**: never rewritten in place, except `/rite-autocomplete --parallel N` writes or replaces only `max_parallel: N`. `max_slices` is the initial
 budget; the mutable remaining count is the `state.md` cursor
 `afk_slices_remaining` (`AFK slices remaining: <n>` in the released bullet
 form), owned by the controlling root. Recognize either spelling and preserve
@@ -119,11 +119,18 @@ candidate manifest to cover the whole recorded chain — run
 - Every human-owned, safety, access, exhaustion, and `NO-GO` condition still stops the
   run exactly as without this field.
 
-`max_parallel` caps a Build batch for unattended runs; `1` forces the serial cycle.
-Unattended runs take the largest eligible set ≤ cap and recompute after every completed
-round (serial slice or parallel integrate)
-([parallel-batch.md § Dynamic selection and re-batching](../../../rite-build/reference/parallel-batch.md#dynamic-selection-and-re-batching));
-an explicit `/rite-build --parallel N` cap wins for that invocation.
+`max_parallel` is the unattended default batch cap only when this invocation does
+not contain `--parallel N`; `1` forces the serial cycle only in that default
+case. An exact `--parallel N` on `/rite-autocomplete` or `/rite-build` is the
+batch cap for this run: do not consult leftover sentinel `max_parallel`, and do
+not treat `max_parallel: 1` as serial. `/rite-autocomplete --parallel N` writes
+or replaces only that field so later ticks keep the cap; `/rite-build --parallel N`
+wins for that invocation without rewriting the sentinel. Never write `max_slices`
+from `--max-slices`. **Failing case:** `/rite-autocomplete --parallel 5` honors a
+leftover `max_parallel: 1` and stays serial.
+Unattended runs take the largest eligible set ≤ that cap and recompute after
+every completed round (serial slice or parallel integrate)
+([parallel-batch.md § Dynamic selection and re-batching](../../../rite-build/reference/parallel-batch.md#dynamic-selection-and-re-batching)).
 
 ## Unattended resource envelope
 
@@ -166,7 +173,18 @@ for the full taxonomy. Summary:
 | blocking | high | sync | 15m | **no** (always pauses) |
 | escalating | novel pattern | sync to specialist | 24h | **no** (always pauses) |
 
-`blocking` and `escalating` always pause regardless of `allow_gates`.
+`blocking` and `escalating` always pause for HITL and for AFK `/rite-build`,
+regardless of `allow_gates`.
+
+**Autocomplete exception.** While `/rite-autocomplete` is the controlling
+caller, an open `gate: blocking` question that already carries a ranked
+recommended option (`proposed:` or option 1 labelled `(Recommended)`) is not a
+user handoff: the orchestrator auto-picks that option through
+`devrites-engine state resolve` and continues, including internal Spec Drift
+Guard when the answer changes ownership or acceptance. Escalating,
+irreversible-risk, access, and blocking questions with no recommended option
+still pause. Putting `blocking` in `allow_gates` does not replace this resolve
+step: an unanswered blocking question still fails Seal.
 
 An open `gate: validating` entry is **merge-blocking by definition**: at `/rite-seal` any
 `questions.md` entry with `gate: validating` and `status: open` is a NO-GO, regardless of

package/pack/.claude/skills/rite-autocomplete/SKILL.md

@@ -8,8 +8,10 @@ user-invocable: true
 # /rite-autocomplete: full lifecycle, unattended
 
 Run every phase after one clarification window. Irreversible-risk,
-blocking/escalating,<!-- pack-scan-ignore: negated statement: gates are NOT disabled -->
-and NO-GO still pause. Use the Standard native
+escalating,<!-- pack-scan-ignore: negated statement: gates are NOT disabled -->
+access, unanswered blocking with no recommended option, and remaining NO-GO
+still pause. Open blocking questions that already name a ranked recommended
+option auto-resolve; they are not a user handoff. Use the Standard native
 profile by default and Full for high-risk scope or explicit `--full`; see
 [`orchestration-profiles.md`](../devrites-lib/reference/orchestration-profiles.md).
 
@@ -85,25 +87,34 @@ executable controller/harness/bundle bytes or a missing writer, read
 3. **Arm AFK once.** Apply the loop's
    [one-write AFK contract](reference/loop.md#arm-afk-once): preserve valid
    existing bytes or create the sentinel once (`allow_gates: [advisory, validating]`); never
-   rewrite it after Vet. Preserve an existing sentinel byte-for-byte.
+   rewrite it after Vet except to write or replace only `max_parallel: N` when
+   this invocation contains `--parallel N`. Preserve an existing sentinel
+   byte-for-byte otherwise. **Failing case:** leftover `max_parallel: 1` keeps
+   the run serial after `--parallel 5`.
    **Completion:** a valid read-only AFK sentinel exists.
 4. **Drive phases.** Follow [the loop](reference/loop.md): `/rite-spec` →
    `/rite-clarify` → `/rite-temper` → `/rite-define` → `/rite-vet` →
    `/rite-build` batch loop → `/rite-prove` → `/rite-polish` →
    `/rite-review` → `/rite-seal`. Read and execute each skill; durable files, not
    chat, carry state. Apply the mutable post-vet budget before first Build.
-   Build runs the largest eligible path-disjoint batch (cap: `--parallel N`, else
-   sentinel `max_parallel`, else 10) and recomputes after every completed round until no
-   pending slice remains; a one-slice round is serial for that round only, then
+   Build runs the largest eligible path-disjoint batch (cap: this invocation's
+   `--parallel N`, else sentinel `max_parallel`, else 10) and recomputes after
+   every completed round until no pending slice remains; a one-slice round is serial for that round only, then
    selection runs again (host isolation still forces serial when concurrent writers
-   cannot be separated).
+   cannot be separated). When `--parallel N`
+   is present, pass it into `/rite-build` and do not consult leftover sentinel
+   `max_parallel`.
    **Completion:** loop reaches Seal GO or persists a valid stop before any later phase.
 5. **Apply stops.** At every gate use
    [stop-conditions.md](reference/stop-conditions.md). A `blocked` label alone is not a stop condition:
    route agent-owned red results through bounded recovery.
    Red gates block forward advancement and enter caller-owned recovery. Stop on
-   hard risk, human-owned blocking/escalating/NO-GO, or the
-   exact fingerprint's proven exhaustion. Technical exhaustion records terminal
+   hard risk, escalating, irreversible-risk, access, blocking with no
+   recommended option, remaining NO-GO, or the exact fingerprint's proven
+   exhaustion. An open blocking question that already names a ranked recommended
+   option (`proposed` or option 1 labelled Recommended) auto-resolves through
+   `devrites-engine state resolve` and continues; do not emit `/rite-resolve` as
+   a user handoff. Technical exhaustion records terminal
    `Next step: none`, never a routine phase command. **Completion:** no stop is active, or its cursor and reason are durable.
 6. **Seal boundary.** Without a ship flag, stop at Seal GO with `/rite-ship` —
    unless `continue_sequence` is armed and sequence budget remains, in which case

package/pack/.claude/skills/rite-autocomplete/reference/decision-policy.md

@@ -36,5 +36,8 @@ not pick the option that's merely easiest to implement.
 
 ## When a choice is NOT autocomplete's to make
 
-Human-owned blocking/escalating, irreversible-risk, and access stay human.
-Recommended temper `expand` auto-applies; do not invent product intent.
+Irreversible-risk, escalating, access, and blocking questions with no ranked
+recommended option stay human. A blocking question that already names option 1
+`(Recommended)` or `proposed:` is autocomplete's to resolve: pick that option
+via `devrites-engine state resolve` and continue. Recommended temper `expand`
+auto-applies; do not invent product intent.

package/pack/.claude/skills/rite-autocomplete/reference/loop.md

@@ -17,18 +17,21 @@ allow_gates: [advisory, validating]
 # max_slices / max_agents / max_minutes / max_review_queue omitted: unlimited
 # continue_sequence: true          # opt-in: chain recorded continuations after Seal GO
 # max_workspaces: 5                # sequence budget when chaining
-# max_parallel: 10                 # Build batch cap; 1 = serial (default: eligible, cap 10)
+# max_parallel: 10                 # default cap when this invocation omits `--parallel N`; `--parallel N` wins and rewrites only this field
 # max_tokens: <N>
 # max_cost_usd: <amount>
 # notify: "<cmd>"
 ```
 
-Read an existing sentinel first. Preserve it byte-for-byte when valid; stop if
+Read an existing sentinel first. Preserve it byte-for-byte when valid, except
+when this invocation contains `--parallel N`: then write or replace only
+`max_parallel: N` and leave every other key unchanged. Stop if the sentinel is
 malformed. Do not stop because it names `max_slices` / `max_agents` /
 `max_minutes` / `max_review_queue` or only `[advisory]`. If absent, write it
-once after clarity. Never write `max_slices` from `--max-slices`.
-It is read-only: never rewrite it after Vet or reset it on resume. Leftover
-`expires_at` is ignored and never rewritten.
+once after clarity, and include `max_parallel: N` when that flag is present.
+Never write `max_slices` from `--max-slices`. It is otherwise read-only: never rewrite it after Vet or reset it on resume. Leftover `expires_at` is ignored
+and never rewritten. **Failing case:** leftover `max_parallel: 1` keeps the run
+serial after `--parallel 5`.
 
 ### Derive the mutable post-vet budget
 
@@ -44,8 +47,13 @@ readiness check first; reject overlap. Do not stop on `max_agents`,
 gets fresh activation-local counters but retains durable slice/recovery state.
 
 When driving `/rite-build`, ignore afk-discipline remaining-0, `--max-slices`,
-and parallel AFK headroom. Close validating questions
-(recommended pick) instead of queuing them.
+and parallel AFK headroom as stop conditions. Pass this invocation's
+`--parallel N` into `/rite-build` when present; leftover sentinel
+`max_parallel` is then not the cap. Close validating questions and blocking questions
+that already name a ranked recommended option (recommended pick via
+`devrites-engine state resolve`) instead of queuing them or handing
+`/rite-resolve` to the user. Escalating, irreversible-risk, access, and
+blocking with no recommended option still pause.
 
 ## Phase arc
 
@@ -58,7 +66,7 @@ Workspace files carry state; chat does not. Read and execute each phase skill:
 | 3 | `/rite-temper` | harden, reduce, or expand; irreversible risk still pauses |
 | 4 | `/rite-define` | approved plan/tasks/traceability |
 | 5 | `/rite-vet` | every plan; derive mutable budget after READY |
-| 6 | `/rite-build` batch loop | largest eligible path-disjoint set (cap 10; one-slice round when <2 eligible); recompute after each round; charge once per green built slice |
+| 6 | `/rite-build` batch loop | largest eligible path-disjoint set (cap: this invocation's `--parallel N`, else sentinel `max_parallel`, else 10; one-slice round when <2 eligible); recompute after each round; charge once per green built slice |
 | 7 | `/rite-prove` | all slices built; approved proof; recovery on red |
 | 8 | `/rite-polish` | re-prove after code edits |
 | 9 | `/rite-review` | in-scope correction then fresh proof |
@@ -122,16 +130,19 @@ agent-owned earlier-phase gap:
 6. Restore and consume the original cursor when prerequisites are green.
 
 <!-- workflow-artifact-adapter: {"module":"devrites-lib/reference/standards/workflow-artifacts.md","entry":"loop tick sees Workflow Artifact trigger/state","action":"invoke classifier once under owner lock; no actor-history migration","return":"same loop cursor; no budget charge for verify/rerun"} -->
-Ask only for a human-owned decision or mandatory safety/access action. Three
-no-progress corrections of one exact fingerprint exhaust; preserve its
-reproduction and dead ends without another Plan/Vet command.
+Ask only for a human-owned decision or mandatory safety/access action. An open
+blocking question with `proposed` or option 1 labelled Recommended is not that
+decision: resolve it and continue. Three no-progress corrections of one exact
+fingerprint exhaust; preserve its reproduction and dead ends without another
+Plan/Vet command.
 
 ## Continuous caller obligation
 
 No user-facing reply is permitted while durable state contains agent-owned
-`NEEDS_REPLAN`, an intermediate Plan/Vet action, or a distinct retained
-Critical/Important fingerprint below its cap. Invoke the next internal repair
-immediately. A narrow reviewer closing one finding and exposing another
+`NEEDS_REPLAN`, an intermediate Plan/Vet action, a distinct retained
+Critical/Important fingerprint below its cap, or an open blocking question that
+already names a ranked recommended option. Invoke the next internal repair or
+`devrites-engine state resolve` immediately. A narrow reviewer closing one finding and exposing another
 Critical/Important invariant is progress, not exhaustion.
 
 The number of completed repair/Vet cycles is not a stop condition. Context

package/pack/.claude/skills/rite-autocomplete/reference/stop-conditions.md

@@ -59,14 +59,21 @@ exhausted.
 <!-- workflow-artifact-adapter: {"module":"devrites-lib/reference/standards/workflow-artifacts.md","entry":"classifier returns owner-busy, exhausted, or existing hard gate","action":"stop on exact WAIT_ACTIVE_OWNER, BLOCKED_EXHAUSTED, or BLOCKED_GATE result","return":"unchanged cursor plus fixed route-owned output"} -->
 ## Other stop classes
 
-- **Gate severity:** blocking or escalating gate. Validating: auto-pick the
-  recommended option, close the question, continue.
+- **Gate severity:** escalating always stops. Blocking with a ranked recommended
+  option (`proposed` or option 1 labelled Recommended): auto-pick via
+  `devrites-engine state resolve`, then continue internally (including Spec Drift
+  Guard when the answer changes ownership or acceptance). Blocking with no
+  recommended option still stops. Validating: auto-pick the recommended option,
+  close the question, continue.
 - **Temper:** `expand` and extra acceptance auto-apply (record + Drift Guard).
   Irreversible-risk still pauses. `hold-rigor`, `reduce-to-MVP`, and a skip do not pause.
 - **Clarify:** material Partial/Missing/unowned decision coverage or a
   low-confidence high-consequence assumption. Continue the initial interview;
   never arm AFK early.
-- **Seal:** NO-GO, with every blocker and fix direction. Never round up to GO.
+- **Seal:** remaining NO-GO after recommended-option questions are closed, with
+  every remaining blocker and fix direction. Never round up to GO. An open
+  recommended-option blocking question is not a Seal stop: resolve it, recover
+  agent-owned findings, then re-enter Seal.
 - **Reslice:** execute its marked action before deciding continue/stop.
 - **Slice budget:** do not stop on `--max-slices`. Leftover
   pre-existing remaining value, explicit flag, sentinel cap, or post-vet pending count