forgedock 1.0.0

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

@@ -0,0 +1,291 @@
+---
+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]
+---
+
+# work-on/build/architect — Multi-Path Implementation Planning
+
+**Invoked by**: `work-on.md` Step 3C.6, between Context Gathering and Implement.
+**Time budget**: Max 3 minutes. Skip any file read that times out.
+**Output**: Post `<!-- FORGE:ARCHITECT -->` comment on the issue, then return structured plan to caller.
+
+---
+
+## 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.
+
+**Principle**: A builder with an explicit plan produces consistent changes. Consistent changes produce zero cross-path review findings.
+
+---
+
+## Inputs
+
+Parse from $ARGUMENTS:
+- `{NUMBER}` — issue number (required, positional first arg)
+- `--repo {GH_REPO}` — GitHub repo (e.g. `RapierCraft/AlterLab`)
+- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R RapierCraft/AlterLab`)
+- `--repo-path {REPO_PATH}` — local filesystem path to the worktree (e.g. `/path/to/.claude/worktrees/fix/issue-121`); used by Phase A1 grep commands
+- `--files {AFFECTED_FILES}` — space-separated list of files from investigation report (passed by `build.md` Phase B4)
+
+Also read from the calling context (in-memory, passed by parent agent):
+- `{INVESTIGATION_REPORT}` — full text of FORGE:INVESTIGATOR comment
+- `{CONTEXT_BRIEFING}` — full text of FORGE:CONTEXT comment (empty string if context step was skipped)
+
+If any of these are not passed directly, read them from GitHub (fallback/recovery path):
+
+```bash
+# Read investigation report
+gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body'
+
+# Read context briefing (may be absent — that's OK)
+gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:CONTEXT")) | .body'
+```
+
+---
+
+## Resume Check
+
+Before doing any work:
+
+```bash
+gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | contains("FORGE:ARCHITECT")) | .body'
+```
+
+- If `<!-- FORGE:ARCHITECT -->` comment exists AND `<!-- FORGE:ARCHITECT:COMPLETE -->` is present in the SAME comment → plan already complete, return existing plan to caller, EXIT.
+- If `<!-- FORGE:ARCHITECT -->` comment exists BUT `<!-- FORGE:ARCHITECT:COMPLETE -->` is ABSENT → plan was interrupted, delete the partial comment and restart:
+  ```bash
+  COMMENT_ID=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+    --jq '.[] | select(.body | contains("FORGE:ARCHITECT")) | .id')
+  gh api repos/{GH_REPO}/issues/comments/$COMMENT_ID -X DELETE
+  ```
+
+---
+
+## Phase A1: Read Entry Points
+
+Identify every entry point that initiates the affected logic. Start from the files named in the investigation report.
+
+For each affected file, read it and identify:
+1. The primary function/method being changed
+2. All callers of that function (grep for usages)
+3. All sibling implementations (same interface, different path — e.g. HTTP vs worker vs relay)
+
+```bash
+# Find all callers of the primary function
+grep -r "{PRIMARY_FUNCTION}" {REPO_PATH} \
+  --include="*.py" --include="*.ts" --include="*.tsx" \
+  -l | grep -v "__pycache__" | grep -v ".pyc"
+
+# Find sibling implementations (same base class or interface)
+grep -r "class.*{BASE_CLASS}\|implements.*{INTERFACE}" {REPO_PATH} \
+  --include="*.py" --include="*.ts" \
+  -l | grep -v "__pycache__"
+```
+
+Read the 3–5 most relevant files identified. Do NOT read more than 8 files total — this is a planning step, not a deep audit.
+
+---
+
+## Phase A2: Trace the Data Flow
+
+From each entry point identified in A1, trace what happens to the data being changed:
+
+1. **Entry**: Where does the data first arrive? (API endpoint, queue consumer, webhook handler)
+2. **Transform**: What functions process it? Which fields are read/written?
+3. **Persist or relay**: Is it saved to DB? Forwarded to another service? Queued?
+4. **Exit**: Where does it leave the system? (response body, downstream call, emitted event)
+
+For each step in the flow, check:
+- Does the proposed change need to propagate here?
+- Is there a validation or coercion that must be updated consistently?
+- Is there a test that covers this path?
+
+Produce a table of ALL files/functions that must change to maintain consistency.
+
+---
+
+## Phase A2.5: Pipeline Phase-Dependency Check
+
+**Skip if**: None of the `{AFFECTED_FILES}` are Forge pipeline command files (i.e., no file matches `commands/**/*.md`). When skipped, proceed directly to A3.
+
+**Applies when**: The change touches one or more files in `commands/` — these files define the pipeline's phase contracts, and a change to one phase frequently requires coordinated updates to sibling or downstream phases.
+
+### Why This Phase Exists
+
+GATE_LOGIC defects (phase-ordering errors, dropped functionality, missing implementations) are the #1 review finding category in the Forge pipeline. They occur when a change is applied to one pipeline phase but the downstream phases that depend on that phase's output contract are not updated. Code-level grep (A1) cannot catch these because pipeline dependencies are expressed in markdown artefact contracts — comment markers, structured output blocks, Skill() invocation signatures, and label state machine transitions — not in code imports.
+
+### Steps
+
+**P1: Identify artefact contracts produced by the changed file**
+
+For each affected `commands/*.md` file, identify what it produces that other phases consume:
+
+1. **Comment markers** — HTML comment markers the phase writes to GitHub (e.g., `<!-- FORGE:ARCHITECT -->`, `<!-- FORGE:ARCHITECT:COMPLETE -->`). Search for `<!-- FORGE:` patterns in the affected file.
+2. **Structured output blocks** — named result blocks returned to the caller (e.g., `BUILD_RESULT:`, `VALIDATE_RESULT:`, `IMPLEMENT_RESULT:`). Search for lines ending in `:` that start a return block.
+3. **Skill() invocation signatures** — parameters the file passes when invoking subcommands (e.g., `Skill("work-on:build:architect", args="... --files ...")`). Search for `Skill(` calls.
+4. **Label state machine transitions** — `gh issue edit ... --add-label ... --remove-label ...` calls that define which label is set at the end of this phase.
+
+**P2: Find downstream phases that consume these artefacts**
+
+For each artefact identified in P1:
+
+```bash
+# Find which pipeline files reference this comment marker or output field
+grep -r "{MARKER_OR_FIELD}" /path/to/repo/commands/ \
+  --include="*.md" -l | grep -v {AFFECTED_FILE}
+
+# Example: if FORGE:ARCHITECT is the marker
+grep -r "FORGE:ARCHITECT" commands/ --include="*.md" -l
+```
+
+For each consumer file found: note the file and the specific phase/section that reads the artefact.
+
+**P3: Check for invocation signature changes**
+
+If the change modifies what parameters a phase accepts (adds, removes, or renames a `--flag` in its Inputs section), find all callers:
+
+```bash
+grep -r "Skill.*{SUBCOMMAND_NAME}" commands/ --include="*.md" -l
+```
+
+For each caller: verify the invocation still matches the new signature. Flag any caller that passes a parameter that is being renamed or removed.
+
+**P4: Emit phase-dependency checklist**
+
+For each downstream phase identified in P2 and P3, emit a checklist item. These items are appended to the `### Consistency Checks` section of the `<!-- FORGE:ARCHITECT -->` comment output:
+
+```
+- [ ] {DOWNSTREAM_FILE} Phase {N}: still reads `{ARTEFACT}` correctly after this change
+- [ ] {CALLER_FILE} Phase {N}: invocation of `{SUBCOMMAND}` passes correct params after signature change
+- [ ] Label state: `{LABEL}` set at end of changed phase matches what `{CONSUMER_FILE}` Phase {N} expects as entry condition
+```
+
+If no downstream phases are found (the change is additive only — new sections, new checklist items, no existing contract modified), emit:
+```
+- [ ] Phase-dependency check: ADDITIVE ONLY — no existing artefact contracts modified; no downstream updates required
+```
+
+---
+
+## Phase A3: Consistency Rules
+
+Identify invariants that ALL affected paths must satisfy. These become the builder's consistency checklist.
+
+Common invariants to check:
+- **Null handling**: All paths handle missing field the same way (None vs empty string vs omission)
+- **Validation**: All paths apply the same size/type/format constraints
+- **Logging**: All paths log the same fields at the same level
+- **Error response**: All paths return the same error shape for the same failure mode
+- **Auth check**: All paths enforce the same permission model
+
+For each invariant: state the rule and note which files it applies to.
+
+---
+
+## Phase A4: Sequence the Implementation
+
+Order the changes to minimize breakage during implementation:
+
+1. **Schema/type changes first** — any shared types, Pydantic models, TypeScript interfaces
+2. **Core logic** — the primary path (usually the API router or main function)
+3. **Secondary paths** — worker consumers, relay handlers, batch endpoints
+4. **Tests** — update or add tests for each changed path
+5. **Config/env** — any new environment variables or feature flags
+
+Rules for ordering:
+- A file that is imported by others must be changed before its importers
+- Tests change last (after the code they test is stable)
+- If two paths are independent, order by risk (higher risk first so review catches it early)
+
+---
+
+## Phase A5: Risk Assessment
+
+For each non-obvious interaction or potential failure mode:
+- State the risk in one sentence
+- Rate it: HIGH / MEDIUM / LOW
+- Suggest a mitigation or check
+
+Focus on:
+- Files that have changed recently (check `git log --oneline -10 -- {FILE}`)
+- Paths that are called in both sync and async contexts
+- Any place where the change touches a serialization boundary (JSON in/out, DB read/write)
+- Unused or dormant code that the change might activate
+
+---
+
+## Output Format
+
+Post the following as a GitHub comment on `{NUMBER}`:
+
+```bash
+gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:ARCHITECT -->
+## Implementation Plan for #{NUMBER}
+
+### Affected Paths (ALL must be updated)
+| # | File | Function/Class | Change Required | Why |
+|---|------|----------------|-----------------|-----|
+| 1 | {FILE} | {FUNCTION} | {CHANGE} | {REASON} |
+
+### Implementation Order
+1. {FIRST_CHANGE} — {WHY_FIRST}
+2. {SECOND_CHANGE} — {WHY_SECOND}
+...
+
+### Consistency Checks
+<!-- Builder must verify each of these before committing -->
+- [ ] {INVARIANT_1}
+- [ ] {INVARIANT_2}
+- [ ] {INVARIANT_3}
+
+### Risk Assessment
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+| {RISK_DESCRIPTION} | HIGH/MEDIUM/LOW | {MITIGATION} |
+
+### Files to Read Before Coding
+<!-- Builder MUST read these files before writing any code -->
+- \`{FILE}\` — {WHY_READ_IT}
+
+<!-- FORGE:ARCHITECT:COMPLETE -->
+"
+```
+
+---
+
+## Timing Rules
+
+- Each file read: skip if the file exceeds 500 lines and only the first 100 lines are needed for structure
+- Each `grep -r` call: timeout after 10s, skip if exceeded
+- Total wall time budget: **3 minutes**. If budget exceeded, post partial results with `<!-- FORGE:ARCHITECT:PARTIAL -->` marker instead of `COMPLETE`.
+
+---
+
+## Skip Conditions
+
+Skip this entire step (post nothing, return empty plan to caller) if:
+- 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:"
+- `{AFFECTED_FILES}` is empty
+
+When skipped, the builder proceeds with investigation report + context briefing only.
+
+---
+
+## Integration Point in work-on.md
+
+This module runs at **Step 3C.6** — after Context Gathering, before Implement:
+
+```
+3C    → Builder Contract posted
+3C.5  → Context Gathering (FORGE:CONTEXT comment)
+3C.6  → [THIS MODULE] Architecture Planning (FORGE:ARCHITECT comment)
+3F    → Implement (builder reads plan, implements ALL affected paths)
+```
+
+The builder agent reads the `<!-- FORGE:ARCHITECT -->` comment as its **primary input** before writing any code. The raw issue body is secondary context. If the architect step was skipped, the builder falls back to investigation report + contract.

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

@@ -0,0 +1,349 @@
+---
+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...]
+---
+
+# work-on/build/context — Pre-Implementation Context Gathering
+
+**Invoked by**: `work-on.md` Step 3C.5, between Builder Contract and Implement.
+**Time budget**: Max 2 minutes of queries. Skip any query that times out.
+**Output**: Post `<!-- FORGE:CONTEXT -->` comment on the issue, then return structured briefing to caller.
+
+---
+
+## 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 -->
+
+**Principle**: A builder with context produces fewer review findings. Fewer findings = fewer fix cycles = lower token cost.
+
+---
+
+## Inputs
+
+Parse from `$ARGUMENTS`:
+- `{NUMBER}` — issue number (positional, required)
+- `--repo {GH_REPO}` — GitHub repo (e.g. `RapierCraft/AlterLab`)
+- `--gh-flag {GH_FLAG}` — gh CLI repo flag (e.g. `-R RapierCraft/AlterLab`)
+- `--repo-path {REPO_PATH}` — local filesystem path to the worktree (e.g. `/path/to/.claude/worktrees/fix/issue-121`); used by Phase C3 grep commands
+- `{AFFECTED_FILES}` — space-separated file paths (positional, after `{NUMBER}`, before any `--functions` flag)
+- `--functions {FUNCTION_NAMES}` — space-separated function/class names extracted from the Builder Contract deliverables table (optional)
+
+**Graceful skip for empty FUNCTION_NAMES**: If `--functions` is absent or `{FUNCTION_NAMES}` is empty, Phase C3 produces zero for-loop iterations and is effectively skipped — no error, no output for that phase. This is expected behavior when the contract does not name specific functions.
+
+---
+
+## Phase C0: Prior Investigation Findings (from Gists)
+
+Scan the issue body for `<!-- FORGE:PRIOR_GIST: {url} -->` annotations embedded by the decompose or orchestrate phases (GIST-02). Also check for `<!-- FORGE:MILESTONE_INDEX: {url} -->` annotations — these reference a milestone-level index Gist (GIST-04) that aggregates all investigation Gist URLs for a milestone into a single reference. Both annotation types reference Knowledge Gists created during upstream investigation (GIST-01) and contain structured findings — verdict, root cause, recommendation, affected files — that the builder needs before writing code.
+
+**Time budget**: 30 seconds total for all Gist fetches. Each individual fetch times out after 15 seconds.
+
+**Skip if**: Issue body contains no `FORGE:PRIOR_GIST` or `FORGE:MILESTONE_INDEX` annotations, AND the issue's milestone description contains no `FORGE:MILESTONE_INDEX` annotation. Zero iterations, no output — this is expected for issues without prior investigation context.
+
+### Step 0: Check for milestone index Gist
+
+Before scanning individual Gist annotations, check if the issue's milestone has an index Gist. If so, fetch the index and extract individual Gist URLs from the table rows.
+
+```bash
+ISSUE_BODY=$(gh issue view {NUMBER} -R {GH_REPO} --json body --jq '.body')
+MILESTONE_NUM=$(gh issue view {NUMBER} -R {GH_REPO} --json milestone --jq '.milestone.number // empty')
+
+MILESTONE_INDEX_URL=""
+INDEX_GIST_URLS=""
+
+# Check issue body for milestone index annotation
+MILESTONE_INDEX_URL=$(echo "$ISSUE_BODY" \
+  | grep -oP '(?<=<!-- FORGE:MILESTONE_INDEX: )https://[^ ]+(?= -->)' \
+  | 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://[^ ]+(?= -->)' \
+    | 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)
+  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/]+' \
+        | head -10)
+      echo "Milestone index fetched: found $(echo "$INDEX_GIST_URLS" | wc -l) investigation Gist(s)"
+    else
+      echo "WARNING: Failed to fetch milestone index Gist — falling back to individual annotations"
+    fi
+  fi
+fi
+```
+
+### Step 1: Detect Gist URLs in issue body
+
+```bash
+GIST_URLS=$(echo "$ISSUE_BODY" \
+  | grep -oP '(?<=<!-- FORGE:PRIOR_GIST: )https://[^ ]+(?= -->)' \
+  | head -5)
+
+# Merge with any URLs discovered from milestone index (deduplicate)
+if [ -n "$INDEX_GIST_URLS" ]; then
+  GIST_URLS=$(echo -e "${GIST_URLS}\n${INDEX_GIST_URLS}" | sort -u | head -5)
+fi
+
+if [ -z "$GIST_URLS" ]; then
+  echo "No FORGE:PRIOR_GIST or FORGE:MILESTONE_INDEX annotations found — skipping Phase C0"
+  # → Continue to Phase C1
+fi
+```
+
+**Max Gists**: 5 per issue. If more than 5 are present (from combined individual + index sources), process only the first 5 to stay within time budget.
+
+### Step 2: Fetch and summarize each Gist
+
+For each Gist URL, extract the Gist ID (last path segment) and fetch the raw content:
+
+```bash
+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)
+
+  if [ -z "$GIST_ID" ]; then
+    echo "WARNING: Could not extract Gist ID from URL: $url — skipping"
+    continue
+  fi
+
+  # Fetch Gist content with timeout
+  GIST_CONTENT=$(timeout 15 gh gist view "$GIST_ID" --raw 2>/dev/null)
+
+  if [ -z "$GIST_CONTENT" ]; then
+    echo "WARNING: Failed to fetch Gist $GIST_ID — skipping (deleted, private, or network error)"
+    GIST_SUMMARIES="${GIST_SUMMARIES}
+- **Gist ${GIST_ID}** (${url}): _Fetch failed — Gist may be deleted or inaccessible_"
+    continue
+  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)
+
+  # Extract structured sections: Root Cause, Recommendation, Affected Files
+  ROOT_CAUSE=$(echo "$GIST_CONTENT" \
+    | sed -n '/^### Root Cause/,/^### /p' \
+    | head -10 | tail -n +2 | head -8)
+  RECOMMENDATION=$(echo "$GIST_CONTENT" \
+    | sed -n '/^### Recommendation/,/^### /p' \
+    | head -10 | tail -n +2 | head -8)
+  AFFECTED_FILES=$(echo "$GIST_CONTENT" \
+    | sed -n '/^### Affected Files/,/^### /p' \
+    | head -10 | tail -n +2 | head -8)
+
+  GIST_SUMMARIES="${GIST_SUMMARIES}
+
+#### Investigation #${SOURCE_ISSUE:-unknown} (${VERDICT:-unknown} / ${SEVERITY:-unknown})
+**Source**: ${url}
+**Task type**: ${TASK_TYPE:-unknown}
+
+**Root Cause**:
+${ROOT_CAUSE:-_Not extracted — read Gist directly_}
+
+**Recommendation**:
+${RECOMMENDATION:-_Not extracted — read Gist directly_}
+
+**Affected Files**:
+${AFFECTED_FILES:-_Not extracted — read Gist directly_}"
+done
+```
+
+### Step 3: Store for output
+
+If `GIST_SUMMARIES` is non-empty, it will be included in the `### Prior Investigation Findings` section of the FORGE:CONTEXT comment (see Output Format below). If empty (all fetches failed or no annotations found), the section is omitted from the output.
+
+---
+
+## Phase C1: Past Review Findings on These Files
+
+Query closed issues with `review-finding` label, searching by filename:
+
+```bash
+for file in {AFFECTED_FILES}; do
+  basename=$(basename "$file" .py)
+  gh issue list -R {GH_REPO} \
+    --state closed \
+    --label "review-finding" \
+    --search "$basename" \
+    --limit 10 \
+    --json number,title,body \
+    --jq '.[] | {
+      number,
+      title,
+      pattern:    (.body | capture("\\*\\*Pattern\\*\\*: *(?<p>[^\\n]+)").p    // null),
+      prevention: (.body | capture("\\*\\*Prevention\\*\\*: *(?<v>[^\\n]+)").v // null),
+      root_cause: (.body | capture("\\*\\*Root cause\\*\\*: *(?<rc>[^\\n]+)").rc // (.body | capture("Root Cause[^\\n]*\\n(?<rc>[^\\n]+)").rc // "see body"))
+    }'
+done
+```
+
+Keep findings where the filename or function name appears in the title or body. Discard false matches (same word, different module).
+
+**Pattern extraction note**: Issues created by `/review-pr` after the feedback-loop feature include structured `**Pattern**`, `**Root cause**`, and `**Prevention**` fields in the `## Pattern Metadata` section. Extract all three when present — they are the primary signal. Fall back to `root_cause` regex for older issues that predate this feature.
+
+**Max results**: 10 findings total across all files.
+
+---
+
+## Phase C2: Past Bugs in the Same Module
+
+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+' \
+  | sort -u \
+  | head -8
+
+# Step 2: for each issue number found, fetch title and any root cause annotation
+gh issue view {RELATED_NUMBER} -R {GH_REPO} \
+  --json number,title,body,labels \
+  --jq '{number, title, labels: [.labels[].name], snippet: (.body[:300])}'
+```
+
+Filter: keep only `bug`, `fix`, or `review-finding` labeled issues. Skip feature issues — they add noise without bug signal.
+
+**Max results**: 5 issues.
+
+---
+
+## Phase C3: Related Code Paths
+
+Identify callers, importers, and sibling implementations that must stay consistent with the changed code:
+
+```bash
+# Python: find importers of modified functions/classes
+for fn in {FUNCTION_NAMES}; do
+  grep -r "$fn" {REPO_PATH} \
+    --include="*.py" \
+    -l \
+    | grep -v "__pycache__" \
+    | grep -v {AFFECTED_FILES} \
+    | head -5
+done
+
+# TypeScript: find usages
+for fn in {FUNCTION_NAMES}; do
+  grep -r "$fn" {REPO_PATH}/web/src \
+    --include="*.ts" --include="*.tsx" \
+    -l \
+    | head -5
+done
+```
+
+For each related file found: note the file path and the nature of the relationship (caller, sibling, test).
+
+**Max results**: 8 related files.
+
+---
+
+## Phase C4: Successful Similar Implementations
+
+Find merged PRs that touched the same domain with a successful outcome — use as a positive pattern reference:
+
+```bash
+gh pr list -R {GH_REPO} \
+  --state merged \
+  --search "{domain_keywords}" \
+  --limit 5 \
+  --json number,title,files \
+  --jq '.[] | {number, title, file_count: (.files | length)}'
+```
+
+Use 2-3 keywords from the issue title. If no results, skip this phase — do not block on it.
+
+---
+
+## Output Format
+
+Post the following as a GitHub comment on `{NUMBER}`:
+
+```bash
+gh issue comment {NUMBER} -R {GH_REPO} --body "<!-- FORGE:CONTEXT -->
+## Implementation Context for #{NUMBER}
+
+### Prior Investigation Findings
+<!-- Summarized Knowledge Gist content from upstream investigations (Phase C0).
+     If no FORGE:PRIOR_GIST annotations were found in the issue body: omit this section entirely.
+     If Gist fetches failed: include the failure note so the builder knows context was attempted. -->
+{GIST_SUMMARIES}
+
+### Known Pitfalls for This Area
+<!-- Structured prevention rules extracted from past review-finding issues (Pattern Metadata section).
+     If a finding has a Prevention field, list it here. Builder MUST read these before writing code.
+     If none: 'No structured pitfalls recorded — first time these files are touched or all findings predate the feedback loop.' -->
+- **{PATTERN}** (`{FILE}`): {PREVENTION}
+
+### Historical Findings on These Files
+<!-- List of past review-finding issues from C1. If none: 'No prior findings.' -->
+- #{NUM}: \"{TITLE}\" — root cause: {ROOT_CAUSE}
+
+### Past Bugs in This Module
+<!-- List of closed bug issues from git log mining. If none: 'No prior bugs found in git history.' -->
+- #{NUM}: \"{TITLE}\" — root cause: {SNIPPET}
+
+### Related Code Paths (must stay consistent)
+<!-- Files that import or call the changed functions. Builder must read and validate these. -->
+- \`{FILE}\` — {RELATIONSHIP}
+
+### Patterns That Cause Bugs Here
+<!-- Synthesize from C1+C2: recurring bug types (e.g. 'String/int coercion at JSON boundaries — 3 prior incidents'). If none: 'No recurring patterns identified.' -->
+
+### Successful Similar Implementations
+<!-- Positive patterns from C4. If none: 'No similar merged PRs found.' -->
+- PR #{NUM}: \"{TITLE}\" — {FILE_COUNT} files, notes: {OBSERVATION}
+
+<!-- FORGE:CONTEXT:COMPLETE -->
+"
+```
+
+---
+
+## Timing Rules
+
+- Phase C0 `gh gist view` calls: timeout after 15s each, 30s total budget for all Gist fetches
+- Each `gh issue list` call: timeout after 20s, skip if exceeded
+- Each `gh pr list` call: timeout after 20s, skip if exceeded
+- Each `grep -r` call: timeout after 10s, skip if exceeded
+- Total wall time budget: **2 minutes** (C0 through C4 combined). If budget exceeded, post partial results with `<!-- FORGE:CONTEXT:PARTIAL -->` marker instead of `COMPLETE`.
+
+---
+
+## Skip Conditions
+
+Skip this entire step (post nothing, return empty briefing) if:
+- 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)
+
+---
+
+## Integration Point in work-on.md
+
+This module runs at **Step 3C.5** — after Builder Contract is posted, before Implement:
+
+```
+3C  → Builder Contract posted
+3C.5 → [THIS MODULE] Context gathering (max 2 min)
+3F  → Implement (builder now has context briefing)
+```
+
+The builder agent reads the `<!-- FORGE:CONTEXT -->` comment before writing any code. If the context step was skipped, the builder proceeds with investigation report + contract only.
+
+When prior investigation Gists are available (Phase C0), the `### Prior Investigation Findings` section gives the builder cross-issue context — root causes, recommendations, and affected files from upstream investigations — without requiring manual Gist lookups. When a milestone-level index Gist exists (GIST-04), Phase C0 can resolve the index to discover all investigation Gists for the milestone from a single URL — providing full milestone-wide context automatically. <!-- Updated: forge#341 -->