@reddb-io/red-skills 4.4.0 → 4.5.0

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

@@ -0,0 +1,45 @@
+#!/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 -u
+
+project_root="${PROJECT_ROOT:-$(pwd)}"
+ctx="$(timeout "${RED_SKILLS_HOOK_STDIN_TIMEOUT_S:-5s}" cat 2>/dev/null || true)"
+[ -n "$ctx" ] || ctx='{}'
+
+has_gradle_build=false
+for candidate in "$project_root"/build.gradle*; do
+  [ -f "$candidate" ] || continue
+  has_gradle_build=true
+  break
+done
+if [ "$has_gradle_build" = false ]; 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/runtime/plugins/dev/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/runtime/plugins/dev/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/runtime/plugins/dev/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/runtime/plugins/dev/skills/engineering/afk/detectors/gradle.sh

@@ -0,0 +1,38 @@
+#!/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)}"
+
+has_gradle_build=false
+for candidate in "$project_root"/build.gradle*; do
+  [ -f "$candidate" ] || continue
+  has_gradle_build=true
+  break
+done
+[ "$has_gradle_build" = true ] || 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/runtime/plugins/dev/skills/engineering/afk/examples/only-mine.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# only-mine.sh — example post_pick hook for /afk.
+#
+# Narrows the queue to issues authored by $RED_AFK_GITHUB_LOGIN. Wire it in
+# .red/config.yaml under `afk.hooks.post_pick`:
+#
+#   afk:
+#     hooks:
+#       post_pick:
+#         - "RED_AFK_GITHUB_LOGIN=$(gh api user --jq .login) \
+#            plugins/dev/skills/engineering/afk/examples/only-mine.sh"
+#
+# Contract (PRD #207, issue #210):
+#   stdin  — JSON object: `{ "issues": [ { number, title, labels, body, author, … } ] }`
+#   stdout — empty (context unchanged) OR a JSON object whose `.issues`
+#            replaces the queue. Extra keys are ignored by AFK.
+#   exit   — non-zero is logged; AFK falls back to the un-mutated list.
+#
+# When $RED_AFK_GITHUB_LOGIN is unset we exit 0 with empty stdout so the
+# queue is preserved — declaring this hook becomes a no-op rather than a
+# silent queue wipe.
+
+set -euo pipefail
+
+login="${RED_AFK_GITHUB_LOGIN:-}"
+if [[ -z "$login" ]]; then
+  exit 0
+fi
+
+jq -c --arg login "$login" '
+  {issues: ((.issues // []) | map(select((.author.login // "") == $login)))}
+'

package/runtime/plugins/dev/skills/engineering/afk/examples/red-afk-attempt-action.yml

@@ -0,0 +1,53 @@
+# Example: direct use of the afk-attempt composite action (the COMPOSABLE path).
+#
+# Use this when you want full control over triggers and gating and don't need the
+# turnkey reusable workflow. The composite action is the execution PRIMITIVE
+# (ADR 0062): it sets up Node, installs the runner CLI, and runs ONE AFK attempt
+# against this repo's checkout. You own the trigger and any trust gate.
+#
+# Trade-off vs. the turnkey caller (`rs-afk-attempt.yml`): the reusable ships
+# the author/label-actor trust gate (ADR 0085); the raw action does not. For
+# public repos prefer the reusable. For private repos an `if:` on the actor (as
+# below) is usually enough.
+#
+# Pin the action to a tag (`@v1`) for reproducible runs — that ref also fixes the
+# `dev` bundle version the launcher fetches. Copy to `.github/workflows/afk.yml`.
+
+name: afk
+on:
+  issues:
+    types: [labeled, opened]
+  workflow_dispatch:
+    inputs:
+      issue:
+        description: "Issue number to process."
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  attempt:
+    # Minimal inline gate: a labeled/opened issue carrying `ready-for-agent`,
+    # applied by a trusted actor. EDIT the login list.
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (
+        contains(github.event.issue.labels.*.name, 'ready-for-agent') &&
+        contains(fromJSON('["filipeforattini"]'), github.event.sender.login)
+      )
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: reddb-io/red-skills/.github/actions/afk-attempt@v1
+        with:
+          issue: ${{ github.event.issue.number || inputs.issue }}
+          runner: opencode
+          # Wire whichever key your org provisions (first set wins; see
+          # opencode-env.ts precedence). EDIT.
+          openrouter-api-key: ${{ secrets.OPENROUTER_API_KEY }}
+          minimax-api-key:    ${{ secrets.MINIMAX_API_KEY }}
+          openai-api-key:     ${{ secrets.OPENAI_API_KEY }}

package/runtime/plugins/dev/skills/engineering/afk/examples/rs-afk-attempt.yml

@@ -0,0 +1,76 @@
+# Example: thin caller for the reddb-io/red-skills AFK Actions lane
+#
+# Copy this file into your repo at
+# `.github/workflows/rs-afk-attempt.yml` (the `rs-*`
+# installed-name convention — only the filename changes; the `uses:` ref
+# below keeps the `reusable-` source name), then edit:
+#   1. `allowlist_authors` and `allowlist_label_actors` — the GitHub
+#      logins whose issues + label-applications you trust to drive an
+#      autonomous run. Adopters: keep these short. Public repos: lean
+#      toward 0 or 1 entry (you and your automation bot only).
+#   2. `runner` — defaults to `opencode` (the third runner, ADR 0059).
+#   3. The `secrets:` block — wire whichever of the three API-key
+#      secrets your org provisions. The env-precedence resolver in
+#      `opencode-env.ts` picks the first set; the others are ignored.
+#
+# This file calls the published reusable workflow
+# `reddb-io/red-skills/.github/workflows/reusable-afk-attempt.yml@v1` and
+# is the only piece of YAML your repo needs to enable the AFK Actions
+# lane. The reusable itself also auto-triggers on `issues: labeled`
+# when this caller does NOT route through it (e.g. an external
+# automation applies `ready-for-agent` directly), so the trigger
+# surface is covered from both sides.
+#
+# If you don't want this caller to exist at all (i.e. you only want
+# auto-trigger), you don't need this file: install
+# `reddb-io/red-skills/.github/workflows/reusable-afk-attempt.yml@v1`
+# directly into your `.github/workflows/` and edit the
+# `allowlist_*` inputs there. The `if:` gate on that workflow
+# filters to the `ready-for-agent` label automatically.
+#
+# Trust gate: rigorous by default. The reusable refuses to claim an
+# issue whose author (`issue.user.login`) is NOT in
+# `allowlist_authors` OR whose label-applier (`sender.login` from the
+# labeled event) is NOT in `allowlist_label_actors`. Both checks
+# pass → claim proceeds. Either fails → logged, no claim, no PR.
+# (See #621 for the runtime predicate; the gh-script in the reusable
+# is the source of truth.)
+#
+# Permission scope (recommended minimum): contents: write, issues:
+# write, pull-requests: write. No id-token (no OIDC), no actions:
+# write (the workflow does not publish actions).
+
+name: rs-afk-attempt
+
+on:
+  # Manual trigger from the Actions UI; the reusable's `if:` filter
+  # also auto-triggers on `issues: labeled` regardless of whether
+  # this caller exists.
+  workflow_dispatch:
+    inputs:
+      issue_number:
+        description: "Issue number to process (e.g. 631). Leave EMPTY to auto-pick the oldest open ready-for-agent issue."
+        required: false
+        type: string
+        default: ""
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  # A reusable workflow is invoked at the JOB level via `uses:` (NOT as a step) —
+  # `with:`/`secrets:` are siblings of `uses:`, and the job has no `runs-on`/`steps`.
+  attempt:
+    uses: reddb-io/red-skills/.github/workflows/reusable-afk-attempt.yml@v1
+    with:
+      issue_number: ${{ inputs.issue_number }}
+      runner: opencode
+      enforce_trust_gate: "true"
+      allowlist_authors: "filipeforattini"          # EDIT — your trusted author logins
+      allowlist_label_actors: "filipeforattini"     # EDIT — your trusted label-applier logins
+    secrets:
+      openrouter_api_key: ${{ secrets.OPENROUTER_API_KEY }}
+      minimax_api_key:    ${{ secrets.MINIMAX_API_KEY }}
+      openai_api_key:     ${{ secrets.OPENAI_API_KEY }}

package/runtime/plugins/dev/skills/engineering/afk/hooks/red-cargo

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# red-cargo — built-in pre_worktree library hook for Rust projects.
+#
+# Contract (ADR 0026, PRD #207, issue #211):
+#   stdin   — JSON object: pre_worktree context (issue, target, branch, env).
+#   applicability — decided by the Node resolver before this leaf runs.
+#   stdout  — a JSON object that merges
+#             {env: {CARGO_TARGET_DIR: <slot dir>}} into the context.
+#   exit    — 0. Never aborts the chain.
+#
+# Side effect: mkdir -p the slot target dir so cargo can use it immediately.
+# CARGO_TARGET_DIR=${RED_AFK_CARGO_TARGET_BASE:-/opt/cargo-target}/slot-${RED_AFK_SLOT:-0}
+# so each worker slot gets its own target directory and Cargo never
+# serializes on .cargo-lock between workers.
+#
+# Env contract (RED_AFK_* exported by the orchestrator):
+#   RED_AFK_SLOT                — worker slot number (0-based); defaults to 0.
+#   RED_AFK_CARGO_TARGET_BASE   — base dir for slot target dirs; defaults to
+#                                 /opt/cargo-target. Set in .red/config.yaml
+#                                 via afk.cargo_target_base or by environment.
+#
+# Shadowing: place a same-named file in .red/hooks/red-cargo to replace this
+# default with a project-local variant. An empty (exit-0) file disables it.
+
+set -u
+
+ctx="$(timeout "${RED_SKILLS_HOOK_STDIN_TIMEOUT_S:-5s}" cat 2>/dev/null || true)"
+[ -n "$ctx" ] || ctx='{}'
+
+slot="${RED_AFK_SLOT:-0}"
+base="${RED_AFK_CARGO_TARGET_BASE:-/opt/cargo-target}"
+target_dir="${base}/slot-${slot}"
+
+mkdir -p "$target_dir" 2>/dev/null || true
+
+printf '%s' "$ctx" | jq -c \
+  --arg t "$target_dir" \
+  '. + {env: ((.env // {}) + {CARGO_TARGET_DIR: $t})}'

package/runtime/plugins/dev/skills/engineering/afk/hooks/red-envelope

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# red-envelope — built-in post_attempt library hook (ADR 0026, 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 (RED_AFK_* exported by the orchestrator):
+#   RED_AFK_STATE_FILE      — absolute path to the iteration's afk.state.json;
+#                             when unset/missing, the default is a no-op.
+#   RED_AFK_RESULT_STATUS   — redundant fallback ("success"|"fail") for
+#                             runners/tests that cannot shape a context JSON;
+#                             if ctx.result.status is absent this is used
+#                             instead.
+#
+# Shadowing: place a same-named file in .red/hooks/red-envelope to replace
+# this default with a project-local variant. An empty (exit-0) file disables
+# it.
+
+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/runtime/plugins/dev/skills/engineering/afk/hooks/red-gradle

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# red-gradle — built-in pre_worktree library hook for Gradle projects.
+#
+# Contract (ADR 0026, PRD #207, issue #211):
+#   stdin   — JSON object: pre_worktree context (issue, target, branch, env).
+#   applicability — decided by the Node resolver before this leaf runs.
+#   stdout  — empty (context unchanged) 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.
+#
+# Env contract (RED_AFK_* exported by the orchestrator):
+#   RED_AFK_SLOT                   — worker slot number (0-based); defaults to 0.
+#   RED_AFK_GRADLE_USER_HOME_BASE  — base dir for per-slot Gradle homes;
+#                                    UNSET by default (opt-in). Set in
+#                                    .red/config.yaml or by environment to
+#                                    activate per-slot Gradle isolation.
+#
+# Shadowing: place a same-named file in .red/hooks/red-gradle to replace this
+# default with a project-local variant. An empty (exit-0) file disables it.
+
+set -u
+
+ctx="$(timeout "${RED_SKILLS_HOOK_STDIN_TIMEOUT_S:-5s}" cat 2>/dev/null || true)"
+[ -n "$ctx" ] || ctx='{}'
+
+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/runtime/plugins/dev/skills/engineering/afk/hooks/red-heartbeat

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# red-heartbeat — built-in post_attempt library hook (ADR 0026, PRD #207,
+# issue #212; renamed from post_worker in #226).
+#
+# Stops the orchestrator's per-minute heartbeat side-channel (when a PID is
+# available) 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.
+#
+# Contract:
+#   stdin   — JSON object: post_attempt context (issue, workspace, result).
+#   stdout  — empty (context unchanged). Pure side-effect.
+#   exit    — 0. Never aborts the post_attempt chain.
+#
+# Env contract (RED_AFK_* exported by the orchestrator):
+#   RED_AFK_HEARTBEAT_PID — PID of the orchestrator heartbeat subprocess;
+#                           empty/unset when no external heartbeat runs
+#                           (e.g. the native TS runtime manages heartbeat
+#                           internally). Killing a stale pid is guarded via
+#                           kill -0.
+#   RED_AFK_ITER_LOG      — absolute path to the Worker's canonical
+#                           worker.log.toonl; the boundary payload is appended only when the file
+#                           exists. Unset/empty → skip the marker.
+#
+# Shadowing: place a same-named file in .red/hooks/red-heartbeat to replace
+# this default. An empty (exit-0) file disables it; the orchestrator EXIT
+# trap remains the backstop for heartbeat teardown.
+
+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/runtime/plugins/dev/skills/engineering/afk/hooks/red-validation

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# red-validation — built-in post_merge library hook (ADR 0026, 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. The pre-merge feedback() step in the mechanism layer stays as the
+# safety gate (ADR 0008 — anything that must abort the merge loudly is
+# mechanism, not a hook); 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 (RED_AFK_* exported by the orchestrator):
+#   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.
+#
+# Shadowing: place a same-named file in .red/hooks/red-validation to replace
+# this default with a project-local variant. An empty (exit-0) file disables
+# it.
+
+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