prizmkit 1.1.145 → 1.1.147

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