devrites 5.11.0 → 5.12.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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.12.0](https://github.com/ViktorsBaikers/DevRites/compare/v5.11.0...v5.12.0) (2026-09-20)
+
+### Added
+
+* **rite:** add machine-checked acceptance and workflow controls ([#80](https://github.com/ViktorsBaikers/DevRites/issues/80)) ([4b72202](https://github.com/ViktorsBaikers/DevRites/commit/4b722020a22c884d044f8782f6e14c946b08c069))
+
 ## [5.11.0](https://github.com/ViktorsBaikers/DevRites/compare/v5.10.2...v5.11.0) (2026-09-16)
 
 ### Added

package/README.md

@@ -34,7 +34,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:** [`v5.11.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v5.11.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v5.12.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v5.12.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 This is the latest published release; `main` may contain unreleased work.
 

package/docs/agents/issue-driven-rites.md

@@ -8,4 +8,4 @@ Local issue files are the source of truth; external trackers are references only
 2. Start `/rite-spec <slug>` from the relevant PRD/issues; copy lifecycle decisions into `.devrites/work/<slug>/`, while tracker status/comments remain in the local issue files.
 3. Run the normal lifecycle: `/rite-clarify` → optional `/rite-temper` → `/rite-define` → `/rite-vet` → `/rite-build` → `/rite-prove` → `/rite-polish` → `/rite-review` → `/rite-seal` → `/rite-ship`.
 4. After a recorded type-GO, mark completed local issues `Status: resolved` and append the ship evidence; include `Closes #NNN` only when an external issue reference exists.
-5. Follow-ups become the next numbered local issue under `.scratch/<slug>/issues/` (or a new feature directory when scope differs); external auto-posting is out of scope.
+5. Follow-ups become the next numbered local issue under `.scratch/<slug>/issues/` (or a new feature directory when scope differs); external auto-posting is out of scope. When picking the next issue to start, run `scripts/issue-ready.sh <slug>` (or unscoped for all features) instead of re-reading every file — it applies the Status/Blocked-by/claimed ready rule deterministically and prints the ready frontier.

package/docs/agents/issue-tracker.md

@@ -9,6 +9,9 @@ Issues and PRDs for this repo live as markdown files in `.scratch/`. For the end
 - Implementation issues are `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`
 - Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
 - Comments and conversation history append to the bottom of the file under a `## Comments` heading
+- An issue discovered while working another records `Found during: NN` (the parent issue number) near the `Status:` line; the discovery trail survives so a later audit can see where it came from
+- Ordering is recorded as optional lines near `Status:`: `Blocked by: NN, NN` (cannot start until those resolve), `Blocks: NN` (this issue gates those), `Relates: NN` (context link, no ordering). A dependency that would create a cycle is flagged and resolved by a human, never silently recorded.
+- An issue is **ready** when its `Status:` is open, every `Blocked by:` target is `resolved`, and nothing has claimed it. Pick work by lowest ready number; a blocked issue is skipped, not partially started. `scripts/issue-ready.sh` computes the ready frontier deterministically (optionally scoped to one feature slug) — use it instead of re-reading every file.
 
 ## When a skill says "publish to the issue tracker"
 

package/docs/cli.md

@@ -22,8 +22,34 @@ devrites-engine check candidate <slug>
 devrites-engine check readiness <slug>
 devrites-engine check readiness --emit-binding <slug>
 devrites-engine check seal <slug>
+devrites-engine check slice <slug> <SLICE-ID>
+devrites-engine check diff-scope <slug> --allow <csv>|--allow-file <path>
+devrites-engine check task-graph <slug>
+devrites-engine check regression <slug> [--update]
+devrites-engine check drift <slug> [--record]
+devrites-engine check windows <slug> [--worktree|--staged|--base <ref>]
+devrites-engine check dup [slug] [--all|--worktree|--staged|--base <ref>]
+devrites-engine check skill-trust <path>
+devrites-engine check path-disjoint [<json-file>|-]
+devrites-engine check indexes [--root <dir>]
+devrites-engine detect commands [--root <dir>] [--json]
+
+devrites-engine observe summary <slug>
+devrites-engine orient <slug>
+devrites-engine observe slice <slug> <SLICE-ID>
+devrites-engine next [slug]
+devrites-engine handoff [slug]
+devrites-engine context [slug] (--phase <p>|--skill <name>) [--role <r>]
+devrites-engine metrics record <slug> --phase <p> --event <e>
+devrites-engine metrics summary [slug]
+devrites-engine dispatch <slug> <open|start|seal|return|status|abandon>
+devrites-engine parallel <subcommand>
+devrites-engine gates <subcommand> <slug>
+devrites-engine claim <add|release|list|check>
+devrites-engine note <add|list|check|rm> <slug>
 
 devrites-engine state resolve <qid> "<answer>"
+devrites-engine state merge-manifest <slug> [pred...]
 devrites-engine state close <slug>
 devrites-engine migrate <slug> [--dry-run] [--answer id=choice]
 
@@ -89,6 +115,54 @@ with the self-contained updater.
   readiness binding; only after that aggregate check passes does it verify that
   `evidence.md`, `review.md`, `seal.md`, and optional `browser-evidence.md`
   contain exactly one binding to the current candidate digest.
+- `check regression <slug>` compares the workspace's structural progress facts —
+  phase ordinal, checked `AC-###` boxes, met and abandoned ledger gates,
+  done-state slices, resolved questions, and present required artifacts —
+  against the durable `regression-baseline.json` high-water mark. A lost fact
+  prints `REGRESSION: <detail>` and exits `3`. `--update` rewrites the baseline
+  under the feature lock at a durable checkpoint and prints each regression it
+  blesses as `REGRESSION-BLESSED`; with no baseline recorded the check reports
+  `unproven` and exits `0`. Recommended placement: compare on a cold resume or
+  scheduled wake before acting on durable state, ratchet after a landed slice
+  checkpoint or phase advance, and treat `BLOCKED` at Seal as NO-GO; `--update`
+  never excuses an unreconciled regression.
+- `check drift <slug>` attributes readiness-input drift to the exact artifact.
+  `--record` snapshots per-input SHA-256 digests into `readiness-inputs.json`
+  under the feature lock after Vet records the aggregate binding; a later
+  compare prints `DRIFT: <path> <changed|missing|added>` per differing input.
+  Without a baseline it falls back to the `eng-review.md` aggregate binding and
+  lists inputs modified after that file as candidates. Advisory: drift is
+  reported, never blocked (a change is legal as a dated delta through the
+  owning rite); a corrupt baseline exits `3`.
+- `detect commands [--root <dir>] [--json]` resolves the repository's own
+  command wiring — Makefile targets first, then `package.json` scripts, then
+  language-manifest fallbacks — and the lockfile-derived package manager.
+  Read-only: nothing is installed or executed. Skills use it to cite real
+  commands in `gates.md` `CHECK` lines and proof steps instead of invented
+  ones; unresolved slots print `unresolved` rather than guessing.
+- `check dup [slug] [--all|--worktree|--staged|--base <ref>]` reports advisory
+  near-duplicate code clusters that survive comment stripping, literal
+  collapsing, and identifier renaming. Diff modes mark units overlapping
+  changed hunks with `*`; stable content-derived cluster hashes let
+  `.devrites/dup-ignore` dismissals survive line moves but resurface when the
+  code's structure changes. Staged mode compares index blobs and excludes
+  untracked files. Successful scans exit `0`; usage errors and unavailable or
+  partial scans exit `2`. Empty eligible input and generated exclusions are
+  explicit. This bounded heuristic produces review leads, not exhaustive proof. See `standards/duplicate-code.md` for the triage contract.
+- `claim <add|release|list|check>` manages advisory session-scoped file claims
+  in the append-only `.devrites/claims.jsonl` ledger. `add --session <id>
+  [--ttl <min>] [--reason <s>] <path>...` records write intent for a path set
+  and exits `3` naming the holder when a live claim by another session covers a
+  path; `release --session <id> --id <claim>` frees it; `list [--all]` shows
+  live (or all) claims; `check [--session <id>] <path>...` is the read-only
+  preflight. Claims coordinate concurrent same-tree sessions; they never
+  replace the one-writer-per-worktree rule in `standards/agents.md`.
+- `note <add|list|check|rm>` manages `notes.md` anchored notes: `add <slug>
+  <subject> <quote> <title> [body]` binds a note to a verbatim quote in one
+  repository file; `list`/`check` regrade each anchor `exact`/`moved`/`stale`/
+  `ambiguous`/`lost` by relocating the quote repo-wide (dependency and workspace
+  trees excluded); `check --repair` rewrites a `moved` subject; `rm` deletes by
+  `NOTE-###`. `check seal` refuses a malformed file or any non-`exact` anchor.
 
 Semantic readiness, traceability, acceptance interpretation, evidence quality,
 doubt, test quality, reviewer reconciliation, and capability interpretation
@@ -97,6 +171,22 @@ checked by the root's explicit native re-read checklist. Repository build,
 test, lint, typecheck, schema, and release commands belong to that repository
 or CI.
 
+## Acceptance ledger
+
+`gates` operates the `gates.md` ledger inside a feature workspace: one gate per
+required outcome, runnable (`CHECK`+`EXPECT`, optional `CWD`) or manual
+(`EVIDENCE` only). Subcommands: `scaffold`, `status`, `run`, `reverify`,
+`lint`, `attest <id> <note>`, `abandon <id> <why>`.
+
+A runnable gate executes only when its `(CHECK, CWD)` pair exactly matches a
+`test-plan.md` `## Build-entry preflight` row. Passing writes
+`automatic-evidence` bound to the gate definition digest; editing the gate
+marks prior evidence stale. `status` prints a stable reduction ending in
+`result: all-met|not-met|handoff|malformed`; exit `3` unless every gate is met
+and none is abandoned. `check readiness`/`check seal` enforce the same
+reduction whenever `gates.md` is a required artifact, so a partially compliant
+ledger blocks the phase exit.
+
 ## Atomic state operations
 
 `state resolve` also supports `--drop <qid> ["<reason>"]` and `--batch <file>`.

package/docs/command-map.md

@@ -40,9 +40,11 @@ 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`, `parallel select`, `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. `parallel select` returns the greedy path-disjoint subset ≤ cap from the supplied ready slices. |
-| Workspace observation | `observe summary`, `orient`, `observe slice <slug> <SLICE-ID>` | JSON workspace snapshot for agents (cursor, task graph, `artifact_budgets`, `bulk_files`); `orient` is an alias for `observe summary`. `observe slice` prints one `SLICE-###` section of `tasks.md` so Build reads a slice, not the file. |
+| Candidate and deterministic checks | `check candidate`, `check readiness [--emit-binding]`, `check seal`, `check slice <slug> <SLICE-ID>`, `check task-graph`, `check regression <slug> [--update]`, `check drift <slug> [--record]`, `check windows <slug>`, `check dup`, `check path-disjoint`, `parallel select`, `check skill-trust`, `check indexes`, `detect commands [--root <dir>] [--json]` | 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 slice` preflights one slice before wright dispatch — contract present, exact Writer allowlist paths, `Satisfies` AC ids resolvable, bounded scope — so a malformed slice fails before a writer context is spent. `check indexes` reports install manifest and optional code-index directory presence as JSON. `parallel select` returns the greedy path-disjoint subset ≤ cap from the supplied ready slices. `check regression` compares current workspace progress against the durable `regression-baseline.json` high-water mark and `--update` ratchets it at a checkpoint, so a lost slice, unchecked criterion, or reopened question fails closed instead of passing silently. `check windows` scans the feature diff for newly introduced deferral markers (TODO/FIXME/skipped test/stub idioms) and fails when any lacks a `windows.md` waiver row — silent deferrals block the seal. `check dup` reports advisory near-duplicate clusters that survive renaming (normalized token shingles, transitive clusters, distance-boosted rank, `*`-marked diff overlap, stable content hashes, `.devrites/dup-ignore` dismissal ledger) — leads for reviewer triage, never a gate. `check drift` attributes readiness-input drift to the exact artifact: `--record` snapshots per-input SHA-256 digests into `readiness-inputs.json` under the feature lock, and a later compare names each `changed`/`missing`/`added` input (falling back to the aggregate `eng-review.md` binding plus mtime candidates when no baseline exists) so a stale-binding repair starts at the right file — advisory, never a gate. `detect commands` resolves the repository's own test/lint/vet/build commands (Makefile targets, then `package.json` scripts, then language-manifest fallbacks, plus the lockfile-derived package manager) so `gates.md` `CHECK` lines and proof steps cite real wiring instead of invented commands — read-only, no installs, no execution. |
+| Workspace observation | `observe summary`, `orient`, `observe slice <slug> <SLICE-ID>`, `next`, `handoff` | JSON workspace snapshot for agents (cursor, task graph, `artifact_budgets`, `bulk_files`); `orient` is an alias for `observe summary`. `observe slice` prints one `SLICE-###` section of `tasks.md` so Build reads a slice, not the file. `next` prints the minimal remaining lifecycle path plus advisory skips (e.g. clarify at zero open questions). `handoff` emits the deterministic resume record (cursor, `awaiting_human`, blocking question gates, ledger reduction with unmet/stale ids, dead ends, read-next order) — the `/rite-handoff` spine and compaction-fallback entry. |
+| Context packets, dispatch waves, metrics, claims, notes | `context [slug] (--phase <p> \| --skill <name>) [--role <r>] [--trigger a,b]`, `dispatch <slug> <open\|start\|seal\|return\|status\|abandon>`, `metrics record`, `metrics summary`, `claim <add\|release\|list\|check>`, `note <add\|list\|check\|rm>` | `context` emits one deduplicated read-set bundle per phase/role/skill from each skill's `loads:` manifest — a dispatch target reads it instead of selecting files; `--skill` works without a workspace when `--out` is given. `dispatch` owns the launch-wave barrier (seal needs a handle per role; return needs seal) and auto-records dispatch/return metrics. `metrics` owns the append-only `metrics.jsonl` ledger. `claim` owns the append-only `.devrites/claims.jsonl` ledger — advisory, session-scoped file claims with TTL so concurrent same-tree sessions see each other's write intent before edits collide (conflict exits 3; never a substitute for one-writer-per-worktree). `note` owns the anchored `notes.md` ledger — notes bound to verbatim code quotes, regraded `exact`/`moved`/`stale`/`ambiguous`/`lost` as the code drifts; `check seal` refuses non-`exact` anchors. `check diff-scope` is the mechanical changed-paths ⊆ allowlist gate run before reviewer dispatch. |
 | Atomic workspace state | `state resolve`, `state merge-manifest`, `state close`, `migrate [--dry-run] [--answer id=choice]` | Go owns answer/drop/batch resolution, the recorded predecessor-chain manifest union for a release milestone, transactional close, and fail-closed v5 schema normalization. |
+| Acceptance ledger | `gates scaffold`, `gates status`, `gates run [--timeout N]`, `gates reverify [--timeout N]`, `gates lint [--strict]`, `gates attest <id> <note>`, `gates abandon <id> <why>` | Go owns the `gates.md` ledger: per-outcome gates whose runnable `CHECK`/`CWD` must exactly match a `test-plan.md` Build-entry preflight row, evidence bound to the gate definition digest (stale = unmet), `ABANDON:` handoffs, and oracle lint. Readiness/seal require a parse-clean, all-met ledger whenever `gates.md` is a required artifact. |
 | 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`. |

package/docs/engine/commands.md

@@ -17,14 +17,35 @@ workflow strategy.
 | `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. |
 | `parallel select --cap <1-10> [--root <dir>] [<json-file> | -]` | Choose the greedy path-disjoint subset ≤ cap from supplied ready slices. |
+| `parallel <create\|integrate\|cleanup\|status\|abort\|lease-read\|lease-write\|lease-clear\|record-green>` | Deterministic parallel worktree leases, integration, and cleanup for parallel writer batches. |
 | `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 regression <slug> [--update]` | Compare the workspace's structural progress facts (phase ordinal, checked ACs, met/abandoned gates, done slices, resolved questions, present artifacts) against the recorded `regression-baseline.json` high-water mark; `--update` ratchets the baseline forward under the feature lock and prints each blessed regression. |
+| `check drift <slug> [--record]` | Attribute readiness-input changes to the exact artifact. `--record` writes the per-input `readiness-inputs.json` digest baseline under the feature lock; without it the workspace diffs current inputs against that baseline (or falls back to the aggregate binding recorded in `eng-review.md`). Advisory: exit `0` on drift; a corrupt baseline exits `3`. |
+| `check windows <slug> [--worktree\|--staged\|--base <ref>]` | Fail on deferral markers (TODO/FIXME/XXX/HACK, skipped-test and stub idioms) the change's added lines introduce without a waiver row in the workspace's `windows.md`. |
+| `check dup [slug] [--all\|--worktree\|--staged\|--base <ref>] [--min-lines n] [--threshold f] [--ignore-file <path>] [--limit n] [--exclude <csv>]` | Report near-duplicate code clusters that survive comment stripping, literal collapsing, and identifier renaming — token-shingle matches chained into segments, clustered transitively, ranked with bounded path/line-distance boosts. Diff modes mark units overlapping changed hunks with `*`; stable content-derived cluster hashes let `.devrites/dup-ignore` dismissals survive line moves but resurface on structural edits. Staged mode reads index blobs and excludes untracked files. Bounded heuristic: successful scans/leads exit `0`; usage, unavailable input, and partial scans exit `2`. |
+| `check slice <slug> <SLICE-ID>` | Pre-dispatch lint of one slice's wright contract: contract present, exact Writer allowlist paths, resolvable `Satisfies` AC ids, bounded scope. |
+| `check diff-scope <slug> --allow <csv>\|--allow-file <path> [--worktree\|--staged\|--base <ref>]` | Verify the changed-path set stays inside the declared allowlist; the mechanical gate run before reviewer dispatch. |
 | `check skill-trust <path>` | Scan one skill/agent Markdown file for structural trust violations. |
+| `check indexes [--root <dir>]` | Report install manifest and code-index presence as JSON. |
 | `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. |
+| `orient <slug>` | Alias for `observe summary`. |
+| `observe slice <slug> <SLICE-ID>` | Print one `SLICE-###` section of `tasks.md` so Build reads a slice, not the file. |
+| `next [slug]` | Print the minimal remaining lifecycle path plus advisory skips. |
+| `handoff [slug]` | Emit the deterministic resume record: cursor fields, `awaiting_human`, open `questions.md` gate kinds, the `gates.md` reduction with unmet/stale/abandoned ids, `decisions.md` dead ends, missing required files, and the canonical read-next order. Read-only; the `/rite-handoff` spine and the compaction-fallback entry point. |
+| `context [slug] (--phase <p>\|--skill <name>) [--role <r>] [--trigger a,b]` | Emit one deduplicated read-set bundle per phase/role/skill from each skill's `loads:` manifest; `--skill` works without a workspace when `--out` is given. |
+| `dispatch <slug> <open\|start\|seal\|return\|status\|abandon>` | Launch-wave barrier for parallel dispatch: seal needs a handle per role, return needs seal; start/return auto-record metrics. |
+| `metrics record <slug> --phase <p> --event <e> [--role r] [--bytes n] [--note s]` | Append an event to the workspace's `metrics.jsonl` ledger. |
+| `metrics summary [slug]` | Reduce `metrics.jsonl` into a per-phase roll-up. |
+| `claim <add\|release\|list\|check>` | Advisory session-scoped file claims in `.devrites/claims.jsonl` (append-only). `add` records intent to write a path set with a TTL (1–240 min, default 30); a live claim by another session exits `3` and names the holder. `release` appends a release event owned by the claiming session. `list` shows live claims (`--all` includes expired/released). `check` is the read-only preflight for a path set. Coordination aid only — never a substitute for one-writer-per-worktree. |
+| `note <add\|list\|check\|rm> <slug> ...` | Anchored workspace notes in `notes.md`: `add <slug> <subject> <quote> <title> [body]` binds a note to a verbatim quote in one repository file and assigns `NOTE-###`; `list` and `check` regrade each anchor `exact`/`moved`/`stale`/`ambiguous`/`lost` by searching the repo for the quote (dependency and workspace trees excluded); `check --repair` rewrites a `moved` subject to its new file; `rm` deletes by ID. `check seal` refuses a malformed `notes.md` and any non-`exact` anchor. |
+| `gates <scaffold\|status\|run\|reverify\|lint\|attest\|abandon> <slug>` | Operate the `gates.md` acceptance ledger: seed per-AC gates, execute runnable gates bound to `test-plan.md` preflight rows, attest manual gates, and reduce to `all-met`/`not-met`/`handoff`/`malformed`. |
 | `state resolve <qid> "<answer>"` | Resolve an open question and update `questions.md` plus `state.md` atomically. |
+| `state merge-manifest <slug> [pred...]` | Fold the recorded predecessor chain's manifests into the release candidate manifest. |
 | `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. |
+| `detect commands [--root <dir>] [--json]` | Resolve the repository's own test/lint/vet/build commands: explicit Makefile targets first, then `package.json` scripts, then language-manifest fallbacks, plus the lockfile-derived package manager. Read-only, no installs, no execution. |
 | `version` | Print the engine version. |
 
 `help`, `-h`, and `--help` print this operational inventory. Each operational

package/docs/engine/state-schema.md

@@ -5,7 +5,7 @@ human-editable files remain authoritative; the engine has no database or
 semantic cache.
 
 <!-- authority:schema-version:start -->
-`schemaVersion: 3`.
+`schemaVersion: 4`.
 <!-- authority:schema-version:end -->
 
 For root selection, supported legacy cursors, and the full artifact layout, see

package/docs/engine/workspace-schema.md

@@ -51,8 +51,9 @@ budgets, IDs, and read order live in
 ```
 
 Conditional artifacts include strategy, design/browser evidence, drift,
-handoff, references, flows, and other phase-specific Markdown named by the
-canonical schema.
+handoff, references, flows, `notes.md` anchored notes (written only via
+`devrites-engine note`; non-`exact` anchors block `check seal`), and other
+phase-specific Markdown named by the canonical schema.
 
 ## Build-readiness binding
 
@@ -76,6 +77,13 @@ its target phase requires `eng-review.md`, and Seal verifies it again. A missing
 malformed, duplicate, or stale line routes through `/rite-vet`; replacing the
 line without rerunning Vet is not review.
 
+`devrites-engine check drift <slug> --record` may additionally snapshot each
+readiness input's SHA-256 into `readiness-inputs.json` in the workspace. That
+baseline is advisory and never a gate input: a later `check drift` names each
+`changed`/`missing`/`added` input so a stale-binding repair starts at the right
+file. Without the baseline the check falls back to comparing the aggregate
+binding recorded in `eng-review.md`.
+
 ## Candidate manifest and bindings
 
 `touched-files.md` contains exactly one `## Touched files` heading and exactly

package/docs/usage.md

@@ -70,6 +70,8 @@ Project-root sentinel (outside the workspace):
 |---|---|---|
 | `.devrites/AFK` | you (presence = AFK mode active) | optional YAML: `max_slices`, `notify`, `allow_gates`. Empty file = AFK with defaults. See [`pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md`](../pack/.claude/skills/devrites-lib/reference/standards/afk-hitl.md). |
 | `.devrites/CHECKPOINT` | unused as a gate | reserved path (not a candidate). After Independent Build review and fail-on-red proof are green (not when a wright returns), `/rite-build` / `/rite-prove` / `/rite-polish` / `/rite-review` land a local `WIP(<slug>): <imperative summary>` commit (serial: checkpoint git recipe or no-op if nothing staged; parallel: `devrites-engine parallel integrate`); `/rite-ship` later collapses an eligible WIP run. See [`pack/.claude/skills/rite-build/reference/checkpoint.md`](../pack/.claude/skills/rite-build/reference/checkpoint.md). |
+| `.devrites/dup-ignore` | you (optional) | One `check dup` cluster hash per line with a `#` reason — the dismissal ledger. Content-derived hashes survive line moves but resurface on structural edits. See [`pack/.claude/skills/devrites-lib/reference/standards/duplicate-code.md`](../pack/.claude/skills/devrites-lib/reference/standards/duplicate-code.md). |
+| `.devrites/claims.jsonl` | `devrites-engine claim add` | Append-only advisory file claims: `{id, session, paths, reason, claimed_at, expires_at}` plus release events. Session-scoped and TTL-bounded — per-checkout state, so gitignore it (a committed ledger exports stale claims to every clone). See [`standards/agents.md`](../pack/.claude/skills/devrites-lib/reference/standards/agents.md). |
 
 The shape of this directory is also documented in
 [`flow.md` § Workspace state model](flow.md#7-workspace-state-model).

package/engine/commands.go

@@ -30,7 +30,7 @@ func rootModeFor(command string, args []string) rootMode {
 	}
 	subcommand := firstRootOperand(args)
 	switch command {
-	case "secret-scan", "open-visual":
+	case "secret-scan", "open-visual", "detect":
 		return rootLenient
 	case "state":
 		switch subcommand {
@@ -38,18 +38,24 @@ func rootModeFor(command string, args []string) rootMode {
 			return rootStrict
 		}
 		return rootUnused
-	case "migrate":
+	case "migrate", "gates":
 		return rootStrictUsage
 	case "check":
 		switch subcommand {
-		case "candidate", "readiness", "seal", "task-graph":
+		case "candidate", "readiness", "seal", "task-graph", "diff-scope", "slice", "regression", "windows", "drift":
 			return rootStrictUsage
-		case "indexes":
+		case "indexes", "dup":
 			return rootLenient
 		}
 		return rootUnused
-	case "orient":
+	case "orient", "next", "context", "metrics", "dispatch", "handoff", "note":
 		return rootStrictUsage
+	case "claim":
+		switch subcommand {
+		case "add", "release":
+			return rootStrictUsage
+		}
+		return rootLenient
 	case "observe":
 		switch subcommand {
 		case "summary", "slice":

package/engine/help.go

@@ -9,7 +9,7 @@ import (
 )
 
 const (
-	checkUsage = `usage: devrites-engine check <candidate|readiness|seal|path-disjoint|task-graph|skill-trust|indexes> ...
+	checkUsage = `usage: devrites-engine check <candidate|readiness|seal|path-disjoint|task-graph|slice|diff-scope|skill-trust|indexes|regression|drift|windows|dup> ...
 
   check candidate <slug>
   check readiness <slug>
@@ -17,8 +17,14 @@ const (
   check seal <slug>
   check path-disjoint [--root <dir>] [<json-file>|-]
   check task-graph <slug>
+  check slice <slug> <SLICE-ID>
+  check diff-scope <slug> --allow <csv> | --allow-file <path> [--worktree|--staged|--base <ref>]
   check skill-trust <path>
   check indexes [--root <dir>]
+  check regression <slug> [--update]
+  check drift <slug> [--record]
+  check windows <slug> [--worktree|--staged|--base <ref>]
+  check dup [slug] [--all|--worktree|--staged|--base <ref>]
 `
 
 	stateUsage = `usage: devrites-engine state <resolve|merge-manifest|close> ...
@@ -37,7 +43,24 @@ const (
 `
 
 	orientUsage  = "usage: devrites-engine orient [slug]"
-	migrateUsage = "usage: devrites-engine migrate <slug> [--dry-run] [--answer id=choice]"
+	nextUsage    = "usage: devrites-engine next [slug]"
+	handoffUsage = "usage: devrites-engine handoff [slug]"
+	contextUsage = `usage: devrites-engine context [slug] (--phase <p> | --skill <name>) [--role <r>] [--trigger a,b] [--skills-root <dir>] [--out <path>]`
+	metricsUsage = `usage: devrites-engine metrics <record|summary> ...
+
+  metrics record <slug> --phase <p> --event <e> [--role r] [--bytes n] [--note s]
+  metrics summary [slug]
+`
+	dispatchUsage  = `usage: devrites-engine dispatch <slug> <open|start|seal|return|status|abandon> [--phase p] [--wave w] [--role r] [--handle h] [--reason s]`
+	claimUsageText = `usage: devrites-engine claim <add|release|list|check> ...
+
+  claim add --session <id> [--ttl <minutes>] [--reason <s>] <path>...
+  claim release --session <id> --id <claim-id>
+  claim list [--session <id>] [--all]
+  claim check [--session <id>] <path>...
+`
+	diffScopeUsage = `usage: devrites-engine check diff-scope <slug> --allow <csv> | --allow-file <path> [--worktree|--staged|--base <ref>] [--allow-empty] [--cwd <dir>]`
+	migrateUsage   = "usage: devrites-engine migrate <slug> [--dry-run] [--answer id=choice]"
 	// scanCmdUsage is help text for `secret-scan`. The identifier must not
 	// contain "secret": gosec G101 treats secret* string consts as credentials.
 	scanCmdUsage        = "usage: devrites-engine secret-scan [--staged] [--stdin] [slug]"
@@ -47,13 +70,37 @@ const (
 	readinessUsage      = "usage: devrites-engine check readiness <slug>\n       devrites-engine check readiness --emit-binding <slug>"
 	sealUsage           = "usage: devrites-engine check seal <slug>"
 	taskGraphUsage      = "usage: devrites-engine check task-graph <slug>"
+	sliceCheckUsage     = "usage: devrites-engine check slice <slug> <SLICE-ID>"
 	skillTrustUsage     = "usage: devrites-engine check skill-trust <path>"
 	indexesUsage        = "usage: devrites-engine check indexes [--root <dir>]"
+	regressionUsageLine = "usage: devrites-engine check regression <slug> [--update]"
+	driftUsageLine      = "usage: devrites-engine check drift <slug> [--record]"
+	detectUsageLine     = "usage: devrites-engine detect commands [--root <dir>] [--json]"
+	windowsUsageLine    = "usage: devrites-engine check windows <slug> [--worktree|--staged|--base <ref>] [--cwd <dir>]"
+	dupUsageLine        = "usage: devrites-engine check dup [slug] [--all|--worktree|--staged|--base <ref>] [--min-lines n] [--threshold f] [--ignore-file <path>] [--limit n] [--exclude <csv>] [--phase p] [--cwd <dir>]"
 	resolveUsage        = `usage: devrites-engine state resolve <qid> "<answer>"  |  state resolve --drop <qid> ["<reason>"]  |  state resolve --batch <file>`
 	mergeManifestUsage  = "usage: devrites-engine state merge-manifest <slug> [<predecessor>...]"
 	closeUsage          = "usage: devrites-engine state close <slug>"
 	observeSliceUsage   = "usage: devrites-engine observe slice <slug> <SLICE-ID>"
 	observeSummaryUsage = "usage: devrites-engine observe summary [slug]"
+	gatesFamilyUsage    = `usage: devrites-engine gates <scaffold|status|run|reverify|lint|attest|abandon> <slug> ...
+
+  gates scaffold <slug>            Create gates.md from spec.md AC ids (only when absent)
+  gates status <slug>              Reduce the ledger without executing; exit 3 unless ALL MET
+  gates run <slug> [--timeout N]   Execute unmet runnable gates and record evidence
+  gates reverify <slug> [--timeout N]  Re-execute every runnable gate, demoting stale passes
+  gates lint <slug> [--strict]     Audit oracle quality without executing
+  gates attest <slug> <id> <note>  Record human evidence on a manual gate
+  gates abandon <slug> <id> <why>  Record a terminal ABANDON handoff on a gate
+`
+	noteFamilyUsage = `usage: devrites-engine note <add|list|check|rm> <slug> ...
+
+  note add <slug> <subject> <quote> <title> [body]
+                                  Anchor a workspace note to verbatim code text
+  note list <slug>                List notes.md entries with their current grade
+  note check <slug> [--repair]    Regrade every anchor; --repair rewrites moved subjects
+  note rm <slug> <NOTE-id>        Remove a note
+`
 )
 
 func isHelpFlag(arg string) bool {
@@ -89,7 +136,7 @@ func shouldPrintHelp(args []string) bool {
 		return true
 	}
 	switch args[0] {
-	case "check", "state", "observe", "parallel":
+	case "check", "state", "observe", "parallel", "gates", "claim", "detect", "note", "metrics", "handoff", "context", "orient", "migrate":
 		return len(args) >= 2 && args[1] == "help"
 	default:
 		return false
@@ -129,14 +176,32 @@ func commandHelp(args []string) (string, bool) {
 		return helpObserve(args[1:]), true
 	case "orient":
 		return orientUsage, true
+	case "next":
+		return nextUsage, true
+	case "handoff":
+		return handoffUsage, true
+	case "context":
+		return contextUsage, true
+	case "metrics":
+		return metricsUsage, true
+	case "dispatch":
+		return dispatchUsage, true
+	case "claim":
+		return claimUsageText, true
 	case "parallel":
 		return parallel.CommandUsage(firstNonHelp(args[1:])), true
+	case "gates":
+		return gatesFamilyUsage, true
+	case "note":
+		return noteFamilyUsage, true
 	case "migrate":
 		return migrateUsage, true
 	case "secret-scan":
 		return scanCmdUsage, true
 	case "open-visual":
 		return openVisualUsage, true
+	case "detect":
+		return detectUsageLine, true
 	case "version", "--version":
 		return versionUsage, true
 	default:
@@ -156,10 +221,22 @@ func helpCheck(rest []string) string {
 		return parallel.CommandUsage("path-disjoint")
 	case "task-graph":
 		return taskGraphUsage
+	case "slice":
+		return sliceCheckUsage
+	case "diff-scope":
+		return diffScopeUsage
 	case "skill-trust":
 		return skillTrustUsage
 	case "indexes":
 		return indexesUsage
+	case "regression":
+		return regressionUsageLine
+	case "drift":
+		return driftUsageLine
+	case "windows":
+		return windowsUsageLine
+	case "dup":
+		return dupUsageLine
 	default:
 		return checkUsage
 	}

package/engine/help_test.go

@@ -16,7 +16,7 @@ func TestCommandHelp(t *testing.T) {
 		{args: []string{"-h"}, want: "Usage:"},
 		{args: []string{"help"}, want: "Usage:"},
 		{args: []string{"check", "--help"}, want: "check candidate <slug>"},
-		{args: []string{"check", "help"}, want: "check <candidate|readiness|seal|path-disjoint|task-graph|skill-trust|indexes>"},
+		{args: []string{"check", "help"}, want: "check <candidate|readiness|seal|path-disjoint|task-graph|slice|diff-scope|skill-trust|indexes|regression|drift|windows|dup>"},
 		{args: []string{"check", "candidate", "--help"}, want: "check candidate <slug>"},
 		{args: []string{"check", "readiness", "-h"}, want: "check readiness --emit-binding <slug>"},
 		{args: []string{"check", "seal", "--help"}, want: "check seal <slug>"},
@@ -24,6 +24,9 @@ func TestCommandHelp(t *testing.T) {
 		{args: []string{"check", "task-graph", "--help"}, want: "check task-graph <slug>"},
 		{args: []string{"check", "skill-trust", "--help"}, want: "check skill-trust <path>"},
 		{args: []string{"check", "indexes", "--help"}, want: "check indexes [--root <dir>]"},
+		{args: []string{"check", "dup", "--help"}, want: "check dup [slug]"},
+		{args: []string{"check", "drift", "--help"}, want: "check drift <slug>"},
+		{args: []string{"detect", "--help"}, want: "detect commands [--root <dir>]"},
 		{args: []string{"state", "--help"}, want: "state <resolve|merge-manifest|close>"},
 		{args: []string{"state", "-h"}, want: "state resolve"},
 		{args: []string{"state", "help"}, want: "state close <slug>"},
@@ -38,6 +41,9 @@ func TestCommandHelp(t *testing.T) {
 		{args: []string{"observe", "summary", "--help"}, want: "observe summary"},
 		{args: []string{"observe", "slice", "--help"}, want: "observe slice <slug> <SLICE-ID>"},
 		{args: []string{"orient", "--help"}, want: "orient [slug]"},
+		{args: []string{"handoff", "--help"}, want: "handoff [slug]"},
+		{args: []string{"claim", "--help"}, want: "claim <add|release|list|check>"},
+		{args: []string{"claim", "help"}, want: "claim <add|release|list|check>"},
 		{args: []string{"migrate", "--help"}, want: "migrate <slug>"},
 		{args: []string{"secret-scan", "--help"}, want: "secret-scan [--staged] [--stdin]"},
 		{args: []string{"open-visual", "--help"}, want: "open-visual <path-or-name>"},