forgedock 1.0.0

package/commands/work-on/decompose.md

@@ -0,0 +1,254 @@
+---
+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]
+---
+
+# work-on/decompose — Decomposition Subcommand
+
+**Input**: $ARGUMENTS
+
+**Invoked by**: `work-on.md` routing loop, when `INVESTIGATE_RESULT.decompose = YES`.
+**Output**: Create sub-issues, update parent tracker, post `<!-- FORGE:DECOMPOSED -->` comment, set labels. STOP — each sub-issue runs its own /work-on.
+
+**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**NEVER use plan mode (EnterPlanMode).**
+
+---
+
+## Inputs
+
+Parse from $ARGUMENTS:
+- `{NUMBER}` — issue number (required)
+- `--repo {GH_REPO}` — GitHub repo (e.g. `RapierCraftStudios/forge`)
+- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R RapierCraftStudios/forge`)
+
+---
+
+## Phase D0: Load State from GitHub (MANDATORY)
+
+Re-read current state before doing anything:
+
+```bash
+gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,milestone
+
+# Read investigation report (required — contains decomposition plan)
+gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | (contains("FORGE:INVESTIGATOR") or contains("ALTERLAB:INVESTIGATOR"))) | .body'
+```
+
+**Validation**:
+- If FORGE:INVESTIGATOR / ALTERLAB:INVESTIGATOR comment is absent → EXIT with `DECOMPOSE_RESULT: status: BLOCKED`, blocker: "No investigation report found — run investigate first"
+- If investigation report has no Decomposition Assessment section, OR the assessment does not list any sub-issues → EXIT with `DECOMPOSE_RESULT: status: BLOCKED`, blocker: "Investigation report has no decomposition plan — re-run investigate with explicit decomposition scope"
+
+Extract from investigation report:
+- Decomposition Assessment section: list of proposed sub-issues with titles and dependencies
+- Milestone (from issue metadata)
+- Priority label (P0/P1/P2) from issue labels
+
+Extract milestone title for sub-issue creation:
+```bash
+MILESTONE_TITLE=$(gh issue view {NUMBER} {GH_FLAG} --json milestone --jq '.milestone.title // empty')
+```
+
+---
+
+## Phase D1: Resume Check
+
+```bash
+gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | (contains("FORGE:DECOMPOSED") or contains("ALTERLAB:DECOMPOSED"))) | .body'
+```
+
+- If `<!-- FORGE:DECOMPOSED -->` or `<!-- ALTERLAB:DECOMPOSED -->` comment exists → decomposition already complete. EXIT with `DECOMPOSE_RESULT: status: ALREADY_DONE`.
+
+---
+
+## Phase D1.5: Collect Parent Knowledge Gist URLs
+
+Query the parent issue's comments for `FORGE:KNOWLEDGE_GIST` annotations created by Phase 1C.5 of the investigation. These URLs will be embedded in each sub-issue body so downstream agents can fetch prior investigation context.
+
+```bash
+GIST_URLS=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '[.[] | select(.body | test("<!-- FORGE:KNOWLEDGE_GIST: https://")) | .body | capture("<!-- FORGE:KNOWLEDGE_GIST: (?<url>https://[^ ]+) -->").url] | unique | .[]')
+
+if [ -n "$GIST_URLS" ]; then
+  echo "Found Knowledge Gist URL(s) on parent issue #${NUMBER}:"
+  echo "$GIST_URLS"
+else
+  echo "No Knowledge Gist annotations found on parent issue #${NUMBER} — sub-issues will not include Prior Investigation section"
+fi
+```
+
+If `GIST_URLS` is non-empty, a `## Prior Investigation` section will be appended to each sub-issue body in Phase D3.
+
+---
+
+## Phase D2: Design Sub-Issues
+
+From the Decomposition Assessment in the investigation report, extract:
+1. Sub-issue titles (in dependency order — independent issues first)
+2. Dependencies between sub-issues (if issue B depends on issue A, A is created first)
+3. Brief description for each sub-issue body
+
+For each sub-issue, prepare:
+- **Title**: from investigation report's proposed sub-issue title
+- **Body**: brief description of scope + `**Parent**: #{NUMBER}` + dependency note if applicable
+- **Labels**: inherit priority label (P0/P1/P2) from parent; do NOT copy workflow labels
+- **Milestone**: same milestone title as parent (if parent has one)
+
+**Ordering rule**: Create independent sub-issues first. If sub-issue B depends on A, create A first so its issue number can be referenced in B's body.
+
+---
+
+## Phase D3: Create Sub-Issues
+
+For each sub-issue (in dependency order):
+
+```bash
+gh issue create {GH_FLAG} \
+  --title "{fix|feat|refactor}: {SUB_ISSUE_TITLE}" \
+  --body "$(cat <<'SUB_BODY_EOF'
+## Problem
+
+{1-3 sentences: what this sub-issue specifically addresses. What's wrong or what needs to be built for this sub-task.}
+
+## Root Cause (if known)
+
+{Specific root cause for this sub-task from the parent investigation. If unknown: "Root cause unknown — investigation needed."}
+
+## Affected Files
+
+Files that need changes:
+1. `{filepath}` — {what needs to change}
+2. `{filepath}` — {what needs to change}
+
+## Acceptance Criteria
+
+- [ ] {Specific, testable criterion}
+- [ ] {Specific, testable criterion}
+- [ ] No regression in {related feature}
+
+## Context
+
+**Parent**: #{NUMBER}
+{If depends on another sub-issue: "**Depends on**: #{SUB_ISSUE_N} — {reason}"}
+SUB_BODY_EOF
+)" \
+  --label "{PRIORITY_LABEL}" \
+  --milestone "{MILESTONE_TITLE}"
+```
+
+**Append Prior Investigation section** (conditional — only if `GIST_URLS` from Phase D1.5 is non-empty):
+
+After creating each sub-issue, append the `## Prior Investigation` section containing all parent Gist URLs. This keeps the Gist references machine-readable for downstream agents.
+
+```bash
+if [ -n "$GIST_URLS" ]; then
+  SUB_BODY=$(gh issue view {SUB_NUMBER} {GH_FLAG} --json body --jq '.body')
+
+  PRIOR_SECTION="
+
+## Prior Investigation
+
+Investigation findings from the parent issue are available as Knowledge Gists:
+"
+  while IFS= read -r url; do
+    PRIOR_SECTION="${PRIOR_SECTION}
+<!-- FORGE:PRIOR_GIST: ${url} -->
+- ${url}"
+  done <<< "$GIST_URLS"
+
+  gh issue edit {SUB_NUMBER} {GH_FLAG} --body "${SUB_BODY}${PRIOR_SECTION}"
+fi
+```
+
+Capture the created issue number from the output URL for the tracker checklist.
+
+If `--milestone` flag fails (milestone not found by name): omit the flag and note in the FORGE:DECOMPOSED comment that milestone assignment was skipped.
+
+---
+
+## Phase D4: Update Parent Issue Body
+
+Add a tracker checklist to the parent issue body showing all sub-issues in dependency order:
+
+```bash
+CURRENT_BODY=$(gh issue view {NUMBER} {GH_FLAG} --json body --jq '.body')
+
+TRACKER="
+
+---
+
+## Sub-Issue Tracker
+
+{if sub-issue B depends on A, note it inline}
+- [ ] #{SUB_ISSUE_1_NUMBER} — {SUB_ISSUE_1_TITLE}
+- [ ] #{SUB_ISSUE_2_NUMBER} — {SUB_ISSUE_2_TITLE} _(depends on #{SUB_ISSUE_1_NUMBER})_
+..."
+
+gh issue edit {NUMBER} {GH_FLAG} --body "${CURRENT_BODY}${TRACKER}"
+```
+
+---
+
+## Phase D5: Post FORGE:DECOMPOSED Comment
+
+```bash
+gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:DECOMPOSED -->
+## Decomposition Complete
+
+This issue has been broken into sub-issues. Each sub-issue runs through its own /work-on pipeline independently.
+
+### Sub-Issues Created
+
+{for each sub-issue, in dependency order:}
+- #{SUB_ISSUE_NUMBER}: {TITLE}{if has dependency: _(depends on #{DEP_NUMBER})_}
+
+### Decomposition Rationale
+
+{brief summary of why this issue was decomposed and the dependency ordering chosen}
+
+<!-- FORGE:DECOMPOSED:COMPLETE -->"
+```
+
+---
+
+## Phase D6: Update Labels
+
+```bash
+gh issue edit {NUMBER} {GH_FLAG} \
+  --add-label "workflow:decomposed" \
+  --remove-label "workflow:ready-to-build,workflow:building,workflow:investigating" 2>/dev/null || true
+```
+
+---
+
+## Phase D7: STOP
+
+Decomposition is a terminal route for the parent issue. Each sub-issue will be picked up separately by /work-on.
+
+Return structured output to the router:
+
+```
+DECOMPOSE_RESULT:
+  status: COMPLETE | ALREADY_DONE | BLOCKED
+  sub_issues: [{number}, ...]
+  comment_url: {url of FORGE:DECOMPOSED comment}
+  blocker: {description if status=BLOCKED}
+```
+
+**Router behavior after DECOMPOSE_RESULT**: `break` — do not continue to build/review/close for the parent issue.
+
+---
+
+## Output
+
+The subcommand writes its results to GitHub (FORGE:DECOMPOSED comment + sub-issues created). The router breaks after this subcommand returns.
+
+```
+DECOMPOSE_RESULT:
+  status: COMPLETE | ALREADY_DONE | BLOCKED
+  sub_issues: [{number}, ...]
+  comment_url: {url of posted FORGE:DECOMPOSED comment}
+  blocker: {description if status=BLOCKED}
+```

package/commands/work-on/investigate.md

@@ -0,0 +1,437 @@
+---
+description: Investigate a GitHub issue — validate it's real, determine root cause, post findings
+argument-hint: [issue number] [--repo RapierCraftStudios/forge] [--gh-flag "-R RapierCraftStudios/forge"]
+---
+
+# /work-on:investigate — Issue Investigation Subcommand
+
+**Input**: $ARGUMENTS
+
+Standalone investigation phase for the work-on pipeline. Validates whether an issue is real, determines root cause, posts a structured FORGE:INVESTIGATOR comment to GitHub, and updates workflow labels.
+
+**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**NEVER use plan mode (EnterPlanMode).**
+
+---
+
+## Inputs
+
+Parse from $ARGUMENTS:
+- `{NUMBER}` — issue number (required)
+- `--repo {GH_REPO}` — GitHub repo (default: `RapierCraftStudios/forge` when running in Forge context; for AlterLab issues use `RapierCraft/AlterLab`)
+- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R RapierCraftStudios/forge`)
+
+If called from `work-on`, these are passed through. If invoked standalone, defaults apply.
+
+---
+
+## Phase 1A: Load Issue & Check Resume State
+
+```bash
+gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,comments
+gh api repos/{GH_REPO}/issues/{NUMBER}/comments --jq '.[] | {id: .id, body: .body}'
+```
+
+**Resume logic**:
+- If `<!-- FORGE:INVESTIGATOR -->` or `<!-- ALTERLAB:INVESTIGATOR -->` comment exists AND `<!-- INVESTIGATION:COMPLETE -->` is present in the SAME comment → investigation already complete, EXIT (return existing verdict to caller)
+- If `<!-- FORGE:INVESTIGATOR -->` or `<!-- ALTERLAB:INVESTIGATOR -->` comment exists BUT `<!-- INVESTIGATION:COMPLETE -->` is ABSENT → investigation was interrupted, delete the partial comment and restart:
+  ```bash
+  gh api repos/{GH_REPO}/issues/comments/{COMMENT_ID} -X DELETE
+  ```
+- If no investigator comment → proceed with fresh investigation
+
+**Set label**:
+```bash
+gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:investigating"
+gh issue edit {NUMBER} {GH_FLAG} --remove-label "workflow:ready-to-build,workflow:building,workflow:in-review" 2>/dev/null || true
+```
+
+---
+
+## Phase 1B: Investigate
+
+**Mission**: Validate whether the issue is real. Assume description is wrong until proven otherwise.
+
+### Resolve target repo and branch
+
+For Forge issues (repo = `RapierCraftStudios/forge`):
+- Key files: `commands/work-on.md`, `commands/review-pr.md`, `commands/quality-gate.md`, `commands/orchestrate.md`, `install.sh`, `CLAUDE.md`
+
+For AlterLab issues (repo = `RapierCraft/AlterLab`):
+
+| Domain | Key files |
+|--------|-----------|
+| BILLING | `routers/billing.py`, `core/pricing.py`, `services/credit_service.py` |
+| SCRAPING | `unified_consumer.py`, `queues.py`, `domain_playbooks.json` |
+| AUTH | `core/auth.py`, `routers/auth.py`, `dependencies.py` |
+| DATABASE | `infra/migrations/`, `models/`, `db/` |
+| FRONTEND | `web/src/app/`, `web/src/components/`, `web/src/lib/` |
+| CORTEX | `cortex_client.py`, `routers/cortex.py` |
+| INFRA | `.github/workflows/`, `docker-compose.yml`, `infra/traefik/` |
+
+### Investigation steps
+
+1. **Check the right branch** — read from the branch specified in the issue body (`**Code branch**: \`{branch}\``) if present
+2. **Read domain files** — start with the key files for the affected domain
+3. **Verify claims** — does the code actually have the problem described?
+4. **Git blame** — trace when/why the relevant code was written
+5. **Domain context discovery** (narrow scope only, 1–5 files):
+   ```bash
+   git log --oneline --all -30 -- {affected_files} | grep -oP '#\d+' | sort -u
+   gh issue list -R {GH_REPO} --state closed --limit 8 --search "{function_name}"
+   ```
+   Keep only file/function-level overlap. Max 5 related issues. Everything is a hint to verify, not a fact.
+6. **Determine root cause** — what's actually broken or missing?
+7. **Identify affected files** — full list of files that need changes
+8. **Fix-approach validation** — if the issue proposes a fix, don't adopt it as spec. Trace through the target system's middleware, auth, routing, config. Cross-domain: if fix in domain A interacts with domain B, read domain B's files too.
+
+---
+
+## Phase 1C: Post Investigation Comment
+
+The comment MUST include `<!-- INVESTIGATION:COMPLETE -->` at the very end, AFTER all required sections are present. This marker signals the investigation finished successfully.
+
+```bash
+gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:INVESTIGATOR -->
+## Investigation Report
+
+**Verdict**: {CONFIRMED|PARTIAL|INVALID}
+**Confidence**: {HIGH|MEDIUM|LOW}
+**Severity**: {CRITICAL|HIGH|MEDIUM|LOW}
+**Task Type**: {Bug Fix|Feature|Refactor|Maintenance|Investigation}
+
+### What Was Claimed
+{summary of what the issue describes}
+
+### What We Found
+{what the code actually shows}
+
+### Root Cause
+{specific root cause, with file:line references where applicable}
+
+### Affected Files
+{numbered list of files that need changes}
+
+### Evidence
+{specific findings — function names, line numbers, behavior observed}
+
+### Recommendation
+{what to build/fix, concrete and actionable}
+
+### Related Issues
+{if any found via domain context discovery, max 5}
+
+### Decomposition Assessment
+**{YES|NO}** — {reason}
+{if YES: proposed sub-issues with titles and dependencies}
+
+<!-- INVESTIGATION:COMPLETE -->"
+```
+
+---
+
+## Phase 1C.5: Create Knowledge Gist
+
+**Skip if**: A comment containing `<!-- FORGE:KNOWLEDGE_GIST:` already exists on this issue.
+
+After the FORGE:INVESTIGATOR comment is posted, create a structured GitHub Gist containing the investigation findings. The Gist provides a stable, linkable URL that downstream issues (siblings, children) can reference.
+
+**This phase is non-blocking** — if Gist creation fails (auth error, rate limit, network), log the failure and continue to Phase 1D. Do NOT stall the pipeline for a knowledge artifact.
+
+### Step 1: Check for existing Gist annotation
+
+```bash
+EXISTING_GIST=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:KNOWLEDGE_GIST:")) | .body' | head -1)
+
+if [ -n "$EXISTING_GIST" ]; then
+  echo "Knowledge Gist already exists — skipping creation"
+  # → Continue to Phase 1D
+fi
+```
+
+### Step 2: Extract investigation content
+
+```bash
+INVESTIGATION_BODY=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | (contains("FORGE:INVESTIGATOR") or contains("ALTERLAB:INVESTIGATOR"))) | .body' | head -1)
+```
+
+### Step 3: Generate filename and metadata
+
+```bash
+ISSUE_TITLE=$(gh issue view {NUMBER} {GH_FLAG} --json title --jq '.title')
+MILESTONE=$(gh issue view {NUMBER} {GH_FLAG} --json milestone --jq '.milestone.title // "none"')
+
+# Generate slug from title: lowercase, replace non-alphanumeric with hyphens, collapse, truncate
+SLUG=$(echo "$ISSUE_TITLE" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//' | cut -c1-40)
+
+# Derive repo short name from GH_REPO (e.g., "RapierCraftStudios/forge" → "forge")
+REPO_SHORT=$(echo "{GH_REPO}" | sed 's|.*/||')
+
+GIST_FILENAME="${REPO_SHORT}_${NUMBER}_${SLUG}.md"
+```
+
+### Step 4: Build Gist content with frontmatter
+
+Extract verdict, task type, and confidence from the investigation body, then compose the Gist:
+
+```bash
+VERDICT=$(echo "$INVESTIGATION_BODY" | grep -oP '(?<=\*\*Verdict\*\*: )\w+' | head -1)
+TASK_TYPE=$(echo "$INVESTIGATION_BODY" | grep -oP '(?<=\*\*Task Type\*\*: ).+' | head -1)
+CONFIDENCE=$(echo "$INVESTIGATION_BODY" | grep -oP '(?<=\*\*Confidence\*\*: )\w+' | head -1)
+SEVERITY=$(echo "$INVESTIGATION_BODY" | grep -oP '(?<=\*\*Severity\*\*: )\w+' | head -1)
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+GIST_CONTENT=$(cat <<GIST_EOF
+---
+issue: ${NUMBER}
+repo: {GH_REPO}
+milestone: ${MILESTONE}
+verdict: ${VERDICT}
+task_type: ${TASK_TYPE}
+confidence: ${CONFIDENCE}
+severity: ${SEVERITY}
+created: ${TIMESTAMP}
+source: FORGE:INVESTIGATOR
+---
+
+# Investigation: ${ISSUE_TITLE} (#${NUMBER})
+
+${INVESTIGATION_BODY}
+GIST_EOF
+)
+```
+
+### Step 5: Create secret Gist
+
+```bash
+GIST_URL=$(echo "$GIST_CONTENT" | gh gist create \
+  -f "$GIST_FILENAME" \
+  -d "Investigation findings for ${REPO_SHORT}#${NUMBER}: ${ISSUE_TITLE}" \
+  - 2>/dev/null)
+
+if [ -z "$GIST_URL" ]; then
+  echo "WARNING: Gist creation failed — continuing without knowledge artifact"
+  # → Continue to Phase 1D (non-blocking)
+fi
+```
+
+### Step 6: Post Gist URL annotation
+
+```bash
+if [ -n "$GIST_URL" ]; then
+  gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:KNOWLEDGE_GIST: ${GIST_URL} -->
+## Knowledge Gist Created
+
+Investigation findings persisted as a linkable artifact.
+
+**Gist**: ${GIST_URL}
+**Filename**: \`${GIST_FILENAME}\`
+
+_This Gist can be referenced by downstream issues for context transfer._"
+fi
+```
+
+→ Continue to Phase 1C.6.
+
+---
+
+## Phase 1C.6: Update Milestone Index Gist
+
+**Skip if**: The issue has no milestone (`MILESTONE` is `"none"` or empty).
+
+After the per-issue Knowledge Gist is created (Phase 1C.5), update the milestone-level index Gist. The index aggregates all investigation Gist URLs for a milestone into a single reference document. Any agent working on a milestone issue can fetch one index URL to get full context across all investigations.
+
+**This phase is non-blocking** — if index creation or update fails, log the warning and continue to Phase 1D. Do NOT stall the pipeline for the index.
+
+### Step 1: Check milestone and skip conditions
+
+```bash
+MILESTONE=$(gh issue view {NUMBER} {GH_FLAG} --json milestone --jq '.milestone.title // "none"')
+MILESTONE_NUM=$(gh issue view {NUMBER} {GH_FLAG} --json milestone --jq '.milestone.number // empty')
+
+if [ "$MILESTONE" = "none" ] || [ -z "$MILESTONE_NUM" ]; then
+  echo "No milestone on issue #${NUMBER} — skipping milestone index update"
+  # → Continue to Phase 1D
+fi
+```
+
+### Step 2: Read milestone description for existing index
+
+```bash
+MILESTONE_DESC=$(gh api repos/{GH_REPO}/milestones/${MILESTONE_NUM} --jq '.description // ""')
+EXISTING_INDEX_URL=$(echo "$MILESTONE_DESC" | grep -oP '(?<=<!-- FORGE:MILESTONE_INDEX: )https://[^ ]+(?= -->)' | head -1)
+```
+
+### Step 3: Build index entry for this issue
+
+```bash
+ISSUE_TITLE=$(gh issue view {NUMBER} {GH_FLAG} --json title --jq '.title')
+VERDICT=$(echo "$INVESTIGATION_BODY" | grep -oP '(?<=\*\*Verdict\*\*: )\w+' | head -1)
+SEVERITY=$(echo "$INVESTIGATION_BODY" | grep -oP '(?<=\*\*Severity\*\*: )\w+' | head -1)
+TASK_TYPE=$(echo "$INVESTIGATION_BODY" | grep -oP '(?<=\*\*Task Type\*\*: ).+' | head -1)
+RECOMMENDATION=$(echo "$INVESTIGATION_BODY" | sed -n '/^### Recommendation/,/^### /p' | head -5 | tail -n +2 | tr '\n' ' ' | cut -c1-120)
+
+# GIST_URL comes from Phase 1C.5 (may be empty if Gist creation failed)
+INDEX_ENTRY="| #${NUMBER} | ${ISSUE_TITLE} | ${VERDICT} / ${SEVERITY} | ${TASK_TYPE} | ${GIST_URL:-_no gist_} | ${RECOMMENDATION:-_see investigation_} |"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+```
+
+### Step 4a: Create new index Gist (no existing index)
+
+```bash
+if [ -z "$EXISTING_INDEX_URL" ]; then
+  MILESTONE_SLUG=$(echo "$MILESTONE" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//' | cut -c1-40)
+  REPO_SHORT=$(echo "{GH_REPO}" | sed 's|.*/||')
+  INDEX_FILENAME="${REPO_SHORT}_milestone_${MILESTONE_SLUG}_index.md"
+
+  INDEX_CONTENT=$(cat <<INDEX_EOF
+---
+type: milestone-index
+repo: {GH_REPO}
+milestone: ${MILESTONE}
+milestone_number: ${MILESTONE_NUM}
+last_updated: ${TIMESTAMP}
+---
+
+# Milestone Index: ${MILESTONE}
+
+Investigation findings index for all issues in this milestone.
+
+| Issue | Title | Verdict / Severity | Task Type | Gist URL | Key Finding |
+|-------|-------|--------------------|-----------|----------|-------------|
+${INDEX_ENTRY}
+INDEX_EOF
+)
+
+  INDEX_URL=$(echo "$INDEX_CONTENT" | gh gist create \
+    -f "$INDEX_FILENAME" \
+    -d "Milestone index: ${MILESTONE} (${REPO_SHORT})" \
+    - 2>/dev/null)
+
+  if [ -z "$INDEX_URL" ]; then
+    echo "WARNING: Milestone index Gist creation failed — continuing without index"
+    # → Continue to Phase 1D (non-blocking)
+  fi
+fi
+```
+
+### Step 4b: Update existing index Gist (index already exists)
+
+```bash
+if [ -n "$EXISTING_INDEX_URL" ]; then
+  INDEX_GIST_ID=$(echo "$EXISTING_INDEX_URL" | grep -oP '[a-f0-9]{20,}' | tail -1)
+
+  if [ -z "$INDEX_GIST_ID" ]; then
+    echo "WARNING: Could not extract Gist ID from index URL — skipping update"
+    # → Continue to Phase 1D
+  fi
+
+  # Fetch current index content
+  CURRENT_INDEX=$(gh gist view "$INDEX_GIST_ID" --raw 2>/dev/null)
+
+  if [ -z "$CURRENT_INDEX" ]; then
+    echo "WARNING: Could not fetch existing index Gist — skipping update"
+    # → Continue to Phase 1D
+  fi
+
+  # Check if this issue is already in the index
+  if echo "$CURRENT_INDEX" | grep -q "| #${NUMBER} |"; then
+    echo "Issue #${NUMBER} already in milestone index — skipping"
+    INDEX_URL="$EXISTING_INDEX_URL"
+    # → Continue to Phase 1D
+  else
+    # Update the last_updated timestamp in frontmatter
+    UPDATED_INDEX=$(echo "$CURRENT_INDEX" | sed "s|^last_updated:.*|last_updated: ${TIMESTAMP}|")
+
+    # Append new entry to the table
+    UPDATED_INDEX="${UPDATED_INDEX}
+${INDEX_ENTRY}"
+
+    # Determine the filename from the existing Gist
+    INDEX_FILENAME=$(gh api gists/${INDEX_GIST_ID} --jq '.files | keys[0]' 2>/dev/null)
+    if [ -z "$INDEX_FILENAME" ]; then
+      INDEX_FILENAME="milestone_index.md"
+    fi
+
+    # Update the Gist
+    echo "$UPDATED_INDEX" | gh gist edit "$INDEX_GIST_ID" -f "$INDEX_FILENAME" - 2>/dev/null
+    if [ $? -eq 0 ]; then
+      INDEX_URL="$EXISTING_INDEX_URL"
+      echo "Milestone index Gist updated: ${INDEX_URL}"
+    else
+      echo "WARNING: Failed to update milestone index Gist — continuing"
+      INDEX_URL="$EXISTING_INDEX_URL"
+    fi
+  fi
+fi
+```
+
+### Step 5: Store index URL in milestone description
+
+```bash
+if [ -n "$INDEX_URL" ]; then
+  if [ -n "$EXISTING_INDEX_URL" ]; then
+    # Replace existing annotation with updated URL (in case Gist was recreated)
+    UPDATED_DESC=$(echo "$MILESTONE_DESC" | sed "s|<!-- FORGE:MILESTONE_INDEX: [^ ]* -->|<!-- FORGE:MILESTONE_INDEX: ${INDEX_URL} -->|")
+  else
+    # Append annotation to milestone description
+    UPDATED_DESC="${MILESTONE_DESC}
+
+<!-- FORGE:MILESTONE_INDEX: ${INDEX_URL} -->"
+  fi
+
+  gh api repos/{GH_REPO}/milestones/${MILESTONE_NUM} \
+    -X PATCH \
+    -f description="$UPDATED_DESC" 2>/dev/null
+
+  if [ $? -eq 0 ]; then
+    echo "Milestone description updated with index URL: ${INDEX_URL}"
+  else
+    echo "WARNING: Failed to update milestone description — index URL not stored"
+  fi
+fi
+```
+
+→ Continue to Phase 1D.
+
+---
+
+## Phase 1D: Update Labels & Return Verdict
+
+**CONFIRMED or PARTIAL with decompose: NO**:
+```bash
+gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:ready-to-build" --remove-label "workflow:investigating"
+```
+Return verdict to caller (work-on routing loop proceeds to build).
+
+**CONFIRMED or PARTIAL with decompose: YES**:
+```bash
+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.
+Return verdict to caller (work-on routing loop proceeds to decompose).
+
+**INVALID**:
+```bash
+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).
+
+---
+
+## Output
+
+The subcommand writes its results to GitHub (FORGE:INVESTIGATOR comment). Output this structured block — the routing loop in `work-on.md` will read this result, re-evaluate state, and continue to the next phase. This subcommand is complete; control returns to the router's loop iteration.
+
+```
+INVESTIGATE_RESULT:
+  verdict: {CONFIRMED|PARTIAL|INVALID}
+  confidence: {HIGH|MEDIUM|LOW}
+  decompose: {YES|NO}
+  comment_url: {url of posted comment}
+  gist_url: {url of knowledge gist, or null if creation failed/skipped}
+  milestone_index_url: {url of milestone index gist, or null if no milestone/creation failed}
+```