devrites 4.6.0 → 5.0.0

package/engine/internal/state/workspaceschema.go

@@ -0,0 +1,58 @@
+package state
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+)
+
+// ErrWorkspaceSchemaRefused identifies a workspace whose declared schema is not
+// the current engine contract; callers map it to the blocked exit code.
+var ErrWorkspaceSchemaRefused = errors.New("workspace schema version refused")
+
+// workspaceSchemaKey is the state.md cursor row carrying the workspace schema
+// version. Workspaces written before the v5 engine carry no row and resolve to
+// schema 2, the last pre-v5 contract.
+const workspaceSchemaKey = CursorSchema
+
+// WorkspaceSchema reports the schema version declared by the feature's
+// state.md cursor. A missing row means the pre-v5 (schema 2) contract.
+func WorkspaceSchema(root, slug string) (int, error) {
+	raw, err := os.ReadFile(filepath.Join(featureDir(root, slug), LedgerFile))
+	if err != nil {
+		return 0, fmt.Errorf("read workspace schema for %s: %w", slug, err)
+	}
+	lines := strings.Split(strings.ReplaceAll(string(raw), "\r\n", "\n"), "\n")
+	return workspaceSchemaRow(lines)
+}
+
+// RequireWorkspaceSchema refuses feature workspaces whose schema is not the
+// current one, naming the exact recovery path for each direction.
+func RequireWorkspaceSchema(root, slug string) error {
+	version, err := WorkspaceSchema(root, slug)
+	if err != nil {
+		return err
+	}
+	if version < SchemaVersion {
+		return fmt.Errorf("%w: workspace %s predates the v5 workspace schema (schema %d, engine requires %d); run devrites-engine migrate %s", ErrWorkspaceSchemaRefused, slug, version, SchemaVersion, slug)
+	}
+	if version > SchemaVersion {
+		return fmt.Errorf("%w: workspace %s declares schema %d, newer than this engine's %d; upgrade devrites", ErrWorkspaceSchemaRefused, slug, version, SchemaVersion)
+	}
+	return nil
+}
+
+func workspaceSchemaRow(lines []string) (int, error) {
+	value, ok := CursorField(lines, workspaceSchemaKey)
+	if !ok {
+		return 2, nil
+	}
+	version, err := strconv.Atoi(strings.TrimSpace(value))
+	if err != nil || version <= 0 {
+		return 0, fmt.Errorf("state.md schema row is invalid (value %q); expected the workspace schema version", value)
+	}
+	return version, nil
+}

package/engine/internal/state/workspaceschema_fuzz_test.go

@@ -0,0 +1,27 @@
+package state
+
+import (
+	"strings"
+	"testing"
+)
+
+func FuzzWorkspaceSchemaRow(f *testing.F) {
+	f.Add([]byte("| schema | 5 |"))
+	f.Add([]byte("- schema: 2"))
+	f.Add([]byte("| schema | abc |"))
+	f.Add([]byte("| schema | 0 |"))
+	f.Add([]byte("## Cursor\n\n| key | value |"))
+	f.Add([]byte("```\n| schema | 7 |\n```"))
+	f.Fuzz(func(t *testing.T, doc []byte) {
+		version, err := workspaceSchemaRow(strings.Split(string(doc), "\n"))
+		if err != nil {
+			if version != 0 {
+				t.Fatalf("error result carries version %d", version)
+			}
+			return
+		}
+		if version < 1 {
+			t.Fatalf("success with non-positive version %d", version)
+		}
+	})
+}

package/engine/internal/state/workspaceschema_test.go

@@ -0,0 +1,67 @@
+package state
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func writeSchemaWorkspace(t *testing.T, stateBody string) (root, slug string) {
+	t.Helper()
+	root = t.TempDir()
+	slug = "demo"
+	if err := os.MkdirAll(featureDir(root, slug), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(featureDir(root, slug), LedgerFile), []byte(stateBody), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return root, slug
+}
+
+func TestWorkspaceSchemaDefaultsToPreV5WhenRowIsAbsent(t *testing.T) {
+	root, slug := writeSchemaWorkspace(t, "- Phase: build\n- Status: running\n")
+	version, err := WorkspaceSchema(root, slug)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if version != 2 {
+		t.Fatalf("version=%d want 2 (pre-v5 default)", version)
+	}
+	if err := RequireWorkspaceSchema(root, slug); err == nil {
+		t.Fatal("pre-v5 workspace must be refused")
+	} else if !strings.Contains(err.Error(), "devrites-engine migrate demo") {
+		t.Fatalf("refusal must name migrate, got %v", err)
+	}
+}
+
+func TestWorkspaceSchemaAcceptsCurrentAndRefusesNewer(t *testing.T) {
+	root, slug := writeSchemaWorkspace(t, "| phase | build |\n| schema | 3 |\n")
+	if err := RequireWorkspaceSchema(root, slug); err != nil {
+		t.Fatalf("current schema must pass, got %v", err)
+	}
+
+	root, slug = writeSchemaWorkspace(t, "| phase | build |\n| schema | 4 |\n")
+	err := RequireWorkspaceSchema(root, slug)
+	if err == nil {
+		t.Fatal("newer schema must be refused")
+	}
+	if !strings.Contains(err.Error(), "upgrade devrites") {
+		t.Fatalf("newer-schema refusal must name the upgrade path, got %v", err)
+	}
+}
+
+func TestWorkspaceSchemaRefusesMalformedRow(t *testing.T) {
+	root, slug := writeSchemaWorkspace(t, "| phase | build |\n| schema | banana |\n")
+	if err := RequireWorkspaceSchema(root, slug); err == nil {
+		t.Fatal("malformed schema row must be refused")
+	}
+}
+
+func TestWorkspaceSchemaMissingLedgerIsRefused(t *testing.T) {
+	root := t.TempDir()
+	if err := RequireWorkspaceSchema(root, "absent"); err == nil {
+		t.Fatal("missing workspace must be refused")
+	}
+}

package/engine/internal/state/write.go

@@ -29,11 +29,12 @@ func AppendLog(path, record string) error {
 	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
 		return fmt.Errorf("append log %s: %w", path, err)
 	}
+	// #nosec G304 -- workspace artifact path inside the .devrites tree
 	f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
 	if err != nil {
 		return fmt.Errorf("append log %s: %w", path, err)
 	}
-	defer f.Close()
+	defer func() { _ = f.Close() }()
 	if _, err := f.WriteString(strings.TrimRight(record, "\n") + "\n"); err != nil {
 		return fmt.Errorf("append log %s: %w", path, err)
 	}
@@ -54,6 +55,6 @@ func WithFeatureLock(root, slug string, fn func() error) error {
 	if err != nil {
 		return fmt.Errorf("lock feature %q: %w", slug, err)
 	}
-	defer l.release()
+	defer func() { _ = l.release() }()
 	return fn()
 }

package/engine/internal/testutil/testutil.go

@@ -8,7 +8,7 @@ import (
 )
 
 // CanonicalTasksMarkdown is a minimal valid slice graph for gate fixtures.
-const CanonicalTasksMarkdown = "# Tasks\n\n## SLICE-001 Ready\nDependencies: none\n"
+const CanonicalTasksMarkdown = "# Tasks\n\n## SLICE-001 Ready\nSatisfies: AC-001\nDependencies: none\n"
 
 // CopyTree recursively copies the directory tree at src into dst, creating dst
 // and any parents. It is used to give each test an isolated, writable copy of a
@@ -48,11 +48,12 @@ func WriteFileMode(t *testing.T, path, data string, perm os.FileMode) {
 // missing or unwritable.
 func AppendFile(t *testing.T, path, data string) {
 	t.Helper()
+	// #nosec G304 -- test fixture path under t.TempDir()
 	f, err := os.OpenFile(path, os.O_APPEND|os.O_WRONLY, 0o644)
 	if err != nil {
 		t.Fatal(err)
 	}
-	defer f.Close()
+	defer func() { _ = f.Close() }()
 	if _, err := f.WriteString(data); err != nil {
 		t.Fatal(err)
 	}
@@ -61,6 +62,7 @@ func AppendFile(t *testing.T, path, data string) {
 // ReadFile returns the contents of path, failing the test on any error.
 func ReadFile(t *testing.T, path string) string {
 	t.Helper()
+	// #nosec G304 -- test fixture path under t.TempDir()
 	data, err := os.ReadFile(path)
 	if err != nil {
 		t.Fatal(err)

package/engine/main.go

@@ -11,7 +11,6 @@ import (
 	"github.com/devrites/devrites/internal/install"
 	"github.com/devrites/devrites/internal/lib"
 	"github.com/devrites/devrites/internal/parallel"
-	"github.com/devrites/devrites/internal/state"
 	"github.com/devrites/devrites/internal/version"
 )
 
@@ -30,9 +29,12 @@ Usage:
   devrites-engine check task-graph <slug>  Validate tasks.md slice dependency graph
   devrites-engine check skill-trust <path> Scan one skill/agent Markdown for trust violations
   devrites-engine observe summary <slug>   Emit sanitized JSON workspace summary
+  devrites-engine orient <slug>            Alias for observe summary
+  devrites-engine check indexes [--root <dir>]  Report manifest and code-index presence as JSON
   devrites-engine parallel <subcommand>   Deterministic parallel worktree lease/create/integrate/cleanup
   devrites-engine state resolve <qid> "<ans>"  Resolve an open question and update state atomically
   devrites-engine state close <slug>       Archive a shipped feature and clear ACTIVE
+  devrites-engine migrate <slug> [--dry-run]  Normalize a pre-v5 workspace to the current schema
   devrites-engine secret-scan [--staged] [--stdin] [slug]  Scan exact staged blobs, stdin, or touched files; HIGH blocks
   devrites-engine open-visual <path-or-name> [--slug <slug>] [--no-open]
                                          Resolve a visual HTML file, optionally open it locally, print agent paths
@@ -85,8 +87,12 @@ func run(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 		return parallel.Run("parallel", args[1:], stdin, stdout, stderr)
 	case "observe":
 		return cmdObserve(root, args[1:], stdout, stderr)
+	case "orient":
+		return cmdOrient(root, args[1:], stdout, stderr)
 	case "state":
 		return cmdState(root, args[1:], stdout, stderr)
+	case "migrate":
+		return lib.Migrate(root, args[1:], stdout, stderr)
 	case "secret-scan":
 		return lib.SecretScan(root, args[1:], stdin, stdout, stderr)
 	case "open-visual":
@@ -105,37 +111,34 @@ func run(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 
 func cmdCheck(root string, args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 	if len(args) == 0 {
-		fmt.Fprintln(stderr, "usage: devrites-engine check <candidate|readiness|seal|path-disjoint|task-graph|skill-trust> ...")
+		fmt.Fprintln(stderr, "usage: devrites-engine check <candidate|readiness|seal|path-disjoint|task-graph|skill-trust|indexes> ...")
 		return exitUsage
 	}
 	sub, rest := args[0], args[1:]
 	switch sub {
 	case "candidate":
-		return cmdCandidate(rest, stdout, stderr)
+		return cmdCandidate(root, rest, stdout, stderr)
 	case "readiness", "seal":
-		return cmdGate(gate.Kind(sub), rest, stdout, stderr)
+		return cmdGate(root, gate.Kind(sub), rest, stdout, stderr)
 	case "path-disjoint":
 		return parallel.Run("path-disjoint", rest, stdin, stdout, stderr)
 	case "task-graph":
 		return cmdTaskGraph(root, rest, stdout, stderr)
 	case "skill-trust":
 		return cmdSkillTrust(rest, stdout, stderr)
+	case "indexes":
+		return lib.RunEnvironmentCheck(root, rest, stdout, stderr)
 	default:
 		fmt.Fprintf(stderr, "devrites: unknown check %q\n", sub)
 		return exitUsage
 	}
 }
 
-func cmdCandidate(args []string, stdout, stderr io.Writer) int {
+func cmdCandidate(root string, args []string, stdout, stderr io.Writer) int {
 	if len(args) != 1 {
 		fmt.Fprintln(stderr, "usage: devrites-engine check candidate <slug>")
 		return exitUsage
 	}
-	root, err := state.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
-	if err != nil {
-		fmt.Fprintf(stderr, "devrites: %v\n", err)
-		return exitUsage
-	}
 	digest, files, err := lib.CandidateIdentity(root, args[0])
 	if err != nil {
 		fmt.Fprintf(stderr, "candidate: BLOCKED: %v\n", err)
@@ -164,17 +167,12 @@ func cmdState(root string, args []string, stdout, stderr io.Writer) int {
 // cmdGate runs readiness completeness or the final seal aggregate. Missing or
 // failed requirements return the HITL pause code; invalid gate state returns
 // the usage/internal code.
-func cmdGate(kind gate.Kind, args []string, stdout, stderr io.Writer) int {
+func cmdGate(root string, kind gate.Kind, args []string, stdout, stderr io.Writer) int {
 	emitBinding := kind == gate.Readiness && len(args) == 2 && args[0] == "--emit-binding"
 	if !emitBinding && len(args) != 1 {
 		fmt.Fprintf(stderr, "usage: devrites-engine check %s <slug>\n", kind)
 		return exitUsage
 	}
-	root, err := state.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
-	if err != nil {
-		fmt.Fprintf(stderr, "devrites: %v\n", err)
-		return exitUsage
-	}
 	if emitBinding {
 		binding, err := gate.ReadinessBinding(root, args[1])
 		if err != nil {
@@ -212,14 +210,6 @@ func cmdTaskGraph(root string, args []string, stdout, stderr io.Writer) int {
 		fmt.Fprintln(stderr, "usage: devrites-engine check task-graph <slug>")
 		return exitUsage
 	}
-	if root == "" {
-		var err error
-		root, err = state.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
-		if err != nil {
-			fmt.Fprintf(stderr, "devrites: %v\n", err)
-			return exitUsage
-		}
-	}
 	return lib.RunTaskGraphCheck(root, args[0], stdout, stderr)
 }
 
@@ -240,14 +230,6 @@ func cmdObserve(root string, args []string, stdout, stderr io.Writer) int {
 		fmt.Fprintf(stderr, "devrites: unknown observe command %q\n", args[0])
 		return exitUsage
 	}
-	if root == "" {
-		var err error
-		root, err = state.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
-		if err != nil {
-			fmt.Fprintf(stderr, "devrites: %v\n", err)
-			return exitUsage
-		}
-	}
 	slug, code, err := lib.ActiveSlug(root, args[1:])
 	if err != nil {
 		fmt.Fprintf(stderr, "observe: %v\n", err)
@@ -258,3 +240,15 @@ func cmdObserve(root string, args []string, stdout, stderr io.Writer) int {
 	}
 	return lib.RunObserveSummary(root, slug, stdout, stderr)
 }
+
+func cmdOrient(root string, args []string, stdout, stderr io.Writer) int {
+	slug, code, err := lib.ActiveSlug(root, args)
+	if err != nil {
+		fmt.Fprintf(stderr, "orient: %v\n", err)
+		if code == 0 {
+			code = exitUsage
+		}
+		return code
+	}
+	return lib.RunObserveSummary(root, slug, stdout, stderr)
+}

package/engine/observation_contract_test.go

@@ -0,0 +1,174 @@
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func copyGoldenShippableWorkspace(t *testing.T, workspace string) {
+	t.Helper()
+	golden := filepath.Join("..", "evals", "golden", "shippable-feature")
+	entries, err := os.ReadDir(golden)
+	if err != nil {
+		t.Fatalf("read golden fixture: %v", err)
+	}
+	if err := os.MkdirAll(workspace, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	for _, entry := range entries {
+		src := filepath.Join(golden, entry.Name())
+		dst := filepath.Join(workspace, entry.Name())
+		if entry.IsDir() {
+			if err := copyDir(src, dst); err != nil {
+				t.Fatalf("copy %s: %v", entry.Name(), err)
+			}
+			continue
+		}
+		data, err := os.ReadFile(src)
+		if err != nil {
+			t.Fatalf("read %s: %v", src, err)
+		}
+		if err := os.WriteFile(dst, data, 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func copyDir(src, dst string) error {
+	if err := os.MkdirAll(dst, 0o755); err != nil {
+		return err
+	}
+	entries, err := os.ReadDir(src)
+	if err != nil {
+		return err
+	}
+	for _, entry := range entries {
+		srcPath := filepath.Join(src, entry.Name())
+		dstPath := filepath.Join(dst, entry.Name())
+		if entry.IsDir() {
+			if err := copyDir(srcPath, dstPath); err != nil {
+				return err
+			}
+			continue
+		}
+		data, err := os.ReadFile(srcPath)
+		if err != nil {
+			return err
+		}
+		if err := os.WriteFile(dstPath, data, 0o644); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func TestOrientMatchesObserveSummaryOnGoldenWorkspace(t *testing.T) {
+	project := t.TempDir()
+	root := filepath.Join(project, ".devrites")
+	slug := "add-csv-export"
+	workspace := filepath.Join(root, "work", slug)
+	copyGoldenShippableWorkspace(t, workspace)
+	if err := os.WriteFile(filepath.Join(root, "ACTIVE"), []byte(slug+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("DEVRITES_ROOT", project)
+
+	var orientOut, observeOut, stderr bytes.Buffer
+	if code := run([]string{"orient", slug}, strings.NewReader(""), &orientOut, &stderr); code != exitOK {
+		t.Fatalf("orient code=%d stderr=%q", code, stderr.String())
+	}
+	stderr.Reset()
+	if code := run([]string{"observe", "summary", slug}, strings.NewReader(""), &observeOut, &stderr); code != exitOK {
+		t.Fatalf("observe summary code=%d stderr=%q", code, stderr.String())
+	}
+	if orientOut.String() != observeOut.String() {
+		t.Fatalf("orient and observe summary differ:\norient=%q\nobserve=%q", orientOut.String(), observeOut.String())
+	}
+
+	var summary map[string]any
+	if err := json.Unmarshal(orientOut.Bytes(), &summary); err != nil {
+		t.Fatalf("summary JSON: %v", err)
+	}
+	if summary["slug"] != slug {
+		t.Fatalf("slug=%v, want %q", summary["slug"], slug)
+	}
+	if summary["phase"] != "done" {
+		t.Fatalf("phase=%v, want done", summary["phase"])
+	}
+}
+
+func TestCheckIndexesJSONContract(t *testing.T) {
+	project := t.TempDir()
+	root := filepath.Join(project, ".devrites")
+	manifestDir := filepath.Join(project, ".claude")
+	if err := os.MkdirAll(manifestDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(manifestDir, "devrites.manifest"), []byte("devrites\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(project, ".codegraph"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("DEVRITES_ROOT", root)
+
+	var stdout, stderr bytes.Buffer
+	if code := run([]string{"check", "indexes", "--root", project}, strings.NewReader(""), &stdout, &stderr); code != exitOK {
+		t.Fatalf("indexes code=%d stdout=%q stderr=%q", code, stdout.String(), stderr.String())
+	}
+
+	var report struct {
+		EngineVersion string `json:"engine_version"`
+		Manifest      struct {
+			Present bool `json:"present"`
+		} `json:"manifest"`
+		Indexes []struct {
+			Path    string `json:"path"`
+			Present bool   `json:"present"`
+		} `json:"indexes"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &report); err != nil {
+		t.Fatalf("indexes JSON: %v; stdout=%q", err, stdout.String())
+	}
+	if report.EngineVersion == "" {
+		t.Fatal("missing engine_version")
+	}
+	if !report.Manifest.Present {
+		t.Fatal("expected manifest present")
+	}
+	wantIndexes := []struct {
+		path    string
+		present bool
+	}{
+		{".codegraph", true},
+		{".code-review-graph", false},
+		{".codebase-memory", false},
+	}
+	if len(report.Indexes) != len(wantIndexes) {
+		t.Fatalf("indexes=%d, want %d", len(report.Indexes), len(wantIndexes))
+	}
+	for i, want := range wantIndexes {
+		got := report.Indexes[i]
+		if got.Path != want.path || got.Present != want.present {
+			t.Fatalf("index[%d]=%+v, want path=%q present=%v", i, got, want.path, want.present)
+		}
+	}
+}
+
+func TestOrientRoutesLikeObserveSummary(t *testing.T) {
+	t.Setenv("DEVRITES_ROOT", t.TempDir())
+	for _, args := range [][]string{{"orient", "missing"}, {"observe", "summary", "missing"}} {
+		t.Run(strings.Join(args, "-"), func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			code := run(args, strings.NewReader(""), &stdout, &stderr)
+			if strings.Contains(stderr.String(), "unknown command") || strings.Contains(stderr.String(), "unknown observe") {
+				t.Fatalf("%q was not routed: %s", args, stderr.String())
+			}
+			_ = code
+		})
+	}
+}

package/engine/root_routing_test.go

@@ -16,7 +16,15 @@ func TestRootModeForCoversReadAndWriteSurfaces(t *testing.T) {
 		want    rootMode
 	}{
 		{name: "unrelated command", command: "unknown", want: rootUnused},
-		{name: "check family", command: "check", args: []string{"readiness"}, want: rootUnused},
+		{name: "check candidate", command: "check", args: []string{"candidate"}, want: rootStrictUsage},
+		{name: "check readiness", command: "check", args: []string{"readiness"}, want: rootStrictUsage},
+		{name: "check seal", command: "check", args: []string{"seal"}, want: rootStrictUsage},
+		{name: "check task-graph", command: "check", args: []string{"task-graph"}, want: rootStrictUsage},
+		{name: "check path-disjoint", command: "check", args: []string{"path-disjoint"}, want: rootUnused},
+		{name: "check skill-trust", command: "check", args: []string{"skill-trust"}, want: rootUnused},
+		{name: "observe summary", command: "observe", args: []string{"summary"}, want: rootStrictUsage},
+		{name: "orient", command: "orient", want: rootStrictUsage},
+		{name: "check indexes", command: "check", args: []string{"indexes"}, want: rootLenient},
 		{name: "resolve", command: "state", args: []string{"resolve"}, want: rootStrict},
 		{name: "close", command: "state", args: []string{"close"}, want: rootStrict},
 		{name: "unknown state command", command: "state", args: []string{"unknown"}, want: rootUnused},
@@ -34,7 +42,7 @@ func TestRootModeForCoversReadAndWriteSurfaces(t *testing.T) {
 }
 
 func TestRemovedCommandsAreUnknown(t *testing.T) {
-	for _, command := range []string{"snapshot", "readiness", "seal", "spec-validate", "check-acceptance", "evidence-fresh", "coverage", "doubt-coverage", "test-integrity", "review-integrity", "build-readiness", "readiness-digest", "analyze", "ledger", "resolve", "clarify-return", "tick-afk", "recovery", "close-out", "migrate", "status", "budget", "mutation-gate", "validate-pack", "doctor"} {
+	for _, command := range []string{"snapshot", "readiness", "seal", "spec-validate", "check-acceptance", "evidence-fresh", "coverage", "doubt-coverage", "test-integrity", "review-integrity", "build-readiness", "readiness-digest", "analyze", "ledger", "resolve", "clarify-return", "tick-afk", "recovery", "close-out", "status", "budget", "mutation-gate", "validate-pack", "doctor"} {
 		for _, args := range [][]string{{command}, {command, "--json"}} {
 			t.Run(strings.Join(args, "-"), func(t *testing.T) {
 				var stdout, stderr bytes.Buffer
@@ -100,7 +108,16 @@ func TestRemovedOutputFlagsAreRejected(t *testing.T) {
 
 func TestNestedCommandFamiliesAreRoutedAndAdvertised(t *testing.T) {
 	t.Setenv("DEVRITES_ROOT", t.TempDir())
-	for _, args := range [][]string{{"check", "candidate"}, {"check", "readiness"}, {"check", "seal"}, {"state", "resolve"}, {"state", "close"}} {
+	for _, args := range [][]string{
+		{"check", "candidate"},
+		{"check", "readiness"},
+		{"check", "seal"},
+		{"check", "indexes"},
+		{"orient", "feature"},
+		{"observe", "summary", "feature"},
+		{"state", "resolve"},
+		{"state", "close"},
+	} {
 		t.Run(strings.Join(args, "-"), func(t *testing.T) {
 			var stdout, stderr bytes.Buffer
 			code := run(args, strings.NewReader(""), &stdout, &stderr)
@@ -109,7 +126,7 @@ func TestNestedCommandFamiliesAreRoutedAndAdvertised(t *testing.T) {
 			}
 		})
 	}
-	for _, want := range []string{"devrites-engine check candidate", "devrites-engine check readiness", "devrites-engine check seal", "devrites-engine state resolve", "devrites-engine state close"} {
+	for _, want := range []string{"devrites-engine orient", "devrites-engine check indexes"} {
 		if !strings.Contains(usage, want) {
 			t.Fatalf("usage does not advertise %q", want)
 		}
@@ -127,7 +144,7 @@ func TestNestedCommandFamilyUsageListsOnlyRetainedCommands(t *testing.T) {
 		want    string
 		removed []string
 	}{
-		{args: []string{"check"}, want: "check <candidate|readiness|seal|path-disjoint|task-graph|skill-trust>", removed: []string{"spec"}},
+		{args: []string{"check"}, want: "check <candidate|readiness|seal|path-disjoint|task-graph|skill-trust|indexes>", removed: []string{"spec"}},
 		{args: []string{"state"}, want: "state <resolve|close>", removed: []string{"clarify", "tick-afk", "recovery"}},
 	} {
 		t.Run(test.args[0], func(t *testing.T) {
@@ -157,6 +174,7 @@ func TestCheckCandidateRoutesAndPrintsIdentity(t *testing.T) {
 	writeBasenameFile(t, project, "source.go", "package source\n")
 	manifest := "# Touched files\n\n## Touched files\nCandidate paths are declared below.\n\n## Candidate manifest\n| State | File | Slice | Reason |\n| --- | --- | --- | --- |\n| present | `source.go` | S-1 | Implementation. |\n"
 	writeBasenameFile(t, workspace, "touched-files.md", manifest)
+	writeBasenameFile(t, workspace, "state.md", "| schema | 3 |\n")
 	t.Setenv("DEVRITES_ROOT", root)
 	var stdout, stderr bytes.Buffer
 	if code := run([]string{"check", "candidate", "feature"}, strings.NewReader(""), &stdout, &stderr); code != exitOK {
@@ -172,6 +190,7 @@ func TestCheckReadinessEmitBindingRoutesOnlyExactShape(t *testing.T) {
 	root := filepath.Join(t.TempDir(), ".devrites")
 	workspace := filepath.Join(root, "work", "feature")
 	for name, body := range map[string]string{
+		"state.md":             "| schema | 3 |\n",
 		"spec.md":              "# Spec\n\nReady.\n",
 		"decision-coverage.md": "# Decision coverage\n\nCLEAR\n",
 		"architecture.md":      "# Architecture\n\nReady.\n",

package/engine/testdata/fixtures/basic/devrites-root/work/auth-tokens/state.md

@@ -1,5 +1,6 @@
 - Phase: build
 - Status: running
+- Schema: 3
 
 # Status
 

package/engine/testdata/fixtures/basic/devrites-root/work/search-ranking/state.md

@@ -1,2 +1,3 @@
 - Phase: spec
 - Status: running
+- Schema: 3

package/engine/testdata/golden/TestParityResolve/answer/state.md.golden

@@ -1,5 +1,6 @@
 - Status: running
 - Next step: (resume: `/rite-build (Claude) / $rite-build (Codex)` to continue the workflow)
+- Schema: 3
 
 ## Log
 - 2024-01-01 spec: created

package/engine/testdata/golden/TestParityResolve/drop/state.md.golden

@@ -1,5 +1,6 @@
 - Status: awaiting_human
 - Next step: wait for q-1
+- Schema: 3
 
 ## Awaiting human
 - qid: q-1

package/engine/tests/adr_0027_readiness_binding_test.go

@@ -26,7 +26,7 @@ func TestADR0027ReadinessBindingBlocksPlanDriftWithRestoredMtime(t *testing.T) {
 		"tasks.md":             testutil.CanonicalTasksMarkdown,
 		"traceability.md":      "# Traceability\n\nAC-001 -> slice A.\n",
 		"eng-review.md":        "# Engineering review\n\nREADY\n",
-		"test-plan.md":         "# Test plan\n\nRun focused Go tests.\n",
+		"test-plan.md":         "# Test plan\n\nRun focused Go tests for AC-001.\n",
 	} {
 		testutil.WriteFile(t, filepath.Join(workspace, name), body)
 	}

package/engine/tests/cli_test.go

@@ -44,11 +44,11 @@ func TestMain(m *testing.M) {
 	build.Dir = engineRoot
 	build.Env = append(os.Environ(), "CGO_ENABLED=0")
 	if out, err := build.CombinedOutput(); err != nil {
-		os.RemoveAll(dir)
+		_ = os.RemoveAll(dir)
 		panic("go build failed: " + err.Error() + "\n" + string(out))
 	}
 	code := m.Run()
-	os.RemoveAll(dir)
+	_ = os.RemoveAll(dir)
 	os.Exit(code)
 }
 

package/engine/tests/gate_test.go

@@ -70,7 +70,7 @@ func TestReadinessEmitBindingPassesExactCLIContract(t *testing.T) {
 	writeCompleteGateCLIWorkspace(t, root, slug, state.PhaseBuild, state.PhaseBuild, "none\n")
 
 	out, errOut, code := runDevrites(t, root, "check", "readiness", "--emit-binding", slug)
-	const wantOut = "Readiness inputs SHA-256: f72109687057f33d5d7f05e5436a4dcc88ccf87367d0933afd9fdcf1a023f5c0\n"
+	const wantOut = "Readiness inputs SHA-256: 72cf891ac97737493a27ead330a827e93c28d8e7e0103e4e972fa35fdcaa8158\n"
 	if code != 0 || out != wantOut || errOut != "" {
 		t.Fatalf("code=%d stdout=%q stderr=%q, want code=0 stdout=%q stderr empty", code, out, errOut, wantOut)
 	}
@@ -595,7 +595,7 @@ func newFinalSealRepo(t *testing.T) (string, string) {
 		"tasks.md":             testutil.CanonicalTasksMarkdown,
 		"traceability.md":      "# Traceability\n\nAC-001 -> final seal.\n",
 		"eng-review.md":        "# Engineering review\n\nPASS\n",
-		"test-plan.md":         "# Test plan\n\nRun focused Go tests.\n",
+		"test-plan.md":         "# Test plan\n\nRun focused Go tests for AC-001.\n",
 		"evidence.md":          "# Evidence\n\nFocused Go tests passed.\n",
 		"touched-files.md":     "# Touched files\n\n## Touched files\nCandidate paths are declared only in the manifest below.\n\n## Candidate manifest\n| State | File | Slice | Reason |\n| --- | --- | --- | --- |\n| present | `source.go` | S-1 | Final Seal fixture. |\n",
 		"review.md": `# Review