forgedock 1.0.21 → 1.1.1

package/commands/work-on/build/architect.md

@@ -176,6 +176,11 @@ if [ -n "$DEVDOCS_PATH" ] && [ -f "$INDEX_PATH" ]; then
   ISSUE_LABELS=$(gh issue view {NUMBER} -R {GH_REPO} --json labels \
     --jq '[.labels[].name] | join(" ")' 2>/dev/null || echo "")
   echo "Issue labels: ${ISSUE_LABELS:-none}"
+  # Separate newline-joined list for the loop below — GitHub label names CAN
+  # contain spaces (e.g. "good first issue"), so the space-joined $ISSUE_LABELS
+  # above is only safe for display, never for iteration.
+  ISSUE_LABELS_LIST=$(gh issue view {NUMBER} -R {GH_REPO} --json labels \
+    --jq '.labels[].name' 2>/dev/null || echo "")
 
   # Read index content
   INDEX_CONTENT=$(cat "$INDEX_PATH" 2>/dev/null || echo "")
@@ -190,7 +195,12 @@ if [ -n "$DEVDOCS_PATH" ] && [ -f "$INDEX_PATH" ]; then
 
   # Extract domain blocks matching any issue label keyword
   DOMAIN_PATHS=""
-  for label in $ISSUE_LABELS; do
+  # $ISSUE_LABELS_LIST is one label per line — herestring (not a piped
+  # `| while read`, which would run the loop body in a subshell and discard
+  # DOMAIN_PATHS once the loop exits) preserves newline-safety for labels
+  # containing spaces.
+  while IFS= read -r label; do
+    [ -z "$label" ] && continue
     KEYWORD=$(echo "$label" | sed 's/^workflow://; s/^priority://; s/^review-finding$//')
     [ -z "$KEYWORD" ] && continue
     # Sanitize KEYWORD before AWK injection — strip chars that would break awk regex delimiters
@@ -207,7 +217,7 @@ if [ -n "$DEVDOCS_PATH" ] && [ -f "$INDEX_PATH" ]; then
       echo "Domain '${SAFE_KEYWORD}' matched — adding docs: $(echo "$BLOCK_PATHS" | tr '\n' ' ')"
       DOMAIN_PATHS="${DOMAIN_PATHS}${BLOCK_PATHS}"$'\n'
     fi
-  done
+  done <<< "$ISSUE_LABELS_LIST"
 
   # Combine always_load + domain paths (deduplicate)
   ALL_PATHS=$(printf "%s\n%s" "$ALWAYS_LOAD_PATHS" "$DOMAIN_PATHS" \
@@ -448,11 +458,45 @@ For each non-obvious interaction or potential failure mode:
 - Suggest a mitigation or check
 
 Focus on:
-- Files that have changed recently (check `git log --oneline -10 -- {FILE}`)
+- Churn / hot-spot files (see below) — high historical change frequency correlates with defect density
 - Paths that are called in both sync and async contexts
 - Any place where the change touches a serialization boundary (JSON in/out, DB read/write)
 - Unused or dormant code that the change might activate
 
+### Churn (Hot-Spot) Signal
+
+Recency alone (did the file appear in the last N commits?) is a weak, binary proxy. Compute a bounded per-file **churn tier** instead — how often each affected file has actually changed over a fixed window — and fold it into the risk table below.
+
+For each file in `{AFFECTED_FILES}` (never repo-wide — this must stay O(affected files) to fit the Phase A0–A5 time budget):
+
+```bash
+CHURN_WINDOW="90 days ago"   # named constant — must match the same window used in review-pr.md Phase 3A
+
+# {AFFECTED_FILES} is a space-separated argument (see --files contract at the top
+# of this file), not newline-separated like review-pr.md's $FILES — so a herestring
+# `while read` line-loop would misparse it as a single line. Split explicitly on
+# IFS=' ' into an array instead of relying on a bare `for FILE in {AFFECTED_FILES}`
+# (which word-splits on the shell's default IFS — space, tab, AND newline). This
+# keeps the existing space-separated contract intact while narrowing the splitting
+# surface to spaces only.
+IFS=' ' read -ra AFFECTED_FILES_ARR <<< "{AFFECTED_FILES}"
+for FILE in "${AFFECTED_FILES_ARR[@]}"; do
+  COMMITS=$(git log --oneline --since="$CHURN_WINDOW" -- "$FILE" | wc -l)
+  if [ "$COMMITS" -ge 15 ]; then TIER="HOT"
+  elif [ "$COMMITS" -ge 5 ]; then TIER="MEDIUM"
+  else TIER="LOW"
+  fi
+  echo "$FILE: $TIER ($COMMITS commits in last 90 days)"
+done
+```
+
+**Tiers** (fixed thresholds — keep identical to `review-pr.md` Phase 3A so both phases agree on what "hot" means):
+- **HOT**: 15+ commits in the window
+- **MEDIUM**: 5–14 commits in the window
+- **LOW**: 0–4 commits in the window
+
+Any file classified **HOT** MUST get an explicit row in the Risk Assessment table below (e.g. "High historical churn — {N} commits in last 90 days — changes here have a higher defect-density prior"), rated at least MEDIUM severity, with a mitigation such as "extra reviewer scrutiny" or "prefer smaller, isolated diffs to this file." MEDIUM-tier files may be noted inline without a dedicated row. LOW-tier files need no mention.
+
 ---
 
 ## Output Format

package/commands/work-on/build/context.md

@@ -125,6 +125,11 @@ if [ -n "$DEVDOCS_PATH" ] && [ -f "$INDEX_PATH" ]; then
   ISSUE_LABELS=$(gh issue view {NUMBER} -R {GH_REPO} --json labels \
     --jq '[.labels[].name] | join(" ")' 2>/dev/null || echo "")
   echo "Issue labels: ${ISSUE_LABELS:-none}"
+  # Separate newline-joined list for the loop below — GitHub label names CAN
+  # contain spaces (e.g. "good first issue"), so the space-joined $ISSUE_LABELS
+  # above is only safe for display, never for iteration.
+  ISSUE_LABELS_LIST=$(gh issue view {NUMBER} -R {GH_REPO} --json labels \
+    --jq '.labels[].name' 2>/dev/null || echo "")
 
   # Read index content
   INDEX_CONTENT=$(cat "$INDEX_PATH" 2>/dev/null || echo "")
@@ -139,7 +144,12 @@ if [ -n "$DEVDOCS_PATH" ] && [ -f "$INDEX_PATH" ]; then
 
   # Extract domain blocks matching any issue label keyword
   DOMAIN_PATHS=""
-  for label in $ISSUE_LABELS; do
+  # $ISSUE_LABELS_LIST is one label per line — herestring (not a piped
+  # `| while read`, which would run the loop body in a subshell and discard
+  # DOMAIN_PATHS once the loop exits) preserves newline-safety for labels
+  # containing spaces.
+  while IFS= read -r label; do
+    [ -z "$label" ] && continue
     # Strip workflow:, priority:, review-finding prefixes — use bare keyword
     KEYWORD=$(echo "$label" | sed 's/^workflow://; s/^priority://; s/^review-finding$//')
     [ -z "$KEYWORD" ] && continue
@@ -158,7 +168,7 @@ if [ -n "$DEVDOCS_PATH" ] && [ -f "$INDEX_PATH" ]; then
       echo "Domain '${SAFE_KEYWORD}' matched — adding docs: $(echo "$BLOCK_PATHS" | tr '\n' ' ')"
       DOMAIN_PATHS="${DOMAIN_PATHS}${BLOCK_PATHS}"$'\n'
     fi
-  done
+  done <<< "$ISSUE_LABELS_LIST"
 
   # Combine always_load + domain paths (deduplicate)
   ALL_PATHS=$(printf "%s\n%s" "$ALWAYS_LOAD_PATHS" "$DOMAIN_PATHS" \
@@ -397,7 +407,12 @@ If `GIST_SUMMARIES` is non-empty, it will be included in the `### Prior Investig
 Query closed issues with `review-finding` label, searching by filename:
 
 ```bash
-for file in {AFFECTED_FILES}; do
+# {AFFECTED_FILES} is a space-separated file path list (see contract note above)
+# — split explicitly on IFS=' ' into an array instead of a bare
+# `for file in {AFFECTED_FILES}`, which word-splits on the shell's default IFS
+# (space, tab, AND newline) and would corrupt any path containing a space.
+IFS=' ' read -ra AFFECTED_FILES_ARR <<< "{AFFECTED_FILES}"
+for file in "${AFFECTED_FILES_ARR[@]}"; do
   basename=$(basename "$file" .py)
   gh issue list -R {GH_REPO} \
     --state closed \
@@ -425,7 +440,7 @@ Keep findings where the filename or function name appears in the title or body.
 
 ## Phase C2: Past Bugs in the Same Module
 
-Mine git log for commit messages referencing issues, then fetch those issues:
+Mine git log for commit messages referencing issues, then fetch those issues. Also read commit bodies/diffs directly — local git history is near-free relative to `gh api` round-trips, and commit bodies often explain the "why" without needing to fetch the linked issue at all.
 
 ```bash
 # Step 1: find issue numbers from git history on affected files
@@ -444,6 +459,20 @@ Filter: keep only `bug`, `fix`, or `review-finding` labeled issues. Skip feature
 
 **Max results**: 5 issues.
 
+**Direct commit-body read (bounded, prefer over `gh api` when it already answers "why")**: For the top 5 commits touching `{AFFECTED_FILES}`, read the commit subject + body directly instead of round-tripping to `gh issue view` when the body already explains the change:
+```bash
+git log -5 --format='%h %ad %s%n%b' --date=short -- {AFFECTED_FILES}
+```
+If a commit body fully explains the prior bug/fix (common for squashed or fix-up commits with no `#NNN` reference), use it directly as a "Past Bug in This Module" entry — do not require a linked GitHub issue to exist.
+
+**Pickaxe pass (has this exact area been fixed before?)** — one bounded pass, capped at 5 hits, keyed on the suspected symbol/string from the Builder Contract or investigation report:
+```bash
+git log -S"{suspected_symbol_or_string}" --oneline -- {AFFECTED_FILES} | head -5
+# Use -G instead of -S for regex patterns
+git log -G"{pattern}" --oneline -- {AFFECTED_FILES} | head -5
+```
+Any hit is a candidate prior fix or reintroduced defect for this exact code area — read `git show {hash}` to confirm scope before including it in the output. This catches regressions the issue-number harvest above misses (e.g. a defect fixed via a squashed commit with no `#NNN` reference).
+
 ---
 
 ## Phase C3: Related Code Paths
@@ -526,8 +555,10 @@ gh issue comment {NUMBER} -R {GH_REPO} --body "<!-- FORGE:CONTEXT -->
 - #{NUM}: \"{TITLE}\" — root cause: {ROOT_CAUSE}
 
 ### Past Bugs in This Module
-<!-- List of closed bug issues from git log mining. If none: 'No prior bugs found in git history.' -->
+<!-- List of closed bug issues from git log mining, PLUS pickaxe-derived findings (commits with no linked issue, or
+     commit bodies read directly per the C2 direct-commit-body step). If none: 'No prior bugs found in git history.' -->
 - #{NUM}: \"{TITLE}\" — root cause: {SNIPPET}
+- {COMMIT_HASH} (no linked issue): {COMMIT_SUBJECT} — {WHY_RELEVANT, from commit body or pickaxe hit}
 
 ### Related Code Paths (must stay consistent)
 <!-- Files that import or call the changed functions. Builder must read and validate these. -->

package/commands/work-on/build/implement.md

@@ -53,7 +53,17 @@ gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
   --jq '.[] | select(.body | contains("FORGE:CONTEXT")) | .body'
 ```
 
-**Resume check**: If `<!-- FORGE:BUILDER -->` comment already exists, the implementation is done — EXIT and return `IMPLEMENT_RESULT: status: ALREADY_DONE` to caller.
+**Resume check**:
+- If `<!-- FORGE:BUILDER:COMPLETE -->` is present in a BUILDER comment → implementation is done — EXIT and return `IMPLEMENT_RESULT: status: ALREADY_DONE` to caller.
+- If `<!-- FORGE:BUILDER -->` exists BUT `<!-- FORGE:BUILDER:COMPLETE -->` is ABSENT → implementation was interrupted after the comment was posted but before the commit (validate.md V5). Delete the partial comment and restart from Phase I2:
+  ```bash
+  PARTIAL_ID=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+    --jq '[.[] | select(.body | contains("FORGE:BUILDER") and (contains("FORGE:BUILDER:COMPLETE") | not))] | last | .id // ""')
+  if [ -n "$PARTIAL_ID" ]; then
+    gh api repos/{GH_REPO}/issues/comments/$PARTIAL_ID -X DELETE
+    echo "Deleted partial FORGE:BUILDER comment (no FORGE:BUILDER:COMPLETE) — restarting implementation"
+  fi
+  ```
 
 **Primary guide**: If `<!-- FORGE:ARCHITECT -->` is present, it is the **primary implementation input**. Follow its ordered implementation list exactly — it defines which files change, in what order, and what consistency checks must pass. The investigation report and contract are secondary context.
 
@@ -225,6 +235,8 @@ gh issue edit {NUMBER} {GH_FLAG} --body "{UPDATED_BODY}"
 
 ## Phase I6: Post FORGE:BUILDER Comment
 
+Post the implementation summary comment. **Do NOT include `<!-- FORGE:BUILDER:COMPLETE -->` here** — that marker is posted by `validate.md` Phase V5 after the commit succeeds. A crash between I6 and V5 would otherwise leave a completion-marked comment with no commit on the branch.
+
 ```bash
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:BUILDER -->
 ## Implementation Complete
@@ -247,11 +259,11 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:BUILDER -->
 - [ ] {Test scenario 2} [type:unit]
 - [ ] {Test scenario 3} [type:e2e]
 
-> **Test-type annotation** (optional): Append `[type:api]`, `[type:unit]`, `[type:e2e]`, or `[type:manual]` to each checklist item. The test gate reads this annotation directly and skips regex inference. Omit it to rely on regex classification fallback.
-
-<!-- FORGE:BUILDER:COMPLETE -->"
+> **Test-type annotation** (optional): Append `[type:api]`, `[type:unit]`, `[type:e2e]`, or `[type:manual]` to each checklist item. The test gate reads this annotation directly and skips regex inference. Omit it to rely on regex classification fallback."
 ```
 
+**Note**: `<!-- FORGE:BUILDER:COMPLETE -->` is intentionally absent from this comment. It is appended to this comment by `validate.md` Phase V5 after the git commit completes — see `validate.md § Phase V5`. This ordering ensures the completion marker only exists when a real commit is present on the branch.
+
 ---
 
 ## Output

package/commands/work-on/build/validate.md

@@ -90,7 +90,12 @@ Needs human review before proceeding to commit.
 
 ## Phase V2: Format and Verify
 
-Run after quality gate passes. 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:
+Run after quality gate passes. 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.
+
+**Track skipped checks** — initialize before any check runs:
+```bash
+SKIPPED_CHECKS=""
+```
 
 **Python**:
 ```bash
@@ -101,6 +106,7 @@ if [ -n "$PYTHON_FORMAT" ]; then
     eval "$PYTHON_FORMAT" 2>&1
 else
     echo "SKIPPED — python.format not configured in verification.commands"
+    SKIPPED_CHECKS="${SKIPPED_CHECKS:+$SKIPPED_CHECKS, }python.format"
 fi
 
 # Compile check always runs for Python files (no config needed — catches syntax errors)
@@ -120,6 +126,7 @@ if [ -n "$TS_FORMAT" ]; then
     eval "$TS_FORMAT" 2>&1
 else
     echo "SKIPPED — typescript.format not configured in verification.commands"
+    SKIPPED_CHECKS="${SKIPPED_CHECKS:+$SKIPPED_CHECKS, }typescript.format"
 fi
 
 if [ -n "$TS_TYPECHECK" ]; then
@@ -130,6 +137,7 @@ elif [ -n "$TS_BUILD" ]; then
     TS_EXIT=$?
 else
     echo "SKIPPED — typescript.typecheck and typescript.build not configured in verification.commands"
+    SKIPPED_CHECKS="${SKIPPED_CHECKS:+$SKIPPED_CHECKS, }typescript.typecheck/build"
     TS_EXIT=0
 fi
 ```
@@ -172,21 +180,30 @@ When changed files touch database engine configuration, flag for manual connecti
 ```bash
 cd {WORKTREE_PATH}
 DB_CONFIG_FILES=""
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$'); do
+# Process substitution (< <(...)), NOT a piped `| while read`, so DB_CONFIG_FILES
+# set inside the loop body survives past the loop (a piped while-read would run
+# in a subshell and silently discard the accumulator).
+while IFS= read -r f; do
+    [ -z "$f" ] && continue
     grep -qE "create_async_engine|AsyncSession|connect_args|pool_size|prepared_statement|engine_from_config|sessionmaker" "$f" 2>/dev/null && \
-        DB_CONFIG_FILES="$DB_CONFIG_FILES $f"
-done
+        DB_CONFIG_FILES="${DB_CONFIG_FILES}${f}"$'\n'
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$')
 
 if [ -n "$DB_CONFIG_FILES" ]; then
-    echo "DB CONFIG CHANGE DETECTED in:$DB_CONFIG_FILES"
+    echo "DB CONFIG CHANGE DETECTED in:"
+    echo "$DB_CONFIG_FILES"
     echo "ACTION: Verify database connectivity after deploy — changes to engine config, connect_args, or session factories can cause silent runtime failures."
     echo "RECOMMENDED: Run a minimal connectivity test (e.g., SELECT 1) through the modified session/engine path."
 
     # Check for lambda/callable in connect_args — the exact bug class from PR #14391
-    for f in $DB_CONFIG_FILES; do
+    # $DB_CONFIG_FILES is one path per line (built above) — herestring, not a
+    # piped `| while read`, so behavior stays consistent with the other fixes
+    # in this sweep even though no accumulator is set inside this particular loop.
+    while IFS= read -r f; do
+        [ -z "$f" ] && continue
         grep -nE "lambda.*:.*['\"]|=lambda" "$f" 2>/dev/null | grep -iE "connect_args|prepared_statement|pool|engine" && \
             echo "WARNING: Lambda/callable in database configuration in $f — verify callback signature matches library's expected calling convention"
-    done
+    done <<< "$DB_CONFIG_FILES"
 fi
 ```
 
@@ -234,7 +251,7 @@ After the gate passes, commit all staged changes in a single commit. This includ
 ```bash
 cd {WORKTREE_PATH}
 git add -u
-git commit -m "fix({SCOPE}): {description} (#NUMBER)"
+git commit -s -m "fix({SCOPE}): {description} (#NUMBER)"
 ```
 
 Where `{SCOPE}` is the command or module scope from the contract (e.g. `work-on`, `quality-gate`), and `{description}` summarises the implementation. Use the commit convention from the contract:
@@ -278,6 +295,32 @@ If `origin/{PR_BASE}` does not exist yet (new branch), skip this check — no co
 git ls-remote --exit-code origin {PR_BASE} >/dev/null 2>&1 || echo "PR_BASE not on origin — skipping ancestry audit"
 ```
 
+### V5 Post-Commit: Mark Build Complete (MANDATORY)
+
+After the ancestry audit passes (or is skipped), append `<!-- FORGE:BUILDER:COMPLETE -->` to the existing FORGE:BUILDER comment. This is the **only** place this marker is written — it signals that a real commit exists on the branch and the build is safe to resume-skip. <!-- Added: forge#1305 -->
+
+```bash
+# Find the FORGE:BUILDER comment posted by implement.md Phase I6
+BUILDER_COMMENT_ID=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '[.[] | select(.body | contains("FORGE:BUILDER") and (contains("FORGE:BUILDER:COMPLETE") | not))] | last | .id // ""')
+
+if [ -n "$BUILDER_COMMENT_ID" ]; then
+  # Fetch current body and append the completion marker
+  CURRENT_BODY=$(gh api repos/{GH_REPO}/issues/comments/$BUILDER_COMMENT_ID --jq '.body')
+  UPDATED_BODY="${CURRENT_BODY}
+
+<!-- FORGE:BUILDER:COMPLETE -->"
+  gh api repos/{GH_REPO}/issues/comments/$BUILDER_COMMENT_ID \
+    -X PATCH \
+    --field body="$UPDATED_BODY"
+  echo "FORGE:BUILDER:COMPLETE appended to comment $BUILDER_COMMENT_ID"
+else
+  echo "WARNING: FORGE:BUILDER comment not found or already marked complete — skipping BUILDER:COMPLETE append"
+fi
+```
+
+**Why here and not in implement.md**: The commit (`git commit`) runs in this phase (V5). Appending `:COMPLETE` after the commit ensures that a session crash between implement.md I6 (comment posted) and this step (commit) leaves a partial BUILDER comment without `:COMPLETE`. The next resume will detect the partial comment, delete it, and restart the build. See `implement.md § Phase I1 resume check`.
+
 ---
 
 ## Output
@@ -293,6 +336,9 @@ VALIDATE_RESULT:
   deploy_completeness_fixes: [{VAR_NAME: location_added}, ...]
   commits_added: [{SHA}, ...]  # from V5 if any
   blocker: {description if gate_passed=false}
+  verification_skipped: []  # empty when all configured checks ran; list of skipped check names otherwise
+                            # e.g. ["python.format", "typescript.typecheck/build"]
+                            # populated from SKIPPED_CHECKS in Phase V2
 ```
 
 ---

package/commands/work-on/build.md

@@ -9,8 +9,8 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--base PR_BA
 
 **Input**: $ARGUMENTS
 
-**Invoked by**: `work-on.md` state 8 (READY_TO_BUILD).
-**Output**: Create worktree, post contract, sequence build subcommands, return result to router.
+**Invoked by**: `work-on.md` Phase 3 — entered when the issue carries label `workflow:ready-to-build` or `workflow:building` (see Universal Phase Dispatcher in work-on.md).
+**Output**: Create worktree, post contract, sequence build subcommands, return result to work-on.md.
 
 **Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
 **NEVER use plan mode (EnterPlanMode).**
@@ -46,7 +46,16 @@ gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
 ```
 
 **Resume check**:
-- If `<!-- FORGE:BUILDER -->` comment exists → build already complete. Return `BUILD_RESULT: status: ALREADY_DONE` to router.
+- If `<!-- FORGE:BUILDER:COMPLETE -->` is present in a BUILDER comment → build already complete. Return `BUILD_RESULT: status: ALREADY_DONE` to router.
+- If `<!-- FORGE:BUILDER -->` exists BUT `<!-- FORGE:BUILDER:COMPLETE -->` is ABSENT → build was interrupted after the comment was posted but before the commit (validate.md V5). Delete the partial comment and restart from Phase B2 (contract): <!-- Added: forge#1305 -->
+  ```bash
+  PARTIAL_ID=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+    --jq '[.[] | select(.body | contains("FORGE:BUILDER") and (contains("FORGE:BUILDER:COMPLETE") | not))] | last | .id // ""')
+  if [ -n "$PARTIAL_ID" ]; then
+    gh api repos/{GH_REPO}/issues/comments/$PARTIAL_ID -X DELETE
+    echo "Deleted partial FORGE:BUILDER comment (no FORGE:BUILDER:COMPLETE) — restarting build from Phase B2"
+  fi
+  ```
 - If no `<!-- FORGE:INVESTIGATOR -->` comment with `<!-- INVESTIGATION:COMPLETE -->` → EXIT with `BUILD_RESULT: status: BLOCKED`, blocker: "Investigation not complete — run investigate first".
 
 Extract from investigation report:
@@ -82,6 +91,14 @@ Append `-{NUMBER}` to ensure uniqueness: e.g. `fix/work-on-build-landing-file-85
 
 - Review-finding issue → parse `**Code branch**: \`{branch}\`` from issue body; branch from `origin/{branch}`
   - **Milestone review-finding hybrid lane** (ONLY when Code branch matches `milestone/*`): This is a high-risk lane. The worktree will carry the full milestone history. The PR target is `staging` (or the base specified). **DANGER: Agents MUST NOT use `git merge` to resolve any conflicts in this lane.** Merge-based conflict resolution will pull the entire milestone commit tree onto staging, contaminating it with unapproved code. Use `git rebase` or `git cherry-pick` only. If conflicts cannot be resolved without a merge, post a comment on the issue, add `needs-human`, and STOP.
+  - **Missing ref fallback**: After parsing, verify the Code branch still exists on remote. If not, fall back to the lane default (`staging` for fast lane, `milestone/{slug}` for feature lane) and note the fallback:
+    ```bash
+    SOURCE_BRANCH="{CODE_BRANCH_FROM_ISSUE_BODY}"
+    if ! git ls-remote --exit-code origin "$SOURCE_BRANCH" >/dev/null 2>&1; then
+      echo "WARNING: Code branch '$SOURCE_BRANCH' not found on remote — falling back to lane default '$PR_BASE'"
+      SOURCE_BRANCH="$PR_BASE"
+    fi
+    ```
 - Feature lane (has milestone) → branch from `origin/{PR_BASE}`
 - Fast lane (no milestone) → branch from `origin/staging`
 
@@ -275,13 +292,14 @@ BUILD_RESULT:
 
 ## Integration Point in work-on.md
 
-This module runs at **state 8 (READY_TO_BUILD)** in the routing loop:
+This module runs during **Phase 3** of the work-on.md pipeline (label: `workflow:ready-to-build` or `workflow:building`). The full sequence is defined by the Universal Phase Dispatcher in work-on.md:
 
 ```
-state 8 → [THIS MODULE] worktree + contract + context + architect + implement + validate
-        → BUILD_RESULT: COMPLETE
-states 7, 6 → work-on:review (push + PR + /review-pr --auto-merge)
-states 5, 4 → work-on:close (trajectory + parent tracker + summary)
+Phase 3 (Build)   → [THIS MODULE] worktree + contract + context + architect + implement + validate
+                  → posts FORGE:BUILDER comment, writes FORGE:CHECKPOINT next_phase=REVIEW
+Phase 4 (PR)      → work-on:review — push branch, create PR, set workflow:in-review
+Phase 5 (Review)  → work-on:review — invoke /review-pr --auto-merge
+Phase 6 (Close)   → work-on:close — trajectory + parent tracker + summary + worktree cleanup
 ```
 
-The router re-reads GitHub state after this module returns COMPLETE — it will then detect state 6 (IN_REVIEW) or 7 (BUILD_NO_PR) and invoke `work-on:review`.
+After this module posts `FORGE:BUILDER` and returns, work-on.md's Universal continuation rule re-reads the issue labels. Since the label is not yet terminal (`workflow:merged` / `workflow:invalid` / `needs-human`), it proceeds immediately to Phase 4 (PR Creation) and then Phase 5 (Auto-Review).

package/commands/work-on/close.md

@@ -179,7 +179,7 @@ ISSUE_STATE=$(gh issue view {NUMBER} {GH_FLAG} --json state --jq '.state')
 
 **If `REMAINING_AFTER > 0`** (multi-phase: uncompleted phases remain):
 ```bash
-# Post phase-complete marker — router state 10 (MULTI_PHASE) will re-detect this issue
+# Post phase-complete marker — work-on.md's Universal continuation rule will re-read labels and continue to the next phase
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:PHASE:COMPLETE -->
 Phase complete. PR #{PR_NUMBER} merged to \`{PR_BASE}\`. ${REMAINING_AFTER} phase item(s) remain — leaving issue open for next pipeline iteration."
 
@@ -279,6 +279,125 @@ Output to stdout (returned to calling agent):
 
 ---
 
+## Phase C4.5: Pipeline Summary Card (MANDATORY)
+
+The shareable artifact. After the close completes, render a box-drawing summary card to
+stdout (terminal screenshot moment) AND compute a machine-readable twin that Phase C5
+embeds in the `FORGE:TRAJECTORY` comment for platform consumption.
+
+**All stats are real — pulled from `gh`/`git`. Every lookup degrades gracefully: a missing
+value renders as `—` and NEVER aborts the card. Do NOT fabricate stats.**
+
+### C4.5a: Gather real stats
+
+```bash
+# Commit / diff stats from the merged PR (single API call). Fallbacks to "—" if absent.
+PR_STATS=$(gh pr view {PR_NUMBER} {GH_FLAG} --json commits,additions,deletions,baseRefName,isDraft 2>/dev/null)
+COMMITS=$(echo "$PR_STATS"   | jq -r '(.commits | length) // empty' 2>/dev/null); COMMITS=${COMMITS:-—}
+ADDITIONS=$(echo "$PR_STATS" | jq -r '.additions // empty' 2>/dev/null); ADDITIONS=${ADDITIONS:-—}
+DELETIONS=$(echo "$PR_STATS" | jq -r '.deletions // empty' 2>/dev/null); DELETIONS=${DELETIONS:-—}
+PR_TARGET=$(echo "$PR_STATS" | jq -r '.baseRefName // empty' 2>/dev/null); PR_TARGET=${PR_TARGET:-{PR_BASE}}
+IS_DRAFT=$(echo "$PR_STATS"  | jq -r '.isDraft // false' 2>/dev/null)
+
+# Review summary — count domain-agent verdicts posted by /review-pr on the PR.
+REVIEW_BODIES=$(gh pr view {PR_NUMBER} {GH_FLAG} --json reviews,comments \
+  --jq '[.reviews[].body // ""] + [.comments[].body // ""] | .[]' 2>/dev/null)
+# NOTE: `grep -c` already prints `0` on no match (and exits non-zero) — do NOT add
+# `|| echo 0`, which would append a second line ("0\n0") and break the arithmetic
+# and `--argjson` below. Swallow the non-zero exit with `|| true`, then default.
+APPROVED=$(echo "$REVIEW_BODIES" | grep -cE 'APPROVED:' 2>/dev/null || true); APPROVED=${APPROVED:-0}
+CHANGES=$(echo  "$REVIEW_BODIES" | grep -cE 'CHANGES REQUESTED:' 2>/dev/null || true); CHANGES=${CHANGES:-0}
+TOTAL_AGENTS=$((APPROVED + CHANGES))
+# Blockers = review-finding issues created by this PR that are still open (best-effort).
+BLOCKERS=$(echo "$REVIEW_BODIES" | grep -ciE 'blocker|merge.?block' 2>/dev/null || true); BLOCKERS=${BLOCKERS:-0}
+if [ "$TOTAL_AGENTS" -gt 0 ]; then
+  REVIEW_SUMMARY="${APPROVED}/${TOTAL_AGENTS} agents passed, ${BLOCKERS} blockers"
+else
+  REVIEW_SUMMARY="—"   # review data unavailable (e.g. review skipped)
+fi
+
+# Elapsed wall-clock: first FORGE agent comment → now.
+FIRST_TS=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '[.[] | select(.body | contains("FORGE:")) | .created_at] | sort | .[0] // empty' 2>/dev/null)
+if [ -n "$FIRST_TS" ]; then
+  START_EPOCH=$(date -u -d "$FIRST_TS" +%s 2>/dev/null \
+    || python3 -c "import sys,datetime; ts=sys.argv[1].rstrip('Z'); print(int(datetime.datetime.fromisoformat(ts+'+00:00').timestamp()))" "$FIRST_TS" 2>/dev/null \
+    || echo "")
+  NOW_EPOCH=$(date -u +%s)
+  if [ -n "$START_EPOCH" ]; then
+    ELAPSED_SECS=$((NOW_EPOCH - START_EPOCH))
+    ELAPSED=$(printf '%dm %02ds' $((ELAPSED_SECS / 60)) $((ELAPSED_SECS % 60)))
+  else ELAPSED="—"; ELAPSED_SECS=0; fi
+else ELAPSED="—"; ELAPSED_SECS=0; fi
+
+# Pipeline line + status — reflect the ACTUAL terminal state.
+#   merged    → investigate → architect → build → review → merge ✓
+#   decomposed→ investigate → decompose ⏹ (sub-issues spawned)
+#   invalid   → investigate → invalid ✗
+#   blocked   → investigate → … → blocked ⚠ (needs-human)
+#   draft PR  → append "(draft)" to the merge segment
+case "{TERMINAL_STATE}" in
+  decomposed) PIPELINE_LINE="investigate → decompose ⏹"; CARD_STATUS="decomposed" ;;
+  invalid)    PIPELINE_LINE="investigate → invalid ✗";   CARD_STATUS="invalid" ;;
+  blocked)    PIPELINE_LINE="investigate → build → blocked ⚠"; CARD_STATUS="blocked" ;;
+  *)          PIPELINE_LINE="investigate → architect → build → review → merge ✓"; CARD_STATUS="merged" ;;
+esac
+[ "$IS_DRAFT" = "true" ] && PIPELINE_LINE="${PIPELINE_LINE} (draft)"
+```
+
+### C4.5b: Render the card to stdout
+
+Print the card to stdout (the calling agent surfaces it in the terminal). Card inner
+width is **51** columns. Truncate the title with an ellipsis (`…`) if `#{NUMBER} — {TITLE}`
+exceeds the field; pad shorter lines with spaces so the right border `║` stays aligned.
+
+```
+╔═══════════════════════════════════════════════════╗
+║  ForgeDock Pipeline Complete                      ║
+╠═══════════════════════════════════════════════════╣
+║                                                   ║
+║  Issue:    #{NUMBER} — {TITLE}                    ║
+║  Pipeline: {PIPELINE_LINE}                        ║
+║  Commits:  {COMMITS} ({ADDITIONS} additions, {DELETIONS} deletions) ║
+║  PR:       #{PR_NUMBER} (merged to {PR_TARGET})   ║
+║  Review:   {REVIEW_SUMMARY}                       ║
+║  Time:     {ELAPSED}                              ║
+║                                                   ║
+╚═══════════════════════════════════════════════════╝
+```
+
+**Edge-case rendering**:
+- Decomposed: title line stays; `Pipeline:` shows `investigate → decompose ⏹`; `PR:`, `Review:`, `Commits:` render `—`; the header reads `ForgeDock Pipeline — Decomposed`.
+- Invalid: header `ForgeDock Pipeline — Closed (invalid)`; `Pipeline:` shows `investigate → invalid ✗`; downstream stats `—`.
+- Blocked / needs-human: header `ForgeDock Pipeline — Blocked`; `Review:`/`PR:` reflect last known state; remaining stats `—`.
+- Draft PR: `PR:` line appends `(draft)` and the merge segment is not marked `✓`.
+
+### C4.5c: Build the machine-readable twin
+
+Assemble the JSON object below (used verbatim by Phase C5). Numeric stats that were `—`
+become `null` in JSON; never emit `"—"` as a number.
+
+```bash
+CARD_JSON=$(jq -nc \
+  --argjson issue {NUMBER} \
+  --arg title "{TITLE}" \
+  --arg status "$CARD_STATUS" \
+  --arg pipeline "$PIPELINE_LINE" \
+  --arg pr "{PR_NUMBER}" \
+  --arg target "$PR_TARGET" \
+  --arg commits "$COMMITS" --arg adds "$ADDITIONS" --arg dels "$DELETIONS" \
+  --arg review "$REVIEW_SUMMARY" --argjson blockers "${BLOCKERS:-0}" \
+  --argjson elapsed "${ELAPSED_SECS:-0}" \
+  '{issue:$issue, title:$title, status:$status, pipeline:$pipeline,
+    pr:($pr|tonumber? // null), pr_target:$target,
+    commits:($commits|tonumber? // null),
+    additions:($adds|tonumber? // null),
+    deletions:($dels|tonumber? // null),
+    review:$review, blockers:$blockers, elapsed_seconds:$elapsed}')
+```
+
+---
+
 ## Phase C5: Trajectory Log (MANDATORY)
 
 Post the `<!-- FORGE:TRAJECTORY -->` comment as the final pipeline record:
@@ -305,9 +424,18 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:TRAJECTORY -->
 
 **Anomalies**: None
 
-**Pipeline completed**: {TIMESTAMP}"
+**Pipeline completed**: {TIMESTAMP}
+
+<!-- FORGE:CARD ${CARD_JSON} -->"
 ```
 
+The `<!-- FORGE:CARD {...} -->` block carries the machine-readable summary computed in
+Phase C4.5c. It is wrapped in an HTML comment so it stays hidden in GitHub's rendered view
+(keeping the trajectory comment clean) while remaining greppable in the raw body for platform
+consumption — `/orchestrate` reads it to build per-issue cards. This block is **additive**:
+all existing `FORGE:TRAJECTORY` consumers select via `contains("FORGE:TRAJECTORY")` and parse
+the markdown table, so the embedded JSON does not affect them.
+
 Where:
 - `{PARENT_STATUS}` = `⏭ Skipped` (if no parent) or `✅ Complete` (if parent updated)
 - `{PARENT_NOTES}` = `No parent tracker` or `Checked off in #{PARENT_REF}`
@@ -449,7 +577,7 @@ CLOSE_RESULT:
   parent_closed: {true|false}
 ```
 
-Where `PHASE_COMPLETE` means the current phase was closed but uncompleted phases remain — the issue is left OPEN for the router to re-evaluate on the next pipeline iteration (state 10, MULTI_PHASE).
+Where `PHASE_COMPLETE` means the current phase was closed but uncompleted phases remain — the issue is left OPEN for work-on.md to re-evaluate on the next invocation (via Universal continuation rule: re-read labels, check terminal state, continue to next phase).
 
 ---
 

package/commands/work-on/investigate.md

@@ -72,13 +72,30 @@ If the issue specifies a **Code branch** (`**Code branch**: \`{branch}\``), chec
 1. **Check the right branch** — read from the branch specified in the issue body (`**Code branch**: \`{branch}\``) if present
 2. **Read domain files** — start with the key files for the affected domain
 3. **Verify claims** — does the code actually have the problem described?
-4. **Git blame** — trace when/why the relevant code was written
+4. **Git blame** — trace when/why the relevant code was written. Run bounded, local commands (no network round-trip):
+   ```bash
+   # Introducing commit for each affected file (first commit that added it)
+   git log --reverse --format='%h %an %ad %s' --date=short -- {affected_file} | head -1
+   # Last-touch commit (most recent change)
+   git log -1 --format='%h %an %ad %s' --date=short -- {affected_file}
+   # Line-level blame for a specific suspect hunk, if the issue names one
+   git blame -L {start},{end} -- {affected_file}
+   ```
+   Record the introducing commit and last-touch commit for each primary affected file — this feeds the mandatory **History findings** field in Phase 1C.
 5. **Domain context discovery** (narrow scope only, 1–5 files):
    ```bash
    git log --oneline --all -30 -- {affected_files} | grep -oP '#\d+' | sort -u
    gh issue list -R {GH_REPO} --state closed --limit 8 --search "{function_name}"
    ```
    Keep only file/function-level overlap. Max 5 related issues. Everything is a hint to verify, not a fact.
+
+   **Pickaxe pass (prior fix / regression detection)** — bounded to one pass, capped at 5 hits: search for prior additions/removals of the suspected symbol or literal string named in the issue (a function name, error string, or config key), independent of whether that fix was ever linked to a filed issue:
+   ```bash
+   git log -S"{suspected_symbol_or_string}" --oneline -- {affected_files} | head -5
+   # Use -G instead of -S when the target is a regex pattern rather than a literal string
+   git log -G"{pattern}" --oneline -- {affected_files} | head -5
+   ```
+   Any hit here is a candidate prior fix or reintroduced defect — read the commit body (`git show {hash}`) to confirm before citing it. Feed confirmed hits into the History findings field and let them inform the verdict (e.g. a defect being reintroduced raises severity).
 6. **Determine root cause** — what's actually broken or missing?
 7. **Identify affected files** — full list of files that need changes
 8. **Fix-approach validation** — if the issue proposes a fix, don't adopt it as spec. Trace through the target system's middleware, auth, routing, config. Cross-domain: if fix in domain A interacts with domain B, read domain B's files too.
@@ -113,6 +130,12 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:INVESTIGATOR -->
 ### Evidence
 {specific findings — function names, line numbers, behavior observed}
 
+### History Findings
+**Introducing commit**: {hash — author — date — subject, per primary affected file}
+**Last touched**: {hash — author — date — subject}
+**Pickaxe hits (prior fixes / regressions)**: {commit(s) found via \`git log -S\`/\`-G\`, or 'None found' — max 5}
+{This field is MANDATORY — populate from the git blame + pickaxe commands in step 4/5. If a file is newly created (no history), write 'New file — no history.'}
+
 ### Recommendation
 {what to build/fix, concrete and actionable}