forgedock 1.0.16 → 1.0.17

package/commands/status.md

@@ -0,0 +1,262 @@
+---
+description: Pipeline-wide situational awareness — groups open issues by workflow state, shows active PRs, flags stale items, and reports milestone progress
+argument-hint: [--repo <owner/repo> | --stale-days <N>]
+---
+
+# /status — Pipeline Status
+
+**Input**: $ARGUMENTS (optional: `--repo <owner/repo>`, `--stale-days <N>`)
+
+Read-only snapshot of the ForgeDock pipeline. Shows open issues grouped by workflow label, active PRs with age, stale items, and milestone progress.
+
+**This command is fully read-only.** It makes no label changes, posts no comments, and creates no issues.
+
+**NEVER use plan mode (EnterPlanMode)** — it breaks execution context.
+
+---
+
+## Config Resolution
+
+```bash
+CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
+GH_REPO=$(yq '.project.owner + "/" + .project.repo' "$CONFIG_FILE")
+GH_FLAG="-R $GH_REPO"
+STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
+
+# Optional: --repo flag overrides the default repo
+if echo "$ARGUMENTS" | grep -q -- "--repo"; then
+    GH_REPO=$(echo "$ARGUMENTS" | sed 's/.*--repo[[:space:]]\([^[:space:]]*\).*/\1/')
+    GH_FLAG="-R $GH_REPO"
+fi
+
+# Optional: --stale-days flag (default: 7)
+STALE_DAYS=7
+if echo "$ARGUMENTS" | grep -q -- "--stale-days"; then
+    STALE_DAYS=$(echo "$ARGUMENTS" | sed 's/.*--stale-days[[:space:]]\([^[:space:]]*\).*/\1/')
+fi
+
+STALE_THRESHOLD=$(date -d "${STALE_DAYS} days ago" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+  || date -v-${STALE_DAYS}d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+  || echo "")
+
+echo "Repo: $GH_REPO"
+echo "Staging branch: $STAGING_BRANCH"
+echo "Stale threshold: ${STALE_DAYS} days"
+```
+
+---
+
+## Phase 1: Issues by Workflow State
+
+Fetch all open issues with `workflow:*` labels. Group and count by state.
+
+```bash
+echo ""
+echo "=== Pipeline Issues — $(date +%Y-%m-%d) ==="
+echo ""
+
+# Workflow states to display (in pipeline order)
+STATES="workflow:investigating workflow:building workflow:in-review workflow:ready-to-build needs-human"
+
+for LABEL in $STATES; do
+    ISSUES=$(gh issue list $GH_FLAG \
+        --state open \
+        --label "$LABEL" \
+        --limit 50 \
+        --json number,title,updatedAt,assignees \
+        --jq '.[] | "#\(.number) \(.title[:60]) [updated: \(.updatedAt[:10])]"' \
+        2>/dev/null || echo "")
+
+    COUNT=$(echo "$ISSUES" | grep -c '#' 2>/dev/null || echo 0)
+    [ "$COUNT" = "0" ] && [ -z "$ISSUES" ] && COUNT=0
+
+    if [ -n "$ISSUES" ] && [ "$COUNT" -gt 0 ]; then
+        echo "[$LABEL] ($COUNT open)"
+        echo "$ISSUES" | while IFS= read -r line; do
+            echo "  $line"
+        done
+        echo ""
+    else
+        echo "[$LABEL] — none"
+    fi
+done
+
+# Issues with no workflow label (untracked / not yet entered pipeline)
+UNTRACKED=$(gh issue list $GH_FLAG \
+    --state open \
+    --limit 20 \
+    --json number,title,labels,createdAt \
+    --jq '.[] | select(
+        (.labels | map(.name) | any(startswith("workflow:"))) | not
+    ) | "#\(.number) \(.title[:60]) [created: \(.createdAt[:10])]"' \
+    2>/dev/null || echo "")
+
+UNTRACKED_COUNT=$(echo "$UNTRACKED" | grep -c '#' 2>/dev/null || echo 0)
+if [ -n "$UNTRACKED" ] && [ "$UNTRACKED_COUNT" -gt 0 ]; then
+    echo "[untracked] ($UNTRACKED_COUNT — not yet in pipeline)"
+    echo "$UNTRACKED" | while IFS= read -r line; do
+        echo "  $line"
+    done
+    echo ""
+fi
+```
+
+---
+
+## Phase 2: Active PRs
+
+Show open PRs targeting `staging` or any `milestone/*` branch, with age and review status.
+
+```bash
+echo "=== Active PRs ==="
+echo ""
+
+gh pr list $GH_FLAG \
+    --state open \
+    --limit 30 \
+    --json number,title,headRefName,baseRefName,createdAt,reviews,isDraft \
+    --jq '.[] | {
+        number: .number,
+        title: .title[:55],
+        head: .headRefName,
+        base: .baseRefName,
+        age_days: (((now - (.createdAt | fromdateiso8601)) / 86400) | floor),
+        draft: .isDraft,
+        review_state: (
+            if (.reviews | length) == 0 then "no review"
+            elif (.reviews | map(select(.state == "APPROVED")) | length) > 0 then "APPROVED"
+            elif (.reviews | map(select(.state == "CHANGES_REQUESTED")) | length) > 0 then "CHANGES REQUESTED"
+            else "COMMENTED"
+            end
+        )
+    } | "  PR #\(.number) \(.title) [\(.age_days)d old] [\(.review_state)]\(if .draft then " [DRAFT]" else "" end)\n    → \(.head) → \(.base)"' \
+    2>/dev/null || echo "  (none)"
+
+echo ""
+```
+
+---
+
+## Phase 3: Stale Items
+
+Flag issues and PRs with no activity in the last `$STALE_DAYS` days.
+
+```bash
+echo "=== Stale Items (no activity > ${STALE_DAYS} days) ==="
+echo ""
+
+if [ -z "$STALE_THRESHOLD" ]; then
+    echo "  (skipped — could not compute stale threshold on this platform)"
+else
+    # Stale open issues with workflow labels
+    STALE_ISSUES=$(gh issue list $GH_FLAG \
+        --state open \
+        --limit 100 \
+        --json number,title,updatedAt,labels \
+        --jq --arg threshold "$STALE_THRESHOLD" \
+        '[.[] |
+            select(
+                (.updatedAt < $threshold) and
+                (.labels | map(.name) | any(startswith("workflow:")))
+            )
+        ] | .[] | "  ISSUE #\(.number) \(.title[:55]) [last updated: \(.updatedAt[:10])] [\(.labels | map(select(.name | startswith("workflow:"))) | .[0].name // "no-workflow")]"' \
+        2>/dev/null || echo "")
+
+    STALE_PRS=$(gh pr list $GH_FLAG \
+        --state open \
+        --limit 50 \
+        --json number,title,updatedAt \
+        --jq --arg threshold "$STALE_THRESHOLD" \
+        '[.[] | select(.updatedAt < $threshold)] |
+        .[] | "  PR #\(.number) \(.title[:55]) [last updated: \(.updatedAt[:10])]"' \
+        2>/dev/null || echo "")
+
+    if [ -z "$STALE_ISSUES" ] && [ -z "$STALE_PRS" ]; then
+        echo "  None — pipeline is moving."
+    else
+        [ -n "$STALE_ISSUES" ] && echo "$STALE_ISSUES"
+        [ -n "$STALE_PRS" ] && echo "$STALE_PRS"
+    fi
+fi
+
+echo ""
+```
+
+---
+
+## Phase 4: Milestone Progress
+
+Show open milestones with open/closed issue counts and percentage complete.
+
+```bash
+echo "=== Milestone Progress ==="
+echo ""
+
+MILESTONES=$(gh api repos/$GH_REPO/milestones \
+    --jq '.[] | select(.state == "open") | {
+        title: .title,
+        number: .number,
+        open: .open_issues,
+        closed: .closed_issues,
+        total: (.open_issues + .closed_issues),
+        due: (.due_on // "no due date")[:10],
+        pct: (if (.open_issues + .closed_issues) > 0 then
+            ((.closed_issues / (.open_issues + .closed_issues)) * 100) | floor
+            else 0 end)
+    } | "\(.title) [\(.pct)% done — \(.closed)/\(.total) issues] [due: \(.due)]"' \
+    2>/dev/null || echo "")
+
+if [ -z "$MILESTONES" ]; then
+    echo "  No active milestones."
+else
+    echo "$MILESTONES" | while IFS= read -r line; do
+        echo "  $line"
+    done
+fi
+
+echo ""
+```
+
+---
+
+## Phase 5: Bottleneck Summary
+
+Highlight states where issues are piling up or stuck.
+
+```bash
+echo "=== Bottleneck Summary ==="
+echo ""
+
+INVESTIGATING=$(gh issue list $GH_FLAG --state open --label "workflow:investigating" --limit 100 --json number --jq '. | length' 2>/dev/null || echo 0)
+BUILDING=$(gh issue list $GH_FLAG --state open --label "workflow:building" --limit 100 --json number --jq '. | length' 2>/dev/null || echo 0)
+IN_REVIEW=$(gh issue list $GH_FLAG --state open --label "workflow:in-review" --limit 100 --json number --jq '. | length' 2>/dev/null || echo 0)
+BLOCKED=$(gh issue list $GH_FLAG --state open --label "needs-human" --limit 100 --json number --jq '. | length' 2>/dev/null || echo 0)
+READY=$(gh issue list $GH_FLAG --state open --label "workflow:ready-to-build" --limit 100 --json number --jq '. | length' 2>/dev/null || echo 0)
+
+TOTAL_INFLIGHT=$((INVESTIGATING + BUILDING + IN_REVIEW + READY))
+
+echo "  investigating  : $INVESTIGATING"
+echo "  ready-to-build : $READY"
+echo "  building       : $BUILDING"
+echo "  in-review      : $IN_REVIEW"
+echo "  needs-human    : $BLOCKED  $([ "$BLOCKED" -gt 0 ] && echo '← ACTION REQUIRED' || true)"
+echo ""
+echo "  Total in-flight: $TOTAL_INFLIGHT"
+
+if [ "$BLOCKED" -gt 0 ]; then
+    echo ""
+    echo "  ⚠  $BLOCKED issue(s) need human attention:"
+    gh issue list $GH_FLAG --state open --label "needs-human" --limit 20 \
+        --json number,title \
+        --jq '.[] | "    #\(.number) \(.title[:70])"' \
+        2>/dev/null || true
+fi
+
+if [ "$IN_REVIEW" -gt 3 ]; then
+    echo ""
+    echo "  ⚠  Review queue depth is $IN_REVIEW — consider running /review-pr or /orchestrate fast-lane"
+fi
+
+echo ""
+echo "=== Status complete — $(date +%Y-%m-%d\ %H:%M:%S) ==="
+```

package/commands/sync-ecosystem.md

@@ -2,6 +2,8 @@
 description: Detect API changes, sync satellite repos, and publish releases
 argument-hint: [check | auto | status | publish | PR-number]
 ---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
 
 # /sync-ecosystem — Cross-Project Sync & Publish
 

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:"