devrites 4.7.0 → 5.0.0

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); err != nil {
+	if err := hostpack.ValidatePayload(os.DirFS(payload), true, true); err != nil {
 		return fmt.Errorf("local update payload under %s is invalid: %w", payload, err)
 	}
 	installFlags := manifestHeader(mf, "devrites-flags")
@@ -153,6 +153,7 @@ func runRemoteUpdate(opts Options, target, installed string) error {
 	if opts.Force {
 		args = append(args, "--force")
 	}
+	// #nosec G204 -- re-execs the located engine binary with fixed migration args
 	cmd := exec.CommandContext(ctx, candidate.EnginePath, args...)
 	cmd.Stdout = opts.Stdout
 	cmd.Stderr = opts.Stderr

package/engine/internal/lib/candidate.go

@@ -103,11 +103,12 @@ func readBoundedRegularFile(name string, limit int64) ([]byte, error) {
 	if before.Size() < 0 || before.Size() > limit {
 		return nil, fmt.Errorf("artifact exceeds %s limit", byteLimitName(limit))
 	}
+	// #nosec G304 -- candidate artifact path; size cap checked above
 	file, err := os.Open(name)
 	if err != nil {
 		return nil, err
 	}
-	defer file.Close()
+	defer func() { _ = file.Close() }()
 	opened, err := file.Stat()
 	if err != nil {
 		return nil, err
@@ -440,11 +441,12 @@ func hashCandidateFile(digest hash.Hash, project string, row candidateRow) error
 		return errors.New("present path disappeared before reading")
 	}
 	name := filepath.Join(project, filepath.FromSlash(row.path))
+	// #nosec G304 -- row path validated against the workspace contract (validateCandidateRow)
 	file, err := os.Open(name)
 	if err != nil {
 		return err
 	}
-	defer file.Close()
+	defer func() { _ = file.Close() }()
 	opened, err := file.Stat()
 	if err != nil {
 		return err

package/engine/internal/lib/candidate_test.go

@@ -435,7 +435,7 @@ func TestCandidateIdentityRejectsSpecialFile(t *testing.T) {
 	if err != nil {
 		t.Skipf("Unix-domain sockets unavailable: %v", err)
 	}
-	defer listener.Close()
+	defer func() { _ = listener.Close() }()
 	if _, _, err := CandidateIdentity(root, "feature"); err == nil || !strings.Contains(err.Error(), "regular file") {
 		t.Fatalf("error=%v, want special-file rejection", err)
 	}

package/engine/internal/lib/environment_report.go

@@ -0,0 +1,109 @@
+package lib
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/version"
+)
+
+// PathProbe records whether one project-relative path exists.
+type PathProbe struct {
+	Path    string `json:"path"`
+	Present bool   `json:"present"`
+}
+
+// EnvironmentReport is a read-only snapshot of install and code-index presence.
+type EnvironmentReport struct {
+	EngineVersion string      `json:"engine_version"`
+	ProjectRoot   string      `json:"project_root"`
+	DevritesRoot  string      `json:"devrites_root,omitempty"`
+	Manifest      PathProbe   `json:"manifest"`
+	Indexes       []PathProbe `json:"indexes"`
+}
+
+func projectRootFromDevritesRoot(root string) string {
+	if root == "" {
+		wd, err := os.Getwd()
+		if err != nil {
+			return "."
+		}
+		return wd
+	}
+	if filepath.Base(root) == devritespaths.DevritesRootName {
+		return filepath.Dir(root)
+	}
+	return root
+}
+
+func probePath(projectRoot, rel string) PathProbe {
+	abs := filepath.Join(projectRoot, filepath.FromSlash(rel))
+	info, err := os.Stat(abs)
+	return PathProbe{Path: rel, Present: err == nil && info != nil}
+}
+
+// EnvironmentReportFor builds a report for one project root.
+func EnvironmentReportFor(devritesRoot, projectRoot string) (EnvironmentReport, error) {
+	if projectRoot == "" {
+		projectRoot = projectRootFromDevritesRoot(devritesRoot)
+	}
+	abs, err := filepath.Abs(projectRoot)
+	if err != nil {
+		return EnvironmentReport{}, err
+	}
+	report := EnvironmentReport{
+		EngineVersion: version.Version,
+		ProjectRoot:   abs,
+		Manifest:      probePath(abs, devritespaths.ManifestName),
+		Indexes: []PathProbe{
+			probePath(abs, ".codegraph"),
+			probePath(abs, ".code-review-graph"),
+			probePath(abs, ".codebase-memory"),
+		},
+	}
+	if devritesRoot != "" {
+		report.DevritesRoot = devritesRoot
+	}
+	return report, nil
+}
+
+// WriteEnvironmentReportJSON prints one JSON object to stdout.
+func WriteEnvironmentReportJSON(devritesRoot, projectRoot string, stdout io.Writer) error {
+	report, err := EnvironmentReportFor(devritesRoot, projectRoot)
+	if err != nil {
+		return fmt.Errorf("build environment report: %w", err)
+	}
+	enc := json.NewEncoder(stdout)
+	enc.SetIndent("", "  ")
+	if err := enc.Encode(report); err != nil {
+		return fmt.Errorf("encode environment report: %w", err)
+	}
+	return nil
+}
+
+// RunEnvironmentCheck implements `devrites-engine check indexes`.
+func RunEnvironmentCheck(devritesRoot string, args []string, stdout, stderr io.Writer) int {
+	projectRoot := ""
+	for i := 0; i < len(args); i++ {
+		if args[i] == "--root" {
+			if i+1 >= len(args) {
+				fmt.Fprintln(stderr, "indexes: --root requires a path")
+				return 2
+			}
+			projectRoot = args[i+1]
+			i++
+			continue
+		}
+		fmt.Fprintf(stderr, "indexes: unexpected argument %q\n", args[i])
+		return 2
+	}
+	if err := WriteEnvironmentReportJSON(devritesRoot, projectRoot, stdout); err != nil {
+		fmt.Fprintf(stderr, "indexes: %v\n", err)
+		return 2
+	}
+	return 0
+}

package/engine/internal/lib/environment_report_test.go

@@ -0,0 +1,54 @@
+package lib
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+)
+
+func TestEnvironmentReportForDetectsManifestAndIndexes(t *testing.T) {
+	project := t.TempDir()
+	root := filepath.Join(project, devritespaths.DevritesRootName)
+	manifestPath := filepath.Join(project, devritespaths.ManifestName)
+	if err := os.MkdirAll(filepath.Dir(manifestPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(manifestPath, []byte("devrites\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(project, ".codegraph"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	report, err := EnvironmentReportFor(root, project)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if report.ProjectRoot != project {
+		t.Fatalf("project root = %q, want %q", report.ProjectRoot, project)
+	}
+	if !report.Manifest.Present {
+		t.Fatal("expected manifest present")
+	}
+	if len(report.Indexes) != 3 {
+		t.Fatalf("indexes = %d, want 3", len(report.Indexes))
+	}
+	if !report.Indexes[0].Present {
+		t.Fatalf("expected .codegraph present, got %+v", report.Indexes)
+	}
+}
+
+func TestRunEnvironmentCheckWritesJSON(t *testing.T) {
+	project := t.TempDir()
+	var stdout, stderr bytes.Buffer
+	if code := RunEnvironmentCheck("", []string{"--root", project}, &stdout, &stderr); code != 0 {
+		t.Fatalf("code=%d stderr=%q", code, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), `"engine_version"`) || !strings.Contains(stdout.String(), `"manifest"`) {
+		t.Fatalf("stdout=%q", stdout.String())
+	}
+}

package/engine/internal/lib/migrate.go

@@ -88,6 +88,7 @@ func Migrate(root string, args []string, stdout, stderr io.Writer) int {
 	var exit int
 	var result string
 	err = state.WithFeatureLock(root, slug, func() error {
+		// #nosec G304 -- workspace ledger path resolved from the operator root
 		raw, err := os.ReadFile(ledger)
 		if err != nil {
 			return err

package/engine/internal/lib/open_visual.go

@@ -77,7 +77,9 @@ func OpenVisual(root string, args []string, stdout, stderr io.Writer) int {
 	var idReport VisualIDConsistency
 	idsChecked := false
 	if !outlineMissing {
+		// #nosec G304 -- visual evidence files inside the workspace
 		htmlBody, herr := os.ReadFile(htmlPath)
+		// #nosec G304 -- visual evidence files inside the workspace
 		outlineBody, oerr := os.ReadFile(outlinePath)
 		switch {
 		case herr != nil:
@@ -239,12 +241,15 @@ func openLocalFile(path string) error {
 	switch runtime.GOOS {
 	case "darwin":
 		// argv only — no shell.
+		// #nosec G204 -- fixed platform opener; path passed as argv, no shell
 		cmd = exec.Command("open", path)
 	case "windows":
 		// Avoid cmd.exe /c shell composition; FileProtocolHandler takes one path argv.
+		// #nosec G204 -- fixed platform opener; path passed as argv, no shell
 		cmd = exec.Command("rundll32.exe", "url.dll,FileProtocolHandler", path)
 	default:
 		// argv only — no shell.
+		// #nosec G204 -- fixed platform opener; path passed as argv, no shell
 		cmd = exec.Command("xdg-open", path)
 	}
 	if err := cmd.Start(); err != nil {

package/engine/internal/lib/resolve.go

@@ -98,6 +98,7 @@ func resolveMutation(mode, qid, payload, qfile, sfile string, stdout, stderr io.
 		fmt.Fprintf(stdout, "Reason:   %s\n", payload)
 		fmt.Fprintf(stdout, "Workspace: questions.md + state.md updated.\n")
 	case "batch":
+		// #nosec G304 -- operator-passed --batch file argument
 		data, err := os.ReadFile(payload)
 		if err != nil {
 			return fail(stderr, "Batch file not found: "+payload, 5)
@@ -188,6 +189,7 @@ func nowUTC() string { return clockNow().UTC().Format("2006-01-02T15:04:05Z") }
 // status, answer, and answered-at time in one pass. Returns 0, or 3 (qid
 // not found) / 4 (qid not open), writing the message on failure.
 func resolveQuestion(qfile, qid, status, answer string, stderr io.Writer) int {
+	// #nosec G304 -- questions.md path inside the feature workspace
 	data, err := os.ReadFile(qfile)
 	if err != nil {
 		return fail(stderr, "questions.md missing at "+qfile, 2)
@@ -284,6 +286,7 @@ var (
 // running, clears the Next step, and appends a Log entry. It is a no-op when the
 // workspace is not waiting on this question.
 func clearAwaiting(sfile, qid string) error {
+	// #nosec G304 -- state.md path inside the feature workspace
 	data, err := os.ReadFile(sfile)
 	if err != nil {
 		return fmt.Errorf("read state %s: %w", sfile, err)

package/engine/internal/lib/secretscan.go

@@ -385,6 +385,7 @@ func scanWorktreePaths(project string, paths []string, budget *secretScanBudget)
 		if info.Size() < 0 || info.Size() > budget.bytesRemaining {
 			return nil, errSecretScanLimit
 		}
+		// #nosec G304 -- workspace walk; size budget checked above
 		file, err := os.Open(fullPath)
 		if err != nil {
 			return nil, err

package/engine/internal/lib/skilltrust.go

@@ -68,11 +68,12 @@ func ScanSkillTrust(path string) (SkillTrustResult, error) {
 	if info.Size() > 1<<20 {
 		return SkillTrustResult{}, fmt.Errorf("skill-trust: %q exceeds 1 MiB limit", path)
 	}
+	// #nosec G304 -- installed skill file; 1 MiB cap checked above
 	file, err := os.Open(path)
 	if err != nil {
 		return SkillTrustResult{}, err
 	}
-	defer file.Close()
+	defer func() { _ = file.Close() }()
 	raw, err := io.ReadAll(io.LimitReader(file, 1<<20+1))
 	if err != nil {
 		return SkillTrustResult{}, err

package/engine/internal/lib/util.go

@@ -65,6 +65,7 @@ func runGitCommandIO(dir string, env []string, input []byte, stdout io.Writer, a
 	ctx, cancel := context.WithTimeout(context.Background(), gitCommandTimeout)
 	defer cancel()
 	commandArgs := append([]string{"-C", dir}, args...)
+	// #nosec G204 -- git -C <operator repo dir>; fixed binary, sanitized env
 	cmd := exec.CommandContext(ctx, "git", commandArgs...)
 	cmd.WaitDelay = 2 * time.Second
 	if input != nil {

package/engine/internal/lib/workspace_read.go

@@ -21,6 +21,7 @@ func readWorkspaceArtifact(root, slug, name string) ([]byte, error) {
 	if info.Size() > 1<<20 {
 		return nil, fmt.Errorf("task-graph: %s exceeds 1 MiB limit", name)
 	}
+	// #nosec G304 -- workspace task-graph file; 1 MiB cap checked above
 	raw, err := os.ReadFile(path)
 	if err != nil {
 		return nil, fmt.Errorf("task-graph: cannot read %s: %w", name, err)

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/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
+}