devrites 2.6.0 → 3.0.0

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

@@ -0,0 +1,117 @@
+---
+name: rite-learn
+description: User-invoked review of the learning ledger; promotes recurring lessons to project rules or principles.
+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, timeline decisions, and health dips are durable
+signal. **Capture is automatic** — `/rite-seal` appends lessons to `.devrites/learnings.md` on every
+GO (step 9a), while the engine can keep `.devrites/timeline.jsonl`,
+`.devrites/health-history.jsonl`, and per-feature review fingerprints as supporting evidence. The
+review skills load the learning 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 `devrites-engine learnings`) 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 `devrites-engine learnings mine` over the archive (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
+   devrites-engine learnings mine
+   ```
+   Use `.devrites/timeline.jsonl`, `.devrites/health-history.jsonl`, and
+   `.devrites/work/*/review-fingerprints.jsonl` as supporting evidence when they exist; do not
+   promote from those traces without the same repeated-feature threshold.
+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).
+   **Completion:** every candidate cites two distinct features, except a single deliberate
+   rejected direction with its durable reason.
+3. **Classify each candidate** into its durable home:
+   - **project rule** — a craft/standard that belongs in a `.claude/skills/devrites-lib/reference/standards/*` file or `CLAUDE.md`.
+   - **project principle** — a recurring correction that is really a *non-negotiable invariant*
+     (not just an idiom or a craft standard): graduate it to `.devrites/principles.md`
+     ([`principles.md`](../devrites-lib/reference/standards/principles.md)). This is the **trusted, gating** layer — higher
+     stakes than a rule — so `/rite-learn` **drafts** the principle + a dated Governance entry for
+     the human to confirm; it never writes a principle silently.
+   - **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).
+   - **rejected direction** — an approach or product direction weighed and ruled out with a
+     reason that outlives one feature; recording it (tag `rejected-direction`) stops ideation
+     skills (`/rite-pressure-test`, `/rite-pov`) from re-proposing it. Exempt from the
+     ≥2-occurrence rule — one deliberate rejection is the whole pattern.
+   - **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.
+   **Completion:** every candidate is explicitly accepted, rejected, or deferred by the human.
+5. **Record the accepted.** For each the user accepts, append it with `devrites-engine learnings add <slug>
+   "<lesson>" <tag>` (`tag` ∈ `rule | convention | dismiss`). If the user approves a **rule**,
+   **principle**, 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 or principle files. A
+   **principle** promotion is the highest-stakes of these: draft the `.devrites/principles.md` entry
+   **plus its dated Governance line**, and let the human confirm before it lands — a principle is a
+   gate, so it is amended deliberately, never auto-written. **Amendment ripple:** a confirmed
+   add/change/retire of a principle has a blast radius — grep its `P#` (and its key nouns) across
+   `.devrites/` and every open `.devrites/work/*/` workspace, and append to the same dated
+   Governance entry one line per referencing artifact: *still-aligned* or *needs-follow-up (what)*.
+   An open plan that bakes in the now-retired or now-tightened invariant is a `needs-follow-up`
+   the next `/rite-vet` or `/rite-plan repair` on that feature must clear; a ripple with zero
+   references is itself worth recording ("no live references"). 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 ideation skills (`/rite-pressure-test`, `/rite-pov`) read the
+**rejected-direction** entries before proposing, so a ruled-out direction returns only with new
+evidence against its recorded why. The ledger is an **untrusted prior** — a fresh observation of the
+live code always overrides a ledger entry (see `.claude/skills/devrites-lib/reference/standards/security.md`). Confidence in a
+recorded lesson never raises its authority.
+
+A **project principle** (`.devrites/principles.md`) is the opposite layer — prescriptive,
+trusted, and **gating**. Promoting a lesson there is a deliberate amendment, not a prior the next
+fan-out can override: a violation becomes a blocking finding, not a suppressed false positive.
+That asymmetry is why principle promotion is human-confirmed and dated, never auto-written.
+
+## 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
+Reply-contract exception: cross-feature learning utility. It may run without an active
+feature, so it skips `devrites-engine progress`, but follows
+[`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md).
+
+```
+Done: learnings mined from <n> features; <n> recurring patterns found.
+Changed: .devrites/learnings.md <updated|unchanged>; rule/ledger drafts <n|none>
+Evidence: mined archive count <n>; candidates rule <a> / convention <b> / dismiss <c> / dropped <d>
+Open: <none | promotion confirmations>
+Next: <single recommended command>
+Record: .devrites/learnings.md
+↻ Hygiene: /clear; the ledger is on disk
+```

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

@@ -0,0 +1,95 @@
+---
+name: rite-plan
+description: Re-plan existing work when reality invalidates the plan: reslice a slice that is too big, repair drift, reorder dependencies, split boundaries, or unblock work. Not first-pass decomposition.
+argument-hint: "[mode: decompose|reslice|repair|reorder|split|unblock|course-correct|revise]"
+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>`. **Revise mode is artifact-only**: reconcile
+`spec.md` / `architecture.md` / `plan.md` / `tasks.md` / `traceability.md` without
+editing source code.
+
+## Rules consulted (read on demand from `.claude/skills/devrites-lib/reference/standards/`)
+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/skills/devrites-lib/reference/standards/core.md` (operating rules) before reshaping anything.
+   Then run `devrites-engine preamble` for deterministic workspace orientation.
+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/skills/devrites-lib/reference/standards/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. When the plan
+     names an `MVP cut`, offer it as the retreat option: falling back to the cut is a pre-agreed
+     scope, not a new negotiation.
+   - **revise** — apply a requested planning-artifact revision and reconcile existing artifacts in
+     any direction; propose the file edit set first, confirm each file before writing, and **never
+     edit source code**. **Gate first — revise or new?** Same intent? >50% of existing scope
+     survives? original *not* completable without this? Two "no"s → new work: recommend
+     sealing/shipping the current workspace (MVP cut if named) then `/rite-spec` for the new
+     intent, and stop. Revise preserves context; a new workspace provides clarity.
+   See [replan-and-repair](reference/replan-and-repair.md) for each mode's steps.
+3. Reason about dependencies — [dependency-graph](reference/dependency-graph.md).
+   **Completion:** the slice graph is cycle-free and every dependency names an existing slice.
+4. Re-slice using vertical-slice rules — [slicing](reference/slicing.md) and
+   [task-breakdown](reference/task-breakdown.md). Prefer thin, shippable, verifiable.
+   **Completion:** every slice is independently shippable/provable or carries an irreducibility reason.
+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.
+   **Completion:** the change is classified, and every behavior/acceptance change has explicit
+   confirmation recorded before the artifacts are updated.
+7. **Done when** — every slice is sized (builds + proves in one cycle; no slice scoring >3
+   left unjustified), the dependency order is acyclic, every `drift.md` entry you stopped for
+   is marked resolved, revised artifacts agree with each other, no source files changed in
+   `revise` mode, and behavior-change-vs-not is confirmed (`no`, or asked + answered).
+   If any check fails, loop back — don't hand off a half-reshaped plan.
+
+> **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
+
+**Progress first** — run `devrites-engine progress`, then use the shared completion reply contract
+([`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md)).
+Default success shape:
+```
+Done: plan repaired for <slug> in <mode> mode.
+Changed: plan.md, tasks.md, traceability.md, decisions.md, state.md
+Evidence: not applicable; slice map now <n> slices and next slice is <name>
+Open: <none | behavior question answered | Alternative: /rite-prove if all built slices need re-verification>
+Next: <single next command: build, re-define, or prove depending on the revision>
+Record: .devrites/work/<slug>/plan.md
+↻ Hygiene: /clear if the repair was large; keep session for small reorder-only repairs
+```

package/pack/generated/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 [standards/anti-patterns.md](../../devrites-lib/reference/standards/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/generated/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-001 (schema)  ->  SLICE-002 (write API)  ->  SLICE-003 (UI form)
+                   \->  SLICE-004 (read API)   ->  SLICE-005 (UI list)
+SLICE-006 (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/generated/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/generated/claude/skills/rite-plan/reference/slicing.md

@@ -0,0 +1,65 @@
+# 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-001: Create a task   (DB + API + minimal UI)   -> user can create + test passes
+SLICE-002: List tasks      (query + API + UI)         -> user can see them
+SLICE-003: Edit a task     (update + API + UI)        -> user can modify
+SLICE-004: 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;
+- is worth its own review gate: a reviewer could meaningfully reject *this* slice while
+  approving its neighbor. If two slices can only pass or fail together, they're one slice.
+
+Too big if: it touches many unrelated files, or you can't name its single observable outcome.
+**The "and" test:** if the slice's *name* needs an "and" ("create **and** list tasks"), it's two
+slices — split on the "and". → reslice.
+
+Sizing isn't cosmetic. An agent builds a small or medium slice reliably in one pass but drifts on
+an outsized one, which is why a slice over `Complexity: 3/5` reslices (the `tasks.md` slice format
+in [`rite-define`](../../rite-define/SKILL.md)). Push every slice to the smallest cut that still
+stands alone end-to-end.
+
+## 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.
+
+**Risk-first exception.** When the biggest risk is a technical *unknown* — "will this library
+even do X?", "can we hit the latency target?" — let slice 1 (or a throwaway spike ahead of it)
+prove that unknown, even if it isn't the thinnest user-facing path. Fail the risky bet first,
+while pivoting is still 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/generated/claude/skills/rite-plan/reference/task-breakdown.md

@@ -0,0 +1,33 @@
+# Task breakdown
+
+How to turn a spec into ordered, vertical slices in `tasks.md`.
+
+## Each slice is one task
+
+Use the complete canonical grammar in
+[`workspace-artifact-schema.md`](../../devrites-lib/reference/workspace-artifact-schema.md#canonical-slice-grammar).
+This reference owns decomposition; the shared schema owns field names and meanings.
+
+## 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), map each to the design
+   brief states, and give each a binary visual acceptance target. Mark which slices cross
+   a module/service boundary (→ `devrites-api-interface`, `devrites-doubt`).
+5. Write or update `traceability.md` so every `AC-###` maps to ≥1 `SLICE-###`, a
+   planned proof, evidence status, and likely touched files.
+6. Sanity check: every acceptance criterion in `spec.md` maps to ≥1 slice; no slice has
+   an unowned criterion.
+
+## Keep it honest
+- **Interfaces prevent cross-slice drift.** A slice-wright sees only its own contract; the
+  `Interfaces` line is how it learns the names and types neighboring slices use. A function
+  called `clearLayers()` in slice 3 and `clearFullLayers()` in slice 7 is a planning bug —
+  name shared symbols once, here.
+- 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/generated/claude/skills/rite-polish/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: rite-polish
+description: Polish the active feature before review: code always, UI when touched. Use when the user says "polish this", "finish before review", "normalize the UI", or "make it bolder/quieter". Not for repo-wide refactors.
+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/skills/devrites-lib/reference/standards/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; for UI scope also read
+   `.claude/skills/devrites-lib/reference/standards/browser-proof-checklist.md`.
+   Then run `devrites-engine preamble` for deterministic workspace orientation.
+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. **Read the `## Visual Verdict` table in `browser-evidence.md` if present:
+   its `FAIL` and `PARTIAL` rows are the normalize/quality-bar worklist** — fix the root cause of
+   each (a missing state, an off-token CTA, an anti-slop hit), don't decorate around it. 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`
+
+Write the detailed report to `polish-report.md`. In chat, run `devrites-engine progress` first,
+then use the shared completion reply contract
+([`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md)).
+Default success shape:
+```
+Done: polished <slug | target>; code/backend/UI phases <ran|n/a>.
+Changed: polish-report.md, <files touched | workspace only>, browser-evidence.md <updated|n/a>
+Evidence: re-verification <cmd -> pass | n/a>; browser <summary | n/a>
+Open: <none | non-blocking design follow-ups>
+Next: /rite-review
+Record: .devrites/work/<slug>/polish-report.md
+↻ Hygiene: /clear before /rite-review
+```
+If a design decision remains unresolved or polish invalidated proof, use `Awaiting human`
+or `Stopped / blocked` and route to the decision or `/rite-prove`; do not recommend
+`/rite-review`.