prizmkit 1.0.124 → 1.0.125

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.124",
-  "bundledAt": "2026-03-27T18:24:06.959Z",
-  "bundledFrom": "a7ba656"
+  "frameworkVersion": "1.0.125",
+  "bundledAt": "2026-03-27T19:33:35.398Z",
+  "bundledFrom": "ae0bada"
 }

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.124",
+  "version": "1.0.125",
   "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/prizmkit-prizm-docs/SKILL.md

@@ -44,21 +44,22 @@ 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 in TWO tiers — flat structures lose nesting relationships, and when two modules share an identically-named sub-module (e.g., `utils/`), flattening creates ambiguous paths:
-   - TOP-LEVEL modules: directories directly under project root (or under src/ for src-based layouts) that contain 3+ source files OR contain sub-directories with 3+ source files. These go into MODULE_INDEX.
-   - SUB-MODULES: directories INSIDE a top-level module that contain 3+ source files. Listed in the parent L1 doc's SUBDIRS section only.
+2. Discover modules using semantic MODULE_DISCOVERY_CRITERIA (see PRIZM-SPEC Section 9.1 Step 2):
+   - 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 top-level module count > 30, ask user for include/exclude patterns.
+   - 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 listing only top-level modules with arrow pointers to .prizm-docs/<M>.prizm (sub-modules stay out of MODULE_INDEX to keep L0 compact and within the 4KB limit), RULES extracted from CODEBUDDY.md/CLAUDE.md/README/linter configs, and PATTERNS. Set PRIZM_VERSION: 2, UPDATED: today's date. Max 4KB.
-5. Generate L1 .prizm files for ALL modules (top-level and sub-modules), each at its correct mirrored path:
+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.
+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 (for top-level only), KEY_FILES (5-10 most important), INTERFACES (public/exported only), DEPENDENCIES (imports, imported-by, external), RULES, DATA_FLOW. Max 3KB 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). This saves significant upfront token cost on large projects.
+   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: `- YYYY-MM-DD | root | add: initialized prizm documentation framework`
 8. Configure UserPromptSubmit hook in platform settings per ${SKILL_DIR}/assets/PRIZM-SPEC.md Section 11.
-9. Validate all generated docs: size limits (L0 <= 4KB, L1 <= 3KB), pointer resolution (every -> reference resolves), no circular dependencies, UPDATED timestamps set, KEY: value format compliance, no anti-patterns (prose, code blocks, markdown headers).
+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.
@@ -72,12 +73,12 @@ PRECONDITION: .prizm-docs/ exists with root.prizm.
 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.
 2. Map changed files to modules by matching against MODULE_INDEX in root.prizm. Group changes by module.
-3. Classify each change: A (added) -> new KEY_FILES/INTERFACES entries. D (deleted) -> remove entries, update counts. M (modified) -> check interface/dependency changes. R (renamed) -> update all path references.
-4. Update affected docs: L2 first (KEY_FILES, INTERFACES, DEPENDENCIES, CHANGELOG, UPDATED), then L1 (FILES count, KEY_FILES, INTERFACES, DEPENDENCIES, UPDATED), then L0 (MODULE_INDEX counts, UPDATED) only if structural change.
-5. Skip updates if: only internal implementation changed (no interface/dependency change), only comments/whitespace/formatting, only test files changed, only .prizm files changed, bug fixes to existing features (bugs are incomplete features being refined — no new module/interface created, no doc update needed).
-6. If new directory with 3+ source files appears and matches no module: create L1 immediately, add to MODULE_INDEX, defer L2.
+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, CHANGELOG), then L1 (FILES count, KEY_FILES, DEPENDENCIES — L1 does NOT contain INTERFACES/DATA_FLOW/TRAPS/DECISIONS), then L0 (MODULE_INDEX counts, CROSS_CUTTING) only if structural change. No UPDATED timestamps — git tracks modification times.
+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, defer L2.
 7. Append entries to changelog.prizm using format: `- YYYY-MM-DD | <module-path> | <verb>: <description>`
-8. Enforce size limits: L0 > 4KB -> consolidate. L1 > 3KB -> move details to L2. L2 > 5KB -> split or archive.
+8. Enforce size limits: L0 > 4KB -> consolidate. L1 > 4KB -> trim KEY_FILES descriptions, ensure RULES <= 3 entries. L2 > 5KB -> split or archive.
 9. Stage updated .prizm files via `git add .prizm-docs/`
 
 OUTPUT: List of updated/created/skipped docs with reasons.
@@ -89,13 +90,13 @@ Check freshness of all .prizm docs.
 PRECONDITION: .prizm-docs/ exists with root.prizm.
 
 STEPS:
-1. Read root.prizm UPDATED timestamp.
-2. Count commits since that timestamp via `git log --since="<timestamp>" --oneline | wc -l`.
-3. For each L1/L2 doc, compare UPDATED timestamp against latest git modification of source files in that module via `git log -1 --format="%ai" -- <module-path>/`.
-4. Classify each doc as: FRESH (updated after latest source change), STALE (source changed since last update), MISSING (module exists but no .prizm doc).
+1. Get last git modification time of root.prizm via `git log -1 --format="%ai" -- .prizm-docs/root.prizm`.
+2. Count commits since that time via `git log --since="<timestamp>" --oneline | wc -l`.
+3. For each L1/L2 doc, compare git modification time of the .prizm file (`git log -1 --format="%ai" -- <prizm-file>`) against latest git modification of source files in that module (`git log -1 --format="%ai" -- <module-path>/`).
+4. Classify each doc as: FRESH (prizm file updated after latest source change), STALE (source changed more recently than prizm file), MISSING (module exists but no .prizm doc).
 5. Flag any docs exceeding size limits.
 
-OUTPUT: Freshness report table with columns: DOC_PATH | LEVEL | STATUS | LAST_UPDATED | SOURCE_LAST_MODIFIED.
+OUTPUT: Freshness report table with columns: DOC_PATH | LEVEL | STATUS | PRIZM_LAST_MOD | SOURCE_LAST_MOD.
 
 ## Operation: Rebuild
 
@@ -124,8 +125,8 @@ 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]). 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 <= 3KB, 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. TIMESTAMP CHECK: Verify all docs have UPDATED field. Flag docs with UPDATED older than 30 days as potentially stale.
-5. COMPLETENESS CHECK: Verify root.prizm has all required fields (PRIZM_VERSION, PROJECT, LANG, MODULE_INDEX). Verify L1 docs have MODULE, FILES, RESPONSIBILITY, INTERFACES, DEPENDENCIES. Verify L2 docs have MODULE, FILES, KEY_FILES, DEPENDENCIES.
+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). 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.
 7. RULES HIERARCHY CHECK: Verify L1/L2 RULES do not contradict root.prizm RULES. L1/L2 may only supplement with module-specific exceptions.
 

package/bundled/skills/prizmkit-prizm-docs/assets/PRIZM-SPEC.md

@@ -1,4 +1,4 @@
-PRIZM_SPEC_VERSION: 3
+PRIZM_SPEC_VERSION: 4
 PURPOSE: AI-only documentation framework for vibe coding projects
 AUDIENCE: AI agents (not humans)
 FORMAT: KEY: value pairs, ALL CAPS section headers, arrow pointers
@@ -35,13 +35,14 @@ LEVELS:
   FILE: .prizm-docs/root.prizm
   CONTAINS: project meta, module index with pointers, build commands, tech stack, top rules
 
-- L1: Module index. Loaded ON DEMAND when AI works in a module area. Max 3KB each.
+- L1: Structural index. Loaded ON DEMAND when AI works in a module area. Max 4KB each.
   FILE: .prizm-docs/<mirrored-path>.prizm (mirrors source directory structure)
-  CONTAINS: module responsibility, subdirs with pointers, key files, interfaces, dependencies, rules
+  CONTAINS: module responsibility, subdirs with pointers, key files, dependency graph, critical rules summary (1-3 only)
+  DOES NOT CONTAIN: interface signatures, data flow, TRAPS, DECISIONS (those belong in L2)
 
-- L2: Detail doc. Loaded when AI modifies files in that sub-module OR needs deep understanding. Max 5KB each.
+- L2: Behavioral detail. Loaded when AI modifies files in that module OR needs deep understanding. Max 5KB each.
   FILE: .prizm-docs/<mirrored-path>/<submodule>.prizm
-  CONTAINS: full file inventory, domain-specific sections, decisions log, traps, rejected approaches
+  CONTAINS: interface signatures, data flow, full rules, TRAPS, DECISIONS, domain-specific sections, rejected approaches
 
 - Changelog: Append-only change log. Loaded at L0. No size limit but keep last 50 entries.
   FILE: .prizm-docs/changelog.prizm
@@ -93,6 +94,8 @@ EXAMPLE (Python project):
       services.prizm                      # L1 for app/services/
       services/
         payment.prizm                     # L2 for app/services/payment/
+    cross-cutting/                          # Optional: cross-module concern details
+      auth.prizm                          # L2-style doc for cross-cutting auth concern
 
 ## 2.3 Git Configuration
 
@@ -107,14 +110,13 @@ RATIONALE: .prizm-docs/ is shared project knowledge that all team members (human
 
 TEMPLATE:
 
-  PRIZM_VERSION: 2
+  PRIZM_VERSION: 4
   PROJECT: <name>
   LANG: <primary language>
   FRAMEWORK: <primary framework or "none">
   BUILD: <build command>
   TEST: <test command>
   ENTRY: <entry point file(s)>
-  UPDATED: <YYYY-MM-DD>
 
   ARCHITECTURE: <layer1> -> <layer2> -> <layer3> -> ...
   LAYERS:
@@ -127,6 +129,8 @@ TEMPLATE:
 
   MODULE_INDEX:
   - <source-path>: <file-count> files. <one-line description>. -> .prizm-docs/<mirrored-path>.prizm
+  (Multi-level entries allowed for efficient navigation. No hard depth limit — constrained by L0 4KB.
+   If navigating from L0 to a target module requires 3+ hops, add intermediate entries here.)
 
   ENTRY_POINTS:
   - <name>: <file-path> (<protocol/port if applicable>)
@@ -139,26 +143,31 @@ TEMPLATE:
   PATTERNS:
   - <pattern-name>: <one-line description of code pattern used across project>
 
+  CROSS_CUTTING:
+  - <concern-name>: <one-line description>. Modules: <affected-module-list>.
+  (Optional: -> .prizm-docs/cross-cutting/<name>.prizm for detailed cross-cutting doc.
+   Only record concerns spanning 2+ modules. Single-module patterns go in that module's RULES.)
+
   DECISIONS:
-  - [YYYY-MM-DD] <project-level architectural decision and rationale>
+  - <project-level architectural decision and rationale>
   - REJECTED: <rejected approach + why>
 
 CONSTRAINTS:
 - Max 4KB (roughly 100 lines)
 - Every line must be a KEY: value pair or a list item
 - MODULE_INDEX must have arrow pointer (->) for every entry
+- MODULE_INDEX may list entries at any depth needed for efficient navigation (no hard depth limit)
 - RULES limited to 5-10 most critical conventions
 - No prose paragraphs
 - root.prizm RULES are AUTHORITATIVE: they override any conflicting L1/L2 RULES
 
-## 3.2 L1: module.prizm
+## 3.2 L1: module.prizm (Structural Index)
 
 TEMPLATE:
 
   MODULE: <source-path>
   FILES: <count>
   RESPONSIBILITY: <one-line>
-  UPDATED: <YYYY-MM-DD>
 
   SUBDIRS:
   - <name>/: <one-line description>. -> .prizm-docs/<child-path>.prizm
@@ -166,37 +175,23 @@ TEMPLATE:
   KEY_FILES:
   - <filename>: <role/purpose>
 
-  INTERFACES:
-  - <function/method signature>: <what it does>
-
   DEPENDENCIES:
   - imports: <internal modules this module uses>
   - imported-by: <internal modules that depend on this>
   - external: <third-party packages used>
 
   RULES:
-  - MUST: <module-specific mandatory rule>
-  - NEVER: <module-specific prohibition>
-  - PREFER: <module-specific preference>
-
-  TRAPS:
-  - [CRITICAL|HIGH|LOW] <what looks safe but is dangerous> | FIX: <correct approach>
-
-  DECISIONS:
-  - <what was decided> — <rationale>
-
-  DATA_FLOW:
-  - <numbered step describing how data moves through this module>
+  - MUST: <1-3 most critical module-specific rules only — full list in L2>
 
 CONSTRAINTS:
-- Max 3KB
-- INTERFACES lists only PUBLIC/EXPORTED signatures
+- Max 4KB
+- L1 is a STRUCTURAL INDEX — it answers "what exists here" not "how it works"
+- DOES NOT CONTAIN: INTERFACES, DATA_FLOW, TRAPS, DECISIONS (those belong in L2)
+- RULES: summary only, max 3 entries of the most critical constraints. Full rules in L2.
 - DEPENDENCIES has 3 sub-categories (imports, imported-by, external)
-- SUBDIRS entries must have arrow pointer (->) if L2 doc exists
+- SUBDIRS entries must have arrow pointer (->) if child doc exists
 - KEY_FILES lists only the most important files (max 10-15)
 - RULES may only SUPPLEMENT root.prizm RULES with module-specific exceptions, never contradict them
-- 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
 
 TRAPS_FORMAT_REFERENCE (spec-only — do NOT include this block in generated .prizm files):
 - Severity levels: CRITICAL = data loss/security/financial/crash, HIGH = functional failure/silent error, LOW = naming/minor quality
@@ -206,14 +201,19 @@ TRAPS_FORMAT_REFERENCE (spec-only — do NOT include this block in generated .pr
 - Minimal valid format: `- [SEVERITY] <description> | FIX: <approach>`
 - Full format: `- [SEVERITY] <description> | FIX: <approach> | REF: <hash> | STALE_IF: <glob>`
 
-## 3.3 L2: detail.prizm
+## 3.3 L2: detail.prizm (Behavioral Detail)
 
 TEMPLATE:
 
   MODULE: <source-path>
   FILES: <comma-separated list of all files>
   RESPONSIBILITY: <one-line>
-  UPDATED: <YYYY-MM-DD>
+
+  INTERFACES:
+  - <function/method signature>: <what it does>
+
+  DATA_FLOW:
+  - <numbered step describing how data moves through this module>
 
   <DOMAIN-SPECIFIC SECTIONS>
   (AI generates these based on what the module does. Examples below.)
@@ -225,16 +225,22 @@ TEMPLATE:
   - uses: <external lib>: <why/how used>
   - imports: <internal module>: <which interfaces consumed>
 
-  DECISIONS:
-  - [YYYY-MM-DD] <decision made within this module and rationale>
-  - REJECTED: <approach that was tried/considered and abandoned + why>
+  RULES:
+  - MUST: <module-specific mandatory rule>
+  - NEVER: <module-specific prohibition>
+  - PREFER: <module-specific preference>
+  (Full rules list — L1 only has a 1-3 item summary of these)
 
   TRAPS:
   - [CRITICAL|HIGH|LOW] <gotcha: something that looks correct but is wrong or dangerous> | FIX: <correct approach>
   - [CRITICAL|HIGH|LOW] <non-obvious coupling, race condition, or side effect> | FIX: <approach>
 
+  DECISIONS:
+  - <decision made within this module> — <rationale>
+  - REJECTED: <approach that was tried/considered and abandoned + why>
+
   CHANGELOG:
-  - YYYY-MM-DD | <verb>: <description of recent change to this module>
+  - <verb>: <description of recent change to this module>
 
 DOMAIN_SPECIFIC_SECTION_EXAMPLES:
 - For state machines: STATES, TRIGGERS, TRANSITIONS
@@ -245,6 +251,10 @@ DOMAIN_SPECIFIC_SECTION_EXAMPLES:
 
 CONSTRAINTS:
 - Max 5KB
+- L2 is the BEHAVIORAL DETAIL — it answers "how it works, what can go wrong, what was decided"
+- INTERFACES: lists only PUBLIC/EXPORTED signatures (moved here from L1 in V4)
+- 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)
 - TRAPS section is CRITICAL for preventing AI from making known mistakes
@@ -260,17 +270,18 @@ CONSTRAINTS:
 TEMPLATE:
 
   CHANGELOG:
-  - YYYY-MM-DD | <module-path> | <verb>: <one-line description>
+  - <module-path> | <verb>: <one-line description>
 
 VERBS: add, update, fix, remove, refactor, rename, deprecate
 RETENTION: Keep last 50 entries. Archive older entries to changelog-archive.prizm if needed.
+TEMPORAL_INFO: Git commit history is the authoritative source for when changes happened. No dates in changelog entries — git log on .prizm-docs/changelog.prizm provides the timeline.
 
 EXAMPLE:
   CHANGELOG:
-  - 2026-03-02 | internal/logic/timer | add: retry logic with exponential backoff
-  - 2026-03-01 | internal/service/sso | update: create_robot handler validates chatbot config
-  - 2026-02-28 | internal/model/chatbot | add: DeepSeek provider model definition
-  - 2026-02-27 | internal/repo/rpc | fix: Hunyuan API timeout not respected
+  - internal/logic/timer | add: retry logic with exponential backoff
+  - internal/service/sso | update: create_robot handler validates chatbot config
+  - internal/model/chatbot | add: DeepSeek provider model definition
+  - internal/repo/rpc | fix: Hunyuan API timeout not respected
 
 ---
 
@@ -280,10 +291,10 @@ HEADERS: ALL CAPS followed by colon (MODULE:, FILES:, RESPONSIBILITY:, etc.)
 VALUES: Single space after colon, value on same line (KEY: value)
 LISTS: Dash-space prefix for items within a section (- item)
 POINTERS: Arrow notation (->) to reference other .prizm files
-DATES: [YYYY-MM-DD] in square brackets for timestamps
-CHANGELOG_SEPARATOR: Pipe (|) between date, module, and description
+CHANGELOG_SEPARATOR: Pipe (|) between module and description
 NESTING: Indent 2 spaces for sub-keys within a section
 COMMENTS: None. Every line carries information. No comments in .prizm files.
+TIMESTAMPS: No date/time fields in .prizm files. Git is the authoritative source for temporal information. Use `git log` or `git blame` on .prizm files when needed.
 
 ---
 
@@ -327,37 +338,54 @@ ON_SESSION_START:
 
 ON_TASK_RECEIVED:
   IF task references specific file or directory:
-    LOAD: L1 for the containing module
+    LOAD: L1 for the containing module (structural index: files, deps, key rules)
   IF task is broad (e.g., "refactor auth", "improve performance"):
     LOAD: L1 for all matching modules from MODULE_INDEX
   IF task is exploratory (e.g., "explain the codebase", "how does X work"):
     LOAD: L0 only, then navigate via pointers as needed
   IF task is cross-cutting (e.g., "add logging everywhere"):
-    LOAD: L1 for affected modules, check DEPENDENCIES.imported-by
+    LOAD: L1 for affected modules, check DEPENDENCIES.imported-by and CROSS_CUTTING in root.prizm
 
 ON_FILE_MODIFICATION:
   BEFORE editing any source file:
-    LOAD: L2 for the containing sub-module (if exists and not already loaded)
-    READ: TRAPS section (prevent known mistakes)
-    READ: DECISIONS section (understand prior choices)
-    READ: REJECTED entries (avoid re-proposing failed approaches)
+    TARGETED LOAD from L2 (NEVER read the entire L2 file — use grep to extract only needed sections):
+    1. Use Grep tool to search for "^TRAPS:" in the L2 doc, read that section (prevent known mistakes)
+    2. Use Grep tool to search for "^DECISIONS:" and "^REJECTED:", read those sections (understand prior choices)
+    3. Use Grep tool to search for "^INTERFACES:" if you need to understand the public API contract
+    Only load additional L2 sections if the task specifically requires them.
+    IF L2 does not exist: GENERATE L2 from source code analysis, then extract needed sections
 
 ON_DEEP_READ:
   WHEN AI needs deep understanding of a module WITHOUT modifying it:
-    LOAD: L2 for the containing sub-module (if exists)
-    IF L2 does not exist: GENERATE L2 from source code analysis, then load it
+    TARGETED LOAD from L2 using grep (same approach as ON_FILE_MODIFICATION)
+    IF L2 does not exist: GENERATE L2 from source code analysis, then extract needed sections
     USE_CASES: code review, architecture analysis, dependency tracing, explaining complex logic
-    RATIONALE: Deep reads benefit from the same structured context as modifications
 
 ## 6.2 Loading Rules
 
 NEVER: Load all L1 and L2 docs at session start (defeats progressive loading)
+NEVER: Read entire L2 files — always use grep/search to extract only the sections you need
 NEVER: Load L2 for modules not being modified or deeply analyzed (wastes context window)
 NEVER: Skip L0 (it is the map for everything else)
 PREFER: Load L1 before L2 (understand module context before diving into details)
-PREFER: Load minimum docs needed for the task
+PREFER: Load minimum docs and minimum sections needed for the task
 BUDGET: Typical task should consume 3000-5000 tokens of prizm docs total
 
+## 6.3 L2 Targeted Loading Protocol
+
+L2 docs can be up to 5KB. Loading them in full defeats the purpose of progressive loading.
+Use targeted grep to extract only the sections relevant to your current task:
+
+COMMAND_PATTERN:
+  Grep tool with pattern "^SECTION_NAME:" and context lines (-A flag) to read a specific section.
+  Stop reading at the next ALL-CAPS section header.
+
+EXAMPLES:
+  - Before editing a file: grep for "^TRAPS:" and "^DECISIONS:" sections
+  - Before changing an API: grep for "^INTERFACES:" section
+  - Before modifying data handling: grep for "^DATA_FLOW:" section
+  - For full module understanding (rare): read the entire L2 (only when task explicitly requires comprehensive analysis)
+
 ---
 
 # SECTION 7: AUTO-UPDATE PROTOCOL
@@ -393,28 +421,31 @@ ALGORITHM: prizm_update
      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
-        UPDATE: UPDATED timestamp
      b. IF L1 doc exists:
         UPDATE: FILES count
         UPDATE: KEY_FILES (if major files added/removed)
-        UPDATE: INTERFACES (if public API changed)
         UPDATE: DEPENDENCIES (if module-level deps changed)
-        UPDATE: UPDATED timestamp
+        (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
-        UPDATE: UPDATED timestamp
 
 5. SKIP_CONDITIONS:
    SKIP if: Only internal implementation changed (no interface/dependency change)
    SKIP if: Only comments, whitespace, or formatting changed
-   SKIP if: Only test files changed (unless test patterns doc exists)
    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 with 3+ source files appears AND matches no existing module:
+   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
@@ -422,7 +453,7 @@ ALGORITHM: prizm_update
 7. SIZE_ENFORCEMENT:
    AFTER each update, check file sizes:
    L0 > 4KB: Consolidate MODULE_INDEX entries, remove lowest-value RULES
-   L1 > 3KB: Move implementation details to L2, keep only signatures in INTERFACES
+   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:
@@ -432,7 +463,7 @@ ALGORITHM: prizm_update
 ## 7.3 Changelog Update
 
 ALWAYS append to .prizm-docs/changelog.prizm after any doc update.
-FORMAT: - YYYY-MM-DD | <module-path> | <verb>: <one-line description>
+FORMAT: - <module-path> | <verb>: <one-line description>
 VERBS: add, update, fix, remove, refactor, rename, deprecate
 
 ---
@@ -444,8 +475,8 @@ WHAT_NOT_TO_PUT_IN_PRIZM_DOCS:
 NEVER: Prose paragraphs or explanatory text (use KEY: value or bullet lists)
 NEVER: Code snippets longer than 1 line (reference file_path:line_number instead)
 NEVER: Human-readable formatting (emoji, ASCII art, markdown tables, horizontal rules)
-NEVER: Duplicate information across levels (L0 summarizes, L1 details, L2 deep-dives)
-NEVER: Implementation details in L0 or L1 (those belong in L2 only)
+NEVER: Duplicate information across levels (L0 summarizes, L1 indexes structure, L2 details behavior)
+NEVER: Implementation details or behavioral detail in L0 or L1 (INTERFACES, DATA_FLOW, TRAPS, DECISIONS belong in L2 only)
 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)
@@ -490,23 +521,33 @@ STEPS:
 2. DISCOVER_MODULES:
    SCAN source directories, preserving the tree structure (DO NOT FLATTEN):
 
-   a. IDENTIFY TOP-LEVEL modules: directories directly under project root (or directly under src/ for src-based layouts) that either:
-      - Contain 3+ source files of the primary language, OR
-      - Contain sub-directories that each have 3+ source files
+   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 contain 3+ source files
+   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 ONLY top-level modules from step 2a.
-      Sub-modules appear in their parent's L1 doc SUBDIRS section, not in MODULE_INDEX.
+   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 top-level module count > 30: ASK user for include/exclude patterns
+   IF total module count > 30: ASK user for include/exclude patterns
 
 3. CREATE_DIRECTORY_STRUCTURE:
    Create .prizm-docs/ directory
@@ -520,46 +561,42 @@ STEPS:
 
 4. GENERATE_ROOT (L0):
    Fill: PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY from step 1
-   Build: MODULE_INDEX — list ONLY top-level modules from step 2a, one entry per module with pointer to .prizm-docs/<M>.prizm
-   NEVER list sub-modules in MODULE_INDEX (sub-modules are navigated via L1 SUBDIRS pointers)
+   Build: MODULE_INDEX — 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
-   Set: PRIZM_VERSION: 2, UPDATED: today's date
+   Extract: CROSS_CUTTING — identify patterns/constraints that span 2+ modules
+   Set: PRIZM_VERSION: 4
 
-5. GENERATE_L1_DOCS:
-   FOR EACH top-level module M in MODULE_INDEX:
-     SCAN M directory:
+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)
-     - Identify exported/public interfaces (language-specific: exported funcs in Go, export in JS/TS, public in Java, pub in Rust)
      - Trace import/require/use statements for DEPENDENCIES
-     - List sub-modules from step 2b in SUBDIRS with pointers: .prizm-docs/<M>/<sub>.prizm
+     - List sub-modules in SUBDIRS with pointers
      - Identify 5-10 most important files for KEY_FILES
-     WRITE: .prizm-docs/<M>.prizm
+     - 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 top-level module M:
-     SCAN M/S directory:
-     - Count all source files in S
-     - Identify exported/public interfaces within S
-     - Trace dependencies within S
-     - Identify key files in S
-     WRITE: .prizm-docs/<M>/<S>.prizm
-     NOTE: This is still an L1 doc (module index level), written at the mirrored sub-path
+   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 requires deep code understanding. Generating shallow L2 docs during init would produce misleading content and create false confidence. L2 docs are generated lazily when AI first modifies files in a sub-module or performs a deep read (ON_DEEP_READ trigger).
+   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:
-   - YYYY-MM-DD | root | add: initialized prizm documentation framework
+   - root | add: initialized prizm documentation framework
 
 8. VALIDATE:
-   CHECK: All generated files are within size limits (L0 <= 4KB, L1 <= 3KB)
+   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: UPDATED timestamps are set on all files
    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)
@@ -621,7 +658,7 @@ STEPS:
 
 2. SIZE_CHECK:
    VERIFY: root.prizm <= 4KB
-   VERIFY: All L1 files <= 3KB
+   VERIFY: All L1 files <= 4KB
    VERIFY: All L2 files <= 5KB
    REPORT: Files exceeding limits with current size and limit
 
@@ -630,21 +667,22 @@ STEPS:
      VERIFY: Target file exists on disk
      REPORT: Broken pointers with source file, line, and missing target
 
-4. TIMESTAMP_CHECK:
+4. STALENESS_CHECK:
    FOR EACH .prizm file:
-     VERIFY: UPDATED field exists
-     FLAG: Docs with UPDATED older than 30 days as potentially stale
-     COMPARE: UPDATED against git log for corresponding source directory
+     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, INTERFACES, DEPENDENCIES
-   L2 docs MUST have: MODULE, FILES, KEY_FILES, DEPENDENCIES, TRAPS
+   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: Implementation details in L0 or L1 (belong in L2 only)
+   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
 
@@ -845,6 +883,18 @@ V3 (2026-03-25): Knowledge quality and resilience
 - 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
@@ -862,13 +912,14 @@ APPEND_ONLY_SECTIONS:
 - CHANGELOG (in L2 docs): Append-only. Keep all entries from both sides.
 
 LATEST_WINS_SECTIONS:
-- UPDATED: Take the more recent timestamp
 - FILES: Take the higher count (or recount from source)
-- KEY_FILES: Take the version from the branch with more recent UPDATED timestamp
-- INTERFACES: Take the version from the branch with more recent UPDATED timestamp
-- DEPENDENCIES: Take the version from the branch with more recent UPDATED timestamp
+- 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
-- RULES: Take the version from the branch with more recent UPDATED timestamp
+- 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
@@ -883,8 +934,8 @@ ALGORITHM: prizm_merge_conflict
       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: UPDATED timestamps from both versions
-        TAKE: Version with more recent UPDATED timestamp
+        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
@@ -908,8 +959,8 @@ BEST_PRACTICE: Coordinate on MODULE_INDEX changes (adding/removing modules) to a
 
 ## 16.1 Migration Principles
 
-BACKWARD_COMPATIBLE: V3 can parse V2 docs without errors, but Validate will flag TRAPS entries missing severity prefixes and auto-migration (Section 16.3) will add [LOW] defaults
-FORWARD_COMPATIBLE: V2 tools will ignore V3-only fields they do not recognize
+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
@@ -960,7 +1011,45 @@ ALGORITHM: prizm_migrate_v2_to_v3
 4. UPDATE_CHANGELOG:
    APPEND: - YYYY-MM-DD | root | update: migrated from PRIZM_VERSION 2 to 3 (TRAPS severity prefixes added)
 
-## 16.4 Future Version Migration Pattern
+## 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:
 

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

@@ -59,21 +59,21 @@ git diff --name-status
 
 **1d.** Update affected docs (bottom-up: L2 → L1 → L0):
 
-- **L2** (if exists): Update KEY_FILES, INTERFACES, DEPENDENCIES, CHANGELOG, UPDATED timestamp
-- **L1**: Update FILES count, KEY_FILES (if major files added/removed), INTERFACES (if public API changed), UPDATED timestamp
-- **L0 root.prizm**: Update MODULE_INDEX file counts only if counts changed. Update UPDATED only if structural change (module added/removed).
+- **L2** (if exists): Update KEY_FILES, INTERFACES, DATA_FLOW, DEPENDENCIES, CHANGELOG, TRAPS, DECISIONS
+- **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).
 
 **1d-migrate.** Legacy TRAPS format migration (opportunistic):
 While updating an affected L1/L2 doc, if you encounter TRAPS entries **without** a severity prefix (e.g., `- foo | FIX: bar` instead of `- [LOW] foo | FIX: bar`), prepend `[LOW]` as a conservative default. This clears legacy format debt incrementally — only in files already being touched, never as a bulk operation.
 
-**1e.** If new directory with 3+ source files matches no existing module: create L1 doc immediately, add to MODULE_INDEX, defer L2.
+**1e.** If new directory qualifies as a module (per MODULE_DISCOVERY_CRITERIA in PRIZM-SPEC Section 9.1 Step 2) and matches no existing module: create L1 doc immediately, add to MODULE_INDEX, defer L2.
 
 **1f.** Enforce size limits:
 - L0 > 4KB → consolidate MODULE_INDEX
-- L1 > 3KB → move details to L2
+- L1 > 4KB → trim KEY_FILES descriptions, ensure RULES <= 3 entries
 - L2 > 5KB → archive old CHANGELOG entries
 
-**SKIP structural sync if**: only internal implementation changed (no interface/dependency impact), only comments/whitespace, only test files, only .prizm files, bug fixes with no interface change.
+**SKIP structural sync if**: only internal implementation changed (no interface/dependency impact), only comments/whitespace, only .prizm files. **DO NOT skip** test file changes or bug fixes — they may reveal TRAPS worth capturing in L2.
 
 **1g. TRAPS staleness check** (only when an L2 doc's TRAPS section has > 10 entries):
 
@@ -95,7 +95,7 @@ Extract TRAPS, RULES, and DECISIONS from development work and inject into `.priz
 ### When to run Job 2
 
 - Feature completion (spec + plan + implementation done)
-- Bugfix with a genuinely new pitfall discovered
+- Bugfix that reveals a non-obvious failure mode (the root cause is itself a TRAP)
 - Refactor that revealed structural insights
 - **Skip for**: trivial fixes, config changes, dependency bumps
 
@@ -143,8 +143,9 @@ When writing TRAPS:
 **QUALITY GATE**: Every item must answer: "If a new AI session reads only `.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.
 
 **2c.** Inject into the correct `.prizm-docs/` file:
-- Module-level TRAPS/RULES/DECISIONS → the affected L1 or L2 `.prizm` file's corresponding section
+- Module-level TRAPS/RULES/DECISIONS → the affected **L2** `.prizm` file's corresponding section (TRAPS/DECISIONS/RULES belong in L2, not L1)
 - Project-level RULES/PATTERNS → `root.prizm`
+- Cross-module concerns spanning 2+ modules → `root.prizm` CROSS_CUTTING section
 
 **RULE**: Only add genuinely new information. Never duplicate existing entries. Never rewrite entire files.
 

package/package.json

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