devrites 5.10.2 → 5.12.0

package/pack/generated/devin/skills/devrites-frontend-craft/reference/quality-standards.md

@@ -0,0 +1,294 @@
+# Frontend quality standards (2026)
+
+The measurable bar UI work is held to. Project conventions win where they're stricter;
+these are the floor, not the ceiling.
+
+## Performance: Core Web Vitals (field/p75 targets)
+- **LCP** (Largest Contentful Paint) ≤ **2.5 s**
+- **INP** (Interaction to Next Paint: the current responsiveness metric, replaced FID)
+  ≤ **200 ms**
+- **CLS** (Cumulative Layout Shift) ≤ **0.1**
+- Keep an interactive page's shipped JS lean (a budget around **≤400 KB gzipped** is a
+  good default); lazy-load below-the-fold and heavy/optional code; minimize hydration;
+  size and reserve space for images/media to avoid layout shift.
+
+## Accessibility: WCAG 2.2 AA
+- **Semantic HTML first:** real `<button>`/`<nav>`/`<label>`/headings; ARIA only to fill
+  gaps semantics can't.
+- **Keyboard**: every interactive element operable by keyboard; logical tab order; **focus
+  visible** with ≥ **3:1** contrast against its background (never remove the outline
+  without an equal replacement).
+- **Contrast**: text ≥ **4.5:1** (≥ 3:1 for large text and UI/graphics).
+- **Target size**: ≥ **24×24** CSS px (WCAG 2.2 AA, SC 2.5.8); prefer **44×44** for primary
+  touch targets.
+- **No drag-only** interactions: provide a single-pointer alternative (SC 2.5.7).
+- Labels/names on all controls; errors announced; respects `prefers-reduced-motion`.
+- **Test** with keyboard, a screen reader, and an automated checker (e.g. axe): early.
+
+## Motion
+- Purposeful only (class table below). Never animate to mask slow loading; honor
+  `prefers-reduced-motion`.
+
+## Responsive
+- Fluid layouts; no fixed widths that break. Verify at **320 / 768 / 1024 / 1440** px;
+  preserve content and controls at **200% text zoom** and **400% browser zoom from
+  1280 px** (320 CSS px). This is the canonical viewport set for UI evidence: [`ui.md`](../../rite-polish/reference/ui.md), [`browser-proof-checklist.md`](../../devrites-lib/reference/standards/browser-proof-checklist.md), and
+  [`browser-polish-evidence.md`](../../rite-polish/reference/browser-polish-evidence.md) cite it rather than restating it.
+- **No page-level horizontal scroll anywhere in 320–1920.** Sweep between checkpoints:
+  a `1fr` track given a 1024 px image can overflow at 900 px. Fix intrinsic sizing
+  (for example `minmax(0, 1fr)`), wrapping and media constraints; root clipping is
+  not a reflow fix. Clip decoration only, never text, controls or focus indicators.
+  A necessary two-dimensional table/map may scroll inside a named, bounded,
+  keyboard-accessible region; surrounding headings, text and pagination must reflow.
+  Record and test that exception. **Failing case:** a localized CTA disappears behind
+  `overflow-x: clip`; the missing scrollbar does not prove accessible reflow.
+- **`dvh`, not `vh`**, for full-height surfaces (`min-height: 100dvh`, never `h-screen` /
+  `100vh`: mobile address bars break them). A hero fits the *initial* viewport: headline
+  ≤2 lines, primary CTA above the fold.
+
+## Design system
+- Use the project's **tokens** (spacing/type/color roles): never hard-code a value a
+  token covers. Compose from existing components; one icon set.
+
+### Consistency locks (one per surface)
+Lock these in `design-brief.md` and hold them page-wide: mid-scroll drift ("a different
+website by section 7") is a tell: **one declared color strategy and role budget**
+(§ Color commitment; no unbriefed accent appearing later), **one radius scale**, **one theme** (light or dark, not both).
+
+## Numerical bar (enforceable specifics)
+
+These are the hard numbers that move "good UI" from opinion to checkable.
+Project tokens win when stricter; these are the floor.
+
+### Color
+- **OKLCH-only** for new tokens: perceptually uniform, predictable lightness
+  steps across hues. Stop reaching for HSL; the lightness lies.
+  - Example: `oklch(0.62 0.18 264)` for a saturated primary.
+- **Never `#000` / `#fff`** as raw values. Pure black/white are too harsh and
+  too clinical; use a near-black (`oklch(0.18 0 0)`) and near-white
+  (`oklch(0.98 0 0)`) or the project's surface tokens.
+- Contrast follows WCAG 2.2: text ≥ 4.5:1, UI/graphics ≥ 3:1. Verify
+  against the *rendered* background, not the theoretical one. Procedure: pair every
+  `color` declaration with its computed background; a button whose text and fill sit
+  within 5% lightness and 0.05 chroma of each other fails regardless of the palette.
+- **Restrained accent, capped:** one accent covers **≤5% of the viewport** at rest
+  (3–5 placements above the fold). Accent-filled panels fail this strategy; another strategy requires the explicit brief and role budgets below.
+- **Tint neutrals toward the brand hue:** pure-grey neutrals look sterile.
+  Nudge every grey 0.005-0.01 chroma toward the brand colour: invisible at
+  a glance, but the surface stops feeling generic.
+- **Alpha is a smell:** heavy translucency usually means an incomplete palette.
+  Define explicit overlay/hover tokens; transparency is for focus rings and scrims.
+- **Every colored surface token ships its `on-` pair** (`primary`/`on-primary`,
+  `destructive`/`on-destructive`, …) so contrast is designed in, not patched after.
+
+#### Color commitment: pick the strategy before the palette
+Decide *how committed* the surface is to colour before opening the picker. Four positions on a single axis; pick one, then design within it:
+
+| Strategy | Rough coverage | Use for |
+|---|---|---|
+| **Restrained** | tinted neutrals + 1 accent ≤5% of the viewport at rest | Most product UI; brand surfaces that want to look quiet. |
+| **Committed** | one saturated colour carries 30-60% of the surface | Brand pages with a strong identity; product feature surfaces that need a hero colour. |
+| **Multi-role** | 3-4 named colour roles, each used deliberately | Brand campaigns; product data-viz with distinct meanings. |
+| **Saturated** | the surface *is* the colour: full-bleed colour ground | Brand heroes, campaign pages, splash moments. |
+
+Two corollaries:
+- The ≤5% accent cap belongs to **Restrained only**. For Committed / Multi-role /
+  Saturated, the brief must name the strategy, purpose, tokens and measured coverage
+  budget per role and viewport. No blanket waiver: an unbudgeted colored panel fails.
+  Preserve distinct success/warning/error meanings; semantic states do not authorize decorative accents. Check rendered captures against the declared budgets.
+- *Register* (brand vs product) doesn't pick the strategy by itself: brand
+  surfaces aren't always Saturated, product surfaces aren't always Restrained. Pick from the scene, not the category.
+
+### Calibration: density & motion
+Colour commitment fixes *how much colour*; two more axes fix *how much space* and
+*how much movement*. Set one position on each (from the **scene sentence**, the same
+way colour is picked) and carry both in `design-brief.md` so the build targets a
+calibration instead of re-deciding it per slice.
+
+**Density**: information per viewport; drives which spacing steps dominate:
+
+| Position | Feels like | Spacing steps that dominate | Use for |
+|---|---|---|---|
+| **Airy** | gallery / calm / room to breathe | `32 / 48 / 64 / 80 / 96` | brand pages, onboarding, focus moments, low-data surfaces |
+| **Balanced** | most product UI | `16 / 20 / 24 / 32` | dashboards, forms, settings: the default |
+| **Dense** | cockpit / data-rich / power tool | `4 / 8 / 12 / 16` | tables, monitors, terminals, pro tools lived in all day |
+
+**Motion**: how much the surface moves; drives which motion classes (table below) are in play:
+
+| Position | Feels like | Motion classes in play | Use for |
+|---|---|---|---|
+| **Minimal** | crisp, almost still | Instant + State | dense tools, regulated/trust surfaces, reduced-motion-leaning |
+| **Standard** | responsive, purposeful | Instant + State + Layout | most product + brand UI: the default |
+| **Expressive** | choreographed, scroll-aware | + Entrance, deliberate sequencing | brand heroes, launch/campaign moments, story scroll |
+
+Corollaries (same shape as colour commitment):
+- Pick from the **scene sentence**, not the category: "an on-call SRE at 2am" → Dense +
+  Minimal; "a launch hero in afternoon light" → Airy + Expressive. Register doesn't decide
+  it by itself.
+- `prefers-reduced-motion` overrides Motion **downward at runtime** regardless of position:
+  an Expressive surface still ships a Minimal path.
+- The position is a target, not a straitjacket: a surface may break density locally for
+  emphasis: name the exception in the brief, don't let the whole page drift off it.
+
+### Spacing
+- **4pt base scale** (`4 / 8 / 12 / 16 / 20 / 24 / 32 / 40 / 48 / 64 / 80 /
+  96`). Project tokens may use a multiplier; never hardcode in-between
+  values.
+- Inline spacing rhythms in multiples of 4 px. Optical alignments may need a
+  1 - 2 px nudge: record the *why* in a comment.
+
+### Typography scale
+- **Brand surfaces**: fluid `clamp()` headings (e.g.,
+  `clamp(2rem, 1rem + 3vw, 3.5rem)`). Display/body pairing OK.
+- **Product surfaces**: **fixed rem scale** (1.125 - 1.2 ratio). One family
+  usually carries headings, body, labels, data.
+- Body line-height ~1.5; headings ~1.1 - 1.25. Prose width ~ 65-75 ch.
+- Adjacent hierarchy levels differ by **≥1.5× in at least one signal** (size, weight,
+  or color); verified under a blur(8px) squint — a flat field means the hierarchy is
+  decorative. **Failing case:** label and helper text differ only by 0.05rem.
+- All-caps display text sets **line-height ≥1.0**; tighter collides cap heights.
+- **Hero font-scale attribution:** a hero headline that wraps past its planned lines at
+  the target viewport is a font-size error first — fix the scale, don't shorten the
+  copy. **Failing case:** a four-line hero headline "fixed" by cutting the sentence.
+- Display ceiling: `clamp()` max ≤ ~6rem: larger is shouting. Display
+  letter-spacing floor **≥ −0.04em**; tighter and the letters touch.
+- `text-wrap: balance` on h1-h3; `text-wrap: pretty` on long prose.
+
+### Motion
+| Class | Duration | Use |
+|---|---|---|
+| Instant | 100 - 150 ms | Hover/press, tooltip enter, color shifts |
+| State | 200 - 300 ms | Toggle, focus ring, dropdown |
+| Layout | 300 - 500 ms | Modal/drawer enter, route transitions |
+| Entrance | 500 - 800 ms | Page entrance, hero animation |
+
+- **Exit at ~75 % of enter.** A 300 ms enter pairs with a 225 ms exit.
+- **Bounce / elastic easing banned** unless the project's design system
+  explicitly uses it.
+- Honor `prefers-reduced-motion`: reduce or remove non-essential motion
+  entirely. Reduced means fewer and gentler, never zero feedback.
+- **Loading feedback appears by ~200 ms**: skeletons/spinners replace stillness
+  after that threshold; below it, feedback flicker reads as jank. Hover intents
+  may delay 150–300 ms; focus indication never fades in — the ring is instant.
+
+### Forms
+- Inputs match button height (44 px floor); visual targets under 24 px expand
+  their hit area with a pseudo-element to the 44 px minimum.
+- Helper/error text reserves **`min-height: 1lh`** so messages never shift layout.
+- Border width is pinned across states (state changes recolor, never resize).
+- Disabled is visible through **three channels**: muted color, `not-allowed`
+  cursor, and blocked interaction — color alone fails.
+- Mobile inputs set **≥16 px** font (smaller triggers iOS zoom-on-focus).
+- Numeric/data columns set **`font-variant-numeric: tabular-nums`**; columns of
+  figures align or the surface reads broken.
+
+### Dark mode (three-axis compensation)
+A token-flip dark mode is sterile. When the project ships dark, compensate
+three axes from light:
+- **Line-height** `+0.05 – 0.10` (text breathes more on dark surfaces).
+- **Letter-spacing** `+0.01 – 0.02 em` (perceived spacing tightens on dark).
+- **Weight** `+1 step` for very small or low-contrast text.
+
+If the project has dark tokens already, follow them. If not and dark is in
+scope, propose the compensation rather than ship a flat invert.
+
+### Focus & states (8 required, 3 conditional)
+Every interactive element ships **8 visual/interaction states**:
+`default`, `hover`, `active`, `focus-visible`, `disabled`, `loading`,
+`selected`, and an error/invalid surface (required wherever the element can be invalid). Data surfaces add the
+conditional three whenever the data can produce them: **partial** (a missing field
+renders an explicit em-dash/placeholder — never `null` or `0`), **conflict** (a
+concurrent-edit/version-mismatch surface), and **offline/unreachable** (stale-data
+banner with retry, not a silently cached render). **Failing case:** a row with a
+missing value renders `0` or blank and the review reads it as real data.
+- `:focus-visible` ring: **2 - 3 px**, **≥ 3:1** contrast against the
+  background, **offset 2 px** so the focus is unambiguous on dense layouts.
+
+### Browser chrome
+User-agent defaults are unfinished craft. Per UI slice, theme or explicitly
+decline (briefed) each of: `::selection` (token colors, not UA blue),
+`caret-color` on editable fields, scrollbar styling or a recorded
+`scrollbar-width` decision, and the project focus-ring token in place of the
+unstyled UA outline. **Failing case:** layout, type, and the 8+3 states pass
+while the UA blue focus ring and default selection remain.
+
+### Container queries vs viewport queries
+- **Component breakpoints:** use **container queries** (`@container`). The
+  same card adapts to its column whether the viewport is 320 or 1920.
+- **Page-level layout:** use viewport queries
+  (`@media (min-width: ...)`) for sidebar collapses, header reflows.
+- Mixing the two is normal; using only one is usually a code smell.
+
+### Semantic z-index scale
+Pick a scale per surface role; never use raw `z-index: 9999`. Suggested
+floor:
+
+| Role | z |
+|---|---|
+| Base content | `auto` / `0` |
+| Sticky header | `50` |
+| Dropdown / popover | `100` |
+| Drawer / sheet | `200` |
+| Modal | `300` |
+| Toast | `400` |
+| System dialog / debug overlay | `500` |
+
+### Materiality (elevation & surface)
+Depth is earned, not defaulted. Reach **down** this ladder in order; stop at the first
+rung that carries the structure.
+- **Hairline first.** A **1 px border / divider** (a hairline in a near-neutral token)
+  defines structure before any shadow does. Borders separate; shadows lift. Most "cards"
+  want a hairline, not elevation.
+- **Elevation is a token scale, not an ad-hoc value.** When a surface genuinely lifts
+  (menu, popover, dragged item), use a **small shadow set from the design system** with one
+  consistent light source: never a one-off `box-shadow`. The elevation step and the
+  semantic z-index role move together.
+- **Texture needs contrast.** Grain / noise / pattern earns its place only when it reads
+  against the surface. Invisible texture is bytes with no signal: drop it.
+- **Asset-led material.** Rich material (photographic grain, real product imagery,
+  generated art) comes from a **real raster / generated asset**, not an SVG/CSS
+  approximation of one. Don't fake a photo with gradients; ship the asset or use a flat
+  token.
+- **No decorative glass.** `backdrop-filter: blur(...)` is for a fixed/sticky surface over
+  moving content (a sticky header, a sheet over scroll), never a default panel look
+  ([`anti-ai-slop.md`](../../rite-polish/reference/anti-ai-slop.md)).
+
+### NEVER (UI numerical bar)
+- Never reintroduce anything [`rite-polish` anti-ai-slop](../../rite-polish/reference/anti-ai-slop.md) bans.
+- Never hard-code a spacing value the 4 pt scale or project tokens cover.
+- Never animate an exit at 100 % of enter duration (feels uncontrolled).
+- Never use raw `z-index` numbers outside the semantic scale.
+- Never use viewport queries for component-internal reflows when the
+  component is reused at different widths.
+- Never ship dark mode as a flat token invert (compensate three axes).
+- Never reach for a shadow where a 1 px hairline carries the structure.
+- Never invent a one-off `box-shadow` outside the elevation token set.
+- Never ship texture / grain that doesn't read against its surface.
+
+## Verification gate (a UI slice isn't done until all pass)
+- [ ] Renders with **no console errors/warnings**
+- [ ] **Keyboard**: tab through reaches everything; focus visible; Esc/Enter behave
+- [ ] **Screen reader** conveys content + structure
+- [ ] **All states**: the canonical 8 + 3 lattice above (§ Focus & states), not a
+      shorter local list
+- [ ] **Responsive** at the canonical viewport set (§ Responsive); no lost content or
+      controls, no page overflow; bounded exceptions tested; zoom-safe
+- [ ] **No accessibility violations** (axe or equivalent)
+- [ ] Meets the **CWV budget** above (measure, don't assume)
+- [ ] Aligned to the **design system** (tokens, components, type, spacing)
+- [ ] **Browser chrome** themed or declined in the brief (§ Browser chrome)
+- [ ] Clickables show `cursor: pointer` + a hover state; icons are SVG from the one set
+      (no emoji); nothing trapped under fixed/sticky bars
+- [ ] **Consistency locks hold** (declared color strategy/roles / one radius scale / one theme) and the
+      mechanical pre-flight passes ([`anti-ai-slop.md`](../../rite-polish/reference/anti-ai-slop.md))
+
+## Craft convergence bar
+
+Craft work terminates; it does not loop. Findings classify as **Critical /
+Major / Minor**: done means zero Critical, zero Major, and every remaining Minor
+accepted **in writing** (owner + reason) in `polish-report.md` — an unwritten
+minor is an ignored finding, not an accepted one. Re-running the full bar after a
+fix pass happens only on an explicit opt-in ("re-run the full bar"); "keep going"
+is not opt-in. Each pass captures every supported viewport, not only the one that
+failed. **Failing case:** the 375 px overflow is fixed, 320 px still overflows,
+and the report reads clean.

package/pack/generated/devin/skills/devrites-frontend-craft/reference/reuse-first.md

@@ -0,0 +1,53 @@
+# Reuse first: frontend application
+
+Frontend application of the canonical rule in
+[`coding-style.md`](../../devrites-lib/reference/standards/coding-style.md#reuse-before-you-write):
+reuse → extend → build new, AHA caveat below. Before creating any new component, style,
+token, icon, hook, util, or helper, search the project first.
+
+This applies to UI **and** non-UI code: utilities, helpers, types, validators, schemas,
+formatters, hooks, query helpers: anything that might already exist.
+
+## The decision (in order)
+1. **Search first.** Apply `../../devrites-lib/reference/standards/tooling.md`: use the
+   primary available code index to find similar definitions, cross-check only a named
+   unresolved predicate, then fall back to grep/glob over `components/`, design tokens, hooks/,
+   utils/, lib/. Look for things doing the *same job*, not just the same name.
+2. **Exact fit → REUSE.** Compose / import the existing thing. No copy, no fork.
+3. **Close fit → EXTEND.** Add a variant/prop/option that the existing component or util
+   can carry without distortion. Adding a prop to a button is fine; adding ten props that
+   each branch the internals is not.
+4. **No fit → BUILD NEW**, in the project's idiom. If a similar need is likely to recur,
+   propose adding it to the shared system (component library / utils module). If it's
+   truly one-off, build it locally: don't pre-abstract.
+
+## When to *avoid* reuse (the AHA caveat)
+Reuse is good; **forcing** it isn't. **Avoid Hasty Abstractions**: if making the existing
+thing fit means warping its API or breaking its contract for one caller, **don't**.
+Duplication is cheaper than the wrong abstraction. Build a sibling component/util and let
+a real pattern emerge from two or three callers before consolidating.
+
+## Record the decision (per slice)
+On each slice, note what was reused / extended / created new, so the seal can see the
+consistency story and reviewers can spot silent duplication.
+
+```
+Existing reused: <Button, useToast, formatCents>
+Extended: <Card — added variant="elevated">
+Created new: <ExportProgress (no prior equivalent; propose for shared lib)>
+```
+
+## Anti-patterns to name
+- Silently re-implementing an existing component / hook / util because it was easier than
+  finding it. Search first.
+- Copy-pasting a component from `components/` into the feature folder. That's a fork.
+- Adding a second icon set / second toast library / second date util because the existing
+  one didn't quite fit: almost always extend the existing or ask first.
+- Forcing reuse via 8 boolean props that branch the internals. That's an abstraction
+  collapsing under its own weight. Split it.
+
+## Search hints
+- **UI**: `components/ui/`, design-system package imports neighboring features use,
+  `tokens.*` / Tailwind config / theme files, icon barrel files, layout primitives.
+- **Non-UI**: `lib/`, `utils/`, `helpers/`, `services/`, `validators/`, `schemas/`,
+  `hooks/`, language stdlib equivalents.

package/pack/generated/devin/skills/devrites-frontend-craft/reference/shape.md

@@ -0,0 +1,61 @@
+# Shape before code
+
+Decide what the UI *is* before how it looks. Aesthetics follow structure; structure
+follows the user's goal. Skipping this is how you get pretty UI that doesn't work.
+
+**The feature-level shape already exists.** `/rite-spec` ran `devrites-ux-shape` and wrote
+`design-brief.md` (design direction, key states, interaction model). In `/rite-build` this
+is a **per-slice refinement of that brief for the surface you're about to code**: confirm
+the answers below against the brief and fill any slice-specific gaps; don't re-derive the
+design. **Only shape from scratch here** when a UI slice has no `design-brief.md` (a spec
+written before shaping), then run `devrites-ux-shape` first; only if it cannot run, answer
+these and write the brief per `../../devrites-ux-shape/reference/brief-template.md`, and
+return through `/rite-vet` before code.
+
+## Answer these before writing markup
+0. **Surface intent:** is this a communication surface (a *site*: persuasion,
+   information, one message per section) or a task surface (an *app*: flows,
+   state, density)? Never ship one dressed as the other — a task tool built like
+   a landing page fails its user, and a marketing page built like a dashboard
+   fails its message.
+1. **User goal:** what is the user here to accomplish? One sentence.
+2. **Primary action:** the single most important thing on this surface. It must be
+   visually obvious. Everything else is secondary.
+3. **Information hierarchy:** what must be seen first, second, third. Rank content;
+   the layout expresses the ranking.
+4. **States:** design all of them, not just the happy path:
+   - default / populated
+   - loading (initial + subsequent)
+   - empty (with a clear next action: welcoming, not a dead end)
+   - error (what happened + how to recover)
+   - success
+   - disabled / read-only / no-permission
+   - long content / overflow / many items
+5. **Responsive:** how it reflows from small (320) to large (1440). What collapses,
+   stacks, hides, or scrolls.
+6. **Accessibility:** focus order, labels, contrast, keyboard operability, semantics.
+7. **Interaction model:** what's inline vs. navigated vs. (rarely) a modal; optimistic
+   vs. pending; how feedback is given.
+
+## Output
+The answers live in the feature's `design-brief.md` (shaped at spec by `devrites-ux-shape`).
+In build, append any slice-specific refinement to its **Build-time refinements** section;
+if you shaped from scratch (no brief existed), write the brief now per
+`../../devrites-ux-shape/reference/brief-template.md`. This drives the build and the polish
+checklist.
+
+## NEVER (shape)
+
+- Never start coding markup without naming the **primary action** for the
+  surface.
+- Never design only the populated/happy state. Empty / loading / error /
+  disabled / long-content are not optional.
+- Never decide the visual direction by personal taste when the project has
+  an existing system. Discover first (`design-references.md`).
+- Never invent a new flow when a neighboring feature already has one: match
+  the neighbor, then deviate only with a recorded reason.
+- Never paper over an ambiguous spec with a "reasonable guess". Ask the user
+  with 2 - 3 concrete options.
+- Never name a state for the *technical* condition (`isLoadingTrue`) when
+  the *user-facing* name (`Loading your invoices…`) tells the user what's
+  happening.

package/pack/generated/devin/skills/devrites-interview/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: devrites-interview
+description: Interview the user one question at a time to extract intent. Use when the user says "interview me", "I am not sure what I want", or the ask is underspecified. Not for casual clarification.
+triggers:
+  - model
+---
+<!-- loads: {"always":["devrites-lib/reference/standards/core.md","rite-spec/reference/interview-patterns.md"],"triggers":{"afk":["devrites-lib/reference/standards/afk-hitl.md"]},"workspace":["spec.md","questions.md","decisions.md","assumptions.md","decision-coverage.md","state.md"]} -->
+> Read-set manifest: `devrites-engine context [slug] --skill devrites-interview` bundles every file named below into one deduplicated read.
+
+# devrites-interview: extract intent
+
+Resolve the difference between the request and the user's intent before writing a
+spec, plan, or code.
+
+## Protocol
+- **Open with a working hypothesis.** State in one line what the user wants, then ask about the
+  highest-value unresolved human-owned material decision.
+- **One question per turn.** Multiple questions get one answered and the rest ignored.
+- **Attach an explicit recommendation** and its reason to every question:
+  > "I recommend CSV only because it covers the use case. Choose CSV, CSV + XLSX,
+  > or something else?"
+  This is a concrete candidate for the user's decision, not an assumption or confirmation.
+- **Ask in a full sentence that names the decision and why it changes the
+  build** — "Which export formats must v1 ship? Each adds a writer and a proof."
+  — never a bare label ("Formats?") or a context-free "any preference?"
+- **Highest-value question first:** order by how much the answer changes the build. A
+  question that moves the data model or acceptance criteria beats a cosmetic one.
+- **Prioritize impact and bound each pass.** Order unknowns **scope > security/privacy > UX >
+  technical**. A pass MAY contain at most **3 questions** for cognitive load. After each pass,
+  rescan the decision tree and continue in later turns until every human-owned material decision
+  is explicitly selected or explicitly deferred by the user. A cap MUST NOT move a blocker to
+  `assumptions.md`. Own and log reversible, low-impact technical details instead of asking.
+- **Structured options** when the space is enumerable: present them as the standard ranked
+  **option set** ([[`afk-hitl.md`](../devrites-lib/reference/standards/afk-hitl.md) → "Option set"](../devrites-lib/reference/standards/afk-hitl.md#option-set-how-every-gap-is-presented)): recommended **first**, labelled
+  `(Recommended)`, each with a dimension-tagged rationale (`logic · infra · business ·
+  architecture`, + `security`/`UX`/`risk` when in scope), plus the escape hatch. Render via
+  `AskUserQuestion` when the harness has it:
+  ```
+  1. <recommended> (Recommended) — logic: … · infra: … · business: … · architecture: …
+  2. <alternative> — <rationale + the trade-off it accepts>
+  3. Something else — I'll describe it
+  ```
+
+## Completion condition
+Complete only when a topology and decision-tree rescan finds no unresolved human-owned
+material decision. Such a decision closes only through the user's option selection,
+free-form answer, or explicit deferral. A recommendation is not confirmation. If the user
+stops early, persist every visible blocker and MUST NOT claim readiness or advance.
+
+Ask fewer, deeper questions. If answers stop converging around one area, **reframe once**
+instead of asking another version of the same question.
+
+## Want vs. should-want
+Users sometimes name the convention or best practice they think they should want instead
+of their actual preference. Signals include abstract virtues ("scalable", "clean",
+"modern"), deference to convention, or an answer that fits any project. Ask: *"if you
+didn't have to justify this to anyone, what would you want?"* Record that answer rather
+than designing to the generic one.
+
+## What counts as a yes
+Approval requires an **explicit** yes. Treat these replies differently:
+- *"Whatever you think is best"* / *"you decide"*: **delegation, not approval.** Offer two
+  concrete options so the user chooses the substance or explicitly defers it.
+- *"Sounds good"* / *"sure, let's go"*: confirm once for a material decision rather than
+  treating a polite exit as approval.
+- **Silence:** not consent. State what is out of scope and get explicit approval for it.
+
+## Don't ask
+- Things the codebase answers (read it first).
+- Reversible, low-impact technical details (decide and log as agent-owned assumptions).
+- Everything at once "to be thorough."
+
+## When the ask is vague: map the decision tree first
+For a short or vague request (`"design a contact page"`), do not ask isolated questions.
+Sketch the **decision tree** first, then resolve each branch **depth-first** with the
+protocol above. Domain branches per area:
+[`../rite-spec/reference/interview-patterns.md`](../rite-spec/reference/interview-patterns.md).
+
+## Reframe (once, when stuck)
+If the interview is not converging, use **one** turn to challenge the premise:
+*"is a form even the right answer here, or a mailto / booking link?"* Then resume the
+protocol with the revised premise.
+
+## /clarify mode: coverage scan of an existing spec
+When clarifying a written spec rather than extracting intent from scratch, first enumerate
+its actors, journeys/components, states, data boundaries, interfaces/integrations, and
+operational/proof surfaces. Scan every material surface against that taxonomy and mark
+**Clear / Partial / Missing** with evidence. Ask at most **3 prioritized decision packets per
+pass**, targeting Missing before Partial, one per turn with an explicit recommendation and reason.
+A packet may close
+several cells only when they share one owner and trade-off.
+
+**Integrate each answer into the relevant spec section** immediately. A Q&A log alone is
+insufficient.
+Record each question and resolution in `decision-coverage.md` as scan evidence, not a
+transcript block in `spec.md`.
+Re-run the scan after each pass. Packet limits control cognitive load, never readiness. Continue
+later passes while human-owned blockers remain, and stop only when every row is clear, agent-owned,
+not applicable, or explicitly deferred by the user with a nonblocking reason, owner, and validation
+gate. Then re-score the affected
+`checklists/<domain>.md`.
+
+## Output
+A short summary for the caller: objective in one sentence, confirmed decisions,
+open non-blocking items, and the recommended next step. If a workspace is active, write
+Q&A to `questions.md`, confirmed calls to `decisions.md`, and only agent-owned reversible,
+low-impact technical details to `assumptions.md`. If not, return the summary without creating
+a workspace.

package/pack/generated/devin/skills/devrites-lib/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: devrites-lib
+description: Internal shared DevRites helper library. Documents cross-cutting engine commands and references; not a user workflow. Do not invoke directly.
+triggers: []
+---
+
+# devrites-lib: shared workflow contracts
+
+Do **not** invoke this skill directly.
+
+## Ownership boundary
+
+- The host owns instruction loading, exact-agent dispatch, scheduling, waiting,
+  follow-up, results, and history. Skills state the role/result, never native
+  fields or dispatch receipts.
+- Dispatch every workflow-required role fresh. A missing role stops for HITL;
+  never skip, substitute, or perform its work in the root.
+- The root owns DevRites state/artifacts but never source/tests. Codex grants it
+  workspace permission only because children cannot elevate; writing follows
+  [`reference/standards/agents.md`](reference/standards/agents.md).
+- The engine owns the retained deterministic structure, atomic-write, install,
+  evidence-freshness, and safety primitives only.
+
+## Workspace orientation
+
+Use the supplied slug or read `.devrites/ACTIVE`. Require its authoritative
+`state.md`; read it directly, then only needed phase artifacts. Never infer
+lifecycle state from chat or optional `README.md`.
+
+## Shared references
+
+- [`reference/standards/agents.md`](reference/standards/agents.md): native custom-agent roles,
+  immutable inputs, result contracts, and source-boundary review.
+- [`reference/candidate-integrity.md`](reference/candidate-integrity.md): the
+  content-bound candidate lifecycle from Build through Ship
+  ([`workspace-artifact-schema.md`](reference/workspace-artifact-schema.md)).
+- [`reference/reply-contract.md`](reference/reply-contract.md): compact user-facing
+  completion states. The host renders the response normally.
+- [`reference/visual-playbooks/index.md`](reference/visual-playbooks/index.md): progressive
+  visual HTML playbook router (load matching ids only; dual-read outline).
+
+## Deterministic engine surface
+
+The engine is limited to:
+
+- Checks: `check candidate` (content-bound identity), `check readiness`
+  (structure; `--emit-binding` emits the Build-input binding), `check seal` (structure
+  plus exact artifact bindings and evidence freshness), `check slice` (slice
+  contract preflight before wright dispatch), `check task-graph`, `check
+  diff-scope` (mechanical changed-paths ⊆ allowlist before reviewer dispatch),
+  `check path-disjoint`, `check skill-trust`, `check indexes`, `check
+  regression` (progress high-water mark), `check drift` (readiness-input
+  attribution), `check windows` (deferral-marker waivers), `check dup`
+  (advisory near-duplicates), `detect commands` (repository test/lint wiring).
+- Observation: `observe summary` (`orient` alias), `observe slice`, `next`
+  (minimal remaining lifecycle path), `handoff` (deterministic resume record).
+- Coordination: `context` emits one deduplicated read-set bundle from each
+  skill's `loads:` manifest into `.devrites/work/<slug>/ctx/` — dispatch targets
+  read it instead of selecting files. It prints `unselected=[...]` for declared
+  triggers not passed; an omitted applicable trigger is a gap, not a shortcut. A
+  `--role` call is a dispatch, so the `agents` trigger auto-fires when declared
+  (`auto=[agents]` in output); a role with no agent contract file fails instead
+  of emitting a contract-less packet.
+  Manifest grammar: `always` loads every call; `triggers` maps names to files that
+  load only when passed or suggested; `workspace` lists the feature artifacts every
+  reader may need; `workspaceByRole` maps a dispatch role to its own artifact list —
+  present role wins, absent role falls back to `workspace`, an empty list means the
+  role reads no workspace files. The engine prints `suggested=[...]` triggers
+  inferred from workspace facts (AFK/parallel flags, frontend/security wording,
+  principles presence); confirm them rather than re-deriving conditions. Repeat
+  calls with unchanged inputs print `unchanged` and reuse the existing bundle.
+  `dispatch` owns the launch-wave barrier — seal needs a distinct handle per
+  role, return needs seal, and start/return auto-record into the `metrics`
+  ledger. `claim` owns the advisory session-scoped `claims.jsonl` ledger;
+  `note` owns anchored `notes.md` entries (`check seal` refuses non-exact
+  anchors); `parallel` owns deterministic worktree lease/create/integrate/
+  cleanup for parallel slices.
+- `gates` owns the machine-checked acceptance ledger (`gates.md`): `scaffold`,
+  `status`, `run`, `reverify`, `lint`, `attest`, `abandon` — grammar and
+  authoring rules in
+  [`reference/standards/gates.md`](reference/standards/gates.md).
+- Atomic state: `state resolve` for answer/drop/batch, `state merge-manifest`
+  for the predecessor-chain union, transactional `state close`, and `migrate`
+  for fail-closed workspace-schema normalization.
+- `secret-scan`, `open-visual`, and `version` remain read-only helpers.
+- Offline, local `install`, `update`, and `uninstall`; their shell/npm callers
+  acquire the candidate bundle, source, and binary before invoking the engine.
+
+Exact native agents/checklists own semantics; the host filesystem owns ledger
+reads/preview/confirmed no-clobber writes, spec grammar re-reading, question-id
+allocation, clarify cursor edits, AFK accounting, recovery accounting, and
+read-only diagnostics. Repository scripts and CI own gates.