devrites 4.6.0 → 5.0.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 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`.
 
+## [5.0.0](https://github.com/ViktorsBaikers/DevRites/compare/v4.7.0...v5.0.0) (2026-09-06)
+
+### ⚠ BREAKING CHANGES
+
+* **release:** restore secrets.NPM_TOKEN for semantic-release publish
+* **ci:** unblock semantic-release on setup-node v6 cache input
+* **repo:** land guidance audit, CI hardening, and omp host pack (#57)
+
+### Added
+
+* **repo:** land guidance audit, CI hardening, and omp host pack ([#57](https://github.com/ViktorsBaikers/DevRites/issues/57)) ([764ad9b](https://github.com/ViktorsBaikers/DevRites/commit/764ad9b0dd43f837d43f1556cf1b395eabdbd0c6))
+
+### Fixed
+
+* **ci:** unblock semantic-release on setup-node v6 cache input ([e357ad9](https://github.com/ViktorsBaikers/DevRites/commit/e357ad916d3b880c9d69239c798bf0f803ee335a))
+* **release:** restore secrets.NPM_TOKEN for semantic-release publish ([24ee2e4](https://github.com/ViktorsBaikers/DevRites/commit/24ee2e4f23eac04cc1f82efe0d2f4e88595f88c7))
+
+## [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

package/NOTICE.md

@@ -17,3 +17,9 @@ DevRites integrates with **Claude Code** and **Codex** and follows each host's
 project-local skill, agent, and instruction conventions. "Claude" and "Claude
 Code" are products of Anthropic; "Codex" is a product of OpenAI. DevRites is
 independent and unaffiliated with Anthropic and OpenAI.
+
+## Framework identifiers
+
+`pack/.claude/skills/devrites-lib/reference/standards/security.md` cites published
+OWASP GenAI Top 10 identifier names (LLM01–LLM10, ASI01–ASI10) as mapping keys
+for interoperability. DevRites does not vendor OWASP documents.

package/README.md

@@ -12,6 +12,11 @@ The work lives under `.devrites/`, not in chat history. A later session or a
 different agent can read the same plan, decisions, state, and evidence before it
 continues.
 
+Executive fast path: **Spec → Build → Prove**. `/rite-spec` writes the
+contract, `/rite-build` implements one slice, `/rite-prove` binds evidence.
+Adaptive Clarify/Vet still run; they ask nothing when the contract is already
+complete. `/rite-quick` covers a small reversible change.
+
 The core path is:
 
 `SPEC -> CLARIFY -> [TEMPER] -> DEFINE -> VET -> BUILD -> PROVE -> POLISH -> REVIEW -> SEAL -> SHIP`
@@ -28,7 +33,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.6.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v4.6.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v5.0.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v5.0.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 This is the latest published release; `main` may contain unreleased work.
 
@@ -83,7 +88,11 @@ the same skill.
 | 3 | Temper | [`/rite-temper`](pack/.claude/skills/rite-temper/SKILL.md) | Challenges scope and failure modes before Define. It is optional for small work and always runs in `/rite-autocomplete`. |
 | 4 | Define | [`/rite-define`](pack/.claude/skills/rite-define/SKILL.md) | Turns the approved spec into architecture, a plan, traceability, and vertical task slices; changed provider/consumer boundaries name one shared contract and consuming tests on both sides. |
 | 5 | Vet | [`/rite-vet`](pack/.claude/skills/rite-vet/SKILL.md) | Reviews every plan before implementation. The review depth scales with the risk. |
-| 6 | Build | [`/rite-build`](pack/.claude/skills/rite-build/SKILL.md) | In HITL, implements and verifies one product slice, then stops. Run it again for each remaining slice. An explicit `.devrites/AFK` sentinel permits bounded low-risk slice chaining under its cap and pause rules. Exact Vet-ready executable workflow artifacts under the active feature workspace are root-materialized and excluded from product slice accounting; their transaction code is proved in a disposable same-layout fixture before active writes and uses normal bounded recovery rather than a one-shot budget. |
+| 6 | Build | [`/rite-build`](pack/.claude/skills/rite-build/SKILL.md) | In HITL, implements and verifies one product slice, then stops. Run it again for each remaining slice. An explicit `.devrites/AFK` sentinel permits bounded low-risk slice chaining under its cap and pause rules. Exact Vet-ready
+executable workflow artifacts under the active feature workspace are root-materialized
+and excluded from product slice accounting. Their transaction code is proved in a
+disposable same-layout fixture before active writes, and uses normal bounded recovery
+rather than a one-shot budget. |
 | 7 | Converge | [`/rite-converge`](pack/.claude/skills/rite-converge/SKILL.md) | Runs only when recovery is needed. It compares the code with the recorded intent, adds missing slices, and sends the changed plan back to Vet. |
 | 8 | Prove | [`/rite-prove`](pack/.claude/skills/rite-prove/SKILL.md) | Runs positive, discriminating tests, build/runtime checks, and UI proof, then binds the evidence to the exact candidate digest. |
 | 9 | Polish | [`/rite-polish`](pack/.claude/skills/rite-polish/SKILL.md) | Cleans up the candidate, normalizes UI when needed, performs durable capability/design/ADR rollups, and refreshes affected proof before closing it. |
@@ -100,13 +109,14 @@ Some work needs a different route:
   the reversible lifecycle unattended. With `--ship`, it continues through
   Ship preflight, discloses the exact Git plan, and waits for a fresh literal
   `GO` plus native approval; without that flag, it stops at Seal GO. A failed
-  consumptive proof action never retries blindly: retained evidence drives
-  offline repair and re-vetting. Ambiguous retained evidence first drives a vetted
-  boundary-discriminating diagnostic design; only its next real acquisition attempt
-  needs a new GO. After an upgrade introduces a supported workflow-artifact writer,
-  Autocomplete reopens a stale missing-writer stop once instead of preserving the
-  obsolete recovery count. The first real root-materializer failure then counts as
-  attempt one under normal fingerprint recovery; it is not terminal by itself.
+  consumptive proof action never retries blindly. Retained evidence drives
+  offline repair and re-vetting. When retained evidence is ambiguous,
+  Autocomplete first designs a vetted boundary-discriminating diagnostic; only
+  the next real acquisition attempt needs a new GO. After an upgrade introduces
+  a supported workflow-artifact writer, Autocomplete reopens a stale
+  missing-writer stop once instead of preserving the obsolete recovery count.
+  The first real root-materializer failure then counts as attempt one under
+  normal fingerprint recovery — it is not terminal by itself.
   Likewise, an internal `NEEDS_REPLAN` result stays inside Autocomplete: it runs
   the next Plan repair and narrow Vet without returning a command to the user.
 - [`/rite-upgrade [slug]`](pack/.claude/skills/rite-upgrade/SKILL.md) is a
@@ -123,8 +133,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,
@@ -224,13 +235,19 @@ and continue:
 
 ```yaml
 max_slices: 10
+max_agents: 32
+max_minutes: 120
+max_review_queue: 8
+expires_at: "<ISO-8601 UTC timestamp>"
 allow_gates: [advisory]
 ```
 
 The workflow treats this file as configuration and never rewrites it.
 `max_slices` seeds the remaining budget in the active feature's `state.md`; the
 root charges that state exactly once after each green built slice and stops
-before another dispatch at zero. Malformed counters fail closed. Delete `.devrites/AFK` to
+before another dispatch at zero. Unattended slice work additionally requires a
+valid `max_agents`, `max_minutes`, `max_review_queue`, and `expires_at`;
+sentinels that miss or malform these fail closed. Delete `.devrites/AFK` to
 return to HITL.
 
 AFK still pauses for product, scope, or policy choices, irreversible risk,
@@ -263,6 +280,13 @@ devrites-engine update
 devrites-engine update --check
 ```
 
+Release binaries and installers ship with SHA-256 sidecars and build-provenance
+attestations. Verify a download with `shasum -a 256 -c <file>.sha256` or
+`gh attestation verify <file> -R ViktorsBaikers/DevRites --signer-workflow ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main`
+(pinning the signer workflow matters: valid provenance proves where a build
+ran, not that the publishing step was the intended one); see
+[docs/release.md](docs/release.md).
+
 Useful install flags:
 
 | Flag | Effect |

package/SECURITY.md

@@ -209,9 +209,9 @@ Repository npm-audit exceptions are temporary trust records, not claims that an
 upstream issue is fixed. Each entry in `scripts/npm-audit-exceptions.json` is
 restricted to an exact advisory, package range, installed node path, owner,
 reason, source, and near-term expiry; validation re-audits the live dependency
-graph and fails stale, broadened, unmatched, or expired entries. In particular,
-the `brace-expansion` advisory remains present in npm's bundled dependency chain
-until a patched ancestor is available.
+graph and fails stale, broadened, unmatched, expired, or inside-the-7-day
+refresh-horizon entries. Prefer pinning a patched ancestor (see
+`package.json` `overrides`) over extending an expiry.
 
 ### Agentic trust boundaries
 

package/bin/devrites.mjs

@@ -62,6 +62,7 @@ Common flags:
   --dry-run             Show the plan, change nothing
   --force               Overwrite existing non-DevRites files
   --no-codex            Skip Codex support files (.agents, .codex, AGENTS.md)
+  --no-omp              Skip OMP support files (.omp/skills, .omp/agents)
   --short-aliases=all   Also install /define /build /prove /seal
   --no-agents           Skip hook-free native specialist profiles
   --no-skills           Skip skills and bundled engineering standards

package/docs/adr/0027-content-bound-build-readiness.md

@@ -75,3 +75,11 @@ the check; hostile concurrent workspace mutation remains outside the local
 agent-workflow threat model.
 
 Guard test: `engine/tests/adr_0027_readiness_binding_test.go`.
+
+## Amendment (2026-09-04)
+
+When `tasks.md` is required, `check readiness` and `check seal` also require
+every canonical `AC-###` ID in `spec.md`'s Acceptance criteria section to appear
+as a literal substring in `tasks.md`. When `test-plan.md` is required, the same
+IDs must appear there. This is identity presence, not semantic coverage. Guard:
+`engine/internal/state/acceptance_test.go`.

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` |
+| [0027](0027-content-bound-build-readiness.md) | Content-bound build readiness | Accepted; AC ID map amended 2026-09-04 | `engine/tests/adr_0027_readiness_binding_test.go`, `engine/internal/state/acceptance_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,10 +212,14 @@ 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
-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
+The engine owns deterministic v5 schema normalization (`devrites-engine migrate`),
+not compatibility telemetry. Readers accept official v1/v2 bullet and v3 table
+`state.md` cursors; mutations require the current state schema (v3). Migration
+can create missing artifact stubs, but those stubs prove neither semantic
+readiness nor completed work. Wider pre-release compatibility experiments are
+not runtime contracts. [ADR-0029](adr/0029-v5-workspace-schema-and-native-migration.md)
+records native migration alongside the semantic boundary established by
+[ADR-0025](adr/0025-evidence-gated-workspace-upgrades.md) and
 [ADR-0022](adr/0022-native-orchestration-thin-engine.md).
 
 ### Why `/engine` was rejected

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

@@ -40,8 +40,9 @@ 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. |
+| Candidate and deterministic checks | `check candidate`, `check readiness [--emit-binding]`, `check seal`, `check task-graph`, `check path-disjoint`, `check skill-trust`, `check indexes` | 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. `check indexes` reports install manifest and optional code-index directory presence as JSON. |
+| Workspace observation | `observe summary`, `orient` | JSON workspace snapshot for agents; `orient` is an alias for `observe summary`. |
+| 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 +54,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,
@@ -133,7 +134,7 @@ the shared reference library.
 | [`devrites-doubt`](../pack/.claude/skills/devrites-doubt/SKILL.md) | non-trivial decision in build/review | CLAIM → EXTRACT → DOUBT → RECONCILE → STOP | adversarial; the root gates genuine human-owned uncertainty |
 | [`devrites-ux-shape`](../pack/.claude/skills/devrites-ux-shape/SKILL.md) | UI detected in `/rite-spec` | Plan UX/UI before code → `design-brief.md` (direction, states, interaction, visual-direction probe) | the build target; refs: brief-template/visual-direction-probe |
 | [`devrites-frontend-craft`](../pack/.claude/skills/devrites-frontend-craft/SKILL.md) | UI detected in build/polish | Build **to** `design-brief.md`: register, refine-per-slice, states, anti-slop | refs: shape/craft/design-references |
-| [`devrites-prose-craft`](../pack/.claude/skills/devrites-prose-craft/SKILL.md) | a phase writes prose; `/rite-polish` Phase 1 catch | Human-voice writing: strip LLM tells, keep precise lists/terms | refs: banned-phrases, structures, examples |
+| [`devrites-prose-craft`](../pack/.claude/skills/devrites-prose-craft/SKILL.md) | a phase writes prose; `/rite-polish` Phase 1 catch | Human-voice writing: strip LLM tells (including assistant leaks), keep precise lists/terms | refs: banned-phrases, structures, examples |
 | [`devrites-browser-proof`](../pack/.claude/skills/devrites-browser-proof/SKILL.md) | UI in prove/polish | Browser proof ladder + evidence schema + the structured **Visual Verdict** table | harness preferred |
 | [`devrites-debug-recovery`](../pack/.claude/skills/devrites-debug-recovery/SKILL.md) | failing tests/build/runtime | 7-step: loop → reproduce → hypotheses → trace → instrument → fix → cleanup | caller + recovery count three failed attempts per causal fingerprint from context and Dead ends/evidence |
 | [`devrites-api-interface`](../pack/.claude/skills/devrites-api-interface/SKILL.md) | cross-boundary slice | Stable API/contract design | FE/BE split |

package/docs/engine/commands.md

@@ -12,15 +12,16 @@ workflow strategy.
 | `update [flags]` | Refresh an existing managed installation. |
 | `uninstall [flags]` | Remove managed artifacts while preserving runtime workspace state. |
 | `check candidate <slug>` | Validate the strict manifest and compute the content-bound project-candidate identity. |
-| `check readiness <slug>` | Check target-Phase files, open human gates from Clarify onward, the `tasks.md` slice graph when that artifact is required, and the current stable Build-input binding when applicable. |
+| `check readiness <slug>` | Check target-Phase files, open human gates from Clarify onward, the `tasks.md` slice graph when that artifact is required, canonical `AC-###` presence in `tasks.md`/`test-plan.md` when those artifacts are required, and the current stable Build-input binding when applicable. |
 | `check readiness --emit-binding <slug>` | Render the exact stable Build-input binding for Vet to record after review. |
-| `check seal <slug>` | Check files required by target Phase `seal`, open human gates, the `tasks.md` slice graph, the stable Build-input binding, and exact candidate bindings. |
+| `check seal <slug>` | Check files required by target Phase `seal`, open human gates, the `tasks.md` slice graph, canonical `AC-###` presence when `tasks.md`/`test-plan.md` are required, the stable Build-input binding, and exact candidate bindings. |
 | `check path-disjoint [--root <dir>] [<json-file> | -]` | Verify slice path sets are pairwise disjoint. |
 | `check task-graph <slug>` | Validate `tasks.md` slice dependency graph for cycles, unknown deps, malformed tokens, duplicate IDs, missing `Dependencies`, and `depends_on` mismatch. |
 | `check skill-trust <path>` | Scan one skill/agent Markdown file for structural trust violations. |
 | `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. |
@@ -37,12 +38,14 @@ The candidate gate validates and hashes path/state/type/mode/content identity;
 it does not infer scope from Git. The readiness gate checks target-Phase
 structure and applies open-question blocking only when that target is Clarify
 or later, plus the exact `tasks.md` slice graph when `tasks.md` is required,
-plus the exact stable Build-input binding after Vet. The seal gate
-always targets Phase `seal`, repeats that graph and binding, and checks exact candidate
-bindings in evidence, optional browser evidence, review, and seal. None judges
-the meaning of `CLEAR`/`READY` prose,
-parses reviewer narratives, infers acceptance coverage, counts assertions,
-interprets capability deltas, or decides whether a technical plan is sound.
+plus canonical `AC-###` ID presence in `tasks.md` and `test-plan.md` when those
+artifacts are required, plus the exact stable Build-input binding after Vet. The
+seal gate always targets Phase `seal`, repeats that graph, ID map, and binding,
+and checks exact candidate bindings in evidence, optional browser evidence,
+review, and seal. None judges the meaning of `CLEAR`/`READY` prose,
+parses reviewer narratives, infers semantic acceptance coverage, counts
+assertions, interprets capability deltas, or decides whether a technical plan is
+sound.
 
 Those judgments are made by the current skill and exact native roles, including
 `devrites-plan-reviewer`, `devrites-proof-runner`, `devrites-spec-reviewer`,
@@ -55,6 +58,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/flow.md

@@ -344,7 +344,7 @@ erDiagram
     }
     WORKSPACE {
         string slug PK ".devrites/work/<slug>/"
-        int schemaVersion "2; older additive layouts remain readable"
+        int schemaVersion "3; mutations require current schema; older cursors remain readable"
     }
     state {
         string phase "frame | spec | clarify | temper | define | plan | vet | build | converge | prove | polish | review | seal | ship | done"

package/docs/orchestration.md

@@ -160,8 +160,10 @@ Native hosts, skills, exact agents, repository tools, or CI own:
 - session history, compaction, status prose, progress, plugins, and memory.
 
 The engine has no agent bridge, semantic readiness protocol/digests, heuristic
-prose parser, capability-ledger interpreter, compatibility telemetry, migration
-command, or old aliases.
+prose parser, capability-ledger interpreter, compatibility telemetry, or old
+aliases. Its `migrate` command performs deterministic schema normalization;
+artifact stubs do not establish semantic readiness or historical proof
+([ADR-0029](adr/0029-v5-workspace-schema-and-native-migration.md)).
 
 Provider/consumer changes use the existing plan and traceability artifacts: one
 canonical contract plus provider- and consumer-side asserting tests that both

package/docs/quick-reference.md

@@ -1,5 +1,10 @@
 # DevRites quick reference
 
+Executive fast path: **Spec → Build → Prove**. `/rite-spec` writes the
+contract, `/rite-build` implements one slice, `/rite-prove` binds evidence.
+Adaptive Clarify/Vet still run; they ask nothing when the contract is already
+complete. Use `/rite-quick` for a small reversible change.
+
 Install DevRites with `npx devrites ...`. Normal installs from package and
 release candidates consume pre-generated project-local Claude Code and Codex
 artifacts; plugin stores do not distribute them. Source-checkout shell shims may

package/docs/release.md

@@ -7,13 +7,20 @@ commit messages. A `feat:`, `fix:`, `perf:`, `refactor:`, `build:`,
 `remove:`, `docs(README):`, or `BREAKING CHANGE:` tells it to choose the next SemVer
 version and run these steps:
 
-1. Waits for the workflow's validation, full shell suite, strict Go-engine checks, Linux cross-compile smoke, and Windows Go tests.
+1. Waits for the workflow's validation, full shell suite, strict Go-engine checks, Linux cross-compile smoke, Windows and macOS Go tests.
 2. Regenerates `CHANGELOG.md` from the commits.
 3. Syncs the new version into `package.json` and the README status line (`scripts/sync-version.sh`), then stages only those known overlays plus the generated changelog so the release index owns their bytes.
 4. Builds `dist/devrites-v<version>.tar.gz` and `dist/install.sh`, each with an exact-filename SHA-256 sidecar, via `scripts/build-release-tarball.sh`. Payload paths and bytes are materialized from the repository-root Git index; the build fails outside that index and never copies a divergent live worktree file. A stdlib Go packager sorts member names and normalizes ownership, modes, timestamps, and the gzip header, so identical indexed sources produce identical archives. `SOURCE_DATE_EPOCH` selects the canonical timestamp and defaults to `0`. The bundle includes the checked-in host-native Claude/Codex artifacts under `pack/generated/`; symlinks and other non-regular payload entries are rejected.
 5. Cross-compiles five `devrites-engine` release binaries (macOS arm64/amd64, Linux arm64/amd64, Windows amd64) plus a SHA-256 sidecar for each.
-6. Publishes the `devrites` package to npm through `@semantic-release/npm`, using `NPM_TOKEN`. This is what `npx devrites@latest` resolves. `npm pack` regenerates the same `pack/generated/` artifacts during `prepack`; there is no `postpack` cleanup step.
-7. Commits the version bump + changelog as `chore(release): <version> [skip ci]`, creates tag `v<version>`, and publishes a GitHub Release with the tarball, verified installer, binaries, and every checksum sidecar attached.
+6. Publishes the `devrites` package to npm through `@semantic-release/npm` with
+   provenance attestation. The job requests OIDC (`id-token: write`) so a
+   future npm Trusted Publisher can take over, and today authenticates with
+   `secrets.NPM_TOKEN` because npm's OIDC exchange still returns
+   "package not found" until that Trusted Publisher is configured for
+   `devrites`. This is what `npx devrites@latest` resolves. `npm pack`
+   regenerates the same `pack/generated/` artifacts during `prepack`; there
+   is no `postpack` cleanup step.
+7. Commits the version bump + changelog as `chore(release): <version> [skip ci]`, creates tag `v<version>`, and publishes a GitHub Release with the tarball, verified installer, binaries, and every checksum sidecar attached. The release job then attests the artifacts with build provenance (`actions/attest-build-provenance`), independent of npm provenance.
 
 Package prepack normally owns host artifact generation; the release archive
 consumes the validated generated files from the same Git index as the rest of
@@ -25,6 +32,45 @@ engine itself only validates and copies host payloads; it never generates them.
 The npm entrypoint, verified release installer, and direct engine updater acquire
 only an exact-SemVer release bundle or platform binary with its mandatory
 exact-filename SHA-256 sidecar.
+
+Verify a downloaded engine binary from a GitHub Release:
+
+```bash
+curl -LO "https://github.com/ViktorsBaikers/DevRites/releases/download/v<version>/devrites-<os>-<arch>[.exe]"
+curl -LO "https://github.com/ViktorsBaikers/DevRites/releases/download/v<version>/devrites-<os>-<arch>[.exe].sha256"
+( cd "$(dirname "$0")" && shasum -a 256 -c devrites-<os>-<arch>[.exe].sha256 )
+```
+
+Every release artifact also carries a GitHub artifact attestation (build
+provenance generated inside the release job, bound to the artifact digest).
+Verify it, pinning the signer workflow so an attestation minted from any other
+workflow path in this repository is rejected — provenance proves where a build
+ran, not that the publishing step was the intended one:
+
+```bash
+gh attestation verify devrites-<os>-<arch>[.exe] -R ViktorsBaikers/DevRites \
+  --signer-workflow ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main
+```
+
+Releases with binaries also attach CycloneDX SBOMs: `devrites-npm.cdx.json`
+for the npm dependency tree (`npm sbom`) and
+`devrites-engine-linux-amd64.cdx.json` for the shipped engine binary
+(Anchore Syft). The engine itself is stdlib-only, so the binary SBOM is
+nominally just the module plus the Go toolchain — it exists so a consumer's
+vulnerability or license tooling has a machine-readable input.
+
+Treat attestations as independent of npm provenance, not as a safety signal:
+the 2026 TanStack and `@redhat-cloud-services` incidents published malicious
+packages with valid SLSA provenance. Verify the artifact digest; provenance
+only proves where a build ran.
+
+npm packages published from `main` set `publishConfig.provenance: true` in
+`package.json`. The release job keeps `id-token: write` for OIDC and wires
+`NPM_TOKEN: ${{ secrets.NPM_TOKEN }}` as the current publish credential until
+an npm Trusted Publisher is configured for this package/workflow. Provenance
+attests build origin, not package safety — still pin versions and audit the
+dependency tree. Do not commit token values; only the Actions secret name.
+
 Every redirect hop remains HTTPS; downloads use private temporary directories
 and fixed in-stream byte ceilings. The bootstrap first streams archive metadata,
 then paths, aborting the producer on a type, count, expanded-size, containment,
@@ -62,14 +108,16 @@ semantic-release derives the next section from the accepted commits on `main`.
 `scripts/check-npm-audit.mjs` re-audits the live npm graph. Temporary entries in
 `scripts/npm-audit-exceptions.json` must remain exact-range, exact-node,
 owner-bound, justified, sourced, and near-term expiring; stale, broadened,
-unmatched, or expired entries fail validation. The current `brace-expansion`
-entry documents an advisory still present in npm's bundled dependency chain; it
-does not claim the advisory is fixed.
+unmatched, expired, or inside-the-7-day-refresh-horizon entries fail
+validation. `osv-scanner.toml` `ignoreUntil` dates must match those expiries.
+Do not extend an expiry silently: refresh the ancestor (today, pin
+`@semantic-release/npm`'s bundled `npm` to `11.19.1` via `overrides`) or
+remove the exception.
 
 ## Authoring commits that trigger releases
 
 | Commit prefix | Bump |
-|---|---|
+| --- | --- |
 | `feat:` | **minor** (`0.1.0` → `0.2.0`) |
 | `remove:` | **minor**; grouped under Removed in release notes |
 | `fix:` / `perf:` / `refactor:` / `build:` / `docs(README):` | **patch** (`0.1.0` → `0.1.1`) |

package/docs/skills.md

@@ -172,7 +172,7 @@ and `Shipped`. Utility commands keep the same compact labels and one-next-action
 
 | Skill | What It Does | Use When |
 |---|---|---|
-| [`rite-vet`](../pack/.claude/skills/rite-vet/SKILL.md) | Engineering review of `plan.md` + `tasks.md`: scope challenge (reuse / minimum-diff / complexity smell), then architecture / plan code-quality / test-coverage design / performance through senior-engineer lenses, every finding confidence-banded with a quote-the-source verification gate. Maps failure modes and dependency safety, hardens the plan, and writes `test-plan.md` plus a semantic `READY` verdict reconciled by the exact native reviewer; acceptance-changing deltas fold back via the Spec Drift Guard. Adversarial fresh-context loop via [`devrites-plan-reviewer`](../pack/.claude/agents/devrites-plan-reviewer.md) on the full pass; optional `--cross-model` second opinion. | **Every defined plan, before build.** Depth scales with the stakes: a light pass on a simple, reversible plan; the full pass on a big or risky one (migration · auth · public API · data model · multi-slice · >8 files · new dependency). Never skipped; always in `/rite-autocomplete`. |
+| [`rite-vet`](../pack/.claude/skills/rite-vet/SKILL.md) | Engineering review of `plan.md` + `tasks.md`: scope (reuse / minimum-diff / complexity), then architecture, plan quality, tests, and performance.<br>Every finding is confidence-banded with a quote-the-source gate.<br>Hardens the plan, maps failure modes and dependency safety, writes `test-plan.md`, and records a semantic `READY` verdict.<br>Acceptance-changing deltas fold back via the Spec Drift Guard.<br>The full pass uses fresh-context [`devrites-plan-reviewer`](../pack/.claude/agents/devrites-plan-reviewer.md); optional `--cross-model` second opinion. | **Every defined plan, before build.** Light pass on a simple reversible plan; full pass on a risky one (migration · auth · public API · data model · multi-slice · >8 files · new dependency). Never skipped; always in `/rite-autocomplete`. |
 
 ### Build: one verified slice at a time
 
@@ -196,7 +196,7 @@ and `Shipped`. Utility commands keep the same compact labels and one-next-action
 |---|---|---|
 | [`rite-polish`](../pack/.claude/skills/rite-polish/SKILL.md) | Runs code/UI polish, then applicable capability-ledger, design-memory, and ADR rollups; updates the manifest and affected proof before closing the candidate. Accepts the existing mode tokens. | All slices proven; ready to finish. |
 | [`devrites-frontend-craft`](../pack/.claude/skills/devrites-frontend-craft/SKILL.md) | Senior frontend craft: register, shape-before-code, all states, design system, anti-AI-slop, Core Web Vitals + WCAG 2.2. | A slice touches UI. |
-| [`devrites-prose-craft`](../pack/.claude/skills/devrites-prose-craft/SKILL.md) | Human-voice writing for artifacts + replies: strips the LLM tells (filler openers, false contrasts, fake profundity, em-dash tics, hedging) while keeping precise lists, exact terms, and spec structure. The catch pass in `/rite-polish` Phase 1. | A phase writes prose (spec / plan / decisions / review / seal / commit / PR bodies) or a user-facing reply. |
+| [`devrites-prose-craft`](../pack/.claude/skills/devrites-prose-craft/SKILL.md) | Human-voice writing for artifacts + replies: strips LLM tells (filler, fake contrast, reasoning-chain scaffolding, assistant leaks) while keeping precise lists, exact terms, and spec structure. The catch pass in `/rite-polish` Phase 1. | A phase writes prose (spec / plan / decisions / review / seal / commit / PR bodies) or a user-facing reply. |
 
 ### Review: adversarial and scoped to the feature
 
@@ -222,7 +222,7 @@ and `Shipped`. Utility commands keep the same compact labels and one-next-action
 
 | Skill | What It Does | Use When |
 |---|---|---|
-| [`rite-autocomplete`](../pack/.claude/skills/rite-autocomplete/SKILL.md) | Runs the whole lifecycle unattended (spec → clarify → … → seal → ship), choosing the recommended option at each soft gate and recording the rationale in `decisions.md`. A vague prompt triggers one up-front spec/clarify window; after decision coverage is CLEAR it runs without per-phase iteration, pausing only for genuine product/scope/policy decisions, irreversible risk, human-only access/actions, NO-GO, or budget exhaustion. Objective red checks use bounded technical recovery, including cold-resume recovery from retained one-shot evidence and one-time migration of stale missing-writer stops when an upgraded contract supplies the first supported workflow-artifact writer. That migration applies once, but the first real materializer failure is only attempt one under normal bounded recovery. Internal `NEEDS_REPLAN` and newly discovered agent-owned review findings remain caller-owned backward edges rather than user-facing stops. Spending an action authorization blocks only another real execution, not offline repair. Default stops at Seal GO; `--ship` (alias `--yolo`) reaches Ship preflight but still requires a fresh literal `GO` and native approval. | "Autocomplete", "do the whole thing", "run the full cycle", "one-shot this feature". |
+| [`rite-autocomplete`](../pack/.claude/skills/rite-autocomplete/SKILL.md) | Runs the lifecycle unattended (spec → clarify → … → seal → ship), choosing the recommended option at each soft gate and recording the rationale in `decisions.md`.<br>A vague prompt gets one up-front spec/clarify window; after CLEAR it does not iterate per phase.<br>It pauses only for genuine product/scope/policy decisions, irreversible risk, human-only access, NO-GO, or budget exhaustion.<br>Objective red checks use bounded technical recovery, including cold-resume from retained one-shot evidence and one-time migration of stale missing-writer stops when an upgraded contract supplies the first supported writer. That migration applies once; the first real materializer failure is attempt one under normal bounded recovery. Internal `NEEDS_REPLAN` and new agent-owned review findings stay caller-owned backward edges, not user-facing stops. Spending an action authorization blocks another real execution, not offline repair.<br>Default stops at Seal GO. `--ship` (alias `--yolo`) reaches Ship preflight but still requires a fresh literal `GO` and native approval. | "Autocomplete", "do the whole thing", "run the full cycle", "one-shot this feature". |
 | [`rite-zoom-out`](../pack/.claude/skills/rite-zoom-out/SKILL.md) | Map the modules, callers, callees, and decisions in an unfamiliar area using the project's domain glossary. | Explicit-only: `/rite-zoom-out` / `/rite zoom-out`. |
 | [`rite-prototype`](../pack/.claude/skills/rite-prototype/SKILL.md) | Throwaway code answering ONE design question: logic harness OR 2 to 4 UI variations on one route. | Explicit-only: `/rite-prototype` / `/rite prototype`. |
 | [`rite-handoff`](../pack/.claude/skills/rite-handoff/SKILL.md) | Compact chat session → handoff doc. References existing `.devrites/work/<slug>/` artifacts by path. | Explicit-only: `/rite-handoff` / `/rite handoff`. |