prizmkit 1.1.155 → 1.1.159

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/skills/prizmkit-workflow/SKILL.md

@@ -96,10 +96,12 @@ Expected transitions:
 | `prizmkit-plan` | `PLAN_READY` plus valid `spec.md`/`plan.md` | `prizmkit-implement` |
 | `prizmkit-implement` | `IMPLEMENTED` plus completed task markers | `prizmkit-code-review` |
 | `prizmkit-code-review` | `PASS` plus valid `review-report.md` | `prizmkit-test` |
-| `prizmkit-test` | `TEST_PASS` plus consistent report/result pair | `prizmkit-retrospective` |
+| `prizmkit-test` | `TEST_PASS` plus a consistent report/result pair with `production_changed=false` | `prizmkit-retrospective` |
 | `prizmkit-retrospective` | `RETRO_COMPLETE` plus an artifact whose `outcome` and `result` agree | `prizmkit-committer` |
 | `prizmkit-committer` | `COMMITTED` after explicit interactive confirmation | end |
 
+Before accepting a Test transition, require `production_changed` to be a boolean and agree between `test-report.md` and `test-result.json`. A passing result with `production_changed=true` follows the bounded production-repair route below and is not final Test authority for Retrospective.
+
 Before invoking `prizmkit-retrospective`, derive the exact changed project paths outside `.prizmkit/` and pass them as `change_paths` with a concise `change_summary`. Do not ask that atomic Skill to infer scope from this composite's state or earlier artifacts.
 
 `TEST_NOT_APPLICABLE` is not a valid lifecycle success. Lightweight changes must execute deterministic verification and return `TEST_PASS`.
@@ -132,6 +134,28 @@ prizmkit-implement
 
 The Main-Agent review skill owns its internal review repairs and its internal ten-round limit before returning its terminal result. The outer workflow repair counter is separate.
 
+### Passing Test with Production Repair
+
+A `TEST_PASS` whose consistent final artifacts report `production_changed=true` proves the Test stage repaired production code after prior Code Review. It does not authorize Retrospective or Committer.
+
+```text
+TEST_PASS + production_changed=true + repair_round < 3
+  → preserve the Test artifacts as repair evidence
+  → increment the outer repair round
+  → invalidate prior final Code Review/Test completion in coordinator state
+  → clear stale stage_result before re-entry
+  → invoke prizmkit-code-review review_scope=delta
+  → require a fresh prizmkit-test result
+
+fresh TEST_PASS + production_changed=false
+  → prizmkit-retrospective
+
+TEST_PASS + production_changed=true + repair_round >= 3
+  → WORKFLOW_BLOCKED
+```
+
+On re-entry, retain only stages that remain authoritative before Code Review in `completed_stages`, set `repair_scope=production`, and set the next/resume entry to delta Code Review without inventing a new atomic result. Repeated Test production repairs consume the same existing outer repair budget; they do not create an unbounded success loop.
+
 ### Test Non-Pass
 
 `prizmkit-test` already performs bounded test construction, execution-failure repair, mandatory Main-Agent review, and optional independent review before returning. The composite consumes its terminal artifacts without recreating those loops.
@@ -187,9 +211,17 @@ The internal `prizmkit-code-review` limit of ten completed review rounds remains
 
 The composite reaches `/prizmkit-committer operation=interactive-commit` but must not silently create a Git commit.
 
-The composite must validate all prior stage artifacts, derive exact non-`.prizmkit/` change paths for the retrospective input, and validate its result. It then invokes the committer with the same `artifact_dir`, exact `evidence_paths`, caller-state paths in `excluded_paths`, and `operation=interactive-commit`. The committer inspects the supplied final change, presents the exact commit, waits for confirmation, and creates it only after approval.
+The composite must validate all prior stage artifacts, derive exact non-`.prizmkit/` change paths for the retrospective input, and validate its result. For interactive commit it then assembles one exact `intended_paths` manifest from:
+
+- final validated requirement paths outside default support namespaces;
+- exact `.prizmkit/prizm-docs/**` paths listed by a consistent `RETRO_COMPLETE` + `DOCS_UPDATED` result;
+- exact support paths explicitly owned by the spec/plan, separately labeled in the preview, covered by the support validation below, and subject to the user's confirmation of that exact manifest.
+
+For each explicit support path, select and execute its applicable semantic contract before invoking Committer: instruction files require readable structure, resolvable project references, consistency with the exact requirement and applicable project conventions, and secret scanning; lockfiles require parse/schema checks plus owning-installer or deterministic-regeneration parity; any other support class requires an exact project-native semantic validator named by the spec/plan. User confirmation alone is not support validation. If no applicable validator exists or evidence is non-passing, block support admission. Pass one exact `support_validation_evidence` record per admitted support path, including its path, contract, completed validation, `PASS` result, and exact evidence path.
+
+All other `.prizmkit/**`, generated support, transient, installed, secret, unknown, or unrelated paths remain excluded or blocking. Invoke the committer with the same `artifact_dir`, exact `evidence_paths`, caller-state paths in `excluded_paths`, the exact `intended_paths`, conditional one-to-one `support_validation_evidence`, and `operation=interactive-commit`. The committer validates the manifest, presents the exact commit, waits for confirmation, and creates it only after approval.
 
-External headless orchestration supplies explicit evidence to `operation=prepare-runtime-commit`, maps `COMMIT_REQUEST_READY` to its own pending state, and lets Python Runtime validate and execute the request. Remote publication remains separate.
+External headless orchestration supplies explicit evidence to `operation=prepare-runtime-commit`, maps `COMMIT_REQUEST_READY` to its own pending state, and lets Python Runtime validate and execute the request. Preparation mode preserves the existing automated contract: the complete `.prizmkit/**` tree remains outside Runtime `intended_paths`. Remote publication remains separate.
 
 ## Automatic Handoff and Manual Fallback
 

package/bundled/skills/prizmkit-workflow/references/workflow-state-protocol.md

@@ -96,7 +96,8 @@ implementation IMPLEMENTED       → status=completed,  stage_result=IMPLEMENTED
 implementation repair/block      → status=failed,     stage_result=IMPLEMENT_REPAIR or IMPLEMENT_BLOCKED
 review-report PASS               → status=completed,  stage_result=REVIEW_PASS
 review-report NEEDS_FIXES        → status=failed,     stage_result=REVIEW_NEEDS_FIXES
-test-result TEST_PASS            → status=completed,  stage_result=TEST_PASS
+test-result TEST_PASS, production_changed=false → status=completed, stage_result=TEST_PASS
+test-result TEST_PASS, production_changed=true  → bounded re-entry; clear stale stage_result before pending delta Code Review
 test-result TEST_NEEDS_FIXES     → status=failed,     stage_result=TEST_NEEDS_FIXES
 test-result TEST_BLOCKED         → status=failed,     stage_result=TEST_BLOCKED
 retrospective outcome=RETRO_COMPLETE, result=DOCS_UPDATED   → status=completed, stage_result=RETRO_COMPLETE
@@ -109,7 +110,20 @@ commit blocked                   → status=failed,     stage_result=COMMIT_BLOC
 
 `DOCS_UPDATED` and `NO_DOC_CHANGE` remain retrospective artifact `result` values. The workflow `stage_result` is the retrospective stage result `RETRO_COMPLETE`.
 
-`TEST_PASS` requires both `test-report.md` and a consistent `test-result.json`. No manifest, attestation, evidence package, or test-internal checkpoint is part of this contract.
+`TEST_PASS` requires both `test-report.md` and a consistent `test-result.json`. Their `production_changed` diagnostics must agree. Only `production_changed=false` is final Test authority for Retrospective. No manifest, attestation, evidence package, or test-internal checkpoint is part of this contract.
+
+## Passing Production-Repair Re-entry
+
+When consistent Test artifacts return `TEST_PASS` with `production_changed=true`, the atomic Test result remains truthful but the prior Code Review no longer covers the final production state. If `repair_round < 3`, the coordinator:
+
+1. preserves the Test artifacts as repair evidence;
+2. increments `repair_round`;
+3. removes invalidated `code-review` and `test` entries from `completed_stages` while preserving authoritative predecessors;
+4. sets `stage=code-review`, `status=pending`, and `stage_result=null` so no stale result survives re-entry;
+5. sets `repair_scope=production`, `next_stage=code-review`, and `resume_from=prizmkit-code-review`;
+6. invokes delta Code Review and then a fresh Test.
+
+A fresh `TEST_PASS` with `production_changed=false` may complete Test and advance. Another production-changing pass repeats this route within the same outer budget. When `repair_round >= 3`, set `WORKFLOW_BLOCKED` without Retrospective or commit progression.
 
 ## Non-Pass Results and Routing Boundary
 
@@ -144,11 +158,16 @@ Any outer repair or continuation policy is independently owned by the caller and
 Interactive execution:
 
 ```text
-committer previews intended files and message
+coordinator assembles exact intended_paths from final requirement paths
+  + exact validated Retrospective .prizmkit/prizm-docs paths
+  + separately labeled explicitly owned support paths with one-to-one passing support_validation_evidence
+→ committer validates and previews the exact files and message
 → waits for explicit current-user confirmation
-→ stages, creates, and verifies the local commit
+→ stages exact pathspecs, creates, and verifies the local commit
 ```
 
+All other `.prizmkit/**`, generated support, transient, installed, secret, unknown, or unrelated paths remain excluded or blocking. Exact durable Prizm documentation admission is an interactive exception backed by the Retrospective result, not a general `.prizmkit` allowlist. User confirmation alone is not support validation: instruction files require structure/reference/requirement-consistency/secret checks, lockfiles require parse/schema plus installer or deterministic-regeneration parity, and any other support class requires the exact project-native semantic validator named by the spec/plan.
+
 Pipeline execution:
 
 ```text
@@ -159,7 +178,7 @@ external coordinator validates its required gates and supplies exact readiness e
 → remote publication remains separate
 ```
 
-The preparation request is data for runtime validation, not prompt-level authorization. The committer must not stage, commit, or predeclare COMMITTED in pipeline preparation mode.
+The preparation request is data for runtime validation, not prompt-level authorization. The committer must not stage, commit, or predeclare COMMITTED in pipeline preparation mode. Preparation preserves the existing automated path contract: the complete `.prizmkit/**` tree remains outside Runtime `intended_paths` in this protocol version.
 
 ## Recovery
 

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.159",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {