forgedock 1.1.11 → 1.2.0

package/commands/validate.md

@@ -1,6 +1,6 @@
 ---
 description: Independently verify if a reported issue is actually a problem before making code changes.
-argument-hint: [issue description or #number]
+argument-hint: "[issue description or #number]"
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -91,10 +91,17 @@ If CONFIRMED — recommended next step:
   Root cause: [one sentence]
   Fix approach: [one sentence]
   Create issue:
+Route 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 — this gets dedup (Phase 2D) and body validation (Phase 3F) for free:
+
 ```bash
-gh issue create --title "fix: [concise description of the confirmed bug]" \
-  --label "[priority],[bug|enhancement]" \
-  --body "$(cat <<'BODY_EOF'
+VALIDATE_ISSUE_TITLE="fix: [concise description of the confirmed bug]"
+# 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.
+VALIDATE_ISSUE_TITLE=$(printf '%s' "$VALIDATE_ISSUE_TITLE" | tr '`' "'" | sed 's/\$(/$ (/g')
+VALIDATE_ISSUE_BODY_FILE=$(mktemp)
+cat <<'BODY_EOF' > "$VALIDATE_ISSUE_BODY_FILE"
 ## Problem
 
 [1-3 sentences: what the validation confirmed is wrong. Specific and concrete.]
@@ -123,7 +130,11 @@ Validated by \`/validate\` on [DATE]. Confidence: [High|Medium|Low].
 - [source]: [finding]
 - [source]: [finding]
 BODY_EOF
-)"
+
+# [priority] and [bug|enhancement] are two separate labels — passed as repeated --label flags,
+# never comma-joined (the /issue programmatic contract's --label is repeatable, not CSV).
+Skill(skill="issue", args="--title \"$VALIDATE_ISSUE_TITLE\" --body-file \"$VALIDATE_ISSUE_BODY_FILE\" --label \"[priority]\" --label \"[bug|enhancement]\"")
+rm -f "$VALIDATE_ISSUE_BODY_FILE"
 ```
 
 If NOT A PROBLEM — why the report was wrong:

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

@@ -1,6 +1,6 @@
 ---
 description: Pre-implementation architecture planning — traces ALL affected code paths and produces an ordered implementation plan before any code is written
-argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--files AFFECTED_FILES]
+argument-hint: "[issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--files AFFECTED_FILES]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

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

@@ -1,6 +1,6 @@
 ---
 description: Pre-implementation context gathering — surfaces historical findings, bug patterns, and related code paths before the builder writes any code
-argument-hint: [issue number] [affected_files...] [--functions function_names...]
+argument-hint: "[issue number] [affected_files...] [--functions function_names...]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

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

@@ -1,6 +1,6 @@
 ---
 description: Implementation agent — writes code, makes commits, posts builder comment
-argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree PATH] [--branch BRANCH]
+argument-hint: "[issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree PATH] [--branch BRANCH]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -102,7 +102,7 @@ Extract from contract:
 | Refactor / Maintenance | Implement directly following contract deliverables |
 | Investigation | Spawn research agents, create GitHub issues for findings, skip to I5 |
 
-**Investigation task special case**: Research deeply, create GitHub issues for each finding using the Pipeline Issue Template (see `commands/issue.md` § "Pipeline Issue Template"). Each issue MUST include `## Problem`, `## Affected Files`, and `## Acceptance Criteria`. Use `gh issue create {GH_FLAG}` with a fully-structured body. Post a deliverables comment listing the created issues, close the original issue, return `IMPLEMENT_RESULT: status: INVESTIGATION_COMPLETE`.
+**Investigation task special case**: Research deeply, create GitHub issues for each finding using the Pipeline Issue Template (see `commands/issue.md` § "Pipeline Issue Template"). Each issue MUST include `## Problem`, `## Affected Files`, and `## Acceptance Criteria`. Create each issue via the `/issue` create-hook's programmatic invocation contract (see `commands/issue.md` § "Programmatic Invocation Contract") — `Skill(skill="issue", args="--title \"...\" --body-file <path> --label ...")` — instead of calling the raw issue-creation command directly; this gets dedup and body validation for free. Post a deliverables comment listing the created issues, close the original issue, return `IMPLEMENT_RESULT: status: INVESTIGATION_COMPLETE`.
 
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 description: Validation agent — quality gate loop, format/verify, proxy check, deploy check
-argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree PATH] [--files FILE1 FILE2...]
+argument-hint: "[issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree PATH] [--files FILE1 FILE2...]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -304,6 +304,8 @@ Where `{SCOPE}` is the command or module scope from the contract (e.g. `work-on`
 
 This is the **only** commit for this build cycle. It replaces the old `git commit` that was previously in `implement.md` Phase I4. Do NOT create a separate commit for validation fixes — they are absorbed into this single commit.
 
+**Attribution**: The commit message is exactly the conventional-commit line above — nothing more. Do NOT append a `Co-Authored-By: Claude` trailer, a `🤖 Generated with Claude Code` line, or any assistant-tool attribution. Pipeline output is ForgeDock-branded; the assistant signature must never enter the repo's commit history. (A PreToolUse guard hard-blocks it as a backstop — see `bin/hooks/pre-tool-use.mjs` Rule 5.)
+
 ### V5 Post-Commit Ancestry Audit (MANDATORY)
 
 After committing, run the ancestry audit to detect merge commits from unrelated branches before the branch is pushed:

package/commands/work-on/build.md

@@ -1,6 +1,6 @@
 ---
 description: Build subcommand — create worktree, post contract, sequence context/architect/implement/validate
-argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--base PR_BASE]
+argument-hint: "[issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--base PR_BASE]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

package/commands/work-on/close.md

@@ -1,6 +1,6 @@
 ---
 description: Close subcommand — update project board, final issue body, parent tracker, summary report, trajectory log
-argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--pr PR_NUMBER] [--base PR_BASE] [--branch BRANCH] [--worktree WORKTREE_PATH]
+argument-hint: "[issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--pr PR_NUMBER] [--base PR_BASE] [--branch BRANCH] [--worktree WORKTREE_PATH]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

package/commands/work-on/decompose.md

@@ -1,6 +1,6 @@
 ---
 description: Decompose subcommand — break a complex issue into ordered sub-issues, post FORGE:DECOMPOSED, stop
-argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG]
+argument-hint: "[issue number] [--repo GH_REPO] [--gh-flag GH_FLAG]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -106,30 +106,14 @@ For each sub-issue, prepare:
 
 ## Phase D3: Create Sub-Issues
 
-For each sub-issue (in dependency order):
+For each sub-issue (in dependency order), route creation through the `/issue` create-hook's programmatic invocation contract (`commands/issue.md` Programmatic Invocation Contract, added in #2085) instead of calling `gh issue create` directly. `/issue`'s Phase 2D runs the same `scripts/issue-dedup.sh` check this file used to run manually — the standalone pre-check below is removed; dedup is now enforced inside the create-hook on every call, with no bypass path. <!-- Changed: forge#2086 — route through /issue create-hook -->
 
-**Before creating each sub-issue, run the deterministic dedup check:** <!-- Added: forge#1335 -->
+**Compose the sub-issue body to a temp file** (avoids quoting issues when passed as `--body-file`):
 
 ```bash
 SUB_TITLE="{fix|feat|refactor}: {SUB_ISSUE_TITLE}"
-DEDUP_RESULT=$(scripts/issue-dedup.sh "$SUB_TITLE" {GH_FLAG} 2>&1)
-DEDUP_EXIT=$?
-if [ "$DEDUP_EXIT" -eq 1 ]; then
-  echo "DEDUP: Sub-issue near-duplicate detected — $DEDUP_RESULT"
-  echo "Skipping creation. Comment on the existing issue instead."
-  # Do NOT call gh issue create for this sub-issue
-elif [ "$DEDUP_EXIT" -eq 2 ]; then
-  echo "DEDUP: Usage error — $DEDUP_RESULT"
-  # Do NOT call gh issue create for this sub-issue — fix the invocation and retry
-fi
-```
-
-Only call `gh issue create` when the dedup script exits 0 (no match):
-
-```bash
-gh issue create {GH_FLAG} \
-  --title "{fix|feat|refactor}: {SUB_ISSUE_TITLE}" \
-  --body "$(cat <<'SUB_BODY_EOF'
+SUB_BODY_FILE="$(mktemp)"
+cat > "$SUB_BODY_FILE" <<'SUB_BODY_EOF'
 ## Problem
 
 {1-3 sentences: what this sub-issue specifically addresses. What's wrong or what needs to be built for this sub-task.}
@@ -155,11 +139,30 @@ Files that need changes:
 **Parent**: #{NUMBER}
 {If depends on another sub-issue: "**Depends on**: #{SUB_ISSUE_N} — {reason}"}
 SUB_BODY_EOF
-)" \
-  --label "{PRIORITY_LABEL}" \
-  --milestone "{MILESTONE_TITLE}"
 ```
 
+**Invoke `/issue` in programmatic mode**:
+
+```
+ISSUE_SKILL_OUTPUT=$(Skill(skill="issue", args="--title \"${SUB_TITLE}\" --body-file \"${SUB_BODY_FILE}\" --label \"{PRIORITY_LABEL}\" --milestone \"{MILESTONE_TITLE}\""))
+```
+
+`/issue` runs Phase 2D dedup, Phase 3F body validation, then creates the issue (Phase 4) — no separate pre-check needed on this side.
+
+**Extract the created sub-issue number from the Skill output** (see `commands/issue.md` Phase 4C/4E — it echoes `Created: {url}` and reports `**#{NUMBER}**: {title}`):
+
+```bash
+# Match either the "Created: {url}" line (extract trailing /issues/N) or the "**#{NUMBER}**" bold report line.
+SUB_NUMBER=$(echo "$ISSUE_SKILL_OUTPUT" | grep -oE 'issues/[0-9]+' | head -1 | grep -oE '[0-9]+')
+[ -z "$SUB_NUMBER" ] && SUB_NUMBER=$(echo "$ISSUE_SKILL_OUTPUT" | grep -oE '\*\*#[0-9]+\*\*' | head -1 | grep -oE '[0-9]+')
+
+if [ -z "$SUB_NUMBER" ]; then
+  echo "WARNING: /issue did not report a created issue number for sub-issue '${SUB_TITLE}' — likely a Phase 2D dedup STOP (near-duplicate found) or a usage error. Skipping this sub-issue: do not reference it in the parent tracker or in dependent sub-issue bodies. Review the Skill output above and, if a near-duplicate exists, comment on the existing issue instead."
+fi
+```
+
+If `SUB_NUMBER` is empty, treat this sub-issue as not created — do not add it to the parent tracker checklist (Phase D4) and do not reference it as a dependency in later sub-issues.
+
 **Append Prior Investigation section** (conditional — only if `GIST_URLS` from Phase D1.5 is non-empty):
 
 After creating each sub-issue, append the `## Prior Investigation` section containing all parent Gist URLs. This keeps the Gist references machine-readable for downstream agents.

package/commands/work-on/investigate.md

@@ -1,6 +1,6 @@
 ---
 description: Investigate a GitHub issue — validate it's real, determine root cause, post findings
-argument-hint: [issue number] [--repo {owner}/{repo}] [--gh-flag "-R {owner}/{repo}"]
+argument-hint: "[issue number] [--repo {owner}/{repo}] [--gh-flag \"-R {owner}/{repo}\"]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -380,7 +380,7 @@ if [ "$ATTRIBUTION_ANNOTATION_LINK" = "true" ]; then
   ANNOTATION_LINK_FOOTER="
 
 ---
-*Pipeline powered by [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock)*"
+*⚒️ Pipeline powered by [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock)*"
 fi
 ```
 

package/commands/work-on/remediate.md

@@ -1,6 +1,6 @@
 ---
 description: Remediate subcommand — checkout a needs-human PR, fix review findings, re-review, and re-gate with a FORGE:REMEDIATION paper trail
-argument-hint: [PR number] [--issue N] [--repo GH_REPO] [--gh-flag GH_FLAG] [--base PR_BASE]
+argument-hint: "[PR number] [--issue N] [--repo GH_REPO] [--gh-flag GH_FLAG] [--base PR_BASE]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

package/commands/work-on/review.md

@@ -1,6 +1,6 @@
 ---
 description: Review subcommand — push branch, create PR, invoke /review-pr with --auto-merge
-argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree PATH] [--branch BRANCH] [--base PR_BASE]
+argument-hint: "[issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree PATH] [--branch BRANCH] [--base PR_BASE]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -159,7 +159,7 @@ ATTRIBUTION_PR_FOOTER=$(grep -A5 "^attribution:" forge.yaml 2>/dev/null | grep "
 If `ATTRIBUTION_PR_FOOTER` is `true`, append the following footer to the PR body (once — never duplicate on retries):
 
 ```
-> 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.
 ```
 
 ### R2C: Create PR
@@ -188,13 +188,15 @@ Closes #{NUMBER}
 **Implementation branch**: \`{BRANCH}\`
 **Base**: \`{PR_BASE}\`
 {IF_ATTRIBUTION_PR_FOOTER_TRUE:
-> 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.}"
 ```
 
 **Note**: `Closes #{NUMBER}` documents intent but does NOT auto-close for non-default-branch PRs. The close subcommand handles explicit closure after merge.
 
 **Attribution guard**: The footer line is appended once at PR creation. If the PR already exists (resume path), do NOT append the footer again — check the existing PR body first.
 
+**No assistant attribution**: The PR body is exactly the sections above (plus the optional ForgeDock footer). Do NOT add a `🤖 Generated with Claude Code` line, a `Co-Authored-By: Claude` trailer, or any assistant-tool attribution — the pipeline is ForgeDock-branded. A PreToolUse guard hard-blocks it as a backstop (`bin/hooks/pre-tool-use.mjs` Rule 5).
+
 If PR creation fails because a PR already exists for this branch:
 ```bash
 gh pr list {GH_FLAG} --head {BRANCH} --json number,url --jq '.[0]'

package/commands/work-on-monolithic.md

@@ -1,6 +1,6 @@
 ---
 description: "[BENCHMARK] Monolithic work-on — single-prompt pipeline with no Skill sub-phase boundaries"
-argument-hint: [issue number]
+argument-hint: "[issue number]"
 install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/work-on.md

@@ -1,6 +1,6 @@
 ---
 description: Pick up a GitHub issue and run the full investigate-build-review-merge pipeline
-argument-hint: [issue number or "next" to pick highest priority]
+argument-hint: "[issue number or \"next\" to pick highest priority]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -926,10 +926,18 @@ For each sub-issue:
 - **Milestone**: same as parent
 
 ### 2C: Create sub-issues
+
+Route 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 — this gets dedup (Phase 2D) and body validation (Phase 3F) for free on every decomposition-spawned sub-issue.
+
 ```bash
-gh issue create {GH_FLAG} \
-  --title "{fix|feat|refactor}: {SUB_ISSUE_TITLE}" \
-  --body "$(cat <<'SUB_BODY_EOF'
+SUB_ISSUE_TITLE_FULL="{fix|feat|refactor}: {SUB_ISSUE_TITLE}"
+# 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.
+SUB_ISSUE_TITLE_FULL=$(printf '%s' "$SUB_ISSUE_TITLE_FULL" | tr '`' "'" | sed 's/\$(/$ (/g')
+SUB_ISSUE_BODY_FILE=$(mktemp)
+cat <<'SUB_BODY_EOF' > "$SUB_ISSUE_BODY_FILE"
 ## Problem
 
 {1-3 sentences: what this sub-issue specifically addresses. What's wrong or what needs to be built.}
@@ -955,9 +963,22 @@ Files that need changes:
 **Parent**: #{NUMBER}
 {If depends on another sub-issue: "**Depends on**: #{SUB_ISSUE_N} — {reason}"}
 SUB_BODY_EOF
-)" \
-  --label "{PRIORITY_LABEL}" \
-  --milestone "{MILESTONE_TITLE}"
+
+# --milestone is only passed when the parent has one (see Phase 2B — "Milestone: same as parent").
+MILESTONE_ARG=""
+[ -n "{MILESTONE_TITLE}" ] && MILESTONE_ARG="--milestone \"{MILESTONE_TITLE}\""
+Skill(skill="issue", args="--title \"$SUB_ISSUE_TITLE_FULL\" --body-file \"$SUB_ISSUE_BODY_FILE\" --label \"{PRIORITY_LABEL}\" ${MILESTONE_ARG}")
+rm -f "$SUB_ISSUE_BODY_FILE"
+
+# /issue has no machine-readable return contract — resolve the created issue's number by
+# exact-title search immediately after the call (used by Phase 2D's tracker checklist).
+# Retry to absorb GitHub Search API indexing lag.
+SUB_ISSUE_NUM=""
+for _resolve_attempt in 1 2 3; do
+  SUB_ISSUE_NUM=$(gh issue list {GH_FLAG} --search "in:title \"${SUB_ISSUE_TITLE_FULL}\"" --state open --limit 1 --json number --jq '.[0].number // empty')
+  [ -n "$SUB_ISSUE_NUM" ] && break
+  sleep 2
+done
 ```
 
 ### 2D: Update parent issue body

package/docs/CI.md

@@ -128,6 +128,24 @@ This is not recommended without understanding the security implications.
 
 ---
 
+## `forgedock run` Execution Backend
+
+This guide's `forgedock-review.yml` workflow invokes `/review-pr` directly via the `claude --print` CLI, so it always needs `ANTHROPIC_API_KEY` as shown above — the CLI itself authenticates against your Anthropic account.
+
+Separately, `npx forgedock run <command>` (the standalone, non-Claude-Code command runner in `bin/runner.mjs`) has its own **backend selection**, independent of this CI workflow:
+
+| Backend | When used | Credential needed |
+|---------|-----------|--------------------|
+| `cli` (via `--backend cli` or `FORGEDOCK_BACKEND=cli`) | Explicit, or auto-selected when a working `claude` CLI is detected on PATH | None — reuses the CLI's own authentication (Pro/Max OAuth or a CLI-managed key) |
+| `api` (via `--backend api` or `FORGEDOCK_BACKEND=api`) | Explicit, or auto-selected fallback when `claude` is not detected | `ANTHROPIC_API_KEY` |
+| `auto` (default) | No `--backend` / `FORGEDOCK_BACKEND` given | Prefers `cli`, falls back to `api` |
+
+**When CI still needs `ANTHROPIC_API_KEY` for `forgedock run`**: CI runners generally do not have an interactively-authenticated `claude` CLI (no browser/OAuth flow available in a headless job), so `auto` detection will typically fall back to `api` there anyway. If your CI runner does install and log in the `claude` CLI (e.g. via a headless API-key-based login), you can force `--backend cli` to skip the SDK/API path entirely. Otherwise, keep `ANTHROPIC_API_KEY` configured as a repository secret (see Setup above) and either let `auto` fall back naturally or set `--backend api` / `FORGEDOCK_BACKEND=api` explicitly for a deterministic CI backend regardless of what happens to be on the runner's PATH.
+
+`npx forgedock run <command> --dry-run` always reports which backend it resolved to, without making any network call or requiring a key either way.
+
+---
+
 ## Customization
 
 ### Skip review for certain PRs

package/docs/CONFIG.md

@@ -29,9 +29,12 @@ echo "forge.yaml" >> .gitignore  # if your credentials path is sensitive
 |----------|----------|
 | `FORGE_NO_MOTION=1` | Same effect as `--fast` — disables animation frames. Color is unaffected. |
 | `NO_COLOR=1` | Disables ANSI color output only. Motion is unaffected (monochrome choreography). |
+| `FORGEDOCK_INIT_BACKEND=cli\|api\|none\|auto` | Overrides AI-enrichment backend selection for `init` (see below). Default `auto` (or unset) preserves the CLI-first ladder. |
 | Non-TTY / piped output (or `CI=1`) | Plain sequential log: no color **and** no animation. |
 
-The default (no flags) is the annotated review screen: detection runs, AI enrichment fills in what it can (when an API key is available), and you review the result on a single screen — Enter accepts everything, low-confidence fields are flagged with a `# TODO(forgedock:<field>)` comment if left unedited.
+The default (no flags) is the annotated review screen: detection runs, AI enrichment fills in what it can — using a local, authenticated `claude` CLI when available, otherwise falling back to the Anthropic API when `ANTHROPIC_API_KEY` is set, otherwise skipped — and you review the result on a single screen — Enter accepts everything, low-confidence fields are flagged with a `# TODO(forgedock:<field>)` comment if left unedited.
+
+If you have both a local `claude` CLI and `ANTHROPIC_API_KEY` set and want to pin one explicitly instead of letting `init` prefer the CLI, set `FORGEDOCK_INIT_BACKEND=api` (or `=cli`, or `=none` to skip enrichment entirely). This is independent of `FORGEDOCK_BACKEND`, which controls the separate `forgedock run` engine backend.
 
 ---
 
@@ -741,7 +744,7 @@ const draft = await detectConfig(process.cwd());
 
 Downstream consumers read `field.value` for the raw value and `field.confidence` to decide how to handle it:
 
-- **`init-enrich`** (AI enrichment): passes `low`- and `medium`-confidence fields to the AI backend to raise their confidence; leaves `high`-confidence fields untouched.
+- **`init-enrich`** (AI enrichment): passes `low`- and `medium`-confidence fields to the selected AI backend (a local `claude` CLI when available, otherwise the Anthropic API with `ANTHROPIC_API_KEY`) to raise their confidence; leaves `high`-confidence fields untouched.
 - **`review-render`** (TUI review screen): shows each field with its source and why; highlights `low`-confidence fields with a `# TODO(forgedock:<field>)` annotation in the generated YAML.
 
 ---

package/docs/site/annotations-explained.md

@@ -57,10 +57,10 @@ ForgeDock can optionally append a small attribution line to pipeline-created PRs
 **`attribution.pr_footer: true`** — every pipeline-created PR ends with one muted footer:
 
 ```
-> Orchestrated with ForgeDock — state, scheduling, review, and memory on GitHub.
+> ⚒️ Orchestrated with ForgeDock — state, scheduling, review, and memory on GitHub.
 ```
 
-**`attribution.annotation_link: true`** — visible (human-readable) annotation comments in the GitHub UI carry a small "Pipeline powered by ForgeDock" link at the end. Machine-readable `<!-- FORGE:... -->` HTML comments are never modified, regardless of this setting.
+**`attribution.annotation_link: true`** — visible (human-readable) annotation comments in the GitHub UI carry a small "⚒️ Pipeline powered by ForgeDock" link at the end. Machine-readable `<!-- FORGE:... -->` HTML comments are never modified, regardless of this setting.
 
 Both keys default to disabled. The recommended configuration for public repos is to enable both; for private repos, leave both off.
 

package/docs/site/command-reference.md

@@ -91,6 +91,27 @@ Analyzes what a PR touches and spawns domain-specific review agents.
 
 ---
 
+### `/review-pr-staging`
+
+**Staging review mode — deep review of a `staging → main` bundle before deploy.**
+
+Purpose-built for the large, heterogeneous diffs a deploy bundle produces (1,000–10,000+ lines). Invoked by the orchestrator via `Skill("review-pr-staging", …)` or directly.
+
+```bash
+/review-pr-staging staging          # Review the staging → main bundle
+/review-pr-staging 123              # Review a PR targeting main
+/review-pr-staging staging:feature  # Review a feature bundle into staging
+```
+
+**What it does**:
+- Handles large, diverse diffs with deep per-domain analysis and business-impact assessment
+- Deep-diffs workflow siblings (e.g. `ci.yml` vs. `deploy-production.yml`) to catch shared-job drift that only surfaces at deploy time
+- Produces a comprehensive verdict gating the deploy to `main`
+
+*Companion to `/review-pr`, tuned for the deploy gate rather than a single feature PR.*
+
+---
+
 ### `/quality-gate`
 
 **Pre-commit quality checker.**

package/docs/spec/review-protocol.md

@@ -14,6 +14,12 @@ Do not duplicate these protocols in any other file. When updating either protoco
 
 ---
 
+## 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)
 
 Every agent MUST follow this protocol:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.1.11",
+  "version": "1.2.0",
   "description": "Autonomous dev pipeline for Claude Code. GitHub as institutional memory — every issue, PR, and annotation survives context resets and makes the next agent smarter.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"