forgedock 1.16.2 → 1.17.0

package/commands/cleanup.md

@@ -10,7 +10,7 @@ install: extras
 
 **Input**: $ARGUMENTS
 
-Scan the entire development environment for rot and fix it. This is a maintenance command — run periodically or after large orchestration batches. It covers 6 domains: stale labels, orphaned issues, worktree/branch pruning, milestone hygiene, and Project board sync.
+Scan the entire development environment for rot and fix it. This is a maintenance command — run periodically or after large orchestration batches. It covers 6 domains: stale labels, orphaned issues and dead claims boards, worktree/branch pruning, milestone hygiene, and Project board sync.
 
 **NEVER use plan mode (EnterPlanMode)** — it breaks execution context.
 
@@ -46,7 +46,7 @@ All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{STAGING_BRANCH}`, `{PROJECT_BOARD
 | Input | Action |
 |-------|--------|
 | `labels` or empty | Fix stale/missing workflow labels on closed issues; detect OPEN issues stuck in intermediate states (Phase 1D) |
-| `orphans` | Close open issues whose PRs are already merged |
+| `orphans` | Close open issues whose PRs are already merged (Phase 2A/2B), and close dead orchestrate claims boards (Phase 2C) |
 | `branches` | Prune worktrees and remote branches for merged PRs |
 | `milestones` | Report milestones with 0 open issues (advisory — never closes) |
 | `board` | Sync closed issues to Project board with correct terminal state |
@@ -234,6 +234,82 @@ gh issue edit $NUM {GH_FLAG} --remove-label "workflow:in-review,workflow:remedia
 
 Also check open issues with `workflow:building` — same pattern (search for merged PRs referencing them).
 
+### 2C: Close dead orchestrate claims boards <!-- Added: forge#3699 -->
+
+Each `/orchestrate` batch creates one claims board (`orchestrate: claims board for batch <id>`, label `automation`) with no PR of its own, so 2A/2B never match it. `/orchestrate` Phase 5 Step 5C closes the board on a clean finish; batches that end by compaction, freeze, crash or a fresh-context resume never reach it. This sweep is the durable safety net. Runs for `orphans` and `all`; respects `DRY_RUN`.
+
+A board is closed only when **all** identity checks pass and **one** closing condition holds:
+
+- Identity: title starts with `orchestrate: claims board for batch`, body contains `<!-- FORGE:COORD_ISSUE -->`, and the author is trusted: `author_association` `OWNER`, `MEMBER` or `COLLABORATOR`, or a Bot account (the pipeline's GitHub App, reported as `CONTRIBUTOR`). A look-alike issue from an outside account is never closed.
+- Close when the last `FORGE:LEASE*` comment is a `FORGE:LEASE_RELEASED`.
+- Close when the last `FORGE:LEASE*`/`FORGE:CLAIM*` comment is older than `BOARD_STALE_HOURS` (default 6, far above the 15 minute lease TTL).
+- Close when there is no lease/claim comment and the issue itself is older than `BOARD_STALE_HOURS`.
+- Never close a board whose last lease event is an unreleased `FORGE:LEASE` younger than `BOARD_STALE_HOURS`.
+
+```bash
+BOARD_STALE_HOURS=${BOARD_STALE_HOURS:-6}
+BOARD_CUTOFF=$(date -u -d "${BOARD_STALE_HOURS} hours ago" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+  || date -u -v-${BOARD_STALE_HOURS}H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+  || echo "")
+BOARDS_CLOSED=0
+
+if [ -z "$BOARD_CUTOFF" ]; then
+  echo "WARNING: cannot compute BOARD_STALE_HOURS cutoff — only released boards will be closed"
+fi
+
+# REST (not `gh issue list`): it exposes author_association and user.type. Boards are created by the
+# pipeline's GitHub App, which GitHub reports as CONTRIBUTOR, so trust is the same predicate as
+# scripts/trusted-comments.sh: OWNER/MEMBER/COLLABORATOR or a Bot account.
+BOARDS=$(gh api --paginate "repos/{GH_REPO}/issues?state=open&labels=automation&per_page=100" 2>/dev/null \
+  | jq -rs '.[][] | select(.pull_request == null)
+         | select(((.title // "") | startswith("orchestrate: claims board for batch"))
+                  and ((.body // "") | contains("<!-- FORGE:COORD_ISSUE -->"))
+                  and (((.author_association // "") | IN("OWNER","MEMBER","COLLABORATOR")) or ((.user.type // "") == "Bot")))
+         | "\(.number)\t\(.created_at)"' 2>/dev/null || echo "")
+
+while IFS=$'\t' read -r BNUM BCREATED; do
+  [ -z "$BNUM" ] && continue
+
+  # --paginate emits one array per page: slurp (jq -s) and flatten BEFORE taking `last`,
+  # otherwise a board with >30 comments reads a stale event from an earlier page.
+  LAST_LEASE=$(gh api --paginate "repos/{GH_REPO}/issues/${BNUM}/comments" 2>/dev/null \
+    | jq -s '[.[][] | select(.body | contains("FORGE:LEASE"))] | last // empty
+             | {released: (.body | contains("FORGE:LEASE_RELEASED")), at: .created_at}' 2>/dev/null || echo "")
+  LAST_ACTIVITY=$(gh api --paginate "repos/{GH_REPO}/issues/${BNUM}/comments" 2>/dev/null \
+    | jq -rs '[.[][] | select(.body | contains("FORGE:LEASE") or contains("FORGE:CLAIM"))] | last // empty | .created_at' 2>/dev/null || echo "")
+
+  REASON=""
+  if [ -n "$LAST_LEASE" ] && [ "$(echo "$LAST_LEASE" | jq -r '.released')" = "true" ]; then
+    REASON="last lease event is FORGE:LEASE_RELEASED"
+  elif [ -n "$BOARD_CUTOFF" ]; then
+    # ISO-8601 UTC timestamps compare correctly as strings
+    LAST_SEEN="${LAST_ACTIVITY:-$BCREATED}"
+    if [ -n "$LAST_SEEN" ] && [ "$LAST_SEEN" \< "$BOARD_CUTOFF" ]; then
+      REASON="no lease/claim activity since ${LAST_SEEN} (older than ${BOARD_STALE_HOURS}h)"
+    fi
+  fi
+
+  if [ -z "$REASON" ]; then
+    echo "KEEP: board #$BNUM has a live or recent lease"
+    continue
+  fi
+
+  if [ "${DRY_RUN:-false}" = "true" ]; then
+    echo "DRY-RUN: would close claims board #$BNUM — $REASON"
+    continue
+  fi
+
+  # Closing an already-closed issue is a no-op; a gh failure is non-fatal.
+  gh issue close "$BNUM" {GH_FLAG} --comment "Closing dead claims board — ${REASON}.
+
+Closed automatically by \`/cleanup\` Phase 2C." 2>/dev/null \
+    && { echo "Closed claims board #$BNUM ($REASON)"; BOARDS_CLOSED=$((BOARDS_CLOSED + 1)); } \
+    || echo "WARNING: failed to close claims board #$BNUM — non-fatal" # allowlist:check-command-side-effects
+done <<< "$BOARDS"
+
+echo "Claims boards closed: $BOARDS_CLOSED"
+```
+
 ---
 
 ## Phase 3: Worktree & Branch Pruning
@@ -599,6 +675,11 @@ fi
 |-------|-----------|--------|
 | #{N} | PR #{M} | Closed |
 
+### Claims Boards Closed
+| Issue | Reason | Action |
+|-------|--------|--------|
+| #{N} | LEASE_RELEASED / stale > {BOARD_STALE_HOURS}h | Closed |
+
 ### Worktrees & Branches Pruned
 | Type | Count |
 |------|-------|

package/commands/deploy-info.md

@@ -56,13 +56,15 @@ else
   # Step 2: Check for open review-finding issues referencing each PR
   OPEN_FINDINGS_SUMMARY=""
   for pr_num in $ALL_PR_NUMBERS; do
+    # Anchored post-filter (same as review-pr-staging.md): the search is a coarse candidate fetch only
+    FINDING_PR_FILTER='[.[] | select((.title | endswith("PR #" + $n + ")")) or ((.body // "") | test("(^|\\n)\\*\\*Source\\*\\*: PR #" + $n + "([^0-9]|$)")))] | .[] | "  - #\(.number): \(.title)"'  # FINDING_PR_FILTER
     OPEN_FINDINGS=$(gh issue list -R {GH_REPO} \
       --label "review-finding" \
       --state open \
       --search "PR #${pr_num}" \
       --limit 20 \
-      --json number,title \
-      --jq ".[] | \"  - #\(.number): \(.title)\"" 2>/dev/null)
+      --json number,title,body 2>/dev/null \
+      | jq -r --arg n "${pr_num}" "$FINDING_PR_FILTER" 2>/dev/null)  # uses FINDING_PR_FILTER
 
     if [ -n "$OPEN_FINDINGS" ]; then
       OPEN_FINDINGS_SUMMARY="${OPEN_FINDINGS_SUMMARY}
@@ -304,13 +306,15 @@ 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)
+  # Anchored post-filter (same as review-pr-staging.md): the search is a coarse candidate fetch only
+  FINDING_PR_FILTER='[.[] | select((.title | endswith("PR #" + $n + ")")) or ((.body // "") | test("(^|\\n)\\*\\*Source\\*\\*: PR #" + $n + "([^0-9]|$)")))] | .[] | "  - #\(.number): \(.title)"'  # FINDING_PR_FILTER
   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)
+    --json number,title,body 2>/dev/null \
+    | jq -r --arg n "${TRAIN_PR_NUMBER}" "$FINDING_PR_FILTER" 2>/dev/null | sed 's/^  - //' || true)  # uses FINDING_PR_FILTER
 
   if [ -n "$HELD_BY" ]; then
     TRAIN_STATUS="HELD"

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.

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)