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
@@ -90,11 +90,13 @@ Use these tables to guide tech stack selection based on project requirements.
90
90
 
91
91
  ### Selection Heuristics
92
92
 
93
- - If the user has no strong preference, default to **Next.js + PostgreSQL + shadcn/ui + Tailwind CSS** as a general-purpose stack.
94
- - If the project involves ML/AI backends, prefer **FastAPI** on the backend.
95
- - If the project requires high concurrency with minimal resource usage, consider **Go**.
96
- - If rapid prototyping is the goal, consider **SQLite** initially with a migration path to PostgreSQL.
97
- - Always ask about deployment preferences (Vercel, AWS, self-hosted) as this influences framework choice.
93
+ Treat the matrices as comparison aids, not a universal stack prescription:
94
+
95
+ - Preserve an existing supported stack unless confirmed goals or evidence justify migration.
96
+ - When the user has no strong preference, compare only options that fit the product outcome, team capability, delivery horizon, deployment environment, operational ownership, and verified project conventions. Recommend one with explicit rationale; do not apply a universal default stack.
97
+ - Consider FastAPI for an ML/AI backend, Go for evidenced high-concurrency/resource constraints, or SQLite for a bounded prototype only when those conditions are confirmed and the trade-offs fit the intent.
98
+ - Ask about deployment when it materially constrains framework, data, cost, compliance, or operations. Otherwise record deployment as explicitly deferred rather than forcing a premature decision.
99
+ - Keep recommendations distinct from confirmed user decisions and state what evidence change would cause the recommendation to be reconsidered.
98
100
 
99
101
 
100
102
 
@@ -15,8 +15,7 @@ Evaluate the user's initial goal statement:
15
15
  - **Vague** — Direction exists but needs narrowing (e.g., "improve security")
16
16
  - **Exploring** — No firm goal yet, just a direction (e.g., "something with auth")
17
17
 
18
- If **vague** or **exploring**, ask follow-up questions to sharpen the goal.
19
- Do NOT proceed until there is a concrete, testable problem statement (one sentence).
18
+ If **vague** or **exploring**, ask about ambiguity that changes the problem, beneficiary, success outcome, or scope. Resolve evidence-backed facts from available context and disclose low-risk assumptions. Do not proceed until there is a concrete, testable problem statement, but do not interrogate implementation details that are not needed to define the problem.
20
19
 
21
20
  ### Phase B: Understand the Idea
22
21
 
@@ -27,20 +26,13 @@ Answer these questions (use codebase exploration as needed):
27
26
  3. **What exists today?** — Current state, prior art in the codebase, adjacent systems.
28
27
  4. **What constraints matter?** — Performance, compatibility, security, timeline.
29
28
 
30
- Non-functional requirements to explicitly clarify or propose defaults for:
31
- - Performance expectations
32
- - Scale (users, data, traffic)
33
- - Security or privacy constraints
34
- - Reliability / availability needs
35
- - Maintenance and ownership expectations
29
+ Consider non-functional dimensions only when they materially affect the app decision: performance, scale, security/privacy, reliability, maintenance, ownership, cost, or another domain-specific constraint. Use project evidence first. If a relevant low-risk value remains unknown, propose and clearly mark a reversible **assumption**; if different answers materially change the product or architecture, ask the user.
36
30
 
37
- If the user is unsure on any point, propose reasonable defaults and clearly mark them as **assumptions**.
38
-
39
- Summarize findings before moving on. If anything is unclear, ask.
31
+ Summarize confirmed facts, evidence-backed inferences, recommendations, assumptions, and consequential unknowns before moving on.
40
32
 
41
33
  ### Phase C: Explore Approaches
42
34
 
43
- Generate **2-3 distinct approaches**. For each:
35
+ First determine whether materially different viable paths exist. If they do, generate the smallest useful comparison—usually 2-3 approaches, but never manufacture options to satisfy a count. If one evidence-supported path remains, explain why alternatives are not materially viable and proceed with that path. For each compared approach:
44
36
 
45
37
  - **Name** — Short label (e.g., "JWT middleware", "OAuth proxy")
46
38
  - **How it works** — 2-3 sentences
@@ -59,9 +51,9 @@ Before asking the user to choose, stress-test each approach using the red team c
59
51
  4. Who disagrees?
60
52
 
61
53
  Mark any approach that fails 2+ red team questions as **HIGH RISK**.
62
- If all approaches fail, generate a hybrid addressing the weaknesses.
54
+ If every viable approach is high risk, reconsider the problem or generate a hybrid that addresses the evidenced weaknesses.
63
55
 
64
- Present the comparison and let the user pick an approach or request a hybrid.
56
+ Present only meaningful choices. Ask the user to select when the choice materially affects product intent, architecture, cost, compatibility, or another consequential outcome; otherwise record the evidence-supported recommendation as a disclosed, reversible assumption.
65
57
 
66
58
  ### Phase D: Capture Design
67
59
 
@@ -72,7 +64,7 @@ Produce a structured summary:
72
64
  [One sentence, testable]
73
65
 
74
66
  ## Approaches Considered
75
- [2-3 approaches with pros/cons/effort]
67
+ [Material alternatives with pros/cons/effort, or why only one viable path remained]
76
68
 
77
69
  ## Selected Approach
78
70
  [Complete selected approach and rationale, written as standalone design context without answer tokens or dialogue provenance]
@@ -93,9 +85,9 @@ This summary becomes the input for the next phase (specification or planning).
93
85
 
94
86
  ## Rules
95
87
 
96
- - Ask as many questions as needed — no rushing
97
- - One topic at a time for complex clarifications
98
- - Prefer multiple-choice questions when possible
99
- - Assumptions must be explicit, never silent
100
- - YAGNI ruthlessly — avoid premature complexity
101
- - Do NOT implement, code, or modify behavior during brainstorming
88
+ - Clarify consequential uncertainty; do not ask merely to remove every unknown.
89
+ - Group related questions when one answer does not depend on another; sequence only dependent decisions.
90
+ - Prefer selectable options for material choices when possible.
91
+ - Keep confirmed facts, inferences, recommendations, assumptions, and unknowns distinct.
92
+ - Apply YAGNI ruthlessly: every selected design element must map to the intent baseline, a confirmed constraint, an existing contract, or an evidenced risk.
93
+ - Do NOT implement, code, or modify behavior during brainstorming.
@@ -40,6 +40,9 @@ Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whethe
40
40
 
41
41
  For every reviewed app-planning artifact or section, check:
42
42
 
43
+ - Intent fidelity and constraint precedence: the selected product outcome, success meaning, scope, non-goals, and project constraints preserve confirmed user intent rather than AI preferences or generic best practices
44
+ - Evidence status honesty: confirmed facts, evidence-backed inferences, recommendations, assumptions, deferrals, and unknowns remain distinct; no consequential project decision is silently defaulted
45
+ - Design necessity and traceability: every app-level decision maps to a confirmed goal, constraint, existing contract, or evidenced risk, and unsupported future complexity is absent
43
46
  - Project brief completeness: goal, users, differentiators, constraints, tech stack assumptions, and at least three actionable ideas when producing a final brief
44
47
  - Consistency among conventions, infrastructure, architecture decisions, and project brief content
45
48
  - Infrastructure completeness or explicit deferral for database, deployment, and cloud services topics when those flows ran
@@ -57,14 +60,15 @@ For every reviewed app-planning artifact or section, check:
57
60
 
58
61
  Repeat the pre-generation simulation for every reviewed new or changed app-planning line or section 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:
59
62
 
60
- 1. What exact product outcome or technical decision does this content record?
61
- 2. What exists today and what desired state or constraint applies?
63
+ 1. What exact confirmed product outcome or technical decision does this content record, and how does it preserve the intent baseline?
64
+ 2. What exists today, which statements are facts versus assumptions/recommendations, and what desired state or constraint applies?
62
65
  3. Which approach was selected, expressed by meaning rather than an option label?
63
66
  4. What constraints and non-goals must downstream work preserve?
64
67
  5. Why is each reference material relevant?
65
68
  6. How will downstream planning or implementation know the decision was honored?
66
69
  7. Does any phrase require an unseen earlier question, recommendation, or option list?
67
70
  8. Do quoted source materials agree with the final task decision?
71
+ 9. Is every included decision necessary for a confirmed goal, constraint, existing contract, or evidenced risk, with no speculative future design?
68
72
 
69
73
  Return `NEEDS_FIXES` if any answer is missing, ambiguous, 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. Ask the user for clarification when there is not one provable antecedent. 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 durable artifact, which must not depend on that source file still existing.
70
74
 
@@ -7,6 +7,15 @@ description: "Interactive bug planning that produces, validates, appends, and su
7
7
 
8
8
  Interactive planning skill that creates, updates, validates, and summarizes the standardized `.prizmkit/plans/bug-fix-list.json` for later autonomous bug-fix execution. It never fixes source code.
9
9
 
10
+ ## Intent-Aligned Planning Policy
11
+
12
+ Before proposing or finalizing bug contracts:
13
+ 1. Establish the **intent baseline**: confirmed actual behavior, expected 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.
14
+ 2. Maintain **evidence status**: distinguish confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns. Never present a suspected root cause, code location, or fix approach as confirmed user intent.
15
+ 3. **Clarify by decision impact**. Ask before choices that materially change expected behavior, scope, compatibility, safety, severity, verification, cost, or irreversible state. Resolve from project evidence first; for low-risk, local, and reversible details, record a disclosed assumption instead of interrupting.
16
+ 4. Explore alternatives only when **materially different viable paths** affect the behavioral contract. Compare meaningful trade-offs without manufacturing an option count or prescribing an unverified fix.
17
+ 5. Produce a **minimum-sufficient** bug contract: every requirement maps to confirmed behavior, a constraint, existing contract, or evidenced risk, and every expected outcome maps to observable completion evidence. Defer speculative cleanup and unsupported future work.
18
+
10
19
  ## Invocation Commitment (Hard Rule)
11
20
 
12
21
  When the user invokes `/bug-planner`, you MUST execute the bug-planner workflow. You must NEVER:
@@ -47,7 +56,7 @@ Every new or changed bug is an executable contract for a fresh AI session that h
47
56
  1. **Self-contained contract**: The bug's `description` and `acceptance_criteria`, read together, MUST define the objective, current state and actual behavior, desired state and expected behavior, selected scope and decisions, severity rationale, constraints, non-goals, relevant integrations, edge cases, reproduction conditions, verification decisions, and completion evidence. Because no separate rationale field is added, include the durable severity rationale in `description`. Preserve user requirements at matching detail.
48
57
  2. **Supplementary evidence only**: `user_context` is supplementary evidence only. Logs, stack traces, screenshots, and source excerpts may support diagnosis, but they MUST NOT expand, replace, or contradict the contract. If `user_context` were removed, a fresh bug-fix session must still know what fails, where and when it fails, what correct behavior means, which scope was selected, and how to verify the fix.
49
58
  3. **Severity and verification are durable decisions**: Write the complete severity rationale, selected scope, environment, reproduction path, verification type, and verification decisions by meaning. Never store only an option label or conversational answer.
50
- 4. **Clarify, do not guess**: Ask the user for clarification whenever expected behavior, root-cause scope, material applicability, or a relative reference has multiple plausible meanings.
59
+ 4. **Clarify by impact, do not guess**: Expected behavior, selected behavioral scope, material applicability, and relative references require clarification when multiple meanings would materially change the contract. Root cause, code location, and fix approach may remain explicitly labeled as evidence-backed hypotheses or unknowns when the confirmed behavior and bounded investigation path are sufficient for execution.
51
60
  5. **Bug isolation**: Each bug contract and its supplementary evidence contain only material relevant to that bug. Repeat shared environment or constraints only when explicitly global.
52
61
 
53
62
  ### Artifact-Wide AI Readability
@@ -191,7 +200,7 @@ Gather project metadata from the project's own configuration and documentation
191
200
  - Auto-detect from project files (`package.json`, `requirements.txt`, `go.mod`, etc.)
192
201
  - If none found, ask the user
193
202
  3. **Identify testing framework**: Read from `.prizmkit/config.json` `tech_stack.testing`, or auto-detect from package.json/requirements.txt/etc., or ask user
194
- 4. **Clarify context** — if the project context, affected systems, or bug scope is unclear, ask questions one at a time (cite the unclear point, give a recommended answer with rationale) until you fully understand the environment. No limit on rounds or number of questions.
203
+ 4. **Clarify context by impact** — inspect project evidence first. Ask when ambiguity in the environment, affected systems, expected behavior, or scope would materially alter the bug contract; label recommendations as recommendations and group related questions unless one answer changes the next. Record low-risk reversible assumptions explicitly instead of questioning until subjective full understanding.
195
204
  5. **Collect reference materials** — **Upfront Material Detection (Hard Rule)**: If the user has already provided materials (file paths, URLs, rules, specifications, code snippets) in the same message that invoked this skill: (a) Acknowledge what was received: "I received the following materials: [list]"; (b) Read/fetch all provided materials immediately; (c) You MUST still ask: "Are there any additional materials you'd like to provide?"; (d) NEVER skip this collection step just because the user already provided some materials.
196
205
 
197
206
  If the user has NOT provided any materials upfront, explicitly ask whether they have any supplementary materials for you to review before proceeding to bug collection:
@@ -229,7 +238,7 @@ When parsing user input, auto-detect the format and read `${SKILL_DIR}/reference
229
238
  - Acceptance criteria (auto-suggest based on description, user can edit)
230
239
  - Model override (optional; if specified, overrides $MODEL env var for this bug fix)
231
240
 
232
- **Per-bug clarification** — if the bug's root cause, reproduction steps, current/actual behavior, desired/expected behavior, selected scope, severity rationale, verification decisions, non-goals, integration impact, edge cases, or evidence purpose is unclear, ask focused questions one at a time (cite the unclear point, give a recommended answer with rationale) until the bug is fully understood. Do not finalize shorthand that requires an unseen question, recommendation, or option list. No limit on the number of questions per bug.
241
+ **Per-bug clarification** — require confirmed current/actual behavior, desired/expected behavior, consequential scope, severity rationale, and verification decisions. Inspect evidence before asking, group related consequential questions, and label any root cause, code location, integration impact, or fix direction as confirmed, evidence-backed hypothesis, or unknown. A fresh execution session may investigate an unknown root cause; do not force certainty or invent a fix merely to finish planning. Do not finalize shorthand that requires an unseen question, recommendation, or option list.
233
242
 
234
243
  **Per-bug confirmation (mandatory)** — after extracting and clarifying each bug, present a structured summary using the template in `${SKILL_DIR}/assets/bug-confirmation-template.md`, then ask the three confirmation questions defined there.
235
244
 
@@ -288,7 +297,7 @@ Return `NEEDS_FIXES` whenever any answer is missing, ambiguous, or available onl
288
297
  - Description clearly states **expected** vs **actual** behavior (not just "X doesn't work")
289
298
  - Reproduction path is specific enough for the pipeline AI to locate the relevant code
290
299
  - If the bug involves user interaction, the trigger action is described (not just the symptom)
291
- - **Code location hints**: Where in the codebase should the AI look? (file paths, module names, function names)
300
+ - **Code location guidance**: Provide evidence-backed file/module/function hints when known; otherwise state the bounded discovery target and mark the exact location unknown rather than inventing one
292
301
  - **Verification method**: How should the AI verify the fix? (run specific test, check specific behavior)
293
302
  - Bad: "Login is broken" — too vague, AI will search the entire codebase
294
303
  - Good: "Login form at /login returns 500 when password field is empty. Expected: validation error 400. Root cause likely in src/api/auth.ts POST /api/auth/login handler — missing null check on password field."
@@ -444,7 +453,6 @@ Key points:
444
453
  - Critical/high severity bugs require clear automated, manual, or hybrid verification evidence.
445
454
  - Medium/low severity bugs use the smallest verification that proves the fix and guards against regression.
446
455
  - `browser_interaction` is supported for UI-reproducible bugs; `verification_type` still declares whether verification is automated, manual, or hybrid.
447
- - Do not generate `critic` or `critic_count`; those fields are fully removed and validators reject them.
448
456
 
449
457
  ---
450
458
 
@@ -10,22 +10,26 @@ Present this after extracting and clarifying each bug:
10
10
  │ Description: <expected vs actual behavior>
11
11
  │ Severity: <auto-classified> | Verification: <type>
12
12
  │
13
- │ Reproduction: <steps if available, or "not provided">
14
- │ Affected: <module/feature or "unknown">
13
+ │ Reproduction: <confirmed steps/evidence, or "unknown — bounded discovery required">
14
+ │ Affected: <evidence-backed module/feature, or "unknown">
15
+ │ Root Cause: <confirmed / evidence-backed hypothesis / unknown> — <basis or investigation boundary>
15
16
  │
16
17
  │ Acceptance Criteria (fix verified when):
17
18
  │ 1. <criterion — specific enough for automated pipeline to verify>
18
19
  │ 2. <criterion>
19
20
  │
20
- │ Open Questions:
21
- │ - <any unclear points, or "None">
21
+ │ Evidence Status:
22
+ │ - Confirmed facts: <actual/expected behavior and evidence>
23
+ │ - Hypotheses/assumptions: <clearly labeled, or "None">
24
+ │ Open Consequential Questions:
25
+ │ - <decisions that materially change behavior/scope/verification, or "None">
22
26
  └────────────────────────────────────────────────────────
23
27
  ```
24
28
 
25
29
  Then ask three confirmation questions:
26
- 1. "Is the description accurate? Any corrections?"
27
- 2. "Need to add more details? (reproduction steps, environment, related code locations, etc.)"
28
- 3. "Are the acceptance criteria specific enough that the pipeline can autonomously verify the fix?"
30
+ 1. "Are the confirmed actual behavior, expected behavior, and selected scope accurate?"
31
+ 2. "Are the evidence, hypotheses, unknowns, and severity rationale labeled correctly?"
32
+ 3. "Are the acceptance criteria specific enough that the pipeline can autonomously verify the outcome without assuming a particular unproven fix?"
29
33
 
30
34
  Only finalize the bug entry after user confirms all three points.
31
35
 
@@ -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 bug entry, check:
31
31
 
32
+ - Intent fidelity: confirmed actual behavior, expected outcome, behavioral scope, non-goals, and verification preserve the user's meaning rather than an AI-selected fix
33
+ - Evidence status honesty: facts, evidence-backed inferences, recommendations, assumptions, and unknowns remain distinct; suspected root causes, code locations, and fix approaches are never presented as confirmed without evidence
34
+ - Minimum-sufficient scope: every requested change maps to confirmed behavior, an existing contract, constraint, or evidenced risk; speculative cleanup and unsupported future work are absent
32
35
  - Schema compatibility with `dev-pipeline-bug-fix-list-v1` and `.prizmkit/dev-pipeline/templates/bug-fix-list-schema.json`
33
36
  - Dependency/DAG consistency, duplicate handling, and root-cause overlap
34
37
  - Description completeness: objective, current/actual behavior, desired/expected behavior, selected scope, reproduction path, code-location hints, affected environment, relevant integrations, constraints, non-goals, edge cases, verification decisions, completion evidence, and headless execution readiness
@@ -45,14 +48,15 @@ For every reviewed bug entry, check:
45
48
 
46
49
  Repeat the pre-generation simulation for every reviewed new or changed bug 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 exists today and what must change from actual to expected behavior?
50
- 3. Which fix scope and verification approach were selected, expressed by meaning rather than an option label?
51
+ 1. What exact confirmed problem or outcome is this task responsible for?
52
+ 2. What exists today, what must change from actual to expected behavior, and which statements are confirmed versus hypothesized?
53
+ 3. Which behavioral fix scope and verification approach were selected, expressed by meaning rather than an option label, without prescribing an unproven implementation?
51
54
  4. What constraints and non-goals must be preserved?
52
55
  5. Why is each reference material relevant?
53
56
  6. How can completion 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. Is every requested change necessary for confirmed behavior, a constraint, existing contract, or evidenced risk, with no speculative cleanup?
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 bug 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 and evidence excerpt 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
 
@@ -25,5 +25,3 @@ Use `browser_interaction` for UI-reproducible bugs.
25
25
  - `tool: playwright-cli` is best for local dev-server verification in an isolated browser.
26
26
  - `tool: opencli` is best when an existing Chrome login/session or third-party integration cookies are needed.
27
27
  - `verify_steps` should describe what to prove, not low-level click scripts.
28
-
29
- Do not emit `critic` or `critic_count`; those fields are retired and validators reject them.
@@ -30,6 +30,21 @@ VALID_SEVERITIES = {"critical", "high", "medium", "low"}
30
30
  VALID_SOURCE_TYPES = {"stack_trace", "user_report", "failed_test", "log_pattern", "monitoring_alert"}
31
31
  VALID_VERIFICATION_TYPES = {"automated", "manual", "hybrid"}
32
32
  VALID_STATUSES = {"pending", "in_progress", "completed", "failed", "skipped", "needs_info", "auto_skipped"}
33
+ ALLOWED_LIST_FIELDS = {
34
+ "$schema", "project_name", "project_description", "created_at",
35
+ "created_by", "bugs", "global_context",
36
+ }
37
+ ALLOWED_GLOBAL_CONTEXT_FIELDS = {
38
+ "tech_stack", "language", "runtime", "frontend_framework",
39
+ "frontend_styling", "backend_framework", "database", "orm",
40
+ "testing_strategy", "bundler", "project_type", "ci_pipeline",
41
+ }
42
+ ALLOWED_BUG_FIELDS = {
43
+ "id", "title", "description", "severity", "priority", "error_source",
44
+ "environment", "affected_modules", "verification_type", "dependencies",
45
+ "acceptance_criteria", "status", "user_context", "browser_interaction",
46
+ "model",
47
+ }
33
48
  BUG_ID_PATTERN = re.compile(r"^B-\d{3}$")
34
49
  SCHEMA_VERSION = "dev-pipeline-bug-fix-list-v1"
35
50
 
@@ -114,6 +129,12 @@ def validate(data, feature_ids=None):
114
129
  warnings = []
115
130
 
116
131
  # Top-level required fields
132
+ unknown_root = set(data) - ALLOWED_LIST_FIELDS
133
+ if unknown_root:
134
+ errors.append("bug list has unknown fields: {}".format(
135
+ ", ".join(sorted(unknown_root))
136
+ ))
137
+
117
138
  if "$schema" not in data:
118
139
  errors.append("Missing required field: $schema")
119
140
  elif data["$schema"] != SCHEMA_VERSION:
@@ -122,6 +143,17 @@ def validate(data, feature_ids=None):
122
143
  if not data.get("project_name"):
123
144
  errors.append("Missing or empty required field: project_name")
124
145
 
146
+ global_context = data.get("global_context")
147
+ if global_context is not None:
148
+ if not isinstance(global_context, dict):
149
+ errors.append("global_context must be an object")
150
+ else:
151
+ unknown_context = set(global_context) - ALLOWED_GLOBAL_CONTEXT_FIELDS
152
+ if unknown_context:
153
+ errors.append("global_context has unknown fields: {}".format(
154
+ ", ".join(sorted(unknown_context))
155
+ ))
156
+
125
157
  bugs = data.get("bugs", [])
126
158
  if not bugs or not isinstance(bugs, list):
127
159
  errors.append("Missing or empty required field: bugs")
@@ -139,13 +171,11 @@ def validate(data, feature_ids=None):
139
171
  for i, bug in enumerate(bugs):
140
172
  prefix = "bugs[{}]".format(i)
141
173
 
142
- for retired_field in ("critic", "critic_count"):
143
- if retired_field in bug:
144
- errors.append(
145
- "{}: '{}' field is retired; remove it from bug-fix-list data".format(
146
- prefix, retired_field
147
- )
148
- )
174
+ unknown = set(bug.keys()) - ALLOWED_BUG_FIELDS
175
+ if unknown:
176
+ errors.append("{} has unknown fields: {}".format(
177
+ prefix, ", ".join(sorted(unknown))
178
+ ))
149
179
 
150
180
  # Required fields
151
181
  bug_id = bug.get("id", "")
@@ -13,6 +13,15 @@ Always produce a validated `.prizmkit/plans/feature-list.json` that conforms to
13
13
 
14
14
  For planning a **new application from scratch** (vision, tech stack, decomposition), use `app-planner` instead.
15
15
 
16
+ ## Intent-Aligned Planning Policy
17
+
18
+ Before proposing or finalizing feature contracts:
19
+ 1. Establish the **intent baseline**: confirmed product 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.
20
+ 2. Maintain **evidence status**: distinguish confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns. Never promote an inference or preferred implementation into user intent.
21
+ 3. **Clarify by decision impact**. Ask before choices that materially change product 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.
22
+ 4. Explore alternatives only when **materially different viable paths** exist. Compare meaningful trade-offs without manufacturing an option count or applying a universal default.
23
+ 5. Produce a **minimum-sufficient** feature contract: every requirement maps to a confirmed goal, constraint, existing contract, or evidenced risk, and every goal maps to observable completion evidence. Defer speculative features and unsupported future infrastructure.
24
+
16
25
  ## Invocation Commitment (Hard Rule)
17
26
 
18
27
  **When the user invokes `/feature-planner`, you MUST execute the feature-planner workflow.** You must NEVER:
@@ -54,7 +63,7 @@ Every new or changed feature is an executable contract for a fresh AI session th
54
63
 
55
64
  1. **Self-contained contract**: The feature's `description` and `acceptance_criteria`, read together, MUST define the objective, current state, desired state, selected decisions, constraints, non-goals, relevant integrations, edge cases, and completion evidence. Preserve detailed user requirements at matching detail; normalization must not simplify substantive rules.
56
65
  2. **Supplementary evidence only**: `user_context` is supplementary evidence only. It may preserve scoped source excerpts and purpose-tagged references, but it MUST NOT expand, replace, or contradict the contract in `description` and `acceptance_criteria`. If `user_context` were removed, a fresh execution session must still know exactly what to implement and how to prove completion.
57
- 3. **Clarify, do not guess**: Ask the user for clarification whenever requirements conflict or a reference has multiple plausible antecedents. Do not finalize the feature while ambiguity remains.
66
+ 3. **Clarify by impact, do not guess**: Ask when conflicting requirements or multiple plausible antecedents would materially change product behavior, scope, compatibility, safety, cost, or completion evidence. Resolve evidence-backed facts from project context and retain safe low-risk reversible choices as explicit assumptions rather than silently inventing user intent.
58
67
  4. **Feature isolation**: In multi-feature planning, each contract and its supplementary evidence contain only material relevant to that feature. Repeat shared context only when it explicitly applies to every affected feature. Ask the user to map material whose applicability is unclear.
59
68
 
60
69
  ### Artifact-Wide AI Readability
@@ -130,8 +139,7 @@ Trigger conditions are covered by the frontmatter `description`. Do NOT use this
130
139
  8. **Browser interaction**: If present, may include `tool` and `verify_steps`; planner should add concrete `verify_steps` when known, but the schema permits an empty object for AI runtime exploration.
131
140
  9. **Complexity enum**: If present, is one of: low, medium, high, critical
132
141
  10. **Model field**: If present, is a non-empty string
133
- 11. **Retired fields**: `critic` and `critic_count` must not appear; validation fails if either field is present
134
- 12. **Root schema**: Has $schema='dev-pipeline-feature-list-v1', project_name, and non-empty features array
142
+ 11. **Root schema**: Has $schema='dev-pipeline-feature-list-v1', project_name, and non-empty features array
135
143
 
136
144
  5. **Use script output as source of truth** — if validation fails, fix and re-run until pass
137
145
 
@@ -142,7 +150,7 @@ Before questions, check optional context files (never block if absent):
142
150
  - `.prizmkit/config.json` (existing stack preferences and detected tech stack)
143
151
  - `.prizmkit/plans/project-brief.md` (project context from app-planner, if available)
144
152
  - existing `.prizmkit/plans/feature-list.json` (required for incremental mode)
145
- - Platform instruction file: use the `platform` field in `.prizmkit/manifest.json` as source of truth when present (`codex` → `AGENTS.md`, `claude` → `CLAUDE.md`, `codebuddy` → `CODEBUDDY.md`, `all` → read every matching file). Legacy manifests may contain `both`; treat it as read-only compatibility and read `CLAUDE.md` plus `CODEBUDDY.md` only when encountered.
153
+ - Platform instruction file: use the `platform` field in `.prizmkit/manifest.json` as source of truth when present (`codex` → `AGENTS.md`, `cursor` → existing user-owned `AGENTS.md` when present, `claude` → `CLAUDE.md`, `codebuddy` → `CODEBUDDY.md`, `all` → read every matching file). Legacy manifests may contain `both`; treat it as read-only compatibility and read `CLAUDE.md` plus `CODEBUDDY.md` only when encountered.
146
154
  - If `.prizmkit/prizm-docs/root.prizm` is absent and the project has existing source code, scan the directory structure to understand the codebase layout:
147
155
  ```bash
148
156
  find . -maxdepth 2 -type d \
@@ -151,7 +159,7 @@ Before questions, check optional context files (never block if absent):
151
159
  -not -path '*/__pycache__/*' -not -path '*/vendor/*' \
152
160
  -not -path '*/.agents/*' -not -path '*/.codex/*' \
153
161
  -not -path '*/.claude/*' -not -path '*/.codebuddy/*' \
154
- -not -path '*/.prizmkit/*' \
162
+ -not -path '*/.cursor/*' -not -path '*/.prizmkit/*' \
155
163
  | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
156
164
  ```
157
165
 
@@ -273,7 +281,7 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
273
281
 
274
282
  ### Interactive Phases
275
283
  1. Clarify scope and goals
276
- 1.1 **Requirement clarification** — for ANY unclear aspect of the user's goals or scope, ask questions one at a time (cite the unclear point, give a recommended answer with rationale) until you fully understand. No limit on rounds. Do not proceed to Phase 2 with unresolved ambiguities.
284
+ 1.1 **Requirement clarification** — establish the intent baseline, inspect project evidence, and classify uncertainty by decision impact. Ask about consequential ambiguity in goals, external behavior, scope, non-goals, compatibility, safety, cost, or irreversible choices; label recommendations and group related questions unless answers are dependent. Proceed when consequential ambiguity is resolved and any low-risk reversible assumptions are explicit—not when every unknown has been eliminated.
277
285
  1.2 **Collect reference materials** — **Upfront Material Detection (Hard Rule)**: If the user has already provided materials (file paths, URLs, rules, specifications, code snippets) in the same message that invoked this skill: (a) Acknowledge what was received: "I received the following materials: [list]"; (b) Read/fetch all provided materials immediately; (c) You MUST still ask: "Are there any additional materials you'd like to provide?"; (d) NEVER skip this collection step just because the user already provided some materials.
278
286
 
279
287
  If the user has NOT provided any materials upfront, explicitly ask whether they have any supplementary materials for you to review. Present this as a single prompt covering all material types:
@@ -290,7 +298,7 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
290
298
  2. Confirm constraints and existing architecture
291
299
  3. Propose feature set with dependencies
292
300
  4. Refine descriptions and acceptance criteria
293
- 4.1 **Per-feature clarification** — for each feature, if the description, acceptance criteria, selected decision, scope, non-goals, edge cases, integration points, completion evidence, or material purpose is vague or could be interpreted multiple ways, ask the user to clarify before finalizing. Reject conversational shorthand that requires an unseen question, recommendation, or option list.
301
+ 4.1 **Per-feature clarification** — for each feature, ask when multiple interpretations of behavior, acceptance criteria, scope, non-goals, material integrations, or completion evidence would materially change the contract. Resolve evidence-backed details from project context, label low-risk reversible assumptions, and reject conversational shorthand that requires an unseen question, recommendation, or option list. Do not force user confirmation for unconstrained implementation details that a fresh session can safely decide and verify.
294
302
  4.2 **Browser interaction** (mandatory for fullstack/frontend projects) — see §Browser Interaction Planning below. Qualifying features get `browser_interaction` by default. Only confirm with the user as a batch summary; do NOT ask per-feature.
295
303
  5. Verify DAG/order/priorities and show the mandatory priority/complexity calibration table with short rationales for every item
296
304
  6. Run the pre-generation Headless Context Completeness Gate (see §Pre-Generation Completeness Review below)
@@ -310,7 +318,7 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
310
318
  | **CP-FP-2** | Feature Proposals | Feature set with titles+deps identified (pre-validation) | 3-5 |
311
319
  | **CP-FP-3** | DAG Validity | No cycles, dependencies resolved (validation dry-run) | 5 |
312
320
  | **CP-FP-3.1** | Browser Interaction Applied | Qualifying features have `browser_interaction` field; user confirmed or opted out | 4 |
313
- | **CP-FP-3.2** | Testing Defaults Applied | All features have appropriate testing expectations and no retired `critic`/`critic_count` fields | 7 |
321
+ | **CP-FP-3.2** | Testing Defaults Applied | All features have appropriate testing expectations | 7 |
314
322
  | **CP-FP-3.3** | Completeness Review Passed | Every new or changed feature passes fresh-session simulation from `description` and `acceptance_criteria` without conversation history or `user_context` | 6 |
315
323
  | **CP-FP-4** | `.prizmkit/plans/feature-list.json` Generated | Schema validates, all required keys present | 7-8 |
316
324
  | **CP-FP-5** | Final Validation Pass | Python script returns `"valid": true` with zero errors | 9 |
@@ -422,7 +430,7 @@ Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the sin
422
430
 
423
431
  ## Testing Defaults (Phase 8)
424
432
 
425
- Set default testing-related fields for each feature. The user can opt out of generated testing expectations, but do not generate retired review-agent configuration fields.
433
+ Set default testing-related fields for each feature. The user can opt out of generated testing expectations.
426
434
 
427
435
  | Priority | Testing expectation | Rationale |
428
436
  |----------|---------------------|-----------|
@@ -430,8 +438,6 @@ Set default testing-related fields for each feature. The user can opt out of gen
430
438
  | medium | Require focused tests for changed public behavior | Normal changes need meaningful boundary coverage. |
431
439
  | low | Require the smallest relevant verification | Low-risk changes should stay lightweight. |
432
440
 
433
- Never emit `critic` or `critic_count`; those fields are fully removed and the validator rejects them.
434
-
435
441
  For frontend features with `browser_interaction`, browser verification is enabled by default. The `tool` field uses the user's choice from the mandatory browser tool question in Phase 4.2 (see §Browser Interaction Planning → Default Behavior).
436
442
 
437
443
  Present a consolidated testing summary table at Phase 8, then ask for confirmation.
@@ -8,7 +8,7 @@ For app-level design references (vision templates, tech stack matrix), see `app-
8
8
 
9
9
  ## Feature Description Writing Guide
10
10
 
11
- Feature descriptions are the **primary input** for autonomous pipeline sessions. A thin description forces the AI to guess — producing worse code. Invest in rich descriptions upfront.
11
+ Feature descriptions are the **primary input** for autonomous pipeline sessions. A thin description forces the AI to guess, while an overprescribed description can turn assumptions into requirements. Write the minimum-sufficient contract: preserve every confirmed behavior and constraint at matching detail, and omit unsupported implementation choices or unrelated future design.
12
12
 
13
13
  ### Minimum Word Counts
14
14
 
@@ -21,17 +21,17 @@ Feature descriptions are the **primary input** for autonomous pipeline sessions.
21
21
 
22
22
  Below 15 words is a validation error. Below the recommended minimum triggers a warning.
23
23
 
24
- **There is NO upper limit** — the more detail the better. Rich descriptions prevent the AI from guessing, producing higher quality code. Always aim to describe the feature as thoroughly as possible: what to build, how it should behave, what data it touches, and what edge cases to handle.
24
+ There is no schema-level upper limit, but length is not a quality target. Add detail only when it establishes confirmed intent, current/desired behavior, constraints, integrations, relevant edge cases, or completion evidence. Do not add speculative infrastructure, API shape, data fields, or future capability merely to reach a recommended word count.
25
25
 
26
26
  ### What to Include
27
27
 
28
- Every description should cover these aspects (adapt per feature type):
28
+ Cover only the aspects that are material to this feature; omit non-applicable dimensions rather than inventing content:
29
29
 
30
- 1. **What to build** — concrete deliverables (API endpoints, UI pages/components, CLI commands, data models)
31
- 2. **Key behaviors** — business rules, validation, state transitions, workflows
32
- 3. **Integration points** — which existing modules, services, or APIs it connects to
33
- 4. **Data model** — entities, relationships, key fields, storage approach (when applicable)
34
- 5. **Error/edge cases** — failure modes, empty states, limits, unauthorized access
30
+ 1. **Outcome and deliverables** — confirmed user-visible or system-observable result; name endpoints, pages, commands, or models only when the contract or existing system establishes them
31
+ 2. **Key behaviors** — business rules, validation, state transitions, and workflows required by the intent
32
+ 3. **Integration points** — verified existing modules, services, APIs, or predecessor outputs and why they matter
33
+ 4. **Data model** — entities, relationships, and constraints when persistence is genuinely required
34
+ 5. **Relevant error/edge cases** — failures, empty states, limits, permissions, concurrency, or idempotency only where they affect completion
35
35
 
36
36
  ### Good vs Bad Examples
37
37
 
@@ -61,7 +61,7 @@ Feature entries are consumed by **autonomous AI sessions running in headless mod
61
61
 
62
62
  **Must include for headless readiness:**
63
63
  1. **Objective and current state** — the exact outcome and what exists today
64
- 2. **Desired state and selected decisions** — the complete chosen behavior or approach, never only an option label
64
+ 2. **Desired state and selected decisions** — the complete chosen product/contract behavior, never only an option label; include implementation approach only when the user, an existing contract, or verified project constraints actually select it
65
65
  3. **Constraints and non-goals** — boundaries the implementation must preserve
66
66
  4. **Relevant integrations** — existing APIs, models, modules, services, and dependency outputs
67
67
  5. **Edge cases** — validation, permissions, empty/error states, limits, concurrency, or idempotency when relevant
@@ -123,7 +123,7 @@ Then [expected outcome]
123
123
 
124
124
  1. **One behavior per criterion.** Each criterion tests exactly one thing.
125
125
  2. **No implementation details.** Criteria describe what, not how. Say "user is redirected" not "React Router navigates to /dashboard."
126
- 3. **Include edge cases.** Cover invalid input, unauthorized access, empty states, and error conditions.
126
+ 3. **Include relevant edge cases.** Cover invalid input, unauthorized access, empty states, and error conditions only when they can affect the confirmed outcome.
127
127
  4. **Be measurable.** Where performance matters, include specific thresholds (e.g., "within 2 seconds").
128
128
  5. **Keep the count manageable.** A feature with more than 8 acceptance criteria may need to be split into sub-features.
129
129
 
@@ -186,17 +186,17 @@ Anti-pattern: a generated plan where every item is `Priority: high` and `Complex
186
186
 
187
187
  These rules ensure the feature dependency graph is valid and buildable.
188
188
 
189
- 1. **F-001 has zero dependencies.** The first feature is always infrastructure or project setup. It must be buildable from scratch with no preconditions.
189
+ 1. **F-001 has zero feature-list dependencies.** It is the first independently executable deliverable for the current project state; make it infrastructure or setup only when confirmed prerequisites require that work. Do not recreate setup that already exists.
190
190
 
191
191
  2. **No circular dependencies.** Dependencies MUST form a directed acyclic graph (DAG). If A depends on B and B depends on A, restructure the features.
192
192
 
193
193
  3. **Minimal dependency sets.** Each feature should depend only on the features it directly needs. Do not add transitive dependencies explicitly. If F-003 depends on F-002 and F-002 depends on F-001, then F-003 does NOT need to list F-001 as a dependency.
194
194
 
195
- 4. **Auth comes early.** Most features depend on authentication. Place auth-related features (registration, login, session management) as early in the graph as possible, typically F-002.
195
+ 4. **Place authentication before its consumers when required.** Do not add or prioritize authentication merely because it is common; use the confirmed product scope and existing auth state.
196
196
 
197
197
  5. **Data model before display.** Features that create or define data entities must precede features that display, search, or manipulate that data.
198
198
 
199
- 6. **Infrastructure before everything.** Database setup, project scaffolding, CI/CD configuration, and environment setup belong in F-001.
199
+ 6. **Place missing prerequisites before their consumers.** Database, scaffolding, CI/CD, or environment work belongs early only when it is absent, in scope, and required by a confirmed feature. Existing-project planning must not manufacture infrastructure tasks.
200
200
 
201
201
  7. **Independent features can be parallel.** If two features share no dependencies on each other, they can be built in parallel. The dependency graph should reflect this by not artificially linking them.
202
202
 
@@ -12,8 +12,8 @@ Scan all AI-visible fields and sections, not only the main contract. Every gener
12
12
 
13
13
  For each new or changed feature, answer all of these from `description` and `acceptance_criteria` alone:
14
14
 
15
- 1. What exact problem or outcome is this feature responsible for?
16
- 2. What exists today and what must change?
15
+ 1. What exact confirmed problem or outcome is this feature responsible for, and how does it preserve the intent baseline?
16
+ 2. What exists today, which statements are facts versus inferences/assumptions, and what must change?
17
17
  3. Which approach was selected, expressed by meaning rather than an option label?
18
18
  4. What constraints and non-goals must be preserved?
19
19
  5. Which existing modules, APIs, data, dependencies, or other relevant integrations are involved?
@@ -22,8 +22,10 @@ For each new or changed feature, answer all of these from `description` and `acc
22
22
  8. Does any phrase require an unseen earlier question, recommendation, or option list?
23
23
  9. Why is each reference material relevant, and what should the execution AI inspect?
24
24
  10. Do quoted source materials agree with the final task decision?
25
+ 11. Does every prescribed behavior or design choice map to a confirmed goal, constraint, existing contract, or evidenced risk?
26
+ 12. Are any unresolved consequential decisions hidden behind an AI recommendation or silent default?
25
27
 
26
- If any answer is unavailable, ambiguous, or present only in `user_context`, the verdict is `NEEDS_FIXES`. Never infer a missing decision from conversation memory.
28
+ If any consequential answer is unavailable, ambiguous, or present only in `user_context`, the verdict is `NEEDS_FIXES`. A low-risk, local, reversible implementation assumption may remain when it is labeled and paired with a verification point; never infer a missing product decision from conversation memory.
27
29
 
28
30
  ## Step 2: Contract and Material Checks
29
31
 
@@ -57,7 +59,9 @@ Look at the feature set as a whole:
57
59
  - **Implied functionality gaps**: Does one feature assume a capability that no feature provides?
58
60
  - **Missing integration seams**: If two features share data or interact at runtime, is the interface specified by meaning?
59
61
  - **Dependency context**: Does each dependent feature state exactly which predecessor output it consumes?
60
- - **Scope leaks**: Does a description activate rejected or out-of-scope functionality?
62
+ - **Scope leaks**: Does a description activate rejected or out-of-scope functionality, speculative future capability, or unsupported infrastructure?
63
+ - **Design necessity**: Does every prescribed component, interface, or dependency map to confirmed intent, an existing contract, or an evidenced risk?
64
+ - **Evidence status**: Are recommendations and inferred implementation details clearly separated from confirmed product decisions?
61
65
  - **Source conflict**: Does an excerpt describe an earlier alternative that conflicts with the selected final decision?
62
66
 
63
67
  ## Step 4: Present Review and Repair
@@ -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 feature entry, check:
31
31
 
32
+ - Intent fidelity: confirmed product outcome, success meaning, scope, non-goals, and constraints preserve user intent rather than AI preferences or generic best practices
33
+ - Evidence status honesty: confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns remain distinct; no consequential product or contract decision is silently defaulted
34
+ - Minimum-sufficient design: every prescribed behavior, component, interface, or dependency maps to a confirmed goal, constraint, existing contract, or evidenced risk; speculative features and unsupported infrastructure are absent
32
35
  - Schema compatibility with `dev-pipeline-feature-list-v1` and `.prizmkit/dev-pipeline/templates/feature-list-schema.json`
33
36
  - Dependency/DAG soundness: dependencies exist, no cycles, no poorly ordered prerequisite chains
34
37
  - Description completeness and headless execution readiness: `description` plus `acceptance_criteria` defines objective, current state, desired state, selected decisions, constraints, non-goals, relevant integrations, edge cases, and completion evidence without conversation history
@@ -45,14 +48,15 @@ For every reviewed feature entry, check:
45
48
 
46
49
  Repeat the pre-generation simulation for every reviewed new or changed feature 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 exists today and what must change?
51
+ 1. What exact confirmed problem or outcome is this task responsible for, and how does it preserve the intent baseline?
52
+ 2. What exists today, which statements are facts versus inferences/assumptions, and what must change?
50
53
  3. Which approach was selected, expressed by meaning rather than an option label?
51
54
  4. What constraints and non-goals must be preserved?
52
55
  5. Why is each reference material relevant?
53
56
  6. How can completion 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 prescribed behavior or design choice have a confirmed requirement, constraint, existing contract, or evidenced risk, with no speculative future scope?
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 task 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