forgedock 1.1.11 → 1.2.0

package/commands/review-pr.md

@@ -1,7 +1,7 @@
 ---
 description: Context-aware PR review — analyzes what the PR touches, spawns domain-specific agents with project conventions. Supports staging reviews.
-argument-hint: [PR number, URL, "open", or "staging" for feature→main review]
-allowed-tools: Task, Bash, Read, Grep, Glob, WebFetch, Skill
+argument-hint: "[PR number, URL, \"open\", or \"staging\" for feature→main review]"
+allowed-tools: Task, Agent, Bash, Read, Grep, Glob, WebFetch, Skill
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -11,7 +11,7 @@ allowed-tools: Task, Bash, Read, Grep, Glob, WebFetch, Skill
 **Input**: $ARGUMENTS
 
 **NEVER use plan mode (EnterPlanMode)** during review — it breaks execution context.
-**NEVER use the Agent tool** — review-pr dispatches domain agents via `Task` tool only. `Agent` spawns opaque subprocesses that bypass the allowed-tools constraint and cannot post structured findings to the PR. Always use `Task(...)` for review agent launch (Phase 3C).
+**Sub-agent dispatch tool: `Task` preferred, `Agent` is the documented fallback.** review-pr dispatches domain review agents via a sub-agent-spawning tool. Resolve which one is available ONCE per invocation, before Phase 3C, 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; inline self-review is a strictly weaker substitute for an isolated fresh-context reviewer and is not a permitted fallback.
 
 **Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "sonnet" (standard tier); the General Security & Quality reviewer spawned as always-runs Task uses `effort: xhigh` (deep tier). Fallback: `model: "opus"` if rate-limited. User can override with `--model <name>`. Pass model and effort explicitly in every `Task` tool call. Feature gate: pass `effort` only on Claude Code >= 2.1.154. **The domain-review Task agents this file dispatches** (per `commands/review-pr-agents/*.md`) resolve via `model: "{SUBAGENT_MODEL}"` — forge.yaml `agents.subagent_model`, else `agents.default_model`, else `"sonnet"` — not `{DEFAULT_MODEL}` directly.
 
@@ -19,7 +19,7 @@ allowed-tools: Task, Bash, Read, Grep, Glob, WebFetch, Skill
 
 ## HARD RULES — READ BEFORE ANYTHING ELSE
 
-1. **Use `Task(...)` for ALL domain agent launches.** Never substitute `Agent(...)`. Task agents run in a constrained context, post findings to the PR via `gh pr comment`, and their output is structured. Agent spawns opaque subprocesses outside allowed-tools.
+1. **Use the resolved `{DISPATCH_TOOL}(...)` for ALL domain agent launches.** Resolve `{DISPATCH_TOOL}` once, per the **Sub-Agent Dispatch Tool Resolution** section below: `Task` when available, `Agent` as the documented fallback when `Task` is absent from the environment. Every dispatch call in this run uses the same resolved tool — do not mix. Whichever tool is used, each agent MUST run in an isolated, fresh-context sub-agent (not inline in the orchestrator's own context) and post findings to the PR via `gh pr comment` in structured form.
 
 2. **Post the FORGE:REVIEW verdict regardless of finding severity.** A review that completes but posts no `<!-- FORGE:REVIEW -->` comment is invisible to the pipeline. Even a PASS verdict must be posted.
 
@@ -29,16 +29,29 @@ allowed-tools: Task, Bash, Read, Grep, Glob, WebFetch, Skill
 
 5. **`spec-evolution` PRs are NEVER auto-merged.** When a PR carries the `spec-evolution` label (created by `/spec-doctor`), Phase -1 MUST set `AUTO_MERGE=false` and add `needs-human` before any other processing. This cannot be overridden by the caller — the eval gate plus human review are the only permitted merge path. See Phase -1 `spec-evolution guard` block. <!-- Added: forge#1742 -->
 
+## Sub-Agent Dispatch Tool Resolution (MANDATORY — run once, before Phase 3C)
+
+This spec dispatches 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.
+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 domain agent, 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 — inline self-review is strictly weaker than an isolated fresh-context reviewer and is never a substitute for a missing dispatch tool.
+
+**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 (and `review-pr-agents.md` / the `review-pr-agents/*.md` persona files) 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** | Spawns opaque subprocesses outside allowed-tools; bypasses spec workflow; cannot post structured findings |
+| `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; must run phases, not plan them |
 
-If you find yourself about to call `Agent(...)`, stop and use `Task(...)` instead. If you find yourself about to use `EnterPlanMode`, stop and execute the next phase directly.
+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. If you find yourself about to use `EnterPlanMode`, stop and execute the next phase directly.
 
 ## Architecture — How This Command Works
 
@@ -48,11 +61,11 @@ This is the **orchestrator**. It routes to the right review mode, runs automated
 
 | File | What | How to invoke |
 |------|------|---------------|
-| `$FORGE_HOME/commands/review-pr-agents/protocols.md` | Shared review protocols (Evidence-Based + Structured Findings + Input Scoping) | `Read` tool during Phase 3C (always) |
-| `$FORGE_HOME/commands/review-pr-agents/<persona>.md` | Per-persona agent prompt templates (9 files) | `Read` tool during Phase 3C (selected agents only) |
-| `$FORGE_HOME/commands/review-pr-staging.md` | Full staging→main review pipeline | `Skill("review-pr-staging", ...)` during Phase 0 |
+| `${FORGE_HOME:-$REPO_PATH}/commands/review-pr-agents/protocols.md` | Shared review protocols (Evidence-Based + Structured Findings + Input Scoping) | `Read` tool during Phase 3C (always) |
+| `${FORGE_HOME:-$REPO_PATH}/commands/review-pr-agents/<persona>.md` | Per-persona agent prompt templates (9 files) | `Read` tool during Phase 3C (selected agents only) |
+| `${FORGE_HOME:-$REPO_PATH}/commands/review-pr-staging.md` | Full staging→main review pipeline | `Skill("review-pr-staging", ...)` during Phase 0 |
 
-`$FORGE_HOME` defaults to `~/.claude` (the directory where `npx forgedock` symlinks commands). Override by setting `FORGE_HOME` in your environment.
+`$FORGE_HOME` defaults to `~/.claude` (the directory where `npx forgedock` symlinks commands). When unset, every resolution in this file falls back to `$REPO_PATH` (the repo root, from `forge.yaml → paths.root`) rather than degrading to a bare root-anchored path — see the `TEMPLATE_BASE` tiered guard in Phase 3C and the verification-script resolution in Step 2.5B for the actual fallback chains. Never resolve a missing file via a filesystem-wide `find` — see the guardrail in `commands/review-pr-agents/protocols.md`.
 
 **Invocation flow:**
 ```
@@ -580,7 +593,7 @@ Map each changed file to its activation requirements.
 
 ### Step 2.5B: Run Verification
 
-For each changed file, execute the relevant checks using the standalone verification scripts in `$FORGE_HOME/scripts/`. These scripts can also be run independently outside the review context (e.g., from `/quality-gate` or `/work-on` builder steps).
+For each changed file, execute the relevant checks using the standalone verification scripts in `${FORGE_HOME:-$SCRIPTS_HOME}/scripts/`. These scripts can also be run independently outside the review context (e.g., from `/quality-gate` or `/work-on` builder steps).
 
 **Platform note**: The verify-*.sh scripts require bash and standard POSIX tools. On Windows without bash (Git Bash / WSL / MSYS2), these checks are skipped with an explicit message — the review continues without them.
 
@@ -588,6 +601,20 @@ For each changed file, execute the relevant checks using the standalone verifica
 CHANGED_FILES=$(gh pr diff $ARGUMENTS --name-only)
 REPO_ROOT="."  # Assumes cwd is the repo root
 
+# Resolve the verify-*.sh scripts source directory with the same deterministic
+# fallback as the Phase 3C TEMPLATE_BASE guard: $FORGE_HOME first (the installed
+# ForgeDock location), then this repo's own root (forge.yaml -> paths.root, or
+# git top-level). A bare/unset $FORGE_HOME must never be used directly in a path —
+# that degrades to a root-anchored path (/scripts/verify-*.sh) and silently skips
+# every check below. Never fall back to a filesystem-wide `find`.
+# <!-- Added: forge#2035 -->
+if [ -n "$FORGE_HOME" ] && [ -f "$FORGE_HOME/scripts/verify-route-registration.sh" ]; then
+    SCRIPTS_HOME="$FORGE_HOME"
+else
+    FORGE_YAML="${FORGE_CONFIG:-$(git rev-parse --show-toplevel 2>/dev/null)/forge.yaml}"
+    SCRIPTS_HOME=$(yq '.paths.root' "$FORGE_YAML" 2>/dev/null || git rev-parse --show-toplevel 2>/dev/null || pwd)
+fi
+
 # --- Platform / bash capability guard ---
 # The verify-*.sh scripts require bash. Detect availability before invoking.
 # On Windows without Git Bash/WSL, skip gracefully rather than crash.
@@ -627,11 +654,11 @@ if [ "$BASH_AVAILABLE" = "true" ]; then
         [ -n "$_API_MIDDLEWARE" ] && export FORGE_API_MIDDLEWARE_DIR="$_API_MIDDLEWARE"
     fi
     echo "=== Running: verify-route-registration.sh ==="
-    bash "$FORGE_HOME/scripts/verify-route-registration.sh" "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
+    bash "$SCRIPTS_HOME/scripts/verify-route-registration.sh" "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
 
     # 2. Environment variable wiring (checks .env.example, docker-compose, env_validation, SOPS mapping)
     echo "=== Running: verify-env-vars.sh ==="
-    bash "$FORGE_HOME/scripts/verify-env-vars.sh" "$DIFF_TMP" "$REPO_ROOT" || true
+    bash "$SCRIPTS_HOME/scripts/verify-env-vars.sh" "$DIFF_TMP" "$REPO_ROOT" || true
 
     # 3. Host headers in shell scripts + client-side proxy bypass check
     # Read project-specific internal service patterns from forge.yaml (if present)
@@ -645,11 +672,11 @@ if [ "$BASH_AVAILABLE" = "true" ]; then
     fi
     export FORGE_INTERNAL_PATTERNS
     echo "=== Running: verify-host-headers.sh ==="
-    bash "$FORGE_HOME/scripts/verify-host-headers.sh" "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
+    bash "$SCRIPTS_HOME/scripts/verify-host-headers.sh" "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
 
     # 4. SOPS deploy chain (ENV_MAPPING consistency, deploy path drift, hotfix sync)
     echo "=== Running: verify-sops-chain.sh ==="
-    bash "$FORGE_HOME/scripts/verify-sops-chain.sh" "$DIFF_TMP" "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
+    bash "$SCRIPTS_HOME/scripts/verify-sops-chain.sh" "$DIFF_TMP" "$CHANGED_FILES_TMP" "$REPO_ROOT" || true
 
     # Cleanup temp files
     rm -f "$CHANGED_FILES_TMP" "$DIFF_TMP"
@@ -1485,9 +1512,9 @@ The `protocols.md` file contains the Evidence-Based Review Protocol, Structured
 6. Substitute code index slice: `[INDEX_SLICE]` → the matching `$INDEX_SLICE_{DOMAIN}` variable for this agent (e.g., `$INDEX_SLICE_AUTH` for the auth agent). Agents MUST query index data first; fall back to grep only when index slice is empty or unavailable.
 7. Substitute per-agent diff slice: `[DOMAIN_DIFF_SLICE]` → the matching `$DIFF_SLICE_*` variable (e.g., `$DIFF_SLICE_AUTH` for the auth agent, `$DIFF_SLICE_SECURITY` for the security agent). This replaces any `gh pr diff [PR_NUMBER]` call inside the agent template — the agent works from the pre-computed slice, not the full changeset.
 8. If Phase 2.5 found broken assumptions, append them to the agent's prompt as "Pre-found integration issues to verify"
-9. Launch via `Task` tool with `model: "{SUBAGENT_MODEL}"` (forge.yaml `agents.subagent_model`, else `agents.default_model`, else `"sonnet"`; fallback `"opus"` if rate-limited)
+9. Launch via the resolved `{DISPATCH_TOOL}` (see Sub-Agent Dispatch Tool Resolution above) with `model: "{SUBAGENT_MODEL}"` (forge.yaml `agents.subagent_model`, else `agents.default_model`, else `"sonnet"`; fallback `"opus"` if rate-limited)
 
-**CRITICAL**: Launch ALL selected agents in a SINGLE message using multiple Task tool calls. Each agent posts findings directly to the PR via `gh pr comment`.
+**CRITICAL**: Launch ALL selected agents in a SINGLE message using multiple `{DISPATCH_TOOL}` calls. Each agent posts findings directly to the PR via `gh pr comment`.
 
 #### Domain Diff Slicing
 
@@ -1629,7 +1656,7 @@ if [ "$DEDUP_EXIT" -eq 1 ]; then
   # Add a comment on the existing issue referencing this recurrence in PR #${PR_NUMBER}
 elif [ "$DEDUP_EXIT" -eq 2 ]; then
   echo "DEDUP: Usage error — $DEDUP_RESULT"
-  # Skip this finding — do NOT fall through to gh issue create on a usage error
+  # Skip this finding — do NOT fall through to issue creation on a usage error
 fi
 ```
 
@@ -1688,13 +1715,17 @@ fi
 - Open `review-finding` issue at same file with similar title (3+ shared keywords) → **skip** (likely same finding despite line drift)
 - Closed `review-finding` at same file within ±5 lines → create with regression warning, elevate to `priority:P1`
 
-**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") — this preserves the bespoke line-range/title dedup above as a precise pre-check, while `/issue`'s own Phase 2D dedup runs as a coarser second pass:
 ```bash
-ISSUE_NUM=$(gh issue create \
-  --title "fix: [summary] (review finding — PR #${PR_NUMBER})" \
-  --label "review-finding,needs-validation,{priority}" \
-  ${MILESTONE_FLAG} \
-  --body "$(cat <<'ISSUE_EOF'
+FINDING_ISSUE_TITLE="fix: [summary] (review finding — PR #${PR_NUMBER})"
+# Defense-in-depth: /issue's arg tokenizer (commands/issue.md Argument Parsing,
+# 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.
+FINDING_ISSUE_TITLE=$(printf '%s' "$FINDING_ISSUE_TITLE" | tr '`' "'" | sed 's/\$(/$ (/g')
+FINDING_ISSUE_BODY_FILE=$(mktemp)
+cat <<'ISSUE_EOF' > "$FINDING_ISSUE_BODY_FILE"
 ## Problem
 
 [One sentence: what bug or issue was found. Where it occurs (`file:line`) and what it causes.]
@@ -1745,7 +1776,21 @@ Files that need changes:
 - [ ] Reproduce or construct proof-of-concept
 [BATCHABLE_ANNOTATION]
 ISSUE_EOF
-)" --json number --jq '.number')
+
+# --label is repeatable (not comma-joined) per the /issue programmatic contract.
+Skill(skill="issue", args="--title \"$FINDING_ISSUE_TITLE\" --body-file \"$FINDING_ISSUE_BODY_FILE\" --label review-finding --label needs-validation --label \"{priority}\" ${MILESTONE_FLAG}")
+rm -f "$FINDING_ISSUE_BODY_FILE"
+
+# /issue has no machine-readable return contract (it's a user-facing command, not a work-on
+# subcommand) — resolve the created issue's number by exact-title search immediately after
+# the call. The title embeds ${PR_NUMBER} and the finding summary, making it 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 ${REPO} --search "in:title \"${FINDING_ISSUE_TITLE}\"" --state open --limit 1 --json number --jq '.[0].number // empty')
+  [ -n "$ISSUE_NUM" ] && break
+  sleep 2
+done
 ```
 
 Labels: `review-finding` + `needs-validation` + priority (`priority:P1` CONFIRMED, `priority:P2` LIKELY, `priority:P3` POSSIBLE).
@@ -1888,7 +1933,7 @@ ATTRIBUTION_FOOTER_LINE=""
 if [ "$ATTRIBUTION_PR_FOOTER" = "true" ]; then
   ATTRIBUTION_FOOTER_LINE="
 ---
-> Orchestrated with [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) — state, scheduling, review, and memory on GitHub."
+> ⚒️ Orchestrated with [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) — state, scheduling, review, and memory on GitHub."
 fi
 
 # Build trust annotation line for verdict body — always included so the decision is auditable.

package/commands/rollback.md

@@ -1,6 +1,6 @@
 ---
 description: Create a revert PR to roll back a shipped feature or fix that caused a production incident
-argument-hint: [PR number to revert, or "last" for most recent deploy]
+argument-hint: "[PR number to revert, or \"last\" for most recent deploy]"
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -213,9 +213,10 @@ fi
 ### Step 4B: Create a follow-up issue
 
 ```bash
-gh issue create --title "fix: {original_title} (reverted — needs new approach)" \
-  --label "bug,priority:P1" \
-  --body "$(cat <<'BODY_EOF'
+FOLLOWUP_TITLE="fix: {original_title} (reverted — needs new approach)"
+FOLLOWUP_BODY_TMPFILE=$(mktemp)
+trap 'rm -f "$FOLLOWUP_BODY_TMPFILE"' EXIT
+cat > "$FOLLOWUP_BODY_TMPFILE" <<'BODY_EOF'
 ## Problem
 
 PR #{PR_NUMBER} ({original_title}) was merged and deployed but caused a production incident. It was reverted in PR #{REVERT_PR_NUMBER}. The original fix needs to be re-implemented with a different approach that avoids the production issue.
@@ -249,7 +250,16 @@ Files that need changes (same as original fix, different approach):
 
 Regression of #{ORIGINAL_ISSUE}. Should investigate why the original approach caused issues before implementing.
 BODY_EOF
-)"
+# Route through the /issue create-hook (canonical dedup + body validation) instead of a raw
+# `gh issue create`.
+Skill(skill="issue", args="--title \"$FOLLOWUP_TITLE\" --body-file \"$FOLLOWUP_BODY_TMPFILE\" --label bug --label \"priority:P1\"")
+rm -f "$FOLLOWUP_BODY_TMPFILE"
+trap - EXIT
+FOLLOWUP_ISSUE_NUMBER=$(gh issue list \
+  --state open \
+  --search "$FOLLOWUP_TITLE" \
+  --json number,title \
+  --jq --arg t "$FOLLOWUP_TITLE" '.[] | select(.title == $t) | .number' 2>/dev/null | head -1)
 ```
 
 ### Step 4C: Clean up worktree

package/commands/security-audit.md

@@ -1,6 +1,6 @@
 ---
 description: Periodic security posture audit — runs a scripted 4-phase checklist against repo files (not diffs), creates GitHub issues for confirmed findings
-argument-hint: [--repo <prefix>] [--phase 1|2|3|4|all] [--dry-run]
+argument-hint: "[--repo <prefix>] [--phase 1|2|3|4|all] [--dry-run]"
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -515,20 +515,18 @@ gh label create "priority:P3" --color "C2E0C6" --description "Low priority — m
 
 ### 5C: Create GitHub issues for CONFIRMED findings
 
-For each CONFIRMED finding (not REVIEW-only), create an issue:
+For each CONFIRMED finding (not REVIEW-only), create an issue — routed 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 -R "{GH_REPO}" \
-  --title "{ISSUE_TITLE}" \
-  --label "security,audit-finding,{SEVERITY}" \
-  --body "$(cat <<'ISSUE_EOF'
+SECURITY_BODY_FILE=$(mktemp)
+cat > "$SECURITY_BODY_FILE" <<'ISSUE_EOF'
 ## Problem
 
 {2-3 sentences describing the finding, its location, and exploitation path.}
 
 ## Evidence
 
-**File**: \`{FILE}\`
+**File**: `{FILE}`
 **Line**: {LINE}
 **Finding**: {GREP_OUTPUT}
 
@@ -538,23 +536,28 @@ gh issue create -R "{GH_REPO}" \
 
 ## Affected Files
 
-1. \`{FILE}\` — {what needs to change}
+1. `{FILE}` — {what needs to change}
 
 ## Acceptance Criteria
 
 - [ ] {Specific remediation step}
-- [ ] Verified by re-running \`/security-audit\` after fix
+- [ ] Verified by re-running `/security-audit` after fix
 
 ## Context
 
 **Audited at**: {TIMESTAMP}
 **Audit phase**: {PHASE}
 **Severity**: {SEVERITY}
-**Source**: \`/security-audit\` run on \`{GH_REPO}\`
+**Source**: `/security-audit` run on `{GH_REPO}`
 ISSUE_EOF
-)"
 ```
 
+```
+Skill(skill="issue", args="--title \"{ISSUE_TITLE}\" --body-file \"$SECURITY_BODY_FILE\" --label \"security\" --label \"audit-finding\" --label \"{SEVERITY}\"")
+```
+
+`security`, `audit-finding`, and `{SEVERITY}` are each passed as their own `--label` flag — `/issue`'s programmatic mode does not comma-split a single `--label` value. Note: `/issue` resolves the target repo from `forge.yaml → project.owner/repo` (or the satellite-prefix table), not from a caller-supplied `-R`/`--repo` flag — this is correct for the common case where `{GH_REPO}` matches `forge.yaml`'s project repo.
+
 ### 5D: Post audit summary comment (if invoked from a GitHub issue context)
 
 If this command was invoked from within a `/work-on` context or with an issue reference:

package/commands/signal-planner.md

@@ -1,6 +1,6 @@
 ---
 description: Closed-loop autonomy — convert a production/analytics/incident signal into a dependency-ordered issue DAG, execute via /orchestrate, then verify the originating signal is resolved. Event-driven companion to /autopilot.
-argument-hint: [--signal '<json>' | --metric '<name> <threshold>' | --incident <issue#> | --geo | --dry-run | --max-issues N]
+argument-hint: "[--signal '<json>' | --metric '<name> <threshold>' | --incident <issue#> | --geo | --dry-run | --max-issues N]"
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -224,10 +224,10 @@ Detect cycles — if a cycle exists, break it by demoting the lower-priority uni
 Post the DAG to a tracker issue on GitHub. First, create the tracker issue:
 
 ```bash
-TRACKER_ISSUE=$(gh issue create -R {GH_REPO} \
-  --title "signal-planner: DAG tracker for {SIGNAL.name}" \
-  --label "signal-planner,priority:{SIGNAL.severity}" \
-  --body "$(cat <<'TRACKER_EOF'
+TRACKER_TITLE="signal-planner: DAG tracker for {SIGNAL.name}"
+TRACKER_BODY_TMPFILE=$(mktemp)
+trap 'rm -f "$TRACKER_BODY_TMPFILE"' EXIT
+cat > "$TRACKER_BODY_TMPFILE" <<'TRACKER_EOF'
 ## Signal
 
 **Type**: {SIGNAL.type}
@@ -247,7 +247,18 @@ This tracker was created by \`/signal-planner\`. The dependency DAG below repres
 - [ ] All DAG issues merged
 - [ ] Originating signal verified resolved (FORGE:SIGNAL_RESOLVED posted)
 TRACKER_EOF
-)" --json number --jq '.number')
+# Route through the /issue create-hook (canonical dedup + body validation) instead of a raw
+# `gh issue create`. This body uses "## Acceptance" rather than the mandatory "## Acceptance
+# Criteria"/"## Affected Files"/"## Problem" sections — /issue's Phase 3F will non-blockingly
+# append placeholder mandatory sections; this is expected for a coordination tracker issue.
+Skill(skill="issue", args="--title \"$TRACKER_TITLE\" --body-file \"$TRACKER_BODY_TMPFILE\" --label signal-planner --label \"priority:{SIGNAL.severity}\"")
+rm -f "$TRACKER_BODY_TMPFILE"
+trap - EXIT
+TRACKER_ISSUE=$(gh issue list -R {GH_REPO} \
+  --state open \
+  --search "$TRACKER_TITLE" \
+  --json number,title \
+  --jq --arg t "$TRACKER_TITLE" '.[] | select(.title == $t) | .number' 2>/dev/null | head -1)
 ```
 
 Then post the `FORGE:PLAN_DAG` comment:
@@ -312,10 +323,10 @@ If governor would be breached, **hard fail** — do not create any issues, do no
 For each work unit with `existing == null`, create a GitHub issue:
 
 ```bash
-ISSUE_NUM=$(gh issue create -R {GH_REPO} \
-  --title "{work_unit.title}" \
-  --label "priority:{work_unit.priority},{work_unit.type}" \
-  --body "$(cat <<'ISSUE_EOF'
+WORK_UNIT_TITLE="{work_unit.title}"
+WORK_UNIT_BODY_TMPFILE=$(mktemp)
+trap 'rm -f "$WORK_UNIT_BODY_TMPFILE"' EXIT
+cat > "$WORK_UNIT_BODY_TMPFILE" <<'ISSUE_EOF'
 ## Problem
 
 {work_unit.rationale — why this is needed to resolve the originating signal}
@@ -341,10 +352,19 @@ Signal context: {relevant subset of SIGNAL.context for this work unit}
 ---
 *Created by \`/signal-planner\` on $(date -u +%Y-%m-%dT%H:%M:%SZ). Will be investigated before any fix is applied.*
 ISSUE_EOF
-)" --json number --jq '.number')
+# Route through the /issue create-hook (canonical dedup + body validation) instead of a raw
+# `gh issue create`.
+Skill(skill="issue", args="--title \"$WORK_UNIT_TITLE\" --body-file \"$WORK_UNIT_BODY_TMPFILE\" --label \"priority:{work_unit.priority}\" --label \"{work_unit.type}\"")
+rm -f "$WORK_UNIT_BODY_TMPFILE"
+trap - EXIT
+ISSUE_NUM=$(gh issue list -R {GH_REPO} \
+  --state open \
+  --search "$WORK_UNIT_TITLE" \
+  --json number,title \
+  --jq --arg t "$WORK_UNIT_TITLE" '.[] | select(.title == $t) | .number' 2>/dev/null | head -1)
 ```
 
-Record each created issue number and update the DAG table in the tracker issue.
+Record each created issue number and update the DAG table in the tracker issue. If `/issue` deduped this work unit against an existing open issue, `ISSUE_NUM` will come back empty — fall back to `work_unit.existing` (if already resolved during Phase 2) or treat the work unit as already covered and skip re-creation.
 
 ### 3C: Compile final DAG issue list
 

package/commands/spec-doctor.md

@@ -1,6 +1,6 @@
 ---
 description: Evidence-backed spec evolution — reads finding concentration for a spec file, drafts a spec diff, opens a spec-evolution PR with per-change citations
-argument-hint: [spec file path | "auto"]
+argument-hint: "[spec file path | \"auto\"]"
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/sync-ecosystem.md

@@ -1,6 +1,6 @@
 ---
 description: Detect API changes, sync satellite repos, and publish releases
-argument-hint: [check | auto | status | publish | PR-number]
+argument-hint: "[check | auto | status | publish | PR-number]"
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -218,10 +218,16 @@ Create issues in the affected repos:
 
 ```bash
 # For satellite repos (separate GitHub repos):
-gh issue create -R {TARGET_REPO} \
-  --title "feat(sync): {description of what API change needs to be reflected}" \
-  --label "feature,priority:P2" \
-  --body "$(cat <<'BODY_EOF'
+#
+# /issue resolves its target repo in Phase 1A from a `{prefix}:` token at the start of the
+# free-text input, not from an explicit -R override — its multi-repo prefix table is keyed
+# off forge.yaml → repos.satellites (the same registry this file already iterates). Prepend
+# the satellite's configured {COMPONENT} (= satellites[].prefix) to the title so /issue routes
+# to {TARGET_REPO} correctly instead of the default project repo.
+SYNC_TITLE="feat(sync): {description of what API change needs to be reflected}"
+SYNC_BODY_TMPFILE=$(mktemp)
+trap 'rm -f "$SYNC_BODY_TMPFILE"' EXIT
+cat > "$SYNC_BODY_TMPFILE" <<'BODY_EOF'
 ## Problem
 
 {1-3 sentences: what API or schema change in the upstream repo needs to be reflected in this satellite repo. What will break or be missing if this sync is not done.}
@@ -252,13 +258,41 @@ Files that need changes:
 
 {If applicable: describe the new API shape with an example}
 BODY_EOF
-)"
+# Route through the /issue create-hook (canonical dedup + body validation) instead of a raw
+# `gh issue create`. Prefixing the title with "{COMPONENT}: " lets /issue's Phase 1A resolve
+# the satellite repo ({TARGET_REPO}) from forge.yaml → repos.satellites, matching how a human
+# would invoke /issue for the same satellite (e.g. "mcp: add list_schemas tool"). The prefix
+# is stripped by /issue's own routing — it does not become part of the created issue title.
+Skill(skill="issue", args="\"{COMPONENT}: $SYNC_TITLE\" --title \"$SYNC_TITLE\" --body-file \"$SYNC_BODY_TMPFILE\" --label feature --label \"priority:P2\"")
+rm -f "$SYNC_BODY_TMPFILE"
+trap - EXIT
+SYNC_ISSUE_NUMBER=$(gh issue list -R {TARGET_REPO} \
+  --state open \
+  --search "$SYNC_TITLE" \
+  --json number,title \
+  --jq --arg t "$SYNC_TITLE" '.[] | select(.title == $t) | .number' 2>/dev/null | head -1)
+
+# Safety net: the "{COMPONENT}: " prefix trick above is not a documented part of the
+# Programmatic Invocation Contract (issue.md has no --repo/-R flag for programmatic mode) —
+# if /issue's Phase 1A did not honor the prefix and created the issue in the default project
+# repo instead of {TARGET_REPO}, the lookup above returns empty and this would otherwise be
+# silently treated as "deduped by /issue" further down. Distinguish the two cases explicitly.
+if [ -z "$SYNC_ISSUE_NUMBER" ]; then
+  MISROUTED_CHECK=$(gh issue list \
+    --state open \
+    --search "$SYNC_TITLE" \
+    --json number,title \
+    --jq --arg t "$SYNC_TITLE" '.[] | select(.title == $t) | .number' 2>/dev/null | head -1)
+  if [ -n "$MISROUTED_CHECK" ]; then
+    echo "WARNING: '/issue' created #$MISROUTED_CHECK in the default project repo instead of {TARGET_REPO} — the '{COMPONENT}:' prefix routing did not take effect. Move/re-file the issue in {TARGET_REPO} manually."
+  fi
+fi
 
 # For monorepo issues (SDKs, packages inside a single repo):
-gh issue create \
-  --title "feat(sync): {description of what API change needs to be reflected}" \
-  --label "feature,priority:P2" \
-  --body "$(cat <<'BODY_EOF'
+MONOREPO_SYNC_TITLE="feat(sync): {description of what API change needs to be reflected}"
+MONOREPO_SYNC_BODY_TMPFILE=$(mktemp)
+trap 'rm -f "$MONOREPO_SYNC_BODY_TMPFILE"' EXIT
+cat > "$MONOREPO_SYNC_BODY_TMPFILE" <<'BODY_EOF'
 ## Problem
 
 {1-3 sentences: what API or schema change needs to be reflected in this SDK or package. What will be out of sync if not updated.}
@@ -285,7 +319,16 @@ Files that need changes:
 **Change**: {description of upstream API change}
 **Detected by**: `/sync-ecosystem`
 BODY_EOF
-)"
+# Route through the /issue create-hook (canonical dedup + body validation) instead of a raw
+# `gh issue create`. No prefix needed — this targets the default/monorepo repo.
+Skill(skill="issue", args="--title \"$MONOREPO_SYNC_TITLE\" --body-file \"$MONOREPO_SYNC_BODY_TMPFILE\" --label feature --label \"priority:P2\"")
+rm -f "$MONOREPO_SYNC_BODY_TMPFILE"
+trap - EXIT
+MONOREPO_SYNC_ISSUE_NUMBER=$(gh issue list \
+  --state open \
+  --search "$MONOREPO_SYNC_TITLE" \
+  --json number,title \
+  --jq --arg t "$MONOREPO_SYNC_TITLE" '.[] | select(.title == $t) | .number' 2>/dev/null | head -1)
 ```
 
 ### Add sync issues to Project board

package/commands/test-gate.md

@@ -1,6 +1,6 @@
 ---
 description: Deterministic deploy-gate — verify a staging→main bundle's acceptance criteria against running code before deploy
-argument-hint: [--prs "<N1 N2 ...>"] [--base <branch>]
+argument-hint: "[--prs \"<N1 N2 ...>\"] [--base <branch>]"
 allowed-tools: Task, Bash, Read, Grep, Glob
 install: extras
 ---
@@ -520,10 +520,16 @@ else
       SOURCE_ISSUES_LIST="${SOURCE_ISSUES_LIST}\n- #${issue_num}"
     done
 
-    ISSUE_NUM=$(gh issue create ${GH_FLAG} \
-      --title "fix: test-gate FAIL — cluster '${cluster}' broken by staging→${DEFAULT_BRANCH} bundle" \
-      --label "test-failure,priority:P1" \
-      --body "$(cat <<ISSUE_EOF
+    TESTGATE_FAIL_TITLE="fix: test-gate FAIL — cluster '${cluster}' broken by staging→${DEFAULT_BRANCH} bundle"
+    # 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.
+    # ${cluster} is config-controlled (forge.yaml verification.integration_tests), but sanitize
+    # unconditionally for defense-in-depth consistency with the other converted call sites.
+    TESTGATE_FAIL_TITLE=$(printf '%s' "$TESTGATE_FAIL_TITLE" | tr '`' "'" | sed 's/\$(/$ (/g')
+    TESTGATE_FAIL_BODY_FILE=$(mktemp)
+    cat <<ISSUE_EOF > "$TESTGATE_FAIL_BODY_FILE"
 ## Problem
 
 The \`/test-gate\` command detected a runtime failure in cluster \`${cluster}\` that was introduced by the staging→${DEFAULT_BRANCH} bundle. The failure did not exist on \`${BASE_BRANCH}\` (baseline PASS), confirming it is batch-introduced, not pre-existing.
@@ -570,7 +576,21 @@ $(echo -e "$SOURCE_ISSUES_LIST")
    $(yq ".verification.integration_tests[] | select(.cluster == \"${cluster}\") | .command" "$CONFIG_FILE")
    \`\`\`
 ISSUE_EOF
-)" --json number --jq '.number' 2>/dev/null || echo "FAILED")
+
+    # Route through the /issue create-hook's programmatic invocation contract (see
+    # commands/issue.md § "Programmatic Invocation Contract") instead of the raw issue-creation call.
+    Skill(skill="issue", args="--title \"$TESTGATE_FAIL_TITLE\" --body-file \"$TESTGATE_FAIL_BODY_FILE\" --label test-failure --label priority:P1")
+    rm -f "$TESTGATE_FAIL_BODY_FILE"
+
+    # /issue has no machine-readable return contract — resolve the created issue's number by
+    # exact-title search immediately after the call. Retry to absorb GitHub Search API indexing lag.
+    ISSUE_NUM=""
+    for _resolve_attempt in 1 2 3; do
+      ISSUE_NUM=$(gh issue list ${GH_FLAG} --search "in:title \"${TESTGATE_FAIL_TITLE}\"" --state open --limit 1 --json number --jq '.[0].number // empty' 2>/dev/null || echo "")
+      [ -n "$ISSUE_NUM" ] && break
+      sleep 2
+    done
+    [ -z "$ISSUE_NUM" ] && ISSUE_NUM="FAILED"
 
     if [ "$ISSUE_NUM" != "FAILED" ] && [ -n "$ISSUE_NUM" ]; then
       echo "Filed test-failure issue #${ISSUE_NUM} for cluster '${cluster}'"
@@ -786,10 +806,14 @@ if [ "${UNCOVERED_COUNT}" -gt 0 ]; then
       continue
     fi
 
-    GAP_ISSUE_NUM=$(gh issue create ${GH_FLAG} \
-      --title "fix: test-gap — uncovered criterion in issue #${GAP_ISSUE} (${GAP_TYPE})" \
-      --label "test-gap" \
-      --body "$(cat <<TGAP_EOF
+    TESTGAP_TITLE="fix: test-gap — uncovered criterion in issue #${GAP_ISSUE} (${GAP_TYPE})"
+    # 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.
+    TESTGAP_TITLE=$(printf '%s' "$TESTGAP_TITLE" | tr '`' "'" | sed 's/\$(/$ (/g')
+    TESTGAP_BODY_FILE=$(mktemp)
+    cat <<TGAP_EOF > "$TESTGAP_BODY_FILE"
 ## Problem
 
 The \`/test-gate\` criteria-adequacy check (Phase 6) found a runtime-testable acceptance criterion in issue #${GAP_ISSUE} that is not covered by any configured test cluster. Coverage gaps cannot produce a clean PASS verdict — this criterion must be covered before the staging→${DEFAULT_BRANCH} bundle can pass the deploy gate.
@@ -822,7 +846,21 @@ Files to be identified during investigation. Start with the test suite for the \
 ${GAP_CRITERION}
 \`\`\`
 TGAP_EOF
-)" --json number --jq '.number' 2>/dev/null || echo "FAILED")
+
+    # Route through the /issue create-hook's programmatic invocation contract (see
+    # commands/issue.md § "Programmatic Invocation Contract") instead of the raw issue-creation call.
+    Skill(skill="issue", args="--title \"$TESTGAP_TITLE\" --body-file \"$TESTGAP_BODY_FILE\" --label test-gap")
+    rm -f "$TESTGAP_BODY_FILE"
+
+    # /issue has no machine-readable return contract — resolve the created issue's number by
+    # exact-title search immediately after the call. Retry to absorb GitHub Search API indexing lag.
+    GAP_ISSUE_NUM=""
+    for _resolve_attempt in 1 2 3; do
+      GAP_ISSUE_NUM=$(gh issue list ${GH_FLAG} --search "in:title \"${TESTGAP_TITLE}\"" --state open --limit 1 --json number --jq '.[0].number // empty' 2>/dev/null || echo "")
+      [ -n "$GAP_ISSUE_NUM" ] && break
+      sleep 2
+    done
+    [ -z "$GAP_ISSUE_NUM" ] && GAP_ISSUE_NUM="FAILED"
 
     if [ "$GAP_ISSUE_NUM" != "FAILED" ] && [ -n "$GAP_ISSUE_NUM" ]; then
       echo "Filed test-gap issue #${GAP_ISSUE_NUM} for uncovered criterion in #${GAP_ISSUE} (${GAP_TYPE})"