prizmkit 1.1.78 → 1.1.79

package/bundled/skills-windows/prizmkit-prizm-docs/references/op-status.md

@@ -0,0 +1,14 @@
+# Operation: Status — Detailed Steps
+
+Check freshness of all .prizm docs.
+
+PRECONDITION: .prizmkit/prizm-docs/ exists with root.prizm.
+
+STEPS:
+1. Get last git modification time of root.prizm via `git log -1 --format="%ai" -- .prizmkit/prizm-docs/root.prizm`.
+2. Count commits since that time via `git log --since="<timestamp>" --oneline | wc -l`.
+3. For each L1/L2 doc, compare git modification time of the .prizm file (`git log -1 --format="%ai" -- <prizm-file>`) against latest git modification of source files in that module (`git log -1 --format="%ai" -- <module-path>/`).
+4. Classify each doc as: FRESH (prizm file updated after latest source change), STALE (source changed more recently than prizm file), MISSING (module exists but no .prizm doc).
+5. Flag any docs exceeding size limits.
+
+OUTPUT: Freshness report table with columns: DOC_PATH | LEVEL | STATUS | PRIZM_LAST_MOD | SOURCE_LAST_MOD.

package/bundled/skills-windows/prizmkit-prizm-docs/references/op-update.md

@@ -0,0 +1,19 @@
+# Operation: Update — Detailed Steps
+
+Update .prizmkit/prizm-docs/ to reflect recent code changes.
+
+PRECONDITION: .prizmkit/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 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, DECISIONS), 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. Do not write CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths — git tracks history. **Preserve** any `PROJECT_BRIEF:` line in root.prizm — it is managed by prizmkit-init, not by this skill.
+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 with sections: MODULE, FILES, RESPONSIBILITY, INTERFACES, DATA_FLOW, KEY_FILES, DEPENDENCIES, RULES, TRAPS, DECISIONS. 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 with sections: MODULE, FILES, RESPONSIBILITY, INTERFACES, DATA_FLOW, KEY_FILES, DEPENDENCIES, RULES, TRAPS, DECISIONS. This ensures Update fills documentation gaps left by previous sessions.
+7. Enforce size limits: L0 > 4KB -> consolidate. L1 > 4KB -> trim KEY_FILES descriptions, ensure RULES <= 3 entries. L2 > 5KB -> trim non-essential derived detail or split oversized cross-cutting detail.
+7a. Validate memory hygiene: no CHANGELOG/UPDATED fields, no workflow metadata, no L1 behavioral sections.
+8. Stage updated .prizm files via `git add .prizmkit/prizm-docs/`
+
+OUTPUT: List of updated/created/skipped docs with reasons.

package/bundled/skills-windows/prizmkit-prizm-docs/references/op-validate.md

@@ -0,0 +1,17 @@
+# Operation: Validate — Detailed Steps
+
+Check format compliance and consistency of all .prizm docs.
+
+PRECONDITION: .prizmkit/prizm-docs/ exists.
+
+STEPS:
+1. FORMAT CHECK: Verify all .prizm files use KEY: value format. Flag any prose paragraphs, code blocks (```), markdown headers (##), emoji, ASCII art, or horizontal rules. Flag TRAPS entries missing severity prefix ([CRITICAL], [HIGH], or [LOW]). Flag CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, and `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths as auxiliary noise. Note: [REVIEW] preceding severity (e.g., `[REVIEW][HIGH]`) is a valid temporary staleness marker, not a format violation.
+2. SIZE CHECK: Verify size limits: L0 <= 4KB, L1 <= 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 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, changelog/history sections, and workflow metadata.
+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-windows/prizmkit-retrospective/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: "prizmkit-retrospective"
+description: "Incremental .prizmkit/prizm-docs/ maintainer. Performs two jobs: (1) structural sync — update .prizmkit/prizm-docs/ KEY_FILES/INTERFACES/DEPENDENCIES, (2) architecture knowledge — inject TRAPS/RULES/DECISIONS into .prizmkit/prizm-docs/. All project knowledge lives in .prizmkit/prizm-docs/ . Run after code review passes and before committing. Trigger on: 'retrospective', 'retro', 'update docs', 'sync docs', 'wrap up', 'done with feature', 'feature complete'. (project)"
+---
+
+# PrizmKit Retrospective
+
+| Store | Location | Content | Purpose |
+|-------|----------|---------|---------|
+| **Architecture Index** | `.prizmkit/prizm-docs/` | MODULE, FILES, INTERFACES, DEPENDENCIES, TRAPS, RULES, DECISIONS | AI quickly locates code structure, interfaces, known pitfalls, and key design decisions |
+
+**This skill handles both structural sync and knowledge injection in one pass:**
+
+1. **Structural Sync** — reflect what changed in code → `.prizmkit/prizm-docs/` (KEY_FILES, INTERFACES, DEPENDENCIES, file counts)
+2. **Architecture Knowledge** — inject TRAPS, RULES, and DECISIONS → `.prizmkit/prizm-docs/`
+
+For initial doc setup, validation, or migration, use `/prizmkit-prizm-docs` instead.
+
+## When to Use
+
+- **Before every commit** (mandatory in pipeline) — ensures docs and code are in sync
+- After completing a feature, refactoring, or bug fix
+- After code review passes
+- User says "retrospective", "retro", "update docs", "sync docs", "wrap up"
+
+## Input
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `artifact_dir` | No | Directory containing spec.md, plan.md, review-report.md. If omitted, scan `.prizmkit/` subdirectories for the most recently modified directory with a `plan.md`. If no artifact directory found, run in standalone mode (structural sync only from `git diff`). |
+
+## When NOT to Use
+
+- Only comments, whitespace, or formatting changed — no structural/knowledge change
+- Only test files changed — no module-level impact
+- Only .prizm files changed — avoid circular updates
+
+---
+
+### Job 1: Structural Sync (always runs)
+Synchronize `.prizmkit/prizm-docs/` structure with actual codebase changes from this session.
+→ Read `${SKILL_DIR}/references/structural-sync-steps.md` for the detailed procedure.
+
+**Key outputs**: Synced L1 file counts, L2 INTERFACES/DATA_FLOW, DEPENDENCIES, and stale TRAPS cleanup.
+
+**Memory hygiene**: `.prizmkit/prizm-docs/` must not contain CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths. Convert artifact-scoped wording into durable product/domain language before writing.
+
+---
+
+### Job 2: Knowledge Injection (conditional)
+Inject newly discovered project knowledge (TRAPS, RULES, DECISIONS) into architecture docs.
+→ Read `${SKILL_DIR}/references/knowledge-injection-steps.md` for the detailed procedure.
+
+**Review gate**: Before running Job 2, check `review-report.md` in the artifact directory for the `## Verdict:` line:
+- Verdict is `PASS` → proceed
+- Verdict is `NEEDS_FIXES` → **skip Job 2** — do not inject knowledge for code that hasn't passed review. Output warning: "Review report has unresolved findings. Skipping knowledge injection."
+- No `review-report.md` found → proceed with warning
+- No artifact directory (standalone mode) → skip Job 2, only Job 1 runs
+
+**Skip for**: pure refactors (no behavioral change).
+
+**Bug Fix Documentation Policy**:
+- DEFAULT for bug fixes: Run Job 1 (structural sync) only. Skip Job 2 (knowledge injection).
+- RUN Job 2 when the bug fix causes any of:
+  • Interface signature changes
+  • Dependency additions/removals
+  • Observable behavior changes to existing features
+  • Newly discovered TRAPs (gotchas/pitfalls)
+- When any of the above apply, run full retrospective (Job 1 + Job 2).
+
+**Key outputs**: New TRAPS entries, RULES updates, DECISIONS records in relevant L1/L2 docs and root.prizm.
+
+---
+
+## Final: Stage
+
+**3a.** Stage all doc changes:
+```powershell
+git add .prizmkit/prizm-docs/
+```
+
+**HANDOFF:** `/prizmkit-committer`
+
+## Output
+
+- `.prizmkit/prizm-docs/*.prizm` — Structurally synced + TRAPS/RULES/DECISIONS enriched
+- All `.prizmkit/prizm-docs/` changes staged via `git add`

package/bundled/skills-windows/prizmkit-retrospective/references/knowledge-injection-steps.md

@@ -0,0 +1,50 @@
+# 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
+- `review-report.md` in the artifact directory — read the findings and fix instructions. If this file exists, use it as a source for pre-categorized decisions and findings.
+- `plan.md` in the artifact directory — read planned vs actual
+- Any companion documents in the artifact directory (e.g., `refactor-analysis.md`, `fix-report.md`) — read what was discovered
+- The relevant `.prizmkit/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.
+
+**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 `.prizmkit/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.
+
+**MEMORY HYGIENE GATE**: Before writing any `.prizmkit/prizm-docs/` entry, remove or translate workflow metadata. Never write CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths. If source artifacts say "fixed in B-001" or "implemented in F-003", write only the durable product/domain fact.
+
+**2c.** Inject into the correct `.prizmkit/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-windows/prizmkit-retrospective/references/structural-sync-steps.md

@@ -0,0 +1,43 @@
+# Structural Sync — Detailed Steps
+
+**1a.** Get changed files (staged + unstaged vs HEAD):
+```powershell
+git diff HEAD --name-status
+```
+
+**1b.** Read `.prizmkit/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 **only the sections affected by the diff files in this module**. For example, if only `api.js` changed: update its KEY_FILES entry, its INTERFACES (if exports changed), its DEPENDENCIES (if imports changed). Do NOT re-scan unchanged files in the module. 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 with these sections: MODULE, FILES, RESPONSIBILITY, INTERFACES, DATA_FLOW, KEY_FILES, DEPENDENCIES, RULES, TRAPS, DECISIONS. Populate **only from the diff files** (the Added/Modified files in this module from step 1a), not from the entire module directory.
+- **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). **Preserve** any `PROJECT_BRIEF:` line — it is managed by prizmkit-init.
+
+**Memory hygiene**: During L0/L1/L2 updates, do not write CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths. Update durable sections in place; git history is the change log.
+
+**1e.** If new directory qualifies as a module and matches no existing module:
+- A directory qualifies as a module if any of: contains source files forming a logical unit, contains entry/config/interface files, contains qualifying sub-modules, or is referenced by multiple modules as dependency.
+- Create L1 doc immediately, add to MODULE_INDEX.
+- If the current diff includes Added or Modified source files with meaningful logic → create L2 immediately. Otherwise defer L2.
+
+**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 → trim non-essential detail, split oversized cross-cutting detail, or move derived context back to source references
+
+**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):
+
+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 `Get-ChildItem`) → delete the TRAP entry
+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>$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.

package/bundled/skills-windows/prizmkit-test/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: "prizmkit-test"
+description: "Full-stack test generation and orchestration. Detects architecture, discovers/runs existing tests, analyzes coverage gaps, generates missing tests (unit/integration/E2E), outputs unified report. Use after completing development to verify quality before deploy. Trigger on: 'test', 'run tests', 'check quality', 'verify code', 'generate tests', 'test coverage', 'fill test gaps', 'quality check', '测试', '验证', '跑测试', '补测试'. (project)"
+---
+
+# PrizmKit Test
+
+A comprehensive test generation and orchestration skill. Discovers existing tests, runs them, compares coverage against spec acceptance criteria and module interfaces, generates missing tests at three levels (unit → integration → E2E), and produces a unified report.
+
+### When to Use
+- After completing one or more features/refactors/bugfixes
+- As a quality gate before deploy
+- Project has a test framework installed but zero tests written (first-time test generation)
+- User says "test", "run tests", "verify", "check quality", "补测试"
+
+### When NOT to Use
+- Project has no test framework AND no code to test
+- Trivial single-line config changes
+
+## Precondition
+
+| Required State | Check | If Missing |
+|---|---|---|
+| `.prizmkit/prizm-docs/root.prizm` exists | File exists | Run `/prizmkit-init` first |
+| Test framework installed | Dependency in package.json or equivalent | Offer to skip or let user install one manually |
+
+If `.prizmkit/prizm-docs/` exists but may be stale (no retrospective run after recent changes), warn user: "Prizm docs may be out of date. Gap analysis accuracy depends on current docs. Continue anyway?"
+
+## Context Loading
+
+Before execution, load context once:
+
+1. **Architecture context**: Read `.prizmkit/prizm-docs/root.prizm` (L0 — project overview, module index, tech stack, conventions) and relevant L1 docs for modules in scope. If scope includes specific modules, also load relevant L2 docs for INTERFACES, DATA_FLOW, TRAPS, and DECISIONS.
+2. **Project config**: Read `.prizmkit/config.json` (tech stack, AI CLI config).
+3. **Dependencies**: Read `package.json` or equivalent to detect test framework and project type.
+
+## Input
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `scope` | No | User selects interactively in Phase 1. In headless mode, defaults to full project. |
+
+## Execution
+
+### Phase 0: Architecture Detection
+
+1. From context already loaded, classify project type:
+
+| Signal | Classification |
+|--------|---------------|
+| react/vue/angular/next in deps, no backend framework | Frontend |
+| express/fastify/django/flask in deps, no frontend framework | Backend |
+| Both present | Fullstack |
+| Neither clear | Ask user (headless: mark as "unknown", skip E2E) |
+
+2. Detect test framework by scanning dependencies:
+   - Jest → `npx jest` or `npm test`
+   - Vitest → `npx vitest run`
+   - pytest → `python -m pytest`
+   - Go testing → `go test ./...`
+   - Multiple frameworks found → use the one with the most test files; list all in report
+   - Custom `npm test` script → use `npm test`
+
+3. **Interactive mode**: Show "Detected: {type}, test framework: {name}. Correct?"
+   **Headless mode**: Auto-proceed with detected values, note assumptions in report.
+
+### Phase 1: Scope Selection
+
+**Interactive mode** — present three options:
+
+1. **Full project** — all modules, all specs in `.prizmkit/specs/`
+2. **Single module** — pick from L1 doc module names (e.g., "auth", "payment")
+3. **Single feature** — pick from `.prizmkit/specs/###-*/` directories
+
+**Headless mode** — default to full project. If `artifact_dir` or `scope` was passed by the caller, use that.
+
+### Phase 2: Run Existing Tests
+
+1. Find test directories matching common patterns: `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`. If no test files exist at all, note this and skip to Phase 3 (all coverage is "missing").
+
+2. Run the detected test command in scope. Capture:
+   - Pass/fail counts and failed test details
+   - Which test files exist (for gap analysis)
+   - Raw output (saved to report directory)
+
+3. If existing tests fail: record failures but continue — this is coverage data. Do not attempt to fix pre-existing test failures (they predate this session).
+
+### Phase 3: Coverage Gap Analysis
+
+Staleness of `.prizmkit/prizm-docs/` was already checked during Context Loading (see Precondition). Gap analysis proceeds with the available data.
+
+Compare what exists against what should exist, across three levels:
+
+**Unit test gaps** — for each module in scope:
+- Read the corresponding L2 `.prizm` doc INTERFACES section to get exported functions/classes. If no L2 doc exists for a module, analyze source files directly to identify exported functions/classes.
+- Check if each has a corresponding test file (match project's test naming: `foo.test.ts`, `foo.spec.ts`, `test_foo.py`)
+- Flag uncovered interfaces
+
+**Integration test gaps** (skip if project has no API/DB layer — pure library/CLI tool):
+- Read L1 doc DEPENDENCIES section for cross-module interactions
+- Check if tests exist covering module boundaries, API endpoints, DB operations
+- Flag missing integration coverage
+
+**E2E test gaps** (skip if project has no UI):
+- Collect acceptance criteria from all spec.md files in scope
+- Check existing E2E test files against these criteria
+- Flag uncovered criteria
+
+### Phase 4: Generate Missing Tests
+
+Generate tests in priority order: unit → integration → E2E. After each batch, run immediately.
+
+When generated tests fail, distinguish two cases:
+- **Test bug** (syntax error, wrong import, wrong mock, wrong framework API usage) → fix the test and re-run
+- **Assertion failure** (test is valid but code returns unexpected result) → mark as "needs review" in report; do NOT modify production code. This is a potential bug discovered by the generated test.
+
+If a test fails repeatedly after 2 fix attempts, skip it and mark as "unresolved" in the report.
+
+**4a. Unit Tests (always applicable)**
+
+For each uncovered interface:
+- Read the source file to understand function signature and logic
+- Generate test file matching project conventions (framework, naming, directory, import style, mock/fixture patterns)
+- Common naming patterns to match:
+  - `src/foo.ts` → `src/__tests__/foo.test.ts` or `src/foo.spec.ts` or `tests/foo_test.py`
+  - Mirror the existing pattern; if no tests exist, use the framework's default convention
+- Cover: happy path, edge cases (null/undefined/empty), error conditions, boundary values
+- Do NOT test framework internals or third-party library behavior
+- Run tests immediately after generating
+
+**4b. Integration Tests**
+
+For each module with dependencies:
+- Generate tests for the module's primary interface exercising its real dependencies
+- If API endpoints exist: request/response tests (valid input, invalid input, missing params, auth)
+- If database operations exist: CRUD tests using the project's existing test database config
+- Run tests immediately after generating
+
+**4c. E2E Tests (conditional)**
+
+Preconditions (ALL must be met):
+- Playwright is available (`@playwright/test` or `playwright` in package.json dependencies, or `npx playwright --version` succeeds as fallback)
+- Playwright browsers are installed (check `npx playwright install --dry-run 2>/dev/null` exits cleanly, or `node_modules/.cache/ms-playwright/` directory exists; if missing, warn in report and skip E2E)
+- Project has a UI layer
+- Project can be started (start/dev script in package.json)
+- Acceptance criteria exist in spec.md files
+
+If ALL met:
+- **Before starting dev server**: detect whether it's already running: (1) check `package.json` scripts for port flags (`--port`, `-p`, `PORT=`), (2) fall back to framework defaults (3000 for React/Next/Express, 5173 for Vite, 8000 for Django, 5000 for Flask), (3) if still unknown, ask the user. Use the detected port in `lsof -i :<port>` to check. If running, tell user: "Dev server appears to be already running on port {N}. Use this running instance for E2E tests?" If user confirms, use existing instance. If user declines, skip E2E.
+- Start the project dev server (only if not already running). Wait for it to be ready.
+- For each uncovered acceptance criterion, generate a Playwright test script
+- Run generated E2E tests, capture screenshots of failures
+- **Only stop dev server if you started it.** Never stop a server that was already running.
+
+If NOT met:
+- Note what was skipped and why in the report
+- If only the server wasn't startable: still generate E2E script files but mark as "not run — manual execution needed"
+
+### Phase 5: Unified Report
+
+Create `.prizmkit/test/{YYYY_MM_DD_HH_MM_SS}_testresult/` directory.
+
+**test-report.md** format:
+
+```markdown
+# Test Report — {timestamp}
+
+## Summary
+- Scope: {full / module: name / feature: ###-name}
+- Architecture: {frontend / backend / fullstack}
+- Test framework: {name}
+- Mode: {interactive / headless}
+
+## Existing Tests
+- Total: {N} | Passed: {N} | Failed: {N}
+{failed test details or "All passing"}
+{or "No existing tests found — generated first batch"}
+
+## Coverage Gaps Found
+| Module | Interface | Type | Status |
+|--------|-----------|------|--------|
+| ... | ... | unit/integration/e2e | covered / generated / needs-review / unresolved / skipped |
+
+## Generated Tests
+- Unit: {N} generated, {N} needs-review, {N} unresolved
+- Integration: {N} generated, {N} needs-review, {N} unresolved
+- E2E: {N} generated, {N} skipped ({reason})
+
+## Final Status
+- All tests passing: {yes / no}
+- Needs human review: {list of tests marked needs-review}
+{remaining failures if any}
+```
+
+Also save:
+- `existing-test-output.txt` — raw output from Phase 2
+- `generated-tests/` — copies of all generated test files
+- `e2e-output/` — E2E logs and failure screenshots (if applicable)
+
+## Output
+
+- Test report: `.prizmkit/test/{timestamp}_testresult/test-report.md`
+- Generated test files written to project test directories
+- Existing test output, generated test copies, and E2E artifacts in the report directory
+
+## Recovery
+
+If the session is interrupted:
+- Check `.prizmkit/test/` for the most recent report directory — it contains what was completed before interruption
+- Re-run `/prizmkit-test` — it starts fresh, but Phase 2 will skip tests that already pass, and Phase 3 will re-evaluate gaps
+
+## Examples
+
+### Example 1: Full-Project Quality Check with Test Generation
+
+**User**: `/prizmkit-test`
+
+**Phase 0 — Architecture Detection**:
+```
+Detected: Fullstack (React + Express)
+Test framework: Vitest (7 existing test files)
+```
+
+**Phase 1 — Scope Selection** (user selects option 1):
+```
+Scope: Full project (all modules, all specs)
+```
+
+**Phase 2 — Existing Tests**: 7 test files found, 20 tests run, 18 passed, 2 pre-existing failures (recorded, not fixed).
+
+**Phase 3 — Gap Analysis** (excerpt):
+| Module | Interface | Type | Status |
+|--------|-----------|------|--------|
+| auth | login() | unit | missing |
+| auth | register() | unit | missing |
+| payment | processPayment() | unit | missing |
+| payment | api/checkout | integration | missing |
+| — | Checkout flow | e2e | missing |
+
+**Phase 4**: Generated 5 unit tests (3 passing, 2 assertion failures marked "needs-review"), 1 integration test (passing), 1 E2E test (passing).
+
+**Phase 5 — Report Summary**:
+```
+Generated: 5 unit (2 needs-review), 1 integration, 1 E2E
+Report: .prizmkit/test/2026_05_23_14_30_00_testresult/test-report.md
+Needs human review: processPayment (returns 400 for negative amounts, expected 422), refund (missing authorization header causes 500 instead of 401)
+```
+
+### Example 2: Single-Feature Targeted Test
+
+**User**: `/prizmkit-test`
+
+**Phase 0 — Architecture Detection**:
+```
+Detected: Backend (Express)
+Test framework: Vitest
+```
+
+**Phase 1 — Scope Selection** (user selects option 3, then picks "042-payment-gateway"):
+```
+Scope: Single feature — 042-payment-gateway
+Test files in scope: 2
+
+**Phase 2 — Existing Tests**: 2 test files, 8 tests, all passing.
+
+**Phase 3 — Gap Analysis** (excerpt):
+| Module | Interface | Type | Status |
+|--------|-----------|------|--------|
+| payment | processPayment() | unit | missing |
+| payment | refund() | unit | missing |
+
+**Phase 4**: Generated 2 unit tests (both passing). No integration/E2E applicable for this scope.
+
+**Phase 5 — Report Summary**:
+```
+Generated: 2 unit tests (all passing)
+Report: .prizmkit/test/2026_05_23_15_00_00_testresult/test-report.md
+All tests passing. Ready for commit.
+```
+
+**HANDOFF:** Independent skill — no handoff. User may proceed to `/prizmkit-committer` if all tests pass, or fix issues manually if tests are marked "needs-review".

package/package.json

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