devrites 1.19.0

package/docs/command-map.md

@@ -0,0 +1,143 @@
+# DevRites Command Map
+
+Reference for every shipped skill and agent — what triggers it, what it reads,
+what it writes, and how the pieces interact.
+
+- **Workflow diagram** (top-level flow) → [`flow.md`](flow.md).
+- **Architecture rationale** → [`architecture.md`](architecture.md).
+- **Worked examples** → [`usage.md`](usage.md).
+
+## Naming convention
+
+`devrites-` is a **namespace prefix** chosen for collision avoidance against
+bundled Claude Code skill names (`prototype`, `handoff`, `triage`, `diagnose`,
+…). It does **not** signal "internal" — visibility is governed by the
+`user-invocable:` flag in each `SKILL.md`. All five public utilities use the
+`rite-*` prefix (`rite-zoom-out`, `rite-prototype`, `rite-handoff`,
+`rite-pressure-test`, `rite-autocomplete`); every `devrites-*` skill is
+model-invoked.
+
+## Public commands (`user-invocable: true`)
+
+| Command | Phase | Argument | What it does | Reads | Writes |
+|---|---|---|---|---|---|
+| [`/rite`](../pack/.claude/skills/rite/SKILL.md) | menu | `[subcommand]` | Compact menu + suggested next command. Pure router; does **not** read state — that's `/rite-status`. | — | — |
+| [`/rite-spec`](../pack/.claude/skills/rite-spec/SKILL.md) | spec | `<feature>` | **Start here.** Deep investigation → writes `spec.md` (placement, what-it-resolves, gaps closed with options, design references). Creates the workspace. | codebase + codegraph/graphify | `spec.md`, `references/`, `references.md`, `brief.md`, `questions.md`, `decisions.md`, `assumptions.md`, `state.md` |
+| [`/rite-temper`](../pack/.claude/skills/rite-temper/SKILL.md) | temper | `[slug] [--mode]` | **Optional, before define.** Strategic review of the readied spec: scope mode (expand / selective / hold-rigor / reduce-to-MVP) + pre-mortem + 9-dimension floor-gate; folds decisions into the spec via the Spec Drift Guard. Significance-gated; **mandatory in `/rite-autocomplete`**. Reviewer: `devrites-strategy-reviewer`. | `spec.md` + decisions/assumptions + design-brief | `strategy.md`, `spec.md`, `decisions.md`, `assumptions.md` |
+| [`/rite-define`](../pack/.claude/skills/rite-define/SKILL.md) | plan | `[slug]` | Turns the approved `spec.md` into plan + vertical task slices + state. Reads `strategy.md` if present. | `spec.md` (+ `strategy.md`) + references | `plan.md`, `tasks.md`, `state.md`, `decisions.md` |
+| [`/rite-vet`](../pack/.claude/skills/rite-vet/SKILL.md) | vet | `[slug] [--cross-model] [--full]` | **Before build — every feature.** Engineering review of the defined plan: scope challenge (reuse / minimum-diff / complexity smell) + architecture / plan code-quality / test-coverage design / performance, confidence-banded with a quote-the-source verification gate; failure-mode + parallelization map. Hardens `plan.md` / `tasks.md` in place; writes the build-readable `test-plan.md`; acceptance-changing deltas route via the Spec Drift Guard. Runs on every plan — depth scales to stakes (light pass on simple plans, full on big/risky), never skipped; **always in `/rite-autocomplete`**. Reviewer: `devrites-plan-reviewer` (+ optional `--cross-model`). | `plan.md` + `tasks.md` + `spec.md` (+ `strategy.md`) | `eng-review.md`, `test-plan.md`, `plan.md`, `tasks.md`, `decisions.md`, `state.md` |
+| [`/rite-plan`](../pack/.claude/skills/rite-plan/SKILL.md) | plan | `[mode]` | Decompose / reslice / repair / re-order / split / unblock an active plan. | spec/plan/tasks/state/drift + diff | `plan.md`, `tasks.md`, `state.md`, `decisions.md` |
+| [`/rite-build`](../pack/.claude/skills/rite-build/SKILL.md) | build | `[slice]` | Implement **exactly one** vertical slice, then stop. | workspace + diff | code + `state.md`, `evidence.md`, `touched-files.md` |
+| [`/rite-prove`](../pack/.claude/skills/rite-prove/SKILL.md) | prove | `[scope]` | Tests + build + runtime + browser proof of the completed feature. | workspace + diff | `evidence.md`, `browser-evidence.md`, `state.md` |
+| [`/rite-polish`](../pack/.claude/skills/rite-polish/SKILL.md) | polish | `[target \| mode]` | Orchestrator. Reads `reference/code.md` always (Phase 1 + 2); reads `reference/ui.md` when UI is touched (Phase 3 + 4). Mode tokens: `bolder \| quieter \| distill \| harden \| normalize-only`. | workspace + design system + diff | `polish-report.md`, `browser-evidence.md` |
+| [`/rite-review`](../pack/.claude/skills/rite-review/SKILL.md) | review | `[scope]` | Feature-scoped multi-axis review. Parallel Spec + Standards sub-agents (`devrites-spec-reviewer`, `devrites-code-reviewer`). | workspace + diff | `review.md`, `evidence.md`, `state.md` |
+| [`/rite-seal`](../pack/.claude/skills/rite-seal/SKILL.md) | seal | — | GO / NO-GO **decision**, hands off to `/rite-ship`. Walks acceptance vs evidence, fans out reviewers, writes the verdict. Runs no git; on GO sets `state.md` `Next step: /rite-ship`. Triggers: "GO / NO-GO", "is it safe to merge", "decide if we can ship". | all artifacts + diff | `seal.md`, `state.md` |
+| [`/rite-ship`](../pack/.claude/skills/rite-ship/SKILL.md) | ship | `[slug]` | Final phase. Requires a GO in `seal.md` → renders type-`GO` + runs the irreversible git ladder (commit → push → tag/PR) + closes the task (archive workspace → `.devrites/archive/<slug>/`, clear `ACTIVE`, phase `done`). Triggers: "ship it", "ship this", "push it out", "close the task". | `seal.md` + all artifacts + diff | `ship.md`, `state.md`, archive |
+| [`/rite-autocomplete`](../pack/.claude/skills/rite-autocomplete/SKILL.md) | (orchestrator) | `[idea] [--ship\|--yolo] [--max-slices N]` | Full unattended lifecycle (spec → … → seal → ship), best option at each soft gate, rationale to `decisions.md`. Vague prompt → up-front interview; pauses on hard-risk / blocking / escalating / open-validating / NO-GO / budget-exhausted. Default stops at the final type-`GO`; `--ship` flag (alias `--yolo`) auto-confirms it. Triggers: "autocomplete", "do the whole thing". | idea + workspace | whole workspace (drives every phase) |
+| [`/rite-quick`](../pack/.claude/skills/rite-quick/SKILL.md) | (express) | `<change>` | Express lane for a **small, reversible, unambiguous** change — one-line contract → TDD build → scoped prove → review-lite → ship, no full artifact tree. **Significance gate first**: auth / migration / public-API / destructive / multi-slice / ambiguous → escalates to `/rite-spec`. Triggers: "quick fix", "small change", "tiny tweak", "just do X". | the change + codebase | code + commit (optional `brief.md` / `evidence.md`) |
+| [`/rite-status`](../pack/.claude/skills/rite-status/SKILL.md) | status | `[slug]` | Active feature: phase, run mode (AFK/HITL), status, next action, evidence, open questions by gate, risks, handoff readiness. Reads via the shared `devrites-lib` preamble (portable). | workspace + `.devrites/AFK` | — |
+| [`/rite-resolve`](../pack/.claude/skills/rite-resolve/SKILL.md) | resume | `<qid> "<answer>"` \| `--drop <qid>` \| `--batch <file>` | Answer / drop / batch-resolve open `questions.md` entries; clears `state.md` `Awaiting human` and sets `Status: running`. Canonical writer for `status: open → answered`. | `questions.md` + `state.md` | `questions.md`, `state.md` |
+| [`/rite-zoom-out`](../pack/.claude/skills/rite-zoom-out/SKILL.md) | utility | — | One-pass structural map of an unfamiliar area (modules, in-callers, out-calls, decisions) in project vocabulary. Prefers codegraph/graphify. | codebase + ADRs/CONTEXT.md | — |
+| [`/rite-prototype`](../pack/.claude/skills/rite-prototype/SKILL.md) | utility | `[question]` | Throwaway code answering ONE design question. Logic harness OR 2–4 UI variations on one route. Captures verdict to `decisions.md`. | spec / surrounding code | prototype scratch + `decisions.md` |
+| [`/rite-handoff`](../pack/.claude/skills/rite-handoff/SKILL.md) | utility | `[next-session-focus]` | Compacts the chat into a handoff doc. Syncs chat-only context into workspace canonical files. References existing artifacts by path. | chat + workspace | `handoff.md` + sync into canonical files |
+| [`/rite-learn`](../pack/.claude/skills/rite-learn/SKILL.md) | utility | `[--mine \| "<lesson>"]` | Mine archived features for recurring mistakes / dismissed-finding classes; propose project-local lessons into `.devrites/learnings.md` (loaded by the review skills before a fan-out). | archive + workspace | `.devrites/learnings.md` |
+| [`/rite-pressure-test`](../pack/.claude/skills/rite-pressure-test/SKILL.md) | utility | `[idea]` | Pressure-test a rough idea: 3–5 genuinely different options → converge on one with trade-off + hinge. | spec / surrounding code | `decisions.md` (optional) |
+
+## Internal skills (`user-invocable: false`, model-invoked)
+
+| Skill | Triggered by | Role | Notable |
+|---|---|---|---|
+| [`devrites-interview`](../pack/.claude/skills/devrites-interview/SKILL.md) | `/rite-spec`, underspecified ask | One-Q-at-a-time protocol | best-guess + confidence stop |
+| [`devrites-source-driven`](../pack/.claude/skills/devrites-source-driven/SKILL.md) | uncertain framework/library fact | Consult docs/source, record citation | writes `evidence.md` / `decisions.md` |
+| [`devrites-doubt`](../pack/.claude/skills/devrites-doubt/SKILL.md) | non-trivial decision in build/review | CLAIM → EXTRACT → DOUBT → RECONCILE → STOP | adversarial; ask user if uncertain |
+| [`devrites-ux-shape`](../pack/.claude/skills/devrites-ux-shape/SKILL.md) | UI detected in `/rite-spec` | Plan UX/UI before code → `design-brief.md` (direction, states, interaction, visual-direction probe) | the build target; refs: brief-template/visual-direction-probe |
+| [`devrites-frontend-craft`](../pack/.claude/skills/devrites-frontend-craft/SKILL.md) | UI detected in build/polish | Build **to** `design-brief.md`: register, refine-per-slice, states, anti-slop | refs: shape/craft/design-references |
+| [`devrites-browser-proof`](../pack/.claude/skills/devrites-browser-proof/SKILL.md) | UI in prove/polish | Browser proof ladder + evidence schema | harness preferred |
+| [`devrites-debug-recovery`](../pack/.claude/skills/devrites-debug-recovery/SKILL.md) | failing tests/build/runtime | 6-phase: loop → reproduce → hypotheses → instrument → fix → cleanup | references split per phase |
+| [`devrites-api-interface`](../pack/.claude/skills/devrites-api-interface/SKILL.md) | cross-boundary slice | Stable API/contract design | FE/BE split |
+| [`devrites-audit simplify`](../pack/.claude/skills/devrites-audit/SKILL.md) | `/rite-polish` Phase 1 | Chesterton's Fence, behavior-preserving simplification | dispatches `devrites-simplifier-reviewer` |
+| [`devrites-audit security`](../pack/.claude/skills/devrites-audit/SKILL.md) | input/auth/data/integration in scope | OWASP Top 10, three-tier boundary | dispatches `devrites-security-auditor` |
+| [`devrites-audit perf`](../pack/.claude/skills/devrites-audit/SKILL.md) | perf relevant or regression risk | Measure-first, CWV targets | dispatches `devrites-performance-reviewer` |
+| [`reference/parallel-dispatch.md`](../pack/.claude/skills/rite-seal/reference/parallel-dispatch.md) (sibling in `rite-review/reference/`) | loaded inline by `/rite-seal` and `/rite-review` | Reference doc — dispatch shape + reconciliation rules for the parallel reviewer fan-out via the `Task` tool | not a skill — a reference file |
+
+## Agents (`.claude/agents/devrites-*`, fresh-context subagents)
+
+Ten **read-only reviewers** plus one **write-capable** executor (`devrites-slice-wright`).
+
+| Agent | Spawned by | Purpose |
+|---|---|---|
+| [`devrites-slice-wright`](../pack/.claude/agents/devrites-slice-wright.md) | `/rite-build` (the build core) | **Write-capable** — turn one slice contract into clean, idiomatic, proven code (orient → TDD → verify, anti-slop); returns a structured artifact, writes no bookkeeping |
+| [`devrites-strategy-reviewer`](../pack/.claude/agents/devrites-strategy-reviewer.md) | `/rite-temper` (pre-plan) | Spec-vs-rubric strategic review (ambition / scope / premise / pre-mortem / YAGNI / testability / irreversibility / cross-cutting / convention); read-only; **not** part of the seal fan-out |
+| [`devrites-plan-reviewer`](../pack/.claude/agents/devrites-plan-reviewer.md) | `/rite-vet` (pre-build) | Plan-vs-rubric engineering review (architecture / scope-reuse / plan code-quality / test-coverage design / performance / reversibility / failure-mode coverage), confidence-banded with a quote-the-source verification gate; read-only; **not** part of the seal fan-out |
+| [`devrites-spec-reviewer`](../pack/.claude/agents/devrites-spec-reviewer.md) | `/rite-review` Spec axis; `/rite-seal` | Does the diff implement the spec? Missing/partial/wrong criteria; scope creep |
+| [`devrites-code-reviewer`](../pack/.claude/agents/devrites-code-reviewer.md) | `/rite-review` Standards axis; `/rite-seal` | Correctness / readability / architecture / maintainability |
+| [`devrites-test-analyst`](../pack/.claude/agents/devrites-test-analyst.md) | `/rite-seal` | Do the tests actually prove the acceptance criteria? |
+| [`devrites-frontend-reviewer`](../pack/.claude/agents/devrites-frontend-reviewer.md) | `/rite-seal` on UI features | UX, a11y, responsive, design-system, anti-AI-slop |
+| [`devrites-security-auditor`](../pack/.claude/agents/devrites-security-auditor.md) | `/rite-seal` when input/auth/data in scope | OWASP Top 10, trust boundary, secrets, deps |
+| [`devrites-performance-reviewer`](../pack/.claude/agents/devrites-performance-reviewer.md) | `/rite-seal` when perf relevant | N+1s, hot paths, payload size |
+| [`devrites-doubt-reviewer`](../pack/.claude/agents/devrites-doubt-reviewer.md) | `devrites-doubt` loop | Adversarial check of a single claim/decision |
+| [`devrites-simplifier-reviewer`](../pack/.claude/agents/devrites-simplifier-reviewer.md) | `devrites-audit simplify` | Independent simplification judgment |
+
+## Engineering rules (`pack/.claude/rules/`)
+
+Progressive-disclosure rules. Each `rite-*` skill Reads `core.md` as its
+first step (step 0); the rest are referenced on demand. Full index in
+[`pack/.claude/rules/README.md`](../pack/.claude/rules/README.md).
+
+- `core.md` (always-on) — operating rules + universal anti-rationalizations + 1-line craft disciplines + persistence-before-stopping summary.
+- `coding-style.md` · `error-handling.md` · `testing.md` · `code-review.md` · `security.md` · `performance.md` · `patterns.md` · `git-workflow.md` · `hooks.md` · `documentation.md` · `development-workflow.md` · `agents.md` · `context-hygiene.md` · `afk-hitl.md`
+- `anti-patterns.md` — pack-wide rationalizations + red flags. Loaded by each per-phase `rite-*/reference/anti-patterns.md`; can be loaded directly for cross-phase reluctance.
+
+## Trigger conditions (auto-selection)
+
+| Trigger | Routes to |
+|---|---|
+| Frontend/UI detected (TSX/JSX/Vue/Svelte/Astro/Angular/ERB, CSS/Tailwind/tokens, components/forms/states) | `devrites-ux-shape` in spec (writes `design-brief.md` — direction, **calibration** density/motion, states), `devrites-frontend-craft` in build (builds to it; extracts to a supplied Figma/image target), `devrites-browser-proof` in prove, `rite-polish` Phase 3 + 4 (`reference/ui.md`) in polish, UX/a11y axes at review/seal, optional **design-memory** rollup → project `DESIGN.md` at ship |
+| Uncertain library / framework behavior | `devrites-source-driven` |
+| Non-trivial decision (boundary, data model, auth, public API, migration, "this scales/safe") | `devrites-doubt` (+ `devrites-doubt-reviewer`) |
+| User input / auth / storage / external integration / secrets / permissions | `devrites-audit security` (+ `devrites-security-auditor`) |
+| Performance requirement or suspected regression | `devrites-audit perf` (+ `devrites-performance-reviewer`) |
+| Failing tests / build / runtime / browser checks | `devrites-debug-recovery` |
+| Slice crosses a boundary or defines a public interface | `devrites-api-interface` |
+| Unfamiliar area, "zoom out", "map this" | `/rite-zoom-out` (uses codegraph/graphify) |
+| Every defined plan before build; "engineering review", "review the architecture", "lock in the plan", "test coverage check" | `/rite-vet` (+ `devrites-plan-reviewer`; depth scales to stakes, never skipped; always in `/rite-autocomplete`) |
+
+## Code-graph integration
+
+Skills that prefer a code-intelligence index (`codegraph_*` / `graphify-out/`)
+when available, falling back to file reads otherwise:
+
+- `/rite-spec`, `/rite-define`, `/rite-plan` — placement / impact / callers during investigation
+- `/rite-vet` — reuse-vs-rebuild, blast-radius, and placement-realism checks during the scope challenge + architecture axis
+- `/rite-build` — `touched-files.md` + impact when loading slice context
+- `/rite-review` — blast-radius checks on the diff
+- `/rite-seal` — final blast-radius check
+- `/devrites-doubt` — "where does this claim reach" via `codegraph_impact` / `codegraph_callers`
+- `/rite-zoom-out` — `codegraph_context` + `codegraph_explore`
+- `/devrites-frontend-craft` — component / token lookups
+
+## Interactions (typical flow)
+
+See [`flow.md`](flow.md) for the Mermaid diagrams. The text path:
+
+```
+/rite-spec → /rite-define → /rite-build ×N → /rite-prove → /rite-polish → /rite-review → /rite-seal → /rite-ship
+   │            │                │  ▲              │                          │             (decide)   (execute+close)
+   │            │                │  └ Spec Drift Guard → /rite-plan repair ────┘
+   │            │                └ devrites-frontend-craft / source-driven / doubt
+   └ (no workspace) → summary    devrites-* internal skills fire on triggers above
+
+/rite-autocomplete drives the entire sequence above unattended (best option per soft gate; --ship auto-confirms ship).
+```
+
+- Every phase **reads the active workspace first**; if none, it stops and tells
+  the user to run `/rite-spec <feature>`.
+- **Spec Drift Guard** lives in build/prove/polish/review/seal: on drift,
+  stop, record in `drift.md`, classify, ask the user if product behavior
+  changes, then `/rite-plan repair` before resuming.
+- `/rite-seal` fans out to `.claude/agents/devrites-*` reviewers **in
+  parallel** for independent, fresh-context judgment, then writes the GO /
+  NO-GO verdict — it runs no git. On GO it hands off to `/rite-ship`, which
+  renders type-`GO`, runs the irreversible git ladder, and closes the task by
+  archiving the workspace to `.devrites/archive/<slug>/` and clearing
+  `.devrites/ACTIVE`.

package/docs/flow.md

@@ -0,0 +1,360 @@
+# DevRites — flow diagrams
+
+Visual reference for how the skills, agents, and rules fit together. GitHub
+renders Mermaid natively — open this file on the repo to see the graphs.
+
+For the full per-skill table, see [`command-map.md`](command-map.md). For the
+"why" behind each piece, see [`architecture.md`](architecture.md).
+
+## 1. Feature lifecycle
+
+The happy path. Every arrow assumes the readiness gate of the previous phase
+passed; failures route through `/rite-plan repair` or `devrites-debug-recovery`.
+HITL slices pause before code is written; `/rite-resolve` is the resume verb.
+
+```mermaid
+flowchart LR
+    Start([user has an idea]) --> Spec[/rite-spec/]
+    Spec -.->|UI detected| Shape[devrites-ux-shape<br/>plan UX/UI → design-brief.md]
+    Shape -.->|brief confirmed| Spec
+    Spec -->|spec.md ready| Define[/rite-define/]
+    Define -->|plan.md + tasks.md<br/>each slice tagged AFK/HITL| Build[/rite-build/]
+    Build -->|one slice done<br/>+ evidence| Build
+    Build -->|HITL gate fires| Await{{Awaiting human<br/>state.md + questions.md}}
+    Await -->|"/rite-resolve &lt;qid&gt; &lt;answer&gt;"| Build
+    Build -->|all slices built| Prove[/rite-prove/]
+    Prove -->|evidence captured| Polish[/rite-polish/]
+    Polish -->|polish-report.md| Review[/rite-review/]
+    Review -->|review.md<br/>Critical == 0| Seal[/rite-seal/]
+    Seal -->|GO| Ship2[/rite-ship/]
+    Ship2 -->|type-GO| Shipped([commit · push · tag · archive])
+    Seal -->|NO-GO| Repair[/rite-plan repair/]
+    Repair --> Build
+
+    Build -.->|Spec Drift Guard| Repair
+    Prove -.->|drift / failure| Repair
+    Polish -.->|drift| Repair
+    Review -.->|drift| Repair
+
+    classDef phase fill:#1f2937,stroke:#60a5fa,stroke-width:1px,color:#f9fafb
+    classDef done fill:#064e3b,stroke:#34d399,color:#ecfdf5
+    classDef repair fill:#4c1d95,stroke:#a78bfa,color:#f5f3ff
+    classDef gate fill:#4c1d95,stroke:#a78bfa,color:#f5f3ff
+    classDef internal fill:#0f172a,stroke:#9ca3af,color:#f9fafb
+    class Spec,Define,Build,Prove,Polish,Review,Seal,Ship2 phase
+    class Shipped done
+    class Repair repair
+    class Await gate
+    class Shape internal
+```
+
+## 2. `/rite-polish` orchestrator
+
+`/rite-polish` is a thin dispatcher that always runs code polish and runs UI
+polish only when the diff touches UI files.
+
+```mermaid
+flowchart TD
+    P[/rite-polish/] -->|read diff + touched-files.md| D{UI<br/>touched?}
+    D -->|always| Code[reference/code.md<br/>Phase 1 + 2]
+    D -->|yes| UI[reference/ui.md<br/>Phase 3 + 4]
+    Code -->|appends to polish-report.md| Out([polish-report.md])
+    UI -->|appends to polish-report.md| Out
+    Code -.->|Phase 1| Simp[devrites-audit simplify]
+    Simp -.->|spawns| SR[devrites-simplifier-reviewer]
+
+    classDef orch fill:#1f2937,stroke:#60a5fa,color:#f9fafb
+    classDef sub fill:#312e81,stroke:#818cf8,color:#eef2ff
+    classDef agent fill:#7c2d12,stroke:#fb923c,color:#fff7ed
+    class P orch
+    class Code,UI,Simp sub
+    class SR agent
+```
+
+Mode tokens passed to `/rite-polish` (`bolder`, `quieter`, `distill`,
+`harden`, `normalize-only`) flow through to Phase 4 (`reference/ui.md`) as
+emphasis dials. `normalize-only` stops after Phase 3.
+
+## 3. `/rite-review` parallel axes
+
+Review runs Spec coverage and Standards compliance in parallel sub-agents so
+neither masks the other.
+
+```mermaid
+flowchart LR
+    R[/rite-review/] -->|spawn parallel<br/>via Task tool| S[devrites-spec-reviewer<br/>**Spec axis**]
+    R -->|spawn parallel<br/>via Task tool| C[devrites-code-reviewer<br/>**Standards axis**]
+    S -->|missing / partial / wrong /<br/>scope-creep findings| Combine
+    C -->|standards violations<br/>cite rule + file| Combine
+    R --> Sec[devrites-audit security]
+    R --> Perf[devrites-audit perf]
+    Sec -->|labelled findings| Combine
+    Perf -->|labelled findings| Combine
+    Combine([review.md<br/>Critical / Important / Suggestion / Nit / FYI])
+
+    classDef phase fill:#1f2937,stroke:#60a5fa,color:#f9fafb
+    classDef agent fill:#7c2d12,stroke:#fb923c,color:#fff7ed
+    classDef skill fill:#312e81,stroke:#818cf8,color:#eef2ff
+    class R phase
+    class S,C agent
+    class Sec,Perf skill
+```
+
+## 4. `/rite-seal` fan-out
+
+The seal fans out **all** relevant reviewers in parallel and reconciles their
+findings, then **decides** GO / NO-GO and stops. It no longer runs git — on GO
+it hands off to `/rite-ship`, which renders the type-GO prompt and runs the
+irreversible commit · push · tag · archive. The advisory `/20` score has been
+removed — the gate is severity + acceptance + drift.
+
+```mermaid
+flowchart TB
+    Seal[/rite-seal/] -->|read all artifacts| Walk[walk acceptance<br/>criteria one by one]
+    Walk -->|spawn in parallel| SpecRev[devrites-spec-reviewer]
+    Walk -->|spawn in parallel| CodeRev[devrites-code-reviewer]
+    Walk -->|spawn in parallel| TestRev[devrites-test-analyst]
+    Walk -.->|UI only| FERev[devrites-frontend-reviewer]
+    Walk -.->|input/auth/data| SecRev[devrites-security-auditor]
+    Walk -.->|perf relevant| PerfRev[devrites-performance-reviewer]
+    SpecRev --> Gate
+    CodeRev --> Gate
+    TestRev --> Gate
+    FERev --> Gate
+    SecRev --> Gate
+    PerfRev --> Gate
+    Gate{Critical == 0?<br/>Acceptance proven?<br/>Drift resolved?}
+    Gate -->|yes + Important == 0| Go
+    Gate -->|yes + Important > 0| YN[render interactive<br/>y/N prompt]
+    Gate -->|no| NoGo[NO-GO]
+    YN -->|y| Go
+    YN -->|N| NoGo
+    Go[GO: write seal.md<br/>Next step: /rite-ship] -->|hand off, type-GO + git live in ship| Ship([/rite-ship/])
+
+    classDef phase fill:#1f2937,stroke:#60a5fa,color:#f9fafb
+    classDef agent fill:#7c2d12,stroke:#fb923c,color:#fff7ed
+    classDef gate fill:#4c1d95,stroke:#a78bfa,color:#f5f3ff
+    classDef ship fill:#064e3b,stroke:#34d399,color:#ecfdf5
+    classDef stop fill:#7f1d1d,stroke:#f87171,color:#fee2e2
+    class Seal,Walk phase
+    class SpecRev,CodeRev,TestRev,FERev,SecRev,PerfRev agent
+    class Gate,YN gate
+    class Go,Ship ship
+    class NoGo stop
+```
+
+## 5. `devrites-debug-recovery` six-phase loop
+
+Failure recovery — the loop construction in Phase 1 is the load-bearing piece.
+
+```mermaid
+flowchart LR
+    F([failing test /<br/>build / runtime]) --> L1[Phase 1<br/>Build the loop]
+    L1 -->|fast deterministic signal| R[Phase 2<br/>Reproduce]
+    R -->|exact error text| H[Phase 3<br/>Ranked hypotheses 3-5]
+    H -->|show user before testing| I[Phase 4<br/>Instrument]
+    I -->|change one variable| Fix[Phase 5<br/>Fix + regression test]
+    Fix --> C[Phase 6<br/>Cleanup + classify]
+    L1 -.->|can't build loop| Ask([STOP — ask user])
+
+    classDef phase fill:#1f2937,stroke:#60a5fa,color:#f9fafb
+    classDef stop fill:#7f1d1d,stroke:#f87171,color:#fee2e2
+    class L1,R,H,I,Fix,C phase
+    class Ask stop
+```
+
+Each phase's detail lives in a separate reference file under
+`pack/.claude/skills/devrites-debug-recovery/reference/` so the SKILL.md body
+stays small.
+
+## 6. Engineering-rules carrier
+
+Each `rite-*` skill Reads `.claude/rules/core.md` (the always-on subset) as
+its first step (step 0); the other rule files load on demand. Per-phase
+skills pull additional rule files via plain `Read` as their workflow
+demands. No carrier skill, no session-start autoload.
+
+```mermaid
+flowchart TD
+    R[rite-* skill<br/>step 0] -->|always-on| Core[.claude/rules/core.md]
+    R -->|on demand index| Idx[(.claude/rules/README.md<br/>15 specialist rule files)]
+    Idx --> CS[coding-style.md]
+    Idx --> EH[error-handling.md]
+    Idx --> T[testing.md]
+    Idx --> CR[code-review.md]
+    Idx --> S[security.md]
+    Idx --> P[performance.md]
+    Idx --> Pat[patterns.md]
+    Idx --> Gw[git-workflow.md]
+    Idx --> Hk[hooks.md]
+    Idx --> Doc[documentation.md]
+    Idx --> DWf[development-workflow.md]
+    Idx --> Ag[agents.md]
+    Idx --> CH[context-hygiene.md]
+    Idx --> Afk[afk-hitl.md]
+    Idx --> AP[anti-patterns.md]
+
+    Build[/rite-build/] -.->|pulls| CS
+    Build -.->|pulls| EH
+    Build -.->|pulls| T
+    Polish[/rite-polish/] -.->|pulls| CS
+    Polish -.->|pulls| Pat
+    Review[/rite-review/] -.->|pulls| CR
+    Review -.->|pulls| S
+    Review -.->|pulls| P
+    Seal[/rite-seal/] -.->|pulls| Ag
+    Seal -.->|pulls| CR
+    Ship[/rite-ship/] -.->|pulls| Gw
+
+    classDef carrier fill:#312e81,stroke:#818cf8,color:#eef2ff
+    classDef rule fill:#1f2937,stroke:#9ca3af,color:#f9fafb
+    classDef phase fill:#064e3b,stroke:#34d399,color:#ecfdf5
+    class R carrier
+    class Core,CS,EH,T,CR,S,P,Pat,Gw,Hk,Doc,DWf,Ag,CH,Afk,AP rule
+    class Build,Polish,Review,Seal,Ship phase
+```
+
+## 7. Workspace state model
+
+`.devrites/work/<feature-slug>/` is the durable memory each phase reads
+before doing anything. **Every** rite-* skill reads the workspace first; if
+no `ACTIVE` is set, it tells the user to run `/rite-spec`. The optional
+`.devrites/AFK` sentinel sits beside `ACTIVE` and toggles the session-level
+run mode for all skills.
+
+```mermaid
+erDiagram
+    ACTIVE ||--o| WORKSPACE : points-to
+    AFK_SENTINEL }|..|| RUN_MODE : "presence is authoritative — skills re-read at decision time"
+    WORKSPACE ||--|| state : has
+    WORKSPACE ||--|| brief : has
+    WORKSPACE ||--|| spec : has
+    WORKSPACE ||--o| strategy : "has (optional — from /rite-temper)"
+    WORKSPACE ||--|| plan : "has (from /rite-define)"
+    WORKSPACE ||--|| tasks : "has — slices tagged Mode + Gate"
+    WORKSPACE ||--o| eng-review : "has (from /rite-vet — every plan, light or full)"
+    WORKSPACE ||--o| test-plan : "has (from /rite-vet; build + prove read it)"
+    WORKSPACE ||--o{ references : "has (design refs)"
+    WORKSPACE ||--o| design-brief : "has (UI features — from /rite-spec via devrites-ux-shape; the build target)"
+    WORKSPACE ||--|| questions : "has — qid, gate, status (open/answered/dropped)"
+    WORKSPACE ||--|| decisions : has
+    WORKSPACE ||--|| assumptions : has
+    WORKSPACE ||--|| drift : has
+    WORKSPACE ||--|| touched-files : "has (from /rite-build)"
+    WORKSPACE ||--|| evidence : "has (from /rite-prove)"
+    WORKSPACE ||--o| browser-evidence : "has (UI features)"
+    WORKSPACE ||--o| polish-report : "has (from /rite-polish)"
+    WORKSPACE ||--o| review : "has (from /rite-review)"
+    WORKSPACE ||--o| seal : "has (from /rite-seal)"
+    WORKSPACE ||--o| ship : "has (from /rite-ship; archived on close)"
+
+    ACTIVE {
+        string slug "names the current workspace"
+    }
+    AFK_SENTINEL {
+        bool present "presence = AFK active"
+        int max_slices "read-only initial budget — copied to state.md once"
+        string notify "optional shell command on pause"
+        list allow_gates "gate severities AFK may auto-handle"
+    }
+    WORKSPACE {
+        string slug PK ".devrites/work/<slug>/"
+    }
+    state {
+        string phase "spec | plan | build | prove | polish | review | seal | ship | done"
+        string status "running | awaiting_human | blocked | done"
+        string active_slice "N — name"
+        int afk_slices_remaining "from .devrites/AFK max_slices on first AFK build"
+        block awaiting_human "qid, gate, question, proposed, raised_at (only when paused)"
+    }
+    questions {
+        string qid PK "q-YYYY-MM-DD-NNN"
+        string status "open | answered | dropped"
+        string gate "advisory | validating | blocking | escalating"
+    }
+```
+
+The exact list of files per workspace and what each holds is in
+[`usage.md`](usage.md#the-workspace). The full pause/resume contract is in
+[`pack/.claude/rules/afk-hitl.md`](../pack/.claude/rules/afk-hitl.md).
+
+## 8. Public vs internal namespace
+
+The `devrites-` prefix is collision-avoidance against bundled Claude Code
+skills (`prototype`, `handoff`, `triage`, `diagnose`). Visibility is the
+`user-invocable:` flag, not the prefix.
+
+```mermaid
+flowchart TB
+    subgraph Public["Public (user-invocable: true) — 19 skills"]
+        direction TB
+        R1[/rite/]
+        R2[/rite-spec/]
+        RT[/rite-temper/]
+        R3[/rite-define/]
+        RV[/rite-vet/]
+        R4[/rite-plan/]
+        R5[/rite-build/]
+        R6[/rite-prove/]
+        R7[/rite-polish/]
+        R8[/rite-review/]
+        R9[/rite-seal/]
+        R12[/rite-ship/]
+        R13[/rite-autocomplete/]
+        R10[/rite-status/]
+        R11[/rite-resolve/]
+        IPT[/rite-pressure-test/]
+        D1[/rite-zoom-out/]
+        D2[/rite-prototype/]
+        D3[/rite-handoff/]
+    end
+    subgraph Internal["Internal (user-invocable: false) — 9 skills, model-invoked"]
+        direction TB
+        I1[devrites-api-interface]
+        I2[devrites-audit<br/>security · perf · simplify]
+        I3[devrites-browser-proof]
+        I4[devrites-debug-recovery]
+        I5[devrites-doubt]
+        I6[devrites-frontend-craft]
+        I7[devrites-interview]
+        I8[devrites-source-driven]
+        I9[devrites-ux-shape]
+    end
+
+    classDef pub fill:#064e3b,stroke:#34d399,color:#ecfdf5
+    classDef int fill:#1f2937,stroke:#9ca3af,color:#f9fafb
+    class R1,R2,RT,R3,RV,R4,R5,R6,R7,R8,R9,R12,R13,R10,R11,IPT,D1,D2,D3 pub
+    class I1,I2,I3,I4,I5,I6,I7,I8,I9 int
+```
+
+## 9. AFK & HITL state machine
+
+The pause/resume primitive for HITL gates and the AFK loop discipline. The
+gate firing on `/rite-build` is the only writer of `Awaiting human`;
+`/rite-resolve` is the only canonical clearer.
+
+```mermaid
+stateDiagram-v2
+    [*] --> running: /rite-build starts
+    running --> running: AFK slice + advisory finding<br/>(log to questions.md, proceed)
+    running --> awaiting_human: HITL gate fires<br/>(blocking / escalating / out-of-gate)
+    running --> awaiting_human: Fail-on-red<br/>(tests/types/lint)
+    running --> awaiting_human: Irreversible risk<br/>(destructive · auth · public API)
+    awaiting_human --> running: /rite-resolve qid "<answer>"
+    awaiting_human --> running: /rite-resolve --drop qid
+    awaiting_human --> blocked: /rite-plan repair (scope change)
+    blocked --> running: plan repaired
+    running --> done: sealed GO + /rite-ship<br/>(type-GO → commit · push · tag · archive)
+    done --> [*]
+
+    note right of awaiting_human
+        state.md: Status: awaiting_human
+        state.md: Awaiting human block
+        questions.md: gate, qid, proposed, raised_at
+        notify hook fired (if .devrites/AFK has one)
+    end note
+```
+
+`AFK` mode (`.devrites/AFK` present) widens which transitions stay in
+`running` via `allow_gates` — but `blocking`, `escalating`, fail-on-red, and
+the irreversible-risk list always transition to `awaiting_human` regardless.

package/docs/release.md

@@ -0,0 +1,29 @@
+# Release pipeline
+
+Releases are **fully automated** via [semantic-release](https://semantic-release.gitbook.io/): every push to `main` is analyzed; if the merged commits carry a `feat:`, `fix:`, `perf:`, `refactor:`, `build:`, `docs(README):` (or a `BREAKING CHANGE:` footer) the `.github/workflows/release.yml` job determines the next SemVer version and:
+
+1. Runs `scripts/validate.sh` + install / uninstall smoke tests.
+2. Syncs the new version into `package.json`, `.claude-plugin/plugin.json`, and `.claude-plugin/marketplace.json` (`scripts/sync-version.sh`).
+3. Builds a `dist/devrites-v<version>.tar.gz` release artifact via `scripts/build-release-tarball.sh` — the extractable bundle end-users get if they don't install via the plugin marketplace.
+4. Regenerates `CHANGELOG.md` from the commits.
+5. Commits the version bump + changelog as `chore(release): <version> [skip ci]`, creates a git tag `v<version>`, and publishes a GitHub Release with the tarball attached.
+
+Local dry-run: `npm run release:dry` (shows the version bump + draft notes without publishing). The release job is gated by passing CI — a broken `main` won't ship.
+
+## Authoring commits that trigger releases
+
+| Commit prefix | Bump |
+|---|---|
+| `feat:` | **minor** (`0.1.0` → `0.2.0`) |
+| `fix:` / `perf:` / `refactor:` / `build:` / `docs(README):` | **patch** (`0.1.0` → `0.1.1`) |
+| Any type with `BREAKING CHANGE:` footer or `!` after type (e.g. `feat!:`) | **major** (`0.1.0` → `1.0.0`) |
+| `chore:` / `ci:` / `test:` / `docs:` (non-README) | no release |
+| Any scope `(no-release)` (e.g. `feat(no-release): …`) | no release |
+
+Husky + commitlint reject non-conventional messages at commit time, so you can't accidentally bypass the rules.
+
+## Dependency updates
+
+Dependabot watches the `npm` and `github-actions` ecosystems and opens a **weekly grouped PR** with all patch + minor bumps (see [`.github/dependabot.yml`](../.github/dependabot.yml)). The [`dependabot-auto-merge.yml`](../.github/workflows/dependabot-auto-merge.yml) workflow auto-approves + enables auto-merge (squash) on those PRs so they land the instant CI is green — no manual click. Major-version bumps stay open with a `needs-review` label so a human can scan the changelog before merging.
+
+> GitHub does not allow Dependabot to push directly to `main` — a PR is always opened. Auto-merge is the closest equivalent. Required CI checks still gate the merge.