devrites 4.6.0 → 5.0.0

package/docs/usage.md

@@ -8,6 +8,7 @@ lifecycle. Workspace phases first read the active workspace from
 command that can create or select one. `/rite-upgrade [slug]` is the
 compatibility audit for an older active workspace that cannot resume.
 
+- **First install** → [README Quick start](../README.md#quick-start) (`npx devrites@latest`)
 - **Full command reference** → [`command-map.md`](command-map.md)
 - **Flow diagrams** → [`flow.md`](flow.md)
 - **Architecture rationale** → [`architecture.md`](architecture.md)
@@ -61,7 +62,7 @@ preservation-first audit: age/cursor encoding alone is not a defect, and only a
 cited current-contract failure routes repair through its phase owner. Completed
 work and evidence stay intact. Candidate defects may route current Prove,
 Polish, Review, and Seal in that order; old passes are never synthesized. The
-engine has no structural migration command.
+engine owns deterministic v5 schema normalization.
 
 Project-root sentinel (outside the workspace):
 

package/engine/.golangci.yml

@@ -0,0 +1,27 @@
+# golangci-lint v2 — curated complement to the existing strict gates
+# (staticcheck, govulncheck, gosec). Enables only checkers that add findings
+# staticcheck does not produce; see the engine job in ci.yml and `make lint`.
+version: "2"
+
+linters:
+  default: none
+  enable:
+    # Unchecked error returns: staticcheck does not flag ignored errors.
+    - errcheck
+    # Assignments never read: distinct from staticcheck's unused analysis.
+    - ineffassign
+  settings:
+    errcheck:
+      # The engine's CLI boundary reports via exit paths, not error returns;
+      # writes to the operator's stdout/stderr streams fail only on closed
+      # writers.
+      exclude-functions:
+        - fmt.Fprint
+        - fmt.Fprintf
+        - fmt.Fprintln
+        - (*bytes.Buffer).WriteByte
+        - (*strings.Builder).WriteByte
+        - (*strings.Builder).WriteString
+
+formatters:
+  default: none

package/engine/AGENTS.md

@@ -0,0 +1,24 @@
+# Engine control plane
+
+This directory is the deterministic Go control plane. Native skills and agents
+own semantic judgment; this binary owns structure, identity, and ID-reference
+completeness.
+
+## Invariants
+
+- Build with `CGO_ENABLED=0`. The hot path is stdlib-only (no CLI framework,
+  no model client). Workspace policy, state, proof, and install-application
+  packages stay network-free. Direct `devrites-engine update` is the bounded,
+  checksummed exception (ADR-0008, ADR-0024, ADR-0028).
+- Date-derived `resolve` output reads the clock through `DEVRITES_NOW`
+  (RFC-3339 or `YYYY-MM-DD`). Operational timestamps (leases, install
+  manifests) use wall time by design (ADR-0006).
+- `check readiness` / `check seal` do not parse reviewer prose or infer
+  coverage quality. They may require that a canonical `AC-###` ID declared in
+  `spec.md` also appears as a literal substring in `tasks.md` and
+  `test-plan.md` when those artifacts are required.
+- Local full gate: `make quality` (`gofmt`, `go vet`, `staticcheck`,
+  `govulncheck`, `gosec`, `golangci-lint`, `osv-scanner`,
+  `go test -race -shuffle=on -count=1`).
+
+See [`../CONTEXT.md`](../CONTEXT.md) and [`../docs/adr/README.md`](../docs/adr/README.md).

package/engine/Makefile

@@ -4,14 +4,18 @@ GOFILES := $(shell find . -name '*.go' -not -path './$(DIST)/*')
 # darwin/amd64 kept for Intel Macs; the five targets the release matrix ships.
 PLATFORMS := darwin/arm64 darwin/amd64 linux/amd64 linux/arm64 windows/amd64
 
-.PHONY: build fmt-check test test-race vet quality staticcheck govulncheck gosec cover crosscompile clean
+.PHONY: build fmt-check test test-race vet quality staticcheck govulncheck gosec lint cover crosscompile clean
 
 STATICCHECK_VERSION := 2026.1
 GOVULNCHECK_VERSION := v1.6.0
 GOSEC_VERSION := v2.28.0
+GOLANGCI_VERSION := v2.13.2
+OSV_SCANNER_VERSION := v2.5.1
 STATICCHECK := go run honnef.co/go/tools/cmd/staticcheck@$(STATICCHECK_VERSION)
 GOVULNCHECK := go run golang.org/x/vuln/cmd/govulncheck@$(GOVULNCHECK_VERSION)
 GOSEC := go run github.com/securego/gosec/v2/cmd/gosec@$(GOSEC_VERSION)
+GOLANGCI := go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@$(GOLANGCI_VERSION)
+OSV_SCANNER := go run github.com/google/osv-scanner/v2/cmd/osv-scanner@$(OSV_SCANNER_VERSION)
 
 build:
 	CGO_ENABLED=0 go build -o $(BINARY) .
@@ -20,18 +24,18 @@ fmt-check:
 	@test -z "$$(gofmt -l $(GOFILES))" || (echo "gofmt required:"; gofmt -l $(GOFILES); exit 1)
 
 test:
-	go test ./...
+	go test -shuffle=on ./...
 
 # Race-enabled run for concurrent state paths and mutable test clients.
 test-race:
-	go test -race -count=1 ./...
+	go test -race -shuffle=on -count=1 ./...
 
 vet:
 	go vet ./...
 
 # quality is the full local gate. Mirror it in CI so a green `make quality`
 # means a green pipeline (the date-sensitive parity golden aside; see ADR-0006).
-quality: fmt-check vet staticcheck govulncheck gosec test-race
+quality: fmt-check vet staticcheck govulncheck gosec lint osv test-race
 
 staticcheck:
 	$(STATICCHECK) ./...
@@ -39,8 +43,19 @@ staticcheck:
 govulncheck:
 	$(GOVULNCHECK) ./...
 
+# No rule-class exclusions: G204/G304/G702/G703 sites carry per-call
+# `// #nosec GXXX -- <justification>` annotations in the source, so a genuinely
+# new injection or traversal sink fails this target.
 gosec:
-	$(GOSEC) -conf .gosec.json -exclude=G204,G304,G702,G703 ./...
+	$(GOSEC) -conf .gosec.json ./...
+
+# Curated complement to staticcheck (errcheck + ineffassign; .golangci.yml).
+lint:
+	$(GOLANGCI) run ./...
+
+# OSV.dev dependency scanner (mirrors CI dependency gate).
+osv:
+	$(OSV_SCANNER) scan --config ../osv-scanner.toml --lockfile go.mod
 
 # Coverage baseline. No hard floor is wired yet (see ADR-0006): the number is
 # understated because most engine behaviour is exercised through CLI-level

package/engine/cmd/releasepack/main.go

@@ -81,7 +81,7 @@ func writeArchive(root, output, prefix string, epoch time.Time) error {
 	if err != nil {
 		return fmt.Errorf("open staged release tree: %w", err)
 	}
-	defer sourceRoot.Close()
+	defer func() { _ = sourceRoot.Close() }()
 
 	entries, err := collectEntries(sourceRoot, prefix)
 	if err != nil {
@@ -96,7 +96,7 @@ func writeArchive(root, output, prefix string, epoch time.Time) error {
 		return fmt.Errorf("create temporary archive: %w", err)
 	}
 	tmpName := tmp.Name()
-	defer os.Remove(tmpName)
+	defer func() { _ = os.Remove(tmpName) }()
 	if err := tmp.Chmod(0o644); err != nil {
 		return errors.Join(fmt.Errorf("set archive mode: %w", err), tmp.Close())
 	}

package/engine/cmd/releasepack/main_test.go

@@ -103,7 +103,7 @@ func TestWriteEntriesRejectsChangedSource(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	defer sourceRoot.Close()
+	defer func() { _ = sourceRoot.Close() }()
 	entries, err := collectEntries(sourceRoot, "devrites-v1")
 	if err != nil {
 		t.Fatal(err)
@@ -138,7 +138,7 @@ func TestWriteEntriesRejectsEscapingSymlinkSwap(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	defer sourceRoot.Close()
+	defer func() { _ = sourceRoot.Close() }()
 	entries, err := collectEntries(sourceRoot, "devrites-v1")
 	if err != nil {
 		t.Fatal(err)
@@ -199,12 +199,12 @@ func readArchive(t *testing.T, archivePath string, epoch time.Time) archiveConte
 	if err != nil {
 		t.Fatal(err)
 	}
-	defer file.Close()
+	defer func() { _ = file.Close() }()
 	gz, err := gzip.NewReader(file)
 	if err != nil {
 		t.Fatal(err)
 	}
-	defer gz.Close()
+	defer func() { _ = gz.Close() }()
 	if !gz.ModTime.Equal(epoch) || gz.OS != 255 || gz.Name != "" || gz.Comment != "" || len(gz.Extra) != 0 {
 		t.Fatalf("gzip header is not normalized: %#v", gz.Header)
 	}

package/engine/commands.go

@@ -17,6 +17,7 @@ const (
 	rootUnused rootMode = iota
 	rootLenient
 	rootStrict
+	rootStrictUsage
 )
 
 // rootModeFor is the single policy boundary between diagnostic/read-only
@@ -34,6 +35,24 @@ func rootModeFor(command string, args []string) rootMode {
 			return rootStrict
 		}
 		return rootUnused
+	case "migrate":
+		return rootStrictUsage
+	case "check":
+		switch subcommand {
+		case "candidate", "readiness", "seal", "task-graph":
+			return rootStrictUsage
+		case "indexes":
+			return rootLenient
+		}
+		return rootUnused
+	case "orient":
+		return rootStrictUsage
+	case "observe":
+		switch subcommand {
+		case "summary":
+			return rootStrictUsage
+		}
+		return rootUnused
 	default:
 		return rootUnused
 	}
@@ -67,6 +86,14 @@ func resolveRootFor(command string, args []string) (string, int, error) {
 			return fallbackRoot(), exitOK, nil
 		}
 		return "", exitUsage, err
+	case rootStrictUsage:
+		root, err := state.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
+		if err != nil {
+			// Workspace-requiring read/check commands have always mapped every
+			// resolution failure to the usage exit code.
+			return "", exitUsage, err
+		}
+		return root, exitOK, nil
 	default:
 		panic("unknown root resolution mode")
 	}

package/engine/internal/devritespaths/paths.go

@@ -15,8 +15,10 @@ const (
 
 	ClaudeSkillsTarget    = ".claude/skills"
 	CodexSkillsTarget     = ".agents/skills"
+	OmpSkillsTarget       = ".omp/skills"
 	ClaudeAgentsTarget    = ".claude/agents"
 	CodexAgentsTarget     = ".codex/agents"
+	OmpAgentsTarget       = ".omp/agents"
 	ClaudeWorkflowsTarget = ".claude/workflows"
 
 	ManifestName = ".claude/devrites.manifest"
@@ -175,6 +177,7 @@ func ActiveSlug(root string) (string, error) {
 	if info, err := os.Lstat(activePath); err == nil && info.Mode()&os.ModeSymlink != 0 {
 		return "", fmt.Errorf("DRV-ACTIVE-SYMLINK: ACTIVE is a symlink; run `rm -f %q`", activePath)
 	}
+	// #nosec G304 -- operator-supplied workspace root; ACTIVE symlink refused above
 	raw, err := os.ReadFile(activePath)
 	if errors.Is(err, os.ErrNotExist) {
 		return "", nil

package/engine/internal/fsutil/copy.go

@@ -84,6 +84,7 @@ func CopyTree(src, dst string) error {
 		return fmt.Errorf("copy %s: %w", src, err)
 	}
 	if !info.IsDir() {
+		// #nosec G304 -- src is an engine-managed path inside the operator-supplied root
 		data, err := os.ReadFile(src)
 		if err != nil {
 			return fmt.Errorf("copy %s: %w", src, err)
@@ -91,6 +92,7 @@ func CopyTree(src, dst string) error {
 		if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
 			return fmt.Errorf("copy to %s: %w", dst, err)
 		}
+		// #nosec G703 -- dst mirrors src within the same managed tree
 		return os.WriteFile(dst, data, 0o644)
 	}
 	entries, err := os.ReadDir(src)

package/engine/internal/fsutil/copy_test.go

@@ -0,0 +1,193 @@
+package fsutil
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestWriteFileAtomicWritesAndOverwrites(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "nested", "file.txt")
+	if err := WriteFileAtomic(path, []byte("first\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(got) != "first\n" {
+		t.Fatalf("content %q", got)
+	}
+	if !PermissionsMatch(mustMode(t, path), 0o644) {
+		t.Fatalf("perm %v", mustMode(t, path))
+	}
+	// Overwrite in place.
+	if err := WriteFileAtomic(path, []byte("second\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if got, _ := os.ReadFile(path); string(got) != "second\n" {
+		t.Fatalf("content after overwrite %q", got)
+	}
+	// No temp files left behind.
+	entries, err := os.ReadDir(filepath.Dir(path))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, e := range entries {
+		if name := e.Name(); name != "file.txt" && name != "nested" {
+			t.Fatalf("temp file left behind: %s", name)
+		}
+	}
+}
+
+func mustMode(t *testing.T, path string) os.FileMode {
+	t.Helper()
+	info, err := os.Stat(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return info.Mode()
+}
+
+func TestFileModTime(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "file.txt")
+	if err := os.WriteFile(path, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	modified, ok := FileModTime(path)
+	if !ok {
+		t.Fatal("regular file should report mod time")
+	}
+	if modified <= 0 {
+		t.Fatalf("mod time %d", modified)
+	}
+	if _, ok := FileModTime(filepath.Join(dir, "missing.txt")); ok {
+		t.Fatal("missing file should report !ok")
+	}
+	if _, ok := FileModTime(dir); ok {
+		t.Fatal("directory should report !ok")
+	}
+}
+
+func TestNewestModTime(t *testing.T) {
+	dir := t.TempDir()
+	old := filepath.Join(dir, "old.txt")
+	new := filepath.Join(dir, "new.txt")
+	if err := os.WriteFile(old, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(new, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	future := time.Now().Add(2 * time.Hour)
+	if err := os.Chtimes(new, future, future); err != nil {
+		t.Skipf("cannot set file times on this platform: %v", err)
+	}
+	newest, ok := NewestModTime(old, new)
+	if !ok {
+		t.Fatal("expected ok")
+	}
+	want, _ := FileModTime(new)
+	if newest != want {
+		t.Fatalf("newest=%d want %d", newest, want)
+	}
+	if _, ok := NewestModTime(filepath.Join(dir, "missing.txt")); ok {
+		t.Fatal("missing-only inputs should report !ok")
+	}
+}
+
+func TestCopyTreeMissingSourceIsNoOp(t *testing.T) {
+	dir := t.TempDir()
+	dst := filepath.Join(dir, "dst")
+	if err := CopyTree(filepath.Join(dir, "missing"), dst); err != nil {
+		t.Fatalf("missing src must not error: %v", err)
+	}
+	if _, err := os.Stat(dst); !os.IsNotExist(err) {
+		t.Fatalf("dst must not be created, got %v", err)
+	}
+}
+
+func TestCopyTreeFileAndTree(t *testing.T) {
+	dir := t.TempDir()
+	src := filepath.Join(dir, "src")
+	if err := os.MkdirAll(filepath.Join(src, "sub"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(src, "root.txt"), []byte("root\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(src, "sub", "leaf.txt"), []byte("leaf\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	dst := filepath.Join(dir, "dst")
+	if err := CopyTree(src, dst); err != nil {
+		t.Fatal(err)
+	}
+	for rel, want := range map[string]string{
+		"root.txt":     "root\n",
+		"sub/leaf.txt": "leaf\n",
+	} {
+		got, err := os.ReadFile(filepath.Join(dst, filepath.FromSlash(rel)))
+		if err != nil {
+			t.Fatalf("%s: %v", rel, err)
+		}
+		if string(got) != want {
+			t.Fatalf("%s: %q want %q", rel, got, want)
+		}
+	}
+
+	// Copying a single file copies its contents.
+	single := filepath.Join(dir, "single.txt")
+	if err := os.WriteFile(single, []byte("one\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	singleDst := filepath.Join(dir, "single-copy.txt")
+	if err := CopyTree(single, singleDst); err != nil {
+		t.Fatal(err)
+	}
+	if got, _ := os.ReadFile(singleDst); string(got) != "one\n" {
+		t.Fatalf("single copy %q", got)
+	}
+
+	// Recopying overwrites existing files.
+	if err := os.WriteFile(filepath.Join(src, "root.txt"), []byte("changed\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := CopyTree(src, dst); err != nil {
+		t.Fatal(err)
+	}
+	if got, _ := os.ReadFile(filepath.Join(dst, "root.txt")); string(got) != "changed\n" {
+		t.Fatalf("overwrite %q", got)
+	}
+}
+
+func TestPermissionsMatch(t *testing.T) {
+	if !PermissionsMatch(0o644, 0o644) {
+		t.Fatal("matching perms must match")
+	}
+	if runtime.GOOS != "windows" && PermissionsMatch(0o600, 0o644) {
+		t.Fatal("differing POSIX perms must not match")
+	}
+}
+
+func TestWriteFileAtomicSurfacesFailure(t *testing.T) {
+	dir := t.TempDir()
+	blocker := filepath.Join(dir, "blocker")
+	if err := os.WriteFile(blocker, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// The parent path is an existing file, so creating the destination
+	// directory must fail and the error must surface to the caller.
+	err := WriteFileAtomic(filepath.Join(blocker, "nested", "file.txt"), []byte("x"), 0o644)
+	if err == nil {
+		t.Fatal("expected the write failure to surface")
+	}
+	if !strings.Contains(err.Error(), "atomic write") {
+		t.Fatalf("error should identify the operation, got %v", err)
+	}
+}

package/engine/internal/gate/gate.go

@@ -103,6 +103,12 @@ func checkObservation(kind Kind, observation *state.WorkspaceObservation) (*Resu
 			}
 		}
 	}
+	if len(missingFiles) == 0 {
+		for _, problem := range acceptanceMapProblems(observation, policy) {
+			stateProblems = append(stateProblems, "acceptance-map: "+problem)
+			blocked = true
+		}
+	}
 	if len(missingFiles) == 0 && phaseRequiresReadinessBinding(policy) {
 		expected, bindingErr := verifyReadinessBinding(observation)
 		if bindingErr != nil {
@@ -136,6 +142,30 @@ func checkObservation(kind Kind, observation *state.WorkspaceObservation) (*Resu
 	return result, nil
 }
 
+func acceptanceMapProblems(observation *state.WorkspaceObservation, policy state.PhasePolicy) []string {
+	requireTasks := phaseRequiresTasks(policy)
+	requireTestPlan := phaseRequiresTestPlan(policy)
+	if !requireTasks && !requireTestPlan {
+		return nil
+	}
+	spec, ok := observation.Fact("spec.md")
+	if !ok || spec.State() != state.ArtifactPresent {
+		return nil
+	}
+	var tasks, testPlan []byte
+	if requireTasks {
+		if fact, ok := observation.Fact("tasks.md"); ok && fact.State() == state.ArtifactPresent {
+			tasks = fact.Bytes()
+		}
+	}
+	if requireTestPlan {
+		if fact, ok := observation.Fact("test-plan.md"); ok && fact.State() == state.ArtifactPresent {
+			testPlan = fact.Bytes()
+		}
+	}
+	return state.ParseAcceptanceMap(spec.Bytes(), tasks, testPlan, requireTasks, requireTestPlan).Problems
+}
+
 func missingSections(observation *state.WorkspaceObservation, required []state.Section) []state.Section {
 	var missing []state.Section
 	for _, section := range required {

package/engine/internal/gate/gate_test.go

@@ -123,7 +123,7 @@ Goal: looks complete without an ordering field
 func TestCheckAndRenderReadiness(t *testing.T) {
 	root := t.TempDir()
 	writeFeature(t, root, "alpha", map[string]string{
-		"state.md":             "- Phase: build\n",
+		"state.md":             "- Phase: build\n- Schema: 3\n",
 		"brief.md":             "brief\n",
 		"spec.md":              "real spec\n",
 		"assumptions.md":       "none\n",
@@ -164,7 +164,7 @@ func TestCheckAndRenderReadiness(t *testing.T) {
 func TestCheckUsesConcreteWorkspaceRequirements(t *testing.T) {
 	root := t.TempDir()
 	files := map[string]string{
-		"state.md":             "| phase | vet |\n",
+		"state.md":             "| phase | vet |\n| schema | 3 |\n",
 		"brief.md":             "brief\n",
 		"spec.md":              "spec\n",
 		"decisions.md":         "decisions\n",
@@ -192,7 +192,7 @@ func TestCheckUsesConcreteWorkspaceRequirements(t *testing.T) {
 func TestSealRequiresDurableReviewAndSealArtifacts(t *testing.T) {
 	root := t.TempDir()
 	files := map[string]string{
-		"state.md":             "| phase | seal |\n",
+		"state.md":             "| phase | seal |\n| schema | 3 |\n",
 		"brief.md":             "brief\n",
 		"spec.md":              "spec\n",
 		"decisions.md":         "decisions\n",
@@ -373,7 +373,7 @@ func TestCheckBlocksOpenHumanQuestions(t *testing.T) {
 		t.Run(tc.name, func(t *testing.T) {
 			root := t.TempDir()
 			writeFeature(t, root, "alpha", map[string]string{
-				"state.md":     "- Phase: build\n- Status: " + tc.status + "\n",
+				"state.md":     "- Phase: build\n- Status: " + tc.status + "\n- Schema: 3\n",
 				"spec.md":      "spec\n",
 				"plan.md":      "plan\n",
 				"decisions.md": "decisions\n",
@@ -412,7 +412,7 @@ func TestCheckUsesWorkspaceOverrideForStateInvariants(t *testing.T) {
 	override := filepath.Join(physicalRoot, "work", "alpha")
 	t.Setenv("DEVRITES_WORKSPACE", override)
 	testutil.WriteFile(t, filepath.Join(override, "README.md"), "---\nphase: spec\nschemaVersion: 1\n---\n")
-	testutil.WriteFile(t, filepath.Join(override, "state.md"), "- Phase: build\n- Status: running\n")
+	testutil.WriteFile(t, filepath.Join(override, "state.md"), "- Phase: build\n- Status: running\n- Schema: 3\n")
 	testutil.WriteFile(t, filepath.Join(override, "spec.md"), "spec\n")
 	testutil.WriteFile(t, filepath.Join(override, "questions.md"), "## q-1\nstatus: open\ngate: blocking\n")
 
@@ -443,7 +443,7 @@ func TestCheckObservationUsesRetainedPhaseQuestionsReadinessAndReview(t *testing
 	if err != nil {
 		t.Fatal(err)
 	}
-	testutil.WriteFile(t, filepath.Join(workspace, "state.md"), "- Phase: spec\n- Status: running\n")
+	testutil.WriteFile(t, filepath.Join(workspace, "state.md"), "- Phase: spec\n- Status: running\n- Schema: 3\n")
 	testutil.WriteFile(t, filepath.Join(workspace, "questions.md"), "## q-1\nstatus: open\ngate: blocking\n")
 	testutil.WriteFile(t, filepath.Join(workspace, "plan.md"), "# Plan\n\nChanged after observation.\n")
 	testutil.WriteFile(t, filepath.Join(workspace, "eng-review.md"), "# Engineering review\n\nNo binding.\n")
@@ -609,7 +609,7 @@ func writeCompleteGateFeature(t *testing.T, root, slug string, current, required
 		content := "# " + name + "\n\nreal\n"
 		switch name {
 		case "state.md":
-			content = "- Phase: " + string(current) + "\n- Status: running\n"
+			content = "- Phase: " + string(current) + "\n- Status: running\n- Schema: 3\n"
 		case "questions.md":
 			questionsRequired = true
 			content = questions

package/engine/internal/gate/readiness_binding.go

@@ -149,17 +149,20 @@ func readinessDiagnosticError(diagnostic state.ArtifactDiagnostic) error {
 }
 
 func phaseRequiresTasks(policy state.PhasePolicy) bool {
-	for _, artifact := range policy.RequiredArtifacts {
-		if artifact == "tasks.md" {
-			return true
-		}
-	}
-	return false
+	return policyRequires(policy, "tasks.md")
+}
+
+func phaseRequiresTestPlan(policy state.PhasePolicy) bool {
+	return policyRequires(policy, "test-plan.md")
 }
 
 func phaseRequiresReadinessBinding(policy state.PhasePolicy) bool {
+	return policyRequires(policy, "eng-review.md")
+}
+
+func policyRequires(policy state.PhasePolicy, name state.ArtifactPath) bool {
 	for _, artifact := range policy.RequiredArtifacts {
-		if artifact == "eng-review.md" {
+		if artifact == name {
 			return true
 		}
 	}

package/engine/internal/gate/readiness_binding_test.go

@@ -77,7 +77,13 @@ func TestReadinessBindingBindsOnlyStableBuildInputs(t *testing.T) {
 	}
 
 	for _, name := range []string{"state.md", "questions.md", "decisions.md", "assumptions.md", "eng-review.md", "evidence.md", "review.md", "seal.md", "handoff.md", "ambient.md"} {
-		testutil.WriteFile(t, filepath.Join(workspace, name), "# Mutable\n\nChanged outside the stable contract.\n")
+		// state.md stays a valid v5 workspace when mutated: the schema row is
+		// part of the contract, not part of the bound inputs.
+		body := "# Mutable\n\nChanged outside the stable contract.\n"
+		if name == "state.md" {
+			body = "| phase | build |\n| schema | 3 |\n" + body
+		}
+		testutil.WriteFile(t, filepath.Join(workspace, name), body)
 		if got := mustReadinessBinding(t, root, "stable"); got != baseline {
 			t.Fatalf("excluded %s altered binding", name)
 		}
@@ -91,7 +97,7 @@ func TestReadinessBindingBindsOnlyStableBuildInputs(t *testing.T) {
 func TestReadinessBindingGoldenDigest(t *testing.T) {
 	root := t.TempDir()
 	writeReadinessFixture(t, root, "golden", "build")
-	const want = "Readiness inputs SHA-256: c4a073e85373f5fd9f9302c61b6772e766e4fa2a3da2ccc77bad23756c9f412d"
+	const want = "Readiness inputs SHA-256: 6a0d4991d86f5a0e78333289840b5fb1a123adbb18b53243b1af34fcffcf1961"
 	if got := mustReadinessBinding(t, root, "golden"); got != want {
 		t.Fatalf("ReadinessBinding()=%q, want %q", got, want)
 	}
@@ -361,11 +367,53 @@ func TestReadinessDiagnosticPayloads(t *testing.T) {
 	}
 }
 
+func TestCheckReadinessBlocksUnmappedAcceptance(t *testing.T) {
+	root := t.TempDir()
+	workspace := writeReadinessFixture(t, root, "unmapped", "build")
+	testutil.WriteFile(t, filepath.Join(workspace, "spec.md"), "# Spec\n\n## Acceptance criteria\n- AC-002: extra requirement.\n")
+	binding := mustReadinessBinding(t, root, "unmapped")
+	testutil.AppendFile(t, filepath.Join(workspace, "eng-review.md"), "\n"+binding+"\n")
+
+	result, err := Check(Readiness, root, "unmapped")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !result.Blocked || result.ReasonID != reason.GateReadinessMissing {
+		t.Fatalf("blocked=%v reason=%q render=%s", result.Blocked, result.ReasonID, result.Render())
+	}
+	joined := strings.Join(result.StateProblems, "\n")
+	for _, want := range []string{
+		"acceptance-map: acceptance AC-002 is not referenced in tasks.md",
+		"acceptance-map: acceptance AC-002 is not referenced in test-plan.md",
+	} {
+		if !strings.Contains(joined, want) {
+			t.Fatalf("missing %q in %q", want, joined)
+		}
+	}
+}
+
+func TestCheckReadinessPassesMappedAcceptance(t *testing.T) {
+	root := t.TempDir()
+	workspace := writeReadinessFixture(t, root, "mapped", "build")
+	testutil.WriteFile(t, filepath.Join(workspace, "spec.md"), "# Spec\n\n## Acceptance criteria\n- AC-001: bind readiness inputs.\n")
+	testutil.WriteFile(t, filepath.Join(workspace, "test-plan.md"), "# Test plan\n\nAC-001 focused tests.\n")
+	binding := mustReadinessBinding(t, root, "mapped")
+	testutil.AppendFile(t, filepath.Join(workspace, "eng-review.md"), "\n"+binding+"\n")
+
+	result, err := Check(Readiness, root, "mapped")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Blocked {
+		t.Fatalf("mapped acceptance blocked: %s", result.Render())
+	}
+}
+
 func writeReadinessFixture(t *testing.T, root, slug, phase string) string {
 	t.Helper()
 	workspace := filepath.Join(root, "work", slug)
 	for name, body := range map[string]string{
-		"state.md":             "| phase | " + phase + " |\n",
+		"state.md":             "| phase | " + phase + " |\n| schema | 3 |\n",
 		"brief.md":             "# Brief\n\nReady.\n",
 		"spec.md":              "# Spec\n\nReady.\n",
 		"decisions.md":         "# Decisions\n\nNone.\n",