devrites 5.14.3 → 6.0.0

package/engine/internal/fsutil/copy.go

@@ -1,18 +1,33 @@
 package fsutil
 
 import (
+	"crypto/rand"
+	"encoding/binary"
+	"errors"
 	"fmt"
 	"io/fs"
 	"os"
 	"path/filepath"
 	"runtime"
+	"syscall"
 )
 
-// PermissionsMatch compares POSIX permission bits where the platform exposes
-// them. Windows os.FileMode synthesizes 0666/0777 from file attributes, so its
-// inherited ACL remains the security boundary instead.
-func PermissionsMatch(mode, want fs.FileMode) bool {
-	return runtime.GOOS == "windows" || mode.Perm() == want.Perm()
+// syncDir flushes a directory's entries so a completed rename survives a crash.
+// It is a variable so tests can observe the call.
+var syncDir = func(dir string) error {
+	if runtime.GOOS == "windows" {
+		return nil
+	}
+	d, err := os.Open(dir) // #nosec G304 -- dir is the parent of an engine-managed path
+	if err != nil {
+		return err
+	}
+	err = d.Sync()
+	_ = d.Close()
+	if errors.Is(err, syscall.EINVAL) || errors.Is(err, errors.ErrUnsupported) {
+		return nil
+	}
+	return err
 }
 
 // WriteFileAtomic writes path by first writing a sibling temp file and then
@@ -51,61 +66,80 @@ func WriteFileAtomic(path string, data []byte, perm fs.FileMode) error {
 		return fmt.Errorf("atomic write %s: %w", path, err)
 	}
 	cleanup = false
-	return nil
-}
-
-// FileModTime returns a regular file's modification time in whole seconds.
-func FileModTime(path string) (int64, bool) {
-	info, err := os.Stat(path)
-	if err != nil || !info.Mode().IsRegular() {
-		return 0, false
+	if err := syncDir(filepath.Dir(path)); err != nil {
+		return fmt.Errorf("atomic write %s: %w", path, err)
 	}
-	return info.ModTime().Unix(), true
+	return nil
 }
 
-// NewestModTime returns the newest modification time among regular files.
-func NewestModTime(paths ...string) (newest int64, ok bool) {
-	for _, path := range paths {
-		if modified, exists := FileModTime(path); exists && (!ok || modified > newest) {
-			newest, ok = modified, true
+// WriteFileAtomicIn is WriteFileAtomic confined to root: every directory
+// component of rel is resolved relative to the open root, so a component
+// swapped for a symlink that leaves the root fails instead of redirecting
+// the write.
+func WriteFileAtomicIn(root *os.Root, rel string, data []byte, perm fs.FileMode) (err error) {
+	defer func() {
+		if err != nil {
+			err = fmt.Errorf("atomic write %s: %w", filepath.Join(root.Name(), rel), err)
 		}
+	}()
+	dir := filepath.Dir(rel)
+	if err := root.MkdirAll(dir, 0o755); err != nil {
+		return err
 	}
-	return newest, ok
-}
-
-// CopyTree recursively copies src to dst, creating parent directories and
-// overwriting files. A missing src is not an error.
-func CopyTree(src, dst string) error {
-	info, err := os.Stat(src)
-	if os.IsNotExist(err) {
-		return nil
+	var tmpName string
+	var tmp *os.File
+	for range 100 {
+		var nonce [8]byte
+		_, _ = rand.Read(nonce[:]) // never fails since go 1.24
+		tmpName = filepath.Join(dir, fmt.Sprintf(".%s.tmp-%d", filepath.Base(rel), binary.BigEndian.Uint64(nonce[:])))
+		tmp, err = root.OpenFile(tmpName, os.O_RDWR|os.O_CREATE|os.O_EXCL, 0o600)
+		if !errors.Is(err, fs.ErrExist) {
+			break
+		}
 	}
 	if err != nil {
-		return fmt.Errorf("copy %s: %w", src, err)
+		return err
 	}
-	if !info.IsDir() {
-		// #nosec G304 -- src is an engine-managed path inside the operator-supplied root
-		data, err := os.ReadFile(src)
-		if err != nil {
-			return fmt.Errorf("copy %s: %w", src, err)
-		}
-		if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
-			return fmt.Errorf("copy to %s: %w", dst, err)
+	cleanup := true
+	defer func() {
+		if cleanup {
+			_ = root.Remove(tmpName)
 		}
-		// #nosec G703 -- dst mirrors src within the same managed tree
-		return os.WriteFile(dst, data, 0o644)
+	}()
+	if _, err := tmp.Write(data); err != nil {
+		_ = tmp.Close()
+		return err
 	}
-	entries, err := os.ReadDir(src)
-	if err != nil {
-		return fmt.Errorf("copy %s: %w", src, err)
+	if err := tmp.Chmod(perm); err != nil {
+		_ = tmp.Close()
+		return err
 	}
-	if err := os.MkdirAll(dst, 0o755); err != nil {
-		return fmt.Errorf("copy to %s: %w", dst, err)
+	if err := tmp.Sync(); err != nil {
+		_ = tmp.Close()
+		return err
 	}
-	for _, e := range entries {
-		if err := CopyTree(filepath.Join(src, e.Name()), filepath.Join(dst, e.Name())); err != nil {
-			return err
-		}
+	if err := tmp.Close(); err != nil {
+		return err
 	}
-	return nil
+	if err := root.Rename(tmpName, rel); err != nil {
+		return err
+	}
+	cleanup = false
+	return syncDirIn(root, dir)
+}
+
+func syncDirIn(root *os.Root, dir string) error {
+	if runtime.GOOS == "windows" {
+		return nil
+	}
+	d, err := root.Open(dir)
+	if err != nil {
+		return err
+	}
+	err = d.Sync()
+	_ = d.Close()
+	if errors.Is(err, syscall.EINVAL) || errors.Is(err, errors.ErrUnsupported) {
+		return nil
+	}
+	return err
 }

package/engine/internal/fsutil/copy_test.go

@@ -6,7 +6,6 @@ import (
 	"runtime"
 	"strings"
 	"testing"
-	"time"
 )
 
 func TestWriteFileAtomicWritesAndOverwrites(t *testing.T) {
@@ -22,7 +21,7 @@ func TestWriteFileAtomicWritesAndOverwrites(t *testing.T) {
 	if string(got) != "first\n" {
 		t.Fatalf("content %q", got)
 	}
-	if !PermissionsMatch(mustMode(t, path), 0o644) {
+	if runtime.GOOS != "windows" && mustMode(t, path).Perm() != 0o644 {
 		t.Fatalf("perm %v", mustMode(t, path))
 	}
 	// Overwrite in place.
@@ -53,141 +52,103 @@ func mustMode(t *testing.T, path string) os.FileMode {
 	return info.Mode()
 }
 
-func TestFileModTime(t *testing.T) {
+func TestWriteFileAtomicSurfacesFailure(t *testing.T) {
 	dir := t.TempDir()
-	path := filepath.Join(dir, "file.txt")
-	if err := os.WriteFile(path, []byte("x"), 0o644); err != nil {
+	blocker := filepath.Join(dir, "blocker")
+	if err := os.WriteFile(blocker, []byte("x"), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	modified, ok := FileModTime(path)
-	if !ok {
-		t.Fatal("regular file should report mod time")
-	}
-	if modified <= 0 {
-		t.Fatalf("mod time %d", modified)
-	}
-	if _, ok := FileModTime(filepath.Join(dir, "missing.txt")); ok {
-		t.Fatal("missing file should report !ok")
+	// The parent path is an existing file, so creating the destination
+	// directory must fail and the error must surface to the caller.
+	err := WriteFileAtomic(filepath.Join(blocker, "nested", "file.txt"), []byte("x"), 0o644)
+	if err == nil {
+		t.Fatal("expected the write failure to surface")
 	}
-	if _, ok := FileModTime(dir); ok {
-		t.Fatal("directory should report !ok")
+	if !strings.Contains(err.Error(), "atomic write") {
+		t.Fatalf("error should identify the operation, got %v", err)
 	}
 }
 
-func TestNewestModTime(t *testing.T) {
-	dir := t.TempDir()
-	old := filepath.Join(dir, "old.txt")
-	new := filepath.Join(dir, "new.txt")
-	if err := os.WriteFile(old, []byte("x"), 0o644); err != nil {
-		t.Fatal(err)
+func TestWriteFileAtomicSyncsParentDirAfterRename(t *testing.T) {
+	var calls []string
+	var existedAtSync bool
+	path := filepath.Join(t.TempDir(), "nested", "file.txt")
+	orig := syncDir
+	syncDir = func(dir string) error {
+		calls = append(calls, dir)
+		_, err := os.Stat(path)
+		existedAtSync = err == nil
+		return nil
 	}
-	if err := os.WriteFile(new, []byte("x"), 0o644); err != nil {
+	t.Cleanup(func() { syncDir = orig })
+	if err := WriteFileAtomic(path, []byte("x"), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	future := time.Now().Add(2 * time.Hour)
-	if err := os.Chtimes(new, future, future); err != nil {
-		t.Skipf("cannot set file times on this platform: %v", err)
-	}
-	newest, ok := NewestModTime(old, new)
-	if !ok {
-		t.Fatal("expected ok")
+	if len(calls) != 1 || calls[0] != filepath.Dir(path) {
+		t.Fatalf("syncDir calls = %v, want one call with %q", calls, filepath.Dir(path))
 	}
-	want, _ := FileModTime(new)
-	if newest != want {
-		t.Fatalf("newest=%d want %d", newest, want)
-	}
-	if _, ok := NewestModTime(filepath.Join(dir, "missing.txt")); ok {
-		t.Fatal("missing-only inputs should report !ok")
+	if !existedAtSync {
+		t.Fatal("syncDir ran before the rename")
 	}
 }
 
-func TestCopyTreeMissingSourceIsNoOp(t *testing.T) {
-	dir := t.TempDir()
-	dst := filepath.Join(dir, "dst")
-	if err := CopyTree(filepath.Join(dir, "missing"), dst); err != nil {
-		t.Fatalf("missing src must not error: %v", err)
-	}
-	if _, err := os.Stat(dst); !os.IsNotExist(err) {
-		t.Fatalf("dst must not be created, got %v", err)
-	}
-}
-
-func TestCopyTreeFileAndTree(t *testing.T) {
-	dir := t.TempDir()
-	src := filepath.Join(dir, "src")
-	if err := os.MkdirAll(filepath.Join(src, "sub"), 0o755); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(filepath.Join(src, "root.txt"), []byte("root\n"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(filepath.Join(src, "sub", "leaf.txt"), []byte("leaf\n"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	dst := filepath.Join(dir, "dst")
-	if err := CopyTree(src, dst); err != nil {
-		t.Fatal(err)
-	}
-	for rel, want := range map[string]string{
-		"root.txt":     "root\n",
-		"sub/leaf.txt": "leaf\n",
-	} {
-		got, err := os.ReadFile(filepath.Join(dst, filepath.FromSlash(rel)))
-		if err != nil {
-			t.Fatalf("%s: %v", rel, err)
-		}
-		if string(got) != want {
-			t.Fatalf("%s: %q want %q", rel, got, want)
+func TestWriteFileAtomicInRefusesSymlinkedDirectoryOutsideRoot(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("creating symlinks needs elevated privileges on Windows")
+	}
+	base := t.TempDir()
+	target := filepath.Join(base, "target")
+	outside := filepath.Join(base, "outside")
+	for _, dir := range []string{target, outside} {
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatal(err)
 		}
 	}
-
-	// Copying a single file copies its contents.
-	single := filepath.Join(dir, "single.txt")
-	if err := os.WriteFile(single, []byte("one\n"), 0o644); err != nil {
+	if err := os.Symlink(outside, filepath.Join(target, ".claude")); err != nil {
 		t.Fatal(err)
 	}
-	singleDst := filepath.Join(dir, "single-copy.txt")
-	if err := CopyTree(single, singleDst); err != nil {
+	root, err := os.OpenRoot(target)
+	if err != nil {
 		t.Fatal(err)
 	}
-	if got, _ := os.ReadFile(singleDst); string(got) != "one\n" {
-		t.Fatalf("single copy %q", got)
-	}
-
-	// Recopying overwrites existing files.
-	if err := os.WriteFile(filepath.Join(src, "root.txt"), []byte("changed\n"), 0o644); err != nil {
-		t.Fatal(err)
+	defer func() { _ = root.Close() }()
+	if err := WriteFileAtomicIn(root, filepath.Join(".claude", "skills", "x.md"), []byte("x"), 0o644); err == nil {
+		t.Fatal("expected the write through a symlink leaving the root to fail")
 	}
-	if err := CopyTree(src, dst); err != nil {
+	entries, err := os.ReadDir(outside)
+	if err != nil {
 		t.Fatal(err)
 	}
-	if got, _ := os.ReadFile(filepath.Join(dst, "root.txt")); string(got) != "changed\n" {
-		t.Fatalf("overwrite %q", got)
+	if len(entries) != 0 {
+		t.Fatalf("outside directory was written to: %v", entries)
 	}
 }
 
-func TestPermissionsMatch(t *testing.T) {
-	if !PermissionsMatch(0o644, 0o644) {
-		t.Fatal("matching perms must match")
-	}
-	if runtime.GOOS != "windows" && PermissionsMatch(0o600, 0o644) {
-		t.Fatal("differing POSIX perms must not match")
-	}
-}
-
-func TestWriteFileAtomicSurfacesFailure(t *testing.T) {
-	dir := t.TempDir()
-	blocker := filepath.Join(dir, "blocker")
-	if err := os.WriteFile(blocker, []byte("x"), 0o644); err != nil {
+func TestWriteFileAtomicInWritesOverwritesAndLeavesNoTemp(t *testing.T) {
+	target := t.TempDir()
+	root, err := os.OpenRoot(target)
+	if err != nil {
 		t.Fatal(err)
 	}
-	// The parent path is an existing file, so creating the destination
-	// directory must fail and the error must surface to the caller.
-	err := WriteFileAtomic(filepath.Join(blocker, "nested", "file.txt"), []byte("x"), 0o644)
-	if err == nil {
-		t.Fatal("expected the write failure to surface")
+	defer func() { _ = root.Close() }()
+	rel := filepath.Join("a", "b", "f.txt")
+	for _, content := range []string{"one", "two"} {
+		if err := WriteFileAtomicIn(root, rel, []byte(content), 0o640); err != nil {
+			t.Fatal(err)
+		}
+		got, err := os.ReadFile(filepath.Join(target, rel))
+		if err != nil || string(got) != content {
+			t.Fatalf("read = %q, %v; want %q", got, err, content)
+		}
 	}
-	if !strings.Contains(err.Error(), "atomic write") {
-		t.Fatalf("error should identify the operation, got %v", err)
+	if runtime.GOOS != "windows" {
+		info, err := os.Stat(filepath.Join(target, rel))
+		if err != nil || info.Mode().Perm() != 0o640 {
+			t.Fatalf("mode = %v, %v; want 0640", info, err)
+		}
+	}
+	entries, err := os.ReadDir(filepath.Join(target, "a", "b"))
+	if err != nil || len(entries) != 1 {
+		t.Fatalf("directory entries = %v, %v; want only the target file", entries, err)
 	}
 }

package/engine/internal/gate/gate.go

@@ -6,8 +6,10 @@ package gate
 
 import (
 	"fmt"
+	"regexp"
 	"strings"
 
+	"github.com/devrites/devrites/internal/markdowntext"
 	"github.com/devrites/devrites/internal/reason"
 	"github.com/devrites/devrites/internal/state"
 )
@@ -114,7 +116,11 @@ func checkObservation(kind Kind, observation *state.WorkspaceObservation) (*Resu
 	var stateProblems []string
 
 	if policy.BlocksOpenQuestions {
-		if gates, awaitingHuman := retainedHumanGates(observation); len(gates) > 0 {
+		gates, awaitingHuman, err := retainedHumanGates(observation)
+		if err != nil {
+			stateProblems = append(stateProblems, "questions.md is invalid Markdown, so open human questions cannot be ruled out")
+			blocked = true
+		} else if len(gates) > 0 {
 			problem := fmt.Sprintf("open %s human question(s) remain in questions.md", strings.Join(gates, "/"))
 			if !awaitingHuman {
 				problem += " but state.md is not awaiting_human"
@@ -247,7 +253,55 @@ func acceptanceMapProblems(observation *state.WorkspaceObservation, policy state
 			testPlan = fact.Bytes()
 		}
 	}
-	return state.ParseAcceptanceMap(spec.Bytes(), tasks, testPlan, requireTasks, requireTestPlan).Problems
+	result := state.ParseAcceptanceMap(spec.Bytes(), tasks, testPlan, requireTasks, requireTestPlan)
+	if len(result.SpecIDs) == 0 && specClaimsAcceptance(spec.Bytes()) {
+		return []string{"spec.md mentions acceptance criteria but no AC-### id was found under a `## Acceptance criteria` heading; use that exact heading and three-digit ids such as AC-001"}
+	}
+	return append(result.Problems, specUnreadAcceptanceProblems(spec.Bytes())...)
+}
+
+var (
+	specAcceptanceHeadingRE     = regexp.MustCompile(`(?i)^\s{0,3}#{1,6}\s+.*acceptance criteria`)
+	specCanonicalAcceptanceHead = regexp.MustCompile(`(?i)^##\s+Acceptance criteria\s*$`)
+	specACTokenRE               = regexp.MustCompile(`\bAC-\d+\b`)
+	specAcceptanceClaimRE       = regexp.MustCompile(`(?im)^\s{0,3}#{1,6}\s+.*acceptance criteria|\bAC-\d+\b`)
+)
+
+// specClaimsAcceptance reports whether structural (unfenced) spec text looks
+// like it carries acceptance criteria, so a parse that finds none is a defect
+// in the spec rather than a spec with nothing to map.
+func specClaimsAcceptance(spec []byte) bool {
+	structural, err := markdowntext.Structural(spec)
+	return err == nil && specAcceptanceClaimRE.Match(structural)
+}
+
+// specUnreadAcceptanceProblems names acceptance text the parser skips: ids that
+// are not exactly three digits and acceptance headings after the first
+// canonical one, which would otherwise escape the coverage check.
+func specUnreadAcceptanceProblems(spec []byte) []string {
+	structural, err := markdowntext.Structural(spec)
+	if err != nil {
+		return nil
+	}
+	var problems []string
+	seen := map[string]bool{}
+	readHeading := false
+	for _, line := range strings.Split(string(structural), "\n") {
+		if specAcceptanceHeadingRE.MatchString(line) {
+			if trimmed := strings.TrimSpace(line); !readHeading && specCanonicalAcceptanceHead.MatchString(trimmed) {
+				readHeading = true
+			} else {
+				problems = append(problems, fmt.Sprintf("spec.md has an acceptance criteria heading the gate does not read (%q); only the first `## Acceptance criteria` section is checked", trimmed))
+			}
+		}
+		for _, id := range specACTokenRE.FindAllString(line, -1) {
+			if len(id) != len("AC-000") && !seen[id] {
+				seen[id] = true
+				problems = append(problems, fmt.Sprintf("spec.md uses %s, which is not a three-digit AC-### id, so the gate does not check it", id))
+			}
+		}
+	}
+	return problems
 }
 
 func missingSections(observation *state.WorkspaceObservation, required []state.Section) []state.Section {
@@ -378,25 +432,43 @@ func diagnosticRepair(code state.DiagnosticCode) string {
 
 const gateSpaceChars = " \t\n\v\f\r"
 
-func retainedHumanGates(observation *state.WorkspaceObservation) ([]string, bool) {
+func retainedHumanGates(observation *state.WorkspaceObservation) ([]string, bool, error) {
 	questions, ok := observation.Fact("questions.md")
 	if !ok || (questions.State() != state.ArtifactPresent && questions.State() != state.ArtifactEmpty) {
-		return nil, false
+		return nil, false, nil
 	}
-	gates := OpenBlockingQuestionGates(questions.Bytes())
-	if len(gates) == 0 {
-		return nil, false
+	gates, err := openBlockingQuestionGates(questions.Bytes())
+	if err != nil || len(gates) == 0 {
+		return nil, false, err
 	}
 	ledger, ok := observation.Fact(state.LedgerFile)
-	return gates, ok && ledger.State() == state.ArtifactPresent && stateAwaitingHuman(ledger.Bytes())
+	return gates, ok && ledger.State() == state.ArtifactPresent && stateAwaitingHuman(ledger.Bytes()), nil
 }
 
 // OpenBlockingQuestionGates returns the deduplicated gate kinds (blocking,
 // validating, escalating) still open in questions.md, tolerating both the
 // per-question block form and the register table form. Exported so the
-// handoff resume record reports the same gates the lifecycle enforces.
+// handoff resume record reports the same gates the lifecycle enforces. Content
+// that cannot be parsed fails closed as [blocking], matching the lifecycle gate,
+// so a caller never reads an unparseable file as having no open gates.
 func OpenBlockingQuestionGates(data []byte) []string {
-	lines := splitLinesNoTrailing(data)
+	gates, err := openBlockingQuestionGates(data)
+	if err != nil {
+		return []string{"blocking"}
+	}
+	return gates
+}
+
+// openBlockingQuestionGates masks fenced regions first: a fenced region is a
+// documented example, never live question structure. Content markdowntext
+// rejects yields no gates and an error, which Check turns into a blocking
+// problem rather than reading the file as clean.
+func openBlockingQuestionGates(data []byte) ([]string, error) {
+	visible, err := markdowntext.Structural(data)
+	if err != nil {
+		return nil, err
+	}
+	lines := splitLinesNoTrailing(visible)
 	seen := map[string]bool{}
 	var gates []string
 	inQ := false
@@ -417,6 +489,7 @@ func OpenBlockingQuestionGates(data []byte) []string {
 		}
 	}
 	for _, line := range lines {
+		lower := strings.ToLower(line)
 		if cells, ok := questionTableCells(line); ok {
 			if !tableOpen {
 				tableOpen = true
@@ -431,20 +504,20 @@ func OpenBlockingQuestionGates(data []byte) []string {
 			statusColumn, gateColumn = -1, -1
 		}
 		switch {
-		case strings.HasPrefix(strings.ToLower(line), "## q-"):
+		case strings.HasPrefix(lower, "## q-"):
 			finalize()
 			inQ, status, gate = true, "", ""
-		case inQ && strings.HasPrefix(line, "status:"):
-			status = strings.TrimLeft(strings.TrimPrefix(line, "status:"), gateSpaceChars)
-		case inQ && strings.HasPrefix(line, "gate:"):
-			gate = strings.TrimLeft(strings.TrimPrefix(line, "gate:"), gateSpaceChars)
+		case inQ && strings.HasPrefix(lower, "status:"):
+			status = strings.TrimLeft(line[len("status:"):], gateSpaceChars)
+		case inQ && strings.HasPrefix(lower, "gate:"):
+			gate = strings.TrimLeft(line[len("gate:"):], gateSpaceChars)
 		case inQ && isHeadingLine(line):
 			finalize()
 			inQ = false
 		}
 	}
 	finalize()
-	return gates
+	return gates, nil
 }
 
 func questionTableCells(line string) ([]string, bool) {