prizmkit 1.1.146 → 1.1.147

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.146",
-  "bundledAt": "2026-07-23T01:20:01.078Z",
-  "bundledFrom": "248d714"
+  "frameworkVersion": "1.1.147",
+  "bundledAt": "2026-07-23T04:05:31.031Z",
+  "bundledFrom": "5238680"
 }

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.146",
+  "version": "1.1.147",
   "skills": {
     "prizmkit": {
       "description": "Framework introduction and navigation for the formal single-requirement lifecycle, project initialization, Prizm docs, and independent deployment.",

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
 

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

@@ -48,29 +48,43 @@ 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.
+
+### 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 the original response inline for traceability: `Selected decision: <complete meaning> (original response: "<exact response>")`.
+- 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.
+- Exclude conversational authorization such as `所有问题都按你的推荐处理` when it only controls how the planner asks or recommends and does not constrain implementation.
+- Do not present rejected alternatives as active instructions. Retain one only when its rejection 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 must inspect. This applies to paths and URLs in both the task contract and `user_context`.
+- 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, record the title/location, explain the purpose, preserve only task-relevant exact excerpts, and move every confirmed requirement into `description` and `acceptance_criteria`.
+- 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.
+- Good: `Selected decision: keep saved filters account-scoped and sync them through the existing preferences API (original response: "方案B")`.
+- Good: `Selected decision: use cursor pagination with a 50-item default and preserve current sort order (original response: "use option A")`.
+- Bad: storing `所有问题都按你的推荐处理` as a feature requirement; it is conversational authorization, not execution context.
+- Bad: attaching an entire PRD only to preserve wording. Good: `Billing PRD §4 — inspect retry and idempotency rules`, include the relevant exact excerpt, and restate the confirmed retry behavior in the feature contract.
 
 **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 +277,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. Record purpose-tagged locations and task-relevant exact excerpts for traceability, but do not copy complete large materials into generated items 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 +302,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 +315,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 +351,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 +394,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 +409,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)
 

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

@@ -57,19 +57,32 @@ 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: `docs/billing-prd.md §4 — inspect webhook retry and idempotency requirements`; preserve only task-relevant exact excerpts and place confirmed behavior in the task contract.
+- Bad: `docs/billing-prd.md` or a full PRD copied into `user_context` without a purpose.
+
+**Decision normalization:**
+- Good: `Selected decision: store saved filters per account through the existing preferences API (original response: "方案B")`.
+- Bad: `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation` with no complete selected meaning.
 
-**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.
 
 ---
 

package/bundled/skills/feature-planner/references/completeness-review.md

@@ -1,57 +1,75 @@
 # Pre-Generation Completeness Review
 
-Before generating `.prizmkit/plans/feature-list.json`, review the full feature set holistically. Individual features may look fine in isolation but have gaps when viewed together.
+## Headless Context Completeness Gate
 
-## Step 1: Description Adequacy Scan
+Before generating `.prizmkit/plans/feature-list.json`, review every new or changed feature as if the reviewer has never seen the planning conversation. Preserve unchanged historical entries; do not bulk-rewrite them. Individual features may look plausible in the original dialogue but still be unusable in a fresh session.
 
-For each feature, evaluate against the word-count thresholds in `planning-guide.md`:
-- Does the description cover: what to build, key behaviors, integration points, data model (if applicable), error/edge cases?
-- Is the description specific enough for an AI coding session to implement without guessing?
-- Flag any feature below the recommended minimum word count for its complexity level (30+/50+/80+/100+ words for low/medium/high/critical). There is no upper limit — more detail is always better.
+The review input is the proposed artifact entry itself. `user_context` is supplementary evidence only: first assess `description` plus `acceptance_criteria` without it, then inspect supplementary evidence for scope and consistency.
 
-**Implementation clarity check** — Every feature description will be consumed by an autonomous AI session. Verify each description specifies:
-1. Concrete deliverables (files to create, endpoints to build, components to implement, models to define)
-2. Key behaviors and business rules (validation, state transitions, error handling)
-3. Integration points with other modules (which APIs to call, which models to use)
+## Step 1: Artifact-Alone Fresh-Session Simulation
 
-**Dependency context check** — If the feature depends on others, the description should reference what it needs from them:
-- Good: "Uses User model from F-001 to link projects to users via userId foreign key"
-- Bad: "depends on F-001" (too vague)
+For each new or changed feature, answer all of these from `description` and `acceptance_criteria` alone:
 
-**Ambiguity check** — Flag vague phrases:
-- Bad: "Create a nice dashboard" (what components? what data? what layout?)
-- Good: "Create dashboard at /dashboard with: (1) summary cards showing total projects count, active tasks count; (2) recent activity feed (last 10 items); (3) quick-access project list (5 most recent). Fetch data via GET /api/dashboard/summary."
+1. What exact problem or outcome is this feature responsible for?
+2. What exists today and what must change?
+3. Which approach was selected, expressed by meaning rather than an option label?
+4. What constraints and non-goals must be preserved?
+5. Which existing modules, APIs, data, dependencies, or other relevant integrations are involved?
+6. Which edge cases, errors, permissions, limits, state transitions, or failure modes matter?
+7. How can completion be verified with observable behavior or deterministic evidence?
+8. Does any phrase require an unseen earlier question, recommendation, or option list?
+9. Why is each reference material relevant, and what should the execution AI inspect?
+10. Do quoted source materials agree with the final task decision?
 
-If any feature description is unclear, **expand it now** before generating the output file.
+If any answer is unavailable, ambiguous, or present only in `user_context`, the verdict is `NEEDS_FIXES`. Never infer a missing decision from conversation memory.
 
-## Step 2: Cross-Feature Completeness Check
+## Step 2: Contract and Material Checks
+
+- Preserve substantive user requirements at matching detail; normalization must not collapse a detailed specification into a short summary.
+- Expand option shorthand into complete selected meaning with inline traceability, for example: `Selected decision: use cursor pagination with a 50-item default (original response: "use option A")`.
+- Resolve `方案B`, `按推荐走`, `same as above`, or `go with your recommendation` only when there is one provable antecedent. Otherwise ask the user for clarification.
+- Exclude conversational authorization that controls planning but does not constrain implementation.
+- Do not present rejected alternatives as active requirements; retain them only as necessary non-goals.
+- Require purpose-tagged paths and URLs, screenshots, logs, stack traces, and documents.
+- For large materials, preserve title/location, purpose, and task-relevant exact excerpts; move confirmed requirements into the task contract rather than embedding the entire source.
+- If `user_context` were removed, `description` and `acceptance_criteria` must remain sufficient for execution and verification.
+
+### Good and Bad Examples
+
+- Bad: `方案B`.
+- Good: `Selected decision: keep saved filters account-scoped and sync through the existing preferences API (original response: "方案B")`.
+- Bad: `same as above` when multiple earlier decisions exist.
+- Good: ask which earlier decision applies, then record its complete meaning.
+- Bad: `docs/search-rfc.md`.
+- Good: `docs/search-rfc.md §3 — inspect ranking tie-breakers and empty-query behavior`.
+- Bad: copy a complete issue into `user_context` while leaving the feature description as `implement the issue`.
+- Good: retain the issue URL and relevant exact excerpts as evidence, then state all confirmed behavior and completion checks in the feature contract.
+
+## Step 3: Cross-Feature Completeness Check
 
 Look at the feature set as a whole:
-- **Implied functionality gaps**: Does feature A's acceptance criteria assume a capability that no other feature provides?
-- **Missing integration seams**: If two features share data or interact at runtime, is the interface specified?
-- **Scope leaks**: Does any feature's description reference functionality outside the agreed scope?
 
-## Step 3: Present Review to User
+- **Implied functionality gaps**: Does one feature assume a capability that no feature provides?
+- **Missing integration seams**: If two features share data or interact at runtime, is the interface specified by meaning?
+- **Dependency context**: Does each dependent feature state exactly which predecessor output it consumes?
+- **Scope leaks**: Does a description activate rejected or out-of-scope functionality?
+- **Source conflict**: Does an excerpt describe an earlier alternative that conflicts with the selected final decision?
 
-Show a structured summary table:
+## Step 4: Present Review and Repair
 
-```
-Feature    | Description | Cross-Feature        | Recommendation
-           | Adequacy    | Issues               |
-F-001      | ✓ (65 words)| —                    | Ready
-F-002      | ⚠ (28 words)| —                    | Expand: add API endpoints, error handling
-F-003      | ✓ (52 words)| Assumes email from   | Clarify: who sends the notification?
-           |             | F-006 (not yet defined)|
-```
+Show a structured summary:
 
-Then ask if any features need further discussion.
+```text
+Feature | Artifact-Alone Answers | References | Cross-Feature Issues | Verdict
+F-001   | complete               | purposeful | none                 | PASS
+F-002   | missing current state  | URL vague  | none                 | NEEDS_FIXES
+```
 
-## Step 4: Interactive Supplementation
+For each `NEEDS_FIXES` item:
 
-For each feature the user wants to discuss:
-1. Ask targeted questions about the unclear aspects
-2. Propose concrete description supplements
-3. Update the feature description with agreed details
-4. Re-check: does the supplement resolve the gap?
+1. Ask targeted clarification when the missing meaning cannot be proven from one antecedent.
+2. Update the draft/source feature, not only `user_context`.
+3. Re-run this gate on the changed item.
+4. Continue until every new or changed feature returns `PASS`.
 
-Continue until the user confirms all features are implementation-ready. Fixing thin descriptions here costs minutes; fixing misimplemented features downstream costs hours.
+Only then may generation proceed. Structural validation after generation does not replace this semantic gate.

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

@@ -31,13 +31,38 @@ For every reviewed feature entry, check:
 
 - Schema compatibility with `dev-pipeline-feature-list-v1` and `.prizmkit/dev-pipeline/templates/feature-list-schema.json`
 - Dependency/DAG soundness: dependencies exist, no cycles, no poorly ordered prerequisite chains
-- Description completeness and headless execution readiness
+- Description completeness and headless execution readiness: `description` plus `acceptance_criteria` defines objective, current state, desired state, selected decisions, constraints, non-goals, relevant integrations, edge cases, and completion evidence without conversation history
 - Acceptance criteria specificity, measurability, and coverage of the described behavior
-- 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 task contract; if `user_context` were removed, execution and verification remain unambiguous
 - Task-scoped `user_context` isolation: no unrelated sibling feature descriptions, file references, or supplementary materials; shared context appears on multiple items 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
 - Priority/complexity calibration: every reviewed feature has short priority and complexity rationales, medium/low assignments are allowed when criteria fit, and high/high is not used merely because work is framework-related, multi-file, or user-requested
 - Browser interaction fields for qualifying frontend/fullstack features when applicable
 
+## Headless Context Completeness Gate
+
+Repeat the pre-generation simulation for every reviewed new or changed feature 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?
+3. Which approach was 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 includes complete meaning and 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 plans.
+
+### Good and Bad Review Examples
+
+- Bad: `same as above`; Good: the complete selected API behavior plus `(original response: "same as above")` after its single antecedent is proven.
+- Bad: a bare URL; Good: `https://example.test/search-rfc — inspect ranking tie-breakers and empty-query behavior` plus only task-relevant exact excerpts.
+- Bad: `所有问题都按你的推荐处理` as an implementation rule; Good: omit it as conversational authorization unless a concrete selected 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-and-generate.py generate --input .prizmkit
 ```
 
 5. Re-run validation/generation until valid. Do not hand-patch `.prizmkit/plans/feature-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
 

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

@@ -45,29 +45,43 @@ The user chose this skill intentionally. Respect that choice.
 5. **NEVER auto-execute** the pipeline, launcher, composite workflow, or any implementation step
 6. Return the validated refactor list to the caller; only `refactor-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-refactor planning, write the relevant user-provided materials into that refactor item's `user_context`. In multi-refactor planning, multi-refactor `user_context` must contain only the user text, file references, goals, and constraints relevant to that specific refactor item.
-   - Preserve the matching user wording verbatim, but scope it to the item it belongs to.
-   - Do NOT copy the full multi-refactor request into every item.
-   - Ensure there are no unrelated sibling refactor goals, target files, constraints, desired end states, or supplementary materials in a refactor item's `user_context`.
-   - Shared global context may be copied to every item only when it is explicitly applicable to all generated items.
-   - If a goal, constraint, target file, or architecture note applies to only one refactor item, attach it only to that matching item.
-   - If applicability is unclear, ask the user to map the material to the correct refactor item before generating the final list.
-5. **`user_context` format**:
-   - Refactor-specific supplementary content, goals, or constraints → store as-is (verbatim text) on the matching refactor item only
-   - Refactor-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 refactor item
+## Fresh-Session Task Contract (Hard Rule)
+
+Every new or changed refactor item 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 item's `description` and `acceptance_criteria`, read together, MUST define the objective, current state, desired target architecture, selected decisions, scope boundaries, constraints, non-goals, relevant integrations and consumers, edge cases, behavior-preservation decisions, and completion evidence. Preserve substantive user requirements at matching detail.
+2. **Supplementary evidence only**: `user_context` is supplementary evidence only. It may contain scoped exact excerpts and purpose-tagged references, but it MUST NOT expand, replace, or contradict the contract. If `user_context` were removed, a fresh refactor session must still know the current structure, target architecture, allowed scope, forbidden changes, preservation strategy, and verification evidence.
+3. **Purposeful scope**: Every path in `scope.files` and every related path reference must be a purpose-tagged target path in the task contract or supplementary evidence, stating what to inspect or change. The scope array may remain schema-compatible path strings, while `description` explains each path or coherent path group's role.
+4. **Clarify, do not guess**: Ask the user for clarification whenever target architecture, scope boundaries, preservation behavior, material applicability, or a relative reference has multiple plausible meanings.
+5. **Item isolation**: Each refactor contract and its supplementary evidence contain only relevant goals, paths, constraints, desired end state, and preservation evidence.
+
+### 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 implementation.
+- Do not present rejected architectures as active instructions; preserve one only when it defines a necessary non-goal or compatibility boundary.
+
+### Reference Material Handling
+
+- Every retained file path, URL, screenshot, log, dependency graph, analysis, 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 the task contract and `user_context`.
+- Good: `src/auth/validation.ts — inspect exported signatures and current error semantics before extracting middleware`; Bad: `src/auth/validation.ts` alone.
+- For large materials, record title/location and purpose, preserve only task-relevant exact excerpts, and move confirmed target architecture, scope boundaries, constraints, and preservation 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 the target architecture.
+- Good: `Selected decision: extract validation behind an auth-owned middleware interface while preserving all handler exports (original response: "方案B")`.
+- Good: `Selected decision: migrate imports in one compatibility-preserving phase and remove no public paths (original response: "use option A")`.
+- Bad: storing `所有问题都按你的推荐处理` as a preservation rule; it is conversational authorization.
+- Bad: attaching a full architecture RFC while saying only `apply this`. Good: retain purpose-tagged RFC sections and relevant exact excerpts, then state the complete selected target architecture and non-goals in the item contract.
 
 **Multi-refactor isolation example:**
 - User request includes: `Refactor A: extract auth validation into middleware`, `Refactor B: split dashboard chart utilities`, and `Shared: preserve all public APIs`.
-- The auth middleware refactor `user_context` includes `Refactor A: extract auth validation into middleware` and the shared API constraint; it MUST NOT include `Refactor B: split dashboard chart utilities`.
-- The chart utilities refactor `user_context` includes `Refactor B: split dashboard chart utilities` and the shared API constraint; it MUST NOT include `Refactor A: extract auth validation into middleware`.
+- The auth item contract fully defines its current and target structure and includes only matching evidence plus the shared API constraint; it MUST NOT include chart-utility scope.
+- The chart item contract fully defines its current and target structure and includes only matching evidence plus the shared API constraint; it MUST NOT include auth scope.
 
 ## When to Use
 - "Plan refactoring", "Scope a restructuring"
@@ -162,7 +176,7 @@ 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. This context is critical for refactoring — understanding the target architecture and constraints prevents risky structural changes.
+   If the user provides materials, require or infer only when unambiguous a refactor-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. This context is critical for understanding the target architecture and constraints.
 
 **CHECKPOINT CP-RP-0**: Project context loaded, tech stack and test suite status known.
 
@@ -190,9 +204,10 @@ Support 4 input formats (users may mix formats):
 > "The database layer is tightly coupled to the HTTP layer"
 
 For each input, ask clarifying questions:
-- What is the specific target (files, modules, patterns)?
-- What is the desired end state?
-- Are there constraints (must preserve API, must not touch certain files)?
+- What is the specific target (files, modules, patterns), and what should the execution AI inspect at each purpose-tagged target path?
+- What is the complete desired target architecture or end state?
+- What are the scope boundaries and non-goals (must preserve API, must not touch certain files, rejected architecture that must stay rejected)?
+- Which behavior-preservation decisions and completion evidence prove the refactor is safe?
 - What is the motivation (maintainability, performance, testability)?
 
 Continue collecting goals until the user says they're done. There is no limit on rounds.
@@ -246,13 +261,13 @@ See `${SKILL_DIR}/references/planning-phases.md` for the display template and co
 
 **CHECKPOINT CP-RP-4**: All items confirmed by user.
 
-### Phase 6: Completeness Review
+### Phase 6: Headless Context Completeness Gate
 
-**Goal**: Check the full item set for consistency, gaps, and headless execution readiness.
+**Goal**: Check every new or changed item as if the reviewer has never seen the planning conversation, including consistency, gaps, target architecture, scope boundaries, purpose-tagged target paths, behavior-preservation decisions, and completion evidence. Return `NEEDS_FIXES` for any unanswered artifact-alone question and preserve unchanged historical items.
 
 See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review checklist (DAG validation, preservation check, gap detection, cross-module impact, headless readiness criteria) and review summary table format.
 
-**CHECKPOINT CP-RP-5**: Completeness review passed, all issues resolved.
+**CHECKPOINT CP-RP-5**: Headless Context Completeness Gate passed for every new or changed item, all issues resolved without relying on `user_context`.
 
 ### Phase 7: Generate & Validate
 
@@ -290,7 +305,7 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
 
 Run this gate after `.prizmkit/plans/refactor-list.json` passes generation and validation, and before the final handoff. It applies whenever this session added or changed final refactor 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 refactor. 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.
 
 ## Output Rules
 

package/bundled/skills/refactor-planner/references/fast-path.md

@@ -30,12 +30,13 @@ For simple refactoring with minimal scope.
 
    **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
 3. Draft items (title + type + scope + description + acceptance_criteria + behavior_preservation + dependencies)
-4. Write draft to `.prizmkit/plans/refactor-list.draft.json`, then call the generate script:
+4. Run the mandatory Phase 6 Headless Context Completeness Gate on every drafted item; repair the draft until each returns `PASS` without conversation history or `user_context`.
+5. Write draft to `.prizmkit/plans/refactor-list.draft.json`, then call the generate script:
    ```bash
    python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
    ```
-5. If valid -> run the mandatory Local Generated-Plan Review Gate from the main `refactor-planner` skill before summarizing or recommending `refactor-pipeline-launcher`.
-6. If invalid -> apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
+6. If valid -> run the mandatory Local Generated-Plan Review Gate from the main `refactor-planner` skill before summarizing or recommending `refactor-pipeline-launcher`.
+7. If invalid -> apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
 
 ## When NOT to Use Fast Path
 - More than 2 refactor items

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

@@ -31,13 +31,38 @@ For every reviewed refactor entry, check:
 
 - Schema compatibility with `dev-pipeline-refactor-list-v1` and `.prizmkit/dev-pipeline/templates/refactor-list-schema.json`
 - Dependency/DAG soundness, including safe behavior-preserving order
-- Description completeness, target scope clarity, and headless execution readiness
+- Description completeness: objective, current state, desired target architecture, selected decisions, scope boundaries, constraints, non-goals, relevant integrations and consumers, edge cases, behavior-preservation decisions, completion evidence, and headless execution readiness
 - Acceptance criteria specificity and measurable behavior-preservation verification
 - `behavior_preservation` strategy quality and consistency with target scope and existing tests
-- 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 refactor contract; if `user_context` were removed, execution and verification remain unambiguous
 - Task-scoped `user_context` isolation: no unrelated sibling refactor goals, target files, constraints, desired end states, or supplementary materials; shared context appears on multiple items only when explicitly global
+- Purpose-tagged target paths and URLs, diagrams, analyses, and documents; large materials retain title/location, purpose, and task-relevant exact excerpts rather than full-content injection
 - Priority/complexity calibration: every reviewed refactor has short priority and complexity rationales, medium/low assignments are allowed when criteria fit, and high/high is not used merely because the work is cleanup, framework-related, multi-file, or user-requested
 
+## Headless Context Completeness Gate
+
+Repeat the pre-generation simulation for every reviewed new or changed refactor 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 current architecture exists and what target architecture must replace it?
+3. Which approach was selected, expressed by meaning rather than an option label?
+4. What scope boundaries, constraints, and non-goals must be preserved?
+5. Why is each reference material and target path relevant?
+6. How can completion and behavior preservation 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 refactors.
+
+### Good and Bad Review Examples
+
+- Bad: `go with your recommendation` as target architecture; Good: `Selected decision: reverse the auth/user dependency through a shared identity interface and retain existing public imports (original response: "go with your recommendation")`.
+- Bad: bare `src/auth/`; Good: `src/auth/ — inspect public exports, dependency direction, and compatibility call sites before restructuring`.
+- Bad: an entire RFC pasted into evidence; Good: a purpose-tagged RFC location, task-relevant exact excerpts, and all confirmed target decisions in the task contract.
+
 ## Fix Loop
 
 1. Present findings with IDs, severity, evidence, and suggested draft/source changes.
@@ -50,7 +75,8 @@ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input
 ```
 
 5. Re-run validation/generation until valid. Do not hand-patch `.prizmkit/plans/refactor-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
 

package/bundled/skills/refactor-planner/references/planning-phases.md

@@ -47,13 +47,31 @@ Offer `Accept`, `Modify`, and `Skip` as selectable options. Re-display modified
 2. **Behavior preservation check**: Every item must have a declared preservation strategy. Flag any item with `manual` strategy and no test coverage.
 3. **Gap detection**: Are there intermediate steps needed between items? Does item A's output match item B's input assumption?
 4. **Cross-module impact**: Do any items affect modules outside the declared scope?
-5. **Headless Execution Readiness**: The refactor pipeline runs each item through an autonomous AI session with NO human interaction. For each item, verify:
-   - **Scope clarity**: Are all affected files explicitly listed? The AI must know exactly where to look.
-   - **Refactoring instructions**: Is the description specific enough to execute without ambiguity?
-     - ❌ "Clean up the utils module" — what exactly should change?
-     - ✅ "Extract validation functions (validateEmail, validatePhone, validateUrl) from src/utils/helpers.ts into src/utils/validation.ts. Update all 12 import sites. Preserve existing function signatures."
-   - **Behavior preservation**: Is it clear what tests to run and what behavior must be preserved?
-   - **Dependency context**: If item depends on earlier refactors, does the description reference what changed?
+5. **Headless Context Completeness Gate**: Review every new or changed item as if the reviewer has never seen the planning conversation. Preserve unchanged historical items. First assess `description` plus `acceptance_criteria` without `user_context`, then answer from the artifact alone:
+   1. What exact problem or outcome is this task responsible for?
+   2. What current architecture exists and what target architecture must replace it?
+   3. Which approach was selected, expressed by meaning rather than an option label?
+   4. What scope boundaries, constraints, and non-goals must be preserved?
+   5. Why is each reference material and target path relevant, and what should be inspected?
+   6. Which integrations, consumers, import paths, and edge cases are affected?
+   7. Which behavior-preservation decisions and completion evidence prove equivalence?
+   8. Does any phrase require an unseen earlier question, recommendation, or option list?
+   9. Do quoted source materials agree with the final task decision?
+
+   Return `NEEDS_FIXES` whenever any answer is missing, ambiguous, or available only in `user_context`. Ask the user for clarification when a relative statement has more than one plausible antecedent; never guess.
+
+   - **Scope clarity**: List all affected files and explain each file or coherent group as purpose-tagged target paths.
+   - **Target architecture**: State concrete module ownership, interfaces, dependency direction, compatibility boundaries, and desired end state.
+   - **Behavior preservation**: State what tests, snapshots, or reproducible checks run and which observable behavior must remain equivalent.
+   - **Dependency context**: State which exact earlier refactor output this item consumes.
+   - **Good**: `Extract validateEmail, validatePhone, and validateUrl from src/utils/helpers.ts into src/utils/validation.ts; update all 12 import sites; preserve signatures and error semantics. src/utils/helpers.ts — inspect current exports and callers before extraction.`
+   - **Bad**: `Clean up the utils module`, `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation`.
+   - **Good normalization**: `Selected decision: introduce an auth-owned validation module while retaining existing public imports through compatibility re-exports (original response: "方案B")`.
+   - **Bad material handling**: embed an entire architecture RFC while saying `apply this`.
+   - **Good material handling**: `Auth Architecture RFC §5 — inspect dependency-direction and compatibility requirements`, preserve task-relevant exact excerpts, and move confirmed decisions into the task contract.
+   - Exclude conversational authorization such as `所有问题都按你的推荐处理` when it does not constrain implementation.
+   - `user_context` is supplementary evidence only. If `user_context` were removed, execution and verification must remain unambiguous at matching detail.
+   - Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures.
 
 ### Review Summary Table Format
 
@@ -67,7 +85,7 @@ R-003      | low      | Local readability only    | low        | One file, no AP
 R-004      | medium   | Reduces bounded coupling  | medium     | 2 modules + snapshot check  | OK         | snapshot     | -              | Ready
 ```
 
-If issues found, discuss with user and resolve before proceeding.
+If issues are found, discuss with the user, apply fixes to the draft/source item, and rerun the Headless Context Completeness Gate until every new or changed item returns `PASS` before proceeding.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.146",
+  "version": "1.1.147",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {