Promote dev to main

.vibe/skills/specfact-code-review/SKILL.md

@@ -1,15 +1,27 @@
 ---
 name: specfact-code-review
-description: House rules for AI coding sessions derived from review findings
+description: Use for SpecFact code review workflows, especially when the user asks to remove AI bloat, simplify code, apply clean-code patterns, reduce boilerplate, fix review findings, or interpret SpecFact guidance.
 allowed-tools: []
 ---
 
-# House Rules - AI Coding Context (v4)
+# SpecFact Code Review Skill
 
-Updated: 2026-03-30 | Module: nold-ai/specfact-code-review
+Updated: 2026-05-22 | Module: nold-ai/specfact-code-review
+
+Use this skill as an interactive cleanup coach, not a raw lint executor. When a user says "remove AI bloat", "simplify", "apply clean code", "fix SpecFact review", or similar, run the SpecFact review workflow, explain decisions in the user's language, show exact patch previews, and validate after small changes.
 
 ## DO
 
+- Treat `specfact code review run --help` as authoritative; use `--instructions` as the fallback AI workflow when prompts/skills are unavailable
+- For simplification queues, run `specfact code review run --scope changed --focus simplify --json --out .specfact/code-review-simplify.json`
+- Ask for walkthrough level when interactive: vibe coder, junior developer, senior/pro, or headless agent; auto-adjust if obvious
+- For vibe coders, present each finding as a decision card: plain-language issue, why it might need to stay, exact patch preview, validation plan, and recommended choice
+- Interpret `guidance_kind`: `safe_mechanical` may apply after local safety checks, `needs_tests` requires tests first, `design_judgment` needs human choice with intent evidence, `preserve` means keep and log `preserve_reason`
+- For `design_judgment`, inspect API, callback, framework hook, adapter, public symbol, CLI boundary, compatibility shim, and readability intent; if intent is unclear, default to keep or skip
+- Log each simplification action as recommended, applied, kept, skipped, failed, with evidence of improvement or preserved contract
+- In headless mode, process one file at a time and emit an action table: file, line, rule, guidance_kind, recommended_action, action_status, evidence
+- Run targeted tests or rerun simplify review after each accepted file or very small batch; if validation cannot prove safety, downgrade to `needs_tests` or `skipped`
+- For merge-quality review, run `specfact code review run --scope changed --bug-hunt --json --out .specfact/code-review.json`
 - Ask whether tests should be included before repo-wide review; default to excluding tests unless test changes are the target
 - Use intention-revealing names; avoid placeholder public names like data/process/handle
 - Keep functions under 120 LOC, shallow nesting, and <= 5 parameters (KISS)
@@ -23,6 +35,10 @@ Updated: 2026-03-30 | Module: nold-ai/specfact-code-review
 
 ## DON'T
 
+- Don't copy prompt templates into AI IDEs when this installed skill can carry the reusable workflow guidance
+- Don't treat simplification findings as AI-authorship proof or apply batch rewrites without explicit user approval
+- Don't ask non-expert users to infer code intent from a raw warning; provide the evidence and safest recommendation
+- Don't apply `design_judgment` findings just because the patch looks shorter
 - Don't enable known noisy findings unless you explicitly want strict/full review output
 - Don't use bare except: or except Exception: pass
 - Don't add # noqa / # type: ignore without inline justification

README.md

@@ -77,6 +77,11 @@ python scripts/sign-modules.py --allow-unsigned --payload-from-filesystem packag
 
 The pre-commit hook auto-runs this step and re-stages updated manifests on non-`main` branches.
 
+Use semantic versioning per bundle payload: patch for bug fixes and backward-compatible metadata or schema additions,
+minor for additive commands or public API capabilities, and major for breaking command, API, or schema changes.
+Manifest `integrity.checksum` values cover the canonical module source payload; registry
+`checksum_sha256` and `.tar.gz.sha256` files cover the published tarball artifact, so these hashes can differ.
+
 ### When signatures are required
 
 | Context | Requirement |

docs/bundles/code-review/run.md

@@ -40,6 +40,7 @@ The pipeline reviews **`.py`** and **`.pyi`** only. The **`--focus docs`** facet
 | `--no-tests` | Skip the TDD gate |
 | `--fix` | Apply Ruff autofixes, then rerun the review |
 | `--interactive` | Prompt for scope decisions before execution |
+| `--instructions` | Print AI-facing simplify / clean-code workflow instructions and exit without running review |
 
 ## Invalid combinations
 
@@ -98,6 +99,16 @@ specfact code review run --scope full --focus docs
 specfact code review run --scope changed --focus simplify --json --out .specfact/code-review-simplify.json
 ```
 
+### AI instructions fallback
+
+When an IDE does not support bundled prompts or skills, print the same guided simplify workflow for an AI assistant:
+
+```bash
+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.
+
 ### Positional files (explicit Python paths)
 
 Do not pass **`--scope`** or **`--path`** when **`FILES...`** are present.

docs/modules/code-review.md

@@ -61,6 +61,8 @@ Options (aligned with `specfact code review run --help`):
 - `--fix`: apply Ruff autofixes and re-run the review before printing results
 - `--interactive`: ask whether changed test files should be included before
   auto-detected review runs
+- `--instructions`: print AI-facing simplify / clean-code workflow instructions
+  and exit without requiring installed slash prompts or skills
 
 ### Invalid combinations
 
@@ -114,6 +116,23 @@ The review pipeline also emits `ai_bloat` findings for code shapes commonly ampl
 
 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.
 
+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:
+
+```bash
+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
+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
+as explicit positional files, and treat findings without `guidance_kind` as
+unguided advisories, not auto-fix input.
+
 Positional `FILES...` cannot be mixed with **`--scope`** or **`--path`** (see
 **Invalid combinations** above).
 
@@ -399,11 +418,12 @@ Then rerun the ledger command from the same repository checkout.
 ## Code review skill
 
 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:
+Claude, Vibe, and Cursor-compatible IDEs. New users do not need to install it
+first: `specfact code review run --instructions` prints the same guided
+simplify workflow for any AI assistant. Install the skill later when the IDE
+supports automatic skill loading and you want the reusable workflow attached to
+phrases such as "remove AI bloat", "simplify", or "apply clean-code patterns".
+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.

openspec/CHANGE_ORDER.md

@@ -102,6 +102,7 @@ The architecture pillar remains active because `architecture-02-well-architected
 | 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) |
+| 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) |
 
 ### Documentation restructure
 

openspec/changes/code-review-12-guided-simplification-enforcement/.openspec.yaml

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