forgedock 1.1.1 → 1.1.2

package/commands/forge-stats.md

@@ -1,6 +1,6 @@
 ---
 description: Track command sizes, detect bloat, compare against baselines and thresholds
-argument-hint: [diff | baseline | full]
+argument-hint: [diff | baseline | full | cost]
 install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -8,7 +8,7 @@ install: internal
 
 # /forge-stats — Prompt Bloat Tracker
 
-**Input**: $ARGUMENTS (default: `diff`)
+**Input**: $ARGUMENTS (default: `diff`; modes: `diff`, `baseline`, `full`, `cost`)
 
 Tracks the size of every Forge command file over time. Detects bloat by comparing current sizes against the git-tracked baseline and per-command thresholds.
 
@@ -194,3 +194,122 @@ If 3+ commands repeat the same instruction block (e.g., "how to create a worktre
 
 ### 4. Remove motivational padding
 Emojis, ALL CAPS warnings, "YOU MUST", "CRITICAL", "NO EXCEPTIONS" — these are noise. Sonnet follows clear instructions, not emphasis. Replace 5 lines of warnings with 1 line of instruction.
+
+---
+
+## Mode: `cost`
+
+Report raw cost-per-issue, cost-per-stage, and cost-per-agent-tier by reading `FORGE:DECISION_RECORD` annotations from merged PRs. **Raw numbers only** — no trend dashboards, no automated regression-flagging, no visualization. Respects the open-core boundary defined in `devdocs/project/architecture.md` (trend analytics are a Platform value-add).
+
+```bash
+cd "$FORGE_HOME"
+
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
+GH_REPO=$(yq e '.project.owner + "/" + .project.repo' "$CONFIG_FILE")
+
+echo "=== Forge Cost Report — $(date +%Y-%m-%d) ==="
+echo "Repo: $GH_REPO"
+echo ""
+
+# Fetch all merged PRs (last 50) and extract their FORGE:DECISION_RECORD JSON blocks
+RECORDS=$(gh pr list -R "$GH_REPO" --state merged --limit 50 --json number \
+  --jq '.[].number' 2>/dev/null | while read pr; do
+    gh api "repos/$GH_REPO/issues/$pr/comments" \
+      --jq '.[] | select(.body | contains("FORGE:DECISION_RECORD")) | .body' 2>/dev/null
+done)
+
+if [ -z "$RECORDS" ]; then
+  echo "No FORGE:DECISION_RECORD annotations found in the last 50 merged PRs."
+  echo "(Older issues predate the cost block — no data to report.)"
+  exit 0
+fi
+
+# Extract cost blocks via Python (handles missing cost block gracefully)
+echo "$RECORDS" | python3 - <<'PYEOF'
+import sys, re, json
+
+records = []
+for block in sys.stdin.read().split("<!-- FORGE:DECISION_RECORD -->"):
+    m = re.search(r'```json\s*(\{.*?\})\s*```', block, re.DOTALL)
+    if not m:
+        continue
+    try:
+        data = json.loads(m.group(1))
+    except json.JSONDecodeError:
+        continue
+    records.append(data)
+
+if not records:
+    print("No parseable FORGE:DECISION_RECORD JSON found.")
+    sys.exit(0)
+
+print(f"Parsed {len(records)} FORGE:DECISION_RECORD annotation(s).\n")
+
+has_cost = [r for r in records if r.get("cost")]
+no_cost  = [r for r in records if not r.get("cost")]
+
+print(f"  With cost block   : {len(has_cost)}")
+print(f"  Without cost block: {len(no_cost)} (older annotations — no data)")
+print()
+
+if not has_cost:
+    print("No cost data available. Cost blocks are written starting with #1296.")
+    sys.exit(0)
+
+# Per-issue raw cost
+print("--- Cost Per Issue ---")
+print(f"{'Issue':<10} {'PR':<8} {'Total ($)':<12} {'Stages'}")
+print(f"{'-----':<10} {'--':<8} {'---------':<12} {'------'}")
+for r in sorted(has_cost, key=lambda x: x.get("issue", 0)):
+    cost = r.get("cost", {})
+    total = cost.get("total_usd", "n/a")
+    stages = cost.get("stages", {})
+    stage_str = ", ".join(f"{k}: ${v}" for k, v in stages.items()) if stages else "n/a"
+    print(f"  #{r.get('issue','?'):<8} #{r.get('pr','?'):<6} {str(total):<12} {stage_str}")
+
+print()
+
+# Per-stage aggregate
+stage_totals = {}
+for r in has_cost:
+    for stage, val in (r.get("cost", {}).get("stages") or {}).items():
+        try:
+            stage_totals[stage] = stage_totals.get(stage, 0.0) + float(val)
+        except (TypeError, ValueError):
+            pass
+
+if stage_totals:
+    print("--- Cost Per Stage (aggregate) ---")
+    for stage, total in sorted(stage_totals.items()):
+        print(f"  {stage:<20}: ${total:.4f}")
+    print()
+
+# Per-agent-tier aggregate
+tier_totals = {}
+for r in has_cost:
+    for tier, val in (r.get("cost", {}).get("agent_tiers") or {}).items():
+        try:
+            tier_totals[tier] = tier_totals.get(tier, 0.0) + float(val)
+        except (TypeError, ValueError):
+            pass
+
+if tier_totals:
+    print("--- Cost Per Agent Tier (aggregate) ---")
+    for tier, total in sorted(tier_totals.items()):
+        print(f"  {tier:<20}: ${total:.4f}")
+    print()
+
+# Summary
+if has_cost:
+    totals = [float(r["cost"]["total_usd"]) for r in has_cost if r.get("cost", {}).get("total_usd") not in (None, "unavailable")]
+    if totals:
+        print(f"Issues with cost data: {len(totals)}")
+        print(f"  Total cost (window) : ${sum(totals):.4f}")
+        print(f"  Average per issue   : ${sum(totals)/len(totals):.4f}")
+        print(f"  Min / Max           : ${min(totals):.4f} / ${max(totals):.4f}")
+PYEOF
+```
+
+**Scope constraint**: This mode reports raw numbers sourced from `FORGE:DECISION_RECORD` annotations only. No new data source is invented. Trend visualization, regression-flagging, and alerting logic are Platform features — do not add them here. If a cost block is absent (older annotations predating #1296), report "no data" rather than erroring.
+
+<!-- Added: forge#1297 -->

package/commands/forgedock-init.md

@@ -11,7 +11,7 @@ argument-hint: [--preserve | --interactive | --section <name>]
 
 You complete the `forge.yaml` configuration that `npx forgedock init` started. The CLI generates required sections (project, paths, branches) from auto-detection. Your job is to scan the codebase, query GitHub APIs, and produce a complete `forge.yaml` with every applicable optional section filled — using detected values directly, without asking for confirmation.
 
-**Agent model policy**: Default `model: "sonnet"`. Fallback: `model: "opus"` if Sonnet is rate-limited.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
 
 ---

package/commands/geo-audit.md

@@ -1,5 +1,6 @@
 ---
 description: "Run a GEO audit — check AI referral traffic, page compliance, and auto-create improvement issues"
+install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -12,6 +13,8 @@ You are the GEO (Generative Engine Optimization) auditor. Pull AI referral data
 
 **NEVER use plan mode (EnterPlanMode)** — it breaks execution context.
 
+<!-- FORGE:SPEC_LOADED — geo-audit.md loaded and active. Agent is bound by this spec. -->
+
 ---
 
 ## Phase 0: Load Config

package/commands/incident-response.md

@@ -1,6 +1,7 @@
 ---
 description: Coordinate P0 incident response — hotfix validation, timeline reconstruction, and post-incident analysis
 argument-hint: [issue number | "active" | "postmortem {issue}"]
+install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -15,7 +16,7 @@ argument-hint: [issue number | "active" | "postmortem {issue}"]
 
 You are the pipeline's incident response coordinator. When production goes down or a critical bug surfaces, this command orchestrates the response: validates the hotfix before deploy, reconstructs the incident timeline, and produces a post-incident analysis.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`. User can override with `--model <name>`.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` 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)** — it breaks execution context.
 

package/commands/issue.md

@@ -11,7 +11,7 @@ argument-hint: [description of the problem or feature]
 
 You create GitHub issues with the exact structure the `/work-on` pipeline expects. Every issue you create must give the investigation agent enough context to find the right files on the first pass — no vague descriptions, no missing domains, no ambiguous scope.
 
-**Agent model policy**: Default `model: "sonnet"`. Fallback: `model: "opus"` if Sonnet is rate-limited.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
 
 ---
@@ -133,8 +133,28 @@ List every file that the fix/feature will need to touch. Be thorough:
 
 ### 2D: Check for duplicates
 
+Run the deterministic dedup script first (authoritative check), then fall back to an LLM pass if the script produces no result:
+
+```bash
+# Authoritative deterministic check — uses token overlap algorithm (see scripts/issue-dedup.sh)
+DEDUP_RESULT=$(scripts/issue-dedup.sh "{PROPOSED_TITLE}" {GH_FLAG} 2>&1)
+DEDUP_EXIT=$?
+
+if [ "$DEDUP_EXIT" -eq 1 ]; then
+  echo "Near-duplicate detected: $DEDUP_RESULT"
+  echo "Existing issue found — do NOT create a new one."
+  # STOP here and report to user (see handling rules below)
+elif [ "$DEDUP_EXIT" -eq 2 ]; then
+  echo "Dedup check usage error: $DEDUP_RESULT"
+  echo "Do NOT proceed to issue creation — fix the invocation and retry."
+  # STOP here — do not fall through to gh issue create
+fi
+```
+
+If the script exits 0 (no match found), also run an LLM-side search as a fallback:
+
 ```bash
-# Search for existing issues with similar scope
+# LLM fallback — broader semantic search for issues the token algorithm may miss
 gh issue list {GH_FLAG} --state open --limit 20 --search "{key_terms}" --json number,title,labels --jq '.[] | "#\(.number) [\(.labels | map(.name) | join(","))] \(.title)"'
 
 # Also check recently closed issues (might be a regression)
@@ -144,6 +164,7 @@ gh issue list {GH_FLAG} --state closed --limit 10 --search "{key_terms}" --json
 If a duplicate exists:
 - **Open duplicate found**: Tell the user. Do NOT create the issue. Show the existing issue number.
 - **Closed duplicate found (regression)**: Create the issue but reference the prior issue in the body: "Regression of #{N}."
+- **User wants to override**: Pass `--force` to the dedup script — this is an explicit human override path. Agents MUST NOT pass `--force` without user authorization. <!-- Added: forge#1335 -->
 
 ### 2E: Check for milestone context
 

package/commands/milestone.md

@@ -1,6 +1,7 @@
 ---
 description: Create, manage, and ship milestones — the top-level planning layer for feature development
 argument-hint: [create <name> | status | ship <slug> | sync <slug>]
+install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -13,7 +14,12 @@ Milestones are the top-level planning unit. They group related issues into a shi
 
 **Hierarchy**: Milestone → Issues → Sub-issues (optional decomposition)
 
-**You have access to ALL tools** — Task tool, Skill tool, sub-agents, everything.
+**NEVER use plan mode (EnterPlanMode).**
+**NEVER use the Agent tool for issue work** — milestone dispatches issue work via `Skill(skill="work-on", ...)` only. The Agent tool bypasses the Skill pipeline's label state machine, FORGE annotations, and structured review. The Agent tool may be used only for coordination tasks within milestone planning itself (e.g., parallel issue list queries) — never for /work-on sub-dispatch.
+
+<!-- FORGE:SPEC_LOADED — milestone.md loaded and active. Agent is bound by this spec. -->
+
+**You have access to Task, Skill, and Bash tools** for milestone coordination.
 
 ## Config Resolution
 
@@ -498,18 +504,29 @@ ISSUE_EOF
 fi
 ```
 
-### Step 3: Create shipping PR
+### Step 3: Create or update shipping PR (merge-train mechanics)
+
+<!-- Added: forge#1327 (update-in-place), extended: forge#1332 (merge-train) -->
+
+**Merge-train policy**: One staging→main PR stays open per deploy cycle. When a milestone ships to staging, it joins the deploy train as a candidate. The train PR is updated in place when fixes are pushed — it is NEVER closed and recreated. Dead-PR chains are eliminated: fix → push → re-request review on the same PR.
+
+**Update-in-place policy**: Before creating a new PR, check whether an open shipping PR already exists for this milestone. If one does, push the updated milestone branch and re-request review on the existing PR — do NOT close and recreate. Closing-and-recreating is pure churn: it burns a new PR number, loses review history, and contributes to a low staging→main pass rate. The correct flow is: fix → push → re-request review on the same PR.
 
 ```bash
-# Get the full diff summary (computed after Step 2.5 rebase, so it reflects the final state)
-DIFF_STATS=$(git diff origin/{STAGING_BRANCH}...origin/milestone/{slug} --stat)
-COMMIT_LOG=$(git log origin/{STAGING_BRANCH}..origin/milestone/{slug} --oneline)
-
-gh pr create {GH_FLAG} \
-  --base {STAGING_BRANCH} \
-  --head milestone/{slug} \
-  --title "Ship: {MILESTONE_TITLE}" \
-  --body "$(cat <<'PR_EOF'
+# Check for an existing open shipping PR for this milestone
+EXISTING_PR=$(gh pr list {GH_FLAG} --head "milestone/{slug}" --base "{STAGING_BRANCH}" --state open \
+    --json number,url --jq '.[0] | "\(.number)|\(.url)"' 2>/dev/null)
+
+if [ -n "$EXISTING_PR" ]; then
+  PR_NUMBER=$(echo "$EXISTING_PR" | cut -d'|' -f1)
+  PR_URL=$(echo "$EXISTING_PR" | cut -d'|' -f2)
+  echo "Existing open shipping PR #$PR_NUMBER found — updating in place (not recreating)."
+
+  # Update PR body to reflect latest diff state after fixes were pushed
+  DIFF_STATS=$(git diff origin/{STAGING_BRANCH}...origin/milestone/{slug} --stat)
+  COMMIT_LOG=$(git log origin/{STAGING_BRANCH}..origin/milestone/{slug} --oneline)
+  gh pr edit "$PR_NUMBER" {GH_FLAG} --body "$(cat <<'PR_EOF'
+<!-- FORGE:TRAIN_CANDIDATE milestone={slug} -->
 ## Milestone: {MILESTONE_TITLE}
 
 {MILESTONE_DESCRIPTION}
@@ -529,7 +546,43 @@ gh pr create {GH_FLAG} \
 ## Commits
 {COMMIT_LOG}
 PR_EOF
-)"
+  )"
+
+  # Re-request review so reviewers are notified of the updated push
+  gh pr review "$PR_NUMBER" {GH_FLAG} --request-review 2>/dev/null || true
+  echo "PR #$PR_NUMBER updated and review re-requested."
+else
+  # No open PR exists — create a new one
+  DIFF_STATS=$(git diff origin/{STAGING_BRANCH}...origin/milestone/{slug} --stat)
+  COMMIT_LOG=$(git log origin/{STAGING_BRANCH}..origin/milestone/{slug} --oneline)
+
+  gh pr create {GH_FLAG} \
+    --base {STAGING_BRANCH} \
+    --head milestone/{slug} \
+    --title "Ship: {MILESTONE_TITLE}" \
+    --body "$(cat <<'PR_EOF'
+<!-- FORGE:TRAIN_CANDIDATE milestone={slug} -->
+## Milestone: {MILESTONE_TITLE}
+
+{MILESTONE_DESCRIPTION}
+
+## Issues Included
+{list of all closed issues in this milestone with PR references}
+
+## Hunk-Loss Audit
+{If Step 2.5 rebase ran: "✓ Rebase completed — {AT_RISK_COUNT} at-risk staging-branch hunks absorbed into milestone branch before this PR was created. All staging content is preserved."}
+{If Step 2.5 found no at-risk hunks: "✓ Clean — no at-risk staging-branch hunks detected. Safe to merge."}
+
+> ⚠ **IMPORTANT: Merge this PR using a MERGE COMMIT, not squash.** Squash-merging a milestone PR can silently drop staging-only hunks in files the milestone touches. Use the "Create a merge commit" option in the GitHub UI, or `gh pr merge {PR_NUMBER} --merge`.
+
+## Diff Summary
+{DIFF_STATS}
+
+## Commits
+{COMMIT_LOG}
+PR_EOF
+    )"
+fi
 ```
 
 ### Step 4: Run staging review
@@ -540,6 +593,16 @@ Use the `/review-pr` skill to review the shipping PR. This is a comprehensive re
 Skill(skill="review-pr", args="{PR_NUMBER}")
 ```
 
+**If the review returns blocking findings (FINDINGS, not PASSED)**:
+- Do NOT close the PR.
+- Do NOT restart from Step 1.
+- Fix the blockers on `milestone/{slug}`, push the commits, then re-invoke review on the same PR:
+  ```
+  Skill(skill="review-pr", args="{PR_NUMBER}")
+  ```
+- Step 3 will detect the open PR on the next `/milestone ship {slug}` call and update it in place — the same PR number is preserved, review history is retained, and the reviewer is re-notified.
+- This eliminates the close-and-recreate churn that inflates the failed-PR count and lowers the staging→main pass rate. <!-- Added: forge#1328 -->
+
 ### Step 5: Report — PR is ready for user to merge
 
 ```
@@ -572,6 +635,8 @@ Milestone stays open. Issues remain assigned. Branch milestone/{slug} preserved.
 Run /milestone ship {slug} again when the milestone is ready for another shipping attempt.
 ```
 
+**When the staging review returns blockers (FINDINGS, not PASSED)**: do NOT close the PR. Fix the blockers on `milestone/{slug}`, push the fixes, then re-run `/milestone ship {slug}`. Step 3 will detect the open PR and update it in place — the same PR number is preserved, review history is retained, and the reviewer is re-notified. This eliminates the close-and-recreate churn that inflates the failed-PR count and lowers the staging→main pass rate. <!-- Added: forge#1327 -->
+
 **If the PR merged successfully**, run the following:
 
 ```bash

package/commands/optimize.md

@@ -1,6 +1,7 @@
 ---
 description: Analyze this repo and generate per-repo adaptive scripts from learned patterns, git history, and existing configuration
 argument-hint: [--dry-run | --force | --no-registry]
+install: extras
 ---
 
 # /optimize — Per-Repo Adaptive Script Generation
@@ -9,7 +10,7 @@ argument-hint: [--dry-run | --force | --no-registry]
 
 Proactively analyze the current repository and generate `.forgedock/scripts/` entries from `forge.yaml → learned:`, git commit history, and pipeline annotations — without waiting for a correction event. This is the proactive half of the learning loop; reactive capture happens in `/work-on` Phase 1D.
 
-**Agent model policy**: Default `model: "sonnet"`. Fallback: `model: "opus"` if Sonnet is rate-limited.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
 
 ---

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.
+
+---
+