devrites 5.11.0 → 5.12.0

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

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

@@ -1,5 +1,7 @@
 # Host-native loop operations
 
+> Applies when: host-native loop and AFK execution semantics.
+
 DevRites owns objectives, durable state, gates, proof, budgets, and stop conditions.
 Claude or Codex owns activation, scheduling, waiting, and event delivery. Never add a
 DevRites daemon, polling broker, background receipt, or second state machine around
@@ -37,7 +39,9 @@ Every unattended loop must name:
 3. **Cycle:** one documented skill invocation; no hidden command chain.
 4. **Evaluator:** the skill's existing readiness, proof, review, or watcher verdict.
 5. **Budget:** every applicable `.devrites/AFK` resource cap.
-6. **Checkpoint:** durable workspace/evidence update before the turn ends.
+6. **Checkpoint:** durable workspace/evidence update before the turn ends; a
+   `devrites-engine check regression <slug> --update` ratchet after each durable
+   advance records the new progress floor.
 7. **Stop:** success, human/safety/access gate, budget exhaustion, unchanged
    no-progress fingerprint, host failure, or terminal external state.
 8. **Notification:** optional native-host notification after state is durable; never a
@@ -53,6 +57,23 @@ Before each wake or dispatch, re-read `.devrites/ACTIVE`, the active workspace,
 chat turn. Refuse overlapping writer cycles for the same workspace; a still-running
 native task is a gap, not a reason to start another.
 
+## Health-check cycles (watchdogs)
+
+A watchdog cycle inspects live state and acts only inside its enumerated scope:
+
+- **Enumerate, don't assume.** Build the check set from a live registry (running
+  sessions, active workspaces, open runs); an unlisted entity does not exist for the
+  cycle — never extend scope by judgment.
+- **Distinguish states before acting.** `crashed` (confirmed dead by durable state),
+  `stuck` (no progress fingerprint change over the window), and `busy`/`idle-waiting`
+  are different verdicts. Observe-only states are never restarted or killed; idle
+  waiting on a human is healthy, not stuck.
+- **Cooldown every action**; repeated firing on an unchanged fingerprint is the
+  no-progress stop, not a retry.
+- **Kill/restart needs proof of death** — durable-state evidence of a crash; silence or
+  a stale heartbeat is `gap`, not a corpse.
+- **Report the sweep** durably: enumerated set, checks, verdicts, actions, next wake.
+
 ## Safe host recipes
 
 Exact syntax varies by host; prompts keep these semantics:
@@ -78,6 +99,16 @@ armed AFK workspace whose exact scope, gates, and budgets permit it.
   causal-fingerprint recovery cap ([`afk-hitl.md`](afk-hitl.md)).
 - A cold resume continues durable slice/recovery state. Fresh
   native activation counters follow `afk-hitl.md`; no durable bound is reinitialized.
+- A cold resume or wake first runs `devrites-engine check regression <slug>`
+  when a `regression-baseline.json` exists: `BLOCKED` means the workspace lost a
+  recorded fact since the last checkpoint — restore or route the lost fact
+  through its owning phase before continuing; `unproven` means no baseline yet
+  and does not block. `--update` is a checkpoint action, never a way to silence
+  an unreconciled regression.
+- When a readiness or seal check reports a stale `Readiness inputs` binding,
+  run `devrites-engine check drift <slug>` before re-vetting: it names the
+  exact input artifact that changed (or `missing`/`added`) since the recorded
+  baseline, so the Spec Drift Guard or `/rite-vet` starts at the right file.
 - Native notifications fire only after evidence and stop state are written.
 
 Use [`afk-hitl.md`](afk-hitl.md) for unattended authority and resource budgets,

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

@@ -1,5 +1,7 @@
 # Observability
 
+> Applies when: production proof, logging, metrics, runtime evidence.
+
 Observability is proof the feature works in **production**: the evidence ladder extended
 past your machine. `/rite-prove` shows it works on localhost; observability is how you know
 it still works, and why it broke, once real traffic hits it. Un-instrumented code is a claim

package/pack/generated/claude/skills/devrites-lib/reference/standards/one-shot-actions.md

@@ -1,5 +1,7 @@
 # One-shot evidence completeness
 
+> Applies when: a failed attempt is not safely retryable (consumptive action).
+
 An action is **consumptive** when a failed attempt is not safely equivalent to a
 normal rerun. This includes commands limited to one attempt, commands whose retry
 needs fresh human authorization, actions that spend external quota or mutate

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

@@ -1,5 +1,7 @@
 # Patterns & architecture
 
+> Applies when: choosing an abstraction, pattern, or architecture shape.
+
 Use a pattern only when it makes the design easier to understand and reduces coupling.
 
 ## Principles

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

@@ -1,16 +1,23 @@
 # Performance
 
+> Applies when: optimizing, measuring, or reviewing for speed or cost.
+
 Measure first. An optimization without a measurement is a guess that adds complexity.
 
 ## Measure before you optimize
 - Establish a number: a timing, a query count, a payload/bundle size, a memory figure:
-  against a budget or a baseline.
+  against a budget or a baseline. Hold workload, dataset, cache state, and named
+  environment comparable; use repeated samples and report spread/noise rather
+  than selecting the best run.
 - No measurement → no performance claim, and usually no change. "Feels slow" is a
   hypothesis to test, not a reason to refactor.
 
 ## Optimize responsibly
 - Fix the **measured** bottleneck, then **re-measure** to prove the win (before/after).
   An optimization that doesn't move the number is just added complexity: revert it.
+  Keep compact failed and neutral experiment notes in the existing evidence:
+  hypothesis, change, comparable measurements, and keep/revert decision. Do not
+  create a separate experiment framework or ledger.
 - **Measurement not reproducible in CI** (noisy host, external dependency): label the claim
   `Lab (<named command/environment>)` — never an elapsed-time assertion in shared CI (a
   flaking wall-clock test is a flaky test, [`testing.md`](testing.md)). Budget regression:

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

@@ -1,5 +1,7 @@
 # Project principles
 
+> Applies when: .devrites/principles.md exists, or a change may violate a declared invariant.
+
 A project principle is a human-approved, falsifiable invariant that the codebase
 must not break, such as "no PII in logs" or "public v1 responses require a
 deprecation cycle before removal." It is not an observed habit or a generic craft
@@ -31,6 +33,18 @@ Each principle must state:
 
 Vague statements such as "write clean code" are not principles.
 
+## File header and governance history
+
+`principles.md` opens with a governance header so reviewers can audit staleness:
+
+```text
+Version: <semver>   Ratified: <date>   Last amended: <date>
+```
+
+Every ratification, amendment, exception grant, or retirement appends a dated
+entry to the file's governance history. A principle with no dated record is
+unaudited.
+
 ## Gate
 
 At plan, build, review, and seal, compare the proposed or actual change with each

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

@@ -1,5 +1,7 @@
 # Prose style: write like a human, not a model
 
+> Applies when: writing user-facing prose, artifacts, or replies.
+
 Every chat reply and artifact DevRites writes (`spec.md`, `plan.md`, `decisions.md`,
 `review.md`, `seal.md`, commit bodies, PR descriptions) should read like a senior engineer
 wrote it for a teammate. The default LLM voice (filler openers,
@@ -94,6 +96,7 @@ The cut-list removes tells; specificity prevents them. Fast tests before deliver
 
 - **Topic-swap test.** If swapping the subject for any other feature still reads true, it says nothing — name the specific thing.
 - **Surprise test.** One concrete unguessable detail (real number, constraint, trade-off)? Slop never surprises; add it.
+- **First-read test.** A sentence the reader must re-read to hold gets split.
 
 A paragraph you could cut 40-60% with no information lost is padding. Cut it.
 

package/pack/generated/claude/skills/devrites-lib/reference/standards/release/ship-checklist.md

@@ -1,8 +1,12 @@
 # Ship checklist
 
+> Applies when: the final pass/fail sweep at ship.
+
 - Current `seal.md` GO; literal GO approved this attempt.
 - Collapse/Git follow project convention.
 - All strategy/decisions/review/seal residuals: one `ship.md` tracked path/ID or prior/explicit human-approved no-action; gaps block archive.
+- Affected-surface matrix recorded: every dimension the change could touch (surface, OS, environment, data state) is marked `verified | fixture-covered | not-run:<reason> | n/a` — an unlisted dimension is an unexamined one.
+- Attached or committed artifacts are sanitized: no secrets, personal paths, or machine-local identifiers in logs, captures, or fixtures.
 - Success: archive; clear `ACTIVE`.
 
 [`git-workflow.md`](../git-workflow.md), [`ci-cd.md`](../ci-cd.md), [`git-ship.md`](../../../../rite-ship/reference/git-ship.md).

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

@@ -1,5 +1,7 @@
 # Repository topology
 
+> Applies when: work spans monorepo members, nested projects, languages, or roots.
+
 Load this when work spans a monorepo member, nested project, multiple languages,
 multiple services, or more than one repository. The purpose is to select the real
 owners and roots before planning paths or commands.

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

@@ -0,0 +1,23 @@
+# Per-language review checklists
+
+> Applies when: reviewing a diff that touches source files. Companion to
+> [`code-review.md`](../code-review.md) — these are file-level probes, not a
+> second severity scale.
+
+Load `default.md` for every reviewed file, plus the file matching the file's
+language. A file with no listed language gets `default.md` only.
+
+| File pattern | Checklist |
+|---|---|
+| every source file | [`default.md`](default.md) |
+| `*.go` | [`go.md`](go.md) |
+| `*.py` | [`python.md`](python.md) |
+| `*.ts`, `*.tsx`, `*.js`, `*.jsx`, `*.mjs`, `*.cjs` | [`ts-js.md`](ts-js.md) |
+| `*.sh`, `*.bash`, `*.zsh`, PKGBUILD, Dockerfile RUN blocks | [`shell.md`](shell.md) |
+| `.github/workflows/*.yml`, `.github/workflows/*.yaml`, `*.gitlab-ci.yml` | [`ci-workflows.md`](ci-workflows.md) |
+
+Each checklist lists investigation probes, not automatic findings. Establish the
+applicable contract, reachable path, and concrete effect before reporting a defect.
+The "do not flag" sections prevent unsupported style or idiom complaints; they do
+not excuse a demonstrated correctness or security failure. Assign severity under
+the canonical review and security standards, never from a pattern match alone.

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

@@ -0,0 +1,50 @@
+# Review: CI workflows
+
+> Applies when: reviewing `.github/workflows/*.yml`, `*.gitlab-ci.yml`, and
+> equivalent pipeline definitions. Load with [`default.md`](default.md).
+
+## Defect probes
+
+- **Unpinned actions/images.** `uses: org/action@main`/`@master` or a mutable
+  tag for third-party actions — supply-chain risk. Pin to a SHA or a semver
+  tag per project policy; flag mutable refs on *untrusted* publishers.
+- **`pull_request_target` / `issue_comment` triggers running untrusted code.**
+  Checking out PR head code or evaluating `${{ github.event.* }}` fields in a
+  privileged context (write token, secrets): trace execution, available authority,
+  and reachable effect; assign severity under [`security.md`](../security.md).
+- **Expression injection.** `${{ github.event.issue.title }}`,
+  `github.head_ref`, PR body, or any attacker-controlled field interpolated
+  into `run:` can turn data into executable syntax. Establish attacker control
+  and impact before assigning severity; pass data through env vars and quote its
+  use instead of interpolating it as script source.
+- **Permissions.** Missing `permissions:` block (defaults to broad write on
+  some configurations); `contents: write` or `packages: write` wider than the
+  job needs; `id-token: write` without an OIDC consumer.
+- **Secret exposure.** `secrets.X` in `run:` output or a step that echoes
+  env/vars; secrets passed to `pull_request_target` or fork-triggered jobs;
+  a secret in a URL or file that gets uploaded as an artifact.
+- **Artifact poisoning.** `actions/upload-artifact` of a path that includes
+  attacker-controlled files later consumed by a privileged job; cross-workflow
+  `actions/download-artifact` without integrity or source checks.
+- **Concurrency gaps.** Missing `concurrency:` on deploy/release jobs —
+  overlapping runs corrupt state; `cancel-in-progress: true` on a deploy that
+  must finish.
+- **`if:` conditions on the wrong level.** A job-level `if` intended per-step;
+  `always()` masking a needed `success()`/`failure()` gate.
+- **Environment/approval bypass.** Deploy steps without `environment:` where
+  the project requires protection rules; self-hosted runner labels on
+  untrusted-triggered jobs.
+- **Cache poisoning.** Cache keys that include attacker-controlled refs;
+  restoring a cache built from PR code into a release/signing job.
+
+## Do not flag
+
+- `uses: actions/*@vN` semver tags on first-party/trusted publishers per
+  project policy — mutable SHA-pinning is a hardening Suggestion, not Critical,
+  unless the policy requires pinning.
+- Missing `permissions:` when `GITHUB_TOKEN` default is read-only in the repo
+  settings — verify the repo setting before flagging.
+- `${{ secrets.X }}` as a step `env:` value consumed by a trusted action —
+  flag only paths to attacker-visible output.
+- Long `run:` blocks that a lint step (`actionlint`, `yamllint`) already
+  covers — do not duplicate lint findings.

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

@@ -0,0 +1,42 @@
+# Review: language-agnostic
+
+> Applies when: reviewing any source file. Load alongside the file's
+> language checklist.
+
+## Defect probes
+
+- **Dropped result.** A fallible call whose error/result value is discarded,
+  swallowed by a catch-all, or logged-and-continued without a stated reason.
+  Trace the failure path to its user-visible consequence before assigning
+  severity.
+- **Boundary values.** Off-by-one on ranges, empty collection, single element,
+  max/min, zero, negative where only positive is expected, `nil`/`null`/`None`
+  reaching a dereference or call.
+- **Resource lifecycle.** Acquired resource (file, connection, lock, timer,
+  subscription, temp dir) without a matching release on every exit path —
+  especially early returns and error branches.
+- **Concurrency.** Shared mutable state read/written without synchronization;
+  a lock held across a blocking or fallible call; a goroutine/thread/task whose
+  failure is unobserved; time-of-check/time-of-use gaps.
+- **Copy-then-drift.** A new block that mirrors an existing one with only names
+  changed — check whether the original receives fixes the copy will miss.
+  Cross-check with `devrites-engine check dup` output when available.
+- **Assertion-free test.** A test that exercises code without discriminating the
+  promised behavior. A no-throw assertion is valid when non-throwing behavior is
+  the actual contract and the targeted regression would make it fail; it cannot
+  prove a returned value or side effect. Cite the missing proof at `file:line`.
+- **Config/code mismatch.** A default, limit, path, or name in config that
+  disagrees with the code that consumes it.
+- **Unreachable branch.** A condition that can never hold given the types or
+  the guarding checks above it.
+
+## Do not flag
+
+- Style choices a formatter or linter already enforces.
+- "Could be more readable" without a concrete confusion a reader would hit.
+- Hypothetical inputs the caller contract already excludes — verify the
+  contract at call sites before claiming a missing guard.
+- Performance concerns without a hot-path or data-size basis; cite the basis
+  or mark it a question.
+- Absence of a feature nobody asked for; scope expansion is a follow-up, not a
+  finding.

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

@@ -0,0 +1,47 @@
+# Review: Go
+
+> Applies when: reviewing `*.go` files. Load with [`default.md`](default.md).
+
+## Defect probes
+
+- **`err` dropped or shadowed.** `x, _ := f()` on a fallible call without a
+  recorded reason; `err` reassigned inside a block so the outer check sees nil;
+  `defer f()` discarding an error that matters (e.g. `Close` on a writable
+  file, `Rollback` result).
+- **Nil-map write.** Assignment into a map declared but never initialized
+  (`var m map[K]V; m[k] = v` panics). Reads are safe; writes are not.
+- **Goroutine leaks.** A goroutine blocked on a channel send/receive that no
+  peer will satisfy after an early return or cancellation; `context.Context`
+  created but never passed or cancelled.
+- **Timers in loops.** Check effective toolchain, module version, and `GODEBUG`
+  settings: under Go 1.23 timer semantics, unreferenced timers are collectible,
+  so `time.After` alone does not prove a leak. Older semantics and retained
+  references need separate analysis; repeated allocation is a measured cost,
+  not automatically a leak. See [timer semantics](https://go.dev/wiki/Go123Timer).
+- **`defer` in a loop.** Deferred `Close`/`Unlock` inside a loop accumulates
+  until function return — in long-running loops this exhausts handles or holds
+  locks far too long.
+- **Loop variable capture.** Goroutine or closure capturing the range variable
+  (pre-Go-1.22 semantics) — check the module's Go version before flagging.
+- **Slice aliasing.** Appending to or mutating a slice derived from a shared
+  backing array; `copy` where aliasing was intended or vice versa.
+- **`mutex` copy.** Passing a struct containing a `sync.Mutex`/`WaitGroup` by
+  value; `go vet` catches some cases — flag the ones it can't (interface
+  boxing, slices of lock-bearing structs).
+- **Error wrapping broken.** `fmt.Errorf` without `%w` where callers use
+  `errors.Is/As`; comparing errors with `==` against a wrapped error.
+- **`interface{}` escape.** A concrete invariant (single expected type) hidden
+  behind `any` plus a cast that can panic on misuse.
+- **HTTP/IO leaks.** `resp.Body` never closed; `io.Reader` partially consumed
+  then reused; `json.Decoder` on an untrusted stream without size bound.
+
+## Do not flag
+
+- `if err != nil { return err }` repetition — it is idiomatic, not a defect.
+- Missing `context.Context` on a purely synchronous internal helper.
+- `//nolint` or `//nosec` that names the suppressed check and gives a reason —
+  judge the reason, not the annotation.
+- Returning a concrete type instead of an interface — Go convention is
+  "accept interfaces, return structs."
+- Unexported struct fields in a CLI/internal package — encapsulation pressure
+  differs from library code.