forgedock 1.0.16 → 1.0.18

package/commands/validate.md

@@ -2,6 +2,8 @@
 description: Independently verify if a reported issue is actually a problem before making code changes.
 argument-hint: [issue description or #number]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # /validate — Independent Issue Verification
 

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

@@ -2,6 +2,8 @@
 description: Pre-implementation architecture planning — traces ALL affected code paths and produces an ordered implementation plan before any code is written
 argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--files AFFECTED_FILES]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # work-on/build/architect — Multi-Path Implementation Planning
 
@@ -11,6 +13,23 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--files AFFE
 
 ---
 
+## 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 (A0 through A5), post NO comment, return empty plan to caller immediately. Do not read any files. This is not an error — trivial single-file changes have no cross-path consistency risk. <!-- Added: forge#679 -->
+
+**If COMPLEXITY_BAND: STANDARD or COMPLEX** → proceed to Phase A0 below.
+
+---
+
 ## Mission
 
 Eliminate cross-path inconsistency bugs before any code is written. The single biggest class of production bugs is a change applied to one code path but not all sibling paths that share the same logic. This agent traces the FULL request/data flow from every entry point, identifies every file that must change, and produces an ordered implementation plan the builder follows exactly.
@@ -127,12 +146,103 @@ fi
 
 ### Step 2: Secondary reads — other applicable project files
 
-Read all other `*.md` files under `DEVDOCS_PATH` where `applies_to` contains `work-on`. Skip `project/custom-instructions.md` (already read). Sort by authority (`required` first).
+**Index-first path** (preferred when `index.yaml` exists): Use domain-filtered selective loading instead of O(N) enumerate. Falls back to full enumerate when index is absent. Skip `project/custom-instructions.md` (already read in Step 1). Sort by authority (`required` first).
 
 ```bash
 PROJECT_CONVENTIONS=""
+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
+    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
+    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
+
+    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 always_load entries
+  if [ -z "$DOMAIN_PATHS" ]; then
+    echo "No domain labels matched index — loading always_load entries only"
+    ALL_PATHS="$ALWAYS_LOAD_PATHS"
+  fi
+
+  APPLICABLE_FILES=""
+  while IFS= read -r rel_path; do
+    [ -z "$rel_path" ] && continue
+    # Skip custom-instructions — already read in Step 1
+    [ "$rel_path" = "project/custom-instructions.md" ] && continue
+    ABS_PATH="${DEVDOCS_PATH}/${rel_path}"
+    [ -f "$ABS_PATH" ] || { echo "WARN: index references missing file: ${rel_path} — skipping"; continue; }
+
+    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" ;;
+      *)           SORT_KEY="3" ;;
+    esac
+    APPLICABLE_FILES="${APPLICABLE_FILES}${SORT_KEY}|${ABS_PATH}"$'\n'
+  done <<< "$ALL_PATHS"
+
+  APPLICABLE_FILES=$(printf "%s" "$APPLICABLE_FILES" | 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
   APPLICABLE_FILES=""
 
   while IFS= read -r -d '' mdfile; do
@@ -148,32 +258,31 @@ if [ -n "$DEVDOCS_PATH" ]; then
         recommended) SORT_KEY="2" ;;
         *)           SORT_KEY="3" ;;
       esac
-      APPLICABLE_FILES="${APPLICABLE_FILES}${SORT_KEY}|${mdfile}\n"
+      APPLICABLE_FILES="${APPLICABLE_FILES}${SORT_KEY}|${mdfile}"$'\n'
     fi
   done < <(find "$DEVDOCS_PATH" -name "*.md" -print0 2>/dev/null)
 
   APPLICABLE_FILES=$(printf "$APPLICABLE_FILES" | sort | cut -d'|' -f2-)
+fi
 
-  while IFS= read -r mdfile; do
-    [ -z "$mdfile" ] && continue
-    TOTAL_LINES=$(wc -l < "$mdfile" 2>/dev/null || echo 0)
-    if [ "$TOTAL_LINES" -gt 200 ]; then
-      FILE_CONTENT=$(head -200 "$mdfile")
-      TRUNCATION_NOTE="_[Truncated at 200 lines — ${TOTAL_LINES} total.]_"
-    else
-      FILE_CONTENT=$(cat "$mdfile")
-      TRUNCATION_NOTE=""
-    fi
+while IFS= read -r mdfile; do
+  [ -z "$mdfile" ] && continue
+  TOTAL_LINES=$(wc -l < "$mdfile" 2>/dev/null || echo 0)
+  if [ "$TOTAL_LINES" -gt 200 ]; then
+    FILE_CONTENT=$(head -200 "$mdfile")
+    TRUNCATION_NOTE="_[Truncated at 200 lines — ${TOTAL_LINES} total.]_"
+  else
+    FILE_CONTENT=$(cat "$mdfile")
+    TRUNCATION_NOTE=""
+  fi
 
-    REL_PATH="${mdfile#${DEVDOCS_PATH}/}"
-    PROJECT_CONVENTIONS="${PROJECT_CONVENTIONS}
+  REL_PATH="${mdfile#${DEVDOCS_PATH}/}"
+  PROJECT_CONVENTIONS="${PROJECT_CONVENTIONS}
 
 #### \`${REL_PATH}\`
 ${FILE_CONTENT}
 ${TRUNCATION_NOTE}"
-  done <<< "$APPLICABLE_FILES"
-fi
-```
+done <<< "$APPLICABLE_FILES"
 
 ### Step 3: Precedence rules to enforce
 
@@ -411,6 +520,7 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:ARCHITECT -->
 ## Skip Conditions
 
 Skip this entire step (post nothing, return empty plan to caller) if:
+- **COMPLEXITY_BAND: TRIVIAL** — checked via FORGE:FAST_PATH comment at entry (see guard above) <!-- Primary skip path: forge#679 -->
 - Issue creates only **new files** with no callers to find (e.g. a new command file with no existing integration point yet)
 - Issue is a 1-file config or docs edit with no code logic
 - Issue title starts with "docs:" or "chore:"

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
 
@@ -241,9 +243,11 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:BUILDER -->
 {Checklist of each criterion from the contract, marked ✅ or ❌}
 
 ### Testing Checklist
-- [ ] {Test scenario 1}
-- [ ] {Test scenario 2}
-- [ ] {Test scenario 3}
+- [ ] {Test scenario 1} [type:api]
+- [ ] {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 -->"
 ```

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