devrites 1.19.0

package/pack/.claude/skills/rite-define/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: rite-define
+description: Decompose an approved `spec.md` into `plan.md` + vertical task slices + `state.md`; every acceptance criterion maps to ≥1 slice. Use when the user says "plan this", "break this into slices", "task breakdown". Not for writing code or repairing an existing plan (use `/rite-plan`).
+argument-hint: "[feature-slug]"
+user-invocable: true
+---
+
+# /rite-define — plan from the spec
+
+Read the active feature's `spec.md` and turn it into a buildable plan: the approach, a
+dependency-ordered set of **vertical slices**, and the state cursor. The spec is the WHAT/
+WHY (from `/rite-spec`); this is the **HOW**. Splitting spec and plan keeps each focused so
+nothing gets missed in one batch. **No code here.**
+
+## Rules consulted (read on demand from `.claude/rules/`)
+**Step 0:** Read `.claude/rules/core.md` first. DevRites skills Read `.claude/rules/core.md`
+as their first step; the other rule files load on demand. Pull these via `Read` when shaping
+the plan:
+- `development-workflow.md` — small batches, trunk-always-green, definition of done.
+- `documentation.md` — record plan-time decisions and rationale.
+
+## Operating rules
+- **Requires a readied spec.** Read the active workspace first; if `.devrites/ACTIVE` is empty,
+  the workspace has no `spec.md`, its readiness gate hasn't passed, or any spec-quality
+  `checklists/<domain>.md` has an open CRITICAL → **STOP** and tell the user to run
+  `/rite-spec <feature>` first. **DO NOT plan from a missing or unreadied spec.**
+- Prefer existing conventions; ask before adding a dependency or a second design system.
+- **Slice count is derived, never dictated.** The number of slices falls out of the work
+  — one per independently-shippable increment, sized by `slicing.md`, every acceptance
+  criterion mapped to ≥1 slice. A user-named count is a hint at most: slice logically and,
+  if your honest count differs, present it and why. Never pad or compress to hit a figure.
+  (`.devrites/AFK` `max_slices` is a separate AFK iteration budget, not the decomposition.)
+
+## Workflow
+0. **Read `.claude/rules/core.md`** — the always-on operating rules and anti-rationalizations.
+   Then **run the shared orientation preamble** — it confirms the active feature and which
+   artifacts exist (it prints `state.md`, the artifacts present, the run mode, and the
+   open-question tally):
+   ```bash
+   P=.claude/skills/devrites-lib/scripts/preamble.sh
+   [ -f "$P" ] || P="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/preamble.sh"
+   [ -f "$P" ] || P=pack/.claude/skills/devrites-lib/scripts/preamble.sh
+   [ -f "$P" ] && bash "$P" || echo "(orientation preamble unavailable on this install — read state.md directly to orient)"
+   ```
+   If there is no active workspace, no `spec.md`, or its readiness gate hasn't passed →
+   **STOP** and tell the user to run `/rite-spec <feature>` first.
+1. **Read the spec** — `spec.md` (objective, requirements, acceptance, **placement**,
+   design references, gaps/decisions), plus `references.md`, `decisions.md`,
+   `assumptions.md`, **`strategy.md` if present** (the scope mode, deferred / out-of-scope
+   register, and pre-mortem risks from `/rite-temper` — cut slices to mitigate the top risks
+   and respect the IN/OUT line; map coverage against the **hardened** spec), and
+   **`design-brief.md` if the feature touches UI** (the UX/UI contract `/rite-spec` shaped —
+   its key states + interaction model drive how UI slices are cut). If a blocking
+   `[NEEDS CLARIFICATION]` remains, stop → `/rite-spec`.
+2. **Decide the approach + architecture** (the HOW the spec deliberately omitted): the
+   strategy, key technical decisions + rationale, and the tech the slices will use. Use a
+   code-intelligence index if available — codebase-memory-mcp first, cross-checked with codegraph + graphify, else standard methods (LSP / Read/Grep/Glob)
+   (see `.claude/rules/tooling.md`) — for structure/impact; for the current API or behaviour of
+   an external library/framework the architecture will rely on, consult context7 if available.
+   Record in `plan.md` ([plan-template](reference/plan-template.md)) and `decisions.md`.
+   **Deep-modules check** — while sketching the major modules, look for opportunities
+   to extract a **deep module**: a small, stable interface that hides a meaningful chunk
+   of behavior, and is therefore independently testable. A *shallow* module — interface
+   nearly as complex as its implementation — earns nothing; either deepen it or delete
+   it. Where a slice will produce a deep module, confirm with the user which deep
+   modules they want unit-tested in isolation (this informs the slice's "Tests to
+   write/run" field).
+3. **Slice into vertical tasks** — each delivers one observable capability end-to-end and
+   is verifiable on its own; the **count emerges from the work, not a target number**;
+   first slice = thinnest useful end-to-end path; order by dependency (risk-first within a
+   tier). Use `rite-plan/reference/slicing.md` and
+   `rite-plan/reference/task-breakdown.md`. Mark per slice: **Frontend craft required**
+   and **Browser proof required** (UI), and whether it's **fullstack** (FE+BE → contract
+   first, see `devrites-frontend-craft/reference/fullstack.md`). **For UI slices, name which
+   of `design-brief.md`'s key states + interaction the slice delivers** — so the brief's
+   state coverage maps onto slices, not just acceptance criteria.
+4. **Map coverage** — every spec acceptance criterion maps to ≥1 slice
+   (`rite-spec/reference/acceptance-criteria.md`); no orphaned criteria, no slice without a
+   criterion.
+4a. **Persist the traceability matrix** — write `coverage.md` (`AC-id → slice(s) → test →
+   evidence-status`), the living map `/rite-prove` and `/rite-seal` walk. Generate it with
+   `coverage.sh` (it reads `spec.md` acceptance + the `tasks.md` `Satisfies:` lines), or write the
+   table by hand from the same inputs if the script is absent:
+   ```bash
+   C=.claude/skills/devrites-lib/scripts/coverage.sh
+   [ -f "$C" ] || C="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/coverage.sh"
+   [ -f "$C" ] || C=pack/.claude/skills/devrites-lib/scripts/coverage.sh
+   S="$(cat .devrites/ACTIVE 2>/dev/null)"
+   [ -f "$C" ] && bash "$C" "$S" > ".devrites/work/$S/coverage.md" || echo "(coverage.sh unavailable — write coverage.md by hand from spec AC + tasks Satisfies:)"
+   ```
+5. **Complexity & deviations gate** — justify anything off DevRites defaults (new dep,
+   extra abstraction, second design system) in the plan; if you can't justify it, simplify.
+6. **Write** `plan.md` + `tasks.md`; update `state.md` (phase: plan → next `/rite-build`).
+7. **Readiness gate** (bottom of plan-template): every acceptance criterion covered by a
+   slice, dependency order acyclic + risk-first, no unjustified deviation, rollback for
+   every destructive/migration step. **Stop and confirm** before code. When the human
+   confirms the plan, write `Plan approved: <iso>` to `state.md` (see
+   [state-workspace](../rite-spec/reference/state-workspace.md)); `/rite-build` checks
+   this exists before building.
+
+## tasks.md slice format
+```markdown
+## Slice N: <name>
+Goal:
+Satisfies: AC-n[, AC-m]     # reverse traceability — which spec acceptance criteria this slice satisfies
+Acceptance criteria:        # which spec FR/criteria this satisfies
+Complexity: N/5 — <reason>  # 1=trivial … 5=hairy; >3 triggers a reslice unless the reason justifies it
+Mode: AFK | HITL            # AFK = implementable + mergeable without human gating;
+                            # HITL = needs a human decision mid-slice (design call,
+                            # architectural choice, destructive migration sign-off).
+                            # Prefer AFK; only mark HITL with the reason inline.
+Gate: advisory | validating | blocking | escalating   # required when Mode=HITL; see reference/gates.md
+SLA: 15m | 4h | 24h | none                            # required when Mode=HITL; matches the gate
+Checkpoint: <one crisp question>                       # required when Mode=HITL; what the human must decide
+Blocked by: Slice M, Slice K  # other slices that must complete first ("None" if free)
+depends_on: [Slice M, Slice K]  # machine-readable mirror of Blocked by (same set) — coverage.sh + /rite-status read it
+Consumes / Produces:        # interfaces this slice reads (types/endpoints/events from prior slices) and exposes for later ones
+Known-Gotchas:              # sharp edges / ordering hazards / framework footguns the wright must avoid (keeps the slice one-pass)
+Validation commands:        # exact runnable commands that prove the slice green (test / build / typecheck / lint)
+Prior-slice learnings:      # (filled forward) what an earlier slice discovered that this one must honor — starts empty
+Files likely touched:       # from the spec's Placement & integration
+Tests to write/run:
+Browser proof required: yes/no
+Frontend craft required: yes/no
+Design brief states:        # UI slices only — which design-brief.md states/interaction this slice delivers (default/empty/error/…)
+Fullstack (FE+BE): yes/no
+Dependencies:               # external deps (libs, services), NOT slice ordering
+Existing to reuse / extend:   # what already exists (components / utils / hooks) the slice should use
+Rollback notes:
+Evidence required:
+```
+
+> **Why Mode + Gate + Blocked by.** `Mode` lets `/rite-build` and `/rite-status` know
+> whether a slice can run unattended or must surface a checkpoint; `Gate` + `SLA` tell
+> AFK loops which gates they may auto-handle vs which always pause (see
+> [`reference/gates.md`](reference/gates.md) for the four-gate taxonomy:
+> advisory / validating / blocking / escalating). `Blocked by` makes the dependency
+> graph explicit so re-planning (`/rite-plan reorder`) doesn't break acceptance-criteria
+> coverage. Keep `Blocked by` cycle-free. `depends_on` is the machine-readable mirror tools read
+> to pick the next *buildable* slice; `Complexity` (>3 → reslice) sizes it; `Satisfies` +
+> `Consumes/Produces` + `Known-Gotchas` + `Validation commands` make each slice a self-contained,
+> one-pass-implementable brief (the PRP target `/rite-vet` checks).
+
+> **Mid-flight discipline.** When tempted to skip vertical slicing, coverage mapping, or dependency-order discipline — see [`anti-patterns`](reference/anti-patterns.md) (Common Rationalizations + Red Flags). Load it the moment you reach for the excuse.
+
+## Output
+
+**Footer first** — render the slice meter + flow ribbon by running the progress footer (`progress.sh`, resolved like the step-0 preamble — canonical snippet in `devrites-lib/SKILL.md`); keep the fact lines below it terse (`key value · key value`). Then:
+```
+Planned: <slug>
+Approach: <one line>
+Slices: N (slice 1: <name>)   Fullstack/UI slices: <which>
+Coverage: <all acceptance criteria mapped? yes/no>
+Strategy: honored (mode <m>; <n> pre-mortem risks → mitigation slices) | none (no strategy.md)
+Next: confirm, then /rite-vet to lock in the engineering plan (every feature — light or full per stakes), then /rite-build   (or /rite-plan to reshape the slices)
+↻ Hygiene: /clear after user confirms (plan.md + tasks.md + decisions.md + state.md captured). See rules/context-hygiene.md.
+```

package/pack/.claude/skills/rite-define/reference/anti-patterns.md

@@ -0,0 +1,25 @@
+# rite-define — anti-patterns
+
+Load this when standing a non-trivial planning decision in `/rite-define`,
+or when the agent feels reluctance toward vertical slicing or coverage
+mapping.
+
+Pack-wide rationalizations + red flags: see [rules/anti-patterns.md](../../../rules/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "Spec is good enough; just start coding." | Plan separates HOW from WHAT for a reason — missed HOW shows up as drift at slice 3. |
+| "One big slice is fine, the work is all related." | If slice 1 isn't shippable on its own, you're not slicing vertically — you're staging waterfall in disguise. |
+| "Tests can come at build time, not in tasks." | Every slice's `Tests to write/run` line is the contract that proves its acceptance — leave it blank, lose the contract. |
+| "Backend + frontend belong in one slice." | Fullstack goes contract-first: split the contract, then build a thin vertical slice that crosses both layers. |
+| "I can skip mapping every spec criterion." | An unmapped criterion is one nobody will build. Coverage isn't bureaucracy. |
+
+## Red Flags
+
+- A slice with no acceptance criterion link back to `spec.md`.
+- No first slice that's end-to-end thin (every slice depends on infra that doesn't exist yet).
+- A new dependency added without rationale in `decisions.md`.
+- A slice that doesn't list "Existing to reuse / extend" (you didn't search).
+- Plan readiness gate failing but you're about to call `/rite-build` anyway.

package/pack/.claude/skills/rite-define/reference/gates.md

@@ -0,0 +1,152 @@
+# Gate taxonomy — advisory · validating · blocking · escalating
+
+DevRites uses a four-gate model for HITL pauses, adapted from the regulated-agentic-workflow
+governance pattern. Picking the right gate for each `Mode: HITL` slice is the difference
+between a workflow that catches real risk and one that becomes a review queue.
+
+> **Default failure mode:** marking every HITL slice as `blocking`. The same reviewer ends
+> up approving low-stakes and high-stakes items at the same priority and the gate becomes
+> a queue. Mix gate types per slice; most plans use 2-3 of the 4.
+
+## The four gates
+
+### advisory
+
+**Stakes:** low. The slice can ship without the human's input; the question exists for
+audit / future record / FYI.
+
+**Behavior:** the slice runs. The question is logged to `questions.md` with
+`gate: advisory` and an explanation. `state.md` does **not** flip to `awaiting_human`.
+`/rite-status` surfaces the count but does not flag it as blocking.
+
+**Example:** "We picked option A from the prototype's verdict but option B is also viable.
+Recording the choice for posterity."
+
+**SLA:** `none` — there is no waiting time because nothing is waiting.
+
+### validating
+
+**Stakes:** medium. The slice can be built but should not merge before a human signs off.
+Async — the human reviews when they get to it, but the loop does not stall.
+
+**Behavior:** in HITL mode, `/rite-build` pauses on this gate and writes
+`Awaiting human` to `state.md`. In AFK mode with `allow_gates: [advisory, validating]`,
+`/rite-build` builds the slice but marks it `built (pending review)` and writes the
+validating question; the feature does not seal until the entry is resolved. An open
+`gate: validating` entry is **merge-blocking by definition** — a slice marked
+`built (pending review)` is not done, and seal is a NO-GO while it stands open.
+
+**Example:** "Schema migration adds a non-null column with a default. Backfill plan is
+recorded; reviewer should confirm the default is the right one for archived rows."
+
+**SLA:** `4h` — the work continues but the validating queue should drain within hours,
+not days.
+
+### blocking
+
+**Stakes:** high. The slice cannot proceed safely without the answer. Synchronous —
+the loop stops.
+
+**Behavior:** **always pauses regardless of `.devrites/AFK` config.** `/rite-build`
+writes `Awaiting human`, sets `Status: awaiting_human`, fires the `notify:` hook, and
+STOPs. The slice is not built until `/rite-resolve` lands.
+
+**Examples:**
+- Destructive migration (data loss risk).
+- Auth/authz boundary change.
+- Public API break.
+- Spec drift that changes acceptance criteria.
+- Tests / types / lint are red and the agent cannot tell whether the slice's contract is
+  wrong or the failing code is.
+
+**SLA:** `15m` — synchronous gates demand fast turnaround; otherwise treat the work as
+genuinely blocked and re-plan around it.
+
+### escalating
+
+**Stakes:** novel pattern. The question is not within the active reviewer's scope and
+needs to route to a specialist (legal, security, principal engineer, designer-of-record).
+
+**Behavior:** same pause behavior as `blocking`, but the `questions.md` entry includes a
+`route:` field naming the specialist tag. `/rite-status` shows it under a separate
+"Escalating" line so it doesn't compete with synchronous blockers for the same reviewer.
+
+**Example:** "Slice introduces a contract with an external partner — needs legal review
+of the data-sharing language."
+
+**SLA:** `24h` — specialist routing implies the SLA is loose; if it needs to be tight,
+it's actually `blocking`.
+
+## Picking the gate
+
+Apply this decision tree per HITL slice:
+
+1. **Can the slice ship safely without the answer?**
+   - Yes → `advisory`.
+   - No → continue.
+2. **Does the slice need a different reviewer than the default one?**
+   - Yes → `escalating`.
+   - No → continue.
+3. **Can the slice be built but not merged until reviewed?**
+   - Yes → `validating`.
+   - No → `blocking`.
+
+## SLA mapping
+
+| Gate | SLA | Synchronous? |
+|---|---|---|
+| advisory | `none` | — (does not pause) |
+| validating | `4h` | no (async; build continues, merge blocks) |
+| blocking | `15m` | yes |
+| escalating | `24h` | yes, but to a specialist |
+
+SLAs are guidance for human reviewers and for tools that surface stale questions. DevRites
+itself does not enforce them; `/rite-status` reports time since `raised_at` so the user
+can see when a gate is slipping.
+
+## AFK interaction
+
+`.devrites/AFK` carries an `allow_gates:` list. AFK auto-handles a gate by logging the
+question as advisory and proceeding **only when** the gate is in `allow_gates`. The
+defaults and the always-pause rules:
+
+| AFK `allow_gates` | advisory | validating | blocking | escalating |
+|---|---|---|---|---|
+| `[]` (or omitted) | log + proceed | pause | pause | pause |
+| `[advisory]` (default) | log + proceed | pause | pause | pause |
+| `[advisory, validating]` | log + proceed | build + queue | pause | pause |
+| `[advisory, validating, blocking]` | log + proceed | build + queue | log + proceed* | pause |
+
+\* but **never** for destructive migrations, auth/authz boundary changes, public API
+breaks, or red tests/types/lint — those always pause. See
+[`.claude/rules/afk-hitl.md`](../../../rules/afk-hitl.md) for the irreversible-risk
+list.
+
+`escalating` is never in `allow_gates` — specialist routing is not something AFK can
+shortcut.
+
+## Anti-patterns
+
+- **One gate for everything.** Validates becomes a queue, blocks all work behind one
+  reviewer. Pick gates per slice.
+- **Marking a destructive migration `validating` to "keep the loop moving".** Destructive
+  work is `blocking` regardless of the urge to ship.
+- **`advisory` as a synonym for "I'm not sure but I don't want to ask".** If the slice
+  needs the answer, it's not advisory. Pick the right gate instead.
+- **`escalating` with no `route:` field.** Without a specialist tag, an escalation is
+  just a slow blocker. Name who answers.
+
+## Field shape in `tasks.md`
+
+```markdown
+## Slice 03: list endpoint
+Mode: HITL
+Gate: blocking
+SLA: 15m
+Checkpoint: Confirm (user_id, created_at) composite index choice vs two single-col indexes.
+Blocked by: Slice 02
+...
+```
+
+`Gate`, `SLA`, and `Checkpoint` are **required** when `Mode: HITL`. The plan readiness
+gate in `plan-template.md` enforces this.

package/pack/.claude/skills/rite-define/reference/plan-template.md

@@ -0,0 +1,65 @@
+# `plan.md` template
+
+Write **how** to build what `spec.md` defines. The plan is **living, not sacred** —
+`/rite-plan` repairs it when reality disagrees. This is where technology choices live
+(they're banned from the spec).
+
+```markdown
+# Plan: <Feature>
+Spec: ./spec.md   Date: <date>
+
+## Summary
+1–2 sentences: the primary requirement + the chosen approach.
+
+## Technical context
+- Language / runtime + version: <e.g. TypeScript 5, Node 20>
+- Frameworks / libraries in play: <...>
+- Storage / data: <...>
+- Testing tools + commands: <from spec "Commands discovered">
+- Target / platform / constraints: <...>
+- `[NEEDS CLARIFICATION: ...]` for any unknown that affects the approach.
+
+## Approach
+The strategy in a few sentences. Why this over the alternatives considered.
+
+## Architecture decisions
+Key decisions + rationale (mirror into decisions.md). New pattern vs reuse — prefer
+reuse of existing project conventions.
+
+## Dependency graph
+What must exist before what (text is fine):
+- Slice 1 (no deps) → Slice 2 (needs 1) → Slice 4 (needs 2,3)
+- Slice 3 (independent / parallelizable)
+
+## Implementation order
+Ordered slice list + the reason for the order (risk-first within a dependency tier).
+
+## Verification checkpoints
+After which slices to run tests / build / browser proof.
+
+## Complexity & deviations gate
+List anything that deviates from DevRites defaults (prefer existing conventions, the
+simplest approach, feature scope only, no new deps/design system) and **justify it**.
+If you can't justify a deviation, simplify instead of recording it.
+| Deviation | Why needed | Simpler option rejected because |
+|-----------|-----------|---------------------------------|
+| <e.g. new dependency X> | <reason> | <why the in-repo option won't work> |
+
+## Rollback notes
+How to back out each risky step (migration down, feature flag, revert boundary, backup).
+
+## Scope boundaries
+What this plan will NOT touch. Restate "Ask first" / "Never do" from the spec.
+
+## Source docs needed
+Framework/library docs to consult (triggers devrites-source-driven). Record URLs in
+decisions.md / evidence.md when used.
+
+## Readiness gate  *(must pass before /rite-build)*
+- [ ] Every spec acceptance criterion is covered by a slice
+- [ ] Dependency order is acyclic and risk-first
+- [ ] No unjustified deviation remains in the complexity gate
+- [ ] Rollback exists for every destructive / migration step
+- [ ] Every `Mode: HITL` slice has `Gate`, `SLA`, and `Checkpoint` populated
+- [ ] No `Gate: blocking` slice is implicitly chained behind an AFK slice without surfacing the dependency
+```

package/pack/.claude/skills/rite-doctor/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: rite-doctor
+description: Diagnose DevRites install + workspace health on demand and print a full report — install integrity, a stale `.devrites/ACTIVE` pointer, a corrupt workspace, orphaned gates, and broken hook wiring. Use when the user says "rite doctor", "check my DevRites install", "is DevRites healthy", "diagnose devrites", or "why isn't the workflow picking up my feature". Not for debugging the user's own code (use `devrites-debug-recovery`) or for feature progress / next-action (use `/rite-status`).
+argument-hint: ""
+user-invocable: true
+---
+
+# /rite-doctor — health check
+
+The on-demand deep report. The same checks run **silently at session start** (the orient
+hook surfaces issues only when there are any); `/rite-doctor` runs them **verbosely** —
+printing every check, pass or fail — so you can inspect health even when nothing is broken.
+
+It is **read-only**: it never edits the workspace, never advances a phase, never blocks.
+
+## Workflow
+1. Run the diagnose core verbosely (resolve across install layouts):
+   ```bash
+   D=.claude/skills/devrites-lib/scripts/doctor.sh
+   [ -f "$D" ] || D="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/doctor.sh"
+   [ -f "$D" ] || D=pack/.claude/skills/devrites-lib/scripts/doctor.sh
+   [ -f "$D" ] && bash "$D" --verbose; echo "doctor rc=$?"
+   ```
+1a. **Surface the learnings nudge** — point the user at `/rite-learn` when a pattern recurs across
+   shipped features (read-only; silent when there's nothing to say):
+   ```bash
+   L=.claude/skills/devrites-lib/scripts/learnings.sh
+   [ -f "$L" ] || L="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/learnings.sh"
+   [ -f "$L" ] || L=pack/.claude/skills/devrites-lib/scripts/learnings.sh
+   [ -f "$L" ] && bash "$L" nudge || true
+   ```
+2. Report the result. **rc=0** → "DevRites healthy" + the `ok:` checks. **rc=1** → list each
+   `issue:` line with the fix it names, then the single command that resolves the most urgent
+   one (a stale ACTIVE → `rite use <slug>` or `/rite-status`; an orphaned gate →
+   `/rite-resolve <qid>`; an incomplete install → reinstall).
+3. **Do not fix anything yourself** — doctor is diagnostic. Hand the user the fix command.
+
+## Gotchas
+- Read-only — never write the workspace or advance a phase (that's the lifecycle skills' job).
+- It diagnoses **DevRites** health, not the user's application — code bugs go to
+  `devrites-debug-recovery`; feature progress goes to `/rite-status`.
+- Healthy is the common case; say so plainly and stop. Don't invent issues.
+
+## Output
+```
+DevRites health: OK | N issue(s)
+<for each issue: the problem + its fix>
+Learnings: <n recurring pattern(s) across features → /rite-learn | none>
+Next: <single command for the most urgent issue, or "nothing to do">
+```

package/pack/.claude/skills/rite-frame/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: rite-frame
+description: Pre-flight + self-audit lens that applies the four classic LLM coding failure modes — silent assumption, overcomplication, out-of-scope edit, unverifiable goal — to ad-hoc and express-lane work the full lifecycle's gates never see. FRAME converts an imperative ask into a falsifiable success criterion + verify command before any code; AUDIT checks the resulting diff against the four modes, each mapped to its DevRites cure. Use at the top of `/rite-quick`, before a plain "just do X" / "quick fix" edit, or to self-review a raw diff for assumptions, bloat, scope creep, or a missing success criterion. Not a replacement for the lifecycle gates (`/rite-seal`, `/rite-review`), the adversarial subagent pre-mortem (`devrites-doubt`), or the fresh-context axis audit (`devrites-audit`) — it is the lightweight inline reflex for work that skips those.
+argument-hint: "[task to frame | diff to audit]"
+user-invocable: true
+---
+
+# /rite-frame — frame the goal, audit the diff
+
+LLMs reliably get four things wrong: they **assume** silently, **overcomplicate**, edit
+**out of scope**, and run on an **unverifiable** "make it work". The full DevRites
+lifecycle catches all four at its gates (spec readiness, the Spec Drift Guard,
+`touched-files.md` + `reconcile.sh`, `/rite-seal`). But the express lane and plain
+"just do X" requests **skip those gates** — and a raw diff has no gate at all.
+
+`rite-frame` is the gate's reflex made portable. Two moves, no workspace required:
+
+- **FRAME** (before code) — turn the imperative ask into a falsifiable success criterion
+  and the command that proves it. *"Give it success criteria and watch it go."*
+- **AUDIT** (after the change) — read the diff against the four failure modes; route each
+  finding to the DevRites cure that already exists for it.
+
+It is a self-applied lens, not a subagent and not a phase. Light enough to run at the top
+of a one-line fix; the heavy guns (`devrites-doubt`, `devrites-audit`, the seal) stay where
+they are.
+
+## When to use
+At the top of `/rite-quick` · before a plain "just do X" / "quick fix" / "tiny tweak" edit
+that won't go through the lifecycle · to self-review a raw `git diff` before you commit ·
+any time you're about to act on an imperative without a written success criterion.
+
+**When not:** a real feature (use `/rite-spec`) · a single high-stakes decision that wants
+an adversarial second read (`devrites-doubt`) · a fresh-context axis review of an active
+feature (`devrites-audit <security|perf|simplify>`) · the final GO/NO-GO (`/rite-seal`).
+rite-frame is the *inline* reflex; those are the *gates*. Don't use it to dodge one.
+
+## FRAME — before you touch code
+
+Restate the ask as a check, not a chore. Convert the verb into a condition that can be
+**false**:
+
+| Imperative ask | Falsifiable success criterion |
+|---|---|
+| "Add validation" | "Inputs `{empty, oversize, wrong-type}` are rejected with a 4xx + message — a test asserts each, and fails today." |
+| "Fix the bug" | "A test reproduces the bug (red now), and turns green after the fix — nothing else changes." |
+| "Make it faster" | "Operation X drops from `<measured baseline>` to `<target>` on `<named benchmark>`." |
+| "Refactor X" | "The existing suite is green before and after; behavior is byte-identical." |
+| "Clean this up" | *(no falsifiable criterion → the ask is ambiguous → mode 1 → ask what "clean" means, or route to `/rite-spec`)* |
+
+Checklist (copy it):
+
+- [ ] **Criterion** — one sentence: *"Done WHEN `<observable, falsifiable check>`."* If you
+      can't write one that could be false, the ask is ambiguous — **stop, name it, ask** (that
+      is failure mode 1, surfaced early instead of after the diff).
+- [ ] **Verify command** — the exact test / build / runtime / screenshot that decides it.
+      No command → no proof → you're about to confidence-assert. Name it now.
+- [ ] **Scope boundary** — the files/areas you will **not** touch. Anything outside is mode 3.
+- [ ] **Loop** — with a falsifiable criterion you can iterate to green unattended; with a weak
+      one ("make it work") you'll need the user every few minutes. Sharpen the criterion until
+      it can drive the loop.
+
+## AUDIT — after the change
+
+Read the diff (or `$ARGUMENTS`) against the four modes. One line per finding, severity-tagged
+(`Critical / Important / Suggestion / Nit / FYI`), each routed to its existing cure. Full
+map + worked examples: [`reference/failure-modes.md`](reference/failure-modes.md).
+
+- [ ] **1 · Silent assumption** — did I pick one reading of an ambiguous ask and run with it?
+      Any value, contract, or behavior I *guessed*? → surface it; route material ones through
+      the Spec Drift Guard (`core.md` #2/#3).
+- [ ] **2 · Overcomplication** — an abstraction / flag / indirection nobody asked for? 200 lines
+      where 50 would do? A defensive check inside trusted code? → apply the **deletion test**;
+      simplify (`coding-style.md`, `patterns.md`, `devrites-audit simplify`).
+- [ ] **3 · Out-of-scope edit** — did I touch code, comments, or formatting outside the ask?
+      "While I'm here" refactors? → revert to the boundary; record the rest as an FYI follow-up
+      (`core.md` #7, `touched-files.md`).
+- [ ] **4 · Unverifiable goal** — is there a command that proves this, run, with output? Or am
+      I asserting "it works"? Tautological test that can't fail? → run the FRAME verify command;
+      record command + output (`testing.md`, evidence-over-confidence).
+
+The test for each changed line: **it traces directly to the criterion, and the criterion can
+be proven false.** A line that fails either is a finding.
+
+## Escalation
+
+If FRAME can't produce a falsifiable criterion, or AUDIT surfaces a mode-1 / mode-3 issue that
+is actually a hidden design decision (new dependency, data model, second design system, an
+auth/migration/public-API touch) → **STOP and route to `/rite-spec`**. Same drift guard the
+express lane enforces — don't quietly grow an unframed ask into unreviewed work.
+
+## Rules
+- Self-applied and inline. No subagent, no `.devrites/` workspace required. For an adversarial
+  fresh-context read of one decision use `devrites-doubt`; for a fresh-context axis audit of an
+  active feature use `devrites-audit`.
+- FRAME before code, AUDIT after. Running AUDIT without having framed the criterion first means
+  mode 4 has nothing to check against.
+- A criterion that can't be false isn't a criterion — it's a wish. Rewrite it or ask.
+- Feature/ask scope only. Out-of-scope findings become FYI follow-ups, never silent fixes.
+
+## Output
+```
+FRAME
+  Criterion: Done WHEN <falsifiable check>.
+  Verify:    <exact command / observation>
+  Boundary:  <files/areas NOT touched>
+
+AUDIT (post-change)
+  1 assumption    : <clean | finding → cure>
+  2 simplicity    : <clean | finding → cure>
+  3 scope         : <clean | finding → cure>
+  4 verifiable    : <command → result, or finding>
+Verdict: framed & clean  |  N findings (acted | escalated to /rite-spec)
+```
+
+↻ Hygiene: rite-frame adds no workspace state — nothing to persist. If it routed you to
+`/rite-spec`, that phase owns the handoff from here.

package/pack/.claude/skills/rite-frame/reference/failure-modes.md

@@ -0,0 +1,68 @@
+# The four failure modes — mapped to their DevRites cure
+
+The lens behind `rite-frame`. Each mode is a thing LLMs reliably get wrong; each already
+has a cure somewhere in the pack. The value of naming them here is a **portable
+vocabulary** — a fast self-check you can run on ad-hoc or express-lane work that never
+reaches the gates where those cures normally fire.
+
+## The map
+
+| # | Failure mode | The tell in a diff / a reply | Cure already in the pack |
+|---|---|---|---|
+| 1 | **Silent assumption** | A value, contract, edge case, or interpretation was *guessed* and run with — no note, no question. The ask had two readings and one was picked silently. | `core.md` #2 (no silent assumptions) / #3 (no guessing through confusion); the Spec Drift Guard; `devrites-doubt` for a single high-stakes call; `devrites-interview` when the ask is underspecified. |
+| 2 | **Overcomplication** | An abstraction, flag, config knob, or indirection nobody asked for. 200 lines where 50 would do. A single-use factory. Defensive `try/catch` + null checks inside trusted code. A dependency added where an in-repo option exists. | `coding-style.md` (simplicity, reuse-first), `patterns.md` (avoid over-engineering), `devrites-audit simplify` (deletion test, Chesterton's Fence), the "over-defensive guarding is slop" anti-pattern. |
+| 3 | **Out-of-scope edit** | Touched code, comments, or formatting outside the ask. A "while I'm here" refactor. Renamed something orthogonal. Reflowed an import block. | `core.md` #7 (feature scope only), `touched-files.md` (the recorded diff boundary), `reconcile.sh` (hard-stops a source file changed outside the claimed set), the "it's only a small refactor" anti-pattern. |
+| 4 | **Unverifiable goal** | "It works" with no command, no output, no test. A success criterion that can't be false ("make it better"). A tautological test that passes no matter what. | `rite-spec/reference/acceptance-criteria.md` (measurable acceptance), `core.md` #6 (evidence over confidence), `testing.md` (assertion strength, see it fail first), the TDD wright. |
+
+The first three are the **diseases** Karpathy named; the fourth is the **leverage** — a
+falsifiable criterion is what lets the model loop to done without a human in the loop every
+few minutes. FRAME front-loads mode 4 so the AUDIT of modes 1–3 has something to check
+against.
+
+## FRAME: the imperative → falsifiable reframe
+
+The move is to rewrite the *verb* as a *condition that can be false*. If you can't, the ask
+is ambiguous — that's mode 1, caught before the diff instead of after.
+
+| Imperative ask | Weak (still a wish) | Falsifiable criterion + verify |
+|---|---|---|
+| "Add validation" | "validate the inputs" | "`{empty, oversize, wrong-type}` → 4xx + message; a test asserts each and is red today." → `npm test path/to.spec` |
+| "Fix the bug" | "make the bug go away" | "Test reproducing the report is red now, green after, nothing else changes." → the repro test |
+| "Make it faster" | "improve performance" | "Endpoint X p95 `<baseline ms>` → `<target ms>` on `<named bench>`." → the benchmark cmd |
+| "Refactor X" | "clean up X" | "Existing suite green before and after; behavior byte-identical." → full suite, twice |
+| "Handle errors" | "add error handling" | "On `<failure F>` the system fails closed with `<observable>`; a test forces F." → that test |
+| "Improve the UX" | "make it nicer" | *(no falsifiable check → ambiguous → `devrites-ux-shape` / ask which states/flows)* |
+
+A criterion passes the bar when a reviewer could run the verify command and get a clear
+pass or fail without asking you what you meant. If they'd have to ask, sharpen it.
+
+## AUDIT: worked finding lines
+
+Findings read like the rest of the pack — one line, severity-tagged, cite `file:line`, route
+to the cure. Severity ladder is the pack standard (`Critical / Important / Suggestion / Nit /
+FYI`).
+
+```
+auth.ts:42  Important  mode 1 (assumption): assumes `role` is always present — unset on legacy rows. → validate at boundary or ask (core #2).
+cart.ts:88  Suggestion mode 2 (overcomplication): single-use `StrategyFactory` for one caller. → inline; deletion test fails it (devrites-audit simplify).
+utils.ts:5  FYI        mode 3 (scope): reflowed an unrelated import block. → revert to boundary; not in this ask (core #7).
+sum.spec:12 Important  mode 4 (unverifiable): test asserts `mock.called`, not the result — passes if the fn is empty. → assert the value; see it fail first (testing.md).
+```
+
+Clean lanes say so explicitly — `1 assumption: clean` — so the audit is a positive
+statement, not a silent skip.
+
+## How this differs from the heavier tools (so you don't reach past it)
+
+- **`devrites-doubt`** — adversarial *fresh-context subagent* pre-mortem on **one** decision.
+  Heavier, independent, anti-anchoring. rite-frame is *self-applied* and covers the four modes
+  broadly; escalate a single load-bearing claim to doubt.
+- **`devrites-audit <axis>`** — *fresh-context subagent* review of an **active feature's** diff
+  on one axis (security / perf / simplify). Needs a `.devrites/` workspace. rite-frame needs no
+  workspace and runs in your own context — cheaper, less independent.
+- **`/rite-review` · `/rite-seal`** — the **gates**: parallel reviewer fan-out, blocking
+  severities, written verdict. rite-frame is the inline reflex for work that never reaches a
+  gate; it does not replace one. If the work is a real feature, the gate is the answer.
+
+The point is not redundancy — it's a tiered ladder. rite-frame is the cheapest rung: a lens
+you run yourself in seconds. Climb to doubt / audit / the gates as the stakes rise.