prizmkit 1.1.155 → 1.1.156

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

@@ -1,51 +1,93 @@
-# Knowledge Injection — Detailed Steps (2a–2c)
+# Knowledge Injection — Exact-Scope Value and Cleanup Steps
 
-**2a.** Gather context from the **actual project files changed outside `.prizmkit/`**:
+## 1. Establish candidate fact authority
 
-- `git diff HEAD -- . ':(exclude).prizmkit/**'` — the source of truth for eligible project changes
-- Current Main-Agent context for the requirement — reuse it rather than rereading artifacts by default
-- Targeted unchanged source, interfaces, callers, dependents, or tests only when an eligible diff raises a concrete ambiguity
-- The affected Prizm docs only as update targets and existing-knowledge checks, never as changed project input
+Gather candidate knowledge only from actual project changes in the exact validated non-`.prizmkit/` input paths:
 
-Do not scan or mine generated records for retrospective knowledge. Caller metadata and existing Prizm docs may describe transient or generated material; they must not create a retrospective fact independently of an observed change in the exact non-`.prizmkit/` project paths supplied as input.
+- `git diff HEAD -- <exact validated change_paths>` using literal pathspecs is the source of truth for eligible changes; never broaden the diff to `.` or use repository-wide status/discovery to add paths.
+- Current source content at those exact paths may clarify the diff.
+- Narrowly required unchanged source context (an interface, direct caller, direct dependent, or test) may be read only when an eligible diff raises a concrete ambiguity that cannot be resolved from the changed path itself.
+- Existing affected Prizm docs may be read only as update targets, pointer maps, protected-current-knowledge evidence, and duplicate/staleness checks.
 
-**2b.** Extract knowledge from what was **observed in code**, not invented:
+Generated artifacts, caller metadata, and existing Prizm text must not independently establish a candidate fact, expand `change_paths`, or turn an unrelated document into a target. `change_summary` is supporting context only. Reuse current Main-Agent source understanding when available, but do not treat lifecycle artifacts, completion notes, task IDs, or prior narrative as source evidence.
 
-**TRAPS** (highest priority) — things that look safe but break:
-- Minimal format: `- [SEVERITY] <description> | FIX: <approach>`
-- Full format: `- [SEVERITY] <description> | FIX: <approach> | REF: <hash> | STALE_IF: <glob>`
-- Source: actual bugs hit, surprising behavior discovered in code, non-obvious coupling
+## 2. Apply the future-incorrect-modification Value Gate
 
-**TRAPS severity classification**:
-- `[CRITICAL]`: data loss, security, financial error, system crash
-- `[HIGH]`: functional failure, silent error, interface incompatibility
-- `[LOW]`: misleading naming, non-intuitive API, minor performance issue
+For every candidate, ask exactly:
 
-When writing TRAPS:
-- Severity prefix is MANDATORY (e.g., `[CRITICAL]`, `[HIGH]`, `[LOW]`)
-- OPTIONAL: append `| REF: <7-char-hash>` when you know the relevant commit (for traceability)
-- OPTIONAL: append `| STALE_IF: <glob>` when the TRAP is tightly coupled to specific files (for auto-expiry detection)
+> Could a future AI that lacks this fact make an incorrect modification?
 
-**Consuming [REVIEW] markers** (from staleness check 1g):
-- If you encounter a TRAP prefixed with `[REVIEW]` (e.g., `[REVIEW][HIGH] ...`), verify whether the trap is still valid by checking the current code. If still valid: remove the `[REVIEW]` prefix, keeping the severity. If no longer relevant: delete the TRAP entry.
+Retain it only when the answer is yes and current eligible source proves that it is durable, non-obvious, actionable for future modification, and owned by the target level.
 
-**RULES** — conventions established or constraints discovered:
-- Format: `- MUST/NEVER/PREFER: <rule>`
-- Source: patterns that proved necessary during implementation
+High-value candidate classes include:
 
-**DECISIONS** — key design choices that affect future development:
-- Format: `- <what was decided> — <rationale>`
-- Source: non-obvious design choices, interface conventions, cross-module contracts
-- Only record decisions that a future AI session would benefit from knowing
-- Do NOT record obvious implementation details that can be derived by reading the code
+- non-obvious public interfaces and wire contracts;
+- data flow, side effects, transactions, integrity boundaries, or surprising coupling;
+- cross-module constraints and non-obvious dependencies;
+- security, data-integrity, concurrency, transaction, and compatibility rules;
+- actual traps, race conditions, failure modes, or unsafe-looking alternatives;
+- architectural rules or durable decisions with rationale;
+- observable behavior boundaries whose omission could cause a regression;
+- rejected alternatives that future sessions are likely to propose again.
 
-**QUALITY GATE**: Every item must answer: "If a new AI session reads only `.prizmkit/prizm-docs/` and this entry, does it gain actionable understanding?" If not, discard. Do not record trivially observable code patterns — the AI can read the code directly.
+For a likely-to-recur rejected alternative, retain the alternative and its reason only when current eligible source establishes both. Do not retain a rejected option merely as design history.
 
-**MEMORY HYGIENE GATE**: Before writing any `.prizmkit/prizm-docs/` entry, remove transient caller metadata. Never write CHANGELOG sections/files, UPDATED/date metadata, internal execution IDs, branch names, absolute worktree paths, or generated artifact paths. Write only durable product/domain facts established by the supplied project changes.
+Reject candidates that are source-derivable structure or signatures, transient implementation conclusions, historical task/change narrative, duplicate meanings, stale/conflicting statements, test inventories, coverage lists, routine file inventories, long procedures, low-value wording, or behavior already complete in a more specific child.
 
-**2c.** Inject into the correct `.prizmkit/prizm-docs/` file:
-- Module-level TRAPS/RULES/DECISIONS → the affected detail `.prizm` file. If the target detail document does not exist, create it from the detail-document generation template before injecting knowledge. These sections belong in detail documentation, not the module index.
-- Project-level RULES/PATTERNS → `root.prizm` (respect the current format — MODULE_INDEX or MODULE_GROUPS — do not convert between them during injection)
-- Cross-module concerns spanning 2+ modules → `root.prizm` CROSS_CUTTING section
+## 3. Extract only observed durable knowledge
 
-**RULE**: Only add genuinely new information. Never duplicate existing entries. Never rewrite entire files.
+### TRAPS
+
+Use `- [SEVERITY] <description> | FIX: <approach>` and include only source-established non-obvious failure risks.
+
+- `[CRITICAL]`: data loss, security failure, financial error, or crash.
+- `[HIGH]`: functional failure, silent error, data-integrity risk, or interface incompatibility.
+- `[LOW]`: misleading naming, non-intuitive API, or minor quality/performance risk that still passes the Value Gate.
+
+Optional `REF` or `STALE_IF` metadata is allowed only when it is durable and source-relevant. For an affected `[REVIEW]` trap, remove the marker only when exact eligible source proves it still valid; delete it only when that source proves it obsolete. Lack of narrow evidence is not permission to delete it.
+
+### RULES
+
+Use `- MUST/NEVER/PREFER: <rule>`. Keep only constraints that a future modification must obey and that eligible source establishes.
+
+### DECISIONS and rejected alternatives
+
+Use `- <decision> — <durable rationale>` or `- REJECTED: <likely recurring alternative> — <why it remains rejected>`. Do not record obvious implementation choices or historical deliberation.
+
+### Interfaces and behavior
+
+Retain only non-obvious public/wire contracts, data flow, side effects, dependencies, and observable boundaries whose absence could cause an incorrect modification. Omit signatures and structure that direct source reading makes obvious.
+
+## 4. Reconcile the current target before insertion
+
+For every bounded affected target:
+
+1. Read its current content and the necessary resolving direct parent/child pointers.
+2. Build the protected set defined by the structural sync procedure before removing anything.
+3. Match by semantic meaning, not exact wording.
+4. Update the canonical entry in place when source changes an equivalent or conflicting fact; merge synonyms into one concise meaning.
+5. Remove only source-proven obsolete facts plus stale, derivable, duplicate, low-value, or parent-copied material outside the protected set.
+6. Add a candidate only when it passes the Value Gate and no equivalent canonical entry remains.
+7. Preserve stable section and entry order; do not reorder unchanged entries or append alternate wording merely to make a diff.
+
+Append-only injection is prohibited. Cleanup remains limited to the exact affected targets and their necessary direct parent summaries/pointers; do not opportunistically clean siblings.
+
+## 5. Place knowledge at the lowest owning level
+
+- Module behavioral details, `INTERFACES`, `DATA_FLOW`, `TRAPS`, complete `RULES`, `DECISIONS`, and rejected alternatives belong in the most specific mirrored or deterministic semantic detail.
+- A real source-submodule boundary uses mirrored detail identity first.
+- A flat module uses a semantic concern detail only when the structural procedure proves stable deterministic identity, explicit non-overlapping source-file ownership, capacity need, complete terminal shape, and a resolving direct-module `DETAILS` pointer.
+- A direct module index keeps concise structure, navigation, critical summaries, and pointers; it does not copy complete child behavior.
+- The root project map keeps only concise navigation and genuinely project-wide/cross-module summaries. An exact eligible change must establish the project-wide fact; existing root text cannot create one.
+
+When one eligible change truly spans multiple affected modules, place complete knowledge in the lowest owning details and retain only the shortest useful cross-module summary/pointers at root. Do not infer cross-module scope from unrelated existing documentation.
+
+## 6. Hand candidate results to capacity preflight
+
+Do not write directly from extraction. Hand the complete cleaned candidate, protected set, exact target identity, and affected direct pointers to `structural-sync-steps.md` for raw UTF-8 size measurement, minimum safe cleanup or semantic split, bottom-up replacement, re-read validation, and safe restoration.
+
+If no candidate survives the Value Gate and structural reconciliation produces no byte change, return a truthful `NO_DOC_CHANGE`. A repeated run over identical source and inputs must preserve byte-identical documentation and must not create duplicate, reorder-only, or synonym-only churn.
+
+## 7. Enforce memory hygiene
+
+Before final candidate validation, remove CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, and `.prizmkit/specs` or `.prizmkit/dev-pipeline` artifact paths. Never trade protected durable product/domain knowledge for traceability noise.

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

@@ -1,90 +1,153 @@
-# Structural Sync — Detailed Steps
+# Structural Sync — Capacity-Safe Detailed Steps
 
 ## 1. Validate supplied changed files
 
 Use only the caller-supplied `change_paths`. Normalize each repository-relative path, reject paths outside the checkout or under `.prizmkit/`, and verify its current added/modified/deleted/renamed state with exact pathspecs.
 
-Do not expand the path set through repository-wide status or diff discovery. If the validated list is empty, structural sync is not needed.
+Do not expand the path set through repository-wide status or diff discovery. Never run an unconditional repository-wide documentation rewrite. If the validated list is empty, structural sync is not needed.
 
-## 2. Map files to modules
+## 2. Map exact changes to a bounded target set
 
-Read `.prizmkit/prizm-docs/root.prizm` and map each changed file to MODULE_INDEX or MODULE_GROUPS entries.
+Read `.prizmkit/prizm-docs/root.prizm` only as the project map, then map each exact changed path through its MODULE_INDEX or MODULE_GROUPS pointer to the most specific existing documentation owner.
 
-If a changed source file maps to no module, evaluate whether its directory qualifies as a new module:
+The writable set contains only:
 
-- Contains source files forming a logical unit
-- Contains entry/config/interface files
-- Contains qualifying submodules
-- Is referenced by multiple modules as a dependency
+- the most specific detail targets that own eligible changed paths;
+- their necessary direct parent summary or pointer at each affected level;
+- a new detail target only when the eligible source change proves meaningful durable behavior and deterministic identity;
+- root only when module structure or its resolving module/group pointer changes.
 
-## 3. Classify changes
+Affected docs may be read to reconcile current content and resolve pointers, but they cannot independently add source facts or pull sibling docs into the writable set. Do not clean unrelated targets merely because they are stale or near a limit.
 
-- `A` added → add to KEY_FILES and check for new public interfaces
-- `D` deleted → remove from KEY_FILES and update file counts
-- `M` modified → check public interfaces, dependencies, data flow, and durable traps/decisions
-- `R` renamed → update path references
+If a changed source path maps to no module, evaluate only that path and narrowly required directory context to determine whether its directory is a real logical module with entry/config/interface files or cross-module dependency use. Do not perform a repository scan to manufacture a module.
 
-## 4. Decide whether sync is needed
+## 3. Classify eligible structural changes
 
-Skip structural sync when changes are limited to:
+- `A` added: update navigation only when the file passes the Value Gate; check source-established public/wire contracts.
+- `D` deleted: remove stale owned navigation and source-invalidated knowledge.
+- `M` modified: check non-obvious public/wire interfaces, dependencies, data flow, behavior, traps, rules, and decisions.
+- `R` renamed: update only implicated ownership and resolving paths.
 
-- comments, whitespace, or formatting
-- internal implementation details with no interface, dependency, data-flow, or module mapping impact
-- test-only changes that reveal no durable boundaries, traps, interface constraints, behavior rules, or regression knowledge
+Skip structural writes for comments, whitespace, formatting, internal implementation detail with no durable contract/behavior impact, and test-only changes that reveal no durable boundary. Do not skip a bug or test change when its exact source evidence changes durable behavior or constraints.
 
-Do not skip automatically just because the task is a bug fix or test change. Run the relevant part of retrospective when the change affects structure, interfaces, dependencies, observable behavior, or durable knowledge.
+## 4. Select the most specific detail identity
 
-## 5. Update affected docs bottom-up
+### Mirrored source identity
 
-### Detail documentation
+When identities compete, mirrored source identity takes precedence.
 
-If a relevant detail document exists, update only sections affected by supplied changed files in that module.
+A real source submodule uses its mirrored detail path. Mirrored source identity takes precedence over a semantic concern with the same path or meaning. Update an existing mirrored detail before considering a semantic split.
 
-If detail documentation does not exist and the supplied changes include Added or Modified source files with meaningful logic, create it with:
+A new mirrored detail uses these required sections:
 
 ```text
 MODULE
 FILES
 RESPONSIBILITY
+INTERFACES
 KEY_FILES
 DEPENDENCIES
-INTERFACES
 TRAPS
 ```
 
-Add DATA_FLOW, RULES, or DECISIONS only when the changed files provide durable information for those sections. Populate from the diff files and targeted source reads, not from an unbounded full-module rescan.
+Add `DATA_FLOW`, `RULES`, `DECISIONS`, rejected alternatives, or domain sections only for facts that pass the Value Gate.
+
+### Deterministic semantic concern identity
+
+For a flat source module, create a semantic concern detail only when current eligible source proves multiple stable product/domain behavior concerns and protected durable knowledge cannot fit one 5120B detail after safe cleanup. A semantic concern is not another documentation level.
+
+Derive one deterministic concern slug:
+
+1. Choose a concise stable product/domain concern name from current source responsibility; task, change, file-count, or temporary initiative labels are invalid.
+2. Normalize the name 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/trailing hyphens and require one non-empty, unambiguous lowercase kebab-case result.
+6. Compare it with sibling semantic concerns, sibling `DETAILS` entries, and mirrored submodule paths. Task IDs, numeric suffixes, timestamps, and branch names are prohibited as collision workarounds.
+
+The detail path is `.prizmkit/prizm-docs/<module>/<concern-slug>.prizm`. It has `MODULE`, `CONCERN`, `FILES`, `RESPONSIBILITY`, `INTERFACES`, `DATA_FLOW`, `KEY_FILES`, `DEPENDENCIES`, `RULES`, `TRAPS`, and `DECISIONS`; use `<SECTION>: none` rather than invented filler when a required behavioral section has no qualifying fact.
+
+`FILES` is a non-empty exhaustive normalized source-file ownership list for the concern. Sibling semantic details require explicit non-overlapping `FILES` ownership. The direct module parent has exactly one `DETAILS` pointer:
+
+```text
+- <concern-slug>: <concise stable behavior summary> -> .prizmkit/prizm-docs/<module>/<concern-slug>.prizm
+```
+
+The pointer path, target `MODULE`, normalized `CONCERN` slug, and `FILES` ownership must agree. Mirrored source identity takes precedence; ambiguity, collision, or overlapping ownership blocks the split. Never add a suffix or partial semantic document to guess around it.
+
+## 5. Preflight every target before replacement
+
+For each target in the bounded writable set:
+
+1. Read current content and resolving parent/child pointers. For an existing target, preserve its exact pre-write bytes; for a new target, record that no pre-write file exists.
+2. Measure the current target before replacement using exact raw UTF-8 bytes, never characters, lines, rounded kilobytes, or locale-dependent encoding.
+3. Establish a protected set before cleanup. It includes every still-valid public or wire contract, CRITICAL/HIGH trap, data-flow or data-integrity constraint, security/concurrency/transaction/compatibility rule, cross-module rule, non-obvious dependency, side effect, and durable decision with necessary rationale.
+4. Build the complete candidate result before replacement. Match existing and candidate facts by meaning; update the canonical entry in place, merge synonyms, remove equivalent, stale, derivable, conflicting, duplicate, or parent-copied material, and never append another version of the same knowledge.
+5. Measure the candidate as exact raw UTF-8 bytes and classify both current and candidate against the target's level.
+
+Capacity limits and bands:
+
+- Exact root project map: hard limit 4096B.
+- Direct module index: hard limit 4096B.
+- Nested mirrored or semantic detail: hard limit 5120B.
+- 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`.
+
+When the current or candidate reaches at least 80%, perform the minimum safe cleanup or semantic split before final replacement:
+
+1. trim stale, source-derivable, procedural, historical, transient, and low-value wording;
+2. merge synonymous facts and remove duplicate meanings;
+3. move child-owned behavior from the root/module index into the existing or newly justified resolving detail;
+4. if one detail still cannot retain protected durable knowledge within 5120B, use the deterministic semantic split only when its stable identity and non-overlapping ownership are unambiguous.
+
+Aim for 3277–3686B for a root/module index and 4096–4607B for a detail document, preserving approximately 10% headroom. Do not pad naturally concise output and do not trim merely to one byte below a hard limit. A post-remediation warning-range result is valid; do not force a needless split when the minimum safe cleanup establishes the target range.
+
+Never remove protected knowledge solely to pass capacity validation. If it cannot fit after concise wording, safe movement, or an unambiguous split, do not replace that target.
+
+## 6. Write bottom-up
 
-### Module index
+Prepare all candidates before the first replacement and write only after each candidate passes its local format, identity, protected-set, and capacity preflight.
 
-Update FILES count, KEY_FILES, SUBDIRS, and DEPENDENCIES when module-level structure changes.
+1. Create or update the most specific detail first.
+2. Re-read and validate that detail before modifying its parent.
+3. Update the direct module index only as concise summaries and resolving pointers, using `SUBDIRS` or `DETAILS` as applicable.
+4. Update the root project map last and only when module structure or its concise resolving pointer changed.
 
-Module indexes do not contain INTERFACES, DATA_FLOW, TRAPS, or DECISIONS; those belong in detail documentation.
+Complete `INTERFACES`, `DATA_FLOW`, `TRAPS`, `DECISIONS`, and full RULES owned by a child must not be copied into the module index or root project map. Parent docs retain the shortest useful summary and pointer. Preserve any root `PROJECT_BRIEF:` line because it is managed separately.
 
-### Root project map
+Before each replacement, compare candidate bytes with current bytes. A byte-identical candidate is not written, reordered, or reported as an update.
 
-Update MODULE_INDEX or MODULE_GROUPS only when module structure changed. Preserve any `PROJECT_BRIEF:` line because it is managed separately.
+## 7. Re-read and validate the actual final files
 
-## 6. New module handling
+After every write:
 
-If a new directory qualifies as a module and matches no existing module:
+1. Re-read the actual bytes from disk and recompute exact raw UTF-8 size.
+2. Reapply the 4096B/4096B/5120B hard limit and 80%/90% band formulas.
+3. Validate required KEY/value format and memory hygiene.
+4. Resolve every affected `MODULE_INDEX`, `MODULE_GROUPS`, `SUBDIRS`, and `DETAILS` pointer; validate both each changed target and its affected direct parent/child.
+5. Confirm semantic `MODULE`, `CONCERN`, path, slug, and `FILES` ownership agree and do not collide or overlap.
+6. Review only the targeted documentation diff for duplicate meanings, copied child behavior, unstable reorder, and unintended paths.
 
-1. Create its module index immediately.
-2. Add it to MODULE_INDEX or MODULE_GROUPS.
-3. Create detail documentation only when the supplied changes include meaningful Added or Modified source files for the module.
+If any post-write check fails, restore every replaced target from its preserved exact pre-write bytes and remove any invalid newly created target. Re-read the restored affected set and ensure no invalid oversized final document remains. Restoration is a bounded file operation; never use Git reset, checkout, or stash.
 
-## 7. Size limits
+## 8. Capacity blocker evidence
 
-- Root project map > 4KB → consolidate MODULE_INDEX or convert to MODULE_GROUPS when module count is high
-- Module index > 4KB → trim KEY_FILES descriptions and keep RULES concise
-- Detail document > 5KB → remove derived detail or stale entries; keep durable knowledge only
+When no safe compression or stable split exists, stop with no invalid candidate left in place. The blocked result's `reason` must include:
 
-## 8. TRAPS staleness check
+- exact target path;
+- measured current bytes and/or candidate bytes, hard limit, and band;
+- protected knowledge that prevented trimming;
+- why attempted cleanup, movement, or identity/ownership checks could not establish a safe split;
+- a concrete recommended split boundary that a future manual decision can evaluate.
 
-Run only when a detail document's TRAPS section has more than 10 entries.
+Its `validation` contains only checks actually attempted. Its `documentation_paths` follows the result schema and never invents a change. `RETRO_COMPLETE` is prohibited after any unresolved capacity, pointer, format, or restoration check.
 
-Process at most 5 oldest TRAPS per detail document:
+## 9. Bounded TRAPS staleness check
 
-1. If a TRAP has `STALE_IF:` and matched files no longer exist, delete the TRAP.
-2. If a TRAP has `REF:` and the referenced file is gone or the commit is older than the review horizon, mark it `[REVIEW]` for the next knowledge pass.
+Run only for an affected detail target whose `TRAPS` section has more than 10 entries. Process at most five oldest traps:
 
-This bounds context cost and prevents unbounded trap accumulation.
+1. Delete a trap only when eligible source evidence proves it stale, including a `STALE_IF` path that no longer exists within the exact scope.
+2. If a `REF` cannot be validated from eligible evidence, retain the trap or mark it `[REVIEW]`; do not mine repository history or unrelated source to decide.
+3. Never remove a still-valid CRITICAL/HIGH trap merely for capacity.

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

@@ -6,6 +6,8 @@ from __future__ import annotations
 import re
 import subprocess
 import sys
+from dataclasses import dataclass
+from functools import cmp_to_key
 from pathlib import Path, PurePosixPath
 
 DOCS_ROOT = Path(".prizmkit/prizm-docs")
@@ -124,24 +126,129 @@ def read_check_content(file_path: str, mode: str) -> tuple[bytes, str] | None:
     return raw, raw.decode("utf-8", errors="replace")
 
 
+@dataclass(frozen=True)
+class CapacityDiagnostic:
+    file_path: str
+    level: str
+    size: int
+    limit: int
+    band: str
+    target_low: int
+    target_high: int
+    actions: str
+
+
+def is_root_doc(file_path: str) -> bool:
+    return PurePosixPath(file_path) == PurePosixPath(ROOT_PRIZM.as_posix())
+
+
 def is_l1_doc(file_path: str) -> bool:
     parent = PurePosixPath(file_path).parent.as_posix()
     return parent == DOCS_ROOT.as_posix()
 
 
 def size_limit(file_path: str) -> tuple[int, str, str]:
-    if file_path.endswith("root.prizm"):
-        return 4096, "L0", "Consolidate MODULE_INDEX, keep top-5 RULES."
+    if is_root_doc(file_path):
+        return (
+            4096,
+            "L0",
+            "trim: lower-priority global wording; "
+            "deduplicate: repeated RULES or module summaries; "
+            "move-to-child: module detail into an L1 document; "
+            "semantic-split: broad module groups into focused L1 documents",
+        )
     if is_l1_doc(file_path):
-        return 3072, "L1", "Move implementation details to L2."
-    return 5120, "L2", "Remove stale or trivially derivable entries."
+        return (
+            4096,
+            "L1",
+            "trim: low-value module summaries; "
+            "deduplicate: repeated interfaces, rules, or traps; "
+            "move-to-child: implementation detail into an L2 document; "
+            "semantic-split: distinct submodules into focused L2 documents",
+        )
+    return (
+        5120,
+        "L2",
+        "trim: stale or derivable detail; "
+        "deduplicate: repeated implementation notes; "
+        "move-to-child: one coherent detail set into a focused child document; "
+        "semantic-split: unrelated responsibilities into focused L2 documents",
+    )
+
+
+def ceil_percent(limit: int, percent: int) -> int:
+    return (limit * percent + 99) // 100
+
+
+def capacity_band(size: int, limit: int) -> str:
+    if size > limit:
+        return "error"
+    if size * 100 >= limit * 90:
+        return "strong-warning"
+    if size * 100 >= limit * 80:
+        return "warning"
+    return "normal"
+
+
+def capacity_diagnostic(file_path: str, size: int) -> CapacityDiagnostic | None:
+    limit, level, actions = size_limit(file_path)
+    band = capacity_band(size, limit)
+    if band == "normal":
+        return None
+    return CapacityDiagnostic(
+        file_path=file_path,
+        level=level,
+        size=size,
+        limit=limit,
+        band=band,
+        target_low=ceil_percent(limit, 80),
+        target_high=ceil_percent(limit, 90) - 1,
+        actions=actions,
+    )
+
+
+def compare_capacity(left: CapacityDiagnostic, right: CapacityDiagnostic) -> int:
+    left_ratio = left.size * right.limit
+    right_ratio = right.size * left.limit
+    if left_ratio > right_ratio:
+        return -1
+    if left_ratio < right_ratio:
+        return 1
+    if left.file_path < right.file_path:
+        return -1
+    if left.file_path > right.file_path:
+        return 1
+    return 0
+
+
+def utilization_percent(size: int, limit: int) -> str:
+    hundredths = (size * 10000) // limit
+    return f"{hundredths // 100}.{hundredths % 100:02d}%"
+
+
+def emit_capacity(diagnostic: CapacityDiagnostic) -> None:
+    severity = {
+        "warning": "WARNING",
+        "strong-warning": "STRONG WARNING",
+        "error": "ERROR",
+    }[diagnostic.band]
+    print(
+        f"{severity}: {diagnostic.file_path} capacity "
+        f"level={diagnostic.level} bytes={diagnostic.size}B limit={diagnostic.limit}B "
+        f"utilization={diagnostic.size}/{diagnostic.limit} "
+        f"({utilization_percent(diagnostic.size, diagnostic.limit)}) "
+        f"band={diagnostic.band} "
+        f"target={diagnostic.target_low}-{diagnostic.target_high}B (80% to <90%) "
+        f"actions={diagnostic.actions}",
+        file=sys.stderr,
+    )
 
 
 def contains_root_field(text: str, field: str) -> bool:
     return re.search(rf"^{re.escape(field)}:", text, re.MULTILINE) is not None
 
 
-def validate_file(file_path: str, raw: bytes, text: str) -> int:
+def validate_file(file_path: str, raw: bytes, text: str) -> tuple[int, CapacityDiagnostic | None]:
     errors = 0
 
     if re.search(r"^#{1,6} ", text, re.MULTILINE):
@@ -195,13 +302,11 @@ def validate_file(file_path: str, raw: bytes, text: str) -> int:
         emit_error(file_path, "contains branch names. Describe durable product/domain context instead.")
         errors += 1
 
-    limit, level, hint = size_limit(file_path)
-    size = len(raw)
-    if size > limit:
-        emit_error(file_path, f"exceeds {level} limit ({size}B > {limit}B). {hint}")
+    diagnostic = capacity_diagnostic(file_path, len(raw))
+    if diagnostic is not None and diagnostic.band == "error":
         errors += 1
 
-    if file_path.endswith("root.prizm"):
+    if is_root_doc(file_path):
         for field in ["PRIZM_VERSION", "PROJECT", "LANG", "RULES"]:
             if not contains_root_field(text, field):
                 emit_error(file_path, f"missing required field {field}:")
@@ -210,7 +315,7 @@ def validate_file(file_path: str, raw: bytes, text: str) -> int:
             emit_error(file_path, "missing required field MODULE_INDEX: or MODULE_GROUPS:")
             errors += 1
 
-    return errors
+    return errors, diagnostic
 
 
 def main(argv: list[str]) -> int:
@@ -223,12 +328,19 @@ def main(argv: list[str]) -> int:
         return 0
 
     errors = 0
+    capacity_entries: list[CapacityDiagnostic] = []
     for file_path in collect_files(mode):
         content = read_check_content(file_path, mode)
         if content is None:
             continue
         raw, text = content
-        errors += validate_file(file_path, raw, text)
+        file_errors, diagnostic = validate_file(file_path, raw, text)
+        errors += file_errors
+        if diagnostic is not None:
+            capacity_entries.append(diagnostic)
+
+    for diagnostic in sorted(capacity_entries, key=cmp_to_key(compare_capacity)):
+        emit_capacity(diagnostic)
 
     if errors > 0:
         print(f"PrizmKit: {errors} format error(s) in .prizm files. Fix before committing.", file=sys.stderr)

package/package.json

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