prizmkit 1.1.155 → 1.1.156

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

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

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

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

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

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

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

@@ -8,16 +8,27 @@ Use this operation for manual edits, merges, rebases, branch switches, generated
 
 STEPS:
 1. Identify drift source. Prefer explicit user context; otherwise inspect git changes with `git diff --cached --name-status`, then `git diff --name-status`. If no git changes exist, run a bounded rescan comparing code structure against existing docs.
-2. Map changed files to modules by matching MODULE_INDEX or MODULE_GROUPS in `root.prizm`.
-3. Classify each change: A (added) -> new KEY_FILES entries; D (deleted) -> remove entries and update counts; M (modified) -> check dependency/interface/data-flow impact; R (renamed) -> update path references.
-4. Update affected docs bottom-up: L2 first for INTERFACES/DATA_FLOW/DEPENDENCIES/TRAPS/DECISIONS, then L1 for FILES/KEY_FILES/SUBDIRS/DEPENDENCIES, then L0 only for structural module changes. L1 does not contain INTERFACES, DATA_FLOW, TRAPS, or DECISIONS.
-5. Preserve `PROJECT_BRIEF:` in `root.prizm`; it is managed by `/prizmkit-init`.
-6. Do not write CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths.
-7. Skip updates for comments/whitespace/formatting-only changes, `.prizm`-only changes, and test-only changes that reveal no durable boundaries, traps, interface constraints, behavior rules, or regression knowledge.
-8. If a new directory qualifies as a module and matches no existing module, create L1 immediately and add it to MODULE_INDEX or MODULE_GROUPS. Create L2 only when source files contain meaningful behavior worth documenting.
-9. During full rescan mode, check for missing L2 docs only for modules with meaningful source behavior. Create L2 docs when the missing detail would help future AI work; do not create empty placeholder L2 files.
-10. Enforce size limits: L0 <= 4KB, L1 <= 4KB, L2 <= 5KB.
-11. Validate memory hygiene and format compliance.
-12. Stage updated `.prizm` files with `git add .prizmkit/prizm-docs/` only after reviewing the repair summary.
+2. Map changed files to modules through MODULE_INDEX or MODULE_GROUPS in `root.prizm`, then resolve mirrored SUBDIRS or flat-module DETAILS ownership from the relevant L1.
+3. Classify each source change as A, D, M, or R, but do not mechanically turn changes into documentation. Treat every possible file, interface, dependency, flow, trap, decision, rule, and summary as a candidate and apply the future-incorrect-modification Value Gate.
+4. Before writing any existing L2, L1, or L0 target, read that target and its resolving parent/child pointers. Build a protected set of still-valid public/wire contracts, cross-module constraints, non-obvious dependencies, traps, decisions with necessary rationale, likely-to-recur rejected alternatives, side effects, and security/data-integrity/concurrency/transaction/compatibility rules.
+5. Apply the Cleanup Gate by semantic meaning:
+   - update an equivalent entry in place rather than appending alternate wording
+   - merge synonymous entries into one shortest complete meaning
+   - remove stale, duplicate, source-derivable, low-value, and parent-copied material
+   - add only a genuinely new durable fact with no semantic equivalent
+   Append-only repair is prohibited.
+6. Reconcile bottom-up. L2 owns Value-Gate-qualified INTERFACES/DATA_FLOW/DEPENDENCIES/RULES/TRAPS/DECISIONS. L1 owns concise FILES/KEY_FILES/SUBDIRS/DETAILS/DEPENDENCIES summaries. L0 changes only for project-map structure. When L2 has complete behavior, L0/L1 retain only a concise summary and resolving pointer, never copied interfaces, data flow, traps, decisions, or full RULES.
+7. Preserve `PROJECT_BRIEF:` in `root.prizm`; it is managed by `/prizmkit-init`. Do not write prohibited history, date, workflow, branch, absolute-path, or runtime-artifact metadata.
+8. Skip comments/whitespace/formatting-only changes, `.prizm`-only changes, and test-only changes that reveal no durable behavior boundary or fact passing the Value Gate.
+9. If a new top-level directory qualifies as a module, create its direct-child L1 and add a concise pointer to MODULE_INDEX or MODULE_GROUPS. Use MODULE_GROUPS whenever MODULE_INDEX cannot fit within 4096B; never raise the limit for project size.
+10. Create L2 only for durable behavioral knowledge:
+   - a real source submodule always uses its mirrored `.prizmkit/prizm-docs/<module>/<submodule>.prizm` path
+   - a flat module may use `.prizmkit/prizm-docs/<module>/<concern-slug>.prizm` only when multiple stable concerns cannot safely fit one 5120B L2 after cleanup
+   - semantic details require the complete CONCERN terminal shape, explicit non-empty/non-overlapping FILES ownership, and one resolving L1 DETAILS entry
+   - ambiguous concern identity, empty normalization, mirrored-path/slug collision, or overlapping ownership blocks creation and reports the manual decision; never use task IDs or numeric suffixes
+11. Measure all affected targets by exact raw UTF-8 bytes with L0/L1 4096B and L2 5120B limits. Natural content below 80% remains unchanged; warning-range content is valid and reported. Clean, move, or safely split rewritten targets at 90% or above toward 3277-3686B for L0/L1 or 4096-4607B for L2. If a hard-limit error or repeated pressure cannot be resolved without deleting protected knowledge, block the write.
+12. Validate Value/Cleanup compliance, parent-summary boundaries, semantic ownership/identity, pointers, hierarchy, capacity, memory hygiene, and format. Warning-only capacity results pass; hard-limit or format errors fail.
+13. Report updated, created, removed, merged, protected, and skipped facts/docs with reasons plus capacity diagnostics ordered by descending utilization.
+14. Stage updated `.prizm` files with `git add .prizmkit/prizm-docs/` only after reviewing the repair summary.
 
-OUTPUT: List updated, created, removed, and skipped docs with reasons. Explicitly state that this was an out-of-band repair/resync, not a normal development retrospective.
+OUTPUT: List updated, created, removed, merged, protected, and skipped docs/facts with reasons; sorted capacity diagnostics; ambiguity blockers; and an explicit statement that this was out-of-band repair/resync, not a normal development retrospective.

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

@@ -5,13 +5,17 @@ Check format compliance and consistency of all .prizm docs.
 PRECONDITION: .prizmkit/prizm-docs/ exists.
 
 STEPS:
-1. FORMAT CHECK: Verify all .prizm files use KEY: value format. Flag any prose paragraphs, code blocks (```), markdown headers (##), emoji, ASCII art, or horizontal rules. Flag TRAPS entries missing severity prefix ([CRITICAL], [HIGH], or [LOW]). Flag CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, and `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths as auxiliary noise. Note: [REVIEW] preceding severity (e.g., `[REVIEW][HIGH]`) is a valid temporary staleness marker, not a format violation.
-2. SIZE CHECK: Verify size limits: L0 <= 4KB, L1 <= 4KB, L2 <= 5KB. Report files exceeding limits with current size.
-3. POINTER CHECK: Verify all arrow (->) references resolve to existing .prizm files. Report broken pointers.
-4. STALENESS CHECK: Compare git modification time of each .prizm file against source directory. Flag docs where source was modified more recently.
-5. COMPLETENESS CHECK: Verify root.prizm has all required fields (PRIZM_VERSION, PROJECT, LANG, MODULE_INDEX or MODULE_GROUPS). Verify L1 docs have MODULE, FILES, RESPONSIBILITY, DEPENDENCIES (no INTERFACES/TRAPS/DECISIONS). Verify L2 docs have MODULE, FILES, KEY_FILES, DEPENDENCIES, INTERFACES, TRAPS.
-6. ANTI-PATTERN CHECK: Flag duplicate information across levels, implementation details in L0/L1, TODO items, session-specific context, changelog/history sections, and workflow metadata.
-7. RULES HIERARCHY CHECK: Verify L1/L2 RULES do not contradict root.prizm RULES. L1/L2 may only supplement with module-specific exceptions.
-8. TRAPS STALENESS CHECK: For each L2 doc where TRAPS section has more than 8 entries, verify that TRAPS include staleness metadata (`STALE_IF:` or `REF:` fields). Flag TRAPS without any staleness metadata as `NEEDS_METADATA` — these are not auto-removed, but flagged for the next `/prizmkit-retrospective` to enrich with `STALE_IF:` globs or `REF:` hashes.
+1. FORMAT CHECK: Verify all `.prizm` files use KEY: value format. Flag prose paragraphs, code blocks, markdown headers, emoji, ASCII art, horizontal rules, invalid TRAPS severity, and prohibited history/date/workflow/branch/absolute/artifact metadata. `[REVIEW]` before severity remains a valid temporary staleness marker.
+2. VALUE CHECK: Flag source-derivable signatures/structure, task or change history, test inventories, temporary conclusions, stale statements, duplicate meanings, long procedures, low-value file lists, line-count/complexity inventories, and parent copies of complete child behavior. Do not flag a still-valid public/wire contract, cross-module constraint, non-obvious dependency, trap, durable decision/rejected rationale, side effect, or security/data-integrity/concurrency/transaction/compatibility rule merely because it consumes capacity.
+3. CAPACITY CHECK: Measure exact raw UTF-8 bytes. Classify only the exact root as L0/4096B, direct children as L1/4096B, and nested mirrored or semantic documents as L2/5120B. Bands are normal below 80%, warning from 80% to below 90%, strong-warning from 90% through 100%, and error above 100%.
+4. CAPACITY REPORT: Sort all non-normal entries by exact descending utilization using integer ratio comparison, then repository-relative path for ties. Every entry includes path, level, current bytes, hard limit, band, target range (3277-3686B for L0/L1; 4096-4607B for L2), and level-appropriate trim, deduplicate, move-to-child, or semantic-split actions consistent with the canonical F-063 classifier.
+5. CAPACITY RESULT: Warning and strong-warning entries are advisory and do not fail Validate when no other violation exists. Any byte above a hard limit is an error and fails; format, pointer, hierarchy, ownership, or completeness errors also fail and are never downgraded because capacity is only a warning.
+6. POINTER/PARENT CHECK: Verify every arrow resolves. L0/L1 contain concise summaries and pointers rather than copied L2 INTERFACES/DATA_FLOW/TRAPS/DECISIONS/full RULES. SUBDIRS targets mirrored source-submodule L2. DETAILS uses exactly `- <concern-slug>: <one-line stable behavior summary> -> .prizmkit/prizm-docs/<module>/<concern-slug>.prizm` and targets one matching semantic L2.
+7. SEMANTIC IDENTITY/OWNERSHIP CHECK: For each semantic L2, verify required fields MODULE, CONCERN, FILES, RESPONSIBILITY, INTERFACES, DATA_FLOW, KEY_FILES, DEPENDENCIES, RULES, TRAPS, and DECISIONS; verify `CONCERN: <stable concern identity> | SLUG: <concern-slug>`; rerun Unicode NFKC/lowercase/kebab normalization; require non-empty explicit repository-relative FILES ownership with no sibling overlap; and require exact parent/path/slug agreement. A mirrored source-submodule path has precedence. Ambiguous identity, collision, or overlap is a validation error requiring a manual decision, not a numbered or task-named repair.
+8. COMPLETENESS CHECK: Verify root has PRIZM_VERSION, PROJECT, LANG, and exactly one of MODULE_INDEX/MODULE_GROUPS. Verify L1 has MODULE, FILES, RESPONSIBILITY, DEPENDENCIES and no behavioral sections. Verify mirrored L2 has MODULE, FILES, RESPONSIBILITY, INTERFACES, KEY_FILES, DEPENDENCIES, and TRAPS with no CONCERN field; DATA_FLOW, RULES, DECISIONS, and domain sections remain optional when no fact passes the Value Gate. In semantic L2 only, explicit `<SECTION>: none` satisfies a required behavioral section when no fact passes the Value Gate.
+9. STALENESS CHECK: Compare each document's git modification time with its mapped source directory or semantic FILES ownership. Flag source-newer documents. Without git history, use filesystem timestamps and report reduced accuracy.
+10. RULES HIERARCHY CHECK: Verify L1/L2 RULES do not contradict authoritative root RULES.
+11. TRAPS STALENESS CHECK: When an L2 TRAPS section has more than 8 entries, flag entries lacking `STALE_IF:` or `REF:` as `NEEDS_METADATA`; do not auto-remove them.
+12. SCALE CHECK: If MODULE_INDEX cannot fit within L0, require MODULE_GROUPS. Never allow a project-size override, limits above 4096B/4096B/5120B, L3/fourth-level documents, a memory state machine, or a fact scoring system.
 
-OUTPUT: Validation report with PASS/FAIL per check, list of issues with file paths and suggested fixes.
+OUTPUT: Validation report with PASS/FAIL per check, sorted non-normal capacity entries, issue paths with actionable fixes, and an exit result. Warning-only capacity diagnostics exit successfully; any hard-limit or other validation error exits nonzero.

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

@@ -5,137 +5,148 @@ description: "Synchronize durable Prizm documentation for one caller-supplied pr
 
 # PrizmKit Retrospective
 
-`/prizmkit-retrospective` synchronizes durable project documentation for one explicitly supplied project change.
+`/prizmkit-retrospective` synchronizes durable project documentation for one explicitly supplied project change. It performs targeted structural synchronization and durable knowledge injection, or records `NO_DOC_CHANGE` when no update passes the Value Gate.
 
-It performs two jobs:
-
-1. **Structural Sync** — reflect changed code structure, interfaces, dependencies, and file mappings in `.prizmkit/prizm-docs/` when the documentation system exists.
-2. **Knowledge Injection** — add durable TRAPS, RULES, and DECISIONS revealed by the supplied project change.
-
-When no documentation update is warranted, it records `NO_DOC_CHANGE` rather than silently producing no result.
-
-For first-time documentation setup, validation, rebuild, migration, or out-of-band repair after docs drift, use `/prizmkit-prizm-docs` independently.
+For first-time documentation setup, validation, rebuild, migration, or out-of-band repair after docs drift, use `/prizmkit-prizm-docs` independently. Retrospective consumes the established Prizm documentation policy but never invokes that Skill.
 
 ## Input
 
 | Parameter | Required | Description |
 |---|---|---|
 | `artifact_dir` | Yes | Exact caller-supplied directory in which to write `retrospective-result.json`. |
-| `change_paths` | Yes | Exact project-relative non-`.prizmkit/` paths whose current change is the documentation input. May be an explicit empty list only when the caller requests a no-change determination. |
-| `change_summary` | No | Caller-supplied summary used only as context; source changes remain authoritative. |
+| `change_paths` | Yes | Exact caller-supplied non-`.prizmkit/` `change_paths` whose current project changes are the only authoritative documentation input. An explicit empty list is allowed only for a caller-requested no-change determination. |
+| `change_summary` | No | Supporting context only; it cannot establish a fact that the supplied project paths do not establish. |
 
 Do not discover a different artifact directory, expand the path set, or infer prerequisite work.
 
 ## Atomic Boundary
 
-`prizmkit-retrospective` owns only structural documentation synchronization, durable knowledge injection, and `retrospective-result.json` for the supplied paths. It returns `RETRO_COMPLETE` or `RETRO_BLOCKED` and stops.
+`prizmkit-retrospective` owns only targeted structural documentation synchronization, durable knowledge injection, and `{artifact_dir}/retrospective-result.json` for the supplied paths. It does not invoke another Skill, does not read or mutate caller or checkpoint state, and does not choose stage order or routing.
+
+It does not stage, commit, reset, checkout, or stash; it does not change Git/ignore policy; and it does not directly edit generated platform outputs. All paths under `.prizmkit/` are framework-internal and remain outside automated task commits. Capacity maintenance does not add a capacity state machine, fact scoring system, routing field, caller-state field, or fourth documentation level. The stage returns `RETRO_COMPLETE` or `RETRO_BLOCKED` and stops.
 
 ## When to Use
 
 - A caller supplies exact project change paths that may affect durable documentation.
-- A previously interrupted documentation synchronization is resumed with the same explicit inputs.
-- The user explicitly requests a retrospective or documentation synchronization for a named change.
+- A previously interrupted synchronization is resumed with the same exact inputs.
+- The user explicitly requests a retrospective for one named project change.
 
 ## When NOT to Use
 
-- The requested change paths are missing, unsafe, contradictory, or cannot be inspected.
-- The request asks this Skill to discover what work should be documented.
-- First-time docs initialization or out-of-band docs repair is needed; use `/prizmkit-prizm-docs` instead.
+- Required paths are missing, unsafe, contradictory, outside the checkout, under `.prizmkit/`, or cannot be inspected.
+- The caller asks this Skill to discover what work should be documented.
+- First-time initialization or repository-wide out-of-band drift repair is needed.
 
-## Input Validation and Scope
+## Exact Input Scope and Candidate Authority
 
-1. Resolve `artifact_dir` and every `change_paths` entry exactly as supplied.
+Treat only the exact caller-supplied non-`.prizmkit/` `change_paths` as authoritative project-change input.
+
+1. Normalize `artifact_dir` and every path exactly as supplied without broadening the set.
 2. Reject paths outside the checkout, paths under `.prizmkit/`, and paths that do not belong to the supplied project change.
-3. Inspect only the supplied non-`.prizmkit/` project changes and the Prizm docs necessary to synchronize them.
-4. Treat `change_summary` as supporting context only. Never infer durable facts from generated records or caller metadata when source/project files do not establish those facts.
-5. If the input cannot safely establish the documentation scope, return `RETRO_BLOCKED` with the exact blocker.
+3. Inspect the current change only through exact pathspecs for the validated paths. Use narrowly required source context only when one eligible change raises a concrete ambiguity about its interface, caller, dependent, data flow, or behavior.
+4. Generated artifacts, lifecycle records, caller metadata, `change_summary`, repository-wide discovery, and existing Prizm text must not independently establish a candidate fact or expand the input scope. Existing Prizm documents are target/current-state evidence only.
+5. Map exact changes to only the affected targets and their necessary direct parent summaries or pointers. Never perform an unconditional repository-wide documentation rewrite.
+6. If exact inputs cannot safely establish candidate or target scope, prepare `RETRO_BLOCKED` with the exact blocker.
 
 Only targeted `.prizmkit/prizm-docs/` changes and `{artifact_dir}/retrospective-result.json` are outputs.
 
-## Job 1: Structural Sync
+## Value and Cleanup Gates
+
+Before retaining any candidate from an eligible source change, ask:
+
+> Could a future AI that lacks this fact make an incorrect modification?
 
-When `.prizmkit/prizm-docs/` exists, read `${SKILL_DIR}/references/structural-sync-steps.md` and synchronize documentation with the supplied project changes.
+Retain a fact only when the answer is yes and the fact is current, durable, non-obvious, actionable, source-established, and placed at its lowest owning documentation level. Preserve rejected alternatives that future sessions are likely to propose again only when their durable reasons remain source-established.
 
-Review only supplied project files outside `.prizmkit/`:
+Reject source-derivable structure or signatures, transient conclusions, historical/task/change material, duplicate meanings, stale or conflicting statements, test inventories, long procedures, parent-copied behavior, and low-value file lists or wording.
 
-- added, modified, deleted, and renamed source files;
-- structural module files, configuration, interfaces, and tests when they reveal durable project behavior;
-- documentation mappings affected by those project changes;
-- stale pointers and stale traps implicated by those project changes;
-- format, pointer, size, and memory-hygiene constraints for any docs the retrospective updates.
+For every existing target:
 
-When `.prizmkit/prizm-docs/` does not exist, record `NO_DOC_CHANGE` with reason `PRIZM_DOCS_NOT_INITIALIZED` and recommend documentation initialization as a separate action.
+1. Read each existing target before preparing its replacement, including the resolving parent/child pointers necessary for that target.
+2. Establish the protected set of still-valid contracts, constraints, traps, rules, data flow, dependencies, decisions, side effects, and safety/integrity knowledge.
+3. Match existing and candidate facts by semantic meaning; update the canonical entry in place, merge synonymous facts, and remove obsolete, stale, derivable, duplicate, conflicting, or parent-copied material.
+4. Add only genuinely new facts that pass the Value Gate and have no equivalent canonical entry. Append-only synchronization is prohibited.
 
-Create a detail document only when the supplied change contains meaningful durable module knowledge.
+Read `${SKILL_DIR}/references/knowledge-injection-steps.md` for candidate extraction and injection details.
 
-## Job 2: Knowledge Injection
+## Capacity Preflight and Structural Sync
 
-When the supplied project change reveals durable knowledge, read `${SKILL_DIR}/references/knowledge-injection-steps.md` and inject only stable product/domain knowledge into Prizm docs.
+Read `${SKILL_DIR}/references/structural-sync-steps.md` and run its preflight for every target before replacement:
 
-Candidate knowledge includes:
+1. Measure the existing target's exact raw UTF-8 bytes.
+2. Build the complete candidate result, including cleanup, before replacement and measure its exact raw UTF-8 bytes.
+3. Apply hard limits of 4096B for the root project map, 4096B for a direct module index, and 5120B for a nested detail document. Classify normal below 80%, warning from 80% to below 90%, strong-warning from 90% through the hard limit, and error above the hard limit.
+4. If current or candidate content reaches at least 80%, perform the minimum safe cleanup or semantic split before final replacement. Aim for 3277–3686B for a root/module index or 4096–4607B for a detail document, preserving approximately 10% headroom; never pad naturally concise output.
+5. Never delete protected knowledge merely to satisfy a byte check. If protected knowledge cannot fit, use an unambiguous stable semantic boundary or block safely.
 
-- new traps, race conditions, or surprising coupling;
-- architectural rules or decisions;
-- interface or contract changes;
-- dependencies affecting module behavior;
-- observable behavior changes;
-- test-established boundaries or regression rules.
+Plan and write bottom-up: create or update the most specific detail first, then synchronize its direct module index and the root project map only as concise summaries and resolving pointers. Complete `INTERFACES`, `DATA_FLOW`, `TRAPS`, `DECISIONS`, and full `RULES` remain in the owning detail rather than being copied into parents.
 
-Do not write transient artifact paths, task IDs, branch names, dates, session/run metadata, or changelog material into Prizm docs.
+A real source submodule uses mirrored detail identity. An eligible flat module may use a deterministic semantic concern detail and direct-module `DETAILS` pointer only when the structural reference's identity, ownership, collision, and complete-terminal-shape checks pass.
 
-When no durable structural or knowledge change exists, return `NO_DOC_CHANGE` and explain why.
+## Safe Write, Verification, and Idempotency
 
-## Verification
+1. Before the first write, preserve exact pre-write bytes for every existing target in the bounded affected set and record which candidates are new.
+2. Do not replace a target whose candidate already violates format, identity, pointer, protected-knowledge, or capacity checks.
+3. Write the validated affected set bottom-up. After each write, re-read the actual file rather than trusting the proposed content.
+4. Re-read every written `.prizm` file as raw bytes, recompute its raw UTF-8 byte length, apply its exact hard limit and warning band, validate its format, and resolve every affected pointer in both directions. Validate all affected parent and child documents, not only the last file written.
+5. Review the final targeted documentation diff. Never report `RETRO_COMPLETE` after a failed check.
+6. If any post-write check fails, restore every replaced target to its exact pre-write bytes and remove any invalid newly created target so no invalid oversized final document remains. Do not use Git reset, checkout, or stash for restoration.
+7. Compare each validated candidate with current target bytes before replacement. If byte-identical, do not rewrite or reorder the document. With identical source changes and inputs and no intervening project change, a second run produces no `.prizm` content diff and returns `NO_DOC_CHANGE` with an already-synchronized reason.
 
-1. Validate any updated docs using the project documentation rules.
-2. Review the final documentation diff and ensure only intended changes are present.
-3. Do not change the target project's Git/ignore policy and do not stage or commit documentation changes. All paths under `.prizmkit/` are framework-internal and remain outside automated task commits.
-4. Never claim documentation synchronization passed if validation failed.
+When `.prizmkit/prizm-docs/` does not exist, record `NO_DOC_CHANGE` with reason `PRIZM_DOCS_NOT_INITIALIZED` and recommend initialization as a separate action.
+
+## Capacity Blocker Contract
+
+If protected knowledge cannot be compressed safely and no unambiguous stable split exists, do not leave the oversized candidate as final content. Restore any earlier writes from this attempt and write `RETRO_BLOCKED` with `result: null`.
+
+The existing seven fields carry all evidence; add no new field. Put the exact target path, measured current or candidate bytes, applicable limit/band, protected knowledge that prevented trimming, and concrete recommended split boundary in `reason`. Put only checks actually attempted, including candidate capacity or pointer checks, in `validation`. Preserve the exact supplied `change_paths`; `documentation_paths` follows the schema and lists only documentation paths actually changed during the attempt. Never invent validation or claim success after restoration/validation failure.
 
 ## Result Artifact
 
-Read `${SKILL_DIR}/references/retrospective-result-schema.json` and write `{artifact_dir}/retrospective-result.json` atomically:
+Read `${SKILL_DIR}/references/retrospective-result-schema.json` and atomically write `{artifact_dir}/retrospective-result.json` with exactly these seven keys:
 
 ```json
 {
   "schema_version": 1,
   "outcome": "RETRO_COMPLETE",
   "result": "DOCS_UPDATED",
-  "reason": "Durable module interfaces and traps changed",
+  "reason": "Durable module contract changed and affected documentation passed validation",
   "change_paths": ["src/example.py"],
   "documentation_paths": [".prizmkit/prizm-docs/example/module.prizm"],
   "validation": ["python3 core/templates/hooks/validate-prizm-docs.py --all"]
 }
 ```
 
-Every retrospective artifact has exactly these seven keys: `schema_version`, `outcome`, `result`, `reason`, `change_paths`, `documentation_paths`, and `validation`. Do not add routing, checkpoint, or caller-state fields.
+Every retrospective artifact has exactly these seven keys: `schema_version`, `outcome`, `result`, `reason`, `change_paths`, `documentation_paths`, and `validation`.
 
-`outcome` is `RETRO_COMPLETE` for a valid `DOCS_UPDATED` or `NO_DOC_CHANGE` result. Use `NO_DOC_CHANGE` with a concrete reason and an empty or unchanged `documentation_paths` list.
-
-If documentation validation or synchronization cannot safely complete, atomically write the same seven-key shape with `result: null`:
+A capacity or validation blocker uses the same shape without adding state:
 
 ```json
 {
   "schema_version": 1,
   "outcome": "RETRO_BLOCKED",
   "result": null,
-  "reason": "Exact validation or synchronization blocker",
+  "reason": "Target .prizmkit/prizm-docs/example/module.prizm candidate=5200B limit=5120B; protected public contract prevents trimming; ownership check could not prove a stable split; recommended boundary: separate transport from persistence behavior",
   "change_paths": ["src/example.py"],
-  "documentation_paths": [".prizmkit/prizm-docs/example/module.prizm"],
-  "validation": ["validation command or check that failed"]
+  "documentation_paths": [],
+  "validation": ["candidate raw UTF-8 capacity check: 5200B > 5120B", "semantic ownership check: ambiguous"]
 }
 ```
 
-For a blocked outcome, `reason` is the exact non-empty blocker, `change_paths` remains the exact supplied input, `documentation_paths` lists only files actually changed before blocking, and `validation` lists only checks actually attempted. Never use `DOCS_UPDATED`, `NO_DOC_CHANGE`, an empty success reason, or an invented validation command with `RETRO_BLOCKED`.
+- `RETRO_COMPLETE` pairs only with `DOCS_UPDATED` or `NO_DOC_CHANGE`.
+- `DOCS_UPDATED` requires non-empty documentation and validation lists.
+- `NO_DOC_CHANGE` uses a concrete reason and truthful empty or unchanged path evidence.
+- `RETRO_BLOCKED` uses `result: null`, a non-empty exact reason, the exact input paths, only truthful documentation paths, and only checks actually attempted.
+
+Do not add checkpoint, routing, capacity-state, caller-state, evidence-manifest, hash, or attestation fields.
 
 ## Output
 
 Return only:
 
 - `artifact_dir` and `retrospective-result.json` path;
-- `RETRO_COMPLETE` with `DOCS_UPDATED` or `NO_DOC_CHANGE`;
+- `RETRO_COMPLETE` with `DOCS_UPDATED` or `NO_DOC_CHANGE`, or `RETRO_BLOCKED` with the exact blocker;
 - documentation paths updated or intentionally unchanged;
-- durable knowledge decisions and validation evidence;
-- `RETRO_BLOCKED` with exact blockers when synchronization cannot complete.
+- durable knowledge decisions and validation evidence.
 
 Return only the listed retrospective outputs. Do not invoke another Skill.