forgedock 1.0.21 → 1.1.1

package/commands/work-on/review.md

@@ -81,6 +81,30 @@ Do NOT push this branch. Human review required to identify the source of the mer
 fi
 ```
 
+## Phase R1: Non-Empty Commit Guard (MANDATORY — run before push) <!-- Added: forge#1305 -->
+
+Before pushing, verify the branch has at least one commit ahead of the PR base. This is the last-line defense against the phantom-commit hazard: a session that resumed from a partial FORGE:BUILDER comment (without `:COMPLETE`) would have skipped the commit step and could otherwise push an empty branch.
+
+```bash
+cd {WORKTREE_PATH}
+# Count commits on this branch that are not reachable from origin/{PR_BASE}
+COMMIT_COUNT=$(git rev-list --count HEAD ^origin/{PR_BASE} 2>/dev/null || echo "0")
+if [ "$COMMIT_COUNT" -eq 0 ]; then
+  gh issue comment {NUMBER} {GH_FLAG} --body "## Push Blocked — No Commits Ahead of Base
+
+Branch \`{BRANCH}\` has 0 commits ahead of \`origin/{PR_BASE}\`. Pushing this branch would create an empty PR.
+
+**Likely cause**: Build was interrupted after the FORGE:BUILDER comment was posted (implement.md Phase I6) but before the commit was created (validate.md Phase V5). The branch was pushed with no implementation on it.
+
+**Resolution**: Delete this branch, re-run \`/work-on {NUMBER}\` to restart the build phase. The partial FORGE:BUILDER comment (lacking \`FORGE:BUILDER:COMPLETE\`) will be detected and deleted, and the build will restart cleanly.
+
+<!-- FORGE:PUSH_BLOCKED_EMPTY_BRANCH -->"
+  gh issue edit {NUMBER} {GH_FLAG} --add-label "needs-human"
+  exit 1
+fi
+echo "Commit count ahead of origin/{PR_BASE}: $COMMIT_COUNT — OK to push"
+```
+
 ## Phase R1: Push Branch
 
 ```bash

package/commands/work-on-monolithic.md

@@ -1,6 +1,7 @@
 ---
 description: "[BENCHMARK] Monolithic work-on — single-prompt pipeline with no Skill sub-phase boundaries"
 argument-hint: [issue number]
+install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

package/commands/work-on.md

@@ -96,6 +96,74 @@ Satellite repos (those without a `staging` branch) receive fast-lane PRs directl
 
 ## Phase 0: Resolve Issue & Load Context
 
+### 0.0: Pre-Flight Checks (MANDATORY — run before any other Phase 0 step)
+
+Validate the environment before the pipeline spends tokens. Each check fails fast with an actionable error and a pointer to the troubleshooting guide (`docs/site/troubleshooting.md`). Run all checks; report every failure, then STOP if any HARD check fails. <!-- Added: forge#1149 -->
+
+```bash
+PREFLIGHT_FAILED=0
+
+# Check 1 — forge.yaml present (HARD)
+if [ ! -f forge.yaml ]; then
+  echo "ERROR: forge.yaml not found in the repository root."
+  echo "  Fix: run \`npx forgedock init\` to generate one, or copy forge.yaml.example."
+  echo "  See: docs/site/troubleshooting.md#1-forgeyaml-not-found"
+  PREFLIGHT_FAILED=1
+fi
+
+# Check 2 — yq installed; forge.yaml is valid YAML (HARD, only if present)
+if [ -f forge.yaml ]; then
+  if ! command -v yq >/dev/null 2>&1; then
+    echo "ERROR: yq is not installed. The pipeline requires yq to parse forge.yaml."
+    echo "  Fix: install yq — https://github.com/mikefarah/yq#install"
+    echo "  See: docs/site/troubleshooting.md#2-forgeyaml-has-a-syntax-error"
+    PREFLIGHT_FAILED=1
+  elif ! yq '.' forge.yaml >/dev/null 2>&1; then
+    echo "ERROR: forge.yaml has a YAML syntax error."
+    echo "  Fix: run \`yq '.' forge.yaml\` to locate the offending line, then correct the indentation/quoting."
+    echo "  See: docs/site/troubleshooting.md#2-forgeyaml-has-a-syntax-error"
+    PREFLIGHT_FAILED=1
+  fi
+fi
+
+# Check 3 — gh CLI authenticated (HARD)
+if ! gh auth status >/dev/null 2>&1; then
+  echo "ERROR: gh CLI is not authenticated. The pipeline cannot read or write GitHub state."
+  echo "  Fix: run \`gh auth login\` (ensure repo scope), then \`gh auth status\` to confirm."
+  echo "  See: docs/site/troubleshooting.md#3-gh-cli-not-authenticated"
+  PREFLIGHT_FAILED=1
+fi
+
+# Check 4 — workflow labels exist on the repo (SOFT — warn, auto-recoverable)
+if [ -f forge.yaml ] && gh auth status >/dev/null 2>&1; then
+  GH_REPO_PF="$(yq -r '.project.owner + "/" + .project.repo' forge.yaml 2>/dev/null)"
+  if [ -n "$GH_REPO_PF" ] && ! gh label list -R "$GH_REPO_PF" --search "workflow:" 2>/dev/null | grep -q "workflow:"; then
+    echo "WARNING: ForgeDock workflow:* labels not found on $GH_REPO_PF."
+    echo "  Fix: run \`npx forgedock labels setup\` (or \`--repo $GH_REPO_PF\`) to bootstrap them."
+    echo "  See: docs/site/troubleshooting.md#9-missing-workflow-labels"
+  fi
+fi
+
+# Check 5 — GitHub API rate limit headroom (SOFT — warn)
+if gh auth status >/dev/null 2>&1; then
+  RL_REMAINING="$(gh api rate_limit --jq '.resources.core.remaining' 2>/dev/null || echo '')"
+  if [ -n "$RL_REMAINING" ] && [ "$RL_REMAINING" -lt 100 ] 2>/dev/null; then
+    RL_RESET="$(gh api rate_limit --jq '.resources.core.reset' 2>/dev/null)"
+    echo "WARNING: GitHub API rate limit low ($RL_REMAINING remaining; resets at epoch $RL_RESET)."
+    echo "  Fix: wait for the reset, reduce orchestration parallelism, or use a higher-limit PAT."
+    echo "  See: docs/site/troubleshooting.md#10-github-api-rate-limit-exceeded"
+  fi
+fi
+
+if [ "$PREFLIGHT_FAILED" -eq 1 ]; then
+  echo "Pre-flight checks failed. Resolve the errors above and re-run /work-on {NUMBER}."
+  echo "Full recovery guide: docs/site/troubleshooting.md"
+  exit 1
+fi
+```
+
+Worktree/branch-already-exists and stale-label conditions are surfaced later (Phase 3E worktree creation and the `## Error Handling` section) with their own recovery guidance in `docs/site/troubleshooting.md`.
+
 ### 0A: Parse input
 Extract project prefix and issue number. If `next`/`pick`: list open issues sorted by priority, skip `needs-human` and `workflow:decomposed`, pick highest priority.
 
@@ -424,7 +492,16 @@ Use `forge.yaml → review.tech_stack` and the issue domain labels to identify e
    grep -rn '\.field_name\s*=' services/   # Attribute assignments
    ```
    If the field is written with different types in different code paths (e.g. dict in the standard path, string in the auth-gated path), document ALL variants. The fix must handle every variant — not just the one on the primary investigated code path. A type guard like `or {}` only protects against falsy values; a non-empty string is truthy and bypasses it.
-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.
 4.5. **Rogue commit pre-state comparison (conditional)**: If the issue body references a specific commit as rogue, bad, or unintended (e.g., "rogue commit `abc1234`", "bad commit", "this was never intended"), MUST run `git show {commit}^:{file}` to see the file before that commit. Compare the pre-commit state against the current file. Any block present in the current file but absent in the pre-commit state was introduced by that commit chain and is a candidate for full reversion — not just partial editing. Report the delta (pre vs. current) in the investigation report. Do NOT assume surrounding code near a named import/bug is correct simply because the issue only named a specific sub-problem. (Ref: forge#278 — investigator confirmed the broken import but never ran `git show 18a3a2cf3^:batch.py`; the surrounding 50-line feature gate was also rogue and was preserved by the fix PR, causing a P1 access regression for all non-Scale users)
 5. Domain context discovery (narrow scope only, 1–5 files):
    ```bash
@@ -432,6 +509,14 @@ Use `forge.yaml → review.tech_stack` and the issue domain labels to identify e
    gh issue list -R {GH_REPO} --state closed --limit 8 --search "{function_name}"
    ```
    Keep only file/function-level overlap. Max 5 related issues.
+
+   **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, 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
 7. Identify affected files — full list of files that need changes
 7.5. **Sibling Pattern Sweep** *(conditional — when the bug is a condition, gated function call, or field presence check)*: After identifying the affected files, grep for the same pattern in sibling files within the same directory. The issue spec may name only the file where the error was first observed — but the same commit or PR that introduced the bug often applied it uniformly across related handlers.
@@ -475,6 +560,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}
 
@@ -744,7 +835,17 @@ esac
 
 <!-- FORGE:PHASE_COMPLETE — Entering Phase 3 (Build). See Universal Phase Dispatcher: sub-phases 3A–3M execute in sequence. No sub-phase completion is terminal. -->
 
-**Skip if**: `<!-- FORGE:BUILDER -->` exists.
+**Skip if**: `<!-- FORGE:BUILDER:COMPLETE -->` is present in a BUILDER comment. <!-- Added: forge#1305 — require completion marker, not mere presence of BUILDER annotation -->
+
+**Partial build detection**: If `<!-- FORGE:BUILDER -->` exists BUT `<!-- FORGE:BUILDER:COMPLETE -->` is ABSENT → the build was interrupted after implement.md Phase I6 (comment posted) but before validate.md Phase V5 (commit). Delete the partial comment and restart Phase 3 from the top: <!-- 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"
+fi
+```
 
 **CRITICAL: You MUST execute ALL sub-phases 3A–3M in order. Sub-phases 3C.5 (context) and 3C.6 (architect) are skipped ONLY for TRIVIAL tasks and Investigation tasks — see Phase 3B for classification. For STANDARD and COMPLEX tasks they post mandatory `FORGE:CONTEXT` and `FORGE:ARCHITECT` comments that Phase 3F reads as its primary input. Skipping them without a TRIVIAL/Investigation classification degrades build quality and causes review findings. After each sub-phase, continue to the next — no sub-phase is terminal.**
 
@@ -766,9 +867,9 @@ gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,milestone
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
   --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body'
 
-# Check if build already completed
+# Check if build already completed (require FORGE:BUILDER:COMPLETE — not just FORGE:BUILDER)
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | contains("FORGE:BUILDER")) | .body'
+  --jq '.[] | select(.body | contains("FORGE:BUILDER:COMPLETE")) | .body'
 
 # Check for existing COMPLEXITY_BAND from a prior run (resume path)
 EXISTING_FAST_PATH=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
@@ -889,7 +990,12 @@ Run these queries (20s timeout each, 2 min total budget):
 
 **C1: Past Review Findings on These Files**
 ```bash
-for file in {AFFECTED_FILES}; do
+# {AFFECTED_FILES} is a space-separated argument (see --files contract) — 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 --label "review-finding" \
     --search "$basename" --limit 10 \
@@ -908,6 +1014,20 @@ git log --oneline -30 -- {AFFECTED_FILES} | grep -oE '#[0-9]+' | sort -u | head
 # For each issue: fetch title + root cause, keep only bug/fix/review-finding labeled. Max 5.
 ```
 
+**Direct commit-body read (bounded, prefer over `gh api` when it already answers "why")**: read the top 5 commit subjects+bodies on the affected files directly — local git is near-free relative to `gh api` round-trips, and commit bodies often explain the "why" without needing to fetch a linked issue at all:
+```bash
+git log -5 --format='%h %ad %s%n%b' --date=short -- {AFFECTED_FILES}
+```
+If a commit body fully explains a 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).
+
 **C3: Related Code Paths** (callers/importers of FUNCTION_NAMES)
 ```bash
 for fn in {FUNCTION_NAMES}; do
@@ -934,7 +1054,8 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:CONTEXT -->
 {past review-finding issues}
 
 ### Past Bugs in This Module
-{closed bug issues from git log mining}
+{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)}
 
 ### Related Code Paths (must stay consistent)
 {files that import/call changed functions}
@@ -1070,6 +1191,14 @@ esac
 **Determine source branch**:
 - Review-finding → parse `**Code branch**: \`{branch}\`` from issue body; branch from `origin/{branch}`
   - **Milestone review-finding hybrid lane** (Code branch matches `milestone/*`): High-risk lane. NEVER use `git merge` to resolve conflicts — use `git rebase` or `git cherry-pick` only. If conflicts can't be resolved without merge, post comment, add `needs-human`, STOP.
+  - **Missing ref fallback**: After parsing, verify the Code branch still exists on remote. If not (e.g., the source PR's head branch was deleted post-merge before a corrected stamp took effect), fall back to `PR_BASE` (the lane default) 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 PR_BASE '$PR_BASE'"
+      SOURCE_BRANCH="$PR_BASE"
+    fi
+    ```
 - Feature lane (has milestone) → branch from `origin/{PR_BASE}` (PR_BASE now set above)
 - Fast lane (no milestone) → branch from `origin/{PR_BASE}` (PR_BASE = `{STAGING_BRANCH}`)
 
@@ -1178,6 +1307,11 @@ if iteration == max_iterations AND not PASS:
 
 All tool commands are read from `forge.yaml → verification.commands`. When a key is absent, the step logs `SKIPPED — not configured in verification.commands` and continues rather than silently passing.
 
+**Track skipped checks** — initialize before any check runs:
+```bash
+VERIFICATION_SKIPPED_CHECKS=""
+```
+
 **Python**:
 ```bash
 cd {WORKTREE_PATH}
@@ -1187,6 +1321,7 @@ if [ -n "$PYTHON_FORMAT" ]; then
     eval "$PYTHON_FORMAT" 2>&1
 else
     echo "SKIPPED — python.format not configured in verification.commands"
+    VERIFICATION_SKIPPED_CHECKS="${VERIFICATION_SKIPPED_CHECKS:+$VERIFICATION_SKIPPED_CHECKS, }python.format"
 fi
 
 # Compile check always runs (no config needed — catches syntax errors)
@@ -1206,6 +1341,7 @@ if [ -n "$TS_FORMAT" ]; then
     eval "$TS_FORMAT" 2>&1
 else
     echo "SKIPPED — typescript.format not configured in verification.commands"
+    VERIFICATION_SKIPPED_CHECKS="${VERIFICATION_SKIPPED_CHECKS:+$VERIFICATION_SKIPPED_CHECKS, }typescript.format"
 fi
 
 if [ -n "$TS_TYPECHECK" ]; then
@@ -1216,6 +1352,7 @@ elif [ -n "$TS_BUILD" ]; then
     TS_EXIT=$?
 else
     echo "SKIPPED — typescript.typecheck and typescript.build not configured in verification.commands"
+    VERIFICATION_SKIPPED_CHECKS="${VERIFICATION_SKIPPED_CHECKS:+$VERIFICATION_SKIPPED_CHECKS, }typescript.typecheck/build"
     TS_EXIT=0
 fi
 ```
@@ -1257,10 +1394,11 @@ Skip if no changed Python files contain DB engine/session/pool patterns.
 
 ```bash
 cd {WORKTREE_PATH}
-for f in $(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$'); do
+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 && \
         echo "DB CONFIG CHANGE DETECTED in: $f"
-done
+done < <(echo {CHANGED_FILES} | tr ' ' '\n' | grep -E '\.py$')
 ```
 
 Advisory only — does not block build. Check for lambda/callable in connect_args (the exact bug class from PR #14391).
@@ -1335,7 +1473,7 @@ Stage all changes and commit:
 ```bash
 cd {WORKTREE_PATH}
 git add -u
-git commit -m "fix({SCOPE}): {description} (#{NUMBER})"
+git commit -s -m "fix({SCOPE}): {description} (#{NUMBER})"
 ```
 
 Conventional prefix: `fix`/`feat`/`refactor`/`docs`. Reference `#{NUMBER}` in message.
@@ -1356,12 +1494,20 @@ Check off completed items, mark phases complete, add PR references.
 
 ### 3M: Post implementation comment
 ```bash
+# Compute verification status from VERIFICATION_SKIPPED_CHECKS (set in Phase 3H)
+if [ -z "$VERIFICATION_SKIPPED_CHECKS" ]; then
+  VERIFICATION_STATUS="✅ All configured verification commands passed"
+else
+  VERIFICATION_STATUS="⚠ Verification NOT run: ${VERIFICATION_SKIPPED_CHECKS} — verification.commands not configured for these checks"
+fi
+
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:BUILDER -->
 ## Implementation Complete
 
 **Branch**: \`{BRANCH}\`
 **Commits**: {COMMIT_SHA(S)}
 **Files changed**: {COUNT}
+**Verification Status**: ${VERIFICATION_STATUS}
 
 ### Approach
 {what was built, key decisions}
@@ -1649,7 +1795,14 @@ fi
 
 ## Phase 7: Summary & Trajectory
 
-### 7A: Report
+### 7A: Report + Pipeline Summary Card
+
+Output the terse report, then render the shareable **Pipeline Summary Card** — the shareable
+moment a developer screenshots. Gather real stats (commits, additions/deletions, PR target,
+review summary, elapsed time) and render exactly as specified in `work-on/close.md` Phase C4.5
+(`C4.5a` stats gathering → `C4.5b` box-drawing card to stdout → `C4.5c` machine-readable twin).
+This inline path and the delegated `close.md` path MUST produce an identical card.
+
 ```
 ## Done: #{NUMBER} — {TITLE}
 - Investigation: {VERDICT} ({CONFIDENCE})
@@ -1658,6 +1811,98 @@ fi
 - Files changed: {COUNT}
 ```
 
+Then print the card to stdout (inner width 51; truncate long titles with `…`; missing stats
+render `—`; pipeline line reflects the actual terminal state — merged / decomposed / invalid /
+blocked; draft PRs append `(draft)`):
+
+```
+╔═══════════════════════════════════════════════════╗
+║  ForgeDock Pipeline Complete                      ║
+╠═══════════════════════════════════════════════════╣
+║                                                   ║
+║  Issue:    #{NUMBER} — {TITLE}                    ║
+║  Pipeline: investigate → architect → build →      ║
+║            review → merge ✓                       ║
+║  Commits:  {COMMITS} ({ADDITIONS} additions, {DELETIONS} deletions) ║
+║  PR:       #{PR_NUMBER} (merged to {PR_BASE})     ║
+║  Review:   {REVIEW_SUMMARY}                       ║
+║  Time:     {ELAPSED}                              ║
+║                                                   ║
+╚═══════════════════════════════════════════════════╝
+```
+
+**Gather real stats** (C4.5a — this block MUST run on the inline path to populate card variables;
+do NOT rely on the cross-reference to `close.md` alone):
+
+```bash
+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_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=$(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
+
+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
+
+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)"
+```
+
+**Build the machine-readable twin** (C4.5c — MUST run this block to assign `CARD_JSON` before
+Phase 7B embeds it; the cross-reference to `close.md` above is insufficient on the inline path): <!-- forge#1178 -->
+
+```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}')
+```
+
+`CARD_JSON` is now set and embedded in the trajectory comment by 7B.
+
 ### 7B: Trajectory Log (MANDATORY)
 
 **Review-presence check** (run before filling in Phase 4-5 row): <!-- Added: forge#381 -->
@@ -1676,6 +1921,13 @@ This check is **audit-only** — it annotates the trajectory for visibility. It
 Post `<!-- FORGE:TRAJECTORY -->` comment with phase-by-phase results table:
 
 ```bash
+# Compute verification row from VERIFICATION_SKIPPED_CHECKS (set in Phase 3H)
+if [ -z "$VERIFICATION_SKIPPED_CHECKS" ]; then
+  VERIFICATION_ROW="✅ Ran"
+else
+  VERIFICATION_ROW="⚠ Skipped — verification.commands not configured for: ${VERIFICATION_SKIPPED_CHECKS}"
+fi
+
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:TRAJECTORY -->
 ## Pipeline Trajectory — #{NUMBER}
 
@@ -1686,14 +1938,22 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:TRAJECTORY -->
 | Phase 2: Decomposition | ⏭ Skipped | {reason} |
 | Phase 3: Build | ✅ Complete | Branch: \`{BRANCH}\` |
 | Phase 3G: Quality Gate | ✅ Gate passed | {iterations} iterations |
+| Phase 3H: Verification | ${VERIFICATION_ROW} | |
 | Phase 4–5: Review + PR | {REVIEW_ROW} | PR #{PR_NUMBER} → \`{PR_BASE}\` |
 | Phase 6: Close | ✅ Complete | Issue closed |
 
 **Decisions**: {key decisions}
 **Anomalies**: {anomalies or None}
-**Pipeline completed**: {TIMESTAMP}"
+**Pipeline completed**: {TIMESTAMP}
+
+<!-- FORGE:CARD ${CARD_JSON} -->"
 ```
 
+Append the `<!-- FORGE:CARD {...} -->` block (machine-readable twin from 7A / close.md C4.5c)
+as the last line of the trajectory comment. It is HTML-comment-wrapped so it stays hidden in
+the rendered view but greppable for platform consumption (`/orchestrate` Phase 6 reads it for
+per-issue cards). Additive — does not affect existing `FORGE:TRAJECTORY` table consumers.
+
 ### 7C: Graph Decision Record (MANDATORY when PR exists)
 
 **Skip if**: `{PR_NUMBER}` is empty (investigation-only tasks with no PR) OR `<!-- FORGE:DECISION_RECORD -->` already posted on the PR.

package/docs/BRAND.md

@@ -6,7 +6,10 @@ Status of reserved and blocked brand handles across platforms.
 
 | Domain | Status |
 |--------|--------|
-| `forgedock.dev` | **Owned** — canonical marketing and App URL |
+| `forgedock.dev` | **Unverified** — live content (2026-07-04) is a third-party product unrelated to ForgeDock; registrar verification pending. Do not use as a public-facing link until resolved. |
+| `forgedock.io` | **Parked** — Porkbun parked page, HTTP-only (HTTPS does not connect). Not controlled by RapierCraft Studios. Do not use as a public-facing link. |
+
+> **Rule**: No public ForgeDock surface (npm homepage, repo description, plugin manifests, docs) may point at a domain until its live content is verified as controlled by RapierCraft Studios.
 
 ## npm
 
@@ -45,7 +48,8 @@ Social handle registration is an operational task. Reserve handles before public
 
 | Platform | Action |
 |----------|--------|
-| Domain | Done |
+| Domain (forgedock.dev) | Unverified — registrar check pending; do not use as live surface |
+| Domain (forgedock.io) | Parked — not controlled by RapierCraft Studios; do not use as live surface |
 | npm | Done |
 | GitHub org slug | Blocked — use variant for App slug |
 | Social handles | Reserve before L1 public launch |

package/docs/CONFIG.md

@@ -12,18 +12,26 @@ echo "forge.yaml" >> .gitignore  # if your credentials path is sensitive
 
 ---
 
-## CLI Flags for `init`
+## CLI Flags
 
-`npx forgedock init` accepts two optional flags that change how configuration is generated:
+`--verbose` and `--fast` apply to both `npx forgedock` (the full install journey) and `npx forgedock init` (config-only regeneration); `--manual` and `--minimal` apply to `init` only:
 
 | Flag | Behavior |
 |------|----------|
-| `--manual` | Skips AI autopilot enrichment entirely. Presents the annotated review screen with detection baseline values only (no AI-enriched suggestions). Detection still runs to provide defaults — you review and edit the raw inferred values on the same single-screen interface. |
-| `--verbose` | Surfaces each field's detection source and confidence rationale during the init flow. Helpful for understanding where ForgeDock inferred values from (e.g. `git remote`, `package.json`, `gh api`). |
+| `--manual` | `npx forgedock init` only. Skips the annotated review screen and asks plain, one-field-at-a-time prompts instead, pre-filled with the detected values as defaults. |
+| `--minimal` | `npx forgedock init` only. Skips detection enrichment and the review screen entirely, and writes a short `forge.yaml` containing only the three required sections (`project`, `paths`, `branches`) with detected values. |
+| `--verbose` | Shows each field's detection source and confidence rationale on the review screen (e.g. `git remote`, `package.json`, `gh api`), instead of only flagging low-confidence fields. |
+| `--fast` | Skips the animation/motion frames and jumps straight to the static screens. |
 
-The two flags can be combined: `npx forgedock init --manual --verbose` shows the annotated review screen with detection baseline values and field provenance at each entry.
+**Environment variables:**
 
-The default (`npx forgedock init` with no flags) remains the zero-question autopilot: AI enrichment fills in everything it can, and you review the result on a single annotated screen.
+| Variable | Behavior |
+|----------|----------|
+| `FORGE_NO_MOTION=1` | Same effect as `--fast` — disables animation frames. Color is unaffected. |
+| `NO_COLOR=1` | Disables ANSI color output only. Motion is unaffected (monochrome choreography). |
+| Non-TTY / piped output (or `CI=1`) | Plain sequential log: no color **and** no animation. |
+
+The default (no flags) is the annotated review screen: detection runs, AI enrichment fills in what it can (when an API key is available), and you review the result on a single screen — Enter accepts everything, low-confidence fields are flagged with a `# TODO(forgedock:<field>)` comment if left unedited.
 
 ---
 
@@ -686,46 +694,43 @@ Downstream consumers read `field.value` for the raw value and `field.confidence`
 
 ---
 
-## CLAUDE.md Integration
+## SessionStart Hook Integration
 
-ForgeDock can inject a managed usage block into your project's `CLAUDE.md` so every Claude Code session opened in the repo automatically knows that ForgeDock drives development here and which commands to use.
+ForgeDock does **not** write anything into your project's `CLAUDE.md` or `AGENTS.md`. Instead, `npx forgedock` registers a `SessionStart` hook in `~/.claude/settings.json` — a small script that runs at the start of every Claude Code session and prints ForgeDock's context straight to that session, without touching any file in your repo.
 
 ### How It Works
 
-Running `npx forgedock init` or `npx forgedock integrate` writes a marker-bounded block into `CLAUDE.md`:
-
-```
-<!-- BEGIN FORGEDOCK -->
-## ForgeDock — Autonomous Development Pipeline
-...command index and conventions...
-<!-- END FORGEDOCK -->
-```
+The hook resolves the current directory's state and reacts accordingly:
 
-The block is **idempotent** — re-running replaces only the managed section and leaves all other `CLAUDE.md` content untouched. If `CLAUDE.md` does not exist, it is created.
+| State | Behavior |
+|-------|----------|
+| `managed-active` (`forge.yaml` present, not opted out) | Prints a summary of `forge.yaml` (project, repo, branches) plus the available pipeline commands |
+| `managed-active`, no `forge.yaml` yet | Suggests running `npx forgedock init` |
+| `managed-optedout` | Completely silent — no output |
+| `unmanaged` | Prints a one-time, suppressible nudge to run `npx forgedock enable` |
 
-If `AGENTS.md` already exists in the project root, the same block is mirrored into it.
+The hook entry is registered idempotently: re-installing (`npx forgedock update`) will not duplicate it, and unrelated hooks or settings in `~/.claude/settings.json` are left untouched. If `settings.json` is malformed, the installer skips writing rather than risk corrupting it.
 
 ### Commands
 
 | Command | Action |
 |---------|--------|
-| `npx forgedock init` | Generates `forge.yaml` **and** injects the CLAUDE.md block |
-| `npx forgedock integrate` | Injects/refreshes the block without modifying `forge.yaml` |
+| `npx forgedock` / `npx forgedock install` | Registers the SessionStart hook (along with installing commands and writing `forge.yaml`) |
+| `npx forgedock update` | Re-registers the hook (relink only — does not touch `forge.yaml`) |
+| `npx forgedock uninstall` | Removes the hook entry from `settings.json` |
 
 ### Opting Out
 
-To prevent ForgeDock from managing the block, remove the `<!-- BEGIN FORGEDOCK -->` / `<!-- END FORGEDOCK -->` markers from `CLAUDE.md`. Without the markers, subsequent runs will append a new block rather than replacing one — so if you want to opt out permanently, delete or omit the markers **and** do not run `integrate` again.
-
-Alternatively, keep the markers but edit the content between them freely — ForgeDock will replace that section on the next run, so any manual edits inside the markers will be overwritten.
-
-### Re-generating
-
-The command index inside the block is auto-generated from the `description:` frontmatter in each `commands/*.md` file. To refresh it after a ForgeDock update:
+Per-directory, independent of the global hook registration. Each command acts on the current working directory — run it inside the project directory:
 
 ```bash
-npx forgedock integrate
+npx forgedock disable  # the current directory goes silent (managed-optedout)
+npx forgedock enable   # re-activate the current directory
+npx forgedock status   # show the current directory's resolved state
 ```
 
+See [Per-Directory State Registry](#per-directory-state-registry) below for how opt-out state is tracked.
+
 ---
 
 ## Per-Directory State Registry
@@ -788,22 +793,22 @@ If you downgrade to a build older than PR #467 **and** your project is accessed
 - The one-time "Enable ForgeDock here?" nudge may reappear once.
 - No data is lost. No crash. Fail-open behaviour holds throughout.
 
-**Recovery**: after downgrading, re-apply your opt-out with the older build:
+**Recovery**: after downgrading, re-apply your opt-out with the older build (run inside the project directory):
 
 ```bash
-npx forgedock disable [dir]
+npx forgedock disable
 ```
 
 This re-writes the entry under the key form the older build expects.
 
 ### Managing Opt-Out State
 
-Use the `forgedock enable` and `forgedock disable` commands to add or remove a directory from the opt-out set:
+Use the `forgedock enable` and `forgedock disable` commands to add or remove a directory from the opt-out set. Each command acts on the current working directory by default — run it inside the project directory, or pass an explicit path:
 
 ```bash
-npx forgedock enable [dir]   # Remove directory from opt-out set (default: cwd)
-npx forgedock disable [dir]  # Add directory to opt-out set (default: cwd)
-npx forgedock status [dir]   # Show resolved state for a directory
+npx forgedock enable [dir]   # Remove a directory from the opt-out set (default: cwd)
+npx forgedock disable [dir]  # Add a directory to the opt-out set (default: cwd)
+npx forgedock status [dir]   # Show a directory's resolved state (default: cwd)
 ```
 
 ---