prizmkit 1.1.3 → 1.1.4

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.1.3",
-  "bundledAt": "2026-04-04T02:47:27.664Z",
-  "bundledFrom": "f15da00"
+  "frameworkVersion": "1.1.4",
+  "bundledAt": "2026-04-04T10:53:06.101Z",
+  "bundledFrom": "5cdc680"
 }

package/bundled/dev-pipeline/run-bugfix.sh

@@ -224,6 +224,41 @@ spawn_and_wait_session() {
 
     log_info "Session result: $session_status"
 
+    # Validate checkpoint completeness after successful session
+    if [[ "$session_status" == "success" ]]; then
+        local _ckpt_root
+        _ckpt_root="$(cd "$SCRIPT_DIR/.." && pwd)"
+        local checkpoint_file="$_ckpt_root/.prizmkit/bugfix/${bug_id}/workflow-checkpoint.json"
+        if [[ -f "$checkpoint_file" ]]; then
+            local checkpoint_result
+            checkpoint_result=$(python3 -c "
+import json, sys
+try:
+    with open(sys.argv[1]) as f:
+        data = json.load(f)
+except json.JSONDecodeError as e:
+    print('CORRUPTED: {}'.format(e))
+    sys.exit(2)
+incomplete = [s for s in data['steps'] if s['status'] not in ('completed', 'skipped')]
+if incomplete:
+    for s in incomplete:
+        print('INCOMPLETE: {} {} = {}'.format(s['id'], s['skill'], s['status']))
+    sys.exit(1)
+print('ALL_COMPLETE')
+sys.exit(0)
+" "$checkpoint_file" 2>&1)
+            local check_exit=$?
+            if [[ $check_exit -eq 2 ]]; then
+                log_warn "CHECKPOINT_CORRUPTED: workflow-checkpoint.json is not valid JSON"
+            elif [[ $check_exit -eq 1 ]]; then
+                log_warn "CHECKPOINT_INCOMPLETE: Not all workflow steps completed:"
+                echo "$checkpoint_result" | while read -r line; do log_warn "  $line"; done
+            else
+                log_info "CHECKPOINT: All workflow steps completed"
+            fi
+        fi
+    fi
+
     # Subagent detection
     prizm_detect_subagents "$session_log"
 

package/bundled/dev-pipeline/run-feature.sh

@@ -287,6 +287,39 @@ sys.exit(1)
         if [[ ! -f "$plan_file" ]]; then
             log_warn "ARTIFACT_MISSING: plan.md not found at $plan_file"
         fi
+
+        # Validate checkpoint completeness
+        local checkpoint_file="$project_root_for_artifacts/.prizmkit/specs/${feature_slug}/workflow-checkpoint.json"
+        if [[ -f "$checkpoint_file" ]]; then
+            local checkpoint_result
+            checkpoint_result=$(python3 -c "
+import json, sys
+try:
+    with open(sys.argv[1]) as f:
+        data = json.load(f)
+except json.JSONDecodeError as e:
+    print('CORRUPTED: {}'.format(e))
+    sys.exit(2)
+incomplete = [s for s in data['steps'] if s['status'] not in ('completed', 'skipped')]
+if incomplete:
+    for s in incomplete:
+        print('INCOMPLETE: {} {} = {}'.format(s['id'], s['skill'], s['status']))
+    sys.exit(1)
+print('ALL_COMPLETE')
+sys.exit(0)
+" "$checkpoint_file" 2>&1)
+            local check_exit=$?
+            if [[ $check_exit -eq 2 ]]; then
+                log_warn "CHECKPOINT_CORRUPTED: workflow-checkpoint.json is not valid JSON"
+            elif [[ $check_exit -eq 1 ]]; then
+                log_warn "CHECKPOINT_INCOMPLETE: Not all workflow steps completed:"
+                echo "$checkpoint_result" | while read -r line; do log_warn "  $line"; done
+            else
+                log_info "CHECKPOINT: All workflow steps completed"
+            fi
+        else
+            log_info "CHECKPOINT: No workflow-checkpoint.json found (checkpoint system not active)"
+        fi
     fi
 
     # Check if session produced a failure-log for future retries

package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py

@@ -530,6 +530,171 @@ def determine_pipeline_mode(complexity):
     return mapping.get(complexity, "lite")
 
 
+# ============================================================
+# Checkpoint generation
+# ============================================================
+
+# Mapping: section name -> (skill_key, display_name, required_artifacts)
+# skill_key is a unique identifier in the checkpoint, not necessarily the
+# prizmkit skill name.  This ensures each section has a distinct key so
+# merge_checkpoint_state() never collides.
+SECTION_TO_SKILL = {
+    "phase0-init": ("prizmkit-init", "Project Bootstrap",
+                    [".prizm-docs/root.prizm", ".prizmkit/config.json"]),
+    "phase0-test-baseline": ("test-baseline", "Test Baseline", []),
+    "phase-context-snapshot": ("context-snapshot", "Build Context Snapshot",
+                               [".prizmkit/specs/{slug}/context-snapshot.md"]),
+    "phase-specify-plan": ("context-snapshot-and-plan", "Specify & Plan",
+                           [".prizmkit/specs/{slug}/context-snapshot.md",
+                            ".prizmkit/specs/{slug}/plan.md"]),
+    "phase-plan": ("prizmkit-plan", "Plan & Tasks",
+                   [".prizmkit/specs/{slug}/plan.md"]),
+    "phase-analyze": ("prizmkit-analyze", "Analyze", []),
+    "phase-critic-plan": ("critic-plan-review", "Critic: Plan Review", []),
+    "phase-implement": ("prizmkit-implement", "Implement + Test", []),
+    "phase-critic-code": ("critic-code-review", "Critic: Code Review", []),
+    "phase-review": ("prizmkit-code-review", "Code Review", []),
+    "phase-browser": ("browser-verification", "Browser Verification", []),
+    "phase-deploy": ("deploy-verification", "Deploy Verification", []),
+    "phase-commit": None,  # special: split into retrospective + committer
+}
+
+# phase-commit is split into two steps
+_COMMIT_STEPS = [
+    ("prizmkit-retrospective", "Retrospective", []),
+    ("prizmkit-committer", "Commit", []),
+]
+
+
+def _resolve_artifacts(artifact_templates, slug):
+    """Replace {slug} placeholder with the actual feature slug."""
+    return [a.replace("{slug}", slug) for a in artifact_templates]
+
+
+def generate_checkpoint_definition(sections, pipeline_mode, workflow_type,
+                                   item_id, item_slug, session_id,
+                                   init_done=False):
+    """Derive checkpoint step definitions from the assembled sections list.
+
+    Args:
+        sections: list of (name, content) tuples from assemble_sections()
+        pipeline_mode: "lite" | "standard" | "full"
+        workflow_type: "feature-pipeline"
+        item_id: feature ID (e.g. "F-001")
+        item_slug: feature slug (e.g. "001-user-auth")
+        session_id: current session ID
+        init_done: whether project is already initialized (Phase 0 skip)
+
+    Returns:
+        dict suitable for writing as workflow-checkpoint.json
+    """
+    steps = []
+    step_counter = 1
+    prev_step_id = None
+
+    for section_name, _content in sections:
+        if section_name not in SECTION_TO_SKILL:
+            continue
+
+        mapping = SECTION_TO_SKILL[section_name]
+
+        if mapping is None:
+            # phase-commit -> split into retrospective + committer
+            for skill, name, artifacts in _COMMIT_STEPS:
+                step_id = "S{:02d}".format(step_counter)
+                steps.append({
+                    "id": step_id,
+                    "skill": skill,
+                    "name": name,
+                    "status": "pending",
+                    "required_artifacts": _resolve_artifacts(artifacts, item_slug),
+                    "depends_on": prev_step_id,
+                })
+                prev_step_id = step_id
+                step_counter += 1
+            continue
+
+        skill, name, artifacts = mapping
+        step_id = "S{:02d}".format(step_counter)
+
+        status = "pending"
+        if init_done and section_name in ("phase0-init", "phase0-test-baseline"):
+            status = "skipped"
+
+        steps.append({
+            "id": step_id,
+            "skill": skill,
+            "name": name,
+            "status": status,
+            "required_artifacts": _resolve_artifacts(artifacts, item_slug),
+            "depends_on": prev_step_id,
+        })
+
+        prev_step_id = step_id
+        step_counter += 1
+
+    return {
+        "version": 1,
+        "workflow_type": workflow_type,
+        "pipeline_mode": pipeline_mode,
+        "item_id": item_id,
+        "item_slug": item_slug,
+        "session_id": session_id,
+        "steps": steps,
+    }
+
+
+def merge_checkpoint_state(existing, fresh, project_root):
+    """Merge existing checkpoint state into a freshly generated definition.
+
+    Matching is by skill_key (not step ID), since tier changes across retries
+    may shift step IDs.
+
+    Merge rules:
+    1. Only keep completed steps whose required_artifacts all exist on disk
+    2. Keep skipped steps unconditionally
+    3. Once a step is NOT completed/skipped, break the dependency chain:
+       all subsequent steps reset to pending
+    """
+    existing_status = {}
+    existing_artifacts = {}
+    for step in existing.get("steps", []):
+        existing_status[step["skill"]] = step["status"]
+        existing_artifacts[step["skill"]] = step.get("required_artifacts", [])
+
+    # Determine which completed steps have valid artifacts
+    valid_completed = set()
+    for skill_key, status in existing_status.items():
+        if status == "completed":
+            artifacts = existing_artifacts.get(skill_key, [])
+            if all(os.path.exists(os.path.join(project_root, a))
+                   for a in artifacts):
+                valid_completed.add(skill_key)
+            else:
+                LOGGER.warning(
+                    "Step '%s' was completed but artifacts missing — "
+                    "resetting to pending", skill_key
+                )
+        elif status == "skipped":
+            valid_completed.add(skill_key)
+
+    # Apply to fresh steps; break chain on first non-valid step
+    chain_broken = False
+    for step in fresh["steps"]:
+        if chain_broken:
+            step["status"] = "pending"
+            continue
+
+        prev = existing_status.get(step["skill"])
+        if step["skill"] in valid_completed:
+            step["status"] = prev  # completed or skipped
+        else:
+            chain_broken = True
+            step["status"] = "pending"
+
+    return fresh
+
+
 # ============================================================
 # Section Assembly (new modular approach)
 # ============================================================
@@ -721,6 +886,12 @@ def assemble_sections(pipeline_mode, sections_dir, init_done, is_resume,
                           load_section(sections_dir,
                                        "subagent-timeout-recovery.md")))
 
+    # --- Checkpoint System ---
+    checkpoint_section_path = os.path.join(sections_dir, "checkpoint-system.md")
+    if os.path.isfile(checkpoint_section_path):
+        sections.append(("checkpoint-system",
+                          load_section(sections_dir, "checkpoint-system.md")))
+
     # --- Execution header ---
     sections.append(("execution-header", "---\n\n## Execution\n"))
 
@@ -1143,6 +1314,9 @@ def build_replacements(args, feature, features, global_context, script_dir):
         "{{SESSION_STATUS_PATH}}": session_status_abs,
         "{{PROJECT_ROOT}}": project_root,
         "{{FEATURE_SLUG}}": feature_slug,
+        "{{CHECKPOINT_PATH}}": os.path.join(
+            ".prizmkit", "specs", feature_slug, "workflow-checkpoint.json",
+        ),
         "{{PIPELINE_MODE}}": pipeline_mode,
         "{{COMPLEXITY}}": complexity,
         "{{CRITIC_ENABLED}}": "true" if critic_enabled else "false",
@@ -1314,6 +1488,52 @@ def main():
     if err:
         emit_failure(err)
 
+    # ── Generate checkpoint file ──────────────────────────────────────
+    project_root = resolve_project_root(
+        os.path.dirname(os.path.abspath(__file__))
+    )
+    feature_slug = replacements.get("{{FEATURE_SLUG}}", "")
+    checkpoint_path = ""
+
+    if use_sections and feature_slug:
+        checkpoint = generate_checkpoint_definition(
+            sections=sections,
+            pipeline_mode=pipeline_mode,
+            workflow_type="feature-pipeline",
+            item_id=args.feature_id,
+            item_slug=feature_slug,
+            session_id=args.session_id,
+            init_done=init_done,
+        )
+
+        checkpoint_dir = os.path.join(
+            project_root, ".prizmkit", "specs", feature_slug,
+        )
+        os.makedirs(checkpoint_dir, exist_ok=True)
+        checkpoint_path = os.path.join(
+            checkpoint_dir, "workflow-checkpoint.json",
+        )
+
+        # On resume, merge existing completed state (with artifact validation)
+        if is_resume and os.path.exists(checkpoint_path):
+            try:
+                with open(checkpoint_path, "r", encoding="utf-8") as f:
+                    existing = json.load(f)
+                checkpoint = merge_checkpoint_state(
+                    existing, checkpoint, project_root,
+                )
+                LOGGER.info("Merged existing checkpoint state from %s",
+                            checkpoint_path)
+            except (json.JSONDecodeError, KeyError) as exc:
+                LOGGER.warning(
+                    "Existing checkpoint corrupted (%s) — generating fresh",
+                    exc,
+                )
+
+        with open(checkpoint_path, "w", encoding="utf-8") as f:
+            json.dump(checkpoint, f, indent=2, ensure_ascii=False)
+        LOGGER.info("Wrote checkpoint to %s", checkpoint_path)
+
     # ── Success JSON ───────────────────────────────────────────────────
     feature_model = feature.get("model", "")
     mode_agent_counts = {"lite": 1, "standard": 3, "full": 3}
@@ -1331,6 +1551,7 @@ def main():
         "render_mode": "sections" if use_sections else "legacy",
         "validation_warnings": len(warnings),
         "validation_errors": len(errors),
+        "checkpoint_path": checkpoint_path,
     }
     print(json.dumps(output, indent=2, ensure_ascii=False))
     sys.exit(0)

package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py

@@ -324,6 +324,95 @@ def emit_failure(message):
     sys.exit(1)
 
 
+# ============================================================
+# Checkpoint generation for bugfix pipeline
+# ============================================================
+
+BUGFIX_STEPS = [
+    ("prizmkit-init", "Initialize", []),
+    ("bug-diagnosis", "Bug Diagnosis & Fix Plan",
+     [".prizmkit/bugfix/{slug}/fix-plan.md"]),
+    ("bug-reproduce", "Write Reproduction Test", []),
+    ("bug-fix", "Implement Fix", []),
+    ("prizmkit-code-review", "Code Review", []),
+    ("prizmkit-committer", "Commit", []),
+    ("bug-report", "Generate Fix Report & Update TRAPS",
+     [".prizmkit/bugfix/{slug}/fix-report.md"]),
+]
+
+
+def generate_bugfix_checkpoint(bug_id, session_id):
+    """Generate a checkpoint definition for bugfix pipeline.
+
+    Returns a dict suitable for writing as workflow-checkpoint.json.
+    """
+    steps = []
+    prev_id = None
+    for i, (skill, name, artifacts) in enumerate(BUGFIX_STEPS, 1):
+        step_id = "S{:02d}".format(i)
+        steps.append({
+            "id": step_id,
+            "skill": skill,
+            "name": name,
+            "status": "pending",
+            "required_artifacts": [a.replace("{slug}", bug_id) for a in artifacts],
+            "depends_on": prev_id,
+        })
+        prev_id = step_id
+
+    return {
+        "version": 1,
+        "workflow_type": "bugfix-pipeline",
+        "pipeline_mode": "single",
+        "item_id": bug_id,
+        "item_slug": bug_id,
+        "session_id": session_id,
+        "steps": steps,
+    }
+
+
+def merge_bugfix_checkpoint_state(existing, fresh, project_root):
+    """Merge existing bugfix checkpoint state into fresh definition.
+
+    Same logic as feature pipeline: validate artifacts, break chain on
+    first invalid step.
+    """
+    existing_status = {}
+    existing_artifacts = {}
+    for step in existing.get("steps", []):
+        existing_status[step["skill"]] = step["status"]
+        existing_artifacts[step["skill"]] = step.get("required_artifacts", [])
+
+    valid_completed = set()
+    for skill_key, status in existing_status.items():
+        if status == "completed":
+            artifacts = existing_artifacts.get(skill_key, [])
+            if all(os.path.exists(os.path.join(project_root, a))
+                   for a in artifacts):
+                valid_completed.add(skill_key)
+            else:
+                LOGGER.warning(
+                    "Step '%s' was completed but artifacts missing — "
+                    "resetting to pending", skill_key
+                )
+        elif status == "skipped":
+            valid_completed.add(skill_key)
+
+    chain_broken = False
+    for step in fresh["steps"]:
+        if chain_broken:
+            step["status"] = "pending"
+            continue
+        prev = existing_status.get(step["skill"])
+        if step["skill"] in valid_completed:
+            step["status"] = prev
+        else:
+            chain_broken = True
+            step["status"] = "pending"
+
+    return fresh
+
+
 def main():
     args = parse_args()
 
@@ -366,6 +455,12 @@ def main():
     # Build replacements
     replacements = build_replacements(args, bug, global_context, script_dir)
 
+    # Add checkpoint path to replacements
+    checkpoint_rel = os.path.join(
+        ".prizmkit", "bugfix", args.bug_id, "workflow-checkpoint.json",
+    )
+    replacements["{{CHECKPOINT_PATH}}"] = checkpoint_rel
+
     # Render the template
     rendered = render_template(template_content, replacements, bug)
 
@@ -374,10 +469,39 @@ def main():
     if err:
         emit_failure(err)
 
+    # Generate checkpoint file
+    project_root = resolve_project_root(script_dir)
+    checkpoint_path = os.path.join(project_root, checkpoint_rel)
+    checkpoint_dir = os.path.dirname(checkpoint_path)
+    os.makedirs(checkpoint_dir, exist_ok=True)
+
+    checkpoint = generate_bugfix_checkpoint(args.bug_id, args.session_id)
+
+    is_resume = args.resume_phase != "null"
+    if is_resume and os.path.exists(checkpoint_path):
+        try:
+            with open(checkpoint_path, "r", encoding="utf-8") as f:
+                existing = json.load(f)
+            checkpoint = merge_bugfix_checkpoint_state(
+                existing, checkpoint, project_root,
+            )
+            LOGGER.info("Merged existing bugfix checkpoint from %s",
+                        checkpoint_path)
+        except (json.JSONDecodeError, KeyError) as exc:
+            LOGGER.warning(
+                "Existing bugfix checkpoint corrupted (%s) — generating fresh",
+                exc,
+            )
+
+    with open(checkpoint_path, "w", encoding="utf-8") as f:
+        json.dump(checkpoint, f, indent=2, ensure_ascii=False)
+    LOGGER.info("Wrote bugfix checkpoint to %s", checkpoint_path)
+
     # Success
     output = {
         "success": True,
         "output_path": os.path.abspath(args.output),
+        "checkpoint_path": checkpoint_path,
     }
     print(json.dumps(output, indent=2, ensure_ascii=False))
     sys.exit(0)

package/bundled/dev-pipeline/templates/agent-prompts/dev-implement.md

@@ -3,7 +3,8 @@
 ⚠️ 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. Run tests with: `{{TEST_CMD}}`. Known baseline failures (pre-existing, not your fault): `{{BASELINE_FAILURES}}`.
-3. After implement completes, verify the '## Implementation Log' section was written to context-snapshot.md.
+3. If plan.md has more than 5 tasks: run `/compact` after completing every 3 tasks to manage context budget. If `/compact` is unavailable, continue without it.
+4. After implement completes, verify the '## Implementation Log' section was written to context-snapshot.md.
 
 ## Acceptance Criteria Verification
 

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

@@ -152,6 +152,8 @@ $TEST_CMD 2>&1 | tee /tmp/test-baseline.txt | tail -20
 - Runs tests using `TEST_CMD` after each task
 - Writes '## Implementation Log' to `context-snapshot.md`
 
+**3b-compact.** Context management — if plan.md has more than 5 tasks, run `/compact` after completing every 3 tasks during implementation. This prevents context window exhaustion in long sessions. If `/compact` is not available (non-Claude CLI), skip this step.
+
 **3c.** After implement completes, verify:
 1. All tasks in plan.md are `[x]`
 2. Run the full test suite to ensure nothing is broken
@@ -285,6 +287,8 @@ git status --short
 ```
 Working tree MUST be clean after this step. If any feature-related files remain, stage them into the SAME commit via `git add <file> && git commit --amend --no-edit`, do NOT create a separate commit.
 
+**Exception**: `session-summary.md` in the artifact directory is a local cross-session artifact generated by `/prizmkit-committer` — it is NOT committed to git. Ignore it in the clean-tree check.
+
 ## Critical Paths
 
 | Resource | Path |

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

@@ -215,8 +215,9 @@ Prompt:
 > ⚠️ 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. Run tests with: `{{TEST_CMD}}`. Known baseline failures (pre-existing, not your fault): `{{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).
+> 3. If plan.md has more than 5 tasks: run `/compact` after completing every 3 tasks to manage context budget. If `/compact` is unavailable, continue without it.
+> 4. After implement completes, verify the '## Implementation Log' section was written to context-snapshot.md.
+> 5. 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.
@@ -383,6 +384,8 @@ git status --short
 ```
 Working tree MUST be clean after this step. If any feature-related files remain, stage them into the SAME commit via `git add <file> && git commit --amend --no-edit`, do NOT create a separate commit.
 
+**Exception**: `session-summary.md` in the artifact directory is a local cross-session artifact generated by `/prizmkit-committer` — it is NOT committed to git. Ignore it in the clean-tree check.
+
 ## Critical Paths
 
 | Resource | Path |

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

@@ -280,8 +280,9 @@ Prompt:
 > ⚠️ 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. Run tests with: `{{TEST_CMD}}`. Known baseline failures (pre-existing, not your fault): `{{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).
+> 3. If plan.md has more than 5 tasks: run `/compact` after completing every 3 tasks to manage context budget. If `/compact` is unavailable, continue without it.
+> 4. After implement completes, verify the '## Implementation Log' section was written to context-snapshot.md.
+> 5. 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**:
@@ -476,6 +477,8 @@ git status --short
 ```
 Working tree MUST be clean after this step. If any feature-related files remain, stage them into the SAME commit via `git add <file> && git commit --amend --no-edit`, do NOT create a separate commit.
 
+**Exception**: `session-summary.md` in the artifact directory is a local cross-session artifact generated by `/prizmkit-committer` — it is NOT committed to git. Ignore it in the clean-tree check.
+
 ## Critical Paths
 
 | Resource | Path |

package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md

@@ -67,6 +67,19 @@ You are the **bug fix session orchestrator**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}
 
 **IMPORTANT**: Only 2 artifact files per bug, NEVER more. This is a fixed convention.
 
+## Workflow Checkpoint System
+
+A checkpoint file tracks your progress through this workflow:
+
+**Path**: `{{CHECKPOINT_PATH}}`
+
+**Rules**:
+1. **Before each step**: Read `workflow-checkpoint.json`, verify the previous step has `status: "completed"` or `status: "skipped"`. If not, complete it first.
+2. **Starting a step**: Update the current step to `status: "in_progress"`.
+3. **After each step completes**: Update the step to `status: "completed"`. Verify JSON is valid after writing.
+4. **On failure**: Set the step to `status: "failed"` and halt.
+5. **On resume**: Steps already `"completed"` are skipped. Start from the first `"pending"` or `"in_progress"` step.
+
 ## Execution Instructions
 
 **YOU are the orchestrator. Execute each phase by spawning the appropriate team agent with run_in_background=false.**
@@ -109,6 +122,7 @@ Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
   "
 - **Wait for Dev to return**
 - **CP-BF-1**: `.prizmkit/bugfix/{{BUG_ID}}/fix-plan.md` exists
+- **Checkpoint update**: set step `bug-diagnosis` to `"completed"` in `{{CHECKPOINT_PATH}}`
 
 **DECISION GATE — Fast Path Check**:
 - If severity is LOW or MEDIUM, AND root cause is obvious (high confidence), AND fix is < 10 lines:
@@ -141,6 +155,7 @@ Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
   - Write session-status.json with status="partial", errors=["reproduction_failed"]
   - Set bug status to `needs_info` and STOP
 - **CP-BF-2**: Reproduction test exists and FAILS
+- **Checkpoint update**: set step `bug-reproduce` to `"completed"` in `{{CHECKPOINT_PATH}}`
 
 ---
 
@@ -158,11 +173,13 @@ Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
      - Do NOT refactor — fix the bug only
   4. Run the reproduction test → MUST PASS
   5. Run the module's test suite → MUST PASS (no regression)
-  6. If fix fails after 3 rounds, report detailed analysis
+  6. If the fix involves multiple files or steps: run `/compact` after completing the core fix and before running the full test suite, to free context budget. If `/compact` is unavailable, continue without it.
+  7. If fix fails after 3 rounds, report detailed analysis
   "
 - **Wait for Dev to return**
 - If fix fails after 3 rounds: escalate to user, write status="failed"
 - **CP-BF-3**: Reproduction test passes, module tests pass
+- **Checkpoint update**: set step `bug-fix` to `"completed"` in `{{CHECKPOINT_PATH}}`
 
 ---
 
@@ -185,6 +202,7 @@ Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
 - **Wait for Reviewer to return**
 - If NEEDS_FIXES: return to Phase 3 for refinement following Fix Instructions (max 2 review rounds)
 - **CP-BF-4**: Code review passes, all tests green
+- **Checkpoint update**: set step `prizmkit-code-review` to `"completed"` in `{{CHECKPOINT_PATH}}`
 
 {{IF_VERIFICATION_MANUAL_OR_HYBRID}}
 **MANUAL VERIFICATION GATE**:
@@ -222,6 +240,7 @@ Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
   - Acceptance Criteria Verification (checklist with pass/fail for each criterion)
 
 - **CP-BF-5**: Commit recorded, fix-report.md written, TRAPS updated (if applicable)
+- **Checkpoint update**: set steps `prizmkit-committer` and `bug-report` to `"completed"` in `{{CHECKPOINT_PATH}}`
 
 ### Step 3: Report Session Status
 

package/bundled/dev-pipeline/templates/sections/checkpoint-system.md

@@ -0,0 +1,36 @@
+## Workflow Checkpoint System
+
+A checkpoint file tracks your progress through this workflow:
+
+**Path**: `{{CHECKPOINT_PATH}}`
+
+### Rules
+
+1. **Before each skill**: Read `workflow-checkpoint.json`, verify the previous step has `status: "completed"` or `status: "skipped"`. If it is still `"pending"` or `"in_progress"`, you MUST complete it first before moving on.
+
+2. **Starting a skill**: Update the current step to `status: "in_progress"`.
+
+3. **After each skill completes**: Update the current step to `status: "completed"`. Then immediately re-read the file to verify the JSON is valid. If the read fails, re-write the file with correct JSON.
+
+4. **On failure**: Set the step to `status: "failed"` and continue to the next step if possible, or halt and write failure-log.md.
+
+5. **On session exit**: The checkpoint file reflects your actual progress. Do NOT manually set future steps to "completed".
+
+### Checkpoint Update Pattern
+
+After completing each skill:
+
+1. Read `{{CHECKPOINT_PATH}}`
+2. Update the current step `"status": "completed"`
+3. Update the next step `"status": "in_progress"`
+4. Write the updated JSON back to `{{CHECKPOINT_PATH}}`
+5. Verify: `python3 -c "import json; json.load(open('{{CHECKPOINT_PATH}}'))"` — if this fails, re-write
+
+### Resume Behavior
+
+**Checkpoint is the primary source of truth for resume.** On retry sessions:
+
+1. Read `workflow-checkpoint.json` — steps already `"completed"` or `"skipped"` are skipped
+2. Start from the first `"pending"` or `"in_progress"` step
+3. If `failure-log.md` exists, read it for diagnostic context (why the previous session failed, what approach to try differently) — but do NOT use it to determine which step to resume from
+4. If `workflow-checkpoint.json` is missing or corrupted, fall back to `failure-log.md` + the resume phase as the legacy mechanism

package/bundled/dev-pipeline/templates/sections/failure-log-check.md

@@ -1,4 +1,4 @@
-**Check for previous failure log:**
+**Check for previous failure log** (diagnostic context only — do NOT use to determine resume point):
 ```bash
 cat .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md 2>/dev/null || echo "NO_PREVIOUS_FAILURE"
 ```
@@ -6,3 +6,4 @@ 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 the commit phase retrospective
 - Do NOT delete failure-log.md until this session completes all phases and commits successfully
+- **Note**: The resume point is determined by `workflow-checkpoint.json`, not by failure-log.md

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

@@ -14,3 +14,6 @@ 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

@@ -14,3 +14,6 @@ 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"`.

package/bundled/dev-pipeline/templates/sections/phase-browser-verification.md

@@ -30,3 +30,6 @@ You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without
    ```
 
 If verification fails, log the failure details but continue to commit. Failures do NOT block the commit, but you MUST attempt verification and MUST clean up the dev server.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `browser-verification` to `"completed"`.

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

@@ -34,3 +34,6 @@ This single commit includes: feature code + tests + .prizm-docs/ updates. Do NOT
 git status --short
 ```
 Working tree MUST be clean after this step. If any feature-related files remain, stage them into the SAME commit via `git add <file> && git commit --amend --no-edit`, do NOT create a separate commit.
+
+
+**Checkpoint update**: After `/prizmkit-retrospective` completes, update `workflow-checkpoint.json` — set step `prizmkit-retrospective` to `"completed"`. After `/prizmkit-committer` completes, set step `prizmkit-committer` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-commit.md

@@ -24,3 +24,6 @@ This single commit includes: feature code + tests + .prizm-docs/ updates. Do NOT
 git status --short
 ```
 Working tree MUST be clean after this step. If any feature-related files remain, stage them into the SAME commit via `git add <file> && git commit --amend --no-edit`, do NOT create a separate commit.
+
+
+**Checkpoint update**: After `/prizmkit-retrospective` completes, update `workflow-checkpoint.json` — set step `prizmkit-retrospective` to `"completed"`. After `/prizmkit-committer` completes, set step `prizmkit-committer` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-context-snapshot-agent-suffix.md

@@ -12,3 +12,6 @@
 
      ### Known TRAPS (from .prizm-docs/)
      - <trap entries extracted from L1/L2 docs>
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `context-snapshot` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-context-snapshot-lite-suffix.md

@@ -1,3 +1,6 @@
    - **Section 3 — Prizm Context**: content of root.prizm and relevant L1/L2 docs
    - **Section 4 — Existing Source Files**: **full verbatim content** of each related file in fenced code blocks (with `### path/to/file` heading and line count). Include ALL files needed for implementation and review — downstream phases read this section instead of re-reading individual source files
    - **Section 5 — Existing Tests**: full content of related test files as code block
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `context-snapshot` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-critic-code.md

@@ -20,3 +20,6 @@ Wait for Critic to return.
 - Read challenge-report.md. For items marked CRITICAL/HIGH: spawn Dev to fix, then proceed to Review.
 
 **CP-3.5**: Code challenges reviewed and resolved.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `critic-code-review` to `"completed"`.

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

@@ -42,3 +42,6 @@ After all critics return, read all 3 reports:
 - Max 1 plan revision round.
 
 **CP-2.5**: Plan challenges reviewed and resolved.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `critic-plan-review` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-critic-plan.md

@@ -21,3 +21,6 @@ Wait for Critic to return.
 - Max 1 plan revision round.
 
 **CP-2.5**: Plan challenges reviewed and resolved.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `critic-plan-review` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-deploy-verification.md

@@ -34,3 +34,6 @@ Deploy verification does NOT block the commit, but you MUST attempt it.
 4. Record smoke test results in `## Deploy Verification` section
 
 If the project cannot be started locally (e.g., requires external services, databases, credentials), skip the smoke test and note why.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `deploy-verification` to `"completed"`.

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

@@ -19,3 +19,6 @@ After Dev agent returns, verify the Implementation Log was written:
 grep -q "## Implementation Log" .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md && echo "GATE:PASS" || echo "GATE:MISSING"
 ```
 If GATE:MISSING — send message to Dev (re-spawn if needed): "Write the '## Implementation Log' section to context-snapshot.md before I can proceed to review. Include: files changed/created, key decisions, deviations from plan, notable discoveries."
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-implement` to `"completed"`.

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

@@ -32,3 +32,6 @@ Wait for Dev to return. **If Dev times out before all tasks are `[x]`**:
 3. Max 2 recovery retries. After 2 failures, orchestrator implements remaining tasks directly.
 
 All tasks `[x]`, tests pass.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-implement` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-implement-lite.md

@@ -30,3 +30,6 @@ $TEST_CMD 2>&1 | tee /tmp/test-baseline.txt | tail -20
 4. If any criterion is not met, fix it now (max 2 fix rounds)
 
 **CP-2**: All acceptance criteria met, all tests pass.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-implement` to `"completed"`.

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

@@ -15,3 +15,6 @@ Before proceeding past CP-1, verify:
 4. If a DB design decision genuinely cannot be resolved from existing code alone, document the assumption made and flag it in the Implementation Log for user review.
 
 **CP-1**: plan.md exists with Tasks section.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-plan` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-plan-lite.md

@@ -14,3 +14,6 @@ Before proceeding past CP-1:
 3. Resolve all uncertain DB design decisions before writing Tasks — document choices in plan.md
 
 **CP-1**: plan.md exists with Tasks section.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-plan` to `"completed"`.

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

@@ -21,3 +21,6 @@ If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '#
 - If NEEDS_FIXES: spawn Dev to fix (Dev reads Fix Instructions in snapshot), re-run Review (max 3 rounds)
 
 **CP-3**: Tests pass, verdict is not NEEDS_FIXES.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-code-review` to `"completed"`.

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

@@ -23,3 +23,6 @@ If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '#
   Then re-run Review (max 3 rounds).
 
 **CP-3**: Integration tests pass, verdict is not NEEDS_FIXES.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-code-review` to `"completed"`.

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

@@ -80,3 +80,6 @@ Before proceeding past CP-1, verify:
 4. If a DB design decision genuinely cannot be resolved from existing code alone, document the assumption made and flag it in the Implementation Log for user review.
 
 **CP-1**: Both spec.md and plan.md exist.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `context-snapshot-and-plan` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase0-init.md

@@ -2,3 +2,6 @@
 - Run `/prizmkit-init` (invoke the prizmkit-init skill)
 - Run `python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
 - **CP-0**: Verify `.prizm-docs/root.prizm`, `.prizmkit/config.json` exist
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-init` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase0-test-baseline.md

@@ -10,3 +10,6 @@ $TEST_CMD 2>&1 | tee /tmp/test-baseline.txt | tail -20
 Save the list of **pre-existing failing tests** (if any) as `BASELINE_FAILURES`. These are known failures that existed before this session — Dev must NOT be blamed for them, but must list them in COMPLETION_SIGNAL.
 
 > **Test Output Rule**: Always capture test output to a temp file (`tee /tmp/test-out.txt`). Then grep the file instead of re-running the suite.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `test-baseline` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/resume-header.md

@@ -1,2 +1,5 @@
 ### Resume from Phase {{RESUME_PHASE}}
-Check `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — if it exists, skip context building and use it directly.
+
+**Primary**: Read `{{CHECKPOINT_PATH}}` — find the first step with `"pending"` or `"in_progress"` status and resume from there. Steps already `"completed"` or `"skipped"` must NOT be re-executed.
+
+**Fallback**: If `workflow-checkpoint.json` is missing or corrupted, check `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — if it exists, skip context building and use it directly.

package/bundled/rules/prizm/prizm-commit-workflow.md

@@ -8,3 +8,4 @@ Before any git commit in this project:
 3. Bug fixes use `fix()` prefix, not `feat()`
 4. Bug fixes run retrospective with structural sync only (Job 1)
 5. Use `/prizmkit-committer` command for the pure commit workflow
+6. After commit, `/prizmkit-committer` generates `session-summary.md` (lightweight cross-session handoff, not committed to git)

package/bundled/rules/prizm/prizm-documentation.md

@@ -18,19 +18,20 @@ WHEN TO UPDATE .prizm-docs/:
 - Before modifying any source file, read `.prizm-docs/root.prizm` if it exists to understand project structure.
 
 FORMAT RULES (enforced by pre-commit hook — violations block commit):
-- ALL CAPS section headers: MODULE:, FILES:, RESPONSIBILITY:, UPDATED:, etc.
+- ALL CAPS section headers: MODULE:, FILES:, RESPONSIBILITY:, etc.
 - KEY: value pairs and dash-prefixed lists only
 - PROHIBITED: prose paragraphs, markdown headers (##/###), code blocks (```), emoji, ASCII art
+- No UPDATED timestamps — git is the authoritative source for temporal information
 - This format is designed for AI token efficiency, not human readability. Do not add human-friendly formatting.
 
 SIZE LIMITS (hard — pre-commit hook blocks commits exceeding these):
 - L0 root.prizm: 4KB max
-- L1 module.prizm: 3KB max
+- L1 module.prizm: 4KB max
 - L2 detail.prizm: 5KB max
 
 SIZE OVERFLOW HANDLING:
-- L0 approaching 4KB: consolidate MODULE_INDEX, keep only top-5 RULES, remove PATTERNS detail
-- L1 approaching 3KB: move implementation details to L2, keep only INTERFACES signatures
+- L0 approaching 4KB: if MODULE_INDEX has > 15 entries, convert to MODULE_GROUPS format (group by domain). Otherwise consolidate descriptions, keep only top-5 RULES, remove PATTERNS detail.
+- L1 approaching 4KB: trim KEY_FILES descriptions, ensure RULES <= 3 entries, move detail to L2
 - L2 approaching 5KB: archive CHANGELOG entries older than 90 days to changelog-archive.prizm
 - NEVER exceed hard limits — pre-commit hook will block the commit
 
@@ -40,26 +41,24 @@ L0 root.prizm:
 - PRIZM_VERSION
 - PROJECT
 - LANG
-- MODULE_INDEX (with -> pointers to L1 files)
+- MODULE_INDEX or MODULE_GROUPS (with -> pointers to L1 files)
 - RULES (top-level project rules)
-- UPDATED
 
-L1 module.prizm:
+L1 module.prizm (structural index only):
 - MODULE
 - FILES
 - RESPONSIBILITY
-- INTERFACES (public/exported only)
 - DEPENDENCIES
-- UPDATED
+- L1 does NOT contain: INTERFACES, DATA_FLOW, TRAPS, DECISIONS (those belong in L2)
 
 L2 detail.prizm:
 - MODULE
 - FILES
 - KEY_FILES
 - DEPENDENCIES
-- TRAPS
+- INTERFACES
+- TRAPS (with severity prefix: [CRITICAL], [HIGH], or [LOW])
 - CHANGELOG
-- UPDATED
 
 L2 GENERATION TEMPLATE (use when AI first touches a sub-module with no L2 doc):
 
@@ -71,10 +70,11 @@ KEY_FILES:
 DEPENDENCIES:
 - uses: <lib>: <why>
 - imports: <module>: <what>
+INTERFACES:
+- <exported function/class>: <signature and purpose>
 TRAPS:
-- <gotcha, race condition, or non-obvious coupling>
+- [LOW] <gotcha, race condition, or non-obvious coupling> | FIX: <approach>
 CHANGELOG:
-- <YYYY-MM-DD> | add: initial L2 documentation
-UPDATED: <YYYY-MM-DD>
+- root | add: initial L2 documentation
 
-TRAPS is critical — always record gotchas, race conditions, non-obvious behavior, and surprising coupling between modules.
+TRAPS is critical — always record gotchas, race conditions, non-obvious behavior, and surprising coupling between modules. Every TRAP must have a severity prefix ([CRITICAL], [HIGH], or [LOW]).

package/bundled/rules/prizm/prizm-progressive-loading.md

@@ -4,7 +4,8 @@ description: "PrizmKit progressive context loading protocol"
 
 This project uses PrizmKit's progressive loading protocol:
 - ON SESSION START: Read `.prizm-docs/root.prizm` (L0 — project map)
-- ON TASK: Read L1 (`.prizm-docs/<module>.prizm`) for relevant modules
+- ON RESUME (feature/bugfix directory has session-summary.md): Read session-summary.md first for prior context, then load only L1/L2 for modules mentioned in it
+- ON TASK: Read L1 (`.prizm-docs/<module>.prizm`) for relevant modules. If MODULE_INDEX entries have keyword tags (e.g., `[login, jwt, oauth]`), match user's task description against tags to prioritize which modules' L1 to load first. If root.prizm uses MODULE_GROUPS, identify the relevant domain first, then load L1 only for modules in that domain.
 - ON FILE EDIT: Read L2 (`.prizm-docs/<module>/<submodule>.prizm`) before modifying
 - NEVER load all .prizm docs at once
 - Arrow notation (->) in .prizm files indicates load pointers

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.3",
+  "version": "1.1.4",
   "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/assets/project-memory-template.md

@@ -5,7 +5,8 @@ This project uses PrizmKit with the Prizm documentation system for AI-optimized
 
 ### Progressive Loading Protocol
 - ON SESSION START: Always read `.prizm-docs/root.prizm` first (L0 — project map)
-- ON TASK: Read L1 (`.prizm-docs/<module>.prizm`) for relevant modules referenced in MODULE_INDEX
+- ON RESUME (feature/bugfix directory has session-summary.md): Read session-summary.md first for prior context, then load only L1/L2 for modules mentioned in it
+- ON TASK: Read L1 (`.prizm-docs/<module>.prizm`) for relevant modules referenced in MODULE_INDEX or MODULE_GROUPS. If entries have keyword tags (e.g., `[login, jwt, oauth]`), match user's task against tags to prioritize which modules to load.
 - ON FILE EDIT: Read L2 (`.prizm-docs/<module>/<submodule>.prizm`) before modifying files. Pay attention to TRAPS and DECISIONS.
 - NEVER load all .prizm docs at once. Load only what is needed for the current task.
 
@@ -16,9 +17,10 @@ This project uses PrizmKit with the Prizm documentation system for AI-optimized
 
 ### Doc Format Rules
 - All `.prizm` files use KEY: value format, not prose
-- Size limits: L0 = 4KB, L1 = 3KB, L2 = 5KB
+- Size limits: L0 = 4KB, L1 = 4KB, L2 = 5KB
 - Arrow notation (->) indicates load pointers to other .prizm docs
 - DECISIONS and CHANGELOG are append-only (never delete entries)
+- No date/time fields — git is the authoritative source for temporal info
 
 ### Creating New L2 Docs
 - When you first modify files in a sub-module that has no L2 doc:

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

@@ -61,6 +61,34 @@ git status
 ```
 - If "nothing to commit, working tree clean": commit verified successfully, proceed
 
+#### Step 5.5: Generate Session Summary (for cross-session recovery)
+
+After a successful commit, generate a lightweight handoff file for future sessions. Locate the artifact directory (`.prizmkit/specs/<feature-dir>/` for features, `.prizmkit/refactor/<slug>/` for refactors, `.prizmkit/bugfix/<id>/` for bugfixes) by checking which `plan.md` was used in this workflow.
+
+If an artifact directory with `plan.md` is found, write `session-summary.md` in that directory:
+
+```markdown
+# Session Summary
+## Completed Tasks
+<list task IDs and one-line descriptions from plan.md [x] items>
+
+## Files Changed
+<list from `git diff HEAD~1 --name-only` of the commit just made>
+
+## Key Decisions
+<1-3 bullet points of non-obvious design choices made this session, referencing DECISIONS in .prizm-docs/ if applicable>
+
+## Active TRAPS
+<any CRITICAL or HIGH TRAPS relevant to the changed files, copied from .prizm-docs/ L2>
+
+## Remaining Work
+<list unchecked [ ] task IDs from plan.md, or "None — feature complete" if all done>
+```
+
+Keep this file under 1.5KB. If no artifact directory with `plan.md` can be identified (e.g., ad-hoc commit), skip this step.
+
+**Lifecycle**: `session-summary.md` is a local cross-session artifact — do NOT commit it to git. It exists only on disk for the next session to read. Overwrite any existing `session-summary.md` from a previous session — this file reflects only the most recent commit's state. In pipeline mode, this file will remain as an untracked file after commit; the pipeline runner should ignore it (it is not a sign of incomplete work).
+
 #### Step 6: Optional Push
 Ask user: "Push to remote?"
 - Yes: `git push`

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

@@ -29,8 +29,9 @@ description: "Execute plan.md tasks with TDD approach. Respects task ordering an
      - **Feature mode**: read `spec.md` in the same directory
      - **Refactor mode**: read `refactor-analysis.md` in the same directory — pay special attention to Scope Boundary (do not implement changes outside scope) and Baseline Tests (all must still pass)
      - **Bugfix mode**: read `fix-plan.md` in the same directory
-2. Load project context — use the most efficient source available:
+2. Load project context — use the most efficient source available (check in this order):
    - If `context-snapshot.md` exists in the feature directory → read it. Section 3 has Prizm docs + TRAPS. Section 4 has File Manifest (Tier-2/3) or full source (Tier-1). Read source files on-demand as directed by the manifest.
+   - Else if `session-summary.md` exists in the feature directory → read it for quick context recovery (completed tasks, key decisions, active TRAPS). Then load only the L1/L2 docs for modules listed in "Files Changed" — skip unrelated modules.
    - Otherwise → **self-service context fallback**:
      1. Read **architecture index**: `.prizm-docs/root.prizm` and relevant L1/L2 for affected modules. Pay special attention to TRAPS and DECISIONS.
      2. Scan needed source files

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

@@ -71,7 +71,8 @@ BROWNFIELD WORKFLOW (existing project):
 **Step 2: Prizm Documentation Generation**
 Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structure from Step 1:
   - Create `.prizm-docs/` directory structure mirroring the source tree (sub-module dirs become subdirectories under `.prizm-docs/<top-level>/`)
-  - Generate `root.prizm` (L0) with project meta and MODULE_INDEX listing only top-level modules
+  - Generate `root.prizm` (L0) with project meta and MODULE_INDEX listing only top-level modules. If module count > 15, use MODULE_GROUPS format instead (group by functional domain).
+  - For each module entry in MODULE_INDEX/MODULE_GROUPS, include keyword tags extracted from the module's source files — scan for: exported symbols, imported packages, domain terms in file/directory names. Format: `- module-name [tag1, tag2, tag3]: ...`. Tags help AI match user intent to relevant modules.
   - Generate L1 docs for top-level modules at `.prizm-docs/<M>.prizm` and for sub-modules at `.prizm-docs/<M>/<S>.prizm`
   - Create `changelog.prizm`
   - Skip L2 (lazy generation) — L2 is generated on first file modification, saving tokens upfront

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

@@ -52,6 +52,8 @@ STEPS:
    - Exclude .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .prizmkit/, .prizm-docs/, dev-pipeline/. If total module count > 30, ask user for include/exclude patterns.
 3. Create .prizm-docs/ directory structure mirroring the source tree exactly. For each top-level module M that has sub-modules, create the subdirectory .prizm-docs/<M>/.
 4. Generate root.prizm (L0) with PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY, MODULE_INDEX with multi-level entries as needed for efficient navigation (constrained by 4KB limit), RULES extracted from CODEBUDDY.md/CLAUDE.md/README/linter configs, PATTERNS, and CROSS_CUTTING (cross-module concerns spanning 2+ modules). Set PRIZM_VERSION: 4. Max 4KB. No UPDATED timestamp — git tracks modification times.
+   - If module count > 15: use MODULE_GROUPS format instead of MODULE_INDEX — group modules by functional domain (3-8 domains, inferred from directory structure and module responsibilities). See PRIZM-SPEC for MODULE_GROUPS format.
+   - For each module entry, auto-generate 3-6 keyword tags by scanning the module's key source files for: exported function/class names, imported library names, domain-specific terms in file/directory names. Add tags in square brackets after the module name (e.g., `- auth [login, session, jwt]: ...`). Tags are optional but recommended for projects with 10+ modules.
 5. Generate L1 .prizm files (structural index only) for ALL modules, each at its correct mirrored path:
    - Top-level module M → write .prizm-docs/<M>.prizm (include SUBDIRS section with pointers to sub-module docs)
    - Sub-module S inside M → write .prizm-docs/<M>/<S>.prizm
@@ -72,9 +74,9 @@ 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 in root.prizm. Group changes by module.
+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 counts, CROSS_CUTTING) only if structural change. No UPDATED timestamps — git tracks modification times.
+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.
 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 using the L2 GENERATION TEMPLATE. 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 using the L2 GENERATION TEMPLATE. This ensures Update fills documentation gaps left by previous sessions.
@@ -110,7 +112,7 @@ STEPS:
 2. Re-scan the module directory for files, interfaces, dependencies, subdirectories.
 3. Generate fresh L1 doc with full module analysis.
 4. Generate L2 docs for all sub-modules immediately (unlike init, rebuild generates L2 right away to capture current state).
-5. Update MODULE_INDEX in root.prizm with new file counts and pointers.
+5. Update MODULE_INDEX (or MODULE_GROUPS) in root.prizm with new file counts and pointers. Re-evaluate grouping: if total module count > 15 and currently using MODULE_INDEX, convert to MODULE_GROUPS. Regenerate keyword tags for rebuilt modules.
 6. Append rebuild entry to changelog.prizm: `- YYYY-MM-DD | <module-path> | refactor: rebuilt module documentation from scratch`
 7. Validate regenerated docs against size limits and format rules.
 
@@ -127,9 +129,10 @@ STEPS:
 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). Verify L1 docs have MODULE, FILES, RESPONSIBILITY, DEPENDENCIES (no INTERFACES/TRAPS/DECISIONS). Verify L2 docs have MODULE, FILES, KEY_FILES, DEPENDENCIES, INTERFACES, TRAPS.
+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-prizm-docs/assets/PRIZM-SPEC.md

@@ -182,6 +182,36 @@ CONSTRAINTS:
 - No prose paragraphs
 - root.prizm RULES are AUTHORITATIVE: they override any conflicting L1/L2 RULES
 
+### MODULE_GROUPS (alternative to MODULE_INDEX for projects with 15+ modules)
+
+When MODULE_INDEX would exceed 15 entries, replace it with MODULE_GROUPS to stay within the 4KB limit. Group modules by functional domain:
+
+  MODULE_GROUPS:
+    <domain-name>:
+      - <module>: <file-count> files. <one-line description>. -> .prizm-docs/<module>.prizm
+      - <module>: <file-count> files. <one-line description>. -> .prizm-docs/<module>.prizm
+    <domain-name>:
+      - <module>: <file-count> files. <one-line description>. -> .prizm-docs/<module>.prizm
+
+CONSTRAINTS for MODULE_GROUPS:
+- Exactly ONE of MODULE_INDEX or MODULE_GROUPS must be present in root.prizm (not both)
+- Domain names: lowercase, descriptive (e.g., api, frontend, infrastructure, shared, data)
+- 3-8 domains is the ideal range
+- Each module appears in exactly one domain
+- Every entry must have an arrow pointer (->), same as MODULE_INDEX
+- AI should load the relevant domain's modules when working on a task, not all domains
+
+### Optional Keyword Tags (applies to both MODULE_INDEX and MODULE_GROUPS)
+
+Entries may include keyword tags for AI intent matching:
+
+  MODULE_INDEX:
+    - auth [login, session, jwt, oauth]: 12 files. Authentication and authorization. -> .prizm-docs/auth.prizm
+    - payments [stripe, billing, subscription]: 8 files. Payment processing. -> .prizm-docs/payments.prizm
+    - users: 6 files. User management. -> .prizm-docs/users.prizm
+
+Tags are optional, enclosed in square brackets after the module name. They contain lowercase keywords that describe the module's domain concepts. AI matches user requirement descriptions against tags to identify relevant modules before loading L1. Tags are auto-generated during Init from module source content (function names, imports, domain terms) and refined during Rebuild.
+
 ## 3.2 L1: module.prizm (Structural Index)
 
 TEMPLATE:
@@ -582,7 +612,7 @@ STEPS:
 
 4. GENERATE_ROOT (L0):
    Fill: PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY from step 1
-   Build: MODULE_INDEX — list modules at the depth needed for efficient navigation, with arrow pointers
+   Build: MODULE_INDEX (or MODULE_GROUPS if 15+ modules — see Section 3.1) — list modules at the depth needed for efficient navigation, with arrow pointers
    Extract: RULES from existing README, .editorconfig, linter configs
    Extract: PATTERNS from common code patterns observed in step 2
    Extract: CROSS_CUTTING — identify patterns/constraints that span 2+ modules

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

@@ -159,8 +159,10 @@ If the user declines, suggest alternatives:
 ### 2.0 Read Target Workflow
 
 1. **Read the workflow's SKILL.md** from `core/skills/orchestration-skill/workflows/{workflow-type}/SKILL.md`
-2. **Read existing artifacts** to restore context (spec, plan, code diffs, bug descriptions, etc.)
-3. **Read relevant `.prizm-docs/`** — load project context (L0 root, relevant L1)
+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.
+   - 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.
 
 This step replaces the context that was lost when the AI session was interrupted.
 

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

@@ -11,7 +11,7 @@
   "members": [
     {
       "name": "dev",
-      "role": "developer",
+      "role": "developer", 
       "agentDefinition": "prizm-dev-team-dev",
       "prompt": "You are a Dev Agent of the prizm-dev-team. Follow /prizmkit-implement workflow with TDD. Read plan.md/spec.md, implement task-by-task, mark completed tasks [x]. Check .prizm-docs/ TRAPS before implementing.",
       "subscriptions": ["*"]

package/package.json

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