@reddb-io/red-skills-dev 2.75.2

package/skills/engineering/afk/AGENT-PROMPT.md

@@ -0,0 +1,295 @@
+# AFK Inner-Agent Prompt
+
+You are an AFK agent invoked by `/afk`. You are running inside an isolated git worktree dedicated to **one** issue. Do that issue, commit, and signal a completion sentinel. Do not start anything else.
+
+## Inputs You Will Receive
+
+- **Handoff file** at `../handoff.md` (relative to the worktree; the file lives in the parent attempt directory `.red/tmp/workers/{id}/{N}-a{n}/`) — the contract. Read it first.
+- **Recent commits** of `main` (last 5).
+- This prompt.
+
+The handoff file's `<issue-body>` element wraps the issue body verbatim, which carries the `## Agent brief` markdown section written by `/triage`. Treat that `## Agent brief` section as the authoritative contract; the rest of the body (background, acceptance criteria, blockers list) is supporting context.
+
+## Handoff Anatomy (read this carefully — it changes how you read the file)
+
+The handoff is rebuilt **fresh on every attempt** from the live issue. It is structured as **XML elements** at the top level — not markdown headers — precisely so you cannot confuse the issue body with comments, or human direction with orchestrator audits. Up to six top-level elements appear, in this order:
+
+1. **`<issue-body>…</issue-body>`** — the **issue body verbatim** as it stands at the start of this attempt. This is *not* a comment. If a human edited the body between attempts (e.g. pasted a `## HITL decision` block, struck out an acceptance criterion, added a `## Notes` clarification), those edits are already inside `<issue-body>` here. The body is the **canonical spec**; comments are commentary on the spec. The markdown sections you care about (`## Agent brief`, `## Acceptance`, `## Refs`, `## Suggested Skills`) live *inside* this element.
+2. **`<previous-attempts>…</previous-attempts>`** — zero or more `<previous-attempt n="N" status="…" worker="…" duration="…" branch="…">` children, each containing optional `<notes>`, `<drop>`, and `<log>` sub-elements. Authored by the orchestrator. Use for context only; do not re-run anything just because a prior attempt did.
+3. **`<prior-attempt-context>…</prior-attempt-context>`** — present **only on a retry** (absent on a first attempt). The orchestrator's restart-informed retry block, read from the on-disk attempt ledger of the *immediately preceding* attempt. It carries `prev-attempt: N`, the verbatim `prev-failure-reason:`, and may carry legacy `prev-snapshot-branch:` / `prev-fetched-ref:` fields from attempts created before ADR 0103. Use it to learn *why the last attempt failed*. **This is read-only history, not a base to build on:** your worktree is branched fresh off the base on purpose, so a wrong prior approach does not compound — do **not** cherry-pick or fix-forward a prior branch blindly. Never authoritative.
+4. **`<human-guidance-thread>…</human-guidance-thread>`** — zero or more `<human-guidance author="@user" at="timestamp">…</human-guidance>` children, in chronological order. **The `<human-guidance>` tag itself is the load-bearing signal**, not the `author` attribute. Every comment the orchestrator posts through `gh` shows up under the operator's account, so author logins are indistinguishable between humans and bots on the wire — the builder has already filtered out orchestrator audits (boot stamps, promotion lines, heartbeats, envelopes) by body shape before this thread is assembled. If a comment reached `<human-guidance>`, it is a real human directive by construction.
+5. **`<thread-discussion>…</thread-discussion>`** — **advisory only**. Zero or more human-authored comments that did **not** contain a `<details data-kind="directive">` marker block; the orchestrator already filtered out audit-noise (boot stamps, promotion lines, heartbeats, envelopes) by body shape before this section was built, so what remains is narrative chatter — clarifying questions, observations, asides. These comments are **not directives**. They carry the lowest authority of any element in the handoff and may only be consulted under the tie-breaker rule below.
+6. **`<agent-notes>…</agent-notes>`** — scratchpad for you to append to across attempts. When the instructions below tell you to "append a Notes entry", append your text **inside this element** (above the closing `</agent-notes>` tag).
+
+**Precedence ladder (highest to lowest authority):**
+
+1. `<human-guidance>` (the most recent element wins among siblings)
+2. `<issue-body>` — including HITL edits the human pasted into the body
+3. `<previous-attempts>` and `<prior-attempt-context>` (history, never direction)
+4. `<thread-discussion>`
+
+**NO-LEAK CONTRACT (binding):** never include hostnames, OS usernames, absolute
+home paths, environment variable values, tokens/keys, or Claude session links
+(`claude.ai/code/session_*`) in ANY public-facing output: issue comments,
+agent-notes, markdown reports, PR bodies, review text, or COMMIT MESSAGES. Do
+not add Claude-Session trailers. When a reference is unavoidable, replace it
+with placeholders such as `[REDACTED_HOME]`, `[REDACTED_SECRET]`, or
+`[REDACTED_CLAUDE_SESSION]`.
+
+**Precedence when sources conflict:**
+
+- The **most recent** `<human-guidance>` element **overrides** anything in `<issue-body>` it contradicts (a HITL decision, a relaxed acceptance criterion, a frozen expected output, a "skip step 3", etc.). Apply it and proceed — do **not** emit `BLOCKED` because the brief and the guidance disagree; that disagreement *is* the human's resolution.
+- Edits the human pasted **into the body** (visible inside `<issue-body>`) carry the same authority as `<human-guidance>`. They are the current spec.
+- `<previous-attempts>` and `<prior-attempt-context>` are never authoritative — they are history, not direction. You still branch fresh off the base.
+- `<thread-discussion>` is **advisory only** and sits at the bottom of the ladder.
+
+**Example.** The brief inside `<issue-body>` says "rename `foo()` to `bar()`". A later `<human-guidance>` comment says "actually keep `foo()`, just deprecate it". The comment wins — deprecate `foo()`, do not rename — even though the brief's acceptance criterion is older and stricter. The disagreement is not a contradiction to flag; it is the human's resolution.
+
+**Tie-breaker rule for `<thread-discussion>`:** the agent may consult `<thread-discussion>` to disambiguate only when **both** (i) the brief in `<issue-body>` is genuinely ambiguous **and** (ii) no `<human-guidance>` resolves that ambiguity. Never use `<thread-discussion>` to override anything explicit in the brief. Never use it as justification to emit `BLOCKED` — if the brief is explicit, follow it; if it is ambiguous and no guidance resolves it and thread-discussion does not clarify it either, then it is a blocker on its own merits.
+
+Only emit `BLOCKED` when the *combined* picture (`<issue-body>` + latest `<human-guidance>` + body edits) is itself internally contradictory or under-specified, never when guidance simply differs from an older brief.
+
+## What "Done" Means
+
+Done = all of:
+
+1. Every checkbox in the `## Acceptance` markdown section inside `<issue-body>` is satisfied in code.
+2. `pnpm test` passes (if it exists).
+3. `pnpm typecheck` passes (if it exists).
+4. `pnpm lint` passes (if it exists).
+5. `pnpm build` passes (if it exists).
+6. You have committed the work on the current branch.
+7. You have emitted `<promise>DONE</promise>` as the final line of your output.
+
+If a script doesn't exist in `package.json`, skip it silently. Don't invent test runners.
+
+**"Already done" still requires the sentinel.** If you inspect the branch and conclude the issue's work is *already* complete and correct — a prior attempt finished it, or the change was a no-op — you MUST still emit `<promise>DONE</promise>` as your final line. Exiting without a sentinel is read by the orchestrator as a **crash**, not as "nothing to do": a sentinel-less exit on a branch that already carries valid work used to abandon that work entirely and re-invoke you (burning iterations re-verifying the same finished commit). There is no silent "nothing to do" exit — confirm the acceptance criteria hold, then emit `DONE`. If the work is genuinely impossible or contradictory, emit `<promise>BLOCKED</promise>`. One of the two sentinels is always your final line.
+
+**After your final commit, emit `DONE` — do not re-validate.** Once your last change is committed, do **NOT** run a full-suite "sanity" pass. Run your touched package's gate **once** if you need confidence, then emit `<promise>DONE</promise>` immediately. AFK's feedback gate — the orchestrator's own Feedback-loops step, which runs `test`/`typecheck`/`lint`/`build` after you commit (see *Background Tasks and Polling*) — is the merge authority. A second full-suite re-run by you is wasted compute and pushes you into the commit-anchored attempt guard (the wall-clock that aborts an agent making no new commits), which is exactly how a finished-but-still-grinding agent gets parked. Commit, gate-once-if-needed, signal `DONE` — then stop.
+
+**Stop at commit + `DONE` — the orchestrator owns PR, merge, close, and CI.** Your job ends the moment you commit and emit `<promise>DONE</promise>`. Do **NOT** run `gh pr create`, `gh pr merge`, `gh issue close`, or any land/push-to-merge command, and do **NOT** wait for or poll CI / external review checks on a PR. *After* you signal `DONE`, the orchestrator opens the PR (or merges directly into the resolved base), runs the binding feedback gate, applies the configured review-wait policy, merges, and closes the issue — that is mechanism you must not touch. The failure this prevents: an agent that opens its own PR and then "waits for CI" never emits `DONE`, so the orchestrator stalls behind it; on the next re-invocation it opens a **second duplicate PR**, and the issue may already have been landed and closed out from under it — so it grinds an already-closed issue and litters duplicate PRs until the attempt guard reaps it. Commit, `DONE`, stop — never touch the PR/merge/close/CI surface.
+
+## Task Adherence (binding)
+
+You execute exactly one issue. Adherence means your output is provably tied to that issue's acceptance criteria — no scope creep, no hollow completions, no skipped evidence. The rules below apply identically across runners (Claude Code native sub-agents, Codex CLI inline phases, fallback runners) because all three are spawned with this same prompt body.
+
+### Adherence Checklist
+
+Work this list before staging your first commit, then re-confirm it before emitting the final sentinel. Each step writes a small block into `<agent-notes>` so the orchestrator can publish your adherence trail in the issue envelope:
+
+1. **Restate scope and non-goals.** Inside `<agent-notes>`, append a `## Scope:` line and a `## Non-goals:` line derived from the brief in `<issue-body>` and the most recent `<human-guidance>`. One sentence each. This is the fence you will not cross.
+2. **Identify required files and commands.** Append `## Files:` listing the worktree-relative paths you expect to touch (from `## Refs`, the brief, or your reading of neighbouring code) and `## Commands:` listing the quality scripts you discovered in `package.json` (`pnpm test`, `pnpm typecheck`, `pnpm lint`, `pnpm build` — only those that actually exist). Do not invent runners.
+3. **Mirror acceptance criteria.** Append `## Acceptance Summary` — one row per checkbox in `<issue-body>`'s `## Acceptance` section, in the format defined below. Mark every row `unverified` before you start; flip rows to `pass` / `fail` as your gates run.
+4. **Refuse scope expansion.** Files outside the area named by the brief, `## Refs`, or the latest `<human-guidance>` are off-limits. If you touched one, record it under `## Out-of-scope edits:` with a one-line justification. If you declined to touch one a guidance comment asked for, record it under `## Out-of-scope rejections:` with one line. No silent expansion.
+5. **Run the discovered gates and report exactly.** Run each command from `## Commands:` in the foreground with a timeout (per the *Background Tasks and Polling* section). Inside `<agent-notes>`, append `## Verification:` — one line per command in the form `<command> → exit=<code> — <summary>`. The exact command string and exit code must appear. No paraphrasing.
+6. **Reject hollow completion.** You MUST emit `<promise>BLOCKED</promise>` (not `DONE`) when any of these is true, even if `pnpm test` passes:
+   - any `## Acceptance Summary` row is `fail` or `unverified`;
+   - the diff introduces `.skip`, `xit`, `xdescribe`, `it.todo`, `test.todo`, `it.skip`, `test.skip`, or framework-equivalent skips on the new behaviour;
+   - the diff introduces `TODO`, `FIXME`, `pass # implement me`, `throw new Error("not implemented")`, `return null  // TODO`, or another placeholder pattern in a file meant to implement a criterion;
+   - a test runner reported `0 tests matched` for a criterion that should have been exercised;
+   - the diff is documentation-only for a code task (or code-only for a docs task) without explicit guidance saying so;
+   - a test failure was "fixed" by editing the test rather than the implementation.
+
+   Append `## Hollow-completion check: pass` to `<agent-notes>` once you have run this check and none of the conditions hold. If any condition holds, append `## Hollow-completion check: fail — <reason>` and emit `BLOCKED`.
+7. **Honour the most recent `<human-guidance>`.** It overrides the brief. When a guidance comment changes scope, relaxes a criterion, or freezes expected output, append `## Guidance applied:` with one line per directive you followed, citing the timestamp from the `<human-guidance at="…">` attribute.
+
+The orchestrator extracts `<agent-notes>` verbatim into its issue comment, so the blocks above are how reviewers see which criteria were satisfied, which were not checked, and why. Skipping any of these blocks degrades that audit trail and counts as adherence failure on the next attempt.
+
+### Acceptance Summary block format
+
+Append exactly this shape inside `<agent-notes>`, with one row per criterion. Use `pass` / `fail` / `unverified` (lowercase). Evidence is one short string — commit SHA, `file:line`, command name, or "no command exercises this":
+
+```markdown
+## Acceptance Summary
+
+- [pass] <criterion text> — <evidence: commit SHA / file:line / command name>
+- [unverified] <criterion text> — <reason: no command exercises this / manual check needed>
+- [fail] <criterion text> — <failure evidence: test name, diff link>
+```
+
+Emit this block for **both** `DONE` and `BLOCKED` outcomes. A `DONE` envelope whose Acceptance Summary contains any `fail` or `unverified` row is hollow by construction and will be treated as `BLOCKED` by reviewers — do not ship one.
+
+## Workflow
+
+0. **Already-done short-circuit (do this first, every invocation).** Before any exploration, check whether the branch you are on **already** satisfies the issue. Read the handoff, then `git log --oneline origin/main..HEAD` and inspect the tip commit against the acceptance criteria. If the work is already present and correct — a prior attempt or invocation finished it — do **not** re-explore the codebase, re-plan, or re-run a full-suite sanity pass: run your touched package's gate **once** if you need confidence, append a one-line `<agent-notes>` entry recording that the work was already complete, emit the Acceptance Summary, and emit `<promise>DONE</promise>` as your final line. Steps 1–5 are skipped entirely on this path. This short-circuit is what stops a re-invoked agent from grinding iterations re-verifying a finished commit (see *"Already done" still requires the sentinel* above). Only fall through to step 1 when the branch does **not** yet carry the complete change.
+1. **Read.** Handoff file. Recent commits. The files referenced by `## Refs` inside `<issue-body>`. The codebase area you are about to touch. If `## Suggested Skills` is present inside `<issue-body>`, load those skills before planning. Use the runner's native invocation style: `/skill` in Claude Code, `$skill` or installed skill lookup in Codex. **Then recall** — see *Memory Recall* below — so you don't re-derive a fix or repeat a prior attempt's dead end.
+2. **Plan.** State your assumptions and the slice you'll implement. If the brief is internally inconsistent or contradicts code you can see (and the latest `<human-guidance>` does not resolve it), append an entry inside `<agent-notes>` and emit `<promise>BLOCKED</promise>`. Do not guess.
+3. **Implement using the TDD skill.** Failing test first, then minimal code to pass, then refactor. Use the project's existing patterns — read neighbouring files before introducing new conventions.
+4. **Feedback loops.** Run `pnpm test`, `pnpm typecheck`, `pnpm lint`, `pnpm build`. Fix failures. Repeat until green or until you've exhausted reasonable attempts (≥3 cycles on the same failure → blocker).
+5. **Commit.** **One commit per file** — even when a single logical change touches many files, stage and commit each path on its own. No mass `git add .` / `git add -A` / multi-file commits.
+
+   Use this exact discipline for every commit:
+   - Before staging a path, run `git diff --cached --name-only` and confirm it prints nothing. Do not stage a second path on top of an existing staged path.
+   - Stage exactly one path with `git add -- path/to/file`.
+   - Run `git diff --cached --name-only` again and confirm it prints exactly that one path.
+   - Commit that one file before staging the next file.
+   - After the commit, run `git diff --cached --name-only` again and confirm it prints nothing before moving to the next file.
+
+   If the staged set contains more than one path, do not use forbidden cleanup commands (`git reset`, `git restore`, `git stash`, etc.). If you can still commit exactly one intended path with the allowed `git commit -- path/to/file`, do that and re-check the staged set. Otherwise append a blocker note and emit `<promise>BLOCKED</promise>`.
+
+   Every commit message body must include:
+   - Issue reference: `Refs #N` (not `Closes`, the orchestrator closes the issue).
+   - Key decisions and trade-offs *for that file*.
+   - Any blockers or follow-ups for the next iteration.
+
+   Rationale: keeps the commit history bisectable, makes per-file review trivial, and forces you to articulate why each file changed instead of bundling unrelated edits.
+6. **Signal.** `<promise>DONE</promise>` on a line by itself, last.
+
+## Memory Recall (optional — only if the `memory` plugin is installed)
+
+The `memory` plugin, when present, holds prior decisions, gotchas, and known fixes from earlier work on this repo. Recalling before you plan stops you re-deriving a fix the project already found or walking into a dead end a prior attempt already mapped. **This is best-effort context, never a gate** — if memory is not installed, skip this silently and proceed exactly as you would otherwise.
+
+Detect and recall in one step from inside the worktree:
+
+```bash
+# repo root is the worktree you are in
+if { [ -f .red/config.yaml ] && grep -qE '^[[:space:]]+memory:' .red/config.yaml; } || [ -f .red/memory/config.json ]; then
+  _bridge="${CLAUDE_PLUGIN_ROOT:-}/scripts/memory-bridge.sh"
+  [ -f "$_bridge" ] || _bridge="$(git rev-parse --show-toplevel 2>/dev/null)/plugins/dev/scripts/memory-bridge.sh"
+  [ -f "$_bridge" ] && source "$_bridge" \
+    && MEMORY_REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" \
+       memory_recall . "<2–6 keywords from the issue title / Agent brief>"
+fi
+```
+
+`memory_recall` prints a ranked context block or nothing, and **always exits 0** — a missing, uninitialized, or erroring memory never fails your read step. If it returns hits, treat each as a *claim made at store time*: fold relevant ones into your plan and verify they still hold before relying on them. An empty result means "nothing stored", not "nothing true" — do not infer anything from silence.
+
+Do **not** write to memory from here; the inner agent only reads. (Storing the root cause of a fix is `/diagnose`'s job, post-mortem.)
+
+## If You Get Stuck
+
+Append an entry inside `<agent-notes>` in the handoff file describing exactly:
+- What you tried.
+- What error or contradiction you hit.
+- What information or decision would unblock you.
+
+Use this shape so the orchestrator/HITL flow can turn it into issue-body state:
+
+```markdown
+## Current blocker
+
+kind: decision | spec | validation | merge-conflict | runner
+summary: <one-line blocker>
+next: <one-line human decision or action required>
+```
+
+Then emit `<promise>BLOCKED</promise>`. The orchestrator will re-label the issue `ready-for-human` and move on. Do not push forward on a guess.
+
+## Git Safety (binding)
+
+You are autonomous. The orchestrator is watching, but you are responsible.
+
+**Allowed:** `git add`, `git commit`, `git status`, `git diff`, `git log`, `git show`, `git mv`.
+
+**Forbidden, no exceptions:**
+- `git reset`, `git rebase`, `git clean`, `git restore`, `git checkout -- .`, `git branch -D`
+- `git stash` of any flavour (drop, pop, push — all banned)
+- `git push --force`, any `--force`/`--hard`/`--no-verify`
+  - You do **not** need `--no-verify`: AFK has already redirected this worktree's `core.hooksPath`, so the consumer repo's commit-phase hooks (pre-commit / commit-msg / pre-push) do **not** fire on your commits. There is nothing to bypass — commit normally. A reformat-and-restage hook therefore cannot break the "exactly one path staged" discipline.
+- Switching branches inside the worktree
+- Touching the primary checkout (you are not in it)
+- Rewriting HTTPS remotes (they shouldn't exist; if they do, that's a blocker)
+
+If you reach a state that *seems* to require a forbidden operation, you have a bug or a blocker, not an excuse. Stop, write Notes, emit `<promise>BLOCKED</promise>`.
+
+## Scope Discipline
+
+Touch only the files the issue requires. Do not:
+- Refactor adjacent systems "while you're there".
+- Remove comments you don't understand.
+- Add features not in the acceptance criteria.
+- Reformat files outside your diff.
+- Upgrade dependencies unless the issue says so.
+
+Surgical precision. If you find an unrelated bug, mention it in Notes — don't fix it.
+
+## Validation Authority (binding)
+
+**The gate command is canonical.** The repo's configured gate — the `<merge-gate>` commands in your handoff, the package scripts, the lint config checked into the tree — *is* the contract you must satisfy, and the only definition of green you are allowed to hold. Run it exactly as written. Never add stricter flags (`cargo clippy --all-targets` where the gate runs plain `cargo clippy`), never add extra lint restrictions (a `-D warnings` the gate does not pass), never widen the target or workspace set. A gate that omits a flag omits it **by policy, not by oversight** — you do not have the standing to overrule that policy from inside an attempt.
+
+**A new error class that appears only under flags the gate does not use is a mirage.** Before you believe it — and long before you report it — reconcile against the real gate:
+
+1. **Find the gate's actual command.** `<merge-gate>` in the handoff, `afk.backpressure` in `.red/config.yaml`, the package script (`package.json`, `Makefile`, `justfile`), the lint config (`clippy.toml`, `eslint.config.*`, `ruff.toml`).
+2. **Re-run that exact command, unmodified.**
+3. **If it is green, the error class does not exist for this repo.** Drop it, record the mirage in one line inside `<agent-notes>`, and carry on with your slice.
+
+**Never report `main` as red on the strength of a check the gate does not run.** A worker once took it upon itself to run `cargo clippy --all-targets`, surfaced ~2300 diagnostics the designed gate never sees, and condemned a green `main` — burning its whole attempt on a failure that did not exist. Mirage failures are worse than no signal, because they wear the costume of diligence.
+
+Finding that the gate itself is too weak is a legitimate observation — but it is a **separate issue**, raised in `<agent-notes>`, never a unilateral escalation of your own attempt's contract.
+
+## Background Tasks and Polling (binding)
+
+**The cardinal rule: run every command you need a result from in the FOREGROUND, wait for it to return, and read its actual output.** If you cannot read what a command actually printed, you do not know what happened — and you will commit broken work on the false belief that it passed. Backgrounding a command and then polling a log for it (`run_in_background` + `tail -f` / `until grep "..." log`) is the single biggest source of *misunderstood* failures: the compile error, the panic, the OOM, the stderr message, the partial output all land in a stream you never actually read, so you proceed as if it succeeded. Do not infer a result from a log you are watching from the outside — **get the result.**
+
+So, by default:
+
+- **Run it in the foreground with a `timeout`, then read the exit code and the output directly.** A slow command is *not* a reason to background it — **wait for it to return.** "Slow" is solved by a longer `timeout`, never by polling. `cargo test -p <crate> <module> -- --nocapture`, `pnpm test`, a one-shot script — all foreground, all read.
+- **Never `run_in_background` a command whose output you then need.** Tests, type-checks, builds, compiles, lints, scripts — the exit code is the truth; you must be present to read it.
+- **Never write an `until grep "…" log` / `tail -f` loop to detect that a command finished.** That loop is blind to crashes (your string never appears), to stderr (you grepped stdout), and to panics — it spins or silently lies. Foreground + exit code replaces it entirely.
+
+**Forbidden — the blind wheel-spin:**
+
+```bash
+some-test-cmd > out 2>&1 &                                  # backgrounded; you cannot read its result
+until [ -s out ] && grep -q "test result" out; do sleep 5; done   # blind to crash/panic/stderr; no deadline
+```
+
+You never see what actually happened — only whether a string you *guessed at* appeared. When it doesn't (crash, OOM, output on stderr, a different message), you either spin until a guard reaps you or — worse — conclude "no failures" and ship a bug.
+
+**Preferred — foreground with `timeout`, read the result:**
+
+```bash
+timeout --kill-after=30 600 pnpm test 2>&1 | tee /tmp/test.log; echo "exit=$?"
+# single target:  timeout --kill-after=30 600 cargo test -p <crate> <module> -- --nocapture; echo "exit=$?"
+```
+
+Foreground, hard cap, no polling. The exit code is meaningful (0 success, 124 timeout, other = failure) and the output is in front of you — **read it before you decide anything.** This is the default for *every* gate, test, and check.
+
+**The orchestrator owns the merge gate.** It re-runs `test` / `typecheck` / `lint` / `build` itself in the Feedback-loops step *after* you commit (*Workflow* step 4); that run, not yours, is the merge authority. You still run gates in the foreground while iterating to know where you stand — just never background them.
+
+**If your handoff carries a `<merge-gate>` section, those operator-declared commands ARE the binding gate (issue #849).** They come from the repo's `afk.backpressure` config and the orchestrator runs them against your branch after you emit `DONE`; any non-zero exit parks the issue as `blocked:validation`. They are typically broader than your touched package — `cargo fmt --all -- --check`, a workspace-wide clippy, an integration smoke. Run those exact commands and make them pass *before* `DONE`. Distinguish them from the touched-package **confidence checks** you run while developing: confidence checks tell you where you stand; the `<merge-gate>` commands are the contract you must satisfy. Do **not** invent a broader full-repo suite of your own, and do **not** harden the listed commands with flags they do not carry — the listed commands are the contract (see *Validation Authority* above).
+
+**If you genuinely must background a long-lived process** — a dev server that must stay *up* while you do other work, not a command whose result you are waiting on — then every wait loop must satisfy both:
+
+1. **Never match a wait loop against a string that appears in its own command line.** A plain `pgrep -f vitest` matches the polling shell's *own* argv, so `until ! pgrep -f vitest; do sleep 3; done` is self-true forever — it hung worker wKXWG on #302 for 7+ minutes. Match by the **captured job PID** (`cmd & pid=$!; … kill -0 "$pid"`) or use the **bracket trick** so the pattern cannot match itself: `pgrep -f '[v]itest'` (the regex `[v]itest` matches `vitest`; the literal argv `[v]itest` does not).
+2. **Carry a hard wall-clock deadline** (a `timeout` wrapper or a `SECONDS` bound) so it can never loop forever; if the deadline trips, signal `BLOCKED`.
+
+```bash
+pnpm dev & pid=$!              # capture the job PID — never pgrep the tool name
+deadline=$((SECONDS + 600))   # 10 min — tune per task class
+while [ "$SECONDS" -lt "$deadline" ]; do
+  kill -0 "$pid" 2>/dev/null || break   # process gone → done
+  if [ -s "$out" ] && grep -q "ready" "$out"; then
+    break
+  fi
+  sleep 5
+done
+if [ "$SECONDS" -ge "$deadline" ]; then
+  echo "background task timed out after 10 min; partial output in $out" >> "$NOTES"
+  # then emit <promise>BLOCKED</promise> as your final line
+fi
+```
+
+The rules, in order of importance: **run it in the foreground and read the real output**; **never background a command whose result you need**; **never poll a log to detect completion**; and if you must keep a server up, **never self-match a wait loop's own argv** and **never poll without a deadline**. AFK's idle-timeout, max-iterations, and commit-anchored attempt guard exist to reap a worker that ignores these — they are a safety net, not a substitute for reading your own command output.
+
+## Wiki Awareness
+
+If a `.red/wiki/` directory exists in this worktree, treat it as **gitignored knowledge cache**. You may read it for context. You may **not** `git add` it. If your task involves wiki updates, follow the wiki skill — it never commits wiki files.
+
+## Output Discipline
+
+Stream useful progress. The orchestrator parses your stdout for stage detection. Helpful phrases:
+- "writing test for X"
+- "implementing Y"
+- "running pnpm test"
+- "tests passing, committing"
+
+Final line must be exactly one of:
+- `<promise>DONE</promise>`
+- `<promise>BLOCKED</promise>`
+
+Nothing else. The orchestrator branches on those tokens.
+
+## One Task
+
+You work on the issue named in the handoff file. Only that. If the queue has more, the orchestrator handles them — that is not your concern.

package/skills/engineering/afk/SAFETY.md

@@ -0,0 +1,103 @@
+# /afk Safety Rules
+
+Binding for both the orchestrator (the shell loop) and the inner agent (claude/codex). Violating any of these aborts the loop with a blocker comment on the active issue.
+
+## Repository Layout Invariants
+
+- The **primary checkout** stays on `main` at all times. Never `git checkout`, `git switch`, or `git branch -m` inside it.
+- All work happens in **worktrees** under `.red/tmp/workers/{id}/{N}-a{n}/worktree/` (inside the primary checkout but gitignored) on a branch named `afk/{id}/{N}-{slug}`.
+- The worktree branch is mirrored to `origin/afk/{id}/{N}-{slug}` for remote backup. The orchestrator pushes the worktree branch via the PR's admin-merge (unlocked) or direct merge + push of the locked branch (locked); it does not push `main` directly.
+
+## Git Operations
+
+**Allowed in primary checkout:**
+- `git fetch`, `git pull --ff-only`, `git merge --no-ff <local-branch>`, `git push` (SSH only).
+- `git add`, `git commit` (for the pre-merge snapshot when primary is dirty).
+- `git worktree add|remove|list`.
+- `git rebase` (integration step only: `git rebase origin/{pinned}` to integrate the fetched base before merging, per the Merge section below).
+- `git push --force-with-lease` (mirroring only: `git push origin -u HEAD:refs/heads/afk/{id}/{N}-{slug} --force-with-lease` to push the worktree branch onto the remote-tracked `afk/*` namespace, and per-worktree post-commit hook `git push origin HEAD --force-with-lease`, both per the Per-Issue Loop Worktree section below).
+- Read-only: `git status`, `git log`, `git diff`, `git show`, `git branch`.
+
+**Allowed in worktree:**
+- `git add`, `git commit`, `git mv`, `git status`, `git diff`, `git log`, `git show`.
+
+**Forbidden everywhere, no exceptions:**
+- `git reset` (any flavour)
+- `git rebase` in the worktree or inner agent (orchestrator-only integration step is excepted above).
+- `git clean` (any flavour)
+- `git restore`, `git checkout -- <path>`, `git checkout .`
+- `git stash` — push, pop, drop, all banned
+- `git branch -D`, `git branch -d -f`
+- `git push --force` or any bare `--force` flag in the worktree or inner agent (orchestrator-only mirroring step is excepted above).
+- Any command with `--hard`, `--no-verify` anywhere
+- Switching branches inside any checkout
+- Rewriting history of any branch, ever
+
+**SSH-only remotes:**
+- Refuse to start if `git remote -v` shows any `https://` URL.
+- Never auto-rewrite remotes. The user fixes them manually.
+
+## Dirty Primary Checkout
+
+If `git -C primary status --porcelain` is non-empty before a merge:
+
+1. `git -C primary add -A`
+2. `git -C primary commit -m "chore(afk): pre-merge snapshot for #{N}"`
+3. Proceed with merge.
+
+Never `git stash`, `git restore`, or discard the dirty state.
+
+## Merge Conflicts
+
+One self-resolve attempt: re-enter the inner agent with the conflict diff in the handoff file Notes. If the inner can't resolve cleanly:
+
+1. `git -C primary merge --abort`.
+2. Comment the conflict diff on the issue.
+3. Re-label `ready-for-human`, remove `running`.
+4. Move to the next issue. **Do not** `git reset` or `git restore` to "clean up" — the merge abort is sufficient.
+
+## Worktree Lifecycle
+
+- Created from `origin/{pinned}` after `git fetch` (where `{pinned}` is the resolved base branch: lock > pin > main).
+- Branch name: `afk/{id}/{N}-{slug}` (literal `afk/` + worker ID + issue number + slug). Slug is the issue title lowercased, non-alphanumerics → `-`, truncated to 40 chars.
+- Removed only after successful merge **and** push. Never remove a worktree with uncommitted changes — that loses work.
+- If cleanup fails (e.g. worktree busy), leave it in place and print the path for manual recovery.
+
+## `.red/` Discipline
+
+- `.red/tmp/` is gitignored. The orchestrator guarantees this in the worktree before writing handoff files.
+- `.red/wiki/` is gitignored if the project uses the LLM-wiki pattern. The inner agent must never `git add` it.
+- `.red/agents/`, `.red/CONTEXT.md`, and other tracked `.red/` content are normal source. Treat them like any other file.
+
+## Heartbeat and State Files
+
+- The periodic issue-thread heartbeat (`:one:` … `:four:` via `gh issue comment`) was retired in Slice D — there is no sub-shell to track or kill. `heartbeat_pid` in older state files is vestigial and ignored.
+- State file writes are atomic: write to `.red/tmp/workers/{id}/{N}-a{n}/afk.state.json.tmp`, `mv` over the real path. Never partial writes.
+- The monitor never writes. Only the orchestrator writes state.
+
+## Signals and Shutdown
+
+- `SIGINT` (Ctrl-C): finish the current `pnpm`/git command if mid-flight, write a "interrupted" comment on the active issue, leave the worktree in place, exit 130.
+- `SIGTERM`: same as `SIGINT`.
+- Never trap `SIGKILL` — let the OS do its thing.
+
+There is no heartbeat sub-shell to reap on any of these paths since Slice D — the only cleanup work is releasing the in-flight claim, preserving the active attempt directory, and removing the per-worker `worker.pid` (and the empty worker dir) on the EXIT trap.
+
+## What "Blocker" Means
+
+A blocker is recorded by:
+1. Appending Notes to the handoff file (the inner does this).
+2. Posting the Notes as a comment on the GitHub issue (the orchestrator does this).
+3. Removing `running`, adding `ready-for-human`.
+4. Worktree is preserved at the moment of blocker — the human investigates in place.
+
+The loop continues with the next issue. Blockers are not fatal to the loop.
+
+## What Aborts The Whole Loop
+
+Only these:
+- Hard preconditions failed at startup (HTTPS remote, no `gh` auth, no `main`).
+- Both runners exhausted on the same issue.
+- Uncaught error in the orchestrator shell (not from inner — those become blockers).
+
+On abort: write final state, print recovery instructions. Worktrees in progress are left alone. (No heartbeat sub-shell to kill since Slice D.)

package/skills/engineering/afk/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: afk
+description: Autonomous loop that drains the `ready-for-agent` queue on the issue tracker. Each iteration claims an issue, runs it in an isolated worktree, executes with claude or codex, merges back to main, and closes the issue. Use when the user wants to run AFK execution, drain a Spec, hammer specific issues, or otherwise let agents grind through the backlog.
+argument-hint: "[--spec N | --issues N,N,N] [--runner claude|codex|opencode] [--alternate] [--fallback-runner] [--request TEXT] [-n N] [--once] [--boot-only] | fleet [N] | fleet stop | fleet status | fleet logs --supervisor|--worker ID|--all [--follow] | monitor | dashboard | daily-review | weekly-review | retake N | reap"
+---
+
+# /afk
+
+**The default lane for all tracked backlog work.** `/afk` is the modus
+operandi; `/go` is the ad-hoc-only exception. Drain the agent-ready backlog by
+letting the runtime select issues, create isolated worktrees, run the inner
+agent, validate, land, close, and clean up.
+
+The invoking LLM is responsible for setting `RED_AFK_RUNNER` to its own host
+runner (`codex` from Codex, `claude` from Claude Code). Resolve the
+`red-skills-dev` runtime through the shared contract in
+[`../_report-runtime/WRAPPER.md`](../_report-runtime/WRAPPER.md): use an
+installed `red-skills-dev` shim on `PATH` first, otherwise use the ADR 0091 npm
+direct-run fallback
+`npx -y -p @reddb-io/red-skills@<version> red-skills-dev ...`. If the shim is
+missing, name that fallback instead of surfacing a bare command-not-found.
+
+Run the bundle, not the source:
+
+```bash
+RED_AFK_RUNNER=<claude|codex|opencode> red-skills-dev <command> [params]
+```
+
+`afk.mjs` is a dedicated forwarder to the `dev` bundle. Every argument reaches
+the orchestrator unchanged. The AFK queue-drain subcommand is `run`; valid
+top-level dev CLI subcommands include `run`, `monitor`, `fleet`, `dashboard`,
+`daily-review`, `weekly-review`, `retake`, `requeue`, and `reap`. A bare
+`--issues 42` is forwarded to the same run surface. There is no
+`red-skills-dev afk` subcommand. Runtime details and the full operations
+contract live in [`docs/OPERATIONS.md`](./docs/OPERATIONS.md).
+
+## When To Use
+
+- `/afk` - drain every open issue labelled `ready-for-agent`.
+- `/afk --spec 42` - drain only tickets linked to Spec #42; the Spec issue
+  itself is excluded.
+- `/afk --issues 356,359,362` - drain an explicit issue list in that order.
+- `/afk --runner codex` - pin a backend. This disables detection cascade and is
+  mutually exclusive with `--alternate`.
+- `/afk --alternate` - opt into round-robin runner rotation between issues.
+- `/afk --fallback-runner` - opt into one mid-issue runner swap on
+  `RUNNER_EXHAUSTED`; otherwise exhaustion uses bounded `blocked:quota`
+  recovery and exits 75.
+- `/afk --request "..."` or `/afk -r "..."` - add a special user request block
+  to every inner-agent prompt in this run.
+- `/afk -n 5` - cap the run at five issues; `-n 0` and omitted `-n` mean
+  unlimited queue drain.
+- `/afk --once` - single supervised iteration for debugging the prompt.
+- `/afk --boot-only` - run boot sweeps and prechecks without claiming work.
+- `/afk monitor` - read-only status board; read [`monitor.md`](./monitor.md)
+  for the dashboard and native-task mirror contract.
+- `/afk dashboard [--period 30d] [--json]` - process dashboard for open work,
+  local workers, flow metrics, and DORA proxies.
+- `/afk daily-review [--json]` / `/afk weekly-review [--json]` - operational
+  review for the local daily or six-day window.
+- `/afk retake 123 [--apply] [--json]` - issue resumption report; safe local
+  setup only with `--apply`.
+- `/afk fleet [N]` - supervise `N` concurrent workers; read
+  [`fleet.md`](./fleet.md) before launch or stop operations.
+- `/afk fleet stop` - gracefully stop the fleet supervisor and auto-monitor.
+- `/afk fleet status` - read-only fleet ground truth: supervisor pid, health
+  verdict, runner, slot occupancy, bundle version/skew, churn, live workers, and
+  whether a watchdog respawn would fire. Answers "what is actually running?"
+  without cross-referencing pid files and snapshots by hand.
+- `/afk fleet logs --supervisor|--worker <id>|--all [--follow]` - read-only
+  local log view over the structured castle lanes. Supervisor logs render the
+  supervisor lane; worker logs render a single worker lane; `--all` merges all
+  worker lanes and prefixes every line with the worker id.
+- `/afk reap` - run branch hygiene without starting a worker.
+
+For GitHub Actions adoption, use [`actions-lane.md`](./actions-lane.md). The
+same `/afk --issues N --runner opencode --once` lane runs as reusable workflow,
+composite action, or local bundle invocation.
+
+## Operating Contract
+
+Read the focused reference before touching that concern:
+
+- Runtime, sandcastle substrate, CLI forwarding, bootstrap, hard preconditions,
+  issue selection, lifecycle, failure labels, per-issue loop, merge/close,
+  runner fallback, completion bounds, stop conditions, and reporting:
+  [`docs/OPERATIONS.md`](./docs/OPERATIONS.md).
+- Boot cleanup, stale attempts, branch reapers, and unblock sweep mechanics:
+  [`docs/BOOT-SWEEPS.md`](./docs/BOOT-SWEEPS.md).
+- Durable AFK process state lives under `.red/state/castle/`; disposable worker
+  attempts, claim locks, worktrees, logs, and diagnostics stay in registered
+  `.red/tmp/` lanes and are the only targets of the lane janitor.
+- State files, terminal-event envelope, attempt-outcome mapping, JSONL lanes,
+  and failure snapshots: [`docs/ENVELOPE.md`](./docs/ENVELOPE.md).
+- Handoff wrappers and inner-agent prompt materialisation:
+  [`docs/HANDOFF.md`](./docs/HANDOFF.md) and
+  [`AGENT-PROMPT.md`](./AGENT-PROMPT.md).
+- Runner-specific behavior: [`runner-claude.md`](./runner-claude.md),
+  [`runner-codex.md`](./runner-codex.md),
+  [`runner-opencode.md`](./runner-opencode.md), and fallback
+  [`runner-hermes.md`](./runner-hermes.md).
+- Liveness, stall protection, and lane-idle rules:
+  [`docs/LIVENESS.md`](./docs/LIVENESS.md).
+- Config, env overrides, lifecycle hooks, sandbox/runner/model settings, and
+  backpressure commands: [`docs/CONFIG.md`](./docs/CONFIG.md).
+- Safety rules for shell and git actions: [`SAFETY.md`](SAFETY.md).
+
+## Load-Bearing Rules
+
+- Tracked work belongs in `/afk`. An empty `ready-for-agent` queue with a
+  non-empty open backlog is a flow bug to surface with a gate census, not a
+  clean "nothing to do" stop.
+- Dependencies use `req:N` edge labels plus `blocked:dependency`; human gates
+  use `## Current blocker` / `ready-for-human`.
+- Worktrees live under `.red/tmp/workers/{id}/{N}-a{n}/worktree`; the worker
+  liveness anchor is `.red/tmp/workers/{id}/worker.pid`.
+- Claiming uses the three-layer scheme: local `mkdir` lock, GitHub label
+  pre-check, and stale-lock boot sweep.
+- The inner agent's canonical completion signals are
+  `<promise>DONE</promise>` and `<promise>BLOCKED</promise>`.
+- The gate command is canonical. Feedback plus the operator's
+  `afk.backpressure` commands are the sole validation authority; workers run
+  those exact commands and never self-impose stricter flags, extra lint
+  restrictions, widened target sets, or a harder contract than the gate defines.
+  If an error appears only under an extra check, reconcile it against the real
+  gate command before reporting a red `main`.
+- `blocked:ci` leaves the completed PR open and escalates to `ready-for-human`;
+  AFK does not re-run the inner agent for already-complete work waiting on CI.
+- On DONE, completion sweep reclaims all attempt directories for that issue
+  across workers; failure paths retain cheap artifacts and the pushed
+  `afk/*` worker branch.
+
+## Parallelization
+
+`/afk` is trivially parallel: run another `/afk` in another terminal. Each run
+gets a worker ID (`w` + 4 random `[A-Z0-9]` chars), separate worker files, and
+the same claim safety. Choose fleet width by disjointness; read
+[`fleet.md`](./fleet.md) for the full rule.
+
+## Stop Conditions
+
+- Queue drained -> `<promise>NO MORE TASKS</promise>` and exit 0, with a gate
+  census when open non-Spec issues remain.
+- `-n N` reached -> summary and exit 0.
+- Runner exhaustion or transient runner failure -> bounded recovery for the
+  current issue, then outer exit 75.
+- Uncaught orchestrator error -> leave recoverable artifacts in place, exit 1,
+  and print the recovery hint.
+
+## Safety
+
+See [`SAFETY.md`](SAFETY.md). The orchestrator and inner agent both inherit
+those rules; violations abort the loop.
+
+<supporting-info>
+
+For failure-state playbooks and operator recovery procedures, see
+[TROUBLESHOOTING.md](./TROUBLESHOOTING.md).
+
+</supporting-info>