chore(release): prepare core cli 0.46.28

CHANGELOG.md

@@ -10,6 +10,22 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.46.28] - 2026-05-21
+
+### Changed
+
+- **Code Review AI bloat guidance**: add core README and docs callouts for
+  `ai_bloat` advisory findings and the `/specfact.08-simplify` IDE prompt,
+  framing them as score-neutral, human-confirmed cleanup candidates rather
+  than AI-authorship detection.
+
+### Fixed
+
+- **Core CLI release metadata**: patch-bump the core package after syncing the
+  latest `main` fix back toward `dev` so the next release can publish cleanly.
+
+---
+
 ## [0.46.27] - 2026-05-20
 
 ### Fixed

README.md

@@ -59,6 +59,8 @@ specfact code review run --path . --scope full
 
 The sample output comes from a pinned capture against `nold-ai/specfact-demo-repo`. Reproduce it with `docs/_support/readme-first-contact/capture-readme-output.sh`; capture metadata lives alongside the raw logs in `docs/_support/readme-first-contact/sample-output/`.
 
+The Code Review bundle also reports `ai_bloat` advisories for code shapes that AI-assisted coding often amplifies, such as redundant wrappers, passthrough lambdas, identity `try`/`except` blocks, and avoidable intermediate lists. These findings are advisory, score-neutral, and not AI-authorship detection. Use the generated `.specfact/code-review.json` report with the Project bundle's `/specfact.08-simplify` IDE prompt to review each cleanup before accepting it. See the [AI bloat quickstart](https://modules.specfact.io/quickstart-ai-bloat/) on the modules docs site.
+
 ## What SpecFact does
 
 - **Reviews AI-assisted changes deterministically** — compare code against contracts, clean-code rules, and policy gates

docs/getting-started/quickstart.md

@@ -12,11 +12,12 @@ doc_owner: specfact-cli
 tracks:
   - src/specfact_cli/**
   - openspec/**
-last_reviewed: 2026-04-02
+last_reviewed: 2026-05-21
 exempt: false
 exempt_reason: ""
 ---
 
+<!-- markdownlint-disable-next-line MD025 -->
 # 5-Minute Quickstart
 
 Get from zero to a **scored code review** in a few commands. This path is aimed at developers who want one command and one clear result before reading about modules, profiles, or architecture.
@@ -44,6 +45,14 @@ uvx specfact-cli code review run --path . --scope full
 
 You should see a **Verdict**, **Score**, and findings. That is the fastest “aha” path on a real codebase.
 
+If the Code Review bundle reports `category=ai_bloat`, treat those entries as cleanup candidates, not proof of AI authorship. They are `severity=info`, advisory-only, and score-neutral. Write the JSON report, then use `/specfact.08-simplify` from your IDE prompts to review each proposed simplification:
+
+```bash
+uvx specfact-cli code review run --json --out .specfact/code-review.json --path . --scope full
+```
+
+For the focused walkthrough, see the [AI bloat quickstart](https://modules.specfact.io/quickstart-ai-bloat/) on the modules docs site.
+
 ## Step 3: Install SpecFact locally (optional)
 
 When you want a stable `specfact` command and IDE integration, install with pip:

docs/index.md

@@ -10,11 +10,12 @@ doc_owner: specfact-cli
 tracks:
   - src/specfact_cli/**
   - openspec/**
-last_reviewed: 2026-04-02
+last_reviewed: 2026-05-21
 exempt: false
 exempt_reason: ""
 ---
 
+<!-- markdownlint-disable-next-line MD025 -->
 # SpecFact CLI Documentation
 
 **Review AI-assisted code against your own contracts.**
@@ -33,6 +34,8 @@ fastest way to see SpecFact on existing code. [Read the full quickstart →](/ge
 
 SpecFact does **not** include built-in AI. It pairs deterministic CLI commands with your chosen IDE and copilot so fast-moving work has a stronger validation and alignment layer around it.
 
+**New in Code Review:** `ai_bloat` advisories flag bloated shapes commonly produced during AI-assisted coding, then feed the `/specfact.08-simplify` IDE prompt for human-confirmed cleanup. They are advisory, score-neutral, and do not classify whether code was written by AI. [Try the AI bloat quickstart on modules.specfact.io](https://modules.specfact.io/quickstart-ai-bloat/).
+
 **SpecFact is the validation and alignment layer for software delivery.**
 
 ---

docs/modules/code-review.md

@@ -1,13 +1,13 @@
 ---
 layout: default
 title: Code Review Module
-description: Install and use the official specfact-code-review module scaffold.
+description: Install and use the official specfact-code-review module for structured review execution, scoring, advisory cleanup, and reporting.
 permalink: /modules/code-review/
 ---
 
 ## Code Review Module
 
-The `nold-ai/specfact-code-review` module extends `specfact code` with a governed `review` subgroup for structured review execution, scoring, and reporting.
+The `nold-ai/specfact-code-review` module extends `specfact code` with a governed `review` subgroup for structured review execution, scoring, advisory cleanup, and reporting.
 
 ## Install
 
@@ -29,7 +29,35 @@ The scaffold adds these review entrypoints:
 - `specfact code review ledger`
 - `specfact code review rules`
 
-This change delivers the command scaffold and the review data model foundation. Runtime review execution and ledger/rules behavior can be layered on in later changes.
+For bundle-deep command usage, keep the modules docs open alongside this core handoff page. The modules quickstart for AI-shaped bloat cleanup lives at [modules.specfact.io/quickstart-ai-bloat/](https://modules.specfact.io/quickstart-ai-bloat/).
+
+## AI-shaped bloat advisories
+
+The review pipeline emits `ai_bloat` findings for code shapes commonly amplified by AI-assisted generation: manual append loops, passthrough lambdas, identity `try`/`except` blocks, 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 exempt from the normal `info: -1` scoring deduction
+- score-neutral even though they use `severity=info`
+- written to `.specfact/code-review.json` when the report includes all severities
+
+They are bloat-shape detection, not AI-authorship detection. Use them as cleanup candidates and confirm each rewrite in your IDE.
+
+Run the review with JSON output:
+
+```bash
+specfact code review run --json --out .specfact/code-review.json
+```
+
+Then run `/specfact.08-simplify` after installing or refreshing Project bundle IDE prompts:
+
+```bash
+specfact module install nold-ai/specfact-project
+specfact init ide
+```
+
+The prompt reads `.specfact/code-review.json`, filters `category=ai_bloat`, groups findings by file and rule, and asks before applying each simplification.
 
 ## Scoring Algorithm
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.46.27"
+version = "0.46.28"
 description = "The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with validation and contract enforcement for new projects and long-lived codebases."
 readme = "README.md"
 requires-python = ">=3.11"

setup.py

@@ -7,7 +7,7 @@
 if __name__ == "__main__":
     _setup = setup(
         name="specfact-cli",
-        version="0.46.27",
+        version="0.46.28",
         description=(
             "The swiss knife CLI for agile DevOps teams. Keep backlog, specs, tests, and code in sync with "
             "validation and contract enforcement for new projects and long-lived codebases."

src/__init__.py

@@ -3,4 +3,4 @@
 """
 
 # Package version: keep in sync with pyproject.toml, setup.py, src/specfact_cli/__init__.py
-__version__ = "0.46.27"
+__version__ = "0.46.28"

src/specfact_cli/__init__.py

@@ -45,6 +45,6 @@ def _bootstrap_bundle_paths() -> None:
 
 _bootstrap_bundle_paths()
 
-__version__ = "0.46.27"
+__version__ = "0.46.28"
 
 __all__ = ["__version__"]