forgedock 1.0.22 → 1.1.2

package/commands/orchestrate/config.md

@@ -0,0 +1,67 @@
+---
+install: internal
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# /orchestrate — Configuration, Hard Rules & Multi-Repo Support
+
+Read this file at the start of every `/orchestrate` invocation.
+
+## HARD RULES — READ BEFORE ANYTHING ELSE
+
+1. **Every agent MUST invoke `/work-on` via the Skill tool.** You do NOT write implementation prompts. You copy the Phase 4A template verbatim and fill in the `{VARIABLES}`. Nothing else. No custom prompts. No "just read and edit" shortcuts. The Skill tool invocation is what triggers labels, investigation comments, structured review, and trajectory tracking. Without it, the agent's work has no paper trail and is worthless.
+
+2. **You are a dispatcher, not a builder.** You resolve issues, build the dependency DAG, spawn agents, and report results. You NEVER read code, edit files, or implement fixes yourself.
+
+3. **After each agent completes, verify it used `/work-on`.** Check that completed issues have `workflow:*` labels and structured comments. If an agent bypassed the pipeline, report it as a failure.
+
+---
+
+You are the top-level orchestrator. Your job is to take a batch of issues, plan the execution order, spawn parallel sub-agents (each running the full `/work-on` pipeline), and report consolidated results.
+
+**You have access to ALL tools** — Agent tool (critical), Task tool, Skill tool, Bash, everything. Use the Agent tool aggressively to parallelize work.
+
+**Agent model policy**: `model: "haiku"`, `effort: low` (mechanical — dispatch bookkeeping, lane routing, classification). Fallback: `model: "sonnet"` if rate-limited. User can override with `--model <name>`. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
+**NEVER use plan mode (EnterPlanMode).**
+
+<!-- FORGE:SPEC_LOADED — orchestrate.md loaded and active. Agent is bound by HARD RULES above. -->
+
+---
+
+## Config Resolution
+
+Read `forge.yaml` at the project root to resolve all project-specific variables before running any commands:
+
+```bash
+# Parse forge.yaml for project context
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
+GH_REPO=$(yq '.project.owner + "/" + .project.repo' "$CONFIG_FILE")
+GH_FLAG="-R $GH_REPO"
+REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
+PROJECT_NAME=$(yq '.project.name' "$CONFIG_FILE")
+STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
+DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE")
+# Build satellite repo map from repos.satellites list
+# Each satellite: { prefix, repo, staging_branch }
+```
+
+All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{PROJECT_NAME}`, `{STAGING_BRANCH}`, and `{DEFAULT_BRANCH}` references below are populated from `forge.yaml`.
+
+---
+
+## Multi-Repo Support
+
+This orchestrator supports issues across multiple repositories. See `/work-on` → "Multi-Repo Support" and `forge.yaml → repos` for the full project registry and context variables.
+
+### Cross-Repo Issue References
+
+Issues can be prefixed with a project shorthand derived from `forge.yaml → repos.satellites`:
+- `#123` or `123` → default repo (`{GH_REPO}`)
+- `{satellite_prefix}:5` → satellite repo (e.g., `mcp:5`, `n8n:12`) — prefixes and repos come from `forge.yaml → repos.satellites`
+- `all-repos` → Scan all configured repos for open issues (combine and prioritize)
+
+When spawning sub-agents, pass the project prefix so `/work-on` resolves to the correct repo.
+
+---
+

package/commands/orchestrate/phase-1-resolve.md

@@ -0,0 +1,159 @@
+---
+install: internal
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# /orchestrate — Phase 1: Resolve the Issue Set
+
+## Phase 1: Resolve the Issue Set
+
+Parse `$ARGUMENTS` to determine which issues to work on:
+
+### Input Patterns
+
+| Input | Resolution |
+|-------|------------|
+| `milestone <slug>` | All open issues assigned to that GitHub milestone (default repo) |
+| `#1 #2 #3` or `1 2 3` | Specific issue numbers, optionally repo-prefixed (e.g., `#123 mcp:5 n8n:12`) |
+| `next <N>` | Top N priority open issues (priority:P0 first, then priority:P1, etc.) |
+| `next <N> all-repos` | Top N across ALL ecosystem repos |
+| `fast-lane` or `fast` | All open fast-lane issues (no milestone, bugs/fixes) |
+| `priority:P0` or `priority:P1` | All open issues with that priority label |
+| `mcp:fast` or `n8n:next 3` | Repo-scoped queries |
+| `<slug>` (no keyword) | Try milestone first, then fall back to label search |
+
+### Fetch the issues
+
+For each resolved repo, use the appropriate `-R` flag:
+
+```bash
+# Default repo (no flag needed if using GH_FLAG="" for the default):
+gh issue list {GH_FLAG} --milestone "{TITLE}" --state open --limit 500 --json number,title,labels,milestone --jq '.[] | {number, title, labels: [.labels[].name], milestone: .milestone.title}'
+
+# Satellite repos — always include -R flag with the satellite repo from forge.yaml:
+# For each satellite in forge.yaml → repos.satellites:
+gh issue list -R {SATELLITE_REPO} --milestone "{TITLE}" --state open --limit 500 --json number,title,labels,milestone
+
+# For specific numbers with repo prefix:
+gh issue view {NUMBER} -R {SATELLITE_REPO} --json number,title,labels,state,milestone,body
+
+# For "all-repos" — fetch from all configured repos and combine:
+gh issue list {GH_FLAG} --state open --limit {N} --json number,title,labels,milestone
+# For each satellite in forge.yaml → repos.satellites:
+gh issue list -R {SATELLITE_REPO} --state open --limit 500 --json number,title,labels,milestone
+# Combine, sort by priority, take top N
+```
+
+**Count validation**: After fetching issues, log the count returned. If a milestone query returns exactly 30 issues, warn the user: "WARNING: Exactly 30 issues returned — gh CLI default may have truncated results. Re-running with --limit 500 is recommended." (The --limit 500 above prevents this for standard runs, but verify if the count seems suspiciously low relative to milestone expectations.)
+
+**Tag each issue with its project prefix** in your internal tracking so sub-agents receive the correct repo context.
+
+### Filter out ineligible issues
+
+Remove issues that should NOT be worked on:
+- Already closed or has `workflow:merged` label
+- Has `workflow:invalid` label
+- Has `needs-human` label (requires manual action)
+- Has `workflow:decomposed` label (parent tracker — its sub-issues should be picked up instead)
+- Has `workflow:building` or `workflow:in-review` label (already in progress)
+- Is an epic (`epic` label) — these are planning containers, not buildable
+
+If a `workflow:decomposed` issue is found, automatically expand it to its open sub-issues instead.
+
+### P3 Review-Finding Batching (deterministic grouping rule)
+
+<!-- Added: forge#1333 -->
+
+Before finalizing the issue set, apply the P3 batching rule to reduce full-pipeline overhead on low-severity review findings.
+
+**Trigger conditions** (BOTH must be true to batch):
+1. The issue has labels `review-finding` + `priority:P3`
+2. The issue has `<!-- FORGE:BATCHABLE -->` in its body
+
+**Safety exclusions — NEVER batch** (override all trigger conditions):
+- Issue body contains the word "security" or "billing" anywhere in the title or `## Problem` section
+- Issue has a `security` label
+- Issue has a `billing` label
+
+**Grouping algorithm:**
+```bash
+# Fetch all open batchable P3 issues
+BATCHABLE_P3=$(gh issue list {GH_FLAG} \
+  --state open \
+  --label "review-finding,priority:P3" \
+  --limit 500 \
+  --json number,title,body,labels \
+  --jq '.[] | select(.body | test("<!-- FORGE:BATCHABLE -->"))
+         | select((.title | test("security|billing"; "i")) | not)
+         | select(.body | test("## Problem[\\s\\S]{0,500}(security|billing)"; "i") | not)
+         | select(([.labels[].name] | any(. == "security" or . == "billing")) | not)')
+
+# Group by domain (file-cluster derived from the affected file path in each issue body)
+# Domain is the top-level directory of the first affected file listed under "## Affected Files"
+# e.g., "services/api/auth/login.py" → domain "services/api/auth"
+#        "web/src/app/billing/"     → EXCLUDED (billing path)
+#        "commands/review-pr.md"    → domain "commands"
+```
+
+**Batch creation rule**: When 5+ batchable P3 issues share the same domain, OR when the oldest batchable P3 in a domain exceeds 72 hours, create a single batch issue grouping those issues:
+
+```bash
+BATCH_ISSUE_NUM=$(gh issue create {GH_FLAG} \
+  --title "fix(batch): P3 review findings — {DOMAIN} domain (batch #{BATCH_N})" \
+  --label "review-finding,priority:P3,batch" \
+  --body "$(cat <<'BATCH_EOF'
+## Problem
+
+Batch of P3 review findings in the **{DOMAIN}** domain, grouped to reduce per-finding pipeline overhead.
+
+## Member Findings
+
+<!-- FORGE:BATCH_MEMBERS -->
+{for each member issue: "- [ ] #{NUM}: {TITLE}"}
+<!-- /FORGE:BATCH_MEMBERS -->
+
+## Acceptance Criteria
+
+- [ ] All member findings addressed or closed as false-positive
+- [ ] Member issues auto-closed with reference to this batch PR on merge
+- [ ] No security or billing paths touched (validated before batching)
+
+## Context
+
+**Batch policy**: 5+ open P3 findings in the same domain, or oldest > 72h.
+**Member issues**: #{N1}, #{N2}, #{N3}, ...
+
+<!-- FORGE:BATCHABLE -->
+BATCH_EOF
+)")
+```
+
+**Replace member issues with the batch issue** in the resolved issue set. Member issues are NOT individually dispatched to `/work-on` — the batch issue is the single pipeline unit.
+
+**Important limits**:
+- Max 10 members per batch issue — if more than 10 batchable P3s exist in a domain, create multiple batch issues of ≤ 10 each
+- P1 and P2 issues are NEVER batched — they keep the standard one-issue-one-PR path
+- Batch issues themselves are never nested inside other batch issues
+
+If fewer than 5 batchable P3 findings exist in any domain AND none exceed 72h, skip batch creation entirely — individual P3s run through the standard pipeline.
+
+### CRITICAL: No duplicate detection at orchestrator level
+
+**The orchestrator NEVER closes, merges, or deduplicates issues.** Even if two issues look like duplicates (similar titles, same error message, same symptoms), they may target different code paths, different ORM objects, or different failure modes. Only a `/work-on` investigation agent — after reading the actual code — can determine whether an issue is truly a duplicate.
+
+**What the orchestrator must NOT do:**
+- Close an issue as "duplicate" based on title/symptom similarity
+- Skip an issue because another issue "covers it"
+- Merge two issues into one agent
+- Make ANY judgment about issue validity
+
+**What the orchestrator SHOULD do:**
+- If two issues look related, add a note in the agent prompt: "Note: #{OTHER} has similar symptoms — investigate whether this is the same root cause or a different code path"
+- Let both agents run independently — if one finds it's truly a duplicate, `/work-on`'s investigation phase will close it as invalid with evidence
+- Flag potential overlap in the DAG plan for the user's awareness, but NEVER act on it
+
+**Why**: Surface-level similarity hides critical differences. #3842 (api_key.id lazy load) and #4039 (user.id lazy load) had identical error messages but targeted completely different ORM objects. Closing #4039 as a "duplicate" would have left a customer-impacting P0 bug unfixed.
+
+---
+

package/commands/orchestrate/phase-2-triage.md

@@ -0,0 +1,126 @@
+---
+install: internal
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# /orchestrate — Phase 2: Investigation-First Triage
+
+## Phase 2: Investigation-First Triage
+
+**Purpose**: Investigation issues produce NEW GitHub issues as their output. If the batch contains investigations, they must run FIRST so their output can be folded into the execution plan.
+
+**If no investigations are found in Step 2A, skip this entire phase and proceed directly to Phase 3.**
+
+### Step 2A: Classify each issue
+
+For each issue in the resolved set, read its title and body to classify it:
+
+```bash
+for NUM in {issue_numbers}; do
+  gh issue view $NUM --json title,body,labels --jq '{title: .title, labels: [.labels[].name], body_preview: (.body[:500])}'
+done
+```
+
+**Classification rules:**
+
+| Signal | Classification |
+|--------|---------------|
+| Title contains "Investigate", "Audit", "Research", "Evaluate", "Assess", "Deep dive" | **Investigation** |
+| Issue body is primarily questions (`- [ ]` checklist) with no concrete code changes | **Investigation** |
+| Issue body says "Deliverable: execution plan" or "create issues" | **Investigation** |
+| Issue has `enhancement` label + title starts with "Enable" + body describes toggling a feature flag | **Implementation** |
+| Issue has `bug`, `refactor`, `dead-code`, or `feature` label | **Implementation** |
+
+Tag each issue internally as `INVESTIGATION` or `IMPLEMENTATION`.
+
+### Step 2B: Run investigations first (Wave 0)
+
+If ANY issues are classified as `INVESTIGATION`:
+
+1. **Move them to Wave 0** — they run BEFORE all implementation issues
+2. **Spawn Wave 0 agents** using the same agent template as Phase 4A, but emphasize that `/work-on` will detect the investigation task type and produce issues (not code)
+3. **Wait for ALL Wave 0 agents to complete** before proceeding to Phase 3
+
+### Step 2C: Collect newly created issues
+
+After Wave 0 completes, each investigation agent will have created new GitHub issues. Collect them:
+
+```bash
+# For each investigation issue that completed successfully:
+# Read the FORGE:BUILDER comment to find created issue numbers
+for INV_NUM in {investigation_numbers}; do
+  gh api repos/{GH_REPO}/issues/${INV_NUM}/comments \
+    --jq '.[] | select(.body | contains("<!-- FORGE:BUILDER -->")) | .body' \
+    | grep -oP '#\K\d+' | sort -u
+done
+
+# Also check: if the investigation issue had a milestone, the new issues should too
+# Verify milestone assignment:
+for NEW_NUM in {newly_created_numbers}; do
+  gh issue view $NEW_NUM --json milestone --jq '.milestone.title // "NO MILESTONE"'
+done
+```
+
+### Step 2C.5: Collect Knowledge Gist URLs from investigations
+
+For each completed investigation issue, query its comments for `FORGE:KNOWLEDGE_GIST` annotations. Store the mapping of investigation issue number → Gist URL(s) so the agent template in Step 4A can include prior investigation context.
+
+```bash
+# Build a map: investigation_number → gist_url(s)
+declare -A INVESTIGATION_GISTS
+for INV_NUM in {investigation_numbers}; do
+  GIST_URLS=$(gh api repos/{GH_REPO}/issues/${INV_NUM}/comments \
+    --jq '[.[] | select(.body | test("<!-- FORGE:KNOWLEDGE_GIST: https://")) | .body | capture("<!-- FORGE:KNOWLEDGE_GIST: (?<url>https://[^ ]+) -->").url] | unique | .[]')
+  if [ -n "$GIST_URLS" ]; then
+    INVESTIGATION_GISTS[$INV_NUM]="$GIST_URLS"
+    echo "Investigation #${INV_NUM}: found Gist URL(s)"
+  fi
+done
+```
+
+When spawning agents for implementation issues in Step 4A, include any Gist URLs from parent/sibling investigations in the agent prompt's context block. See the `{GIST_CONTEXT}` variable in the agent template.
+
+**Milestone index Gist**: If the milestone has a `<!-- FORGE:MILESTONE_INDEX: {url} -->` annotation in its description, read the index URL and store it for inclusion in agent context. The milestone index aggregates all investigation Gist URLs for the milestone into a single reference.
+
+```bash
+# Read milestone index URL from milestone description (if milestone exists)
+MILESTONE_INDEX_URL=""
+if [ -n "$MILESTONE_NUM" ]; then
+  MILESTONE_DESC=$(gh api repos/{GH_REPO}/milestones/${MILESTONE_NUM} --jq '.description // ""' 2>/dev/null)
+  MILESTONE_INDEX_URL=$(echo "$MILESTONE_DESC" | grep -oP '(?<=<!-- FORGE:MILESTONE_INDEX: )https://[^ ]+(?= -->)' | head -1)
+  if [ -n "$MILESTONE_INDEX_URL" ]; then
+    echo "Milestone index Gist found: ${MILESTONE_INDEX_URL}"
+  fi
+fi
+```
+
+### Step 2D: Merge new issues into the batch
+
+Add the newly created issues to the issue set. Re-check each one:
+- Filter out any that are already ineligible (same rules as Phase 1)
+- Tag them as `IMPLEMENTATION` (investigations don't spawn more investigations)
+- They inherit the milestone from their parent investigation if applicable
+
+**Issue body standard**: Any new issues created by investigation agents MUST use the **Pipeline Issue Template** from `issue.md` Phase 3D as their body structure. Investigation agents that produce issues as output should be prompted to use that template — not ad-hoc body formats — so every spawned issue enters the pipeline with the correct structure (Problem, Root Cause, Affected Files, Acceptance Criteria). Verify spawned issues have all mandatory sections before adding them to the batch; if sections are missing, the `/issue` body-validation step (Phase 4C.5) will repair them. <!-- Added: forge#293 -->
+
+**Updated issue set** = original `IMPLEMENTATION` issues + newly spawned issues from investigations.
+
+### Step 2E: Report Wave 0 results to user
+
+```
+## Wave 0: Investigations Complete
+
+| # | Investigation | Result | Issues Created |
+|---|--------------|--------|---------------|
+| #{INV1} | {title} | ✓ Closed | #{N1}, #{N2}, #{N3} |
+| #{INV2} | {title} | ✓ Closed | #{N4}, #{N5} |
+
+**New issues added to batch**: {count}
+**Updated total**: {original_count} → {new_total} issues
+
+Proceeding to dependency analysis with the expanded issue set...
+```
+
+---
+

package/commands/orchestrate/phase-2.5-synthesis.md

@@ -0,0 +1,156 @@
+---
+install: internal
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# /orchestrate — Phase 2.5: Investigation Synthesis
+
+## Phase 2.5: Investigation Synthesis
+
+<!-- Added: forge#1192 -->
+
+**Purpose**: Reconcile *competing recommendations* across investigation outputs BEFORE they fan out to implementation agents. Phase 3's conflict detection (Step 3C) deconflicts issues at the **file** layer only — it prevents git merge conflicts. It performs **zero semantic deconfliction**: two issues can touch entirely different files while proposing **contradictory approaches to the same problem**, and the file-overlap detector passes both straight to parallel dispatch. This phase closes that gap by clustering investigations semantically (by target subsystem, not by file) and arbitrating incompatible plans into a single decision — or serializing them so the second agent inherits the first's decision.
+
+**This phase operates ONLY on FORGE annotations and issue bodies. It NEVER reads code, and it NEVER closes, skips, or merges issues.** Reconciling plans/annotations is distinct from adjudicating *duplicate validity* (Safety Rule 9, the #3842/#4039 scar): the anti-dedup rule forbids the orchestrator from deciding two issues are the same bug and closing one — that call belongs to `/work-on` investigation agents examining actual code. Plan reconciliation touches neither code nor issue state; it only writes a synthesis brief annotation and adds `Depends on #X` serialization edges. It therefore does not violate Hard Rule 2 (dispatcher, not builder) or Safety Rule 9.
+
+**No-op guard**: This entire phase is skipped when the batch contains **0 or 1 investigations** — there is nothing to reconcile against. Proceed directly to Phase 3.
+
+### Step 2.5A: No-op guard
+
+```bash
+# Count investigations that completed in Wave 0 (Phase 2), regardless of whether each
+# emitted a Knowledge Gist. Use the full completed-investigation set (the same
+# {investigation_numbers} that Steps 2C.5, 2.5B and 2.5C iterate) — NOT the
+# INVESTIGATION_GISTS map, which only holds gist-producing investigations and would
+# undercount when a genuine investigation reached a recommendation without a gist.
+# If < 2, skip synthesis entirely.
+INVESTIGATION_NUMS=( {investigation_numbers} )
+INVESTIGATION_COUNT=${#INVESTIGATION_NUMS[@]}
+if [ "$INVESTIGATION_COUNT" -lt 2 ]; then
+  echo "Phase 2.5 skipped: ${INVESTIGATION_COUNT} investigation(s) in batch — nothing to reconcile. Proceeding to Phase 3."
+  SYNTHESIS_RAN=false
+  RECONCILED_COUNT=0
+  # Skip to Phase 3.
+else
+  SYNTHESIS_RAN=true
+fi
+```
+
+If `SYNTHESIS_RAN` is false, do NOT execute Steps 2.5B–2.5D — proceed directly to Phase 3. Step 4A's `{GIST_CONTEXT}` generation will fall back to the existing raw-gist behavior (no synthesis brief exists).
+
+### Step 2.5B: Cluster investigations by target subsystem
+
+For each investigation that completed in Wave 0, read its `FORGE:INVESTIGATOR` comment (and the newly spawned implementation issue bodies from Step 2D) and extract its **Recommendation** and **Affected Files / target subsystem** — NOT to compare files for merge conflicts, but to group investigations that operate on the **same conceptual surface** (e.g. "auth session lifecycle", "credit metering", "orchestrate DAG construction").
+
+```bash
+# For each investigation, pull its recommendation + affected-files block (annotations only — no code reads)
+declare -A INV_RECOMMENDATION
+declare -A INV_SUBSYSTEM
+for INV_NUM in {investigation_numbers}; do
+  INV_BODY=$(gh api repos/{GH_REPO}/issues/${INV_NUM}/comments \
+    --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body' 2>/dev/null | head -1)
+  # Extract the Recommendation section (annotation prose only)
+  INV_RECOMMENDATION[$INV_NUM]=$(echo "$INV_BODY" | awk '/^### Recommendation/{p=1;next}/^### /{p=0}p')
+  # Derive a coarse subsystem tag from Affected Files directories + title keywords
+  INV_SUBSYSTEM[$INV_NUM]=$(echo "$INV_BODY" \
+    | grep -oP '`[^`]+/[^`]+`' | xargs -r -n1 dirname 2>/dev/null | sort | uniq -c | sort -rn | head -1)
+done
+```
+
+**Cluster rule**: Two investigations are in the same cluster when they share a target subsystem (overlapping affected-file directories OR the same domain tag from Step 3B applied to their recommendations). Clustering is by **conceptual surface**, deliberately coarser than Step 3C's file-level analysis — the goal is to surface plan-level contradictions the file layer cannot see.
+
+**Forward reference — related future signal** <!-- Added: forge#1196 -->: This clustering step (Step 2.5B) runs before Phase 3, so no Layer 5 data exists yet at this point — do not treat it as an input here. For readers extending this clustering rule in the future: Step 3C Layer 5 (historical co-change coupling, computed later in Phase 3) is a related signal worth reusing — two investigations whose affected files have historically co-changed would be good candidates for the same subsystem cluster. This is purely a forward reference, not a functional dependency or phase-reordering.
+
+### Step 2.5C: Detect and resolve competing recommendations
+
+Within each cluster (2+ investigations on the same subsystem), compare the **Recommendation** sections for incompatibility — e.g. one recommends adding a cache layer while another recommends removing caching from the same path; one proposes a new abstraction another proposes to delete. This is a semantic comparison of *proposed approaches*, read purely from the annotation prose.
+
+For each detected conflict, resolve it in exactly ONE of two ways:
+
+1. **Arbitration decision** — When the two recommendations are directly incompatible and one is clearly correct given the combined evidence, record a single deconflicted decision for BOTH issues. State which approach wins and why. This decision is written into each affected issue's `FORGE:SYNTHESIS_BRIEF` (Step 2.5D) — it does NOT close either issue; both still run, but against a reconciled plan.
+2. **Serialization edge** — When the approaches are interdependent (the second issue's correct approach depends on what the first decides) or arbitration cannot pick a winner from annotations alone, add a `Depends on #{FIRST}` marker to the SECOND issue's body so the two serialize. The second agent then inherits the first's merged result during its own investigation/context phase.
+
+```bash
+# Serialization is expressed as a standard "Depends on #X" edge so Step 3A consumes it
+# with no new plumbing (see Step 3A dependency-marker parsing).
+RECONCILED_COUNT=0
+N_ARBITRATED=0
+N_SERIALIZED=0
+for CONFLICT in "${DETECTED_CONFLICTS[@]}"; do
+  # CONFLICT = "FIRST SECOND RESOLUTION" where RESOLUTION is "arbitrate" or "serialize"
+  set -- $CONFLICT; FIRST=$1; SECOND=$2; RESOLUTION=$3
+  if [ "$RESOLUTION" = "serialize" ]; then
+    # Reverse-direction cycle guard: before adding "#SECOND depends on #FIRST", check
+    # whether #FIRST already declares "Depends on #SECOND". If it does, the requested
+    # edge would close a 2-node cycle (#FIRST -> #SECOND -> #FIRST) that Step 3D.5's
+    # cycle detector would later have to exclude from dispatch entirely (both issues
+    # stuck behind needs-human). Skip the edge and fall back to arbitration-in-place
+    # instead, so both issues still run.
+    FIRST_BODY=$(gh issue view $FIRST -R {GH_REPO} --json body --jq '.body')
+    if echo "$FIRST_BODY" | grep -qiE "depends on #${SECOND}\b"; then
+      echo "Phase 2.5: skipping serialization edge #${FIRST} -> #${SECOND}: reverse edge #${SECOND} -> #${FIRST} already exists (would create a cycle). Falling back to arbitration-in-place."
+      RESOLUTION="arbitrate"
+    else
+      SECOND_BODY=$(gh issue view $SECOND -R {GH_REPO} --json body --jq '.body')
+      if ! echo "$SECOND_BODY" | grep -qiE "depends on #${FIRST}\b"; then
+        gh issue edit $SECOND -R {GH_REPO} \
+          --body "${SECOND_BODY}
+
+Depends on #${FIRST}
+<!-- Serialized by orchestrate Phase 2.5: competing recommendation reconciled via dependency edge. -->"
+      fi
+    fi
+  fi
+  # Re-check RESOLUTION (may have been downgraded from "serialize" to "arbitrate" above)
+  # so the breakdown counters and the Step 2.5D per-issue decision recording both reflect
+  # the resolution that was actually applied, not the one originally proposed.
+  if [ "$RESOLUTION" = "serialize" ]; then
+    N_SERIALIZED=$((N_SERIALIZED + 1))
+  else
+    N_ARBITRATED=$((N_ARBITRATED + 1))
+  fi
+  RECONCILED_COUNT=$((RECONCILED_COUNT + 1))
+done
+echo "Phase 2.5 reconciled ${RECONCILED_COUNT} competing recommendation(s) (${N_ARBITRATED} arbitrated, ${N_SERIALIZED} serialized)."
+```
+
+**MUST NOT**: close, skip, or merge any issue on the basis of a detected conflict. Two issues with competing recommendations are BOTH valid work items — Phase 2.5 makes their plans coherent, it does not eliminate either. (This is the Safety Rule 9 boundary — see the Purpose note above.)
+
+### Step 2.5D: Emit one deconflicted brief per issue
+
+For each implementation issue about to be dispatched, write a single `FORGE:SYNTHESIS_BRIEF` annotation containing ONLY the reconciled context relevant to *that* issue — the arbitration decisions affecting it and pointers to the specific sibling investigation Gists it actually needs. This replaces injecting the entire aggregated milestone-index gist (which forces each agent to independently re-arbitrate the same contradictions, wasting tokens and producing nondeterministic cross-PR incoherence).
+
+```bash
+for ISSUE_NUM in {implementation_issue_numbers}; do
+  # Assemble the per-issue brief: arbitration decisions touching this issue's subsystem +
+  # only the relevant sibling gist URLs (not the full milestone-index dump)
+  BRIEF_BODY="Reconciled context for this issue (see orchestrate Phase 2.5):
+${PER_ISSUE_DECISIONS[$ISSUE_NUM]}"
+  gh issue comment $ISSUE_NUM -R {GH_REPO} --body "<!-- FORGE:SYNTHESIS_BRIEF -->
+## Synthesis Brief
+
+${BRIEF_BODY}
+
+<!-- FORGE:SYNTHESIS_BRIEF:COMPLETE -->"
+done
+```
+
+The `FORGE:SYNTHESIS_BRIEF` annotation is consumed by Step 4A's `{GIST_CONTEXT}` generation (which prefers it over the raw milestone-index gist when present) and its reconciled count (`RECONCILED_COUNT`) feeds the Step 6B `Competing recommendations reconciled (Phase 2.5)` metric.
+
+**Report**: Post a brief Phase 2.5 summary to the user before proceeding to Phase 3:
+
+```
+## Phase 2.5: Investigation Synthesis
+
+**Investigations reconciled**: {INVESTIGATION_COUNT}
+**Competing recommendations detected**: {RECONCILED_COUNT}
+  - Arbitrated in place: {N_ARBITRATED} (includes any serialization edges downgraded by the reverse-cycle guard)
+  - Serialized via dependency edge: {N_SERIALIZED}
+**Per-issue synthesis briefs emitted**: {N_briefs}
+
+Proceeding to dependency analysis with a deconflicted plan set...
+```
+
+---
+