Release dev to main

docs/bundles/code-review/overview.md

@@ -10,7 +10,7 @@ expertise_level: [beginner, intermediate]
 
 # Code Review bundle overview
 
-The **Code Review** bundle (`nold-ai/specfact-code-review`) extends the shared **`specfact code`** command group with **`review`** workflows: governed review runs, **reward ledger** history, and **house-rules** skill management.
+The **Code Review** bundle (`nold-ai/specfact-code-review`) extends the shared **`specfact code`** command group with **`review`** workflows: governed review runs, **reward ledger** history, and bundled code-review skill management through the **`rules`** command.
 
 Use it together with the [Codebase](/bundles/codebase/overview/) bundle (`import`, `analyze`, `drift`, `validate`, `repro`) on the same `code` surface.
 
@@ -25,7 +25,7 @@ Use it together with the [Codebase](/bundles/codebase/overview/) bundle (`import
 |--------|---------|
 | `run` | Execute a governed review (scope, JSON output, `--fix`, TDD gate, etc.) |
 | `ledger` | Inspect and update review reward history |
-| `rules` | Manage the house-rules skill (`show`, `init`, `update`) |
+| `rules` | Manage the bundled code-review skill (`show`, `init`, `update`) |
 
 ### `ledger` subcommands
 
@@ -46,9 +46,10 @@ Use it together with the [Codebase](/bundles/codebase/overview/) bundle (`import
 ## Bundle-owned skills and policy packs
 
 House rules and review payloads ship **inside the bundle** (for example Semgrep
-packs, the `specfact/clean-code-principles` policy-pack manifest, and skill
-metadata). They are **not** core CLI-owned resources. Install or refresh
-IDE-side assets with `specfact init ide` after upgrading the bundle.
+packs, the `specfact/clean-code-principles` policy-pack manifest, and the
+`specfact-code-review` skill). They are **not** core CLI-owned resources. Use
+`specfact code review rules init --ide codex` or the matching IDE target to
+install the reusable skill instead of copying prompt templates by hand.
 
 ## Quick examples
 

docs/bundles/code-review/rules.md

@@ -12,7 +12,11 @@ expertise_level: [intermediate, advanced]
 
 # Code review rules
 
-The rules commands manage the house-rules skill that backs the Code Review bundle’s policy guidance.
+The rules commands manage the bundled `specfact-code-review` skill. Install it
+when Codex CLI, Claude, Vibe, Cursor, or another SKILL.md-compatible AI IDE
+needs the Code Review workflow without copying slash prompt templates by hand.
+The skill includes CLI self-healing guidance, review run commands,
+simplification queue handling, and compact house rules.
 
 ## Commands
 
@@ -38,7 +42,9 @@ specfact code review rules update --ide cursor
 
 ## Bundle-owned resources
 
-The skill content is bundled with `nold-ai/specfact-code-review`. Initialize or refresh it from the installed module version instead of copying legacy core-owned files by hand.
+The skill content is bundled with `nold-ai/specfact-code-review`. Initialize or
+refresh it from the installed module version instead of copying prompt templates
+or legacy core-owned files by hand.
 
 ## Related
 

docs/bundles/code-review/run.md

@@ -29,7 +29,7 @@ The pipeline reviews **`.py`** and **`.pyi`** only. The **`--focus docs`** facet
 | `--scope changed\|full` | Review changed files or the full repository when no positional files are provided |
 | `--path <prefix>` | Narrow auto-discovered review files to one or more repo-relative prefixes |
 | `--include-tests`, `--exclude-tests` | Control whether changed test files participate in auto-scope review |
-| `--focus <facet>` | Limit auto-discovered scope to **`source`**, **`tests`**, and/or **`docs`** (repeatable); mutually exclusive with `--include-tests` / `--exclude-tests` |
+| `--focus <facet>` | Limit auto-discovered scope to **`source`**, **`tests`**, **`docs`**, and/or **`simplify`** (repeatable); mutually exclusive with `--include-tests` / `--exclude-tests` |
 | `--mode shadow\|enforce` | **`shadow`** surfaces findings without failing the exit code for policy violations; **`enforce`** applies normal gating (default **`enforce`**) |
 | `--level error\|warning` | Optional reporting level override before scoring: **`error`** keeps errors only (drops warnings and info); **`warning`** keeps errors and warnings (drops info only); omit to keep all severities (JSON, verdict, and `ci_exit_code` use the filtered list) |
 | `--bug-hunt` | Enable exploratory / bug-hunt style heuristics in the review pipeline |
@@ -89,12 +89,13 @@ specfact code review run --scope changed --mode shadow --json --out /tmp/review-
 
 ### `--focus` facets (repeatable)
 
-Use **`--focus`** with **`source`**, **`tests`**, and/or **`docs`** (union of facets, then intersect with scope). Do not combine **`--focus`** with **`--include-tests`** or **`--exclude-tests`**.
+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.
 
 ```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
 ```
 
 ### Positional files (explicit Python paths)
@@ -122,6 +123,14 @@ The review pipeline uses rules, skills, and policy payloads shipped with the ins
 
 The built-in `specfact/ai-bloat-patterns` policy pack is parallel to `specfact/clean-code-principles`. It maps advisory `ai_bloat` rules to the `ai_bloat` principle, emits `severity=info`, and stays score-neutral so simplification candidates do not block commits. Omit `--level` when producing the JSON report for `/specfact.08-simplify`; `--level error` intentionally filters info-level findings out of the command report.
 
+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
+```
+
+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.
+
 ## Related
 
 - [Code review ledger](/bundles/code-review/ledger/)

docs/bundles/project/overview.md

@@ -82,7 +82,7 @@ Brownfield **code import** (`specfact code import`, `specfact import …`) lives
 
 Plan and review flows may ship **prompts or templates** with the bundle. Treat them as **bundle payload**, not core CLI sources of truth. Refresh IDE-facing resources with `specfact init ide` after upgrades so editors receive the same artifacts the CLI expects.
 
-The project prompt set includes `/specfact.08-simplify`, which reads `.specfact/code-review.json`, filters `category=ai_bloat` findings from the Code Review bundle, and walks the user through accept/reject/skip/explain choices before applying any simplification edit.
+The project prompt set includes `/specfact.08-simplify`, which reads `.specfact/code-review-simplify.json`, groups `ai_bloat` and metadata-backed simplification findings by `intent_key`, file or domain, and rule, shows related locations, and walks the user through accept/reject/skip/explain choices before applying any simplification edit.
 
 ## Quick examples
 

docs/modules/code-review.md

@@ -35,10 +35,11 @@ Options (aligned with `specfact code review run --help`):
   review scope is auto-detected from `git diff`
 - `--focus`: repeatable facet filter applied after scope resolution; values are
   `source` (non-test, non-docs Python), `tests` (paths with a `tests/` segment),
-  and `docs` (Python under a `docs/` directory segment). Multiple `--focus`
-  values **union** their file sets, then intersect with the resolved scope. When
-  any `--focus` is set, **`--include-tests` and `--exclude-tests` are rejected**
-  (use focus alone to express test intent)
+  `docs` (Python under a `docs/` directory segment), and `simplify`
+  (simplification-focused findings). Multiple `--focus` values **union** their
+  file sets, then intersect with the resolved scope. When any `--focus` is set,
+  **`--include-tests` and `--exclude-tests` are rejected** (use focus alone to
+  express test intent)
 - `--mode shadow|enforce`: **enforce** (default) keeps today’s non-zero process
   exit when the governed report says the run failed; **shadow** still runs the
   full toolchain and preserves `overall_verdict` in JSON, but forces
@@ -103,15 +104,15 @@ specfact code review run --scope changed --path packages/specfact-code-review --
 ```
 
 Copy-pastable recipes for **shadow mode**, **JSON `--out`**, **`--focus`**
-(`source` / `tests` / `docs` Python only), **noise flags**, and **interactive**
+(`source` / `tests` / `docs` / `simplify`), **noise flags**, and **interactive**
 test prompts live in the [Code review run](/bundles/code-review/run/) bundle
 guide (same Typer surface as this section).
 
 ### AI-shaped bloat advisories
 
 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, and the `/specfact.08-simplify` IDE prompt 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. They do not claim AI authorship; they identify simplification candidates.
 
 Positional `FILES...` cannot be mixed with **`--scope`** or **`--path`** (see
 **Invalid combinations** above).
@@ -395,23 +396,29 @@ specfact module init --scope project
 
 Then rerun the ledger command from the same repository checkout.
 
-## House rules skill
+## Code review skill
 
-The `specfact-code-review` bundle can derive a compact house-rules skill from the
-reward ledger and keep it small enough for AI session context injection. The
-default charter now encodes the clean-code principles directly:
+The `specfact-code-review` bundle ships a compact `SKILL.md` for Codex CLI,
+Claude, Vibe, and Cursor-compatible IDEs. Use it as the reusable alternative to
+copying prompt templates into every AI IDE: it carries the CLI-grounded review
+workflow, simplification queue guidance, self-healing `--help` behavior, and
+house rules derived from the reward ledger. The default charter encodes the
+clean-code principles directly:
 
 - Naming: use intention-revealing names instead of placeholders.
 - KISS: keep functions small, shallow, and narrow in parameters.
 - YAGNI: remove unused private helpers and speculative layers.
 - DRY: extract repeated function shapes once duplication appears.
 - SOLID: keep transport and persistence responsibilities separate.
 - TDD + contracts: keep test-first and icontract discipline in the baseline skill.
+- Simplification loop: use `--focus simplify` for advisory cleanup queues and
+  require explicit user approval before edits.
 
 ### Command flow
 
 ```bash
 specfact code review rules init
+specfact code review rules init --ide codex
 specfact code review rules show
 specfact code review rules update
 ```

openspec/CHANGE_ORDER.md

@@ -101,6 +101,7 @@ The architecture pillar remains active because `architecture-02-well-architected
 | code-review + codebase | 01 | code-review-bug-finding-and-sidecar-venv-fix | [#174](https://github.com/nold-ai/specfact-cli-modules/issues/174) | 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) |
 | codebase + project-runtime | 02 | codebase-import-runtime-hardening | [#235](https://github.com/nold-ai/specfact-cli-modules/issues/235) | Parent Feature: [#234](https://github.com/nold-ai/specfact-cli-modules/issues/234); Epic: [#162](https://github.com/nold-ai/specfact-cli-modules/issues/162); no known blockers |
 | 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) |
 
 ### Documentation restructure
 

openspec/changes/code-review-11-simplification-feedback-loop/.openspec.yaml

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