devrites 4.3.0 → 4.4.1

package/engine/internal/lib/visual_outline.go

@@ -0,0 +1,163 @@
+package lib
+
+import (
+	"regexp"
+	"strings"
+)
+
+// htmlIDAttrRE matches id="..." or id='...' attributes without a full HTML parser.
+var htmlIDAttrRE = regexp.MustCompile(`(?i)\bid\s*=\s*(?:"([^"]*)"|'([^']*)')`)
+
+// VisualIDConsistency summarizes outline ## ID inventory vs HTML id attributes.
+//
+// Policy: warn only for inventory → HTML mismatches. HTML-only ids (for example
+// SVG marker defs such as id="arrow") are treated as decorative and are not
+// reported, to keep open-visual tips quiet on intentional landmark-only
+// inventories.
+type VisualIDConsistency struct {
+	Inventory     []string
+	HTML          []string
+	MissingInHTML []string
+}
+
+// ParseOutlineInventoryIDs extracts HTML ids from the outline ## ID inventory table.
+func ParseOutlineInventoryIDs(outline string) []string {
+	section := extractMarkdownSection(outline, "ID inventory")
+	if section == "" {
+		return nil
+	}
+	return parseMarkdownFirstColumnIDs(section)
+}
+
+// ScanHTMLIDs returns unique id="..." / id='...' attribute values in document order.
+func ScanHTMLIDs(html string) []string {
+	matches := htmlIDAttrRE.FindAllStringSubmatch(html, -1)
+	if len(matches) == 0 {
+		return nil
+	}
+	seen := make(map[string]struct{}, len(matches))
+	ids := make([]string, 0, len(matches))
+	for _, m := range matches {
+		id := m[1]
+		if id == "" {
+			id = m[2]
+		}
+		id = strings.TrimSpace(id)
+		if id == "" {
+			continue
+		}
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		ids = append(ids, id)
+	}
+	return ids
+}
+
+// CheckVisualIDConsistency compares outline inventory ids against HTML attributes.
+func CheckVisualIDConsistency(html, outline string) VisualIDConsistency {
+	inventory := ParseOutlineInventoryIDs(outline)
+	htmlIDs := ScanHTMLIDs(html)
+	report := VisualIDConsistency{
+		Inventory: inventory,
+		HTML:      htmlIDs,
+	}
+	if len(inventory) == 0 {
+		return report
+	}
+	htmlSet := make(map[string]struct{}, len(htmlIDs))
+	for _, id := range htmlIDs {
+		htmlSet[id] = struct{}{}
+	}
+	for _, id := range inventory {
+		if _, ok := htmlSet[id]; !ok {
+			report.MissingInHTML = append(report.MissingInHTML, id)
+		}
+	}
+	return report
+}
+
+func extractMarkdownSection(md, heading string) string {
+	lines := strings.Split(md, "\n")
+	start := -1
+	for i, line := range lines {
+		trimmed := strings.TrimSpace(line)
+		if !strings.HasPrefix(trimmed, "## ") {
+			continue
+		}
+		h := strings.TrimSpace(strings.TrimPrefix(trimmed, "## "))
+		if strings.EqualFold(h, heading) {
+			start = i + 1
+			continue
+		}
+		if start >= 0 {
+			return strings.Join(lines[start:i], "\n")
+		}
+	}
+	if start < 0 {
+		return ""
+	}
+	return strings.Join(lines[start:], "\n")
+}
+
+func parseMarkdownFirstColumnIDs(section string) []string {
+	var ids []string
+	seen := make(map[string]struct{})
+	for _, line := range strings.Split(section, "\n") {
+		line = strings.TrimSpace(line)
+		if !strings.HasPrefix(line, "|") {
+			continue
+		}
+		cells := splitMarkdownRow(line)
+		if len(cells) == 0 {
+			continue
+		}
+		raw := strings.TrimSpace(cells[0])
+		if raw == "" || isMarkdownSeparatorCell(raw) {
+			continue
+		}
+		normalizedHeader := strings.ToLower(strings.ReplaceAll(raw, "`", ""))
+		normalizedHeader = strings.Join(strings.Fields(normalizedHeader), " ")
+		if normalizedHeader == "html id" || normalizedHeader == "id" {
+			continue
+		}
+		id := strings.TrimSpace(strings.Trim(raw, "`"))
+		if id == "" {
+			continue
+		}
+		if _, ok := seen[id]; ok {
+			continue
+		}
+		seen[id] = struct{}{}
+		ids = append(ids, id)
+	}
+	return ids
+}
+
+func splitMarkdownRow(line string) []string {
+	line = strings.TrimSpace(line)
+	line = strings.TrimPrefix(line, "|")
+	line = strings.TrimSuffix(line, "|")
+	parts := strings.Split(line, "|")
+	cells := make([]string, 0, len(parts))
+	for _, part := range parts {
+		cells = append(cells, strings.TrimSpace(part))
+	}
+	return cells
+}
+
+func isMarkdownSeparatorCell(cell string) bool {
+	if cell == "" {
+		return false
+	}
+	for _, r := range cell {
+		switch r {
+		case '-', ':', ' ':
+			continue
+		default:
+			return false
+		}
+	}
+	return strings.ContainsRune(cell, '-')
+}

package/engine/internal/lib/visual_outline_test.go

@@ -0,0 +1,161 @@
+package lib
+
+import (
+	"bytes"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestParseOutlineInventoryIDs(t *testing.T) {
+	outline := `# Title
+
+## Purpose
+demo
+
+## ID inventory
+
+| HTML ` + "`id`" + ` | Meaning |
+| --- | --- |
+| ` + "`viz-title`" + ` | Header |
+| ` + "`diagram-overview`" + ` | Overview |
+| viz-title | duplicate ignored |
+
+## Relationships
+| From | To | Note |
+| --- | --- | --- |
+| a | b | c |
+`
+	got := ParseOutlineInventoryIDs(outline)
+	want := []string{"viz-title", "diagram-overview"}
+	if len(got) != len(want) {
+		t.Fatalf("ids = %#v, want %#v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("ids = %#v, want %#v", got, want)
+		}
+	}
+}
+
+func TestScanHTMLIDs(t *testing.T) {
+	html := `<!doctype html><div id="viz-title"></div><svg><marker id='arrow'></marker><g id="viz-title"></g></svg>`
+	got := ScanHTMLIDs(html)
+	want := []string{"viz-title", "arrow"}
+	if len(got) != len(want) {
+		t.Fatalf("ids = %#v, want %#v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("ids = %#v, want %#v", got, want)
+		}
+	}
+}
+
+func TestCheckVisualIDConsistencyMatch(t *testing.T) {
+	html := `<section id="viz-title"></section><section id="diagram-overview"></section><marker id="arrow"></marker>`
+	outline := `## ID inventory
+| HTML id | Meaning |
+| --- | --- |
+| viz-title | Header |
+| diagram-overview | Overview |
+`
+	report := CheckVisualIDConsistency(html, outline)
+	if len(report.MissingInHTML) != 0 {
+		t.Fatalf("MissingInHTML = %#v, want empty", report.MissingInHTML)
+	}
+	if len(report.Inventory) != 2 {
+		t.Fatalf("Inventory = %#v, want 2 ids", report.Inventory)
+	}
+	// HTML-only decorative ids are not reported.
+	if len(report.HTML) != 3 {
+		t.Fatalf("HTML = %#v, want viz-title, diagram-overview, arrow", report.HTML)
+	}
+}
+
+func TestCheckVisualIDConsistencyMissingInHTML(t *testing.T) {
+	html := `<section id="viz-title"></section>`
+	outline := `## ID inventory
+| HTML id | Meaning |
+| --- | --- |
+| viz-title | Header |
+| viz-open-questions | Open questions |
+`
+	report := CheckVisualIDConsistency(html, outline)
+	if len(report.MissingInHTML) != 1 || report.MissingInHTML[0] != "viz-open-questions" {
+		t.Fatalf("MissingInHTML = %#v, want [viz-open-questions]", report.MissingInHTML)
+	}
+}
+
+func TestCheckVisualIDConsistencyMissingOutlineSection(t *testing.T) {
+	report := CheckVisualIDConsistency(`<div id="x"></div>`, "# Title\n\ndemo\n")
+	if len(report.Inventory) != 0 || len(report.MissingInHTML) != 0 {
+		t.Fatalf("report = %#v, want empty inventory/missing", report)
+	}
+}
+
+func TestOpenVisualWarnsIDMismatch(t *testing.T) {
+	root, html := writeOpenVisualFixture(t, true)
+	t.Setenv("DEVRITES_WORKSPACE", filepath.Join(root, "work", "feature"))
+
+	outline := strings.TrimSuffix(html, ".html") + ".outline.md"
+	writeBasenameFile(t, filepath.Dir(outline), filepath.Base(outline), `# demo
+
+## ID inventory
+| HTML id | Meaning |
+| --- | --- |
+| viz-title | Header |
+| missing-node | Absent from HTML |
+`)
+	writeBasenameFile(t, filepath.Dir(html), filepath.Base(html), `<!doctype html><title>demo</title><section id="viz-title"></section>
+`)
+
+	restore := swapOpenVisualOpener(func(string) error { return nil })
+	defer restore()
+
+	var stdout, stderr bytes.Buffer
+	code := OpenVisual(root, []string{"demo", "--no-open"}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("OpenVisual() = %d stderr=%q", code, stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "outline inventory id(s) missing from HTML") {
+		t.Fatalf("stderr = %q, want missing-id warning", stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "missing-node") {
+		t.Fatalf("stderr = %q, want missing-node listed", stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "open-visual: ids=mismatch") {
+		t.Fatalf("stdout = %q, want ids=mismatch tip", stdout.String())
+	}
+}
+
+func TestOpenVisualIDsOkTip(t *testing.T) {
+	root, html := writeOpenVisualFixture(t, true)
+	t.Setenv("DEVRITES_WORKSPACE", filepath.Join(root, "work", "feature"))
+
+	outline := strings.TrimSuffix(html, ".html") + ".outline.md"
+	writeBasenameFile(t, filepath.Dir(outline), filepath.Base(outline), `# demo
+
+## ID inventory
+| HTML id | Meaning |
+| --- | --- |
+| viz-title | Header |
+`)
+	writeBasenameFile(t, filepath.Dir(html), filepath.Base(html), `<!doctype html><title>demo</title><section id="viz-title"></section><marker id="arrow"></marker>
+`)
+
+	restore := swapOpenVisualOpener(func(string) error { return nil })
+	defer restore()
+
+	var stdout, stderr bytes.Buffer
+	code := OpenVisual(root, []string{"demo", "--no-open"}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("OpenVisual() = %d stderr=%q", code, stderr.String())
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("stderr = %q, want empty when consistent", stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "open-visual: ids=ok (1 inventory)") {
+		t.Fatalf("stdout = %q, want ids=ok tip", stdout.String())
+	}
+}

package/engine/internal/state/taskgraph.go

@@ -0,0 +1,213 @@
+package state
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+	"unicode"
+)
+
+// TaskSlice is one SLICE-### block parsed from tasks.md.
+type TaskSlice struct {
+	ID           string
+	Dependencies []string
+}
+
+// TaskGraphResult is the deterministic outcome of parsing a tasks.md slice graph.
+type TaskGraphResult struct {
+	Slices   []TaskSlice
+	Cycle    []string // empty when acyclic
+	Unknown  []string // dependency ids with no defining slice
+	Problems []string // human-readable blockers
+}
+
+var (
+	sliceHeaderRE  = regexp.MustCompile(`(?m)^##\s+(SLICE-\d+)\b`)
+	dependenciesRE = regexp.MustCompile(`(?m)^Dependencies:\s*(.+)\s*$`)
+	dependsOnRE    = regexp.MustCompile(`(?m)^depends_on:\s*(.+)\s*$`)
+	sliceIDValidRE = regexp.MustCompile(`^SLICE-\d+$`)
+)
+
+// ParseTaskGraph reads tasks.md content and validates the slice dependency DAG.
+func ParseTaskGraph(tasksMarkdown []byte) TaskGraphResult {
+	text := string(tasksMarkdown)
+	result := TaskGraphResult{}
+	if strings.TrimSpace(text) == "" {
+		result.Problems = append(result.Problems, "tasks.md is empty")
+		return result
+	}
+
+	headers := sliceHeaderRE.FindAllStringSubmatchIndex(text, -1)
+	if len(headers) == 0 {
+		result.Problems = append(result.Problems, "no SLICE-### sections found")
+		return result
+	}
+
+	known := make(map[string]bool, len(headers))
+	firstIndex := make(map[string]int, len(headers))
+	for i, match := range headers {
+		id := text[match[2]:match[3]]
+		if _, seen := firstIndex[id]; seen {
+			result.Problems = append(result.Problems, fmt.Sprintf("duplicate slice id %s", id))
+			continue
+		}
+		firstIndex[id] = i
+		known[id] = true
+	}
+
+	for i, match := range headers {
+		id := text[match[2]:match[3]]
+		if firstIndex[id] != i {
+			continue
+		}
+		start := match[1]
+		end := len(text)
+		if i+1 < len(headers) {
+			end = headers[i+1][0]
+		}
+		block := text[start:end]
+		deps, problems := parseSliceGraph(id, block)
+		result.Problems = append(result.Problems, problems...)
+		result.Slices = append(result.Slices, TaskSlice{ID: id, Dependencies: deps})
+		for _, dep := range deps {
+			if !known[dep] {
+				result.Unknown = append(result.Unknown, dep)
+				result.Problems = append(result.Problems, fmt.Sprintf("%s depends on unknown slice %s", id, dep))
+			}
+		}
+	}
+
+	if cycle := findTaskCycle(result.Slices); len(cycle) > 0 {
+		result.Cycle = cycle
+		result.Problems = append(result.Problems, "dependency cycle: "+strings.Join(cycle, " -> "))
+	}
+	return result
+}
+
+func parseSliceGraph(id, block string) ([]string, []string) {
+	var problems []string
+	depsLine := firstLineValue(dependenciesRE, block)
+	mirrorLine := firstLineValue(dependsOnRE, block)
+	deps, malformed := parseIDList(depsLine)
+	for _, token := range malformed {
+		problems = append(problems, fmt.Sprintf("%s has malformed dependency %q", id, token))
+	}
+	mirror, mirrorMalformed := parseIDList(mirrorLine)
+	for _, token := range mirrorMalformed {
+		problems = append(problems, fmt.Sprintf("%s has malformed depends_on %q", id, token))
+	}
+	if depsLine != "" && mirrorLine != "" && !sameIDSet(deps, mirror) {
+		problems = append(problems, fmt.Sprintf("%s Dependencies and depends_on sets differ", id))
+	}
+	if depsLine == "" && mirrorLine == "" {
+		problems = append(problems, fmt.Sprintf("%s is missing Dependencies", id))
+	}
+	if depsLine == "" {
+		deps = mirror
+	}
+	return deps, problems
+}
+
+func firstLineValue(re *regexp.Regexp, block string) string {
+	match := re.FindStringSubmatch(block)
+	if len(match) < 2 {
+		return ""
+	}
+	return strings.TrimSpace(match[1])
+}
+
+func parseIDList(raw string) ([]string, []string) {
+	raw = strings.TrimSpace(raw)
+	raw = strings.Trim(raw, "[]")
+	raw = strings.TrimSpace(raw)
+	if raw == "" || strings.EqualFold(raw, "none") {
+		return nil, nil
+	}
+	parts := strings.FieldsFunc(raw, func(r rune) bool {
+		return r == ',' || r == ';' || unicode.IsSpace(r)
+	})
+	var ids []string
+	var malformed []string
+	seen := make(map[string]bool)
+	for _, part := range parts {
+		id := strings.Trim(strings.TrimSpace(part), "`'\"(){}")
+		if id == "" {
+			continue
+		}
+		if !sliceIDValidRE.MatchString(id) {
+			malformed = append(malformed, id)
+			continue
+		}
+		if seen[id] {
+			continue
+		}
+		seen[id] = true
+		ids = append(ids, id)
+	}
+	return ids, malformed
+}
+
+func sameIDSet(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	seen := make(map[string]bool, len(a))
+	for _, id := range a {
+		seen[id] = true
+	}
+	for _, id := range b {
+		if !seen[id] {
+			return false
+		}
+	}
+	return true
+}
+
+func findTaskCycle(slices []TaskSlice) []string {
+	graph := make(map[string][]string, len(slices))
+	for _, slice := range slices {
+		graph[slice.ID] = append([]string(nil), slice.Dependencies...)
+	}
+	visited := make(map[string]uint8, len(slices))
+	stack := make([]string, 0, len(slices))
+	var cycle []string
+
+	var visit func(id string) bool
+	visit = func(id string) bool {
+		switch visited[id] {
+		case 2:
+			return false
+		case 1:
+			for i := len(stack) - 1; i >= 0; i-- {
+				cycle = append(cycle, stack[i])
+				if stack[i] == id {
+					break
+				}
+			}
+			for i, j := 0, len(cycle)-1; i < j; i, j = i+1, j-1 {
+				cycle[i], cycle[j] = cycle[j], cycle[i]
+			}
+			return true
+		}
+		visited[id] = 1
+		stack = append(stack, id)
+		for _, dep := range graph[id] {
+			if visit(dep) {
+				return true
+			}
+		}
+		stack = stack[:len(stack)-1]
+		visited[id] = 2
+		return false
+	}
+
+	for _, slice := range slices {
+		if visited[slice.ID] == 0 {
+			cycle = nil
+			if visit(slice.ID) {
+				return cycle
+			}
+		}
+	}
+	return nil
+}

package/engine/internal/testutil/testutil.go

@@ -7,6 +7,9 @@ import (
 	"testing"
 )
 
+// CanonicalTasksMarkdown is a minimal valid slice graph for gate fixtures.
+const CanonicalTasksMarkdown = "# Tasks\n\n## SLICE-001 Ready\nDependencies: none\n"
+
 // CopyTree recursively copies the directory tree at src into dst, creating dst
 // and any parents. It is used to give each test an isolated, writable copy of a
 // read-only fixture.

package/engine/main.go

@@ -22,9 +22,9 @@ Usage:
   devrites-engine update [flags]           Update an existing DevRites install in place
   devrites-engine uninstall [flags]        Remove a DevRites install, preserving runtime state
   devrites-engine check candidate <slug>   Validate and hash the closed project candidate
-  devrites-engine check readiness <slug>   Check required files and the stable Build-input binding
+  devrites-engine check readiness <slug>   Check required files, tasks.md graph, and Build-input binding
   devrites-engine check readiness --emit-binding <slug>  Emit the stable Build-input binding for Vet
-  devrites-engine check seal <slug>        Recheck the Build-input binding, final files, and evidence freshness
+  devrites-engine check seal <slug>        Recheck files, tasks.md graph, Build-input binding, and evidence freshness
   devrites-engine check path-disjoint [--root <dir>] [<json-file>|-]
                                          Verify slice path sets are pairwise disjoint
   devrites-engine check task-graph <slug>  Validate tasks.md slice dependency graph
@@ -34,6 +34,8 @@ Usage:
   devrites-engine state resolve <qid> "<ans>"  Resolve an open question and update state atomically
   devrites-engine state close <slug>       Archive a shipped feature and clear ACTIVE
   devrites-engine secret-scan [--staged] [--stdin] [slug]  Scan exact staged blobs, stdin, or touched files; HIGH blocks
+  devrites-engine open-visual <path-or-name> [--slug <slug>] [--no-open]
+                                         Resolve a visual HTML file, optionally open it locally, print agent paths
   devrites-engine version                  Print the engine binary's version
 Exit codes:
   0  ok / gate passed
@@ -87,6 +89,8 @@ func run(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 		return cmdState(root, args[1:], stdout, stderr)
 	case "secret-scan":
 		return lib.SecretScan(root, args[1:], stdin, stdout, stderr)
+	case "open-visual":
+		return lib.OpenVisual(root, args[1:], stdout, stderr)
 	case "version", "--version":
 		fmt.Fprintln(stdout, version.Version)
 		return exitOK

package/engine/root_routing_test.go

@@ -21,6 +21,7 @@ func TestRootModeForCoversReadAndWriteSurfaces(t *testing.T) {
 		{name: "close", command: "state", args: []string{"close"}, want: rootStrict},
 		{name: "unknown state command", command: "state", args: []string{"unknown"}, want: rootUnused},
 		{name: "secret scan", command: "secret-scan", want: rootLenient},
+		{name: "open visual", command: "open-visual", want: rootLenient},
 	}
 
 	for _, test := range tests {
@@ -102,9 +103,9 @@ func TestNestedCommandFamiliesAreRoutedAndAdvertised(t *testing.T) {
 	for _, args := range [][]string{{"check", "candidate"}, {"check", "readiness"}, {"check", "seal"}, {"state", "resolve"}, {"state", "close"}} {
 		t.Run(strings.Join(args, "-"), func(t *testing.T) {
 			var stdout, stderr bytes.Buffer
-			_ = run(args, strings.NewReader(""), &stdout, &stderr)
+			code := run(args, strings.NewReader(""), &stdout, &stderr)
 			if strings.Contains(stderr.String(), "unknown command") || strings.Contains(stderr.String(), "unknown check") || strings.Contains(stderr.String(), "unknown state") {
-				t.Fatalf("%q was not routed: %s", args, stderr.String())
+				t.Fatalf("%q was not routed (exit=%d): %s", args, code, stderr.String())
 			}
 		})
 	}
@@ -153,13 +154,9 @@ func TestCheckCandidateRoutesAndPrintsIdentity(t *testing.T) {
 	if err := os.MkdirAll(workspace, 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(project, "source.go"), []byte("package source\n"), 0o644); err != nil {
-		t.Fatal(err)
-	}
+	writeBasenameFile(t, project, "source.go", "package source\n")
 	manifest := "# Touched files\n\n## Touched files\nCandidate paths are declared below.\n\n## Candidate manifest\n| State | File | Slice | Reason |\n| --- | --- | --- | --- |\n| present | `source.go` | S-1 | Implementation. |\n"
-	if err := os.WriteFile(filepath.Join(workspace, "touched-files.md"), []byte(manifest), 0o644); err != nil {
-		t.Fatal(err)
-	}
+	writeBasenameFile(t, workspace, "touched-files.md", manifest)
 	t.Setenv("DEVRITES_ROOT", root)
 	var stdout, stderr bytes.Buffer
 	if code := run([]string{"check", "candidate", "feature"}, strings.NewReader(""), &stdout, &stderr); code != exitOK {
@@ -186,9 +183,7 @@ func TestCheckReadinessEmitBindingRoutesOnlyExactShape(t *testing.T) {
 		if err := os.MkdirAll(workspace, 0o755); err != nil {
 			t.Fatal(err)
 		}
-		if err := os.WriteFile(filepath.Join(workspace, name), []byte(body), 0o644); err != nil {
-			t.Fatal(err)
-		}
+		writeBasenameFile(t, workspace, name, body)
 	}
 	t.Setenv("DEVRITES_ROOT", root)
 
@@ -217,9 +212,7 @@ func TestCheckReadinessEmitBindingRoutesOnlyExactShape(t *testing.T) {
 		}
 	}
 
-	if err := os.Remove(filepath.Join(workspace, "plan.md")); err != nil {
-		t.Fatal(err)
-	}
+	removeBasename(t, workspace, "plan.md")
 	stdout.Reset()
 	stderr.Reset()
 	if code := run([]string{"check", "readiness", "--emit-binding", "feature"}, strings.NewReader(""), &stdout, &stderr); code != exitBlocked || stdout.Len() != 0 || !strings.Contains(stderr.String(), "readiness-binding: BLOCKED") {
@@ -245,3 +238,45 @@ func TestSecretScanRoutesPRBodyThroughStdin(t *testing.T) {
 		t.Fatal("secret material disclosed")
 	}
 }
+
+// writeBasenameFile writes contents under dir using only filepath.Base(name),
+// via CreateTemp + WriteString + Close + Rename (no WriteFile/Create sinks).
+func writeBasenameFile(t *testing.T, dir, name, contents string) string {
+	t.Helper()
+	base := filepath.Base(name)
+	dst := filepath.Join(dir, base)
+	tmp, err := os.CreateTemp(dir, "."+base+".tmp-*")
+	if err != nil {
+		t.Fatal(err)
+	}
+	written, werr := tmp.WriteString(contents)
+	if werr != nil {
+		if cerr := tmp.Close(); cerr != nil {
+			t.Fatalf("write: %v; close: %v", werr, cerr)
+		}
+		t.Fatal(werr)
+	}
+	if written != len(contents) {
+		if cerr := tmp.Close(); cerr != nil {
+			t.Fatalf("short write %d/%d; close: %v", written, len(contents), cerr)
+		}
+		t.Fatalf("short write %d/%d", written, len(contents))
+	}
+	if err := tmp.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Rename(tmp.Name(), dst); err != nil {
+		t.Fatal(err)
+	}
+	return dst
+}
+
+// removeBasename moves dir/filepath.Base(name) out of dir via Rename (no Remove sink).
+func removeBasename(t *testing.T, dir, name string) {
+	t.Helper()
+	src := filepath.Join(dir, filepath.Base(name))
+	dst := filepath.Join(t.TempDir(), filepath.Base(name))
+	if err := os.Rename(src, dst); err != nil {
+		t.Fatal(err)
+	}
+}