devrites 3.0.3 → 3.0.5

package/engine/internal/lib/packageexistence_test.go

@@ -0,0 +1,343 @@
+package lib
+
+import (
+	"bytes"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestPackageExistenceJavaScriptWorkspaces(t *testing.T) {
+	tests := []struct {
+		name        string
+		sourcePath  string
+		workingDir  string
+		importLine  string
+		files       map[string]string
+		wantCode    int
+		wantFinding string
+	}{
+		{
+			name:       "nested workspace",
+			sourcePath: "frontend/src/example.ts",
+			workingDir: "frontend",
+			importLine: `import { Dialog } from "@ark-ui/svelte/dialog";`,
+			files: map[string]string{
+				"frontend/package.json": `{"dependencies":{"@ark-ui/svelte":"^5.22.1"}}`,
+			},
+		},
+		{
+			name:       "scoped package subpath",
+			sourcePath: "app/src/example.ts",
+			importLine: `import value from "@scope/package/subpath";`,
+			files: map[string]string{
+				"app/package.json": `{"devDependencies":{"@scope/package":"1.0.0"}}`,
+			},
+		},
+		{
+			name:       "wildcard alias",
+			sourcePath: "frontend/src/example.ts",
+			importLine: `import Button from "$lib/components/button";`,
+			files: map[string]string{
+				"frontend/package.json":              `{}`,
+				"frontend/tsconfig.json":             "{\n  // SvelteKit generates the inherited aliases.\n  \"extends\": \"./.svelte-kit/tsconfig.json\"\n}",
+				"frontend/.svelte-kit/tsconfig.json": `{"compilerOptions":{"paths":{"$lib/*":["../src/lib/*"]}}}`,
+			},
+		},
+		{
+			name:       "exact alias",
+			sourcePath: "frontend/src/example.ts",
+			importLine: `import library from "$lib";`,
+			files: map[string]string{
+				"frontend/package.json":  `{}`,
+				"frontend/tsconfig.json": `{"compilerOptions":{"paths":{"$lib":["./src/lib"]}}}`,
+			},
+		},
+		{
+			name:       "package shaped alias",
+			sourcePath: "frontend/src/example.svelte",
+			importLine: `import { css } from "styled-system/css";`,
+			files: map[string]string{
+				"frontend/package.json":  `{}`,
+				"frontend/jsconfig.json": `{"compilerOptions":{"paths":{"styled-system/*":["./styled-system/*"]}}}`,
+			},
+		},
+		{
+			name:        "undeclared dependency",
+			sourcePath:  "frontend/src/example.ts",
+			importLine:  `import missing from "definitely-missing-package";`,
+			files:       map[string]string{"frontend/package.json": `{}`},
+			wantCode:    3,
+			wantFinding: "definitely-missing-package",
+		},
+		{
+			name:       "sibling isolation",
+			sourcePath: "workspace-a/src/example.ts",
+			importLine: `import sibling from "sibling-only-package";`,
+			files: map[string]string{
+				"workspace-a/package.json": `{}`,
+				"workspace-b/package.json": `{"dependencies":{"sibling-only-package":"1.0.0"}}`,
+			},
+			wantCode:    3,
+			wantFinding: "sibling-only-package",
+		},
+		{
+			name:       "malformed config does not allow alias",
+			sourcePath: "frontend/src/example.ts",
+			importLine: `import { css } from "styled-system/css";`,
+			files: map[string]string{
+				"frontend/package.json":  `{}`,
+				"frontend/tsconfig.json": `{"compilerOptions":{"paths":{"styled-system/*":["./styled-system/*"]}}`,
+			},
+			wantCode:    3,
+			wantFinding: "styled-system",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			repo := t.TempDir()
+			writePackageExistenceFile(t, repo, "Cargo.toml", "[package]\nname = \"fixture\"\nversion = \"0.1.0\"\n")
+			writePackageExistenceFile(t, repo, test.sourcePath, "// baseline\n")
+			for path, content := range test.files {
+				writePackageExistenceFile(t, repo, path, content+"\n")
+			}
+			gitPackageExistence(t, repo, "init", "-q")
+			gitPackageExistence(t, repo, "config", "user.email", "test@example.com")
+			gitPackageExistence(t, repo, "config", "user.name", "Test")
+			gitPackageExistence(t, repo, "add", ".")
+			gitPackageExistence(t, repo, "commit", "-qm", "baseline")
+			if err := os.MkdirAll(featureDir(repo, "feat"), 0o755); err != nil {
+				t.Fatal(err)
+			}
+			writePackageExistenceFile(t, repo, test.sourcePath, "// baseline\n"+test.importLine+"\n")
+			t.Chdir(filepath.Join(repo, test.workingDir))
+
+			var stdout, stderr bytes.Buffer
+			gotCode := PackageExistence(repo, []string{"feat"}, &stdout, &stderr)
+			if gotCode != test.wantCode {
+				t.Fatalf("code = %d, want %d\nstdout: %s\nstderr: %s", gotCode, test.wantCode, stdout.String(), stderr.String())
+			}
+			if test.wantFinding != "" && !strings.Contains(stderr.String(), test.wantFinding) {
+				t.Fatalf("stderr does not name %q: %s", test.wantFinding, stderr.String())
+			}
+		})
+	}
+}
+
+func TestPackageExistenceNonJavaScriptWorkspaces(t *testing.T) {
+	tests := []struct {
+		name        string
+		sourcePath  string
+		addedSource string
+		files       map[string]string
+		wantCode    int
+		wantFinding string
+	}{
+		{
+			name:        "go import block rejects undeclared module",
+			sourcePath:  "main.go",
+			addedSource: "package main\n\nimport (\n\t\"definitely.invalid/missing\"\n)\n",
+			files:       map[string]string{"go.mod": "module example.com/app\n\ngo 1.26\n"},
+			wantCode:    3,
+			wantFinding: "definitely.invalid/missing",
+		},
+		{
+			name:        "go modules do not collide by hostname",
+			sourcePath:  "main.go",
+			addedSource: "package main\n\nimport \"github.com/evil/missing\"\n",
+			files:       map[string]string{"go.mod": "module example.com/app\n\ngo 1.26\n\nrequire github.com/good/pkg v1.0.0\n"},
+			wantCode:    3,
+			wantFinding: "github.com/evil/missing",
+		},
+		{
+			name:        "nested go module declaration",
+			sourcePath:  "backend/main.go",
+			addedSource: "package main\n\nimport \"github.com/good/pkg/sub\"\n",
+			files: map[string]string{
+				"Cargo.toml":     "[package]\nname = \"root\"\nversion = \"0.1.0\"\n",
+				"backend/go.mod": "module example.com/backend\n\ngo 1.26\n\nrequire github.com/good/pkg v1.0.0\n",
+			},
+		},
+		{
+			name:        "go standard library subpackage",
+			sourcePath:  "main.go",
+			addedSource: "package main\n\nimport \"encoding/json\"\n",
+			files:       map[string]string{"go.mod": "module example.com/app\n\ngo 1.26\n"},
+		},
+		{
+			name:        "go standard library typo remains undeclared",
+			sourcePath:  "main.go",
+			addedSource: "package main\n\nimport \"encoding/josn\"\n",
+			files:       map[string]string{"go.mod": "module example.com/app\n\ngo 1.26\n"},
+			wantCode:    3,
+			wantFinding: "encoding/josn",
+		},
+		{
+			name:        "malformed go manifest does not declare import",
+			sourcePath:  "main.go",
+			addedSource: "package main\n\nimport \"github.com/missing/pkg\"\n",
+			files:       map[string]string{"go.mod": "module example.com/app\n\ngo 1.26\n\nrequire (\n  github.com/missing/pkg v1.0.0\n"},
+			wantCode:    3,
+			wantFinding: "github.com/missing/pkg",
+		},
+		{
+			name:        "rust rejects undeclared crate",
+			sourcePath:  "src/main.rs",
+			addedSource: "use definitely_missing_crate::Thing;\n",
+			files:       map[string]string{"Cargo.toml": "[package]\nname = \"fixture\"\nversion = \"0.1.0\"\n\n[dependencies]\n"},
+			wantCode:    3,
+			wantFinding: "definitely_missing_crate",
+		},
+		{
+			name:        "nested rust dependency and hyphen normalization",
+			sourcePath:  "crates/app/src/main.rs",
+			addedSource: "use serde_json::Value;\n",
+			files: map[string]string{
+				"Cargo.toml":            "[workspace]\nmembers = [\"crates/app\"]\n",
+				"crates/app/Cargo.toml": "[package]\nname = \"app\"\nversion = \"0.1.0\"\n\n[dependencies.serde-json]\nversion = \"1\"\n",
+			},
+		},
+		{
+			name:        "python dotted import uses top-level module",
+			sourcePath:  "app.py",
+			addedSource: "from requests.sessions import Session\n",
+			files:       map[string]string{"requirements.txt": "requests==2.32.0\n"},
+		},
+		{
+			name:        "python standard library module",
+			sourcePath:  "app.py",
+			addedSource: "import asyncio\n",
+			files:       map[string]string{"requirements.txt": "requests==2.32.0\n"},
+		},
+		{
+			name:        "nested python manifest declaration",
+			sourcePath:  "backend/app.py",
+			addedSource: "import requests\n",
+			files: map[string]string{
+				"Cargo.toml":               "[package]\nname = \"root\"\nversion = \"0.1.0\"\n",
+				"backend/requirements.txt": "requests==2.32.0\n",
+			},
+		},
+		{
+			name:        "pyproject dependency declaration",
+			sourcePath:  "service/app.py",
+			addedSource: "import requests\n",
+			files: map[string]string{
+				"service/pyproject.toml": "[project]\ndependencies = [\n  \"requests[socks]>=2.32\",\n]\n",
+			},
+		},
+		{
+			name:        "pipfile dependency declaration",
+			sourcePath:  "service/app.py",
+			addedSource: "import requests\n",
+			files: map[string]string{
+				"service/Pipfile": "[packages]\nrequests = \"*\"\n",
+			},
+		},
+		{
+			name:        "malformed pyproject does not declare import",
+			sourcePath:  "service/app.py",
+			addedSource: "import definitely_missing\n",
+			files: map[string]string{
+				"service/pyproject.toml": "[project]\ndependencies = [\n  \"definitely_missing\"\n",
+			},
+			wantCode:    3,
+			wantFinding: "definitely_missing",
+		},
+		{
+			name:        "python multiple imports reject undeclared module",
+			sourcePath:  "app.py",
+			addedSource: "import requests, definitely_missing\n",
+			files:       map[string]string{"requirements.txt": "requests==2.32.0\n"},
+			wantCode:    3,
+			wantFinding: "definitely_missing",
+		},
+		{
+			name:        "comments and other ecosystems do not declare python imports",
+			sourcePath:  "app.py",
+			addedSource: "import definitely_missing\n",
+			files: map[string]string{
+				"Cargo.toml":       "[package]\nname = \"definitely_missing\"\nversion = \"0.1.0\"\n",
+				"requirements.txt": "# definitely_missing is intentionally absent\n",
+			},
+			wantCode:    3,
+			wantFinding: "definitely_missing",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			repo := t.TempDir()
+			for path, content := range test.files {
+				writePackageExistenceFile(t, repo, path, content)
+			}
+			writePackageExistenceFile(t, repo, test.sourcePath, "// baseline\n")
+			gitPackageExistence(t, repo, "init", "-q")
+			gitPackageExistence(t, repo, "config", "user.email", "test@example.com")
+			gitPackageExistence(t, repo, "config", "user.name", "Test")
+			gitPackageExistence(t, repo, "add", ".")
+			gitPackageExistence(t, repo, "commit", "-qm", "baseline")
+			if err := os.MkdirAll(featureDir(repo, "feat"), 0o755); err != nil {
+				t.Fatal(err)
+			}
+			writePackageExistenceFile(t, repo, test.sourcePath, test.addedSource)
+			t.Chdir(repo)
+
+			var stdout, stderr bytes.Buffer
+			gotCode := PackageExistence(repo, []string{"feat"}, &stdout, &stderr)
+			if gotCode != test.wantCode {
+				t.Fatalf("code = %d, want %d\nstdout: %s\nstderr: %s", gotCode, test.wantCode, stdout.String(), stderr.String())
+			}
+			if test.wantFinding != "" && !strings.Contains(stderr.String(), test.wantFinding) {
+				t.Fatalf("stderr does not name %q: %s", test.wantFinding, stderr.String())
+			}
+		})
+	}
+}
+
+func TestPackageExistenceGenericResolverFailsClosed(t *testing.T) {
+	repo := t.TempDir()
+	writePackageExistenceFile(t, repo, "package.json", `{"dependencies":{"definitely-missing-package":"1.0.0"}}`)
+	writePackageExistenceFile(t, repo, "src/example.custom", "// baseline\n")
+	gitPackageExistence(t, repo, "init", "-q")
+	gitPackageExistence(t, repo, "config", "user.email", "test@example.com")
+	gitPackageExistence(t, repo, "config", "user.name", "Test")
+	gitPackageExistence(t, repo, "add", ".")
+	gitPackageExistence(t, repo, "commit", "-qm", "baseline")
+	if err := os.MkdirAll(featureDir(repo, "feat"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	writePackageExistenceFile(t, repo, "src/example.custom", "import \"definitely-missing-package\"\n")
+	t.Chdir(repo)
+
+	var stdout, stderr bytes.Buffer
+	gotCode := PackageExistence(repo, []string{"feat"}, &stdout, &stderr)
+	if gotCode != 3 {
+		t.Fatalf("code = %d, want 3\nstdout: %s\nstderr: %s", gotCode, stdout.String(), stderr.String())
+	}
+	if !strings.Contains(stderr.String(), "definitely-missing-package") {
+		t.Fatalf("stderr does not name unresolved import: %s", stderr.String())
+	}
+}
+
+func writePackageExistenceFile(t *testing.T, root, path, content string) {
+	t.Helper()
+	fullPath := filepath.Join(root, filepath.FromSlash(path))
+	if err := os.MkdirAll(filepath.Dir(fullPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(fullPath, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func gitPackageExistence(t *testing.T, root string, args ...string) {
+	t.Helper()
+	cmd := exec.Command("git", append([]string{"-C", root}, args...)...)
+	if out, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("git %s: %v\n%s", strings.Join(args, " "), err, out)
+	}
+}

package/engine/internal/lib/util.go

@@ -14,7 +14,7 @@ func gitToplevel(dir string) string {
 	if err != nil {
 		return ""
 	}
-	return strings.TrimSpace(string(out))
+	return filepath.Clean(strings.TrimSpace(string(out)))
 }
 
 // gitDiffNames lists the paths that differ, relative to gitRoot. With one ref it

package/engine/internal/migrate/migrate.go

@@ -90,11 +90,11 @@ func featureDirsNeedingNormalization(root string) ([]normalizationTarget, error)
 }
 
 func needsNormalizeFeature(dir string) bool {
-	if !regularFileExists(filepath.Join(dir, "feature.md")) {
+	if !regularFileExists(filepath.Join(dir, state.WorkspaceMapFile)) {
 		return true
 	}
-	return regularFileExists(filepath.Join(dir, "evidence.md")) && !regularFileExists(filepath.Join(dir, "proof.md")) ||
-		regularFileExists(filepath.Join(dir, state.LedgerFile)) && !regularFileExists(filepath.Join(dir, "status.md"))
+	return regularFileExists(filepath.Join(dir, "proof.md")) && !regularFileExists(filepath.Join(dir, state.EvidenceFile)) ||
+		regularFileExists(filepath.Join(dir, "status.md")) && !regularFileExists(filepath.Join(dir, state.LedgerFile))
 }
 
 func regularFileExists(path string) bool {
@@ -103,16 +103,21 @@ func regularFileExists(path string) bool {
 }
 
 func normalizeFeatureDir(dir, slug string) error {
-	if !regularFileExists(filepath.Join(dir, "feature.md")) {
+	for _, alias := range state.WorkspaceMapFiles()[1:] {
+		if err := copyAliasFile(dir, alias, state.WorkspaceMapFile); err != nil {
+			return fmt.Errorf("copy %s to %s: %w", alias, state.WorkspaceMapFile, err)
+		}
+	}
+	if !regularFileExists(filepath.Join(dir, state.WorkspaceMapFile)) {
 		phase := derivePhase(filepath.Join(dir, state.LedgerFile))
-		if err := state.AtomicWrite(filepath.Join(dir, "feature.md"), []byte(featureIndex(slug, phase)), 0o644); err != nil {
-			return fmt.Errorf("write feature index: %w", err)
+		if err := state.AtomicWrite(filepath.Join(dir, state.WorkspaceMapFile), []byte(workspaceIndex(slug, phase)), 0o644); err != nil {
+			return fmt.Errorf("write workspace index: %w", err)
 		}
 	}
-	if err := copyAliasFile(dir, "evidence.md", "proof.md"); err != nil {
-		return fmt.Errorf("copy evidence.md to proof.md: %w", err)
+	if err := copyAliasFile(dir, "proof.md", state.EvidenceFile); err != nil {
+		return fmt.Errorf("copy proof.md to evidence.md: %w", err)
 	}
-	return copyAliasFile(dir, state.LedgerFile, "status.md")
+	return copyAliasFile(dir, "status.md", state.LedgerFile)
 }
 
 func copyAliasFile(dir, alias, canonical string) error {
@@ -128,8 +133,8 @@ func copyAliasFile(dir, alias, canonical string) error {
 	return state.AtomicWrite(dst, data, 0o644)
 }
 
-// featureIndex renders the manifest added to a normalized workspace.
-func featureIndex(slug string, phase state.Phase) string {
+// workspaceIndex renders the compact map added to a normalized workspace.
+func workspaceIndex(slug string, phase state.Phase) string {
 	return fmt.Sprintf(`---
 slug: %s
 title: %s

package/engine/internal/migrate/migrate_test.go

@@ -1,6 +1,7 @@
 package migrate
 
 import (
+	"os"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -33,8 +34,11 @@ func TestRunNormalizesCanonicalWorkLayout(t *testing.T) {
 	}
 
 	assertFile(t, root, "work/alpha/spec.md", "spec\n")
-	assertFile(t, root, "work/alpha/proof.md", "proof\n")
-	assertFile(t, root, "work/alpha/status.md", "status: done - shipped\n")
+	assertFile(t, root, "work/alpha/evidence.md", "proof\n")
+	assertFile(t, root, "work/alpha/state.md", "status: done - shipped\n")
+	assertFileContains(t, root, "work/alpha/README.md", "phase: done")
+	assertMissing(t, root, "work/alpha/proof.md")
+	assertMissing(t, root, "work/alpha/status.md")
 	assertFile(t, root, "work/alpha/review.md", "review\n")
 
 	f, err := state.LoadFeature(root, "alpha")
@@ -57,8 +61,9 @@ func TestRunNormalizesCanonicalWorkLayout(t *testing.T) {
 
 func TestRunNormalizesLiveFeatureAliases(t *testing.T) {
 	root := t.TempDir()
-	testutil.WriteFile(t, filepath.Join(root, "features/beta/state.md"), "- Phase: prove\n")
-	testutil.WriteFile(t, filepath.Join(root, "features/beta/evidence.md"), "evidence\n")
+	testutil.WriteFile(t, filepath.Join(root, "features/beta/feature.md"), "# Beta\n")
+	testutil.WriteFile(t, filepath.Join(root, "features/beta/status.md"), "- Phase: prove\n")
+	testutil.WriteFile(t, filepath.Join(root, "features/beta/proof.md"), "evidence\n")
 
 	res, err := Run(root)
 	if err != nil {
@@ -67,6 +72,9 @@ func TestRunNormalizesLiveFeatureAliases(t *testing.T) {
 	if got := strings.Join(res.Migrated, ","); got != "beta" {
 		t.Fatalf("Run normalized=%q, want beta", got)
 	}
+	assertFile(t, root, "features/beta/README.md", "# Beta\n")
+	assertFile(t, root, "features/beta/state.md", "- Phase: prove\n")
+	assertFile(t, root, "features/beta/evidence.md", "evidence\n")
 	assertFile(t, root, "features/beta/status.md", "- Phase: prove\n")
 	assertFile(t, root, "features/beta/proof.md", "evidence\n")
 
@@ -111,3 +119,17 @@ func assertFile(t *testing.T, root, rel, want string) {
 		t.Fatalf("%s=%q, want %q", rel, got, want)
 	}
 }
+
+func assertFileContains(t *testing.T, root, rel, want string) {
+	t.Helper()
+	if got := testutil.ReadFile(t, filepath.Join(root, rel)); !strings.Contains(got, want) {
+		t.Fatalf("%s=%q, want it to contain %q", rel, got, want)
+	}
+}
+
+func assertMissing(t *testing.T, root, rel string) {
+	t.Helper()
+	if _, err := os.Stat(filepath.Join(root, rel)); !os.IsNotExist(err) {
+		t.Fatalf("%s exists or stat failed with %v, want missing", rel, err)
+	}
+}

package/engine/internal/state/feature.go

@@ -66,8 +66,8 @@ func featureDir(root, slug string) string {
 
 // ListFeatures returns the slugs of every feature under root — directories under
 // canonical work/ plus compatibility features/ recognized as a feature — sorted.
-// A directory is a feature if it has a manifest (feature.md) OR the working-state
-// ledger (state.md), so a live workspace the pack created without a manifest
+// A directory is a feature if it has a workspace map OR the working-state
+// ledger (state.md), so a live workspace the pack created without a map
 // still lists. Missing layout directories yield an empty list, not an error.
 func ListFeatures(root string) ([]string, error) {
 	seen := map[string]bool{}
@@ -96,11 +96,18 @@ func ListFeatures(root string) ([]string, error) {
 	return slugs, nil
 }
 
-// isFeatureDir reports whether dir is a recognized feature: it carries a manifest
-// or the working-state ledger. Either is a sufficient phase source for LoadFeature.
+// isFeatureDir reports whether dir carries a workspace map or the working-state
+// ledger. Either is a sufficient phase source for LoadFeature.
 func isFeatureDir(dir string) bool {
-	return regularFileExists(filepath.Join(dir, "feature.md")) ||
-		regularFileExists(filepath.Join(dir, LedgerFile))
+	if regularFileExists(filepath.Join(dir, LedgerFile)) {
+		return true
+	}
+	for _, name := range workspaceMapFiles {
+		if regularFileExists(filepath.Join(dir, name)) {
+			return true
+		}
+	}
+	return false
 }
 
 func regularFileExists(path string) bool {
@@ -109,18 +116,25 @@ func regularFileExists(path string) bool {
 }
 
 // LoadFeature reads feature <slug> under root. The phase comes from the live
-// working-state ledger when it declares one, otherwise from feature.md
-// frontmatter. A feature with neither a manifest nor a ledger does not exist.
-// Section content is read from the canonical section files or their transitional
+// working-state ledger when it declares one, otherwise from workspace-map
+// frontmatter. A feature with neither a map nor a ledger does not exist.
+// Section content is read from the canonical section files or their
 // aliases (see sectionFiles).
 func LoadFeature(root, slug string) (*Feature, error) {
 	dir := featureDir(root, slug)
 
-	manifest, mErr := os.ReadFile(filepath.Join(dir, "feature.md"))
-	if mErr != nil && !errors.Is(mErr, os.ErrNotExist) {
-		return nil, fmt.Errorf("feature %q: %w", slug, mErr)
+	var manifest []byte
+	for _, name := range workspaceMapFiles {
+		data, err := os.ReadFile(filepath.Join(dir, name))
+		if err == nil {
+			manifest = data
+			break
+		}
+		if !errors.Is(err, os.ErrNotExist) {
+			return nil, fmt.Errorf("feature %q: read %s: %w", slug, name, err)
+		}
 	}
-	hasManifest := mErr == nil
+	hasManifest := manifest != nil
 	hasLedger := regularFileExists(filepath.Join(dir, LedgerFile))
 	if !hasManifest && !hasLedger {
 		return nil, fmt.Errorf("feature %q not found", slug)
@@ -150,7 +164,7 @@ func LoadFeature(root, slug string) (*Feature, error) {
 		phase = manifestPhase
 	}
 	if phase == "" {
-		return nil, fmt.Errorf("feature %q: no phase in feature.md frontmatter or %s ledger", slug, LedgerFile)
+		return nil, fmt.Errorf("feature %q: no phase in workspace-map frontmatter or %s ledger", slug, LedgerFile)
 	}
 	if !KnownPhase(phase) {
 		return nil, fmt.Errorf("feature %q: unknown phase %q", slug, phase)

package/engine/internal/state/schema.go

@@ -3,11 +3,23 @@ package state
 //go:generate go run ./cmd/workflowmanifest -out workflow_manifest.json
 
 // SchemaVersion is the .devrites state-schema version this engine understands.
-// A feature.md may declare its own schemaVersion in frontmatter; the engine
+// A workspace map may declare its own schemaVersion in frontmatter; the engine
 // refuses a version newer than this (see LoadFeature) and otherwise reads the
 // files, which evolve additively.
 const SchemaVersion = 1
 
+const (
+	WorkspaceMapFile = "README.md"
+	EvidenceFile     = "evidence.md"
+)
+
+var workspaceMapFiles = []string{WorkspaceMapFile, "feature.md", "index.md"}
+
+// WorkspaceMapFiles returns the canonical workspace map followed by readable aliases.
+func WorkspaceMapFiles() []string {
+	return append([]string(nil), workspaceMapFiles...)
+}
+
 // Section is one single-concern completeness file within a feature directory.
 // Splitting a feature into small files (rather than one long document) keeps
 // each file context-cheap and makes completeness self-evident.
@@ -33,23 +45,23 @@ var Sections = []Section{
 }
 
 // sectionFiles lists the filenames that can satisfy each section, canonical name
-// first, then the transitional aliases the live pack still writes — the same
-// mapping `devrites-engine migrate` normalizes (evidence→proof, state→status). A section
+// first, then supported aliases — the same mapping `devrites-engine migrate`
+// normalizes (proof→evidence, status→state). A section
 // counts as present if ANY of its files has real content, so the engine reads a
-// live workspace before the pack sweep converges the filenames. The manifest
-// (feature.md) is not a section; it is handled separately in LoadFeature.
+// live workspace before the pack sweep converges the filenames. The workspace
+// map is not a section; it is handled separately in LoadFeature.
 var sectionFiles = map[Section][]string{
 	SectionSpec:      {"spec.md"},
 	SectionPlan:      {"plan.md"},
 	SectionDecisions: {"decisions.md"},
 	SectionTasks:     {"tasks.md"},
-	SectionProof:     {"proof.md", "evidence.md"},
-	SectionStatus:    {"status.md", "state.md"},
+	SectionProof:     {EvidenceFile, "proof.md"},
+	SectionStatus:    {"state.md", "status.md"},
 }
 
 // LedgerFile is the working-state ledger the live pack writes. It carries the
 // phase in its canonical cursor table (legacy "- Phase: <p>" remains readable)
-// when no feature.md manifest declares one, and it satisfies the status section.
+// when no workspace map declares one, and it satisfies the status section.
 const LedgerFile = "state.md"
 
 // Phase is a workflow state. The order mirrors the rite-* arc.

package/engine/internal/state/state_test.go

@@ -138,9 +138,9 @@ func writeWorkSection(t *testing.T, root, slug, name, body string) {
 	}
 }
 
-// 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.
+// A live workspace map need not carry frontmatter: the phase lives in
+// the canonical state.md ledger and the proof/status concepts are satisfied by
+// 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")
@@ -148,7 +148,7 @@ func TestLoadFeatureFromLedgerAndAliases(t *testing.T) {
 	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
+	writeSection(t, root, "live", "evidence.md", "# Evidence\n\nTests pass.\n")
 
 	rep, err := Status(root, "live")
 	if err != nil {
@@ -158,10 +158,10 @@ func TestLoadFeatureFromLedgerAndAliases(t *testing.T) {
 		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")
+		t.Error("proof section should be present via canonical evidence.md")
 	}
 	if !rep.Present[SectionStatus] {
-		t.Error("status section should be present via its state.md alias")
+		t.Error("status section should be present via canonical state.md")
 	}
 	if !rep.Complete() {
 		t.Errorf("prove-phase feature should be complete, missing: %v", rep.Missing)

package/engine/tests/budget_test.go

@@ -7,8 +7,8 @@ import (
 
 // TestStatusLiveWorkspace is the P2 acceptance check: `devrites-engine status <slug>`
 // must report a canonical work/<slug> feature the live pack created without a
-// feature.md manifest — phase from the state.md ledger, proof/status via their
-// evidence.md/state.md aliases. Before the schema unification this returned
+// 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
 // "feature not found".
 func TestStatusLiveWorkspace(t *testing.T) {
 	work := t.TempDir()

package/engine/tests/meta_test.go

@@ -1,7 +1,7 @@
 package main_test
 
-// Cross-cutting assertions the spec calls out explicitly: the engine makes zero
-// network calls, and the inline fail-open guard no-ops when the binary is absent.
+// Cross-cutting assertions: network I/O stays inside the one sanctioned package,
+// and the inline fail-open guard no-ops when the binary is absent.
 
 import (
 	"bytes"
@@ -11,7 +11,7 @@ import (
 )
 
 // TestFirstPartyMakesNoNetworkCalls asserts that no first-party package imports a
-// network client EXCEPT internal/iohooks — the ONE sanctioned network surface,
+// network client EXCEPT internal/iohooks — the one sanctioned network surface,
 // where the source-citation cache does conditional-HEAD revalidation. Confining
 // network to that single, auditable package keeps the rest of the engine a
 // network-free control plane that makes zero model calls (PRD: "zero API"). The