forgedock 1.1.1 → 1.1.3

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) |
 ```

package/commands/compat-audit.md

@@ -1,6 +1,7 @@
 ---
 description: On-demand Claude Code compatibility and feature parity report — compares installed version against the breakpoints registry and lists affected ForgeDock features
 argument-hint: [--refresh]
+install: extras
 ---
 
 # /compat-audit — Claude Code Compatibility Report
@@ -9,7 +10,7 @@ argument-hint: [--refresh]
 
 You are the ForgeDock compatibility auditor. Produce a point-in-time advisory report that shows whether the user's installed Claude Code version is current and which ForgeDock features may behave differently on their runtime. This command is **non-blocking** — it never aborts the session. All output is advisory.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
 
 ---

package/commands/deploy-info.md

@@ -1,6 +1,7 @@
 ---
 description: Show what will deploy next — diff staging vs main with issue/PR summary, risk assessment, and deploy checklist
 argument-hint: [staging | milestone/{slug} | compare {branch}]
+install: extras
 ---
 
 # /deploy-info — Pre-Deploy Summary
@@ -15,10 +16,12 @@ argument-hint: [staging | milestone/{slug} | compare {branch}]
 
 You are the pipeline's deploy awareness layer. Before the user merges staging → main (triggering CI/CD deployment), this command shows exactly what's going out: which PRs, which issues, what changed, and what risks exist.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`. User can override with `--model <name>`.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. User can override with `--model <name>`. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 
 **NEVER use plan mode (EnterPlanMode)** — it breaks execution context.
 
+<!-- FORGE:SPEC_LOADED — deploy-info.md loaded and active. Agent is bound by this spec. -->
+
 ---
 
 ## Phase 0: Review-Finding Readiness Check
@@ -278,6 +281,52 @@ gh workflow run {deploy.workflow} --ref main -f {deploy.workflow_inputs.services
 
 ---
 
+## Phase 4B: Deploy Train State <!-- Added: forge#1332 -->
+
+**Purpose**: Report the current state of the rolling staging→main deploy candidate (the "merge train"). One deploy PR should stay open per deploy cycle — this phase shows whether a candidate exists, what is holding it, and what is queued behind it.
+
+```bash
+git fetch origin {STAGING_BRANCH} {DEFAULT_BRANCH} 2>/dev/null
+
+# Step 1: Find the current open staging→main deploy PR (the "train")
+TRAIN_PR=$(gh pr list {GH_FLAG} \
+  --head "{STAGING_BRANCH}" \
+  --base "{DEFAULT_BRANCH}" \
+  --state open \
+  --json number,title,headRefOid,createdAt,reviewRequests \
+  --jq '.[0] // empty' 2>/dev/null)
+
+TRAIN_PR_NUMBER=$(echo "$TRAIN_PR" | jq -r '.number // empty')
+TRAIN_PR_SHA=$(echo "$TRAIN_PR" | jq -r '.headRefOid // empty' | cut -c1-7)
+TRAIN_PR_CREATED=$(echo "$TRAIN_PR" | jq -r '.createdAt // empty')
+
+if [ -z "$TRAIN_PR_NUMBER" ]; then
+  TRAIN_STATUS="NO_TRAIN — no open staging→main PR. Run /review-pr-staging to open one."
+else
+  # Step 2: Check whether the train is held (has blocking findings)
+  HELD_BY=$(gh issue list {GH_FLAG} \
+    --label "review-finding" \
+    --state open \
+    --search "PR #${TRAIN_PR_NUMBER}" \
+    --limit 20 \
+    --json number,title \
+    --jq '[.[] | "#\(.number): \(.title)"] | join("\n")' 2>/dev/null || true)
+
+  if [ -n "$HELD_BY" ]; then
+    TRAIN_STATUS="HELD"
+  else
+    TRAIN_STATUS="CLEAR — ready to merge"
+  fi
+
+  # Step 3: Count commits queued (commits in staging not yet in main)
+  QUEUED_COMMITS=$(git rev-list --count origin/{DEFAULT_BRANCH}..origin/{STAGING_BRANCH} 2>/dev/null || echo "?")
+fi
+```
+
+Train state is included in the Phase 5 output summary.
+
+---
+
 ## Phase 5: Output Summary
 
 ```
@@ -285,6 +334,14 @@ gh workflow run {deploy.workflow} --ref main -f {deploy.workflow_inputs.services
 
 **Commits**: {N} | **PRs**: {N} | **Issues closed**: {N} | **Files changed**: {N}
 
+### Deploy Train State
+**Train PR**: #{TRAIN_PR_NUMBER} (SHA: {TRAIN_PR_SHA}, opened: {TRAIN_PR_CREATED})
+**Status**: {TRAIN_STATUS}
+{If HELD: "**Held by**: {count} open finding(s) — fix and push to unblock:\n{HELD_BY}"}
+{If CLEAR: "**Ready to merge**: no open findings on the train PR"}
+{If NO_TRAIN: "No open staging→main PR — run /review-pr-staging to open one"}
+**Queued commits**: {QUEUED_COMMITS} (commits in staging not yet in main)
+
 ### Services Affected
 | Service | Files Changed | Rebuild Required |
 |---------|---------------|-----------------|