devrites 3.0.6 → 3.1.0

package/engine/root_routing_test.go

@@ -0,0 +1,277 @@
+package main
+
+import (
+	"bytes"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"reflect"
+	"sort"
+	"strings"
+	"testing"
+)
+
+func TestRootModeForCoversReadAndWriteSurfaces(t *testing.T) {
+	tests := []struct {
+		name    string
+		command string
+		args    []string
+		want    rootMode
+	}{
+		{name: "unrelated command", command: "doctor", want: rootUnused},
+		{name: "first task", command: "first-task", want: rootLenient},
+		{name: "spec dedupe", command: "spec-dedupe", want: rootLenient},
+		{name: "footprint render", command: "footprint", args: []string{"render"}, want: rootLenient},
+		{name: "footprint roster", command: "footprint", args: []string{"roster"}, want: rootLenient},
+		{name: "footprint log", command: "footprint", args: []string{"log"}, want: rootStrict},
+		{name: "evidence fresh", command: "evidence-fresh", want: rootLenient},
+		{name: "coverage", command: "coverage", want: rootLenient},
+		{name: "doubt coverage", command: "doubt-coverage", want: rootLenient},
+		{name: "budget", command: "budget", want: rootLenient},
+		{name: "preamble", command: "preamble", want: rootLenient},
+		{name: "progress", command: "progress", want: rootLenient},
+		{name: "stuck check", command: "stuck", args: []string{"check"}, want: rootLenient},
+		{name: "stuck log", command: "stuck", args: []string{"log"}, want: rootStrict},
+		{name: "recovery route", command: "recovery", args: []string{"route"}, want: rootLenient},
+		{name: "recovery check", command: "recovery", args: []string{"check"}, want: rootLenient},
+		{name: "recovery fingerprint", command: "recovery", args: []string{"fingerprint"}, want: rootLenient},
+		{name: "recovery record", command: "recovery", args: []string{"record"}, want: rootStrict},
+		{name: "recovery clear", command: "recovery", args: []string{"clear"}, want: rootStrict},
+		{name: "build readiness", command: "build-readiness", want: rootLenient},
+		{name: "readiness digest", command: "readiness-digest", want: rootLenient},
+		{name: "clarify enter", command: "clarify-return", args: []string{"enter"}, want: rootStrict},
+		{name: "clarify restore", command: "clarify-return", args: []string{"restore"}, want: rootStrict},
+		{name: "analyze", command: "analyze", want: rootLenient},
+		{name: "mutation gate", command: "mutation-gate", want: rootLenient},
+		{name: "test integrity", command: "test-integrity", want: rootLenient},
+		{name: "review integrity", command: "review-integrity", want: rootLenient},
+		{name: "package existence", command: "package-existence", want: rootLenient},
+		{name: "reconcile snapshot", command: "reconcile", args: []string{"snapshot"}, want: rootStrict},
+		{name: "reconcile check", command: "reconcile", args: []string{"check"}, want: rootStrict},
+		{name: "reconcile close", command: "reconcile", args: []string{"close"}, want: rootStrict},
+		{name: "resolve", command: "resolve", want: rootStrict},
+		{name: "resolve next qid", command: "resolve", args: []string{"next-qid"}, want: rootLenient},
+		{name: "close out", command: "close-out", want: rootStrict},
+		{name: "archive search", command: "archive-search", want: rootLenient},
+		{name: "decisions search", command: "decisions", args: []string{"search"}, want: rootLenient},
+		{name: "decisions index", command: "decisions", args: []string{"index"}, want: rootStrict},
+		{name: "ledger diff", command: "ledger", args: []string{"diff"}, want: rootLenient},
+		{name: "ledger validate", command: "ledger", args: []string{"validate"}, want: rootLenient},
+		{name: "ledger list", command: "ledger", args: []string{"list"}, want: rootLenient},
+		{name: "ledger show", command: "ledger", args: []string{"show"}, want: rootLenient},
+		{name: "ledger sync", command: "ledger", args: []string{"sync"}, want: rootStrict},
+		{name: "ledger json before sync", command: "ledger", args: []string{"--json", "sync"}, want: rootStrict},
+		{name: "learnings list", command: "learnings", args: []string{"list"}, want: rootLenient},
+		{name: "learnings top", command: "learnings", args: []string{"top"}, want: rootLenient},
+		{name: "learnings mine", command: "learnings", args: []string{"mine"}, want: rootLenient},
+		{name: "learnings nudge", command: "learnings", args: []string{"nudge"}, want: rootLenient},
+		{name: "learnings add", command: "learnings", args: []string{"add"}, want: rootStrict},
+		{name: "timeline list", command: "timeline", args: []string{"list"}, want: rootLenient},
+		{name: "timeline report", command: "timeline", args: []string{"report"}, want: rootLenient},
+		{name: "timeline log", command: "timeline", args: []string{"log"}, want: rootStrict},
+		{name: "timeline purge", command: "timeline", args: []string{"purge"}, want: rootStrict},
+		{name: "health list", command: "health", args: []string{"list"}, want: rootLenient},
+		{name: "health default", command: "health", want: rootStrict},
+		{name: "health run", command: "health", args: []string{"run"}, want: rootStrict},
+		{name: "health check", command: "health", args: []string{"check"}, want: rootStrict},
+		{name: "health record", command: "health", args: []string{"record"}, want: rootStrict},
+		{name: "config", command: "config", args: []string{"get"}, want: rootLenient},
+		{name: "reviewers", command: "reviewers", args: []string{"list"}, want: rootLenient},
+		{name: "outside voice", command: "outside-voice", want: rootLenient},
+		{name: "docs stale", command: "docs-stale", want: rootLenient},
+		{name: "secret scan", command: "secret-scan", want: rootLenient},
+		{name: "review fingerprints read", command: "review-fingerprints", want: rootLenient},
+		{name: "review fingerprints write", command: "review-fingerprints", args: []string{"demo", "--write"}, want: rootStrict},
+		{name: "reviewer stats report", command: "reviewer-stats", args: []string{"report"}, want: rootLenient},
+		{name: "reviewer stats record", command: "reviewer-stats", args: []string{"record"}, want: rootStrict},
+		{name: "lanes", command: "lanes", args: []string{"plan"}, want: rootLenient},
+		{name: "forge missing verb", command: "forge", want: rootStrict},
+		{name: "forge plan", command: "forge", args: []string{"plan"}, want: rootStrict},
+		{name: "forge record", command: "forge", args: []string{"record"}, want: rootStrict},
+		{name: "forge extract", command: "forge", args: []string{"extract"}, want: rootStrict},
+		{name: "forge merge", command: "forge", args: []string{"merge"}, want: rootStrict},
+		{name: "forge cleanup", command: "forge", args: []string{"cleanup"}, want: rootStrict},
+		{name: "forge reap", command: "forge", args: []string{"reap"}, want: rootStrict},
+		{name: "extensions list", command: "extensions", args: []string{"list"}, want: rootLenient},
+		{name: "extensions validate", command: "extensions", args: []string{"validate"}, want: rootLenient},
+		{name: "extensions sync", command: "extensions", args: []string{"sync"}, want: rootStrict},
+		{name: "overrides", command: "overrides", args: []string{"validate"}, want: rootLenient},
+		{name: "context show", command: "context", args: []string{"show"}, want: rootLenient},
+		{name: "context sync", command: "context", args: []string{"sync"}, want: rootStrict},
+		{name: "runbook list", command: "runbook", args: []string{"list"}, want: rootLenient},
+		{name: "runbook validate", command: "runbook", args: []string{"validate"}, want: rootLenient},
+		{name: "runbook run", command: "runbook", args: []string{"run"}, want: rootStrict},
+		{name: "runbook resume", command: "runbook", args: []string{"resume"}, want: rootStrict},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			if got := rootModeFor(test.command, test.args); got != test.want {
+				t.Fatalf("rootModeFor(%q, %q) = %d, want %d", test.command, test.args, got, test.want)
+			}
+		})
+	}
+}
+
+func TestStrictForgeRefusesParentWorkspaceAcrossNestedRepository(t *testing.T) {
+	parent := t.TempDir()
+	if err := os.Mkdir(filepath.Join(parent, ".devrites"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	child := filepath.Join(parent, "nested")
+	if err := os.Mkdir(child, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	initRootRoutingGitRepo(t, child)
+	withRootRoutingCWD(t, child)
+	t.Setenv("DEVRITES_ROOT", "")
+	t.Setenv("DEVRITES_WORKSPACE", "")
+
+	var stdout, stderr bytes.Buffer
+	code := run([]string{"forge", "plan"}, strings.NewReader(""), &stdout, &stderr)
+	if code != exitBlocked {
+		t.Fatalf("forge plan exit = %d, want %d; stdout=%q stderr=%q", code, exitBlocked, stdout.String(), stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "unsafe DevRites root") {
+		t.Fatalf("stderr = %q, want unsafe-root refusal", stderr.String())
+	}
+	if _, err := os.Stat(filepath.Join(child, ".devrites")); !os.IsNotExist(err) {
+		t.Fatalf("strict refusal must not create nested workspace; stat err=%v", err)
+	}
+
+	stdout.Reset()
+	stderr.Reset()
+	code = run([]string{"context", "show"}, strings.NewReader(""), &stdout, &stderr)
+	if code != exitOK {
+		t.Fatalf("context show exit = %d, want %d; stderr=%q", code, exitOK, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "DRV-ROOT-OUTSIDE-GIT") {
+		t.Fatalf("context show should diagnose the unsafe parent root; stdout=%q", stdout.String())
+	}
+}
+
+func TestStrictWriterRefusesExternalWorkspaceBeforeMutation(t *testing.T) {
+	project := t.TempDir()
+	root := filepath.Join(project, ".devrites")
+	if err := os.MkdirAll(filepath.Join(root, "work", "demo"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	initRootRoutingGitRepo(t, project)
+	withRootRoutingCWD(t, project)
+	t.Setenv("DEVRITES_ROOT", "")
+	t.Setenv("DEVRITES_WORKSPACE", t.TempDir())
+	before := rootRoutingTree(t, root)
+
+	var stdout, stderr bytes.Buffer
+	code := run([]string{"timeline", "log", "rite-build"}, strings.NewReader(""), &stdout, &stderr)
+	if code != exitBlocked {
+		t.Fatalf("timeline log exit = %d, want %d; stdout=%q stderr=%q", code, exitBlocked, stdout.String(), stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "unsafe DevRites root") {
+		t.Fatalf("stderr = %q, want unsafe-root refusal", stderr.String())
+	}
+	if after := rootRoutingTree(t, root); !reflect.DeepEqual(after, before) {
+		t.Fatalf("strict refusal mutated workspace tree: before=%q after=%q", before, after)
+	}
+
+	stdout.Reset()
+	stderr.Reset()
+	code = run(
+		[]string{"timeline", "purge", "--run", "drv-run-v1:0123456789abcdef0123456789abcdef"},
+		strings.NewReader(""),
+		&stdout,
+		&stderr,
+	)
+	if code != exitBlocked {
+		t.Fatalf("timeline purge exit = %d, want %d; stdout=%q stderr=%q", code, exitBlocked, stdout.String(), stderr.String())
+	}
+	if after := rootRoutingTree(t, root); !reflect.DeepEqual(after, before) {
+		t.Fatalf("unsafe timeline purge mutated workspace tree: before=%q after=%q", before, after)
+	}
+}
+
+func TestStrictWriterRefusesWorkspaceOverrideWithoutRoot(t *testing.T) {
+	project := t.TempDir()
+	initRootRoutingGitRepo(t, project)
+	withRootRoutingCWD(t, project)
+	t.Setenv("DEVRITES_ROOT", "")
+	t.Setenv("DEVRITES_WORKSPACE", t.TempDir())
+
+	var stdout, stderr bytes.Buffer
+	code := run([]string{"learnings", "add", "demo", "must not escape"}, strings.NewReader(""), &stdout, &stderr)
+	if code != exitBlocked {
+		t.Fatalf("learnings add exit = %d, want %d; stdout=%q stderr=%q", code, exitBlocked, stdout.String(), stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "DEVRITES_WORKSPACE requires a selected DevRites root") {
+		t.Fatalf("stderr = %q, want workspace-without-root refusal", stderr.String())
+	}
+	if _, err := os.Stat(filepath.Join(project, ".devrites")); !os.IsNotExist(err) {
+		t.Fatalf("strict refusal must not create a root; stat err=%v", err)
+	}
+}
+
+func TestStrictWriterRefusesMissingExplicitRoot(t *testing.T) {
+	project := t.TempDir()
+	initRootRoutingGitRepo(t, project)
+	withRootRoutingCWD(t, project)
+	root := filepath.Join(project, ".devrites")
+	t.Setenv("DEVRITES_ROOT", root)
+	t.Setenv("DEVRITES_WORKSPACE", "")
+
+	var stdout, stderr bytes.Buffer
+	code := run([]string{"learnings", "add", "demo", "must not bootstrap"}, strings.NewReader(""), &stdout, &stderr)
+	if code != exitBlocked {
+		t.Fatalf("learnings add exit = %d, want %d; stdout=%q stderr=%q", code, exitBlocked, stdout.String(), stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "unsafe DevRites root") {
+		t.Fatalf("stderr = %q, want invalid explicit-root refusal", stderr.String())
+	}
+	if _, err := os.Stat(root); !os.IsNotExist(err) {
+		t.Fatalf("strict refusal must not create explicit missing root; stat err=%v", err)
+	}
+}
+
+func initRootRoutingGitRepo(t *testing.T, dir string) {
+	t.Helper()
+	cmd := exec.Command("git", "init", "-q", dir)
+	if output, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("git init %s: %v\n%s", dir, err, output)
+	}
+}
+
+func withRootRoutingCWD(t *testing.T, dir string) {
+	t.Helper()
+	before, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Chdir(dir); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		if err := os.Chdir(before); err != nil {
+			t.Errorf("restore cwd: %v", err)
+		}
+	})
+}
+
+func rootRoutingTree(t *testing.T, root string) []string {
+	t.Helper()
+	var paths []string
+	err := filepath.WalkDir(root, func(path string, entry os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		rel, err := filepath.Rel(root, path)
+		if err != nil {
+			return err
+		}
+		paths = append(paths, rel)
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	sort.Strings(paths)
+	return paths
+}

package/engine/testdata/golden/TestParityBuildReadiness/arg=approved.golden

@@ -1,2 +1,2 @@
 exit 0
-readiness: OK: plan approved 2024-01-01, status running. Ready to build.
+readiness: OK: plan approved 2024-01-01, decision coverage CLEAR, implementation READY, status running. Ready to build.

package/engine/testdata/golden/TestParityBuildReadiness/arg=emptystatus.golden

@@ -1,2 +1,2 @@
 exit 0
-readiness: OK: plan approved 2024-01-01, status running. Ready to build.
+readiness: OK: plan approved 2024-01-01, decision coverage CLEAR, implementation READY, status running. Ready to build.

package/engine/testdata/golden/TestParityBuildReadiness/arg=noclarify.golden

@@ -0,0 +1 @@
+exit 6

package/engine/testdata/golden/TestParityBuildReadiness/arg=novet.golden

@@ -0,0 +1 @@
+exit 7

package/engine/testdata/golden/TestParityBuildReadiness/arg=stalevet.golden

@@ -0,0 +1 @@
+exit 7

package/engine/testdata/golden/TestParityBuildReadiness/arg=trailhash.golden

@@ -1,2 +1,2 @@
 exit 0
-readiness: OK: plan approved 2024-01-01, status running. Ready to build.
+readiness: OK: plan approved 2024-01-01, decision coverage CLEAR, implementation READY, status running. Ready to build.

package/engine/testdata/golden/TestParityBuildReadiness/arg=trailpipe.golden

@@ -1,2 +1,2 @@
 exit 0
-readiness: OK: plan approved 2024-01-01, status running. Ready to build.
+readiness: OK: plan approved 2024-01-01, decision coverage CLEAR, implementation READY, status running. Ready to build.

package/engine/testdata/golden/TestParityBuildReadiness/arg=vetnotready.golden

@@ -0,0 +1 @@
+exit 7

package/engine/testdata/golden/TestParityProgress/arg=allbuilt.golden

@@ -1,4 +1,4 @@
 exit 0
 ── rite-build ─────────
 Slices 2/2  ██████████  ✅ ALL BUILT
-Flow   spec ✓ define ✓ plan ✓ build ◉ prove ○ polish ○ review ○ seal ○ ship ○
+Flow   spec ✓ clarify ✓ define ✓ plan ✓ build ◉ prove ○ polish ○ review ○ seal ○ ship ○

package/engine/testdata/golden/TestParityProgress/arg=done.golden

@@ -1,3 +1,3 @@
 exit 0
 ── rite-done ─────────
-Flow   spec ✓ define ✓ plan ✓ build ✓ prove ✓ polish ✓ review ✓ seal ✓ ship ✓
+Flow   spec ✓ clarify ✓ define ✓ plan ✓ build ✓ prove ✓ polish ✓ review ✓ seal ✓ ship ✓

package/engine/testdata/golden/TestParityProgress/arg=mid.golden

@@ -1,4 +1,4 @@
 exit 0
 ── rite-build ─────────
 Slice 2/3  ███████░░░  detail ✓
-Flow   spec ✓ temper ✓ define ✓ plan ✓ vet ✓ build ◉ prove ○ polish ○ review ○ seal ○ ship ○
+Flow   spec ✓ clarify ✓ temper ✓ define ✓ plan ✓ vet ✓ build ◉ prove ○ polish ○ review ○ seal ○ ship ○

package/engine/testdata/golden/TestParityProgress/arg=nophase.golden

@@ -1,3 +1,3 @@
 exit 0
 ── rite-spec ─────────
-Flow   spec ◉ define ○ plan ○ build ○ prove ○ polish ○ review ○ seal ○ ship ○
+Flow   spec ◉ clarify ○ define ○ plan ○ build ○ prove ○ polish ○ review ○ seal ○ ship ○

package/engine/testdata/golden/TestParityProgress/arg=noslice.golden

@@ -1,3 +1,3 @@
 exit 0
 ── rite-spec ─────────
-Flow   spec ◉ define ○ plan ○ build ○ prove ○ polish ○ review ○ seal ○ ship ○
+Flow   spec ◉ clarify ○ define ○ plan ○ build ○ prove ○ polish ○ review ○ seal ○ ship ○

package/engine/testdata/golden/TestParityProgress/arg=plan.golden

@@ -1,4 +1,4 @@
 exit 0
 ── rite-plan ─────────
 Slice 2/3  ███████░░░  detail ✓
-Flow   spec ✓ define ✓ plan ◉ build ○ prove ○ polish ○ review ○ seal ○ ship ○
+Flow   spec ✓ clarify ✓ define ✓ plan ◉ build ○ prove ○ polish ○ review ○ seal ○ ship ○

package/engine/testdata/golden/TestParityProgress/arg=seal.golden

@@ -1,3 +1,3 @@
 exit 0
 ── rite-seal ─────────
-Flow   spec ✓ define ✓ plan ✓ build ✓ prove ✓ polish ✓ review ✓ seal ◉ ship ○
+Flow   spec ✓ clarify ✓ define ✓ plan ✓ build ✓ prove ✓ polish ✓ review ✓ seal ◉ ship ○

package/engine/testdata/golden/TestParityReconcile/check-clean.golden

@@ -1,2 +1,2 @@
 exit 0
-reconcile: OK: every source change is the wright's; orchestrator touched only bookkeeping.
+reconcile: OK: every slice change matches the orchestrator allowlist; baseline retained for post-slice gates (run "reconcile close" afterward).

package/engine/testdata/golden/TestParityReconcile/inline-fallback.golden

@@ -1 +1,2 @@
 exit 0
+reconcile: closed slice window for feat.

package/engine/testdata/golden/TestParityReconcile/snapshot-no-allowlist.golden

@@ -0,0 +1 @@
+exit 6

package/engine/testdata/golden/TestParityWrightScope/devrites-edit-denied.golden

@@ -0,0 +1,2 @@
+exit 0
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"DevRites scope: this write is not in the orchestrator-provided exact wright allowlist, or it targets .devrites. Build only the slice contract; return the blocked path to the orchestrator instead of widening scope. (devrites-wright-scope)"}}

package/engine/testdata/golden/TestParityWrightScope/out-of-scope-enforce-denies.golden

@@ -1,2 +1,2 @@
 exit 0
-{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"DevRites scope: this path is not in touched-files.md. Build only the slice contract; if the slice genuinely needs this file, return an Escalation so the orchestrator routes it through the Spec Drift Guard: do not widen scope yourself. (devrites-wright-scope)"}}
+{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"DevRites scope: this write is not in the orchestrator-provided exact wright allowlist, or it targets .devrites. Build only the slice contract; return the blocked path to the orchestrator instead of widening scope. (devrites-wright-scope)"}}

package/engine/tests/adr_0011_define_plan_test.go

@@ -0,0 +1,30 @@
+package main_test
+
+import (
+	"testing"
+
+	"github.com/devrites/devrites/internal/state"
+)
+
+func TestADR0011DefineAndPlanHaveDistinctTransitionRights(t *testing.T) {
+	if got := state.ResumeVerb(state.PhaseDefine); got != "define" {
+		t.Fatalf("define resumes %q, want define", got)
+	}
+	if got := state.ResumeVerb(state.PhasePlan); got != "vet" {
+		t.Fatalf("plan resumes %q, want vet", got)
+	}
+	if got, ok := state.PhaseForName("planning"); !ok || got != state.PhasePlan {
+		t.Fatalf("planning alias=(%q,%v), want plan compatibility", got, ok)
+	}
+
+	rights := map[string]state.Phase{}
+	for _, phase := range state.WorkflowPhases() {
+		if phase.TransitionRight == "" {
+			t.Fatalf("phase %q has no transition right", phase.ID)
+		}
+		if prior := rights[phase.TransitionRight]; prior != "" {
+			t.Fatalf("phases %q and %q share transition right %q", prior, phase.ID, phase.TransitionRight)
+		}
+		rights[phase.TransitionRight] = phase.ID
+	}
+}

package/engine/tests/budget_test.go

@@ -5,18 +5,29 @@ import (
 	"testing"
 )
 
-// TestStatusLiveWorkspace is the P2 acceptance check: `devrites-engine status <slug>`
-// must report a canonical work/<slug> feature the live pack created without a
-// workspace-map frontmatter: phase from the canonical state.md ledger and proof/status
-// completeness from canonical evidence.md/state.md files. Before schema unification this returned
+// TestStatusLiveWorkspace checks a canonical work/<slug> feature without
+// workspace-map frontmatter. Status must read the phase from state.md and
+// completeness from evidence.md and state.md instead of reporting
 // "feature not found".
 func TestStatusLiveWorkspace(t *testing.T) {
 	work := t.TempDir()
 	writeFile(t, work, ".devrites/work/live/state.md", "- Phase: build\n- Status: running\n")
-	writeFile(t, work, ".devrites/work/live/spec.md", "# Spec\n\nDo the thing.\n")
-	writeFile(t, work, ".devrites/work/live/plan.md", "# Plan\n\nApproach.\n")
-	writeFile(t, work, ".devrites/work/live/decisions.md", "# Decisions\n\nChose X.\n")
-	writeFile(t, work, ".devrites/work/live/tasks.md", "# Tasks\n\n- [x] slice 1\n")
+	for name, body := range map[string]string{
+		"brief.md":             "# Brief\n\nDo the thing.\n",
+		"spec.md":              "# Spec\n\nDo the thing.\n",
+		"decisions.md":         "# Decisions\n\nChose X.\n",
+		"assumptions.md":       "# Assumptions\n\nNone.\n",
+		"questions.md":         "# Questions\n\nNone.\n",
+		"decision-coverage.md": "# Decision coverage\n\nCLEAR.\n",
+		"architecture.md":      "# Architecture\n\nExisting layer.\n",
+		"plan.md":              "# Plan\n\nApproach.\n",
+		"tasks.md":             "# Tasks\n\n- [x] slice 1\n",
+		"traceability.md":      "# Traceability\n\nMapped.\n",
+		"eng-review.md":        "# Engineering review\n\nREADY.\n",
+		"test-plan.md":         "# Test plan\n\nRun tests.\n",
+	} {
+		writeFile(t, work, ".devrites/work/live/"+name, body)
+	}
 	(parityCase{
 		workdir: work,
 		env:     libRootEnv(work),

package/engine/tests/concurrency_cli_test.go

@@ -19,8 +19,13 @@ import (
 // from many goroutines. It returns stdout and exit code (and a fatal error only
 // for a non-exit failure like the binary being unrunnable).
 func runProc(root string, args ...string) (stdout string, code int, fatal error) {
+	return runProcInput(root, "", args...)
+}
+
+func runProcInput(root, stdin string, args ...string) (stdout string, code int, fatal error) {
 	cmd := exec.Command(binPath, args...)
 	cmd.Env = append(os.Environ(), "DEVRITES_ROOT="+root)
+	cmd.Stdin = strings.NewReader(stdin)
 	var out bytes.Buffer
 	cmd.Stdout = &out
 	cmd.Stderr = &bytes.Buffer{}
@@ -94,7 +99,8 @@ func TestConcurrentStopGateAppendsNeverTear(t *testing.T) {
 		wg.Add(1)
 		go func(i int) {
 			defer wg.Done()
-			_, code, fatal := runProc(root, "hook", "stop-gate", "--harness=claude")
+			_, code, fatal := runProcInput(root, `{"stop_hook_active":false}`,
+				"hook", "stop-gate", "--harness=claude")
 			if fatal != nil {
 				code = -1
 			}

package/engine/tests/doctor_cli_test.go

@@ -1,9 +1,12 @@
 package main_test
 
-// Issue 05: `doctor` version triangle, at the CLI seam.
+// CLI coverage for Issue 05: the `doctor` version triangle.
 
 import (
+	"bytes"
+	"errors"
 	"os"
+	"os/exec"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -15,13 +18,101 @@ func TestDoctorPrintsTriangle(t *testing.T) {
 	if code != 0 {
 		t.Fatalf("exit = %d, want 0 (stderr: %s)", code, errOut)
 	}
-	for _, leg := range []string{"binary:", "pack:", "state-schema:", "verdict:"} {
+	for _, leg := range []string{"project:", "root:", "root-selection:", "binary:", "pack:", "state-schema:", "verdict:"} {
 		if !strings.Contains(out, leg) {
 			t.Errorf("doctor output missing %q leg\n%s", leg, out)
 		}
 	}
 }
 
+func TestDoctorReportsStaleActiveWithPasteableRepair(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, "doctor")
+	if code != 0 {
+		t.Fatalf("exit = %d, want warning exit 0 (stderr: %s)\n%s", code, errOut, out)
+	}
+	if !strings.Contains(out, "[DRV-ACTIVE-STALE]") || !strings.Contains(out, "fix: rm -f") {
+		t.Fatalf("doctor did not diagnose stale ACTIVE with remediation:\n%s", out)
+	}
+}
+
+func TestDoctorRefusesParentStateAcrossNestedRepositoryBoundary(t *testing.T) {
+	outer := doctorRepo(t, filepath.Join(t.TempDir(), "outer"))
+	if err := os.MkdirAll(filepath.Join(outer, ".devrites"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	child := doctorRepo(t, filepath.Join(outer, "services", "child"))
+	out, errOut, code := runDoctorAt(t, child)
+	if code != 3 {
+		t.Fatalf("exit = %d, want unsafe-root refusal (stderr: %s)\n%s", code, errOut, out)
+	}
+	if !strings.Contains(out, "[DRV-ROOT-OUTSIDE-GIT]") || !strings.Contains(out, "fix: cd ") {
+		t.Fatalf("doctor did not explain nested-repository boundary:\n%s", out)
+	}
+}
+
+func TestDoctorKeepsOrdinaryRootAbsenceDiagnosable(t *testing.T) {
+	repo := doctorRepo(t, filepath.Join(t.TempDir(), "repo"))
+	out, errOut, code := runDoctorAt(t, repo)
+	if code != 0 {
+		t.Fatalf("exit = %d, want diagnostic exit 0 (stderr: %s)\n%s", code, errOut, out)
+	}
+	if !strings.Contains(out, "root: none") || !strings.Contains(out, "[DRV-ROOT-NOT-FOUND]") {
+		t.Fatalf("doctor hid ordinary root absence:\n%s", out)
+	}
+}
+
+func TestDoctorRefusesWorkspaceOverrideWithoutRoot(t *testing.T) {
+	repo := doctorRepo(t, filepath.Join(t.TempDir(), "repo"))
+	out, errOut, code := runDoctorAtEnv(t, repo, "DEVRITES_WORKSPACE="+t.TempDir())
+	if code != 3 {
+		t.Fatalf("exit = %d, want unsafe-root refusal (stderr: %s)\n%s", code, errOut, out)
+	}
+	if !strings.Contains(out, "[DRV-WORKSPACE-WITHOUT-ROOT]") || !strings.Contains(out, "fix: unset DEVRITES_WORKSPACE") {
+		t.Fatalf("doctor hid workspace-without-root remediation:\n%s", out)
+	}
+}
+
+func TestDoctorReportsLinkedWorktreeAndSubmoduleTopology(t *testing.T) {
+	t.Run("linked worktree", func(t *testing.T) {
+		base := t.TempDir()
+		main := doctorRepo(t, filepath.Join(base, "main"))
+		worktree := filepath.Join(base, "linked")
+		doctorGit(t, main, "worktree", "add", "-q", "-b", "doctor-linked", worktree)
+		if err := os.MkdirAll(filepath.Join(worktree, ".devrites"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		out, errOut, code := runDoctorAt(t, worktree)
+		if code != 0 {
+			t.Fatalf("exit = %d stderr=%s\n%s", code, errOut, out)
+		}
+		if !strings.Contains(out, "linked-worktree=true") {
+			t.Fatalf("doctor omitted linked-worktree topology:\n%s", out)
+		}
+	})
+
+	t.Run("submodule", func(t *testing.T) {
+		base := t.TempDir()
+		origin := doctorRepo(t, filepath.Join(base, "origin"))
+		super := doctorRepo(t, filepath.Join(base, "super"))
+		doctorGit(t, super, "-c", "protocol.file.allow=always", "submodule", "add", "-q", origin, "deps/sub")
+		sub := filepath.Join(super, "deps", "sub")
+		if err := os.MkdirAll(filepath.Join(sub, ".devrites"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		out, errOut, code := runDoctorAt(t, sub)
+		if code != 0 {
+			t.Fatalf("exit = %d stderr=%s\n%s", code, errOut, out)
+		}
+		if !strings.Contains(out, "submodule=true") || !strings.Contains(out, "git-superproject:") {
+			t.Fatalf("doctor omitted submodule topology:\n%s", out)
+		}
+	})
+}
+
 func TestDoctorReportsMergeInProgress(t *testing.T) {
 	root := newWorkspace(t)
 	git := filepath.Join(filepath.Dir(root), ".git")
@@ -60,3 +151,58 @@ func TestDoctorRefusesNewerStateSchema(t *testing.T) {
 		t.Errorf("verdict not a REFUSE\n%s", out)
 	}
 }
+
+func runDoctorAt(t *testing.T, dir string) (stdout, stderr string, code int) {
+	t.Helper()
+	return runDoctorAtEnv(t, dir)
+}
+
+func runDoctorAtEnv(t *testing.T, dir string, extraEnv ...string) (stdout, stderr string, code int) {
+	t.Helper()
+	cmd := exec.Command(binPath, "doctor")
+	cmd.Dir = dir
+	for _, item := range os.Environ() {
+		if strings.HasPrefix(item, "DEVRITES_ROOT=") || strings.HasPrefix(item, "DEVRITES_WORKSPACE=") {
+			continue
+		}
+		cmd.Env = append(cmd.Env, item)
+	}
+	cmd.Env = append(cmd.Env, extraEnv...)
+	var outBuf, errBuf bytes.Buffer
+	cmd.Stdout = &outBuf
+	cmd.Stderr = &errBuf
+	err := cmd.Run()
+	if err != nil {
+		var exitErr *exec.ExitError
+		if !errors.As(err, &exitErr) {
+			t.Fatalf("doctor: %v", err)
+		}
+		code = exitErr.ExitCode()
+	}
+	return outBuf.String(), errBuf.String(), code
+}
+
+func doctorRepo(t *testing.T, path string) string {
+	t.Helper()
+	if err := os.MkdirAll(path, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	doctorGit(t, path, "init", "-q")
+	doctorGit(t, path, "config", "user.email", "devrites@example.invalid")
+	doctorGit(t, path, "config", "user.name", "DevRites Test")
+	if err := os.WriteFile(filepath.Join(path, ".fixture"), []byte("fixture\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	doctorGit(t, path, "add", ".fixture")
+	doctorGit(t, path, "commit", "-q", "-m", "fixture")
+	return path
+}
+
+func doctorGit(t *testing.T, dir string, args ...string) {
+	t.Helper()
+	cmd := exec.Command("git", append([]string{"-C", dir}, args...)...)
+	cmd.Env = append(os.Environ(), "GIT_TERMINAL_PROMPT=0")
+	if out, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("git %s: %v\n%s", strings.Join(args, " "), err, out)
+	}
+}