forgedock 1.0.16 → 1.0.17

package/commands/review-pr.md

@@ -3,6 +3,8 @@ description: Context-aware PR review — analyzes what the PR touches, spawns do
 argument-hint: [PR number, URL, "open", or "staging" for feature→main review]
 allowed-tools: Task, Bash, Read, Grep, Glob, WebFetch, Skill
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # PR Review — Orchestrator
 
@@ -124,6 +126,9 @@ while [ "$MERGE_HEALTH" = "UNKNOWN" ] && [ "$MERGE_RETRY" -lt 3 ]; do
 done
 # MERGE_HEALTH: MERGEABLE | CONFLICTING | UNKNOWN (still async after retries)
 # MERGE_HEALTH_STATE: CLEAN | DIRTY | BLOCKED | UNSTABLE | UNKNOWN
+
+# Resolve repo name early — used in Phases 5, 6, 8B, 9A (clean-review skip path bypasses Phase 6A) <!-- Added: forge#820 -->
+REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
 ```
 
 ### 1B: Classify
@@ -731,7 +736,6 @@ If synthesis needed, launch a `general-purpose` Task (model: resolved per policy
 ### 6A: Extract Findings
 
 ```bash
-REPO=$(gh repo view --json nameWithOwner --jq '.nameWithOwner')
 HAS_SYNTHESIS=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" --jq '.[].body' | grep -c 'REVIEW-FINDINGS-SYNTHESIZED-START' || echo 0)
 
 if [ "$HAS_SYNTHESIS" -gt 0 ]; then
@@ -786,8 +790,8 @@ fi
 
 if [ -n "$MILESTONE_BRANCH" ]; then
     BRANCH_SLUG=$(echo "$MILESTONE_BRANCH" | sed 's|^milestone/||')
-    MILESTONE_NUMBER=$(gh api repos/${REPO}/milestones --jq --arg slug "$BRANCH_SLUG" '.[] | select((.title | ascii_downcase | gsub("[^a-z0-9]+"; "-")) == $slug) | .number' 2>/dev/null | head -1)
-    [ -z "$MILESTONE_NUMBER" ] && MILESTONE_NUMBER=$(gh api repos/${REPO}/milestones --jq --arg slug "$BRANCH_SLUG" '.[] | select((.title | ascii_downcase | gsub("[^a-z0-9]+"; "-")) | test($slug)) | .number' 2>/dev/null | head -1)
+    MILESTONE_NUMBER=$(gh api repos/${REPO}/milestones 2>/dev/null | jq --arg slug "$BRANCH_SLUG" '.[] | select((.title | ascii_downcase | gsub("[^a-z0-9]+"; "-")) == $slug) | .number' 2>/dev/null | head -1)
+    [ -z "$MILESTONE_NUMBER" ] && MILESTONE_NUMBER=$(gh api repos/${REPO}/milestones 2>/dev/null | jq --arg slug "$BRANCH_SLUG" '.[] | select((.title | ascii_downcase | gsub("[^a-z0-9]+"; "-")) | test($slug)) | .number' 2>/dev/null | head -1)
     [ -n "$MILESTONE_NUMBER" ] && MILESTONE_FLAG="--milestone $(gh api repos/${REPO}/milestones/${MILESTONE_NUMBER} --jq '.title')"
 fi
 ```
@@ -1060,12 +1064,89 @@ fi
 
 **Important**: Phase 8 ONLY merges the PR. It does NOT close the issue, update labels, or clean up worktrees. When invoked via `/work-on`, those responsibilities belong to `work-on/close.md` — which runs after the router detects state 4 (MERGE_COMPLETE: PR merged + issue open). Doing them here would cause the router to hit TERMINAL_MERGED (state 1) and skip the close phase entirely.
 
+### 8B: Post-Merge Review Finding Demilestoning (Milestone PRs Only)
+
+**Skip if**: `IS_MILESTONE_TO_STAGING` is false or `MERGE_STATE != "MERGED"`. Runs only when a milestone→staging PR was just successfully merged.
+
+**Purpose**: Review-finding issues created during a milestone PR review (Phase 6C) inherit the milestone. Once the milestone PR merges, those findings should flow through the fast lane independently — not remain stranded on a closed milestone. This step clears their milestone assignment automatically.
+
+```bash
+if [ "${IS_MILESTONE_TO_STAGING:-false}" = "true" ] && [ "${MERGE_STATE:-}" = "MERGED" ]; then
+    echo "Phase 8B: Clearing milestone from open review-finding issues referencing PR #${PR_NUMBER}..."
+
+    # Find open review-finding issues whose body references this PR number
+    # The title template in Phase 6C always includes: "review finding — PR #${PR_NUMBER}"
+    FINDINGS_TO_DEMILESTONE=$(gh issue list -R "${REPO}" \
+        --state open \
+        --label "review-finding" \
+        --limit 200 \
+        --json number,title,milestone \
+        --jq ".[] | select(.milestone != null) | select(.title | test(\"PR #${PR_NUMBER}\")) | .number" \
+        2>/dev/null || echo "")
+
+    if [ -z "$FINDINGS_TO_DEMILESTONE" ]; then
+        echo "Phase 8B: No open review-finding issues with milestones found referencing PR #${PR_NUMBER}."
+    else
+        MOVED_COUNT=0
+        echo "$FINDINGS_TO_DEMILESTONE" | while IFS= read -r FINDING_NUM; do
+            [ -z "$FINDING_NUM" ] && continue
+            FINDING_TITLE=$(gh issue view "$FINDING_NUM" -R "${REPO}" --json title --jq '.title' 2>/dev/null || echo "#${FINDING_NUM}")
+            gh issue edit "$FINDING_NUM" -R "${REPO}" --milestone "" 2>/dev/null && \
+                echo "  Moved to fast lane: #${FINDING_NUM} — ${FINDING_TITLE}" || \
+                echo "  WARNING: Failed to clear milestone for #${FINDING_NUM}"
+            MOVED_COUNT=$((MOVED_COUNT + 1))
+        done
+        echo "Phase 8B: Review finding demilestoning complete."
+    fi
+fi
+```
+
+<!-- Added: forge#815 -->
+
 ---
 
 ## Phase 9: Integrity Check & Summary (LAST)
 
 **Run AFTER Phase 6 (issues created), Phase 7 (verdict posted), Phase 8 (merge if applicable).**
 
+### 9A: Post-Merge Review Finding Demilestoning Fallback (Milestone PRs Only)
+
+**Skip if**: `IS_MILESTONE_TO_STAGING` is false. Runs when `AUTO_MERGE=false` but the PR was merged manually — Phase 8B did not run in this case, so Phase 9 handles cleanup.
+
+**Detection**: Check if the PR is now MERGED. If so and `IS_MILESTONE_TO_STAGING=true`, run the same demilestoning logic as Phase 8B.
+
+```bash
+if [ "${IS_MILESTONE_TO_STAGING:-false}" = "true" ]; then
+    PR_MERGE_STATE=$(gh pr view $ARGUMENTS --json state --jq '.state' 2>/dev/null || echo "")
+    if [ "$PR_MERGE_STATE" = "MERGED" ]; then
+        echo "Phase 9A: Checking for open review-finding issues to demilestone (fallback — manual merge path)..."
+
+        FINDINGS_TO_DEMILESTONE=$(gh issue list -R "${REPO}" \
+            --state open \
+            --label "review-finding" \
+            --limit 200 \
+            --json number,title,milestone \
+            --jq ".[] | select(.milestone != null) | select(.title | test(\"PR #${PR_NUMBER}\")) | .number" \
+            2>/dev/null || echo "")
+
+        if [ -z "$FINDINGS_TO_DEMILESTONE" ]; then
+            echo "Phase 9A: No open review-finding issues with milestones found referencing PR #${PR_NUMBER} (already cleared or none created)."
+        else
+            echo "$FINDINGS_TO_DEMILESTONE" | while IFS= read -r FINDING_NUM; do
+                [ -z "$FINDING_NUM" ] && continue
+                FINDING_TITLE=$(gh issue view "$FINDING_NUM" -R "${REPO}" --json title --jq '.title' 2>/dev/null || echo "#${FINDING_NUM}")
+                gh issue edit "$FINDING_NUM" -R "${REPO}" --milestone "" 2>/dev/null && \
+                    echo "  Moved to fast lane: #${FINDING_NUM} — ${FINDING_TITLE}" || \
+                    echo "  WARNING: Failed to clear milestone for #${FINDING_NUM}"
+            done
+            echo "Phase 9A: Fallback demilestoning complete."
+        fi
+    fi
+fi
+```
+
+<!-- Added: forge#815 -->
+
 ```bash
 CURRENT_SHA=$(gh pr view $ARGUMENTS --json headRefOid --jq '.headRefOid')
 REVIEW_IS_STALE="false"
@@ -1118,4 +1199,5 @@ Review complete for PR #X. Verdict: [VERDICT].
 - Integration checks: [pass/N broken paths found]
 - Issues created: [M]
 {IF AUTO_MERGE: "PR merged and issue closed." / "Merge FAILED — see issue."}
+{IF IS_MILESTONE_TO_STAGING: "Review findings demilestoned: [N] issues moved to fast lane." / ""}
 ```

package/commands/rollback.md

@@ -2,6 +2,8 @@
 description: Create a revert PR to roll back a shipped feature or fix that caused a production incident
 argument-hint: [PR number to revert, or "last" for most recent deploy]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # /rollback — Automated Revert PR Creation
 

package/commands/scope.md

@@ -0,0 +1,280 @@
+---
+description: Estimate issue complexity before running /work-on — affected files, blast radius, risk flags, and decomposition recommendation
+argument-hint: <issue number> [--repo {owner}/{repo}]
+---
+
+# /scope — Pre-Flight Complexity Estimator
+
+**Input**: $ARGUMENTS
+
+You are a read-only pre-flight analyst. Given a GitHub issue number, you estimate how complex it is BEFORE the user commits to running `/work-on`. You surface affected files, blast radius, dependency risks, estimated pipeline phases, and a decomposition recommendation.
+
+**This command is strictly READ-ONLY.** No labels are written, no comments are posted, no worktrees are created.
+
+**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**NEVER use plan mode (EnterPlanMode).**
+
+---
+
+## Config Preamble
+
+Read `forge.yaml` before running any phase:
+
+```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"
+  REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
+else
+  echo "WARNING: forge.yaml not found."
+  echo "Run: npx forgedock init"
+  exit 1
+fi
+```
+
+Parse `$ARGUMENTS`:
+- `{NUMBER}` — issue number (required)
+- `--repo {owner}/{repo}` — override GH_REPO (optional; useful for satellite repos)
+
+If `--repo` is provided: set `GH_REPO` and `GH_FLAG` to the override value.
+
+---
+
+## Phase 1: Load Issue
+
+```bash
+gh issue view {NUMBER} {GH_FLAG} \
+  --json number,title,body,labels,milestone,state
+```
+
+If the issue is CLOSED: print `Issue #{NUMBER} is already closed — scope analysis may not be actionable.` and continue anyway (the user may be scoping a re-open or reference).
+
+Extract:
+- `TITLE` — issue title (strip conventional commit prefix: `fix:`, `feat:`, `refactor:`, `chore:`)
+- `BODY` — full body text
+- `LABELS` — label names (used for domain detection)
+- `MILESTONE` — milestone title if set (indicates feature lane)
+- `TASK_TYPE` — infer from title prefix: `fix:` → Bug Fix, `feat:` → Feature, `refactor:` → Refactor, `chore:` → Maintenance, other → Unknown
+
+---
+
+## Phase 2: Extract Keywords
+
+From `TITLE` and `BODY`, extract:
+1. **Explicit file references** — anything matching `*.py`, `*.ts`, `*.tsx`, `*.md`, `*.yml`, `*.yaml`, `*.json`, `*.sh`, `docker-compose*`, `Dockerfile*` — collect as `EXPLICIT_FILES`
+2. **Domain terms** — nouns and compound terms (e.g. function names, service names, component names, CLI command names) — collect as `DOMAIN_TERMS`
+3. **Affected section files** — lines under `## Affected Files` section in the body (if present)
+
+Merge `EXPLICIT_FILES` + `AFFECTED_SECTION_FILES` into `TARGET_FILES` (deduplicated).
+
+Limit `DOMAIN_TERMS` to the 10 most specific (skip generic words: "fix", "bug", "issue", "add", "the", "and", "for", "with", "use", "get", "set").
+
+---
+
+## Phase 3: Affected-File Discovery
+
+Search `REPO_PATH` for each keyword to find candidate files:
+
+```bash
+# For each file explicitly named in the issue
+for file in {TARGET_FILES}; do
+  find "$REPO_PATH" -name "$file" -not -path "*/.git/*" -not -path "*/node_modules/*" 2>/dev/null
+done
+
+# For each domain term: grep for references
+for term in {DOMAIN_TERMS}; do
+  grep -rl "$term" "$REPO_PATH" \
+    --include="*.py" --include="*.ts" --include="*.tsx" \
+    --include="*.md" --include="*.yml" --include="*.yaml" \
+    --include="*.json" --include="*.sh" \
+    --exclude-dir=".git" --exclude-dir="node_modules" \
+    --exclude-dir=".claude" 2>/dev/null | head -5
+done
+
+# Git log — files recently changed alongside the named files
+if [ -n "{TARGET_FILES}" ]; then
+  for file in {TARGET_FILES}; do
+    git -C "$REPO_PATH" log --oneline -20 -- "$file" \
+      --name-only --format="" 2>/dev/null | grep -v "^$" | sort -u | head -10
+  done
+fi
+```
+
+Collect all results into `CANDIDATE_FILES` (deduplicated, sorted, absolute paths stripped to relative).
+
+**Relevance filter**: Keep only files where the keyword match is in the file's primary logic — not in test fixtures, lock files, or generated output. Exclude: `*.lock`, `package-lock.json`, `yarn.lock`, `*.min.js`, `dist/`, `build/`, `.next/`, `__pycache__/`.
+
+Final list: `AFFECTED_FILES` — at most 25 files.
+
+---
+
+## Phase 4: Blast Radius
+
+From `AFFECTED_FILES`, compute:
+
+```bash
+# Count unique top-level directories
+DIRS=$(echo "{AFFECTED_FILES}" | xargs -I{} dirname {} | sort -u)
+DIR_COUNT=$(echo "$DIRS" | grep -c .)
+
+# Count unique service groups (second-level directories under known roots)
+# Adapt to project structure — common roots: services/, apps/, packages/, web/, commands/
+SERVICE_GROUPS=$(echo "{AFFECTED_FILES}" | sed 's|/[^/]*$||' | sort -u)
+SERVICE_COUNT=$(echo "$SERVICE_GROUPS" | grep -c .)
+
+# Classify affected modules
+MODULES=""
+echo "{AFFECTED_FILES}" | grep -q "^commands/" && MODULES="$MODULES pipeline-commands"
+echo "{AFFECTED_FILES}" | grep -q "^bin/" && MODULES="$MODULES installer"
+echo "{AFFECTED_FILES}" | grep -q "^\.github/" && MODULES="$MODULES CI/CD"
+echo "{AFFECTED_FILES}" | grep -q "^docs/" && MODULES="$MODULES docs"
+echo "{AFFECTED_FILES}" | grep -q "services/" && MODULES="$MODULES backend-services"
+echo "{AFFECTED_FILES}" | grep -q "web/" && MODULES="$MODULES frontend"
+echo "{AFFECTED_FILES}" | grep -q "infra/\|docker-compose" && MODULES="$MODULES infrastructure"
+echo "{AFFECTED_FILES}" | grep -q "migrations/" && MODULES="$MODULES database"
+```
+
+---
+
+## Phase 5: Risk Flag Detection
+
+Scan `AFFECTED_FILES` and the issue body for high-risk signals:
+
+```bash
+RISK_FLAGS=""
+
+# Auth risk
+(echo "{AFFECTED_FILES}" | grep -qiE "auth|login|session|token|jwt|oauth|permission|role" || \
+ echo "$BODY" | grep -qiE "auth|login|session|token|jwt|oauth|permission|role") && \
+  RISK_FLAGS="$RISK_FLAGS AUTH"
+
+# Billing risk
+(echo "{AFFECTED_FILES}" | grep -qiE "billing|payment|stripe|subscription|credit|invoice" || \
+ echo "$BODY" | grep -qiE "billing|payment|stripe|subscription|credit|invoice") && \
+  RISK_FLAGS="$RISK_FLAGS BILLING"
+
+# Database migration risk
+(echo "{AFFECTED_FILES}" | grep -qiE "migration|alembic|schema|model" || \
+ echo "$BODY" | grep -qiE "migration|schema change|db migration|database") && \
+  RISK_FLAGS="$RISK_FLAGS DB-MIGRATION"
+
+# API schema / contract risk
+(echo "{AFFECTED_FILES}" | grep -qiE "openapi|schema|serializer|types\.ts|api\.ts|client\.py" || \
+ echo "$BODY" | grep -qiE "api.contract|breaking.change|response.shape|openapi") && \
+  RISK_FLAGS="$RISK_FLAGS API-CONTRACT"
+
+# CI/CD risk
+(echo "{AFFECTED_FILES}" | grep -qiE "\.github/workflows|Dockerfile|docker-compose|deploy|infra/" || \
+ echo "$BODY" | grep -qiE "deploy|CI|CD|workflow|dockerfile|container") && \
+  RISK_FLAGS="$RISK_FLAGS CI-CD"
+
+# Pipeline-phase risk (for ForgeDock itself)
+echo "{AFFECTED_FILES}" | grep -qE "^commands/(work-on|review-pr|quality-gate|orchestrate)" && \
+  RISK_FLAGS="$RISK_FLAGS PIPELINE-CORE"
+
+# New env vars
+echo "$BODY" | grep -qiE "env var|environment variable|\.env|getenv|process\.env" && \
+  RISK_FLAGS="$RISK_FLAGS ENV-VARS"
+```
+
+---
+
+## Phase 6: Complexity Scoring
+
+Compute a complexity score from the signals collected:
+
+| Signal | Points |
+|--------|--------|
+| Each affected file | +1 |
+| Each unique directory | +2 |
+| AUTH risk flag | +5 |
+| BILLING risk flag | +5 |
+| DB-MIGRATION risk flag | +4 |
+| API-CONTRACT risk flag | +3 |
+| CI-CD risk flag | +3 |
+| PIPELINE-CORE risk flag | +4 |
+| ENV-VARS risk flag | +2 |
+| Milestone set (feature lane) | +3 |
+| 2+ task type signals in body | +3 |
+
+**Score bands**:
+| Score | Band | Typical pipeline time |
+|-------|------|-----------------------|
+| 0–10 | TRIVIAL | 5–15 min (1-file fix, 1–2 pipeline phases) |
+| 11–20 | SIMPLE | 20–40 min (2–5 files, all phases) |
+| 21–35 | MODERATE | 45–90 min (5–10 files, possible review findings) |
+| 36–55 | COMPLEX | 90–150 min (10+ files, multiple domains) |
+| 56+ | DECOMPOSE | 2h+ (multiple task types, 3+ service groups) |
+
+---
+
+## Phase 7: Decomposition Recommendation
+
+Apply the same signals `/work-on` uses to trigger decomposition. Recommend **decompose: YES** if 2+ of these signals match (at least 1 Strong):
+
+**Strong signals**:
+- [ ] 2+ distinct task types (Bug Fix + Feature, Refactor + Feature, etc.)
+- [ ] 3+ service groups affected
+- [ ] 6+ files across 3+ directories
+
+**Supporting signals**:
+- [ ] Phased requirements ("first do X, then Y, then Z")
+- [ ] Score band is DECOMPOSE (56+)
+- [ ] Both frontend and backend affected
+- [ ] DB migration + API contract change in same issue
+
+If decompose: YES — suggest 2–4 sub-issue titles based on the natural fault lines visible in the affected-file analysis.
+
+---
+
+## Phase 8: Output Scope Report
+
+Print a structured scope report. Do NOT post it as a GitHub comment — print to stdout only.
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  /scope — Issue #{NUMBER}: {TITLE}
+╠══════════════════════════════════════════════════════════════╣
+║  Task type : {TASK_TYPE}
+║  Lane      : {Fast lane (no milestone) | Feature lane — milestone: {MILESTONE}}
+║  Complexity: {SCORE} → {BAND}
+║  Est. time : {TYPICAL_PIPELINE_TIME}
+╠══════════════════════════════════════════════════════════════╣
+║  AFFECTED FILES ({COUNT})
+╠══════════════════════════════════════════════════════════════╣
+{list each file — one per line, relative to REPO_PATH}
+╠══════════════════════════════════════════════════════════════╣
+║  BLAST RADIUS
+║  Directories : {DIR_COUNT}
+║  Modules     : {MODULES}
+╠══════════════════════════════════════════════════════════════╣
+║  RISK FLAGS
+{if no flags: "  None detected"}
+{for each flag: "  ⚠  {FLAG} — {brief note on what to watch for}"}
+╠══════════════════════════════════════════════════════════════╣
+║  DECOMPOSITION
+║  Recommendation: {decompose: YES | decompose: NO}
+{if YES:
+"║  Signals met: {list matched signals}
+║  Suggested sub-issues:
+║    1. {sub-issue title}
+║    2. {sub-issue title}
+║  → Run /work-on {NUMBER} — it will auto-decompose based on investigation."
+}
+{if NO:
+"║  → Safe to run /work-on {NUMBER} directly."
+}
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Risk flag annotations:
+- AUTH — review auth middleware, permission checks, and session handling carefully
+- BILLING — get explicit sign-off before merging; test with real payment fixtures
+- DB-MIGRATION — verify migration is reversible and tested on a copy of prod data
+- API-CONTRACT — grep all consumers of the changed endpoint before shipping
+- CI-CD — test workflow changes in a fork or staging environment first
+- PIPELINE-CORE — changes to work-on/review-pr/quality-gate affect the entire AI dev loop; review-pr will run extra scrutiny
+- ENV-VARS — ensure new vars are added to .env.example and all required config locations

package/commands/security-audit.md

@@ -2,6 +2,8 @@
 description: Periodic security posture audit — runs a scripted 4-phase checklist against repo files (not diffs), creates GitHub issues for confirmed findings
 argument-hint: [--repo <prefix>] [--phase 1|2|3|4|all] [--dry-run]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # /security-audit — Periodic Security Posture Audit