forgedock 1.7.0 → 1.8.0

package/commands/review-pr.md

@@ -33,9 +33,28 @@ allowed-tools: Task, Agent, Bash, Read, Grep, Glob, WebFetch, Skill
 
 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:
 
+### OpenCode Runtime Override
+
+When the workflow is running under OpenCode, resolve the native tool before applying the Claude-specific availability order above:
+
+```bash
+IS_OPENCODE_RUNTIME=false
+if [ "${FORGE_RUNTIME:-}" = "opencode" ] ||
+   [ -n "${OPENCODE_SESSION_ID:-}" ] ||
+   [ -n "${OPENCODE_PID:-}" ] ||
+   [ -n "${OPENCODE:-}" ]; then
+  IS_OPENCODE_RUNTIME=true
+  DISPATCH_TOOL=task
+  DISPATCH_SUBAGENT_TYPE=general
+fi
+```
+
+When `IS_OPENCODE_RUNTIME=true`, lowercase native `task` is the preferred isolated dispatch tool. Do not enter the `Neither tool is available` branch merely because Claude's literal `Task` and `Agent` names are absent. Every native task call must use a top-level `subagent_type`: `general` for implementation/review work and `explore` for read-only discovery (Claude `general-purpose` and `codebase-explorer` map to those values). Review tasks are foreground: wait for their completed result before synthesis. If the native `task` capability itself is absent from the current tool registry, use the existing hard-stop path and post `FORGE:REVIEW_BLOCKED`; never substitute inline review.
+
 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.
+4. **Dispatch pool exhausted or dispatch call fails**: this is distinct from tool absence. If any selected reviewer cannot be launched because the runtime reports a sub-agent/session/pool limit (or any dispatch call fails), HARD STOP immediately. Do not review that domain inline, do not silently reduce the panel, and do not merge. Mark the PR `review-degraded`, add `needs-human` to the linked issue, post `<!-- FORGE:GATE_FAILURE:TYPE=review-panel-integrity -->` with the selected and completed reviewer counts, then exit without a `FORGE:REVIEW` verdict. A later fresh session must re-run the full selected panel.
 
 **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.
 
@@ -1520,9 +1539,31 @@ 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 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)
+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). Under OpenCode, emit a top-level `subagent_type: "general"` or `"explore"` in the native `task` argument object and use `background: false` for each reviewer.
+
+**CRITICAL**: Launch ALL selected agents in a SINGLE message using multiple `{DISPATCH_TOOL}` calls. Each agent must persist its finalized body before posting it with `gh pr comment --body-file`, include `<!-- FORGE:REVIEW-AGENT:{lowercase-domain} -->`, and return its verdict and findings to the orchestrator independently of GitHub delivery.
 
-**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`.
+**Dispatch failure and partial-panel guard (MANDATORY):** Count the selected roster before dispatch. If any launch fails, including from pool exhaustion, do not continue with the agents that did launch as a sufficient panel. Immediately create the managed label if necessary, label the PR `review-degraded`, add `needs-human` to the linked issue, post `FORGE:GATE_FAILURE`, and exit without a verdict. After all foreground reviewers return, independently compare their posted `FORGE:REVIEW-AGENT` markers with the selected count; a smaller count is the same hard stop. This catches a reviewer that accepted dispatch but failed before posting.
+
+```bash
+SELECTED_AGENT_COUNT=$(echo "$SELECTED_AGENTS" | tr ' ' '\n' | grep -c '.')
+ACTUAL_AGENT_COUNT=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" \
+  --jq '[.[].body | scan("<!-- FORGE:REVIEW-AGENT:([a-z-]+) -->") | .[0]] | unique | length' 2>/dev/null || echo 0)
+
+if [ "$DISPATCH_FAILED" = "true" ] || [ "$ACTUAL_AGENT_COUNT" -lt "$SELECTED_AGENT_COUNT" ]; then
+  gh label create "review-degraded" --color "E4E669" --description "PR review panel was incomplete; re-review required before deployment. Managed by ForgeDock." --force -R "$REPO" 2>/dev/null || true
+  gh pr edit "$PR_NUMBER" -R "$REPO" --add-label "review-degraded" --add-label "needs-human" 2>/dev/null || true # allowlist:check-command-side-effects
+  gh pr comment "$PR_NUMBER" -R "$REPO" --body "<!-- FORGE:GATE_FAILURE:TYPE=review-panel-integrity -->
+## Review Blocked: Incomplete Isolated Review Panel
+
+**Selected isolated reviewers**: ${SELECTED_AGENT_COUNT}
+**Completed isolated reviewers**: ${ACTUAL_AGENT_COUNT}
+
+At least one reviewer could not be dispatched or complete, commonly because the per-session sub-agent pool was exhausted. No inline substitution was performed. Re-run the full panel in a fresh session before merging."
+  [ -n "${MERGE_ISSUE:-}" ] && gh issue edit "$MERGE_ISSUE" {MERGE_GH_FLAG} --add-label "needs-human" 2>/dev/null || true # allowlist:check-command-side-effects
+  exit 1
+fi
+```
 
 #### Domain Diff Slicing
 
@@ -1551,9 +1592,29 @@ When substituting `[FILE_LIST]` in each agent's template:
 ```bash
 gh pr view $ARGUMENTS --json comments --jq '.comments | length'
 gh api repos/{owner}/{repo}/issues/$ARGUMENTS/comments --jq '.[-10:] | .[].body[:100]'
+
+# Every dispatched agent must have delivered its own persisted review to GitHub.
+# Do not infer a clean review from a missing comment: its return text may contain
+# findings that could not be posted because GitHub writes were throttled.
+MISSING_AGENT_COMMENTS=""
+for AGENT in $SELECTED_AGENTS; do
+    AGENT_DOMAIN=$(printf '%s' "$AGENT" | tr '[:upper:]' '[:lower:]')
+    AGENT_COMMENT_COUNT=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" \
+        --jq "[.[] | select(.body | contains(\"<!-- FORGE:REVIEW-AGENT:${AGENT_DOMAIN} -->\"))] | length" \
+        2>/dev/null || printf '0')
+    if [ "${AGENT_COMMENT_COUNT:-0}" -lt 1 ]; then
+        MISSING_AGENT_COMMENTS="${MISSING_AGENT_COMMENTS} ${AGENT_DOMAIN}"
+    fi
+done
+
+if [ -n "$MISSING_AGENT_COMMENTS" ]; then
+    echo "REVIEW DELIVERY FAILURE: missing findings comment(s) for:${MISSING_AGENT_COMMENTS}"
+    echo "Use each agent's returned verdict, findings, and durable body path to recover the review."
+    exit 1
+fi
 ```
 
-**Do NOT proceed until ALL launched agent comments are visible on the PR.**
+**Do NOT proceed until ALL launched agent comments are visible on the PR.** Under OpenCode, each foreground `task(..., background: false)` returns only when that reviewer is complete; verify its corresponding structured PR comment before continuing. A missing comment is an explicit delivery failure: do not synthesize a verdict or treat it as a clean result.
 
 ---
 
@@ -1734,7 +1795,11 @@ FINDING_ISSUE_TITLE="fix: [summary] (review finding — PR #${PR_NUMBER})"
 # 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)
+SCRATCHPAD="${FORGE_SCRATCHPAD:-$PWD/.forge-scratch}"
+REVIEW_AGENT_TOKEN="${AGENT_ID:-${HOSTNAME:-reviewer}-$$}"
+mkdir -p "$SCRATCHPAD"
+FINDING_BODY_MARKER="FORGE:BODY-INTEGRITY:${PR_NUMBER}_review_${REVIEW_AGENT_TOKEN}"
+FINDING_ISSUE_BODY_FILE=$(mktemp "$SCRATCHPAD/${PR_NUMBER}_review_${REVIEW_AGENT_TOKEN}.XXXXXX.md")
 cat <<'ISSUE_EOF' > "$FINDING_ISSUE_BODY_FILE"
 ## Problem
 
@@ -1754,9 +1819,11 @@ cat <<'ISSUE_EOF' > "$FINDING_ISSUE_BODY_FILE"
 **Prevention**: [one sentence — what the builder must do to avoid this class of bug]
 
 <!-- FORGE:PATTERN: [pattern-slug] -->
+<!-- FORGE:CLASS: [pattern-slug] -->
 <!-- This machine-readable tag is used by pipeline-health Phase 4A to count pattern recurrences.
-     When this slug appears on 3+ findings, a check-promotion issue is automatically filed.
-     Keep the slug consistent across all findings for the same defect class. --> <!-- Added: forge#1331 -->
+      When this slug appears on 3+ findings, a check-promotion issue is automatically filed.
+      Keep the slug consistent across all findings for the same defect class. FORGE:CLASS is
+      consumed by orchestrate's P3 batching rule; use a lowercase hyphenated slug. --> <!-- Added: forge#1331, forge#2858 -->
 
 ## Affected Files
 
@@ -1802,6 +1869,7 @@ Files that need changes:
 - [ ] Reproduce or construct proof-of-concept
 [BATCHABLE_ANNOTATION]
 ISSUE_EOF
+printf '\n<!-- %s -->\n' "$FINDING_BODY_MARKER" >> "$FINDING_ISSUE_BODY_FILE"
 
 # FINDING_SEVERITY is extracted from the finding's own **Severity** body field
 # (set above in the heredoc) — example assignment shown here for clarity, same
@@ -1826,19 +1894,22 @@ if [ "$FINDING_PRIORITY_EXIT" -ne 0 ]; then
 else
 
 # --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 \"$FINDING_PRIORITY\" ${MILESTONE_FLAG}")
+ISSUE_SKILL_OUTPUT=$(Skill(skill="issue", args="--title \"$FINDING_ISSUE_TITLE\" --body-file \"$FINDING_ISSUE_BODY_FILE\" --label review-finding --label needs-validation --label \"$FINDING_PRIORITY\" ${MILESTONE_FLAG}"))
+# /issue re-reads the created issue and hard-fails unless this exact marker is present.
 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
+# /issue succeeds only after its API create-token read-back (Phase 4B). Its
+# explicit result marker distinguishes a verified create from an intentional
+# dedup STOP; never use title search to mask a swallowed 403.
+ISSUE_NUM=$(printf '%s\n' "$ISSUE_SKILL_OUTPUT" | sed -n 's/.*ISSUE_CREATE_RESULT:CREATED number=\([0-9][0-9]*\).*/\1/p' | head -1)
+DEDUP_NUMBER=$(printf '%s\n' "$ISSUE_SKILL_OUTPUT" | sed -n 's/.*ISSUE_CREATE_RESULT:DEDUP number=\([0-9][0-9]*\).*/\1/p' | head -1)
+if [ -n "$DEDUP_NUMBER" ]; then
+  ISSUE_NUM="$DEDUP_NUMBER"
+  echo "Review finding deduped against existing issue #${ISSUE_NUM}."
+elif [ -z "$ISSUE_NUM" ]; then
+  echo "ERROR: /issue did not report a verified review-finding number; stopping review instead of silently dropping the finding." >&2
+  exit 1
+fi
 fi
 ```
 
@@ -2131,9 +2202,10 @@ if [ "$PRE_MERGE_HEALTH" = "CONFLICTING" ] || [ "$PRE_MERGE_HEALTH_STATE" = "DIR
 else
 
 # Previously-escalated re-review guard <!-- Added: forge#1810; base-scoped: forge#2570 -->
-# If the linked issue currently carries needs-human, this PR was escalated at some
-# earlier point (VERDICT/purpose-regression/calibration/trust/mergeability) and has
-# now been remediated + re-reviewed back to a clean, mergeable APPROVED state above.
+# If the linked issue currently carries needs-human, or remediation has posted its
+# in-progress marker, this PR was escalated at some earlier point
+# (VERDICT/purpose-regression/calibration/trust/mergeability) and has now been
+# remediated + re-reviewed back to a clean, mergeable APPROVED state above.
 #
 # forge#2570: the hold is now scoped by the PR's target branch. This PR still transitions
 # to workflow:awaiting-merge (clearing needs-human) in BOTH cases below — the transition is
@@ -2146,8 +2218,8 @@ else
 #     uses for the same target branch — no manual click. This reconciles the asymmetry where a
 #     bot-only re-review (authorAssociation=NONE) could never satisfy the strict ≥2 verified-
 #     human bar and so stranded staging PRs the fast lane would auto-merge.
-PREVIOUSLY_ESCALATED=$(gh issue view {MERGE_ISSUE} {MERGE_GH_FLAG} --json labels \
-  --jq '[.labels[].name] | any(. == "needs-human")' 2>/dev/null || echo "false")
+PREVIOUSLY_ESCALATED=$(gh issue view {MERGE_ISSUE} {MERGE_GH_FLAG} --json labels,comments \
+  --jq '([.labels[].name | . == "needs-human"] + [.comments[].body | contains("FORGE:REMEDIATION")]) | any' 2>/dev/null || echo "false")
 GUARD_BASE=$(gh pr view {PR_NUMBER} {MERGE_GH_FLAG} --json baseRefName --jq '.baseRefName' 2>/dev/null || echo "")
 
 if [ "$PREVIOUSLY_ESCALATED" = "true" ]; then
@@ -2355,7 +2427,7 @@ ACTUAL_AGENT_DOMAINS=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" \
 ACTUAL_AGENT_COUNT=$(echo "$ACTUAL_AGENT_DOMAINS" | tr ',' '\n' | grep -c '.' 2>/dev/null)
 ```
 
-Substitute `ACTUAL_AGENT_COUNT`/`ACTUAL_AGENT_DOMAINS` into the summary's `**Agents**: [N] ([names])` field below — do NOT substitute a manually-counted or remembered figure. If the agent's own recollection of what it launched disagrees with `ACTUAL_AGENT_COUNT` (e.g. it believes it ran agents but zero `FORGE:REVIEW-AGENT` comments exist), that mismatch itself is the signal this check exists to surface: report `ACTUAL_AGENT_COUNT` as-is (it is the ground truth) and add a note in the Recommendation section flagging the discrepancy — never suppress it to make the summary look complete. If `ACTUAL_AGENT_COUNT` is `0`, the review degraded to solo/inline mode (the exact failure mode this guard exists to catch) and the verdict MUST reflect that (`NEEDS RE-REVIEW`), regardless of what analysis was performed inline.
+Substitute `ACTUAL_AGENT_COUNT`/`ACTUAL_AGENT_DOMAINS` into the summary's `**Agents**: [N] ([names])` field below — do NOT substitute a manually-counted or remembered figure. Compare it to `SELECTED_AGENT_COUNT` from Phase 3C. If it is smaller, the panel is degraded: the Phase 3C hard-stop path must already have labelled the PR `review-degraded`, added `needs-human`, and exited without a verdict. Never summarize, approve, or merge a partial panel. `ACTUAL_AGENT_COUNT=0` is the same hard stop, not a solo/inline review mode.
 
 ```bash
 gh pr comment $ARGUMENTS --body "$(cat <<'EOF'

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

@@ -109,6 +109,8 @@ if iteration == max_iterations AND result != PASS AND blocker_findings not empty
 Skill("quality-gate", args="{CHANGED_FILES} --worktree {WORKTREE_PATH}")
 ```
 
+**Timeout handling**: The quality-gate's executable checks carry their own explicit timeouts; a `QUALITY-GATE-TIMEOUT` result is a failed gate iteration. Record it as HIGH, do not apply speculative fixes, and proceed to V1-FAIL immediately (post the failure comment, add `needs-human`, return `GATE_PASSED: false`). Do not retry a timed-out check. A wall-time timeout for the in-context `Skill(...)` invocation itself requires native runtime support and is not claimed by this workflow.
+
 **Rules**:
 - Re-run after EVERY fix pass — never trust that fixes resolved findings without verification
 - Each iteration re-scans ALL changed files — fixes can introduce new issues
@@ -138,6 +140,24 @@ Run after quality gate passes. All tool commands are read from `forge.yaml → v
 **Track skipped checks** — initialize before any check runs:
 ```bash
 SKIPPED_CHECKS=""
+
+# Verification commands are project configuration; bound each one so a stalled
+# formatter, typechecker, or build cannot block validation indefinitely.
+# Set FORGEDOCK_VERIFICATION_TIMEOUT_SECONDS to override the 120-second default.
+run_verification_command() {
+    local label="$1" command="$2"
+    local timeout_seconds="${FORGEDOCK_VERIFICATION_TIMEOUT_SECONDS:-120}"
+    if ! [[ "$timeout_seconds" =~ ^[1-9][0-9]*$ ]]; then
+        echo "VERIFY-CONFIG | HIGH | timeout | FORGEDOCK_VERIFICATION_TIMEOUT_SECONDS must be a positive integer (got '$timeout_seconds')"
+        return 2
+    fi
+    timeout "$timeout_seconds" bash -c "$command" 2>&1
+    local command_exit=$?
+    if [ "$command_exit" -eq 124 ]; then
+        echo "VERIFY-TIMEOUT | HIGH | $label | timed out after ${timeout_seconds}s"
+    fi
+    return "$command_exit"
+}
 ```
 
 **Python**:
@@ -146,7 +166,7 @@ cd {WORKTREE_PATH}
 
 PYTHON_FORMAT=$(yq '.verification.commands.python.format // ""' forge.yaml 2>/dev/null || echo '')
 if [ -n "$PYTHON_FORMAT" ]; then
-    eval "$PYTHON_FORMAT" 2>&1
+    run_verification_command "python.format" "$PYTHON_FORMAT"
 else
     echo "SKIPPED — python.format not configured in verification.commands"
     SKIPPED_CHECKS="${SKIPPED_CHECKS:+$SKIPPED_CHECKS, }python.format"
@@ -166,18 +186,19 @@ TS_TYPECHECK=$(yq '.verification.commands.typescript.typecheck // ""' forge.yaml
 TS_BUILD=$(yq '.verification.commands.typescript.build // ""' forge.yaml 2>/dev/null || echo '')
 
 if [ -n "$TS_FORMAT" ]; then
-    eval "$TS_FORMAT" 2>&1
+    run_verification_command "typescript.format" "$TS_FORMAT"
 else
     echo "SKIPPED — typescript.format not configured in verification.commands"
     SKIPPED_CHECKS="${SKIPPED_CHECKS:+$SKIPPED_CHECKS, }typescript.format"
 fi
 
 if [ -n "$TS_TYPECHECK" ]; then
-    eval "$TS_TYPECHECK" 2>&1
+    run_verification_command "typescript.typecheck" "$TS_TYPECHECK"
     TS_EXIT=$?
 elif [ -n "$TS_BUILD" ]; then
-    eval "$TS_BUILD" 2>&1 | tail -30
+    TS_OUTPUT=$(run_verification_command "typescript.build" "$TS_BUILD")
     TS_EXIT=$?
+    echo "$TS_OUTPUT" | tail -30
 else
     echo "SKIPPED — typescript.typecheck and typescript.build not configured in verification.commands"
     SKIPPED_CHECKS="${SKIPPED_CHECKS:+$SKIPPED_CHECKS, }typescript.typecheck/build"

package/commands/work-on/close.md

@@ -139,7 +139,7 @@ The `INVARIANT_ANOMALIES` variable is read in Phase C4.5 (trajectory post) and w
 BODY=$(gh issue view {NUMBER} {GH_FLAG} --json body --jq '.body')
 
 # Count remaining unchecked items BEFORE any edit
-REMAINING_BEFORE=$(echo "$BODY" | grep -c '^- \[ \]' || true)
+REMAINING_BEFORE=$(printf '%s\n' "$BODY" | grep -cE '^[-*+] \[ \]' || true)
 ```
 
 **If `REMAINING_BEFORE == 0`** (no unchecked items): skip body edit — all items already checked, proceed to add PR reference only:
@@ -149,24 +149,54 @@ gh issue edit {NUMBER} {GH_FLAG} --body "{UPDATED_BODY}"
 REMAINING_AFTER=0
 ```
 
-**If `REMAINING_BEFORE > 0`**: check whether ANY `- [ ]` items will still remain after a full check-off — i.e., does the issue have multi-phase structure?
+**If `REMAINING_BEFORE > 0`**: check whether ANY unchecked GFM task items will still remain after a full check-off — i.e., does the issue have multi-phase structure?
+
+Multi-phase issues have **two or more checkbox-bearing sections** — that is, two or more heading-delimited sections that each contain at least one GFM task item. Test that structure directly; do **not** infer it from the presence of headings. Every templated issue carries `## Problem`, `## Evidence`, `## Affected Files`, `## Acceptance Criteria`, and `## Context`, so a heading count is `> 0` universally and says nothing about phase structure. <!-- Fixed: forge#2840 -->
 
-Multi-phase issues have checkbox groups separated by phase headings (lines starting with `##` or `###`) where at least one group has unchecked items. Detect this:
 ```bash
-# Conservative heuristic: if the issue body contains a phase heading (## or ###)
-# AND unchecked items remain, treat as multi-phase — do NOT check off items from
-# future phases; only add the PR reference and leave unchecked items intact.
-HAS_PHASE_HEADINGS=$(echo "$BODY" | grep -cP '^#{2,3} ' || true)
+# Structural test: count heading-delimited sections that contain checkbox items.
+# Multi-phase == 2+ checkbox-bearing sections. A single checkbox group is
+# single-phase regardless of how many prose headings surround it.
+#
+# - Fenced code blocks are stripped first: issue bodies routinely embed fenced
+#   blocks whose lines start with '#' or contain a literal '- [ ]'. An
+#   unterminated fence keeps the original body so later work is never hidden.
+# - ATX headings and setext underlines both delimit sections. The ATX pattern
+#   avoids awk interval-quantifier variance across awk implementations.
+# - grep -E / awk only — no PCRE. '^#+ ' needs none.
+FENCE_COUNT=$(printf '%s\n' "$BODY" | grep -cE '^(```+|~~~+)' || true)
+if [ $(( ${FENCE_COUNT:-0} % 2 )) -ne 0 ]; then
+  BODY_STRIPPED="$BODY"
+else
+  BODY_STRIPPED=$(printf '%s\n' "$BODY" | awk '/^(```+|~~~+)/{f=!f; next} !f')
+fi
 
-if [ "$HAS_PHASE_HEADINGS" -gt 0 ]; then
+CHECKBOX_SECTIONS=$(printf '%s\n' "$BODY_STRIPPED" | awk '
+  /^#+ / { if (in_section && has) n++; in_section=1; has=0; previous=""; next }
+  /^(=+|-+)$/ && previous != "" { if (in_section && has) n++; in_section=1; has=0; previous=""; next }
+  { if (in_section && /^[-*+] \[[ xX]\]/) has=1; previous=$0 }
+  END { if (in_section && has) n++; print n+0 }
+')
+
+# Sub-issue-tracker guard: a decompose parent whose only checkbox group is
+# '## Sub-Issue Tracker' counts 1 section. Checking those off would mark open
+# sub-issues done and close the tracker, so any unchecked GFM task item for an
+# issue forces multi-phase.
+SUBISSUE_ITEMS=$(printf '%s\n' "$BODY_STRIPPED" | grep -cE '^[-*+] \[ \] #[0-9]+' || true)
+
+# Keep this consuming guard synchronized with Phase 6A's Sync invariant in
+# commands/work-on.md.
+# Both counters are default-expanded: a failed extraction yields an empty string,
+# not 0, which would make the integer test error out rather than evaluate false.
+if [ "${CHECKBOX_SECTIONS:-0}" -ge 2 ] || [ "${SUBISSUE_ITEMS:-0}" -gt 0 ]; then
   # Multi-phase issue: do NOT check off any [ ] items
   # Only add the PR reference so progress is recorded
   UPDATED_BODY="${BODY}"$'\n\n'"**PR**: #{PR_NUMBER} → merged to \`{PR_BASE}\` (phase complete — remaining phases open)"
   gh issue edit {NUMBER} {GH_FLAG} --body "{UPDATED_BODY}"
   REMAINING_AFTER="$REMAINING_BEFORE"
 else
-  # Single-phase issue: check off all remaining [ ] items
-  UPDATED_BODY=$(echo "$BODY" | sed 's/^- \[ \]/- [x]/g')
+  # Single-phase issue: check off all remaining GFM task items
+  UPDATED_BODY=$(printf '%s\n' "$BODY" | sed 's/^\([-*+]\) \[ \]/\1 [x]/g')
   UPDATED_BODY="${UPDATED_BODY}"$'\n\n'"**PR**: #{PR_NUMBER} → merged to \`{PR_BASE}\`"
   gh issue edit {NUMBER} {GH_FLAG} --body "{UPDATED_BODY}"
   REMAINING_AFTER=0

package/commands/work-on/decompose.md

@@ -97,7 +97,7 @@ From the Decomposition Assessment in the investigation report, extract:
 3. Brief description for each sub-issue body
 
 For each sub-issue, prepare:
-- **Title**: from investigation report's proposed sub-issue title
+- **Title**: from investigation report's proposed sub-issue title, including the final `{fix|feat|refactor}: ` prefix used in Phase D3
 - **Body**: brief description of scope + `**Parent**: #{NUMBER}` + dependency note if applicable
 - **Labels**: inherit priority label (P0/P1/P2) from parent; do NOT copy workflow labels
 - **Milestone**: same milestone title as parent (if parent has one)
@@ -106,6 +106,38 @@ For each sub-issue, prepare:
 
 ---
 
+## Phase D2.5: Equivalent Set Check
+
+Before creating any sub-issue, check whether the complete planned title set already exists for this parent. This covers an interrupted earlier decomposition: its child issues may exist even though it never reached the `FORGE:DECOMPOSED` comment checked in D1.
+
+```bash
+# SUB_TITLES contains the final, ordered titles prepared in D2.
+EXPECTED_TITLES=$(printf '%s\n' "${SUB_TITLES[@]}" | jq -Rsc 'split("\n") | map(select(length > 0)) | sort')
+PARENT_SUB_ISSUES=$(gh issue list {GH_FLAG} --state all \
+  --search "\"**Parent**: #{NUMBER}\" in:body" --limit 100 --json number,title,body)
+
+# Keep the earliest child for each title as canonical. This also collapses a
+# previously duplicated set without creating a third copy.
+CANONICAL_SUB_ISSUES=$(jq --arg parent "**Parent**: #{NUMBER}" --argjson expected "$EXPECTED_TITLES" '
+  ([.[] | select(.body | contains($parent)) | {number, title}]
+    | sort_by(.number) | group_by(.title) | map(.[0])) as $canonical
+  | ($canonical | map(.title) | sort) as $actual
+  | if $actual == $expected then $canonical else empty end
+' <<< "$PARENT_SUB_ISSUES")
+```
+
+If `CANONICAL_SUB_ISSUES` is non-empty, the decomposition has already created an equivalent set. Do **not** create issues, edit the parent body, or post another decomposition comment. Preserve those original sub-issues and EXIT with:
+
+```
+DECOMPOSE_RESULT:
+  status: ALREADY_DONE
+  sub_issues: {CANONICAL_SUB_ISSUES}
+```
+
+If no exact title-set match exists, continue. A partial set is not equivalent: let `/issue` dedup protect its existing children while creating only the missing work.
+
+---
+
 ## Phase D3: Create Sub-Issues
 
 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 -->

package/commands/work-on/investigate.md

@@ -481,6 +481,36 @@ After the FORGE:INVESTIGATOR comment is posted, create a structured GitHub Gist
 
 **This phase is non-blocking** — if Gist creation fails (auth error, rate limit, network), log the failure and continue to Phase 1D. Do NOT stall the pipeline for a knowledge artifact.
 
+### Step 0: Check cached Gist capability
+
+`FORGE_GIST_CAPABLE` is set once by `/orchestrate` before it dispatches workers. A standalone
+`/work-on` run has no parent cache, so it performs the same read-only identity probe once for its
+own process. GitHub App installation identities are `Bot` users and cannot use the Gists API.
+
+```bash
+if [ -z "${FORGE_GIST_CAPABLE+x}" ]; then
+  GIST_AUTH_TYPE=$(gh api user --jq '.type' 2>/dev/null || true)
+  if [ "$GIST_AUTH_TYPE" = "Bot" ]; then
+    FORGE_GIST_CAPABLE=false
+  else
+    # Preserve the existing behavior when the identity probe is unavailable or is a PAT user.
+    FORGE_GIST_CAPABLE=true
+  fi
+  export FORGE_GIST_CAPABLE
+fi
+
+if [ "$FORGE_GIST_CAPABLE" != "true" ]; then
+  echo "INFO: Knowledge Gist subsystem unavailable for this authentication — skipping Gist phases"
+  GIST_URL=""
+  INDEX_URL=""
+  # Skip every remaining step in Phases 1C.5 and 1C.6; continue directly to Phase 1D.
+fi
+```
+
+When `FORGE_GIST_CAPABLE` is not `true`, do not call `gh gist create`, `gh gist view`,
+`gh gist edit`, or any other Gist command in either Phase 1C.5 or Phase 1C.6. This is an
+informational skip, not a warning, retry, or escalation.
+
 ### Step 1: Check for existing Gist annotation
 
 ```bash
@@ -584,6 +614,9 @@ fi
 
 **Skip if**: The issue has no milestone (`MILESTONE` is `"none"` or empty).
 
+**Also skip if**: `FORGE_GIST_CAPABLE` from Phase 1C.5 is not `true`. Do not independently
+re-probe capability here; the cached result covers both Gist phases.
+
 After the per-issue Knowledge Gist is created (Phase 1C.5), update the milestone-level index Gist. The index aggregates all investigation Gist URLs for a milestone into a single reference document. Any agent working on a milestone issue can fetch one index URL to get full context across all investigations.
 
 **This phase is non-blocking** — if index creation or update fails, log the warning and continue to Phase 1D. Do NOT stall the pipeline for the index.

package/commands/work-on/remediate.md

@@ -20,7 +20,7 @@ argument-hint: "[PR number] [--issue N] [--repo GH_REPO] [--gh-flag GH_FLAG] [--
 
 **Scope note**: This mode owns exactly one gap — re-driving a `needs-human` PR's own remediation. It does NOT implement the `needs-human` sub-label taxonomy (#1815's scope) and it does NOT edit `review-pr.md`'s Phase 8 guard (forge#1810) — that guard's existing safe-default (`workflow:awaiting-merge` on any clean re-review of a previously-escalated PR) is reused as-is; this file only adds a bar-check *after* that guard has already fired.
 
-**Engine coverage** (forge#2379): this subcommand's `command` name (`work-on/remediate`) and completion marker (`FORGE:REMEDIATION:COMPLETE`, including the `**Re-gate outcome**` field Phase M8 posts below) are now registered in the headless engine's phase table — `RESERVED_TYPES.REMEDIATION` in `packages/protocol/src/types.js`, `remediate` in `packages/protocol/src/phases.js`'s `PHASE_IDS`/`PHASE_MARKERS`, and a matching `remediate` entry in `bin/engine/phases.mjs`'s `PHASES` array (`entryCondition`: review committed + `terminalReason: "needs-human"`; `detectOutcome` maps each re-gate outcome to the right terminal reason). **Known limitation, documented in that engine entry's own comment**: a single continuous `runIssue()` walk cannot reach this phase today — `review`'s `"blocked"` outcome and the needs-human divergence guard both terminate the run before `remediate`'s `entryCondition` is ever evaluated. This subcommand therefore continues to run exactly as documented above — as its own separate top-level entry point — until a follow-up issue live-wires the engine to reconstruct state from GitHub for a dedicated remediation run.
+**Engine coverage** (forge#2379, #2889): this subcommand's `command` name (`work-on/remediate`) and completion marker (`FORGE:REMEDIATION:COMPLETE`, including the `**Re-gate outcome**` field Phase M8 posts below) are registered in the headless engine's phase table — `RESERVED_TYPES.REMEDIATION` in `packages/protocol/src/types.js`, `remediate` in `packages/protocol/src/phases.js`'s `PHASE_IDS`/`PHASE_MARKERS`, and a matching `remediate` entry in `bin/engine/phases.mjs`'s `PHASES` array. A blocked review is committed with `terminalReason: "needs-human"`, then the engine continues directly into remediation; the divergence guard permits this specific handoff while keeping all other `needs-human` states paused.
 
 ---
 
@@ -110,7 +110,19 @@ BLOCK_COMMENTS=$(gh api repos/{GH_REPO}/issues/{ISSUE_NUMBER}/comments \
 
 **If the block reason classifies as UNFIXABLE** (and no FIXABLE item accompanies it): do NOT attempt any fix. Skip directly to Phase M8 with verdict `UNFIXABLE`, re-affirm `needs-human` (it should already be present), and return `REMEDIATE_RESULT: status: UNFIXABLE`. This satisfies AC5 — "genuinely-blocked PRs still terminate at `needs-human`."
 
-**If at least one FIXABLE item exists**: proceed to Phase M2.
+**If at least one FIXABLE item exists**: transition the issue out of its terminal gate before proceeding to Phase M2. `needs-human` represents the prior review result, not an active automated remediation run; retaining it would make the dispatcher and recovery paths stop while remediation is in progress. Keep exactly one active workflow state:
+
+```bash
+if [ "${DRY_RUN:-false}" = "true" ]; then
+  echo "DRY_RUN: would replace needs-human with workflow:in-review on issue #{ISSUE_NUMBER}"
+else
+  gh issue edit {ISSUE_NUMBER} {GH_FLAG} \
+    --add-label "workflow:in-review" \
+    --remove-label "needs-human" 2>/dev/null || true # <!-- allowlist:check-command-side-effects -->
+fi
+```
+
+Do not perform this transition for an UNFIXABLE policy escalation. Any later quality-gate, push, or re-review block re-adds `needs-human`; after re-review, remove `workflow:in-review` whenever that terminal label is present.
 
 ---
 
@@ -217,10 +229,33 @@ Note the marker is `<!-- FORGE:REMEDIATION -->` with **no** `:COMPLETE` suffix y
 Skill(skill="review-pr", args="{PR_NUMBER} --auto-merge --issue {ISSUE_NUMBER} --base {PR_BASE} --gh-flag {GH_FLAG}")
 ```
 
-This re-runs the full review (domain agents → verdict → Phase 8 auto-merge gate). Because `{ISSUE_NUMBER}` still carries `needs-human` at this point, one of two things happens inside `review-pr.md`'s existing, **unedited** Phase 8:
+**OpenCode joined-child contract**: When `FORGE_RUNTIME=opencode` (or an OpenCode runtime marker is present), run this required re-review through one native foreground `task`:
+
+```
+if DRY_RUN=true:
+  record "Would invoke the foreground re-review task for PR #{PR_NUMBER}."
+else:
+  task(
+    description="Re-review PR #{PR_NUMBER}",
+    subagent_type="general",
+    background=false,
+    prompt="Load commands/review-pr.md and execute it for PR {PR_NUMBER} with --auto-merge --issue {ISSUE_NUMBER} --base {PR_BASE} --gh-flag {GH_FLAG}. Return only the structured REVIEW_RESULT block after the review reaches its outcome."
+  )
+```
+
+Wait for the completed child result and retain its `REVIEW_RESULT` in remediation state before continuing to Phase M7. A running/progress response is not a completion result. If the child errors or does not return a parseable `REVIEW_RESULT`, stop with `REMEDIATE_RESULT: status: BLOCKED`; do not report remediation in progress as a terminal parent result. The `Skill(...)` invocation above remains the non-OpenCode path.
+
+This re-runs the full review (domain agents → verdict → Phase 8 auto-merge gate). The FIXABLE transition above left the issue at the non-terminal `workflow:in-review` state. `review-pr.md` recognizes the in-progress `FORGE:REMEDIATION` marker posted in Phase M5 as evidence of the prior escalation, so one of two things happens inside Phase 8:
+
+- **Re-escalated**: the re-review itself trips a fresh block (`CHANGES REQUESTED`, purpose-regression, calibration, trust, or a still-`CONFLICTING` mergeability check) → it adds `needs-human`, and this phase removes `workflow:in-review`, leaving one terminal state.
+- **Clean re-review**: `VERDICT=APPROVED`-equivalent, mergeable, and the "Previously-escalated re-review guard" (forge#1810) fires — setting `workflow:awaiting-merge` and removing `workflow:in-review`, *without* auto-merging (that guard's own safe default, left untouched by this file).
 
-- **Re-escalated**: the re-review itself trips a fresh block (`CHANGES REQUESTED`, purpose-regression, calibration, trust, or a still-`CONFLICTING` mergeability check) → `needs-human` remains set, no merge attempted.
-- **Clean re-review**: `VERDICT=APPROVED`-equivalent, mergeable, and the "Previously-escalated re-review guard" (forge#1810) fires — clearing `needs-human` and setting `workflow:awaiting-merge`, *without* auto-merging (that guard's own safe default, left untouched by this file).
+```bash
+POST_REVIEW_LABELS=$(gh issue view {ISSUE_NUMBER} {GH_FLAG} --json labels --jq '[.labels[].name] | join(",")')
+if echo "$POST_REVIEW_LABELS" | grep -qE '(^|,)needs-human(,|$)'; then
+  gh issue edit {ISSUE_NUMBER} {GH_FLAG} --remove-label "workflow:in-review" 2>/dev/null || true # <!-- allowlist:check-command-side-effects -->
+fi
+```
 
 Extract the re-review verdict for the paper trail (Phase M8 reports this verbatim):
 ```bash

package/commands/work-on/review.md

@@ -203,6 +203,15 @@ If `ATTRIBUTION_PR_FOOTER` is `true`, append the following footer to the PR body
 
 ### R2C: Create PR
 
+For a batch issue, construct a non-closing reference line from `BATCH_MEMBERS` before creating the PR:
+
+```bash
+BATCH_MEMBER_REFS=""
+if [ "${IS_BATCH:-0}" = "1" ]; then
+  BATCH_MEMBER_REFS=$(printf 'Refs #%s\n' "${BATCH_MEMBERS[@]}")
+fi
+```
+
 ```bash
 gh pr create {GH_FLAG} \
   --base {PR_BASE} \
@@ -223,6 +232,8 @@ gh pr create {GH_FLAG} \
 ---
 
 Closes #{NUMBER}
+${BATCH_MEMBER_REFS}
+**Batch member disposition**: The batch issue is the code unit being closed. Referenced members that require human or operator action remain open as a split outcome.
 
 **Implementation branch**: \`{BRANCH}\`
 **Base**: \`{PR_BASE}\`
@@ -278,6 +289,22 @@ Invoke the review command:
 Skill(skill="review-pr", args="{PR_NUMBER} --auto-merge --issue {NUMBER} --base {PR_BASE} --gh-flag {GH_FLAG}")
 ```
 
+**OpenCode joined-child contract**: When `FORGE_RUNTIME=opencode` (or an OpenCode runtime marker is present), invoke this load-bearing review through one native foreground `task` instead of treating the `Skill(...)` line as an asynchronous handoff:
+
+```
+if DRY_RUN=true:
+  record "Would invoke the foreground review task for PR #{PR_NUMBER}."
+else:
+  task(
+    description="Review PR #{PR_NUMBER}",
+    subagent_type="general",
+    background=false,
+    prompt="Load commands/review-pr.md and execute it for PR {PR_NUMBER} with --auto-merge --issue {NUMBER} --base {PR_BASE} --gh-flag {GH_FLAG}. Return only the structured REVIEW_RESULT block after the review reaches its outcome."
+  )
+```
+
+Wait for that task's completed result before Phase R4. Propagate its `REVIEW_RESULT` as this module's child state; do not return `REVIEW_RESULT`, report progress, release an orchestrator slot, or begin close work while the child is running. If the child errors or returns no parseable `REVIEW_RESULT`, return `REVIEW_RESULT: status: BLOCKED` with the child failure as the blocker. The normal `Skill(...)` invocation above remains the non-OpenCode path.
+
 /review-pr handles: full domain-agent review → post findings as separate issues (non-blocking) → merge the PR → close the issue → clean up worktree.
 
 ---