prizmkit 1.1.8 → 1.1.10

package/bundled/skills/prizmkit-prizm-docs/assets/{PRIZM-SPEC.md → prizm-docs-format.md}

@@ -10,22 +10,18 @@ LICENSE: MIT
 
 ## Table of Contents
 
-1. Overview (L32–49)
-2. Architecture (L50–127)
-3. Document Format Specification (L128–308)
-4. Format Conventions (L309–321)
-5. Path Mapping Rules (L322–351)
-6. Progressive Loading Protocol (L352–411)
-7. Auto-Update Protocol (L412–491)
-8. Anti-Patterns (L492–511)
-9. Initialization Procedure (L512–646)
-10. Skill Definition (L647–768)
-11. Hook Configuration (L769–823)
-12. Language-Specific Initialization Hints (L824–857)
-13. Minimal Viable Prizm (L858–875)
-14. Version History (L876–920)
-15. Conflict Resolution (L921–978)
-16. Version Migration (L979–1087)
+1. Overview
+2. Architecture
+3. Document Format Specification
+4. Format Conventions
+5. Path Mapping Rules
+6. Progressive Loading Protocol
+7. Auto-Update Protocol
+8. Anti-Patterns
+9. Initialization Procedure
+10. Skill Definition
+11. Hook Configuration
+12. Language-Specific Initialization Hints
 
 ---
 
@@ -448,68 +444,9 @@ GOAL: Keep prizm docs synchronized with source code
 
 ## 7.2 Update Decision Logic
 
-ALGORITHM: prizm_update
-
-1. GET_CHANGES:
-   Run: git diff --cached --name-status
-   If nothing staged: Run: git diff --name-status
-   Result: List of (status, file_path) pairs
-
-2. MAP_TO_MODULES:
-   FOR EACH changed file:
-     Find its module by matching against MODULE_INDEX in root.prizm
-     Group changes by module
-
-3. CLASSIFY_CHANGES:
-   FOR EACH changed file:
-     A (added): May need new entries in KEY_FILES, INTERFACES
-     D (deleted): Remove from KEY_FILES, update FILES count
-     M (modified): Check if public interfaces or dependencies changed
-     R (renamed): Update all path references in affected docs
-
-4. UPDATE_DOCS:
-   FOR EACH affected module:
-     a. IF L2 doc exists for this module:
-        UPDATE: KEY_FILES (add/remove/modify)
-        UPDATE: INTERFACES (if signatures changed)
-        UPDATE: DATA_FLOW (if data flow changed)
-        UPDATE: DEPENDENCIES (if imports changed)
-        UPDATE: TRAPS (if new pitfalls discovered)
-        APPEND: CHANGELOG entry
-     b. IF L1 doc exists:
-        UPDATE: FILES count
-        UPDATE: KEY_FILES (if major files added/removed)
-        UPDATE: DEPENDENCIES (if module-level deps changed)
-        (NOTE: L1 does NOT contain INTERFACES/DATA_FLOW/TRAPS/DECISIONS — those are in L2 only)
-     c. UPDATE root.prizm (L0):
-        UPDATE: MODULE_INDEX file counts
-        UPDATE: CROSS_CUTTING (if cross-module concerns changed)
-        ONLY IF: module added, removed, or project-wide structural change
-
-5. SKIP_CONDITIONS:
-   SKIP if: Only internal implementation changed (no interface/dependency change)
-   SKIP if: Only comments, whitespace, or formatting changed
-   SKIP if: Only .prizm files changed (avoid circular updates)
-
-   DO NOT SKIP (may reveal TRAPS worth capturing in L2):
-   - Test file changes that expose edge cases, boundary conditions, or regression patterns
-   - Bug fixes that reveal non-obvious failure modes (the root cause is itself a TRAP)
-
-6. CREATE_NEW_DOCS:
-   IF new directory qualifies as a module (see MODULE_DISCOVERY_CRITERIA, Section 9.1 Step 2) AND matches no existing module:
-     CREATE: L1 doc immediately
-     ADD: entry to MODULE_INDEX in root.prizm
-     DEFER: L2 creation to first modification or deep read
-
-7. SIZE_ENFORCEMENT:
-   AFTER each update, check file sizes:
-   L0 > 4KB: Consolidate MODULE_INDEX entries, remove lowest-value RULES
-   L1 > 4KB: Move detailed KEY_FILES descriptions to L2, trim RULES to top 3
-   L2 > 5KB: Split into sub-module docs or archive old CHANGELOG entries
-
-8. STAGE_DOCS:
-   Run: git add .prizm-docs/
-   (Prizm docs are committed alongside source code changes)
+SUMMARY: Get changed files → map to modules → classify (A/D/M/R) → update docs bottom-up (L2→L1→L0) → skip if no structural impact → enforce size limits → stage.
+
+DETAILED_STEPS: → ${SKILL_DIR}/references/op-update.md
 
 ## 7.3 Changelog Update
 
@@ -546,114 +483,29 @@ NEVER: TRAPS entries without severity prefix ([CRITICAL], [HIGH], or [LOW])
 OPERATION: Init (invoked via prizmkit-prizm-docs skill)
 PRECONDITION: No .prizm-docs/ directory exists (or user confirms overwrite)
 
-ALGORITHM: prizm_init
-
 INPUT: Project root directory
 OUTPUT: .prizm-docs/ with root.prizm, changelog.prizm, and L1 docs for discovered modules
 
-STEPS:
-
-1. DETECT_PROJECT:
-   SCAN project root for build system files:
-   - go.mod -> Go
-   - package.json -> JavaScript/TypeScript
-   - requirements.txt, pyproject.toml, setup.py -> Python
-   - Cargo.toml -> Rust
-   - pom.xml, build.gradle -> Java
-   - *.csproj, *.sln -> C#
-   IDENTIFY: primary language, framework, build command, test command
-   FIND: entry points by convention:
-   - Go: main.go, cmd/*/main.go
-   - JS/TS: package.json "main"/"bin", index.ts, index.js
-   - Python: __main__.py, manage.py, app.py
-   - Rust: main.rs, lib.rs
-   - Java: *Application.java, Main.java
-
-2. DISCOVER_MODULES:
-   SCAN source directories, preserving the tree structure (DO NOT FLATTEN):
-
-   MODULE_DISCOVERY_CRITERIA — a directory qualifies as a module if ANY of the following is true:
-   - Contains source files that collectively form a logical unit (shared responsibility)
-   - Contains entry points, configuration files, or interface definitions
-   - Contains sub-directories that themselves qualify as modules
-   - Is referenced by multiple other modules as a dependency
-
-   A directory does NOT qualify if ALL of the following are true:
-   - Contains only generated/derived files (build output, compiled assets)
-   - Contains only vendored/third-party code
-   - Is in the EXCLUDE list
-
-   a. IDENTIFY TOP-LEVEL modules: directories directly under project root (or directly under src/ for src-based layouts) that qualify per MODULE_DISCOVERY_CRITERIA.
-      RESULT: top_modules = [src, internal, app, lib, ...]
-
-   b. IDENTIFY SUB-MODULES: for each top-level module M, find directories INSIDE M that qualify per MODULE_DISCOVERY_CRITERIA.
-      RESULT: sub_modules[M] = [scripts, lib, templates, ...]  (relative names, not full paths)
-
-   c. HIERARCHY RULE: if directory X lives inside top-level module M, X is a sub-module of M — NOT a separate top-level module.
-      WRONG: src/routes/ treated as top-level module -> .prizm-docs/routes.prizm
-      CORRECT: src/routes/ is a sub-module of src -> .prizm-docs/src/routes.prizm
-
-   d. MODULE_INDEX in root.prizm lists modules at the depth needed for efficient navigation.
-      Multi-level entries are allowed (no hard depth limit). If navigating from L0 to a commonly-used module would require 3+ hops via SUBDIRS pointers, add an intermediate entry to MODULE_INDEX.
-      The 4KB L0 size limit naturally constrains how many entries can be listed.
-
-   - EXCLUDE: .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .prizmkit/, .prizm-docs/, dev-pipeline/
-   IF total module count > 30: ASK user for include/exclude patterns
-
-3. CREATE_DIRECTORY_STRUCTURE:
-   Create .prizm-docs/ directory
-   For each top-level module M that has sub-modules: create .prizm-docs/<M>/ directory
-   RULE: .prizm-docs/ directory tree must mirror the source directory tree exactly
-   EXAMPLE:
-     source: src/routes/     -> prizm: .prizm-docs/src/routes.prizm
-     source: src/models/     -> prizm: .prizm-docs/src/models.prizm
-     source: src/            -> prizm: .prizm-docs/src.prizm
-   NEVER create .prizm-docs/routes.prizm for a directory that lives at src/routes/
-
-4. GENERATE_ROOT (L0):
-   Fill: PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY from step 1
-   Build: MODULE_INDEX (or MODULE_GROUPS if 15+ modules — see Section 3.1) — list modules at the depth needed for efficient navigation, with arrow pointers
-   Extract: RULES from existing README, .editorconfig, linter configs
-   Extract: PATTERNS from common code patterns observed in step 2
-   Extract: CROSS_CUTTING — identify patterns/constraints that span 2+ modules
-   Set: PRIZM_VERSION: 4
-
-5. GENERATE_L1_DOCS (structural index only):
-   FOR EACH module in MODULE_INDEX:
-     SCAN the module directory:
-     - Count all source files (direct files only, not recursive)
-     - Trace import/require/use statements for DEPENDENCIES
-     - List sub-modules in SUBDIRS with pointers
-     - Identify 5-10 most important files for KEY_FILES
-     - Identify 1-3 most critical module-specific rules for RULES summary
-     DO NOT include INTERFACES, DATA_FLOW, TRAPS, or DECISIONS (those are L2, generated lazily)
-     WRITE: .prizm-docs/<mirrored-path>.prizm
-
-   FOR EACH sub-module S of a parent module M:
-     SCAN M/S directory with same structural-index approach as above
-     WRITE: .prizm-docs/<M>/<S>.prizm (L1 structural index at the mirrored sub-path)
-
-6. SKIP_L2:
-   DO NOT generate L2 docs during initialization.
-   RATIONALE: L2 contains behavioral detail (INTERFACES, DATA_FLOW, TRAPS, DECISIONS) that requires deep code understanding. Generating shallow L2 docs during init would produce misleading content. L2 docs are generated lazily when AI first modifies files in a module or performs a deep read (ON_DEEP_READ trigger).
-
-7. CREATE_CHANGELOG:
-   Write .prizm-docs/changelog.prizm with single entry:
-   - root | add: initialized prizm documentation framework
-
-8. VALIDATE:
-   CHECK: All generated files are within size limits (L0 <= 4KB, L1 <= 4KB)
-   CHECK: Every MODULE_INDEX pointer resolves to an existing .prizm file
-   CHECK: No circular dependencies in DEPENDENCIES sections
-   CHECK: KEY: value format compliance (no prose, no code blocks, no markdown headers)
-   CHECK: No anti-patterns per Section 8
-   CHECK: L1 docs do not contain INTERFACES/DATA_FLOW/TRAPS/DECISIONS
-
-9. CONFIGURE_HOOK:
-   Add UserPromptSubmit hook to .codebuddy/settings.json (see Section 11)
-
-10. REPORT:
-    Output summary: modules discovered, L1 docs generated, files excluded, warnings
+SUMMARY: Detect project type → discover modules (MODULE_DISCOVERY_CRITERIA) → create mirrored directory structure → generate root.prizm (L0) → generate L1 docs → skip L2 (lazy) → create changelog → configure hook → validate → report.
+
+DETAILED_STEPS: → ${SKILL_DIR}/references/op-init.md
+
+KEY_CONCEPTS:
+
+MODULE_DISCOVERY_CRITERIA — a directory qualifies as a module if ANY of the following is true:
+- Contains source files that collectively form a logical unit (shared responsibility)
+- Contains entry points, configuration files, or interface definitions
+- Contains sub-directories that themselves qualify as modules
+- Is referenced by multiple other modules as a dependency
+
+A directory does NOT qualify if ALL of the following are true:
+- Contains only generated/derived files (build output, compiled assets)
+- Contains only vendored/third-party code
+- Is in the EXCLUDE list
+
+HIERARCHY RULE: if directory X lives inside top-level module M, X is a sub-module of M — NOT a separate top-level module.
+
+EXCLUDE: .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .prizmkit/, .prizm-docs/, dev-pipeline/
 
 ## 9.2 Post-Init Behavior
 
@@ -682,117 +534,12 @@ The Prizm skill is defined at: ${SKILL_DIR}/SKILL.md
 
 OPERATIONS (all invoked via the prizmkit-prizm-docs skill):
 
-  Init       - Bootstrap .prizm-docs/ for a new project (Section 9)
-  Update     - Sync docs with code changes (Section 7)
-  Status     - Check freshness of all docs
-  Rebuild    - Regenerate docs for a specific module
-  Validate   - Check format compliance and consistency (Section 10.2)
-  Migrate    - Convert existing docs to .prizm-docs/ format (Section 10.3)
-
-## 10.2 Validate Operation
-
-OPERATION: Validate (invoked via prizmkit-prizm-docs skill)
-PRECONDITION: .prizm-docs/ directory exists
-
-ALGORITHM: prizm_validate
-
-STEPS:
-
-1. FORMAT_CHECK:
-   FOR EACH .prizm file:
-     VERIFY: All content uses KEY: value format or dash-prefixed list items
-     FLAG: Prose paragraphs (lines without KEY: prefix or - prefix)
-     FLAG: Code blocks (``` markers)
-     FLAG: Markdown headers (## / ### markers)
-     FLAG: Emoji, ASCII art, horizontal rules
-     FLAG: Markdown tables
-
-2. SIZE_CHECK:
-   VERIFY: root.prizm <= 4KB
-   VERIFY: All L1 files <= 4KB
-   VERIFY: All L2 files <= 5KB
-   REPORT: Files exceeding limits with current size and limit
-
-3. POINTER_CHECK:
-   FOR EACH arrow pointer (->) in all .prizm files:
-     VERIFY: Target file exists on disk
-     REPORT: Broken pointers with source file, line, and missing target
-
-4. STALENESS_CHECK:
-   FOR EACH .prizm file:
-     COMPARE: git last-modified time of .prizm file vs git last-modified time of corresponding source directory
-     COMMAND: `git log -1 --format="%ai" -- <prizm-file>` vs `git log -1 --format="%ai" -- <source-dir>/`
-     FLAG: Docs where source was modified more recently than the .prizm file as potentially stale
-
-5. COMPLETENESS_CHECK:
-   root.prizm MUST have: PRIZM_VERSION, PROJECT, LANG, MODULE_INDEX, RULES
-   L1 docs MUST have: MODULE, FILES, RESPONSIBILITY, DEPENDENCIES
-   L1 docs MUST NOT have: INTERFACES, DATA_FLOW, TRAPS, DECISIONS (those belong in L2)
-   L2 docs MUST have: MODULE, FILES, KEY_FILES, DEPENDENCIES, INTERFACES, TRAPS
-   REPORT: Missing required fields per file
-
-6. ANTI_PATTERN_CHECK:
-   FLAG: Duplicate information across levels (same content in L0 and L1)
-   FLAG: Behavioral detail in L1 (INTERFACES, DATA_FLOW, TRAPS, DECISIONS belong in L2 only)
-   FLAG: TODO items or future plans in any .prizm file
-   FLAG: Session-specific context or conversation history
-
-7. RULES_HIERARCHY_CHECK:
-   EXTRACT: RULES from root.prizm (authoritative)
-   FOR EACH L1/L2 doc with RULES section:
-     CHECK: No contradiction with root.prizm RULES
-     VERIFY: L1/L2 RULES only add module-specific exceptions
-     FLAG: Direct contradictions with root.prizm RULES
-
-OUTPUT: Validation report with PASS/FAIL per check category, issue list with file paths and line references, suggested fixes for common problems.
-
-## 10.3 Migrate Operation
-
-OPERATION: Migrate (invoked via prizmkit-prizm-docs skill)
-PRECONDITION: Existing documentation (docs/, docs/AI_CONTEXT/, README.md, ARCHITECTURE.md, etc.). No .prizm-docs/ directory (or user confirms overwrite).
-
-ALGORITHM: prizm_migrate
-
-STEPS:
-
-1. DISCOVER_EXISTING_DOCS:
-   SCAN for: docs/, docs/AI_CONTEXT/, README.md, ARCHITECTURE.md, CONTRIBUTING.md, API docs
-   CATALOG: List all found documentation files with sizes and types
-
-2. EXTRACT_INFORMATION:
-   FROM each doc, extract:
-   - Project metadata (name, language, framework, build/test commands)
-   - Module descriptions and responsibilities
-   - Architecture patterns and layers
-   - Rules, conventions, and constraints
-   - Decisions and their rationale
-   - Dependencies and relationships
-   - Known issues and traps
-
-3. MAP_TO_PRIZM_LEVELS:
-   Project-wide info -> root.prizm (L0): PROJECT, LANG, FRAMEWORK, RULES, PATTERNS
-   Module-level info -> L1 docs: MODULE, RESPONSIBILITY, INTERFACES, DEPENDENCIES
-   Detailed module info -> L2 docs: KEY_FILES, TRAPS, domain-specific sections
-
-4. CONVERT_FORMAT:
-   Strip markdown formatting (headers, tables, horizontal rules, emphasis)
-   Convert prose to KEY: value pairs
-   Convert lists to dash-prefixed items
-   Convert code blocks to file_path:line_number references
-   Condense multi-sentence explanations to single-line values
-
-5. GENERATE_PRIZM_DOCS:
-   Follow standard init procedure (Section 9) but seed with extracted information
-   Merge source-code-scanned data with documentation-extracted data
-   Prefer documentation-extracted RULES (they capture rationale)
-   Prefer source-code-scanned INTERFACES and DEPENDENCIES (they are current)
-
-6. VALIDATE:
-   Run full validation per Section 10.2
-   Flag any content that could not be automatically converted
-
-7. REPORT:
-   Output: Source files processed, .prizm files generated, content successfully migrated, content requiring manual review, warnings
+  Init       - Bootstrap .prizm-docs/ for a new project. → ${SKILL_DIR}/references/op-init.md
+  Update     - Sync docs with code changes. → ${SKILL_DIR}/references/op-update.md
+  Status     - Check freshness of all docs. → ${SKILL_DIR}/references/op-status.md
+  Rebuild    - Regenerate docs for a specific module. → ${SKILL_DIR}/references/op-rebuild.md
+  Validate   - Check format compliance and consistency. → ${SKILL_DIR}/references/op-validate.md
+  Migrate    - Convert existing docs to .prizm-docs/ format. Steps inline in SKILL.md.
 
 ---
 
@@ -882,235 +629,3 @@ Python            import ..., from ... import ...
 Rust              use crate::..., use super::..., extern crate
 Java              import package.Class
 C#                using Namespace
-
----
-
-# SECTION 13: MINIMAL VIABLE PRIZM
-
-For any project, the minimum viable Prizm setup is:
-
-FILES:
-  .prizm-docs/root.prizm        # Project meta + module index (L0)
-  .prizm-docs/changelog.prizm   # Change log
-
-This is enough to give AI a project overview and track changes.
-L1 and L2 docs can be added incrementally as AI works in specific areas.
-
-BOOTSTRAP:
-  Invoke prizmkit-prizm-docs skill (Init operation)
-
-Or manually create these two files following the templates in Section 3.
-
----
-
-# SECTION 14: VERSION HISTORY
-
-V1 (2026-03-02): Initial specification
-- 3-level progressive loading (L0, L1, L2)
-- KEY: value format, AI-only audience
-- UserPromptSubmit hook with type: prompt for auto-update
-- Mirrored directory structure under .prizm-docs/
-- Lazy L2 generation strategy
-- Universal language support
-
-V2 (2026-03-02): Enhanced specification
-- Added ON_DEEP_READ trigger for L2 generation (L2 created during deep analysis, not just modifications)
-- Added Validate operation for format compliance and consistency checking
-- Added Migrate operation for converting existing docs to .prizm-docs/ format
-- Added RULES hierarchy: root.prizm RULES authoritative, L1/L2 supplement only with module-specific exceptions
-- Added Section 15: Conflict Resolution for multi-person collaboration merge strategies
-- Added Section 16: Version Migration for upgrading between spec versions
-- Changed fixed skill path to ${SKILL_DIR} convention for cross-IDE compatibility
-- Enhanced Section 9.1 with ON_DEEP_READ trigger alongside ON_MODIFY
-- Updated PRIZM_SPEC_VERSION to 2
-
-V3 (2026-03-25): Knowledge quality and resilience
-- TRAPS entries now MUST have severity prefix: [CRITICAL], [HIGH], or [LOW]
-- TRAPS optional fields: REF (commit hash for traceability), STALE_IF (glob for auto-expiry detection)
-- Added TRAPS staleness check in retrospective (step 1g): auto-archive stale TRAPS when count > 10
-- Added Failure Capture Protocol: bootstrap templates write failure-log.md on session failure for cross-session learning
-- Added retrospective data source: failure-log.md DISCOVERED_TRAPS are prioritized for .prizm-docs/ injection
-- Added TRAPS_FORMAT_REFERENCE as spec-only block (must NOT appear in generated .prizm files)
-- Added V2→V3 migration: auto-tag legacy TRAPS with [LOW] default severity
-- Updated PRIZM_SPEC_VERSION to 3
-
-V4 (2026-03-28): L1/L2 boundary clarification and doc quality
-- L1 redefined as structural index: removed INTERFACES, DATA_FLOW, TRAPS, DECISIONS from L1 template
-- L1 RULES now summary only (1-3 critical rules); full RULES list in L2
-- L1 size limit raised from 3KB to 4KB
-- MODULE_INDEX allows multi-level entries; no hard depth limit, constrained by L0 4KB
-- Module discovery changed from "3+ source files" to semantic MODULE_DISCOVERY_CRITERIA
-- Added CROSS_CUTTING section to root.prizm for cross-module architectural knowledge
-- Added cross-cutting/ subdirectory in .prizm-docs/ for detailed cross-cutting concern docs
-- Relaxed update skip conditions: test files and bug fixes can generate TRAPS
-- Added V3→V4 migration: move INTERFACES/DATA_FLOW/TRAPS/DECISIONS from L1 to L2
-- Updated PRIZM_SPEC_VERSION to 4
-
----
-
-# SECTION 15: CONFLICT RESOLUTION
-
-## 15.1 Multi-Person Collaboration
-
-CONTEXT: When multiple developers (human or AI) work on the same project, .prizm-docs/ files may have merge conflicts since they are committed to git.
-
-## 15.2 Merge Strategies by Section Type
-
-APPEND_ONLY_SECTIONS:
-- changelog.prizm: Append-only. Use standard git merge. Both sides' entries are kept. Sort by date descending after merge.
-- DECISIONS (in any .prizm file): Append-only. Keep all entries from both sides on merge conflicts.
-- REJECTED (in any .prizm file): Append-only. Keep all entries from both sides.
-- CHANGELOG (in L2 docs): Append-only. Keep all entries from both sides.
-
-LATEST_WINS_SECTIONS:
-- FILES: Take the higher count (or recount from source)
-- KEY_FILES: Take the version from the branch with more recent git commit timestamp
-- INTERFACES: Take the version from the branch with more recent git commit timestamp (L2 only)
-- DATA_FLOW: Take the version from the branch with more recent git commit timestamp (L2 only)
-- DEPENDENCIES: Take the version from the branch with more recent git commit timestamp
-- MODULE_INDEX: Merge entries from both sides, take latest counts, keep all pointers
-- CROSS_CUTTING: Merge entries from both sides, keep all concerns
-- RULES: Take the version from the branch with more recent git commit timestamp
-- TRAPS: Union of both sides (traps are safety-critical, never discard)
-
-## 15.3 Conflict Resolution Algorithm
-
-ALGORITHM: prizm_merge_conflict
-
-1. DETECT: Identify conflicted .prizm files from git merge markers (<<<<<<<, =======, >>>>>>>)
-
-2. FOR EACH conflicted file:
-   a. PARSE both versions (ours and theirs) into sections by ALL CAPS KEY
-   b. FOR EACH section:
-      IF section is APPEND_ONLY (DECISIONS, REJECTED, CHANGELOG):
-        MERGE: Concatenate entries from both versions, deduplicate by content, sort by date
-      IF section is LATEST_WINS:
-        COMPARE: git commit timestamps from both branches
-        TAKE: Version from the more recent commit
-      IF section is TRAPS:
-        UNION: Keep all entries from both versions, deduplicate by content
-   c. REASSEMBLE: Write merged sections back to file
-   d. VALIDATE: Check size limits and format compliance
-
-3. STAGE: git add resolved .prizm files
-
-4. IF manual intervention needed:
-   FLAG: Sections where both versions modified the same KEY: value line with different values
-   REPORT: List conflicted keys for human review
-
-## 15.4 Prevention
-
-BEST_PRACTICE: Run prizmkit-prizm-docs Update operation immediately before committing to minimize drift
-BEST_PRACTICE: Keep .prizm doc changes small and focused (section-level, not file-level rewrites)
-BEST_PRACTICE: Coordinate on MODULE_INDEX changes (adding/removing modules) to avoid structural conflicts
-
----
-
-# SECTION 16: VERSION MIGRATION
-
-## 16.1 Migration Principles
-
-BACKWARD_COMPATIBLE: V4 can parse V3 docs without errors, but Validate will flag L1 docs containing INTERFACES/DATA_FLOW/TRAPS/DECISIONS and auto-migration (Section 16.4) will move them to L2
-FORWARD_COMPATIBLE: V3 tools will ignore V4-only fields (CROSS_CUTTING) they do not recognize
-MIGRATION_TRIGGER: AI detects PRIZM_VERSION in root.prizm and applies migration if needed
-
-## 16.2 V1 to V2 Migration
-
-TRIGGER: Automatic on first prizmkit-prizm-docs Update or Validate operation after spec upgrade
-
-ALGORITHM: prizm_migrate_v1_to_v2
-
-1. UPDATE_VERSION:
-   Change: PRIZM_VERSION: 1 -> PRIZM_VERSION: 2
-   In: root.prizm
-
-2. ADD_RULES_HIERARCHY:
-   VERIFY: root.prizm has RULES section
-   ADD comment-free note: root.prizm RULES are authoritative
-   SCAN: L1/L2 docs for RULES sections
-   FLAG: Any L1/L2 RULES that contradict root.prizm RULES for manual review
-
-3. VALIDATE:
-   Run full Validate operation
-   REPORT: Migration results and any issues found
-
-4. UPDATE_CHANGELOG:
-   APPEND: - YYYY-MM-DD | root | update: migrated from PRIZM_VERSION 1 to 2
-
-## 16.3 V2 to V3 Migration
-
-TRIGGER: Automatic on first prizmkit-prizm-docs Update or Validate operation after spec upgrade
-
-ALGORITHM: prizm_migrate_v2_to_v3
-
-1. UPDATE_VERSION:
-   Change: PRIZM_VERSION: 2 -> PRIZM_VERSION: 3
-   In: root.prizm
-
-2. MIGRATE_TRAPS_FORMAT:
-   SCAN: All L1 and L2 .prizm files for TRAPS entries
-   FOR EACH TRAPS entry without severity prefix ([CRITICAL], [HIGH], or [LOW]):
-     PREPEND: [LOW] as conservative default severity
-     EXAMPLE: `- foo is dangerous | FIX: use bar` becomes `- [LOW] foo is dangerous | FIX: bar`
-   RATIONALE: [LOW] is the safest default — it preserves the trap without over-alarming.
-   AI or user can manually upgrade severity to [HIGH] or [CRITICAL] during next retrospective.
-
-3. VALIDATE:
-   Run full Validate operation
-   REPORT: Migration results — number of TRAPS entries migrated, files updated
-
-4. UPDATE_CHANGELOG:
-   APPEND: - YYYY-MM-DD | root | update: migrated from PRIZM_VERSION 2 to 3 (TRAPS severity prefixes added)
-
-## 16.4 V3 to V4 Migration
-
-TRIGGER: Automatic on first prizmkit-prizm-docs Update or Validate operation after spec upgrade
-
-ALGORITHM: prizm_migrate_v3_to_v4
-
-1. UPDATE_VERSION:
-   Change: PRIZM_VERSION: 3 -> PRIZM_VERSION: 4
-   In: root.prizm
-
-2. MIGRATE_L1_CONTENT_TO_L2:
-   FOR EACH L1 .prizm file:
-     IF file contains INTERFACES, DATA_FLOW, TRAPS, or DECISIONS sections:
-       IF corresponding L2 doc exists at the child path:
-         MERGE: Append sections into L2 doc (do not overwrite existing L2 content)
-       ELSE:
-         CREATE: New L2 doc with moved sections + MODULE/FILES/RESPONSIBILITY from L1
-       REMOVE: Those sections from L1 file
-     IF file has RULES with > 3 entries:
-       KEEP: Top 3 most critical entries in L1 RULES
-       MOVE: Full RULES list to L2 RULES section
-   RATIONALE: L1 is now a structural index only. Behavioral detail belongs in L2.
-
-3. UPDATE_SIZE_REFS:
-   All internal size checks: L1 <= 3KB -> L1 <= 4KB
-
-4. ADD_CROSS_CUTTING:
-   IF root.prizm does not have CROSS_CUTTING section:
-     ADD: Empty CROSS_CUTTING section after PATTERNS
-   RATIONALE: Placeholder for future cross-module concern entries.
-
-5. VALIDATE:
-   Run full Validate operation
-   REPORT: Migration results — L1 sections moved to L2, RULES trimmed, files updated
-
-6. UPDATE_CHANGELOG:
-   APPEND: - YYYY-MM-DD | root | update: migrated from PRIZM_VERSION 3 to 4 (L1/L2 boundary redefined, CROSS_CUTTING added)
-
-## 16.5 Future Version Migration Pattern
-
-FOR any future version N to N+1:
-
-1. READ: root.prizm PRIZM_VERSION
-2. IF version < target: Apply migration steps sequentially (V1->V2, V2->V3, etc.)
-3. EACH migration step:
-   a. Update PRIZM_VERSION
-   b. Add new required fields with sensible defaults
-   c. Transform existing fields if format changed
-   d. Validate result
-   e. Append migration entry to changelog
-4. NEVER: Delete existing fields during migration (only add or transform)
-5. ALWAYS: Keep backward compatibility (old tools should still parse new format)

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

@@ -0,0 +1,46 @@
+# Operation: Init — Detailed Steps
+
+Bootstrap .prizm-docs/ for the current project.
+
+PRECONDITION: No .prizm-docs/ directory exists, or user confirms overwrite.
+
+STEPS:
+1. Detect project type by scanning for build system files (go.mod, package.json, requirements.txt, Cargo.toml, pom.xml, *.csproj). Identify primary language, framework, build command, test command, and entry points.
+2. Discover modules using MODULE_DISCOVERY_CRITERIA:
+   - A directory qualifies as a module if it contains source files forming a logical unit, contains entry/config/interface files, contains qualifying sub-modules, or is referenced by multiple modules as a dependency.
+   - TOP-LEVEL modules: directories directly under project root (or under src/ for src-based layouts) that qualify.
+   - SUB-MODULES: directories INSIDE a top-level module that qualify. Listed in the parent L1 doc's SUBDIRS section.
+   - HIERARCHY RULE: directory X inside top-level module M maps to .prizm-docs/<M>/<X>.prizm, never to .prizm-docs/<X>.prizm.
+   - Exclude .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .prizmkit/, .prizm-docs/, dev-pipeline/. If total module count > 30, ask user for include/exclude patterns.
+3. Create .prizm-docs/ directory structure mirroring the source tree exactly. For each top-level module M that has sub-modules, create the subdirectory .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 UPDATED timestamp — git tracks modification times.
+   - 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.
+5. Generate L1 .prizm files (structural index only) for ALL modules, each at its correct mirrored path:
+   - Top-level module M → write .prizm-docs/<M>.prizm (include SUBDIRS section with pointers to sub-module docs)
+   - Sub-module S inside M → write .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. Create changelog.prizm with initial entry: `- root | add: initialized prizm documentation framework`
+8. Configure UserPromptSubmit hook in platform settings per ${SKILL_DIR}/assets/prizm-docs-format.md.md Section 11.
+9. 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 UPDATED timestamps (git is authority).
+10. Report summary: modules discovered, L1 docs generated, files excluded, warnings.
+
+OUTPUT: List of generated files, module count, and validation results.
+
+## Post-Init Behavior
+
+After initialization, L2 docs are created incrementally:
+
+ON_MODIFY trigger:
+- First time AI modifies a file in sub-module S within module M:
+  IF .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_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 .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

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

@@ -0,0 +1,16 @@
+# Operation: Rebuild — Detailed Steps
+
+Regenerate docs for a specific module from scratch. Requires a module path argument.
+
+PRECONDITION: .prizm-docs/ exists. Module path is valid.
+
+STEPS:
+1. Delete existing L1 and all L2 docs for the specified module.
+2. Re-scan the module directory for files, interfaces, dependencies, subdirectories.
+3. Generate fresh L1 doc with full module analysis.
+4. Generate L2 docs for all sub-modules immediately (unlike init, rebuild generates L2 right away to capture current state).
+5. Update MODULE_INDEX (or MODULE_GROUPS) in root.prizm with new file counts and pointers. Re-evaluate grouping: if total module count > 15 and currently using MODULE_INDEX, convert to MODULE_GROUPS. Regenerate keyword tags for rebuilt modules. **Preserve** any `PROJECT_BRIEF:` line in root.prizm.
+6. Append rebuild entry to changelog.prizm: `- <module-path> | refactor: rebuilt module documentation from scratch`
+7. Validate regenerated docs against size limits and format rules.
+
+OUTPUT: Regenerated doc summary with before/after comparison.