forgedock 1.1.11 → 1.3.0

package/commands/orchestrate/phase-5-cleanup.md

@@ -39,9 +39,50 @@ Include the audit summary in the final report (Phase 6). Key metrics to surface:
 - **Resume cycles** — how many times agents had to be resumed
 - **Stall boundaries** — which phase transitions cause the most stalls
 
-### Step 5C: Report cleanup results
+### Step 5C: Close the coordination issue (claims board) <!-- Added: forge#2072 -->
 
-Include the cleanup summary in the final report (Phase 6). If cleanup found problems, call them out — they indicate agent pipeline failures that may need investigation.
+**Why this step exists**: Step 3D.1 (`phase-3-dependency.md`) creates a per-batch coordination issue (the claims board) and exports `FORGE_COORD_ISSUE`/`COORD_ISSUE_NUMBER`. Step 5A's `/cleanup` sweep only closes orphaned issues whose PR merged — the claims board has no PR of its own, so that heuristic never matches it. Without this step, one `automation`-labelled issue leaks per orchestration batch.
+
+**Run after Step 5B, before Step 5D.** No-ops cleanly if the claims board was never created this run (`COORD_ISSUE_NUMBER` unset/empty — e.g. Step 3D.1's `gh issue create` failed, or this batch never reached DAG construction). Tolerates GitHub API failures without aborting the rest of Phase 5 — the same tolerant-failure convention (`2>/dev/null || echo ...`, `|| true`) used throughout `phase-3-dependency.md`/`phase-4-execution.md`.
+
+```bash
+if [ -n "${COORD_ISSUE_NUMBER:-}" ]; then
+  # Detect any still-active (unreleased) claims — a claim posted with no matching
+  # CLAIM_RELEASED comment on the same coordination issue. Adapted from the query
+  # phase-4-execution.md's claims-board relaxation sweep uses (Step 4B item 4),
+  # simplified to holder-only (a flat string array) since Step 5C only needs
+  # holder names for the closure note — unlike phase-4-execution.md's version,
+  # which also captures each claim's `files` into an object alongside `holder`.
+  ACTIVE_CLAIMS=$(gh api repos/{GH_REPO}/issues/${COORD_ISSUE_NUMBER}/comments \
+    --jq '[.[] | select(.body | contains("<!-- FORGE:CLAIM -->")) |
+           select(.body | contains("<!-- FORGE:CLAIM_RELEASED -->") | not)] |
+          map(.body | capture("\\*\\*Holder\\*\\*: (?P<h>[^\\n]+)").h // "unknown")' 2>/dev/null || echo '[]')
+  ACTIVE_CLAIMS_COUNT=$(echo "$ACTIVE_CLAIMS" | jq 'length' 2>/dev/null || echo 0)
+
+  if [ "$ACTIVE_CLAIMS_COUNT" -gt 0 ] 2>/dev/null; then
+    ACTIVE_CLAIMS_NOTE="**Still-active claims at close time** (${ACTIVE_CLAIMS_COUNT}) — not blocking closure, listed for visibility:
+$(echo "$ACTIVE_CLAIMS" | jq -r '.[] | "- " + .' 2>/dev/null)"
+  else
+    ACTIVE_CLAIMS_NOTE="No active (unreleased) claims at close time."
+  fi
+
+  gh issue close "$COORD_ISSUE_NUMBER" -R {GH_REPO} --comment "Batch complete — closing claims board.
+
+${ACTIVE_CLAIMS_NOTE}
+
+Closed automatically by \`/orchestrate\` Phase 5 Step 5C." 2>/dev/null \
+    && echo "Closed coordination issue #${COORD_ISSUE_NUMBER}" \
+    || echo "WARNING: failed to close coordination issue #${COORD_ISSUE_NUMBER} — non-fatal, continuing Phase 5"
+else
+  echo "No coordination issue for this batch (FORGE_COORD_ISSUE unset) — Step 5C is a no-op"
+fi
+```
+
+**Idempotency**: `gh issue close` on an already-closed issue succeeds as a no-op (no error) — safe to re-run this step on a resumed/compacted session without an extra pre-check.
+
+### Step 5D: Report cleanup results
+
+Include the cleanup summary in the final report (Phase 6), including whether the coordination issue was closed this run (see Step 5C). If cleanup found problems, call them out — they indicate agent pipeline failures that may need investigation.
 
 ---
 

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

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

package/commands/orchestrate.md

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

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

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

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

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

package/commands/pipeline-health.md

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

package/commands/pipeline-resume.md

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

package/commands/pipeline-status.md

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

package/commands/qa-sweep.md

@@ -1,6 +1,6 @@
 ---
 description: Full platform QA sweep — auto-discovers every page, tests every UI element via browser automation, creates GitHub issues for all findings
-argument-hint: [all | dashboard | marketing | page <route> | journey | visual | functional | a11y]
+argument-hint: "[all | dashboard | marketing | page <route> | journey | visual | functional | a11y]"
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -36,6 +36,23 @@ See README.md Requirements section for full setup instructions.
 
 ---
 
+## Playwright MCP Prerequisite (MANDATORY — check before proceeding)
+
+Playwright MCP is a **guaranteed ForgeDock dependency** for all browser automation commands. Before running any qa-sweep phase, verify it is available:
+
+**Check**: Confirm `mcp__playwright__*` tools are available in your tool context (e.g., `mcp__playwright__browser_navigate`, `mcp__playwright__browser_snapshot`).
+
+**If Playwright MCP tools are NOT available**: STOP immediately. Do not attempt to run qa-sweep — all browser automation steps will fail silently.
+
+**Fix**:
+1. Register Playwright MCP: `claude mcp add playwright npx @playwright/mcp@latest`
+2. Restart Claude Code to reload MCP servers
+3. Verify with: `npx forgedock doctor` (Check 9 confirms registration)
+
+See README.md Requirements section for full setup instructions.
+
+---
+
 ## Browser Tool Reference
 
 All browser automation uses Playwright MCP tools (`mcp__playwright__*`). Playwright MCP is a guaranteed ForgeDock dependency — see the Playwright MCP Prerequisite section above.
@@ -274,10 +291,11 @@ Each journey agent: maintain state ledger, verify outcomes cross-step, report da
 1. Parse all agent findings
 2. Deduplicate (prefer journey context over page-only findings)
 3. Reprioritize: found in 3+ pages → bump severity; blocks journey → P0
-4. Create GitHub issues:
+4. Create GitHub issues — route creation through the `/issue` create-hook's programmatic invocation contract (see `commands/issue.md` → Programmatic Invocation Contract) so dedup and mandatory-section validation run on every finding:
 
 ```bash
-gh issue create --title "{fix|feat}: {title} on {page}" --label "qa,{bug_or_enhancement},{priority}" --body "$(cat <<'BODY_EOF'
+QA_BODY_FILE=$(mktemp)
+cat > "$QA_BODY_FILE" <<'BODY_EOF'
 ## Problem
 
 {1-3 sentences: what the QA sweep found. What's broken or missing, with specific observable behavior.}
@@ -318,9 +336,14 @@ Files that need changes:
 
 {List other pages where this issue was also observed, or "None"}
 BODY_EOF
-)"
 ```
 
+```
+Skill(skill="issue", args="--title \"{fix|feat}: {title} on {page}\" --body-file \"$QA_BODY_FILE\" --label \"qa\" --label \"{bug_or_enhancement}\" --label \"{priority}\"")
+```
+
+`qa`, `{bug_or_enhancement}`, and `{priority}` are each passed as their own `--label` flag — `/issue`'s programmatic mode does not comma-split a single `--label` value.
+
 Issue body includes: Source, Page, Device, Type, Severity, Journey context, Description, Steps to Reproduce, State Context, Cross-Page Impact.
 
 5. Cross-page consistency table (compare balance/tier/email across all pages)

package/commands/recover-orphans.md

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

package/commands/replay.md

@@ -95,7 +95,7 @@ fi
 
 ```bash
 # Filter to comments that contain a FORGE pipeline annotation
-FORGE_COMMENTS=$(echo "$ALL_COMMENTS" | jq -c '[.[] | select(.body | test("<!-- FORGE:(INVESTIGATOR|CONTRACT|CONTEXT|ARCHITECT|BUILDER|DECOMPOSED|TRAJECTORY)"))]')
+FORGE_COMMENTS=$(echo "$ALL_COMMENTS" | jq -c '[.[] | select(.body | test("<!-- FORGE:(INVESTIGATOR|CONTRACT|CONTEXT|ARCHITECT|BUILDER|DECOMPOSED|SUMMARY|TRAJECTORY)"))]')
 FORGE_COUNT=$(echo "$FORGE_COMMENTS" | jq 'length')
 
 if [ "$FORGE_COUNT" -eq 0 ]; then
@@ -115,7 +115,7 @@ echo ""
 
 ## Step 5: Display Each Annotation
 
-Phase mapping (inline): `INVESTIGATOR`→Phase 1, `CONTRACT`→Phase 3C, `CONTEXT`→Phase 3C.5, `ARCHITECT`→Phase 3C.6, `BUILDER`→Phase 3M, `DECOMPOSED`→Phase 2, `TRAJECTORY`→Phase 7.
+Phase mapping (inline): `INVESTIGATOR`→Phase 1, `CONTRACT`→Phase 3C, `CONTEXT`→Phase 3C.5, `ARCHITECT`→Phase 3C.6, `BUILDER`→Phase 3M, `DECOMPOSED`→Phase 2, `SUMMARY`→Phase C4.5, `TRAJECTORY`→Phase 7.
 
 For each FORGE comment in chronological order, print a formatted block. Use Python for robust multiline extraction from the comment body.
 
@@ -136,6 +136,7 @@ echo "$FORGE_COMMENTS" | jq -c '.[]' | while IFS= read -r COMMENT; do
     "FORGE:ARCHITECT")    PHASE_LABEL="Phase 3C.6 — Architecture Plan" ;;
     "FORGE:BUILDER")      PHASE_LABEL="Phase 3M — Implementation" ;;
     "FORGE:DECOMPOSED")   PHASE_LABEL="Phase 2 — Decomposition" ;;
+    "FORGE:SUMMARY")      PHASE_LABEL="Phase C4.5 — Shareable Summary" ;;
     "FORGE:TRAJECTORY")   PHASE_LABEL="Phase 7 — Pipeline Trajectory" ;;
     *)                    PHASE_LABEL="$ANNOTATION" ;;
   esac
@@ -216,6 +217,19 @@ elif annotation == "FORGE:DECOMPOSED":
     for s in subs[:5]:
         print(f"│    {s}")
 
+elif annotation == "FORGE:SUMMARY":
+    lane       = extract(r'\*\*Lane\*\*\s*\|\s*([^\|]+)')
+    verdict    = extract(r'\*\*Investigation verdict\*\*\s*\|\s*([^\|]+)')
+    task_type  = extract(r'\*\*Task type\*\*\s*\|\s*([^\|]+)')
+    review     = extract(r'\*\*Review verdict\*\*\s*\|\s*([^\|]+)')
+    files      = extract(r'\*\*Files changed\*\*\s*\|\s*([^\|]+)')
+    pr_link    = extract(r'\[View PR #(\d+)\]')
+    print(f"│  Lane       : {lane.strip()[:60]}")
+    print(f"│  Verdict    : {verdict.strip()[:60]}")
+    print(f"│  Task type  : {task_type.strip()[:60]}")
+    print(f"│  Review     : {review.strip()[:60]}")
+    print(f"│  Files      : {files.strip()[:30]}  |  PR: #{pr_link}")
+
 elif annotation == "FORGE:TRAJECTORY":
     # Print the phase table lines verbatim (they're already formatted)
     in_table = False

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

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