prizmkit 1.1.86 → 1.1.87

package/bundled/dev-pipeline-windows/templates/sections/phase-prizmkit-test.md

@@ -0,0 +1,186 @@
+### Scoped Feature Test Gate — PrizmKit Test
+
+**Goal**: Generate and verify tests for this feature's changed scope before code review.
+
+Create a start marker immediately before invoking the skill so the gate can reject stale reports from older sessions:
+
+```powershell
+New-Item -ItemType Directory -Force -Path ".prizmkit/specs/{{FEATURE_SLUG}}" | Out-Null
+$testGateMarker = ".prizmkit/specs/{{FEATURE_SLUG}}/.prizmkit-test-started"
+New-Item -ItemType File -Force -Path $testGateMarker | Out-Null
+```
+
+Run `/prizmkit-test` with the feature artifact directory:
+
+```text
+/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/
+```
+
+Rules:
+- This gate is feature-pipeline only. Do NOT use `.prizmkit/bugfix/` or `.prizmkit/refactor/` artifact directories here.
+- Generate or update tests only for this feature's changed files, changed public interfaces, and acceptance criteria.
+- Record unrelated historical coverage gaps under `Out of Scope Gaps`; do not generate tests for them and do not fail this feature because of them.
+- If generated tests fail because implementation is wrong, fix implementation within this feature scope and rerun the affected tests.
+- If failures are baseline or unrelated to this feature, document them in the report and continue only when no in-scope failure remains unexplained.
+
+**Gate Check — Test Report**:
+After `/prizmkit-test` returns, locate the newest test report created after the start marker and validate that it belongs to this feature scope, has a PASS verdict, and has passed the boundary completion/validation gates before writing the checkpoint pointer:
+```powershell
+$featureArtifactDir = ".prizmkit/specs/{{FEATURE_SLUG}}/"
+$latestTestReport = Get-ChildItem -Path ".prizmkit/test" -Filter "test-report.md" -Recurse -ErrorAction SilentlyContinue |
+  Where-Object { $_.LastWriteTime -ge (Get-Item -LiteralPath $testGateMarker).LastWriteTime } |
+  Sort-Object FullName |
+  Select-Object -Last 1
+
+if ($latestTestReport) {
+  $lines = Get-Content -LiteralPath $latestTestReport.FullName -ErrorAction SilentlyContinue
+  $inScope = $false
+  $reportMode = ""
+  $reportArtifactDir = ""
+  $reportVerdict = ""
+  $inBoundaryGate = $false
+  $inBoundaryValidation = $false
+  $inBoundaryMatrix = $false
+  $boundaryGatePassed = ""
+  $boundaryMissing = ""
+  $happyPathOnly = ""
+  $boundaryValidationResult = ""
+  $boundaryColumnsOk = $false
+  $boundaryIncomplete = $false
+  for ($i = 0; $i -lt $lines.Count; $i++) {
+    $line = $lines[$i]
+    if ($line -match '^## Scope\s*$') { $inScope = $true; $inBoundaryGate = $false; $inBoundaryValidation = $false; $inBoundaryMatrix = $false; continue }
+    if ($line -match '^## Boundary Matrix\s*$') { $inBoundaryMatrix = $true; $inScope = $false; $inBoundaryGate = $false; $inBoundaryValidation = $false; continue }
+    if ($line -match '^## Boundary Completion Gate\s*$') { $inBoundaryGate = $true; $inScope = $false; $inBoundaryValidation = $false; $inBoundaryMatrix = $false; continue }
+    if ($line -match '^## Boundary Validation\s*$') { $inBoundaryValidation = $true; $inScope = $false; $inBoundaryGate = $false; $inBoundaryMatrix = $false; continue }
+    if ($line -match '^## ' -and $inScope) { $inScope = $false }
+    if ($line -match '^## ' -and $inBoundaryMatrix) { $inBoundaryMatrix = $false }
+    if ($line -match '^## ' -and $inBoundaryGate) { $inBoundaryGate = $false }
+    if ($line -match '^## ' -and $inBoundaryValidation) { $inBoundaryValidation = $false }
+    if ($inScope -and $line -match '^- Mode:\s*(.+)$') { $reportMode = $Matches[1].Trim() }
+    if ($inScope -and $line -match '^- Artifact Dir:\s*(.+)$') { $reportArtifactDir = $Matches[1].Trim() }
+    if ($inBoundaryMatrix -and $line -match '^\|') {
+      $hasRequiredColumns =
+        $line -match '\|\s*Module\s*\|' -and
+        $line -match '\|\s*Interface\s*\|' -and
+        $line -match '\|\s*Service Type\s*\|' -and
+        $line -match '\|\s*Happy Path\s*\|' -and
+        $line -match '\|\s*Request Validation\s*\|' -and
+        $line -match '\|\s*Auth / Permission / Ownership\s*\|' -and
+        $line -match '\|\s*Domain Invariants\s*\|' -and
+        $line -match '\|\s*Collection / Pagination\s*\|' -and
+        $line -match '\|\s*Date / Time\s*\|' -and
+        $line -match '\|\s*State Transitions\s*\|' -and
+        $line -match '\|\s*Dependency Failure\s*\|' -and
+        $line -match '\|\s*Response Contract\s*\|' -and
+        $line -match '\|\s*N/A Reasons\s*\|' -and
+        $line -match '\|\s*Final Status\s*\|'
+      if ($hasRequiredColumns) { $boundaryColumnsOk = $true }
+      if ($line -match 'boundary-missing|happy-path-only|unresolved') { $boundaryIncomplete = $true }
+    }
+    if ($inBoundaryGate -and $line -match '^-?\s*Completion gate passed:\s*yes\s*$') { $boundaryGatePassed = "yes" }
+    if ($inBoundaryGate -and $line -match '^-?\s*Boundary-missing:\s*(\d+)\s*$') { $boundaryMissing = $Matches[1].Trim() }
+    if ($inBoundaryGate -and $line -match '^-?\s*Happy-path-only:\s*(\d+)\s*$') { $happyPathOnly = $Matches[1].Trim() }
+    if ($inBoundaryValidation -and $line -match '^-?\s*Validator result:\s*(\S+)') { $boundaryValidationResult = $Matches[1].Trim().ToLowerInvariant() }
+    if ($line -match '^## Verdict\s*$') {
+      for ($j = $i + 1; $j -lt $lines.Count; $j++) {
+        if ($lines[$j].Trim()) { $reportVerdict = $lines[$j].Trim(); break }
+      }
+      break
+    }
+  }
+  $openapiFile = ""
+  $openapiCandidates = @(
+    "openapi.yaml", "openapi.yml", "swagger.yaml", "swagger.yml",
+    "docs/openapi.yaml", "docs/openapi.yml", "docs/swagger.yaml", "docs/swagger.yml",
+    "api/openapi.yaml", "api/openapi.yml", "api/swagger.yaml", "api/swagger.yml"
+  )
+  foreach ($openapiCandidate in $openapiCandidates) {
+    if (Test-Path -LiteralPath $openapiCandidate) { $openapiFile = $openapiCandidate; break }
+  }
+  $boundaryValidatorPassed = $false
+  $boundaryValidators = @(
+    ".claude/command-assets/prizmkit-test/scripts/validate_boundary_report.py",
+    ".codebuddy/skills/prizmkit-test/scripts/validate_boundary_report.py",
+    ".agents/skills/prizmkit-test/scripts/validate_boundary_report.py"
+  )
+  foreach ($boundaryValidator in $boundaryValidators) {
+    if (Test-Path -LiteralPath $boundaryValidator) {
+      $boundaryValidatorArgs = @($boundaryValidator, "--report", $latestTestReport.FullName)
+      if ($openapiFile) { $boundaryValidatorArgs += @("--openapi", $openapiFile) }
+      Invoke-PrizmPython @boundaryValidatorArgs *> $null
+      if ($LASTEXITCODE -eq 0) { $boundaryValidatorPassed = $true; break }
+    }
+  }
+  $scopeFreshOk = $false
+  try {
+    $reportMtime = (Get-Item -LiteralPath $latestTestReport.FullName).LastWriteTimeUtc
+    $markerMtime = (Get-Item -LiteralPath $testGateMarker).LastWriteTimeUtc
+    if ($reportMtime -ge $markerMtime) {
+      function Get-ScopedFileList($sectionName) {
+        $inScopeSection = $false
+        $inList = $false
+        $values = @()
+        foreach ($rawLine in $lines) {
+          $line = $rawLine.Trim()
+          if ($line -match '^## Scope\s*$') { $inScopeSection = $true; continue }
+          if ($inScopeSection -and $line -match '^## ') { break }
+          if (-not $inScopeSection) { continue }
+          if ($line -eq "- ${sectionName}:") { $inList = $true; continue }
+          if ($inList) {
+            if ($rawLine -match '^\s{2,}-\s+(.+)$') {
+              $value = $Matches[1].Trim().Trim('`')
+              if ($value -and $value -ne '{...}' -and $value -ne '...') { $values += $value }
+              continue
+            }
+            if ($line -match '^- ') { break }
+          }
+        }
+        return $values
+      }
+      $sourceFiles = @(Get-ScopedFileList "In-Scope Source Files")
+      $testFiles = @(Get-ScopedFileList "In-Scope Test Files")
+      if ($sourceFiles.Count -gt 0 -and $testFiles.Count -gt 0) {
+        $scopeFreshOk = $true
+        $projectRoot = (Resolve-Path ".").Path
+        $ignored = @('none', 'n/a', 'not applicable', '(none)', '{...}', '...')
+        foreach ($listedFile in $sourceFiles + $testFiles) {
+          $normalized = $listedFile.Trim().Trim('`')
+          if (-not $normalized -or $ignored -contains $normalized.ToLowerInvariant()) { $scopeFreshOk = $false; break }
+          if ([System.IO.Path]::IsPathRooted($normalized)) { $candidate = $normalized } else { $candidate = Join-Path $projectRoot $normalized }
+          if (-not (Test-Path -LiteralPath $candidate -PathType Leaf)) { $scopeFreshOk = $false; break }
+          $candidatePath = (Resolve-Path -LiteralPath $candidate).Path
+          if (-not ($candidatePath -eq $projectRoot -or $candidatePath.StartsWith($projectRoot + [System.IO.Path]::DirectorySeparatorChar))) { $scopeFreshOk = $false; break }
+          if ((Get-Item -LiteralPath $candidatePath).LastWriteTimeUtc -gt $reportMtime) { $scopeFreshOk = $false; break }
+        }
+      }
+    }
+  } catch {
+    $scopeFreshOk = $false
+  }
+  $artifactOk = $reportArtifactDir -eq $featureArtifactDir -or $reportArtifactDir -eq $featureArtifactDir.TrimEnd('/')
+  $boundaryOk = $boundaryColumnsOk -and -not $boundaryIncomplete -and $boundaryGatePassed -eq "yes" -and $boundaryMissing -eq "0" -and $happyPathOnly -eq "0" -and $boundaryValidationResult -eq "passed" -and $boundaryValidatorPassed -and $scopeFreshOk
+  if ($reportMode -eq "this-change" -and $artifactOk -and $reportVerdict -eq "PASS" -and $boundaryOk) {
+    Set-Content -LiteralPath ".prizmkit/specs/{{FEATURE_SLUG}}/test-report-path.txt" -Value $latestTestReport.FullName
+    "GATE:PASS $($latestTestReport.FullName)"
+  } else {
+    "GATE:FAIL verdict=$reportVerdict mode=$reportMode artifact_dir=$reportArtifactDir boundary_gate=$boundaryGatePassed boundary_missing=$boundaryMissing happy_path_only=$happyPathOnly boundary_validation=$boundaryValidationResult validator_passed=$boundaryValidatorPassed scope_fresh=$scopeFreshOk openapi=$openapiFile report=$($latestTestReport.FullName)"
+  }
+} else {
+  "GATE:MISSING"
+}
+```
+
+Gate outcomes:
+- `GATE:PASS` → append the report path and a 3-5 bullet summary to `context-snapshot.md` under `## PrizmKit Test Gate`, then update the checkpoint.
+- `GATE:FAIL` with `NEEDS_FIXES` → read the report's `In-Scope Failures`, fix the feature implementation or generated tests within this feature scope, rerun `/prizmkit-test`, and repeat the gate check. Do not proceed to code review while the verdict is not `PASS`.
+- `GATE:FAIL` with `BLOCKED`, wrong mode, wrong artifact dir, or unreadable report → write `.prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md` with the scoped test failure and stop for recovery.
+- `GATE:MISSING` → perform one bounded status check: inspect `/prizmkit-test` output and `.prizmkit/test/` for a report directory. If no current-run report exists, write `failure-log.md` and stop for recovery.
+
+Only after `GATE:PASS`, run the update script to set step `prizmkit-test` to `"completed"`:
+```powershell
+Invoke-PrizmPython {{PIPELINE_DIR}}\scripts\update-checkpoint.py `
+  --checkpoint-path {{CHECKPOINT_PATH}} `
+  --step prizmkit-test `
+  --status completed
+```

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

@@ -1,4 +1,8 @@
-### Review + Test — Code Review
+### Review — Code Review
+
+Precondition: the `prizmkit-test` checkpoint is completed and `.prizmkit/specs/{{FEATURE_SLUG}}/test-report-path.txt` points to the scoped test report.
+
+Before invoking review, read `.prizmkit/specs/{{FEATURE_SLUG}}/test-report-path.txt`, read the referenced `/prizmkit-test` report, and confirm the summary in `context-snapshot.md` under `## PrizmKit Test Gate` matches it. The code-review skill must receive this context through `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` and the Reviewer must assess generated/updated test quality, `In-Scope Failures`, `Baseline Failures`, `Out of Scope Gaps`, boundary coverage if present, and the scoped report verdict.
 
 Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`.
 

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

@@ -1,4 +1,8 @@
-### Review + Test — Code Review
+### Review — Code Review
+
+Precondition: the `prizmkit-test` checkpoint is completed and `.prizmkit/specs/{{FEATURE_SLUG}}/test-report-path.txt` points to the scoped test report.
+
+Before invoking review, read `.prizmkit/specs/{{FEATURE_SLUG}}/test-report-path.txt`, read the referenced `/prizmkit-test` report, and confirm the summary in `context-snapshot.md` under `## PrizmKit Test Gate` matches it. The code-review skill must receive this context through `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` and the Reviewer must assess generated/updated test quality, `In-Scope Failures`, `Baseline Failures`, `Out of Scope Gaps`, boundary coverage if present, and the scoped report verdict.
 
 Run `/prizmkit-code-review` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`.
 

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.86",
+  "version": "1.1.87",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",

package/bundled/skills/prizmkit-code-review/SKILL.md

@@ -32,8 +32,13 @@ The loop repeats until the Reviewer finds no issues or the max round limit is re
 
 1. **Read spec.md** from the artifact directory — extract goals and acceptance criteria.
 2. **Read plan.md** from the artifact directory — extract architecture decisions and completed tasks.
-3. **Read dev rules** (if configured): If `.prizmkit/prizm-docs/root.prizm` exists, read it and check for a `RULES:` line. If present, read all referenced `.prizmkit/rules/<layer>-rules.md` files. If `root.prizm` or a referenced rules file does not exist, continue with "No custom dev rules configured — use general best practices."
-4. **Capture workspace diff**: run `git diff` (unstaged) + `git diff --cached` (staged) + `git status` to understand the full scope of changes. For new files in git status, note their paths for the Reviewer to read.
+3. **Read scoped test report when present**:
+   - If `{artifact_dir}/test-report-path.txt` exists, read the path, then read that `/prizmkit-test` report.
+   - Extract `Scope`, `Generated / Updated Tests`, `In-Scope Failures`, `Baseline Failures`, `Out of Scope Gaps`, `Boundary Matrix` / `Boundary Completion Gate` when present, and `Verdict`.
+   - If `context-snapshot.md` contains `## PrizmKit Test Gate`, read that summary too.
+   - If this is a feature artifact under `.prizmkit/specs/` and no test report pointer or summary exists, pass `No scoped /prizmkit-test report found` into the Reviewer context so the reviewer can flag the missing gate.
+4. **Read dev rules** (if configured): If `.prizmkit/prizm-docs/root.prizm` exists, read it and check for a `RULES:` line. If present, read all referenced `.prizmkit/rules/<layer>-rules.md` files. If `root.prizm` or a referenced rules file does not exist, continue with "No custom dev rules configured — use general best practices."
+5. **Capture workspace diff**: run `git diff` (unstaged) + `git diff --cached` (staged) + `git status` to understand the full scope of changes. For new files in git status, note their paths for the Reviewer to read.
    - If no changes are detected, skip Phase 1 and proceed to Phase 2 with verdict PASS, rounds 0, and an empty findings list. Always write `review-report.md`; downstream pipeline steps use it as the review gate.
 
 ## Phase 1: Review-Fix Loop

package/bundled/skills/prizmkit-code-review/references/reviewer-agent-prompt.md

@@ -11,6 +11,9 @@ You are a code reviewer. Review workspace changes against the spec goals, plan d
 ## Plan Decisions
 {architecture decisions and task list from plan.md}
 
+## Scoped Test Report
+{summary from artifact_dir/test-report-path.txt and test-report.md, including Scope, Generated / Updated Tests, In-Scope Failures, Baseline Failures, Out of Scope Gaps, Boundary Matrix / Boundary Completion Gate if present, and Verdict. If no scoped report exists for a feature artifact, write "No scoped /prizmkit-test report found."}
+
 ## Dev Rules (per-layer conventions)
 {rules from .prizmkit/rules/<layer>-rules.md, or "No custom dev rules configured — use general best practices."}
 
@@ -34,7 +37,8 @@ Evaluate the changes across these dimensions (focus on what's relevant):
 3. **Completeness**: Files that should have been changed but weren't? Missing tests, types, imports, exports?
 4. **Consistency**: Do changes follow the project's existing patterns, naming conventions, and code style?
 5. **Security**: Hardcoded secrets, injection vulnerabilities, unsafe operations.
-6. **Rules compliance**: (Skip this dimension if no dev rules were provided.) Do changes follow the per-layer dev rules? Flag violations of framework conventions, naming patterns, state management, or other rules defined for that layer.
+6. **Test quality**: If a scoped `/prizmkit-test` report is present, verify the report scope is `this-change`, the artifact dir matches the feature, generated/updated tests assert real behavior rather than mock success or empty assertions, in-scope failures are not mislabeled as baseline failures, baseline failures are genuinely unrelated or pre-existing, out-of-scope gaps were not turned into unrelated test changes, and the report verdict is compatible with proceeding.
+7. **Rules compliance**: (Skip this dimension if no dev rules were provided.) Do changes follow the per-layer dev rules? Flag violations of framework conventions, naming patterns, state management, or other rules defined for that layer.
 
 ## Output Format
 Respond with EXACTLY this format:
@@ -46,7 +50,7 @@ Respond with EXACTLY this format:
 
 #### Finding N
 - **Severity**: high | medium | low
-- **Dimension**: goal-alignment | defect | completeness | consistency | security | rules-compliance
+- **Dimension**: goal-alignment | defect | completeness | consistency | security | test-quality | rules-compliance
 - **Location**: filepath:line (or "project-level")
 - **Problem**: What is wrong and why it matters
 - **Suggestion**: Recommended fix approach

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

@@ -1,11 +1,11 @@
 ---
 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)"
+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', '测试', '验证', '跑测试', '补测试', '边界测试'. (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.
+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.
 
 ### When to Use
 - After completing one or more features/refactors/bugfixes
@@ -34,11 +34,26 @@ Before execution, load context once:
 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
+
+Do not load all modules or all specs merely because they exist.
+
 ## Input
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `scope` | No | User selects interactively in Phase 1. In headless mode, defaults to full project. |
+| `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. |
+| `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. |
 
 ## Execution
 
@@ -72,7 +87,14 @@ Before execution, load context once:
 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.
+**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.
+
+`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.
 
 ### Phase 2: Run Existing Tests
 
@@ -83,13 +105,37 @@ Before execution, load context once:
    - 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).
+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.
+
+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.
 
 ### 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:
+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.
@@ -106,30 +152,76 @@ Compare what exists against what should exist, across three levels:
 - Check existing E2E test files against these criteria
 - Flag uncovered criteria
 
-### Phase 4: Generate Missing Tests
+### 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.
+
+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 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 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
 
-Read `${SKILL_DIR}/references/test-generation-steps.md` for the detailed generation procedure — priority order (unit → integration → E2E), failure handling rules, and generation patterns for each test level.
+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`.
 
-When generating unit tests for service-like functions, use `${SKILL_DIR}/references/service-boundary-test-catalog.md` via the generation procedure so boundary cases reflect the function's business responsibility, not only generic null/empty inputs.
+### Phase 5: Generate Missing and Boundary Tests
 
-### Phase 5: Unified Report
+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.
+
+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.
+
+For `scope=this-change`:
+- Generate or update tests only for the in-scope source/test set.
+- 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.
+
+### 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.
 
+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`
+
+`Out of Scope Gaps` are informational only for `scope=this-change`: they must not trigger generated tests and must not fail the verdict.
+
+After writing the report, 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 \
+  --report .prizmkit/test/{timestamp}_testresult/test-report.md \
+  --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.
+
 ## 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
+- 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 will re-evaluate gaps
+- 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
 
 ## Examples
 
-Read `${SKILL_DIR}/references/examples.md` for worked examples of full-project and single-feature test runs.
+Read `${SKILL_DIR}/references/examples.md` for worked examples of full-project, single-feature, and happy-path-only remediation runs.
 
-**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".
+**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.