forgedock 1.0.22 → 1.1.2

package/commands/compat-audit.md

@@ -1,6 +1,7 @@
 ---
 description: On-demand Claude Code compatibility and feature parity report — compares installed version against the breakpoints registry and lists affected ForgeDock features
 argument-hint: [--refresh]
+install: extras
 ---
 
 # /compat-audit — Claude Code Compatibility Report
@@ -9,7 +10,7 @@ argument-hint: [--refresh]
 
 You are the ForgeDock compatibility auditor. Produce a point-in-time advisory report that shows whether the user's installed Claude Code version is current and which ForgeDock features may behave differently on their runtime. This command is **non-blocking** — it never aborts the session. All output is advisory.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**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/deploy-info.md

@@ -1,6 +1,7 @@
 ---
 description: Show what will deploy next — diff staging vs main with issue/PR summary, risk assessment, and deploy checklist
 argument-hint: [staging | milestone/{slug} | compare {branch}]
+install: extras
 ---
 
 # /deploy-info — Pre-Deploy Summary
@@ -15,10 +16,12 @@ argument-hint: [staging | milestone/{slug} | compare {branch}]
 
 You are the pipeline's deploy awareness layer. Before the user merges staging → main (triggering CI/CD deployment), this command shows exactly what's going out: which PRs, which issues, what changed, and what risks exist.
 
-**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.
 
+<!-- FORGE:SPEC_LOADED — deploy-info.md loaded and active. Agent is bound by this spec. -->
+
 ---
 
 ## Phase 0: Review-Finding Readiness Check
@@ -156,7 +159,7 @@ done
 # Full file diff summary
 git diff --stat origin/$TARGET..origin/$SOURCE
 
-# Read layout paths from forge.yaml, fall back to AlterLab defaults
+# Read layout paths from forge.yaml, fall back to forge.yaml defaults
 LAYOUT_API=$(yq '.review.layout.api // "services/api"' forge.yaml 2>/dev/null || echo "services/api")
 LAYOUT_WORKER=$(yq '.review.layout.worker // "services/worker"' forge.yaml 2>/dev/null || echo "services/worker")
 LAYOUT_PAGES=$(yq '.review.layout.pages // "web/src/app"' forge.yaml 2>/dev/null || echo "web/src/app")
@@ -231,8 +234,10 @@ if [ -n "$NEW_ENV" ]; then
   # If your project uses a different backend, skip this block and verify manually.
   if [ "{DEPLOY_SECRETS_BACKEND}" = "sops" ]; then
     for var in $(echo "$NEW_ENV" | grep -oE '^\+[A-Z_]+' | sed 's/^\+//'); do
-      if ! grep -q "$var" scripts/decrypt-secrets.sh 2>/dev/null; then
-        echo "  ❌ $var NOT in decrypt-secrets.sh ENV_MAPPING"
+      if [ -f "{REPO_PATH}/scripts/decrypt-secrets.sh" ]; then
+        grep -q "$var" "{REPO_PATH}/scripts/decrypt-secrets.sh" 2>/dev/null || echo "  ❌ $var NOT in decrypt-secrets.sh ENV_MAPPING"
+      else
+        echo "  ℹ️  scripts/decrypt-secrets.sh not found — skipping ENV_MAPPING cross-check for $var. Verify manually in your SOPS chain."
       fi
     done
   else
@@ -276,6 +281,52 @@ gh workflow run {deploy.workflow} --ref main -f {deploy.workflow_inputs.services
 
 ---
 
+## Phase 4B: Deploy Train State <!-- Added: forge#1332 -->
+
+**Purpose**: Report the current state of the rolling staging→main deploy candidate (the "merge train"). One deploy PR should stay open per deploy cycle — this phase shows whether a candidate exists, what is holding it, and what is queued behind it.
+
+```bash
+git fetch origin {STAGING_BRANCH} {DEFAULT_BRANCH} 2>/dev/null
+
+# Step 1: Find the current open staging→main deploy PR (the "train")
+TRAIN_PR=$(gh pr list {GH_FLAG} \
+  --head "{STAGING_BRANCH}" \
+  --base "{DEFAULT_BRANCH}" \
+  --state open \
+  --json number,title,headRefOid,createdAt,reviewRequests \
+  --jq '.[0] // empty' 2>/dev/null)
+
+TRAIN_PR_NUMBER=$(echo "$TRAIN_PR" | jq -r '.number // empty')
+TRAIN_PR_SHA=$(echo "$TRAIN_PR" | jq -r '.headRefOid // empty' | cut -c1-7)
+TRAIN_PR_CREATED=$(echo "$TRAIN_PR" | jq -r '.createdAt // empty')
+
+if [ -z "$TRAIN_PR_NUMBER" ]; then
+  TRAIN_STATUS="NO_TRAIN — no open staging→main PR. Run /review-pr-staging to open one."
+else
+  # Step 2: Check whether the train is held (has blocking findings)
+  HELD_BY=$(gh issue list {GH_FLAG} \
+    --label "review-finding" \
+    --state open \
+    --search "PR #${TRAIN_PR_NUMBER}" \
+    --limit 20 \
+    --json number,title \
+    --jq '[.[] | "#\(.number): \(.title)"] | join("\n")' 2>/dev/null || true)
+
+  if [ -n "$HELD_BY" ]; then
+    TRAIN_STATUS="HELD"
+  else
+    TRAIN_STATUS="CLEAR — ready to merge"
+  fi
+
+  # Step 3: Count commits queued (commits in staging not yet in main)
+  QUEUED_COMMITS=$(git rev-list --count origin/{DEFAULT_BRANCH}..origin/{STAGING_BRANCH} 2>/dev/null || echo "?")
+fi
+```
+
+Train state is included in the Phase 5 output summary.
+
+---
+
 ## Phase 5: Output Summary
 
 ```
@@ -283,6 +334,14 @@ gh workflow run {deploy.workflow} --ref main -f {deploy.workflow_inputs.services
 
 **Commits**: {N} | **PRs**: {N} | **Issues closed**: {N} | **Files changed**: {N}
 
+### Deploy Train State
+**Train PR**: #{TRAIN_PR_NUMBER} (SHA: {TRAIN_PR_SHA}, opened: {TRAIN_PR_CREATED})
+**Status**: {TRAIN_STATUS}
+{If HELD: "**Held by**: {count} open finding(s) — fix and push to unblock:\n{HELD_BY}"}
+{If CLEAR: "**Ready to merge**: no open findings on the train PR"}
+{If NO_TRAIN: "No open staging→main PR — run /review-pr-staging to open one"}
+**Queued commits**: {QUEUED_COMMITS} (commits in staging not yet in main)
+
 ### Services Affected
 | Service | Files Changed | Rebuild Required |
 |---------|---------------|-----------------|

package/commands/design-bench.md

@@ -1,6 +1,7 @@
 ---
 description: Run the ABC benchmark — reference URL → design-blind brief → render arms A/B/C → blind judge → scorecard with win-rates over n runs
 argument-hint: [<brief-name>|all] [--n <runs>] [--corpus-version <ver>]
+install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -21,6 +22,10 @@ live there — this command is the executable workflow over that methodology.
 **No application runtime.** ForgeDock is a set of command specs. This command is a step-by-step procedure an
 agent executes; the only executable helper is the deterministic aggregator `scripts/bench-scorecard.mjs`.
 
+**NEVER use plan mode (EnterPlanMode).**
+
+<!-- FORGE:SPEC_LOADED — design-bench.md loaded and active. Agent is bound by this spec. -->
+
 ---
 
 ## The three arms (one variable)
@@ -127,7 +132,7 @@ The aggregator (see `scripts/bench-scorecard.mjs`):
   generated arm is a judge defect, not a harness win — treat those runs as suspect.
 
 Post the result as a `FORGE:BENCH_SCORECARD` annotation (registered in
-[`docs/FORGE-PROTOCOL.md`](../docs/FORGE-PROTOCOL.md)) on the tracking issue:
+[`docs/spec/forge-protocol-v1.md`](../docs/spec/forge-protocol-v1.md)) on the tracking issue:
 
 ```bash
 gh issue comment <ISSUE> --body "<!-- FORGE:BENCH_SCORECARD -->

package/commands/design-render-critique-loop.md

@@ -1,6 +1,7 @@
 ---
 description: Render a design from its FORGE:DESIGN_SPEC, critique the rendered pixels against the perceptual negatives, and iterate until it passes or the budget is spent — the missing reward signal.
 argument-hint: [<issue-number>|<spec-path>] [--max-iters <n>] [--viewports desktop,mobile]
+install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -81,7 +82,7 @@ real reference*. They must never be the same judge. This is also distinct from t
 
 ## `FORGE:CRITIQUE` annotation
 
-Registered in [FORGE-PROTOCOL](../docs/FORGE-PROTOCOL.md). One per iteration, so the improvement trajectory is an
+Registered in [FORGE Annotation Protocol](../docs/spec/forge-protocol-v1.md). One per iteration, so the improvement trajectory is an
 auditable artifact:
 
 ```markdown

package/commands/design.md

@@ -1,6 +1,7 @@
 ---
 description: Route a design GitHub issue through the UI Taste Harness — investigate → architect → implement → critique loop → user-feedback loop → close — accumulating FORGE:DESIGN_* annotations and driving the design:* label state machine to design:shipped.
 argument-hint: <issue-number> | <brief-name>
+install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

package/commands/diagnose.md

@@ -1,6 +1,7 @@
 ---
 description: Trace a failed or stalled pipeline run — identify which FORGE annotation is missing or malformed, diagnose the failure point, and suggest specific remediation steps
 argument-hint: [issue number] [--repo prefix]
+install: extras
 ---
 
 # /diagnose — Pipeline Failure Tracer
@@ -9,7 +10,7 @@ argument-hint: [issue number] [--repo prefix]
 
 **NEVER use plan mode (EnterPlanMode)** — it breaks execution context.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**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.
 
 You are the pipeline's diagnostic layer. Given a single GitHub issue number, you reconstruct the full FORGE annotation chain for that pipeline run, identify the exact failure point, and suggest specific remediation steps. This command is **read-only** — it never mutates GitHub state.
 

package/commands/explain.md

@@ -1,6 +1,7 @@
 ---
 description: Plain-English breakdown of what happened on a GitHub issue — translates FORGE pipeline annotations into a human-readable narrative for teammates and PMs
 argument-hint: <issue number or PR#N> [--repo prefix]
+install: extras
 ---
 
 # /explain — FORGE Annotation Translator
@@ -9,7 +10,7 @@ argument-hint: <issue number or PR#N> [--repo prefix]
 
 You translate the FORGE pipeline's machine-readable annotations on a GitHub issue or PR into a clear, plain-English narrative that anyone can understand — no pipeline knowledge required. This is a read-only command: it never writes to GitHub, never changes labels, and never modifies any state.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**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/forge-stats.md

@@ -1,13 +1,14 @@
 ---
 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 -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # /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.
 
@@ -193,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
 
@@ -495,7 +516,7 @@ Create all {N} issues? (yes / adjust #N / cancel)
 
 | Bad Issue | Why It Fails | Good Version |
 |-----------|-------------|-------------|
-| "Fix docker mount" | Which compose file? Which mount? | "fix: `.gemini` volume mount in docker-compose.prod.yml missing rw flag" |
+| "Fix docker mount" | Which compose file? Which mount? | "fix: `logs` volume in docker-compose.yml missing `rw` flag — container writes fail at runtime" |
 | "Update billing" | What about billing? What's broken? | "fix: payment_processor.charge() raises ZeroDivisionError when amount == 0" |
 | "Investigate performance" | Investigate what? Where? | "investigate: API p95 latency doubled since last deploy — trace hot paths in job processing routers" |
 | No affected files listed | Investigator guesses wrong files | List every file with what needs to change |

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).**
 
 ---