devrites 2.6.1 → 3.0.0

package/engine/internal/state/snapshot.go

@@ -0,0 +1,384 @@
+package state
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/fsutil"
+	"github.com/devrites/devrites/internal/workflow"
+)
+
+const WorkspaceSnapshotSchema = "devrites.workspace.v1"
+
+var (
+	snapshotSliceCheckRe   = regexp.MustCompile(`^- \[[^\]]*\][[:space:]]*`)
+	snapshotSliceNameRe    = regexp.MustCompile(`^Slice[[:space:]]*[0-9]+:[[:space:]]*`)
+	snapshotSliceStateRe   = regexp.MustCompile(`[[:space:]]+(built|pending)[[:space:]]*$`)
+	snapshotSliceSepRe     = regexp.MustCompile(`[[:space:]]+[^[:alnum:][:space:]]+[[:space:]]*$`)
+	snapshotSliceCheckedRe = regexp.MustCompile(`\[[xX]\]`)
+	snapshotTouchedPathRe  = regexp.MustCompile("`([^`]+)`")
+)
+
+// WorkspaceSnapshot is the machine-readable DevRites workspace/status contract.
+// It models DevRites' native unit of work — a feature workspace at a phase with
+// section completeness — rather than a generic harness session/worker shape.
+type WorkspaceSnapshot struct {
+	SchemaVersion   string               `json:"schemaVersion"`
+	Slug            string               `json:"slug"`
+	Phase           string               `json:"phase"`
+	RunMode         string               `json:"runMode"`
+	Complete        bool                 `json:"complete"`
+	Sections        []SectionSnapshot    `json:"sections"`
+	MissingSections []string             `json:"missingSections,omitempty"`
+	CurrentSlice    *SliceSnapshot       `json:"currentSlice,omitempty"`
+	Evidence        EvidenceSnapshot     `json:"evidence"`
+	Drift           DriftSnapshot        `json:"drift"`
+	Review          ReviewSnapshot       `json:"review"`
+	Harness         HarnessSnapshot      `json:"harness"`
+	Extensions      ExtensionSnapshot    `json:"extensions"`
+	DirtyWorkspace  DirtyWorkspace       `json:"dirtyWorkspace"`
+	Capabilities    []CapabilitySnapshot `json:"capabilities"`
+	NextCommand     string               `json:"nextCommand,omitempty"` // legacy: Claude Code form; prefer nextCommands.
+	NextCommands    CommandSnapshot      `json:"nextCommands"`
+	Warnings        []string             `json:"warnings,omitempty"`
+}
+
+type CommandSnapshot struct {
+	Verb   string `json:"verb,omitempty"`
+	Claude string `json:"claude,omitempty"`
+	Codex  string `json:"codex,omitempty"`
+}
+
+type SectionSnapshot struct {
+	Name     string `json:"name"`
+	Present  bool   `json:"present"`
+	Required bool   `json:"required"`
+}
+
+type SliceSnapshot struct {
+	Index int    `json:"index"`
+	Total int    `json:"total"`
+	Name  string `json:"name,omitempty"`
+	State string `json:"state"`
+}
+
+type EvidenceSnapshot struct {
+	Status string `json:"status"`
+	Detail string `json:"detail,omitempty"`
+}
+
+type DriftSnapshot struct {
+	Status string `json:"status"`
+	Open   int    `json:"open,omitempty"`
+}
+
+type ReviewSnapshot struct {
+	Status string `json:"status"`
+	Detail string `json:"detail,omitempty"`
+}
+
+type HarnessSnapshot struct {
+	Status string `json:"status"`
+	Detail string `json:"detail,omitempty"`
+}
+
+type ExtensionSnapshot struct {
+	Status string `json:"status"`
+	Count  int    `json:"count"`
+}
+
+type DirtyWorkspace struct {
+	Status  string   `json:"status"`
+	Changed int      `json:"changed"`
+	Sample  []string `json:"sample,omitempty"`
+}
+
+type CapabilitySnapshot struct {
+	Name     string `json:"name"`
+	Status   string `json:"status"`
+	UsedBy   string `json:"usedBy"`
+	Fallback string `json:"fallback"`
+	Risk     string `json:"risk"`
+}
+
+// Snapshot computes the stable JSON-facing status snapshot for slug. Empty slug
+// falls back to .devrites/ACTIVE so future status surfaces can inspect the live
+// workspace without chat context.
+func Snapshot(root, slug string) (*WorkspaceSnapshot, error) {
+	if strings.TrimSpace(slug) == "" {
+		slug = readActiveSlug(root)
+	}
+	report, err := Status(root, slug)
+	if err != nil {
+		return nil, fmt.Errorf("snapshot workspace: %w", err)
+	}
+
+	workDir := featureDir(root, report.Slug)
+	next := workflow.ForPhase(string(report.Phase))
+	snap := &WorkspaceSnapshot{
+		SchemaVersion:  WorkspaceSnapshotSchema,
+		Slug:           report.Slug,
+		Phase:          string(report.Phase),
+		RunMode:        runMode(root),
+		Complete:       report.Complete(),
+		CurrentSlice:   currentSlice(workDir),
+		Evidence:       evidenceSummary(root, workDir),
+		Drift:          driftSummary(workDir),
+		Review:         reviewSummary(workDir),
+		Harness:        harnessSummary(filepath.Dir(root)),
+		Extensions:     extensionSummary(root),
+		DirtyWorkspace: dirtyWorkspace(filepath.Dir(root)),
+		Capabilities:   capabilityInventory(filepath.Dir(root)),
+		NextCommand:    next.Claude,
+		NextCommands:   CommandSnapshot{Verb: next.Verb, Claude: next.Claude, Codex: next.Codex},
+	}
+	for _, section := range Sections {
+		snap.Sections = append(snap.Sections, SectionSnapshot{
+			Name:     string(section),
+			Present:  report.Present[section],
+			Required: report.Required[section],
+		})
+	}
+	for _, section := range report.Missing {
+		snap.MissingSections = append(snap.MissingSections, string(section))
+	}
+	if snap.RunMode == "AFK" && len(snap.MissingSections) > 0 {
+		snap.Warnings = append(snap.Warnings, "AFK workspace has missing required sections")
+	}
+	if snap.Evidence.Status == "missing" && (report.Phase == PhaseProve || report.Phase == PhaseSeal || report.Phase == PhaseShip) {
+		snap.Warnings = append(snap.Warnings, "proof phase requires fresh evidence")
+	}
+	if snap.Drift.Open > 0 {
+		snap.Warnings = append(snap.Warnings, fmt.Sprintf("%d open drift item(s)", snap.Drift.Open))
+	}
+	return snap, nil
+}
+
+func readActiveSlug(root string) string {
+	if ws := devritespaths.WorkspaceOverride(root, ""); ws != "" {
+		return filepath.Base(ws)
+	}
+	raw, err := os.ReadFile(filepath.Join(root, "ACTIVE"))
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(raw))
+}
+
+func runMode(root string) string {
+	if info, err := os.Stat(filepath.Join(root, "AFK")); err == nil && !info.IsDir() {
+		return "AFK"
+	}
+	return "HITL"
+}
+
+func currentSlice(workDir string) *SliceSnapshot {
+	for _, name := range []string{"state.md", "tasks.md"} {
+		raw, err := os.ReadFile(filepath.Join(workDir, name))
+		if err != nil {
+			continue
+		}
+		slices := parseSliceLines(string(raw))
+		if len(slices) == 0 {
+			continue
+		}
+		for i, s := range slices {
+			if s.State != "built" {
+				s.Index, s.Total = i+1, len(slices)
+				return &s
+			}
+		}
+		last := slices[len(slices)-1]
+		last.Index, last.Total = len(slices), len(slices)
+		return &last
+	}
+	return nil
+}
+
+func parseSliceLines(text string) []SliceSnapshot {
+	var out []SliceSnapshot
+	for _, line := range strings.Split(text, "\n") {
+		trimmed := strings.TrimSpace(line)
+		if !strings.HasPrefix(trimmed, "- [") {
+			continue
+		}
+		name := snapshotSliceCheckRe.ReplaceAllString(trimmed, "")
+		name = snapshotSliceNameRe.ReplaceAllString(name, "")
+		name = snapshotSliceStateRe.ReplaceAllString(name, "")
+		name = snapshotSliceSepRe.ReplaceAllString(name, "")
+		state := "pending"
+		if snapshotSliceCheckedRe.MatchString(trimmed) {
+			state = "built"
+		}
+		out = append(out, SliceSnapshot{Name: strings.TrimSpace(name), State: state})
+	}
+	return out
+}
+
+func evidenceSummary(root, workDir string) EvidenceSnapshot {
+	newestProof, haveProof := fsutil.NewestModTime(
+		filepath.Join(workDir, "evidence.md"),
+		filepath.Join(workDir, "proof.md"),
+		filepath.Join(workDir, "browser-evidence.md"),
+	)
+	if !haveProof {
+		return EvidenceSnapshot{Status: "missing", Detail: "no evidence.md / proof.md / browser-evidence.md"}
+	}
+	touched, err := os.ReadFile(filepath.Join(workDir, "touched-files.md"))
+	if err != nil {
+		return EvidenceSnapshot{Status: "fresh", Detail: "no touched-files.md; nothing to compare"}
+	}
+	var newestCode int64
+	var newestPath string
+	for _, match := range snapshotTouchedPathRe.FindAllStringSubmatch(string(touched), -1) {
+		listed := match[1]
+		path := listed
+		if !filepath.IsAbs(path) {
+			path = filepath.Join(filepath.Dir(root), path)
+		}
+		if m, ok := fsutil.FileModTime(path); ok && m > newestCode {
+			newestCode, newestPath = m, listed
+		}
+	}
+	if newestCode > newestProof {
+		return EvidenceSnapshot{Status: "stale", Detail: newestPath + " is newer than proof"}
+	}
+	return EvidenceSnapshot{Status: "fresh", Detail: "proof post-dates touched files"}
+}
+
+func driftSummary(workDir string) DriftSnapshot {
+	for _, name := range []string{"drift.md", "questions.md"} {
+		raw, err := os.ReadFile(filepath.Join(workDir, name))
+		if err != nil {
+			continue
+		}
+		open := countOpenMarkers(string(raw))
+		if open > 0 {
+			return DriftSnapshot{Status: "open", Open: open}
+		}
+	}
+	return DriftSnapshot{Status: "clear"}
+}
+
+func countOpenMarkers(text string) int {
+	open := 0
+	for _, line := range strings.Split(text, "\n") {
+		l := strings.ToLower(strings.TrimSpace(line))
+		if strings.Contains(l, "status: open") || strings.Contains(l, "- [ ]") || strings.Contains(l, "gate: blocking") {
+			open++
+		}
+	}
+	return open
+}
+
+func reviewSummary(workDir string) ReviewSnapshot {
+	for _, name := range []string{"review.md", "eng-review.md"} {
+		raw, err := os.ReadFile(filepath.Join(workDir, name))
+		if err != nil {
+			continue
+		}
+		text := string(raw)
+		if strings.Contains(text, "**Critical**") || strings.Contains(text, "**Important**") {
+			return ReviewSnapshot{Status: "findings", Detail: name}
+		}
+		if strings.Contains(strings.ToLower(text), "no-findings") {
+			return ReviewSnapshot{Status: "clean", Detail: name}
+		}
+		return ReviewSnapshot{Status: "present", Detail: name}
+	}
+	return ReviewSnapshot{Status: "missing"}
+}
+
+func harnessSummary(projectDir string) HarnessSnapshot {
+	claude := regularFileExists(filepath.Join(projectDir, ".claude", "settings.json"))
+	codex := regularFileExists(filepath.Join(projectDir, ".codex", "hooks.json")) || regularFileExists(filepath.Join(projectDir, "AGENTS.md"))
+	switch {
+	case claude && codex:
+		return HarnessSnapshot{Status: "project-local", Detail: "Claude and Codex artifacts present"}
+	case claude:
+		return HarnessSnapshot{Status: "project-local", Detail: "Claude artifacts present"}
+	case codex:
+		return HarnessSnapshot{Status: "project-local", Detail: "Codex artifacts present"}
+	default:
+		return HarnessSnapshot{Status: "missing", Detail: "no project-local host artifacts detected"}
+	}
+}
+
+func extensionSummary(root string) ExtensionSnapshot {
+	entries, err := os.ReadDir(filepath.Join(root, "extensions"))
+	if err != nil {
+		return ExtensionSnapshot{Status: "none", Count: 0}
+	}
+	count := 0
+	for _, entry := range entries {
+		if entry.IsDir() && !strings.HasPrefix(entry.Name(), ".") {
+			count++
+		}
+	}
+	if count == 0 {
+		return ExtensionSnapshot{Status: "none", Count: 0}
+	}
+	return ExtensionSnapshot{Status: "present", Count: count}
+}
+
+func dirtyWorkspace(projectDir string) DirtyWorkspace {
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+	cmd := exec.CommandContext(ctx, "git", "status", "--porcelain")
+	cmd.Dir = projectDir
+	out, err := cmd.Output()
+	if err != nil {
+		return DirtyWorkspace{Status: "unknown"}
+	}
+	var sample []string
+	changed := 0
+	for _, line := range strings.Split(strings.TrimSpace(string(out)), "\n") {
+		if strings.TrimSpace(line) == "" {
+			continue
+		}
+		changed++
+		if len(sample) < 5 {
+			sample = append(sample, strings.TrimSpace(line))
+		}
+	}
+	if changed == 0 {
+		return DirtyWorkspace{Status: "clean"}
+	}
+	return DirtyWorkspace{Status: "dirty", Changed: changed, Sample: sample}
+}
+
+func capabilityInventory(projectDir string) []CapabilitySnapshot {
+	return []CapabilitySnapshot{
+		capability("codegraph", "spec/define/plan", "file reads + search", "lower placement confidence"),
+		capability("graphify", "zoom-out/spec", "repo search", "stale topology or no graph context"),
+		capability("playwright", "prove/polish/browser-proof", "manual/browser proof ladder", "weaker browser evidence"),
+		capability("chrome-devtools", "performance/browser-proof", "Playwright or manual traces", "no Lighthouse/perf trace"),
+		mcpConfigCapability(projectDir),
+	}
+}
+
+func capability(binary, usedBy, fallback, risk string) CapabilitySnapshot {
+	status := "missing"
+	if _, err := exec.LookPath(binary); err == nil {
+		status = "available"
+	}
+	return CapabilitySnapshot{Name: binary, Status: status, UsedBy: usedBy, Fallback: fallback, Risk: risk}
+}
+
+func mcpConfigCapability(projectDir string) CapabilitySnapshot {
+	status := "missing"
+	for _, rel := range []string{".mcp.json", ".claude/mcp.json", ".codex/config.toml"} {
+		if regularFileExists(filepath.Join(projectDir, rel)) {
+			status = "configured"
+			break
+		}
+	}
+	return CapabilitySnapshot{Name: "mcp-config", Status: status, UsedBy: "optional external tools", Fallback: "engine/file-system gates", Risk: "optional capabilities unavailable"}
+}

package/engine/internal/state/state_test.go

@@ -0,0 +1,260 @@
+package state
+
+// Focused unit tests on the deterministic core: phase→required mapping,
+// present/empty detection, and status computation. These assert behavior
+// (observable results), not internal structure.
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+const fixtureRoot = "../../testdata/fixtures/basic/devrites-root"
+
+func TestRequiredSectionsIsPhaseRelativeAndOrdered(t *testing.T) {
+	got := RequiredSections(PhaseBuild)
+	want := []Section{SectionSpec, SectionPlan, SectionDecisions, SectionTasks}
+	if len(got) != len(want) {
+		t.Fatalf("RequiredSections(build) = %v, want %v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Errorf("index %d: got %q, want %q", i, got[i], want[i])
+		}
+	}
+	if len(RequiredSections(PhaseFrame)) != 0 {
+		t.Errorf("frame should require no sections, got %v", RequiredSections(PhaseFrame))
+	}
+}
+
+func TestStatusFixtureBuildIncomplete(t *testing.T) {
+	rep, err := Status(fixtureRoot, "auth-tokens")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if rep.Phase != PhaseBuild {
+		t.Errorf("phase = %q, want build", rep.Phase)
+	}
+	// tasks.md is a heading-only stub → empty → the one missing required section.
+	if len(rep.Missing) != 1 || rep.Missing[0] != SectionTasks {
+		t.Errorf("Missing = %v, want [tasks]", rep.Missing)
+	}
+	if rep.Complete() {
+		t.Error("Complete() = true, want false")
+	}
+	// proof is empty but not required at build, so it must not count as missing.
+	if rep.Required[SectionProof] {
+		t.Error("proof should not be required during the build phase")
+	}
+}
+
+func TestStatusFixtureSpecComplete(t *testing.T) {
+	rep, err := Status(fixtureRoot, "search-ranking")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !rep.Complete() {
+		t.Errorf("Complete() = false, want true (missing: %v)", rep.Missing)
+	}
+}
+
+func TestStatusUnknownSlugErrors(t *testing.T) {
+	if _, err := Status(fixtureRoot, "nope"); err == nil {
+		t.Fatal("Status on unknown slug returned nil error, want an error")
+	}
+}
+
+func writeSection(t *testing.T, root, slug, name, body string) {
+	t.Helper()
+	dir := filepath.Join(root, "features", slug)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, name), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func writeWorkSection(t *testing.T, root, slug, name, body string) {
+	t.Helper()
+	dir := filepath.Join(root, "work", slug)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, name), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// A live workspace the pack creates has no feature.md manifest: the phase lives in
+// the state.md ledger and the proof/status sections are satisfied by their aliases
+// (evidence.md / state.md). The engine must load, list, and report it anyway.
+func TestLoadFeatureFromLedgerAndAliases(t *testing.T) {
+	root := filepath.Join(t.TempDir(), ".devrites")
+	writeSection(t, root, "live", "state.md", "- Phase: prove\n- Status: running\n")
+	writeSection(t, root, "live", "spec.md", "# Spec\n\nDo the thing.\n")
+	writeSection(t, root, "live", "plan.md", "# Plan\n\nApproach.\n")
+	writeSection(t, root, "live", "decisions.md", "# Decisions\n\nChose X.\n")
+	writeSection(t, root, "live", "tasks.md", "# Tasks\n\n- [x] slice 1\n")
+	writeSection(t, root, "live", "evidence.md", "# Evidence\n\nTests pass.\n") // alias for proof
+
+	rep, err := Status(root, "live")
+	if err != nil {
+		t.Fatalf("Status on a manifest-less live workspace = %v, want nil", err)
+	}
+	if rep.Phase != PhaseProve {
+		t.Errorf("phase = %q, want prove (from the state.md ledger)", rep.Phase)
+	}
+	if !rep.Present[SectionProof] {
+		t.Error("proof section should be present via its evidence.md alias")
+	}
+	if !rep.Present[SectionStatus] {
+		t.Error("status section should be present via its state.md alias")
+	}
+	if !rep.Complete() {
+		t.Errorf("prove-phase feature should be complete, missing: %v", rep.Missing)
+	}
+
+	slugs, err := ListFeatures(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(slugs) != 1 || slugs[0] != "live" {
+		t.Errorf("ListFeatures = %v, want [live] (a ledger-only dir must list)", slugs)
+	}
+}
+
+func TestWorkLayoutIsCanonicalAndFeaturesIsAlias(t *testing.T) {
+	root := filepath.Join(t.TempDir(), ".devrites")
+	writeWorkSection(t, root, "live", "state.md", "- Phase: build\n")
+	writeWorkSection(t, root, "live", "spec.md", "# Spec\n\nDo the thing.\n")
+	writeSection(t, root, "alias", "state.md", "- Phase: spec\n")
+	writeSection(t, root, "alias", "spec.md", "# Spec\n\nAlias.\n")
+
+	for _, slug := range []string{"live", "alias"} {
+		if _, err := Status(root, slug); err != nil {
+			t.Fatalf("Status(%q) = %v, want nil", slug, err)
+		}
+	}
+
+	slugs, err := ListFeatures(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := strings.Join(slugs, ","); got != "alias,live" {
+		t.Fatalf("ListFeatures = %v, want [alias live]", slugs)
+	}
+}
+
+// An unknown phase word in the ledger is ignored (not accepted as a phase), so a
+// ledger-only feature with no recognizable phase is a clear error, not a silent
+// mis-load.
+func TestLedgerPhaseRejectsUnknownWord(t *testing.T) {
+	root := filepath.Join(t.TempDir(), ".devrites")
+	writeSection(t, root, "bogus", "state.md", "- Phase: banana\n")
+	if _, err := Status(root, "bogus"); err == nil {
+		t.Error("Status on a ledger with an unknown phase word = nil error, want an error")
+	}
+}
+
+func writeFeatureMD(t *testing.T, root, slug, featureMD string) {
+	t.Helper()
+	dir := filepath.Join(root, "features", slug)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "feature.md"), []byte(featureMD), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestLoadFeatureRejectsBadFrontmatter(t *testing.T) {
+	root := filepath.Join(t.TempDir(), ".devrites")
+	cases := map[string]string{
+		"no-phase":  "---\ntitle: x\n---\n\nbody\n",             // documented: missing phase is an error
+		"bad-phase": "---\nphase: banana\n---\n",                // documented: unknown phase is an error
+		"future":    "---\nphase: spec\nschemaVersion: 99\n---", // schemaVersion newer than the engine
+		"bad-ver":   "---\nphase: spec\nschemaVersion: x\n---",  // non-numeric schemaVersion
+	}
+	for slug, md := range cases {
+		writeFeatureMD(t, root, slug, md)
+	}
+	for slug := range cases {
+		if _, err := Status(root, slug); err == nil {
+			t.Errorf("Status(%q) = nil error, want an error", slug)
+		}
+	}
+}
+
+func TestLoadFeatureAcceptsSupportedSchemaVersion(t *testing.T) {
+	root := filepath.Join(t.TempDir(), ".devrites")
+	writeFeatureMD(t, root, "ok", "---\nphase: spec\nschemaVersion: 1\n---\n")
+	if _, err := Status(root, "ok"); err != nil {
+		t.Errorf("Status on schemaVersion 1 = %v, want nil", err)
+	}
+}
+
+func TestSectionPresentDistinguishesContentFromStubs(t *testing.T) {
+	dir := t.TempDir()
+	cases := []struct {
+		name string
+		body string
+		want bool
+	}{
+		{"missing", "", false}, // no file written for this case
+		{"empty", "", false},
+		{"heading-only stub", "# Tasks\n", false},
+		{"frontmatter-only", "---\nphase: build\n---\n", false},
+		{"real content", "# Spec\n\nDo the thing.\n", true},
+		{"content after frontmatter", "---\nk: v\n---\n\nreal words\n", true},
+	}
+	for i, c := range cases {
+		path := filepath.Join(dir, "s.md")
+		_ = os.Remove(path)
+		if c.name != "missing" {
+			if err := os.WriteFile(path, []byte(c.body), 0o644); err != nil {
+				t.Fatal(err)
+			}
+		}
+		if got := sectionPresent(path); got != c.want {
+			t.Errorf("case %d (%s): sectionPresent = %v, want %v", i, c.name, got, c.want)
+		}
+	}
+}
+
+func TestResolveRootAcceptsProjectRootOrDevritesRoot(t *testing.T) {
+	project := t.TempDir()
+	root := filepath.Join(project, ".devrites")
+	if err := os.MkdirAll(root, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	for _, in := range []string{project, root} {
+		got, err := ResolveRoot(in)
+		if err != nil {
+			t.Fatalf("ResolveRoot(%q): %v", in, err)
+		}
+		if got != root {
+			t.Fatalf("ResolveRoot(%q) = %q, want %q", in, got, root)
+		}
+	}
+}
+
+func TestDevritesWorkspaceOverridesActiveFeature(t *testing.T) {
+	root := filepath.Join(t.TempDir(), ".devrites")
+	writeWorkSection(t, root, "explicit", "state.md", "- Phase: spec\n")
+	writeWorkSection(t, root, "explicit", "spec.md", "# Spec\n\nBody\n")
+	if err := os.WriteFile(filepath.Join(root, "ACTIVE"), []byte("other\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("DEVRITES_WORKSPACE", filepath.Join(root, "work", "explicit"))
+
+	snap, err := Snapshot(root, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if snap.Slug != "explicit" {
+		t.Fatalf("Snapshot slug = %q, want explicit", snap.Slug)
+	}
+}