prizmkit 1.1.154 → 1.1.156

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

@@ -46,7 +46,7 @@ Accept:
 
 - `description`: the natural-language formal requirement;
 - `artifact_dir`: optional explicit requirement artifact root;
-- `execution_mode`: `interactive` by default; headless only when a trusted host explicitly authorizes it;
+- `execution_mode`: `interactive`; external headless automation must invoke atomic stages directly and use its Python runtime for commit execution;
 - `resume`: optional workflow state path or requirement slug for recovery.
 
 If `description` is missing and no resumable workflow is supplied, ask for the requirement before invoking `prizmkit-plan`. External automation must invoke atomic stages directly with its own execution checkpoint rather than nesting this composite workflow.
@@ -57,11 +57,11 @@ If `description` is missing and no resumable workflow is supplied, ask for the r
 
 Invoke `/prizmkit-plan` with the requirement and any explicit `artifact_dir`. Do not write a second plan in this orchestrator.
 
-If initialization context is missing, allow `prizmkit-plan` to recommend initialization and continue with source fallback when the user chooses to proceed. Initialization is a soft prerequisite, not a hidden lifecycle stage.
+If initialization context is missing, let `prizmkit-plan` use its source fallback. Initialization is not a hidden lifecycle stage.
 
 ### 2. Preserve Requirement Identity
 
-Once `prizmkit-plan` resolves an `artifact_dir`, capture it and pass the exact same value to every later stage. The artifact root is generic and is not restricted to one directory family:
+Once `prizmkit-plan` resolves an `artifact_dir`, capture it and pass the exact same value to every later stage. Read `${SKILL_DIR}/references/artifact-identity.md` before deriving or opening workflow state. The artifact root is generic and is not restricted to one directory family:
 
 ```text
 .prizmkit/specs/<requirement-slug>/
@@ -69,35 +69,38 @@ Once `prizmkit-plan` resolves an `artifact_dir`, capture it and pass the exact s
 .prizmkit/refactor/<refactor-id>/
 ```
 
-Never select a different most-recent plan when resuming or handing off. The workflow state path is:
+Never select a different most-recent plan when resuming or handing off. Derive the workflow state path from the exact artifact-directory basename, validate its safe identity, and fail closed if an existing state path belongs to another artifact:
 
 ```text
-.prizmkit/state/workflows/<requirement-slug>.json
+.prizmkit/state/workflows/<requirement-identity>.json
 ```
 
-Read `${SKILL_DIR}/references/workflow-state-protocol.md` for the shared state contract. This workflow state remains distinct from any external host execution checkpoint. The target project controls whether generated `.prizmkit/` files are committed, ignored, or shared; do not modify its Git policy.
+Read `${SKILL_DIR}/references/artifact-identity.md` for path/collision rules and `${SKILL_DIR}/references/workflow-state-protocol.md` for the shared state content contract. This workflow state remains distinct from any external host execution checkpoint. The target project controls whether generated `.prizmkit/` files are committed, ignored, or shared; do not modify its Git policy.
 
 ### 3. Advance Only on Truthful Success
 
 After each atomic stage:
 
-1. Read the stage's actual output and terminal status.
-2. Validate the expected authoritative artifact or evidence and workflow-state transition.
-3. Preserve the same `artifact_dir`.
-4. Continue only on the permitted success status.
-5. Because this composite is the active orchestrator, atomic skills return terminal state and `next_stage` to it; they must not invoke the next stage recursively.
-6. If the host cannot invoke another skill automatically, stop with exactly one deterministic next skill, its `artifact_dir`, and the workflow-state path.
+1. Read the stage-local result and stage-owned artifacts.
+2. Validate those artifacts independently.
+3. Map the domain result to this composite's lifecycle status and update workflow state itself.
+4. Preserve the same `artifact_dir`.
+5. Continue only on the permitted success result.
+6. Supply explicit stage-local inputs to the next invocation; atomic Skills never read this composite's state or choose routing.
+7. If the host cannot invoke another Skill automatically, stop with one deterministic next invocation and caller-owned state path.
 
 Expected transitions:
 
 | Stage | Required success | Next stage |
 |---|---|---|
-| `prizmkit-plan` | `status=completed`, `stage_result=PLAN_READY` | `prizmkit-implement` |
-| `prizmkit-implement` | `status=completed`, `stage_result=IMPLEMENTED` | `prizmkit-code-review` |
-| `prizmkit-code-review` | `status=completed`, `stage_result=REVIEW_PASS` | `prizmkit-test` |
-| `prizmkit-test` | `status=completed`, `stage_result=TEST_PASS` | `prizmkit-retrospective` |
-| `prizmkit-retrospective` | `status=completed`, `stage_result=RETRO_COMPLETE`, with artifact result `DOCS_UPDATED` or `NO_DOC_CHANGE` | `prizmkit-committer` |
-| `prizmkit-committer` | explicit interactive confirmation, then `status=completed` with `stage_result=COMMITTED` | end |
+| `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-retrospective` | `RETRO_COMPLETE` plus an artifact whose `outcome` and `result` agree | `prizmkit-committer` |
+| `prizmkit-committer` | `COMMITTED` after explicit interactive confirmation | end |
+
+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`.
 
@@ -106,16 +109,16 @@ Expected transitions:
 The composite must not:
 
 - reinterpret a plan as implementation;
-- repair production code outside `prizmkit-implement` or the Main-Agent review loop;
+- repair production code itself instead of invoking the appropriate atomic stage with explicit repair input;
 - claim tests passed without a consistent `test-report.md` and terminal `test-result.json`;
 - reinterpret testing-domain results as runtime/session outcomes;
 - perform retrospective documentation changes itself;
-- stage or commit before `prizmkit-committer` applies the current execution's authorization boundary;
+- stage or commit before `prizmkit-committer` completes the interactive preview and confirmation boundary;
 - invoke `prizmkit-deploy` as a hidden seventh stage.
 
 ## Failure and Repair Routing
 
-Use the shared workflow state and authoritative stage evidence to determine routing. Do not blindly retry every failure.
+Use caller-owned workflow state and authoritative stage artifacts to determine routing. Atomic Skills never own this decision.
 
 ### Review Failure
 
@@ -136,15 +139,16 @@ The Main-Agent review skill owns its internal review repairs and its internal te
 ```text
 TEST_NEEDS_FIXES
   → preserve test-report.md and test-result.json
-  → stop with the known remaining correction or delta-review requirement
-  → caller owns any later review/retest decision
+  → when the outer repair budget remains, supply the exact correction to prizmkit-implement
+  → require fresh prizmkit-code-review and prizmkit-test results
+  → otherwise stop with WORKFLOW_BLOCKED
 
 TEST_BLOCKED
   → preserve test-report.md and test-result.json
   → stop with the unresolved truth, input, safety, environment, or reliability blocker
 ```
 
-The composite must not invoke implementation or Code Review automatically from inside the returned testing result unless its own explicitly authorized outer policy defines a new invocation. It must never treat either result as an AI CLI crash.
+The composite's bounded outer repair policy owns that fresh invocation route; it does not recreate the testing-local repair loop. It must never treat either non-pass result as an AI CLI crash.
 
 ### Environment Block
 
@@ -159,7 +163,7 @@ TEST_BLOCKED
   → stop with a deterministic prizmkit-test resume entry
 ```
 
-A trusted headless host performs its own bounded automatic environment recovery when invoking atomic stages. It does not invoke this composite workflow or silently turn a blocked result into success.
+An external headless runtime may perform its own bounded environment recovery when invoking atomic stages. It does not invoke this interactive composite workflow or silently turn a blocked result into success.
 
 ### Repair Limit
 
@@ -179,19 +183,13 @@ When the limit is reached:
 
 The internal `prizmkit-code-review` limit of ten completed review rounds remains separate and does not increment `repair_round`.
 
-## Commit Authorization Boundary
-
-The composite may automatically reach `/prizmkit-committer`, but it must not silently create a Git commit.
+## Interactive Commit Boundary
 
-Interactive execution requires the committer to:
+The composite reaches `/prizmkit-committer operation=interactive-commit` but must not silently create a Git commit.
 
-1. verify all five preceding stage results for the same `artifact_dir`;
-2. inspect the final workspace;
-3. present intended files, diff summary, sensitive-file warnings, and the proposed Conventional Commit message;
-4. wait for explicit user confirmation from the current user;
-5. create and verify the local commit only after confirmation.
+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.
 
-Trusted headless execution is a separate atomic-stage path. It requires a host-defined non-interactive `mode`, a trusted `owner` identifier, and `local_commit_authorized=true`; it does not ask or wait. Unknown headless contexts are blocked. Remote publication is a separate host-runtime operation and is never decided by this composite workflow.
+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.
 
 ## Automatic Handoff and Manual Fallback
 
@@ -206,7 +204,7 @@ When it does not:
 ```text
 Next stage: /prizmkit-<skill>
 artifact_dir: <same resolved artifact_dir>
-workflow_state: .prizmkit/state/workflows/<requirement-slug>.json
+workflow_state: .prizmkit/state/workflows/<requirement-identity>.json
 ```
 
 The user can invoke that one atomic skill and this composite can resume with `resume` later.
@@ -242,7 +240,7 @@ push: not performed automatically
 next_action: invoke /prizmkit-deploy separately if deployment is needed
 ```
 
-If the user declines interactive commit confirmation, report `status=in_progress`, `stage_result=COMMIT_PENDING` rather than `WORKFLOW_COMPLETE` and provide the exact `/prizmkit-committer` resume entry.
+If the user declines interactive commit confirmation, preserve the committer stage as pending or in progress without a workflow `stage_result`, report the atomic operation result `COMMIT_DECLINED`, and provide the exact `/prizmkit-committer operation=interactive-commit` resume entry. `COMMIT_PENDING` is reserved for a validated Runtime commit request and must not represent an interactive decline.
 
 If blocked, report:
 

package/bundled/skills/prizmkit-workflow/references/artifact-identity.md

@@ -0,0 +1,34 @@
+# Interactive Workflow Artifact Identity
+
+The interactive workflow derives state identity from the exact caller/planning artifact directory; it never generates a second slug.
+
+## Derivation
+
+1. Resolve `artifact_dir` as a project-relative path inside the active checkout.
+2. Take its final path component unchanged as `<requirement-identity>`.
+3. Require 1-96 Unicode code points and at most 200 UTF-8 bytes, containing only letters, decimal digits, ASCII hyphens, or ASCII underscores, with a letter or digit at both ends. Reject control characters, separators, `.`/`..`, symlink escape, and empty identity. The byte limit leaves portable filename space for the `.json` suffix.
+4. Use exactly:
+
+```text
+.prizmkit/state/workflows/<requirement-identity>.json
+```
+
+Examples:
+
+```text
+.prizmkit/specs/070-skill-generated-artifact-contracts/
+→ .prizmkit/state/workflows/070-skill-generated-artifact-contracts.json
+
+.prizmkit/bugfix/B-001/
+→ .prizmkit/state/workflows/B-001.json
+```
+
+## Collision and Resume Safety
+
+- Store the exact normalized project-relative `artifact_dir` in state.
+- Before creating state, if the target file already exists, read it and require its `artifact_dir` to equal the active artifact directory exactly.
+- A state file naming collision with a different artifact directory is blocking. Do not overwrite, merge, suffix, or silently select a recent state; require the caller to resolve the conflicting record explicitly.
+- When `resume` supplies a state path, require it to equal the derived path, remain under `.prizmkit/state/workflows/`, and point to the exact artifact directory recorded inside it.
+- Continue using the same state path and artifact directory for every stage and repair round.
+
+External checkpoints use their own identity and are never derived from or merged into this path.

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

@@ -4,11 +4,13 @@
 
 ## Location and Identity
 
+Derive the path through `${SKILL_DIR}/references/artifact-identity.md`:
+
 ```text
-.prizmkit/state/workflows/<requirement-slug>.json
+.prizmkit/state/workflows/<requirement-identity>.json
 ```
 
-The active `artifact_dir` is preserved exactly across every stage:
+The identity is the validated artifact-directory basename. An existing state file for a different `artifact_dir` is a blocking collision and is never overwritten or suffixed automatically. The active `artifact_dir` is preserved exactly across every stage:
 
 ```text
 .prizmkit/specs/<requirement-slug>/
@@ -31,7 +33,7 @@ The state file is an index, not the authority for stage completion:
 | Terminal testing result | `{artifact_dir}/test-result.json` |
 | Retrospective completion | `{artifact_dir}/retrospective-result.json` |
 | Durable architecture knowledge | `.prizmkit/prizm-docs/` |
-| Local commit | Git history and confirmed or authorized commit identity |
+| Local commit | Git history and runtime- or user-verified commit identity |
 | Current stage, orchestrator, and resume entry | Workflow state |
 | External orchestration progress | External host checkpoint |
 
@@ -64,7 +66,7 @@ Every consumer compares workflow state with the skill-owned artifacts and curren
 | `orchestrator` | Semantic coordinator identifier, or null for direct stage use. |
 | `stage` | Stage that most recently wrote state. |
 | `status` | Lifecycle status: `pending`, `in_progress`, `completed`, `failed`, or `skipped`. |
-| `stage_result` | Domain result for the current stage, such as `PLAN_READY`, `IMPLEMENTED`, `REVIEW_PASS`, `REVIEW_NEEDS_FIXES`, `TEST_*`, `RETRO_COMPLETE`, or `COMMITTED`. |
+| `stage_result` | Coordinator-recorded lifecycle result mapped from a validated atomic result and its required artifacts, such as `PLAN_READY`, `IMPLEMENTED`, `REVIEW_PASS`, `REVIEW_NEEDS_FIXES`, `TEST_*`, `RETRO_COMPLETE`, or `COMMITTED`. |
 | `completed_stages` | Ordered stages completed for this requirement. |
 | `repair_scope` | Optional caller-owned routing scope. The test skill reports high-risk repairs through `test-result.json` instead of scheduling another stage. |
 | `repair_round` | Optional outer cross-stage repair round, from 0 through 3. It is not a test-internal repair counter. |
@@ -97,10 +99,10 @@ review-report NEEDS_FIXES        → status=failed,     stage_result=REVIEW_NEED
 test-result TEST_PASS            → status=completed,  stage_result=TEST_PASS
 test-result TEST_NEEDS_FIXES     → status=failed,     stage_result=TEST_NEEDS_FIXES
 test-result TEST_BLOCKED         → status=failed,     stage_result=TEST_BLOCKED
-retrospective DOCS_UPDATED       → status=completed,  stage_result=RETRO_COMPLETE
-retrospective NO_DOC_CHANGE      → status=completed,  stage_result=RETRO_COMPLETE
-retrospective blocked            → status=failed,     stage_result=RETRO_BLOCKED
-commit authorization pending     → status=in_progress, stage_result=COMMIT_PENDING
+retrospective outcome=RETRO_COMPLETE, result=DOCS_UPDATED   → status=completed, stage_result=RETRO_COMPLETE
+retrospective outcome=RETRO_COMPLETE, result=NO_DOC_CHANGE  → status=completed, stage_result=RETRO_COMPLETE
+retrospective outcome=RETRO_BLOCKED                         → status=failed,    stage_result=RETRO_BLOCKED
+runtime commit preparation       → status=in_progress, stage_result=COMMIT_PENDING
 local commit confirmed           → status=completed,  stage_result=COMMITTED
 commit blocked                   → status=failed,     stage_result=COMMIT_BLOCKED
 ```
@@ -115,8 +117,8 @@ commit blocked                   → status=failed,     stage_result=COMMIT_BLOC
 
 ```text
 TEST_NEEDS_FIXES
-→ known correction or required delta review remains
-→ caller decides whether and how to arrange another stage
+→ a known correction remains
+→ caller decides whether and how to arrange another invocation
 
 TEST_BLOCKED
 → truth, input, safe environment, or reliable execution prevents a verdict
@@ -132,30 +134,32 @@ Any outer repair or continuation policy is independently owned by the caller and
 
 1. An atomic stage performs only its own stage, writes its truthful result and artifact paths, and returns control.
 2. When `orchestrator` is non-null, only that orchestrator invokes the next skill.
-3. Direct stage use may report a possible next invocation but does not claim it ran.
+3. Direct atomic use returns only its local result and artifacts; it does not report or select another invocation.
 4. Every handoff preserves the same `artifact_dir`.
 5. External automation invokes atomic stages directly and does not nest the composite workflow.
 6. Workflow state never replaces or absorbs an external host checkpoint.
 
-## Commit Authorization
+## Commit Execution Ownership
 
 Interactive execution:
 
 ```text
 committer previews intended files and message
 → waits for explicit current-user confirmation
-→ creates the local commit
+→ stages, creates, and verifies the local commit
 ```
 
-Trusted headless execution:
+Pipeline execution:
 
 ```text
-trusted host explicitly authorizes the current local task commit
-→ committer verifies gates and commits automatically
+external coordinator validates its required gates and supplies exact readiness evidence
+→ committer validates only that evidence and writes an exact runtime-commit-request.json
+→ external coordinator maps COMMIT_REQUEST_READY to its checkpoint's in_progress/COMMIT_PENDING state
+→ Python runtime validates the request, commits, verifies Git, and writes checkpoint completed/COMMITTED
 → remote publication remains separate
 ```
 
-A self-declared or untrusted headless context does not authorize a commit.
+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.
 
 ## Recovery
 
@@ -171,4 +175,4 @@ When state is missing, stale, or inconsistent:
 8. Reconstruct the latest safe predecessor and report the reconstruction.
 9. Continue only from the first incomplete or invalid stage.
 
-Stale state never bypasses review, testing, retrospective, commit authorization, or external checkpoint enforcement.
+Stale state never bypasses review, testing, retrospective, commit preparation/execution, or external checkpoint enforcement.

package/bundled/skills/recovery-workflow/SKILL.md

@@ -42,7 +42,8 @@ The detector reads only active checkout records:
 
 A candidate is resumable only when:
 - `state` is `active`;
-- `task_id` matches its task family;
+- `task_type` equals the checkout directory family;
+- `task_id` is explicitly recorded, matches the exact `F-NNN`, `B-NNN`, or `R-NNN` family form, and equals its parent state-directory name;
 - `active_dev_branch` is present; and
 - the recorded local branch still exists.
 

package/bundled/skills/recovery-workflow/references/detection.md

@@ -13,9 +13,10 @@ Recovery uses the runtime's durable task checkout identity rather than reconstru
 A record is resumable only when:
 
 1. `state` equals `active`.
-2. `task_id` matches the directory family.
-3. `active_dev_branch` is non-empty.
-4. `refs/heads/<active_dev_branch>` exists locally.
+2. `task_type` equals the checkout directory family.
+3. `task_id` is explicitly present, matches the exact `F-NNN`, `B-NNN`, or `R-NNN` family form, and equals its parent state-directory name.
+4. `active_dev_branch` is non-empty.
+5. `refs/heads/<active_dev_branch>` exists locally.
 
 Ignore records whose state is `completed` or `reset`. Also ignore session logs, plan lists, artifact directories, and checkpoint files when no active checkout record exists. Those files may remain after completed or historical work and are not evidence of an interrupted task.
 

package/bundled/skills/recovery-workflow/scripts/detect-recovery-state.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import re
 import subprocess
 from pathlib import Path
 
@@ -14,19 +15,19 @@ FAMILIES = (
         "name": "feature",
         "state_dir": "features",
         "plan_path": ".prizmkit/plans/feature-list.json",
-        "id_prefix": "F-",
+        "id_pattern": r"^F-\d{3}$",
     },
     {
         "name": "bugfix",
         "state_dir": "bugfix",
         "plan_path": ".prizmkit/plans/bug-fix-list.json",
-        "id_prefix": "B-",
+        "id_pattern": r"^B-\d{3}$",
     },
     {
         "name": "refactor",
         "state_dir": "refactor",
         "plan_path": ".prizmkit/plans/refactor-list.json",
-        "id_prefix": "R-",
+        "id_pattern": r"^R-\d{3}$",
     },
 )
 
@@ -83,9 +84,18 @@ def detect_candidates(project_root: Path) -> list[dict[str, object]]:
             data = load_json(checkout_path)
             if not data or str(data.get("state") or "") != "active":
                 continue
-            task_id = str(data.get("task_id") or checkout_path.parent.name).strip()
+            raw_task_id = data.get("task_id")
+            if not isinstance(raw_task_id, str):
+                continue
+            task_id = raw_task_id.strip()
             branch = str(data.get("active_dev_branch") or "").strip()
-            if not task_id.startswith(family["id_prefix"]) or not branch_exists(project_root, branch):
+            if (
+                task_id != raw_task_id
+                or data.get("task_type") != family["name"]
+                or checkout_path.parent.name != task_id
+                or re.fullmatch(family["id_pattern"], task_id) is None
+                or not branch_exists(project_root, branch)
+            ):
                 continue
             candidates.append(
                 {

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.154",
+  "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": {