prizmkit 1.1.111 → 1.1.113

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

@@ -1,43 +1,95 @@
 # Structural Sync — Detailed Steps
 
-**1a.** Get changed files (staged + unstaged vs HEAD):
+## 1. Get changed files
+
+Get changed files from staged and unstaged changes relative to HEAD:
+
 ```bash
 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.
+If the caller supplied an explicit file list, use that list instead and note the source in the report.
+
+## 2. Map files to modules
+
+Read `.prizmkit/prizm-docs/root.prizm` and map each changed file to MODULE_INDEX or MODULE_GROUPS entries.
+
+If a changed source file maps to no module, evaluate whether its directory qualifies as a new module:
+
+- Contains source files forming a logical unit
+- Contains entry/config/interface files
+- Contains qualifying submodules
+- Is referenced by multiple modules as a dependency
+
+## 3. Classify changes
+
+- `A` added → add to KEY_FILES and check for new public interfaces
+- `D` deleted → remove from KEY_FILES and update file counts
+- `M` modified → check public interfaces, dependencies, data flow, and durable traps/decisions
+- `R` renamed → update path references
+
+## 4. Decide whether sync is needed
+
+Skip structural sync when changes are limited to:
+
+- comments, whitespace, or formatting
+- `.prizm` files only
+- internal implementation details with no interface, dependency, data-flow, or module mapping impact
+- test-only changes that reveal no durable boundaries, traps, interface constraints, behavior rules, or regression knowledge
+
+Do not skip automatically just because the task is a bug fix or test change. Run the relevant part of retrospective when the change affects structure, interfaces, dependencies, observable behavior, or durable knowledge.
+
+## 5. Update affected docs bottom-up
+
+### L2
+
+If L2 exists, update only sections affected by changed files in that module.
+
+If L2 does not exist and the current diff includes Added or Modified source files with meaningful logic, create L2 with:
+
+```text
+MODULE
+FILES
+RESPONSIBILITY
+KEY_FILES
+DEPENDENCIES
+INTERFACES
+TRAPS
+```
+
+Add DATA_FLOW, RULES, or DECISIONS only when the changed files provide durable information for those sections. Populate from the diff files and targeted source reads, not from an unbounded full-module rescan.
+
+### L1
+
+Update FILES count, KEY_FILES, SUBDIRS, and DEPENDENCIES when module-level structure changes.
+
+L1 does not contain INTERFACES, DATA_FLOW, TRAPS, or DECISIONS; those belong in L2.
+
+### L0
+
+Update MODULE_INDEX or MODULE_GROUPS only when module structure changed. Preserve any `PROJECT_BRIEF:` line because it is managed by `/prizmkit-init`.
 
-**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
+## 6. New module handling
 
-**1d.** Update affected docs (bottom-up: L2 → L1 → L0):
+If a new directory qualifies as a module and matches no existing module:
 
-- **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.
+1. Create L1 immediately.
+2. Add it to MODULE_INDEX or MODULE_GROUPS.
+3. Create L2 only when the current diff includes meaningful Added or Modified source files for the module.
 
-**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.
+## 7. Size limits
 
-**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.
+- L0 > 4KB → consolidate MODULE_INDEX or convert to MODULE_GROUPS when module count is high
+- L1 > 4KB → trim KEY_FILES descriptions and keep RULES concise
+- L2 > 5KB → remove derived detail or stale entries; keep durable knowledge only
 
-**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
+## 8. TRAPS staleness check
 
-**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.
+Run only when an L2 doc's TRAPS section has more than 10 entries.
 
-**1g. TRAPS staleness check** (only when an L2 doc's TRAPS section has > 10 entries):
+Process at most 5 oldest TRAPS per L2 doc:
 
-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
-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)
+1. If a TRAP has `STALE_IF:` and matched files no longer exist, delete the TRAP.
+2. If a TRAP has `REF:` and the referenced file is gone or the commit is older than the review horizon, mark it `[REVIEW]` for the next knowledge pass.
 
-This step is lightweight — it only triggers when TRAPS exceed 10 entries, and processes at most 5 per run.
+This bounds context cost and prevents unbounded trap accumulation.

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

@@ -1,204 +1,199 @@
 ---
 name: "prizmkit-test"
-description: "Full-stack test generation and orchestration. Detects architecture, discovers/runs existing tests, analyzes coverage gaps, generates missing unit/integration/E2E tests including business-specific boundary cases, validates every interface with a required boundary coverage matrix, and outputs a 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', 'boundary tests', 'edge cases', 'quality check', 'add tests'. (project)"
+description: "Risk-triggered full-stack test generation and orchestration. Detects architecture, runs existing tests, analyzes coverage gaps, generates missing unit/integration/E2E tests, validates boundary coverage, and writes a unified report. Use after development when behavior, public interfaces, data models, security/permission/payment logic, deployment readiness, or user-requested quality verification warrants testing. Supports full-project, module, feature selection, and generic change-artifact `scope=this-change`. Trigger on: 'test', 'run tests', 'verify code', 'quality check', 'test coverage', 'boundary tests', 'edge cases', 'add tests'. (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), verifies business-specific boundary coverage for every in-scope interface, and produces a unified report.
+A risk-triggered test generation and orchestration skill. It discovers existing tests, runs them, compares coverage against project interfaces and task acceptance criteria, generates missing tests, validates business-specific boundary coverage, and produces a unified report.
+
+`/prizmkit-test` is not mandatory for every lifecycle path. Run it when risk or user intent warrants verification.
 
 ### 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", "add tests"
+- Behavior changes that need verification
+- Public API/interface changes
+- Data model, schema, migration, persistence, or serialization changes
+- Security, permission, authentication, payment, billing, entitlement, or ownership logic
+- Deployment readiness checks
+- First-time test generation for a project with a test framework
+- User says "test", "run tests", "verify", "quality check", "add tests", or asks about coverage/boundaries
 
 ### When NOT to Use
-- Project has no test framework AND no code to test
-- Trivial single-line config changes
+- Pure documentation edits
+- Formatting-only changes
+- Internal renames with no behavior impact
+- Tiny config tweaks with no runtime behavior change
+- Project has no test framework and no code to test
 
 ## 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 |
+| Test framework installed | Dependency in package.json or equivalent | Offer to skip, install manually, or generate a plan to add tests |
+
+If Prizm docs may be stale, warn that gap analysis accuracy depends on current docs. Continue only if the user accepts the risk or the run uses explicit changed files.
+
+## Scope Model
+
+| Scope | Meaning |
+|---|---|
+| `full-project` | Analyze and test the whole project. |
+| `module:<name>` | Analyze one module from Prizm docs. |
+| `feature:<slug>` | Interactive selection of a historical feature/spec directory. |
+| `this-change` | Analyze the current change artifact and changed files only. |
 
-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?"
+A **change artifact** is any artifact directory containing `spec.md` + `plan.md`, regardless of whether the work is a feature, bug fix, refactor, or migration. `scope=this-change` is not feature-only.
+
+Compatibility guard: Do not automatically apply `scope=this-change` to `.prizmkit/bugfix/<BUG_ID>/` or `.prizmkit/refactor/<REFACTOR_ID>/` by directory name alone. Treat those directories as change artifacts only when the caller provides `artifact_dir` and the directory contains `spec.md` + `plan.md` plus a changed-files source.
 
 ## 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.
-
-For `scope=this-change`, load only:
-- `.prizmkit/prizm-docs/root.prizm`
-- relevant L1/L2 docs inferred from in-scope changed files
-- `artifact_dir/spec.md`
-- `artifact_dir/plan.md`
-- `artifact_dir/context-snapshot.md` if present
-- `artifact_dir/review-report.md` if present
-- changed source files and directly related existing tests
+1. Architecture context: `root.prizm`, relevant L1 docs, and relevant L2 docs when scope requires interface or boundary detail.
+2. Project config: `.prizmkit/config.json` if present.
+3. Dependency manifest: `package.json`, `pyproject.toml`, `requirements.txt`, `go.mod`, or equivalent.
+4. For `scope=this-change`:
+   - `artifact_dir/spec.md`
+   - `artifact_dir/plan.md`
+   - `artifact_dir/context-snapshot.md` if present
+   - `artifact_dir/review-report.md` if present
+   - changed source files and directly related tests
 
-Do not load all modules or all specs merely because they exist.
+Do not load every module or every spec merely because they exist.
 
 ## Input
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `scope` | No | `full-project`, `module:<name>`, `feature:<slug>`, or `this-change`. In headless mode, defaults to `this-change` only when `artifact_dir` points to `.prizmkit/specs/<FEATURE_SLUG>/`; otherwise defaults to full project. |
-| `artifact_dir` | No | Feature artifact directory. For `scope=this-change`, must be `.prizmkit/specs/<FEATURE_SLUG>/`. Do not infer this-change scope from `.prizmkit/bugfix/` or `.prizmkit/refactor/`. |
-| `diff_base` | No | Git ref used to compute changed files for this feature. |
+| `scope` | No | `full-project`, `module:<name>`, `feature:<slug>`, or `this-change`. |
+| `artifact_dir` | No | Change artifact directory. For `scope=this-change`, it must contain `spec.md` and `plan.md`. |
+| `diff_base` | No | Git ref used to compute changed files for this change. |
 | `changed_files` | No | Explicit caller-provided changed file list. Takes precedence over `diff_base`. |
-| `generation_policy` | No | Defaults to `in-scope-only` for `scope=this-change`. Out-of-scope gaps are reported but not generated. |
+| `generation_policy` | No | Defaults to `in-scope-only` for `scope=this-change`; full-project can generate broader coverage. |
+
+Headless default:
+- If `scope=this-change` is provided, require a valid `artifact_dir` with `spec.md` + `plan.md`.
+- If a valid `artifact_dir` is provided without `scope`, treat it as `scope=this-change`.
+- If neither scope nor artifact directory is provided, default 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.
+1. Classify project type from loaded context and dependencies:
+   - Frontend
+   - Backend
+   - Fullstack
+   - Library/CLI
+   - Unknown
+2. Detect test framework:
+   - Jest, Vitest, pytest, Go test, Playwright, or custom `npm test`
+   - If multiple frameworks exist, use the one with the most relevant test files and list all detected frameworks in the report
+3. Interactive mode: show detected architecture/framework and ask for correction when uncertain.
+4. Headless mode: proceed with detected assumptions and record them in the report.
 
 ### Phase 1: Scope Selection
 
-**Interactive mode** — present three options:
+Interactive mode 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
+1. Full project
+2. Single module
+3. Single historical feature/spec directory
+4. Current change artifact when an artifact directory is available
 
-**Headless mode**:
-1. If `scope=this-change`, require `artifact_dir=.prizmkit/specs/<FEATURE_SLUG>/` and run in feature-scoped mode.
-2. If `artifact_dir=.prizmkit/specs/<FEATURE_SLUG>/` is provided without `scope`, treat it as `scope=this-change`.
-3. If `scope=full-project` is explicitly provided, run full-project mode even if an artifact directory exists.
-4. If `artifact_dir` points to `.prizmkit/bugfix/` or `.prizmkit/refactor/`, do not infer `scope=this-change`.
-5. If neither `scope` nor feature `artifact_dir` is provided, default to full project.
+For `scope=this-change`, build the in-scope source set using this priority:
 
-`scope=this-change` is feature-only. It is valid only when `artifact_dir` is under `.prizmkit/specs/<FEATURE_SLUG>/`. Do not automatically apply `scope=this-change` to `.prizmkit/bugfix/<BUG_ID>/` or `.prizmkit/refactor/<REFACTOR_ID>/`. If the caller passes `scope=this-change` with a bugfix/refactor artifact directory, stop and report that this mode is unsupported for that artifact type. Bugfix and refactor workflows keep their existing reproduction-test and behavior-preservation test gates.
+1. `changed_files` parameter
+2. `git diff --name-only <diff_base>`
+3. files/tasks listed in `artifact_dir/plan.md`
+4. file manifest in `artifact_dir/context-snapshot.md`
+5. file/module mapping from `artifact_dir/spec.md`
+
+If no changed file source can be determined for `scope=this-change`, stop with a clear error and ask for `changed_files` or `diff_base`.
 
 ### 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").
+1. Find test files using project conventions: `tests/`, `__tests__/`, `*.test.*`, `*.spec.*`, or language-specific patterns.
+2. Run the detected test command in scope.
+3. Capture pass/fail counts, failed details, and raw output in the report directory.
+4. For `scope=this-change`, classify failures:
+   - In-Scope Failures: changed tests, tests mapped to in-scope source, or acceptance-criteria tests without baseline evidence.
+   - Baseline Failures: unrelated pre-existing failures.
+5. If `scope=this-change` has unexplained In-Scope Failures, final verdict must be `NEEDS_FIXES` or `BLOCKED`.
+
+### Phase 3: Coverage Gap Analysis
 
-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)
+For `scope=this-change`, analyze only:
 
-3. Classify existing test failures before continuing:
-   - For `scope=this-change`, failures in changed tests, tests mapped to in-scope source files, or tests directly covering feature acceptance criteria are `In-Scope Failures` unless a captured pre-feature baseline proves they already failed before this feature.
-   - For `scope=this-change`, unrelated failures are `Baseline Failures`; record them without failing the scoped verdict.
-   - For other scopes, record failures as existing test failures and do not assume they are caused by this test-generation pass.
+- changed/new public interfaces
+- acceptance criteria from the change artifact
+- directly affected integration boundaries
+- directly affected UI/E2E flows
 
-4. If `scope=this-change` has any unexplained `In-Scope Failures`, the final report verdict must be `NEEDS_FIXES` or `BLOCKED`, not `PASS`. Do not hide them as baseline failures.
+Record unrelated historical gaps under `Out of Scope Gaps`; do not generate tests for them and do not fail the verdict because of them.
 
-### Phase 3: Coverage Gap Analysis
+For other scopes, compare existing tests against expected coverage across:
 
-Staleness of `.prizmkit/prizm-docs/` was already checked during Context Loading (see Precondition). Gap analysis proceeds with the available data.
-
-For `scope=this-change`:
-
-1. Build the in-scope source set using this priority:
-   - `changed_files` parameter
-   - `git diff --name-only <diff_base>`
-   - files/tasks listed in `artifact_dir/plan.md`
-   - File Manifest in `artifact_dir/context-snapshot.md`
-   - direct file/module mapping from `artifact_dir/spec.md` acceptance criteria
-2. Build the in-scope test set:
-   - tests already changed in this feature
-   - tests matching in-scope source files by project naming convention
-   - directly affected integration/E2E tests for feature acceptance criteria
-3. Analyze only:
-   - changed/new public interfaces
-   - feature acceptance criteria from `artifact_dir/spec.md`
-   - integration boundaries directly affected by in-scope files
-   - UI/E2E flows directly affected by this feature
-4. For unrelated historical gaps, record them under `Out of Scope Gaps`; do not generate tests and do not fail the feature verdict because of them.
-
-For other scopes, 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
+- Unit tests for exported functions/classes and changed logic
+- Integration tests for module boundaries, API endpoints, DB operations, and external service seams
+- E2E tests for user-visible acceptance criteria when a UI exists
 
 ### Phase 4: Boundary Coverage Matrix
 
-Phase 3 answers "which interfaces are missing tests?" Phase 4 answers "which business boundaries are missing for each interface?" Build this matrix before generating tests so the run does not mistake broad happy-path coverage for real safety coverage.
+Build the **Boundary Coverage Matrix** before generating tests. Happy-path coverage alone is not enough, and the boundary completion gate determines whether coverage is complete.
 
-A path, method, function, or class is not considered covered merely because a happy-path test exists; happy path proves the interface works once, while boundary tests prove it behaves safely under realistic invalid, unauthorized, edge, and failure states.
+Read `${SKILL_DIR}/references/boundary-coverage-protocol.md` for matrix format, category definitions, and completion gate.
 
-Read `${SKILL_DIR}/references/boundary-coverage-protocol.md` for the required matrix format, category definitions, and completion gate. For every in-scope interface and API endpoint, classify applicable categories such as request validation, auth/permission/ownership, domain invariants, collection/pagination, date/time boundaries, state transitions, dependency failures, and response contract checks. In `scope=this-change`, build this matrix only for the in-scope feature interfaces/endpoints; unrelated interfaces belong in `Out of Scope Gaps`.
+For each in-scope interface or endpoint, classify applicable categories such as:
 
-For each category, mark one of:
-- `covered` — an existing test already asserts the boundary behavior
-- `generated` — this run generated and passed the test
-- `needs-review` — a valid generated test found behavior mismatch
-- `skipped` — not applicable, with a concrete reason
+- request validation
+- auth / permission / ownership
+- domain invariants
+- collection / pagination
+- date/time boundaries
+- state transitions
+- dependency failures
+- response contract
 
-If an interface has only happy-path coverage, mark it `boundary-missing` and generate applicable boundary tests in Phase 5. Do not mark happy-path-only coverage as `covered`.
+Mark each category as:
+
+- `covered`
+- `generated`
+- `needs-review`
+- `skipped` with reason
+- `boundary-missing`
 
 ### Phase 5: Generate Missing and Boundary Tests
 
-Read `${SKILL_DIR}/references/test-generation-steps.md` for the detailed generation procedure — boundary-matrix-driven workflow, priority order (unit → integration → E2E), failure handling rules, and generation patterns for each test level.
+Read `${SKILL_DIR}/references/test-generation-steps.md` for detailed generation rules.
 
-When generating unit tests for service-like functions or API/integration tests for endpoints with business-specific behavior, use `${SKILL_DIR}/references/service-boundary-test-catalog.md` via the generation procedure so boundary cases reflect the interface's business responsibility, not only generic null/empty inputs.
+When generating unit tests for service-like functions or API/integration tests with business-specific behavior, use `${SKILL_DIR}/references/service-boundary-test-catalog.md`.
 
-For `scope=this-change`:
-- Generate or update tests only for the in-scope source/test set.
+Rules:
+- Generate tests only for the selected scope.
 - Check for equivalent existing tests before writing new tests.
-- Do not create tests for unrelated modules just because coverage is missing.
-- Do not refactor unrelated tests.
 - Do not modify unrelated production code.
-- Do not expand to full-project coverage unless the user explicitly requested `scope=full-project`.
-- Generated tests must assert real behavior, boundaries, or integration contracts; do not add empty assertions or mock-success-only tests.
+- Do not add empty assertions or mock-success-only tests.
+- If a valid generated test reveals behavior mismatch, mark it `needs-review` rather than changing production code inside this skill.
 
 ### Phase 6: Unified Report and Boundary Validation
 
-Create `.prizmkit/test/{YYYY_MM_DD_HH_MM_SS}_testresult/` directory. Read `${SKILL_DIR}/references/test-report-template.md` for the full report format and artifact list.
+Create `.prizmkit/test/{YYYY_MM_DD_HH_MM_SS}_testresult/` and write `test-report.md` using `${SKILL_DIR}/references/test-report-template.md`.
 
-For `scope=this-change`, the report must include:
-- `## Scope` with mode, artifact dir, diff base, changed-files source, generation policy, in-scope source files, and in-scope test files
-- `## Existing Tests Run`
-- `## Generated / Updated Tests`
-- `## In-Scope Failures`
-- `## Baseline Failures`
-- `## Out of Scope Gaps`
-- `## Verdict` with `PASS`, `NEEDS_FIXES`, or `BLOCKED`
+For `scope=this-change`, include:
 
-`Out of Scope Gaps` are informational only for `scope=this-change`: they must not trigger generated tests and must not fail the verdict.
+- mode, artifact dir, diff base, changed-files source
+- in-scope source and test files
+- existing tests run
+- generated/updated tests
+- in-scope failures
+- baseline failures
+- out-of-scope gaps
+- verdict: `PASS`, `NEEDS_FIXES`, or `BLOCKED`
 
-After writing the report, run the deterministic boundary-report validator when the project has an OpenAPI file or the report contains a Boundary Matrix:
+Run the deterministic boundary-report validator when the project has an OpenAPI file or the report contains a Boundary Matrix:
 
 ```bash
 python3 ${SKILL_DIR}/scripts/validate_boundary_report.py \
@@ -206,22 +201,24 @@ python3 ${SKILL_DIR}/scripts/validate_boundary_report.py \
   --openapi openapi.yaml
 ```
 
-If the project has no OpenAPI file, omit `--openapi`. If validation fails, keep the report but do not claim the run is complete; report that tests may pass while boundary coverage remains incomplete.
+If no OpenAPI file exists, omit `--openapi`. If validation fails, keep the report but do not claim boundary coverage is complete.
 
 ## Output
 
 - Test report: `.prizmkit/test/{timestamp}_testresult/test-report.md`
-- Generated test files written to project test directories
-- Existing test output, generated test copies, E2E artifacts, and boundary validation output in the report directory
+- Generated or updated test files
+- Raw existing-test output, generated-test copies, E2E artifacts, and boundary validation output 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/4 will re-evaluate gaps and boundary coverage
+If interrupted:
+
+- Check `.prizmkit/test/` for the most recent report directory.
+- Re-run `/prizmkit-test`; it starts fresh but can reuse passing tests and existing generated files.
+- Preserve any `needs-review` findings in the next report.
 
 ## Examples
 
-Read `${SKILL_DIR}/references/examples.md` for worked examples of full-project, single-feature, and happy-path-only remediation runs.
+Read `${SKILL_DIR}/references/examples.md` for worked examples of full-project, module, feature selection, and change-artifact runs.
 
-**HANDOFF:** Independent skill — no handoff. User may proceed to `/prizmkit-committer` only if tests pass and the boundary completion gate passes. If tests are marked `needs-review` or boundary validation fails, fix issues manually or run another targeted `/prizmkit-test` pass.
+**HANDOFF:** Independent skill. If tests fail, boundary validation fails, or generated tests are marked `needs-review`, fix issues manually or run another targeted `/prizmkit-test` pass. Proceed to `/prizmkit-committer` only when testing was required and the report verdict allows it.

package/bundled/skills/prizmkit-test/references/boundary-coverage-protocol.md

@@ -4,7 +4,7 @@ Use this protocol during `/prizmkit-test` Phase 4 and update it during Phase 5.
 
 ## Required Boundary Matrix
 
-Build this matrix before writing tests and update it after generated tests pass or produce `needs-review` findings. In `scope=this-change`, build the matrix only for in-scope feature interfaces/endpoints; unrelated interfaces are recorded under `Out of Scope Gaps` and do not trigger generated tests.
+Build this matrix before writing tests and update it after generated tests pass or produce `needs-review` findings. In `scope=this-change`, build the matrix only for interfaces/endpoints in the reviewed change artifact or changed-file set; unrelated interfaces are recorded under `Out of Scope Gaps` and do not trigger generated tests.
 
 | Module | Interface | Service Type | Happy Path | Request Validation | Auth / Permission / Ownership | Domain Invariants | Collection / Pagination | Date / Time | State Transitions | Dependency Failure | Response Contract | N/A Reasons | Final Status |
 |--------|-----------|--------------|------------|--------------------|-------------------------------|-------------------|-------------------------|-------------|-------------------|-------------------|-------------------|-------------|--------------|

package/bundled/skills/prizmkit-test/references/examples.md

@@ -42,9 +42,9 @@ 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
+## Example 2: Single Feature/Spec Targeted Test
 
-This is an interactive single-feature selection. It is different from headless `scope=this-change`, which is driven by `.prizmkit/specs/<FEATURE_SLUG>/` and changed files.
+This is an interactive selection of one existing spec directory. It is different from headless `scope=this-change`, which is driven by a current change artifact plus changed files.
 
 **User**: `/prizmkit-test`
 
@@ -114,27 +114,29 @@ Generate tests for:
 Do not report `user` as covered just because both endpoints have success tests.
 
 
-## Example 3: Feature Pipeline this-change Run
+## Example 4: Change Artifact this-change Run
 
 **Caller**: `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`
 
+For non-feature changes, use the same command shape with any explicit change artifact directory that contains `spec.md` + `plan.md` and has a changed-files source. The `{{FEATURE_SLUG}}` path below is a compatibility example for existing feature artifacts; it does not limit `scope=this-change` to feature work.
+
 **Expected behavior**:
-- Reads `.prizmkit/specs/{{FEATURE_SLUG}}/spec.md`, `plan.md`, and optional `context-snapshot.md`.
-- Builds in-scope files from changed files and feature artifacts.
-- Generates or updates only tests for this feature's changed files, public interfaces, and acceptance criteria.
+- Reads the change artifact's `spec.md`, `plan.md`, and optional `context-snapshot.md`.
+- Builds in-scope files from changed files and the change artifact.
+- Generates or updates only tests for this change's files, public interfaces, and acceptance criteria.
 - Records unrelated historical gaps under `Out of Scope Gaps`.
 - Does not generate tests for unrelated modules.
-- Does not infer this-change mode from `.prizmkit/bugfix/{{BUG_ID}}/` or `.prizmkit/refactor/{{REFACTOR_ID}}/`.
+- The change artifact may represent a feature, bug fix, refactor, migration, or other scoped change.
 
 **Report excerpt**:
 ```markdown
 ## Scope
 - Mode: this-change
-- Artifact Dir: .prizmkit/specs/{{FEATURE_SLUG}}/
+- Artifact Dir: .prizmkit/specs/{{CHANGE_SLUG}}/
 - Generation Policy: in-scope-only
 
 ## Out of Scope Gaps
-- payment: missing legacy tests, but this feature did not change payment code.
+- payment: missing legacy tests, but this change did not affect payment code.
 
 ## Verdict
 PASS

package/bundled/skills/prizmkit-test/references/test-generation-steps.md

@@ -4,7 +4,7 @@
 
 Before generating any test, determine whether the run is `scope=this-change`.
 
-For `scope=this-change`, use `generation_policy=in-scope-only` by default. Generate tests only for the in-scope source/test set built from the feature artifact directory and changed files. If a missing test is unrelated to the feature, record it in `Out of Scope Gaps` and do not generate it. Do not infer this-change scope from `.prizmkit/bugfix/` or `.prizmkit/refactor/`.
+For `scope=this-change`, use `generation_policy=in-scope-only` by default. Generate tests only for the in-scope source/test set built from the change artifact and changed files. If a missing test is unrelated to the current change, record it in `Out of Scope Gaps` and do not generate it. A change artifact is any directory with `spec.md` and `plan.md`; it may represent a feature, bug fix, refactor, migration, or other scoped change. Do not infer this-change scope from `.prizmkit/bugfix/` or `.prizmkit/refactor/` by directory name alone; require an explicit artifact directory and changed-files source.
 
 
 Generate tests from the Phase 4 Boundary Coverage Matrix in priority order: unit → integration → E2E. After each batch, run immediately.

package/bundled/skills/prizmkit-test/references/test-report-template.md

@@ -8,14 +8,14 @@ Used in Phase 6 of `/prizmkit-test`. Create `.prizmkit/test/{YYYY_MM_DD_HH_MM_SS
 # Test Report — {timestamp}
 
 ## Summary
-- Scope: {full / module: name / feature: ###-name}
+- Scope: {full / module: name / feature: ###-name / this-change}
 - Architecture: {frontend / backend / fullstack}
 - Test framework: {name}
 - Mode: {interactive / headless}
 
 ## Scope
 - Mode: {full-project / module:<name> / feature:<slug> / this-change}
-- Artifact Dir: {none / .prizmkit/specs/<FEATURE_SLUG>/}
+- Artifact Dir: {none / path to change artifact containing spec.md + plan.md}
 - Diff Base: {ref or none}
 - Changed Files Source: {changed_files / diff_base / plan.md / context-snapshot.md / spec.md / not applicable}
 - Generation Policy: {in-scope-only / full-project}