prizmkit 1.1.154 → 1.1.156

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

@@ -34,6 +34,54 @@ Do not route ordinary development-loop "update docs" or "sync docs" here. In nor
 
 Key principle: `/prizmkit-prizm-docs` defines and repairs the documentation system. `/prizmkit-retrospective` keeps docs in sync during ordinary development.
 
+## Governing Content Gates
+
+These gates apply uniformly wherever this Skill generates, migrates, repairs, or rebuilds documentation. Operation references may add sequencing but must not weaken them.
+
+### Value Gate
+
+Before retaining any candidate fact, ask exactly:
+
+> Could a future AI that lacks this fact make an incorrect modification?
+
+Retain the fact only when the answer is yes and the fact is current, durable, non-obvious, and stated at the lowest owning level. High-value knowledge includes:
+
+- non-obvious public interfaces and wire contracts
+- cross-module constraints and non-obvious dependencies
+- traps and side effects that can cause an incorrect change
+- durable decisions with only the rationale necessary to preserve the choice
+- rejected alternatives that future sessions are likely to propose again, with the reason for rejection
+- security, data-integrity, concurrency, transaction, and compatibility rules
+
+Reject source-derivable structure or signatures, task/change history, test inventories, temporary conclusions, stale statements, duplicate meanings, long procedures, low-value file lists, and facts already owned by a child detail document. File names, counts, and summaries remain only when needed for navigation or ownership.
+
+Critical-knowledge rule: a still-valid public or wire contract, cross-module constraint, non-obvious dependency, critical trap, durable decision, side effect, or safety/integrity rule must survive cleanup and capacity remediation. Never delete it merely to satisfy a byte check.
+
+### Cleanup Gate
+
+Before Update or Rebuild writes an existing target:
+
+1. Read the target and its resolving parent/child pointers first.
+2. Build a protected set of still-valid critical knowledge under the Value Gate.
+3. Match facts by semantic meaning, not wording; update an equivalent entry in place and merge synonymous entries.
+4. Remove stale, duplicate, parent-copied, source-derivable, and otherwise low-value material.
+5. Add only genuinely new durable knowledge that has no equivalent entry.
+6. Keep L0 and L1 as concise structural summaries and pointers; do not copy L2 interfaces, data flow, traps, decisions, or full rules into a parent.
+
+Append-only synchronization is prohibited. If protected knowledge cannot fit after safe cleanup, movement to the owning child, or an unambiguous semantic split, report the blocker instead of deleting knowledge.
+
+### Capacity and Sharding Invariants
+
+Use the canonical capacity classifier: exact raw UTF-8 bytes; L0 `root.prizm` limit 4096B; direct-child L1 limit 4096B; nested L2 limit 5120B. Bands are normal below 80%, warning from 80% to below 90%, strong warning from 90% through 100%, and error above 100%.
+
+- Natural content below 80% stays unchanged; do not pad it.
+- Warning-range content remains valid and is reported without failure.
+- A generated or rewritten target at 90% or above requires cleanup, movement, or a safe split. After automatic remediation, measure every affected parent and child: each must be within its hard limit and the operation targets 3277–3686B for L0/L1 or 4096–4607B for L2 (80% to below 90%), not one byte below the hard limit. A naturally concise result below 80% stays unpadded.
+- Any target still above its hard limit blocks completion. A warning must never downgrade another format or hard-limit error.
+- When L0 navigation cannot fit, use `MODULE_GROUPS`; never raise limits for project size.
+- When one L2 cannot safely retain a flat module's multiple stable behavior concerns, use the semantic L2 policy in the format specification. Preserve mirrored L2 paths for real source submodules.
+- Do not add a memory state machine, scoring system, project-size override, task-named or numbered shard, or a fourth documentation level.
+
 ### When to Use
 - First-time project documentation setup
 - Checking whether docs are fresh or valid
@@ -52,7 +100,7 @@ Bootstrap `.prizmkit/prizm-docs/` for the current project.
 
 Precondition: no `.prizmkit/prizm-docs/` directory exists, or user confirms overwrite.
 
-Read `${SKILL_DIR}/references/op-init.md` for detailed steps.
+Read `${SKILL_DIR}/references/op-init.md` for detailed steps. Apply the Value Gate before retaining every generated fact.
 
 ## Operation: Update
 
@@ -70,7 +118,7 @@ Use Update only when docs drifted outside the normal development loop, such as:
 
 During normal feature/bugfix/refactor work, do not use Update; use `/prizmkit-retrospective` to avoid duplicate writers and conflicting edits.
 
-Read `${SKILL_DIR}/references/op-update.md` for detailed steps.
+Read `${SKILL_DIR}/references/op-update.md` for detailed steps. Apply both the Value Gate and target-first Cleanup Gate to every written target.
 
 ## Operation: Status
 
@@ -86,7 +134,7 @@ Regenerate docs for a specific module from scratch.
 
 Precondition: `.prizmkit/prizm-docs/` exists and module path is valid.
 
-Read `${SKILL_DIR}/references/op-rebuild.md` for detailed steps.
+Read `${SKILL_DIR}/references/op-rebuild.md` for detailed steps. Rebuild from current source analysis without delete-first loss: preserve the target-first inventory, then apply both governing gates.
 
 ## Operation: Validate
 
@@ -104,24 +152,40 @@ Precondition: existing `docs/`, `docs/AI_CONTEXT/`, README, or architecture docs
 
 Steps:
 1. Discover existing docs: `docs/`, `docs/AI_CONTEXT/`, `README.md`, `ARCHITECTURE.md`, and structured documentation files.
-2. Extract project metadata, module descriptions, architecture patterns, rules, decisions, and dependencies.
-3. Map project-wide info to L0, module structure to L1, and behavioral details to L2.
-4. Convert prose to KEY: value format and strip markdown tables, diagrams, and decorative formatting.
-5. Generate `.prizmkit/prizm-docs/` using init structure seeded with extracted information.
-6. Validate migrated docs against format rules and size limits.
-7. Report files processed, generated `.prizm` files, and manual review items.
+2. Treat every extracted statement as a candidate, verify it against current source, and apply the Value Gate. Do not migrate source-derivable structure, task/history material, test inventories, temporary conclusions, stale statements, duplicate meanings, long procedures, or low-value file lists.
+3. Map project-wide summaries and pointers to L0, module structure and pointers to L1, and retained behavioral knowledge to L2. When a child L2 owns complete knowledge, keep only a concise parent summary and resolving pointer.
+4. Preserve source-mirrored L2 paths for real submodules. For a flat module that needs multiple stable behavior concerns to retain required knowledge within 5120B, apply the deterministic semantic-detail identity, ownership, `DETAILS` pointer, and ambiguity-blocking contract in the format specification.
+5. Convert retained content to KEY: value format and strip markdown tables, diagrams, decorative formatting, and procedural prose. Merge semantically equivalent source statements before writing.
+6. Generate `.prizmkit/prizm-docs/` using the Init structure seeded only with retained content; use `MODULE_GROUPS` when the L0 map cannot fit within 4096B.
+7. Run the canonical capacity classifier. Warning-only results remain successful; remediate strong-warning/error generated targets toward 3277–3686B for L0/L1 or 4096–4607B for L2 without deleting protected knowledge. An unresolved hard-limit, ambiguous or unstable concern identity, ownership problem, or slug collision is blocking; never resolve it with a task-named or numbered shard.
+8. Validate format, required semantic L2 fields, source-file ownership, pointer resolution, hierarchy, capacity, and critical-knowledge preservation.
+9. Report files processed, generated `.prizm` files, omitted low-value categories, capacity results, and manual decisions required.
+
+## 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.
+- Capacity warning or strong warning: report the exact classifier fields and clean/organize only when required by the governing capacity policy; automatic remediation targets 80% to below 90%.
+- Size limit exceeded: fail validation until Value/Cleanup filtering, deduplication, movement to the owning child, or an unambiguous semantic split brings the target within its hard limit; never delete protected knowledge or raise the limit.
 - No git history: fall back to filesystem timestamps for freshness checks and warn that accuracy is reduced.
 
 ## Key Protocols
 
 For detailed protocol specifications, read `assets/prizm-docs-format.md`:
 
+- Value and Cleanup Gates: Sections 1 and 7
+- Semantic L2 identity and ownership: Sections 3.2, 3.3, and 5
+- Capacity classification and remediation: Sections 2.1 and 7
 - Progressive Loading: Section 6.1
 - Update/repair protocol: Section 7
 - RULES hierarchy: Section 3.1