@reddb-io/red-skills-dev 2.75.2

package/skills/engineering/red-setup/issue-tracker-github.md

@@ -0,0 +1,88 @@
+# Issue tracker: GitHub
+
+Issues and Specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
+
+## Dependency & hierarchy operations
+
+Use GitHub's native issue relationships for the human-facing graph, and keep the RedSkills labels/body fallback in sync for AFK machinery.
+
+### Create a native sub-issue relationship
+
+Create the child issue first, then attach it to its parent Spec or map with the sub-issues endpoint. Pass the child's numeric database id with `-F` (typed field) so `gh` sends it as a JSON integer — `-f` sends a string and the endpoint rejects it with HTTP 422:
+
+```bash
+child_id="$(gh api "repos/{owner}/{repo}/issues/<child-number>" --jq '.id')"
+gh api --method POST "repos/{owner}/{repo}/issues/<parent-number>/sub_issues" \
+  -F "sub_issue_id=$child_id"
+```
+
+For Spec slicing, also apply `spec:<parent-number>` to the child. For `/wayfinder`, the parent carries `wayfinder:map` and the child carries exactly one `wayfinder:<type>` label.
+
+### Create a native blocked-by relationship
+
+Use the child's dependency endpoint and pass the blocker issue's numeric database id (again with `-F`, for the same reason):
+
+```bash
+blocker_id="$(gh api "repos/{owner}/{repo}/issues/<blocker-number>" --jq '.id')"
+gh api --method POST "repos/{owner}/{repo}/issues/<child-number>/dependencies/blocked_by" \
+  -F "issue_id=$blocker_id"
+```
+
+**Trap:** `issue_id` must be the blocker's numeric database id from the REST issue `.id` field. It is never the GitHub issue `#number`, and it is never the GraphQL `node_id`. Passing the wrong value can link the wrong issue silently.
+
+For AFK dependencies, also apply `blocked:dependency` plus one `req:<blocker-number>` label per blocker. Keep the strict `## Blocked by` body fallback when the issue should auto-promote after blockers close.
+
+### Read blocked-by edges for audit
+
+Audit the actual native blocker list from the child's endpoint:
+
+```bash
+gh api "repos/{owner}/{repo}/issues/<child-number>/dependencies/blocked_by" \
+  --jq '.[] | {number, id, state, title}'
+```
+
+Use this list when checking whether native blocked-by edges and `req:N` labels diverge.
+
+### Read dependency summary counts
+
+The REST issue payload includes `issue_dependencies_summary`. Its `blocked_by` field is an open-blocker count only:
+
+```bash
+gh api "repos/{owner}/{repo}/issues/<child-number>" \
+  --jq '.issue_dependencies_summary.blocked_by'
+```
+
+`issue_dependencies_summary.blocked_by == 0` means no open blockers remain; it does not enumerate blockers and it should not replace the blocked-by audit endpoint above.
+
+## Wayfinding operations
+
+This repo expresses `/wayfinder` maps and tickets with GitHub Issues plus the RedSkills label vocabulary:
+
+- The map is one GitHub issue labeled `wayfinder:map`.
+- Tickets are native GitHub sub-issues of the map. Each ticket carries exactly one type label: `wayfinder:research`, `wayfinder:prototype`, `wayfinder:grilling`, or `wayfinder:task`.
+- Blocking uses GitHub's native blocked-by relationship. Mirror every native blocking edge as a `req:N` label, per ADR 0094, so existing RedSkills queue and backpressure tools see the same dependency.
+- Create and audit these native relationships with the commands in [Dependency & hierarchy operations](#dependency--hierarchy-operations).
+- The frontier is the set of open child issues whose blockers are all closed and that have no assignee. Claim by assignment: assign yourself before working a ticket, and treat any assigned open ticket as claimed.
+- AFK-typed children (`wayfinder:research` and AFK-safe `wayfinder:task`) enter the autonomous queue with `ready-for-agent` once unblocked. Blocked AFK children use `blocked:dependency` plus their `req:N` labels, not `ready-for-agent`.
+- HITL-typed children (`wayfinder:grilling`, `wayfinder:prototype`, and any human-only `wayfinder:task`) use `ready-for-human` plus assignment to the expected human or role. They move back to the autonomous lane only after `/hitl` or `/retake` determines the blocker is resolved.
+- An unblocked AFK-safe `wayfinder:task` is in `ready-for-agent` and can be dispatched immediately with `/afk --issues <n>`. The wayfinder session must not resolve it inline — route it to the AFK engine instead.
+- If native blocking is unavailable, add a strict `## Blocked by` fallback section to the ticket body and list the blocking issue names with links. Keep the `req:N` labels in sync with that fallback.

package/skills/engineering/red-setup/rsp-retirement-runbook.md

@@ -0,0 +1,35 @@
+# rsp Retirement Operator Runbook
+
+RTK is retired for live RedSkills guidance after the measured parity decision in #1420. This runbook documents the operator-owned machine cleanup. Repository code must not execute these steps automatically.
+
+## Scope
+
+- Live guidance should point at `rsp` wrappers, loss levels, `rsp show`, and the per-repo hook opt-in.
+- Historical ADRs, issue threads, benchmark fixtures, and memory artifacts are history and should not be rewritten only to remove older names.
+- The ambient host-instruction replacement for per-host RTK.md files is tracked in #1415. Treat it as the follow-up deliverable that ships the generated `apps/rsp/generated/AMBIENT-SKILL.md` surface to each host.
+
+## Remove the Pre-Execution Hook
+
+Inspect each agent's local settings and remove the RTK pre-execution hook entry. The exact file is host-specific, but the intent is the same: delete only the hook command that invokes the retired binary and keep unrelated hooks intact.
+
+After editing settings, open a fresh agent session and confirm routine commands are no longer rewritten by the retired hook. In repos that opt in with `rsp.enabled: true`, the RedSkills hook may still rewrite simple supported commands to `rsp`; that is expected.
+
+## Delete the Binary
+
+Remove the retired binary from the operator-managed bin directory or package manager that installed it. Verify that the shell no longer resolves it:
+
+```bash
+command -v <retired-binary>
+```
+
+If another unrelated tool with the same executable name remains on `PATH`, leave that tool alone and document the distinction in local operator notes rather than changing repo guidance.
+
+## Telemetry Database Retention
+
+The old telemetry database includes a parse-failure ledger with forensic value. Keeping it, archiving it, or deleting it is an operator decision:
+
+- **Keep** when recent failures may still inform `rsp` parity audits or incident review.
+- **Archive** when the ledger is no longer active but may be needed for provenance.
+- **Delete** only when local retention policy says the forensic value has expired.
+
+Do not migrate this ledger into repo state. `rsp` stores current reversible elisions in the repo RedDB store under its own collection; the retired telemetry database remains a machine-local artifact.

package/skills/engineering/red-setup/scripts/install-runtime-shim.sh

@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+bin_dir="${XDG_BIN_HOME:-$HOME/.local/bin}"
+name="${1:-red-skills-dev}"
+dev_target="$bin_dir/$name"
+rsp_target="$bin_dir/rsp"
+
+mkdir -p "$bin_dir"
+
+cat >"$dev_target" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+
+env_launcher() {
+  local root
+  for root in \
+    "${RED_SKILLS_DEV_PLUGIN_ROOT:-}" \
+    "${CLAUDE_PLUGIN_ROOT:-}" \
+    "${CODEX_PLUGIN_ROOT:-}" \
+    "${OPENCODE_PLUGIN_ROOT:-}"
+  do
+    [ -n "$root" ] || continue
+    if [ -f "$root/skills/engineering/afk/bin/afk.mjs" ]; then
+      printf '%s\n' "$root/skills/engineering/afk/bin/afk.mjs"
+      return 0
+    fi
+  done
+  return 1
+}
+
+latest_cache_launcher() {
+  local dir
+  for dir in "$HOME"/.codex/plugins/cache/red-skills/dev/* "$HOME"/.claude/plugins/cache/red-skills/dev/*; do
+    [ -f "$dir/skills/engineering/afk/bin/afk.mjs" ] &&
+      printf '%s\t%s\n' "$(basename "$dir")" "$dir/skills/engineering/afk/bin/afk.mjs"
+  done | sort -V | tail -1 | cut -f2-
+}
+
+latest_bundle() {
+  local bundle
+  for bundle in "$HOME"/.cache/red-skills/bundles/dev-*.bundle.min.mjs; do
+    [ -f "$bundle" ] || continue
+    local version="${bundle##*/dev-}"
+    version="${version%.bundle.min.mjs}"
+    printf '%s\t%s\n' "$version" "$bundle"
+  done | sort -V | tail -1 | cut -f2-
+}
+
+launcher="$(env_launcher || true)"
+if [ -n "$launcher" ]; then
+  exec node "$launcher" "$@"
+fi
+
+launcher="$(latest_cache_launcher || true)"
+if [ -n "$launcher" ]; then
+  exec node "$launcher" "$@"
+fi
+
+bundle="$(latest_bundle || true)"
+if [ -n "$bundle" ]; then
+  exec node "$bundle" "$@"
+fi
+
+cat >&2 <<'EOF'
+red-skills-dev: no RedSkills dev runtime found.
+
+Expected one of:
+- an installed dev plugin under ~/.codex/plugins/cache/red-skills/dev/*
+- an installed dev plugin under ~/.claude/plugins/cache/red-skills/dev/*
+- a warmed bundle under ~/.cache/red-skills/bundles/dev-*.bundle.min.mjs
+
+Fallback:
+  npx -y -p @reddb-io/red-skills@<version> red-skills-dev "$@"
+
+Run /red-setup in a repo with plugins.dev.enabled: true, then restart the
+agent session so the plugin SessionStart hook can warm the runtime cache, or use
+the npm direct-run fallback above for a fresh machine.
+EOF
+exit 127
+SH
+
+cat >"$rsp_target" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+
+env_bundle() {
+  local root bundle
+  for root in \
+    "${RED_SKILLS_DEV_PLUGIN_ROOT:-}" \
+    "${CLAUDE_PLUGIN_ROOT:-}" \
+    "${CODEX_PLUGIN_ROOT:-}" \
+    "${OPENCODE_PLUGIN_ROOT:-}"
+  do
+    [ -n "$root" ] || continue
+    for bundle in \
+      "$root/../../dist/rsp.bundle.min.mjs" \
+      "$root/dist/rsp.bundle.min.mjs"
+    do
+      if [ -f "$bundle" ]; then
+        printf '%s\n' "$bundle"
+        return 0
+      fi
+    done
+  done
+  return 1
+}
+
+latest_cache_bundle() {
+  local dir bundle
+  for dir in "$HOME"/.codex/plugins/cache/red-skills/dev/* "$HOME"/.claude/plugins/cache/red-skills/dev/*; do
+    [ -d "$dir" ] || continue
+    for bundle in "$dir/../../dist/rsp.bundle.min.mjs" "$dir/dist/rsp.bundle.min.mjs"; do
+      [ -f "$bundle" ] &&
+        printf '%s\t%s\n' "$(basename "$dir")" "$bundle"
+    done
+  done | sort -V | tail -1 | cut -f2-
+}
+
+latest_bundle() {
+  local cache_root bundle version
+  cache_root="${RED_SKILLS_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/red-skills/bundles}"
+
+  if [ -f "$cache_root/rsp.bundle.min.mjs" ]; then
+    printf '%s\n' "$cache_root/rsp.bundle.min.mjs"
+    return 0
+  fi
+
+  for bundle in "$cache_root"/rsp-*.bundle.min.mjs; do
+    [ -f "$bundle" ] || continue
+    version="${bundle##*/rsp-}"
+    version="${version%.bundle.min.mjs}"
+    printf '%s\t%s\n' "$version" "$bundle"
+  done | sort -V | tail -1 | cut -f2-
+}
+
+find_red_binary() {
+  local cache_root red version
+  cache_root="${RED_SKILLS_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/red-skills/bundles}"
+
+  for red in "$cache_root"/reddb/*/red "$cache_root"/reddb/*/red.exe; do
+    [ -x "$red" ] || continue
+    version="${red%/*}"
+    version="${version##*/}"
+    printf '%s\t%s\n' "$version" "$red"
+  done | sort -V | tail -1 | cut -f2-
+}
+
+with_red_binary() {
+  local red
+  red="$(find_red_binary || true)"
+  if [ -n "$red" ]; then
+    REDDB_BIN="$red" exec node "$@"
+  fi
+  exec node "$@"
+}
+
+bundle="$(env_bundle || true)"
+if [ -n "$bundle" ]; then
+  with_red_binary "$bundle" "$@"
+fi
+
+bundle="$(latest_cache_bundle || true)"
+if [ -n "$bundle" ]; then
+  with_red_binary "$bundle" "$@"
+fi
+
+bundle="$(latest_bundle || true)"
+if [ -n "$bundle" ]; then
+  with_red_binary "$bundle" "$@"
+fi
+
+cat >&2 <<'EOF'
+rsp: no RedSkills rsp runtime found.
+
+Expected one of:
+- an installed dev plugin with dist/rsp.bundle.min.mjs under ~/.codex/plugins/cache/red-skills/dev/*
+- an installed dev plugin with dist/rsp.bundle.min.mjs under ~/.claude/plugins/cache/red-skills/dev/*
+- a warmed rsp bundle under ${RED_SKILLS_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/red-skills/bundles}
+
+Run /red-setup in a repo with plugins.dev.enabled: true, then restart the
+agent session so the plugin SessionStart hook can warm the runtime cache.
+EOF
+exit 127
+SH
+
+chmod 0755 "$dev_target" "$rsp_target"
+printf 'installed %s\n' "$dev_target"
+printf 'installed %s\n' "$rsp_target"

package/skills/engineering/red-setup/triage-labels.md

@@ -0,0 +1,176 @@
+# Triage Labels
+
+Canonical label vocabulary and full issue lifecycle. This is the single source of truth — `/triage`, `/afk`, `/to-tickets`, and `/to-spec` all reference this file.
+
+## Label Mapping
+
+The skills speak in terms of canonical triage roles. Map them here to the actual label strings used in this repo's issue tracker.
+
+| Canonical role     | Label in our tracker | Applied by                            | Removed by                          |
+| ------------------ | -------------------- | ------------------------------------- | ----------------------------------- |
+| `needs-triage`     | `needs-triage`       | `red-issues-needs-triage` workflow, `/triage` | `/triage` (when state transitions) |
+| `needs-info`       | `needs-info`         | `/triage`                             | `/triage` (when reporter replies)   |
+| `ready-for-agent`  | `ready-for-agent`    | `/triage`, `/to-tickets`               | `/afk` (when claiming)              |
+| `running`          | `running`            | `/afk` (when claiming an issue)       | `/afk` (on close, blocker, or release) |
+| `ready-for-human`  | `ready-for-human`    | `/triage`, `/afk` (on blocker)        | maintainer                          |
+| `wontfix`          | `wontfix`            | `/triage` (then close)                | rarely — usually issue closes       |
+| `needs-slicing`    | `needs-slicing`      | `/to-spec` (on publish)                | `/to-tickets` (when slices are created) |
+| `type:spec`         | `type:spec`           | `/to-spec` (on publish)                | never — type marker, permanent       |
+
+Edit the right-hand column to match whatever vocabulary you actually use.
+
+## Full Lifecycle
+
+Every issue moves through this state machine. Arrows show the transitions; the actor on each arrow is the skill or workflow responsible.
+
+```
+                       ┌─────────────────────┐
+                       │   issue created     │
+                       │   (any source)      │
+                       └──────────┬──────────┘
+                                  │
+              red-issues-needs-triage workflow
+              (auto on opened/reopened, no label)
+                                  ▼
+                       ┌─────────────────────┐
+        ┌─────────────│    needs-triage     │────────────┐
+        │              └──────────┬──────────┘            │
+        │                         │                       │
+   /triage:                  /triage:                /triage:
+   needs-info               wontfix                  ready-for-*
+        │                         │                       │
+        ▼                         ▼                       │
+┌──────────────┐           ┌──────────────┐               │
+│ needs-info   │           │   wontfix    │               │
+│ (await user) │           │   + close    │               │
+└──────┬───────┘           └──────────────┘               │
+       │                                                  │
+  reporter replies                                        │
+   → /triage                                              │
+       │                                                  │
+       └──────────────────► needs-triage                  │
+                                                          ▼
+                              ┌───────────────────────────────────┐
+                              │                                   │
+                              ▼                                   ▼
+                  ┌──────────────────────┐         ┌──────────────────────┐
+                  │   ready-for-agent    │         │   ready-for-human    │
+                  │   (## Agent brief    │         │   (needs judgment)   │
+                  │    in body)          │         └──────────────────────┘
+                  └──────────┬───────────┘                     │
+                             │                                 │
+                       /afk claim:                       human picks up
+                       removes ready-for-agent,          (manual impl,
+                       adds running                       eventually closes)
+                             │
+                             ▼
+                  ┌──────────────────────┐
+                  │       running        │
+                  │  (worktree active,   │
+                  │   heartbeats post)   │
+                  └──────────┬───────────┘
+                             │
+              ┌──────────────┼──────────────┐
+              │              │              │
+        /afk: DONE      /afk: BLOCKED   /afk: merge conflict
+              │              │              │
+              ▼              ▼              ▼
+        ┌─────────┐   ┌────────────────────────────┐
+        │ closed  │   │ remove running,            │
+        │ + merge │   │ add ready-for-human,       │
+        │ comment │   │ worktree preserved         │
+        └─────────┘   └────────────────────────────┘
+```
+
+## State Definitions
+
+### `needs-triage`
+Maintainer has not evaluated the issue yet. **Applied automatically** by `red-issues-needs-triage.yml` workflow on every fresh `opened`/`reopened` issue with no labels. Manual application by `/triage` when the maintainer puts an evaluated issue back into the queue. Removed by `/triage` when the issue transitions to a definitive state.
+
+### `needs-info`
+The triage agent or maintainer needs more information from the reporter before a decision can be made. Removed by `/triage` once the reporter responds and the issue cycles back through `needs-triage`.
+
+### `ready-for-agent`
+The issue body contains a complete `## Agent brief` section (see `triage/AGENT-BRIEF.md`) that forms a contract sufficient for an AFK agent to implement without human context. **This is the only state `/afk` consumes.** Applied by `/triage` (after grilling) or `/to-tickets` (on creation when the slice is AFK-safe).
+
+### `running`
+`/afk` has claimed the issue and is actively executing it. Applied atomically with the removal of `ready-for-agent` so two parallel `/afk` runs cannot race on the same issue. The orchestrator's heartbeat sub-shell posts `:one:` → `:four:` comments every 10 min while this label is present. Removed on close (success), on blocker (replaced with `ready-for-human`), or on graceful release (if the user interrupts the loop).
+
+### `ready-for-human`
+The issue requires human decision or resolution before it can proceed or be delegated. Two sources: `/triage` decides it during evaluation (e.g. architectural call, design review needed), or `/afk` promotes it from `running` after a blocker (inner agent gave up, merge conflict couldn't be auto-resolved, both runners exhausted). When `/afk` promotes, the worktree is **preserved at the moment of blocker** so the human can inspect or resolve the blocker in place.
+
+### `wontfix`
+Will not be actioned. Applied by `/triage`. For bugs, paired with a polite explanation and close. For enhancements, paired with a `.out-of-scope/*.md` entry (see `triage/OUT-OF-SCOPE.md`).
+
+### `type:spec`
+Permanent type marker for Spec issues created by `/to-spec`. A Spec is a planning artifact, **not an implementable slice** — it describes *what* to build at the product level and must be split into child issues by `/to-tickets` before any agent can execute. `/afk` hard-filters issues carrying `type:spec` from its candidate list even if `ready-for-agent` was applied by mistake. Never remove this label.
+
+### `needs-slicing`
+The Spec has been published but `/to-tickets` has not yet split it into child slices. Applied by `/to-spec` on publish, removed by `/to-tickets` once at least one child issue with `spec:{N}` exists. `/afk` counts these in its straggler check so a forgotten Spec surfaces before the loop runs dry.
+
+## Heartbeat Comments
+
+While `running`, `/afk` posts a heartbeat comment every 10 minutes so the issue is never silent during long executions:
+
+```
+t=10 min  →  :one:
+t=20 min  →  :two:
+t=30 min  →  :three:
+t=40 min  →  :four:
+t=50 min  →  :one:   (cycle resets)
+```
+
+Stops on any terminal transition out of `running`.
+
+## Optional Auxiliary Labels
+
+These exist for filtering and don't drive lifecycle transitions:
+
+| Label          | Meaning                                         | Applied by                       |
+| -------------- | ----------------------------------------------- | -------------------------------- |
+| `bug`          | Something is broken                             | `/triage`                        |
+| `enhancement`  | New feature or improvement                      | `/triage`                        |
+| `priority:high` | Urgent / high-impact — `/afk` drains these first | `/triage` or maintainer        |
+| `priority:low`  | Everything else                                  | `/triage` or maintainer        |
+| `spec:{N}`      | Issue belongs to Spec #N                         | `/to-tickets` when splitting a Spec |
+| `wayfinder:map` | Planning map Ticket for work too large for one agent session. Carries `## Destination`, `## Not yet specified`, and `## Out of scope`; the map is an index, not a store. | `/wayfinder` |
+| `wayfinder:research` | Wayfinder child type for AFK-typed research scoped to one session. Unblocked children use `ready-for-agent`; blocked children use `blocked:dependency` plus `req:N`. | `/wayfinder` |
+| `wayfinder:grilling` | Wayfinder child type for HITL-typed decision work routed to a `/start` session and claimed by assignment. | `/wayfinder` |
+| `wayfinder:prototype` | Wayfinder child type for HITL-typed design or logic exploration routed to a `/prototype` session and claimed by assignment. | `/wayfinder` |
+| `wayfinder:task` | Wayfinder child type for AFK-typed implementation/docs work scoped to one session. Unblocked children use `ready-for-agent`; blocked children use `blocked:dependency` plus `req:N`. | `/wayfinder` |
+| `runner-error` | `/afk` fleet supervisor parked a slot after fast-death streak; affected issues were restored to `ready-for-agent` after the runner was discarded | `/afk` fleet supervisor on circuit trip |
+| `landing:manual` | Per-issue **manual-landing** mode (#1049): on a `ready-for-agent` issue, `/afk` runs the full pipeline + opens the PR, then **holds for a human's merge click** (parks `ready-for-human`, never auto-merges, never re-runs the agent). The issue auto-closes on PR merge via `Closes #N`. Lets agent-codable slices that must not be auto-merged stay in the autonomous lane instead of being hand-dispatched via `/go`. | `/triage` at brief time, or `/hitl`'s **delegable-manual-landing** disposition |
+
+`runner-error` is the only auxiliary label `/afk` may create autonomously: the fleet supervisor calls `gh label create runner-error` when it trips the circuit breaker, so the cleanup never fails just because the label has not been provisioned. Provision it up front via `/red-setup` to keep colour/description consistent across repos.
+
+## Blocked Reasons (`blocked:<reason>`) — typed, auto-classified
+
+`/afk` already computes a precise terminal outcome for every iteration; instead of flattening every failure to one `blocked`, it tags the issue with the matching **`blocked:<reason>`** label so the backlog is filterable by *what kind* of block it is. The reason is derived automatically from the outcome — **no human classification**.
+
+| Outcome (runtime) | Label | Recovery | Retry cap (env) |
+| ----------------- | ----- | -------- | --------------- |
+| runner quota / both exhausted | `blocked:quota` | **auto-retry** → ready-for-agent | 3 (`RED_AFK_RETRY_QUOTA`) |
+| runner transport/setup failed | `blocked:runner-transient` | **auto-retry** → ready-for-agent | 3 (`RED_AFK_RETRY_RUNNER_TRANSIENT`) |
+| couldn't integrate or land | `blocked:merge-conflict` | **auto-retry** (base settles) | 3 (`RED_AFK_RETRY_MERGE`) |
+| mergeable PR blocked by CI (required check failed / still pending) | `blocked:ci` | **pages** → ready-for-human / CI-aware finisher (never re-runs the agent) | — (never auto) |
+| agent exited without a sentinel | `blocked:crashed` | **auto-retry once** (transient) | 1 (`RED_AFK_RETRY_CRASH`) |
+| a user `pre_*` guard hook rejected it | `blocked:policy` | **auto-retry once** | 1 (`RED_AFK_RETRY_POLICY`) |
+| agent emitted `<promise>BLOCKED</promise>` | `blocked:spec` | **pages** → ready-for-human (decide/clarify) | — (never auto) |
+| feedback gate failed (test/lint/build) | `blocked:validation` | **pages** → ready-for-human (review diff) | — (never auto) |
+| stall-reaper killed a hung worker | `blocked:stalled` | **auto-retry** → ready-for-agent (clean) | 3 (`RED_AFK_RETRY_STALLED`) |
+| worktree/base/push setup failed | `blocked:infra` | pages → ready-for-human (ops) | — |
+
+**Bounded auto-recovery (live).** The recoverable reasons loop back to `ready-for-agent` and are retried, up to their per-reason cap (counting real attempt-ledger attempts); on the cap they **escalate** to `ready-for-human` with a `🤖 /afk escalating … retry budget exhausted (attempt N/cap)` comment. So a transient hiccup self-heals and never pages, but a persistent one still surfaces — bounded, no runaway loop. The supervisor stall-reaper's `blocked:stalled` re-queue is bounded by the **same** policy (`RED_AFK_RETRY_STALLED`, default 3). Caps are env-tunable (non-numeric/0 → default). `spec`, `validation`, and `ci` **always page** (a human must decide / review the diff / drive the open PR to merge); `dependency` waits on its `req:N` edges (never pages). `blocked:ci` (#812) is deliberately non-recoverable: the work is already complete and committed on the open PR, so re-running the agent would re-spend tokens for nothing — a human / CI-aware finisher merges the existing PR once CI is green. **A re-queue is hygienic:** promoting an issue to `ready-for-agent` (auto-retry) or `running` (claim) sheds any `blocked:*` label in the same edit, so no live/queued issue ever carries `ready-for-agent`/`running` together with `blocked:*`. The typed `blocked:<reason>` label rides only the `ready-for-human` escalation.
+
+> Not yet wired: time-based backoff (today the re-queue is immediate; the cap is what prevents runaway).
+
+All `blocked:*` labels are created on the fly when first applied (mirroring `runner-error`) and provisioned by `/red-setup`.
+
+## Naming Convention
+
+All labels follow one of two shapes:
+
+- **kebab-case** — `needs-triage`, `ready-for-agent`, `running`, `wontfix`, `bug`.
+- **`prefix:value`** — `priority:high`, `spec:42`.
+
+No uppercase, CamelCase, snake_case, or spaces. GitHub matches labels case-insensitively for filtering but stores the case you create them with — keep the tracker clean by normalising on creation. `/red-setup` surfaces non-conforming labels and offers to rename via `gh label edit "Old Name" --name "new-name"`.

package/skills/engineering/red-setup/workflows/red-issues-needs-triage.yml

@@ -0,0 +1,36 @@
+# Auto-applies the `needs-triage` label to any newly opened or reopened issue
+# that has no labels yet. Keeps fresh issues from slipping past `/triage` and
+# `/afk` (which only consumes `ready-for-agent`).
+#
+# Installed by `/red-setup`. Filename prefix `red-` marks it as belonging
+# to the RedSkills ecosystem.
+
+name: red-issues-needs-triage
+
+on:
+  issues:
+    types: [opened, reopened]
+
+permissions:
+  issues: write
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const issue = context.payload.issue;
+            const labels = (issue.labels || []).map(l => l.name);
+            if (labels.length > 0) {
+              core.info(`Issue #${issue.number} already labelled (${labels.join(', ')}). Skipping.`);
+              return;
+            }
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo:  context.repo.repo,
+              issue_number: issue.number,
+              labels: ['needs-triage']
+            });
+            core.info(`Applied 'needs-triage' to #${issue.number}.`);