devrites 3.0.7 → 3.2.0

package/engine/internal/rootfacts/facts_test.go

@@ -0,0 +1,306 @@
+package rootfacts
+
+import (
+	"errors"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestResolveNormalCheckoutAndOrdinaryAbsence(t *testing.T) {
+	repo := initRepository(t, filepath.Join(t.TempDir(), "repo"))
+	root := filepath.Join(repo, ".devrites")
+	if err := os.MkdirAll(root, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	facts, err := ResolveFrom(filepath.Join(repo, "nested"), "")
+	if err == nil {
+		t.Fatal("missing nested directory should fail before root resolution")
+	}
+	if err := os.MkdirAll(filepath.Join(repo, "nested"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	facts, err = ResolveFrom(filepath.Join(repo, "nested"), "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantRoot, _ := physical(root)
+	if facts.PhysicalRoot != wantRoot || facts.SelectionReason != "git-ancestor" {
+		t.Fatalf("facts = %+v, want root %q selected by Git-bounded search", facts, wantRoot)
+	}
+	if facts.Git.TopLevel == "" || facts.Git.Dir == "" || facts.Git.CommonDir == "" {
+		t.Fatalf("missing Git identities: %+v", facts.Git)
+	}
+
+	if err := os.RemoveAll(root); err != nil {
+		t.Fatal(err)
+	}
+	facts, err = ResolveFrom(repo, "")
+	if !errors.Is(err, ErrNoRoot) || hazard(facts, "DRV-ROOT-NOT-FOUND") == nil || facts.Refuses() {
+		t.Fatalf("ordinary absence facts=%+v err=%v", facts, err)
+	}
+
+	t.Setenv("DEVRITES_WORKSPACE", filepath.Join(t.TempDir(), "outside"))
+	facts, err = ResolveFrom(repo, "")
+	if !errors.Is(err, ErrUnsafeRoot) || hazard(facts, "DRV-WORKSPACE-WITHOUT-ROOT") == nil || !facts.Refuses() {
+		t.Fatalf("workspace without root facts=%+v err=%v", facts, err)
+	}
+}
+
+func TestResolveStopsAtNestedRepositoryAndMultiRepoBoundaries(t *testing.T) {
+	parent := t.TempDir()
+	outer := initRepository(t, filepath.Join(parent, "outer"))
+	if err := os.MkdirAll(filepath.Join(outer, ".devrites"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	child := initRepository(t, filepath.Join(outer, "services", "child"))
+
+	facts, err := ResolveFrom(child, "")
+	if !errors.Is(err, ErrUnsafeRoot) {
+		t.Fatalf("nested repo error = %v, want unsafe root", err)
+	}
+	h := hazard(facts, "DRV-ROOT-OUTSIDE-GIT")
+	if h == nil || !h.Refuse || h.Remediation == "" {
+		t.Fatalf("nested repo hazard = %+v", h)
+	}
+	if facts.PhysicalRoot != "" {
+		t.Fatalf("nested repository inherited parent root %q", facts.PhysicalRoot)
+	}
+
+	multi := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(multi, ".devrites"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	a := initRepository(t, filepath.Join(multi, "a"))
+	_ = initRepository(t, filepath.Join(multi, "b"))
+	facts, err = ResolveFrom(a, "")
+	if !errors.Is(err, ErrUnsafeRoot) || hazard(facts, "DRV-ROOT-OUTSIDE-GIT") == nil {
+		t.Fatalf("multi-repository parent facts=%+v err=%v", facts, err)
+	}
+}
+
+func TestResolveKeepsRepositoryBoundaryWhenGitProbeIsUnavailable(t *testing.T) {
+	outer := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(outer, ".devrites"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	repo := filepath.Join(outer, "repo")
+	if err := os.MkdirAll(filepath.Join(repo, ".git"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("PATH", "")
+
+	facts, err := ResolveFrom(repo, "")
+	if !errors.Is(err, ErrUnsafeRoot) {
+		t.Fatalf("Git-unavailable error = %v, want bounded refusal", err)
+	}
+	if hazard(facts, "DRV-GIT-FACTS-UNAVAILABLE") == nil || hazard(facts, "DRV-ROOT-OUTSIDE-GIT") == nil {
+		t.Fatalf("Git-unavailable facts lost boundary diagnostics: %+v", facts)
+	}
+}
+
+func TestResolveLinkedWorktreeUsesPerWorktreeRootAndCommonDir(t *testing.T) {
+	base := t.TempDir()
+	main := initRepository(t, filepath.Join(base, "main"))
+	worktree := filepath.Join(base, "linked")
+	runGit(t, main, "worktree", "add", "-q", "-b", "linked-test", worktree)
+	root := filepath.Join(worktree, ".devrites")
+	if err := os.MkdirAll(root, 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	facts, err := ResolveFrom(worktree, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !facts.Git.LinkedWorktree || facts.Git.Dir == facts.Git.CommonDir {
+		t.Fatalf("linked worktree identities = %+v", facts.Git)
+	}
+	want, _ := physical(root)
+	if facts.PhysicalRoot != want {
+		t.Fatalf("root = %q, want per-worktree %q", facts.PhysicalRoot, want)
+	}
+}
+
+func TestResolveSubmoduleNeverInheritsSuperprojectState(t *testing.T) {
+	base := t.TempDir()
+	origin := initRepository(t, filepath.Join(base, "origin"))
+	super := initRepository(t, filepath.Join(base, "super"))
+	runGit(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(super, ".devrites"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	facts, err := ResolveFrom(sub, "")
+	if !errors.Is(err, ErrUnsafeRoot) || !facts.Git.Submodule || facts.Git.Superproject == "" {
+		t.Fatalf("submodule without root facts=%+v err=%v", facts, err)
+	}
+	if facts.PhysicalRoot != "" || hazard(facts, "DRV-ROOT-OUTSIDE-GIT") == nil {
+		t.Fatalf("submodule inherited superproject state: %+v", facts)
+	}
+
+	subRoot := filepath.Join(sub, ".devrites")
+	if err := os.MkdirAll(subRoot, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	facts, err = ResolveFrom(sub, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	want, _ := physical(subRoot)
+	if facts.PhysicalRoot != want || !facts.Git.Submodule {
+		t.Fatalf("submodule local facts=%+v, want root %q", facts, want)
+	}
+
+	superFacts, err := ResolveFrom(super, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if superFacts.Git.Submodule || superFacts.Git.Superproject != "" {
+		t.Fatalf("superproject mislabeled as submodule: %+v", superFacts.Git)
+	}
+}
+
+func TestResolveCanonicalizesExplicitSymlinkAndRejectsRootEscape(t *testing.T) {
+	base := t.TempDir()
+	real := initRepository(t, filepath.Join(base, "real"))
+	if err := os.MkdirAll(filepath.Join(real, ".devrites"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	link := filepath.Join(base, "project-link")
+	if err := os.Symlink(real, link); err != nil {
+		t.Skipf("symlinks unavailable: %v", err)
+	}
+	facts, err := ResolveFrom(base, link)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want, _ := physical(filepath.Join(real, ".devrites"))
+	if facts.LexicalRoot != filepath.Join(link, ".devrites") || facts.PhysicalRoot != want {
+		t.Fatalf("symlink facts=%+v, want lexical link and physical root %q", facts, want)
+	}
+
+	escapedProject := filepath.Join(base, "escaped-project")
+	if err := os.MkdirAll(escapedProject, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	outside := filepath.Join(base, "outside-root")
+	if err := os.MkdirAll(outside, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink(outside, filepath.Join(escapedProject, ".devrites")); err != nil {
+		t.Fatal(err)
+	}
+	facts, err = ResolveFrom(base, escapedProject)
+	if !errors.Is(err, ErrUnsafeRoot) || hazard(facts, "DRV-ROOT-SYMLINK-ESCAPE") == nil {
+		t.Fatalf("root symlink escape facts=%+v err=%v", facts, err)
+	}
+}
+
+func TestResolveRejectsWorkspaceAndActiveSymlinkState(t *testing.T) {
+	project := filepath.Join(t.TempDir(), "project")
+	root := filepath.Join(project, ".devrites")
+	outside := filepath.Join(t.TempDir(), "outside")
+	if err := os.MkdirAll(filepath.Join(root, "work"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(outside, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	workspaceLink := filepath.Join(root, "work", "escaped")
+	if err := os.Symlink(outside, workspaceLink); err != nil {
+		t.Skipf("symlinks unavailable: %v", err)
+	}
+	facts, err := ResolveFrom(project, project)
+	if !errors.Is(err, ErrUnsafeRoot) || hazard(facts, "DRV-WORKSPACE-SYMLINK-ESCAPE") == nil {
+		t.Fatalf("workspace symlink facts=%+v err=%v", facts, err)
+	}
+
+	if err := os.Remove(workspaceLink); err != nil {
+		t.Fatal(err)
+	}
+	activeTarget := filepath.Join(outside, "ACTIVE")
+	if err := os.WriteFile(activeTarget, []byte("ghost\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink(activeTarget, filepath.Join(root, "ACTIVE")); err != nil {
+		t.Fatal(err)
+	}
+	facts, err = ResolveFrom(project, project)
+	if !errors.Is(err, ErrUnsafeRoot) || hazard(facts, "DRV-ACTIVE-SYMLINK") == nil {
+		t.Fatalf("ACTIVE symlink facts=%+v err=%v", facts, err)
+	}
+}
+
+func TestResolveReportsStaleActiveAndExternalWorkspace(t *testing.T) {
+	project := initRepository(t, filepath.Join(t.TempDir(), "repo"))
+	root := filepath.Join(project, ".devrites")
+	if err := os.MkdirAll(root, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, "ACTIVE"), []byte("ghost\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	facts, err := ResolveFrom(project, project)
+	if err != nil {
+		t.Fatal(err)
+	}
+	h := hazard(facts, "DRV-ACTIVE-STALE")
+	if h == nil || !strings.Contains(h.Remediation, "rm -f") {
+		t.Fatalf("stale ACTIVE hazard = %+v", h)
+	}
+
+	t.Setenv("DEVRITES_WORKSPACE", filepath.Join(t.TempDir(), "ghost"))
+	facts, err = ResolveFrom(project, project)
+	if !errors.Is(err, ErrUnsafeRoot) {
+		t.Fatalf("external workspace error = %v, want unsafe root", err)
+	}
+	h = hazard(facts, "DRV-WORKSPACE-OUTSIDE-ROOT")
+	if h == nil || h.Remediation != "unset DEVRITES_WORKSPACE" || !h.Refuse {
+		t.Fatalf("external workspace hazard = %+v", h)
+	}
+
+	facts, err = ResolveFrom(project, "")
+	if !errors.Is(err, ErrUnsafeRoot) || hazard(facts, "DRV-WORKSPACE-OUTSIDE-ROOT") == nil {
+		t.Fatalf("implicit external workspace facts=%+v err=%v", facts, err)
+	}
+}
+
+func hazard(facts Facts, id string) *Hazard {
+	for i := range facts.Hazards {
+		if facts.Hazards[i].ID == id {
+			return &facts.Hazards[i]
+		}
+	}
+	return nil
+}
+
+func initRepository(t *testing.T, path string) string {
+	t.Helper()
+	if err := os.MkdirAll(path, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	runGit(t, path, "init", "-q")
+	runGit(t, path, "config", "user.email", "devrites@example.invalid")
+	runGit(t, path, "config", "user.name", "DevRites Test")
+	if err := os.WriteFile(filepath.Join(path, ".fixture"), []byte("fixture\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	runGit(t, path, "add", ".fixture")
+	runGit(t, path, "commit", "-q", "-m", "fixture")
+	return path
+}
+
+func runGit(t *testing.T, dir string, args ...string) string {
+	t.Helper()
+	cmd := exec.Command("git", append([]string{"-C", dir}, args...)...)
+	cmd.Env = append(os.Environ(), "GIT_TERMINAL_PROMPT=0")
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("git %s: %v\n%s", strings.Join(args, " "), err, out)
+	}
+	return strings.TrimSpace(string(out))
+}

package/engine/internal/safepath/safepath.go

@@ -0,0 +1,55 @@
+package safepath
+
+import (
+	"os"
+	"path/filepath"
+)
+
+// WithinResolved reports whether candidate remains within parent after resolving
+// symlinks in every existing path prefix. It also handles not-yet-created files.
+func WithinResolved(candidate, parent string) bool {
+	if candidateInfo, err := os.Stat(candidate); err == nil {
+		if parentInfo, err := os.Stat(parent); err == nil && os.SameFile(candidateInfo, parentInfo) {
+			return true
+		}
+	}
+	resolvedCandidate, err := ResolveExisting(candidate)
+	if err != nil {
+		return false
+	}
+	resolvedParent, err := ResolveExisting(parent)
+	if err != nil {
+		return false
+	}
+	rel, err := filepath.Rel(resolvedParent, resolvedCandidate)
+	return err == nil && rel != ".." &&
+		!filepath.IsAbs(rel) && !hasParentPrefix(rel)
+}
+
+// ResolveExisting resolves symlinks in the longest existing path prefix, then
+// appends any missing tail without allowing it to change the resolved parent.
+func ResolveExisting(filename string) (string, error) {
+	var tail []string
+	for {
+		resolved, err := filepath.EvalSymlinks(filename)
+		if err == nil {
+			for i := len(tail) - 1; i >= 0; i-- {
+				resolved = filepath.Join(resolved, tail[i])
+			}
+			return filepath.Clean(resolved), nil
+		}
+		if !os.IsNotExist(err) {
+			return "", err
+		}
+		parent := filepath.Dir(filename)
+		if parent == filename {
+			return "", err
+		}
+		tail = append(tail, filepath.Base(filename))
+		filename = parent
+	}
+}
+
+func hasParentPrefix(rel string) bool {
+	return rel == ".." || len(rel) > 3 && rel[:3] == ".."+string(filepath.Separator)
+}

package/engine/internal/safepath/safepath_test.go

@@ -0,0 +1,69 @@
+package safepath
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+func TestWithinResolvedHandlesExistingSymlinksAndMissingTails(t *testing.T) {
+	base := t.TempDir()
+	parent := filepath.Join(base, "real")
+	outside := filepath.Join(base, "outside")
+	if err := os.MkdirAll(parent, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(outside, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	link := filepath.Join(base, "link")
+	if err := os.Symlink(parent, link); err != nil {
+		t.Skipf("symlinks unavailable: %v", err)
+	}
+	escape := filepath.Join(parent, "escape")
+	if err := os.Symlink(outside, escape); err != nil {
+		t.Fatal(err)
+	}
+
+	cases := []struct {
+		name      string
+		candidate string
+		parent    string
+		want      bool
+	}{
+		{"same path", parent, parent, true},
+		{"symlinked existing prefix", filepath.Join(link, "new", "file"), parent, true},
+		{"missing parent tail", filepath.Join(parent, "new", "file"), filepath.Join(parent, "new"), true},
+		{"symlink escape", filepath.Join(escape, "file"), parent, false},
+		{"lexical escape", filepath.Join(parent, "..", "outside"), parent, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := WithinResolved(tc.candidate, tc.parent); got != tc.want {
+				t.Fatalf("WithinResolved(%q, %q) = %v, want %v", tc.candidate, tc.parent, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestWithinResolvedDoesNotInventCaseFolding(t *testing.T) {
+	parent := filepath.Join(t.TempDir(), "CaseSensitiveName")
+	if err := os.MkdirAll(parent, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	wrongCase := filepath.Join(filepath.Dir(parent), strings.ToLower(filepath.Base(parent)))
+	_, err := os.Stat(wrongCase)
+	if err == nil {
+		// The host filesystem treats the paths as the same. Native filepath
+		// semantics are the authority on that host.
+		if !WithinResolved(wrongCase, parent) {
+			t.Fatalf("%s considers paths equivalent but containment disagrees", runtime.GOOS)
+		}
+		return
+	}
+	if WithinResolved(wrongCase, parent) {
+		t.Fatalf("%s filesystem is case-sensitive; containment folded case", runtime.GOOS)
+	}
+}

package/engine/internal/safepath/safepath_windows_test.go

@@ -0,0 +1,26 @@
+//go:build windows
+
+package safepath
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+func TestWindowsNativeVolumeAndSeparatorContainment(t *testing.T) {
+	parent := t.TempDir()
+	if !WithinResolved(filepath.Join(parent, "child", "file"), parent) {
+		t.Fatal("native Windows child path should remain contained")
+	}
+	volume := filepath.VolumeName(parent)
+	if volume == "" {
+		t.Fatalf("temporary path %q has no Windows volume", parent)
+	}
+	other := `Z:\outside`
+	if filepath.VolumeName(parent) == "Z:" {
+		other = `Y:\outside`
+	}
+	if WithinResolved(other, parent) {
+		t.Fatalf("different Windows volumes reported contained: %q in %q", other, parent)
+	}
+}

package/engine/internal/state/clarify_transition.go

@@ -0,0 +1,165 @@
+package state
+
+import (
+	"fmt"
+	"strings"
+)
+
+// ClarifyIntent is the only transition family piloted through a pure next-state
+// function. Other lifecycle mutations intentionally remain unchanged.
+type ClarifyIntent string
+
+const (
+	ClarifyEnter   ClarifyIntent = "enter"
+	ClarifyRestore ClarifyIntent = "restore"
+)
+
+// ClarifyCursor is the complete cursor surface owned by clarify-return.
+type ClarifyCursor struct {
+	Phase            Phase
+	Status           string
+	NextAction       string
+	ReturnPhase      Phase
+	ReturnNextAction string
+	HasReturn        bool
+}
+
+// ClarifyTransitionInput carries the current typed cursor plus host-rendered
+// defaults. NextClarifyCursor is pure: it does no file or environment I/O.
+type ClarifyTransitionInput struct {
+	Cursor                  ClarifyCursor
+	ClarifyNextAction       string
+	DefaultReturnNextAction string
+}
+
+// ClarifyFieldPolicy is emitted in the workflow manifest for documentation.
+type ClarifyFieldPolicy struct {
+	Field  string `json:"field"`
+	Policy string `json:"policy"`
+}
+
+// ClarifyFieldPolicies declares which fields the pilot derives and preserves.
+func ClarifyFieldPolicies() []ClarifyFieldPolicy {
+	return []ClarifyFieldPolicy{
+		{Field: CursorPhase, Policy: "derived"},
+		{Field: CursorStatus, Policy: "derived"},
+		{Field: CursorNextAction, Policy: "derived"},
+		{Field: CursorReturnPhase, Policy: "derived"},
+		{Field: CursorReturnNextAction, Policy: "curated when present; otherwise derived"},
+		{Field: "all other state.md content", Policy: "curated and preserved byte-for-byte"},
+	}
+}
+
+// ClarifyTransitionError reports an illegal typed transition.
+type ClarifyTransitionError struct {
+	Intent ClarifyIntent
+	Reason string
+}
+
+func (e *ClarifyTransitionError) Error() string {
+	return fmt.Sprintf("clarify %s: %s", e.Intent, e.Reason)
+}
+
+// NextClarifyCursor returns the full next clarify-owned cursor surface.
+func NextClarifyCursor(intent ClarifyIntent, input ClarifyTransitionInput) (ClarifyCursor, error) {
+	current := input.Cursor
+	switch intent {
+	case ClarifyEnter:
+		if current.Phase == PhaseClarify {
+			return current, nil
+		}
+		if !PhaseAfterClarify(current.Phase) {
+			return ClarifyCursor{}, &ClarifyTransitionError{Intent: intent, Reason: fmt.Sprintf("phase %q is not a later-phase retrofit", current.Phase)}
+		}
+		returnNext := strings.TrimSpace(current.NextAction)
+		if returnNext == "" {
+			returnNext = input.DefaultReturnNextAction
+		}
+		return ClarifyCursor{
+			Phase:            PhaseClarify,
+			Status:           "running",
+			NextAction:       input.ClarifyNextAction,
+			ReturnPhase:      current.Phase,
+			ReturnNextAction: returnNext,
+			HasReturn:        true,
+		}, nil
+	case ClarifyRestore:
+		if !current.HasReturn {
+			return current, nil
+		}
+		if !PhaseAfterClarify(current.ReturnPhase) {
+			return ClarifyCursor{}, &ClarifyTransitionError{Intent: intent, Reason: fmt.Sprintf("invalid return phase %q", current.ReturnPhase)}
+		}
+		next := strings.TrimSpace(current.ReturnNextAction)
+		if next == "" {
+			next = input.DefaultReturnNextAction
+		}
+		return ClarifyCursor{
+			Phase:      current.ReturnPhase,
+			Status:     "running",
+			NextAction: next,
+		}, nil
+	default:
+		return ClarifyCursor{}, &ClarifyTransitionError{Intent: intent, Reason: "unknown intent"}
+	}
+}
+
+// ParseClarifyCursor reads the clarify-owned fields from either cursor format.
+func ParseClarifyCursor(lines []string) (ClarifyCursor, error) {
+	rawPhase, ok := CursorField(lines, CursorPhase)
+	if !ok || strings.TrimSpace(rawPhase) == "" {
+		return ClarifyCursor{}, fmt.Errorf("state.md has no phase")
+	}
+	phase, ok := firstKnownPhase(rawPhase)
+	if !ok {
+		return ClarifyCursor{}, fmt.Errorf("unknown phase %q", rawPhase)
+	}
+	current := ClarifyCursor{Phase: phase}
+	current.Status, _ = CursorField(lines, CursorStatus)
+	current.NextAction, _ = CursorField(lines, CursorNextAction)
+	rawReturn, hasReturn := CursorField(lines, CursorReturnPhase)
+	if hasReturn && strings.TrimSpace(rawReturn) != "" {
+		returnPhase, ok := firstKnownPhase(rawReturn)
+		if !ok {
+			return ClarifyCursor{}, fmt.Errorf("invalid return phase %q", rawReturn)
+		}
+		current.ReturnPhase = returnPhase
+		current.HasReturn = true
+	}
+	current.ReturnNextAction, _ = CursorField(lines, CursorReturnNextAction)
+	return current, nil
+}
+
+func firstKnownPhase(raw string) (Phase, bool) {
+	fields := strings.Fields(strings.ToLower(strings.TrimSpace(raw)))
+	if len(fields) == 0 {
+		return "", false
+	}
+	return PhaseForName(fields[0])
+}
+
+// ApplyClarifyCursor serializes only clarify-owned fields and preserves all
+// unrelated Markdown through the existing presentation-preserving mutators.
+func ApplyClarifyCursor(lines []string, cursor ClarifyCursor) []string {
+	lines = UpsertCursorField(lines, CursorPhase, string(cursor.Phase))
+	lines = UpsertCursorField(lines, CursorStatus, cursor.Status)
+	lines = UpsertCursorField(lines, CursorNextAction, cursor.NextAction)
+	if cursor.HasReturn {
+		lines = UpsertCursorField(lines, CursorReturnPhase, string(cursor.ReturnPhase))
+		lines = UpsertCursorField(lines, CursorReturnNextAction, cursor.ReturnNextAction)
+		return lines
+	}
+	lines = DeleteCursorField(lines, CursorReturnPhase)
+	return DeleteCursorField(lines, CursorReturnNextAction)
+}
+
+// PhaseAfterClarify reports whether clarify-return may retrofit this phase.
+func PhaseAfterClarify(phase Phase) bool {
+	switch phase {
+	case PhaseTemper, PhaseDefine, PhasePlan, PhaseVet, PhaseBuild, PhaseConverge,
+		PhaseProve, PhasePolish, PhaseReview, PhaseSeal, PhaseShip:
+		return true
+	default:
+		return false
+	}
+}