prizmkit 1.1.155 → 1.1.156

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.155",
-  "bundledAt": "2026-07-27T14:17:49.935Z",
-  "bundledFrom": "330ce51"
+  "frameworkVersion": "1.1.156",
+  "bundledAt": "2026-07-27T23:46:04.550Z",
+  "bundledFrom": "6d92126"
 }

package/bundled/skills/_metadata.json

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

package/bundled/skills/prizmkit-prizm-docs/SKILL.md

@@ -34,6 +34,54 @@ Do not route ordinary development-loop "update docs" or "sync docs" here. In nor
 
 Key principle: `/prizmkit-prizm-docs` defines and repairs the documentation system. `/prizmkit-retrospective` keeps docs in sync during ordinary development.
 
+## Governing Content Gates
+
+These gates apply uniformly wherever this Skill generates, migrates, repairs, or rebuilds documentation. Operation references may add sequencing but must not weaken them.
+
+### Value Gate
+
+Before retaining any candidate fact, ask exactly:
+
+> Could a future AI that lacks this fact make an incorrect modification?
+
+Retain the fact only when the answer is yes and the fact is current, durable, non-obvious, and stated at the lowest owning level. High-value knowledge includes:
+
+- non-obvious public interfaces and wire contracts
+- cross-module constraints and non-obvious dependencies
+- traps and side effects that can cause an incorrect change
+- durable decisions with only the rationale necessary to preserve the choice
+- rejected alternatives that future sessions are likely to propose again, with the reason for rejection
+- security, data-integrity, concurrency, transaction, and compatibility rules
+
+Reject source-derivable structure or signatures, task/change history, test inventories, temporary conclusions, stale statements, duplicate meanings, long procedures, low-value file lists, and facts already owned by a child detail document. File names, counts, and summaries remain only when needed for navigation or ownership.
+
+Critical-knowledge rule: a still-valid public or wire contract, cross-module constraint, non-obvious dependency, critical trap, durable decision, side effect, or safety/integrity rule must survive cleanup and capacity remediation. Never delete it merely to satisfy a byte check.
+
+### Cleanup Gate
+
+Before Update or Rebuild writes an existing target:
+
+1. Read the target and its resolving parent/child pointers first.
+2. Build a protected set of still-valid critical knowledge under the Value Gate.
+3. Match facts by semantic meaning, not wording; update an equivalent entry in place and merge synonymous entries.
+4. Remove stale, duplicate, parent-copied, source-derivable, and otherwise low-value material.
+5. Add only genuinely new durable knowledge that has no equivalent entry.
+6. Keep L0 and L1 as concise structural summaries and pointers; do not copy L2 interfaces, data flow, traps, decisions, or full rules into a parent.
+
+Append-only synchronization is prohibited. If protected knowledge cannot fit after safe cleanup, movement to the owning child, or an unambiguous semantic split, report the blocker instead of deleting knowledge.
+
+### Capacity and Sharding Invariants
+
+Use the canonical capacity classifier: exact raw UTF-8 bytes; L0 `root.prizm` limit 4096B; direct-child L1 limit 4096B; nested L2 limit 5120B. Bands are normal below 80%, warning from 80% to below 90%, strong warning from 90% through 100%, and error above 100%.
+
+- Natural content below 80% stays unchanged; do not pad it.
+- Warning-range content remains valid and is reported without failure.
+- A generated or rewritten target at 90% or above requires cleanup, movement, or a safe split. After automatic remediation, measure every affected parent and child: each must be within its hard limit and the operation targets 3277–3686B for L0/L1 or 4096–4607B for L2 (80% to below 90%), not one byte below the hard limit. A naturally concise result below 80% stays unpadded.
+- Any target still above its hard limit blocks completion. A warning must never downgrade another format or hard-limit error.
+- When L0 navigation cannot fit, use `MODULE_GROUPS`; never raise limits for project size.
+- When one L2 cannot safely retain a flat module's multiple stable behavior concerns, use the semantic L2 policy in the format specification. Preserve mirrored L2 paths for real source submodules.
+- Do not add a memory state machine, scoring system, project-size override, task-named or numbered shard, or a fourth documentation level.
+
 ### When to Use
 - First-time project documentation setup
 - Checking whether docs are fresh or valid
@@ -52,7 +100,7 @@ Bootstrap `.prizmkit/prizm-docs/` for the current project.
 
 Precondition: no `.prizmkit/prizm-docs/` directory exists, or user confirms overwrite.
 
-Read `${SKILL_DIR}/references/op-init.md` for detailed steps.
+Read `${SKILL_DIR}/references/op-init.md` for detailed steps. Apply the Value Gate before retaining every generated fact.
 
 ## Operation: Update
 
@@ -70,7 +118,7 @@ Use Update only when docs drifted outside the normal development loop, such as:
 
 During normal feature/bugfix/refactor work, do not use Update; use `/prizmkit-retrospective` to avoid duplicate writers and conflicting edits.
 
-Read `${SKILL_DIR}/references/op-update.md` for detailed steps.
+Read `${SKILL_DIR}/references/op-update.md` for detailed steps. Apply both the Value Gate and target-first Cleanup Gate to every written target.
 
 ## Operation: Status
 
@@ -86,7 +134,7 @@ Regenerate docs for a specific module from scratch.
 
 Precondition: `.prizmkit/prizm-docs/` exists and module path is valid.
 
-Read `${SKILL_DIR}/references/op-rebuild.md` for detailed steps.
+Read `${SKILL_DIR}/references/op-rebuild.md` for detailed steps. Rebuild from current source analysis without delete-first loss: preserve the target-first inventory, then apply both governing gates.
 
 ## Operation: Validate
 
@@ -104,12 +152,14 @@ Precondition: existing `docs/`, `docs/AI_CONTEXT/`, README, or architecture docs
 
 Steps:
 1. Discover existing docs: `docs/`, `docs/AI_CONTEXT/`, `README.md`, `ARCHITECTURE.md`, and structured documentation files.
-2. Extract project metadata, module descriptions, architecture patterns, rules, decisions, and dependencies.
-3. Map project-wide info to L0, module structure to L1, and behavioral details to L2.
-4. Convert prose to KEY: value format and strip markdown tables, diagrams, and decorative formatting.
-5. Generate `.prizmkit/prizm-docs/` using init structure seeded with extracted information.
-6. Validate migrated docs against format rules and size limits.
-7. Report files processed, generated `.prizm` files, and manual review items.
+2. Treat every extracted statement as a candidate, verify it against current source, and apply the Value Gate. Do not migrate source-derivable structure, task/history material, test inventories, temporary conclusions, stale statements, duplicate meanings, long procedures, or low-value file lists.
+3. Map project-wide summaries and pointers to L0, module structure and pointers to L1, and retained behavioral knowledge to L2. When a child L2 owns complete knowledge, keep only a concise parent summary and resolving pointer.
+4. Preserve source-mirrored L2 paths for real submodules. For a flat module that needs multiple stable behavior concerns to retain required knowledge within 5120B, apply the deterministic semantic-detail identity, ownership, `DETAILS` pointer, and ambiguity-blocking contract in the format specification.
+5. Convert retained content to KEY: value format and strip markdown tables, diagrams, decorative formatting, and procedural prose. Merge semantically equivalent source statements before writing.
+6. Generate `.prizmkit/prizm-docs/` using the Init structure seeded only with retained content; use `MODULE_GROUPS` when the L0 map cannot fit within 4096B.
+7. Run the canonical capacity classifier. Warning-only results remain successful; remediate strong-warning/error generated targets toward 3277–3686B for L0/L1 or 4096–4607B for L2 without deleting protected knowledge. An unresolved hard-limit, ambiguous or unstable concern identity, ownership problem, or slug collision is blocking; never resolve it with a task-named or numbered shard.
+8. Validate format, required semantic L2 fields, source-file ownership, pointer resolution, hierarchy, capacity, and critical-knowledge preservation.
+9. Report files processed, generated `.prizm` files, omitted low-value categories, capacity results, and manual decisions required.
 
 ## Recovery Backup Contract
 
@@ -125,13 +175,17 @@ If that path exists, use the lowest available suffix `.001`, `.002`, and so on,
 
 - `root.prizm` corrupted or invalid: create the byte-for-byte recovery backup above, then rebuild affected docs from source.
 - Broken pointers: create the missing `.prizm` file if the source module exists; remove the pointer if the source module was deleted.
-- Size limit exceeded: consolidate L0, move L1 implementation detail to L2, trim L2 derived detail.
+- Capacity warning or strong warning: report the exact classifier fields and clean/organize only when required by the governing capacity policy; automatic remediation targets 80% to below 90%.
+- Size limit exceeded: fail validation until Value/Cleanup filtering, deduplication, movement to the owning child, or an unambiguous semantic split brings the target within its hard limit; never delete protected knowledge or raise the limit.
 - No git history: fall back to filesystem timestamps for freshness checks and warn that accuracy is reduced.
 
 ## Key Protocols
 
 For detailed protocol specifications, read `assets/prizm-docs-format.md`:
 
+- Value and Cleanup Gates: Sections 1 and 7
+- Semantic L2 identity and ownership: Sections 3.2, 3.3, and 5
+- Capacity classification and remediation: Sections 2.1 and 7
 - Progressive Loading: Section 6.1
 - Update/repair protocol: Section 7
 - RULES hierarchy: Section 3.1

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

@@ -37,10 +37,16 @@ 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)
+- Value-gated retention: before keeping a candidate fact, ask `Could a future AI that lacks this fact make an incorrect modification?`; retain it only when yes, current, durable, non-obvious, and owned at this level
+- Protected critical knowledge: preserve still-valid public/wire contracts, cross-module constraints, non-obvious dependencies, traps, decisions with necessary rationale, likely-to-recur rejected alternatives and reasons, side effects, and security/data-integrity/concurrency/transaction/compatibility rules
+- Rejected low-value material: omit source-derivable structure, task/change history, test inventories, temporary conclusions, stale statements, duplicate meanings, long procedures, low-value file lists, and child-owned behavioral detail copied into parents
+- Cleanup in place: Update and Rebuild read existing targets, update equivalent meanings in place, merge synonyms, remove stale/duplicate/derivable/parent-copied content, and add only genuinely new durable knowledge
 - 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)
+- Size-enforced (hard limits per level prevent bloat; no project-size override)
+- Capacity-aware (raw UTF-8 byte bands drive warnings and safe remediation; critical knowledge is never deleted merely to meet a check)
+- Lazy L2 generation (detail docs created when durable knowledge exists, not as placeholders during init)
 - Rules hierarchy (root.prizm RULES are authoritative, module RULES supplement only)
+- Three levels only (semantic concern documents are L2, never a fourth level or memory state machine)
 
 ---
 
@@ -49,18 +55,20 @@ CORE_PRINCIPLES:
 ## 2.1 Progressive Loading Levels
 
 LEVELS:
-- L0: Root index. ALWAYS loaded at session start. Max 4KB.
+- L0: Root index. ALWAYS loaded at session start. Hard limit 4096 raw UTF-8 bytes.
   FILE: .prizmkit/prizm-docs/root.prizm
-  CONTAINS: project meta, module index with pointers, build commands, tech stack, top rules
+  CONTAINS: concise project meta, module summaries with pointers, build commands, tech stack, top rules
+  DOES NOT CONTAIN: child-owned interfaces, data flow, TRAPS, DECISIONS, full rules, or copied behavioral detail
 
-- L1: Structural index. Loaded ON DEMAND when AI works in a module area. Max 4KB each.
+- L1: Structural index. Loaded ON DEMAND when AI works in a module area. Hard limit 4096 raw UTF-8 bytes each.
   FILE: .prizmkit/prizm-docs/<mirrored-path>.prizm (mirrors source directory structure)
-  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)
+  CONTAINS: concise module responsibility, source submodule pointers, semantic detail pointers, key navigation files, dependency summary, critical rules summary (1-3 only)
+  DOES NOT CONTAIN: interface signatures, data flow, TRAPS, DECISIONS, full rules, or content already complete in L2
 
-- L2: Behavioral detail. Loaded when AI modifies files in that module OR needs deep understanding. Max 5KB each.
-  FILE: .prizmkit/prizm-docs/<mirrored-path>/<submodule>.prizm
-  CONTAINS: interface signatures, data flow, full rules, TRAPS, DECISIONS, domain-specific sections, rejected approaches
+- L2: Behavioral detail. Loaded when AI modifies files in that module OR needs deep understanding. Hard limit 5120 raw UTF-8 bytes each.
+  FILE: mirrored source submodule at .prizmkit/prizm-docs/<module>/<submodule>.prizm, or semantic concern at .prizmkit/prizm-docs/<module>/<concern-slug>.prizm for an eligible flat module
+  CONTAINS: Value-Gate-qualified public interfaces, data flow, rules, TRAPS, DECISIONS, domain-specific sections, and rejected approaches
+  IDENTITY: a real source submodule path takes precedence; a semantic concern remains an L2 document and never adds a level
 
 ## 2.2 Directory Layout
 
@@ -114,6 +122,33 @@ EXAMPLE (Python project):
 COMMIT: .prizmkit/prizm-docs/ MUST be committed to git alongside source code
 RATIONALE: .prizmkit/prizm-docs/ is shared project knowledge that all team members (human and AI) benefit from.
 
+## 2.4 Capacity Classification and Remediation
+
+MEASUREMENT: exact raw UTF-8 bytes; never characters, lines, rounded kilobytes, or locale-dependent encoding
+LEVEL_LIMITS:
+- L0: exact `.prizmkit/prizm-docs/root.prizm` -> 4096B
+- L1: direct `.prizm` child of `.prizmkit/prizm-docs/` -> 4096B
+- L2: nested `.prizm` document -> 5120B, including mirrored and semantic concern details
+BANDS:
+- normal: size * 100 < limit * 80
+- warning: size * 100 >= limit * 80 and size * 100 < limit * 90
+- strong-warning: size * 100 >= limit * 90 and size <= limit
+- error: size > limit
+TARGET_RANGE:
+- L0/L1 automatic remediation: 3277–3686B (80% to below 90%)
+- L2 automatic remediation: 4096–4607B (80% to below 90%)
+- Content naturally below 80% remains normal and is never padded to the target
+ACTION_ORDER:
+1. trim stale, derivable, procedural, historical, and low-value wording
+2. deduplicate repeated meanings and merge synonyms
+3. move child-owned behavior out of L0/L1 to a resolving child pointer
+4. semantic-split an eligible flat module's unrelated stable concerns into deterministic L2 documents
+PRESERVATION: establish protected critical knowledge before remediation; never remove still-valid contracts, constraints, dependencies, traps, decisions, side effects, or safety/integrity rules merely to reduce bytes
+COMPLETION: after automatic cleanup or split, measure every affected parent and child; each stays within its hard limit and remediation aims for the target range without padding naturally concise output; warning-range targets remain valid and visible; unresolved hard-limit errors fail validation
+REPORT_ORDER: non-normal entries sort by exact descending utilization using integer ratio comparison, then repository-relative path ascending for ties
+REPORT_FIELDS: path, level, current raw bytes, hard limit, utilization band, target range, and actionable trim, deduplicate, move-to-child, or semantic-split guidance
+EXIT: warning and strong-warning diagnostics alone do not fail Validate; hard-limit or format errors fail and cannot be downgraded
+
 ---
 
 # SECTION 3: DOCUMENT FORMAT SPECIFICATION
@@ -165,7 +200,7 @@ TEMPLATE:
   - REJECTED: <rejected approach + why>
 
 CONSTRAINTS:
-- Max 4KB (roughly 100 lines)
+- Hard limit 4096 raw UTF-8 bytes; project size never raises it
 - 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)
@@ -173,9 +208,9 @@ CONSTRAINTS:
 - No prose paragraphs
 - root.prizm RULES are AUTHORITATIVE: they override any conflicting L1/L2 RULES
 
-### MODULE_GROUPS (alternative to MODULE_INDEX for projects with 15+ modules)
+### MODULE_GROUPS (capacity-safe alternative to MODULE_INDEX)
 
-When MODULE_INDEX would exceed 15 entries, replace it with MODULE_GROUPS to stay within the 4KB limit. Group modules by functional domain:
+When MODULE_INDEX cannot retain the required concise module map within the L0 4096B hard limit, replace it with MODULE_GROUPS. More than 15 modules is a mandatory grouping trigger, but measured L0 capacity may require grouping earlier. Group modules by stable functional domain; never raise the L0 limit or add a project-size override:
 
   MODULE_GROUPS:
     <domain-name>:
@@ -186,6 +221,7 @@ When MODULE_INDEX would exceed 15 entries, replace it with MODULE_GROUPS to stay
 
 CONSTRAINTS for MODULE_GROUPS:
 - Exactly ONE of MODULE_INDEX or MODULE_GROUPS must be present in root.prizm (not both)
+- Grouping changes navigation shape only; L0 remains a concise summary/pointer map and the 4096B hard limit is unchanged
 - Domain names: lowercase, descriptive (e.g., api, frontend, infrastructure, shared, data)
 - 3-8 domains is the ideal range
 - Each module appears in exactly one domain
@@ -212,7 +248,11 @@ TEMPLATE:
   RESPONSIBILITY: <one-line>
 
   SUBDIRS:
-  - <name>/: <one-line description>. -> .prizmkit/prizm-docs/<child-path>.prizm
+  - <name>/: <one-line source-submodule summary>. -> .prizmkit/prizm-docs/<child-path>.prizm
+
+  DETAILS:
+  - <concern-slug>: <one-line stable behavior summary> -> .prizmkit/prizm-docs/<module>/<concern-slug>.prizm
+  (DETAILS is present only for semantic concern L2 documents in a flat module. SUBDIRS owns real source-submodule pointers.)
 
   KEY_FILES:
   - <filename>: <role/purpose>
@@ -226,13 +266,16 @@ TEMPLATE:
   - MUST: <1-3 most critical module-specific rules only — full list in L2>
 
 CONSTRAINTS:
-- Max 4KB
+- Hard limit 4096 raw UTF-8 bytes; project size never raises it
 - 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)
+- DOES NOT CONTAIN: INTERFACES, DATA_FLOW, TRAPS, DECISIONS, full RULES, or copied L2 behavioral content
 - 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 child doc exists
-- KEY_FILES lists only the most important files (max 10-15)
+- SUBDIRS entries point only to mirrored real source-submodule details; each pointer must resolve
+- DETAILS entries use exactly `- <concern-slug>: <one-line stable behavior summary> -> .prizmkit/prizm-docs/<module>/<concern-slug>.prizm`; each pointer must resolve to one semantic L2 whose MODULE and CONCERN match
+- A real source-submodule path takes precedence over the same semantic slug; ambiguity or collision blocks semantic detail creation
+- KEY_FILES lists only navigation-critical files that pass the Value Gate (max 10-15, often fewer); never use it as a file inventory
+- If a child L2 contains the complete rule, interface, trap, decision, or data flow, L1 keeps only the shortest useful summary and pointer
 - RULES may only SUPPLEMENT root.prizm RULES with module-specific exceptions, never contradict them
 
 TRAPS_FORMAT_REFERENCE (spec-only — do NOT include this block in generated .prizm files):
@@ -245,63 +288,79 @@ TRAPS_FORMAT_REFERENCE (spec-only — do NOT include this block in generated .pr
 
 ## 3.3 L2: detail.prizm (Behavioral Detail)
 
-TEMPLATE:
+COMMON_TEMPLATE:
 
-  MODULE: <source-path>
-  FILES: <comma-separated list of all files>
-  RESPONSIBILITY: <one-line>
+  MODULE: <source-submodule path for mirrored detail, or flat parent module path for semantic detail>
+  CONCERN: <stable concern identity> | SLUG: <concern-slug>
+  (CONCERN is required only for semantic concern details and prohibited on mirrored source-submodule details.)
+  FILES: <comma-separated repository-relative source files owned by this detail>
+  RESPONSIBILITY: <one-line durable behavior boundary>
 
   INTERFACES:
-  - <function/method signature>: <what it does>
+  - <non-obvious public/exported signature or wire contract>: <modification consequence>
 
   DATA_FLOW:
-  - <numbered step describing how data moves through this module>
+  - <numbered non-obvious step, side effect, transaction, or cross-boundary flow>
 
   <DOMAIN-SPECIFIC SECTIONS>
-  (AI generates these based on what the module does. Examples below.)
+  (AI generates these only when entries pass the Value Gate.)
 
   KEY_FILES:
-  - <filename>: <detailed description, line count, complexity notes>
+  - <repository-relative source file>: <why a future modification needs this navigation pointer>
 
   DEPENDENCIES:
-  - uses: <external lib>: <why/how used>
-  - imports: <internal module>: <which interfaces consumed>
+  - uses: <external dependency>: <non-obvious contract or constraint>
+  - imports: <internal module>: <consumed public contract or coupling>
 
   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>
+  - [CRITICAL|HIGH|LOW] <incorrect-looking-safe change or non-obvious side effect> | FIX: <correct approach>
 
   DECISIONS:
-  - <decision made within this module> — <rationale>
-  - REJECTED: <approach that was tried/considered and abandoned + why>
+  - <durable decision> — <only the rationale needed to preserve it>
+  - REJECTED: <alternative future sessions are likely to propose again> — <why it remains rejected>
+
+REQUIRED_FIELDS:
+- Mirrored source-submodule L2: MODULE, FILES, RESPONSIBILITY, INTERFACES, KEY_FILES, DEPENDENCIES, TRAPS. DATA_FLOW, RULES, DECISIONS, and domain-specific sections are present only when facts pass the Value Gate, preserving existing mirrored-document compatibility.
+- Semantic concern L2 complete terminal shape: MODULE, CONCERN, FILES, RESPONSIBILITY, INTERFACES, DATA_FLOW, KEY_FILES, DEPENDENCIES, RULES, TRAPS, DECISIONS
+- In a semantic concern L2, if a required behavioral section has no fact that passes the Value Gate, render the section as `<SECTION>: none`; never invent filler to populate it
+- DOMAIN-SPECIFIC sections are optional and contain only Value-Gate-qualified facts
+
+SEMANTIC_CONCERN_TERMINAL_SHAPE:
+- Eligibility: a flat source module has multiple stable behavior concerns and required protected knowledge cannot fit one L2 within 5120B after Value/Cleanup filtering
+- Path: `.prizmkit/prizm-docs/<module>/<concern-slug>.prizm`; it is L2, not a new documentation level
+- MODULE: exact flat source module path
+- CONCERN: stable source-evidenced product/domain behavior name plus its deterministic slug
+- FILES: non-empty exhaustive list of repository-relative source files owned by this concern
+- Ownership: sibling semantic concerns have explicit non-overlapping FILES; unclear or overlapping ownership blocks automatic creation
+- Parent: exactly one L1 DETAILS entry using the Section 3.2 grammar resolves to the semantic file; the slug, path, MODULE, and CONCERN must agree
+- Mirrored precedence: if a real source submodule maps to the same path, the mirrored submodule owns it and semantic creation is blocked pending a different unambiguous concern identity
+- Terminal outcomes: write the complete required shape, or report the ambiguity/collision/ownership blocker and required manual decision; never emit a partial semantic file
 
 DOMAIN_SPECIFIC_SECTION_EXAMPLES:
-- For state machines: STATES, TRIGGERS, TRANSITIONS
+- For state transition logic: STATES, TRIGGERS, TRANSITIONS
 - For API handlers: ENDPOINTS, REQUEST_FORMAT, RESPONSE_FORMAT, ERROR_CODES
 - For data stores: TABLES, QUERIES, INDEXES, CACHE_KEYS
 - For config modules: CONFIG_KEYS, ENV_VARS, DEFAULTS
 - For UI components: PROPS, EVENTS, SLOTS, STYLES
 
 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 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.
+- Hard limit 5120 raw UTF-8 bytes; project size never raises it
+- L2 is the BEHAVIORAL DETAIL — it answers only non-obvious "how it works, what can go wrong, what was decided" questions that pass the Value Gate
+- INTERFACES lists only non-obvious PUBLIC/EXPORTED or wire contracts; omit source-derivable signatures as `INTERFACES: none`
+- DATA_FLOW records only flows or side effects whose absence could cause an incorrect modification
+- RULES contains the full retained module-specific rules list; L1 has at most a short summary
+- DECISIONS records durable rationale only; keep it current by updating equivalent decisions in place and removing stale ones
+- 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 severity: CRITICAL = data loss/security/financial/crash, HIGH = functional failure/silent error, LOW = naming/minor quality (see TRAPS_FORMAT_REFERENCE in Section 3.2)
-- REJECTED entries prevent AI from re-proposing failed approaches
-- FILES lists all files, not just key ones
+- REJECTED entries exist only for alternatives likely to recur and include the durable reason
+- FILES is an ownership list, not a low-value repository inventory; mirrored details list files in their source boundary and semantic details list their explicitly owned files
+- KEY_FILES contains only navigation-critical files and never line counts, complexity inventories, or derivable descriptions
 - RULES may only SUPPLEMENT root.prizm RULES with module-specific exceptions, never contradict them
 
 ## 3.4 Metadata Policy
@@ -349,8 +408,40 @@ app/services/                 .prizmkit/prizm-docs/app/services.prizm
 FOR any source file at path P:
   1. Walk up directory tree to find the first ancestor D where .prizmkit/prizm-docs/<D>.prizm exists
   2. That file is the L1 doc for this source file
-  3. If P is inside a subdirectory S of D, check if .prizmkit/prizm-docs/<D>/<S>.prizm exists for L2
-  4. If no .prizm doc found, the module is undocumented (may need retrospective after development or prizmkit-prizm-docs Update for out-of-band repair)
+  3. If P is inside a source subdirectory S of D, check `.prizmkit/prizm-docs/<D>/<S>.prizm` first; mirrored source-submodule identity has precedence
+  4. For a flat module, resolve each L1 DETAILS pointer and select the one semantic L2 whose FILES ownership contains P
+  5. If semantic FILES ownership is absent, overlaps, or disagrees with its parent pointer, report ambiguity instead of guessing
+  6. If no .prizm doc found, the module is undocumented (may need retrospective after development or prizmkit-prizm-docs Update for out-of-band repair)
+
+## 5.4 Deterministic Semantic Concern Identity
+
+ELIGIBILITY:
+- The source module is flat: the concern is not already a real source submodule that can use mirrored identity
+- Current source proves multiple stable product/domain behavior boundaries
+- Required protected knowledge cannot fit one 5120B L2 after the Value Gate, Cleanup Gate, deduplication, and concise wording
+
+SLUG_ALGORITHM:
+1. Choose one concise stable product/domain behavior concern name evidenced by current source responsibility; task, feature, bug, session, workflow, branch, temporary initiative, and file-count labels are invalid identities.
+2. Normalize the identity with Unicode NFKC.
+3. Apply Unicode lowercase.
+4. Replace each maximal run of characters that is neither a Unicode letter nor a Unicode decimal digit with one ASCII hyphen.
+5. Trim leading and trailing hyphens. The result must be non-empty, lowercase kebab-case and map unambiguously to exactly one stable concern.
+6. Compare the result with every sibling semantic CONCERN slug, sibling DETAILS entry, and mirrored source-submodule path before creating a file.
+
+OWNERSHIP_RULES:
+- FILES uses normalized repository-relative source paths and is non-empty.
+- Each owned file belongs to exactly one sibling semantic concern. Do not silently duplicate or overlap ownership.
+- Source files outside the flat module, unclear multi-concern files, unstable behavior boundaries, empty slugs, and one slug mapping to multiple concern meanings require a manual ownership/identity decision.
+
+COLLISION_OUTCOME:
+- If normalized identities collide, a semantic slug collides with a mirrored source-submodule path, or concern/FILES ownership is ambiguous, do not create or rename a detail arbitrarily.
+- Report the candidate identities, colliding path or overlapping files, and the manual decision required.
+- Never use task IDs, numeric suffixes (`-2`, `-003`), timestamps, branch names, or silent overlapping documents to resolve the collision.
+
+POINTER_RESOLUTION:
+- Semantic path = `.prizmkit/prizm-docs/<module>/<concern-slug>.prizm`.
+- Parent L1 contains exactly one matching DETAILS entry; the target exists; target MODULE equals `<module>`; target CONCERN slug equals `<concern-slug>`; target FILES satisfies ownership rules.
+- A semantic concern remains at L2. Do not create L3, a fourth level, a memory state machine, or a scoring system.
 
 ---
 
@@ -365,6 +456,7 @@ ON_SESSION_START:
 ON_TASK_RECEIVED:
   IF task references specific file or directory:
     LOAD: L1 for the containing module (structural index: files, deps, key rules)
+    RESOLVE: a mirrored SUBDIRS pointer first; for a flat module, use the one DETAILS pointer whose semantic L2 FILES ownership contains the source file
   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"):
@@ -399,7 +491,7 @@ 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.
+L2 docs can be up to 5120 raw UTF-8 bytes. 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:
@@ -421,13 +513,46 @@ EXAMPLES:
 WHEN: During normal development, run `/prizmkit-retrospective` before commits when structure, interfaces, dependencies, behavior, or durable project knowledge changed. Use `prizmkit-prizm-docs Update` only for out-of-band repair/resync after docs drifted outside the normal development loop.
 GOAL: Keep prizm docs synchronized with source code without creating multiple competing docs writers.
 
-## 7.2 Update Decision Logic
-
-SUMMARY: For normal development, `/prizmkit-retrospective` gets changed files → maps modules → classifies (A/D/M/R) → updates docs bottom-up (L2→L1→L0) → skips if no structural or durable-knowledge impact → enforces size limits → stages. For out-of-band drift, `prizmkit-prizm-docs Update` runs the same repair shape after confirming the drift source.
+## 7.2 Value Gate
+
+QUESTION: Before retaining a candidate fact, ask `Could a future AI that lacks this fact make an incorrect modification?`
+PASS: yes, and the fact is current, durable, non-obvious, actionable for a future modification, and placed at the lowest owning level
+KEEP:
+- non-obvious public/exported interfaces and wire contracts
+- cross-module constraints and non-obvious dependencies
+- traps, side effects, and failure boundaries
+- durable decisions with necessary rationale
+- rejected alternatives likely to recur, with the reason they remain rejected
+- security, data-integrity, concurrency, transaction, and compatibility rules
+REJECT:
+- structure/signatures directly and safely derivable from source
+- task/change/session history and test inventories
+- temporary investigation conclusions and future plans
+- stale statements, duplicated meanings, and synonyms already represented
+- long procedures, generic advice, low-value file lists, line counts, and complexity inventories
+- behavioral content already complete in a child L2
+APPLIES: Init, Update, Rebuild, and Migrate evaluate every candidate through this same gate
+
+## 7.3 Cleanup Gate
+
+TRIGGER: Before Update or Rebuild writes an existing target
+STEPS:
+1. Read the current target and its parent/child pointers; never use append-only synchronization or delete-first regeneration.
+2. Verify every current fact against source and build the protected set of still-valid contracts, constraints, dependencies, traps, decisions, side effects, and safety/integrity rules.
+3. Match candidate and existing facts by semantic meaning. Update one equivalent entry in place and merge synonyms instead of appending alternate wording.
+4. Remove stale, duplicate, source-derivable, low-value, and parent-copied material.
+5. Add only genuinely new durable facts that pass the Value Gate and have no equivalent entry.
+6. Reconcile bottom-up: L2 owns behavior; L1 owns concise structure and SUBDIRS/DETAILS pointers; L0 owns the concise project map.
+7. Measure raw UTF-8 capacity. If automatic remediation is required, follow Section 2.4 and preserve the protected set.
+BLOCK: If protected knowledge cannot fit after safe movement or an unambiguous semantic split, report the blocker and required manual decision; never delete it for capacity.
+
+## 7.4 Update Decision Logic
+
+SUMMARY: For normal development, `/prizmkit-retrospective` gets changed files → maps modules → classifies (A/D/M/R) → applies value-aware bottom-up reconciliation (L2→L1→L0) → skips if no structural or durable-knowledge impact → enforces capacity. For out-of-band drift, `prizmkit-prizm-docs Update` applies the governing Value and Cleanup Gates after confirming the drift source.
 
 DETAILED_STEPS: → ${SKILL_DIR}/references/op-update.md
 
-## 7.3 Auxiliary Metadata Policy
+## 7.5 Auxiliary Metadata Policy
 
 NEVER: Add CHANGELOG sections or changelog.prizm during doc sync.
 NEVER: Add UPDATED/date/time fields to .prizm files.
@@ -444,6 +569,9 @@ 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 indexes structure, L2 details behavior)
+NEVER: Copy complete L2 interfaces, data flow, TRAPS, DECISIONS, or full RULES into L0/L1; keep a concise parent summary and resolving pointer
+NEVER: Retain a candidate fact that fails the future-incorrect-modification Value Gate
+NEVER: Append synonymous entries instead of updating one semantic meaning in place
 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)
@@ -454,6 +582,10 @@ 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)
+NEVER: Delete still-valid critical knowledge merely to cross a capacity threshold
+NEVER: Raise 4096B/4096B/5120B hard limits for project size or trim only to one byte below a limit when automatic remediation is required
+NEVER: Create task-named, numbered, timestamped, colliding, ambiguous, or silently overlapping semantic concern documents
+NEVER: Add L3, a fourth documentation level, a memory state machine, or a fact scoring system
 NEVER: TRAPS entries without severity prefix ([CRITICAL], [HIGH], or [LOW])
 
 ---
@@ -468,7 +600,7 @@ PRECONDITION: No .prizmkit/prizm-docs/ directory exists (or user confirms overwr
 INPUT: Project root directory
 OUTPUT: .prizmkit/prizm-docs/ with root.prizm and L1 docs for discovered modules
 
-SUMMARY: Detect project type → discover modules (MODULE_DISCOVERY_CRITERIA) → create mirrored directory structure → generate root.prizm (L0) → generate L1 docs → skip L2 (lazy) → configure hook → validate → report.
+SUMMARY: Detect project type → discover modules (MODULE_DISCOVERY_CRITERIA) → apply Value Gate to every candidate → create mirrored directory structure → generate concise root.prizm (L0) and L1 pointer indexes → skip placeholder L2 (lazy) → configure hook → validate format/capacity/pointers → report.
 
 DETAILED_STEPS: → ${SKILL_DIR}/references/op-init.md
 
@@ -485,7 +617,9 @@ A directory does NOT qualify if ALL of the following are true:
 - 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.
+HIERARCHY RULE: if directory X lives inside top-level module M, X is a sub-module of M — NOT a separate top-level module. Its durable behavioral detail uses the mirrored L2 path. Semantic concern identity is considered only for a flat module under Section 5.4.
+
+CAPACITY RULE: use MODULE_GROUPS whenever MODULE_INDEX cannot fit L0 within 4096B. Do not change hard limits for project size. Init does not create semantic or mirrored L2 placeholders; later Update/Rebuild/Migrate may create complete L2 documents when durable knowledge and unambiguous identity exist.
 
 EXCLUDE: .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .prizmkit/, .prizmkit/prizm-docs/, dev-pipeline/
 
@@ -499,8 +633,9 @@ ON_MODIFY trigger:
     AI reads the relevant L2 sections.
   ELSE:
     AI reads the target source files as fallback and proceeds with the modification.
-- After the change, `/prizmkit-retrospective` creates L2 if the changed files contain meaningful interfaces, data flow, traps, or decisions worth preserving.
-- This keeps initialization lightweight while still capturing L2 depth when real change context exists.
+- After the change, `/prizmkit-retrospective` creates L2 only when candidate interfaces, data flow, traps, or decisions pass the Value Gate.
+- Real source submodules retain mirrored paths. A flat-module semantic detail follows Sections 3.3 and 5.4 and blocks on ambiguous concern identity, slug collision, or overlapping ownership.
+- This keeps initialization lightweight while still capturing L2 depth when real durable context exists.
 
 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):