devrites 2.6.0 → 3.0.0

package/pack/generated/codex/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/codex/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/codex/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/codex/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/codex/skills/rite-polish/SKILL.md

@@ -0,0 +1,99 @@
+---
+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
+---
+
+## Codex compatibility
+
+This is the Codex mirror of a DevRites skill. In Codex:
+
+- Load DevRites engineering standards from `.agents/skills/devrites-lib/reference/standards/`. Read `.agents/skills/devrites-lib/reference/standards/core.md` before workflow work, then load the other `.agents/skills/devrites-lib/reference/standards/*.md` files exactly when this skill asks for them.
+- Use the installed `devrites-engine` binary as the canonical runtime helper surface for orientation, gates, and state mutation.
+- When this skill asks for a DevRites specialist or writer agent, **explicitly** spawn the matching Codex custom agent from `.codex/agents/devrites-*.toml` through Codex subagents (`spawn_agent`), then wait for its result and reconcile it as the skill instructs. Do not do the review inline just because the instruction to spawn is embedded here — Codex under-fires embedded spawn/skill instructions (openai/codex #23496), so treat the spawn as required, not optional.
+- The independence of a fresh-context subagent is the point. If Codex genuinely cannot spawn subagents in the current surface, run the documented inline fallback and **label the result an inline fallback, not an independent review** — an inline pass shares the calling context and is weaker evidence.
+- Codex project hooks are installed in `.codex/hooks.json`. Review and trust them with `/hooks` before relying on hook enforcement.
+- When this skill asks a HITL question via `AskUserQuestion`: Codex's equivalent (`request_user_input`) exists only in Plan mode. Outside Plan mode, render the option set as a plain numbered list in chat and **end the turn** so the human answers — NEVER silently pick an option yourself; auto-picking is AFK's contract, gated by the `.devrites/AFK` sentinel.
+
+
+# $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** `.agents/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
+   `.agents/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`.

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

@@ -0,0 +1,206 @@
+# 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.
+
+### Copy & data realism
+Placeholder content is a tell even when the layout is clean:
+- **Fake-perfect numbers** — `99.99%`, `10,000+`, `$1M`. Real data is ragged: `47.2%`, `1,283`.
+- **Placeholder people/brands** — "John Doe", "Acme", "Nexus". Invent specific, plausible ones.
+- **Filler verbs** — Elevate / Seamless / Unleash / Supercharge / Next-Gen. Say what it does.
+- **Copy self-audit** — re-read every visible string before shipping; anything grammatically
+  broken, referent-unclear, or "an LLM trying to sound thoughtful" gets rewritten. 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.
+
+## 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.
+
+### Comment density — before / after
+
+```js
+// Before (slop): a comment narrating almost every line
+function calculateTotal(items) {
+  // initialize the total to zero
+  let total = 0;
+  // loop through each item in the items array
+  for (const item of items) {
+    // add the item price to the total
+    total += item.price;
+  }
+  // return the final total
+  return total;
+}
+
+// After: the names carry it; no comment needed
+function sumPrices(items) {
+  return items.reduce((total, item) => total + item.price, 0);
+}
+
+// A comment that earns its place — it explains WHY, not what:
+// Prices are in minor units (cents); the gateway rejects fractional amounts.
+const total = sumPrices(items);
+```
+
+## Why these are banned
+They signal "a model generated this" rather than "this team designed/wrote this." They
+ignore the product's register and the project's idiom, add noise, hide bugs (defensive
+catches), bloat the diff (over-engineering, beyond-spec), and often fail accessibility
+or correctness review. They're cargo-cult, not craft.
+
+## What to do instead
+- **UI**: project tokens / shared components / consistent type & spacing
+  (`design-system-discovery.md`); content shapes layout; motion serves feedback;
+  reserve modals for focused interrupting tasks.
+- **Code**: validate at trust boundaries (don't sprinkle null checks); catch narrow,
+  recover or rethrow; one clear name per concept; one responsibility per function;
+  reuse before write (`coding-style.md`); implement exactly the spec; let inherent
+  complexity be — don't pad with ceremony.
+- If the project **does** use one of these intentionally, follow the project. Consistency
+  beats the rule.
+
+## When in doubt: ask
+A "robust" check or shiny abstraction you can't justify in one sentence is probably slop.
+Delete it; or ask the user if it should exist.

package/pack/generated/codex/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/codex/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/codex/skills/rite-polish/reference/browser-polish-evidence.md

@@ -0,0 +1,31 @@
+# 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 target viewports (375 / 768 / 1280 as relevant).
+  **Open each screenshot and describe what's actually 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.