prizmkit 1.1.140 → 1.1.142

package/bundled/skills/prizmkit-test/references/external-contract-mock-guidance.md

@@ -0,0 +1,119 @@
+# External Contract Mock Guidance
+
+## Purpose
+
+Use traceable contracts to model external services, persistence, filesystems, queues, generated clients, browser-facing backends, and cross-module endpoints without connecting tests to production targets or inventing provider behavior.
+
+Mocks are test tools, not proof of a deployed environment.
+
+## Contract Source Order
+
+Use the highest available source:
+
+1. project-owned OpenAPI, JSON Schema, Protocol Buffers, GraphQL, AsyncAPI, database schema, generated types, SDK interfaces, fixtures, and documentation;
+2. vendored or lock-version-matched dependency documentation;
+3. public official service documentation obtained through approved read-only web retrieval;
+4. observed non-production behavior only when explicitly authorized and safely isolated.
+
+Use the current locked/provider version when behavior differs by version. Record the source path, public URL, document/version identifier, or generated type used in `test-report.md`.
+
+Never invent fields, statuses, error shapes, retry rules, pagination behavior, ordering, or timing guarantees without a traceable source.
+
+## Safe Documentation Retrieval
+
+Public official documentation retrieval may be used only to read the minimum contract material needed for tests.
+
+- Do not send source code, repository-private content, proprietary payloads, secrets, credentials, or user data to a public endpoint.
+- Prefer a project-local or vendored source when it is authoritative.
+- Distinguish official provider documentation from blogs, examples, forum answers, and third-party tutorials.
+- When official sources conflict with the project's pinned generated client or schema, apply the skill's truth precedence and report the conflict.
+- If the required contract cannot be established, return `TEST_BLOCKED` when it prevents a safe verdict.
+
+## Build the Smallest Faithful Double
+
+Use the target project's existing fake, fixture, mock library, mock server, container, or isolated service when adequate. Model only behavior relevant to the affected module, but preserve the contract property being tested.
+
+Applicable variants include:
+
+- normal success;
+- empty success;
+- minimum, maximum, pagination, cursor, or size boundary;
+- malformed or contract-invalid response;
+- timeout or cancellation;
+- rate limiting or quota rejection;
+- authentication or authorization rejection;
+- transient service failure;
+- permanent service failure;
+- partial response or interrupted stream;
+- retry, replay, and idempotency behavior;
+- transaction, constraint, rollback, or conflict behavior for stateful services.
+
+Do not require every variant mechanically. Select variants from the actual behavior/risk model and explain material omissions.
+
+## Assertions
+
+Assert the application's observable handling of the contract:
+
+- outbound request shape, required headers or metadata, and serialization;
+- response mapping, nullability, enum and format handling;
+- retry count and retryable versus permanent classification;
+- timeout and cancellation propagation;
+- pagination and cursor behavior;
+- idempotency and side-effect counts;
+- state transition, rollback, cleanup, and absence of partial effects;
+- consumer-visible error type or result.
+
+A mock-success-only test is insufficient when dependency failure can change observable behavior.
+
+## Avoid Over-Mocking
+
+Keep production composition real when that composition is the property under test. Mock at a stable external boundary rather than mocking the method being verified or every internal collaborator.
+
+Reject a double when it:
+
+- repeats the current implementation instead of the external contract;
+- bypasses serialization, mapping, retries, or state transitions under test;
+- returns impossible provider behavior;
+- asserts only that a mock was called without proving the business result;
+- silently drifts from the project or official contract.
+
+Use contract/integration or isolated infrastructure tests when a mock cannot preserve the relevant transaction, protocol, or composition property.
+
+## Databases and Stateful Services
+
+Prefer project-provided isolated infrastructure, a faithful local fake, or a disposable service. Derive structure and constraints from schemas, migrations, models, or official protocol contracts.
+
+Any disposable resource must have:
+
+- a unique non-production identity;
+- bounded lifetime;
+- deterministic setup;
+- verified cleanup;
+- no dependency on production credentials or data.
+
+Test relevant constraints, transactions, rollback, concurrency, idempotency, and failure mapping. Cleanup failure that undermines reliability produces `TEST_BLOCKED`.
+
+## Production and Data Prohibitions
+
+Never use:
+
+- production credentials or tokens;
+- production databases, APIs, queues, object storage, caches, or services;
+- real customer or user data;
+- a target whose non-production status cannot be established;
+- destructive operations against external data.
+
+Project configuration may be reused only when it demonstrably selects a safe isolated test target. If safety cannot be proven, do not connect; report the unexecuted check and return `TEST_BLOCKED` when it is necessary for the verdict.
+
+## Reporting
+
+For every material external contract, record:
+
+- dependency and behavior under test;
+- contract source and version when available;
+- mock/fake/isolated-service strategy;
+- variants exercised;
+- production resources used: `no`;
+- unresolved fidelity or deployed-environment risk.
+
+Do not claim that a local mock, fake, contract snapshot, container, or isolated service verifies a deployed production environment.

package/bundled/skills/prizmkit-test/references/independent-test-review.md

@@ -0,0 +1,269 @@
+# Independent Test Review
+
+## Purpose
+
+Run one optional independent semantic review after mandatory Main-Agent test construction, execution, and review have converged. The Reviewer determines whether the complete current tests credibly prove the affected business module and Regression Ring and whether the tests themselves are valid.
+
+The Reviewer is not required to disagree. It returns `NO_CORRECTION_NEEDED` when no evidence-backed correction is justified.
+
+This reference is complete within `prizmkit-test`. Do not depend on another skill's prompt or a platform-generated Reviewer role.
+
+## Required Ordering and Budget
+
+```text
+Main Agent builds and executes project-native tests
+→ mandatory Main-Agent test review: maximum ten completed rounds
+→ optional independent Test Reviewer: maximum five responses
+→ final native regression
+→ TEST_PASS | TEST_NEEDS_FIXES | TEST_BLOCKED
+```
+
+Create at most one Reviewer for this invocation. Reuse the exact same Reviewer through native continuation. Never reuse a Reviewer from another lifecycle stage and never create a replacement with a summary to simulate continuation.
+
+## Host Capability Gate
+
+The gate is all-or-nothing. Before creating a Reviewer, the host must prove this semantic execution contract:
+
+```yaml
+execution_unit:
+  count: 1
+  access: read-only
+  mutation: unavailable
+  arbitrary_command_execution: unavailable
+  downstream_execution: structurally-unavailable
+  context_continuation: same-unit-native-resume
+  workspace_observation: bounded-active-checkout-input
+  model_configuration: inherit-current-session
+```
+
+Rules:
+
+- Prompt instructions cannot satisfy a missing structural capability.
+- Do not branch on platform identity, tool name, execution-unit type name, adapter output, or an allowlist.
+- A general execution unit that merely promises not to mutate, execute commands, or delegate is ineligible while those capabilities remain available.
+- The Reviewer inherits the current session's model configuration.
+- If any capability is missing or unproven, create no Reviewer and use Strict Downgrade.
+
+## Bounded Immutable Review Input
+
+Before every response, the Main Agent captures a complete input that remains immutable for that response:
+
+```text
+test-review-input
+├── manifest
+│   ├── response number and input identity
+│   ├── exact changed production and test paths
+│   ├── relevant unchanged path inventory
+│   └── consistency markers
+├── change context
+│   ├── requirement and acceptance criteria
+│   ├── current production change
+│   └── applicable project rules
+├── coverage context
+│   ├── affected business module
+│   ├── observable behaviors
+│   ├── risk and boundary assessment
+│   └── Regression Ring
+├── test context
+│   ├── existing, added, and modified tests
+│   ├── fixtures, mocks, and contracts
+│   ├── selected test layers
+│   └── native execution results
+└── targeted supporting context
+    ├── relevant callers and consumers
+    ├── shared schemas and contracts
+    └── necessary public official contract excerpts
+```
+
+The Reviewer does not run Git, tests, builds, network calls, or broad repository discovery. The Main Agent captures authoritative current state. Do not include secrets, credentials, production data, or unrelated private repository content.
+
+Before ordinary review, the Reviewer verifies that manifest and content agree. Missing paths, unexplained changed files, stale content, or mixed-response input produces `REVIEW_BLOCKED`, never partial success.
+
+## Initial Reviewer Prompt
+
+Instantiate bracketed fields and retain every execution boundary.
+
+```text
+You are the sole independent Test Reviewer for this PrizmKit Test invocation.
+
+Purpose:
+Objectively determine whether the complete current project-native tests credibly prove the affected business module and Regression Ring and whether the tests themselves are valid. You are not an adversary and are not required to disagree. Return NO_CORRECTION_NEEDED when no evidence-backed correction is justified.
+
+Response:
+This is response [RESPONSE_NUMBER] of a maximum five responses.
+Review-input identity: [INPUT_ID]
+Manifest: [MANIFEST]
+Change context: [CHANGE_CONTEXT]
+Coverage context: [COVERAGE_CONTEXT]
+Test context: [TEST_CONTEXT]
+Targeted supporting context: [SUPPORTING_CONTEXT]
+
+Execution boundaries:
+- Complete this review personally.
+- Do not create, schedule, resume, continue, request, or coordinate another execution unit.
+- Do not ask the Main Agent to create a helper.
+- Do not re-enter orchestration, delegation, another review workflow, or an equivalent process.
+- Do not modify, create, delete, rename, stage, commit, or otherwise mutate files.
+- Do not execute commands, tests, builds, network calls, or any operation that can change state.
+- Read only the bounded review input and explicitly represented targeted supporting material.
+- Do not perform broad repository discovery or a full repository scan.
+- Report only corrections supported by a concrete target and evidence.
+- Do not invent an issue merely to return feedback.
+- Return REVIEW_BLOCKED rather than delegate or provide an incomplete success result.
+- Do not expose private reasoning traces. Return only the required output.
+
+First validate input consistency. Then review:
+- requirement and acceptance-criteria coverage;
+- complete observable behavior of the affected module;
+- critical low-level logic and exact boundaries;
+- functional, boundary, error, state, side-effect, permission, concurrency, idempotency, time, dependency, and consumer risks;
+- Regression Ring completeness;
+- selection of focused, module, contract/integration, applicable E2E, module-regression, and Regression Ring layers;
+- assertion strength and observable effect;
+- vacuous or false-positive tests and tests that cannot fail for the intended defect;
+- over-mocking or removal of production composition;
+- mock fidelity to project or public official contracts;
+- nondeterminism and flakiness risk;
+- native execution results matching the declared scope;
+- production repairs that require delta Code Review;
+- remaining risks being stated honestly.
+
+Do not rewrite the requirement, modify code, execute tests, or perform broad exploration.
+Return exactly one result using the Reviewer Output Protocol.
+```
+
+## Resume Prompt
+
+Resume the exact same Reviewer. Do not create a new Reviewer with this prompt.
+
+```text
+Continue as the same independent Test Reviewer.
+
+Response:
+This is response [RESPONSE_NUMBER] of a maximum five responses.
+New review-input identity: [INPUT_ID]
+New manifest: [MANIFEST]
+Current change context: [CHANGE_CONTEXT]
+Current coverage context: [COVERAGE_CONTEXT]
+Current test context: [TEST_CONTEXT]
+Current supporting context: [SUPPORTING_CONTEXT]
+Previously accepted corrections: [ACCEPTED_CORRECTIONS_OR_NONE]
+Repairs actually made: [REPAIRS_OR_NONE]
+Main-Agent native verification: [VERIFICATION]
+Previously rejected corrections and rejection evidence: [REJECTIONS_OR_NONE]
+Unresolved items: [UNRESOLVED_OR_NONE]
+
+All initial execution boundaries and the Reviewer Output Protocol remain mandatory. Review the complete current state, not only the repair and not the superseded input. Do not repeat a rejected correction unless the new state invalidates its rejection evidence. Validate the new input before ordinary review and return exactly one result.
+```
+
+## Reviewer Output Protocol
+
+Return exactly one form. Do not add severity, confidence, dimension, workflow routing, or acceptance fields.
+
+### No Correction Needed
+
+```markdown
+### Result: NO_CORRECTION_NEEDED
+
+### Corrections
+None.
+
+### Summary
+<one or two sentences confirming the reviewed coverage and test validity>
+```
+
+### Correction Needed
+
+```markdown
+### Result: CORRECTION_NEEDED
+
+### Corrections
+
+#### Correction 1
+- Target: <behavior, risk, test, contract, caller, or execution>
+- Problem: <what is missing or invalid>
+- Evidence: <concrete basis or reproducible scenario>
+- Correction: <required test or coverage correction>
+
+### Summary
+<one or two sentences describing the current state>
+```
+
+Every correction contains only `Target`, `Problem`, `Evidence`, and `Correction`.
+
+### Review Blocked
+
+```markdown
+### Result: REVIEW_BLOCKED
+
+### Blocker
+- Target: <missing or inconsistent review input>
+- Problem: <why complete review cannot be performed>
+- Evidence: <concrete mismatch or missing fact>
+- Correction: <what would unblock review>
+
+### Summary
+No review verdict was produced.
+```
+
+`REVIEW_BLOCKED` is an internal Reviewer result, not the final testing result.
+
+## Main-Agent Adjudication
+
+The Main Agent verifies every proposed correction and records exactly one decision:
+
+| Decision | Meaning | Action |
+|---|---|---|
+| `accepted` | Evidence proves an in-scope correction is required. | Repair tests or permitted production code, execute targeted and required regression tests, and perform a complete Main-Agent review round. |
+| `rejected` | Code, contracts, tests, execution output, or rules disprove the problem. | Record concrete rejection evidence and make no change. |
+| `unresolved` | Truth, correctness, input completeness, or safe repair cannot be established. | Return `TEST_BLOCKED`, or `TEST_NEEDS_FIXES` only when a known correction remains. |
+
+The Reviewer never mutates files and cannot overrule adjudication.
+
+Independent review converges when:
+
+1. the Reviewer returns `NO_CORRECTION_NEEDED`; or
+2. every correction in the current response is rejected with concrete evidence and no unresolved item remains.
+
+## Response Algorithm
+
+1. Run only after mandatory Main-Agent review converges with no unresolved finding.
+2. Apply the Host Capability Gate.
+3. If eligible, capture response-one input and create exactly one Reviewer with the Initial Reviewer Prompt.
+4. Validate the response against the output protocol and record it in the report.
+5. Adjudicate every correction and record accepted, rejected, or unresolved with evidence.
+6. For accepted corrections, the Main Agent repairs the current workspace, executes focused and required regressions, then performs a complete Main-Agent review round over the new state within its ten-round budget.
+7. If responses remain, capture the complete fresh input and natively resume the exact same Reviewer. Never create a replacement.
+8. If response five contains an accepted correction, do not repair and claim pass without independent recheck. Return `TEST_NEEDS_FIXES` with the known correction.
+9. If response five contains an unresolved correction or `REVIEW_BLOCKED` that cannot be corrected safely, return `TEST_BLOCKED`.
+10. Stop sending messages when the review converges, reaches its limit, or becomes blocked. Explicitly terminate the unit only when the host safely supports it.
+
+## Strict Downgrade
+
+Use Strict Downgrade when:
+
+- required capability is unavailable or unproven before creation;
+- creation fails before a valid response;
+- a required structural capability disappears;
+- exact native resume fails after mutation.
+
+Behavior:
+
+1. Never create a weaker or replacement Reviewer.
+2. Never create a fresh Reviewer with a summary; summary context is not native continuation.
+3. Before creation or before any valid response, record the downgrade and preserve the converged mandatory Main-Agent review.
+4. When resume fails after mutation, the old independent result no longer describes the final state. Rerun mandatory Main-Agent review over the mutation within its remaining budget, record the downgrade, and set `final_state_rechecked=false` for independent review.
+5. A semantic `REVIEW_BLOCKED` caused by incomplete or inconsistent required input is not silently downgraded. Correct the input and resume the same Reviewer within budget, or return `TEST_BLOCKED`.
+6. Strict Downgrade is visible reduced assurance, not a new testing result and not permission to weaken Main-Agent review or native test execution.
+
+## Report Recording
+
+Record:
+
+- capability gate outcome and downgrade reason;
+- each response number `1..5`, input identity, result, and correction count;
+- every Main-Agent adjudication and its evidence;
+- actual repair and native verification;
+- whether the exact final state was independently rechecked.
+
+The report remains the human-readable test artifact. Do not create a separate Reviewer state machine or evidence package.

package/bundled/skills/prizmkit-test/references/test-coverage-model.md

@@ -0,0 +1,193 @@
+# Test Coverage Model
+
+## Purpose
+
+Use this model to determine whether project-native tests adequately prove the complete affected business module and its concrete Regression Ring. It is a semantic working model and report input, not a persisted state machine or machine-attested evidence package.
+
+## Outside-In Scope
+
+Start with behavior observable by a user, caller, consumer, or external contract. Trace each behavior inward:
+
+```text
+business capability or acceptance criterion
+├── public entry point
+├── business rules and invariants
+├── state transitions and side effects
+├── critical low-level logic
+├── dependency and external contracts
+└── callers, consumers, shared contracts, and shared state
+```
+
+Changed lines locate possible impact. They do not define completeness.
+
+## Affected Business Module
+
+Prefer an explicit project module. If none exists, derive one cohesive boundary from files that jointly implement one observable responsibility.
+
+Primary Scope includes every discoverable observable behavior in that module, including relevant pre-existing behavior whose tests are incomplete. Do not expand into unrelated modules merely to increase coverage.
+
+## Regression Ring
+
+Include only evidenced coupling:
+
+- direct callers;
+- consumers of return values, errors, events, files, or ordering;
+- shared schemas, types, protocols, generated artifacts, and adapters;
+- persistence, cache, lock, queue, transaction, or other shared state;
+- registrations, configuration, or runtime discovery that concretely connects behavior.
+
+Record dynamic or unprovable coupling as a remaining edge. An edge that can change the testing verdict prevents `TEST_PASS` until resolved.
+
+## Truth Precedence
+
+Resolve expected behavior in this order:
+
+1. confirmed specification;
+2. machine-readable contract;
+3. acceptance criteria;
+4. trusted existing tests;
+5. callers and consumers;
+6. current implementation.
+
+Do not encode a possible implementation defect as expected behavior. Conflicting higher-precedence truth that cannot be resolved produces `TEST_BLOCKED`.
+
+## Behavior Inventory
+
+For each observable behavior, capture enough working context to answer:
+
+| Concern | Questions |
+|---|---|
+| Preconditions | Which identity, state, configuration, or dependency state is required? |
+| Inputs | Which valid, minimal, complex, empty, null, malformed, type, and format classes matter? |
+| Boundaries | What happens before, at, and after exact contract limits or transitions? |
+| Outputs | Which values, errors, response shapes, ordering, and identifiers are observable? |
+| Side effects | Which writes, calls, events, files, messages, counts, ordering, or absences are required? |
+| State | What are the valid and invalid transitions, retry behavior, and repeated-call outcomes? |
+| Dependencies | Which success, empty, malformed, timeout, rate-limit, and failure responses matter? |
+| Consumers | Which return shapes, errors, events, ordering, shared contracts, and invocation assumptions must remain stable? |
+
+Working notes may be lightweight. The final report summarizes the model; no JSON matrix, IDs, hashes, or attestation records are required.
+
+## Risk Dimensions
+
+Assess every dimension for every behavior. A dimension can be inapplicable, but the report must give a concise behavior-specific reason when omission would otherwise be surprising.
+
+### Functional
+
+Cover normal, minimal, and complex valid inputs and every contract-relevant observable branch.
+
+### Boundary
+
+Cover empty/null, exact minimum and maximum, before/at/after transitions, malformed formats, collection limits, overflow, and truncation where relevant.
+
+### Error
+
+Cover validation, dependency, malformed-response, timeout, cancellation, cleanup, and partial-failure mapping. Assert both the error and the absence of forbidden partial effects.
+
+### State and Side Effects
+
+Cover valid and invalid transitions, retries, repeated calls, writes, events, call counts, ordering, rollback, and cleanup.
+
+### Permission
+
+Apply to identity, role, tenant, ownership, policy, entitlement, secret, or protected-resource behavior. Include missing/invalid identity, wrong owner or tenant, insufficient grants, and default-deny behavior.
+
+### Concurrency
+
+Apply when shared mutable state, locks, optimistic versions, duplicate workers or calls, race-prone caches, or transaction ordering can affect observable results. Use deterministic barriers, fakes, or synchronization; do not rely on timing sleeps.
+
+### Idempotency
+
+Apply to retries, deduplication keys, create/update/delete repetition, webhook or job replay, token rotation, and repeated transitions. Assert result and side-effect count.
+
+### Time
+
+Apply to expiry, schedules, windows, date ranges, TTL, time zones, and clock-sensitive signatures. Control the clock and test exact boundaries plus before and after.
+
+### Dependency
+
+Apply to databases, filesystems, queues, providers, clocks/randomness, cross-module adapters, and network clients. Assert failure mapping, retry bounds, cleanup, and absence of partial effects.
+
+### Consumer
+
+Apply when callers depend on return shape, errors, side effects, ordering, generated assets, shared types, contracts, state, or invocation conventions.
+
+## Layer Selection
+
+Use the lowest layer that proves a property without removing relevant composition.
+
+| Layer | Use For |
+|---|---|
+| Focused/unit | Critical pure logic, exact boundaries, deterministic errors, fast localization. |
+| Module/component | Public module behavior with internal collaborators composed as production uses them. |
+| Contract/integration | Shared protocol compatibility or isolated infrastructure that mocks cannot adequately prove. |
+| Code-level E2E | User-visible CLI, API, or UI composition when an applicable native harness exists. |
+| Affected-module regression | Every required test for the complete affected module. |
+| Regression Ring | Concrete callers, consumers, contracts, adapters, and shared state dependencies. |
+
+Not every behavior needs every layer. Record a concise reason for omitted higher layers, such as a pure library having no process or UI boundary.
+
+## Critical Low-Level Logic
+
+Do not require one test per private function. Add a direct focused test when a helper has one or more of these properties:
+
+- nontrivial business rule or algorithm;
+- exact boundary or numerical behavior;
+- security, permission, data-integrity, time, or concurrency risk;
+- many public paths depend on it and failure localization matters;
+- public-only tests would require over-mocking or would not reliably exercise the property.
+
+Otherwise prove private logic through stable public behavior to avoid brittle implementation-coupled tests.
+
+## Assertion Quality
+
+A useful test can fail for the intended defect. It should:
+
+- assert observable outcomes rather than merely that code ran;
+- verify error type and relevant message or contract fields without overspecifying incidental text;
+- assert state and side effects, including forbidden partial effects;
+- keep the behavior under test real while isolating irrelevant dependencies;
+- use deterministic time, randomness, concurrency, and fixtures;
+- provide useful failure diagnostics;
+- follow native test organization and naming.
+
+Reject snapshot-only or mock-call-only tests when those assertions do not prove the behavior. Reject a mock that duplicates the implementation or bypasses the composition being tested.
+
+## Existing-Test-First Construction
+
+Before adding tests:
+
+1. Inspect manifests, native commands, runner configuration, and CI conventions.
+2. Read existing test assertions rather than relying on names.
+3. Reuse project fixtures, fakes, helpers, mock servers, and coverage tooling.
+4. Run the smallest relevant existing tests.
+5. Add or update tests only for concrete behavior/risk gaps.
+6. Add only the smallest native infrastructure needed for a necessary layer.
+
+Never add a second framework when the existing one is adequate. Never delete or weaken a valid test just to make the suite pass.
+
+## Coverage Metrics
+
+Use existing line, branch, or function coverage to locate possibly omitted behavior. Do not:
+
+- use a percentage as the business-completeness verdict;
+- force direct tests for irrelevant private lines;
+- weaken assertions to increase percentages;
+- exclude difficult business behavior merely to improve a metric.
+
+## Completion Review
+
+Coverage is complete enough for `TEST_PASS` only when:
+
+1. every discoverable observable behavior is represented;
+2. every applicable risk has a credible project-native test;
+3. critical low-level logic has direct focused coverage when justified;
+4. selected layers preserve the property being proved;
+5. complete affected-module regression passes;
+6. Regression Ring verification passes;
+7. concrete unresolved coupling no longer affects the verdict;
+8. Main-Agent review converges;
+9. applicable independent review converges or is strictly downgraded;
+10. no mutation follows final review and execution.
+
+Absolute completeness cannot be guaranteed. State remaining informational risks honestly without presenting them as proven behavior.