prizmkit 1.1.156 → 1.1.160

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

@@ -25,7 +25,13 @@ Recommended project initialization skill. Scans any brownfield or greenfield pro
 
 ### 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.
+`.prizmkit/**` is the PrizmKit framework directory. Initialization may read and write only its declared managed artifacts, but it does not stage, commit, force-add, change or interpret `.gitignore`, require Git history, or decide whether those paths are ignored, untracked, or tracked. The project controls Git visibility; initialization behavior is otherwise identical. Root instruction and platform-support files remain support data rather than initialization-owned commit output.
+
+## 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
 
@@ -75,19 +81,9 @@ BROWNFIELD WORKFLOW (existing project):
 2. Map directory structure using a TWO-TIER model — flat structures lose the nesting relationships that AI needs to navigate the codebase:
    - TOP-LEVEL modules: directories directly under project root that contain source files or sub-directories with source files (e.g. `src/`, `internal/`, `lib/`)
    - 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'
-     ```
+   - Exact `root.prizm` is L0; top-level module M maps to direct-child `.prizmkit/prizm-docs/<M>.prizm` (L1); sub-module S maps to nested `.prizmkit/prizm-docs/<M>/<S>.prizm` (L2). Deeper source ownership remains L2 and never creates L3.
+   - Exclude: `.git/`, `node_modules/`, `vendor/`, `build/`, `dist/`, `__pycache__/`, `target/`, `bin/`, `.agents/`, `.codex/`, `.claude/`, `.codebuddy/`, `.pi/`, and the complete `.prizmkit/` framework directory. This excludes installed `.prizmkit/dev-pipeline/` artifacts but not canonical top-level `dev-pipeline/` source.
+   - **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,38 +168,38 @@ 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:
-  - Create `.prizmkit/prizm-docs/` directory structure mirroring the source tree (sub-module dirs become subdirectories under `.prizmkit/prizm-docs/<top-level>/`)
-  - Generate `root.prizm` (L0) with project meta and MODULE_INDEX listing only top-level modules. If module count > 15, use MODULE_GROUPS format instead (group by functional domain).
-  - For each module entry in MODULE_INDEX/MODULE_GROUPS, include keyword tags extracted from the module's source files — scan for: exported symbols, imported packages, domain terms in file/directory names. Format: `- module-name [tag1, tag2, tag3]: ...`. Tags help AI match user intent to relevant modules.
-  - Generate L1 docs for top-level modules at `.prizmkit/prizm-docs/<M>.prizm` and for sub-modules at `.prizmkit/prizm-docs/<M>/<S>.prizm`
-  - Skip L2 (lazy generation) — L2 is created later by `/prizmkit-retrospective` when a changed module has meaningful behavior or durable knowledge. During implementation, if an affected L2 is missing, `/prizmkit-implement` reads the target source files as fallback instead of blocking.
-  - Do not create auxiliary `changelog.prizm`, CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths; git history is the source of change history
+  - Create only documentation directories needed by complete documents; do not create placeholder sub-module files.
+  - Generate exact `root.prizm` (L0) with `PRIZM_VERSION: 4`, project meta, and MODULE_INDEX listing only top-level modules. If module count > 15 or measured capacity requires it, use MODULE_GROUPS.
+  - For each module entry in MODULE_INDEX/MODULE_GROUPS, include only high-value intent tags and a pointer to one direct-child L1 at `.prizmkit/prizm-docs/<M>.prizm`.
+  - Generate one direct-child L1 structural index for each top-level module. Record source submodules structurally, but emit a SUBDIRS pointer only when its complete nested L2 exists.
+  - Skip all L2 during Init. Before later source modification, read a complete existing relevant L2 and complete resolving pointer documents; if absent, inspect bounded relevant source as fallback without creating a placeholder. `/prizmkit-retrospective` may later create a complete Value-Gate-qualified L2.
+  - Do not create auxiliary `changelog.prizm`, CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths; temporal history is outside Prizm memory
 
 **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,19 +305,19 @@ 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)
-  src/models/     → .prizmkit/prizm-docs/models.prizm (8 files)
-  src/services/   → .prizmkit/prizm-docs/services.prizm (15 files)
-  src/middleware/  → .prizmkit/prizm-docs/middleware.prizm (5 files)
+  src/            → .prizmkit/prizm-docs/src.prizm (top-level L1)
+  src/routes/     → nested source submodule (no placeholder L2 during Init)
+  src/models/     → nested source submodule (no placeholder L2 during Init)
+  src/services/   → nested source submodule (no placeholder L2 during Init)
 
 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)
+Generated: root.prizm + 1 direct-child L1 doc
+Saved: .prizmkit/config.json (tech_stack + detected_layers + enabled_rule_profiles recorded)
 
 Next: Use /prizmkit-plan to start your first feature
 ```
@@ -349,9 +345,9 @@ Tech stack changes detected:
   = frontend: React (unchanged)
 
 Documentation gap-fill:
-  + app/share/[token].prizm (L2) — created (3 source files, meaningful logic)
-  = routes.prizm (L1) — up to date
-  ~ models.prizm (L1) — FILES count updated (8 → 10)
+  = app.prizm (direct-child L1) — up to date
+  source fallback: app/share/[token] (nested L2 absent; no placeholder created)
+  ~ app.prizm (L1) — concise source summary updated
 
 Project brief: inferred from codebase → confirmed by user
   → .prizmkit/plans/project-brief.md (generated)

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-init/references/update-supplement.md

@@ -2,8 +2,8 @@
 
 Runs after tech stack merge in Update mode:
 
-1. **Module scan**: Re-scan project directories using the same TWO-TIER model from Step 1. Compare discovered modules against existing MODULE_INDEX in root.prizm.
-2. **Missing L1 check**: For any discovered module with no corresponding L1 `.prizm` doc → create L1 immediately and add to MODULE_INDEX.
-3. **Missing L2 check**: For any module/sub-module that has source files with meaningful logic but no L2 `.prizm` doc → create L2 using the L2 GENERATION TEMPLATE. Judgment call: skip trivial wrapper directories or single-config modules.
-4. **Stale L1 check**: For existing L1 docs, verify FILES count and KEY_FILES are still accurate. Update if source directory contents have changed significantly.
-5. **Report**: Include in the Update report: modules added, L1 docs created, L2 docs created, stale docs refreshed.
+1. **Bounded module scan**: Re-scan only the registered top-level source modules and concrete structural gaps using the same two-tier model. Exclude the complete `.prizmkit/` framework directory, including installed `.prizmkit/dev-pipeline/`, but do not exclude a repository's canonical top-level `dev-pipeline/` source module.
+2. **Missing L1 check**: For a discovered top-level module with no direct-child L1, build one complete Value-Gate-filtered structural candidate at `.prizmkit/prizm-docs/<M>.prizm` and add a resolving root pointer only after the candidate validates.
+3. **Missing L2 context**: For an affected source submodule with no nested L2, inspect only the bounded source files and narrowly implicated contracts needed to determine the gap. Do not create a placeholder. A complete L2 may be created only when current durable facts pass the Value Gate and mirrored/semantic identity, ownership, pointer, format, and capacity checks all pass.
+4. **Existing target reconciliation**: Read every complete affected target and complete resolving parent/child pointer document. Apply Cleanup by semantic meaning, preserve protected knowledge, build candidates bottom-up, skip byte-identical replacements, and re-read actual bytes after writes.
+5. **Failure and report**: If any post-write check fails, restore exact pre-write bytes and remove invalid new targets before reporting a blocker. Report modules/details added, skipped source fallbacks, stale summaries reconciled, and capacity/pointer validation. Never stage, commit, force-add, change or interpret `.gitignore`, require Git history, or classify tracking state as documentation health.

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

@@ -61,7 +61,7 @@ Critical-knowledge rule: a still-valid public or wire contract, cross-module con
 
 Before Update or Rebuild writes an existing target:
 
-1. Read the target and its resolving parent/child pointers first.
+1. Read the complete target and complete resolving parent/child pointer documents 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.
@@ -70,6 +70,12 @@ Before Update or Rebuild writes an existing target:
 
 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.
 
+### Framework Directory and Git Neutrality
+
+`.prizmkit/**` is the PrizmKit framework directory. This Skill may read and write only its managed documentation and recovery artifacts, but it never owns project Git policy: do not add, remove, force-add, stage, commit, or interpret `.gitignore` entries for `.prizmkit/**`, and do not require Git history or treat ignored, untracked, or tracked state as a documentation error. Generation, reconciliation, validation, capacity behavior, and failure restoration are identical in all three tracking states apart from ordinary Git visibility.
+
+Exact path classification is mandatory: only `.prizmkit/prizm-docs/root.prizm` is L0; a direct `.prizm` child of `.prizmkit/prizm-docs/` other than root is L1; every nested `.prizm` document is L2. Before source modification, read the complete relevant L2 plus complete parent/child documents needed to resolve its pointers. If relevant L2 is absent, inspect bounded relevant source and create no placeholder as part of context loading.
+
 ### 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%.
@@ -159,7 +165,8 @@ Steps:
 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.
+9. Write complete validated candidates bottom-up, compare candidate/current bytes to avoid byte-identical rewrites, re-read actual bytes, and restore every prior target byte-for-byte or remove an invalid new target if any post-write check fails.
+10. Report files processed, generated `.prizm` files, omitted low-value categories, capacity results, and manual decisions required.
 
 ## Recovery Backup Contract
 
@@ -174,10 +181,10 @@ If that path exists, use the lowest available suffix `.001`, `.002`, and so on,
 ## Error Handling
 
 - `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.
+- Broken pointers: inspect the bounded owning source and parent context. Create a complete Value-Gate-qualified detail only through the selected documentation operation; otherwise remove a stale pointer or report the ambiguity. Never emit a placeholder merely to make a pointer resolve.
 - 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.
+- Freshness checks use current source/document filesystem evidence and never require Git history or branch/tracking state.
 
 ## Key Protocols
 
@@ -196,10 +203,9 @@ For detailed protocol specifications, read `assets/prizm-docs-format.md`:
 
 ```text
 Generated .prizmkit/prizm-docs/:
-  root.prizm (L0) — 3 modules in MODULE_INDEX
-  routes.prizm (L1) — module structure and dependencies
-  models.prizm (L1) — module structure and dependencies
-  services.prizm (L1) — module structure and dependencies
+  root.prizm (L0) — top-level module map
+  src.prizm (L1) — direct-child source-module structure and dependencies
+  (no nested L2 placeholders during Init)
 ```
 
 L1 docs are structural indexes. Interface signatures, data flow, TRAPS, and DECISIONS belong in L2 docs.
@@ -208,7 +214,7 @@ L1 docs are structural indexes. Interface signatures, data flow, TRAPS, and DECI
 
 ```text
 Changed outside normal dev loop: src/routes/avatar.ts (A), src/models/user.ts (M)
-Updated: .prizmkit/prizm-docs/routes.prizm — added avatar route file mapping
-Created: .prizmkit/prizm-docs/routes/avatar.prizm — recorded new route interfaces and traps
-Updated: .prizmkit/prizm-docs/models.prizm — file count changed
+Updated: .prizmkit/prizm-docs/src/routes.prizm — complete nested route detail
+Updated: .prizmkit/prizm-docs/src/models.prizm — complete nested model detail
+Updated: .prizmkit/prizm-docs/src.prizm — concise direct-child summaries and resolving pointers
 ```