devrites 2.6.0 → 3.0.0

package/engine/tests/meta_test.go

@@ -0,0 +1,67 @@
+package main_test
+
+// Cross-cutting assertions the spec calls out explicitly: the engine makes zero
+// network calls, and the inline fail-open guard no-ops when the binary is absent.
+
+import (
+	"bytes"
+	"os/exec"
+	"strings"
+	"testing"
+)
+
+// TestFirstPartyMakesNoNetworkCalls asserts that no first-party package imports a
+// network client EXCEPT internal/iohooks — the ONE sanctioned network surface,
+// where the source-citation cache does conditional-HEAD revalidation. Confining
+// network to that single, auditable package keeps the rest of the engine a
+// network-free control plane that makes zero model calls (PRD: "zero API"). The
+// engine still makes zero MODEL/API calls anywhere; this is the executable form of
+// both guarantees, narrowed to permit exactly the sanctioned cache.
+func TestFirstPartyMakesNoNetworkCalls(t *testing.T) {
+	if _, err := exec.LookPath("go"); err != nil {
+		t.Skip("go toolchain unavailable")
+	}
+	out, err := exec.Command("go", "list", "-f",
+		"{{.ImportPath}} {{join .Imports \" \"}}",
+		"github.com/devrites/devrites/...").Output()
+	if err != nil {
+		t.Fatalf("go list: %v", err)
+	}
+	forbidden := map[string]bool{"net": true, "net/http": true, "net/rpc": true, "net/smtp": true}
+	const sanctioned = "github.com/devrites/devrites/internal/iohooks"
+	for _, line := range strings.Split(strings.TrimSpace(string(out)), "\n") {
+		fields := strings.Fields(line)
+		if len(fields) == 0 {
+			continue
+		}
+		pkg, imports := fields[0], fields[1:]
+		if pkg == sanctioned {
+			continue // the one package allowed to touch the network
+		}
+		for _, imp := range imports {
+			if forbidden[imp] {
+				t.Errorf("first-party package %s imports network package %q — only %s may make network calls", pkg, imp, sanctioned)
+			}
+		}
+	}
+}
+
+// TestFailOpenGuardNoOpsWhenBinaryMissing exercises the inline POSIX guard the
+// hooks.json entries wrap every devrites-engine hook in. With no devrites-engine on PATH the
+// guard must be a silent no-op (exit 0), so a teammate without the binary
+// installed is never wedged.
+func TestFailOpenGuardNoOpsWhenBinaryMissing(t *testing.T) {
+	if _, err := exec.LookPath("sh"); err != nil {
+		t.Skip("sh unavailable")
+	}
+	const guard = `command -v devrites-engine >/dev/null 2>&1 && devrites-engine hook orient --harness=claude || exit 0`
+	cmd := exec.Command("sh", "-c", guard)
+	cmd.Env = []string{"PATH="} // empty PATH -> devrites-engine is not found
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("guard did not exit 0 with the binary absent: %v\n%s", err, out)
+	}
+	if len(bytes.TrimSpace(out)) != 0 {
+		t.Errorf("guard produced output with the binary absent: %q", out)
+	}
+}

package/engine/tests/migrate_cli_test.go

@@ -0,0 +1,193 @@
+package main_test
+
+// Issue 06: `migrate` workspace normalization at the CLI seam.
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// workWorkspace writes a canonical .devrites/work/<slug> workspace with one
+// feature and an ACTIVE pointer, and returns the .devrites root.
+func workWorkspace(t *testing.T) (root, slug string) {
+	t.Helper()
+	root = filepath.Join(t.TempDir(), ".devrites")
+	slug = "legacy-feat"
+	work := filepath.Join(root, "work", slug)
+	if err := os.MkdirAll(work, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	files := map[string]string{
+		"state.md":     "# State\n\nphase: build\n\nWorking on it.\n",
+		"spec.md":      "# Spec\n\nRotate tokens.\n",
+		"plan.md":      "# Plan\n\nStep 1, step 2.\n",
+		"tasks.md":     "# Tasks\n\n- [x] one\n",
+		"evidence.md":  "# Evidence\n\nTests green.\n",
+		"decisions.md": "# Decisions\n\nUse HMAC.\n",
+	}
+	for name, body := range files {
+		if err := os.WriteFile(filepath.Join(work, name), []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := os.WriteFile(filepath.Join(root, "ACTIVE"), []byte(slug+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return root, slug
+}
+
+func backupDirs(t *testing.T, root string) []string {
+	t.Helper()
+	m, err := filepath.Glob(filepath.Join(root, ".migrate-backup-*"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return m
+}
+
+func TestMigrateNormalizesCanonicalWorkSchema(t *testing.T) {
+	root, slug := workWorkspace(t)
+	out, errOut, code := runDevrites(t, root, "migrate")
+	if code != 0 {
+		t.Fatalf("exit = %d, want 0 (stderr: %s)", code, errOut)
+	}
+	if !strings.Contains(out, "migrated 1 feature(s)") {
+		t.Errorf("unexpected migrate output\n%s", out)
+	}
+
+	feat := filepath.Join(root, "work", slug)
+	// evidence.md → proof.md, state.md → status.md, plus a generated feature.md.
+	for _, want := range []string{"feature.md", "spec.md", "plan.md", "decisions.md", "tasks.md", "proof.md", "status.md"} {
+		if _, err := os.Stat(filepath.Join(feat, want)); err != nil {
+			t.Errorf("missing new-schema file %s: %v", want, err)
+		}
+	}
+	fm, err := os.ReadFile(filepath.Join(feat, "feature.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(fm), "phase: build") {
+		t.Errorf("feature.md phase not derived from state.md\n%s", fm)
+	}
+	if !strings.Contains(string(fm), "schemaVersion: 1") {
+		t.Errorf("feature.md missing schemaVersion\n%s", fm)
+	}
+	proof, _ := os.ReadFile(filepath.Join(feat, "proof.md"))
+	if !strings.Contains(string(proof), "Tests green") {
+		t.Errorf("proof.md did not carry evidence.md content\n%s", proof)
+	}
+
+	// A backup of the pre-migration state must exist.
+	if got := backupDirs(t, root); len(got) != 1 {
+		t.Errorf("want exactly one backup dir, got %v", got)
+	}
+}
+
+func TestMigratePostStatusWorks(t *testing.T) {
+	root, slug := workWorkspace(t)
+	if _, _, code := runDevrites(t, root, "migrate"); code != 0 {
+		t.Fatal("migrate failed")
+	}
+	out, errOut, code := runDevrites(t, root, "status", slug)
+	if code != 0 {
+		t.Fatalf("status after migrate exit = %d (stderr: %s)", code, errOut)
+	}
+	if !strings.Contains(out, "phase: build") {
+		t.Errorf("migrated feature status is wrong\n%s", out)
+	}
+}
+
+func TestMigrateIsIdempotent(t *testing.T) {
+	root, _ := workWorkspace(t)
+	if _, _, code := runDevrites(t, root, "migrate"); code != 0 {
+		t.Fatal("first migrate failed")
+	}
+	before := backupDirs(t, root)
+
+	out, _, code := runDevrites(t, root, "migrate")
+	if code != 0 {
+		t.Fatalf("second migrate exit = %d, want 0", code)
+	}
+	if !strings.Contains(out, "already up to date") {
+		t.Errorf("second migrate was not a no-op\n%s", out)
+	}
+	// A no-op re-run must not create another backup.
+	if after := backupDirs(t, root); len(after) != len(before) {
+		t.Errorf("re-run created a new backup: before=%v after=%v", before, after)
+	}
+}
+
+func TestMigrateNormalizesLiveFeatureInPlace(t *testing.T) {
+	root := filepath.Join(t.TempDir(), ".devrites")
+	slug := "live-feat"
+	feat := filepath.Join(root, "features", slug)
+	if err := os.MkdirAll(feat, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	files := map[string]string{
+		"state.md":     "# State\n\n- Phase: prove\n- Status: running\n",
+		"spec.md":      "# Spec\n\nRotate tokens.\n",
+		"plan.md":      "# Plan\n\nStep 1, step 2.\n",
+		"tasks.md":     "# Tasks\n\n- [x] one\n",
+		"evidence.md":  "# Evidence\n\nTests green.\n",
+		"decisions.md": "# Decisions\n\nUse HMAC.\n",
+	}
+	for name, body := range files {
+		if err := os.WriteFile(filepath.Join(feat, name), []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	out, errOut, code := runDevrites(t, root, "migrate")
+	if code != 0 {
+		t.Fatalf("exit = %d, want 0 (stderr: %s)", code, errOut)
+	}
+	if !strings.Contains(out, "migrated 1 feature(s)") {
+		t.Errorf("unexpected migrate output\n%s", out)
+	}
+	for _, want := range []string{"feature.md", "proof.md", "status.md", "state.md", "evidence.md"} {
+		if _, err := os.Stat(filepath.Join(feat, want)); err != nil {
+			t.Errorf("missing normalized file %s: %v", want, err)
+		}
+	}
+	fm, err := os.ReadFile(filepath.Join(feat, "feature.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(fm), "phase: prove") {
+		t.Errorf("feature.md phase not derived from ledger\n%s", fm)
+	}
+	status, _ := os.ReadFile(filepath.Join(feat, "status.md"))
+	if !strings.Contains(string(status), "running") {
+		t.Errorf("status.md did not carry state.md content\n%s", status)
+	}
+	proof, _ := os.ReadFile(filepath.Join(feat, "proof.md"))
+	if !strings.Contains(string(proof), "Tests green") {
+		t.Errorf("proof.md did not carry evidence.md content\n%s", proof)
+	}
+	if got := backupDirs(t, root); len(got) != 1 {
+		t.Errorf("want exactly one backup dir, got %v", got)
+	}
+
+	out, errOut, code = runDevrites(t, root, "status", slug)
+	if code != 0 {
+		t.Fatalf("status after normalize exit = %d (stderr: %s)", code, errOut)
+	}
+	if !strings.Contains(out, "phase: prove") || !strings.Contains(out, "proof      present") || !strings.Contains(out, "status     present") {
+		t.Errorf("normalized feature status is wrong\n%s", out)
+	}
+
+	before := backupDirs(t, root)
+	out, _, code = runDevrites(t, root, "migrate")
+	if code != 0 {
+		t.Fatalf("second migrate exit = %d, want 0", code)
+	}
+	if !strings.Contains(out, "already up to date") {
+		t.Errorf("second migrate was not a no-op\n%s", out)
+	}
+	if after := backupDirs(t, root); len(after) != len(before) {
+		t.Errorf("re-run created a new backup: before=%v after=%v", before, after)
+	}
+}

package/engine/tests/parity_analyze_test.go

@@ -0,0 +1,55 @@
+package main_test
+
+import "testing"
+
+// TestParityAnalyze checks `analyze`'s coverage/consistency report against the
+// golden snapshots for each spec↔tasks fixture.
+func TestParityAnalyze(t *testing.T) {
+	work := t.TempDir()
+
+	// covered: every spec AC has a slice that Satisfies it → clear (exit 0).
+	writeFeatureFile(t, work, "covered", "spec.md", "# spec\n- [AC1] must foo\n")
+	writeFeatureFile(t, work, "covered", "tasks.md", "## Slice 1: foo\nSatisfies: AC1\n")
+
+	// uncovered: a spec AC no slice satisfies → CRITICAL (exit 1).
+	writeFeatureFile(t, work, "uncovered", "spec.md", "# spec\n- [AC1] must foo\n- [AC2] must bar\n")
+	writeFeatureFile(t, work, "uncovered", "tasks.md", "## Slice 1: foo\nSatisfies: AC1\n")
+
+	// dangling: a slice Satisfies an AC the spec never defines → CRITICAL (exit 1).
+	writeFeatureFile(t, work, "dangling", "spec.md", "# spec\n- [AC1] must foo\n")
+	writeFeatureFile(t, work, "dangling", "tasks.md", "## Slice 1: foo\nSatisfies: AC1, AC9\n")
+
+	// noac: spec has no [ACn] ids → warn, nothing dangling/orphan → clear (exit 0).
+	writeFeatureFile(t, work, "noac", "spec.md", "# spec\njust prose, no acceptance ids\n")
+	writeFeatureFile(t, work, "noac", "tasks.md", "# tasks\njust prose, no slices\n")
+
+	// orphan: a slice with no Satisfies line → warn, still clear (exit 0).
+	writeFeatureFile(t, work, "orphan", "spec.md", "# spec\n- [AC1] must foo\n")
+	writeFeatureFile(t, work, "orphan", "tasks.md",
+		"## Slice 1: foo\nSatisfies: AC1\n## Slice 2: bar\n- does stuff\n")
+
+	// order: byte-order sort must place AC10 before AC2 (LC_ALL=C), all covered.
+	writeFeatureFile(t, work, "order", "spec.md", "# spec\n- [AC1] a\n- [AC2] b\n- [AC10] c\n")
+	writeFeatureFile(t, work, "order", "tasks.md", "## Slice 1: all\nSatisfies: AC1, AC2, AC10\n")
+
+	// ghost: slug with no workspace → need spec.md+tasks.md (exit 2, empty stdout).
+
+	for _, slug := range []string{"covered", "uncovered", "dangling", "noac", "orphan", "order", "ghost"} {
+		c := parityCase{
+			workdir: work,
+			env:     libRootEnv(work),
+			goArgs:  []string{"analyze", slug},
+		}
+		t.Run("slug="+slug, func(t *testing.T) { c.assertEqual(t) })
+	}
+
+	// no active workspace: no slug arg and no .devrites/ACTIVE → exit 2, empty stdout.
+	noactive := t.TempDir()
+	t.Run("noactive", func(t *testing.T) {
+		(parityCase{
+			workdir: noactive,
+			env:     libRootEnv(noactive),
+			goArgs:  []string{"analyze"},
+		}).assertEqual(t)
+	})
+}

package/engine/tests/parity_buildreadiness_test.go

@@ -0,0 +1,42 @@
+package main_test
+
+// TestParityBuildReadiness checks the build-readiness gate's stdout + exit code
+// against the golden snapshot for each state.md fixture.
+
+import "testing"
+
+func TestParityBuildReadiness(t *testing.T) {
+	work := t.TempDir()
+
+	// Status halts (stderr-only messages; parity is stdout + exit code).
+	writeFeatureFile(t, work, "await", "state.md", "- Status: awaiting_human\n") // exit 3
+	writeFeatureFile(t, work, "blocked", "state.md", "- Status: blocked\n")      // exit 4
+
+	// Ready: plan approved + status.
+	writeFeatureFile(t, work, "approved", "state.md", "- Plan approved: 2024-01-01\n- Status: running\n") // exit 0
+
+	// Plan not approved: missing line, or the literal "none".
+	writeFeatureFile(t, work, "noapprove", "state.md", "- Status: running\n")                          // exit 2
+	writeFeatureFile(t, work, "approvenone", "state.md", "- Plan approved: none\n- Status: running\n") // exit 2
+
+	// field() strip: a trailing " | none" / " # note" annotation is trimmed off
+	// Status before the case match, so both stay "running" and reach OK.
+	writeFeatureFile(t, work, "trailpipe", "state.md", "- Plan approved: 2024-01-01\n- Status: running | none\n") // exit 0
+	writeFeatureFile(t, work, "trailhash", "state.md", "- Plan approved: 2024-01-01\n- Status: running # note\n") // exit 0
+
+	// Empty Status value + plan approved → status renders as "running".
+	writeFeatureFile(t, work, "emptystatus", "state.md", "- Plan approved: 2024-01-01\n- Status: \n") // exit 0
+
+	// "ghost" is intentionally never created → no workspace/state.md (exit 5).
+	for _, arg := range []string{
+		"await", "blocked", "approved", "noapprove", "approvenone",
+		"trailpipe", "trailhash", "emptystatus", "ghost",
+	} {
+		c := parityCase{
+			workdir: work,
+			env:     libRootEnv(work),
+			goArgs:  []string{"build-readiness", arg},
+		}
+		t.Run("arg="+arg, func(t *testing.T) { c.assertEqual(t) })
+	}
+}

package/engine/tests/parity_closeout_test.go

@@ -0,0 +1,102 @@
+package main_test
+
+// Golden snapshot for the ported close-out command (lib.CloseOut).
+//
+// close-out MUTATES the tree — it moves .devrites/features/<slug> to
+// .devrites/archive/<slug> and, when it is the active slug, clears
+// .devrites/ACTIVE. Each case snapshots the command's stdout + exit code (stderr
+// is diagnostic, not contract) and then asserts the post-move filesystem shape
+// with plain Go checks.
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestParityCloseOut(t *testing.T) {
+	dirExists := func(path string) bool {
+		fi, err := os.Stat(path)
+		return err == nil && fi.IsDir()
+	}
+	gone := func(path string) bool {
+		_, err := os.Stat(path)
+		return os.IsNotExist(err)
+	}
+
+	// run executes close-out in gw and snapshots its stdout + exit code under the
+	// current subtest's golden.
+	run := func(t *testing.T, gw string, args ...string) {
+		t.Helper()
+		out, code := runArgv(t, gw, libEnv, "", binPath, append([]string{"close-out"}, args...)...)
+		assertGolden(t, out, code)
+	}
+
+	t.Run("active_slug_cleared", func(t *testing.T) {
+		slug := "feat-x"
+		gw := t.TempDir()
+		writeFile(t, gw, filepath.Join(".devrites/features", slug, "spec.md"), "# spec\n")
+		writeFile(t, gw, ".devrites/ACTIVE", slug+"\n")
+
+		run(t, gw, slug, ".devrites")
+
+		// archive created, features/ source gone, ACTIVE truncated.
+		if !dirExists(filepath.Join(gw, ".devrites/archive", slug)) {
+			t.Error("archive dir not created")
+		}
+		if !gone(filepath.Join(gw, ".devrites/features", slug)) {
+			t.Error("source workspace not moved")
+		}
+		if b, err := os.ReadFile(filepath.Join(gw, ".devrites/ACTIVE")); err != nil {
+			t.Fatalf("reading ACTIVE: %v", err)
+		} else if len(b) != 0 {
+			t.Errorf("ACTIVE not cleared: %q", string(b))
+		}
+	})
+
+	t.Run("active_pointed_elsewhere", func(t *testing.T) {
+		slug := "feat-y"
+		other := "someone-else\n"
+		gw := t.TempDir()
+		writeFile(t, gw, filepath.Join(".devrites/features", slug, "spec.md"), "# spec\n")
+		writeFile(t, gw, ".devrites/ACTIVE", other)
+
+		run(t, gw, slug, ".devrites")
+
+		// The archive moved, but ACTIVE (pointed elsewhere) is left untouched.
+		if !dirExists(filepath.Join(gw, ".devrites/archive", slug)) {
+			t.Error("archive dir not created")
+		}
+		if b, err := os.ReadFile(filepath.Join(gw, ".devrites/ACTIVE")); err != nil {
+			t.Fatalf("reading ACTIVE: %v", err)
+		} else if string(b) != other {
+			t.Errorf("ACTIVE changed: %q", string(b))
+		}
+	})
+
+	t.Run("missing_workspace", func(t *testing.T) {
+		// No workspace seeded -> non-zero exit, empty stdout.
+		gw := t.TempDir()
+		run(t, gw, "ghost", ".devrites")
+	})
+
+	t.Run("archive_clobber", func(t *testing.T) {
+		slug := "feat-z"
+		gw := t.TempDir()
+		writeFile(t, gw, filepath.Join(".devrites/features", slug, "spec.md"), "# spec\n")
+		writeFile(t, gw, filepath.Join(".devrites/archive", slug, "old.md"), "old\n")
+
+		run(t, gw, slug, ".devrites")
+
+		// Refused: source stays in place, the pre-existing archive is not clobbered.
+		if !dirExists(filepath.Join(gw, ".devrites/features", slug)) {
+			t.Error("source workspace was moved despite clobber refusal")
+		}
+	})
+
+	t.Run("missing_slug", func(t *testing.T) {
+		// No slug arg -> non-zero exit.
+		gw := t.TempDir()
+		run(t, gw)
+	})
+}

package/engine/tests/parity_githelpers_test.go

@@ -0,0 +1,41 @@
+package main_test
+
+import (
+	"os/exec"
+	"testing"
+)
+
+// requireGit skips a parity case when git is unavailable (the git-backed gates
+// fail open / skip without it, so a parity assertion would be meaningless).
+func requireGit(t *testing.T) {
+	t.Helper()
+	if _, err := exec.LookPath("git"); err != nil {
+		t.Skip("git not available; skipping git-backed parity case")
+	}
+}
+
+// runGit runs a git subcommand in dir and fails the test on error.
+func runGit(t *testing.T, dir string, args ...string) {
+	t.Helper()
+	cmd := exec.Command("git", append([]string{"-C", dir}, args...)...)
+	if out, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("git %v: %v\n%s", args, err, out)
+	}
+}
+
+// initGitRepo initialises a fresh, self-contained git repo in dir (local identity
+// + no signing, so `commit` never depends on the host's global config).
+func initGitRepo(t *testing.T, dir string) {
+	t.Helper()
+	runGit(t, dir, "init", "-q")
+	runGit(t, dir, "config", "user.email", "test@example.com")
+	runGit(t, dir, "config", "user.name", "Test")
+	runGit(t, dir, "config", "commit.gpgsign", "false")
+}
+
+// gitCommitAll stages every change and commits it.
+func gitCommitAll(t *testing.T, dir, msg string) {
+	t.Helper()
+	runGit(t, dir, "add", "-A")
+	runGit(t, dir, "commit", "-q", "-m", msg)
+}

package/engine/tests/parity_learnings_test.go

@@ -0,0 +1,90 @@
+package main_test
+
+// TestParityLearnings checks the learnings command against the golden snapshots.
+// learnings state is ROOT-LEVEL, read from DEVRITES_ROOT=work/.devrites when the
+// case runs in workdir=work with libRootEnv(work). The mine/nudge pipelines are
+// deterministic from fixtures. Fixture counts are DISTINCT (3 vs 2) so ordering
+// never depends on a platform-specific tie-break.
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+func TestParityLearnings(t *testing.T) {
+	learn := func(a ...string) []string { return append([]string{"learnings"}, a...) }
+
+	// --- add: fresh workspace. bash creates the ledger + a dated entry; Go then
+	// appends a second entry. Only stdout ("learnings: recorded.") + exit 0 are the
+	// contract — the dated file line is a nondeterministic side effect, not stdout.
+	addw := t.TempDir()
+	t.Run("add", func(t *testing.T) {
+		(parityCase{
+			workdir: addw, env: libRootEnv(addw),
+			goArgs: learn("add", "my-slug", "a recurring correction", "note"),
+		}).assertEqual(t)
+	})
+
+	// --- list: a pre-written ledger; both sides cat the same file verbatim.
+	listw := t.TempDir()
+	writeFile(t, listw, filepath.Join(".devrites", "learnings.md"),
+		"# DevRites learnings ledger\n\n"+
+			"- [2026-01-01] (note · feat-x) prefer explicit error handling\n"+
+			"- [2026-01-02] (bug · feat-y) the linter false-positive recurs\n")
+	t.Run("list", func(t *testing.T) {
+		(parityCase{
+			workdir: listw, env: libRootEnv(listw),
+			goArgs: learn("list"),
+		}).assertEqual(t)
+	})
+
+	// --- mine + nudge: two archived features. The shared "recurring finding" bullet
+	// normalizes identically across features despite differing numbers/paths (the sed
+	// id/path/number stripping), giving count 3; the "second dead end" bullet gives
+	// count 2. Distinct counts ⇒ deterministic order on any `sort`.
+	arch := t.TempDir()
+	writeFile(t, arch, filepath.Join(".devrites", "archive", "feat-a", "decisions.md"),
+		"# decisions for feat-a\n"+
+			"- recurring finding: stale cache after deploy 3 times on `foo.js`\n"+
+			"- recurring finding: stale cache after deploy 8 times on `baz.ts`\n"+
+			"- second dead end: retry backoff exceeded 5 attempts\n"+
+			"some prose line that does not match the grep at all\n")
+	writeFile(t, arch, filepath.Join(".devrites", "archive", "feat-b", "decisions.md"),
+		"# decisions for feat-b\n"+
+			"- recurring finding: stale cache after deploy 7 times on `bar.js`\n"+
+			"- second dead end: retry backoff exceeded 9 attempts\n"+
+			"- a one-off dismiss note about the flaky linter run\n")
+
+	// mine: default archive (bash .devrites/archive, Go <root>/archive — same dir).
+	t.Run("mine", func(t *testing.T) {
+		(parityCase{
+			workdir: arch, env: libRootEnv(arch),
+			goArgs: learn("mine"),
+		}).assertEqual(t)
+	})
+
+	// mine: no archive. An explicit relative path both sides resolve against workdir,
+	// so the path embedded in the message is identical for bash and Go.
+	t.Run("mine-no-archive", func(t *testing.T) {
+		(parityCase{
+			workdir: arch, env: libRootEnv(arch),
+			goArgs: learn("mine", "no-such-archive"),
+		}).assertEqual(t)
+	})
+
+	// nudge: >=2 features + a class recurring 3x + no review marker ⇒ the nudge line.
+	t.Run("nudge", func(t *testing.T) {
+		(parityCase{
+			workdir: arch, env: libRootEnv(arch),
+			goArgs: learn("nudge"),
+		}).assertEqual(t)
+	})
+
+	// --- unknown cmd: usage to stderr, exit 2 (stdout empty on both sides).
+	t.Run("unknown", func(t *testing.T) {
+		(parityCase{
+			workdir: arch, env: libRootEnv(arch),
+			goArgs: learn("bogus"),
+		}).assertEqual(t)
+	})
+}

package/engine/tests/parity_mutationgate_test.go

@@ -0,0 +1,36 @@
+package main_test
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+// TestParityMutationGate runs mutation-gate in a NON-git temp dir with no
+// manifests so it resolves gitroot="" and detects no runner — the deterministic
+// advisory-skip path — and checks stdout + exit against the golden snapshot. (If
+// the host happens to have a runner on PATH, it is detected via the same lookup,
+// so the golden check still holds.)
+func TestParityMutationGate(t *testing.T) {
+	work := t.TempDir()
+
+	// The workspace directory must exist for the gate to proceed past its exit-2.
+	makeFeatureDir(t, work, "feat")
+	writeFile(t, work, filepath.Join(".devrites", "ACTIVE"), "feat\n")
+
+	cases := []struct {
+		name string
+		slug []string // extra args after the subcommand
+	}{
+		{"explicit-slug", []string{"feat"}},
+		{"active-slug", nil},         // resolves slug from ACTIVE
+		{"ghost", []string{"ghost"}}, // no workspace -> exit 2
+	}
+	for _, tc := range cases {
+		c := parityCase{
+			workdir: work,
+			env:     libRootEnv(work),
+			goArgs:  append([]string{"mutation-gate"}, tc.slug...),
+		}
+		t.Run(tc.name, func(t *testing.T) { c.assertEqual(t) })
+	}
+}