fix(code-review): restore actionable review output with interactive choices (#2055)

* fix(code-review): restore actionable review output with interactive choices

The March 15 rewrite (PR #2007) removed the ability to auto-fix patches,
create action items in story files, and handle deferred/spec findings.
This restores interactive post-review actions:

- Deferred findings: auto-written to deferred-work.md and checked off in story
- Intent gap/bad spec: conversation with downgrade-to-patch, patch-spec,
  reset-to-ready-for-dev, or dismiss options
- Patch findings: fix automatically, create action items, or show details

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(code-review): simplify triage to decision-needed/patch/defer/dismiss

Replace 5-bucket classification (intent_gap, bad_spec, patch, defer, reject)
with 4 pragmatic buckets. Findings always written to story file first.
Decision-needed findings gate patch handling — resolve ambiguity before fixing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(code-review): address PR review findings in step-04-present

Replace undefined curly-brace placeholders with angle-bracket syntax,
add HALT guard before patch menu, guard spec_file references for
no-spec mode, and backtick category names for consistency.

* feat(code-review): add HALT guards, batch option, defer reason, final summary

Add strong HALT guards after decision-needed and patch menus to prevent
auto-progression. Add batch-apply option 0 for >3 patch findings. Prompt
for defer reason and append to story file and deferred-work.md. Show
boxed final summary with counts. Polish clean-review shortcut in triage.

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

src/bmm-skills/4-implementation/bmad-code-review/steps/step-03-triage.md

@@ -30,19 +30,18 @@
    - Set `source` to the merged sources (e.g., `blind+edge`).
 
 3. **Classify** each finding into exactly one bucket:
-   - **intent_gap** -- The spec/intent is incomplete; cannot resolve from existing information. Only possible if `{review_mode}` = `"full"`.
-   - **bad_spec** -- The spec should have prevented this; spec is wrong or ambiguous. Only possible if `{review_mode}` = `"full"`.
-   - **patch** -- Code issue that is trivially fixable without human input. Just needs a code change.
+   - **decision_needed** -- There is an ambiguous choice that requires human input. The code cannot be correctly patched without knowing the user's intent. Only possible if `{review_mode}` = `"full"`.
+   - **patch** -- Code issue that is fixable without human input. The correct fix is unambiguous.
    - **defer** -- Pre-existing issue not caused by the current change. Real but not actionable now.
-   - **reject** -- Noise, false positive, or handled elsewhere.
+   - **dismiss** -- Noise, false positive, or handled elsewhere.
 
-   If `{review_mode}` = `"no-spec"` and a finding would otherwise be `intent_gap` or `bad_spec`, reclassify it as `patch` (if code-fixable) or `defer` (if not).
+   If `{review_mode}` = `"no-spec"` and a finding would otherwise be `decision_needed`, reclassify it as `patch` (if the fix is unambiguous) or `defer` (if not).
 
-4. **Drop** all `reject` findings. Record the reject count for the summary.
+4. **Drop** all `dismiss` findings. Record the dismiss count for the summary.
 
-5. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping rejects AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review.
+5. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping dismissed AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review.
 
-6. If zero findings remain after dropping rejects and no layers failed, note clean review.
+6. If zero findings remain after triage (all rejected or none raised): state "✅ Clean review — all layers passed." (Step 3 already warned if any review layers failed via `{failed_layers}`.)
 
 
 ## NEXT

src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md

@@ -1,38 +1,84 @@
 ---
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 ---
 
-# Step 4: Present
+# Step 4: Present and Act
 
 ## RULES
 
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-- Do NOT auto-fix anything. Present findings and let the user decide next steps.
+- When `{spec_file}` is set, always write findings to the story file before offering action choices.
+- `decision-needed` findings must be resolved before handling `patch` findings.
 
 ## INSTRUCTIONS
 
-1. Group remaining findings by category.
+### 1. Clean review shortcut
 
-2. Present to the user in this order (include a section only if findings exist in that category):
+If zero findings remain after triage (all dismissed or none raised): state that and end the workflow.
 
-   - **Intent Gaps**: "These findings suggest the captured intent is incomplete. Consider clarifying intent before proceeding."
-     - List each with title + detail.
+### 2. Write findings to the story file
 
-   - **Bad Spec**: "These findings suggest the spec should be amended. Consider regenerating or amending the spec with this context:"
-     - List each with title + detail + suggested spec amendment.
+If `{spec_file}` exists and contains a Tasks/Subtasks section, append a `### Review Findings` subsection. Write all findings in this order:
 
-   - **Patch**: "These are fixable code issues:"
-     - List each with title + detail + location (if available).
+1. **`decision-needed`** findings (unchecked):
+   `- [ ] [Review][Decision] <Title> — <Detail>`
 
-   - **Defer**: "Pre-existing issues surfaced by this review (not caused by current changes):"
-     - List each with title + detail.
+2. **`patch`** findings (unchecked):
+   `- [ ] [Review][Patch] <Title> [<file>:<line>]`
 
-3. Summary line: **X** intent_gap, **Y** bad_spec, **Z** patch, **W** defer findings. **R** findings rejected as noise.
+3. **`defer`** findings (checked off, marked deferred):
+   `- [x] [Review][Defer] <Title> [<file>:<line>] — deferred, pre-existing`
 
-4. If clean review (zero findings across all layers after triage): state that N findings were raised but all were classified as noise, or that no findings were raised at all (as applicable).
+Also append each `defer` finding to `{deferred_work_file}` under a heading `## Deferred from: code review ({date})`. If `{spec_file}` is set, include its basename in the heading (e.g., `code review of story-3.3 (2026-03-18)`). One bullet per finding with description.
 
-5. Offer the user next steps (recommendations, not automated actions):
-   - If `patch` findings exist: "These can be addressed in a follow-up implementation pass or manually."
-   - If `intent_gap` or `bad_spec` findings exist: "Consider running the planning workflow to clarify intent or amend the spec before continuing."
-   - If only `defer` findings remain: "No action needed for this change. Deferred items are noted for future attention."
+### 3. Present summary
 
-Workflow complete.
+Announce what was written:
+
+> **Code review complete.** <D> `decision-needed`, <P> `patch`, <W> `defer`, <R> dismissed as noise.
+
+If `{spec_file}` is set, add: `Findings written to the review findings section in {spec_file}.`
+Otherwise add: `Findings are listed above. No story file was provided, so nothing was persisted.`
+
+### 4. Resolve decision-needed findings
+
+If `decision_needed` findings exist, present each one with its detail and the options available. The user must decide — the correct fix is ambiguous without their input. Walk through each finding (or batch related ones) and get the user's call. Once resolved, each becomes a `patch`, `defer`, or is dismissed.
+
+If the user chooses to defer, ask: Quick one-line reason for deferring this item? (helps future reviews): — then append that reason to both the story file bullet and the `{deferred_work_file}` entry.
+
+**HALT** — I am waiting for your numbered choice. Reply with only the number (or "0" for batch). Do not proceed until you select an option.
+
+### 5. Handle `patch` findings
+
+If `patch` findings exist (including any resolved from step 4), HALT. Ask the user:
+
+If `{spec_file}` is set, present all three options (if >3 `patch` findings exist, also show option 0):
+
+> **How would you like to handle the <Z> `patch` findings?**
+> 0. **Batch-apply all** — automatically fix every non-controversial patch (recommended when there are many)
+> 1. **Fix them automatically** — I will apply fixes now
+> 2. **Leave as action items** — they are already in the story file
+> 3. **Walk through each** — let me show details before deciding
+
+If `{spec_file}` is **not** set, present only options 1 and 3 (omit option 2 — findings were not written to a file). If >3 `patch` findings exist, also show option 0:
+
+> **How would you like to handle the <Z> `patch` findings?**
+> 0. **Batch-apply all** — automatically fix every non-controversial patch (recommended when there are many)
+> 1. **Fix them automatically** — I will apply fixes now
+> 2. **Walk through each** — let me show details before deciding
+
+**HALT** — I am waiting for your numbered choice. Reply with only the number (or "0" for batch). Do not proceed until you select an option.
+
+- **Option 0** (only when >3 findings): Apply all non-controversial patches without per-finding confirmation. Skip any finding that requires judgment. Present a summary of changes made and any skipped findings.
+- **Option 1**: Apply each fix. After all patches are applied, present a summary of changes made. If `{spec_file}` is set, check off the items in the story file.
+- **Option 2** (only when `{spec_file}` is set): Done — findings are already written to the story.
+- **Walk through each**: Present each finding with full detail, diff context, and suggested fix. After walkthrough, re-offer the applicable options above.
+
+  **HALT** — I am waiting for your numbered choice. Reply with only the number (or "0" for batch). Do not proceed until you select an option.
+
+**✅ Code review actions complete**
+
+- Decision-needed resolved: <D>
+- Patches handled: <P>
+- Deferred: <W>
+- Dismissed: <R>