forgedock 1.16.2 → 1.18.0

package/commands/milestone.md

@@ -412,11 +412,18 @@ Before shipping, ensure the milestone branch is up to date with `staging` (picks
 ```bash
 cd {REPO_PATH}
 git fetch origin {STAGING_BRANCH} milestone/{slug}
-git checkout milestone/{slug}
-git merge origin/{STAGING_BRANCH} --no-edit
-# If conflicts, report to user and STOP — do not auto-resolve
-git push origin milestone/{slug}
-git checkout {STAGING_BRANCH}
+# Never mutate the main checkout: sync in a detached worktree at the milestone tip
+SYNC_WT=$(mktemp -d)
+git worktree add --detach "$SYNC_WT" origin/milestone/{slug}
+if git -C "$SYNC_WT" merge origin/{STAGING_BRANCH} --no-edit; then
+  git -C "$SYNC_WT" push origin HEAD:refs/heads/milestone/{slug}
+  git worktree remove --force "$SYNC_WT"
+else
+  # Conflicts: report to user and STOP — do not auto-resolve
+  git -C "$SYNC_WT" merge --abort 2>/dev/null || true
+  git worktree remove --force "$SYNC_WT"
+  echo "STOP: merge conflict syncing milestone/{slug} with {STAGING_BRANCH}"; exit 1
+fi
 ```
 
 ### Step 2.5: Pre-Merge Hunk-Loss Audit (MANDATORY before creating PR)
@@ -425,6 +432,7 @@ git checkout {STAGING_BRANCH}
 
 This step identifies "at-risk hunks" — staging-only content in files the milestone also modifies — and absorbs them into the milestone branch via rebase before the PR is created. After the rebase, even a squash merge will preserve all staging content because it's now part of the milestone branch's commits.
 
+<!-- allowlist:check-spec-bash -->
 ```bash
 cd {REPO_PATH}
 git fetch origin {STAGING_BRANCH} milestone/{slug}
@@ -453,18 +461,19 @@ else
         echo "$AT_RISK" | grep '^--- a/' | sed 's|^--- a/||'
 
         echo "Rebasing milestone/{slug} onto origin/{STAGING_BRANCH} to absorb at-risk hunks..."
-        git checkout milestone/{slug}
-        git rebase origin/{STAGING_BRANCH}
+        REBASE_WT=$(mktemp -d)
+        git worktree add --detach "$REBASE_WT" origin/milestone/{slug}
+        git -C "$REBASE_WT" rebase origin/{STAGING_BRANCH}
 
         REBASE_EXIT=$?
         if [ "$REBASE_EXIT" -ne 0 ]; then
             # Capture conflicting files BEFORE aborting (after abort, unmerged state is gone)
-            CONFLICTING_FILES=$(git diff --name-only --diff-filter=U 2>/dev/null)
+            CONFLICTING_FILES=$(git -C "$REBASE_WT" diff --name-only --diff-filter=U 2>/dev/null)
             [ -z "$CONFLICTING_FILES" ] && CONFLICTING_FILES="unknown — check git status after resolving manually"
 
             # Abort the failed rebase and return to a clean state
-            git rebase --abort 2>/dev/null || true
-            git checkout {STAGING_BRANCH}
+            git -C "$REBASE_WT" rebase --abort 2>/dev/null || true
+            git worktree remove --force "$REBASE_WT"
 
             # Truncate AT_RISK to safe size for issue body (avoid shell quoting issues with large diffs)
             AT_RISK_SNIPPET=$(echo "$AT_RISK" | head -60 | sed "s/'/'\\\\''/g")
@@ -519,6 +528,7 @@ ISSUE_EOF
 ISSUE_SKILL_OUTPUT=$(Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"fix(milestone): rebase conflict during hunk-loss audit for milestone/{slug}\" --body-file \"${REBASE_ISSUE_BODY_FILE}\" --label \"bug\" --label \"priority:P0\" --label \"needs-human\""))
 ```
 
+<!-- allowlist:check-spec-bash -->
 ```bash
             echo "STOP: Rebase conflict. Created issue for manual resolution (see /issue output above). Do NOT proceed to PR creation."
             echo "Run '/milestone ship {slug}' again after resolving the conflict."
@@ -526,9 +536,9 @@ ISSUE_SKILL_OUTPUT=$(Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"fi
         fi
 
         # Rebase succeeded — push the rebased branch
-        git push origin milestone/{slug} --force-with-lease
+        git -C "$REBASE_WT" push origin HEAD:refs/heads/milestone/{slug} --force-with-lease
+        git worktree remove --force "$REBASE_WT"
         echo "Rebase complete. Milestone branch now includes all $AT_RISK_COUNT at-risk staging hunks."
-        git checkout {STAGING_BRANCH}
     fi
 fi
 ```
@@ -716,11 +726,18 @@ Syncs the milestone branch with the latest default branch to pick up fast-lane f
 cd {REPO_PATH}
 DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE")
 git fetch origin $DEFAULT_BRANCH milestone/{slug}
-git checkout milestone/{slug}
-git merge origin/$DEFAULT_BRANCH --no-edit
-# If conflicts, report to user and STOP
-git push origin milestone/{slug}
-git checkout $DEFAULT_BRANCH
+# Never mutate the main checkout: sync in a detached worktree at the milestone tip
+SYNC_WT=$(mktemp -d)
+git worktree add --detach "$SYNC_WT" origin/milestone/{slug}
+if git -C "$SYNC_WT" merge origin/$DEFAULT_BRANCH --no-edit; then
+  git -C "$SYNC_WT" push origin HEAD:refs/heads/milestone/{slug}
+  git worktree remove --force "$SYNC_WT"
+else
+  # If conflicts, report to user and STOP
+  git -C "$SYNC_WT" merge --abort 2>/dev/null || true
+  git worktree remove --force "$SYNC_WT"
+  echo "STOP: merge conflict syncing milestone/{slug} with $DEFAULT_BRANCH"; exit 1
+fi
 ```
 
 Report: "Synced milestone/{slug} with latest `{DEFAULT_BRANCH}`. {N} new commits incorporated."

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

@@ -260,7 +260,7 @@ gh issue list -R {SATELLITE_REPO} --state open --limit 500 --json number,title,l
 ### Filter out ineligible issues
 
 Remove issues that should NOT be worked on:
-- Already closed or has `workflow:merged` label
+- Already closed or has `workflow:merged` label (exception: an explicitly requested closed `workflow:decomposed` parent is expanded first, see below)
 - 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)
@@ -269,6 +269,9 @@ Remove issues that should NOT be worked on:
 
 If a `workflow:decomposed` issue is found, automatically expand it to its open sub-issues instead.
 
+<!-- Added: forge#3736 -->
+**Closed decomposed parents**: with `decomposition.close_parent` enabled, a decomposed parent is CLOSED at decomposition and keeps `workflow:decomposed`. Run this expansion BEFORE the "already closed" filter: when an explicitly requested issue is a closed `workflow:decomposed` parent, expand it to its open children (parse the `- [ ] #N` and `- [x] #N` lines of the Sub-Issue Tracker in its body, keep those whose state is OPEN) instead of dropping it as closed. A closed decomposed parent with no open children is reported as complete and skipped. A closed parent without `workflow:decomposed` is still dropped.
+
 ### Source-PR Triage Hint (pre-flight, non-binding)
 
 <!-- Added: forge#2351 -->

package/commands/orchestrate/phase-4-execution.md

@@ -53,6 +53,8 @@ fi
 # --- End lease gate ---
 ```
 
+**Board closure ownership** <!-- Added: forge#3699 -->: lease takeover never reclaims or closes a claims board (each batch creates its own, Step 3D.1). Closing it is owned by Phase 5 Step 5C and, for batches that never reach it, `/cleanup` Phase 2C.
+
 **Lease release**: `LEASE_RELEASED_THIS_SESSION` (declared just below, alongside `release_orchestrator_lease()`) guards against double-posting `FORGE:LEASE_RELEASED`. The release call is invoked from both the **Step 4A-pre.-0.5 "Stopping the orchestrator"** procedure (interrupted path) and the **Termination condition** at the end of Step 4B (normal clean/paused drain) — both exit paths route through the same idempotent function so the lease is never left dangling either way.
 
 ```bash
@@ -1609,6 +1611,12 @@ classify_predecessor_state() {
     PRED_LABELS=$(echo "$PRED_INFO" | jq -r '.workflow[]?' 2>/dev/null)
   fi
 
+  # forge#3566: age bound for the remediating / engine-error IN_PROGRESS arms below. Resolved here, not once at
+  # Step 4 setup, because wake reconstruction calls this helper from a fresh shell. Non-numeric falls back to 48.
+  local IN_PROGRESS_MAX_HOURS
+  IN_PROGRESS_MAX_HOURS=$(yq '.orchestration.in_progress_max_hours // 48' forge.yaml 2>/dev/null || echo 48)
+  case "$IN_PROGRESS_MAX_HOURS" in ''|*[!0-9]*) IN_PROGRESS_MAX_HOURS=48 ;; esac
+
   # reverify_merged_trail: re-run the phase-trail verifier for a merged predecessor that has NO escalation
   # record (forge#3156), so wake reconstruction does not trust the `workflow:merged` label alone. Prints OK
   # when the trail verifies, UNVERIFIED otherwise. Fails closed: a wake runs in a fresh shell where FORGE_ROOT is
@@ -1671,7 +1679,10 @@ classify_predecessor_state() {
     # forge#3541: autonomous remediation (ci-gate / in-pr-fix / base-sync) is pending or running. No human decision is
     # needed, so this is NOT GATED: dependents keep waiting exactly as for any mid-pipeline predecessor, and item 6.4
     # (or the engine handoff) drives the fix. A concurrent `needs-human` is matched by the GATED arm above first.
-    echo "IN_PROGRESS"
+    # Time-boxed (forge#3566): past orchestration.in_progress_max_hours (default 48) [IN_PROGRESS_MAX_HOURS, resolved from forge.yaml] the state is stranded, not in flight.
+    PRED_AGE_H=$(gh issue view "$PRED" -R {GH_REPO} --json updatedAt --jq '((now - (.updatedAt | fromdateiso8601)) / 3600 | floor)' 2>/dev/null || echo "")
+    case "$PRED_AGE_H" in ''|*[!0-9]*) PRED_AGE_H=0 ;; esac  # unreadable age keeps IN_PROGRESS (fail safe)
+    if [ "$PRED_AGE_H" -ge "${IN_PROGRESS_MAX_HOURS:-48}" ]; then echo "GATED"; else echo "IN_PROGRESS"; fi
   elif echo "$PRED_LABELS" | grep -qx "workflow:engine-error"; then
     # forge#2261: the engine/tool itself broke on this run (e.g. a fail-fast
     # CLI_BACKEND_FAILED, or an exhausted retry loop where the runner never
@@ -1688,7 +1699,11 @@ classify_predecessor_state() {
     # ENGINE_DISPATCH_MAP-tracked issues (fresh Agent-spawn fallback on empty
     # committed state) — 2a's Agent(resume=...) alone cannot reach them, since
     # they were never in AGENT_ISSUE_MAP.
-    echo "IN_PROGRESS"
+    # Time-boxed (forge#3566): past orchestration.in_progress_max_hours (default 48) [IN_PROGRESS_MAX_HOURS, resolved from forge.yaml] auto-resume has evidently
+    # not recovered it; classify GATED so a human is told instead of dependents waiting forever.
+    PRED_AGE_H=$(gh issue view "$PRED" -R {GH_REPO} --json updatedAt --jq '((now - (.updatedAt | fromdateiso8601)) / 3600 | floor)' 2>/dev/null || echo "")
+    case "$PRED_AGE_H" in ''|*[!0-9]*) PRED_AGE_H=0 ;; esac  # unreadable age keeps IN_PROGRESS (fail safe)
+    if [ "$PRED_AGE_H" -ge "${IN_PROGRESS_MAX_HOURS:-48}" ]; then echo "GATED"; else echo "IN_PROGRESS"; fi
   elif [ "$PRED_STATE" = "CLOSED" ]; then
     # Closed with no workflow:invalid/merged label (e.g. closed-not-planned) — treat as DONE,
     # not a new deadlock state; there is no pending code for dependents to wait on.
@@ -3928,7 +3943,10 @@ if [ -n "$TS_CHANGED" ]; then
     echo "=== Integration Build Gate (TypeScript): batch checkpoint ==="
     cd {REPO_PATH}
     git fetch origin ${MILESTONE_BRANCH}
-    git checkout origin/${MILESTONE_BRANCH} --detach 2>/dev/null
+    # Detached worktree: never check out in the main checkout
+    GATE_WT=$(mktemp -d)
+    git worktree add --detach "$GATE_WT" "origin/${MILESTONE_BRANCH}" 2>/dev/null
+    cd "$GATE_WT"
 
     if [ -n "$TS_TYPECHECK" ]; then
         eval "$TS_TYPECHECK" 2>&1 | head -30
@@ -3946,7 +3964,8 @@ if [ -n "$TS_CHANGED" ]; then
         BUILD_EXIT=0
     fi
 
-    git checkout - 2>/dev/null
+    cd {REPO_PATH}
+    git worktree remove --force "$GATE_WT" 2>/dev/null || true
 
     if [ "$TSC_EXIT" -ne 0 ]; then
         echo "BLOCKING: TypeScript errors on ${MILESTONE_BRANCH} after batch checkpoint."
@@ -3962,7 +3981,9 @@ PY_CHANGED=$(git diff origin/{DEFAULT_BRANCH}...origin/${MILESTONE_BRANCH} --nam
 if [ -n "$PY_CHANGED" ]; then
     echo "=== Integration Build Gate (Python): batch checkpoint ==="
     cd {REPO_PATH}
-    git checkout origin/${MILESTONE_BRANCH} --detach 2>/dev/null
+    GATE_WT=$(mktemp -d)
+    git worktree add --detach "$GATE_WT" "origin/${MILESTONE_BRANCH}" 2>/dev/null
+    cd "$GATE_WT"
 
     if [ -n "$PYTHON_FORMAT" ]; then
         eval "$PYTHON_FORMAT" 2>&1 | tail -10
@@ -3972,7 +3993,8 @@ if [ -n "$PY_CHANGED" ]; then
         FORMAT_EXIT=0
     fi
 
-    git checkout - 2>/dev/null
+    cd {REPO_PATH}
+    git worktree remove --force "$GATE_WT" 2>/dev/null || true
 
     if [ "$FORMAT_EXIT" -ne 0 ]; then
         echo "WARNING: Python formatting issues on ${MILESTONE_BRANCH} after batch checkpoint."

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

@@ -44,13 +44,24 @@ Include the audit summary in the final report (Phase 6). Key metrics to surface:
 
 ### Step 5C: Close the coordination issue (claims board) <!-- Added: forge#2072 -->
 
-**Why this step exists**: Step 3D.1 (`phase-3-dependency.md`) creates a per-batch coordination issue (the claims board) and exports `FORGE_COORD_ISSUE`/`COORD_ISSUE_NUMBER`. Step 5A's `/cleanup` sweep only closes orphaned issues whose PR merged — the claims board has no PR of its own, so that heuristic never matches it. Without this step, one `automation`-labelled issue leaks per orchestration batch.
+**Why this step exists**: Step 3D.1 (`phase-3-dependency.md`) creates a per-batch coordination issue (the claims board) and exports `FORGE_COORD_ISSUE`/`COORD_ISSUE_NUMBER`. Step 5A's `/cleanup` orphan sweep (Phase 2A/2B) only closes issues whose PR merged — the claims board has no PR of its own, so that heuristic never matches it; `/cleanup` Phase 2C is the separate safety net that closes boards this step missed. Without this step, one `automation`-labelled issue leaks per orchestration batch.
 
 **Run after Step 5B, before Step 5D.** No-ops cleanly if the claims board was never created this run (`COORD_ISSUE_NUMBER` unset/empty — e.g. Step 3D.1's `gh issue create` failed, or this batch never reached DAG construction). Tolerates GitHub API failures without aborting the rest of Phase 5 — the same tolerant-failure convention (`2>/dev/null || echo ...`, `|| true`) used throughout `phase-3-dependency.md`/`phase-4-execution.md`.
 
 **Orchestrator lease should already be released by this point** (forge#2627): `phase-4-execution.md`'s Termination condition (end of Step 4B) calls `release_orchestrator_lease()` before handing off to Phase 5 on a normal drain, and the "Stopping the orchestrator" procedure (Step 4A-pre.-0.5) does the same on an interrupted exit. Closing the coordination issue here does not depend on lease state either way — an unreleased lease on an issue about to be closed is harmless (a future batch creates its own new coordination issue per Step 3D.1), but if `ACTIVE_CLAIMS_NOTE` logic is ever extended to also surface lease state, prefer checking for a still-unreleased `FORGE:LEASE` the same way `ACTIVE_CLAIMS` is computed above.
 
+**Recover the board when the variable is lost** <!-- Added: forge#3699 -->: `COORD_ISSUE_NUMBER` is a shell variable and does not survive compaction, `--retry` or a fresh-context resume. When it is unset but `BATCH_ID` is known, look the board up on GitHub by the exact `<!-- FORGE:BATCH_ID: ${BATCH_ID} -->` body marker (never a prefix, so another live batch's board is never matched). If `BATCH_ID` is also lost, fall through to the no-op and leave the board to `/cleanup` Phase 2C.
+
 ```bash
+if [ -z "${COORD_ISSUE_NUMBER:-}" ] && [ -n "${BATCH_ID:-}" ]; then
+  COORD_ISSUE_NUMBER=$(gh issue list -R {GH_REPO} --state open --label automation --limit 100 \
+    --json number,body 2>/dev/null \
+    | jq -r --arg marker "<!-- FORGE:BATCH_ID: ${BATCH_ID} -->" \
+      '[.[] | select(.body | contains("<!-- FORGE:COORD_ISSUE -->") and contains($marker))] | first | .number // empty' \
+      2>/dev/null || echo "")
+  [ -n "$COORD_ISSUE_NUMBER" ] && echo "Recovered coordination issue #${COORD_ISSUE_NUMBER} from FORGE:BATCH_ID marker"
+fi
+
 if [ -n "${COORD_ISSUE_NUMBER:-}" ]; then
   # 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
@@ -66,15 +77,20 @@ $(echo "$ACTIVE_CLAIMS" | jq -r '.[] | "- " + .' 2>/dev/null)"
     ACTIVE_CLAIMS_NOTE="No active (unreleased) claims at close time."
   fi
 
+  # Outcome counters come from Phase 4/6 state; tolerate unset values (default n/a when the orchestrator did not track them).
+  MERGED_COUNT="${MERGED_COUNT:-n/a}"; GATED_COUNT="${GATED_COUNT:-n/a}"; FAILED_COUNT="${FAILED_COUNT:-n/a}"
+
   gh issue close "$COORD_ISSUE_NUMBER" -R {GH_REPO} --comment "Batch complete — closing claims board.
 
+**Summary**: merged ${MERGED_COUNT} / gated ${GATED_COUNT} / failed ${FAILED_COUNT}
+
 ${ACTIVE_CLAIMS_NOTE}
 
 Closed automatically by \`/orchestrate\` Phase 5 Step 5C." 2>/dev/null \
     && echo "Closed coordination issue #${COORD_ISSUE_NUMBER}" \
     || echo "WARNING: failed to close coordination issue #${COORD_ISSUE_NUMBER} — non-fatal, continuing Phase 5"
 else
-  echo "No coordination issue for this batch (FORGE_COORD_ISSUE unset) — Step 5C is a no-op"
+  echo "No coordination issue for this batch (unset and not recoverable via BATCH_ID) — Step 5C is a no-op; /cleanup Phase 2C will sweep it if it exists"
 fi
 ```
 

package/commands/pipeline-health/phase-1-context.md

@@ -36,6 +36,8 @@ else
 fi
 ```
 
+**Decomposition trackers** <!-- Added: forge#3736 -->: issues labelled `workflow:decomposed` are trackers (open, or closed at decomposition when `decomposition.close_parent` is true), not work. Phase 2 excludes `workflow:decomposed` from every open-work and issue-flow count and reports them separately as `trackers (N)`.
+
 ### 1C: Load Prior Health Report
 
 Fetch the most recent `health-report` issue for the same repo and parse its metrics for trend computation. This must run before Phase 2 so that PRIOR_* variables are available when Phase 3A builds the trend column.

package/commands/pipeline-health/phase-2-metrics.md

@@ -323,7 +323,7 @@ INVALID_ISSUES=$(gh issue list -R $REPO --state closed --label "workflow:invalid
   --jq "[.[] | select(.createdAt > \"$SINCE\" and (.labels | map(.name) | index(\"review-finding\") | not))] | length")
 
 TOTAL_INVESTIGATED=$(gh issue list -R $REPO --state all --limit 500 --json number,createdAt,labels \
-  --jq "[.[] | select(.createdAt > \"$SINCE\" and (.labels | map(.name) | any(. == \"workflow:investigating\" or . == \"workflow:building\" or . == \"workflow:in-review\" or . == \"workflow:merged\" or . == \"workflow:invalid\")))  ] | length")
+  --jq "[.[] | select(.createdAt > \"$SINCE\" and (.labels | map(.name) | index(\"workflow:decomposed\") | not) and (.labels | map(.name) | any(. == \"workflow:investigating\" or . == \"workflow:building\" or . == \"workflow:in-review\" or . == \"workflow:merged\" or . == \"workflow:invalid\")))  ] | length")
 
 echo "Investigation invalidation rate: $INVALID_ISSUES / $TOTAL_INVESTIGATED"
 # Target: < 15%
@@ -354,15 +354,22 @@ echo "Re-investigation count: $REINVESTIGATED"
 # 4. Issue structure compliance (/issue adoption proxy)
 # Issues created in window that have an "Affected Files" section in their body
 TOTAL_ISSUES=$(gh issue list -R $REPO --state all --limit 500 --json number,createdAt,labels \
-  --jq "[.[] | select(.createdAt > \"$SINCE\" and (.labels | map(.name) | index(\"review-finding\") | not))] | length")
+  --jq "[.[] | select(.createdAt > \"$SINCE\" and (.labels | map(.name) | index(\"review-finding\") | not) and (.labels | map(.name) | index(\"workflow:decomposed\") | not))] | length")
 
 STRUCTURED_ISSUES=$(gh issue list -R $REPO --state all --limit 500 --json number,createdAt,body,labels \
-  --jq "[.[] | select(.createdAt > \"$SINCE\" and (.labels | map(.name) | index(\"review-finding\") | not) and (.body | contains(\"Affected Files\")))] | length")
+  --jq "[.[] | select(.createdAt > \"$SINCE\" and (.labels | map(.name) | index(\"review-finding\") | not) and (.labels | map(.name) | index(\"workflow:decomposed\") | not) and (.body | contains(\"Affected Files\")))] | length")
 
 echo "Issue structure compliance: $STRUCTURED_ISSUES / $TOTAL_ISSUES"
 # Target: > 80%. Issues without Affected Files are harder to investigate and more likely to produce ISSUE_SPEC failures.
 ```
 
+**Decomposition trackers** <!-- Added: forge#3736 -->: issues labelled `workflow:decomposed` are trackers, not work. `TOTAL_INVESTIGATED`, `TOTAL_ISSUES`, `STRUCTURED_ISSUES` and both stall-rate queries exclude them with an `index("workflow:decomposed") | not` filter, so a parent closed at decomposition (`decomposition.close_parent`) and an open one are treated alike. Report them separately as `trackers (N)`:
+
+```bash
+TRACKER_COUNT=$(gh issue list -R $REPO --state all --label "workflow:decomposed" --limit 500 --json number --jq 'length' 2>/dev/null || echo 0)
+echo "trackers ($TRACKER_COUNT) — decomposed parents, excluded from work counts"
+```
+
 **Issue quality score** = weighted average of sub-metrics:
 - Invalidation rate: 40% weight (direct signal — these issues failed)
 - ISSUE_SPEC audit findings: 30% weight (downstream cost signal)
@@ -496,14 +503,14 @@ Query issues that received a `<!-- FORGE:STALL_DETECTED -->` comment within the
 BATCH_TOTAL=$(gh issue list -R $GH_REPO \
   --state all --limit 500 \
   --json number,createdAt,labels \
-  --jq "[.[] | select(.createdAt > \"$SINCE\") | select(.labels | map(.name) | any(startswith(\"workflow:\")))] | length" \
+  --jq "[.[] | select(.createdAt > \"$SINCE\") | select(.labels | map(.name) | any(startswith(\"workflow:\"))) | select(.labels | map(.name) | index(\"workflow:decomposed\") | not)] | length" \
   2>/dev/null || echo 0)
 
 # Enumerate pipeline-active issue numbers for per-issue comment queries
 PIPELINE_ISSUE_NUMS=$(gh issue list -R $GH_REPO \
   --state all --limit 500 \
   --json number,createdAt,labels \
-  --jq "[.[] | select(.createdAt > \"$SINCE\") | select(.labels | map(.name) | any(startswith(\"workflow:\"))) | .number]" \
+  --jq "[.[] | select(.createdAt > \"$SINCE\") | select(.labels | map(.name) | any(startswith(\"workflow:\"))) | select(.labels | map(.name) | index(\"workflow:decomposed\") | not) | .number]" \
   2>/dev/null || echo "[]")
 
 # Count issues with at least one FORGE:STALL_DETECTED comment

package/commands/pipeline-status.md

@@ -100,6 +100,26 @@ if [ -n "$UNTRACKED" ] && [ "$UNTRACKED_COUNT" -gt 0 ]; then
     done
     echo ""
 fi
+
+# Decomposition trackers (workflow:decomposed) are NOT work: they are excluded from every
+# work count in this report and listed separately. With decomposition.close_parent a tracker
+# is CLOSED at decomposition, so query --state all and keep only trackers with unfinished
+# `- [ ]` checklist items. <!-- Added: forge#3736 -->
+TRACKERS=$(gh issue list $GH_FLAG \
+    --state all \
+    --label "workflow:decomposed" \
+    --limit 100 \
+    --json number,title,state,body \
+    --jq '.[] | select(.body | test("(?m)^[[:space:]]*[-*+] \\[ \\]")) | "#\(.number) \(.title[:60]) [\(.state | ascii_downcase)]"' \
+    2>/dev/null || echo "")
+TRACKER_COUNT=$(printf '%s' "$TRACKERS" | grep -c '#' 2>/dev/null || true)
+echo "[trackers] (${TRACKER_COUNT:-0} — decomposed parents awaiting children; not counted as work)"
+if [ -n "$TRACKERS" ]; then
+    echo "$TRACKERS" | while IFS= read -r line; do
+        echo "  $line"
+    done
+fi
+echo ""
 ```
 
 ---
@@ -295,7 +315,7 @@ echo ""
 INVESTIGATING=$(gh issue list $GH_FLAG --state open --label "workflow:investigating" --limit 100 --json number --jq '. | length' 2>/dev/null || echo 0)
 BUILDING=$(gh issue list $GH_FLAG --state open --label "workflow:building" --limit 100 --json number --jq '. | length' 2>/dev/null || echo 0)
 IN_REVIEW=$(gh issue list $GH_FLAG --state open --label "workflow:in-review" --limit 100 --json number --jq '. | length' 2>/dev/null || echo 0)
-BLOCKED=$(gh issue list $GH_FLAG --state open --label "needs-human" --limit 100 --json number --jq '. | length' 2>/dev/null || echo 0)
+BLOCKED=$(gh issue list $GH_FLAG --state open --label "needs-human" --limit 100 --json number,labels --jq '[.[] | select(.labels | map(.name) | index("workflow:decomposed") | not)] | length' 2>/dev/null || echo 0)  # workflow:decomposed trackers are excluded from work counts
 READY=$(gh issue list $GH_FLAG --state open --label "workflow:ready-to-build" --limit 100 --json number --jq '. | length' 2>/dev/null || echo 0)
 
 TOTAL_INFLIGHT=$((INVESTIGATING + BUILDING + IN_REVIEW + READY))

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

@@ -192,6 +192,7 @@ Append this block at the very end of your comment (after the `---` footer line,
 9. **Agent marker**: Include exactly one `<!-- FORGE:REVIEW-AGENT:{domain} -->` marker in the persisted body, where `{domain}` is the marker domain the orchestrator passes you (the canonical value from the roster-to-marker table in `review-pr.md`, e.g. `infra` and `scraper`; never a lowercased display name such as `infrastructure` or `scraping`).
 10. **Reviewed SHA**: Include exactly one line `Reviewed-SHA: [REVIEW_SHA]` (the full 40-hex head you were pinned to) in the persisted body, outside the marker. `/review-pr` scopes its completion wait and idempotent re-entry to this line, so a comment without the current head does not count as a completed review. Do NOT put the SHA inside the `<!-- FORGE:REVIEW-AGENT:{domain} -->` marker.
 11. **Failure scenario and scope (provenance inputs)**: every finding's body section (the prose above the findings block) MUST carry a `**Failure scenario**` line — concrete inputs leading to a wrong output or behaviour — and a `**Scope**: changed` or `**Scope**: pre-existing` line (`changed` = the cited line is added or modified by this PR; `pre-existing` = it was already there). `/review-pr` §6B.4 reads these: a finding without a failure scenario is demoted to a note (unless CRITICAL/HIGH, any confidence), and a MEDIUM or lower finding whose cited line is not in the PR diff is routed as pre-existing (CRITICAL/HIGH never are; see §5). The `**Scope**` tag is informational and never gates routing. Speculative hardening with no failure scenario is a note, not a finding. The one-line `<!-- FINDING:... -->` grammar above is unchanged. <!-- Added: forge#3452 -->
+12. **Fix efficacy (linked-issue contradiction)**: when a finding says the PR's linked issue is NOT fixed, or that the PR re-introduces the defect it claims to fix, its body section MUST carry a `**Fix efficacy**: fails` (the fix does not work) or `**Fix efficacy**: regresses` (the PR re-introduces the defect) line, and the prose may include the token on its own line (`FIX_EFFICACY: fails|regresses`; line-anchored, a mid-sentence mention does not count). Opt-in on the tag, never on keywords. `/review-pr` §6B.5 passes it to `scripts/classify-finding.sh --fix-efficacy`, which exempts a MEDIUM finding from the fix-PR damper. Use it only for the linked issue's own fix; never for unrelated defects. The one-line `<!-- FINDING:... -->` grammar is unchanged. <!-- Added: forge#3693 -->
 
 ### Domain Prefixes
 

package/commands/review-pr-agents.md

@@ -35,6 +35,12 @@ post `FORGE:REVIEW_BLOCKED` and never replace the isolated review with inline wo
 
 ---
 
+## Read-Only Git Rule (all reviewer agents)
+
+Every reviewer agent is read-only with respect to the main checkout (the repo's shared primary working tree). It MUST NOT run `git checkout`, `git switch`, `git reset`, `git stash`, or `git merge` there: those race with the operator and other agents. Read PR code with `git show <sha>:<path>`, `gh pr diff`, `gh api`, or a per-PR worktree (`git worktree add --detach`) that the agent removes afterward. The orchestrator appends this rule to every dispatched prompt (review-pr.md Phase 3C). <!-- Added: forge#3650 -->
+
+---
+
 ## How to Load Agents (Phase 3C)
 
 For each agent selected in Phase 3B, read **only** the files relevant to that agent:
@@ -49,14 +55,16 @@ For each agent selected in Phase 3B, read **only** the files relevant to that ag
 | Agent | Trigger | Marker domain | File |
 |-------|---------|---------------|------|
 | General Security & Quality Scan | ALWAYS RUNS | `security` | `review-pr-agents/security.md` |
-| Auth Conventions Auditor | AUTH domain | `auth` | `review-pr-agents/auth.md` |
+| Auth Conventions Auditor | Auth/session/trust-filter files changed (path-gated) | `auth` | `review-pr-agents/auth.md` |
 | Billing Integrity Auditor | BILLING domain | `billing` | `review-pr-agents/billing.md` |
 | Concurrency & Race Condition Auditor | CONCURRENCY or BILLING domain | `concurrency` | `review-pr-agents/concurrency.md` |
 | Domain Logic Auditor | SCRAPING domain (requires `review.domains.scraping` in forge.yaml) | `scraper` | `review-pr-agents/scraper.md` |
 | Frontend Quality Auditor | WEB service touched | `frontend` | `review-pr-agents/frontend.md` |
 | API Design & Consistency Auditor | New/modified routers or SDK/OpenAPI files | `api` | `review-pr-agents/api.md` |
 | Database & Migration Auditor | DATABASE domain | `database` | `review-pr-agents/database.md` |
-| Infrastructure & Deploy Safety Auditor | INFRA service touched | `infra` | `review-pr-agents/infra.md` |
+| Infrastructure & Deploy Safety Auditor | Docker, CI, deploy or infra files changed (path-gated) | `infra` | `review-pr-agents/infra.md` |
+
+The table is applied by `scripts/review-roster.sh` (Phase 3B Step 4), which tiers the roster by diff size and fix-PR lineage: small and fix PRs run Security only unless a path trigger fires, and Auth and Infra are selected by file path, never by diff-text score. `--thorough` and milestone-to-staging always run the full union. The tier and reason are recorded in `FORGE:REVIEW_TIER`.
 
 ## Domain Prefixes (for Structured Findings)