# AFK & HITL: the pause/resume contract > Root-only: not inlined in --role bundles. > Applies when: any rite/devrites skill that can pause for a human or run unattended; irreversible-risk list, budgets, recovery accounting. Two pause modes for `rite-*`/`devrites-*`, chiefly `/rite-build`, `/rite-status`, `/rite-resolve`, `devrites-doubt`: one sentinel, queue, resume verb. ## Contents - [Run modes](#run-modes) - [The sentinel: `.devrites/AFK`](#the-sentinel-devritesafk) - [Unattended resource envelope](#unattended-resource-envelope) - [The four gates](#the-four-gates) - [Option set: how every gap is presented](#option-set-how-every-gap-is-presented) - [Decision ownership: search before asking](#decision-ownership-search-before-asking) - [Irreversible-risk list (always pause)](#irreversible-risk-list-always-pause) - [`questions.md` schema](#questionsmd-schema) - [`state.md` `Awaiting human` block](#statemd-awaiting-human-block) - [The resume verb: `/rite-resolve`](#the-resume-verb-riteresolve) - [AFK exception for discretionary pauses](#afk-exception-for-discretionary-pauses) - [Retry cap, no-progress loops, and self-resolve](#retry-cap-no-progress-loops-and-self-resolve) - [What the rule does NOT cover](#what-the-rule-does-not-cover) - [Cross-reference](#cross-reference) ## Run modes - **HITL (default):** human is present. At a gap/checkpoint the skill **asks inline** via the harness `ask_user_question` 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**. **If the current surface has no interactive question tool** (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 selection. 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 owns run mode; gate-deciding skills re-read it at decision time. No `state.md` run-mode field can drift out of sync. ## The sentinel: `.devrites/AFK` Presence = AFK active. The file body is optional YAML: ```yaml mode: autocomplete # optional controller identity; absent = standalone AFK max_slices: 10 # whole-workspace writer budget; seeds state.md remaining count max_agents: 32 # native agent dispatches in one host activation max_minutes: 120 # min; /rite-autocomplete: not a ceiling max_review_queue: 8 # unresolved review/gate items admitted before fan-out stops # max_tokens: 200000 # optional stricter host-observed token cap # max_cost_usd: 10 # optional stricter host-observed cost cap notify: 'curl -fsS -m 10 -d "$DEVRITES_QID: $DEVRITES_QUESTION" ntfy.sh/my-topic' # shell command; examples: .dsh/skills/rite-build/reference/afk-discipline.md allow_gates: [advisory, validating] # gate severities AFK auto-handles (auto-picks the recommended option) continue_sequence: true # after Seal GO, open the next recorded continuation max_workspaces: 5 # workspaces one armed sequence may open max_parallel: 10 # global writer cap; explicit --parallel N wins ``` AFK is read-only after entry. Explicit `/rite-autocomplete` upserts only `mode: autocomplete` and, with `--parallel N`, `max_parallel: N`; preserve other fields. Missing mode keeps standalone behavior; invalid/duplicate mode fails closed. Mode identifies scheduling, never grants phase, safety or Git authority. Outside active `/rite-autocomplete`, the following slice-budget rules apply: `max_slices` seeds root-owned `state.md` cursor `afk_slices_remaining` (released bullet alias: `AFK slices remaining: `). Accept either spelling; preserve table/bullet presentation. Before dispatch, require configured `max_slices` and existing remaining values to be decimal nonnegative integers; malformed or negative values fail closed. The pending → built state transition spends exactly one slice: on the first green slice write `max_slices - 1`, otherwise write `remaining - 1`, never below zero. Re-reading an already built slice does not spend again. At zero, stop before the next dispatch. A stricter post-planning budget may pre-seed `afk_slices_remaining` before first dispatch, not rewrite the sentinel: use the minimum of pending work and all configured/explicit caps. An existing counter may be lowered but never increased or reinitialized. It remains effective even if the sentinel omits `max_slices`. Under active `/rite-autocomplete`, skip these slice-cap checks, charges, zero stops, and minimum-cap seeding; use its [post-Vet budget](../../../rite-autocomplete/reference/loop.md#derive-the-mutable-post-vet-budget). ### Sequence continuation (`continue_sequence`, `max_workspaces`) `continue_sequence: true` opens the next **recorded** continuation after Seal GO. Under `/rite-autocomplete`, absent means on, even in existing sentinels; `false` opts out. `max_workspaces` (default 5): nonnegative decimal sequence budget, fail closed; charge new workspaces only, never resumes. `max_slices`/`afk_slices_remaining` stay **per workspace** outside active `/rite-autocomplete`, which uses its post-Vet pending count. The chain lives in root-owned `state.md` cursor fields, not in chat: `sequence_parent` (the immediately preceding workspace slug), `sequence_position` (1-based ordinal), `sequence_workspaces_remaining` (slots the chain may still open after this workspace), and — on the release milestone only — `sequence_role: release`. Seed exactly once from the recorded parent and its counter at creation. On resume, re-derive missing continuation fields from its `brief.md` parent/position and parent counter — same values, never a second charge. No recorded parent/position means no sequence membership. Counter only decreases; malformed values fail closed; `0` opens nothing. `sequence_role: release` makes `check candidate` and `check seal` require the candidate manifest to cover the whole recorded chain — run `devrites-engine state merge-manifest ` before Prove. - Only checked recorded continuations qualify, under the [sequence grammar](../workspace-artifact-schema.md#what-each-file-owns). No next entry or opening budget stops new openings, not existing child work. - Milestones are **not** shipped: they stay sealed and unarchived in `.devrites/work/` with `Next step: /rite-ship` preserved. Local `WIP():` checkpoints still land ([checkpoint.md](../../../rite-build/reference/checkpoint.md)), so the tree stays clean and crash-safe. - Git stays human-gated. The release ship is one disclosed plan, one literal `GO`, and one native approval; it collapses the sequence's `WIP` commits into the single release commit and may archive the sealed predecessors. - Human-owned, safety, access, and exhaustion stops remain. Active `/rite-autocomplete` recovers agent-owned Seal `NO-GO` per [stop-conditions.md](../../../rite-autocomplete/reference/stop-conditions.md), not a handoff. `--parallel N` wins over AFK `max_parallel`, else retained lease capacity on resume, else 10. Build's flag never rewrites AFK; explicit controller entry may update only mode/capacity. One cap covers all admitted sources, even explicit 1; standalone Build stays local. Follow the [global pass](../parallel-workspaces.md#continuous-global-frontier) for immediate-successor preparation, narrow `frontier-blocked` deferrals, qualified foreign `serial:` handoff and automatic dispatch-return scheduling. These are scheduling disclosures, never readiness, isolation, proof or Ship waivers. ## Unattended resource envelope Outside `/rite-autocomplete`, AFK writer admission needs a bounded input queue, effective slice cap, and valid `max_agents`, `max_minutes`, and `max_review_queue`. Existing sentinels that declare writer admission but miss/malform these fail closed (Autocomplete's sentinel omits them as unlimited; see below); cold resume keeps the state-owned slice counter. A leftover `expires_at` is ignored and never rewritten. Read-only watchers use equivalent native caps from [`loop-operations.md`](loop-operations.md). Outside active `/rite-autocomplete`, the following dispatch/queue limits apply: `max_agents` counts every leaf in the native activation, including failures and parallel branches; do not add dispatch telemetry to `.devrites/`. `max_review_queue` counts open validating questions plus unresolved admitted Critical/Important findings. Above it stop; at it run only reconciliation that reduces the queue. Optional `max_tokens`/`max_cost_usd` lower native caps in all unattended modes; if declared but unobservable, stop. `/rite-autocomplete` deliberately ignores `max_slices`, `max_agents`, `max_minutes` and `max_review_queue` ([stop-conditions.md](../../../rite-autocomplete/reference/stop-conditions.md)); not ceilings there. Numeric limits are nonnegative decimals. Before costly checks, fan-out, or writing, run cheap readiness and reject overlap. Outside active `/rite-autocomplete`, count queue and confirm agent/time headroom; under Autocomplete those ignored limits never block admission. In both cases confirm declared token/cost and native safety headroom; re-check after every result. Never start a call that can exceed an applicable remaining limit. Agent/time/token/cost counters are per native activation and start fresh only for a new activation. Slice/recovery state and review queue remain durable/recomputed across wakes. Persist stops/checkpoints before notification. Fresh AFK omits expiry and notification/token/cost caps. Standalone post-Vet counts may lower slices; preserve existing fields except controller entry above. Delete the file to restore HITL on the next invocation. ## The four gates Every `Mode: HITL` slice declares a `Gate:` and an `SLA:`. See [`.dsh/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 for HITL and for AFK `/rite-build`, regardless of `allow_gates`. **Autocomplete exception.** While `/rite-autocomplete` is the controlling caller, an open `gate: blocking` question that already carries a ranked recommended option (`proposed:` or option 1 labelled `(Recommended)`) is not a user handoff: the orchestrator auto-picks that option through `devrites-engine state resolve` and continues, including internal Spec Drift Guard when the answer changes ownership or acceptance. Escalating, irreversible-risk, access, and blocking questions with no recommended option still pause. Putting `blocking` in `allow_gates` does not replace this resolve step: an unanswered blocking question still fails Seal. 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-clarify`, `/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 has a **one-line, dimension-tagged rationale**: `logic · infra · business · architecture` (add `security` / `UX` / `risk` in scope) and trade-off. - Always include an escape hatch (`Something else — describe it`). - With more than four materially distinct choices, first ask a discriminating question or use sequential packets, then obtain final confirmation. Materially distinct options MUST NOT be silently dropped, merged, or preselected to fit the UI. - Recommend for project conventions, stack, scale, and domain, not a generic default. - **One visit per decision chain.** Ask the follow-ups an answer predictably triggers (a dependency's lock lines, a rerun after a failed measurement) in the same entry or one `--batch`; each link asked alone costs one human wait. **HITL** renders the set via `ask_user_question`; the human's pick resolves the gate **in place**. **AFK** auto-picks option 1 for gates it may auto-handle. Record the chosen option verbatim and keep the **rejected options in `questions.md`**. ## Decision ownership: search before asking First search live code, project/decision docs, and authoritative dependency sources; make and record reversible implementation/test choices. Ask only human-owned product, scope, acceptance, architecture-policy, irreversible-risk, or access/action choices. Objective test/build/tool failure runs bounded `devrites-debug-recovery`; fix it, or escalate and park it under the [retry contract](#retry-cap-no-progress-loops-and-self-resolve). Never ask permission for another attempt, test, parser repair, or probe. Close decisions at the earliest informed phase: product in spec, coverage in clarify, scope/risk in temper, architecture/dependencies in define, and proof/toolchain in vet. Build keeps only unavailable-pre-code or mandatory action-time checkpoints. ## 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. 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 requires the safe path; it does not cancel the work. A writer's overwrite or removal of a path outside the workspace that it created itself in the same wave is not destruction. The root proves it with each path's birth time (`stat -c %W`) at or after the wave's `started` time and the writer's ownership, records that evidence, and continues without a question. Any path it cannot prove pauses as above. By default, AFK widens what's *automatic*; it never widens what's *irreversible*. Red checks remain hard non-advance build gates, but are not inherently irreversible or human-owned; bounded recovery owns them. ## `questions.md` schema Append-only. One entry per qid. Format: ```markdown ## q-YYYY-MM-DD-NNN status: open | answered | dropped slice: gate: advisory | validating | blocking | escalating question: options: | # ranked option set; recommended FIRST (see "Option set") 1. (Recommended) — logic: … · infra: … · business: … · architecture: … 2. — 3. Something else — describe it proposed: raised_at: answered_at: answer: answered_by: human # only when a human resolved it (`state resolve --human`) ``` Rules: - `NNN` is sequential per date: the next-available 3-digit integer. - `state append` refuses a new open entry that breaks this schema (2-4 options plus the escape hatch, `(Recommended)` only on option 1); length is advisory. - `status: open` is the only state `/rite-resolve` can mutate; `answered` and `dropped` are terminal. - `answered_by: human` is written only by `state resolve --human`. HITL live picks and `/rite-resolve` pass `--human`; an AFK or autocomplete run never does, and the writer removes any `answered_by:` line (any indentation or case) from a qid it resolves without the flag. Only an unindented lowercase `answered_by: human` line counts as human resolution. - 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. AFK never authorizes destructive Git. The native host permission/sandbox boundary owns any such request and requires explicit user approval. ## `state.md` `Awaiting human` block When a HITL gate fires, `/rite-build` sets cursor `status` to `awaiting_human` and `next_action` to `/rite-resolve ""` via `devrites-engine state set` (under AFK it names questions the sentinel auto-picks: resolve those unless irreversible-risk), then writes the `Awaiting human` table (`question_id`, `gate`, `blocking_slices`) owned by [`state-workspace.md`](../../../rite-spec/reference/state-workspace.md#statemd-template) § state.md template. The question text, `proposed` answer, and `raised_at` live in the `questions.md` entry. Legacy `- Status:`/`- Next step:`/`- qid:` bullet keys are engine-accepted aliases, not the authoring format. `/rite-resolve` removes the block on success and sets cursor `status` to `running`. ## The resume verb: `/rite-resolve` Three shapes: ``` /rite-resolve "" /rite-resolve --drop [""] /rite-resolve --batch ``` `/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 `ask_user_question` 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 state resolve` writer**: one source of truth, two entry points (live pick vs typed verb). Use the writer; manual edits are never destructive-operation authority. 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 With `.devrites/AFK`, apply decision ownership first. Accepted in-scope technical corrections return to the caller for repair/verification; severity blocks acceptance, not authorized repair. Never silently accept a defect or broaden existing approval. Discretionary ceilings apply only to human-owned trade-off/risk decisions; accepted technical corrections do not enter these branches. Compare Suggestion/Nit/FYI→advisory, Important→validating, Critical→blocking against advisory < validating < blocking < escalating: - Within the slice's `Gate:` and `.devrites/AFK` `allow_gates`: record advisory in `questions.md`, trade-off in `decisions.md`, proceed. - Above ceiling, missing authority, or unapproved irreversible risk: record blocking question, `Status: awaiting_human`, fire `notify:`, STOP. Recovery uses only the [retry contract](#retry-cap-no-progress-loops-and-self-resolve). ## Retry cap, no-progress loops, and self-resolve Owns all phase recovery, including Doubt/Vet/serial/parallel Build. Resource, access, safety and irreversible-action boundaries independently stop work. - **Fingerprint the failed invariant, not the review round.** Identify owning invariant + defect mechanism + minimal reproduction/decisive failure signal. DEC/DRIFT IDs, line numbers, wording and splitting one cause create no new budget. - **Cap no-progress retries:** three no-progress attempts per exact causal fingerprint and strategy across wright/recovery. Only a correction whose narrow recheck leaves that cause open or reproduces its failure consumes an attempt. Closing a prior finding with discriminating evidence is progress: resolve it, do not charge. A new Critical or Important finding gets its own budget only for a distinct evidenced cause. The same invariant with a different evidenced mechanism qualifies; renaming/splitting an unchanged cause does not. Suggestion/Nit/FYI cannot extend recovery. Initial discovery and expected test-first RED are not corrections; total rounds, re-batches and distinct-finding counts never exhaust recovery. Every 5 Build wright rounds on one slice, the next first needs a reslice review ([`wright-dispatch.md`](../../../rite-build/reference/wright-dispatch.md#run)). - **Rechecks are scoped; late findings never reopen the round.** *Late* applies only from a phase's **second** review pass (Vet 1b, Build's recheck after the first repair, Review step 7); an initial pass has no late findings and every supported finding is folded normally. A recheck packet names the open fingerprints, the correction diff, and the dependents of each changed clause/hunk; the owning reviewer's verdict covers exactly that. A finding on text/code unchanged since that role's previous pass is *late*: Critical with a concrete failure path → new fingerprint under this budget; otherwise recorded (Plan/Vet: `eng-review.md` `## Deferred findings`; Build: `touched-files.md` `## Review trail`) with severity · site · role · kind · round, and consumed by the next full-inventory gate (Vet `mechanism` → one `test-plan.md` proof row; Build → the `/rite-review` roster) — never by another repair round in this phase. Review closes every deferred row with a labeled verdict; Seal blocks on any without one. A Vet write-set closure row (plan-reviewer dimension 6) is never late: it names an unbuilt slice's missing path and folds in this phase's one Plan repair, since deferring it only reopens Plan at that slice's Build entry. **Failing case:** round 4 finds three Important items on clauses untouched since round 1 and dispatches another repair. - **Recovery findings need a discriminator; recovery scope stays frozen.** While a fingerprint is in recovery, a new Important finding keeps it open or opens another only with an executed reproduction or a quoted AC/INV/PROH/accepted-DEC line whose observable outcome fails; root turns it into a control the next wright must pass. A static counterexample against plan-invented hardening goes to the Review trail or `## Deferred findings` (Review gives it a verdict; Seal blocks without one). A Critical with a concrete failure path always opens a fingerprint. A correction adds no proof site or mechanism its fingerprint's closure does not need. No reviewer is skipped. - **Separate consumptive authority from recovery.** Spent one-shot authorization blocks another execution, not offline recovery. Retained evidence starts caller-owned diagnosis/correction immediately; the next consumptive execution needs fresh authority. - **Persist existing records.** Put fingerprint, reproduction, correction, `progress: resolved|no-progress` and decisive result in `drift.md` and `evidence.md`. Cold resume derives counts there; no new counter file/command. - **Reconcile terminal cursors.** Retained distinct Critical/Important evidence below cap resumes despite stale `Next step: none`; age/spent action authority is not exhaustion. - **Escalate a spent strategy; never stop on it.** Three no-progress attempts spend the fingerprint's current *strategy*, not the work. Record that strategy and its attempts under `## Dead ends`, then the controlling caller escalates inline in the same invocation: re-diagnose from the reproduction and dead ends, take the first class below that still has an untried strategy, and resume with a fresh three-attempt budget. Re-plan only when the strategy must change a planning input (writer allowlist, interface or contract, slice topology, or a `test-plan.md` proof row): run `/rite-plan repair` plus narrow Vet for it. A strategy that fits the vetted plan, with `devrites-engine check readiness ` still passing, goes straight to the wright with the dead ends in its contract; Build's review and proof still gate it. Classes, in order, cheapest evidence before costliest change: (1) **shared root cause**: fix the owner every failing path routes through and enforce it across all callers instead of another local guard; (2) **diagnostic amplification**: add discriminating probes or fixtures, then correct from that evidence (last for a consumptive action, whose attempt needs fresh authorization); (3) **boundary redesign**: acceptance-preserving reslice or redesign of the failing seam, built on that evidence. A recorded strategy, or a rewording of one, never repeats. Escalation never weakens tests, validators or acceptance. Each fingerprint gets at most three escalations per activation; record each in `drift.md` with its class and strategy. - **Park, finish the rest, then stop once.** Human-owned contract/risk/access gaps open their gate. Otherwise, with every escalation spent, mark the fingerprint `parked` in `drift.md`, keep its reproduction and dead ends, and continue every step that does not depend on it. Only when nothing runnable remains, set `Status: blocked` and `Next step: — technical recovery parked; reinvoke to reopen with fresh escalation`. Emit no retry-permission question or `/rite-resolve`. A genuinely new user-issued activation appends `reopened: ` to each parked fingerprint and grants it three fresh escalations, counted from that line; wakes, compaction and nested re-entry of the same run never reset counts. - **Resolve agent-owned questions first** from code/docs/decisions. Human communication is for blocked environment, handover, inaccessible critical information or missing credentials/permission—not writing, testing or review. Blocking/escalating/ irreversible gates remain. ## 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 changes which decisions are automatic. It changes nothing else. ## Cross-reference - Skill: `/rite-resolve` (`.dsh/skills/rite-resolve/SKILL.md`). - Workflow integration: `/rite-build` (`.dsh/skills/rite-build/SKILL.md`), the readiness / HITL pre-flight stages before dispatch, and the DOUBT → PROVE (fail-on-red) → RECORD stages on the wright's return ([`one-slice-cycle.md`](../../../rite-build/reference/one-slice-cycle.md)). - Render contract: `.dsh/skills/rite-build/reference/checkpoint-protocol.md`. - Loop discipline: `.dsh/skills/rite-build/reference/afk-discipline.md`. - Gate taxonomy: `.dsh/skills/rite-define/reference/gates.md`. - Schema: `.dsh/skills/rite-spec/reference/state-workspace.md`. - Doubt's AFK exception: `.dsh/skills/devrites-doubt/SKILL.md` (AFK exception section).