prizmkit 1.1.154 → 1.1.155

package/bundled/skills/prizmkit-implement/references/implementation-subagent-procedure.md

@@ -29,8 +29,8 @@ Do not create worktrees, copied repositories, remote checkouts, or branch switch
 1. Read `context-snapshot.md` first when it exists.
 2. Use Section 3 for relevant Prizm rules/traps and Section 4 File Manifest for file summaries.
 3. Do not re-read files already summarized in the File Manifest unless a specific implementation detail is missing.
-4. If no context snapshot exists, read `.prizmkit/prizm-docs/root.prizm`, relevant L1/L2 docs, then targeted source files.
-5. If a relevant L2 doc is missing, use source fallback and note that retrospective may create or update docs later.
+4. If no context snapshot exists, read `.prizmkit/prizm-docs/root.prizm`, follow only relevant module/detail pointers, then read targeted source files.
+5. If relevant detail documentation is missing, use source fallback and note the missing context without creating documentation.
 
 ## Implementation Rules
 
@@ -41,7 +41,7 @@ Do not create worktrees, copied repositories, remote checkouts, or branch switch
 - Do not execute git `add`, `commit`, `reset`, `push`, branch checkout, rebase, merge, or stash operations.
 - Do not spawn further agents.
 - Do not perform broad repository rediscovery. Read only delegated files and targeted dependencies needed for correctness.
-- Do not write PrizmKit feature/bug/refactor/task/session/run IDs, pipeline IDs, workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths into `.prizmkit/prizm-docs/`, user-visible UI text, API responses, emails, notifications, or expected product-copy tests.
+- Do not write internal execution IDs, branch names, absolute worktree paths, or runtime artifact paths into `.prizmkit/prizm-docs/`, user-visible UI text, API responses, emails, notifications, or expected product-copy tests.
 - If creating a new sub-module, note the durable facts needed for retrospective; do not overwrite existing `.prizmkit/prizm-docs/` files in full.
 
 ## Output Format
@@ -61,7 +61,7 @@ Report exactly:
 - command/check: result
 
 ### Notes for Main Agent
-- durable decisions, missing L2 docs, or blockers
+- durable decisions, missing detail documentation, or blockers
 ```
 
 For `WRONG_CHECKOUT`, include only the checkout mismatch evidence and do not include normal implementation findings.

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

@@ -23,6 +23,10 @@ Recommended project initialization skill. Scans any brownfield or greenfield pro
 - If artifacts already exist: idempotent status check offers regenerate/skip choices (see Phase 3: Idempotent Status Check)
 - If no source files found in any directory: fall back to greenfield mode
 
+### Artifact Ownership
+
+All paths under `.prizmkit/` are framework-internal and remain outside automated task commits. Initialization must not stage or commit them. Root instruction or platform-support files written during setup also remain support data rather than task-owned source.
+
 ## Execution Steps
 
 **Phase 1: Platform Detection**

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

@@ -1,11 +1,11 @@
 ---
 name: "prizmkit-plan"
-description: "Start the formal PrizmKit requirement lifecycle by turning a natural-language change into spec.md and plan.md artifacts, running mandatory Main-Agent planning review plus optional capability-gated independent correctness review, initializing workflow state, and handing off to prizmkit-implement. Works for features, bug fixes, refactors, migrations, tests, and other formal requirements. (project)"
+description: "Create and review spec.md and plan.md artifacts for one supplied software requirement. Covers features, bug fixes, refactors, migrations, tests, and other scoped changes; returns PLAN_READY or PLAN_BLOCKED. (project)"
 ---
 
 # PrizmKit Plan
 
-`/prizmkit-plan` is the entry point for one formal requirement. It converts a natural-language change into a reviewed change artifact: `spec.md` defines WHAT and WHY; `plan.md` defines HOW and executable tasks.
+`/prizmkit-plan` converts one caller-supplied natural-language change into a reviewed change artifact: `spec.md` defines WHAT and WHY; `plan.md` defines HOW and executable tasks.
 
 A change artifact can describe a feature, bug fix, refactor, migration, test improvement, or another scoped requirement.
 
@@ -19,47 +19,34 @@ A change artifact can describe a feature, bug fix, refactor, migration, test imp
 ## When NOT to Use
 
 - Direct edit: typo, pure formatting, small documentation edit, or another explicitly low-risk non-requirement change.
-- The active artifact directory already has an adequate reviewed `spec.md` and `plan.md`; resume from the workflow state instead.
-
-## Formal Lifecycle
-
-A successful plan starts this fixed lifecycle:
-
-```text
-plan → implement → code-review → test → retrospective → committer
-```
-
-Planning depth may be concise or comprehensive, but no later formal lifecycle stage may be silently skipped.
+- The supplied artifact directory already has an adequate reviewed `spec.md` and `plan.md`; return the existing stage result instead of regenerating them.
 
 ## Input
 
 | Parameter | Required | Description |
 |---|---|---|
 | `description` | Yes | Natural-language description of the requirement. |
-| `artifact_dir` | No | Directory for the change artifact. If omitted, create a numbered slug under `.prizmkit/specs/`. |
+| `artifact_dir` | No | Exact caller-supplied directory for the change artifact. If omitted, create a deterministic numbered directory under `.prizmkit/specs/` using `${SKILL_DIR}/references/artifact-identity.md`. |
 
 ## Atomic Stage Boundary
 
-`prizmkit-plan` owns only specification, plan, task generation, and planning-quality review. It writes its truthful terminal result and `next_stage`, then returns control. It must not invoke `prizmkit-implement` itself, including when an external orchestrator is active. The active orchestrator owns the next-stage invocation.
+`prizmkit-plan` owns specification, plan, task generation, and planning-quality review for one supplied requirement. Its terminal outputs are `PLAN_READY` or `PLAN_BLOCKED`; it stops after producing that result.
 
 ## Phase 0: Initialization Check and Context
 
 1. Check whether project context such as `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json`, or a project brief exists.
-2. If initialization context is missing:
-   - recommend `/prizmkit-init` and explain that it improves project context and cross-session continuity;
-   - do not block planning;
-   - if the user continues, load the README, manifests, project instruction files, source structure, and relevant source files as fallback.
-3. If Prizm docs exist, read `root.prizm`, relevant L1 docs, relevant L2 docs when present, and source fallback when L2 is absent.
-4. Resolve `artifact_dir` once and reuse it for every later lifecycle handoff. Do not re-detect another artifact during the same requirement.
+2. If initialization context is missing, do not block planning; load the README, manifests, project instruction files, source structure, and relevant source files as fallback.
+3. If Prizm docs exist, read `root.prizm`, follow only its relevant module/detail pointers, and use source fallback when detailed documentation is absent.
+4. Read `${SKILL_DIR}/references/artifact-identity.md`, validate or generate `artifact_dir` exactly once, and keep it stable throughout this planning invocation.
 
 ## Phase 1: Specify (`spec.md`)
 
 Skip regeneration when `spec.md` already exists and still matches the requested requirement.
 
 1. Gather the requirement description. If it is missing in an interactive run, ask the user; otherwise return a clear blocked result.
-2. Determine the artifact directory:
-   - use the caller-provided `artifact_dir` when present;
-   - otherwise scan `.prizmkit/specs/` for existing numbered directories and create `.prizmkit/specs/###-task-slug/`.
+2. Determine the artifact directory through `${SKILL_DIR}/references/artifact-identity.md`:
+   - validate and preserve the exact caller-provided `artifact_dir` when present;
+   - otherwise derive the normalized title slug, allocate the next collision-safe number, and create `.prizmkit/specs/<number>-<slug>/`.
 3. Generate `spec.md` from `${SKILL_DIR}/assets/spec-template.md`:
    - focus on WHAT and WHY, not HOW;
    - include only relevant sections;
@@ -86,7 +73,7 @@ Precondition: `spec.md` exists with no unresolved blocker.
    - component and file changes;
    - data migration approach when relevant;
    - interface/API contract design when relevant;
-   - test strategy for the mandatory `/prizmkit-test` stage;
+   - project-native test strategy appropriate to the requirement;
    - risks and mitigations;
    - behavior-preservation strategy for refactors.
 5. Cross-check every spec goal against the plan.
@@ -98,7 +85,7 @@ Precondition: `spec.md` exists with no unresolved blocker.
 2. Append `## Tasks` to `plan.md` using `${SKILL_DIR}/assets/plan-template.md`.
 3. Include setup, foundation, core, polish, and checkpoint tasks only when applicable.
 4. Mark `[P]` only for tasks that can safely execute independently.
-5. Include implementation-local verification where useful, while preserving the later full code-review and test stages.
+5. Include appropriate implementation-local and regression verification tasks without executing them during planning.
 6. Run `${SKILL_DIR}/references/verification-checklist.md` and repair plan defects.
 
 ## Phase 4: Plan/Spec Review Loop
@@ -113,7 +100,7 @@ Run every time `spec.md` or `plan.md` is created or changed. This is the mandato
 6. If a `BLOCKER` remains, ask targeted questions in interactive mode; otherwise record `PLAN_BLOCKED` and stop.
 7. Continue only when no unresolved blocker remains.
 
-The planning review must not implement code, run the full test stage, or launch external orchestration.
+The planning review must not modify product/source code or execute the planned verification strategy.
 
 ## Phase 5: Independent Plan Review
 
@@ -127,47 +114,17 @@ Run only after the Main-Agent Plan/Spec review converges. This optional check ne
 6. If neither compliant continuation nor replacement is available after modification, record downgrade and rerun the Main-Agent local Plan/Spec review over that modification as specified by the reference.
 7. If the final allowed response causes a modification, run targeted verification, record that the final state was not independently rechecked, and do not exceed the response budget.
 8. Append the terminal `## Independent Plan Review` record. Appending that audit record does not trigger another response.
-9. Any unresolved correction produces `PLAN_BLOCKED`; otherwise independent convergence or strict downgrade may continue to handoff from the valid completed Main-Agent review.
-
-## Phase 6: Workflow State and Handoff
-
-Read `${SKILL_DIR}/references/workflow-state-protocol.md` and create or update:
-
-```text
-.prizmkit/state/workflows/<requirement-slug>.json
-```
-
-Follow the bundled protocol. At minimum record:
-
-```json
-{
-  "schema_version": 1,
-  "artifact_dir": ".prizmkit/specs/001-example",
-  "stage": "plan",
-  "status": "completed",
-  "stage_result": "PLAN_READY",
-  "completed_stages": ["plan"],
-  "repair_round": 0,
-  "repair_scope": null,
-  "next_stage": "implement",
-  "resume_from": "prizmkit-implement"
-}
-```
-
-The state file is runtime metadata. Do not change the target project's Git or ignore policy.
+9. Any unresolved correction produces `PLAN_BLOCKED`; otherwise independent convergence or strict downgrade produces `PLAN_READY`.
 
 ## Output
 
-- `spec.md` and `plan.md` in the resolved artifact directory.
-- Workflow state with `PLAN_READY` or a truthful blocked result.
-- Planning depth, key decisions, task count, and checkpoint summary.
-- The same `artifact_dir` for every downstream stage.
-
-## Handoff
+Return only planning-stage outputs:
 
-On `PLAN_READY`:
+- the resolved `artifact_dir`;
+- `spec.md` and `plan.md` paths;
+- planning depth, key decisions, and task count;
+- `PLAN_READY` when artifacts pass planning review, otherwise `PLAN_BLOCKED` with unresolved planning blockers.
 
-1. If workflow state names an active `orchestrator`, return `PLAN_READY`, `stage_result=PLAN_READY`, `next_stage=implement`, the state path, and the same `artifact_dir` to that orchestrator; do not invoke the next stage independently.
-2. For direct stage use with no active orchestrator, report exactly one deterministic next action: `/prizmkit-implement`, with `stage_result=PLAN_READY`, the state-file path, and `artifact_dir`; a host may perform that semantic handoff on the user's behalf.
+Return only the listed planning outputs. Do not invoke another Skill.
 
 Read `${SKILL_DIR}/references/examples.md` only when a worked planning example is needed.

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