forgedock 1.1.11 → 1.3.0

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

@@ -0,0 +1,179 @@
+---
+install: internal
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# Agent: Spec/CLI Auditor
+
+> Read `review-pr-agents/protocols.md` for the Evidence-Based Review Protocol, Structured Findings Protocol, Per-Agent Input Scoping rules, and Tool-Result Truncation Discipline that all agents must follow.
+
+
+
+**Trigger**: SPEC_CLI domain detected (PR touches `commands/**` or `bin/**`)
+**Type**: `security-exploit-auditor` | **Model**: `sonnet`
+
+**Prompt template:**
+```
+You are auditing PR #[PR_NUMBER] for spec-as-code and CLI correctness in [PROJECT_NAME].
+
+## Context
+- PR title: [TITLE]
+- Files changed: [FILE_LIST]
+[PROJECT_CONTEXT]
+
+## Spec/CLI Conventions
+
+[DOMAIN_CONTEXT]
+
+If no spec/CLI context is configured above, derive conventions from the changed files: read sibling `.mjs` files for the established exec pattern and sibling `commands/*.md` files for the established side-effect gating pattern.
+
+## Why This Agent Exists
+`commands/**` (the pipeline's spec-as-code prompts) and `bin/**` (the Node CLI) ARE the product — every `commands/*.md` file is executed as instructions by an AI agent on every customer repo, and every `bin/*.mjs` file runs with the user's local `gh` credentials. The General Security agent's checklist is Python/FastAPI/Docker-shaped and does not cover exec/spawn injection in `.mjs`, `gh` write/egress side effects, or command-spec side-effect changes — this agent exists to close exactly that gap (ref: forge#1586, forge#1587, both of which reached staging via PR #1575 uncaught by any automated persona).
+
+## Step 1: Read the Diff
+
+The diff is pre-supplied as `[DOMAIN_DIFF_SLICE]` and is capped at ~100K chars. Do NOT re-fetch the full diff — use what was provided.
+
+```bash
+gh pr diff [PR_NUMBER] --name-only
+# Use the pre-supplied diff: [DOMAIN_DIFF_SLICE]
+```
+
+Build the two file subsets this agent scans (note: `gh pr diff` does NOT accept path arguments — always filter the name-only list with grep):
+
+```bash
+CLI_FILES=$(gh pr diff [PR_NUMBER] --name-only | grep -E '^bin/.*\.(mjs|js|ts)$')
+SPEC_FILES=$(gh pr diff [PR_NUMBER] --name-only | grep -E '^commands/.*\.md$')
+```
+
+## Step 2: Shell-String Exec/Spawn Interpolation (CLI files)
+
+Node's `child_process.exec()`/`execSync()` run their argument through `/bin/sh -c` (or `cmd.exe` on Windows) — any interpolated string becomes shell-interpretable. `execFile()`/`execFileSync()`/`spawn()` with an args array never invoke a shell and are safe by construction.
+
+Scan the added lines of the pre-supplied diff for exec calls with template-string or concatenated arguments (attribute each hit to its file via the nearest preceding `diff --git` header):
+
+```bash
+# Added lines with exec/execSync taking a template string or concatenation
+echo "[DOMAIN_DIFF_SLICE]" | grep -E '^\+' | grep -E '\bexecSync?\(`|\bexecSync?\([^)]*\+' | grep -v '^\+\+\+'
+```
+
+For each hit, read the surrounding file (from `$CLI_FILES`) with the Read tool to trace the interpolated variable to its source. Classify:
+- `execSync(\`gh ... ${variable} ...\`)` or `execSync("cmd " + variable)`: **CONFIRMED HIGH** if `variable` derives from ANY external/config-controlled source — a repo-local `forge.yaml` field, CLI argv, an environment variable, or a `gh api` response body. This is the exact shape of forge#1586 (`ghJson()` in `bin/report.mjs` interpolated `forge.yaml`-derived `owner`/`repo` into an `execSync` string parsed by a hand-rolled YAML reader that did not reject `$(...)`, backticks, `;`, or `&`).
+- `execFileSync("gh", [...args])` or `spawn(cmd, [args], {shell: false})`: **OK** — this is the safe pattern already used elsewhere in this codebase (e.g. `watch()` in `bin/forgedock.mjs`).
+- `execSync`/`exec` called with a **fully static string literal** (no interpolation, no concatenation): **OK** — no injectable surface.
+
+**Do not stop at the first call site** — scan every `exec(`/`execSync(` occurrence in the diff, not just the one nearest an obviously-tainted variable. A file can fix one call site and leave a sibling one unconverted.
+
+## Step 3: `gh` Write/Egress Side Effects (all files)
+
+Any new or modified `gh` invocation that **writes** (mutates GitHub state) or **publishes** (makes something world-readable) is a side-effect change and must be justified by the PR's stated purpose.
+
+```bash
+# gh write/publish operations in added lines
+echo "[DOMAIN_DIFF_SLICE]" | grep -E '^\+' | grep -E \
+  'gh (gist create|pr merge|pr close|issue create|issue close|issue comment|repo edit|label create|release create|workflow run)' | \
+  grep -v '^\+\+\+'
+
+# Newly-added --public / visibility flags
+echo "[DOMAIN_DIFF_SLICE]" | grep -E '^\+' | grep -E '\-\-public\b|visibility.*public|make.*public' | grep -v '^\+\+\+'
+```
+
+For each hit:
+- A new `gh gist create ... --public` (or any new default-to-public visibility change) that writes issue/PR content, root-cause analysis, or file paths: **CONFIRMED HIGH** — this is the exact shape of forge#1587 (`commands/work-on/close.md` published the pipeline's per-issue memory index — titles, root causes, affected file paths — to a world-readable Gist; a secret gist is sufficient since the read side already authenticates via `gh`).
+- A new `gh pr merge`, `gh issue close`, or `gh label` mutation added to a command spec (`commands/*.md`) that was not previously present: **LIKELY MEDIUM** — verify the new destructive/mutating step is gated behind the same preconditions (auto-merge flag, terminal-state check, etc.) as sibling mutations in the same file. An ungated new mutation can fire on a code path the spec author didn't intend.
+- Read-only `gh` calls (`gh pr view`, `gh issue list`, `gh api ... GET`) or a write call gated behind an explicit `--auto-merge`/confirmation flag already present in the spec: **OK**.
+
+## Step 4: Command-Spec Side-Effect Changes (spec files)
+
+`commands/*.md` files are prompts, but they are executable specifications — they instruct an autonomous agent to run shell/`gh` commands with real side effects on every repo that installs ForgeDock. Review diffs to these files the same way you would review a code diff to a function that performs the same operations.
+
+```bash
+# Added lines in the pre-supplied diff that introduce/alter gh, git-destructive, delete, or network commands
+echo "[DOMAIN_DIFF_SLICE]" | grep -E '^\+' | grep -E '\bgh \w|\bgit (push|reset|clean|rm)|\brm -rf|\bcurl\b|\bwget\b' | grep -v '^\+\+\+'
+```
+
+Attribute each hit to its `commands/*.md` file via the nearest preceding `diff --git` header, then ask: "Does this new/changed line cause a write, delete, publish, or network egress that the PREVIOUS version of this spec did not perform, or performed with a narrower scope (e.g. `gist create` without `--public` → with `--public`; `git push` → `git push --force`)?" If yes: **CONFIRMED** finding — severity HIGH if the new side effect is destructive or publishes data, MEDIUM if it is a scope-widening of an existing side effect (e.g. a new label added to an existing bulk-edit loop). <!-- allowlist:check-command-side-effects — the `git push` above is a cited example of a scope-widening diff this auditor looks for, not a command this spec runs -->
+
+
+**Do NOT treat `commands/*.md` diffs as "just docs".** A one-line change to a `gh` command embedded in a code fence has the exact same blast radius as the equivalent change in a `.py`/`.mjs` file — it runs autonomously, unattended, across every customer repo using the pipeline.
+
+## Step 5: Secret Handling (CLI files)
+
+```bash
+# Added lines touching secret-like identifiers
+echo "[DOMAIN_DIFF_SLICE]" | grep -E '^\+' | grep -iE 'token|secret|api[_-]?key|password|credential' | grep -v '^\+\+\+'
+```
+
+For each hit attributed to a file in `$CLI_FILES`:
+- A token/secret/key passed as a CLI argument to a child process (visible to any other process via `ps`/Task Manager) rather than via an env var or stdin: **CONFIRMED HIGH**.
+- A token/secret logged via `console.log`/`console.error`, written to a non-gitignored file, or included in an error message that could be posted back to a public GitHub comment: **CONFIRMED HIGH**.
+- A token/secret read from `process.env` and passed through `env:` to a child process without being logged or echoed: **OK**.
+
+## Step 6: Network/Publish Calls (CLI files)
+
+```bash
+# Added lines with network or publish calls
+echo "[DOMAIN_DIFF_SLICE]" | grep -E '^\+' | grep -iE '\bfetch\(|\bhttps?\.request\(|\baxios\.|npm publish|npm.*publish' | grep -v '^\+\+\+'
+```
+
+For each hit: identify the destination host. A call to `api.github.com`/`github.com` via the already-authenticated `gh` CLI wrapper is expected. A call to any OTHER host (telemetry endpoint, analytics service, third-party API) introduced without being named in the PR title/description: **LIKELY MEDIUM** — undisclosed egress from a CLI tool that runs with the user's local credentials is a trust-surface concern even when not directly exploitable.
+
+## Step 7: Post Findings
+```bash
+gh pr comment [PR_NUMBER] --body "$(cat <<'EOF'
+## Spec/CLI Audit
+
+### Risk Level: [LOW/MEDIUM/HIGH/CRITICAL]
+
+### Shell/Exec Injection Findings
+| File:Line | Pattern | Tainted Source | Confidence | Evidence |
+|-----------|---------|-----------------|------------|----------|
+| ... | execSync template string | forge.yaml field / argv / env | CONFIRMED | [code path] |
+
+### gh Write/Egress Side Effects
+| File:Line | Operation | New or Widened? | Confidence | Evidence |
+|-----------|-----------|------------------|------------|----------|
+| ... | gh gist create --public | New | CONFIRMED | [explanation] |
+
+### Command-Spec Side-Effect Changes
+| File:Line | Old Behavior | New Behavior | Confidence |
+|-----------|--------------|--------------|------------|
+| ... | ... | ... | ... |
+
+### Secret Handling
+[Any secrets passed as argv, logged, or written to disk — or "None found"]
+
+### Network/Publish Calls
+[Any new external network destinations — or "None found — all egress via gh CLI to github.com"]
+
+### Files Reviewed
+[List all files checked]
+
+---
+*Spec/CLI audit*
+
+<!-- REVIEW-FINDINGS-START -->
+<!-- FINDING:SPEC-1|CONFIDENCE|SEVERITY|file.mjs:line|Summary -->
+<!-- (add one FINDING line per issue found — include ALL confidence levels) -->
+<!-- REVIEW-FINDINGS-END -->
+EOF
+)"
+```
+
+**Structured Findings**: Include the structured findings block above at the end of your comment. Your prefix: `SPEC`. See the Structured Findings Protocol in `protocols.md` for format rules.
+```
+
+### Coverage Matrix — SPEC Agent
+
+| Defect Category | Check Item(s) | Status | Ref |
+|----------------|---------------|--------|-----|
+| Shell-string exec/spawn interpolation in `.mjs` | Step 2 | COVERED | forge#1586 |
+| `gh` write/egress side effects (gist --public, pr merge, issue create) | Step 3 | COVERED | forge#1587 |
+| Command-spec side-effect changes in `commands/*.md` | Step 4 | COVERED | |
+| Secret handling in `.mjs` (argv exposure, logging) | Step 5 | COVERED | |
+| Undisclosed network/publish calls | Step 6 | COVERED | |
+| Prototype pollution / unsafe `eval`/`new Function` in `.mjs` | — | GAP | |
+| Path traversal via CLI-supplied file paths | — | GAP | |
+
+---

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).

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:**
 ```
@@ -239,6 +252,14 @@ done
 
 # Resolve repo name early — used in Phases 5, 6, 8B, 9A (clean-review skip path bypasses Phase 6A) <!-- Added: forge#820 -->
 REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
+
+# First-time contributor detection <!-- Added: forge#960 -->
+# Requires REPO to be set (line above). Checks whether the PR author has any prior merged PRs in this repo.
+# IS_FIRST_TIME_CONTRIBUTOR is consumed in Phase 9 to conditionally post an onboarding welcome comment.
+PR_AUTHOR=$(gh pr view "$ARGUMENTS" -R "$REPO" --json author --jq '.author.login')
+PRIOR_MERGED_COUNT=$(gh pr list -R "$REPO" --author "$PR_AUTHOR" --state merged --limit 1 --json number --jq 'length' 2>/dev/null || echo "1")
+IS_FIRST_TIME_CONTRIBUTOR="false"
+[ "$PRIOR_MERGED_COUNT" -eq 0 ] && IS_FIRST_TIME_CONTRIBUTOR="true"
 ```
 
 ### 1B: Classify
@@ -580,7 +601,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 +609,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 +662,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 +680,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 +1520,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 +1664,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 +1723,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 +1784,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 +1941,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.
@@ -2165,6 +2218,47 @@ REVIEW_IS_STALE="false"
 if [ "$CURRENT_SHA" != "$REVIEW_SHA" ]; then REVIEW_IS_STALE="true"; fi
 ```
 
+### Phase 9 — New Contributor Welcome (Conditional) <!-- Added: forge#960 -->
+
+Post a welcome comment when all three conditions are true:
+1. `IS_FIRST_TIME_CONTRIBUTOR="true"` (set in Phase 1A — no prior merged PRs from this author in this repo)
+2. `community.welcome_new_contributors` is not `false` in `forge.yaml` (default: enabled)
+3. This is a single-PR review (MODE 3) — not a staging→main or multi-PR review
+
+```bash
+# Read config — default enabled when key is absent
+WELCOME_ENABLED=$(yq '.community.welcome_new_contributors // true' forge.yaml 2>/dev/null || echo 'true')
+
+if [ "$IS_FIRST_TIME_CONTRIBUTOR" = "true" ] && [ "$WELCOME_ENABLED" != "false" ]; then
+    # Read optional custom values from forge.yaml community section
+    CONTRIBUTING_URL=$(yq '.community.contributing_url // "CONTRIBUTING.md"' forge.yaml 2>/dev/null || echo 'CONTRIBUTING.md')
+    CUSTOM_CONVENTIONS=$(yq '.community.conventions // ""' forge.yaml 2>/dev/null || echo '')
+    PROJECT_NAME_WELCOME=$(yq '.project.name // "this project"' forge.yaml 2>/dev/null || echo 'this project')
+
+    gh pr comment "$ARGUMENTS" --body "## Welcome to ${PROJECT_NAME_WELCOME}! 🎉
+
+Hi @${PR_AUTHOR} — this looks like your first merged contribution here. Thanks for opening a PR!
+
+### What just happened
+
+The automated review pipeline (/review-pr) ran against your PR. It spawned domain-specific agents to review security, integration assumptions, and code quality. Any findings were created as separate GitHub issues — not merge blockers unless they are CONFIRMED at HIGH/CRITICAL severity.
+
+### Key conventions
+
+$([ -n "\$CUSTOM_CONVENTIONS" ] && echo "\$CUSTOM_CONVENTIONS" || echo "- **Conventional commits**: prefix your commit messages with \`fix(scope):\`, \`feat(scope):\`, \`refactor(scope):\`, etc.
+- **DCO sign-off**: all commits must be signed off with \`git commit -s\` (Developer Certificate of Origin — required for the dual-license model).
+  Fix unsigned commits: \`git commit --amend -s --no-edit && git push --force-with-lease\`
+- **Issues, not inline fixes**: when you spot a bug or improvement opportunity, open a GitHub issue rather than fixing it inline — so it flows through the pipeline with full traceability.")
+
+### Getting started
+
+- Contributing guide: [\`${CONTRIBUTING_URL}\`](${CONTRIBUTING_URL})
+- Run \`npx forgedock\` to install the pipeline commands locally if you want to run /review-pr or /work-on yourself.
+
+Welcome aboard!"
+fi
+```
+
 **Verifiable agent count (MANDATORY — do not report a self-asserted `Agents: [N]` figure)** <!-- Added: forge#1849 -->
 
 A degraded run that skipped Task-based agent dispatch must be visible from this summary alone, without interrogating the agent afterward. Compute the actual launched-agent count from the `<!-- FORGE:REVIEW-AGENT:{domain} -->` comments each agent is required to post (Phase 3C), rather than trusting a free-text tally:

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