devrites 5.4.0 → 5.6.0

package/engine/internal/install/apply.go

@@ -24,6 +24,7 @@ func (r *runner) install() error {
 	fmt.Fprintf(r.opts.Stdout, "  agents : %s\n", yesno(r.opts.WithAgents))
 	fmt.Fprintf(r.opts.Stdout, "  codex  : %s\n", yesno(r.opts.WithCodex))
 	fmt.Fprintf(r.opts.Stdout, "  omp    : %s\n", yesno(r.opts.WithOmp))
+	fmt.Fprintf(r.opts.Stdout, "  pi     : %s\n", yesno(r.opts.WithPi))
 	fmt.Fprintf(r.opts.Stdout, "  aliases: %s\n", r.opts.AliasMode)
 	if r.opts.DryRun {
 		fmt.Fprintln(r.opts.Stdout, "  (dry run - no changes will be made)")
@@ -38,7 +39,7 @@ func (r *runner) install() error {
 		return err
 	}
 
-	for _, tree := range hostpack.InstallTrees(r.opts.WithSkills, r.opts.WithAgents, r.opts.WithCodex, r.opts.WithOmp) {
+	for _, tree := range hostpack.InstallTrees(r.opts.WithSkills, r.opts.WithAgents, r.opts.WithCodex, r.opts.WithOmp, r.opts.WithPi) {
 		if err := r.installTree(tree.PayloadPrefix, tree.TargetPrefix); err != nil {
 			return fmt.Errorf("install tree %s: %w", tree.TargetPrefix, err)
 		}
@@ -49,7 +50,7 @@ func (r *runner) install() error {
 			if err != nil {
 				return fmt.Errorf("render alias skill %s: %w", alias.Name, err)
 			}
-			for _, rel := range hostpack.AliasTargets(alias, r.opts.WithCodex, r.opts.WithOmp) {
+			for _, rel := range hostpack.AliasTargets(alias, r.opts.WithCodex, r.opts.WithOmp, r.opts.WithPi) {
 				if err := r.installData(data, rel); err != nil {
 					return fmt.Errorf("install alias: %w", err)
 				}
@@ -64,6 +65,11 @@ func (r *runner) install() error {
 			return fmt.Errorf("merge %s: %w", hostpack.CodexConfigMerge.TargetRel, err)
 		}
 	}
+	if r.opts.WithSkills && r.opts.WithPi {
+		if err := r.mergeMarkerFile(hostpack.PiAgentsMerge); err != nil {
+			return fmt.Errorf("merge %s: %w", hostpack.PiAgentsMerge.TargetRel, err)
+		}
+	}
 	if r.opts.WithSkills {
 		if err := r.seedClaudeSettings(); err != nil {
 			return fmt.Errorf("seed claude settings: %w", err)
@@ -93,11 +99,11 @@ func (r *runner) install() error {
 	fmt.Fprintf(r.opts.Stdout, "  installed: %d   overwritten: %d   skipped(conflict): %d   pruned: %d\n", r.stats.installed, r.stats.overwrote, r.stats.skipped, r.stats.pruned)
 	if !r.opts.DryRun && r.opts.WithSkills {
 		switch {
-		case r.opts.WithCodex && r.opts.WithOmp:
-			fmt.Fprintln(r.opts.Stdout, "Next: reopen the project, then run /rite (Claude) or $rite (Codex) or /skill:rite.")
+		case r.opts.WithCodex && (r.opts.WithOmp || r.opts.WithPi):
+			fmt.Fprintln(r.opts.Stdout, "Next: reopen the project, then run /rite (Claude) or $rite (Codex) or /skill:rite (omp/pi).")
 		case r.opts.WithCodex:
 			fmt.Fprintln(r.opts.Stdout, "Next: reopen the project, then run /rite (Claude) or $rite (Codex).")
-		case r.opts.WithOmp:
+		case r.opts.WithOmp || r.opts.WithPi:
 			fmt.Fprintln(r.opts.Stdout, "Next: reopen the project, then run /rite or /skill:rite.")
 		default:
 			fmt.Fprintln(r.opts.Stdout, "Next: reopen the project, then run /rite.")
@@ -311,6 +317,9 @@ func (r *runner) flagsString() string {
 	if !r.opts.WithOmp {
 		flags = append(flags, "--no-omp")
 	}
+	if !r.opts.WithPi {
+		flags = append(flags, "--no-pi")
+	}
 	if !r.opts.WithBinary {
 		flags = append(flags, "--no-binary")
 	}

package/engine/internal/install/install.go

@@ -35,6 +35,7 @@ type Options struct {
 	WithAgents  bool
 	WithCodex   bool
 	WithOmp     bool
+	WithPi      bool
 	WithBinary  bool
 	KeepBinary  bool
 	AliasMode   string
@@ -84,6 +85,7 @@ func DefaultOptions(mode Mode) Options {
 		WithAgents: true,
 		WithCodex:  true,
 		WithOmp:    true,
+		WithPi:     true,
 		WithBinary: true,
 		AliasMode:  "safe",
 		Stdout:     io.Discard,
@@ -135,6 +137,7 @@ func parseArgs(args []string, opts *Options) error {
 	force := flags.Bool("force", opts.Force, "")
 	noCodex := flags.Bool("no-codex", !opts.WithCodex, "")
 	noOmp := flags.Bool("no-omp", !opts.WithOmp, "")
+	noPi := flags.Bool("no-pi", !opts.WithPi, "")
 	noAgents := flags.Bool("no-agents", !opts.WithAgents, "")
 	noSkills := flags.Bool("no-skills", !opts.WithSkills, "")
 	noBinary := flags.Bool("no-binary", !opts.WithBinary, "")
@@ -162,6 +165,7 @@ func parseArgs(args []string, opts *Options) error {
 	opts.Force = *force
 	opts.WithCodex = !*noCodex
 	opts.WithOmp = !*noOmp
+	opts.WithPi = !*noPi
 	opts.WithAgents = !*noAgents
 	opts.WithSkills = !*noSkills
 	opts.WithBinary = !*noBinary
@@ -208,7 +212,7 @@ func usage(mode Mode) string {
 	case ModeUpdate:
 		return "usage: devrites-engine update [--target DIR] [--dry-run] [--force] [--check] [install flags] [--source-dir DIR --payload-dir DIR]\n"
 	default:
-		return "usage: devrites-engine install [--target DIR] [--dry-run] [--force] [--no-codex] [--no-omp] [--no-agents] [--no-skills] [--no-binary] [--short-aliases=all]\n"
+		return "usage: devrites-engine install [--target DIR] [--dry-run] [--force] [--no-codex] [--no-omp] [--no-pi] [--no-agents] [--no-skills] [--no-binary] [--short-aliases=all]\n"
 	}
 }
 
@@ -333,7 +337,7 @@ func (r *runner) validatePayload() error {
 	if r.payload == "" {
 		return fmt.Errorf("generated install payload not found; pass --payload-dir or run scripts/build-host-artifacts.sh")
 	}
-	if err := hostpack.ValidatePayload(r.payloadFS, r.opts.WithCodex, r.opts.WithOmp); err != nil {
+	if err := hostpack.ValidatePayload(r.payloadFS, r.opts.WithCodex, r.opts.WithOmp, r.opts.WithPi); err != nil {
 		return fmt.Errorf("generated install payload under %s: %w", r.payload, err)
 	}
 	return nil
@@ -349,6 +353,8 @@ func isGlobalTarget(target string) bool {
 		filepath.Join(home, ".codex"),
 		filepath.Join(home, ".omp"),
 		filepath.Join(home, ".omp", "agent"),
+		filepath.Join(home, ".pi"),
+		filepath.Join(home, ".pi", "agent"),
 	} {
 		if target == global || strings.HasPrefix(target, global+string(os.PathSeparator)) {
 			return true

package/engine/internal/install/install_test.go

@@ -53,12 +53,14 @@ func TestInstallPrintsFirstMoveForInstalledHosts(t *testing.T) {
 		name      string
 		withCodex bool
 		withOmp   bool
+		withPi    bool
 		want      string
 	}{
-		{name: "Claude, Codex, and OMP", withCodex: true, withOmp: true, want: "Next: reopen the project, then run /rite (Claude) or $rite (Codex) or /skill:rite."},
-		{name: "Claude and Codex", withCodex: true, withOmp: false, want: "Next: reopen the project, then run /rite (Claude) or $rite (Codex)."},
-		{name: "Claude and OMP", withCodex: false, withOmp: true, want: "Next: reopen the project, then run /rite or /skill:rite."},
-		{name: "Claude only", withCodex: false, withOmp: false, want: "Next: reopen the project, then run /rite."},
+		{name: "Claude, Codex, and OMP", withCodex: true, withOmp: true, want: "Next: reopen the project, then run /rite (Claude) or $rite (Codex) or /skill:rite (omp/pi)."},
+		{name: "Claude and Codex", withCodex: true, withOmp: false, withPi: false, want: "Next: reopen the project, then run /rite (Claude) or $rite (Codex)."},
+		{name: "Claude and OMP", withCodex: false, withOmp: true, withPi: false, want: "Next: reopen the project, then run /rite or /skill:rite."},
+		{name: "Claude and pi", withCodex: false, withOmp: false, withPi: true, want: "Next: reopen the project, then run /rite or /skill:rite."},
+		{name: "Claude only", withCodex: false, withOmp: false, withPi: false, want: "Next: reopen the project, then run /rite."},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
 			var out bytes.Buffer
@@ -67,6 +69,7 @@ func TestInstallPrintsFirstMoveForInstalledHosts(t *testing.T) {
 			opts.PayloadDir = testPayload(t)
 			opts.WithCodex = tc.withCodex
 			opts.WithOmp = tc.withOmp
+			opts.WithPi = tc.withPi
 			opts.Stdout = &out
 			opts.Stderr = &bytes.Buffer{}
 
@@ -758,7 +761,7 @@ func TestLegacyCodexHooksMergeIsCleanupOnly(t *testing.T) {
 	if !ok || merge != legacy {
 		t.Fatalf("legacy marker lookup = %#v, %t", merge, ok)
 	}
-	if slices.Contains(hostpack.RequiredPayload(true, true), "codex/hooks.json") {
+	if slices.Contains(hostpack.RequiredPayload(true, true, true), "codex/hooks.json") {
 		t.Fatal("legacy Codex hooks entered the required payload")
 	}
 	r := runner{opts: DefaultOptions(ModeInstall), payloadFS: os.DirFS(testPayload(t))}
@@ -1247,6 +1250,10 @@ extends = ":workspace"
 	testutil.WriteFile(t, filepath.Join(root, "omp", "skills", "rite", "SKILL.md"), "omp rite\n")
 	testutil.WriteFile(t, filepath.Join(root, "omp", "agents", "devrites-code-reviewer.md"), "omp agent\n")
 	testutil.WriteFile(t, filepath.Join(root, "omp", ".omp-plugin", "plugin.json"), "{}\n")
+	testutil.WriteFile(t, filepath.Join(root, "pi", "skills", "rite", "SKILL.md"), "pi rite\n")
+	testutil.WriteFile(t, filepath.Join(root, "pi", "agents", "devrites-code-reviewer.md"), "pi agent\n")
+	testutil.WriteFile(t, filepath.Join(root, "pi", "prompts", "rite.md"), "pi prompt\n")
+	testutil.WriteFile(t, filepath.Join(root, "pi", "AGENTS.md"), "<!-- BEGIN DEVRITES PI -->\nDevRites\n<!-- END DEVRITES PI -->\n")
 }
 
 func testSource(t *testing.T, version string) string {

package/engine/internal/install/merge.go

@@ -63,6 +63,11 @@ func (r *runner) mergeMarkerFile(merge hostpack.MarkerMerge) error {
 		if err := fsutil.WriteFileAtomic(dest, next, 0o644); err != nil {
 			return fmt.Errorf("cannot write %s: %w", merge.TargetRel, err)
 		}
+		// Multiple marker blocks can share one target (AGENTS.md carries both
+		// the Codex and pi blocks).
+		if err := r.refreshPreflight(merge.TargetRel); err != nil {
+			return err
+		}
 	}
 	return r.installMarker(merge.MarkerRel, merge.MarkerText)
 }

package/engine/internal/install/preflight.go

@@ -93,7 +93,7 @@ func (r *runner) preflightUninstall(entries []string) error {
 
 func (r *runner) desiredInstallPaths() (map[string]bool, error) {
 	out := map[string]bool{".devrites/README.md": true}
-	for _, tree := range hostpack.InstallTrees(r.opts.WithSkills, r.opts.WithAgents, r.opts.WithCodex, r.opts.WithOmp) {
+	for _, tree := range hostpack.InstallTrees(r.opts.WithSkills, r.opts.WithAgents, r.opts.WithCodex, r.opts.WithOmp, r.opts.WithPi) {
 		err := fs.WalkDir(r.payloadFS, tree.PayloadPrefix, func(path string, d fs.DirEntry, err error) error {
 			if err != nil {
 				return err
@@ -114,7 +114,7 @@ func (r *runner) desiredInstallPaths() (map[string]bool, error) {
 	}
 	if r.opts.WithSkills && r.opts.AliasMode == "all" {
 		for _, alias := range hostpack.Aliases {
-			for _, rel := range hostpack.AliasTargets(alias, r.opts.WithCodex, r.opts.WithOmp) {
+			for _, rel := range hostpack.AliasTargets(alias, r.opts.WithCodex, r.opts.WithOmp, r.opts.WithPi) {
 				out[rel] = true
 			}
 		}
@@ -123,6 +123,9 @@ func (r *runner) desiredInstallPaths() (map[string]bool, error) {
 		out[hostpack.CodexAgentsMerge.MarkerRel] = true
 		out[hostpack.CodexConfigMerge.MarkerRel] = true
 	}
+	if r.opts.WithSkills && r.opts.WithPi {
+		out[hostpack.PiAgentsMerge.MarkerRel] = true
+	}
 	if r.opts.WithSkills {
 		out[hostpack.ClaudeSettingsMerge.MarkerRel] = true
 	}
@@ -136,6 +139,9 @@ func (r *runner) installMergeTargets() []string {
 		if r.opts.WithCodex {
 			out = append(out, hostpack.CodexAgentsMerge.TargetRel, hostpack.CodexConfigMerge.TargetRel)
 		}
+		if r.opts.WithPi {
+			out = append(out, hostpack.PiAgentsMerge.TargetRel)
+		}
 	}
 	return out
 }
@@ -153,6 +159,18 @@ func (r *runner) rememberPath(rel string) (pathSnapshot, error) {
 	return snapshot, nil
 }
 
+// refreshPreflight replaces a recorded snapshot after the runner's own
+// verified write (marker merge, strip). Needed when several managed merges
+// share one target such as AGENTS.md.
+func (r *runner) refreshPreflight(rel string) error {
+	snap, err := inspectManagedPath(r.target, rel)
+	if err != nil {
+		return err
+	}
+	r.preflight[filepath.ToSlash(rel)] = snap
+	return nil
+}
+
 func (r *runner) recheckPath(rel string) error {
 	rel = filepath.ToSlash(rel)
 	before, ok := r.preflight[rel]

package/engine/internal/install/uninstall.go

@@ -58,6 +58,11 @@ func (r *runner) uninstall() error {
 		if err := stripMarkerPath(filepath.Join(r.target, filepath.FromSlash(merge.TargetRel)), merge.Begin, merge.End); err != nil {
 			return fmt.Errorf("strip marker block from %s: %w", merge.TargetRel, err)
 		}
+		// The Codex and pi AGENTS.md blocks share one target; record the strip
+		// so the next merge's recheckPath sees our own write, not a race.
+		if err := r.refreshPreflight(merge.TargetRel); err != nil {
+			return err
+		}
 	}
 
 	var dirs []string

package/engine/internal/install/update.go

@@ -65,7 +65,7 @@ func runUpdate(opts Options) error {
 	if err != nil {
 		return fmt.Errorf("resolve payload %s: %w", opts.PayloadDir, err)
 	}
-	if err := hostpack.ValidatePayload(os.DirFS(payload), true, true); err != nil {
+	if err := hostpack.ValidatePayload(os.DirFS(payload), true, true, true); err != nil {
 		return fmt.Errorf("local update payload under %s is invalid: %w", payload, err)
 	}
 	installFlags := manifestHeader(mf, "devrites-flags")

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")
 		}

package/engine/internal/lib/manifest_union.go

@@ -0,0 +1,326 @@
+package lib
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/state"
+)
+
+// maxSequenceChain bounds the sequence_parent walk so a malformed cycle cannot
+// loop forever; real chains are far smaller.
+const maxSequenceChain = 64
+
+// RunMergeManifest folds predecessor candidate manifests into the release
+// workspace's `## Candidate manifest` so a release milestone's prove/review/seal
+// binds the union surface instead of only its own slices. On a path collision
+// the later sequence position's row wins (it records the most recent touch).
+// Everything outside the manifest section of the release workspace's
+// touched-files.md is preserved.
+//
+// args is `<slug>` to walk the recorded `sequence_parent` chain, or
+// `<slug> <predecessor> [<predecessor>...]` for an explicit ordered list —
+// required for chains recorded before the sequence cursor fields existed.
+// Exit codes:
+//
+//	0  merged and written
+//	2  usage error
+//	3  blocked: a workspace, manifest, or chain check failed
+//	1  internal/IO error
+func RunMergeManifest(root string, args []string, stdout, stderr io.Writer) int {
+	if len(args) < 1 {
+		fmt.Fprintln(stderr, "usage: devrites-engine state merge-manifest <slug> [<predecessor>...]")
+		return 2
+	}
+	slug := args[0]
+	workspace, err := devritespaths.ExistingFeatureDirChecked(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "merge-manifest: BLOCKED: workspace for %s: %v\n", slug, err)
+		return 3
+	}
+	if err := state.RequireWorkspaceSchema(root, slug); err != nil {
+		fmt.Fprintf(stderr, "merge-manifest: BLOCKED: %v\n", err)
+		return 3
+	}
+	manifestPath := filepath.Join(workspace, "touched-files.md")
+	releaseRaw, err := readBoundedRegularFile(manifestPath, maxCandidateManifestBytes)
+	if err != nil {
+		fmt.Fprintf(stderr, "merge-manifest: BLOCKED: candidate manifest %s: %v\n", manifestPath, err)
+		return 3
+	}
+
+	var manifests [][]candidateRow
+	if len(args) > 1 {
+		manifests, err = explicitManifests(root, slug, args[1:])
+	} else {
+		// The walked chain is validated inside walkSequenceChain; only its
+		// manifests feed the union.
+		_, manifests, err = walkSequenceChain(root, slug, workspace)
+	}
+	if err != nil {
+		fmt.Fprintf(stderr, "merge-manifest: BLOCKED: %v\n", err)
+		return 3
+	}
+
+	merged := make(map[string]candidateRow)
+	collisions := 0
+	fold := func(rows []candidateRow) {
+		for _, row := range rows {
+			if _, dup := merged[row.path]; dup {
+				collisions++
+			}
+			merged[row.path] = row
+		}
+	}
+	for _, rows := range manifests {
+		fold(rows)
+	}
+	releaseRows, err := parseCandidateManifest(releaseRaw)
+	if err != nil {
+		fmt.Fprintf(stderr, "merge-manifest: BLOCKED: candidate manifest %s: %v\n", manifestPath, err)
+		return 3
+	}
+	fold(releaseRows)
+
+	paths := make([]string, 0, len(merged))
+	for path := range merged {
+		paths = append(paths, path)
+	}
+	sort.Strings(paths)
+	body := make([]string, 0, len(paths)+2)
+	if len(paths) == 0 {
+		body = append(body, "No project files.")
+	} else {
+		body = append(body, "| State | File | Slice | Reason |", "| --- | --- | --- | --- |")
+		for _, path := range paths {
+			row := merged[path]
+			body = append(body, fmt.Sprintf("| %s | `%s` | %s | %s |", row.state, row.path, row.slice, row.reason))
+		}
+	}
+	updated, err := replaceManifestSectionBody(releaseRaw, body)
+	if err != nil {
+		fmt.Fprintf(stderr, "merge-manifest: BLOCKED: candidate manifest %s: %v\n", manifestPath, err)
+		return 3
+	}
+	if err := state.AtomicWrite(manifestPath, updated, 0o644); err != nil {
+		fmt.Fprintf(stderr, "merge-manifest: cannot write %s: %v\n", manifestPath, err)
+		return 1
+	}
+	fmt.Fprintf(stdout, "merge-manifest: merged %d manifest(s) into %d row(s)", len(manifests)+1, len(paths))
+	if collisions > 0 {
+		fmt.Fprintf(stdout, " (%d path collision(s), later position kept)", collisions)
+	}
+	fmt.Fprintln(stdout)
+	return 0
+}
+
+// explicitManifests parses the caller-ordered predecessor list. When the
+// workspace carries a sequence_parent cursor, the last predecessor must be the
+// recorded parent; a mismatch means the list does not describe this chain.
+func explicitManifests(root, slug string, predecessors []string) ([][]candidateRow, error) {
+	seen := make(map[string]struct{}, len(predecessors))
+	for _, pred := range predecessors {
+		if pred == slug {
+			return nil, fmt.Errorf("predecessor %q names the target workspace", pred)
+		}
+		if _, dup := seen[pred]; dup {
+			return nil, fmt.Errorf("duplicate predecessor %q", pred)
+		}
+		seen[pred] = struct{}{}
+	}
+	if parent := sequenceParent(root, slug); parent != "" && parent != predecessors[len(predecessors)-1] {
+		return nil, fmt.Errorf("%s records sequence_parent %q; pass the full ordered predecessor list ending with it (or no list to walk the recorded chain)", slug, parent)
+	}
+	manifests := make([][]candidateRow, 0, len(predecessors))
+	for _, pred := range predecessors {
+		rows, err := predecessorManifestRows(root, pred)
+		if err != nil {
+			return nil, fmt.Errorf("predecessor %s: %w", pred, err)
+		}
+		manifests = append(manifests, rows)
+	}
+	return manifests, nil
+}
+
+// walkSequenceChain follows the target workspace's sequence_parent links to the
+// chain head, returning predecessors oldest-first with their manifests. Every
+// link must resolve to a live or archived workspace carrying the cursor field;
+// a broken link refuses the merge rather than producing a partial union.
+func walkSequenceChain(root, slug, workspace string) ([]string, [][]candidateRow, error) {
+	visited := map[string]struct{}{slug: {}}
+	chain := []string{}
+	manifests := [][]candidateRow{}
+	dir := workspace
+	for len(chain) < maxSequenceChain {
+		raw, err := readBoundedRegularFile(filepath.Join(dir, "state.md"), maxCandidateManifestBytes)
+		if err != nil {
+			return nil, nil, fmt.Errorf("%s state.md: %w", filepath.Base(dir), err)
+		}
+		parent, _ := state.CursorField(strings.Split(string(raw), "\n"), state.CursorSequenceParent)
+		if parent == "" {
+			break
+		}
+		if _, dup := visited[parent]; dup {
+			return nil, nil, fmt.Errorf("sequence_parent cycle at %q", parent)
+		}
+		visited[parent] = struct{}{}
+		rows, err := predecessorManifestRows(root, parent)
+		if err != nil {
+			return nil, nil, fmt.Errorf("sequence_parent %s: %w", parent, err)
+		}
+		dir, err = devritespaths.ExistingFeatureDirChecked(root, parent)
+		if errors.Is(err, os.ErrNotExist) {
+			dir, err = devritespaths.ExistingArchivedFeatureDirChecked(root, parent)
+		}
+		if err != nil {
+			return nil, nil, fmt.Errorf("sequence_parent %s: %w", parent, err)
+		}
+		chain = append(chain, parent)
+		manifests = append(manifests, rows)
+	}
+	if len(chain) == 0 {
+		return nil, nil, fmt.Errorf("%s has no sequence_parent; pass an explicit ordered predecessor list", slug)
+	}
+	for i, j := 0, len(chain)-1; i < j; i, j = i+1, j-1 {
+		chain[i], chain[j] = chain[j], chain[i]
+		manifests[i], manifests[j] = manifests[j], manifests[i]
+	}
+	return chain, manifests, nil
+}
+
+func sequenceParent(root, slug string) string {
+	dir, err := devritespaths.ExistingFeatureDirChecked(root, slug)
+	if err != nil {
+		return ""
+	}
+	raw, err := readBoundedRegularFile(filepath.Join(dir, "state.md"), maxCandidateManifestBytes)
+	if err != nil {
+		return ""
+	}
+	parent, _ := state.CursorField(strings.Split(string(raw), "\n"), state.CursorSequenceParent)
+	return parent
+}
+
+// VerifyReleaseUnion enforces the release-milestone contract at the candidate
+// and seal gates: a workspace whose cursor declares `sequence_role: release`
+// must carry a candidate manifest covering every predecessor in its recorded
+// `sequence_parent` chain. Workspaces without the role are unaffected.
+func VerifyReleaseUnion(root, slug string) error {
+	dir, err := devritespaths.ExistingFeatureDirChecked(root, slug)
+	if err != nil {
+		return fmt.Errorf("workspace for %s: %w", slug, err)
+	}
+	raw, err := readBoundedRegularFile(filepath.Join(dir, "state.md"), maxCandidateManifestBytes)
+	if errors.Is(err, os.ErrNotExist) {
+		return nil // no state.md: nothing declares the release role
+	}
+	if err != nil {
+		return fmt.Errorf("%s state.md: %w", slug, err)
+	}
+	role, _ := state.CursorField(strings.Split(string(raw), "\n"), state.CursorSequenceRole)
+	if role != "release" {
+		return nil
+	}
+	_, manifests, err := walkSequenceChain(root, slug, dir)
+	if err != nil {
+		return err
+	}
+	manifestRaw, err := readBoundedRegularFile(filepath.Join(dir, "touched-files.md"), maxCandidateManifestBytes)
+	if err != nil {
+		return fmt.Errorf("candidate manifest: %w", err)
+	}
+	rows, err := parseCandidateManifest(manifestRaw)
+	if err != nil {
+		return fmt.Errorf("candidate manifest: %w", err)
+	}
+	declared := make(map[string]struct{}, len(rows))
+	for _, row := range rows {
+		declared[row.path] = struct{}{}
+	}
+	var missing []string
+	for _, ancestor := range manifests {
+		for _, row := range ancestor {
+			if _, ok := declared[row.path]; !ok {
+				missing = append(missing, row.path)
+			}
+		}
+	}
+	if len(missing) > 0 {
+		sort.Strings(missing)
+		const show = 8
+		list := missing
+		if len(list) > show {
+			list = append(append([]string(nil), missing[:show]...), fmt.Sprintf("…and %d more", len(missing)-show))
+		}
+		return fmt.Errorf("release manifest does not cover the recorded sequence chain; run `devrites-engine state merge-manifest %s`. Missing: %s", slug, strings.Join(list, ", "))
+	}
+	return nil
+}
+
+// predecessorManifestRows loads the candidate manifest of a sealed or archived
+// predecessor workspace. Live workspaces win over archive entries so an
+// unshipped sequence member is always found first.
+func predecessorManifestRows(root, slug string) ([]candidateRow, error) {
+	dir, err := devritespaths.ExistingFeatureDirChecked(root, slug)
+	if errors.Is(err, os.ErrNotExist) {
+		dir, err = devritespaths.ExistingArchivedFeatureDirChecked(root, slug)
+	}
+	if err != nil {
+		return nil, fmt.Errorf("no live or archived workspace: %w", err)
+	}
+	raw, err := readBoundedRegularFile(filepath.Join(dir, "touched-files.md"), maxCandidateManifestBytes)
+	if err != nil {
+		return nil, fmt.Errorf("candidate manifest: %w", err)
+	}
+	rows, err := parseCandidateManifest(raw)
+	if err != nil {
+		return nil, fmt.Errorf("candidate manifest: %w", err)
+	}
+	return rows, nil
+}
+
+// replaceManifestSectionBody rewrites the body of the single
+// `## Candidate manifest` section, keeping every other byte of the file —
+// headings, `## Touched files` narrative, and `## Review trail` — intact.
+func replaceManifestSectionBody(raw []byte, body []string) ([]byte, error) {
+	text := string(raw)
+	crlf := strings.Contains(text, "\r\n")
+	lines := strings.Split(text, "\n")
+	start, count := -1, 0
+	for i, line := range lines {
+		if strings.TrimSpace(line) == "## Candidate manifest" {
+			start = i + 1
+			count++
+		}
+	}
+	if count != 1 {
+		return nil, errors.New("requires exactly one ## Candidate manifest section")
+	}
+	end := len(lines)
+	for i := start; i < len(lines); i++ {
+		if strings.HasPrefix(strings.TrimSpace(lines[i]), "## ") {
+			end = i
+			break
+		}
+	}
+	emitted := append([]string(nil), body...)
+	if crlf {
+		for i := range emitted {
+			emitted[i] += "\r"
+		}
+	}
+	if end < len(lines) {
+		emitted = append(emitted, "")
+		if crlf {
+			emitted[len(emitted)-1] = "\r"
+		}
+	}
+	lines = append(lines[:start], append(emitted, lines[end:]...)...)
+	return []byte(strings.Join(lines, "\n")), nil
+}