devrites 2.6.1 → 3.0.0

package/pack/generated/codex/skills/rite-ship/reference/git-ship.md

@@ -0,0 +1,73 @@
+# The irreversible ship — type-GO + git ladder
+
+`$rite-ship` is the only DevRites phase that runs actions that cannot be undone
+silently. The seal verdict authorizes the *decision*; this prompt authorizes the
+*action*.
+
+## The type-GO prompt (render verbatim, wait)
+
+```
+About to: <git commit + git push [+ git tag vX.Y.Z | open PR]>
+Feature:  <slug>
+Verdict:  GO  (seal.md)
+Acceptance criteria proven: <n / total>
+Branch:   <target branch>
+
+Type "GO" exactly to proceed. Anything else cancels.
+```
+
+Rules for the prompt:
+- Render it **every time**, even with auto-trigger enabled — this is the last net.
+- Only the literal string `GO` (no quotes) proceeds. `y`, `yes`, `go` (lowercase),
+  `ok`, `sure`, `do it`, or anything else → cancel, record the cancel in `ship.md`
+  as "user declined irreversible step at <ts>", and stop.
+- `$rite-autocomplete --ship` (or `--yolo`) is the *only* caller permitted to satisfy
+  this prompt automatically. Every other path requires the human's literal `GO`.
+
+## The git ladder
+
+Follow `.agents/skills/devrites-lib/reference/standards/git-workflow.md` and the project's own convention. Do not invent
+a release flow the project doesn't use.
+
+0. **Collapse checkpoints** (only if checkpoint mode ran — see
+   [rite-build/reference/checkpoint.md](../../rite-build/reference/checkpoint.md)). Local
+   `WIP(<slug>)` commits are scratch; fold them into the working tree so the ship is one
+   atomic feature commit. `reset --soft` moves only the branch pointer — index and worktree
+   are untouched, so no change is ever lost:
+   ```bash
+   base=$(git rev-parse --abbrev-ref '@{upstream}' 2>/dev/null) || base=main
+   mb=$(git merge-base HEAD "$base" 2>/dev/null)
+   if [ -n "$mb" ] && git log --format='%s' "$mb..HEAD" | grep -q '^WIP('; then
+     git log --format='%s' "$mb..HEAD" | grep -qv '^WIP(' \
+       && echo "history since $base mixes WIP + real commits — surface and confirm before collapsing" \
+       || git reset --soft "$mb"   # fold every WIP commit since the branch point → staged
+   fi
+   ```
+   No WIP commits (checkpoint mode was off) → this is a silent no-op.
+1. **Stage** only the files in `touched-files.md`. Never `git add -A`; never stage
+   secrets, `.env`, or out-of-scope files (see the never-commit list in `git-workflow.md`).
+2. **Commit** with a Conventional Commit message derived from the feature (`feat(scope):
+   …` / `fix(scope): …`). Atomic — one logical change. Put the *why* in the body.
+   For non-trivial features, append trailers from the workspace record:
+   `Constraint:` from binding principles/irreversible risks, `Rejected:` from material alternatives,
+   `Confidence:` from `seal.md`, `Scope-risk:` from the blast-radius scan, and `Not-tested:` for
+   known proof gaps. Skip trailers for typos and pure formatting.
+3. **Push** to the target branch (the feature branch, or per the project's trunk
+   convention).
+4. **Tag / PR** only if the project does it: cut a tag when the project tags releases,
+   or open a PR when the project reviews via PRs. Otherwise skip — pushing the branch
+   is the ship.
+
+Capture the resulting commit SHA(s), branch, and tag/PR URL for `ship.md`.
+
+## Pull request body
+
+When this ship opens a PR, include only applicable sections:
+
+- **Summary** — what shipped and acceptance proven.
+- **Risk & rollback** — migration/auth/destructive risk and reversal from `seal.md`.
+- **What to scrutinize** — highest-blast-radius review stops.
+- **Evidence** — condensed proof plus the archived evidence bundle.
+
+For an agent-owned staged rollout, apply [`rollout.md`](rollout.md). CI-owned deploys
+skip that branch. Delete empty sections rather than writing `N/A`.

package/pack/generated/codex/skills/rite-ship/reference/ledger.md

@@ -0,0 +1,56 @@
+# Capability ledger — the living "what the system does now" layer
+
+The ledger is DevRites' cumulative spec store: `.devrites/specs/<capability>/spec.md`, a flat
+list of proven `### Requirement:` blocks per capability. Unlike a feature workspace — which is
+archived away on close — the ledger **persists** and accumulates, so feature N+1 starts from the
+proven contract of every feature before it instead of re-deriving from code.
+
+It lives outside `.devrites/work/`, so close-out's archival never touches it. It is written only
+here, on ship, and only from behavior that just passed the seal GO + evidence-freshness gate — so
+the ledger records *proven* truth, never merely proposed.
+
+## Fold semantics
+
+A feature's `spec.md` carries **deltas** grouped under capability-tagged H2 sections
+(`## ADDED Requirements — capability: <c>`, `MODIFIED`, `REMOVED`) — see
+[`spec-grammar.md`](../../devrites-lib/reference/standards/spec-grammar.md) § Delta form.
+`devrites-engine ledger sync` groups them by capability and folds each into its ledger spec:
+
+- **ADDED** → append the block (upsert: replaces in place on a re-sync, so sync is idempotent)
+- **MODIFIED** → replace the same-named block with the full new version
+- **REMOVED** → delete the block (an emptied capability spec is dropped)
+
+Matching is by **requirement header identity**. A flat feature spec (no delta H2 sections) folds
+as all-ADDED into the capability named by the feature slug.
+
+## Sync workflow (rite-ship step 2b)
+
+Runs **before the commit** so the ledger change ships in the same commit as the code that proves it.
+
+1. Preview the fold — deterministic, zero-token:
+   ```bash
+   devrites-engine ledger diff .devrites/work/<slug>
+   ```
+2. **Opt-in and confirmed** (mirrors the design-memory rollup): present the option set — default
+   is to sync, since a shipped feature's proven behavior belongs in the ledger; the escape hatch
+   is skip (the feature ships without updating the living spec — a deliberate call, e.g. an
+   internal-only change with no capability contract).
+3. On yes:
+   ```bash
+   devrites-engine ledger sync .devrites/work/<slug>
+   ```
+   Then append each written `.devrites/specs/<capability>/spec.md` to `touched-files.md` so it is
+   staged and committed at the git ladder (step 4). Record the synced capabilities in `ship.md`.
+   **The ledger must be git-tracked.** Most of `.devrites/` is runtime state a project gitignores;
+   `specs/` is the exception (durable shared truth). If a `git status` / `git check-ignore` shows
+   the ledger path ignored, the commit would silently drop it — carve it out first:
+   `.devrites/*` + `!.devrites/specs/`. Surface this rather than shipping a ledger that never lands.
+4. Skip when the feature declares no requirements (a pure refactor / chore with no spec deltas).
+
+## Reading the ledger (earlier phases)
+
+`$rite-spec` and `$rite-adopt` consult the ledger before writing a new spec:
+```bash
+devrites-engine ledger list            # capabilities + requirement counts
+devrites-engine ledger show <capability>   # the proven contract to write deltas against
+```

package/pack/generated/codex/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/generated/codex/skills/rite-ship/reference/ship-template.md

@@ -0,0 +1,33 @@
+# `ship.md` template
+
+The durable record of what shipped and how. Written by `$rite-ship` into the
+workspace **before** close-out, so it travels into `.devrites/archive/<slug>/ship.md`.
+
+```markdown
+# Ship: <slug>
+
+- Shipped at: <iso>
+- Verdict: GO (see seal.md)
+- Branch: <branch>
+- Commit(s): <sha> [<sha> …]
+- Tag / PR: <vX.Y.Z | PR url | none>
+
+## What shipped
+<one-paragraph summary of the feature delivered, in the project's vocabulary>
+
+## Acceptance
+- Criteria proven: <n / total>   (full walk in evidence.md / seal.md)
+- Outstanding (shipped with known follow-ups): <list | none>
+
+## Evidence pointers
+- seal.md — final GO/NO-GO verdict + reviewer reconciliation
+- evidence.md — acceptance walk; browser-evidence.md (if UI)
+- review.md — multi-axis review findings
+
+## Follow-ups (FYI, not blocking)
+- <recorded follow-up + where it's tracked> | none
+```
+
+Keep it short — it points at the existing audit files rather than restating them.
+The acceptance count must match `seal.md`; if they disagree, the seal is the source of
+truth and the ship should not have proceeded.

package/pack/generated/codex/skills/rite-spec/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: rite-spec
+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
+---
+
+## 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-spec — investigate deeply, write the spec
+
+The spec phase. Turn a request (even a vague one) into a **fully-covered, correctly-placed
+`spec.md`** by investigating deeply and closing every material gap with the human — so
+`$rite-define` can plan it and nothing is missed. **No plan, tasks, or code here** — those
+are `$rite-define` and `$rite-build`.
+
+> **Too small to spec? Use `$rite-quick`.** A typo, copy tweak, config bump, or one-function
+> fix does **not** need a full workspace + lifecycle. Stop and run `$rite-quick <change>` — its
+> express lane (one contract → TDD build → scoped prove → ship) escalates back here the moment
+> 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 `.agents/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` 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 `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 `.agents/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`, `.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
+   principles, so this feature is specced on top of an onboarded project (adopt owns the
+   onboarding; `$rite-spec` only detects and routes — no duplicated logic). In **HITL** present a
+   ranked option (recommended: *adopt first, then spec this on top*; escape hatch: *spec-only, skip
+   onboarding*); in **AFK** (adoption allowed) run `$rite-adopt` first automatically. **Greenfield
+   (no pre-existing source) or an already-onboarded project → skip silently** — never block a spec
+   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 .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 —
+   callers, dependents, data, APIs/events); **what it resolves**; **issues**
+   (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 `.agents/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. 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 `.agents/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` 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
+   references + the spec into a feature-level **`design-brief.md`** (design direction, key
+   states, interaction model, optional Figma/image visual-direction probe) that `$rite-build`
+   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 — 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
+   criterion can only be satisfied by breaking a declared principle (`.devrites/principles.md`),
+   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 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`](../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 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
+   prose* for completeness / clarity / measurability — "is 'prominent' quantified?", "is every
+   enumeration closed?" — **not** the implementation. Fix each CRITICAL fail by editing the spec
+   (not by softening the question); minor fails are logged. The checklists feed the readiness gate.
+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, **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
+   `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
+   devrites-engine spec-skeleton ".devrites/work/<slug>"
+   devrites-engine spec-validate ".devrites/work/<slug>" --against .devrites/specs
+   ```
+   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
+
+**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:
+```
+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/generated/codex/skills/rite-spec/reference/acceptance-criteria.md

@@ -0,0 +1,31 @@
+# Acceptance criteria
+
+Acceptance criteria are the contract the seal checks. Write them so each is
+**independently verifiable by evidence**, not opinion.
+
+## A good criterion
+- Is observable: a test passes, a command outputs X, a screenshot shows Y.
+- Is binary: met or not — no "mostly".
+- Names the evidence: "`npm test path/x.test.ts` passes" or "POST /export returns 200
+  with a CSV body" or "empty state renders 'No exports yet' at 375px".
+- Belongs to a slice: every criterion maps to at least one slice (mapped in `$rite-define`).
+
+## Forms
+| Type | Template |
+|---|---|
+| Functional | "Given <state>, when <action>, then <observable result>." |
+| API | "<METHOD> <route> with <input> returns <status> and <shape>." |
+| UI | "<screen> shows <element/state> at <viewport>; <interaction> does <result>." |
+| UI vs reference | "<screen> matches design reference <Rn> at <viewport>." |
+| Non-functional | "<operation> completes under <budget> / handles <volume>." |
+| Negative | "<invalid input> is rejected with <message>, no <side effect>." |
+
+## Anti-patterns
+- "Works well" / "is fast" / "looks good" — unverifiable. Attach a number or an
+  observation.
+- Criteria with no slice — orphaned scope.
+- Criteria only provable by reading the code — require runtime/test evidence instead.
+
+## At seal time
+Each criterion gets a checkbox + the evidence that proves it. Unproven critical
+criteria force **NO-GO**.

package/pack/generated/codex/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/generated/codex/skills/rite-spec/reference/anti-patterns.md

@@ -0,0 +1,28 @@
+# rite-spec — anti-patterns
+
+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 [standards/anti-patterns.md](../../devrites-lib/reference/standards/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "User said *just make it work* — no spec needed." | Vague asks are exactly where `$rite-spec` earns its keep; load `devrites-interview` and ask one question at a time. |
+| "I already understand the request." | Then writing the placement + acceptance criteria takes minutes and saves drift later. Investigation isn't for *you*, it's for `$rite-define`. |
+| "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
+
+- About to start writing `spec.md` without a Placement & integration section.
+- Spec has no measurable acceptance criteria — "works as expected" is not measurable.
+- 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/generated/codex/skills/rite-spec/reference/interview-patterns.md

@@ -0,0 +1,56 @@
+# Interview patterns
+
+Question ladders by domain. Pull the rung that matches the biggest current unknown.
+Each question still follows the protocol: one at a time, best guess attached.
+
+## Vague ask? Map the decision tree first
+For a fuzzy one-liner (`"design a contact page"`, `"add reporting"`), sketch the branches
+the answer splits into, then resolve each **depth-first** — one branch to a decision before
+opening the next:
+
+```text
+contact page
+├─ purpose?   ── sales lead | support request | general
+├─ fields?    ── name/email/message | + company/phone | file upload
+├─ on submit? ── email | ticket/CRM | DB row | embedded third-party form
+└─ success?   ── inline confirm | redirect | autoresponder
+```
+
+Once per interview you may **challenge the premise** instead of refining it
+(*"is a form even the right answer, or a mailto / booking link?"*) — a good reframe
+collapses whole branches. Then use the domain ladders below for each open branch.
+
+## Objective / problem
+- "What does success look like in one sentence?"
+- "Who hits this, how often, and what do they do today instead?"
+- "If we shipped only one thing here, what must it be?"
+
+## Scope boundaries
+- "What is explicitly **out** of scope for this first version?"
+- "Is this a new capability or a change to an existing flow?"
+- "What's the smallest version that's still useful?" (→ slice 1)
+
+## Data model
+- "What are the core entities and how do they relate?"
+- "What's the source of truth, and can these fields change after creation?"
+- "Any uniqueness, ordering, or soft-delete needs?"
+
+## UX / flow
+- "Walk me through the happy path screen by screen."
+- "What are the empty / loading / error / permission-denied states?"
+- "Brand surface (marketing) or product surface (app UI)?" (drives craft)
+
+## Integration / external
+- "Which external systems or APIs are involved, and who owns them?"
+- "Sync or async? What happens when the dependency is down?"
+
+## Non-functional
+- "Any latency, scale, or volume targets I should design to?"
+- "Auth/permission rules? Anything sensitive (PII, secrets, payments)?"
+
+## Acceptance
+- "How will we *prove* this works — what's the test or observation?"
+- "What would make you reject the PR?"
+
+## Anti-references (taste)
+- "Show me one thing that does this well, and one that does it badly."