prizmkit 1.1.146 → 1.1.148

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.146",
-  "bundledAt": "2026-07-23T01:20:01.078Z",
-  "bundledFrom": "248d714"
+  "frameworkVersion": "1.1.148",
+  "bundledAt": "2026-07-23T15:48:35.778Z",
+  "bundledFrom": "63b5f6e"
 }

package/bundled/skills/_metadata.json

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

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

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

package/bundled/skills/app-planner/references/brainstorm-guide.md

@@ -75,7 +75,7 @@ Produce a structured summary:
 [2-3 approaches with pros/cons/effort]
 
 ## Selected Approach
-[User's choice + rationale]
+[Complete selected approach and rationale, written as standalone design context without answer tokens or dialogue provenance]
 
 ## Assumptions
 [All assumptions explicitly listed]

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

@@ -44,17 +44,47 @@ For every reviewed app-planning artifact or section, check:
 - Consistency among conventions, infrastructure, architecture decisions, and project brief content
 - Infrastructure completeness or explicit deferral for database, deployment, and cloud services topics when those flows ran
 - Rules pointer consistency: generated `.prizmkit/rules/<layer>-rules.md` files are referenced by the `root.prizm` `RULES:` line when rules were configured
-- User-provided wording preservation in project brief ideas, conventions, infrastructure notes, architecture decisions, and rules
+- Substantive user meaning and detail preservation at matching detail after conversational normalization in project brief ideas, conventions, infrastructure notes, architecture decisions, and rules
+- Artifact-wide readability: every generated natural-language value across all AI-visible fields and sections—including briefs/drafts, instruction sections, generated rules, appendices, comments, brainstorm summaries, quoted evidence, and parentheticals—is a standalone domain statement without dialogue-role labels, question IDs, answer tokens, planning-option recommendation markers, raw answer-map content, or planning provenance
+- Every selected product or technical decision is expressed by complete meaning rather than `A`, `B`, `C`, `方案A`, `方案B`, or another unseen option label; substantive rationale remains durable, while opaque transcript provenance is absent
+- Purpose-tagged stable code, configuration, machine-consumed interface, and URL references; non-code planning/evidence source paths are replaced by inline task-relevant decisions and excerpts, and large materials are bounded rather than injected in full
+- Conversational authorization is excluded when it controls planning but does not constrain implementation; rejected alternatives appear only as necessary non-goals
 - Downstream readiness: `feature-planner` has enough context to produce `.prizmkit/plans/feature-list.json` without guessing core app purpose, stack, constraints, or implementation conventions
 - No implementation/scaffolding actions are introduced by the app plan; outputs stay within app-planner's writable boundary
 
+## Headless Context Completeness Gate
+
+Repeat the pre-generation simulation for every reviewed new or changed app-planning line or section as if the reviewer has never seen the planning conversation. 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 product outcome or technical decision does this content record?
+2. What exists today and what desired state or constraint applies?
+3. Which approach was selected, expressed by meaning rather than an option label?
+4. What constraints and non-goals must downstream work preserve?
+5. Why is each reference material relevant?
+6. How will downstream planning or implementation know the decision was honored?
+7. Does any phrase require an unseen earlier question, recommendation, or option list?
+8. Do quoted source materials agree with the final task decision?
+
+Return `NEEDS_FIXES` if any answer is missing, ambiguous, or dependent on shorthand such as `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation`. 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. Ask the user for clarification when there is not one provable antecedent. 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 durable artifact, which must not depend on that source file still existing.
+
+Apply this stricter gate prospectively to new or changed content and preserve unchanged historical app-planning content.
+
+### Good and Bad Review Examples
+
+- Bad: `[ ] 使用方案B` or `[ ] Authentication uses organization-scoped OAuth with server-side sessions (original response: "方案B")`; Good: `[ ] Authentication uses organization-scoped OAuth with server-side sessions`.
+- Bad: repeating `(original response: "全部按照推荐")` after each convention; Good: omit the blanket approval after normalizing every accepted convention into concrete meaning.
+- Bad: a bare architecture URL; Good: `Architecture RFC §5 — inspect identity ownership and session boundaries`, plus only task-relevant exact excerpts.
+- Bad: `.agents/brainstorm/design.md — inspect accepted risks` in a final brief; Good: write the accepted risks and resulting constraints inline, then omit the transient planning path.
+- Bad: a rejected serverless alternative listed as an active infrastructure decision; Good: include it only as a non-goal when preserving the selected container deployment boundary requires that fact.
+
 ## Fix Loop
 
 1. Present findings with artifact path, section name, severity, evidence, and suggested source change.
-2. Accept only findings that improve planner correctness, consistency, user wording preservation, or downstream feature-planner readiness.
+2. Accept only findings that improve planner correctness, consistency, substantive meaning preservation, or downstream feature-planner readiness.
 3. Apply accepted fixes to the source representation first: brief draft/checklist, instruction-file section source, rules answer/template source, or `root.prizm` `RULES:` pointer source.
 4. Regenerate or rewrite final artifacts through the same writer path used by app-planner. Do not hand-patch final artifacts as a shortcut when a draft/source representation exists.
-5. Re-read the changed final artifacts directly and re-run the local review only for changed sections.
+5. Re-read the changed final artifacts directly and repeat the Headless Context Completeness Gate only for changed sections.
+6. Do not report `PASS` until every required fresh-session answer is available and each changed artifact passes its final writer/validation check.
 
 ## Report Format
 

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

@@ -28,8 +28,16 @@
    - Change `[ ]` to `[x]`
    - Append `->` followed by the **key file or directory paths** that implement it
    - List the most important 1-3 paths only (entry point, core module, or directory) — not every touched file
-   - Example: `[x] User authentication with OAuth -> src/auth/, src/middleware/auth.ts`
-   - This lets future AI sessions instantly locate the implementation without re-scanning
+   - Purpose-tag every retained path so a fresh session knows what to inspect
+   - Good: `[x] User authentication uses organization-scoped OAuth with server-side sessions -> src/auth/ — inspect provider/session ownership; src/middleware/auth.ts — inspect request authorization`
+   - Bad: `[x] User authentication -> src/auth/, src/middleware/auth.ts` because neither the selected behavior nor path purpose is clear
+   - This lets future AI sessions locate the implementation without guessing or broad rescanning
+7. **Complete decision meaning**: Every line names the actual product or technical decision. Never write only `A`, `B`, `C`, `方案A`, `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation`.
+8. **Artifact-safe normalization**: Every natural-language line, comment, quote, and parenthetical is written for an AI with no planning-session access. Preserve substantive rationale and constraints in durable prose. Do not emit transcript annotations, dialogue-role/chronology labels, question IDs, answer tokens, planning-option recommendation markers, or raw answer-map content; bare selection tokens are not independently intelligible and materially useful exact wording.
+9. **Ambiguous references**: Resolve shorthand only with one provable antecedent. Otherwise ask the user for clarification; never guess.
+10. **Conversational authorization**: Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as dialogue control. Write each concrete accepted default, omit the raw approval, and never repeat it once per accepted recommendation.
+11. **References**: Purpose-tag stable code, configuration, machine-consumed interface, and URL references. Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`, uploads, screenshots, or ad-hoc logs in the brief; copy or normalize the task-relevant content inline so the brief must not depend on that source file still existing. For large materials, retain purpose and task-relevant exact excerpts rather than complete source content, and retain a location only when it is a stable execution-time source of truth.
+12. **Alternatives**: Do not present rejected alternatives as active brief items; include them only as necessary non-goals.
 
 ## Brownfield Init
 
@@ -76,7 +84,22 @@ If the user gives short/vague answers, don't accept them — rephrase and ask ag
 
 ### Generate & Confirm
 Once all criteria are met:
-1. Generate brief in checklist format (see Format section above)
-2. Present to user with: "Here's what I captured — anything to add, remove, or change?"
-3. Apply edits and write to `.prizmkit/plans/project-brief.md`
+1. Generate the proposed brief in checklist format (see Format section above).
+2. Run the app-planner Pre-Generation Headless Context Completeness Gate on every new or changed line as if the reviewer has never seen the planning conversation. Confirm the actual outcome/current state/desired state, selected meaning, constraints/non-goals, reference relevance, downstream completion signal, absence of unseen conversational dependencies, and that quoted source materials agree with the final task decision.
+3. Return `NEEDS_FIXES` for any unanswered question, update the draft/source line, and repeat until all changed lines pass. Preserve unchanged historical brief items.
+4. Present to user with: "Here's what I captured — anything to add, remove, or change?"
+5. Apply edits, rerun the gate for modified lines, and write `.prizmkit/plans/project-brief.md` only after `PASS`.
+
+### Good and Bad Brief Examples
+
+- Bad: `[ ] 使用方案B`.
+- Bad: `[ ] Authentication uses organization-scoped OAuth with server-side sessions (original response: "方案B")`; the parenthetical still depends on an unseen option list.
+- Good: `[ ] Authentication uses organization-scoped OAuth with server-side sessions`.
+- Bad: repeating `(original response: "全部按照推荐")` on accepted conventions; omit the blanket approval after writing each convention's concrete meaning.
+- Bad: `[ ] same as above` when several prior decisions exist.
+- Good: ask the user which decision applies, then record its complete meaning.
+- Bad: `[ ] Follow https://example.test/platform-rfc`.
+- Good: `[ ] Deployment uses a managed container service with regional PostgreSQL; Platform RFC §3 — inspect region and failover constraints`.
+- Bad: `[ ] 首期采用通用电商方图；.agents/brainstorm/design.md — inspect accepted risks` because the brief breaks when the planning note is deleted.
+- Good: state the accepted dimensions, deferred platform templates, and accepted risks directly in the brief, with no brainstorm-file path.
 

package/bundled/skills/app-planner/references/project-conventions-discovery.md

@@ -55,5 +55,5 @@ Then ask in text: "Anything I missed that you'd like to standardize?" — if the
 
 ## After Discovery
 
-→ Save answers to `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` under `### Project Conventions` section (format: one bullet per convention)
+→ Save resolved convention meanings to `AGENTS.md` / `CLAUDE.md` / `CODEBUDDY.md` under `### Project Conventions` (one standalone domain rule per bullet). Do not copy raw answers, option labels, recommendation markers, question IDs, or dialogue provenance.
 → Output format will naturally vary per project — that is the intended behavior

package/bundled/skills/app-planner/references/rules/backend/derivation-rules.md

@@ -6,7 +6,7 @@
 
 ## Table of Contents
 
-- [Phase 2 Answer Direct-Fill Table (copy user answer text directly into placeholders)](#phase-2-answer-direct-fill-table-copy-user-answer-text-directly-into-placeholders)
+- [Phase 2 Normalized Semantic Fill Table](#phase-2-normalized-semantic-fill-table)
 - [Trigger Map](#trigger-map)
 - [Rule Block Definitions](#rule-block-definitions)
 - [Template Placeholder Coverage Self-Check](#template-placeholder-coverage-self-check)
@@ -14,7 +14,9 @@
 ---
 
 
-## Phase 2 Answer Direct-Fill Table (copy user answer text directly into placeholders)
+## Phase 2 Normalized Semantic Fill Table
+
+Resolve each selected option or custom reply into the complete semantic value shown by the examples. Never copy raw answer tokens, recommendation markers, question IDs, dialogue labels, or planning chronology into placeholders. The Source column is internal derivation metadata only and never appears in generated rules.
 
 | Template Placeholder | Source | Example Fill |
 |---------------------|--------|-------------|

package/bundled/skills/app-planner/references/rules/backend/question-bank.md

@@ -2,7 +2,7 @@
 
 > This file is read on demand by SKILL.md in Phase 2. The AI must strictly follow the group order defined in this file, asking **one group at a time (1–3 questions)**, never dumping all questions at once.
 > For every question, show the user: question number, question text, options, **recommended choice (marked "Recommended")**, and a one-line description.
-> After each user response, immediately record the choice to internal state `answers[Qx] = ...` and proceed to the next group.
+> After each response, resolve it to the complete option or custom meaning and record that internal-only semantic choice in `answers[Qx]`. Never store raw answer tokens, and never render question IDs or answer-map entries into generated artifacts.
 
 ---
 

package/bundled/skills/app-planner/references/rules/database/derivation-rules.md

@@ -6,14 +6,16 @@
 
 ## Table of Contents
 
-- [Phase 2 Answer Direct-Fill Table](#phase-2-answer-direct-fill-table)
+- [Phase 2 Normalized Semantic Fill Table](#phase-2-normalized-semantic-fill-table)
 - [Trigger Map](#trigger-map)
 - [Rule Block Definitions](#rule-block-definitions)
 
 ---
 
 
-## Phase 2 Answer Direct-Fill Table
+## Phase 2 Normalized Semantic Fill Table
+
+Resolve each selected option or custom reply into the complete semantic value shown by the examples. Never copy raw answer tokens, recommendation markers, question IDs, dialogue labels, or planning chronology into placeholders. The Source column is internal derivation metadata only and never appears in generated rules.
 
 | Template Placeholder | Source | Example Fill |
 |---------------------|--------|-------------|

package/bundled/skills/app-planner/references/rules/database/question-bank.md

@@ -2,7 +2,7 @@
 
 > This file is read on demand by SKILL.md in Phase 2. The AI must strictly follow the group order defined in this file, asking **one group at a time (1–3 questions)**, never dumping all questions at once.
 > For every question, show the user: question number, question text, options, **recommended choice (marked "Recommended")**, and a one-line description.
-> After each user response, immediately record the choice to internal state `answers[Qx] = ...` and proceed to the next group.
+> After each response, resolve it to the complete option or custom meaning and record that internal-only semantic choice in `answers[Qx]`. Never store raw answer tokens, and never render question IDs or answer-map entries into generated artifacts.
 
 ---
 

package/bundled/skills/app-planner/references/rules/frontend/derivation-rules.md

@@ -8,7 +8,7 @@
 
 ## Table of Contents
 
-- [Phase 2 Answer Direct-Fill Table (no derivation needed; copy the user's answer text directly into the placeholder)](#phase-2-answer-direct-fill-table-no-derivation-needed-copy-the-users-answer-text-directly-into-the-placeholder)
+- [Phase 2 Normalized Semantic Fill Table](#phase-2-normalized-semantic-fill-table)
 - [Trigger Map](#trigger-map)
 - [Rule Block Definitions](#rule-block-definitions)
 - [Template Placeholder Coverage Self-Check Table (Mandatory Check Before Phase 4 Rendering)](#template-placeholder-coverage-self-check-table-mandatory-check-before-phase-4-rendering)
@@ -16,16 +16,16 @@
 ---
 
 
-## Phase 2 Answer Direct-Fill Table (no derivation needed; copy the user's answer text directly into the placeholder)
+## Phase 2 Normalized Semantic Fill Table
 
-> These placeholders **don't need rule blocks**. In Phase 4, the AI directly writes the answers collected in Phase 2 into them.
+> These placeholders **don't need rule blocks**. Resolve the selected option or custom reply into the complete semantic value shown by the examples. Never copy raw answer tokens, recommendation markers, question IDs, dialogue labels, or planning chronology into placeholders. The Source column is internal derivation metadata only and never appears in generated rules.
 
 | Template Placeholder | Source | Example Fill |
 |---------------------|--------|-------------|
 | `{{ project_name }}` | Phase 0 auto-read from `package.json` `name` field; if unavailable, ask the user | `robot-svc` |
 | `{{ generated_at }}` | Phase 4, AI writes current ISO date | `2026-05-18` |
 | `{{ project_scope }}` | Phase 0 ask user ("Which directories/subprojects does this spec apply to?") | `apps/web, apps/admin` |
-| `{{ design_source }}` | Q8 answer | `Existing HTML prototype, path temp/` |
+| `{{ design_source }}` | Q8 answer | `Responsive layout, token, and component constraints extracted into this rules document; transient planning source omitted` |
 | `{{ framework }}` | Q1 answer | `React 18+` |
 | `{{ meta_framework }}` | Q2 answer | `Next.js (App Router)` |
 | `{{ package_manager }}` | Q3 answer | `pnpm` |

package/bundled/skills/app-planner/references/rules/frontend/question-bank.md

@@ -2,7 +2,7 @@
 
 > This file is read on demand by SKILL.md in Phase 2. The AI must strictly follow the group order defined in this file, asking **one group at a time (1–5 questions)**, never dumping all questions at once.
 > For every question, show the user: question number, question text, options, **recommended choice (marked "Recommended")**, and a one-line description.
-> After each user response, immediately record the choice to internal state `answers[Qx] = ...` and proceed to the next group.
+> After each response, resolve it to the complete option or custom meaning and record that internal-only semantic choice in `answers[Qx]`. Never store raw answer tokens, and never render question IDs or answer-map entries into generated artifacts.
 
 ---
 
@@ -153,13 +153,13 @@ Total: 25 questions.
 
 ## G4 — Design System
 
-### Q8. Primary Design/Mockup Source
+### Q8. Primary Design/Mockup Basis
 - **Options**:
-  - A) Existing HTML prototype in `temp/` directory
-  - B) Existing Figma designs
-  - C) Other location (specify path)
+  - A) Existing HTML prototype committed as a stable project artifact
+  - B) Existing Figma design with a stable accessible URL
+  - C) Other stable execution-time design source
   - D) None, starting from scratch
-- **Note**: If multiple sources exist, select the primary one. Additional sources will be noted in the output. A/B trigger a "design extraction" step (annotate token sources in output). D triggers a "recommend doing a style direction first" hint.
+- **Note**: If a source is transient—such as a brainstorm note, upload path, screenshot path, or temporary directory—extract its relevant layout, token, component, and interaction constraints into the generated rules and omit the path. Retain only purpose-tagged stable code/interface paths or URLs that the execution AI must inspect. D triggers a "recommend doing a style direction first" hint.
 - **Maps to**: `{{ design_source }}` (document header metadata)
 
 ### Q9. Token Naming Layers

package/bundled/skills/app-planner/references/rules/frontend/template.md

@@ -2,7 +2,7 @@
 
 > This document was generated by the `frontend-rules` skill on {{ generated_at }}
 > Scope: {{ project_scope }}
-> Design/mockup source: {{ design_source }}
+> Design basis: {{ design_source }}
 > Audience: All human developers + all AI coding assistants on this project
 >
 > **Usage**:

package/bundled/skills/app-planner/references/rules/mobile/derivation-rules.md

@@ -6,7 +6,7 @@
 
 ## Table of Contents
 
-- [Phase 2 Answer Direct-Fill Table (copy user answer text directly into placeholders)](#phase-2-answer-direct-fill-table-copy-user-answer-text-directly-into-placeholders)
+- [Phase 2 Normalized Semantic Fill Table](#phase-2-normalized-semantic-fill-table)
 - [Trigger Map](#trigger-map)
 - [Rule Block Definitions](#rule-block-definitions)
 - [Template Placeholder Coverage Self-Check](#template-placeholder-coverage-self-check)
@@ -14,7 +14,9 @@
 ---
 
 
-## Phase 2 Answer Direct-Fill Table (copy user answer text directly into placeholders)
+## Phase 2 Normalized Semantic Fill Table
+
+Resolve each selected option or custom reply into the complete semantic value shown by the examples. Never copy raw answer tokens, recommendation markers, question IDs, dialogue labels, or planning chronology into placeholders. The Source column is internal derivation metadata only and never appears in generated rules.
 
 | Template Placeholder | Source | Example Fill |
 |---------------------|--------|-------------|

package/bundled/skills/app-planner/references/rules/mobile/question-bank.md

@@ -2,7 +2,7 @@
 
 > This file is read on demand by SKILL.md in Phase 2. The AI must strictly follow the group order defined in this file, asking **one group at a time (1–3 questions)**, never dumping all questions at once.
 > For every question, show the user: question number, question text, options, **recommended choice (marked "Recommended")**, and a one-line description.
-> After each user response, immediately record the choice to internal state `answers[Qx] = ...` and proceed to the next group.
+> After each response, resolve it to the complete option or custom meaning and record that internal-only semantic choice in `answers[Qx]`. Never store raw answer tokens, and never render question IDs or answer-map entries into generated artifacts.
 
 ---
 

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`.