devrites 4.5.0 → 4.7.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [4.7.0](https://github.com/ViktorsBaikers/DevRites/compare/v4.6.0...v4.7.0) (2026-08-30)
+
+### Added
+
+* **devrites:** markdown knowledge-layer round 5 and engine v5 slate ([#49](https://github.com/ViktorsBaikers/DevRites/issues/49)) ([2ef8e9a](https://github.com/ViktorsBaikers/DevRites/commit/2ef8e9a20c750d37f506d6ed0fbcd6bce74fce55))
+
+## [4.6.0](https://github.com/ViktorsBaikers/DevRites/compare/v4.5.0...v4.6.0) (2026-08-28)
+
+### Added
+
+* **skills:** markdown knowledge-layer round 4 ([#48](https://github.com/ViktorsBaikers/DevRites/issues/48)) ([9dab7af](https://github.com/ViktorsBaikers/DevRites/commit/9dab7af644c219ab3f3411b4a701947b9da9108b))
+
 ## [4.5.0](https://github.com/ViktorsBaikers/DevRites/compare/v4.4.2...v4.5.0) (2026-08-27)
 
 ### Added

package/NOTICE.md

@@ -7,19 +7,6 @@ The Nielsen heuristics 0–4 scoring rubric in
 `pack/.claude/skills/rite-review/reference/nielsen-heuristics.md` references the heuristics themselves
 (Jakob Nielsen, 1994 / 2020 — public usability canon).
 
-## Research attribution (2026-08-27 instruction upgrade)
-
-The 2026-08-27 Markdown methodology round adapted *concepts* (not text) from external,
-untrusted-at-research-time repositories. Adaptations below are rewritten in DevRites language;
-no upstream prose ships in this pack.
-
-- [rebelytics/one-skill-to-rule-them-all](https://github.com/rebelytics/one-skill-to-rule-them-all) — CC BY 4.0: its capture/promotion/self-improvement loop **structure** informed `rite-learn` and `devrites-retrospector` guardrails (qualification contract, consolidation duty, growth cap, rejection persistence). Attribution required by license and hereby given.
-- [mukul975/Anthropic-Cybersecurity-Skills](https://github.com/mukul975/Anthropic-Cybersecurity-Skills) — Apache 2.0: its change-type→domain routing shape and co-located framework-identifier binding method informed `standards/security.md`. Concept-level adaptation; catalog not imported.
-- [pbakaus/impeccable](https://github.com/pbakaus/impeccable) — Apache 2.0: earlier derivative material remains in-tree; this round's Verify-vs-Refuse framing influenced the browser-proof checklist rewrite. Concept-level adaptation.
-- [netresearch/file-search-skill](https://github.com/netresearch/file-search-skill) — MIT AND CC BY-SA 4.0: only the *idea* of a question-type→tool matrix was used; `standards/tooling.md`'s table was rebuilt natively from DevRites tools (no structural transplant, honoring share-alike).
-- [Nutlope/hallmark](https://github.com/Nutlope/hallmark), [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill), [educlopez/ui-craft](https://github.com/educlopez/ui-craft), [Weizhena/Deep-Research-skills](https://github.com/Weizhena/Deep-Research-skills) — MIT: viewport/state-capture checks, mechanical slop counters, coverage markers, and research checkpoint ideas, adapted concept-level.
-
-
 ## License
 Free to use. Modification is permitted **for personal use**; any other use —
 distributing it, distributing modified versions, or commercial/organizational use —

package/README.md

@@ -28,7 +28,7 @@ project-conventional push, tag, or PR action, and archive the workspace.
 Unattended runs may create local WIP checkpoint commits along the way, but they
 remain local unless Ship's disclosed plan includes an approved remote action.
 
-**Status:** [`v4.5.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v4.5.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v4.7.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v4.7.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 This is the latest published release; `main` may contain unreleased work.
 
@@ -123,8 +123,9 @@ with the self-contained updater.
 `/rite-upgrade` is the separate native, preservation-first route for reconciling
 an unfinished workspace. It proves a current-contract defect before routing
 Clarify, Plan repair, Converge, Vet, Prove, Polish, Review, or Seal; it never
-migrates cursor format or invents historical proof. The engine has no workspace
-migration command. See the [CLI contract](docs/cli.md).
+migrates cursor format or invents historical proof. `devrites-engine migrate`
+owns deterministic v5 schema normalization; see the [CLI contract](docs/cli.md)
+and [ADR-0029](docs/adr/0029-v5-workspace-schema-and-native-migration.md).
 
 The [command map](docs/command-map.md) covers every command, trigger, input, and
 output. The [worked examples](docs/usage.md) show normal features, plan drift,

package/docs/adr/0029-v5-workspace-schema-and-native-migration.md

@@ -0,0 +1,62 @@
+# ADR-0029: v5 workspace schema and native migration
+
+- **Status:** Accepted
+- **Date:** 2026-08-28
+
+## Context
+
+The v5 engine changes the workspace contract: `state.md` carries a `schema`
+cursor row declaring the workspace schema version, and the current contract is
+schema 3. Workspaces written before v5 carry no row and resolve to schema 2,
+the last pre-v5 contract.
+
+The repository's preservation-first stance (ADR-0022, as applied by ADR-0025)
+forbade an engine migrator: judgment work belongs to skills, and
+`/rite-upgrade` routes repairs through phase owners. That stance served
+read-compatible releases where no normalization was needed. A schema bump is
+different: normalization — cursor encoding, missing-artifact reconciliation —
+is deterministic, content-preserving work that needs per-feature locking,
+atomic writes, and fail-closed refusal on ambiguity. Those primitives are
+engine-owned.
+
+## Decision
+
+- The engine declares the current workspace schema (`state.SchemaVersion`), and
+  each workspace declares its own through a `schema` row in its `state.md`
+  cursor. An absent row means schema 2.
+- `state resolve` and `state close` refuse workspaces whose declared schema
+  differs from the engine's, naming the recovery path:
+  `devrites-engine migrate <slug>` for pre-v5 workspaces, `upgrade devrites`
+  for newer ones. Diagnostic checks (readiness, candidate, task-graph, observe)
+  keep reading pre-v5 workspaces and reporting their established named gaps.
+- `devrites-engine migrate` performs fail-closed normalization: cursor-form
+  conversion through the existing dual-form primitives, missing required
+  artifacts as empty stubs with no synthesized content, and byte-exact
+  preservation of bound proof files. The v2→v3 normalization cannot invalidate
+  a binding — it only creates missing files and rewrites the unbound ledger —
+  and any future schema delta that would modify a bound file requires explicit
+  per-finding confirmation before it applies.
+- This supersedes the no-migrator invariant of ADR-0022 as applied by ADR-0025
+  for deterministic schema normalization only. `/rite-upgrade` keeps
+  preservation-first routing for judgment work and may hand mechanical
+  normalization to the engine command.
+
+## Alternatives considered
+
+| Option | Why not |
+|--------|---------|
+| Keep the no-migrator stance | Every pre-v5 workspace would strand mid-feature or silently diverge from the declared contract; the manifest version alone cannot normalize. |
+| Refuse all reads of pre-v5 workspaces | Diagnostics are the user's fastest evidence of what migration will change; refusing them removes actionable output without adding safety. |
+| Migrate as a skill checklist | Cursor rewrites and artifact stubs need the feature lock, atomic writes, and deterministic refusal on ambiguity — engine-owned primitives. |
+| New marker file per workspace | Duplicates the ledger; the cursor row travels inside the file every workspace already has. |
+
+## Consequences
+
+Pre-v5 workspaces remain readable; mutating or closing them requires
+migration. Migration is deterministic and byte-preserving by default, so
+recorded proof stays valid, and invalidation is never silent. The schema row
+travels inside `state.md`, so no new file format exists. New workspaces created
+by the v5 pack declare the row at creation.
+
+Guard tests: `engine/internal/state/workspaceschema_test.go`,
+`engine/tests/parity_resolve_test.go`, `engine/tests/parity_closeout_test.go`.

package/docs/adr/README.md

@@ -67,10 +67,11 @@ architecture; per-feature `decisions.md` files stay scoped to that feature.
 | [0019](0019-native-boundary-with-deterministic-gates.md) | Native boundary with deterministic gates | Accepted in part; semantic gates superseded by 0022, native writer and fresh approval retained | `engine/internal/gate/gate_test.go` |
 | [0020](0020-thin-engine-native-orchestration-boundary.md) | Thin engine and native host orchestration | Accepted in part; engine-surface/migration scope superseded by 0022, native orchestration retained | `tests/native-orchestration-contract-test.sh`, `engine/root_routing_test.go` |
 | [0021](0021-observable-workspace-compatibility.md) | Observable and reversible workspace compatibility | Superseded by 0022 | historical |
-| [0022](0022-native-orchestration-thin-engine.md) | Native orchestration with a thin deterministic engine | Accepted in part; snapshot/JSON-output clauses superseded by 0023; retained policy-command/install clauses narrowed by 0024 | `engine/root_routing_test.go`, `engine/internal/gate/gate_test.go`, `engine/internal/lib/cursor_compat_test.go`, `tests/native-orchestration-contract-test.sh` |
+| [0022](0022-native-orchestration-thin-engine.md) | Native orchestration with a thin deterministic engine | Accepted in part; snapshot/JSON-output clauses superseded by 0023; retained policy-command/install clauses narrowed by 0024; no-migrator normalization scope superseded by 0029 | `engine/root_routing_test.go`, `engine/internal/gate/gate_test.go`, `engine/internal/lib/cursor_compat_test.go`, `tests/native-orchestration-contract-test.sh` |
 | [0023](0023-native-workspace-reads-line-output.md) | Native workspace reads and line-oriented engine output | Accepted in part; AFK/recovery/doctor retention superseded by 0024 | `engine/root_routing_test.go`, `engine/internal/gate/gate_test.go`, `tests/native-orchestration-contract-test.sh`, `tests/npx-pack-smoke.sh` |
 | [0024](0024-native-policy-offline-installer-boundary.md) | Native policy and offline installer boundary | Accepted in part; offline engine-update clause superseded by 0028 | `tests/native-orchestration-contract-test.sh`, `tests/phase-gate-routing-test.sh`, `tests/install-smoke.sh`, `tests/host-artifacts-test.sh` |
-| [0025](0025-evidence-gated-workspace-upgrades.md) | Evidence-gated semantic workspace upgrades | Accepted | `tests/phase-gate-routing-test.sh`, `tests/host-artifacts-test.sh` |
+| [0025](0025-evidence-gated-workspace-upgrades.md) | Evidence-gated semantic workspace upgrades | Accepted; no-migrator scope superseded by 0029 | `tests/phase-gate-routing-test.sh`, `tests/host-artifacts-test.sh` |
 | [0026](0026-content-bound-proof-and-bounded-inputs.md) | Content-bound proof and bounded inputs | Accepted | `engine/internal/lib/candidate_test.go`, `engine/internal/lib/evidencefresh_test.go`, `engine/internal/gate/gate_test.go`, `engine/root_routing_test.go`, `engine/tests/parity_githelpers_test.go`, `tests/native-orchestration-contract-test.sh`, `tests/phase-gate-routing-test.sh`, `tests/install-smoke.sh`, `tests/update-smoke.sh`, `tests/npx-pack-smoke.sh`, `tests/release-tarball-test.sh` |
 | [0027](0027-content-bound-build-readiness.md) | Content-bound build readiness | Accepted | `engine/tests/adr_0027_readiness_binding_test.go` |
 | [0028](0028-self-contained-engine-update.md) | Self-contained engine update | Accepted | `engine/internal/install/install_test.go`, `engine/internal/release/release_test.go`, `engine/tests/meta_test.go` |
+| [0029](0029-v5-workspace-schema-and-native-migration.md) | v5 workspace schema and native migration | Accepted | `engine/internal/state/workspaceschema_test.go`, `engine/tests/parity_resolve_test.go`, `engine/tests/parity_closeout_test.go` |

package/docs/architecture.md

@@ -212,7 +212,7 @@ delta; Clarify, Plan repair, Converge, Vet, Prove, Polish, Review, or Seal then
 performs it under normal gates. Candidate repair runs current real proof and
 never synthesizes a historical pass; ambiguous legacy candidate scope is a gap.
 
-The engine has no structural migration command or compatibility telemetry. It
+The engine owns deterministic v5 schema normalization (`devrites-engine migrate`) or compatibility telemetry. It
 directly reads the official v1/v2 bullet and v3 table `state.md` cursors without
 rewriting them. Wider pre-release compatibility experiments are not runtime
 contracts. See [ADR-0025](adr/0025-evidence-gated-workspace-upgrades.md) and

package/docs/cli.md

@@ -22,6 +22,7 @@ devrites-engine check seal <slug>
 
 devrites-engine state resolve <qid> "<answer>"
 devrites-engine state close <slug>
+devrites-engine migrate <slug> [--dry-run] [--answer id=choice]
 
 devrites-engine secret-scan [--staged] [--stdin] [slug]
 devrites-engine open-visual <path-or-name> [--slug <slug>] [--no-open]
@@ -30,8 +31,7 @@ devrites-engine version
 
 Commands outside this operational list and the standard help/version forms are
 unsupported. There are no legacy engine aliases, tombstones, agent-protocol
-versions, semantic-readiness digests, compatibility telemetry, or workspace
-migration command.
+versions, semantic-readiness digests, or compatibility telemetry.
 `check candidate` is additive; no existing engine command or public `/rite-*`
 workflow was removed or renamed.
 

package/docs/command-map.md

@@ -41,7 +41,7 @@ The Go surface is intentionally closed and deterministic:
 | Lane | Commands | Owner |
 |---|---|---|
 | Candidate and deterministic checks | `check candidate`, `check readiness [--emit-binding]`, `check seal`, `check task-graph`, `check path-disjoint`, `check skill-trust` | Candidate validates/hashes the strict project manifest; readiness checks phase files, the required `tasks.md` slice graph, or emits the vetted Build-input binding; seal checks final files/open gates, that graph and binding, then exact candidate bindings. |
-| Atomic workspace state | `state resolve`, `state close` | Go owns answer/drop/batch resolution and transactional close. |
+| Atomic workspace state | `state resolve`, `state close`, `migrate [--dry-run] [--answer id=choice]` | Go owns answer/drop/batch resolution, transactional close, and fail-closed v5 schema normalization. |
 | Security | `secret-scan` | `/rite-ship`, safe hooks, or an operator scans staged blobs, stdin, or touched files. |
 | Install/operator | `install`, `update`, `uninstall`, `version` | Direct update acquires latest; npm/bootstrap may supply local candidates; the engine performs manifest-owned local changes. |
 | Native policy | no engine command | Skills/root own spec grammar re-read, qid allocation, Clarify cursor edits, AFK/recovery accounting, and read-only `/rite-doctor`. |
@@ -53,7 +53,7 @@ prints exactly
 `candidate-sha256: <64 lowercase hex>` and `candidate-files: <row count>` on a
 pass; usage/root errors exit `2` and candidate blocks exit `3`. There are no
 semantic readiness commands, reviewer-prose parsers, capability-ledger engine,
-compatibility telemetry, or migration command.
+or compatibility telemetry.
 
 Claude Code and Codex own native dispatch. Installed skills and exact agents
 own semantic readiness, traceability, acceptance/evidence quality, doubt,

package/docs/engine/commands.md

@@ -21,6 +21,7 @@ workflow strategy.
 | `observe summary <slug>` | Emit sanitized JSON workspace summary from one retained observation. `task_graph.ok` is true iff `task_graph.problems` is empty; `problems` lists cycle, unknown-dep, malformed-token, duplicate-id, and missing-`Dependencies` blockers. |
 | `state resolve <qid> "<answer>"` | Resolve an open question and update `questions.md` plus `state.md` atomically. |
 | `state close <slug>` | Archive a shipped workspace and clear matching `ACTIVE`. |
+| `migrate <slug> [--dry-run] [--answer id=choice]` | Normalize a pre-v5 workspace to the current schema; fail-closed, one-shot. |
 | `secret-scan [--staged] [--stdin] [slug]` | Scan exact staged blobs, stdin, or touched regular files for credential material. |
 | `open-visual <path-or-name> [--slug <slug>] [--no-open]` | Resolve a local visual HTML file, optionally open it in the OS browser, warn if the sibling outline is missing or inventory ids are absent from HTML, and print agent path tips. No network. |
 | `version` | Print the engine version. |
@@ -55,6 +56,14 @@ State mutations use the shared physical-root checks, feature lock, and atomic
 write path. `state resolve` additionally supports `--drop` and `--batch`;
 `state close` owns transactional archive plus `ACTIVE` clearing.
 
+`migrate` normalizes a pre-v5 workspace: legacy bullet cursor fields become
+canonical table rows, the `schema` row is recorded, and missing required
+artifacts are created as empty stubs (content is never synthesized, and bound
+proof files stay byte-exact). It is one-shot and fail-closed: on ambiguity it
+writes nothing, prints its questions, and exits `3`; answers arrive on rerun
+via `--answer id=choice`. `--dry-run` prints the plan and always writes
+nothing. See [ADR-0029](../adr/0029-v5-workspace-schema-and-native-migration.md).
+
 Normative spec grammar checks, qid allocation, Clarify cursor transitions, AFK
 slice accounting, recovery attempt accounting, and installation diagnostics are
 explicit root-owned native procedures. The workflow owns reproduction,

package/docs/engine/state-schema.md

@@ -1,11 +1,11 @@
-# `.devrites/` state schema (v2)
+# `.devrites/` state schema (v3)
 
 The engine reads workflow state from plain files under `.devrites/`. Those
 human-editable files remain authoritative; the engine has no database or
 semantic cache.
 
 <!-- authority:schema-version:start -->
-`schemaVersion: 2`.
+`schemaVersion: 3`.
 <!-- authority:schema-version:end -->
 
 For root selection, supported legacy cursors, and the full artifact layout, see

package/docs/engine/workspace-schema.md

@@ -125,7 +125,12 @@ The runtime reads only official released workspace formats:
 The canonical workspace location remains `.devrites/work/<slug>/`; canonical
 map, cursor, and proof files are `README.md`, `state.md`, and `evidence.md`.
 Compatibility reads do not rewrite a workspace and do not emit local telemetry.
-There is no structural migration command. `/rite-upgrade` first audits an older
+Since engine v5, workspaces declare their schema through a `schema` row in the
+`state.md` cursor; an absent row means the pre-v5 schema 2 contract. `state
+resolve` and `state close` refuse workspaces whose declared schema is not the
+current one: pre-v5 workspaces run `devrites-engine migrate <slug>`, and newer
+workspaces require upgrading devrites.
+`/rite-upgrade` first audits an older
 active workspace against named current contracts; only a cited defect may route
 an edit through its normal phase owner. For released unfinished post-Build
 workspaces, candidate defects route through current Prove, Polish, Review, and
@@ -134,8 +139,9 @@ an old pass.
 
 Other pre-release layouts, filename substitutions, and phase encodings are
 not runtime authorities. See
-[ADR-0022](../adr/0022-native-orchestration-thin-engine.md) and
-[ADR-0025](../adr/0025-evidence-gated-workspace-upgrades.md).
+[ADR-0022](../adr/0022-native-orchestration-thin-engine.md),
+[ADR-0025](../adr/0025-evidence-gated-workspace-upgrades.md), and
+[ADR-0029](../adr/0029-v5-workspace-schema-and-native-migration.md).
 
 ## Native policy state
 

package/docs/usage.md

@@ -61,7 +61,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/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,20 @@ 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
+		}
+		return rootUnused
+	case "observe":
+		switch subcommand {
+		case "summary":
+			return rootStrictUsage
+		}
+		return rootUnused
 	default:
 		return rootUnused
 	}
@@ -67,6 +82,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/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_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_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)
 		}
@@ -365,7 +371,7 @@ 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",