devrites 5.5.0 → 5.6.0

package/pack/generated/pi/skills/rite-polish/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: rite-polish
+description: Polish the active feature's code and any touched UI before review. Use for finish or normalization requests; not for repository-wide refactors.
+argument-hint: "[target | bolder | quieter | distill | harden | normalize-only]"
+user-invocable: true
+---
+
+# /rite-polish: finish before review
+
+Polish code for every feature. When the feature touches UI, normalize and polish the
+UI as well. Complete this self-review before `/rite-review`. The code and UI phases
+live in [`reference/code.md`](reference/code.md)
+([`anti-ai-slop.md`](reference/anti-ai-slop.md),
+[`backend-polish.md`](reference/backend-polish.md))
+and [`reference/ui.md`](reference/ui.md)
+([`browser-polish-evidence.md`](reference/browser-polish-evidence.md),
+[`design-system-discovery.md`](reference/design-system-discovery.md),
+[`harden-checklist.md`](reference/harden-checklist.md));
+read only the phase in scope.
+
+## Operating rules
+
+- **Functionality complete first.** Polish runs after `/rite-prove` (full
+  feature proven).
+- Follow the shared
+  [`candidate-integrity.md`](../devrites-lib/reference/candidate-integrity.md).
+  Polish owns every candidate-affecting correction and durable rollup before Review.
+- Feature scope only.
+- For UI, **normalize before polishing**. Do not add decoration on top of drift.
+- **Bounded polish passes.** Verification runs in bounded passes, not a loop: after the
+  Phase 4 assessment, at most one more correction round for **new** findings, then stop —
+  residual subjective preference is recorded in `polish-report.md`, not re-polished.
+  **Failing case:** the same surface reopened a third time with no new failing evidence.
+- **Root selects; wright edits.** The controlling chat assesses and reconciles, but every
+  accepted source/test correction is dispatched to the sole writer,
+  `devrites-slice-wright`, through
+  [`agents.md`](../devrites-lib/reference/standards/agents.md). Never edit source inline or
+  run two correction writers concurrently.
+
+## Polish axes (C3 — completeness vs craft)
+
+Score **separately**; conflating them hides gaps:
+
+| Axis | Question | Failing case |
+| --- | --- | --- |
+| **ux_coverage** | Did we compare every stated alternative/state? | Omitted empty/error state treated as agreement |
+| **completeness** | Are required states, copy, and flows present? | Hero-only layout with no loading/error |
+| **craft / anti-slop** | Does the UI avoid generic template patterns? | Inter + purple gradient hero with no product-specific hierarchy |
+| **distinction** | Is there one intentional signature detail? | Polished but indistinguishable from a template |
+
+Incomplete comparison is **not** agreement. Record axis deltas in `polish-report.md`.
+
+## Orchestration
+
+0. **Read** `.pi/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
+   `.pi/skills/devrites-lib/reference/standards/browser-proof-checklist.md`.
+   Then read the explicit or active workspace's `state.md` directly.
+1. **Read** `state.md`, `touched-files.md`, the current candidate digest, 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 assess **Phase 1
+   (code polish)**; if backend was touched, assess **Phase 2 (backend polish)** from
+   the same file. Reconcile the findings, then send accepted corrections as one bounded
+   wright contract.
+4. **If UI scope detected** read [`reference/ui.md`](reference/ui.md), and read
+   `design-brief.md` if present so the polish follows the direction and states established
+   by `devrites-ux-shape` and refined by `devrites-frontend-craft`. **Read the
+   `## Visual Verdict` table in `browser-evidence.md` if present:
+   its `FAIL` and `PARTIAL` rows are the normalize/quality-bar worklist**: identify the root
+   cause of each (a missing state, an off-token CTA, or an anti-slop hit) rather than
+   hiding it with decoration. Assess **Phase 3 (normalize)** → **Phase 4 (UI polish)**,
+   then send accepted UI
+   corrections to the wright (which invokes the relevant craft skill). Honor argument modes:
+   - `bolder | quieter | distill | harden`: passed to Phase 4 as the
+     emphasis dial.
+   - `normalize-only`: assess Phase 3 and stop (no Phase 4).
+5. **Finish durable rollups before Review.** Apply the capability
+   [`ledger`](reference/ledger.md) when requirements changed, the optional UI
+   [`design memory`](reference/design-memory.md), and durable
+   [`ADR promotion`](reference/adr-promotion.md). Add every changed project path
+   to the candidate manifest; none of these writes waits for Ship.
+6. **Re-prove and close.** After all accepted code/UI corrections and rollups,
+   run `devrites-engine check candidate <slug>`. Any digest change requires
+   affected real re-proof using the approved commands, fresh proof-runner
+   validation, refreshed evidence/browser bindings, and an updated candidate
+   manifest. Record a **`Re-verification:`** line in `polish-report.md`. Close
+   the candidate for Review only after these checks are green.
+7. **Aggregate output:** each phase appends to the single `polish-report.md`.
+
+## Refinement modes
+
+Pass the requested UI direction to Phase 4. Modes do not bypass normalization or the
+quality bar; they apply after the system is aligned. See `reference/ui.md`.
+
+> **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).

package/pack/generated/pi/skills/rite-polish/reference/adr-promotion.md

@@ -0,0 +1,11 @@
+# ADR promotion
+
+During Polish, promote a `decisions.md` architecture/interface choice only when it is
+hard to reverse, surprising without context, and a real trade-off. Otherwise leave it in
+the archived workspace. If the project has no `docs/adr/`, ask before creating that
+convention.
+
+Write the next append-only `docs/adr/ADR-NNN.md` with Context, Decision, Status
+`accepted`, and Consequences. Never rewrite an accepted ADR; supersede it with a linked
+new ADR. Add it to the candidate manifest, run affected real re-proof, and refresh evidence
+and browser bindings before Review. Ship performs no ADR promotion.

package/pack/generated/pi/skills/rite-polish/reference/anti-ai-slop.md

@@ -0,0 +1,187 @@
+# Anti-AI-slop
+
+Tells of generic LLM-generated work — in **UI** and in **code**. Applies at two stages:
+
+- **At build time** (preventive) — `/rite-build` checks against these as it writes; the
+  cheap moment to avoid them.
+- **At polish time** (catch) — `/rite-polish` Phase 1 (Code) + Phase 2 (Backend) + Phase 4
+  (UI) scrub anything that slipped through.
+
+Avoid these unless the project's existing system explicitly uses them. When in doubt,
+match the neighbors.
+
+## UI anti-slop (banned defaults)
+- Default **purple/blue gradients** as the brand look. Special case: any
+  hero hex in the `#6366f1 → #a855f7 → #ec4899` family applied as a default.
+- **Gradient text** (`background-clip: text`) used decoratively on headings.
+- **Glassmorphism** (`backdrop-filter: blur(...)` on translucent panels) as
+  a default surface.
+- **Side-stripe colored borders** on cards/sections — the
+  "tiny-bar-of-meaningful-accent-color-on-the-left" pattern. Distinctive
+  templating tell.
+- **Pure `#000` / `#fff`** as raw text or background — too clinical; use
+  near-black/near-white tokens (`oklch(0.18 0 0)` / `oklch(0.98 0 0)` or
+  the project's surface tokens).
+- **All-CAPS body text** for paragraphs/labels. Reserve uppercase for short
+  micro-copy (badges, eyebrows); never for sentences.
+- **Em-dashes in UI copy — zero.** Soft limits ("use sparingly") get ignored; the rule
+  is binary and greppable: no `—` in any visible string. Use a comma, period, or colon.
+- **Cards inside cards** — nested bordered/elevated containers.
+- **Identical card grids** for everything, regardless of content.
+- A **generic rounded-square icon tile** above every heading/section.
+- **Gray text on colored backgrounds** (fails contrast, looks templated).
+- The **hero-metric cliché** — three big numbers in a row with no real meaning.
+- **Decorative bounce / elastic easing** on everything; motion without purpose.
+- **Reflex fonts** picked because they're the default in a tutorial:
+  - Inter for every product when the project has its own choice.
+  - **DM Sans**, **Plus Jakarta Sans**, **Fraunces**, **Newsreader** when
+    they're not the project's actual type system.
+  Match the project; don't reach for the "tasteful default" of 2024.
+- **Modal-first thinking** — reaching for a modal as the answer to every interaction.
+- **Ghost-card** — a `1px` border *and* a soft (blur ≥16px) shadow on the same element.
+  Borders separate; shadows lift — pick one
+  (`devrites-frontend-craft/reference/quality-standards.md` — Materiality).
+- **Balloon radius** — `border-radius` above ~16px on cards, inputs, panels. Cards top
+  out around 12–16px; full pills are for tags and buttons only.
+- **Uppercase tracked eyebrow above every section** — one named kicker is voice; one per
+  section is template grammar (countable cap below).
+- **Numbered-section scaffolding** (`01 / 02 / 03`) when the sections aren't a sequence.
+- **Fake UI-in-a-div** — a "product screenshot" assembled from nested divs, or hand-drawn/
+  sketchy SVG scenery. Ship a real capture/asset or nothing (quality-standards — Materiality).
+- **Hero prop badges** — version labels (`V0.6`, `BETA`) and decorative pulsing status
+  dots as set dressing.
+- **Unstyled UA chrome** — shipping the browser's default blue selection, caret,
+  scrollbar, or focus outline as the look (quality-standards § Browser chrome).
+- **Invented metrics** — precise-looking numbers with no source (`+247% faster`,
+  `99.99% uptime`). **Off-token color** — a hex used inline that the token set doesn't
+  define. Both are realism failures, not styling choices.
+
+### Required remediations (fix the hit, don't just flag it)
+A slop finding names its remediation from this table; a ban without a stated fix is
+an incomplete finding.
+
+| Signature | Required remediation |
+| --- | --- |
+| Default purple/blue gradient; gradient text; glassmorphism default | Re-derive from the scene sentence and colour commitment, then re-run both category-reflex tests |
+| Invented metric | Replace with the state lattice's missing-data placeholder (quality-standards § Focus & states) plus a "metric to confirm" question, or delete the proof slot |
+| Off-token color | Lift into the token set as a named color; replace every inline use |
+| Wrapping CTA / nav overflow | Shorter label, `white-space: nowrap`, or a collapsed nav — never a shrunken tap target |
+| Horizontal scroll in 320–1920 | `minmax(0, 1fr)` on content tracks + `overflow-x: clip` on `html`/`body` (quality-standards § Responsive) |
+| Fake UI-in-a-div screenshot | Ship a real capture/asset or remove the block |
+| Sticky sub-nav hidden by a banner | Offset by the banner's token height; split z-index roles instead of one raised value |
+| Unstyled UA selection / focus ring / caret / scrollbar | Theme from tokens per quality-standards § Browser chrome, or decline in `design-brief.md` |
+
+### Copy & data realism
+Placeholder content is a tell even when the layout is clean: fake-perfect numbers
+(`99.99%`, `10,000+` — real data is ragged), placeholder people/brands ("John Doe",
+"Acme"), filler verbs (Elevate / Seamless / Unleash). Re-read every visible string before
+shipping; AI-cute copy is worse than boring copy.
+
+### Category-reflex check — run at two altitudes
+
+Most generic-AI design fails one of these two reflex tests. Run both — the
+second one catches what the first one misses.
+
+- **First-order:** if someone could guess the theme + palette *from the
+  category alone* — "observability → dark blue", "healthcare → white +
+  teal", "fintech → navy + gold", "AI tool → black with a violet accent",
+  "crypto → neon on black" — the styling is on the first training-data
+  reflex. Rework the scene sentence
+  (`devrites-frontend-craft/reference/design-references.md`) and the
+  colour-commitment strategy
+  (`devrites-frontend-craft/reference/quality-standards.md`) until the
+  answer isn't obvious from the domain.
+- **Second-order:** if a stranger looked at the surface with *no copy
+  visible* and confidently said "this is a CRM / fitness tracker / fintech
+  / AI workflow tool", the styling is still on a category template — just
+  one tier deeper. The first reflex was avoided, the second wasn't.
+  Re-shape until the surface doesn't telegraph its category from looks
+  alone.
+
+Both pass = the surface looks like *this product*, not "an app in this category".
+
+### Mechanical pre-flight (countable — run, don't vibe)
+Each is pass/fail by counting or grep, not judgment:
+- **Em-dashes** in visible UI strings: exactly **0**.
+- **Eyebrows** (uppercase-tracked kickers): ≤ `ceil(sections / 3)`.
+- **Layout families** (hero, image+text split, card grid, bento, table…): no family more
+  than twice per page; never 3 consecutive image+text zigzags.
+- **Icons**: 0 emoji-as-icon; exactly one icon set imported.
+- **State presence in code**: default+hover+focus-visible+active+disabled for every interactive element; loading/error/empty where data delays or fails — an unreachable state's screenshot proves nothing.
+- **Form inputs**: no border-width shifts between states; focus ring from outline/ring (not border swap); consistent control height; reserved helper slot; disabled beyond opacity alone.
+
+## Code anti-slop (UI **and** backend)
+- **Over-defensive checks** — `if (x && x.length > 0)` repeated, layered null guards,
+  belt-and-braces nullability the surrounding code already proves. Signals lack of
+  confidence in the flow.
+- **Blanket `catch` / "robust" error handling** that swallows errors or wraps them in
+  generic "Something went wrong." Hides bugs. Catch narrow; rethrow with context; fail
+  closed on auth/permission/transaction.
+- **Useless wrapper functions** — `function getUser(id){ return User.find(id); }` adds a
+  hop with no value. Inline or remove.
+- **Over-engineered abstractions** for trivial problems — a factory + interface + plugin
+  registry for a 10-line function. **Don't add abstraction before two real callers**
+  (see `coding-style.md`, `patterns.md`).
+- **Convention-blind** code — ignores the repo's naming, file layout, error patterns,
+  validation style. "Generic good code" beats the project's idiom; reuse first (see
+  `coding-style.md`).
+- **Going beyond the spec** — features/options/configs/flags the spec didn't ask for.
+  Implement exactly what was specified; flag extras as follow-ups.
+- **Comment noise — the most common code tell.** Default to **zero** comments; the code and
+  the names carry the meaning. A comment earns its place only by answering *why* in one
+  sentence (intent, a trade-off, a non-obvious constraint, a "here be dragons" warning). Cut
+  every comment that restates the code:
+  - *What-comments* — `// increment i by 1`, `// set the user name`, `// return the result`.
+  - *Tutorial comments* — `// loop through the array` over a `.forEach`; `// check if null`.
+  - *Sycophant / filler* — `// helper function`, `// this is important`, `// magic happens here`.
+  - *Ownerless TODOs* — `// TODO: improve this later` with no issue/owner.
+  - *Meta / edit-process comments* — the agent narrating its own edit: `// Now I'll add error
+    handling`, `// Updated to handle the edge case`, `// As requested`, `// Step 1: … Step 2:`.
+    The reader doesn't care how the diff was produced.
+  - *Hedging / apologetic / overconfident comments* — `// should work`, `// hopefully handles
+    this`, `// I think`, `// hacky`, `// sorry`, or `// obviously` / `// just` / `// trivial`.
+    They admit the code is unverified (or paper over it). Verify the code; delete the doubt.
+  Density smell: more than roughly **one comment per ~10 lines of straightforward code** means
+  you are narrating, not explaining. Rename the thing or delete the comment.
+- **Names must match the contract.** A name is a promise about what the symbol does — keep it
+  honest. A `validateUser()` that actually checks payment status, an `isReady` that mutates
+  state, a `getUser()` that also writes a log: the name lies. Models pick names that *sound*
+  plausible for the category; verify the name says what the code does.
+- **Generic AI naming** — `process_data`, `handle_thing`, `do_it`, `result`, `data`,
+  `temp`, `manager`, `helper`, `util2`. Name for *intent*, in the repo's casing and idiom —
+  not for the action's category.
+- **Premature config** — feature flags / config knobs / extension points with no current
+  user.
+- **Dead leftovers** — TODOs without an owner/issue, commented-out code, unused imports,
+  `console.log`s, debug prints.
+- **Hallucinated imports & APIs** — an import of a package or module the project doesn't
+  declare (absent from the manifest/lockfile) or that doesn't exist, and invented methods or
+  parameters on a real library. Unused imports are dead code; *non-existent* ones are the model
+  inventing dependencies. Verify every import resolves and every unfamiliar API exists at the
+  source (`devrites-source-driven`) — never invent one.
+- **Placeholder bodies posing as complete** — a function that looks implemented but only does
+  `pass` / `...` / `return None` / `throw NotImplementedError` / returns a constant. It promises
+  functionality that isn't there. A genuine `@abstractmethod` / interface / Protocol stub is
+  fine — the slop is the stub pretending to be the real implementation.
+- **Fake or inflated docstrings** — a generic "This function does X" / "Handles the logic" that
+  restates the signature, or a 10-line docstring over a 2-line body. A real public-API docstring
+  earns its place; the slop is the one that inflates or says nothing. Follow the project's doc
+  convention either way.
+- **Oversized units (smell, not a hard gate)** — a function past ~50 logical lines, cyclomatic
+  complexity >10, more than ~4 parameters, or nesting ≥4 deep is a god-function smell. Split it
+  or flatten with guard clauses; judge in context, don't game the metric.
+- **Unexplained magic constants** — a bare literal, a hardcoded URL/endpoint, or an embedded
+  account/provider/test ID inline with no name or source. Give it a name (a const) or a home
+  (config/env). The mirror image of premature config, and just as much a tell.
+- **Copy-paste duplication** — a near-identical block pasted and tweaked instead of reused.
+  Reuse → extend → build new (`coding-style.md`, `patterns.md`); duplication beats the *wrong*
+  abstraction, but pasted clones are slop, not a deliberate AHA call.
+
+## Why banned, what instead
+They signal model-generated rather than team-designed work: they ignore register and
+idiom, add noise, hide bugs (defensive catches), bloat diffs, and often fail a11y or
+correctness review. Instead: project tokens/components, validate at trust boundaries,
+catch narrow and rethrow, one clear name per concept, reuse first (`coding-style.md`),
+implement exactly the spec. If the project intentionally uses one of these, follow the
+project — consistency beats the rule. A check or abstraction you can't justify in one
+sentence is slop: delete it or ask.

package/pack/generated/pi/skills/rite-polish/reference/anti-patterns.md

@@ -0,0 +1,30 @@
+# rite-polish: anti-patterns
+
+Load this when standing a non-trivial polish decision, or when tempted to
+skip normalize, polish without Chesterton's Fence, or cite clean lint/build
+as proof of quality.
+
+Pack-wide rationalizations + red flags (incl. lint-pass-as-quality): see
+[standards/anti-patterns.md](../../devrites-lib/reference/standards/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "Tests pass; the feature is done." | Tests don't measure ship-quality, design drift, anti-slop, or backend polish. |
+| "UI looks fine to me." | Must align to the design system + meet CWV/WCAG 2.2, not match a personal taste. |
+| "Code is simple enough; no need to audit." | Measure first. If there's no hotspot, that's fine, but record "no hotspots found", don't skip silently. |
+| "It's a small UI change; polish without normalize is fine." | **NO**: decoration on drift is banned. Phase 3 runs before Phase 4, always. |
+| "Backend looks OK; skip Phase 2." | If the diff touched BE, Phase 2 runs: error responses, logging hygiene, queries, anti-slop. |
+| "Fewer lines is simpler, so this is done." | The bar is the comprehension test, not line count: would a new reader understand it *faster* than the original? A cryptic one-liner fails it. Fewer-but-slower is churn: revert it. |
+
+## Red Flags
+
+- About to polish UI (Phase 4) without running normalize (Phase 3) first.
+- No browser evidence saved for a UI polish.
+- Code polish ran without naming a single technique (guard clauses, Extract Method, ...).
+- Backend was touched but `polish-report.md` shows no Phase 2 section.
+- A "simplification" that changes observable behavior. That's not behavior-preserving.
+- Reading a Chesterton's Fence as "looks dead" and deleting without explaining what it guards.
+- Simplifying, reflowing, or "tidying" a block marked `devrites:keep` / `simplify-ignore`: the marker is an explicit fence; leave it in place.
+- Hand-editing a >500-line simplification that a codemod / AST transform should have applied uniformly.

package/pack/generated/pi/skills/rite-polish/reference/backend-polish.md

@@ -0,0 +1,80 @@
+# Backend polish (when backend touched)
+
+Runs as Phase 2 of `/rite-polish` when the feature touches server-side code: handlers /
+controllers / services / routes / models / migrations / queries / jobs / workers / auth /
+schemas. Polishes the **server side** to ship-quality before review, the way UI normalize
++ polish does for the client side.
+
+## Scope detection (BE is in scope if any of these are touched)
+- API/route handlers (REST/GraphQL/gRPC); controllers/services/middleware.
+- DB layer: models, queries, migrations, schemas, ORM calls.
+- Auth/session/permission code; trust-boundary checks.
+- Background jobs, workers, schedulers, queue handlers.
+- Server-side files in the project's language (`.rb`/`.py`/`.go`/`.rs`/`.java`/`.cs`/
+  `.php`/`.ts`-server etc.) outside the UI layer.
+
+## Polish checklist
+
+### Error handling (consistent + meaningful)
+- [ ] **Consistent error response shape** across endpoints (e.g. an RFC 7807 problem
+      document or the project's existing convention). One shape, not three.
+- [ ] **Correct HTTP / protocol status codes** (4xx for client errors, 5xx for server
+      errors; not 200 with `{ error: ... }`).
+- [ ] **Custom error classes** (or equivalent) so callers can distinguish error kinds.
+- [ ] **Fail closed** on auth/permission/transaction errors: deny + roll back; never
+      default to allow or partial commit (`error-handling.md`, `security.md`).
+- [ ] **Narrow `catch`**: no blanket `catch (e) {}` swallows. If you catch, recover or
+      rethrow with context.
+
+### Logging hygiene
+- [ ] **Structured logs** (key/value or JSON) with **context**: request id, user/actor
+      id, operation, duration.
+- [ ] Log the **events that matter**: failures, access violations, validation rejections,
+      retries, auth events.
+- [ ] **Never log** secrets, tokens, full credentials, PII, full request bodies for
+      sensitive endpoints. Mask or omit.
+- [ ] No `console.log` / debug prints left in. No noisy "got here" lines.
+
+### Data & queries
+- [ ] **No N+1**: fetch in batches / use joins or includes.
+- [ ] **No unbounded result sets**: pagination/limits where data can grow.
+- [ ] **Parameterized queries** only; never string-built SQL/shell/HTML.
+- [ ] **Indexes** exist for new query patterns (or recorded as a follow-up if the project
+      adds them by migration).
+- [ ] **Transaction boundaries** are right: one logical write = one transaction; rollback
+      on error; no partial commits.
+- [ ] Don't return more fields than the caller needs.
+
+### API contract
+- [ ] Response shape matches the contract the spec set (and what the UI / consumers
+      expect: match against `references/` if any).
+- [ ] **Idempotency** where applicable (PUT/DELETE; retry-safe POSTs with idempotency
+      keys).
+- [ ] **Pagination, sorting, filtering** consistent with neighboring endpoints.
+- [ ] **Validation at the boundary**: type/length/format/range on untrusted input;
+      reject what doesn't match (see `security.md` three-tier).
+
+### Performance (measure first)
+- [ ] Hot-path work measured; obvious wins (cache, batch, hoist) applied; perf claims
+      cite a number (`devrites-audit perf`).
+- [ ] No accidental quadratic loops over growing collections.
+
+### Cleanup
+- [ ] **Dead routes / unused endpoints** removed if this feature created them and they're
+      unused.
+- [ ] Naming + comments in touched server code: clear, intent-revealing, no fake-helpful
+      "// gets the user" lines.
+- [ ] No leftover `TODO`s without an owner/issue.
+- [ ] **Migrations** are reversible where reasonable; destructive ones have rollback notes.
+
+### Anti-slop (code patterns: see `anti-ai-slop.md`)
+- [ ] No over-defensive null/length checks layered redundantly.
+- [ ] No useless wrapper functions ("`function getUser(id) { return User.find(id); }`").
+- [ ] No generic AI naming (`process_data`, `handle_thing`, `do_it`).
+- [ ] No "robust" code that catches everything and hides bugs.
+- [ ] Didn't go **beyond the spec**: implemented what the spec asked, no extras.
+
+## Rules
+- Feature scope only. Don't refactor unrelated server code.
+- Re-prove after changes: targeted tests + a real request/response observation.
+- A polish change that breaks a test isn't behavior-preserving: revert and reconsider.

package/pack/generated/pi/skills/rite-polish/reference/browser-polish-evidence.md

@@ -0,0 +1,33 @@
+# Browser polish evidence
+
+Polish claims need visual proof. When a browser can run, capture evidence via the proof
+ladder (`devrites-browser-proof`) and record it in `browser-evidence.md` (and summarize
+in `polish-report.md`).
+
+## Required when a browser can run
+- Screenshots of the polished UI at the canonical viewport set
+  (`devrites-frontend-craft/reference/quality-standards.md` § Responsive — currently
+  320 / 768 / 1024 / 1440).
+  **Open each screenshot and describe what's visible**: a path is not proof.
+- All key interaction states captured or exercised: hover, focus, active, disabled,
+  loading, empty, error, success.
+- Console clean (no errors/warnings): captured.
+- No layout shift on load: observed.
+- Reduced-motion behavior checked if motion was added.
+- **Design references**: if the spec saved references in `.devrites/work/<slug>/references/`,
+  compare the polished UI against them: does it match the agreed target? Note any diffs.
+
+## Before/after
+Where polish changed something visible, capture a **before/after** pair. The pair is the
+evidence that the change is real and an improvement, not a regression.
+
+## If no browser is available
+- Record the limitation explicitly in `browser-evidence.md`.
+- Write the exact manual steps to verify (route, viewport, what to look for in each
+  state).
+- Do **not** claim the polish is verified. Mark it **pending (manual)** and let
+  `/rite-review` / `/rite-seal` weigh the UI risk.
+
+## Never
+- Cite "lint clean" / "build passed" / "no type errors" as evidence of *visual* quality.
+- Assert a state works without exercising it.

package/pack/generated/pi/skills/rite-polish/reference/code.md

@@ -0,0 +1,82 @@
+# Code + backend polish (Phase 1 + Phase 2)
+
+Loaded from `/rite-polish` every run, regardless of UI scope. Two sub-phases:
+code polish (Phase 1) and, when backend is touched, backend polish (Phase 2).
+
+## Rules consulted (read on demand from `.pi/skills/devrites-lib/reference/standards/`)
+
+- `coding-style.md`: Phase 1 (simplify, dead code, naming, comments).
+- `patterns.md`: Phase 1 simplification: avoid over-engineering.
+- `error-handling.md`: Phase 2 backend (no silent catches, consistent errors).
+- `performance.md`: Phase 2 backend (N+1s, query bounds).
+- `documentation.md`: keep touched docs current; record polish-time decisions.
+
+## Operating rules
+
+- **Never cite clean automation** (lint/build pass) as proof of good design or
+  simplicity.
+- Feature scope only. Spec Drift Guard applies.
+- Re-run targeted tests after each change: a simplification that breaks a
+  test wasn't behavior-preserving.
+
+## Phase 1: Code polish *(always)*
+
+Delegates the audit to `devrites-audit simplify`. Reduce complexity in the
+feature's touched code while **preserving exact behavior**. Scope = active
+feature only.
+
+- **Measure first, target hotspots:** deep nesting, long branchy functions,
+  high cyclomatic complexity, sprawling conditionals. Don't redistribute
+  complexity, reduce it. Untargeted cleanup just moves decision points around.
+- **Behavior-preserving techniques** (name the one used per change): guard
+  clauses (flatten nested if/else, return early on unwanted cases), Extract
+  Method (a coherent block into a named single-responsibility helper), simplify
+  conditionals (switch/lookup over a long if-else; decompose a complex boolean
+  into well-named parts), dedupe, inline single-use indirection, replace
+  hand-rolled utils with the stdlib/existing helper, delete dead code this
+  feature added.
+- **Chesterton's Fence:** understand *why* something exists before removing it.
+  If you can't explain a check, branch, or wrapper, you may not remove it:
+  many "useless" lines guard a real edge case. A `devrites:keep` / `simplify-ignore`
+  marker comment **is** an author's fence, made explicit: read it and leave the marked
+  block exactly as-is: never simplify, reflow, or "tidy" it. Honor the marker in place;
+  don't rewrite the file around it.
+- **Behavior preservation:** observable behavior stays identical; tests stay
+  green. If behavior would change, it's not simplification. It needs its own
+  acceptance + proof (and maybe drift handling). Prefer transformations with
+  obvious equivalence.
+- **Don't over-reduce / proportionality:** inherent complexity is fine;
+  readability is the goal, not a metric. Forcing the complexity number down by
+  *hiding* branches elsewhere is worse. Don't spend disproportionate effort on
+  small, stable, rarely-touched code; target central/often-read code.
+- **Guardrails:** feature scope only, no project-wide refactor; don't delete
+  suspected dead code **outside** this feature without asking; re-prove after
+  simplifying (a simplification that breaks a test wasn't behavior-preserving);
+  cleverness that's shorter but harder to read is not simpler.
+- **Rule of 500: mechanize the big ones.** A simplification touching more than ~500 lines
+  (a rename, an API-shape change, a repeated idiom swap) is a job for a codemod / AST transform /
+  `sed`, not hand-edits. Hand-editing at that scale is where transcription bugs and inconsistent
+  application creep in; a scripted transform applies once, uniformly, and is reviewable as one diff.
+- **Cleanup**: remove TODOs, `console.log`s, commented-out code, unused
+  imports/vars; tighten naming and comments in code this feature touched.
+- **The comprehension test (the completion criterion).** Every change must pass one question:
+  *would a new team member understand this faster than the original?* If not, it's churn, not
+  simplification: revert it. Fewer lines that read slower fail this test; a clearer five lines
+  beat a cryptic one.
+- **Done when:** every touched change passes the comprehension test, every anti-slop charter
+  item in the touched code is cleared (the AI-tells do-not list: [anti-ai-slop.md](anti-ai-slop.md)
+  Code section, `coding-style.md`) **and** the feature's targeted tests + build re-run green.
+  An open charter item or a red check means Phase 1 isn't done.
+
+## Phase 2: Backend polish *(if BE touched)*
+
+See [backend-polish.md](backend-polish.md). For server-side scope (handlers,
+services, routes, models, migrations, queries, jobs, auth). Polish the server
+side to ship-quality.
+
+## Output → appends to `polish-report.md`
+
+```
+Phase 1 (code polish): findings → fixes (technique + why behavior preserved)
+Phase 2 (backend polish): error/log/data/API/cleanup fixes | n/a (no backend)
+```

package/pack/generated/pi/skills/rite-polish/reference/design-memory.md

@@ -0,0 +1,117 @@
+# Design memory: record proven design rules in `DESIGN.md`
+
+This optional `/rite-polish` step applies only to UI features. Feature design decisions
+live in `design-brief.md` and archive with the workspace. With the user's approval,
+copy proven, reusable design rules into the project-level `DESIGN.md` for later
+features.
+
+`devrites-ux-shape` §1 and
+`devrites-frontend-craft/reference/design-references.md` read `DESIGN.md` when present.
+This step writes that file from real feature evidence before Review.
+
+## When it runs
+- **UI features only.** No UI in the diff → skip silently.
+- **During Polish, after initial proof and before candidate closure.** Any update
+  enters the candidate manifest and is proved and reviewed with the feature.
+- **Opt in and confirm.** A project-wide artifact is outside feature scope
+  (`standards/core.md` rule 7), so never write it silently. Present a ranked option set
+  (see [`afk-hitl.md`](../../devrites-lib/reference/standards/afk-hitl.md), "Option set");
+  **default is skip**. The user opts to persist.
+- **AFK:** first-time `DESIGN.md` creation is a `validating` gate because it adds a
+  persistent project artifact. Propose and queue it; do not create it automatically. An append to an
+  existing `DESIGN.md` is `advisory` and may auto-proceed when `allow_gates` permits, since
+  it only adds evidence-proven entries.
+
+## Inputs (proven only)
+
+Entries are **proven, not aspirational**.
+- `design-brief.md`: direction, color strategy, **calibration** (density / motion), key
+  states, named anchors, and the per-slice **Build-time refinements**.
+- The **closed candidate diff** and `touched-files.md`: the tokens, components,
+  and states the candidate proves. Record only what the diff proves, not
+  everything the brief intended.
+- Existing `DESIGN.md` if present: the merge target.
+
+## What to record
+Record only reusable rules established by the proved candidate. Exclude choices
+that apply only to this feature.
+- **Tokens introduced + used:** new color roles / spacing steps / type steps / elevation
+  / radius proved in the candidate and reusable. Names and values, mirrored from the code.
+- **Color strategy and calibration baseline:** the strategy (Restrained / Committed / …) and
+  established density / motion; record a deviation as a deviation, not a new
+  default.
+- **Type & spacing scales** in actual use; **motion** classes + easing; **materiality**
+  (elevation set, hairline usage, glass / texture policy).
+- **Component behaviors:** for each shared component established or extended by the
+  feature, record its proved states and interaction model.
+- **Named-anchor lineage:** the anchors used by proved features.
+- **Anti-slop exceptions:** any banned default the project *intentionally* uses (with the
+  why), so build / polish don't "correct" a deliberate choice.
+
+## Merge discipline
+- **Append, don't overwrite.** Add proven entries; never silently rewrite an existing one.
+- **Ask about conflicts.** If a new token, font, or strategy contradicts an existing
+  `DESIGN.md` entry, present the option set to the user. Do not resolve it yourself.
+  Keep one design system per project.
+- **Never invent.** Include only rules proven by the feature.
+- **Attribute and keep it short.** Tag each new entry with the feature slug. Future
+  specs read this file, so use concise entries.
+
+## How it enters the candidate
+`DESIGN.md` is a tracked project artifact:
+1. Write / update `<project-root>/DESIGN.md` from the template below.
+2. Add `DESIGN.md` to the authoritative candidate manifest.
+3. Run affected real re-proof, refresh evidence/browser digest bindings, and
+   include the result in Review. Ship performs no design-memory write.
+
+## `DESIGN.md` template (project-level, stack-agnostic)
+```markdown
+# DESIGN.md — <project> design memory
+
+> Rolled up from proven features by `/rite-polish` (design memory). Read by
+> `devrites-ux-shape` and `devrites-frontend-craft` as the inherited system. Evidence-only:
+> every entry was proven. Edit through a feature's polish, not by hand.
+
+## Register & direction
+Default register per surface (brand / product) and the scene-derived direction the product
+keeps converging on.
+
+## Color
+Strategy baseline (Restrained | Committed | Multi-role | Saturated). Token roles
+(surface / text / accent / border / danger / …) with values or token names. Dark-mode approach.
+
+## Calibration
+Density baseline (Airy | Balanced | Dense) · Motion baseline (Minimal | Standard | Expressive).
+Surfaces that deviate + why.
+
+## Typography
+Families; the scale in use (fixed rem / fluid clamp); heading↔body ratio; weights.
+
+## Spacing
+The scale (4 pt multiples) and section rhythm in use.
+
+## Motion
+Classes in use, easing, `prefers-reduced-motion` handling.
+
+## Materiality
+Elevation token set, hairline usage, glass policy, texture / asset approach.
+
+## Components (proven behaviors)
+| Component | States proven | Interaction model | First proven by |
+|---|---|---|---|
+| <name> | default/hover/focus/loading/empty/error/… | inline / navigated / modal · feedback | <slug> |
+
+## Named-anchor lineage
+The anchors features steered toward (keeps new work coherent).
+
+## Anti-slop — project exceptions
+Banned defaults this project *intentionally* uses, with the why (so build/polish don't undo them).
+```
+
+## NEVER (design memory)
+- Never roll up unattended on first creation: a new persistent project artifact is a
+  confirmed step, never an AFK silent write.
+- Never write an entry the feature did not prove: no aspirational tokens.
+- Never overwrite or silently reconcile a conflicting existing entry: surface it.
+- Never persist a feature-only one-off as if it were the project default.
+- Never leave `DESIGN.md` outside the candidate manifest or defer it until Ship.