devrites 2.6.0 → 3.0.0

package/pack/generated/codex/skills/devrites-lib/reference/parallel-dispatch.md

@@ -0,0 +1,165 @@
+# Parallel review dispatch
+
+How `$rite-review` and `$rite-seal` fan out the fresh-context review subagents under
+`.codex/agents/`. The **single source** for the dispatch + reconciliation contract — loaded on
+demand by the calling skill (each points here); not a skill itself.
+
+The seal/review fan-out **roster** is the seven post-build reviewers in the table below — this
+file is the single source of which reviewer fires when. The seal and the multi-axis review need
+them running **at the same time**, on the same workspace + diff, so the verdicts don't
+contaminate each other. Every other agent under `.codex/agents/` fires from its own phase, not
+here — the roster table below names them under **Not in this fan-out** so the set is unambiguous.
+
+Pattern: delegate to specialized agents with isolated context, brief each one precisely, run
+them concurrently, reconcile on return.
+
+## The roster — every reviewer the fan-out accounts for
+
+These seven are the **roster**. `$rite-seal` accounts for **all** of them — the always-on three
+plus each conditional, either dispatched or skip-recorded; `$rite-review` runs the two always-on
+axes. Each trigger is a *checkable signal*, not a judgement call, so a conditional reviewer is
+either fired or consciously skipped — never silently dropped.
+
+| Reviewer | Fires | Trigger — the checkable signal |
+|---|---|---|
+| `devrites-spec-reviewer` | always | `$rite-review` Spec axis; `$rite-seal` (carry review's verdict forward only if the diff is unchanged) |
+| `devrites-code-reviewer` | always | `$rite-review` Code-review axis; `$rite-seal` (carry forward only if the diff is unchanged) |
+| `devrites-test-analyst` | always | at `$rite-seal` |
+| `devrites-frontend-reviewer` | conditional | the diff touches a UI file — component / template / stylesheet, per the project's UI paths |
+| `devrites-security-auditor` | conditional | the diff touches input handling, auth / authz, data storage or access, an external integration, or a secret |
+| `devrites-performance-reviewer` | conditional | `spec.md` states a perf budget, **OR** the diff adds a query / a loop over a growing set / hot-path or render work |
+| `devrites-devex-reviewer` | conditional | the diff changes a developer-facing surface — public API, CLI, SDK/library export, webhook, config/env contract, error message, or getting-started path |
+
+### Hit-rate gating — consult before dispatching conditionals
+
+Before dispatching, run `devrites-engine reviewer-stats report`. It grades each reviewer from the
+cross-feature dispatch ledger (`.devrites/reviewer-stats.jsonl`):
+
+- `run` / `run (always-on)` / `run (insurance — never gated)` — dispatch per the trigger table above.
+- `gate-candidate` — this **conditional** reviewer produced zero surviving findings in its last 10+
+  dispatches on this project. Skip it as a *recorded* skip:
+  `devrites-engine footprint log <slug> skip devrites-<x>-reviewer` with the reason
+  `gated: zero surviving findings in <N> dispatches`. The roster gate stays satisfied — a gated
+  skip is a conscious skip.
+
+The verdict is engine-owned and deterministic; never gate by your own judgement of a reviewer's
+past usefulness. Two hard bounds: the always-on axes (`spec`, `code-review`, `test-analyst`) and
+the insurance reviewers (`security-auditor`, `doubt-reviewer`) are **never** gated — the engine
+never grades them `gate-candidate`, and a caller must not skip them on hit-rate grounds. The user
+can override gating for one run by asking for a full panel (`--full`): then dispatch every
+triggered reviewer regardless of verdict.
+
+After reconciliation, close the loop — record each **dispatched** reviewer's outcome so the
+ledger stays live:
+
+```bash
+devrites-engine reviewer-stats record devrites-<x>-reviewer <surviving Critical+Important count> <slug>
+```
+
+Surviving means it stood after reconciliation and dismissals — a finding the caller dismissed as a
+false positive does not count. Record `0` honestly; dry streaks are the signal.
+
+**Not in this fan-out** (named so the roster is unambiguous): `devrites-simplifier-reviewer` fires
+at `$rite-polish` Phase 1 (via `devrites-audit simplify`) and `devrites-doubt-reviewer` fires from
+`devrites-doubt` when a decision is stood up — neither is a seal reviewer, so neither is part of
+the seal accounting. `devrites-strategy-reviewer` (pre-plan, `$rite-temper`), `devrites-plan-reviewer`
+(pre-build, `$rite-vet`), `devrites-forge-judge` (`$rite-build` forge), and `devrites-retrospector`
+(`$rite-ship` close) are single-agent, phase-locked gates — they fire iff their phase runs, not here.
+
+One entity, one name: the `devrites-code-reviewer`'s axis is the **Code-review axis** everywhere
+(at both `$rite-review` and `$rite-seal`) — don't rename it per caller.
+
+## Dispatch shape
+
+For each chosen subagent, the caller uses the harness's subagent primitive — the `Task` tool on
+Claude Code, `spawn_agent` (with the matching `.codex/agents/devrites-*.toml` custom agent) on
+Codex — with this prompt shape:
+
+```
+Audit the active DevRites feature.
+
+Workspace: .devrites/work/<slug>/
+Read (yourself, fresh context):
+  - spec.md  (+ acceptance criteria)
+  - touched-files.md
+  - the git diff
+  - <any axis-specific files: decisions.md, evidence.md, references/...>
+
+Before judging the diff, derive the expected behaviour from the spec
+yourself, then compare it against what the code does. Anchor every finding
+to file:line plus the spec criterion or command output that proves it —
+an unanchored finding is a Suggestion at most. The order or length of the
+diff is not evidence.
+
+Apply your documented discipline. Return labeled findings (Critical /
+Important / Suggestion / Nit / FYI) using your documented output format,
+ONE FINDING PER LINE, cite file:line.
+
+Feature scope only. No edits. Do not summarize or re-rank — the caller
+reconciles.
+```
+
+Rules:
+
+- **One Task call per subagent, awaited in the same turn.** Send them in a single message with multiple `Task` invocations so the runtime dispatches concurrently. Never background/detach reviewers in `$rite-autocomplete` or AFK; there is no event loop that guarantees a later result is reconciled.
+- **No cross-pollination.** Each subagent gets only its narrow brief and the workspace path. Do not pass another subagent's findings into a sibling's prompt — that recreates the masking problem.
+- **No author context.** Do not include the caller's analysis or the user's framing of the change; the point is a fresh, adversarial read.
+- **Never coach a reviewer.** No "do not flag X", "treat Y as at most Minor", or "the plan
+  chose this" in a dispatch prompt — pre-judging findings is how a known defect sails through.
+  A plan-mandated quirk still gets reported; the caller (or the human) grades it, not the prompt.
+- **Feature scope only.** Each subagent must stay inside `touched-files.md` + the diff.
+- **Can't-verify is a verdict, not a pass.** A reviewer that cannot verify a spec requirement
+  from the diff + its allowed reads returns it as a `CANNOT-VERIFY: <requirement> — <why>` line.
+  The caller resolves each one itself before the gate; an unresolved CANNOT-VERIFY on an
+  acceptance-mapped requirement stands as a gap, not a pass.
+
+## Account for every reviewer — the roster gate
+
+The fan-out is done only when **every roster reviewer is accounted for** — dispatched, or
+consciously skipped with a one-line reason. A conditional reviewer that genuinely does not apply
+(no UI in the diff → `frontend-reviewer`) is a *recorded* skip, not a silent no-op. That record
+is the difference between "reviewed" and "declared done after firing three of seven" — the silent
+skip is exactly how a needed reviewer never runs.
+
+Record each decision to the footprint as you make it (via `devrites-engine footprint`, as in `$rite-build`). Log the reviewer's
+**exact agent name** — the `.codex/agents/` stem, e.g. `devrites-frontend-reviewer`; the `roster`
+gate matches on it (stripping the `devrites-` prefix), so a freehand label like `frontend` or
+`Spec axis` will not match and the gate reads that reviewer as unaccounted:
+
+- dispatched → `devrites-engine footprint log <slug> reviewer devrites-<x>-reviewer`  (the dispatch record itself)
+- skipped → `devrites-engine footprint log <slug> skip devrites-<x>-reviewer`  # e.g. `skip devrites-frontend-reviewer` — no UI in the diff
+
+Then, **before the verdict**, prove the roster is complete:
+
+```bash
+devrites-engine footprint roster <slug>   # rc=0 complete · rc=3 a reviewer was neither dispatched nor skipped · rc=1 an always-on reviewer was skipped
+```
+
+`rc=3` is the silent omission the gate exists to catch: resolve it by dispatching the reviewer or
+recording why it does not apply — never by proceeding with it unaccounted. `rc=1` means an
+always-on axis (Spec / Code-review) was skip-recorded; that is legitimate only as a carry-forward
+of `$rite-review`'s verdict on an **unchanged** diff — confirm that, don't wave it through.
+
+## Reconciliation
+
+When the subagents return:
+
+1. **Quote verbatim.** Place each subagent's findings under its own `## <axis>` heading in `review.md` / `seal.md`. Do not merge, re-rank, or summarize. `devrites-code-reviewer` runs its **full** documented discipline (tests-first, correctness, readability, architecture, maintainability, standards); the inline lead **reconciles** the returned reports — it does not re-run those same axes itself.
+2. **Surface contradictions explicitly.** "Spec axis says complete, Code-review axis says untestable" is a finding, not noise. The caller decides at the gate.
+3. **Severity is the gate, not a score.** Sum the labels (`Critical / Important / Suggestion / Nit / FYI`) and apply the caller's gate (`$rite-seal` blocks on `Critical == 0`; `$rite-review` reports counts).
+4. **One scale.** All subagents use the same five-label scale (Critical / Important / Suggestion / Nit / FYI). Reject any subagent output that invents its own. **Exception:** `devrites-simplifier-reviewer` deliberately emits only Suggestion / Nit / FYI (it is non-blocking by design) — that is a valid subset of the scale, not an invented one; do not reject it during reconciliation.
+5. **Consensus roll-up (after the verbatim per-axis record).** Keep every axis's findings verbatim under its `## <axis>` heading (above), then add one deduped roll-up the gate reads: where **≥2 axes flag the same `file:line`**, raise it to the top and mark it *consensus* — independent corroboration raises confidence. A lone low-confidence finding with no `file:line` or evidence anchor drops out of the roll-up (it stays in its per-axis section). The roll-up reduces noise without hiding any axis — the verbatim sections are the audit trail; the roll-up is the actionable summary the gate acts on.
+
+## Model tier
+
+Every reviewer in this fan-out runs at **ceiling tier** — the orchestrator's own model, inherited
+by declaring no `model:` in the agent definition (see
+[`model-tiers.md`](model-tiers.md)). Adversarial review is exactly where a cheaper model costs the
+most: a missed Critical is far more expensive than the tokens saved. Do not downgrade a reviewer to
+save cost. Extraction-tier savings belong to scouts (archive-search, footprint), not to the panel.
+
+## Fallback
+
+If the harness has **no subagent primitive at all** (neither Claude's `Task` nor Codex's
+`spawn_agent` — an absent tool on one harness while the other's equivalent exists does NOT
+qualify), the caller runs the relevant subagent discipline **inline** in its own context and flags the result as a fallback (not an independent review). The seal weighs the fallback differently — see [`../../rite-seal/reference/risk-and-rollback.md`](../../rite-seal/reference/risk-and-rollback.md). This is the [`model-tiers.md`](model-tiers.md) degradation rule applied to the review panel: no subagent primitive → run inline under the same discipline and budget.

package/pack/generated/codex/skills/devrites-lib/reference/reply-contract.md

@@ -0,0 +1,111 @@
+# DevRites completion reply contract
+
+Use this for every user-facing, workspace-operating `rite-*` skill. The chat reply is
+a compact status summary; durable detail belongs in the phase artifact
+(`spec.md`, `plan.md`, `eng-review.md`, `evidence.md`, `polish-report.md`,
+`review.md`, `seal.md`, `ship.md`, and related records).
+
+Before the final reply, persist the phase event, then render the deterministic
+progress chrome:
+
+```bash
+devrites-engine timeline log completed --skill <skill> --slug "$(cat .devrites/ACTIVE 2>/dev/null)" --outcome "<ok|blocked|no-go|go>" --decision "<one-line result>"
+devrites-engine budget
+devrites-engine progress
+```
+
+If the phase produced a quality verdict (review, prove, polish, seal, ship), also
+record the evidence-backed health signal before `progress`:
+
+```bash
+devrites-engine health record <0..10> "<evidence-backed label>" --note "<primary check or blocker>"
+```
+
+Skip `timeline` / `health` only when the skill is explicitly workspace-less or
+read-only and has no active `.devrites` workspace.
+
+Do not restate the slice meter or flow ribbon in prose. Keep the default reply to
+roughly 8-10 lines after the progress footer.
+
+## Default completion
+
+```text
+Done: <phase result in one sentence>
+Changed: <artifact(s) written/updated, or "workspace only">
+Evidence: <checks/proof/artifact pointer, or "not applicable">
+Open: <none | non-blocking questions or follow-ups>
+Next: <exactly one recommended command>
+Record: <primary durable artifact path>
+↻ Hygiene: <clear/compact/handoff advice, one line>
+```
+
+Rules:
+- Use this default form only for a green, non-blocking result. If proof, a verdict,
+  or a required decision is missing, use `Awaiting human`, `Stopped / blocked`, or
+  `NO-GO`; do not label the phase `Done` or advance it.
+- `Next:` contains exactly one recommended command. Put alternates in `Open:` or an
+  `Alternative:` line only when the phase needs one.
+- Use `Evidence: not applicable` only when the phase truly does not verify runtime
+  behavior, such as spec or plan creation.
+- Claims such as "proved", "reviewed", "sealed", "shipped", and "all slices built"
+  must point to evidence or an artifact.
+- Use stable labels: `Done`, `Changed`, `Evidence`, `Open`, `Next`, `Record`,
+  `↻ Hygiene`.
+- Status symbols are optional; never rely on color or emoji alone. Pair them with
+  explicit text labels such as `Done`, `Stopped`, `Awaiting human`, `NO-GO`, `GO`,
+  or `Shipped`.
+
+## Awaiting human
+
+```text
+Awaiting human: <qid> · <gate> · <slice/phase>
+Question: <one-line question>
+Recommended: <option 1 + short reason>
+Options: <2-4 compact choices, if already generated>
+Resume: $rite-resolve <qid> "<answer>"
+Record: .devrites/work/<slug>/questions.md
+↻ Hygiene: no /clear until the answer is persisted
+```
+
+## Stopped / blocked
+
+```text
+Stopped: <reason>
+Blocking: <specific blocker>
+Why: <one-line impact>
+Fix: <single command or action>
+Record: <artifact path>
+↻ Hygiene: /compact (<topic>) if fixing now; /clear if stopping
+```
+
+## NO-GO
+
+```text
+NO-GO: <short verdict>
+Blockers: <count + top 1-3 blockers>
+Fix: <single next command>
+Record: .devrites/work/<slug>/seal.md
+↻ Hygiene: /compact (seal blockers) if fixing now; /clear if stopping
+```
+
+## GO
+
+```text
+GO: feature cleared to ship
+Follow-ups: <none | non-blocking count>
+Next: $rite-ship
+Record: .devrites/work/<slug>/seal.md
+↻ Hygiene: /clear before $rite-ship
+```
+
+## Shipped
+
+```text
+Shipped: <feature>
+Commit: <sha> on <branch>
+Tag/PR: <value | none>
+Acceptance: <n>/<total> proven
+Archived: .devrites/archive/<slug>/ · ACTIVE cleared
+Record: .devrites/archive/<slug>/ship.md
+↻ Hygiene: /clear
+```

package/pack/generated/codex/skills/devrites-lib/reference/standards/README.md

@@ -0,0 +1,61 @@
+# DevRites rules
+
+Stack-agnostic engineering rules that DevRites installs to `.agents/skills/devrites-lib/reference/standards/`. They encode
+the standards the DevRites workflow holds code to — quality, safety, testing, and review
+discipline that apply in any language.
+
+These are **common** by design: nothing here assumes a specific framework or language.
+Project-specific conventions always win where they exist (DevRites reads the codebase and
+prefers what's already there).
+
+## Loading model — progressive disclosure
+
+To keep context lean, the rules follow progressive disclosure: each DevRites `rite-*`
+skill Reads `.agents/skills/devrites-lib/reference/standards/core.md` as its first step;
+the remaining rule files load on demand by the phase that needs them.
+
+### Always-on (read by each `rite-*` skill as step 0)
+
+| Rule | Covers |
+|---|---|
+| `core.md` | Operating rules, universal anti-rationalizations, one-line craft disciplines (fail-fast, reuse-first, test-behaviour-not-impl, trust boundary, measure-first), persistence + hygiene reminders. |
+
+### On-demand (read by the phase / topic that needs it)
+
+| Rule | Covers | Typical phase |
+|---|---|---|
+| `coding-style.md` | Naming, function shape, guard clauses, comments, simplicity, reuse-first. | `$rite-build`, `$rite-polish` Phase 1. |
+| `prose-style.md` | Human-voice writing for artifacts + replies; two registers (prose vs technical); the LLM-tell cut-list. Depth in the `devrites-prose-craft` skill. | Any phase that writes prose — `$rite-spec`, `$rite-define`, `$rite-review`, `$rite-seal`, `$rite-ship`; `$rite-polish` Phase 1 as the catch. |
+| `error-handling.md` | Fail fast, no silent catches, meaningful messages, fail closed. | `$rite-build`, `$rite-polish` (backend), `$rite-review`. |
+| `testing.md` | Pyramid, behavior over implementation, determinism. | `$rite-build`, `$rite-prove`, `$rite-review`. |
+| `spec-grammar.md` | Optional, recommended structure for behavioral acceptance — `### Requirement:` (SHALL/MUST) + `#### Scenario:` (WHEN/THEN), validated deterministically by `devrites-engine spec-validate`. Progressive rigor; flat `AC-###` bullets stay valid. | `$rite-spec` readiness gate; `$rite-prove`, `$rite-review` consume the scenario hooks. |
+| `code-review.md` | Small PRs, severity labels, what to check, actionable feedback. | `$rite-review`, `$rite-seal`. |
+| `edge-case-trace.md` | Mechanical branch/boundary sweep, fixed-set siblings, and deletion-contract checks. | `$rite-review`, `$rite-seal`, `devrites-doubt`. |
+| `security.md` | Untrusted input, least privilege, secrets, three-tier trust boundary, fail closed. | When input / auth / data / integrations are in scope. |
+| `performance.md` | Measure first, common pitfalls, prove the win. | When perf is in scope. |
+| `observability.md` | Structured logs, metrics/SLIs, traces, symptom-based alerts, verify-the-telemetry-fires — proof a feature works in prod. | When the change has a runtime surface (endpoint, job, integration, user flow); `$rite-prove`, `$rite-seal`. |
+| `developer-experience.md` | DX as a measured axis — the predict-at-vet / measure-at-prove / reconcile-at-seal boomerang; scorecard (TTHW, getting-started, error-message quality, ergonomics, docs); severity by who-pays. Conditional + greenfield no-op. | When a developer-facing surface is in scope (public API, CLI, SDK/library, webhook, config, error messages, getting-started); `$rite-vet`, `$rite-prove`, `$rite-seal`. |
+| `patterns.md` | SOLID, composition, loose coupling, avoid over-engineering. | `$rite-build`, simplification audit. |
+| `git-workflow.md` | Conventional Commits, atomic commits, small PRs. | `$rite-ship` commit / push / tag steps. |
+| `hooks.md` | Stage checks by cost, fast local hooks, secret scanning. | Reference-only — read when setting up the project's git hooks; not auto-loaded by any phase. |
+| `ci-cd.md` | Shift-left + faster-is-safer, the no-skip gate pipeline, the CI-failure loop, Build Cop, feature-flags decouple deploy from release, secret tiers, the pipeline-speed ladder. | Reference — read when setting up or changing a build/deploy pipeline; `$rite-ship` when CI/CD is in scope. |
+| `documentation.md` | Explain why, keep current, record decisions. | `$rite-spec`, `$rite-define`, `$rite-seal`. |
+| `elicitation.md` | A move-set of named reasoning techniques (Steelman, Delphi, Red-Team/Blue-Team, Assumption Audit, Pre-Mortem…) selected per section by risk, to deepen a spec or plan on demand. | `$rite-temper`, `$rite-vet`; any section that needs sharper thinking. |
+| `development-workflow.md` | Small batches, trunk-always-green, definition of done. | `$rite-define`, `$rite-plan`. |
+| `principles.md` | The four knowledge layers; project invariants (`.devrites/principles.md`) as a *trusted, gating* pass/fail (vs conventions' untrusted prior); justified-exception register; dated-amendment governance. | `$rite-define`, `$rite-vet`, `$rite-build`, `$rite-review`, `$rite-seal`; seeded by `$rite-adopt`, grown by `$rite-learn`. |
+| `deprecation.md` | Code-as-liability, Hyrum's law, prove-unused-before-remove, expand→contract, deprecate-before-delete. The safe path behind the irreversible-migration gate. | When removing / replacing / migrating code, a feature, an API, or data. |
+| `agents.md` | DevRites review subagents + specialist skills, when to fan out. | `$rite-review`, `$rite-seal`. |
+| `context-hygiene.md` | `/clear` vs `/compact`, lost-in-the-middle, phase-aware hygiene footer. | Phase-end hygiene footer; choosing `/clear` vs `/compact`. |
+| `anti-patterns.md` | Pack-wide rationalizations + red flags the agent reaches for. | Loaded by each `rite-*/reference/anti-patterns.md`; loaded directly when reluctance is broader than the active phase. |
+| `afk-hitl.md` | AFK vs HITL contract: `.devrites/AFK` sentinel format, `questions.md` schema, four-gate taxonomy (advisory / validating / blocking / escalating), AFK-never-silently-accepts boundaries. | `$rite-build`, `$rite-status`, `$rite-resolve`, `devrites-doubt`; anywhere a pause-or-proceed decision happens. |
+| `tooling.md` | Optional external tools — code intelligence (codebase-memory-mcp first → cross-verify with codegraph + graphify → standard methods LSP / `Read`/`Grep`/`Glob`), up-to-date library docs (context7), architecture/ADR memory. Recommended, not required. | Any phase doing structural lookups (callers / impact / placement) or relying on external library/framework facts. |
+| `skill-authoring.md` | Skill descriptions, progressive disclosure, completion criteria, and pruning rules for keeping DevRites skills predictable and cheap. | When creating or editing DevRites skills or reviewing skill pack quality. |
+| `definition-of-done.md` | Done means acceptance proven, evidence recorded, drift resolved, and handoff/ship state clean. | `$rite-prove`, `$rite-seal`, `$rite-ship`. |
+| `review-checklist.md` | Compact reviewer pass/fail checklist. | `$rite-review`, `$rite-seal`. |
+| `test-proof-checklist.md` | Proof-quality checklist for tests and evidence. | `$rite-prove`, `$rite-seal`. |
+| `browser-proof-checklist.md` | Browser/UI proof checklist. | UI features in `$rite-prove`, `$rite-polish`, `$rite-seal`. |
+| `security-checklist.md` | Security review checklist. | Auth/input/data/integration changes. |
+
+How they're used: DevRites skills follow these rules; you and Claude can reference them
+directly. They are guidance, not enforced gates — the enforced gates live in the
+workflow skills (Spec Drift Guard, readiness gates, the seal).

package/pack/generated/codex/skills/devrites-lib/reference/standards/afk-hitl.md

@@ -0,0 +1,243 @@
+# AFK & HITL — the pause/resume contract
+
+The rule layer for DevRites's two run modes. Every `rite-*` and `devrites-*` skill that
+might pause for a human reads from this contract; `$rite-build`, `$rite-status`,
+`$rite-resolve`, and `devrites-doubt` are the primary callers.
+
+The contract is intentionally small: one sentinel, one queue, one verb.
+
+## Run modes
+
+- **HITL (default)** — human is present. At a gap/checkpoint the skill **asks inline** via
+  the harness `AskUserQuestion` tool — a ranked **option set** (recommended first, each with
+  dimension-tagged rationale; see [Option set](#option-set--how-every-gap-is-presented)). The
+  human picks; the skill records the pick to `questions.md` (`answered`) + `decisions.md` and
+  **continues in place — no `$rite-resolve` round-trip**. `$rite-resolve` is only for answering
+  **async** (a pause that already stopped the session) or in **batch**.
+  **No interactive question tool in the current surface?** (Codex outside Plan mode —
+  `request_user_input` is Plan-mode-only.) Render the same option set as a plain numbered
+  list in chat and **end the turn**; the human's reply is the pick. Auto-picking an option
+  is **AFK's contract, gated by the `.devrites/AFK` sentinel** — a missing tool never
+  converts a HITL gap into a self-answered one.
+- **AFK** — `.devrites/AFK` is present. For any gate AFK may auto-handle (severity in
+  `allow_gates`), the skill **auto-picks the recommended option** (option 1 of the set), records
+  it (`gate: advisory` + a `decisions.md` ADR), and continues unattended. Gates above the
+  ceiling — and every irreversible-risk item — pause and queue a `questions.md` entry for
+  `$rite-resolve`.
+
+`.devrites/AFK` presence is authoritative for run mode; gate-deciding skills re-read the
+sentinel at decision time (the shared preamble derives the mode from it). There is no
+`state.md` run-mode field to drift out of sync.
+
+## The sentinel — `.devrites/AFK`
+
+Presence = AFK active. The file body is optional YAML:
+
+```yaml
+max_slices: 10                       # read-only INITIAL budget; seeds state.md `AFK slices remaining`
+notify: "ntfy.sh/my-topic"           # shell command run on awaiting_human transition
+allow_gates: [advisory, validating]  # gate severities AFK auto-handles (auto-picks the recommended option)
+```
+
+The file is **read-only config** — never rewritten in place. `max_slices` is the initial
+budget; the mutable remaining count lives in `state.md` as `AFK slices remaining: <n>`,
+seeded from `max_slices` on the first AFK build and decremented by `devrites-engine tick-afk` (which
+exits non-zero at 0, forcing a HITL stop). The cap is enforced by the script, not prose.
+
+Missing keys fall back to defaults:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `max_slices` | unlimited | a missing cap is unsafe; recommend setting one explicitly |
+| `notify` | none | no notification fires |
+| `allow_gates` | `[advisory]` | AFK auto-handles advisory only by default (auto-picks the recommended option) |
+
+To leave AFK, delete the file. The next skill invocation reverts to HITL.
+
+## The four gates
+
+Every `Mode: HITL` slice declares a `Gate:` and an `SLA:`. See
+[`.agents/skills/rite-define/reference/gates.md`](../../../rite-define/reference/gates.md)
+for the full taxonomy. Summary:
+
+| Gate | Stakes | Pause? | SLA | AFK auto-handle when in `allow_gates`? |
+|---|---|---|---|---|
+| advisory | low | no | none | yes (log + proceed) |
+| validating | medium | async | 4h | yes (build + queue, no merge until resolved) |
+| blocking | high | sync | 15m | **no** — always pauses |
+| escalating | novel pattern | sync to specialist | 24h | **no** — always pauses |
+
+`blocking` and `escalating` always pause regardless of `allow_gates`. They are the
+"AFK never silently accepts" guarantees in protocol form.
+
+An open `gate: validating` entry is **merge-blocking by definition**: at `$rite-seal` any
+`questions.md` entry with `gate: validating` and `status: open` is a NO-GO, regardless of
+its behavior impact. A slice marked `built (pending review)` is **not done** until that
+validating gate resolves.
+
+## Option set — how every gap is presented
+
+Wherever a gap, checkpoint, or non-trivial decision surfaces (`$rite-spec`, `$rite-define`,
+`$rite-build`, `$rite-temper`, `$rite-vet`, `devrites-doubt`, `devrites-interview`), present a
+**ranked option set**, never a single bare guess:
+
+- **2–4 concrete options**, the **recommended one first**, labelled `(Recommended)`.
+- Each option carries a **one-line rationale tagged by the dimensions that matter** —
+  `logic · infra · business · architecture` (add `security` / `UX` / `risk` when in scope).
+  Name the trade-off, not just the choice.
+- Always include an escape hatch (`Something else — I'll describe it`).
+- The recommendation reflects what's best for *this* project (its conventions, stack, scale,
+  domain) — not a generic default.
+
+**HITL** renders the set via `AskUserQuestion` (recommended option first; rationale in each
+option's description); the human's pick resolves the gate **in place**. **AFK** auto-picks
+option 1 (the recommendation) for gates it may auto-handle. Either way the chosen option is
+recorded verbatim and the **rejected options stay in `questions.md`** as the considered-alternatives
+trail — the audit shows what was weighed, not just what was decided.
+
+## Irreversible-risk list (always pause)
+
+The following always invoke the checkpoint protocol, regardless of `Mode`, `Gate`, or
+`allow_gates`:
+
+- Destructive data migration (drop column, drop table, irreversible backfill).
+- Auth / authz boundary change.
+- Public API break (response shape, removed endpoint, changed status code semantics).
+- External-service contract change.
+- Filesystem destruction outside the workspace.
+- Red tests / types / lint on slice completion (fail-on-red).
+
+When a pause clears and you proceed with a destructive migration, a removal, or a
+public-API break, take the **safe path** the gate stopped you for: expand→contract,
+prove the old path unused before removing it, and a rollback for every destructive step
+([`deprecation.md`](deprecation.md)). The gate exists to make you do it right, not to
+abandon the work.
+
+By default, AFK widens what's *automatic*; it never widens what's *irreversible*.
+
+## `questions.md` schema
+
+Append-only. One entry per qid. Format:
+
+```markdown
+## q-YYYY-MM-DD-NNN
+status: open | answered | dropped
+slice: <slice id, e.g. 03-list-endpoint, or "spec" / "plan">
+gate: advisory | validating | blocking | escalating
+question: <one crisp sentence>
+options: |                                    # ranked option set; recommended FIRST (see "Option set")
+  1. <recommended> (Recommended) — logic: … · infra: … · business: … · architecture: …
+  2. <alternative> — <dimension-tagged rationale + trade-off>
+  3. Something else — describe it
+proposed: <the recommended option restated — the HITL default + the AFK auto-pick>
+raised_at: <iso>
+answered_at: <iso, when status flips off "open">
+answer: <chosen option (or human's verbatim reply / drop reason)>
+```
+
+Rules:
+- `NNN` is sequential per date — the next-available 3-digit integer.
+- `status: open` is the only state `$rite-resolve` can mutate; `answered` and `dropped`
+  are terminal.
+- The file is the audit trail. Don't edit answered/dropped entries — open a new qid that
+  references the old one (`supersedes: q-...-OLD`) and resolve it.
+
+## `state.md` `Awaiting human` block
+
+When a HITL gate fires, `$rite-build` writes:
+
+```markdown
+- Status: awaiting_human
+- Next step: $rite-resolve <qid> "<answer>"
+
+## Awaiting human
+- qid: <q-...>
+- gate: <gate>
+- question: <crisp text>
+- proposed: <agent's tentative answer>
+- raised_at: <iso>
+- blocking_slices: [<slice ids that cannot advance>]
+```
+
+`$rite-resolve` removes the block on success and flips `Status: running`.
+
+## The resume verb — `$rite-resolve`
+
+Three shapes:
+
+```
+$rite-resolve <qid> "<answer>"
+$rite-resolve --drop <qid> ["<reason>"]
+$rite-resolve --batch <path-to-yaml>
+```
+
+`$rite-resolve` is the canonical writer for **async** resume — a gate that already paused and
+stopped the session (an AFK blocking/escalating/irreversible queue, or a HITL pause the human
+walked away from), plus `--batch`. In an **interactive HITL** session the skill resolves the
+`AskUserQuestion` pick **in place** (the same `questions.md` `answered` write + `state.md`
+clear), so you don't type `$rite-resolve` for gaps you answer live. Both paths flip
+`status: open → answered` and clear `Awaiting human` through the **same `devrites-engine resolve` writer** —
+one source of truth, two entry points (live pick vs typed verb). Manual edits work but the
+script is the contract — use it.
+
+When `$rite-resolve` does resume a stopped session, the skill does **not** auto-run the next
+`$rite-build`. The user types the next command explicitly so:
+- A `$rite-plan repair` can land first if the answer changes scope.
+- The user sees the workspace state before resuming.
+- Each verb has one mutation; chaining is a hidden side-effect.
+
+## AFK exception for discretionary pauses
+
+`devrites-doubt` and similar skills that "ask the user" follow this rule when
+`.devrites/AFK` exists:
+
+- Finding severity ≤ slice's gate ceiling (slice's `Gate:` plus `.devrites/AFK`
+  `allow_gates`) → log to `questions.md` as `gate: advisory`, record the trade-off in
+  `decisions.md`, proceed.
+- Finding severity > gate ceiling, OR finding touches the irreversible-risk list →
+  log to `questions.md` as `gate: blocking`, set `state.md` `Status: awaiting_human`,
+  fire `notify:`, STOP.
+
+The loop limits of the calling skill still apply — after the limit, the unresolved
+doubt becomes a blocking question regardless of AFK config.
+
+## Retry cap, stuck loops, and self-resolve
+
+- **Cap retries.** At most **3 attempts** on the same failing check (test, lint, type, build).
+  On the third failure, stop guessing and convert it to a `gate: blocking` question — a fourth
+  identical attempt is thrash, not progress.
+- **Stuck loops pause even in AFK.** A detected loop — the same action repeating, or an
+  action↔error ping-pong — pauses regardless of `allow_gates` (`devrites-engine stuck`), the same standing as
+  the irreversible-risk list. AFK widens what's automatic, never what's looping.
+- **Bias to self-resolve.** Before raising a question, try to answer it from the code, the docs,
+  or `decisions.md`. Communicate only for a blocked environment, a deliverable to hand over,
+  critical info you genuinely can't access, or a credential / permission you lack. This narrows
+  needless pauses and never weakens the blocking / escalating / irreversible gates.
+- **Human time is for human-only work.** A `human_intervention` pause is for what the agent
+  literally cannot do (create a cloud account, click a console button) — never for writing code,
+  writing tests, or reviewing. Punting the agent's own job to the human is not a valid gate.
+
+## What the rule does NOT cover
+
+This contract is about **human pauses**. It does not weaken or replace:
+
+- `$rite-prove`, `$rite-review`, `$rite-seal` — feature-scoped gates that always run.
+- Spec Drift Guard — answer that changes acceptance criteria routes through
+  `$rite-plan repair`, not silently into the slice.
+- `evidence.md` writes — every AFK iteration still records evidence; un-recorded passes
+  are unproven at `$rite-prove`.
+- `/clear` / `/compact` advice — context-hygiene rules are unchanged.
+
+AFK shifts the boundary between automatic and "ask"; nothing else.
+
+## Cross-reference
+
+- Skill: `$rite-resolve` (`.agents/skills/rite-resolve/SKILL.md`).
+- Workflow integration: `$rite-build` (`.agents/skills/rite-build/SKILL.md`),
+  workflow steps 0 + 2a (readiness / HITL pre-flight) and steps 4–6 (doubt / fail-on-red /
+  record) on the wright's return.
+- Render contract: `.agents/skills/rite-build/reference/checkpoint-protocol.md`.
+- Loop discipline: `.agents/skills/rite-build/reference/afk-discipline.md`.
+- Gate taxonomy: `.agents/skills/rite-define/reference/gates.md`.
+- Schema: `.agents/skills/rite-spec/reference/state-workspace.md`.
+- Doubt's AFK exception: `.agents/skills/devrites-doubt/SKILL.md` (AFK exception section).