devflow-kit 1.8.3 → 2.0.1

package/src/assets/commands/resolve.mds

@@ -0,0 +1,636 @@
+---
+description: Process review issues - validate with Triage agent, fix with Code agent, verify with Validate agent
+output-dir: dist/commands
+---
+@import { knowledge_load, knowledge_writeback } from "./_partials/_knowledge.mds"
+@import { decisions_load } from "./_partials/_decisions.mds"
+@import { compliance_gate } from "./_partials/_compliance.mds"
+@import { publication_gate } from "./_partials/_publication.mds"
+
+# Resolve Command
+
+Process issues from code review reports: triage every issue through the blast-radius disposition matrix, fix FIX_NOW items with Code agents, verify fixes with a Validate agent gate, and track FIX_SEPARATE/TECH_DEBT items as manage-debt tickets. Defaults to the latest timestamped review directory. Supports multi-worktree auto-discovery.
+
+## Usage
+
+```
+/resolve                        (resolve latest review on current branch — or all worktrees)
+/resolve #42                    (resolve issues for specific PR)
+/resolve --review 2026-03-28_0900  (resolve a specific review run by timestamp)
+/resolve --path /path/to/worktree  (resolve a specific worktree only)
+```
+
+## Phases
+
+### Phase 0: Worktree Discovery & Pre-Flight
+
+#### Step 0a: Discover Worktrees
+
+**Produces:** WORKTREES
+
+1. **Discover resolvable worktrees** using the `devflow:worktree-support` skill discovery algorithm:
+   - Run `git worktree list --porcelain` → parse, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
+   - See `~/.claude/skills/devflow:worktree-support/SKILL.md` for the full 7-step algorithm and canonical protected branch list
+   - Additional filter: must have unresolved reviews (latest review directory has no `resolution-summary.md`)
+2. **If `--path` flag provided:** use only that worktree, skip discovery
+   **`--path` validation**: Before proceeding, verify the path exists as a directory and appears in `git worktree list` output. If not: report error and stop.
+3. **If only 1 resolvable worktree** (the common case): proceed as single-worktree flow — zero behavior change
+4. **If multiple resolvable worktrees:** report "Found N worktrees with unresolved reviews: \{list\}" and proceed with multi-worktree flow
+
+#### Step 0b: Per-Worktree Pre-Flight (Git Agent)
+
+**Produces:** BRANCH_INFO, PR_DESCRIPTION, DIFF_FILES
+**Requires:** WORKTREES
+
+For each resolvable worktree, spawn Git agent:
+
+```
+Agent(subagent_type="Git", run_in_background=false):
+"OPERATION: validate-branch
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+Check feature branch, clean working directory, reviews exist.
+Return: branch, branch-slug, PR#, review count, DIFF_FILES"
+```
+
+In multi-worktree mode, spawn all pre-flight agents **in a single message** (parallel).
+
+**If BLOCKED:** In single-worktree mode, stop and report the blocker to user. If no reviews found, suggest `/code-review` or `/bug-analysis` first. In multi-worktree mode, report the failure but continue with other worktrees.
+
+**Extract from response:** `branch`, `branch_slug`, `pr_number`, `review_count`, `diff_files` per worktree.
+
+**Fetch PR body** (after extracting `pr_number`):
+```bash
+PR_DESCRIPTION=$(gh pr view {pr_number} --json body --jq '.body' 2>/dev/null || echo "(none)")
+```
+If `pr_number` is absent or the command fails, set `PR_DESCRIPTION` to `(none)`.
+
+**DIFF_FILES** is extracted from the `### Diff Scope` block in the Git agent validate-branch output. Set to empty string `""` if the block is absent (bug-analysis mode edge case).
+
+#### Step 0c: Target Review Directory
+
+**Produces:** TARGET_DIR
+**Requires:** BRANCH_INFO
+
+For each worktree:
+
+1. List directories in `\{worktree\}/.devflow/docs/reviews/\{branch-slug\}/`
+2. **If `--review \{timestamp\}` provided:** use that specific directory (not supported in multi-worktree mode)
+3. **Otherwise:** sort directories by name descending (timestamps are naturally sortable), scan the 10 most recent directories only. Select the first that contains `review-summary.md` (complete review)
+4. **If latest directory already has `resolution-summary.md`:** the review is resolved — check bug-analysis fallback (step 5b).
+5. **Legacy fallback:** if no timestamped subdirectories exist but flat `*.md` files do in `\{worktree\}/.devflow/docs/reviews/\{branch-slug\}/`, read them directly (backwards compatible).
+
+**5b. Bug analysis fallback** — if no qualifying review directory found (no reviews exist, or all resolved):
+- List directories in `\{worktree\}/.devflow/docs/bug-analysis/\{branch-slug\}/`
+- Sort by name descending (timestamps are naturally sortable), scan the 10 most recent directories only. Select the latest that:
+  - Contains at least one focus report (`security.md`, `functional.md`, `integration.md`, or `usability.md`)
+  - Does NOT contain a `resolution-summary.md`
+- If found: set `TARGET_DIR` to that path. Reviews take priority — bug analysis is only used when no qualifying review exists.
+- If not found within those 10 directories: skip worktree — report "No unresolved review or bug analysis found. Run `/code-review` or `/bug-analysis` first."
+
+Set `TARGET_DIR` to the selected review or bug-analysis directory path.
+
+#### Step 0d: Load Project Decisions
+
+**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, COMPLIANCE_SKILL_INSTALLED, REVIEW_PUBLICATION
+
+{decisions_load()}
+
+This produces a compact index of active ADR/PF entries written at render time — Deprecated/Superseded entries are already stripped. Pass `DECISIONS_CONTEXT` to the Triage agent in Phase 2 and to Code agents in Phase 4.
+
+{knowledge_load()}
+
+Pass `FEATURE_KNOWLEDGE` to the Triage agent in Phase 2.
+
+{compliance_gate()}
+Reuse this result for every worktree.
+
+{publication_gate()}
+Resolve this per worktree — unlike the compliance check above, the config file is per worktree root.
+
+### Phase 1: Parse Issues
+
+**Produces:** ISSUES
+**Requires:** TARGET_DIR
+
+Read review reports from `\{TARGET_DIR\}/*.md` and extract:
+
+**Exclude from issue extraction:**
+- `review-summary.md` (Synthesize agent output, not individual findings)
+- `resolution-summary.md` (if it exists from a previous partial run)
+- `bug-analysis-summary.md` (Synthesize agent output for bug-analysis runs)
+- `static-findings.md` (raw static analysis tool output, not individual findings)
+
+**Include:** ALL issues from all categories and severities, including Suggestions.
+
+Issues are extracted from `\{TARGET_DIR\}` only — never cross-reference reviews from other worktrees.
+
+**Extract per issue:**
+- `id`: Generated from file:line:type
+- `file`: Full path
+- `line`: Line number
+- `severity`: CRITICAL/HIGH/MEDIUM/LOW
+- `category`: blocking/should-fix/pre-existing
+- `type`: Issue type from review
+- `description`: Problem statement
+- `suggested_fix`: From review report
+- `reviewer_confidence`: Confidence percentage if present in the report (e.g., "85%"), else omit
+
+### Phase 1b: Fetch External Review Threads (Compliance-gated)
+
+**Produces:** THREAD_MAP
+**Requires:** PR_INFO, COMPLIANCE_SKILL_INSTALLED
+
+Skip this phase if `COMPLIANCE_SKILL_INSTALLED` is false.
+
+Spawn Git agent to fetch unresolved external (non-devflow-authored) review threads:
+
+```
+Agent(subagent_type="Git"):
+"OPERATION: fetch-review-threads
+PR_NUMBER: {pr_number}
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+Return THREAD_MAP for use in Phase 9b."
+```
+
+Parse `THREAD_MAP` from Git agent output. If Git agent returns `TRACEABILITY: DEGRADED`: record the reason, set `THREAD_MAP = empty`, continue.
+
+### Phase 2: Global Triage
+
+**Produces:** TRIAGE_RESULTS
+**Requires:** ISSUES, DIFF_FILES, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, PR_DESCRIPTION, BRANCH_INFO
+
+Spawn a single global Triage agent for ALL issues:
+
+```
+Agent(subagent_type="Triage"):
+"ISSUES: {all_issues}
+DIFF_FILES: {diff_files}
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+DECISIONS_CONTEXT: {decisions_context}
+FEATURE_KNOWLEDGE: {feature_knowledge}
+PR_DESCRIPTION: <pr-description>{pr_description}</pr-description>
+Triage every issue using the blast-radius disposition matrix. Assign exactly one verdict per issue.
+Follow devflow:apply-decisions to Read full ADR/PF bodies on demand.
+Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE."
+```
+
+Wait for Triage agent to complete before proceeding. Parse verdict ledger from Triage agent output:
+- **ESCALATED**: Security issues requiring human escalation
+- **FIX_NOW**: Valid issues assigned to Code agents (with risk tier: Standard | Careful)
+- **FALSE_POSITIVE**: Issues the Review agent got wrong (with cited evidence)
+- **BY_DESIGN**: Intentional code (with ADR or code doc citation)
+- **FIX_SEPARATE**: Valid but out of blast-radius scope (must become manage-debt ticket)
+- **TECH_DEBT**: Architectural overhaul only — LAST RESORT
+
+Collect all decisions citations (ADR-NNN / PF-NNN) from Triage agent Reasoning columns.
+
+**Triage agent completeness assertion (avoids PF-002):** Verify the parsed ledger against ISSUES before proceeding:
+1. Every issue `id` from ISSUES must appear in exactly one verdict bucket — none may vanish, none may appear in multiple buckets.
+2. If the Triage agent output is empty, contains a skill re-entrancy guard string (e.g., contains `already running`), or is missing any issue IDs from ISSUES: treat as a **Triage agent failure**:
+   - Retry the Triage agent once with the same inputs.
+   - If the retry also fails the completeness check: abort with a clear error message listing the missing issue IDs and failure reason — never proceed with dropped issues.
+
+**If ESCALATED issues exist:** surface them in a `## Escalations` section with a prominent display callout — never route escalations to manage-debt.
+
+### Phase 3: Batch FIX_NOW Issues
+
+**Produces:** BATCHES
+**Requires:** TRIAGE_RESULTS
+
+If FIX_NOW list is empty: skip to Phase 5 — write full summary (Phase 5), run manage-debt (Phase 9) if FIX_SEPARATE/TECH_DEBT exist, run thread resolution + resolution comment (Phase 9b), run merge readiness (Phase 9c), display results (Phase 10).
+
+Otherwise, batch FIX_NOW issues for Code agent execution:
+- **Same-file issues** → one batch (one Code agent per file, sequential for same-file pairs)
+- **Distinct-file issues** → parallel Code agents
+- **Max 5 issues per batch** — chunk large sets
+
+### Phase 4: Fix (Code agent × N)
+
+**Produces:** CODE_AGENT_RESULTS
+**Requires:** BATCHES, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, BRANCH_INFO
+
+For each batch, spawn Code agent with `OPERATION: issue-fix` and `PUSH: false`:
+
+```
+Agent(subagent_type="Code"):
+"TASK_ID: resolve-{batch-id}
+OPERATION: issue-fix
+ISSUES: {fix_now_issues_in_batch}
+SCOPE: {risk_tier_per_issue}
+PUSH: false
+CREATE_PR: false
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+DECISIONS_CONTEXT: {decisions_context}
+FEATURE_KNOWLEDGE: {feature_knowledge}
+Fix only the listed pre-classified FIX_NOW issues. Do not re-litigate dispositions.
+Same-file issues → one commit. Include ## Verification block in report.
+Regression fix without failing-then-passing regression test → BLOCKED."
+```
+
+Spawn distinct-file batch Code agents **in a single message** (parallel). Sequential Code agents for same-file batches must wait for the prior Code agent to complete before spawning.
+
+Collect from each Code agent:
+- `\{status, commitShas, unresolved\}` per batch
+- `## Verification` block (commands run + results)
+
+### Phase 5: Write resolution-summary.md
+
+**Produces:** RESOLUTION_FILE (early write for compaction safety)
+**Requires:** TRIAGE_RESULTS, CODE_AGENT_RESULTS
+
+**Immediately write `resolution-summary.md`** to `\{TARGET_DIR\}` using the Write tool. Do this now — not in Phase 9 — while results are fresh in context. This ensures the record is persisted even if later phases (Simplify, Verification Gate, CI gate, Tech Debt) trigger context compaction.
+
+Set `Tracked` for FIX_SEPARATE and TECH_DEBT items to `(pending)` — to be backfilled after Phase 9 manage-debt.
+
+Use the template from the Output Artifact section below.
+
+### Phase 6: Simplify
+
+**Produces:** SIMPLIFICATION_RESULT
+**Requires:** CODE_AGENT_RESULTS
+
+If any fixes were made, spawn Simplify agent to refine the changed code:
+
+```
+Agent(subagent_type="Simplify", run_in_background=false):
+"TASK_DESCRIPTION: Issue resolution fixes
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+FILES_CHANGED: {list of files modified by Code agents}
+Simplify and refine the fixes for clarity and consistency"
+```
+
+### Phase 7: Verification Gate
+
+**Produces:** VERIFICATION_STATUS
+**Requires:** CODE_AGENT_RESULTS
+
+If no fixes were made (CODE_AGENT_RESULTS contains 0 commits) → set VERIFICATION_STATUS = SKIPPED, skip: "No fixes applied — skipping Verification Gate."
+
+Otherwise, spawn Validate agent:
+
+```
+Agent(subagent_type="Validate", model="haiku"):
+"FILES_CHANGED: {list of files from Code agent output}
+VALIDATION_SCOPE: full
+Run build, typecheck, lint, test. Report pass/fail with failure details."
+```
+
+`validation_retry_count = 0`
+
+**If FAIL:**
+1. Extract failure details from Validate agent output
+2. Increment `validation_retry_count`
+3. If `validation_retry_count <= 2`:
+   - Spawn Code agent with fix context:
+   ```
+   Agent(subagent_type="Code"):
+   "TASK_ID: resolve-\{batch-id\}-valfix-\{count\}
+   OPERATION: validation-fix
+   VALIDATION_FAILURES: \{parsed failures from Validate agent\}
+   SCOPE: Fix only the listed failures, no other changes
+   PUSH: false
+   CREATE_PR: false
+   WORKTREE_PATH: \{worktree_path\}  (omit if cwd)"
+   ```
+   - Loop back to re-validate
+4. If `validation_retry_count > 2`: set VERIFICATION_STATUS = FAILED and exit the validation loop — record a blocking callout in the `## Verification` section (never a silent pass).
+
+**If PASS:** set VERIFICATION_STATUS = PASS and exit the validation loop.
+
+Record `## Verification` outcome in resolution-summary.md (runs unconditionally after the validation loop exits):
+- Rewrite the `## Verification` section with | Command | Result | table + `Final gate: PASS | FAILED after N attempts`
+
+Push all commits to remote once (Code agents and validation-fix Code agents ran with PUSH: false — runs unconditionally whether the gate PASSED or FAILED, so the branch is always visible before Phase 9 or CI runs):
+```bash
+git -C {worktree} push
+```
+
+**Route after push:** VERIFICATION_STATUS = PASS → continue to Phase 8 (CI gate). VERIFICATION_STATUS = FAILED → skip Phase 8; proceed directly to Phase 9 (manage-debt), then Phase 9b (thread resolution + resolution comment), then Phase 9c (merge readiness), then Phase 10 (report). VERIFICATION_STATUS = SKIPPED → skip Phase 8 (no fixes applied); proceed to Phase 9 (manage-debt), then Phase 9b (thread resolution + resolution comment), then Phase 9c (merge readiness, compliance-gated), then Phase 10 (report).
+
+### Phase 8: CI Status Gate (Conditional)
+
+**Produces:** CI_STATUS
+**Requires:** CODE_AGENT_RESULTS, VERIFICATION_STATUS
+
+If no issues were fixed (CODE_AGENT_RESULTS contains 0 fixes) → skip: "No fixes applied — skipping CI validation."
+
+If Verification Gate FAILED → skip CI gate (validation failures already reported).
+
+Otherwise, for each worktree with fixes:
+
+<!-- PATTERN: ci-status-gate — shared polling/classification/budget logic; context-specific preamble lives outside this block -->
+1. Spawn `Agent(subagent_type="Git")` with `OPERATION: check-ci-status` and `WORKTREE_PATH`.
+2. **If PASSING** → proceed to next phase.
+3. **If NO_PR or NO_CI** → skip: "No PR/CI configured, skipping CI validation." Proceed to next phase.
+4. **If PENDING** → poll every 60 seconds (global budget, see step 6). Re-spawn Git agent each poll. If PASSING → proceed. If still PENDING after budget exhausted → report "CI still running — verify manually before merging" and proceed.
+5. **If FAILING** → report failing checks. Spawn `Agent(subagent_type="Code")` to fix CI failures based on check names and failure context. After fix, push and re-check. Max 2 fix attempts. If still failing → report failures and proceed.
+6. **Total budget**: max 10 polls and max 2 fix attempts across all check/fix cycles combined. If the budget is exhausted, report current status and proceed.
+<!-- /PATTERN: ci-status-gate -->
+
+### Phase 9: Manage Debt (Sequential)
+
+**Produces:** DEBT_RESULT
+**Requires:** TRIAGE_RESULTS, TARGET_DIR
+
+**IMPORTANT**: Run sequentially across all worktrees (not in parallel) to avoid GitHub API conflicts.
+
+If any issues are FIX_SEPARATE or TECH_DEBT, spawn Git agent:
+
+```
+Agent(subagent_type="Git"):
+"OPERATION: manage-debt
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+REVIEW_DIR: {TARGET_DIR}
+TIMESTAMP: {timestamp}
+Note: Deferred issues (FIX_SEPARATE and TECH_DEBT) from triage are in resolution-summary.md
+under ## Fix Separately and ## Deferred to Tech Debt."
+```
+
+After manage-debt completes, backfill `Tracked = #\{backlog_issue_number\}` in resolution-summary.md for each FIX_SEPARATE and TECH_DEBT item.
+
+### Phase 9b: Thread Resolution + Resolution Comment
+
+**Produces:** THREAD_RESOLUTION_RESULT, PR_COMMENT
+**Requires:** THREAD_MAP (from Phase 1b), VERIFICATION_STATUS, CODE_AGENT_RESULTS, TRIAGE_RESULTS
+
+**Step 9b-1: Resolve external threads (Compliance-gated)**
+
+Skip this step if `COMPLIANCE_SKILL_INSTALLED` is false or THREAD_MAP is empty.
+
+Prepare THREAD_MAP with verdicts from triage/code agent results:
+- For each `ext-\{N\}`: match to an issue verdict (FIXED, FALSE_POSITIVE, BY_DESIGN, ESCALATED) by `file:line` correlation
+- Include `commit_sha` from Code agent results for FIXED verdicts
+- Unmatched threads: ESCALATED (human review)
+
+Spawn Git agent:
+
+```
+Agent(subagent_type="Git"):
+"OPERATION: resolve-review-threads
+THREAD_MAP: {thread_map_with_verdicts}
+VERIFICATION_STATUS: {PASS | FAILED | SKIPPED}
+PR_NUMBER: {pr_number}
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+D9: resolve threads only when VERIFICATION_STATUS == PASS and verdict is FIXED/FALSE_POSITIVE/BY_DESIGN with cited evidence."
+```
+
+If Git agent returns `TRACEABILITY: DEGRADED`: warn, record in `## Third-Party Threads`, continue to step 9b-2.
+
+**Step 9b-2: Post resolution summary (ALWAYS-ON)**
+
+Always run this step when a PR is known, regardless of `COMPLIANCE_SKILL_INSTALLED`.
+
+Spawn Git agent:
+
+```
+Agent(subagent_type="Git"):
+"OPERATION: post-resolution-summary
+PR_NUMBER: {pr_number}
+RESOLUTION_SUMMARY_PATH: {TARGET_DIR}/resolution-summary.md
+REVIEW_PUBLICATION: {REVIEW_PUBLICATION}
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+Posts the consolidated resolution-summary comment (marker-deduped by the operation)."
+```
+
+If Git agent returns `TRACEABILITY: DEGRADED`: warn, continue.
+
+Update `## Third-Party Threads` section in resolution-summary.md with thread resolution results.
+
+### Phase 9c: Merge Readiness (Compliance-gated, Report-only)
+
+**Produces:** MERGE_READINESS_REPORT
+**Requires:** PR_INFO, COMPLIANCE_SKILL_INSTALLED
+
+Skip this phase if `COMPLIANCE_SKILL_INSTALLED` is false.
+
+Spawn Git agent:
+
+```
+Agent(subagent_type="Git"):
+"OPERATION: check-merge-readiness
+PR_NUMBER: {pr_number}
+WORKTREE_PATH: {worktree_path}  (omit if cwd)"
+```
+
+Include merge readiness verdict (READY / NOT_READY / DEGRADED) in Phase 10 report. Never block on this result — report-only.
+
+If Git agent returns `TRACEABILITY: DEGRADED`: warn, proceed to Phase 10.
+
+### Phase 10: Report
+
+**Requires:** TARGET_DIR
+
+The resolution summary was already written to `\{TARGET_DIR\}/resolution-summary.md` in Phase 5 (updated by Phase 7 and Phase 9). Display results to the user:
+
+```
+## Resolution Summary
+
+**Branch**: {branch}
+**Reviews Processed**: {n} reports from {TARGET_DIR}
+**Total Issues**: {n}
+
+### Results
+| Outcome | Count |
+|---------|-------|
+| Fixed | {n} |
+| False Positive | {n} |
+| By Design | {n} |
+| Deferred | {n} |
+| Blocked | {n} |
+| Escalated | {n} |
+
+### Verification
+Final gate: {PASS | FAILED after N attempts}
+
+### Commits Created
+- {sha} {message}
+
+### Escalations (if any)
+> ⚠️ Security escalations require human review before merge:
+> {list of escalated issues}
+
+### Tech Debt Added
+- {n} items added to backlog
+
+### Publication (from Git agent)
+{FULL (private repo) | FULL (config override) | STUB (public repository) | OFF (publication disabled by config)}
+
+### Merge Readiness (if compliance enabled)
+{READY | NOT_READY (reason) | DEGRADED (reason) | SKIPPED (compliance not enabled)}
+
+### Artifacts
+- Resolution report: {TARGET_DIR}/resolution-summary.md
+```
+
+In multi-worktree mode, report results per worktree with aggregate summary.
+
+{knowledge_writeback()}
+
+## Architecture
+
+```
+/resolve (orchestrator - spawns agents only)
+│
+├─ Phase 0: Worktree Discovery & Pre-flight
+│  ├─ Step 0a: git worktree list → filter resolvable
+│  ├─ Step 0b: Git agent (validate-branch) per worktree [parallel] ← + DIFF_FILES
+│  ├─ Step 0c: Target latest review directory per worktree
+│  └─ Step 0d: Load project decisions → DECISIONS_CONTEXT + COMPLIANCE_SKILL_INSTALLED + REVIEW_PUBLICATION
+│
+├─ Phase 1: Parse issues from TARGET_DIR + extract confidence %
+│
+├─ Phase 1b: Fetch external threads (compliance-gated)
+│  └─ Git agent (fetch-review-threads) → THREAD_MAP
+│
+├─ Phase 2: Global Triage [Triage agent, opus, single agent]
+│  └─ ALL issues → verdict ledger by disposition
+│
+├─ Phase 3: Batch FIX_NOW issues (skip if empty)
+│  └─ same-file sequential, distinct-file parallel, max 5/batch
+│
+├─ Phase 4: Fix [Code agent × N, OPERATION: issue-fix, PUSH: false]
+│  └─ Returns Verification block per batch
+│
+├─ Phase 5: Write resolution-summary.md (compaction safety; Tracked = "(pending)")
+│
+├─ Phase 6: Simplify [Simplify agent]
+│
+├─ Phase 7: Verification Gate [Validate agent, haiku] + push + Code agent validation-fix loop ≤2
+│
+├─ Phase 8: CI Status Gate (conditional — skipped if no fixes or verification FAILED)
+│  └─ Git agent (check-ci-status) → poll/fix loop
+│
+├─ Phase 9: Git agent (manage-debt) — FIX_SEPARATE + TECH_DEBT → backfill Tracked=#
+│  SEQUENTIAL across worktrees
+│
+├─ Phase 9b: Thread resolution + resolution comment
+│  ├─ Step 9b-1: Git agent (resolve-review-threads) — compliance-gated
+│  └─ Step 9b-2: Git agent (post-resolution-summary, REVIEW_PUBLICATION) — always-on
+│
+├─ Phase 9c: Git agent (check-merge-readiness) — compliance-gated, report-only
+│
+└─ Phase 10: Display results (resolution-summary.md written in Phase 5)
+```
+
+## Edge Cases
+
+| Case | Handling |
+|------|----------|
+| No reviews exist | Check bug-analysis fallback (Step 0c-5b); if also absent, error and suggest `/code-review` or `/bug-analysis` |
+| All false positives | Normal completion, report shows 0 fixes |
+| Fix attempt fails | Revert changes, mark BLOCKED, continue others |
+| Issue dependencies | Sequential chain, skip dependents if predecessor blocked |
+| No actionable issues | Report "No issues to resolve" |
+| Incomplete review directory (no review-summary.md) | Skip — resolve only targets complete reviews |
+| Latest review already resolved | Check bug-analysis fallback (Step 0c-5b); if also absent, skip worktree and suggest `/code-review` or `/bug-analysis` |
+| Legacy flat layout (no subdirectories) | Read flat *.md files directly (backwards compatible) |
+| `--review \{timestamp\}` in multi-worktree mode | Not supported — use `--path` + `--review` to target specific worktree + review |
+| Worktree pre-flight fails | Report failure, continue with other worktrees |
+| Empty FIX_NOW list | Skip Phases 3-4/6-8; still write full summary + run manage-debt if FIX_SEPARATE/TECH_DEBT exist |
+| ESCALATED security issues | Surfaced in ## Escalations + display callout; never routed to manage-debt |
+| Verification Gate FAILED after 2 attempts | Recorded as FAILED in ## Verification + blocking callout; CI gate skipped; proceed to Phase 9 (manage-debt) then Phase 10 (display) |
+| gh/GitHub absent | manage-debt fails gracefully; Tracked stays "(pending)" + noted — recorded, not dropped |
+| COMPLIANCE_SKILL_INSTALLED false | Phases 1b, 9b-step-1, and 9c are skipped; post-resolution-summary (Phase 9b step 2) still runs if a PR is known |
+| THREAD_MAP empty or DEGRADED | Phase 9b-1 skipped; resolution comment (Phase 9b-2) still posted if PR known |
+| No PR exists for post-resolution-summary | Git agent returns TRACEABILITY: DEGRADED; resolution-summary.md already on disk — not a blocker |
+| Public repo (`auto` mode) | Git agent probes visibility, posts counts-only STUB comment; full resolution report stays local |
+| `reviewPublication: off` | Git agent skips posting the resolution comment (OFF) |
+
+## Principles
+
+1. **Orchestration only** - Command spawns agents, doesn't do git/resolve work itself
+2. **No agent grades its own homework** - Triage agent validates, Code agents fix, Validate agent verifies
+3. **Global triage first** - Single Triage agent sees all issues for cross-issue consistency; no issue may vanish
+4. **Git agent for git work** - All git operations go through Git agent
+5. **Parallel execution** - Distinct-file Code agent batches run in parallel; same-file batches sequential
+6. **Honest reporting** - Verification failure is recorded and displayed, never silenced
+7. **Complete tracking** - Every issue gets exactly one verdict in the ledger
+8. **Latest review by default** - Only process the most recent complete review
+9. **Auto-discover worktrees** - One command handles all resolvable branches
+10. **Traceability-aware** - Compliance-gated ops (thread fetch/resolve, merge readiness) degrade cleanly when skill absent; resolution comment (Phase 9b-2) is always-on
+
+## Output Artifact
+
+Written in Phase 5 (Collect Results) to `\{TARGET_DIR\}/resolution-summary.md`:
+
+```markdown
+# Resolution Summary
+
+**Branch**: {branch} -> {base}
+**Date**: {timestamp}
+**Review**: {TARGET_DIR}
+**Command**: /resolve
+
+## Decisions Citations
+
+- applies ADR-{NNN} — {batch-id}, {issue-id}
+- avoids PF-{NNN} — {batch-id}, {issue-id}
+
+(Omit section if no citations were made)
+
+## Statistics
+| Metric | Value |
+|--------|-------|
+| Total Issues | {n} |
+| Fixed | {n} |
+| False Positive | {n} |
+| By Design | {n} |
+| Deferred | {n} |
+| Blocked | {n} |
+| Escalated | {n} |
+
+_(Note: `Deferred` = `## Fix Separately` count + `## Deferred to Tech Debt` count combined — the two sections are distinct by scope, but the Statistics row aggregates both for the convergence parser.)_
+
+## Verification
+| Command | Result |
+|---------|--------|
+| {build/typecheck/lint/test} | PASS \| FAIL |
+
+Regression tests added: {n}
+
+Final gate: PASS | FAILED after {n} attempts
+
+## Fixed Issues
+| Issue | File:Line | Commit |
+|-------|-----------|--------|
+| {description} | {file}:{line} | {sha} |
+
+## False Positives
+| Issue | File:Line | Reasoning |
+|-------|-----------|-----------|
+| {description} | {file}:{line} | {why} |
+
+## By Design
+| Issue | File:Line | Rationale (ADR/doc) |
+|-------|-----------|---------------------|
+| {description} | {file}:{line} | {applies ADR-NNN or code comment} |
+
+## Fix Separately
+| Issue | File:Line | Reason | Tracked |
+|-------|-----------|--------|---------|
+| {description} | {file}:{line} | {why out of scope} | #{backlog} |
+
+## Deferred to Tech Debt
+| Issue | File:Line | Risk Factor |
+|-------|-----------|-------------|
+| {description} | {file}:{line} | {architectural concern} |
+
+## Escalations
+| Issue | File:Line | Security Concern |
+|-------|-----------|-----------------|
+| {description} | {file}:{line} | {why escalated} |
+
+## Blocked
+| Issue | File:Line | Blocker |
+|-------|-----------|---------|
+| {description} | {file}:{line} | {why} |
+
+## Third-Party Threads
+| Thread | File:Line | Verdict | Status |
+|--------|-----------|---------|--------|
+| ext-{N} | {file}:{line} | {FIXED \| FALSE_POSITIVE \| BY_DESIGN \| ESCALATED} | {RESOLVED \| REPLIED \| DEGRADED} |
+```
+
+_(Omit `## Third-Party Threads` if `COMPLIANCE_SKILL_INSTALLED` is false or no external threads were found.)_
+
+**Statistics mapping (parser contract)**: the `Deferred` row = FIX_SEPARATE + TECH_DEBT (both deferral dispositions combined); By Design and Escalated are counted separately and excluded from `Deferred`. The `/code-review` convergence parser reads the `Deferred`, `Fixed`, and `False Positive` Statistics rows plus the `## Fixed Issues` / `## False Positives` headings — keep those labels byte-stable.