devrites 2.6.1 → 3.0.0

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

@@ -0,0 +1,121 @@
+---
+name: rite-resolve
+description: User-invoked resume verb for answering, dropping, or batch-resolving open `questions.md` gates.
+argument-hint: "<qid> \"<answer>\"  |  --drop <qid> [\"<reason>\"]  |  --batch <path-to-yaml>"
+user-invocable: true
+disable-model-invocation: 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-resolve — answer the human gate
+
+`$rite-resolve` is the canonical resume verb for **async** human gates — a checkpoint that
+already paused and **stopped the session** (an AFK blocking/escalating/irreversible queue, or a
+HITL pause the human walked away from), plus `--batch`. When `$rite-build` asks a gap **inline**
+via `AskUserQuestion` and the human is present, that pick resolves the gate **in place** through
+the same `devrites-engine resolve` writer — you don't type `$rite-resolve` for it. For the async case this
+skill takes the human's answer (or `--drop` / `--batch`), writes it to `questions.md`, updates
+`state.md` (clears `Awaiting human`, sets `Status: running`), and recommends the next command.
+
+It is **deliberately small**: one verb, one source of truth (`questions.md`), one cursor
+(`state.md`). The full AFK / HITL contract lives in
+[`afk-hitl.md`](../devrites-lib/reference/standards/afk-hitl.md).
+
+## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
+
+Pull these via `Read` when shaping the resolve:
+
+- `afk-hitl.md` — gate taxonomy, `questions.md` schema, AFK exception rules.
+- `documentation.md` — record decisions and rationale where the answer changes scope.
+
+## Operating rules
+
+- **Requires an active workspace.** Read `.devrites/ACTIVE` first; if empty or the slug
+  has no `questions.md`, **STOP** and tell the user to run `$rite-spec <feature>` first.
+- **One mutation per call.** A single qid (or `--batch` file) per invocation; never
+  silently coalesce multiple human decisions into one log entry.
+- **Never overwrite an answered question.** If the qid's `status` is `answered` or
+  `dropped`, refuse with the existing answer; ask the user to open a new qid that
+  references the old one (the file is the audit trail).
+- **If the answer materially changes scope, architecture, or acceptance**, route it
+  through the Spec Drift Guard (`$rite-plan repair`) **after** writing the answer — do
+  not modify `spec.md` / `plan.md` inside this skill.
+- **The script is the source of truth.** Always invoke
+  `devrites-engine resolve` — it keeps `questions.md` + `state.md` consistent and emits the
+  next-action recommendation. The one `state.md` field this skill may write by hand is the
+  unblocked slice's `Slice mode` (step 4, the named exception); everything else goes through
+  the script, never by hand.
+- **Human gates are for human-only decisions, not the agent's work.** A `questions.md` entry the
+  human must answer is a genuine *decision* (a scope / design / risk call only the human can make)
+  — not a task the agent can do itself. If a question is really agent-doable ("should I write the
+  test?", "go implement X"), don't record a human answer that punts the agent's own job back to it:
+  flag the mis-tag and route it to the right skill (`$rite-build`, `$rite-plan unblock`,
+  `devrites-debug-recovery`). The human resolves decisions; the agent does the work.
+
+## Workflow
+
+0. **Read `.agents/skills/devrites-lib/reference/standards/core.md`** (operating rules + persistence discipline) before
+   touching the workspace.
+   Then run `devrites-engine preamble` for deterministic workspace orientation.
+1. **Parse arguments.** `$ARGUMENTS` is one of:
+   - `<qid> "<answer>"` — answer the single open question.
+   - `--drop <qid>` (optional `"<reason>"`) — mark the question `dropped`; record
+     the reason inline.
+   - `--batch <path-to-yaml>` — bulk resolve, one entry per qid (see
+     [`reference/answer-protocol.md`](reference/answer-protocol.md) for the batch
+     format).
+2. **Load context.** Read `state.md`, `questions.md`, and the relevant slice from
+   `tasks.md`. Confirm the qid is `status: open`. If `state.md` `Status` is not
+   `awaiting_human` and the question's `gate` is `blocking`, surface the inconsistency
+   before proceeding (don't auto-repair — flag it).
+3. **Render preview.** Echo the qid, the question, the proposed answer (if any), the
+   user's answer, and which slice unblocks. Stop here and ask `confirm? (y/N)` **unless**
+   the answer was provided non-interactively via `--batch`.
+4. **Mutate.** Run `devrites-engine resolve` with the same
+   arguments. The script:
+   - flips the qid's `status` to `answered` / `dropped` and stamps `answered_at` + `answer`;
+   - if the qid is in `state.md`'s `Awaiting human` block (single-question pause), clears
+     that block and sets `Status: running`;
+   - appends a `Log` line to `state.md`.
+
+   On resume, also clear or update the unblocked slice's `Slice mode` in `state.md`: if
+   the answer lets the slice proceed, drop the pause-time `Slice mode` so `$rite-build`
+   re-derives it on the next selection; if the answer re-shapes how the slice should be
+   built, set `Slice mode` to match.
+5. **Post-resolve hand-off.** If the answer changes product behavior or acceptance →
+   recommend `$rite-plan repair`. Otherwise → recommend the slice's natural next action
+   (typically `$rite-build` for the slice that was awaiting).
+   **Completion:** the resolved state contains exactly one next command.
+6. **STOP.** This skill does not run `$rite-build` itself — the user re-enters the
+   workflow explicitly.
+
+> **Mid-flight discipline.** Don't edit `spec.md` / `plan.md` to "incorporate" the
+> answer — that's `$rite-plan repair`. Don't silently retry a build after the answer
+> lands — the user types the next command. Don't merge two open questions into one
+> answered entry — each question is independently auditable.
+
+## 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: resolved <qid> for <gate> at <slice/phase>.
+Changed: questions.md, state.md, decisions.md <updated|n/a>
+Evidence: not applicable; answer persisted before resume
+Open: <none | remaining questions | plan repair needed>
+Next: <single recommended command>
+Record: .devrites/work/<slug>/questions.md
+↻ Hygiene: no /clear needed; the answer is persisted
+```

package/pack/generated/codex/skills/rite-resolve/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false

package/pack/generated/codex/skills/rite-resolve/reference/answer-protocol.md

@@ -0,0 +1,115 @@
+# Answer protocol — how `$rite-resolve` mutates the workspace
+
+`$rite-resolve` is the single canonical writer for `questions.md` `status` flips and
+`state.md` `Awaiting human` clearance. This file is the reference for the three input
+shapes, the batch file format, and the rules the underlying `devrites-engine resolve` obeys.
+
+## Three input shapes
+
+### 1. Single answer
+
+```
+$rite-resolve q-2026-05-28-001 "composite index — single key is fine for now, revisit at 1M rows"
+```
+
+- The qid must be `status: open`. Re-answering is refused (see "Never overwrite").
+- The answer is recorded verbatim. Use straight quotes around the answer so the shell
+  preserves whitespace.
+
+### 2. Drop
+
+```
+$rite-resolve --drop q-2026-05-28-002 "merged into q-...-003 after we narrowed the scope"
+```
+
+- A drop is **not** an answer — it removes the question from the active queue without
+  recording a decision. Use it when the question is obsolete, a duplicate, or absorbed
+  by a re-plan.
+- The reason is an optional single trailing string, **strongly recommended** for the
+  audit trail. "obsolete" / "duplicate" / "absorbed by Slice N" are sufficient; if omitted,
+  `devrites-engine resolve` records the reason as `dropped`.
+
+### 3. Batch
+
+```
+$rite-resolve --batch .devrites/work/<slug>/answers.batch
+```
+
+The batch file is plain text, one resolution per line. Two line shapes:
+
+```
+q-2026-05-28-001: composite index, revisit at 1M rows
+q-2026-05-28-002: clinician sign-off required at runtime, not at plan time
+--drop q-2026-05-28-003: merged into q-...-004
+# Lines starting with # are comments. Blank lines ignored.
+```
+
+- One qid per line. The first colon is the separator; the rest of the line is the value.
+- Order matters only for `state.md` clearance — the script processes top-to-bottom and
+  flushes `Awaiting human` after each match.
+- Errors abort the batch at the first failing line so partial state is small and
+  diagnosable. (Re-run after fixing the offending line; already-applied lines refuse to
+  re-apply because their `status` is no longer `open`.)
+
+## Never overwrite
+
+A qid that is already `answered` or `dropped` refuses to be re-resolved. The audit trail
+is the file — you do not edit history. If the original answer was wrong:
+
+1. Open a new qid (the agent will, during the next `$rite-build` if the bad answer
+   re-surfaces; or you write it manually).
+2. Reference the old qid in the new question's body (`supersedes: q-...-001`).
+3. Resolve the new qid.
+
+The same rule applies to `--drop`: a dropped question is not undropped. Re-raise it as
+a new qid if it turns out to matter after all.
+
+## State machine
+
+```
+open ──answer──▶ answered  (terminal)
+ │
+ └──drop────▶ dropped   (terminal)
+```
+
+Both terminals stamp `answered_at: <iso>` and write the answer/reason to `answer:`.
+
+## `state.md` clearance rules
+
+`state.md`'s `Awaiting human` block is **single-question by default** — `$rite-build`
+writes one block at a time and pauses. When `$rite-resolve` matches the block's qid:
+
+- the entire `Awaiting human` block is removed (header + fields);
+- `- Status: running` is set;
+- a `Log` line is appended: `- <iso> build: resolved <qid>`.
+
+If `state.md`'s `Status` is `awaiting_human` but no `Awaiting human` block matches the
+qid (drift between the two files), `$rite-resolve` flags the inconsistency and refuses
+to silently fix it. Use `$rite-plan repair` to reconcile.
+
+If the answer materially changes spec/plan, **do not** edit `spec.md` or `plan.md` inside
+`$rite-resolve` — that's `$rite-plan repair`'s job. The skill's post-resolve hand-off
+recommends `$rite-plan repair` whenever the answer touches acceptance criteria, scope,
+or architecture.
+
+## Multi-question awaiting
+
+If a future evolution lets `$rite-build` queue multiple questions per pause, the
+`Awaiting human` block becomes a YAML list. `$rite-resolve` will:
+
+- match the qid in the list and remove only that entry;
+- leave the rest of the list intact;
+- flip `Status: running` only when the list is empty.
+
+This shape is reserved — current `$rite-build` writes one question per pause.
+
+## Why no auto-`$rite-build` after resolve
+
+The user types the next command explicitly. Reasons:
+
+1. The answer may need a `$rite-plan repair` first; auto-continuing would build against
+   a stale plan.
+2. The user may want to `$rite-status` before resuming.
+3. Atomicity: one verb, one mutation. Chaining is a hidden side-effect that hides bugs.
+
+The output's `Next:` line is a recommendation, not an auto-run.

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

@@ -0,0 +1,183 @@
+---
+name: rite-review
+description: Review polished feature diff for correctness, readability, architecture, security, tests proving acceptance, Critical/Important findings, and quality dimensions before seal.
+argument-hint: "[scope: slice N | feature] [--full]"
+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-review — feature-scoped review
+
+Senior review of the **active feature scope only**. **Read the active workspace first**;
+if none, tell the user to run `$rite-spec <feature>`.
+
+> **Differs from built-in `/code-review` in:** `/code-review` is a generic
+> diff review with no workspace context. `$rite-review` reads
+> `.devrites/work/<slug>/spec.md` first, runs Spec ↔ Code-review axes as
+> parallel subagents (see [`parallel-dispatch.md`](../devrites-lib/reference/parallel-dispatch.md)), and gates feeding
+> into `$rite-seal`. Use `/code-review` for a one-off diff; use
+> `$rite-review` for a DevRites feature where the spec is the contract.
+
+## Rules consulted (read on demand from `.agents/skills/devrites-lib/reference/standards/`)
+Pull these via `Read` when the diff demands them:
+- `code-review.md` — small PRs, severity labels, tests-first review focus.
+- `review-checklist.md` — compact pass/fail sweep before reporting the verdict.
+- `principles.md` — declared project invariants (`.devrites/principles.md`); a diff that violates one with no recorded exception is a Critical, blocking finding.
+- `testing.md` — confirm the tests prove the spec, not just pass.
+- `agents.md` — when to fan out to which review subagent.
+- `security.md` — when input / auth / data / integrations / secrets are in scope.
+- `security-checklist.md` — for the same security-sensitive scope, the compact trust-boundary sweep.
+- `performance.md` — only when perf is relevant or a regression risk is visible.
+
+## Operating rules
+- **Feature scope only.** Review touched files + the diff. **NO whole-project refactors,
+  NO drive-by cleanup.** DO NOT delete suspected dead code outside this feature without
+  asking. Spec Drift Guard applies.
+- **Reviews the finished product.** `$rite-polish` has already done **code simplification**
+  + UI normalize/polish. Review judges; if it reveals a real complexity issue polish
+  missed, flag it as a finding — don't re-run a simplification sweep here.
+- Findings are labeled (below). Re-prove after any change you make.
+
+## Workflow
+0. Read `.agents/skills/devrites-lib/reference/standards/core.md` first (the always-on operating rules); pull the
+   on-demand rules above as the diff demands them.
+   Then run `devrites-engine preamble` for deterministic workspace orientation.
+1. Read `spec.md`, `tasks.md`, `state.md`, `decisions.md`, `evidence.md`,
+   `touched-files.md`, `.devrites/principles.md` (if present — the binding invariants to score
+   the diff against), and the `git diff`. For "what would this change break"
+   questions, prefer a code-intelligence index if available — codebase-memory-mcp first,
+   cross-checked with codegraph + graphify, else standard methods (LSP / Read/Grep/Glob); see
+   `.agents/skills/devrites-lib/reference/standards/tooling.md` — over file reads;
+   they answer impact/callers in one call. When a finding hinges on an external library's
+   current API, context7 if available can confirm the signature.
+2. **Review tests first** — do they actually prove the acceptance criteria? Missing,
+   weak, or wrong tests are the first findings.
+   **Completion:** every acceptance criterion maps to a proven test or a labeled finding.
+3. **Spec ↔ Code-review split (parallel sub-agents, fresh context).** A change can pass
+   one axis and fail the other — code that follows every project standard but
+   implements the wrong thing (Code-review pass, Spec fail), or code that does exactly
+   what the spec asked but breaks project conventions (Spec pass, Code-review fail).
+   Running them serially in one context lets one mask the other. So:
+   - Dispatch **two** read-only reviewers in **parallel** via the `Task` tool, each
+     with its own narrow brief and no cross-pollination:
+     - **Spec axis** → `devrites-spec-reviewer`: "Apply your documented discipline on
+       the active feature workspace + diff. Report (a) criteria the spec asked for that
+       are missing or partial, (b) behaviour in the diff the spec did not ask for
+       (scope creep / drift), (c) criteria implemented incorrectly. Quote the spec
+       line per finding. If the spec is missing or unreadable, report `Review gap:
+       missing spec` and do not infer requirements from the diff."
+     - **Code-review axis** → `devrites-code-reviewer`: "Apply your full documented
+       discipline (tests-first, correctness, readability, architecture, maintainability,
+       standards) on the active feature workspace + diff. Cite file:line per finding;
+       skip what tooling already enforces. Also flag the AI-codegen smells (silent/empty
+       catch, defensive try-catch bloat + redundant logging, single-use factory / needless
+       indirection, dependency creep where an in-repo option exists, a 100-line function
+       where 20 would do) and the silent-failure bugs (a missing value coerced to 0/''/[],
+       a dropped Result/err return, off-by-one / boundary, logic that contradicts the
+       comment/docstring/name). Per hunk, check whether working code was deleted that the
+       task did not ask to remove. Score the diff against `.devrites/principles.md` — a change
+       that breaks a declared invariant with no recorded, human-approved exception is a Critical.
+       Distinguish hard documented-standard violations from baseline smells; smells are judgment
+       calls unless a DevRites or project standard makes them binding."
+   - **Do NOT merge or re-rank** their findings. Present them under separate
+     `## Spec` and `## Code review` sub-sections in `review.md`. Surface contradictions
+     between the axes explicitly (e.g. "Spec axis says complete, Code-review axis says
+     untestable") — `$rite-seal` decides what blocks.
+4. **Reconcile, don't re-review.** With the two parallel reports in hand, the inline
+   lead reconciles — it does **not** re-run the code-review axes over correctness /
+   readability / architecture / maintainability that `devrites-code-reviewer` already
+   covered. Stay in scope ([feature-scoped-review](reference/feature-scoped-review.md)).
+   Add only what the dispatched agents could not, then resolve overlaps and
+   contradictions before labeling. ([five-axis-review.md](reference/five-axis-review.md)
+   documents the axes the code-review agent applies.)
+   - **UI feature?** Apply the **UX rubric**
+     ([nielsen-heuristics](reference/nielsen-heuristics.md)) and the
+     **cognitive-load lens** ([cognitive-load](reference/cognitive-load.md)) on the
+     UX axis — surface heuristics scoring ≤ 2 and any cognitive-load findings
+     (extraneous noise, missing progressive disclosure, vocabulary drift) at the
+     appropriate severity.
+5. **Security** — apply `devrites-audit security`
+   ([security-review](reference/security-review.md)) when user input, auth, data
+   storage, external integrations, secrets, or permissions are involved.
+6. **Performance** — apply `devrites-audit perf`
+   ([performance-review](reference/performance-review.md)) only when performance is
+   relevant or a regression risk is visible (measure first).
+7. Apply only in-scope fixes; **run verification after changes** (`$rite-prove` logic).
+8. Update `review.md`, `evidence.md`, and `state.md`.
+9. **Guard against the silent reviewer.** After `review.md` is written, run:
+   ```bash
+   devrites-engine review-integrity
+   devrites-engine review-fingerprints --write
+   ```
+   Exit 1 means an adversarial axis reported nothing and justified nothing — a suspected
+   rubber-stamp. Re-run that axis or add its `No-findings:` justification; do not carry a silent
+   axis into `$rite-seal` (where it surfaces as an Important).
+
+## Finding labels
+- **Critical** — must fix before seal (correctness/security/data loss).
+- **Important** — should fix before seal (likely bug, real maintainability risk).
+- **Suggestion** — worth doing, not blocking.
+- **Nit** — trivial/style.
+- **FYI** — context, no action implied.
+
+**Action decoration (orthogonal to severity).** Also tag each finding with how to act on it:
+`blocking` (fix before seal), `non-blocking` (fix when convenient), or `if-minor` (fix only if the
+change is already small — a pure noise-economics lever). Only a **`blocking` Critical** gates the
+seal; a `non-blocking` / `if-minor` finding is recorded, not a stop.
+
+## Confidence + signal-to-noise
+Borrow `$rite-vet`'s discipline so review stays **trusted, not noisy** — a reviewer that posts
+18 comments per PR teaches the team to ignore every one (below ~10% false-positive rate devs
+investigate each finding; past ~30% they label the tool noisy and skip it):
+- **Confidence-band each finding** (1–10) and state the band. A low-confidence finding (≤4)
+  you can't verify against the code is **suppressed** — roll it into one `Suppressed
+  (low-confidence): n` line, never raised as Critical/Important.
+- **Verify before you escalate.** Every Critical/Important quotes the spec line or cites the
+  `file:line` that proves it — no unverified blockers.
+- **Budget the noise.** Roll up trivia ("N style nits") into a single line; tooling already
+  catches style. Review's job is correctness + spec fidelity, not a lint dump.
+- **A silent axis is suspicious, not clean.** An adversarial axis that raises nothing must earn
+  it: end its `## Spec` / `## Code review` section with a **`No-findings:`** line naming the
+  passes it ran (missing/partial/incorrect for spec; edge cases, error paths, the riskiest
+  decision, a changed behavior whose test may not cover it for code) and why each came back
+  empty. This is the mirror of confidence-banding — banding kills the false positive, this catches
+  the false negative ([`code-review.md` § Zero findings is suspicious](../devrites-lib/reference/standards/code-review.md)).
+
+## Severity orientation (labels, not score)
+
+After labeling, summarize findings as `Critical / Important / Suggestion / Nit /
+FYI` counts. There is no composite number — `$rite-seal` gates on
+`Critical == 0` and on acceptance + drift. Inventing a number invites gaming;
+the labels do the work.
+
+> **Mid-flight discipline.** When tempted to demote a Critical, hide a finding, fix without re-verification, or wander out of scope — see [`anti-patterns`](reference/anti-patterns.md). Load it the moment you reach for the excuse.
+
+## Output → `review.md`
+
+Write the detailed review to `review.md`. In chat, run `devrites-engine progress` first, then use
+the shared completion reply contract
+([`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md)).
+Default success shape:
+```
+Done: review complete for <slice N | feature>.
+Changed: review.md, review-fingerprints.jsonl, evidence.md <updated|n/a>, state.md
+Evidence: open findings Critical 0 / Important <non-blocking n> / Suggestion <n> / Nit <n> / FYI <n>; re-verification <cmd -> pass|n/a>
+Open: <none | non-blocking Important/Suggestion follow-ups>
+Next: $rite-seal
+Record: .devrites/work/<slug>/review.md
+↻ Hygiene: /compact (review findings) if fixing now; /clear if clean
+```
+If a blocking Critical or required re-proof remains, use the shared `Stopped /
+blocked` form and route `Fix:` to the single repair or `$rite-prove`; do not
+recommend `$rite-seal`.

package/pack/generated/codex/skills/rite-review/reference/anti-patterns.md

@@ -0,0 +1,32 @@
+# rite-review — anti-patterns
+
+Load this when standing a non-trivial review decision, when tempted to
+demote severity to hide a finding, or when crossing out of feature scope.
+
+Pack-wide rationalizations + red flags: see
+[standards/anti-patterns.md](../../devrites-lib/reference/standards/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "Polish already cleaned this up; nothing to flag." | Polish finishes; review judges. If review still spots a real issue, flag it — don't re-run polish here. |
+| "Tests pass, so they're adequate." | Adequacy = do they prove acceptance, including failure / boundary / empty paths? A passing test is not automatically a good test. |
+| "Security audit isn't needed for this feature." | If the feature touches user input, auth, data storage, external integrations, secrets, or permissions — yes it is. |
+| "I'll just fix everything I find in scope." | Some fixes belong in `$rite-plan` as drift, not as smuggled redesigns inside review. |
+| "Performance is fine without measuring." | No claim without a number or a specified measurement. "Feels fast" is not a finding. |
+
+## Severity gaming
+
+| Excuse | Rebuttal |
+|---|---|
+| "Demoting a Critical to Important keeps the review clean." | Severity reflects the actual risk to ship — not the review you'd like. |
+| "I won't surface this Critical; user can find it later." | Hidden Criticals are the worst-case play. The seal blocks anyway, and now you've burned trust. |
+
+## Red Flags
+
+- A finding without `file:line`.
+- A finding without a severity label (Critical / Important / Suggestion / Nit / FYI).
+- A Critical recorded but silently fixed instead of surfaced to the seal.
+- A fix applied without re-verification afterwards.
+- Review crossing into out-of-scope files because they "looked wrong".

package/pack/generated/codex/skills/rite-review/reference/cognitive-load.md

@@ -0,0 +1,92 @@
+# Cognitive load — a UX review lens
+
+Cognitive load is the total mental effort the interface demands. Overloaded users
+hesitate, misclick, abandon. Reviewing UI without this lens misses a whole class of
+defects that no a11y checker or perf tool will flag.
+
+DevRites' `$rite-review` uses this reference when the feature touches UI. It is
+descriptive (helps you spot defects) rather than scored — findings raised here
+roll up under the UX axis of the multi-axis review with the usual severity labels.
+
+## Three kinds of load
+
+| Type | Source | Reviewer's job |
+|---|---|---|
+| **Intrinsic** | The task itself — its inherent steps, decisions, and required knowledge. | Can't be eliminated, only **structured**: step the user through it, provide defaults, group related decisions, defer what isn't needed yet. |
+| **Extraneous** | Bad design — friction the task doesn't require: noisy hierarchy, redundant choices, jargon, layout that hides the next step. | **Eliminate it ruthlessly.** It's pure waste, and the easiest class of finding to land. |
+| **Germane** | Effort the user spends *forming a mental model* of the product. | **Invest deliberately.** Consistent flows, shared vocabulary, predictable affordances — anything that lets the user re-use what they already learned. |
+
+A surface can be intrinsic-heavy *and* extraneously-fine — that's a hard task done
+right. A simple surface that still feels heavy is extraneous load disguised as
+"complexity."
+
+## Symptoms reviewers should flag
+
+Treat each as a finding when present; classify by load type so the fix is obvious.
+
+### Extraneous (reduce / remove)
+- **Visual noise** that doesn't earn its place: redundant borders, shadows,
+  dividers, gratuitous icons next to every label, colour used decoratively.
+- **Competing primary actions** — two or three buttons of equal weight when one
+  is clearly the next step.
+- **Jargon and abbreviations** the user doesn't share — names from the codebase
+  or internal team that leaked into the UI.
+- **Restated headings** (the body of a section repeats the section title in
+  long-form).
+- **Decision paralysis** — too many options when one default + a "more options"
+  toggle would do.
+- **Form fields without obvious priority** — required vs optional, primary vs
+  secondary mixed in a single column with no rhythm.
+- **Premature error messaging** (validation that fires before the user has
+  finished typing).
+
+### Intrinsic (structure, don't try to eliminate)
+- **No progressive disclosure** on a genuinely complex task — every field
+  visible at once because "the user might need it".
+- **No safe defaults** on multi-step flows — the user has to choose at every step
+  even when one path is the obvious answer.
+- **Decisions grouped wrong** — "billing address" sandwiched between two
+  unrelated sections rather than next to "shipping address".
+- **No scaffolding** (no template, no example input, no recently-used value)
+  for tasks that have a high blank-page cost.
+
+### Germane (invest in)
+- **Inconsistent vocabulary** across the feature — same concept named two ways
+  (e.g. "member" in one screen, "user" in the next).
+- **Flow-shape divergence** from neighbouring features (modal where the project
+  uses inline; route-change where the project uses an overlay).
+- **Affordances that look interactive but aren't** (and vice versa) — destroys
+  the mental model the user is trying to build.
+
+## Reviewing a flow — three-pass discipline
+
+1. **First pass: silent.** Walk the flow without reading any explainer copy.
+   Anything that stops you cold without copy is a finding — either extraneous
+   load you can't dismiss, or a germane-load problem (the user is missing a
+   mental model the UI assumes).
+2. **Second pass: with copy.** Read every label, helper, and error. Does the
+   copy resolve the friction the first pass surfaced, or just paper over it?
+   "Tooltip explaining a confusing button" is rarely the right fix — usually
+   the button needs a different label.
+3. **Third pass: empty + error.** Run the flow with no data, partial data, and
+   the worst inputs (offline / 500 / permission-denied). Most cognitive-load
+   defects hide in non-happy paths because nobody designs them.
+
+## The cheap-fix test
+
+If a finding would take more than 30 minutes to fix, classify it (token gap /
+component miss / flow misalignment per `rite-polish/reference/ui.md`) and
+route to the appropriate bucket. Cognitive-load review surfaces problems; it
+doesn't decide the rewrite strategy.
+
+## What this lens **doesn't** cover
+
+- **Accessibility** — separate axis (WCAG 2.2; see
+  [`devrites-frontend-craft/reference/quality-standards.md`](../../devrites-frontend-craft/reference/quality-standards.md)).
+- **Performance** — separate axis (Core Web Vitals; see
+  [`performance-checklist.md`](performance-checklist.md)).
+- **Code quality** — covered by the simplification audit
+  (`devrites-audit simplify`).
+- **Security** — covered by the security audit (`devrites-audit security`).
+
+Cognitive-load findings live on the **UX axis** of the multi-axis review.

package/pack/generated/codex/skills/rite-review/reference/feature-scoped-review.md

@@ -0,0 +1,26 @@
+# Feature-scoped review
+
+The review boundary is the **active feature**: the files in `touched-files.md` and the
+current diff. This is a hard rule, not a guideline.
+
+## In scope
+- Code added/changed by this feature.
+- Tests for this feature.
+- Files this feature intentionally inspected and depends on (read for context, but
+  don't refactor them).
+
+## Out of scope (do NOT)
+- Refactor unrelated modules because they're "nearby" or "while we're here".
+- Delete suspected dead code outside this feature without asking the user.
+- Restyle/upgrade dependencies or change project-wide config to suit this feature.
+- Expand the review into a project audit.
+
+## When you spot a real problem outside scope
+Record it as an **[FYI] follow-up** in `review.md` (and suggest a separate feature/issue)
+— don't fix it inline. Drive-by changes balloon the diff, dodge their own review, and
+mix concerns the seal can't cleanly evaluate.
+
+## Why scope discipline matters
+A tight diff gets a real review; a sprawling one gets a rubber stamp. Scope creep is how
+"a small fix" becomes an unreviewable, unprovable change. Keep the feature shippable and
+the review honest.

package/pack/generated/codex/skills/rite-review/reference/five-axis-review.md

@@ -0,0 +1,60 @@
+# Code-review axes
+
+The axes the dispatched `devrites-code-reviewer` applies to the diff (tests first
+— always), under one severity scale (Critical / Important / Suggestion / Nit / FYI).
+The `$rite-review` inline lead **reconciles** the returned report against the Spec
+axis — it does not re-run these axes itself. This file is the shared definition of
+what "full code-review discipline" covers; use it to judge whether the agent's report
+is complete, and to scope anything the agent could not (e.g. UI-only lenses below).
+
+## 0. Tests (first)
+- Do tests exist for the changed behavior, and do they prove the acceptance criteria?
+- Would they fail if the code were wrong? (No assertion-free or tautological tests.)
+- Edge cases: empty, boundary, error, permission-denied, concurrency.
+
+## 1. Correctness
+- Does it do what the spec says? Off-by-one, null/undefined, error paths, race
+  conditions, incorrect assumptions about inputs.
+- Does it handle the states the slice promised (loading/empty/error for UI)?
+
+## 2. Readability
+- Can the next engineer understand it without the author? Naming, function length,
+  nesting depth, comments that explain *why* not *what*.
+- Structural smells: a conditional **bolted onto an unrelated flow** (wants its own
+  helper/state/policy — a design smell, not a nit); **repeated conditionals on the same
+  shape** (a missing model or dispatcher).
+
+## 3. Architecture
+- Right seam/boundary? Coupling and cohesion. Does it fit existing patterns or
+  introduce a competing one? Is the abstraction earned (not premature)?
+- Does a refactor **reduce** complexity or just **relocate** it? Count the concepts a
+  reader must hold; a "cleaner" version that leaves that count unchanged isn't cleaner.
+- Is feature-specific logic **leaking into a shared module** instead of its owning layer?
+  Is a **type boundary** left implicit by a gratuitous `any`/cast or a silent fallback?
+- **Name the remedy, not just the smell** — replace a conditional chain with a typed
+  dispatcher, separate orchestration from business logic, move feature logic to its owning
+  package, delete a pass-through wrapper, split a large file. Prefer the move that removes
+  moving pieces over one that re-centralizes the same complexity.
+
+## 4. Security
+- Trust boundaries, input validation, authz checks, secrets handling. Hand off to
+  `devrites-audit security` when input/auth/data/integration is in scope.
+
+## 5. Performance
+- Obvious N+1s, unnecessary work in hot paths, payload sizes. Hand off to
+  `devrites-audit perf` when perf is relevant — **measure before claiming**.
+
+## 6. Maintainability
+- Tests, docs/comments where needed, no dead code added, no TODOs left, consistent
+  with project conventions.
+
+## Frontend axes (if UI)
+- UX flow matches neighbors; all interaction states; a11y (focus, labels, contrast,
+  keyboard); responsive; design-system alignment (no drift, no anti-AI-slop).
+
+## Sizing & speed
+Prefer reviewing roughly one slice / ~100 lines of meaningful change at a time. Larger
+diffs hide defects — recommend splitting rather than rubber-stamping. Watch **file size,
+not just diff size**: a small diff that pushes an already-large file further past a healthy
+boundary wants decomposition (extract helpers / split modules) *first* — decompose, then
+add.