Fix PR 289 code review findings

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

@@ -1,20 +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-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
-- Interpret `guidance_kind`: `safe_mechanical` may apply after local safety checks, `needs_tests` requires tests first, `design_judgment` needs human choice, `preserve` means keep and log `preserve_reason`
+- 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)
@@ -28,6 +35,10 @@ Updated: 2026-05-22 | 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

@@ -79,6 +79,8 @@ The pre-commit hook auto-runs this step and re-stages updated manifests on non-`
 
 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
 

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 origin/dev...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 origin/dev...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/changes/code-review-12-guided-simplification-enforcement/TDD_EVIDENCE.md

@@ -22,6 +22,10 @@
   - Result: failed as expected before final detector tightening.
   - Evidence: 2 failed.
   - Missing contract areas: safe-mechanical dead-branch detection required the current duplicate guard to be terminal and have no `else`.
+- `hatch run pytest tests/unit/specfact_code_review/tools/test_ai_bloat_runner.py::test_dead_branch_ignores_duplicate_guard_after_assignment tests/unit/specfact_code_review/run/test_commands.py::test_apply_simplification_fixes_keeps_dead_branch_after_assignment tests/unit/specfact_code_review/run/test_commands.py::test_run_review_once_applies_simplification_fixes_before_rerun -q`
+  - Result: failed as expected before PR 289 dev-branch review fixes.
+  - Evidence: 3 failed.
+  - Missing contract areas: duplicate guard state invalidation, dead-branch autofix state invalidation, and applied simplification evidence in the post-fix report.
 
 ## Passing After
 
@@ -43,26 +47,40 @@
   - Result after complexity cleanup: 3 passed.
 - `hatch run pytest tests/unit/specfact_code_review/tools/test_ai_bloat_runner.py::test_dead_branch_flags_duplicate_prior_return_guard tests/unit/specfact_code_review/tools/test_ai_bloat_runner.py::test_dead_branch_ignores_duplicate_guard_after_else_path tests/unit/specfact_code_review/tools/test_ai_bloat_runner.py::test_dead_branch_ignores_nonterminal_duplicate_guard tests/unit/specfact_code_review/tools/test_ai_bloat_runner.py::test_dead_branch_ignores_duplicate_guard_with_else tests/unit/specfact_code_review/tools/test_ai_bloat_runner.py::test_dead_branch_ignores_impure_duplicate_guard -q`
   - Result after final detector tightening: 5 passed.
+- `hatch run pytest tests/unit/specfact_code_review/tools/test_ai_bloat_runner.py::test_dead_branch_ignores_duplicate_guard_after_assignment tests/unit/specfact_code_review/run/test_commands.py::test_apply_simplification_fixes_keeps_dead_branch_after_assignment tests/unit/specfact_code_review/run/test_commands.py::test_run_review_once_applies_simplification_fixes_before_rerun -q`
+  - Result after PR 289 dev-branch review fixes: 3 passed.
+- `hatch run pytest tests/unit/test_guided_simplify_resources.py -q`
+  - Result after prompt/skill user-experience tightening: 2 passed.
+- `hatch run validate-prompt-commands`
+  - Result after prompt/skill user-experience tightening: prompt command validation passed with no findings.
+- `hatch run pytest tests/unit/specfact_code_review/review/test_commands.py::test_review_run_help_lists_simplify_focus tests/unit/specfact_code_review/review/test_commands.py::test_review_run_instructions_prints_ai_workflow_without_running_review tests/unit/docs/test_code_review_docs_parity.py::test_code_review_run_doc_mentions_public_ty_options tests/unit/test_guided_simplify_resources.py tests/unit/specfact_code_review/rules/test_updater.py::test_load_bundled_skill_content_returns_valid_structure_when_available -q`
+  - Result after adding the AI instructions fallback and docs: 6 passed.
+- `hatch run specfact code review run --instructions`
+  - Result after adding the AI instructions fallback: printed the guided simplify / clean-code workflow and exited successfully without running review analysis.
+- Subagent simulation with only `specfact code review run --instructions` guidance
+  - Result: the assistant followed the conservative decision-card workflow, treated missing `guidance_kind` findings as unguided advisories, and identified the clean-PR branch fallback as actionable after adding a base-ref diff example.
 - `hatch run contract-test`
   - Result after PR review fixes: 758 passed, 2 warnings.
 - `hatch run smart-test`
   - Result: 742 passed, 2 warnings.
 - `hatch run type-check`
   - Result: 0 errors, 0 warnings, 0 notes.
 - `hatch run lint`
-  - Result: 10.00/10.
+  - Result after AI instructions fallback: 10.00/10.
 - `hatch run yaml-lint`
-  - Result: validated 6 manifests and `registry/index.json`.
+  - Result after AI instructions fallback: validated 6 manifests and `registry/index.json`.
 - `hatch run check-bundle-imports`
   - Result: import boundary check passed.
 - `hatch run validate-prompt-commands`
   - Result: prompt command validation passed with no findings.
 - `hatch run verify-modules-signature --payload-from-filesystem --enforce-version-bump --version-check-base origin/dev`
-  - Result after PR review fixes: verified 6 module manifests.
+  - Result after AI instructions fallback: verified 6 module manifests.
 - `hatch run specfact code review run --bug-hunt --json --out .specfact/code-review.json --scope changed`
   - Result after final PR review fixes: PASS, CI exit 0, score 120, 0 findings.
+- `hatch run specfact code review run --bug-hunt --include-tests --json --out .specfact/code-review.json --scope changed`
+  - Result after AI instructions fallback: PASS, CI exit 0, 0 findings.
 - `openspec validate code-review-12-guided-simplification-enforcement --strict`
-  - Result: valid.
+  - Result after AI instructions fallback: valid.
 
 ## Local Dev-Link Validation
 
@@ -88,4 +106,4 @@
 
 ## Signing Note
 
-`hatch run verify-modules-signature --payload-from-filesystem --require-signature --enforce-version-bump --version-check-base origin/main` passed before the final source edits, verifying the existing `0.47.23` signature was a real cryptographic signature. The final local payload was then bumped to `0.47.24` and refreshed with `hatch run sign-modules --changed-only --base-ref origin/dev --bump-version patch --allow-unsigned --payload-from-filesystem`, because no private signing key is available in the local worktree. Cryptographic signature restoration remains an approval-time or post-merge signing step.
+`hatch run verify-modules-signature --payload-from-filesystem --require-signature --enforce-version-bump --version-check-base origin/main` passed before the final source edits, verifying the existing `0.47.23` signature was a real cryptographic signature. The final local payload is refreshed at `0.47.25` for `specfact-code-review` and `0.41.16` for `specfact-project` with `hatch run sign-modules --changed-only --base-ref origin/dev --bump-version patch --allow-unsigned --payload-from-filesystem`, because no private signing key is available in the local worktree. Cryptographic signature restoration remains an approval-time or post-merge signing step.

packages/specfact-code-review/module-package.yaml

@@ -1,5 +1,5 @@
 name: nold-ai/specfact-code-review
-version: 0.47.24
+version: 0.47.26
 commands:
   - code
 tier: official
@@ -23,5 +23,5 @@ description: Official SpecFact code review bundle package.
 category: codebase
 bundle_group_command: code
 integrity:
-  checksum: sha256:32bdb881f64482da2f10785b952e9ee39270aa4df34d27b24d068aae9a09d7a7
-  signature: 8Uf+zsIzLokI9U4yVB10W1NtVFjI66HzKz3uzZPnqLwHi3eKrcDW9g6L97ncRU13gdOoQMvs/S2OQkNIRwaABA==
+  checksum: sha256:87a17f884d717d6def557d2bfc3076288d610e4751a38b12aed4e72e64ed32e2
+  signature: uGnmRW920celR5bugIuq8XLjBJ4qdWT/WZmUz/h/Gk7/V0VD7NY+F7O0wB8BgaClL55yxochTTFEjEM18iHmCA==

packages/specfact-code-review/src/specfact_code_review/resources/skills/specfact-code-review/SKILL.md

@@ -1,22 +1,22 @@
 ---
 name: specfact-code-review
-description: CLI-grounded SpecFact code review workflow and house rules for AI coding sessions
+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 / SpecFact Code Review Skill (v2)
-
+# SpecFact Code Review Skill
 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
-- Use this skill when asked to run, interpret, or act on SpecFact code review in Codex CLI or another AI IDE
-- Treat `specfact code review run --help` as authoritative; self-heal stale options by checking help before changing workflow
+- 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
-- Interpret `guidance_kind`: `safe_mechanical` may apply after local safety checks, `needs_tests` requires tests first, `design_judgment` needs human choice, `preserve` means keep and log `preserve_reason`
+- 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)
 - Delete unused private helpers and speculative abstractions quickly (YAGNI)
@@ -28,6 +28,8 @@ Updated: 2026-05-22 | 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