prizmkit 1.1.154 → 1.1.156

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):

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

@@ -9,24 +9,23 @@ STEPS:
 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 .prizmkit/prizm-docs/<M>/<X>.prizm, never to .prizmkit/prizm-docs/<X>.prizm.
+   - SUB-MODULES: directories INSIDE a top-level module that qualify. Record them as source structure in the parent L1; if durable L2 is created later, its path mirrors the sub-module.
+   - HIERARCHY RULE: directory X inside top-level module M maps to `.prizmkit/prizm-docs/<M>/<X>.prizm`, never to `.prizmkit/prizm-docs/<X>.prizm`.
    - Exclude .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .prizmkit/, .prizmkit/prizm-docs/, dev-pipeline/. If total module count > 30, ask user for include/exclude patterns.
-3. Create .prizmkit/prizm-docs/ directory structure mirroring the source tree exactly. For each top-level module M that has sub-modules, create the subdirectory .prizmkit/prizm-docs/<M>/.
-4. Generate root.prizm (L0) with PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY, MODULE_INDEX with multi-level entries as needed for efficient navigation (constrained by 4KB limit), RULES extracted from user-facing main memory files (AGENTS.md, CLAUDE.md, CODEBUDDY.md), README, and linter configs. Do not extract RULES from AGENTS.private.md, CLAUDE.private.md, or CODEBUDDY.private.md because those files contain PrizmKit framework protocol text. Include PATTERNS and CROSS_CUTTING (cross-module concerns spanning 2+ modules). Set PRIZM_VERSION: 4. Max 4KB. No CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths — git tracks history.
-   - If `.prizmkit/plans/project-brief.md` exists: add `PROJECT_BRIEF: .prizmkit/plans/project-brief.md` to root.prizm (generated by prizmkit-init). If not present, skip — prizmkit-init Phase 7 will add it later.
-   - If module count > 15: use MODULE_GROUPS format instead of MODULE_INDEX — group modules by functional domain (3-8 domains, inferred from directory structure and module responsibilities). See prizm-docs-format.md for MODULE_GROUPS format.
-   - For each module entry, auto-generate 3-6 keyword tags by scanning the module's key source files for: exported function/class names, imported library names, domain-specific terms in file/directory names. Add tags in square brackets after the module name (e.g., `- auth [login, session, jwt]: ...`). Tags are optional but recommended for projects with 10+ modules.
-5. Generate L1 .prizm files (structural index only) for ALL modules, each at its correct mirrored path:
-   - Top-level module M → write .prizmkit/prizm-docs/<M>.prizm (include SUBDIRS section with pointers to sub-module docs)
-   - Sub-module S inside M → write .prizmkit/prizm-docs/<M>/<S>.prizm
-   Each L1 includes MODULE (full relative path), FILES count, RESPONSIBILITY, SUBDIRS with pointers, KEY_FILES (5-10 most important), DEPENDENCIES (imports, imported-by, external), RULES (1-3 most critical only). L1 does NOT include INTERFACES, DATA_FLOW, TRAPS, or DECISIONS (those are L2, generated lazily). Max 4KB each.
-6. Skip L2 docs during init — L2 docs are created after real context exists, not as placeholders. During implementation, if relevant L2 is missing, the implementing skill reads target source files as fallback and proceeds. `/prizmkit-retrospective` creates or updates L2 after the change only when durable structure, behavior, dependencies, interfaces, or TRAPS exist. Explicit `/prizmkit-prizm-docs` repair/rebuild may also create L2 when fixing out-of-band doc drift.
-7. Configure UserPromptSubmit hook in platform settings per ${SKILL_DIR}/assets/prizm-docs-format.md Section 11.
-8. Validate all generated docs: size limits (L0 <= 4KB, L1 <= 4KB), pointer resolution (every -> reference resolves), no circular dependencies, KEY: value format compliance, no anti-patterns (prose, code blocks, markdown headers), L1 does not contain INTERFACES/DATA_FLOW/TRAPS/DECISIONS, no CHANGELOG sections/files, no UPDATED/date metadata, no feature/bug/refactor/task/session/run/pipeline/workflow IDs, no branch names, no absolute worktree paths, and no `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths.
-9. Report summary: modules discovered, L1 docs generated, files excluded, warnings.
-
-OUTPUT: List of generated files, module count, and validation results.
+3. Apply the Value Gate from SKILL.md and the format specification to every metadata, rule, pattern, dependency, file, and summary candidate. Keep navigational structure only when needed to locate ownership. Reject source-derivable signatures, history, test inventories, temporary conclusions, stale/duplicate meanings, procedures, and low-value file lists.
+4. Create `.prizmkit/prizm-docs/` and only the mirrored directories needed by documents that will exist. Do not create placeholder detail files.
+5. Generate `root.prizm` (L0) with concise PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY, navigation pointers, and only Value-Gate-qualified global RULES/PATTERNS/CROSS_CUTTING facts. Set `PRIZM_VERSION: 4`. Keep L0 a summary/pointer map; never copy child interfaces, data flow, traps, decisions, or full rules. 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.
+   - If `.prizmkit/plans/project-brief.md` exists, add `PROJECT_BRIEF: .prizmkit/plans/project-brief.md`; otherwise skip it.
+   - Use MODULE_GROUPS whenever MODULE_INDEX cannot fit the required map within 4096B. More than 15 modules is a mandatory grouping trigger. Use 3-8 stable functional domains; never raise the L0 limit for project size.
+   - Generate only high-value intent-matching keyword tags; do not copy exported names or imports mechanically when they add no navigation value.
+6. Generate one direct-child L1 structural index for each discovered top-level source module at `.prizmkit/prizm-docs/<module>.prizm`. Include concise MODULE, FILES navigation summary, RESPONSIBILITY, SUBDIRS, KEY_FILES, DEPENDENCIES, and at most three critical RULES. A SUBDIRS arrow is emitted only when its mirrored L2 exists, so every arrow resolves. Do not include INTERFACES, DATA_FLOW, TRAPS, DECISIONS, full rules, or a low-value file inventory.
+7. Skip all L2 creation during Init. Init has no behavioral context requiring placeholder mirrored or semantic details. Later `/prizmkit-retrospective`, Update, Rebuild, or Migrate may create a complete L2 only when facts pass the Value Gate. Real source submodules use mirrored identity. Flat-module semantic details use the deterministic CONCERN/FILES/DETAILS contract and block on unstable boundaries, overlapping ownership, empty slugs, or collisions; task-named and numbered shards are prohibited.
+8. Measure every generated file with the canonical raw UTF-8 capacity classifier: L0/L1 4096B, L2 5120B. Report warning-range files without failing. If a generated L0/L1 reaches 90% or above, clean or reorganize it toward 3277-3686B without deleting protected knowledge. Any unresolved hard-limit error blocks Init.
+9. Configure UserPromptSubmit hook in platform settings per `${SKILL_DIR}/assets/prizm-docs-format.md` Section 11.
+10. Validate all generated docs: Value Gate, size/band reporting, pointer resolution, no circular dependencies, KEY: value format, parent-summary boundary, no anti-patterns, and no prohibited metadata. Warning-only capacity results pass; hard-limit or format errors fail.
+11. Report modules discovered, L1 docs generated, files/categories omitted by the Value Gate, files excluded, capacity diagnostics in descending utilization, and any required manual decisions.
+
+OUTPUT: List of generated files, module count, Value-Gate omissions by category, capacity results, and validation results.
 
 ## Post-Init Behavior
 
@@ -35,7 +34,8 @@ After initialization, L2 docs are created only when durable context exists:
 ON_MODIFY behavior:
 - When an AI modifies a file in sub-module S within module M and `.prizmkit/prizm-docs/<M>/<S>.prizm` does not exist, the implementation reads the source files in S as fallback context and proceeds.
 - Do not block implementation only to create a placeholder L2 doc.
-- After the change, run `/prizmkit-retrospective` when structure, interfaces, dependencies, behavior, or durable TRAPS changed; retrospective creates or updates L2 then.
+- After the change, run `/prizmkit-retrospective` when structure, interfaces, dependencies, behavior, or durable TRAPS changed; retrospective creates or updates L2 then only for facts that pass the future-incorrect-modification Value Gate.
+- Preserve the mirrored source-submodule path. For a flat module with multiple stable concerns under repeated L2 capacity pressure, use deterministic semantic L2 identity and explicit non-overlapping FILES ownership; block ambiguous creation.
 
 ON_DEEP_READ behavior:
 - When an AI needs deep understanding but L2 is absent, read the relevant source files directly as fallback context.

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

@@ -5,11 +5,17 @@ Regenerate docs for a specific module from scratch. Requires a module path argum
 PRECONDITION: .prizmkit/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. Validate regenerated docs against size limits and format rules.
-
-OUTPUT: Regenerated doc summary with before/after comparison.
+1. Read the existing module L1, every pointed L2, and the relevant root entry before changing anything. Do not delete first. Snapshot semantic meanings, pointers, paths, and a protected set of still-valid public/wire contracts, cross-module constraints, non-obvious dependencies, traps, decisions with necessary rationale, likely-to-recur rejected alternatives, side effects, and security/data-integrity/concurrency/transaction/compatibility rules.
+2. Re-scan the current module source for files, public/wire behavior, dependencies, flows, stable concerns, and real source submodules. Treat each observation and each old entry as a candidate under the future-incorrect-modification Value Gate; source-derived, transient, historical, test-inventory, stale, duplicate, procedural, and low-value material is omitted.
+3. Reconstruct the module map in memory, then apply the Cleanup Gate to each existing target: update equivalent meanings in place, merge synonyms, remove stale/derivable/parent-copied content, and add only genuinely new durable knowledge. Append-only growth and delete-first regeneration are prohibited.
+4. Reconcile detail identity:
+   - real source submodules preserve mirrored `.prizmkit/prizm-docs/<module>/<submodule>.prizm` paths
+   - a flat module may gain deterministic semantic `.prizmkit/prizm-docs/<module>/<concern-slug>.prizm` L2 documents only when multiple stable behavior concerns cannot retain protected knowledge in one 5120B L2 after cleanup
+   - each semantic L2 has the complete CONCERN terminal shape, explicit non-empty/non-overlapping FILES ownership, and one resolving L1 DETAILS pointer
+   - unstable concern boundaries, empty normalized slugs, sibling or mirrored-path collisions, and overlapping ownership block arbitrary creation; report the required manual identity/ownership decision instead of task names or numeric suffixes
+5. Rewrite the existing L1 as a concise structural summary and pointer index only. Preserve SUBDIRS pointers for real source-submodule L2 and DETAILS pointers for semantic L2. Never copy child interfaces, data flow, traps, decisions, or full rules into L1. Remove an obsolete detail only after all still-valid protected knowledge has been preserved in its current owner and its source/concern identity no longer exists.
+6. Update only the equivalent root MODULE_INDEX or MODULE_GROUPS entry in place. Preserve concise pointer-only parent behavior, existing project-wide knowledge, and `PROJECT_BRIEF:`. Use MODULE_GROUPS whenever MODULE_INDEX cannot fit within the unchanged 4096B L0 limit; more than 15 modules is a mandatory grouping trigger, not permission for a larger root.
+7. Measure exact raw UTF-8 bytes using hard limits L0/L1 4096B and L2 5120B. Report warning-range results without failing. For any rewritten target at 90% or above, trim low-value material, deduplicate, move child-owned behavior, or safely semantic-split toward 3277-3686B for L0/L1 or 4096-4607B for L2. Never delete protected knowledge for size; unresolved hard-limit or unsafe-split pressure blocks Rebuild.
+8. Validate Value/Cleanup compliance, complete semantic fields, FILES ownership, pointer resolution, hierarchy, parent-summary boundaries, capacity, and format. Warning-only results pass; hard-limit or format errors fail.
+
+OUTPUT: Rebuilt-document before/after summary listing entries updated in place, merged, removed, added, and protected; sorted capacity diagnostics; semantic identity/ownership decisions; and any blocking ambiguity.

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

@@ -5,10 +5,17 @@ Check freshness of all .prizm docs.
 PRECONDITION: .prizmkit/prizm-docs/ exists with root.prizm.
 
 STEPS:
-1. Get last git modification time of root.prizm via `git log -1 --format="%ai" -- .prizmkit/prizm-docs/root.prizm`.
+1. Get the last git modification time of `root.prizm` via `git log -1 --format="%ai" -- .prizmkit/prizm-docs/root.prizm`. If history is unavailable, use filesystem timestamps and report reduced freshness accuracy.
 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.
+3. For each L1/L2 document, compare its git modification time with the latest source modification in its mapped module. Resolve real source submodules through SUBDIRS and flat semantic concerns through DETAILS plus their authoritative FILES ownership.
+4. Classify freshness as FRESH (doc updated after source), STALE (source newer), or MISSING (durable module/concern exists without a document). An absent placeholder with no Value-Gate-qualified knowledge is not MISSING.
+5. Measure every `.prizm` file from its actual raw UTF-8 bytes and classify the exact path: only `.prizmkit/prizm-docs/root.prizm` is L0 with 4096B; direct children are L1 with 4096B; nested mirrored or semantic documents are L2 with 5120B. Never infer capacity from project size, line count, character count, or filename alone.
+6. Classify capacity as normal (<80%), warning (80% to <90%), strong-warning (90% through 100%), or error (>100%). Sort every non-normal capacity entry by exact descending utilization using integer ratio comparison, then repository-relative path ascending for ties.
+7. For each non-normal entry report `DOC_PATH | LEVEL | BYTES | LIMIT | BAND | TARGET_RANGE | ACTIONS`. Target is 3277-3686B for L0/L1 or 4096-4607B for L2. ACTIONS must include concrete level-appropriate trim, deduplicate, move-to-child, and semantic-split guidance consistent with the canonical F-063 classifier.
+8. Status is read-only. A warning or strong warning is not "oversize" and does not force a split. An error is over the hard limit. Recommend semantic split only for an eligible flat module with multiple stable concerns after Value/Cleanup filtering; otherwise recommend the applicable non-destructive actions or manual decision.
+9. When inspecting representative or named documents, use their current measured bytes and detected level. Do not special-case paths or repeat stale measurements in guidance.
 
-OUTPUT: Freshness report table with columns: DOC_PATH | LEVEL | STATUS | PRIZM_LAST_MOD | SOURCE_LAST_MOD.
+OUTPUT:
+- Freshness table: `DOC_PATH | LEVEL | STATUS | PRIZM_LAST_MOD | SOURCE_LAST_MOD`.
+- Capacity table: non-normal entries in descending utilization with `DOC_PATH | LEVEL | BYTES | LIMIT | BAND | TARGET_RANGE | ACTIONS`.
+- Summary counts for normal, warning, strong-warning, and error. Status reports errors but does not mutate documents.