forgedock 1.8.2 → 1.8.4

package/commands/design-bench.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 description: Run the ABC benchmark — reference URL → design-blind brief → render arms A/B/C → blind judge → scorecard with win-rates over n runs
 argument-hint: "[<brief-name>|all] [--n <runs>] [--corpus-version <ver>]"
 install: internal

package/commands/design-render-critique-loop.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 description: Render a design from its FORGE:DESIGN_SPEC, critique the rendered pixels against the perceptual negatives, and iterate until it passes or the budget is spent — the missing reward signal.
 argument-hint: "[<issue-number>|<spec-path>] [--max-iters <n>] [--viewports desktop,mobile]"
 install: internal

package/commands/design.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 description: Route a design GitHub issue through the UI Taste Harness — investigate → architect → implement → critique loop → user-feedback loop → close — accumulating FORGE:DESIGN_* annotations and driving the design:* label state machine to design:shipped.
 argument-hint: <issue-number> | <brief-name>
 install: internal

package/commands/forge-stats.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 description: Track command sizes, detect bloat, compare against baselines and thresholds
 argument-hint: "[diff | baseline | full | cost]"
 install: internal

package/commands/orchestrate/config.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/orchestrate/phase-1-resolve.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 
 install: core
 ---

package/commands/orchestrate/phase-2-triage.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/orchestrate/phase-2.5-synthesis.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/orchestrate/phase-3-dependency.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -1393,6 +1394,7 @@ fi
 #    hold_merged_trail, resolve_orch_login, trail_escalation_state, release_merged_trail (reverify_merged_trail is
 #    nested inside the classifier). It reports a missing helper on stderr and classifies GATED. The same trusted-author
 #    filter (OWNER/MEMBER/COLLABORATOR or the orchestrator login) applies to the release/fail markers on wake.
+#    forge#3169: merged + needs-human with no escalation record classifies GATED on wake (never keyed on the verifier).
 declare -A ISSUE_CLASS
 declare -A ISSUE_FILES
 DONE_ISSUES=()

package/commands/orchestrate/phase-4-execution.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -1342,21 +1343,19 @@ For an OpenCode completion, retain `OPENCODE_DISPATCH_MAP[{NUMBER}]` until the t
 ```bash
 # hold_merged_trail <issue> <trail-text> (forge#3156): the single escalation path for a merged issue whose phase
 # trail failed or could not be verified. Used by Step 4B item 0 and by the classifier's wake re-verification.
-# Order matters: the `needs-human` label is written FIRST (read-back verified, 3 tries) because the classifier
-# holds on merged + needs-human even before the comment exists; the comment follows (verified, 2 tries) and is
-# the audit record that lets a human release the hold. Returns 0 when the label hold is verified, 1 otherwise.
+# Order matters (forge#3169): the escalation COMMENT is posted FIRST (re-read immediately before each post, skipped when
+# an ACTIVE escalation already exists, verified ACTIVE by re-read after), then the `needs-human` label is written
+# (read-back verified, 3 tries). The comment is the durable audit record, independent of the verifier, so a label-only
+# hold is not the normal state and a human release always has an anchor to be recorded against. Returns 0 only when both
+# halves are verified; otherwise returns 1 and stderr names which half failed (the label is still attempted after a
+# comment failure, because holding dependents is the safe side).
 hold_merged_trail() {
-  local N="$1" TXT="$2" TRY HELD=1
-  for TRY in 1 2 3; do
-    gh issue edit "$N" -R {GH_REPO} --add-label "needs-human" >/dev/null 2>&1 || true # <!-- allowlist:check-command-side-effects -->
-    if gh issue view "$N" -R {GH_REPO} --json labels --jq '[.labels[].name] | join(",")' 2>/dev/null \
-         | grep -qE '(^|,)needs-human(,|$)'; then HELD=0; break; fi
-  done
-  [ "$HELD" -ne 0 ] && echo "PHASE TRAIL HOLD FAILED: #${N} — needs-human label could not be verified; dependents are NOT held. Hold them manually." >&2
+  local N="$1" TXT="$2" TRY COMMENTED=1 HELD=1
   for TRY in 1 2; do
     # forge#3157: dedupe only against an ACTIVE escalation, so a re-escalation after a recorded release posts a new one.
+    # forge#3169: re-read right before each post (cache entry removed) to narrow the concurrent-classifier duplicate window.
     [ -n "${TRAIL_CACHE_DIR:-}" ] && rm -f "$TRAIL_CACHE_DIR/trail-$N"
-    [ "$(trail_escalation_state "$N")" = "ACTIVE" ] && break
+    if [ "$(trail_escalation_state "$N")" = "ACTIVE" ]; then COMMENTED=0; break; fi
     gh issue comment "$N" -R {GH_REPO} --body "<!-- FORGE:PHASE_TRAIL_FAILED -->
 #${N} merged with an incomplete phase trail (or one that could not be verified), detected by /orchestrate.
 
@@ -1364,10 +1363,19 @@ hold_merged_trail() {
 ${TXT}
 \`\`\`
 
-The PR is already merged, so \`/work-on\` cannot re-run the missing phases. Review the merged change, then remove \`needs-human\` to release dependents held as \`blocked-on-human-merge\`." >/dev/null 2>&1 || true
+The PR is already merged, so \`/work-on\` cannot re-run the missing phases. Review the merged change, then remove \`needs-human\` to release dependents held as \`blocked-on-human-merge\`." >/dev/null 2>&1 || true # <!-- allowlist:check-command-side-effects -->
+    [ -n "${TRAIL_CACHE_DIR:-}" ] && rm -f "$TRAIL_CACHE_DIR/trail-$N"
+    if [ "$(trail_escalation_state "$N")" = "ACTIVE" ]; then COMMENTED=0; break; fi
+  done
+  for TRY in 1 2 3; do
+    gh issue edit "$N" -R {GH_REPO} --add-label "needs-human" >/dev/null 2>&1 || true # <!-- allowlist:check-command-side-effects -->
+    if gh issue view "$N" -R {GH_REPO} --json labels --jq '[.labels[].name] | join(",")' 2>/dev/null \
+         | grep -qE '(^|,)needs-human(,|$)'; then HELD=0; break; fi
   done
   [ -n "${TRAIL_CACHE_DIR:-}" ] && rm -f "$TRAIL_CACHE_DIR/trail-$N"
-  return "$HELD"
+  [ "$COMMENTED" -ne 0 ] && echo "PHASE TRAIL HOLD FAILED: #${N} — escalation comment could not be verified (audit record missing); hold dependents manually." >&2
+  [ "$HELD" -ne 0 ] && echo "PHASE TRAIL HOLD FAILED: #${N} — needs-human label could not be verified; dependents are NOT held. Hold them manually." >&2
+  [ "$COMMENTED" -eq 0 ] && [ "$HELD" -eq 0 ]
 }
 
 # resolve_orch_login (forge#3168): prints the login of the identity that authors the orchestrator's own FAILED/RELEASED
@@ -1410,6 +1418,8 @@ trail_escalation_state() {
 
 # release_merged_trail <issue> (forge#3157): record that a human cleared a merged-trail hold, so the escalation
 # stops gating. Call only after classify_predecessor_state reported DONE for a merged issue whose escalation is ACTIVE.
+# Only an ACTIVE escalation is released here: hold_merged_trail posts the comment before the label (forge#3169), so a
+# human release of a label-only (ABSENT) hold is not expected and is not recorded (avoids a stray RELEASED marker).
 # Idempotent (no-op unless ACTIVE) and never run in dry-run. The comment must not contain the escalation marker text.
 release_merged_trail() {
   local N="$1"
@@ -1452,13 +1462,29 @@ classify_predecessor_state() {
 
   # reverify_merged_trail: re-run the phase-trail verifier for a merged predecessor that has NO escalation
   # record (forge#3156), so wake reconstruction does not trust the `workflow:merged` label alone. Prints OK
-  # when the trail verifies, UNVERIFIED otherwise. FORGE_ROOT comes from the Step 4A-pre/item 0 bootstrap; if
-  # it is unresolved the verifier cannot run, so a predecessor already holding `needs-human` fails closed
-  # (UNVERIFIED), while a plain merged one is trusted (OK) because item 0 verified it on its completion.
+  # when the trail verifies, UNVERIFIED otherwise. Fails closed: a wake runs in a fresh shell where FORGE_ROOT is
+  # unset, so the helper resolves it itself (canonical bootstrap, only when unset); if it is still unresolved or
+  # the verifier is missing, the result is UNVERIFIED for every predecessor, never OK.
   reverify_merged_trail() {
-    local P="$1" HAS_HUMAN="$2" RC
+    local P="$1" RC
+    if [ -z "${FORGE_ROOT:-}" ]; then
+      # FORGE_ROOT bootstrap (canonical; keep byte-identical across specs, guarded by scripts/forge-root.test.sh)
+      FORGE_ROOT=""
+      if [ -n "${FORGEDOCK_HOME:-}" ]; then case "$FORGEDOCK_HOME" in /*) FORGE_ROOT="$FORGEDOCK_HOME" ;; esac; else
+        # Portable to bash 3.2 (macOS), BSD/GNU coreutils and zsh: no mapfile, no sort -V, no bare globs (zsh aborts on no match).
+        _l="$HOME/.claude/commands/work-on.md"; _l="$(readlink -f "$_l" 2>/dev/null || readlink "$_l" 2>/dev/null)"; [ -n "$_l" ] && _l="$(dirname "$(dirname "$_l")")"
+        # newest cached version first: numeric major.minor.patch of the version dir name only; a release outranks its pre-release (1.10.0 > 1.9.0 > 1.9.0-rc1)
+        _v="$(find -L "$HOME/.claude/plugins/cache" -mindepth 3 -maxdepth 3 -type d 2>/dev/null | awk -F/ '$(NF-1)=="forgedock"{v=$NF;p=index(v,"-");r=1;if(p){v=substr(v,1,p-1);r=0};split(v,a,".");printf "%d %d %d %d %s\n",a[1],a[2],a[3],r,$0}' | sort -k1,1nr -k2,2nr -k3,3nr -k4,4nr | cut -d' ' -f5-)"
+        _m="$(find -L "$HOME/.claude/plugins/marketplaces" -mindepth 1 -maxdepth 1 -type d -iname '*forgedock*' 2>/dev/null)"
+        # '${CLAUDE_PLUGIN_ROOT}' is substituted by Claude Code when it loads a plugin spec (the exact spelling only, never as an env var), so a running plugin resolves to its own root first; unsubstituted (other runtimes) it stays a literal that the /* check rejects.
+        _k="$(printf '%s\n' '${CLAUDE_PLUGIN_ROOT}' "${FORGE_HOME:-}" "$_l" "$_v" "$_m")"
+        while IFS= read -r _c; do
+          case "$_c" in /*) [ -z "$FORGE_ROOT" ] && [ -f "$_c/scripts/verify-phase-trail.sh" ] && [ -f "$_c/scripts/lint-dispatch-prompt.sh" ] && [ -f "$_c/scripts/is-docs-only.sh" ] && [ -f "$_c/bin/engine/resolve.mjs" ] && [ -f "$_c/bin/engine/orchestrate-canary.mjs" ] && [ -f "$_c/bin/engine/admission.mjs" ] && FORGE_ROOT="$_c" ;; esac
+        done <<< "$_k"
+      fi
+    fi
     if [ -z "${FORGE_ROOT:-}" ] || [ ! -f "$FORGE_ROOT/scripts/verify-phase-trail.sh" ]; then
-      [ "$HAS_HUMAN" = "yes" ] && echo "UNVERIFIED" || echo "OK"; return
+      echo "UNVERIFIED"; return
     fi
     bash "$FORGE_ROOT/scripts/verify-phase-trail.sh" "$P" -R {GH_REPO} --code-diff >/dev/null 2>&1; RC=$?
     [ "$RC" -eq 0 ] && echo "OK" || echo "UNVERIFIED"
@@ -1469,13 +1495,14 @@ classify_predecessor_state() {
   elif echo "$PRED_LABELS" | grep -qx "workflow:merged" && echo "$PRED_LABELS" | grep -qx "needs-human"; then
     # forge#3148: GATED when Step 4B item 0 escalated a merged issue with an incomplete phase trail
     # (the code is in the base branch, but /work-on cannot repair a merged issue, so a human must review it;
-    # dependents wait until a human clears needs-human). Item 0 adds `needs-human` BEFORE posting the comment
-    # (forge#3156), so merged + needs-human with no comment yet is either the in-flight window or a stale label:
-    # re-verify the trail to tell them apart (clean trail => stale label => DONE). Unreadable comments fail closed.
+    # dependents wait until a human clears needs-human). forge#3169: the hold is NOT keyed on the verifier. A passing
+    # verifier does not mean "not held" (an agent-reported bypass verifies clean), and hold_merged_trail posts the
+    # comment before the label, so merged + needs-human with no record is a failed/partial hold: fail closed (GATED).
+    # A human release is the removal of needs-human, recorded by the release sweep via release_merged_trail.
     local TRAIL_ESC
     TRAIL_ESC=$(trail_escalation_state "$PRED")
     case "$TRAIL_ESC" in
-      ABSENT)   [ "$(reverify_merged_trail "$PRED" yes)" = "OK" ] && echo "DONE" || echo "GATED" ;;
+      ABSENT)   echo "GATED" ;;    # forge#3169: no record yet; never trust the verifier to release a labelled hold
       RELEASED) echo "DONE" ;;   # forge#3157: a human release was recorded after the last escalation; this needs-human is unrelated
       *)        echo "GATED" ;;  # ACTIVE or UNREADABLE: fail closed
     esac
@@ -1483,16 +1510,20 @@ classify_predecessor_state() {
     # forge#3156: no needs-human. A recorded escalation (ACTIVE or RELEASED) means a human already released the hold
     # (DONE, forge#3157: the sweep records it via release_merged_trail); otherwise re-verify the trail so a merged
     # predecessor that item 0 never got to escalate (orchestrator died mid-hold, wake reconstruction) is not trusted
-    # on the label alone.
+    # on the label alone. forge#3169: hold only when the record re-reads exactly ABSENT immediately before (an
+    # UNREADABLE read classifies GATED without writing), so a concurrent classifier or a recorded release is not
+    # overridden and at most one escalation comment is posted in the common case.
     case "$(trail_escalation_state "$PRED")" in
       ACTIVE|RELEASED) echo "DONE" ;;
+      UNREADABLE) echo "GATED" ;;
       *)
-        if [ "$(reverify_merged_trail "$PRED" no)" = "OK" ]; then
+        if [ "$(reverify_merged_trail "$PRED")" = "OK" ]; then
           echo "DONE"
         else
           # Unverified trail with no hold on record: establish it now so a human can release it.
           # Output is discarded (stdout is the classification), but a failed hold is reported on stderr, not swallowed.
-          [ "${DRY_RUN:-false}" = "true" ] || hold_merged_trail "$PRED" "PHASE_TRAIL: FAIL (re-verified at wake classification)" >/dev/null || echo "classify_predecessor_state: hold on #${PRED} could not be verified" >&2
+          [ -n "${TRAIL_CACHE_DIR:-}" ] && rm -f "$TRAIL_CACHE_DIR/trail-$PRED"
+          [ "${DRY_RUN:-false}" = "true" ] || [ "$(trail_escalation_state "$PRED")" != "ABSENT" ] || hold_merged_trail "$PRED" "PHASE_TRAIL: FAIL (re-verified at wake classification)" >/dev/null || echo "classify_predecessor_state: hold on #${PRED} could not be verified" >&2
           echo "GATED"
         fi ;;
     esac
@@ -1879,13 +1910,15 @@ done
    - `TRAIL_RC -ge 2` (`PHASE_TRAIL: ERROR`: unreadable trail, unreadable labels, or 127 when the verifier is unresolvable) → classify as **BLOCKED (infrastructure)**, NOT a bypass. A re-dispatched `/work-on` would hit the same unreadable or unresolvable verifier in its resume preflight, so do NOT re-dispatch. Surface `PHASE TRAIL ERROR: #{NUMBER} — <TRAIL line>` in the operator status update, add `needs-human`, and continue with the rest of the batch.
    - `TRAIL_RC=1` (`PHASE_TRAIL: FAIL`) → classify as a **bypass** (handling below).
 
+   **Transient GitHub outage** — if a worker returns (or the issue's latest blocker comment shows) a blocker starting with `github-unavailable:`, the issue is not human-gated: do not count it as `needs-human`/GATED. Re-dispatch it once after the other ready issues (the `/work-on` router already retried each phase twice). <!-- field test: GitHub HTTP 500 window -->
+
    On `PHASE_TRAIL: FAIL`, classify the issue as a **bypass**, never `DONE`. Classify ONLY on objective evidence — the trail verdict above and the issue's labels. Do NOT reclassify an issue from a worker's own narrative ("ran inline", "dispatched reviewers directly", "skipped an optional step"): every phase runs forked and the merge itself is gated (CI green on the exact merged commit, reviewed head or docs-only delta, phase trail), so a merged issue whose trail passes is DONE. Field evidence: narrative-based holds flagged spec-compliant behaviour and put 5 of 6 merged issues in a stress batch on needs-human. Surface it in the operator status update (`PHASE BYPASS: #{NUMBER} — missing: ...`) and do not cascade it as a satisfied predecessor.
 
-   **Do NOT re-dispatch a merged issue** (forge#3148): `/work-on` Phase 0B stops on a closed or `workflow:merged` issue before its resume preflight, so a fresh agent exits without repairing anything and the predecessor would stay unresolved forever. The PR is already merged, so the gap can only be resolved by a human. Escalate it instead, which classifies it **GATED** (`classify_predecessor_state` holds `workflow:merged` + `needs-human` unless the trail re-verifies clean; the label is written first, then the comment), so item 6.5 tracks its dependents as `blocked-on-human-merge` instead of dispatching them. A merged issue whose trail could not be read (`TRAIL_RC -ge 2`, handled above) is escalated by the same block, so it is gated the same way. A bypass reported by the agent on a `workflow:merged` issue whose trail verifies is handled the same way (set `TRAIL_RC=1` before this block):
+   **Do NOT re-dispatch a merged issue** (forge#3148): `/work-on` Phase 0B stops on a closed or `workflow:merged` issue before its resume preflight, so a fresh agent exits without repairing anything and the predecessor would stay unresolved forever. The PR is already merged, so the gap can only be resolved by a human. Escalate it instead, which classifies it **GATED** (`classify_predecessor_state` holds `workflow:merged` + `needs-human` with no recorded release, regardless of the verifier; the comment is posted first, then the label, both verified), so item 6.5 tracks its dependents as `blocked-on-human-merge` instead of dispatching them. A merged issue whose trail could not be read (`TRAIL_RC -ge 2`, handled above) is escalated by the same block, so it is gated the same way. A bypass reported by the agent on a `workflow:merged` issue whose trail verifies is handled the same way (set `TRAIL_RC=1` before this block):
    ```bash
    # Only a merged issue is escalated here; an unmerged bypass is resumed by item 2 (see below).
    # Any non-zero rc on a merged issue escalates: rc 1 (missing phases) and rc >= 2 (unverifiable trail) alike,
-   # because classify_predecessor_state() gates a merged predecessor only when this escalation comment exists.
+   # because classify_predecessor_state() gates a merged predecessor on the escalation record plus the needs-human label.
    # forge#3156: also escalate when the label read itself failed: an unreadable issue cannot be proven unmerged, so
    # fail closed instead of posting nothing. forge#3168: key on TRAIL_LABELS_READ_OK, not an empty TRAIL_LABELS, so a
    # successfully read, label-less, non-merged issue is never escalated (read OK + empty labels => no escalation).
@@ -1893,10 +1926,11 @@ done
      if [ "${DRY_RUN:-false}" = "true" ]; then
        echo "[DRY-RUN] Would add needs-human and post FORGE:PHASE_TRAIL_FAILED on merged #{NUMBER}"
      else
-       # hold_merged_trail (defined with classify_predecessor_state) writes `needs-human` FIRST, read-back verified
-       # with retries, then the escalation comment (verified, retried). The label alone holds dependents, so there
-       # is no window where a comment without the label reads as DONE. A failed verification is reported on stderr.
-       hold_merged_trail {NUMBER} "${TRAIL}" || echo "PHASE TRAIL ESCALATION FAILED: #{NUMBER} — needs-human not verified." >&2
+       # hold_merged_trail (defined with classify_predecessor_state) posts the escalation comment FIRST (re-read before
+       # posting, verified), then writes `needs-human` (read-back verified, retried). A merged + needs-human issue with no
+       # comment classifies GATED regardless of the verifier. A failed half is reported on stderr and the operator must
+       # hold dependents manually (residual: a human clearing the label after both comment attempts failed).
+       hold_merged_trail {NUMBER} "${TRAIL}" || echo "PHASE TRAIL ESCALATION FAILED: #{NUMBER} — comment or needs-human not verified." >&2
      fi
    fi
    ```

package/commands/orchestrate/phase-5-cleanup.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/orchestrate/phase-6-report.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 
 install: core
 ---

package/commands/orchestrate/safety.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/pipeline-health/config.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/pipeline-health/phase-1-context.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/pipeline-health/phase-2-metrics.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/pipeline-health/phase-3-analyze.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/pipeline-health/phase-4-proposals.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/pipeline-health/phase-5-report.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/pipeline-health/phase-6-summary.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/recover-orphans.md

@@ -317,7 +317,9 @@ done
 
 For each diagnosed issue, apply the recovery action. All mutating actions are skipped when `DRY_RUN=true`.
 
-**Claim before re-entering the pipeline** (forge#3158): the `review-pr` first-refusal resume and `create-pr` re-enter `/work-on` inline. A repeated or concurrent sweep, or a live `/orchestrate` agent, could otherwise run the pipeline twice on one issue. Every inline `/work-on` resume MUST go through `claim_orphan` first and call `release_orphan` afterwards. A sweep is not an orchestrator, so it takes an issue-scoped `FORGE:RECOVERY_CLAIM` marker (visible to other sweeps) and defers to any live orchestrator signal (a fresh `FORGE:HEARTBEAT`, which `/work-on --under-orchestration` posts at every phase entry).
+**Claim before re-entering the pipeline** (forge#3158): the `review-pr` first-refusal resume and `create-pr` re-enter `/work-on` inline. A repeated or concurrent sweep, or a live `/orchestrate` agent, could otherwise run the pipeline twice on one issue. Every inline `/work-on` resume MUST go through `claim_orphan` first and run inside `resume_orphan_inline`, which releases the claim on every exit. A sweep is not an orchestrator, so it takes an issue-scoped `FORGE:RECOVERY_CLAIM` marker (visible to other sweeps) and defers to any live orchestrator signal (a fresh `FORGE:HEARTBEAT`, which `/work-on --under-orchestration` posts at every phase entry).
+
+**Claim refresh and guaranteed release** (forge#3171): liveness is judged from the claim comment's `updated_at`, and an inline resume posts no `FORGE:HEARTBEAT` (that is gated on `--under-orchestration`, which sweeps do not pass). So the claim is kept alive by editing it: `claim_orphan` records the claim comment id, and `start_claim_keepalive` runs `refresh_orphan` in a background loop every `RECOVERY_CLAIM_TTL_MIN / 3` minutes while the resume runs. `refresh_orphan` PATCHes the claim body, keeping the `**Sweep: id**` line and appending a changing `Refreshed: <UTC>` line, so `updated_at` always advances. Refresh is best-effort; if the keepalive is lost the claim degrades to the plain TTL behavior. `resume_orphan_inline` registers `trap ... release_orphan ... EXIT` in a subshell, so the claim is released always, on success and when the `Skill(...)` call fails, and `release_orphan` stops the keepalive first and is idempotent (it never posts the release marker twice). The keepalive and the `Skill(...)` call belong to the same sweep run. DRY_RUN makes every one of these helpers a no-op.
 
 ```bash
 RECOVERY_CLAIM_TTL_MIN="${RECOVERY_CLAIM_TTL_MIN:-30}"   # a claim or heartbeat older than this is treated as dead
@@ -328,7 +330,7 @@ SWEEP_ID="sweep-$(date -u +%Y%m%dT%H%M%SZ)-$$"
 # Both reads run under pipefail in a subshell: the pipeline status would otherwise be jq's, and a gh failure
 # (rate limit, 403) would yield "[]" with exit 0, indistinguishable from "no live holder".
 claim_orphan() {
-  local num="$1" now cutoff comments live
+  local num="$1" now cutoff comments live resp
   [ "$DRY_RUN" = "true" ] && return 0   # dry-run: no claim comment is posted (callers already skip dry-run resumes)
   now=$(date -u +%s); cutoff=$(( now - RECOVERY_CLAIM_TTL_MIN * 60 ))
   comments=$(set -o pipefail; gh api --paginate "repos/${GH_REPO}/issues/${num}/comments" 2>/dev/null \
@@ -349,10 +351,13 @@ claim_orphan() {
     return 1
   fi
 
-  gh issue comment "$num" ${GH_FLAG} --body "<!-- FORGE:RECOVERY_CLAIM -->
+  # Post via the API so the comment id is known: refresh_orphan needs it. The Sweep line must stay line 2.
+  CLAIM_BODY="<!-- FORGE:RECOVERY_CLAIM -->
 **Sweep: ${SWEEP_ID}**
-Holder: /recover-orphans — resuming /work-on #${num}. Other sweeps and dispatchers: do not re-enter this issue until the matching release marker is posted." >/dev/null 2>&1 \
-    || { CLAIM_SKIP_REASON="could not post FORGE:RECOVERY_CLAIM"; return 1; }
+Holder: /recover-orphans — resuming /work-on #${num}. Other sweeps and dispatchers: do not re-enter this issue until the matching release marker is posted."
+  resp=$(gh api -X POST "repos/${GH_REPO}/issues/${num}/comments" -f body="$CLAIM_BODY" --jq '.id' 2>/dev/null) \
+    && [ -n "$resp" ] || { CLAIM_SKIP_REASON="could not post FORGE:RECOVERY_CLAIM"; return 1; }
+  CLAIM_COMMENT_ID="$resp"; CLAIM_HELD_NUM="$num"   # set before the race check so release_orphan covers the race-lost paths
 
   # Race check: re-read; the earliest unreleased claim wins. Losing means another sweep claimed first.
   local first
@@ -371,12 +376,56 @@ Holder: /recover-orphans — resuming /work-on #${num}. Other sweeps and dispatc
   return 0
 }
 
+# refresh_orphan <issue> — best-effort: edit the claim comment so its updated_at advances. The body must change
+# every time (an identical-body edit may not bump updated_at). Never carries FORGE:HEARTBEAT or the RELEASED marker.
+refresh_orphan() {
+  [ "$DRY_RUN" = "true" ] && return 0
+  [ -n "${CLAIM_COMMENT_ID:-}" ] && [ "${CLAIM_HELD_NUM:-}" = "$1" ] || return 0
+  gh api -X PATCH "repos/${GH_REPO}/issues/comments/${CLAIM_COMMENT_ID}" \
+    -f body="${CLAIM_BODY}
+Refreshed: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >/dev/null 2>&1 || true
+}
+
+# start_claim_keepalive <issue> — non-blocking background refresh every TTL/3 (strictly under the TTL).
+start_claim_keepalive() {
+  [ "$DRY_RUN" = "true" ] && return 0
+  stop_claim_keepalive
+  local num="$1" interval=$(( RECOVERY_CLAIM_TTL_MIN * 60 / 3 ))
+  [ "$interval" -ge 1 ] || interval=1
+  ( while sleep "$interval"; do refresh_orphan "$num"; done ) >/dev/null 2>&1 &
+  KEEPALIVE_PID=$!
+}
+
+stop_claim_keepalive() {
+  [ -n "${KEEPALIVE_PID:-}" ] || return 0
+  pkill -P "$KEEPALIVE_PID" 2>/dev/null || true   # the pending sleep
+  kill "$KEEPALIVE_PID" 2>/dev/null || true
+  wait "$KEEPALIVE_PID" 2>/dev/null || true
+  unset KEEPALIVE_PID
+}
+
+# release_orphan <issue> — stops the keepalive first; idempotent (the release marker is posted at most once per claim).
 release_orphan() {
   [ "$DRY_RUN" = "true" ] && return 0
+  stop_claim_keepalive
+  [ "${CLAIM_HELD_NUM:-}" = "$1" ] || return 0
+  unset CLAIM_HELD_NUM CLAIM_COMMENT_ID
   gh issue comment "$1" ${GH_FLAG} --body "<!-- FORGE:RECOVERY_CLAIM_RELEASED -->
 **Sweep: ${SWEEP_ID}**
 Released by /recover-orphans." >/dev/null 2>&1 || true
 }
+
+# resume_orphan_inline <issue> — run after claim_orphan succeeded. The subshell EXIT trap releases the claim always:
+# on success and when the Skill call fails. The keepalive runs alongside the Skill call and is stopped by the release.
+resume_orphan_inline() {
+  local num="$1"
+  (
+    trap 'release_orphan "$num"' EXIT
+    start_claim_keepalive "$num"
+    refresh_orphan "$num"
+    Skill(skill="{FORGE_SKILL_PREFIX}work-on", args="${num}")
+  )
+}
 ```
 
 ```bash
@@ -510,8 +559,7 @@ See the latest FORGE:PHASE_TRAIL_FAILED comment for the missing phases. Re-run e
             # First refusal: resume /work-on, whose resume preflight re-runs each missing phase via Skill(...)
             # and then re-enters review (work-on.md Phase 0B resume → work-on/review.md).
             if claim_orphan "$NUM"; then
-              Skill(skill="{FORGE_SKILL_PREFIX}work-on", args="${NUM}")
-              release_orphan "$NUM"
+              resume_orphan_inline "$NUM"   # releases the claim on every exit
               RECOVERY_RESULTS="${RECOVERY_RESULTS}| #${NUM} | review-pr | PR #${PR_NUM} refused (phase trail) — resumed /work-on to re-run missing phases |\n"
             else
               RECOVERY_RESULTS="${RECOVERY_RESULTS}| #${NUM} | review-pr | PR #${PR_NUM} refused (phase trail) — /work-on resume skipped: ${CLAIM_SKIP_REASON} |\n"
@@ -545,8 +593,7 @@ See the latest FORGE:PHASE_TRAIL_FAILED comment for the missing phases. Re-run e
         echo "  [DRY-RUN] Would: Skill(skill='{FORGE_SKILL_PREFIX}work-on', args='$NUM')"
         RECOVERY_RESULTS="${RECOVERY_RESULTS}| #${NUM} | create-pr | Would resume /work-on — branch $BRANCH has commits, no PR |\n"
       elif claim_orphan "$NUM"; then
-        Skill(skill="{FORGE_SKILL_PREFIX}work-on", args="${NUM}")
-        release_orphan "$NUM"
+        resume_orphan_inline "$NUM"   # releases the claim on every exit
         RECOVERY_RESULTS="${RECOVERY_RESULTS}| #${NUM} | create-pr | Resumed /work-on — branch $BRANCH has commits, no PR |\n"
       else
         RECOVERY_RESULTS="${RECOVERY_RESULTS}| #${NUM} | create-pr | /work-on resume skipped: ${CLAIM_SKIP_REASON} |\n"

package/commands/review-pr-agents/api.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/review-pr-agents/auth.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/review-pr-agents/billing.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/review-pr-agents/concurrency.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/review-pr-agents/database.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/review-pr-agents/frontend.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/review-pr-agents/infra.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/review-pr-agents/protocols.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/review-pr-agents/scraper.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/review-pr-agents/security.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/review-pr-agents/spec-cli.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/review-pr-agents.md

@@ -1,3 +1,7 @@
+---
+description: Review agent catalog (read by /review-pr; not a user entrypoint)
+user-invocable: false
+---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 

package/commands/review-pr-staging.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 description: Staging review mode — comprehensive review of staging branch before deploy to main
 argument-hint: "[PR number or \"staging\"]"
 allowed-tools: Task, Agent, Bash, Read, Grep, Glob, WebFetch

package/commands/review-pr.md

@@ -1751,7 +1751,9 @@ Run the deterministic dedup script first, then fall through to the line-range ch
 # Step 0: Deterministic title dedup — catches near-duplicates before line-range check
 # See scripts/issue-dedup.sh for the token-overlap algorithm. <!-- Added: forge#1335 -->
 FINDING_TITLE_DEDUP="fix: brief description of finding (review finding — PR #${PR_NUMBER})"
-DEDUP_RESULT=$(scripts/issue-dedup.sh "$FINDING_TITLE_DEDUP" "$GH_FLAG" 2>&1)
+# Never dedup against the issue this PR fixes (MERGE_ISSUE): it is about to be closed, so a
+# finding "matched" to it is tracked nowhere. Field test #3169: SEC-2 matched #3169 itself and was dropped.
+DEDUP_RESULT=$(scripts/issue-dedup.sh "$FINDING_TITLE_DEDUP" "$GH_FLAG" ${MERGE_ISSUE:+--exclude "$MERGE_ISSUE"} 2>&1)
 DEDUP_EXIT=$?
 if [ "$DEDUP_EXIT" -eq 1 ]; then
   echo "DEDUP: Skipping — $DEDUP_RESULT"
@@ -1775,7 +1777,7 @@ LINE_MAX=$((FINDING_LINE + 5))
 
 # Check open issues for line-range overlap OR title similarity on the same file
 CANDIDATES=$(gh issue list --state open --label "review-finding" --limit 100 --json number,title,body \
-  --jq "[.[] | select(.body | test(\"${FINDING_FILE}\"))]" 2>/dev/null)
+  --jq "[.[] | select(.number != ${MERGE_ISSUE:-0}) | select(.body | test(\"${FINDING_FILE}\"))]" 2>/dev/null)
 
 EXISTING=$(echo "$CANDIDATES" | jq -r --arg file "$FINDING_FILE" --argjson min "$LINE_MIN" --argjson max "$LINE_MAX" --arg title "$FINDING_TITLE" '
   .[] |
@@ -1926,7 +1928,7 @@ if [ "$FINDING_PRIORITY_EXIT" -ne 0 ]; then
 else
 
 # --label is repeatable (not comma-joined) per the /issue programmatic contract.
-ISSUE_SKILL_OUTPUT=$(Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"$FINDING_ISSUE_TITLE\" --body-file \"$FINDING_ISSUE_BODY_FILE\" --label review-finding --label needs-validation --label \"$FINDING_PRIORITY\" ${MILESTONE_FLAG}"))
+ISSUE_SKILL_OUTPUT=$(Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"$FINDING_ISSUE_TITLE\" --body-file \"$FINDING_ISSUE_BODY_FILE\" --label review-finding --label needs-validation --label \"$FINDING_PRIORITY\" ${MILESTONE_FLAG} ${MERGE_ISSUE:+--exclude \"$MERGE_ISSUE\"}"))
 # /issue re-reads the created issue and hard-fails unless this exact marker is present.
 rm -f "$FINDING_ISSUE_BODY_FILE"
 

package/commands/work-on/build/architect.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 description: Pre-implementation architecture planning — traces ALL affected code paths and produces an ordered implementation plan before any code is written
 argument-hint: "{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --repo-path {WORKTREE} --files \"<space-separated>\""
 context: fork

package/commands/work-on/build/context.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 description: Pre-implementation context gathering — surfaces historical findings, bug patterns, and related code paths before the builder writes any code
 argument-hint: "{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --repo-path {WORKTREE} --files \"<space-separated>\" [--functions \"<names>\"]"
 context: fork

package/commands/work-on/build/implement.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 description: Implementation agent — writes code, makes commits, posts builder comment
 argument-hint: "{NUMBER} --repo {GH_REPO} --gh-flag \"{GH_FLAG}\" --worktree {WORKTREE} --branch {BRANCH} --base {PR_BASE} [--fix-acceptance \"<failed checks>\"]"
 context: fork

package/commands/work-on/build/validate.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 description: Validation agent — quality gate loop, format/verify, proxy check, deploy check
 argument-hint: "{NUMBER} --repo {GH_REPO} --gh-flag \"{GH_FLAG}\" --worktree {WORKTREE} --branch {BRANCH} --base {PR_BASE} --files \"<changed files>\""
 context: fork

package/commands/work-on/build.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 description: Build subcommand — create worktree, post contract, sequence context/architect/implement/validate
 context: fork
 argument-hint: "{NUMBER} --repo {GH_REPO} --gh-flag \"{GH_FLAG}\" --base {PR_BASE}"
@@ -12,6 +13,9 @@ argument-hint: "{NUMBER} --repo {GH_REPO} --gh-flag \"{GH_FLAG}\" --base {PR_BAS
 
 **Input**: $ARGUMENTS
 
+> **Transient GitHub failures** (field test: a 12-minute GitHub HTTP 500 window parked an issue at needs-human): retry any `gh` call that fails with HTTP 5xx, a timeout or "Something went wrong" up to 3 times with 10s/30s/60s backoff. If it still fails, do NOT add `needs-human` — print this phase's RESULT block with `status: BLOCKED` and a blocker that starts with `github-unavailable:`. The router retries the phase; every phase resumes from GitHub state, so a retry is safe.
+
+
 **Invoked by**: the work-on router, when the issue carries label `workflow:ready-to-build` or `workflow:building`. This skill runs in an isolated forked context: it sees only its args and re-reads everything else from GitHub and git.
 **Output**: Create worktree, classify complexity, post contract, run the child phases (context, architect, implement, validate) through `Skill()`, run the acceptance gate, and print exactly one `BUILD_RESULT:` block as the final reply.
 

package/commands/work-on/close.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 description: Close subcommand — update project board, final issue body, parent tracker, summary report, trajectory log
 argument-hint: "[issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--pr PR_NUMBER] [--base PR_BASE] [--branch BRANCH] [--worktree WORKTREE_PATH] --terminal-state merged|investigation|decomposed|invalid"
 context: fork
@@ -12,6 +13,9 @@ context: fork
 
 **Input**: $ARGUMENTS
 
+> **Transient GitHub failures** (field test: a 12-minute GitHub HTTP 500 window parked an issue at needs-human): retry any `gh` call that fails with HTTP 5xx, a timeout or "Something went wrong" up to 3 times with 10s/30s/60s backoff. If it still fails, do NOT add `needs-human` — print this phase's RESULT block with `status: BLOCKED` and a blocker that starts with `github-unavailable:`. The router retries the phase; every phase resumes from GitHub state, so a retry is safe.
+
+
 **Invoked by**: the `work-on` router, as its final step, via `Skill(skill="{FORGE_SKILL_PREFIX}work-on:close", args="...")`. This file declares `context: fork`, so it runs in an isolated sub-agent context that sees ONLY this text and its args — there is no "Phase 0 state" to rely on. Everything not passed as an arg is re-derived from GitHub/git in Phase C0. The router sees ONLY the final `CLOSE_RESULT:` block (see Output), so this file is the single source of truth for the close report, the summary card, the trajectory comment and the decision record.
 **Output**: Update project board, close issue, update parent tracker, post trajectory log, post decision record, clean up the worktree. Final reply is the `CLOSE_RESULT:` block.
 

package/commands/work-on/decompose.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 description: Decompose subcommand — break a complex issue into ordered sub-issues, post FORGE:DECOMPOSED, stop
 context: fork
 argument-hint: "{NUMBER} --repo {GH_REPO} --gh-flag \"{GH_FLAG}\""
@@ -12,6 +13,9 @@ argument-hint: "{NUMBER} --repo {GH_REPO} --gh-flag \"{GH_FLAG}\""
 
 **Input**: $ARGUMENTS
 
+> **Transient GitHub failures** (field test: a 12-minute GitHub HTTP 500 window parked an issue at needs-human): retry any `gh` call that fails with HTTP 5xx, a timeout or "Something went wrong" up to 3 times with 10s/30s/60s backoff. If it still fails, do NOT add `needs-human` — print this phase's RESULT block with `status: BLOCKED` and a blocker that starts with `github-unavailable:`. The router retries the phase; every phase resumes from GitHub state, so a retry is safe.
+
+
 **Invoked by**: the work-on router, when `INVESTIGATE_RESULT.decompose = YES`. This skill runs in an isolated forked context: it sees only its args and re-reads everything else from GitHub.
 **Output**: Create sub-issues, update parent tracker, post `<!-- FORGE:DECOMPOSED -->` comment, set `workflow:decomposed`. STOP — each sub-issue runs its own /work-on. This skill is the SOLE owner of the `workflow:decomposed` label. On BLOCKED it adds `needs-human` and posts the blocker.
 

package/commands/work-on/investigate.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 description: Investigate a GitHub issue — validate it's real, determine root cause, post findings
 argument-hint: "{NUMBER} --repo {GH_REPO} --gh-flag \"{GH_FLAG}\""
 context: fork
@@ -10,6 +11,9 @@ context: fork
 
 **Input**: $ARGUMENTS
 
+> **Transient GitHub failures** (field test: a 12-minute GitHub HTTP 500 window parked an issue at needs-human): retry any `gh` call that fails with HTTP 5xx, a timeout or "Something went wrong" up to 3 times with 10s/30s/60s backoff. If it still fails, do NOT add `needs-human` — print this phase's RESULT block with `status: BLOCKED` and a blocker that starts with `github-unavailable:`. The router retries the phase; every phase resumes from GitHub state, so a retry is safe.
+
+
 Standalone investigation phase for the work-on pipeline. Validates whether an issue is real, determines root cause, posts a structured FORGE:INVESTIGATOR comment to GitHub, and updates workflow labels.
 
 This skill runs in an **isolated forked context**: it sees only this file and its args. It has no variables from the caller — every other piece of state is re-read from GitHub/git here. It ends by printing exactly one `INVESTIGATE_RESULT:` block (see `## Output`) as its final reply, on **every** exit path (success, ALREADY_DONE, INVALID, BLOCKED).

package/commands/work-on/remediate.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 description: Remediate subcommand — checkout a needs-human PR, fix review findings, re-review, and re-gate with a FORGE:REMEDIATION paper trail
 argument-hint: "[PR number] [--issue N] [--repo GH_REPO] [--gh-flag GH_FLAG] [--base PR_BASE]"
 context: fork
@@ -12,6 +13,9 @@ context: fork
 
 **Input**: $ARGUMENTS
 
+> **Transient GitHub failures** (field test: a 12-minute GitHub HTTP 500 window parked an issue at needs-human): retry any `gh` call that fails with HTTP 5xx, a timeout or "Something went wrong" up to 3 times with 10s/30s/60s backoff. If it still fails, do NOT add `needs-human` — print this phase's RESULT block with `status: BLOCKED` and a blocker that starts with `github-unavailable:`. The router retries the phase; every phase resumes from GitHub state, so a retry is safe.
+
+
 **Invoked by**:
 - `work-on.md` Phase 0A.1 (router), standalone: `/work-on <pr> --remediate` (see forge#1813).
 - `commands/orchestrate/phase-4-execution.md` item 6.4, auto-dispatched against a `needs-human`-gated predecessor's own open PR.

package/commands/work-on/review.md

@@ -1,4 +1,5 @@
 ---
+user-invocable: false
 description: Review subcommand — push branch, create PR, invoke /review-pr with --auto-merge
 context: fork
 argument-hint: "{NUMBER} --repo {GH_REPO} --gh-flag \"{GH_FLAG}\" --worktree {WORKTREE} --branch {BRANCH} --base {PR_BASE}"
@@ -12,6 +13,9 @@ argument-hint: "{NUMBER} --repo {GH_REPO} --gh-flag \"{GH_FLAG}\" --worktree {WO
 
 **Input**: $ARGUMENTS
 
+> **Transient GitHub failures** (field test: a 12-minute GitHub HTTP 500 window parked an issue at needs-human): retry any `gh` call that fails with HTTP 5xx, a timeout or "Something went wrong" up to 3 times with 10s/30s/60s backoff. If it still fails, do NOT add `needs-human` — print this phase's RESULT block with `status: BLOCKED` and a blocker that starts with `github-unavailable:`. The router retries the phase; every phase resumes from GitHub state, so a retry is safe.
+
+
 **Invoked by**: the `work-on` router, after `build/validate.md` returns `GATE_PASSED: true`.
 **Output**: Push branch, create PR, invoke /review-pr --auto-merge, verify the merge, and print exactly one `REVIEW_RESULT:` block as the final reply (all paths, including every guard/failure).
 

package/commands/work-on.md

@@ -507,6 +507,12 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:HEARTBEAT -->
 
 ---
 
+## Transient GitHub failures (router-owned retry)
+
+Any phase result whose blocker starts with `github-unavailable:` is an infrastructure outage, not a decision: do not add `needs-human`. Wait 2 minutes, then re-invoke the **same phase with the same args**; repeat at most twice (5 minutes before the second retry). Phases are idempotent and resume from GitHub state. If the third attempt still returns `github-unavailable:`, post one comment with the blocker, add `needs-human`, and STOP — at that point GitHub has been unavailable for 10+ minutes.
+
+---
+
 ## Phase 1: Investigate
 
 **Skip if**: a `<!-- FORGE:INVESTIGATOR -->` comment contains `<!-- INVESTIGATION:COMPLETE -->` or `<!-- INVESTIGATION:INVALID -->` (route on the existing verdict as below — the skill's own resume check returns it if invoked).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.8.2",
+  "version": "1.8.4",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"

package/scripts/check-spec-markers.sh

@@ -284,6 +284,16 @@ if [ -d "$WORKFLOWS_DIR" ]; then
   done < <(find "$WORKFLOWS_DIR" -name '*.yml' | sort)
 fi
 
+# ---------------------------------------------------------------------------
+# Merged-trail hold must not be keyed on the verifier (forge#3169)
+# ---------------------------------------------------------------------------
+
+P4_SPEC="$COMMANDS_DIR/orchestrate/phase-4-execution.md"
+if [ -f "$P4_SPEC" ] && grep -qE 'ABSENT\) +\[ "\$\(reverify_merged_trail "\$PRED"[^)]*\)" = "OK" \] *&& *echo "DONE"' "$P4_SPEC"; then
+  echo "HIGH | $P4_SPEC | merged + needs-human + ABSENT classifies DONE via the verifier (must fail closed to GATED)" >&2
+  VIOLATIONS=$((VIOLATIONS + 1))
+fi
+
 # ---------------------------------------------------------------------------
 # Summary
 # ---------------------------------------------------------------------------

package/commands/work-on-monolithic.md

@@ -1,367 +0,0 @@
----
-description: "[BENCHMARK] Monolithic work-on — single-prompt pipeline with no Skill sub-phase boundaries"
-argument-hint: "[issue number]"
-install: internal
----
-<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
-<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
-
-# /work-on-monolithic — Full Issue Pipeline (Single Prompt)
-
-> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.
-
-**Input**: $ARGUMENTS
-
-Orchestrator for the full issue lifecycle: investigate → build → review → merge → close. GitHub issues are the persistent context layer — read existing comments before starting, write structured reports back, use `workflow:*` labels to track state.
-
-**Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "sonnet" (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
-**NEVER use plan mode (EnterPlanMode).**
-
-> **Relationship to `/work-on` (canonical path)**: This file is a `[BENCHMARK]` reference variant. It documents the same inline-execution model that `/work-on` Phase 3 and `work-on/build.md` use as their **default** for STANDARD/fast-lane issues — all build sub-phases (context → architect → implement → validate) run inline in the current context window with no `Skill()` sub-agent spawns. The difference is that this file omits the worktree lifecycle, `FORGE:CONTRACT` posting, and the Spawn-Decision exception path for large builds. Use `/work-on` for production runs; use this file for baseline benchmarking or when comparing single-prompt token cost against the modular path. See `work-on/build.md` (Canonical Build Path section) for the reconciled build topology. <!-- Added: forge#1276 -->
-**NEVER use the Agent tool** — this spec executes all phases inline as a single monolithic prompt. The Agent tool would spawn a subprocess outside this context, breaking the single-prompt contract and losing all accumulated pipeline state.
-
-<!-- FORGE:SPEC_LOADED — work-on-monolithic.md loaded and active. Agent is bound by this spec. -->
-
-### Compaction Resilience
-
-1. Write state to GitHub after EVERY significant step
-2. Re-read GitHub state at the START of each phase (don't rely on in-memory context)
-3. After compaction: re-read issue (body + comments + labels) to reconstruct state
-4. Key principle: A NEW session running this command should pick up where the last left off by reading GitHub state alone
-
----
-
-## Pipeline Rules
-
-- **NEVER merge to main.** PRs target `staging` (fast lane) or `milestone/{slug}` (feature lane).
-- **`Closes #N` does not auto-close for non-default-branch PRs.** You MUST explicitly `gh issue close`.
-- **Review findings are NOT merge blockers.** They become separate issues.
-
----
-
-## Project Configuration
-
-Read `forge.yaml` from the repository root. If missing, tell the user to run `npx forgedock init` and stop.
-
-Resolve the following variables from `forge.yaml` before running any pipeline phase:
-
-| Variable | Source in forge.yaml | Description |
-|----------|----------------------|-------------|
-| `GH_REPO` | `project.owner` + `project.repo` | Full GitHub repo identifier (`owner/repo`) |
-| `REPO_PATH` | `paths.root` | Absolute path to the local repository |
-| `STAGING_BRANCH` | `branches.staging` | Branch for fast-lane PRs (no milestone) |
-| `WORKTREE_BASE` | `paths.worktree_base` | Directory where git worktrees are created |
-| `GH_FLAG` | _(empty for default repo; `-R owner/repo` for satellites)_ | Extra flag for `gh` CLI satellite repo calls |
-
-**Multi-repo routing** (optional): If `forge.yaml` contains a `repos.satellites` list, build the prefix routing table from it. Each satellite entry has `prefix`, `repo`, `staging_branch`, and `local_path`. Issues without a prefix route to the default `GH_REPO`. Satellite repos have no staging — their fast-lane PRs go to their configured `staging_branch` (typically `main`).
-
-If no `repos.satellites` section exists, only the primary repo is available — all issues route to `GH_REPO`.
-
----
-
-## Phase 0: Resolve Issue & Load Context
-
-### 0A: Parse input
-Extract project prefix and issue number.
-
-### 0B: Load issue + existing context
-```bash
-gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,comments,milestone
-gh api repos/{GH_REPO}/issues/{NUMBER}/comments --jq '.[] | {id: .id, author: .user.login, body: .body}'
-```
-
-**Check**: state (closed → STOP), terminal labels (`workflow:merged`/`workflow:invalid` → STOP), existing agent comments (`FORGE:INVESTIGATOR`, `FORGE:CONTRACT`, `FORGE:BUILDER`, `FORGE:TRAJECTORY`), parent tracker status.
-
-**Determine resume point**: No comments → Phase 1. Investigation exists + ready-to-build → Phase 3. Builder:COMPLETE + no PR → Phase 4. Builder without :COMPLETE (partial/interrupted build) + no PR → Phase 3 (partial-build cleanup). Builder + PR open → Phase 5. PR merged + issue open → close issue.
-
-**Classify lane**: Milestone → feature lane (`milestone/{slug}`). No milestone → fast lane (`staging`).
-
-**Source branch for review-findings**: Parse `**Code branch**: \`{branch}\`` from body. Branch from there, not main.
-
-### 0C: Sync to Project board
-Add issue to project, set Status=In Progress, Lane, Component, Priority, Workflow=Investigating.
-
----
-
-## Phase 1: Investigation
-
-**Skip if**: `<!-- FORGE:INVESTIGATOR -->` exists with `<!-- INVESTIGATION:COMPLETE -->`.
-
-### 1A: Set label
-```bash
-gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:investigating"
-gh issue edit {NUMBER} {GH_FLAG} --remove-label "workflow:ready-to-build,workflow:building,workflow:in-review" 2>/dev/null || true
-```
-
-### 1B: Investigate the issue
-
-Mission: Validate whether the issue is real. Assume description is wrong until proven otherwise.
-
-**Domain file hints** (start search here):
-
-Configure domain-to-file mappings for your project in `forge.yaml → review.key_paths`. The table below shows the standard layout — override any entry that doesn't match your codebase:
-
-| Domain | Default key files (override via forge.yaml) |
-|--------|---------------------------------------------|
-| BILLING | `routers/billing.py`, `core/pricing.py`, `services/payment_service.py` |
-| WORKER | `worker/main.py`, `worker/queues.py`, `worker/tasks.py` |
-| AUTH | `core/auth.py`, `routers/auth.py`, `dependencies.py` |
-| DATABASE | `infra/migrations/`, `models/`, `db/` |
-| FRONTEND | `web/src/app/`, `web/src/components/`, `web/src/lib/` |
-| AI | `services/ai_client.py`, `routers/ai.py` |
-| INFRA | `.github/workflows/`, `docker-compose.yml`, `infra/traefik/` |
-
-If `forge.yaml → review.key_paths` is present, use those mappings instead of the defaults above.
-
-**Steps**: Check right branch → read domain files → verify claims → git blame → determine root cause → identify affected files → validate proposed fixes against full system stack.
-
-**Fix-Approach Validation**: If issue proposes a fix, don't adopt it as spec. Trace through target system's middleware, auth, routing.
-
-**Domain Context Discovery** (narrow scope, max 5 files):
-```bash
-git log --oneline --all -30 -- {affected_files} | grep -oP '#\d+' | sort -u
-```
-
-**Output format**: Verdict (CONFIRMED/PARTIAL/INVALID), Confidence, Severity, Task Type, What Was Claimed, What We Found, Root Cause, Affected Files, Evidence, Recommendation.
-
-### 1C: Post investigation comment
-```bash
-gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:INVESTIGATOR -->
-<!-- INVESTIGATION:COMPLETE -->
-## Investigation Report
-{report}"
-```
-
-### 1D: Update labels
-CONFIRMED/PARTIAL → add `workflow:ready-to-build`, continue to Phase 3.
-INVALID → close issue, add `workflow:invalid`, STOP.
-
----
-
-## Phase 3: Build
-
-**Skip if**: `<!-- FORGE:BUILDER -->` exists.
-
-### 3A: Re-read state from GitHub (MANDATORY)
-```bash
-gh issue view {NUMBER} {GH_FLAG} --json body,labels
-gh api repos/{GH_REPO}/issues/{NUMBER}/comments --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body'
-```
-
-### 3B: Classify task type
-
-| Signal | Type | Approach |
-|--------|------|----------|
-| UI/UX, feature + web/ files | UI/UX | `frontend-design` skill |
-| Feature + services/ | Backend Feature | Implement directly |
-| Feature + both | Full-Stack | Backend first, then frontend-design |
-| Bug + web/ | Frontend Fix | Direct |
-| Bug + services/ | Backend Fix | Direct |
-| Refactor/docs | Maintenance | Direct |
-
-Then classify COMPLEXITY_BAND with the same table as `work-on/build.md` B0.5 (TRIVIAL: single doc/config file, no logic; STANDARD: 1–5 files, existing patterns; COMPLEX: 6+ files, new abstractions, cross-service, schema changes) and post the `FORGE:FAST_PATH` marker. `scripts/verify-phase-trail.sh` reads the band from it and fails the review-pr merge gate when it is absent (forge#3148):
-
-```bash
-FP_BODY="<!-- FORGE:FAST_PATH -->
-## Fast-Path Classification
-
-**COMPLEXITY_BAND**: {TRIVIAL|STANDARD|COMPLEX}
-**Task type**: {TASK_TYPE}
-**Affected file count**: {N}
-**Rationale**: {one-sentence explanation of classification decision}
-**Phases skipped**: {3C.5, 3C.6 for TRIVIAL | none — full pipeline}"
-gh issue comment {NUMBER} {GH_FLAG} --body "$FP_BODY" # <!-- allowlist:check-command-side-effects -->
-```
-
-### 3C: Builder Contract (MANDATORY)
-Post `<!-- FORGE:CONTRACT -->` comment with: task type, proposed approach, deliverables table (file/change/why), acceptance criteria, quality considerations.
-
-### 3C.5: Context Gathering (max 2 minutes — MANDATORY for STANDARD/COMPLEX, skip for TRIVIAL)
-
-Surface institutional memory before writing code. For each affected file:
-```bash
-# Recent agent work on these files
-git log --oneline --all -30 -- {affected_files} | grep -oP '#\d+' | sort -u | head -5
-# Check for review findings on same files
-for ISSUE_NUM in {related_issue_numbers}; do
-  gh api repos/{GH_REPO}/issues/${ISSUE_NUM}/comments --jq '.[] | select(.body | contains("FORGE:")) | .body' 2>/dev/null | head -20
-done
-```
-
-Post `<!-- FORGE:CONTEXT -->` comment with findings. For STANDARD/COMPLEX it is required even when no relevant history is found (say so in the comment): the merge gate checks for it.
-
-### 3C.6: Architecture Plan (MANDATORY for STANDARD/COMPLEX — skip for TRIVIAL)
-
-For multi-file changes, trace ALL affected code paths before writing code:
-- Map the call chain: entry point → middleware → handler → service → model → response
-- Identify every file that needs to change
-- Order implementation steps to avoid broken intermediate states
-
-Post `<!-- FORGE:ARCHITECT -->` comment with the implementation plan.
-
-Skip this step only when COMPLEXITY_BAND is TRIVIAL. For STANDARD/COMPLEX, the merge gate checks for the `FORGE:ARCHITECT` comment.
-
-### 3D: Set building label
-```bash
-gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:building" --remove-label "workflow:ready-to-build,workflow:investigating"
-```
-
-### 3E: Create worktree
-Branch slug from title (lowercase, hyphenated, max 40 chars). Prefix: `fix/` (bugs) or `feat/` (features).
-- Review-finding → branch from `origin/{SOURCE_BRANCH}`
-- Fast lane → branch from `origin/{STAGING_BRANCH}`
-- Feature lane → branch from `origin/milestone/{slug}`
-
-```bash
-cd {REPO_PATH}
-git fetch origin
-BRANCH="fix/{slug}-{NUMBER}"
-git worktree add {WORKTREE_BASE}/{BRANCH} -b {BRANCH} origin/{PR_BASE}
-```
-
-### 3F: Implement
-Route by task type. Read the investigation report and contract. Implement the fix/feature.
-
-### 3F.5: Quality Gate
-Invoke quality-gate on changed files:
-```
-Skill(skill="{FORGE_SKILL_PREFIX}quality-gate", args="{changed_files} --worktree {WORKTREE_PATH}")
-```
-Fix HIGH/MEDIUM findings. Max 2 iterations. Skip for 1-file config/docs edits.
-
-Then post the `FORGE:QUALITY_GATE` marker with the real gate result (same contract as `work-on/build/validate.md` V1/V5). Post it even when the gate was skipped (`**Result**: PASS (skipped — single config/docs file)`). The merge gate requires it unless the whole diff is docs-only (forge#3148):
-
-```bash
-QG_BODY="<!-- FORGE:QUALITY_GATE -->
-## Quality Gate Result
-
-**Result**: {PASS|FAIL}
-**Iterations**: {N}
-**Commands run**: {quality-gate invocation actually executed}
-**Findings remaining**: {none | summary}"
-gh issue comment {NUMBER} {GH_FLAG} --body "$QG_BODY" # <!-- allowlist:check-command-side-effects -->
-```
-
-If the gate still reports HIGH/MEDIUM findings after 2 iterations, post `**Result**: FAIL`, add `needs-human`, and STOP.
-
-### 3G: Format and verify
-- Python: `black` + `isort` + `py_compile`
-- TypeScript (primary repo): `prettier --write` + `tsc --noEmit` (BLOCKING if fails)
-- TypeScript (satellite): `npm run build` + `prettier --write`
-
-### 3H: Frontend proxy wiring check (MANDATORY)
-All client-side fetch/useSWR/apiFetch must use `/api/...` proxy routes, NEVER `/api/v1/...` directly.
-
-### 3I: Deployment completeness check (MANDATORY)
-Skip if no new env vars introduced.
-
-For each new env var, verify present in ALL required locations:
-
-| Location | Required for |
-|----------|-------------|
-| `.env.example` | All new vars |
-| Secrets backend (see `deploy.secrets_backend`) | Secret vars — skip if backend is `none` or unset |
-| `app/env_validation.py` | API service vars (if project has one) |
-
-**Secrets backend check** *(trigger: `deploy.secrets_backend == "sops"`)*:
-
-If the project uses SOPS, verify the new var is present in all SOPS chain locations:
-- `infra/secrets/prod.enc.yaml` — SOPS-encrypted secret store
-- `infra/decrypt-secrets.sh` ENV_MAPPING — maps SOPS key to env var name
-
-If `deploy.secrets_backend` is absent or not `sops`, skip these checks and log:
-> `SKIP: SOPS chain check — deploy.secrets_backend is not "sops". Configure deploy.secrets_backend in forge.yaml to enable.`
-
-### 3J: Commit
-Conventional prefix (fix/feat/refactor/docs). Reference #{NUMBER} in the commit message.
-
-### 3K: Post implementation comment
-Post `<!-- FORGE:BUILDER -->` with: branch, commit, files changed, approach, changes list, testing checklist.
-
----
-
-## Phase 4: PR Creation
-
-### 4A: Push branch
-```bash
-cd {WORKTREE_PATH} && git push -u origin {BRANCH}
-```
-If fails: try `--force-with-lease`. If still fails: post comment, add `needs-human`, STOP.
-
-### 4B: Determine PR target
-No milestone → `staging`. Has milestone → `milestone/{slug}`. NEVER `main`.
-
-### 4C: Create PR
-```bash
-gh pr create {GH_FLAG} --base {PR_BASE} --title "{Fix|Feat}: {description} (#{NUMBER})" --body "..."
-```
-Include `Closes #{NUMBER}`.
-
-### 4D: Update labels
-```bash
-gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:in-review" --remove-label "workflow:building"
-```
-
----
-
-## Phase 5: Auto-Review
-
-### 5A: Re-read state from GitHub (MANDATORY)
-### 5B: Invoke /review-pr with --auto-merge
-```
-if DRY_RUN=true:
-  record "Would invoke review-pr --auto-merge for PR #{PR_NUMBER}; skipped (dry-run)."
-else:
-  Skill(skill="{FORGE_SKILL_PREFIX}review-pr", args="{PR_NUMBER} --auto-merge --issue {NUMBER} --base {PR_BASE} --gh-flag {GH_FLAG}")
-```
-
-### 5C: Verify merge and close (recovery)
-
-**`REVIEW_RESULT: status: PHASE_TRAIL_FAILED`** (forge#3148): review-pr's Phase 8 refused the merge because a phase marker is missing. The PR is intentionally unmerged — do NOT run the `gh pr merge` recovery below, which would merge around the gate. Re-run each phase named on the `MISSING: <marker> -> <action>` lines (never hand-post a marker), then re-run 5B once. If it returns `PHASE_TRAIL_FAILED` again, add `needs-human` and STOP; review-pr has already posted the `FORGE:PHASE_TRAIL_FAILED` comment.
-
-**`REVIEW_RESULT: status: BLOCKED` with a phase-trail or auto-merge-gate blocker** (any blocker containing "phase trail", or "auto-merge requires --issue"; forge#3147): the gate refused or could not run. Do NOT re-run phases and do NOT run the manual merge below. Add `needs-human` and STOP.
-
-Otherwise:
-- PR MERGED + issue CLOSED → proceed to Phase 6/7
-- PR MERGED + issue OPEN → close issue manually
-- PR NOT MERGED + review returned `REVIEW_RESULT: status: COMPLETE` → run `scripts/wait-ci-green.sh {PR_NUMBER} {GH_FLAG}` (resolved from the plugin root); only on exit 0 merge with `--merge --match-head-commit <the CI_GATE_HEAD it printed>` and close the issue. A non-zero gate (or a "ci gate" / "stale review" blocker) → do NOT merge; post the gate output, add `needs-human`, STOP. If the merge fails → post comment, add `needs-human`, STOP.
-- PR NOT MERGED + any other, missing, or unparseable `REVIEW_RESULT` → do NOT merge (an unrecognized refusal must never fall through to a manual merge). Add `needs-human` and STOP.
-
-### 5D: Project board update (Workflow=Merged, Status=Done)
-
-### 5E: Final issue body update
-Check off remaining items.
-
----
-
-## Phase 6: Parent Tracker Update (Sub-Issues Only)
-
-**Skip if**: Not a sub-issue.
-
-Check off this sub-issue in parent body. If ALL sub-issues closed → close parent with `workflow:merged`.
-
----
-
-## Phase 7: Summary & Trajectory
-
-### 7A: Report
-```
-## Done: #{NUMBER} — {TITLE}
-- Investigation: {verdict} ({confidence})
-- Lane: {FAST/FEATURE}
-- Fix: {branch} → PR #{PR_NUMBER} → merged to `{PR_BASE}`
-- Files changed: {count}
-```
-
-### 7B: Trajectory Log (MANDATORY)
-Post `<!-- FORGE:TRAJECTORY -->` comment with phase-by-phase results table, decisions, anomalies.
-
----
-
-## Error Handling
-
-- Worktree exists: reuse or clean up
-- PR creation fails: check if branch pushed, if PR already exists
-- Merge conflicts: report to user, do NOT auto-resolve
-- gh CLI fails: check `gh auth status`
-- Label missing: create it