forgedock 1.0.0

package/commands/work-on/build.md

@@ -0,0 +1,262 @@
+---
+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]
+---
+
+# work-on/build — Build Phase Orchestrator
+
+**Input**: $ARGUMENTS
+
+**Invoked by**: `work-on.md` state 8 (READY_TO_BUILD).
+**Output**: Create worktree, post contract, sequence build subcommands, return result to router.
+
+**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.**
+
+---
+
+## 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`)
+- `--base {PR_BASE}` — PR target branch (e.g. `milestone/modular-pipeline-architecture` or `staging`)
+
+---
+
+## Phase B0: 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
+
+# Check investigation report
+gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | (contains("FORGE:INVESTIGATOR") or contains("ALTERLAB:INVESTIGATOR"))) | .body'
+
+# Check if build already completed
+gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | (contains("FORGE:BUILDER") or contains("ALTERLAB:BUILDER"))) | .body'
+```
+
+**Resume check**:
+- If `<!-- FORGE:BUILDER -->` or `<!-- ALTERLAB:BUILDER -->` comment exists → build already complete. Return `BUILD_RESULT: status: ALREADY_DONE` to router.
+- If no `<!-- FORGE:INVESTIGATOR -->` or `<!-- ALTERLAB:INVESTIGATOR -->` comment with `<!-- INVESTIGATION:COMPLETE -->` → EXIT with `BUILD_RESULT: status: BLOCKED`, blocker: "Investigation not complete — run investigate first".
+
+Extract from investigation report:
+- Affected files list
+- Root cause
+- Recommendation
+- Task type (Bug Fix / Feature / Refactor / Maintenance / UI/UX / Full-Stack)
+
+---
+
+## Phase B1: Create Worktree & Branch
+
+### B1A: Derive branch name
+
+From issue title: lowercase, hyphenated, max 40 chars (truncate if needed).
+- Bug / fix issues → prefix `fix/`
+- Feature issues → prefix `feat/`
+- Refactor / maintenance → prefix `fix/` or `refactor/`
+
+Append `-{NUMBER}` to ensure uniqueness: e.g. `fix/work-on-build-landing-file-85`.
+
+### B1B: Determine source branch
+
+- Review-finding issue → parse `**Code branch**: \`{branch}\`` from issue body; branch from `origin/{branch}`
+  - **Milestone review-finding hybrid lane** (ONLY when Code branch matches `milestone/*`): This is a high-risk lane. The worktree will carry the full milestone history. The PR target is `staging` (or the base specified). **DANGER: Agents MUST NOT use `git merge` to resolve any conflicts in this lane.** Merge-based conflict resolution will pull the entire milestone commit tree onto staging, contaminating it with unapproved code. Use `git rebase` or `git cherry-pick` only. If conflicts cannot be resolved without a merge, post a comment on the issue, add `needs-human`, and STOP.
+- Feature lane (has milestone) → branch from `origin/{PR_BASE}`
+- Fast lane (no milestone) → branch from `origin/staging`
+
+### B1C: Create worktree
+
+```bash
+WORKTREE_PATH="/path/to/repo/.claude/worktrees/{BRANCH_SLUG}"
+git worktree add {WORKTREE_PATH} -b {BRANCH} origin/{SOURCE_BRANCH}
+```
+
+If worktree already exists at that path:
+```bash
+# Reuse existing worktree — verify it's on the correct branch
+git -C {WORKTREE_PATH} branch --show-current
+```
+If wrong branch, remove and recreate:
+```bash
+git worktree remove {WORKTREE_PATH} --force
+git worktree add {WORKTREE_PATH} -b {BRANCH} origin/{SOURCE_BRANCH}
+```
+
+### B1D: Set building label
+
+```bash
+gh issue edit {NUMBER} {GH_FLAG} \
+  --add-label "workflow:building" \
+  --remove-label "workflow:ready-to-build"
+```
+
+---
+
+## Phase B2: Post Builder Contract
+
+Post `<!-- FORGE:CONTRACT -->` comment documenting what will be built and why:
+
+```bash
+gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:CONTRACT -->
+## Builder Contract
+
+**Task type**: {TASK_TYPE}
+
+### Proposed Approach
+
+{BRIEF_APPROACH_DESCRIPTION}
+
+### Deliverables
+
+| File | Change | Why |
+|------|--------|-----|
+{DELIVERABLES_ROWS}
+
+### Acceptance Criteria
+
+{ACCEPTANCE_CRITERIA_CHECKLIST}
+
+### Quality Considerations
+
+{AUTH_MODEL_NEW_ENV_VARS_SQL_SAFETY_SECURITY_SURFACE}
+
+### Out of Scope
+
+{OUT_OF_SCOPE_ITEMS}"
+```
+
+Contract must be grounded in the investigation report. Every deliverable file must appear in the affected files list from the investigator. Adversarially validate the proposed fix against adjacent system layers before posting.
+
+---
+
+## Phase B2.5: Extract FUNCTION_NAMES from Contract
+
+After posting the Builder Contract, extract the primary function/class names from the contract's deliverables table. These are passed to the context subcommand for Phase C3 caller/importer discovery.
+
+```bash
+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_]*`' \
+  | tr -d '`' \
+  | sort -u \
+  | tr '\n' ' ' \
+  | xargs)
+# Scope is limited to the ### Deliverables section to avoid false matches from FORGE markers,
+# phase labels (B2, C3), and identifiers mentioned in Acceptance Criteria or Quality sections.
+# Fallback: if extraction yields nothing, FUNCTION_NAMES remains empty string
+# context.md Phase C3 skips gracefully when FUNCTION_NAMES is empty (for-loop produces zero iterations)
+```
+
+If `FUNCTION_NAMES` is non-empty, it will be passed via `--functions` to the context subcommand. If empty, the `--functions` flag is omitted — Phase C3 will naturally skip with zero iterations and no error.
+
+---
+
+## Phase B3: Context Gathering (MANDATORY Subcommand)
+
+**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.
+
+Invoke the context subcommand to surface historical review findings and bug patterns:
+
+```
+Skill("work-on:build:context", args="{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --repo-path {WORKTREE_PATH} {AFFECTED_FILES} --functions {FUNCTION_NAMES}")
+```
+
+If `FUNCTION_NAMES` is empty, omit the `--functions` flag entirely:
+
+```
+Skill("work-on:build:context", args="{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --repo-path {WORKTREE_PATH} {AFFECTED_FILES}")
+```
+
+**After subcommand returns**:
+- Returns structured context briefing (or indicates no relevant history) → continue to B4
+- If subcommand times out or errors → log warning, continue to B4 with empty context (non-blocking)
+# MUST CONTINUE to Phase B4 — context result is intermediate, NOT terminal.
+
+---
+
+## Phase B4: Architecture Planning (MANDATORY Subcommand)
+
+**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.
+
+Invoke the architect subcommand to trace all affected code paths and produce an ordered implementation plan:
+
+```
+Skill("work-on:build:architect", args="{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --repo-path {WORKTREE_PATH} --files {AFFECTED_FILES}")
+```
+
+**After subcommand returns**:
+- Returns ordered implementation plan → continue to B5
+- If subcommand returns BLOCKED → post comment, add `needs-human`, return `BUILD_RESULT: status: BLOCKED`
+# MUST CONTINUE to Phase B5 — architect result is intermediate, NOT terminal.
+
+---
+
+## Phase B5: Implementation (Subcommand)
+
+Invoke the implement subcommand to write code, stage, and post the builder comment:
+
+```
+Skill("work-on:build:implement", args="{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --worktree {WORKTREE_PATH} --branch {BRANCH}")
+```
+
+**After subcommand returns**:
+- `IMPLEMENT_RESULT: status: COMPLETE` → continue to B6
+- `IMPLEMENT_RESULT: status: ALREADY_DONE` → skip to B6 (validate what's already there)
+- `IMPLEMENT_RESULT: status: INVESTIGATION_COMPLETE` → issues created as deliverables; return `BUILD_RESULT: status: INVESTIGATION_COMPLETE`
+- `IMPLEMENT_RESULT: status: BLOCKED` → post comment with blocker description, add `needs-human`, return `BUILD_RESULT: status: BLOCKED`
+# MUST CONTINUE to Phase B6 — implement result is intermediate, NOT terminal (validation still required).
+
+---
+
+## Phase B6: Validation (Subcommand)
+
+Invoke the validate subcommand to run the quality gate loop, formatting, and deploy checks:
+
+```
+Skill("work-on:build:validate", args="{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --worktree {WORKTREE_PATH} --files {CHANGED_FILES}")
+```
+
+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: false` → subcommand has already posted comment and added `needs-human` label; return `BUILD_RESULT: status: BLOCKED`
+
+---
+
+## Output
+
+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.
+
+```
+BUILD_RESULT:
+  status: COMPLETE | ALREADY_DONE | INVESTIGATION_COMPLETE | BLOCKED
+  branch: {BRANCH}
+  worktree: {WORKTREE_PATH}
+  blocker: {description if status=BLOCKED}
+```
+
+---
+
+## Integration Point in work-on.md
+
+This module runs at **state 8 (READY_TO_BUILD)** in the routing loop:
+
+```
+state 8 → [THIS MODULE] worktree + contract + context + architect + implement + validate
+        → BUILD_RESULT: COMPLETE
+states 7, 6 → work-on:review (push + PR + /review-pr --auto-merge)
+states 5, 4 → work-on:close (trajectory + parent tracker + summary)
+```
+
+The router re-reads GitHub state after this module returns COMPLETE — it will then detect state 6 (IN_REVIEW) or 7 (BUILD_NO_PR) and invoke `work-on:review`.

package/commands/work-on/close.md

@@ -0,0 +1,350 @@
+---
+description: Close subcommand — update project board, final issue body, parent tracker, summary report, trajectory log
+argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--pr PR_NUMBER] [--base PR_BASE] [--branch BRANCH] [--worktree WORKTREE_PATH]
+---
+
+# work-on/close — Close & Trajectory Subcommand
+
+**Input**: $ARGUMENTS
+
+**Invoked by**: `work-on.md` Phase 6–7, after `review.md` returns `REVIEW_RESULT: status: COMPLETE`.
+**Output**: Update project board, close issue, update parent tracker, post trajectory log. Return final summary.
+
+**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`)
+- `--pr {PR_NUMBER}` — merged PR number
+- `--base {PR_BASE}` — branch the PR merged into (e.g. `milestone/modular-pipeline-architecture`)
+- `--branch {BRANCH}` — feature branch name (for worktree cleanup reference)
+- `--worktree {WORKTREE_PATH}` — absolute path to the git worktree to remove (optional — skip cleanup if not provided)
+
+---
+
+## Phase C0: Load State from GitHub (MANDATORY)
+
+Re-read current state before doing anything:
+
+```bash
+# Issue full context
+gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,milestone
+
+# PR state
+gh pr view {PR_NUMBER} {GH_FLAG} --json state,mergedAt,mergeCommit
+
+# All agent comments (to reconstruct pipeline results)
+gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | {body: .body, created_at: .created_at}'
+```
+
+Extract from agent comments:
+- From FORGE:INVESTIGATOR: verdict, confidence, task type
+- From FORGE:BUILDER: branch, commits, files changed
+- From FORGE:TRAJECTORY (if exists): prior trajectory entries
+
+**Resume check**:
+- If `<!-- FORGE:TRAJECTORY -->` comment already exists → trajectory already posted, EXIT with `CLOSE_RESULT: status: ALREADY_DONE`
+- If issue is already CLOSED and PR is MERGED → skip to C3 (just post trajectory if missing)
+
+---
+
+## Phase C1: Final Issue Body Update
+
+**Multi-phase guard**: Before checking off items, detect whether the issue has multiple phases. Only check off items belonging to the current completed phase — not all remaining items across future phases.
+
+```bash
+# Read current body
+BODY=$(gh issue view {NUMBER} {GH_FLAG} --json body --jq '.body')
+
+# Count remaining unchecked items BEFORE any edit
+REMAINING_BEFORE=$(echo "$BODY" | grep -c '^- \[ \]' || true)
+```
+
+**If `REMAINING_BEFORE == 0`** (no unchecked items): skip body edit — all items already checked, proceed to add PR reference only:
+```bash
+UPDATED_BODY="${BODY}"$'\n\n'"**PR**: #{PR_NUMBER} → merged to \`{PR_BASE}\`"
+gh issue edit {NUMBER} {GH_FLAG} --body "{UPDATED_BODY}"
+REMAINING_AFTER=0
+```
+
+**If `REMAINING_BEFORE > 0`**: check whether ANY `- [ ]` items will still remain after a full check-off — i.e., does the issue have multi-phase structure?
+
+Multi-phase issues have checkbox groups separated by phase headings (lines starting with `##` or `###`) where at least one group has unchecked items. Detect this:
+```bash
+# Conservative heuristic: if the issue body contains a phase heading (## or ###)
+# AND unchecked items remain, treat as multi-phase — do NOT check off items from
+# future phases; only add the PR reference and leave unchecked items intact.
+HAS_PHASE_HEADINGS=$(echo "$BODY" | grep -cP '^#{2,3} ' || true)
+
+if [ "$HAS_PHASE_HEADINGS" -gt 0 ]; then
+  # Multi-phase issue: do NOT check off any [ ] items
+  # Only add the PR reference so progress is recorded
+  UPDATED_BODY="${BODY}"$'\n\n'"**PR**: #{PR_NUMBER} → merged to \`{PR_BASE}\` (phase complete — remaining phases open)"
+  gh issue edit {NUMBER} {GH_FLAG} --body "{UPDATED_BODY}"
+  REMAINING_AFTER="$REMAINING_BEFORE"
+else
+  # Single-phase issue: check off all remaining [ ] items
+  UPDATED_BODY=$(echo "$BODY" | sed 's/^- \[ \]/- [x]/g')
+  UPDATED_BODY="${UPDATED_BODY}"$'\n\n'"**PR**: #{PR_NUMBER} → merged to \`{PR_BASE}\`"
+  gh issue edit {NUMBER} {GH_FLAG} --body "{UPDATED_BODY}"
+  REMAINING_AFTER=0
+fi
+```
+
+The `REMAINING_AFTER` variable is passed to Phase C2 to decide whether to close.
+
+---
+
+## Phase C1.5: Project Board Update (Status=Done, Workflow=Merged)
+
+Update the project board to reflect the merged state. This replaces the old Phase 5E project board update that existed before the modular refactor.
+
+```bash
+# Find the project item ID for this issue
+ISSUE_URL="https://github.com/{GH_REPO}/issues/{NUMBER}"
+ITEM_ID=$(gh project item-list 1 --owner RapierCraft --format json --limit 200 \
+  --jq ".items[] | select(.content.url == \"$ISSUE_URL\") | .id" 2>/dev/null | head -1)
+```
+
+If `ITEM_ID` is found:
+```bash
+# Set Status=Done
+gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" \
+  --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF6E --single-select-option-id 98236657 2>/dev/null || true  # Status=Done
+
+# Set Workflow=Merged
+gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" \
+  --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yGAA --single-select-option-id b510c537 2>/dev/null || true  # Workflow=Merged
+```
+
+If `ITEM_ID` is empty (issue not on project board) → log and skip:
+```bash
+echo "INFO: Issue #{NUMBER} not found on project board — skipping board update"
+```
+
+**Field reference** (project `PVT_kwHOCx3gR84BSK2L`):
+| Field | Field ID | Option | Option ID |
+|-------|----------|--------|-----------|
+| Status | `PVTSSF_lAHOCx3gR84BSK2Lzg_yF6E` | Done | `98236657` |
+| Workflow | `PVTSSF_lAHOCx3gR84BSK2Lzg_yGAA` | Merged | `b510c537` |
+
+---
+
+## Phase C2: Ensure Issue is Closed
+
+**Multi-phase guard**: If `REMAINING_AFTER > 0` (set in Phase C1), uncompleted phases remain — do NOT close the issue. Instead, post a phase-complete comment and exit early so the router can pick up the next phase on the next pipeline iteration.
+
+```bash
+ISSUE_STATE=$(gh issue view {NUMBER} {GH_FLAG} --json state --jq '.state')
+```
+
+**If `REMAINING_AFTER > 0`** (multi-phase: uncompleted phases remain):
+```bash
+# Post phase-complete marker — router state 10 (MULTI_PHASE) will re-detect this issue
+gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:PHASE:COMPLETE -->
+Phase complete. PR #{PR_NUMBER} merged to \`{PR_BASE}\`. ${REMAINING_AFTER} phase item(s) remain — leaving issue open for next pipeline iteration."
+
+# Update labels to reflect phase complete (not yet fully merged)
+gh issue edit {NUMBER} {GH_FLAG} \
+  --remove-label "workflow:in-review,workflow:building,workflow:investigating" 2>/dev/null || true
+
+# EXIT — do not close, do not post trajectory, do not run C3–C6
+# Return CLOSE_RESULT: status: PHASE_COMPLETE to caller
+exit 0
+```
+
+**If `REMAINING_AFTER == 0`** (all phases complete — single-phase or final phase of multi-phase):
+
+If state is `OPEN`:
+```bash
+gh issue close {NUMBER} {GH_FLAG} \
+  --comment "Closed: PR #{PR_NUMBER} merged to \`{PR_BASE}\`. Closes #{NUMBER}."
+```
+
+Add merged label:
+```bash
+gh issue edit {NUMBER} {GH_FLAG} \
+  --add-label "workflow:merged" \
+  --remove-label "workflow:in-review,workflow:building,workflow:investigating" 2>/dev/null || true
+```
+
+---
+
+## Phase C3: Parent Tracker Update (Sub-Issues Only)
+
+**Skip if**: Issue body does NOT contain a parent issue reference (e.g. `Part of #NNN`) or the issue has no parent in its milestone tracker.
+
+Detect parent reference:
+```bash
+PARENT_REF=$(gh issue view {NUMBER} {GH_FLAG} --json body --jq '.body' \
+  | grep -oP '(?i)(part of|spawned from|sub-issue of|parent issue[:]?|parent[:])\s*#\K\d+' \
+  | head -1)
+```
+
+If no parent reference found → log a warning and skip this phase:
+```bash
+echo "WARNING: No parent reference found in issue body — skipping parent tracker update"
+```
+
+If parent found:
+```bash
+# Read parent body
+PARENT_BODY=$(gh issue view {PARENT_REF} {GH_FLAG} --json body --jq '.body')
+
+# Check off this sub-issue in parent body (replace "- [ ] #{NUMBER}" with "- [x] #{NUMBER}")
+UPDATED_PARENT=$(echo "$PARENT_BODY" | sed "s/- \[ \] #${NUMBER}/- [x] #${NUMBER}/g")
+gh issue edit {PARENT_REF} {GH_FLAG} --body "$UPDATED_PARENT"
+
+# Check if all sub-issues are now closed
+OPEN_SUBS=$(echo "$UPDATED_PARENT" | grep -c '\- \[ \]' || true)
+```
+
+If `OPEN_SUBS == 0` (all sub-issues checked off):
+```bash
+gh issue close {PARENT_REF} {GH_FLAG} \
+  --comment "All sub-issues complete. Closing parent tracker. Last completed: #{NUMBER} (PR #{PR_NUMBER})."
+gh issue edit {PARENT_REF} {GH_FLAG} --add-label "workflow:merged"
+```
+
+---
+
+## Phase C4: Summary Report
+
+Reconstruct the pipeline summary from GitHub state:
+
+```bash
+# Get investigation verdict from FORGE:INVESTIGATOR comment (or legacy ALTERLAB:INVESTIGATOR)
+VERDICT=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | (contains("FORGE:INVESTIGATOR") or contains("ALTERLAB:INVESTIGATOR"))) | .body' \
+  | grep -oP '(?<=\*\*Verdict\*\*: )\w+' | head -1)
+
+CONFIDENCE=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | (contains("FORGE:INVESTIGATOR") or contains("ALTERLAB:INVESTIGATOR"))) | .body' \
+  | grep -oP '(?<=\*\*Confidence\*\*: )\w+' | head -1)
+
+# Get files changed from FORGE:BUILDER comment (or legacy ALTERLAB:BUILDER)
+FILES_CHANGED=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '.[] | select(.body | (contains("FORGE:BUILDER") or contains("ALTERLAB:BUILDER"))) | .body' \
+  | grep -oP '(?<=\*\*Files changed\*\*: )\d+' | head -1)
+```
+
+Output to stdout (returned to calling agent):
+
+```
+## Done: #{NUMBER} — {TITLE}
+- Investigation: {VERDICT} ({CONFIDENCE})
+- Lane: FEATURE
+- Fix: {BRANCH} → PR #{PR_NUMBER} → merged to `{PR_BASE}`
+- Files changed: {FILES_CHANGED}
+```
+
+---
+
+## Phase C5: Trajectory Log (MANDATORY)
+
+Post the `<!-- FORGE:TRAJECTORY -->` comment as the final pipeline record:
+
+```bash
+gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:TRAJECTORY -->
+## Pipeline Trajectory — #{NUMBER}
+
+| Phase | Result | Notes |
+|-------|--------|-------|
+| Phase 0: Context Load | ✅ Complete | Feature lane → \`{PR_BASE}\` |
+| Phase 1: Investigation | ✅ {VERDICT} ({CONFIDENCE}) | Task type: {TASK_TYPE} |
+| Phase 2: Decomposition | ⏭ Skipped | Single-concern change, no decomposition needed |
+| Phase 3: Build | ✅ Complete | Branch: \`{BRANCH}\` |
+| Phase 3F.5: Validate | ✅ Gate passed | Quality gate: pass |
+| Phase 4–5: Review + PR | ✅ Merged | PR #{PR_NUMBER} → \`{PR_BASE}\` |
+| Phase 6: Parent Tracker | {PARENT_STATUS} | {PARENT_NOTES} |
+| Phase C6: Cleanup | {CLEANUP_STATUS} | Worktree: {WORKTREE_PATH}, Branch: {BRANCH} |
+| Phase 7: Close | ✅ Complete | Issue closed |
+
+**Decisions**:
+- Decomposition skipped: {DECOMPOSE_REASON}
+- PR merged to: \`{PR_BASE}\` (feature lane, milestone branch)
+
+**Anomalies**: None
+
+**Pipeline completed**: {TIMESTAMP}"
+```
+
+Where:
+- `{PARENT_STATUS}` = `⏭ Skipped` (if no parent) or `✅ Complete` (if parent updated)
+- `{PARENT_NOTES}` = `No parent tracker` or `Checked off in #{PARENT_REF}`
+- `{CLEANUP_STATUS}` = `✅ Removed` (worktree removed + branch deleted) or `⏭ Skipped` (no path provided or path not found)
+- `{TIMESTAMP}` = current date/time in ISO format
+
+---
+
+## Phase C6: Worktree & Branch Cleanup
+
+Remove the git worktree and delete the local feature branch after the PR has merged. This prevents worktree accumulation across pipeline runs.
+
+**Skip if**: `{WORKTREE_PATH}` is not provided OR the path does not exist.
+
+```bash
+# Remove worktree (--force handles detached or uncommitted state)
+if [ -n "{WORKTREE_PATH}" ] && [ -d "{WORKTREE_PATH}" ]; then
+  # Use --git-common-dir to correctly resolve REPO_ROOT for linked worktrees.
+  # --show-toplevel returns the worktree path itself (not the main repo root),
+  # so xargs dirname would give the worktree's parent dir — not the repo root.
+  # --git-common-dir returns the shared .git dir (e.g. /repo/.git), and
+  # dirname of that is always the main repo root regardless of worktree depth.
+  GIT_COMMON=$(git -C {WORKTREE_PATH} rev-parse --git-common-dir 2>/dev/null)
+  REPO_ROOT=$(dirname "$(realpath "$GIT_COMMON" 2>/dev/null || echo "$GIT_COMMON")")
+  git -C "$REPO_ROOT" worktree remove {WORKTREE_PATH} --force 2>/dev/null || true
+  echo "Worktree removed: {WORKTREE_PATH}"
+
+  # Delete local feature branch (remote branch already deleted by GitHub on merge)
+  if [ -n "{BRANCH}" ]; then
+    git -C "$REPO_ROOT" branch -D {BRANCH} 2>/dev/null || true
+    echo "Local branch deleted: {BRANCH}"
+  fi
+else
+  echo "Worktree cleanup skipped: path not provided or does not exist"
+fi
+```
+
+Set `{CLEANUP_STATUS}` based on outcome:
+- Worktree path provided and existed → `✅ Removed` (worktree removed, branch deleted)
+- Worktree path not provided or path didn't exist → `⏭ Skipped`
+
+Update the trajectory log `{CLEANUP_STATUS}` field accordingly (the trajectory was already posted in C5, so this is recorded in the output summary, not by re-editing the comment).
+
+---
+
+## Output
+
+Return structured output to the caller:
+
+```
+CLOSE_RESULT:
+  status: COMPLETE | ALREADY_DONE | PHASE_COMPLETE
+  issue_state: closed | open
+  trajectory_url: {url of FORGE:TRAJECTORY comment}
+  parent_updated: {true|false}
+  parent_closed: {true|false}
+```
+
+Where `PHASE_COMPLETE` means the current phase was closed but uncompleted phases remain — the issue is left OPEN for the router to re-evaluate on the next pipeline iteration (state 10, MULTI_PHASE).
+
+---
+
+## Integration Point in work-on.md
+
+This module runs at **Phases 6–7** — after review.md returns `REVIEW_RESULT: status: COMPLETE`:
+
+```
+4–5  → Review (by review.md) — PR created, reviewed, merged, issue closed
+6–7  → [THIS MODULE] Final body update, parent tracker, summary, trajectory
+```
+
+This is the terminal phase — after CLOSE_RESULT returns, the pipeline is complete.