devrites 2.6.1 → 3.0.1

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

@@ -0,0 +1,19 @@
+# /rite-adopt — anti-patterns
+
+Start with the universal table in [`../../devrites-lib/reference/standards/anti-patterns.md`](../../devrites-lib/reference/standards/anti-patterns.md).
+Below are the rationalizations specific to onboarding an existing codebase.
+
+## Adoption-specific rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "I'll improve this messy bit while I document it." | Adoption *documents* what exists; it changes nothing. A cleanup is the *next* feature through the normal lifecycle — recording it as a drive-by here hides the baseline and balloons the diff. |
+| "This looks like the convention, so I'll seed it." | Seed only what the code *actually and consistently* follows. A guessed seed becomes a high-confidence-looking prior that steers the first slice wrong. Observe it in ≥2 places or leave it out. |
+| "I'll spec the ideal architecture, not the current one." | The spec's baseline is *current behavior*. Aspirations go in the next objective, not the baseline — otherwise every later slice drifts against a spec that never matched reality. |
+| "Whole repo in one adopt." | Onboard the area you'll actually work in. A repo-wide adopt produces an unfocused spec and a ledger full of conventions no slice will touch. |
+
+## Red flags
+
+- A seeded convention with no concrete code location behind it.
+- `spec.md` describing behavior the code does **not** currently have (that's the next feature, not the baseline).
+- Editing source during adoption — adoption writes `.devrites/` + the ledger, never project code.

package/pack/generated/claude/skills/rite-autocomplete/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: rite-autocomplete
+description: Run the DevRites lifecycle end-to-end unattended; --ship confirms the final gate. Use when the user says "autocomplete", "one-shot this feature", or "ship it autonomously". Not for a single phase.
+argument-hint: "[idea] [--ship|--yolo] [--max-slices N]"
+user-invocable: true
+---
+
+# /rite-autocomplete — full lifecycle, unattended
+
+Drives every DevRites phase in order without stopping for discretionary input. The
+prompt may be vague — autocomplete asks its clarifying questions **up front**, then
+runs to completion. It does **not** disable the safety gates: hard irreversible-risk,<!-- pack-scan-ignore: negated statement — gates are NOT disabled -->
+blocking / escalating gates, and any NO-GO still pause.
+
+## Rules consulted (read on demand from `.claude/skills/devrites-lib/reference/standards/`)
+**Step 0:** Read `.claude/skills/devrites-lib/reference/standards/core.md` and `.claude/skills/devrites-lib/reference/standards/afk-hitl.md` first.
+
+## Operating rules
+- **One human window.** Clarifying questions are batched up front via
+  `devrites-interview`. After that, discretionary decisions are made automatically and
+  recorded in `decisions.md` — not asked. See [reference/decision-policy.md](reference/decision-policy.md).
+- **Safety gates are not bypassable.** AFK never auto-passes destructive migration /
+  auth-authz change / public-API break / external-contract change / red tests; blocking
+  and escalating gates and any open `gate: validating` always pause. `--ship` auto-confirms
+  the **final** type-GO only — nothing else. A change that violates a declared project
+  principle (`.devrites/principles.md`) with no recorded exception pauses too — autocomplete
+  never grants a principle exception on its own (`principles.md`: that's a human decision).
+- **Loop budget = the plan's own slice count, not a fixed number.** After `/rite-vet`
+  (not `/rite-define` — vet may split or add slices, so the count isn't final until then),
+  set the AFK budget to however many slices the plan has, so the loop builds exactly the
+  task's slices and stops when they're done. `--max-slices N` is an OPTIONAL *lower* safety
+  cap (partial / babysat run); omit it to run the whole plan. The budget is finite
+  (= planned slices), so a runaway is still bounded.
+- **Best option, recorded.** For each discretionary choice, pick the option the relevant
+  specialist / reviewer favours and record the rationale. Never silently coin-flip.
+- **Strategic review runs, but never auto-grows scope.** After `/rite-spec`, run `/rite-temper`
+  (significance-gated — it skips low-stakes specs in one line). Unattended it auto-applies only
+  `hold-rigor` + `reduce-to-MVP` (these never grow acceptance); **any `expand` is a blocking
+  pause**, and irreversible-risk findings always pause. Autocomplete hardens and may *prune* the
+  spec on its own; it never *expands* the build's scope without the human.
+- **Engineering review runs on every plan, but never auto-grows scope.** After `/rite-define`,
+  run `/rite-vet` on **every** feature (depth scales — a light pass on simple plans, full rigor on
+  big/risky; never skipped). Unattended it auto-applies only *hardening* findings — added test
+  requirements, error-handling / failure-mode coverage, tightened scope, reuse-over-rebuild,
+  ordering / parallel-lane fixes (these never grow acceptance); **any finding that grows scope,
+  adds a slice, or changes acceptance is a blocking pause**, and irreversible-risk findings always
+  pause. Cross-model is off unless `--cross-model` was armed.
+
+## Workflow
+1. **Orient + parse args.** Run `devrites-engine preamble` for deterministic workspace orientation.
+   The idea + flags: `--ship` / `--yolo` (auto-confirm the final
+   type-GO), `--max-slices N` (OPTIONAL *lower* safety cap for a partial run; default =
+   the plan's slice count, i.e. run all planned slices).
+2. **Clarify up front.** If the idea is underspecified, run `devrites-interview` to
+   ~95% confidence — the only interactive window. If already clear, skip.
+3. **Arm AFK.** Write `.devrites/AFK` with `allow_gates: [advisory]`; set the slice budget
+   from the plan's count after `/rite-vet` (the slice count is only final post-vet), or from
+   an explicit `--max-slices` ([reference/loop.md](reference/loop.md)). validating / blocking / escalating +
+   irreversible-risk still pause. Also `touch .devrites/CHECKPOINT` — an unattended run is the
+   case checkpoint mode earns its keep, so each proven slice is committed local-only as
+   crash-survivable `WIP` ([rite-build/reference/checkpoint.md](../rite-build/reference/checkpoint.md));
+   `/rite-ship` collapses them into the one feature commit.
+4. **Drive the phases** ([reference/loop.md](reference/loop.md)): `/rite-spec` →
+   **`/rite-temper`** → `/rite-define` → **`/rite-vet`** → `/rite-build` (loop until all slices
+   built; `devrites-engine tick-afk` each) → `/rite-prove` → `/rite-polish` → `/rite-review` → `/rite-seal`.
+   Run each by Reading its `SKILL.md` and executing its workflow; state is carried by the
+   workspace files, not chat.
+5. **Apply stop conditions at every gate** ([reference/stop-conditions.md](reference/stop-conditions.md)):
+   on hard-risk / blocking / escalating / NO-GO / budget-exhausted / still-low-confidence
+   → write `state.md` (`Status`, `Next step`), surface *why*, and **STOP**.
+6. **Seal GO → ship.** With `--ship`, proceed to `/rite-ship` and auto-confirm the
+   type-GO. Without it, render the type-GO prompt and stop for the human.
+
+> **Mid-flight discipline.** When tempted to auto-pass a blocking gate "to keep moving",
+> answer a material question yourself instead of pausing, or run past red tests — stop.
+> Autonomy is for the routine path; the gates exist for everything else.
+
+## Output
+A compact phase-by-phase log, then the final status. **Progress first for the final
+status** — run `devrites-engine progress`, then use the shared typed states from
+[`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md):
+`Shipped`, `Stopped`, `Awaiting human`, `NO-GO`, or `GO`.
+
+Keep the log terse:
+```
+Autocomplete: <slug>
+spec <done|stopped> · temper <done|skipped|stopped> · define <done|stopped> · vet <done|stopped> · build <n/N|stopped> · prove <done|stopped> · polish <done|stopped> · review <done|stopped> · seal <GO|NO-GO|stopped>
+```
+
+Final state examples: `Shipped: <feature>`, `Stopped: <reason>`, `Awaiting human:
+<qid> · <gate> · <slice/phase>`, `NO-GO: <verdict>`, or `GO: feature cleared to ship`.
+Do not write a narrative recap.
+
+## Clean baseline and checkpoint mode
+- Before an autonomous run, require a clean or explicitly accepted baseline: refuse unrelated dirty work and record expected planning artifacts.
+- Arm `.devrites/CHECKPOINT` for the run so each proven slice can be checkpointed local-only; `/rite-ship` owns collapsing those checkpoints.
+- Stop on risky steps, red gates, NO-GO, stale evidence, or budget exhaustion.
+- Autocomplete gets one approved pass through the lifecycle; `/rite-build` still builds exactly one slice per invocation.

package/pack/generated/claude/skills/rite-autocomplete/reference/decision-policy.md

@@ -0,0 +1,35 @@
+# Decision policy — how autocomplete "chooses the best option"
+
+Unattended ≠ careless. Every discretionary choice is made the way a senior engineer
+would, then **recorded** so the seal can audit it. The difference from interactive mode
+is only *who answers* a discretionary question — not whether it's reasoned.
+
+## The rule
+
+For each non-trivial choice, pick the option the **relevant specialist favours**, and
+write the choice + the one-line rationale to `decisions.md`. Do not coin-flip, and do
+not pick the option that's merely easiest to implement.
+
+| Choice type | Defer to | Then |
+|---|---|---|
+| Uncertain framework / library behaviour | `devrites-source-driven` (check the docs/source) | record the source in `evidence.md` |
+| Risky boundary / data-model / API decision | `devrites-doubt` (+ `devrites-doubt-reviewer`) | record the trade-off in `decisions.md` |
+| Cross-boundary contract (FE/BE split, API shape) | `devrites-api-interface` | contract-first slice |
+| UI surface / states / a11y | `devrites-frontend-craft` | shape before code |
+| Two reasonable designs, no clear winner | the simpler one that meets acceptance | note why in `decisions.md` |
+
+## Defaults autocomplete may assume (record them)
+
+- Follow the project's existing conventions, components, and test commands — always.
+- Prefer the smallest vertical slice that proves the acceptance criterion.
+- Reuse → extend → build new, in that order (`coding-style.md`).
+- When two options are equivalent on the evidence, choose the lower-risk / more
+  reversible one.
+
+## When a choice is NOT autocomplete's to make
+
+If a discretionary choice would change **product behaviour, scope, data model, security
+posture, or acceptance criteria**, it is no longer discretionary — it is a material
+question. Route it through the Spec Drift Guard / a `blocking` question and **stop**
+(see [stop-conditions.md](stop-conditions.md)). Autocomplete answers *how*, never
+*what to build* beyond what the up-front interview settled.

package/pack/generated/claude/skills/rite-autocomplete/reference/loop.md

@@ -0,0 +1,54 @@
+# The autocomplete loop — arm AFK, drive every phase
+
+Autocomplete is an orchestrator: it runs the existing `/rite-*` skills in order,
+exactly as a human would, but without stopping between them. It owns no workflow of
+its own — the phases do the work; autocomplete sequences them and enforces stops.
+
+## Arm AFK
+
+Arm the gate policy up front; set the slice budget once the plan's count is known:
+
+```yaml
+allow_gates: [advisory]        # only advisory auto-handles; validating+ pause
+# notify: "<cmd>"              # optional — fired on any awaiting_human pause
+# max_slices: <N>              # the slice BUDGET — set from the plan's count after
+# /rite-define (or an explicit --max-slices). NOT a target decomposition; it only
+# caps how many run unattended (default = all the plan's slices).
+```
+
+The budget is the plan's own slice count, not a fixed number — so the loop builds exactly
+the task's slices and stops when they're done; `--max-slices N` only *lowers* it for a
+partial run. Arm the gate policy at step 3; write `max_slices` / `AFK slices remaining`
+**after `/rite-vet`** (it runs before the build loop and may split or add a slice, so the
+count isn't final until then — vet runs on every plan here, so always set the budget after it).
+
+`allow_gates: [advisory]` is deliberate: an open `gate: validating` is merge-blocking
+at seal (`afk-hitl.md`), so autocomplete must *pause* on it rather than queue it and
+then hit NO-GO. Widen `allow_gates` only if the caller explicitly asked.
+
+## Drive the phases
+
+Run each by Reading its `SKILL.md` and executing that workflow. State flows through the
+workspace files (`state.md`, `tasks.md`, `evidence.md`, …), so each phase picks up where
+the last left off — there is nothing to thread through chat.
+
+| Step | Phase | Loop / gate |
+|---|---|---|
+| 1 | `/rite-spec` | feed the interview answers; write `spec.md` |
+| 2 | `/rite-temper` | significance-gated strategic review; harden spec + write `strategy.md`. Skip low-stakes specs in one line. AFK: `hold-rigor` / `reduce-to-MVP` auto-apply; **any `expand` pauses (blocking)**; irreversible-risk pauses |
+| 3 | `/rite-define` | reads `strategy.md`; `plan.md` + `tasks.md`; record `Plan approved` |
+| 4 | `/rite-vet` | engineering plan review on **every** plan (light pass on simple plans, full on big/risky; never skipped); harden `plan.md` / `tasks.md` + write `eng-review.md` + `test-plan.md`. AFK: hardening / coverage findings auto-apply; **any scope-growing / acceptance-changing finding pauses (blocking)**; irreversible-risk pauses. Set the slice budget after this (vet may split a slice) |
+| 5 | `/rite-build` ×N | **loop** while any slice is `pending`; build one (the slice-wright reads `test-plan.md` for coverage), then run `devrites-engine tick-afk state.md` — exit 3 (budget hit) ⇒ STOP |
+| 6 | `/rite-prove` | once all slices `built`; walks `test-plan.md`; on failure → `devrites-debug-recovery` within scope |
+| 7 | `/rite-polish` | re-verify after code edits (evidence must stay fresh) |
+| 8 | `/rite-review` | apply in-scope fixes; re-prove if code changed |
+| 9 | `/rite-seal` | GO/NO-GO decision (no git here) |
+| 10 | `/rite-ship` | only if seal GO; `--ship` auto-confirms type-GO, else stop for human |
+
+## Between phases
+
+- Re-read the active workspace before each phase (don't trust chat memory).
+- After a phase that edits code (build, polish, review), evidence may be stale — let
+  the next gate re-prove rather than carrying a stale pass (see
+  `.claude/skills/devrites-lib/reference/standards/development-workflow.md`).
+- Check [stop-conditions.md](stop-conditions.md) at every gate **before** advancing.

package/pack/generated/claude/skills/rite-autocomplete/reference/stop-conditions.md

@@ -0,0 +1,59 @@
+# Stop conditions — when autocomplete must pause for a human
+
+Autonomy covers the routine path. These are the cases where autocomplete writes
+`state.md` (`Status: awaiting_human` or `blocked`), surfaces *why* + the single resume
+command, fires `notify` if set, and **stops**. None are bypassable by `--ship`.
+
+## Always stop (irreversible-risk list — from `afk-hitl.md`)
+
+Regardless of `allow_gates` or `--ship`:
+- Destructive data migration (drop column/table, irreversible backfill).
+- Auth / authz boundary change.
+- Public-API break (response shape, removed endpoint, changed status semantics).
+- External-service contract change.
+- Filesystem destruction outside the workspace.
+- Red tests / types / lint at slice end (fail-on-red).
+
+## Stop on gate severity
+
+- `blocking` gate fires → synchronous pause.
+- `escalating` gate fires → pause, route to the specialist tag.
+- Any `questions.md` entry with `gate: validating` and `status: open` → pause (it is a
+  seal NO-GO by definition; don't sail into a guaranteed NO-GO).
+
+## Stop on strategic-review scope expansion (`/rite-temper`)
+
+- `/rite-temper` choosing scope mode `expand` — or otherwise **adding** any acceptance
+  criterion to `spec.md` — → synchronous pause, regardless of `allow_gates` / `--ship`.
+  Autocomplete may auto-apply only `hold-rigor` and `reduce-to-MVP` (they harden / prune and
+  never grow the build's scope); **growing scope unattended is never automatic**. A low-stakes
+  spec that temper skips, or a `hold-rigor` / `reduce-to-MVP` run, does **not** pause.
+
+## Stop on workflow state
+
+- **NO-GO at seal** → stop; surface every blocker with `file:line` and the fix
+  direction. Do not round NO-GO up to GO.
+- **Spec Drift Guard fires** (`/rite-build` finds the plan is wrong and the change
+  alters product behaviour) → stop; route through `/rite-plan repair`.
+- **Budget exhausted with slices still pending** — `devrites-engine tick-afk` exit 3 while `tasks.md`
+  still has unbuilt slices (only when an explicit `--max-slices` capped the run below the
+  plan's count) → stop; report slices remaining. Exhausting the default budget = all
+  planned slices built = normal completion → continue to `/rite-prove`, don't pause.
+- **Still low-confidence after the interview** — the idea can't be pinned to testable
+  acceptance criteria → stop and ask, rather than guessing the product.
+- **Repeated failure** — a phase fails, `devrites-debug-recovery` can't fix it within
+  scope after a bounded number of attempts → stop with the reproduction.
+
+## The final type-GO
+
+- Default: render the type-GO prompt at `/rite-ship` and **stop** for the human's
+  literal `GO`.
+- With `--ship` / `--yolo`: auto-confirm the type-GO (the *only* thing the flag changes).
+  Everything above still pauses.
+
+## How to stop well
+
+State must be enough for a fresh agent to resume cold:
+- `state.md`: `Status`, the blocking reason, and a single `Next step` command.
+- The relevant `questions.md` / `drift.md` / `seal.md` entry that explains the pause.
+- A one-line user-facing message: *what* stopped it and *what command* resumes.

package/pack/generated/claude/skills/rite-build/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: rite-build
+description: Build one approved vertical slice, then stop with evidence. Use when the next planned slice should be implemented. Not for multiple slices.
+argument-hint: "[slice number or name]"
+user-invocable: true
+---
+
+# /rite-build — one verified slice
+
+Build the next single slice, leave it working and proven, then **stop**. **Read the
+active workspace first**; if none, tell the user to run `/rite-spec <feature>`.
+
+This skill is the **orchestrator**: it owns the gates and the workspace; a fresh-context
+[`devrites-slice-wright`](../../agents/devrites-slice-wright.md) owns the **writing**. You run
+pre-flight (readiness, slice select, HITL pause), dispatch the wright for the build core, then
+run the post-return gates (doubt, fail-on-red, record, stop). See
+[`reference/wright-dispatch.md`](reference/wright-dispatch.md).
+
+## Rules consulted (read on demand from `.claude/skills/devrites-lib/reference/standards/`)
+Read `.claude/skills/devrites-lib/reference/standards/core.md` first (workflow step 0). The
+following load on demand — **the wright reads them** (they are named in its contract) while it
+writes; read them yourself for the doubt/record gates or in the inline fallback:
+- `coding-style.md` — naming, function shape, guard clauses, comments, reuse-first.
+- `error-handling.md` — fail fast, no silent catches, fail closed.
+- `testing.md` — pyramid, behaviour over implementation, see-it-fail-first.
+- `patterns.md` — composition over inheritance, avoid premature abstraction.
+- `principles.md` — the project invariants (`.devrites/principles.md`) the slice must honor; the wright reads them as **binding**, not priors.
+- `security.md` — when the slice touches user input, auth, data, or external integrations.
+- `definition-of-done.md` — standing Done bar: acceptance mapped, fresh proof, no open hard gates, scoped edits, rollback/docs where needed.
+
+
+## Operating rules
+- **One slice at a time. DO NOT** start the next slice without the user asking.
+- Evidence over confidence. Prefer existing conventions. Feature scope only — no
+  drive-by refactors.
+- **Noticed, not touched.** An adjacent smell the wright sees outside `touched-files.md` is
+  recorded as an FYI follow-up in `decisions.md`, never fixed inline — the slice's change summary
+  states what it *deliberately left alone* ([`git-workflow.md`](../devrites-lib/reference/standards/git-workflow.md) "Things
+  I didn't touch"), so the reviewer reads a feature-scoped diff, not a renovation. The `devrites-engine reconcile`
+  gate (step 6) enforces this by exit code.
+- **Don't re-run an unchanged check.** Re-running the same build/test command on code that hasn't
+  changed since proves nothing new — it's motion, not evidence. Re-verify after an edit, not before.
+- Surface material assumptions; ask before adding dependencies or a second design
+  system. The [Spec Drift Guard](reference/spec-drift-guard.md) is active throughout.
+- **Avoid AI slop while writing.** `devrites-slice-wright` enforces the anti-slop charter **at
+  the source** — the canonical do-not list is `rite-polish/reference/anti-ai-slop.md` (the
+  wright reads it; don't restate it here). It writes the code the *project* would write, in its
+  idiom, reusing before building; **you verify the charter held on return** — you do not re-list
+  it and you do not fix slop by editing source. Polish catches what slips; build prevents.
+  The **prose you write yourself** — `evidence.md`, `decisions.md`, the slice report — follows
+  the human-voice charter (`.claude/skills/devrites-lib/reference/standards/prose-style.md`; depth in `devrites-prose-craft`): no
+  filler openers, no marketing adjectives, exact commands and identifiers kept verbatim.
+- **Honor declared project principles.** The wright reads `.devrites/principles.md` and treats
+  each invariant as **binding** (not a prior to weigh like a convention) — a slice it cannot build
+  without breaking one is an **Escalation**, not a silent violation. On return **you verify no
+  principle was broken**; a fresh violation is handled like any irreversible-risk item — a
+  human-approved, scoped exception in the register or a stop, never folded into the slice. No
+  `.devrites/principles.md` → none declared → nothing to honor.
+- **You never edit source — the wright is the only writer of code + tests.** You write only
+  `.devrites/` bookkeeping. On any red gate, doubt finding, or coverage gap your only remedies
+  are **continue the same wright once** (it fixes in its own context) or **stop + escalate** —
+  never patch the code yourself. The `devrites-engine reconcile` gate (step 6) enforces this by exit code:
+  any source file changed outside the wright's claimed set is a hard STOP.
+- **A `Forge: yes` slice competes candidates — one author still lands.** When `/rite-vet`
+  flagged the slice a genuine architecture fork, step 3 runs K=2–3 candidate wrights in
+  **isolated worktrees** and lands exactly one winner's diff; the single-writer invariant holds
+  because no tree ever has two authors and only the winner reaches the working tree. You still
+  never edit source, and reconcile runs against the winner's claimed set. The default slice is
+  single-path — forge is the rare exception ([`reference/forge.md`](reference/forge.md)).
+
+## Workflow
+
+Run the full execution contract in
+[`reference/phase-contract.md`](reference/phase-contract.md). It is not optional:
+it contains the gated one-slice workflow, including readiness, HITL/AFK handling,
+wright dispatch, forge, doubt, fail-on-red, record gates, and stop behavior.
+
+## Output
+
+Use the full output contract in [`reference/output.md`](reference/output.md).
+It preserves the progress-footer-first response shape, uses the shared completion
+reply contract
+([`devrites-lib/reference/reply-contract.md`](../devrites-lib/reference/reply-contract.md)),
+and keeps the explicit stop after one slice.

package/pack/generated/claude/skills/rite-build/reference/afk-discipline.md

@@ -0,0 +1,145 @@
+# AFK discipline — running `/rite-build` unattended without burning the trunk
+
+AFK mode is `.devrites/AFK` present. It lets `/rite-build` chain slices without per-slice
+user input. The discipline below is what keeps an AFK loop from drifting into damage.
+
+The core principles are borrowed from established autonomous-coding loops (Ralph Wiggum,
+Claude Code auto mode):
+
+1. **Feedback loops are the trust substrate.** No green tests / types / lint → no
+   "built" status. The loop can't declare victory if the lights are red.
+2. **Always cap iterations.** Stochastic systems + infinite loops = unsafe. `max_slices`
+   is the hard counter.
+3. **Promote pre-action gates, demote post-action gates.** Code that lands without a
+   gate is a finding; gates after the fact are review queues.
+4. **AFK widens what's automatic, never what's irreversible.** Destructive work, auth
+   boundaries, public API breaks always pause regardless of the sentinel.
+
+## The sentinel file
+
+`.devrites/AFK` (presence = AFK). Optional YAML body:
+
+```yaml
+max_slices: 10                       # read-only INITIAL budget; seeds state.md on first AFK build
+notify: "ntfy.sh/my-topic"           # shell command run on awaiting_human transition
+allow_gates: [advisory, validating]  # gate severities AFK may auto-handle
+```
+
+`.devrites/AFK` 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`
+(see "Iteration cap").
+
+Defaults when keys are omitted:
+- `max_slices`: unlimited (a missing cap is risky — see "Always cap iterations").
+- `notify`: none.
+- `allow_gates`: `[advisory]`.
+
+To disable AFK temporarily, delete the file. The next `/rite-build` boots straight back
+into HITL.
+
+## Iteration cap
+
+`/rite-build`'s **record step** (workflow step 6) decrements `state.md`'s `AFK slices
+remaining` by 1 each time a slice is marked `built`, by running
+`devrites-engine tick-afk <state.md path>`. The script reads the
+field, decrements, writes it back, prints the new value, and **exits `3` when it hits 0**.
+The cap is enforced by `devrites-engine tick-afk`, not by prose — when it exits 3:
+
+- `/rite-build` treats exit 3 as a forced HITL stop:
+  ```
+  AFK cap reached. Raise `state.md` `AFK slices remaining` or remove the sentinel to continue.
+  ```
+- The workspace stays consistent — no half-built slice, no pending question.
+
+Step 0 re-derives the remaining budget from `state.md` (seeding it from `.devrites/AFK`
+`max_slices` on the first AFK build); `max_slices` itself is read-only and never rewritten.
+
+The cap is intentional: a missing or large cap **must be a conscious choice**. Ralph's
+rule: 5-10 iterations for small tasks, 30-50 for larger ones. Don't ship "unlimited" as
+the default for a job you haven't observed running once HITL.
+
+## Fail-on-red
+
+The **fail-on-red step** (workflow step 5) refuses to mark a slice `built` if targeted tests /
+types / lint are red. The reasoning:
+
+- A red signal means either the slice's contract is wrong or the failing code is. Neither
+  is something AFK can resolve.
+- Marking it `built` and letting the AFK loop chain to the next slice burns the trunk —
+  the next slice builds on broken state.
+
+The fail-on-red path:
+
+1. Append a question to `questions.md` with `gate: blocking`, the SLA of the slice, and a
+   crisp `question:` field naming what failed.
+2. Set `state.md` `Status: awaiting_human` and the `Awaiting human` block.
+3. Fire the `notify:` hook if defined.
+4. STOP.
+
+The user resolves via `/rite-resolve` after diagnosing or re-planning.
+
+## Irreversible-risk list (always pause)
+
+Regardless of `allow_gates`, AFK invokes the checkpoint protocol when the slice touches
+any of:
+
+- Destructive data migration (drop column, drop table, irreversible backfill).
+- Auth / authz boundary change (new role, changed permission check, new public auth endpoint).
+- Public API break (response shape change, removed endpoint, changed status code semantics).
+- External-service contract change (webhook payload, partner-facing schema).
+- Filesystem destructive operation outside the workspace (`rm -rf` of project paths,
+  rewriting `.gitignore`-listed paths, deleting fixtures).
+- Anything the slice's `Gate: blocking` plus `tasks.md` `Why HITL:` flags as irreversible.
+
+The list is the same one Claude Code auto-mode's transcript classifier protects — adapted
+to DevRites's workspace shape.
+
+## The `notify:` hook contract
+
+The hook is a single shell command run on the `awaiting_human` transition. Environment
+the hook receives:
+
+| Var | Value |
+|---|---|
+| `DEVRITES_QID` | the new qid (e.g. `q-2026-05-28-001`) |
+| `DEVRITES_GATE` | `advisory` / `validating` / `blocking` / `escalating` |
+| `DEVRITES_SLICE` | `<N — name>` |
+| `DEVRITES_SLUG` | active feature slug |
+| `DEVRITES_QUESTION` | the checkpoint text |
+| `DEVRITES_PROPOSED` | the proposed answer |
+
+The hook is best-effort: non-zero exit does **not** roll back the pause. Failures are
+logged to `evidence.md` so the user sees them on return.
+
+Example targets:
+- `curl -d "$DEVRITES_QID: $DEVRITES_QUESTION" ntfy.sh/my-topic`
+- `osascript -e "display notification \"$DEVRITES_QUESTION\" with title \"DevRites: $DEVRITES_GATE\""`
+- `pb push "$DEVRITES_SLUG: $DEVRITES_QUESTION"` (via pushbullet CLI)
+
+DevRites owns no notification logic — the hook is a seam, not a feature.
+
+## When to leave AFK
+
+Drop the sentinel before:
+
+- A novel feature where you have not yet seen `/rite-build` work on this codebase HITL —
+  Ralph's progression: HITL first → refine prompt → AFK once trusted.
+- A risky slice you marked `Mode: HITL` and want to walk through interactively even if
+  the gate is technically `validating`.
+- Any time you'd rather review per-slice than batch-resolve afterwards.
+
+AFK is a **bias toward continuing**, not a vow. Re-enter it whenever the next stretch of
+work is bulk + low-stakes.
+
+## What AFK does NOT do
+
+- It does not bypass `/rite-prove`, `/rite-review`, or `/rite-seal`. Those gates are
+  feature-scoped and always run when their phase runs.
+- It does not skip `/rite-plan repair` on Spec Drift Guard fires.
+- It does not skip `devrites-source-driven` checks. Uncertain framework behavior still
+  triggers the doc lookup.
+- It does not skip `evidence.md` writes. AFK runs that don't record evidence are
+  unproven and get rejected at `/rite-prove` regardless.
+
+The sentinel widens *human pauses*, nothing else.

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

@@ -0,0 +1,37 @@
+# rite-build — anti-patterns
+
+Load this when standing a non-trivial implementation decision, or when the
+agent feels reluctance toward stopping after one slice, applying TDD, or
+calling `devrites-doubt`.
+
+Pack-wide rationalizations + red flags (incl. tests-later, defensive checks,
+generic AI naming, drive-by refactors): see
+[standards/anti-patterns.md](../../devrites-lib/reference/standards/anti-patterns.md).
+
+## Phase-specific rationalizations
+
+| Excuse | Rebuttal |
+|---|---|
+| "Slices 1 and 2 are related; let me do both." | One slice, then stop. Full stop. The user asks for the next. |
+| "It's faster to skip `devrites-doubt` for this small change." | Doubt is cheapest *before* the decision is standing. After is debugging. |
+
+## Forge ([forge.md](forge.md))
+
+| Excuse | Rebuttal |
+|---|---|
+| "This slice is hard — I'll forge it." | Hard ≠ forkable. Forge competes ≥2 *genuinely-different* approaches with no clear winner. One hard approach is single-path; building it K times wastes K× for one answer. |
+| "I'm not sure which approach is right, so let me compete them and decide." | Forge is for a real fork the plan couldn't settle, not for dodging a decision you can make now. Decide from the code/docs first; forge only when the alternatives are genuinely undecidable on paper. |
+| "Candidate A's data layer plus B's UI would be the best of both." | Don't hand-merge candidates — two authors in one tree is the incoherence the single-writer rule exists to prevent. Land one winner whole; graft a *specific* runner-up idea only by continuing the winning wright once. |
+| "The judge already scored these, so I can skip the post-return doubt." | The judge picks *between* candidates; it doesn't replace doubting the winner's standing decisions. Steps 4–7 run on the winner unchanged. |
+| "A fourth candidate might be even better." | K is capped at 3. A fourth rarely moves the winner and multiplies cost; if none of three is right, the plan is wrong — `/rite-plan repair`, don't add candidates. |
+
+## Red Flags
+
+- About to start slice N+1 without the user asking.
+- Skipping `devrites-doubt` on a branching, boundary, data-model, auth, public-API, or migration decision.
+- Adding a dependency or a second design system without recording rationale in `decisions.md`.
+- Writing a `try/catch` block wider than what you actually handle.
+- A comment that restates what the next line does.
+- Touching files that aren't in `touched-files.md` for "tidiness".
+- Forging a slice with no acceptance / `test-plan.md` coverage for the judge to score against.
+- Landing more than one candidate's code, or keeping a losing worktree/branch around after F7.