prizmkit 1.0.138 → 1.0.139

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.138",
-  "bundledAt": "2026-03-28T14:47:53.378Z",
-  "bundledFrom": "cc919b1"
+  "frameworkVersion": "1.0.139",
+  "bundledAt": "2026-03-28T16:00:11.932Z",
+  "bundledFrom": "ce5323e"
 }

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

@@ -130,7 +130,7 @@ grep -q '^/binary-name$' .gitignore || echo '/binary-name' >> .gitignore
 ```
 Never commit compiled binaries, build output, or generated artifacts.
 
-**Before starting**: detect the test command and record baseline:
+**3a.** Detect the test command and record baseline:
 ```bash
 # Try in order, use first that exits 0
 node --test tests/**/*.test.js 2>&1 | tail -3   # Node built-in
@@ -141,26 +141,22 @@ Record the working command as `TEST_CMD`. Then record baseline failures (if any)
 $TEST_CMD 2>&1 | tee /tmp/test-baseline.txt | tail -20
 ```
 
-For each task in plan.md Tasks section:
-1. Read the relevant section from `context-snapshot.md` (no need to re-read individual files)
-2. Write/edit the code
-3. Run tests after each task: `$TEST_CMD 2>&1 | tee /tmp/test-out.txt | tail -20` — then grep `/tmp/test-out.txt` for failure details; never re-run just to apply a different filter
-4. Mark task `[x]` in plan.md Tasks section immediately
+**3b.** Run `/prizmkit-implement` — this handles the full implementation cycle:
+- Reads plan.md Tasks section from `.prizmkit/specs/{{FEATURE_SLUG}}/`
+- Reads context from `context-snapshot.md` (Prizm docs, TRAPS, file manifest)
+- Implements task-by-task with TDD, marking each `[x]` immediately
+- Creates/updates L2 `.prizm` docs when creating new modules or significantly modifying existing ones — AI selectively decides which modules warrant L2 based on complexity and importance
+- Runs tests using `TEST_CMD` after each task
+- Writes '## Implementation Log' to `context-snapshot.md`
 
-After all tasks complete:
-1. Run the full test suite to ensure nothing is broken
-2. Verify each acceptance criterion from Section 1 of context-snapshot.md is met — check mentally, do NOT re-read files you already wrote
-3. If any criterion is not met, fix it now (max 2 fix rounds)
+**3c.** After implement completes, verify:
+1. All tasks in plan.md are `[x]`
+2. Run the full test suite to ensure nothing is broken
+3. Verify each acceptance criterion from Section 1 of context-snapshot.md is met — check mentally, do NOT re-read files you already wrote
+4. If any criterion is not met, fix it now (max 2 fix rounds)
 
 **CP-2**: All acceptance criteria met, all tests pass.
 
-After verification, append to `context-snapshot.md`:
-```
-## Implementation Log
-Files changed/created: [list]
-Key decisions: [list]
-```
-
 {{IF_BROWSER_INTERACTION}}
 ### Phase 3.5: Browser Verification (playwright-cli)
 
@@ -188,7 +184,8 @@ If any step fails, log the failure and continue. Do NOT retry browser verificati
 **4a.** Run `/prizmkit-retrospective` — maintains `.prizm-docs/` (architecture index):
 1. **Structural sync**: Use `git diff --cached --name-status` to locate changed modules, update KEY_FILES/INTERFACES/DEPENDENCIES/file counts in affected `.prizm-docs/` files
 2. **Architecture knowledge** (feature sessions only): Extract TRAPS/RULES/DECISIONS from completed work into `.prizm-docs/`
-3. Stage doc changes: `git add .prizm-docs/`
+3. **L2 coverage check**: For any module/sub-module with source files created or significantly modified in this session but no L2 `.prizm` doc — evaluate whether L2 is warranted and create if so. The current session has the best context for accurate KEY_FILES, TRAPS, and DECISIONS.
+4. Stage doc changes: `git add .prizm-docs/`
 ⚠️ Do NOT commit here. Only stage.
 
 **4b.** Stage all feature code explicitly (NEVER use `git add -A` or `git add .`):

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

@@ -194,20 +194,13 @@ Wait for Critic to return.
 Spawn Dev subagent (Agent tool, subagent_type="prizm-dev-team-dev", run_in_background=false).
 
 Prompt:
-> "Read {{DEV_SUBAGENT_PATH}}. Implement feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}) using TDD.
-> **IMPORTANT**: Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST.
-> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — Section 3 has Prizm Context (TRAPS/RULES), Section 4 has File Manifest with paths and interfaces.
->    **⚠️ DO NOT re-read source files that are already listed in Section 4 File Manifest.** Only read a source file directly if: (a) NOT in the manifest, (b) needing an implementation detail beyond the interface summary, or (c) needing a constant/enum/field-name value not captured in the interface column.
-> 2. Read `plan.md` (including Tasks section) from `.prizmkit/specs/{{FEATURE_SLUG}}/`.
-> 3. Implement task-by-task. Mark each `[x]` in plan.md Tasks section **immediately** after completion (do NOT batch).
-> 4. Use `TEST_CMD=<TEST_CMD>` to run tests — do NOT explore alternative test commands. **When tests fail: run `$TEST_CMD 2>&1 | tee /tmp/test-out.txt` ONCE, then grep `/tmp/test-out.txt` for failure details. Never re-run the full suite just to apply a different filter.**
-> 5. After ALL tasks done, append '## Implementation Log' to context-snapshot.md with:
->    - Files changed/created (with paths)
->    - Key implementation decisions and rationale
->    - Deviations from plan.md (if any)
->    - Notable discoveries (unexpected behavior, hidden dependencies, new TRAPS)
-> 6. Do NOT execute any git commands (no git add/commit/reset/push).
-> 7. If `<TEST_CMD>` shows failures, check against BASELINE_FAILURES=`<BASELINE_FAILURES>`. Failures present in the baseline are pre-existing — list them explicitly in your COMPLETION_SIGNAL.
+> "Read {{DEV_SUBAGENT_PATH}}. Implement feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}).
+> **IMPORTANT**: Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has Prizm Context (TRAPS/RULES), Section 4 has File Manifest with paths and interfaces.
+> ⚠️ DO NOT re-read source files already listed in Section 4 File Manifest unless you need implementation detail beyond the interface summary.
+> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` for full context.
+> 2. Run `/prizmkit-implement` to execute the tasks in plan.md. Use `TEST_CMD=<TEST_CMD>` for testing. Baseline failures: `BASELINE_FAILURES=<BASELINE_FAILURES>`.
+> 3. After implement completes, verify the '## Implementation Log' section was written to context-snapshot.md.
+> 4. Do NOT execute any git commands (no git add/commit/reset/push).
 > Do NOT exit until all tasks are [x] and the '## Implementation Log' section is written in context-snapshot.md."
 
 Wait for Dev to return. All tasks must be `[x]`, tests pass.
@@ -302,7 +295,8 @@ If any step fails, log the failure and continue. Do NOT retry browser verificati
 **6a.** Run `/prizmkit-retrospective` — maintains `.prizm-docs/` (architecture index):
 1. **Structural sync**: Use `git diff --cached --name-status` to locate changed modules, update KEY_FILES/INTERFACES/DEPENDENCIES/file counts in affected `.prizm-docs/` files
 2. **Architecture knowledge** (feature sessions only): Extract TRAPS/RULES/DECISIONS from completed work into `.prizm-docs/`
-3. Stage doc changes: `git add .prizm-docs/`
+3. **L2 coverage check**: For any module/sub-module with source files created or significantly modified in this session but no L2 `.prizm` doc — evaluate whether L2 is warranted and create if so. The current session has the best context for accurate KEY_FILES, TRAPS, and DECISIONS.
+4. Stage doc changes: `git add .prizm-docs/`
 ⚠️ Do NOT commit here. Only stage.
 
 **6b.** Stage all feature code explicitly (NEVER use `git add -A` or `git add .`):

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

@@ -274,20 +274,13 @@ grep -c '^\- \[ \]' .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null || echo
 Spawn Dev agent (Agent tool, subagent_type="prizm-dev-team-dev", run_in_background=false).
 
 Prompt:
-> "Read {{DEV_SUBAGENT_PATH}}. Implement feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}) using TDD.
-> **IMPORTANT**: Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST.
-> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — Section 3 has Prizm Context (TRAPS/RULES), Section 4 has File Manifest with paths and interfaces.
->    **⚠️ DO NOT re-read source files that are already listed in Section 4 File Manifest.** The manifest already contains their key interfaces. Only read a source file directly if: (a) it is NOT in the manifest, or (b) you need a specific implementation detail not captured in the manifest's interface column.
-> 2. Read `plan.md` (including Tasks section) from `.prizmkit/specs/{{FEATURE_SLUG}}/`.
-> 3. Implement task-by-task. Mark each `[x]` in plan.md Tasks section **immediately** after completion (do NOT batch).
-> 4. Use `TEST_CMD=<TEST_CMD>` to run tests — do NOT explore alternative test commands. **When tests fail: run `$TEST_CMD 2>&1 | tee /tmp/test-out.txt` ONCE, then grep `/tmp/test-out.txt` for failure details. Never re-run the full suite just to apply a different filter.**
-> 5. After ALL tasks done, append '## Implementation Log' to context-snapshot.md with:
->    - Files changed/created (with paths)
->    - Key implementation decisions and rationale
->    - Deviations from plan.md (if any)
->    - Notable discoveries (unexpected behavior, hidden dependencies, new TRAPS)
-> 6. Do NOT execute any git commands (no git add/commit/reset/push).
-> 7. If `<TEST_CMD>` shows failures, check against BASELINE_FAILURES=`<BASELINE_FAILURES>`. Failures present in the baseline are pre-existing — list them explicitly in your COMPLETION_SIGNAL.
+> "Read {{DEV_SUBAGENT_PATH}}. Implement feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}).
+> **IMPORTANT**: Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has Prizm Context (TRAPS/RULES), Section 4 has File Manifest with paths and interfaces.
+> ⚠️ DO NOT re-read source files already listed in Section 4 File Manifest unless you need implementation detail beyond the interface summary.
+> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` for full context.
+> 2. Run `/prizmkit-implement` to execute the tasks in plan.md. Use `TEST_CMD=<TEST_CMD>` for testing. Baseline failures: `BASELINE_FAILURES=<BASELINE_FAILURES>`.
+> 3. After implement completes, verify the '## Implementation Log' section was written to context-snapshot.md.
+> 4. Do NOT execute any git commands (no git add/commit/reset/push).
 > Do NOT exit until all tasks are [x] and the '## Implementation Log' section is written in context-snapshot.md."
 
 **Gate Check — Implementation Log**:
@@ -303,10 +296,8 @@ Wait for Dev to return. **If Dev times out before all tasks are `[x]`**:
    > "Read {{DEV_SUBAGENT_PATH}}. You are resuming implementation of feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}).
    > 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — Section 4 has File Manifest, 'Implementation Log' (if present) shows what was already done.
    > 2. Run `git diff HEAD` to see actual code changes already made.
-   > 3. Read plan.md Tasks section — complete ONLY the remaining `[ ]` tasks. Do NOT redo completed `[x]` tasks.
-   > 4. Use `TEST_CMD=<TEST_CMD>` to run tests.
-   > 5. Append progress to '## Implementation Log' in context-snapshot.md.
-   > 6. Do NOT execute any git commands."
+   > 3. Run `/prizmkit-implement` to complete the remaining `[ ]` tasks. Use `TEST_CMD=<TEST_CMD>` for testing.
+   > 4. Do NOT execute any git commands."
 3. Max 2 recovery retries. After 2 failures, orchestrator implements remaining tasks directly.
 
 All tasks `[x]`, tests pass.
@@ -412,6 +403,7 @@ git log --oneline | grep "{{FEATURE_ID}}" | head -3
 **6b.** Run `/prizmkit-retrospective` (**before commit**, maintains `.prizm-docs/` architecture index):
 - **Structural sync**: update KEY_FILES/INTERFACES/DEPENDENCIES/file counts for changed modules
 - **Architecture knowledge** (feature sessions only): extract TRAPS, RULES, DECISIONS from completed work into `.prizm-docs/`
+- **L2 coverage check**: For any module/sub-module with source files created or significantly modified in this session but no L2 `.prizm` doc — evaluate whether L2 is warranted and create if so. The current session has the best context for accurate KEY_FILES, TRAPS, and DECISIONS.
 - Stage doc changes: `git add .prizm-docs/`
 ⚠️ Do NOT commit here. Only stage.
 - **For bug-fix sessions**: structural sync only, skip knowledge injection unless a genuinely new pitfall was discovered

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

@@ -39,7 +39,10 @@ Execute implementation by following the task breakdown in plan.md. Respects task
 3. Check if checkpoint tasks are complete before proceeding to next phase
 4. For each unchecked task in order:
    a. If task has `[P]` marker, it can run in parallel with other `[P]` tasks in the same group
-   b. Read L2 doc for target file's module (if exists) — TRAPS save you from repeating known mistakes
+   b. Read L2 doc for target file's module. TRAPS save you from repeating known mistakes.
+      - If L2 exists: check TRAPS and DECISIONS before modifying files.
+      - If L2 does not exist and this task creates a new module directory or adds significant source files: create L2 using the L2 GENERATION TEMPLATE (see PRIZM-SPEC). Seed KEY_FILES and DEPENDENCIES from the files being created. TRAPS and DECISIONS can be minimal initially — `/prizmkit-retrospective` will enrich them.
+      - Judgment call: not every directory needs L2. Create L2 when the module has meaningful logic, non-obvious coupling, or design decisions worth preserving. Skip for trivial wrapper directories or single-config modules.
    c. Apply TDD where applicable: write a failing test first, then implement until it passes. For UI components or configuration changes where unit tests don't apply, skip the test-first step.
    d. Mark task as `[x]` in `plan.md` Tasks section immediately — not batched at the end. Immediate marking means the plan always reflects true progress, even if the session is interrupted.
    e. After all tasks, append '## Implementation Log' to `context-snapshot.md` (if running in pipeline context): files changed/created, key decisions, notable discoveries.

package/bundled/skills/prizmkit-prizm-docs/SKILL.md

@@ -76,7 +76,7 @@ STEPS:
 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 counts, CROSS_CUTTING) only if structural change. No UPDATED timestamps — git tracks modification times.
 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, defer 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 using the L2 GENERATION TEMPLATE. Otherwise defer L2.
 7. Append entries to changelog.prizm using format: `- YYYY-MM-DD | <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/`
@@ -162,7 +162,7 @@ When working in a project with .prizm-docs/:
 
 - ON SESSION START: Always read .prizm-docs/root.prizm (L0). This is the project map.
 - ON TASK: Read L1 docs for relevant modules referenced in MODULE_INDEX.
-- ON FILE EDIT: Read L2 doc before modifying files. Check TRAPS and DECISIONS sections.
+- ON FILE EDIT: Read L2 doc before modifying files. Check TRAPS and DECISIONS sections. If L2 does not exist and you are creating/modifying significant source files in this module → generate L2 using the L2 GENERATION TEMPLATE before proceeding.
 - ON DEEP READ: If you need deep understanding of a module without modifying it, generate L2 if it doesn't exist.
 - NEVER load all .prizm docs at once. Progressive loading saves tokens.
 - BUDGET: Typical task should consume 3000-5000 tokens of Prizm docs total.

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

@@ -59,14 +59,16 @@ git diff --name-status
 
 **1d.** Update affected docs (bottom-up: L2 → L1 → L0):
 
-- **L2** (if exists): Update KEY_FILES, INTERFACES, DATA_FLOW, DEPENDENCIES, CHANGELOG, TRAPS, DECISIONS
+- **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.
 - **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).
 
 **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: create L1 doc immediately, add to MODULE_INDEX, defer L2.
+**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.
 
 **1f.** Enforce size limits:
 - L0 > 4KB → consolidate MODULE_INDEX
@@ -143,7 +145,7 @@ When writing TRAPS:
 **QUALITY GATE**: Every item must answer: "If a new AI session reads only `.prizm-docs/` and this entry, does it gain actionable understanding?" If not, discard. Do not record trivially observable code patterns — the AI can read the code directly.
 
 **2c.** Inject into the correct `.prizm-docs/` file:
-- Module-level TRAPS/RULES/DECISIONS → the affected **L2** `.prizm` file's corresponding section (TRAPS/DECISIONS/RULES belong in L2, not L1)
+- Module-level TRAPS/RULES/DECISIONS → the affected **L2** `.prizm` file. If the target L2 does not exist, create it first using the L2 GENERATION TEMPLATE before injecting knowledge. (TRAPS/DECISIONS/RULES belong in L2, not L1.)
 - Project-level RULES/PATTERNS → `root.prizm`
 - Cross-module concerns spanning 2+ modules → `root.prizm` CROSS_CUTTING section
 

package/package.json

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