prizmkit 1.1.162 → 1.1.165

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 (75) hide show
  1. package/bin/create-prizmkit.js +4 -4
  2. package/bundled/VERSION.json +3 -3
  3. package/bundled/adapters/cursor/assets/prizmkit-hook.cjs +65 -0
  4. package/bundled/adapters/cursor/hooks-adapter.js +139 -0
  5. package/bundled/adapters/cursor/paths.js +11 -0
  6. package/bundled/adapters/cursor/rules-adapter.js +49 -0
  7. package/bundled/adapters/cursor/skill-adapter.js +27 -0
  8. package/bundled/dev-pipeline/README.md +18 -5
  9. package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py +3 -25
  10. package/bundled/dev-pipeline/prizmkit_runtime/config.py +71 -14
  11. package/bundled/dev-pipeline/prizmkit_runtime/gitops.py +28 -4
  12. package/bundled/dev-pipeline/prizmkit_runtime/heartbeat.py +5 -2
  13. package/bundled/dev-pipeline/prizmkit_runtime/platform_detection.py +21 -3
  14. package/bundled/dev-pipeline/prizmkit_runtime/runners.py +19 -5
  15. package/bundled/dev-pipeline/prizmkit_runtime/sessions.py +123 -28
  16. package/bundled/dev-pipeline/prizmkit_runtime/status.py +2 -0
  17. package/bundled/dev-pipeline/prizmkit_runtime/test_result.py +1 -42
  18. package/bundled/dev-pipeline/scripts/init-bugfix-pipeline.py +43 -6
  19. package/bundled/dev-pipeline/scripts/init-pipeline.py +46 -8
  20. package/bundled/dev-pipeline/scripts/init-refactor-pipeline.py +41 -6
  21. package/bundled/dev-pipeline/scripts/parse-stream-progress.py +143 -27
  22. package/bundled/dev-pipeline/scripts/update-feature-status.py +2 -2
  23. package/bundled/dev-pipeline/scripts/utils.py +3 -12
  24. package/bundled/dev-pipeline/templates/bug-fix-list-schema.json +4 -2
  25. package/bundled/dev-pipeline/templates/feature-list-schema.json +4 -2
  26. package/bundled/dev-pipeline/templates/refactor-list-schema.json +4 -2
  27. package/bundled/dev-pipeline/tests/live_ai_cli_log_smoke.py +2 -1
  28. package/bundled/dev-pipeline/tests/test_checkpoint_state.py +5 -23
  29. package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py +2 -2
  30. package/bundled/dev-pipeline/tests/test_python_runner_parity.py +231 -0
  31. package/bundled/dev-pipeline/tests/test_unified_cli.py +406 -30
  32. package/bundled/dev-pipeline/tests/test_utils.py +23 -0
  33. package/bundled/rules/USAGE.md +3 -0
  34. package/bundled/skills/_metadata.json +1 -1
  35. package/bundled/skills/app-planner/SKILL.md +18 -9
  36. package/bundled/skills/app-planner/references/app-design-guide.md +7 -5
  37. package/bundled/skills/app-planner/references/brainstorm-guide.md +13 -21
  38. package/bundled/skills/app-planner/references/generated-plan-review.md +6 -2
  39. package/bundled/skills/bug-planner/SKILL.md +13 -5
  40. package/bundled/skills/bug-planner/assets/bug-confirmation-template.md +11 -7
  41. package/bundled/skills/bug-planner/references/generated-plan-review.md +7 -3
  42. package/bundled/skills/bug-planner/references/verification.md +0 -2
  43. package/bundled/skills/bug-planner/scripts/validate-bug-list.py +37 -7
  44. package/bundled/skills/feature-planner/SKILL.md +17 -11
  45. package/bundled/skills/feature-planner/assets/planning-guide.md +13 -13
  46. package/bundled/skills/feature-planner/references/completeness-review.md +8 -4
  47. package/bundled/skills/feature-planner/references/generated-plan-review.md +6 -2
  48. package/bundled/skills/feature-planner/scripts/validate-and-generate.py +43 -19
  49. package/bundled/skills/prizmkit-init/SKILL.md +1 -1
  50. package/bundled/skills/prizmkit-init/references/config-schema.md +2 -2
  51. package/bundled/skills/prizmkit-plan/SKILL.md +15 -4
  52. package/bundled/skills/prizmkit-plan/assets/plan-template.md +18 -3
  53. package/bundled/skills/prizmkit-plan/assets/spec-template.md +17 -5
  54. package/bundled/skills/prizmkit-plan/references/clarify-guide.md +26 -24
  55. package/bundled/skills/prizmkit-plan/references/review-plan-spec-loop.md +7 -5
  56. package/bundled/skills/prizmkit-plan/references/verification-checklist.md +15 -6
  57. package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md +1 -1
  58. package/bundled/skills/prizmkit-prizm-docs/references/op-init.md +1 -1
  59. package/bundled/skills/refactor-planner/SKILL.md +18 -11
  60. package/bundled/skills/refactor-planner/references/generated-plan-review.md +6 -2
  61. package/bundled/skills/refactor-planner/references/planning-phases.md +14 -9
  62. package/bundled/skills/refactor-planner/references/refactor-scoping-guide.md +8 -2
  63. package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +38 -9
  64. package/package.json +4 -2
  65. package/src/ai-cli-launch.js +9 -2
  66. package/src/clean.js +42 -6
  67. package/src/config.js +51 -10
  68. package/src/detect-platform.js +30 -8
  69. package/src/external-skills.js +33 -99
  70. package/src/index.js +5 -0
  71. package/src/manifest.js +30 -4
  72. package/src/platforms.js +11 -4
  73. package/src/prompts.js +12 -4
  74. package/src/scaffold.js +75 -4
  75. package/src/upgrade.js +15 -14
@@ -42,6 +42,21 @@ VALID_STATUSES = {"pending", "in_progress", "completed", "failed", "skipped", "s
42
42
  VALID_COMPLEXITIES = {"low", "medium", "high", "critical"}
43
43
  VALID_PRIORITIES = {"critical", "high", "medium", "low"}
44
44
  VALID_GRANULARITIES = {"feature", "sub_feature", "auto"}
45
+ ALLOWED_LIST_FIELDS = {
46
+ "$schema", "project_name", "project_description", "created_at",
47
+ "created_by", "features", "global_context",
48
+ }
49
+ ALLOWED_GLOBAL_CONTEXT_FIELDS = {
50
+ "tech_stack", "language", "runtime", "frontend_framework",
51
+ "frontend_styling", "backend_framework", "database", "orm",
52
+ "design_system", "testing_strategy", "bundler", "project_type",
53
+ }
54
+ ALLOWED_FEATURE_FIELDS = {
55
+ "id", "title", "description", "priority", "estimated_complexity",
56
+ "dependencies", "acceptance_criteria", "status", "session_granularity",
57
+ "sub_features", "model", "completion_notes", "user_context",
58
+ "browser_interaction", "testing",
59
+ }
45
60
  FEATURE_ID_RE = re.compile(r"^F-\d{3}(-[A-Z])?$")
46
61
  SUB_FEATURE_ID_RE = re.compile(r"^F-\d{3}-[A-Z]$")
47
62
 
@@ -170,17 +185,33 @@ def validate_feature_list(data, is_new_plan=True):
170
185
  # ------------------------------------------------------------------
171
186
  # 1. Top-level schema validation
172
187
  # ------------------------------------------------------------------
188
+ unknown_root = set(data) - ALLOWED_LIST_FIELDS
189
+ if unknown_root:
190
+ errors.append("feature list has unknown fields: {}".format(
191
+ ", ".join(sorted(unknown_root))
192
+ ))
193
+
173
194
  schema = data.get("$schema")
174
195
  if schema != SCHEMA_VERSION:
175
196
  errors.append(
176
197
  "$schema must be '{}', got '{}'".format(SCHEMA_VERSION, schema)
177
198
  )
178
199
 
179
- # Support both project_name (canonical) and app_name (legacy)
180
- app_name = data.get("project_name", data.get("app_name"))
181
- if not isinstance(app_name, str) or not app_name.strip():
200
+ project_name = data.get("project_name")
201
+ if not isinstance(project_name, str) or not project_name.strip():
182
202
  errors.append("project_name must be a non-empty string")
183
203
 
204
+ global_context = data.get("global_context")
205
+ if global_context is not None:
206
+ if not isinstance(global_context, dict):
207
+ errors.append("global_context must be an object")
208
+ else:
209
+ unknown_context = set(global_context) - ALLOWED_GLOBAL_CONTEXT_FIELDS
210
+ if unknown_context:
211
+ errors.append("global_context has unknown fields: {}".format(
212
+ ", ".join(sorted(unknown_context))
213
+ ))
214
+
184
215
  features = data.get("features")
185
216
  if not isinstance(features, list) or len(features) == 0:
186
217
  errors.append("features must be a non-empty array")
@@ -225,6 +256,12 @@ def validate_feature_list(data, is_new_plan=True):
225
256
  label, ", ".join(sorted(missing))
226
257
  ))
227
258
 
259
+ unknown = set(feat.keys()) - ALLOWED_FEATURE_FIELDS
260
+ if unknown:
261
+ errors.append("{} has unknown fields: {}".format(
262
+ label, ", ".join(sorted(unknown))
263
+ ))
264
+
228
265
  # -- ID format & uniqueness --
229
266
  fid = feat.get("id", "")
230
267
  if not FEATURE_ID_RE.match(str(fid)):
@@ -335,15 +372,6 @@ def validate_feature_list(data, is_new_plan=True):
335
372
  # -- Sub-features --
336
373
  subs = feat.get("sub_features")
337
374
 
338
- # -- Retired fields --
339
- for retired_field in ("critic", "critic_count"):
340
- if retired_field in feat:
341
- errors.append(
342
- "{}: '{}' field is retired; remove it from feature-list data".format(
343
- label, retired_field
344
- )
345
- )
346
-
347
375
  # -- Browser interaction check (warning for frontend features) --
348
376
  has_frontend = bool(
349
377
  data.get("global_context", {}).get("frontend_framework")
@@ -546,11 +574,11 @@ def _build_dependency_graph_text(features):
546
574
 
547
575
  def generate_summary_markdown(data):
548
576
  """Generate a markdown summary of the feature list."""
549
- app_name = data.get("project_name", data.get("app_name", "Unknown"))
577
+ project_name = data.get("project_name", "Unknown")
550
578
  features = data.get("features", [])
551
579
 
552
580
  lines = []
553
- lines.append("# Feature Summary: {}".format(app_name))
581
+ lines.append("# Feature Summary: {}".format(project_name))
554
582
  lines.append("")
555
583
 
556
584
  # Table header
@@ -636,7 +664,7 @@ def generate_summary_json(data):
636
664
  })
637
665
 
638
666
  return {
639
- "project_name": data.get("project_name", data.get("app_name", "")),
667
+ "project_name": data.get("project_name", ""),
640
668
  "features": feature_summaries,
641
669
  "stats": {
642
670
  "total_features": len(features),
@@ -749,10 +777,6 @@ def cmd_generate(args):
749
777
  data.setdefault("created_at", now)
750
778
  data.setdefault("created_by", "feature-planner")
751
779
 
752
- # Ensure project_name from app_name if needed
753
- if "project_name" not in data and "app_name" in data:
754
- data["project_name"] = data["app_name"]
755
-
756
780
  # Set default status for features without one
757
781
  for feature in data.get("features", []):
758
782
  feature.setdefault("status", "pending")
@@ -82,7 +82,7 @@ BROWNFIELD WORKFLOW (existing project):
82
82
  - TOP-LEVEL modules: directories directly under project root that contain source files or sub-directories with source files (e.g. `src/`, `internal/`, `lib/`)
83
83
  - SUB-MODULES: directories INSIDE a top-level module (e.g. `src/routes/`, `src/models/`)
84
84
  - Exact `root.prizm` is L0; top-level module M maps to direct-child `.prizmkit/prizm-docs/<M>.prizm` (L1); sub-module S maps to nested `.prizmkit/prizm-docs/<M>/<S>.prizm` (L2). Deeper source ownership remains L2 and never creates L3.
85
- - Exclude: `.git/`, `node_modules/`, `vendor/`, `build/`, `dist/`, `__pycache__/`, `target/`, `bin/`, `.agents/`, `.codex/`, `.claude/`, `.codebuddy/`, `.pi/`, and the complete `.prizmkit/` framework directory. This excludes installed `.prizmkit/dev-pipeline/` artifacts but not canonical top-level `dev-pipeline/` source.
85
+ - Exclude: `.git/`, `node_modules/`, `vendor/`, `build/`, `dist/`, `__pycache__/`, `target/`, `bin/`, `.agents/`, `.codex/`, `.claude/`, `.codebuddy/`, `.pi/`, `.cursor/`, and the complete `.prizmkit/` framework directory. This excludes installed `.prizmkit/dev-pipeline/` artifacts but not canonical top-level `dev-pipeline/` source.
86
86
  - **Bounded discovery contract** — use the current Host's available directory-listing or file-search capability to enumerate at most two directory levels, apply the exclusions above before analysis, preserve parent/child relationships, and report the resulting project-relative structure. Do not require a POSIX shell pipeline or any other operating-system-specific command.
87
87
  3. Identify entry points by language convention
88
88
  4. Catalog dependencies (external packages)
@@ -20,13 +20,13 @@ Handles re-init without losing user edits:
20
20
  | Field | Type | Description |
21
21
  |-------|------|-------------|
22
22
  | `adoption_mode` | string | `"passive"` \| `"advisory"` \| `"active"` |
23
- | `platform` | string | Installed payload metadata: `"codebuddy"` \| `"claude"` \| `"codex"` \| `"pi"` \| `"all"`. It records installation, not a canonical behavior allowlist. |
23
+ | `platform` | string | Installed payload metadata: `"codebuddy"` \| `"claude"` \| `"codex"` \| `"pi"` \| `"cursor"` \| `"all"`. It records installation, not a canonical behavior allowlist. |
24
24
  | `tech_stack` | object | Detected or user-provided tech stack |
25
25
  | `tech_stack._auto_detected` | boolean | `true` if auto-detected, `false` if user-provided |
26
26
  | `detected_layers` | string[] | Development layers observed in the project. Written by prizmkit-init Phase 4.5. Values: `frontend` / `backend` / `database` / `mobile`. Empty only when no layers are observed. Always refreshed from code and never cleared by rule-adoption choices. |
27
27
  | `enabled_rule_profiles` | string[] | Rule profiles the user explicitly enabled. This is independent from `detected_layers`; an empty array means no custom profile is enabled, not that the project has no detected layers. |
28
28
 
29
- Legacy manifests may still contain `both` for read-only migration compatibility. New config writes must use `codebuddy`, `claude`, `codex`, `pi`, or `all`.
29
+ Legacy manifests may still contain `both` for read-only migration compatibility. New config writes must use `codebuddy`, `claude`, `codex`, `pi`, `cursor`, or `all`.
30
30
 
31
31
  ## Examples
32
32
 
@@ -32,6 +32,15 @@ A change artifact can describe a feature, bug fix, refactor, migration, test imp
32
32
 
33
33
  `prizmkit-plan` owns specification, plan, task generation, and planning-quality review for one supplied requirement. Its terminal outputs are `PLAN_READY` or `PLAN_BLOCKED`; it stops after producing that result.
34
34
 
35
+ ## Intent-Aligned Planning Policy
36
+
37
+ Before proposing or finalizing a plan:
38
+ 1. Establish the **intent baseline**: confirmed goal, success outcome, scope/non-goals, and explicit constraints. User requirements and confirmed decisions outrank AI preferences or general best practices; never silently violate safety, legal/privacy/data-integrity obligations, or verified existing contracts. Surface material conflicts instead.
39
+ 2. Maintain **evidence status**: distinguish confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns. Never promote an inference or recommendation into user intent.
40
+ 3. **Clarify by decision impact**. Ask before choices that materially change goals, external behavior, scope, compatibility, safety, cost, or irreversible state. Resolve from project evidence first; for low-risk, local, and reversible details, record a disclosed assumption instead of interrupting.
41
+ 4. Explore alternatives only when **materially different viable paths** exist. Compare meaningful trade-offs without manufacturing an option count or applying a universal default.
42
+ 5. Produce a **minimum-sufficient** plan: every plan element maps to a confirmed goal, constraint, existing contract, or evidenced risk, and every goal maps to observable completion evidence. Defer unsupported future work.
43
+
35
44
  ## Phase 0: Initialization Check and Context
36
45
 
37
46
  1. Check whether project context such as `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json`, or a project brief exists.
@@ -49,13 +58,14 @@ Skip regeneration when `spec.md` already exists and still matches the requested
49
58
  - otherwise derive the normalized title slug, allocate the next collision-safe number, and create `.prizmkit/specs/<number>-<slug>/`.
50
59
  3. Generate `spec.md` from `${SKILL_DIR}/assets/spec-template.md`:
51
60
  - focus on WHAT and WHY, not HOW;
61
+ - record the intent baseline and evidence status without turning recommendations into requirements;
52
62
  - include only relevant sections;
53
63
  - give every goal acceptance criteria;
54
- - mark genuine ambiguity with `[NEEDS CLARIFICATION]`.
64
+ - mark consequential ambiguity with `[NEEDS CLARIFICATION]`; retain low-risk unknowns as explicit assumptions when safe.
55
65
  4. For persistence changes, inspect existing schemas and add a Data Model section using project conventions.
56
66
  5. Resolve clarification markers:
57
- - interactive: use `${SKILL_DIR}/references/clarify-guide.md` and ask targeted questions;
58
- - non-interactive: choose conservative defaults, annotate them, and block when a safe default is impossible.
67
+ - interactive: use `${SKILL_DIR}/references/clarify-guide.md`; ask about consequential decisions and record safe low-risk assumptions without silently defaulting user intent;
68
+ - non-interactive: choose conservative defaults only when they are safe and reversible, annotate them, and block when a consequential decision has no safe default.
59
69
 
60
70
  Internal ID hygiene: PrizmKit IDs, task/session/run IDs, branch names, absolute worktree paths, and internal artifact paths may exist in change artifacts but must not leak into `.prizmkit/prizm-docs/`, product UI copy, API responses, emails, notifications, or expected user-visible test strings.
61
71
 
@@ -69,7 +79,8 @@ Precondition: `spec.md` exists with no unresolved blocker.
69
79
  - concise for small, well-scoped formal requirements;
70
80
  - comprehensive for multi-module, public API, data model, security, permission, payment, deployment-impacting, or ambiguous requirements.
71
81
  4. Generate `plan.md` from `${SKILL_DIR}/assets/plan-template.md` with:
72
- - change approach;
82
+ - change approach and goal/constraint traceability;
83
+ - decision rationale and alternatives only when materially different viable paths exist;
73
84
  - component and file changes;
74
85
  - data migration approach when relevant;
75
86
  - interface/API contract design when relevant;
@@ -1,7 +1,18 @@
1
1
  # Plan: [TITLE]
2
2
 
3
3
  ## Change Approach
4
- [Description of the technical approach — how these changes integrate with the existing system]
4
+ [Description of the minimum-sufficient technical approach — how these changes integrate with the existing system]
5
+
6
+ ## Decision Traceability
7
+ | Goal / Constraint / Existing Contract / Evidenced Risk | Design Response | Evidence Status and Rationale | Completion Evidence |
8
+ |---|---|---|---|
9
+ | [G-1 or constraint] | [Necessary design response] | [confirmed fact / inference / recommendation / assumption] | [Observable test or check] |
10
+
11
+ ## Alternatives and Decision Rationale
12
+ <!-- Include only when materially different viable paths exist. Do not manufacture alternatives to fill this section. Delete when not applicable. -->
13
+ - Selected approach: [Complete meaning and why it fits the confirmed intent]
14
+ - Material alternatives: [Alternative + meaningful trade-off]
15
+ - Reconsider when: [Constraint or evidence change that would alter the decision]
5
16
 
6
17
  ## Component Design
7
18
 
@@ -85,12 +96,16 @@
85
96
  - [ ] CI/CD pipeline update needed
86
97
 
87
98
  ## Pre-Implementation Gates
88
- - [ ] Spec coverage: all goals mapped to components
99
+ - [ ] Intent fidelity: goals, success outcome, scope, and non-goals match the confirmed requirement
100
+ - [ ] Evidence honesty: facts, inferences, recommendations, assumptions, and unknowns remain distinct
101
+ - [ ] Spec coverage: all goals mapped to components and observable completion evidence
102
+ - [ ] Design necessity: every component/task maps to a goal, confirmed constraint, existing contract, or evidenced risk
103
+ - [ ] Minimum sufficiency: unsupported future work and unjustified abstractions are absent
89
104
  - [ ] Data model reviewed — existing schema conventions documented and followed (if applicable)
90
105
  - [ ] All `[NEEDS CLARIFICATION]` items resolved
91
106
  - [ ] Testing approach agreed
92
107
  - [ ] Behavior preservation strategy defined (if modifying existing behavior)
93
- - [ ] Root cause confirmed with reproduction test design (if fixing a defect)
108
+ - [ ] Root cause is confirmed with evidence or explicitly retained as a bounded hypothesis/unknown with reproduction and investigation tasks (if fixing a defect)
94
109
 
95
110
  ## Tasks
96
111
 
@@ -3,6 +3,13 @@
3
3
  ## Overview
4
4
  [One paragraph describing the purpose and motivation]
5
5
 
6
+ ## Intent and Evidence
7
+ - Confirmed intent: [User goal and successful outcome, expressed by complete meaning]
8
+ - Confirmed facts: [Evidence-backed current state and constraints]
9
+ - Evidence-backed inferences: [Inference + supporting evidence; delete if none]
10
+ - Assumptions: [Low-risk, local, reversible assumptions + verification point; delete if none]
11
+ - Unknowns: [Consequential unknowns use `[NEEDS CLARIFICATION]`; non-blocking unknowns retain their evidence status]
12
+
6
13
  ## Goals
7
14
 
8
15
  ### G-1: [Goal Title]
@@ -29,10 +36,12 @@
29
36
  - [Existing test suites that must continue to pass]
30
37
 
31
38
  ## Root Cause
32
- <!-- Include this section when the task is fixing a defect. Delete if not applicable. -->
39
+ <!-- Include this section when the task is fixing a defect. Delete if not applicable. Do not invent a root cause merely to complete the template. -->
33
40
  - Error classification: [Runtime / Network / Auth / Data / Logic / Config / External]
34
- - Root cause: [specific code location and mechanism]
35
- - Affected files: [file list with line numbers]
41
+ - Root-cause status: [confirmed / evidence-backed hypothesis / unknown]
42
+ - Root cause or hypothesis: [specific mechanism when supported; otherwise state the bounded investigation question]
43
+ - Evidence: [reproduction, failing test, trace, source observation, or other concrete basis]
44
+ - Affected files: [evidence-backed file list with purpose; use unknown when not established]
36
45
  - Impact: [blast radius — which modules / features are affected]
37
46
 
38
47
  ## Dependencies
@@ -62,7 +71,8 @@
62
71
  - [Constraint 1]
63
72
 
64
73
  ## Clarifications
65
- [NEEDS CLARIFICATION]: [Ambiguous item]
74
+ <!-- Use markers only for consequential ambiguity. Keep safe low-risk assumptions in Intent and Evidence instead of turning every uncertainty into a question. -->
75
+ [NEEDS CLARIFICATION]: [Decision, materially different outcomes, and why confirmation is required]
66
76
 
67
77
  ## Review Checklist
68
78
  - [ ] All goals have acceptance criteria
@@ -70,4 +80,6 @@
70
80
  - [ ] Dependencies are identified
71
81
  - [ ] No implementation details (WHAT not HOW)
72
82
  - [ ] Behavior preservation defined (if modifying existing behavior)
73
- - [ ] Root cause identified with evidence (if fixing a defect)
83
+ - [ ] Root cause is evidence-backed or explicitly labeled as hypothesis/unknown (if fixing a defect)
84
+ - [ ] Facts, inferences, recommendations, assumptions, and unknowns are not conflated
85
+ - [ ] Every goal has observable completion evidence and no scope item lacks a requirement or confirmed constraint
@@ -6,35 +6,36 @@ Invoked automatically during `/prizmkit-plan` Phase 0 (specify) when `[NEEDS CLA
6
6
 
7
7
  ## Question Strategy
8
8
 
9
- **Ask one question at a time.** Batching questions produces lower-quality answers.
9
+ Classify each uncertainty before asking:
10
10
 
11
- For each question:
12
- 1. Cite the exact location in spec.md (e.g., "§Goals G-1 says..." or "§Scope says...")
13
- 2. State what is ambiguous and why it matters for implementation
14
- 3. Provide a **recommended answer** with rationale — gives the user a concrete starting point to accept, modify, or reject
11
+ - **Consequential ambiguity** — different answers materially change the goal, external behavior, scope, compatibility, safety, cost, data, or an irreversible decision. Ask the user and keep `[NEEDS CLARIFICATION]` until resolved.
12
+ - **Evidence-resolvable uncertainty** — project docs, source, schemas, or existing contracts determine the answer. Inspect the bounded evidence and record the confirmed fact instead of asking.
13
+ - **Low-risk assumption** — the choice is local, reversible, and does not alter user-visible intent. Record the assumption and its verification point; let the user override it without blocking progress.
15
14
 
16
- **Prioritize by implementation impact** (highest first):
17
- 1. Data model (entities, relationships, field types, constraints, naming) — **hardest to change after code is written**
18
- 2. Functional scope boundaries
19
- 3. UX flow and error handling
20
- 4. Non-functional requirements (performance, security)
21
- 5. Edge cases and integration points
15
+ For each question or tightly related batch:
16
+ 1. Cite the exact location in `spec.md` (for example, "§Goals G-1" or "§Scope").
17
+ 2. State what is ambiguous, which outcomes differ, and why the decision is consequential.
18
+ 3. Provide an explicitly labeled **recommendation** with rationale when evidence supports one; it remains a recommendation until the user confirms it.
19
+ 4. Group questions that share one decision context. Ask sequentially only when one answer changes which later question is relevant.
20
+
21
+ Prioritize by consequence and reversibility, not by a universal domain order. Data integrity, safety, public contracts, and destructive migrations are commonly high impact; a data-model, UX, performance, or integration detail is consequential only when its alternatives materially change the requirement.
22
22
 
23
23
  ## Update Discipline
24
24
 
25
- After **each** user answer:
26
- - Immediately update `spec.md` (do not batch at the end)
27
- - Remove the resolved `[NEEDS CLARIFICATION]` marker
28
- - Re-evaluate for new ambiguities exposed by the answer
25
+ After each answer or related answer batch:
26
+ - Update `spec.md` with the complete selected meaning, not an answer token or conversation reference.
27
+ - Remove only the resolved `[NEEDS CLARIFICATION]` marker.
28
+ - Reclassify newly exposed uncertainty as consequential, evidence-resolvable, or a low-risk assumption.
29
29
 
30
- ## No Limits Policy
30
+ ## Convergence Policy
31
31
 
32
- **There is no cap on rounds or questions.** Keep asking until:
33
- - All `[NEEDS CLARIFICATION]` markers are removed, AND
34
- - No vague or underspecified areas remain, AND
35
- - You are fully confident about the requirements
32
+ Use no arbitrary target number of questions. Clarification converges when:
33
+ - no consequential `[NEEDS CLARIFICATION]` marker remains;
34
+ - confirmed facts, recommendations, assumptions, and unknowns are not conflated;
35
+ - unresolved low-risk assumptions are explicit and have a verification point; and
36
+ - the acceptance criteria let a fresh implementation session determine completion.
36
37
 
37
- If the user's answer raises new questions — ask those too. If a previously-resolved item needs revisiting due to new context — go back.
38
+ Do not keep questioning merely to reach subjective "full confidence" or specify low-level implementation choices that the plan can safely leave to implementation. If a user answer creates a new consequential conflict, surface that conflict and ask; otherwise preserve the uncertainty with its correct evidence status.
38
39
 
39
40
  ## Early Termination
40
41
 
@@ -62,6 +63,7 @@ If the user says "done", "stop", or "enough" — end immediately and output a su
62
63
 
63
64
  ## Guidelines
64
65
 
65
- - Stay at WHAT/WHY level — no implementation details (HOW) in spec
66
- - If an answer contradicts an existing requirement, surface the conflict and ask which takes precedence
67
- - If the user seems fatigued: "I have N more questions — continue now or later?" — but never silently stop with unresolved ambiguities
66
+ - Stay at WHAT/WHY level — no implementation details (HOW) in spec.
67
+ - If an answer contradicts an existing requirement, surface the conflict and ask which takes precedence.
68
+ - Do not present a project default or general best practice as confirmed user intent.
69
+ - If the user seems fatigued, summarize the remaining consequential decisions and offer to continue now or save them as explicit blockers; do not silently default them.
@@ -4,7 +4,7 @@
4
4
 
5
5
  Run this local planning-quality gate after `spec.md` and `plan.md` are drafted or updated, before returning `PLAN_READY`.
6
6
 
7
- This is not a separate skill and it does not use a Critic agent. It is the mandatory Main-Agent baseline executed inside `prizmkit-plan` to improve the planning artifacts only. Its maximum of two local rounds remains independent of the optional Reviewer described in `independent-plan-review.md`.
7
+ This mandatory Main-Agent baseline runs inside `prizmkit-plan` to improve the planning artifacts only. Its maximum of two local rounds remains independent of the optional Reviewer described in `independent-plan-review.md`.
8
8
 
9
9
  ## Non-Goals
10
10
 
@@ -13,7 +13,6 @@ Do not do any of the following from this guide:
13
13
  - Start implementation or edit product/source code.
14
14
  - Run tests, builds, lint, or package commands.
15
15
  - Start implementation or any other execution process.
16
- - Spawn or require a Critic agent inside this Main-Agent loop. The separate optional independent review is considered only after this loop converges and only through `independent-plan-review.md`.
17
16
  - Create a separate review-loop skill.
18
17
  - Expand scope beyond improving `spec.md` and `plan.md`.
19
18
 
@@ -31,13 +30,16 @@ Review both artifacts against these dimensions:
31
30
 
32
31
  | Dimension | Check |
33
32
  |---|---|
34
- | Ambiguity | Requirements, scope, terms, or expected behavior are unclear or internally inconsistent. |
33
+ | Intent fidelity | Goals, success outcomes, scope, non-goals, and constraint precedence preserve confirmed user meaning instead of substituting AI preferences or generic best practices. |
34
+ | Evidence status | Confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns remain distinct; consequential choices are not silently defaulted. |
35
+ | Ambiguity | Consequential requirements, scope, terms, or expected behavior are unclear or internally inconsistent; low-risk reversible assumptions are explicit rather than over-questioned. |
35
36
  | Acceptance criteria completeness | Each goal has verifiable acceptance criteria; edge/error cases are included when meaningful. |
36
37
  | Missing constraints | Security, data, compatibility, performance, platform, deployment, migration, or non-goal constraints are absent where relevant. |
37
38
  | Task ordering errors | Tasks are sequenced before their prerequisites, checkpoints are misplaced, or dependency order is unsafe. |
38
39
  | Dependency assumptions | The plan assumes missing APIs, schemas, files, services, packages, auth, environment variables, or generated artifacts without evidence. |
39
40
  | Scope drift | The plan adds unrelated work, backlog items, nice-to-haves, or implementation beyond the spec. |
40
- | Overengineering | The plan introduces abstractions, services, agents, workflows, data stores, or cross-module rewrites that the spec does not justify. |
41
+ | Overengineering | The plan introduces abstractions, services, agents, workflows, data stores, cross-module rewrites, or speculative future work that no goal, confirmed constraint, existing contract, or evidenced risk justifies. |
42
+ | Decision traceability | Every design element has a justified source and every goal maps to observable completion evidence; material alternatives are compared only when genuine viable paths exist. |
41
43
  | Implementation readiness | Tasks are actionable, file-scoped when possible, testable, and resumable; blockers are explicit. |
42
44
  | Source-reading overhead | The implementation plan avoids broad rereads and identifies the minimum context/files needed for execution. |
43
45
 
@@ -87,7 +89,7 @@ Optional findings do not block planning completion.
87
89
  4. Do not apply `OPTIONAL` findings unless they clearly improve readiness without expanding scope.
88
90
  5. If any fixes were applied, rerun this review once.
89
91
  6. Stop after at most 2 total review rounds.
90
- 7. If unresolved `BLOCKER` findings remain after the final round, stop planning and ask targeted clarification questions. Do not escalate from this loop to a Critic agent or treat independent review as blocker recovery.
92
+ 7. If unresolved `BLOCKER` findings remain after the final round, stop planning and ask targeted clarification questions. Do not treat independent review as blocker recovery.
91
93
  8. If no unresolved blockers remain, report that the mandatory Main-Agent planning quality gate passed and hand off to the optional independent Plan review boundary in `independent-plan-review.md`.
92
94
 
93
95
  ## Output Summary
@@ -4,9 +4,16 @@ Run this checklist after generating the Tasks section in plan.md. Fix any issues
4
4
 
5
5
  ---
6
6
 
7
+ ## Intent and Evidence
8
+
9
+ - [ ] Confirmed goals, successful outcomes, scope, non-goals, and explicit constraints preserve the user's meaning without adding AI preferences as requirements
10
+ - [ ] Confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns are labeled distinctly
11
+ - [ ] No consequential decision was silently defaulted in an interactive plan
12
+ - [ ] Low-risk assumptions are local, reversible, disclosed, and paired with a verification point
13
+
7
14
  ## Coverage
8
15
 
9
- - [ ] Every goal (G-N) in spec.md has at least one task in plan.md
16
+ - [ ] Every goal (G-N) in spec.md has at least one task in plan.md and observable completion evidence
10
17
  - [ ] Every task has a target file path (`— file: path/to/file`)
11
18
  - [ ] Risk assessment contains at least one concrete risk with a mitigation plan
12
19
  - [ ] The plan contains at least one verification checkpoint; a small plan may use one final checkpoint
@@ -18,15 +25,17 @@ Run this checklist after generating the Tasks section in plan.md. Fix any issues
18
25
  - [ ] No near-duplicate requirements exist across spec.md sections (same intent, different wording)
19
26
  - [ ] If duplicates found, consolidate to the clearer phrasing and remove the other
20
27
 
21
- ## Orphan Detection
28
+ ## Orphan and Design-Necessity Detection
22
29
 
23
- - [ ] No task exists without a mapped goal (orphan task)
24
- - [ ] No plan component exists without a corresponding spec requirement
30
+ - [ ] No task exists without a mapped goal, confirmed constraint, existing contract, or evidenced risk
31
+ - [ ] No plan component exists without a corresponding requirement or justified preservation obligation
32
+ - [ ] No speculative future feature, abstraction, infrastructure component, or cleanup expands the confirmed scope
25
33
 
26
34
  ## Ambiguity Scan
27
35
 
28
- - [ ] No unresolved `[NEEDS CLARIFICATION]`, TBD, TODO, or `???` markers remain
29
- - [ ] No vague criteria without measurable thresholds (e.g., "fast", "secure", "scalable", "intuitive" — replace with concrete numbers or conditions)
36
+ - [ ] No consequential `[NEEDS CLARIFICATION]`, TBD, TODO, or `???` marker remains
37
+ - [ ] Non-blocking unknowns and low-risk assumptions retain their evidence status instead of being presented as facts
38
+ - [ ] No vague criterion uses a measurable threshold unless that threshold is confirmed or supported by project evidence; otherwise clarify the observable condition
30
39
 
31
40
  ## Terminology Consistency
32
41
 
@@ -592,7 +592,7 @@ HIERARCHY RULE: if directory X lives inside top-level module M, X is a sub-modul
592
592
 
593
593
  CAPACITY RULE: use MODULE_GROUPS whenever MODULE_INDEX cannot fit L0 within 4096B. Do not change hard limits for project size. Init does not create semantic or mirrored L2 placeholders; later Update/Rebuild/Migrate may create complete L2 documents when durable knowledge and unambiguous identity exist.
594
594
 
595
- EXCLUDE: .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .codex/, .agents/, .pi/, .prizmkit/
595
+ EXCLUDE: .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .codex/, .agents/, .pi/, .cursor/, .prizmkit/
596
596
  SOURCE_BOUNDARY: Excluding `.prizmkit/` excludes the installed Runtime at `.prizmkit/dev-pipeline/`; never exclude a repository's canonical top-level `dev-pipeline/` source module by basename.
597
597
 
598
598
  ## 9.2 Post-Init Behavior
@@ -11,7 +11,7 @@ STEPS:
11
11
  - TOP-LEVEL modules: directories directly under project root (or under src/ for src-based layouts) that qualify.
12
12
  - SUB-MODULES: directories INSIDE a top-level module that qualify. Record them as source structure in the direct-child parent L1; if durable L2 is created later, its nested path mirrors the sub-module.
13
13
  - HIERARCHY RULE: exact `root.prizm` is L0; top-level module M maps to direct-child `.prizmkit/prizm-docs/<M>.prizm` (L1); directory X inside M maps to nested `.prizmkit/prizm-docs/<M>/<X>.prizm` (L2). Deeper source ownership remains L2 and never creates L3.
14
- - Exclude .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .codex/, .agents/, .pi/, and the complete `.prizmkit/` framework directory. This excludes installed `.prizmkit/dev-pipeline/` artifacts but never excludes a repository's canonical top-level `dev-pipeline/` source module by basename. If total module count > 30, ask user for include/exclude patterns.
14
+ - Exclude .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .codex/, .agents/, .pi/, .cursor/, and the complete `.prizmkit/` framework directory. This excludes installed `.prizmkit/dev-pipeline/` artifacts but never excludes a repository's canonical top-level `dev-pipeline/` source module by basename. If total module count > 30, ask user for include/exclude patterns.
15
15
  3. Apply the Value Gate from SKILL.md and the format specification to every metadata, rule, pattern, dependency, file, and summary candidate. Keep navigational structure only when needed to locate ownership. Reject source-derivable signatures, history, test inventories, temporary conclusions, stale/duplicate meanings, procedures, and low-value file lists.
16
16
  4. Create `.prizmkit/prizm-docs/` and only the mirrored directories needed by documents that will exist. Do not create placeholder detail files.
17
17
  5. Generate `root.prizm` (L0) with concise PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY, navigation pointers, and only Value-Gate-qualified global RULES/PATTERNS/CROSS_CUTTING facts. Set `PRIZM_VERSION: 4`. Keep L0 a summary/pointer map; never copy child interfaces, data flow, traps, decisions, or full rules. No CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths.
@@ -11,6 +11,15 @@ Plan executable refactoring items for later autonomous dev-pipeline execution. T
11
11
 
12
12
  Always produce a validated `.prizmkit/plans/refactor-list.json` that conforms to `dev-pipeline-refactor-list-v1`.
13
13
 
14
+ ## Intent-Aligned Planning Policy
15
+
16
+ Before proposing or finalizing refactor contracts:
17
+ 1. Establish the **intent baseline**: confirmed structural goal, preserved behavior, scope/non-goals, and explicit constraints. User requirements and confirmed decisions outrank AI preferences or general best practices; never silently violate safety, legal/privacy/data-integrity obligations, or verified existing contracts. Surface material conflicts instead.
18
+ 2. Maintain **evidence status**: distinguish confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns. Never present an inferred target architecture or scope expansion as confirmed user intent.
19
+ 3. **Clarify by decision impact**. Ask before choices that materially change target structure, public contracts, behavior preservation, scope, compatibility, safety, cost, or irreversible migration state. Resolve from project evidence first; for low-risk, local, and reversible details, record a disclosed assumption instead of interrupting.
20
+ 4. Explore alternatives only when **materially different viable paths** exist. Compare meaningful architectural trade-offs without manufacturing an option count or applying a universal pattern.
21
+ 5. Produce a **minimum-sufficient** refactor contract: every operation maps to a confirmed structural goal, constraint, existing contract, or evidenced risk, and every preservation goal maps to observable completion evidence of equivalence. Defer unrelated cleanup and speculative redesign.
22
+
14
23
  ## Invocation Commitment (Hard Rule)
15
24
 
16
25
  **When the user invokes `/refactor-planner`, you MUST execute the refactor-planner workflow.** You must NEVER:
@@ -52,7 +61,7 @@ Every new or changed refactor item is an executable contract for a fresh AI sess
52
61
  1. **Self-contained contract**: The item's `description` and `acceptance_criteria`, read together, MUST define the objective, current state, desired target architecture, selected decisions, scope boundaries, constraints, non-goals, relevant integrations and consumers, edge cases, behavior-preservation decisions, and completion evidence. Preserve substantive user requirements at matching detail.
53
62
  2. **Supplementary evidence only**: `user_context` is supplementary evidence only. It may contain scoped exact excerpts and purpose-tagged references, but it MUST NOT expand, replace, or contradict the contract. If `user_context` were removed, a fresh refactor session must still know the current structure, target architecture, allowed scope, forbidden changes, preservation strategy, and verification evidence.
54
63
  3. **Purposeful scope**: Every path in `scope.files` and every related path reference must be a purpose-tagged target path in the task contract or supplementary evidence, stating what to inspect or change. The scope array may remain schema-compatible path strings, while `description` explains each path or coherent path group's role.
55
- 4. **Clarify, do not guess**: Ask the user for clarification whenever target architecture, scope boundaries, preservation behavior, material applicability, or a relative reference has multiple plausible meanings.
64
+ 4. **Clarify by impact, do not guess**: Ask when multiple meanings of target architecture, scope boundaries, preservation behavior, material applicability, or relative references would materially change the refactor contract. Keep AI-proposed architecture labeled as a recommendation until confirmed; retain low-risk reversible implementation details as explicit assumptions when safe.
56
65
  5. **Item isolation**: Each refactor contract and its supplementary evidence contain only relevant goals, paths, constraints, desired end state, and preservation evidence.
57
66
 
58
67
  ### Artifact-Wide AI Readability
@@ -213,14 +222,14 @@ Support 4 input formats (users may mix formats):
213
222
  > "There's a circular dependency between auth and user modules"
214
223
  > "The database layer is tightly coupled to the HTTP layer"
215
224
 
216
- For each input, ask clarifying questions:
217
- - What is the specific target (files, modules, patterns), and what should the execution AI inspect at each purpose-tagged target path?
218
- - What is the complete desired target architecture or end state?
219
- - What are the scope boundaries and non-goals (must preserve API, must not touch certain files, rejected architecture that must stay rejected)?
220
- - Which behavior-preservation decisions and completion evidence prove the refactor is safe?
221
- - What is the motivation (maintainability, performance, testability)?
225
+ For each input, establish:
226
+ - The confirmed structural pain point and desired outcome.
227
+ - Evidence-backed target files, modules, patterns, consumers, and purpose-tagged inspection paths.
228
+ - Behavior invariants, public contracts, scope boundaries, and non-goals.
229
+ - Behavior-preservation and completion evidence.
230
+ - Motivation and constraints that determine whether a target architecture is necessary.
222
231
 
223
- Continue collecting goals until the user says they're done. There is no limit on rounds.
232
+ If the user has not selected a target architecture, inspect the code first and present a recommendation or meaningful alternatives only when materially different viable paths exist. Ask about consequential structure/scope/preservation decisions; group related questions and retain safe low-risk reversible details as explicit assumptions. Continue until the user indicates no additional goals and no consequential ambiguity remains.
224
233
 
225
234
  **CHECKPOINT CP-RP-1**: All refactoring goals collected and understood.
226
235
 
@@ -335,7 +344,7 @@ Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the sin
335
344
 
336
345
  ## Verification Defaults
337
346
 
338
- Set behavior-preservation and testing expectations for each refactor item. Do not generate retired review-agent configuration fields.
347
+ Set behavior-preservation and testing expectations for each refactor item.
339
348
 
340
349
  | Priority | Complexity | Verification expectation |
341
350
  |----------|-----------|--------------------------|
@@ -344,8 +353,6 @@ Set behavior-preservation and testing expectations for each refactor item. Do no
344
353
  | high | high | Scoped tests for changed boundaries plus review gate |
345
354
  | other combinations | any | Smallest meaningful behavior-preservation check |
346
355
 
347
- Never emit `critic` or `critic_count`; those fields are fully removed and validators reject them.
348
-
349
356
  ---
350
357
 
351
358
  ## Fast Path
@@ -29,6 +29,9 @@ Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whethe
29
29
 
30
30
  For every reviewed refactor entry, check:
31
31
 
32
+ - Intent fidelity: confirmed structural outcome, behavior invariants, scope, non-goals, and constraints preserve user intent rather than an AI-selected architecture
33
+ - 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
34
+ - 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
32
35
  - Schema compatibility with `dev-pipeline-refactor-list-v1` and `.prizmkit/dev-pipeline/templates/refactor-list-schema.json`
33
36
  - Dependency/DAG soundness, including safe behavior-preserving order
34
37
  - 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
@@ -45,14 +48,15 @@ For every reviewed refactor entry, check:
45
48
 
46
49
  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:
47
50
 
48
- 1. What exact problem or outcome is this task responsible for?
49
- 2. What current architecture exists and what target architecture must replace it?
51
+ 1. What exact confirmed structural problem or outcome is this task responsible for, and how does it preserve the intent baseline?
52
+ 2. What current architecture exists according to evidence, which target statements are confirmed versus recommended/assumed, and what target architecture must replace it?
50
53
  3. Which approach was selected, expressed by meaning rather than an option label?
51
54
  4. What scope boundaries, constraints, and non-goals must be preserved?
52
55
  5. Why is each reference material and target path relevant?
53
56
  6. How can completion and behavior preservation be verified?
54
57
  7. Does any phrase require an unseen earlier question, recommendation, or option list?
55
58
  8. Do quoted source materials agree with the final task decision?
59
+ 9. Does every operation have a confirmed structural goal, behavior invariant, existing contract, or evidenced risk, with no unrelated cleanup or speculative redesign?
56
60
 
57
61
  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.
58
62