devrites 3.0.7 → 3.2.0

package/engine/tests/json_contract_test.go

@@ -10,9 +10,11 @@ import (
 )
 
 type jsonEnvelope struct {
+	Schema   string `json:"schema"`
 	Command  string `json:"command"`
 	OK       bool   `json:"ok"`
 	ExitCode int    `json:"exitCode"`
+	ReasonID string `json:"reason_id"`
 }
 
 func TestJSONContractCommandsEmitExactlyOneEnvelope(t *testing.T) {
@@ -41,6 +43,9 @@ func TestJSONContractCommandsEmitExactlyOneEnvelope(t *testing.T) {
 			if env.Command == "" {
 				t.Fatalf("missing command in envelope: %s", out)
 			}
+			if env.Schema != "devrites-command/v1" {
+				t.Fatalf("schema=%q\n%s", env.Schema, out)
+			}
 			if env.ExitCode != code {
 				t.Fatalf("envelope exitCode=%d process exit=%d\n%s", env.ExitCode, code, out)
 			}
@@ -51,6 +56,73 @@ func TestJSONContractCommandsEmitExactlyOneEnvelope(t *testing.T) {
 	}
 }
 
+func TestLifecycleGateJSONCarriesRuleOwnedReasonID(t *testing.T) {
+	root := newWorkspace(t)
+	for _, tc := range []struct {
+		command string
+		want    string
+	}{
+		{"readiness", "DRV-GATE-READINESS-MISSING"},
+		{"seal", "DRV-GATE-SEAL-MISSING"},
+	} {
+		t.Run(tc.command, func(t *testing.T) {
+			out, _, code := runDevrites(t, root, tc.command, "auth-tokens", "--json")
+			if code != 3 {
+				t.Fatalf("%s exit=%d\n%s", tc.command, code, out)
+			}
+			var env jsonEnvelope
+			decodeExactlyOneJSON(t, out, &env)
+			if env.ReasonID != tc.want {
+				t.Fatalf("%s reason_id=%q, want %q\n%s", tc.command, env.ReasonID, tc.want, out)
+			}
+		})
+	}
+}
+
+func TestLifecycleGateAppendsRootRelativeV1Provenance(t *testing.T) {
+	root := newWorkspace(t)
+	_, _, _ = runDevrites(t, root, "readiness", "auth-tokens", "--json")
+	raw, err := os.ReadFile(filepath.Join(root, "timeline.jsonl"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(raw), filepath.Dir(root)) {
+		t.Fatalf("timeline retained an absolute project path:\n%s", raw)
+	}
+	var boundaries []string
+	for _, line := range strings.Split(strings.TrimSpace(string(raw)), "\n") {
+		var event struct {
+			Schema     string   `json:"schema"`
+			Boundary   string   `json:"boundary"`
+			RootSource string   `json:"root_source"`
+			Workspace  string   `json:"workspace"`
+			ReasonID   string   `json:"reason_id"`
+			Evidence   []string `json:"evidence_paths"`
+		}
+		if json.Unmarshal([]byte(line), &event) != nil || event.Schema != "devrites-event/v1" {
+			continue
+		}
+		boundaries = append(boundaries, event.Boundary)
+		if event.RootSource != "DEVRITES_ROOT" {
+			t.Fatalf("non-canonical root/workspace provenance: %+v", event)
+		}
+		if event.Boundary == "lifecycle-gate" && event.Workspace != ".devrites/features/auth-tokens" {
+			t.Fatalf("gate workspace provenance: %+v", event)
+		}
+		if event.Boundary == "root-selection" && event.Workspace != "" {
+			t.Fatalf("root selection invented an inactive workspace: %+v", event)
+		}
+		for _, path := range event.Evidence {
+			if filepath.IsAbs(path) || strings.HasPrefix(path, "..") {
+				t.Fatalf("non-relative evidence %q", path)
+			}
+		}
+	}
+	if strings.Join(boundaries, ",") != "root-selection,lifecycle-gate" {
+		t.Fatalf("boundaries=%v\n%s", boundaries, raw)
+	}
+}
+
 func TestContextShowJSONReportsActiveWorkspace(t *testing.T) {
 	root := newWorkspace(t)
 	if err := os.WriteFile(filepath.Join(root, "ACTIVE"), []byte("auth-tokens\n"), 0o644); err != nil {
@@ -63,18 +135,32 @@ func TestContextShowJSONReportsActiveWorkspace(t *testing.T) {
 	var got struct {
 		Root            string `json:"root"`
 		Project         string `json:"project"`
+		LexicalRoot     string `json:"lexicalRoot"`
+		RootSelection   string `json:"rootSelection"`
 		ActiveWorkspace string `json:"activeWorkspace"`
 		Source          string `json:"source"`
-		HostCommands    struct {
+		Git             struct {
+			TopLevel       string `json:"topLevel"`
+			LinkedWorktree bool   `json:"linkedWorktree"`
+			Submodule      bool   `json:"submodule"`
+		} `json:"git"`
+		HostCommands struct {
 			Claude string `json:"claude"`
 			Codex  string `json:"codex"`
 		} `json:"hostCommands"`
 		Status []any `json:"status"`
 	}
 	decodeExactlyOneJSON(t, out, &got)
-	if got.Root != root || got.Project != filepath.Dir(root) {
+	wantRoot, err := filepath.EvalSymlinks(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.Root != wantRoot || got.Project != filepath.Dir(wantRoot) {
 		t.Fatalf("wrong roots: %+v", got)
 	}
+	if got.LexicalRoot != root || got.RootSelection != "DEVRITES_ROOT" {
+		t.Fatalf("wrong root provenance: %+v", got)
+	}
 	if got.ActiveWorkspace != filepath.Join(".devrites", "features", "auth-tokens") || got.Source != "ACTIVE" {
 		t.Fatalf("wrong active workspace: %+v", got)
 	}
@@ -86,6 +172,45 @@ func TestContextShowJSONReportsActiveWorkspace(t *testing.T) {
 	}
 }
 
+func TestContextShowJSONCarriesCanonicalRootHazards(t *testing.T) {
+	root := newWorkspace(t)
+	if err := os.WriteFile(filepath.Join(root, "ACTIVE"), []byte("ghost\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	out, errOut, code := runDevrites(t, root, "context", "show", "--json")
+	if code != 0 {
+		t.Fatalf("context show exit=%d stderr=%s", code, errOut)
+	}
+	var got struct {
+		RootSelection string `json:"rootSelection"`
+		Status        []struct {
+			ID          string `json:"id"`
+			Remediation string `json:"remediation"`
+		} `json:"status"`
+	}
+	decodeExactlyOneJSON(t, out, &got)
+	if got.RootSelection != "DEVRITES_ROOT" || len(got.Status) != 1 ||
+		got.Status[0].ID != "DRV-ACTIVE-STALE" || !strings.Contains(got.Status[0].Remediation, "rm -f") {
+		t.Fatalf("context root status = %+v\n%s", got, out)
+	}
+}
+
+func TestContextShowSeparatesRootAndWorkspaceSelection(t *testing.T) {
+	root := newWorkspace(t)
+	out, errOut, code := runDevrites(t, root, "context", "show", "--json")
+	if code != 0 {
+		t.Fatalf("context show exit=%d stderr=%s", code, errOut)
+	}
+	var got struct {
+		RootSelection string `json:"rootSelection"`
+		Source        string `json:"source"`
+	}
+	decodeExactlyOneJSON(t, out, &got)
+	if got.RootSelection != "DEVRITES_ROOT" || got.Source != "none" {
+		t.Fatalf("root/workspace selections are conflated: %+v", got)
+	}
+}
+
 func decodeExactlyOneJSON(t *testing.T, text string, v any) {
 	t.Helper()
 	dec := json.NewDecoder(strings.NewReader(text))

package/engine/tests/migrate_cli_test.go

@@ -1,6 +1,6 @@
 package main_test
 
-// Issue 06: `migrate` workspace normalization at the CLI seam.
+// CLI coverage for Issue 06: `migrate` workspace normalization.
 
 import (
 	"os"
@@ -71,7 +71,7 @@ func TestMigrateNormalizesCanonicalWorkSchema(t *testing.T) {
 	if !strings.Contains(string(readme), "phase: temper") {
 		t.Errorf("README.md phase not derived from state.md\n%s", readme)
 	}
-	if !strings.Contains(string(readme), "schemaVersion: 1") {
+	if !strings.Contains(string(readme), "schemaVersion: 2") {
 		t.Errorf("README.md missing schemaVersion\n%s", readme)
 	}
 	for _, unwanted := range []string{"feature.md", "proof.md", "status.md"} {

package/engine/tests/parity_buildreadiness_test.go

@@ -1,36 +1,135 @@
 package main_test
 
-// TestParityBuildReadiness checks the build-readiness gate's stdout + exit code
+// TestParityBuildReadiness checks the build-readiness gate's stdout and exit code
 // against the golden snapshot for each state.md fixture.
 
-import "testing"
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/devrites/devrites/internal/lib"
+)
 
 func TestParityBuildReadiness(t *testing.T) {
 	work := t.TempDir()
 
-	// Status halts (stderr-only messages; parity is stdout + exit code).
+	// Status halts write only to stderr; parity covers stdout and the 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
+	writeReadyArtifacts := func(slug string) {
+		t.Helper()
+		writeCoverageArtifacts(t, work, slug)
+		for name, body := range map[string]string{
+			"architecture.md": "# Architecture\n\nExisting layer.\n",
+			"plan.md":         "# Plan\n\nOne slice.\n",
+			"tasks.md":        "# Tasks\n\n## SLICE-001\nBuild.\n",
+			"traceability.md": "# Traceability\n\nAC-001 -> SLICE-001.\n",
+			"test-plan.md": `# Test plan
+
+DevRites contract: devrites.readiness-artifacts.v2
+
+## Build-entry preflight
+| Gate | Command | Cwd | Expected | Prerequisites | Provenance to recapture |
+| --- | --- | --- | --- | --- | --- |
+| unit | go test ./... | engine | exit 0 | none | go version |
+
+## Per-gap test requirements
+| ID | Path / flow | Test file | Asserts | Kind | Slice | Priority |
+| --- | --- | --- | --- | --- | --- | --- |
+| T1 | flow | flow_test.go | request → success | unit | SLICE-001 | P1 |
+
+## Acceptance → test map
+- AC-001 → T1
+`,
+		} {
+			writeFeatureFile(t, work, slug, name, body)
+		}
+		root := filepath.Join(work, ".devrites")
+		digest, err := lib.ReadinessInputDigest(root, slug, "engineering")
+		if err != nil {
+			t.Fatal(err)
+		}
+		writeFeatureFile(t, work, slug, "eng-review.md", fmt.Sprintf(`# Eng review
+
+DevRites contract: devrites.readiness-artifacts.v2
+Implementation readiness: READY
+Readiness inputs SHA-256: %s
+
+## 2a. Build-entry preflight
+| Gate | Command + cwd | Tool/version | Prerequisite owner | Full provenance inputs | Fixture/smoke | Verdict |
+| --- | --- | --- | --- | --- | --- | --- |
+| unit | go test ./... | go | none | go.mod | focused | pass |
+
+## 2b. Implementation readiness
+| Surface | Requirement/decision | Boundary/wiring | Slice | Proof | Verdict |
+| --- | --- | --- | --- | --- | --- |
+| flow | AC-001 | existing | SLICE-001 | T1 | ready |
+
+## 4. Failure modes
+| New codepath | Realistic failure | Test? | Handling? | Silent? | Verdict |
+| --- | --- | --- | --- | --- | --- |
+| flow | invalid | yes | yes | no | ok |
+
+## 7. Completion summary
+- Ready.
+`, digest))
+	}
+
+	// A ready feature has an approved plan, running status, and current
+	// clarification and vet artifacts.
+	for _, slug := range []string{"approved", "trailpipe", "trailhash", "emptystatus"} {
+		writeReadyArtifacts(slug)
+	}
+	writeFeatureFile(t, work, "approved", "state.md", "- Phase: vet\n- Plan approved: 2024-01-01\n- Status: running\n") // exit 0
 
 	// Plan not approved: missing line, or the literal "none".
+	writeCoverageArtifacts(t, work, "noapprove")
+	writeCoverageArtifacts(t, work, "approvenone")
 	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
+	writeFeatureFile(t, work, "trailpipe", "state.md", "- Phase: vet\n- Plan approved: 2024-01-01\n- Status: running | none\n") // exit 0
+	writeFeatureFile(t, work, "trailhash", "state.md", "- Phase: vet\n- Plan approved: 2024-01-01\n- Status: running # note\n") // exit 0
+
+	// An empty Status with an approved plan renders as "running".
+	writeFeatureFile(t, work, "emptystatus", "state.md", "- Phase: vet\n- Plan approved: 2024-01-01\n- Status: \n") // exit 0
+
+	// A plan cannot build without an explicit closed clarification scan and a
+	// successful engineering-readiness verdict. These are objective routes, not
+	// human questions.
+	writeFeatureFile(t, work, "noclarify", "state.md", "- Phase: vet\n- Plan approved: 2024-01-01\n- Status: running\n") // exit 6
+
+	writeFeatureFile(t, work, "clarifyopen", "state.md", "- Phase: vet\n- Plan approved: 2024-01-01\n- Status: running\n") // exit 6
+	writeFeatureFile(t, work, "clarifyopen", "brief.md", "# Brief\n\nOutcome.\n")
+	writeFeatureFile(t, work, "clarifyopen", "spec.md", "# Spec\n\nAC-001.\n")
+	writeFeatureFile(t, work, "clarifyopen", "decision-coverage.md", "# Decision coverage\n\n- Decision coverage: NEEDS CLARIFICATION\n")
 
-	// 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
+	writeFeatureFile(t, work, "novet", "state.md", "- Phase: plan\n- Plan approved: 2024-01-01\n- Status: running\n") // exit 7
+	writeCoverageArtifacts(t, work, "novet")
+
+	writeFeatureFile(t, work, "vetnotready", "state.md", "- Phase: vet\n- Plan approved: 2024-01-01\n- Status: running\n") // exit 7
+	writeCoverageArtifacts(t, work, "vetnotready")
+	writeFeatureFile(t, work, "vetnotready", "eng-review.md", "# Engineering review\n\n- Implementation readiness: NEEDS REPLAN\n")
+
+	writeReadyArtifacts("stalevet")
+	writeFeatureFile(t, work, "stalevet", "state.md", "- Phase: plan\n- Plan approved: 2024-01-01\n- Status: running\n") // exit 7
+
+	writeCoverageArtifacts(t, work, "legacycontract")
+	writeFeatureFile(t, work, "legacycontract", "state.md", "- Phase: vet\n- Plan approved: 2024-01-01\n- Status: running\n") // exit 8
+	legacyCoverage := filepath.Join(work, ".devrites", "features", "legacycontract", "decision-coverage.md")
+	replaceInFile(t, legacyCoverage, "DevRites contract: devrites.readiness-artifacts.v2\n", "")
 
 	// "ghost" is intentionally never created → no workspace/state.md (exit 5).
 	for _, arg := range []string{
 		"await", "blocked", "approved", "noapprove", "approvenone",
-		"trailpipe", "trailhash", "emptystatus", "ghost",
+		"trailpipe", "trailhash", "emptystatus", "noclarify", "clarifyopen",
+		"novet", "vetnotready", "stalevet", "legacycontract", "ghost",
 	} {
 		c := parityCase{
 			workdir: work,
@@ -40,3 +139,61 @@ func TestParityBuildReadiness(t *testing.T) {
 		t.Run("arg="+arg, func(t *testing.T) { c.assertEqual(t) })
 	}
 }
+
+func replaceInFile(t *testing.T, path, old, replacement string) {
+	t.Helper()
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	body := string(data)
+	if strings.Count(body, old) != 1 {
+		t.Fatalf("%s: expected exactly one %q", path, old)
+	}
+	if err := os.WriteFile(path, []byte(strings.Replace(body, old, replacement, 1)), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func writeCoverageArtifacts(t *testing.T, work, slug string) {
+	t.Helper()
+	writeFeatureFile(t, work, slug, "brief.md", "# Brief\n\nOutcome.\n")
+	writeFeatureFile(t, work, slug, "spec.md", "# Spec\n\n## Acceptance criteria\n- AC-001 succeeds.\n")
+	writeFeatureFile(t, work, slug, "decisions.md", "# Decisions\n\nNo open product decisions.\n")
+	writeFeatureFile(t, work, slug, "assumptions.md", "# Assumptions\n\nNo material assumptions.\n")
+	writeFeatureFile(t, work, slug, "questions.md", "# Questions\n\nNone.\n")
+	root := filepath.Join(work, ".devrites")
+	digest, err := lib.ReadinessInputDigest(root, slug, "coverage")
+	if err != nil {
+		t.Fatal(err)
+	}
+	writeFeatureFile(t, work, slug, "decision-coverage.md", fmt.Sprintf(`# Decision coverage
+
+DevRites contract: devrites.readiness-artifacts.v2
+Decision coverage: CLEAR
+Coverage inputs SHA-256: %s
+
+## Topology
+| Surface | Kind | Related IDs | Evidence |
+| --- | --- | --- | --- |
+| flow | behavior | AC-001 | spec.md |
+
+## Coverage matrix
+| Surface | Dimension | Status | Canonical reference | Owner / validation gate | Consequence if wrong |
+| --- | --- | --- | --- | --- | --- |
+| flow | behavior | closed | AC-001 | rite-prove | failure |
+
+## Assumption audit
+| Assumption | Evidence | Confidence | Owner | Validation | Consequence if wrong |
+| --- | --- | --- | --- | --- | --- |
+| none | n/a | high | n/a | n/a | n/a |
+
+## Residual uncertainty
+| Item | Why nonblocking | Owner | Validation gate |
+| --- | --- | --- | --- |
+| none | n/a | n/a | n/a |
+
+## Readiness verdict
+No unresolved decision remains.
+`, digest))
+}

package/engine/tests/parity_learnings_test.go

@@ -1,10 +1,9 @@
 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.
+// Learning state lives at the root selected by DEVRITES_ROOT. The mine and nudge
+// fixtures use counts of 3 and 2 so sorting never depends on a platform-specific
+// tie.
 
 import (
 	"path/filepath"
@@ -14,10 +13,11 @@ import (
 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.
+	// Add to a fresh workspace. Bash creates the ledger and a dated entry, then Go
+	// appends another. Only stdout ("learnings: recorded.") and exit 0 belong to
+	// the contract because the dated file entry is nondeterministic.
 	addw := t.TempDir()
+	mkdirAllT(t, addw, ".devrites")
 	t.Run("add", func(t *testing.T) {
 		(parityCase{
 			workdir: addw, env: libRootEnv(addw),
@@ -25,7 +25,7 @@ func TestParityLearnings(t *testing.T) {
 		}).assertEqual(t)
 	})
 
-	// --- list: a pre-written ledger; both sides cat the same file verbatim.
+	// List a prepared ledger. Both implementations print the file unchanged.
 	listw := t.TempDir()
 	writeFile(t, listw, filepath.Join(".devrites", "learnings.md"),
 		"# DevRites learnings ledger\n\n"+
@@ -38,10 +38,9 @@ func TestParityLearnings(t *testing.T) {
 		}).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`.
+	// Mine and nudge use two archived features. Normalization strips IDs, paths,
+	// and numbers, so "recurring finding" has count 3 and "second dead end" has
+	// count 2. The distinct counts keep sort order stable.
 	arch := t.TempDir()
 	writeFile(t, arch, filepath.Join(".devrites", "archive", "feat-a", "decisions.md"),
 		"# decisions for feat-a\n"+
@@ -55,7 +54,7 @@ func TestParityLearnings(t *testing.T) {
 			"- 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).
+	// Both implementations resolve the default archive to the same directory.
 	t.Run("mine", func(t *testing.T) {
 		(parityCase{
 			workdir: arch, env: libRootEnv(arch),
@@ -63,8 +62,8 @@ func TestParityLearnings(t *testing.T) {
 		}).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.
+	// Both implementations resolve an explicit relative path against workdir, so
+	// the missing path in the message is identical.
 	t.Run("mine-no-archive", func(t *testing.T) {
 		(parityCase{
 			workdir: arch, env: libRootEnv(arch),
@@ -72,7 +71,7 @@ func TestParityLearnings(t *testing.T) {
 		}).assertEqual(t)
 	})
 
-	// nudge: >=2 features + a class recurring 3x + no review marker ⇒ the nudge line.
+	// Two features, three occurrences, and no review marker produce a nudge.
 	t.Run("nudge", func(t *testing.T) {
 		(parityCase{
 			workdir: arch, env: libRootEnv(arch),
@@ -80,7 +79,7 @@ func TestParityLearnings(t *testing.T) {
 		}).assertEqual(t)
 	})
 
-	// --- unknown cmd: usage to stderr, exit 2 (stdout empty on both sides).
+	// An unknown command writes usage to stderr and exits 2 without stdout.
 	t.Run("unknown", func(t *testing.T) {
 		(parityCase{
 			workdir: arch, env: libRootEnv(arch),

package/engine/tests/parity_reconcile_test.go

@@ -2,14 +2,15 @@ package main_test
 
 import (
 	"fmt"
+	"strings"
 	"testing"
 )
 
 // TestParityReconcile checks reconcile against the golden snapshots: snapshot
-// captures the worktree as a tree object, check diffs it and flags source changes
-// outside the claimed manifest. Runs git in a real repo, so stdout + exit are
-// captured from the live command. The .devrites/ bookkeeping is skipped by the
-// gate, so it never affects the verdict.
+// captures the worktree as a tree object, check diffs it and flags changes
+// outside the orchestrator-authored allowlist, and close ends the retained
+// post-slice baseline. It runs Git in a real repository, so stdout and exit are
+// captured from the live command.
 func TestParityReconcile(t *testing.T) {
 	requireGit(t)
 
@@ -25,7 +26,12 @@ func TestParityReconcile(t *testing.T) {
 	}
 	// snapshot is also a setup step for the check-* cases, so it snapshots under a
 	// distinct key to avoid colliding with check's golden in the same subtest.
-	snapshot := func(t *testing.T, work string) {
+	snapshot := func(t *testing.T, work string, allowed ...string) {
+		body := ""
+		if len(allowed) > 0 {
+			body = strings.Join(allowed, "\n") + "\n"
+		}
+		writeFeatureFile(t, work, "feat", ".wright-allowlist", body)
 		out, code := runArgv(t, work, libRootEnv(work), "", binPath, "reconcile", "snapshot", "feat")
 		assertGoldenKey(t, t.Name()+"/snapshot", fmt.Sprintf("exit %d\n%s", code, out))
 	}
@@ -38,38 +44,35 @@ func TestParityReconcile(t *testing.T) {
 
 	t.Run("check-clean", func(t *testing.T) {
 		work := newRepo(t)
-		snapshot(t, work)
+		snapshot(t, work, "src/a.js")
 		writeFile(t, work, "src/a.js", "console.log(999)\n") // the wright's change
-		writeFeatureFile(t, work, "feat", ".reconcile-claimed", "src/a.js\n")
 		check(t, work)
 	})
 
 	t.Run("check-violation", func(t *testing.T) {
 		work := newRepo(t)
-		snapshot(t, work)
+		snapshot(t, work, "src/a.js")
 		writeFile(t, work, "src/a.js", "console.log(999)\n")
-		writeFile(t, work, "src/b.js", "console.log(888)\n") // NOT claimed -> A1 breach
-		writeFeatureFile(t, work, "feat", ".reconcile-claimed", "src/a.js\n")
+		writeFile(t, work, "src/b.js", "console.log(888)\n") // Outside the allowlist; an A1 breach.
 		check(t, work)
 	})
 
 	t.Run("check-no-base", func(t *testing.T) {
 		work := newRepo(t)
-		writeFeatureFile(t, work, "feat", ".reconcile-claimed", "src/a.js\n")
-		check(t, work) // no snapshot -> exit 6
+		check(t, work) // No snapshot, so exit 6.
 	})
 
-	t.Run("check-no-claimed", func(t *testing.T) {
+	t.Run("snapshot-no-allowlist", func(t *testing.T) {
 		work := newRepo(t)
-		snapshot(t, work)
-		check(t, work) // base present, no claimed -> exit 6
+		out, code := runArgv(t, work, libRootEnv(work), "", binPath, "reconcile", "snapshot", "feat")
+		assertGolden(t, out, code)
 	})
 
 	t.Run("inline-fallback", func(t *testing.T) {
 		work := newRepo(t)
 		snapshot(t, work)
-		writeFeatureFile(t, work, "feat", ".reconcile-inline", "")
-		check(t, work) // gate skipped -> exit 0
+		out, code := runArgv(t, work, libRootEnv(work), "", binPath, "reconcile", "close", "feat")
+		assertGolden(t, out, code)
 	})
 
 	t.Run("not-git", func(t *testing.T) {

package/engine/tests/parity_resolve_test.go

@@ -7,8 +7,8 @@ import (
 	"testing"
 )
 
-// Golden snapshot for resolve: it MUTATES questions.md + state.md. Each case
-// snapshots the command's stdout + exit code and, for the mutating cases, the
+// Golden snapshots for resolve include its changes to questions.md and state.md.
+// Each case records stdout and the exit code. Mutating cases also record the
 // resulting file bytes. The two nondeterministic timestamp fields (answered_at
 // and the Log entry) are masked out before the file content is snapshotted so the
 // golden is deterministic across runs.
@@ -45,8 +45,8 @@ const resolveState = `- Status: awaiting_human
 `
 
 func TestParityResolve(t *testing.T) {
-	// setup writes the fixtures into a Go tree (.devrites/features/feat) and returns
-	// the workspace root.
+	// setup writes fixtures under .devrites/features/feat and returns the
+	// workspace root.
 	setup := func(t *testing.T, questions, state string) (gwork string) {
 		t.Helper()
 		gwork = t.TempDir()
@@ -55,7 +55,7 @@ func TestParityResolve(t *testing.T) {
 		writeFile(t, gwork, filepath.Join(".devrites", "ACTIVE"), "feat\n")
 		return gwork
 	}
-	// run executes resolve in gwork and snapshots its stdout + exit code under the
+	// run executes resolve in gwork and snapshots stdout and the exit code under the
 	// current subtest's golden.
 	run := func(t *testing.T, gwork string, args ...string) {
 		t.Helper()
@@ -124,16 +124,17 @@ answer: prior
 	})
 
 	t.Run("no-workspace", func(t *testing.T) {
-		// Bare tree: no ACTIVE, no questions.md -> exit 2.
+		// A bare tree with no explicit root, ACTIVE, or questions.md exits 2.
+		// Pointing DEVRITES_ROOT at the nonexistent .devrites child would instead
+		// be an explicit unsafe-root refusal, which is a different contract.
 		gwork := t.TempDir()
-		run(t, gwork, "q-1", "x")
+		out, code := runArgv(t, gwork, libEnv, "", binPath, "resolve", "q-1", "x")
+		assertGolden(t, out, code)
 	})
 
 	t.Run("next-qid", func(t *testing.T) {
-		// Read-only: computes the next qid for an explicit questions.md path.
-		// DEVRITES_NOW pins the clock so the golden is stable across day
-		// boundaries: without it the qid tracks the real date and the snapshot
-		// fails every day but the one it was recorded on (ADR-0006, clock seam).
+		// DEVRITES_NOW fixes the date used by next-qid so the snapshot stays stable.
+		// See ADR-0006.
 		dir := t.TempDir()
 		writeFile(t, dir, "questions.md", "## q-2024-01-01-001\nstatus: open\n")
 		qpath := filepath.Join(dir, "questions.md")