prizmkit 1.1.146 → 1.1.148

package/bundled/skills/bug-planner/SKILL.md

@@ -40,29 +40,53 @@ After planning is complete, you MUST:
 4. NEVER auto-execute the pipeline, launcher, composite workflow, or any fix step
 5. Return the validated bug list to the caller; only `bugfix-pipeline-launcher` prepares the runtime command
 
-## User-Provided Content Priority (Hard Rule)
-
-When the user provides detailed specifications, rules, or implementation requirements:
-
-1. **Verbatim preservation**: The user's exact wording MUST be preserved in `description` and `acceptance_criteria` fields. Do NOT paraphrase, summarize, abstract, or simplify.
-2. **No autonomous simplification**: A 200-word user specification must NOT become a 30-word description. Match the detail level of the user's input.
-3. **Clarify, don't assume**: If any user-provided rule is ambiguous or potentially conflicts with another, ASK the user to clarify. No limit on clarification rounds. Do NOT proceed with unresolved ambiguities.
-4. **Task-scoped `user_context`**: In single-bug planning, write the relevant user-provided materials into that bug's `user_context`. In multi-bug planning, multi-bug `user_context` must contain only the user text, file references, logs, and reproduction details relevant to that specific bug.
-   - Preserve the matching user wording verbatim, but scope it to the item it belongs to.
-   - Do NOT copy the full multi-bug request into every bug.
-   - Ensure there are no unrelated sibling bug descriptions, stack traces, logs, reproduction steps, expected/actual behavior notes, or supplementary materials in a bug's `user_context`.
-   - Shared global context may be copied to every item only when it is explicitly applicable to all generated items.
-   - If a log, stack trace, screenshot, reproduction path, or file reference applies to only one bug, attach it only to that matching bug.
-   - If applicability is unclear, ask the user to map the material to the correct bug before generating the final list.
-5. **`user_context` format**:
-   - Bug-specific supplementary content or rules → store as-is (verbatim text) on the matching bug only
-   - Bug-specific file references → store as path string, e.g. `src/auth/login.ts:42-78` or `src/utils/validate.ts — focus on validateEmail function`
-   - Truly shared global constraints or environment context → repeat only when they apply to every generated bug
+## Fresh-Session Task Contract (Hard Rule)
+
+Every new or changed bug is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
+
+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.
+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.
+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.
+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.
+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.
+
+### Artifact-Wide AI Readability
+
+- Every generated natural-language value must be a standalone domain statement. This applies to all AI-visible fields and sections, including `project_description`, `global_context`, titles, descriptions, acceptance criteria, severity/priority rationale, `error_source`, affected-module and environment text, `user_context`, verification goals, comments, appendices, and parentheticals.
+- Machine metadata such as schema markers, stable IDs, statuses, enums, and timestamps is exempt. Natural-language metadata is not exempt.
+- Never emit dialogue-role or chronology labels such as `user said`, `user answered`, `original request`, `this round`, `previous discussion`, `as discussed earlier`, `用户本轮回答`, or `如前面讨论`. Never emit planning question IDs, answer tokens, planning-option recommendation markers, checkpoint provenance, or raw internal answer-map entries as domain content.
+- `user_context` and `error_source` may hold independently intelligible evidence, not transcript fragments. Rewrite every confirmed turn into direct actual/expected behavior, scope, rationale, reproduction, or verification evidence before generation.
+
+### Conversational Context Normalization
+
+- Never persist standalone option labels such as `A`, `B`, `C`, `方案A`, or `方案B` as execution context.
+- Expand a selected option into complete meaning and preserve substantive user rationale and constraints in durable prose at matching detail.
+- Do not emit transcript annotations such as `(original response: "...")` in final bug artifacts. Bare option labels and relative shorthand are not independently intelligible and materially useful exact wording.
+- Resolve `上面`, `这个`, `按推荐走`, `同前`, `继续这样`, `用刚才的方案`, `same as above`, or `go with your recommendation` only when there is one provable antecedent. Otherwise ask the user for clarification; never guess.
+- Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization. Apply the concrete accepted recommendations, then omit the raw approval; never repeat it once per accepted recommendation.
+- Do not present rejected root-cause or fix alternatives as active instructions; preserve one only when it defines a necessary non-goal. Retain exact user wording only when it is independently intelligible and materially useful.
+
+### Reference Material Handling
+
+- Every retained stable code, configuration, machine-consumed interface, or URL reference must be purpose-tagged: state why it is relevant and what the execution AI should inspect. This applies to paths and URLs in structured evidence and `user_context`.
+- Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`, uploaded-report paths, screenshot paths, or ad-hoc log paths in durable bug contracts. Instead, copy or normalize the task-relevant content and exact evidence excerpt into `description` and `acceptance_criteria`; the bug must not depend on that source file still existing.
+- Good: `src/auth/validation.ts — inspect empty-password handling`; Bad: `logs/api-500.log — inspect the failure`. For a transient log, inline the relevant request, exception, and correlation evidence without retaining the path.
+- For large materials, preserve purpose and only task-relevant exact excerpts, and move confirmed expected behavior, selected scope, severity rationale, and verification decisions into `description` and `acceptance_criteria`. Retain a location only when it is a stable execution-time source of truth.
+- Embed complete large materials only when the execution session cannot access the source and all content is genuinely required.
+
+### Good and Bad Normalization Examples
+
+- Bad: `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation` stored as selected fix scope.
+- Bad: `Selected decision: reject empty passwords with HTTP 400 (original response: "方案B")`; the annotation still requires an unseen option list.
+- Good: `Selected decision: reject empty passwords in request validation with HTTP 400 and do not enter credential verification`.
+- Good: `Selected decision: reproduce against the API integration test and retain UI verification as a regression check`.
+- Bad: storing or repeating `全部按照推荐` / `所有问题都按你的推荐处理` as a bug constraint; it is conversational authorization.
+- Bad: attaching a complete production log or retaining its local path while saying only `fix this`. Good: inline the relevant exception excerpt, actual/expected behavior, scope, and verification; retain a monitoring URL only when it is a stable execution-time source of truth.
 
 **Multi-bug isolation example:**
 - User request includes: `Bug A: login crashes when password is empty`, `Bug B: CSV export loses Chinese characters`, and `Shared: production uses Node 20`.
-- The login bug `user_context` includes `Bug A: login crashes when password is empty` and the shared Node 20 environment; it MUST NOT include `Bug B: CSV export loses Chinese characters`.
-- The CSV bug `user_context` includes `Bug B: CSV export loses Chinese characters` and the shared Node 20 environment; it MUST NOT include `Bug A: login crashes when password is empty`.
+- The login bug contract fully defines its expected/actual behavior and includes only matching evidence plus the shared Node 20 environment; it MUST NOT include the CSV report.
+- The CSV bug contract fully defines encoding expectations and includes only matching evidence plus the shared Node 20 environment; it MUST NOT include the login report.
 
 ## When to Use
 
@@ -180,7 +204,7 @@ Gather project metadata from the project's own configuration and documentation
    >
    > If none, we'll proceed with bug collection."
 
-   If the user provides materials, read/fetch them all before proceeding to Phase 2. For web links, use web fetch to retrieve and analyze the content. For images, read and analyze them visually. This context significantly improves bug diagnosis accuracy and description quality.
+   If the user provides materials, require or infer only when unambiguous a bug-specific purpose for each material; otherwise ask what the execution AI should inspect. Read/fetch the relevant material before Phase 2. For web links, retrieve the relevant content; for images, analyze the relevant visual evidence. Material ingestion follows the same durability rule as final output: copy or normalize task-relevant requirements and exact evidence, omit transient non-code paths, and retain only purpose-tagged stable execution-time sources. Do not inject complete large materials merely to preserve them.
 
 Output: `project_name`, `project_description`, `global_context` fields populated.
 
@@ -205,7 +229,7 @@ When parsing user input, auto-detect the format and read `${SKILL_DIR}/reference
 - Acceptance criteria (auto-suggest based on description, user can edit)
 - Model override (optional; if specified, overrides $MODEL env var for this bug fix)
 
-**Per-bug clarification** — if the bug's root cause, reproduction steps, expected behavior, or scope is unclear from the provided information, 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 a bug entry with ambiguous details. No limit on the number of questions per bug.
+**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.
 
 **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.
 
@@ -245,11 +269,22 @@ Only finalize the bug entry after user confirms all three points.
 
 **Gate → CP-BP-3**: Severity/priority assigned, duplicates resolved.
 
-### Phase 4: Pre-Generation Completeness Review
+### Phase 4: Pre-Generation Headless Context Completeness Gate
+
+Before generating `.prizmkit/plans/bug-fix-list.json`, review every new or changed bug as if the reviewer has never seen the planning conversation. Preserve unchanged historical bugs; do not bulk-rewrite them. Scan all AI-visible fields and sections first: every generated natural-language value in `project_description`, `global_context`, item fields, `error_source`, environment/evidence, `user_context`, comments, and parentheticals must be session-independent, with no dialogue-role labels, question IDs, answer tokens, planning-option recommendation markers, or planning provenance. Review changed root prose even when no bug item changed. Then remove `user_context` from the review view and answer from `description` plus `acceptance_criteria` alone:
 
-Before generating `.prizmkit/plans/bug-fix-list.json`, perform a holistic scan across all collected bugs. The bugfix pipeline runs autonomously — any ambiguity left here becomes a wrong assumption later.
+1. What exact problem or outcome is this task responsible for?
+2. What exists today, including actual behavior, and what must change to the expected behavior?
+3. Which fix scope and verification approach were selected, expressed by meaning rather than an option label?
+4. What constraints and non-goals must be preserved?
+5. Why is each reference material relevant, and what should be inspected?
+6. How can completion be verified?
+7. Does any phrase require an unseen earlier question, recommendation, or option list?
+8. Do quoted source materials agree with the final task decision?
 
-**Step 1 — Description adequacy scan (Headless Execution Readiness)**: The bugfix pipeline runs each bug through an autonomous AI session with NO human interaction. Every description must be unambiguous enough for headless execution. For each bug, check:
+Return `NEEDS_FIXES` whenever any answer is missing, ambiguous, or available only in supplementary evidence. Ask the user for clarification rather than guessing when a reference does not have one provable antecedent.
+
+**Step 1 — Description adequacy scan (Headless Execution Readiness)**: The bugfix pipeline runs each bug through an autonomous AI session with NO human interaction. Every task contract must be unambiguous enough for headless execution. For each bug, check:
 - Description clearly states **expected** vs **actual** behavior (not just "X doesn't work")
 - Reproduction path is specific enough for the pipeline AI to locate the relevant code
 - If the bug involves user interaction, the trigger action is described (not just the symptom)
@@ -258,7 +293,7 @@ Before generating `.prizmkit/plans/bug-fix-list.json`, perform a holistic scan a
 - Bad: "Login is broken" — too vague, AI will search the entire codebase
 - 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."
 
-**Step 2 — Acceptance criteria specificity check**: For each bug, verify each acceptance criterion passes the "pipeline autonomy test" — could an AI session, without asking a human, determine whether this criterion is met? Flag criteria that are subjective ("works correctly"), lack measurable conditions ("performs better"), or don't specify the verification method.
+**Step 2 — Acceptance criteria specificity check**: For each bug, verify each acceptance criterion passes the "pipeline autonomy test" — could an AI session, without asking a human, determine whether this criterion is met? Flag criteria that are subjective ("works correctly"), lack measurable conditions ("performs better"), omit expected behavior, or leave reproduction and verification decisions only in `user_context`.
 
 **Step 3 — Cross-bug analysis**: Check for:
 - **Root cause overlap**: Multiple bugs in the same module may share a root cause — flag for user to confirm whether they should be merged or kept separate
@@ -269,11 +304,11 @@ Before generating `.prizmkit/plans/bug-fix-list.json`, perform a holistic scan a
 
 For any items that need attention, ask targeted questions to fill gaps. Iterate until the user confirms all bugs are adequately described. Present the prompt:
 
-> "Above is the completeness review. Items needing more detail — address them now, or proceed and refine later?"
+> "Above is the completeness review. Every `NEEDS_FIXES` item must be clarified before generation. Which flagged item should we address first?"
 
-Only proceed to Phase 5 after user confirms.
+For every `NEEDS_FIXES` result, update the draft/source bug contract, rerun the artifact-alone questions, and continue until all new or changed bugs return `PASS`. Only proceed to Phase 5 after user confirms.
 
-**Gate → CP-BP-4**: All bugs pass headless execution readiness check.
+**Gate → CP-BP-4**: All new or changed bugs pass the Headless Context Completeness Gate without relying on conversation history or `user_context`.
 
 ### Phase 5: Generate & Validate
 
@@ -295,7 +330,7 @@ Only proceed to Phase 5 after user confirms.
 
 Run this gate after `.prizmkit/plans/bug-fix-list.json` passes generation and validation, and before the final handoff. It applies whenever this session added or changed final bug entries. For validate-only, summary-only, or draft-save flows with no final content change, report that the gate is not applicable.
 
-Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual draft and final artifacts directly because `.prizmkit` files may be gitignored. Keep the review planning-only, apply accepted findings to the draft/source representation, regenerate the final JSON, and require validation to pass again before reporting the review result.
+Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual draft and final artifacts directly because `.prizmkit` files may be gitignored. Repeat the Headless Context Completeness Gate for every reviewed new or changed bug. Keep the review planning-only, apply accepted findings to the draft/source representation, regenerate the final JSON, rerun validation, and repeat local review until it returns `PASS` before reporting the result.
 
 #### Success Output
 
@@ -341,12 +376,13 @@ Batch-parse error logs with minimal interaction: parse automatically, then requi
    - verification_type: default to `automated`
    - acceptance_criteria: auto-generate "Error no longer occurs in [scenario]"
 4. Write draft to `.prizmkit/plans/bug-fix-list.draft.json` for user review
-5. Ask: "Review and confirm? You can edit individual entries."
-6. After user confirms, call the generate script:
+5. Run the Phase 4 Headless Context Completeness Gate on every parsed bug. Ask targeted clarification for missing expected behavior, selected scope, severity rationale, or verification decisions; update the draft until all entries pass.
+6. Ask: "Review and confirm? You can edit individual entries."
+7. After user confirms, call the generate script:
    ```bash
    python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
    ```
-7. If validation passes, run the mandatory Local Generated-Plan Review Gate before summarizing or recommending `bugfix-pipeline-launcher`.
+8. If validation passes, run the mandatory Local Generated-Plan Review Gate before summarizing or recommending `bugfix-pipeline-launcher`.
 
 ## Operation: From Tests
 
@@ -359,12 +395,13 @@ Batch-parse failed test output:
 3. Auto-populate `failed_test_path`, `error_message`
 4. Set verification_type to `automated` (test already exists)
 5. Write draft to `.prizmkit/plans/bug-fix-list.draft.json`
-6. Present parsed failed-test bug entries for confirmation; allow edits, merges, or removals
-7. After user confirms, call the generate script:
+6. Run the Phase 4 Headless Context Completeness Gate on every parsed failed-test bug; ensure the failing test evidence agrees with the final expected behavior and selected fix scope.
+7. Present parsed failed-test bug entries for confirmation; allow edits, merges, or removals
+8. After user confirms, call the generate script:
    ```bash
    python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/plans/bug-fix-list.draft.json --output .prizmkit/plans/bug-fix-list.json
    ```
-7. If validation passes, run the mandatory Local Generated-Plan Review Gate before summarizing or recommending `bugfix-pipeline-launcher`.
+9. If validation passes, run the mandatory Local Generated-Plan Review Gate before summarizing or recommending `bugfix-pipeline-launcher`.
 
 ## Operation: Validate
 
@@ -417,7 +454,7 @@ Recommend invoking `bugfix-pipeline-launcher` to configure and launch the pipeli
 
 After `.prizmkit/plans/bug-fix-list.json` is generated, validated, and reviewed, present:
 1. Summary of generated bugs (count, severity breakdown)
-2. Local generated-plan review result: verdict, reviewed bug IDs, accepted fixes (or "none"), and final validation result
+2. Local generated-plan review result: verdict, reviewed bug IDs plus reviewed root prose when applicable, accepted fixes (or "none"), and final validation result
 3. Recommend: "Say 'start fixing' to launch the bugfix pipeline via `bugfix-pipeline-launcher`"
 4. Alternative: fix a single bug interactively via `bug-fix-workflow`
 

package/bundled/skills/bug-planner/references/generated-plan-review.md

@@ -20,8 +20,8 @@ Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whethe
 ## Review Scope
 
 1. If a pre-session final list exists, compare by stable bug IDs (`B-*`).
-2. Treat bugs as changed only when item fields changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
-3. Review newly added bug IDs and changed bug IDs.
+2. Root project prose is reviewable content, not generator metadata. Review new or changed `project_description` and `global_context` even when no bug item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
+3. Treat bugs as changed only when item fields changed; review newly added bug IDs and changed bug IDs.
 4. Preserve unchanged historical bugs. Read unchanged entries only when needed to verify dependency references, duplicate handling, or root-cause overlap with reviewed bugs.
 5. If no snapshot exists, review all bug entries produced by the current generation flow.
 
@@ -31,13 +31,40 @@ For every reviewed bug entry, check:
 
 - Schema compatibility with `dev-pipeline-bug-fix-list-v1` and `.prizmkit/dev-pipeline/templates/bug-fix-list-schema.json`
 - Dependency/DAG consistency, duplicate handling, and root-cause overlap
-- Description completeness: expected vs actual behavior, reproduction path, code-location hints, affected environment, and headless execution readiness
+- 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
+- Artifact-wide readability: every generated natural-language value across all AI-visible fields and sections—including `project_description`, `global_context`, `error_source`, environment/evidence, rationales, `user_context`, comments, and parentheticals—is a standalone domain statement without dialogue-role labels, question IDs, answer tokens, planning-option recommendation markers, or planning provenance
 - Acceptance criteria specificity and measurable verification method
-- User-provided wording preservation in `description`, `acceptance_criteria`, and `user_context`
+- User-provided detail preservation at matching detail after conversational normalization
+- `user_context` is supplementary evidence only: it does not expand, replace, or contradict the bug contract; if `user_context` were removed, execution and verification remain unambiguous
 - Task-scoped `user_context` isolation: no unrelated sibling bug descriptions, logs, stack traces, reproduction steps, expected/actual behavior notes, or supplementary materials; shared context appears on multiple bugs only when explicitly global
+- Purpose-tagged stable code, configuration, machine-consumed interface, and URL references; transient non-code planning/evidence paths are replaced by inline task-relevant decisions and excerpts, and large materials are bounded rather than injected in full
 - Severity/priority calibration: every reviewed bug has a short severity rationale and priority rationale, the preserved severity-to-priority mapping is followed, and high priority is not used without core outage, data loss/integrity, security/auth, timeout/crash, or no-workaround indicators
 - Browser interaction and verification fields for UI-reproducible bugs when applicable
 
+## Headless Context Completeness Gate
+
+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:
+
+1. What exact problem or outcome is this task responsible for?
+2. What exists today and what must change from actual to expected behavior?
+3. Which fix scope and verification approach were selected, expressed by meaning rather than an option label?
+4. What constraints and non-goals must be preserved?
+5. Why is each reference material relevant?
+6. How can completion be verified?
+7. Does any phrase require an unseen earlier question, recommendation, or option list?
+8. Do quoted source materials agree with the final task decision?
+
+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.
+
+Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Apply this stricter gate prospectively to new or changed entries and preserve unchanged historical bugs.
+
+### Good and Bad Review Examples
+
+- Bad: `按推荐走` as severity or verification scope, including as `(original response: "按推荐走")`; Good: `Selected decision: classify as medium because export is incorrect but a JSON workaround exists; verify with the existing Unicode export test`.
+- Bad: repeating `(original response: "全部按照推荐")` after each accepted bug decision; Good: write each concrete decision and omit the blanket approval.
+- Bad: `.agents/brainstorm/export.md` or a transient log path in the final bug contract; Good: inline the selected behavior and exact relevant failure excerpt, and retain only a purpose-tagged stable code/interface path when execution must inspect it.
+- Bad: `所有问题都按你的推荐处理` as a fix constraint; Good: omit it as conversational authorization unless a concrete decision was separately confirmed.
+
 ## Fix Loop
 
 1. Present findings with IDs, severity, evidence, and suggested draft/source changes.
@@ -50,14 +77,15 @@ python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/pla
 ```
 
 5. Re-run validation/generation until valid. Do not hand-patch `.prizmkit/plans/bug-fix-list.json` as the source of truth.
-6. Repeat the local review only for entries changed by accepted fixes.
+6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
+7. Do not report `PASS` until every required fresh-session answer is available and final validation passes after regeneration.
 
 ## Report Format
 
 Report in the final handoff summary:
 
 - `Local generated-plan review: PASS` or `NEEDS_FIXES`
-- Reviewed bug IDs
+- Reviewed bug IDs and reviewed root prose (`project_description` / `global_context`) when applicable
 - Accepted fixes, or `none`
 - Final validation result
 - Note when review was not applicable because no new final planning content was written

package/bundled/skills/feature-planner/SKILL.md

@@ -48,29 +48,52 @@ The user chose this skill intentionally. Respect that choice.
 4. **NEVER auto-execute** the pipeline, launcher, composite workflow, or any implementation step
 5. Return the validated list to the caller; only `feature-pipeline-launcher` prepares the runtime command
 
-## User-Provided Content Priority (Hard Rule)
-
-When the user provides detailed specifications, rules, or implementation requirements:
-
-1. **Verbatim preservation**: The user's exact wording MUST be preserved in `description` and `acceptance_criteria` fields. Do NOT paraphrase, summarize, abstract, or simplify.
-2. **No autonomous simplification**: A 200-word user specification must NOT become a 30-word description. Match the detail level of the user's input.
-3. **Clarify, don't assume**: If any user-provided rule is ambiguous or potentially conflicts with another, ASK the user to clarify. No limit on clarification rounds. Do NOT proceed with unresolved ambiguities.
-4. **Task-scoped `user_context`**: In single-feature planning, write the relevant user-provided materials into that feature's `user_context`. In multi-feature planning, multi-feature `user_context` must contain only the user text, file references, and supplementary materials relevant to that specific feature.
-   - Preserve the matching user wording verbatim, but scope it to the item it belongs to.
-   - Do NOT copy the full multi-feature request into every feature.
-   - Ensure there are no unrelated sibling feature descriptions, file references, screenshots, or supplementary materials in a feature's `user_context`.
-   - Shared global context may be copied to every item only when it is explicitly applicable to all generated items.
-   - If a material applies to only one feature, attach it only to that matching feature.
-   - If applicability is unclear, ask the user to map the material to the correct feature before generating the final list.
-5. **`user_context` format**:
-   - Feature-specific supplementary content or rules → store as-is (verbatim text) on the matching feature only
-   - Feature-specific file references → store as path string, e.g. `src/auth/login.ts:42-78` or `src/utils/validate.ts — focus on validateEmail function`
-   - Truly shared global constraints → repeat only when they apply to every generated feature
+## Fresh-Session Task Contract (Hard Rule)
+
+Every new or changed feature is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
+
+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.
+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.
+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.
+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.
+
+### Artifact-Wide AI Readability
+
+- Every generated natural-language value must be a standalone domain statement. This applies to all AI-visible fields and sections, including `project_description`, `global_context`, titles, descriptions, acceptance criteria, rationales, `sub_features`, `completion_notes`, `testing`, `user_context`, evidence and environment text, browser verification goals, comments, appendices, and parentheticals.
+- Machine metadata such as schema markers, stable IDs, statuses, enums, and timestamps is exempt. Natural-language metadata is not exempt.
+- Never emit dialogue-role or chronology labels such as `user said`, `user answered`, `original request`, `this round`, `previous discussion`, `as discussed earlier`, `用户本轮回答`, or `如前面讨论`. Never emit planning question IDs, answer tokens, planning-option recommendation markers, checkpoint provenance, or raw internal answer-map entries as domain content.
+- `user_context` may hold independently intelligible evidence, not transcript fragments. Rewrite every confirmed turn into direct product behavior, constraints, rationale, or verification evidence before generation.
+
+### Conversational Context Normalization
+
+- Never persist standalone option labels such as `A`, `B`, `C`, `方案A`, or `方案B` as execution context.
+- Expand a selected option into its complete meaning and preserve substantive user rationale and constraints in durable prose at matching detail.
+- Do not emit transcript annotations such as `(original response: "...")` in final feature artifacts. Bare option labels and relative shorthand are not independently intelligible and materially useful exact wording.
+- Resolve relative statements such as `上面`, `这个`, `按推荐走`, `同前`, `继续这样`, `用刚才的方案`, `same as above`, or `go with your recommendation` only when there is one provable antecedent. If more than one antecedent is plausible, ask the user for clarification; never guess.
+- Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization. Apply the concrete accepted recommendations, then omit the raw approval; never repeat it once per accepted recommendation.
+- Do not present rejected alternatives as active instructions. Retain one only when its rejection defines a necessary non-goal. Retain exact user wording only when it is independently intelligible and materially useful.
+
+### Reference Material Handling
+
+- Every retained stable code, configuration, machine-consumed interface, or URL reference must be purpose-tagged: state why it is relevant and what the execution AI must inspect. This applies to paths and URLs in both the task contract and `user_context`.
+- Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`, uploaded-document paths, screenshot paths, or ad-hoc log paths in durable feature contracts. Instead, copy or normalize the task-relevant content into `description` and `acceptance_criteria`; the task must not depend on that source file still existing.
+- Good: `src/auth/login.ts:42-78 — inspect empty-password validation and the response-status transition`; Bad: `src/auth/login.ts:42-78` with no purpose.
+- For large materials such as issues, PRDs, logs, or documents, explain the purpose, preserve only task-relevant exact excerpts, and move every confirmed requirement into `description` and `acceptance_criteria`. Retain a location only when it is a stable execution-time source of truth.
+- Embed complete large materials only when the execution session cannot access the source and all content is genuinely required. Reference material never substitutes for the task contract.
+
+### Good and Bad Normalization Examples
+
+- Bad: `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation` stored alone.
+- Bad: `Selected decision: keep saved filters account-scoped (original response: "方案B")`; the annotation still requires an unseen option list.
+- Good: `Selected decision: keep saved filters account-scoped and sync them through the existing preferences API`.
+- Good: `Selected decision: use cursor pagination with a 50-item default and preserve current sort order`.
+- Bad: storing or repeating `全部按照推荐` / `所有问题都按你的推荐处理` as a feature requirement; it is conversational authorization, not execution context.
+- Bad: attaching an entire PRD or transient PRD path only to preserve wording. Good: state the confirmed retry and idempotency behavior directly in the feature contract; retain a purpose-tagged PRD URL only when it is a stable execution-time source of truth.
 
 **Multi-feature isolation example:**
 - User request includes: `Feature A: add saved filters to the dashboard`, `Feature B: export filtered results as CSV`, and `Shared: preserve existing auth permissions`.
-- The saved-filters feature `user_context` includes `Feature A: add saved filters to the dashboard` and the shared auth constraint; it MUST NOT include `Feature B: export filtered results as CSV`.
-- The CSV export feature `user_context` includes `Feature B: export filtered results as CSV` and the shared auth constraint; it MUST NOT include `Feature A: add saved filters to the dashboard`.
+- The saved-filters feature contract fully defines saved-filter behavior and includes only matching supplementary evidence plus the shared auth constraint; it MUST NOT include the CSV export request.
+- The CSV export feature contract fully defines export behavior and includes only matching supplementary evidence plus the shared auth constraint; it MUST NOT include the saved-filters request.
 
 ## When to Use
 
@@ -263,14 +286,14 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
    >
    > If none, we'll proceed with what's available in the codebase."
 
-   If the user provides materials, read/fetch them all before proceeding to Phase 2. For web links, use web fetch to retrieve and analyze the content. For images, read and analyze them visually. Record what was reviewed for traceability.
+   If the user provides materials, require or infer only when unambiguous a task-specific purpose for each material; otherwise ask what the execution AI should inspect. Read/fetch them before Phase 2. For web links, retrieve and analyze the relevant content; for images, analyze the relevant visual evidence. Material ingestion follows the same durability rule as final output: copy or normalize task-relevant requirements and exact evidence, omit transient non-code paths, and retain only purpose-tagged stable execution-time sources. Do not copy complete large materials merely to preserve them.
 2. Confirm constraints and existing architecture
 3. Propose feature set with dependencies
 4. Refine descriptions and acceptance criteria
-   4.1 **Per-feature clarification** — for each feature, if the description, acceptance criteria, or scope is vague or could be interpreted multiple ways, ask the user to clarify before finalizing.
+   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.
    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.
 5. Verify DAG/order/priorities and show the mandatory priority/complexity calibration table with short rationales for every item
-6. Pre-generation completeness review (see §Pre-Generation Completeness Review below)
+6. Run the pre-generation Headless Context Completeness Gate (see §Pre-Generation Completeness Review below)
 7. Build or append `.prizmkit/plans/feature-list.json`
 8. Apply default testing strategy (see §Testing Defaults below)
 9. Validate and fix until pass
@@ -288,7 +311,7 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
 | **CP-FP-3** | DAG Validity | No cycles, dependencies resolved (validation dry-run) | 5 |
 | **CP-FP-3.1** | Browser Interaction Applied | Qualifying features have `browser_interaction` field; user confirmed or opted out | 4 |
 | **CP-FP-3.2** | Testing Defaults Applied | All features have appropriate testing expectations and no retired `critic`/`critic_count` fields | 7 |
-| **CP-FP-3.3** | Completeness Review Passed | All features reviewed for description adequacy and cross-feature gaps | 6 |
+| **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 |
 | **CP-FP-4** | `.prizmkit/plans/feature-list.json` Generated | Schema validates, all required keys present | 7-8 |
 | **CP-FP-5** | Final Validation Pass | Python script returns `"valid": true` with zero errors | 9 |
 | **CP-FP-6** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed feature entries, applied accepted fixes through draft/source data, regenerated, and revalidated | 10 |
@@ -301,7 +324,7 @@ Before generating `.prizmkit/plans/feature-list.json`, review the full feature s
 
 → Read `${SKILL_DIR}/references/completeness-review.md` for the full review process (description adequacy scan, cross-feature completeness check, user presentation, and interactive supplementation).
 
-This gate ensures all features are implementation-ready before output generation. Thin descriptions here cost minutes to fix; misimplemented features downstream cost hours.
+This is the mandatory Headless Context Completeness Gate. It reviews every new or changed feature as if the reviewer has never seen the planning conversation and must return `NEEDS_FIXES` when any required artifact-alone question cannot be answered. It does not bulk-rewrite unchanged historical features. Thin descriptions here cost minutes to fix; misimplemented features downstream cost hours.
 
 ## Fast Path (Simple Incremental)
 
@@ -337,12 +360,13 @@ For simple incremental planning, skip detailed Phase 2-3 analysis:
    **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
 3. Generate next sequential feature IDs
 4. Draft features (title + description + acceptance_criteria + dependencies)
-5. Write draft to `.prizmkit/plans/feature-list.draft.json`, then call the generate script:
+5. Run the mandatory pre-generation Headless Context Completeness Gate from Phase 6 on every drafted feature; repair the draft until each returns `PASS`.
+6. Write draft to `.prizmkit/plans/feature-list.draft.json`, then call the generate script:
    ```bash
    python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json
    ```
-6. If valid → run the mandatory Local Generated-Plan Review Gate, then summarize and recommend next step
-7. If invalid → apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
+7. If valid → run the mandatory Local Generated-Plan Review Gate, then summarize and recommend next step
+8. If invalid → apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
 
 ## Browser Interaction Planning
 
@@ -379,7 +403,7 @@ Key requirements:
 - new items default `status: "pending"`
 - English feature titles for stable slug generation
 - `browser_interaction` auto-generated for qualifying frontend features (with `tool` selection: `auto`/`playwright-cli`/`opencli`)
-- descriptions: minimum 15 words (error), recommended minimum 30/50/80/100+ for low/medium/high/critical (warning). No upper limit — more detail prevents AI guessing
+- descriptions: minimum 15 words (error), recommended minimum 30/50/80/100+ for low/medium/high/critical (warning). No upper limit — preserve substantive requirements at matching detail so `description` plus `acceptance_criteria` remains complete without `user_context`
 - `estimated_complexity` records implementation scope and verification risk for planning summaries, ordering, and downstream context. It does not select a fixed agent count or named review topology; every normal feature session receives the runtime's full guidance.
 
 **IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
@@ -394,7 +418,7 @@ The script fills in defaults (`$schema`, `created_at`, `created_by`), validates
 
 Run this gate after `.prizmkit/plans/feature-list.json` passes generation and validation, and before the final handoff. It applies whenever this session added or changed final feature entries. For validate-only, summary-only, or draft-save flows with no final content change, report that the gate is not applicable.
 
-Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual draft and final artifacts directly because `.prizmkit` files may be gitignored. Keep the review planning-only, apply accepted findings to the draft/source representation, regenerate the final JSON, and require validation to pass again before reporting the review result.
+Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the actual draft and final artifacts directly because `.prizmkit` files may be gitignored. Repeat the Headless Context Completeness Gate for every reviewed new or changed feature. Keep the review planning-only, apply accepted findings to the draft/source representation, regenerate the final JSON, rerun validation, and repeat the local review until it returns `PASS` before reporting the result.
 
 ## Testing Defaults (Phase 8)
 
@@ -450,7 +474,7 @@ After successful validation and the Local Generated-Plan Review Gate, report:
 1. Output file path
 2. Total features + newly added features
 3. Dependency and priority highlights
-4. Local generated-plan review result: verdict, reviewed feature IDs, accepted fixes (or "none"), and final validation result
+4. Local generated-plan review result: verdict, reviewed feature IDs plus reviewed root prose when applicable, accepted fixes (or "none"), and final validation result
 5. Recommended next action: `feature-pipeline-launcher`
 
 Then apply the post-planning handoff in §Scope Boundary (ask before proceeding; never auto-execute).

package/bundled/skills/feature-planner/assets/planning-guide.md

@@ -57,19 +57,34 @@ Every description should cover these aspects (adapt per feature type):
 
 ### Headless Execution Requirements
 
-Feature descriptions are consumed by **autonomous AI sessions running in headless mode** — no human is available to clarify ambiguities. This raises the bar for description quality:
+Feature entries are consumed by **autonomous AI sessions running in headless mode** — no human is available to clarify ambiguities. Treat `description` plus `acceptance_criteria` as the complete task contract, not as a summary of a conversation.
 
 **Must include for headless readiness:**
-1. **Concrete deliverables** — specific files, endpoints, components, or models to create
-2. **Integration points** — which existing APIs to call, which models to import, which modules to extend
-3. **Key behaviors** — validation rules, state transitions, error codes, edge cases
+1. **Objective and current state** — the exact outcome and what exists today
+2. **Desired state and selected decisions** — the complete chosen behavior or approach, never only an option label
+3. **Constraints and non-goals** — boundaries the implementation must preserve
+4. **Relevant integrations** — existing APIs, models, modules, services, and dependency outputs
+5. **Edge cases** — validation, permissions, empty/error states, limits, concurrency, or idempotency when relevant
+6. **Completion evidence** — observable behavior and deterministic tests/checks that prove the feature is done
+
+`user_context` is supplementary evidence only. If `user_context` were removed, `description` and `acceptance_criteria` must still provide all six categories at matching detail.
 
 **Dependency descriptions:**
 When a feature depends on others, explicitly state what it needs from them:
-- ✅ "Uses the User model (id, email, display_name) from F-001 to create a foreign key user_id on the Project model"
-- ❌ "depends on F-001" — the AI won't know what F-001 built
+- Good: "Uses the User model (id, email, display_name) from F-001 to create a foreign key user_id on the Project model."
+- Bad: "depends on F-001" — the fresh session cannot infer what F-001 built.
+
+**Reference descriptions:**
+- Good: `src/billing/webhook.ts — inspect retry and idempotency behavior` for a stable execution target.
+- Bad: `.agents/brainstorm/billing.md §4 — inspect retry requirements`; copy the confirmed retry and idempotency requirements into the task contract and omit the transient planning path.
+- Bad: a full PRD copied into `user_context` without a purpose. Preserve only task-relevant exact excerpts, and never make the task depend on the non-code source still existing.
+
+**Decision normalization:**
+- Good: `Selected decision: store saved filters per account through the existing preferences API`.
+- Bad: `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation` with no complete selected meaning.
+- Bad: appending `(original response: "方案B")` or `(original response: "全部按照推荐")`; transcript provenance still requires an unseen prompt. Preserve substantive rationale in the decision prose, but omit blanket recommendation approval.
 
-**Self-test:** Read the description as if you have no other context. Could you implement it without asking a single question? If not, add more detail.
+**Self-test:** Review the entry as if you have never seen the planning conversation. Could you implement it and prove completion without asking a single question or reading `user_context`? If not, return `NEEDS_FIXES` and add the missing detail.
 
 ---