prizmkit 1.0.104 → 1.0.106

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.104",
-  "bundledAt": "2026-03-25T14:43:36.061Z",
-  "bundledFrom": "a253848"
+  "frameworkVersion": "1.0.106",
+  "bundledAt": "2026-03-25T15:56:50.507Z",
+  "bundledFrom": "d91f86f"
 }

package/bundled/dev-pipeline/run.sh

@@ -288,6 +288,18 @@ sys.exit(1)
         fi
     fi
 
+    # Check if session produced a failure-log for future retries
+    if [[ "$session_status" != "success" && -n "$feature_slug" ]]; then
+        local project_root_for_failure
+        project_root_for_failure="$(cd "$SCRIPT_DIR/.." && pwd)"
+        local failure_log="$project_root_for_failure/.prizmkit/specs/${feature_slug}/failure-log.md"
+        if [[ -f "$failure_log" ]]; then
+            log_info "FAILURE_LOG: Session wrote failure-log.md — will be available to next retry"
+        else
+            log_info "FAILURE_LOG: No failure-log.md written by session"
+        fi
+    fi
+
     # Update feature status
     local update_output
     update_output=$(python3 "$SCRIPTS_DIR/update-feature-status.py" \

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

@@ -73,6 +73,15 @@ Check `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — if it exists, s
 
 ### Phase 1: Build Context Snapshot
 
+**Check for previous failure log:**
+```bash
+cat .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md 2>/dev/null || echo "NO_PREVIOUS_FAILURE"
+```
+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 completes all phases and commits successfully
+
 ```bash
 ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md 2>/dev/null && echo "EXISTS" || echo "MISSING"
 ```
@@ -167,6 +176,28 @@ git commit -m "chore({{FEATURE_ID}}): include session artifacts"
 | Context Snapshot | `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` |
 | Project Root | {{PROJECT_ROOT}} |
 
+## Failure Capture Protocol
+
+If you encounter an unrecoverable error, context overflow, or are about to exit without completing all phases:
+
+1. Write `.prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md` BEFORE exiting:
+   ```
+   FAILURE_TYPE: timeout | test_failure | review_rejected | context_overflow | unknown
+   PHASE: <which phase failed>
+   ROOT_CAUSE: <1-2 sentence explanation>
+   ATTEMPTED: <approaches already tried>
+   SUGGESTION: <what the next session should try differently>
+   DISCOVERED_TRAPS:
+   - [CRITICAL|HIGH|LOW] <gotcha discovered during this failed session> | FIX: <approach>
+   ```
+
+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

@@ -84,6 +84,15 @@ Check `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — if exists, skip
 
 ### Phase 1: Build Context Snapshot (you, the orchestrator)
 
+**Check for previous failure log:**
+```bash
+cat .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md 2>/dev/null || echo "NO_PREVIOUS_FAILURE"
+```
+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 completes all phases and commits successfully
+
 ```bash
 ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md 2>/dev/null && echo "EXISTS" || echo "MISSING"
 ```
@@ -216,6 +225,28 @@ git commit -m "chore({{FEATURE_ID}}): include session artifacts"
 | Reviewer Agent Def | {{REVIEWER_SUBAGENT_PATH}} |
 | Project Root | {{PROJECT_ROOT}} |
 
+## Failure Capture Protocol
+
+If you encounter an unrecoverable error, context overflow, or are about to exit without completing all phases:
+
+1. Write `.prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md` BEFORE exiting:
+   ```
+   FAILURE_TYPE: timeout | test_failure | review_rejected | context_overflow | unknown
+   PHASE: <which phase failed>
+   ROOT_CAUSE: <1-2 sentence explanation>
+   ATTEMPTED: <approaches already tried>
+   SUGGESTION: <what the next session should try differently>
+   DISCOVERED_TRAPS:
+   - [CRITICAL|HIGH|LOW] <gotcha discovered during this failed session> | FIX: <approach>
+   ```
+
+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

@@ -147,6 +147,15 @@ After team setup: check `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`
 
 ### Phase 1-2: Specify + Plan — Orchestrator (you)
 
+**Check for previous failure log:**
+```bash
+cat .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md 2>/dev/null || echo "NO_PREVIOUS_FAILURE"
+```
+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 completes all phases and commits successfully
+
 Check existing artifacts first:
 ```bash
 ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
@@ -396,6 +405,28 @@ git commit -m "chore({{FEATURE_ID}}): include session artifacts"
 | Project Root | {{PROJECT_ROOT}} |
 | Feature List Path | {{FEATURE_LIST_PATH}} |
 
+## Failure Capture Protocol
+
+If you encounter an unrecoverable error, context overflow, or are about to exit without completing all phases:
+
+1. Write `.prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md` BEFORE exiting:
+   ```
+   FAILURE_TYPE: timeout | test_failure | review_rejected | context_overflow | unknown
+   PHASE: <which phase failed>
+   ROOT_CAUSE: <1-2 sentence explanation>
+   ATTEMPTED: <approaches already tried>
+   SUGGESTION: <what the next session should try differently>
+   DISCOVERED_TRAPS:
+   - [CRITICAL|HIGH|LOW] <gotcha discovered during this failed session> | FIX: <approach>
+   ```
+
+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.104",
+  "version": "1.0.106",
   "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/prizmkit-prizm-docs/SKILL.md

@@ -121,7 +121,7 @@ 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.
+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 <= 3KB, 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. TIMESTAMP CHECK: Verify all docs have UPDATED field. Flag docs with UPDATED older than 30 days as potentially stale.

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

@@ -1,4 +1,4 @@
-PRIZM_SPEC_VERSION: 2
+PRIZM_SPEC_VERSION: 3
 PURPOSE: AI-only documentation framework for vibe coding projects
 AUDIENCE: AI agents (not humans)
 FORMAT: KEY: value pairs, ALL CAPS section headers, arrow pointers
@@ -180,7 +180,7 @@ TEMPLATE:
   - PREFER: <module-specific preference>
 
   TRAPS:
-  - <what looks safe but is dangerous> | FIX: <correct approach>
+  - [CRITICAL|HIGH|LOW] <what looks safe but is dangerous> | FIX: <correct approach>
 
   DECISIONS:
   - <what was decided> — <rationale>
@@ -195,6 +195,16 @@ CONSTRAINTS:
 - SUBDIRS entries must have arrow pointer (->) if L2 doc exists
 - KEY_FILES lists only the most important files (max 10-15)
 - RULES may only SUPPLEMENT root.prizm RULES with module-specific exceptions, never contradict them
+- 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_FORMAT_REFERENCE (spec-only — do NOT include this block in generated .prizm files):
+- Severity levels: CRITICAL = data loss/security/financial/crash, HIGH = functional failure/silent error, LOW = naming/minor quality
+- Temporary prefix: [REVIEW] may precede severity (e.g., `[REVIEW][HIGH]`) — signals the TRAP needs re-validation. Consumed by the next retrospective: verify and either remove [REVIEW] or delete the TRAP.
+- REF: first 7 chars of the commit where the trap was discovered (optional, for traceability)
+- STALE_IF: glob pattern — when matched files are deleted or heavily rewritten, this trap needs re-validation (optional)
+- Minimal valid format: `- [SEVERITY] <description> | FIX: <approach>`
+- Full format: `- [SEVERITY] <description> | FIX: <approach> | REF: <hash> | STALE_IF: <glob>`
 
 ## 3.3 L2: detail.prizm
 
@@ -220,8 +230,8 @@ TEMPLATE:
   - REJECTED: <approach that was tried/considered and abandoned + why>
 
   TRAPS:
-  - <gotcha: something that looks correct but is wrong or dangerous>
-  - <non-obvious coupling, race condition, or side effect>
+  - [CRITICAL|HIGH|LOW] <gotcha: something that looks correct but is wrong or dangerous> | FIX: <correct approach>
+  - [CRITICAL|HIGH|LOW] <non-obvious coupling, race condition, or side effect> | FIX: <approach>
 
   CHANGELOG:
   - YYYY-MM-DD | <verb>: <description of recent change to this module>
@@ -238,6 +248,9 @@ CONSTRAINTS:
 - DOMAIN-SPECIFIC SECTIONS are flexible, not prescribed
 - DECISIONS is append-only (never delete, archive if >20 entries)
 - 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: 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
@@ -440,6 +453,7 @@ NEVER: Session-specific context or conversation history (docs are session-indepe
 NEVER: Flowcharts, diagrams, mermaid blocks, or ASCII art (wastes tokens, AI cannot parse visually)
 NEVER: Markdown headers (## / ###) inside .prizm files (use ALL CAPS KEY: format instead)
 NEVER: Rewrite entire .prizm files on update (modify only affected sections)
+NEVER: TRAPS entries without severity prefix ([CRITICAL], [HIGH], or [LOW])
 
 ---
 
@@ -821,6 +835,16 @@ V2 (2026-03-02): Enhanced specification
 - Enhanced Section 9.1 with ON_DEEP_READ trigger alongside ON_MODIFY
 - Updated PRIZM_SPEC_VERSION to 2
 
+V3 (2026-03-25): Knowledge quality and resilience
+- TRAPS entries now MUST have severity prefix: [CRITICAL], [HIGH], or [LOW]
+- TRAPS optional fields: REF (commit hash for traceability), STALE_IF (glob for auto-expiry detection)
+- Added TRAPS staleness check in retrospective (step 1g): auto-archive stale TRAPS when count > 10
+- Added Failure Capture Protocol: bootstrap templates write failure-log.md on session failure for cross-session learning
+- Added retrospective data source: failure-log.md DISCOVERED_TRAPS are prioritized for .prizm-docs/ injection
+- Added TRAPS_FORMAT_REFERENCE as spec-only block (must NOT appear in generated .prizm files)
+- Added V2→V3 migration: auto-tag legacy TRAPS with [LOW] default severity
+- Updated PRIZM_SPEC_VERSION to 3
+
 ---
 
 # SECTION 15: CONFLICT RESOLUTION
@@ -884,8 +908,8 @@ BEST_PRACTICE: Coordinate on MODULE_INDEX changes (adding/removing modules) to a
 
 ## 16.1 Migration Principles
 
-BACKWARD_COMPATIBLE: V2 can read V1 docs without modification
-FORWARD_COMPATIBLE: V1 tools will ignore V2-only fields they do not recognize
+BACKWARD_COMPATIBLE: V3 can parse V2 docs without errors, but Validate will flag TRAPS entries missing severity prefixes and auto-migration (Section 16.3) will add [LOW] defaults
+FORWARD_COMPATIBLE: V2 tools will ignore V3-only fields they do not recognize
 MIGRATION_TRIGGER: AI detects PRIZM_VERSION in root.prizm and applies migration if needed
 
 ## 16.2 V1 to V2 Migration
@@ -911,7 +935,32 @@ ALGORITHM: prizm_migrate_v1_to_v2
 4. UPDATE_CHANGELOG:
    APPEND: - YYYY-MM-DD | root | update: migrated from PRIZM_VERSION 1 to 2
 
-## 16.3 Future Version Migration Pattern
+## 16.3 V2 to V3 Migration
+
+TRIGGER: Automatic on first prizmkit-prizm-docs Update or Validate operation after spec upgrade
+
+ALGORITHM: prizm_migrate_v2_to_v3
+
+1. UPDATE_VERSION:
+   Change: PRIZM_VERSION: 2 -> PRIZM_VERSION: 3
+   In: root.prizm
+
+2. MIGRATE_TRAPS_FORMAT:
+   SCAN: All L1 and L2 .prizm files for TRAPS entries
+   FOR EACH TRAPS entry without severity prefix ([CRITICAL], [HIGH], or [LOW]):
+     PREPEND: [LOW] as conservative default severity
+     EXAMPLE: `- foo is dangerous | FIX: use bar` becomes `- [LOW] foo is dangerous | FIX: bar`
+   RATIONALE: [LOW] is the safest default — it preserves the trap without over-alarming.
+   AI or user can manually upgrade severity to [HIGH] or [CRITICAL] during next retrospective.
+
+3. VALIDATE:
+   Run full Validate operation
+   REPORT: Migration results — number of TRAPS entries migrated, files updated
+
+4. UPDATE_CHANGELOG:
+   APPEND: - YYYY-MM-DD | root | update: migrated from PRIZM_VERSION 2 to 3 (TRAPS severity prefixes added)
+
+## 16.4 Future Version Migration Pattern
 
 FOR any future version N to N+1:
 

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

@@ -63,6 +63,9 @@ git diff --name-status
 - **L1**: Update FILES count, KEY_FILES (if major files added/removed), INTERFACES (if public API changed), UPDATED timestamp
 - **L0 root.prizm**: Update MODULE_INDEX file counts only if counts changed. Update UPDATED only if structural change (module added/removed).
 
+**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 with 3+ source files matches no existing module: create L1 doc immediately, add to MODULE_INDEX, defer L2.
 
 **1f.** Enforce size limits:
@@ -72,6 +75,15 @@ git diff --name-status
 
 **SKIP structural sync if**: only internal implementation changed (no interface/dependency impact), only comments/whitespace, only test files, only .prizm files, bug fixes with no interface change.
 
+**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`) → 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.
+
 ---
 
 ## Job 2: Architecture Knowledge Injection → `.prizm-docs/`
@@ -95,14 +107,29 @@ Extract TRAPS, RULES, and DECISIONS from development work and inject into `.priz
 - `.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/`
 - The relevant `.prizm-docs/` L1/L2 docs for affected modules
 
 **2b.** Extract knowledge from what was **observed in code**, not invented:
 
 **TRAPS** (highest priority) — things that look safe but break:
-- Format: `- <what looks safe but is dangerous> | FIX: <correct approach>`
+- Minimal format: `- [SEVERITY] <description> | FIX: <approach>`
+- 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**:
+- `[CRITICAL]`: data loss, security, financial error, system crash
+- `[HIGH]`: functional failure, silent error, interface incompatibility
+- `[LOW]`: misleading naming, non-intuitive API, minor performance issue
+
+When writing TRAPS:
+- Severity prefix is MANDATORY (e.g., `[CRITICAL]`, `[HIGH]`, `[LOW]`)
+- OPTIONAL: append `| REF: <7-char-hash>` when you know the relevant commit (for traceability)
+- OPTIONAL: append `| STALE_IF: <glob>` when the TRAP is tightly coupled to specific files (for auto-expiry detection)
+
+**Consuming [REVIEW] markers** (from staleness check 1g):
+- If you encounter a TRAP prefixed with `[REVIEW]` (e.g., `[REVIEW][HIGH] ...`), verify whether the trap is still valid by checking the current code. If still valid: remove the `[REVIEW]` prefix, keeping the severity. If no longer relevant: delete the TRAP entry and append CHANGELOG.
+
 **RULES** — conventions established or constraints discovered:
 - Format: `- MUST/NEVER/PREFER: <rule>`
 - Source: patterns that proved necessary during implementation

package/package.json

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