prizmkit 1.1.153 → 1.1.155

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

@@ -0,0 +1,38 @@
+# Planning Artifact Identity
+
+Use one stable, project-relative artifact directory for the entire planning invocation.
+
+## Generated Directory
+
+When the caller does not provide `artifact_dir`:
+
+1. Inspect only direct child directories of `.prizmkit/specs/` whose basenames match `<number>-<slug>`, where `<number>` is at least three decimal digits.
+2. Choose one greater than the highest valid number, starting at `001`, and zero-pad to at least three digits. Numbers above `999` retain all digits.
+3. Derive `<slug>` from the concise requirement title:
+   - normalize text with Unicode NFKC and lowercase where the script has a lowercase form;
+   - retain Unicode letters and decimal digits;
+   - replace every run of other characters with one ASCII hyphen;
+   - trim leading/trailing hyphens;
+   - truncate without splitting a Unicode code point until the slug is at most 64 code points and the complete `<number>-<slug>` basename is at most 200 UTF-8 bytes, then trim a trailing hyphen;
+   - use `requirement` if no letter or digit remains.
+4. Create `.prizmkit/specs/<number>-<slug>/` without overwriting an existing path. If it appeared concurrently, rescan and retry with the next number; after three collisions, return `PLAN_BLOCKED`.
+
+Examples:
+
+```text
+.prizmkit/specs/001-user-login/
+.prizmkit/specs/070-skill-generated-artifact-contracts/
+.prizmkit/specs/1000-支付回调/
+```
+
+## Caller-Supplied Directory
+
+An explicit `artifact_dir` is preserved exactly; never slugify or relocate it. Before writing:
+
+- require a project-relative path that resolves inside the active checkout;
+- reject `.`/`..` components, control characters, symlink escape, and an empty basename;
+- require a basename of 1-96 Unicode code points and at most 200 UTF-8 bytes, containing only letters, decimal digits, ASCII hyphens, or ASCII underscores, with a letter or digit at both ends;
+- if existing `spec.md` or `plan.md` belongs to a different requirement, return `PLAN_BLOCKED` rather than overwrite it;
+- if the directory already contains the same requirement, reuse it and preserve its identity.
+
+The directory basename is the requirement identity exposed to callers. `spec.md` and `plan.md` are the only planning filenames in that directory.

package/bundled/skills/prizmkit-plan/references/independent-plan-review.md

@@ -54,7 +54,7 @@ spec_path: [EXACT_SPEC_PATH]
 plan_path: [EXACT_PLAN_PATH]
 ```
 
-The paths come from the current workflow state or explicit handoff even when ignored by Git. Never ask the Reviewer to discover a latest artifact or guess among multiple `spec.md` and `plan.md` files.
+The caller supplies these exact paths as planning-stage input even when ignored by Git. Never ask the Reviewer to discover a latest artifact or guess among multiple `spec.md` and `plan.md` files.
 
 The Plan Reviewer receives only:
 
@@ -90,7 +90,7 @@ Execution boundaries:
 - Complete this review personally.
 - Do not create, schedule, resume, continue, request, or coordinate another execution unit.
 - Do not ask the Main Agent to create a helper.
-- Do not re-enter orchestration, delegation, another review workflow, or an equivalent process.
+- Do not re-enter delegation or another review process.
 - Do not modify, create, delete, rename, stage, commit, or otherwise mutate files.
 - Do not execute shell, Git, tests, builds, network calls, external processes, or any operation that can change state.
 - Read only the supplied planning input at the exact paths and contents identified above.
@@ -133,7 +133,7 @@ All initial execution boundaries and the Reviewer Output Protocol remain mandato
 
 ## Reviewer Output Protocol
 
-Return exactly one of these forms. Do not add severity, confidence, dimension, workflow impact, or acceptance fields.
+Return exactly one of these forms. Do not add severity, confidence, dimension, caller-routing impact, or acceptance fields.
 
 ### No Correction Needed
 
@@ -181,7 +181,7 @@ Every correction contains only `Target`, `Problem`, `Evidence`, and `Correction`
 No review verdict was produced.
 ```
 
-`REVIEW_BLOCKED` is an internal independent-review result, not a lifecycle result.
+`REVIEW_BLOCKED` is an internal independent-review result, not the planning-stage result.
 
 ## Main-Agent Adjudication
 

package/bundled/skills/prizmkit-plan/references/review-plan-spec-loop.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Run this local planning-quality gate after `spec.md` and `plan.md` are drafted or updated, before handing off to `/prizmkit-implement`.
+Run this local planning-quality gate after `spec.md` and `plan.md` are drafted or updated, before returning `PLAN_READY`.
 
 This is not a separate skill and it does not use a Critic agent. It is the mandatory Main-Agent baseline executed inside `prizmkit-plan` to improve the planning artifacts only. Its maximum of two local rounds remains independent of the optional Reviewer described in `independent-plan-review.md`.
 
@@ -12,7 +12,7 @@ Do not do any of the following from this guide:
 
 - Start implementation or edit product/source code.
 - Run tests, builds, lint, or package commands.
-- Launch a feature, bugfix, or refactor pipeline.
+- Start implementation or any other execution process.
 - Spawn or require a Critic agent inside this Main-Agent loop. The separate optional independent review is considered only after this loop converges and only through `independent-plan-review.md`.
 - Create a separate review-loop skill.
 - Expand scope beyond improving `spec.md` and `plan.md`.
@@ -75,7 +75,7 @@ Examples:
 - Alternative task grouping with no correctness impact.
 - A lower-risk cleanup suggestion outside current scope.
 
-Optional findings do not block handoff.
+Optional findings do not block planning completion.
 
 ## Loop Algorithm
 
@@ -92,10 +92,10 @@ Optional findings do not block handoff.
 
 ## Output Summary
 
-At handoff, include a short summary:
+At completion, include a short summary:
 
 - Review rounds run: `1` or `2`.
 - Fixes applied to `spec.md`: short list or `none`.
 - Fixes applied to `plan.md`: short list or `none`.
 - Optional findings deferred: short list or `none`.
-- Unresolved blockers: `none` before handoff.
+- Unresolved blockers: `none` before `PLAN_READY`.

package/bundled/skills/prizmkit-prizm-docs/SKILL.md

@@ -111,9 +111,19 @@ Steps:
 6. Validate migrated docs against format rules and size limits.
 7. Report files processed, generated `.prizm` files, and manual review items.
 
+## Recovery Backup Contract
+
+Before replacing a corrupted `root.prizm`, copy its exact bytes outside the managed documentation tree:
+
+```text
+.prizmkit/backups/prizm-docs/root.prizm.bak
+```
+
+If that path exists, use the lowest available suffix `.001`, `.002`, and so on, for example `root.prizm.bak.001`. Never overwrite an earlier backup, never place backup files under `.prizmkit/prizm-docs/`, and never normalize or partially parse the backup content. Report the backup path before rebuilding. Backups are recovery copies, not Prizm documents or sources of durable knowledge.
+
 ## Error Handling
 
-- `root.prizm` corrupted or invalid: back it up, then rebuild affected docs from source.
+- `root.prizm` corrupted or invalid: create the byte-for-byte recovery backup above, then rebuild affected docs from source.
 - Broken pointers: create the missing `.prizm` file if the source module exists; remove the pointer if the source module was deleted.
 - Size limit exceeded: consolidate L0, move L1 implementation detail to L2, trim L2 derived detail.
 - No git history: fall back to filesystem timestamps for freshness checks and warn that accuracy is reduced.

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

@@ -1,80 +1,76 @@
 ---
 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 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 discovered during the task when such knowledge exists.
+2. **Knowledge Injection** — add durable TRAPS, RULES, and DECISIONS revealed by the supplied project change.
 
-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.
+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.
 
-## Formal Lifecycle Position
+## Input
 
-```text
-prizmkit-plan
-  → prizmkit-implement
-  → prizmkit-code-review
-  → prizmkit-test
-  → prizmkit-retrospective
-  → prizmkit-committer
-```
+| 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. |
+
+Do not discover a different artifact directory, expand the path set, or infer prerequisite work.
 
-## Atomic Stage Boundary
+## Atomic Boundary
 
-`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.
+`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.
 
 ## 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 documentation synchronization is resumed with the same explicit inputs.
+- The user explicitly requests a retrospective or documentation synchronization for a named 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.
+- 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.
 
-## Preconditions and Artifact Identity
+## Input Validation and Scope
 
-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.
+1. Resolve `artifact_dir` and every `change_paths` entry exactly as supplied.
+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.
 
-`.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.
+Only targeted `.prizmkit/prizm-docs/` changes and `{artifact_dir}/retrospective-result.json` are outputs.
 
 ## Job 1: Structural Sync
 
-When `.prizmkit/prizm-docs/` exists, read `${SKILL_DIR}/references/structural-sync-steps.md` and synchronize documentation with the final codebase changes.
+When `.prizmkit/prizm-docs/` exists, read `${SKILL_DIR}/references/structural-sync-steps.md` and synchronize documentation with the supplied project changes.
 
-Review only changed project files outside `.prizmkit/`:
+Review only supplied project files outside `.prizmkit/`:
 
 - 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;
+- 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.
 
-Never use `.prizmkit/` changes themselves as structural-sync input.
+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.
 
-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.
-
-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.
+Create a detail document only when the supplied change contains meaningful durable module knowledge.
 
 ## Job 2: Knowledge Injection
 
-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.
+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.
 
 Candidate knowledge includes:
 
@@ -83,73 +79,63 @@ Candidate knowledge includes:
 - interface or contract changes;
 - dependencies affecting module behavior;
 - observable behavior changes;
-- test-discovered boundaries or regression rules.
+- test-established boundaries or regression rules.
 
 Do not write transient artifact paths, task IDs, branch names, dates, session/run metadata, or changelog material into Prizm docs.
 
 When no durable structural or knowledge change exists, return `NO_DOC_CHANGE` and explain why.
 
-## Verification and Staging
+## Verification
 
 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`.
+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.
 
-## Retrospective Result
+## Result Artifact
 
-Write `{artifact_dir}/retrospective-result.json` for every formal requirement:
+Read `${SKILL_DIR}/references/retrospective-result-schema.json` and write `{artifact_dir}/retrospective-result.json` atomically:
 
 ```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"
+  "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
+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.
 
-Before reading or updating workflow state, read `${SKILL_DIR}/references/workflow-state-protocol.md`.
+`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.
 
-On successful completion, update `.prizmkit/state/workflows/<requirement-slug>.json`:
+If documentation validation or synchronization cannot safely complete, atomically write the same seven-key shape with `result: null`:
 
 ```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": "Exact validation or synchronization blocker",
+  "change_paths": ["src/example.py"],
+  "documentation_paths": [".prizmkit/prizm-docs/example/module.prizm"],
+  "validation": ["validation command or check that failed"]
 }
 ```
 
-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.
+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`.
 
-If documentation validation or synchronization cannot safely complete, return `RETRO_BLOCKED`, do not commit, and provide the exact recovery entry.
+## Output
 
-## Output and Handoff
+Return only:
 
-Report:
-
-- `{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`;
+- documentation paths updated or intentionally unchanged;
+- durable knowledge decisions and validation evidence;
+- `RETRO_BLOCKED` with exact blockers when synchronization cannot complete.
 
-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

@@ -7,7 +7,7 @@
 - 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
 
-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.
+Do not scan or mine generated records for retrospective knowledge. Caller metadata and existing Prizm docs may describe transient or generated material; they must not create a retrospective fact independently of an observed change in the exact non-`.prizmkit/` project paths supplied as input.
 
 **2b.** Extract knowledge from what was **observed in code**, not invented:
 
@@ -41,10 +41,10 @@ When writing TRAPS:
 
 **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.
 
-**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.
+**MEMORY HYGIENE GATE**: Before writing any `.prizmkit/prizm-docs/` entry, remove transient caller metadata. Never write CHANGELOG sections/files, UPDATED/date metadata, internal execution IDs, branch names, absolute worktree paths, or generated artifact paths. Write only durable product/domain facts established by the supplied project changes.
 
 **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.)
+- Module-level TRAPS/RULES/DECISIONS → the affected detail `.prizm` file. If the target detail document does not exist, create it from the detail-document generation template before injecting knowledge. These sections belong in detail documentation, not the module index.
 - Project-level RULES/PATTERNS → `root.prizm` (respect the current format — MODULE_INDEX or MODULE_GROUPS — do not convert between them during injection)
 - Cross-module concerns spanning 2+ modules → `root.prizm` CROSS_CUTTING section
 

package/bundled/skills/prizmkit-retrospective/references/retrospective-result-schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "PrizmKit Retrospective Result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "outcome",
+    "result",
+    "reason",
+    "change_paths",
+    "documentation_paths",
+    "validation"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "outcome": {
+      "enum": ["RETRO_COMPLETE", "RETRO_BLOCKED"]
+    },
+    "result": {
+      "enum": ["DOCS_UPDATED", "NO_DOC_CHANGE", null]
+    },
+    "reason": {
+      "type": "string",
+      "minLength": 1
+    },
+    "change_paths": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "allOf": [
+          {
+            "not": {
+              "pattern": "\\\\"
+            }
+          },
+          {
+            "not": {
+              "pattern": "^/"
+            }
+          },
+          {
+            "not": {
+              "pattern": "//"
+            }
+          },
+          {
+            "not": {
+              "pattern": "(?:^|/)\\.\\.?(?:/|$)"
+            }
+          },
+          {
+            "not": {
+              "pattern": "^\\.prizmkit(?:/|$)"
+            }
+          }
+        ]
+      }
+    },
+    "documentation_paths": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^\\.prizmkit/prizm-docs/.+\\.prizm$",
+        "allOf": [
+          {
+            "not": {
+              "pattern": "\\\\"
+            }
+          },
+          {
+            "not": {
+              "pattern": "//"
+            }
+          },
+          {
+            "not": {
+              "pattern": "(?:^|/)\\.\\.?(?:/|$)"
+            }
+          }
+        ]
+      }
+    },
+    "validation": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  },
+  "oneOf": [
+    {
+      "properties": {
+        "outcome": {
+          "const": "RETRO_COMPLETE"
+        },
+        "result": {
+          "enum": ["DOCS_UPDATED", "NO_DOC_CHANGE"]
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "result": {
+                "const": "DOCS_UPDATED"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "documentation_paths": {
+                "minItems": 1
+              },
+              "validation": {
+                "minItems": 1
+              }
+            }
+          }
+        }
+      ]
+    },
+    {
+      "properties": {
+        "outcome": {
+          "const": "RETRO_BLOCKED"
+        },
+        "result": {
+          "type": "null"
+        }
+      }
+    }
+  ]
+}

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

@@ -1,16 +1,10 @@
 # Structural Sync — Detailed Steps
 
-## 1. Get changed files
+## 1. Validate supplied changed files
 
-Get changed project files from staged and unstaged changes relative to HEAD while excluding the entire `.prizmkit/` tree:
+Use only the caller-supplied `change_paths`. Normalize each repository-relative path, reject paths outside the checkout or under `.prizmkit/`, and verify its current added/modified/deleted/renamed state with exact pathspecs.
 
-```bash
-git diff HEAD --name-status -- . ':(exclude).prizmkit/**'
-```
-
-If pathspec exclusion is unavailable, filter every result whose normalized repository-relative path is exactly `.prizmkit` or starts with `.prizmkit/` before classification. Do not infer project structure or durable knowledge from excluded files.
-
-If the caller supplied an explicit file list, apply the same `.prizmkit/` exclusion before using it and note the source in the report. If no files remain, structural sync is not needed.
+Do not expand the path set through repository-wide status or diff discovery. If the validated list is empty, structural sync is not needed.
 
 ## 2. Map files to modules
 
@@ -42,11 +36,11 @@ Do not skip automatically just because the task is a bug fix or test change. Run
 
 ## 5. Update affected docs bottom-up
 
-### L2
+### Detail documentation
 
-If L2 exists, update only sections affected by changed files in that module.
+If a relevant detail document exists, update only sections affected by supplied changed files in that module.
 
-If L2 does not exist and the current diff includes Added or Modified source files with meaningful logic, create L2 with:
+If detail documentation does not exist and the supplied changes include Added or Modified source files with meaningful logic, create it with:
 
 ```text
 MODULE
@@ -60,35 +54,35 @@ TRAPS
 
 Add DATA_FLOW, RULES, or DECISIONS only when the changed files provide durable information for those sections. Populate from the diff files and targeted source reads, not from an unbounded full-module rescan.
 
-### L1
+### Module index
 
 Update FILES count, KEY_FILES, SUBDIRS, and DEPENDENCIES when module-level structure changes.
 
-L1 does not contain INTERFACES, DATA_FLOW, TRAPS, or DECISIONS; those belong in L2.
+Module indexes do not contain INTERFACES, DATA_FLOW, TRAPS, or DECISIONS; those belong in detail documentation.
 
-### L0
+### Root project map
 
-Update MODULE_INDEX or MODULE_GROUPS only when module structure changed. Preserve any `PROJECT_BRIEF:` line because it is managed by `/prizmkit-init`.
+Update MODULE_INDEX or MODULE_GROUPS only when module structure changed. Preserve any `PROJECT_BRIEF:` line because it is managed separately.
 
 ## 6. New module handling
 
 If a new directory qualifies as a module and matches no existing module:
 
-1. Create L1 immediately.
+1. Create its module index immediately.
 2. Add it to MODULE_INDEX or MODULE_GROUPS.
-3. Create L2 only when the current diff includes meaningful Added or Modified source files for the module.
+3. Create detail documentation only when the supplied changes include meaningful Added or Modified source files for the module.
 
 ## 7. Size limits
 
-- L0 > 4KB → consolidate MODULE_INDEX or convert to MODULE_GROUPS when module count is high
-- L1 > 4KB → trim KEY_FILES descriptions and keep RULES concise
-- L2 > 5KB → remove derived detail or stale entries; keep durable knowledge only
+- Root project map > 4KB → consolidate MODULE_INDEX or convert to MODULE_GROUPS when module count is high
+- Module index > 4KB → trim KEY_FILES descriptions and keep RULES concise
+- Detail document > 5KB → remove derived detail or stale entries; keep durable knowledge only
 
 ## 8. TRAPS staleness check
 
-Run only when an L2 doc's TRAPS section has more than 10 entries.
+Run only when a detail document's TRAPS section has more than 10 entries.
 
-Process at most 5 oldest TRAPS per L2 doc:
+Process at most 5 oldest TRAPS per detail document:
 
 1. If a TRAP has `STALE_IF:` and matched files no longer exist, delete the TRAP.
 2. If a TRAP has `REF:` and the referenced file is gone or the commit is older than the review horizon, mark it `[REVIEW]` for the next knowledge pass.