prizmkit 1.1.86 → 1.1.87

package/bundled/skills/prizmkit-test/scripts/validate_boundary_report.py

@@ -0,0 +1,347 @@
+#!/usr/bin/env python3
+"""
+Validate a prizmkit-test report's boundary coverage gate.
+
+Usage:
+  python3 scripts/validate_boundary_report.py --report .prizmkit/test/.../test-report.md
+  python3 scripts/validate_boundary_report.py --report .prizmkit/test/.../test-report.md --openapi openapi.yaml
+
+The script intentionally performs deterministic structural checks only. It cannot prove that every
+business boundary is semantically correct, but it prevents reports from silently claiming completion
+when interfaces are missing from the Boundary Matrix or remain happy-path-only / boundary-missing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from typing import Dict, List, Set, Tuple
+
+ALLOWED_FINAL_STATUSES = {
+    "boundary-covered",
+    "generated-needs-review",
+    "skipped-with-reason",
+}
+INCOMPLETE_MARKERS = {
+    "boundary-missing",
+    "happy-path-only",
+    "unresolved",
+}
+REQUIRED_SECTIONS = [
+    "## Boundary Matrix",
+    "## Boundary Completion Gate",
+    "## Final Status",
+]
+REQUIRED_BOUNDARY_COLUMNS = [
+    "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",
+]
+BOUNDARY_CATEGORY_COLUMNS = [
+    "Happy Path",
+    "Request Validation",
+    "Auth / Permission / Ownership",
+    "Domain Invariants",
+    "Collection / Pagination",
+    "Date / Time",
+    "State Transitions",
+    "Dependency Failure",
+    "Response Contract",
+]
+
+
+def read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        raise SystemExit(f"FAIL: file not found: {path}")
+
+
+HTTP_METHODS = {"GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE"}
+
+
+def extract_openapi_paths(openapi_text: str) -> List[str]:
+    """Extract OpenAPI path keys without requiring PyYAML.
+
+    Supports common YAML forms inside the `paths:` mapping:
+    - /users:
+    - "/users/{id}":
+    - '/users/{id}':
+    """
+    return [path for _method, path in extract_openapi_operations(openapi_text)]
+
+
+def extract_openapi_operations(openapi_text: str) -> List[Tuple[str, str]]:
+    """Extract OpenAPI method+path operations without requiring PyYAML."""
+    operations: List[Tuple[str, str]] = []
+    in_paths = False
+    paths_indent = 0
+    current_path = ""
+    current_path_indent = 0
+    path_key_re = re.compile(
+        r"^\s*(?:(['\"])(/.*?)\1|(/[^:\s]+))\s*:\s*(?:#.*)?$"
+    )
+    method_re = re.compile(r"^\s*([A-Za-z]+)\s*:\s*(?:#.*)?$")
+
+    for raw_line in openapi_text.splitlines():
+        stripped = raw_line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        indent = len(raw_line) - len(raw_line.lstrip())
+        if not in_paths:
+            if re.match(r"^\s*paths\s*:\s*(?:#.*)?$", raw_line):
+                in_paths = True
+                paths_indent = indent
+            continue
+
+        if indent <= paths_indent:
+            break
+
+        path_match = path_key_re.match(raw_line)
+        if path_match:
+            current_path = path_match.group(2) or path_match.group(3) or ""
+            current_path_indent = indent
+            continue
+
+        method_match = method_re.match(raw_line)
+        if current_path and method_match and indent > current_path_indent:
+            method = method_match.group(1).upper()
+            if method in HTTP_METHODS:
+                operations.append((method, current_path))
+
+    return operations
+
+
+def extract_section(text: str, heading: str) -> str:
+    start = text.find(heading)
+    if start == -1:
+        return ""
+    rest = text[start + len(heading) :]
+    match = re.search(r"\n## ", rest)
+    if not match:
+        return rest
+    return rest[: match.start()]
+
+
+def split_markdown_row(line: str) -> List[str]:
+    return [cell.strip() for cell in line.strip().strip("|").split("|")]
+
+
+def parse_boundary_matrix(text: str) -> Tuple[List[str], List[Dict[str, str]]]:
+    section = extract_section(text, "## Boundary Matrix")
+    if not section:
+        return [], []
+
+    lines = [line.strip() for line in section.splitlines() if line.strip().startswith("|")]
+    header_index = -1
+    for idx, line in enumerate(lines):
+        cells = split_markdown_row(line)
+        if "Interface" in cells and "Final Status" in cells:
+            header_index = idx
+            break
+    if header_index == -1:
+        return [], []
+
+    headers = split_markdown_row(lines[header_index])
+    rows: List[Dict[str, str]] = []
+    for line in lines[header_index + 1 :]:
+        cells = split_markdown_row(line)
+        if all(re.fullmatch(r":?-{3,}:?", cell) for cell in cells):
+            continue
+        if len(cells) < len(headers):
+            cells.extend([""] * (len(headers) - len(cells)))
+        row = {header: cells[i] if i < len(cells) else "" for i, header in enumerate(headers)}
+        # Ignore example placeholder rows that were accidentally left in templates.
+        if row.get("Interface", "").strip(".` ") in {"...", ""}:
+            continue
+        rows.append(row)
+    return headers, rows
+
+
+def has_inline_reason(value: str) -> bool:
+    normalized = value.strip().lower()
+    if not normalized:
+        return False
+    if "—" in value or " - " in value or ":" in value:
+        return True
+    # Accept phrases longer than a bare status marker.
+    bare = {"n/a", "na", "skipped", "skip"}
+    return normalized not in bare and (normalized.startswith("n/a ") or normalized.startswith("skipped "))
+
+
+def extract_matrix_operations(interface_values: List[str]) -> Tuple[Set[Tuple[str, str]], Set[str]]:
+    """Extract method+path and path-only tokens from Boundary Matrix Interface cells."""
+    operations: Set[Tuple[str, str]] = set()
+    path_only: Set[str] = set()
+    token_re = re.compile(
+        r"(?:(\b(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE)\b)\s+)?(/[^\s,`|)]+)",
+        flags=re.IGNORECASE,
+    )
+    for value in interface_values:
+        for match in token_re.finditer(value):
+            method = match.group(1).upper() if match.group(1) else ""
+            path = normalize_path(match.group(2))
+            if not path:
+                continue
+            if method:
+                operations.add((method, path))
+            else:
+                path_only.add(path)
+    return operations, path_only
+
+
+def normalize_path(path: str) -> str:
+    normalized = path.strip().strip("'\"`")
+    if len(normalized) > 1:
+        normalized = normalized.rstrip("/")
+    return normalized
+
+
+def validate_report(report_text: str, openapi_paths: List[str] | None,
+                    openapi_operations: List[Tuple[str, str]] | None = None) -> List[str]:
+    errors: List[str] = []
+
+    for section in REQUIRED_SECTIONS:
+        if section not in report_text:
+            errors.append(f"missing required section: {section}")
+
+    headers, rows = parse_boundary_matrix(report_text)
+    if not rows:
+        errors.append("Boundary Matrix table is missing or empty")
+        return errors
+
+    for column in REQUIRED_BOUNDARY_COLUMNS:
+        if column not in headers:
+            errors.append(f"Boundary Matrix missing required column: {column}")
+
+    final_statuses = []
+    interface_values = []
+    for idx, row in enumerate(rows, start=1):
+        interface = row.get("Interface", "").strip()
+        interface_values.append(interface)
+
+        final_status = row.get("Final Status", "").strip().lower()
+        final_statuses.append(final_status)
+        if not final_status:
+            errors.append(f"row {idx} ({interface}) missing Final Status")
+        elif final_status not in ALLOWED_FINAL_STATUSES:
+            errors.append(
+                f"row {idx} ({interface}) has invalid/incomplete Final Status: {row.get('Final Status', '')}"
+            )
+
+        for column in BOUNDARY_CATEGORY_COLUMNS:
+            if column in headers and not row.get(column, "").strip():
+                errors.append(f"row {idx} ({interface}) missing boundary category value: {column}")
+
+        for header, value in row.items():
+            normalized = value.strip().lower()
+            if any(marker in normalized for marker in INCOMPLETE_MARKERS):
+                errors.append(f"row {idx} ({interface}) has incomplete marker in {header}: {value}")
+
+        n_a_reasons = row.get("N/A Reasons", "").strip()
+        for header, value in row.items():
+            if header in {"Module", "Interface", "Service Type", "Final Status", "N/A Reasons"}:
+                continue
+            normalized = value.strip().lower()
+            if normalized in {"n/a", "na", "skipped", "skip"} and not n_a_reasons:
+                errors.append(f"row {idx} ({interface}) marks {header} as {value} without N/A reason")
+            if ("skipped" in normalized or normalized.startswith("n/a")) and not (n_a_reasons or has_inline_reason(value)):
+                errors.append(f"row {idx} ({interface}) marks {header} as {value} without concrete reason")
+
+    if openapi_operations is not None:
+        matrix_operations, matrix_path_only = extract_matrix_operations(interface_values)
+        for method, path in openapi_operations:
+            normalized_path = normalize_path(path)
+            if (method, normalized_path) not in matrix_operations:
+                if normalized_path in matrix_path_only:
+                    errors.append(
+                        "OpenAPI operation missing from Boundary Matrix: "
+                        f"{method} {path} (path-only row is ambiguous)"
+                    )
+                else:
+                    errors.append(
+                        f"OpenAPI operation missing from Boundary Matrix: {method} {path}"
+                    )
+    elif openapi_paths is not None:
+        _matrix_operations, matrix_path_only = extract_matrix_operations(interface_values)
+        missing_paths = [path for path in openapi_paths
+                         if normalize_path(path) not in matrix_path_only]
+        for path in missing_paths:
+            errors.append(f"OpenAPI path missing from Boundary Matrix: {path}")
+
+    gate_section = extract_section(report_text, "## Boundary Completion Gate")
+    if gate_section:
+        for label in ["Interfaces total", "Boundary-covered", "Boundary-missing", "Happy-path-only", "Completion gate passed"]:
+            if label not in gate_section:
+                errors.append(f"Boundary Completion Gate missing metric: {label}")
+        for label in ["Boundary-missing", "Happy-path-only"]:
+            match = re.search(rf"{re.escape(label)}:\s*(\d+)", gate_section)
+            if match and int(match.group(1)) > 0:
+                errors.append(f"Boundary Completion Gate reports {label}: {match.group(1)}")
+        if re.search(r"Completion gate passed:\s*no", gate_section, flags=re.IGNORECASE):
+            errors.append("Boundary Completion Gate reports failure")
+
+    final_section = extract_section(report_text, "## Final Status")
+    if final_section:
+        if re.search(r"Ready for commit:\s*yes", final_section, flags=re.IGNORECASE):
+            if any(status != "boundary-covered" for status in final_statuses):
+                errors.append("Final Status says ready for commit but not every interface is boundary-covered")
+            review_match = re.search(r"Needs human review:\s*(.+)", final_section, flags=re.IGNORECASE)
+            if review_match and review_match.group(1).strip().lower() not in {"none", "no", "n/a", ""}:
+                errors.append("Final Status says ready for commit while human review is still needed")
+
+    return errors
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate prizmkit-test boundary coverage report")
+    parser.add_argument("--report", required=True, help="Path to test-report.md")
+    parser.add_argument("--openapi", help="Optional OpenAPI file whose paths must appear in Boundary Matrix")
+    args = parser.parse_args()
+
+    report_path = Path(args.report)
+    report_text = read_text(report_path)
+
+    openapi_paths = None
+    openapi_operations = None
+    if args.openapi:
+        openapi_path = Path(args.openapi)
+        if openapi_path.exists():
+            openapi_text = read_text(openapi_path)
+            openapi_operations = extract_openapi_operations(openapi_text)
+            openapi_paths = [path for _method, path in openapi_operations]
+        else:
+            print(f"WARN: OpenAPI file not found, skipping path coverage check: {openapi_path}")
+
+    errors = validate_report(report_text, openapi_paths, openapi_operations)
+    if errors:
+        print("Boundary report validation: FAIL")
+        for error in errors:
+            print(f"- {error}")
+        return 1
+
+    print("Boundary report validation: PASS")
+    print(f"Report: {report_path}")
+    if openapi_operations is not None:
+        print(f"OpenAPI operations checked: {len(openapi_operations)}")
+    elif openapi_paths is not None:
+        print(f"OpenAPI paths checked: {len(openapi_paths)}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bundled/skills-windows/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-windows/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-windows/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.