prizmkit 1.1.7 → 1.1.9

package/bundled/skills/prizmkit-prizm-docs/references/op-status.md

@@ -0,0 +1,14 @@
+# Operation: Status — Detailed Steps
+
+Check freshness of all .prizm docs.
+
+PRECONDITION: .prizm-docs/ exists with root.prizm.
+
+STEPS:
+1. Get last git modification time of root.prizm via `git log -1 --format="%ai" -- .prizm-docs/root.prizm`.
+2. Count commits since that time via `git log --since="<timestamp>" --oneline | wc -l`.
+3. For each L1/L2 doc, compare git modification time of the .prizm file (`git log -1 --format="%ai" -- <prizm-file>`) against latest git modification of source files in that module (`git log -1 --format="%ai" -- <module-path>/`).
+4. Classify each doc as: FRESH (prizm file updated after latest source change), STALE (source changed more recently than prizm file), MISSING (module exists but no .prizm doc).
+5. Flag any docs exceeding size limits.
+
+OUTPUT: Freshness report table with columns: DOC_PATH | LEVEL | STATUS | PRIZM_LAST_MOD | SOURCE_LAST_MOD.

package/bundled/skills/prizmkit-prizm-docs/references/op-update.md

@@ -0,0 +1,19 @@
+# Operation: Update — Detailed Steps
+
+Update .prizm-docs/ to reflect recent code changes.
+
+PRECONDITION: .prizm-docs/ exists with root.prizm.
+
+STEPS:
+1. Get changed files via `git diff --cached --name-status`. If nothing staged, use `git diff --name-status`. If no git changes at all, do full rescan comparing code against existing docs — this includes checking for modules that have source files but no L2 doc.
+2. Map changed files to modules by matching against MODULE_INDEX or MODULE_GROUPS in root.prizm. Group changes by module.
+3. Classify each change: A (added) -> new KEY_FILES entries. D (deleted) -> remove entries, update counts. M (modified) -> check dependency changes. R (renamed) -> update all path references.
+4. Update affected docs: L2 first (KEY_FILES, INTERFACES, DATA_FLOW, DEPENDENCIES, TRAPS, CHANGELOG), then L1 (FILES count, KEY_FILES, DEPENDENCIES — L1 does NOT contain INTERFACES/DATA_FLOW/TRAPS/DECISIONS), then L0 (MODULE_INDEX or MODULE_GROUPS counts, CROSS_CUTTING) only if structural change. No UPDATED timestamps — git tracks modification times. **Preserve** any `PROJECT_BRIEF:` line in root.prizm — it is managed by prizmkit-init, not by this skill.
+5. Skip updates if: only internal implementation changed (no interface/dependency change), only comments/whitespace/formatting, only .prizm files changed. DO NOT skip test file changes or bug fixes — they may reveal TRAPS worth capturing in L2.
+6. If new directory qualifies as a module (per MODULE_DISCOVERY_CRITERIA) and matches no existing module: create L1 immediately, add to MODULE_INDEX. If the current diff includes Added or Modified source files in this module → also create L2 immediately with sections: MODULE, FILES, RESPONSIBILITY, INTERFACES, DATA_FLOW, KEY_FILES, DEPENDENCIES, RULES, TRAPS, DECISIONS, CHANGELOG. Otherwise defer L2.
+6a. **L2 gap check** (runs during full rescan mode only — when no git changes detected): For each existing module in MODULE_INDEX, check if L2 doc exists. If L2 is missing and the module has source files with meaningful logic (not trivial config/wrapper) → create L2 with sections: MODULE, FILES, RESPONSIBILITY, INTERFACES, DATA_FLOW, KEY_FILES, DEPENDENCIES, RULES, TRAPS, DECISIONS, CHANGELOG. This ensures Update fills documentation gaps left by previous sessions.
+7. Append entries to changelog.prizm using format: `- <module-path> | <verb>: <description>`
+8. Enforce size limits: L0 > 4KB -> consolidate. L1 > 4KB -> trim KEY_FILES descriptions, ensure RULES <= 3 entries. L2 > 5KB -> split or archive.
+9. Stage updated .prizm files via `git add .prizm-docs/`
+
+OUTPUT: List of updated/created/skipped docs with reasons.

package/bundled/skills/prizmkit-prizm-docs/references/op-validate.md

@@ -0,0 +1,17 @@
+# Operation: Validate — Detailed Steps
+
+Check format compliance and consistency of all .prizm docs.
+
+PRECONDITION: .prizm-docs/ exists.
+
+STEPS:
+1. FORMAT CHECK: Verify all .prizm files use KEY: value format. Flag any prose paragraphs, code blocks (```), markdown headers (##), emoji, ASCII art, or horizontal rules. Flag TRAPS entries missing severity prefix ([CRITICAL], [HIGH], or [LOW]). Note: [REVIEW] preceding severity (e.g., `[REVIEW][HIGH]`) is a valid temporary staleness marker, not a format violation.
+2. SIZE CHECK: Verify size limits: L0 <= 4KB, L1 <= 4KB, L2 <= 5KB. Report files exceeding limits with current size.
+3. POINTER CHECK: Verify all arrow (->) references resolve to existing .prizm files. Report broken pointers.
+4. STALENESS CHECK: Compare git modification time of each .prizm file against source directory. Flag docs where source was modified more recently.
+5. COMPLETENESS CHECK: Verify root.prizm has all required fields (PRIZM_VERSION, PROJECT, LANG, MODULE_INDEX or MODULE_GROUPS). Verify L1 docs have MODULE, FILES, RESPONSIBILITY, DEPENDENCIES (no INTERFACES/TRAPS/DECISIONS). Verify L2 docs have MODULE, FILES, KEY_FILES, DEPENDENCIES, INTERFACES, TRAPS.
+6. ANTI-PATTERN CHECK: Flag duplicate information across levels, implementation details in L0/L1, TODO items, session-specific context.
+7. RULES HIERARCHY CHECK: Verify L1/L2 RULES do not contradict root.prizm RULES. L1/L2 may only supplement with module-specific exceptions.
+8. TRAPS STALENESS CHECK: For each L2 doc where TRAPS section has more than 8 entries, verify that TRAPS include staleness metadata (`STALE_IF:` or `REF:` fields). Flag TRAPS without any staleness metadata as `NEEDS_METADATA` — these are not auto-removed, but flagged for the next `/prizmkit-retrospective` to enrich with `STALE_IF:` globs or `REF:` hashes.
+
+OUTPUT: Validation report with PASS/FAIL per check, list of issues with file paths and suggested fixes.

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

@@ -19,19 +19,15 @@ For initial doc setup, validation, or migration, use `/prizmkit-prizm-docs` inst
 ## When to Use
 
 - **Before every commit** (mandatory in pipeline) — ensures docs and code are in sync
-- After completing a feature
-- After code review passes (PASS or PASS WITH WARNINGS)
+- After completing a feature, refactoring, or bug fix
+- After code review passes
 - User says "retrospective", "retro", "update docs", "sync docs", "wrap up"
-- After refactoring or bugfix cycles (structural sync + optional TRAPS update)
 
-## PRECONDITION
+## Input
 
-| Mode | Required Input | Expected Source | If Missing |
-|---|---|---|---|
-| **Feature** | Code review verdict (PASS/PASS_WITH_WARNINGS) | `.prizmkit/specs/###-feature-name/` context-snapshot.md Review Notes | Run `/prizmkit-code-review` |
-| **Refactor** | Code review verdict + behavior preservation evidence | `.prizmkit/refactor/<slug>/` context-snapshot.md | Run `/prizmkit-code-review` in refactor mode |
-| **Bugfix** | Code review verdict + regression test evidence | `.prizmkit/bugfix/<BUG_ID>/` context-snapshot.md | Run `/prizmkit-code-review` in bugfix mode |
-| **Standalone** (user-invoked) | Code changes in working tree | `git diff` output | No prerequisite — runs structural sync only |
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `artifact_dir` | No | Directory containing spec.md, plan.md, review-report.md. If omitted, scan `.prizmkit/` subdirectories for the most recently modified directory with a `plan.md`. If no artifact directory found, run in standalone mode (structural sync only from `git diff`). |
 
 ## When NOT to Use
 
@@ -39,32 +35,36 @@ For initial doc setup, validation, or migration, use `/prizmkit-prizm-docs` inst
 - Only test files changed — no module-level impact
 - Only .prizm files changed — avoid circular updates
 
-## PRECONDITION: Review Verdict Gate
-
-Before executing, check the most recent `/prizmkit-code-review` verdict from the current session context:
-
-| Verdict | Action |
-|---------|--------|
-| `PASS` | Proceed normally |
-| `PASS_WITH_WARNINGS` | Proceed normally (warnings are informational) |
-| `NEEDS_FIXES` | **ABORT** — do not sync docs for code that failed review. Output: "Code review verdict is NEEDS_FIXES. Fix the issues identified in code review first, then re-run `/prizmkit-code-review` before proceeding to retrospective." |
-| No verdict found | Proceed with warning: "No code review verdict found — running retrospective without review gate. Consider running `/prizmkit-code-review` first." |
-
-This gate prevents updating `.prizm-docs/` for code that hasn't passed review, which would create a false impression that the codebase is in a consistent, reviewed state.
-
 ---
 
 ### Job 1: Structural Sync (always runs)
 Synchronize `.prizm-docs/` structure with actual codebase changes from this session.
-→ Read `${SKILL_DIR}/references/structural-sync-steps.md` for the detailed 7-step procedure (1a–1g).
+→ Read `${SKILL_DIR}/references/structural-sync-steps.md` for the detailed procedure.
 
 **Key outputs**: Updated L1 file counts, L2 INTERFACES/DATA_FLOW, changelog entries, stale TRAPS cleanup.
 
 ---
 
-### Job 2: Knowledge Injection (conditional — skip for pure refactors)
+### Job 2: Knowledge Injection (conditional)
 Inject newly discovered project knowledge (TRAPS, RULES, DECISIONS) into architecture docs.
-→ Read `${SKILL_DIR}/references/knowledge-injection-steps.md` for the detailed 3-step procedure (2a–2c).
+→ Read `${SKILL_DIR}/references/knowledge-injection-steps.md` for the detailed procedure.
+
+**Review gate**: Before running Job 2, check `review-report.md` in the artifact directory for the `## Verdict:` line:
+- Verdict is `PASS` → proceed
+- Verdict is `NEEDS_FIXES` → **skip Job 2** — do not inject knowledge for code that hasn't passed review. Output warning: "Review report has unresolved findings. Skipping knowledge injection."
+- No `review-report.md` found → proceed with warning
+- No artifact directory (standalone mode) → skip Job 2, only Job 1 runs
+
+**Skip for**: pure refactors (no behavioral change).
+
+**Bug Fix Documentation Policy**:
+- DEFAULT for bug fixes: Run Job 1 (structural sync) only. Skip Job 2 (knowledge injection).
+- RUN Job 2 when the bug fix causes any of:
+  • Interface signature changes
+  • Dependency additions/removals
+  • Observable behavior changes to existing features
+  • Newly discovered TRAPs (gotchas/pitfalls)
+- When any of the above apply, run full retrospective (Job 1 + Job 2).
 
 **Key outputs**: New TRAPS entries, RULES updates, DECISIONS records in relevant L1/L2 docs and root.prizm.
 
@@ -82,45 +82,7 @@ Inject newly discovered project knowledge (TRAPS, RULES, DECISIONS) into archite
 git add .prizm-docs/
 ```
 
-**3c.** Handoff:
-- `/prizmkit-committer` — proceed to commit
-
----
-
-## Integration with Pipeline
-
-In the dev-pipeline, this skill is the **single doc maintenance step** before commit:
-
-```
-implement → code-review → retrospective (architecture sync) → committer (pure commit)
-```
-
-The pipeline enforces a **docs pass condition**: `.prizm-docs/` must show changes in the final commit. This skill satisfies that requirement.
-
-## HANDOFF Chain
-
-| From | To | Condition |
-|------|----|-----------|
-| `prizmkit-code-review` | **this skill** | Review verdict is PASS or PASS_WITH_WARNINGS |
-| **this skill** | `prizmkit-deploy` (conditional) | Architecture synced; deploy only if new infrastructure components detected (new DB, cache, MQ, etc.) |
-| **this skill** | `prizmkit-committer` (direct) | Architecture synced, no new infrastructure components |
-| `prizmkit-deploy` | `prizmkit-committer` | Deploy docs updated, ready to commit |
-| `prizmkit-committer` | — | Committed |
-
-### Deploy Decision Logic
-
-After structural sync and knowledge injection are complete, decide the next step:
-
-1. **Check if this is a fast-path change** (bugfix, config tweak, simple refactor) → skip deploy, go to `/prizmkit-committer`
-2. **Check `.prizmkit/config.json`** for `deploy_strategy` field:
-   - If absent → skip deploy (project hasn't configured deployment yet)
-   - If present → continue to step 3
-3. **Scan this session's changes** for new infrastructure indicators:
-   - New `Dockerfile`, `docker-compose.yml`, cloud config files (vercel.json, fly.toml, etc.)
-   - New database migrations, new cache/queue dependencies in package.json/requirements.txt
-   - New environment variables added to source code
-   - If any found → invoke `/prizmkit-deploy`
-   - If none found → go to `/prizmkit-committer`
+**HANDOFF:** `/prizmkit-committer`
 
 ## Output
 

package/bundled/skills/prizmkit-retrospective/references/knowledge-injection-steps.md

@@ -3,10 +3,9 @@
 **2a.** Gather context — read the **actual code that was changed** plus any available artifacts:
 
 - `git diff HEAD` — the real source of truth for what happened
-- `.prizmkit/specs/###-feature-name/context-snapshot.md` — read the '## Implementation Log' section (Dev's changes, decisions, discoveries) and '## Review Notes' section (Reviewer's findings). These are the **preferred source** for pre-categorized decisions and findings. If these sections exist, prefer them over re-extracting from git diff.
-- `.prizmkit/specs/###-feature-name/plan.md` — if feature work, read planned vs actual
-- `.prizmkit/bugfix/<id>/fix-report.md` — if bugfix, read what was discovered
-- `.prizmkit/specs/###-feature-name/failure-log.md` — if a previous session failed, read DISCOVERED_TRAPS. These are high-value TRAPS because they come from actual failures — prioritize injecting them into `.prizm-docs/`
+- `review-report.md` in the artifact directory — read the findings and fix instructions. If this file exists, use it as a source for pre-categorized decisions and findings.
+- `plan.md` in the artifact directory — read planned vs actual
+- Any companion documents in the artifact directory (e.g., `refactor-analysis.md`, `fix-report.md`) — read what was discovered
 - The relevant `.prizm-docs/` L1/L2 docs for affected modules
 
 **2b.** Extract knowledge from what was **observed in code**, not invented:

package/bundled/skills/prizmkit-retrospective/references/structural-sync-steps.md

@@ -1,4 +1,4 @@
-# Structural Sync — Detailed Steps (1a–1g)
+# Structural Sync — Detailed Steps
 
 **1a.** Get changed files:
 ```bash
@@ -19,16 +19,14 @@ git diff --name-status
 
 **1d.** Update affected docs (bottom-up: L2 → L1 → L0):
 
-- **L2**: If L2 exists → update KEY_FILES, INTERFACES, DATA_FLOW, DEPENDENCIES, CHANGELOG, TRAPS, DECISIONS. If L2 does NOT exist AND the module has Added or Modified source files in the current diff with meaningful logic (not trivial config) → create L2 using the L2 GENERATION TEMPLATE, then populate from source.
+- **L2**: If L2 exists → update KEY_FILES, INTERFACES, DATA_FLOW, DEPENDENCIES, CHANGELOG, TRAPS, DECISIONS. If L2 does NOT exist AND the module has Added or Modified source files in the current diff with meaningful logic (not trivial config) → create L2 with these sections: MODULE, FILES, RESPONSIBILITY, INTERFACES, DATA_FLOW, KEY_FILES, DEPENDENCIES, RULES, TRAPS, DECISIONS, CHANGELOG. Populate from source.
 - **L1**: Update FILES count, KEY_FILES (if major files added/removed), DEPENDENCIES (if module-level deps changed). **L1 does NOT contain INTERFACES, DATA_FLOW, TRAPS, or DECISIONS** — those belong in L2 only.
-- **L0 root.prizm**: Update MODULE_INDEX file counts only if counts changed. Update CROSS_CUTTING if cross-module concerns changed. Update only if structural change (module added/removed).
+- **L0 root.prizm**: Update MODULE_INDEX file counts only if counts changed. Update CROSS_CUTTING if cross-module concerns changed. Update only if structural change (module added/removed). **Preserve** any `PROJECT_BRIEF:` line — it is managed by prizmkit-init.
 
-**1d-migrate.** Legacy TRAPS format migration (opportunistic):
-While updating an affected L1/L2 doc, if you encounter TRAPS entries **without** a severity prefix (e.g., `- foo | FIX: bar` instead of `- [LOW] foo | FIX: bar`), prepend `[LOW]` as a conservative default. This clears legacy format debt incrementally — only in files already being touched, never as a bulk operation.
-
-**1e.** If new directory qualifies as a module (per MODULE_DISCOVERY_CRITERIA in PRIZM-SPEC Section 9.1 Step 2) and matches no existing module:
-1. Create L1 doc immediately, add to MODULE_INDEX.
-2. If the current diff includes Added or Modified source files with meaningful logic in this module → create L2 immediately using the L2 GENERATION TEMPLATE. Otherwise defer L2 to the next session that touches this module.
+**1e.** If new directory qualifies as a module and matches no existing module:
+- A directory qualifies as a module if any of: contains source files forming a logical unit, contains entry/config/interface files, contains qualifying sub-modules, or is referenced by multiple modules as dependency.
+- Create L1 doc immediately, add to MODULE_INDEX.
+- If the current diff includes Added or Modified source files with meaningful logic → create L2 immediately. Otherwise defer L2.
 
 **1f.** Enforce size limits:
 - L0 > 4KB → if using MODULE_INDEX with > 15 entries, convert to MODULE_GROUPS format (group by functional domain). Otherwise, consolidate MODULE_INDEX descriptions.
@@ -39,25 +37,9 @@ While updating an affected L1/L2 doc, if you encounter TRAPS entries **without**
 
 **1g. TRAPS staleness check** (only when an L2 doc's TRAPS section has > 10 entries):
 
-(Note: `/prizmkit-prizm-docs` Validate uses a lower threshold of > 8 entries to flag TRAPS needing staleness metadata. This step uses > 10 because it performs actual cleanup, which is more expensive. Validate warns early; this step acts later.)
-
 Perform a quick staleness scan on existing TRAPS to prevent unbounded accumulation:
 1. If a TRAP has `STALE_IF:` and the glob-matched files no longer exist (verified via `ls`) → delete the TRAP entry, append CHANGELOG: `remove: archived stale TRAP - <summary>`
 2. If a TRAP has `REF:` → check if the referenced file still exists and the REF commit is less than 180 days old (via `git log --since="180 days ago" <hash> 2>/dev/null`). If the file is deleted OR the REF commit is older than 180 days → prepend `[REVIEW]` to the severity, signaling it needs verification during the next retrospective Job 2
 3. Process at most 5 of the oldest TRAPS per L2 doc per session (to bound context cost)
 
 This step is lightweight — it only triggers when TRAPS exceed 10 entries, and processes at most 5 per run.
-
-**1h. Periodic full TRAPS audit** (runs approximately once every 10 retrospective sessions):
-
-Check `.prizm-docs/changelog.prizm` for the marker `audit: traps-audit full-scan`. If the marker does not exist, OR the most recent `audit: traps-audit full-scan` entry has 10+ other changelog entries after it:
-
-1. Scan ALL L2 `.prizm` files (not just ones touched this session)
-2. For each L2 doc with TRAPS entries:
-   - Verify referenced file paths still exist (via `ls`)
-   - If `STALE_IF:` glob matches zero files → delete the TRAP, append CHANGELOG: `remove: archived stale TRAP - <summary>`
-   - If `REF:` commit is older than 180 days AND the referenced file was significantly refactored (>50% lines changed since REF commit) → prepend `[REVIEW]`
-3. Process at most 3 TRAPS per L2 doc to bound context cost (total max ~15 TRAPS per audit)
-4. Append to `.prizm-docs/changelog.prizm`: `- root | audit: traps-audit full-scan — checked N docs, removed M stale, marked K for review`
-
-This is a lightweight background pass. If the project has fewer than 5 L2 docs, skip this step (not enough accumulation to warrant auditing).

package/bundled/skills/recovery-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "recovery-workflow"
-description: "Recover and resume interrupted interactive workflow sessions. Auto-detects which workflow (feature-workflow, bug-fix-workflow, refactor-workflow) was interrupted and what phase it reached by inspecting git branch names, characteristic artifacts, and pipeline state — then resumes from the breakpoint. Use this skill whenever an AI CLI session is interrupted mid-workflow, times out, or hits token limits. Trigger on: 'recover', 'resume', 'continue where I left off', 'session interrupted', 'session timed out', 'pick up where it left off', 'token limit exceeded', 'salvage partial work'. (project)"
+description: "Recover and resume interrupted interactive workflow sessions. Auto-detects which workflow (feature-workflow, bug-fix-workflow, refactor-workflow) was interrupted and what phase it reached by inspecting git branch names, characteristic artifacts, and pipeline state — then resumes from the breakpoint. Use this skill whenever an AI CLI session is interrupted mid-workflow, times out, or hits token limits. Trigger on: 'recover', 'resume', 'continue where I left off', 'session interrupted', 'session timed out', 'pick up where it left off', 'token limit exceeded', 'salvage partial work'."
 ---
 
 # Recovery Workflow
@@ -25,8 +25,8 @@ User says:
 | Workflow | Branch Pattern | Key Artifacts |
 |----------|---------------|---------------|
 | bug-fix-workflow | `fix/<BUG_ID>-*` | `.prizmkit/bugfix/<BUG_ID>/fix-plan.md`, `fix-report.md` |
-| feature-workflow | `feat/*` | `feature-list.json`, `dev-pipeline/state/features/` |
-| refactor-workflow | `refactor/*` | `refactor-list.json`, `dev-pipeline/state/refactors/` |
+| feature-workflow | `feat/*` | `.prizmkit/plans/feature-list.json`, `.prizmkit/state/features/features/` |
+| refactor-workflow | `refactor/*` | `.prizmkit/plans/refactor-list.json`, `.prizmkit/state/refactor/refactors/` |
 
 ---
 
@@ -71,9 +71,9 @@ The script uses **priority-ordered signature matching**:
 1. Current branch matches fix/*           → bug-fix-workflow
 2. .prizmkit/bugfix/ directory has content → bug-fix-workflow
 3. Current branch matches refactor/*       → refactor-workflow
-4. refactor-list.json exists               → refactor-workflow
+4. .prizmkit/plans/refactor-list.json exists               → refactor-workflow
 5. Current branch matches feat/*           → feature-workflow
-6. feature-list.json exists                → feature-workflow
+6. .prizmkit/plans/feature-list.json exists                → feature-workflow
 7. None of the above                       → no workflow detected
 ```
 
@@ -92,7 +92,7 @@ To start a new workflow:
   • /refactor-workflow  — behavior-preserving code restructuring
 ```
 
-**CHECKPOINT CP-RW-0**: Workflow type and phase identified.
+**CHECKPOINT CP-REC-0**: Workflow type and phase identified.
 
 ---
 
@@ -148,7 +148,7 @@ If the user declines, suggest alternatives:
 - "Use `/feature-workflow` to start fresh"
 - "Use `/refactor-workflow` to start fresh"
 
-**CHECKPOINT CP-RW-1**: User confirmed recovery.
+**CHECKPOINT CP-REC-1**: User confirmed recovery.
 
 ---
 
@@ -160,10 +160,10 @@ If the user declines, suggest alternatives:
 
 1. **Read the workflow's SKILL.md** from `core/skills/orchestration-skill/workflows/{workflow-type}/SKILL.md`
 2. **Read existing artifacts** to restore context — check in this order for the most efficient recovery:
-   - If `session-summary.md` exists in the artifact directory → read it first. It provides a lightweight summary of completed tasks, key decisions, active TRAPS, and remaining work from the interrupted session.
-     > **Note**: `session-summary.md` is generated by the pipeline's bootstrap prompt system (`generate-bootstrap-prompt.py`) at the end of each AI CLI session. It may not exist if the session crashed before completion or if running in interactive (non-pipeline) mode. If absent, reconstruct context from the artifacts below.
-   - Then read remaining artifacts: spec, plan, code diffs, bug descriptions, etc.
-3. **Read relevant `.prizm-docs/`** — load project context (L0 root, relevant L1). If `session-summary.md` was found, use its "Files Changed" section to focus L1/L2 loading on affected modules only.
+   - If `context-snapshot.md` exists in the artifact directory → read it first. It provides a snapshot of completed tasks, key decisions, and remaining work from the interrupted session.
+   - If `session-summary.md` exists → read it for a lightweight summary of the previous session.
+   - Then read remaining artifacts: spec.md, plan.md, review-report.md, code diffs, bug descriptions, etc.
+3. **Read relevant `.prizm-docs/`** — load project context (L0 root, relevant L1/L2 for affected modules).
 
 This step replaces the context that was lost when the AI session was interrupted.
 
@@ -175,7 +175,7 @@ Phase inference table:
 
 | Detected State | Resume From | Actions |
 |---------------|------------|---------|
-| On `fix/<BUG_ID>-*` branch, no artifacts | Phase 1: Deep Bug Diagnosis | Read bug description from `bug-fix-list.json`. Start interactive diagnosis Q&A |
+| On `fix/<BUG_ID>-*` branch, no artifacts | Phase 1: Deep Bug Diagnosis | Read bug description from `.prizmkit/plans/bug-fix-list.json`. Start interactive diagnosis Q&A |
 | `fix-plan.md` exists, no code changes | Phase 4: Fix | Read fix-plan.md. Implement the fix following the plan |
 | `fix-plan.md` + code changes exist | Phase 5: Review | Invoke `/prizmkit-code-review` on all changes |
 | All docs + review passed | Phase 6: User Verification | Ask user to verify the fix works |
@@ -195,11 +195,11 @@ Phase inference table:
 
 | Detected State | Resume From | Actions |
 |---------------|------------|---------|
-| No `feature-list.json` | Phase 1: Brainstorm | Cannot recover conversation context. Start requirement clarification, but leverage any workspace content (README, existing code) for context |
-| `feature-list.json` exists, no pipeline state | Phase 3: Launch | Invoke `feature-pipeline-launcher` to start the pipeline |
-| `feature-list.json` + pipeline state exists | Phase 4: Monitor | Check pipeline status via `feature-pipeline-launcher` (Intent B: Check Status) |
+| No `.prizmkit/plans/feature-list.json` | Phase 1: Brainstorm | Cannot recover conversation context. Start requirement clarification, but leverage any workspace content (README, existing code) for context |
+| `.prizmkit/plans/feature-list.json` exists, no pipeline state | Phase 3: Launch | Invoke `feature-pipeline-launcher` to start the pipeline |
+| `.prizmkit/plans/feature-list.json` + pipeline state exists | Phase 4: Monitor | Check pipeline status via `feature-pipeline-launcher` (Intent B: Check Status) |
 
-**Note**: Feature-workflow recovery is simpler because Phases 3-4 are pipeline-driven. The main recovery value is avoiding re-brainstorming (Phase 1) when `feature-list.json` already exists.
+**Note**: Feature-workflow recovery is simpler because Phases 3-4 are pipeline-driven. The main recovery value is avoiding re-brainstorming (Phase 1) when `.prizmkit/plans/feature-list.json` already exists.
 
 ---
 
@@ -209,9 +209,9 @@ Phase inference table (mirrors feature-workflow):
 
 | Detected State | Resume From | Actions |
 |---------------|------------|---------|
-| No `refactor-list.json` | Phase 1: Brainstorm | Start refactoring goal clarification |
-| `refactor-list.json` exists, no pipeline state | Phase 3: Launch | Invoke `refactor-pipeline-launcher` to start the pipeline |
-| `refactor-list.json` + pipeline state exists | Phase 4: Monitor | Check pipeline status |
+| No `.prizmkit/plans/refactor-list.json` | Phase 1: Brainstorm | Start refactoring goal clarification |
+| `.prizmkit/plans/refactor-list.json` exists, no pipeline state | Phase 3: Launch | Invoke `refactor-pipeline-launcher` to start the pipeline |
+| `.prizmkit/plans/refactor-list.json` + pipeline state exists | Phase 4: Monitor | Check pipeline status |
 
 ---
 
@@ -232,7 +232,7 @@ Recovery complete.
     • Or start a new workflow
 ```
 
-**CHECKPOINT CP-RW-2**: Workflow recovered and completed.
+**CHECKPOINT CP-REC-2**: Workflow recovered and completed.
 
 ---
 
@@ -243,9 +243,9 @@ Recovery complete.
 | No workflow signature matches | Show guidance message, suggest original workflow skills |
 | Branch exists but artifacts are inconsistent | Trust git as ground truth, report discrepancy in detection report |
 | Test failures in existing code | Report in detection summary; user decides whether to continue |
-| Multiple workflows could match (e.g., on main but both feature-list.json and bug-fix artifacts exist) | Pick highest priority (bug-fix > refactor > feature), mention others in report |
+| Multiple workflows could match (e.g., on main but both .prizmkit/plans/feature-list.json and bug-fix artifacts exist) | Pick highest priority (bug-fix > refactor > feature), mention others in report |
 | Detection script fails | Fall back to manual detection (run individual git/file checks in bash) |
-| Bug ID not found in bug-fix-list.json | Continue with branch-only context; note that full bug description is unavailable |
+| Bug ID not found in .prizmkit/plans/bug-fix-list.json | Continue with branch-only context; note that full bug description is unavailable |
 
 ---
 

package/bundled/skills/recovery-workflow/evals/evals.json

@@ -22,16 +22,16 @@
       "id": 3,
       "name": "feature-list-exists",
       "prompt": "resume",
-      "expected_output": "Should auto-detect feature-workflow from feature-list.json. Should detect feature-list.json exists but no pipeline state → infer Phase 3 (Launch). Should invoke feature-pipeline-launcher to start the pipeline.",
-      "setup_description": "On main branch, create feature-list.json with 3 features. No dev-pipeline/state/features/ directory.",
+      "expected_output": "Should auto-detect feature-workflow from .prizmkit/plans/feature-list.json. Should detect .prizmkit/plans/feature-list.json exists but no pipeline state → infer Phase 3 (Launch). Should invoke feature-pipeline-launcher to start the pipeline.",
+      "setup_description": "On main branch, create .prizmkit/plans/feature-list.json with 3 features. No .prizmkit/state/features/features/ directory.",
       "files": []
     },
     {
       "id": 4,
       "name": "refactor-monitoring",
       "prompt": "pick up where it left off",
-      "expected_output": "Should auto-detect refactor-workflow from refactor-list.json + pipeline state. Should infer Phase 4 (Monitor). Should check pipeline status and report results.",
-      "setup_description": "On main branch, create refactor-list.json with 2 items. Create dev-pipeline/state/refactors/ with status files showing 1 completed, 1 in-progress.",
+      "expected_output": "Should auto-detect refactor-workflow from .prizmkit/plans/refactor-list.json + pipeline state. Should infer Phase 4 (Monitor). Should check pipeline status and report results.",
+      "setup_description": "On main branch, create .prizmkit/plans/refactor-list.json with 2 items. Create .prizmkit/state/refactor/refactors/ with status files showing 1 completed, 1 in-progress.",
       "files": []
     },
     {
@@ -39,7 +39,7 @@
       "name": "no-workflow-detected",
       "prompt": "恢复",
       "expected_output": "Should detect no workflow signatures in workspace. Should display guidance message suggesting /feature-workflow, /bug-fix-workflow, or /refactor-workflow. Should NOT attempt any recovery actions.",
-      "setup_description": "Clean workspace on main branch. No feature-list.json, no bug-fix artifacts, no refactor-list.json, no fix/* or feat/* or refactor/* branches.",
+      "setup_description": "Clean workspace on main branch. No .prizmkit/plans/feature-list.json, no bug-fix artifacts, no .prizmkit/plans/refactor-list.json, no fix/* or feat/* or refactor/* branches.",
       "files": []
     }
   ]

package/bundled/skills/recovery-workflow/scripts/detect-recovery-state.py

@@ -85,7 +85,14 @@ def detect_workflow_type(project_root):
         return ("refactor-workflow", {"branch": branch})
 
     # Priority 4: refactor-list.json exists → refactor-workflow
-    if os.path.isfile(os.path.join(project_root, "refactor-list.json")):
+    # Check both new and old paths for backward compatibility
+    new_refactor = os.path.join(project_root, ".prizmkit", "plans", "refactor-list.json")
+    old_refactor = os.path.join(project_root, "refactor-list.json")
+    if os.path.isfile(new_refactor):
+        return ("refactor-workflow", {"branch": branch})
+    elif os.path.isfile(old_refactor):
+        print(f"⚠️  Migration notice: refactor-list.json found in root. "
+              f"Please move to .prizmkit/plans/refactor-list.json", file=sys.stderr)
         return ("refactor-workflow", {"branch": branch})
 
     # Priority 5: feat/* branch → feature-workflow
@@ -93,7 +100,14 @@ def detect_workflow_type(project_root):
         return ("feature-workflow", {"branch": branch})
 
     # Priority 6: feature-list.json exists → feature-workflow
-    if os.path.isfile(os.path.join(project_root, "feature-list.json")):
+    # Check both new and old paths for backward compatibility
+    new_feature = os.path.join(project_root, ".prizmkit", "plans", "feature-list.json")
+    old_feature = os.path.join(project_root, "feature-list.json")
+    if os.path.isfile(new_feature):
+        return ("feature-workflow", {"branch": branch})
+    elif os.path.isfile(old_feature):
+        print(f"⚠️  Migration notice: feature-list.json found in root. "
+              f"Please move to .prizmkit/plans/feature-list.json", file=sys.stderr)
         return ("feature-workflow", {"branch": branch})
 
     # No match
@@ -164,10 +178,27 @@ def _infer_pipeline_workflow_phase(project_root, list_filename, state_subdir, wo
       No list file                → Phase 1: Brainstorm
       List file, no pipeline state → Phase 3: Launch
       List file + pipeline state   → Phase 4: Monitor
+
+    Checks new path (.prizmkit/plans/<list_filename>) first, then falls back
+    to old root-level path with a migration warning.
     """
-    has_list = os.path.isfile(os.path.join(project_root, list_filename))
-    state_dir = os.path.join(project_root, "dev-pipeline", "state", state_subdir)
-    has_pipeline_state = os.path.isdir(state_dir) and bool(os.listdir(state_dir))
+    # Check new path first, then old path with fallback warning
+    new_list_path = os.path.join(project_root, ".prizmkit", "plans", list_filename)
+    old_list_path = os.path.join(project_root, list_filename)
+    has_list = os.path.isfile(new_list_path)
+    if not has_list and os.path.isfile(old_list_path):
+        has_list = True
+        print(f"⚠️  Migration notice: {list_filename} found in root. "
+              f"Please move to .prizmkit/plans/{list_filename}", file=sys.stderr)
+
+    # Check new state path first, then old path with fallback warning
+    new_state_dir = os.path.join(project_root, ".prizmkit", "state", state_subdir)
+    old_state_dir = os.path.join(project_root, "dev-pipeline", "state", state_subdir)
+    has_pipeline_state = os.path.isdir(new_state_dir) and bool(os.listdir(new_state_dir))
+    if not has_pipeline_state and os.path.isdir(old_state_dir) and bool(os.listdir(old_state_dir)):
+        has_pipeline_state = True
+        print(f"⚠️  Migration notice: pipeline state found at dev-pipeline/state/{state_subdir}. "
+              f"Please move to .prizmkit/state/{state_subdir}", file=sys.stderr)
 
     artifacts = {
         f"{workflow_label}_list_exists": has_list,
@@ -176,16 +207,16 @@ def _infer_pipeline_workflow_phase(project_root, list_filename, state_subdir, wo
 
     if has_list and has_pipeline_state:
         return 4, "Monitor", artifacts, \
-            f"{list_filename} + pipeline state exist", \
+            f".prizmkit/plans/{list_filename} + pipeline state exist", \
             "check pipeline status and report results"
 
     if has_list:
         return 3, "Launch", artifacts, \
-            f"{list_filename} exists, no pipeline state", \
+            f".prizmkit/plans/{list_filename} exists, no pipeline state", \
             "launch pipeline → monitor progress"
 
     return 1, "Brainstorm", artifacts, \
-        f"no {list_filename} found", \
+        f"no .prizmkit/plans/{list_filename} found", \
         f"{workflow_label} goal clarification → plan → launch → monitor"
 
 
@@ -199,7 +230,7 @@ def infer_feature_phase(project_root):
 def infer_refactor_phase(project_root):
     """Infer refactor-workflow phase from artifacts and pipeline state."""
     return _infer_pipeline_workflow_phase(
-        project_root, "refactor-list.json", "refactors", "refactor"
+        project_root, "refactor-list.json", "refactor", "refactor"
     )
 
 
@@ -256,6 +287,9 @@ def detect_code_changes(project_root, main_branch="main"):
     files that represent actual implementation work.
     """
     IGNORED_FILES = {
+        ".prizmkit/plans/feature-list.json",
+        ".prizmkit/plans/bug-fix-list.json",
+        ".prizmkit/plans/refactor-list.json",
         "feature-list.json",
         "bug-fix-list.json",
         "refactor-list.json",
@@ -265,7 +299,6 @@ def detect_code_changes(project_root, main_branch="main"):
     }
     IGNORED_PREFIXES = (
         ".prizmkit/",
-        "dev-pipeline/state/",
         ".prizm-docs/",
         ".claude/",
         ".codebuddy/",