devrites 1.19.0

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

@@ -0,0 +1,95 @@
+---
+name: rite-handoff
+description: Compact the current chat into a handoff doc a fresh agent can pick up cold — syncs chat-only context into the canonical `.devrites/` files, references artifacts by path. Use when the user says "handoff", "prep for tomorrow", "I'm leaving for a while", "summarize for the next agent". Not for routine `/clear` between phases.
+user-invocable: true
+argument-hint: "[what the next session will focus on]"
+---
+
+# /rite-handoff — chat-only context, into a fresh-agent doc
+
+DevRites' workspace `.devrites/work/<slug>/` already captures everything that *should*
+persist (spec, plan, tasks, decisions, evidence, drift, review). This skill captures
+what the **chat** is holding that is **not** in the workspace, so a fresh agent — or
+the same user after `/clear` — can pick the work up without re-reading the transcript.
+
+Read `.claude/rules/core.md` first — its "Persistence before stopping" discipline is
+exactly what this skill executes. The other rule files load on demand.
+
+Then **run the shared orientation preamble** — it prints `state.md`, the artifacts present,
+the run mode (HITL/AFK), and the open-question tally by gate, so you orient deterministically
+instead of re-deriving state from raw Markdown:
+```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)"
+```
+
+## Where to write
+
+- **Active feature exists** → `.devrites/work/<slug>/handoff.md` (overwrites the previous
+  handoff; the workspace is the canonical home for this slug).
+- **No active feature** → OS temp dir (`$TMPDIR` / `/tmp` / `%TEMP%`) as
+  `rite-handoff-<ISO-timestamp>.md`. Print the absolute path after writing.
+
+## Before you write — sync, don't duplicate
+
+For each of these, write the content into its **canonical home** first, then merely
+*note* in the handoff that the sync happened:
+
+- **Open mid-flight question** → append to `questions.md` (with best-guess attached if
+  possible).
+- **Decision discussed but not yet recorded** → append to `decisions.md` with the *why*,
+  not just the *what*.
+- **Assumption** about behaviour / API / user intent → append to `assumptions.md`.
+- **Drift event raised but not fully resolved** → update `drift.md` with the current
+  resolution status (open / asked-user / repaired).
+- **Files modified in chat not yet in `touched-files.md`** → append to
+  `touched-files.md`.
+
+The handoff doc itself then says "synced N entries into decisions.md", not the entries
+themselves. The workspace is the canonical store; the handoff is the chat-only delta.
+
+## What to include in the handoff
+
+1. **Suggested next action.** ONE command, not three options. If the active feature is
+   mid-phase, name the next `rite-*` command. If a question blocks progress, point at
+   it. If the user passed `[what the next session will focus on]`, tailor this section
+   to the named focus. Where you were mid-thought, **quote the most recent next-step
+   verbatim** from the chat (the exact sentence describing what to do next) so no nuance
+   is lost to paraphrase.
+2. **What just happened in this chat** (3–5 bullets). Distil — do not transcribe.
+3. **External references** that exist only in chat: URLs, Figma links, screenshot paths,
+   video timestamps the user pasted. List as references; do not embed.
+4. **Live assumptions the agent is acting on** that the workspace doesn't reflect yet
+   (after the sync above, this section should be near-empty — flag anything that
+   remains).
+5. **How to resume** — fixed boilerplate (see template below).
+
+## What NOT to include
+
+- Anything already in `spec.md`, `plan.md`, `tasks.md`, `state.md`, `decisions.md`,
+  `evidence.md`, `review.md` — link by path instead.
+- `git diff` output — the next agent runs `git diff` themselves.
+- The full conversation transcript — distil.
+- Secrets (API keys, tokens, PII, credentials). Redact aggressively.
+- **New ideas the user didn't confirm.** A handoff records what *happened* and what's *next* —
+  not fresh suggestions, scope the user didn't agree to, or a redesign you thought of. Capture the
+  state, not your opinions about it.
+
+## Output template
+
+Loaded on demand from [`reference/handoff-template.md`](reference/handoff-template.md).
+Fill in each section + write to `.devrites/work/<slug>/handoff.md` (or to a temp file
+when no active feature).
+
+After writing, **print the absolute path** of the handoff file so the user (or the next
+agent) can open it without searching.
+
+## Session hygiene
+Close with the one-line hygiene advisory + the single resume command — this skill *is* the
+pre-`/clear` bridge, so it's where the advisory matters most (`context-hygiene.md`):
+```
+↻ Hygiene: /clear — handoff written; all chat-only context is now on disk, safe to /clear
+or close the session. Resume next session with: <the single next command from state.md>
+```

package/pack/.claude/skills/rite-handoff/reference/handoff-template.md

@@ -0,0 +1,34 @@
+# Handoff doc template
+
+Loaded on demand by `/rite-handoff`. Write the filled-in template to
+`.devrites/work/<slug>/handoff.md` (or to a `$TMPDIR` file when no active feature).
+
+```
+# Handoff — <feature slug | "no active feature"> — <ISO date>
+
+## Suggested next action
+<one command, no options>
+
+## What just happened (this chat)
+- ...
+- ...
+
+## External references (chat-only)
+- <URL / Figma / screenshot path / video timestamp>
+
+## Live assumptions (not yet in assumptions.md)
+- ...   (this section should be near-empty after the sync step)
+
+## Synced this turn
+- decisions.md: <N entries appended>
+- questions.md: <N appended>
+- assumptions.md: <N appended>
+- drift.md: <updated? yes/no>
+- touched-files.md: <N appended>
+
+## How to resume
+1. Read this file.
+2. Read `.devrites/work/<slug>/state.md` for the workspace cursor.
+3. Run `/rite-status` for the current phase / next action / open drift.
+4. Continue with the suggested next action above.
+```

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

@@ -0,0 +1,82 @@
+---
+name: rite-learn
+description: Review the auto-captured learning ledger and promote recurring lessons to project rules — the human-gated half of the cross-feature learning loop. Capture is automatic (`/rite-seal` appends dismissed-finding classes + dead-ends to `.devrites/learnings.md` on every GO; the review skills load it before a fan-out), so the system learns without a command; this skill mines that ledger across features and decides which recurring lessons graduate into a rule (propose, don't impose). Use when the user says "what have we learned", "rite learn", "harvest lessons", "promote our learnings", or after several features ship. Not for the install (`/rite-doctor`), feature status (`/rite-status`), onboarding (`/rite-adopt`), or a diff review (`/rite-review`).
+argument-hint: "[--mine | \"<lesson to record>\"]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# /rite-learn — the cross-feature learning loop
+
+Recurring corrections, dismissed review findings, and dead-ends are durable signal. **Capture is
+automatic** — `/rite-seal` appends them to `.devrites/learnings.md` on every GO (step 9a), and the
+review skills load that ledger **before** a fan-out, so a dismissed-finding class stops being
+re-flagged without anyone running a command. The system learns as it ships.
+
+`/rite-learn` is the periodic **review + promote** pass on that auto-populated ledger: cluster the
+signal across features and decide which recurring lessons graduate into a project rule. **Propose,
+never impose** — promotion is the human's call, which is why it stays a deliberate command rather
+than firing on its own.
+
+Read-mostly. It reads the auto-populated ledger + the archive; it writes only `.devrites/learnings.md`
+(consolidation, via `learnings.sh`) and drafts proposed rule/ledger edits for the user to confirm —
+it never edits source or rule files on its own.
+
+## Modes
+
+- `/rite-learn` or `/rite-learn --mine` — **mine + propose** (the default).
+- `/rite-learn "<lesson>"` — **record one lesson** directly to the ledger and stop.
+
+## Workflow (mine + propose)
+
+1. **Gather the signal.** Start from the **auto-populated ledger** `.devrites/learnings.md` (seal
+   appends to it on every GO — step 9a), then run `learnings.sh mine` over the archive (resolve via
+   the standard 3-path snippet; it clusters repeated finding / decision / drift phrases across shipped
+   features) to surface cross-feature patterns the per-feature entries don't show on their own:
+   ```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" mine || echo "(learnings.sh unavailable — scan .devrites/archive/*/{decisions,drift,review}.md by hand)"
+   ```
+2. **Cluster + name.** Group the recurring corrections into candidate lessons. A candidate needs
+   **≥2 occurrences across distinct features** — one-offs are noise, not a pattern. Name the
+   pattern in one specific sentence (the specificity rule from `prose-style.md` applies: a lesson
+   you could swap onto any project says nothing).
+3. **Classify each candidate** into its durable home:
+   - **project rule** — a craft/standard that belongs in a `.claude/rules/*` file or `CLAUDE.md`.
+   - **conventions-ledger entry** — a proven project idiom for `.devrites/conventions.md`.
+   - **dismissed-finding class** — a pattern reviewers keep flagging that is *intentional here*;
+     recording it stops the recurring false positive (`learnings.md`, loaded pre-fan-out).
+   - **drop** — not durable; let it go.
+4. **Propose, don't impose.** Present the candidates with their evidence (which features, how many
+   times, the proposed home) via `AskUserQuestion` — the human picks which to promote. Never
+   promote a lesson to a rule silently; an unproven "lesson" hardened into a rule is its own slop.
+5. **Record the accepted.** For each the user accepts, append it with `learnings.sh add <slug>
+   "<lesson>" <tag>` (`tag` ∈ `rule | convention | dismiss`). If the user approves a **rule** or
+   **ledger** promotion, draft the exact edit and let the user confirm it through the normal flow
+   — `/rite-learn` writes the ledger, not the rule files. Then `touch .devrites/.learnings-reviewed`
+   so the SessionStart learnings nudge snoozes until new signal accumulates.
+
+## How the ledger is used
+
+The review skills (`/rite-review`, `/rite-seal`) read `.devrites/learnings.md` before they fan
+out: a **dismissed-finding class** suppresses the recurring false positive; a **proven
+convention** raises the bar. The ledger is an **untrusted prior** — a fresh observation of the
+live code always overrides a ledger entry (see `.claude/rules/security.md`). Confidence in a
+recorded lesson never raises its authority.
+
+## Gotchas
+- Evidence first: a lesson without ≥2 real occurrences is speculation. Cite the features.
+- Don't pad the ledger. Five real lessons that change behaviour beat thirty rubber-stamped rows.
+- The ledger records *what was learned*; it does not re-open shipped features or edit their archives.
+
+## Output
+```
+Mined: <n> features · <n> recurring patterns
+Candidates: <n> (rule: a · convention: b · dismiss: c · dropped: d)
+Promoted: <n> → .devrites/learnings.md  (+ <n> rule/ledger edits drafted for your confirm)
+
+Session hygiene: /clear (recommended) — the ledger is on disk; the proposals are listed above.
+Resume next session with: <the single next command, e.g. the drafted rule edit, or /rite-status>
+```

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

@@ -0,0 +1,82 @@
+---
+name: rite-plan
+description: Reshape an active plan — decompose / reslice / repair / reorder / split FE-BE / unblock / course-correct — without changing product behavior unless asked. Use when the user says "replan", "reslice", "repair the plan", "drift", "unblock", "change of plan", "we're pivoting", or `/rite-build` flags Spec Drift. Not for the initial plan (use `/rite-define`).
+argument-hint: "[mode: decompose|reslice|repair|reorder|split|unblock|course-correct]"
+user-invocable: true
+---
+
+# /rite-plan — (re)plan an active feature
+
+Reshape the plan when reality and the plan disagree. **Read the active workspace
+first.** If `.devrites/ACTIVE` is empty or its workspace is missing, stop and tell the
+user to run `/rite-spec <feature>`.
+
+## Rules consulted (read on demand from `.claude/rules/`)
+Read `.claude/rules/core.md` first. Pull `development-workflow.md` via `Read` when
+reshaping slice cadence or DoD criteria.
+
+## Operating rules
+- Spec is living, not sacred — but never plan around a known-wrong assumption silently.
+- If a change alters product behavior, scope, architecture, data model, UX, security,
+  or migration risk → **ask the user first** (use the Spec Drift Guard question format).
+- Keep each slice small enough for one focused build → prove cycle.
+- **Slice count is derived, never dictated** — reslice when a slice fails the sizing rule
+  (multiple "and"s, can't build+prove in one cycle), not to hit a user-named tally. A
+  requested count is a hint at most; slice logically and explain if it differs. See
+  [`reference/slicing.md`](reference/slicing.md) ("How many slices?").
+- **Size by complexity, order by dependency.** A slice carries a `Complexity: N/5` score (from
+  `/rite-define`); a slice scoring **>3** is a reslice trigger unless its inline reason justifies
+  the irreducible complexity. Honor each slice's `depends_on:` — the next *buildable* slice is the
+  lowest pending one whose dependencies are all built (keeps one-slice-at-a-time correct, not parallel).
+
+## Workflow
+0. Read `.claude/rules/core.md` (operating rules) before reshaping anything.
+   Then **run the shared orientation preamble** — it prints `state.md`, the artifacts present,
+   the run mode (HITL/AFK), and the open-question tally by gate, so you orient deterministically
+   instead of re-deriving state from raw Markdown:
+   ```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)"
+   ```
+1. Read `spec.md`, `plan.md`, `tasks.md`, `state.md`, `drift.md`, and the current
+   `git diff` (if a repo). Read `decisions.md` and `assumptions.md`. If a code-intelligence
+   index is available — `codebase-memory-mcp` first, cross-checked with `codegraph`
+   (`.codegraph/` / `codegraph_*` tools) + `graphify` (`graphify-out/`), else standard methods
+   (LSP / `Read`/`Grep`/`Glob`); see `.claude/rules/tooling.md` —
+   prefer it for structural questions (what calls X, what would
+   changing Y break) over reading whole files, to keep planning context lean. For an external
+   dependency's current API surface, consult context7 if available.
+2. **Pick the mode** (`$ARGUMENTS` or infer):
+   - **decompose** — first/again break the feature into vertical slices.
+   - **reslice** — a slice is too large; split into thinner end-to-end slices.
+   - **repair** — a Spec Drift Guard event; fold the resolution into plan + tasks.
+   - **reorder** — fix the dependency order.
+   - **split** — separate backend/frontend contracts (see `devrites-api-interface`).
+   - **unblock** — a verification failed; re-route around the blocker.
+   - **course-correct** — a deliberate mid-build *pivot* (the user changed their mind), distinct
+     from accidental drift: classify the change, assess its impact across the remaining slices,
+     decide rollback vs forward-fix, and update `spec.md` + `plan.md` + `tasks.md` + `decisions.md`
+     atomically. An acceptance/behavior change still goes through the user first.
+   See [replan-and-repair](reference/replan-and-repair.md) for each mode's steps.
+3. Reason about dependencies — [dependency-graph](reference/dependency-graph.md).
+4. Re-slice using vertical-slice rules — [slicing](reference/slicing.md) and
+   [task-breakdown](reference/task-breakdown.md). Prefer thin, shippable, verifiable.
+5. Update `plan.md`, `tasks.md`, `state.md`, and append rationale to `decisions.md`.
+   If you stopped for drift, mark the `drift.md` entry resolved.
+6. If product behavior/acceptance criteria change, confirm with the user before writing.
+
+> **Mid-flight discipline.** When tempted to change product behavior without asking, absorb drift silently, or skip the user — see [`anti-patterns`](reference/anti-patterns.md). 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:
+```
+Re-planned <slug> — mode: <mode>
+Changes: <what moved/split/repaired>
+Slices now: N (next: slice <N — name>)
+Behavior change? <no | asked + answer>
+Next: /rite-build   (or /rite-prove if a built slice needs re-verification)
+↻ Hygiene: /clear if reshape was big or unwound a drift; keep session for small reorders. See rules/context-hygiene.md.
+```

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

@@ -0,0 +1,24 @@
+# rite-plan — anti-patterns
+
+Load this when standing a non-trivial re-plan decision, or when the agent
+feels reluctance toward asking the user before a behavior change.
+
+Pack-wide rationalizations + red flags: see [rules/anti-patterns.md](../../../rules/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "User didn't ask for a re-plan." | A Spec Drift Guard event *is* a re-plan trigger — ask is courtesy, the route is automatic. |
+| "I can fix the slice mid-build, no need to update tasks." | `tasks.md` is the contract `/rite-build` reads. A fix that isn't there isn't visible to the next phase. |
+| "Reordering slices is cosmetic." | Dependency order controls risk discovery; risk-first wins because it surfaces blockers early. |
+| "This drift is small enough to absorb silently." | Silent drift = unrecorded decision = future "why does this work?" debugging session. |
+| "I can change product behavior to make the plan fit." | Behavior change always asks the user first, no exceptions. |
+
+## Red Flags
+
+- About to change product behavior, acceptance, or scope without asking the user.
+- `drift.md` entry unresolved while planning the next slice.
+- A "mode" invented that isn't one of `decompose / reslice / repair / reorder / split / unblock`.
+- Slices reordered without updating dependency notes — order changed, rationale didn't.
+- Repairing a drift event by silently widening the spec rather than narrowing the plan.

package/pack/.claude/skills/rite-plan/reference/dependency-graph.md

@@ -0,0 +1,33 @@
+# Dependency graph
+
+Order slices by what must exist before what. Keep it in `plan.md` as plain text.
+
+## Build the graph
+1. For each slice, list its hard prerequisites (a model it queries, an endpoint it
+   calls, a component it composes).
+2. Draw edges prerequisite → dependent.
+3. Topologically sort. Independent slices can be built in any order (or noted as
+   parallelizable for the user).
+
+```
+Slice 1 (schema)  ──►  Slice 2 (write API)  ──►  Slice 3 (UI form)
+                  └─►  Slice 4 (read API)   ──►  Slice 5 (UI list)
+Slice 6 (config)  ── independent ──
+```
+
+## Within a tier: risk-first
+Among slices that are equally unblocked, do the **riskiest** first — the one most
+likely to invalidate the plan (new integration, uncertain library behavior, migration).
+Finding drift early is cheap; finding it at seal time is not.
+
+## Smells
+- A slice with many prerequisites → probably too big; reslice for a thinner cut that
+  stands alone.
+- A cycle (A needs B needs A) → the boundary is wrong; split the contract
+  (`devrites-api-interface`) so one side can land with a stub.
+- Everything depends on slice 1 → slice 1 is doing too much.
+
+## Cross-boundary edges
+Mark edges that cross a frontend/backend or service boundary. Those slices should
+define the contract first (so both sides can proceed) and trigger `devrites-doubt`
+before standing the interface.

package/pack/.claude/skills/rite-plan/reference/replan-and-repair.md

@@ -0,0 +1,42 @@
+# Re-plan & repair modes
+
+`/rite-plan` runs in one of these modes. Pick from `$ARGUMENTS` or infer from state.
+
+## decompose
+First (or fresh) breakdown into vertical slices. Use `task-breakdown.md` +
+`slicing.md`. Output: a populated `tasks.md` and an ordered `plan.md` graph.
+
+## reslice
+A slice proved too large (couldn't build+prove in one cycle, or its goal has multiple
+"and"s). Split into thinner end-to-end slices, preserving acceptance coverage — split
+**by the sizing rule, not to a target count**. Update `tasks.md`; renumber; fix
+dependency edges.
+
+## repair (after Spec Drift Guard)
+A drift event stopped the build. Steps:
+1. Read the `drift.md` entry and its classification.
+2. If the user answered a drift question, encode that decision in `decisions.md`.
+3. Update `spec.md` (only the affected sections) and `plan.md`/`tasks.md` to match
+   reality. Adjust acceptance criteria if they were wrong.
+4. Mark the `drift.md` entry **resolved** with the resolution + date.
+5. Resume at the corrected slice.
+Never repair by quietly deleting the inconvenient requirement — if behavior changes,
+that was a user question.
+
+## reorder
+Dependency order is wrong or suboptimal. Recompute the graph (`dependency-graph.md`),
+re-sort risk-first within tiers, update `plan.md`'s implementation order.
+
+## split (backend/frontend contract)
+A slice couples two sides too tightly. Define the contract first (shape, status codes,
+errors — `devrites-api-interface`), then split into a backend slice (can land with a
+stub consumer) and a frontend slice (can land against a mock/real contract).
+
+## unblock
+A `/rite-prove` failure can't be fixed inside the current slice. Capture the blocker in
+`state.md`, decide: route around it (reorder), shrink the slice (reslice), or escalate
+to the user (if it changes scope). Don't loop on the same failing approach.
+
+## Always
+Update `state.md` (phase, next step) and append a dated line to `decisions.md`
+explaining *why* the plan changed. Ask the user before any product-behavior change.

package/pack/.claude/skills/rite-plan/reference/slicing.md

@@ -0,0 +1,52 @@
+# Slicing
+
+DevRites builds in **thin vertical slices**: each slice cuts through every layer it
+needs (data → logic → API → UI) and leaves the system in a working, testable state.
+
+## Vertical, not horizontal
+Horizontal ("build all models, then all controllers, then all views") delays working
+software and hides integration risk until the end. Vertical delivers a usable path each
+slice:
+```
+Slice 1: Create a task   (DB + API + minimal UI)   → user can create + test passes
+Slice 2: List tasks      (query + API + UI)         → user can see them
+Slice 3: Edit a task     (update + API + UI)        → user can modify
+Slice 4: Delete a task   (delete + API + UI + confirm) → full CRUD
+```
+
+## Sizing a slice
+A slice is the right size when it:
+- delivers one observable capability end-to-end;
+- can be built and proven in a single `/rite-build` → `/rite-prove` cycle;
+- has acceptance criteria you can verify with evidence;
+- can be rolled back on its own.
+
+Too big if: it touches many unrelated files, has multiple "and"s in its goal, or you
+can't name its single observable outcome. → reslice.
+
+## How many slices? — derive, don't dictate
+The slice **count is an output, not an input.** It falls out of the work: one slice per
+independently-shippable vertical increment that satisfies one (or a tight group of)
+acceptance criteria and passes the sizing test above. A 2-criterion feature is 1–2 slices;
+a 12-criterion feature is however many thin end-to-end cuts those 12 need.
+
+- **Never slice to a target number.** Don't pad a small feature into "5 slices" or
+  compress a large one into "3" because a figure was named.
+- **A user-supplied count is a hint at most.** If the user says "do it in 4", slice the
+  work logically first; if your honest decomposition differs, present the logical count
+  and *why*, then let them redirect — don't silently force their number.
+- **Re-size by the rule, not the tally** (`/rite-plan reslice`): split a slice because it
+  failed the sizing test, not to hit a count.
+
+Not to be confused with `.devrites/AFK` `max_slices` — that's an AFK *iteration budget*
+capping how many slices the unattended loop builds before it stops, **not** the plan's
+decomposition. The plan always holds exactly the slices the work needs; `max_slices` only
+limits how many run unattended.
+
+## First slice
+Make slice 1 the **thinnest useful end-to-end path** — it flushes out integration and
+convention surprises early, while changes are cheap.
+
+## Slice independence
+Order by dependency, but minimize coupling. A slice that needs three other slices first
+is a smell — look for a thinner cut that stands alone.

package/pack/.claude/skills/rite-plan/reference/task-breakdown.md

@@ -0,0 +1,34 @@
+# Task breakdown
+
+How to turn a spec into ordered, vertical slices in `tasks.md`.
+
+## Each slice is one task, in this format
+```markdown
+## Slice N: <name>
+Goal:                       # single observable capability
+Acceptance criteria:        # binary, evidence-backed (see ../../rite-spec/reference/acceptance-criteria.md)
+Files likely touched:       # real paths from codebase inspection
+Tests to write/run:         # the command(s) that prove it
+Browser proof required:     # yes/no (yes if UI — see ../../rite-build/reference/frontend-trigger.md)
+Frontend craft required:    # yes/no
+Dependencies:               # slice numbers that must land first
+Rollback notes:             # how to back this slice out
+Evidence required:          # what /rite-prove must capture
+```
+
+## Process
+1. List the capabilities the spec promises.
+2. Map each to a vertical slice (thinnest end-to-end cut).
+3. Order by dependency; risk-first within a tier (do the scary slice early while it's
+   cheap to change).
+4. Mark which slices touch UI (→ frontend craft + browser proof) and which cross a
+   module/service boundary (→ `devrites-api-interface`, `devrites-doubt`).
+5. Sanity check: every acceptance criterion in `spec.md` maps to ≥1 slice; no slice has
+   an unowned criterion.
+
+## Keep it honest
+- Don't pre-write code in the task — describe the outcome, not the implementation.
+- Don't bundle "while we're here" work into a slice. That's scope creep; log it as a
+  follow-up instead.
+- Don't slice to a target number — the count comes from the capabilities + the sizing
+  rule (`slicing.md`), not a figure anyone named.

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

@@ -0,0 +1,90 @@
+---
+name: rite-polish
+description: Polish the active feature before review — code polish always; UI normalize + ship-quality pass when UI is touched. Use when the user says "polish this", "finish before review", "ship-quality", "normalize the UI", "bolder", "quieter", "distill", "harden". Not for repo-wide refactors or pre-`/rite-prove` polish.
+argument-hint: "[target | bolder | quieter | distill | harden | normalize-only]"
+user-invocable: true
+---
+
+# /rite-polish — finish before review
+
+The "finish" phase. **Always** code-polishes; **and** runs UI normalize +
+design polish when the feature touches UI. Self-review the work to ship
+quality *before* handing it to `/rite-review`. The two-phase split (code,
+UI) lives in `reference/code.md` and `reference/ui.md` — read each on demand,
+don't load both up front.
+
+## Operating rules
+
+- **Functionality complete first.** Polish runs after `/rite-prove` (full
+  feature proven).
+- Feature scope only.
+- For UI: **NEVER polish without normalizing first** — decoration on drift is
+  banned.
+
+## Orchestration
+
+0. **Read** `.claude/rules/core.md` first (the always-on operating rules). The
+   per-phase rule files (`coding-style.md`, `error-handling.md`, …) load on demand
+   from `reference/code.md` / `reference/ui.md` when their phase runs.
+   Then **run the shared orientation preamble** — it prints `state.md`, the artifacts present,
+   the run mode (HITL/AFK), and the open-question tally by gate, so you orient deterministically
+   instead of re-deriving state from raw Markdown:
+   ```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)"
+   ```
+1. **Read** `state.md`, `touched-files.md`, and the `git diff` for the active
+   workspace (or `$ARGUMENTS` if a target was given).
+2. **Detect UI scope** — UI is touched if the diff or `touched-files.md`
+   contains any of: `.tsx`, `.jsx`, `.vue`, `.svelte`, `.html`, `.css`,
+   `.scss`, `.sass`, `.less`, `.styl`, component dirs (`components/`,
+   `pages/`, `routes/`, `app/`, `views/`, `screens/`), Storybook stories,
+   or design-token files. When in doubt, look for visual changes that need
+   verification.
+3. **Always** read [`reference/code.md`](reference/code.md) and run **Phase 1
+   (code polish)**; if backend was touched, continue into **Phase 2 (backend
+   polish)** from the same file.
+4. **If UI scope detected** read [`reference/ui.md`](reference/ui.md), and read
+   `design-brief.md` if present (the UX/UI contract `devrites-ux-shape` shaped at spec and
+   `devrites-frontend-craft` refined while building) so the polish honors the agreed
+   direction + states. Then run
+   **Phase 3 (normalize)** → **Phase 4 (UI polish)**. Honor argument modes:
+   - `bolder | quieter | distill | harden` — passed to Phase 4 as the
+     emphasis dial.
+   - `normalize-only` — run Phase 3 and stop (no Phase 4).
+5. **Re-verify after any code edit** — polish edits code, so the proof from
+   `/rite-prove` no longer post-dates it. Run the relevant fast checks (the
+   targeted tests for the touched files + typecheck/lint; browser re-check if UI
+   changed) and record a **`Re-verification:`** line in `polish-report.md`. A
+   polish that changed code without a green re-verification isn't finished.
+6. **Aggregate output** — both phases append to the single `polish-report.md`.
+
+## Refinement modes
+
+When the user (or your own assessment) names a direction the UI should move,
+pass it through to Phase 4. Modes don't bypass normalize + quality-bar work —
+they shape the polish *after* the system is aligned. See `reference/ui.md` for
+the mode table.
+
+> **Mid-flight discipline.** When tempted to polish UI without normalize, cite
+> clean lint as proof of quality, skip Phase 2 on a backend diff, or delete a
+> Chesterton's Fence — see [anti-patterns](reference/anti-patterns.md).
+
+## Output → `polish-report.md`
+
+**Footer first (to chat, not into the report file)** — 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`). Then write the report:
+```
+Target: <slug | path/route/component>
+Phase 1 (code polish): findings → fixes (technique + why behavior preserved)
+Phase 2 (backend polish): error/log/data/API/cleanup fixes | n/a (no backend)
+Phase 3 (normalize):    drift found → root-cause fixes     | n/a (no UI)
+Phase 4 (UI polish):    quality-bar deltas                 | n/a (no UI)
+Browser evidence: <summary | n/a>
+Re-verification: <fast checks run after the edits → pass/fail | n/a (no code changed)>
+Open design questions asked: <none | list>
+Re-prove: <if polish changed code, run a scoped `/rite-prove` so evidence post-dates the change before /rite-review → /rite-seal | n/a — no code changed>
+Next: /rite-review
+↻ Hygiene: /clear between polish targets and before /rite-review (polish-report.md + browser-evidence.md captured). See rules/context-hygiene.md.
+```