prizmkit 1.1.191 → 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 (169) hide show
  1. package/bundled/VERSION.json +3 -3
  2. package/bundled/adapters/antigravity/skill-adapter.js +13 -4
  3. package/bundled/adapters/codex/skill-adapter.js +28 -8
  4. package/bundled/adapters/cursor/skill-adapter.js +13 -4
  5. package/bundled/adapters/pi/skill-adapter.js +28 -7
  6. package/bundled/dev-pipeline/.env.example +4 -12
  7. package/bundled/dev-pipeline/README.md +5 -10
  8. package/bundled/dev-pipeline/assets/skill-subagent-integration.md +3 -6
  9. package/bundled/dev-pipeline/prizmkit_runtime/atomic_io.py +48 -0
  10. package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py +66 -23
  11. package/bundled/dev-pipeline/prizmkit_runtime/cli.py +10 -7
  12. package/bundled/dev-pipeline/prizmkit_runtime/commands.py +2 -21
  13. package/bundled/dev-pipeline/prizmkit_runtime/config.py +24 -76
  14. package/bundled/dev-pipeline/prizmkit_runtime/daemon.py +125 -67
  15. package/bundled/dev-pipeline/prizmkit_runtime/gitops.py +77 -430
  16. package/bundled/dev-pipeline/prizmkit_runtime/heartbeat.py +93 -49
  17. package/bundled/dev-pipeline/prizmkit_runtime/interoperability.py +1 -3
  18. package/bundled/dev-pipeline/prizmkit_runtime/paths.py +0 -6
  19. package/bundled/dev-pipeline/prizmkit_runtime/platform_detection.py +36 -14
  20. package/bundled/dev-pipeline/prizmkit_runtime/processes.py +206 -151
  21. package/bundled/dev-pipeline/prizmkit_runtime/reset.py +2 -23
  22. package/bundled/dev-pipeline/prizmkit_runtime/reset_preserve.py +15 -134
  23. package/bundled/dev-pipeline/prizmkit_runtime/results.py +25 -0
  24. package/bundled/dev-pipeline/prizmkit_runtime/runner_bookkeeping.py +68 -83
  25. package/bundled/dev-pipeline/prizmkit_runtime/runner_classification.py +15 -5
  26. package/bundled/dev-pipeline/prizmkit_runtime/runner_models.py +1 -29
  27. package/bundled/dev-pipeline/prizmkit_runtime/runner_prompts.py +0 -2
  28. package/bundled/dev-pipeline/prizmkit_runtime/runner_status.py +7 -2
  29. package/bundled/dev-pipeline/prizmkit_runtime/runners.py +276 -217
  30. package/bundled/dev-pipeline/prizmkit_runtime/runtime_commit.py +124 -122
  31. package/bundled/dev-pipeline/prizmkit_runtime/runtime_helper.py +90 -9
  32. package/bundled/dev-pipeline/prizmkit_runtime/sessions.py +183 -130
  33. package/bundled/dev-pipeline/prizmkit_runtime/status.py +1 -3
  34. package/bundled/dev-pipeline/prizmkit_runtime/stream_progress.py +2780 -0
  35. package/bundled/dev-pipeline/prizmkit_runtime/task_checkout.py +27 -101
  36. package/bundled/dev-pipeline/prizmkit_runtime/test_result.py +58 -4
  37. package/bundled/dev-pipeline/scripts/check-session-status.py +43 -19
  38. package/bundled/dev-pipeline/scripts/continuation.py +6 -4
  39. package/bundled/dev-pipeline/scripts/detect-stuck.py +28 -28
  40. package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +7 -2
  41. package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py +7 -2
  42. package/bundled/dev-pipeline/scripts/init-bugfix-pipeline.py +10 -7
  43. package/bundled/dev-pipeline/scripts/init-change-artifact.py +8 -2
  44. package/bundled/dev-pipeline/scripts/init-pipeline.py +14 -69
  45. package/bundled/dev-pipeline/scripts/parse-stream-progress.py +31 -2616
  46. package/bundled/dev-pipeline/scripts/patch-completion-notes.py +4 -24
  47. package/bundled/dev-pipeline/scripts/prompt_framework.py +56 -9
  48. package/bundled/dev-pipeline/scripts/status_common.py +591 -0
  49. package/bundled/dev-pipeline/scripts/update-bug-status.py +85 -463
  50. package/bundled/dev-pipeline/scripts/update-checkpoint.py +227 -65
  51. package/bundled/dev-pipeline/scripts/update-feature-status.py +76 -509
  52. package/bundled/dev-pipeline/scripts/utils.py +5 -12
  53. package/bundled/dev-pipeline/templates/bootstrap-tier3.md +4 -4
  54. package/bundled/dev-pipeline/templates/bug-fix-list-schema.json +7 -0
  55. package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md +1 -1
  56. package/bundled/dev-pipeline/templates/sections/artifact-manifest.md +1 -1
  57. package/bundled/dev-pipeline/templates/sections/bugfix-phase-manual-verification.md +1 -1
  58. package/bundled/dev-pipeline/templates/sections/bugfix-phase-review.md +1 -1
  59. package/bundled/dev-pipeline/templates/sections/bugfix-phase-test.md +2 -1
  60. package/bundled/dev-pipeline/templates/sections/checkpoint-system.md +1 -1
  61. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-auto.md +1 -1
  62. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-opencli.md +2 -2
  63. package/bundled/dev-pipeline/templates/sections/phase-browser-verification.md +2 -2
  64. package/bundled/dev-pipeline/templates/sections/phase-prizmkit-test.md +2 -1
  65. package/bundled/dev-pipeline/templates/sections/phase-review-full.md +1 -1
  66. package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md +3 -6
  67. package/bundled/dev-pipeline/templates/session-status-schema.json +2 -5
  68. package/bundled/dev-pipeline/tests/_helpers.py +418 -0
  69. package/bundled/dev-pipeline/tests/conftest.py +45 -1
  70. package/bundled/dev-pipeline/tests/test_auto_skip.py +4 -69
  71. package/bundled/dev-pipeline/tests/test_checkpoint_state.py +126 -1
  72. package/bundled/dev-pipeline/tests/test_daemon_and_scripts.py +257 -0
  73. package/bundled/dev-pipeline/tests/test_e2e_pipeline_run.py +500 -0
  74. package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py +59 -117
  75. package/bundled/dev-pipeline/tests/test_generate_bugfix_prompt.py +12 -10
  76. package/bundled/dev-pipeline/tests/test_python_runner_parity.py +431 -3099
  77. package/bundled/dev-pipeline/tests/test_recovery_workflow.py +7 -8
  78. package/bundled/dev-pipeline/tests/test_repository_bootstrap.py +0 -1
  79. package/bundled/dev-pipeline/tests/test_reset_modes.py +15 -27
  80. package/bundled/dev-pipeline/tests/test_reset_preserve.py +54 -139
  81. package/bundled/dev-pipeline/tests/test_runner_bookkeeping.py +766 -0
  82. package/bundled/dev-pipeline/tests/test_runner_lifecycle.py +1257 -0
  83. package/bundled/dev-pipeline/tests/test_runtime_helper.py +97 -20
  84. package/bundled/dev-pipeline/tests/test_session_launch.py +1101 -0
  85. package/bundled/dev-pipeline/tests/test_stream_progress.py +585 -0
  86. package/bundled/dev-pipeline/tests/test_unified_cli.py +155 -2034
  87. package/bundled/dev-pipeline/tests/test_utils.py +3 -3
  88. package/bundled/skills/_metadata.json +9 -63
  89. package/bundled/skills/app-planner/SKILL.md +32 -303
  90. package/bundled/skills/app-planner/references/app-design-guide.md +0 -4
  91. package/bundled/skills/app-planner/references/generated-plan-review.md +2 -1
  92. package/bundled/skills/app-planner/references/project-brief-guide.md +14 -0
  93. package/bundled/skills/app-planner/references/project-conventions-discovery.md +4 -6
  94. package/bundled/skills/app-planner/references/project-state-detection.md +2 -3
  95. package/bundled/skills/bug-fix-workflow/SKILL.md +1 -2
  96. package/bundled/skills/bug-fix-workflow/references/bug-diagnosis.md +4 -7
  97. package/bundled/skills/bug-planner/SKILL.md +54 -435
  98. package/bundled/skills/bug-planner/references/generated-plan-review.md +3 -2
  99. package/bundled/skills/bug-planner/references/input-formats.md +32 -0
  100. package/bundled/skills/bugfix-pipeline-launcher/SKILL.md +4 -6
  101. package/bundled/skills/bugfix-pipeline-launcher/references/configuration.md +4 -28
  102. package/bundled/skills/feature-pipeline-launcher/SKILL.md +4 -6
  103. package/bundled/skills/feature-pipeline-launcher/references/configuration.md +4 -28
  104. package/bundled/skills/feature-planner/SKILL.md +60 -439
  105. package/bundled/skills/feature-planner/assets/planning-guide.md +1 -1
  106. package/bundled/skills/feature-planner/references/completeness-review.md +34 -0
  107. package/bundled/skills/feature-planner/references/decomposition-patterns.md +2 -2
  108. package/bundled/skills/feature-planner/references/error-recovery.md +1 -1
  109. package/bundled/skills/feature-planner/references/generated-plan-review.md +3 -2
  110. package/bundled/skills/feature-planner/references/incremental-feature-planning.md +3 -1
  111. package/bundled/skills/feature-workflow/SKILL.md +1 -2
  112. package/bundled/skills/prizmkit/SKILL.md +7 -1
  113. package/bundled/skills/prizmkit-code-review/SKILL.md +14 -6
  114. package/bundled/skills/prizmkit-code-review/references/independent-code-review.md +7 -4
  115. package/bundled/skills/prizmkit-code-review/references/review-report-template.md +16 -0
  116. package/bundled/skills/prizmkit-code-review/scripts/render_review_report.py +58 -20
  117. package/bundled/skills/prizmkit-implement/SKILL.md +1 -1
  118. package/bundled/skills/prizmkit-init/SKILL.md +24 -127
  119. package/bundled/skills/prizmkit-init/assets/project-brief-template.md +3 -3
  120. package/bundled/skills/prizmkit-plan/SKILL.md +6 -8
  121. package/bundled/skills/prizmkit-plan/references/clarify-guide.md +1 -1
  122. package/bundled/skills/prizmkit-plan/references/independent-plan-review.md +5 -2
  123. package/bundled/skills/prizmkit-plan/references/review-plan-spec-loop.md +6 -5
  124. package/bundled/skills/prizmkit-prizm-docs/SKILL.md +1 -13
  125. package/bundled/skills/prizmkit-prizm-docs/references/op-update.md +1 -1
  126. package/bundled/skills/prizmkit-retrospective/SKILL.md +6 -4
  127. package/bundled/skills/prizmkit-test/SKILL.md +25 -133
  128. package/bundled/skills/prizmkit-test/references/independent-test-review.md +5 -2
  129. package/bundled/skills/prizmkit-test/references/test-coverage-model.md +6 -0
  130. package/bundled/skills/prizmkit-workflow/SKILL.md +2 -3
  131. package/bundled/skills/prizmkit-workflow/references/workflow-state-protocol.md +4 -3
  132. package/bundled/skills/recovery-workflow/SKILL.md +7 -7
  133. package/bundled/skills/recovery-workflow/evals/evals.json +1 -1
  134. package/bundled/skills/recovery-workflow/references/detection.md +1 -3
  135. package/bundled/skills/recovery-workflow/scripts/detect-recovery-state.py +0 -6
  136. package/bundled/templates/project-memory-template.md +1 -2
  137. package/package.json +1 -1
  138. package/src/scaffold.js +28 -7
  139. package/bundled/dev-pipeline/SCHEMA_ANALYSIS.md +0 -53
  140. package/bundled/dev-pipeline/scripts/generate-refactor-prompt.py +0 -649
  141. package/bundled/dev-pipeline/scripts/init-refactor-pipeline.py +0 -463
  142. package/bundled/dev-pipeline/scripts/update-refactor-status.py +0 -1512
  143. package/bundled/dev-pipeline/templates/refactor-bootstrap-prompt.md +0 -240
  144. package/bundled/dev-pipeline/templates/refactor-list-schema.json +0 -266
  145. package/bundled/dev-pipeline/templates/sections/refactor-critical-paths.md +0 -15
  146. package/bundled/dev-pipeline/templates/sections/refactor-mission.md +0 -9
  147. package/bundled/dev-pipeline/templates/sections/refactor-phase-commit-report.md +0 -24
  148. package/bundled/dev-pipeline/templates/sections/refactor-phase-implement.md +0 -16
  149. package/bundled/dev-pipeline/templates/sections/refactor-phase-init.md +0 -9
  150. package/bundled/dev-pipeline/templates/sections/refactor-phase-plan.md +0 -22
  151. package/bundled/dev-pipeline/templates/sections/refactor-phase-review.md +0 -19
  152. package/bundled/dev-pipeline/templates/sections/refactor-phase-test.md +0 -24
  153. package/bundled/dev-pipeline/templates/sections/refactor-reminders.md +0 -12
  154. package/bundled/dev-pipeline/templates/sections/refactor-session-context.md +0 -6
  155. package/bundled/dev-pipeline/templates/sections/refactor-task-contract.md +0 -52
  156. package/bundled/dev-pipeline/tests/test_generate_refactor_prompt.py +0 -478
  157. package/bundled/skills/feature-planner/assets/evaluation-guide.md +0 -44
  158. package/bundled/skills/refactor-pipeline-launcher/SKILL.md +0 -219
  159. package/bundled/skills/refactor-pipeline-launcher/references/configuration.md +0 -78
  160. package/bundled/skills/refactor-planner/SKILL.md +0 -467
  161. package/bundled/skills/refactor-planner/assets/planning-guide.md +0 -291
  162. package/bundled/skills/refactor-planner/references/behavior-preservation.md +0 -187
  163. package/bundled/skills/refactor-planner/references/error-recovery.md +0 -45
  164. package/bundled/skills/refactor-planner/references/fast-path.md +0 -59
  165. package/bundled/skills/refactor-planner/references/generated-plan-review.md +0 -107
  166. package/bundled/skills/refactor-planner/references/planning-phases.md +0 -172
  167. package/bundled/skills/refactor-planner/references/refactor-scoping-guide.md +0 -230
  168. package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +0 -1120
  169. package/bundled/skills/refactor-workflow/SKILL.md +0 -205
@@ -1,107 +0,0 @@
1
- # Generated Plan Review — Refactor Planner
2
-
3
- Use this local review loop on the batch that is about to be inserted into `.prizmkit/plans/refactor-list.json`. This is a planner-output review, not an implementation/code-diff review, and it runs before the insert so the verdict decides whether the batch lands.
4
-
5
- ## Trigger
6
-
7
- Run only when the current `refactor-planner` session produced a draft batch of new or changed refactors. For validate-only, summary-only, or draft-save flows with no new batch, report: `Local generated-plan review: not applicable — no new planning content written.`
8
-
9
- The draft is the whole review surface. Nothing is written to the final list while this loop runs: the single insert happens only after a `PASS`, so the verdict decides whether the batch lands and no final list ever holds reviewed-looking entries that were never reviewed.
10
-
11
- ## Direct Artifact Reads
12
-
13
- Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files through bounded, source-first access:
14
-
15
- - Review target: `.prizmkit/plans/refactor-list.draft.json` — the additions-only or complete batch, read in full; this is the only planning content under review
16
- - Final list: `.prizmkit/plans/refactor-list.json` — run the `context` command for root prose and recent IDs; do not load the complete historical list into AI context, and do not expect this session's batch to appear in it yet
17
- - Pre-session final list snapshot if captured in memory before edits — retain only bounded root context, prior task count/next ID, and the five recent `{id, description}` pairs, not full history
18
- - In-memory draft object if the session has not written a draft file yet
19
- - Already-committed entries a reviewed item relies on — load each referenced ID with `python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-NNN`
20
-
21
- Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whether planner output exists or changed. If the final list already contains this session's batch, the insert ran before the verdict — report that instead of reviewing an already-landed batch. Do not invoke `/prizmkit-code-review` for this planner-output gate; `/prizmkit-code-review` remains the implementation/code-diff review gate after `/prizmkit-implement`.
22
-
23
- ## Review Scope
24
-
25
- 1. Treat the draft batch as the change set. Its `R-*` IDs are the sequential `context` IDs the writer demands at insert time, so the IDs reviewed are the IDs that land; do not compare complete pre/post historical arrays in AI context.
26
- 2. Root project prose is reviewable content, not generator metadata. Read it through `context`; review new or changed `project_description` and `global_context` even when no refactor item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
27
- 3. Treat refactors as changed only when item fields changed; load and review newly added refactor IDs and explicitly changed refactor IDs through `show`.
28
- 4. Preserve unchanged historical refactors. Do not load unchanged entries merely to establish review completeness. Use the full-list validator for dependency/DAG truth; use `show` for an old dependency or behavior-preservation interaction only when a specific reviewed refactor requires semantic inspection.
29
- 5. If no snapshot exists during initial generation, review all entries in that session's complete draft. Absence of a snapshot never authorizes loading unrelated history during append flow.
30
-
31
- ## Review Checklist
32
-
33
- For every reviewed refactor entry, check:
34
-
35
- - Intent fidelity: confirmed structural outcome, behavior invariants, scope, non-goals, and constraints preserve user intent rather than an AI-selected architecture
36
- - Evidence status honesty: current-state facts, evidence-backed inferences, recommendations, assumptions, and unknowns remain distinct; proposed target architecture is not presented as confirmed until selected
37
- - Minimum-sufficient scope: every operation maps to a confirmed structural goal, behavior invariant, existing contract, or evidenced risk; unrelated cleanup and speculative redesign are absent
38
- - Schema compatibility with `dev-pipeline-refactor-list-v1` and `.prizmkit/dev-pipeline/templates/refactor-list-schema.json`
39
- - Dependency/DAG soundness, including safe behavior-preserving order
40
- - Description completeness: objective, current state, desired target architecture, selected decisions, scope boundaries, constraints, non-goals, relevant integrations and consumers, edge cases, behavior-preservation decisions, completion evidence, and headless execution readiness
41
- - Artifact-wide readability: every generated natural-language value across all AI-visible fields and sections—including `project_description`, `global_context`, scope explanations, rationales, behavior-preservation/evidence text, `user_context`, comments, and parentheticals—is a standalone domain statement without dialogue-role labels, question IDs, answer tokens, planning-option recommendation markers, or planning provenance
42
- - Acceptance criteria specificity and measurable behavior-preservation verification
43
- - `behavior_preservation` strategy quality and consistency with target scope and existing tests
44
- - User-provided detail preservation at matching detail after conversational normalization
45
- - `user_context` is supplementary evidence only: it does not expand, replace, or contradict the refactor contract; if `user_context` were removed, execution and verification remain unambiguous
46
- - Task-scoped `user_context` isolation: no unrelated sibling refactor goals, target files, constraints, desired end states, or supplementary materials; shared context appears on multiple items only when explicitly global
47
- - Purpose-tagged stable code, configuration, machine-consumed interface, and URL targets; transient non-code planning/evidence paths are replaced by inline task-relevant decisions and excerpts, and large materials are bounded rather than injected in full
48
- - Priority/complexity calibration: every reviewed refactor has short priority and complexity rationales, medium/low assignments are allowed when criteria fit, and high/high is not used merely because the work is cleanup, framework-related, multi-file, or user-requested
49
- - Domain cohesion: same contract-bounded capability stays one top-level item; independently shippable is not a split reason; same-domain over-split is `NEEDS_FIXES` unless one existing headless session cannot finish
50
- - Injected-field fidelity: confirmed structure, scope, preservation, and completion evidence are in `description` and `acceptance_criteria`; AI rewrite is allowed; dropping a confirmed item is not
51
- - Insert feasibility: every `dependencies` entry on a committed ID exists in the final list, the batch uses the consecutive IDs `context` reported, and the merge dry run returns `"valid": true`. Draft-only validation cannot see the merged graph, so a `PASS` without this check is a verdict the writer may reject.
52
- - Size: there is no word-count upper limit and no acceptance-criteria count upper limit
53
-
54
- ## Headless Context Completeness Gate
55
-
56
- Repeat the pre-generation simulation for every reviewed new or changed refactor as if the reviewer has never seen the planning conversation. First scan all AI-visible fields and sections; machine metadata is exempt, but every generated natural-language value must be session-independent. From the artifact alone, answer:
57
-
58
- 1. What exact confirmed structural problem or outcome is this task responsible for, and how does it preserve the intent baseline?
59
- 2. What current architecture exists according to evidence, which target statements are confirmed versus recommended/assumed, and what target architecture must replace it?
60
- 3. Which approach was selected, expressed by meaning rather than an option label?
61
- 4. What scope boundaries, constraints, and non-goals must be preserved?
62
- 5. Why is each reference material and target path relevant?
63
- 6. How can completion and behavior preservation be verified?
64
- 7. Does any phrase require an unseen earlier question, recommendation, or option list?
65
- 8. Do quoted source materials agree with the final task decision?
66
- 9. Does every operation have a confirmed structural goal, behavior invariant, existing contract, or evidenced risk, with no unrelated cleanup or speculative redesign?
67
-
68
- Return `NEEDS_FIXES` if any answer is missing, ambiguous, available only in `user_context`, or dependent on shorthand such as `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation`. Parenthetical notes are part of the artifact and must pass the same fresh-session test. Do not emit transcript annotations such as `(original response: "...")`; raw shorthand is not independently intelligible and materially useful. Preserve substantive rationale in the durable refactor contract. Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization: write the concrete accepted decisions, omit the raw approval, and never repeat it once per accepted recommendation. Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`; copy or normalize the task-relevant content into the contract, which must not depend on that source file still existing. Ask the user for clarification when there is not one provable antecedent.
69
-
70
- Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Apply this stricter gate prospectively to new or changed entries and preserve unchanged historical refactors.
71
-
72
- ### Good and Bad Review Examples
73
-
74
- - Bad: `go with your recommendation` as target architecture or as `(original response: "go with your recommendation")`; Good: `Selected decision: reverse the auth/user dependency through a shared identity interface and retain existing public imports`.
75
- - Bad: repeating `(original response: "全部按照推荐")`; Good: omit the blanket approval after writing each concrete accepted decision.
76
- - Bad: bare `src/auth/`; Good: `src/auth/ — inspect public exports, dependency direction, and compatibility call sites before restructuring`.
77
- - Bad: an entire RFC pasted into evidence or `.agents/brainstorm/refactor.md` retained as a requirement; Good: inline task-relevant excerpts and all confirmed target decisions, then omit the transient planning path.
78
-
79
- ## Fix Loop
80
-
81
- 1. Present findings with IDs, severity, evidence, and suggested draft/source changes.
82
- 2. Accept only findings that improve planner correctness, completeness, or downstream behavior-preserving execution readiness.
83
- 3. Apply accepted fixes to `.prizmkit/plans/refactor-list.draft.json` or the in-memory draft object first.
84
- 4. Re-check the fixed draft without writing:
85
-
86
- ```bash
87
- 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
88
- ```
89
-
90
- The dry run enforces the same base, exact-ID, dependency, and complete-DAG checks as the real insert, so keep it green instead of discovering a merge conflict after `PASS`. A new list or explicit full-list rewrite has no merged graph to check and nothing to overwrite, so its single post-`PASS` `generate` is the validator; if it rejects the draft, fix and retry, because no file was written.
91
-
92
- 5. Never hand-patch `.prizmkit/plans/refactor-list.json` as the source of truth and do not add a user approval round for the mechanical rewrite.
93
- 6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
94
- 7. Do not report `PASS` until every required fresh-session answer is available and the draft validation plus merge dry run pass.
95
- 8. After `PASS`, insert the batch exactly once (`append`, or `generate` for a new list), confirm the writer's `appended_ids`, then delete `.prizmkit/plans/refactor-list.draft.json`. Retain a draft only under the conditions in `${SKILL_DIR}/references/error-recovery.md`; report the retained path and reason.
96
-
97
- ## Report Format
98
-
99
- Report in the final handoff summary:
100
-
101
- - `Local generated-plan review: PASS` or `NEEDS_FIXES`
102
- - Reviewed batch IDs and reviewed root prose (`project_description` / `global_context`) when applicable
103
- - Merge dry-run result
104
- - Accepted fixes, or `none`
105
- - Insert result: the single writer run and the `appended_ids` it reported
106
- - Draft cleanup result: `removed`, or retained path and recovery reason
107
- - Note when review was not applicable because no new planning content was written
@@ -1,172 +0,0 @@
1
- # Planning Phases — Refactor Planner
2
-
3
- Detailed procedures for Phases 4-6 of the refactor-planner interactive workflow, plus refactoring-specific assessment rules and browser verification guidance.
4
-
5
- ---
6
-
7
- ## Phase 4: Item Decomposition Procedure
8
-
9
- Read `${SKILL_DIR}/assets/planning-guide.md` for decomposition patterns and dependency ordering rules.
10
-
11
- For each refactoring goal:
12
- 1. Identify only the atomic operations necessary for the confirmed structural outcome; map each operation to a goal, behavior invariant, existing contract, or evidenced risk. Group by contract-bounded capability (shared domain objects, state machine, invariants, public API, and error semantics; not the same module, directory, or written task contract); independently shippable is not a split reason.
13
- 2. Determine inter-item dependencies from actual producer/consumer relationships; use safe renames before structural changes as a default heuristic, not a substitute for evidence
14
- 3. Assess complexity per item from concrete indicators (file count, cross-module scope, public API/import-path impact, dependency depth, test coverage, behavior-preservation risk, migration impact)
15
- 4. Assign priority from concrete impact (blocked delivery, correctness/security/data risk, maintainability value, or local cleanup), not from size or user urgency alone
16
- 5. Assign behavior preservation strategy per item (read `${SKILL_DIR}/references/behavior-preservation.md`)
17
-
18
- ---
19
-
20
- ## Phase 5: Per-Item Confirmation Loop
21
-
22
- Present items in reviewable groups. Use `AskUserQuestion` for each consequential scope, target-architecture, public-contract, migration, or behavior-preservation decision; independent low-risk items may share one confirmation batch when their meanings remain clear:
23
-
24
- ```text
25
- Refactor Item R-001:
26
- Title: [title]
27
- Type: [extract/rename/restructure/simplify/decouple/migrate]
28
- Scope: [files list]
29
- Priority: [critical/high/medium/low]
30
- Priority Rationale: [short concrete impact reason]
31
- Complexity: [low/medium/high]
32
- Complexity Rationale: [short scope/risk reason]
33
- Behavior Preservation: [test-gate/snapshot/manual]
34
- Acceptance Criteria:
35
- - [criterion 1]
36
- - [criterion 2]
37
- Dependencies: [none / R-002, R-003]
38
- ```
39
-
40
- Offer `Accept`, `Modify`, and `Skip` as selectable options. Re-display modified consequential items before acceptance. Do not ask the user to approve unconstrained implementation mechanics that preserve all confirmed boundaries and remain locally reversible.
41
-
42
- ---
43
-
44
- ## Phase 6: Completeness Review Checklist
45
-
46
- 1. **Dependency ordering check**: Verify items form a valid DAG (no cycles). Follow verified producer/consumer dependencies; otherwise prefer the risk-reducing order safe renames -> extract/inline -> structural changes -> migrations.
47
- 2. **Behavior preservation check**: Every item must have a declared preservation strategy. Flag any item with `manual` strategy and no test coverage.
48
- 3. **Gap detection**: Are there intermediate steps needed between items? Does item A's output match item B's input assumption?
49
- 4. **Cross-module impact**: Do any items affect modules outside the declared scope?
50
- 5. **Intent and design necessity**: Does every item map to a confirmed structural goal, behavior invariant, existing contract, or evidenced risk? Remove unrelated cleanup and speculative redesign.
51
- 6. **Evidence status**: Are current-state observations, inferred architecture, recommendations, assumptions, and unknowns labeled distinctly? No AI-proposed architecture may appear as confirmed user intent without confirmation.
52
- 7. **Headless Context Completeness Gate**: Review every new or changed item as if the reviewer has never seen the planning conversation. Preserve unchanged historical items. Scan all AI-visible fields and sections first: every generated natural-language value in `project_description`, `global_context`, item fields, scope explanations, behavior-preservation/evidence text, `user_context`, comments, and parentheticals must be session-independent, with no dialogue-role labels, question IDs, answer tokens, planning-option recommendation markers, or planning provenance. Review changed root prose even when no refactor item changed. Then assess `description` plus `acceptance_criteria` without `user_context` and answer from the artifact alone:
53
- 1. What exact confirmed structural problem or outcome is this task responsible for, and how does it preserve the intent baseline?
54
- 2. What current architecture exists according to evidence, which target statements are confirmed versus recommended/assumed, and what target architecture must replace it?
55
- 3. Which approach was selected, expressed by meaning rather than an option label?
56
- 4. What scope boundaries, constraints, and non-goals must be preserved?
57
- 5. Why is each reference material and target path relevant, and what should be inspected?
58
- 6. Which integrations, consumers, import paths, and edge cases are affected?
59
- 7. Which behavior-preservation decisions and completion evidence prove equivalence?
60
- 8. Does any phrase require an unseen earlier question, recommendation, or option list?
61
- 9. Do quoted source materials agree with the final task decision?
62
- 10. Does every operation map to a confirmed structural goal, behavior invariant, existing contract, or evidenced risk, with no unrelated cleanup or speculative redesign?
63
-
64
- Return `NEEDS_FIXES` whenever any answer is missing, ambiguous, or available only in `user_context`. Parenthetical notes must pass the same gate. Do not emit transcript annotations such as `(original response: "...")`; preserve substantive rationale, but omit bare selection tokens and `全部按照推荐` or equivalent blanket recommendation approval after normalization. Ask the user for clarification when a relative statement has more than one plausible antecedent; never guess.
65
-
66
- - **Scope clarity**: List all affected files and explain each file or coherent group as purpose-tagged target paths.
67
- - **Target architecture**: State concrete module ownership, interfaces, dependency direction, compatibility boundaries, and desired end state.
68
- - **Behavior preservation**: State what tests, snapshots, or reproducible checks run and which observable behavior must remain equivalent.
69
- - **Dependency context**: State which exact earlier refactor output this item consumes.
70
- - **Good**: `Extract validateEmail, validatePhone, and validateUrl from src/utils/helpers.ts into src/utils/validation.ts; update all 12 import sites; preserve signatures and error semantics. src/utils/helpers.ts — inspect current exports and callers before extraction.`
71
- - **Bad**: `Clean up the utils module`, `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation`.
72
- - **Bad normalization**: append `(original response: "方案B")` to a complete architecture decision; the annotation is not independently intelligible and materially useful.
73
- - **Good normalization**: `Selected decision: introduce an auth-owned validation module while retaining existing public imports through compatibility re-exports`.
74
- - **Bad material handling**: embed an entire architecture RFC while saying `apply this`, or retain `.agents/brainstorm/refactor.md` as a final requirement source.
75
- - Do not retain non-code planning-source paths in the final contract.
76
- - **Good material handling**: copy or normalize the task-relevant content and exact excerpts into the contract; retain only purpose-tagged stable execution targets. The item must not depend on that source file still existing.
77
- - Exclude `所有问题都按你的推荐处理`, `全部按照推荐`, and equivalent conversational authorization when it does not constrain implementation; never repeat it once per accepted recommendation.
78
- - `user_context` is supplementary evidence only. If `user_context` were removed, execution and verification must remain unambiguous at matching detail.
79
- - Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures.
80
-
81
- ### Review Summary Table Format
82
-
83
- Present review summary:
84
-
85
- ```
86
- Item | Priority | Priority Rationale | Complexity | Complexity Rationale | Deps Valid | Preservation | Gaps | Status
87
- R-001 | high | Blocks core feature work | high | 3 modules + public imports | OK | test-gate | - | Ready
88
- R-002 | medium | Planned maintainability | medium | 5 files + tests exist | OK | test-gate | - | Ready
89
- R-003 | low | Local readability only | low | One file, no API change | OK | manual | No test coverage| Needs attention
90
- R-004 | medium | Reduces bounded coupling | medium | 2 modules + snapshot check | OK | snapshot | - | Ready
91
- ```
92
-
93
- If issues are found, discuss with the user, apply fixes to the draft/source item, and rerun the Headless Context Completeness Gate until every new or changed item returns `PASS` before proceeding.
94
-
95
- ---
96
-
97
- ## Behavior Preservation Check
98
-
99
- Every item MUST declare a behavior preservation strategy. Read `${SKILL_DIR}/references/behavior-preservation.md` for strategy details.
100
-
101
- | Strategy | When to Use |
102
- |----------|-------------|
103
- | `test-gate` | Reliable tests cover the preserved contract; record the relevant evidence and the required downstream pass condition. |
104
- | `snapshot` | Deterministic output or state can be compared; record representative inputs, normalization, and required equivalence. |
105
- | `manual` | Human judgment is unavoidable; record a reproducible checklist and flag the higher verification risk. |
106
-
107
- Flag items using `manual` strategy prominently — they carry the highest risk of behavior regression.
108
-
109
- ---
110
-
111
- ## Dependency Ordering
112
-
113
- Auto-detect producer/consumer dependencies and enforce the resulting safe order. When no evidence requires another sequence, use this risk-reducing heuristic:
114
- 1. **Safe renames** first (lowest risk, no structural change)
115
- 2. **Extract/inline** operations (moderate risk, changes module boundaries)
116
- 3. **Structural changes** (higher risk, reorganizes architecture)
117
- 4. **Migrations** last (highest risk, changes patterns/paradigms)
118
-
119
- Do not reorder items against verified dependencies merely to match the heuristic.
120
-
121
- ---
122
-
123
- ## Complexity Assessment
124
-
125
- Complexity is a behavior-preserving execution risk estimate, not a measure of how much the user wants the refactor. Do not default to high because a refactor spans multiple files, targets framework code, or improves maintainability.
126
-
127
- Assess each item's complexity based on:
128
- - **File count**: 1-3 files = low, 4-8 files = medium, 9+ files = high
129
- - **Cross-module scope**: same module = low, 2 modules = medium, 3+ modules = high
130
- - **Public API/import-path impact**: no public change = low, bounded internal interface = medium, public API/import migration = high
131
- - **Dependency depth**: 0-2 import/update sites = low, 3-5 = medium, 6+ = high
132
- - **Test coverage**: strong existing tests can keep complexity lower; weak/missing tests increase complexity
133
- - **Behavior-preservation risk**: test-gate with clear assertions = lower, snapshot/manual verification = higher
134
- - **Migration impact**: no rollout = low, compatibility shim = medium, cross-module migration or phased rollout = high
135
-
136
- Take the highest well-supported individual assessment as the item's complexity, then record the rationale in the confirmation table.
137
-
138
- ### Mixed Calibration Examples
139
-
140
- | Refactor | Priority | Complexity | Rationale |
141
- |----------|----------|------------|-----------|
142
- | Break circular dependency blocking auth feature work | high | high | Blocks core delivery; 3 modules, public imports, and weak tests. |
143
- | Extract chart formatting helpers from dashboard files | medium | medium | Improves planned maintainability; 5 files with bounded helper API and existing tests. |
144
- | Rename local variable in parser for readability | low | low | Local cleanup only; one file, no interface or behavior change. |
145
-
146
- Anti-pattern: do not generate an all-high refactor list unless every item independently satisfies documented high-priority and high-complexity criteria.
147
-
148
- ---
149
-
150
- ## Browser Verification
151
-
152
- Browser verification is supported for UI-affecting refactors, but it is supplemental. Every refactor still uses `behavior_preservation.strategy` as the primary preservation contract:
153
-
154
- - `strategy: test-gate` — Record the relevant existing tests and the required downstream pass condition.
155
- - `strategy: snapshot` — Record the representative inputs, observable outputs, and allowed normalization for downstream comparison.
156
- - `strategy: manual` — Record a reproducible human-verification checklist and the reason automated evidence is insufficient.
157
-
158
- 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:
159
-
160
- Example:
161
- ```
162
- Refactor Title: Extract UserProfile component from AccountSettings
163
- Type: extract
164
- Strategy: snapshot
165
- Acceptance Criteria:
166
- 1. UserProfile component renders identically to inline version (compare snapshots)
167
- 2. All props are correctly forwarded (unit tests pass)
168
- 3. No visual regression (screenshot comparison)
169
- 4. Component is reusable in other views
170
- ```
171
-
172
- The generated plan supplies this evidence contract to the autonomous refactor session; this planner does not execute the verification.
@@ -1,230 +0,0 @@
1
- # Refactor Scoping Guide
2
-
3
- This guide helps assess refactoring scope, determine the appropriate approach, and identify risks before decomposing into executable items.
4
-
5
- Treat numeric thresholds and named patterns in this guide as evidence prompts, not user-intent overrides. Base the final scope, complexity, and decomposition on verified files, consumers, contracts, tests, and the confirmed structural goal. Label estimates as recommendations or assumptions until evidence supports them.
6
-
7
- ---
8
-
9
- ## 1. Scope Classification
10
-
11
- Classify the observed refactoring effort into the closest of three scope categories. Classification recommends planning depth; it does not expand the user's goal or make a larger target architecture mandatory.
12
-
13
- ### Incremental Refactoring
14
-
15
- **Definition**: Gradual, low-risk improvements applied piece by piece. Each step is independently deployable.
16
-
17
- **Characteristics**:
18
- - Targets a specific area without restructuring the whole module
19
- - Each item can be merged independently
20
- - Low coordination overhead between items
21
- - Suitable for ongoing tech debt reduction
22
-
23
- **When to use**:
24
- - Code smell is localized (one file, one function, one class)
25
- - Team wants continuous improvement without large PRs
26
- - Risk tolerance is low
27
- - No architectural changes needed
28
-
29
- **Planning depth**: Lightweight. Phase 3 (Code Analysis) can be abbreviated. Fast path may apply.
30
-
31
- ### Full Refactoring
32
-
33
- **Definition**: Comprehensive restructuring of an entire module, subsystem, or architectural layer.
34
-
35
- **Characteristics**:
36
- - Touches many files across the target area
37
- - Items have significant interdependencies
38
- - Requires careful ordering and coordination
39
- - Higher risk, bigger payoff
40
- - May need a feature branch or phased rollout
41
-
42
- **When to use**:
43
- - Module has accumulated significant tech debt
44
- - Current structure actively impedes feature development
45
- - Multiple code smells are interconnected
46
- - Architecture needs fundamental restructuring
47
-
48
- **Planning depth**: Full workflow required. All 7 phases mandatory. No fast path.
49
-
50
- ### Targeted Refactoring
51
-
52
- **Definition**: Focused on a specific concern, pattern, or dependency — not the entire module.
53
-
54
- **Characteristics**:
55
- - Clear, narrow objective (e.g., "extract payment logic", "break circular dependency")
56
- - May touch multiple files but only for the specific concern
57
- - Moderate risk
58
- - Well-defined "done" state
59
-
60
- **When to use**:
61
- - Specific pain point identified (circular dependency, god class, leaky abstraction)
62
- - New feature requires cleaner structure in one area
63
- - Code review identified a specific structural issue
64
-
65
- **Planning depth**: Standard workflow. Phase 3 focuses on the specific concern.
66
-
67
- ---
68
-
69
- ## 2. File Impact Analysis
70
-
71
- Before decomposing, assess the blast radius of the proposed refactoring.
72
-
73
- ### Impact Assessment Steps
74
-
75
- 1. **Identify primary targets**: Files/modules directly being refactored
76
- 2. **Trace imports/dependencies**: What files import from the targets?
77
- 3. **Trace test files**: What test files exercise the targets?
78
- 4. **Trace configuration**: Do any config files reference the targets (routes, DI containers, etc.)?
79
- 5. **Count total affected files**: Primary + importing + testing + config
80
-
81
- ### Impact Categories
82
-
83
- Use file counts as an initial heuristic, then adjust from verified public contracts, dependency direction, behavior risk, and test coverage. A high count of mechanical import updates can be lower risk than one safety-critical public contract.
84
-
85
- | Affected Files | Impact Level | Planning Implication |
86
- |---------------|-------------|---------------------|
87
- | 1-3 | Low | Complexity/risk label; still one item when it is one contract-bounded capability |
88
- | 4-8 | Medium | Raise complexity label and verification depth; do not add items solely for file count |
89
- | 9-15 | High | Stronger tests and dependency tracing; keep one item unless an existing headless session cannot finish |
90
- | 16+ | Very High | Session-overflow split at capability seams only; file count is not a split reason |
91
-
92
- ### Dependency Graph Analysis
93
-
94
- For each target file, map:
95
- - **Incoming dependencies**: Who imports/uses this file? (blast radius)
96
- - **Outgoing dependencies**: What does this file import? (coupling assessment)
97
- - **Circular dependencies**: Does this file participate in any cycles? (critical risk)
98
-
99
- Tools to assess:
100
- ```bash
101
- # Find all importers of a module (JS/TS)
102
- grep -r "from.*['\"].*target-module" --include="*.js" --include="*.ts" -l
103
-
104
- # Find all importers of a module (Python)
105
- grep -r "from.*target_module\|import.*target_module" --include="*.py" -l
106
-
107
- # Count total affected files
108
- # Primary targets + importers + their test files
109
- ```
110
-
111
- ---
112
-
113
- ## 3. Cross-Module Dependency Assessment
114
-
115
- Cross-module refactoring carries higher risk because changes ripple through module boundaries.
116
-
117
- ### Assessment Checklist
118
-
119
- | Question | If Yes |
120
- |----------|--------|
121
- | Does the refactoring change any module's public API? | All consumers must be updated. Document API changes explicitly. |
122
- | Does it change import paths? | All importers must be updated. Consider re-exports for backward compatibility. |
123
- | Does it move shared types/interfaces? | All type consumers must be updated. May need temporary type aliases. |
124
- | Does it change event/message contracts? | All subscribers/handlers must be updated. Version the contract if possible. |
125
- | Does it affect database schema? | Migration required. This may be beyond refactoring scope. |
126
- | Does it change configuration format? | Config consumers must be updated. Consider backward-compatible format. |
127
-
128
- ### Cross-Module Risk Mitigation
129
-
130
- 1. **Re-export pattern**: When moving a module, leave a re-export at the old path during transition
131
- 2. **Adapter pattern**: When changing an interface, create an adapter that bridges old and new
132
- 3. **Feature flag**: For risky cross-module changes, implement behind a flag
133
- 4. **Phased rollout**: Update consumers module by module, not all at once
134
-
135
- ---
136
-
137
- ## 4. Risk Assessment Framework
138
-
139
- Assess risk for each refactoring item and for the overall plan.
140
-
141
- ### Per-Item Risk Factors
142
-
143
- Use only measurements supported by repository evidence. If coverage, code age, complexity, or dependency counts are unknown, mark them unknown rather than selecting a risk band from intuition.
144
-
145
- | Factor | Low Risk | Medium Risk | High Risk |
146
- |--------|----------|-------------|-----------|
147
- | Test coverage | >80% on target | 40-80% | <40% |
148
- | Dependency count | 0-2 dependents | 3-5 dependents | 6+ dependents |
149
- | Code age | Recently written/modified | 6-12 months old | 1+ year untouched |
150
- | Documentation | Well-documented | Partially documented | No documentation |
151
- | Complexity (cyclomatic) | <10 | 10-20 | >20 |
152
- | Cross-module impact | None | 1 other module | 2+ other modules |
153
-
154
- ### Overall Plan Risk
155
-
156
- Aggregate item risks to assess the plan:
157
- - **Low risk plan**: All items are low risk, or mostly low with 1-2 medium
158
- - **Medium risk plan**: Mix of low and medium, or 1-2 high risk items
159
- - **High risk plan**: Multiple high risk items, or cross-module migration
160
-
161
- ### Risk Mitigation Strategies
162
-
163
- | Risk Level | Strategy |
164
- |-----------|----------|
165
- | Low | Standard test-gate, proceed normally |
166
- | Medium | Ensure snapshot comparison, add extra acceptance criteria |
167
- | High | Require stronger tests first; do not split a contract-bounded capability solely because risk is high |
168
- | Very High | Recommend writing comprehensive tests before refactoring; split only when one existing headless session cannot finish |
169
-
170
- ---
171
-
172
- ## 5. When to Split Large Refactors
173
-
174
- ### Splitting Heuristics
175
-
176
- Treat these as triggers to assess a split, not automatic requirements. Split only when it reduces evidenced coordination, behavior-preservation, context, or rollback risk without breaking a necessary atomic migration:
177
-
178
- 1. **Item count exceeds 8**: More than 8 items in a single plan increases coordination risk. Split into logical phases only when that is a different contract-bounded capability or an existing headless session cannot finish.
179
- 2. **Existing-session overflow**: Split at capability seams only when implementation plus verification cannot finish in one existing headless session.
180
- 3. **Risk accumulates**: If early items must be proven before a later high-risk seam, keep them as top-level items only when they do not share one contract-bounded capability that would otherwise drift.
181
- 4. **Cross-module work in one contract-bounded capability stays one item.** Independently shippable is not a split reason.
182
- 5. **Different preservation strategies**: Split only when those strategies cannot share one contract and one existing headless session.
183
-
184
- ### How to Split
185
-
186
- When a split is justified by the heuristics above, create additional **top-level** items at capability seams, each with a complete injected contract:
187
-
188
- 1. **By contract-bounded capability**, not by directory or module name alone
189
- 2. **By existing-session overflow**, when one headless session cannot finish implementation plus verification
190
- 3. **By true dependency layer** only when later work cannot share the earlier item's contracts without drift
191
-
192
- Do not open a new list merely because files live in different modules. Independently shippable is not a split reason.
193
-
194
- ### Merging Split Plans
195
-
196
- When executing split plans sequentially:
197
- - Run the first plan fully (including validation)
198
- - Verify all tests pass after the first plan
199
- - Then start planning the second phase (the codebase has changed)
200
- - Do NOT pre-plan the second phase based on the original code state
201
-
202
- ---
203
-
204
- ## 6. Scope Boundary Enforcement
205
-
206
- During planning, actively enforce scope boundaries to prevent scope creep.
207
-
208
- ### In-Scope Markers
209
-
210
- Explicitly define what IS in scope:
211
- - Specific files or directories
212
- - Specific refactoring operations
213
- - Specific code smells being addressed
214
-
215
- ### Out-of-Scope Markers
216
-
217
- Explicitly define what is NOT in scope:
218
- - New features (redirect to `feature-planner`)
219
- - Bug fixes (redirect to `bug-planner`)
220
- - Performance optimization that changes behavior
221
- - Database schema changes (requires migration planning)
222
- - API contract changes (requires consumer coordination)
223
-
224
- ### Scope Creep Detection
225
-
226
- Flag and discuss with the user when:
227
- - A refactoring item implies new functionality
228
- - An item requires changing external interfaces
229
- - An item's description includes "also add" or "while we're at it"
230
- - An item's acceptance criteria describe new behavior, not preserved behavior