prizmkit 1.1.154 → 1.1.156

package/bundled/skills/prizmkit-retrospective/references/retrospective-result-schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "PrizmKit Retrospective Result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "outcome",
+    "result",
+    "reason",
+    "change_paths",
+    "documentation_paths",
+    "validation"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "outcome": {
+      "enum": ["RETRO_COMPLETE", "RETRO_BLOCKED"]
+    },
+    "result": {
+      "enum": ["DOCS_UPDATED", "NO_DOC_CHANGE", null]
+    },
+    "reason": {
+      "type": "string",
+      "minLength": 1
+    },
+    "change_paths": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "allOf": [
+          {
+            "not": {
+              "pattern": "\\\\"
+            }
+          },
+          {
+            "not": {
+              "pattern": "^/"
+            }
+          },
+          {
+            "not": {
+              "pattern": "//"
+            }
+          },
+          {
+            "not": {
+              "pattern": "(?:^|/)\\.\\.?(?:/|$)"
+            }
+          },
+          {
+            "not": {
+              "pattern": "^\\.prizmkit(?:/|$)"
+            }
+          }
+        ]
+      }
+    },
+    "documentation_paths": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^\\.prizmkit/prizm-docs/.+\\.prizm$",
+        "allOf": [
+          {
+            "not": {
+              "pattern": "\\\\"
+            }
+          },
+          {
+            "not": {
+              "pattern": "//"
+            }
+          },
+          {
+            "not": {
+              "pattern": "(?:^|/)\\.\\.?(?:/|$)"
+            }
+          }
+        ]
+      }
+    },
+    "validation": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  },
+  "oneOf": [
+    {
+      "properties": {
+        "outcome": {
+          "const": "RETRO_COMPLETE"
+        },
+        "result": {
+          "enum": ["DOCS_UPDATED", "NO_DOC_CHANGE"]
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "result": {
+                "const": "DOCS_UPDATED"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "documentation_paths": {
+                "minItems": 1
+              },
+              "validation": {
+                "minItems": 1
+              }
+            }
+          }
+        }
+      ]
+    },
+    {
+      "properties": {
+        "outcome": {
+          "const": "RETRO_BLOCKED"
+        },
+        "result": {
+          "type": "null"
+        }
+      }
+    }
+  ]
+}

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

@@ -1,96 +1,153 @@
-# Structural Sync — Detailed Steps
+# Structural Sync — Capacity-Safe Detailed Steps
 
-## 1. Get changed files
+## 1. Validate supplied changed files
 
-Get changed project files from staged and unstaged changes relative to HEAD while excluding the entire `.prizmkit/` tree:
+Use only the caller-supplied `change_paths`. Normalize each repository-relative path, reject paths outside the checkout or under `.prizmkit/`, and verify its current added/modified/deleted/renamed state with exact pathspecs.
 
-```bash
-git diff HEAD --name-status -- . ':(exclude).prizmkit/**'
-```
-
-If pathspec exclusion is unavailable, filter every result whose normalized repository-relative path is exactly `.prizmkit` or starts with `.prizmkit/` before classification. Do not infer project structure or durable knowledge from excluded files.
+Do not expand the path set through repository-wide status or diff discovery. Never run an unconditional repository-wide documentation rewrite. If the validated list is empty, structural sync is not needed.
 
-If the caller supplied an explicit file list, apply the same `.prizmkit/` exclusion before using it and note the source in the report. If no files remain, structural sync is not needed.
+## 2. Map exact changes to a bounded target set
 
-## 2. Map files to modules
+Read `.prizmkit/prizm-docs/root.prizm` only as the project map, then map each exact changed path through its MODULE_INDEX or MODULE_GROUPS pointer to the most specific existing documentation owner.
 
-Read `.prizmkit/prizm-docs/root.prizm` and map each changed file to MODULE_INDEX or MODULE_GROUPS entries.
+The writable set contains only:
 
-If a changed source file maps to no module, evaluate whether its directory qualifies as a new module:
+- the most specific detail targets that own eligible changed paths;
+- their necessary direct parent summary or pointer at each affected level;
+- a new detail target only when the eligible source change proves meaningful durable behavior and deterministic identity;
+- root only when module structure or its resolving module/group pointer changes.
 
-- Contains source files forming a logical unit
-- Contains entry/config/interface files
-- Contains qualifying submodules
-- Is referenced by multiple modules as a dependency
+Affected docs may be read to reconcile current content and resolve pointers, but they cannot independently add source facts or pull sibling docs into the writable set. Do not clean unrelated targets merely because they are stale or near a limit.
 
-## 3. Classify changes
+If a changed source path maps to no module, evaluate only that path and narrowly required directory context to determine whether its directory is a real logical module with entry/config/interface files or cross-module dependency use. Do not perform a repository scan to manufacture a module.
 
-- `A` added → add to KEY_FILES and check for new public interfaces
-- `D` deleted → remove from KEY_FILES and update file counts
-- `M` modified → check public interfaces, dependencies, data flow, and durable traps/decisions
-- `R` renamed → update path references
+## 3. Classify eligible structural changes
 
-## 4. Decide whether sync is needed
+- `A` added: update navigation only when the file passes the Value Gate; check source-established public/wire contracts.
+- `D` deleted: remove stale owned navigation and source-invalidated knowledge.
+- `M` modified: check non-obvious public/wire interfaces, dependencies, data flow, behavior, traps, rules, and decisions.
+- `R` renamed: update only implicated ownership and resolving paths.
 
-Skip structural sync when changes are limited to:
+Skip structural writes for comments, whitespace, formatting, internal implementation detail with no durable contract/behavior impact, and test-only changes that reveal no durable boundary. Do not skip a bug or test change when its exact source evidence changes durable behavior or constraints.
 
-- comments, whitespace, or formatting
-- internal implementation details with no interface, dependency, data-flow, or module mapping impact
-- test-only changes that reveal no durable boundaries, traps, interface constraints, behavior rules, or regression knowledge
+## 4. Select the most specific detail identity
 
-Do not skip automatically just because the task is a bug fix or test change. Run the relevant part of retrospective when the change affects structure, interfaces, dependencies, observable behavior, or durable knowledge.
+### Mirrored source identity
 
-## 5. Update affected docs bottom-up
+When identities compete, mirrored source identity takes precedence.
 
-### L2
+A real source submodule uses its mirrored detail path. Mirrored source identity takes precedence over a semantic concern with the same path or meaning. Update an existing mirrored detail before considering a semantic split.
 
-If L2 exists, update only sections affected by changed files in that module.
-
-If L2 does not exist and the current diff includes Added or Modified source files with meaningful logic, create L2 with:
+A new mirrored detail uses these required sections:
 
 ```text
 MODULE
 FILES
 RESPONSIBILITY
+INTERFACES
 KEY_FILES
 DEPENDENCIES
-INTERFACES
 TRAPS
 ```
 
-Add DATA_FLOW, RULES, or DECISIONS only when the changed files provide durable information for those sections. Populate from the diff files and targeted source reads, not from an unbounded full-module rescan.
+Add `DATA_FLOW`, `RULES`, `DECISIONS`, rejected alternatives, or domain sections only for facts that pass the Value Gate.
+
+### Deterministic semantic concern identity
+
+For a flat source module, create a semantic concern detail only when current eligible source proves multiple stable product/domain behavior concerns and protected durable knowledge cannot fit one 5120B detail after safe cleanup. A semantic concern is not another documentation level.
+
+Derive one deterministic concern slug:
+
+1. Choose a concise stable product/domain concern name from current source responsibility; task, change, file-count, or temporary initiative labels are invalid.
+2. Normalize the name with Unicode NFKC.
+3. Apply Unicode lowercase.
+4. Replace each maximal run of characters that is neither a Unicode letter nor a Unicode decimal digit with one ASCII hyphen.
+5. Trim leading/trailing hyphens and require one non-empty, unambiguous lowercase kebab-case result.
+6. Compare it with sibling semantic concerns, sibling `DETAILS` entries, and mirrored submodule paths. Task IDs, numeric suffixes, timestamps, and branch names are prohibited as collision workarounds.
+
+The detail path is `.prizmkit/prizm-docs/<module>/<concern-slug>.prizm`. It has `MODULE`, `CONCERN`, `FILES`, `RESPONSIBILITY`, `INTERFACES`, `DATA_FLOW`, `KEY_FILES`, `DEPENDENCIES`, `RULES`, `TRAPS`, and `DECISIONS`; use `<SECTION>: none` rather than invented filler when a required behavioral section has no qualifying fact.
+
+`FILES` is a non-empty exhaustive normalized source-file ownership list for the concern. Sibling semantic details require explicit non-overlapping `FILES` ownership. The direct module parent has exactly one `DETAILS` pointer:
+
+```text
+- <concern-slug>: <concise stable behavior summary> -> .prizmkit/prizm-docs/<module>/<concern-slug>.prizm
+```
+
+The pointer path, target `MODULE`, normalized `CONCERN` slug, and `FILES` ownership must agree. Mirrored source identity takes precedence; ambiguity, collision, or overlapping ownership blocks the split. Never add a suffix or partial semantic document to guess around it.
+
+## 5. Preflight every target before replacement
+
+For each target in the bounded writable set:
+
+1. Read current content and resolving parent/child pointers. For an existing target, preserve its exact pre-write bytes; for a new target, record that no pre-write file exists.
+2. Measure the current target before replacement using exact raw UTF-8 bytes, never characters, lines, rounded kilobytes, or locale-dependent encoding.
+3. Establish a protected set before cleanup. It includes every still-valid public or wire contract, CRITICAL/HIGH trap, data-flow or data-integrity constraint, security/concurrency/transaction/compatibility rule, cross-module rule, non-obvious dependency, side effect, and durable decision with necessary rationale.
+4. Build the complete candidate result before replacement. Match existing and candidate facts by meaning; update the canonical entry in place, merge synonyms, remove equivalent, stale, derivable, conflicting, duplicate, or parent-copied material, and never append another version of the same knowledge.
+5. Measure the candidate as exact raw UTF-8 bytes and classify both current and candidate against the target's level.
+
+Capacity limits and bands:
+
+- Exact root project map: hard limit 4096B.
+- Direct module index: hard limit 4096B.
+- Nested mirrored or semantic detail: hard limit 5120B.
+- normal: `size * 100 < limit * 80`.
+- warning: `size * 100 >= limit * 80` and `size * 100 < limit * 90`.
+- strong-warning: `size * 100 >= limit * 90` and `size <= limit`.
+- error: `size > limit`.
+
+When the current or candidate reaches at least 80%, perform the minimum safe cleanup or semantic split before final replacement:
+
+1. trim stale, source-derivable, procedural, historical, transient, and low-value wording;
+2. merge synonymous facts and remove duplicate meanings;
+3. move child-owned behavior from the root/module index into the existing or newly justified resolving detail;
+4. if one detail still cannot retain protected durable knowledge within 5120B, use the deterministic semantic split only when its stable identity and non-overlapping ownership are unambiguous.
+
+Aim for 3277–3686B for a root/module index and 4096–4607B for a detail document, preserving approximately 10% headroom. Do not pad naturally concise output and do not trim merely to one byte below a hard limit. A post-remediation warning-range result is valid; do not force a needless split when the minimum safe cleanup establishes the target range.
+
+Never remove protected knowledge solely to pass capacity validation. If it cannot fit after concise wording, safe movement, or an unambiguous split, do not replace that target.
+
+## 6. Write bottom-up
 
-### L1
+Prepare all candidates before the first replacement and write only after each candidate passes its local format, identity, protected-set, and capacity preflight.
 
-Update FILES count, KEY_FILES, SUBDIRS, and DEPENDENCIES when module-level structure changes.
+1. Create or update the most specific detail first.
+2. Re-read and validate that detail before modifying its parent.
+3. Update the direct module index only as concise summaries and resolving pointers, using `SUBDIRS` or `DETAILS` as applicable.
+4. Update the root project map last and only when module structure or its concise resolving pointer changed.
 
-L1 does not contain INTERFACES, DATA_FLOW, TRAPS, or DECISIONS; those belong in L2.
+Complete `INTERFACES`, `DATA_FLOW`, `TRAPS`, `DECISIONS`, and full RULES owned by a child must not be copied into the module index or root project map. Parent docs retain the shortest useful summary and pointer. Preserve any root `PROJECT_BRIEF:` line because it is managed separately.
 
-### L0
+Before each replacement, compare candidate bytes with current bytes. A byte-identical candidate is not written, reordered, or reported as an update.
 
-Update MODULE_INDEX or MODULE_GROUPS only when module structure changed. Preserve any `PROJECT_BRIEF:` line because it is managed by `/prizmkit-init`.
+## 7. Re-read and validate the actual final files
 
-## 6. New module handling
+After every write:
 
-If a new directory qualifies as a module and matches no existing module:
+1. Re-read the actual bytes from disk and recompute exact raw UTF-8 size.
+2. Reapply the 4096B/4096B/5120B hard limit and 80%/90% band formulas.
+3. Validate required KEY/value format and memory hygiene.
+4. Resolve every affected `MODULE_INDEX`, `MODULE_GROUPS`, `SUBDIRS`, and `DETAILS` pointer; validate both each changed target and its affected direct parent/child.
+5. Confirm semantic `MODULE`, `CONCERN`, path, slug, and `FILES` ownership agree and do not collide or overlap.
+6. Review only the targeted documentation diff for duplicate meanings, copied child behavior, unstable reorder, and unintended paths.
 
-1. Create L1 immediately.
-2. Add it to MODULE_INDEX or MODULE_GROUPS.
-3. Create L2 only when the current diff includes meaningful Added or Modified source files for the module.
+If any post-write check fails, restore every replaced target from its preserved exact pre-write bytes and remove any invalid newly created target. Re-read the restored affected set and ensure no invalid oversized final document remains. Restoration is a bounded file operation; never use Git reset, checkout, or stash.
 
-## 7. Size limits
+## 8. Capacity blocker evidence
 
-- L0 > 4KB → consolidate MODULE_INDEX or convert to MODULE_GROUPS when module count is high
-- L1 > 4KB → trim KEY_FILES descriptions and keep RULES concise
-- L2 > 5KB → remove derived detail or stale entries; keep durable knowledge only
+When no safe compression or stable split exists, stop with no invalid candidate left in place. The blocked result's `reason` must include:
 
-## 8. TRAPS staleness check
+- exact target path;
+- measured current bytes and/or candidate bytes, hard limit, and band;
+- protected knowledge that prevented trimming;
+- why attempted cleanup, movement, or identity/ownership checks could not establish a safe split;
+- a concrete recommended split boundary that a future manual decision can evaluate.
 
-Run only when an L2 doc's TRAPS section has more than 10 entries.
+Its `validation` contains only checks actually attempted. Its `documentation_paths` follows the result schema and never invents a change. `RETRO_COMPLETE` is prohibited after any unresolved capacity, pointer, format, or restoration check.
 
-Process at most 5 oldest TRAPS per L2 doc:
+## 9. Bounded TRAPS staleness check
 
-1. If a TRAP has `STALE_IF:` and matched files no longer exist, delete the TRAP.
-2. If a TRAP has `REF:` and the referenced file is gone or the commit is older than the review horizon, mark it `[REVIEW]` for the next knowledge pass.
+Run only for an affected detail target whose `TRAPS` section has more than 10 entries. Process at most five oldest traps:
 
-This bounds context cost and prevents unbounded trap accumulation.
+1. Delete a trap only when eligible source evidence proves it stale, including a `STALE_IF` path that no longer exists within the exact scope.
+2. If a `REF` cannot be validated from eligible evidence, retain the trap or mark it `[REVIEW]`; do not mine repository history or unrelated source to decide.
+3. Never remove a still-valid CRITICAL/HIGH trap merely for capacity.

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

@@ -1,13 +1,13 @@
 ---
 name: "prizmkit-test"
-description: "AI-led project-native testing for the complete affected business module and its Regression Ring. Adds comprehensive behavior, boundary, error, state, side-effect, permission, concurrency, idempotency, time, dependency, and consumer tests; repairs valid failures in a bounded loop; performs mandatory Main-Agent review plus one optional strict independent Test Reviewer; and returns TEST_PASS, TEST_NEEDS_FIXES, or TEST_BLOCKED with a human report and minimal terminal result. (project)"
+description: "Test one supplied current change with project-native affected-module and Regression Ring coverage. Use for contract testing, test-double fidelity, consumer/provider compatibility, browser and Full-stack E2E, persistence re-entry, and cross-boundary integration; returns TEST_PASS, TEST_NEEDS_FIXES, or TEST_BLOCKED with stage-owned report/result artifacts. (project)"
 ---
 
 # PrizmKit Test
 
 `/prizmkit-test` is the independent testing stage for the current workspace. It understands the affected business behavior, fills project-native test gaps, executes the tests, repairs valid failures, reviews the final tests, and reports a truthful testing-domain result.
 
-It does not build an evidence package, prove historical TDD order, validate a previous checkout, or manage pipeline/session state.
+It does not build an evidence package, prove historical TDD order, or validate a previous checkout.
 
 ## Atomic Skill Boundary
 
@@ -26,25 +26,21 @@ resolve current change and requirement context
 → return TEST_PASS | TEST_NEEDS_FIXES | TEST_BLOCKED
 ```
 
-After writing its result, this skill returns control to its caller. It must not:
-
-- invoke implementation, Code Review, retrospective, or committer;
-- update a workflow checkpoint or pipeline runtime state;
-- classify an AI CLI session as success, crash, retry, or continuation;
-- decide whether a workflow terminates or resumes;
-- call a testing-domain non-pass result a runtime failure.
+After writing its result, this Skill stops. It owns only testing-local source/test repairs and its two terminal artifacts. It does not invoke another Skill.
 
 ## Inputs and Outputs
 
 | Parameter | Required | Description |
 |---|---|---|
 | `scope` | No | `full-project`, `module:<name>`, `feature:<slug>`, or `this-change`. Defaults to `this-change` when current change context exists, otherwise `full-project`. |
-| `artifact_dir` | No | Active requirement directory containing available specification, plan, and prior review context. Reuse the caller-provided path. |
+| `artifact_dir` | Yes | Exact caller-supplied project-relative directory for the two terminal artifacts and any available specification, plan, and behavior context. Reuse it unchanged. |
 | `changed_files` | No | Explicit current changed paths. Highest-priority scope locator. |
 | `diff_base` | No | Git comparison base when explicit changed paths are absent. |
 | `test_commands` | No | Project-native commands when repository conventions are ambiguous. |
 
-Write exactly two terminal artifacts in `artifact_dir` when it is available; otherwise use a clearly reported caller-visible artifact directory selected from the active request context:
+Resolve `artifact_dir` before Test execution. In interactive use, ask the user to confirm an exact project-relative directory when omitted. In non-interactive use, a missing or unsafe directory is a response-only `TEST_BLOCKED` precondition failure: create no fallback directory or artifact and report that the caller must retry with `artifact_dir`. This precondition rejection is the sole case where terminal files cannot be written because their required identity is absent.
+
+For every invocation that passes input resolution, write exactly two terminal artifacts in the supplied `artifact_dir`:
 
 ```text
 {artifact_dir}/
@@ -52,16 +48,16 @@ Write exactly two terminal artifacts in `artifact_dir` when it is available; oth
 └── test-result.json
 ```
 
-Do not create `.prizmkit/test/evidence/`, manifests, hashes, attestations, package lifecycle records, or test-internal checkpoints.
+Do not create `.prizmkit/test/evidence/`, manifests, hashes, attestations, package state records, or test-internal checkpoints.
 
 ## Context Loading and Scope Resolution
 
 1. Reuse current requirement and workspace context already loaded by the Main Agent.
 2. Load `root.prizm`, the relevant module indexes, and the applicable detail docs before modifying source or tests.
 3. Inspect current staged, unstaged, untracked, deleted, and renamed paths. Changed lines locate impact but never define completeness.
-4. Read the available specification, acceptance criteria, plan, and prior review only as needed to establish expected behavior.
+4. Read the available specification, acceptance criteria, plan, and caller-supplied behavior context only as needed to establish expected behavior.
 5. Inspect manifests, runner configuration, CI conventions, existing test assertions, fixtures, fakes, mocks, contracts, and coverage support.
-6. If necessary scope cannot be determined safely, report the precise missing input and return `TEST_BLOCKED`.
+6. If necessary scope cannot be determined safely, report the precise missing input and return `TEST_BLOCKED` in the resolved artifact pair.
 
 Do not infer the active requirement solely from the name of an old artifact directory. Do not use a historical worktree, second checkout, mutation proof, baseline-failure proof, or test overlay.
 
@@ -101,29 +97,29 @@ Use the lowest layer that proves a property without losing relevant composition,
 
 ```text
 focused/unit
-→ module/component
-→ contract/integration
-→ code-level E2E when applicable
+→ module/component or UI component
+→ consumer/provider contract or integration
+→ Mock Browser or Full-stack E2E according to actual composition
 → complete affected-module regression
 → Regression Ring verification
 ```
 
-Do not mechanically test every private function. Add direct focused tests for critical low-level logic when complexity, boundaries, risk, or failure localization justify them; otherwise prove it through public behavior.
+Browser execution alone is not Full-stack E2E. Do not mechanically test every private function. Add direct focused tests for critical low-level logic when complexity, boundaries, risk, or failure localization justify them; otherwise prove it through public behavior.
 
 ## Test Construction
 
-Read `${SKILL_DIR}/references/test-coverage-model.md` and, when external or cross-module contracts apply, `${SKILL_DIR}/references/external-contract-mock-guidance.md`.
+Read `${SKILL_DIR}/references/test-coverage-model.md` and, whenever serialization, a producer-consumer boundary, or any test double replaces a producer or consumer, `${SKILL_DIR}/references/boundary-contract-and-test-double-guidance.md`.
 
-Expected behavior follows this precedence:
+Expected behavior follows boundary-specific authority:
 
-1. confirmed specification;
-2. machine-readable contract;
-3. acceptance criteria;
-4. trusted existing tests;
-5. callers and consumers;
-6. current implementation.
+1. confirmed specification and acceptance criteria;
+2. machine-readable wire contract;
+3. traceably generated type, client, server stub, or fixture;
+4. provider raw-wire contract evidence or authorized isolated observation;
+5. provider implementation, locked SDK behavior, and matching official documentation;
+6. trusted existing tests, callers and consumers, consumer-local types/fixtures/mocks, and other current implementation evidence.
 
-Conflicting higher-precedence truth that cannot be resolved is `TEST_BLOCKED`; do not preserve a possible implementation defect as a characterization test.
+Lower-authority material cannot override higher-authority truth or prove a property outside its boundary. Conflicts that cannot be resolved are `TEST_BLOCKED`; do not preserve a possible implementation defect as a characterization test.
 
 Tests must:
 
@@ -135,6 +131,20 @@ Tests must:
 - avoid vacuous assertions and assertions that merely duplicate implementation steps;
 - never delete or weaken a valid existing test just to obtain green output.
 
+## Boundary Contract and Composition Gate
+
+A test cannot prove a property that depends on production composition it replaces. Before test construction and again before `TEST_PASS`:
+
+1. Inventory every verdict-relevant mock, fake, fixture, route interception, mock server, container, emulator, or isolated service that crosses or replaces a producer-consumer boundary.
+2. Record its producer, consumer, boundary/protocol, contract authority, fidelity proof, composition removed, property not proven, composition-preserving test, and remaining risk.
+3. Treat consumer-local types, fixtures, and mocks as expectations, not provider truth, unless they are generated from or validated against the authoritative boundary contract.
+4. Classify tests by actual composition. An API-intercepted browser test is a Mock Browser Test, not Full-stack E2E.
+5. Require risk-relevant Provider Contract Tests to inspect raw wire payload before provider-owned deserialization.
+6. For any verdict-capable serialization or multi-layer risk in removed composition, require provider/consumer contract evidence, a composition-preserving integration test, or a Full-stack path appropriate to the risk and keeping the defect-bearing boundary real.
+7. For state-changing workflows, verify commit point, cancellation, pending/duplicate protection, failure recovery, reload or re-entry, retry/conflict/idempotency, and downstream consumption.
+
+If required composition-preserving evidence cannot run in a proven safe isolated environment, return `TEST_BLOCKED`. Never substitute a lower-layer green test or downgrade the proof requirement.
+
 Reuse an adequate existing framework. Add only the smallest necessary project-native infrastructure when a required property cannot otherwise be expressed.
 
 Minimal behavior-preserving testability seams are allowed, including dependency injection through an existing abstraction, pure-function extraction, an internal adapter, or controllable clock/randomness/state. Classify any production change under the repair boundary below.
@@ -145,13 +155,13 @@ The target project owns its runner, command, working directory, timeout, concurr
 
 During construction and repair, run the smallest relevant tests first. Before a pass decision, run all required layers, the complete affected-module regression, the Regression Ring, and project-wide regression when concrete coupling or project convention requires it.
 
-A nonzero execution is development feedback, not an immediate workflow stop. Classify it:
+A nonzero execution is testing feedback, not an immediate terminal result. Classify it:
 
 | Classification | Action |
 |---|---|
 | `test-defect` | Repair the test, fixture, mock, import, syntax, or test infrastructure. |
 | `local-production-defect` | Repair the proven internal implementation defect when public and cross-module contracts remain unchanged. |
-| `high-risk-production-defect` | Repair only when safe, then require delta Code Review and return `TEST_NEEDS_FIXES`. |
+| `high-risk-production-defect` | Do not repair it in this invocation; record the proven defect and return `TEST_NEEDS_FIXES`. |
 | `environment-unavailable` | Return `TEST_BLOCKED` with the unavailable safe prerequisite. |
 | `truth-unresolved` | Return `TEST_BLOCKED`; never guess the assertion. |
 | `flaky-or-unreliable` | Diagnose within budget; otherwise return `TEST_BLOCKED`. |
@@ -165,9 +175,9 @@ Never retry until green or weaken scope/assertions to manufacture a pass.
 
 ## Production Repair Boundary
 
-A repair may close inside this skill only when evidence establishes that it is limited to private/internal implementation, a behavior-preserving algorithm correction, test infrastructure, a behavior-preserving testability seam, or local error handling with unchanged public obligations.
+A repair may close inside this Skill only when evidence establishes that it is limited to private/internal implementation, a behavior-preserving algorithm correction, test infrastructure, a behavior-preserving testability seam, or local error handling with unchanged public obligations.
 
-Set `review_required=true` and `review_scope=delta` when a repair affects or may affect:
+Do not perform the repair in this invocation when it affects or may affect:
 
 - public API or observable public behavior;
 - schema, migration, serialization, or generated protocol shape;
@@ -178,7 +188,7 @@ Set `review_required=true` and `review_scope=delta` when a repair affects or may
 - compatibility guarantees;
 - any change whose locality cannot be established confidently.
 
-Record completed repairs and test results, return `TEST_NEEDS_FIXES`, and stop. Do not invoke Code Review or prescribe caller routing from this skill.
+Record the defect evidence and required correction, return `TEST_NEEDS_FIXES`, and stop. Do not prescribe or execute work outside this testing invocation.
 
 ## Mandatory Main-Agent Test Review
 
@@ -200,7 +210,10 @@ Every complete round checks:
 - critical low-level boundary logic;
 - incorrect truth precedence or expected behavior;
 - weak, vacuous, implementation-only, nondeterministic, or flaky assertions;
-- over-mocking, invented contracts, and missing negative side-effect assertions;
+- complete boundary/test-double inventory, boundary-appropriate authority, fidelity proof, and consumer-authored ideal fixtures not being treated as provider truth;
+- Provider raw-wire assertions, test-layer labels matching actual composition, and Browser Tests with intercepted critical APIs not being called Full-stack E2E;
+- any test that would still pass with the target defect, any verdict-capable composition removed without preserving evidence, and missing negative side-effect assertions;
+- state-changing workflow commit, cancellation, failure recovery, reload/re-entry, retry/conflict/idempotency, and repeated-operation coverage;
 - unjustified layer omissions or tests absent from actual native execution;
 - production repairs outside this skill's safe boundary.
 
@@ -244,17 +257,17 @@ Only after Main-Agent review converges, read `${SKILL_DIR}/references/independen
 - If response five still contains unresolved truth, input, or safety, return `TEST_BLOCKED`.
 - Never claim `TEST_PASS` for a final mutation that was not independently rechecked when independent review had already begun, unless the reference's strict downgrade rule establishes the permitted Main-Agent fallback.
 
-## External Services and Safety
+## Boundary Contracts and External Safety
 
-Read `${SKILL_DIR}/references/external-contract-mock-guidance.md` whenever an external service, persistence boundary, queue, filesystem, generated client, or cross-module endpoint affects the tested property.
+Read `${SKILL_DIR}/references/boundary-contract-and-test-double-guidance.md` for internal and external APIs, cross-module endpoints, persistence, queues, filesystems, caches, generated clients/servers, and any test double replacing a producer or consumer.
 
-- Prefer project-owned schemas, generated types, SDK interfaces, fixtures, and documentation.
-- Use approved retrieval of public official documentation only when project artifacts are insufficient.
+- Select authority for the property at the actual boundary; a database schema does not independently prove HTTP or message serialization.
+- Use approved retrieval of public official documentation only when higher-authority project artifacts are insufficient.
 - Never expose secrets, private source, proprietary payloads, or repository-private data during retrieval.
 - Never use production credentials, production databases/APIs/queues/storage, real user data, or destructive external operations.
 - If an endpoint cannot be proven non-production, do not connect to it.
-- Use contract-backed local fakes, mocks, fixtures, mock servers, containers, or project-owned isolated services.
-- Record necessary unverified external behavior as a remaining risk or `TEST_BLOCKED` when it prevents the verdict.
+- Use contract-backed local doubles or project-owned isolated services only within their stated proof boundary.
+- Missing fidelity or composition evidence that affects the verdict produces `TEST_BLOCKED`, not a conditional pass.
 
 ## Final Verification
 
@@ -262,11 +275,13 @@ Before writing `TEST_PASS`:
 
 1. Main-Agent review converged on the exact final state.
 2. Independent review converged or was strictly and visibly downgraded under its capability contract.
-3. Every required focused, module, contract/integration, applicable E2E, affected-module, and Regression Ring test passes reliably.
-4. Any required project-wide regression passes.
-5. No accepted correction, unresolved finding, verdict-capable scope edge, or required environment check remains.
-6. No high-risk production repair awaits delta Code Review.
-7. No mutation occurred after the final applicable review and execution.
+3. Every required focused, module/component, consumer/provider contract, integration, actual-composition E2E, affected-module, and Regression Ring test passes reliably.
+4. Every verdict-relevant test double has boundary-appropriate authority and fidelity proof, and every test-layer claim matches actual composition.
+5. Every verdict-capable property in removed composition has composition-preserving evidence; applicable Provider Contract Tests assert raw wire output and state-changing workflows cover the required lifecycle.
+6. Any required project-wide regression passes.
+7. No accepted correction, unresolved finding, verdict-capable scope edge, missing fidelity/composition proof, or required environment check remains.
+8. No high-risk production defect or correction remains.
+9. No mutation occurred after the final applicable review and execution.
 
 ## Terminal Results
 
@@ -276,15 +291,15 @@ Only these testing-domain outcomes are valid:
 TEST_PASS | TEST_NEEDS_FIXES | TEST_BLOCKED
 ```
 
-- `TEST_PASS`: final reviewed state passes every required native test and no high-risk repair awaits review.
-- `TEST_NEEDS_FIXES`: a known correction remains, a review/repair budget did not converge, or a completed high-risk repair requires delta Code Review.
+- `TEST_PASS`: final reviewed state passes every required native test and no high-risk correction remains.
+- `TEST_NEEDS_FIXES`: a known correction remains or a testing-local review/repair budget did not converge.
 - `TEST_BLOCKED`: expected truth, safe input, environment, execution reliability, external-target safety, or required review input prevents a safe verdict.
 
 No conditional pass exists.
 
 ## Terminal Report and Result
 
-Read `${SKILL_DIR}/references/test-report-template.md` before finalization. Write `test-report.md` and `test-result.json` together for every terminal outcome. The report must use the exact canonical `## Final Result` section and `- Result: <TEST_*>` marker from that template; do not rename it to `Terminal Result`, `Final Decision`, or another heading.
+Read `${SKILL_DIR}/references/test-report-template.md` before finalization. After required input resolution, write `test-report.md` and `test-result.json` together for every terminal outcome. The report must use the exact canonical `## Final Result` section and `- Result: <TEST_*>` marker from that template; do not rename it to `Terminal Result`, `Final Decision`, or another heading.
 
 `test-result.json` is a terminal projection, not a checkpoint:
 
@@ -302,12 +317,10 @@ Read `${SKILL_DIR}/references/test-report-template.md` before finalization. Writ
   },
   "repair_rounds": 1,
   "production_changed": false,
-  "review_required": false,
-  "review_scope": null,
   "unresolved_items": []
 }
 ```
 
-Allowed `independent_review.status` values are `completed`, `downgraded`, and `not_applicable`. `completed` requires one through five responses and `final_state_rechecked=true`; `downgraded` requires zero responses, a non-empty reason, and `final_state_rechecked=false`; `not_applicable` requires zero responses, no reason, and `final_state_rechecked=false`. `review_scope` is `delta` only when `review_required=true`; otherwise it is null. The report and JSON must agree on result, review requirement, and unresolved items. If consistency cannot be established, write a truthful `TEST_BLOCKED` result rather than fabricating pass.
+Allowed `independent_review.status` values are `completed`, `downgraded`, and `not_applicable`. `completed` requires one through five responses and `final_state_rechecked=true`; `downgraded` requires zero responses, a non-empty reason, and `final_state_rechecked=false`; `not_applicable` requires zero responses, no reason, and `final_state_rechecked=false`. `TEST_PASS` requires an empty `unresolved_items`; each non-pass result requires at least one exact unresolved correction or blocker. The report and JSON must agree on result, production-change diagnostics, and unresolved items. If consistency cannot be established, write a truthful `TEST_BLOCKED` result rather than fabricating pass.
 
-**HANDOFF:** Return the testing result plus `test-report.md` and `test-result.json` paths to the caller, then stop.
+Return only the testing result, `test-report.md`/`test-result.json` paths, execution summary, repair diagnostics, and unresolved items.