forgedock 1.1.11 → 1.2.0

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

@@ -300,6 +300,7 @@ current session's live wake pick them up automatically if it is still running).
 - Worktrees removed: {N}
 - Branches pruned: {N}
 - Milestones closed: {N}
+- Coordination board: {IF `COORD_ISSUE_NUMBER` was set this run: "closed — #{COORD_ISSUE_NUMBER}" ELSE: "n/a (no claims board this batch)"} <!-- Added: forge#2072 -->
 
 ### Agent Efficiency (from /audit-agents)
 

package/commands/orchestrate.md

@@ -1,6 +1,6 @@
 ---
 description: Orchestrate parallel work on multiple issues or an entire milestone — spawns sub-agents that each run the full /work-on pipeline
-argument-hint: [milestone <slug> | #1 #2 #3 | next <N> | fast-lane | priority:P0]
+argument-hint: "[milestone <slug> | #1 #2 #3 | next <N> | fast-lane | priority:P0]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

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

@@ -38,6 +38,19 @@ while IFS= read -r line; do
   [ -z "$SLUG" ] && continue
   [ "$COUNT" -lt 3 ] && continue
 
+  # SECURITY: $SLUG is sourced from a <!-- FORGE:PATTERN: ([^\s>]+) --> tag inside
+  # a review-finding issue body — untrusted, externally-influenced text. It is
+  # interpolated below into a Skill(skill="issue", args="...") string, and
+  # commands/issue.md's Phase 1A resolves that string via `eval "set -- $ARGUMENTS"`.
+  # Any shell metacharacter (quote, backtick, $, ;) in $SLUG would break out of the
+  # intended --title token and be eval'd as shell. Whitelist-validate at the
+  # extraction point — the only legitimate values are check-registry-safe
+  # identifiers (also used to build a filename: scripts/check-registry/${SLUG}.sh).
+  if ! echo "$SLUG" | grep -qE '^[A-Za-z0-9_-]+$'; then
+    echo "WARNING: pattern slug '$SLUG' contains disallowed characters — skipping check-promotion for this pattern (unsafe for interpolation into a downstream eval sink)."
+    continue
+  fi
+
   # Check if a promotion issue already exists for this slug (avoid duplicates)
   EXISTING_PROMOTION=$(gh issue list {GH_FLAG} \
     --label "check-promotion" \
@@ -57,10 +70,13 @@ while IFS= read -r line; do
     "#\(.number)"
   ' 2>/dev/null | head -10 | tr '\n' ' ')
 
-  gh issue create {GH_FLAG} \
-    --title "feat(quality-gate): promote pattern '$SLUG' to deterministic registry check (recurred ${COUNT}x)" \
-    --label "check-promotion,priority:P2" \
-    --body "$(cat <<CHECK_EOF
+  # Route through the /issue programmatic create-hook (#2085) instead of a raw
+  # `gh issue create` — gets Phase 2D dedup + Phase 3F body validation for free.
+  # The hook's programmatic mode requires the body via --body-file, and expects
+  # one repeatable --label flag per label (a single comma-joined --label value
+  # would be treated as one malformed label name, not two labels).
+  CHECK_BODY_FILE=$(mktemp)
+  cat > "$CHECK_BODY_FILE" <<CHECK_EOF
 ## Problem
 
 The review-finding pattern \`$SLUG\` has recurred ${COUNT} times in the analysis window ($(date -u +%Y-%m-%d) window). Each recurrence costs a full investigate→build→review→merge cycle. A static check catches this in milliseconds.
@@ -91,7 +107,9 @@ ${SOURCE_FINDINGS}
 
 <!-- AUTO-CREATED: pipeline-health Phase 4A — pattern recurrence threshold exceeded -->
 CHECK_EOF
-  )"
+
+  Skill(skill="issue", args="--title \"feat(quality-gate): promote pattern '$SLUG' to deterministic registry check (recurred ${COUNT}x)\" --body-file $CHECK_BODY_FILE --label check-promotion --label priority:P2")
+  rm -f "$CHECK_BODY_FILE"
   echo "Created check-promotion issue for pattern '$SLUG' (recurred ${COUNT}x from: $SOURCE_FINDINGS)"
 done <<< "$PATTERN_LIST"
 ```
@@ -150,6 +168,16 @@ echo "$SPEC_CONCENTRATION" | while IFS=' ' read -r count spec_file finding_nums;
   [ -z "$spec_file" ] && continue
   [ "${count:-0}" -lt "$SPEC_DOCTOR_THRESHOLD" ] && continue
 
+  # SECURITY (defense-in-depth, consistency with $SLUG above): $spec_file is
+  # already constrained by the extraction regex (commands/[a-z0-9_/-]+\.md), but
+  # it is interpolated below into a Skill(skill="issue", args="...") string that
+  # /issue's Phase 1A resolves via eval. Whitelist-validate again at point of use
+  # so this call site does not depend solely on the extraction regex staying safe.
+  if ! echo "$spec_file" | grep -qE '^commands/[A-Za-z0-9_/-]+\.md$'; then
+    echo "WARNING: spec file '$spec_file' failed the safe-path whitelist — skipping spec-doctor trigger for this entry (unsafe for interpolation into a downstream eval sink)."
+    continue
+  fi
+
   # Skip if a spec-doctor trigger issue already exists for this spec (dedup)
   EXISTING_TRIGGER=$(gh issue list {GH_FLAG} \
     --label "spec-doctor-trigger" \
@@ -167,10 +195,10 @@ echo "$SPEC_CONCENTRATION" | while IFS=' ' read -r count spec_file finding_nums;
   FINDING_LINKS=$(echo "$finding_nums" | tr ',' '\n' | \
     awk '{print "- " $0}' | head -20 | tr '\n' '\n')
 
-  gh issue create {GH_FLAG} \
-    --title "feat(spec-doctor): queue spec evolution pass for $(basename $spec_file .md) (${count} concentrated findings)" \
-    --label "spec-doctor-trigger,priority:P2" \
-    --body "$(cat <<TRIGGER_EOF
+  # Route through the /issue programmatic create-hook (#2085) instead of a raw
+  # `gh issue create` — same rationale and --label handling as Phase 4A above.
+  TRIGGER_BODY_FILE=$(mktemp)
+  cat > "$TRIGGER_BODY_FILE" <<TRIGGER_EOF
 ## Problem
 
 \`$spec_file\` has accumulated **${count} review findings** in the last 30 days.
@@ -206,7 +234,9 @@ This issue was auto-created by \`pipeline-health\` Phase 4A.5.
 
 <!-- AUTO-CREATED: pipeline-health Phase 4A.5 — spec concentration threshold exceeded -->
 TRIGGER_EOF
-  )"
+
+  Skill(skill="issue", args="--title \"feat(spec-doctor): queue spec evolution pass for $(basename $spec_file .md) (${count} concentrated findings)\" --body-file $TRIGGER_BODY_FILE --label spec-doctor-trigger --label priority:P2")
+  rm -f "$TRIGGER_BODY_FILE"
   echo "Created spec-doctor trigger for '$spec_file' (${count} findings: $finding_nums)"
 done
 ```

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

@@ -10,13 +10,26 @@ install: extras
 
 ### 5A: Post health report
 
-Create a detailed health report as a GitHub issue in the Forge repo:
+Create a detailed health report as a GitHub issue in the Forge repo, routed through the
+`/issue` programmatic create-hook (#2085) instead of a raw `gh issue create`. Because `/issue`'s
+programmatic mode resolves `GH_REPO` from `forge.yaml → project.owner/repo` (via `$FORGE_CONFIG`,
+default `forge.yaml`) with no explicit `-R` override, and `$FORGE_REPO` may differ from the
+analyzed project's own repo (`forge.yaml → project.forge_repo`, see Config Resolution), point
+`$FORGE_CONFIG` at a synthesized minimal config for the duration of the call so the create-hook
+targets the Forge repo, not the analyzed repo:
 
 ```bash
-gh issue create -R $FORGE_REPO \
-  --title "Pipeline Health: $REPO — $(date +%Y-%m-%d) — Score: [SCORE]/100" \
-  --label "health-report" \
-  --body "$(cat <<'EOF'
+FORGE_ISSUE_HOOK_CONFIG=$(mktemp)
+cat > "$FORGE_ISSUE_HOOK_CONFIG" <<HOOKCFG_EOF
+project:
+  owner: "${FORGE_REPO%%/*}"
+  repo: "${FORGE_REPO##*/}"
+paths:
+  root: "$FORGE_HOME"
+HOOKCFG_EOF
+
+HEALTH_BODY_FILE=$(mktemp)
+cat > "$HEALTH_BODY_FILE" <<'EOF'
 ## Pipeline Health Report
 
 **Project**: $REPO
@@ -229,9 +242,71 @@ _Post-deploy audit findings by failure point — see Phase 3A-II table above._
 
 [Git log from Phase 2A]
 EOF
-)"
+
+# Environment variable state is not guaranteed to persist across separate tool-call
+# boundaries (a Bash call's shell state does not carry into the next Bash call, and the
+# Skill tool has no env-passthrough parameter — it only accepts `skill`/`args`; `Skill`
+# is a distinct tool invocation, not a bash subprocess, so an `export` in a prior Bash
+# call cannot reach the nested /issue phases' own Bash calls at all). What DOES persist
+# reliably across tool-call boundaries is the working directory (per the Bash tool's own
+# contract) and the filesystem it points at. commands/issue.md Phase 1A resolves
+# `CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"` — when `$FORGE_CONFIG` is unset (the normal
+# case, since env vars do not propagate), it falls back to the literal relative path
+# `forge.yaml`, which resolves against the current working directory. So instead of
+# relying on env-var propagation, temporarily swap the on-disk `forge.yaml` at the repo
+# root for the synthesized hook config, invoke /issue, then restore the original content —
+# this is observed correctly by every nested Bash call regardless of tool-call boundaries.
+FORGE_YAML_BACKUP=$(mktemp)
+FORGE_YAML_EXISTED=false
+[ -f forge.yaml ] && FORGE_YAML_EXISTED=true
+cp forge.yaml "$FORGE_YAML_BACKUP" 2>/dev/null || true
+# Restore helper: distinguishes "forge.yaml existed before the swap" (restore the backup)
+# from "forge.yaml was absent before the swap" (remove the stub rather than leaving an
+# empty file behind, which `mv`-ing an empty mktemp file would otherwise do).
+restore_forge_yaml() {
+  if [ "$FORGE_YAML_EXISTED" = "true" ]; then
+    cp "$FORGE_YAML_BACKUP" forge.yaml 2>/dev/null || echo "ERROR: failed to restore forge.yaml from backup ${FORGE_YAML_BACKUP} — repo config may still be the synthesized Forge-repo stub. Restore manually before running any other command." >&2
+  else
+    rm -f forge.yaml 2>/dev/null || true
+  fi
+}
+# Register the restore as a trap on EXIT (covers normal completion, an error inside the
+# Skill(...) call, AND an unexpected early termination of this bash invocation) — not just
+# the sequential "restore line after the Skill call" below, which would be skipped if this
+# script/session terminates before reaching it. The trap is cleared right after the
+# sequential restore succeeds, so it does not double-restore (harmless if it did, but
+# avoids a redundant no-op restore on the normal path).
+trap restore_forge_yaml EXIT
+cp "$FORGE_ISSUE_HOOK_CONFIG" forge.yaml
+
+ISSUE_RESULT=$(Skill(skill="issue", args="--title \"Pipeline Health: $REPO — $(date +%Y-%m-%d) — Score: [SCORE]/100\" --body-file $HEALTH_BODY_FILE --label health-report"))
+echo "$ISSUE_RESULT"
+
+# Restore the original forge.yaml immediately — so a subsequent Bash call in this same
+# pipeline-health run (or any other command) does not keep reading the analyzed project's
+# config as the Forge repo's synthesized hook config. The EXIT trap above is the backstop
+# for abnormal termination; this is the normal-path restore, and clears the trap once done.
+restore_forge_yaml
+trap - EXIT
+
+# Verify the issue actually landed in FORGE_REPO — if the forge.yaml swap above was not
+# honored (e.g. some nested phase re-read a cached config from before the swap), the report
+# would be mis-filed into the analyzed project's own GH_REPO instead of the Forge repo. Fail
+# loudly rather than let a pipeline-health report silently spam the analyzed project's issue
+# tracker.
+if ! echo "$ISSUE_RESULT" | grep -q "github.com/${FORGE_REPO}/issues/"; then
+  echo "ERROR: pipeline-health report was not created in FORGE_REPO ($FORGE_REPO) — verify the forge.yaml swap propagated to the /issue invocation above before proceeding."
+fi
+
+rm -f "$FORGE_ISSUE_HOOK_CONFIG" "$HEALTH_BODY_FILE"
 ```
 
+The health report body above does not carry the `## Problem`/`## Affected Files`/`## Acceptance
+Criteria` mandatory sections (it is a metrics report, not a pipeline work item) — `/issue`'s
+Phase 3F pre-create validation auto-repairs this non-blockingly by appending placeholder
+sections, exactly as it does for any other programmatic caller that omits them. This is expected
+and does not indicate a problem with the report body.
+
 ### 5B: Create improvement issues in Forge
 
 For each improvement proposal, create a trackable issue using the `/issue` structure.
@@ -248,11 +323,25 @@ For each improvement proposal, create a trackable issue using the `/issue` struc
 - Metric 10–20% below target → `P2`
 - Metric < 10% below target → `P3`
 
+Routed through the `/issue` programmatic create-hook (#2085), same as 5A — `$FORGE_REPO` may
+differ from the analyzed repo's own `forge.yaml → project.owner/repo`, so `$FORGE_CONFIG` is
+pointed at a synthesized minimal config for the duration of the call. This body already carries
+all three mandatory sections (`## Problem`, `## Affected Files`, `## Acceptance Criteria`), so
+Phase 3F's pre-create validation is expected to be a no-op here.
+
 ```bash
-gh issue create -R $FORGE_REPO \
-  --title "fix([command]): [description]" \
-  --label "[bug|enhancement|feature],[P1|P2|P3]" \
-  --body "## Problem
+FORGE_ISSUE_HOOK_CONFIG=$(mktemp)
+cat > "$FORGE_ISSUE_HOOK_CONFIG" <<HOOKCFG_EOF
+project:
+  owner: "${FORGE_REPO%%/*}"
+  repo: "${FORGE_REPO##*/}"
+paths:
+  root: "$FORGE_HOME"
+HOOKCFG_EOF
+
+PROPOSAL_BODY_FILE=$(mktemp)
+cat > "$PROPOSAL_BODY_FILE" <<'EOF'
+## Problem
 
 [1–3 sentences describing what the pipeline health metric reveals. Include the current value and target value.]
 
@@ -260,13 +349,13 @@ gh issue create -R $FORGE_REPO \
 
 ## Root Cause (if known)
 
-\`commands/[file].md\` [section] — [what the section currently does that causes the metric to suffer]
+`commands/[file].md` [section] — [what the section currently does that causes the metric to suffer]
 
 ## Affected Files
 
 Files that need changes:
 
-1. \`commands/[file].md\` — [what needs to change in this file]
+1. `commands/[file].md` — [what needs to change in this file]
 
 ## Expected Behavior
 
@@ -277,7 +366,45 @@ After the fix, [metric] should reach [target value]. [Describe the concrete beha
 - [ ] [Specific, testable criterion tied to the metric]
 - [ ] [Specific, testable criterion tied to the command behaviour]
 - [ ] No regression in other pipeline-health metrics
-"
+EOF
+
+# See the persistence note in 5A above — env vars do not cross tool-call boundaries, and
+# the Skill tool is a distinct invocation, not a bash subprocess. Use the same
+# working-directory-relative forge.yaml swap as 5A instead of relying on `export`. This is a
+# separate bash invocation from 5A's, so the swap/restore/trap setup is repeated here rather
+# than reused (shell functions and traps do not persist across separate tool-call boundaries
+# any more than exported env vars do).
+FORGE_YAML_BACKUP=$(mktemp)
+FORGE_YAML_EXISTED=false
+[ -f forge.yaml ] && FORGE_YAML_EXISTED=true
+cp forge.yaml "$FORGE_YAML_BACKUP" 2>/dev/null || true
+restore_forge_yaml() {
+  if [ "$FORGE_YAML_EXISTED" = "true" ]; then
+    cp "$FORGE_YAML_BACKUP" forge.yaml 2>/dev/null || echo "ERROR: failed to restore forge.yaml from backup ${FORGE_YAML_BACKUP} — repo config may still be the synthesized Forge-repo stub. Restore manually before running any other command." >&2
+  else
+    rm -f forge.yaml 2>/dev/null || true
+  fi
+}
+# Same EXIT-trap backstop as 5A — restores forge.yaml even if the Skill(...) call errors or
+# this bash invocation terminates early, not just on the normal sequential path below.
+trap restore_forge_yaml EXIT
+cp "$FORGE_ISSUE_HOOK_CONFIG" forge.yaml
+
+ISSUE_RESULT=$(Skill(skill="issue", args="--title \"fix([command]): [description]\" --body-file $PROPOSAL_BODY_FILE --label \"[bug|enhancement|feature]\" --label \"[P1|P2|P3]\""))
+echo "$ISSUE_RESULT"
+
+# Restore the original forge.yaml immediately — same rationale as 5A. Clears the EXIT trap
+# once the normal-path restore succeeds.
+restore_forge_yaml
+trap - EXIT
+
+# Same wrong-repo safeguard as 5A — fail loudly instead of silently filing the improvement
+# proposal into the analyzed project's own repo.
+if ! echo "$ISSUE_RESULT" | grep -q "github.com/${FORGE_REPO}/issues/"; then
+  echo "ERROR: pipeline-health proposal was not created in FORGE_REPO ($FORGE_REPO) — verify the forge.yaml swap propagated to the /issue invocation above before proceeding."
+fi
+
+rm -f "$FORGE_ISSUE_HOOK_CONFIG" "$PROPOSAL_BODY_FILE"
 ```
 
 ---

package/commands/pipeline-health.md

@@ -1,6 +1,6 @@
 ---
 description: Self-analysis — measures pipeline performance, correlates with prompt changes, proposes improvements
-argument-hint: [project repo slug or "all"]
+argument-hint: "[project repo slug or \"all\"]"
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/pipeline-resume.md

@@ -1,6 +1,6 @@
 ---
 description: Recover full pipeline context after compaction — find the last active issue, reconstruct FORGE annotations, and resume work
-argument-hint: [issue number (optional — auto-detects if omitted)]
+argument-hint: "[issue number (optional — auto-detects if omitted)]"
 install: extras
 ---
 

package/commands/pipeline-status.md

@@ -1,6 +1,6 @@
 ---
 description: Pipeline-wide situational awareness — groups open issues by workflow state, shows active PRs, flags stale items, and reports milestone progress
-argument-hint: [--repo <owner/repo> | --stale-days <N>]
+argument-hint: "[--repo <owner/repo> | --stale-days <N>]"
 install: extras
 ---
 

package/commands/qa-sweep.md

@@ -1,6 +1,6 @@
 ---
 description: Full platform QA sweep — auto-discovers every page, tests every UI element via browser automation, creates GitHub issues for all findings
-argument-hint: [all | dashboard | marketing | page <route> | journey | visual | functional | a11y]
+argument-hint: "[all | dashboard | marketing | page <route> | journey | visual | functional | a11y]"
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -274,10 +274,11 @@ Each journey agent: maintain state ledger, verify outcomes cross-step, report da
 1. Parse all agent findings
 2. Deduplicate (prefer journey context over page-only findings)
 3. Reprioritize: found in 3+ pages → bump severity; blocks journey → P0
-4. Create GitHub issues:
+4. Create GitHub issues — route creation through the `/issue` create-hook's programmatic invocation contract (see `commands/issue.md` → Programmatic Invocation Contract) so dedup and mandatory-section validation run on every finding:
 
 ```bash
-gh issue create --title "{fix|feat}: {title} on {page}" --label "qa,{bug_or_enhancement},{priority}" --body "$(cat <<'BODY_EOF'
+QA_BODY_FILE=$(mktemp)
+cat > "$QA_BODY_FILE" <<'BODY_EOF'
 ## Problem
 
 {1-3 sentences: what the QA sweep found. What's broken or missing, with specific observable behavior.}
@@ -318,9 +319,14 @@ Files that need changes:
 
 {List other pages where this issue was also observed, or "None"}
 BODY_EOF
-)"
 ```
 
+```
+Skill(skill="issue", args="--title \"{fix|feat}: {title} on {page}\" --body-file \"$QA_BODY_FILE\" --label \"qa\" --label \"{bug_or_enhancement}\" --label \"{priority}\"")
+```
+
+`qa`, `{bug_or_enhancement}`, and `{priority}` are each passed as their own `--label` flag — `/issue`'s programmatic mode does not comma-split a single `--label` value.
+
 Issue body includes: Source, Page, Device, Type, Severity, Journey context, Description, Steps to Reproduce, State Context, Cross-Page Impact.
 
 5. Cross-page consistency table (compare balance/tier/email across all pages)

package/commands/recover-orphans.md

@@ -1,6 +1,6 @@
 ---
 description: Scan for pipeline-orphaned issues stuck in intermediate workflow states and recover them — diagnose each orphan's actual GitHub state, apply recovery actions, clean up worktrees
-argument-hint: [--dry-run | --since <hours> | --issue <number>]
+argument-hint: "[--dry-run | --since <hours> | --issue <number>]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

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

@@ -29,6 +29,10 @@ All tool results consumed by agents — including diff slices, file reads, and c
 
 Rationale: agents receiving oversized context perform worse, not better — attention dilutes across irrelevant content, and token limits risk truncating the structured findings block that the triage phase depends on.
 
+## File Resolution Discipline
+
+Pipeline agents MUST NOT use `find` (unbounded or filesystem-wide) to locate protocol files, persona templates, or verification scripts under any circumstances. If a `Read` or `bash` invocation of an expected pipeline file fails (e.g. because `$FORGE_HOME` is unset and the path degraded to a root-anchored form), that is never a reason to search the filesystem — it means the deterministic fallback chain the orchestrator already computed (`$FORGE_HOME` → `$REPO_PATH` → documented last-resort) was exhausted. Stop and report the failure (or fall through to the orchestrator's documented FATAL/hard-stop behavior — see `commands/review-pr.md` Phase 3C `TEMPLATE_BASE` guard) instead of improvising a `find /`-style search. A filesystem-wide `find` on an unset variable is the exact failure mode that produced runaway orphaned processes in production (see forge#1984, forge#2035). <!-- Added: forge#2035 -->
+
 ---
 
 ## Evidence-Based Review Protocol (ALL Agents Follow) <!-- allowlist:check-protocol-restatements -->

package/commands/review-pr-agents.md

@@ -11,10 +11,13 @@ to avoid loading the full catalog on every invocation. Protocols live in `docs/s
 Do not modify this file without also updating `review-pr.md`. To update either protocol, edit
 `docs/spec/review-protocol.md` and sync the copy to `commands/review-pr-agents/protocols.md`.
 
-**NEVER use the Agent tool.** The orchestrator dispatches review agents via `Task` only. `Agent` spawns
-opaque subprocesses that bypass the `allowed-tools` constraint, cannot post structured findings to the PR,
-and are not tracked by the review pipeline. Every agent template is intended to be passed as the `prompt`
-argument to a `Task(...)` call.
+**Dispatch tool: `Task` preferred, `Agent` is the documented fallback.** The orchestrator (`/review-pr` or
+`/review-pr-staging`) resolves the dispatch tool once per invocation per its **Sub-Agent Dispatch Tool
+Resolution** rule: `Task` when available, `Agent` when `Task` is absent from the environment — never inline
+self-review as a substitute for either. Every agent template in this catalog is intended to be passed as
+the `prompt` argument to whichever tool the orchestrator resolved (`Task(...)` or `Agent(...)`), with the
+same per-agent isolation and the same requirement that each agent posts structured findings to the PR
+directly (`gh pr comment`) rather than relaying them through the orchestrator's own context.
 
 <!-- FORGE:PROTOCOL_SOURCE — canonical definition lives in docs/spec/review-protocol.md -->
 

package/commands/review-pr-staging.md

@@ -1,8 +1,8 @@
 ---
 description: Staging review mode — comprehensive review of staging branch before deploy to main
-argument-hint: [PR number or "staging"]
-allowed-tools: Task, Bash, Read, Grep, Glob, WebFetch
-install: extras
+argument-hint: "[PR number or \"staging\"]"
+allowed-tools: Task, Agent, Bash, Read, Grep, Glob, WebFetch
+install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -15,20 +15,33 @@ Performs comprehensive review of `staging` before merging to `main`. Handles lar
 
 **Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "sonnet" (standard tier). Fallback: `model: "opus"` if rate-limited. User can override with `--model <name>`. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
-**NEVER use the Agent tool** — this spec uses `Task` for domain agent dispatch. The Agent tool bypasses the allowed-tools constraint declared in this spec's frontmatter and produces opaque output that cannot be structured into the review verdict.
+**Sub-agent dispatch tool: `Task` preferred, `Agent` is the documented fallback.** This spec dispatches domain review agents via a sub-agent-spawning tool. Resolve which one is available ONCE per invocation, before Phase 3, per the **Sub-Agent Dispatch Tool Resolution** rule below — do not halt to ask the operator which tool to use. Never fall back to reviewing inline in the orchestrator's own context; that is a strictly weaker substitute for an isolated fresh-context reviewer and is not a permitted fallback.
 
 <!-- FORGE:SPEC_LOADED — review-pr-staging.md loaded and active. Agent is bound by this spec. -->
 
+## Sub-Agent Dispatch Tool Resolution (MANDATORY — run once, before Phase 3)
+
+This spec dispatches Bug Hunter and domain review agents via a sub-agent-spawning tool. Different runtimes expose different tools for this — resolve deterministically, once per invocation, and use the same tool for every dispatch call in this run:
+
+1. **If `Task` is available in the current environment**: set `{DISPATCH_TOOL} = Task`. This is the preferred tool — tightest `allowed-tools` scoping. (Identical resolution logic to `/review-pr` Phase 3C — do not diverge.)
+2. **Else if `Agent` is available**: set `{DISPATCH_TOOL} = Agent`. This is the documented fallback, not a degraded path — use it exactly as you would `Task`: one call per selected agent (Bug Hunters in Phase 3, Code Quality in Phase 4, domain agents in Phase 5), same prompt template, `subagent_type: "general-purpose"` (or the closest equivalent the environment offers), same requirement that each agent posts its own findings directly to the PR via `gh pr comment`. Isolation and fresh-context review are preserved either way.
+3. **Neither tool is available**: this is a genuine setup defect, not a routing decision — HARD STOP, post a PR/issue comment explaining that no sub-agent dispatch tool is available, add `needs-human`, and exit without posting a verdict. Do NOT fall back to reviewing inline in the orchestrator's own context.
+
+**Do not halt to ask the operator which tool to use.** Steps 1–2 are deterministic and fully resolve the common case; only step 3 (both absent) requires a stop, and even then the action is HARD STOP + `needs-human`, not a question back to the operator.
+
+Everywhere this file says `Task(...)`, read it as `{DISPATCH_TOOL}(...)` using the value resolved here.
+
 ## Forbidden Tools Self-Check
 
-**Before executing any phase**, verify you are NOT using any of these tools:
+**Before executing any phase**, verify you are NOT using any of these:
 
-| Tool | Status | Reason |
+| Tool/Pattern | Status | Reason |
 |------|--------|--------|
-| `Agent` | **FORBIDDEN** | Bypasses allowed-tools constraint; produces opaque output that cannot be structured into the review verdict |
+| `Agent`, when `Task` is available | **FORBIDDEN** | `Task` is preferred whenever present — `Agent` is only the fallback for when `Task` is absent, not a free substitute |
+| Inline self-review (no sub-agent spawn at all) | **FORBIDDEN** | Bypasses isolated fresh-context review entirely — always spawn via the resolved `{DISPATCH_TOOL}`, never review directly in the orchestrator's own context |
 | `EnterPlanMode` | **FORBIDDEN** | Breaks execution context; phases must be executed, not planned |
 
-If you find yourself about to call `Agent(...)`, stop and use `Task(...)` instead.
+If you find yourself about to call `Agent(...)` while `Task` is available, stop and use `Task(...)` instead. If neither `Task` nor `Agent` is available, do not fall through to inline review — follow step 3 of Sub-Agent Dispatch Tool Resolution above.
 
 ---
 
@@ -677,13 +690,16 @@ Check for open review-finding issues at same file:line → skip. Closed issues a
 ### 7F: Create Issues
 Sequential creation. Title: `Staging Review: {summary} (staging → main)`. Labels: review-finding, needs-validation, staging-review, priority:P1/priority:P2/priority:P3. Body includes: source branch context (`staging`), code context, evidence, validation checklist.
 
-**For each finding** (that passes dedup), create issue:
+**For each finding** (that passes dedup), create issue through the `/issue` create-hook's programmatic invocation contract (see `commands/issue.md` § "Programmatic Invocation Contract") instead of calling the raw issue-creation command directly:
 ```bash
-ISSUE_NUM=$(gh issue create \
-  -R {GH_REPO} \
-  --title "chore: [summary] (staging review — PR #${PR_NUMBER})" \
-  --label "review-finding,needs-validation,staging-review,{priority}" \
-  --body "$(cat <<'ISSUE_EOF'
+STAGING_FINDING_TITLE="chore: [summary] (staging review — PR #${PR_NUMBER})"
+# Defense-in-depth: /issue's arg tokenizer (commands/issue.md, forge#2094) uses
+# an xargs-based tokenizer that never expands backtick/$(...) substitution, so
+# this is no longer required for safety — but strip it anyway so the raw title
+# stays readable if it round-trips through any other eval-based consumer.
+STAGING_FINDING_TITLE=$(printf '%s' "$STAGING_FINDING_TITLE" | tr '`' "'" | sed 's/\$(/$ (/g')
+STAGING_FINDING_BODY_FILE=$(mktemp)
+cat <<'ISSUE_EOF' > "$STAGING_FINDING_BODY_FILE"
 ## Problem
 
 [One sentence: what bug or issue was found. Where it occurs (`file:line`) and what it causes.]
@@ -716,7 +732,20 @@ Files that need changes:
 - [ ] Finding validated: VALIDATED / FALSE_POSITIVE / INCONCLUSIVE
 - [ ] If VALIDATED: fix implemented and tested on correct branch
 ISSUE_EOF
-)" --json number --jq '.number')
+
+# --label is repeatable (not comma-joined) per the /issue programmatic contract.
+Skill(skill="issue", args="--title \"$STAGING_FINDING_TITLE\" --body-file \"$STAGING_FINDING_BODY_FILE\" --label review-finding --label needs-validation --label staging-review --label \"{priority}\"")
+rm -f "$STAGING_FINDING_BODY_FILE"
+
+# /issue has no machine-readable return contract — resolve the created issue's number by
+# exact-title search immediately after the call (title embeds ${PR_NUMBER} + summary, unique
+# enough for a reliable single-match lookup). Retry to absorb GitHub Search API indexing lag.
+ISSUE_NUM=""
+for _resolve_attempt in 1 2 3; do
+  ISSUE_NUM=$(gh issue list -R {GH_REPO} --search "in:title \"${STAGING_FINDING_TITLE}\"" --state open --limit 1 --json number --jq '.[0].number // empty')
+  [ -n "$ISSUE_NUM" ] && break
+  sleep 2
+done
 ```
 
 Labels: `review-finding` + `needs-validation` + `staging-review` + priority (`priority:P1` CONFIRMED, `priority:P2` LIKELY, `priority:P3` POSSIBLE).