devrites 4.6.0 → 5.0.0

package/engine/internal/markdowntext/markdowntext_fuzz_test.go

@@ -0,0 +1,36 @@
+package markdowntext
+
+import (
+	"bytes"
+	"testing"
+	"unicode/utf8"
+)
+
+func FuzzStructural(f *testing.F) {
+	f.Add([]byte("# Title\n\n```go\nfmt.Println()\n```\n"))
+	f.Add([]byte("~~~\nunclosed fence\n"))
+	f.Add([]byte("   ```\n  ~~~\n"))
+	f.Add([]byte("code ``` inline\n| not | a | fence |\n"))
+	f.Add([]byte("line\r\nwith\r\ncrlf\r\n"))
+	f.Add([]byte("\xff\xfe invalid utf8 \x00"))
+	f.Add([]byte(""))
+	f.Fuzz(func(t *testing.T, input []byte) {
+		out, err := Structural(input)
+		if err != nil {
+			if utf8.Valid(input) && bytes.IndexByte(input, 0) < 0 {
+				t.Fatalf("Structural rejected input without malformed UTF-8 or NUL: %v", err)
+			}
+			return
+		}
+		if len(out) != len(input) {
+			t.Fatalf("Structural changed length: %d -> %d", len(input), len(out))
+		}
+		if !utf8.Valid(out) {
+			t.Fatal("Structural emitted invalid UTF-8")
+		}
+		stable, err := Structural(out)
+		if err != nil || !bytes.Equal(stable, out) {
+			t.Fatal("Structural is not idempotent")
+		}
+	})
+}

package/engine/internal/parallel/cli.go

@@ -225,6 +225,7 @@ func readJSONInput(path string, stdin io.Reader) ([]byte, error) {
 	if strings.Contains(path, "..") {
 		return nil, fmt.Errorf("json path must not contain '..'")
 	}
+	// #nosec G304 -- path traversal refused just above
 	return os.ReadFile(path)
 }
 

package/engine/internal/parallel/git.go

@@ -18,6 +18,7 @@ const gitTimeout = 60 * time.Second
 func git(repo string, args ...string) (string, error) {
 	ctx, cancel := context.WithTimeout(context.Background(), gitTimeout)
 	defer cancel()
+	// #nosec G204 -- git -C <worktree>; fixed binary, sanitized env
 	cmd := exec.CommandContext(ctx, "git", append([]string{"-C", repo}, args...)...)
 	env := append(gitenv.Sanitize(os.Environ()),
 		"GIT_TERMINAL_PROMPT=0",

package/engine/internal/parallel/lease.go

@@ -213,6 +213,7 @@ func WriteLease(path string, lease *Lease) error {
 }
 
 func ReadLease(path string) (*Lease, error) {
+	// #nosec G304 -- lease file under the engine-managed work dir
 	data, err := os.ReadFile(path)
 	if err != nil {
 		return nil, err

package/engine/internal/parallel/ops.go

@@ -9,6 +9,16 @@ import (
 	"strings"
 )
 
+// Test seams: indirection over the real primitives so discriminating tests
+// can inject transient failures without touching the filesystem.
+var (
+	writeLease     = WriteLease
+	removeWorktree = worktreeRemove
+	warnf          = func(format string, args ...any) {
+		fmt.Fprintf(os.Stderr, "warning: parallel: "+format+"\n", args...)
+	}
+)
+
 // CreateOpts configures parallel worktree creation.
 type CreateOpts struct {
 	Root    string
@@ -54,13 +64,16 @@ func Create(opts CreateOpts) (*Lease, error) {
 	createdBranches := make([]string, 0, len(opts.Slices))
 	cleanupPartial := func() {
 		for _, p := range createdPaths {
-			_ = worktreeRemove(opts.Root, p)
+			if err := removeWorktree(opts.Root, p); err != nil {
+				warnf("worktree cleanup %s: %v", p, err)
+			}
 		}
 		for _, b := range createdBranches {
-			_ = deleteBranch(opts.Root, b)
+			if err := deleteBranch(opts.Root, b); err != nil {
+				warnf("branch cleanup %s: %v", b, err)
+			}
 		}
 	}
-
 	slices := make([]LeaseSlice, 0, len(opts.Slices))
 	for _, sp := range opts.Slices {
 		if err := validateSliceID(sp.ID); err != nil {
@@ -252,12 +265,28 @@ func Integrate(opts IntegrateOpts) (tip string, lease *Lease, err error) {
 	}
 
 	fail := func(reason error) (string, *Lease, error) {
-		_ = worktreeRemove(opts.Root, stageWT)
-		_ = deleteBranch(opts.Root, ibranch)
-		_, _ = git(opts.Root, "worktree", "prune")
+		if err := removeWorktree(opts.Root, stageWT); err != nil {
+			warnf("staging worktree cleanup: %v", err)
+		}
+		if err := deleteBranch(opts.Root, ibranch); err != nil {
+			warnf("integrate branch cleanup: %v", err)
+		}
+		if _, err := git(opts.Root, "worktree", "prune"); err != nil {
+			warnf("worktree prune: %v", err)
+		}
 		lease.Status = StatusIntegrateFailed
-		_ = WriteLease(leasePath, lease)
-		_ = ensureControlAtBase(opts.Root, base, true)
+		if err := writeLease(leasePath, lease); err != nil {
+			// The integrate-failed transition must survive a transient write
+			// failure: a stale running lease still blocks create and stays
+			// retryable, but the honest state must be recorded when possible.
+			if retryErr := writeLease(leasePath, lease); retryErr != nil {
+				warnf("lease %s still status=%s (write failed twice: %v)",
+					leasePath, StatusRunning, retryErr)
+			}
+		}
+		if err := ensureControlAtBase(opts.Root, base, true); err != nil {
+			warnf("control reset to base: %v", err)
+		}
 		return "", lease, reason
 	}
 
@@ -313,8 +342,18 @@ func Integrate(opts IntegrateOpts) (tip string, lease *Lease, err error) {
 	if err != nil {
 		return fail(err)
 	}
-	_ = worktreeRemove(opts.Root, stageWT)
-	_, _ = git(opts.Root, "worktree", "prune")
+	if err := removeWorktree(opts.Root, stageWT); err != nil {
+		if _, statErr := os.Stat(stageWT); statErr == nil {
+			// The directory is genuinely stuck; failing now keeps the lease in
+			// integrate-failed and avoids compounding into un-cleanable branch
+			// state. Retrying integrate re-attempts the same removals.
+			return fail(fmt.Errorf("staging worktree could not be removed; retry integrate after cleanup: %w", err))
+		}
+		warnf("staging worktree cleanup: %v", err)
+	}
+	if _, err := git(opts.Root, "worktree", "prune"); err != nil {
+		warnf("worktree prune: %v", err)
+	}
 
 	if opts.ApplyToControl {
 		if err := mergeFFOnly(opts.Root, tip); err != nil {
@@ -361,17 +400,29 @@ func Cleanup(repoRoot, slug string, force bool) error {
 	}
 	for _, sl := range lease.Slices {
 		if sl.WorktreePath != "" {
-			_ = worktreeRemove(repoRoot, sl.WorktreePath)
-			_ = os.RemoveAll(sl.WorktreePath)
+			if err := removeWorktree(repoRoot, sl.WorktreePath); err != nil {
+				warnf("worktree cleanup %s: %v", sl.WorktreePath, err)
+			}
+			if err := os.RemoveAll(sl.WorktreePath); err != nil {
+				warnf("worktree dir cleanup %s: %v", sl.WorktreePath, err)
+			}
 		}
 		if sl.Branch != "" {
-			_ = deleteBranch(repoRoot, sl.Branch)
+			if err := deleteBranch(repoRoot, sl.Branch); err != nil {
+				warnf("branch cleanup %s: %v", sl.Branch, err)
+			}
 		}
 	}
 	ibranch := IntegrateBranchName(slug, lease.BatchID)
-	_ = deleteBranch(repoRoot, ibranch)
-	_ = os.RemoveAll(filepath.Join(ScratchRoot(repoRoot), lease.BatchID))
-	_, _ = git(repoRoot, "worktree", "prune")
+	if err := deleteBranch(repoRoot, ibranch); err != nil {
+		warnf("integrate branch cleanup %s: %v", ibranch, err)
+	}
+	if err := os.RemoveAll(filepath.Join(ScratchRoot(repoRoot), lease.BatchID)); err != nil {
+		warnf("scratch cleanup: %v", err)
+	}
+	if _, err := git(repoRoot, "worktree", "prune"); err != nil {
+		warnf("worktree prune: %v", err)
+	}
 	return ClearLease(leasePath)
 }
 

package/engine/internal/parallel/ops_test.go

@@ -0,0 +1,211 @@
+package parallel
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// commitIn makes a one-file green commit inside a worker worktree and returns
+// its transfer commit SHA.
+func commitIn(t *testing.T, wt, file, marker string) string {
+	t.Helper()
+	body := "package main\n\nfunc " + marker + "() {}\n"
+	if err := os.WriteFile(filepath.Join(wt, file), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	gitOk(t, wt, "add", file)
+	gitOk(t, wt, "commit", "-m", "slice "+marker)
+	return gitOk(t, wt, "rev-parse", "HEAD")
+}
+
+// greenBatch creates a running lease with two recorded-green slices.
+func greenBatch(t *testing.T, repo, base, slug, batch string) *Lease {
+	t.Helper()
+	lease, err := Create(CreateOpts{
+		Root:    repo,
+		Slug:    slug,
+		BatchID: batch,
+		BaseSHA: base,
+		Slices: []SlicePaths{
+			{ID: "slice-a", Paths: []string{"src/a.go"}},
+			{ID: "slice-b", Paths: []string{"src/b.go"}},
+		},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	tcA := commitIn(t, lease.Slices[0].WorktreePath, "src/a.go", "A")
+	tcB := commitIn(t, lease.Slices[1].WorktreePath, "src/b.go", "B")
+	if _, err := RecordGreen(repo, slug, "slice-a", tcA); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := RecordGreen(repo, slug, "slice-b", tcB); err != nil {
+		t.Fatal(err)
+	}
+	return lease
+}
+
+type seamRestore struct {
+	origLease  func(string, *Lease) error
+	origRemove func(string, string) error
+	origWarn   func(string, ...any)
+}
+
+func swapSeams(t *testing.T) {
+	t.Helper()
+	s := seamRestore{origLease: writeLease, origRemove: removeWorktree, origWarn: warnf}
+	t.Cleanup(func() { writeLease, removeWorktree, warnf = s.origLease, s.origRemove, s.origWarn })
+}
+
+// TestIntegrateFailedTransitionSurvivesTransientWriteFailure proves the
+// integrate-failed lease transition is retried once when the first write
+// fails, so the on-disk lease honestly records integrate-failed instead of a
+// stale running status.
+func TestIntegrateFailedTransitionSurvivesTransientWriteFailure(t *testing.T) {
+	repo, base := setupRepo(t)
+	slug, batch := "demo-feature", "batch1"
+	greenBatch(t, repo, base, slug, batch)
+	leasePath, err := LeasePath(repo, slug)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Corrupt a transfer commit so Integrate fails mid-flight via fail().
+	corrupted, err := ReadLease(leasePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	corrupted.Slices[0].TransferCommit = strings.Repeat("deadbeef", 5)
+	if err := WriteLease(leasePath, corrupted); err != nil {
+		t.Fatal(err)
+	}
+
+	swapSeams(t)
+	calls := 0
+	writeLease = func(path string, l *Lease) error {
+		calls++
+		if calls == 1 {
+			return errors.New("transient lease write failure")
+		}
+		// delegates to the real WriteLease captured by swapSeams
+		return origWriteLease()(path, l)
+	}
+
+	_, got, err := Integrate(IntegrateOpts{Root: repo, Slug: slug, ApplyToControl: true})
+	if err == nil {
+		t.Fatal("expected integrate failure from corrupted transfer commit")
+	}
+	if calls != 2 {
+		t.Fatalf("lease write calls=%d want 2 (initial + one retry)", calls)
+	}
+	if got == nil || got.Status != StatusIntegrateFailed {
+		t.Fatalf("returned lease status=%v want integrate-failed", got)
+	}
+	onDisk, err := ReadLease(leasePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if onDisk.Status != StatusIntegrateFailed {
+		t.Fatalf("on-disk lease status=%s want integrate-failed", onDisk.Status)
+	}
+	if head := gitOk(t, repo, "rev-parse", "HEAD"); head != base {
+		t.Fatalf("control head %s want base %s", head, base)
+	}
+}
+
+// origWriteLease returns the real WriteLease bypassing any test override.
+func origWriteLease() func(string, *Lease) error {
+	return WriteLease
+}
+
+// TestIntegrateSurfacesStuckStagingWorktree proves a staging-worktree removal
+// failure on the integrate success path is propagated (fail closed, status
+// integrate-failed, control untouched) instead of silently compounding into
+// un-cleanable branch state.
+func TestIntegrateSurfacesStuckStagingWorktree(t *testing.T) {
+	repo, base := setupRepo(t)
+	slug, batch := "demo-feature", "batch1"
+	greenBatch(t, repo, base, slug, batch)
+	leasePath, err := LeasePath(repo, slug)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	swapSeams(t)
+	removeWorktree = func(string, string) error {
+		return errors.New("simulated locked staging worktree")
+	}
+
+	_, got, err := Integrate(IntegrateOpts{Root: repo, Slug: slug, ApplyToControl: true})
+	if err == nil {
+		t.Fatal("expected integrate to surface the stuck staging worktree")
+	}
+	if !strings.Contains(err.Error(), "staging worktree") {
+		t.Fatalf("error should name the staging worktree, got %v", err)
+	}
+	if got == nil || got.Status != StatusIntegrateFailed {
+		t.Fatalf("returned lease status=%v want integrate-failed", got)
+	}
+	onDisk, err := ReadLease(leasePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if onDisk.Status != StatusIntegrateFailed {
+		t.Fatalf("on-disk lease status=%s want integrate-failed", onDisk.Status)
+	}
+	if head := gitOk(t, repo, "rev-parse", "HEAD"); head != base {
+		t.Fatalf("control head %s want base %s (merge must not apply when staging cleanup fails)", head, base)
+	}
+}
+
+// TestCleanupWarnsOnFailedBranchCleanup proves Cleanup reports branch cleanup
+// failures instead of erasing the lease while orphans remain.
+func TestCleanupWarnsOnFailedBranchCleanup(t *testing.T) {
+	repo, base := setupRepo(t)
+	slug, batch := "demo-feature", "batch1"
+	lease, err := Create(CreateOpts{
+		Root:    repo,
+		Slug:    slug,
+		BatchID: batch,
+		BaseSHA: base,
+		Slices: []SlicePaths{
+			{ID: "slice-a", Paths: []string{"src/a.go"}},
+			{ID: "slice-b", Paths: []string{"src/b.go"}},
+		},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	branchA := lease.Slices[0].Branch
+
+	swapSeams(t)
+	// Removal "fails" without removing; Cleanup's own RemoveAll then deletes
+	// the worktree directory while the stale git registration still lists the
+	// branch as checked out, so deleteBranch refuses and must be reported.
+	removeWorktree = func(string, string) error {
+		return errors.New("simulated stuck worker worktree")
+	}
+	var warnings []string
+	warnf = func(format string, args ...any) {
+		warnings = append(warnings, fmt.Sprintf(format, args...))
+	}
+
+	if err := Cleanup(repo, slug, true); err != nil {
+		t.Fatalf("cleanup continues after reporting failures: %v", err)
+	}
+	joined := strings.Join(warnings, "\n")
+	if !strings.Contains(joined, branchA) {
+		t.Fatalf("warnings should name the stuck branch %s, got:\n%s", branchA, joined)
+	}
+	leasePath, err := LeasePath(repo, slug)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(leasePath); !os.IsNotExist(err) {
+		t.Fatalf("cleanup should still clear the lease, got %v", err)
+	}
+}

package/engine/internal/parallel/pathdisjoint.go

@@ -32,6 +32,12 @@ func NormalizePath(raw string) (string, error) {
 	}
 	parts := make([]string, 0, strings.Count(path, "/")+1)
 	for part := range strings.SplitSeq(path, "/") {
+		// Edge whitespace on a segment would survive segment filtering and
+		// make normalization non-idempotent ("0\n." collapsing to "0\n"),
+		// so reject it outright like the other malformed shapes.
+		if trimmed := strings.TrimSpace(part); trimmed != part {
+			return "", fmt.Errorf("path segment must not have leading or trailing whitespace: %q", raw)
+		}
 		if part == "" || part == "." {
 			continue
 		}

package/engine/internal/parallel/pathdisjoint_fuzz_test.go

@@ -0,0 +1,43 @@
+package parallel
+
+import (
+	"strings"
+	"testing"
+)
+
+func FuzzPathDisjoint(f *testing.F) {
+	f.Add("src/a.go", []byte(`{"slices":[{"id":"a","paths":["src/a.go"]},{"id":"b","paths":["src/b.go"]}]}`))
+	f.Add("../escape", []byte(`[{"id":"a","paths":["/abs"]},{"id":"b","paths":[".devrites/state.md"]}]`))
+	f.Add("src\\windows.go", []byte(`{"slices":[{"id":"a","paths":["src", "src"]}]}`))
+	f.Add("src//double/", []byte(`not json`))
+	f.Add(".devrites", []byte(`{"slices":[]}`))
+	f.Fuzz(func(t *testing.T, raw string, doc []byte) {
+		normalized, err := NormalizePath(raw)
+		if err == nil {
+			if normalized == "" || strings.HasPrefix(normalized, "/") || strings.Contains(normalized, "\\") {
+				t.Fatalf("NormalizePath accepted %q into %q", raw, normalized)
+			}
+			for _, part := range strings.Split(normalized, "/") {
+				if part == "" || part == "." || part == ".." {
+					t.Fatalf("NormalizePath accepted %q into %q with bad segment %q", raw, normalized, part)
+				}
+			}
+			again, err := NormalizePath(normalized)
+			if err != nil || again != normalized {
+				t.Fatalf("NormalizePath not idempotent: %q -> %q (err %v)", normalized, again, err)
+			}
+		}
+
+		slices, err := ParseSlicesJSON(doc)
+		if err != nil {
+			return
+		}
+		ids, err := CheckPathDisjoint(slices, "")
+		if err != nil {
+			return
+		}
+		if len(ids) != len(slices) {
+			t.Fatalf("CheckPathDisjoint returned %d ids for %d slices", len(ids), len(slices))
+		}
+	})
+}

package/engine/internal/parallel/pathdisjoint_test.go

@@ -9,7 +9,10 @@ import (
 
 func TestNormalizePathRejectsDirty(t *testing.T) {
 	t.Parallel()
-	cases := []string{"", " ", "/", "/abs", `C:\windows`, `..`, "a/../b", "../x"}
+	cases := []string{"", " ", "/", "/abs", `C:\windows`, `..`, "a/../b", "../x",
+		// Segment-edge whitespace previously survived normalization
+		// ("0 /." collapsed to "0 "), making the mapping non-idempotent.
+		"0 /.", "src /a.go", "./ \n/x"}
 	for _, raw := range cases {
 		if _, err := NormalizePath(raw); err == nil {
 			t.Fatalf("NormalizePath(%q) should fail", raw)

package/engine/internal/parallel/testdata/fuzz/FuzzPathDisjoint/a449b81b4711b7b4

@@ -0,0 +1,3 @@
+go test fuzz v1
+string("0 /")
+[]byte("0")

package/engine/internal/release/release.go

@@ -164,7 +164,7 @@ func fetchJSON(ctx context.Context, rawURL string, out any) error {
 	if err != nil {
 		return err
 	}
-	defer resp.Body.Close()
+	defer func() { _ = resp.Body.Close() }()
 	if resp.StatusCode < 200 || resp.StatusCode > 299 {
 		return fmt.Errorf("%s returned %s", resp.Request.URL.Redacted(), resp.Status)
 	}
@@ -192,6 +192,7 @@ func downloadVerified(ctx context.Context, rawURL, destination, filename string,
 	if err := download(ctx, rawURL+".sha256", sumPath, maxChecksumBytes, 0o600); err != nil {
 		return fmt.Errorf("missing checksum for %s: %w", filename, err)
 	}
+	// #nosec G304 -- checksum downloaded into the self-update temp dir
 	sum, err := os.ReadFile(sumPath)
 	if err != nil {
 		return fmt.Errorf("read checksum for %s: %w", filename, err)
@@ -204,6 +205,7 @@ func downloadVerified(ctx context.Context, rawURL, destination, filename string,
 	if err != nil || len(want) != sha256.Size {
 		return fmt.Errorf("invalid SHA-256 for %s", filename)
 	}
+	// #nosec G304 -- downloaded release asset in the self-update temp dir
 	file, err := os.Open(destination)
 	if err != nil {
 		return fmt.Errorf("open %s for checksum: %w", filename, err)
@@ -228,7 +230,7 @@ func download(ctx context.Context, rawURL, destination string, maxBytes int64, m
 	if err != nil {
 		return err
 	}
-	defer resp.Body.Close()
+	defer func() { _ = resp.Body.Close() }()
 	if resp.StatusCode < 200 || resp.StatusCode > 299 {
 		return fmt.Errorf("%s returned %s", resp.Request.URL.Redacted(), resp.Status)
 	}
@@ -338,16 +340,17 @@ func extractBundle(archive, destination, tag string) (string, error) {
 }
 
 func extractTarGz(archive, destination string) error {
+	// #nosec G304 -- downloaded release archive in the self-update temp dir
 	file, err := os.Open(archive)
 	if err != nil {
 		return fmt.Errorf("open archive: %w", err)
 	}
-	defer file.Close()
+	defer func() { _ = file.Close() }()
 	gz, err := gzip.NewReader(file)
 	if err != nil {
 		return fmt.Errorf("open gzip stream: %w", err)
 	}
-	defer gz.Close()
+	defer func() { _ = gz.Close() }()
 	reader := tar.NewReader(gz)
 	root, err := filepath.Abs(destination)
 	if err != nil {
@@ -389,6 +392,7 @@ func extractTarGz(archive, destination string) error {
 			if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
 				return fmt.Errorf("create directory for %s: %w", name, err)
 			}
+			// #nosec G304 -- tar member name ValidPath-checked and confined to the extraction root above
 			out, err := os.OpenFile(target, os.O_CREATE|os.O_EXCL|os.O_WRONLY, mode)
 			if err != nil {
 				return fmt.Errorf("create %s: %w", name, err)

package/engine/internal/rootfacts/facts.go

@@ -299,6 +299,7 @@ func inspectWorkspaceState(facts *Facts) {
 		})
 		return
 	}
+	// #nosec G304 -- workspace ACTIVE path; symlink policy enforced by state.ResolveRoot
 	raw, err := os.ReadFile(activePath)
 	if err != nil {
 		return
@@ -349,6 +350,7 @@ func probeGit(dir string) GitFacts {
 func gitPath(dir, flag string) (string, bool) {
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
+	// #nosec G204 -- git -C <operator repo dir>, fixed args, sanitized env
 	cmd := exec.CommandContext(ctx, "git", "-C", dir, "rev-parse", "--path-format=absolute", flag)
 	cmd.Env = append(gitenv.Sanitize(os.Environ()), "GIT_OPTIONAL_LOCKS=0", "GIT_TERMINAL_PROMPT=0")
 	out, err := cmd.Output()
@@ -441,6 +443,7 @@ func within(candidate, parent string) bool {
 }
 
 func isDir(path string) bool {
+	// #nosec G703 -- existence probe on a safepath-resolved candidate
 	info, err := os.Stat(path)
 	return err == nil && info.IsDir()
 }

package/engine/internal/safepath/safepath_fuzz_test.go

@@ -0,0 +1,21 @@
+package safepath
+
+import "testing"
+
+func FuzzWithinResolved(f *testing.F) {
+	f.Add("child/file.txt", "/tmp/parent")
+	f.Add("..", "/tmp/parent")
+	f.Add("", "")
+	f.Fuzz(func(t *testing.T, candidate, parent string) {
+		_ = WithinResolved(candidate, parent)
+	})
+}
+
+func FuzzResolveExisting(f *testing.F) {
+	f.Add("/tmp/example")
+	f.Add("relative/path")
+	f.Add("")
+	f.Fuzz(func(t *testing.T, filename string) {
+		_, _ = ResolveExisting(filename)
+	})
+}

package/engine/internal/state/acceptance.go

@@ -0,0 +1,87 @@
+package state
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+var (
+	acceptanceHeadingRE = regexp.MustCompile(`(?i)^##\s+Acceptance criteria\s*$`)
+	canonicalACRE       = regexp.MustCompile(`\bAC-\d{3}\b`)
+	h2HeadingRE         = regexp.MustCompile(`^##\s+`)
+)
+
+// AcceptanceMapResult is the deterministic ID-presence check from spec.md
+// onto tasks.md and test-plan.md. It does not judge coverage quality.
+type AcceptanceMapResult struct {
+	SpecIDs  []string
+	Problems []string
+}
+
+// ParseAcceptanceMap extracts canonical AC-### IDs from spec.md's Acceptance
+// criteria section and requires each to appear as a literal substring in the
+// required planning artifacts.
+func ParseAcceptanceMap(spec, tasks, testPlan []byte, requireTasks, requireTestPlan bool) AcceptanceMapResult {
+	ids := uniqueCanonicalACs(acceptanceSection(spec))
+	result := AcceptanceMapResult{SpecIDs: ids}
+	if len(ids) == 0 {
+		return result
+	}
+	if requireTasks {
+		text := string(tasks)
+		for _, id := range ids {
+			if !strings.Contains(text, id) {
+				result.Problems = append(result.Problems, fmt.Sprintf("acceptance %s is not referenced in tasks.md", id))
+			}
+		}
+	}
+	if requireTestPlan {
+		text := string(testPlan)
+		for _, id := range ids {
+			if !strings.Contains(text, id) {
+				result.Problems = append(result.Problems, fmt.Sprintf("acceptance %s is not referenced in test-plan.md", id))
+			}
+		}
+	}
+	return result
+}
+
+func acceptanceSection(spec []byte) string {
+	lines := strings.Split(strings.ReplaceAll(string(spec), "\r\n", "\n"), "\n")
+	start := -1
+	for i, line := range lines {
+		if acceptanceHeadingRE.MatchString(strings.TrimSpace(line)) {
+			start = i + 1
+			break
+		}
+	}
+	if start < 0 {
+		return ""
+	}
+	end := len(lines)
+	for i := start; i < len(lines); i++ {
+		if h2HeadingRE.MatchString(lines[i]) {
+			end = i
+			break
+		}
+	}
+	return strings.Join(lines[start:end], "\n")
+}
+
+func uniqueCanonicalACs(text string) []string {
+	found := canonicalACRE.FindAllString(text, -1)
+	if len(found) == 0 {
+		return nil
+	}
+	seen := make(map[string]bool, len(found))
+	var ids []string
+	for _, id := range found {
+		if seen[id] {
+			continue
+		}
+		seen[id] = true
+		ids = append(ids, id)
+	}
+	return ids
+}