prizmkit 1.1.155 → 1.1.159

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

@@ -19,6 +19,8 @@ Remote publication is outside this Skill.
 | `artifact_dir` | Yes | Exact caller-supplied artifact root for this commit stage. |
 | `operation` | Yes | `interactive-commit` or `prepare-runtime-commit`. |
 | `evidence_paths` | Yes | Exact caller-supplied project-relative artifacts that establish commit readiness. |
+| `intended_paths` | Interactive only: Yes | Exact unique project-relative final paths approved by the caller for preview and staging. It is never inferred from `git add .` or workspace breadth. |
+| `support_validation_evidence` | Interactive conditional | Required when `intended_paths` contains an explicit support path. Supply one exact record per support path with `path`, named semantic `contract`, completed `validation`, `result=PASS`, and an exact `evidence_path` also present in `evidence_paths`. |
 | `excluded_paths` | No | Exact caller-owned metadata paths that must remain outside the commit and are also excluded by the selected operation's consumer contract. It is not an allowlist for unrelated project changes. |
 | `request_path` | Preparation only | Must equal `{artifact_dir}/runtime-commit-request.json`. |
 
@@ -32,12 +34,14 @@ In preparation mode it must not stage, unstage, commit, amend, reset, merge, or
 
 ## Step 1: Validate Supplied Evidence and Final Change
 
-1. Resolve `artifact_dir` and every `evidence_paths` entry exactly as supplied by the caller.
+1. Resolve `artifact_dir` and every `evidence_paths` entry exactly as supplied by the caller. For interactive operation, also resolve every exact `intended_paths` entry without broadening it.
 2. Reject missing, unreadable, stale, contradictory, blocked, or explicitly non-passing evidence.
 3. Inspect staged, unstaged, untracked, deleted, and renamed files with bounded Git status/diff commands.
-4. Confirm every changed path belongs to the supplied change, a concrete dependency, its tests, durable documentation, or caller-required artifacts.
-5. Reject unresolved merge state and sensitive files such as real environment files, credentials, secrets, private keys, certificates, or local settings.
-6. Confirm no requested task output remains to be generated after this stage.
+4. Confirm every intended path belongs to the supplied change, a concrete dependency, its tests, durable documentation, or an explicitly caller-owned support artifact. Unknown or unrelated Git-visible changes block rather than entering the manifest.
+5. For every explicit support path, require one unique `support_validation_evidence` record whose `path` equals that manifest entry, whose `evidence_path` is supplied and readable, and whose named contract, completed validation, and `result=PASS` agree with that evidence. Missing, generic, self-asserted, or non-passing support evidence blocks admission.
+6. Reject unresolved merge state and sensitive files such as real environment files, credentials, secrets, private keys, certificates, or local settings.
+7. Confirm no requested task output remains to be generated after this stage.
+8. Never force-add an ignored file or modify Git/ignore policy. An intended durable documentation path that is not stageable under the project's existing policy blocks with the exact path and policy reason.
 
 The caller decides which evidence is required and how the returned commit-stage result is used. This Skill validates the supplied evidence but does not infer a larger stage sequence.
 
@@ -49,32 +53,33 @@ Generate one concise Conventional Commit message:
 <type>(<scope>): <description>
 ```
 
-Classify every observed change before constructing the request. All paths under `.prizmkit/` are framework-internal and remain outside automated task commits.
+Classify every observed change before validating either operation.
 
 - **task-owned**: justified source, tests, product/project documentation, configuration, and dependency changes outside recognized support namespaces;
-- **PrizmKit-internal**: every path under `.prizmkit/`, including config, plans, Prizm docs, lifecycle Artifacts, installed Runtime files, and state;
-- **platform support**: `AGENTS.md`, `skills-lock.json`, installed platform directories, and local platform settings;
+- **durable Prizm documentation**: exact stageable `.prizmkit/prizm-docs/**` paths listed by one supplied `retrospective-result.json` whose `outcome=RETRO_COMPLETE`, `result=DOCS_UPDATED`, non-empty `validation`, and `documentation_paths` exactly authorize those paths;
+- **explicit interactive support**: `AGENTS.md`, `skills-lock.json`, or another support path named by the exact spec/plan, covered one-to-one by passing `support_validation_evidence`, labeled separately in the interactive preview, and included in the user's confirmation;
+- **PrizmKit transient/internal**: `.prizmkit/specs/**`, `.prizmkit/state/**`, `.prizmkit/dev-pipeline/**`, config, plans/status, installed Runtime files, checkpoints, and other framework execution data;
+- **generated platform support**: installed platform directories and local platform settings not explicitly owned by the interactive requirement;
 - **project transient**: data the project already excludes through Git ignore rules;
 - **unknown Git-visible**: any remaining path whose task ownership cannot be proven.
 
-Build a unique set of exact project-relative **task-owned** changed paths. Include intended tracked modifications, deletions, renames, new source/tests, and justified project documentation outside support namespaces. Exclude:
+All paths under `.prizmkit/` are framework-internal and remain outside automated task commits.
 
-- `.git/`;
-- the complete `.prizmkit/` tree;
-- `AGENTS.md`, `skills-lock.json`, installed platform directories, and local platform settings;
-- sensitive or unrelated files.
+For `operation=interactive-commit`, validate the caller-supplied `intended_paths` as the complete approved manifest. It may contain task-owned paths, evidence-backed durable Prizm documentation, and explicitly owned support paths. Every entry must be exact, unique, project-relative, currently changed, stageable without force, and covered by the applicable evidence above. An instruction support file contract must validate readable structure, referenced project paths, consistency with the exact requirement and applicable project conventions, and secret absence. A lockfile support contract must validate parse/schema integrity and owning-installer or deterministic-regeneration parity. Another support class requires the exact project-native semantic validator named by the spec/plan; if no applicable validator exists, support admission blocks. The following remain prohibited: `.git/**`, every PrizmKit transient/internal path, installed platform payloads, local settings, secrets, temporary files, and unrelated or unknown changes.
 
-Unknown Git-visible paths block the operation; do not silently classify them as transient. Project-specific transient data belongs in the project's Git ignore rules, not caller-provided exclusions. Do not use wildcard pathspecs, `git add .`, or `git add -A` as an intended-path description. In preparation mode, reject an `excluded_paths` entry unless the Python Runtime independently excludes that exact caller-owned metadata class; unrelated or user-authored project changes cannot be hidden from exact-path coverage.
+For `operation=prepare-runtime-commit`, preserve the existing automated consumer boundary: construct a unique exact set of task-owned changed paths outside recognized support namespaces, and exclude the complete `.prizmkit/` tree plus platform support and sensitive/unrelated files. Preparation mode preserves the Python Runtime's exact path-coverage contract and does not admit the interactive durable-documentation or support exceptions.
+
+Unknown Git-visible paths block the selected operation; do not silently classify them as transient. Project-specific transient data belongs in the project's Git ignore rules, not caller-provided exclusions. Do not use wildcard pathspecs, `git add .`, or `git add -A`. In preparation mode, reject an `excluded_paths` entry unless the Python Runtime independently excludes that exact caller-owned metadata class; unrelated or user-authored project changes cannot be hidden from exact-path coverage.
 
 ## Step 3A: Interactive Commit
 
 For `operation=interactive-commit`:
 
-1. Present intended paths, change summary, sensitive-file warnings, diff statistics, proposed message, and intentionally excluded changes.
+1. Present the exact `intended_paths`, change summary, sensitive-file warnings, diff statistics, proposed message, intentionally excluded changes, and a separate label for each admitted durable Prizm documentation or explicit support path.
 2. Ask the current user to confirm that exact local commit.
-3. Only after confirmation, stage tracked changes safely and new files explicitly.
-4. Verify the staged diff exactly matches the confirmed path set.
-5. Create the local commit and verify its hash, committed paths, and remaining workspace changes.
+3. Only after confirmation, stage with `git add -- <exact paths>` semantics: use exact pathspecs for tracked changes, deletions, and explicitly named new files; never stage workspace breadth.
+4. Verify the staged diff exactly matches the confirmed manifest and contains no path added by a hook or incidental operation.
+5. Create the local commit and verify its hash, message, committed paths, and remaining workspace changes against the confirmed manifest.
 6. Return `COMMITTED`, the commit hash/message, committed paths, and intentional remaining changes.
 
 If confirmation is declined, return `COMMIT_DECLINED` without Git mutation.

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

@@ -27,6 +27,12 @@ Recommended project initialization skill. Scans any brownfield or greenfield pro
 
 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.
 
+## Host-Neutral Interaction and Discovery
+
+- Ask required questions through the current Host's available user-interaction capability. If no structured interaction capability exists, ask directly in ordinary conversation and wait for the user's answer.
+- Describe required filesystem evidence and bounded discovery results semantically. Do not require a specific tool name, shell, command, or operating system.
+- Platform-specific commands may be shown only as non-normative examples after the Host has established that they are available; an unavailable example never blocks an equivalent Host-native operation.
+
 ## Execution Steps
 
 **Phase 1: Platform Detection**
@@ -77,17 +83,7 @@ BROWNFIELD WORKFLOW (existing project):
    - SUB-MODULES: directories INSIDE a top-level module (e.g. `src/routes/`, `src/models/`)
    - A sub-module maps to `.prizmkit/prizm-docs/<M>/<S>.prizm`, never to `.prizmkit/prizm-docs/<S>.prizm` — flattening would create ambiguous paths when two modules have identically-named sub-modules
    - Exclude: `.git/`, `node_modules/`, `vendor/`, `build/`, `dist/`, `__pycache__/`, `target/`, `bin/`, `.agents/`, `.codex/`, `.claude/`, `.codebuddy/`, `.prizmkit/`
-   - **Scan command** — run this to get a 2-level directory tree (excludes noise directories):
-     ```bash
-     find . -maxdepth 2 -type d \
-       -not -path '*/node_modules/*' -not -path '*/.git/*' \
-       -not -path '*/dist/*' -not -path '*/build/*' \
-       -not -path '*/__pycache__/*' -not -path '*/vendor/*' \
-      -not -path '*/.agents/*' -not -path '*/.codex/*' \
-      -not -path '*/.claude/*' -not -path '*/.codebuddy/*' \
-       -not -path '*/.prizmkit/*' -not -path '*/target/*' \
-       | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
-     ```
+   - **Bounded discovery contract** — use the current Host's available directory-listing or file-search capability to enumerate at most two directory levels, apply the exclusions above before analysis, preserve parent/child relationships, and report the resulting project-relative structure. Do not require a POSIX shell pipeline or any other operating-system-specific command.
 3. Identify entry points by language convention
 4. Catalog dependencies (external packages)
 5. Count source files per directory
@@ -106,7 +102,7 @@ After tech stack detection, determine which development layers exist in the proj
    - **backend**: Express/FastAPI/Gin/etc. in dependencies, or `routes/`/`controllers/` with server code
    - **database**: Prisma/TypeORM/SQLAlchemy/etc. in dependencies, or `migrations/`/`prisma/` directory
    - **mobile**: `pubspec.yaml` (Flutter), `react-native` in package.json, or simultaneous `ios/`+`android/` directories
-3. For mobile signals — if ambiguous (e.g., monorepo with web + ios/android dirs), use `AskUserQuestion` to confirm: "Mobile platform signals detected. Is this project a mobile app?" Options: "Yes, this is a mobile app" / "No, these are for another purpose".
+3. For mobile signals — if ambiguous (e.g., monorepo with web + ios/android dirs), ask the user directly: "Mobile platform signals detected. Is this project a mobile app?" Offer "Yes, this is a mobile app" and "No, these are for another purpose" as clear choices, using the Host-neutral interaction contract above.
 4. Assemble `detected_layers` array (e.g., `["frontend", "backend", "database"]`). If no layers detected (library/CLI project), array is empty.
 
 **Phase 4.6: Infrastructure Quick Scan**
@@ -120,7 +116,7 @@ Detect database and deployment signals, then ask 1-2 brief questions. This phase
    - **Database signals**: ORM/database client dependencies in `package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pyproject.toml` (look for: prisma, typeorm, sequelize, mongoose, sqlalchemy, django, gorm, diesel, sqlx, pg, mysql2, etc.); directories named `migrations/`, `db/`, `schema/`, `prisma/`; environment variables `DATABASE_URL`, `DB_HOST`, `DB_NAME`, `MONGO_URI` in `.env*` files
    - **Deployment signals**: `Dockerfile`, `docker-compose.yml`, `vercel.json`, `fly.toml`, `railway.json`, `netlify.toml`, `cloudflare.json`, `.github/workflows/`, `Procfile`, `app.yaml`, `serverless.yml`, `terraform/`, `pulumi/`
 
-2. **Brief inquiry** (using `AskUserQuestion`, max 2 questions):
+2. **Brief inquiry** (ask through the Host-neutral interaction contract, max 2 questions):
 
    **Question 1 — Database**:
    - If database signals detected: pre-fill with detected info
@@ -172,14 +168,14 @@ Detect database and deployment signals, then ask 1-2 brief questions. This phase
 After Infrastructure Quick Scan completes, check if `detected_layers` is non-empty (from Phase 4.5). If layers were detected, offer a lightweight entry point for rules configuration.
 
 1. If `detected_layers` is empty (library/CLI project) → skip this phase entirely, proceed to Phase 5.
-2. If layers detected, use `AskUserQuestion`:
+2. If layers are detected, ask through the Host-neutral interaction contract:
 
    **Question**: "Detected **{list detected layers}** code. Would you like to set up custom development rules for AI to follow? This helps AI generate code that matches your conventions."
    - **Configure later (Recommended)** — Record layers and configure rules later
    - **Skip entirely** — no custom rules, AI uses general best practices
 
-3. If user picked "Skip entirely" → clear `detected_layers` to empty array, proceed to Phase 5.
-4. If user picked "Configure later" → keep `detected_layers`, proceed to Phase 5. The layers will be written to config.json in Phase 6.
+3. If the user picked "Skip entirely" → preserve `detected_layers` as observed project facts, set `enabled_rule_profiles` to an empty array, and proceed to Phase 5.
+4. If the user picked "Configure later" → preserve `detected_layers`, keep `enabled_rule_profiles` unchanged when already configured or initialize it to an empty array, and proceed to Phase 5. Detection never implies rule adoption.
 
 **Phase 5: Prizm Documentation Generation**
 Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structure from Phase 4:
@@ -192,18 +188,18 @@ Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structu
 
 **Phase 6: Workspace Initialization**
 6a. Create `.prizmkit/` directory structure (if missing):
-  - `.prizmkit/config.json` (adoption_mode, speckit_hooks_enabled, platform)
+  - `.prizmkit/config.json` (adoption_mode, platform installation metadata, detected_layers, enabled_rule_profiles)
   - `.prizmkit/specs/` (empty)
   - `.prizmkit/plans/` (empty — needed by Phase 7 and future pipeline tasks)
 
 6b. Write detected tech stack to `.prizmkit/config.json`:
    → Read `${SKILL_DIR}/references/config-schema.md` for merge strategy, field definitions, and examples.
 
-6c. Write `detected_layers` to `.prizmkit/config.json` (alongside `tech_stack`):
-   - Field: `"detected_layers": ["frontend", "backend"]` — the layers from Phase 4.5
-   - If user chose "Skip entirely" in Phase 4.7, write empty array `[]`
-   - For greenfield projects (Phase 4.5 skipped): write `[]` — no code layers to configure rules for yet; user can configure rules later when code exists
-   - This field indicates which development layers exist in the project and can be used to determine available rule configuration options.
+6c. Write observed layers and separate rule adoption to `.prizmkit/config.json` (alongside `tech_stack`):
+   - `"detected_layers": ["frontend", "backend"]` records only the observed layers from Phase 4.5 and is never cleared because the user declines rule configuration.
+   - `"enabled_rule_profiles": []` records rule adoption separately. Preserve valid existing entries; initialize an empty array when no profiles are enabled.
+   - For greenfield projects (Phase 4.5 skipped), write both fields as empty arrays until code exists or the user explicitly enables a rule profile.
+   - Future re-detection updates observed layers without silently enabling or disabling rule profiles.
 
 **Phase 7: Project Brief Generation**
 
@@ -301,7 +297,7 @@ Tech stack detected:
 
 Layer Detection:
   Detected layers: frontend, backend, database (from dependency + directory signals)
-  → Stored for config.json
+  → Observed layers stored in config.json independently from rule-profile adoption
 
 Infrastructure Quick Scan:
   Database: PostgreSQL (Prisma) — detected from dependencies
@@ -309,7 +305,7 @@ Infrastructure Quick Scan:
   → Written to the detected main platform instruction file `### Infrastructure` (not `.private.md`)
 
 Rules Quick Entry:
-  Matched layers: frontend (React), backend (Express.js), database (Prisma) → keeping default rules
+  Matched layers: frontend (React), backend (Express.js), database (Prisma) → no rule profiles enabled yet
 
 Modules discovered:
   src/routes/     → .prizmkit/prizm-docs/routes.prizm (12 files)
@@ -321,7 +317,7 @@ Project brief: inferred from codebase → confirmed by user
   → .prizmkit/plans/project-brief.md
 
 Generated: root.prizm + 4 L1 docs
-Saved: .prizmkit/config.json (tech_stack + detected_layers recorded)
+Saved: .prizmkit/config.json (tech_stack + detected_layers + enabled_rule_profiles recorded)
 
 Next: Use /prizmkit-plan to start your first feature
 ```

package/bundled/skills/prizmkit-init/references/config-schema.md

@@ -7,11 +7,12 @@ Handles re-init without losing user edits:
 - Read existing `config.json` if present
 - If `tech_stack` field exists AND `_auto_detected` is `false` or absent:
   → **SKIP** — user has manually configured tech stack, preserve their settings
-- Always update `detected_layers` with new layer detection results on every init run — layer detection is based on code that exists, not user preference. This ensures greenfield projects that later gain code get their `detected_layers` populated correctly. Note: the final value written is still determined by Phase 6c (e.g., if user chose "Skip entirely" in Phase 4.7, Phase 6c writes `[]` regardless of detection results).
+- Always update `detected_layers` with fresh observed layer-detection results on every init run — detection is based on code that exists, never on whether the user enables custom rules. A rule-configuration choice must not erase detected project facts.
+- Preserve valid `enabled_rule_profiles` entries independently from detection. Initialize `[]` only when the field is absent or the user explicitly disables every rule profile.
 - If `tech_stack` field exists AND `_auto_detected` is `true`:
-  → **MERGE** — overwrite auto-detected values with new detection results, but preserve any keys the user added manually (keys not in the new detection result). Overwrite `detected_layers` with new layer detection results.
+  → **MERGE** — overwrite auto-detected values with new detection results, but preserve any keys the user added manually (keys not in the new detection result). Overwrite `detected_layers` with new observed results and preserve `enabled_rule_profiles` independently.
 - If `tech_stack` field does NOT exist:
-  → **WRITE** full detected tech stack with `"_auto_detected": true`, and write `detected_layers` from layer detection
+  → **WRITE** full detected tech stack with `"_auto_detected": true`, write `detected_layers` from observed layer detection, and initialize `enabled_rule_profiles` to `[]` unless the user explicitly enabled profiles
 - Only include fields that were actually detected (no empty/null values)
 
 ## Field Definitions
@@ -19,12 +20,13 @@ Handles re-init without losing user edits:
 | Field | Type | Description |
 |-------|------|-------------|
 | `adoption_mode` | string | `"passive"` \| `"advisory"` \| `"active"` |
-| `platform` | string | `"codebuddy"` \| `"claude"` \| `"codex"` \| `"all"` |
+| `platform` | string | Installed payload metadata: `"codebuddy"` \| `"claude"` \| `"codex"` \| `"pi"` \| `"all"`. It records installation, not a canonical behavior allowlist. |
 | `tech_stack` | object | Detected or user-provided tech stack |
 | `tech_stack._auto_detected` | boolean | `true` if auto-detected, `false` if user-provided |
-| `detected_layers` | string[] | Development layers detected in the project. Written by prizmkit-init Phase 4.5. Used to determine available rule configuration options. Values: `frontend` / `backend` / `database` / `mobile`. Empty array when no layers detected or user skipped rules. Always updated on every init run based on fresh code detection — not gated by `_auto_detected` (see Merge Strategy above). |
+| `detected_layers` | string[] | Development layers observed in the project. Written by prizmkit-init Phase 4.5. Values: `frontend` / `backend` / `database` / `mobile`. Empty only when no layers are observed. Always refreshed from code and never cleared by rule-adoption choices. |
+| `enabled_rule_profiles` | string[] | Rule profiles the user explicitly enabled. This is independent from `detected_layers`; an empty array means no custom profile is enabled, not that the project has no detected layers. |
 
-Legacy manifests may still contain `both` for read-only migration compatibility. New config writes must use `codebuddy`, `claude`, `codex`, or `all`.
+Legacy manifests may still contain `both` for read-only migration compatibility. New config writes must use `codebuddy`, `claude`, `codex`, `pi`, or `all`.
 
 ## Examples
 
@@ -34,6 +36,7 @@ Fullstack project:
   "adoption_mode": "passive",
   "platform": "claude",
   "detected_layers": ["frontend", "backend", "database"],
+  "enabled_rule_profiles": [],
   "tech_stack": {
     "language": "TypeScript",
     "runtime": "Node.js 20",
@@ -65,6 +68,7 @@ Pure Python backend:
     "project_type": "backend",
     "_auto_detected": true
   },
-  "detected_layers": ["backend", "database"]
+  "detected_layers": ["backend", "database"],
+  "enabled_rule_profiles": []
 }
 ```

package/bundled/skills/prizmkit-init/references/rules/layer-detection.md

@@ -28,7 +28,7 @@
 
 ## Mobile Confirmation
 
-When mobile signals are detected but ambiguous (e.g., a monorepo with web + mobile), use `AskUserQuestion`:
+When mobile signals are detected but ambiguous (e.g., a monorepo with web + mobile), ask the user through the current Host's available interaction capability; use ordinary conversation when no structured interaction is available:
 
 > "Mobile platform signals detected (ios/ + android/ directories). Is this project
 > a mobile app, or are these directories for another purpose?"
@@ -37,5 +37,5 @@ When mobile signals are detected but ambiguous (e.g., a monorepo with web + mobi
 ## Output
 
 After detection (signals + your own judgment), assemble `detected_layers` array (e.g., `["frontend", "backend", "database"]`).
-Store in memory for Phase 6 config.json writing.
-If no layers detected (library/CLI project), array is empty.
+Store the observed values in memory for Phase 6 config.json writing. Rule-profile adoption is recorded separately and never changes this detection result.
+If no layers are detected (library/CLI project), the array is empty.

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

@@ -83,10 +83,11 @@ Precondition: `spec.md` exists with no unresolved blocker.
 
 1. Choose an MVP-first, incremental, or safe parallel task strategy.
 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 appropriate implementation-local and regression verification tasks without executing them during planning.
-6. Run `${SKILL_DIR}/references/verification-checklist.md` and repair plan defects.
+3. Include setup, foundation, core, and polish phases only when applicable; do not manufacture empty phases for a small plan.
+4. Every formal plan must contain at least one concrete risk with mitigation and at least one verification checkpoint. A small plan may use one final checkpoint instead of artificial phase checkpoints.
+5. Mark `[P]` only for tasks that can safely execute independently.
+6. Include appropriate implementation-local and regression verification tasks without executing them during planning.
+7. Run `${SKILL_DIR}/references/verification-checklist.md` and repair plan defects.
 
 ## Phase 4: Plan/Spec Review Loop
 

package/bundled/skills/prizmkit-plan/assets/plan-template.md

@@ -61,6 +61,7 @@
 - E2E: [Approach]
 
 ## Risk Assessment
+<!-- Every formal plan keeps at least one concrete risk and mitigation. Use a truthful low-impact risk for small changes rather than filler. -->
 | Risk | Impact | Mitigation |
 |------|--------|------------|
 | [Risk] | [H/M/L] | [Plan] |
@@ -107,12 +108,14 @@
 
 ### Phase: Polish
 - [ ] [T-900] Final verification
-- [ ] [T-901] Documentation update
+- [ ] [T-901] Update required project/user-facing documentation <!-- Conditional; Prizm memory synchronization is Retrospective-owned, not an implementation task. -->
 
 ### Checkpoints
+<!-- Every formal plan has at least one verification checkpoint. Keep only checkpoints for phases that actually exist; a small plan may use one final checkpoint. -->
 - [ ] [CP-1] After Setup: project builds and tests pass
 - [ ] [CP-2] After Foundation: base changes verified
 - [ ] [CP-3] After each Core group: acceptance criteria pass
+- [ ] [CP-FINAL] Final: planned acceptance and regression verification passes
 
 ## Independent Plan Review
 <!-- Append this terminal audit record after the Main-Agent review and the optional independent-review attempt. -->

package/bundled/skills/prizmkit-plan/references/verification-checklist.md

@@ -8,7 +8,8 @@ Run this checklist after generating the Tasks section in plan.md. Fix any issues
 
 - [ ] Every goal (G-N) in spec.md has at least one task in plan.md
 - [ ] Every task has a target file path (`— file: path/to/file`)
-- [ ] Risk assessment contains at least one risk with a mitigation plan
+- [ ] Risk assessment contains at least one concrete risk with a mitigation plan
+- [ ] The plan contains at least one verification checkpoint; a small plan may use one final checkpoint
 - [ ] If spec includes `## Behavior Preservation` → at least one verification task exists
 - [ ] If spec includes `## Root Cause` → at least one reproduction test task exists
 
@@ -36,7 +37,7 @@ Run this checklist after generating the Tasks section in plan.md. Fix any issues
 
 - [ ] No task references the output of a later task without an explicit dependency note
 - [ ] Foundation tasks precede Core tasks that depend on them
-- [ ] Checkpoint tasks exist between phases
+- [ ] Checkpoints exist between dependent phases that are present; plans without multiple phases use one final checkpoint
 
 ## Rules Alignment
 

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,12 +152,14 @@ 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
 
@@ -125,13 +175,17 @@ If that path exists, use the lowest available suffix `.001`, `.002`, and so on,
 
 - `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