prizmkit 1.1.190 → 1.1.192

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (189) hide show
  1. package/bin/create-prizmkit.js +4 -4
  2. package/bundled/VERSION.json +3 -3
  3. package/bundled/adapters/antigravity/assets/prizmkit-hook.cjs +150 -0
  4. package/bundled/adapters/antigravity/hooks-adapter.js +195 -0
  5. package/bundled/adapters/antigravity/paths.js +14 -0
  6. package/bundled/adapters/antigravity/rules-adapter.js +54 -0
  7. package/bundled/adapters/antigravity/skill-adapter.js +38 -0
  8. package/bundled/adapters/codex/skill-adapter.js +28 -8
  9. package/bundled/adapters/cursor/skill-adapter.js +13 -4
  10. package/bundled/adapters/pi/skill-adapter.js +28 -7
  11. package/bundled/dev-pipeline/.env.example +4 -12
  12. package/bundled/dev-pipeline/README.md +21 -15
  13. package/bundled/dev-pipeline/assets/skill-subagent-integration.md +3 -6
  14. package/bundled/dev-pipeline/prizmkit_runtime/atomic_io.py +48 -0
  15. package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py +66 -23
  16. package/bundled/dev-pipeline/prizmkit_runtime/cli.py +10 -7
  17. package/bundled/dev-pipeline/prizmkit_runtime/commands.py +2 -21
  18. package/bundled/dev-pipeline/prizmkit_runtime/config.py +29 -70
  19. package/bundled/dev-pipeline/prizmkit_runtime/daemon.py +125 -67
  20. package/bundled/dev-pipeline/prizmkit_runtime/gitops.py +89 -442
  21. package/bundled/dev-pipeline/prizmkit_runtime/heartbeat.py +93 -49
  22. package/bundled/dev-pipeline/prizmkit_runtime/interoperability.py +1 -3
  23. package/bundled/dev-pipeline/prizmkit_runtime/paths.py +0 -6
  24. package/bundled/dev-pipeline/prizmkit_runtime/platform_detection.py +49 -18
  25. package/bundled/dev-pipeline/prizmkit_runtime/processes.py +206 -151
  26. package/bundled/dev-pipeline/prizmkit_runtime/reset.py +2 -23
  27. package/bundled/dev-pipeline/prizmkit_runtime/reset_preserve.py +15 -134
  28. package/bundled/dev-pipeline/prizmkit_runtime/results.py +25 -0
  29. package/bundled/dev-pipeline/prizmkit_runtime/runner_bookkeeping.py +68 -83
  30. package/bundled/dev-pipeline/prizmkit_runtime/runner_classification.py +15 -5
  31. package/bundled/dev-pipeline/prizmkit_runtime/runner_models.py +1 -29
  32. package/bundled/dev-pipeline/prizmkit_runtime/runner_prompts.py +0 -2
  33. package/bundled/dev-pipeline/prizmkit_runtime/runner_status.py +7 -2
  34. package/bundled/dev-pipeline/prizmkit_runtime/runners.py +282 -217
  35. package/bundled/dev-pipeline/prizmkit_runtime/runtime_commit.py +124 -122
  36. package/bundled/dev-pipeline/prizmkit_runtime/runtime_helper.py +90 -9
  37. package/bundled/dev-pipeline/prizmkit_runtime/sessions.py +369 -154
  38. package/bundled/dev-pipeline/prizmkit_runtime/status.py +3 -3
  39. package/bundled/dev-pipeline/prizmkit_runtime/stream_progress.py +2780 -0
  40. package/bundled/dev-pipeline/prizmkit_runtime/task_checkout.py +27 -101
  41. package/bundled/dev-pipeline/prizmkit_runtime/test_result.py +58 -4
  42. package/bundled/dev-pipeline/scripts/check-session-status.py +43 -19
  43. package/bundled/dev-pipeline/scripts/continuation.py +6 -4
  44. package/bundled/dev-pipeline/scripts/detect-stuck.py +28 -28
  45. package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +7 -2
  46. package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py +7 -2
  47. package/bundled/dev-pipeline/scripts/init-bugfix-pipeline.py +10 -7
  48. package/bundled/dev-pipeline/scripts/init-change-artifact.py +8 -2
  49. package/bundled/dev-pipeline/scripts/init-pipeline.py +14 -69
  50. package/bundled/dev-pipeline/scripts/parse-stream-progress.py +31 -2328
  51. package/bundled/dev-pipeline/scripts/patch-completion-notes.py +4 -24
  52. package/bundled/dev-pipeline/scripts/prompt_framework.py +56 -9
  53. package/bundled/dev-pipeline/scripts/status_common.py +591 -0
  54. package/bundled/dev-pipeline/scripts/update-bug-status.py +85 -463
  55. package/bundled/dev-pipeline/scripts/update-checkpoint.py +227 -65
  56. package/bundled/dev-pipeline/scripts/update-feature-status.py +76 -509
  57. package/bundled/dev-pipeline/scripts/utils.py +10 -15
  58. package/bundled/dev-pipeline/templates/bootstrap-tier3.md +4 -4
  59. package/bundled/dev-pipeline/templates/bug-fix-list-schema.json +7 -0
  60. package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md +1 -1
  61. package/bundled/dev-pipeline/templates/sections/artifact-manifest.md +1 -1
  62. package/bundled/dev-pipeline/templates/sections/bugfix-phase-manual-verification.md +1 -1
  63. package/bundled/dev-pipeline/templates/sections/bugfix-phase-review.md +1 -1
  64. package/bundled/dev-pipeline/templates/sections/bugfix-phase-test.md +2 -1
  65. package/bundled/dev-pipeline/templates/sections/checkpoint-system.md +1 -1
  66. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-auto.md +1 -1
  67. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-opencli.md +2 -2
  68. package/bundled/dev-pipeline/templates/sections/phase-browser-verification.md +2 -2
  69. package/bundled/dev-pipeline/templates/sections/phase-prizmkit-test.md +2 -1
  70. package/bundled/dev-pipeline/templates/sections/phase-review-full.md +1 -1
  71. package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md +3 -6
  72. package/bundled/dev-pipeline/templates/session-status-schema.json +2 -5
  73. package/bundled/dev-pipeline/tests/_helpers.py +418 -0
  74. package/bundled/dev-pipeline/tests/conftest.py +45 -1
  75. package/bundled/dev-pipeline/tests/live_ai_cli_log_smoke.py +1 -0
  76. package/bundled/dev-pipeline/tests/test_auto_skip.py +4 -69
  77. package/bundled/dev-pipeline/tests/test_checkpoint_state.py +126 -1
  78. package/bundled/dev-pipeline/tests/test_daemon_and_scripts.py +257 -0
  79. package/bundled/dev-pipeline/tests/test_e2e_pipeline_run.py +500 -0
  80. package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py +59 -117
  81. package/bundled/dev-pipeline/tests/test_generate_bugfix_prompt.py +12 -10
  82. package/bundled/dev-pipeline/tests/test_python_runner_parity.py +561 -3094
  83. package/bundled/dev-pipeline/tests/test_recovery_workflow.py +7 -8
  84. package/bundled/dev-pipeline/tests/test_repository_bootstrap.py +0 -1
  85. package/bundled/dev-pipeline/tests/test_reset_modes.py +15 -27
  86. package/bundled/dev-pipeline/tests/test_reset_preserve.py +54 -139
  87. package/bundled/dev-pipeline/tests/test_runner_bookkeeping.py +766 -0
  88. package/bundled/dev-pipeline/tests/test_runner_lifecycle.py +1257 -0
  89. package/bundled/dev-pipeline/tests/test_runtime_helper.py +97 -20
  90. package/bundled/dev-pipeline/tests/test_session_launch.py +1101 -0
  91. package/bundled/dev-pipeline/tests/test_stream_progress.py +585 -0
  92. package/bundled/dev-pipeline/tests/test_unified_cli.py +490 -2006
  93. package/bundled/dev-pipeline/tests/test_utils.py +3 -3
  94. package/bundled/rules/USAGE.md +1 -0
  95. package/bundled/skills/_metadata.json +9 -63
  96. package/bundled/skills/app-planner/SKILL.md +32 -303
  97. package/bundled/skills/app-planner/references/app-design-guide.md +0 -4
  98. package/bundled/skills/app-planner/references/generated-plan-review.md +2 -1
  99. package/bundled/skills/app-planner/references/project-brief-guide.md +14 -0
  100. package/bundled/skills/app-planner/references/project-conventions-discovery.md +4 -6
  101. package/bundled/skills/app-planner/references/project-state-detection.md +2 -3
  102. package/bundled/skills/bug-fix-workflow/SKILL.md +1 -2
  103. package/bundled/skills/bug-fix-workflow/references/bug-diagnosis.md +4 -7
  104. package/bundled/skills/bug-planner/SKILL.md +54 -435
  105. package/bundled/skills/bug-planner/references/generated-plan-review.md +3 -2
  106. package/bundled/skills/bug-planner/references/input-formats.md +32 -0
  107. package/bundled/skills/bugfix-pipeline-launcher/SKILL.md +4 -6
  108. package/bundled/skills/bugfix-pipeline-launcher/references/configuration.md +4 -28
  109. package/bundled/skills/feature-pipeline-launcher/SKILL.md +4 -6
  110. package/bundled/skills/feature-pipeline-launcher/references/configuration.md +4 -28
  111. package/bundled/skills/feature-planner/SKILL.md +60 -439
  112. package/bundled/skills/feature-planner/assets/planning-guide.md +1 -1
  113. package/bundled/skills/feature-planner/references/completeness-review.md +34 -0
  114. package/bundled/skills/feature-planner/references/decomposition-patterns.md +2 -2
  115. package/bundled/skills/feature-planner/references/error-recovery.md +1 -1
  116. package/bundled/skills/feature-planner/references/generated-plan-review.md +3 -2
  117. package/bundled/skills/feature-planner/references/incremental-feature-planning.md +3 -1
  118. package/bundled/skills/feature-workflow/SKILL.md +1 -2
  119. package/bundled/skills/prizmkit/SKILL.md +7 -1
  120. package/bundled/skills/prizmkit-code-review/SKILL.md +14 -6
  121. package/bundled/skills/prizmkit-code-review/references/independent-code-review.md +7 -4
  122. package/bundled/skills/prizmkit-code-review/references/review-report-template.md +16 -0
  123. package/bundled/skills/prizmkit-code-review/scripts/render_review_report.py +58 -20
  124. package/bundled/skills/prizmkit-implement/SKILL.md +1 -1
  125. package/bundled/skills/prizmkit-init/SKILL.md +25 -128
  126. package/bundled/skills/prizmkit-init/assets/project-brief-template.md +3 -3
  127. package/bundled/skills/prizmkit-init/references/config-schema.md +2 -2
  128. package/bundled/skills/prizmkit-plan/SKILL.md +6 -8
  129. package/bundled/skills/prizmkit-plan/references/clarify-guide.md +1 -1
  130. package/bundled/skills/prizmkit-plan/references/independent-plan-review.md +5 -2
  131. package/bundled/skills/prizmkit-plan/references/review-plan-spec-loop.md +6 -5
  132. package/bundled/skills/prizmkit-prizm-docs/SKILL.md +1 -13
  133. package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md +1 -1
  134. package/bundled/skills/prizmkit-prizm-docs/references/op-init.md +1 -1
  135. package/bundled/skills/prizmkit-prizm-docs/references/op-update.md +1 -1
  136. package/bundled/skills/prizmkit-retrospective/SKILL.md +6 -4
  137. package/bundled/skills/prizmkit-test/SKILL.md +25 -133
  138. package/bundled/skills/prizmkit-test/references/independent-test-review.md +5 -2
  139. package/bundled/skills/prizmkit-test/references/test-coverage-model.md +6 -0
  140. package/bundled/skills/prizmkit-workflow/SKILL.md +2 -3
  141. package/bundled/skills/prizmkit-workflow/references/workflow-state-protocol.md +4 -3
  142. package/bundled/skills/recovery-workflow/SKILL.md +7 -7
  143. package/bundled/skills/recovery-workflow/evals/evals.json +1 -1
  144. package/bundled/skills/recovery-workflow/references/detection.md +1 -3
  145. package/bundled/skills/recovery-workflow/scripts/detect-recovery-state.py +0 -6
  146. package/bundled/templates/project-memory-template.md +1 -2
  147. package/package.json +1 -1
  148. package/src/ai-cli-launch.js +1 -1
  149. package/src/clean.js +40 -4
  150. package/src/config.js +64 -4
  151. package/src/detect-platform.js +10 -6
  152. package/src/external-skills.js +2 -2
  153. package/src/index.js +1 -0
  154. package/src/manifest.js +1 -1
  155. package/src/platforms.js +6 -2
  156. package/src/prompts.js +11 -3
  157. package/src/scaffold.js +87 -11
  158. package/src/upgrade.js +9 -3
  159. package/bundled/dev-pipeline/SCHEMA_ANALYSIS.md +0 -53
  160. package/bundled/dev-pipeline/scripts/generate-refactor-prompt.py +0 -649
  161. package/bundled/dev-pipeline/scripts/init-refactor-pipeline.py +0 -463
  162. package/bundled/dev-pipeline/scripts/update-refactor-status.py +0 -1512
  163. package/bundled/dev-pipeline/templates/refactor-bootstrap-prompt.md +0 -240
  164. package/bundled/dev-pipeline/templates/refactor-list-schema.json +0 -266
  165. package/bundled/dev-pipeline/templates/sections/refactor-critical-paths.md +0 -15
  166. package/bundled/dev-pipeline/templates/sections/refactor-mission.md +0 -9
  167. package/bundled/dev-pipeline/templates/sections/refactor-phase-commit-report.md +0 -24
  168. package/bundled/dev-pipeline/templates/sections/refactor-phase-implement.md +0 -16
  169. package/bundled/dev-pipeline/templates/sections/refactor-phase-init.md +0 -9
  170. package/bundled/dev-pipeline/templates/sections/refactor-phase-plan.md +0 -22
  171. package/bundled/dev-pipeline/templates/sections/refactor-phase-review.md +0 -19
  172. package/bundled/dev-pipeline/templates/sections/refactor-phase-test.md +0 -24
  173. package/bundled/dev-pipeline/templates/sections/refactor-reminders.md +0 -12
  174. package/bundled/dev-pipeline/templates/sections/refactor-session-context.md +0 -6
  175. package/bundled/dev-pipeline/templates/sections/refactor-task-contract.md +0 -52
  176. package/bundled/dev-pipeline/tests/test_generate_refactor_prompt.py +0 -478
  177. package/bundled/skills/feature-planner/assets/evaluation-guide.md +0 -44
  178. package/bundled/skills/refactor-pipeline-launcher/SKILL.md +0 -219
  179. package/bundled/skills/refactor-pipeline-launcher/references/configuration.md +0 -78
  180. package/bundled/skills/refactor-planner/SKILL.md +0 -467
  181. package/bundled/skills/refactor-planner/assets/planning-guide.md +0 -291
  182. package/bundled/skills/refactor-planner/references/behavior-preservation.md +0 -187
  183. package/bundled/skills/refactor-planner/references/error-recovery.md +0 -45
  184. package/bundled/skills/refactor-planner/references/fast-path.md +0 -59
  185. package/bundled/skills/refactor-planner/references/generated-plan-review.md +0 -107
  186. package/bundled/skills/refactor-planner/references/planning-phases.md +0 -172
  187. package/bundled/skills/refactor-planner/references/refactor-scoping-guide.md +0 -230
  188. package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +0 -1120
  189. package/bundled/skills/refactor-workflow/SKILL.md +0 -205
@@ -1,291 +0,0 @@
1
- # Refactor Planning Reference Guide
2
-
3
- This guide provides structured patterns, decision matrices, and templates for decomposing refactoring goals into well-scoped, executable items. It is intended as a practical reference for the AI during interactive refactor planning sessions.
4
-
5
- ---
6
-
7
- ## 1. Identifying Refactoring Boundaries
8
-
9
- Refactoring boundaries define where one refactor item ends and another begins. Group by **contract-bounded capability**: shared domain objects, state machine, invariants, public API, and error semantics. That grouping is not the same module, directory, or written task contract. Independently shippable is not a split reason.
10
-
11
- ### Boundary Heuristics
12
-
13
- These signals help assess coupling, risk, and verification depth. They do not by themselves create extra top-level items.
14
-
15
- | Signal | What it tells you | Do not treat as |
16
- |--------|-------------------|-----------------|
17
- | Different files/modules | Blast radius and complexity **label** | Automatic extra list items |
18
- | Different refactoring operations | Work mix inside one capability | A required split |
19
- | Different risk levels | Test and review depth | A required split of one capability |
20
- | Different test suites affected | Verification surface | A required split |
21
- | Sequential dependency | Ordering inside or across capabilities | A split of one shared capability |
22
-
23
- ### Rules for Setting Boundaries
24
-
25
- 1. **Prefer contract-bounded grouping.** Independently shippable is not a split reason. Directory and module names are clues only. A rename and a structural extraction stay one item when they share one contract-bounded capability and must land in one existing headless session.
26
- 2. **Each remaining top-level item should be independently testable.** After completing item R-001, all tests should pass before starting R-002.
27
- 3. **File count is a complexity label, not a split reason.** There is no word-count upper limit and no acceptance-criteria count upper limit.
28
- 4. **Split into additional top-level items only when implementation plus verification cannot finish in one existing headless session**, typically after two or more heavy capability seams, or when behavior preservation truly requires different strategies that cannot share one contract.
29
-
30
- ---
31
-
32
- ## 2. Description Writing Guide
33
-
34
- Refactor item descriptions are the primary input for autonomous pipeline sessions. A thin description forces the AI to guess about scope and safety constraints.
35
-
36
- ### Minimum Word Counts
37
-
38
- | Complexity | Minimum Words | Warning Threshold |
39
- |------------|---------------|-------------------|
40
- | low | 15 | 30 |
41
- | medium | 15 | 50 |
42
- | high | 15 | 80 |
43
-
44
- Below 15 words is a validation error. Below the threshold triggers a warning. There is no word-count upper limit and no acceptance-criteria count upper limit. AI rewrite is allowed; dropping a confirmed item is not.
45
-
46
- ### What to Include
47
-
48
- Every refactor description should cover:
49
-
50
- 1. **What to change** — specific files, functions, classes, or patterns being refactored
51
- 2. **How to change it** — the refactoring operation (extract, rename, move, inline, simplify)
52
- 3. **Why** — the motivation (reduce complexity, improve testability, remove duplication)
53
- 4. **Constraints** — what must NOT change (public API, behavior contracts, external interfaces)
54
- 5. **Verification** — how to confirm the refactoring succeeded without breaking behavior
55
-
56
- ### Good vs Bad Examples
57
-
58
- **Bad** (12 words — too thin):
59
- ```
60
- "Extract the validation logic from the handler into a separate module."
61
- ```
62
-
63
- **Good** (55 words — implementation-ready):
64
- ```
65
- "Extract all input validation functions from src/api/handler.js (validateEmail, validatePassword, validateUsername) into a new src/utils/validators.js module. Update all imports in handler.js and any other files that import these functions directly. Preserve the exact function signatures and return types. The handler.js file should import from the new location. All existing tests must continue to pass without modification."
66
- ```
67
-
68
- **Bad** (14 words):
69
- ```
70
- "Convert the user service from callbacks to async/await pattern throughout."
71
- ```
72
-
73
- **Good** (72 words — implementation-ready):
74
- ```
75
- "Convert src/services/user-service.js from callback-based functions to async/await. Target functions: createUser, findUserById, updateUser, deleteUser (4 functions total). Each function currently accepts a callback as the last parameter and calls it with (err, result). Convert to return Promises and use async/await internally. Update all callers in src/routes/user-routes.js to use await instead of passing callbacks. Preserve all error handling behavior — errors that were passed to callbacks should now be thrown."
76
- ```
77
-
78
- ---
79
-
80
- ## 3. Common Refactoring Patterns
81
-
82
- Use these patterns as starting points when decomposing refactoring goals.
83
-
84
- ### Pattern A: Extract Method/Function
85
-
86
- **When**: A function is too long, has multiple responsibilities, or contains duplicated logic.
87
-
88
- ```
89
- R-001: Extract [specific logic] from [source function] into [new function name]
90
- Type: extract
91
- Scope: [source file]
92
- Complexity: low
93
- Preservation: test-gate
94
- ```
95
-
96
- ### Pattern B: Extract Class/Module
97
-
98
- **When**: A file/class is too large, a group of functions share a common concern, or a module has multiple responsibilities.
99
-
100
- ```
101
- R-001: Create new module [name] with extracted [concern] logic
102
- Type: extract
103
- Scope: [source file, new file]
104
- Complexity: medium
105
- Preservation: test-gate
106
-
107
- R-002: Update imports to use new [name] module (deps: R-001)
108
- Type: restructure
109
- Scope: [all importing files]
110
- Complexity: low
111
- Preservation: test-gate
112
- ```
113
-
114
- ### Pattern C: Move Module/File
115
-
116
- **When**: A file is in the wrong directory, module organization needs restructuring.
117
-
118
- ```
119
- R-001: Move [file] from [old path] to [new path]
120
- Type: restructure
121
- Scope: [file, all importers]
122
- Complexity: low-medium (depends on import count)
123
- Preservation: test-gate
124
- ```
125
-
126
- ### Pattern D: Inline (Reverse of Extract)
127
-
128
- **When**: An abstraction is unnecessary, a wrapper adds no value, or indirection hurts readability.
129
-
130
- ```
131
- R-001: Inline [function/module] into [target]
132
- Type: simplify
133
- Scope: [source file, target file]
134
- Complexity: low
135
- Preservation: test-gate
136
- ```
137
-
138
- ### Pattern E: Rename (Variable, Function, Class, File)
139
-
140
- **When**: Names are misleading, inconsistent, or don't follow conventions.
141
-
142
- ```
143
- R-001: Rename [old name] to [new name] across codebase
144
- Type: rename
145
- Scope: [all files containing the name]
146
- Complexity: low
147
- Preservation: test-gate
148
- ```
149
-
150
- ### Pattern F: Decouple Dependencies
151
-
152
- **When**: Circular dependencies, tight coupling between modules, or difficulty testing in isolation.
153
-
154
- ```
155
- R-001: Define interface/contract for [dependency] (deps: none)
156
- Type: decouple
157
- Scope: [new interface file]
158
- Complexity: medium
159
- Preservation: test-gate
160
-
161
- R-002: Implement [dependency] behind new interface (deps: R-001)
162
- Type: decouple
163
- Scope: [implementation file]
164
- Complexity: medium
165
- Preservation: test-gate
166
-
167
- R-003: Update consumers to use interface instead of concrete (deps: R-002)
168
- Type: decouple
169
- Scope: [all consumer files]
170
- Complexity: medium
171
- Preservation: test-gate
172
- ```
173
-
174
- ### Pattern G: Architecture Migration
175
-
176
- **When**: Converting between paradigms (callbacks to promises, classes to functions, monolith to modules).
177
-
178
- ```
179
- R-001: Add new [pattern] alongside old [pattern] (deps: none)
180
- Type: migrate
181
- Scope: [target files]
182
- Complexity: medium-high
183
- Preservation: test-gate or snapshot
184
-
185
- R-002: Migrate [specific area] to new pattern (deps: R-001)
186
- Type: migrate
187
- Scope: [area files]
188
- Complexity: medium
189
- Preservation: test-gate
190
-
191
- R-003: Remove old [pattern] code (deps: R-002)
192
- Type: simplify
193
- Scope: [cleaned files]
194
- Complexity: low
195
- Preservation: test-gate
196
- ```
197
-
198
- ---
199
-
200
- ## 4. Dependency Ordering Rules
201
-
202
- Correct ordering minimizes risk and ensures each step is independently verifiable.
203
-
204
- ### Ordering Priority (execute in this order)
205
-
206
- 1. **Safe renames** — Lowest risk. Pure name changes with no structural impact. Can be reverted trivially.
207
- 2. **Extract/inline** — Moderate risk. Changes module boundaries but doesn't reorganize architecture.
208
- 3. **Structural changes** — Higher risk. Reorganizes file layout, module hierarchy, or dependency graph.
209
- 4. **Migrations** — Highest risk. Changes programming patterns or paradigms.
210
-
211
- ### Dependency Rules
212
-
213
- 1. **No circular dependencies.** Dependencies MUST form a directed acyclic graph (DAG).
214
- 2. **Minimal dependency sets.** Each item should depend only on items it directly needs.
215
- 3. **Rename before restructure.** If you're renaming something AND moving it, rename first (easier to track).
216
- 4. **Create before consume.** If item A creates a new module and item B uses it, B depends on A.
217
- 5. **Interface before implementation.** If decoupling, define the interface before implementing behind it.
218
- 6. **Preserve before remove.** If migrating, ensure new code works before removing old code.
219
-
220
- ### Validation Checklist
221
-
222
- - [ ] No item depends on itself
223
- - [ ] No circular dependency chains exist
224
- - [ ] Every item ID referenced in a dependency list is defined in the plan
225
- - [ ] The graph can be topologically sorted
226
- - [ ] Renames appear before structural changes that reference the renamed entities
227
-
228
- ---
229
-
230
- ## 5. Acceptance Criteria for Refactoring
231
-
232
- Refactoring acceptance criteria focus on structural improvement AND behavior preservation. They differ from feature acceptance criteria.
233
-
234
- ### Standard Criteria Templates
235
-
236
- **For extract operations:**
237
- - [ ] New module/function exists at [target path]
238
- - [ ] Original location imports from new location (no duplication)
239
- - [ ] All existing tests pass without modification
240
- - [ ] No new circular dependencies introduced
241
-
242
- **For rename operations:**
243
- - [ ] Old name does not appear anywhere in codebase (except git history)
244
- - [ ] All references updated to new name
245
- - [ ] All existing tests pass without modification
246
-
247
- **For restructure operations:**
248
- - [ ] Files are in their new locations
249
- - [ ] All import paths updated
250
- - [ ] Module boundary is clean (no reaching into internal paths)
251
- - [ ] All existing tests pass without modification
252
-
253
- **For decouple operations:**
254
- - [ ] Interface/contract defined and documented
255
- - [ ] Implementation satisfies interface
256
- - [ ] Consumers depend on interface, not implementation
257
- - [ ] No circular dependencies remain
258
- - [ ] All existing tests pass without modification
259
-
260
- **For migrate operations:**
261
- - [ ] New pattern is used in target area
262
- - [ ] Old pattern code is removed (no dead code)
263
- - [ ] All existing tests pass (may need test updates to use new pattern)
264
- - [ ] Behavior is identical (verified via test-gate or snapshot)
265
-
266
- ### Writing Principles
267
-
268
- 1. **Always include "all existing tests pass"** — this is the fundamental refactoring invariant.
269
- 2. **Be specific about structural outcomes** — "files are organized by feature" is vague; "auth files are in src/features/auth/" is concrete.
270
- 3. **Include negative criteria** — "no circular dependencies", "no dead code", "no duplicated logic".
271
- 4. **Keep every confirmed criterion.** There is no acceptance-criteria count upper limit. Do not drop confirmed preservation evidence to stay under a count.
272
-
273
- ---
274
-
275
- ## 6. Complexity Estimation for Refactoring
276
-
277
- | Factor | Low | Medium | High |
278
- |--------|-----|--------|------|
279
- | File count | 1-2 files | 3-5 files | 6+ files |
280
- | Cross-module scope | Same module | 2 modules | 3+ modules |
281
- | Test coverage | High (>80%) | Moderate (40-80%) | Low (<40%) |
282
- | Pattern familiarity | Well-known (rename, extract) | Common (restructure) | Novel (custom migration) |
283
- | Dependency changes | None | Minor (1-2 imports) | Significant (module graph changes) |
284
-
285
- **Rule**: Take the highest individual factor as the overall complexity. When in doubt, estimate higher.
286
-
287
- ### Complexity Labeling Notes
288
-
289
- File count, module count, and acceptance-criteria count may raise the complexity **label**. They are not automatic split reasons. Independently shippable is not a split reason. Group by contract-bounded capability.
290
-
291
- Split into additional top-level items only when implementation plus verification cannot finish in one existing headless session, or when a necessary atomic migration would be broken by a split.
@@ -1,187 +0,0 @@
1
- # Behavior Preservation Planning Guide
2
-
3
- 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.
4
-
5
- ## Table of Contents
6
-
7
- 1. [Planning Boundary](#planning-boundary)
8
- 2. [Preservation Strategies](#preservation-strategies)
9
- 3. [Strategy Selection](#strategy-selection)
10
- 4. [Behavior-Risk Checklist](#behavior-risk-checklist)
11
- 5. [Coverage Assessment](#coverage-assessment)
12
- 6. [Plan-Readiness Checklist](#plan-readiness-checklist)
13
-
14
- ## Planning Boundary
15
-
16
- For every refactor item, the planner must:
17
-
18
- - choose a primary strategy: `test-gate`, `snapshot`, or `manual`;
19
- - identify the observable behavior that must remain stable;
20
- - identify existing evidence sources when they are discoverable by reading the repository;
21
- - record missing evidence and any prerequisite item needed to close the gap;
22
- - write measurable acceptance criteria that a non-interactive downstream session can evaluate;
23
- - avoid claiming that tests, snapshots, or manual verification have already run.
24
-
25
- ## Preservation Strategies
26
-
27
- ### Strategy: `test-gate`
28
-
29
- Use when the target has reliable automated tests that cover the behavior being preserved.
30
-
31
- Planning requirements:
32
-
33
- - name the relevant test files, suites, or project-native test command when discoverable;
34
- - identify the behavior contracts represented by those tests;
35
- - require evidence that previously passing relevant tests remain passing after the structural change;
36
- - note known flaky tests or coverage gaps;
37
- - add a prerequisite planning item when missing tests make the refactor unsafe.
38
-
39
- ```json
40
- {
41
- "behavior_preservation": {
42
- "strategy": "test-gate",
43
- "existing_tests": true,
44
- "new_tests_needed": []
45
- }
46
- }
47
- ```
48
-
49
- ### Strategy: `snapshot`
50
-
51
- Use when formal coverage is insufficient but deterministic observable behavior can be compared.
52
-
53
- Planning requirements:
54
-
55
- - define representative inputs;
56
- - define the observable outputs or state to compare;
57
- - define allowed normalization or acceptable differences;
58
- - require before/after evidence from the same inputs;
59
- - identify non-deterministic fields that must be excluded or normalized.
60
-
61
- ```json
62
- {
63
- "behavior_preservation": {
64
- "strategy": "snapshot",
65
- "existing_tests": false,
66
- "new_tests_needed": []
67
- },
68
- "acceptance_criteria": [
69
- "Responses for the documented API cases match the approved baseline after normalization",
70
- "CLI help output preserves all documented flags and exit codes"
71
- ]
72
- }
73
- ```
74
-
75
- ### Strategy: `manual`
76
-
77
- Use only when neither reliable tests nor deterministic observable output can prove preservation.
78
-
79
- Planning requirements:
80
-
81
- - state exactly which behavior requires human judgment;
82
- - define a reproducible verification checklist;
83
- - identify required screenshots, recordings, or written baselines;
84
- - mark the item as high verification risk;
85
- - avoid subjective criteria such as “looks correct” without named observations.
86
-
87
- ```json
88
- {
89
- "behavior_preservation": {
90
- "strategy": "manual",
91
- "existing_tests": false,
92
- "new_tests_needed": []
93
- },
94
- "acceptance_criteria": [
95
- "The verification checklist covers email login, social login, and password reset without changing their documented outcomes"
96
- ]
97
- }
98
- ```
99
-
100
- ## Strategy Selection
101
-
102
- Choose the smallest strategy that can credibly prove behavior preservation:
103
-
104
- 1. Reliable relevant tests exist and cover the contract: choose `test-gate`.
105
- 2. Tests are incomplete but behavior is deterministic and observable: choose `snapshot`.
106
- 3. Tests are flaky: plan stabilization as a prerequisite, or use `snapshot` when stabilization is explicitly out of scope.
107
- 4. Neither automated evidence source is viable: choose `manual` and document the risk.
108
-
109
- | Existing Evidence | Observable Output | Primary Strategy | Planning Risk |
110
- |---|---|---|---|
111
- | Reliable tests | Any | `test-gate` | Low |
112
- | Partial tests | Deterministic | `snapshot` or `test-gate` with documented gaps | Medium |
113
- | No reliable tests | Deterministic | `snapshot` | High |
114
- | No reliable tests | Non-deterministic or subjective | `manual` | Very high |
115
-
116
- 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.
117
-
118
- ## Behavior-Risk Checklist
119
-
120
- Inspect the target and capture relevant risks in the item description or acceptance criteria.
121
-
122
- ### Side-effect ordering
123
-
124
- Record initialization, mutation, and external-call ordering that must not change.
125
-
126
- ### Error propagation
127
-
128
- Record which errors reach which handlers, including error types, messages, codes, and retry behavior.
129
-
130
- ### Closure and binding semantics
131
-
132
- Record captured variables, `this` binding, lifetime, and scope assumptions affected by extraction or movement.
133
-
134
- ### Import-time behavior
135
-
136
- Record side-effect imports, polyfills, registration order, and module initialization dependencies.
137
-
138
- ### Defaults and type coercion
139
-
140
- Record existing default-value and coercion behavior, especially where falsy values differ from missing values.
141
-
142
- ### Async timing and concurrency
143
-
144
- Record ordering, atomicity, cancellation, race, and shared-state constraints.
145
-
146
- ### Public interfaces
147
-
148
- Record exports, signatures, import paths, configuration keys, CLI flags, response shapes, and compatibility commitments.
149
-
150
- ### Operational observability
151
-
152
- Record log patterns, metrics, alerts, performance limits, and other externally observed behavior that consumers rely on.
153
-
154
- ## Coverage Assessment
155
-
156
- Assess coverage by reading existing repository evidence only:
157
-
158
- - test runner configuration;
159
- - relevant test files and their imports;
160
- - assertions that describe behavior contracts;
161
- - existing coverage reports when already present;
162
- - project documentation and CI configuration.
163
-
164
- 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.
165
-
166
- Planning decisions:
167
-
168
- - Strong relevant coverage: use `test-gate` and name the evidence source.
169
- - Partial coverage: list uncovered paths and consider a prerequisite test item.
170
- - No relevant coverage: prefer a prerequisite test item or a snapshot strategy.
171
- - No viable automated evidence: use `manual`, document the verification protocol, and flag the risk.
172
-
173
- 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.
174
-
175
- ## Plan-Readiness Checklist
176
-
177
- Before finalizing each refactor item, verify the plan states:
178
-
179
- - [ ] the primary preservation strategy;
180
- - [ ] the behavior contracts that must remain stable;
181
- - [ ] the existing evidence sources, or an explicit `unknown`/missing-evidence statement;
182
- - [ ] prerequisite evidence work when necessary;
183
- - [ ] measurable post-change acceptance criteria;
184
- - [ ] public interface and compatibility constraints;
185
- - [ ] error, logging, configuration, and performance constraints when relevant;
186
- - [ ] supplemental browser or manual evidence when automated evidence is insufficient;
187
- - [ ] no claim that implementation or verification has already occurred.
@@ -1,45 +0,0 @@
1
- # Refactor Planner Error Recovery
2
-
3
- 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.
4
-
5
- ## Validation Recovery
6
-
7
- - Warnings only: present them and continue when informational. Ask the user only when a warning exposes a consequential architecture, scope, behavior-preservation, or verification decision; do not add a generic draft-promotion approval.
8
- - Validation errors: group related errors, apply unambiguous mechanical corrections to the planning draft, and rerun the matching writer. Ask before semantic corrections, and limit automatic correction to three attempts before retaining the draft and asking the user how to proceed.
9
- - Keep `.prizmkit/plans/refactor-list.json` at the project-root `.prizmkit/plans/` path.
10
- - Do not alter source code or run project tests while recovering a planning artifact.
11
-
12
- ## Resume Detection
13
-
14
- | Artifact Found | Resume Point |
15
- |---|---|
16
- | No planning artifact | Phase 1: Project Context |
17
- | Draft only in `.prizmkit/plans/` | Phase matching the draft's actual completeness |
18
- | Incomplete final refactor list | Resume writer/validation repair through the source draft |
19
- | Valid final refactor list only | Mode D: Summary or a new bounded append |
20
- | Valid final plus draft | Treat as interrupted review or cleanup-failure state; inspect and offer resume review, discard, or a new append rather than assuming either artifact wins |
21
-
22
- Read the artifacts directly because `.prizmkit` content may be gitignored. Preserve existing valid entries and resume only unfinished planning work. When final and draft both exist and available evidence cannot distinguish interrupted review from cleanup failure, ask the user before deleting or promoting the draft.
23
-
24
- ## Session Exit Gate
25
-
26
- Activate the exit gate when all of these are true:
27
-
28
- - the user explicitly invoked `refactor-planner`;
29
- - validation has not passed;
30
- - no valid final refactor list was produced in this session.
31
-
32
- Use `AskUserQuestion` with these options:
33
-
34
- - **Continue to completion (Recommended)** — resume from the detected planning phase.
35
- - **Save draft and exit** — save current planning content as `.prizmkit/plans/refactor-list.draft.json` and retain it as explicit recovery state.
36
- - **Abandon** — exit without saving new planning content.
37
-
38
- When saving a draft, state clearly that it is not validated and can be resumed by running `refactor-planner` again. Terminal cleanup does not apply until resumed planning completes.
39
-
40
- ## Draft Management
41
-
42
- - Keep an ordinary writer draft through generation/append, validation, and the complete Local Generated-Plan Review fix loop.
43
- - After Local Generated-Plan Review returns `PASS` and final validation passes, delete the ordinary internal draft before handoff.
44
- - Retain a draft only for explicit **Save draft and exit**, interruption or blocking before terminal gates, or cleanup failure. Report its path and reason.
45
- - Cleanup failure does not invalidate a reviewed and validated final list, but the retained file is stale recovery state and must be surfaced.
@@ -1,59 +0,0 @@
1
- # Fast Path — Refactor Planner
2
-
3
- For simple refactoring with minimal scope.
4
-
5
- ## Eligibility Criteria (ALL must apply)
6
- - 1-2 refactor items only
7
- - Complexity: `low` or `medium` for all items
8
- - The confirmed scope is one contract-bounded capability, or a user-explicit tiny slice of one; module and directory names do not decide eligibility
9
- - Well-known refactoring pattern (rename, extract method/class, inline)
10
- - Existing test coverage for target area
11
-
12
- ## Fast Path Workflow
13
- 1. If `.prizmkit/plans/refactor-list.json` exists, run the parent Skill's bounded `context` command and consume only root context plus the five recent `{id, description}` pairs; never read the complete historical list or perform default keyword search. Then confirm refactoring scope with the user.
14
- 2. **User confirmation (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
15
-
16
- ```
17
- AskUserQuestion:
18
- question: "This qualifies for fast-path (simple refactoring). How would you like to proceed?"
19
- header: "Approach"
20
- options:
21
- - label: "Fast-path"
22
- description: "Skip detailed analysis, draft refactor items directly and add to refactor-list.json"
23
- - label: "Full workflow"
24
- description: "Use the complete planning workflow with detailed code analysis"
25
- ```
26
-
27
- - **Fast-path** → Continue with fast-path workflow below
28
- - **Full workflow** → Exit fast path, use full workflow from Phase 2
29
- - If the user wants direct implementation instead of planning, exit the planner flow after explicit confirmation and recommend `/prizmkit-plan`; do not invoke implementation from inside `refactor-planner`.
30
-
31
- **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
32
- 3. Draft items (title + type + scope + description + acceptance_criteria + behavior_preservation + dependencies)
33
- 4. Run the mandatory Phase 6 Headless Context Completeness Gate on every drafted item; repair the draft until each returns `PASS` without conversation history or `user_context`.
34
- 5. Write `.prizmkit/plans/refactor-list.draft.json` as the private review workspace. For a new list, write the complete final-list draft; for an existing list, write only the additions-only `refactors` object and check merge feasibility without writing, with no second draft-approval pause:
35
- ```bash
36
- python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json --dry-run
37
- ```
38
- 6. If valid -> run the mandatory Local Generated-Plan Review Gate from the main `refactor-planner` skill against the draft. After review returns `PASS`, insert once (`append`, or `generate` for a new list), delete the draft under the main Skill's Draft Lifecycle, then present the final written result before recommending `refactor-pipeline-launcher`.
39
- 7. For a later adjustment after cleanup, recreate only the minimum source draft from confirmed in-memory entries or exact-ID `show`, then rerun `generate` for a new-list rewrite or `append --replace-tail` for an ordinary append.
40
- 8. If invalid -> apply fixes to the draft and re-run the dry run; a new list is validated by its post-`PASS` `generate`, which writes nothing when it rejects (max 2 attempts, then escalate to full workflow)
41
-
42
- ## When NOT to Use Fast Path
43
- - More than 2 refactor items
44
- - Any item with `high` complexity
45
- - Work that spans two contract-bounded capabilities or a confirmed architecture migration (Format C goals)
46
- - No existing test coverage for target area
47
-
48
- ## Example Fast Path Session
49
- ```
50
- User: "Rename the auth middleware function from checkAuth to requireAuth everywhere."
51
- AI: [Detects simple rename, one contract-bounded capability]
52
- AI: [Qualifies for fast path: 1 item, low complexity, one capability]
53
- AI: [Uses AskUserQuestion with options: "Fast-path", "Full workflow"]
54
- User: [Selects "Fast-path"]
55
- AI: "Drafting R-001..."
56
- AI: [Validates immediately]
57
- AI: [Runs the Local Generated-Plan Review Gate on R-001 only]
58
- AI: "Ready to proceed to dev-pipeline."
59
- ```