devrites 6.10.0 → 7.0.0

package/engine/internal/lib/next.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/devrites/devrites/internal/devritespaths"
 	"github.com/devrites/devrites/internal/markdowntext"
+	"github.com/devrites/devrites/internal/parallel"
 	"github.com/devrites/devrites/internal/state"
 	"github.com/devrites/devrites/internal/workflow"
 )
@@ -18,7 +19,8 @@ import (
 // RunNext prints the minimal remaining lifecycle path: the first phase whose
 // required artifacts are not all present, plus advisory skips for phases whose
 // remaining work is vacuous (e.g. clarify with zero open questions). Advisory
-// only — the rite still owns the decision to advance.
+// only — the rite still owns the decision to advance — except the root-edit
+// tripwire, which exits 3 while an unattributed product edit is in the tree.
 func RunNext(root string, args []string, stdout, stderr io.Writer) int {
 	slug, code, err := ActiveSlug(root, args)
 	if err != nil {
@@ -60,10 +62,24 @@ func RunNext(root string, args []string, stdout, stderr io.Writer) int {
 		fmt.Fprintln(stdout, "current-status: incomplete")
 	}
 	fmt.Fprintf(stdout, "open-questions: %d\n", openQuestions)
+	// The root-edit tripwire (ADR-0038) leads the output and exits 3; the rest
+	// still prints so the root sees where it resumes once the edit is routed.
+	exit := 0
+	if flagged, err := unattributedEdits(root, slug); err != nil {
+		fmt.Fprintf(stdout, "blocked: tree baseline: %v\n", err)
+		exit = 3
+	} else if len(flagged) > 0 {
+		recordUnattributed(root, slug, string(report.Phase), flagged)
+		fmt.Fprintf(stdout, "blocked: %s\n", unattributedMessage(slug, flagged))
+		exit = 3
+	}
+	if report.Phase == state.PhaseBuild {
+		printPlanBatch(stdout, root, slug)
+	}
 
 	if report.Phase == state.PhaseDone {
 		fmt.Fprintln(stdout, "next-phase: done")
-		return 0
+		return exit
 	}
 
 	// Walk from the current phase to the first incomplete one. Vacuous phases
@@ -74,7 +90,7 @@ func RunNext(root string, args []string, stdout, stderr io.Writer) int {
 		if policy.Target == state.PhaseDone {
 			fmt.Fprintln(stdout, "next-phase: done")
 			printSkips(stdout, skips)
-			return 0
+			return exit
 		}
 		var missing []string
 		if i == currentIdx {
@@ -106,11 +122,35 @@ func RunNext(root string, args []string, stdout, stderr io.Writer) int {
 			fmt.Fprintf(stdout, "missing: %s\n", strings.Join(missing, ","))
 		}
 		printSkips(stdout, skips)
-		return 0
+		return exit
 	}
 	fmt.Fprintln(stdout, "next-phase: done")
 	printSkips(stdout, skips)
-	return 0
+	return exit
+}
+
+// printPlanBatch prints the slices runnable now and the batch `parallel select
+// --from-plan` picks at the AFK max_parallel cap (else the maximum), with the
+// command itself. Advisory: an unreadable plan prints why, never an exit code.
+func printPlanBatch(stdout io.Writer, root, slug string) {
+	capN := afkMaxParallel(root)
+	if capN < 1 || capN > parallel.MaxParallelSlices {
+		capN = parallel.MaxParallelSlices
+	}
+	eligible, batch, err := planBatch(root, slug, capN)
+	if err != nil {
+		fmt.Fprintf(stdout, "batch: unavailable (%v)\n", err)
+		return
+	}
+	list := func(ids []string) string {
+		if len(ids) == 0 {
+			return "none"
+		}
+		return strings.Join(ids, ",")
+	}
+	fmt.Fprintf(stdout, "eligible_now: %s\n", list(eligible))
+	fmt.Fprintf(stdout, "batch: %s\n", list(batch))
+	fmt.Fprintf(stdout, "select-command: %s\n", planSelectCommand(filepath.Dir(root), slug, capN))
 }
 
 func renderNextCommand(policy state.PhasePolicy) string {

package/engine/internal/lib/observe_summary.go

@@ -157,13 +157,11 @@ func missingSectionNames(sections []state.Section) []string {
 	return out
 }
 
-// WriteObserveSummaryJSON prints one JSON object to stdout.
+// WriteObserveSummaryJSON prints one compact JSON object line to stdout.
 func WriteObserveSummaryJSON(root, slug string, stdout io.Writer) error {
 	summary, err := ObserveSummaryFor(root, slug)
 	if err != nil {
 		return err
 	}
-	enc := json.NewEncoder(stdout)
-	enc.SetIndent("", "  ")
-	return enc.Encode(summary)
+	return json.NewEncoder(stdout).Encode(summary)
 }

package/engine/internal/lib/packet.go

@@ -0,0 +1,319 @@
+package lib
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/devrites/devrites/internal/acceptance"
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/state"
+)
+
+// PacketUsage is the help and usage-error text for `packet`.
+const PacketUsage = `usage: devrites-engine packet <slug> --wave <w> --phase <p> --role <r> [--slice <SLICE-ID>] [--recheck] [--checks <G-ID,...>] [--focus <file>]
+
+Renders one role's by-reference dispatch packet and runs the lints dispatch
+open runs on it; a refused packet is removed and the command exits 3. A
+wright role (needs --slice and --checks) writes a same-worktree
+packets/<w>.contract.md with the slice's Writer allowlist and each --checks
+gates.md gate's CHECK, which must be an approved test-plan.md Build-entry
+preflight row; a native-worktree pilot keeps its own contract. A reviewer
+role (*-reviewer, *-auditor, test-analyst) writes packets/<w>.<role>.md with
+its Outcome/Counts return head. Read first names the role's context bundle
+(run context first; --recheck names the build --recheck bundle) and
+packets/<w>.diff when candidate freeze wrote one; Candidate copies
+packets/<w>.sha256 verbatim, or only its header rows when the per-file rows
+would overflow the packet (required at review and seal). --focus (relative
+to the workspace) holds one "- <ID> <path:line> <text>" row per line, text up
+to 240 characters, and any other non-blank line is refused: open findings
+for a reviewer, defects and quoted carry-forward constraints for a wright,
+and the 1-3 row claim a doubt-reviewer attacks (required for that role).
+`
+
+// focusRowRE is the only open-finding shape a packet carries: an ID, an
+// anchor, and a bounded defect statement, never narrative or outcomes.
+var focusRowRE = regexp.MustCompile(`^- [A-Za-z][A-Za-z0-9._-]{0,63} [^\s:]+(?::[0-9]+)+(?:-[0-9]+)? \S.{0,239}$`)
+
+// RunPacket implements `packet`: it renders the fixed skeleton so the root
+// never hand-writes packet prose, hashes, or IDs.
+func RunPacket(root string, args []string, stdout, stderr io.Writer) int {
+	var wave, phase, role, slice, checks, focus, recheck string
+	var positional []string
+	for i := 0; i < len(args); i++ {
+		value := argAt(args, i+1)
+		switch args[i] {
+		case "--recheck":
+			// Non-empty selects the .recheck bundle name; the text is the context hint.
+			recheck = " --recheck <inventory>"
+			continue
+		case "--wave":
+			wave = value
+		case "--phase":
+			phase = value
+		case "--role":
+			role = value
+		case "--slice":
+			slice = value
+		case "--checks":
+			checks = value
+		case "--focus":
+			focus = value
+		default:
+			if strings.HasPrefix(args[i], "-") {
+				fmt.Fprintf(stderr, "packet: unknown flag %q\n", args[i])
+				return 2
+			}
+			positional = append(positional, args[i])
+			continue
+		}
+		i++
+	}
+	wright := strings.Contains(role, "wright")
+	doubt := roleBase(role) == "doubt-reviewer"
+	if len(positional) != 1 || !packetNameRE.MatchString(wave) || !packetNameRE.MatchString(phase) || !packetNameRE.MatchString(role) ||
+		(slice != "" && !packetNameRE.MatchString(slice)) || (!wright && !isReviewerRole(role)) || (wright && slice == "") || (!wright && checks != "") ||
+		(recheck != "" && (phase != "build" || slice == "")) || (doubt && focus == "") {
+		fmt.Fprint(stderr, PacketUsage)
+		return 2
+	}
+	slug := positional[0]
+	fail := func(err error) int {
+		fmt.Fprintf(stderr, "packet: %v\n", err)
+		return 3
+	}
+	workspace, err := devritespaths.ExistingFeatureDirChecked(root, slug)
+	if err != nil {
+		return fail(err)
+	}
+	rel := workspaceRel(root, workspace)
+	bundle := "ctx/" + bundleName(contextOpts{phase: phase, role: role, slice: slice, recheck: recheck})
+	if info, err := os.Stat(filepath.Join(workspace, filepath.FromSlash(bundle))); err != nil || !info.Mode().IsRegular() {
+		scope := recheck
+		if slice != "" {
+			scope = " --slice " + slice + recheck
+		}
+		return fail(fmt.Errorf("%s/%s is missing; run devrites-engine context %s --phase %s --role %s%s first", rel, bundle, slug, phase, role, scope))
+	}
+	candidate, partial, err := frozenCandidate(workspace, wave)
+	if err != nil {
+		return fail(err)
+	}
+	finalPhase := strings.EqualFold(phase, "review") || strings.EqualFold(phase, "seal")
+	if candidate == "" && !wright && finalPhase {
+		return fail(fmt.Errorf("a %s reviewer packet needs a frozen candidate; run devrites-engine candidate freeze %s --wave %s first", phase, slug, wave))
+	}
+
+	var b strings.Builder
+	fmt.Fprintf(&b, "# Packet %s: %s\n\nFeature: %s\nPhase: %s\n", wave, role, slug, phase)
+	if slice != "" {
+		fmt.Fprintf(&b, "Slice: %s\n", slice)
+	}
+	if wright {
+		b.WriteString("Isolation: same-worktree\n")
+		b.WriteString("Authority: sole writer for this slice. Edit only the Allowlist paths; never edit .devrites/**, never commit or push, and ask the user nothing.\n")
+	} else {
+		b.WriteString("Authority: read-only reviewer. Edit nothing and ask the user nothing; judge the candidate against the bundle sources.\n")
+	}
+	fmt.Fprintf(&b, "\nRead first:\n- %s/%s\n", rel, bundle)
+	if candidate != "" {
+		fmt.Fprintf(&b, "- %s/packets/%s.diff\n", rel, wave)
+	}
+	if wright {
+		raw, err := readWorkspaceArtifact(root, slug, "tasks.md")
+		if err != nil {
+			return fail(err)
+		}
+		writes, _ := sliceWritePaths(raw, ParseTaskGraph(raw))
+		if len(writes[slice]) == 0 {
+			return fail(fmt.Errorf("slice %s names no Writer allowlist or Files likely touched in tasks.md", slice))
+		}
+		b.WriteString("\nAllowlist:\n")
+		for _, p := range writes[slice] {
+			fmt.Fprintf(&b, "- %s\n", p)
+		}
+		if checks != "" {
+			lines, err := writerSafeChecks(root, slug, checks)
+			if err != nil {
+				return fail(err)
+			}
+			b.WriteString("\n" + lines)
+		}
+	}
+	if candidate != "" {
+		source := "verbatim from"
+		if partial {
+			source = "header rows verbatim; per-file rows in"
+		}
+		fmt.Fprintf(&b, "\nCandidate (%s %s/packets/%s.sha256):\n```text\n%s```\n", source, rel, wave, candidate)
+	}
+	if focus != "" {
+		rows, err := focusRows(workspace, focus)
+		if err != nil {
+			return fail(err)
+		}
+		heading := "Open findings:"
+		switch {
+		case wright:
+			heading = "Focus (defects to fix, carry-forward constraints to honor):"
+		case doubt:
+			heading = "Claim to attack:"
+			if rows == "" || strings.Count(rows, "\n") > 3 {
+				return fail(fmt.Errorf("--focus %s must hold the 1-3 row claim the doubt-reviewer attacks", focus))
+			}
+		}
+		if rows != "" {
+			b.WriteString("\n" + heading + "\n" + rows)
+		}
+	}
+	if wright {
+		b.WriteString("\nReturn: every field of your role's return block, with each Writer-safe check's command and exit status.\n")
+	} else {
+		b.WriteString("\nReturn (lines 1-2 exactly, then your role's rows):\nOutcome: <findings|no-findings|gap>\nCounts:")
+		for _, key := range countKeys(role) {
+			fmt.Fprintf(&b, " %s=<n>", key)
+		}
+		b.WriteString("\n")
+	}
+
+	name := wave + "." + role + ".md"
+	if wright {
+		name = wave + ".contract.md"
+	}
+	out := filepath.Join(workspace, "packets", name)
+	if err := os.MkdirAll(filepath.Dir(out), 0o755); err != nil {
+		return fail(err)
+	}
+	// Lint a sibling draft so a refused re-render keeps the packet already on disk.
+	draft := filepath.Join(workspace, "packets", "."+name+".draft")
+	if err := state.AtomicWrite(draft, []byte(b.String()), 0o600); err != nil {
+		return fail(err)
+	}
+	if err := lintRenderedPacket(root, slug, draft, role, wright, finalPhase); err != nil {
+		_ = os.Remove(draft)
+		return fail(fmt.Errorf("BLOCKED: %w", err))
+	}
+	if err := os.Rename(draft, out); err != nil {
+		_ = os.Remove(draft)
+		return fail(err)
+	}
+	fmt.Fprintf(stdout, "packet: %s/packets/%s (%s, %d bytes)\n", rel, name, role, b.Len())
+	return 0
+}
+
+// lintRenderedPacket runs the lints dispatch open runs for the role; a wright
+// contract also gets the gates.md `RUN: writer` precheck lint.
+func lintRenderedPacket(root, slug, path, role string, wright, finalPhase bool) error {
+	if wright {
+		return lintWrightContractFor(root, slug, path)
+	}
+	if err := lintReviewerWavePacket(path, []string{role}); err != nil {
+		return err
+	}
+	if finalPhase {
+		return lintReviewCandidate(root, slug, path)
+	}
+	return nil
+}
+
+// frozenCandidate returns packets/<wave>.sha256 when candidate freeze wrote
+// both it and a non-empty diff, or "" when the wave has no frozen candidate.
+// partial reports that only the header rows were kept: the per-file rows of a
+// large candidate would push the packet past the dispatch lints' read bound.
+func frozenCandidate(workspace, wave string) (sums string, partial bool, err error) {
+	raw, err := readBoundedRegularFile(filepath.Join(workspace, "packets", wave+".sha256"), workspaceArtifactLimit)
+	if errors.Is(err, os.ErrNotExist) {
+		return "", false, nil
+	}
+	if err != nil {
+		return "", false, fmt.Errorf("packets/%s.sha256: %w", wave, err)
+	}
+	if info, err := os.Stat(filepath.Join(workspace, "packets", wave+".diff")); err != nil || !info.Mode().IsRegular() || info.Size() == 0 {
+		return "", false, fmt.Errorf("packets/%s.sha256 has no non-empty packets/%s.diff beside it; rerun candidate freeze under a new wave", wave, wave)
+	}
+	if len(raw) <= maxContractBytes/2 {
+		return string(raw), false, nil
+	}
+	var head strings.Builder
+	for _, line := range strings.SplitAfter(string(raw), "\n") {
+		if !strings.HasPrefix(line, "file ") {
+			head.WriteString(line)
+		}
+	}
+	return head.String(), true, nil
+}
+
+// writerSafeChecks resolves each named gates.md gate to its CHECK, refusing an
+// unknown gate or a CHECK no approved test-plan.md preflight row vets, and adds
+// `gates precheck` when the ledger marks a gate `RUN: writer`.
+func writerSafeChecks(root, slug, ids string) (string, error) {
+	ledger, err := readWorkspaceArtifact(root, slug, acceptance.GatesFile)
+	if err != nil {
+		return "", fmt.Errorf("--checks: %w", err)
+	}
+	plan, err := readWorkspaceArtifact(root, slug, "test-plan.md")
+	if err != nil {
+		return "", fmt.Errorf("--checks: %w", err)
+	}
+	doc := acceptance.ParseLedger(string(ledger))
+	approved := acceptance.ApprovedCommands(plan)
+	var names []string
+	var rows strings.Builder
+	for _, id := range strings.Split(ids, ",") {
+		id = strings.TrimSpace(id)
+		var gate *acceptance.Gate
+		for _, g := range doc.Gates {
+			if g.ID == id {
+				gate = g
+				break
+			}
+		}
+		switch {
+		case gate == nil:
+			return "", fmt.Errorf("--checks: gate %q is not in %s", id, acceptance.GatesFile)
+		case gate.Check == "":
+			return "", fmt.Errorf("--checks: gate %s has no CHECK", id)
+		case !acceptance.Approved(gate.Check, gate.Cwd, approved):
+			return "", fmt.Errorf("--checks: gate %s CHECK is not an approved test-plan.md Build-entry preflight row", id)
+		}
+		names = append(names, id)
+		cwd := gate.Cwd
+		if cwd == "" {
+			cwd = "repository root"
+		}
+		fmt.Fprintf(&rows, "- %s (cwd %s): `%s`\n", id, cwd, gate.Check)
+	}
+	if len(doc.WriterGates()) > 0 {
+		fmt.Fprintf(&rows, "- gates precheck (cwd repository root): `devrites-engine gates precheck %s --worktree .`\n", slug)
+	}
+	return "Writer-safe checks: " + strings.Join(names, ", ") + "\n" + rows.String(), nil
+}
+
+// focusRows reads the --focus file (relative to the workspace) and returns its
+// open-finding rows, refusing any non-blank line of another shape.
+func focusRows(workspace, focus string) (string, error) {
+	path := focus
+	if !filepath.IsAbs(path) {
+		path = filepath.Join(workspace, filepath.FromSlash(focus))
+	}
+	raw, err := readBoundedRegularFile(path, maxContractBytes)
+	if err != nil {
+		return "", fmt.Errorf("--focus %s: %w", focus, err)
+	}
+	var rows strings.Builder
+	for i, line := range strings.Split(string(raw), "\n") {
+		line = strings.TrimRight(line, "\r")
+		if strings.TrimSpace(line) == "" {
+			continue
+		}
+		if !focusRowRE.MatchString(line) {
+			return "", fmt.Errorf("--focus %s:%d is not an open-finding row \"- <finding-ID> <path:line> <text up to 240 characters>\"; a packet carries open findings only, never narrative or outcomes", focus, i+1)
+		}
+		rows.WriteString(line + "\n")
+	}
+	return rows.String(), nil
+}

package/engine/internal/lib/packet_freeze.go

@@ -0,0 +1,227 @@
+package lib
+
+import (
+	"crypto/sha256"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/state"
+)
+
+// CandidateFreezeUsage is the help and usage-error text for `candidate freeze`.
+const CandidateFreezeUsage = `usage: devrites-engine candidate freeze <slug> --wave <w> (--slice <SLICE-ID> | --paths <path>...) [--base <ref>]
+
+Freezes one review candidate. It writes packets/<w>.diff (the path set's
+tracked changes against --base, default HEAD, plus each untracked file as a
+/dev/null diff) and packets/<w>.sha256 (base commit, diff digest, per-file
+sha256, and the aggregate candidate digest under the check candidate domain
+and bounds). --slice takes that slice's Writer allowlist (else Files likely
+touched) from tasks.md. A wave's frozen candidate is never replaced by a
+different one; freeze a changed candidate under a new wave.
+`
+
+// packetNameRE bounds a wave, role, phase, or slice used in a packets/ or
+// ctx/ file name: one path component, no traversal.
+var packetNameRE = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`)
+
+// RunCandidateFreeze implements `candidate freeze`: the producer of the frozen
+// .diff a Review or Seal reviewer packet must name.
+func RunCandidateFreeze(root string, args []string, stdout, stderr io.Writer) int {
+	var wave, slice, base string
+	var paths, positional []string
+	for i := 0; i < len(args); i++ {
+		value := argAt(args, i+1)
+		switch args[i] {
+		case "--wave":
+			wave = value
+		case "--slice":
+			slice = value
+		case "--base":
+			base = value
+		case "--paths":
+			for i+1 < len(args) && !strings.HasPrefix(args[i+1], "-") {
+				i++
+				paths = append(paths, args[i])
+			}
+			continue
+		default:
+			if strings.HasPrefix(args[i], "-") {
+				fmt.Fprintf(stderr, "candidate freeze: unknown flag %q\n", args[i])
+				return 2
+			}
+			positional = append(positional, args[i])
+			continue
+		}
+		i++
+	}
+	if len(positional) != 1 || !packetNameRE.MatchString(wave) || (slice == "") == (len(paths) == 0) {
+		fmt.Fprint(stderr, CandidateFreezeUsage)
+		return 2
+	}
+	slug := positional[0]
+	fail := func(err error) int {
+		fmt.Fprintf(stderr, "candidate freeze: %v\n", err)
+		return 3
+	}
+	workspace, err := devritespaths.ExistingFeatureDirChecked(root, slug)
+	if err != nil {
+		return fail(err)
+	}
+	if slice != "" {
+		raw, err := readWorkspaceArtifact(root, slug, "tasks.md")
+		if err != nil {
+			return fail(err)
+		}
+		writes, _ := sliceWritePaths(raw, ParseTaskGraph(raw))
+		if paths = writes[slice]; len(paths) == 0 {
+			return fail(fmt.Errorf("slice %s names no Writer allowlist or Files likely touched in tasks.md", slice))
+		}
+	}
+	project := projectDir(root)
+	rows, err := freezeRows(project, paths)
+	if err != nil {
+		return fail(err)
+	}
+	if err := validateCandidateRows(project, rows); err != nil {
+		return fail(err)
+	}
+	diff, baseCommit, err := freezeDiff(project, base, rows)
+	if err != nil {
+		return fail(err)
+	}
+	if len(diff) == 0 {
+		return fail(errors.New("the path set has no change against the base; there is no candidate to freeze"))
+	}
+	digest, err := hashCandidate(project, rows)
+	if err != nil {
+		return fail(err)
+	}
+	var sums strings.Builder
+	fmt.Fprintf(&sums, "%s %s\nbase %s\ndiff %x packets/%s.diff\n", candidateDigestDomain, candidateDigestVersion, baseCommit, sha256.Sum256(diff), wave)
+	for _, row := range rows {
+		if row.state != "present" {
+			fmt.Fprintf(&sums, "file absent %s\n", row.path)
+			continue
+		}
+		file := sha256.New()
+		if err := hashCandidateFile(file, project, row); err != nil {
+			return fail(fmt.Errorf("candidate %q: %w", row.path, err))
+		}
+		fmt.Fprintf(&sums, "file %x %s\n", file.Sum(nil), row.path)
+	}
+	fmt.Fprintf(&sums, "aggregate %s\n", digest)
+
+	dir := filepath.Join(workspace, "packets")
+	diffPath, sumPath := filepath.Join(dir, wave+".diff"), filepath.Join(dir, wave+".sha256")
+	if prev, err := readBoundedRegularFile(sumPath, workspaceArtifactLimit); err == nil && string(prev) != sums.String() {
+		return fail(fmt.Errorf("packets/%s.sha256 already freezes a different candidate; a frozen candidate is never replaced, so freeze this one under a new wave", wave))
+	} else if err != nil && !errors.Is(err, os.ErrNotExist) {
+		return fail(err)
+	}
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return fail(err)
+	}
+	if err := state.AtomicWrite(diffPath, diff, 0o600); err != nil {
+		return fail(err)
+	}
+	if err := state.AtomicWrite(sumPath, []byte(sums.String()), 0o600); err != nil {
+		return fail(err)
+	}
+	rel := workspaceRel(root, workspace)
+	fmt.Fprintf(stdout, "candidate: %s (%d paths, base %s)\ndiff: %s/packets/%s.diff\nsha256: %s/packets/%s.sha256\n", digest, len(rows), baseCommit, rel, wave, rel, wave)
+	return 0
+}
+
+// freezeRows normalizes, deduplicates, and sorts the path set, marking each
+// row present or deleted (absent) as hashCandidate expects.
+func freezeRows(project string, paths []string) ([]candidateRow, error) {
+	seen := map[string]bool{}
+	var rows []candidateRow
+	for _, p := range paths {
+		name, err := normalizeCandidatePath(p)
+		if err != nil {
+			return nil, fmt.Errorf("path %q: %w", p, err)
+		}
+		if seen[name] {
+			continue
+		}
+		seen[name] = true
+		_, exists, err := candidatePathInfo(project, name)
+		if err != nil {
+			return nil, fmt.Errorf("candidate %q: %w", name, err)
+		}
+		row := candidateRow{state: "deleted", path: name}
+		if exists {
+			row.state = "present"
+		}
+		rows = append(rows, row)
+	}
+	if len(rows) > maxCandidateRows {
+		return nil, errors.New("path set exceeds 4096 rows")
+	}
+	sort.Slice(rows, func(i, j int) bool { return rows[i].path < rows[j].path })
+	return rows, nil
+}
+
+// freezeDiff renders the path set's tracked changes against base, then each
+// untracked file as a /dev/null diff, with fixed prefixes so git apply takes it
+// whatever the user's diff config.
+func freezeDiff(project, base string, rows []candidateRow) ([]byte, string, error) {
+	if base == "" {
+		base = "HEAD"
+	}
+	if strings.HasPrefix(base, "-") {
+		return nil, "", fmt.Errorf("--base %q is not a revision", base)
+	}
+	out, err := runGitCommand(project, nil, "rev-parse", "--verify", "--quiet", base+"^{commit}")
+	if err != nil {
+		return nil, "", fmt.Errorf("--base %q is not a commit: %w", base, err)
+	}
+	commit := strings.TrimSpace(string(out))
+	names := make([]string, len(rows))
+	for i, row := range rows {
+		names[i] = row.path
+	}
+	flags := []string{"--binary", "--no-color", "--no-ext-diff", "--no-textconv", "--no-renames", "--src-prefix=a/", "--dst-prefix=b/"}
+	diff, err := runGitCommand(project, nil, append(append(append([]string{"--literal-pathspecs", "diff"}, flags...), "--relative", commit, "--"), names...)...)
+	if err != nil {
+		return nil, "", err
+	}
+	diff = append([]byte(nil), diff...)
+	untracked, err := runGitCommand(project, nil, append([]string{"--literal-pathspecs", "ls-files", "--others", "-z", "--"}, names...)...)
+	if err != nil {
+		return nil, "", err
+	}
+	for _, name := range strings.Split(string(untracked), "\x00") {
+		if name == "" {
+			continue
+		}
+		var part cappedGitOutput
+		_, err := runGitCommandIO(project, nil, nil, &part, append(append([]string{"diff", "--no-index"}, flags...), "--", "/dev/null", name)...)
+		var gitErr *gitCommandError
+		if err != nil && !(errors.As(err, &gitErr) && gitErr.exitCode == 1) {
+			return nil, "", err // --no-index exits 1 when the files differ
+		}
+		if part.truncated || len(diff)+part.Len() > gitOutputLimit {
+			return nil, "", errors.New("candidate diff exceeds the git output limit")
+		}
+		diff = append(diff, part.Bytes()...)
+	}
+	return diff, commit, nil
+}
+
+// workspaceRel is the feature workspace as a slash path relative to the
+// project, the form packets hand agents; it falls back to the absolute path.
+func workspaceRel(root, workspace string) string {
+	if rel, err := filepath.Rel(projectDir(root), workspace); err == nil {
+		return filepath.ToSlash(rel)
+	}
+	return filepath.ToSlash(workspace)
+}