Implement cleanup forecast handoff

docs/bundles/code-review/run.md

@@ -39,6 +39,8 @@ The pipeline reviews **`.py`** and **`.pyi`** only. The **`--focus docs`** facet
 | `--score-only` | Print just the reward delta integer |
 | `--no-tests` | Skip the TDD gate |
 | `--fix` | Apply Ruff autofixes, then rerun the review |
+| `--preview-fixes` | For **`--focus simplify`**, compute non-mutating patch evidence for supported safe-mechanical simplification fixers |
+| `--with-mutation` | For **`--focus simplify`**, record opt-in mutation proof evidence for cleanup candidates; unavailable tooling is inconclusive |
 | `--interactive` | Prompt for scope decisions before execution |
 | `--instructions` | Print AI-facing simplify / clean-code workflow instructions and exit without running review |
 
@@ -53,6 +55,9 @@ The Typer entrypoint validates **review flags** first: it raises **`typer.BadPar
 - **`--include-tests` with `--exclude-tests`**: pick at most one test inclusion mode. Runtime error: **`Cannot use both --include-tests and --exclude-tests`**
 - **`--out` without `--json`**: **`--out`** is accepted only when **`--json`** is also set. Runtime error: **`Use --out together with --json.`**
 - **`--json` with `--score-only`**: do not combine JSON report output with score-only mode (**`Use either --json or --score-only, not both.`**).
+- **`--preview-fixes` with `--fix`**: preview is non-mutating and cannot be combined with write mode. Runtime error: **`Cannot combine --preview-fixes with --fix.`**
+- **`--preview-fixes` without simplify focus**: preview evidence is scoped to cleanup findings. Runtime error: **`Use --preview-fixes only with --focus simplify.`**
+- **`--with-mutation` without simplify focus**: mutation proof is scoped to cleanup candidates. Runtime error: **`Use --with-mutation only with --focus simplify.`**
 
 **Supported targeting:** either pass **positional file paths** for a fixed review set (the pipeline still only reviews Python sources it accepts, such as **`.py`** / **`.pyi`**), or omit files and use **`--scope`** / **`--path`** (and related test flags) for auto-discovery — do not mix positional paths with **`--scope`** or **`--path`**.
 
@@ -90,13 +95,14 @@ specfact code review run --scope changed --mode shadow --json --out /tmp/review-
 
 ### `--focus` facets (repeatable)
 
-Use **`--focus`** with **`source`**, **`tests`**, **`docs`**, and/or **`simplify`** (union of facets, then intersect with scope). Do not combine **`--focus`** with **`--include-tests`** or **`--exclude-tests`**. The **`simplify`** facet produces simplification-focused reports: advisory **`ai_bloat`** findings plus high-confidence **`dry`** and **`kiss`** findings that carry deterministic metadata such as **`rewrite_hint`**, **`canonical_pattern`**, **`intent_key`**, **`estimated_deletion_lines`**, and **`related_locations`**. Simplification-focused findings are score-neutral and non-blocking.
+Use **`--focus`** with **`source`**, **`tests`**, **`docs`**, and/or **`simplify`** (union of facets, then intersect with scope). Do not combine **`--focus`** with **`--include-tests`** or **`--exclude-tests`**. The **`simplify`** facet produces simplification-focused reports: advisory **`ai_bloat`** findings plus high-confidence **`dry`** and **`kiss`** findings that carry deterministic metadata such as **`rewrite_hint`**, **`canonical_pattern`**, **`intent_key`**, **`estimated_deletion_lines`**, and **`related_locations`**. Simplification-focused JSON also includes **`cleanup_forecast`**, **`signal_trace`**, **`preserve_reasons`**, and **`remediation_packet`** fields when available.
 
 ```bash
 specfact code review run --scope changed --focus tests
 specfact code review run --scope full --path packages/specfact-code-review --focus source
 specfact code review run --scope full --focus docs
-specfact code review run --scope changed --focus simplify --json --out .specfact/code-review-simplify.json
+specfact code review run --scope changed --focus simplify --preview-fixes --json --out .specfact/code-review-simplify.json
+specfact code review run --scope changed --focus simplify --with-mutation --json --out .specfact/code-review-simplify.json
 ```
 
 ### AI instructions fallback
@@ -107,7 +113,7 @@ When an IDE does not support bundled prompts or skills, print the same guided si
 specfact code review run --instructions
 ```
 
-The output explains how to remove AI bloat and apply clean-code simplifications using SpecFact evidence, including `safe_mechanical`, `needs_tests`, `design_judgment`, and `preserve` handling, patch previews, conservative keep/skip defaults, and per-file validation. It also tells assistants how to handle clean PR branches where `--scope changed` has no worktree files: find branch-delta Python files with a base-ref diff such as `git diff --name-only <base-ref>...HEAD -- '*.py' '*.pyi'`, review those files as explicit positional files, and treat findings without `guidance_kind` as unguided advisories rather than auto-fix input.
+The output explains how to remove AI bloat and apply clean-code simplifications using SpecFact evidence, including `cleanup_forecast`, `safe_mechanical`, `needs_tests`, `design_judgment`, `preserve`, `remediation_packet`, patch previews, conservative keep/skip defaults, and per-file validation. It also tells assistants how to handle clean PR branches where `--scope changed` has no worktree files: find branch-delta Python files with a base-ref diff such as `git diff --name-only <base-ref>...HEAD -- '*.py' '*.pyi'`, review those files as explicit positional files, and treat findings without `guidance_kind` as unguided advisories rather than auto-fix input. `ai_bloat` findings are cleanup signals, not proof of AI authorship.
 
 ### Positional files (explicit Python paths)
 
@@ -137,10 +143,10 @@ The built-in `specfact/ai-bloat-patterns` policy pack is parallel to `specfact/c
 Use `--focus simplify` when producing the IDE simplification queue:
 
 ```bash
-specfact code review run --scope changed --focus simplify --json --out .specfact/code-review-simplify.json
+specfact code review run --scope changed --focus simplify --preview-fixes --json --out .specfact/code-review-simplify.json
 ```
 
-Simplify-focused reports keep advisory `ai_bloat` findings plus high-confidence `dry` and `kiss` findings that include deterministic simplification metadata. Metadata fields such as `rewrite_hint`, `canonical_pattern`, `intent_key`, `estimated_deletion_lines`, and `related_locations` are additive; legacy consumers can keep reading the original finding fields. Simplification findings remain score-neutral and non-blocking.
+Simplify-focused reports keep advisory `ai_bloat` findings plus high-confidence `dry` and `kiss` findings that include deterministic simplification metadata. Metadata fields such as `rewrite_hint`, `canonical_pattern`, `intent_key`, `estimated_deletion_lines`, `related_locations`, `signal_trace`, `preserve_reasons`, and `remediation_packet` are additive; legacy consumers can keep reading the original finding fields. The report-level `cleanup_forecast` summarizes reviewed LOC, estimated deletion ranges, guidance-kind totals, normalized AI-bloat density, weighted bloat points, and cleanup-yield LOC per KLOC. Simplification findings remain score-neutral; enforce mode blocks only unresolved safe-mechanical cleanup candidates.
 
 ## Related
 

docs/modules/code-review.md

@@ -59,6 +59,11 @@ Options (aligned with `specfact code review run --help`):
 - `--score-only`: print only the integer `reward_delta`
 - `--no-tests`: skip the targeted TDD gate
 - `--fix`: apply Ruff autofixes and re-run the review before printing results
+- `--preview-fixes`: with **`--focus simplify`**, compute non-mutating patch
+  evidence for supported safe-mechanical simplification fixers
+- `--with-mutation`: with **`--focus simplify`**, record opt-in mutation proof
+  evidence for cleanup candidates; missing mutation tooling is recorded as
+  inconclusive
 - `--interactive`: ask whether changed test files should be included before
   auto-detected review runs
 - `--instructions`: print AI-facing simplify / clean-code workflow instructions
@@ -75,6 +80,9 @@ The command rejects incompatible mixes (same rules as the bundle run guide): Typ
 - **`--include-tests` with `--exclude-tests`**: pick at most one test inclusion mode.
 - **`--out` without `--json`**: **`--out`** is accepted only when **`--json`** is also set.
 - **`--json` with `--score-only`**: pick one, not both (**`--json`** cannot be used with **`--score-only`**).
+- **`--preview-fixes` with `--fix`**: preview is non-mutating and cannot be combined with write mode.
+- **`--preview-fixes` without `--focus simplify`**: preview evidence is scoped to cleanup findings.
+- **`--with-mutation` without `--focus simplify`**: mutation proof is scoped to cleanup candidates.
 
 When `FILES` is omitted, the command falls back to:
 
@@ -114,7 +122,7 @@ guide (same Typer surface as this section).
 
 The review pipeline also emits `ai_bloat` findings for code shapes commonly amplified by AI-assisted generation: manual append loops, passthrough lambdas, identity `try/except`, one-call wrappers, speculative `Optional[...] = None` parameters, duplicate terminal guards, long low-branch functions, and redundant intermediates.
 
-These findings are `severity=info`, advisory-only, and score-neutral. They are written to `.specfact/code-review.json` when the report includes all severities; for simplification queues, write `.specfact/code-review-simplify.json` with `--focus simplify` so `/specfact.08-simplify` can filter them by `category=ai_bloat` for per-change confirmed rewrites. They do not claim AI authorship; they identify simplification candidates.
+These findings are `severity=info`, advisory-only, and score-neutral. They are written to `.specfact/code-review.json` when the report includes all severities; for simplification queues, write `.specfact/code-review-simplify.json` with `--focus simplify` so `/specfact.08-simplify` can filter them by `category=ai_bloat` for per-change confirmed rewrites. Simplify JSON now includes `cleanup_forecast` at report level plus per-finding `signal_trace`, `preserve_reasons`, and `remediation_packet` where available. They do not claim AI authorship; they identify simplification candidates.
 
 For the lowest-friction AI onboarding path, start with the built-in instruction
 printer instead of requiring a user to install IDE prompts or skills first:
@@ -125,8 +133,9 @@ specfact code review run --instructions
 
 Paste that output into any AI coding assistant and ask it to simplify or remove
 AI bloat with SpecFact. The instructions explain the expected report file,
-`guidance_kind` handling, patch-preview decision cards, conservative defaults
-for `design_judgment`, and per-file validation. They also cover clean PR
+`cleanup_forecast`, `guidance_kind`, `remediation_packet` handling,
+patch-preview decision cards, conservative defaults for `design_judgment`,
+and per-file validation. They also cover clean PR
 branches where `--scope changed` has no worktree files: the assistant should
 find branch-delta Python files with a base-ref diff such as
 `git diff --name-only <base-ref>...HEAD -- '*.py' '*.pyi'`, review those files
@@ -190,6 +199,19 @@ specfact code review run --score-only packages/specfact-code-review/src/specfact
 specfact code review run --fix packages/specfact-code-review/src/specfact_code_review/run/commands.py
 ```
 
+For simplify-focused cleanup, prefer a JSON-first preview loop before writing:
+
+```bash
+specfact code review run --scope changed --focus simplify --preview-fixes --json --out .specfact/code-review-simplify.json
+```
+
+Inspect `cleanup_forecast` to estimate cleanup yield and sort by
+`guidance_kind`. For each finding, use `remediation_packet` as the portable AI
+IDE contract. The preview evidence reports patch deltas without editing tracked
+files. Use `--with-mutation` only when you explicitly want candidate-scoped
+mutation evidence; missing or timed-out tooling is inconclusive, not proof that
+deletion is safe.
+
 ## Tool runners
 
 The `specfact-code-review` bundle now includes internal runners that translate tool

docs/quickstart-ai-bloat.md

@@ -10,7 +10,7 @@ expertise_level: [beginner, intermediate]
 
 # AI bloat quickstart
 
-Use the Code Review bundle to detect bloat patterns commonly produced by AI-assisted coding, then use the Project bundle's `/specfact.08-simplify` prompt to review each cleanup with confirmation.
+Use the Code Review bundle to detect bloat patterns commonly produced by AI-assisted coding, estimate cleanup impact, and hand structured remediation packets to any AI IDE. The Project bundle's `/specfact.08-simplify` prompt can still drive the confirmed rewrite loop.
 
 ## 1. Install and refresh prompts
 
@@ -20,31 +20,36 @@ specfact module install nold-ai/specfact-project
 specfact init ide
 ```
 
-## 2. Run review with full JSON evidence
+## 2. Run simplify review with cleanup forecast evidence
 
 ```bash
-specfact code review run --json --out .specfact/code-review.json
+specfact code review run --scope changed --focus simplify --preview-fixes --json --out .specfact/code-review-simplify.json
 ```
 
-Omit `--level` for this report. `--level error` intentionally filters info-level findings, including `ai_bloat`, out of the command output.
+Omit `--level` for this report. `--level error` intentionally filters info-level findings, including `ai_bloat`, out of the command output. `--preview-fixes` is non-mutating: it adds patch forecast evidence without editing tracked files.
 
 ## 3. Inspect the signal
 
-Look for findings where `category` is `ai_bloat`. They are `severity=info`, advisory-only, and score-neutral.
+Look first at `cleanup_forecast`. It summarizes reviewed LOC, low/expected/high deletion estimates, guidance-kind totals, AI-bloat density, weighted bloat points, and cleanup-yield LOC per KLOC. Then inspect findings where `category` is `ai_bloat`. They are `severity=info`, advisory-only, and score-neutral.
 
 Example output from the implementation dry run for this change: the AST detector found advisory `ai_bloat` candidates across `specfact-code-review` and `specfact-project` package sources, with no automatic rewrites applied. `/specfact.08-simplify` is the human-confirmed rewrite path.
 
 ```json
 {
   "category": "ai_bloat",
   "severity": "info",
-  "rule": "ai-bloat.identity-try-except"
+  "rule": "ai-bloat.identity-try-except",
+  "guidance_kind": "safe_mechanical",
+  "remediation_packet": {
+    "safe_to_autofix": true,
+    "validation_plan": ["run targeted tests", "rerun simplify review"]
+  }
 }
 ```
 
 ## 4. Simplify in the IDE
 
-Run `/specfact.08-simplify`. The prompt reads `.specfact/code-review.json`, groups findings by file and rule, and asks before applying each edit.
+Run `/specfact.08-simplify` or pass `.specfact/code-review-simplify.json` to your AI IDE. The JSON is the contract: sort by `guidance_kind`, use each `remediation_packet`, preserve anything with `preserve_reasons`, and ask before editing `design_judgment` findings.
 
 Example cleanup:
 
@@ -83,7 +88,7 @@ def double(values: list[int]) -> list[int]:
 ## 5. Re-run review
 
 ```bash
-specfact code review run --json --out .specfact/code-review.json
+specfact code review run --scope changed --focus simplify --json --out .specfact/code-review-simplify.json
 ```
 
 Use the new report to confirm accepted simplifications cleared the corresponding `ai_bloat` findings. This is bloat-shape detection, not AI-authorship detection.

openspec/CHANGE_ORDER.md

@@ -103,6 +103,7 @@ The architecture pillar remains active because `architecture-02-well-architected
 | code-review + project | 03 | code-review-ai-bloat-detection | [#269](https://github.com/nold-ai/specfact-cli-modules/issues/269) | Parent Feature: [#175](https://github.com/nold-ai/specfact-cli-modules/issues/175); Epic: [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162); no known blockers |
 | code-review + project | 04 | code-review-11-simplification-feedback-loop | [#276](https://github.com/nold-ai/specfact-cli-modules/issues/276) | Parent Feature: [#275](https://github.com/nold-ai/specfact-cli-modules/issues/275); Epic: [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162); blocked by `code-review-ai-bloat-detection` / [#269](https://github.com/nold-ai/specfact-cli-modules/issues/269) |
 | code-review + project | 05 | code-review-12-guided-simplification-enforcement | [#286](https://github.com/nold-ai/specfact-cli-modules/issues/286) | Parent Feature: [#275](https://github.com/nold-ai/specfact-cli-modules/issues/275); Epic: [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162); blocked by `code-review-11-simplification-feedback-loop` / [#276](https://github.com/nold-ai/specfact-cli-modules/issues/276) |
+| code-review + project | 06 | code-review-13-cleanup-forecast-agent-handoff | [#297](https://github.com/nold-ai/specfact-cli-modules/issues/297) | Parent Feature: [#275](https://github.com/nold-ai/specfact-cli-modules/issues/275); Epic: [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162); blocked by `code-review-12-guided-simplification-enforcement` / [#286](https://github.com/nold-ai/specfact-cli-modules/issues/286) |
 
 ### Documentation restructure
 

openspec/changes/code-review-13-cleanup-forecast-agent-handoff/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-24

openspec/changes/code-review-13-cleanup-forecast-agent-handoff/README.md

@@ -0,0 +1,3 @@
+# code-review-13-cleanup-forecast-agent-handoff
+
+Cleanup forecast, AI-bloat index, remediation packets, and AI IDE handoff for code review.

openspec/changes/code-review-13-cleanup-forecast-agent-handoff/TDD_EVIDENCE.md

@@ -0,0 +1,55 @@
+# TDD Evidence: code-review-13-cleanup-forecast-agent-handoff
+
+## Failing-before evidence
+
+Command:
+
+```bash
+hatch run pytest tests/unit/specfact_code_review/run/test_findings.py tests/unit/specfact_code_review/run/test_runner.py tests/unit/specfact_code_review/run/test_commands.py tests/unit/specfact_code_review/review/test_commands.py -q
+```
+
+Result before implementation:
+
+- Exit code: 2
+- Collection failed because `AiBloatIndex` and `_preserve_reasons_for_finding` did not exist yet.
+
+## Passing evidence
+
+Targeted implementation command:
+
+```bash
+hatch run pytest tests/unit/specfact_code_review/run/test_cleanup_evidence.py tests/unit/specfact_code_review/run/test_forecast.py tests/unit/specfact_code_review/run/test_findings.py tests/unit/specfact_code_review/run/test_runner.py tests/unit/specfact_code_review/run/test_commands.py tests/unit/specfact_code_review/review/test_commands.py -q
+```
+
+Result after implementation:
+
+- Exit code: 0
+- 137 passed
+
+Docs and packaged-resource parity command:
+
+```bash
+hatch run pytest tests/unit/docs/test_code_review_docs_parity.py tests/unit/specfact_code_review/rules/test_updater.py tests/unit/test_guided_simplify_resources.py -q
+```
+
+Result:
+
+- Exit code: 0
+- 22 passed
+
+Required final gates:
+
+- `hatch run format` — exit code 0
+- `hatch run type-check` — exit code 0
+- `hatch run lint` — exit code 0
+- `hatch run yaml-lint` — exit code 0
+- `hatch run check-bundle-imports` — exit code 0
+- `hatch run verify-modules-signature --payload-from-filesystem --enforce-version-bump` — exit code 0
+- `hatch run specfact code review run --bug-hunt --json --out .specfact/code-review.json --scope changed` — exit code 0
+- `openspec validate code-review-13-cleanup-forecast-agent-handoff --strict` — exit code 0
+
+Full suite wrappers:
+
+- `hatch run contract-test -- tests/cli-contracts/specfact-code-review-run.scenarios.yaml` — exit code 0, 785 passed, 2 warnings
+- `hatch run smart-test` — exit code 0, 785 passed, 2 warnings
+- `hatch run test -- -q` — exit code 0, 785 passed, 2 warnings