forgedock 1.0.16 → 1.0.17

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,41 @@ 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 |
+
+**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:

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

package/commands/resume.md

@@ -0,0 +1,264 @@
+---
+description: Recover full pipeline context after compaction — find the last active issue, reconstruct FORGE annotations, and resume work
+argument-hint: [issue number (optional — auto-detects if omitted)]
+---
+
+# /resume — Context Recovery After Compaction
+
+**Input**: $ARGUMENTS
+
+You are the context-recovery agent. When a session ends or context is compressed, all working state is lost. Your job is to restore it instantly — find the most recently active issue, read all FORGE annotations, reconstruct the current pipeline phase, and re-enter the pipeline exactly where it left off.
+
+**Agent model policy**: Default `model: "sonnet"`. Fallback: `model: "opus"` if Sonnet is rate-limited.
+**NEVER use plan mode (EnterPlanMode).**
+
+---
+
+## Phase 0: Config Resolution
+
+Read `forge.yaml` to configure all project-specific variables before running any commands:
+
+```bash
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
+GH_REPO=$(yq '.project.owner + "/" + .project.repo' "$CONFIG_FILE")
+GH_FLAG="-R $GH_REPO"
+REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
+STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
+```
+
+If `forge.yaml` is missing: stop and tell the user to run `npx forgedock init` to generate it.
+
+---
+
+## Phase 1: Find Active Issue
+
+### 1A: Parse input
+
+Check `$ARGUMENTS`:
+
+- **Explicit issue number** (e.g., `610`, `#610`): strip `#`, set `TARGET_NUMBER={number}`, skip to Phase 2.
+- **Empty**: proceed with auto-detection below.
+
+### 1B: Query for in-progress issues
+
+The `gh issue list --label` flag uses AND filtering when multiple labels are given. To find issues with ANY active workflow label, run one query per label and merge results:
+
+```bash
+# Find open issues with any active workflow label, sorted by most recently updated
+# (gh --label uses AND, so query each label separately and merge)
+ACTIVE_ISSUES=$(
+  for LABEL in "workflow:investigating" "workflow:ready-to-build" "workflow:building" "workflow:in-review"; do
+    gh issue list {GH_FLAG} \
+      --state open \
+      --label "$LABEL" \
+      --limit 10 \
+      --json number,title,labels,updatedAt
+  done | jq -s '
+    flatten |
+    unique_by(.number) |
+    sort_by(.updatedAt) | reverse |
+    .[] | {
+      number,
+      title,
+      phase: (.labels | map(.name | select(startswith("workflow:"))) | first // "unknown"),
+      updatedAt
+    }
+  ')
+echo "$ACTIVE_ISSUES"
+```
+
+### 1C: Select issue
+
+**If one result**: use it — set `TARGET_NUMBER={number}`.
+
+**If multiple results**: display a ranked list (most recently updated first), then select the top entry:
+
+```
+## Active Issues Found (most recent first)
+
+| # | Issue | Phase | Last Updated |
+|---|-------|-------|--------------|
+| 1 | #{number}: {title} | {phase} | {updatedAt} |
+| 2 | #{number}: {title} | {phase} | {updatedAt} |
+...
+
+Auto-selecting #1 (most recently updated). Pass an explicit issue number to override.
+```
+
+Set `TARGET_NUMBER` to the top-ranked issue number.
+
+### 1D: Fallback — no active label found
+
+If `ACTIVE_ISSUES` is empty, search recent issues by FORGE annotation presence:
+
+```bash
+# Look for recently updated open issues with FORGE annotations (pipeline may have stalled pre-label)
+RECENT_ISSUES=$(gh issue list {GH_FLAG} \
+  --state open \
+  --limit 20 \
+  --json number,title,updatedAt \
+  --jq 'sort_by(.updatedAt) | reverse | .[0:5] | .[] | {number, title, updatedAt}')
+
+# For each candidate, check if it has FORGE annotations
+for NUMBER in $(echo "$RECENT_ISSUES" | jq -r '.number'); do
+  HAS_FORGE=$(gh api repos/{GH_REPO}/issues/$NUMBER/comments \
+    --jq '[.[] | select(.body | test("<!-- FORGE:"))] | length > 0' 2>/dev/null || echo "false")
+  if [ "$HAS_FORGE" = "true" ]; then
+    TARGET_NUMBER=$NUMBER
+    break
+  fi
+done
+```
+
+If still no candidate: display `No recent active issues found. To resume work on a specific issue, run: /resume {issue-number}` and STOP.
+
+---
+
+## Phase 2: Reconstruct Context
+
+### 2A: Load issue state
+
+```bash
+ISSUE=$(gh issue view {TARGET_NUMBER} {GH_FLAG} \
+  --json number,title,body,labels,state,milestone,updatedAt)
+
+ISSUE_TITLE=$(echo "$ISSUE" | jq -r '.title')
+ISSUE_STATE=$(echo "$ISSUE" | jq -r '.state')
+ISSUE_LABELS=$(echo "$ISSUE" | jq -r '[.labels[].name] | join(", ")')
+ISSUE_MILESTONE=$(echo "$ISSUE" | jq -r '.milestone.title // "none"')
+
+echo "Issue: #${TARGET_NUMBER} — $ISSUE_TITLE"
+echo "State: $ISSUE_STATE | Labels: $ISSUE_LABELS | Milestone: $ISSUE_MILESTONE"
+```
+
+If issue is CLOSED and has `workflow:merged` or `workflow:invalid` label: display completion status and STOP — no work remaining.
+
+### 2B: Read all FORGE annotations
+
+Fetch all comments and extract the FORGE-annotated ones in pipeline order:
+
+```bash
+COMMENTS=$(gh api repos/{GH_REPO}/issues/{TARGET_NUMBER}/comments \
+  --jq '.[] | select(.body | test("<!-- FORGE:")) | {
+    id: .id,
+    created_at: .created_at,
+    type: (.body | capture("<!-- FORGE:(?<t>[A-Z_:]+)") | .t),
+    body: .body
+  }')
+```
+
+Extract specific annotations:
+
+```bash
+# Investigation report
+FORGE_INVESTIGATOR=$(gh api repos/{GH_REPO}/issues/{TARGET_NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body' 2>/dev/null || echo "")
+
+# Builder contract
+FORGE_CONTRACT=$(gh api repos/{GH_REPO}/issues/{TARGET_NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:CONTRACT")) | .body' 2>/dev/null || echo "")
+
+# Implementation context
+FORGE_CONTEXT=$(gh api repos/{GH_REPO}/issues/{TARGET_NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:CONTEXT")) | .body' 2>/dev/null || echo "")
+
+# Architecture plan
+FORGE_ARCHITECT=$(gh api repos/{GH_REPO}/issues/{TARGET_NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:ARCHITECT")) | .body' 2>/dev/null || echo "")
+
+# Builder implementation report
+FORGE_BUILDER=$(gh api repos/{GH_REPO}/issues/{TARGET_NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:BUILDER")) | .body' 2>/dev/null || echo "")
+```
+
+### 2C: Determine current pipeline phase
+
+Read labels and annotation presence to identify where the pipeline was interrupted:
+
+```bash
+# Extract active workflow label
+WORKFLOW_LABEL=$(echo "$ISSUE_LABELS" | grep -oP 'workflow:[a-z:-]+' | grep -v 'workflow:merged\|workflow:invalid\|workflow:decomposed' | head -1)
+
+# Check annotation completion markers
+HAS_INVESTIGATION=$([ -n "$FORGE_INVESTIGATOR" ] && echo "$FORGE_INVESTIGATOR" | grep -q "INVESTIGATION:COMPLETE" && echo "YES" || echo "NO")
+HAS_CONTRACT=$([ -n "$FORGE_CONTRACT" ] && echo "YES" || echo "NO")
+HAS_CONTEXT=$([ -n "$FORGE_CONTEXT" ] && echo "YES" || echo "NO")
+HAS_ARCHITECT=$([ -n "$FORGE_ARCHITECT" ] && echo "YES" || echo "NO")
+HAS_BUILDER=$([ -n "$FORGE_BUILDER" ] && echo "$FORGE_BUILDER" | grep -q "FORGE:BUILDER:COMPLETE" && echo "YES" || echo "NO")
+
+# Check for open PR on this issue's branch
+OPEN_PR=$(gh pr list {GH_FLAG} --state open --search "#{TARGET_NUMBER}" --limit 1 --json number,headRefName --jq '.[0]' 2>/dev/null || echo "")
+```
+
+Map to current phase:
+
+| Condition | Current Phase | Resume Action |
+|-----------|---------------|---------------|
+| `HAS_INVESTIGATION=NO` | Phase 1: Investigating | Reinvestigate |
+| `HAS_INVESTIGATION=YES`, `WORKFLOW_LABEL=workflow:ready-to-build` | Phase 3: Build | Enter build from 3A |
+| `HAS_INVESTIGATION=YES`, `HAS_BUILDER=NO`, `WORKFLOW_LABEL=workflow:building` | Phase 3: Build in progress | Enter build from 3A (will skip completed sub-phases) |
+| `HAS_BUILDER=YES`, PR not found | Phase 4: PR Creation | Push branch + create PR |
+| `OPEN_PR` found, `WORKFLOW_LABEL=workflow:in-review` | Phase 5: Auto-Review | Invoke review-pr |
+| PR merged, issue still open | Phase 6: Close | Close issue, update board |
+
+### 2D: Display context summary
+
+Emit a structured context block before resuming — this is what anchors the agent's working memory:
+
+```
+## Context Recovered — Issue #${TARGET_NUMBER}
+
+**Title**: {ISSUE_TITLE}
+**Lane**: {fast-lane | feature-lane (milestone: {MILESTONE})}
+**Current Phase**: {CURRENT_PHASE}
+**Active Label**: {WORKFLOW_LABEL}
+
+### Investigation Summary
+{if HAS_INVESTIGATION=YES: extract "### What We Found" + "### Root Cause" + "### Affected Files" blocks from FORGE_INVESTIGATOR}
+{if HAS_INVESTIGATION=NO: "Not yet investigated."}
+
+### Contract
+{if HAS_CONTRACT=YES: extract "### Proposed Approach" + "### Deliverables" table from FORGE_CONTRACT}
+{if HAS_CONTRACT=NO: "Contract not yet written."}
+
+### Architecture Plan
+{if HAS_ARCHITECT=YES: extract "### Affected Paths" table + "### Implementation Order" from FORGE_ARCHITECT}
+{if HAS_ARCHITECT=NO: "Architecture plan not yet written."}
+
+### Build Status
+{if HAS_BUILDER=YES: extract "### Changes" + "### Acceptance Criteria Status" from FORGE_BUILDER}
+{if HAS_BUILDER=NO: "Implementation not yet started."}
+
+### Open PR
+{if OPEN_PR: "PR #{pr_number} → {headRefName} (open)"}
+{if not OPEN_PR: "No PR yet."}
+
+### Resume Entry Point
+→ Will invoke /work-on {TARGET_NUMBER} — pipeline re-enters at {CURRENT_PHASE}
+```
+
+---
+
+## Phase 3: Resume
+
+Invoke `/work-on` to re-enter the pipeline. Work-on reads GitHub state independently and routes to the correct phase automatically.
+
+```
+Skill("work-on", args="{TARGET_NUMBER}")
+```
+
+**Why delegation works**: `/work-on` Phase 0B already implements "Determine resume point" — it reads issue labels and FORGE annotations to route to the correct phase. `/resume` provides the human-readable context summary, then hands off to `/work-on` for execution.
+
+**Do NOT re-implement pipeline logic here.** The context summary above is for the agent's working memory only — the actual phase routing and execution is owned by `/work-on`.
+
+---
+
+## Error Handling
+
+| Condition | Response |
+|-----------|----------|
+| `forge.yaml` missing | Stop: "Run \`npx forgedock init\` to generate forge.yaml" |
+| No active issues + no FORGE annotations found | Stop: "No recent active issues found. Run \`/resume {number}\` with an explicit issue number, or \`/work-on next\` to start a new issue." |
+| Issue is closed with `workflow:merged` | Stop: "Issue #{number} is already merged. Nothing to resume." |
+| Issue is closed with `workflow:invalid` | Stop: "Issue #{number} was closed as invalid. Nothing to resume." |
+| Issue has `needs-human` label | Stop: "Issue #{number} is blocked (needs-human). Review the blocking comment and resolve it manually before resuming." |

package/commands/review-pr-agents.md

@@ -1,3 +1,6 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
 # Agent Catalog for `/review-pr`
 
 This file is the Agent Catalog referenced by the `/review-pr` orchestrator. It is read via the `Read` tool during Phase 3C (agent dispatch). It contains:
@@ -1171,9 +1174,10 @@ If no API context is configured above, derive conventions from the changed files
     BASE=$(gh pr view [PR_NUMBER] --json baseRefName --jq '.baseRefName')
 
     # Find PRs merged to this base in the last 48 hours
+    CUTOFF="$(date -u -d '48 hours ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v-48H +%Y-%m-%dT%H:%M:%SZ)"
     RECENT_MERGED=$(gh pr list --base "$BASE" --state merged --limit 20 \
       --json number,title,mergedAt,files \
-      --jq --arg cutoff "$(date -u -d '48 hours ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v-48H +%Y-%m-%dT%H:%M:%SZ)" \
+      2>/dev/null | jq --arg cutoff "$CUTOFF" \
       '.[] | select(.mergedAt > $cutoff) | {number, title, schema_files: [.files[].path | select(test("schemas?/|scrape\\.py|models\\.py"))]}' \
       2>/dev/null | head -40)
 

package/commands/review-pr-staging.md

@@ -3,6 +3,8 @@ description: Staging review mode — comprehensive review of staging branch befo
 argument-hint: [PR number or "staging"]
 allowed-tools: Task, Bash, Read, Grep, Glob, WebFetch
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # Staging Review