devrites 5.4.0 → 5.5.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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.5.0](https://github.com/ViktorsBaikers/DevRites/compare/v5.4.0...v5.5.0) (2026-09-13)
+
+### Added
+
+* **rite:** cap parallel batch width and chain deferred ship ([#68](https://github.com/ViktorsBaikers/DevRites/issues/68)) ([d023dfa](https://github.com/ViktorsBaikers/DevRites/commit/d023dfa742d5b6f5a9775c21308cd4731d6858f9))
+
 ## [5.4.0](https://github.com/ViktorsBaikers/DevRites/compare/v5.3.0...v5.4.0) (2026-09-13)
 
 ### 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.4.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v5.4.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v5.5.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v5.5.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 This is the latest published release; `main` may contain unreleased work.
 

package/docs/command-map.md

@@ -41,8 +41,8 @@ The Go surface is intentionally closed and deterministic:
 | Lane | Commands | Owner |
 |---|---|---|
 | Candidate and deterministic checks | `check candidate`, `check readiness [--emit-binding]`, `check seal`, `check task-graph`, `check path-disjoint`, `check skill-trust`, `check indexes` | Candidate validates/hashes the strict project manifest; readiness checks phase files, the required `tasks.md` slice graph, or emits the vetted Build-input binding; seal checks final files/open gates, that graph and binding, then exact candidate bindings. `check indexes` reports install manifest and optional code-index directory presence as JSON. |
-| Workspace observation | `observe summary`, `orient` | JSON workspace snapshot for agents; `orient` is an alias for `observe summary`. |
-| Atomic workspace state | `state resolve`, `state close`, `migrate [--dry-run] [--answer id=choice]` | Go owns answer/drop/batch resolution, transactional close, and fail-closed v5 schema normalization. |
+| Workspace observation | `observe summary`, `orient`, `observe slice <slug> <SLICE-ID>` | JSON workspace snapshot for agents (cursor, task graph, `artifact_budgets`, `bulk_files`); `orient` is an alias for `observe summary`. `observe slice` prints one `SLICE-###` section of `tasks.md` so Build reads a slice, not the file. |
+| Atomic workspace state | `state resolve`, `state merge-manifest`, `state close`, `migrate [--dry-run] [--answer id=choice]` | Go owns answer/drop/batch resolution, the recorded predecessor-chain manifest union for a release milestone, transactional close, and fail-closed v5 schema normalization. |
 | Security | `secret-scan` | `/rite-ship`, safe hooks, or an operator scans staged blobs, stdin, or touched files. |
 | Install/operator | `install`, `update`, `uninstall`, `version` | Direct update acquires latest; npm/bootstrap may supply local candidates; the engine performs manifest-owned local changes. |
 | Native policy | no engine command | Skills/root own spec grammar re-read, qid allocation, Clarify cursor edits, AFK/recovery accounting, and read-only `/rite-doctor`. |

package/docs/engine/state-schema.md

@@ -147,6 +147,18 @@ There is no recovery-counter artifact. The caller and recovery loop count at
 most three failed attempts per causal fingerprint from current context and the
 recorded `## Dead ends` / `evidence.md`, then stop before a fourth.
 
+For a deferred-ship continuation chain (`.devrites/AFK` `continue_sequence`),
+three optional cursor fields carry the chain: `sequence_parent` (the immediately
+preceding workspace slug), `sequence_position` (1-based ordinal), and
+`sequence_workspaces_remaining` (slots the chain may still open). The controlling
+root seeds them once per continuation workspace from the recorded parent and the
+parent's counter; values only decrease, malformed values fail closed, and a
+workspace without a recorded parent/position is not a sequence member. The
+release milestone additionally carries `sequence_role: release`, which makes
+`check candidate` and `check seal` require its manifest to cover the whole
+recorded chain (built by `state merge-manifest`).
+`observe summary`/`orient` surface them under `sequence`.
+
 <!-- authority:state-tracking:start -->
 Git-tracked shared state: `.devrites/specs/`. Per-clone runtime state: `.devrites/work/`, `.devrites/archive/`, `.devrites/ACTIVE`.
 <!-- authority:state-tracking:end -->

package/docs/flow.md

@@ -351,6 +351,10 @@ erDiagram
         string status "running | awaiting_human | blocked | done"
         string active_slice "N: name"
         int afk_slices_remaining "root-owned; never negative; one charge per green built slice"
+        string sequence_parent "deferred-ship chain: preceding workspace slug"
+        int sequence_position "1-based ordinal in the recorded continuation chain"
+        int sequence_workspaces_remaining "chain slots still open after this workspace; never negative"
+        string sequence_role "release on the release milestone; gates then require the chain union"
         string return_phase "durable later-phase clarify return"
         string return_next_action "restored only after fresh CLEAR"
         block awaiting_human "qid, gate, question, proposed, raised_at (only when paused)"

package/docs/orchestration.md

@@ -127,8 +127,11 @@ conflict, extra paths, moved base, or cleanup failure stops with worktree eviden
 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 `/rite-build --parallel N` when path-disjoint eligibility, abort-batch,
-and a control `parallel-lease.md` apply (see
+**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
+the largest eligible set, recomputes after every integrate, and repeats until no pending
+slice remains; fewer than two eligible slices fall back to the serial cycle (see
 [`parallel-batch.md`](../pack/.claude/skills/rite-build/reference/parallel-batch.md)).
 Same-worktree multi-writer and root-emulated worktrees remain forbidden; default
 `/rite-build` stays one writer across linked worktrees.

package/engine/commands.go

@@ -31,7 +31,7 @@ func rootModeFor(command string, args []string) rootMode {
 		return rootLenient
 	case "state":
 		switch subcommand {
-		case "resolve", "close":
+		case "resolve", "merge-manifest", "close":
 			return rootStrict
 		}
 		return rootUnused
@@ -49,7 +49,7 @@ func rootModeFor(command string, args []string) rootMode {
 		return rootStrictUsage
 	case "observe":
 		switch subcommand {
-		case "summary":
+		case "summary", "slice":
 			return rootStrictUsage
 		}
 		return rootUnused

package/engine/internal/devritespaths/paths.go

@@ -118,6 +118,21 @@ func ArchiveDirChecked(root string) (string, error) {
 	return checkedCanonicalDir(root, filepath.Join(root, "archive"), "archive", "")
 }
 
+// ExistingArchivedFeatureDirChecked resolves an archived feature directory that
+// must already exist. A live workspace never satisfies this lookup; callers
+// that accept either location try ExistingFeatureDirChecked first.
+func ExistingArchivedFeatureDirChecked(root, slug string) (string, error) {
+	if !validSlug(slug) {
+		return "", fmt.Errorf("DRV-WORKSPACE-INVALID: %q is not a feature slug", slug)
+	}
+	candidate := filepath.Join(root, "archive", slug)
+	resolved, err := checkedCanonicalDir(root, candidate, filepath.Join("archive", slug), "")
+	if err != nil {
+		return "", err
+	}
+	return resolved, nil
+}
+
 func checkedCanonicalDir(root, candidate, parent, slug string) (string, error) {
 	resolvedRoot, err := safepath.ResolveExisting(root)
 	if err != nil {

package/engine/internal/gate/gate.go

@@ -51,9 +51,38 @@ func Check(kind Kind, root, slug string) (*Result, error) {
 	if err != nil {
 		return nil, fmt.Errorf("gate %s: %w", kind, err)
 	}
+	for _, problem := range unsanctionedRootFiles(observation) {
+		result.StateProblems = append(result.StateProblems, "placement: "+problem)
+		// Keep a more specific reason (readiness-stale) when the observation
+		// already blocked; only an otherwise-passing gate takes the generic one.
+		if !result.Blocked {
+			result.Blocked = true
+			result.ReasonID = ResultReasonID(kind, true)
+		}
+	}
 	return result, nil
 }
 
+// unsanctionedRootFiles blocks a workspace-root file the schema does not place
+// there and is over the packet ceiling. `packets/` owns by-reference dispatch
+// packets and admitted accounts (<= 64 KiB each) and `history/` owns relocated
+// narrative, so a large stray file in the root is misplaced payload — the shape
+// that let a real workspace reach 71 MB, 83% of it reviewer packets and traces
+// (see context-hygiene.md dispatch packets and its failing case).
+func unsanctionedRootFiles(observation *state.WorkspaceObservation) []string {
+	var problems []string
+	for _, file := range observation.RootFiles() {
+		if state.SanctionedRootFile(file.Name) || file.Bytes <= state.PacketMaxBytes {
+			continue
+		}
+		problems = append(problems, fmt.Sprintf(
+			"%s is %d bytes in the workspace root; move dispatch packets and accounts to packets/ (<= %d bytes each), closed narrative to history/ via /rite-plan revise, and never persist transcripts anywhere in .devrites/",
+			file.Name, file.Bytes, state.PacketMaxBytes,
+		))
+	}
+	return problems
+}
+
 func checkObservation(kind Kind, observation *state.WorkspaceObservation) (*Result, error) {
 	phase, err := observation.DeclaredPhase()
 	if err != nil {
@@ -109,6 +138,28 @@ func checkObservation(kind Kind, observation *state.WorkspaceObservation) (*Resu
 			blocked = true
 		}
 	}
+	if len(missingFiles) == 0 {
+		for _, problem := range artifactBudgetProblems(observation, policy) {
+			stateProblems = append(stateProblems, "budget: "+problem)
+			blocked = true
+		}
+	}
+	// Deliberately not gated on missingFiles: a file over the read cap IS missing,
+	// so the budget comparison below can never reach it. Missing already blocks it;
+	// name the size remedies too so the signal is actionable rather than a bare cap.
+	for _, artifact := range policy.RequiredArtifacts {
+		fact, ok := observation.Fact(artifact)
+		if !ok {
+			continue
+		}
+		if diagnostic, has := fact.Diagnostic(); has && diagnostic.Code == state.DiagnosticFileTooLarge {
+			stateProblems = append(stateProblems, fmt.Sprintf(
+				"budget: %s exceeds the %d-byte artifact cap; relocate history (history/<file>-<YYYYMMDD>.md) or split the feature via /rite-plan revise|course-correct",
+				artifact, state.MaxArtifactBytes,
+			))
+			blocked = true
+		}
+	}
 	if len(missingFiles) == 0 && phaseRequiresReadinessBinding(policy) {
 		expected, bindingErr := verifyReadinessBinding(observation)
 		if bindingErr != nil {
@@ -142,6 +193,33 @@ func checkObservation(kind Kind, observation *state.WorkspaceObservation) (*Resu
 	return result, nil
 }
 
+// artifactBudgetProblems blocks a required artifact only on a material overshoot
+// (>= state.BudgetBlockFactor of a line or byte budget) with no structural
+// `Budget override:` line. Smaller overshoots stay advisory and are reported by
+// `orient`.
+func artifactBudgetProblems(observation *state.WorkspaceObservation, policy state.PhasePolicy) []string {
+	var problems []string
+	for _, artifact := range policy.RequiredArtifacts {
+		fact, ok := observation.Fact(artifact)
+		if !ok || fact.State() != state.ArtifactPresent {
+			continue
+		}
+		if !state.ArtifactBudgetGateApplies(string(artifact)) {
+			continue
+		}
+		status, ok := state.ArtifactBudget(string(artifact), fact.Bytes())
+		if !ok || !status.Material || status.Override {
+			continue
+		}
+		problems = append(problems, fmt.Sprintf(
+			"%s is %d lines/%d bytes, at or above %gx its %d-line/%d-byte budget; relocate history (history/<file>-<YYYYMMDD>.md) or split the feature via /rite-plan revise|course-correct, or record a structural `Budget override: <reason>` line",
+			status.File, status.Lines, status.Bytes, state.BudgetBlockFactor,
+			status.LineBudget, status.ByteBudget,
+		))
+	}
+	return problems
+}
+
 func acceptanceMapProblems(observation *state.WorkspaceObservation, policy state.PhasePolicy) []string {
 	requireTasks := phaseRequiresTasks(policy)
 	requireTestPlan := phaseRequiresTestPlan(policy)

package/engine/internal/gate/gate_test.go

@@ -636,3 +636,121 @@ func writeWorkFeature(t *testing.T, root, slug string, files map[string]string)
 		testutil.WriteFile(t, filepath.Join(root, "work", slug, name), content)
 	}
 }
+
+func TestCheckBlocksMaterialBudgetOvershootWithoutOverride(t *testing.T) {
+	root := t.TempDir()
+	writeCompleteGateFeature(t, root, "oversized", state.PhaseBuild, state.PhaseBuild, "none\n")
+	workspace := filepath.Join(root, "work", "oversized")
+	oversized := "# Tasks\n\n## SLICE-001 A\nDependencies: none\n\n" + strings.Repeat("long line of planning prose\n", 500)
+	testutil.WriteFile(t, filepath.Join(workspace, "tasks.md"), oversized)
+	binding := mustReadinessBinding(t, root, "oversized")
+	testutil.AppendFile(t, filepath.Join(workspace, "eng-review.md"), "\n"+binding+"\n")
+
+	res, err := Check(Readiness, root, "oversized")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !res.Blocked {
+		t.Fatalf("blocked=false, want true")
+	}
+	joined := strings.Join(res.StateProblems, "\n")
+	if !strings.Contains(joined, "budget: tasks.md is") || !strings.Contains(joined, "Budget override") {
+		t.Fatalf("StateProblems=%q", joined)
+	}
+
+	testutil.AppendFile(t, filepath.Join(workspace, "tasks.md"), "\nBudget override: vendored requirement matrix, relocation pending\n")
+	res, err = Check(Readiness, root, "oversized")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(strings.Join(res.StateProblems, "\n"), "budget: tasks.md") {
+		t.Fatalf("override did not clear the budget problem: %v", res.StateProblems)
+	}
+}
+
+func TestCheckKeepsNonMaterialOvershootAdvisory(t *testing.T) {
+	root := t.TempDir()
+	writeCompleteGateFeature(t, root, "slightly-over", state.PhaseBuild, state.PhaseBuild, "none\n")
+	workspace := filepath.Join(root, "work", "slightly-over")
+	// 300 lines against a 280-line budget: over, but below the material factor.
+	testutil.WriteFile(t, filepath.Join(workspace, "tasks.md"), testutil.CanonicalTasksMarkdown+"\n"+strings.Repeat("note\n", 200))
+	binding := mustReadinessBinding(t, root, "slightly-over")
+	testutil.AppendFile(t, filepath.Join(workspace, "eng-review.md"), "\n"+binding+"\n")
+
+	res, err := Check(Readiness, root, "slightly-over")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(strings.Join(res.StateProblems, "\n"), "budget:") {
+		t.Fatalf("non-material overshoot must stay advisory: %v", res.StateProblems)
+	}
+}
+
+func TestCheckBlocksOversizedPacketInWorkspaceRoot(t *testing.T) {
+	root := t.TempDir()
+	writeCompleteGateFeature(t, root, "stray", state.PhaseBuild, state.PhaseBuild, "none\n")
+	workspace := filepath.Join(root, "work", "stray")
+	binding := mustReadinessBinding(t, root, "stray")
+	testutil.AppendFile(t, filepath.Join(workspace, "eng-review.md"), "\n"+binding+"\n")
+
+	// Sanctioned conditional artifact over the ceiling: placement stays legal.
+	testutil.WriteFile(t, filepath.Join(workspace, "references.md"),
+		"# refs\n\n"+strings.Repeat("reference line\n", 6000))
+	// Unsanctioned root payload over the ceiling: blocked.
+	testutil.WriteFile(t, filepath.Join(workspace, "vet-review-input-031.json"),
+		strings.Repeat("x", state.PacketMaxBytes+1))
+
+	res, err := Check(Readiness, root, "stray")
+	if err != nil {
+		t.Fatal(err)
+	}
+	joined := strings.Join(res.StateProblems, "\n")
+	if !res.Blocked || !strings.Contains(joined, "placement: vet-review-input-031.json") {
+		t.Fatalf("blocked=%v StateProblems=%q", res.Blocked, joined)
+	}
+	if !strings.Contains(joined, "packets/") {
+		t.Fatalf("remediation must name packets/: %q", joined)
+	}
+	if strings.Contains(joined, "references.md") {
+		t.Fatalf("sanctioned root artifact must not be treated as misplaced: %q", joined)
+	}
+}
+
+func TestCheckNamesSizeRemediesForArtifactOverReadCap(t *testing.T) {
+	root := t.TempDir()
+	writeCompleteGateFeature(t, root, "huge", state.PhaseBuild, state.PhaseBuild, "none\n")
+	workspace := filepath.Join(root, "work", "huge")
+	// Over the read cap, so the artifact cannot be measured against its line budget.
+	// No binding: an over-cap file cannot be hashed into one, and this asserts the
+	// size signal alone rather than a passing gate.
+	testutil.WriteFile(t, filepath.Join(workspace, "tasks.md"),
+		"# Tasks\n\n"+strings.Repeat("n\n", state.MaxArtifactBytes/2+1))
+
+	res, err := Check(Readiness, root, "huge")
+	if err != nil {
+		t.Fatal(err)
+	}
+	joined := strings.Join(res.StateProblems, "\n")
+	if !res.Blocked || !strings.Contains(joined, "budget: tasks.md exceeds the") {
+		t.Fatalf("blocked=%v StateProblems=%q", res.Blocked, joined)
+	}
+	if !strings.Contains(joined, "history/") || !strings.Contains(joined, "/rite-plan") {
+		t.Fatalf("size remedies must be named: %q", joined)
+	}
+}
+
+func TestCheckLeavesProofLedgerOvershootAdvisory(t *testing.T) {
+	root := t.TempDir()
+	writeCompleteGateFeature(t, root, "big-ledger", state.PhaseProve, state.PhaseProve, "none\n")
+	workspace := filepath.Join(root, "work", "big-ledger")
+	testutil.WriteFile(t, filepath.Join(workspace, "evidence.md"), strings.Repeat("EVID-001 proof line\n", 800))
+	testutil.WriteFile(t, filepath.Join(workspace, "touched-files.md"), strings.Repeat("trail line\n", 600))
+
+	res, err := Check(Readiness, root, "big-ledger")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if joined := strings.Join(res.StateProblems, "\n"); strings.Contains(joined, "budget:") {
+		t.Fatalf("proof ledgers must stay advisory: %v", res.StateProblems)
+	}
+}

package/engine/internal/lib/candidate.go

@@ -33,6 +33,8 @@ const (
 type candidateRow struct {
 	state      string
 	path       string
+	slice      string
+	reason     string
 	executable bool
 	size       int64
 	info       os.FileInfo
@@ -203,10 +205,12 @@ func parseCandidateManifest(raw []byte) ([]candidateRow, error) {
 		if err != nil {
 			return nil, fmt.Errorf("row %d File: %w", i+1, err)
 		}
-		if strings.TrimSpace(cells[3]) == "" {
+		sliceCell := strings.TrimSpace(cells[3])
+		if sliceCell == "" {
 			return nil, fmt.Errorf("row %d Slice must be nonempty", i+1)
 		}
-		if strings.TrimSpace(cells[4]) == "" {
+		reasonCell := strings.TrimSpace(cells[4])
+		if reasonCell == "" {
 			return nil, fmt.Errorf("row %d Reason must be nonempty", i+1)
 		}
 		if _, ok := seen[normalized]; ok {
@@ -221,7 +225,7 @@ func parseCandidateManifest(raw []byte) ([]candidateRow, error) {
 		}
 		seen[normalized] = struct{}{}
 		seenFolded[folded] = normalized
-		rows = append(rows, candidateRow{state: state, path: normalized})
+		rows = append(rows, candidateRow{state: state, path: normalized, slice: sliceCell, reason: reasonCell})
 		if len(rows) > maxCandidateRows {
 			return nil, errors.New("manifest exceeds 4096 rows")
 		}