/gsd-blocker-recovery

name: gsd-blocker-recovery
description: >-
  GSD blocker and failed-run recovery authority. Use when a GSD run is blocked
  or paused on an auto-pause blocker, a Task attempt failed, a recovery action
  exists, or anyone asks to "clear the blocker", "unblock the run", "resolve
  the pause", or "resume the failed task". Explains the two enforced routes:
  blocker resolution is cleared only by the human in the native terminal, and
  a Task recovery resume is one gated continuation after a real repair with
  concrete evidence — never a state-surgery bypass.

<objective> Teach the enforced blocker/recovery authority model so recovery requests go through the real routes instead of state surgery. GSD's blocker command, Task recovery guards, and domain operations already enforce these boundaries; this skill makes them discoverable so an agent neither attempts a forbidden bypass nor stalls when a legitimate gated route exists. </objective>

<context> GSD separates three identities and three outcomes. Confusing them is the root cause of most bad recovery advice:

| Concept | Meaning | |---|---| | Blocker ID (`workflow_blockers.blocker_id`) | Identifies one blocker. It is not a Recovery Action ID and not an Attempt ID. | | `eligible: true` | Clear-only association eligibility from `/gsd blocker inspect`: the blocker is open, human-owned, and associated with exactly one open auto pause. It does NOT mean the problem is repaired and never means a Task succeeded. | | Native blocker resolution | A human clears an eligible blocker and its pause via `/gsd blocker resolve <id> resolved <reason>` in the native terminal, with nonblank evidence and an explicit y approval. RPC/headless callers can only inspect. Clearing resumes nothing. | | Task Recovery Action resume | One gated continuation for an agent-owned abort/remediation: it authorizes exactly one new (lineage-linked successor) Task Attempt after a real repair, via `gsd_task_recovery_resume` or the operator bridge `/gsd recover <recoveryActionId>`, with repair summary + concrete evidence. The authorization is consumed once. | | Verified Task completion | The Attempt (failed or successor) settles and completes only through the normal host-verification path. Failure or interruption never equals completion. |

Human auto-pause blocker kinds (the only ones a human can clear): `missing_authority`, `missing_access`, `external_dependency`, `consent`, `ambiguous_intent`, `subjective_uat`, `user_limit`. </context>

<core_principle> **BLOCKER APPROVAL IS HUMAN AND NATIVE-TERMINAL-ONLY.** `/gsd blocker resolve` runs an interactive approval component in the real terminal; the caller must press y. In RPC/headless contexts that component never executes, so resolution is impossible there — inspect only. Never synthesize, simulate, or automate that approval; never impersonate the user or fabricate input markers; a dialog response or command exit is not consent. There is no agent or RPC path to approve a blocker resolution.

**RESUME IS GATED, NOT FREE.** A recovery resume is legitimate only when the recorded cause is genuinely repaired and concrete verification evidence accompanies it. The durable guards fail closed: recovery action exists; action is abort or remediate and agent-owned; not linked to a Blocker; not already resumed; Task lifecycle `ready` or `in_progress`; Attempt settled and still owning the causal route; no open blockers. The authorization is consumed by the next lineage-linked Task Attempt and cannot be reused.

**FAIL-CLOSED FENCES ARE LOAD-BEARING.** Resolution re-verifies the checkout, the existing writable database binding, and the inspected snapshot (revision + authority epoch) before the atomic clear. A mismatch refuses and requires a fresh inspect — that is stale-consent protection, not a bug to route around.

**DIAGNOSIS STAYS READ-ONLY.** In forensics or `find_root_cause_only` debug mode, stay inside that goal: inspect, analyze, and hand the operator the route. Do not clear, approve, resume, or repair state as a side effect. </core_principle>

<process>

1. Diagnose read-only

• Inspect the blocker: `/gsd blocker inspect <blockerId>` (or the `gsd_*` status/read tools). Read the returned snapshot: `eligible`, `failure`, blocker `{id, kind, owner, scope, origin, lifecycleState}`, pause, `revision`, `authorityEpoch`.
• For a failed Task attempt, find the recoveryActionId in the auto-mode error/notification text (it is embedded in prose, e.g. "...recoveryActionId: <id>). Resume it with /gsd recover <id>.").
• Post-mortem evidence lives under `.gsd/` (activity, journal, metrics, pauses); the `forensics` skill covers that read-only sweep.

2. Route by identity

• Open eligible human blocker → tell the user to run `/gsd blocker resolve <blockerId> resolved <reason>` in their native terminal and answer the evidence + approval prompts. After it clears, `/gsd auto` re-dispatches normally; clearing did not resume anything itself.
• Agent-owned abort/remediate Recovery Action with a genuinely repaired cause → resume through the gated route: `gsd_task_recovery_resume` with the exact recoveryActionId, a plain-language repair summary, and concrete verification evidence (or the operator runs `/gsd recover <recoveryActionId>`, which prompts for the same inputs). Then re-run `/gsd auto`; the successor Attempt must still pass normal host verification before completion.
• Ineligible or refused → report the guard/failure reason verbatim and re-inspect after any state change. Do not shop for a bypass.

3. Report blockers the honest way

While executing a unit, a plan-invalidating problem is reported through `gsd_task_complete` with `blockerDiscovered: true` (name the category in narrative/knownIssues) — the orchestrator routes it. Never mark a Task complete to escape it, and never hide it.

</process>

<prohibited> These are not recovery methods. None of them can make GSD treat work as unblocked or complete:

• Direct database access or mutation