@reddb-io/red-skills-dev 2.75.2

package/skills/engineering/afk/defaults/envelope-post-attempt.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# envelope-post-attempt.sh — built-in post_attempt default (PRD #207, issue
+# #212; renamed from post_worker in #226).
+#
+# Reconciles the iteration's intermediate envelope state on the AFK state
+# file as soon as the runner returns — before any user `post_attempt` hook
+# runs, so a user notifier/pager integration that reads state already sees
+# the worker's terminal result classified.
+#
+# Contract:
+#   stdin   — JSON object: post_attempt context with `.result.status` of
+#             "success" or "fail".
+#   stdout  — empty (context unchanged). Pure side-effect on the state file.
+#   exit    — 0. Never aborts the chain.
+#
+# Env contract (set by afk.sh before dispatch):
+#   RED_AFK_STATE_FILE      — path to the iteration's afk.state.json;
+#                             when unset/missing, the default is a no-op.
+#   RED_AFK_RESULT_STATUS   — redundant fallback for tests / runners that
+#                             can't shape a ctx; if ctx.result.status is
+#                             absent the env var is used instead.
+#
+# Disable with `afk.hooks.defaults.envelope: false` in `.red/config.yaml`.
+
+set -uo pipefail
+
+ctx="$(timeout "${RED_SKILLS_HOOK_STDIN_TIMEOUT_S:-5s}" cat 2>/dev/null || true)"
+
+state_file="${RED_AFK_STATE_FILE:-}"
+[[ -z "$state_file" || ! -f "$state_file" ]] && exit 0
+
+status=""
+if [[ -n "$ctx" ]]; then
+  status="$(printf '%s' "$ctx" | jq -r '.result.status // empty' 2>/dev/null || true)"
+fi
+[[ -z "$status" ]] && status="${RED_AFK_RESULT_STATUS:-}"
+[[ -z "$status" ]] && exit 0
+
+tmp="${state_file}.tmp.$$"
+if jq --arg s "$status" '.current = ((.current // {}) + {result_status: $s})' \
+     "$state_file" > "$tmp" 2>/dev/null; then
+  mv "$tmp" "$state_file"
+else
+  rm -f "$tmp"
+fi
+
+exit 0

package/skills/engineering/afk/defaults/gradle-pre-worktree.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# gradle-pre-worktree.sh — built-in pre_worktree default for Gradle projects.
+#
+# Contract (PRD #207, issue #211):
+#   stdin   — JSON object: pre_worktree context (issue, target, branch, env).
+#   stdout  — empty (context unchanged) when no build.gradle* is present at
+#             $PROJECT_ROOT, OR when RED_AFK_GRADLE_USER_HOME_BASE is unset
+#             (opt-in by env var — we do not claim a path on the user's
+#             filesystem without their consent). Otherwise a JSON object
+#             that merges {env: {GRADLE_USER_HOME: <slot dir>}} into ctx.
+#   exit    — 0 on either branch. Never aborts the chain.
+#
+# Side effect: mkdir -p the slot Gradle home so daemons / caches are isolated
+# between worker slots.
+#
+# Disable with `afk.hooks.defaults.gradle: false` in `.red/config.yaml`.
+
+set -uo pipefail
+
+project_root="${PROJECT_ROOT:-$(pwd)}"
+ctx="$(timeout "${RED_SKILLS_HOOK_STDIN_TIMEOUT_S:-5s}" cat 2>/dev/null || true)"
+[[ -z "$ctx" ]] && ctx='{}'
+
+shopt -s nullglob
+matches=("$project_root"/build.gradle*)
+shopt -u nullglob
+if [[ "${#matches[@]}" -eq 0 ]]; then
+  exit 0
+fi
+
+if [[ -z "${RED_AFK_GRADLE_USER_HOME_BASE:-}" ]]; then
+  exit 0
+fi
+
+slot="${RED_AFK_SLOT:-0}"
+home_dir="${RED_AFK_GRADLE_USER_HOME_BASE}/slot-${slot}"
+
+mkdir -p "$home_dir" 2>/dev/null || true
+
+printf '%s' "$ctx" | jq -c \
+  --arg h "$home_dir" \
+  '. + {env: ((.env // {}) + {GRADLE_USER_HOME: $h})}'

package/skills/engineering/afk/defaults/heartbeat-post-attempt.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# heartbeat-post-attempt.sh — built-in post_attempt default (PRD #207, issue
+# #212; renamed from post_worker in #226).
+#
+# Contract:
+#   stdin   — JSON object: post_attempt context (issue, workspace, result).
+#   stdout  — empty (context unchanged). The default is a pure side-effect:
+#             it stops the orchestrator's per-minute heartbeat side-channel
+#             and writes the "iteration stopped" boundary marker into the
+#             iteration log, migrating the inline `heartbeat_stop` that
+#             used to fire from afk.sh right after `run_inner` returned.
+#   exit    — 0. Never aborts the post_attempt chain (the dispatcher already
+#             routes post_attempt rc through `continue` policy, but the
+#             default also belt-and-braces this with a 0 exit).
+#
+# Env contract (set by afk.sh before dispatch):
+#   RED_AFK_HEARTBEAT_PID — pid of the orchestrator heartbeat sub-shell;
+#                           empty when no heartbeat was started for this
+#                           iteration (smoke paths). Killing a stale pid
+#                           is a no-op via `kill -0` guard.
+#   RED_AFK_ITER_LOG      — path to the iteration log; the boundary line
+#                           is appended only when the file exists.
+#
+# Disable with `afk.hooks.defaults.heartbeat: false` in `.red/config.yaml`.
+
+set -uo pipefail
+
+# Drain stdin (context flows through unchanged — emit nothing).
+timeout "${RED_SKILLS_HOOK_STDIN_TIMEOUT_S:-5s}" cat >/dev/null 2>&1 || true
+
+pid="${RED_AFK_HEARTBEAT_PID:-}"
+if [[ -n "$pid" ]] && kill -0 "$pid" 2>/dev/null; then
+  kill "$pid" 2>/dev/null || true
+  # Best-effort reap; the sub-shell may already be exiting.
+  wait "$pid" 2>/dev/null || true
+fi
+
+iterlog="${RED_AFK_ITER_LOG:-}"
+if [[ -n "$iterlog" && -f "$iterlog" ]]; then
+  printf '[heartbeat] iteration stopped at %s\n' "$(date -Is)" >> "$iterlog"
+fi
+
+exit 0

package/skills/engineering/afk/defaults/validation-post-merge.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# validation-post-merge.sh — built-in post_merge default (PRD #207, issue #213).
+#
+# Runs CI/smoke validation against the merged primary checkout so user
+# post_merge hooks see the validation status already reconciled into the
+# context. Migrated from the inline `feedback`-style call: the pre-merge
+# `feedback()` in afk.sh stays as the mechanism-owned safety gate (ADR 0008
+# — anything that must abort the merge loudly is mechanism, not a hook), and
+# this default exposes a post-merge re-run hook authors can disable, observe,
+# or replace.
+#
+# Contract:
+#   stdin   — JSON object: post_merge context (issue, workspace, merge_commit).
+#   stdout  — JSON object: the same context with
+#             `.result = {validation_status: "passed"|"failed"|"skipped",
+#                          validation_summary: <one-line string>}` merged into
+#             it. Non-JSON stdin → pass-through with no validation attempt.
+#   exit    — 0. Post_merge policy is `continue`; even a failing validation
+#             only logs (it cannot roll back the merge — that ship has sailed
+#             at this lifecycle point).
+#
+# Env contract (set by afk.sh before dispatch):
+#   RED_AFK_WORKSPACE   — primary checkout (post-merge tip). When unset or
+#                          not a directory, the default is a no-op.
+#   RED_AFK_MERGE_COMMIT — full sha of the merge commit on `target`. Not
+#                          consumed by this default but documented so user
+#                          hooks reading env directly see a consistent view.
+#
+# Disable with `afk.hooks.defaults.validation: false` in `.red/config.yaml`.
+
+set -uo pipefail
+
+ctx="$(timeout "${RED_SKILLS_HOOK_STDIN_TIMEOUT_S:-5s}" cat 2>/dev/null || true)"
+ws="${RED_AFK_WORKSPACE:-}"
+
+emit_ctx() {
+  local status="$1" summary="$2"
+  if [[ -z "$ctx" ]]; then
+    return 0
+  fi
+  printf '%s' "$ctx" \
+    | jq --arg s "$status" --arg sum "$summary" \
+        '.result = ((.result // {}) + {validation_status: $s, validation_summary: $sum})' \
+        2>/dev/null \
+    || printf '%s' "$ctx"
+}
+
+if [[ -z "$ws" || ! -d "$ws" ]]; then
+  emit_ctx "skipped" "no workspace"
+  exit 0
+fi
+
+if ! [[ -f "$ws/package.json" ]]; then
+  emit_ctx "skipped" "no package.json"
+  exit 0
+fi
+
+# Run pnpm test/typecheck/lint/build at the workspace root if the script
+# exists. This mirrors the mechanism-owned `feedback()` step shape but
+# operates on the merged tip rather than the worker's worktree.
+overall="passed"
+parts=""
+for script in test typecheck lint build; do
+  if jq -e --arg s "$script" '.scripts[$s] // empty' "$ws/package.json" >/dev/null 2>&1; then
+    if ( cd "$ws" && pnpm -s "$script" >/dev/null 2>&1 ); then
+      parts+="${script}:✓ "
+    else
+      parts+="${script}:✗ "
+      overall="failed"
+    fi
+  else
+    parts+="${script}:skip "
+  fi
+done
+
+emit_ctx "$overall" "${parts% }"
+exit 0

package/skills/engineering/afk/detectors/README.md

@@ -0,0 +1,72 @@
+# afk detectors
+
+Shipped detectors invoked by the AFK runtime's hook orchestrator
+at the `pre-spawn` hook point. Each
+detector is a self-contained shell script that decides, on its own,
+whether it applies to the current project; if so, it writes
+`KEY=value` exports into `$RED_AFK_HOOK_ENV_FILE` and exits 0. The
+orchestrator sources that env-file back into the spawn shell, so a
+detector's exports propagate to the worker.
+
+## Convention
+
+A detector is a single `*.sh` file in this directory. Project-local
+detectors at `<project>/.red/hooks/detectors/*.sh` follow the same
+convention. Each script must:
+
+1. Run an **applicability check** first. If the detector does not
+   apply to the current project (or required opt-in env vars are
+   unset), `exit 1` immediately. Exit code 1 means "not applicable"
+   to the orchestrator — it is never an error and never appears in
+   the boot-log.
+2. If applicable, write zero-or-more `KEY=value` lines to
+   `$RED_AFK_HOOK_ENV_FILE`, then `exit 0`. The env-file is unique per
+   invocation and the orchestrator deletes it after sourcing.
+3. Any other exit code is treated as an error. On a `pre-*` hook the
+   orchestrator aborts; on a `post-*` hook it logs and continues.
+
+The orchestrator runs detectors in C-locale alphabetical order:
+shipped first, then project. Detectors share no state — each runs in
+its own subprocess with a fresh `$RED_AFK_HOOK_ENV_FILE`.
+
+## Available env
+
+The orchestrator exports the standard AFK contract before invoking a
+detector:
+
+- `RED_AFK_SLOT` — supervisor slot index (defaults to `0` when not run
+  under the supervisor).
+- `RED_AFK_PLUGIN_DIR`, `PROJECT_ROOT` — discovery roots.
+- `RED_AFK_HOOK_ENV_FILE` — the path the detector must write to.
+
+## Disabling a shipped detector
+
+Set the matching key under `afk.hooks.defaults` in `.red/config.yaml`
+to `false`:
+
+```yaml
+afk:
+  hooks:
+    defaults:
+      cargo: false
+```
+
+Project detectors are never gated by config — they only exist when
+the project authored the file.
+
+## Shipped detectors
+
+- **`cargo.sh`** — applies on Rust projects (`Cargo.toml` present).
+  Exports `CARGO_TARGET_DIR=${RED_AFK_CARGO_TARGET_BASE:-/opt/cargo-target}/slot-${RED_AFK_SLOT}`,
+  pre-creating the directory with `mkdir -p` so the first run on a
+  fresh host succeeds. Override the base with `RED_AFK_CARGO_TARGET_BASE`.
+- **`gradle.sh`** — applies on Gradle projects (`build.gradle*`
+  present) **and** only when `RED_AFK_GRADLE_USER_HOME_BASE` is set in the
+  supervisor's env. Without that base var the detector is a no-op
+  (exits 1) — opt-in so we never claim a path on the user's
+  filesystem without consent. When both conditions hold, exports
+  `GRADLE_USER_HOME=${RED_AFK_GRADLE_USER_HOME_BASE}/slot-${RED_AFK_SLOT}`,
+  pre-creating the directory.
+
+Both detectors give each worker slot its own build cache so Cargo
+and Gradle never serialize on shared lock files.

package/skills/engineering/afk/detectors/cargo.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# cargo.sh — afk pre-spawn detector for Rust projects.
+#
+# Applies when a Cargo.toml exists at PROJECT_ROOT. Exports
+# CARGO_TARGET_DIR=${RED_AFK_CARGO_TARGET_BASE:-/opt/cargo-target}/slot-${RED_AFK_SLOT}
+# so each worker slot gets its own target directory and Cargo
+# never serializes on .cargo-lock between workers.
+#
+# Exit codes:
+#   1 — not a Rust project (no Cargo.toml). The orchestrator treats
+#       this as "skip silently".
+#   0 — applies; KEY=value line(s) written to $RED_AFK_HOOK_ENV_FILE.
+
+set -u
+
+project_root="${PROJECT_ROOT:-$(pwd)}"
+[ -f "$project_root/Cargo.toml" ] || exit 1
+
+slot="${RED_AFK_SLOT:-0}"
+base="${RED_AFK_CARGO_TARGET_BASE:-/opt/cargo-target}"
+target_dir="${base}/slot-${slot}"
+
+mkdir -p "$target_dir"
+
+: "${RED_AFK_HOOK_ENV_FILE:?RED_AFK_HOOK_ENV_FILE not set}"
+printf 'CARGO_TARGET_DIR=%s\n' "$target_dir" >> "$RED_AFK_HOOK_ENV_FILE"
+exit 0

package/skills/engineering/afk/detectors/gradle.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# gradle.sh — afk pre-spawn detector for Gradle projects.
+#
+# Applies when a build.gradle* file exists at PROJECT_ROOT AND the
+# operator has opted in by setting RED_AFK_GRADLE_USER_HOME_BASE. Exports
+# GRADLE_USER_HOME=${RED_AFK_GRADLE_USER_HOME_BASE}/slot-${RED_AFK_SLOT} so each
+# worker slot gets its own Gradle home (caches, daemons, lockfiles).
+#
+# Opt-in by env var is deliberate: we will not claim a path on the
+# user's filesystem without their consent. Without
+# RED_AFK_GRADLE_USER_HOME_BASE the detector is a no-op (exit 1).
+#
+# Exit codes:
+#   1 — not a Gradle project, or RED_AFK_GRADLE_USER_HOME_BASE unset.
+#   0 — applies; KEY=value line written to $RED_AFK_HOOK_ENV_FILE.
+
+set -u
+
+project_root="${PROJECT_ROOT:-$(pwd)}"
+
+shopt -s nullglob
+matches=("$project_root"/build.gradle*)
+shopt -u nullglob
+[ "${#matches[@]}" -gt 0 ] || exit 1
+
+[ -n "${RED_AFK_GRADLE_USER_HOME_BASE:-}" ] || exit 1
+
+slot="${RED_AFK_SLOT:-0}"
+home_dir="${RED_AFK_GRADLE_USER_HOME_BASE}/slot-${slot}"
+
+mkdir -p "$home_dir"
+
+: "${RED_AFK_HOOK_ENV_FILE:?RED_AFK_HOOK_ENV_FILE not set}"
+printf 'GRADLE_USER_HOME=%s\n' "$home_dir" >> "$RED_AFK_HOOK_ENV_FILE"
+exit 0

package/skills/engineering/afk/docs/BOOT-SWEEPS.md

@@ -0,0 +1,81 @@
+# AFK boot-time sweeps (reference)
+
+> Extracted from `afk/SKILL.md` for progressive disclosure. Consulted on demand — not the agent's step-by-step loop.
+>
+> How the bundle reclaims stale tmp-lane state at boot. Durable AFK process state
+> lives in the state tier under `.red/state/castle/`; the agent never runs these by
+> hand because they are the bundle's startup hygiene. Referenced from *Bootstrap*
+> and the *Per-Issue Loop* close step.
+
+The lane janitor only acts on registered disposable lanes under `.red/tmp/`.
+Tmp lane cleanup never deletes `.red/state/`, plugin stores, tracked config, or
+`.red/researches/`.
+
+## Orphan Cleanup (boot-time)
+
+Right after bootstrap and before *Straggler Check*, `/afk` runs two passes. First it reconciles leftover **legacy flat** `.red/tmp/work-*` dirs from the pre-nested scheme (the drain-first cutover, issue #252). This sweep is pid-guarded and slug-sparing: slug-named manual worktrees are left alone, and numeric legacy work dirs are removed only when their recorded or inferable process is no longer live. Then it sweeps the nested attempt dirs in every worker namespace (`.red/tmp/workers/*/*/`, `.red/tmp/go-workers/*/*/`, and `.red/tmp/scout-workers/*/*/`) whose parent worker's `worker.pid` is dead, and afterwards removes dead empty worker shells across those namespaces: dead/corrupt/missing `worker.pid` files plus the worker dir when it contains no attempt dirs or only empty attempt dirs. Live `worker.pid` dirs and non-empty preserved attempt dirs are left untouched. For each orphaned attempt dir:
+
+1. **(Slice D — heartbeat sub-shell retired.)** No zombie reap step is needed; older state files may still carry a `heartbeat_pid` but it's vestigial and ignored.
+2. **Decide fate from issue state.** `gh issue view N --json labels,state`:
+   - `state == CLOSED` → `rm -rf`. Work landed; nothing to inspect.
+   - label `ready-for-human` → **split TTL** based on `envelope.posted` in the attempt state file (see *Terminal-Event Envelope* below):
+     - `envelope.posted == true` → 1-day TTL. The issue thread already carries the canonical record; the local dir is pure redundancy.
+     - `envelope.posted == false` or field missing → 7-day TTL. The envelope POST failed (or this dir predates the envelope writer), so the local notes/log are the only copy.
+   - label `running` (orchestrator crashed mid-issue) → restore `ready-for-agent`, post a recovery comment, then `rm -rf`. Leaving the issue eternally `running` is worse than losing the dir.
+   - any other state → `rm -rf`.
+3. **Fallback on gh failure.** Network / rate-limit error → fall back to mtime TTL: 7 days for dirs with a state file, 1 day for dirs without one. Conservative enough to survive transient outages without losing artefacts the human wanted.
+
+This removes the manual "remember to clean `.red/tmp/`" discipline. Blocker dirs persist until their TTL expires; everything else self-collects on the next `/afk` run.
+
+## Attempt Cap (boot-time, issue #257)
+
+The *Completion sweep* (close step 11) only fires when an issue completes. Issues that **never** complete — blocked-forever work that accumulates retries — would otherwise leak attempt dirs indefinitely. Right after *Orphan Cleanup*, `cap_issue_attempts` walks every attempt dir across all workers, groups them by issue, and per issue prunes (newest attempt kept first) anything over either cap:
+
+- **Age cap** — fixed at 14 days. An attempt dir whose mtime is older than this is reclaimed.
+- **Count cap** — fixed at 5. Only the newest five attempts (by attempt number) for one issue are retained; older ones are reclaimed.
+
+Both caps share the completion sweep's invariant: a **live** worker's active attempt (state file carrying a live `pid`) is never counted toward the cap nor removed.
+
+## On-Demand Branch Reaper (issue #275)
+
+Run `/afk reap` (the bundle's `reap` command) to perform branch hygiene without starting a worker, claiming an issue, or firing lifecycle hooks. The command first prints one line:
+
+```text
+afk branch counts: remote-afk=N local-afk=N
+```
+
+It then applies the same live-branch reapers used during `/afk` boot: remote `afk/*` and local `afk/*`. Open issues and transiently unclassified issues are kept; local branches checked out by any worktree are kept. Each successful deletion logs the branch, issue number, and classification reason. Re-running is a natural no-op once stale refs are gone.
+
+## Docs Sweep (boot-time)
+
+After branch cleanup and before the dependency Unblock Sweep, `/afk` verifies
+that source-of-truth docs under `.red/` are visible from the freshly fetched
+base. The sweep covers glossary docs (`.red/CONTEXT.md`,
+`.red/CONTEXT-MAP.md`, `.red/contexts/**`) and ADR docs (`.red/adr/**`) from
+three signals:
+
+- working-tree changes and deletions;
+- untracked or ignored docs, including adopter repos that ignore `.red/`;
+- doc paths changed by commits ahead of `origin/<base>`.
+
+Operational surfaces are excluded: `.red/tmp/`, `.red/wiki/`, `.red/memory/`,
+`.red/brain/`, and `.red/state/`.
+
+When every stranded doc is publishable, `/afk` creates one isolated worktree
+under `.red/tmp/docs-sweep/` from `origin/<base>`, copies only those doc paths,
+creates one `docs:` commit, pushes a branch, opens one PR, merges it, and fetches
+the base afterward. It never commits in the primary checkout, switches branches,
+stashes, or resets.
+
+When the base cannot be fetched, the PR lane fails, or an ignored doc path class
+has no tracked precedent on `origin/<base>`, boot halts before issue selection or
+fleet slot spawn. The halt message carries the explicit relative file list so a
+maintainer can land or remove the stranded docs deliberately.
+
+## Fleet mode: the supervisor owns the boot (issue #623)
+
+The sweeps above (*Orphan Cleanup*, *Attempt Cap*, live branch cleanup, *Docs Sweep*, the *Unblock Sweep*, and the *Straggler Check*) all read and mutate **shared** `.red/tmp` / branch / `gh` state. When several workers boot at once they would race over that state — the observed failure mode was a fleet collapsing to a single live worker because peers fast-died in their boot sweeps.
+
+So in **fleet mode** the **supervisor** runs the full sweep suite **exactly once, before it spawns any worker**, and logs the result to `.red/tmp/supervisors/default/supervisor.log.toonl` (`boot sweeps complete: orphans … | attempt-cap … | branches … | docs-sweep … | unblocked … | stragglers …`). Every worker the supervisor spawns carries a `RED_AFK_SWEEPS_DONE=1` marker; a marked worker's boot is **bootstrap + claim only** — it ensures its dirs/gitignore/`worker.pid` and goes straight to claiming an issue, skipping every shared sweep. This makes respawns cheap and keeps workers from racing each other over boot state. The supervisor runs the sweeps a single time per lifetime: a worker that exits and is respawned does **not** re-trigger them.
+
+A **solo** `/afk run` (no supervisor, no marker) is unchanged — it runs the full sweep suite itself, exactly as described above. `/afk run --boot-only` reports which path it took: `sweeps ran` for a solo boot, `sweeps skipped (supervisor-owned)` for a marked worker.