prizmkit 1.1.3 → 1.1.5

package/bundled/skills/prizmkit-plan/references/clarify-guide.md

@@ -0,0 +1,67 @@
+# Clarification Phase — Execution Guide
+
+Invoked automatically during `/prizmkit-plan` Phase 0 (specify) when `[NEEDS CLARIFICATION]` markers exist, or during Phase 1 (design) when data model ambiguities arise.
+
+---
+
+## Question Strategy
+
+**Ask one question at a time.** Batching questions produces lower-quality answers.
+
+For each question:
+1. Cite the exact location in spec.md (e.g., "§3.2 says...")
+2. State what is ambiguous and why it matters for implementation
+3. Provide a **recommended answer** with rationale — gives the user a concrete starting point to accept, modify, or reject
+
+**Prioritize by implementation impact** (highest first):
+1. Data model (entities, relationships, field types, constraints, naming) — **hardest to change after code is written**
+2. Functional scope boundaries
+3. UX flow and error handling
+4. Non-functional requirements (performance, security)
+5. Edge cases and integration points
+
+## Update Discipline
+
+After **each** user answer:
+- Immediately update `spec.md` (do not batch at the end)
+- Remove the resolved `[NEEDS CLARIFICATION]` marker
+- Re-evaluate for new ambiguities exposed by the answer
+
+## No Limits Policy
+
+**There is no cap on rounds or questions.** Keep asking until:
+- All `[NEEDS CLARIFICATION]` markers are removed, AND
+- No vague or underspecified areas remain, AND
+- You are fully confident about the requirements
+
+If the user's answer raises new questions — ask those too. If a previously-resolved item needs revisiting due to new context — go back.
+
+## Early Termination
+
+If the user says "done", "stop", or "enough" — end immediately and output a summary of:
+- What was resolved
+- What remains unclear (list any open `[NEEDS CLARIFICATION]` items)
+
+## Example Exchange
+
+**Question:**
+> §3.2 says "User can upload files" but doesn't specify file types or size limits.
+>
+> **Recommended:** Accept JPEG, PNG, PDF up to 10MB — covers common use cases without straining storage.
+>
+> Do you agree, or different constraints?
+
+**User:** "Also allow SVG, make it 25MB"
+
+**Action:** Update spec.md §3.2 → `File upload: JPEG, PNG, PDF, SVG. Max 25MB per file.` Remove marker.
+
+**Follow-up question triggered by answer:**
+> SVGs can contain embedded scripts (XSS risk). Should uploaded SVGs be sanitized (strip `<script>` + event handlers), or restricted to trusted users only?
+>
+> **Recommended:** Sanitize all SVG uploads — allows all users to upload safely.
+
+## Guidelines
+
+- Stay at WHAT/WHY level — no implementation details (HOW) in spec
+- If an answer contradicts an existing requirement, surface the conflict and ask which takes precedence
+- If the user seems fatigued: "I have N more questions — continue now or later?" — but never silently stop with unresolved ambiguities

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/prizmkit-retrospective/references/knowledge-injection-steps.md

@@ -0,0 +1,49 @@
+# Knowledge Injection — Detailed Steps (2a–2c)
+
+**2a.** Gather context — read the **actual code that was changed** plus any available artifacts:
+
+- `git diff HEAD` — the real source of truth for what happened
+- `.prizmkit/specs/###-feature-name/context-snapshot.md` — read the '## Implementation Log' section (Dev's changes, decisions, discoveries) and '## Review Notes' section (Reviewer's findings). These are the **preferred source** for pre-categorized decisions and findings. If these sections exist, prefer them over re-extracting from git diff.
+- `.prizmkit/specs/###-feature-name/plan.md` — if feature work, read planned vs actual
+- `.prizmkit/bugfix/<id>/fix-report.md` — if bugfix, read what was discovered
+- `.prizmkit/specs/###-feature-name/failure-log.md` — if a previous session failed, read DISCOVERED_TRAPS. These are high-value TRAPS because they come from actual failures — prioritize injecting them into `.prizm-docs/`
+- 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:
+- 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
+
+**DECISIONS** — key design choices that affect future development:
+- Format: `- <what was decided> — <rationale>`
+- Source: non-obvious design choices, interface conventions, cross-module contracts
+- Only record decisions that a future AI session would benefit from knowing
+- Do NOT record obvious implementation details that can be derived by reading the code
+
+**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. 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` (respect the current format — MODULE_INDEX or MODULE_GROUPS — do not convert between them during injection)
+- Cross-module concerns spanning 2+ modules → `root.prizm` CROSS_CUTTING section
+
+**RULE**: Only add genuinely new information. Never duplicate existing entries. Never rewrite entire files.

package/bundled/skills/prizmkit-retrospective/references/structural-sync-steps.md

@@ -0,0 +1,63 @@
+# Structural Sync — Detailed Steps (1a–1g)
+
+**1a.** Get changed files:
+```bash
+git diff --cached --name-status
+```
+If nothing staged, fallback:
+```bash
+git diff --name-status
+```
+
+**1b.** Read `.prizm-docs/root.prizm` to get MODULE_INDEX (or MODULE_GROUPS). Map each changed file to its module.
+
+**1c.** Classify changes:
+- `A` (added) → add to KEY_FILES, check for new INTERFACES
+- `D` (deleted) → remove from KEY_FILES, update FILE count
+- `M` (modified) → check if public interfaces or dependencies changed
+- `R` (renamed) → update all path references
+
+**1d.** Update affected docs (bottom-up: L2 → L1 → L0):
+
+- **L2**: If L2 exists → update KEY_FILES, INTERFACES, DATA_FLOW, DEPENDENCIES, CHANGELOG, TRAPS, DECISIONS. If L2 does NOT exist AND the module has Added or Modified source files in the current diff with meaningful logic (not trivial config) → create L2 using the L2 GENERATION TEMPLATE, then populate from source.
+- **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:
+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 → if using MODULE_INDEX with > 15 entries, convert to MODULE_GROUPS format (group by functional domain). Otherwise, consolidate MODULE_INDEX descriptions.
+- L1 > 4KB → trim KEY_FILES descriptions, ensure RULES <= 3 entries
+- L2 > 5KB → archive old CHANGELOG entries
+
+**SKIP structural sync if**: only internal implementation changed (no interface/dependency impact), only comments/whitespace, only .prizm files. **DO NOT skip** test file changes or bug fixes — they may reveal TRAPS worth capturing in L2.
+
+**1g. TRAPS staleness check** (only when an L2 doc's TRAPS section has > 10 entries):
+
+(Note: `/prizmkit-prizm-docs` Validate uses a lower threshold of > 8 entries to flag TRAPS needing staleness metadata. This step uses > 10 because it performs actual cleanup, which is more expensive. Validate warns early; this step acts later.)
+
+Perform a quick staleness scan on existing TRAPS to prevent unbounded accumulation:
+1. If a TRAP has `STALE_IF:` and the glob-matched files no longer exist (verified via `ls`) → delete the TRAP entry, append CHANGELOG: `remove: archived stale TRAP - <summary>`
+2. If a TRAP has `REF:` → check if the referenced file still exists and the REF commit is less than 180 days old (via `git log --since="180 days ago" <hash> 2>/dev/null`). If the file is deleted OR the REF commit is older than 180 days → prepend `[REVIEW]` to the severity, signaling it needs verification during the next retrospective Job 2
+3. Process at most 5 of the oldest TRAPS per L2 doc per session (to bound context cost)
+
+This step is lightweight — it only triggers when TRAPS exceed 10 entries, and processes at most 5 per run.
+
+**1h. Periodic full TRAPS audit** (runs approximately once every 10 retrospective sessions):
+
+Check `.prizm-docs/changelog.prizm` for the marker `audit: traps-audit full-scan`. If the marker does not exist, OR the most recent `audit: traps-audit full-scan` entry has 10+ other changelog entries after it:
+
+1. Scan ALL L2 `.prizm` files (not just ones touched this session)
+2. For each L2 doc with TRAPS entries:
+   - Verify referenced file paths still exist (via `ls`)
+   - If `STALE_IF:` glob matches zero files → delete the TRAP, append CHANGELOG: `remove: archived stale TRAP - <summary>`
+   - If `REF:` commit is older than 180 days AND the referenced file was significantly refactored (>50% lines changed since REF commit) → prepend `[REVIEW]`
+3. Process at most 3 TRAPS per L2 doc to bound context cost (total max ~15 TRAPS per audit)
+4. Append to `.prizm-docs/changelog.prizm`: `- root | audit: traps-audit full-scan — checked N docs, removed M stale, marked K for review`
+
+This is a lightweight background pass. If the project has fewer than 5 L2 docs, skip this step (not enough accumulation to warrant auditing).

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

@@ -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.5",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {