devrites 1.19.0

package/pack/.claude/rules/tooling.md

@@ -0,0 +1,72 @@
+# Optional tooling — code intelligence, docs, memory
+
+Every external tool DevRites can use is **optional**. Detect what's present, use the best fit
+for the job, and **degrade gracefully to `Read` / `Grep` / `Glob`** (always available) when
+nothing is. Never assume a tool is installed, never require installing one to run a phase, and
+never block on a missing tool — the fallback path is a first-class path, not a failure.
+
+DevRites is stack-agnostic and installs into arbitrary projects; an index or MCP server that
+exists in one repo is absent in the next. Treat the tools below as accelerators you reach for
+*when available*, not dependencies.
+
+## Code intelligence — structure, placement, callers, impact, blast-radius, trace
+
+For "where is X / what calls X / what would changing X break / how does X reach Y", reach for a
+code-intelligence index when available. The three indexes below are **recommended, not
+mandatory** — follow this order and skip any that isn't installed:
+
+1. **codebase-memory-mcp — primary.** When available, answer the structural question here
+   **first**: `search_graph`, `trace_path`, `detect_changes` (git-diff → affected symbols +
+   blast radius), `get_architecture`, `get_code_snippet`, `query_graph`.
+2. **Cross-verify with codegraph *and* graphify (both, when present).** Re-ask the same
+   structural question of `codegraph` (`.codegraph/`, `codegraph_*`) **and** `graphify`
+   (`graphify-out/`), and confirm they agree with the codebase-memory-mcp answer — especially
+   for load-bearing claims (blast radius, every caller of a thing you're about to change,
+   "nothing else uses this"). A disagreement between indexes is a signal, not noise: trust a
+   fresh read of the **live code** over any index, and investigate the gap before relying on it.
+3. **Standard methods — the always-available fallback.** When none of the three indexes is
+   present — or to pin an exact reference an index is unsure of — use **LSP** (Claude Code Code
+   Intelligence: go-to-definition, find-references, hover / signature, diagnostics, document &
+   workspace symbols) plus **`Read` / `Grep` / `Glob`**, reading comprehensively rather than
+   stopping at the first match (see `core.md` rule 1).
+
+Use whatever subset is installed: codebase-memory-mcp alone is fine; codebase-memory-mcp plus
+one of the others still cross-verifies; none present → standard methods. The fallback path is a
+first-class path — never block a phase on a missing index.
+
+### Keeping the indexes fresh
+
+An index only helps if it matches the live code; after edits, a stale graph manufactures the
+very index-disagreement step 2 treats as a signal. DevRites keeps the three mechanical indexes
+current automatically — the [`devrites-refresh-indexes`](../skills/devrites-refresh-indexes/SKILL.md)
+Stop hook incrementally reindexes whichever of codebase-memory-mcp, codegraph, and graphify
+track the repo, at end of turn, in a detached process. It self-guards on changes, no-ops when no
+index is present, and is disabled by `DEVRITES_REFRESH_INDEXES=off`. Force a synchronous refresh
+— or re-run graphify's semantic pass after **doc** changes (`/graphify --update`) — via that
+skill. Still trust a fresh read of the live code over any index when they disagree.
+
+## Up-to-date library / framework docs — context7
+
+When implementing against, choosing, or verifying an **external** library/framework whose
+current API or version behaviour matters, use **context7 if available**: `resolve-library-id`
+(library name + your question) → `query-docs` (the resolved id + the question).
+
+context7 pairs with [`devrites-source-driven`](../skills/devrites-source-driven/SKILL.md), it
+doesn't replace it: the project's **installed / pinned source still wins** for the version the
+project actually runs. Reach for context7 when the local source/docs are missing, or when you
+need the *current upstream* behaviour the installed copy may predate. Record the fact + its
+source in `decisions.md` / `evidence.md` the same way — a context7 lookup is a cited source,
+not a memory.
+
+## Architecture & decision memory — codebase-memory-mcp
+
+Where a fast codebase map or a durable decision record helps, and codebase-memory-mcp is
+available: `get_architecture` for an overview (languages, packages, routes, hotspots, clusters)
+during `/rite-spec`, `/rite-define`, or `/rite-zoom-out`; `manage_adr` for an ADR-style record
+at `/rite-define` / `/rite-seal`. This complements the workspace `decisions.md`; it never
+replaces it — the workspace files remain the canonical source of truth.
+
+## Output hygiene
+
+Per [`prose-style.md`](prose-style.md): don't name these tools to the user. Say what you
+learned ("the change touches three call sites"), not which tool found it.

package/pack/.claude/settings.json

@@ -0,0 +1,53 @@
+{
+  "$comment": "DevRites hooks — auto-approve the read-only orientation/gate scripts (no more per-run permission prompts), inject the active feature's orientation at session start + a live cursor each turn, arm the A1 pre-block guard on Edit/Write, drop a fail-on-red sentinel on test/build Bash output (devrites-redwatch.sh), and refuse to end a turn while the workspace is provably inconsistent (devrites-stop-gate.sh, Stop). All new gates are OBSERVE-only by default (they log but never block); enable enforcement per gate: DEVRITES_A1_HOOK=enforce (or a .a1-enforce file), DEVRITES_STOP_GATE=enforce — each only after its log confirms no false positives. The wright-scope and reviewer-readonly guards are wired from subagent frontmatter, not here. The bash installer SEEDS this file only when .claude/settings.json is absent; it is never overwritten on update, so your own settings are safe to add here. Plugin installs get the same hooks via pack/.claude/hooks/hooks.json instead.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/devrites-allow.sh\"" }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/devrites-a1-guard.sh\"" }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/devrites-redwatch.sh\"" }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/devrites-stop-gate.sh\"" }
+        ]
+      },
+      {
+        "hooks": [
+          { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/devrites-refresh-indexes.sh\"" }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/devrites-cursor.sh\"" }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/devrites-orient.sh\"" }
+        ]
+      }
+    ]
+  }
+}

package/pack/.claude/skills/devrites-api-interface/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: devrites-api-interface
+description: Design stable APIs and interface contracts before implementation — REST/GraphQL endpoints, module boundaries, type contracts, FE/BE splits. Use when the user says "design the API", "contract this out", "split frontend and backend", or a slice crosses a boundary. Not for internal helpers or post-ship interfaces (use `/rite-review`).
+user-invocable: false
+---
+
+# devrites-api-interface — contract before implementation
+
+When a slice crosses a boundary (FE/BE, service/service, module/module) or exposes a
+public interface, define the contract first so both sides can proceed and the interface
+stays stable.
+
+## Define the contract first
+- **Shape** — request/response or function signature; field names, types, optionality,
+  units. Follow the project's existing naming and conventions.
+- **Status & errors** — success codes, error codes, error body shape, validation
+  messages. Errors are part of the contract, not an afterthought.
+- **Semantics** — idempotency, pagination, ordering, nullability, side effects.
+- **Versioning/compat** — is this new or a change to an existing contract? A breaking
+  change to an existing consumer is a user decision (and a drift event if unplanned).
+
+## Stability principles
+- Design for the caller. The interface should make the common case easy and the wrong
+  call hard.
+- Be conservative in what you expose; you can add later, but removing/changing breaks
+  consumers.
+- Match existing endpoints/modules in style — don't introduce a competing convention.
+- Validate at the boundary (untrusted → trusted); don't trust caller-supplied trust
+  signals (IDs, roles). (See `rite-review/reference/security-review.md` three-tier.)
+
+## Enables the split
+A clear contract lets `/rite-plan split` proceed: the backend slice can land against the
+contract with a stub consumer; the frontend slice can build against a mock or the real
+contract. Neither side blocks on the other.
+
+## Doubt the contract
+Before standing the interface, run `devrites-doubt` — boundary decisions are exactly the
+non-trivial kind worth an adversarial check. Record the contract + rationale in
+`decisions.md`.
+
+## Gotchas
+- Be conservative — you can add to a contract later, but removing or changing a field breaks every consumer.
+- Validate at the boundary; never trust caller-supplied IDs, roles, or prices.
+- A breaking change to an existing consumer is a user decision (and a `drift.md` event if unplanned), not a silent edit.
+- Match the project's existing endpoint/module conventions; a competing convention is a tax, not a design.

package/pack/.claude/skills/devrites-audit/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: devrites-audit
+description: Read-only audit dispatch for the active feature on the requested axis — security (OWASP, trust boundary, secrets), perf (measure-first, N+1, CWV), or simplify (Chesterton's Fence, deletion test). Use when the user says "security review", "is this safe", "is this fast enough", "perf check", "N+1", "simplify this", "Chesterton's Fence". Not for write actions or whole-project audits.
+argument-hint: "<security | perf | simplify>"
+user-invocable: false
+---
+
+# devrites-audit — read-only audit dispatch
+
+Dispatch one read-only review subagent against the active feature's workspace + diff. The subagent runs in **fresh context** (no author anchoring) and returns labeled findings. The caller (`/rite-polish` Phase 1, `/rite-review`, or the user) acts on them — this skill returns the subagent's report verbatim.
+
+This is the **inline single-axis pass** used during build / polish — one axis at a time, on demand, where a quick read keeps a slice honest. It is intentionally distinct from the seal/review **gate**, where the reviewer agents fan out in parallel across all relevant axes in their own fresh contexts (see `/rite-seal`). Same agents, different role: the audit is a cheap mid-flight check; the seal fan-out is the blocking gate. Both reading the same agent disciplines is the point, not a divergence.
+
+Why a subagent rather than inline: an adversarial reviewer with no author context is more likely to find what's wrong. Anthropic bug [#49559](https://github.com/anthropics/claude-code/issues/49559) leaves `context: fork` silently inline under plugin install, so `Task` dispatch is the reliable path under both plugin and bash installs.
+
+## Axis selection
+
+`$ARGUMENTS` picks the axis. If the caller did not pass one, infer from intent and confirm with the user before dispatch.
+
+| Axis | Subagent (`.claude/agents/`) | Discipline |
+|---|---|---|
+| `security` | `devrites-security-auditor` | OWASP Top 10; three-tier trust boundary (untrusted → boundary → trusted); secrets handling; dependency risk. A real auth-bypass / data-exposure / injection is **Critical → NO-GO** at seal. |
+| `perf` | `devrites-performance-reviewer` | Measure-first: no claim without a number or a specified measurement. N+1s, hot-path work, payload/bundle size, Core Web Vitals risks. Breach of a stated `spec.md` budget is **Important/Critical**. |
+| `simplify` | `devrites-simplifier-reviewer` | Behavior-preserving simplification: guard clauses, Extract Method, simplify conditionals, the deletion-test heuristic, Chesterton's Fence; plus the AI-codegen over-engineering smells — single-use factory / needless indirection, defensive try-catch bloat + redundant logging, dependency creep where an in-repo option exists, a 100-line function where 20 would do. Findings are **Suggestion / Nit / FYI** — no behavior change. |
+
+## Gather
+
+1. Read `.devrites/ACTIVE` to resolve the active feature `<slug>`.
+2. Confirm `.devrites/work/<slug>/touched-files.md` and `spec.md` exist. If missing → **STOP** and tell the caller the feature has no recorded diff or spec yet.
+
+## Dispatch
+
+Use the `Task` tool to launch the chosen subagent with this prompt shape (axis-specific reads in `Read:`):
+
+```
+Audit the active DevRites feature on the <axis> axis.
+
+Workspace: .devrites/work/<slug>/
+Read:
+  - spec.md   (acceptance criteria; for perf: any perf budget; for security: data model + affected areas)
+  - decisions.md   (if present)
+  - evidence.md    (existing measurements, for perf)
+  - touched-files.md
+Run `git diff` and read the listed touched files. Apply your documented
+discipline and return labeled findings (Critical / Important / Suggestion /
+Nit / FYI) using your documented output format. ONE FINDING PER LINE,
+cite file:line.
+
+Feature scope only. No edits. Do not summarize or re-rank — the caller
+reconciles.
+```
+
+Rules for the dispatch:
+
+- **One subagent per call.** This skill is not a fan-out; multi-axis fan-out is `/rite-seal`'s job (see `.claude/skills/rite-seal/reference/parallel-dispatch.md`).
+- **No author context.** Do not pass the caller's analysis or framing of the change to the subagent — fresh, adversarial read is the point.
+- **No cross-pollination.** If the caller wants more than one axis, dispatch each axis in its own `Task` call in a single message so the runtime parallelizes; each subagent gets only its own brief.
+
+## Return
+
+Pass the subagent's findings report back to the caller **verbatim**. Do not re-label, re-rank, or summarize. The caller (`/rite-polish` for `simplify`, `/rite-review` for `security`/`perf`) decides what to act on within feature scope, and surfaces any **Critical** to `/rite-seal` as a NO-GO blocker.
+
+## Fallback
+
+If the `Task` tool is unavailable in the current environment, fall back to a read-only inline audit using the discipline documented in the corresponding agent file (`.claude/agents/devrites-{security-auditor,performance-reviewer,simplifier-reviewer}.md`). **Flag clearly that this was an inline fallback**, not an independent review. The seal weighs the fallback differently — see [`rite-seal/reference/risk-and-rollback.md`](../rite-seal/reference/risk-and-rollback.md).
+
+## Scope reminders
+
+- Active feature + touched files only. Out-of-scope risks become FYI follow-ups.
+- Read-only. No edits.
+- For `perf`: no number → no claim. Speculative micro-opts are Suggestion at most.
+- For `simplify`: behavior-preserving only. Anything that needs new tests is out of scope here — route to `/rite-plan reslice`.
+- Critical findings block the seal.

package/pack/.claude/skills/devrites-browser-proof/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: devrites-browser-proof
+description: Prove UI behavior via the browser-proof ladder — browser-harness → Chrome DevTools MCP → `/run`+`/verify` → project E2E → manual — recording routes, viewports, screenshots, console, network, interactions, design-reference match to `browser-evidence.md`. Use when the user says "check the UI in browser", "screenshot this", "prove it renders". Not for backend-only features.
+user-invocable: false
+---
+
+# devrites-browser-proof — runtime evidence for UI
+
+Screenshots and runtime observations beat "it should render fine." Use the highest rung
+of the ladder that's available; record which one.
+
+## Ladder (top-down)
+1. **browser-harness** — detect `command -v browser-harness`. Connects to the user's
+   Chrome over CDP. Pattern: `new_tab(url)` → `wait_for_load()` → `capture_screenshot()`
+   → read the pixel → `click_at_xy(x,y)` → re-screenshot. Coordinate clicks pass through
+   iframes/shadow/cross-origin. `print(page_info())` for liveness. Don't launch a new
+   browser; don't auto-install.
+2. **Chrome DevTools MCP** (if configured) — screenshots, DOM, console, network,
+   performance, accessibility tree.
+3. **Claude Code `/run` + `/verify`** (if available) — launch + observe the app.
+4. **Project-native E2E** (only if present) — Playwright/Cypress/Capybara/Selenium via
+   the project's existing commands. Don't add a new framework.
+5. **Manual fallback** — none available: record the limitation + exact manual steps.
+
+## Evidence schema → `browser-evidence.md`
+Tooling used · route(s) · viewports (375/768/1280) · screenshot paths **opened and
+described** · console errors/warnings · network failures · interaction path tested ·
+accessibility basics · responsive checks · **design-reference match** (if the spec saved
+references in `references/`, compare the built UI to them and note match/diffs) ·
+limitations.
+
+## Hard rules
+- A screenshot **path is not proof** — open it and describe what's visible.
+- Check ≥1 small and ≥1 large viewport for layout work.
+- **Auth wall → stop and ask the user**; never type credentials from a screenshot.
+- Confirm destructive actions before performing them to "prove" a flow.
+- Detect, don't install. Tooling setup is the user's decision.
+- No browser available → mark proof **pending (manual)** with steps; don't fake a pass.

package/pack/.claude/skills/devrites-debug-recovery/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: devrites-debug-recovery
+description: Debug systematically when tests, builds, or runtime/browser checks fail — deterministic feedback loop, reproduce, 3-5 ranked hypotheses, instrument, fix root cause, regression-test. Use when the user says "debug this", "why is it failing", "it broke", "the build is red", "the tests fail". Not for code review or flaky tests (fix the flake first).
+user-invocable: false
+---
+
+# devrites-debug-recovery — fix the root cause, not the symptom
+
+Disciplined recovery from failures. **NO shotgun edits, NO blanket retries.**
+
+## When to invoke
+
+Loaded by `/rite-prove` (and during `/rite-build`) when something fails. Use
+when tests, builds, typecheck, runtime, or browser checks are red and the next
+move is unclear.
+
+## The six-phase cycle
+
+1. **Build the feedback loop** — fast, deterministic, agent-runnable pass/fail
+   signal. **This is the skill** — be aggressive here.
+   See [build-the-loop.md](reference/build-the-loop.md).
+2. **Reproduce** — run the loop. Confirm the failure matches the user's report
+   (not a nearby failure); capture the **exact error text**; confirm
+   reproducibility (or a high enough repro rate for flaky bugs). Do not proceed
+   without reproduction.
+3. **Ranked hypotheses (3-5, falsifiable)** — generate the list before testing
+   any of them. Each must state a prediction.
+   See [hypotheses.md](reference/hypotheses.md).
+4. **Instrument** — debugger > logs > "log everything and grep". One variable
+   at a time. Tagged debug-log prefixes.
+   See [instrumentation.md](reference/instrumentation.md).
+5. **Fix + regression test** — write the regression test before the fix, but
+   only if a correct seam exists. If no correct seam: that IS the finding;
+   record it.
+   See [regression-test.md](reference/regression-test.md).
+6. **Cleanup + classify** — repro gone, debug logs gone, throwaway harnesses
+   gone, hypothesis recorded. Classify the failure.
+   See [cleanup-and-classify.md](reference/cleanup-and-classify.md).
+
+## Hard rules
+
+- **Quote real error text;** never paraphrase it away.
+- **Change one thing at a time** so you know what fixed it.
+- **Do NOT loosen / delete a failing assertion** to get green — check whether
+  it's drift first (route via `/rite-plan repair`).
+- **Do NOT hide flakiness** with sleeps / retries — characterize it.
+- **3 failed attempts on the same root cause → escalate**: record the wrong idea and *why it
+  failed* under `## Dead ends` in `decisions.md` (so a retry or the next agent doesn't repeat it),
+  then re-hypothesize from **scratch** — fresh context, carrying those dead-ends as ruled-out —
+  invoke `devrites-doubt`, or ask the user. Don't keep trying variations of a wrong idea.

package/pack/.claude/skills/devrites-debug-recovery/reference/build-the-loop.md

@@ -0,0 +1,47 @@
+# Build the feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a fast,
+deterministic, agent-runnable pass/fail signal for the failure, you will find
+the cause — bisection, hypothesis-testing, and instrumentation all just consume
+that signal. If you don't have one, no amount of staring at code will save you.
+
+**Spend disproportionate effort here. Be aggressive. Refuse to give up.**
+
+## Build the loop — try these in roughly this order
+
+1. **Failing test** at whatever seam reaches the failure (unit / integration / e2e).
+2. **Direct CLI / curl invocation** against the running dev server or process.
+3. **Replay a captured trace** — save the offending request/payload/event to disk, replay it through the code path in isolation.
+4. **Throwaway harness** — spin up a minimal subset (one service, mocked deps) that triggers the failure with a single function call.
+5. **Headless browser script** (Chrome DevTools MCP / Playwright) — drives the UI, asserts on DOM/console/network.
+6. **Bisection harness** — if the failure appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so `git bisect run` can find it.
+7. **Differential harness** — same input through old-version vs new-version (or two configs), diff outputs.
+8. **Property / fuzz loop** — if the failure is "sometimes wrong", run 1000 random inputs and look for the failure shape.
+9. **Human-in-the-loop, structured** — last resort. If a human must click, drive *them* with a checklist so the loop stays structured. Captured output feeds back.
+
+## Iterate on the loop itself
+
+The loop is a product. Once you have *a* loop, ask:
+
+- Can I make it faster? (cache setup, skip unrelated init, narrow scope.)
+- Can I make the signal sharper? (assert on the specific symptom, not "didn't crash".)
+- Can I make it more deterministic? (pin time, seed RNG, isolate filesystem, freeze network.)
+
+A 30-second flaky loop is barely better than no loop. A 2-second deterministic
+loop is a debugging superpower.
+
+## Non-deterministic failures
+
+Goal is **higher reproduction rate**, not a clean repro. Loop the trigger 100×,
+parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug
+is debuggable; 1% is not — raise the rate until it's debuggable.
+
+## When you genuinely cannot build a loop
+
+**STOP and say so explicitly.** List what you tried. Ask the user for:
+
+- access to whatever environment reproduces it,
+- a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or
+- permission to add temporary production instrumentation.
+
+**Do NOT proceed without a loop you believe in.**

package/pack/.claude/skills/devrites-debug-recovery/reference/cleanup-and-classify.md

@@ -0,0 +1,17 @@
+# Cleanup + classify
+
+## Classify the failure (for the report)
+
+- `test-right / code-wrong` (fix code)
+- `test-wrong` (possible **spec drift** → `/rite-plan repair`)
+- `environment / setup`
+- `flaky / ordering`
+- `external-dependency-down` (blocker)
+
+## Cleanup checklist — required before declaring done
+
+- [ ] Original repro no longer reproduces (re-run the Phase 1 loop).
+- [ ] Regression test passes (or absence of seam is documented).
+- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix).
+- [ ] Throwaway harnesses deleted (or moved to a clearly marked debug location).
+- [ ] The correct hypothesis is stated in `evidence.md` + the commit/PR message — next debugger learns.

package/pack/.claude/skills/devrites-debug-recovery/reference/hypotheses.md

@@ -0,0 +1,17 @@
+# Ranked hypotheses (3-5, falsifiable)
+
+Generate **3-5 ranked hypotheses** *before* testing any of them.
+Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: *"If <X> is the cause, then <changing Y> will make the failure
+> disappear / <changing Z> will make it worse."*
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or
+sharpen it.
+
+**Show the ranked list to the user before testing.** Domain knowledge re-ranks
+instantly ("we just deployed a change to #3"), or they've already ruled out
+hypotheses. Cheap checkpoint, big time saver. Don't block on it — proceed with
+your ranking if the user is AFK.

package/pack/.claude/skills/devrites-debug-recovery/reference/instrumentation.md

@@ -0,0 +1,21 @@
+# Instrumentation
+
+Each probe maps to a specific prediction from the hypothesis phase.
+**Change one variable at a time.**
+
+## Tool preference
+
+1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. **NEVER** "log everything and grep".
+
+## Tagged prefixes
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at
+the end is a single grep. Untagged logs survive; tagged logs die.
+
+## Perf branch
+
+For performance regressions, logs are usually wrong. Establish a baseline
+measurement (timing harness, `performance.now()`, profiler, query plan), then
+bisect. **Measure first, fix second.**

package/pack/.claude/skills/devrites-debug-recovery/reference/regression-test.md

@@ -0,0 +1,31 @@
+# Fix + regression test
+
+Write the regression test **before the fix** — *but only if there is a correct
+seam for it*.
+
+A correct seam exercises the **real failure pattern** as it occurs at the call
+site. If the only available seam is too shallow (unit test that can't replicate
+the chain that triggered the failure), a regression test there gives false
+confidence.
+
+## No correct seam? That itself is the finding
+
+Note it in `evidence.md` and append a follow-up in the active feature's
+`decisions.md` (or open a `/rite-plan` repair item if the spec is affected): the
+codebase architecture is preventing this class of failure from being locked
+down. Frame it as a *deepening opportunity* — "this module needs a seam at <X>
+so failures here can be regression-tested" — so the next refactor (or an
+`improve-codebase-architecture` pass at the project level) has a concrete
+target.
+
+Do **not** invent an artificial seam just to host a test: a shallow seam that
+doesn't exercise the real call chain gives false confidence and is worse than
+no test at all.
+
+## When a correct seam exists
+
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail.
+3. Apply the fix.
+4. Watch it pass.
+5. Re-run the Phase 1 loop against the original (un-minimised) scenario.

package/pack/.claude/skills/devrites-doubt/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: devrites-doubt
+description: Stress-test a single non-trivial decision via CLAIM → EXTRACT → DOUBT → RECONCILE → STOP with `devrites-doubt-reviewer` for an independent take. Use when the user says "are we sure", "double-check this", "what could go wrong", or a boundary / data-model / auth / public-API / migration change is about to commit. Not for post-merge review or trivial choices.
+user-invocable: false
+---
+
+# devrites-doubt — CLAIM → EXTRACT → DOUBT → RECONCILE → STOP
+
+A pre-mortem on a single decision, not a final review. Find what's wrong before it's
+load-bearing.
+
+## When to use
+Introducing branching logic · crossing a module/service boundary · changing the data
+model · modifying auth/authz · changing a public API · touching migrations · changing a
+browser/user flow · relying on an assumption tests can't prove · working in unfamiliar
+code · claiming "this is safe", "this scales", or "this matches the spec".
+
+## The cycle (copy this checklist)
+
+- [ ] **1. CLAIM** — state the claim in 1–3 sentences + why it matters.
+- [ ] **2. EXTRACT** — isolate the smallest reviewable artifact + its contract; strip your reasoning so the reviewer sees only the code/decision.
+- [ ] **3. DOUBT** — invoke a fresh-context reviewer with an ADVERSARIAL prompt: *"find what's wrong; do not validate."* Prefer a real subagent (`.claude/agents/devrites-doubt-reviewer`) so it has no anchoring context.
+- [ ] **4. RECONCILE** — classify EVERY finding: contract misread | valid & actionable | valid trade-off | noise.
+- [ ] **5. STOP** — met a stop condition (only trivial findings, 3 cycles done, or user override). Emit a **binary gate verdict** the orchestrator must clear: **accept** (no valid-&-actionable findings remain) or **reject + the specific required changes**. On reject, the orchestrator loops the wright on those changes before the slice is accepted; still reject after the 3-cycle cap → escalate to the user.
+
+## Deletion-test lens (for "is this abstraction load-bearing?" doubts)
+
+When the claim is "this new module / boundary / wrapper is worth it", apply the
+**deletion test** before standing it: *imagine the abstraction never existed — does
+its complexity vanish (it was a pass-through, the abstraction was added on speculation)
+or does the same complexity re-appear distributed across N callers (it concentrates real
+complexity, deletion would smear it)?* Pass-throughs that fail the test get downgraded
+to "not yet" — wait for the second real caller before standing the seam.
+
+## Rules
+- For "where does this claim reach / what would change with it" questions, prefer a
+  code-intelligence index if available — codebase-memory-mcp (`detect_changes` / `trace_path`)
+  first, cross-checked with codegraph (`codegraph_impact` / `codegraph_callers`) + graphify,
+  else standard methods (LSP / Read/Grep/Glob); see `.claude/rules/tooling.md` — over file
+  reads; they answer impact in one call without polluting context.
+- The reviewer prompt must be adversarial — its job is to break the claim, not to agree.
+- Strip your own justification before review; reasoning anchors the reviewer toward
+  agreement.
+- Loop **max 3 times**. If material uncertainty remains after 3, **ask the user**.
+- Act on "valid & actionable" findings (fix or re-plan). Accept "valid trade-off"
+  explicitly in `decisions.md`. Discard "noise" with a one-line reason. Re-check
+  "contract misread" against the actual contract text.
+- In interactive sessions, a **cross-model second opinion** is allowed **only with
+  explicit user authorization**. Never run external CLIs without authorization.
+
+## AFK exception
+
+When `.devrites/AFK` exists and the user is away, `escalated to user` is unavailable in
+real time. Map the verdict to a `questions.md` entry instead of a synchronous prompt:
+
+- **Finding severity ≤ slice's gate ceiling** (the slice's `Gate:` plus `.devrites/AFK`
+  `allow_gates`, default `[advisory]`): append a `questions.md` entry with
+  `gate: advisory`, record the trade-off in `decisions.md`, and proceed with the best
+  inference. The advisory is surfaced by `/rite-status` so the user sees it on return.
+- **Finding severity > gate ceiling, OR the claim touches destructive migration,
+  auth/authz boundaries, public APIs, irreversible data writes**: append a
+  `questions.md` entry with `gate: blocking`, set `state.md` `Status: awaiting_human`,
+  fire the `notify:` hook, and STOP. AFK never silently accepts irreversible risk.
+
+The 3-loop limit still applies — after 3 cycles, the verdict is `escalated to user` and
+the unresolved doubt becomes a blocking question regardless of AFK config.
+
+## Output
+```
+Claim: ...
+Gate: accept | reject — <the specific required changes, if reject>
+Verdict: holds | revised | escalated to user
+Actionable findings handled: ...
+Trade-offs accepted (→ decisions.md): ...
+```