prizmkit 1.1.130 → 1.1.134

package/bundled/skills/refactor-planner/references/behavior-preservation.md

@@ -1,306 +1,187 @@
-# Behavior Preservation Guide
+# Behavior Preservation Planning Guide
 
-This guide covers strategies for ensuring that refactoring changes structure without changing behavior. Every refactor item must declare a behavior preservation strategy.
+This guide helps the planner select and describe behavior-preservation evidence for each refactor item. It is a planning reference only: inspect existing code and test configuration as read-only evidence, then record what the downstream refactor session must prove. Do not run tests, change code, capture runtime snapshots, or perform rollback from this planner.
 
----
+## Table of Contents
 
-## 1. Preservation Strategies
+1. [Planning Boundary](#planning-boundary)
+2. [Preservation Strategies](#preservation-strategies)
+3. [Strategy Selection](#strategy-selection)
+4. [Behavior-Risk Checklist](#behavior-risk-checklist)
+5. [Coverage Assessment](#coverage-assessment)
+6. [Plan-Readiness Checklist](#plan-readiness-checklist)
 
-### Strategy: test-gate
+## Planning Boundary
 
-**Definition**: Run the full test suite after each refactoring change. All previously-passing tests must continue to pass.
+For every refactor item, the planner must:
 
-**How it works**:
-1. Run the full test suite before starting the refactor item (establish baseline)
-2. Implement the refactoring change
-3. Run the full test suite again
-4. Compare: all tests that passed before must still pass
-5. If any test fails -> revert the change, investigate, and retry
+- choose a primary strategy: `test-gate`, `snapshot`, or `manual`;
+- identify the observable behavior that must remain stable;
+- identify existing evidence sources when they are discoverable by reading the repository;
+- record missing evidence and any prerequisite item needed to close the gap;
+- write measurable acceptance criteria that a non-interactive downstream session can evaluate;
+- avoid claiming that tests, snapshots, or manual verification have already run.
 
-**When to use**:
-- Target area has good test coverage (>60%)
-- Tests are reliable (no flaky tests in the target area)
-- Test suite runs in reasonable time (<5 minutes for the relevant subset)
-- Tests cover the behavior contracts you need to preserve
+## Preservation Strategies
 
-**Strengths**:
-- Most reliable automated strategy
-- Catches regressions immediately
-- Well-understood and widely practiced
-- Works with any test framework
+### Strategy: `test-gate`
 
-**Limitations**:
-- Only as good as test coverage — untested behavior can still break
-- Slow test suites may bottleneck iteration speed
-- Flaky tests create false negatives
+Use when the target has reliable automated tests that cover the behavior being preserved.
+
+Planning requirements:
+
+- name the relevant test files, suites, or project-native test command when discoverable;
+- identify the behavior contracts represented by those tests;
+- require evidence that previously passing relevant tests remain passing after the structural change;
+- note known flaky tests or coverage gaps;
+- add a prerequisite planning item when missing tests make the refactor unsafe.
 
-**Configuration in refactor-list.json**:
 ```json
 {
   "behavior_preservation": {
     "strategy": "test-gate",
-    "existing_tests": true
+    "existing_tests": true,
+    "new_tests_needed": []
   }
 }
 ```
 
----
-
-### Strategy: snapshot
+### Strategy: `snapshot`
 
-**Definition**: Capture the observable output/state of the target code before and after refactoring, then compare.
+Use when formal coverage is insufficient but deterministic observable behavior can be compared.
 
-**How it works**:
-1. Identify observable outputs of the target code (API responses, rendered UI, log output, file output)
-2. Capture a "before" snapshot by exercising the code with representative inputs
-3. Implement the refactoring change
-4. Capture an "after" snapshot with the same inputs
-5. Compare: snapshots must match (or differ only in acceptable ways like formatting)
+Planning requirements:
 
-**When to use**:
-- Test coverage is insufficient but behavior is observable
-- The code produces deterministic output for given inputs
-- You can identify representative inputs that exercise the key behavior paths
-- API endpoints, CLI tools, data processing pipelines
+- define representative inputs;
+- define the observable outputs or state to compare;
+- define allowed normalization or acceptable differences;
+- require before/after evidence from the same inputs;
+- identify non-deterministic fields that must be excluded or normalized.
 
-**Strengths**:
-- Works even when formal tests are missing
-- Captures real behavior rather than test assertions
-- Can detect subtle regressions that tests might miss
-
-**Limitations**:
-- Requires deterministic behavior (non-deterministic outputs need normalization)
-- May miss edge cases if representative inputs are incomplete
-- Snapshot comparison tools may need configuration for acceptable differences
-- More manual setup than test-gate
-
-**Configuration in refactor-list.json**:
 ```json
 {
   "behavior_preservation": {
-    "strategy": "snapshot"
+    "strategy": "snapshot",
+    "existing_tests": false,
+    "new_tests_needed": []
   },
   "acceptance_criteria": [
-    "API responses for /api/users/* match before/after snapshots",
-    "CLI output for --help remains unchanged"
+    "Responses for the documented API cases match the approved baseline after normalization",
+    "CLI help output preserves all documented flags and exit codes"
   ]
 }
 ```
 
----
-
-### Strategy: manual
+### Strategy: `manual`
 
-**Definition**: Human verification is required to confirm behavior is preserved. Used as a last resort.
+Use only when neither reliable tests nor deterministic observable output can prove preservation.
 
-**When to use**:
-- No test coverage AND no easily observable deterministic output
-- UI-heavy changes where visual regression is the primary concern
-- Legacy code with unknown behavior contracts
-- Code that interacts with external services in non-reproducible ways
+Planning requirements:
 
-**How it works**:
-1. Document the current behavior (screenshots, recordings, written descriptions)
-2. Implement the refactoring change
-3. Human manually verifies the behavior matches the documentation
-4. Human signs off on the change
+- state exactly which behavior requires human judgment;
+- define a reproducible verification checklist;
+- identify required screenshots, recordings, or written baselines;
+- mark the item as high verification risk;
+- avoid subjective criteria such as “looks correct” without named observations.
 
-**Strengths**:
-- Works for any situation
-- Humans can assess subjective quality (UI layout, user experience)
-- Can catch issues that automated tools miss
-
-**Limitations**:
-- Slowest strategy — blocks on human availability
-- Error-prone — humans miss regressions, especially subtle ones
-- Not scalable — each item needs separate human attention
-- Not repeatable — different humans may verify differently
-
-**Configuration in refactor-list.json**:
 ```json
 {
   "behavior_preservation": {
-    "strategy": "manual"
+    "strategy": "manual",
+    "existing_tests": false,
+    "new_tests_needed": []
   },
   "acceptance_criteria": [
-    "Manual verification confirms email login, social login, and password reset behavior remain unchanged"
+    "The verification checklist covers email login, social login, and password reset without changing their documented outcomes"
   ]
 }
 ```
 
----
-
-## 2. Choosing the Right Strategy
-
-Use this decision tree to select the appropriate strategy for each refactor item:
-
-1. If the target area has reliable test coverage above 60%, choose `test-gate`.
-2. If tests exist but are flaky, plan a prerequisite item to stabilize tests first; if stabilization is out of scope, choose `snapshot`.
-3. If test coverage is below 60% but behavior is deterministic and observable, choose `snapshot`.
-4. If neither reliable tests nor deterministic observable output exist, choose `manual` and flag the item as high risk.
-
-### Strategy Selection Table
-
-| Test Coverage | Output Observable | Recommended Strategy | Risk Level |
-|--------------|-------------------|---------------------|------------|
-| High (>60%) | Yes | test-gate | Low |
-| High (>60%) | No | test-gate | Low |
-| Medium (30-60%) | Yes | test-gate + snapshot | Medium |
-| Medium (30-60%) | No | test-gate (acknowledge gaps) | Medium |
-| Low (<30%) | Yes | snapshot | Medium-High |
-| Low (<30%) | No | manual | High |
-| None (0%) | Yes | snapshot | High |
-| None (0%) | No | manual | Very High |
-
-### Mixed Strategies
-
-For complex items, you can combine strategies:
-- **test-gate + snapshot**: Run tests AND compare output snapshots. Provides defense in depth.
-- **test-gate + manual**: Run tests AND have a human verify UI/UX aspects.
-- Use the primary strategy in the `behavior_preservation` field and note the secondary in `verification_notes`.
-
----
-
-## 3. Common Behavior-Breaking Pitfalls
-
-These are patterns that frequently cause unintended behavior changes during refactoring. Check for each one when planning.
-
-### 3.1 Side Effect Ordering
-
-**Pitfall**: Reordering function calls or module initialization can change side effects.
-
-**Example**: Moving `initLogger()` after `loadConfig()` when the logger depends on config.
+## Strategy Selection
 
-**Prevention**: Map side effects and their dependencies before restructuring. Document execution order constraints.
+Choose the smallest strategy that can credibly prove behavior preservation:
 
-### 3.2 Error Handling Changes
+1. Reliable relevant tests exist and cover the contract: choose `test-gate`.
+2. Tests are incomplete but behavior is deterministic and observable: choose `snapshot`.
+3. Tests are flaky: plan stabilization as a prerequisite, or use `snapshot` when stabilization is explicitly out of scope.
+4. Neither automated evidence source is viable: choose `manual` and document the risk.
 
-**Pitfall**: Extracting code into a new function changes which errors are caught and where.
+| Existing Evidence | Observable Output | Primary Strategy | Planning Risk |
+|---|---|---|---|
+| Reliable tests | Any | `test-gate` | Low |
+| Partial tests | Deterministic | `snapshot` or `test-gate` with documented gaps | Medium |
+| No reliable tests | Deterministic | `snapshot` | High |
+| No reliable tests | Non-deterministic or subjective | `manual` | Very high |
 
-**Example**: A try/catch block that previously caught errors from inline code no longer catches them when the code is extracted to a separate function with its own error handling.
+When a complex item needs more than one evidence type, keep one primary strategy in `behavior_preservation` and record supplemental evidence in acceptance criteria or verification notes.
 
-**Prevention**: Trace error propagation paths before and after. Ensure the same errors reach the same handlers.
+## Behavior-Risk Checklist
 
-### 3.3 Closure and Scope Changes
+Inspect the target and capture relevant risks in the item description or acceptance criteria.
 
-**Pitfall**: Moving code changes what variables are in scope, especially with closures.
+### Side-effect ordering
 
-**Example**: Extracting a closure that captures `this` into a standalone function loses the `this` binding.
+Record initialization, mutation, and external-call ordering that must not change.
 
-**Prevention**: Identify all captured variables. Ensure they are passed as parameters or the binding is preserved.
+### Error propagation
 
-### 3.4 Import Order Side Effects
+Record which errors reach which handlers, including error types, messages, codes, and retry behavior.
 
-**Pitfall**: In some languages/frameworks, import order matters (module initialization, polyfills, monkey-patching).
+### Closure and binding semantics
 
-**Example**: Moving an import of a polyfill to a different position causes it to load after the code that needs it.
+Record captured variables, `this` binding, lifetime, and scope assumptions affected by extraction or movement.
 
-**Prevention**: Identify imports with side effects. Document order constraints. Test module initialization explicitly.
+### Import-time behavior
 
-### 3.5 Default Parameter Changes
+Record side-effect imports, polyfills, registration order, and module initialization dependencies.
 
-**Pitfall**: Extracting a function and adding default parameters changes behavior for callers that relied on the old defaults.
+### Defaults and type coercion
 
-**Example**: Original: `function process(data, format) { format = format || 'json'; ... }` — Refactored: `function process(data, format = 'json') { ... }` — These behave differently for `process(data, '')` (empty string).
+Record existing default-value and coercion behavior, especially where falsy values differ from missing values.
 
-**Prevention**: Audit all default value logic. Use identical defaulting behavior in the refactored version.
+### Async timing and concurrency
 
-### 3.6 Async/Await Conversion Gotchas
+Record ordering, atomicity, cancellation, race, and shared-state constraints.
 
-**Pitfall**: Converting callbacks to async/await can change error propagation, timing, and concurrency.
+### Public interfaces
 
-**Example**: Callback errors that were silently swallowed now throw unhandled promise rejections.
+Record exports, signatures, import paths, configuration keys, CLI flags, response shapes, and compatibility commitments.
 
-**Prevention**: Map all error paths in the callback version. Ensure async version handles every path. Test with error scenarios.
+### Operational observability
 
-### 3.7 Type Coercion Changes
+Record log patterns, metrics, alerts, performance limits, and other externally observed behavior that consumers rely on.
 
-**Pitfall**: Moving code between contexts can change implicit type coercion behavior.
+## Coverage Assessment
 
-**Example**: `==` comparisons that relied on type coercion break when types change due to new module boundaries.
+Assess coverage by reading existing repository evidence only:
 
-**Prevention**: Prefer strict equality. Audit type assumptions at module boundaries.
+- test runner configuration;
+- relevant test files and their imports;
+- assertions that describe behavior contracts;
+- existing coverage reports when already present;
+- project documentation and CI configuration.
 
-### 3.8 Timing and Race Conditions
+Do not generate fresh coverage evidence from this planner. When current coverage cannot be established from existing files, record it as `unknown` rather than guessing.
 
-**Pitfall**: Restructuring async code can change execution timing, revealing or creating race conditions.
-
-**Example**: Splitting a synchronous operation into two async steps creates a window where state is inconsistent.
-
-**Prevention**: Identify shared mutable state. Ensure atomicity is preserved. Test concurrent scenarios.
-
----
-
-## 4. Test Coverage Assessment
-
-Before refactoring, assess the test coverage of the target area to select the appropriate preservation strategy.
-
-### Quick Coverage Assessment
-
-If a formal coverage tool is available:
-```bash
-# JavaScript (Istanbul/nyc)
-npx nyc --reporter=text -- npm test -- --grep "target-module"
-
-# Python (pytest-cov)
-pytest --cov=target_module --cov-report=term-missing
-
-# Go
-go test -coverprofile=coverage.out ./target-package/...
-```
-
-### Manual Coverage Assessment
-
-When coverage tools aren't available, assess manually:
-
-1. **List all public functions/methods** in the target area
-2. **Search for test files** that import or reference the target
-3. **Check test assertions** — do they test behavior or just structure?
-4. **Identify untested paths** — error handling, edge cases, default behavior
-
-### Coverage-Based Planning Decisions
-
-| Coverage Level | Planning Decision |
-|---------------|-------------------|
-| >80% | Proceed with test-gate. High confidence in behavior preservation. |
-| 60-80% | Proceed with test-gate. Note gaps in refactor item descriptions for the pipeline to be cautious about. |
-| 30-60% | Consider writing additional tests before refactoring as a normal `R-NNN` prerequisite item. Or use snapshot strategy for low-coverage areas. |
-| <30% | Strongly recommend writing tests first. If user declines, use snapshot or manual strategy and flag as high risk. |
-| 0% | WARN user explicitly. Recommend writing tests as a prerequisite. If user insists on proceeding, use manual strategy and document all known behaviors. |
-
-### Adding Tests as a Prerequisite Item
-
-When test coverage is insufficient, add a prerequisite refactor item using the normal `R-NNN` sequence. If the prerequisite is added before other generated items, it is usually `R-001`; downstream refactors depend on that ID.
-
-```
-Refactor Item R-001:
-  Title: Add test coverage for [target area] before refactoring
-  Type: restructure
-  Scope: [test files]
-  Priority: critical
-  Complexity: medium
-  Behavior Preservation: manual (no existing tests to gate against)
-  Acceptance Criteria:
-    - Test coverage for [target area] reaches >60%
-    - Tests cover: [list key behavior contracts]
-    - All new tests pass
-  Dependencies: none
-```
+Planning decisions:
 
-This item runs first, establishing the test baseline that all subsequent items use for their test-gate strategy.
+- Strong relevant coverage: use `test-gate` and name the evidence source.
+- Partial coverage: list uncovered paths and consider a prerequisite test item.
+- No relevant coverage: prefer a prerequisite test item or a snapshot strategy.
+- No viable automated evidence: use `manual`, document the verification protocol, and flag the risk.
 
----
+A prerequisite test item remains a planning artifact. It must describe the missing contracts and measurable evidence without claiming the tests were already written or run.
 
-## 5. Behavior Verification Checklist
+## Plan-Readiness Checklist
 
-Before marking a refactor item as complete, verify:
+Before finalizing each refactor item, verify the plan states:
 
-- [ ] All previously-passing tests still pass
-- [ ] No new warnings or deprecation notices in test output
-- [ ] No new lint errors introduced
-- [ ] Public API surface is unchanged (same exports, same function signatures)
-- [ ] Error messages and error codes are unchanged (consumers may depend on these)
-- [ ] Logging output is unchanged (monitoring/alerting may depend on log patterns)
-- [ ] Configuration interface is unchanged (env vars, config files, CLI flags)
-- [ ] Performance characteristics are within acceptable bounds (no regression >10%)
-- [ ] No dead code left behind (unused imports, unreachable functions)
+- [ ] the primary preservation strategy;
+- [ ] the behavior contracts that must remain stable;
+- [ ] the existing evidence sources, or an explicit `unknown`/missing-evidence statement;
+- [ ] prerequisite evidence work when necessary;
+- [ ] measurable post-change acceptance criteria;
+- [ ] public interface and compatibility constraints;
+- [ ] error, logging, configuration, and performance constraints when relevant;
+- [ ] supplemental browser or manual evidence when automated evidence is insufficient;
+- [ ] no claim that implementation or verification has already occurred.

package/bundled/skills/refactor-planner/references/error-recovery.md

@@ -0,0 +1,37 @@
+# Refactor Planner Error Recovery
+
+Load this reference when validation fails, the planning session is interrupted, existing planning artifacts are detected, or the user exits before a valid final plan is produced.
+
+## Validation Recovery
+
+- Warnings only: present the warnings and ask whether to continue.
+- Validation errors: group related errors, correct the planning draft, and regenerate. Limit automatic correction to three attempts before asking the user how to proceed.
+- Keep `.prizmkit/plans/refactor-list.json` at the project-root `.prizmkit/plans/` path.
+- Do not alter source code or run project tests while recovering a planning artifact.
+
+## Resume Detection
+
+| Artifact Found | Resume Point |
+|---|---|
+| No planning artifact | Phase 1: Project Context |
+| Draft in `.prizmkit/plans/` | Phase matching the draft's completeness |
+| Incomplete final refactor list | Phase 6: Completeness Review |
+| Valid final refactor list | Mode D: Summary |
+
+Read the artifact directly because `.prizmkit` content may be gitignored. Preserve existing valid entries and resume only the unfinished planning work.
+
+## Session Exit Gate
+
+Activate the exit gate when all of these are true:
+
+- the user explicitly invoked `refactor-planner`;
+- validation has not passed;
+- no valid final refactor list was produced in this session.
+
+Use `AskUserQuestion` with these options:
+
+- **Continue to completion (Recommended)** — resume from the detected planning phase.
+- **Save draft and exit** — save current planning content as `.prizmkit/plans/refactor-list.draft.json`.
+- **Abandon** — exit without saving new planning content.
+
+When saving a draft, state clearly that it is not validated and can be resumed by running `refactor-planner` again.

package/bundled/skills/refactor-planner/references/planning-phases.md

@@ -19,9 +19,9 @@ For each refactoring goal:
 
 ## Phase 5: Per-Item Confirmation Loop
 
-For each item, display:
+For each item, present the structured fields and use `AskUserQuestion` for the decision:
 
-```
+```text
 Refactor Item R-001:
   Title: [title]
   Type: [extract/rename/restructure/simplify/decouple/migrate]
@@ -35,15 +35,9 @@ Refactor Item R-001:
     - [criterion 1]
     - [criterion 2]
   Dependencies: [none / R-002, R-003]
-  
-  Confirm? (Y/modify/skip)
 ```
 
-- **Y**: Accept item as-is
-- **modify**: User provides changes, update item, re-display for confirmation
-- **skip**: Remove item from the list
-
-Continue until all items are confirmed or skipped.
+Offer `Accept`, `Modify`, and `Skip` as selectable options. Re-display modified items before acceptance, and continue until all items are accepted or skipped.
 
 ---
 
@@ -83,9 +77,9 @@ Every item MUST declare a behavior preservation strategy. Read `${SKILL_DIR}/ref
 
 | Strategy | When to Use |
 |----------|-------------|
-| `test-gate` | Target area has good test coverage. Run full test suite after each change. |
-| `snapshot` | Compare output/state before and after. Used when tests are insufficient but behavior is observable. |
-| `manual` | Human verification required. Last resort when neither tests nor snapshots are feasible. |
+| `test-gate` | Reliable tests cover the preserved contract; record the relevant evidence and the required downstream pass condition. |
+| `snapshot` | Deterministic output or state can be compared; record representative inputs, normalization, and required equivalence. |
+| `manual` | Human judgment is unavoidable; record a reproducible checklist and flag the higher verification risk. |
 
 Flag items using `manual` strategy prominently — they carry the highest risk of behavior regression.
 
@@ -130,11 +124,11 @@ Anti-pattern: do not generate an all-high refactor list unless every item indepe
 
 ## Browser Verification
 
-Browser verification is supported for UI-affecting refactors, but it is supplemental. Every refactor still uses `behavior_preservation.strategy` as the primary behavior-preservation contract:
+Browser verification is supported for UI-affecting refactors, but it is supplemental. Every refactor still uses `behavior_preservation.strategy` as the primary preservation contract:
 
-- `strategy: test-gate` — Rely on existing test suite. Pipeline runs tests before and after refactoring.
-- `strategy: snapshot` — Compare behavior before/after refactoring using executable snapshots (outputs, API responses, side effects)
-- `strategy: manual` — Require human verification that behavior is preserved
+- `strategy: test-gate` — Record the relevant existing tests and the required downstream pass condition.
+- `strategy: snapshot` — Record the representative inputs, observable outputs, and allowed normalization for downstream comparison.
+- `strategy: manual` — Record a reproducible human-verification checklist and the reason automated evidence is insufficient.
 
 For refactors that modify UI code, add `browser_interaction.verify_steps` when visual or browser-flow verification is useful. Also keep behavior-preservation acceptance criteria explicit:
 
@@ -150,4 +144,4 @@ Acceptance Criteria:
   4. Component is reusable in other views
 ```
 
-The refactor pipeline AI will use the snapshot strategy to verify external behavior is preserved during refactoring.
+The generated plan supplies this evidence contract to the autonomous refactor session; this planner does not execute the verification.

package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py

@@ -32,7 +32,7 @@ from datetime import datetime, timezone
 
 SCHEMA_VERSION = "dev-pipeline-refactor-list-v1"
 
-VALID_STATUSES = {"pending", "in_progress", "completed", "failed", "skipped"}
+VALID_STATUSES = {"pending", "in_progress", "completed", "failed", "skipped", "auto_skipped"}
 VALID_TYPES = {"extract", "rename", "restructure", "simplify", "decouple", "migrate"}
 VALID_PRIORITIES = {"critical", "high", "medium", "low"}
 VALID_COMPLEXITIES = {"low", "medium", "high"}