forgedock 1.0.16 → 1.0.17

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

@@ -2,6 +2,8 @@
 description: Pre-implementation context gathering — surfaces historical findings, bug patterns, and related code paths before the builder writes any code
 argument-hint: [issue number] [affected_files...] [--functions function_names...]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # work-on/build/context — Pre-Implementation Context Gathering
 
@@ -11,6 +13,23 @@ argument-hint: [issue number] [affected_files...] [--functions function_names...
 
 ---
 
+## COMPLEXITY_BAND Guard (check BEFORE all phases)
+
+Read COMPLEXITY_BAND from the `<!-- FORGE:FAST_PATH -->` comment on the issue:
+
+```bash
+COMPLEXITY_BAND=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:FAST_PATH")) | .body' 2>/dev/null \
+  | sed -n 's/.*\*\*COMPLEXITY_BAND\*\*: \([A-Z_]*\).*/\1/p' | head -1)
+COMPLEXITY_BAND="${COMPLEXITY_BAND:-STANDARD}"
+```
+
+**If COMPLEXITY_BAND: TRIVIAL** → skip all phases (C-1 through C4), post NO comment, return empty briefing to caller immediately. Do not query GitHub, do not read files. This is not an error — trivial single-file changes have no institutional memory to surface. <!-- Added: forge#679 -->
+
+**If COMPLEXITY_BAND: STANDARD or COMPLEX** → proceed to Phase C-1 below.
+
+---
+
 ## Mission
 
 Surface what went wrong in this area before the builder writes a single line of code. The builder starts with the investigator report and contract — this step adds institutional memory: what did review agents catch last time someone touched these files, what bugs recurred, what other paths must stay consistent. When prior investigation Gists are linked in the issue body, fetch and summarize them so the builder has cross-issue context without manual lookups. When a milestone-level index Gist exists, use it to discover all investigation Gists for the milestone — providing full cross-issue context from a single URL. <!-- Updated: forge#341 -->
@@ -75,13 +94,106 @@ fi
 
 ### Step 1: Enumerate and filter applicable files
 
-Find all `.md` files under `DEVDOCS_PATH`, parse YAML frontmatter, keep those with `work-on` in `applies_to`. Sort by authority (`required` first, then `recommended`, then `reference`).
+**Index-first path** (preferred when `index.yaml` exists): Read the lightweight index, extract issue labels to filter by domain, load only matching docs. Falls back to O(N) enumerate when index is absent.
 
 ```bash
 DEVDOCS_APPLICABLE=""  # list of paths that apply
+INDEX_PATH="${DEVDOCS_PATH}/index.yaml"
+
+# --- Read devdocs.index_path override from forge.yaml (optional) ---
+if [ -f "$FORGE_YAML_PATH" ]; then
+  INDEX_PATH_OVERRIDE=$(grep -A5 '^devdocs:' "$FORGE_YAML_PATH" \
+    | grep '^\s*index_path:' \
+    | head -1 \
+    | sed 's/.*index_path:\s*//' \
+    | tr -d '"'"'"' \
+    | tr -d '[:space:]')
+  if [ -n "$INDEX_PATH_OVERRIDE" ]; then
+    # Resolve relative to REPO_PATH if not absolute
+    case "$INDEX_PATH_OVERRIDE" in
+      /*) INDEX_PATH="$INDEX_PATH_OVERRIDE" ;;
+      *)  INDEX_PATH="{REPO_PATH}/${INDEX_PATH_OVERRIDE}" ;;
+    esac
+  fi
+fi
+
+if [ -n "$DEVDOCS_PATH" ] && [ -f "$INDEX_PATH" ]; then
+  # --- Index-first loading path ---
+  echo "Devdocs index found at ${INDEX_PATH} — using selective domain loading"
+
+  # Read issue labels to determine domain(s)
+  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}"
+
+  # Read index content
+  INDEX_CONTENT=$(cat "$INDEX_PATH" 2>/dev/null || echo "")
+
+  # Extract always_load paths (lines with "path:" under "always_load:" block)
+  ALWAYS_LOAD_PATHS=$(echo "$INDEX_CONTENT" \
+    | awk '/^always_load:/,/^[a-z]/' \
+    | grep '^\s*-\s*path:' \
+    | sed 's/.*path:\s*//' \
+    | tr -d '"'"'"' \
+    | tr -d '[:space:]')
+
+  # Extract domain blocks matching any issue label keyword
+  DOMAIN_PATHS=""
+  for label in $ISSUE_LABELS; do
+    # Strip workflow:, priority:, review-finding prefixes — use bare keyword
+    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
+    SAFE_KEYWORD=$(printf '%s' "$KEYWORD" | tr -cd 'a-zA-Z0-9_-')
+    [ -z "$SAFE_KEYWORD" ] && continue
+
+    # Find the domain block matching this keyword, extract its doc paths
+    BLOCK_PATHS=$(echo "$INDEX_CONTENT" \
+      | awk "/^  ${SAFE_KEYWORD}:/{found=1; next} found && /^  [a-z]/{found=0} found && /^\s*-\s*path:/{print}" \
+      | sed 's/.*path:\s*//' \
+      | tr -d '"'"'"' \
+      | tr -d '[:space:]')
+
+    if [ -n "$BLOCK_PATHS" ]; then
+      echo "Domain '${SAFE_KEYWORD}' matched — adding docs: $(echo "$BLOCK_PATHS" | tr '\n' ' ')"
+      DOMAIN_PATHS="${DOMAIN_PATHS}${BLOCK_PATHS}"$'\n'
+    fi
+  done
+
+  # Combine always_load + domain paths (deduplicate)
+  ALL_PATHS=$(printf "%s\n%s" "$ALWAYS_LOAD_PATHS" "$DOMAIN_PATHS" \
+    | grep -v '^$' | sort -u)
+
+  # When no domain labels matched, load only authority:required files from always_load
+  if [ -z "$DOMAIN_PATHS" ]; then
+    echo "No domain labels matched index — loading always_load entries only"
+    ALL_PATHS="$ALWAYS_LOAD_PATHS"
+  fi
+
+  # Build DEVDOCS_APPLICABLE list with sort keys
+  while IFS= read -r rel_path; do
+    [ -z "$rel_path" ] && continue
+    ABS_PATH="${DEVDOCS_PATH}/${rel_path}"
+    [ -f "$ABS_PATH" ] || { echo "WARN: index references missing file: ${rel_path} — skipping"; continue; }
+
+    # Extract authority from frontmatter for sort key
+    FRONTMATTER=$(awk '/^---/{c++; if(c==1){next} if(c==2){exit}} c==1{print}' "$ABS_PATH" 2>/dev/null)
+    AUTHORITY=$(echo "$FRONTMATTER" | grep 'authority:' | head -1 | sed 's/.*authority:\s*//' | tr -d ' ')
+    case "$AUTHORITY" in
+      required)    SORT_KEY="1" ;;
+      recommended) SORT_KEY="2" ;;
+      reference)   SORT_KEY="3" ;;
+      *)           SORT_KEY="4" ;;
+    esac
+    DEVDOCS_APPLICABLE="${DEVDOCS_APPLICABLE}${SORT_KEY}|${ABS_PATH}"$'\n'
+  done <<< "$ALL_PATHS"
+
+  DEVDOCS_APPLICABLE=$(printf "%s" "$DEVDOCS_APPLICABLE" | sort | cut -d'|' -f2-)
+
+elif [ -n "$DEVDOCS_PATH" ]; then
+  # --- Fallback: O(N) enumerate (backward compatible — no index.yaml present) ---
+  echo "No index.yaml found at ${INDEX_PATH} — falling back to full enumerate (backward compatible)"
 
-if [ -n "$DEVDOCS_PATH" ]; then
-  # Find all markdown files recursively
   while IFS= read -r -d '' mdfile; do
     # Extract frontmatter block (between first two --- markers)
     FRONTMATTER=$(awk '/^---/{c++; if(c==1){next} if(c==2){exit}} c==1{print}' "$mdfile" 2>/dev/null)
@@ -96,16 +208,16 @@ if [ -n "$DEVDOCS_PATH" ]; then
         reference)   SORT_KEY="3" ;;
         *)           SORT_KEY="4" ;;
       esac
-      DEVDOCS_APPLICABLE="${DEVDOCS_APPLICABLE}${SORT_KEY}|${mdfile}\n"
+      DEVDOCS_APPLICABLE="${DEVDOCS_APPLICABLE}${SORT_KEY}|${mdfile}"$'\n'
     fi
   done < <(find "$DEVDOCS_PATH" -name "*.md" -print0 2>/dev/null)
 
   # Sort by authority key and extract paths
-  DEVDOCS_APPLICABLE=$(printf "$DEVDOCS_APPLICABLE" | sort | cut -d'|' -f2-)
+  DEVDOCS_APPLICABLE=$(printf "%s" "$DEVDOCS_APPLICABLE" | sort | cut -d'|' -f2-)
 fi
 
 if [ -z "$DEVDOCS_APPLICABLE" ]; then
-  echo "No devdocs files with 'applies_to: work-on' found — skipping Phase C-1 content read"
+  echo "No applicable devdocs files found — skipping Phase C-1 content read"
 fi
 ```
 
@@ -165,26 +277,26 @@ INDEX_GIST_URLS=""
 
 # Check issue body for milestone index annotation
 MILESTONE_INDEX_URL=$(echo "$ISSUE_BODY" \
-  | grep -oP '(?<=<!-- FORGE:MILESTONE_INDEX: )https://[^ ]+(?= -->)' \
+  | sed -n 's/.*<!-- FORGE:MILESTONE_INDEX: \(https:\/\/[^ ]*\) -->.*/\1/p' \
   | head -1)
 
 # If not in issue body, check milestone description
 if [ -z "$MILESTONE_INDEX_URL" ] && [ -n "$MILESTONE_NUM" ]; then
   MILESTONE_DESC=$(gh api repos/{GH_REPO}/milestones/${MILESTONE_NUM} --jq '.description // ""' 2>/dev/null)
   MILESTONE_INDEX_URL=$(echo "$MILESTONE_DESC" \
-    | grep -oP '(?<=<!-- FORGE:MILESTONE_INDEX: )https://[^ ]+(?= -->)' \
+    | sed -n 's/.*<!-- FORGE:MILESTONE_INDEX: \(https:\/\/[^ ]*\) -->.*/\1/p' \
     | head -1)
 fi
 
 # If found, fetch the index and extract individual Gist URLs from table rows
 if [ -n "$MILESTONE_INDEX_URL" ]; then
-  INDEX_GIST_ID=$(echo "$MILESTONE_INDEX_URL" | grep -oP '[a-f0-9]{20,}' | tail -1)
+  INDEX_GIST_ID=$(echo "$MILESTONE_INDEX_URL" | grep -oE '[a-f0-9]{20,}' | tail -1)
   if [ -n "$INDEX_GIST_ID" ]; then
     INDEX_CONTENT=$(timeout 15 gh gist view "$INDEX_GIST_ID" --raw 2>/dev/null)
     if [ -n "$INDEX_CONTENT" ]; then
       # Extract Gist URLs from table rows (format: | ... | https://gist.github.com/... | ... |)
       INDEX_GIST_URLS=$(echo "$INDEX_CONTENT" \
-        | grep -oP 'https://gist\.github\.com/[a-f0-9/]+' \
+        | grep -oE 'https://gist\.github\.com/[a-f0-9/]+' \
         | head -10)
       echo "Milestone index fetched: found $(echo "$INDEX_GIST_URLS" | wc -l) investigation Gist(s)"
     else
@@ -198,7 +310,7 @@ fi
 
 ```bash
 GIST_URLS=$(echo "$ISSUE_BODY" \
-  | grep -oP '(?<=<!-- FORGE:PRIOR_GIST: )https://[^ ]+(?= -->)' \
+  | sed -n 's/.*<!-- FORGE:PRIOR_GIST: \(https:\/\/[^ ]*\) -->.*/\1/p' \
   | head -5)
 
 # Merge with any URLs discovered from milestone index (deduplicate)
@@ -223,7 +335,7 @@ GIST_SUMMARIES=""
 
 for url in $GIST_URLS; do
   # Extract Gist ID from URL (last path segment, strip any trailing slash)
-  GIST_ID=$(echo "$url" | grep -oP '[a-f0-9]{20,}' | tail -1)
+  GIST_ID=$(echo "$url" | grep -oE '[a-f0-9]{20,}' | tail -1)
 
   if [ -z "$GIST_ID" ]; then
     echo "WARNING: Could not extract Gist ID from URL: $url — skipping"
@@ -241,10 +353,10 @@ for url in $GIST_URLS; do
   fi
 
   # Extract key sections for summary (~2K chars target per Gist)
-  VERDICT=$(echo "$GIST_CONTENT" | grep -oP '(?<=verdict: )\w+' | head -1)
-  TASK_TYPE=$(echo "$GIST_CONTENT" | grep -oP '(?<=task_type: ).+' | head -1)
-  SEVERITY=$(echo "$GIST_CONTENT" | grep -oP '(?<=severity: )\w+' | head -1)
-  SOURCE_ISSUE=$(echo "$GIST_CONTENT" | grep -oP '(?<=issue: )\d+' | head -1)
+  VERDICT=$(echo "$GIST_CONTENT" | sed -n 's/.*verdict: \([A-Za-z_]*\).*/\1/p' | head -1)
+  TASK_TYPE=$(echo "$GIST_CONTENT" | sed -n 's/.*task_type: \(.*\)/\1/p' | head -1)
+  SEVERITY=$(echo "$GIST_CONTENT" | sed -n 's/.*severity: \([A-Za-z_]*\).*/\1/p' | head -1)
+  SOURCE_ISSUE=$(echo "$GIST_CONTENT" | sed -n 's/.*issue: \([0-9]*\).*/\1/p' | head -1)
 
   # Extract structured sections: Root Cause, Recommendation, Affected Files
   ROOT_CAUSE=$(echo "$GIST_CONTENT" \
@@ -318,7 +430,7 @@ Mine git log for commit messages referencing issues, then fetch those issues:
 ```bash
 # Step 1: find issue numbers from git history on affected files
 git log --oneline -30 -- {AFFECTED_FILES} \
-  | grep -oP '#\d+' \
+  | grep -oE '#[0-9]+' \
   | sort -u \
   | head -8
 
@@ -448,6 +560,7 @@ gh issue comment {NUMBER} -R {GH_REPO} --body "<!-- FORGE:CONTEXT -->
 ## Skip Conditions
 
 Skip this entire step (post nothing, return empty briefing) if:
+- **COMPLEXITY_BAND: TRIVIAL** — checked via FORGE:FAST_PATH comment at entry (see guard above) <!-- Primary skip path: forge#679 -->
 - Issue is a 1-file config or docs edit with no code logic
 - The affected files have zero git history (new files being created)
 - `{AFFECTED_FILES}` is empty (investigation produced no file list)

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

@@ -2,6 +2,8 @@
 description: Implementation agent — writes code, makes commits, posts builder comment
 argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree PATH] [--branch BRANCH]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # work-on/build/implement — Implementation Subcommand
 

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

@@ -2,6 +2,8 @@
 description: Validation agent — quality gate loop, format/verify, proxy check, deploy check
 argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree PATH] [--files FILE1 FILE2...]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # work-on/build/validate — Validation Subcommand
 

package/commands/work-on/build.md

@@ -2,6 +2,8 @@
 description: Build subcommand — create worktree, post contract, sequence context/architect/implement/validate
 argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--base PR_BASE]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # work-on/build — Build Phase Orchestrator
 
@@ -13,7 +15,7 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--base PR_BA
 **Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
 **NEVER use plan mode (EnterPlanMode).**
 
-**CRITICAL: You MUST execute ALL phases B0–B6 in order. After each Skill() call returns, you MUST continue to the next phase. Do NOT skip phases B3 (context) or B4 (architect) — they post mandatory `FORGE:CONTEXT` and `FORGE:ARCHITECT` comments that the implement phase reads as its primary input. Skipping them degrades build quality.**
+**CRITICAL: You MUST execute ALL phases B0–B6 in order. After each Skill() call returns, you MUST continue to the next phase. Phases B3 (context) and B4 (architect) are skipped ONLY when COMPLEXITY_BAND: TRIVIAL (read from FORGE:FAST_PATH comment in Phase B0). For STANDARD and COMPLEX tasks they are NOT optional — skipping them degrades build quality.**
 
 ---
 
@@ -53,6 +55,16 @@ Extract from investigation report:
 - Recommendation
 - Task type (Bug Fix / Feature / Refactor / Maintenance / UI/UX / Full-Stack)
 
+**Read COMPLEXITY_BAND** (from FORGE:FAST_PATH comment posted by Phase 3B):
+```bash
+COMPLEXITY_BAND=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:FAST_PATH")) | .body' 2>/dev/null \
+  | sed -n 's/.*\*\*COMPLEXITY_BAND\*\*: \([A-Z_]*\).*/\1/p' | head -1)
+# Default to STANDARD if not found (conservative — runs full pipeline)
+COMPLEXITY_BAND="${COMPLEXITY_BAND:-STANDARD}"
+echo "COMPLEXITY_BAND: $COMPLEXITY_BAND"
+```
+
 ---
 
 ## Phase B1: Create Worktree & Branch
@@ -146,7 +158,7 @@ After posting the Builder Contract, extract the primary function/class names fro
 FUNCTION_NAMES=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
   --jq '.[] | select(.body | contains("FORGE:CONTRACT")) | .body' \
   | awk '/^### Deliverables/{p=1; next} /^### /{p=0} p' \
-  | grep -oP '`[A-Za-z_][A-Za-z0-9_]*`' \
+  | grep -oE '`[A-Za-z_][A-Za-z0-9_]*`' \
   | tr -d '`' \
   | sort -u \
   | tr '\n' ' ' \
@@ -161,9 +173,11 @@ If `FUNCTION_NAMES` is non-empty, it will be passed via `--functions` to the con
 
 ---
 
-## Phase B3: Context Gathering (MANDATORY Subcommand)
+## Phase B3: Context Gathering (MANDATORY for STANDARD/COMPLEX — skip for TRIVIAL)
+
+**Skip if COMPLEXITY_BAND: TRIVIAL** (read from FORGE:FAST_PATH in Phase B0) — do not invoke the context subcommand. Proceed directly to Phase B4.
 
-**This phase is NOT optional.** Always invoke it regardless of issue size or complexity. Do NOT invent skip heuristics (e.g. "FAST_PATH") — the context subcommand handles trivial cases gracefully and returns quickly.
+**For STANDARD and COMPLEX tasks**: Always invoke. Do NOT skip without a TRIVIAL COMPLEXITY_BAND.
 
 Invoke the context subcommand to surface historical review findings and bug patterns:
 
@@ -184,9 +198,11 @@ Skill("work-on:build:context", args="{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLA
 
 ---
 
-## Phase B4: Architecture Planning (MANDATORY Subcommand)
+## Phase B4: Architecture Planning (MANDATORY for STANDARD/COMPLEX — skip for TRIVIAL)
 
-**This phase is NOT optional.** Always invoke it regardless of issue size or complexity. Do NOT invent skip heuristics — the architect subcommand handles simple changes gracefully and returns quickly. Even a 1-file fix benefits from cross-path consistency checks.
+**Skip if COMPLEXITY_BAND: TRIVIAL** (read from FORGE:FAST_PATH in Phase B0) — do not invoke the architect subcommand. Proceed directly to Phase B5.
+
+**For STANDARD and COMPLEX tasks**: Always invoke. Even a 1-file STANDARD fix benefits from cross-path consistency checks. Do NOT skip without a TRIVIAL COMPLEXITY_BAND.
 
 Invoke the architect subcommand to trace all affected code paths and produce an ordered implementation plan:
 
@@ -229,9 +245,18 @@ Skill("work-on:build:validate", args="{NUMBER} --repo {GH_REPO} --gh-flag {GH_FL
 Where `{CHANGED_FILES}` is the space-separated list of files changed by the implement subcommand (read from `IMPLEMENT_RESULT` or from the `<!-- FORGE:BUILDER -->` comment).
 
 **After subcommand returns**:
-- `VALIDATE_RESULT: gate_passed: true` → build complete, return `BUILD_RESULT: status: COMPLETE`
+- `VALIDATE_RESULT: gate_passed: true` → write checkpoint, then return `BUILD_RESULT: status: COMPLETE`
 - `VALIDATE_RESULT: gate_passed: false` → subcommand has already posted comment and added `needs-human` label; return `BUILD_RESULT: status: BLOCKED`
 
+**When gate_passed is true — write machine-readable phase checkpoint before returning (MANDATORY)**:
+```bash
+CHECKPOINT_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:CHECKPOINT -->
+\`\`\`json
+{\"phase\": \"BUILD\", \"status\": \"COMPLETE\", \"next_phase\": \"REVIEW\", \"timestamp\": \"${CHECKPOINT_TIMESTAMP}\"}
+\`\`\`"
+```
+
 ---
 
 ## Output

package/commands/work-on/close.md

@@ -2,6 +2,8 @@
 description: Close subcommand — update project board, final issue body, parent tracker, summary report, trajectory log
 argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--pr PR_NUMBER] [--base PR_BASE] [--branch BRANCH] [--worktree WORKTREE_PATH]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # work-on/close — Close & Trajectory Subcommand
 
@@ -314,6 +316,88 @@ Where:
 
 ---
 
+## Phase C5.5: Graph Decision Record (MANDATORY when PR exists)
+
+**Skip if**: `{PR_NUMBER}` is empty OR `<!-- FORGE:DECISION_RECORD -->` already posted on the PR.
+
+Post a consolidated provenance artifact to the PR that proves the merge was backed by citable evidence. Mirrors the Phase 7C step in `work-on.md` — must stay in sync.
+
+**Idempotency check**:
+```bash
+GDR_EXISTS=$(gh api repos/{GH_REPO}/issues/{PR_NUMBER}/comments \
+  --jq '[.[] | select(.body | contains("FORGE:DECISION_RECORD"))] | length > 0' 2>/dev/null || echo "false")
+```
+
+**Extract context edge counts** from FORGE:CONTEXT comment:
+```bash
+CONTEXT_COMMENT=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:CONTEXT")) | .body' 2>/dev/null | head -1)
+REVIEW_FINDING_COUNT=$(echo "$CONTEXT_COMMENT" | grep -oP '#\d+' | wc -l | tr -d ' ')
+REVIEW_FINDING_COUNT=${REVIEW_FINDING_COUNT:-0}
+```
+
+**Extract review verdict** from PR review summary:
+```bash
+REVIEW_SUMMARY=$(gh api repos/{GH_REPO}/issues/{PR_NUMBER}/comments \
+  --jq '[.[] | select(.body | contains("FORGE:REVIEWER") or (.body | test("APPROVED:|CHANGES REQUESTED:"; "i")))] | last | .body // ""' 2>/dev/null || echo '')
+REVIEW_VERDICT=$(echo "$REVIEW_SUMMARY" | grep -oP '(?<=Verdict: )(APPROVED|CHANGES REQUESTED)' | head -1 || echo "APPROVED")
+FINDINGS_COUNT=$(echo "$REVIEW_SUMMARY" | grep -oP '\d+(?= findings)' | head -1 || echo "0")
+AGENTS_RUN=$(echo "$REVIEW_SUMMARY" | grep -oP '\d+(?= agents)' | head -1 || echo "0")
+```
+
+**Post GDR to PR** (not to issue — PR comment is the permanent artifact):
+```bash
+if [ "$GDR_EXISTS" != "true" ] && [ -n "{PR_NUMBER}" ]; then
+  GDR_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  HEAD_SHA=$(gh pr view {PR_NUMBER} {GH_FLAG} --json headRefOid --jq '.headRefOid' 2>/dev/null || echo "")
+  MERGE_COMMIT=$(gh pr view {PR_NUMBER} {GH_FLAG} --json mergeCommit --jq '.mergeCommit.oid // ""' 2>/dev/null || echo "")
+
+  gh pr comment {PR_NUMBER} {GH_FLAG} --body "<!-- FORGE:DECISION_RECORD -->
+## Graph Decision Record — Issue #${NUMBER} / PR #${PR_NUMBER}
+
+\`\`\`json
+{
+  \"schema_version\": \"1\",
+  \"issue\": ${NUMBER},
+  \"pr\": ${PR_NUMBER},
+  \"repo\": \"{GH_REPO}\",
+  \"lane\": \"feature\",
+  \"pr_base\": \"{PR_BASE}\",
+  \"branch\": \"{BRANCH}\",
+  \"head_sha\": \"${HEAD_SHA}\",
+  \"merge_commit\": \"${MERGE_COMMIT}\",
+  \"investigation\": {
+    \"verdict\": \"{VERDICT}\",
+    \"confidence\": \"{CONFIDENCE}\",
+    \"task_type\": \"{TASK_TYPE}\"
+  },
+  \"context\": {
+    \"historical_edges_referenced\": ${REVIEW_FINDING_COUNT},
+    \"forge_annotations_read\": [\"FORGE:INVESTIGATOR\", \"FORGE:CONTRACT\", \"FORGE:CONTEXT\", \"FORGE:ARCHITECT\", \"FORGE:BUILDER\"]
+  },
+  \"build\": {
+    \"files_changed\": {FILES_CHANGED},
+    \"quality_gate\": \"{pass|fail}\",
+    \"quality_gate_iterations\": {GATE_ITERATIONS}
+  },
+  \"review\": {
+    \"verdict\": \"${REVIEW_VERDICT:-APPROVED}\",
+    \"findings_created\": ${FINDINGS_COUNT},
+    \"agents_run\": ${AGENTS_RUN}
+  },
+  \"merge\": {
+    \"merged_at\": \"${GDR_TIMESTAMP}\",
+    \"justification\": \"Investigation confirmed ({VERDICT}/{CONFIDENCE}), quality gate passed, review ${REVIEW_VERDICT:-approved}\"
+  }
+}
+\`\`\`"
+fi
+```
+
+<!-- Added: forge#776 -->
+
+---
+
 ## Phase C6: Worktree & Branch Cleanup
 
 Remove the git worktree and delete the local feature branch after the PR has merged. This prevents worktree accumulation across pipeline runs.
@@ -360,6 +444,7 @@ CLOSE_RESULT:
   status: COMPLETE | ALREADY_DONE | PHASE_COMPLETE
   issue_state: closed | open
   trajectory_url: {url of FORGE:TRAJECTORY comment}
+  decision_record_url: {url of FORGE:DECISION_RECORD comment on PR, or "" if skipped}
   parent_updated: {true|false}
   parent_closed: {true|false}
 ```

package/commands/work-on/decompose.md

@@ -2,6 +2,8 @@
 description: Decompose subcommand — break a complex issue into ordered sub-issues, post FORGE:DECOMPOSED, stop
 argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # work-on/decompose — Decomposition Subcommand
 

package/commands/work-on/investigate.md

@@ -2,6 +2,8 @@
 description: Investigate a GitHub issue — validate it's real, determine root cause, post findings
 argument-hint: [issue number] [--repo {owner}/{repo}] [--gh-flag "-R {owner}/{repo}"]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # /work-on:investigate — Issue Investigation Subcommand
 
@@ -352,8 +354,13 @@ ${INDEX_ENTRY}"
     fi
 
     # Update the Gist
-    echo "$UPDATED_INDEX" | gh gist edit "$INDEX_GIST_ID" -f "$INDEX_FILENAME" - 2>/dev/null
-    if [ $? -eq 0 ]; then
+    # gh gist edit does not support stdin via '-'; use a temp file instead
+    TMPFILE=$(mktemp --suffix=.md)
+    echo "$UPDATED_INDEX" > "$TMPFILE"
+    gh gist edit "$INDEX_GIST_ID" -f "$INDEX_FILENAME" "$TMPFILE" 2>/dev/null
+    EDIT_EXIT=$?
+    rm -f "$TMPFILE"
+    if [ $EDIT_EXIT -eq 0 ]; then
       INDEX_URL="$EXISTING_INDEX_URL"
       echo "Milestone index Gist updated: ${INDEX_URL}"
     else
@@ -400,6 +407,16 @@ fi
 ```bash
 gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:ready-to-build" --remove-label "workflow:investigating"
 ```
+
+Write machine-readable phase checkpoint (MUST execute immediately after label update, before returning):
+```bash
+CHECKPOINT_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:CHECKPOINT -->
+\`\`\`json
+{\"phase\": \"INVESTIGATION\", \"status\": \"COMPLETE\", \"next_phase\": \"BUILD\", \"timestamp\": \"${CHECKPOINT_TIMESTAMP}\"}
+\`\`\`"
+```
+
 Return verdict to caller (work-on routing loop proceeds to build).
 
 **CONFIRMED or PARTIAL with decompose: YES**:
@@ -407,6 +424,16 @@ Return verdict to caller (work-on routing loop proceeds to build).
 gh issue edit {NUMBER} {GH_FLAG} --remove-label "workflow:investigating"
 ```
 Do NOT add `workflow:ready-to-build` — the routing loop will invoke `work-on:decompose` based on the `decompose: YES` return value.
+
+Write machine-readable phase checkpoint (MUST execute immediately after label update, before returning):
+```bash
+CHECKPOINT_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:CHECKPOINT -->
+\`\`\`json
+{\"phase\": \"INVESTIGATION\", \"status\": \"COMPLETE\", \"next_phase\": \"DECOMPOSE\", \"timestamp\": \"${CHECKPOINT_TIMESTAMP}\"}
+\`\`\`"
+```
+
 Return verdict to caller (work-on routing loop proceeds to decompose).
 
 **INVALID**:
@@ -414,7 +441,7 @@ Return verdict to caller (work-on routing loop proceeds to decompose).
 gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:invalid" --remove-label "workflow:investigating"
 gh issue close {NUMBER} {GH_FLAG} --comment "Closing as invalid: {reason from investigation}"
 ```
-Return INVALID to caller (work-on stops).
+Return INVALID to caller (work-on stops). No checkpoint written — INVALID is terminal.
 
 ---
 

package/commands/work-on/review.md

@@ -2,6 +2,8 @@
 description: Review subcommand — push branch, create PR, invoke /review-pr with --auto-merge
 argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree PATH] [--branch BRANCH] [--base PR_BASE]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # work-on/review — Review & PR Creation Subcommand
 
@@ -208,7 +210,17 @@ gh issue view {NUMBER} {GH_FLAG} --json state --jq '.state'
 ```
 
 **Cases**:
-- PR MERGED (issue OPEN or CLOSED) → `REVIEW_RESULT: status: COMPLETE` — do NOT close the issue or add labels here; the router will route to `work-on:close` which handles issue closure, label updates, project board, trajectory log, and worktree cleanup.
+- PR MERGED (issue OPEN or CLOSED) → write checkpoint, then return `REVIEW_RESULT: status: COMPLETE` — do NOT close the issue or add labels here; the router will route to `work-on:close` which handles issue closure, label updates, project board, trajectory log, and worktree cleanup.
+
+  Write machine-readable phase checkpoint before returning (MANDATORY when PR is MERGED):
+  ```bash
+  CHECKPOINT_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:CHECKPOINT -->
+  \`\`\`json
+  {\"phase\": \"REVIEW\", \"status\": \"COMPLETE\", \"next_phase\": \"CLOSE\", \"timestamp\": \"${CHECKPOINT_TIMESTAMP}\"}
+  \`\`\`"
+  ```
+
 - PR NOT MERGED → attempt manual merge:
   ```bash
   gh pr merge {PR_NUMBER} {GH_FLAG} --merge --auto

package/commands/work-on-monolithic.md

@@ -2,6 +2,8 @@
 description: "[BENCHMARK] Monolithic work-on — single-prompt pipeline with no Skill sub-phase boundaries"
 argument-hint: [issue number]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # /work-on-monolithic — Full Issue Pipeline (Single Prompt)