forgedock 1.7.0 → 1.8.0

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

@@ -49,16 +49,11 @@ Include the audit summary in the final report (Phase 6). Key metrics to surface:
 
 ```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 '[]')
+  # Use Step 4A's read_active_claims() helper (re-declare it verbatim here when this
+  # phase runs in a fresh context). Releases are separate later comments, so checking
+  # for CLAIM_RELEASED inside the claim body would retain every released claim.
+  ACTIVE_CLAIMS=$(read_active_claims "$COORD_ISSUE_NUMBER" 2>/dev/null \
+    | jq '[.[].holder // "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
@@ -87,4 +82,3 @@ fi
 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

@@ -1,4 +1,5 @@
 ---
+
 install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -208,6 +209,7 @@ Sweep (Step 4F.2.5) once the batch is no longer fully gated.
 | #{F} | {title} | original | ⏸ Awaiting Merge | #{PR} | staging |
 | #{E} | {title} | original | ⏭ Skipped (dep) | — | — |
 | #{G} | {title} | original | 🔗 Blocked-on-Merge (gated by #{PRED}) | — | — |
+| #{H} | {title} | original | ⚠ Review Panel Degraded | #{PR} | {target} |
 
 `⏸ Awaiting Merge` (`workflow:awaiting-merge`) is structurally distinct from `⚠ Blocked`
 (`needs-human`): a Blocked row means the pipeline hit something it cannot resolve on its own
@@ -223,6 +225,17 @@ was abandoned. A Blocked-on-Merge row means the work is queued and will auto-dis
 the gating predecessor's PR merges — no manual `/orchestrate` re-run required. Never render a
 blocked-on-human-merge dependent as `⏭ Skipped (dep)`.
 
+### Degraded Review Panels
+
+{IF any PR reviewed during this batch has the `review-degraded` label:}
+| Issue | PR | Target | Required action |
+|-------|----|--------|-----------------|
+| #{NUM} | #{PR} | {target} | Re-run the complete isolated review panel in a fresh session |
+
+These PRs are not eligible to merge or deploy. A dispatch-pool failure produced an incomplete panel, so no inline or partial-panel verdict is accepted.
+
+{ELSE: omit this section entirely.}
+
 {IF `MERGE_READY_PRS` (Step 6A.5) is non-empty:}
 
 ### Merge-Ready — {N} PR(s) awaiting only a human merge
@@ -286,12 +299,14 @@ current session's live wake pick them up automatically if it is still running).
 {list of cosmetic deferred issue numbers and titles}
 
 ### Summary
+- **Knowledge Gists**: {IF FORGE_GIST_CAPABLE == "false": "Skipped - unavailable for the batch authentication (informational)." ELSE: "Available."}
 - **Investigations**: {N} completed, spawned {M} new issues
 - **Review findings**: {N} spawned, {M} resolved in-batch, {K} swept, {J} deferred (cosmetic), {L} deferred (gen2), {IDLE_POLICY_DEFERRED_COUNT} deferred (idle policy, forge#1814)
 - **Succeeded**: {N} issues resolved (implementation + sweep)
 - **Failed**: {N} issues need attention
 - **Merge-ready**: {#MERGE_READY_PRS[@]:-0} PRs awaiting only a human merge (see "Merge-Ready" section above)
 - **Blocked-on-merge**: {#BLOCKED_ON_MERGE[@]:-0} issues queued behind a human-gated predecessor, will auto-dispatch on merge (see "Blocked-on-Merge" section above)
+- **Degraded review panels**: {N} PRs require a fresh full-panel re-review before merge/deploy
 - **Skipped**: {N} issues (dependency failures)
 
 ### Post-Batch Cleanup
@@ -325,6 +340,11 @@ current session's live wake pick them up automatically if it is still running).
 | Findings deferred — idle policy (forge#1814) | {IDLE_POLICY_DEFERRED_COUNT} (batch fully human-gated at defer time — see Step 4B item 6.7) |
 | P3 findings clubbed (surface-area batching, forge#1818) | {SURFACE_BATCH_COUNT:-0} batch(es) covering {#SURFACE_BATCHED_FINDINGS[@]:-0} finding(s) — see Step 4C |
 | Findings deferred — token budget (forge#1858) | {#TOKEN_DEFERRED[@]:-0} (batch spend {BATCH_TOKEN_SPEND:-0}/{TOKEN_BUDGET:-uncapped} tokens — see Step 4C) |
+| Full-repo intake (`policy: all`) | {FULL_REPO_SWEEP_COUNT:-0} sweep completion mark; {#FULL_REPO_INTAKE[@]:-0} newly-seen actionable issues admitted |
+| Automated alerts deduplicated | {AUTOMATED_DUPLICATES_CLOSED:-0} closed; canonical issue retained and linked for each |
+| **Cascade amplification** | **{FINDINGS_SPAWNED:-0}/{MERGED_UNITS:-0} = {AMPLIFICATION_RATIO:-0} findings per merged unit** |
+| Amplification composition | {#REFINEMENT_FINDINGS[@]:-0} same-lineage refinements; {#NEW_SURFACE_FINDINGS[@]:-0} new-surface findings |
+| Amplification bound | {CASCADE_MAX_AMPLIFICATION:-off}; {#AMPLIFICATION_DEFERRED[@]:-0} same-lineage refinements deferred to completion sweep |
 | Competing recommendations reconciled (Phase 2.5) | {RECONCILED_COUNT} (investigation plans arbitrated in place + serialized) |
 | Findings validated | {N} |
 | False positives | {N} ({%}) |
@@ -334,12 +354,19 @@ current session's live wake pick them up automatically if it is still running).
 | Actual spend (best-effort telemetry) | ${ACTUAL_SPEND:-—} |
 | Issues deferred (budget ceiling) | {#DEFERRED_BUDGET_ISSUES[@]:-0} |
 | ε-reserve issued (no-prior dispatch) | {EPSILON_DISPATCHED:-no} |
+| Top-level workers dispatched | ${TOP_LEVEL_DISPATCH_TOTAL:-0} |
+| Subagent spawns planned (8 per worker) | ${PLANNED_SUBAGENT_SPAWNS:-0} |
+| Subagent spawns observed | ${OBSERVED_SUBAGENT_SPAWNS:-unavailable} |
 | **Value-weighted throughput** | **{VALUE_THROUGHPUT:-—} value-pts/USD** |
 
 `value-weighted throughput` = Σ(priority_weight × danger_zone_weight) for **merged** issues ÷ actual spend (USD). A higher value means more high-priority issues were resolved per dollar. Trend this across runs via `/pipeline-health` to measure the economic scheduling ROI. <!-- Added: forge#1743 -->
 
 `P3 findings clubbed` and `Findings deferred — token budget` are a DIFFERENT mechanism from the `$`-denominated `Budget limit`/`Projected spend`/`Actual spend`/`Issues deferred (budget ceiling)` rows above (forge#1743, opt-in `--budget N` flag, gates the *original* issue dispatch order). The token-budget row reads the always-on, token-denominated ceiling that scopes ONLY to Step 4C's review-finding cascade dispatch (forge#1858); `SURFACE_BATCH_COUNT` and `SURFACE_BATCHED_FINDINGS` are populated by the same Step 4C surface-area-batching block (forge#1818) that clubs P3 findings sharing a file/leaf-directory into one dispatched pipeline. Both degrade gracefully to `0`/`uncapped` when the batch had no review findings or ran with defaults. <!-- Added: forge#1858 -->
 
+**Cascade amplification detail**: render one row per `FINDINGS_BY_SOURCE_PR` entry: `| PR #{source} | {finding count} | {refinement count} | {new-surface count} |`. A ratio at or above 1.0 means the batch is not reducing its open-work count through merges alone; it does **not** mean the findings are low-value. Include any convergence warning and state that the default `max_amplification: off` never defers findings. When an opt-in bound deferred a refinement, list it under Completion Sweep as re-evaluable rather than silently omitting it.
+
+For `policy: all`, include the full-repo intake counts and list each automated duplicate with its canonical issue. A sweep measures all new open issues, including CI alerts without `review-finding`; it must not claim that the cascade ratio alone measures total queue growth.
+
 **Compute value-weighted throughput** (populate before rendering the table):
 
 ```bash
@@ -433,4 +460,3 @@ the Summary section above. `BATCH_ELAPSED` is the wall-clock duration of the orc
 (Step 6B `Duration`), not the sum of per-issue elapsed times.
 
 ---
-

package/commands/orchestrate/safety.md

@@ -11,7 +11,7 @@ install: core
 1. **Every agent MUST invoke `/work-on` via the Skill tool.** No custom prompts. No manual implementation. Copy the Phase 4A template, fill in variables, done. (See HARD RULES at top of file.)
 2. **NEVER merge anything to `main`** — agents merge to `staging` or `milestone/{slug}` only
 3. **Concurrency is capped by default (12 in-flight agents)** <!-- Updated: forge#1912 --> — file overlap and dependencies still determine which issues are *eligible* to run in parallel, but Phase 4 never dispatches more than `MAX_CONCURRENT` at once (default 12); the rest queue and dispatch as running agents complete. Set `forge.yaml → orchestration.max_concurrent` to raise or lower the cap (see Engine mode § Concurrency model, and `phase-4-execution.md` Step 4A-pre.0.2).
-4. **Always confirm with user before launching** — Step 3E is the mandatory checkpoint
+4. **Always confirm with user before launching** — Step 3E is the mandatory checkpoint. Headless callers must pass the explicit `--auto` or `--confirm` authorization; OpenCode must not infer confirmation from a completed preflight.
 5. **No retries** — if an agent fails, report it and move on
 6. **Respect existing work** — skip issues already being worked on (`workflow:building`, `workflow:in-review`)
 7. **Dependency failures cascade** — if A fails and B depends on A, all transitive dependents of A are skipped (not attempted)

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] [--auto|--confirm]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -9,8 +9,46 @@ argument-hint: "[milestone <slug> | #1 #2 #3 | next <N> | fast-lane | priority:P
 
 **Input**: $ARGUMENTS
 
+`--auto` and `--confirm` authorize the dispatch checkpoint; they are control
+flags, not part of the issue-set query. `--deep-plan` requests the full analysis
+path, and `--max-concurrent N` only tunes the dispatch cap.
+
 This file is the slim dispatcher. Detailed phase content lives in `commands/orchestrate/`.
 
+## OpenCode Preflight
+
+When `FORGE_RUNTIME=opencode` (or an OpenCode runtime marker is present), run the
+deterministic preflight at `$FORGE_HOME/bin/orchestrate-preflight.mjs` immediately,
+before reading `orchestrate/config.md`, this workflow, or any phase spec. The helper
+resolves the repository from `forge.yaml`, including a parent config when the target
+is a nested Git worktree:
+
+```bash
+node "$FORGE_HOME/bin/orchestrate-preflight.mjs" \
+  --repo "$GH_REPO" \
+  --args "$ARGUMENTS"
+```
+
+The preflight is a compact mechanical adapter for issue resolution, eligibility,
+explicit dependencies, scoped issue-body file overlap, database serialization, and
+the initial ready queue. If it returns a supported plan with `requiresDeepPlan: false`
+and `confirmed: true`, launch `dispatchNow` with native background `task` calls
+immediately. Without an explicit `--auto` or `--confirm` argument, present the
+compact plan and ask for one confirmation; after the user confirms, launch the
+plan's ready queue without re-reading the large phase files. Do not load the full
+Phase 3 or Phase 4 prose just to ask that question.
+
+Continue through the phase files when the plan says `requiresDeepPlan`, the input is
+unsupported, preflight fails, or a task-result event requires recovery. This adapter
+never closes, deduplicates, or edits issues; the full shared workflow remains the
+authority for investigations, review-finding cascade handling, recovery, cleanup,
+and reporting.
+
+For a supported compact OpenCode plan, stop after the fast-path dispatch. The phase
+execution order below is the fallback path for deep plans, unsupported inputs,
+preflight failures, and task-result recovery; do not read it merely to confirm or
+dispatch a compact plan.
+
 ## Execution Order
 
 Read and execute phases in sequence. Each phase file is self-contained.

package/commands/quality-gate.md

@@ -246,6 +246,12 @@ echo "Applicable domains: $DOMAINS"
 
 Run ONLY the checks whose domain was identified in Step 1.5. Skip checks for domains not present in the `DOMAINS` list.
 
+**Execution budget**: Set `FORGEDOCK_QUALITY_GATE_TIMEOUT_SECONDS` to configure the
+per-check budget (default: 30 seconds). Set `FORGEDOCK_VERIFICATION_TIMEOUT_SECONDS`
+to configure formatter, typecheck, and build commands (default: 120 seconds). Both
+values must be positive integers. A timeout emits a structured HIGH finding and fails
+the gate rather than leaving the workflow blocked.
+
 - **2A (Security)**: Run if `SECURITY` in DOMAINS *(always — included for all code files)*
 - **2B (Auth)**: Run if `AUTH` in DOMAINS
 - **2C (Deploy chain)**: Run if `DEPLOY` in DOMAINS
@@ -715,9 +721,9 @@ Do NOT suppress the finding by making the check less strict or adding fake no-op
 ```bash
 # 2G.9: Danger-zone recurrence check
 # Step 1: Read injected danger-zone cards from FORGE:CONTEXT comment on the issue
-CONTEXT_COMMENT=$(gh api repos/{GH_REPO}/issues/{ISSUE_NUMBER}/comments \
+CONTEXT_COMMENT=$(timeout 10 gh api repos/{GH_REPO}/issues/{ISSUE_NUMBER}/comments \
   --jq '[.[] | select(.body | contains("<!-- FORGE:CONTEXT -->"))] | last | .body // ""' 2>/dev/null \
-  | timeout 10 cat || echo '')
+  || echo '')
 
 # Extract the Danger-Zone Rule Cards section
 DZ_SECTION=$(echo "$CONTEXT_COMMENT" \
@@ -1302,6 +1308,11 @@ done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$')
 ```bash
 REGISTRY_FILE="{WORKTREE_PATH}/scripts/check-registry/manifest.json"
 REGISTRY_FINDINGS=""
+QUALITY_GATE_TIMEOUT_SECONDS="${FORGEDOCK_QUALITY_GATE_TIMEOUT_SECONDS:-30}"
+if ! [[ "$QUALITY_GATE_TIMEOUT_SECONDS" =~ ^[1-9][0-9]*$ ]]; then
+    echo "QUALITY-GATE-CONFIG | HIGH | timeout | FORGEDOCK_QUALITY_GATE_TIMEOUT_SECONDS must be a positive integer (got '$QUALITY_GATE_TIMEOUT_SECONDS')"
+    QUALITY_GATE_TIMEOUT_SECONDS=30
+fi
 
 if [ ! -f "$REGISTRY_FILE" ]; then
     echo "2R: No check registry found at $REGISTRY_FILE — skipping registry checks."
@@ -1332,11 +1343,15 @@ else
                 continue
             fi
 
-            # Run the check; pass changed files list and worktree path
-            CHECK_OUTPUT=$("$SCRIPT_PATH" "{CHANGED_FILES}" "{WORKTREE_PATH}" 2>/dev/null)
+            # Bound every third-party check. Exit 124 is timeout's documented code.
+            CHECK_OUTPUT=$(timeout "$QUALITY_GATE_TIMEOUT_SECONDS" "$SCRIPT_PATH" "{CHANGED_FILES}" "{WORKTREE_PATH}" 2>/dev/null)
             CHECK_EXIT=$?
 
-            if [ "$CHECK_EXIT" -eq 1 ]; then
+            if [ "$CHECK_EXIT" -eq 124 ]; then
+                REGISTRY_FINDINGS="${REGISTRY_FINDINGS}
+REGISTRY-${SLUG}-timeout | HIGH | (check-registry) | Registry check '$SLUG' timed out after ${QUALITY_GATE_TIMEOUT_SECONDS}s — failing closed. Investigate and optimize the script before proceeding."
+                echo "2R: TIMEOUT — $SLUG (${QUALITY_GATE_TIMEOUT_SECONDS}s) — fail-closed HIGH finding added"
+            elif [ "$CHECK_EXIT" -eq 1 ]; then
                 # Check fired — append to findings
                 while IFS= read -r line; do
                     [ -z "$line" ] && continue
@@ -1383,6 +1398,11 @@ if [[ "$ADAPTIVE_DIR_NORM" != "${WORKTREE_NORM}/"* ]]; then
 fi
 
 GATED_FINDINGS=""
+QUALITY_GATE_TIMEOUT_SECONDS="${FORGEDOCK_QUALITY_GATE_TIMEOUT_SECONDS:-30}"
+if ! [[ "$QUALITY_GATE_TIMEOUT_SECONDS" =~ ^[1-9][0-9]*$ ]]; then
+    echo "QUALITY-GATE-CONFIG | HIGH | timeout | FORGEDOCK_QUALITY_GATE_TIMEOUT_SECONDS must be a positive integer (got '$QUALITY_GATE_TIMEOUT_SECONDS')"
+    QUALITY_GATE_TIMEOUT_SECONDS=30
+fi
 
 if [ "$ADAPTIVE_ENABLED" != "false" ]; then
     GATE_D_DIR="${ADAPTIVE_DIR}/gate.d"
@@ -1411,17 +1431,17 @@ if [ "$ADAPTIVE_ENABLED" != "false" ]; then
                     continue
                 fi
 
-                # Run with per-script 30s timeout; pass diff path and worktree root
+                # Run with the configured per-script timeout; pass diff path and worktree root
                 # timeout exit code 124 = timed out; treat as fail-closed (HIGH finding)
-                GATE_OUTPUT=$(timeout 30 bash "$script" "$DIFF_PATH" "{WORKTREE_PATH}" 2>/dev/null)
+                GATE_OUTPUT=$(timeout "$QUALITY_GATE_TIMEOUT_SECONDS" bash "$script" "$DIFF_PATH" "{WORKTREE_PATH}" 2>/dev/null)
                 GATE_EXIT=$?
 
                 if [ "$GATE_EXIT" -eq 124 ]; then
                     # Timeout — fail closed: block the gate with HIGH finding
-                    TIMEOUT_FINDING="GATD-${SLUG}-timeout | HIGH | (gate.d) | gate.d script '$SLUG' timed out after 30s — failing closed. Investigate and optimize the script or increase timeout via gate.d contract."
+                    TIMEOUT_FINDING="GATD-${SLUG}-timeout | HIGH | (gate.d) | gate.d script '$SLUG' timed out after ${QUALITY_GATE_TIMEOUT_SECONDS}s — failing closed. Investigate and optimize the script or increase the configured timeout."
                     GATED_FINDINGS="${GATED_FINDINGS}
 ${TIMEOUT_FINDING}"
-                    echo "2R.5: TIMEOUT — $SLUG (30s) — fail-closed HIGH finding added"
+                    echo "2R.5: TIMEOUT — $SLUG (${QUALITY_GATE_TIMEOUT_SECONDS}s) — fail-closed HIGH finding added"
                 elif [ "$GATE_EXIT" -eq 1 ]; then
                     # Script fired — findings on stdout
                     while IFS= read -r line; do
@@ -1453,7 +1473,7 @@ If any gate.d check produces findings, include them in the Step 3 findings list
 - `$2` = absolute path to the worktree root
 - stdout = findings lines, one per line: `SLUG | HIGH|MEDIUM|LOW | FILE | MESSAGE`
 - Exit 0 = no findings / passed; Exit 1 = findings emitted; Exit 2 = inapplicable (diff has no relevant content)
-- 30-second wall-time budget enforced by quality-gate; timeout = fail-closed HIGH finding
+- `FORGEDOCK_QUALITY_GATE_TIMEOUT_SECONDS` wall-time budget (30 seconds by default) enforced by quality-gate; timeout = fail-closed HIGH finding
 - Do NOT write to disk, do NOT make network requests, do NOT modify any files
 
 ---

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

@@ -29,6 +29,12 @@ 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-Backed GitHub Write Integrity
+
+When staging a body for `gh issue create|edit` or `gh pr create|comment` with `--body-file`, use the session scratchpad (or a repo-relative scratch directory) rather than a generic path under shared `/tmp`; native Windows `gh` may not resolve Git Bash `/tmp` reliably. The filename must contain the issue or PR number and an agent-unique token, and `mktemp` must add a random suffix. Add exactly one caller-chosen marker to the body: `<!-- FORGE:BODY-INTEGRITY:<entity>_<role>_<agent-token> -->`.
+
+Immediately after the write, re-read the issue, PR, or posted comment and assert that it contains that exact marker. Treat a missing marker as a hard error and stop. A unique filename reduces collision risk, but only the read-back detects another agent's plausible-looking content being posted in its place; do not rely on a visual review. The `/issue` programmatic contract performs this assertion for its `--body-file` callers.
+
 ## 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 -->
@@ -145,6 +151,12 @@ Every finding must include:
 
 **All review agents MUST include a machine-readable findings block at the end of their PR comment.** This is NON-OPTIONAL. Without structured findings, the review system cannot create GitHub issues, and findings die as unread PR comments. Every finding that doesn't become a GitHub issue is a finding that will never be addressed.
 
+### Persist Before Post
+
+GitHub is a delivery channel, not the sole record of a review. Before the first `gh pr comment` attempt, write the finalized complete review body, including its `<!-- FORGE:REVIEW-AGENT:{domain} -->` marker and structured findings block, to a uniquely named durable file such as `${TMPDIR:-/tmp}/forge-review-${PR_NUMBER}-${DOMAIN}-$$.md`. Use `gh pr comment --body-file "$REVIEW_BODY_PATH"`; do not construct a retry loop around a failed write.
+
+Every agent MUST return its verdict, finding count, and one line per finding to the orchestrator even when posting succeeds. If the post fails, return the durable body path and the same finding summary, then stop. A 403 or other write failure is a failed delivery, not a clean review and not a reason to retry in the background.
+
 ### Format
 
 Append this block at the very end of your comment (after the `---` footer line, still inside the EOF heredoc). It uses HTML comments so it's invisible in rendered markdown:
@@ -163,6 +175,7 @@ Append this block at the very end of your comment (after the `---` footer line,
 6. **Summary**: Concise one-line description (no pipe `|` characters in summary)
 7. **Empty block**: If no findings at all, include just the START/END markers
 8. **HTML comments**: The block is invisible in rendered markdown but parseable by the review system
+9. **Agent marker**: Include exactly one `<!-- FORGE:REVIEW-AGENT:{domain} -->` marker in the persisted body, where `{domain}` is the lowercase dispatched domain.
 
 ### Domain Prefixes
 

package/commands/review-pr-agents.md

@@ -19,6 +19,14 @@ the `prompt` argument to whichever tool the orchestrator resolved (`Task(...)` o
 same per-agent isolation and the same requirement that each agent posts structured findings to the PR
 directly (`gh pr comment`) rather than relaying them through the orchestrator's own context.
 
+**OpenCode override**: When `FORGE_RUNTIME=opencode` or an equivalent OpenCode marker is present, the
+orchestrator must set `DISPATCH_TOOL=task` before checking literal Claude tool names. A native task
+argument is shaped as `{ description: "...", prompt: "...", subagent_type: "general"|"explore", background: false }`:
+use `general` for implementation/review and `explore` for read-only discovery. The `Neither tool is
+available` hard stop applies only when lowercase native `task` is genuinely absent; it must not be
+triggered by the absence of `Task` and `Agent` names in an OpenCode session. If native `task` is absent,
+post `FORGE:REVIEW_BLOCKED` and never replace the isolated review with inline work.
+
 <!-- FORGE:PROTOCOL_SOURCE — canonical definition lives in docs/spec/review-protocol.md -->
 
 ---

package/commands/review-pr-staging.md

@@ -23,9 +23,28 @@ Performs comprehensive review of `staging` before merging to `main`. Handles lar
 
 This spec dispatches Bug Hunter and domain review agents via a sub-agent-spawning tool. Different runtimes expose different tools for this — resolve deterministically, once per invocation, and use the same tool for every dispatch call in this run:
 
+### 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. (Identical resolution logic to `/review-pr` Phase 3C — do not diverge.)
 2. **Else if `Agent` is available**: set `{DISPATCH_TOOL} = Agent`. This is the documented fallback, not a degraded path — use it exactly as you would `Task`: one call per selected agent (Bug Hunters in Phase 3, Code Quality in Phase 4, domain agents in Phase 5), same prompt template, `subagent_type: "general-purpose"` (or the closest equivalent the environment offers), same requirement that each agent posts its own findings directly to the PR via `gh pr comment`. Isolation and fresh-context review are preserved either way.
 3. **Neither tool is available**: this is a genuine setup defect, not a routing decision — HARD STOP, post a PR/issue comment explaining that no sub-agent dispatch tool is available, add `needs-human`, and exit without posting a verdict. Do NOT fall back to reviewing inline in the orchestrator's own context.
+4. **Dispatch pool exhausted or dispatch call fails**: this is not tool absence. If any Bug Hunter, quality, domain, material-change, or regression reviewer cannot be launched because the sub-agent pool/session limit is exhausted (or any dispatch call fails), HARD STOP. Do not substitute inline review or silently continue with a partial panel. Mark the PR `review-degraded`, post `<!-- FORGE:GATE_FAILURE:TYPE=review-panel-integrity -->` with the selected and completed counts, and exit without a deploy verdict. A fresh session must re-run the full 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.
 
@@ -180,9 +199,17 @@ ALL_PR_NUMBERS=$(echo "$BUNDLE_PRS $MERGE_PRS" | tr ' ' '\n' | sort -u | grep -E
 
 echo "PRs in staging→main bundle: $(echo $ALL_PR_NUMBERS | tr '\n' ' ')"
 
-# Step 2: For each PR in the bundle, check for open review-finding issues
+# Step 2: For each PR in the bundle, check for open review-finding issues and degraded panels
 BLOCKING_FINDINGS=""
+DEGRADED_REVIEWS=""
 for pr_num in $ALL_PR_NUMBERS; do
+  IS_REVIEW_DEGRADED=$(gh pr view "$pr_num" -R {GH_REPO} --json labels \
+    --jq '[.labels[].name] | any(. == "review-degraded")' 2>/dev/null || echo "false")
+  if [ "$IS_REVIEW_DEGRADED" = "true" ]; then
+    DEGRADED_REVIEWS="${DEGRADED_REVIEWS}
+**PR #${pr_num}** has a \`review-degraded\` label and requires a full fresh-context re-review."
+  fi
+
   # Search for open review-finding issues that reference this PR
   OPEN_FINDINGS=$(gh issue list -R {GH_REPO} \
     --label "review-finding" \
@@ -199,6 +226,27 @@ ${OPEN_FINDINGS}"
   fi
 done
 
+# A degraded panel is a review-integrity failure, not a finding that an override may waive.
+if [ -n "$DEGRADED_REVIEWS" ]; then
+  echo "⛔ DEPLOY BLOCKED — An included PR has an incomplete isolated review panel."
+  echo "$DEGRADED_REVIEWS"
+  if [ -n "$PR_NUMBER" ]; then
+    gh pr comment "$PR_NUMBER" -R {GH_REPO} --body "<!-- FORGE:GATE_FAILURE -->
+## Deploy Gate: BLOCKED
+
+**Gate**: review-panel-integrity
+
+### Degraded Review Panels
+
+${DEGRADED_REVIEWS}
+
+Re-run the complete review panel in a fresh session before deployment.
+
+<!-- FORGE:GATE_FAILURE:TYPE=review-panel-integrity -->" 2>/dev/null || true
+  fi
+  exit 1
+fi
+
 # Step 3: Block deploy if open findings exist (unless human override present)
 if [ -n "$BLOCKING_FINDINGS" ]; then
   # Check for human override comment on the staging→main PR
@@ -385,7 +433,7 @@ For fixable failures: checkout staging, apply fix, verify locally, commit as `fi
 
 Launch agent (model: {SUBAGENT_MODEL}) to analyze all commits since last deploy. Categorize as: NEW FEATURE, ENHANCEMENT, BUG FIX, REFACTOR, SECURITY, PERFORMANCE, INFRASTRUCTURE, DEPENDENCY. Separate user-facing vs internal. Document breaking changes and required pre-deploy actions.
 
-**MANDATORY — post findings as PR comment**: After completing analysis, the agent MUST post its full report directly to the PR:
+**MANDATORY — post findings as PR comment**: Before its first post attempt, the agent MUST persist the final report to a uniquely named durable file, then post it with `--body-file`. It MUST also return verdict, finding count, and one line per finding to the orchestrator whether the post succeeds or fails; on failure, return the file path and stop without retrying. After completing analysis, the agent posts its full report directly to the PR:
 ```bash
 gh pr comment ${PR_NUMBER} -R ${GH_REPO} --body "<!-- FORGE:REVIEW-AGENT:material-change -->
 ## Material Change Analysis
@@ -410,7 +458,7 @@ Launch Bug Hunter agents for each service with changes:
 
 **Web Bug Hunter** (web/src/): React issues (keys, closures, hydration), data fetching, security (XSS), UX, build-breaking patterns, type issues. Prefix: FE.
 
-Each reads the service diff, hunts for bugs, traces context across imports, posts findings with structured block.
+Each reads the service diff, hunts for bugs, traces context across imports, persists its finalized report before posting, and returns its verdict and findings independently of GitHub delivery.
 
 **MANDATORY — each Bug Hunter agent MUST post its findings directly to the PR immediately upon completion** (do not wait for the orchestrator to batch-post):
 ```bash
@@ -431,7 +479,7 @@ Where `{service}` is `api`, `worker`, or `web`. Post one comment per service age
 
 Agent hunts for: dead code, duplicate logic, complexity (>50 line functions), naming issues, missing abstractions, logging quality, magic numbers. Prefix: QA.
 
-**MANDATORY — post findings as PR comment**: After completing analysis, the agent MUST post its full report directly to the PR:
+**MANDATORY — post findings as PR comment**: Before its first post attempt, the agent MUST persist the final report to a uniquely named durable file, then post it with `--body-file`. It MUST also return verdict, finding count, and one line per finding to the orchestrator whether the post succeeds or fails; on failure, return the file path and stop without retrying. After completing analysis, the agent posts its full report directly to the PR:
 ```bash
 gh pr comment ${PR_NUMBER} -R ${GH_REPO} --body "<!-- FORGE:REVIEW-AGENT:code-quality -->
 ## Code Quality Review
@@ -488,7 +536,7 @@ fi
 
 Launch domain-specific agents based on which domains have changes. Substitute PR diff commands with staging diff commands. Agents: General Security (always), Auth, Billing, Concurrency, Scraper, API Design, Database, Infrastructure.
 
-**MANDATORY — each domain agent MUST post its findings directly to the PR immediately upon completion** (not batched by the orchestrator):
+**MANDATORY — each domain agent MUST persist its finalized body before posting its findings directly to the PR immediately upon completion** (not batched by the orchestrator). It MUST return verdict, finding count, and one line per finding to the orchestrator independently of delivery; if posting fails, return the durable file path and stop without retrying:
 ```bash
 gh pr comment ${PR_NUMBER} -R ${GH_REPO} --body "<!-- FORGE:REVIEW-AGENT:{domain} -->
 ## {Domain} Review
@@ -507,7 +555,7 @@ Where `{domain}` is `security`, `auth`, `billing`, `concurrency`, `scraper`, `ap
 
 Agent maps dependencies, assesses integration points (service boundaries, env vars, Docker changes, workflow sibling drift between ci.yml and deploy-production.yml), evaluates rollback difficulty (easy/hard/destructive/state-dependent), checks test coverage. Posts risk matrix with rollback plan. Prefix: REG.
 
-**MANDATORY — post findings as PR comment**: After completing analysis, the agent MUST post its full report directly to the PR:
+**MANDATORY — post findings as PR comment**: Before its first post attempt, the agent MUST persist the final report to a uniquely named durable file, then post it with `--body-file`. It MUST also return verdict, finding count, and one line per finding to the orchestrator whether the post succeeds or fails; on failure, return the file path and stop without retrying. After completing analysis, the agent posts its full report directly to the PR:
 ```bash
 gh pr comment ${PR_NUMBER} -R ${GH_REPO} --body "<!-- FORGE:REVIEW-AGENT:regression-risk -->
 ## Regression Risk Assessment
@@ -664,8 +712,51 @@ If the gate exits with `RESULT: BLOCK DEPLOY` → **STOP**. A `<!-- FORGE:GATE_F
 
 ---
 
+**Incomplete-panel guard (MANDATORY):** Increment `SELECTED_AGENT_COUNT` for every reviewer selected across Phases 2–6 before launching it. If any dispatch fails, set `DISPATCH_FAILED=true`. Before Phase 7, count unique `FORGE:REVIEW-AGENT` markers. If the completed count is lower than selected, follow the same hard-stop path as pool exhaustion: create `review-degraded` if needed, label the PR, post `FORGE:GATE_FAILURE`, and exit. Do not create a deploy verdict from partial reviewer output.
+
+```bash
+ACTUAL_AGENT_COUNT=$(gh api "repos/${GH_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 "$GH_REPO" 2>/dev/null || true
+  gh pr edit "$PR_NUMBER" -R "$GH_REPO" --add-label "review-degraded" --add-label "needs-human" 2>/dev/null || true # allowlist:check-command-side-effects
+  gh pr comment "$PR_NUMBER" -R "$GH_REPO" --body "<!-- FORGE:GATE_FAILURE:TYPE=review-panel-integrity -->
+## Deploy Review Blocked: Incomplete Isolated Review Panel
+
+**Selected isolated reviewers**: ${SELECTED_AGENT_COUNT}
+**Completed isolated reviewers**: ${ACTUAL_AGENT_COUNT}
+
+Re-run the full staging review in a fresh session before deployment."
+  exit 1
+fi
+```
+
 ## Phase 7: Finding Triage & Issue Creation
 
+### Phase 6.75: Verify Agent Delivery
+
+Before launching every Phase 2-6 review agent, append its lowercase marker domain (for example, `security`, `bug-hunter-api`, or `regression-risk`) to `LAUNCHED_REVIEW_AGENTS`. A completed agent is accounted for only when its corresponding marker comment is present on the PR.
+
+```bash
+MISSING_AGENT_COMMENTS=""
+for AGENT_DOMAIN in $LAUNCHED_REVIEW_AGENTS; do
+  AGENT_COMMENT_COUNT=$(gh api "repos/${GH_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 "Recover each agent's returned verdict, findings, and durable body path before rerunning review."
+  exit 1
+fi
+```
+
+Missing comments are an explicit failure, never evidence of no findings. Do not triage or synthesize a deploy verdict while any launched agent is unaccounted for.
+
 ### 7A: Extract Findings
 From PR comments, extract structured findings (`<!-- FINDING:... -->`). If none found, scan for unstructured findings. If still 0 → skip to Phase 8.
 
@@ -716,7 +807,11 @@ STAGING_FINDING_TITLE="chore: [summary] (staging review — PR #${PR_NUMBER})"
 # this is no longer required for safety — but strip it anyway so the raw title
 # stays readable if it round-trips through any other eval-based consumer.
 STAGING_FINDING_TITLE=$(printf '%s' "$STAGING_FINDING_TITLE" | tr '`' "'" | sed 's/\$(/$ (/g')
-STAGING_FINDING_BODY_FILE=$(mktemp)
+SCRATCHPAD="${FORGE_SCRATCHPAD:-$PWD/.forge-scratch}"
+REVIEW_AGENT_TOKEN="${AGENT_ID:-${HOSTNAME:-reviewer}-$$}"
+mkdir -p "$SCRATCHPAD"
+STAGING_FINDING_BODY_MARKER="FORGE:BODY-INTEGRITY:${PR_NUMBER}_staging-review_${REVIEW_AGENT_TOKEN}"
+STAGING_FINDING_BODY_FILE=$(mktemp "$SCRATCHPAD/${PR_NUMBER}_staging-review_${REVIEW_AGENT_TOKEN}.XXXXXX.md")
 cat <<'ISSUE_EOF' > "$STAGING_FINDING_BODY_FILE"
 ## Problem
 
@@ -750,6 +845,7 @@ Files that need changes:
 - [ ] Finding validated: VALIDATED / FALSE_POSITIVE / INCONCLUSIVE
 - [ ] If VALIDATED: fix implemented and tested on correct branch
 ISSUE_EOF
+printf '\n<!-- %s -->\n' "$STAGING_FINDING_BODY_MARKER" >> "$STAGING_FINDING_BODY_FILE"
 
 # STAGING_FINDING_SEVERITY is extracted from the finding's own **Severity**
 # body field (set above in the heredoc) — example assignment shown here for
@@ -776,18 +872,22 @@ else
 # --label is repeatable (not comma-joined) per the /issue programmatic contract.
 # ${MILESTONE_FLAG} carries the Phase 7D derivation through — empty string is
 # a no-op arg when the reviewed branch has no milestone (plain staging→main).
-Skill(skill="issue", args="--title \"$STAGING_FINDING_TITLE\" --body-file \"$STAGING_FINDING_BODY_FILE\" --label review-finding --label needs-validation --label staging-review --label \"$STAGING_FINDING_PRIORITY\" ${MILESTONE_FLAG}")
+ISSUE_SKILL_OUTPUT=$(Skill(skill="issue", args="--title \"$STAGING_FINDING_TITLE\" --body-file \"$STAGING_FINDING_BODY_FILE\" --label review-finding --label needs-validation --label staging-review --label \"$STAGING_FINDING_PRIORITY\" ${MILESTONE_FLAG}"))
+# /issue re-reads the created issue and hard-fails unless this exact marker is present.
 rm -f "$STAGING_FINDING_BODY_FILE"
 
-# /issue has no machine-readable return contract — resolve the created issue's number by
-# exact-title search immediately after the call (title embeds ${PR_NUMBER} + summary, unique
-# enough for a reliable single-match lookup). Retry to absorb GitHub Search API indexing lag.
-ISSUE_NUM=""
-for _resolve_attempt in 1 2 3; do
-  ISSUE_NUM=$(gh issue list -R {GH_REPO} --search "in:title \"${STAGING_FINDING_TITLE}\"" --state open --limit 1 --json number --jq '.[0].number // empty')
-  [ -n "$ISSUE_NUM" ] && break
-  sleep 2
-done
+# /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; do not 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 "Staging review finding deduped against existing issue #${ISSUE_NUM}."
+elif [ -z "$ISSUE_NUM" ]; then
+  echo "ERROR: /issue did not report a verified staging review-finding number; stopping review instead of silently dropping the finding." >&2
+  exit 1
+fi
 fi
 ```