forgedock 1.0.22 → 1.1.2

package/commands/audit-agents.md

@@ -1,6 +1,7 @@
 ---
 description: Audit agent outputs from an orchestration run — timeline analysis, stall detection, active vs idle time breakdown
 argument-hint: [session-id | latest | <agent-id>]
+install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -48,20 +49,49 @@ fi
 
 ### Step 1A: Find the session
 
-Agent outputs live in `/tmp/claude-1000/` as symlinks to JSONL files in `~/.claude/projects/*/subagents/`.
+Agent outputs live in `~/.claude/projects/{munged-project-path}/subagents/agent-{agentId}.jsonl`.
+The project path munging rule: both `/` and `.` are replaced with `-`
+(e.g. `/home/user/projects/myproject` → `-home-user-projects-myproject`).
 
-```bash
-# List recent sessions
-ls -lt /tmp/claude-1000/ 2>/dev/null | head -10
-
-# For each session dir, list agent output files
-for DIR in /tmp/claude-1000/*/; do
-  TASKS_DIR="${DIR}*/tasks/"
-  AGENT_COUNT=$(find $TASKS_DIR -name "a*.output" -type l 2>/dev/null | wc -l)
-  if [ "$AGENT_COUNT" -gt 0 ]; then
-    echo "$(stat -c %Y "$DIR" 2>/dev/null) $DIR ($AGENT_COUNT agents)"
-  fi
-done | sort -rn | head -5
+```python
+import os, sys
+from pathlib import Path
+
+def _session_project_dir(project_path):
+    """Convert a Claude Code project path to its ~/.claude/projects/ directory name.
+    Rule: both '/' and '.' are replaced with '-'.
+    Matches pipeline-health.md _session_project_dir() exactly.
+    """
+    import re
+    return re.sub(r'[/.]', '-', project_path)
+
+CLAUDE_PROJECTS_DIR = Path.home() / ".claude" / "projects"
+
+# Discover all subagent JSONL files under ~/.claude/projects/
+# Each subagent file: ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl
+subagent_files = []
+if CLAUDE_PROJECTS_DIR.exists():
+    for jsonl_path in sorted(CLAUDE_PROJECTS_DIR.rglob("subagents/agent-*.jsonl"),
+                             key=lambda p: p.stat().st_mtime, reverse=True):
+        # Only process files with actual content (> 10 lines / non-empty)
+        try:
+            size = jsonl_path.stat().st_size
+            if size < 200:  # 200 bytes ≈ fewer than 10 minimal JSONL lines
+                continue
+            # Count lines portably without wc -l
+            with open(jsonl_path, 'rb') as fh:
+                line_count = sum(1 for _ in fh)
+            if line_count > 10:
+                subagent_files.append(jsonl_path)
+        except OSError:
+            continue
+
+if not subagent_files:
+    print("SKIPPED — transcripts unreadable on this platform")
+    print("  ~/.claude/projects/ not found or contains no subagent JSONL files.")
+    sys.exit(0)
+
+print(f"Found {len(subagent_files)} subagent JSONL file(s) under {CLAUDE_PROJECTS_DIR}")
 ```
 
 **Input resolution:**
@@ -72,20 +102,47 @@ done | sort -rn | head -5
 
 ### Step 1B: Collect agent JSONL files
 
-```bash
-SESSION_DIR="/tmp/claude-1000/{PROJECT_PATH}/{SESSION_ID}"
-TASKS_DIR="${SESSION_DIR}/tasks"
-
-# Agent files are symlinks starting with 'a' pointing to .jsonl files
-for LINK in ${TASKS_DIR}/a*.output; do
-  AGENT_ID=$(basename "$LINK" .output)
-  TARGET=$(readlink -f "$LINK")
-  LINES=$(wc -l < "$TARGET" 2>/dev/null || echo 0)
-  echo "$AGENT_ID $LINES $TARGET"
-done
+```python
+import os
+from pathlib import Path
+
+# Filter subagent_files by $ARGUMENTS (session UUID, agent ID, project fragment, or "latest")
+ARGUMENT = "$ARGUMENTS".strip()
+
+if not ARGUMENT or ARGUMENT.lower() == "latest":
+    # Use the most recent session — take the most recently modified subagent directory
+    # Group by parent session dir (grandparent of the subagent file)
+    by_session = {}
+    for p in subagent_files:
+        session_dir = p.parent.parent  # .../projects/{project}/{sessionId}/
+        mtime = session_dir.stat().st_mtime if session_dir.exists() else 0
+        if session_dir not in by_session or mtime > by_session[session_dir][0]:
+            by_session[session_dir] = (mtime, [])
+        by_session[session_dir][1].append(p)
+    if by_session:
+        latest_session_dir = max(by_session, key=lambda d: by_session[d][0])
+        agent_files = by_session[latest_session_dir][1]
+    else:
+        agent_files = []
+else:
+    # Filter by session UUID, agent ID, or project path fragment
+    agent_files = [
+        p for p in subagent_files
+        if ARGUMENT in str(p)
+    ]
+
+if not agent_files:
+    print(f"SKIPPED — no matching agent JSONL files found for argument: {ARGUMENT!r}")
+    import sys; sys.exit(0)
+
+print(f"Processing {len(agent_files)} agent file(s)")
+for p in agent_files:
+    agent_id = p.stem.replace("agent-", "", 1)
+    print(f"  {agent_id}  {p}")
 ```
 
 Only process files with `> 10` lines (smaller files are helper/polling agents, not work-on agents).
+Line count is computed in Python from the actual JSONL bytes — not from a symlink stub.
 
 ---
 
@@ -189,17 +246,43 @@ def parse_agent(filepath, agent_id):
     max_replays = max(ts_counts.values()) if ts_counts else 1
     resume_cycles = max_replays - 1  # first occurrence is original, rest are replays
 
-    # Build phase timeline from unique skill invocations
+    # Build phase timeline from unique skill invocations.
+    # Stall detection: a gap is a TRUE STALL only when it is >120s AND contains zero
+    # tool_use events (i.e. ends in end_turn with no tool calls in the window).
+    # Gaps that contain any tool_use block (Bash, Edit, Read, Grep, …) are ACTIVE work —
+    # the agent was building; only Skill() calls were sparse.
+    #
+    # To detect tool activity between consecutive Skill() calls we collect all
+    # tool_use timestamps from the raw lines and check whether any fall in the gap.
+    all_tool_use_ts = []
+    for raw_line in lines:
+        raw = json.loads(raw_line)
+        raw_msg = raw.get('message', {})
+        raw_content = raw_msg.get('content', [])
+        raw_ts_str = raw.get('timestamp', '')
+        if raw_ts_str and isinstance(raw_content, list):
+            for c in raw_content:
+                if c.get('type') == 'tool_use':
+                    try:
+                        all_tool_use_ts.append(
+                            datetime.fromisoformat(raw_ts_str.replace('Z', '+00:00'))
+                        )
+                    except ValueError:
+                        pass
+
     phases = []
     prev_ts = first_ts
     for si in skill_invocations:
         gap_sec = (si['ts'] - prev_ts).total_seconds()
+        # Any tool_use event inside the gap window means the agent was active
+        has_tool_use_in_gap = any(prev_ts < t <= si['ts'] for t in all_tool_use_ts)
+        is_stall = gap_sec > 120 and not has_tool_use_in_gap
         phases.append({
             'ts': si['ts'],
             'skill': si['skill'],
             'args': si['args'],
             'gap_from_prev_sec': gap_sec,
-            'is_stall': gap_sec > 120  # > 2 min = stall
+            'is_stall': is_stall,  # True only when >2 min AND zero tool calls in gap
         })
         prev_ts = si['ts']
 
@@ -433,6 +516,6 @@ This enables tracking whether orchestrator/prompt changes actually improved thro
 ## Notes
 
 - **File format**: Agent outputs are JSONL (one JSON object per line). Each line has `type` (user/assistant), `timestamp`, `message` (with `content` array and optional `stop_reason`).
-- **Symlinks**: Files in `/tmp/claude-1000/*/tasks/a*.output` are symlinks to `~/.claude/projects/*/subagents/agent-*.jsonl`.
+- **Subagent files**: Located at `~/.claude/projects/{munged-project-path}/{sessionId}/subagents/agent-{agentId}.jsonl`. The munging rule: both `/` and `.` in the project path are replaced with `-` (e.g. `/home/user/projects/myapp` → `-home-user-projects-myapp`). There are no platform-specific temp paths or symlinks involved.
 - **Size filtering**: Only analyze files > 10 lines. Small files are helper/polling agents spawned by the orchestrator for status checks.
 - **Resume detection**: When an agent is resumed, the full conversation is replayed. Duplicate `(timestamp, skill_name)` pairs indicate replay cycles. `max(duplicates) - 1 = resume_cycles`.

package/commands/audit.md

@@ -1,6 +1,7 @@
 ---
 description: Trace a production issue or pipeline failure end-to-end through GitHub artifacts, then file a detailed improvement issue to the Forge repo
 argument-hint: <description of what went wrong> [--issue N] [--pr N] [--repo prefix]
+install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -13,7 +14,7 @@ You are Forge's post-mortem auditor. When something reaches production that shou
 
 **This command ALWAYS files issues to `{FORGE_REPO}`.** The target project is read-only — you only read its GitHub artifacts as evidence.
 
-**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).**
 
@@ -286,6 +287,24 @@ Create a detailed, actionable issue in the **Forge repository**.
 
 ### 4B: Create the issue
 
+**Before creating, run the deterministic dedup check:** <!-- Added: forge#1335 -->
+
+```bash
+AUDIT_TITLE="fix(pipeline): {one-line description of what the pipeline missed}"
+DEDUP_RESULT=$(scripts/issue-dedup.sh "$AUDIT_TITLE" -R {FORGE_REPO} 2>&1)
+DEDUP_EXIT=$?
+if [ "$DEDUP_EXIT" -eq 1 ]; then
+  echo "DEDUP: Audit finding near-duplicate — $DEDUP_RESULT"
+  echo "Skipping creation. Comment on the existing issue with new evidence instead."
+  # Do NOT call gh issue create for this audit finding
+elif [ "$DEDUP_EXIT" -eq 2 ]; then
+  echo "DEDUP: Usage error — $DEDUP_RESULT"
+  # Do NOT call gh issue create for this audit finding — fix the invocation and retry
+fi
+```
+
+Only call `gh issue create` when the dedup script exits 0:
+
 ```bash
 gh issue create -R {FORGE_REPO} \
   --title "fix(pipeline): {one-line description of what the pipeline missed}" \

package/commands/autopilot.md

@@ -1,6 +1,7 @@
 ---
 description: Autonomous platform improvement cycle — recon, triage, fix, report. Runs recon+triage by default; pass --fix to also pick up and fix top issues. Human gates all deploys.
-argument-hint: [--fix | --recon-only | --fix --limit 5 | --dry-run]
+argument-hint: [--fix | --recon-only | --fix --limit 5 | --dry-run | --fix --yes]
+install: extras
 ---
 
 # /autopilot — Recursive Platform Improvement Cycle
@@ -10,7 +11,7 @@ argument-hint: [--fix | --recon-only | --fix --limit 5 | --dry-run]
 **Config variables used by this command** (set in `forge.yaml`):
 - `{CREDENTIALS_FILE}` ← `paths.credentials.file` (optional) — path to credentials YAML for analytics APIs
 - `{SERVER_SSH}` ← `services.server_ssh` (optional) — SSH target for production server health checks (e.g., `ubuntu@1.2.3.4`)
-- `{EMEMO_PATH}` ← `services.ememo_path` (optional) — path on production server to open eMemo files
+- `{OPS_INBOX_PATH}` ← `services.ops_inbox_path` (optional) — path on production server to a directory of open work-item files (e.g. `/srv/ops/inbox`)
 - `{BILLING_ENABLED}` ← `billing.enabled` (optional, default `false`) — set to `true` to enable Stripe data collection in the Analytics Snapshot agent
 
 Resolve `{BILLING_ENABLED}` from `forge.yaml` before executing any phase:
@@ -19,13 +20,18 @@ Resolve `{BILLING_ENABLED}` from `forge.yaml` before executing any phase:
 BILLING_ENABLED=$(yq '.billing.enabled // false' "$(git rev-parse --show-toplevel)/forge.yaml" 2>/dev/null || echo 'false')
 ```
 
+**NEVER use plan mode (EnterPlanMode).**
+**NEVER use the Agent tool** — autopilot dispatches work via `Skill(skill="work-on", ...)` only. The Agent tool bypasses the Skill pipeline's label state machine, investigation comments, and structured review — leaving no audit trail.
+
+<!-- FORGE:SPEC_LOADED — autopilot.md loaded and active. Agent is bound by this spec. -->
+
 You are an autonomous improvement engine for this project. Your job is to **find what's wrong, create trackable issues, and optionally fix the highest-impact ones** — all in a single cycle. Every cycle leaves the platform measurably better than before.
 
 **This is designed to run repeatedly.** Each cycle builds on the last — issues created in cycle N get fixed in cycle N+1. The platform compounds improvements over time.
 
 **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"`. User can override with `--model <name>`. Pass the resolved model in every `Agent`/`Task` tool call. Each agent prompt is scoped to a specific data source or issue — the model executes the explicit steps without needing broad inference.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. User can override with `--model <name>`. Pass model explicitly in every `Agent`/`Task` tool call. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 
 ---
 
@@ -38,6 +44,7 @@ You are an autonomous improvement engine for this project. Your job is to **find
 | `--fix --limit N` | Fix at most N issues (default: 3) |
 | `--recon-only` | Phase 1 only (data collection, no issue creation) |
 | `--dry-run` | Run everything but don't create issues or PRs — just report what would happen |
+| `--fix --yes` | Auto-approve low-risk fixes (P3, single-file, non-sensitive domain); P0/P1, multi-file, and sensitive-domain fixes still require confirmation |
 
 Parse `$ARGUMENTS` and set these variables:
 ```
@@ -45,6 +52,7 @@ MODE = "full" | "recon-only" | "fix"    # derived from flags
 DO_FIX = true if --fix present
 FIX_LIMIT = N from --limit N, default 3
 DRY_RUN = true if --dry-run present
+AUTO_YES = true if --yes present
 ```
 
 ---
@@ -112,7 +120,7 @@ Spawn these as **background agents** (all `run_in_background=true`, all `model="
 **Agent: Production Health**
 ```
 Check production system health:
-1. SSH to check for open eMemos: if {SERVER_SSH} is configured, run: ssh {SERVER_SSH} "ls {EMEMO_PATH}/*-open-* 2>/dev/null" — skip this step if SERVER_SSH or EMEMO_PATH is not set in forge.yaml
+1. SSH to check for open ops-inbox items: if {SERVER_SSH} is configured, run: ssh {SERVER_SSH} "ls {OPS_INBOX_PATH}/*-open-* 2>/dev/null" — skip this step if SERVER_SSH or OPS_INBOX_PATH is not set in forge.yaml
 2. If any exist, cat each one and summarize
 3. Check container health via MCP: get_production_status, run_production_health_check
 4. Check recent error logs: get_production_logs for api and worker (last 100 lines), grep for ERROR/CRITICAL
@@ -197,7 +205,7 @@ For each finding from RECON_DATA, assign:
 
 | Signal | Priority | Type |
 |--------|----------|------|
-| Production eMemo (open) | P1 | bug |
+| Open ops-inbox item | P1 | bug |
 | Container unhealthy | P0 | bug |
 | Error spike (>5x normal) | P1 | bug |
 | Tier degradation (>20% drop) | P2 | bug |
@@ -286,7 +294,7 @@ Print a structured report:
 
 ### Production Health
 - Containers: {all healthy / N unhealthy}
-- Open eMemos: {count}
+- Open ops-inbox items: {count}
 - Error patterns: {summary or "none"}
 
 ### Scraping Performance
@@ -356,22 +364,47 @@ gh issue list --state open --label "bug" --limit 50 --json number,title,labels,c
 
 **MANDATORY CHECKPOINT — do NOT proceed without user confirmation.**
 
+**Exception**: when `AUTO_YES = true`, classify each fix target by risk tier before prompting. Low-risk fixes are auto-approved; high-risk fixes still require confirmation.
+
+**Risk classification** (evaluate per-issue at this step):
+
+```
+LOW_RISK = all of the following are true:
+  - Priority is P2 or P3 (not P0 or P1)
+  - Affects only a single file (from issue body or recon finding)
+  - No sensitive-domain labels: auth, billing, database, security, payments, gdpr
+
+HIGH_RISK = any of the following:
+  - Priority P0 or P1
+  - Multi-file change (2+ files)
+  - Has a sensitive-domain label (auth, billing, database, security, payments, gdpr)
+  - Issue has `needs-human` label
+```
+
+When `AUTO_YES = true`:
+- **LOW_RISK issues**: auto-approve, log `[AUTO-APPROVED: low-risk]`, proceed to 4B.5/4C without waiting.
+- **HIGH_RISK issues**: present the checkpoint below and wait for user response. If user skips, remove from fix targets and continue with remaining low-risk issues.
+
+When `AUTO_YES = false` (default): present the full checkpoint for ALL fix targets and wait.
+
 ```markdown
 ## Autopilot Fix Plan
 
 I'll run `/work-on` for these {N} issues:
 
-| # | Title | Priority | Estimated Scope |
-|---|-------|----------|-----------------|
-| {number} | {title} | {priority} | {small/medium/large} |
+| # | Title | Priority | Estimated Scope | Risk Tier |
+|---|-------|----------|-----------------|-----------|
+| {number} | {title} | {priority} | {small/medium/large} | LOW / HIGH |
 
 Each issue goes through: investigate → validate → build → review → merge to staging.
 Nothing merges to `main` — you deploy when ready.
 
+{If AUTO_YES and any HIGH_RISK: "Note: {N_low} low-risk issues were auto-approved. The {N_high} high-risk issue(s) above require your confirmation."}
+
 **Proceed?** (yes / adjust / skip)
 ```
 
-Wait for user response. If they adjust, re-select. If they skip, end the cycle.
+Wait for user response on high-risk issues. If they adjust, re-select. If they skip all, end the cycle.
 
 ### 4B.5: Spec-Edit Impact Analysis (MANDATORY before any spec-touching fix) <!-- Added: forge#870 -->
 
@@ -484,6 +517,44 @@ FIX_RESULTS.push({
 When ready to deploy, merge `staging` → `main` via GitHub.
 ```
 
+### 4E: Deploy Train Check <!-- Added: forge#1332 -->
+
+After fixes are merged to staging, check the deploy train state. The deploy train is the single rolling staging→main PR — one per deploy cycle. Do NOT open a new staging→main PR if one is already open.
+
+```bash
+# Check for an open staging→main deploy PR (the current train)
+TRAIN_PR=$(gh pr list {GH_FLAG} \
+  --head "{STAGING_BRANCH}" \
+  --base "{DEFAULT_BRANCH}" \
+  --state open \
+  --json number,url \
+  --jq '.[0] // empty' 2>/dev/null)
+
+TRAIN_PR_NUMBER=$(echo "$TRAIN_PR" | jq -r '.number // empty')
+
+if [ -n "$TRAIN_PR_NUMBER" ]; then
+  # Train exists — check if it is held by open findings
+  HELD_BY_COUNT=$(gh issue list {GH_FLAG} \
+    --label "review-finding" \
+    --state open \
+    --search "PR #${TRAIN_PR_NUMBER}" \
+    --json number --jq '. | length' 2>/dev/null || echo 0)
+
+  if [ "$HELD_BY_COUNT" -gt 0 ]; then
+    echo "Deploy train PR #${TRAIN_PR_NUMBER} is HELD by ${HELD_BY_COUNT} open finding(s)."
+    echo "The fixes merged in this autopilot cycle may resolve some of them."
+    echo "Re-run /review-pr-staging ${TRAIN_PR_NUMBER} to re-evaluate the train gate."
+  else
+    echo "Deploy train PR #${TRAIN_PR_NUMBER} is CLEAR — no open findings. Ready to merge when you authorize."
+  fi
+else
+  echo "No open staging→main PR found. The merged fixes are queued in staging."
+  echo "Run /review-pr-staging to open a new train PR when ready."
+fi
+```
+
+**Deploy policy**: Autopilot NEVER merges staging→main. It merges issue fixes TO staging only. The train PR is a human-gated merge — the user decides when to ship.
+
 ---
 
 ## Safety Rules
@@ -497,7 +568,7 @@ When ready to deploy, merge `staging` → `main` via GitHub.
 7. **If a fix fails, move on** — don't retry. Log it and let the next cycle or human handle it.
 8. **DRY_RUN means NO side effects** — no issues created, no PRs, no label changes. Report only.
 9. **P0 overrides everything** — if P0 exists, skip normal recon and fix P0 immediately.
-10. **Always gate fixes on user approval** — Phase 4B checkpoint is non-negotiable.
+10. **Always gate high-risk fixes on user approval** — Phase 4B checkpoint is non-negotiable for P0/P1, multi-file, or sensitive-domain changes. `--yes` only auto-approves LOW_RISK tier (P2/P3, single-file, non-sensitive).
 
 ---
 
@@ -525,4 +596,5 @@ The platform gets better every cycle. Issues that aren't picked up age and rise
 - **Runtime**: Recon-only ~3-5 min. Full cycle with fixes ~15-45 min depending on issue count.
 - **Token budget**: Recon is cheap (mostly MCP + API calls). Fixes are expensive (full /work-on per issue).
 - **Idempotent**: Safe to run multiple times — dedup prevents duplicate issues, /work-on resumes from checkpoints.
-- **Pairs with /loop**: Run `/loop 4h /autopilot` for continuous improvement, or `/loop 4h /autopilot --fix --limit 2` for autonomous fixing with a human checkpoint every cycle.
+- **Pairs with /loop**: Run `/loop 4h /autopilot` for continuous improvement, `/loop 4h /autopilot --fix --limit 2` for autonomous fixing with a human checkpoint every cycle, or `/loop 4h /autopilot --fix --yes` for fully unattended low-risk fixes (high-risk issues still surface for approval).
+- **Event-driven complement**: `/autopilot` is a periodic cycle. When a specific production signal fires (metric regression, incident, GEO gap), use `/signal-planner` instead — it converts the signal into a dependency-ordered issue DAG, executes via `/orchestrate`, and verifies the originating signal is resolved after the work merges. Use `/autopilot` for scheduled health sweeps; use `/signal-planner` for targeted signal-driven response.

package/commands/changelog.md

@@ -1,6 +1,7 @@
 ---
 description: Auto-generate release notes from merged PRs and FORGE:TRAJECTORY annotations — grouped by conventional commit type
 argument-hint: [v1.0.0..v1.1.0 | since:YYYY-MM-DD | last-N]
+install: extras
 ---
 
 # /changelog — Release Notes Generator
@@ -9,7 +10,7 @@ argument-hint: [v1.0.0..v1.1.0 | since:YYYY-MM-DD | last-N]
 
 Generate a structured markdown changelog from merged PRs and their FORGE:TRAJECTORY annotations. Groups entries by conventional commit type (feat, fix, refactor, docs, chore) and enriches each entry with task type and investigation verdict from the pipeline's annotation layer.
 
-**Agent model policy**: Default `model: "sonnet"`. Fallback: `model: "opus"` if Sonnet is rate-limited.
+**Agent model policy**: `model: "haiku"`, `effort: low` (mechanical tier — annotation reading, changelog generation). Fallback: `model: "sonnet"` if rate-limited. Feature gate: pass `effort` only on Claude Code >= 2.1.154.
 
 **NEVER use plan mode (EnterPlanMode)** — it breaks execution context.
 

package/commands/ci-audit.md

@@ -1,6 +1,7 @@
 ---
 description: Stack-aware CI gap detection — audits a project's GitHub Actions workflows against its declared tech stack and files issues for missing config validation checks
 argument-hint: [--repo <prefix>] [--dry-run]
+install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -29,7 +30,7 @@ This command is designed to be run:
 
 This is NOT a PR review — it does not approve or block. It creates issues for each CI gap found.
 
-**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/cleanup.md

@@ -1,6 +1,7 @@
 ---
 description: Sweep closed issues for stale labels, missing workflow state, and Project board gaps — plus prune worktrees, branches, and milestones
 argument-hint: [labels | branches | milestones | board | orphans | all]
+install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -44,11 +45,12 @@ All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{STAGING_BRANCH}`, `{PROJECT_BOARD
 
 | Input | Action |
 |-------|--------|
-| `labels` or empty | Fix stale/missing workflow labels on closed issues |
+| `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 |
 | `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 |
+| `batch-p3` | Sweep: fold stale unbatched P3 review findings into domain-grouped batch issues |
 | `all` | All of the above, in order |
 
 ---
@@ -105,6 +107,46 @@ gh issue list {GH_FLAG} --state closed --limit 200 --json number,title,labels \
 
 These were closed outside the pipeline. Report count but don't fix (not necessarily wrong).
 
+### 1D: Detect stale OPEN issues in intermediate workflow states
+
+Open issues stuck in `workflow:building`, `workflow:in-review`, or `workflow:investigating` beyond a configurable threshold indicate a stalled agent. These are invisible to Phase 1A–1C (which only query closed issues).
+
+```bash
+# Configurable threshold — override by setting STALE_THRESHOLD_HOURS before invoking /cleanup
+STALE_THRESHOLD_HOURS=${STALE_THRESHOLD_HOURS:-48}
+
+# Compute cutoff datetime — GNU date (Linux) with BSD date (macOS) fallback
+CUTOFF=$(date -d "${STALE_THRESHOLD_HOURS} hours ago" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+  || date -v-${STALE_THRESHOLD_HOURS}H +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+  || echo "")
+
+echo "=== Stale-Open Intermediate Issues (threshold: ${STALE_THRESHOLD_HOURS}h) ==="
+
+STALE_OPEN_COUNT=0
+
+for LABEL in "workflow:building" "workflow:in-review" "workflow:investigating"; do
+  ISSUES=$(gh issue list {GH_FLAG} \
+    --state open \
+    --label "$LABEL" \
+    --limit 100 \
+    --json number,title,updatedAt,labels \
+    --jq --arg threshold "$CUTOFF" --arg label "$LABEL" \
+    '[.[] | select($threshold == "" or .updatedAt < $threshold)] |
+     .[] | "#\(.number) — \(.title[:60]) [label: \($label)] [last update: \(.updatedAt[:10])] → resume: /work-on \(.number)"' \
+    2>/dev/null || echo "")
+
+  if [ -n "$ISSUES" ]; then
+    echo "$ISSUES"
+    COUNT=$(echo "$ISSUES" | grep -c '^#' 2>/dev/null || echo 0)
+    STALE_OPEN_COUNT=$((STALE_OPEN_COUNT + COUNT))
+  fi
+done
+
+echo "Total stale-open intermediate issues: $STALE_OPEN_COUNT"
+```
+
+These are **report-only** — no automatic action is taken. Use `/work-on <n>` (idempotent) to resume a stalled issue. Priority issues (P1/P2) should be actioned first.
+
 ---
 
 ## Phase 2: Orphaned Issues (open issues with merged PRs)
@@ -278,6 +320,111 @@ Do NOT call `gh api ... -X PATCH -f state=closed` on any milestone. This phase i
 
 ---
 
+## Phase 4B: P3 Batch Sweep (if `batch-p3` or `all`)
+
+<!-- Added: forge#1333 -->
+
+**Purpose**: Fold stale unbatched P3 review findings into domain-grouped batch issues. Reduces pipeline overhead from individual per-finding full-pipeline runs.
+
+**Skip if**: Input is not `batch-p3` and not `all`.
+
+### Step 4B.1: Fetch open batchable P3 findings
+
+```bash
+# Find all open P3 review findings that carry the FORGE:BATCHABLE annotation
+# and are not already members of a batch (no "batch" label)
+UNBATCHED_P3=$(gh issue list {GH_FLAG} \
+  --state open \
+  --label "review-finding,priority:P3" \
+  --limit 500 \
+  --json number,title,body,labels,createdAt \
+  --jq '.[] | select(.body | test("<!-- FORGE:BATCHABLE -->"))
+         | select(([.labels[].name] | any(. == "batch")) | not)
+         | select(([.labels[].name] | any(. == "security" or . == "billing")) | not)
+         | select((.title | test("security|billing|payment|stripe"; "i")) | not)')
+
+echo "Unbatched batchable P3 findings: $(echo "$UNBATCHED_P3" | jq -s 'length')"
+```
+
+### Step 4B.2: Group by domain
+
+For each finding, extract the domain from the first affected file path under `## Affected Files`:
+
+```bash
+# Domain = top-level directory of the first affected file
+# e.g., "services/api/auth/login.py" → "services/api/auth"
+#        "commands/review-pr.md"     → "commands"
+# Exclude findings where the domain contains "billing" or "security"
+
+# Group findings by domain, track oldest creation timestamp per group
+declare -A DOMAIN_ISSUES
+declare -A DOMAIN_OLDEST
+
+echo "$UNBATCHED_P3" | jq -c '.[]' | while read -r issue; do
+  NUM=$(echo "$issue" | jq -r '.number')
+  CREATED=$(echo "$issue" | jq -r '.createdAt')
+  BODY=$(echo "$issue" | jq -r '.body')
+
+  # Extract first affected file path from body
+  FIRST_FILE=$(echo "$BODY" | sed -n '/^## Affected Files/,/^## /p' | grep -oP '`[^`]+`' | head -1 | tr -d '`')
+  if [ -z "$FIRST_FILE" ]; then
+    FIRST_FILE=$(echo "$BODY" | grep -oP '(?<=\`)[^`]+\.(?:py|ts|tsx|js|go|rs|java|sh|md)(?=\`)' | head -1 || echo "unknown")
+  fi
+  DOMAIN=$(echo "$FIRST_FILE" | cut -d/ -f1,2,3 | sed 's|/[^/]*$||')
+  [ -z "$DOMAIN" ] && DOMAIN="general"
+
+  echo "${NUM}:${DOMAIN}:${CREATED}"
+done
+```
+
+### Step 4B.3: Apply batching threshold
+
+For each domain group:
+- **Trigger**: 5+ unbatched batchable P3 findings in the domain, **OR** the oldest finding in the domain is > 72 hours old
+- **No trigger**: fewer than 5 findings AND none older than 72 hours → skip (no batch created)
+
+```bash
+NOW_EPOCH=$(date +%s)
+HOURS_72=$((72 * 3600))
+
+# For each domain group that meets the threshold, create a batch issue
+# (max 10 members per batch — if more, create multiple batches of ≤ 10 each)
+
+# Exclude domains with "security" or "billing" in the domain path
+echo "$DOMAIN_ISSUES" | while IFS=: read -r domain issue_list; do
+  echo "$domain" | grep -qiE 'security|billing' && continue
+
+  COUNT=$(echo "$issue_list" | tr ',' '\n' | wc -l)
+  OLDEST_EPOCH=$(echo "$DOMAIN_OLDEST[$domain]" | date -d "$..." +%s 2>/dev/null || echo "$NOW_EPOCH")
+  AGE_SECS=$((NOW_EPOCH - OLDEST_EPOCH))
+
+  if [ "$COUNT" -ge 5 ] || [ "$AGE_SECS" -ge "$HOURS_72" ]; then
+    echo "Batching $COUNT P3 findings in domain: ${domain}"
+    # Create batch issues (in chunks of ≤ 10)
+    # See orchestrate.md Phase 1 for the batch creation template
+  fi
+done
+```
+
+**Batch creation** uses the same template as `orchestrate.md Phase 1 → P3 Review-Finding Batching`. After creating the batch issue, add the `batch` label to each member issue to prevent re-batching on the next sweep.
+
+### Step 4B.4: Report
+
+```
+## P3 Batch Sweep
+
+| Domain | Unbatched P3s | Threshold Met | Action |
+|--------|--------------|---------------|--------|
+| {domain} | {N} | ≥5 issues | Created batch #{NUM} ({M} members) |
+| {domain} | {N} | Oldest > 72h | Created batch #{NUM} ({M} members) |
+| {domain} | {N} | Below threshold | No action |
+
+Total batch issues created: {N}
+Total P3 findings batched: {N}
+```
+
+---
+
 ## Phase 5: Sync Project Board (if `board` or `all`)
 
 **Skip if `project_board` is not configured** — check resolved vars before proceeding:
@@ -320,6 +467,13 @@ fi
 | workflow:investigating → cleaned | {N} |
 | needs-validation removed | {N} |
 
+### Stale-Open Intermediate Issues (Phase 1D)
+| Issue | Label | Last Update | Action |
+|-------|-------|-------------|--------|
+| #{N} | workflow:X | YYYY-MM-DD | `/work-on {N}` to resume |
+
+*Total stale-open: {N} (threshold: {STALE_THRESHOLD_HOURS}h)*
+
 ### Orphaned Issues Closed
 | Issue | Merged PR | Action |
 |-------|-----------|--------|
@@ -345,4 +499,10 @@ fi
 
 ### Still Missing Workflow Label
 {N} closed issues have no workflow label (closed outside pipeline — no action needed)
+
+### P3 Batch Sweep Results
+| Domain | Unbatched P3s | Action |
+|--------|--------------|--------|
+| {domain} | {N} | Created batch #{NUM} with {M} members |
+| {domain} | {N} | Below threshold — no action (< 5 findings, none > 72h) |
 ```