devrites 3.0.6 → 3.1.0

package/engine/internal/lib/clarifyreturn_test.go

@@ -0,0 +1,123 @@
+package lib
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/devrites/devrites/internal/state"
+)
+
+func TestClarifyReturnSurvivesResolveAndRestoresLaterPhase(t *testing.T) {
+	root := t.TempDir()
+	slug := "retrofit"
+	writeReadinessFile(t, root, slug, "state.md", `# State
+
+## Cursor
+| Key | Value |
+| --- | --- |
+| phase | build |
+| status | running |
+| next_action | /rite-build |
+`)
+	if err := os.WriteFile(filepath.Join(root, "ACTIVE"), []byte(slug+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	var stdout, stderr bytes.Buffer
+	if code := ClarifyReturn(root, []string{"enter", slug}, &stdout, &stderr); code != 0 {
+		t.Fatalf("enter code=%d stderr=%q", code, stderr.String())
+	}
+	lines := readStateLines(t, root, slug)
+	assertCursor(t, lines, state.CursorPhase, "clarify")
+	assertCursor(t, lines, state.CursorReturnPhase, "build")
+	assertCursor(t, lines, state.CursorReturnNextAction, "/rite-build")
+
+	writeReadinessFile(t, root, slug, "questions.md", `# Questions
+
+## q-2026-07-23-001
+status: open
+gate: blocking
+question: choose behavior
+`)
+	statePath := filepath.Join(root, "work", slug, "state.md")
+	stateRaw, err := os.ReadFile(statePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	waiting := strings.Replace(string(stateRaw), "| status | running |", "| status | awaiting_human |", 1) + `
+## Awaiting human
+| Key | Value |
+| --- | --- |
+| question_id | q-2026-07-23-001 |
+| gate | blocking |
+`
+	if err := os.WriteFile(statePath, []byte(waiting), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	stdout.Reset()
+	stderr.Reset()
+	if code := Resolve(root, []string{"q-2026-07-23-001", "decided"}, &stdout, &stderr); code != 0 {
+		t.Fatalf("resolve code=%d stderr=%q", code, stderr.String())
+	}
+	lines = readStateLines(t, root, slug)
+	assertCursor(t, lines, state.CursorPhase, "clarify")
+	next, _ := state.CursorField(lines, state.CursorNextAction)
+	if !strings.Contains(next, "rite-clarify") || strings.Contains(next, "rite-build") {
+		t.Fatalf("resolve next_action=%q, want clarify", next)
+	}
+
+	writeReadinessFile(t, root, slug, "brief.md", "# Brief\n\nOutcome.\n")
+	writeReadinessFile(t, root, slug, "spec.md", "# Spec\n\n## Acceptance criteria\n- AC-001 succeeds.\n")
+	writeReadinessFile(t, root, slug, "decisions.md", "# Decisions\n\nThe resolved answer is reflected in the spec.\n")
+	writeReadinessFile(t, root, slug, "assumptions.md", "# Assumptions\n\nNone material.\n")
+	digest, err := readinessInputsDigest(root, slug, readinessContract.Coverage.Inputs)
+	if err != nil {
+		t.Fatal(err)
+	}
+	writeReadinessFile(t, root, slug, "decision-coverage.md", validCoverage(digest))
+
+	stdout.Reset()
+	stderr.Reset()
+	if code := ClarifyReturn(root, []string{"restore", slug}, &stdout, &stderr); code != 0 {
+		t.Fatalf("restore code=%d stderr=%q", code, stderr.String())
+	}
+	lines = readStateLines(t, root, slug)
+	assertCursor(t, lines, state.CursorPhase, "build")
+	assertCursor(t, lines, state.CursorNextAction, "/rite-build")
+	if _, ok := state.CursorField(lines, state.CursorReturnPhase); ok {
+		t.Fatalf("return phase was not cleared:\n%s", strings.Join(lines, "\n"))
+	}
+}
+
+func TestClarifyReturnRefusesRestoreBeforeFreshClear(t *testing.T) {
+	root := t.TempDir()
+	slug := "unclear"
+	writeReadinessFile(t, root, slug, "state.md", "- Phase: build\n- Status: running\n- Next step: /rite-build\n")
+	if code := ClarifyReturn(root, []string{"enter", slug}, &bytes.Buffer{}, &bytes.Buffer{}); code != 0 {
+		t.Fatalf("enter code=%d", code)
+	}
+	if code := ClarifyReturn(root, []string{"restore", slug}, &bytes.Buffer{}, &bytes.Buffer{}); code != 3 {
+		t.Fatalf("restore code=%d, want 3 before CLEAR", code)
+	}
+}
+
+func readStateLines(t *testing.T, root, slug string) []string {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join(root, "work", slug, "state.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return strings.Split(string(raw), "\n")
+}
+
+func assertCursor(t *testing.T, lines []string, key, want string) {
+	t.Helper()
+	got, ok := state.CursorField(lines, key)
+	if !ok || got != want {
+		t.Fatalf("%s=(%q,%v), want %q\n%s", key, got, ok, want, strings.Join(lines, "\n"))
+	}
+}

package/engine/internal/lib/context.go

@@ -8,6 +8,7 @@ import (
 	"path/filepath"
 	"strings"
 
+	"github.com/devrites/devrites/internal/rootfacts"
 	"github.com/devrites/devrites/internal/state"
 )
 
@@ -16,12 +17,17 @@ const (
 	contextEnd   = "<!-- DEVRITES END -->"
 )
 
-// Context owns only a small delimited block in project context files. It never
-// rewrites the surrounding AGENTS.md / CLAUDE.md content.
+// Context owns only a small delimited block in project context files. It leaves
+// the surrounding AGENTS.md or CLAUDE.md content unchanged.
 func Context(root string, args []string, stdout, stderr io.Writer) int {
 	switch argAt(args, 0) {
 	case "sync":
-		return contextSync(root, args[1:], stdout, stderr)
+		facts, err := rootfacts.Resolve(root)
+		if err != nil {
+			fmt.Fprintf(stderr, "context: unsafe root selection: %v\n", err)
+			return 3
+		}
+		return contextSync(facts.PhysicalRoot, args[1:], stdout, stderr)
 	case "show":
 		return contextShow(root, args[1:], stdout, stderr)
 	default:
@@ -50,12 +56,16 @@ func contextSync(root string, args []string, stdout, stderr io.Writer) int {
 }
 
 type contextShowDocument struct {
-	Root            string          `json:"root"`
-	Project         string          `json:"project"`
-	ActiveWorkspace string          `json:"activeWorkspace,omitempty"`
-	Source          string          `json:"source"`
-	HostCommands    contextCommands `json:"hostCommands"`
-	Status          []Diagnostic    `json:"status"`
+	Root            string             `json:"root"`
+	Project         string             `json:"project"`
+	LexicalRoot     string             `json:"lexicalRoot,omitempty"`
+	LexicalProject  string             `json:"lexicalProject,omitempty"`
+	RootSelection   string             `json:"rootSelection"`
+	Git             rootfacts.GitFacts `json:"git"`
+	ActiveWorkspace string             `json:"activeWorkspace,omitempty"`
+	Source          string             `json:"source"`
+	HostCommands    contextCommands    `json:"hostCommands"`
+	Status          []rootfacts.Hazard `json:"status"`
 }
 
 type contextCommands struct {
@@ -85,27 +95,52 @@ func contextShow(root string, args []string, stdout, stderr io.Writer) int {
 	}
 	fmt.Fprintln(stdout, "DevRites context")
 	fmt.Fprintf(stdout, "Project: %s\n", doc.Project)
-	fmt.Fprintf(stdout, "Root: %s\n", doc.Root)
+	rootDisplay := doc.Root
+	if rootDisplay == "" {
+		rootDisplay = "none"
+	}
+	fmt.Fprintf(stdout, "Root: %s\n", rootDisplay)
+	fmt.Fprintf(stdout, "Root selection: %s\n", doc.RootSelection)
+	if doc.LexicalProject != "" && doc.LexicalProject != doc.Project {
+		fmt.Fprintf(stdout, "Project (lexical): %s\n", doc.LexicalProject)
+	}
+	if doc.LexicalRoot != "" && doc.LexicalRoot != doc.Root {
+		fmt.Fprintf(stdout, "Root (lexical): %s\n", doc.LexicalRoot)
+	}
+	if doc.Git.TopLevel != "" {
+		fmt.Fprintf(stdout, "Git: %s (dir: %s, common: %s, linked worktree: %t, submodule: %t)\n",
+			doc.Git.TopLevel, doc.Git.Dir, doc.Git.CommonDir, doc.Git.LinkedWorktree, doc.Git.Submodule)
+	}
 	if doc.ActiveWorkspace != "" {
 		fmt.Fprintf(stdout, "Active workspace: %s (source: %s)\n", doc.ActiveWorkspace, doc.Source)
 	} else {
 		fmt.Fprintf(stdout, "Active workspace: none (source: %s)\n", doc.Source)
 	}
 	fmt.Fprintf(stdout, "Commands: Claude %s · Codex %s\n", doc.HostCommands.Claude, doc.HostCommands.Codex)
+	for _, hazard := range doc.Status {
+		fmt.Fprintf(stdout, "Status [%s] %s: %s\n", hazard.ID, hazard.Severity, hazard.Message)
+		fmt.Fprintf(stdout, "Fix: %s\n", hazard.Remediation)
+	}
 	return 0
 }
 
 func contextDocument(root string) contextShowDocument {
-	project := filepath.Dir(root)
-	slug := activeSlug(root)
+	facts, err := rootfacts.Resolve(os.Getenv("DEVRITES_ROOT"))
+	if err != nil && len(facts.Hazards) == 0 && root != "" {
+		facts, _ = rootfacts.Resolve(root)
+	}
+	root = facts.PhysicalRoot
+	project := facts.PhysicalProject
+	slug := ""
+	if root != "" {
+		slug = activeSlug(root)
+	}
 	source := "none"
 	active := ""
 	if strings.TrimSpace(os.Getenv("DEVRITES_WORKSPACE")) != "" {
 		source = "DEVRITES_WORKSPACE"
 	} else if slug != "" {
 		source = "ACTIVE"
-	} else if strings.TrimSpace(os.Getenv("DEVRITES_ROOT")) != "" {
-		source = "DEVRITES_ROOT"
 	}
 	if slug != "" {
 		active = filepath.Join(".devrites", "work", slug)
@@ -116,10 +151,14 @@ func contextDocument(root string) contextShowDocument {
 	return contextShowDocument{
 		Root:            root,
 		Project:         project,
+		LexicalRoot:     facts.LexicalRoot,
+		LexicalProject:  facts.LexicalProject,
+		RootSelection:   facts.SelectionReason,
+		Git:             facts.Git,
 		ActiveWorkspace: active,
 		Source:          source,
 		HostCommands:    contextCommands{Claude: "/rite", Codex: "$rite"},
-		Status:          []Diagnostic{},
+		Status:          append([]rootfacts.Hazard{}, facts.Hazards...),
 	}
 }
 

package/engine/internal/lib/cursor_compat_test.go

@@ -32,10 +32,18 @@ func TestCanonicalCursorReadAndWriteConsumers(t *testing.T) {
 	}
 
 	t.Run("build readiness", func(t *testing.T) {
+		readyState := strings.Replace(canonicalCursor, "| phase | temper |", "| phase | vet |", 1)
+		if err := os.WriteFile(statePath, []byte(readyState), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		writeValidReadinessArtifacts(t, root, "demo")
 		var stdout, stderr bytes.Buffer
 		if code := BuildReadiness(root, []string{"demo"}, &stdout, &stderr); code != 0 {
 			t.Fatalf("code=%d, stderr=%s", code, stderr.String())
 		}
+		if err := os.WriteFile(statePath, []byte(canonicalCursor), 0o644); err != nil {
+			t.Fatal(err)
+		}
 	})
 
 	t.Run("progress", func(t *testing.T) {

package/engine/internal/lib/extensions.go

@@ -211,9 +211,6 @@ func extensionsValidate(extDir string, stdout, stderr io.Writer) int {
 	return 0
 }
 
-// validateComponentManifest enforces DevRites' Spec Kit-inspired component
-// contract while keeping distribution npm-first and project-local. It accepts a
-// small YAML subset instead of pulling a YAML dependency into the static engine.
 func validateProvenance(extName, path string) []string {
 	data, err := os.ReadFile(path)
 	if err != nil {
@@ -245,6 +242,8 @@ func validateProvenance(extName, path string) []string {
 	return problems
 }
 
+// validateComponentManifest enforces the project-local component contract
+// through a small YAML subset instead of adding a dependency to the static engine.
 func validateComponentManifest(extName, path string) []string {
 	content, ok := readFileOK(path)
 	if !ok {