prizmkit 1.0.105 → 1.0.108

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.105",
-  "bundledAt": "2026-03-25T15:34:22.423Z",
-  "bundledFrom": "c46942e"
+  "frameworkVersion": "1.0.108",
+  "bundledAt": "2026-03-26T01:27:22.624Z",
+  "bundledFrom": "90a9f59"
 }

package/bundled/adapters/claude/command-adapter.js

@@ -102,8 +102,9 @@ export async function installCommand(corePath, targetRoot) {
   const skillName = path.basename(corePath);
   const hasAssets = existsSync(path.join(corePath, 'assets'));
   const hasScripts = existsSync(path.join(corePath, 'scripts'));
+  const hasRules = existsSync(path.join(corePath, 'rules'));
 
-  if (hasAssets || hasScripts) {
+  if (hasAssets || hasScripts || hasRules) {
     // Use directory structure for commands with resources
     const targetDir = path.join(targetRoot, COMMANDS_DIR, skillName);
     mkdirSync(targetDir, { recursive: true });
@@ -117,7 +118,7 @@ export async function installCommand(corePath, targetRoot) {
     }
 
     // Copy assets and scripts
-    for (const subdir of ['scripts', 'assets']) {
+    for (const subdir of ['scripts', 'assets', 'rules']) {
       const srcSubdir = path.join(corePath, subdir);
       if (existsSync(srcSubdir)) {
         cpSync(srcSubdir, path.join(targetDir, subdir), { recursive: true });

package/bundled/adapters/codebuddy/skill-adapter.js

@@ -58,7 +58,7 @@ export async function installSkill(corePath, targetRoot, options = {}) {
     }
 
     // Copy scripts/ and assets/ if they exist
-    for (const subdir of ['scripts', 'assets']) {
+    for (const subdir of ['scripts', 'assets', 'rules']) {
       const srcSubdir = path.join(corePath, subdir);
       if (existsSync(srcSubdir)) {
         cpSync(srcSubdir, path.join(targetDir, subdir), { recursive: true });

package/bundled/dev-pipeline/templates/bootstrap-tier1.md

@@ -80,7 +80,7 @@ cat .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md 2>/dev/null || echo "NO_PREV
 If failure-log.md exists:
 - Read ROOT_CAUSE and SUGGESTION — adjust your approach accordingly
 - Read DISCOVERED_TRAPS — if any are genuine, inject into .prizm-docs/ during Phase 4 retrospective
-- Do NOT delete failure-log.md until this session succeeds
+- Do NOT delete failure-log.md until this session completes all phases and commits successfully
 
 ```bash
 ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md 2>/dev/null && echo "EXISTS" || echo "MISSING"
@@ -193,6 +193,11 @@ If you encounter an unrecoverable error, context overflow, or are about to exit
 
 2. This file is intentionally lightweight — write it BEFORE context runs out.
 
+**Lifecycle**: failure-log.md is a temporary cross-session artifact. Do NOT commit it to git. After a successful session (all phases complete + commit done), delete it:
+```bash
+rm -f .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md
+```
+
 ## Reminders
 
 - Tier 1: you handle everything directly — no subagents needed

package/bundled/dev-pipeline/templates/bootstrap-tier2.md

@@ -91,7 +91,7 @@ cat .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md 2>/dev/null || echo "NO_PREV
 If failure-log.md exists:
 - Read ROOT_CAUSE and SUGGESTION — adjust your approach accordingly
 - Read DISCOVERED_TRAPS — if any are genuine, inject into .prizm-docs/ during Phase 5 retrospective
-- Do NOT delete failure-log.md until this session succeeds
+- Do NOT delete failure-log.md until this session completes all phases and commits successfully
 
 ```bash
 ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md 2>/dev/null && echo "EXISTS" || echo "MISSING"
@@ -242,6 +242,11 @@ If you encounter an unrecoverable error, context overflow, or are about to exit
 
 2. This file is intentionally lightweight — write it BEFORE context runs out.
 
+**Lifecycle**: failure-log.md is a temporary cross-session artifact. Do NOT commit it to git. After a successful session (all phases complete + commit done), delete it:
+```bash
+rm -f .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md
+```
+
 ## Reminders
 
 - Tier 2: orchestrator builds context+plan, Dev implements, Reviewer reviews+tests — use direct Agent spawn for agents

package/bundled/dev-pipeline/templates/bootstrap-tier3.md

@@ -154,7 +154,7 @@ cat .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md 2>/dev/null || echo "NO_PREV
 If failure-log.md exists:
 - Read ROOT_CAUSE and SUGGESTION — adjust your approach accordingly
 - Read DISCOVERED_TRAPS — if any are genuine, inject into .prizm-docs/ during Phase 6 retrospective
-- Do NOT delete failure-log.md until this session succeeds
+- Do NOT delete failure-log.md until this session completes all phases and commits successfully
 
 Check existing artifacts first:
 ```bash
@@ -422,6 +422,11 @@ If you encounter an unrecoverable error, context overflow, or are about to exit
 
 2. This file is intentionally lightweight — write it BEFORE context runs out.
 
+**Lifecycle**: failure-log.md is a temporary cross-session artifact. Do NOT commit it to git. After a successful session (all phases complete + commit done), delete it:
+```bash
+rm -f .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md
+```
+
 ## Reminders
 
 - Tier 3: full team — Dev (implementation) → Reviewer (review + test) — spawn agents directly via Agent tool

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.105",
+  "version": "1.0.108",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",

package/bundled/skills/prizm-kit/SKILL.md

@@ -71,6 +71,21 @@ PrizmKit produces two complementary knowledge layers:
 .prizmkit/specs/       → Feature "what to do" (workflow: spec → plan → code(implement))
 ```
 
+## Core Skill Reference
+
+| Skill | Purpose | Trigger Phrases |
+|-------|---------|-----------------|
+| `/prizmkit-specify` | Natural language → structured spec.md | "specify", "new feature", "I want to add..." |
+| `/prizmkit-clarify` | Resolve spec ambiguities interactively | "clarify", "refine spec", "resolve ambiguities" |
+| `/prizmkit-plan` | Spec → plan.md with architecture + tasks | "plan", "architect", "break it down", "create tasks" |
+| `/prizmkit-analyze` | Cross-doc consistency check (read-only) | "analyze", "check consistency", "validate spec" |
+| `/prizmkit-implement` | Execute plan.md tasks, write code (TDD) | "implement", "build", "code it", "start coding" |
+| `/prizmkit-code-review` | Diagnose issues + produce Fix Instructions | "review", "check code", "is it ready to commit" |
+| `/prizmkit-retrospective` | Sync .prizm-docs/ with code changes | "retrospective", "retro", "sync docs", "wrap up" |
+| `/prizmkit-committer` | Safe git commit with Conventional Commits | "commit", "submit", "finish", "ship it" |
+| `/prizmkit-init` | Project bootstrap + .prizm-docs/ setup | "init", "initialize", "take over this project" |
+| `/prizmkit-prizm-docs` | Doc management (init/status/rebuild/validate) | "check docs", "rebuild docs", "validate docs" |
+
 **Reading guide**:
 - Need code structure/modules/interfaces/traps/decisions? → `.prizm-docs/`
 

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

@@ -12,7 +12,12 @@ Perform a non-destructive cross-artifact consistency and quality analysis across
 - User says "analyze", "check consistency", "validate spec", "review plan"
 - Before `/prizmkit-implement` as a quality gate
 
-**PRECONDITION:** `spec.md` and `plan.md` exist in `.prizmkit/specs/###-feature-name/`. `plan.md` must include a Tasks section.
+**PRECONDITION:**
+
+| Required Artifact | Directory | Check | If Missing |
+|---|---|---|---|
+| `spec.md` | `.prizmkit/specs/###-feature-name/` | File exists | Run `/prizmkit-specify` |
+| `plan.md` (with Tasks section) | `.prizmkit/specs/###-feature-name/` | File exists + has Tasks section | Run `/prizmkit-plan` |
 
 ## Operating Constraints
 

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

@@ -12,7 +12,11 @@ Interactive requirement clarification that resolves ambiguities in feature speci
 - User says "clarify", "resolve ambiguities", "refine spec"
 - Before `/prizmkit-plan` to ensure spec is unambiguous
 
-**PRECONDITION:** `spec.md` exists in current feature directory (`.prizmkit/specs/###-feature-name/`)
+**PRECONDITION:**
+
+| Required Artifact | Directory | Check | If Missing |
+|---|---|---|---|
+| `spec.md` | `.prizmkit/specs/###-feature-name/` | File exists with `[NEEDS CLARIFICATION]` markers or underspecified areas | Run `/prizmkit-specify` first |
 
 ## Execution Steps
 

package/bundled/skills/prizmkit-code-review/SKILL.md

@@ -7,8 +7,8 @@ description: "Code review with fix strategy formulation. Diagnoses issues across
 
 Perform a comprehensive code review against the feature spec, implementation plan, and project best practices. This skill has two phases:
 
-1. **Diagnostic Review** — read-only analysis across 6 dimensions, producing findings with severity ratings
-2. **Fix Strategy Formulation** — for each finding, analyze root cause, impact, and produce actionable Fix Instructions with verification criteria
+1. **Diagnostic Review** — read-only analysis producing findings with severity ratings
+2. **Fix Strategy Formulation** — for each finding, produce actionable Fix Instructions
 
 The review itself is read-only. Fix Instructions are structured guidance for the developer — the reviewer does not modify code.
 
@@ -17,58 +17,35 @@ The review itself is read-only. Fix Instructions are structured guidance for the
 - User says "review", "check code", "review my implementation"
 - As a quality gate before `/prizmkit-committer`
 
-**PRECONDITION (multi-mode):**
-- **Feature mode**: `spec.md` and `plan.md` (with Tasks section) exist in `.prizmkit/specs/###-feature-name/` with completed tasks
-- **Refactor mode**: `refactor-analysis.md` and `plan.md` (with Tasks section) exist in `.prizmkit/refactor/<refactor-slug>/` with completed tasks. No `spec.md` is needed — review against `refactor-analysis.md` goals and behavior preservation instead.
-- **Bugfix mode**: `fix-plan.md` exists in `.prizmkit/bugfix/<BUG_ID>/` with completed tasks. Review against the bug description and reproduction test.
-- **Auto-detect**: Check which artifact directory was passed by the calling workflow, or scan `.prizmkit/` for the most recently modified feature/refactor/bugfix directory.
+**PRECONDITION:**
+
+| Mode | Required Artifacts | Directory | Check | If Missing |
+|---|---|---|---|---|
+| **Feature** | `spec.md` + `plan.md` (with Tasks) | `.prizmkit/specs/###-feature-name/` | Files exist + tasks completed | Run `/prizmkit-implement` |
+| **Refactor** | `refactor-analysis.md` + `plan.md` (with Tasks) | `.prizmkit/refactor/<refactor-slug>/` | Files exist + tasks completed. Review against behavior preservation, not spec. | Run `/prizmkit-implement` in refactor mode |
+| **Bugfix** | `fix-plan.md` | `.prizmkit/bugfix/<BUG_ID>/` | File exists + tasks completed. Review against bug description + reproduction test. | Run `/prizmkit-implement` in bugfix mode |
+
+**Auto-detect**: Check which artifact directory was passed by the calling workflow, or scan `.prizmkit/` for the most recently modified feature/refactor/bugfix directory.
 
 ## Phase 1: Diagnostic Review
 
-1. **Detect mode and load review baseline**:
-   - If `spec.md` exists → **Feature mode**: read `spec.md` + `plan.md` as baseline. Review dimensions: spec compliance, plan adherence, code quality, security, consistency, test coverage.
-   - If `refactor-analysis.md` exists → **Refactor mode**: read `refactor-analysis.md` + `plan.md` as baseline. Review dimensions shift: replace "spec compliance" with **behavior preservation** (observable behavior unchanged), replace "plan adherence" with **structural improvement** (is the code measurably better?). Also check test integrity and code quality.
-   - If `fix-plan.md` exists → **Bugfix mode**: read `fix-plan.md` as baseline. Review dimensions: bug is actually fixed, no regressions, reproduction test passes, minimal change scope.
+1. **Detect mode and load review baseline + dimension rules**:
+   - If `spec.md` exists → **Feature mode**: read `spec.md` + `plan.md` as baseline. Load `${SKILL_DIR}/rules/dimensions-feature.md` for review dimensions.
+   - If `refactor-analysis.md` exists → **Refactor mode**: read `refactor-analysis.md` + `plan.md` as baseline. Load `${SKILL_DIR}/rules/dimensions-refactor.md` for review dimensions.
+   - If `fix-plan.md` exists → **Bugfix mode**: read `fix-plan.md` as baseline. Load `${SKILL_DIR}/rules/dimensions-bugfix.md` for review dimensions.
    - If none found → prompt user: "No review baseline found. Which workflow are you in? (feature/refactor/bugfix)"
 2. Read **architecture index**: `.prizm-docs/root.prizm` RULES and PATTERNS for project conventions
 3. Read **past decisions**: check DECISIONS sections in relevant `.prizm-docs/` L1/L2 files — helps verify implementation respects established conventions
 4. Read '## Implementation Log' section of context-snapshot.md in the feature directory (if exists) — understand Dev's implementation decisions, trade-offs, and notable discoveries. This context helps distinguish intentional design choices from accidental patterns during review.
 5. Scan all code files referenced in completed tasks
-6. Review across 6 dimensions:
-   - **Spec compliance**: Does code implement all acceptance criteria? Missing criteria are the #1 source of "it works but it's wrong" bugs
-   - **Plan adherence**: Does implementation follow architectural decisions in plan.md? Deviations may be improvements or may break assumptions other components depend on
-   - **Code quality**: Naming, structure, complexity, DRY. Focus on maintainability — will someone understand this code in 6 months?
-   - **Security**: Injection (SQL, XSS, command), auth/authz gaps, sensitive data exposure, insecure defaults. Security issues are always HIGH+ because they're the hardest to catch later
-   - **Consistency**: Follows project patterns from `.prizm-docs/` PATTERNS section. Inconsistent patterns increase cognitive load for every future reader
-   - **Test coverage**: Are critical paths tested? Focus on paths that handle user input, money, or state transitions
+6. Review across all dimensions defined in the loaded rules file
 7. Generate findings with severity: `CRITICAL` > `HIGH` > `MEDIUM` > `LOW`
 
 ## Phase 2: Fix Strategy Formulation
 
-For each finding from Phase 1 (CRITICAL and HIGH are mandatory; MEDIUM/LOW when actionable):
-
-1. **Root Cause Analysis** — identify WHY the problem exists, not just WHAT is wrong. Trace the issue to its origin (wrong assumption? missing context? copy-paste error?)
-2. **Impact Analysis** — search the codebase for all callers/dependents of the affected code. List concrete file:line locations that will be affected by the fix
-3. **Fix Strategy** — concrete step-by-step modification plan:
-   - What to change, where, and in what order
-   - Which project conventions to follow (reference `.prizm-docs/` RULES)
-   - Dependencies between fixes (FIX-1 must be done before FIX-3)
-4. **Code Guidance** — show before/after code snippets for the key change. Keep minimal — enough to unambiguate the approach, not a full implementation
-5. **Verification Criteria** — how to confirm the fix works:
-   - Specific commands to run (grep patterns, test commands)
-   - What the output should look like
-   - Edge cases to verify
-
-### Finding Grouping
-
-Group related findings that should be fixed together. If FIX-1 and FIX-3 share the same root cause or affect the same code path, mark them as a group with a shared fix strategy. This prevents Dev from fixing symptoms individually only to have the underlying cause persist.
+Load `${SKILL_DIR}/rules/fix-strategy.md` for the complete fix formulation process, finding format, grouping rules, and priority ordering.
 
-### Fix Priority Ordering
-
-Order Fix Instructions by:
-1. **Dependencies first** — if FIX-2 depends on FIX-1, FIX-1 comes first
-2. **CRITICAL before HIGH** — severity determines priority within independent fixes
-3. **Grouped fixes together** — related findings are adjacent
+For each finding from Phase 1 (CRITICAL and HIGH are mandatory; MEDIUM/LOW when actionable), follow the fix strategy rules to produce structured Fix Instructions.
 
 ## Severity & Verdict
 
@@ -83,65 +60,6 @@ Cap findings at 30 to keep the review actionable. If there are more, summarize t
 
 If you're unsure whether something is a bug or intentional design, flag it as MEDIUM with a note asking the developer to confirm. Don't silently skip uncertain findings.
 
-## Finding Format
-
-```
-#### FIX-1: [CRITICAL] SQL Injection in User Search
-- Location: src/services/userService.ts:47
-- Dimension: security
-- Root Cause: User input `searchTerm` is interpolated directly into SQL query
-  string. The `buildQuery()` helper (line 12) accepts raw strings without
-  sanitization, and all callers trust it blindly.
-- Impact: All callers of `searchUsers()` are affected — found 3 call sites:
-  routes/api.ts:89, routes/admin.ts:34, services/reportService.ts:112
-- Fix Strategy:
-  1. Replace string interpolation with parameterized query at line 47
-  2. Update `buildQuery()` helper to accept params array
-  3. Update all 3 call sites to pass params
-  Note: project uses `pg` client directly (not ORM), follow the pattern
-  established in `orderService.ts:23` per .prizm-docs/ RULES
-- Code Guidance:
-  ```ts
-  // line 47: change from
-  const result = await db.query(`SELECT * FROM users WHERE name LIKE '%${searchTerm}%'`);
-  // to
-  const result = await db.query('SELECT * FROM users WHERE name LIKE $1', [`%${searchTerm}%`]);
-  ```
-- Verification:
-  - `grep -rn "\${.*}" src/ --include="*.ts"` returns no SQL-context matches
-  - Test `user.search.test.ts` covers parameterized path
-  - Existing test suite passes
-- Related: FIX-3 (same pattern in reportService)
-- Depends On: (none)
-- Blocks: FIX-3
-
-#### FIX-2: [HIGH] Missing Acceptance Criterion AC-3
-- Location: src/routes/upload.ts
-- Dimension: spec-compliance
-- Root Cause: spec.md §AC-3 requires "display progress bar during upload" but
-  the upload handler uses a simple fetch() without progress tracking.
-  Implementation Log does not mention this criterion — likely overlooked.
-- Impact: Upload route only — no cross-module impact
-- Fix Strategy:
-  1. Replace fetch() with XMLHttpRequest or fetch + ReadableStream
-  2. Add progress callback that emits percentage events
-  3. Wire progress events to the UI component (if frontend exists)
-- Code Guidance:
-  ```ts
-  // Replace simple fetch with progress-aware upload
-  const xhr = new XMLHttpRequest();
-  xhr.upload.onprogress = (e) => {
-    if (e.lengthComputable) onProgress(Math.round(e.loaded / e.total * 100));
-  };
-  ```
-- Verification:
-  - Upload a file > 1MB and verify progress callback fires
-  - Test covers progress event emission
-- Related: (none)
-- Depends On: (none)
-- Blocks: (none)
-```
-
 ## Review Notes Format
 
 When writing to context-snapshot.md, use this structured format:
@@ -156,7 +74,7 @@ When writing to context-snapshot.md, use this structured format:
 ### Fix Instructions (ordered by priority)
 
 #### FIX-1: [SEVERITY] Title
-(full finding format as above)
+(finding format per ${SKILL_DIR}/rules/fix-strategy.md)
 
 #### FIX-2: [SEVERITY] Title
 ...
@@ -177,7 +95,7 @@ In unattended pipeline mode, the review→fix→review cycle can loop indefinite
 - Track a `review_iteration` counter starting at 1. Each review-fix-review cycle increments the counter.
 - **max_iterations = 5**: If `review_iteration >= 5`, you MUST proceed to `/prizmkit-retrospective` regardless of remaining findings. Log remaining issues as known technical debt: "Loop protection triggered — proceeding to retrospective with N unresolved findings (iterations: 5/5)."
 - Unresolved findings should be recorded in the review report so they can be tracked as follow-up work.
-- On re-review (iteration > 1): only check the specific Verification Criteria from previous Fix Instructions + scan for regressions. Do NOT re-run the full 6-dimension review unless new code was added beyond the fix scope.
+- On re-review (iteration > 1): only check the specific Verification Criteria from previous Fix Instructions + scan for regressions. Do NOT re-run the full dimension review unless new code was added beyond the fix scope.
 
 ## Output
 

package/bundled/skills/prizmkit-code-review/rules/dimensions-bugfix.md

@@ -0,0 +1,25 @@
+# Review Dimensions — Bugfix Mode
+
+Review code against `fix-plan.md` and the bug description. Minimal scope — the fix should change as little as possible.
+
+## Bugfix-Specific Dimensions
+
+### Bug Actually Fixed
+- The reproduction steps from fix-plan.md no longer trigger the bug
+- The root cause identified in fix-plan.md is addressed (not just symptoms)
+- A regression test exists that would catch this bug if reintroduced
+
+### No Regressions
+- All existing tests still pass
+- The fix does not change behavior for non-buggy inputs
+- Related code paths are not inadvertently affected
+
+### Minimal Change Scope
+- Only files directly related to the bug are modified
+- No "while I'm here" refactoring mixed with the fix
+- If scope creep is detected, flag it — those changes belong in a separate commit
+
+### Reproduction Test
+- A test exists that reproduces the exact bug scenario
+- The test would fail on the pre-fix code and pass on the post-fix code
+- The test covers the specific input/state that triggered the bug

package/bundled/skills/prizmkit-code-review/rules/dimensions-feature.md

@@ -0,0 +1,43 @@
+# Review Dimensions — Feature Mode
+
+Review code against `spec.md` and `plan.md` across 6 dimensions:
+
+## 1. Spec Compliance
+Does code implement all acceptance criteria? Missing criteria are the #1 source of "it works but it's wrong" bugs.
+- Check every acceptance criterion in spec.md has a corresponding implementation
+- Verify edge cases mentioned in spec are handled
+- Confirm scope boundaries are respected (no over-implementation, no under-implementation)
+
+## 2. Plan Adherence
+Does implementation follow architectural decisions in plan.md? Deviations may be improvements or may break assumptions other components depend on.
+- Check component structure matches plan's architecture approach
+- Verify data model matches plan's schema design
+- Confirm API contracts (endpoints, request/response) match plan
+
+## 3. Code Quality
+Naming, structure, complexity, DRY. Focus on maintainability — will someone understand this code in 6 months?
+- Function/variable names are descriptive and consistent with project conventions
+- No unnecessary complexity (cyclomatic complexity, deep nesting)
+- No copy-paste duplication that should be abstracted
+- Error messages are informative for debugging
+
+## 4. Security
+Injection (SQL, XSS, command), auth/authz gaps, sensitive data exposure, insecure defaults. Security issues are always HIGH+ because they're the hardest to catch later.
+- User input is validated and sanitized before use in queries, HTML, or commands
+- Authentication and authorization checks are present on protected routes
+- Sensitive data (passwords, tokens, PII) is not logged or exposed in responses
+- Cryptographic operations use established libraries, not custom implementations
+
+## 5. Consistency
+Follows project patterns from `.prizm-docs/` PATTERNS section. Inconsistent patterns increase cognitive load for every future reader.
+- Code style matches existing codebase conventions
+- Error handling follows established patterns
+- File organization follows project structure conventions
+- Naming conventions align with `.prizm-docs/` RULES
+
+## 6. Test Coverage
+Are critical paths tested? Focus on paths that handle user input, money, or state transitions.
+- Happy path tests exist for each user story
+- Error/edge case tests for critical paths
+- Tests are deterministic (no flaky timing dependencies)
+- Test names clearly describe what they verify

package/bundled/skills/prizmkit-code-review/rules/dimensions-refactor.md

@@ -0,0 +1,25 @@
+# Review Dimensions — Refactor Mode
+
+Review code against `refactor-analysis.md` goals. Standard dimensions (code quality, security, consistency, test coverage) still apply — load `${SKILL_DIR}/rules/dimensions-feature.md` §3–§6 for those.
+
+## Refactor-Specific Dimensions
+
+### Behavior Preservation (replaces Spec Compliance)
+Observable behavior must remain unchanged. This is the #1 refactor risk — "improving" code that subtly changes behavior.
+- All existing tests still pass without modification (test changes during refactor are a red flag)
+- Public API signatures are unchanged (parameter types, return types, error types)
+- Side effects (logging, metrics, events) are preserved unless explicitly scoped for removal
+- Edge case handling is preserved — refactors often silently drop edge case branches
+
+### Structural Improvement (replaces Plan Adherence)
+Is the code measurably better against the refactor goals?
+- Complexity metrics improved (fewer nested conditions, shorter functions)
+- Coupling reduced (fewer cross-module imports, clearer boundaries)
+- Duplication reduced (DRY violations eliminated per refactor-analysis.md scope)
+- Readability improved (naming, organization, documentation)
+
+### Test Integrity
+Refactors must not weaken the test suite.
+- No tests were deleted or skipped
+- Test coverage percentage is equal or higher
+- If tests were rewritten, they cover the same behavioral scenarios

package/bundled/skills/prizmkit-code-review/rules/fix-strategy.md

@@ -0,0 +1,61 @@
+# Fix Strategy Formulation
+
+For each finding from the Diagnostic Review (CRITICAL and HIGH mandatory; MEDIUM/LOW when actionable):
+
+## Per-Finding Analysis
+
+### 1. Root Cause Analysis
+Identify WHY the problem exists, not just WHAT is wrong. Trace the issue to its origin (wrong assumption? missing context? copy-paste error?).
+
+### 2. Impact Analysis
+Search the codebase for all callers/dependents of the affected code. List concrete `file:line` locations that will be affected by the fix.
+
+### 3. Fix Strategy
+Concrete step-by-step modification plan:
+- What to change, where, and in what order
+- Which project conventions to follow (reference `.prizm-docs/` RULES)
+- Dependencies between fixes (FIX-1 must be done before FIX-3)
+
+### 4. Code Guidance
+Show before/after code snippets for the key change. Keep minimal — enough to unambiguate the approach, not a full implementation.
+
+### 5. Verification Criteria
+How to confirm the fix works:
+- Specific commands to run (grep patterns, test commands)
+- What the output should look like
+- Edge cases to verify
+
+## Finding Grouping
+
+Group related findings that should be fixed together. If FIX-1 and FIX-3 share the same root cause or affect the same code path, mark them as a group with a shared fix strategy. This prevents Dev from fixing symptoms individually only to have the underlying cause persist.
+
+## Fix Priority Ordering
+
+Order Fix Instructions by:
+1. **Dependencies first** — if FIX-2 depends on FIX-1, FIX-1 comes first
+2. **CRITICAL before HIGH** — severity determines priority within independent fixes
+3. **Grouped fixes together** — related findings are adjacent
+
+## Finding Format
+
+```
+#### FIX-N: [SEVERITY] Title
+- Location: file:line
+- Dimension: category
+- Root Cause: explanation
+- Impact: affected callers/dependents with file:line locations
+- Fix Strategy:
+  1. step one
+  2. step two
+  Note: reference project conventions from .prizm-docs/ RULES
+- Code Guidance:
+  ```language
+  // before → after
+  ```
+- Verification:
+  - command to run
+  - expected output
+- Related: FIX-X (if grouped)
+- Depends On: FIX-Y (if dependency)
+- Blocks: FIX-Z (if blocking)
+```

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

@@ -14,6 +14,14 @@ Pure git commit workflow. Analyzes changes, generates a Conventional Commits mes
 - After `/prizmkit-retrospective` has finished architecture sync
 - The UserPromptSubmit hook will remind to use this skill when commit intent is detected
 
+**PRECONDITION:**
+
+| Required State | Check | If Missing |
+|---|---|---|
+| Uncommitted changes exist | `git status` shows modified/added/untracked files | Inform user "nothing to commit" and stop |
+| `.prizm-docs/` synced (feature/refactor) | `/prizmkit-retrospective` has run | Run `/prizmkit-retrospective` first |
+| Code review passed (pipeline mode) | `context-snapshot.md` has Review Notes with PASS/PASS_WITH_WARNINGS | Run `/prizmkit-code-review` first |
+
 ### Workflow
 
 Follow these steps STRICTLY in order:
@@ -32,9 +40,14 @@ By consulting the primary agent or based on the existing context, condense this
 If CHANGELOG.md exists in the project root, append an entry following Keep a Changelog format under the `[Unreleased]` section. Match the existing style in the file.
 
 #### Step 4: Git Commit
-```bash
-git add .
-```
+
+Stage changes using a safe strategy — **never use `git add .` or `git add -A`** as they may stage sensitive files (.env, credentials, secrets) or unintended changes:
+
+1. Review untracked files with `git status`. Warn the user if any files match sensitive patterns (`.env*`, `*credential*`, `*secret*`, `*.pem`, `*.key`).
+2. Stage tracked modified files: `git add -u`
+3. For new files: stage explicitly by name after confirming they should be included.
+4. Verify staged content with `git diff --cached --stat` before committing.
+
 ```bash
 git commit -m "<type>(<scope>): <description>"
 ```

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

@@ -12,11 +12,15 @@ Execute implementation by following the task breakdown in plan.md. Respects task
 - User says "implement", "build", "code it", "start coding", "develop"
 - For fast-path: user describes a simple change directly (fast-path skips specify, but still requires a simplified plan.md with Tasks section)
 
-**PRECONDITION (multi-mode):**
-- **Feature mode** (default): `plan.md` exists in `.prizmkit/specs/###-feature-name/` with a Tasks section containing unchecked tasks
-- **Refactor mode**: `plan.md` exists in `.prizmkit/refactor/<refactor-slug>/` with a Tasks section containing unchecked tasks
-- **Bugfix mode**: `plan.md` exists in `.prizmkit/bugfix/<BUG_ID>/` with a Tasks section containing unchecked tasks
-- **Auto-detect**: If the calling workflow passes an explicit artifact directory, use that. Otherwise scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks.
+**PRECONDITION:**
+
+| Mode | Required Artifact | Directory | Check | If Missing |
+|---|---|---|---|---|
+| **Feature** (default) | `plan.md` with Tasks section | `.prizmkit/specs/###-feature-name/` | File exists + unchecked tasks | Run `/prizmkit-plan` |
+| **Refactor** | `plan.md` with Tasks section | `.prizmkit/refactor/<refactor-slug>/` | File exists + unchecked tasks | Run `/prizmkit-plan` in refactor mode |
+| **Bugfix** | `plan.md` with Tasks section | `.prizmkit/bugfix/<BUG_ID>/` | File exists + unchecked tasks | Run `/prizmkit-plan` in bugfix mode |
+
+**Auto-detect**: If the calling workflow passes an explicit artifact directory, use that. Otherwise scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks.
 
 ## Execution Steps
 

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

@@ -18,11 +18,15 @@ Generate a comprehensive technical implementation plan from a feature specificat
 - Simple bug fix or config change → use fast path (`/prizmkit-plan` with simplified output → `/prizmkit-implement` → `/prizmkit-committer`)
 - User just wants to explore/research → answer directly, no plan artifact needed
 
-**PRECONDITION (multi-mode):**
-- **Feature mode** (default): `spec.md` exists in `.prizmkit/specs/###-feature-name/`, `.prizm-docs/root.prizm` exists. If spec.md is missing, prompt the user: "No spec found — want me to run /prizmkit-specify first?"
-- **Refactor mode**: `refactor-analysis.md` exists in `.prizmkit/refactor/<refactor-slug>/`. Use refactor-analysis.md as the input document in place of spec.md. Output plan.md to the same `.prizmkit/refactor/<refactor-slug>/` directory, NOT to `.prizmkit/specs/`.
-- **Bugfix mode**: Bug description provided by caller or `fix-plan.md` exists in `.prizmkit/bugfix/<BUG_ID>/`. Output plan.md to the same directory.
-- **Auto-detect**: If the calling workflow passes an explicit artifact directory, use that. Otherwise check which input document type exists.
+**PRECONDITION:**
+
+| Mode | Required Artifact | Directory | Check | If Missing |
+|---|---|---|---|---|
+| **Feature** (default) | `spec.md` + `.prizm-docs/root.prizm` | `.prizmkit/specs/###-feature-name/` | File exists | Prompt: "No spec found — run `/prizmkit-specify` first?" |
+| **Refactor** | `refactor-analysis.md` | `.prizmkit/refactor/<refactor-slug>/` | File exists | Run upstream refactor workflow |
+| **Bugfix** | `fix-plan.md` or bug description from caller | `.prizmkit/bugfix/<BUG_ID>/` | File exists or caller-provided | Run `/bug-fix-workflow` |
+
+**Auto-detect**: If the calling workflow passes an explicit artifact directory, use that. Otherwise check which input document type exists.
 
 ## Execution Steps
 

package/bundled/skills/prizmkit-prizm-docs/assets/PRIZM-SPEC.md

@@ -250,7 +250,7 @@ CONSTRAINTS:
 - TRAPS section is CRITICAL for preventing AI from making known mistakes
 - TRAPS entries MUST have severity prefix ([CRITICAL], [HIGH], or [LOW]). [REVIEW] may precede severity as a temporary staleness marker.
 - TRAPS optional fields: append `| REF: <7-char-hash>` for traceability, `| STALE_IF: <glob>` for auto-expiry detection
-- TRAPS severity guide: CRITICAL = data loss/security/financial/crash, HIGH = functional failure/silent error, LOW = naming/minor quality
+- TRAPS severity: CRITICAL = data loss/security/financial/crash, HIGH = functional failure/silent error, LOW = naming/minor quality (see TRAPS_FORMAT_REFERENCE in Section 3.2)
 - REJECTED entries prevent AI from re-proposing failed approaches
 - FILES lists all files, not just key ones
 - RULES may only SUPPLEMENT root.prizm RULES with module-specific exceptions, never contradict them

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

@@ -78,8 +78,8 @@ 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):
 
 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` or `git status`) → delete the TRAP entry, append CHANGELOG: `remove: archived stale TRAP - <summary>`
-2. If a TRAP has `REF:` and the referenced code has been substantially rewritten (>80% of the original diff is gone, checked via `git log --follow`) → prepend `[REVIEW]` to the severity, signaling it needs manual verification
+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.
@@ -117,10 +117,10 @@ Extract TRAPS, RULES, and DECISIONS from development work and inject into `.priz
 - Full format: `- [SEVERITY] <description> | FIX: <approach> | REF: <hash> | STALE_IF: <glob>`
 - Source: actual bugs hit, surprising behavior discovered in code, non-obvious coupling
 
-**TRAPS severity classification guide**:
-- `[CRITICAL]`: data loss, security vulnerability, financial error, system crash
+**TRAPS severity classification**:
+- `[CRITICAL]`: data loss, security, financial error, system crash
 - `[HIGH]`: functional failure, silent error, interface incompatibility
-- `[LOW]`: misleading naming, non-intuitive API usage, minor performance issue
+- `[LOW]`: misleading naming, non-intuitive API, minor performance issue
 
 When writing TRAPS:
 - Severity prefix is MANDATORY (e.g., `[CRITICAL]`, `[HIGH]`, `[LOW]`)

package/package.json

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