forgedock 1.0.5 → 1.0.7

package/commands/milestone.md

@@ -25,14 +25,23 @@ GH_FLAG="-R $GH_REPO"
 REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
 PROJECT_NAME=$(yq '.project.name' "$CONFIG_FILE")
 STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
+DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE")
 PROJECT_BOARD_OWNER=$(yq '.project_board.owner // .project.owner' "$CONFIG_FILE")
-PROJECT_NUMBER=$(yq '.project_board.project_number // "1"' "$CONFIG_FILE")
-PROJECT_ID=$(yq '.project_board.project_id' "$CONFIG_FILE")
+PROJECT_NUMBER=$(yq '.project_board.project_number // empty' "$CONFIG_FILE" 2>/dev/null || echo "")
+PROJECT_ID=$(yq '.project_board.project_id // empty' "$CONFIG_FILE" 2>/dev/null || echo "")
+# Project board field and option IDs — empty string when project_board section is absent
+STATUS_FIELD_ID=$(yq '.project_board.field_ids.status // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+LANE_FIELD_ID=$(yq '.project_board.field_ids.lane // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+COMPONENT_FIELD_ID=$(yq '.project_board.field_ids.component // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+PRIORITY_FIELD_ID=$(yq '.project_board.field_ids.priority // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+STATUS_TODO_OPTION_ID=$(yq '.project_board.option_ids.status.todo // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+LANE_FEATURE_OPTION_ID=$(yq '.project_board.option_ids.lane.feature // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+PRIORITY_OPTION_ID=""  # Resolved per-issue from the issue's priority label — see Step 6B
 # Build satellite repo map from repos.satellites list
 # Each satellite: { prefix, repo, staging_branch }
 ```
 
-All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{PROJECT_NAME}`, `{STAGING_BRANCH}`, `{PROJECT_BOARD_OWNER}`, `{PROJECT_NUMBER}`, and `{PROJECT_ID}` references below are populated from `forge.yaml`.
+All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{PROJECT_NAME}`, `{STAGING_BRANCH}`, `{DEFAULT_BRANCH}`, `{PROJECT_BOARD_OWNER}`, `{PROJECT_NUMBER}`, `{PROJECT_ID}`, `{STATUS_FIELD_ID}`, `{LANE_FIELD_ID}`, `{COMPONENT_FIELD_ID}`, `{PRIORITY_FIELD_ID}`, `{STATUS_TODO_OPTION_ID}`, and `{LANE_FEATURE_OPTION_ID}` references below are populated from `forge.yaml`.
 
 ---
 
@@ -101,40 +110,45 @@ Capture the milestone number from the response.
 
 ```bash
 cd {REPO_PATH}
-git fetch origin main
-git branch milestone/{slug} origin/main
+git fetch origin $DEFAULT_BRANCH
+git branch milestone/{slug} origin/$DEFAULT_BRANCH
 git push origin milestone/{slug}
 ```
 
 ### Step 4: Scope decomposition
 
-Use a Task sub-agent to analyze the milestone scope and propose issues:
-
-> You are planning the scope for milestone "{TITLE}" on the {PROJECT_NAME} platform.
->
-> **Milestone description**: {DESCRIPTION}
->
-> **Your job**: Break this milestone into concrete, implementable GitHub issues. Each issue should be:
-> - Independently shippable (produces a working PR on its own)
-> - Specific enough for the `/work-on` pipeline to pick up and implement
-> - Ordered by dependencies (if B needs A's API, A comes first)
->
-> **Project ecosystem context** (from `forge.yaml`):
-> - **Primary repo** (`{GH_REPO}`): The main project codebase at `{REPO_PATH}`
-> - **Tech stack**: {review.tech_stack from forge.yaml, or read CLAUDE.md for project context}
-> - **Satellite repos**: Read from `forge.yaml → repos.satellites` (each has a prefix and repo)
->
-> Check the existing codebase at `{REPO_PATH}` to understand current architecture before proposing changes.
->
-> **Output format**: Numbered list of proposed issues, each with:
-> - **Title**: Actionable, specific
-> - **Repo**: Which repo this issue belongs to (default or satellite prefix from forge.yaml)
-> - **Type**: `feature`, `bug`, `refactor`, `infra`
-> - **Priority**: P1-P3
-> - **Size**: S (1-2 files), M (3-5 files), L (6+ files)
-> - **Dependencies**: Which other issues must be done first (by number)
-> - **Scope**: Key files/modules affected
-> - **Acceptance criteria**: 2-3 testable requirements
+**Investigation-gated decomposition** — do NOT skip code reads. The single-pass shallow-planning approach (one agent, whole milestone, no per-issue code reads) produces under-specified issues that ship incomplete. This step mandates per-proposed-issue investigation before any issue body is written. See `work-on/decompose.md` Phase D0 for the reference pattern that enforces this gate. <!-- Added: forge#293 -->
+
+**4A: First pass — enumerate proposed issues (no code reads yet)**
+
+Analyze the milestone description and produce a preliminary list of proposed issues. At this stage, only the title, type, and rough dependency order are needed. Do NOT write issue bodies yet.
+
+**4B: Per-issue investigation (MANDATORY before writing any issue body)**
+
+For each proposed issue in the preliminary list, MUST read the actual code before writing the issue body:
+
+1. **Identify affected files**: Read the files the issue will touch. Start with the files named in the milestone description, then expand to callers and related modules.
+2. **Enumerate all call sites**: For coverage/refactor tasks, grep for every occurrence of the pattern being changed. Do NOT estimate — enumerate. Example: `grep -rn 'poetry run\|npx ' commands/ --include='*.md' | wc -l` to count call sites before writing a "make X config-driven" issue.
+3. **Write exhaustive acceptance criteria**: For coverage/refactor tasks, acceptance criteria MUST be falsifiable. A `grep`/absence assertion qualifies (e.g., `` `grep -rn 'hardcoded_value' commands/` returns no matches ``). The number of criteria must match the scope — there is no cap. Two criteria for a 14-call-site refactor is not acceptable.
+4. **Identify override/companion files**: If a file needs a change, its companion files (config overrides, prod variants, sibling modules) almost certainly do too. List all of them.
+
+**4C: Output format — per-issue, after code read**
+
+For each proposed issue, after completing the per-issue investigation in Step 4B:
+
+- **Title**: Actionable, specific (conventional commit prefix: `fix:`, `feat:`, `refactor:`)
+- **Repo**: Which repo this issue belongs to (default or satellite prefix from forge.yaml)
+- **Type**: `feature`, `bug`, `refactor`, `infra`
+- **Priority**: P1-P3
+- **Size**: S (1-2 files), M (3-5 files), L (6+ files)
+- **Dependencies**: Which other issues must be done first (by number)
+- **Affected files**: Full list of files enumerated during the Step 4B code read (not estimated)
+- **Acceptance criteria**: Exhaustive and falsifiable. For coverage/refactor tasks: one criterion per affected call site or pattern, written as a grep/absence assertion. No cap on criteria count — the list must be complete enough that a reviewer can verify coverage without reading the implementation.
+
+**Project ecosystem context** (from `forge.yaml`):
+- **Primary repo** (`{GH_REPO}`): The main project codebase at `{REPO_PATH}`
+- **Tech stack**: {review.tech_stack from forge.yaml, or read CLAUDE.md for project context}
+- **Satellite repos**: Read from `forge.yaml → repos.satellites` (each has a prefix and repo)
 
 ### Step 5: Review with user
 
@@ -144,10 +158,14 @@ Present the proposed issues to the user. Ask:
 
 ### Step 6: Create issues and assign to milestone
 
+**Issue body standard**: Use the **Pipeline Issue Template** from `issue.md` Phase 3D as the body structure for every issue created here. Do NOT use a bespoke inline template — the Pipeline Issue Template is the single canonical standard for all automated issue creation across the pipeline. The body content (Problem, Root Cause, Affected Files, Acceptance Criteria, Context, Dependencies) comes from the per-issue investigation in Step 4B. <!-- Added: forge#293 -->
+
 For each approved issue, create it in the **correct repo** based on the scope analysis:
 
 ```bash
 # For default repo issues:
+# Body content derives from the Step 4B per-issue investigation.
+# Structure MUST match the Pipeline Issue Template in issue.md Phase 3D.
 gh issue create {GH_FLAG} \
   --title "{fix|feat|refactor}: {issue_title}" \
   --label "{type},{priority}" \
@@ -155,20 +173,21 @@ gh issue create {GH_FLAG} \
   --body "$(cat <<'BODY_EOF'
 ## Problem
 
-{1-3 sentences: what needs to be built or fixed for this milestone. What's missing or broken.}
+{1-3 sentences: what needs to be built or fixed for this milestone. Specific — derived from Step 4B code read, not milestone description alone.}
 
 ## Root Cause (if known)
 
-{Why this needs to change — architecture gap, missing feature, technical debt. If a new feature: "New capability required for {MILESTONE_TITLE}."}
+{Why this needs to change — architecture gap, missing feature, technical debt. Reference specific file:line where possible. If a new feature: "New capability required for {MILESTONE_TITLE}."}
 
 ## Affected Files
 
-Files that need changes:
+Files that need changes (full list from Step 4B code read — ordered by dependency):
 1. `{filepath}` — {what needs to change}
 2. `{filepath}` — {what needs to change}
 
 ## Acceptance Criteria
 
+{Exhaustive and falsifiable. For coverage/refactor tasks: one criterion per affected call site or pattern, written as a grep/absence assertion. No cap — list must be complete.}
 - [ ] {Specific, testable criterion}
 - [ ] {Specific, testable criterion}
 - [ ] No regression in {related feature}
@@ -186,6 +205,7 @@ BODY_EOF
 
 # For satellite repo issues (MCP, n8n) — create in the satellite repo:
 # Note: GitHub milestones are per-repo, so satellite issues reference the milestone by name only
+# Body structure MUST match the Pipeline Issue Template in issue.md Phase 3D.
 gh issue create -R {SATELLITE_REPO} \
   --title "{fix|feat|refactor}: {issue_title}" \
   --label "{type},{priority}" \
@@ -196,16 +216,17 @@ gh issue create -R {SATELLITE_REPO} \
 
 ## Root Cause (if known)
 
-{Why this needs to change. If a new feature: "New capability required for {MILESTONE_TITLE}."}
+{Why this needs to change. Reference specific file:line where possible. If a new feature: "New capability required for {MILESTONE_TITLE}."}
 
 ## Affected Files
 
-Files that need changes:
+Files that need changes (full list from Step 4B code read):
 1. `{filepath}` — {what needs to change}
 2. `{filepath}` — {what needs to change}
 
 ## Acceptance Criteria
 
+{Exhaustive and falsifiable. No cap — coverage/refactor tasks require one criterion per affected call site.}
 - [ ] {Specific, testable criterion}
 - [ ] {Specific, testable criterion}
 
@@ -223,19 +244,47 @@ BODY_EOF
 
 ### Step 6B: Add issues to Project board
 
-For each created issue, add it to the GitHub Project board with initial fields. Reference `forge.yaml → project_board` for field IDs, or `docs/CONFIG.md` → "Project Board" for lookup commands.
+**Skip if `project_board` is not configured** — check resolved vars before proceeding:
 
 ```bash
-for ISSUE_NUM in {created_issue_numbers}; do
-  ISSUE_URL="https://github.com/{GH_REPO}/issues/${ISSUE_NUM}"
-  ITEM_ID=$(gh project item-add {PROJECT_NUMBER} --owner {PROJECT_BOARD_OWNER} --url "$ISSUE_URL" --format json --jq '.id' 2>/dev/null)
-  if [ -n "$ITEM_ID" ]; then
-    gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {PROJECT_BOARD_STATUS_FIELD_ID} --single-select-option-id {PROJECT_BOARD_STATUS_TODO_ID} 2>/dev/null || true  # Status=Todo
-    gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {PROJECT_BOARD_LANE_FIELD_ID} --single-select-option-id {PROJECT_BOARD_LANE_FEATURE_ID} 2>/dev/null || true  # Lane=Feature
-    gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {PROJECT_BOARD_COMPONENT_FIELD_ID} --single-select-option-id {COMPONENT_OPTION_ID} 2>/dev/null || true  # Component (from forge.yaml → project_board.field_ids)
-    gh project item-edit --project-id {PROJECT_ID} --id "$ITEM_ID" --field-id {PROJECT_BOARD_PRIORITY_FIELD_ID} --single-select-option-id {PRIORITY_OPTION_ID} 2>/dev/null || true  # Priority (from label)
-  fi
-done
+if [ -z "$PROJECT_BOARD_OWNER" ] || [ -z "$PROJECT_ID" ] || [ -z "$PROJECT_NUMBER" ]; then
+  echo "INFO: project_board not configured in forge.yaml — skipping board sync for created issues"
+else
+  # Resolve component option ID for this repo from forge.yaml → project_board.components
+  COMPONENT_OPTION_ID=$(yq '.project_board.components[] | select(.repo == "'"$GH_REPO"'") | .option_id' "$CONFIG_FILE" 2>/dev/null || echo "")
+
+  for ISSUE_NUM in {created_issue_numbers}; do
+    ISSUE_URL="https://github.com/$GH_REPO/issues/${ISSUE_NUM}"
+    ITEM_ID=$(gh project item-add "$PROJECT_NUMBER" --owner "$PROJECT_BOARD_OWNER" --url "$ISSUE_URL" --format json --jq '.id' 2>/dev/null)
+    if [ -n "$ITEM_ID" ]; then
+      # Resolve priority option ID from the issue's priority label
+      ISSUE_PRIORITY=$(gh issue view "$ISSUE_NUM" "$GH_FLAG" --json labels \
+        --jq '[.labels[].name | select(startswith("priority:"))] | .[0] | ltrimstr("priority:") | ascii_downcase' 2>/dev/null || echo "")
+      # Validate ISSUE_PRIORITY matches expected pattern before use as yq key path <!-- Added: forge#300 -->
+      PRIORITY_OPTION_ID=""
+      if [[ "$ISSUE_PRIORITY" =~ ^p[0-3]$ ]]; then
+        PRIORITY_OPTION_ID=$(yq '.project_board.option_ids.priority.'"$ISSUE_PRIORITY"' // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+      fi
+
+      if [ -n "$STATUS_FIELD_ID" ] && [ -n "$STATUS_TODO_OPTION_ID" ]; then
+        gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" \
+          --field-id "$STATUS_FIELD_ID" --single-select-option-id "$STATUS_TODO_OPTION_ID" 2>/dev/null || true  # Status=Todo
+      fi
+      if [ -n "$LANE_FIELD_ID" ] && [ -n "$LANE_FEATURE_OPTION_ID" ]; then
+        gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" \
+          --field-id "$LANE_FIELD_ID" --single-select-option-id "$LANE_FEATURE_OPTION_ID" 2>/dev/null || true  # Lane=Feature
+      fi
+      if [ -n "$COMPONENT_FIELD_ID" ] && [ -n "$COMPONENT_OPTION_ID" ]; then
+        gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" \
+          --field-id "$COMPONENT_FIELD_ID" --single-select-option-id "$COMPONENT_OPTION_ID" 2>/dev/null || true  # Component (from forge.yaml → project_board.components)
+      fi
+      if [ -n "$PRIORITY_FIELD_ID" ] && [ -n "$PRIORITY_OPTION_ID" ]; then
+        gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" \
+          --field-id "$PRIORITY_FIELD_ID" --single-select-option-id "$PRIORITY_OPTION_ID" 2>/dev/null || true  # Priority (from issue label)
+      fi
+    fi
+  done
+fi
 ```
 
 ### Step 7: Report

package/commands/orchestrate.md

@@ -1,6 +1,6 @@
 ---
 description: Orchestrate parallel work on multiple issues or an entire milestone — spawns sub-agents that each run the full /work-on pipeline
-argument-hint: [milestone <slug> | #1 #2 #3 | next <N> | fast-lane | P0]
+argument-hint: [milestone <slug> | #1 #2 #3 | next <N> | fast-lane | priority:P0]
 ---
 
 # /orchestrate — Multi-Issue Parallel Orchestrator
@@ -37,11 +37,12 @@ GH_FLAG="-R $GH_REPO"
 REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
 PROJECT_NAME=$(yq '.project.name' "$CONFIG_FILE")
 STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
+DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE")
 # Build satellite repo map from repos.satellites list
 # Each satellite: { prefix, repo, staging_branch }
 ```
 
-All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{PROJECT_NAME}`, and `{STAGING_BRANCH}` references below are populated from `forge.yaml`.
+All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{PROJECT_NAME}`, `{STAGING_BRANCH}`, and `{DEFAULT_BRANCH}` references below are populated from `forge.yaml`.
 
 ---
 
@@ -70,10 +71,10 @@ Parse `$ARGUMENTS` to determine which issues to work on:
 |-------|------------|
 | `milestone <slug>` | All open issues assigned to that GitHub milestone (default repo) |
 | `#1 #2 #3` or `1 2 3` | Specific issue numbers, optionally repo-prefixed (e.g., `#123 mcp:5 n8n:12`) |
-| `next <N>` | Top N priority open issues (P0 first, then P1, etc.) |
+| `next <N>` | Top N priority open issues (priority:P0 first, then priority:P1, etc.) |
 | `next <N> all-repos` | Top N across ALL ecosystem repos |
 | `fast-lane` or `fast` | All open fast-lane issues (no milestone, bugs/fixes) |
-| `P0` or `P1` | All open issues with that priority label |
+| `priority:P0` or `priority:P1` | All open issues with that priority label |
 | `mcp:fast` or `n8n:next 3` | Repo-scoped queries |
 | `<slug>` (no keyword) | Try milestone first, then fall back to label search |
 
@@ -230,6 +231,8 @@ Add the newly created issues to the issue set. Re-check each one:
 - Tag them as `IMPLEMENTATION` (investigations don't spawn more investigations)
 - They inherit the milestone from their parent investigation if applicable
 
+**Issue body standard**: Any new issues created by investigation agents MUST use the **Pipeline Issue Template** from `issue.md` Phase 3D as their body structure. Investigation agents that produce issues as output should be prompted to use that template — not ad-hoc body formats — so every spawned issue enters the pipeline with the correct structure (Problem, Root Cause, Affected Files, Acceptance Criteria). Verify spawned issues have all mandatory sections before adding them to the batch; if sections are missing, the `/issue` body-validation step (Phase 4C.5) will repair them. <!-- Added: forge#293 -->
+
 **Updated issue set** = original `IMPLEMENTATION` issues + newly spawned issues from investigations.
 
 ### Step 2E: Report Wave 0 results to user
@@ -275,18 +278,19 @@ For each issue, estimate which domains it touches based on title, body, and labe
 for NUM in {issue_numbers}; do
   ISSUE=$(gh issue view $NUM --json title,body,labels --jq '{title: .title, labels: [.labels[].name], body: (.body[:300])}')
   echo "=== #$NUM ==="
-  echo "$ISSUE" | grep -qiE "credit|billing|pricing|stripe|tier.*cost|charge|refund" && echo "  BILLING" || true
+  echo "$ISSUE" | grep -qiE "credit|billing|pricing|stripe|charge|refund" && echo "  BILLING" || true
   echo "$ISSUE" | grep -qiE "auth|session|jwt|login|permission|oauth" && echo "  AUTH" || true
-  echo "$ISSUE" | grep -qiE "scrape|tier|proxy|playwright|playbook|worker|unified_consumer|penetrat" && echo "  SCRAPING" || true
+  echo "$ISSUE" | grep -qiE "worker|queue|job|task|background|consumer" && echo "  WORKER" || true
   echo "$ISSUE" | grep -qiE "migration|\.sql|database|postgres|alembic" && echo "  DATABASE" || true
   echo "$ISSUE" | grep -qiE "component|page|layout|dashboard|ui|ux|frontend|web/src" && echo "  FRONTEND" || true
   echo "$ISSUE" | grep -qiE "docker|deploy|traefik|nginx|ci|cd|infra|github.action" && echo "  INFRA" || true
-  echo "$ISSUE" | grep -qiE "cortex|llm|extract|schema|format" && echo "  CORTEX" || true
+  echo "$ISSUE" | grep -qiE "llm|extract|schema|format|embedding|model" && echo "  AI" || true
+  # For project-specific domains, configure keywords in forge.yaml → review.domains and extend above
 done
 ```
 
 **Use domain info for wave planning:**
-- Issues in the SAME domain (especially SCRAPING, BILLING, DATABASE) are more likely to touch the same files → prefer sequential within a wave or adjacent waves
+- Issues in the SAME domain (especially WORKER, BILLING, DATABASE) are more likely to touch the same files → prefer sequential within a wave or adjacent waves
 - Issues in DIFFERENT domains are more likely independent → safe to parallelize
 - BILLING + AUTH issues should be prioritized early (security-critical)
 - **DATABASE issues are ALWAYS serialized — hard rule, no exceptions.** Multiple agents writing migrations simultaneously will produce duplicate migration numbers (e.g., two `0067_*.sql` files), which breaks the migration runner. Every DATABASE issue must be in its own wave. If 3 DATABASE issues are in a batch: Wave 1 runs issue A, Wave 2 runs issue B, Wave 3 runs issue C.
@@ -363,11 +367,17 @@ When two issues modify different files that **import from the same utility/init
 
 **Apply inferences:**
 ```
-# High-fan-in files — if ANY issue touches these, serialize it with all same-service issues:
+# High-fan-in files — if ANY issue touches these, serialize it with all same-service issues.
+# Read layout paths from forge.yaml review.layout; fall back to sensible generic defaults.
+# Example (pseudo-code — adapt to your forge.yaml parsing method):
+#   API_MAIN    = forge_yaml.review.layout.api_main    ?? "services/api/app/main.py"
+#   WORKER_MAIN = forge_yaml.review.layout.worker_main ?? "services/worker/worker/main.py"
+#   PAGES_ROOT  = forge_yaml.review.layout.pages       ?? "web/src/app"
+
 HIGH_FAN_IN = [
-  "services/api/app/main.py",
-  "services/worker/worker/unified_consumer.py",
-  "web/src/app/layout.tsx",
+  API_MAIN,                          # e.g. "services/api/app/main.py" — router/middleware registration
+  WORKER_MAIN,                       # e.g. "services/worker/worker/main.py" — worker entrypoint (set forge.yaml review.layout.worker_main)
+  PAGES_ROOT + "/layout.tsx",        # e.g. "web/src/app/layout.tsx" — root layout for all pages
   "docker-compose.yml",
   "docker-compose.prod.yml",
   ".env.example"
@@ -403,7 +413,7 @@ Build the final conflict graph by merging signals from all four layers:
 | Layer 4: Low confidence + same domain | **Conservative** | Serialize |
 | Layer 4: Low confidence + no domain | **Conservative** | Serialize with prior wave |
 
-**This supplements, not replaces, the domain keyword estimation.** Domain tags still help with broad sequencing decisions. Multi-layer conflict detection catches the specific cases keywords miss (e.g., two issues that both modify files in `services/api/app/models/` where one is labeled SCRAPING and the other BILLING — Layer 2 catches this even though Layer 1 shows no direct file overlap).
+**This supplements, not replaces, the domain keyword estimation.** Domain tags still help with broad sequencing decisions. Multi-layer conflict detection catches the specific cases keywords miss (e.g., two issues that both modify files in `services/api/app/models/` where one is labeled WORKER and the other BILLING — Layer 2 catches this even though Layer 1 shows no direct file overlap).
 
 ### Step 3D: Build the execution plan
 
@@ -445,15 +455,15 @@ Wave 2 (after deps): #2634 (enable daemon — after #2633 fixes memory leak), #2
 ### Domain Distribution
 | Domain | Issues | Notes |
 |--------|--------|-------|
-| SCRAPING | {N} | {High overlap risk / Independent targets} |
 | FRONTEND | {N} | {Independent pages / Shared components} |
 | BILLING | {N} | {Critical — prioritize in Wave 1} |
 | DATABASE | {N} | {Sequential — migration order matters} |
 | AUTH | {N} | {Critical — Wave 1} |
+| WORKER | {N} | {High overlap risk within worker service} |
+| AI | {N} | {Independent} |
 | INFRA | {N} | {Independent} |
-| CORTEX | {N} | {Independent} |
 
-(Omit rows with 0 issues.)
+(Omit rows with 0 issues. Add project-specific domain rows from forge.yaml → review.domains.)
 
 ### Implementation Waves
 
@@ -488,12 +498,18 @@ Proceed? (yes / adjust / pick specific issues)
 ```bash
 # Capture staging baseline before launching the wave
 git fetch origin
-STAGING_LINES_BEFORE=$(git diff --stat origin/main...origin/staging 2>/dev/null \
-  | tail -1 \
-  | grep -oP '\d+ insertion' \
-  | grep -oP '\d+' \
-  || echo "0")
-echo "Staging baseline before Wave {N}: ${STAGING_LINES_BEFORE} lines ahead of main"
+if [ "$DEFAULT_BRANCH" = "$STAGING_BRANCH" ]; then
+  # Single-branch repo — staging and default are the same; diff is always zero
+  STAGING_LINES_BEFORE=0
+  echo "Staging baseline before Wave {N}: skipped — single-branch repo (staging == default)"
+else
+  STAGING_LINES_BEFORE=$(git diff --stat origin/$DEFAULT_BRANCH...origin/$STAGING_BRANCH 2>/dev/null \
+    | tail -1 \
+    | grep -oP '\d+ insertion' \
+    | grep -oP '\d+' \
+    || echo "0")
+  echo "Staging baseline before Wave {N}: ${STAGING_LINES_BEFORE} lines ahead of $DEFAULT_BRANCH"
+fi
 ```
 
 Store `STAGING_LINES_BEFORE` per wave. After the wave completes (after Step 4C), run the integrity check:
@@ -501,27 +517,32 @@ Store `STAGING_LINES_BEFORE` per wave. After the wave completes (after Step 4C),
 ```bash
 # Check staging integrity after wave completes (run after Step 4C)
 git fetch origin
-STAGING_LINES_AFTER=$(git diff --stat origin/main...origin/staging 2>/dev/null \
-  | tail -1 \
-  | grep -oP '\d+ insertion' \
-  | grep -oP '\d+' \
-  || echo "0")
-STAGING_GROWTH=$((STAGING_LINES_AFTER - STAGING_LINES_BEFORE))
-
-echo "Staging after Wave {N}: ${STAGING_LINES_AFTER} lines (+${STAGING_GROWTH} vs baseline)"
-
-# Alert if growth exceeds expected delta
-# Expected: only the lines from PRs merged in this wave
-# Alert threshold: growth > 500 lines more than the sum of changed lines from wave PRs
-# (Use 0 as threshold if no PRs merged — any growth is unexpected)
-EXPECTED_DELTA={SUM_OF_PR_LINE_COUNTS_THIS_WAVE}  # set from PR diffs collected in 4B
-UNEXPECTED_GROWTH=$((STAGING_GROWTH - EXPECTED_DELTA))
-if [ "$UNEXPECTED_GROWTH" -gt 500 ]; then
-  echo "ALERT: Staging grew by ${STAGING_GROWTH} lines (+${UNEXPECTED_GROWTH} beyond expected ${EXPECTED_DELTA})."
-  echo "This may indicate milestone-code contamination via agent merge commits."
-  echo "Review: git log --oneline --merges origin/main..origin/staging"
-  echo "Do NOT merge staging → main until the unexpected growth is investigated."
-  # Do NOT auto-stop — alert the user and let them decide
+if [ "$DEFAULT_BRANCH" = "$STAGING_BRANCH" ]; then
+  STAGING_LINES_AFTER=0
+  STAGING_GROWTH=0
+  echo "Staging integrity check: skipped — single-branch repo (staging == default)"
+else
+  STAGING_LINES_AFTER=$(git diff --stat origin/$DEFAULT_BRANCH...origin/$STAGING_BRANCH 2>/dev/null \
+    | tail -1 \
+    | grep -oP '\d+ insertion' \
+    | grep -oP '\d+' \
+    || echo "0")
+  STAGING_GROWTH=$((STAGING_LINES_AFTER - STAGING_LINES_BEFORE))
+  echo "Staging after Wave {N}: ${STAGING_LINES_AFTER} lines (+${STAGING_GROWTH} vs baseline)"
+
+  # Alert if growth exceeds expected delta
+  # Expected: only the lines from PRs merged in this wave
+  # Alert threshold: growth > 500 lines more than the sum of changed lines from wave PRs
+  # (Use 0 as threshold if no PRs merged — any growth is unexpected)
+  EXPECTED_DELTA={SUM_OF_PR_LINE_COUNTS_THIS_WAVE}  # set from PR diffs collected in 4B
+  UNEXPECTED_GROWTH=$((STAGING_GROWTH - EXPECTED_DELTA))
+  if [ "$UNEXPECTED_GROWTH" -gt 500 ]; then
+    echo "ALERT: Staging grew by ${STAGING_GROWTH} lines (+${UNEXPECTED_GROWTH} beyond expected ${EXPECTED_DELTA})."
+    echo "This may indicate milestone-code contamination via agent merge commits."
+    echo "Review: git log --oneline --merges origin/$DEFAULT_BRANCH..origin/$STAGING_BRANCH"
+    echo "Do NOT merge $STAGING_BRANCH → $DEFAULT_BRANCH until the unexpected growth is investigated."
+    # Do NOT auto-stop — alert the user and let them decide
+  fi
 fi
 ```
 
@@ -738,7 +759,7 @@ for FINDING_NUM in {spawned_finding_numbers}; do
   FINDING_DATA=$(gh issue view $FINDING_NUM -R {GH_REPO} --json labels,title,body \
     --jq '{labels: [.labels[].name], title: .title, body: .body}')
 
-  PRIORITY=$(echo "$FINDING_DATA" | jq -r '.labels[] | select(startswith("P")) | .' | head -1)
+  PRIORITY=$(echo "$FINDING_DATA" | jq -r '.labels[] | select(startswith("priority:P")) | ltrimstr("priority:")' | head -1)
   TITLE=$(echo "$FINDING_DATA" | jq -r '.title')
 
   # Heuristic 1: Generation check — source issue has review-finding label (always defer, even for P1/P2)
@@ -799,7 +820,14 @@ They remain open in GitHub — they will be picked up by future `/orchestrate` o
 
 **When to run**: After each wave completes, IF the batch targets a milestone branch AND any `.tsx`/`.ts` files were changed by agents in the completed wave.
 
+All tool commands are read from `forge.yaml → verification.commands`; each step logs `SKIPPED — not configured` when the corresponding key is absent rather than silently passing.
+
 ```bash
+# Read toolchain commands from forge.yaml
+TS_TYPECHECK=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'typecheck:' | head -1 | sed "s/.*typecheck: *['\"]//;s/['\"].*//")
+TS_BUILD=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    typescript:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'build:' | head -1 | sed "s/.*build: *['\"]//;s/['\"].*//")
+PYTHON_FORMAT=$(awk '/^  commands:/{f=1;next} f && /^[^ \t]/{exit} f' forge.yaml 2>/dev/null | awk '/^    python:/{f=1;next} f && /^    [^ \t]/{exit} f' | grep 'format:' | head -1 | sed "s/.*format: *['\"]//;s/['\"].*//")
+
 # Check if this is a milestone batch with TypeScript changes
 MILESTONE_BRANCH="milestone/{milestone_slug}"
 TS_CHANGED=$(git diff origin/{DEFAULT_BRANCH}...origin/${MILESTONE_BRANCH} --name-only | grep -E '\.(tsx?|jsx?)$' | head -1)
@@ -809,20 +837,31 @@ if [ -n "$TS_CHANGED" ]; then
     cd {REPO_PATH}
     git fetch origin ${MILESTONE_BRANCH}
     git checkout origin/${MILESTONE_BRANCH} --detach 2>/dev/null
-    cd web && npx tsc --noEmit 2>&1 | head -30
-    TSC_EXIT=$?
-    if [ "$TSC_EXIT" -eq 0 ]; then
-        npx next build 2>&1 | tail -30
+
+    if [ -n "$TS_TYPECHECK" ]; then
+        eval "$TS_TYPECHECK" 2>&1 | head -30
+        TSC_EXIT=$?
+    else
+        echo "SKIPPED — typescript.typecheck not configured in verification.commands"
+        TSC_EXIT=0
+    fi
+
+    if [ "$TSC_EXIT" -eq 0 ] && [ -n "$TS_BUILD" ]; then
+        eval "$TS_BUILD" 2>&1 | tail -30
         BUILD_EXIT=$?
+    elif [ -z "$TS_BUILD" ]; then
+        echo "SKIPPED — typescript.build not configured in verification.commands"
+        BUILD_EXIT=0
     fi
-    cd .. && git checkout - 2>/dev/null
+
+    git checkout - 2>/dev/null
 
     if [ "$TSC_EXIT" -ne 0 ]; then
         echo "BLOCKING: TypeScript errors on ${MILESTONE_BRANCH} after Wave {N}."
         echo "Fix type errors before starting next wave."
     elif [ "${BUILD_EXIT:-0}" -ne 0 ]; then
-        echo "BLOCKING: next build failed on ${MILESTONE_BRANCH} after Wave {N}."
-        echo "SSG prerender or build errors — fix before starting next wave."
+        echo "BLOCKING: build failed on ${MILESTONE_BRANCH} after Wave {N}."
+        echo "Build/prerender errors — fix before starting next wave."
     fi
 fi
 
@@ -832,20 +871,25 @@ if [ -n "$PY_CHANGED" ]; then
     echo "=== Integration Build Gate (Python): Wave {N} ==="
     cd {REPO_PATH}
     git checkout origin/${MILESTONE_BRANCH} --detach 2>/dev/null
-    cd services/api && poetry run black --check app/ 2>&1 | tail -10
-    BLACK_EXIT=$?
-    poetry run isort --check app/ 2>&1 | tail -10
-    ISORT_EXIT=$?
-    cd ../.. && git checkout - 2>/dev/null
 
-    if [ "$BLACK_EXIT" -ne 0 ] || [ "$ISORT_EXIT" -ne 0 ]; then
+    if [ -n "$PYTHON_FORMAT" ]; then
+        eval "$PYTHON_FORMAT" 2>&1 | tail -10
+        FORMAT_EXIT=$?
+    else
+        echo "SKIPPED — python.format not configured in verification.commands"
+        FORMAT_EXIT=0
+    fi
+
+    git checkout - 2>/dev/null
+
+    if [ "$FORMAT_EXIT" -ne 0 ]; then
         echo "WARNING: Python formatting issues on ${MILESTONE_BRANCH} after Wave {N}."
         echo "Not blocking but should be fixed before milestone→staging."
     fi
 fi
 ```
 
-**If the gate fails**: Report the errors to the user. Do NOT proceed to the next wave. The accumulated milestone branch has integration errors that will only get worse with more PRs on top. `next build` failures are BLOCKING (not just `tsc`) — SSG prerender crashes are invisible to type checking.
+**If the gate fails**: Report the errors to the user. Do NOT proceed to the next wave. The accumulated milestone branch has integration errors that will only get worse with more PRs on top. Build failures are BLOCKING — SSG/prerender crashes are invisible to typecheck alone — configure `typescript.build` in `verification.commands` to catch them.
 
 ### Step 4E: Advance to next wave
 
@@ -1051,12 +1095,12 @@ Aggregate into the batch-level analytics for Step 6B.
 → Gets all unmilestoned bugs/fixes
 → Groups by independence, runs in waves
 
-### "orchestrate milestone cortex-recursive-loop"
-→ Fetches all open issues in "Cortex Recursive Loop" milestone
-→ Detects #2644 is an investigation issue (title: "Investigate: Complete the autonomous recursive loop...")
-→ Wave 0: Runs `/work-on 2644` — investigation creates 5 new issues (#2650-#2654)
-→ Re-fetches milestone issues, now includes #2650-#2654
-→ Wave 1: #2633 (P0 orphaned queues), #2636 (invalidation), #2650, #2651 (all independent)
-→ Wave 2: #2634 (enable daemon, after #2633), #2652 (depends on #2650)
+### "orchestrate milestone user-auth-v2"
+→ Fetches all open issues in "User Auth v2" milestone
+→ Detects #42 is an investigation issue (title: "Investigate: session expiry race condition under high concurrency")
+→ Wave 0: Runs `/work-on 42` — investigation creates 3 new issues (#55-#57)
+→ Re-fetches milestone issues, now includes #55-#57
+→ Wave 1: #38 (P0 token refresh bug), #41 (session store migration), #55, #56 (all independent)
+→ Wave 2: #39 (enable refresh rotation — after #38 fixes token bug), #57 (depends on #55)
 → Wave 3: remaining issues
 → Final report shows investigation spawned issues and their results

package/commands/pipeline-health.md

@@ -15,7 +15,14 @@ Read project identity from `forge.yaml` before running any phase:
 
 ```bash
 CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
-FORGE_REPO=$(yq e '.project.owner + "/" + .project.repo' "$CONFIG_FILE")
+GH_REPO=$(yq e '.project.owner + "/" + .project.repo' "$CONFIG_FILE")
+GH_FLAG="-R $GH_REPO"
+# FORGE_REPO: the self-pipeline repo where pipeline-health issues are filed.
+# Set project.forge_repo in forge.yaml if your pipeline repo differs from GH_REPO.
+# Example: project:
+#            forge_repo: "my-org/my-forge"
+FORGE_REPO=$(yq '.project.forge_repo // ""' "$CONFIG_FILE")
+[ -z "$FORGE_REPO" ] && FORGE_REPO="$GH_REPO"
 FORGE_HOME=$(yq e '.paths.root' "$CONFIG_FILE")
 echo "Forge repo: $FORGE_REPO"
 echo "Forge home: $FORGE_HOME"

package/commands/qa-sweep.md

@@ -170,8 +170,19 @@ fi
 **Dynamic discovery from filesystem** (NOT hardcoded):
 
 ```bash
-cd $PROJECT_ROOT/web/src/app
-find . -name "page.tsx" -o -name "page.js" | sort
+# Read pages root from forge.yaml review.layout.pages, fall back to web/src/app
+PAGES_ROOT=$(yq '.review.layout.pages // "web/src/app"' $PROJECT_ROOT/forge.yaml 2>/dev/null || echo "web/src/app")
+
+cd $PROJECT_ROOT/$PAGES_ROOT
+PAGES=$(find . -name "page.tsx" -o -name "page.js" | sort)
+
+# Loud failure when zero pages found — prevents silent no-op qa-sweep runs
+if [ -z "$PAGES" ]; then
+  echo "ERROR: Zero pages discovered under $PAGES_ROOT. If your project uses a different layout, set review.layout.pages in forge.yaml (e.g., 'apps/web/src/app' or 'src/pages')."
+  exit 1
+fi
+
+echo "$PAGES"
 ```
 
 Convert paths to routes: `./dashboard/billing/page.tsx` → `/dashboard/billing`
@@ -180,7 +191,7 @@ Convert paths to routes: `./dashboard/billing/page.tsx` → `/dashboard/billing`
 
 **Resolve dynamic routes** (`[param]`) by fetching real IDs from API. Test invalid IDs too.
 
-**For `diff` mode**: `git diff --name-only origin/main...origin/staging -- web/src/` → map to affected pages.
+**For `diff` mode**: `git diff --name-only origin/main...origin/staging -- $PAGES_ROOT/` → map to affected pages.
 
 **Present test plan to user** (page count by category, journey count, estimated waves). Wait for confirmation.
 

package/commands/review-pr-agents.md

@@ -987,7 +987,7 @@ done
 gh pr comment [PR_NUMBER] --body "$(cat <<'EOF'
 ## Scraper Logic Audit
 
-### Components Affected: [tiers/playbooks/cortex/validation/detection-keywords/capacity-constants/api-gate-semantics/cross-component-gate]
+### Components Affected: [list the specific service/worker/api components touched — e.g. job-queue/rate-limiter/validation/gate-semantics/cross-component-gate]
 
 ### Tier Flow Analysis
 [Trace the tier selection and escalation with file:line references]