devrites 5.11.0 → 5.12.0

package/engine/internal/notes/notes.go

@@ -0,0 +1,384 @@
+// Package notes implements anchored notes: short workspace observations bound
+// to a verbatim quote from one repository file. A note is exact while its
+// quote is still present in the subject file; edits that move or delete the
+// anchored text regrade the note moved, stale, ambiguous, or lost, so
+// rationale that drifted from the code it describes surfaces at the seal gate
+// instead of reading as current.
+package notes
+
+import (
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/devrites/devrites/internal/markdowntext"
+)
+
+// NotesFile is the canonical anchored-notes artifact inside a feature
+// workspace.
+const NotesFile = "notes.md"
+
+const maxNoteIDLen = 64
+
+// Note is one parsed anchored note. Line and SubjectLine are 1-based rows in
+// the source text so repair can rewrite the subject without reparsing prose.
+type Note struct {
+	ID          string
+	Summary     string
+	Subject     string
+	Quote       string
+	Body        string
+	Line        int
+	SubjectLine int
+}
+
+// Document is a parsed notes.md. Errors is fail-closed: any entry means the
+// document cannot be graded reliably.
+type Document struct {
+	Notes   []*Note
+	Errors  []string
+	newline string
+}
+
+var (
+	noteLineRE     = regexp.MustCompile(`^\s*- (NOTE-[^\s:]+): (.*)$`)
+	attrLineRE     = regexp.MustCompile(`^(\s+)(SUBJECT|QUOTE|BODY):(.*)$`)
+	unindentedAttr = regexp.MustCompile(`^(SUBJECT|QUOTE|BODY):`)
+)
+
+// ParseNotes strictly parses a notes.md document. Fenced code blocks are
+// masked per CommonMark fence rules so examples never become notes.
+func ParseNotes(text string) *Document {
+	doc := &Document{}
+	doc.newline = "\n"
+	if strings.Contains(text, "\r\n") {
+		doc.newline = "\r\n"
+	}
+	structural, err := markdowntext.Structural([]byte(text))
+	if err != nil {
+		doc.Errors = append(doc.Errors, "notes is not valid Markdown text: "+err.Error())
+		return doc
+	}
+	lines := strings.Split(strings.ReplaceAll(string(structural), "\r\n", "\n"), "\n")
+
+	var current *Note
+	seen := map[string]bool{}
+	flush := func() { current = nil }
+
+	for i, line := range lines {
+		lineno := i + 1
+		if match := noteLineRE.FindStringSubmatch(line); match != nil {
+			id := match[1]
+			if len(id) > maxNoteIDLen {
+				doc.Errors = append(doc.Errors, fmt.Sprintf("line %d: note id %q exceeds %d characters", lineno, id, maxNoteIDLen))
+				flush()
+				continue
+			}
+			if seen[id] {
+				doc.Errors = append(doc.Errors, fmt.Sprintf("line %d: duplicate note id %q", lineno, id))
+				flush()
+				continue
+			}
+			seen[id] = true
+			current = &Note{ID: id, Summary: strings.TrimSpace(match[2]), Line: lineno}
+			doc.Notes = append(doc.Notes, current)
+			continue
+		}
+		if match := attrLineRE.FindStringSubmatch(line); match != nil {
+			value := strings.TrimSpace(match[3])
+			if current == nil {
+				doc.Errors = append(doc.Errors, fmt.Sprintf("line %d: %s attribute has no note", lineno, match[2]))
+				continue
+			}
+			switch match[2] {
+			case "SUBJECT":
+				if current.Subject != "" {
+					doc.Errors = append(doc.Errors, fmt.Sprintf("line %d: note %s repeats SUBJECT", lineno, current.ID))
+					continue
+				}
+				current.Subject = value
+				current.SubjectLine = lineno
+			case "QUOTE":
+				if current.Quote != "" {
+					doc.Errors = append(doc.Errors, fmt.Sprintf("line %d: note %s repeats QUOTE", lineno, current.ID))
+					continue
+				}
+				current.Quote = value
+			case "BODY":
+				if current.Body != "" {
+					doc.Errors = append(doc.Errors, fmt.Sprintf("line %d: note %s repeats BODY", lineno, current.ID))
+					continue
+				}
+				current.Body = value
+			}
+			continue
+		}
+		if unindentedAttr.MatchString(line) {
+			doc.Errors = append(doc.Errors, fmt.Sprintf("line %d: attribute must be indented beneath its note: %q", lineno, strings.TrimSpace(line)))
+			continue
+		}
+		if strings.TrimSpace(line) != "" {
+			flush()
+		}
+	}
+
+	for _, note := range doc.Notes {
+		if note.Summary == "" {
+			doc.Errors = append(doc.Errors, fmt.Sprintf("note %s has an empty summary", note.ID))
+		}
+		if note.Subject == "" {
+			doc.Errors = append(doc.Errors, fmt.Sprintf("note %s is missing SUBJECT", note.ID))
+		} else if err := ValidateSubject(note.Subject); err != nil {
+			doc.Errors = append(doc.Errors, fmt.Sprintf("note %s: %v", note.ID, err))
+		}
+		if note.Quote == "" {
+			doc.Errors = append(doc.Errors, fmt.Sprintf("note %s is missing QUOTE", note.ID))
+		}
+	}
+	return doc
+}
+
+// ValidateSubject requires a repository-relative subject path with no
+// traversal or absolute anchor.
+func ValidateSubject(subject string) error {
+	if subject == "" {
+		return fmt.Errorf("SUBJECT is empty")
+	}
+	if strings.HasPrefix(subject, "/") || regexp.MustCompile(`^[A-Za-z]:[\\/]`).MatchString(subject) || strings.HasPrefix(subject, `\\`) {
+		return fmt.Errorf("SUBJECT must be repository-relative, not absolute: %q", subject)
+	}
+	for _, seg := range strings.FieldsFunc(subject, func(r rune) bool { return r == '/' || r == '\\' }) {
+		if seg == ".." {
+			return fmt.Errorf("SUBJECT must not contain traversal: %q", subject)
+		}
+	}
+	return nil
+}
+
+// Grade is the current anchor state of a note.
+type Grade string
+
+const (
+	// GradeExact: the quote is still present in the subject file.
+	GradeExact Grade = "exact"
+	// GradeMoved: the quote is absent from the subject and present in exactly
+	// one other repository file; the anchor is repairable.
+	GradeMoved Grade = "moved"
+	// GradeStale: the subject file exists but the quote is gone everywhere.
+	GradeStale Grade = "stale"
+	// GradeAmbiguous: the quote is absent from the subject and present in more
+	// than one other file; re-anchoring needs human judgment.
+	GradeAmbiguous Grade = "ambiguous"
+	// GradeLost: the subject file is gone and the quote is found nowhere.
+	GradeLost Grade = "lost"
+)
+
+// Graded pairs a note with its current grade and, for moved notes, the
+// repository-relative path the quote now lives in.
+type Graded struct {
+	*Note
+	Grade   Grade
+	MovedTo string
+}
+
+// normalizeWS collapses whitespace so a quote matches across re-wrapping and
+// indentation changes while staying verbatim in every other respect.
+func normalizeWS(s string) string {
+	return strings.Join(strings.Fields(s), " ")
+}
+
+// skippedDirs are never searched for relocated quotes: version control,
+// dependencies, build output, and the workspace itself.
+var skippedDirs = map[string]bool{
+	".git":         true,
+	".devrites":    true,
+	"node_modules": true,
+	"vendor":       true,
+	"dist":         true,
+	"build":        true,
+	"out":          true,
+	"target":       true,
+	"bin":          true,
+	"coverage":     true,
+}
+
+const maxSearchFileBytes = 512 << 10
+
+// fileText reads a candidate file as normalized text, skipping oversized and
+// binary files so quotes never match inside archives or images.
+func fileText(path string) (string, bool) {
+	info, err := os.Stat(path)
+	if err != nil || !info.Mode().IsRegular() || info.Size() > maxSearchFileBytes {
+		return "", false
+	}
+	// #nosec G304 -- repository scan path under the resolved project root
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return "", false
+	}
+	head := raw
+	if len(head) > 512 {
+		head = head[:512]
+	}
+	if strings.IndexByte(string(head), 0) >= 0 {
+		return "", false
+	}
+	return normalizeWS(string(raw)), true
+}
+
+// quoteLocations returns every repository-relative file whose normalized text
+// contains the normalized quote, excluding the subject itself.
+func quoteLocations(project, subject, quote string) []string {
+	var found []string
+	_ = filepath.WalkDir(project, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return nil
+		}
+		if d.IsDir() {
+			if path != project && skippedDirs[d.Name()] {
+				return fs.SkipDir
+			}
+			return nil
+		}
+		rel, err := filepath.Rel(project, path)
+		if err != nil {
+			return nil
+		}
+		rel = filepath.ToSlash(rel)
+		if rel == subject {
+			return nil
+		}
+		if text, ok := fileText(path); ok && strings.Contains(text, quote) {
+			found = append(found, rel)
+			if len(found) > 1 {
+				return fs.SkipAll // ambiguous already; stop early
+			}
+		}
+		return nil
+	})
+	return found
+}
+
+// Grade resolves one note's current anchor state against the project tree.
+// The repo-wide relocation scan runs only when the subject no longer carries
+// the quote, so exact notes cost one file read.
+func GradeNote(project string, note *Note) Graded {
+	graded := Graded{Note: note}
+	subjectPath := filepath.Join(project, filepath.FromSlash(note.Subject))
+	subjectText, subjectOK := fileText(subjectPath)
+	quote := normalizeWS(note.Quote)
+	if subjectOK && strings.Contains(subjectText, quote) {
+		graded.Grade = GradeExact
+		return graded
+	}
+	found := quoteLocations(project, note.Subject, quote)
+	switch {
+	case len(found) == 1:
+		graded.Grade = GradeMoved
+		graded.MovedTo = found[0]
+	case len(found) > 1:
+		graded.Grade = GradeAmbiguous
+	case subjectOK:
+		graded.Grade = GradeStale
+	default:
+		graded.Grade = GradeLost
+	}
+	return graded
+}
+
+// GradeAll grades every note in document order.
+func GradeAll(project string, doc *Document) []Graded {
+	out := make([]Graded, 0, len(doc.Notes))
+	for _, note := range doc.Notes {
+		out = append(out, GradeNote(project, note))
+	}
+	return out
+}
+
+// Newline returns the document's original line-ending style for writeback.
+func (d *Document) Newline() string {
+	if d.newline == "" {
+		return "\n"
+	}
+	return d.newline
+}
+
+// NextID returns the lowest unused NOTE-### id, so ids are stable and
+// collision-free under the feature lock.
+func (d *Document) NextID() string {
+	used := map[string]bool{}
+	max := 0
+	for _, note := range d.Notes {
+		used[note.ID] = true
+		var n int
+		if _, err := fmt.Sscanf(note.ID, "NOTE-%d", &n); err == nil && n > max {
+			max = n
+		}
+	}
+	for n := max + 1; ; n++ {
+		id := fmt.Sprintf("NOTE-%03d", n)
+		if !used[id] {
+			return id
+		}
+	}
+}
+
+// Render appends a note entry to existing notes.md text, preserving the
+// document's newline style. An absent or empty document gains its header.
+func Render(text, newline, id, summary, subject, quote, body string) string {
+	entry := "- " + id + ": " + summary + "\n" +
+		"  SUBJECT: " + subject + "\n" +
+		"  QUOTE: " + quote + "\n"
+	if body != "" {
+		entry += "  BODY: " + body + "\n"
+	}
+	if newline == "\r\n" {
+		entry = strings.ReplaceAll(entry, "\n", "\r\n")
+	}
+	if strings.TrimSpace(text) == "" {
+		text = "# Anchored notes" + newline + newline
+	} else if !strings.HasSuffix(text, newline) {
+		text += newline
+	}
+	return text + entry
+}
+
+// RemoveEntry deletes one note block (its `- NOTE-` row through its last
+// contiguous attribute row) from the source text.
+func RemoveEntry(text, newline string, note *Note) string {
+	lines := strings.Split(strings.ReplaceAll(text, "\r\n", "\n"), "\n")
+	end := note.Line
+	for end < len(lines) && attrLineRE.MatchString(lines[end]) {
+		end++
+	}
+	kept := append([]string{}, lines[:note.Line-1]...)
+	kept = append(kept, lines[end:]...)
+	out := strings.Join(kept, "\n")
+	if newline == "\r\n" {
+		out = strings.ReplaceAll(out, "\n", "\r\n")
+	}
+	return out
+}
+
+// RepairSubject rewrites a moved note's SUBJECT line to the new
+// repository-relative path, preserving indentation.
+func RepairSubject(text, newline string, note *Note, movedTo string) string {
+	lines := strings.Split(strings.ReplaceAll(text, "\r\n", "\n"), "\n")
+	idx := note.SubjectLine - 1
+	if idx < 0 || idx >= len(lines) {
+		return text
+	}
+	match := attrLineRE.FindStringSubmatch(lines[idx])
+	if match == nil || match[2] != "SUBJECT" {
+		return text
+	}
+	lines[idx] = match[1] + "SUBJECT: " + movedTo
+	out := strings.Join(lines, "\n")
+	if newline == "\r\n" {
+		out = strings.ReplaceAll(out, "\n", "\r\n")
+	}
+	return out
+}

package/engine/internal/notes/notes_test.go

@@ -0,0 +1,173 @@
+package notes
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func writeFile(t *testing.T, root, rel, body string) {
+	t.Helper()
+	path := filepath.Join(root, filepath.FromSlash(rel))
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+const sampleNotes = `# Anchored notes
+
+- NOTE-001: pool cap rationale
+  SUBJECT: src/pool.go
+  QUOTE: maxConns = 4
+  BODY: fairness under bursty saves, not memory
+- NOTE-002: retry window
+  SUBJECT: src/retry.go
+  QUOTE: backoff = 250 * attempts
+`
+
+func TestParseNotesWellFormed(t *testing.T) {
+	doc := ParseNotes(sampleNotes)
+	if len(doc.Errors) != 0 {
+		t.Fatalf("errors: %v", doc.Errors)
+	}
+	if len(doc.Notes) != 2 {
+		t.Fatalf("notes: %d", len(doc.Notes))
+	}
+	n := doc.Notes[0]
+	if n.ID != "NOTE-001" || n.Subject != "src/pool.go" || n.Quote != "maxConns = 4" || n.Body == "" {
+		t.Fatalf("note: %+v", n)
+	}
+}
+
+func TestParseNotesRejectsMalformed(t *testing.T) {
+	for name, text := range map[string]string{
+		"duplicate id":    "- NOTE-001: a\n  SUBJECT: f.go\n  QUOTE: q\n- NOTE-001: b\n  SUBJECT: g.go\n  QUOTE: r\n",
+		"missing subject": "- NOTE-001: a\n  QUOTE: q\n",
+		"missing quote":   "- NOTE-001: a\n  SUBJECT: f.go\n",
+		"unindented attr": "- NOTE-001: a\nSUBJECT: f.go\n  QUOTE: q\n",
+		"orphan attr":     "  SUBJECT: f.go\n",
+		"traversal":       "- NOTE-001: a\n  SUBJECT: ../f.go\n  QUOTE: q\n",
+		"absolute":        "- NOTE-001: a\n  SUBJECT: /etc/passwd\n  QUOTE: q\n",
+		"empty summary":   "- NOTE-001: \n  SUBJECT: f.go\n  QUOTE: q\n",
+		"repeated quote":  "- NOTE-001: a\n  SUBJECT: f.go\n  QUOTE: q\n  QUOTE: r\n",
+	} {
+		t.Run(name, func(t *testing.T) {
+			if doc := ParseNotes(text); len(doc.Errors) == 0 {
+				t.Fatalf("want errors for %q", text)
+			}
+		})
+	}
+}
+
+func TestParseNotesMasksFencedBlocks(t *testing.T) {
+	text := "# Notes\n\n```\n- NOTE-999: fenced fake\n  SUBJECT: x.go\n  QUOTE: y\n```\n\n" + sampleNotes
+	doc := ParseNotes(text)
+	if len(doc.Errors) != 0 || len(doc.Notes) != 2 {
+		t.Fatalf("notes=%d errors=%v", len(doc.Notes), doc.Errors)
+	}
+}
+
+func TestGradeExactMovedStaleAmbiguousLost(t *testing.T) {
+	project := t.TempDir()
+	writeFile(t, project, "src/pool.go", "package src\n\nconst maxConns = 4\n")
+	writeFile(t, project, "src/retry.go", "package src\n\nvar backoff = 250 * attempts\n")
+
+	doc := ParseNotes(sampleNotes)
+	graded := GradeAll(project, doc)
+	if graded[0].Grade != GradeExact || graded[1].Grade != GradeExact {
+		t.Fatalf("grades: %v %v", graded[0].Grade, graded[1].Grade)
+	}
+
+	// moved: quote relocates to exactly one other file
+	writeFile(t, project, "src/pool.go", "package src\n\nconst maxConns = 8\n")
+	writeFile(t, project, "src/config/limits.go", "package config\nconst maxConns = 4\n")
+	graded = GradeAll(project, doc)
+	if graded[0].Grade != GradeMoved || graded[0].MovedTo != "src/config/limits.go" {
+		t.Fatalf("moved: %+v", graded[0])
+	}
+
+	// ambiguous: quote in two other files
+	writeFile(t, project, "src/config/other.go", "package config\nconst maxConns = 4\n")
+	graded = GradeAll(project, doc)
+	if graded[0].Grade != GradeAmbiguous {
+		t.Fatalf("ambiguous: %+v", graded[0])
+	}
+
+	// stale: subject alive, quote gone everywhere
+	writeFile(t, project, "src/config/other.go", "package config\nconst other = 1\n")
+	writeFile(t, project, "src/config/limits.go", "package config\nconst other = 2\n")
+	graded = GradeAll(project, doc)
+	if graded[0].Grade != GradeStale {
+		t.Fatalf("stale: %+v", graded[0])
+	}
+
+	// lost: subject file deleted entirely
+	if err := os.Remove(filepath.Join(project, "src/pool.go")); err != nil {
+		t.Fatal(err)
+	}
+	graded = GradeAll(project, doc)
+	if graded[0].Grade != GradeLost {
+		t.Fatalf("lost: %+v", graded[0])
+	}
+}
+
+func TestGradeSkipsDependencyAndWorkspaceDirs(t *testing.T) {
+	project := t.TempDir()
+	writeFile(t, project, "src/a.go", "package src\nvar other = 1\n")
+	writeFile(t, project, "node_modules/dep/index.js", "var depAnchor = 1\n")
+	writeFile(t, project, ".devrites/work/f/notes.md", "depAnchor = 1\n")
+	doc := ParseNotes("- NOTE-001: x\n  SUBJECT: src/missing.go\n  QUOTE: depAnchor = 1\n")
+	graded := GradeAll(project, doc)
+	if graded[0].Grade != GradeLost {
+		t.Fatalf("dependency dirs must not count as relocation: %+v", graded[0])
+	}
+}
+
+func TestGradeNormalizesWhitespace(t *testing.T) {
+	project := t.TempDir()
+	writeFile(t, project, "src/a.go", "package src\n\n\tvar   anchor\t=\t1\n")
+	doc := ParseNotes("- NOTE-001: x\n  SUBJECT: src/a.go\n  QUOTE: var anchor = 1\n")
+	if g := GradeAll(project, doc)[0]; g.Grade != GradeExact {
+		t.Fatalf("whitespace-normalized match: %+v", g)
+	}
+}
+
+func TestNextIDFillsLowest(t *testing.T) {
+	doc := ParseNotes("- NOTE-001: a\n  SUBJECT: f\n  QUOTE: q\n- NOTE-003: b\n  SUBJECT: g\n  QUOTE: r\n")
+	if got := doc.NextID(); got != "NOTE-004" {
+		t.Fatalf("NextID = %q", got)
+	}
+}
+
+func TestRenderAndRemoveRoundTrip(t *testing.T) {
+	text := Render("", "\n", "NOTE-001", "first", "a.go", "q1", "body")
+	text = Render(text, "\n", "NOTE-002", "second", "b.go", "q2", "")
+	doc := ParseNotes(text)
+	if len(doc.Errors) != 0 || len(doc.Notes) != 2 {
+		t.Fatalf("render parse: %v / %d", doc.Errors, len(doc.Notes))
+	}
+	removed := RemoveEntry(text, "\n", doc.Notes[0])
+	doc = ParseNotes(removed)
+	if len(doc.Notes) != 1 || doc.Notes[0].ID != "NOTE-002" {
+		t.Fatalf("after remove: %+v", doc.Notes)
+	}
+	if strings.Contains(removed, "NOTE-001") {
+		t.Fatal("removed text still carries NOTE-001")
+	}
+}
+
+func TestRepairSubjectRewritesOnlyThatLine(t *testing.T) {
+	doc := ParseNotes(sampleNotes)
+	note := doc.Notes[0]
+	out := RepairSubject(sampleNotes, "\n", note, "src/new/pool.go")
+	if !strings.Contains(out, "  SUBJECT: src/new/pool.go") {
+		t.Fatalf("repair out: %q", out)
+	}
+	if !strings.Contains(out, "SUBJECT: src/retry.go") {
+		t.Fatal("repair touched the other note")
+	}
+}

package/engine/internal/parallel/lease.go

@@ -8,6 +8,8 @@ import (
 	"regexp"
 	"strings"
 	"time"
+
+	"github.com/devrites/devrites/internal/fsutil"
 )
 
 const (
@@ -219,14 +221,7 @@ func WriteLease(path string, lease *Lease) error {
 	if err != nil {
 		return err
 	}
-	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
-		return err
-	}
-	tmp := path + ".tmp"
-	if err := os.WriteFile(tmp, []byte(text), 0o644); err != nil {
-		return err
-	}
-	return os.Rename(tmp, path)
+	return fsutil.WriteFileAtomic(path, []byte(text), 0o644)
 }
 
 func ReadLease(path string) (*Lease, error) {

package/engine/internal/parallel/parallel_test.go

@@ -78,6 +78,40 @@ func TestLeaseRoundTrip(t *testing.T) {
 	}
 }
 
+func TestWriteLeasePreservesFixedTemp(t *testing.T) {
+	for _, directory := range []bool{false, true} {
+		t.Run(fmt.Sprint(directory), func(t *testing.T) {
+			path := filepath.Join(t.TempDir(), "lease.md")
+			sentinel := path + ".tmp"
+			if directory {
+				if err := os.Mkdir(sentinel, 0755); err != nil {
+					t.Fatal(err)
+				}
+			} else if err := os.WriteFile(sentinel, []byte("owned elsewhere"), 0644); err != nil {
+				t.Fatal(err)
+			}
+			lease := &Lease{BatchID: "batch", CreatedAt: "now", BaseSHA: "abcdef1", N: 2, Status: StatusRunning, Slices: []LeaseSlice{{ID: "a", Paths: []string{"a.go"}}, {ID: "b", Paths: []string{"b.go"}}}}
+			if err := WriteLease(path, lease); err != nil {
+				t.Fatal(err)
+			}
+			if _, err := ReadLease(path); err != nil {
+				t.Fatal(err)
+			}
+			if directory {
+				info, err := os.Stat(sentinel)
+				if err != nil || !info.IsDir() {
+					t.Fatalf("sentinel changed: %v", err)
+				}
+			} else {
+				raw, err := os.ReadFile(sentinel)
+				if err != nil || string(raw) != "owned elsewhere" {
+					t.Fatalf("sentinel changed: %q %v", raw, err)
+				}
+			}
+		})
+	}
+}
+
 func TestCreateAbortCleanup(t *testing.T) {
 	repo, base := setupRepo(t)
 	slug := "demo-feature"

package/engine/internal/state/budgets.go

@@ -41,6 +41,7 @@ var artifactLineBudgets = map[string]int{
 	"traceability.md":      220,
 	"eng-review.md":        240,
 	"test-plan.md":         260,
+	"gates.md":             200,
 	"state.md":             120,
 	"evidence.md":          280,
 	"browser-evidence.md":  220,
@@ -53,6 +54,8 @@ var artifactLineBudgets = map[string]int{
 	"review.md":            240,
 	"seal.md":              200,
 	"ai-spec.md":           160,
+	"windows.md":           120,
+	"notes.md":             160,
 }
 
 // advisoryOnlyArtifacts are append-only proof ledgers: they scale with proof
@@ -73,15 +76,17 @@ func ArtifactLineBudget(name string) (int, bool) {
 
 // sanctionedRootFiles are workspace-root files the schema places there without a
 // line budget: conditional artifacts (`references.md`, `investigation-map.md`,
-// `dogfood.md`) and the engine-owned parallel lease. Anything else in the root
-// is unsanctioned placement — `packets/` and `history/` own by-reference
-// packets and relocated narrative (workspace-artifact-schema.md "Required by
-// phase").
+// `dogfood.md`) and engine-owned machine files (the parallel lease, the metrics
+// ledger, the regression baseline). Anything else in the root is unsanctioned
+// placement — `packets/` and `history/` own by-reference packets and relocated
+// narrative (workspace-artifact-schema.md "Required by phase").
 var sanctionedRootFiles = map[string]bool{
-	"references.md":        true,
-	"investigation-map.md": true,
-	"dogfood.md":           true,
-	"parallel-lease.md":    true,
+	"references.md":            true,
+	"investigation-map.md":     true,
+	"dogfood.md":               true,
+	"parallel-lease.md":        true,
+	"metrics.jsonl":            true,
+	"regression-baseline.json": true,
 }
 
 // SanctionedRootFile reports whether name is a legitimate workspace-root file:

package/engine/internal/state/observation_test.go

@@ -26,6 +26,7 @@ func TestWorkspaceObservationInventoryCanonicalArtifactsOnce(t *testing.T) {
 		"traceability.md",
 		"eng-review.md",
 		"test-plan.md",
+		"gates.md",
 		"evidence.md",
 		"touched-files.md",
 		"review.md",

package/engine/internal/state/schema.go

@@ -3,8 +3,9 @@ package state
 //go:generate go run ./cmd/workflowmanifest -out workflow_manifest.json
 
 // SchemaVersion versions the persisted workflow/state manifest and the
-// workspace contract the engine accepts.
-const SchemaVersion = 3
+// workspace contract the engine accepts. Schema 4 adds the gates.md
+// acceptance ledger to the vetted artifact set.
+const SchemaVersion = 4
 
 const EvidenceFile = "evidence.md"
 
@@ -93,7 +94,7 @@ var (
 	artifactsSpec    = []ArtifactPath{"brief.md", "spec.md", "state.md", "decisions.md", "assumptions.md", "questions.md"}
 	artifactsClarify = append(append([]ArtifactPath(nil), artifactsSpec...), "decision-coverage.md")
 	artifactsPlan    = append(append([]ArtifactPath(nil), artifactsClarify...), "architecture.md", "plan.md", "tasks.md", "traceability.md")
-	artifactsVetted  = append(append([]ArtifactPath(nil), artifactsPlan...), "eng-review.md", "test-plan.md")
+	artifactsVetted  = append(append([]ArtifactPath(nil), artifactsPlan...), "eng-review.md", "test-plan.md", "gates.md")
 	artifactsProof   = append(append([]ArtifactPath(nil), artifactsVetted...), "evidence.md", "touched-files.md")
 	artifactsFinal   = append(append([]ArtifactPath(nil), artifactsProof...), "review.md", "seal.md")
 )