prizmkit 1.1.147 → 1.1.149

package/bundled/skills/app-planner/references/rules-configuration.md

@@ -46,7 +46,7 @@ For each selected layer, run the 4-phase rule generation pattern:
   - `options_vary_by: "<Qid>"` — the question is still asked; only its option list depends on that prior answer.
 - Legacy shortcut labels in question banks such as `recommended`, `default`, or `skip` are converted into selectable options in `AskUserQuestion`.
 - Do not ask the user to type these commands manually; selectable options prevent merged or missed decisions.
-- Record answers in memory after each group. Track which manifest questions are answered, auto-derived, or conditionally skipped so Phase D can verify coverage.
+- Resolve each response to a complete semantic choice and record only that normalized internal value after each group. Track which manifest questions are answered, auto-derived, or conditionally skipped so Phase D can verify coverage; raw turns and answer tokens are never writer input.
 
 ### Phase C — Auto-derivation
 
@@ -58,9 +58,13 @@ For each selected layer, run the 4-phase rule generation pattern:
 
 - Read `${SKILL_DIR}/references/rules/<layer>/template.md`.
 - Fill all template placeholders with accumulated content from Phases A+B+C.
+- Never copy raw answer text into a rendered rule. Convert option labels, custom replies, recommended/default shortcuts, and internal Q&A state into normalized semantic values that name the selected technology, behavior, constraint, or deferral.
+- Internal question IDs, answer tokens, `answers[Qx]`, dialogue-role labels, recommendation markers, and planning chronology must not appear in generated rules, TL;DR tables, headers, appendices, comments, or metadata prose.
+- Apply the same source durability rule during rendering: inline relevant meaning from non-code planning/evidence files and omit their transient paths; retain only purpose-tagged stable execution-time references.
 - Post-render self-check driven by `question-manifest.json` -> `template_placeholders`:
   1. Coverage pass — for every placeholder in `from_questions`, confirm it traces to an answered question OR an `auto_derived_when` path OR a conditionally-skipped question (`required_if` false). If a `from_questions` placeholder has no source, go back and ask it before writing.
   2. Residual pass — scan the rendered document for any residual `{{ ` or ` }}`; count must be 0. Placeholders in `from_fixed_rules`, `auto_generated`, and `metadata` are filled from fixed rules, Phase D generation, and project metadata.
+  3. AI-readability pass — scan all AI-visible fields and sections. Every generated natural-language value must stand alone without the planning conversation; reject raw turns, Q&A provenance, unresolved relative wording, or transient source dependencies before writing.
 - Generate Appendix A (Deny List) and Appendix B (Recommended Tools) per template instructions.
 - Create `.prizmkit/rules/` directory if it doesn't exist.
 - Write `.prizmkit/rules/<layer>-rules.md`.

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

@@ -50,28 +50,38 @@ Every new or changed bug is an executable contract for a fresh AI session that h
 4. **Clarify, do not guess**: Ask the user for clarification whenever expected behavior, root-cause scope, material applicability, or a relative reference has multiple plausible meanings.
 5. **Bug isolation**: Each bug contract and its supplementary evidence contain only material relevant to that bug. Repeat shared environment or constraints only when explicitly global.
 
+### Artifact-Wide AI Readability
+
+- Every generated natural-language value must be a standalone domain statement. This applies to all AI-visible fields and sections, including `project_description`, `global_context`, titles, descriptions, acceptance criteria, severity/priority rationale, `error_source`, affected-module and environment text, `user_context`, verification goals, comments, appendices, and parentheticals.
+- Machine metadata such as schema markers, stable IDs, statuses, enums, and timestamps is exempt. Natural-language metadata is not exempt.
+- Never emit dialogue-role or chronology labels such as `user said`, `user answered`, `original request`, `this round`, `previous discussion`, `as discussed earlier`, `用户本轮回答`, or `如前面讨论`. Never emit planning question IDs, answer tokens, planning-option recommendation markers, checkpoint provenance, or raw internal answer-map entries as domain content.
+- `user_context` and `error_source` may hold independently intelligible evidence, not transcript fragments. Rewrite every confirmed turn into direct actual/expected behavior, scope, rationale, reproduction, or verification evidence before generation.
+
 ### Conversational Context Normalization
 
 - Never persist standalone option labels such as `A`, `B`, `C`, `方案A`, or `方案B` as execution context.
-- Expand a selected option into complete meaning with inline traceability: `Selected decision: <complete meaning> (original response: "<exact response>")`.
+- Expand a selected option into complete meaning and preserve substantive user rationale and constraints in durable prose at matching detail.
+- Do not emit transcript annotations such as `(original response: "...")` in final bug artifacts. Bare option labels and relative shorthand are not independently intelligible and materially useful exact wording.
 - Resolve `上面`, `这个`, `按推荐走`, `同前`, `继续这样`, `用刚才的方案`, `same as above`, or `go with your recommendation` only when there is one provable antecedent. Otherwise ask the user for clarification; never guess.
-- Exclude conversational authorization such as `所有问题都按你的推荐处理` when it controls planning behavior but does not constrain the fix.
-- Do not present rejected root-cause or fix alternatives as active instructions; preserve one only when it defines a necessary non-goal.
+- Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization. Apply the concrete accepted recommendations, then omit the raw approval; never repeat it once per accepted recommendation.
+- Do not present rejected root-cause or fix alternatives as active instructions; preserve one only when it defines a necessary non-goal. Retain exact user wording only when it is independently intelligible and materially useful.
 
 ### Reference Material Handling
 
-- Every retained file path, URL, screenshot, log, stack trace, or document reference must be purpose-tagged: state why it is relevant and what the execution AI should inspect. This applies to paths and URLs in structured evidence and `user_context`.
-- Good: `logs/api-500.log lines 220-248 — inspect the empty-password request, exception, and correlation ID`; Bad: `logs/api-500.log` alone.
-- For large materials, record title/location and purpose, preserve only task-relevant exact excerpts, and move confirmed expected behavior, selected scope, severity rationale, and verification decisions into `description` and `acceptance_criteria`.
+- Every retained stable code, configuration, machine-consumed interface, or URL reference must be purpose-tagged: state why it is relevant and what the execution AI should inspect. This applies to paths and URLs in structured evidence and `user_context`.
+- Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`, uploaded-report paths, screenshot paths, or ad-hoc log paths in durable bug contracts. Instead, copy or normalize the task-relevant content and exact evidence excerpt into `description` and `acceptance_criteria`; the bug must not depend on that source file still existing.
+- Good: `src/auth/validation.ts — inspect empty-password handling`; Bad: `logs/api-500.log — inspect the failure`. For a transient log, inline the relevant request, exception, and correlation evidence without retaining the path.
+- For large materials, preserve purpose and only task-relevant exact excerpts, and move confirmed expected behavior, selected scope, severity rationale, and verification decisions into `description` and `acceptance_criteria`. Retain a location only when it is a stable execution-time source of truth.
 - Embed complete large materials only when the execution session cannot access the source and all content is genuinely required.
 
 ### Good and Bad Normalization Examples
 
 - Bad: `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation` stored as selected fix scope.
-- Good: `Selected decision: reject empty passwords in request validation with HTTP 400 and do not enter credential verification (original response: "方案B")`.
-- Good: `Selected decision: reproduce against the API integration test and retain UI verification as a regression check (original response: "use option A")`.
-- Bad: storing `所有问题都按你的推荐处理` as a bug constraint; it is conversational authorization.
-- Bad: attaching a complete production log while saying only `fix this`. Good: retain the relevant exception excerpt and purpose-tagged log location, then state actual behavior, expected behavior, scope, and verification in the task contract.
+- Bad: `Selected decision: reject empty passwords with HTTP 400 (original response: "方案B")`; the annotation still requires an unseen option list.
+- Good: `Selected decision: reject empty passwords in request validation with HTTP 400 and do not enter credential verification`.
+- Good: `Selected decision: reproduce against the API integration test and retain UI verification as a regression check`.
+- Bad: storing or repeating `全部按照推荐` / `所有问题都按你的推荐处理` as a bug constraint; it is conversational authorization.
+- Bad: attaching a complete production log or retaining its local path while saying only `fix this`. Good: inline the relevant exception excerpt, actual/expected behavior, scope, and verification; retain a monitoring URL only when it is a stable execution-time source of truth.
 
 **Multi-bug isolation example:**
 - User request includes: `Bug A: login crashes when password is empty`, `Bug B: CSV export loses Chinese characters`, and `Shared: production uses Node 20`.
@@ -194,7 +204,7 @@ Gather project metadata from the project's own configuration and documentation
    >
    > If none, we'll proceed with bug collection."
 
-   If the user provides materials, require or infer only when unambiguous a bug-specific purpose for each material; otherwise ask what the execution AI should inspect. Read/fetch the relevant material before Phase 2. For web links, retrieve the relevant content; for images, analyze the relevant visual evidence. Preserve purpose-tagged locations and task-relevant exact excerpts, but do not inject complete large materials merely for verbatim preservation.
+   If the user provides materials, require or infer only when unambiguous a bug-specific purpose for each material; otherwise ask what the execution AI should inspect. Read/fetch the relevant material before Phase 2. For web links, retrieve the relevant content; for images, analyze the relevant visual evidence. Material ingestion follows the same durability rule as final output: copy or normalize task-relevant requirements and exact evidence, omit transient non-code paths, and retain only purpose-tagged stable execution-time sources. Do not inject complete large materials merely to preserve them.
 
 Output: `project_name`, `project_description`, `global_context` fields populated.
 
@@ -261,7 +271,7 @@ Only finalize the bug entry after user confirms all three points.
 
 ### Phase 4: Pre-Generation Headless Context Completeness Gate
 
-Before generating `.prizmkit/plans/bug-fix-list.json`, review every new or changed bug as if the reviewer has never seen the planning conversation. Preserve unchanged historical bugs; do not bulk-rewrite them. First remove `user_context` from the review view and answer from `description` plus `acceptance_criteria` alone:
+Before generating `.prizmkit/plans/bug-fix-list.json`, review every new or changed bug as if the reviewer has never seen the planning conversation. Preserve unchanged historical bugs; do not bulk-rewrite them. Scan all AI-visible fields and sections first: every generated natural-language value in `project_description`, `global_context`, item fields, `error_source`, environment/evidence, `user_context`, comments, and parentheticals must be session-independent, with no dialogue-role labels, question IDs, answer tokens, planning-option recommendation markers, or planning provenance. Review changed root prose even when no bug item changed. Then remove `user_context` from the review view and answer from `description` plus `acceptance_criteria` alone:
 
 1. What exact problem or outcome is this task responsible for?
 2. What exists today, including actual behavior, and what must change to the expected behavior?
@@ -444,7 +454,7 @@ Recommend invoking `bugfix-pipeline-launcher` to configure and launch the pipeli
 
 After `.prizmkit/plans/bug-fix-list.json` is generated, validated, and reviewed, present:
 1. Summary of generated bugs (count, severity breakdown)
-2. Local generated-plan review result: verdict, reviewed bug IDs, accepted fixes (or "none"), and final validation result
+2. Local generated-plan review result: verdict, reviewed bug IDs plus reviewed root prose when applicable, accepted fixes (or "none"), and final validation result
 3. Recommend: "Say 'start fixing' to launch the bugfix pipeline via `bugfix-pipeline-launcher`"
 4. Alternative: fix a single bug interactively via `bug-fix-workflow`
 

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

@@ -20,8 +20,8 @@ Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whethe
 ## Review Scope
 
 1. If a pre-session final list exists, compare by stable bug IDs (`B-*`).
-2. Treat bugs as changed only when item fields changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
-3. Review newly added bug IDs and changed bug IDs.
+2. Root project prose is reviewable content, not generator metadata. Review new or changed `project_description` and `global_context` even when no bug item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
+3. Treat bugs as changed only when item fields changed; review newly added bug IDs and changed bug IDs.
 4. Preserve unchanged historical bugs. Read unchanged entries only when needed to verify dependency references, duplicate handling, or root-cause overlap with reviewed bugs.
 5. If no snapshot exists, review all bug entries produced by the current generation flow.
 
@@ -32,17 +32,18 @@ For every reviewed bug entry, check:
 - Schema compatibility with `dev-pipeline-bug-fix-list-v1` and `.prizmkit/dev-pipeline/templates/bug-fix-list-schema.json`
 - Dependency/DAG consistency, duplicate handling, and root-cause overlap
 - Description completeness: objective, current/actual behavior, desired/expected behavior, selected scope, reproduction path, code-location hints, affected environment, relevant integrations, constraints, non-goals, edge cases, verification decisions, completion evidence, and headless execution readiness
+- Artifact-wide readability: every generated natural-language value across all AI-visible fields and sections—including `project_description`, `global_context`, `error_source`, environment/evidence, rationales, `user_context`, comments, and parentheticals—is a standalone domain statement without dialogue-role labels, question IDs, answer tokens, planning-option recommendation markers, or planning provenance
 - Acceptance criteria specificity and measurable verification method
 - User-provided detail preservation at matching detail after conversational normalization
 - `user_context` is supplementary evidence only: it does not expand, replace, or contradict the bug contract; if `user_context` were removed, execution and verification remain unambiguous
 - Task-scoped `user_context` isolation: no unrelated sibling bug descriptions, logs, stack traces, reproduction steps, expected/actual behavior notes, or supplementary materials; shared context appears on multiple bugs only when explicitly global
-- Purpose-tagged paths and URLs, screenshots, logs, stack traces, and documents; large materials retain title/location, purpose, and task-relevant exact excerpts rather than full-content injection
+- Purpose-tagged stable code, configuration, machine-consumed interface, and URL references; transient non-code planning/evidence paths are replaced by inline task-relevant decisions and excerpts, and large materials are bounded rather than injected in full
 - Severity/priority calibration: every reviewed bug has a short severity rationale and priority rationale, the preserved severity-to-priority mapping is followed, and high priority is not used without core outage, data loss/integrity, security/auth, timeout/crash, or no-workaround indicators
 - Browser interaction and verification fields for UI-reproducible bugs when applicable
 
 ## Headless Context Completeness Gate
 
-Repeat the pre-generation simulation for every reviewed new or changed bug as if the reviewer has never seen the planning conversation. From the artifact alone, answer:
+Repeat the pre-generation simulation for every reviewed new or changed bug as if the reviewer has never seen the planning conversation. First scan all AI-visible fields and sections; machine metadata is exempt, but every generated natural-language value must be session-independent. From the artifact alone, answer:
 
 1. What exact problem or outcome is this task responsible for?
 2. What exists today and what must change from actual to expected behavior?
@@ -53,14 +54,15 @@ Repeat the pre-generation simulation for every reviewed new or changed bug as if
 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.
+Return `NEEDS_FIXES` if any answer is missing, ambiguous, available only in `user_context`, or dependent on shorthand such as `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation`. Parenthetical notes are part of the artifact and must pass the same fresh-session test. Do not emit transcript annotations such as `(original response: "...")`; raw shorthand is not independently intelligible and materially useful. Preserve substantive rationale in the durable bug contract. Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization: write the concrete accepted decisions, omit the raw approval, and never repeat it once per accepted recommendation. Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`; copy or normalize the task-relevant content and evidence excerpt into the contract, which must not depend on that source file still existing. Ask the user for clarification when there is not one provable antecedent.
 
 Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Apply this stricter gate prospectively to new or changed entries and preserve unchanged historical bugs.
 
 ### Good and Bad Review Examples
 
-- Bad: `按推荐走` as severity or verification scope; Good: `Selected decision: classify as medium because export is incorrect but a JSON workaround exists; verify with the existing Unicode export test (original response: "按推荐走")`.
-- Bad: a bare log path; Good: `logs/export.log lines 90-118 — inspect encoding selection and the emitted response header` plus only task-relevant exact excerpts.
+- Bad: `按推荐走` as severity or verification scope, including as `(original response: "按推荐走")`; Good: `Selected decision: classify as medium because export is incorrect but a JSON workaround exists; verify with the existing Unicode export test`.
+- Bad: repeating `(original response: "全部按照推荐")` after each accepted bug decision; Good: write each concrete decision and omit the blanket approval.
+- Bad: `.agents/brainstorm/export.md` or a transient log path in the final bug contract; Good: inline the selected behavior and exact relevant failure excerpt, and retain only a purpose-tagged stable code/interface path when execution must inspect it.
 - Bad: `所有问题都按你的推荐处理` as a fix constraint; Good: omit it as conversational authorization unless a concrete decision was separately confirmed.
 
 ## Fix Loop
@@ -83,7 +85,7 @@ python3 ${SKILL_DIR}/scripts/validate-bug-list.py generate --input .prizmkit/pla
 Report in the final handoff summary:
 
 - `Local generated-plan review: PASS` or `NEEDS_FIXES`
-- Reviewed bug IDs
+- Reviewed bug IDs and reviewed root prose (`project_description` / `global_context`) when applicable
 - Accepted fixes, or `none`
 - Final validation result
 - Note when review was not applicable because no new final planning content was written

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

@@ -57,29 +57,38 @@ Every new or changed feature is an executable contract for a fresh AI session th
 3. **Clarify, do not guess**: Ask the user for clarification whenever requirements conflict or a reference has multiple plausible antecedents. Do not finalize the feature while ambiguity remains.
 4. **Feature isolation**: In multi-feature planning, each contract and its supplementary evidence contain only material relevant to that feature. Repeat shared context only when it explicitly applies to every affected feature. Ask the user to map material whose applicability is unclear.
 
+### Artifact-Wide AI Readability
+
+- Every generated natural-language value must be a standalone domain statement. This applies to all AI-visible fields and sections, including `project_description`, `global_context`, titles, descriptions, acceptance criteria, rationales, `sub_features`, `completion_notes`, `testing`, `user_context`, evidence and environment text, browser verification goals, comments, appendices, and parentheticals.
+- Machine metadata such as schema markers, stable IDs, statuses, enums, and timestamps is exempt. Natural-language metadata is not exempt.
+- Never emit dialogue-role or chronology labels such as `user said`, `user answered`, `original request`, `this round`, `previous discussion`, `as discussed earlier`, `用户本轮回答`, or `如前面讨论`. Never emit planning question IDs, answer tokens, planning-option recommendation markers, checkpoint provenance, or raw internal answer-map entries as domain content.
+- `user_context` may hold independently intelligible evidence, not transcript fragments. Rewrite every confirmed turn into direct product behavior, constraints, rationale, or verification evidence before generation.
+
 ### Conversational Context Normalization
 
 - Never persist standalone option labels such as `A`, `B`, `C`, `方案A`, or `方案B` as execution context.
-- Expand a selected option into its complete meaning and preserve the original response inline for traceability: `Selected decision: <complete meaning> (original response: "<exact response>")`.
+- Expand a selected option into its complete meaning and preserve substantive user rationale and constraints in durable prose at matching detail.
+- Do not emit transcript annotations such as `(original response: "...")` in final feature artifacts. Bare option labels and relative shorthand are not independently intelligible and materially useful exact wording.
 - Resolve relative statements such as `上面`, `这个`, `按推荐走`, `同前`, `继续这样`, `用刚才的方案`, `same as above`, or `go with your recommendation` only when there is one provable antecedent. If more than one antecedent is plausible, ask the user for clarification; never guess.
-- 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.
+- Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization. Apply the concrete accepted recommendations, then omit the raw approval; never repeat it once per accepted recommendation.
+- Do not present rejected alternatives as active instructions. Retain one only when its rejection defines a necessary non-goal. Retain exact user wording only when it is independently intelligible and materially useful.
 
 ### Reference Material Handling
 
-- Every retained 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`.
+- Every retained stable code, configuration, machine-consumed interface, or URL reference must be purpose-tagged: state why it is relevant and what the execution AI must inspect. This applies to paths and URLs in both the task contract and `user_context`.
+- Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`, uploaded-document paths, screenshot paths, or ad-hoc log paths in durable feature contracts. Instead, copy or normalize the task-relevant content into `description` and `acceptance_criteria`; the task must not depend on that source file still existing.
+- Good: `src/auth/login.ts:42-78 — inspect empty-password validation and the response-status transition`; Bad: `src/auth/login.ts:42-78` with no purpose.
+- For large materials such as issues, PRDs, logs, or documents, explain the purpose, preserve only task-relevant exact excerpts, and move every confirmed requirement into `description` and `acceptance_criteria`. Retain a location only when it is a stable execution-time source of truth.
 - Embed complete large materials only when the execution session cannot access the source and all content is genuinely required. Reference material never substitutes for the task contract.
 
 ### Good and Bad Normalization Examples
 
 - Bad: `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation` stored alone.
-- 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.
+- Bad: `Selected decision: keep saved filters account-scoped (original response: "方案B")`; the annotation still requires an unseen option list.
+- Good: `Selected decision: keep saved filters account-scoped and sync them through the existing preferences API`.
+- Good: `Selected decision: use cursor pagination with a 50-item default and preserve current sort order`.
+- Bad: storing or repeating `全部按照推荐` / `所有问题都按你的推荐处理` as a feature requirement; it is conversational authorization, not execution context.
+- Bad: attaching an entire PRD or transient PRD path only to preserve wording. Good: state the confirmed retry and idempotency behavior directly in the feature contract; retain a purpose-tagged PRD URL only when it is a stable execution-time source of truth.
 
 **Multi-feature isolation example:**
 - User request includes: `Feature A: add saved filters to the dashboard`, `Feature B: export filtered results as CSV`, and `Shared: preserve existing auth permissions`.
@@ -277,7 +286,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, 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.
+   If the user provides materials, require or infer only when unambiguous a task-specific purpose for each material; otherwise ask what the execution AI should inspect. Read/fetch them before Phase 2. For web links, retrieve and analyze the relevant content; for images, analyze the relevant visual evidence. Material ingestion follows the same durability rule as final output: copy or normalize task-relevant requirements and exact evidence, omit transient non-code paths, and retain only purpose-tagged stable execution-time sources. Do not copy complete large materials merely to preserve them.
 2. Confirm constraints and existing architecture
 3. Propose feature set with dependencies
 4. Refine descriptions and acceptance criteria
@@ -465,7 +474,7 @@ After successful validation and the Local Generated-Plan Review Gate, report:
 1. Output file path
 2. Total features + newly added features
 3. Dependency and priority highlights
-4. Local generated-plan review result: verdict, reviewed feature IDs, accepted fixes (or "none"), and final validation result
+4. Local generated-plan review result: verdict, reviewed feature IDs plus reviewed root prose when applicable, accepted fixes (or "none"), and final validation result
 5. Recommended next action: `feature-pipeline-launcher`
 
 Then apply the post-planning handoff in §Scope Boundary (ask before proceeding; never auto-execute).

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

@@ -75,12 +75,14 @@ When a feature depends on others, explicitly state what it needs from them:
 - 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.
+- Good: `src/billing/webhook.ts — inspect retry and idempotency behavior` for a stable execution target.
+- Bad: `.agents/brainstorm/billing.md §4 — inspect retry requirements`; copy the confirmed retry and idempotency requirements into the task contract and omit the transient planning path.
+- Bad: a full PRD copied into `user_context` without a purpose. Preserve only task-relevant exact excerpts, and never make the task depend on the non-code source still existing.
 
 **Decision normalization:**
-- Good: `Selected decision: store saved filters per account through the existing preferences API (original response: "方案B")`.
+- Good: `Selected decision: store saved filters per account through the existing preferences API`.
 - Bad: `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation` with no complete selected meaning.
+- Bad: appending `(original response: "方案B")` or `(original response: "全部按照推荐")`; transcript provenance still requires an unseen prompt. Preserve substantive rationale in the decision prose, but omit blanket recommendation approval.
 
 **Self-test:** 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

@@ -6,6 +6,8 @@ Before generating `.prizmkit/plans/feature-list.json`, review every new or chang
 
 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.
 
+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.
+
 ## Step 1: Artifact-Alone Fresh-Session Simulation
 
 For each new or changed feature, answer all of these from `description` and `acceptance_criteria` alone:
@@ -25,23 +27,26 @@ If any answer is unavailable, ambiguous, or present only in `user_context`, the
 
 ## 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")`.
+- 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 conversational authorization that controls planning but does not constrain implementation.
+- 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, 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.
+- 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`.
-- Good: `Selected decision: keep saved filters account-scoped and sync through the existing preferences API (original response: "方案B")`.
+- 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: `docs/search-rfc.md`.
-- Good: `docs/search-rfc.md §3 — inspect ranking tie-breakers and empty-query behavior`.
+- 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.
 

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.
 
@@ -32,17 +32,18 @@ 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` 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 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
+- 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. From the artifact alone, answer:
+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?
@@ -53,14 +54,16 @@ Repeat the pre-generation simulation for every reviewed new or changed feature a
 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.
+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`; Good: the complete selected API behavior plus `(original response: "same as above")` after its single antecedent is proven.
+- 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
@@ -83,7 +86,7 @@ python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit
 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

@@ -55,28 +55,38 @@ Every new or changed refactor item is an executable contract for a fresh AI sess
 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 with inline traceability: `Selected decision: <complete meaning> (original response: "<exact response>")`.
+- 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.
-- 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.
+- 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 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`.
+- 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, 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`.
+- 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.
-- 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.
+- 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`.
@@ -176,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, 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.
+   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.
 
@@ -415,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/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.
 
@@ -32,17 +32,18 @@ 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: 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 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
+- 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. From the artifact alone, answer:
+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?
@@ -53,15 +54,16 @@ Repeat the pre-generation simulation for every reviewed new or changed refactor
 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.
+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; 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: `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; Good: a purpose-tagged RFC location, task-relevant exact excerpts, and all confirmed target decisions in the task contract.
+- 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
 
@@ -83,7 +85,7 @@ python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input
 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,7 +47,7 @@ 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 Context Completeness Gate**: Review every new or changed item as if the reviewer has never seen the planning conversation. Preserve unchanged historical items. First assess `description` plus `acceptance_criteria` without `user_context`, then answer from the artifact alone:
+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?
@@ -58,7 +58,7 @@ Offer `Accept`, `Modify`, and `Skip` as selectable options. Re-display modified
    8. Does any phrase require an unseen earlier question, recommendation, or option list?
    9. Do quoted source materials agree with the final task decision?
 
-   Return `NEEDS_FIXES` whenever any answer is missing, ambiguous, or available only in `user_context`. Ask the user for clarification when a relative statement has more than one plausible antecedent; never guess.
+   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.
@@ -66,10 +66,12 @@ Offer `Accept`, `Modify`, and `Skip` as selectable options. Re-display modified
    - **Dependency context**: State which exact earlier refactor output this item consumes.
    - **Good**: `Extract validateEmail, validatePhone, and validateUrl from src/utils/helpers.ts into src/utils/validation.ts; update all 12 import sites; preserve signatures and error semantics. src/utils/helpers.ts — inspect current exports and callers before extraction.`
    - **Bad**: `Clean up the utils module`, `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation`.
-   - **Good normalization**: `Selected decision: introduce an auth-owned validation module while retaining existing public imports through compatibility re-exports (original response: "方案B")`.
-   - **Bad material handling**: embed an entire architecture RFC while saying `apply this`.
-   - **Good material handling**: `Auth Architecture RFC §5 — inspect dependency-direction and compatibility requirements`, preserve task-relevant exact excerpts, and move confirmed decisions into the task contract.
-   - Exclude conversational authorization such as `所有问题都按你的推荐处理` when it does not constrain implementation.
+   - **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.