prizmkit 1.1.145 → 1.1.147

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

@@ -35,7 +35,7 @@ If you believe the task is better suited for a different workflow, you MUST:
 
 **Your ONLY writable outputs are:**
 1. `.prizmkit/plans/project-brief.md` (`.prizmkit/plans/` — accumulated project context brief)
-2. `.prizmkit/plans/project-brief.draft.md` — draft only when user exits before completion
+2. `.prizmkit/plans/project-brief.draft.md` — working source during planning and saved draft when the user exits before completion
 3. Project conventions and architecture decisions appended to `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` (with user consent)
 4. Infrastructure configuration (database conventions, deployment config, **cloud services**) appended to `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` `### Infrastructure` section
 5. `.prizmkit/rules/<layer>-rules.md` — per-layer development rules generated by Rules Configuration
@@ -56,6 +56,49 @@ If you believe the task is better suited for a different workflow, you MUST:
 4. **NEVER generate `feature-list.json`** — that is exclusively `feature-planner`'s responsibility
 5. Return the completed planning context to the caller. Direct implementation and planned pipeline execution are separate next steps; this planner is not an execution intermediary
 
+## Durable App Context Contract (Hard Rule)
+
+Every new or changed project brief line, convention, infrastructure decision, architecture decision, and rule must be understandable by a fresh AI session that has never seen the planning conversation. Durable app context records the actual selected product or technical decision, not the answer token used in chat.
+
+### Conversational Context Normalization
+
+- Never persist standalone option labels such as `A`, `B`, `C`, `方案A`, or `方案B`.
+- Expand each selected option into complete meaning and preserve its source inline: `Selected decision: <complete meaning> (original response: "<exact response>")`.
+- Resolve `上面`, `这个`, `按推荐走`, `同前`, `继续这样`, `用刚才的方案`, `same as above`, or `go with your recommendation` only when there is one provable antecedent. If multiple antecedents are plausible, ask the user for clarification; never guess.
+- Exclude conversational authorization such as `所有问题都按你的推荐处理` when it only controls planning behavior and does not constrain the product or implementation.
+- Do not present rejected alternatives as active decisions. Include one only when it defines a necessary non-goal or compatibility boundary.
+- Preserve detailed user requirements at matching detail; normalization must not simplify away substantive product, infrastructure, architecture, or development rules.
+
+### Reference Material Handling
+
+- Every retained file path, URL, screenshot, diagram, log, issue, PRD, or document reference must be purpose-tagged: say why it matters and what a downstream AI should inspect. This applies to paths and URLs in all app-planning artifacts.
+- Good: `docs/architecture.md §Authentication — inspect identity-provider ownership and session boundaries`; Bad: `docs/architecture.md` alone.
+- For large materials, record title/location and purpose, preserve only task-relevant exact excerpts, and move confirmed product or technical decisions into the durable app-planning artifact.
+- Embed complete large materials only when future sessions 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`.
+- Good: `[ ] Authentication uses organization-scoped OAuth with server-side sessions (original response: "方案B")`.
+- Good: `Deployment target: managed container service with PostgreSQL in the same region (original response: "use option A")`.
+- Bad: storing `所有问题都按你的推荐处理` as a project convention; it is conversational authorization.
+- Bad: attaching an entire infrastructure proposal while recording only `follow this`. Good: retain a purpose-tagged proposal section and task-relevant exact excerpts, then name the actual network, database, and deployment decisions.
+
+## Pre-Generation Headless Context Completeness Gate
+
+Before any final app-planning writer runs, review every new or changed brief line, convention, infrastructure decision, architecture decision, and rule as if the reviewer has never seen the planning conversation. Preserve unchanged historical content; do not bulk-rewrite it. From the proposed artifact alone, answer:
+
+1. What exact product outcome or technical decision does this line record?
+2. What exists today and what desired state or constraint applies?
+3. Which approach was selected, expressed by meaning rather than an option label?
+4. What constraints and non-goals must downstream work preserve?
+5. Why is each reference material relevant, and what should be inspected?
+6. How will downstream planning or implementation know the decision has been honored?
+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` whenever any answer is unavailable or ambiguous. Ask the user for clarification rather than guessing, update the draft/source representation, and rerun the gate before writing final artifacts. This pre-generation gate is separate from the Local Generated-Plan Review, which repeats the same simulation after final writes.
+
 ## When to Use
 
 The skill `description` lists the trigger phrases. Beyond those, use this section to disambiguate from `feature-planner` and other workflows.
@@ -85,18 +128,18 @@ Do NOT use this skill when:
 
    → Read `${SKILL_DIR}/references/project-conventions-discovery.md` for the full AI-driven discovery procedure (Analyze → Reason → Present via AskUserQuestion).
 
-   → Save answers to `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` under `### Project Conventions` section (format: one bullet per convention)
+   → Run the Pre-Generation Headless Context Completeness Gate on each proposed convention, then save passing answers to `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` under `### Project Conventions` section (format: one bullet per convention)
    → Output format will naturally vary per project — that is the intended behavior
 
    **Infrastructure Convention Discovery (Database + Deployment)**
 
    After project conventions are captured, check the project instruction file for `### Infrastructure` section status. Read `${SKILL_DIR}/references/infrastructure-convention-discovery.md` for the full database (6 topics — table naming, field naming, migrations, primary keys, indexes, environment separation), deployment (4 topics — target refinement, existing infrastructure, AI-assisted deploy, env var management), and cloud services (2-round AskUserQuestion) inquiry procedures. Follow the inquiry flow there — use `AskUserQuestion` for each batch. Each question MUST include a "Skip — decide later" option.
 
-   After inquiry, update the `### Infrastructure` section in the project instruction file with all collected information (see reference file for full output format). Items still marked "Skip — decide later" remain as `<!-- [topic]: deferred -->` for `prizmkit-deploy` to pick up later.
+   After inquiry, run the Pre-Generation Headless Context Completeness Gate on every proposed infrastructure decision, then update the `### Infrastructure` section in the project instruction file with passing content (see reference file for full output format). Items still marked "Skip — decide later" remain as `<!-- [topic]: deferred -->` for `prizmkit-deploy` to pick up later.
 
 4. **Project brief accumulation** — throughout all interactive phases:
    → Read `${SKILL_DIR}/references/project-brief-guide.md` for template and rules
-   → Update after each meaningful user response containing business intent, constraints, or design decisions
+   → Update the in-memory or `.prizmkit/plans/project-brief.draft.md` source after each meaningful user response containing business intent, constraints, or design decisions; do not write the final `.prizmkit/plans/project-brief.md` until the Pre-Generation Headless Context Completeness Gate passes
 
 ## Rules Configuration (after Infrastructure)
 
@@ -104,7 +147,7 @@ After Infrastructure configuration is complete (CP-AP-1.5), check whether the pr
 
 Rules are optional. If the user skips, AI uses general best practices freely — no reminders, no blocking.
 
-→ Read `${SKILL_DIR}/references/rules-configuration.md` for the full procedure: layer detection, configuration mode selection, interactive Q&A per layer, template rendering, and root.prizm RULES pointer update.
+→ Read `${SKILL_DIR}/references/rules-configuration.md` for the full procedure: layer detection, configuration mode selection, interactive Q&A per layer, template rendering, and root.prizm RULES pointer update. Before rendering final rule files or updating the pointer, run the Pre-Generation Headless Context Completeness Gate on every proposed new or changed rule.
 
 ### After rules configuration
 
@@ -179,9 +222,9 @@ Route by answer:
 - **Generate project context only** → Enter **Quick Context Mode** (brownfield only):
   - Run Project State Detection → if greenfield, redirect to produce mode
   - Proactively scan the project (same as brownfield behavior)
-  - Generate project-brief.md from inferred context
+  - Generate the proposed project brief in memory or `.prizmkit/plans/project-brief.draft.md` from inferred context
   - Skip extensive brainstorming and constraint phases
-  - Present brief for user confirmation → write → run CP-AP-6 Generated App-Plan Review Gate → completion summary
+  - Run the Pre-Generation Headless Context Completeness Gate → Present brief for user confirmation → write → run CP-AP-6 Generated App-Plan Review Gate → completion summary
 
 Session goal tracking: Track the intent (`produce`, `explore`, or `quick_context`) throughout the session. If `explore`, always re-prompt before ending.
 
@@ -224,7 +267,7 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
    2.2 **Frontend design check** (for frontend projects) — scan for existing UI/UX design docs. If none found, use `AskUserQuestion`:
        - Question: "No UI/UX design docs found. Would you like to establish design direction?"
        - Options: "Establish design direction now (Recommended)", "Skip for now", "I have external designs"
-3. Capture architecture decisions and finalize project brief
+3. Capture architecture decisions, run the Pre-Generation Headless Context Completeness Gate on every proposed new or changed app-planning line, and finalize project brief only after the gate passes
 4. Present completion summary with artifacts produced and possible next steps
 
 ### Checkpoints (Mandatory Gates)
@@ -239,20 +282,21 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
 | **CP-AP-1.6** | Rules Configured | For each detected layer (from config.json or self-detection), rules file exists in `.prizmkit/rules/` or user explicitly skipped. `root.prizm` `RULES:` pointer up-to-date. | 2 |
 | **CP-AP-2** | Vision Summary | Goal/users/differentiators confirmed by user. For brownfield: existing purpose confirmed or refined. | 1-2 |
 | **CP-AP-3** | Frontend Design Evaluated | For frontend projects: checked for existing UI/UX design system; user was asked if missing. **Auto-pass** for backend-only or non-UI projects. | 2 |
-| **CP-AP-4** | Project Brief Accumulated | `.prizmkit/plans/project-brief.md` exists at `.prizmkit/plans/` with at least 3 ideas listed. For brownfield: already-implemented items marked `[x]` count toward this total. | 3 |
-| **CP-AP-5** | Planning Complete | All project-level context captured: conventions, infrastructure config, tech stack, architecture decisions, project brief finalized | 4 |
-| **CP-AP-6** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, directly reviewed current-session final app-planning artifacts, applied accepted fixes through source/writer paths, and rechecked changed sections | 4 |
+| **CP-AP-4** | Project Brief Accumulated | The in-memory brief or `.prizmkit/plans/project-brief.draft.md` contains at least 3 ideas. For brownfield: already-implemented items marked `[x]` count toward this total. The final brief is not written before CP-AP-5.5. | 3 |
+| **CP-AP-5** | Planning Complete | All project-level context captured: conventions, infrastructure config, tech stack, architecture decisions, project brief drafted | 4 |
+| **CP-AP-5.5** | Fresh-Session Context Passed | Every new or changed brief line, convention, infrastructure decision, architecture decision, and rule passes the Pre-Generation Headless Context Completeness Gate before its final writer runs | 4 |
+| **CP-AP-6** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, directly reviewed current-session final app-planning artifacts, repeated fresh-session simulation, applied accepted fixes through source/writer paths, and rechecked changed sections | 4 |
 
 ## Generated App-Plan Review Gate
 
 User requirement preserved verbatim: `Add generated-plan review in app-planner also .`
 
-Run this gate before any final handoff whenever the current `app-planner` session wrote or rewrote final app-level planning content. In full produce mode this runs after CP-AP-5; in Quick Context Mode it runs after the confirmed `.prizmkit/plans/project-brief.md` write; in conventions, infrastructure, architecture-decision, or rules-only final-write flows it runs after those writes and before the completion summary. This gate reviews generated planning artifacts directly, not implementation diffs.
+Run this gate before any final handoff whenever the current `app-planner` session wrote or rewrote final app-level planning content. In full produce mode this runs after CP-AP-5.5 and the passing content's final writes; in Quick Context Mode it runs after the confirmed `.prizmkit/plans/project-brief.md` write; in conventions, infrastructure, architecture-decision, or rules-only final-write flows it runs after those writes and before the completion summary. This gate reviews generated planning artifacts directly, not implementation diffs.
 
 1. **Load the local reference**: read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the source of truth for app-planner generated content review.
 2. **Read actual planning artifacts directly**: inspect current-session final outputs such as `.prizmkit/plans/project-brief.md`, selected `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` sections, `.prizmkit/rules/<layer>-rules.md`, and `.prizmkit/prizm-docs/root.prizm` `RULES:` pointer line. Do not rely on `git status`, `git diff`, or `git diff --cached`, because `.prizmkit` planning artifacts are often gitignored or untracked.
 3. **Scope to new/changed app-planning content**: compare against pre-session snapshots or in-memory drafts when available. Preserve unchanged historical brief items, instruction-file sections, rules files, and Prizm doc content. For explore-only sessions, draft-save exits, or flows with no new final planning content, report: `Local generated-plan review: not applicable — no new final planning content written.`
-4. **Run the local checklist** from the reference: project brief completeness, consistency of conventions/infrastructure/architecture decisions, rules pointer consistency, user-provided wording preservation, app-planner writable-boundary compliance, and downstream `feature-planner` readiness to produce `.prizmkit/plans/feature-list.json` without guessing.
+4. **Run the local checklist and fresh-session simulation** from the reference: project brief completeness, consistency of conventions/infrastructure/architecture decisions, rules pointer consistency, normalization of selected decisions, purpose-tagged references, app-planner writable-boundary compliance, and downstream `feature-planner` readiness to produce `.prizmkit/plans/feature-list.json` without guessing or seeing the original conversation.
 5. **Apply accepted fixes through the source/writer path**: project brief fixes go through the draft/checklist source, instruction-file section fixes go through the selected platform instruction file section source with user confirmation when changing approved wording, rules fixes re-render from rules configuration answers/templates when available, and `root.prizm` fixes are limited to the `RULES:` pointer line.
 6. **Recheck changed sections directly** after every accepted fix batch.
 7. **Report CP-AP-6** in the completion summary: include local generated-plan review verdict, reviewed app-planning artifacts/sections, accepted fixes (or "none"), and final writer/validation result.
@@ -262,13 +306,13 @@ Run this gate before any final handoff whenever the current `app-planner` sessio
 After Phase 2, if framework-shaping architecture decisions emerged during planning (tech stack, communication patterns, data model strategies — not individual feature details), read `${SKILL_DIR}/references/architecture-decisions.md` and follow the capture flow. Most sessions will NOT produce architecture decisions — only capture when genuinely impactful.
 
 **How it works**:
-1. If decisions are captured → append to `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` under `### Architecture Decisions` section
+1. If decisions are captured → run the Pre-Generation Headless Context Completeness Gate on each decision, then append passing decisions to `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` under `### Architecture Decisions` section
 2. Downstream skills (feature-planner, prizmkit-plan, etc.) read `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` as standard context, so they automatically receive these decisions
 3. Do NOT write architecture decision content directly to `.prizmkit/prizm-docs/root.prizm` — that file is maintained by `prizmkit-prizm-docs` and `prizmkit-retrospective`. (The `RULES:` pointer line is managed by Rules Configuration, not by this section.) If the project needs `.prizmkit/prizm-docs/`, recommend the user run `prizmkit-prizm-docs` init after planning.
 
 ## Project Brief Accumulation
 
-During interactive planning, maintain a `.prizmkit/plans/project-brief.md` at `.prizmkit/plans/` as a simple checklist of product ideas.
+During interactive planning, maintain the proposed brief in memory or `.prizmkit/plans/project-brief.draft.md` as a simple checklist of product ideas. After the Pre-Generation Headless Context Completeness Gate passes, write the final `.prizmkit/plans/project-brief.md` through the project brief writer path.
 
 → Read `${SKILL_DIR}/references/project-brief-guide.md` for full format and rules.
 

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

@@ -44,17 +44,44 @@ For every reviewed app-planning artifact or section, check:
 - Consistency among conventions, infrastructure, architecture decisions, and project brief content
 - Infrastructure completeness or explicit deferral for database, deployment, and cloud services topics when those flows ran
 - Rules pointer consistency: generated `.prizmkit/rules/<layer>-rules.md` files are referenced by the `root.prizm` `RULES:` line when rules were configured
-- User-provided wording preservation in project brief ideas, conventions, infrastructure notes, architecture decisions, and rules
+- User-provided wording preservation and detail preservation at matching detail after conversational normalization in project brief ideas, conventions, infrastructure notes, architecture decisions, and rules
+- Every selected product or technical decision is expressed by complete meaning rather than `A`, `B`, `C`, `方案A`, `方案B`, or another unseen option label; whenever the selection originated as shorthand, the original response is preserved inline for traceability
+- Purpose-tagged paths and URLs, screenshots, diagrams, logs, issues, PRDs, and documents; large materials retain title/location, purpose, and task-relevant exact excerpts rather than full-content injection
+- Conversational authorization is excluded when it controls planning but does not constrain implementation; rejected alternatives appear only as necessary non-goals
 - Downstream readiness: `feature-planner` has enough context to produce `.prizmkit/plans/feature-list.json` without guessing core app purpose, stack, constraints, or implementation conventions
 - No implementation/scaffolding actions are introduced by the app plan; outputs stay within app-planner's writable boundary
 
+## Headless Context Completeness Gate
+
+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. From the artifact alone, answer:
+
+1. What exact product outcome or technical decision does this content record?
+2. What exists today and what desired state or constraint applies?
+3. Which approach was selected, expressed by meaning rather than an option label?
+4. What constraints and non-goals must downstream work preserve?
+5. Why is each reference material relevant?
+6. How will downstream planning or implementation know the decision was honored?
+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, or dependent on shorthand such as `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation`. Accept an expanded decision only when it states complete meaning with inline traceability such as `(original response: "方案B")`. Ask the user for clarification when there is not one provable antecedent. Exclude `所有问题都按你的推荐处理` and equivalent conversational authorization unless a concrete implementation constraint was separately confirmed.
+
+Apply this stricter gate prospectively to new or changed content and preserve unchanged historical app-planning content.
+
+### Good and Bad Review Examples
+
+- Bad: `[ ] 使用方案B`; Good: `[ ] Authentication uses organization-scoped OAuth with server-side sessions (original response: "方案B")`.
+- Bad: a bare architecture URL; Good: `Architecture RFC §5 — inspect identity ownership and session boundaries`, plus only task-relevant exact excerpts.
+- Bad: a rejected serverless alternative listed as an active infrastructure decision; Good: include it only as a non-goal when preserving the selected container deployment boundary requires that fact.
+
 ## Fix Loop
 
 1. Present findings with artifact path, section name, severity, evidence, and suggested source change.
 2. Accept only findings that improve planner correctness, consistency, user wording preservation, or downstream feature-planner readiness.
 3. Apply accepted fixes to the source representation first: brief draft/checklist, instruction-file section source, rules answer/template source, or `root.prizm` `RULES:` pointer source.
 4. Regenerate or rewrite final artifacts through the same writer path used by app-planner. Do not hand-patch final artifacts as a shortcut when a draft/source representation exists.
-5. Re-read the changed final artifacts directly and re-run the local review only for changed sections.
+5. Re-read the changed final artifacts directly and repeat the Headless Context Completeness Gate only for changed sections.
+6. Do not report `PASS` until every required fresh-session answer is available and each changed artifact passes its final writer/validation check.
 
 ## Report Format
 

package/bundled/skills/app-planner/references/project-brief-guide.md

@@ -28,8 +28,16 @@
    - Change `[ ]` to `[x]`
    - Append `->` followed by the **key file or directory paths** that implement it
    - List the most important 1-3 paths only (entry point, core module, or directory) — not every touched file
-   - Example: `[x] User authentication with OAuth -> src/auth/, src/middleware/auth.ts`
-   - This lets future AI sessions instantly locate the implementation without re-scanning
+   - Purpose-tag every retained path so a fresh session knows what to inspect
+   - Good: `[x] User authentication uses organization-scoped OAuth with server-side sessions -> src/auth/ — inspect provider/session ownership; src/middleware/auth.ts — inspect request authorization`
+   - Bad: `[x] User authentication -> src/auth/, src/middleware/auth.ts` because neither the selected behavior nor path purpose is clear
+   - This lets future AI sessions locate the implementation without guessing or broad rescanning
+7. **Complete decision meaning**: Every line names the actual product or technical decision. Never write only `A`, `B`, `C`, `方案A`, `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation`.
+8. **Traceability**: Whenever a selection originated as shorthand, expand it into meaning and retain the original response inline: `[ ] Authentication uses organization-scoped OAuth with server-side sessions (original response: "方案B")`.
+9. **Ambiguous references**: Resolve shorthand only with one provable antecedent. Otherwise ask the user for clarification; never guess.
+10. **Conversational authorization**: Exclude statements such as `所有问题都按你的推荐处理` when they control planning behavior but do not constrain the product or implementation.
+11. **References**: Require purpose-tagged paths and URLs, documents, screenshots, diagrams, and logs. For large materials, retain title/location, purpose, and task-relevant exact excerpts; move confirmed decisions into the brief instead of embedding complete large materials.
+12. **Alternatives**: Do not present rejected alternatives as active brief items; include them only as necessary non-goals.
 
 ## Brownfield Init
 
@@ -76,7 +84,18 @@ If the user gives short/vague answers, don't accept them — rephrase and ask ag
 
 ### Generate & Confirm
 Once all criteria are met:
-1. Generate brief in checklist format (see Format section above)
-2. Present to user with: "Here's what I captured — anything to add, remove, or change?"
-3. Apply edits and write to `.prizmkit/plans/project-brief.md`
+1. Generate the proposed brief in checklist format (see Format section above).
+2. Run the app-planner Pre-Generation Headless Context Completeness Gate on every new or changed line as if the reviewer has never seen the planning conversation. Confirm the actual outcome/current state/desired state, selected meaning, constraints/non-goals, reference relevance, downstream completion signal, absence of unseen conversational dependencies, and that quoted source materials agree with the final task decision.
+3. Return `NEEDS_FIXES` for any unanswered question, update the draft/source line, and repeat until all changed lines pass. Preserve unchanged historical brief items.
+4. Present to user with: "Here's what I captured — anything to add, remove, or change?"
+5. Apply edits, rerun the gate for modified lines, and write `.prizmkit/plans/project-brief.md` only after `PASS`.
+
+### Good and Bad Brief Examples
+
+- Bad: `[ ] 使用方案B`.
+- Good: `[ ] Authentication uses organization-scoped OAuth with server-side sessions (original response: "方案B")`.
+- Bad: `[ ] same as above` when several prior decisions exist.
+- Good: ask the user which decision applies, then record its complete meaning.
+- Bad: `[ ] Follow https://example.test/platform-rfc`.
+- Good: `[ ] Deployment uses a managed container service with regional PostgreSQL; Platform RFC §3 — inspect region and failover constraints`.
 

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

@@ -40,29 +40,43 @@ 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.
+
+### 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 with inline traceability: `Selected decision: <complete meaning> (original response: "<exact response>")`.
+- Resolve `上面`, `这个`, `按推荐走`, `同前`, `继续这样`, `用刚才的方案`, `same as above`, or `go with your recommendation` only when there is one provable antecedent. Otherwise ask the user for clarification; never guess.
+- Exclude conversational authorization such as `所有问题都按你的推荐处理` when it controls planning behavior but does not constrain the fix.
+- Do not present rejected root-cause or fix alternatives as active instructions; preserve one only when it defines a necessary non-goal.
+
+### Reference Material Handling
+
+- Every retained file path, URL, screenshot, log, stack trace, or document 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`.
+- Good: `logs/api-500.log lines 220-248 — inspect the empty-password request, exception, and correlation ID`; Bad: `logs/api-500.log` alone.
+- For large materials, record title/location and purpose, preserve only task-relevant exact excerpts, and move confirmed expected behavior, selected scope, severity rationale, and verification decisions into `description` and `acceptance_criteria`.
+- 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.
+- Good: `Selected decision: reject empty passwords in request validation with HTTP 400 and do not enter credential verification (original response: "方案B")`.
+- Good: `Selected decision: reproduce against the API integration test and retain UI verification as a regression check (original response: "use option A")`.
+- Bad: storing `所有问题都按你的推荐处理` as a bug constraint; it is conversational authorization.
+- Bad: attaching a complete production log while saying only `fix this`. Good: retain the relevant exception excerpt and purpose-tagged log location, then state actual behavior, expected behavior, scope, and verification in the task contract.
 
 **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 +194,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. Preserve purpose-tagged locations and task-relevant exact excerpts, but do not inject complete large materials merely for verbatim preservation.
 
 Output: `project_name`, `project_description`, `global_context` fields populated.
 
@@ -205,7 +219,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 +259,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. First 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 +283,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 +294,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 +320,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 +366,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 +385,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
 

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

@@ -31,13 +31,38 @@ 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
 - 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 paths and URLs, screenshots, logs, stack traces, and documents; large materials retain title/location, purpose, and task-relevant exact excerpts rather than full-content injection
 - 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. 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`. Accept an expanded decision only when it states complete meaning with inline traceability such as `(original response: "方案B")`. Exclude conversational authorization that does not constrain implementation. 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; Good: `Selected decision: classify as medium because export is incorrect but a JSON workaround exists; verify with the existing Unicode export test (original response: "按推荐走")`.
+- Bad: a bare log path; Good: `logs/export.log lines 90-118 — inspect encoding selection and the emitted response header` plus only task-relevant exact excerpts.
+- 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,7 +75,8 @@ 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