forgedock 1.0.16 → 1.0.18

package/commands/pipeline-health.md

@@ -2,6 +2,8 @@
 description: Self-analysis — measures pipeline performance, correlates with prompt changes, proposes improvements
 argument-hint: [project repo slug or "all"]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # /pipeline-health — Forge Self-Analysis
 
@@ -541,6 +543,57 @@ fi
 
 **Why this matters**: Outcome metrics (findings per PR, fix-up rate) measure what the pipeline produces. Orchestration efficiency measures how much wasted motion occurs getting there. An agent that takes 40 minutes to do 8 minutes of actual work has 80% idle time — all of which is pipeline overhead. Reducing stall time directly improves throughput without changing code quality. This is the only metric that reveals whether the routing loop in `work-on.md` is functioning or causing agents to stop and wait.
 
+**Step 4 — Batch stall rate (from FORGE:STALL_DETECTED annotations)**:
+
+Query issues that received a `<!-- FORGE:STALL_DETECTED -->` comment within the analysis window. This measures how often the orchestrator's time-based stall detector fired — distinct from the resume-cycle count (which comes from completion-event stalls).
+
+```bash
+# Denominator: issues that entered the pipeline in the window (have any workflow:* label)
+# Using pipeline-active issues avoids inflating the denominator with all 500 issues in window
+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" \
+  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]" \
+  2>/dev/null || echo "[]")
+
+# Count issues with at least one FORGE:STALL_DETECTED comment
+# Use wc -l pattern (not variable accumulation) to avoid bash subshell scope loss
+STALL_COUNT=$(echo "$PIPELINE_ISSUE_NUMS" | jq -r '.[]' | while read -r NUM; do
+  STALL_COMMENTS=$(gh api repos/$GH_REPO/issues/${NUM}/comments \
+    --jq '[.[] | select(.body | contains("FORGE:STALL_DETECTED"))] | length' 2>/dev/null || echo 0)
+  [ "$STALL_COMMENTS" -gt 0 ] && echo "$NUM"
+done | wc -l)
+
+# Count issues that escalated (2+ stall comments = auto-resume exhausted)
+ESCALATED_COUNT=$(echo "$PIPELINE_ISSUE_NUMS" | jq -r '.[]' | while read -r NUM; do
+  STALL_COMMENTS=$(gh api repos/$GH_REPO/issues/${NUM}/comments \
+    --jq '[.[] | select(.body | contains("FORGE:STALL_DETECTED"))] | length' 2>/dev/null || echo 0)
+  [ "$STALL_COMMENTS" -ge 2 ] && echo "$NUM"
+done | wc -l)
+
+# Compute batch stall rate
+if [ "$BATCH_TOTAL" -gt 0 ]; then
+  BATCH_STALL_RATE=$(echo "scale=1; $STALL_COUNT * 100 / $BATCH_TOTAL" | bc 2>/dev/null || echo "N/A")
+  echo "Batch stall rate: ${BATCH_STALL_RATE}% (${STALL_COUNT}/${BATCH_TOTAL} pipeline issues stalled) — target: < 10%"
+  echo "Escalated to needs-human: ${ESCALATED_COUNT} issues"
+else
+  BATCH_STALL_RATE="N/A"
+  echo "Batch stall rate: N/A (no pipeline issues in window or FORGE:STALL_DETECTED not yet deployed)"
+fi
+export BATCH_STALL_RATE STALL_COUNT BATCH_TOTAL ESCALATED_COUNT
+```
+
+**Target**: `BATCH_STALL_RATE` < 10% (stalled issues / total issues in window). A rate above 10% indicates systemic pipeline unreliability — agents stopping without reaching terminal state frequently enough to require orchestrator intervention.
+
+**Note**: `BATCH_STALL_RATE` requires `FORGE:STALL_DETECTED` comments, which are written by the stall detector in `/orchestrate` Step 4B.5. If the stall detector is not deployed, this metric returns N/A and falls back to the resume-cycle proxy from Step 3.
+
 ### 2L: Post-deploy failure metrics (pipeline escape signal)
 
 `/audit` creates `audit-finding` labeled issues in the Forge repo whenever a defect escapes the pipeline and reaches staging or production. Each finding is tagged with a `**Failure point**:` field indicating which pipeline phase failed (INVESTIGATION, IMPLEMENTATION, REVIEW, REVIEW_FALSE_NEG, DEPLOY_GATE, etc.). Aggregating these reveals the post-deploy defect rate and review escape rate — signals invisible to the pre-merge metrics above.
@@ -2100,6 +2153,8 @@ gh issue create -R $FORGE_REPO \
 | — Avg agent idle% | ?% | < 30% | ✅/⚠️/❌ |
 | — Avg resume cycles per agent | ? | < 1 | ✅/⚠️/❌ |
 | — Clean agent rate | ?% | > 60% | ✅/⚠️/❌ |
+| — Batch stall rate | ?% (?/? issues) | < 10% | ✅/⚠️/❌ |
+| — Escalated to needs-human | ? issues | 0 | ✅/⚠️/❌ |
 | Original work ratio | ?% | > 70% | ✅/⚠️/❌ |
 | Milestone merge success | ?% | 80%+ | ✅/⚠️/❌ |
 | Issue close velocity | ? days | < 2 days | ✅/⚠️/❌ |
@@ -2123,13 +2178,15 @@ _If no trajectory data available in window: "No FORGE:TRAJECTORY comments found
 
 ## Orchestration Efficiency
 
-_From Phase 2K — persisted FORGE:AUDIT-AGENTS summaries ([N] sessions, [M] agents total)_
+_From Phase 2K — persisted FORGE:AUDIT-AGENTS summaries ([N] sessions, [M] agents total) + FORGE:STALL_DETECTED annotations_
 
 | Metric | Value | Target | Status |
 |--------|-------|--------|--------|
 | Avg agent idle% | ?% | < 30% | ✅/⚠️/❌ |
 | Avg resume cycles per agent | ? | < 1 | ✅/⚠️/❌ |
 | Clean agent rate | ?% | > 60% | ✅/⚠️/❌ |
+| Batch stall rate | ?% (?/? issues) | < 10% | ✅/⚠️/❌ |
+| Escalated to needs-human | ? issues | 0 | ✅/⚠️/❌ |
 
 **Top stall boundaries** (phase transitions causing the most stalls):
 | Boundary | Occurrences |
@@ -2140,6 +2197,8 @@ _From Phase 2K — persisted FORGE:AUDIT-AGENTS summaries ([N] sessions, [M] age
 
 _If no FORGE:AUDIT-AGENTS data available: "No persisted audit-agents summaries found in window. Run \`audit-agents --persist\` after orchestration runs to enable this metric. Proxy: [N] issues had resume/stall anomalies in trajectory data."_
 
+_Batch stall rate: sourced from \`FORGE:STALL_DETECTED\` comments (requires \`/orchestrate\` Step 4B.5 to be active). N/A if stall detector is not deployed._
+
 ## Transcript Flow Metrics
 
 _From Phase 2N — JSONL transcript analytics ([N] pipeline sessions, [M] subagent sessions in window)_

package/commands/qa-sweep.md

@@ -2,6 +2,8 @@
 description: Full platform QA sweep — auto-discovers every page, tests every UI element via browser automation, creates GitHub issues for all findings
 argument-hint: [all | dashboard | marketing | page <route> | journey | visual | functional | a11y]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # /qa-sweep — Platform-Wide QA Testing
 
@@ -14,9 +16,26 @@ You are the QA orchestrator. Auto-discover every page across the platform (dashb
 
 ---
 
+## Playwright MCP Prerequisite (MANDATORY — check before proceeding)
+
+Playwright MCP is a **guaranteed ForgeDock dependency** for all browser automation commands. Before running any qa-sweep phase, verify it is available:
+
+**Check**: Confirm `mcp__playwright__*` tools are available in your tool context (e.g., `mcp__playwright__browser_navigate`, `mcp__playwright__browser_snapshot`).
+
+**If Playwright MCP tools are NOT available**: STOP immediately. Do not attempt to run qa-sweep — all browser automation steps will fail silently.
+
+**Fix**:
+1. Register Playwright MCP: `claude mcp add playwright npx @playwright/mcp@latest`
+2. Restart Claude Code to reload MCP servers
+3. Verify with: `npx forgedock doctor` (Check 9 confirms registration)
+
+See README.md Requirements section for full setup instructions.
+
+---
+
 ## Browser Tool Reference
 
-All browser automation uses Playwright MCP tools (`mcp__playwright__*`).
+All browser automation uses Playwright MCP tools (`mcp__playwright__*`). Playwright MCP is a guaranteed ForgeDock dependency — see the Playwright MCP Prerequisite section above.
 
 | Action | Tool | Key param |
 |--------|------|-----------|
@@ -95,7 +114,25 @@ Depth-first, workflow-driven:
 
 ## Phase 0: Setup & Auth
 
-**Load config from forge.yaml** before running any checks:
+**Playwright MCP prerequisite guard** — run BEFORE loading forge.yaml config:
+
+Confirm `mcp__playwright__browser_navigate` (or any `mcp__playwright__*` tool) is available in your tool context. If Playwright MCP tools are absent:
+
+```
+STOP. Playwright MCP is not registered in this Claude Code session.
+
+Register it with:  claude mcp add playwright npx @playwright/mcp@latest
+Then restart Claude Code and run /qa-sweep again.
+
+Verify installation with: npx forgedock doctor (Check 9 confirms Playwright MCP status)
+See: README.md Requirements section for full setup instructions.
+```
+
+Do not proceed past this guard if Playwright MCP tools are unavailable — all browser automation steps will fail silently without clear error messages.
+
+---
+
+**Load config from forge.yaml** after confirming Playwright MCP is available:
 
 ```bash
 QA_CONFIG=$(python3 - <<'PYEOF'

package/commands/quality-gate.md

@@ -2,6 +2,8 @@
 description: Pre-commit quality check — catches defects the review would flag, so the builder can fix them before committing
 argument-hint: (invoked by /work-on, not directly)
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # /quality-gate — Pre-Commit Quality Check
 
@@ -15,6 +17,42 @@ You do NOT post to GitHub. You do NOT create issues. You return findings directl
 
 ---
 
+## Adaptive Design
+
+This quality gate uses **domain detection** to adapt to your project's actual tech stack. Checks are not one-size-fits-all — they are selectively triggered based on the file types and patterns present in each change.
+
+**How it works**:
+1. Changed files are classified into domains (AUTH, DEPLOY, DATABASE, FRONTEND, etc.) by pattern-matching against file paths, extensions, and diff content
+2. Only checks for detected domains are executed — irrelevant checks are skipped entirely
+3. A project that only changes markdown files runs zero domain checks; a project that changes only TypeScript components runs only SECURITY, FRONTEND, and PROXY checks
+
+**Universal check** (always runs for any code file):
+- **SECURITY** — SQL injection, SSRF, path traversal, hardcoded secrets, XSS, command injection
+
+**Conditional checks** (triggered only when relevant patterns are detected):
+
+| Domain | Triggered when |
+|--------|----------------|
+| AUTH | Files matching `*router*` or `route.ts` handlers |
+| DEPLOY | Files referencing `os.getenv` or `process.env` |
+| DATABASE | `.sql` files or files under `migrations/` |
+| FRONTEND | `.tsx`/`.ts` files in client component paths |
+| PROXY | Client components using `fetch`/`useSWR`/`apiFetch` |
+| SHELL | `.sh` files or scripts using `curl`/`wget` |
+| STRING_SETS | Python files in anti-detection or browser automation paths |
+| CONCURRENCY | Python files using `asyncio.shield`, `asyncio.wait_for`, or `Task.cancel` |
+| STATE | Python files with new module-level mutable variable assignments |
+| CAPACITY | Worker/infra Python files with new size/limit/threshold constants |
+| WORKFLOW | `.yml` files in `.github/workflows/` |
+| IMPORT_RESOLUTION | Python files with new `from app.*` imports added outside `try:` blocks |
+| INFRA | Dockerfiles or entrypoints with runtime UID changes |
+| ROUTER_BUG | Router Python files where gate conditions are narrowed |
+| FORGE_GRAPH | `commands/*.md` specs or `scripts/*` files change (ForgeDock self-consistency) |
+
+**Stack-agnostic coverage**: The example domains above reflect common patterns caught in production; they are not requirements. A Go or Ruby project benefits from SECURITY checks. A Node.js project benefits from FRONTEND, PROXY, and DEPLOY checks. Any project benefits from DATABASE and WORKFLOW checks when those file types are present. The stack-specific examples (Python routers, SOPS secrets chain, FastAPI layouts, appleboy SSH deploys) are illustrative — the domain detection system applies the applicable subset to any codebase.
+
+---
+
 ## Input Format
 
 The builder passes:
@@ -61,6 +99,7 @@ Before running checks, classify the changed files into domains. This avoids runn
 | `*.py` with new `from app.` import statements added outside `try:` blocks | IMPORT_RESOLUTION |
 | `Dockerfile*` or `entrypoint*.sh` with added/changed `USER`, `su-exec`, `gosu`, or `setuid` | INFRA |
 | `*.py` in `routers/` where the diff removes a line containing an or-gate condition (lines starting with `-` containing `if.*or`) | ROUTER_BUG |
+| `commands/*.md` or `scripts/*` files (ForgeDock repo only — dogfoods its own spec graph) | FORGE_GRAPH |
 
 **Apply the classification:**
 
@@ -88,6 +127,9 @@ for f in {CHANGED_FILES}; do
             echo "$f" | grep -qE '\.py$' && DOMAINS="$DOMAINS STRING_SETS"
             ;;
     esac
+    case "$f" in
+        commands/*.md|scripts/*) DOMAINS="$DOMAINS FORGE_GRAPH" ;;
+    esac
     case "$f" in
         .github/workflows/*.yml) DOMAINS="$DOMAINS WORKFLOW" ;;
     esac
@@ -375,6 +417,31 @@ done
 
 Report any hit as **HIGH** — the DB connection will fail in any environment where PostgreSQL is not on `127.0.0.1:5432`.
 
+### 2G.6: Spec graph self-consistency (FORGE_GRAPH domain)
+
+**Triggered when**: changed files include `commands/*.md` specs or `scripts/*` files (ForgeDock repo only — it dogfoods its own Spec Knowledge Graph). Skips silently in any project without `scripts/validate-spec-graph.sh`.
+
+**Why this matters**: ForgeDock's pipeline behavior is encoded in a ~1.2 MB prose spec corpus where drift is invisible — a `FORGE:*` annotation written but never read, a `Skill(skill="X")` referencing a sub-phase that no longer exists, or a `workflow:*` label set by no command. The Spec Knowledge Graph (`build-spec-graph.mjs`) makes this queryable; `validate-spec-graph.sh` consumes it and partitions findings into HARD (dangling cross-refs, broken label transitions) and SOFT (orphan annotations).
+
+```bash
+# Run only when commands/*.md or scripts/* changed and the validator ships in this repo.
+VALIDATOR="$FORGEDOCK_SCRIPTS/validate-spec-graph.sh"
+[ -f "$VALIDATOR" ] || VALIDATOR="{WORKTREE_PATH}/scripts/validate-spec-graph.sh"
+if [ -f "$VALIDATOR" ]; then
+    # The graph is auto-built from the worktree (gitignored JSON not required).
+    # --soft keeps the gate non-blocking on the documented baseline orphans;
+    # HARD findings are still reported below and surfaced as gate findings.
+    GRAPH_REPORT=$(bash "$VALIDATOR" --root "{WORKTREE_PATH}" --soft 2>&1 || true)
+    echo "$GRAPH_REPORT"
+    # Map any HARD finding to a quality-gate finding (dangling ref / broken transition).
+    echo "$GRAPH_REPORT" | grep -E '^\s*\[HARD\]' | while IFS= read -r hit; do
+        echo "FORGE_GRAPH | HIGH | spec-graph | ${hit#*] }"
+    done
+fi
+```
+
+Report each `[HARD]` line as **HIGH** — a dangling `Skill()` target or a label set by no command is a real pipeline break (an agent will invoke a phase that does not exist, or a state will never be entered/exited). Orphan-annotation `[SOFT]` lines are advisory: surface them in the report for periodic triage but do NOT block the commit. Scaffolding `[INFO]` lines are expected and need no action. To gate on HARD findings (fail the build), drop `--soft`; the default keeps existing baseline orphans from blocking until they are triaged. <!-- Added: forge#869 -->
+
 ### 2H: Asyncio cancellation safety (Python async code)
 
 **Triggered when**: changed Python files contain `asyncio.shield`, `asyncio.wait_for`, or `Task.cancel`.

package/commands/replay.md

@@ -0,0 +1,263 @@
+---
+description: Read-only playback of a completed pipeline run — shows FORGE annotations phase by phase with timestamps
+argument-hint: <issue-number>
+---
+
+# /replay — Pipeline Run Playback
+
+**Input**: $ARGUMENTS (issue number)
+
+Replay a completed pipeline run. Fetches all FORGE annotations posted during the pipeline and displays them chronologically — phase headings, timestamps, and key structured fields. Read-only: nothing is written, no labels changed.
+
+**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+
+---
+
+## Config Preamble
+
+```bash
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
+if [ -f "$CONFIG_FILE" ]; then
+  GH_OWNER=$(yq '.project.owner' "$CONFIG_FILE")
+  GH_REPO_NAME=$(yq '.project.repo' "$CONFIG_FILE")
+  GH_REPO="${GH_OWNER}/${GH_REPO_NAME}"
+  GH_FLAG="-R $GH_REPO"
+else
+  echo "ERROR: forge.yaml not found."
+  echo "Run: npx forgedock init"
+  exit 1
+fi
+```
+
+---
+
+## Step 1: Parse Input
+
+```bash
+NUMBER=$(echo "$ARGUMENTS" | grep -oP '^\s*#?\K\d+' | head -1)
+if [ -z "$NUMBER" ]; then
+  echo "Usage: /replay <issue-number>"
+  echo "Example: /replay 42"
+  exit 1
+fi
+echo "Replaying pipeline run for issue #${NUMBER}..."
+```
+
+---
+
+## Step 2: Fetch Issue Metadata
+
+```bash
+ISSUE_JSON=$(gh issue view "$NUMBER" "$GH_FLAG" \
+  --json number,title,state,labels,createdAt,closedAt 2>/dev/null)
+
+if [ -z "$ISSUE_JSON" ] || echo "$ISSUE_JSON" | grep -q '"message"'; then
+  echo "ERROR: Issue #${NUMBER} not found in ${GH_REPO}."
+  exit 1
+fi
+
+ISSUE_TITLE=$(echo "$ISSUE_JSON" | jq -r '.title')
+ISSUE_STATE=$(echo "$ISSUE_JSON" | jq -r '.state')
+ISSUE_CREATED=$(echo "$ISSUE_JSON" | jq -r '.createdAt')
+ISSUE_CLOSED=$(echo "$ISSUE_JSON" | jq -r '.closedAt // "open"')
+WORKFLOW_LABELS=$(echo "$ISSUE_JSON" | jq -r '[.labels[].name | select(startswith("workflow:"))] | join(", ")')
+
+echo ""
+echo "══════════════════════════════════════════════════════════════"
+echo "  Pipeline Replay — #${NUMBER}: ${ISSUE_TITLE}"
+echo "══════════════════════════════════════════════════════════════"
+echo "  State   : ${ISSUE_STATE}"
+echo "  Opened  : ${ISSUE_CREATED}"
+[ "$ISSUE_CLOSED" != "open" ] && echo "  Closed  : ${ISSUE_CLOSED}"
+[ -n "$WORKFLOW_LABELS" ] && echo "  Labels  : ${WORKFLOW_LABELS}"
+echo "══════════════════════════════════════════════════════════════"
+```
+
+---
+
+## Step 3: Fetch All Comments
+
+```bash
+# One API call — returns all comments in chronological order
+ALL_COMMENTS=$(gh api "repos/${GH_REPO}/issues/${NUMBER}/comments" 2>/dev/null)
+
+if [ -z "$ALL_COMMENTS" ] || [ "$ALL_COMMENTS" = "[]" ]; then
+  echo ""
+  echo "  No comments on this issue. No pipeline run to replay."
+  exit 0
+fi
+```
+
+---
+
+## Step 4: Identify FORGE Annotations
+
+```bash
+# Filter to comments that contain a FORGE pipeline annotation
+FORGE_COMMENTS=$(echo "$ALL_COMMENTS" | jq -c '[.[] | select(.body | test("<!-- FORGE:(INVESTIGATOR|CONTRACT|CONTEXT|ARCHITECT|BUILDER|DECOMPOSED|TRAJECTORY)"))]')
+FORGE_COUNT=$(echo "$FORGE_COMMENTS" | jq 'length')
+
+if [ "$FORGE_COUNT" -eq 0 ]; then
+  echo ""
+  echo "  No FORGE pipeline annotations found on issue #${NUMBER}."
+  echo "  This issue was not processed by the /work-on pipeline,"
+  echo "  or comments were posted before pipeline annotation was introduced."
+  exit 0
+fi
+
+echo ""
+echo "  Found ${FORGE_COUNT} pipeline annotation(s). Playing back..."
+echo ""
+```
+
+---
+
+## Step 5: Display Each Annotation
+
+Phase mapping (inline): `INVESTIGATOR`→Phase 1, `CONTRACT`→Phase 3C, `CONTEXT`→Phase 3C.5, `ARCHITECT`→Phase 3C.6, `BUILDER`→Phase 3M, `DECOMPOSED`→Phase 2, `TRAJECTORY`→Phase 7.
+
+For each FORGE comment in chronological order, print a formatted block. Use Python for robust multiline extraction from the comment body.
+
+```bash
+echo "$FORGE_COMMENTS" | jq -c '.[]' | while IFS= read -r COMMENT; do
+  BODY=$(echo "$COMMENT" | jq -r '.body')
+  CREATED=$(echo "$COMMENT" | jq -r '.created_at')
+  AUTHOR=$(echo "$COMMENT" | jq -r '.user.login')
+
+  # Identify annotation type
+  ANNOTATION=$(echo "$BODY" | grep -oP '(?<=<!-- )FORGE:[A-Z:]+(?= -->| -->)' | head -1)
+
+  # Map to phase label
+  case "$ANNOTATION" in
+    "FORGE:INVESTIGATOR") PHASE_LABEL="Phase 1 — Investigation" ;;
+    "FORGE:CONTRACT")     PHASE_LABEL="Phase 3C — Builder Contract" ;;
+    "FORGE:CONTEXT")      PHASE_LABEL="Phase 3C.5 — Context Gathering" ;;
+    "FORGE:ARCHITECT")    PHASE_LABEL="Phase 3C.6 — Architecture Plan" ;;
+    "FORGE:BUILDER")      PHASE_LABEL="Phase 3M — Implementation" ;;
+    "FORGE:DECOMPOSED")   PHASE_LABEL="Phase 2 — Decomposition" ;;
+    "FORGE:TRAJECTORY")   PHASE_LABEL="Phase 7 — Pipeline Trajectory" ;;
+    *)                    PHASE_LABEL="$ANNOTATION" ;;
+  esac
+
+  # Format timestamp: 2025-01-15T14:32:00Z → 2025-01-15 14:32 UTC
+  TIMESTAMP=$(echo "$CREATED" | sed 's/T/ /; s/:[0-9][0-9]Z/ UTC/')
+
+  echo "┌─────────────────────────────────────────────────────────────"
+  echo "│  ${PHASE_LABEL}"
+  echo "│  ${TIMESTAMP}  ·  @${AUTHOR}"
+  echo "├─────────────────────────────────────────────────────────────"
+
+  # Extract key fields per annotation type
+  ANNOTATION="$ANNOTATION" BODY_CONTENT="$BODY" python3 - <<'PYEOF'
+import re, sys, os
+
+body = os.environ.get('BODY_CONTENT', '')
+
+def extract(pattern, default="—"):
+    m = re.search(pattern, body, re.MULTILINE | re.DOTALL)
+    return m.group(1).strip() if m else default
+
+def count_lines(header):
+    m = re.search(r'### ' + header + r'\n(.*?)(?=\n###|\Z)', body, re.DOTALL)
+    if not m: return 0
+    return len([l for l in m.group(1).strip().splitlines() if l.strip()])
+
+annotation = os.environ.get('ANNOTATION', '')
+
+if annotation == "FORGE:INVESTIGATOR":
+    verdict    = extract(r'\*\*Verdict\*\*:\s*(\S+)')
+    confidence = extract(r'\*\*Confidence\*\*:\s*(\S+)')
+    severity   = extract(r'\*\*Severity\*\*:\s*(\S+)')
+    task_type  = extract(r'\*\*Task Type\*\*:\s*([^\n]+)')
+    root_cause = extract(r'### Root Cause\n([^\n]+)')
+    decompose  = extract(r'\*\*(YES|NO)\*\* —', '—')
+    print(f"│  Verdict    : {verdict} ({confidence} confidence)")
+    print(f"│  Severity   : {severity}  |  Task type: {task_type}")
+    print(f"│  Root cause : {root_cause[:80]}")
+    print(f"│  Decompose  : {decompose}")
+
+elif annotation == "FORGE:CONTRACT":
+    task_type  = extract(r'\*\*Task type\*\*:\s*([^\n]+)')
+    approach   = extract(r'### Proposed Approach\n([^\n]+)')
+    n_files    = len(re.findall(r'^\|[^|]+\|[^|]+\|[^|]+\|', body, re.MULTILINE)) - 2  # subtract header+sep
+    n_criteria = len(re.findall(r'^- \[', body, re.MULTILINE))
+    print(f"│  Task type  : {task_type}")
+    print(f"│  Approach   : {approach[:80]}")
+    print(f"│  Deliverables: {max(0,n_files)} file(s)  |  Criteria: {n_criteria}")
+
+elif annotation == "FORGE:CONTEXT":
+    pitfalls = extract(r'### Known Pitfalls[^\n]*\n([^\n]+)')
+    print(f"│  Pitfalls   : {pitfalls[:80]}")
+    print(f"│  (Context gathered — see full comment for details)")
+
+elif annotation == "FORGE:ARCHITECT":
+    n_paths = len(re.findall(r'^\| \d+', body, re.MULTILINE))
+    order_m = re.search(r'### Implementation Order\n(.*?)(?=\n###|\Z)', body, re.DOTALL)
+    n_steps = len([l for l in (order_m.group(1).strip().splitlines() if order_m else []) if re.match(r'^\d+\.', l.strip())])
+    print(f"│  Paths      : {n_paths} affected path(s)")
+    print(f"│  Order      : {n_steps} implementation step(s)")
+    print(f"│  (Full plan in comment)")
+
+elif annotation == "FORGE:BUILDER":
+    branch   = extract(r'\*\*Branch\*\*:\s*`([^`]+)`')
+    commits  = extract(r'\*\*Commits\*\*:\s*([^\n]+)')
+    n_files  = extract(r'\*\*Files changed\*\*:\s*(\d+)')
+    approach = extract(r'### Approach\n([^\n]+)')
+    print(f"│  Branch     : {branch}")
+    print(f"│  Commits    : {commits}")
+    print(f"│  Files      : {n_files}")
+    print(f"│  Approach   : {approach[:80]}")
+
+elif annotation == "FORGE:DECOMPOSED":
+    subs_m = re.search(r'### Sub-Issues Created\n(.*?)(?=\n###|\Z)', body, re.DOTALL)
+    subs = [l.strip() for l in (subs_m.group(1).strip().splitlines() if subs_m else []) if l.strip().startswith('-')]
+    print(f"│  Sub-issues : {len(subs)}")
+    for s in subs[:5]:
+        print(f"│    {s}")
+
+elif annotation == "FORGE:TRAJECTORY":
+    # Print the phase table lines verbatim (they're already formatted)
+    in_table = False
+    count = 0
+    for line in body.splitlines():
+        if '| Phase' in line or (in_table and line.startswith('|')):
+            in_table = True
+            print(f"│  {line}")
+            count += 1
+        elif in_table and not line.startswith('|'):
+            break
+    if count == 0:
+        print("│  (Trajectory table not found in comment)")
+    decisions = extract(r'\*\*Decisions\*\*:\s*([^\n]+)')
+    anomalies = extract(r'\*\*Anomalies\*\*:\s*([^\n]+)')
+    print(f"│  Decisions  : {decisions[:80]}")
+    print(f"│  Anomalies  : {anomalies[:80]}")
+
+else:
+    # Unknown annotation — print first non-empty, non-marker line
+    for line in body.splitlines():
+        stripped = line.strip()
+        if stripped and not stripped.startswith('<!--') and not stripped.startswith('#'):
+            print(f"│  {stripped[:100]}")
+            break
+PYEOF
+
+  echo "└─────────────────────────────────────────────────────────────"
+  echo ""
+done
+```
+
+---
+
+## Step 7: Summary Footer
+
+```bash
+echo "══════════════════════════════════════════════════════════════"
+echo "  Replay complete — ${FORGE_COUNT} pipeline phase(s) shown"
+echo "  Issue: https://github.com/${GH_REPO}/issues/${NUMBER}"
+echo "══════════════════════════════════════════════════════════════"
+```
+
+---
+
+**Constraints**: Read-only — never writes to GitHub, never posts comments, never edits labels. Partial pipeline runs are shown as-is (missing phases are absent, not errors).