devrites 5.11.0 → 5.12.0

package/pack/generated/claude/skills/devrites-lib/reference/standards/code-navigation.md

@@ -1,5 +1,7 @@
 # Code navigation
 
+> Applies when: choosing structural search tools (code index vs grep) before exploring.
+
 Decision tree for structural questions. Load with [`tooling.md`](tooling.md);
 this file is the pack-canonical routing table agents cite in Build, Vet, and
 Review.
@@ -15,16 +17,61 @@ Review.
 | Rename, references, diagnostics | LSP (`lsp` rename/references) when available | graph trace + grep |
 | Known file, one-line fix | `Read` at offset/limit | — |
 | Literal string / config value | `Grep` | — |
+| Does a similar implementation already exist? | embedding/similarity tool when present | `search_graph` on purpose-words and name variants, then targeted `Read` |
 
 ## Before cross-file edits
 
 1. Run **one** primary route from the table (record tool + query in the artifact).
-2. Read symbol bodies you will change (`read_symbol` counts as read).
-3. After edits: LSP diagnostics + project tests.
+   **Compute the affected set before writing code, not after** — the blast-radius
+   list is the edit plan: every file on it is a touch or a conscious skip.
+2. Read symbol bodies you will change (`read_symbol` counts as read), comments
+   included — a why-comment is often the only record of a decision.
+3. After edits: LSP diagnostics + project tests. Compiler errors are the oracle
+   for callers the graph listed — fix them in dependency order, direct
+   dependents first. Errors absent from the list mean the list was incomplete
+   (see blind spots below); record the gap.
 
 Skipping step 1 on a multi-file slice is a Build orient gap unless recorded
 `cannot_verify`.
 
+## Query budget
+
+Spend the minimum that settles the question:
+
+- Minimal output first — pass the smallest detail/scope option a tool offers;
+  escalate to a fuller answer only when the minimal one cannot decide.
+- One structural question ≈ five index calls. The sixth means the question needs
+  re-scoping or a file read, not another query.
+- Stop at sufficiency: an index answer that names the symbols and their source
+  ends the search; re-verifying it with grep is waste, not diligence.
+
+## What the static graph cannot see
+
+Import/call edges are only the statically visible share of the dependency
+surface. A blast-radius answer that ignores the rest is a false negative
+factory:
+
+- **Cross-language edges:** HTTP/RPC call sites (`fetch("/api/…")` → the route
+  handler file), subprocess/CLI invocations, and queue topic names couple files
+  no import statement links. Grep the literal route/command/topic when a
+  producer or consumer file changes.
+- **Dynamic binding:** `import()`/dynamic `require`, reflection, string-keyed
+  DI/registries, plugin/extension loading, ORM model registration,
+  `require.context`-style glob imports. A symbol with zero static dependents
+  may be load-bearing at runtime.
+- **Co-change coupling:** files that change together in `git log` but share no
+  import edge are coupled by convention (paired configs, parallel
+  implementations, duplicated schemas). Before a structural edit, run
+  `git log --name-only` on the target file's recent history and treat repeat
+  companions as soft dependents.
+- **Type-only edges** (`import type`, generics-only references) inform impact
+  and dead-code reads but do not execute — do not count them as runtime
+  coupling (see [`architecture-health.md`](architecture-health.md)).
+
+The compiler and the test suite are the oracle for everything in this list:
+zero static dependents + zero compiler errors + green tests is evidence;
+zero static dependents alone is a hypothesis.
+
 ## Index freshness
 
 | Index path | Provider |
@@ -32,8 +79,28 @@ Skipping step 1 on a multi-file slice is a Build orient gap unless recorded
 | `.codegraph/` | CodeGraph |
 | `.code-review-graph/` | code-review-graph MCP |
 | `.codebase-memory/` | codebase-memory MCP |
-Run `devrites-engine check indexes` for a quick presence check. Stale or missing index:
-build/refresh per provider docs, or fall back to LSP + grep and note the gap.
+| `graph.json` | Graphify (`graphify query` / `graphify path A B`) |
+Run `devrites-engine check indexes` for a quick presence check. It detects
+**in-repo artifacts only** — codebase-memory may be indexed in the server's
+central store with no `.codebase-memory/` dir; when the MCP server answers
+(`list_projects`/`index_status`), trust it over the file probe. Stale or missing
+index: build/refresh per provider docs, or fall back to LSP + grep and note the gap.
+
+## Tool availability
+
+- On Claude hosts, provider tools arrive as `mcp__<server>__<tool>` — e.g.
+  `mcp__codegraph__codegraph_explore`, `mcp__code-review-graph__query_graph_tool`,
+  `mcp__codebase-memory-mcp__search_graph`. DevRites agent profiles and
+  `.claude/settings.json` already allowlist these servers; a server that is not
+  installed simply offers no tools — fall back per the table, no error path needed.
+- Server names are install-configured (`codebase-memory-mcp` and `codebase-memory`
+  are both allowlisted). If your server uses another name, add it to
+  `settings.json` allow and the agent `tools:` lines.
+- CodeGraph and Graphify also run as CLIs (`codegraph explore`,
+  `graphify query` / `graphify path A B`) — allowlisted via `Bash(...)` rules.
+- On non-Claude hosts the `mcp__*` entries are ignored by generation; use each
+  host's own nav extensions or the CLI forms. All listed tools are read-only
+  navigation — do not call index rebuild, refactor-apply, or mutation tools.
 
 ## Anti-patterns
 

package/pack/generated/claude/skills/devrites-lib/reference/standards/code-review.md

@@ -1,5 +1,7 @@
 # Code review
 
+> Applies when: reviewing any diff for design clarity, logic, tests, risk.
+
 Ask whether the change improves or preserves design clarity, logic, tests, and risk.
 If it does not, do not merge it.
 
@@ -18,18 +20,47 @@ If it does not, do not merge it.
 ## What to check (tests first)
 1. **Tests:** do they exist and prove the behavior + failure modes (empty, error,
    boundary, concurrency)? Would they fail if the code were wrong? A `skip`/`only`/
-   `TODO` placeholder or assertion-free test is a finding, not coverage.
-2. **Correctness:** logic, edge cases, error paths, race conditions, wrong assumptions. For branching or boundary changes, run the [`edge-case trace`](edge-case-trace.md): relevant probe classes, fixed-set siblings, real wiring, negative intent, and deletion contracts with an evidence disposition.
-3. **Readability:** names, function size, control flow, intent obvious without the author.
-4. **Architecture:** right seam, coupling/cohesion, fits existing patterns, no premature
+   `TODO` placeholder or assertion-free test is a finding, not coverage. Account
+   for coverage per changed function, not per file: name the test that drives each
+   changed function, or list the function under `Missing tests:` — a file-level
+   "tests exist" over a diff whose riskiest function is unexercised is a gap.
+2. **Bar integrity:** sweep the diff for a lowered bar masquerading as a change:
+   new suppression comments (`@ts-ignore`, `eslint-disable`, `noqa`, `nolint`),
+   loosened thresholds (coverage floors, budgets, lint levels, timeout bumps with
+   no justification), stripped assertions, deleted or skipped tests, and new
+   unimplemented stubs or `throw`-only placeholders. Each names what it lowers and
+   needs a recorded reason in the diff or `decisions.md`; unexplained is a finding.
+3. **Correctness:** logic, edge cases, error paths, race conditions, wrong assumptions. For branching or boundary changes, run the [`edge-case trace`](edge-case-trace.md): relevant probe classes, fixed-set siblings, real wiring, negative intent, and deletion contracts with an evidence disposition.
+4. **Readability:** names, function size, control flow, intent obvious without the author.
+5. **Architecture:** right seam, coupling/cohesion, fits existing patterns, no premature
    abstraction. Check how it fits the larger system as well as its local behavior.
-5. **Security:** trust boundaries, input validation, authz, secrets.
-6. **Risk:** migrations, destructive changes, rollback.
-7. **Read depth matches risk:** the review's `Basis` names **full reads of the largest
+   Search for a **reimplemented-elsewhere** twin: a new function/module that
+   semantically duplicates an existing one (renamed, reshaped, or vendored) is an
+   architecture finding; reuse the canonical implementation or justify the fork.
+   Run `devrites-engine check dup` in the mode matching the diff (`--base <ref>`
+   for committed work, `--staged`/`--worktree` for uncommitted) for leads and
+   triage each cluster per [`duplicate-code.md`](duplicate-code.md).
+6. **Security:** trust boundaries, input validation, authz, secrets.
+7. **Risk:** migrations, destructive changes, rollback.
+8. **Read depth matches risk:** the review's `Basis` names **full reads of the largest
    diff files** (top three by changed lines), and any config/dependency/SQL/auth/migration
    file is read in full — never skimmed. A review that cannot name what it fully read is
    unproven. **Failing case:** a 600-line diff gets hunk-by-hunk commentary on the first
    screen and silence on the migration file at the bottom.
+9. **Every file in the review set gets its own pass.** Reviewing an implementation
+   file does not cover its header, interface, test, or config counterpart — being the
+   smaller member of a group is no reason to skip it. Findings attach to files inside
+   the review set, never outside it. Report the accounting: a `Coverage:` line names
+   the files reviewed in full, reviewed at hunk level, and explicitly skipped with
+   reason (generated, vendored, lockfile). Files named nowhere count as not reviewed.
+10. **Per-language probes.** For each file, apply [`review/README.md`](review/README.md):
+    `review/default.md` always, plus the checklist for the file's language. These are
+    defect probes with explicit do-not-flag lists — a do-not-flag item raised as
+    Critical/Important is a review defect, not a finding.
+11. **Large diffs get a risk pass.** When the diff exceeds the soft ceiling (~400
+    lines) or touches a migration, auth, dependency, or config file, run a second
+    focused pass over just those surfaces after the general pass — first-pass
+    attention decays with diff size and the risk-bearing file is usually last.
 
 ## Give actionable feedback
 - Read surrounding source before severity: call sites, existing guards, and the nearest consumer decide impact; a diff hunk alone is not enough.
@@ -54,6 +85,15 @@ If it does not, do not merge it.
   was inspected; the consolidated account names what was not covered or marks `gap`.
   **Failing case:** a findings list silent on, say, migration safety is not a clean
   migration review — name the inspection or the gap.
+- **Separate the verdict from its context.** A verdict flips only on evidence
+  scoped to the change under review — its diffs, its acceptance criteria, its
+  blast radius. Whole-repo signals gathered along the way (a global health
+  score, an unrelated security note, a pre-existing smell) are recorded under
+  an informational/deferred heading with that label, never folded silently into
+  the verdict — and never used to soften or harden it either direction.
+  **Failing case:** a clean change is failed because a repo-wide scan surfaced
+  a decade-old finding the diff did not introduce — or a broken change is
+  approved because "overall health" still looked fine.
 - Let automation (linters, formatters, CI) catch the trivial stuff so review focuses on
   design and correctness.
 
@@ -73,6 +113,26 @@ An author who is factually right wins over a reviewer's taste.
 
 Root re-verifies each claimed consequence at the cited site, keeps the surviving evidence, sets final severity itself (reviewer severity advisory), records what decided ([agents.md § Independence](agents.md#independence)); unresolved conflicts stay open blockers.
 
+Adjudication is asymmetric: dropping a true finding destroys it silently, while
+keeping a false one costs only a re-check. A finding is removed only on two
+grounds, each citing evidence:
+
+1. **Refuted at the site** — the quoted code or a direct read shows the claim is
+   factually wrong (the guard exists, the value cannot be nil, the test asserts
+   it). "Looks unlikely" is not refutation.
+2. **Out of scope** — the file is not in the review set or the finding describes
+   pre-existing code the diff did not touch. Route it as a follow-up, never
+   delete the record.
+
+"Cannot verify", "suspicious", "would not have raised it", and "inconvenient to
+fix now" are not grounds for removal — the finding stays open.
+
+**Protected subjects** veto dismissal regardless of convenience: a claim of a
+correctness bug, a security exposure, a data-loss/migration risk, a silently
+dropped error, or a violated project principle survives unless ground 1 produces
+a direct counter-read at the cited site. Never drop a protected-subject finding
+because the fix is large or the release is close — escalate the decision instead.
+
 ## Heuristic checks: FLAG vs NOTE
 
 A heuristic check that gates emits **FLAG** only when it can state the observed

package/pack/generated/claude/skills/devrites-lib/reference/standards/coding-style.md

@@ -1,5 +1,7 @@
 # Coding style
 
+> Applies when: writing or editing code; naming, reuse, guard clauses, readability.
+
 Write code the next engineer can read without you in the room. Match the project's
 existing idiom first; these rules fill the gaps.
 
@@ -30,10 +32,13 @@ Handle unwanted cases first and return early; keep the success path flat.
 
 ## Reuse before you write
 Before adding a new util, helper, hook, type, component, or formatter, **search** for an
-existing one. **Reuse → extend → build new**, in that order. Don't re-implement what the
-project (or stdlib) already provides. If forcing reuse would distort the existing thing's
-shape, build a sibling and consolidate later: duplication is cheaper than the wrong
-abstraction (AHA).
+existing one. Search by *problem shape*, not just name — the same problem solved under
+different names is still an existing implementation, and the hardest duplicates to spot
+are the renamed and reshaped ones. **Reuse → extend → build new**, in that order. Don't
+re-implement what the project (or stdlib) already provides. If forcing reuse would
+distort the existing thing's shape, build a sibling and consolidate later: duplication
+is cheaper than the wrong abstraction (AHA). When a plan or slice adds a new
+implementation, name the nearest existing analog it considered — or record `none found`.
 
 ## Edit reliably, change only what's asked
 - **No elision.** Never write `// ... rest unchanged` / `# ... existing code` in place of an

package/pack/generated/claude/skills/devrites-lib/reference/standards/context-hygiene.md

@@ -1,5 +1,7 @@
 # Context hygiene
 
+> Applies when: persisting phase results, resuming after compaction, before /clear.
+
 Persist phase results before starting fresh. The feature workspace, not chat memory,
 stores continuity.
 
@@ -44,9 +46,16 @@ changed contracts, implementation, proof, or dependencies, not every prior gener
 Required review rosters and final proof remain. Preserve protected history unchanged;
 a compact current view references originals without omitting active requirements.
 
-**Compaction fallback:** when hooks do not restore context, read `.devrites/ACTIVE`,
-then the `state.md` cursor, open `questions.md` gates, `decisions.md`, and
-`test-plan.md`/`evidence.md` proof pointers.
+**Compaction fallback:** after compaction, reload `.devrites/ACTIVE`, `state.md`,
+`questions.md`, `decisions.md`, `test-plan.md`, and `evidence.md`. When hooks do
+not restore context, run
+`devrites-engine handoff [slug]` first — one deterministic resume record reduced
+from durable artifacts (cursor, `awaiting_human`, open `questions.md` gates,
+the `gates.md` reduction with unmet/stale ids, `decisions.md` dead ends, and the
+canonical read-next order). Open the artifacts `read_next` names; resume from
+the record, not from transcript memory. Then `devrites-engine check
+regression <slug>`: `BLOCKED` names a durable fact lost since the last
+checkpoint; `unproven` does not block.
 
 ## Authority and trust
 
@@ -107,3 +116,11 @@ handoff.
 
 For a break longer than a few hours, point the footer at `/rite-handoff`: persist
 chat-only context to canonical files before clearing or closing the session.
+
+## Resume reconciliation
+
+Before trusting recorded state on resume, reconcile it against the tree:
+`git status --short` and `git diff --stat` versus the `state.md` cursor,
+`touched-files.md`, and the last recorded phase. Tree changes with no recorded
+provenance are drift — surface them (`drift.md` or a question) before doing new
+work on top, never silently absorb them into the current change.

package/pack/generated/claude/skills/devrites-lib/reference/standards/core.md

@@ -1,7 +1,13 @@
 # DevRites core rules
 
+> Applies when: always; every workspace rite reads it first.
+
 Each workspace rite reads core first; load phase files from `README.md` on demand.
 
+Rules are cited as `core.md #N` (CORE-N). Numbering is stable: text may be
+reworded, an ID never changes meaning. Other files name the ID instead of
+repeating the rule.
+
 Repository conventions follow [Precedence](#precedence).
 
 ## Operating rules (every phase)
@@ -25,7 +31,10 @@ Repository conventions follow [Precedence](#precedence).
    stop. HITL never auto-continues; AFK runs to its slice budget
    ([`afk-hitl.md`](afk-hitl.md)).
 6. **Evidence over confidence:** tests, builds, runtime, screenshots beat
-   assertions; record commands and output.
+   assertions; record commands and output. Tag how each claim was known:
+   `observed` (you ran or read the evidence), `inferred` (deduced — name the
+   step), `asserted` (unverified). An `inferred`/`asserted` claim never reads
+   as `observed`.
 7. **Feature scope only:** keep review/simplify/polish/security within the active
    feature and touched files; no drive-by refactor. Route account creation,
    production provisioning/testing, and credential/secret work to the human.

package/pack/generated/claude/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/claude/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/claude/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/claude/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/claude/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/claude/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/claude/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/claude/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/claude/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