prizmkit 1.1.112 → 1.1.114

package/bundled/skills/prizmkit-prizm-docs/references/op-init.md

@@ -13,7 +13,7 @@ STEPS:
    - HIERARCHY RULE: directory X inside top-level module M maps to .prizmkit/prizm-docs/<M>/<X>.prizm, never to .prizmkit/prizm-docs/<X>.prizm.
    - Exclude .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .prizmkit/, .prizmkit/prizm-docs/, dev-pipeline/. If total module count > 30, ask user for include/exclude patterns.
 3. Create .prizmkit/prizm-docs/ directory structure mirroring the source tree exactly. For each top-level module M that has sub-modules, create the subdirectory .prizmkit/prizm-docs/<M>/.
-4. Generate root.prizm (L0) with PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY, MODULE_INDEX with multi-level entries as needed for efficient navigation (constrained by 4KB limit), RULES extracted from CODEBUDDY.md/CLAUDE.md/README/linter configs, PATTERNS, and CROSS_CUTTING (cross-module concerns spanning 2+ modules). Set PRIZM_VERSION: 4. Max 4KB. No CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths — git tracks history.
+4. Generate root.prizm (L0) with PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY, MODULE_INDEX with multi-level entries as needed for efficient navigation (constrained by 4KB limit), RULES extracted from user-facing main memory files (AGENTS.md, CLAUDE.md, CODEBUDDY.md), README, and linter configs. Do not extract RULES from AGENTS.private.md, CLAUDE.private.md, or CODEBUDDY.private.md because those files contain PrizmKit framework protocol text. Include PATTERNS and CROSS_CUTTING (cross-module concerns spanning 2+ modules). Set PRIZM_VERSION: 4. Max 4KB. No CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths — git tracks history.
    - If `.prizmkit/plans/project-brief.md` exists: add `PROJECT_BRIEF: .prizmkit/plans/project-brief.md` to root.prizm (generated by prizmkit-init). If not present, skip — prizmkit-init Phase 7 will add it later.
    - If module count > 15: use MODULE_GROUPS format instead of MODULE_INDEX — group modules by functional domain (3-8 domains, inferred from directory structure and module responsibilities). See prizm-docs-format.md for MODULE_GROUPS format.
    - For each module entry, auto-generate 3-6 keyword tags by scanning the module's key source files for: exported function/class names, imported library names, domain-specific terms in file/directory names. Add tags in square brackets after the module name (e.g., `- auth [login, session, jwt]: ...`). Tags are optional but recommended for projects with 10+ modules.
@@ -21,8 +21,8 @@ STEPS:
    - Top-level module M → write .prizmkit/prizm-docs/<M>.prizm (include SUBDIRS section with pointers to sub-module docs)
    - Sub-module S inside M → write .prizmkit/prizm-docs/<M>/<S>.prizm
    Each L1 includes MODULE (full relative path), FILES count, RESPONSIBILITY, SUBDIRS with pointers, KEY_FILES (5-10 most important), DEPENDENCIES (imports, imported-by, external), RULES (1-3 most critical only). L1 does NOT include INTERFACES, DATA_FLOW, TRAPS, or DECISIONS (those are L2, generated lazily). Max 4KB each.
-6. Skip L2 docs during init — L2 is created lazily on first file modification or when AI needs deep understanding (ON_DEEP_READ trigger). L2 contains behavioral detail: INTERFACES, DATA_FLOW, TRAPS, DECISIONS, full RULES, domain-specific sections.
-7. Configure UserPromptSubmit hook in platform settings per ${SKILL_DIR}/assets/prizm-docs-format.md.md Section 11.
+6. Skip L2 docs during init — L2 docs are created after real context exists, not as placeholders. During implementation, if relevant L2 is missing, the implementing skill reads target source files as fallback and proceeds. `/prizmkit-retrospective` creates or updates L2 after the change only when durable structure, behavior, dependencies, interfaces, or TRAPS exist. Explicit `/prizmkit-prizm-docs` repair/rebuild may also create L2 when fixing out-of-band doc drift.
+7. Configure UserPromptSubmit hook in platform settings per ${SKILL_DIR}/assets/prizm-docs-format.md Section 11.
 8. Validate all generated docs: size limits (L0 <= 4KB, L1 <= 4KB), pointer resolution (every -> reference resolves), no circular dependencies, KEY: value format compliance, no anti-patterns (prose, code blocks, markdown headers), L1 does not contain INTERFACES/DATA_FLOW/TRAPS/DECISIONS, no CHANGELOG sections/files, no UPDATED/date metadata, no feature/bug/refactor/task/session/run/pipeline/workflow IDs, no branch names, no absolute worktree paths, and no `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths.
 9. Report summary: modules discovered, L1 docs generated, files excluded, warnings.
 
@@ -30,16 +30,14 @@ OUTPUT: List of generated files, module count, and validation results.
 
 ## Post-Init Behavior
 
-After initialization, L2 docs are created incrementally:
+After initialization, L2 docs are created only when durable context exists:
 
-ON_MODIFY trigger:
-- First time AI modifies a file in sub-module S within module M:
-  IF .prizmkit/prizm-docs/<M>/<S>.prizm does not exist:
-    AI reads the source files in S, generates L2 doc, then proceeds with modification
-- This ensures L2 docs have real depth, written when AI has actual context
+ON_MODIFY behavior:
+- When an AI modifies a file in sub-module S within module M and `.prizmkit/prizm-docs/<M>/<S>.prizm` does not exist, the implementation reads the source files in S as fallback context and proceeds.
+- Do not block implementation only to create a placeholder L2 doc.
+- After the change, run `/prizmkit-retrospective` when structure, interfaces, dependencies, behavior, or durable TRAPS changed; retrospective creates or updates L2 then.
 
-ON_DEEP_READ trigger:
-- When AI needs to deeply understand a module but not modify it (e.g., code review, architecture analysis, dependency tracing, explaining complex logic):
-  IF .prizmkit/prizm-docs/<M>/<S>.prizm does not exist:
-    AI reads the source files in S, generates L2 doc for future reference
-- This ensures L2 docs are available for read-heavy analysis tasks, not just modifications
+ON_DEEP_READ behavior:
+- When an AI needs deep understanding but L2 is absent, read the relevant source files directly as fallback context.
+- Create L2 through `/prizmkit-retrospective` after normal development work, or through explicit `/prizmkit-prizm-docs` repair/rebuild when fixing out-of-band doc drift.
+- Do not create L2 merely because a module was read; L2 should capture durable knowledge, not transient investigation notes.

package/bundled/skills/prizmkit-test/SKILL.md

@@ -100,7 +100,7 @@ Interactive mode options:
 
 1. Full project
 2. Single module
-3. Single feature/spec directory
+3. Single historical feature/spec directory
 4. Current change artifact when an artifact directory is available
 
 For `scope=this-change`, build the in-scope source set using this priority:

package/bundled/skills/prizmkit-test/references/boundary-coverage-protocol.md

@@ -4,7 +4,7 @@ Use this protocol during `/prizmkit-test` Phase 4 and update it during Phase 5.
 
 ## Required Boundary Matrix
 
-Build this matrix before writing tests and update it after generated tests pass or produce `needs-review` findings. In `scope=this-change`, build the matrix only for in-scope feature interfaces/endpoints; unrelated interfaces are recorded under `Out of Scope Gaps` and do not trigger generated tests.
+Build this matrix before writing tests and update it after generated tests pass or produce `needs-review` findings. In `scope=this-change`, build the matrix only for interfaces/endpoints in the reviewed change artifact or changed-file set; unrelated interfaces are recorded under `Out of Scope Gaps` and do not trigger generated tests.
 
 | Module | Interface | Service Type | Happy Path | Request Validation | Auth / Permission / Ownership | Domain Invariants | Collection / Pagination | Date / Time | State Transitions | Dependency Failure | Response Contract | N/A Reasons | Final Status |
 |--------|-----------|--------------|------------|--------------------|-------------------------------|-------------------|-------------------------|-------------|-------------------|-------------------|-------------------|-------------|--------------|

package/bundled/skills/prizmkit-test/references/examples.md

@@ -118,7 +118,7 @@ Do not report `user` as covered just because both endpoints have success tests.
 
 **Caller**: `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`
 
-For non-feature changes, use the same command shape with any explicit change artifact directory that contains `spec.md` + `plan.md` and has a changed-files source.
+For non-feature changes, use the same command shape with any explicit change artifact directory that contains `spec.md` + `plan.md` and has a changed-files source. The `{{FEATURE_SLUG}}` path below is a compatibility example for existing feature artifacts; it does not limit `scope=this-change` to feature work.
 
 **Expected behavior**:
 - Reads the change artifact's `spec.md`, `plan.md`, and optional `context-snapshot.md`.
@@ -136,7 +136,7 @@ For non-feature changes, use the same command shape with any explicit change art
 - Generation Policy: in-scope-only
 
 ## Out of Scope Gaps
-- payment: missing legacy tests, but this feature did not change payment code.
+- payment: missing legacy tests, but this change did not affect payment code.
 
 ## Verdict
 PASS

package/bundled/skills/refactor-pipeline-launcher/SKILL.md

@@ -169,7 +169,7 @@ Detect user intent from their message, then follow the corresponding workflow:
    - No (default) — Use defaults for critic review and failure behavior
    - Yes — Configure critic review, stop-on-failure, and reasoning effort options
 
-   Note: Refactor filter defaults to all refactor items (by priority order). If the user selects "Other" on any option, handle their custom input.
+   Note: Refactor filter defaults to all refactor items. Runtime selects eligible refactors in stable list order after dependencies are completed; planners should order unrelated refactors by user priority before launch. If the user selects "Other" on any option, handle their custom input.
 
    **If user chose "Yes" to Advanced config**, run the advanced configuration round (a second `AskUserQuestion` round, plus a reasoning-effort follow-up). It applies to a minority of sessions, so the full question set lives in `${SKILL_DIR}/references/configuration.md` → **Advanced Configuration Round**. Default Critic to Off unless refactor items have `priority: "critical"` (in which case default to On).
 
@@ -225,6 +225,7 @@ Detect user intent from their message, then follow the corresponding workflow:
    - Summarize results: total refactors, succeeded, failed, skipped
    - If all succeeded: each refactor session has already run `prizmkit-retrospective` internally. Ask user what's next.
    - If some failed: show failed refactor IDs and suggest `python3 ./.prizmkit/dev-pipeline/cli.py reset refactor <R-XXX> --clean --run` for a fresh retry
+   - **Browser verification**: Refactor sessions with `browser_interaction` perform supplemental UI verification during execution. After completion, use `python3 ./.prizmkit/dev-pipeline/cli.py refactor status .prizmkit/plans/refactor-list.json` and per-refactor session logs as the source of truth before summarizing browser verification results.
 
    **If background daemon**:
    1. Verify launch:
@@ -328,7 +329,7 @@ Read the error-handling table in `${SKILL_DIR}/references/configuration.md` for
 ### Integration Notes
 
 - **After refactor-planner**: This is the natural next step. When user finishes refactor planning and has `.prizmkit/plans/refactor-list.json`, suggest launching the refactor pipeline.
-- **Session independence**: The pipeline runs completely detached. User can close the AI CLI session, open a new session later, and use this skill to check progress or stop the pipeline.
+- **Session independence**: Only Background daemon mode runs detached. Foreground runs in the current AI CLI session, and Manual mode prints commands without launching.
 - **Single instance per family**: Only one refactor pipeline can run at a time. Different pipeline families may coexist because they use separate daemon metadata and state directories.
 - **Pipeline coexistence**: Refactor pipeline uses `.prizmkit/state/refactor/` separate from `.prizmkit/state/features/` (features) and `.prizmkit/state/bugfix/` (bugs), so all three pipelines can run simultaneously without conflict.
 - **State preservation**: Stopping and restarting the pipeline resumes from where it left off -- completed refactors are not re-run.

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

@@ -265,12 +265,12 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
    ```
    The script fills in defaults (`$schema`, `created_at`, `created_by`), validates all fields, and writes the final file only if validation passes.
 3. If validation fails -> fix the draft and retry (max 3 attempts)
-4. If validation passes -> run the mandatory Post-Generation Plan Review Gate (see §Post-Generation Plan Review Gate below); apply accepted fixes to the draft/source plan, regenerate, and revalidate until pass
+4. If validation passes -> run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below); apply accepted fixes to the draft/source plan, regenerate, and revalidate until pass
 5. If review and validation pass -> present final summary
 
 **CHECKPOINT CP-RP-6**: `.prizmkit/plans/refactor-list.json` generated and validated.
 
-**CHECKPOINT CP-RP-7**: `/prizmkit-code-review` reviewed only newly added/changed refactor entries; accepted fixes were regenerated and revalidated.
+**CHECKPOINT CP-RP-7**: Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed refactor entries, applied accepted fixes through draft/source data, regenerated, and revalidated.
 
 ## Checkpoints (Mandatory Gates)
 
@@ -283,32 +283,26 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
 | **CP-RP-4** | Items Confirmed | User confirmed/modified/skipped each item | 5 |
 | **CP-RP-5** | Completeness OK | DAG valid, preservation strategies declared, no gaps | 6 |
 | **CP-RP-6** | Output Valid | `.prizmkit/plans/refactor-list.json` passes validation script | 7 |
-| **CP-RP-7** | Plan Review Passed | `/prizmkit-code-review` reviewed only newly added/changed refactor entries; accepted fixes were regenerated and revalidated | 7 |
-
-## Post-Generation Plan Review Gate
-
-User requirement preserved verbatim: `每次完成任务规划的时候，应该调用/prizmkit-code-review 对新增的计划内容进行review，确保生成新增的计划的正确行和完整性。`
-
-Run this gate **after** `.prizmkit/plans/refactor-list.json` passes the validation/generate script and **before** the final handoff summary recommends `refactor-pipeline-launcher`. This gate applies to full workflow, Mode B from analysis, and fast-path refactor planning.
-
-1. **Identify review scope**: compare the final validated refactor list against the pre-session list when one existed. Review only newly added or changed refactor entries. Do not re-review unchanged historical entries except when needed to verify dependency references or behavior-preservation interactions.
-2. **Invoke `/prizmkit-code-review` as a planning-quality gate** with an explicit prompt that this is a refactor-plan-entry review, not an implementation review. The review must check:
-   - schema correctness and compatibility with `dev-pipeline-refactor-list-v1`
-   - dependency/DAG soundness, including safe behavior-preserving order
-   - description completeness and headless execution readiness
-   - acceptance criteria specificity and measurable behavior-preservation verification
-   - `behavior_preservation` strategy quality and target scope consistency
-   - preservation of user-provided wording in `description`, `acceptance_criteria`, and `user_context`
-   - task-scoped `user_context` isolation: no unrelated sibling refactor goals, target files, constraints, or supplementary materials, and shared context appears on multiple items only when explicitly global
-   - priority/complexity calibration: every reviewed refactor has a short priority rationale and complexity rationale, 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
-3. **Keep the review planning-only**: do NOT start `refactor-pipeline-launcher`, do NOT run the refactor pipeline, do NOT run tests/builds/installs, and do NOT implement source-code refactors.
-4. **Apply accepted review fixes through the draft/source plan**: when a finding is accepted, update `.prizmkit/plans/refactor-list.draft.json` or the in-memory draft representation first, then regenerate the final file with:
+| **CP-RP-7** | Local Plan Review Passed | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only newly added/changed refactor entries, applied accepted fixes through draft/source data, regenerated, and revalidated | 7 |
+
+## Local Generated-Plan Review Gate
+
+User requirement preserved verbatim: `there is a litter bug for prizm-code-review will to check git diff in working space and staged space , however the .prizmkit will be gitignored in most situation.  so do you think the content should be change to inline a new reference file instead of use prizmkit-code-review`
+
+Run this gate **after** `.prizmkit/plans/refactor-list.json` passes the validation/generate script and **before** the final handoff summary recommends `refactor-pipeline-launcher`. This gate applies to full workflow, Mode B from analysis, and fast-path refactor planning when the current session generated, appended, or rewrote final refactor planning content. For validate-only, summary-only, or draft-save flows with no new final planning content, report: `Local generated-plan review: not applicable — no new final planning content written.`
+
+1. **Load the local reference**: read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the source of truth for this planner-output review loop.
+2. **Read actual planning artifacts directly**: inspect `.prizmkit/plans/refactor-list.json`, `.prizmkit/plans/refactor-list.draft.json` when present, and any pre-session or in-memory draft snapshot. Do not rely on `git status`, `git diff`, or `git diff --cached`, because `.prizmkit` planning artifacts are often gitignored or untracked.
+3. **Identify review scope**: compare by stable refactor IDs and item fields against the pre-session list when one existed. Ignore root generator metadata such as `$schema`, `created_at`, and `created_by`. Review only newly added or changed refactor entries; preserve unchanged historical entries except when needed to verify dependency references or behavior-preservation interactions.
+4. **Run the local checklist** from the reference: schema compatibility, dependency/DAG soundness, safe behavior-preserving order, description completeness, headless execution readiness, acceptance criteria measurability, `behavior_preservation` strategy quality, user-provided wording preservation, task-scoped `user_context` isolation, and priority/complexity calibration.
+5. **Keep the review planning-only**: do NOT start `refactor-pipeline-launcher`, do NOT run the refactor pipeline, do NOT run tests/builds/installs, and do NOT implement source-code refactors.
+6. **Apply accepted review fixes through the draft/source plan**: when a finding is accepted, update `.prizmkit/plans/refactor-list.draft.json` or the in-memory draft representation first, then regenerate the final file with:
    ```bash
    python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
    ```
    Do not hand-patch the final JSON as the source of truth; map final-output findings back to draft entries before regeneration.
-5. **Revalidate after every accepted fix batch**: the generate script must pass again before the planner can proceed. If validation fails, fix the draft and rerun until pass.
-6. **Report the gate outcome** in the final summary: include `/prizmkit-code-review` verdict, reviewed refactor IDs, accepted fixes (or "none"), and final validation result.
+7. **Revalidate after every accepted fix batch**: the generate script must pass again before the planner can proceed. If validation fails, fix the draft and rerun until pass.
+8. **Report the gate outcome** in the final summary: include local generated-plan review verdict, reviewed refactor IDs, accepted fixes (or "none"), and final validation result.
 
 ## Output Rules
 
@@ -444,10 +438,10 @@ Prevent accidental session exit without deliverable completion.
 
 ## Handoff Message Template
 
-After successful validation and the Post-Generation Plan Review Gate, report:
+After successful validation and the Local Generated-Plan Review Gate, report:
 1. Output file path
 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. Review result: `/prizmkit-code-review` verdict, reviewed refactor IDs, accepted fixes (or "none"), and final validation result
+5. Local generated-plan review result: verdict, reviewed refactor IDs, accepted fixes (or "none"), and final validation result
 6. Recommended next action: `refactor-pipeline-launcher`

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

@@ -34,7 +34,7 @@ For simple refactoring with minimal scope.
    ```bash
    python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
    ```
-5. If valid -> run the mandatory Post-Generation Plan Review Gate from the main `refactor-planner` skill before summarizing or recommending `refactor-pipeline-launcher`.
+5. If valid -> run the mandatory Local Generated-Plan Review Gate from the main `refactor-planner` skill before summarizing or recommending `refactor-pipeline-launcher`.
 6. If invalid -> apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
 
 ## When NOT to Use Fast Path
@@ -53,6 +53,6 @@ AI: [Uses AskUserQuestion with options: "Fast-path", "Full workflow"]
 User: [Selects "Fast-path"]
 AI: "Drafting R-001..."
 AI: [Validates immediately]
-AI: [Runs the Post-Generation Plan Review Gate on R-001 only]
+AI: [Runs the Local Generated-Plan Review Gate on R-001 only]
 AI: "Ready to proceed to dev-pipeline."
 ```

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

@@ -0,0 +1,63 @@
+# Generated Plan Review — Refactor Planner
+
+Use this local review loop after `.prizmkit/plans/refactor-list.json` has been generated and validated. This is a planner-output review, not an implementation/code-diff review.
+
+## Trigger
+
+Run only when the current `refactor-planner` session generated, appended, or rewrote final refactor planning content. For validate-only, summary-only, or draft-save flows with no new final planning content, report: `Local generated-plan review: not applicable — no new final planning content written.`
+
+## Direct Artifact Reads
+
+Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files directly:
+
+- Final list: `.prizmkit/plans/refactor-list.json`
+- Draft/source list when present: `.prizmkit/plans/refactor-list.draft.json`
+- Pre-session final list snapshot if captured in memory before edits
+- In-memory draft object if the session has not written a draft file yet
+
+Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whether planner output exists or changed. Do not invoke `/prizmkit-code-review` for this planner-output gate; `/prizmkit-code-review` remains the implementation/code-diff review gate after `/prizmkit-implement`.
+
+## 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.
+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.
+
+## Review Checklist
+
+For every reviewed refactor entry, check:
+
+- Schema compatibility with `dev-pipeline-refactor-list-v1` and `.prizmkit/dev-pipeline/templates/refactor-list-schema.json`
+- Dependency/DAG soundness, including safe behavior-preserving order
+- Description completeness, target scope clarity, and headless execution readiness
+- Acceptance criteria specificity and measurable behavior-preservation verification
+- `behavior_preservation` strategy quality and consistency with target scope and existing tests
+- User-provided wording preservation in `description`, `acceptance_criteria`, and `user_context`
+- 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
+- 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
+
+## Fix Loop
+
+1. Present findings with IDs, severity, evidence, and suggested draft/source changes.
+2. Accept only findings that improve planner correctness, completeness, or downstream behavior-preserving execution readiness.
+3. Apply accepted fixes to `.prizmkit/plans/refactor-list.draft.json` or the in-memory draft object first.
+4. Regenerate the final list through the existing generator:
+
+```bash
+python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
+```
+
+5. Re-run validation/generation until valid. Do not hand-patch `.prizmkit/plans/refactor-list.json` as the source of truth.
+6. Repeat the local review only for entries changed by accepted fixes.
+
+## Report Format
+
+Report in the final handoff summary:
+
+- `Local generated-plan review: PASS` or `NEEDS_FIXES`
+- Reviewed refactor IDs
+- 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-workflow/SKILL.md

@@ -172,10 +172,11 @@ Use Fast Path only after explicit user selection.
 1. Invoke `/prizmkit-plan` with the handoff brief and behavior-preservation expectations.
 2. Invoke `/prizmkit-implement` after the plan is ready.
 3. Run behavior-preservation checks identified in the plan.
-4. Run `/prizmkit-code-review` as the quality and behavior-preservation gate.
-5. Run `/prizmkit-retrospective` before commit because refactors often change durable structure.
-6. Run `/prizmkit-committer` with a `refactor(<scope>):` message.
-7. End the workflow after commit; do not call `refactor-planner`, `refactor-pipeline-launcher`, or monitoring.
+4. Run `/prizmkit-test` only when risk triggers match: public contracts, data models, migration behavior, weak behavior-preservation evidence, or explicit user verification request.
+5. Run `/prizmkit-code-review` when the user requested review, behavior-preservation uncertainty is high, or Full-path-level risk appears during implementation.
+6. Run `/prizmkit-retrospective` only when structure, interfaces, dependencies, behavior, or durable project knowledge changed.
+7. Run `/prizmkit-committer` with a `refactor(<scope>):` message.
+8. End the workflow after commit; do not call `refactor-planner`, `refactor-pipeline-launcher`, or monitoring.
 
 If the refactor starts changing behavior or grows beyond Fast Path criteria, pause and ask whether to switch to `feature-workflow` or Pipeline Path.
 
@@ -241,5 +242,5 @@ For start/stop/logs/retry execution, hand off to `refactor-pipeline-launcher`; d
 
 ## Output
 
-- Fast Path: `spec.md`, `plan.md`, behavior-preserving code changes, behavior-check evidence, review result, Prizm docs sync, and one refactor commit.
+- Fast Path: `spec.md`, `plan.md`, behavior-preserving code changes, behavior-check evidence, conditional test/review evidence when triggered, Prizm docs sync only when durable knowledge changed, and one refactor commit.
 - Pipeline Path: handoff brief, validated `.prizmkit/plans/refactor-list.json` from `refactor-planner`, and pipeline launch/status handled by `refactor-pipeline-launcher`.

package/package.json

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

package/src/clean.js

@@ -3,6 +3,19 @@ import path from 'path';
 import fs from 'fs-extra';
 import { loadMetadata, loadRulesMetadata } from './metadata.js';
 import { readManifest } from './manifest.js';
+import { privateProjectMemoryFile, projectMemoryFile } from './platforms.js';
+
+const PRIZMKIT_GITIGNORE_HEADERS = new Set([
+  '# PrizmKit',
+  '# PrizmKit 运行时全部产物（state/、prizm-docs/、.env、logs 等）',
+]);
+const PRIZMKIT_GITIGNORE_ENTRIES = new Set([
+  '.prizmkit/',
+  '.prizmkit/*',
+  'CLAUDE.private.md',
+  'AGENTS.private.md',
+  'CODEBUDDY.private.md',
+]);
 
 async function removePath(targetPath, dryRun) {
   if (!await fs.pathExists(targetPath)) {
@@ -54,11 +67,14 @@ async function cleanGitignore(projectRoot, dryRun) {
   }
 
   const content = await fs.readFile(gitignorePath, 'utf8');
-  const next = content
-    .replace(/\n\n# PrizmKit\n\.prizmkit\/\n?/g, '\n')
-    .replace(/\n# PrizmKit\n\.prizmkit\/\n?/g, '\n');
-
-  if (next === content) {
+  const nextLines = content.split(/\r?\n/).filter(line => {
+    const trimmed = line.trim();
+    return !PRIZMKIT_GITIGNORE_HEADERS.has(trimmed)
+      && !PRIZMKIT_GITIGNORE_ENTRIES.has(trimmed);
+  });
+  const next = nextLines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd();
+
+  if (`${next}\n` === content || next === content.trimEnd()) {
     return { updated: false, reason: 'no_prizmkit_section' };
   }
 
@@ -66,7 +82,7 @@ async function cleanGitignore(projectRoot, dryRun) {
     return { updated: true, reason: 'dry_run' };
   }
 
-  await fs.writeFile(gitignorePath, next.trimEnd() + '\n');
+  await fs.writeFile(gitignorePath, next ? `${next}\n` : '');
   return { updated: true };
 }
 
@@ -100,6 +116,38 @@ async function cleanMarkedProjectMemory(projectRoot, fileName, dryRun) {
   return { path: filePath, removed: true, note: '(PrizmKit section)' };
 }
 
+async function cleanProjectMemoryImport(projectRoot, fileName, privateFileName, dryRun) {
+  const filePath = path.join(projectRoot, fileName);
+  if (!await fs.pathExists(filePath)) {
+    return { path: filePath, removed: false, reason: 'not_found' };
+  }
+
+  const importPointer = `@./${privateFileName}`;
+  const content = await fs.readFile(filePath, 'utf8');
+  const next = content
+    .split(/\r?\n/)
+    .filter(line => line.trim() !== importPointer)
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trimEnd();
+
+  if (next === content.trimEnd()) {
+    return { path: filePath, removed: false, reason: 'no_prizmkit_import' };
+  }
+
+  if (dryRun) {
+    return { path: filePath, removed: false, reason: 'dry_run' };
+  }
+
+  if (!next) {
+    await fs.remove(filePath);
+    return { path: filePath, removed: true, note: '(PrizmKit import only)' };
+  }
+
+  await fs.writeFile(filePath, `${next}\n`);
+  return { path: filePath, removed: true, note: '(PrizmKit import)' };
+}
+
 async function removeGeneratedCodexConfig(projectRoot, dryRun) {
   const configPath = path.join(projectRoot, '.codex', 'config.toml');
   if (!await fs.pathExists(configPath)) {
@@ -228,7 +276,12 @@ export async function runClean(directory, options = {}) {
   const legacyCodexRulesDir = path.join(projectRoot, '.codex', 'rules');
   results.push(...await removeKnownEntries(legacyCodexRulesDir, ruleFileNames.map(n => `${n}.md`), dryRun));
 
-  for (const memoryFile of ['CODEBUDDY.md', 'CLAUDE.md', 'AGENTS.md']) {
+  for (const platform of ['codebuddy', 'claude', 'codex']) {
+    const memoryFile = projectMemoryFile(platform);
+    const privateMemoryFile = privateProjectMemoryFile(platform);
+    if (!memoryFile || !privateMemoryFile) continue;
+    results.push(await cleanProjectMemoryImport(projectRoot, memoryFile, privateMemoryFile, dryRun));
+    results.push(await cleanMarkedProjectMemory(projectRoot, privateMemoryFile, dryRun));
     results.push(await cleanMarkedProjectMemory(projectRoot, memoryFile, dryRun));
   }
 

package/src/config.js

@@ -38,6 +38,7 @@ import {
   resolveRuleNamesForRuntime,
   findStaleManagedPipelineFiles,
   removeStaleManagedPipelineFiles,
+  normalizeMainProjectMemoryContent,
 } from './scaffold.js';
 import {
   removeSkillFiles,
@@ -54,7 +55,7 @@ import {
   confirmTeamMode,
   confirmPipeline,
 } from './prompts.js';
-import { isKnownPlatform, platformLabel, projectMemoryFile, resolvePayloadPlatforms } from './platforms.js';
+import { isKnownPlatform, platformLabel, privateProjectMemoryFile, privateProjectMemoryFiles, projectMemoryFile, resolvePayloadPlatforms } from './platforms.js';
 import { normalizeRuntime, runtimeLabel } from './runtimes.js';
 import { applyAiCliLaunchToConfig, resolveAiCliLaunchSelection, storedAiCliLaunch } from './ai-cli-launch.js';
 
@@ -114,6 +115,50 @@ function getProjectMemoryFile(platform) {
   return projectMemoryFile(platform);
 }
 
+function logManagedMemoryWarnings(mainFile, warnings) {
+  for (const warning of warnings) {
+    console.log(chalk.yellow(`      ⚠ ${mainFile}: ${warning}; preserving unmatched marker content`));
+  }
+}
+
+async function removeProjectMemoryArtifacts(platform, projectRoot, dryRun) {
+  const mainFile = projectMemoryFile(platform);
+  const privateFile = privateProjectMemoryFile(platform);
+  if (!mainFile || !privateFile) return;
+
+  const privatePath = path.join(projectRoot, privateFile);
+  if (await fs.pathExists(privatePath)) {
+    if (dryRun) {
+      console.log(chalk.gray(`      [dry-run] remove ${privateFile}`));
+    } else {
+      await fs.remove(privatePath);
+      console.log(chalk.red(`      ✗ removed ${privateFile}`));
+    }
+  }
+
+  const mainPath = path.join(projectRoot, mainFile);
+  if (!await fs.pathExists(mainPath)) return;
+
+  const current = await fs.readFile(mainPath, 'utf-8');
+  const normalized = normalizeMainProjectMemoryContent(current, privateFile);
+  logManagedMemoryWarnings(mainFile, normalized.warnings);
+  const next = normalized.content.trim();
+  if (next === current.trim()) return;
+
+  if (dryRun) {
+    console.log(chalk.gray(`      [dry-run] update ${mainFile} (remove PrizmKit import)`));
+    return;
+  }
+
+  if (!next) {
+    await fs.remove(mainPath);
+    console.log(chalk.red(`      ✗ removed ${mainFile} (empty after PrizmKit import removal)`));
+  } else {
+    await fs.writeFile(mainPath, `${next}\n`, 'utf-8');
+    console.log(chalk.green(`      ✓ updated ${mainFile} (removed PrizmKit import)`));
+  }
+}
+
 async function migrateProjectMemoryOnPlatformDrop(droppedPlatform, newPlatforms, projectRoot, dryRun) {
   const sourceFile = getProjectMemoryFile(droppedPlatform);
   if (!sourceFile) return;
@@ -135,8 +180,13 @@ async function migrateProjectMemoryOnPlatformDrop(droppedPlatform, newPlatforms,
     return;
   }
 
-  const sourceContent = await fs.readFile(sourcePath, 'utf-8');
-  if (!sourceContent.trim()) return;
+  const normalized = normalizeMainProjectMemoryContent(
+    await fs.readFile(sourcePath, 'utf-8'),
+    privateProjectMemoryFile(droppedPlatform),
+  );
+  logManagedMemoryWarnings(sourceFile, normalized.warnings);
+  const sourceContent = normalized.content.trim();
+  if (!sourceContent) return;
 
   if (!await fs.pathExists(targetPath)) {
     const normalized = sourceContent.endsWith('\n') ? sourceContent : `${sourceContent}\n`;
@@ -244,18 +294,8 @@ async function removePlatformFiles(platform, projectRoot, manifest, dryRun) {
     }
   }
 
-  // Project memory file
-  const memoryFile = projectMemoryFile(platform);
-  if (!memoryFile) return;
-  const memoryPath = path.join(projectRoot, memoryFile);
-  if (await fs.pathExists(memoryPath)) {
-    if (dryRun) {
-      console.log(chalk.gray(`      [dry-run] remove ${memoryFile}`));
-    } else {
-      await fs.remove(memoryPath);
-      console.log(chalk.red(`      ✗ removed ${memoryFile}`));
-    }
-  }
+  // Project memory artifacts: remove only managed private file/imports, not user-owned main content.
+  await removeProjectMemoryArtifacts(platform, projectRoot, dryRun);
 
   // Command assets (Claude only)
   if (platform === 'claude') {
@@ -611,10 +651,8 @@ export async function runConfig(directory, options = {}) {
       console.log(chalk.blue('\n    Settings & Rules:'));
       await installSettings(p, projectRoot, { pipeline: newConfig.pipeline, rules: newConfig.rules }, false, newConfig.runtime);
 
-      if (isNew) {
-        console.log(chalk.blue('\n    Project Memory:'));
-        await installProjectMemory(p, projectRoot, false);
-      }
+      console.log(chalk.blue('\n    Project Memory:'));
+      await installProjectMemory(p, projectRoot, false);
 
       if (newConfig.team) {
         console.log(chalk.blue('\n    Team Config:'));
@@ -648,7 +686,10 @@ export async function runConfig(directory, options = {}) {
 
   // 5f. Update .gitignore
   console.log(chalk.blue('\n    Gitignore:'));
-  await installGitignore(projectRoot, { pipeline: newConfig.pipeline }, false);
+  await installGitignore(projectRoot, {
+    pipeline: newConfig.pipeline,
+    privateMemoryFiles: privateProjectMemoryFiles(newPlatforms),
+  }, false);
 
   // 5g. Runtime-aware git hook and PrizmKit helper scripts
   if (newConfig.runtime !== currentConfig.runtime || runtimeManifestNeedsNormalization || runtimeOptionNeedsNormalization) {

package/src/gitignore-template.js

@@ -9,11 +9,14 @@
  * @returns {string}
  */
 export function generateGitignore(options = {}) {
-  void options;
+  const privateMemoryFiles = Array.isArray(options.privateMemoryFiles)
+    ? options.privateMemoryFiles.filter(Boolean)
+    : [];
   const lines = [
-    '# PrizmKit 运行时全部产物（state/、prizm-docs/、.env、logs 等）',
+    '# PrizmKit',
     '.prizmkit/*',
+    ...privateMemoryFiles,
   ];
 
-  return lines.join('\n');
+  return [...new Set(lines)].join('\n');
 }

package/src/manifest.js

@@ -9,7 +9,7 @@
 
 import fs from 'fs-extra';
 import path from 'path';
-import { projectMemoryFile, resolvePayloadPlatforms } from './platforms.js';
+import { privateProjectMemoryFile, projectMemoryFile, resolvePayloadPlatforms } from './platforms.js';
 import { normalizeRuntime } from './runtimes.js';
 
 const MANIFEST_FILE = 'manifest.json';
@@ -100,7 +100,11 @@ export function buildManifest({
       pipeline: pipeline ? [...pipeline] : [],
       extras: extras ? [...extras] : [],
       payloadPlatforms: installedPayloadPlatforms,
-      other: [...new Set(installedPayloadPlatforms.map(projectMemoryFile).filter(Boolean))],
+      memory: {
+        main: [...new Set(installedPayloadPlatforms.map(projectMemoryFile).filter(Boolean))],
+        private: [...new Set(installedPayloadPlatforms.map(privateProjectMemoryFile).filter(Boolean))],
+      },
+      other: [...new Set(installedPayloadPlatforms.map(privateProjectMemoryFile).filter(Boolean))],
     },
   };
 }

package/src/platforms.js

@@ -62,6 +62,20 @@ export function projectMemoryFile(platform) {
   return null;
 }
 
+export function privateProjectMemoryFile(platform) {
+  const mainFile = projectMemoryFile(platform);
+  if (!mainFile) return null;
+  return mainFile.replace(/\.md$/i, '.private.md');
+}
+
+export function projectMemoryFiles(platform) {
+  return [projectMemoryFile(platform), privateProjectMemoryFile(platform)].filter(Boolean);
+}
+
+export function privateProjectMemoryFiles(platforms) {
+  return [...new Set((platforms || []).map(privateProjectMemoryFile).filter(Boolean))];
+}
+
 export function defaultCliForPlatform(platform) {
   if (platform === 'claude') return 'claude';
   if (platform === 'codebuddy') return 'cbc';