prizmkit 1.1.86 → 1.1.87

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

@@ -0,0 +1,220 @@
+# Boundary Coverage Protocol
+
+Use this protocol during `/prizmkit-test` Phase 4 and update it during Phase 5. The goal is to prevent a common false positive: treating "there is a test for this interface" as equivalent to "this interface is safely covered." A happy path proves that the interface can work once; boundary tests prove that the interface handles realistic invalid inputs, authorization failures, ownership rules, state transitions, and dependency failures.
+
+## 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.
+
+| 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 |
+|--------|-----------|--------------|------------|--------------------|-------------------------------|-------------------|-------------------------|-------------|-------------------|-------------------|-------------------|-------------|--------------|
+| auth | POST /auth/login | Auth / Session | covered | generated | N/A — public route | generated | N/A — no collection input | N/A — no date input | covered | skipped — password hasher not injectable | covered | ... | boundary-covered |
+
+## Status Values
+
+Use these values consistently:
+
+- `covered` — an existing test already asserts this behavior.
+- `generated` — this run generated a test and the test passed.
+- `needs-review` — a generated test is valid, but production behavior mismatched the expected contract.
+- `unresolved` — the test could not be made runnable after the allowed fix attempts.
+- `skipped` — not applicable or not practical in this run, with a concrete reason in `N/A Reasons`.
+- `boundary-missing` — applicable boundary exists but no test covers it yet.
+
+## Completion Gate
+
+An in-scope interface is complete only when:
+
+1. It has happy-path coverage when a happy path exists.
+2. Every applicable boundary category is `covered`, `generated`, or `needs-review`.
+3. Every non-applicable category has a concrete reason.
+4. No applicable category remains `boundary-missing`.
+5. The final status is one of:
+   - `boundary-covered`
+   - `generated-needs-review`
+   - `skipped-with-reason`
+
+If an interface has only happy-path coverage, set `Final Status` to `boundary-missing` and continue generating applicable boundary tests. Do not call the run complete while any in-scope interface is `boundary-missing` or `happy-path-only`.
+
+## How to Decide Whether Existing Tests Count
+
+An existing test counts for a boundary category only when it:
+
+- targets the same public interface or endpoint,
+- creates the boundary input, state, dependency failure, or authorization context,
+- asserts the expected error code, exception, state change, response shape, or side effect,
+- verifies behavior rather than only checking that the call returned a response.
+
+Examples:
+
+- `POST /users/create` returns HTTP 200 with non-empty data → happy path only.
+- `POST /users/create` with missing email asserts `code=10001` → request validation boundary.
+- `POST /items/delete` with another user's item asserts forbidden/not-found code → ownership boundary.
+- Service create method with mocked repository failure asserts no partial side effect → dependency failure boundary.
+
+## Boundary Categories
+
+### Request Validation
+
+Use when the interface accepts client input or public parameters.
+
+Generate applicable cases for:
+- missing required fields,
+- empty string / empty array / empty object,
+- malformed JSON or wrong content type when the framework exposes that behavior,
+- wrong type,
+- unsupported enum,
+- invalid numeric values: zero, negative, min/max, just above max,
+- invalid string format: URL, email, phone, date, timestamp, UUID/ULID, object key.
+
+### Auth / Permission / Ownership
+
+Use when the interface depends on identity, roles, tenant, ownership, entitlement, or token state.
+
+Generate applicable cases for:
+- missing auth,
+- malformed auth header,
+- invalid/expired/revoked token,
+- authenticated user accessing another user's resource,
+- missing role/permission/entitlement,
+- default-deny when ownership cannot be proven.
+
+### Domain Invariants
+
+Use when business rules constrain combinations of fields or state.
+
+Generate applicable cases for:
+- ratios or totals that must sum to a value,
+- start date before end date,
+- calorie/weight/amount ranges,
+- unsupported lifecycle status,
+- duplicate unique identifiers,
+- device binding requirements,
+- token rotation/reuse semantics,
+- image quality / provider classification rules,
+- product-specific thresholds such as 90%-110% calorie hit boundaries.
+
+### Collection / Pagination
+
+Use when the interface accepts or returns lists, pages, filters, or cursors.
+
+Generate applicable cases for:
+- empty result,
+- one item,
+- many items,
+- duplicate IDs,
+- omitted page / page size defaults,
+- page 0, negative page, max page size, max + 1,
+- invalid filters,
+- nullable filters such as true/false/null,
+- stable ordering or total count when specified.
+
+### Date / Time
+
+Use when the interface parses, stores, filters, expires, schedules, or compares time.
+
+Generate applicable cases for:
+- invalid date / timestamp format,
+- timezone assumptions,
+- inclusive vs exclusive date range boundaries,
+- start after end,
+- exact expiry instant and just before/after expiry,
+- today/yesterday/stale streak or schedule semantics,
+- leap day/month end when relevant.
+
+### State Transitions
+
+Use when the interface creates, updates, deletes, confirms, unbinds, retries, logs out, refreshes, or changes status.
+
+Generate applicable cases for:
+- create then read,
+- update sets expected derived fields,
+- delete excludes from later reads,
+- double delete / unbind idempotency when specified,
+- refresh rotates token and rejects old token,
+- batch operation with empty list vs explicit IDs,
+- retry count below/at/above max,
+- no partial writes when one operation fails.
+
+### Dependency Failure
+
+Use when collaborators are mockable or the test layer can safely simulate failures.
+
+Generate applicable cases for:
+- repository/database error,
+- storage/signing provider failure,
+- SMS/push/email provider failure,
+- LLM/API client error,
+- timeout/network failure,
+- malformed provider response,
+- ID/random/clock failure when injectable.
+
+If a dependency cannot be mocked in the current test layer, mark it `skipped` with a reason and consider a lower-level unit test where it can be mocked.
+
+### Response Contract
+
+Use for API endpoints and public adapters.
+
+Generate applicable cases for:
+- unified envelope fields (`code`, `message`, `data`) or framework-specific response format,
+- fixed business error codes,
+- response field names and snake_case/camelCase contract,
+- omitted vs empty data shape,
+- generated IDs and derived fields,
+- side-effect visibility in response.
+
+## Endpoint and Interface Mapping
+
+Use names, routes, methods, schemas, binding tags, repository calls, and service logic to choose categories. When names and behavior disagree, trust behavior.
+
+| Pattern | Likely Categories |
+|---------|-------------------|
+| register / signup / create user | request validation, auth/session, domain invariants, dependency failure, response contract |
+| login | request validation, auth/session, rate limit, token response, dependency failure |
+| refresh / logout | token state, rotation/revocation, idempotency, dependency failure |
+| get / detail | auth/ownership, not found, response contract, dependency failure |
+| list / search / trends | auth, filters, pagination/empty result, date range, response contract, dependency failure |
+| create | request validation, domain invariants, state transition, dependency failure, response contract |
+| update / set goal / confirm | request validation, ownership, partial update semantics, domain invariants, state transition |
+| delete / unbind | request validation, ownership, not found, soft delete, double operation behavior |
+| upload / sign url | request validation, file/storage rules, provider failure, response contract |
+| AI / provider / recognize | request validation, date/time, provider error mapping, quality classifications, async job state |
+| stats / analytics | date range, empty data, boundary thresholds, response shape, dependency failure |
+| achievement / streak | empty state, date continuity, threshold boundaries, state persistence |
+
+## N/A Reason Rules
+
+A skipped category must explain why it does not apply or why it cannot be exercised at this level.
+
+Good reasons:
+- `N/A — public route; no authenticated principal expected`
+- `N/A — endpoint has no collection input or paginated response`
+- `N/A — dependency is not injectable at handler level; covered by service unit test`
+- `N/A — function is pure and has no stateful side effects`
+- `N/A — E2E skipped because project has no UI layer`
+
+Bad reasons:
+- `N/A`
+- `not tested`
+- `probably fine`
+- `covered by happy path`
+
+## Report Requirements
+
+The final report must include:
+
+1. The Boundary Matrix.
+2. A Completion Gate summary:
+   - interfaces total,
+   - boundary-covered count,
+   - generated-needs-review count,
+   - skipped-with-reason count,
+   - boundary-missing count,
+   - happy-path-only count.
+3. A clear final status:
+   - `All tests passing and boundary coverage complete`, or
+   - `Tests passing, but boundary coverage incomplete`, or
+   - `Tests failing`, or
+   - `Needs human review`.
+
+If any interface remains `boundary-missing` or `happy-path-only`, the final report must not say "ready for commit" without qualifying that boundary coverage is incomplete.

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

@@ -26,17 +26,26 @@ Scope: Full project (all modules, all specs)
 | payment | api/checkout | integration | missing |
 | — | Checkout flow | e2e | missing |
 
-**Phase 4**: Generated 5 unit tests (3 passing, 2 assertion failures marked "needs-review"), 1 integration test (passing), 1 E2E test (passing).
+**Phase 4 — Boundary Matrix** (excerpt):
+| Module | Interface | Service Type | Happy Path | Request Validation | Auth / Permission / Ownership | Domain Invariants | Dependency Failure | Final Status |
+|--------|-----------|--------------|------------|--------------------|-------------------------------|-------------------|-------------------|--------------|
+| auth | login() | Auth / Session | covered | boundary-missing | boundary-missing | skipped | boundary-missing | boundary-missing |
+| payment | processPayment() | Payment / Billing | covered | boundary-missing | boundary-missing | boundary-missing | boundary-missing | boundary-missing |
 
-**Phase 5 — Report Summary**:
+**Phase 5**: Generated 5 unit boundary tests (3 passing, 2 assertion failures marked `needs-review`), 1 integration boundary test (passing), 1 E2E test (passing).
+
+**Phase 6 — Report Summary**:
 ```
 Generated: 5 unit (2 needs-review), 1 integration, 1 E2E
+Boundary gate: failed — 2 interfaces need human review
 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
 
+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.
+
 **User**: `/prizmkit-test`
 
 **Phase 0 — Architecture Detection**:
@@ -49,22 +58,86 @@ Test framework: Vitest
 ```
 Scope: Single feature — 042-payment-gateway
 Test files in scope: 2
+```
 
 **Phase 2 — Existing Tests**: 2 test files, 8 tests, all passing.
 
 **Phase 3 — Gap Analysis** (excerpt):
 | Module | Interface | Type | Status |
 |--------|-----------|------|--------|
-| payment | processPayment() | unit | missing |
-| payment | refund() | unit | missing |
+| payment | processPayment() | unit | boundary-missing |
+| payment | refund() | unit | boundary-missing |
+
+**Phase 4 — Boundary Matrix**:
+| Module | Interface | Service Type | Happy Path | Request Validation | Auth / Permission / Ownership | Domain Invariants | State Transitions | Dependency Failure | Final Status |
+|--------|-----------|--------------|------------|--------------------|-------------------------------|-------------------|-------------------|-------------------|--------------|
+| payment | processPayment() | Payment / Billing | covered | boundary-missing | boundary-missing | boundary-missing | generated | boundary-missing | boundary-missing |
+| payment | refund() | Payment / Refund | covered | boundary-missing | boundary-missing | boundary-missing | boundary-missing | skipped — provider sandbox unavailable | boundary-missing |
 
-**Phase 4**: Generated 2 unit tests (both passing). No integration/E2E applicable for this scope.
+**Phase 5**: Generated 8 unit tests covering amount boundaries, currency mismatch, missing entitlement, duplicate idempotency key, partial refund, full refund, over-refund, and repository failure. All passing.
 
-**Phase 5 — Report Summary**:
+**Phase 6 — Report Summary**:
 ```
-Generated: 2 unit tests (all passing)
+Generated: 8 unit tests (all passing)
+Boundary gate: passed
 Report: .prizmkit/test/2026_05_23_15_00_00_testresult/test-report.md
-All tests passing. Ready for commit.
+All tests passing and boundary coverage complete. Ready for commit.
+```
+
+## Example 3: Existing Happy Path Is Not Enough
+
+**User**: `/prizmkit-test user module`
+
+**Existing tests found**:
+```
+TestHandler_UpdateProfile_Success
+TestHandler_GetProfile_Success
+```
+
+**Boundary Matrix result**:
+| Module | Interface | Service Type | Happy Path | Request Validation | Auth / Permission / Ownership | Domain Invariants | Dependency Failure | Final Status |
+|--------|-----------|--------------|------------|--------------------|-------------------------------|-------------------|-------------------|--------------|
+| user | POST /user/update-profile | Validation / CRUD | covered | boundary-missing | boundary-missing | boundary-missing | boundary-missing | boundary-missing |
+| user | POST /user/get-profile | CRUD / Auth | covered | N/A — empty request | boundary-missing | N/A — no domain input | boundary-missing | boundary-missing |
+
+**Correct action**:
+Generate tests for:
+- missing auth,
+- invalid gender,
+- invalid activity level,
+- implausible height/weight when specified by service contract,
+- user not found,
+- repository failure,
+- response envelope shape.
+
+**Incorrect action**:
+Do not report `user` as covered just because both endpoints have success tests.
+
+
+## Example 3: Feature Pipeline this-change Run
+
+**Caller**: `/prizmkit-test scope=this-change artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/`
+
+**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.
+- 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}}/`.
+
+**Report excerpt**:
+```markdown
+## Scope
+- Mode: this-change
+- Artifact Dir: .prizmkit/specs/{{FEATURE_SLUG}}/
+- Generation Policy: in-scope-only
+
+## Out of Scope Gaps
+- payment: missing legacy tests, but this feature did not change payment code.
+
+## Verdict
+PASS
 ```
 
-**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, or fix issues manually if tests are marked `needs-review`.

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

@@ -1,6 +1,13 @@
-# Test Generation Steps (Phase 4)
+# Test Generation Steps (Phase 5)
 
-Generate tests in priority order: unit → integration → E2E. After each batch, run immediately.
+## Scope Guard
+
+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/`.
+
+
+Generate tests from the Phase 4 Boundary Coverage Matrix in priority order: unit → integration → E2E. After each batch, run immediately.
 
 When generated tests fail, distinguish two cases:
 - **Test bug** (syntax error, wrong import, wrong mock, wrong framework API usage) → fix the test and re-run
@@ -8,9 +15,49 @@ When generated tests fail, distinguish two cases:
 
 If a test fails repeatedly after 2 fix attempts, skip it and mark as "unresolved" in the report.
 
-## 4a. Unit Tests (always applicable)
+## 5a. Boundary Matrix First
+
+Before writing any new test, create or update the per-interface Boundary Test Matrix from `references/boundary-coverage-protocol.md`. This step matters because a test suite with broad happy-path coverage can still miss the conditions that cause production failures: invalid input, unauthorized access, ownership mistakes, state transitions, dependency errors, and product-specific invariants.
+
+For each in-scope interface or endpoint:
+- Identify existing happy-path coverage.
+- Identify existing boundary coverage by reading test assertions, not just test names.
+- Classify applicable categories: request validation, auth/permission/ownership, domain invariants, collection/pagination, date/time, state transitions, dependency failure, and response contract.
+- Mark non-applicable categories as `N/A` with a concrete reason.
+- Mark applicable uncovered categories as `boundary-missing`.
+
+Do not generate only happy-path tests. If happy path is missing, generate it, then continue with applicable boundary tests in the same batch.
+
+### Existing Test Evaluation
+
+An existing test counts as boundary coverage only when it:
+- targets the same interface/endpoint,
+- sends the relevant boundary input or creates the relevant state/dependency failure,
+- asserts the expected business code, exception, response shape, state change, or side effect,
+- verifies behavior beyond "HTTP 200" or "non-empty response".
 
-For each uncovered interface:
+A test that only checks the route returns successfully is happy-path coverage, not boundary coverage.
+
+### API Endpoint Boundary Discovery
+
+For API endpoints, derive boundary cases from:
+- OpenAPI request schemas and response schemas,
+- handler binding tags and request parsing behavior,
+- service validation logic,
+- repository/service error handling,
+- Prizm L2 TRAPS and DECISIONS,
+- existing tests and source behavior,
+- product rules in project brief/specs.
+
+Map each endpoint to business-specific cases. Examples:
+- `POST /auth/refresh`: missing token, malformed token, reused/rotated token, revoked token, token-version race if testable.
+- `POST /meals/update`: missing ID, missing foods, invalid meal type, invalid timestamp, not found, wrong owner, recomputed totals, confirmed state transition.
+- `POST /stats/trends`: invalid type, invalid period, invalid date range, empty data, each supported trend type, inclusive end date behavior.
+- `POST /upload/sign-url`: unsupported content type, file_count 0/default/max/max+1, scene handling, storage provider failure.
+
+## 5b. Unit Tests (always applicable)
+
+For each in-scope uncovered interface:
 - Read the source file to understand function signature, branch logic, dependencies, state changes, side effects, and failure paths.
 - Classify the function/class method by service responsibility using names, module path, parameters, dependencies, and related Prizm docs/spec acceptance criteria.
 - Read `references/service-boundary-test-catalog.md` when the unit is service-like or has business-specific inputs — it maps service responsibilities to boundary cases such as auth/session, payment/wallet, repository, pagination, file storage, notification, queue, cache/idempotency, API client, and date/expiration behavior.
@@ -24,15 +71,16 @@ For each uncovered interface:
 - Do NOT test framework internals or third-party library behavior
 - Run tests immediately after generating
 
-## 4b. Integration Tests
+## 5c. Integration Tests
 
-For each module with dependencies:
-- Generate tests for the module's primary interface exercising its real dependencies
-- If API endpoints exist: request/response tests (valid input, invalid input, missing params, auth)
-- If database operations exist: CRUD tests using the project's existing test database config
-- Run tests immediately after generating
+For each in-scope module with dependencies:
+- Generate tests for the module's primary interface exercising its real dependencies.
+- If API endpoints exist, generate request/response tests for every applicable boundary category in the Boundary Matrix, not only valid input. Cover auth, missing params, invalid formats/enums, ownership/not-found, state transitions, and response envelope or schema.
+- If database operations exist, generate CRUD tests using the project's existing test database config when available. Cover transactions, duplicate keys, soft-delete visibility, rollback, and query boundary behavior when applicable.
+- If a dependency failure is not practical at integration level, mark it `N/A` with the reason and cover it in a unit test where mocks are available.
+- Run tests immediately after generating.
 
-## 4c. E2E Tests (conditional)
+## 5d. E2E Tests (conditional)
 
 Preconditions (ALL must be met):
 - Playwright is available (`@playwright/test` or `playwright` in package.json dependencies, or `npx playwright --version` succeeds as fallback)
@@ -44,10 +92,18 @@ Preconditions (ALL must be met):
 If ALL met:
 - **Before starting dev server**: detect whether it's already running: (1) check `package.json` scripts for port flags (`--port`, `-p`, `PORT=`), (2) fall back to framework defaults (3000 for React/Next/Express, 5173 for Vite, 8000 for Django, 5000 for Flask), (3) if still unknown, ask the user. Use the detected port in `lsof -i :<port>` to check. If running, tell user: "Dev server appears to be already running on port {N}. Use this running instance for E2E tests?" If user confirms, use existing instance. If user declines, skip E2E.
 - Start the project dev server (only if not already running). Wait for it to be ready.
-- For each uncovered acceptance criterion, generate a Playwright test script
+- For each in-scope uncovered acceptance criterion, generate a Playwright test script.
+- Include boundary user journeys when acceptance criteria mention validation, permissions, empty states, error messages, or lifecycle transitions.
 - Run generated E2E tests, capture screenshots of failure.
 - **Only stop dev server if you started it.** Never stop a server that was already running.
 
 If NOT met:
 - Note what was skipped and why in the report
 - If only the server wasn't startable: still generate E2E script files but mark as "not run — manual execution needed"
+
+## 5e. Boundary Completion Check
+
+After generating and running tests:
+- Update the Boundary Matrix statuses based on passing tests and `needs-review` findings.
+- If any interface remains `boundary-missing` or happy-path-only, run another targeted generation pass for those categories before final reporting.
+- Stop only when all in-scope interfaces are `boundary-covered`, `generated-needs-review`, or `skipped-with-reason`, or when remaining gaps are explicitly listed as unresolved.

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

@@ -1,6 +1,6 @@
 # Test Report Output Template
 
-Used in Phase 5 of `/prizmkit-test`. Create `.prizmkit/test/{YYYY_MM_DD_HH_MM_SS}_testresult/` directory and write `test-report.md`.
+Used in Phase 6 of `/prizmkit-test`. Create `.prizmkit/test/{YYYY_MM_DD_HH_MM_SS}_testresult/` directory and write `test-report.md`.
 
 ## test-report.md Format
 
@@ -13,7 +13,19 @@ Used in Phase 5 of `/prizmkit-test`. Create `.prizmkit/test/{YYYY_MM_DD_HH_MM_SS
 - Test framework: {name}
 - Mode: {interactive / headless}
 
-## Existing Tests
+## Scope
+- Mode: {full-project / module:<name> / feature:<slug> / this-change}
+- Artifact Dir: {none / .prizmkit/specs/<FEATURE_SLUG>/}
+- 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}
+- In-Scope Source Files:
+  - {...}
+- In-Scope Test Files:
+  - {...}
+
+
+## Existing Tests Run
 - Total: {N} | Passed: {N} | Failed: {N}
 {failed test details or "All passing"}
 {or "No existing tests found — generated first batch"}
@@ -21,21 +33,57 @@ Used in Phase 5 of `/prizmkit-test`. Create `.prizmkit/test/{YYYY_MM_DD_HH_MM_SS
 ## Coverage Gaps Found
 | Module | Interface | Type | Status |
 |--------|-----------|------|--------|
-| ... | ... | unit/integration/e2e | covered / generated / needs-review / unresolved / skipped |
+| ... | ... | unit/integration/e2e | covered / generated / needs-review / unresolved / skipped / boundary-missing |
+
+## Boundary Matrix
+| 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 |
+|--------|-----------|--------------|------------|--------------------|-------------------------------|-------------------|-------------------------|-------------|-------------------|-------------------|-------------------|-------------|--------------|
+| ... | ... | auth/repository/upload/etc. | covered/generated/skipped | covered/generated/needs-review/skipped/boundary-missing | ... | ... | ... | ... | ... | ... | ... | category — reason | boundary-covered / generated-needs-review / skipped-with-reason / boundary-missing |
+
+## Boundary Completion Gate
+- Interfaces total: {N}
+- Boundary-covered: {N}
+- Generated-needs-review: {N}
+- Skipped-with-reason: {N}
+- Boundary-missing: {N}
+- Happy-path-only: {N}
+- Completion gate passed: {yes / no}
 
-## Boundary Coverage
-| Module | Interface | Service Type | Boundary Categories Covered | N/A Categories |
-|--------|-----------|--------------|-----------------------------|----------------|
-| ... | ... | auth/payment/repository/etc. | happy path, service-specific, branch paths, side effects, dependency failures | concurrency — no shared mutable state |
+If `Boundary-missing > 0` or `Happy-path-only > 0`, write:
+`Tests may pass, but boundary coverage is incomplete.`
 
-## Generated Tests
+## Boundary Coverage Notes
+| Module | Interface | Boundary Categories Covered | Missing Applicable Boundaries | N/A Categories with Reasons |
+|--------|-----------|-----------------------------|-------------------------------|-----------------------------|
+| ... | ... | request validation, ownership, dependency failure | invalid timestamp, repo failure | pagination — endpoint has no list semantics |
+
+## Generated / Updated Tests
 - Unit: {N} generated, {N} needs-review, {N} unresolved
 - Integration: {N} generated, {N} needs-review, {N} unresolved
 - E2E: {N} generated, {N} skipped ({reason})
 
+## Boundary Validation
+- Validator command: `{command or "not run — reason"}`
+- Validator result: {passed / failed / skipped}
+- Validator output: {summary or path to raw output}
+
+## In-Scope Failures
+- {failures caused by this-change scope, or "None"}
+
+## Baseline Failures
+- {pre-existing failures, or "None"}
+
+## Out of Scope Gaps
+- {unrelated historical gaps; informational only for scope=this-change}
+
+## Verdict
+PASS | NEEDS_FIXES | BLOCKED
+
 ## Final Status
 - All tests passing: {yes / no}
-- Needs human review: {list of tests marked needs-review}
+- Boundary completion gate passed: {yes / no}
+- Ready for commit: {yes / no — include reason}
+- Needs human review: {list of tests/interfaces marked needs-review}
 {remaining failures if any}
 ```
 
@@ -45,3 +93,19 @@ Also save alongside `test-report.md`:
 - `existing-test-output.txt` — raw output from Phase 2
 - `generated-tests/` — copies of all generated test files
 - `e2e-output/` — E2E logs and failure screenshots (if applicable)
+- `boundary-validation-output.txt` — output from `scripts/validate_boundary_report.py` when run
+
+## Final Status Rules
+
+Use these rules so the report does not overstate quality:
+
+| Tests Passing | Boundary Gate | Needs Review | Ready for Commit |
+|---------------|---------------|--------------|------------------|
+| yes | yes | no | yes |
+| yes | yes | yes | no — human review required |
+| yes | no | any | no — boundary coverage incomplete |
+| no | any | any | no — tests failing |
+
+Do not write "All tests passing. Ready for commit." if any interface is `boundary-missing`, `happy-path-only`, `unresolved`, or `needs-review`.
+
+Out-of-scope gaps are informational only. They must not trigger generated tests and must not fail a `scope=this-change` run.