forgedock 1.8.1 → 1.8.3

package/commands/recover-orphans.md

@@ -7,13 +7,15 @@ argument-hint: "[--dry-run | --since <hours> | --issue <number>]"
 
 # /recover-orphans — Pipeline Orphan Recovery
 
+> **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
 
 Scan ALL open issues with intermediate workflow labels for orphaned state — issues where the agent died mid-pipeline (context expired, rate-limited, crashed) and no active agent is continuing. Diagnose each orphan's actual GitHub state and apply the appropriate recovery action.
 
 **Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "sonnet". Fallback: `model: "opus"` if rate-limited.
 **NEVER use plan mode (EnterPlanMode).**
-**NEVER use the Agent tool** — recover-orphans re-enters the pipeline via `Skill(skill="work-on", ...)` and `Skill(skill="review-pr", ...)` only.
+**NEVER use the Agent tool** — recover-orphans re-enters the pipeline via `Skill(skill="{FORGE_SKILL_PREFIX}work-on", ...)` and `Skill(skill="{FORGE_SKILL_PREFIX}review-pr", ...)` only.
 
 <!-- FORGE:SPEC_LOADED — recover-orphans.md loaded and active. Agent is bound by this spec. -->
 
@@ -171,7 +173,6 @@ for NUM in $ORPHAN_LIST; do
     DIAG_REASON[$NUM]="Already in terminal state: $ISSUE_LABELS"
     continue
   fi
-
   # Check for merged PR referencing this issue
   MERGED_PR=$(gh pr list ${GH_FLAG} \
     --state merged \
@@ -198,6 +199,15 @@ for NUM in $ORPHAN_LIST; do
     continue
   fi
 
+  # forge#3148: checked after the merged-PR label cleanup above, so a merged orphan is still closed out.
+  # An escalated orphan is waiting on a human — re-running a recovery action every sweep
+  # (e.g. re-invoking /review-pr against an unrepaired phase trail) only repeats the same refusal.
+  if echo ", $ISSUE_LABELS," | grep -q ", needs-human,"; then
+    DIAG_ACTION[$NUM]="skip"
+    DIAG_REASON[$NUM]="Escalated (needs-human) — waiting on a human"
+    continue
+  fi
+
   # Check for an open PR on any branch associated with this issue
   # Strategy: look for branches with the issue number in the name
   ISSUE_BRANCH=$(git ls-remote --heads origin 2>/dev/null | grep "/$NUM" | sed 's|.*refs/heads/||' | head -1)
@@ -307,6 +317,117 @@ 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 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
+SWEEP_ID="sweep-$(date -u +%Y%m%dT%H%M%SZ)-$$"
+
+# claim_orphan <issue> — returns 0 if this sweep now holds the claim, 1 if it must skip (reason in CLAIM_SKIP_REASON).
+# Fails closed: an unreadable comment list (initial read or race-check re-read) is treated as "held by someone else".
+# 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 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 \
+    | jq -s 'add // []') || { CLAIM_SKIP_REASON="could not read comments to check for a live holder"; return 1; }
+
+  # Live orchestrator signal: a recent heartbeat from /work-on --under-orchestration, or a recent claim of any sweep.
+  # A claim is "released" only by a later RELEASED marker naming its sweep id.
+  live=$(echo "$comments" | jq --argjson cutoff "$cutoff" '
+    ([.[] | select(.body | contains("FORGE:RECOVERY_CLAIM_RELEASED")) | .body | capture("Sweep: (?<id>[^ \n]+)").id]) as $rel
+    | [ .[] | select(
+          ((.body | contains("FORGE:HEARTBEAT")) or (.body | contains("<!-- FORGE:RECOVERY_CLAIM -->")))
+          and ((.body | contains("FORGE:RECOVERY_CLAIM_RELEASED")) | not)
+          and ((.updated_at | fromdateiso8601) >= $cutoff)
+          and ((.body | capture("Sweep: (?<id>[^ \n]+)")? // {id:""}).id as $sid | ($rel | index($sid)) == null)
+        ) ] | length') || live=1
+  if [ "${live:-1}" -gt 0 ]; then
+    CLAIM_SKIP_REASON="live holder (heartbeat or unreleased recovery claim within ${RECOVERY_CLAIM_TTL_MIN}m)"
+    return 1
+  fi
+
+  # 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."
+  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
+  first=$(set -o pipefail; gh api --paginate "repos/${GH_REPO}/issues/${num}/comments" 2>/dev/null | jq -rs --argjson cutoff "$cutoff" '
+    add // [] | ([.[] | select(.body | contains("FORGE:RECOVERY_CLAIM_RELEASED")) | .body | capture("Sweep: (?<id>[^ \n]+)").id]) as $rel
+    | [.[] | select(.body | contains("<!-- FORGE:RECOVERY_CLAIM -->"))
+           | select((.updated_at | fromdateiso8601) >= $cutoff)
+           | select((.body | capture("Sweep: (?<id>[^ \n]+)").id) as $sid | ($rel | index($sid)) == null)]
+    | first | .body // ""' | sed -n 's/^\*\*Sweep: \(.*\)\*\*$/\1/p') \
+    || { release_orphan "$num"; CLAIM_SKIP_REASON="could not re-read comments to confirm the claim race"; return 1; }
+  if [ "$first" != "$SWEEP_ID" ]; then
+    release_orphan "$num"
+    CLAIM_SKIP_REASON="lost claim race to ${first:-unknown}"
+    return 1
+  fi
+  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
 RECOVERY_RESULTS=""
 
@@ -352,8 +473,31 @@ for NUM in $ORPHAN_LIST; do
       if [ "$DRY_RUN" = "true" ]; then
         echo "  [DRY-RUN] Would: gh pr merge $PR_NUM --merge --auto"
       else
-        MERGE_RESULT=$(gh pr merge "$PR_NUM" ${GH_FLAG} --merge --auto 2>&1)
-        MERGE_EXIT=$?
+        # CI gate (MANDATORY before any autonomous merge): merge only when every check on the PR is
+        # green. Field test: PRs merged to staging with checks pending or red (#3165), because branch
+        # protection required none and an auto-merge waits only for *required* checks.
+        CI_GATE_SCRIPT=""
+        _l="$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null || true)"; _l="${_l%/commands/work-on.md}"
+        for _c in '${CLAUDE_PLUGIN_ROOT}' "${FORGE_ROOT:-}" "${FORGEDOCK_HOME:-}" "${FORGE_HOME:-}" "$_l"; do
+          case "$_c" in /*) [ -z "$CI_GATE_SCRIPT" ] && [ -f "$_c/scripts/wait-ci-green.sh" ] && CI_GATE_SCRIPT="$_c/scripts/wait-ci-green.sh" ;; esac
+        done
+        if [ -n "$CI_GATE_SCRIPT" ]; then CI_GATE_OUT=$(bash "$CI_GATE_SCRIPT" "$PR_NUM" ${GH_FLAG}); CI_GATE_RC=$?
+        else CI_GATE_OUT="CI_GATE: ERROR — scripts/wait-ci-green.sh not resolvable (fail closed)"; CI_GATE_RC=2; fi
+        echo "$CI_GATE_OUT"
+        GATED_HEAD=$(printf '%s\n' "$CI_GATE_OUT" | sed -n 's/^CI_GATE_HEAD: //p' | head -1)
+        # rc 3 = CI still running: re-run this block (up to 3 more times) before treating it as a failure.
+        if [ "$CI_GATE_RC" -eq 0 ]; then
+          MERGE_RESULT=$(gh pr merge "$PR_NUM" ${GH_FLAG} --merge --auto --match-head-commit "$GATED_HEAD" 2>&1)
+          MERGE_EXIT=$?
+        else
+          MERGE_RESULT="not merged: CI gate rc=${CI_GATE_RC}"; MERGE_EXIT=1
+          CI_MSG="⛔ /recover-orphans did not merge PR #${PR_NUM}: CI is not green.
+\`\`\`
+${CI_GATE_OUT}
+\`\`\`"
+          gh issue comment "$NUM" ${GH_FLAG} --body "$CI_MSG" 2>/dev/null || true # allowlist:check-command-side-effects
+          gh issue edit "$NUM" ${GH_FLAG} --add-label "needs-human" 2>/dev/null || true # allowlist:check-command-side-effects
+        fi
         echo "  Merge result (exit $MERGE_EXIT): $MERGE_RESULT"
         if [ $MERGE_EXIT -eq 0 ]; then
           # Close the issue explicitly (Closes # only auto-closes on default branch)
@@ -373,25 +517,87 @@ for NUM in $ORPHAN_LIST; do
       # Open PR awaiting review — invoke /review-pr
       echo "  Applying review-pr: invoking /review-pr on PR #$PR_NUM"
       if [ "$DRY_RUN" = "true" ]; then
-        echo "  [DRY-RUN] Would: Skill(skill='review-pr', args='$PR_NUM --auto-merge --issue $NUM --gh-flag $GH_FLAG')"
+        echo "  [DRY-RUN] Would: Skill(skill='{FORGE_SKILL_PREFIX}review-pr', args='$PR_NUM --auto-merge --issue $NUM --gh-flag $GH_FLAG')"
       else
-        Skill(skill="review-pr", args="${PR_NUM} --auto-merge --issue ${NUM} --gh-flag ${GH_FLAG}")
-        # After review: update label
-        gh issue edit "$NUM" ${GH_FLAG} --add-label "workflow:in-review" \
-          --remove-label "workflow:building,workflow:awaiting-merge" 2>/dev/null || true
+        # forge#3148: count trail refusals that predate this sweep, so a refusal from an earlier sweep escalates
+        # instead of re-reviewing the same unrepaired trail every run.
+        # forge#3159: count only TRUSTED comments (pipeline bot, or OWNER/MEMBER/COLLABORATOR) newer than the latest
+        # repair (the most recent needs-human unlabel event), so a stranger's comment or a refusal a human already
+        # repaired never forces an escalation. Epoch fallback on a failed lookup counts more, i.e. fails toward escalation.
+        # --paginate: the comments endpoint returns 30 per page, oldest first. An unreadable count fails toward escalation.
+        PRIOR_TRAIL_CUTOFF=$(gh api --paginate "repos/${GH_REPO}/issues/${NUM}/events" \
+            --jq '.[] | select(.event == "unlabeled" and .label.name == "needs-human") | .created_at' 2>/dev/null \
+            | sort | tail -1)
+        PRIOR_TRAIL_CUTOFF="${PRIOR_TRAIL_CUTOFF:-1970-01-01T00:00:00Z}"
+        # gh api --jq takes one expression and no --arg, so the cutoff goes through a real jq pipe.
+        if PRIOR_TRAIL_IDS=$(set -o pipefail; gh api --paginate "repos/${GH_REPO}/issues/${NUM}/comments" 2>/dev/null \
+            | jq -r --arg cutoff "$PRIOR_TRAIL_CUTOFF" '.[] | select(.body | contains("FORGE:PHASE_TRAIL_FAILED"))
+              | select(.created_at > $cutoff)
+              | select(.user.type == "Bot" or (.author_association | IN("OWNER","MEMBER","COLLABORATOR"))) | .id'); then
+          PRIOR_TRAIL_FAILS=$(printf '%s\n' "$PRIOR_TRAIL_IDS" | grep -c '[0-9]')
+        else
+          PRIOR_TRAIL_FAILS=1
+        fi
+        REVIEW_STATUS=""; REVIEW_BLOCKER=""   # reset per orphan so a previous orphan's result never leaks into this one
+        Skill(skill="{FORGE_SKILL_PREFIX}review-pr", args="${PR_NUM} --auto-merge --issue ${NUM} --gh-flag ${GH_FLAG}")
+        # REVIEW_STATUS = the `status:` field of the REVIEW_RESULT block the Skill call returned.
+        if [ "$REVIEW_STATUS" = "PHASE_TRAIL_FAILED" ]; then
+          # Phase 8 refused the merge: the issue's phase trail is incomplete (review-pr posted the
+          # MISSING lines as FORGE:PHASE_TRAIL_FAILED). Do NOT set workflow:in-review — that only re-queues
+          # the same refusal for the next sweep. Never hand-post the missing markers.
+          if [ "${PRIOR_TRAIL_FAILS:-0}" -gt 0 ]; then
+            gh issue edit "$NUM" ${GH_FLAG} --add-label "needs-human" 2>/dev/null || true
+            gh issue comment "$NUM" ${GH_FLAG} --body "<!-- FORGE:ORPHAN_RECOVERED -->
+## Orphan Recovery — Escalated
+
+**Action**: \`/review-pr\` refused to merge PR #${PR_NUM} again because the phase trail is incomplete, and an earlier refusal was not repaired.
+**Recovered by**: /recover-orphans
+
+See the latest FORGE:PHASE_TRAIL_FAILED comment for the missing phases. Re-run each one via its Skill (or \`/work-on ${NUM}\`), then remove \`needs-human\`." 2>/dev/null || true
+            RECOVERY_RESULTS="${RECOVERY_RESULTS}| #${NUM} | review-pr | PR #${PR_NUM} refused (phase trail) again — needs-human added |\n"
+          else
+            # 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
+              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"
+            fi
+          fi
+        elif [ "$REVIEW_STATUS" = "BLOCKED" ] && echo "$REVIEW_BLOCKER" | grep -qE 'phase trail|auto-merge requires --issue'; then
+          # REVIEW_BLOCKER = the `blocker:` field of the same REVIEW_RESULT block. The gate could not run (verifier
+          # rc>=2 / unresolvable) or had no issue to verify (forge#3147). review-pr already added needs-human for the
+          # rc>=2 case; add it here too so the diagnosis skip above stops re-sweeping this orphan.
+          gh issue edit "$NUM" ${GH_FLAG} --add-label "needs-human" 2>/dev/null || true
+          RECOVERY_RESULTS="${RECOVERY_RESULTS}| #${NUM} | review-pr | PR #${PR_NUM} blocked by the merge gate — needs-human added |\n"
+        elif case "$REVIEW_STATUS" in COMPLETE|ALREADY_MERGED|BLOCKED) false ;; *) true ;; esac; then
+          # forge#3159: an empty or unrecognized status means the review result could not be read. Do not report
+          # "submitted for review" or re-queue it; escalate to a human.
+          gh issue edit "$NUM" ${GH_FLAG} --add-label "needs-human" 2>/dev/null || true
+          RECOVERY_RESULTS="${RECOVERY_RESULTS}| #${NUM} | review-pr | PR #${PR_NUM} unrecognized review status '${REVIEW_STATUS}' — needs-human added |\n"
+        else
+          # After review: update label
+          gh issue edit "$NUM" ${GH_FLAG} --add-label "workflow:in-review" \
+            --remove-label "workflow:building,workflow:awaiting-merge" 2>/dev/null || true
+          RECOVERY_RESULTS="${RECOVERY_RESULTS}| #${NUM} | review-pr | PR #${PR_NUM} submitted for review |\n"
+        fi
       fi
-      RECOVERY_RESULTS="${RECOVERY_RESULTS}| #${NUM} | review-pr | PR #${PR_NUM} submitted for review |\n"
+      [ "$DRY_RUN" = "true" ] && RECOVERY_RESULTS="${RECOVERY_RESULTS}| #${NUM} | review-pr | PR #${PR_NUM} would be submitted for review |\n"
       ;;
 
     create-pr)
       # Branch has commits but no PR — resume /work-on to create PR
       echo "  Applying create-pr: resuming /work-on to advance from build to PR creation"
       if [ "$DRY_RUN" = "true" ]; then
-        echo "  [DRY-RUN] Would: Skill(skill='work-on', args='$NUM')"
+        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
+        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
-        Skill(skill="work-on", args="${NUM}")
+        RECOVERY_RESULTS="${RECOVERY_RESULTS}| #${NUM} | create-pr | /work-on resume skipped: ${CLAIM_SKIP_REASON} |\n"
       fi
-      RECOVERY_RESULTS="${RECOVERY_RESULTS}| #${NUM} | create-pr | Resumed /work-on — branch $BRANCH has commits, no PR |\n"
       ;;
 
     reset-labels)

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 -->
 
@@ -37,7 +41,7 @@ For each agent selected in Phase 3B, read **only** the files relevant to that ag
 
 1. **Always read first** (shared protocols, all agents require this):
    ```
-   Read: $FORGE_HOME/commands/review-pr-agents/protocols.md
+   Read: ${CLAUDE_PLUGIN_ROOT}/commands/review-pr-agents/protocols.md
    ```
 
 2. **Then read the persona file for each selected agent**:
@@ -70,11 +74,11 @@ For each agent selected in Phase 3B, read **only** the files relevant to that ag
 
 ## Loading Instructions for Phase 3C
 
-Replace the single `Read: $FORGE_HOME/commands/review-pr-agents.md` call with:
+Replace the single `Read: ${CLAUDE_PLUGIN_ROOT}/commands/review-pr-agents.md` call with:
 
 ```
-Read: $FORGE_HOME/commands/review-pr-agents/protocols.md
-Read: $FORGE_HOME/commands/review-pr-agents/<persona>.md   (one per selected agent)
+Read: ${CLAUDE_PLUGIN_ROOT}/commands/review-pr-agents/protocols.md
+Read: ${CLAUDE_PLUGIN_ROOT}/commands/review-pr-agents/<persona>.md   (one per selected agent)
 ```
 
 Each persona file contains:
@@ -87,3 +91,5 @@ The `protocols.md` file contains:
 - Tool-Result Truncation Discipline
 - Evidence-Based Review Protocol (all agents follow)
 - Structured Findings Protocol (machine-readable findings block format)
+
+**Spec root (MANDATORY)**: read every file named in this catalog from `${CLAUDE_PLUGIN_ROOT}` — the install root of the ForgeDock plugin that is running this command (Claude Code fills it in when it loads the spec). Only if that path does not start with `/` (not a Claude Code plugin session: install.sh, Codex, OpenCode) use `$FORGE_HOME` instead. Never read sub-files from `$FORGE_HOME` when the plugin root resolved: an exported `FORGE_HOME` can point at a different, older ForgeDock checkout, and mixing roots runs stale phase specs.

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
@@ -9,7 +10,9 @@ install: core
 
 # Staging Review
 
-**Trigger**: Invoked by the orchestrator via `Skill("review-pr-staging", $ARGUMENTS)`, or directly with `$ARGUMENTS` = "staging", a PR number targeting main, or "staging:feature".
+> **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.
+
+**Trigger**: Invoked by the orchestrator via `Skill("{FORGE_SKILL_PREFIX}review-pr-staging", $ARGUMENTS)`, or directly with `$ARGUMENTS` = "staging", a PR number targeting main, or "staging:feature".
 
 Performs comprehensive review of `staging` before merging to `main`. Handles large diffs (1,000-10,000+ lines), diverse changes, deep analysis, and business impact assessment.
 
@@ -502,7 +505,13 @@ Missing persona templates are a fatal setup error, not permission to skip multi-
 
 ```bash
 TEMPLATE_BASE=""
-if [[ -f "$FORGE_HOME/commands/review-pr-agents/protocols.md" ]]; then
+# Tier 0: the running plugin's own root (Claude Code substitutes this exact spelling; elsewhere it stays a
+# literal that the /* check rejects). Wins over an exported FORGE_HOME, which may name an older checkout.
+_PLUGIN_ROOT='${CLAUDE_PLUGIN_ROOT}'; case "$_PLUGIN_ROOT" in /*) ;; *) _PLUGIN_ROOT="" ;; esac
+if [[ -n "$_PLUGIN_ROOT" && -f "$_PLUGIN_ROOT/commands/review-pr-agents/protocols.md" ]]; then
+  TEMPLATE_BASE="$_PLUGIN_ROOT/commands/review-pr-agents"
+  TEMPLATE_SOURCE="plugin_root"
+elif [[ -f "$FORGE_HOME/commands/review-pr-agents/protocols.md" ]]; then
   TEMPLATE_BASE="$FORGE_HOME/commands/review-pr-agents"
   TEMPLATE_SOURCE="forge_home"
 else
@@ -530,7 +539,7 @@ fi
 
 **If `TEMPLATE_SOURCE` is `none`**: HARD STOP. Post a PR comment explaining the setup is broken, instructing the user to run `npx forgedock update` to repair the install, add `needs-human`, and exit without posting any findings or a verdict. **NEVER perform the review inline in the main agent context as a substitute.**
 
-**If `TEMPLATE_SOURCE` is `forge_home` or `repo_path`** (normal cases — behavior unchanged): `Read: $TEMPLATE_BASE/protocols.md` and `Read: $TEMPLATE_BASE/<persona>.md` per selected agent.
+**If `TEMPLATE_SOURCE` is `plugin_root`, `forge_home` or `repo_path`** (normal cases — behavior unchanged): `Read: $TEMPLATE_BASE/protocols.md` and `Read: $TEMPLATE_BASE/<persona>.md` per selected agent.
 
 **If `TEMPLATE_SOURCE` is `monolithic_catalog`** (last resort): `Read: $MONOLITHIC_CATALOG` and extract the shared protocols section plus each selected persona's section from within that single file.
 
@@ -593,7 +602,7 @@ TEST_GATE_REASON="Phase 6.5 not yet run"
 
 # Invoke /test-gate with the bundle PRs already computed in Phase 0A
 # ALL_PR_NUMBERS is the de-duplicated union of both scan methods (commit log + merge subjects)
-GATE_OUTPUT=$(Skill("test-gate", "--prs \"$(echo $ALL_PR_NUMBERS | tr '\n' ' ' | xargs)\" --base $DEFAULT_BRANCH"))
+GATE_OUTPUT=$(Skill("{FORGE_SKILL_PREFIX}test-gate", "--prs \"$(echo $ALL_PR_NUMBERS | tr '\n' ' ' | xargs)\" --base $DEFAULT_BRANCH"))
 
 # Extract machine-readable verdict from Skill output
 TEST_GATE_VERDICT=$(echo "$GATE_OUTPUT" | grep -oP '(?<=FORGE:TEST_GATE:RESULT=)(BLOCK|PASS|SKIP)' | tail -1 || echo "SKIP")
@@ -872,7 +881,7 @@ else
 # --label is repeatable (not comma-joined) per the /issue programmatic contract.
 # ${MILESTONE_FLAG} carries the Phase 7D derivation through — empty string is
 # a no-op arg when the reviewed branch has no milestone (plain staging→main).
-ISSUE_SKILL_OUTPUT=$(Skill(skill="issue", args="--title \"$STAGING_FINDING_TITLE\" --body-file \"$STAGING_FINDING_BODY_FILE\" --label review-finding --label needs-validation --label staging-review --label \"$STAGING_FINDING_PRIORITY\" ${MILESTONE_FLAG}"))
+ISSUE_SKILL_OUTPUT=$(Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"$STAGING_FINDING_TITLE\" --body-file \"$STAGING_FINDING_BODY_FILE\" --label review-finding --label needs-validation --label staging-review --label \"$STAGING_FINDING_PRIORITY\" ${MILESTONE_FLAG}"))
 # /issue re-reads the created issue and hard-fails unless this exact marker is present.
 rm -f "$STAGING_FINDING_BODY_FILE"