prizmkit 1.1.154 → 1.1.156

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

@@ -1,155 +1,152 @@
 ---
 name: "prizmkit-retrospective"
-description: "Mandatory retrospective stage after a formal requirement passes code review and testing. Synchronizes durable Prizm documentation or records that no documentation change is needed, updates workflow state, and hands off to prizmkit-committer. (project)"
+description: "Synchronize durable Prizm documentation for one caller-supplied project change, or record that no documentation update is warranted. Writes retrospective-result.json and returns RETRO_COMPLETE or RETRO_BLOCKED. (project)"
 ---
 
 # PrizmKit Retrospective
 
-`/prizmkit-retrospective` is the mandatory documentation and durable-knowledge stage after `prizmkit-test` returns `TEST_PASS`.
+`/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:
+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.
 
-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 discovered during the task when such knowledge exists.
+## Input
 
-The stage must always run for a formal requirement. When no documentation update is warranted, it records `NO_DOC_CHANGE` as a successful retrospective result rather than silently skipping the stage.
+| Parameter | Required | Description |
+|---|---|---|
+| `artifact_dir` | Yes | Exact caller-supplied directory in which to write `retrospective-result.json`. |
+| `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. |
 
-For first-time documentation setup, validation, rebuild, migration, or out-of-band repair after docs drift, use `/prizmkit-prizm-docs` independently.
+Do not discover a different artifact directory, expand the path set, or infer prerequisite work.
 
-## Formal Lifecycle Position
+## Atomic Boundary
 
-```text
-prizmkit-plan
-  → prizmkit-implement
-  → prizmkit-code-review
-  → prizmkit-test
-  → prizmkit-retrospective
-  → prizmkit-committer
-```
-
-## Atomic Stage Boundary
+`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.
 
-`prizmkit-retrospective` owns only structural documentation synchronization, durable knowledge injection, and retrospective result recording. It writes its truthful completion status and result plus `next_stage`, then returns control. It must not invoke `prizmkit-committer` itself; the active orchestrator owns the next-stage invocation.
+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
 
-- After `/prizmkit-test` returns `TEST_PASS` for a formal requirement.
-- When workflow state resumes a previously interrupted retrospective.
-- When the user explicitly requests a retrospective or documentation synchronization outside a formal requirement.
+- A caller supplies exact project change paths that may affect durable documentation.
+- 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 requirement has not passed code review and testing.
-- `TEST_NEEDS_FIXES` or `TEST_BLOCKED` remains unresolved.
-- The request is a direct edit outside the formal requirement lifecycle, unless the user explicitly asks for documentation maintenance.
-- First-time docs initialization or out-of-band docs repair; 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.
+
+## Exact Input Scope and Candidate Authority
+
+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 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.
 
-## Preconditions and Artifact Identity
+## Value and Cleanup Gates
 
-1. Reuse the caller's `artifact_dir`; do not select another requirement.
-2. Confirm the latest review result is `PASS`.
-3. Confirm the latest testing result is `TEST_PASS`.
-4. Read the final source diff with `.prizmkit/` excluded, then use `spec.md`, `plan.md`, the final `review-report.md`, `test-report.md`, and `test-result.json` only as supporting context for the non-`.prizmkit/` changes.
-5. If the workflow state is missing or stale, reconstruct it from those authoritative artifacts and report the reconstruction.
+Before retaining any candidate from an eligible source change, ask:
 
-`.prizmkit/` is always excluded from retrospective project-change input scope. Do not treat any file under `.prizmkit/`—including plans, artifacts, state, evidence, or existing Prizm docs—as a changed project file from which structural or durable knowledge is inferred. Required lifecycle state/evidence writes and targeted `.prizmkit/prizm-docs/` updates remain outputs; documentation changes must be justified only by observed non-`.prizmkit/` project changes.
+> Could a future AI that lacks this fact make an incorrect modification?
 
-## Job 1: Structural Sync
+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.
 
-When `.prizmkit/prizm-docs/` exists, read `${SKILL_DIR}/references/structural-sync-steps.md` and synchronize documentation with the final codebase changes.
+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.
 
-Review only changed project files outside `.prizmkit/`:
+For every existing target:
 
-- 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 non-`.prizmkit/` 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.
+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.
 
-Never use `.prizmkit/` changes themselves as structural-sync input.
+Read `${SKILL_DIR}/references/knowledge-injection-steps.md` for candidate extraction and injection details.
 
-When `.prizmkit/prizm-docs/` does not exist, do not pretend structural sync occurred. Record `NO_DOC_CHANGE` with reason `PRIZM_DOCS_NOT_INITIALIZED` and recommend `/prizmkit-init` or `/prizmkit-prizm-docs` for a future setup. The formal lifecycle may still continue because initialization is a soft prerequisite.
+## Capacity Preflight and Structural Sync
 
-Do not create an L2 document merely because one was missing during implementation. Create it only when the final change contains meaningful durable module knowledge.
+Read `${SKILL_DIR}/references/structural-sync-steps.md` and run its preflight for every target before replacement:
 
-## Job 2: Knowledge Injection
+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.
 
-When the final project change outside `.prizmkit/` reveals durable knowledge, read `${SKILL_DIR}/references/knowledge-injection-steps.md` and inject only stable product/domain knowledge into Prizm docs.
+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.
 
-Candidate knowledge includes:
+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.
 
-- new traps, race conditions, or surprising coupling;
-- architectural rules or decisions;
-- interface or contract changes;
-- dependencies affecting module behavior;
-- observable behavior changes;
-- test-discovered boundaries or regression rules.
+## Safe Write, Verification, and Idempotency
 
-Do not write transient artifact paths, task IDs, branch names, dates, session/run metadata, or changelog material into Prizm docs.
+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.
 
-When no durable structural or knowledge change exists, return `NO_DOC_CHANGE` and explain why.
+When `.prizmkit/prizm-docs/` does not exist, record `NO_DOC_CHANGE` with reason `PRIZM_DOCS_NOT_INITIALIZED` and recommend initialization as a separate action.
 
-## Verification and Staging
+## Capacity Blocker Contract
 
-1. Validate any updated docs using the project documentation rules.
-2. Review the final diff and ensure only intended documentation changes are present.
-3. Do not change the target project's Git or ignore policy. If the host or project workflow stages docs, report what was staged; otherwise leave staging to `/prizmkit-committer`.
-4. Never claim documentation synchronization passed if validation failed.
+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`.
 
-## Retrospective Result
+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.
 
-Write `{artifact_dir}/retrospective-result.json` for every formal requirement:
+## Result Artifact
+
+Read `${SKILL_DIR}/references/retrospective-result-schema.json` and atomically write `{artifact_dir}/retrospective-result.json` with exactly these seven keys:
 
 ```json
 {
-  "status": "completed",
-  "stage_result": "RETRO_COMPLETE",
+  "schema_version": 1,
+  "outcome": "RETRO_COMPLETE",
   "result": "DOCS_UPDATED",
-  "reason": "Durable module interfaces and traps changed",
-  "review_verdict": "PASS",
-  "test_verdict": "TEST_PASS"
+  "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"]
 }
 ```
 
-`status=completed` is the stable lifecycle status. `stage_result=RETRO_COMPLETE` marks successful retrospective completion; `result` must be exactly `DOCS_UPDATED` or `NO_DOC_CHANGE`. Use `result=NO_DOC_CHANGE` with a concrete reason when no documentation update is warranted. This artifact is the retrospective gate evidence consumed by the committer and external automation; workflow state alone does not prove completion.
-
-## Workflow State and Handoff
-
-Before reading or updating workflow state, read `${SKILL_DIR}/references/workflow-state-protocol.md`.
+Every retrospective artifact has exactly these seven keys: `schema_version`, `outcome`, `result`, `reason`, `change_paths`, `documentation_paths`, and `validation`.
 
-On successful completion, update `.prizmkit/state/workflows/<requirement-slug>.json`:
+A capacity or validation blocker uses the same shape without adding state:
 
 ```json
 {
-  "stage": "retrospective",
-  "status": "completed",
-  "stage_result": "RETRO_COMPLETE",
-  "completed_stages": ["plan", "implement", "code-review", "test", "retrospective"],
-  "next_stage": "committer",
-  "resume_from": "prizmkit-committer"
+  "schema_version": 1,
+  "outcome": "RETRO_BLOCKED",
+  "result": null,
+  "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": [],
+  "validation": ["candidate raw UTF-8 capacity check: 5200B > 5120B", "semantic ownership check: ambiguous"]
 }
 ```
 
-Use `status=completed` and `stage_result=RETRO_COMPLETE` for both successful outcomes, with `result=DOCS_UPDATED` when durable docs changed or `result=NO_DOC_CHANGE` when the stage completed without a docs update. Both result values permit the commit stage.
+- `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.
 
-If documentation validation or synchronization cannot safely complete, return `RETRO_BLOCKED`, do not commit, and provide the exact recovery entry.
+Do not add checkpoint, routing, capacity-state, caller-state, evidence-manifest, hash, or attestation fields.
 
-## Output and Handoff
+## Output
 
-Report:
+Return only:
 
-- `{artifact_dir}/retrospective-result.json` with `DOCS_UPDATED` or `NO_DOC_CHANGE`;
-- docs updated, created, or intentionally unchanged;
-- durable knowledge decisions;
-- validation evidence;
-- workflow state path and status;
-- the same `artifact_dir` for the next stage.
-
-After `RETRO_COMPLETE`:
-
-```text
-RETRO_COMPLETE
-  → /prizmkit-committer
-```
+- `artifact_dir` and `retrospective-result.json` path;
+- `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.
 
-If workflow state names an active `orchestrator`, return `RETRO_COMPLETE`, `stage_result`, the retrospective/state paths, and `next_stage=committer` to it; do not invoke the committer independently. For direct stage use, provide the deterministic `/prizmkit-committer` invocation; a host may perform that semantic handoff on the user's behalf.
+Return only the listed retrospective outputs. Do not invoke another Skill.

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

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