devrites 5.11.0 → 5.12.0

package/pack/generated/pi/skills/devrites-lib/reference/standards/data-integrity.md

@@ -1,5 +1,7 @@
 # Data integrity
 
+> Applies when: a change writes durable state, alters schema, migrates or backfills data.
+
 Load this when a change writes durable state, changes a schema, migrates or backfills
 records, changes retention, can expose one tenant's data to another, or feeds a
 model/feature pipeline (training data, features, labels, embeddings). Data work is
@@ -61,6 +63,12 @@ Treat a partial migration as an explicit mixed-version state: identify migrated/
 rows, compatible readers/writers, resume cursor, rejected records, and reconciliation before
 contracting the old path.
 
+**Green types ≠ applied schema.** When the change touches ORM models, schema files, or
+migration directories, `compiles`/`typechecks` prove nothing about the live store —
+types can generate from config while the database is still old. The plan carries the
+apply step (migrate/push) as an explicit blocking task; proof records the post-apply
+state, not just the passing build.
+
 ## Writes, retries, and concurrency
 
 - Make duplicate requests/jobs/events converge on one effect with a durable idempotency
@@ -85,14 +93,28 @@ contracting the old path.
 - Derive tenant/subject scope from authenticated server-side context, not a caller's
   free-form id. Apply it to reads, writes, indexes, caches, jobs, exports, logs, and RAG
   retrieval.
-- Prove cross-tenant denial with two distinct tenants and data; a single-tenant happy
-  path cannot detect leakage.
+- Prove cross-tenant denial with two distinct principals/tenants and existing data.
+  An allowed control must reach the resource; the other principal must get no
+  forbidden disclosure or effect. Two 404s against a missing fixture prove nothing.
 - Minimize collected and returned fields. Define deletion/retention behavior for
   primary data and derived copies, and do not claim deletion while recoverable copies
   remain without a documented policy basis.
 - Never place secrets or sensitive records in migration logs, rejected-row dumps, or
   evidence artifacts.
 
+## Restore and replay preserve current policy
+
+Before restored or replayed data becomes visible, reconcile it with current
+retention/deletion records and authorization policy. Old backups, events and
+indexes must not resurrect deleted records or revoked grants. Name the durable
+deletion/revocation source and how recovery catches up with concurrent changes;
+if reconciliation cannot be established, keep recovered data inaccessible.
+
+Rehearse a snapshot/event from before deletion and revocation, then restore or
+replay it under current policy. Assert the deleted record stays absent, a
+revoked principal is denied, and an authorized control still reaches retained
+data. Counts or successful restore commands alone do not prove these invariants.
+
 ## Required plan and proof
 
 For each applicable change, `plan.md` records:

package/pack/generated/pi/skills/devrites-lib/reference/standards/debug-recovery.md

@@ -1,5 +1,7 @@
 # Debug recovery (async wait discipline)
 
+> Applies when: polling async readiness, timeouts, retries, stuck-wait triage.
+
 Triggered standard for polling async readiness without blind sleep. Skill owner:
 [`devrites-debug-recovery`](../../../devrites-debug-recovery/SKILL.md).
 
@@ -15,6 +17,18 @@ When waiting for async readiness (server start, job completion, browser signal):
 **Failing case:** `sleep(5)` loop with no captured last signal → recovery incomplete;
 treat as flaky/unproven.
 
+## Service readiness (spawned process)
+
+When the thing waited on is a process the task started (dev server, build watch,
+test service):
+
+- Retain its handle/PID and separate stdout/stderr captures from the start.
+- Poll readiness **and** process liveness together: an early exit is an immediate
+  fail with exit code and log tail — never keep polling a dead process.
+- On timeout, capture the last signal (log tail, bound port, exit status) before teardown.
+- Clean up only the process tree this task started; never kill by port or name pattern
+  that could match a neighbor's process.
+
 ## Diagnosis write freeze
 
 During diagnosis, writable paths are the reproduction harness plus the files

package/pack/generated/pi/skills/devrites-lib/reference/standards/definition-of-done.md

@@ -1,5 +1,7 @@
 # Definition of Done
 
+> Applies when: declaring any task, phase, or slice complete.
+
 Acceptance criteria prove the requested behavior; this bar proves the change is
 shippable. Phase owners keep the checks — this file is the index, not a second list.
 
@@ -9,11 +11,15 @@ re-judge from this table alone.
 | Required | Owner | Failing case |
 | --- | --- | --- |
 | Each AC names a stored evidence path (command or artifact) | [`testing.md`](testing.md), `rite-prove` | An AC is checked off with no path in `evidence.md` |
+| Every explicit request maps to an artifact, test, or observed command | `rite-prove`, `rite-seal` | Numbered asks counted done by proxy — green suite, manifest presence, effort spent — with no per-requirement evidence map |
+| Runnable required checks ran to a recorded outcome | [`test-proof-checklist.md`](test-proof-checklist.md), [`debug-recovery.md`](debug-recovery.md) | A failed, timed-out, or unstartable check reported as "unrelated"/omitted instead of a named blocker |
 | Discriminating tests for changed behavior | [`testing.md`](testing.md) | Suite green; revert of the change would still be green |
 | Fresh runtime/build/test/browser records | `rite-prove`, [`browser-proof-checklist.md`](browser-proof-checklist.md) | Proof claimed from stale or unrun commands |
 | Scope-clean diff | [`code-review.md`](code-review.md) | Unscoped edits or a hidden second system remain |
 | Open hard gates closed | [`afk-hitl.md`](afk-hitl.md), `rite-seal` | HITL, red tests, drift, or NO-GO still open |
 | Rollback named for risky work | [`data-integrity.md`](data-integrity.md) | "revert if needed" with no trigger/procedure/proof |
 | Docs/ADR for public behavior | [`documentation.md`](documentation.md) | Command or contract changed; docs did not |
+| Written artifacts re-read from disk before handoff | [`workspace-artifact-schema.md`](../workspace-artifact-schema.md), phase owner | Report describes a spec/plan/evidence state the file on disk does not contain |
+| Recipient-path execution | [`verification-methods.md`](verification-methods.md), `rite-prove` | Tests run against the working tree; the packaged artifact was never installed, opened, or navigated as its recipient would |
 
 Use from `rite-vet`, `rite-build`, `rite-prove`, `rite-seal`, and `rite-quick`.

package/pack/generated/pi/skills/devrites-lib/reference/standards/deprecation.md

@@ -1,11 +1,29 @@
 # Deprecation & migration
 
+> Applies when: removing behavior, breaking a public API, migrating data or config.
+
 Removing behavior is riskier than adding it because hidden consumers may depend on observable quirks as well as documented contracts (Hyrum's law). Destructive migration, public-API breakage, auth changes, and data-loss paths always use the irreversible-risk pause in [`afk-hitl.md`](afk-hitl.md).
 
 ## Prove it is unused
 
 Find callers, subscribers, stored data, external clients, and scheduled jobs with code intelligence, then confirm runtime usage through [`observability.md`](observability.md). Static absence alone does not prove zero consumers. If zero usage cannot be proven, deprecate instead of deleting.
 
+### Dead-code confidence
+
+A "zero dependents" report is a *lead* graded by confidence, not a verdict —
+the grade names what could still secretly consume the symbol:
+
+| Confidence | Shape | Disposition |
+| --- | --- | --- |
+| **high** | Unexported symbol with zero references; or exported with zero dependents in a non-aggregator file | Deletion candidate after the usual runtime check |
+| **medium** | Exported from a barrel/index file (external consumers invisible); sole dependent is a test file | Verify external/package consumers first; test-only dependents may justify removal |
+| **low** | Exported from a package entry point (public API surface); interface/type with zero dependents (`import type` invisible); lives in a dynamic-binding directory (`routes/`, `pages/`, `handlers/`, `commands/`, `middleware/`, `api/`) | Deprecate, never delete on static evidence alone |
+
+Low-confidence leads record the *reason* ("barrel export — may feed external
+consumers"), never a bare "unused". Runtime-confirmation rules for dynamic
+edges live in [`code-navigation.md`](code-navigation.md) § What the static
+graph cannot see.
+
 ## Expand → migrate → contract
 
 Use three independently shippable and reversible steps:

package/pack/generated/pi/skills/devrites-lib/reference/standards/developer-experience.md

@@ -1,5 +1,7 @@
 # Developer experience
 
+> Applies when: shipping a surface another engineer uses: API, CLI, SDK, config.
+
 When a change ships a surface another engineer has to *use* (a public API, a CLI, an SDK
 or library, a webhook, a config/env contract, an error message, or the getting-started path
 that introduces all of them) the developer using it is a user, and their experience is part

package/pack/generated/pi/skills/devrites-lib/reference/standards/development-workflow.md

@@ -1,5 +1,7 @@
 # Development workflow
 
+> Applies when: slicing work, committing, keeping trunk green.
+
 Ship small, integrate often, and keep the main branch releasable. Workflow phase order comes from the engine manifest, not this standard.
 
 ## Work in small batches

package/pack/generated/pi/skills/devrites-lib/reference/standards/documentation.md

@@ -1,5 +1,7 @@
 # Documentation
 
+> Applies when: writing docs, comments, READMEs; recording decisions.
+
 Document intent/decisions; public inputs, outputs, errors, and gotchas; non-obvious
 constraints; and real build/test/run commands. Update with behavior; prefer one runnable
 example. Do not restate code or types.
@@ -41,3 +43,13 @@ Promotion is maintenance of an existing authority, not a new memory system.
    required. Never create a learning ledger, index, queue, score, or parallel authority.
 
 Long reference material stays behind its existing on-demand route.
+
+## Living documents
+
+Canonical documents are updated, not appended to. When truth changes, rewrite the
+owning section in the present tense; sealed artifacts take dated deltas through the
+owning rite instead ([`core.md`](core.md) #4). Pick a steering verb deliberately —
+`create`, `consolidate`, `split`, `trim`, `retire` — rather than letting the last-opened
+file absorb every new topic. Document what code cannot own (contracts, invariants,
+decisions, rationale); a doc that restates implementation drifts the day it lands.
+Sparse is correct — never pad a document to look complete.

package/pack/generated/pi/skills/devrites-lib/reference/standards/duplicate-code.md

@@ -0,0 +1,118 @@
+# Duplicate code
+
+> Applies when: a review or polish pass needs near-duplicate leads that survive
+> renaming, or a dup finding needs a dismissal that persists.
+
+`devrites-engine check dup` is the deterministic scanner. It normalizes source
+(strips comments, collapses strings, canonicalizes identifiers and literals),
+matches token shingles between files, clusters overlapping matches, and prints
+advisory clusters — **leads**, not findings. The engine never judges whether a
+cluster is worth merging; that decision is semantic and belongs to the
+reviewer. Successful scans exit 0 even with clusters; usage and operational
+errors, including incomplete scans, exit 2.
+
+## Running it
+
+```text
+devrites-engine check dup [slug] --worktree|--staged|--base <ref>|--all
+    [--min-lines n] [--threshold f] [--ignore-file <path>]
+    [--limit n] [--exclude <csv>]
+```
+
+- `--staged` / `--worktree` / `--base <ref>`: scan the repo, then print only
+  clusters with a unit overlapping the diff's changed hunks, marked `*`. Pick
+  the mode matching the diff under review: `--base <ref>` when the feature's
+  commits are landed (the common `/rite-review` case), `--staged`/`--worktree`
+  for uncommitted diffs. `--staged` reads index blobs for every comparator and
+  excludes untracked files, regardless of working-tree edits or deletions.
+  Keep the index stable during the scan. Other modes read working-tree bytes.
+- `--all`: whole-repo triage, includes untracked source files. Use in
+  `/rite-polish` or `/devrites-audit` passes.
+- `--min-lines` (default 8): minimum meaningful overlap. Lower it for tiny
+  helper-heavy languages, raise it to cut boilerplate noise.
+- `--threshold` (default 0.6): minimum similarity score per reported pair.
+- `--exclude`: extra path prefixes to skip (fixtures, generated code).
+- `dup: scanned … units` in the header is the coverage line — a scan of 3
+  files in a 300-file repo proves nothing.
+
+## Evidence limits
+
+This is a bounded heuristic, not exhaustive duplicate detection. The scanner
+limits eligible files (8,192), source bytes (64 MiB total, 1 MiB per file),
+Git listing/diff output (16 MiB), repeated-shingle postings, pair anchors, and
+reported clusters. Normalization loses language semantics; a successful scan
+with no leads does not prove the repository has no duplication.
+
+No eligible input and intentional generated exclusions are reported explicitly
+with exit 0, without claiming a successful source scan. Unreadable/non-regular
+source, unresolved index entries, Git failures, and input resource limits exit 2.
+A partial scan may print available leads, but never an `ok` verdict or a success
+metric. Generated exclusions are counted separately from unavailable input.
+Repeated options, conflicting modes, missing/flag-like values, and nonfinite
+thresholds fail before scanning or metrics. Diff helpers and text conversion
+are disabled so configured executables cannot change the inspected evidence.
+
+## Output shape
+
+```text
+dup: scanned 42 files (2 skipped), 17 units; ignore-file .devrites/dup-ignore
+dup: 2 cluster(s) (1 ignored)
+cluster 1 (a1b2c3d4e5f6) score 0.93:
+  * engine/a.go:10-58
+    engine/b.go:120-168
+cluster 2 (f6e5d4c3b2a1) score 0.81:
+    pkg/x/util.py:30-70
+    pkg/y/util.py:14-54
+```
+
+`*` marks a unit that overlaps the diff's changed lines. The hex after
+`cluster N` is the cluster's stable hash.
+
+## Triage each cluster
+
+For every reported cluster a reviewer returns exactly one verdict:
+
+| Verdict | When | Action |
+|---|---|---|
+| **merge** | Same logic, same contract, no behavioral reason to differ | Finding: extract a shared helper or call the canonical implementation. Name which unit survives. |
+| **keep** | Convergent code (test scaffolding, protocol mirrors, intentional fork points) | Record the cluster hash in the ignore ledger with a one-line reason. |
+| **watch** | Similar now, likely to diverge — copied seed that is about to change | FYI finding noting the drift risk; do not ignore. |
+
+Ranking boosts distant matches across directories or far apart within one file.
+Distance is a triage hint, not proof that two contracts are interchangeable.
+Check whether fixes to one copy should also apply to the other.
+
+## Ignore ledger
+
+`.devrites/dup-ignore` (project-root default; `--ignore-file` overrides) holds
+one cluster hash per line, `#` comments allowed:
+
+```text
+a1b2c3d4e5f6  # test scaffolding mirrors on purpose — do not merge
+```
+
+The hash derives from normalized code *content*, not line numbers. It survives
+renames, comment churn, literal tweaks, and line moves, but **changes when the
+code's structure changes** — a dismissed cluster that gets edited resurfaces
+for re-triage. This is intentional: a ledger entry must never permanently
+blind the scan.
+
+Rules:
+
+- Never add a hash without reading both units — an unread dismissal is a gap.
+- Write the reason on the same line after `#`; a bare hash is an unexplained
+  dismissal and counts as a skipped check.
+- Do not commit-ignore clusters introduced by the *current* diff — a `*` unit
+  needs a verdict (merge/keep/watch), not suppression.
+
+## Reporting dup findings
+
+Dup findings use the C2 shape like any other finding, plus the cluster hash so
+the dismissal ledger can reference it:
+
+```text
+Finding: Suggestion | engine/a.go:10 | cluster a1b2c3d4e5f6 duplicates engine/b.go:120 (score 0.93) | fixes to one will drift from the other | extract shared helper `dupNormalize` into engine/internal/lib
+```
+
+A reviewer that ran `check dup` and found nothing reports it under
+`No-findings:` / `Basis:` (`dup: 0 clusters over 42 files`) — not by silence.

package/pack/generated/pi/skills/devrites-lib/reference/standards/edge-case-trace.md

@@ -1,5 +1,7 @@
 # Edge-case trace
 
+> Applies when: a boundary, branch, or failure mode changes in spec, plan, diff, or proof.
+
 Use this when requirements, plans, diffs, or proof change a boundary, branch,
 validation rule, deletion contract, retryable action, or claim that a path is safe.
 The trace finds relevant cases, records why irrelevant ones were dismissed, and prevents

package/pack/generated/pi/skills/devrites-lib/reference/standards/elicitation.md

@@ -1,5 +1,7 @@
 # Elicitation: a move-set for the thinking phases
 
+> Applies when: a thinking phase needs more than the default review shape for a section.
+
 The thinking phases (`/rite-temper` on the spec, `/rite-vet` on the plan) default to one shape each.
 A pre-mortem, a plan review. That's a floor, not a ceiling. When a section needs deeper thought,
 this is the menu you reach into: named reasoning techniques, each with the shape it produces, so
@@ -24,6 +26,7 @@ Selection is by the section's risk, not taste. Reach for the row that fits:
 | a vague or contested requirement | Steelman-then-Attack · Devil's Advocate · Five Whys |
 | an estimate, sizing, or a "how long / how risky" | Delphi · Reference-Class Forecast |
 | a design with more than one plausible shape | Tournament (A vs B) · Inversion · Analogy Mapping |
+| a plan or patch that may be solving the wrong problem | Backward Chain |
 | a spec that feels *too* big or *too* small | Scope Extremes (MVP vs Gold-plate) · YAGNI Pass |
 | a risk surface you suspect is under-explored | Chaos Scenarios · Edge-Case Hunt · Second-Order Effects |
 
@@ -52,6 +55,10 @@ Each entry is **name (when to reach for it) the shape it produces** (`→` reads
   → invert each failure into a requirement.
 - **Second-Order Effects:** a change that touches shared surface. For each first-order effect ask
   "and then what?" twice → surface the downstream consequence the diff hides.
+- **Backward Chain:** a plan or patch that may be solving the wrong problem. Write the desired end
+  state as one checkable sentence → ask "what must be true immediately before it?" → recurse to the
+  current state → any planned step that does not land on the chain is wrong-direction work; name the
+  tempting one explicitly.
 
 ### Sizing and estimating
 - **Delphi:** an estimate one person is anchoring. Gather independent estimates *without* seeing
@@ -82,4 +89,26 @@ Run the technique on the **section in front of you**, not the whole document: a
 everything is a move applied to nothing. Record what it changed in the phase artifact (a new
 requirement, a mitigation, a blocking question), not just that you ran it.
 
+## Asking mechanics
+
+- **Batch 2–4 independent questions;** ask serially when one answer determines the next
+  question or the question is an approval gate.
+- **Never ask for the discoverable** — repo, docs, prior artifacts, and conversation
+  first; a question whose answer sits in a file is a stall dressed as diligence.
+- **One decision per question** with enough context to answer without reopening files;
+  recommend a path and name its trade-off — never raw unevaluated options.
+- **At an approval gate, state the defaults you chose** so a wrong assumption gets
+  corrected before it ships.
+- **Never continue past a question by inventing the answer** — headless sessions report
+  the unresolved decision instead of assuming it.
+- **A skipped, declined, or timed-out answer is `unanswered`, not approval.** A
+  proposal, silence, or timeout never becomes a decision. Continue only work the
+  open decision cannot affect; when the unanswered question blocks scope,
+  spending, publication, or anything irreversible, stop and name the specific
+  unresolved choice — do not reissue the same question as if nonresponse were an
+  error.
+- **No question tool → numbered text fallback.** Two to four concrete options,
+  each with its trade-off, one marked as the recommendation, and a free-text
+  escape. A recommendation is labeled, never pre-selected.
+
 A project can append its own house techniques to this file: same entry shape — **name (when to reach for it)** → the shape it produces.

package/pack/generated/pi/skills/devrites-lib/reference/standards/error-handling.md

@@ -1,5 +1,7 @@
 # Error handling
 
+> Applies when: code can fail; error paths, messages, retries, partial state.
+
 Errors are part of the contract, not an afterthought. Make failure loud, local, and
 recoverable.
 

package/pack/generated/pi/skills/devrites-lib/reference/standards/gates.md

@@ -0,0 +1,117 @@
+# Gates — the machine-checked acceptance ledger
+
+> Applies when: authoring or checking the machine-verified acceptance ledger (gates.md).
+
+`gates.md` is the acceptance ledger: every required outcome becomes one
+independently checkable gate, and the engine — not reviewer prose — decides
+whether each gate ran and produced its declared signal. It is the structural
+answer to partial compliance: a feature cannot report "done" while a required
+outcome is unchecked, stale, or abandoned.
+
+Written at Vet alongside `test-plan.md`, executed at Prove, required all-met at
+Seal. Like every required artifact it is phase-bound: vet/build/converge and
+every later phase requires its presence; proof phases require every gate met.
+
+## Grammar
+
+```markdown
+- [ ] AC-001: <observable outcome>
+  CHECK: <exact command from test-plan.md Build-entry preflight>
+  EXPECT: <substring | /regex/flags>
+  CWD: <repository-relative path; omit for repo root>
+  EVIDENCE: pending
+
+- [x] AC-002: <human-judged outcome>
+  EVIDENCE: <human attestation, one line>
+
+ABANDON: AC-003 <why the outcome can never be met>
+```
+
+- One `- [ ]`/`- [x]` row per gate; `ID:` ends at the first colon, max 64 chars.
+- `CHECK` and `EXPECT` are a pair: both present (runnable gate) or both absent
+  (manual gate). A partial pair is a parse error.
+- Attributes are indented beneath their gate. Fenced code examples never parse.
+- `EXPECT` is a substring, or `/pattern/flags` with `i`, `m`, `s` flags.
+- `CWD` is repository-relative; absolute paths and `..` segments are rejected.
+- `ABANDON:` starts at column 1, names a known gate, and requires a reason.
+  An abandoned gate blocks completion and demands a handoff — it can never
+  read as a pass.
+- An empty ledger (no gates) is malformed.
+
+## Runnable gates and the approval boundary
+
+A runnable gate executes only when its exact `(CHECK, CWD)` pair matches a row
+of `test-plan.md`'s `## Build-entry preflight` table (`Command` + `Cwd`
+columns). Approval is exact-text equality after whitespace/cwd normalization —
+a differently spelled command or different directory is a different oracle and
+needs its own vetted row. This is the DevRites approval boundary: the vetted
+test plan is the sole list of commands the engine may run, so gates can never
+execute unreviewed code.
+
+Execution contract: the command runs through the platform shell in the named
+directory with a bounded timeout; pass requires exit 0 **and** output matching
+EXPECT. Output is captured but never persisted — only its digest.
+
+## Evidence binding
+
+A successful run writes `EVIDENCE: automatic-evidence=v1; def=<sha256>; …`
+where `def` binds the exact CHECK/EXPECT/CWD the run executed. Editing any of
+the three renders prior evidence `stale-unmet` — a stale pass cannot hide
+behind an edited oracle. Prose evidence on a runnable gate is also stale:
+only automatic evidence bound to the current definition counts.
+
+Manual gates are met when checked with non-empty human evidence (anything
+except `pending`); honesty of that evidence stays with the Prove/Seal
+reviewers.
+
+## Commands
+
+```text
+devrites-engine gates scaffold <slug>     create gates.md from spec.md AC ids
+devrites-engine gates status <slug>       reduce without executing; all-met/handoff/not-met/malformed
+devrites-engine gates run <slug>          execute unmet runnable gates, write bound evidence
+devrites-engine gates reverify <slug>     re-execute every runnable gate; demote stale passes
+devrites-engine gates lint <slug>         audit oracle quality without executing
+devrites-engine gates attest <slug> <id> <note>   record human evidence on a manual gate
+devrites-engine gates abandon <slug> <id> <why>   record a terminal ABANDON handoff
+```
+
+Run/reverify hold the feature lock, re-read the ledger before writeback, and
+discard a result whose gate definition moved mid-run. Reverify is the
+suspicion-killer: when any doubt exists about prior passes, rerun it rather
+than trusting recorded evidence.
+
+## Oracle quality (`gates lint`)
+
+Lint audits signs an oracle cannot fail honestly — fixed-output CHECKs
+(`echo done`), EXPECT values that also appear in failure output (`pass`,
+`ok`, `0`), path-shaped regexes, activity titles instead of outcomes
+("Improve coverage"), unmeasured numbers in manual titles, unvetted CHECKs,
+and mostly-manual ledgers. Warnings prompt sharpening; an unvetted CHECK is
+an error because the runner can never execute it.
+
+## Authoring guidance
+
+- One gate per observable outcome; gate ids should reuse canonical `AC-###`
+  ids so `check readiness` coverage and the ledger name the same set.
+- Write oracles a stranger could judge: EXPECT a line only success can print,
+  never a word failure output also contains.
+- Source `CHECK` text from the repository's own wiring:
+  `devrites-engine detect commands` resolves test/lint/vet/build commands from
+  the Makefile, `package.json` scripts, and language manifests without
+  executing them. Cite the resolved command verbatim in the preflight row;
+  an `unresolved` slot means Vet must name the concrete command, never guess.
+- Prefer runnable gates; reserve manual gates for genuinely judgment-bound
+  outcomes and make the title's claim inspectable.
+- Pick the strongest oracle the outcome admits: differential (output compared
+  against a recorded baseline or the pre-change behavior) over property
+  (an invariant the output must always satisfy) over example (one concrete
+  input/output case). An example-shaped oracle on a property-shaped outcome is
+  a weak gate — reviewers flag it even when it passes.
+- When an outcome becomes impossible, `gates abandon` it and route the
+  handoff — never delete the row to make the ledger pass.
+- The gate set is the coverage denominator: it never shrinks to reach
+  `all-met`. Two gates sharing one normalized CHECK+EXPECT+CWD are one oracle
+  counted twice — `gates lint` flags them as `duplicate-oracle`. Distinct
+  methods and denominator rules live in
+  [`verification-methods.md`](verification-methods.md).

package/pack/generated/pi/skills/devrites-lib/reference/standards/git-workflow.md

@@ -1,5 +1,7 @@
 # Git workflow
 
+> Applies when: committing, branching, writing history.
+
 History is documentation. Keep it clean, atomic, and readable.
 
 ## Conventional Commits

package/pack/generated/pi/skills/devrites-lib/reference/standards/glossary.md

@@ -0,0 +1,40 @@
+# Glossary
+
+> Applies when: any DevRites term is unclear — resolve it here once instead of
+> inferring from context. Alphabetical. The owning file holds the full contract.
+
+| Term | Meaning |
+| --- | --- |
+| AFK / HITL | Unattended vs human-in-the-loop execution modes. [`afk-hitl.md`](afk-hitl.md) owns pause/resume rules. |
+| Agent | Fresh-context `devrites-*` role spawned by the host; never the root chat. Roster: [`agents.md`](agents.md). |
+| Allowlist | The exact project-relative path set a wright may write. Checked mechanically by `devrites-engine check diff-scope`. |
+| Applicability map | `spec.md` table routing risk families (topology, data, integration, security, delivery) to their owning standard. A routed standard is mandatory, not optional. |
+| Binding | A recorded hash tying evidence or review to one exact candidate; stale binding = unproven. |
+| Bundle (context) | One deduplicated read-set file emitted by `devrites-engine context` into `ctx/`; a dispatch target reads it instead of selecting files. |
+| Candidate | The content-bound project state (digest + file set) reviews and proof run against. [`candidate-integrity.md`](../candidate-integrity.md). |
+| Consumptive action | An action whose failed attempt is not safely retryable (spends quota, mutates external state, or deletes its own failure evidence). [`one-shot-actions.md`](one-shot-actions.md). |
+| Controlling caller | The rite that invoked an earlier rite inline for repair; it keeps authority and resumes after the nested stop. |
+| Cursor | The `state.md` key/value table (phase, status, next_action, …) that is the authoritative lifecycle position. |
+| Decision coverage | Clarify's ledger that every material decision has current evidence and an owner; `CLEAR` unblocks later phases. |
+| Detected commands | `devrites-engine detect commands`: resolves the repo's own test/lint/vet/build commands (Makefile → package.json → manifests, lockfile-derived package manager) without executing them; cite resolved text verbatim, `unresolved` means name it in the plan. |
+| Diff-scope gate | `devrites-engine check diff-scope`: changed paths ⊆ allowlist, run before reviewer dispatch. |
+| Drift baseline | `readiness-inputs.json`: per-input SHA-256 snapshot recorded by `check drift --record` after Vet's binding; `check drift` attributes later input changes to the exact artifact. Advisory, never a gate. |
+| Dup ignore ledger | `.devrites/dup-ignore`: one `check dup` cluster hash per line with a `#` reason; content-derived hashes resurface on structural edits. [`duplicate-code.md`](duplicate-code.md). |
+| Evidence freshness | The rule that proof must postdate the candidate it claims to cover; [`candidate-integrity.md`](../candidate-integrity.md) § evidence validity. |
+| Finding shape (C2) | Canonical `Outcome / Finding / Basis` result rows every reviewer must return; [`agents.md`](agents.md) § Result admission. |
+| Gap | Result state naming missing/stale/unreadable input or a skipped required check; a required gap blocks, it is never `no-findings`. |
+| Gates ledger | `gates.md`: machine-checked acceptance rows (scaffold/status/run/reverify/lint/attest/abandon). [`gates.md`](gates.md). |
+| Loads manifest | The `<!-- loads: {...} -->` block in a SKILL.md declaring its exact read-set (`always`, `triggers`, `workspace`) for `devrites-engine context`. |
+| Metrics ledger | Append-only `metrics.jsonl` in a feature workspace recording dispatches, returns, bundle bytes, repair rounds. |
+| Nested phase boundary | A `STOP` inside a caller-invoked repair rite; it returns control to the caller, not the human. |
+| Read next | The per-phase bounded read order for workspace artifacts; [`workspace-artifact-schema.md`](../workspace-artifact-schema.md) § Read next by phase. |
+| Regression baseline | `regression-baseline.json`: the durable high-water mark of workspace progress facts; `check regression` compares against it, `--update` ratchets it at a checkpoint. |
+| Seal | Final GO/NO-GO decision phase; a GO never authorizes irreversible mutation by itself. |
+| Slice | One vertical, independently provable unit of the plan (`SLICE-###` in `tasks.md`). |
+| Spec Drift Guard | The only legal path to change a sealed spec/plan: batch-sweep violations, record drift, repair through the owning rite. `rite-build/reference/spec-drift-guard.md`. |
+| Standards | The rule files in this directory; `core.md` is always-on, the rest load on trigger (`README.md` table). |
+| Transfer commit | The isolated wright's local unpushed `WIP(<slug>):` transport commit; never the control-branch checkpoint. |
+| Trigger | A named conditional read-set in a `loads:` manifest (e.g. `tdd`, `applicability`, `ui`); engine fails closed on unknown names. |
+| Windows ledger | `windows.md`: one waiver row per deferral marker the change introduces; `check windows` fails on unwaived hits. [`windows.md`](windows.md). |
+| Workflow Artifact | A Vet-ready, root-authored executable file under `.devrites/work/<slug>/`; [`workflow-artifacts.md`](workflow-artifacts.md). |
+| Wright | `devrites-slice-wright`: the sole product source/test writer under a path-bounded contract. |

package/pack/generated/pi/skills/devrites-lib/reference/standards/hooks.md

@@ -1,5 +1,7 @@
 # Automation hooks
 
+> Applies when: adding or changing automation hooks.
+
 Automate easy-to-forget checks at the earliest affordable stage. Keep local hooks fast
 and scoped so developers continue to run them.
 
@@ -23,3 +25,17 @@ owns fail-closed PR-body transport.
 - Bypassing a hook (`--no-verify`) is for genuine emergencies, not routine. CI must
   re-check what a bypass skipped, so a skipped local check can't reach the trunk.
 - Hooks are checked into the repo and shared, so the whole team gets the same gates.
+
+## Context-injection hooks
+
+Hosts with prompt/tool lifecycle hooks can re-surface durable state every turn so a
+plan survives `/clear` and compaction — the file persists, the context window does not:
+
+- **Inject pointers, not bodies.** A prompt-submit hook emits a few lines — active
+  workspace, current phase, open gates, paths to read. The agent reads the files; the
+  hook never inlines them.
+- **Persist before compaction.** A pre-compact hook flushes any unpersisted checkpoint
+  to the workspace before the window is rewritten.
+- **Stay quiet and cheap.** A hook with nothing to inject prints nothing and never
+  blocks the turn; a missing script degrades silently — reported once per prompt at
+  most, on the user-visible event, never per tool call.

package/pack/generated/pi/skills/devrites-lib/reference/standards/integration-reliability.md

@@ -1,5 +1,7 @@
 # Integration reliability
 
+> Applies when: third-party APIs, webhooks, queues, caches, background jobs.
+
 Load this for third-party APIs, webhooks, queues, background jobs, caches, or
 cross-service calls. The boundary contract includes failure, timing, duplication, and
 recovery—not only the success payload.
@@ -61,6 +63,23 @@ For every call or delivery, classify the observed outcome:
   capacity/drain/recovery action; auto-scaling without downstream capacity protection
   only moves the outage.
 
+## Idempotency identity and lifetime
+
+Scope a key to the authenticated tenant/principal and operation, and bind it to
+the canonical payload identity. Same key with a different payload is a conflict,
+not a cached success. Atomically claim the key at the existing durable owner
+before the effect; a check-then-insert race is not deduplication. Couple effect
+and completion where possible, or reconcile the unknown interval.
+
+Define what an in-flight duplicate receives: bounded wait, pending/status, or
+conflict. It must not launch a second effect. Retain completion records across
+the full permitted retry, queue-redelivery and manual-replay window. After key
+expiry, reject stale replay or reconcile against authoritative effect identity
+before treating it as new work; a TTL alone does not make replay safe.
+
+Proof races two same-key deliveries, changes the payload and tenant scope,
+interrupts after the effect but before completion, and replays at/after expiry.
+
 ## Partial failure and recovery
 
 Map each multi-step effect as `not started | committed | unknown | compensating |