forgedock 1.0.3 → 1.0.4

package/commands/cleanup.md

@@ -19,13 +19,14 @@ Read `forge.yaml` at the project root to resolve all project-specific variables
 
 ```bash
 # Parse forge.yaml for project context
-GH_REPO=$(yq '.project.owner + "/" + .project.repo' forge.yaml)
+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' forge.yaml)
-STAGING_BRANCH=$(yq '.branches.staging' forge.yaml)
-PROJECT_BOARD_OWNER=$(yq '.project_board.owner // .project.owner' forge.yaml)
-PROJECT_NUMBER=$(yq '.project_board.project_number // "1"' forge.yaml)
-PROJECT_ID=$(yq '.project_board.project_id' forge.yaml)
+REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
+STAGING_BRANCH=$(yq '.branches.staging' "$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")
 ```
 
 All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{STAGING_BRANCH}`, `{PROJECT_BOARD_OWNER}`, `{PROJECT_NUMBER}`, and `{PROJECT_ID}` references below are populated from `forge.yaml`.

package/commands/forge-stats.md

@@ -14,7 +14,8 @@ Tracks the size of every Forge command file over time. Detects bloat by comparin
 Read project home from `forge.yaml` before running any mode:
 
 ```bash
-FORGE_HOME=$(yq e '.paths.root' forge.yaml)
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
+FORGE_HOME=$(yq e '.paths.root' "$CONFIG_FILE")
 echo "Forge home: $FORGE_HOME"
 ```
 

package/commands/forgedock-init.md

@@ -55,7 +55,7 @@ fi
 ### 1A: Locate and read
 
 ```bash
-FORGE_YAML="$(pwd)/forge.yaml"
+FORGE_YAML="${FORGE_CONFIG:-$(git rev-parse --show-toplevel 2>/dev/null)/forge.yaml}"
 if [ ! -f "$FORGE_YAML" ]; then
   echo "forge.yaml not found in current directory."
   echo ""

package/commands/issue.md

@@ -38,10 +38,11 @@ The user's input (`$ARGUMENTS`) can be:
 Read `forge.yaml` to build the routing table dynamically:
 
 ```bash
-GH_REPO=$(yq '.project.owner + "/" + .project.repo' forge.yaml)
+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' forge.yaml)
-STAGING_BRANCH=$(yq '.branches.staging' forge.yaml)
+REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
+STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
 # Satellite repos from forge.yaml → repos.satellites (each has: prefix, repo, staging_branch)
 ```
 
@@ -424,8 +425,8 @@ fi
 
 ```bash
 # Add to project board if forge.yaml → project_board is configured
-PROJECT_NUMBER=$(yq '.project_board.project_number // ""' forge.yaml)
-PROJECT_BOARD_OWNER=$(yq '.project_board.owner // .project.owner' forge.yaml)
+PROJECT_NUMBER=$(yq '.project_board.project_number // ""' "$CONFIG_FILE")
+PROJECT_BOARD_OWNER=$(yq '.project_board.owner // .project.owner' "$CONFIG_FILE")
 if [ -n "$PROJECT_NUMBER" ] && [ "$PROJECT_NUMBER" != "null" ]; then
   gh project item-add "$PROJECT_NUMBER" --owner "$PROJECT_BOARD_OWNER" --url "${ISSUE_URL}" 2>/dev/null || true
 fi

package/commands/milestone.md

@@ -19,14 +19,15 @@ Read `forge.yaml` at the project root to resolve all project-specific variables
 
 ```bash
 # Parse forge.yaml for project context
-GH_REPO=$(yq '.project.owner + "/" + .project.repo' forge.yaml)
+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' forge.yaml)
-PROJECT_NAME=$(yq '.project.name' forge.yaml)
-STAGING_BRANCH=$(yq '.branches.staging' forge.yaml)
-PROJECT_BOARD_OWNER=$(yq '.project_board.owner // .project.owner' forge.yaml)
-PROJECT_NUMBER=$(yq '.project_board.project_number // "1"' forge.yaml)
-PROJECT_ID=$(yq '.project_board.project_id' forge.yaml)
+REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
+PROJECT_NAME=$(yq '.project.name' "$CONFIG_FILE")
+STAGING_BRANCH=$(yq '.branches.staging' "$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")
 # Build satellite repo map from repos.satellites list
 # Each satellite: { prefix, repo, staging_branch }
 ```
@@ -231,7 +232,7 @@ for ISSUE_NUM in {created_issue_numbers}; do
   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.fields)
+    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
@@ -568,7 +569,7 @@ Syncs the milestone branch with the latest default branch to pick up fast-lane f
 
 ```bash
 cd {REPO_PATH}
-DEFAULT_BRANCH=$(yq '.branches.default' forge.yaml)
+DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE")
 git fetch origin $DEFAULT_BRANCH milestone/{slug}
 git checkout milestone/{slug}
 git merge origin/$DEFAULT_BRANCH --no-edit

package/commands/orchestrate.md

@@ -31,11 +31,12 @@ Read `forge.yaml` at the project root to resolve all project-specific variables
 
 ```bash
 # Parse forge.yaml for project context
-GH_REPO=$(yq '.project.owner + "/" + .project.repo' forge.yaml)
+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' forge.yaml)
-PROJECT_NAME=$(yq '.project.name' forge.yaml)
-STAGING_BRANCH=$(yq '.branches.staging' forge.yaml)
+REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
+PROJECT_NAME=$(yq '.project.name' "$CONFIG_FILE")
+STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
 # Build satellite repo map from repos.satellites list
 # Each satellite: { prefix, repo, staging_branch }
 ```

package/commands/pipeline-health.md

@@ -14,8 +14,9 @@ You are the Forge pipeline's self-awareness layer. Your job is to measure how we
 Read project identity from `forge.yaml` before running any phase:
 
 ```bash
-FORGE_REPO=$(yq e '.project.owner + "/" + .project.repo' forge.yaml)
-FORGE_HOME=$(yq e '.paths.root' forge.yaml)
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
+FORGE_REPO=$(yq e '.project.owner + "/" + .project.repo' "$CONFIG_FILE")
+FORGE_HOME=$(yq e '.paths.root' "$CONFIG_FILE")
 echo "Forge repo: $FORGE_REPO"
 echo "Forge home: $FORGE_HOME"
 ```

package/commands/quality-gate.md

@@ -783,7 +783,7 @@ If 0 findings:
 ```
 QUALITY GATE: PASS — no issues detected.
 
-<!-- FORGE:PHASE_COMPLETE — Quality gate is an intermediate check. See work-on.md Universal Phase Dispatcher for next phase. Not terminal — calling agent must continue. -->
+**YOU MUST NOW continue to sub-phase 3H (Format and verify) in work-on.md — this PASS is intermediate, NOT terminal. Do NOT stop.**
 ```
 
 If findings exist:
@@ -791,5 +791,5 @@ If findings exist:
 QUALITY GATE FINDINGS: N issues detected.
 {findings list}
 
-<!-- FORGE:PHASE_COMPLETE — Quality gate is an intermediate check. See work-on.md Universal Phase Dispatcher for next phase. Not terminal — calling agent must continue. -->
+**YOU MUST NOW fix each HIGH and MEDIUM finding, then re-run the quality gate — this result is intermediate, NOT terminal. Do NOT stop.**
 ```

package/commands/review-pr.md

@@ -108,6 +108,22 @@ REVIEW_SHA=$(gh pr view $ARGUMENTS --json headRefOid --jq '.headRefOid')
 REVIEW_SHA_SHORT=$(echo "$REVIEW_SHA" | cut -c1-7)
 gh pr diff $ARGUMENTS --name-only
 gh pr diff $ARGUMENTS
+
+# Mergeability check — GitHub computes this asynchronously; retry up to 3× on UNKNOWN
+# <!-- Added: forge#194 -->
+MERGE_HEALTH_RESULT=$(gh pr view $ARGUMENTS --json mergeable,mergeStateStatus --jq '"\\(.mergeable)|\\(.mergeStateStatus)"')
+MERGE_HEALTH=${MERGE_HEALTH_RESULT%%|*}
+MERGE_HEALTH_STATE=${MERGE_HEALTH_RESULT##*|}
+MERGE_RETRY=0
+while [ "$MERGE_HEALTH" = "UNKNOWN" ] && [ "$MERGE_RETRY" -lt 3 ]; do
+    MERGE_RETRY=$((MERGE_RETRY + 1))
+    sleep 5
+    MERGE_HEALTH_RESULT=$(gh pr view $ARGUMENTS --json mergeable,mergeStateStatus --jq '"\\(.mergeable)|\\(.mergeStateStatus)"')
+    MERGE_HEALTH=${MERGE_HEALTH_RESULT%%|*}
+    MERGE_HEALTH_STATE=${MERGE_HEALTH_RESULT##*|}
+done
+# MERGE_HEALTH: MERGEABLE | CONFLICTING | UNKNOWN (still async after retries)
+# MERGE_HEALTH_STATE: CLEAN | DIRTY | BLOCKED | UNSTABLE | UNKNOWN
 ```
 
 ### 1B: Classify
@@ -508,7 +524,7 @@ Read the file: $FORGE_HOME/commands/review-pr-agents.md
 **>>> LOAD CONFIG: Read forge.yaml for project context:**
 ```bash
 # Read review config from forge.yaml (if present in project root)
-FORGE_YAML="${REPO_ROOT}/forge.yaml"
+FORGE_YAML="${FORGE_CONFIG:-$(git rev-parse --show-toplevel 2>/dev/null)/forge.yaml}"
 PROJECT_NAME=$(yq '.project.name' "$FORGE_YAML" 2>/dev/null || echo "this project")
 PROJECT_CONTEXT=$(yq '.review.context' "$FORGE_YAML" 2>/dev/null || echo "")
 TECH_STACK=$(yq '.review.tech_stack' "$FORGE_YAML" 2>/dev/null || echo "")
@@ -752,7 +768,7 @@ for FINDING_NUM in {numbers}; do
   # PROJECT_ID = forge.yaml → project_board.project_id
   # STATUS_FIELD_ID = forge.yaml → project_board.field_ids.status
   # LANE_FIELD_ID = forge.yaml → project_board.field_ids.lane
-  # REVIEW_FINDING_OPTION_ID = forge.yaml → project_board.option_ids.status.in_review
+  # REVIEW_FINDING_OPTION_ID = forge.yaml → project_board.option_ids.workflow.in_review
   ITEM_ID=$(gh project item-add ${PROJECT_NUMBER} --owner ${OWNER} --url "https://github.com/${GH_REPO}/issues/${FINDING_NUM}" --format json --jq '.id' 2>/dev/null)
   [ -n "$ITEM_ID" ] && {
     [ -n "$STATUS_FIELD_ID" ] && gh project item-edit --project-id ${PROJECT_ID} --id "$ITEM_ID" --field-id ${STATUS_FIELD_ID} --single-select-option-id ${REVIEW_FINDING_OPTION_ID} 2>/dev/null || true
@@ -836,16 +852,31 @@ Verdict determined by standard blocking criteria.
 1. Phase 2 automated checks failed (build error, type error, test failure)
 2. Agent finding is CONFIRMED at HIGH or CRITICAL severity
 3. **[Milestone PRs only]** Phase 7A Purpose Regression Gate flagged `HAS_PURPOSE_REGRESSION=true` for this finding — regardless of whether it causes a runtime error
+4. `MERGE_HEALTH == "CONFLICTING"` OR `MERGE_HEALTH_STATE` in {`DIRTY`, `BLOCKED`} — PR cannot be merged cleanly into its base branch <!-- Added: forge#194 -->
+   - Verdict: CHANGES REQUESTED. Message: "Merge conflict with `{base}`. Rebase `{head}` onto `origin/{base}`, resolve the conflicting files, then re-run /review-pr."
+   - If `MERGE_HEALTH == "UNKNOWN"` after retries: emit a WARNING in the verdict body (do NOT treat as a block — GitHub may still be computing it).
 
 ```bash
+# Determine if mergeability is a blocker (MERGE_HEALTH/MERGE_HEALTH_STATE set in Phase 1A; BASE/HEAD set in Phase 0 Mode 3)
+HAS_MERGE_CONFLICT=false
+MERGE_CONFLICT_MSG=""
+if [ "$MERGE_HEALTH" = "CONFLICTING" ] || [ "$MERGE_HEALTH_STATE" = "DIRTY" ] || [ "$MERGE_HEALTH_STATE" = "BLOCKED" ]; then
+    HAS_MERGE_CONFLICT=true
+    MERGE_CONFLICT_MSG="Merge conflict with \`${BASE}\`. Rebase \`${HEAD}\` onto \`origin/${BASE}\`, resolve the conflicting files, then re-run /review-pr."
+fi
+
 # Stale review:
 gh pr review $ARGUMENTS --comment --body "Review of commit $REVIEW_SHA_SHORT is stale — PR HEAD changed. Re-run /review-pr."
 
 # Clean (no blocking issues):
-gh pr review $ARGUMENTS --comment --body "APPROVED: commit $REVIEW_SHA_SHORT after context-aware review ([N] agents: [names]). [M] findings created as issues. Safe to merge."
+gh pr review $ARGUMENTS --comment --body "APPROVED: commit $REVIEW_SHA_SHORT after context-aware review ([N] agents: [names]). [M] findings created as issues. Safe to merge.
+$([ "$MERGE_HEALTH" = "UNKNOWN" ] && echo "
+⚠ Mergeability: GitHub is still computing merge state (UNKNOWN after retries). Verify manually before merging.")"
 
-# Blocking issues (including purpose regressions):
+# Blocking issues (including merge conflicts and purpose regressions):
 gh pr review $ARGUMENTS --comment --body "CHANGES REQUESTED: commit $REVIEW_SHA_SHORT — [N] blocking issues found. See GitHub issues.
+$([ "$HAS_MERGE_CONFLICT" = "true" ] && echo "
+🔴 Merge Conflict: ${MERGE_CONFLICT_MSG}")
 $([ "$HAS_PURPOSE_REGRESSION" = "true" ] && echo "
 ⚠ Purpose Regression: [N] finding(s) contradict the milestone's stated goal and are automatically blocking regardless of runtime impact. See: ${PURPOSE_REGRESSION_FINDINGS[@]}")"
 ```
@@ -857,15 +888,28 @@ $([ "$HAS_PURPOSE_REGRESSION" = "true" ] && echo "
 **Skip if** `AUTO_MERGE=false`.
 
 ```bash
-# Checkpoint comment on issue
-gh issue comment {MERGE_ISSUE} {MERGE_GH_FLAG} --body "Review complete for PR #{PR_NUMBER}. Verdict: {VERDICT}. Proceeding to merge."
+# Pre-merge mergeability guard — re-fetch fresh state before attempting merge <!-- Added: forge#194 -->
+# A PR that was MERGEABLE at Phase 1A may have become CONFLICTING if the base branch
+# received commits while the review was running. Re-check before every auto-merge.
+PRE_MERGE_RESULT=$(gh pr view {PR_NUMBER} {MERGE_GH_FLAG} --json mergeable,mergeStateStatus --jq '"\\(.mergeable)|\\(.mergeStateStatus)"')
+PRE_MERGE_HEALTH=${PRE_MERGE_RESULT%%|*}
+PRE_MERGE_HEALTH_STATE=${PRE_MERGE_RESULT##*|}
 
-# Merge
-gh pr merge {PR_NUMBER} {MERGE_GH_FLAG} --merge
+if [ "$PRE_MERGE_HEALTH" = "CONFLICTING" ] || [ "$PRE_MERGE_HEALTH_STATE" = "DIRTY" ] || [ "$PRE_MERGE_HEALTH_STATE" = "BLOCKED" ]; then
+    gh issue comment {MERGE_ISSUE} {MERGE_GH_FLAG} --body "⛔ Auto-merge aborted for PR #{PR_NUMBER}: PR is not mergeable (\`mergeable=${PRE_MERGE_HEALTH}\`, \`mergeStateStatus=${PRE_MERGE_HEALTH_STATE}\`). Rebase the branch onto \`{MERGE_BASE}\` and resolve conflicts, then re-run /review-pr."
+    gh issue edit {MERGE_ISSUE} {MERGE_GH_FLAG} --add-label "needs-human" 2>/dev/null || true
+    # STOP — do not attempt gh pr merge on a CONFLICTING/DIRTY PR
+else
+    # Checkpoint comment on issue
+    gh issue comment {MERGE_ISSUE} {MERGE_GH_FLAG} --body "Review complete for PR #{PR_NUMBER}. Verdict: {VERDICT}. Proceeding to merge."
+
+    # Merge
+    gh pr merge {PR_NUMBER} {MERGE_GH_FLAG} --merge
 
-# Verify
-MERGE_STATE=$(gh pr view {PR_NUMBER} {MERGE_GH_FLAG} --json state --jq '.state')
-[ "$MERGE_STATE" != "MERGED" ] && gh issue comment {MERGE_ISSUE} {MERGE_GH_FLAG} --body "PR #{PR_NUMBER} merge failed. State: $MERGE_STATE."
+    # Verify
+    MERGE_STATE=$(gh pr view {PR_NUMBER} {MERGE_GH_FLAG} --json state --jq '.state')
+    [ "$MERGE_STATE" != "MERGED" ] && gh issue comment {MERGE_ISSUE} {MERGE_GH_FLAG} --body "PR #{PR_NUMBER} merge failed. State: $MERGE_STATE."
+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.

package/commands/sync-ecosystem.md

@@ -19,9 +19,10 @@ Before any phase runs, build the ecosystem registry from `forge.yaml → repos.s
 # Read satellite repos from forge.yaml
 # Each entry provides: prefix, repo, staging_branch, local_path
 # (Optional: package, publish_workflow — read from each satellite's package.json / workflow files)
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
 
 # Gate: if repos section is absent or has no satellites, stop here
-if [ -z "$(yq '.repos.satellites // empty' forge.yaml 2>/dev/null)" ]; then
+if [ -z "$(yq '.repos.satellites // empty' "$CONFIG_FILE" 2>/dev/null)" ]; then
   echo "No satellite repos configured in forge.yaml → repos.satellites."
   echo "Add entries to forge.yaml to use /sync-ecosystem:"
   echo ""
@@ -52,10 +53,10 @@ fi
 #       node_sdk: "sdk/node"
 #   Then {REPO_PATH}/sdk/python and {REPO_PATH}/sdk/node are the per-SDK roots.
 
-PROJECT_NAME=$(yq '.project.name' forge.yaml)
-PROJECT_BOARD_OWNER=$(yq '.project_board.owner // .project.owner' forge.yaml)
-PROJECT_BOARD_NUMBER=$(yq '.project_board.project_number // empty' forge.yaml)
-PROJECT_BOARD_ID=$(yq '.project_board.project_id // empty' forge.yaml)
+PROJECT_NAME=$(yq '.project.name' "$CONFIG_FILE")
+PROJECT_BOARD_OWNER=$(yq '.project_board.owner // .project.owner' "$CONFIG_FILE")
+PROJECT_BOARD_NUMBER=$(yq '.project_board.project_number // empty' "$CONFIG_FILE")
+PROJECT_BOARD_ID=$(yq '.project_board.project_id // empty' "$CONFIG_FILE")
 ```
 
 ---

package/commands/work-on/close.md

@@ -110,13 +110,14 @@ Update the project board to reflect the merged state. This replaces the old Phas
 
 ```bash
 # Read project board config from forge.yaml
-PROJECT_BOARD_OWNER=$(yq '.project_board.owner // ""' forge.yaml 2>/dev/null || echo "")
-PROJECT_ID=$(yq '.project_board.project_id // ""' forge.yaml 2>/dev/null || echo "")
-PROJECT_NUMBER=$(yq '.project_board.project_number // ""' forge.yaml 2>/dev/null || echo "")
-STATUS_FIELD_ID=$(yq '.project_board.field_ids.status // ""' forge.yaml 2>/dev/null || echo "")
-WORKFLOW_FIELD_ID=$(yq '.project_board.field_ids.workflow // ""' forge.yaml 2>/dev/null || echo "")
-STATUS_DONE_OPTION_ID=$(yq '.project_board.option_ids.status.done // ""' forge.yaml 2>/dev/null || echo "")
-WORKFLOW_MERGED_OPTION_ID=$(yq '.project_board.option_ids.workflow.merged // ""' forge.yaml 2>/dev/null || echo "")
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
+PROJECT_BOARD_OWNER=$(yq '.project_board.owner // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+PROJECT_ID=$(yq '.project_board.project_id // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+PROJECT_NUMBER=$(yq '.project_board.project_number // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+STATUS_FIELD_ID=$(yq '.project_board.field_ids.status // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+WORKFLOW_FIELD_ID=$(yq '.project_board.field_ids.workflow // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+STATUS_DONE_OPTION_ID=$(yq '.project_board.option_ids.status.done // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
+WORKFLOW_MERGED_OPTION_ID=$(yq '.project_board.option_ids.workflow.merged // ""' "$CONFIG_FILE" 2>/dev/null || echo "")
 
 if [ -z "$PROJECT_BOARD_OWNER" ] || [ -z "$PROJECT_ID" ] || [ -z "$STATUS_FIELD_ID" ]; then
   echo "INFO: project_board not configured in forge.yaml — skipping board update"

package/commands/work-on/review.md

@@ -219,7 +219,9 @@ gh issue view {NUMBER} {GH_FLAG} --json state --jq '.state'
 
 ## Output
 
-Output this structured block — the routing loop in `work-on.md` will read this result, re-evaluate state, and continue to the next phase. This subcommand is complete; control returns to the router's loop iteration.
+**After posting this result, immediately proceed to the close subcommand — do NOT stop here. `REVIEW_RESULT: status: COMPLETE` is an intermediate result, NOT a terminal state. The pipeline is not done. You MUST invoke `Skill("work-on:close", ...)` now to close the issue, update labels to `workflow:merged`, post the trajectory log, and clean up the worktree.**
+
+Output this structured block:
 
 ```
 REVIEW_RESULT:

package/commands/work-on.md

@@ -741,9 +741,9 @@ if iteration == max_iterations AND not PASS:
     Add needs-human label → STOP
 ```
 
-<!-- FORGE:PHASE_COMPLETE — Quality gate done. See Universal Phase Dispatcher: next sub-phase is 3H. Not terminal — continue immediately. -->
+# MUST CONTINUE to sub-phase 3H (Format and verify) — quality gate PASS is intermediate, NOT terminal. <!-- Added: forge#220 -->
 
-**After quality gate completes (PASS or fixes applied): proceed to the next sub-phase per the Universal Phase Dispatcher. Quality gate is an intermediate check — "PASS" means the code is clean, NOT that the build is done.**
+**After quality gate completes (PASS or fixes applied): proceed immediately to sub-phase 3H below. Quality gate is an intermediate check — "PASS" means the code is clean, NOT that the build is done. Do NOT stop.**
 
 ### 3H: Format and verify
 
@@ -974,6 +974,8 @@ gh issue view {NUMBER} {GH_FLAG} --json state --jq '.state'
 
 <!-- FORGE:PHASE_COMPLETE — Review done, PR merged. See Universal Phase Dispatcher: next phase is Phase 6 (Close & Cleanup). Not terminal — continue immediately. -->
 
+**After /review-pr returns and the PR is confirmed merged: immediately proceed to Phase 6 (Close & Cleanup). Do NOT stop here. `REVIEW_RESULT: status: COMPLETE` is an intermediate result — the pipeline is NOT done. Invoke Phase 6 now to close the issue, update labels, post the trajectory log, and clean up the worktree.**
+
 ---
 
 ## Phase 6: Close & Cleanup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "GitHub as a knowledge graph for AI agents. Autonomous dev pipeline for Claude Code.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"