prizmkit 1.1.8 → 1.1.10

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
@@ -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.
 
@@ -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.
 
 ---
 

package/bundled/skills/refactor-pipeline-launcher/SKILL.md

@@ -135,20 +135,16 @@ Detect user intent from their message, then follow the corresponding workflow:
 
    Use `AskUserQuestion` to present the following configuration choices. Each question is a separate selectable option:
 
-   **Question 1 — Critic review** (multiSelect: false):
-   - Off (default) — Skip adversarial review
-   - On — Enable critic review after refactoring (+3-8 min/refactor for critical/high complexity)
-
-   **Question 2 — Verbose logging** (multiSelect: false):
+   **Question 1 — Verbose logging** (multiSelect: false):
    - On (default) — Detailed AI session logs including tool calls and subagent activity
    - Off — Minimal logging
 
-   **Question 3 — Max retries** (multiSelect: false):
+   **Question 2 — Max retries** (multiSelect: false):
    - 3 (default)
    - 1
    - 5
 
-   **Question 4 — Session timeout** (multiSelect: false):
+   **Question 3 — Session timeout** (multiSelect: false):
    - None (default) — No timeout
    - 30 min — `SESSION_TIMEOUT=1800`
    - 1 hour — `SESSION_TIMEOUT=3600`
@@ -171,6 +167,19 @@ Detect user intent from their message, then follow the corresponding workflow:
    | Strict behavior: On | `STRICT_BEHAVIOR_CHECK=1` |
    | Strict behavior: Off | `STRICT_BEHAVIOR_CHECK=0` |
 
+   **Advanced environment variables** (not exposed in interactive menu, pass via `--env`):
+
+   | Variable | Default | Purpose |
+   |----------|---------|---------|
+   | `MODEL` | (none) | AI model override (e.g. `claude-opus-4.6`) |
+   | `AUTO_PUSH` | `0` | Auto-push to remote after successful refactor (`1` to enable) |
+   | `DEV_BRANCH` | auto-generated | Custom dev branch name (default: `refactor/pipeline-{run_id}`) |
+   | `HEARTBEAT_INTERVAL` | `30` | Heartbeat log interval in seconds |
+   | `HEARTBEAT_STALE_THRESHOLD` | `600` | Max seconds without heartbeat before marking stale |
+   | `LOG_CLEANUP_ENABLED` | `1` | Run periodic log cleanup (`0` to disable) |
+   | `LOG_RETENTION_DAYS` | `14` | Delete logs older than N days |
+   | `LOG_MAX_TOTAL_MB` | `1024` | Keep total logs under N MB via oldest-first cleanup |
+
    ⚠️ STOP HERE and wait for user response before continuing to step 7.
 
 7. **Show final command**: After user confirms configuration in step 6, assemble the complete command from execution mode + user-confirmed configuration, and present it to the user.
@@ -324,8 +333,7 @@ SESSION_TIMEOUT=3600 STRICT_BEHAVIOR_CHECK=1 dev-pipeline/retry-refactor.sh R-00
 ```
 
 Notes:
-- `retry-refactor.sh` runs exactly one refactor session and exits.
-- `reset-refactor.sh --clean --run` clears the refactor state before retrying (fresh start).
+- `retry-refactor.sh` runs exactly one refactor session and exits. It **preserves prior session artifacts and checkpoint state** — reads `retry_count` and `resume_from_phase` from `status.json` so the AI session can resume from where it left off. For a full clean retry, use `dev-pipeline/reset-refactor.sh <R-XXX> --clean --run`.
 - Keep pipeline daemon mode for main run management (`launch-refactor-daemon.sh`).
 
 ---

package/bundled/skills/refactor-planner/SKILL.md

@@ -35,13 +35,13 @@ The user chose this skill intentionally. Respect that choice.
 
 **Your ONLY writable outputs are:**
 1. `.prizmkit/plans/refactor-list.json` (`.prizmkit/plans/`)
-2. Draft backups in `.prizmkit/planning/`
+2. Draft backups in `.prizmkit/plans/` (e.g., `refactor-list.draft.json`)
 
 **After planning is complete**, you MUST:
 1. Present the summary and recommended next step
 2. **Ask the user explicitly** whether they want to proceed to execution
-3. If the user agrees -> recommend invoking `refactor-pipeline-launcher` or running `run-refactor.sh` (do NOT execute it yourself)
-4. If the user wants to adjust -> continue refining `.prizmkit/plans/refactor-list.json`
+3. If the user agrees → recommend invoking `refactor-pipeline-launcher` (do NOT execute it yourself)
+4. If the user wants to adjust → continue refining `.prizmkit/plans/refactor-list.json`
 5. **NEVER auto-execute** the pipeline, launcher, or any implementation step
 
 ## When to Use
@@ -240,12 +240,19 @@ Continue until all items are confirmed or skipped.
 
 ### Phase 6: Completeness Review
 
-**Goal**: Check the full item set for consistency and gaps.
+**Goal**: Check the full item set for consistency, gaps, and headless execution readiness.
 
 1. **Dependency ordering check**: Verify items form a valid DAG (no cycles). Items should be ordered: safe renames -> extract/inline -> structural changes -> migrations
 2. **Behavior preservation check**: Every item must have a declared preservation strategy. Flag any item with `manual` strategy and no test coverage.
 3. **Gap detection**: Are there intermediate steps needed between items? Does item A's output match item B's input assumption?
 4. **Cross-module impact**: Do any items affect modules outside the declared scope?
+5. **Headless Execution Readiness**: The refactor pipeline runs each item through an autonomous AI session with NO human interaction. For each item, verify:
+   - **Scope clarity**: Are all affected files explicitly listed? The AI must know exactly where to look.
+   - **Refactoring instructions**: Is the description specific enough to execute without ambiguity?
+     - ❌ "Clean up the utils module" — what exactly should change?
+     - ✅ "Extract validation functions (validateEmail, validatePhone, validateUrl) from src/utils/helpers.ts into src/utils/validation.ts. Update all 12 import sites. Preserve existing function signatures."
+   - **Behavior preservation**: Is it clear what tests to run and what behavior must be preserved?
+   - **Dependency context**: If item depends on earlier refactors, does the description reference what changed?
 
 Present review summary:
 ```
@@ -286,7 +293,7 @@ If issues found, discuss with user and resolve before proceeding.
 | **CP-RP-5** | Completeness OK | DAG valid, preservation strategies declared, no gaps | 6 |
 | **CP-RP-6** | Output Valid | `.prizmkit/plans/refactor-list.json` passes validation script | 7 |
 
-**Resume Detection**: If existing artifacts found (partial `.prizmkit/plans/refactor-list.json`, draft in `.prizmkit/planning/`), offer to resume from the appropriate checkpoint.
+**Resume Detection**: If existing artifacts found (partial `.prizmkit/plans/refactor-list.json`, draft `refactor-list.draft.json` in `.prizmkit/plans/`), offer to resume from the appropriate checkpoint.
 
 ## Output Rules
 
@@ -295,7 +302,7 @@ If issues found, discuss with user and resolve before proceeding.
 - Non-empty `refactors` array
 - Sequential IDs: `R-001`, `R-002`, ...
 - Valid dependency DAG (no cycles)
-- Each item has a declared `behavior_preservation` strategy: `test-gate`, `snapshot`, or `manual`
+- Each item has a declared `behavior_preservation` object with `strategy` field: `"test-gate"`, `"snapshot"`, or `"manual"`. Optional fields: `existing_tests` (boolean), `new_tests_needed` (string array). See `dev-pipeline/templates/refactor-list-schema.json` for the full schema.
 - `priority` must be a string: `"critical"`, `"high"`, `"medium"`, or `"low"`
 - New items default `status: "pending"`
 - English titles for stable slug generation
@@ -304,27 +311,16 @@ If issues found, discuss with user and resolve before proceeding.
 - `model` field is optional — omitting it means the pipeline uses $MODEL env or CLI default
 - `scope` object with nested structure: `files` array (target file paths) and `modules` array (module names)
 
-## Adversarial Critic Review
+## Adversarial Critic Defaults
 
-All refactoring items support optional critic review for additional quality assurance. The critic mechanism helps validate that refactoring preserves behavior while improving code quality.
+Set default critic fields for each refactor item. The user can override per-item.
 
-### Default Critic Behavior
-
-| Priority | Complexity | `critic` | `critic_count` | Rationale |
-|----------|-----------|----------|----------------|-----------|
-| critical | high | `true` | `3` | Multi-critic voting for high-risk refactors |
-| critical | medium/low | `true` | `1` | Single critic for critical-priority refactors |
-| high | high | `true` | `1` | Single critic for high-complexity refactors |
-| high | medium/low | `false` | (omitted) | Skip critic for simpler high-priority items |
-| medium | any | `false` | (omitted) | Skip critic for medium-priority refactors |
-| low | any | `false` | (omitted) | Skip critic for low-priority refactors |
-
-- `critic: true` — Enable adversarial review after refactoring completion
-- `critic_count: 1` — Single critic agent reviews the refactor
-- `critic_count: 3` — Three critic agents vote on the refactor quality
-- Critic verifies: behavior preservation strategy followed, code quality improved, no regressions, tests passing
-
-**User Override**: During planning phases, users can opt to enable/disable critic on a per-item basis.
+| Priority | Complexity | `critic` | `critic_count` |
+|----------|-----------|----------|----------------|
+| critical | high | `true` | `3` |
+| critical | medium/low | `true` | `1` |
+| high | high | `true` | `1` |
+| other combinations | any | `false` | (omitted) |
 
 ---
 
@@ -423,21 +419,7 @@ Take the highest of these individual assessments as the item's complexity.
 
 ## Next-Step Execution Policy (after planning)
 
-Recommend these three options in this strict order:
-
-1. **Preferred**: invoke `refactor-pipeline-launcher` skill (natural-language handoff)
-2. **Fallback A**: run daemon wrapper
-   ```bash
-   ./dev-pipeline/launch-refactor-daemon.sh start .prizmkit/plans/refactor-list.json
-   ./dev-pipeline/launch-refactor-daemon.sh status
-   ```
-3. **Fallback B**: run direct foreground script
-   ```bash
-   ./dev-pipeline/run-refactor.sh run
-   ./dev-pipeline/run-refactor.sh status
-   ```
-
-When launcher is available, do not prioritize raw scripts.
+Recommend invoking `refactor-pipeline-launcher` to configure and launch the dev-pipeline. Do NOT recommend running shell scripts directly — that is the launcher's responsibility.
 
 ## Error Recovery & Resume
 
@@ -452,7 +434,7 @@ Key behaviors:
 | Artifact Found | Resume From |
 |---------------|------------|
 | Nothing | Phase 1: Project Context |
-| Draft in `.prizmkit/planning/` | Phase matching draft state |
+| Draft in `.prizmkit/plans/` | Phase matching draft state |
 | Partial `.prizmkit/plans/refactor-list.json` | Phase 6: Completeness Review |
 | Valid `.prizmkit/plans/refactor-list.json` | Mode D: Summary |
 

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

@@ -1,7 +1,6 @@
 ---
 name: "refactor-workflow"
-tier: companion
-description: "One-stop entry point for code refactoring. Brainstorms refactoring goals with the user until fully clarified, then orchestrates refactor-planner → refactor-pipeline-launcher → execution. Handles multi-refactor batch development from a single request. Use this skill whenever the user wants to restructure, clean up, or optimize code without changing behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', 'code refactoring', 'batch refactor'. (project)"
+description: "One-stop entry point for code refactoring. Brainstorms refactoring goals with the user until fully clarified, then orchestrates refactor-planner → refactor-pipeline-launcher → execution. Handles multi-refactor batch development from a single request. Use this skill whenever the user wants to restructure, clean up, or optimize code without changing behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', 'code refactoring', 'batch refactor'."
 ---
 
 # Refactor Workflow

package/bundled/team/prizm-dev-team.json

@@ -20,7 +20,7 @@
       "name": "reviewer",
       "role": "reviewer",
       "agentDefinition": "prizm-dev-team-reviewer",
-      "prompt": "You are the Reviewer Agent of the prizm-dev-team. In Phase 4: run /prizmkit-analyze for cross-document consistency. In Phase 6: run /prizmkit-code-review for diagnosis + fix strategy formulation, write and execute integration tests. Produce structured Fix Instructions (Root Cause, Impact, Fix Strategy, Code Guidance, Verification) so Dev can follow them precisely. Write Fix Instructions to context-snapshot.md '## Review Notes' section.",
+      "prompt": "You are the Reviewer Agent of the prizm-dev-team. Run /prizmkit-code-review for diagnosis + fix strategy formulation, write and execute integration tests. Produce structured Fix Instructions (Root Cause, Impact, Fix Strategy, Code Guidance, Verification) so Dev can follow them precisely. review-report.md is written to the artifact directory by /prizmkit-code-review.",
       "subscriptions": ["*"]
     },
     {

package/bundled/{skills/prizm-kit/assets → templates}/project-memory-template.md

@@ -37,6 +37,6 @@ Not every change needs the full spec -> plan workflow. Use fast path for:
 - Documentation-only changes, test additions for existing code
 - Fast path: `/prizmkit-plan` (simplified) → `/prizmkit-implement` → `/prizmkit-committer`
 
-Use the full workflow (/prizmkit-plan -> /prizmkit-analyze -> /prizmkit-implement) for:
+Use the full workflow (/prizmkit-plan -> /prizmkit-implement) for:
 - New features, multi-file coordinated changes, architectural decisions, data model or API changes
 <!-- PRIZMKIT:END -->

package/package.json

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

package/src/clean.js

@@ -122,7 +122,6 @@ export async function runClean(directory, options = {}) {
     path.join('.prizmkit', 'plans', 'feature-list.json'),          // feature-planner output
     path.join('.prizmkit', 'plans', 'bug-fix-list.json'),          // bug-planner output
     path.join('.prizmkit', 'plans', 'project-brief.md'),           // feature-planner project brief
-    path.join('.prizmkit', 'project-conventions.json'),   // feature-planner coding conventions
     path.join('.codebuddy', 'settings.json'),
     path.join('.claude', 'settings.json'),
     path.join('.claude', 'team-info.json'),

package/src/gitignore-template.js

@@ -25,7 +25,6 @@ export function generateGitignore(options = {}) {
     '',
     '# 规划产物（按需决定是否提交）',
     '# .prizmkit/plans/',
-    '# project-conventions.json',
     '',
   ];
 

package/src/scaffold.js

@@ -537,11 +537,9 @@ export async function installProjectMemory(platform, projectRoot, dryRun) {
   const targetName = platform === 'claude' ? 'CLAUDE.md' : 'CODEBUDDY.md';
   const targetPath = path.join(projectRoot, targetName);
 
-  // Prefer core/templates, fallback to prizm-kit/assets in hierarchical or flat skills layouts.
+  // Template lives in core/templates/ (bundled as templates/).
   const templateCandidates = [
     path.join(templatesDir, templateName),
-    path.join(skillsDir, 'prizmkit-skill', 'prizm-kit', 'assets', templateName),
-    path.join(skillsDir, 'prizm-kit', 'assets', templateName),
   ];
   const templatePath = templateCandidates.find(candidate => fs.pathExistsSync(candidate));
 
@@ -690,6 +688,15 @@ export async function installPipeline(projectRoot, dryRun, { forceOverwrite = fa
   }
 
   console.log(chalk.green(`      ✓ dev-pipeline/ (${installedCount} 项)`));
+
+  // Copy .env.example to project root if it exists in pipeline source
+  const envExampleSrc = path.join(pipelineSource, '.env.example');
+  const envExampleTgt = path.join(projectRoot, '.env.example');
+  if (await fs.pathExists(envExampleSrc) && !await fs.pathExists(envExampleTgt)) {
+    await fs.copy(envExampleSrc, envExampleTgt);
+    console.log(chalk.green(`      ✓ .env.example (pipeline environment configuration)`));
+  }
+
   return installedFiles;
 }
 

package/bundled/dev-pipeline/templates/agent-prompts/reviewer-analyze.md

@@ -1,5 +0,0 @@
-"Read {{REVIEWER_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
-1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has project context, Section 4 has file manifest.
-2. Run prizmkit-analyze: cross-check `spec.md` and `plan.md` (including Tasks section) for consistency.
-3. Before flagging CRITICAL or HIGH issues, read the relevant source files listed in the File Manifest to verify.
-Report: CRITICAL, HIGH, MEDIUM issues found (or 'No issues found')."

package/bundled/dev-pipeline/templates/sections/phase-analyze-agent.md

@@ -1,19 +0,0 @@
-### Analyze — Reviewer Subagent
-
-**Spawn Agent**:
-| Parameter | Value |
-|-----------|-------|
-| subagent_type | prizm-dev-team-reviewer |
-| mode | plan |
-| run_in_background | false |
-
-**Prompt**:
-> {{AGENT_PROMPT_REVIEWER_ANALYZE}}
-
-Wait for Reviewer to return.
-- If CRITICAL issues found: fix them yourself — read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` for full project context. Fix ONLY the listed CRITICAL issues in plan.md. Then re-run analyze (max 1 round).
-
-**CP-2**: No CRITICAL issues.
-
-
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-analyze` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-analyze-full.md

@@ -1,19 +0,0 @@
-### Analyze — Reviewer Agent
-
-**Spawn Agent**:
-| Parameter | Value |
-|-----------|-------|
-| subagent_type | prizm-dev-team-reviewer |
-| mode | plan |
-| run_in_background | false |
-
-**Prompt**:
-> {{AGENT_PROMPT_REVIEWER_ANALYZE}}
-
-Wait for Reviewer to return.
-- If CRITICAL issues found: fix them yourself — read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` for full project context. Fix ONLY the listed CRITICAL issues in spec.md/plan.md. Then re-run analyze (max 1 round).
-
-**CP-2**: No CRITICAL issues.
-
-
-**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-analyze` to `"completed"`.