prizmkit 1.1.146 → 1.1.148

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

@@ -1,57 +1,80 @@
 # 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)
+Scan all AI-visible fields and sections, not only the main contract. Every generated natural-language value in `project_description`, `global_context`, item fields, `user_context`, evidence, comments, and parentheticals must stand alone. Review changed root prose even when no feature item changed. Return `NEEDS_FIXES` for dialogue-role/chronology labels, question IDs, answer tokens, planning-option recommendation markers, checkpoint provenance, or raw internal answer-map content.
 
-**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)
+## Step 1: Artifact-Alone Fresh-Session Simulation
 
-**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."
+For each new or changed feature, answer all of these from `description` and `acceptance_criteria` alone:
 
-If any feature description is unclear, **expand it now** before generating the output file.
+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?
 
-## Step 2: Cross-Feature Completeness Check
+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: Contract and Material Checks
+
+- Preserve substantive user requirements, rationale, and constraints at matching detail; normalization must not collapse a detailed specification into a short summary.
+- Expand option shorthand into complete selected meaning, for example: `Selected decision: use cursor pagination with a 50-item default`.
+- Do not emit transcript annotations such as `(original response: "...")`; parenthetical content must also be independently intelligible and materially useful.
+- Resolve `方案B`, `按推荐走`, `same as above`, or `go with your recommendation` only when there is one provable antecedent. Otherwise ask the user for clarification.
+- Exclude `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval when it controls planning but does not constrain implementation; never repeat it once per accepted recommendation.
+- Do not present rejected alternatives as active requirements; retain them only as necessary non-goals.
+- Require purpose-tagged paths and URLs when they identify stable execution targets.
+- Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`, uploads, screenshots, or ad-hoc logs. Instead, copy or normalize the task-relevant content into the contract, which must not depend on that source file still existing.
+- For large materials, preserve purpose and task-relevant exact excerpts; move confirmed requirements into the task contract rather than embedding the entire source, and retain a location only when it is a stable execution-time source of truth.
+- If `user_context` were removed, `description` and `acceptance_criteria` must remain sufficient for execution and verification.
+
+### Good and Bad Examples
+
+- Bad: `方案B` or `Selected decision: keep saved filters account-scoped (original response: "方案B")`.
+- Good: `Selected decision: keep saved filters account-scoped and sync through the existing preferences API`.
+- Bad: repeating `(original response: "全部按照推荐")` after each accepted default; write each concrete default and omit the blanket approval.
+- Bad: `same as above` when multiple earlier decisions exist.
+- Good: ask which earlier decision applies, then record its complete meaning.
+- Bad: `.agents/brainstorm/search.md — inspect ranking choices`.
+- Good: state the selected ranking tie-breakers and empty-query behavior in the task contract; retain only a purpose-tagged stable code or interface path when execution must inspect it.
+- 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

@@ -20,8 +20,8 @@ Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whethe
 ## Review Scope
 
 1. If a pre-session final list exists, compare by stable feature IDs (`F-*`).
-2. Treat features as changed only when item fields changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
-3. Review newly added feature IDs and changed feature IDs.
+2. Root project prose is reviewable content, not generator metadata. Review new or changed `project_description` and `global_context` even when no feature item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
+3. Treat features as changed only when item fields changed; review newly added feature IDs and changed feature IDs.
 4. Preserve unchanged historical features. Read unchanged entries only when needed to verify dependency references from reviewed features.
 5. If no snapshot exists, review all feature entries produced by the current generation flow.
 
@@ -31,13 +31,41 @@ 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
+- Artifact-wide readability: every generated natural-language value across all AI-visible fields and sections—including `project_description`, `global_context`, titles, rationales, `user_context`, evidence, comments, and parentheticals—is a standalone domain statement without dialogue-role labels, question IDs, answer tokens, planning-option recommendation markers, or planning provenance
 - Acceptance criteria specificity, 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 stable code, configuration, machine-consumed interface, and URL references; transient non-code planning/evidence paths are replaced by inline task-relevant decisions and excerpts, and large materials are bounded rather than injected in full
 - 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. First scan all AI-visible fields and sections; machine metadata is exempt, but every generated natural-language value must be session-independent. From the artifact alone, answer:
+
+1. What exact problem or outcome is this task responsible for?
+2. What exists today and what must change?
+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`. Parenthetical notes are part of the artifact and must pass the same fresh-session test. Do not emit transcript annotations such as `(original response: "...")`; raw shorthand is not independently intelligible and materially useful. Preserve substantive rationale in the durable task contract. Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization: write the concrete accepted decisions, omit the raw approval, and never repeat it once per accepted recommendation. Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`; copy or normalize the task-relevant content into the contract, which must not depend on that source file still existing. Ask the user for clarification when there is not one provable antecedent.
+
+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` or a complete API decision followed by `(original response: "same as above")`; Good: record only the complete selected API behavior after its single antecedent is proven.
+- Bad: repeating `(original response: "全部按照推荐")` on accepted defaults; Good: omit the blanket approval after normalizing each default into concrete behavior.
+- 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: `.agents/brainstorm/search.md — inspect selected behavior` in a final contract; Good: write the selected behavior inline and omit the transient planning path.
+- 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,14 +78,15 @@ 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
 
 Report in the final handoff summary:
 
 - `Local generated-plan review: PASS` or `NEEDS_FIXES`
-- Reviewed feature IDs
+- Reviewed feature IDs and reviewed root prose (`project_description` / `global_context`) when applicable
 - Accepted fixes, or `none`
 - Final validation result
 - Note when review was not applicable because no new final planning content was written

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

@@ -45,29 +45,53 @@ 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.
+
+### Artifact-Wide AI Readability
+
+- Every generated natural-language value must be a standalone domain statement. This applies to all AI-visible fields and sections, including `project_description`, `global_context`, titles, descriptions, scope explanations, complexity/priority rationale, `behavior_preservation`, `completion_notes`, acceptance criteria, `user_context`, verification goals, comments, appendices, and parentheticals.
+- Machine metadata such as schema markers, stable IDs, statuses, enums, and timestamps is exempt. Natural-language metadata is not exempt.
+- Never emit dialogue-role or chronology labels such as `user said`, `user answered`, `original request`, `this round`, `previous discussion`, `as discussed earlier`, `用户本轮回答`, or `如前面讨论`. Never emit planning question IDs, answer tokens, planning-option recommendation markers, checkpoint provenance, or raw internal answer-map entries as domain content.
+- `user_context` may hold independently intelligible evidence, not transcript fragments. Rewrite every confirmed turn into direct current/target architecture, scope, constraints, rationale, preservation, or verification evidence before generation.
+
+### Conversational Context Normalization
+
+- Never persist standalone option labels such as `A`, `B`, `C`, `方案A`, or `方案B` as execution context.
+- Expand a selected option into complete meaning and preserve substantive user rationale and constraints in durable prose at matching detail.
+- Do not emit transcript annotations such as `(original response: "...")` in final refactor artifacts. Bare option labels and relative shorthand are not independently intelligible and materially useful exact wording.
+- Resolve `上面`, `这个`, `按推荐走`, `同前`, `继续这样`, `用刚才的方案`, `same as above`, or `go with your recommendation` only when there is one provable antecedent. Otherwise ask the user for clarification; never guess.
+- Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization. Apply the concrete accepted recommendations, then omit the raw approval; never repeat it once per accepted recommendation.
+- Do not present rejected architectures as active instructions; preserve one only when it defines a necessary non-goal or compatibility boundary. Retain exact user wording only when it is independently intelligible and materially useful.
+
+### Reference Material Handling
+
+- Every retained stable code, configuration, machine-consumed interface, or URL reference must be purpose-tagged: state why it is relevant and what the execution AI should inspect. This applies to paths and URLs in the task contract and `user_context`.
+- Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`, uploaded-analysis paths, screenshot paths, or ad-hoc log paths in durable refactor contracts. Instead, copy or normalize the task-relevant content into `description` and `acceptance_criteria`; the item must not depend on that source file still existing.
+- Good: `src/auth/validation.ts — inspect exported signatures and current error semantics before extracting middleware`; Bad: `src/auth/validation.ts` alone.
+- For large materials, preserve purpose and only task-relevant exact excerpts, and move confirmed target architecture, scope boundaries, constraints, and preservation decisions into `description` and `acceptance_criteria`. Retain a location only when it is a stable execution-time source of truth.
+- Embed complete large materials only when the execution session cannot access the source and all content is genuinely required.
+
+### Good and Bad Normalization Examples
+
+- Bad: `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation` stored as the target architecture.
+- Bad: `Selected decision: extract auth validation (original response: "方案B")`; the annotation still requires an unseen option list.
+- Good: `Selected decision: extract validation behind an auth-owned middleware interface while preserving all handler exports`.
+- Good: `Selected decision: migrate imports in one compatibility-preserving phase and remove no public paths`.
+- Bad: storing or repeating `全部按照推荐` / `所有问题都按你的推荐处理` as a preservation rule; it is conversational authorization.
+- Bad: attaching a full architecture RFC or `.agents/brainstorm/refactor.md` path while saying only `apply this`. Good: copy the relevant architecture, scope, and preservation decisions into the item contract and omit the transient planning path.
 
 **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 +186,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. Material ingestion follows the same durability rule as final output: copy or normalize task-relevant requirements and exact evidence, omit transient non-code paths, and retain only purpose-tagged stable execution-time sources. Do not inject complete large materials merely to preserve them. 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 +214,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 +271,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 +315,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
 
@@ -400,5 +425,5 @@ After successful validation and the Local Generated-Plan Review Gate, report:
 2. Total refactor items
 3. Dependency ordering highlights (which items must run first)
 4. Behavior preservation strategy distribution (N items with test-gate, M with snapshot, etc.)
-5. Local generated-plan review result: verdict, reviewed refactor IDs, accepted fixes (or "none"), and final validation result
+5. Local generated-plan review result: verdict, reviewed refactor IDs plus reviewed root prose when applicable, accepted fixes (or "none"), and final validation result
 6. Recommended next action: `refactor-pipeline-launcher`

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

@@ -20,8 +20,8 @@ Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whethe
 ## Review Scope
 
 1. If a pre-session final list exists, compare by stable refactor IDs (`R-*`).
-2. Treat refactors as changed only when item fields changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
-3. Review newly added refactor IDs and changed refactor IDs.
+2. Root project prose is reviewable content, not generator metadata. Review new or changed `project_description` and `global_context` even when no refactor item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
+3. Treat refactors as changed only when item fields changed; review newly added refactor IDs and changed refactor IDs.
 4. Preserve unchanged historical refactors. Read unchanged entries only when needed to verify dependency references or behavior-preservation interactions with reviewed refactors.
 5. If no snapshot exists, review all refactor entries produced by the current generation flow.
 
@@ -31,13 +31,40 @@ 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
+- Artifact-wide readability: every generated natural-language value across all AI-visible fields and sections—including `project_description`, `global_context`, scope explanations, rationales, behavior-preservation/evidence text, `user_context`, comments, and parentheticals—is a standalone domain statement without dialogue-role labels, question IDs, answer tokens, planning-option recommendation markers, or planning provenance
 - Acceptance criteria specificity and measurable 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 stable code, configuration, machine-consumed interface, and URL targets; transient non-code planning/evidence paths are replaced by inline task-relevant decisions and excerpts, and large materials are bounded rather than injected in full
 - 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. First scan all AI-visible fields and sections; machine metadata is exempt, but every generated natural-language value must be session-independent. From the artifact alone, answer:
+
+1. What exact problem or outcome is this task responsible for?
+2. What 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`. Parenthetical notes are part of the artifact and must pass the same fresh-session test. Do not emit transcript annotations such as `(original response: "...")`; raw shorthand is not independently intelligible and materially useful. Preserve substantive rationale in the durable refactor contract. Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization: write the concrete accepted decisions, omit the raw approval, and never repeat it once per accepted recommendation. Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`; copy or normalize the task-relevant content into the contract, which must not depend on that source file still existing. Ask the user for clarification when there is not one provable antecedent.
+
+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 or as `(original response: "go with your recommendation")`; Good: `Selected decision: reverse the auth/user dependency through a shared identity interface and retain existing public imports`.
+- Bad: repeating `(original response: "全部按照推荐")`; Good: omit the blanket approval after writing each concrete accepted decision.
+- 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 or `.agents/brainstorm/refactor.md` retained as a requirement; Good: inline task-relevant excerpts and all confirmed target decisions, then omit the transient planning path.
+
 ## Fix Loop
 
 1. Present findings with IDs, severity, evidence, and suggested draft/source changes.
@@ -50,14 +77,15 @@ 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
 
 Report in the final handoff summary:
 
 - `Local generated-plan review: PASS` or `NEEDS_FIXES`
-- Reviewed refactor IDs
+- Reviewed refactor IDs and reviewed root prose (`project_description` / `global_context`) when applicable
 - Accepted fixes, or `none`
 - Final validation result
 - Note when review was not applicable because no new final planning content was written

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

@@ -47,13 +47,33 @@ 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. Scan all AI-visible fields and sections first: every generated natural-language value in `project_description`, `global_context`, item fields, scope explanations, behavior-preservation/evidence text, `user_context`, comments, and parentheticals must be session-independent, with no dialogue-role labels, question IDs, answer tokens, planning-option recommendation markers, or planning provenance. Review changed root prose even when no refactor item changed. Then assess `description` plus `acceptance_criteria` without `user_context` and 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`. Parenthetical notes must pass the same gate. Do not emit transcript annotations such as `(original response: "...")`; preserve substantive rationale, but omit bare selection tokens and `全部按照推荐` or equivalent blanket recommendation approval after normalization. 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`.
+   - **Bad normalization**: append `(original response: "方案B")` to a complete architecture decision; the annotation is not independently intelligible and materially useful.
+   - **Good normalization**: `Selected decision: introduce an auth-owned validation module while retaining existing public imports through compatibility re-exports`.
+   - **Bad material handling**: embed an entire architecture RFC while saying `apply this`, or retain `.agents/brainstorm/refactor.md` as a final requirement source.
+   - Do not retain non-code planning-source paths in the final contract.
+   - **Good material handling**: copy or normalize the task-relevant content and exact excerpts into the contract; retain only purpose-tagged stable execution targets. The item must not depend on that source file still existing.
+   - Exclude `所有问题都按你的推荐处理`, `全部按照推荐`, and equivalent conversational authorization when it does not constrain implementation; never repeat it once per accepted recommendation.
+   - `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 +87,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.148",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {