devrites 5.10.2 → 5.12.0

package/pack/generated/devin/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
+  ([`quality-standards.md`](../../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/devin/skills/rite-polish/reference/code.md

@@ -0,0 +1,87 @@
+# 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 `.devin/skills/devrites-lib/reference/standards/`)
+
+- [`coding-style.md`](../../devrites-lib/reference/standards/coding-style.md): Phase 1 (simplify, dead code, naming, comments).
+- [`patterns.md`](../../devrites-lib/reference/standards/patterns.md): Phase 1 simplification: avoid over-engineering.
+- [`duplicate-code.md`](../../devrites-lib/reference/standards/duplicate-code.md): Phase 1 dedupe — `check dup` leads, triage verdicts, ignore ledger.
+- [`error-handling.md`](../../devrites-lib/reference/standards/error-handling.md): Phase 2 backend (no silent catches, consistent errors).
+- [`performance.md`](../../devrites-lib/reference/standards/performance.md): Phase 2 backend (N+1s, query bounds).
+- [`documentation.md`](../../devrites-lib/reference/standards/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. Run `devrites-engine check dup <slug>` (mode matching the
+  candidate diff: `--base <ref>` when committed, `--worktree`/`--staged` when
+  not) for near-duplicate leads and give each reported cluster a verdict per
+  [`duplicate-code.md`](../../devrites-lib/reference/standards/duplicate-code.md)
+  (merge / keep-with-reason / watch).
+- **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`](../../devrites-lib/reference/standards/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/devin/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
+[`design-references.md`](../../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
+  ([`core.md`](../../devrites-lib/reference/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.

package/pack/generated/devin/skills/rite-polish/reference/design-system-discovery.md

@@ -0,0 +1,8 @@
+# Design-system discovery
+
+Use the canonical discovery and register rules in
+[`design-references.md`](../../devrites-frontend-craft/reference/design-references.md#discover-these).
+
+Polish-specific decision: preserve the discovered identity by default. Depart only when
+the design brief or the user explicitly targets this surface for redesign. Completion:
+every changed value maps to an existing token/component or a recorded, confirmed departure.

package/pack/generated/devin/skills/rite-polish/reference/harden-checklist.md

@@ -0,0 +1,109 @@
+# Harden checklist: UI against real-world inputs
+
+Designs that only work on the happy path are not production-ready. `/rite-polish`
+Phase 4 (UI polish) uses this list to harden the feature against the inputs, errors,
+languages, and network conditions real users will throw at it.
+
+Feature scope only: don't harden screens this feature doesn't touch.
+
+## 1. Extreme content (the input axis)
+
+Walk every text-bearing surface in the feature with deliberately hostile data:
+
+- **Very long text:** names of 200+ chars, descriptions of 5000+ chars, titles
+  longer than the viewport. Check truncation, wrapping, ellipsis, overflow.
+- **Very short / empty text:** single-char names, empty strings, names that are
+  whitespace only. Check whether layout collapses or filters fail.
+- **Unicode:** emoji (`👨‍👩‍👧‍👦`: note grapheme clusters in count limits),<!-- pack-scan-ignore: intentional ZWJ in emoji edge-case example -->
+  zero-width joiners, RTL text (`مرحبا`), combining accents (`café` vs `café`).
+- **Numerics at scale:** `0`, negative numbers, `1.000.000`, `1234567890`, very
+  large currency. Check column width, formatter behaviour, locale separators.
+- **List sizes:** empty list, 1 item, 50 items, 1000+ items. Check pagination,
+  virtualisation, empty state, loading-state-then-empty.
+- **Adversarial input:** strings with `<script>`, `‮` (RTL override),<!-- pack-scan-ignore: intentional RTL-override example in adversarial-input checklist -->
+  trailing whitespace, leading zeros. Confirm escaping at render time (not just
+  on submit).
+
+## 2. Error scenarios (the failure axis)
+
+Every async path needs designed behaviour for at least these states:
+
+- **Network failure:** offline, slow (throttled to 3G), timeout, intermittent.
+- **HTTP:** `400` (validation), `401` (signed-out), `403` (permission),
+  `404` (gone), `409` (conflict), `429` (rate-limited), `500` / `502` /
+  `503` (server).
+- **Partial success:** a bulk action where some items succeed and others fail.
+- **Stale data:** user reads, leaves the tab open for an hour, then acts on
+  data that's since changed.
+- **Concurrent edit:** two windows of the same user, or two users on the same
+  record.
+
+For each: what does the UI show? Can the user recover, or are they stranded?
+Errors must be visible **where the user was acting**, not in a corner toast they
+might miss.
+
+## 3. Network / device conditions
+
+- **Slow connection:** does the surface show progress, or feel frozen?
+- **Offline:** does anything that *could* work offline still work (drafts,
+  cached views), and is everything that can't gracefully blocked with a clear
+  message?
+- **Touch + small screen:** every interactive element ≥ 24×24 CSS px (44×44
+  for primary touch targets). No drag-only flows.
+- **Keyboard-only:** full feature reachable without a mouse; visible focus;
+  Esc closes overlays; Enter submits primary forms.
+- **Screen reader:** every control has a name; live regions for async
+  feedback; reading order matches visual order.
+- **Reduced motion:** `prefers-reduced-motion` removes non-essential motion
+  (no auto-carousel, no spring entrances).
+- **High zoom:** 200% text zoom; layout doesn't break, nothing overflows.
+
+## 4. Localisation / i18n
+
+Even single-locale features get hardened against the dimensions i18n exposes,
+because real text behaves the same way:
+
+- **String length variance:** German + Finnish + Japanese typically run +30-60%
+  longer than English; check buttons, table headers, badges.
+- **RTL:** Hebrew / Arabic mirror the layout. Even if the project is LTR-only,
+  no RTL content should *break* anything.
+- **Date / number formats:** `1,234.56` vs `1.234,56` vs `1 234.56`. Currency
+  symbol placement.
+- **Pluralisation:** "1 item" vs "2 items" vs "0 items", and locales with
+  more than two plural forms.
+
+## 5. Permission / authorisation states
+
+Designed states for what the **current user** can / cannot do:
+
+- **Not signed in:** does the surface degrade, redirect, or 404 cleanly?
+- **Signed in, no permission:** message states what's missing and how to get
+  it; doesn't show empty data as if it were a real empty state.
+- **Signed in, partial permission:** read-only mode designed (controls
+  disabled with reason; never silently no-oped).
+- **Signed in, owner / admin:** surfaces destructive actions appropriately and
+  guards them.
+
+## 6. Tooling-assisted checks (when available)
+
+If the project has the tools, run them; capture evidence in `evidence.md`.
+
+- `prefers-reduced-motion`: emulate in DevTools → re-verify motion.
+- Throttle to "Slow 3G" → re-verify loading + error states.
+- Lighthouse / axe / pa11y → re-verify accessibility floor.
+- Playwright MCP or Chrome DevTools MCP (per `devrites-browser-proof`) → capture
+  screenshots of the worst-case input states above.
+
+## Reporting in `/rite-polish`
+
+For each finding raised by this checklist, classify by Phase-3 normalize bucket
+per [ui.md](ui.md):
+- **Token gap:** the design system already has the answer (`text-truncate`
+  token, `state-empty` component) and it isn't being used.
+- **Component miss:** the project already has an `EmptyState`, `ErrorBanner`,
+  `OfflineNotice`, and a one-off was built instead.
+- **Flow / IA misalignment:** the error / empty / offline state doesn't follow
+  the project's pattern (e.g. inline where the project shows a banner; toast
+  where the project uses inline).
+
+Fix in scope; route anything that would balloon the diff as a follow-up FYI.

package/pack/generated/devin/skills/rite-polish/reference/ledger.md

@@ -0,0 +1,67 @@
+# Capability ledger
+
+`.devrites/specs/<capability>/spec.md` is the canonical ledger of proven capability
+`### Requirement:` blocks across feature archival.
+Host filesystem I/O; no engine command.
+
+## Fold semantics
+
+A feature spec may group deltas under capability-tagged H2s (`## ADDED
+Requirements — capability: <c>`, `MODIFIED`, or `REMOVED`); see
+[`spec-grammar.md`](../../devrites-lib/reference/standards/spec-grammar.md).
+
+| Delta | Rule |
+|---|---|
+| ADDED | Append an absent block. Identical existing content is a no-op; the same header with different content conflicts. |
+| MODIFIED | Replace the named block in full. Equal content is a no-op; an absent target conflicts. |
+| REMOVED | Delete the named block. An absent target is a no-op; preview deletion if the capability becomes empty. |
+
+Match exact `### Requirement:` headers. Rename = REMOVED + ADDED. Flat specs
+seed the slug capability as all-ADDED.
+
+For MODIFIED, compare the complete current requirement block to its full replacement.
+It MUST preserve
+every existing scenario and normative or source-grounded claim unless an exact accepted `DEC-###`
+explicitly names its replacement or removal and rationale. For MODIFIED or REMOVED,
+reconciliation MUST account for load-bearing adjacent notes,
+examples, and comments whose meaning depends on changed text. Ambiguous ownership blocks
+reconciliation: preserve and show the content for an explicit decision; MUST NOT silently
+relocate or drop it. An unexplained omission is a blocking conflict,
+not cleanup or simplification.
+
+## Native preview/write workflow
+
+Run during Polish before Review so ledger edits enter the proved candidate.
+
+1. **Read.** Read the feature spec and only affected ledger specs. Reject a
+   capability escaping `.devrites/specs`, symlink/special file, duplicate header,
+   or malformed delta — an unknown verb, an empty delta section, a REMOVED block
+   carrying scenarios, or a MODIFIED/REMOVED header with no verbatim ledger
+   match (a near-match is a spec typo, not a rename).
+2. **Preview, do not write.** Show exact target paths; every delta with before/after
+   header; full requirement order; and changed files. Apply the table to current
+   bytes and the preservation rule to MODIFIED and REMOVED. Conflicts stop.
+3. **Check feature grammar.** Apply [`spec-grammar.md`](../../devrites-lib/reference/standards/spec-grammar.md)'s Native grammar re-read
+   checklist to the saved feature spec. Any miss stops. Step 2's native comparison owns delta reconciliation; an
+   already-applied empty preview remains a no-op.
+4. **Confirm.** Name exact paths and deltas. A later Seal or Ship approval does
+   not confirm this write. Skip only when no capability contract exists.
+5. **Write safely.** Use `git check-ignore` and `git status` to prove targets will
+   be tracked; surface a needed ignore carve-out. Immediately re-read and refuse
+   bytes changed since preview. Touch only `.devrites/specs/`, preserve unrelated
+   bytes/order, and apply only previewed replacements or empty-file deletion.
+   **Failing case:** Polish rewrites feature `spec.md` acceptance criteria "to match
+   code." Capability fold is the non-trigger; feature `spec.md` stays sealed
+   ([`core.md`](../../devrites-lib/reference/standards/core.md) rule 4).
+6. **Verify.** Re-read targets; require unrelated blocks byte-identical and the
+   same preview empty. Apply the same Native grammar re-read checklist to each
+   resulting capability spec.
+   Add changed paths to the authoritative candidate manifest, run affected real
+   re-proof, and refresh evidence/browser digest bindings before Review.
+
+Skip all six steps for a refactor/chore with no requirements.
+
+## Reading in Spec and Adopt
+
+List ledger specs with the host filesystem and read only touched capabilities.
+Classify against current file content, never memory.

package/pack/generated/devin/skills/rite-polish/reference/ui.md

@@ -0,0 +1,137 @@
+# Normalize + UI quality (Phase 3 + Phase 4)
+
+Loaded from `/rite-polish` only when the diff touches UI. Two phases, strict
+order: normalize to the design system (Phase 3), then the ship-quality detail
+pass (Phase 4). Normalize removes drift and aligns to the system; polish sweats
+the details. Skipping normalize means polishing drift.
+
+## Operating rules
+
+- **NEVER polish without normalizing first:** decoration on drift is banned.
+  Phase 3 runs before Phase 4, always.
+- Browser evidence required for UI polish when a browser can run
+  ([browser-polish-evidence.md](browser-polish-evidence.md)).
+- Don't invent a new design system. Ask when design-system principles are
+  ambiguous. Spec Drift Guard applies (a design-system contradiction is drift).
+
+## Why this order
+
+A beautiful component that ignores the project's tokens, components, and flow
+shape is *worse* than a plain one that fits. It adds a second system the team
+must maintain. Alignment is the precondition for polish, not an optional first
+step. **Fixing the symptom without naming the cause is how drift compounds:**
+patching a colour without adding the token bakes the next drift in; swapping a
+class without moving to the shared component leaves the next caller to redo the
+work.
+
+## Phase 3: Normalize
+
+Goal: this feature looks and behaves like it belongs in *this* product.
+
+1. **Discover the design system**
+   ([design-system-discovery.md](design-system-discovery.md)): docs, tokens,
+   shared components, spacing/type scales, color roles, icon set, interaction
+   & form patterns, neighboring screens.
+2. **Identify drift by root cause**, classifying each into one of **three
+   buckets**: the bucket dictates the fix:
+
+   | Bucket | What it is | Fix |
+   |---|---|---|
+   | **Token gap** | A value is hard-coded where a token should carry it (colour, spacing, type size, radius, shadow). | Use the existing token; if a needed slot doesn't exist, propose adding it to the system: don't invent one inline. |
+   | **Component miss** | A one-off implementation exists where a shared component already covers the case (button, input, dialog, menu, table row). | Swap to the shared component. Don't fork it into the feature folder. |
+   | **Flow / IA misalignment** | The feature's flow shape, naming, or mental model doesn't match neighbouring features (modal where the project goes inline; save-on-blur where the project uses explicit submit; new vocabulary for an existing concept). | Reshape the flow / rename to the project's vocabulary. The most expensive bucket, and the most damaging if skipped. |
+
+   Sub-cases that map back to the buckets above: generic-AI-template styling →
+   **Token gap** (hard-coded styling that should ride a token) or **Component
+   miss** (rebuilt instead of reused); orphaned styles or components this
+   feature created → **Component miss** (consolidate or remove); inconsistent
+   IA / naming → **Flow / IA misalignment**.
+3. **Fix root causes, not symptoms:** use existing tokens, swap to shared
+   components, align flow shape with neighbors, consolidate duplication, remove
+   obsolete styles created by this feature. Ask the user when a design-system
+   principle is genuinely ambiguous: don't guess the system's intent.
+
+## Phase 4: UI polish
+
+Only after functionality is complete **and** Phase 3 is done. Systematic detail
+pass against the UI quality bar below: zoom in, squint, use the thing. Little
+things add up.
+
+Meet the measurable bar below. Avoid [anti-ai-slop.md](anti-ai-slop.md). If the spec saved design
+references in `references/`, **match them**.
+
+Run the production-hardening sweep before declaring polish done (extreme
+inputs, errors, network, i18n, permission states) per
+[harden-checklist.md](harden-checklist.md). Polish that only works on the happy
+path isn't polish.
+
+### UI quality bar (checklist)
+
+- [ ] **Aligned to the design system:** drift named and resolved by root cause (Phase 3)
+- [ ] **IA & flow** match neighboring features
+- [ ] **Visual hierarchy:** the primary action is obviously primary
+- [ ] **Spacing** uses design tokens consistently; rhythm reads as deliberate
+- [ ] **Alignment** perfect at every breakpoint
+- [ ] **Typography** hierarchy consistent; line length sane (65-75ch prose)
+- [ ] **Color & contrast**: semantic roles; text ≥ 4.5:1 (≥ 3:1 large/UI), WCAG 2.2 AA
+- [ ] **All interaction states**: hover, active, focus, disabled, selected
+- [ ] **Focus states visible** and **keyboard navigation** works
+- [ ] **Loading** states clear; **empty** states welcoming with a next action
+- [ ] **Error** states helpful (what happened + how to recover); **success** states clear
+- [ ] **Forms** properly labeled, validated, with inline errors
+- [ ] **Copy & terminology** consistent with the product's vocabulary
+- [ ] **Icons** consistent set, properly sized and aligned
+- [ ] **Responsive** behavior correct across target viewports
+- [ ] **Target size** ≥ 24×24px (WCAG 2.2 AA); ≥ 44×44px for primary touch; **no drag-only** actions
+- [ ] **Motion** smooth (~60fps), purposeful; **reduced-motion** respected
+- [ ] **Performance basics:** no obvious jank, oversized images, or blocking work
+- [ ] **No console errors or warnings**
+- [ ] **No layout shift** on load
+- [ ] Works in the project's **supported browsers**
+- [ ] **Code quality** in touched UI files: no TODOs, console.logs, commented-out code
+
+### Measurable bar (2026)
+
+Polish verifies against the frontend quality standards
+([`quality-standards.md`](../../devrites-frontend-craft/reference/quality-standards.md)), measured not assumed:
+- Core Web Vitals (p75): **LCP ≤ 2.5 s · INP ≤ 200 ms · CLS ≤ 0.1**.
+- WCAG 2.2 AA: semantic HTML, keyboard-operable, visible focus ≥ 3:1, no drag-only.
+- Responsive at the canonical viewport set (quality-standards § Responsive — currently
+  **320 / 768 / 1024 / 1440**, plus the 320–1920 no-horizontal-scroll sweep); survives
+  200% text zoom.
+- No console errors/warnings; no axe violations; `prefers-reduced-motion` honored.
+Cite the evidence in `browser-evidence.md`.
+
+### Triage
+
+If it ships in 30 minutes, fix what users will notice (hierarchy,
+states, broken layout, bad copy) before micro-spacing. Don't introduce bugs
+while polishing: re-prove after changes.
+
+### Refinement modes (optional dials within Phase 4)
+
+| Mode | When | What it means |
+|---|---|---|
+| **bolder** | Surface reads safe / generic / forgettable. | Stronger hierarchy + weight contrast, one decisive accent, more committed scale. Reject generic-bold reflexes: gradients, glassmorphism, neon. |
+| **quieter** | Surface reads loud / overstimulating. | Reduce chroma, increase whitespace, flatten elevation, soften motion. Personality stays; intensity drops. |
+| **distill** | Too many elements / colours / sizes competing. | Remove anything that doesn't earn its place: redundant copy, decorative shadows/borders. One primary action per screen. |
+| **harden** | Surface only works on the happy path. | Walk [harden-checklist.md](harden-checklist.md) explicitly. Design every error / empty / partial / offline state. |
+
+Modes are advisory. Default Phase 4 covers all four already; the mode just
+shifts the emphasis of the same pass when the brief asks for it.
+
+## NEVER
+
+- Polish before it's functionally complete.
+- Polish without aligning first (decoration on drift).
+- Guess at design-system principles instead of asking.
+- Introduce bugs while polishing (re-prove after changes).
+- Invent a new design system or add a component/icon library without asking.
+
+## Output → appends to `polish-report.md`
+
+```
+Phase 3 (normalize): drift found → root-cause fixes
+Phase 4 (UI polish): quality-bar deltas
+Browser evidence: <summary>
+```

package/pack/generated/devin/skills/rite-pov/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: rite-pov
+description: Project-grounded verdict for adopting, switching, rejecting, or revisiting a named external technology, library, platform, CVE, or pattern.
+argument-hint: "[candidate/link/question]"
+---
+<!-- loads: {"always":["devrites-lib/reference/standards/core.md"],"workspace":["decisions.md"]} -->
+> Read-set manifest: `devrites-engine context [slug] --skill rite-pov` bundles every file named below into one deduplicated read.
+
+# /rite-pov: project-grounded external verdict
+
+Decide whether this project should adopt, trial, hold, reject, or ignore one
+named outside candidate.
+
+## Workflow
+
+1. Frame the candidate, decision intent, and reversibility tier (two-way = locally
+   reversible; bounded-one-way = reversible via a recorded rollback; high-stakes =
+   irreversible or costly). Route an
+   open-ended market search to `/rite-pressure-test` or `/rite-spec`.
+2. Inspect the live repository for at least one concrete project fact: an
+   incumbent dependency/call site, integration seam, relevant ADR/decision, or
+   confirmed absence. No profile cache.
+3. Verify the external claim from current primary documentation, source,
+   advisory, or release notes.
+4. Compare fit, existing alternatives, migration cost, reversibility, project
+   principles, security, licensing, and deprecation risk.
+5. Return exactly one verdict: `Adopt`, `Trial`, `Hold`, `Reject`, or
+   `Not-our-problem`.
+6. Persist only when asked: use the active feature's `decisions.md` for a
+   feature-scoped choice or propose an ADR for a durable architecture decision.
+   Do not write a parallel rejection or learning index.
+
+## Output
+
+```text
+Verdict: <grade> — <one sentence>
+Tier: <two-way | bounded-one-way | high-stakes>
+Project evidence: <file:line or local doc>
+External evidence: <primary source>
+Why: <three bullets max>
+Next: <one action | done>
+Record: <path | not written>
+```
+
+No project evidence or no primary external source means `Hold`, not a generic
+technology opinion.
+
+## Non-trigger
+
+Not a market survey or premise stress-test (`/rite-pressure-test` / `/rite-spec`),
+not implementation, not a patch plan. A CVE still needs a live advisory URL
+before any `Adopt`/`Trial`.
+
+## Failure and recovery
+
+- Missing project evidence or missing live primary source → `Hold`. **Failing
+  case:** "Adopt Redis" with no incumbent call site and no opened docs URL.
+- High-stakes / irreversible without a named rollback → cannot be `Adopt`.
+- Persist only when asked; a chat-only verdict is not a decision record.