devrites 2.6.1 → 3.0.0

package/pack/.claude/skills/rite-ship/reference/rollout.md

@@ -0,0 +1,43 @@
+# Staged rollout & rollback — when the ship includes a live deploy
+
+Opt-in. `/rite-ship`'s job ends at the git ladder (commit → push → tag / PR) and archiving the
+workspace; most projects deploy from CI on merge, and their pipeline owns the rollout. Reach for
+this reference only when the ship *itself* drives a live, staged production rollout the agent is
+responsible for. When it doesn't apply, skip it — the same no-op discipline as the rest of the pack.
+
+The governing idea is the one already in [`git-workflow.md`](../../devrites-lib/reference/standards/git-workflow.md) and
+[`deprecation.md`](../../devrites-lib/reference/standards/deprecation.md): **a launch is only done when it's reversible,
+observable, and incremental.** Write the rollback plan *before* you deploy, not after it breaks.
+
+## The rollback plan is a pre-condition
+Before the first byte ships, the plan exists, with a measured **time-to-rollback** per mechanism —
+feature flag < 1 min, redeploy < 5 min, DB rollback < 15 min. If the fastest reversal is slow, that
+is a launch risk to fix (add a flag) before shipping, not after. A destructive/migration step ships
+only with its rollback proven (expand→contract, [`deprecation.md`](../../devrites-lib/reference/standards/deprecation.md)).
+
+## Advance on evidence — the rollout decision thresholds
+Stage the exposure and, at each stage, read the signals ([`observability.md`](../../devrites-lib/reference/standards/observability.md))
+against a fixed table — advance on green, hold on yellow, roll back on red. Don't eyeball it.
+
+| Signal | Green (advance) | Yellow (hold, investigate) | Red (roll back now) |
+|---|---|---|---|
+| Error rate | within ~10% of baseline | 10–100% over baseline | > 2× baseline |
+| p95 latency | within ~20% of baseline | 20–50% over | > 50% over |
+| Client JS errors | none new | < 0.1% of sessions | > 0.1% of sessions |
+| Business metric on the path | neutral or up | < 5% decline | > 5% decline |
+
+## Stage the exposure, with a monitoring window at each step
+Internal/team → canary ~5% (hold 24–48h) → 25% → 50% → 100%, advancing only when **all** thresholds
+are green and you can still roll back to the previous percentage at any point. Data integrity or a
+security regression is an **immediate** rollback regardless of the table.
+
+## Feature-flag hygiene
+Every flag has an owner and an expiry; test both states in CI; don't nest flags (state explodes);
+remove the flag and its dead branch within ~2 weeks of full rollout — a lingering flag is the
+deprecation debt [`deprecation.md`](../../devrites-lib/reference/standards/deprecation.md) exists to prevent.
+
+## Verify in the first hour (a runbook, not a vibe)
+Health endpoint returns 200 · the error dashboard is flat · latency within budget · one critical
+user flow driven by hand · logs/metrics/traces actually flowing ([`observability.md`](../../devrites-lib/reference/standards/observability.md)
+"verify the telemetry fires") · a rollback dry-run confirmed reversible. Record the observations in
+`ship.md` / `evidence.md` — an un-watched launch is an unproven one.

package/pack/.claude/skills/rite-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rite-spec
-description: Investigate a new feature and write `spec.md` (placement, gaps, design refs, measurable acceptance) under `.devrites/work/<slug>/`. Use when the user says "spec out a new feature" or "I have an idea". Not for planning approved specs (use `/rite-define`) or replanning (use `/rite-plan`).
+description: Spec new or high-risk behavior before code and write its `.devrites/work/<slug>/` workspace. Use for a feature/app, vague product idea, auth or migration work, or a public-API change. Not for approved-spec planning.
 argument-hint: "<feature or idea>"
 user-invocable: true
 ---
@@ -18,36 +18,35 @@ are `/rite-define` and `/rite-build`.
 > the change turns out to touch auth / data / a migration / a public API / more than one slice.
 > Spec is for real features; don't pay its ceremony for a one-off.
 
-## Rules consulted (read on demand from `.claude/rules/`)
-**Step 0:** Read `.claude/rules/core.md` first. DevRites skills Read `.claude/rules/core.md`
-as their first step; the other rule files load on demand. Pull `documentation.md` via `Read`
+## Rules consulted (read on demand from `.claude/skills/devrites-lib/reference/standards/`)
+Pull `documentation.md` via `Read`
 when capturing significant spec decisions (why-not-what, ADR-style notes in `decisions.md`);
 pull `principles.md` when the project has declared invariants (`.devrites/principles.md`) — a
 new spec must respect them, and a requirement that can only be met by breaking one is a blocking gap.
-Pull `spec-grammar.md` when writing acceptance for a behavioral / high-risk requirement (auth,
+Pull `spec-grammar.md` and `devrites-lib/reference/workspace-artifact-schema.md` when writing
+acceptance for a behavioral / high-risk requirement (auth,
 data model, state machine, public API, money, migration) — the structured `### Requirement:` /
-`#### Scenario:` (SHALL · WHEN/THEN) form, lint-checked by `spec-validate.sh`. Simple criteria
-stay flat `[ACn]` bullets; the grammar is opt-in by rigor, never forced.
+`#### Scenario:` (SHALL · WHEN/THEN) form, lint-checked by `devrites-engine spec-validate`. Simple criteria
+stay flat `AC-###` bullets; the grammar is opt-in by rigor, never forced.
 
 ## Operating rules (DevRites core)
 - No silent assumptions · no guessing through confusion · prefer existing conventions ·
   ask the human when an answer changes scope, placement, data model, UX, security,
   migration risk, or acceptance.
+- **Author section by section, not in one dump.** Draft the spec one section at a time
+  (problem → goal → requirements → acceptance → edge cases), and pause after each: a section
+  that carries real risk (a contested requirement, a boundary, an unstated assumption) can be
+  deepened right there with a fitting technique from
+  [`elicitation.md`](../devrites-lib/reference/standards/elicitation.md) before moving on. A spec
+  written a section at a time is where sharper thinking lands cheaply; a wall-of-text spec hides
+  the weak section.
 
 ## Workflow
-0. **Read `.claude/rules/core.md`** — the always-on operating rules and anti-rationalizations.
-   Then **run the shared orientation preamble** — it prints `state.md`, the artifacts present,
-   the run mode (HITL/AFK), and the open-question tally by gate, so you orient deterministically
-   instead of re-deriving state from raw Markdown:
-   ```bash
-   P=.claude/skills/devrites-lib/scripts/preamble.sh
-   [ -f "$P" ] || P="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/preamble.sh"
-   [ -f "$P" ] || P=pack/.claude/skills/devrites-lib/scripts/preamble.sh
-   [ -f "$P" ] && bash "$P" || echo "(orientation preamble unavailable on this install — read state.md directly to orient)"
-   ```
+0. **Read `.claude/skills/devrites-lib/reference/standards/core.md`** — the always-on operating rules and anti-rationalizations.
+   Then run `devrites-engine preamble` for deterministic workspace orientation.
 0a. **Brownfield check — onboard before speccing onto un-adopted existing code.** If this is an
    **existing codebase** (real source predating DevRites) that has **never been adopted** — no
-   `.devrites/conventions.md`, no prior `.devrites/work` or `.devrites/archive` — the build has no
+   `.devrites/conventions.md`, no prior `.devrites/work`, `.devrites/features`, or `.devrites/archive` — the build has no
    conventions ledger to follow and the first slice would guess the project's idioms. Route
    through `/rite-adopt` **first**, carrying `$ARGUMENTS` as its *next objective*: adopt
    reverse-derives the baseline `spec.md`, **seeds the conventions ledger**, and proposes
@@ -59,13 +58,20 @@ stay flat `[ACn]` bullets; the grammar is opt-in by rigor, never forced.
    for the absence of adoption (the same no-op discipline as the principles gate). Cheap probe:
    ```bash
    if [ ! -f .devrites/conventions.md ] && [ ! -d .devrites/archive ] \
-      && [ -z "$(ls .devrites/work 2>/dev/null)" ] \
+      && [ -z "$(ls .devrites/work .devrites/features 2>/dev/null)" ] \
       && [ -n "$(git ls-files 2>/dev/null | grep -vE '^\.(devrites|claude)/' | head -1)" ]; then
      echo "brownfield, not yet adopted → recommend /rite-adopt first (carry this idea as its next objective)"
    else echo "greenfield or already onboarded → continue spec"; fi
    ```
 1. **Understand the request** (`$ARGUMENTS`). Restate the goal and the *real problem
    behind it* in a sentence or two.
+   **Completion:** one sentence states both requested outcome and underlying problem.
+1a. **Local dedupe.** Search local issues/PRDs and archived specs before creating a new workspace:
+   ```bash
+   devrites-engine spec-dedupe "$ARGUMENTS"
+   ```
+   If it finds a close match, ask the user: extend existing / adopt / new spec. Record the choice in
+   `decisions.md` once the workspace exists. No match → continue silently.
 2. **Investigate deeply** — [investigation](reference/investigation.md). Produce, and
    later write into the spec: **current behavior**; **placement** (which module/layer/
    file/component should own it, the seam, patterns to reuse, and integration points —
@@ -73,20 +79,32 @@ stay flat `[ACn]` bullets; the grammar is opt-in by rigor, never forced.
    (conflicts/constraints); **gaps** (unknowns); **blast radius**. Use a code-intelligence
    index **if available** — `codebase-memory-mcp` first, cross-checked with `codegraph`
    (`.codegraph/` / `codegraph_*`) + `graphify` (`graphify-out/`), else standard methods
-   (LSP / `Read`/`Grep`/`Glob`); see `.claude/rules/tooling.md` —
+   (LSP / `Read`/`Grep`/`Glob`); see `.claude/skills/devrites-lib/reference/standards/tooling.md` —
    for placement/callers/impact instead of broad file reads; fall back to reading files. For
    uncertain external library/framework facts that bear on placement or feasibility, consult
-   context7 if available.
+   context7 if available. When a material decision turns on a fact outside the codebase — a
+   common UX pattern, a standard, a prevailing best practice, how comparable products solve it —
+   **search the web if available** (brave MCP preferred; see `.claude/skills/devrites-lib/reference/standards/tooling.md`), and
+   carry the cited finding into the option you put to the human at step 4.
    Also discover the project's **test / build/typecheck/lint** commands and the
    frontend/backend systems; read `PRODUCT.md` / `DESIGN.md` / `CLAUDE.md` / `AGENTS.md` if
    present (`AGENTS.md` is the cross-tool agent-conventions standard — treat it as project
    conventions the build must follow, same standing as `CLAUDE.md`), and read
    `.devrites/principles.md` if present — the declared invariants the feature must respect.
+   **Consult the capability ledger** — the living record of what the system already does
+   ([`ledger.md`](../rite-ship/reference/ledger.md)): `devrites-engine ledger list` for the
+   capabilities on record, then `devrites-engine ledger show <capability>` for any this feature
+   touches. Also search prior decisions with `devrites-engine decisions search "<2-4 feature nouns>"`
+   before asking the human to re-decide a settled architecture/API/auth choice. Starting from the proven contract (not a cold re-derive) is what makes the spec store
+   compound across features; it also tells you which requirements are new vs a change to existing
+   behavior, which decides the delta kind in step 5.
 3. **Gather design references (optional)** — [references-intake](reference/references-intake.md).
    The human **may** attach screenshots, mockups, a Figma link, a video, or links — or
    **none at all** (perfectly normal; skip this step then). If any are given: **view/fetch**
    them, **save local files** into `.devrites/work/<slug>/references/`, and index them in
-   `references.md`. They become the target later phases verify against.
+   `references.md` as target, constraint, or inspiration. Later phases honor that role
+   rather than treating every reference as a fidelity target.
+   **Completion:** every supplied reference is saved and classified, or absence is explicit.
 3a. **Shape the UX/UI before code (if the feature touches UI)** — when this feature is
    frontend ([frontend-trigger](../rite-build/reference/frontend-trigger.md)), apply
    `devrites-ux-shape` **now**, woven into the spec — not as a separate phase. It turns the
@@ -95,14 +113,25 @@ stay flat `[ACn]` bullets; the grammar is opt-in by rigor, never forced.
    targets so the UI is built to plan, not guessed. In HITL it pauses for the human to
    confirm the direction; in AFK it asserts the best guess and logs it. Pure
    backend/data/CLI features skip this.
-4. **Close the gaps with the human.** Turn each material gap/issue into a question — one
-   at a time, **best guess attached**, structured options + escape hatch. (Vague ask →
-   `devrites-interview`; rough idea → `/rite-pressure-test`; ladders in
-   [interview-patterns](reference/interview-patterns.md) / [question-protocol](reference/question-protocol.md).)
-   For a vague ask, **map the decision tree** and resolve each branch depth-first; **cover
-   every dimension** (objective · scope · data model · UX · integration · non-functional ·
-   acceptance) — resolved or explicitly deferred — and **stop when answers converge** or you
-   can predict them (don't interrogate). Aim for **zero blocking gaps**. *If a gap is genuinely undecidable on paper (state
+4. **Close the gaps with the human — you recommend, the human decides.** Every material gap
+   (one that moves **objective · scope · placement · data model · UX · integration ·
+   non-functional · security · migration risk · acceptance**) is **put to the human as a ranked
+   option set**, one gap at a time, via the harness `AskUserQuestion` in HITL: **2–4 concrete
+   options, your recommended one first and marked `(Recommended)`**, each with a one-line
+   rationale + trade-off tagged by the dimensions that matter, plus an escape hatch (*Something
+   else — I'll describe it*). Render contract + AFK behaviour: the **Option set** section of
+   [`afk-hitl.md`](../devrites-lib/reference/standards/afk-hitl.md); spec-phase question discipline:
+   [question-protocol](reference/question-protocol.md). Your job is to **investigate, rank, and
+   recommend** — not to settle a material decision yourself. **Confidence changes the *cost* of
+   the question, not its *owner*:** when you're near-certain, you still present the set — the
+   human just confirms your `(Recommended)` option in one pick — you do **not** silently decide
+   it because you predicted the answer. Only a **genuinely reversible, low-impact** detail is
+   auto-decided and logged to `assumptions.md`; when unsure whether a gap is material, ask.
+   (Vague ask → `devrites-interview`; rough idea → `/rite-pressure-test`.) For a vague ask,
+   load [`reference/interview-patterns.md`](reference/interview-patterns.md), **map the decision
+   tree**, and resolve each branch depth-first; **cover every dimension** —
+   each resolved by a human pick or explicitly deferred (logged, non-blocking), never silently
+   skipped. Aim for **zero blocking gaps**. *If a gap is genuinely undecidable on paper (state
    machine that may deadlock, data shape ambiguity, "which UX wins") → suggest a
    scoped detour to `/rite-prototype` to answer that ONE question before
    continuing.* **Invariant conflict is a blocking gap:** if a requirement or acceptance
@@ -110,17 +139,31 @@ stay flat `[ACn]` bullets; the grammar is opt-in by rigor, never forced.
    surface it — the principle wins by default; breaking it needs a recorded, scoped exception a
    human approves, never a spec that silently contradicts an invariant.
 5. **Create the workspace** + set `.devrites/ACTIVE`
-   ([state-workspace](reference/state-workspace.md)). Write `spec.md`
-   ([spec-template](reference/spec-template.md)) — WHAT/WHY, technology-agnostic, with
-   **Placement & integration**, **Design references**, **Gaps/issues/decisions**, and
-   measurable acceptance ([acceptance-criteria](reference/acceptance-criteria.md)). For a
+   ([state-workspace](reference/state-workspace.md)). Write compact `README.md`,
+   `brief.md`, and `spec.md` ([spec-template](reference/spec-template.md)) — WHAT/WHY,
+   technology-agnostic, with requirements, acceptance, edge cases, scope boundaries, links
+   to future `architecture.md` / `traceability.md`, and measurable acceptance
+   ([acceptance-criteria](reference/acceptance-criteria.md)). For a
    behavioral / high-risk requirement, write the acceptance as a structured
    `### Requirement:` (SHALL) + `#### Scenario:` (WHEN/THEN) block per
-   [`spec-grammar.md`](../../rules/spec-grammar.md), nesting the `[ACn]` id inside each scenario
-   so `/rite-seal` still grades it; routine criteria stay flat `[ACn]` bullets. Also
+   [`spec-grammar.md`](../devrites-lib/reference/standards/spec-grammar.md), nesting the `AC-###` id inside each scenario
+   so `/rite-seal` still grades it; routine criteria stay flat `AC-###` bullets. **When a
+   capability the ledger already holds is changing, write those requirements as deltas** —
+   `## ADDED / MODIFIED / REMOVED Requirements — capability: <c>` (spec-grammar.md § Delta form) —
+   so the change, not just the end state, is explicit and `/rite-ship` folds it cleanly; a
+   capability with no ledger entry stays flat (the first sync seeds it). Also
    write `brief.md`, `references.md`, `questions.md`, `decisions.md`, `assumptions.md`,
-   and an initial `state.md` (phase: spec). When the feature touches UI, `design-brief.md`
-   is written here too (by `devrites-ux-shape`, step 3a).
+   and an initial compact `state.md` (phase: spec) from
+   [state-workspace](reference/state-workspace.md). When the feature touches
+   UI, `design-brief.md` is written here too (by `devrites-ux-shape`, step 3a).
+   Populate `## Edge Coverage` with the deterministic boundary classes implied by each requirement
+   (empty/huge input, rounding, timezone, ordering, permissions, races, migration) and `## Prohibitions (must-NOT)`
+   only for bespoke constraints. If the feature touches model calls, RAG, agents, evals, or LLM output,
+   also create `ai-spec.md` from [ai-spec-template](reference/ai-spec-template.md). Then refresh any
+   managed project context block so `AGENTS.md` / `CLAUDE.md` point at the new active workspace:
+   ```bash
+   devrites-engine context sync || true
+   ```
 5a. **Score the spec prose — "unit tests for English"** ([spec-checklists](reference/spec-checklists.md)).
    Emit `.devrites/work/<slug>/checklists/<domain>.md` (one per requirement domain the spec covers:
    functional · data-model · interaction · non-functional · edge-cases). Each tests the *requirement
@@ -130,40 +173,45 @@ stay flat `[ACn]` bullets; the grammar is opt-in by rigor, never forced.
 6. **Run the spec readiness gate** (bottom of spec-template): no blocking
    `[NEEDS CLARIFICATION]`, placement decided, all material gaps resolved, any design
    references provided are saved, **UX/UI shaped into `design-brief.md` if the feature is
-   UI**, requirements testable, success criteria measurable, **every `checklists/<domain>.md` at
+   UI**, requirements testable, success criteria measurable, **one-sentence intent** (the whole
+   change states its intent in a single sentence — if it can't, it is two features: split it or
+   narrow the scope), **every `checklists/<domain>.md` at
    `Verdict: pass`**, and **any structured requirement blocks are grammar-valid** — run
-   `spec-validate.sh` (resolved like the step-0 preamble), a non-zero exit is a blocking
-   failure to fix, not soften:
+   `devrites-engine spec-skeleton` first, then `devrites-engine spec-validate` with
+   `--against .devrites/specs` so any delta sections are also
+   reconciled against the ledger (an ADDED that already exists, or a MODIFIED/REMOVED that doesn't,
+   is a blocking failure to fix, not soften):
    ```bash
-   SV=.claude/skills/devrites-lib/scripts/spec-validate.sh
-   [ -f "$SV" ] || SV="${CLAUDE_SKILL_DIR:-}/../devrites-lib/scripts/spec-validate.sh"
-   [ -f "$SV" ] || SV=pack/.claude/skills/devrites-lib/scripts/spec-validate.sh
-   [ -f "$SV" ] && bash "$SV" ".devrites/work/<slug>" || echo "(spec-grammar validator unavailable — eyeball the Requirement/Scenario blocks)"
+   devrites-engine spec-skeleton ".devrites/work/<slug>"
+   devrites-engine spec-validate ".devrites/work/<slug>" --against .devrites/specs
    ```
-   When it passes, write `Spec gate: passed <iso>` to `state.md`. **Stop** when
-   it passes.
+   Treat edge/prohibition findings as blocking just like grammar findings. When it passes, write `Spec gate: passed <iso>` to `state.md`.
+6a. **Review-before-code digest.** Before handing off to planning, render the cheap human review:
+   `Intent` (one sentence), `Done means` (top acceptance/scenario IDs), `Scope/risk` (what is in/out
+   plus the hard gates), and `Build exactly this?` (yes → next phase; no → revise now). The digest
+   is a view over `spec.md`, not a new artifact. **Stop** after the digest.
 
 > **Mid-flight discipline.** When tempted to skip investigation depth, gap-closing, or placement decisions — see [`anti-patterns`](reference/anti-patterns.md) (Common Rationalizations + Red Flags). Load it the moment you reach for the excuse.
 
 ## Output
 
-**Footer first** — render the slice meter + flow ribbon by running the progress footer (`progress.sh`, resolved like the step-0 preamble — canonical snippet in `devrites-lib/SKILL.md`); keep the fact lines below it terse (`key value · key value`). Then:
+**Progress first** — run `devrites-engine progress`, then use the shared completion reply contract
+([`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md)).
+Default success shape:
 ```
-Spec ready: <slug>
-Objective: <one sentence>   Placement: <where it lives>
-Resolves: <value>
-References: <n saved | none provided>
-Design brief: <design-brief.md shaped (compact|full) | n/a — not UI>
-Gaps closed: <n>   Open (non-blocking): <n>
-Checklists: <n domains scored — all pass | BLOCKED: n CRITICAL open>
-Grammar: <n requirements / m scenarios — valid | n/a (flat acceptance)>
-Next: big / risky feature (auth · data model · public API · migration · multi-slice · ambiguous scope)?
-      → /rite-temper   (strategic review: scope mode + pre-mortem, hardens the spec) — then /rite-define.
-      Small / reversible / unambiguous? → /rite-define directly.
-↻ Hygiene: /clear before /rite-define (spec.md + references/ + decisions.md + assumptions.md + questions.md captured); /rite-handoff if away > a few hours. See rules/context-hygiene.md.
+Done: spec ready for <slug>; placement decided and gaps closed.
+Changed: spec.md, decisions.md, assumptions.md, questions.md, references/ <updated|n/a>
+Evidence: checklists passed; grammar <valid | n/a flat acceptance>; design brief <path | n/a>
+Open: <none | n non-blocking questions | Alternative: /rite-define for small reversible work>; review digest: intent + done-means + scope/risk rendered
+Next: /rite-temper
+Record: .devrites/work/<slug>/spec.md
+↻ Hygiene: /clear before the next phase; /rite-handoff if away > a few hours
 ```
 If a workspace with the slug already exists, update its spec rather than overwriting blindly —
 and **show the human a short diff of what changed** in `spec.md` (acceptance criteria added /
 removed / reworded) before proceeding. A spec edit reviewed as a diff catches silent scope
 drift that a full re-read buries; this is the spec-review view (`/rite-spec --review` renders
 just the diff + the open-question delta, no re-investigation).
+
+When the ask overlaps the ACTIVE feature (same intent, >50% scope), route to
+`/rite-plan revise` — its gate decides — rather than minting a parallel workspace.

package/pack/.claude/skills/rite-spec/reference/ai-spec-template.md

@@ -0,0 +1,33 @@
+# `ai-spec.md` template
+
+Create this annex only when the feature touches model calls, RAG, agents, evals,
+or LLM output.
+
+```markdown
+# AI-SPEC: <Feature>
+
+## AI surface
+| Surface | Purpose | Owner |
+| --- | --- | --- |
+| <model call/RAG/agent/eval> | <why it exists> | <module/team> |
+
+## Model/runtime choice
+- Framework/model/provider: <choice or project default>
+- Settings that matter: <temperature, tools, retrieval scope, limits>
+- Fallback/degradation: <what users see when AI is unavailable>
+
+## Domain evals
+| Eval ID | Scenario | Expected signal | Gate |
+| --- | --- | --- | --- |
+| EVAL-001 | <domain-specific case> | <pass condition> | build/seal |
+
+## Guardrails
+- Inputs: <validation, prompt-injection boundaries, tenant/data limits>
+- Outputs: <schema checks, refusals, human review, citations>
+- Privacy/security: <data sent to model, retention, secrets policy>
+
+## Monitoring
+- Runtime metrics/logs: <latency, cost, quality, refusal/error rates>
+- Alerts or manual review: <trigger>
+- Rollback/kill switch: <mechanism>
+```

package/pack/.claude/skills/rite-spec/reference/anti-patterns.md

@@ -4,7 +4,7 @@ Load this when standing a non-trivial decision in `/rite-spec`, or when the
 agent feels reluctance toward investigation depth, gap-closing, or
 placement decisions.
 
-Pack-wide rationalizations + red flags: see [rules/anti-patterns.md](../../../rules/anti-patterns.md).
+Pack-wide rationalizations + red flags: see [standards/anti-patterns.md](../../devrites-lib/reference/standards/anti-patterns.md).
 
 ## Phase-specific rationalizations
 
@@ -15,6 +15,8 @@ Pack-wide rationalizations + red flags: see [rules/anti-patterns.md](../../../ru
 | "Too small for a spec." | If it's big enough for `/rite-build`, it's big enough for one paragraph of WHAT/WHY + measurable acceptance. |
 | "No design refs were attached, so skip references." | Skip the *gathering*, not the *acknowledgement*. Note "no references provided" in the spec — silence is ambiguous. |
 | "I can resolve gaps as I build." | Drift discovered at slice 3 costs more than 5 questions answered now. |
+| "I'm confident of the answer, so I'll just decide this myself." | Confidence changes the *cost* of the question, not its *owner*. A material decision (scope · placement · data model · UX · security · migration · acceptance) is put to the human as a ranked option set — near-certainty just makes it a one-pick confirm, never a silent decision. |
+| "Presenting options for every gap is over-asking." | Over-asking is many questions at once or asking what the codebase answers. One ranked option set per *material* gap, recommended-first, is the opposite: it hands the human the decision cheaply. Reversible low-impact details you still auto-decide and log. |
 
 ## Red Flags
 
@@ -23,3 +25,4 @@ Pack-wide rationalizations + red flags: see [rules/anti-patterns.md](../../../ru
 - A `[NEEDS CLARIFICATION]` marker remains on a blocking item.
 - Design references were attached but never opened, saved, or indexed in `references.md`.
 - The investigation didn't read the module/component that currently owns this area.
+- A material decision landed in `spec.md` / `assumptions.md` that the human never picked from an option set — decided on the agent's confidence alone.

package/pack/.claude/skills/rite-spec/reference/investigation.md

@@ -6,10 +6,27 @@ requirement **completely**, decide **where it correctly belongs**, name what it
 the user so the spec ships fully-covered and correctly-placed. A gap found here is cheap;
 a gap found in `/rite-build` is a drift event.
 
-Use a code-intelligence index if available — codebase-memory-mcp first, cross-checked with codegraph + graphify, else standard methods (LSP / Read/Grep/Glob)
-(see `../../../rules/tooling.md`) — for the structural parts below; it answers "where does this
+Use a code-intelligence index if available (see
+`../../devrites-lib/reference/standards/tooling.md`) for the structural parts below; it answers "where does this
 live / what calls it / what would it break" far more cheaply and accurately than reading files.
-With none present, fall back to Read/Grep/Glob.
+With none present, fall back to Read/Grep/Glob. When a gap turns on a fact the codebase can't
+answer — a standard, a prevailing UX pattern, how comparable products solve it — **search the
+web if available** (brave MCP preferred; `../../devrites-lib/reference/standards/tooling.md`) and cite the finding in
+the option you present, so the human's pick is informed rather than guessed.
+
+## Prior art — check our own archive first (cheap, silent when empty)
+Before investigating outward, check whether we already shipped this. Grep the shipped
+archive for the feature's key nouns — a hit means an extension, a conflict, or a re-spec of
+solved work, and you inherit its decisions instead of re-deriving them:
+```bash
+devrites-engine archive-search "<key nouns>" 2>/dev/null \
+  || grep -rliE '<noun1>|<noun2>' .devrites/archive/*/spec.md 2>/dev/null
+```
+- **Overlap found** → read the overlapping `spec.md` + its `decisions.md`, then put it to
+  the human as a ranked option — *extend the shipped feature* · *this supersedes it* ·
+  *genuinely distinct* — same option-set contract as a gap.
+- **No archive / no hit** → skip silently; never block a spec on absent history (the
+  brownfield / principles no-op discipline).
 
 ## Produce these findings (write into spec.md)
 1. **The real ask** — restate the goal and the *problem behind the request* (people ask
@@ -41,24 +58,27 @@ State the **present state** and the **desired state**; the delta is the work, an
 **unknowns in the delta are the gaps**. Drive the count of open gaps toward zero before
 handing off to `/rite-define`. Mark each gap inline with `[NEEDS CLARIFICATION: question]`.
 
-## Turn gaps & issues into questions WITH options
+## Turn gaps & issues into questions WITH options — you recommend, the human decides
 For each material gap/issue (one that changes scope, placement, data model, UX, security,
-migration risk, or acceptance), ask the user — one question at a time, **best guess
-attached**, with structured options and an escape hatch:
+migration risk, or acceptance), **put it to the human** — one gap at a time, as a ranked
+option set with the recommended option **first and marked `(Recommended)`** plus an escape
+hatch (via `AskUserQuestion` in HITL):
 ```
 <gap/issue stated in one line>. Why it matters: <...>
-1. <option A> — <implication / where it places the work>
-2. <option B> — <implication>
-3. <option C> — <implication>
+1. <recommended option> (Recommended) — <implication / where it places the work; cite any web/docs finding>
+2. <alternative> — <implication>
+3. <alternative> — <implication>
 4. Something else — I'll describe it
-   (My best guess: #2, because <reason>.)
 ```
-Resolve material gaps before finalizing the spec. Reversible, low-impact gaps: decide,
-record in `assumptions.md`, and move on — don't interrogate.
+Investigate and recommend; don't settle a material decision yourself. Confidence in the answer
+lowers the *cost* of the question (a one-pick confirm), not its owner — present the set anyway.
+Only a **genuinely reversible, low-impact** gap is decided and recorded in `assumptions.md`
+without asking. Full render contract + AFK behaviour: [`afk-hitl.md`](../../devrites-lib/reference/standards/afk-hitl.md).
 
 ## Done when
+- The shipped archive was checked for prior art; any overlap was surfaced to the human.
 - The real problem, current behavior, placement, and what-it-resolves are written down.
-- Every issue has a disposition; every material gap is resolved (or explicitly deferred
-  as non-blocking).
+- Every issue has a disposition; every material gap is resolved **by a human pick** from its
+  option set (or explicitly deferred as non-blocking) — not settled silently on your confidence.
 - No blocking `[NEEDS CLARIFICATION]` remains — the spec is **fully covered and correctly
   placed**. This is the `/rite-spec` readiness gate before `/rite-define` plans it.

package/pack/.claude/skills/rite-spec/reference/question-protocol.md

@@ -1,41 +1,11 @@
-# Question protocol
+# Spec question protocol
 
-The discipline behind `/rite-spec` and `devrites-interview`.
+For vague or unknown intent, invoke `devrites-interview`; it owns question order,
+one-question turns, best guesses, option sets, blocking-question budget, reframing,
+and completion. The shared HITL/AFK rendering contract lives in
+[`afk-hitl.md` § Option set](../../devrites-lib/reference/standards/afk-hitl.md#option-set--how-every-gap-is-presented).
 
-## One question at a time
-Ask exactly one question per turn. Multiple questions at once get one answered and the
-rest ignored, and they signal you haven't prioritized.
-
-## Always attach your best guess
-Every question carries your current assumption and *why*:
-> "I'm assuming the export is CSV only (simplest, covers the stated use case). Right,
-> or do you need XLSX/PDF too?"
-This converts an open question into a cheap yes/no correction and reveals your model so
-the user can fix the premise, not just the question.
-
-## Highest-value question first
-Order by how much the answer changes the build. A question that changes the data model
-or acceptance criteria beats a cosmetic one. If two are equal, ask the one that unblocks
-the most downstream work.
-
-## Structured options when the space is enumerable
-```
-1. <option> — <what it implies for build/scope>
-2. <option> — <implication>
-3. <option> — <implication>
-4. Something else — I'll describe it
-```
-Always include the escape hatch (#4). Mark your recommended option.
-
-## Stop conditions (any one)
-- **Confidence** — you can predict the user's answer to the next question (~95%).
-- **Convergence** — the last 2–3 answers only rubber-stamped your guesses; the spec
-  stopped moving.
-- **Soft cap** — after ~8 material questions, proceed with best-guess answers logged as
-  assumptions (hard-stop sooner if the ask is small).
-
-If you keep circling one area without progress, **reframe once** — challenge the premise
-rather than asking again.
+This reference owns only the spec-specific coverage and recording rules below.
 
 ## Coverage gate — am I done asking?
 Before declaring the interview complete, each dimension is **resolved** or **explicitly
@@ -51,7 +21,7 @@ deferred** (logged, non-blocking) — never silently skipped:
 A blocking gap in any dimension keeps the interview open; a deferred one goes to
 `questions.md` and doesn't block. This feeds the `/rite-spec` readiness gate.
 
-## What NOT to ask
+## Spec question boundary
 - Things the codebase answers (read it first).
 - Reversible implementation details (decide and note as an assumption).
 - Everything at once "to be thorough." Thoroughness is depth on the few that matter.

package/pack/.claude/skills/rite-spec/reference/references-intake.md

@@ -1,12 +1,9 @@
 # Reference intake — design/style materials from the human
 
-During the spec phase the human **may** hand you **how it should look or behave**:
-screenshots, mockups, a Figma link, a video of a flow, a reference site, or a doc — **or
-nothing at all** (no design, no screenshots, no explanation is perfectly normal). This is
-entirely **optional**. When references *are* given, treat them as first-class inputs:
-gather them, understand them, **save the local ones**, and index them so every later phase
-(build, prove, polish, seal) can check the work against them. When there are none, skip
-this and proceed with the spec.
+During spec, the human may supply screenshots, Figma, video, sites, or docs showing how the
+feature should look or behave. When present, inspect them, save local copies, and classify
+each as a fidelity **target**, hard **constraint**, or **inspiration** so a mood reference
+cannot become a pixel-match contract. No references is valid; skip this intake.
 
 ## Gather + understand each reference
 - **Images / screenshots / mockups** — open and **view** them (the Read tool renders
@@ -28,30 +25,38 @@ cp "<the file the human gave>" .devrites/work/<slug>/references/<clear-name>.<ex
 ```
 Use clear names (`login-mockup.png`, `checkout-flow.mp4`). Don't move the user's
 original; copy it. For remote-only refs (a live Figma/URL), record the link in the index.
+Index source/owner/license and **reference-only** or **may ship** usage; external screenshots
+never grant rights to copy brand, copy, or assets.
 
 ## Index in `references.md`
 ```markdown
 # References: <slug>
-| Ref | Type | Location | Shows / why it's a reference | Informs |
-|-----|------|----------|------------------------------|---------|
-| R1 | screenshot | references/login-mockup.png | target login layout + spacing | spec UI, slice 2, polish |
-| R2 | figma | https://figma.com/… (+ export references/tokens.png) | design tokens, component set | all UI |
-| R3 | video | references/checkout-flow.mp4 | expected step order + transitions | build, prove |
-| R4 | link | https://example.com | tone + density to match | craft |
+| Ref | Role | Usage / provenance | Type | Location | Shows / why it's a reference | Informs |
+|-----|------|--------------------|------|----------|------------------------------|---------|
+| R1 | target | project; may ship | screenshot | references/login-mockup.png | approved composition + spacing | spec UI, slice 2, proof |
+| R2 | constraint | project; may ship | figma | https://figma.com/… | required tokens + components | all UI |
+| R3 | target | user; reference-only | video | references/checkout-flow.mp4 | approved step order + transitions | build, proof |
+| R4 | inspiration | external; reference-only | link | https://example.com | tone + density, not identity/layout | shape |
 ```
 
+Roles are normative: **target** means compare fidelity, **constraint** means satisfy the
+named rule, and **inspiration** means extract the cited principle without copying identity,
+composition, copy, or distinctive assets. Usage is normative too: only **may ship** assets
+enter product code.
+
 ## Feed them into the spec + the design brief
 - Use references to sharpen `spec.md` (UI impact, success/acceptance — e.g. "matches R1").
 - When the feature touches UI, these references are the primary input to **`devrites-ux-shape`**
   (spec step 3a): they anchor the design direction and can seed the visual-direction probe
   (a Figma link → pulled design context; reference sites → screenshots). The resulting
-  `design-brief.md` cites them by R-id.
+  `design-brief.md` cites them by R-id **and role**.
 - A reference can *resolve a gap* ("which layout?") — record that in the gaps table.
 - If a reference **conflicts** with the existing design system, that's an issue to raise
   with the human (match the system, or adopt the reference — their call).
 
 ## Later phases use them (wire-through)
-`devrites-frontend-craft` builds **to** the references; `/rite-polish` compares the built
-UI **against** them; `/rite-prove` / `browser-evidence.md` verify against them; `/rite-seal`
-checks "matches the agreed design references" as acceptance. So save them once here and
-everything downstream can connect to them.
+`devrites-frontend-craft` builds to the approved brief and its **target** references,
+honors **constraints**, and uses **inspiration** only for the named principle. `/rite-prove`
+records rendered comparisons in `browser-evidence.md`; `/rite-polish` and `/rite-seal`
+reuse that same contract. Save and classify once here so every downstream phase makes the
+same fidelity decision.