prizmkit 1.1.60 → 1.1.62

package/bin/create-prizmkit.js

@@ -31,7 +31,7 @@ program
 program
   .command('install [directory]')
   .description('Install PrizmKit into a project directory')
-  .option('--platform <platform>', 'Target platform: codebuddy, claude, codex, both, or all')
+  .option('--platform <platform>', 'Target platform: codebuddy, claude, codex, or all')
   .option('--runtime <runtime>', 'Runtime assets: unix, windows, or auto')
   .option('--skills <suite>', 'Skill suite: core, minimal, or recommended:<type> (frontend/backend/fullstack/library)', 'core')
   .option('--team', 'Enable multi-agent team mode (default: true)')
@@ -90,7 +90,7 @@ program
 program
   .command('config [directory]')
   .description('Reconfigure existing PrizmKit installation (change platform, skills, rules, options)')
-  .option('--platform <platform>', 'Target platform: codebuddy, claude, codex, both, or all')
+  .option('--platform <platform>', 'Target platform: codebuddy, claude, codex, or all')
   .option('--runtime <runtime>', 'Runtime assets: unix, windows, or auto')
   .option('--skills <suite>', 'Skill suite: core, minimal, or recommended:<type>')
   .option('--rules <preset>', 'Rules preset: recommended, minimal, or none')

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.60",
-  "bundledAt": "2026-06-08T12:49:43.025Z",
-  "bundledFrom": "62b5c3d"
+  "frameworkVersion": "1.1.62",
+  "bundledAt": "2026-06-08T16:36:59.712Z",
+  "bundledFrom": "280ca81"
 }

package/bundled/adapters/codex/skill-adapter.js

@@ -16,12 +16,27 @@ function toCodexSkillReference(commandName) {
   return `PrizmKit skill \`${commandName}\` (\`.agents/skills/${commandName}/SKILL.md\`)`;
 }
 
+function applyCodexInteractionCompatibility(content) {
+  const fallbackInstruction = 'Use `request_user_input` when available. If unavailable in the current Codex surface, including Default mode, ask the same options directly in chat and wait for an explicit answer. Tool unavailability is not permission to choose defaults.';
+
+  return content
+    .replace(/\bAskUserQuestion\b/g, 'request_user_input')
+    .replace(
+      /Do NOT render options as plain text — the user must be able to click\/select\./g,
+      fallbackInstruction
+    )
+    .replace(
+      /Do NOT render options as plain text \(e\.g\., `\[A\] option \[B\] option`\) — the user must be able to click\/select, not type a letter\./g,
+      fallbackInstruction
+    );
+}
+
 export function convertSkill(skillContent, skillName) {
   const { frontmatter, body } = parseFrontmatter(skillContent);
 
   if (!frontmatter.name) frontmatter.name = skillName;
 
-  let convertedBody = body.replace(
+  let convertedBody = applyCodexInteractionCompatibility(body).replace(
     /\$\{SKILL_DIR\}/g,
     `.agents/skills/${skillName}`
   );
@@ -34,7 +49,7 @@ export function convertSkill(skillContent, skillName) {
     }
   );
 
-  const codexNote = `> Codex project install: when instructions mention a PrizmKit slash command such as \`/prizmkit-plan\`, read and execute the matching project skill at \`.agents/skills/prizmkit-plan/SKILL.md\`.\n\n`;
+  const codexNote = `> Codex project install: when instructions mention a PrizmKit slash command such as \`/prizmkit-plan\`, read and execute the matching project skill at \`.agents/skills/prizmkit-plan/SKILL.md\`.\n>\n> Codex interaction compatibility: when this skill or any referenced PrizmKit file says \`AskUserQuestion\`, use Codex \`request_user_input\` if it is available. If the current Codex surface does not expose \`request_user_input\`, including Default mode, ask the same question directly in chat and wait for explicit user input. Tool unavailability is not permission to choose defaults. If a source instruction asks more questions than Codex allows in one call, split them into multiple calls while preserving order. Only true headless/non-interactive runs, such as \`codex exec\` automation with no conversational user available, may skip interaction and choose documented defaults; never silently choose defaults in an interactive session.\n\n`;
 
   return buildMarkdown(frontmatter, codexNote + convertedBody);
 }

package/bundled/agents/prizm-dev-team-dev.md

@@ -48,8 +48,8 @@ If the snapshot does not exist:
 8. Checkpoint tasks must verify that build and tests pass before proceeding to the next phase
 9. Execute sequential tasks in order; stop on failure. Parallel `[P]` tasks may continue
 10. When creating a new sub-module, generate the corresponding `.prizmkit/prizm-docs/` L2 document. **Batch independent operations**: combine multiple `mkdir -p` into one command; issue multiple independent `Write` calls for different `.prizmkit/prizm-docs/` files in a single message turn (they have no dependencies between them).
-11. **`.prizmkit/prizm-docs/` write safety**: Before writing ANY `.prizmkit/prizm-docs/` file, check if it already exists (`ls <path>`). If it **exists**: only append or update structural fields (KEY_FILES, INTERFACES, DEPENDENCIES, file counts, UPDATED date) — **never overwrite the full file**. DECISIONS and CHANGELOG sections are **append-only** — never delete or replace existing entries. If it does **not** exist: create it only for sub-modules you are actively creating in this session. Do NOT write `.prizmkit/prizm-docs/` files for modules you are not directly creating.
-11. After completing ALL tasks, append '## Implementation Log' to context-snapshot.md: files changed/created, key decisions, notable discoveries
+11. **`.prizmkit/prizm-docs/` write safety**: Before writing ANY `.prizmkit/prizm-docs/` file, check if it already exists (`ls <path>`). If it **exists**: update only durable structural/knowledge fields (KEY_FILES, INTERFACES, DEPENDENCIES, file counts, RULES, TRAPS, DECISIONS) — **never overwrite the full file**. Do not add CHANGELOG, UPDATED/date fields, Bug IDs, feature IDs, refactor IDs, task IDs, session IDs, run IDs, pipeline IDs, workflow IDs, branch names, absolute worktree paths, pipeline artifact paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths. If a durable fact changes, update the existing section in place. If the file does **not** exist: create it only for sub-modules you are actively creating in this session. Do NOT write `.prizmkit/prizm-docs/` files for modules you are not directly creating.
+12. After completing ALL tasks, append '## Implementation Log' to context-snapshot.md: files changed/created, key decisions, notable discoveries
 
 ### Never Do (NEVER)
 
@@ -59,7 +59,8 @@ If the snapshot does not exist:
 - **Do not execute any git operations** (git commit / git add / git reset / git push are all prohibited — the Orchestrator handles commits via /prizmkit-committer)
 - Do not modify any files in `.prizmkit/specs/` except `plan.md` (marking Tasks [x]) and `context-snapshot.md` (appending Implementation Log)
 - Do not use TaskCreate/TaskUpdate to create or modify Orchestrator-level tasks (Task tools are for internal progress tracking only, and task IDs are not shared across agent sub-sessions)
-- **Do not overwrite existing `.prizmkit/prizm-docs/` files in full** — if a doc already exists, only update structural fields; never replace the entire file. Do NOT write `.prizmkit/prizm-docs/` entries for modules you are not actively creating in this session.
+- **Do not overwrite existing `.prizmkit/prizm-docs/` files in full** — if a doc already exists, only update the affected durable fields; never replace the entire file. Do NOT write `.prizmkit/prizm-docs/` entries for modules you are not actively creating in this session.
+- **Do not leak internal PrizmKit metadata into product surfaces or memory docs** — feature IDs (`F-001`), bug/refactor IDs, task IDs, session IDs, run IDs, pipeline IDs, workflow IDs, branch names, absolute worktree paths, pipeline artifact paths, and `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths must not appear in `.prizmkit/prizm-docs/`, user-visible UI copy, API responses, emails, notifications, or tests that assert visible product text.
 
 ### Behavioral Rules
 
@@ -83,7 +84,8 @@ DEV-15: After ALL tasks, append '## Implementation Log' to context-snapshot.md (
 DEV-16: Without context-snapshot: read .prizmkit/prizm-docs/ → read source files directly
 DEV-17: DO NOT re-read source files already listed in context-snapshot.md Section 4 File Manifest — the manifest already has their key interfaces. Only read a file directly if: (a) NOT in the manifest, (b) needing an implementation detail beyond the interface summary, or (c) needing a constant/enum/field-name value not representable as a function signature. Unnecessary re-reads waste significant context budget.
 DEV-18: When tests fail, run `$TEST_CMD 2>&1 | tee /tmp/test-out.txt` ONCE, then grep `/tmp/test-out.txt` for failure details. Never re-run the full test suite just to apply a different grep filter to its output.
-DEV-19: Before writing any `.prizmkit/prizm-docs/` file, check if it exists. If it exists: only update structural fields (KEY_FILES, INTERFACES, DEPENDENCIES, file counts, UPDATED) — never overwrite the full file. DECISIONS/CHANGELOG are append-only. Only create new L2 docs for sub-modules you are actively creating in this session.
+DEV-19: Before writing any `.prizmkit/prizm-docs/` file, check if it exists. If it exists: only update durable fields (KEY_FILES, INTERFACES, DEPENDENCIES, file counts, RULES, TRAPS, DECISIONS) — never overwrite the full file. Never add CHANGELOG, UPDATED/date fields, or workflow metadata. Only create new L2 docs for sub-modules you are actively creating in this session.
+DEV-20: Internal tracking IDs are not product copy. Before writing UI text or UI-copy assertions, translate references like `F-003 guard` into product-language behavior such as `the high-risk guard`. Add regression coverage when a feature touches user-visible text.
 ```
 
 ### Workflow
@@ -121,4 +123,3 @@ Direct communication between Agents is allowed, but key messages and conclusions
 - Send COMPLETION_SIGNAL to indicate all tasks are complete
 - Send ESCALATION to report interface ambiguities or task blockers
 - Receive TASK_ASSIGNMENT to get assigned work
-

package/bundled/rules/prizm/prizm-documentation.md

@@ -22,6 +22,7 @@ FORMAT RULES (enforced by pre-commit hook — violations block commit):
 - KEY: value pairs and dash-prefixed lists only
 - PROHIBITED: prose paragraphs, markdown headers (##/###), code blocks (```), emoji, ASCII art
 - No UPDATED timestamps — git is the authoritative source for temporal information
+- PROHIBITED: CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, and `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths
 - This format is designed for AI token efficiency, not human readability. Do not add human-friendly formatting.
 
 SIZE LIMITS (hard — pre-commit hook blocks commits exceeding these):
@@ -32,7 +33,7 @@ SIZE LIMITS (hard — pre-commit hook blocks commits exceeding these):
 SIZE OVERFLOW HANDLING:
 - L0 approaching 4KB: if MODULE_INDEX has > 15 entries, convert to MODULE_GROUPS format (group by domain). Otherwise consolidate descriptions, keep only top-5 RULES, remove PATTERNS detail.
 - L1 approaching 4KB: trim KEY_FILES descriptions, ensure RULES <= 3 entries, move detail to L2
-- L2 approaching 5KB: archive CHANGELOG entries older than 90 days to changelog-archive.prizm
+- L2 approaching 5KB: remove stale or trivially derivable entries; never create changelog-archive.prizm
 - NEVER exceed hard limits — pre-commit hook will block the commit
 
 REQUIRED FIELDS PER LEVEL:
@@ -58,7 +59,6 @@ L2 detail.prizm:
 - DEPENDENCIES
 - INTERFACES
 - TRAPS (with severity prefix: [CRITICAL], [HIGH], or [LOW])
-- CHANGELOG
 
 L2 GENERATION TEMPLATE (use when AI first touches a sub-module with no L2 doc):
 
@@ -74,7 +74,5 @@ INTERFACES:
 - <exported function/class>: <signature and purpose>
 TRAPS:
 - [LOW] <gotcha, race condition, or non-obvious coupling> | FIX: <approach>
-CHANGELOG:
-- root | add: initial L2 documentation
 
 TRAPS is critical — always record gotchas, race conditions, non-obvious behavior, and surprising coupling between modules. Every TRAP must have a severity prefix ([CRITICAL], [HIGH], or [LOW]).

package/bundled/rules/prizm/prizm-progressive-loading.md

@@ -9,4 +9,5 @@ This project uses PrizmKit's progressive loading protocol:
 - ON FILE EDIT: Read L2 (`.prizmkit/prizm-docs/<module>/<submodule>.prizm`) before modifying
 - NEVER load all .prizm docs at once
 - Arrow notation (->) in .prizm files indicates load pointers
-- DECISIONS and CHANGELOG in .prizm files are append-only
+- .prizm files do not contain 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
+- Update stale durable knowledge in place; git history is the change log

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.60",
+  "version": "1.1.62",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",

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

@@ -45,7 +45,7 @@ If you believe the task is better suited for a different workflow, you MUST:
 - Codex → `AGENTS.md`
 - Claude Code → `CLAUDE.md`
 - CodeBuddy → `CODEBUDDY.md`
-- `both` → `CLAUDE.md` and `CODEBUDDY.md`; `all` → all three files.
+- `all` → all three files.
 - Only when the manifest is missing, fall back to installed PrizmKit-owned platform files such as `.codex/agents/*.toml`, `.claude/commands/prizm-kit.md`, or `.codebuddy/skills/prizm-kit/SKILL.md`. Do not treat a generic `.agents/` directory as Codex.
 
 **After planning is complete**, you MUST:

package/bundled/skills/app-planner/references/architecture-decisions.md

@@ -29,7 +29,7 @@ After Phase 2 (Confirm constraints and tech assumptions), before Phase 3 (Captur
    - `codex` → append to `AGENTS.md`
    - `claude` → append to `CLAUDE.md`
    - `codebuddy` → append to `CODEBUDDY.md`
-   - `both` → append to `CLAUDE.md` and `CODEBUDDY.md`; `all` → append to all three files.
+   - `all` → append to all three files. Legacy manifests may contain `both`; treat it as read-only compatibility and append to `CLAUDE.md` and `CODEBUDDY.md` only when encountered.
    - Only when the manifest is missing, fall back to PrizmKit-owned install artifacts: `.codex/agents/*.toml`, `.claude/commands/prizm-kit.md`, `.codebuddy/skills/prizm-kit/SKILL.md`.
    - Do not treat a generic `.agents/` directory as Codex; it may contain unrelated third-party skills.
    - If no platform can be determined, skip (no project instruction file).

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

@@ -111,7 +111,7 @@ Before questions, check optional context files (never block if absent):
 - `.prizmkit/config.json` (existing stack preferences and detected tech stack)
 - `.prizmkit/plans/project-brief.md` (project context from app-planner, if available)
 - existing `.prizmkit/plans/feature-list.json` (required for incremental mode)
-- Platform instruction file: use the `platform` field in `.prizmkit/manifest.json` as source of truth when present (`codex` → `AGENTS.md`, `claude` → `CLAUDE.md`, `codebuddy` → `CODEBUDDY.md`; `both`/`all` → read every matching file)
+- Platform instruction file: use the `platform` field in `.prizmkit/manifest.json` as source of truth when present (`codex` → `AGENTS.md`, `claude` → `CLAUDE.md`, `codebuddy` → `CODEBUDDY.md`, `all` → read every matching file). Legacy manifests may contain `both`; treat it as read-only compatibility and read `CLAUDE.md` plus `CODEBUDDY.md` only when encountered.
 - If `.prizmkit/prizm-docs/root.prizm` is absent and the project has existing source code, scan the directory structure to understand the codebase layout:
   ```bash
   find . -maxdepth 2 -type d \

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

@@ -41,6 +41,7 @@ For each unchecked task in plan.md, in order:
 
 1. Read L1/L2 doc for the target file's module — check TRAPS and DECISIONS before modifying files
 2. Apply TDD where applicable: write a failing test first, then implement until it passes. For UI components or configuration changes where unit tests don't apply, skip the test-first step.
+   - **Internal ID hygiene**: Do not place PrizmKit feature/bug/refactor IDs (`F-001`, `B-001`, `R-001`), task IDs, session IDs, run IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths in `.prizmkit/prizm-docs/`, user-visible UI text, API responses, emails, notifications, or tests that assert visible product copy. Translate internal references into durable product/domain language before writing memory docs, tests, or UI copy.
    - **Cover three paths for each function**: happy path (valid inputs producing expected behavior), edge cases (boundary values specific to the parameter type and domain — e.g., zero/min/max for numeric, empty collection, boundary index), and error conditions (inputs that should trigger error handling). Determine edge cases from the function's parameter types and domain logic, not from a fixed checklist. If a function has no edge or error paths, don't force them.
    - **No redundant tests**: Check if a test for this behavior already exists before writing. Each test must verify a uniquely different code path — don't write multiple tests that exercise the same logic.
    - **Test your own code only**: Don't test framework behavior, third-party library internals, or language built-ins. For library calls, test the integration point (correct parameters passed, return value correctly handled), not the library itself.

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

@@ -183,7 +183,7 @@ Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structu
   - For each module entry in MODULE_INDEX/MODULE_GROUPS, include keyword tags extracted from the module's source files — scan for: exported symbols, imported packages, domain terms in file/directory names. Format: `- module-name [tag1, tag2, tag3]: ...`. Tags help AI match user intent to relevant modules.
   - Generate L1 docs for top-level modules at `.prizmkit/prizm-docs/<M>.prizm` and for sub-modules at `.prizmkit/prizm-docs/<M>/<S>.prizm`
   - Skip L2 (lazy generation) — L2 is generated on first file modification, saving tokens upfront
-  - Do not create auxiliary `changelog.prizm` or date/time metadata fields; git history is the source of change history
+  - Do not create auxiliary `changelog.prizm`, 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 history is the source of change history
 
 **Phase 6: Workspace Initialization**
 6a. Create `.prizmkit/` directory structure (if missing):

package/bundled/skills/prizmkit-init/references/config-schema.md

@@ -19,11 +19,13 @@ Handles re-init without losing user edits:
 | Field | Type | Description |
 |-------|------|-------------|
 | `adoption_mode` | string | `"passive"` \| `"advisory"` \| `"active"` |
-| `platform` | string | `"codebuddy"` \| `"claude"` \| `"both"` |
+| `platform` | string | `"codebuddy"` \| `"claude"` \| `"codex"` \| `"all"` |
 | `tech_stack` | object | Detected or user-provided tech stack |
 | `tech_stack._auto_detected` | boolean | `true` if auto-detected, `false` if user-provided |
 | `detected_layers` | string[] | Development layers detected in the project. Written by prizmkit-init Phase 4.5. Used to determine available rule configuration options. Values: `frontend` / `backend` / `database` / `mobile`. Empty array when no layers detected or user skipped rules. Always updated on every init run based on fresh code detection — not gated by `_auto_detected` (see Merge Strategy above). |
 
+Legacy manifests may still contain `both` for read-only migration compatibility. New config writes must use `codebuddy`, `claude`, `codex`, or `all`.
+
 ## Examples
 
 Fullstack project:

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

@@ -49,6 +49,8 @@ A universal spec + plan generator. Takes a natural-language description of ANY d
 
 **Writing principles**: Focus on WHAT and WHY, never HOW. Every goal needs acceptance criteria. Scope boundaries must be explicit. Mark all genuine ambiguities — the clarification phase resolves them.
 
+**Internal ID hygiene**: PrizmKit IDs (`F-001`, `B-001`, `R-001`), task IDs (`T-100`), session IDs, run IDs, branch names, absolute worktree paths, and `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths are internal tracking metadata. They may appear in specs, plans, commit messages, and non-memory pipeline artifacts, but must never be written to `.prizmkit/prizm-docs/`, user-visible product copy, UI text, API responses, or expected UI strings in tests. If a behavior is scoped to the current feature, describe the product behavior without the ID.
+
 ### Phase 1: Design (spec.md → plan.md)
 
 **Precondition**: `spec.md` exists in the artifact directory.

package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md

@@ -37,6 +37,7 @@ CORE_PRINCIPLES:
 - Self-updating (docs stay fresh via commit-time hooks)
 - Universal (language and framework agnostic)
 - Durable project knowledge over auxiliary history (decisions, traps, interfaces, dependencies)
+- Memory hygiene over traceability noise (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)
 - Size-enforced (hard limits per level prevent bloat)
 - Lazy L2 generation (detail docs created on first modification or deep read, not during init)
 - Rules hierarchy (root.prizm RULES are authoritative, module RULES supplement only)
@@ -294,7 +295,7 @@ CONSTRAINTS:
 - DATA_FLOW: describes how data moves through the module (moved here from L1 in V4)
 - RULES: full module-specific rules list (L1 only has a 1-3 item summary)
 - DOMAIN-SPECIFIC SECTIONS are flexible, not prescribed
-- DECISIONS is append-only (never delete, archive if >20 entries)
+- DECISIONS records durable rationale only; update or remove stale entries in place when code reality changes
 - TRAPS section is CRITICAL for preventing AI from making known mistakes
 - TRAPS entries MUST have severity prefix ([CRITICAL], [HIGH], or [LOW]). [REVIEW] may precede severity as a temporary staleness marker.
 - TRAPS optional fields: append `| REF: <7-char-hash>` for traceability, `| STALE_IF: <glob>` for auto-expiry detection
@@ -307,6 +308,7 @@ CONSTRAINTS:
 
 TEMPORAL_INFO: Git history is the authoritative source for change timing and edit history.
 AUXILIARY_FIELDS: Do not generate CHANGELOG or UPDATED fields in .prizm files.
+WORKFLOW_METADATA: Do not write feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths into .prizm files.
 RATIONALE: Keep project memory focused on durable architecture, interfaces, dependencies, traps, rules, and decisions.
 
 ---
@@ -429,6 +431,7 @@ DETAILED_STEPS: → ${SKILL_DIR}/references/op-update.md
 
 NEVER: Add CHANGELOG sections or changelog.prizm during doc sync.
 NEVER: Add UPDATED/date/time fields to .prizm files.
+NEVER: Add workflow metadata such as feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths.
 RATIONALE: Git already provides history; .prizm files should store only durable project memory.
 
 ---
@@ -446,6 +449,8 @@ NEVER: Stale information (update or delete, never leave outdated entries)
 NEVER: Full file contents or large code blocks (summarize purpose and interfaces)
 NEVER: TODO items or future plans (those belong in issue trackers)
 NEVER: Session-specific context or conversation history (docs are session-independent)
+NEVER: Workflow metadata such as feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths
+NEVER: CHANGELOG sections, changelog.prizm, or update-history sections
 NEVER: Flowcharts, diagrams, mermaid blocks, or ASCII art (wastes tokens, AI cannot parse visually)
 NEVER: Markdown headers (## / ###) inside .prizm files (use ALL CAPS KEY: format instead)
 NEVER: Rewrite entire .prizm files on update (modify only affected sections)

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 date/time metadata fields — git tracks modification times.
+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.
    - 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.
@@ -23,7 +23,7 @@ STEPS:
    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.
-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 date/time metadata fields (git is authority).
+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.
 
 OUTPUT: List of generated files, module count, and validation results.

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

@@ -8,11 +8,12 @@ STEPS:
 1. Get changed files via `git diff --cached --name-status`. If nothing staged, use `git diff --name-status`. If no git changes at all, do full rescan comparing code against existing docs — this includes checking for modules that have source files but no L2 doc.
 2. Map changed files to modules by matching against MODULE_INDEX or MODULE_GROUPS in root.prizm. Group changes by module.
 3. Classify each change: A (added) -> new KEY_FILES entries. D (deleted) -> remove entries, update counts. M (modified) -> check dependency changes. R (renamed) -> update all path references.
-4. Update affected docs: L2 first (KEY_FILES, INTERFACES, DATA_FLOW, DEPENDENCIES, TRAPS, DECISIONS), then L1 (FILES count, KEY_FILES, DEPENDENCIES — L1 does NOT contain INTERFACES/DATA_FLOW/TRAPS/DECISIONS), then L0 (MODULE_INDEX or MODULE_GROUPS counts, CROSS_CUTTING) only if structural change. No date/time metadata fields — git tracks modification times. **Preserve** any `PROJECT_BRIEF:` line in root.prizm — it is managed by prizmkit-init, not by this skill.
+4. Update affected docs: L2 first (KEY_FILES, INTERFACES, DATA_FLOW, DEPENDENCIES, TRAPS, DECISIONS), then L1 (FILES count, KEY_FILES, DEPENDENCIES — L1 does NOT contain INTERFACES/DATA_FLOW/TRAPS/DECISIONS), then L0 (MODULE_INDEX or MODULE_GROUPS counts, CROSS_CUTTING) only if structural change. Do not write 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. **Preserve** any `PROJECT_BRIEF:` line in root.prizm — it is managed by prizmkit-init, not by this skill.
 5. Skip updates if: only internal implementation changed (no interface/dependency change), only comments/whitespace/formatting, only .prizm files changed. DO NOT skip test file changes or bug fixes — they may reveal TRAPS worth capturing in L2.
 6. If new directory qualifies as a module (per MODULE_DISCOVERY_CRITERIA) and matches no existing module: create L1 immediately, add to MODULE_INDEX. If the current diff includes Added or Modified source files in this module → also create L2 immediately with sections: MODULE, FILES, RESPONSIBILITY, INTERFACES, DATA_FLOW, KEY_FILES, DEPENDENCIES, RULES, TRAPS, DECISIONS. Otherwise defer L2.
 6a. **L2 gap check** (runs during full rescan mode only — when no git changes detected): For each existing module in MODULE_INDEX, check if L2 doc exists. If L2 is missing and the module has source files with meaningful logic (not trivial config/wrapper) → create L2 with sections: MODULE, FILES, RESPONSIBILITY, INTERFACES, DATA_FLOW, KEY_FILES, DEPENDENCIES, RULES, TRAPS, DECISIONS. This ensures Update fills documentation gaps left by previous sessions.
 7. Enforce size limits: L0 > 4KB -> consolidate. L1 > 4KB -> trim KEY_FILES descriptions, ensure RULES <= 3 entries. L2 > 5KB -> trim non-essential derived detail or split oversized cross-cutting detail.
+7a. Validate memory hygiene: no CHANGELOG/UPDATED fields, no workflow metadata, no L1 behavioral sections.
 8. Stage updated .prizm files via `git add .prizmkit/prizm-docs/`
 
 OUTPUT: List of updated/created/skipped docs with reasons.

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

@@ -5,12 +5,12 @@ Check format compliance and consistency of all .prizm docs.
 PRECONDITION: .prizmkit/prizm-docs/ exists.
 
 STEPS:
-1. FORMAT CHECK: Verify all .prizm files use KEY: value format. Flag any prose paragraphs, code blocks (```), markdown headers (##), emoji, ASCII art, or horizontal rules. Flag TRAPS entries missing severity prefix ([CRITICAL], [HIGH], or [LOW]). Flag CHANGELOG/UPDATED/date-time metadata fields as auxiliary noise. Note: [REVIEW] preceding severity (e.g., `[REVIEW][HIGH]`) is a valid temporary staleness marker, not a format violation.
+1. FORMAT CHECK: Verify all .prizm files use KEY: value format. Flag any prose paragraphs, code blocks (```), markdown headers (##), emoji, ASCII art, or horizontal rules. Flag TRAPS entries missing severity prefix ([CRITICAL], [HIGH], or [LOW]). Flag CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, and `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths as auxiliary noise. Note: [REVIEW] preceding severity (e.g., `[REVIEW][HIGH]`) is a valid temporary staleness marker, not a format violation.
 2. SIZE CHECK: Verify size limits: L0 <= 4KB, L1 <= 4KB, L2 <= 5KB. Report files exceeding limits with current size.
 3. POINTER CHECK: Verify all arrow (->) references resolve to existing .prizm files. Report broken pointers.
 4. STALENESS CHECK: Compare git modification time of each .prizm file against source directory. Flag docs where source was modified more recently.
 5. COMPLETENESS CHECK: Verify root.prizm has all required fields (PRIZM_VERSION, PROJECT, LANG, MODULE_INDEX or MODULE_GROUPS). Verify L1 docs have MODULE, FILES, RESPONSIBILITY, DEPENDENCIES (no INTERFACES/TRAPS/DECISIONS). Verify L2 docs have MODULE, FILES, KEY_FILES, DEPENDENCIES, INTERFACES, TRAPS.
-6. ANTI-PATTERN CHECK: Flag duplicate information across levels, implementation details in L0/L1, TODO items, session-specific context.
+6. ANTI-PATTERN CHECK: Flag duplicate information across levels, implementation details in L0/L1, TODO items, session-specific context, changelog/history sections, and workflow metadata.
 7. RULES HIERARCHY CHECK: Verify L1/L2 RULES do not contradict root.prizm RULES. L1/L2 may only supplement with module-specific exceptions.
 8. TRAPS STALENESS CHECK: For each L2 doc where TRAPS section has more than 8 entries, verify that TRAPS include staleness metadata (`STALE_IF:` or `REF:` fields). Flag TRAPS without any staleness metadata as `NEEDS_METADATA` — these are not auto-removed, but flagged for the next `/prizmkit-retrospective` to enrich with `STALE_IF:` globs or `REF:` hashes.
 

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

@@ -43,6 +43,8 @@ Synchronize `.prizmkit/prizm-docs/` structure with actual codebase changes from
 
 **Key outputs**: Synced L1 file counts, L2 INTERFACES/DATA_FLOW, DEPENDENCIES, and stale TRAPS cleanup.
 
+**Memory hygiene**: `.prizmkit/prizm-docs/` must not contain 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. Convert artifact-scoped wording into durable product/domain language before writing.
+
 ---
 
 ### Job 2: Knowledge Injection (conditional)

package/bundled/skills/prizmkit-retrospective/references/knowledge-injection-steps.md

@@ -40,6 +40,8 @@ When writing TRAPS:
 
 **QUALITY GATE**: Every item must answer: "If a new AI session reads only `.prizmkit/prizm-docs/` and this entry, does it gain actionable understanding?" If not, discard. Do not record trivially observable code patterns — the AI can read the code directly.
 
+**MEMORY HYGIENE GATE**: Before writing any `.prizmkit/prizm-docs/` entry, remove or translate workflow metadata. Never write 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. If source artifacts say "fixed in B-001" or "implemented in F-003", write only the durable product/domain fact.
+
 **2c.** Inject into the correct `.prizmkit/prizm-docs/` file:
 - Module-level TRAPS/RULES/DECISIONS → the affected **L2** `.prizm` file. If the target L2 does not exist, create it first using the L2 GENERATION TEMPLATE before injecting knowledge. (TRAPS/DECISIONS/RULES belong in L2, not L1.)
 - Project-level RULES/PATTERNS → `root.prizm` (respect the current format — MODULE_INDEX or MODULE_GROUPS — do not convert between them during injection)

package/bundled/skills/prizmkit-retrospective/references/structural-sync-steps.md

@@ -19,6 +19,8 @@ git diff HEAD --name-status
 - **L1**: Update FILES count, KEY_FILES (if major files added/removed), DEPENDENCIES (if module-level deps changed). **L1 does NOT contain INTERFACES, DATA_FLOW, TRAPS, or DECISIONS** — those belong in L2 only.
 - **L0 root.prizm**: Update MODULE_INDEX file counts only if counts changed. Update CROSS_CUTTING if cross-module concerns changed. Update only if structural change (module added/removed). **Preserve** any `PROJECT_BRIEF:` line — it is managed by prizmkit-init.
 
+**Memory hygiene**: During L0/L1/L2 updates, do not write 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. Update durable sections in place; git history is the change log.
+
 **1e.** If new directory qualifies as a module and matches no existing module:
 - A directory qualifies as a module if any of: contains source files forming a logical unit, contains entry/config/interface files, contains qualifying sub-modules, or is referenced by multiple modules as dependency.
 - Create L1 doc immediately, add to MODULE_INDEX.

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

@@ -45,7 +45,7 @@ If you believe the task is better suited for a different workflow, you MUST:
 - Codex → `AGENTS.md`
 - Claude Code → `CLAUDE.md`
 - CodeBuddy → `CODEBUDDY.md`
-- `both` → `CLAUDE.md` and `CODEBUDDY.md`; `all` → all three files.
+- `all` → all three files. Legacy manifests may contain `both`; treat it as read-only compatibility and update `CLAUDE.md` and `CODEBUDDY.md` only when encountered.
 - Only when the manifest is missing, fall back to installed PrizmKit-owned platform files such as `.codex/agents/*.toml`, `.claude/commands/prizm-kit.md`, or `.codebuddy/skills/prizm-kit/SKILL.md`. Do not treat a generic `.agents/` directory as Codex.
 
 **After planning is complete**, you MUST:

package/bundled/skills-windows/app-planner/references/architecture-decisions.md

@@ -29,7 +29,7 @@ After Phase 2 (Confirm constraints and tech assumptions), before Phase 3 (Captur
    - `codex` → append to `AGENTS.md`
    - `claude` → append to `CLAUDE.md`
    - `codebuddy` → append to `CODEBUDDY.md`
-   - `both` → append to `CLAUDE.md` and `CODEBUDDY.md`; `all` → append to all three files.
+   - `all` → append to all three files. Legacy manifests may contain `both`; treat it as read-only compatibility and append to `CLAUDE.md` and `CODEBUDDY.md` only when encountered.
    - Only when the manifest is missing, fall back to PrizmKit-owned install artifacts: `.codex/agents/*.toml`, `.claude/commands/prizm-kit.md`, `.codebuddy/skills/prizm-kit/SKILL.md`.
    - Do not treat a generic `.agents/` directory as Codex; it may contain unrelated third-party skills.
    - If no platform can be determined, skip (no project instruction file).

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

@@ -135,7 +135,7 @@ Before questions, check optional context files (never block if absent):
 - `.prizmkit/config.json` (existing stack preferences and detected tech stack)
 - `.prizmkit/plans/project-brief.md` (project context from app-planner, if available)
 - existing `.prizmkit/plans/feature-list.json` (required for incremental mode)
-- Platform instruction file: use the `platform` field in `.prizmkit/manifest.json` as source of truth when present (`codex` → `AGENTS.md`, `claude` → `CLAUDE.md`, `codebuddy` → `CODEBUDDY.md`; `both`/`all` → read every matching file)
+- Platform instruction file: use the `platform` field in `.prizmkit/manifest.json` as source of truth when present (`codex` → `AGENTS.md`, `claude` → `CLAUDE.md`, `codebuddy` → `CODEBUDDY.md`, `all` → read every matching file). Legacy manifests may contain `both`; treat it as read-only compatibility and read `CLAUDE.md` plus `CODEBUDDY.md` only when encountered.
 - If `.prizmkit/prizm-docs/root.prizm` is absent and the project has existing source code, scan the directory structure to understand the codebase layout:
   ```powershell
   Get-ChildItem -Path . -Directory -Recurse -Depth 2 -ErrorAction SilentlyContinue |

package/bundled/skills-windows/prizmkit-init/SKILL.md

@@ -184,7 +184,7 @@ Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structu
   - For each module entry in MODULE_INDEX/MODULE_GROUPS, include keyword tags extracted from the module's source files — scan for: exported symbols, imported packages, domain terms in file/directory names. Format: `- module-name [tag1, tag2, tag3]: ...`. Tags help AI match user intent to relevant modules.
   - Generate L1 docs for top-level modules at `.prizmkit/prizm-docs/<M>.prizm` and for sub-modules at `.prizmkit/prizm-docs/<M>/<S>.prizm`
   - Skip L2 (lazy generation) — L2 is generated on first file modification, saving tokens upfront
-  - Do not create auxiliary `changelog.prizm` or date/time metadata fields; git history is the source of change history
+  - Do not create auxiliary `changelog.prizm`, 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 history is the source of change history
 
 **Phase 6: Workspace Initialization**
 6a. Create `.prizmkit/` directory structure (if missing):

package/bundled/skills-windows/prizmkit-init/references/config-schema.md

@@ -19,11 +19,13 @@ Handles re-init without losing user edits:
 | Field | Type | Description |
 |-------|------|-------------|
 | `adoption_mode` | string | `"passive"` \| `"advisory"` \| `"active"` |
-| `platform` | string | `"codebuddy"` \| `"claude"` \| `"both"` |
+| `platform` | string | `"codebuddy"` \| `"claude"` \| `"codex"` \| `"all"` |
 | `tech_stack` | object | Detected or user-provided tech stack |
 | `tech_stack._auto_detected` | boolean | `true` if auto-detected, `false` if user-provided |
 | `detected_layers` | string[] | Development layers detected in the project. Written by prizmkit-init Phase 4.5. Used to determine available rule configuration options. Values: `frontend` / `backend` / `database` / `mobile`. Empty array when no layers detected or user skipped rules. Always updated on every init run based on fresh code detection — not gated by `_auto_detected` (see Merge Strategy above). |
 
+Legacy manifests may still contain `both` for read-only migration compatibility. New config writes must use `codebuddy`, `claude`, `codex`, or `all`.
+
 ## Examples
 
 Fullstack project:

package/bundled/templates/hooks/diff-prizm-docs.sh

@@ -107,7 +107,7 @@ done
 find .prizmkit/prizm-docs -name '*.prizm' 2>/dev/null | while IFS= read -r prizm_file; do
   _basename=$(basename "$prizm_file")
   case "$_basename" in
-    root.prizm|changelog.prizm|changelog-archive.prizm)
+    root.prizm)
       continue
       ;;
   esac

package/bundled/templates/hooks/prizm-pre-commit.sh

@@ -19,20 +19,69 @@ FILES=$(git diff --cached --name-only 2>/dev/null | grep '\.prizm$')
 [ -z "$FILES" ] && exit 0
 
 ERRORS=0
+TEMP_FILES=""
+
+cleanup() {
+    # shellcheck disable=SC2086
+    [ -z "$TEMP_FILES" ] || rm -f $TEMP_FILES
+}
+trap cleanup EXIT HUP INT TERM
+
 for FILE in $FILES; do
-    [ -f "$FILE" ] || continue
+    git cat-file -e ":$FILE" 2>/dev/null || continue
+    CHECK_FILE=$(mktemp "${TMPDIR:-/tmp}/prizm-doc.XXXXXX") || exit 1
+    TEMP_FILES="$TEMP_FILES $CHECK_FILE"
+    git show ":$FILE" > "$CHECK_FILE" 2>/dev/null || continue
 
-    if grep -qE '^#{1,6} ' "$FILE"; then
+    if grep -qE '^#{1,6} ' "$CHECK_FILE"; then
         echo "ERROR: $FILE contains markdown headers (##). Use KEY: value format." >&2
         ERRORS=$((ERRORS + 1))
     fi
 
-    if grep -q '^```' "$FILE"; then
+    if grep -q '^```' "$CHECK_FILE"; then
         echo "ERROR: $FILE contains code blocks. Use file_path:line_number reference." >&2
         ERRORS=$((ERRORS + 1))
     fi
 
-    SIZE=$(wc -c < "$FILE" | tr -d ' ')
+    BASE_NAME=$(basename "$FILE" | tr '[:upper:]' '[:lower:]')
+    case "$BASE_NAME" in
+        changelog.prizm|changelog-archive.prizm|*changelog*.prizm)
+            echo "ERROR: $FILE is auxiliary history. Use git history instead of changelog .prizm files." >&2
+            ERRORS=$((ERRORS + 1))
+            ;;
+    esac
+    if grep -qiE '^[[:space:]]*[-*]?[[:space:]]*(CHANGELOG|CREATED([ _-]?(AT|ON|DATE))?|UPDATED([ _-]?(AT|ON|DATE))?|MODIFIED([ _-]?(AT|ON|DATE))?|LAST[ _-]?(UPDATED|MODIFIED)([ _-]?(AT|ON|DATE))?|DATE|TIMESTAMP):' "$CHECK_FILE"; then
+        echo "ERROR: $FILE contains auxiliary history metadata. Use durable KEY: value sections only; git tracks history." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    if grep -qiE '(^|[^[:alnum:]_])([FBR]-[0-9]{3}|T-[0-9]{3})(-[A-Z])?([^[:alnum:]_]|$)' "$CHECK_FILE" \
+        || grep -qiE '^[[:space:]]*[-*]?[[:space:]]*((bug|feature|refactor|task)[ _-]?id|(session|run|pipeline|workflow)([ _-]?id)?)([[:space:]]*(:|=)|[[:space:]]+)' "$CHECK_FILE" \
+        || grep -qiE '^[[:space:]]*[-*]?[[:space:]]*(bug|feature|refactor|task|session|run|pipeline|workflow)([ _-](bug|feature|refactor|task|session|run|pipeline|workflow|id))+([[:space:]]*(:|=)|[[:space:]]+)' "$CHECK_FILE"; then
+        echo "ERROR: $FILE contains workflow metadata. Translate IDs, branch names, worktree paths, and pipeline artifacts into durable product/domain language." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    if sed 's#\\#/#g' "$CHECK_FILE" | grep -qE '(^|[^[:alnum:]_.-])\.prizmkit/(specs|dev-pipeline)($|/|[^[:alnum:]_.-])'; then
+        echo "ERROR: $FILE contains PrizmKit artifact paths. Translate specs/dev-pipeline references into durable product/domain language." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    if sed 's#\\#/#g' "$CHECK_FILE" | grep -qE '(^|[^[:alnum:]_./:-])(/Users/|/home/|/tmp/|/private/tmp/|/var/folders/|/workspace/|/workspaces/|/opt/|/srv/|/root/|/var/tmp/|/Volumes/|/mnt/[A-Za-z]/|[A-Za-z]:/)'; then
+        echo "ERROR: $FILE contains absolute worktree paths. Use repository-relative source paths only." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    if grep -qE '^[[:space:]]*[-*]?[[:space:]]*(BRANCH|BRANCH_NAME|CURRENT_BRANCH|SOURCE_BRANCH|BASE_BRANCH|HEAD_BRANCH|GIT_BRANCH|TARGET_BRANCH)[[:space:]_-]*(:|=|[[:space:]])' "$CHECK_FILE" \
+        || grep -qE '^[[:space:]]*[-*]?[[:space:]]*[A-Z][A-Z0-9_]*_BRANCH[[:space:]_-]*(:|=|[[:space:]])[[:space:]]*(main|master|develop|development|trunk|[A-Za-z0-9._-]+/[A-Za-z0-9._/-]+|(feature|fix|bugfix|hotfix|release|chore|refactor|task|dev)[/_-][A-Za-z0-9._/-]+)[[:space:]]*(#.*)?$' "$CHECK_FILE" \
+        || grep -qiE '^[[:space:]]*[-*]?[[:space:]]*(branch[ _-]*name|current[ _-]*branch|source[ _-]*branch|base[ _-]*branch|head[ _-]*branch|git[ _-]*branch|target[ _-]*branch)[[:space:]_-]*(:|=|[[:space:]])' "$CHECK_FILE" \
+        || grep -qiE '^[[:space:]]*[-*]?[[:space:]]*([[:alnum:]]+[ _-]+)+branch([[:space:]]*(:|=)|[[:space:]]+)[[:space:]]*(main|master|develop|development|trunk|[A-Za-z0-9._-]+/[A-Za-z0-9._/-]+|(feature|fix|bugfix|hotfix|release|chore|refactor|task|dev)[/_-][A-Za-z0-9._/-]+)[[:space:]]*(#.*)?$' "$CHECK_FILE" \
+        || grep -qiE '^[[:space:]]*[-*]?[[:space:]]*branch[[:space:]_-]*(:|=|[[:space:]])[[:space:]]*(main|master|develop|development|trunk|[A-Za-z0-9._-]+/[A-Za-z0-9._/-]+|(feature|fix|bugfix|hotfix|release|chore|refactor|task|dev)[/_-][A-Za-z0-9._/-]+)[[:space:]]*(#.*)?$' "$CHECK_FILE"; then
+        echo "ERROR: $FILE contains branch names. Describe durable product/domain context instead." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    SIZE=$(wc -c < "$CHECK_FILE" | tr -d ' ')
     case "$FILE" in
         *root.prizm) LIMIT=4096 ;;
         *)

package/bundled/templates/hooks/validate-prizm-docs.sh

@@ -4,6 +4,13 @@
 
 MODE="${1:---staged}"
 ERRORS=0
+TEMP_FILES=""
+
+cleanup() {
+    # shellcheck disable=SC2086
+    [ -z "$TEMP_FILES" ] || rm -f $TEMP_FILES
+}
+trap cleanup EXIT HUP INT TERM
 
 # Not a prizm project — exit silently
 [ -f ".prizmkit/prizm-docs/root.prizm" ] || exit 0
@@ -22,22 +29,70 @@ fi
 [ -z "$FILES" ] && exit 0
 
 for FILE in $FILES; do
-    [ -f "$FILE" ] || continue
+    CHECK_FILE="$FILE"
+    if [ "$MODE" = "--staged" ]; then
+        git cat-file -e ":$FILE" 2>/dev/null || continue
+        CHECK_FILE=$(mktemp "${TMPDIR:-/tmp}/prizm-doc.XXXXXX") || exit 1
+        TEMP_FILES="$TEMP_FILES $CHECK_FILE"
+        git show ":$FILE" > "$CHECK_FILE" 2>/dev/null || continue
+    else
+        [ -f "$FILE" ] || continue
+    fi
 
     # Check markdown headers
-    if grep -qE '^#{1,6} ' "$FILE"; then
+    if grep -qE '^#{1,6} ' "$CHECK_FILE"; then
         echo "ERROR: $FILE contains markdown headers (##). Use KEY: value format." >&2
         ERRORS=$((ERRORS + 1))
     fi
 
     # Check code blocks
-    if grep -q '^```' "$FILE"; then
+    if grep -q '^```' "$CHECK_FILE"; then
         echo "ERROR: $FILE contains code blocks. Use file_path:line_number reference." >&2
         ERRORS=$((ERRORS + 1))
     fi
 
+    # Check auxiliary history fields and files
+    BASE_NAME=$(basename "$FILE" | tr '[:upper:]' '[:lower:]')
+    case "$BASE_NAME" in
+        changelog.prizm|changelog-archive.prizm|*changelog*.prizm)
+            echo "ERROR: $FILE is auxiliary history. Use git history instead of changelog .prizm files." >&2
+            ERRORS=$((ERRORS + 1))
+            ;;
+    esac
+    if grep -qiE '^[[:space:]]*[-*]?[[:space:]]*(CHANGELOG|CREATED([ _-]?(AT|ON|DATE))?|UPDATED([ _-]?(AT|ON|DATE))?|MODIFIED([ _-]?(AT|ON|DATE))?|LAST[ _-]?(UPDATED|MODIFIED)([ _-]?(AT|ON|DATE))?|DATE|TIMESTAMP):' "$CHECK_FILE"; then
+        echo "ERROR: $FILE contains auxiliary history metadata. Use durable KEY: value sections only; git tracks history." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    # Check workflow metadata leakage
+    if grep -qiE '(^|[^[:alnum:]_])([FBR]-[0-9]{3}|T-[0-9]{3})(-[A-Z])?([^[:alnum:]_]|$)' "$CHECK_FILE" \
+        || grep -qiE '^[[:space:]]*[-*]?[[:space:]]*((bug|feature|refactor|task)[ _-]?id|(session|run|pipeline|workflow)([ _-]?id)?)([[:space:]]*(:|=)|[[:space:]]+)' "$CHECK_FILE" \
+        || grep -qiE '^[[:space:]]*[-*]?[[:space:]]*(bug|feature|refactor|task|session|run|pipeline|workflow)([ _-](bug|feature|refactor|task|session|run|pipeline|workflow|id))+([[:space:]]*(:|=)|[[:space:]]+)' "$CHECK_FILE"; then
+        echo "ERROR: $FILE contains workflow metadata. Translate IDs, branch names, worktree paths, and pipeline artifacts into durable product/domain language." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    if sed 's#\\#/#g' "$CHECK_FILE" | grep -qE '(^|[^[:alnum:]_.-])\.prizmkit/(specs|dev-pipeline)($|/|[^[:alnum:]_.-])'; then
+        echo "ERROR: $FILE contains PrizmKit artifact paths. Translate specs/dev-pipeline references into durable product/domain language." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    if sed 's#\\#/#g' "$CHECK_FILE" | grep -qE '(^|[^[:alnum:]_./:-])(/Users/|/home/|/tmp/|/private/tmp/|/var/folders/|/workspace/|/workspaces/|/opt/|/srv/|/root/|/var/tmp/|/Volumes/|/mnt/[A-Za-z]/|[A-Za-z]:/)'; then
+        echo "ERROR: $FILE contains absolute worktree paths. Use repository-relative source paths only." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
+    if grep -qE '^[[:space:]]*[-*]?[[:space:]]*(BRANCH|BRANCH_NAME|CURRENT_BRANCH|SOURCE_BRANCH|BASE_BRANCH|HEAD_BRANCH|GIT_BRANCH|TARGET_BRANCH)[[:space:]_-]*(:|=|[[:space:]])' "$CHECK_FILE" \
+        || grep -qE '^[[:space:]]*[-*]?[[:space:]]*[A-Z][A-Z0-9_]*_BRANCH[[:space:]_-]*(:|=|[[:space:]])[[:space:]]*(main|master|develop|development|trunk|[A-Za-z0-9._-]+/[A-Za-z0-9._/-]+|(feature|fix|bugfix|hotfix|release|chore|refactor|task|dev)[/_-][A-Za-z0-9._/-]+)[[:space:]]*(#.*)?$' "$CHECK_FILE" \
+        || grep -qiE '^[[:space:]]*[-*]?[[:space:]]*(branch[ _-]*name|current[ _-]*branch|source[ _-]*branch|base[ _-]*branch|head[ _-]*branch|git[ _-]*branch|target[ _-]*branch)[[:space:]_-]*(:|=|[[:space:]])' "$CHECK_FILE" \
+        || grep -qiE '^[[:space:]]*[-*]?[[:space:]]*([[:alnum:]]+[ _-]+)+branch([[:space:]]*(:|=)|[[:space:]]+)[[:space:]]*(main|master|develop|development|trunk|[A-Za-z0-9._-]+/[A-Za-z0-9._/-]+|(feature|fix|bugfix|hotfix|release|chore|refactor|task|dev)[/_-][A-Za-z0-9._/-]+)[[:space:]]*(#.*)?$' "$CHECK_FILE" \
+        || grep -qiE '^[[:space:]]*[-*]?[[:space:]]*branch[[:space:]_-]*(:|=|[[:space:]])[[:space:]]*(main|master|develop|development|trunk|[A-Za-z0-9._-]+/[A-Za-z0-9._/-]+|(feature|fix|bugfix|hotfix|release|chore|refactor|task|dev)[/_-][A-Za-z0-9._/-]+)[[:space:]]*(#.*)?$' "$CHECK_FILE"; then
+        echo "ERROR: $FILE contains branch names. Describe durable product/domain context instead." >&2
+        ERRORS=$((ERRORS + 1))
+    fi
+
     # Size limits — determine level by path depth
-    SIZE=$(wc -c < "$FILE" | tr -d ' ')
+    SIZE=$(wc -c < "$CHECK_FILE" | tr -d ' ')
     case "$FILE" in
         *root.prizm)
             LIMIT=4096; LEVEL="L0"
@@ -51,7 +106,7 @@ for FILE in $FILES; do
                 HINT="Move implementation details to L2."
             else
                 LIMIT=5120; LEVEL="L2"
-                HINT="Archive CHANGELOG entries older than 90 days."
+                HINT="Remove stale or trivially derivable entries."
             fi
             ;;
     esac
@@ -64,11 +119,11 @@ for FILE in $FILES; do
     # Required fields in root.prizm
     case "$FILE" in
         *root.prizm)
-            if ! grep -q 'PRIZM_VERSION:' "$FILE"; then
+            if ! grep -q 'PRIZM_VERSION:' "$CHECK_FILE"; then
                 echo "ERROR: $FILE missing required field PRIZM_VERSION:" >&2
                 ERRORS=$((ERRORS + 1))
             fi
-            if ! grep -q 'MODULE_INDEX:' "$FILE"; then
+            if ! grep -q 'MODULE_INDEX:' "$CHECK_FILE"; then
                 echo "ERROR: $FILE missing required field MODULE_INDEX:" >&2
                 ERRORS=$((ERRORS + 1))
             fi

package/bundled/templates/project-memory-template.md

@@ -19,7 +19,8 @@ This project uses PrizmKit with the Prizm documentation system for AI-optimized
 - All `.prizm` files use KEY: value format, not prose
 - Size limits: L0 = 4KB, L1 = 4KB, L2 = 5KB
 - Arrow notation (->) indicates load pointers to other .prizm docs
-- DECISIONS and CHANGELOG are append-only (never delete entries)
+- Memory files must not contain 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
+- Update durable sections in place; git history is the change log
 - No date/time fields — git is the authoritative source for temporal info
 
 ### Creating New L2 Docs

package/package.json

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

package/src/config.js

@@ -53,7 +53,7 @@ import {
   confirmTeamMode,
   confirmPipeline,
 } from './prompts.js';
-import { expandPlatforms, platformLabel, projectMemoryFile } from './platforms.js';
+import { expandPlatforms, isKnownPlatform, platformLabel, projectMemoryFile } from './platforms.js';
 import { normalizeRuntime, runtimeLabel } from './runtimes.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -362,6 +362,10 @@ export async function runConfig(directory, options = {}) {
     aiCli: userConfig.ai_cli || oldManifest.options?.aiCli || '',
   };
 
+  if (options.platform !== undefined && !isKnownPlatform(options.platform)) {
+    throw new Error(`Unknown platform "${options.platform}". Expected codebuddy, claude, codex, or all.`);
+  }
+
   // Display current config
   console.log(chalk.bold('  当前配置:'));
   console.log(`    平台:     ${chalk.cyan(platformLabel(currentConfig.platform))}`);
@@ -431,6 +435,10 @@ export async function runConfig(directory, options = {}) {
     }
   }
 
+  if (!isKnownPlatform(newConfig.platform)) {
+    throw new Error(`Unknown platform "${newConfig.platform}". Expected codebuddy, claude, codex, or all.`);
+  }
+
   // ── Phase 3: COMPUTE DIFF ────────────────────────────────────────────────
 
   const changes = [];

package/src/detect-platform.js

@@ -44,8 +44,6 @@ export function detectPlatform() {
   let suggested = 'codebuddy';
   if (cbc && claude && codex) {
     suggested = 'all';
-  } else if ((cbc) && (claude)) {
-    suggested = 'both';
   } else if (codex && !cbc && !claude) {
     suggested = 'codex';
   } else if ((claude) && !cbc) {

package/src/external-skills.js

@@ -21,7 +21,7 @@ import { expandPlatforms } from './platforms.js';
  *   skill.repo       {string}  - GitHub short ref (e.g. "pbakaus/impeccable") or full URL
  *   skill.name       {string}  - Skill name (used for display / single-skill mode)
  *   skill.installAll {boolean} - If true, install all skills from the repo
- * @param {string} platform     - 'claude' | 'codebuddy' | 'codex' | 'both' | 'all'
+ * @param {string} platform     - 'claude' | 'codebuddy' | 'codex' | 'all' ('both' supported only for legacy manifests)
  * @param {string} projectRoot  - Target project root
  * @param {boolean} dryRun
  */
@@ -105,7 +105,7 @@ export async function installExternalSkill(skill, platform, projectRoot, dryRun)
  * Call this once after all external skills have been installed.
  *
  * @param {string} projectRoot
- * @param {string} platform - 'claude' | 'codebuddy' | 'codex' | 'both' | 'all'
+ * @param {string} platform - 'claude' | 'codebuddy' | 'codex' | 'all' ('both' supported only for legacy manifests)
  */
 export async function cleanExternalSkillArtifacts(projectRoot, platform) {
   const keepDirs = new Set(

package/src/index.js

@@ -106,10 +106,6 @@ export async function runScaffold(directory, options) {
           name: `Codex (AGENTS.md + .agents/skills + .codex/)${detected.codex ? chalk.green(' ← 已检测到 codex') : ''}`,
           value: 'codex',
         },
-        {
-          name: '同时安装 CodeBuddy + Claude Code',
-          value: 'both',
-        },
         {
           name: '同时安装全部平台',
           value: 'all',

package/src/manifest.js

@@ -47,7 +47,7 @@ export async function writeManifest(projectRoot, data) {
  * Build a manifest object from installation config.
  * @param {Object} params
  * @param {string} params.version - PrizmKit version
- * @param {string} params.platform - 'codebuddy' | 'claude' | 'codex' | 'both' | 'all'
+ * @param {string} params.platform - 'codebuddy' | 'claude' | 'codex' | 'all' ('both' supported only for legacy manifests)
  * @param {string} [params.runtime] - 'unix' | 'windows'
  * @param {string} params.suite - skill suite name
  * @param {string[]} params.skills - resolved skill name list

package/src/platforms.js

@@ -1,11 +1,13 @@
 export const PLATFORM_IDS = ['codebuddy', 'claude', 'codex'];
 export const PLATFORM_GROUPS = {
-  both: ['codebuddy', 'claude'],
   all: PLATFORM_IDS,
 };
+const LEGACY_PLATFORM_GROUPS = {
+  both: ['codebuddy', 'claude'],
+};
 
 export function expandPlatforms(platform) {
-  return PLATFORM_GROUPS[platform] || [platform];
+  return PLATFORM_GROUPS[platform] || LEGACY_PLATFORM_GROUPS[platform] || [platform];
 }
 
 export function isKnownPlatform(platform) {
@@ -13,8 +15,8 @@ export function isKnownPlatform(platform) {
 }
 
 export function platformLabel(platform) {
-  if (platform === 'both') return 'CodeBuddy + Claude Code';
-  if (platform === 'all') return 'CodeBuddy + Claude Code + Codex';
+  if (platform === 'both') return 'legacy codebuddy/claude group';
+  if (platform === 'all') return 'All platforms (CodeBuddy, Claude Code, Codex)';
   if (platform === 'codebuddy') return 'CodeBuddy';
   if (platform === 'claude') return 'Claude Code';
   if (platform === 'codex') return 'Codex';

package/src/prompts.js

@@ -8,6 +8,16 @@ import chalk from 'chalk';
 import { platformLabel } from './platforms.js';
 import { normalizeRuntime } from './runtimes.js';
 
+let selectPlatformPrompt = select;
+
+export function __setSelectPlatformPromptForTests(promptFn) {
+  selectPlatformPrompt = promptFn;
+}
+
+export function __resetSelectPlatformPromptForTests() {
+  selectPlatformPrompt = select;
+}
+
 export async function selectRuntime(currentRuntime) {
   return select({
     message: '选择运行系统 (决定安装 macOS/Linux 或 Windows 版本的流水线与编排技能):',
@@ -20,13 +30,23 @@ export async function selectRuntime(currentRuntime) {
 }
 
 /**
- * Select target platform (codebuddy, claude, codex, both, or all).
+ * Select target platform (codebuddy, claude, codex, or all).
  * @param {string} currentPlatform - current platform value
  * @param {Object} detected - detected environment info (e.g., { cbc: true, claude: false })
  * @returns {Promise<string>}
  */
 export async function selectPlatform(currentPlatform, detected = {}) {
-  const platform = await select({
+  const selectablePlatforms = ['codebuddy', 'claude', 'codex', 'all'];
+  const detectedDefault = selectablePlatforms.includes(detected.suggested)
+    ? detected.suggested
+    : 'claude';
+  let defaultPlatform = detectedDefault;
+  if (currentPlatform === 'both') {
+    defaultPlatform = 'all';
+  } else if (selectablePlatforms.includes(currentPlatform)) {
+    defaultPlatform = currentPlatform;
+  }
+  const platform = await selectPlatformPrompt({
     message: '选择目标平台 (决定安装的目录结构):',
     choices: [
       {
@@ -41,16 +61,12 @@ export async function selectPlatform(currentPlatform, detected = {}) {
         name: `Codex (AGENTS.md + .agents/skills + .codex/)${detected.codex ? chalk.green(' ← 已检测到 codex') : ''}`,
         value: 'codex',
       },
-      {
-        name: '同时安装 CodeBuddy + Claude Code',
-        value: 'both',
-      },
       {
         name: `同时安装全部平台 (${platformLabel('all')})`,
         value: 'all',
       },
     ],
-    default: currentPlatform || detected.suggested || 'claude',
+    default: defaultPlatform,
   });
   return platform;
 }

package/src/scaffold.js

@@ -574,6 +574,135 @@ max_depth = 1
 /**
  * 安装 git pre-commit hook（prizm 格式校验）
  */
+const PRIZMKIT_HOOK_MARKER_START = '# PRIZMKIT_PRE_COMMIT_HOOK_START';
+const PRIZMKIT_HOOK_MARKER_END = '# PRIZMKIT_PRE_COMMIT_HOOK_END';
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function ensureTrailingNewline(value) {
+  return value.endsWith('\n') ? value : `${value}\n`;
+}
+
+function buildStandalonePrizmHook(templateContent) {
+  const content = templateContent.trimEnd();
+  const firstNewline = content.indexOf('\n');
+
+  if (content.startsWith('#!') && firstNewline !== -1) {
+    return [
+      content.slice(0, firstNewline),
+      PRIZMKIT_HOOK_MARKER_START,
+      content.slice(firstNewline + 1),
+      PRIZMKIT_HOOK_MARKER_END,
+      '',
+    ].join('\n');
+  }
+
+  return [
+    PRIZMKIT_HOOK_MARKER_START,
+    content,
+    PRIZMKIT_HOOK_MARKER_END,
+    '',
+  ].join('\n');
+}
+
+function buildAppendedPrizmHook(templateContent) {
+  return [
+    PRIZMKIT_HOOK_MARKER_START,
+    templateContent.trimEnd(),
+    PRIZMKIT_HOOK_MARKER_END,
+    '',
+  ].join('\n');
+}
+
+function insertPrizmHookIntoUserHook(userHookContent, prizmHookBlock) {
+  const content = userHookContent.trimEnd();
+  const terminalSuccessExitPattern = /(^|\n)([ \t]*exit[ \t]+0[ \t]*(?:#.*)?)[ \t]*$/;
+  const match = content.match(terminalSuccessExitPattern);
+
+  if (!match) {
+    return `${content}\n\n${prizmHookBlock}`;
+  }
+
+  const exitLineStart = match.index + match[1].length;
+  const beforeExit = content.slice(0, exitLineStart).trimEnd();
+  const exitLine = match[2];
+
+  return [
+    beforeExit,
+    prizmHookBlock.trimEnd(),
+    exitLine,
+    '',
+  ].filter((part, index) => index > 0 || part.length > 0).join('\n\n');
+}
+
+function findLegacyPrizmHookEnd(content, markerIndex) {
+  const afterMarker = content.slice(markerIndex);
+  const exitMatch = afterMarker.match(/(^|\n)[ \t]*exit[ \t]+0[ \t]*(\r?\n|$)/);
+  if (exitMatch) {
+    return markerIndex + exitMatch.index + exitMatch[0].length;
+  }
+
+  const markerLineEnd = content.indexOf('\n', markerIndex);
+  const searchStart = markerLineEnd === -1 ? content.length : markerLineEnd + 1;
+  const blankLineIndex = content.slice(searchStart).search(/\r?\n[ \t]*(\r?\n|$)/);
+  if (blankLineIndex !== -1) {
+    return searchStart + blankLineIndex + 1;
+  }
+
+  return content.length;
+}
+
+function stripLegacyPrizmHookBlocks(existing) {
+  const legacyMarker = '# prizm-pre-commit.sh';
+  let cleaned = '';
+  let cursor = 0;
+
+  while (cursor < existing.length) {
+    const markerIndex = existing.indexOf(legacyMarker, cursor);
+    if (markerIndex === -1) {
+      cleaned += existing.slice(cursor);
+      break;
+    }
+
+    const markerLineStart = existing.lastIndexOf('\n', markerIndex) + 1;
+    let blockStart = markerLineStart;
+    if (markerLineStart > 0) {
+      const previousLineEnd = markerLineStart - 1;
+      const previousLineStart = existing.lastIndexOf('\n', previousLineEnd - 1) + 1;
+      const previousLine = existing.slice(previousLineStart, previousLineEnd).replace(/\r$/, '');
+      if (previousLine.startsWith('#!')) {
+        blockStart = previousLineStart;
+      }
+    }
+
+    cleaned += existing.slice(cursor, blockStart);
+    cursor = findLegacyPrizmHookEnd(existing, markerIndex);
+  }
+
+  return cleaned;
+}
+
+function stripManagedPrizmHook(existing) {
+  const markedBlockPattern = new RegExp(
+    `(^|\\n)${escapeRegExp(PRIZMKIT_HOOK_MARKER_START)}[\\s\\S]*?${escapeRegExp(PRIZMKIT_HOOK_MARKER_END)}\\n?`,
+    'g',
+  );
+
+  let cleaned = existing.replace(markedBlockPattern, '\n');
+  cleaned = stripLegacyPrizmHookBlocks(cleaned);
+
+  return cleaned.replace(/\n{3,}/g, '\n\n').trimEnd();
+}
+
+function hasUserHookContent(content) {
+  return content
+    .replace(/^#!.*(\r?\n|$)/, '')
+    .trim()
+    .length > 0;
+}
+
 export async function installGitHook(projectRoot, dryRun, runtime = 'unix') {
   const gitDir = path.join(projectRoot, '.git');
   const normalizedRuntime = normalizeRuntime(runtime);
@@ -591,21 +720,17 @@ export async function installGitHook(projectRoot, dryRun, runtime = 'unix') {
   const templatePath = path.join(getTemplatesDir(), 'hooks', 'prizm-pre-commit.sh');
   const hooksDir = path.join(gitDir, 'hooks');
   const preCommitPath = path.join(hooksDir, 'pre-commit');
+  const hookContent = fs.readFileSync(templatePath, 'utf8');
 
   if (normalizedRuntime === RUNTIME_WINDOWS) {
-    if (fs.existsSync(preCommitPath) && fs.existsSync(templatePath)) {
+    if (fs.existsSync(preCommitPath)) {
       const existing = fs.readFileSync(preCommitPath, 'utf8');
-      const shellTemplate = fs.readFileSync(templatePath, 'utf8');
-      if (existing === shellTemplate) {
+      const cleaned = stripManagedPrizmHook(existing);
+      if (!hasUserHookContent(cleaned)) {
         await fs.remove(preCommitPath);
         console.log(chalk.gray('      • .git/hooks/pre-commit shell hook removed for Windows runtime'));
-      } else if (existing.includes(shellTemplate)) {
-        const cleaned = existing.replace(shellTemplate, '').replace(/\n{3,}/g, '\n\n').trimEnd();
-        if (cleaned) {
-          fs.writeFileSync(preCommitPath, `${cleaned}\n`);
-        } else {
-          await fs.remove(preCommitPath);
-        }
+      } else if (cleaned !== existing.trimEnd()) {
+        fs.writeFileSync(preCommitPath, ensureTrailingNewline(cleaned));
         console.log(chalk.gray('      • PrizmKit shell hook block removed for Windows runtime'));
       }
     }
@@ -617,11 +742,15 @@ export async function installGitHook(projectRoot, dryRun, runtime = 'unix') {
 
   if (fs.existsSync(preCommitPath)) {
     const existing = fs.readFileSync(preCommitPath, 'utf8');
-    if (existing.includes('PrizmKit')) return;
-    const hookContent = fs.readFileSync(templatePath, 'utf8');
-    fs.writeFileSync(preCommitPath, existing + '\n\n' + hookContent);
+    const cleaned = stripManagedPrizmHook(existing);
+    if (hasUserHookContent(cleaned)) {
+      fs.writeFileSync(preCommitPath, insertPrizmHookIntoUserHook(cleaned, buildAppendedPrizmHook(hookContent)));
+    } else {
+      fs.writeFileSync(preCommitPath, buildStandalonePrizmHook(hookContent));
+    }
+    fs.chmodSync(preCommitPath, 0o755);
   } else {
-    await fs.copy(templatePath, preCommitPath);
+    fs.writeFileSync(preCommitPath, buildStandalonePrizmHook(hookContent));
     fs.chmodSync(preCommitPath, 0o755);
   }
 
@@ -1153,7 +1282,7 @@ export const EXTRAS_REGISTRY = {
 /**
  * 执行纯净安装
  * @param {Object} config
- * @param {string} config.platform - 'codebuddy' | 'claude' | 'codex' | 'both' | 'all'
+ * @param {string} config.platform - 'codebuddy' | 'claude' | 'codex' | 'all'
  * @param {string} [config.runtime] - 'unix' | 'windows'
  * @param {string} config.skills - 'core' | 'minimal' | 'recommended:<type>'
  * @param {boolean} config.team - 是否启用团队模式
@@ -1171,7 +1300,7 @@ export async function scaffold(config) {
   const { platform, skills, team, pipeline, rules, aiCli, externalSkills, playwrightCli, openCli, openCliAutoDownload, projectRoot, dryRun } = config;
   const runtime = normalizeRuntime(config.runtime);
   if (!isKnownPlatform(platform)) {
-    throw new Error(`Unknown platform "${platform}". Expected codebuddy, claude, codex, both, or all.`);
+    throw new Error(`Unknown platform "${platform}". Expected codebuddy, claude, codex, or all.`);
   }
   const platforms = expandPlatforms(platform);
 

package/src/upgrade.js

@@ -229,7 +229,7 @@ export async function runUpgrade(directory, options = {}) {
   // (e.g. legacy installs before manifest tracked platform).
   let platform;
   if (oldManifest?.platform) {
-    platform = oldManifest.platform;
+    platform = oldManifest.platform === 'both' ? 'all' : oldManifest.platform;
   } else {
     // Fallback: detect from filesystem for legacy manifests without platform field
     const hasPlatformFiles = async (dir) => {
@@ -247,11 +247,14 @@ export async function runUpgrade(directory, options = {}) {
     const hasCodex = await hasPlatformFiles(path.join(projectRoot, '.agents', 'skills'))
                      || await hasPlatformFiles(path.join(projectRoot, '.codex', 'agents'));
 
-    if (hasClaude && hasCodeBuddy && hasCodex) platform = 'all';
-    else if (hasClaude && hasCodeBuddy) platform = 'both';
-    else if (hasCodex) platform = 'codex';
-    else if (hasCodeBuddy) platform = 'codebuddy';
-    else if (hasClaude) platform = 'claude';
+    const detectedPlatforms = [
+      hasCodeBuddy && 'codebuddy',
+      hasClaude && 'claude',
+      hasCodex && 'codex',
+    ].filter(Boolean);
+
+    if (detectedPlatforms.length > 1) platform = 'all';
+    else if (detectedPlatforms.length === 1) platform = detectedPlatforms[0];
     else platform = 'claude'; // ultimate fallback
   }