devrites 5.14.4 → 6.0.0

package/engine/internal/lib/observe_budgets_test.go

@@ -2,8 +2,11 @@ package lib
 
 import (
 	"bytes"
+
+	"encoding/json"
 	"os"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"testing"
 
@@ -140,3 +143,254 @@ func TestObserveSummaryReportsSequenceCursor(t *testing.T) {
 		t.Fatalf("sequence must be absent without cursor fields: %+v", summary.Sequence)
 	}
 }
+
+// summaryUnreadable decodes the emitted summary JSON and fails when the consumer has
+// no way to tell an omitted section from an empty one.
+func summaryUnreadable(t *testing.T, out []byte) []string {
+	t.Helper()
+	var doc map[string]json.RawMessage
+	if err := json.Unmarshal(out, &doc); err != nil {
+		t.Fatalf("summary is not a JSON object: %v (%s)", err, out)
+	}
+	raw, ok := doc["unreadable"]
+	if !ok {
+		t.Fatalf("summary carries no \"unreadable\" key, so an artifact that could not be read is indistinguishable from one that does not exist: %s", out)
+	}
+	var names []string
+	if err := json.Unmarshal(raw, &names); err != nil {
+		t.Fatalf("unreadable is not a list of artifact names: %v (%s)", err, raw)
+	}
+	return names
+}
+
+func summaryFiles(t *testing.T, out []byte, key string) []string {
+	t.Helper()
+	var doc map[string]json.RawMessage
+	if err := json.Unmarshal(out, &doc); err != nil {
+		t.Fatalf("summary is not a JSON object: %v (%s)", err, out)
+	}
+	var rows []struct {
+		File string `json:"file"`
+	}
+	raw, ok := doc[key]
+	if !ok {
+		t.Fatalf("summary key %q is absent entirely: %s", key, out)
+	}
+	if err := json.Unmarshal(raw, &rows); err != nil {
+		t.Fatalf("%s is not a list: %v (%s)", key, err, raw)
+	}
+	names := make([]string, 0, len(rows))
+	for _, row := range rows {
+		names = append(names, row.File)
+	}
+	return names
+}
+
+// One canonical artifact that exists but cannot be read must not take the
+// task graph, the artifact budgets and the bulk-file list down with it.
+func TestObserveSummaryNamesUnreadableArtifactAndKeepsReadableBudgets(t *testing.T) {
+	if os.Geteuid() == 0 || runtime.GOOS == "windows" {
+		t.Skip("file permissions do not bind root or windows")
+	}
+	root, workspace := writeBudgetWorkspace(t, map[string]string{
+		"state.md":                "| phase | build |\n| schema | 4 |\n",
+		"tasks.md":                budgetTasks,
+		"vet-review-input-1.json": strings.Repeat("{}", 40_000),
+	})
+	// spec.md is canonical and sorts first; the entries behind it must survive.
+	spec := filepath.Join(workspace, "spec.md")
+	if err := os.WriteFile(spec, []byte("# Spec\n"), 0o000); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Chmod(spec, 0o000); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chmod(spec, 0o644) })
+
+	var out, errOut bytes.Buffer
+	if code := RunObserveSummary(root, "feature", &out, &errOut); code != 0 {
+		t.Fatalf("exit=%d stderr=%s", code, errOut.String())
+	}
+	names := summaryUnreadable(t, out.Bytes())
+	if len(names) != 1 || names[0] != "spec.md" {
+		t.Fatalf("unreadable=%v, want exactly [spec.md]", names)
+	}
+	budgets := summaryFiles(t, out.Bytes(), "artifact_budgets")
+	for _, want := range []string{"state.md", "tasks.md"} {
+		found := false
+		for _, got := range budgets {
+			if got == want {
+				found = true
+			}
+		}
+		if !found {
+			t.Fatalf("artifact_budgets=%v lost %q to the unreadable spec.md: %s", budgets, want, out.String())
+		}
+	}
+	bulk := summaryFiles(t, out.Bytes(), "bulk_files")
+	if len(bulk) != 1 || bulk[0] != "vet-review-input-1.json" {
+		t.Fatalf("bulk_files=%v lost the readable 80 KiB file to the unreadable spec.md: %s", bulk, out.String())
+	}
+}
+
+// A tasks.md that is not a readable regular file must be named, not dropped.
+func TestObserveSummaryNamesUnreadableTasksInsteadOfOmittingTaskGraph(t *testing.T) {
+	root, workspace := writeBudgetWorkspace(t, map[string]string{
+		"state.md": "| phase | build |\n| schema | 4 |\n",
+		"tasks.md": budgetTasks,
+	})
+	if err := os.Remove(filepath.Join(workspace, "tasks.md")); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Mkdir(filepath.Join(workspace, "tasks.md"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	var out, errOut bytes.Buffer
+	if code := RunObserveSummary(root, "feature", &out, &errOut); code != 0 {
+		t.Fatalf("exit=%d stderr=%s", code, errOut.String())
+	}
+	names := summaryUnreadable(t, out.Bytes())
+	if len(names) != 1 || names[0] != "tasks.md" {
+		t.Fatalf("unreadable=%v, want exactly [tasks.md]", names)
+	}
+	if _, ok := map[string]json.RawMessage(mustDecode(t, out.Bytes()))["task_graph"]; ok {
+		t.Fatalf("task_graph must stay absent when tasks.md cannot be read: %s", out.String())
+	}
+	if budgets := summaryFiles(t, out.Bytes(), "artifact_budgets"); len(budgets) != 1 || budgets[0] != "state.md" {
+		t.Fatalf("artifact_budgets=%v, want [state.md]", budgets)
+	}
+}
+
+func mustDecode(t *testing.T, out []byte) map[string]json.RawMessage {
+	t.Helper()
+	var doc map[string]json.RawMessage
+	if err := json.Unmarshal(out, &doc); err != nil {
+		t.Fatalf("summary is not a JSON object: %v (%s)", err, out)
+	}
+	return doc
+}
+
+// A workspace that has not reached define has no tasks.md; that is absence, not a read failure.
+func TestObserveSummaryOmitsUnreadableWhenTasksAbsent(t *testing.T) {
+	root, _ := writeBudgetWorkspace(t, map[string]string{
+		"state.md": "| phase | spec |\n| schema | 4 |\n",
+	})
+	var out, errOut bytes.Buffer
+	if code := RunObserveSummary(root, "feature", &out, &errOut); code != 0 {
+		t.Fatalf("exit=%d stderr=%s", code, errOut.String())
+	}
+	if _, ok := mustDecode(t, out.Bytes())["unreadable"]; ok {
+		t.Fatalf("a missing tasks.md must not be reported as unreadable: %s", out.String())
+	}
+}
+
+// A tasks.md that fails both the task-graph read and the budget read is named once.
+func TestObserveSummaryNamesUnreadableTasksOnce(t *testing.T) {
+	if os.Geteuid() == 0 || runtime.GOOS == "windows" {
+		t.Skip("file permissions do not bind root or windows")
+	}
+	root, workspace := writeBudgetWorkspace(t, map[string]string{
+		"state.md": "| phase | build |\n| schema | 4 |\n",
+		"tasks.md": budgetTasks,
+	})
+	tasks := filepath.Join(workspace, "tasks.md")
+	if err := os.Chmod(tasks, 0o000); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chmod(tasks, 0o644) })
+
+	var out, errOut bytes.Buffer
+	if code := RunObserveSummary(root, "feature", &out, &errOut); code != 0 {
+		t.Fatalf("exit=%d stderr=%s", code, errOut.String())
+	}
+	if names := summaryUnreadable(t, out.Bytes()); len(names) != 1 || names[0] != "tasks.md" {
+		t.Fatalf("unreadable=%v, want exactly [tasks.md]", names)
+	}
+}
+
+const (
+	artifactSchemaDocPath  = "../../../pack/.claude/skills/devrites-lib/reference/workspace-artifact-schema.md"
+	outlineTemplateDocPath = "../../../pack/.claude/skills/devrites-lib/reference/visual-playbooks/outline-template.md"
+)
+
+// Every artifact the schema's Budget column names must either be measured by the
+// engine or say in its Budget cell that the budget is advisory.
+func TestSchemaBudgetRowsAreEnforcedOrMarkedAdvisory(t *testing.T) {
+	raw, err := os.ReadFile(artifactSchemaDocPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	rows := 0
+	for _, line := range strings.Split(string(raw), "\n") {
+		cells := strings.Split(line, "|")
+		if len(cells) != 5 || !strings.Contains(cells[3], "lines") {
+			continue
+		}
+		first, budget := strings.TrimSpace(cells[1]), cells[3]
+		if !strings.HasPrefix(first, "`") || !strings.HasSuffix(first, "`") {
+			continue
+		}
+		rows++
+		name := strings.Trim(first, "`")
+		if _, canonical := state.ArtifactLineBudget(name); canonical {
+			continue
+		}
+		if !strings.Contains(strings.ToLower(budget), "advisory") {
+			t.Errorf("%s has a budget %q but is neither in state.artifactLineBudgets nor marked advisory", name, strings.TrimSpace(budget))
+		}
+	}
+	if rows < 30 {
+		t.Fatalf("parsed %d budget rows from the schema table, want at least 30", rows)
+	}
+}
+
+func TestOutlineTemplateBudgetIsMarkedAdvisory(t *testing.T) {
+	raw, err := os.ReadFile(outlineTemplateDocPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, line := range strings.Split(string(raw), "\n") {
+		if strings.HasPrefix(line, "- Budget:") {
+			if !strings.Contains(strings.ToLower(line), "advisory") {
+				t.Fatalf("outline budget line %q does not say the budget is advisory", line)
+			}
+			return
+		}
+	}
+	t.Fatal("outline template has no \"- Budget:\" line")
+}
+
+// A canonical artifact larger than the read cap is reported over budget from its
+// size alone, without being read whole.
+func TestObserveArtifactBudgetsOversizedArtifactIsOverWithoutFullRead(t *testing.T) {
+	const size = 32 << 20
+	_, workspace := writeBudgetWorkspace(t, map[string]string{"state.md": "| phase | build |\n"})
+	file, err := os.OpenFile(filepath.Join(workspace, "state.md"), os.O_WRONLY, 0o644)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := file.Truncate(size); err != nil {
+		t.Fatal(err)
+	}
+	if err := file.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	var before, after runtime.MemStats
+	runtime.ReadMemStats(&before)
+	budgets, _, unreadable, err := observeArtifactBudgets(workspace)
+	runtime.ReadMemStats(&after)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(unreadable) != 0 {
+		t.Fatalf("unreadable=%v, an oversized artifact is over budget, not unreadable", unreadable)
+	}
+	if len(budgets) != 1 || !budgets[0].Over || budgets[0].Bytes != size {
+		t.Fatalf("budgets=%+v, want state.md over budget with Bytes=%d", budgets, size)
+	}
+	if allocated := after.TotalAlloc - before.TotalAlloc; allocated > size/4 {
+		t.Fatalf("allocated %d bytes for a %d byte artifact; the read must be bounded", allocated, size)
+	}
+}

package/engine/internal/lib/observe_summary.go

@@ -2,8 +2,12 @@ package lib
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
+	"io/fs"
+	"path/filepath"
+	"slices"
 
 	"github.com/devrites/devrites/internal/devritespaths"
 	"github.com/devrites/devrites/internal/state"
@@ -41,6 +45,7 @@ type ObserveSummary struct {
 	NextAction        string                 `json:"next_action,omitempty"`
 	MissingSections   []string               `json:"missing_sections,omitempty"`
 	MissingFiles      []string               `json:"missing_files,omitempty"`
+	Unreadable        []string               `json:"unreadable,omitempty"`
 	PrinciplesPresent bool                   `json:"principles_present"`
 	TaskGraph         *ObserveTaskGraph      `json:"task_graph,omitempty"`
 	ArtifactBudgets   []ArtifactBudget       `json:"artifact_budgets,omitempty"`
@@ -64,7 +69,13 @@ func ObserveSummaryFor(root, slug string) (ObserveSummary, error) {
 		MissingSections:   missingSectionNames(report.Missing),
 	}
 
-	if graph, graphErr := CheckTaskGraph(root, slug); graphErr == nil && (len(graph.Slices) > 0 || len(graph.Problems) > 0) {
+	graph, graphErr := CheckTaskGraph(root, slug)
+	switch {
+	case errors.Is(graphErr, fs.ErrNotExist):
+		// tasks.md is created at define; before that its absence is expected.
+	case graphErr != nil:
+		summary.Unreadable = append(summary.Unreadable, "tasks.md")
+	case len(graph.Slices) > 0 || len(graph.Problems) > 0:
 		slices := make([]ObserveSlice, 0, len(graph.Slices))
 		for _, slice := range graph.Slices {
 			deps := make([]string, 0, len(slice.Dependencies))
@@ -89,9 +100,19 @@ func ObserveSummaryFor(root, slug string) (ObserveSummary, error) {
 		}
 	}
 	if workspace, wsErr := devritespaths.ExistingFeatureDirChecked(root, slug); wsErr == nil {
-		if budgets, bulk, budgetErr := observeArtifactBudgets(workspace); budgetErr == nil {
+		budgets, bulk, unreadable, budgetErr := observeArtifactBudgets(workspace)
+		if budgetErr == nil {
 			summary.ArtifactBudgets = budgets
 			summary.BulkFiles = bulk
+			for _, name := range unreadable {
+				if !slices.Contains(summary.Unreadable, name) {
+					summary.Unreadable = append(summary.Unreadable, name)
+				}
+			}
+		} else {
+			// The directory itself is unreadable, so no entry name is available; report
+			// the loss under the workspace rather than emitting a shorter summary.
+			summary.Unreadable = append(summary.Unreadable, filepath.Base(workspace))
 		}
 	}
 	return summary, nil

package/engine/internal/lib/open_visual.go

@@ -1,8 +1,10 @@
 package lib
 
 import (
+	"errors"
 	"fmt"
 	"io"
+	"io/fs"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -227,8 +229,8 @@ func resolveOpenVisualFeatureDir(root, slug string) (string, error) {
 	}
 	dir, err := devritespaths.ExistingFeatureDirChecked(root, slug)
 	if err != nil {
-		if os.IsNotExist(err) {
-			retErr := fmt.Errorf("no workspace for slug %q", slug)
+		if errors.Is(err, fs.ErrNotExist) {
+			retErr := fmt.Errorf("no workspace for slug %q at %s", slug, filepath.Join(root, "work", slug))
 			return "", retErr
 		}
 		return "", err

package/engine/internal/lib/open_visual_test.go

@@ -278,3 +278,14 @@ func swapOpenVisualOpener(fn func(string) error) func() {
 	openVisualOpener = fn
 	return func() { openVisualOpener = prev }
 }
+
+func TestOpenVisualMissingWorkspaceNamesResolvedPath(t *testing.T) {
+	root := t.TempDir()
+	var stdout, stderr bytes.Buffer
+
+	code := OpenVisual(root, []string{"demo", "--slug", "ghost"}, &stdout, &stderr)
+	want := filepath.Join(root, "work", "ghost")
+	if code != 2 || !strings.Contains(stderr.String(), `"ghost"`) || !strings.Contains(stderr.String(), want) {
+		t.Fatalf("open-visual missing workspace = %d, want exit 2 naming %q\n%s", code, want, stderr.String())
+	}
+}

package/engine/internal/lib/regression.go

@@ -26,6 +26,9 @@ import (
 //
 //	devrites-engine check regression <slug>            compare vs baseline
 //	devrites-engine check regression <slug> --update   ratchet baseline to now
+//	devrites-engine check regression <slug> --update --allow-empty
+//	                                                   ratchet even when every
+//	                                                   acceptance fact is gone
 //
 //	0  clean / no baseline yet
 //	2  usage error or workspace unreadable
@@ -75,18 +78,18 @@ type regressionBaseline struct {
 // RunCheckRegression compares the workspace against its recorded progress
 // baseline, or ratchets that baseline forward with --update.
 func RunCheckRegression(root string, args []string, stdout, stderr io.Writer) int {
-	if len(args) < 1 || len(args) > 2 {
+	if len(args) < 1 || len(args) > 3 {
 		fmt.Fprintln(stderr, regressionUsage)
 		return 2
 	}
 	slug := args[0]
-	update := false
-	if len(args) == 2 {
-		if args[1] != "--update" {
+	update, allowEmpty := false, false
+	if len(args) >= 2 {
+		if args[1] != "--update" || (len(args) == 3 && args[2] != "--allow-empty") {
 			fmt.Fprintln(stderr, regressionUsage)
 			return 2
 		}
-		update = true
+		update, allowEmpty = true, len(args) == 3
 	}
 	workspace, err := devritespaths.ExistingFeatureDirChecked(root, slug)
 	if err != nil {
@@ -120,24 +123,41 @@ func RunCheckRegression(root string, args []string, stdout, stderr io.Writer) in
 		fmt.Fprintf(stdout, "check regression: BLOCKED: %d regression(s) vs baseline %s\n", len(regressions), baseline.UpdatedAt)
 		return 3
 	}
-	return updateRegressionBaseline(root, slug, baselinePath, baseline, hasBaseline, current, stdout, stderr)
+	return updateRegressionBaseline(root, slug, baselinePath, baseline, hasBaseline, current, allowEmpty, stdout, stderr)
 }
 
-// fingerprintWorkspace computes the current structural progress facts.
+// fingerprintWorkspace computes the current structural progress facts. A
+// non-nil error names every artifact that existed but could not be read or
+// parsed; the returned fingerprint is then incomplete.
 func fingerprintWorkspace(root, slug, workspace string) (progressFingerprint, error) {
 	fp := progressFingerprint{PhaseOrdinal: -1}
 
-	if report, err := state.Status(root, slug); err == nil && report != nil {
-		fp.Phase = string(report.Phase)
-		for i, policy := range state.PhasePolicies() {
-			if policy.Target == report.Phase {
-				fp.PhaseOrdinal = i
-				break
-			}
+	// An unobservable phase would disable the phase-regression comparison, so
+	// it blocks instead of yielding PhaseOrdinal -1.
+	report, err := state.Status(root, slug)
+	if err != nil {
+		return fp, fmt.Errorf("phase unreadable, refusing to treat as progress facts: %w", err)
+	}
+	fp.Phase = string(report.Phase)
+	for i, policy := range state.PhasePolicies() {
+		if policy.Target == report.Phase {
+			fp.PhaseOrdinal = i
+			break
+		}
+	}
+
+	// A missing artifact is a legitimate early-phase state; an unreadable or
+	// unparsable one would silently yield an empty fact set, so it is named.
+	var degraded []string
+	note := func(name string, err error) {
+		if err != nil && !os.IsNotExist(err) {
+			degraded = append(degraded, fmt.Sprintf("%s: %v", name, err))
 		}
 	}
 
-	if masked, err := maskedArtifact(workspace, "spec.md"); err == nil {
+	masked, err := maskedArtifact(workspace, "spec.md")
+	note("spec.md", err)
+	if err == nil {
 		for _, m := range regressACRe.FindAllStringSubmatch(masked, -1) {
 			if strings.EqualFold(m[1], "x") {
 				fp.CheckedAC = append(fp.CheckedAC, m[2])
@@ -145,14 +165,19 @@ func fingerprintWorkspace(root, slug, workspace string) (progressFingerprint, er
 		}
 	}
 
-	if raw, err := os.ReadFile(filepath.Join(workspace, "tasks.md")); err == nil { // #nosec G304 -- workspace artifact
-		if masked, maskErr := markdowntext.Structural(raw); maskErr == nil {
-			fp.DoneSlices = doneSlices(string(masked))
-		}
+	masked, err = maskedArtifact(workspace, "tasks.md")
+	note("tasks.md", err)
+	if err == nil {
+		fp.DoneSlices = doneSlices(masked)
 	}
 
-	if raw, err := os.ReadFile(filepath.Join(workspace, acceptance.GatesFile)); err == nil { // #nosec G304 -- workspace artifact
+	raw, err := os.ReadFile(filepath.Join(workspace, acceptance.GatesFile)) // #nosec G304 -- workspace artifact
+	note(acceptance.GatesFile, err)
+	if err == nil {
 		doc := acceptance.ParseLedger(string(raw))
+		if len(doc.Errors) > 0 {
+			note(acceptance.GatesFile, fmt.Errorf("%s", strings.Join(doc.Errors, "; ")))
+		}
 		for _, g := range doc.Gates {
 			if g.Checked {
 				fp.MetGates = append(fp.MetGates, g.ID)
@@ -163,12 +188,17 @@ func fingerprintWorkspace(root, slug, workspace string) (progressFingerprint, er
 		}
 	}
 
-	if masked, err := maskedArtifact(workspace, "questions.md"); err == nil {
+	masked, err = maskedArtifact(workspace, "questions.md")
+	note("questions.md", err)
+	if err == nil {
 		fp.ResolvedQuestions = resolvedQuestions(masked)
 	}
 
 	fp.PresentArtifacts = presentArtifacts(workspace)
 	sortSets(&fp)
+	if len(degraded) > 0 {
+		return fp, fmt.Errorf("degraded artifact(s), refusing to treat as progress facts: %s", strings.Join(degraded, "; "))
+	}
 	return fp, nil
 }
 
@@ -297,10 +327,19 @@ func compareProgress(base, current progressFingerprint) []string {
 // updateRegressionBaseline replaces the baseline with the current fingerprint.
 // Regressions being blessed are printed, never hidden — a ratchet is the
 // recorded acknowledgment that the current state is the new floor.
-func updateRegressionBaseline(root, slug, baselinePath string, base regressionBaseline, hasBaseline bool, current progressFingerprint, stdout, stderr io.Writer) int {
+func updateRegressionBaseline(root, slug, baselinePath string, base regressionBaseline, hasBaseline bool, current progressFingerprint, allowEmpty bool, stdout, stderr io.Writer) int {
 	var blessed []string
 	if hasBaseline {
 		blessed = compareProgress(base.progressFingerprint, current)
+		// Wiping every recorded acceptance fact is indistinguishable from a
+		// destroyed workspace, so it needs an explicit flag.
+		if !allowEmpty && len(base.CheckedAC)+len(base.MetGates) > 0 && len(current.CheckedAC)+len(current.MetGates) == 0 {
+			for _, line := range blessed {
+				fmt.Fprintf(stdout, "REGRESSION: %s\n", line)
+			}
+			fmt.Fprintf(stdout, "check regression: BLOCKED: --update would leave no checked acceptance criterion or met gate; rerun with --allow-empty to accept\n")
+			return 3
+		}
 	}
 	// Keep the phase high-water mark: a baseline never forgets the furthest phase.
 	if hasBaseline && base.PhaseOrdinal > current.PhaseOrdinal {
@@ -375,4 +414,4 @@ func sortSets(fp *progressFingerprint) {
 	sort.Strings(fp.PresentArtifacts)
 }
 
-const regressionUsage = "usage: devrites-engine check regression <slug> [--update]"
+const regressionUsage = "usage: devrites-engine check regression <slug> [--update [--allow-empty]]"

package/engine/internal/lib/regression_test.go

@@ -177,3 +177,106 @@ func TestRegressionUsageErrors(t *testing.T) {
 		t.Fatalf("bad flag code=%d", code)
 	}
 }
+
+func TestRegressionDegradedArtifactRefusesRatchet(t *testing.T) {
+	root, dir := regressionWorkspace(t, "build")
+	if code, out := checkRegression(t, root, "feat", "--update"); code != 0 || !strings.Contains(out, "baseline updated") {
+		t.Fatalf("healthy update code=%d out=%s", code, out)
+	}
+	baselinePath := filepath.Join(dir, regressionBaselineFile)
+	before, err := os.ReadFile(baselinePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	healthy, err := fingerprintWorkspace(root, "feat", dir)
+	if err != nil || len(healthy.CheckedAC) != 1 || healthy.CheckedAC[0] != "AC-001" {
+		t.Fatalf("healthy fingerprint err=%v checked=%v", err, healthy.CheckedAC)
+	}
+
+	writeFile(t, filepath.Join(dir, "spec.md"), "# Spec\n\n## Acceptance criteria\n- [x] AC-001: a\x00\n")
+	if _, err := fingerprintWorkspace(root, "feat", dir); err == nil || !strings.Contains(err.Error(), "spec.md") {
+		t.Fatalf("degraded fingerprint must name spec.md, err=%v", err)
+	}
+	code, out := checkRegression(t, root, "feat", "--update")
+	if code != 2 || strings.Contains(out, "baseline updated") || !strings.Contains(out, "spec.md") {
+		t.Fatalf("degraded ratchet code=%d out=%s", code, out)
+	}
+	after, err := os.ReadFile(baselinePath)
+	if err != nil || !bytes.Equal(before, after) {
+		t.Fatalf("baseline rewritten from degraded fingerprint: err=%v", err)
+	}
+}
+
+func TestRegressionUpdateRefusesToWipeAcceptanceFacts(t *testing.T) {
+	root, dir := regressionWorkspace(t, "build")
+	if code, out := checkRegression(t, root, "feat", "--update"); code != 0 || !strings.Contains(out, "baseline updated") {
+		t.Fatalf("healthy update code=%d out=%s", code, out)
+	}
+	baselinePath := filepath.Join(dir, regressionBaselineFile)
+	before, err := os.ReadFile(baselinePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	writeFile(t, filepath.Join(dir, "spec.md"), strings.Replace(regressionSpec, "- [x] AC-001", "- [ ] AC-001", 1))
+	writeFile(t, filepath.Join(dir, "gates.md"), strings.Replace(regressionGates, "- [x] AC-001", "- [ ] AC-001", 1))
+
+	code, out := checkRegression(t, root, "feat", "--update")
+	if code != 3 || strings.Contains(out, "baseline updated") || !strings.Contains(out, "--allow-empty") {
+		t.Fatalf("wiping ratchet code=%d out=%s", code, out)
+	}
+	after, err := os.ReadFile(baselinePath)
+	if err != nil || !bytes.Equal(before, after) {
+		t.Fatalf("baseline rewritten by refused wipe: err=%v", err)
+	}
+
+	code, out = checkRegression(t, root, "feat", "--update", "--allow-empty")
+	if code != 0 || !strings.Contains(out, "REGRESSION-BLESSED") || !strings.Contains(out, "baseline updated") {
+		t.Fatalf("explicit wipe code=%d out=%s", code, out)
+	}
+}
+
+func TestRegressionMalformedGatesRefusesRatchet(t *testing.T) {
+	root, dir := regressionWorkspace(t, "build")
+	if code, out := checkRegression(t, root, "feat", "--update"); code != 0 || !strings.Contains(out, "baseline updated") {
+		t.Fatalf("healthy update code=%d out=%s", code, out)
+	}
+	baselinePath := filepath.Join(dir, regressionBaselineFile)
+	before, err := os.ReadFile(baselinePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	writeFile(t, filepath.Join(dir, "gates.md"), strings.Replace(regressionGates, "first thing works", "first thing works\x00", 1))
+	if _, err := fingerprintWorkspace(root, "feat", dir); err == nil || !strings.Contains(err.Error(), "gates.md") {
+		t.Fatalf("malformed gates fingerprint must name gates.md, err=%v", err)
+	}
+	code, out := checkRegression(t, root, "feat", "--update", "--allow-empty")
+	if code != 2 || strings.Contains(out, "baseline updated") || !strings.Contains(out, "gates.md") {
+		t.Fatalf("malformed gates ratchet code=%d out=%s", code, out)
+	}
+	after, err := os.ReadFile(baselinePath)
+	if err != nil || !bytes.Equal(before, after) {
+		t.Fatalf("baseline rewritten from malformed gates: err=%v", err)
+	}
+}
+
+func TestRegressionUnreadablePhaseIsNotPass(t *testing.T) {
+	root, dir := regressionWorkspace(t, "prove")
+	if code, out := checkRegression(t, root, "feat", "--update"); code != 0 || !strings.Contains(out, "baseline updated") {
+		t.Fatalf("healthy update code=%d out=%s", code, out)
+	}
+	if code, out := checkRegression(t, root, "feat"); code != 0 || !strings.Contains(out, "PASS") {
+		t.Fatalf("healthy control code=%d out=%s", code, out)
+	}
+
+	writeFile(t, filepath.Join(dir, "state.md"), "# State\n\n## Cursor\n| Key | Value |\n| --- | --- |\n| status | running |\n")
+	// Premise: the corrupted state.md must leave the phase unobservable.
+	if fp, err := fingerprintWorkspace(root, "feat", dir); err == nil && fp.PhaseOrdinal >= 0 {
+		t.Fatalf("premise failed: phase still observable, ordinal=%d", fp.PhaseOrdinal)
+	}
+	code, out := checkRegression(t, root, "feat")
+	if code == 0 || strings.Contains(out, "PASS") {
+		t.Fatalf("unreadable phase must not pass: code=%d out=%s", code, out)
+	}
+}