prizmkit 1.1.156 → 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-workflow/SKILL.md

@@ -96,10 +96,12 @@ Expected transitions:
 | `prizmkit-plan` | `PLAN_READY` plus valid `spec.md`/`plan.md` | `prizmkit-implement` |
 | `prizmkit-implement` | `IMPLEMENTED` plus completed task markers | `prizmkit-code-review` |
 | `prizmkit-code-review` | `PASS` plus valid `review-report.md` | `prizmkit-test` |
-| `prizmkit-test` | `TEST_PASS` plus consistent report/result pair | `prizmkit-retrospective` |
+| `prizmkit-test` | `TEST_PASS` plus a consistent report/result pair with `production_changed=false` | `prizmkit-retrospective` |
 | `prizmkit-retrospective` | `RETRO_COMPLETE` plus an artifact whose `outcome` and `result` agree | `prizmkit-committer` |
 | `prizmkit-committer` | `COMMITTED` after explicit interactive confirmation | end |
 
+Before accepting a Test transition, require `production_changed` to be a boolean and agree between `test-report.md` and `test-result.json`. A passing result with `production_changed=true` follows the bounded production-repair route below and is not final Test authority for Retrospective.
+
 Before invoking `prizmkit-retrospective`, derive the exact changed project paths outside `.prizmkit/` and pass them as `change_paths` with a concise `change_summary`. Do not ask that atomic Skill to infer scope from this composite's state or earlier artifacts.
 
 `TEST_NOT_APPLICABLE` is not a valid lifecycle success. Lightweight changes must execute deterministic verification and return `TEST_PASS`.
@@ -132,6 +134,28 @@ prizmkit-implement
 
 The Main-Agent review skill owns its internal review repairs and its internal ten-round limit before returning its terminal result. The outer workflow repair counter is separate.
 
+### Passing Test with Production Repair
+
+A `TEST_PASS` whose consistent final artifacts report `production_changed=true` proves the Test stage repaired production code after prior Code Review. It does not authorize Retrospective or Committer.
+
+```text
+TEST_PASS + production_changed=true + repair_round < 3
+  → preserve the Test artifacts as repair evidence
+  → increment the outer repair round
+  → invalidate prior final Code Review/Test completion in coordinator state
+  → clear stale stage_result before re-entry
+  → invoke prizmkit-code-review review_scope=delta
+  → require a fresh prizmkit-test result
+
+fresh TEST_PASS + production_changed=false
+  → prizmkit-retrospective
+
+TEST_PASS + production_changed=true + repair_round >= 3
+  → WORKFLOW_BLOCKED
+```
+
+On re-entry, retain only stages that remain authoritative before Code Review in `completed_stages`, set `repair_scope=production`, and set the next/resume entry to delta Code Review without inventing a new atomic result. Repeated Test production repairs consume the same existing outer repair budget; they do not create an unbounded success loop.
+
 ### Test Non-Pass
 
 `prizmkit-test` already performs bounded test construction, execution-failure repair, mandatory Main-Agent review, and optional independent review before returning. The composite consumes its terminal artifacts without recreating those loops.
@@ -187,9 +211,17 @@ The internal `prizmkit-code-review` limit of ten completed review rounds remains
 
 The composite reaches `/prizmkit-committer operation=interactive-commit` but must not silently create a Git commit.
 
-The composite must validate all prior stage artifacts, derive exact non-`.prizmkit/` change paths for the retrospective input, and validate its result. It then invokes the committer with the same `artifact_dir`, exact `evidence_paths`, caller-state paths in `excluded_paths`, and `operation=interactive-commit`. The committer inspects the supplied final change, presents the exact commit, waits for confirmation, and creates it only after approval.
+The composite must validate all prior stage artifacts, derive exact non-`.prizmkit/` change paths for the retrospective input, and validate its result. For interactive commit it then assembles one exact `intended_paths` manifest from:
+
+- final validated requirement paths outside default support namespaces;
+- exact `.prizmkit/prizm-docs/**` paths listed by a consistent `RETRO_COMPLETE` + `DOCS_UPDATED` result;
+- exact support paths explicitly owned by the spec/plan, separately labeled in the preview, covered by the support validation below, and subject to the user's confirmation of that exact manifest.
+
+For each explicit support path, select and execute its applicable semantic contract before invoking Committer: instruction files require readable structure, resolvable project references, consistency with the exact requirement and applicable project conventions, and secret scanning; lockfiles require parse/schema checks plus owning-installer or deterministic-regeneration parity; any other support class requires an exact project-native semantic validator named by the spec/plan. User confirmation alone is not support validation. If no applicable validator exists or evidence is non-passing, block support admission. Pass one exact `support_validation_evidence` record per admitted support path, including its path, contract, completed validation, `PASS` result, and exact evidence path.
+
+All other `.prizmkit/**`, generated support, transient, installed, secret, unknown, or unrelated paths remain excluded or blocking. Invoke the committer with the same `artifact_dir`, exact `evidence_paths`, caller-state paths in `excluded_paths`, the exact `intended_paths`, conditional one-to-one `support_validation_evidence`, and `operation=interactive-commit`. The committer validates the manifest, presents the exact commit, waits for confirmation, and creates it only after approval.
 
-External headless orchestration supplies explicit evidence to `operation=prepare-runtime-commit`, maps `COMMIT_REQUEST_READY` to its own pending state, and lets Python Runtime validate and execute the request. Remote publication remains separate.
+External headless orchestration supplies explicit evidence to `operation=prepare-runtime-commit`, maps `COMMIT_REQUEST_READY` to its own pending state, and lets Python Runtime validate and execute the request. Preparation mode preserves the existing automated contract: the complete `.prizmkit/**` tree remains outside Runtime `intended_paths`. Remote publication remains separate.
 
 ## Automatic Handoff and Manual Fallback
 

package/bundled/skills/prizmkit-workflow/references/workflow-state-protocol.md

@@ -96,7 +96,8 @@ implementation IMPLEMENTED       → status=completed,  stage_result=IMPLEMENTED
 implementation repair/block      → status=failed,     stage_result=IMPLEMENT_REPAIR or IMPLEMENT_BLOCKED
 review-report PASS               → status=completed,  stage_result=REVIEW_PASS
 review-report NEEDS_FIXES        → status=failed,     stage_result=REVIEW_NEEDS_FIXES
-test-result TEST_PASS            → status=completed,  stage_result=TEST_PASS
+test-result TEST_PASS, production_changed=false → status=completed, stage_result=TEST_PASS
+test-result TEST_PASS, production_changed=true  → bounded re-entry; clear stale stage_result before pending delta Code Review
 test-result TEST_NEEDS_FIXES     → status=failed,     stage_result=TEST_NEEDS_FIXES
 test-result TEST_BLOCKED         → status=failed,     stage_result=TEST_BLOCKED
 retrospective outcome=RETRO_COMPLETE, result=DOCS_UPDATED   → status=completed, stage_result=RETRO_COMPLETE
@@ -109,7 +110,20 @@ commit blocked                   → status=failed,     stage_result=COMMIT_BLOC
 
 `DOCS_UPDATED` and `NO_DOC_CHANGE` remain retrospective artifact `result` values. The workflow `stage_result` is the retrospective stage result `RETRO_COMPLETE`.
 
-`TEST_PASS` requires both `test-report.md` and a consistent `test-result.json`. No manifest, attestation, evidence package, or test-internal checkpoint is part of this contract.
+`TEST_PASS` requires both `test-report.md` and a consistent `test-result.json`. Their `production_changed` diagnostics must agree. Only `production_changed=false` is final Test authority for Retrospective. No manifest, attestation, evidence package, or test-internal checkpoint is part of this contract.
+
+## Passing Production-Repair Re-entry
+
+When consistent Test artifacts return `TEST_PASS` with `production_changed=true`, the atomic Test result remains truthful but the prior Code Review no longer covers the final production state. If `repair_round < 3`, the coordinator:
+
+1. preserves the Test artifacts as repair evidence;
+2. increments `repair_round`;
+3. removes invalidated `code-review` and `test` entries from `completed_stages` while preserving authoritative predecessors;
+4. sets `stage=code-review`, `status=pending`, and `stage_result=null` so no stale result survives re-entry;
+5. sets `repair_scope=production`, `next_stage=code-review`, and `resume_from=prizmkit-code-review`;
+6. invokes delta Code Review and then a fresh Test.
+
+A fresh `TEST_PASS` with `production_changed=false` may complete Test and advance. Another production-changing pass repeats this route within the same outer budget. When `repair_round >= 3`, set `WORKFLOW_BLOCKED` without Retrospective or commit progression.
 
 ## Non-Pass Results and Routing Boundary
 
@@ -144,11 +158,16 @@ Any outer repair or continuation policy is independently owned by the caller and
 Interactive execution:
 
 ```text
-committer previews intended files and message
+coordinator assembles exact intended_paths from final requirement paths
+  + exact validated Retrospective .prizmkit/prizm-docs paths
+  + separately labeled explicitly owned support paths with one-to-one passing support_validation_evidence
+→ committer validates and previews the exact files and message
 → waits for explicit current-user confirmation
-→ stages, creates, and verifies the local commit
+→ stages exact pathspecs, creates, and verifies the local commit
 ```
 
+All other `.prizmkit/**`, generated support, transient, installed, secret, unknown, or unrelated paths remain excluded or blocking. Exact durable Prizm documentation admission is an interactive exception backed by the Retrospective result, not a general `.prizmkit` allowlist. User confirmation alone is not support validation: instruction files require structure/reference/requirement-consistency/secret checks, lockfiles require parse/schema plus installer or deterministic-regeneration parity, and any other support class requires the exact project-native semantic validator named by the spec/plan.
+
 Pipeline execution:
 
 ```text
@@ -159,7 +178,7 @@ external coordinator validates its required gates and supplies exact readiness e
 → remote publication remains separate
 ```
 
-The preparation request is data for runtime validation, not prompt-level authorization. The committer must not stage, commit, or predeclare COMMITTED in pipeline preparation mode.
+The preparation request is data for runtime validation, not prompt-level authorization. The committer must not stage, commit, or predeclare COMMITTED in pipeline preparation mode. Preparation preserves the existing automated path contract: the complete `.prizmkit/**` tree remains outside Runtime `intended_paths` in this protocol version.
 
 ## Recovery
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.156",
+  "version": "1.1.159",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {