prizmkit 1.1.120 → 1.1.121

package/bundled/skills/prizmkit-code-review/references/review-report-template.md

@@ -1,13 +1,16 @@
 # Review Report Output Template
 
-Used in Phase 2 of `/prizmkit-code-review`. Always write `review-report.md` to the artifact directory using this format.
+Used in Phase 2 of `/prizmkit-code-review`. Write `review-report.md` to the artifact directory using this format.
 
 ```markdown
 # Review Report
 
 ## Verdict: <PASS|NEEDS_FIXES>
-## Review Mode: <reviewer-agent-active-checkout|not-run-no-changes>
-## Rounds: <number of review rounds completed; use 0 for no-change PASS>
+## Review Mode: <independent-reviewer-verified-snapshot|not-run-no-changes>
+## Reviewer Strategy: <platform-selected strategy summary|not-applicable>
+## Snapshot Verification: <VERIFIED|FAILED|NOT_APPLICABLE>
+## Snapshot Identity: <manifest identity or failure reason>
+## Rounds: <number of completed review rounds; use 0 for no-change PASS or pre-review snapshot failure>
 ## Total findings: <total> → Fixed: <fixed>, Rejected: <rejected>, Unresolved: <unresolved>
 
 ## Round <N>
@@ -15,18 +18,20 @@ Findings: <count> | Accepted: <count>, Rejected: <count>
 
 ### Finding <N>: <short title>
 - Severity: <high|medium|low>
-- Dimension: <goal-alignment|defect|completeness|consistency|security|rules-compliance>
+- Dimension: <goal-alignment|defect|completeness|consistency|security|test-quality|rules-compliance>
 - Location: <filepath:line or project-level>
 - Problem: <what was wrong and why it mattered>
 - Status: <fixed (round N)|rejected — reason|unresolved — reason>
 
 ## Final Summary
-<One to three sentences summarizing the review outcome, including no-change PASS when applicable.>
+<One to three sentences summarizing the review outcome, snapshot verification, and any remaining blocker.>
 ```
 
-For `PASS` with no findings, write `Total findings: 0 → Fixed: 0, Rejected: 0, Unresolved: 0` and `## Round 0: PASS — no workspace changes to review` or `## Round N: PASS — no issues found`.
+For `PASS` with no findings, write `Total findings: 0 → Fixed: 0, Rejected: 0, Unresolved: 0` and either `## Round 0: PASS — no workspace changes to review` or `## Round N: PASS — no issues found`.
+
+For snapshot verification failure, use verdict `NEEDS_FIXES`, snapshot verification `FAILED`, and record the mismatch as an unresolved review blocker rather than an ordinary code finding.
 
 ## Verdict Rules
 
-- `PASS`: Reviewer returned no findings, no workspace changes existed, or all remaining findings were rejected as unreasonable.
-- `NEEDS_FIXES`: Max rounds completed but accepted findings remain unresolved.
+- `PASS`: Reviewer returned no findings from a verified snapshot, no workspace changes existed, or all findings from a verified snapshot were rejected as unreasonable.
+- `NEEDS_FIXES`: Max rounds completed with accepted findings unresolved, or no independent Reviewer could verify an equivalent current snapshot.

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

@@ -1,9 +1,9 @@
 # Reviewer Subagent Prompt Template
 
-Used in Phase 1 Step 1 of `/prizmkit-code-review`. The orchestrator fills `{goals}`, `{plan decisions}`, `{scoped test report}`, `{workspace context}`, `{dev rules}`, `{round N}`, and `{round_context}` before spawning an independent inline reviewer subagent from the active checkout.
+Used in Phase 1 Step 1 of `/prizmkit-code-review`. The orchestrator fills the placeholders before spawning an independent read-only Reviewer under `${SKILL_DIR}/references/reviewer-workspace-protocol.md`.
 
 ```
-You are an independent PrizmKit reviewer subagent launched by `/prizmkit-code-review` from the active checkout. Review workspace changes against the spec goals, plan decisions, scoped test evidence, and per-layer dev rules. Do not modify files and do not apply fixes; the Main Agent will filter findings and apply accepted fixes directly.
+You are the independent read-only Reviewer for `/prizmkit-code-review`. Review the verified workspace snapshot against the spec goals, plan decisions, scoped test evidence, and dev rules. Do not modify files or apply fixes; the Main Agent will filter findings and apply accepted fixes.
 
 ## Spec Goals
 {goals and acceptance criteria from spec.md}
@@ -12,53 +12,67 @@ You are an independent PrizmKit reviewer subagent launched by `/prizmkit-code-re
 {architecture decisions and task list from plan.md}
 
 ## Scoped Test Report
-{summary from artifact_dir/test-report-path.txt and test-report.md, including Scope, Generated / Updated Tests, In-Scope Failures, Baseline Failures, Out of Scope Gaps, Boundary Matrix / Boundary Completion Gate if present, and Verdict. If no scoped report exists for a change artifact, write "No scoped /prizmkit-test report found (expected for pre-test review)." Treat that absence as informational unless the calling workflow explicitly requires a prior test report.}
+{summary from artifact_dir/test-report-path.txt and test-report.md, including Scope, Generated / Updated Tests, In-Scope Failures, Baseline Failures, Out of Scope Gaps, Boundary Matrix / Boundary Completion Gate if present, and Verdict. If no scoped report exists, write "No scoped /prizmkit-test report found (expected for pre-test review)." Treat that absence as informational unless the calling workflow requires a prior report.}
 
-## Workspace Context
-{git status, unstaged diff summary, staged diff summary, current working directory, expected active checkout git top-level, and new-file paths captured by the Main Agent in Phase 0 from the active checkout. This is your primary review scope — use this context to understand what changed. Request targeted file reads only when you need specific line-level detail for a finding, not to re-discover or re-index the repository. Do not read files that are not in the workspace context unless you need them to verify impact (callers, dependents, shared patterns).}
+## Workspace Manifest
+{repository and baseline identity, review-round identity, changed path inventory and statuses, staged/unstaged composition, untracked content entries, delete markers, rename pairs, and stable content identities captured by the Main Agent}
 
-## Active Checkout Guard
-The orchestrator must provide the expected active checkout git top-level in Workspace Context. Before reviewing, verify that your current git top-level matches that expected active checkout.
+## Review Payload
+{the reviewable representation of every manifest entry, plus clearly identified unchanged context needed to evaluate callers, dependents, or shared patterns}
 
-If your current checkout is different, or appears to be under `.claude/worktrees/`, `.prizmkit/state/worktrees/`, a copied checkout, a remote isolated checkout, a temporary repository clone, or any branch/top-level other than the orchestrator-provided active checkout:
-- Stop immediately.
-- Do not review files.
-- Do not produce normal findings.
-- Report `WRONG_CHECKOUT` and state that `/prizmkit-code-review` cannot continue because the reviewer subagent was not started in the active checkout/no-worktree mode required by this skill.
+## Reviewer Strategy
+{concise description of how the current platform made the snapshot available. This is diagnostic context, not a required parameter contract.}
 
-Worktree, copied-checkout, remote-checkout, and branch-switched review are not supported by `/prizmkit-code-review`; do not continue even if the files appear similar. Do not request or create worktrees, copied repositories, branch switches, or remote checkouts.
+## Workspace Equivalence Guard
+Validate the supplied manifest and payload according to the Reviewer Workspace Protocol before normal review:
+- Every manifest path and state must be represented.
+- Staged, unstaged, untracked, deleted, and renamed changes must not be silently lost.
+- Changed content identities and review-round identity must match.
+- Unexplained changed paths, stale content, or unverifiable entries are mismatches.
 
-## Dev Rules (per-layer conventions)
+Do not reject a snapshot merely because its physical path, checkout layout, branch label, host, or transport differs from the Main Agent's environment. Content equivalence is the invariant.
+
+If equivalence cannot be proven:
+- Stop before normal review.
+- Do not produce ordinary findings.
+- Return `WORKSPACE_MISMATCH` with concrete mismatch evidence and required corrective action.
+
+## Dev Rules
 {rules from .prizmkit/rules/<layer>-rules.md, or "No custom dev rules configured — use general best practices."}
 
 ## Review Round
 Round {N}. {round_context}
 
 ## What to Review
-Use the orchestrator-provided workspace context as the source of truth for changed files:
-- For new files listed in workspace status, read their full content.
-- For modified files, read enough surrounding context to understand the change.
-- Do not edit files, stage changes, run test suites, spawn other agents, or invoke tools that modify the workspace.
-- Do not request or create worktrees — you are reviewing the active checkout's changes. The orchestrator has already captured the full diff and status context; re-discovering the whole repository is wasteful and unnecessary.
+Use the verified workspace snapshot as the primary review scope:
+- Read the full content of new files.
+- For modified files, read enough surrounding context to understand behavior and impact.
+- Read unchanged callers, dependents, or shared patterns only when needed to verify a potential finding.
+- Do not edit files, stage changes, run tools that modify the review view, spawn other agents, or apply fixes.
+- Do not broadly re-index the repository when the supplied snapshot and targeted reads are sufficient.
 
 ## Review Dimensions
-Evaluate the changes across these dimensions (focus on what's relevant):
+Evaluate the relevant dimensions:
 
-1. **Goal alignment**: Do the changes accomplish all goals from spec.md? Anything missing or off-target?
-2. **Defects**: Logic bugs, missing error handling, boundary condition issues, incorrect behavior.
-3. **Completeness**: Files that should have been changed but weren't? Missing tests, types, imports, exports?
-4. **Consistency**: Do changes follow the project's existing patterns, naming conventions, and code style?
-5. **Security**: Hardcoded secrets, injection vulnerabilities, unsafe operations.
-6. **Test quality**: If a scoped `/prizmkit-test` report is present, verify the report scope is `this-change`, the artifact dir matches the reviewed change, generated/updated tests assert real behavior rather than mock success or empty assertions, in-scope failures are not mislabeled as baseline failures, baseline failures are genuinely unrelated or pre-existing, out-of-scope gaps were not turned into unrelated test changes, and the report verdict is compatible with proceeding.
-7. **Rules compliance**: (Skip this dimension if no dev rules were provided.) Do changes follow the per-layer dev rules? Flag violations of framework conventions, naming patterns, state management, or other rules defined for that layer.
+1. **Goal alignment**: Do the changes accomplish the spec goals and acceptance criteria?
+2. **Defects**: Are there logic bugs, boundary failures, or missing error handling?
+3. **Completeness**: Are required files, tests, types, imports, or exports missing?
+4. **Consistency**: Do the changes follow existing project patterns, naming, and style?
+5. **Security**: Do the changes introduce secrets, injection paths, or unsafe operations?
+6. **Test quality**: When a scoped report exists, verify its scope and artifact identity, meaningful assertions, failure classification, boundary evidence, and verdict compatibility.
+7. **Rules compliance**: When dev rules exist, verify the relevant layer conventions.
 
 ## Output Format
-Respond with EXACTLY this format:
+Respond with exactly this structure:
+
+### Result: PASS | NEEDS_FIXES | WORKSPACE_MISMATCH
 
-### Result: PASS | NEEDS_FIXES | WRONG_CHECKOUT
+### Snapshot Verification
+- Status: VERIFIED | FAILED
+- Identity: <manifest identity or mismatch summary>
 
 ### Findings
-(If PASS, write "No issues found." If WRONG_CHECKOUT, include only checkout mismatch evidence and do not include normal review findings.)
+(If PASS, write "No issues found." If WORKSPACE_MISMATCH, include only mismatch evidence and required action.)
 
 #### Finding N
 - **Severity**: high | medium | low
@@ -69,10 +83,10 @@ Respond with EXACTLY this format:
 - **Verification**: How to confirm the fix is correct
 
 ### Summary
-One to two sentences about the overall state of the changes.
+One to two sentences about the snapshot and overall state of the changes.
 ```
 
 ## Round Context
 
 - Round 1: "This is the first review. Examine all changes comprehensively."
-- Round 2+: "Previous round found issues that were fixed. Focus on: (1) whether previous fixes are correct, (2) whether fixes introduced new problems, (3) any remaining issues. Do not re-report issues that have already been fixed."
+- Round 2+: "Previous findings were filtered and accepted fixes were applied. Verify those fixes, check for regressions, and identify remaining issues without re-reporting resolved findings."

package/bundled/skills/prizmkit-code-review/references/reviewer-workspace-protocol.md

@@ -0,0 +1,90 @@
+# Reviewer Workspace Protocol
+
+Use this protocol whenever `/prizmkit-code-review` delegates review to an independent Reviewer. The protocol defines observable guarantees, not Agent API parameters, so the Main Agent can adapt to the capabilities of the current platform.
+
+## Protocol Invariants
+
+1. **Independence**: A subagent separate from the Main Agent performs review judgment. The Main Agent may prepare the snapshot, filter findings, and apply fixes, but does not substitute its own review when delegation fails.
+2. **Completeness**: The review snapshot represents every in-scope staged, unstaged, untracked, deleted, and renamed change captured for the round.
+3. **Currency**: Each review round uses a snapshot captured after the previous round's fixes. Never reuse a prior-round snapshot as evidence of current state.
+4. **Equivalence**: The Reviewer's view must be content-equivalent to the captured Main-Agent workspace. Physical path, checkout layout, branch label, host, and transport may differ without violating equivalence.
+5. **Verifiability**: The Reviewer validates the supplied manifest before normal review. Missing, extra, stale, or mixed content produces `WORKSPACE_MISMATCH`, not code findings.
+6. **Read-only review**: The Reviewer does not modify files or apply fixes. This keeps review evidence stable and preserves clear fix ownership.
+
+## Strategy Selection
+
+Choose a platform-supported strategy that can satisfy all protocol invariants. The strategy may use a shared workspace, an isolated workspace populated with the captured change, a remote environment supplied with equivalent content, a materialized snapshot, or another mechanism the platform supports.
+
+Do not encode a particular Agent type, model, isolation value, branch convention, directory prefix, or transport command into the skill contract. Those details are implementation choices and may change across platforms or sessions.
+
+Prefer the least elaborate strategy that can prove equivalence. If a candidate strategy cannot carry or expose all workspace states, choose another strategy rather than weakening the protocol.
+
+## Workspace Manifest
+
+Create a manifest for each round containing enough information to detect an incomplete or stale review view:
+
+- repository identity and baseline revision
+- round number or equivalent monotonic round identity
+- changed path inventory and each path's status
+- staged and unstaged composition when both exist for a path
+- untracked file content required for review
+- deleted-path markers
+- rename source and destination pairs
+- stable content identities for changed content and any review-critical context
+- relevant spec, plan, dev-rule, and scoped-test evidence identities or embedded content
+
+The exact encoding is implementation-defined. Use hashes when available, but another deterministic content identity is acceptable when the environment lacks a hashing utility. A prose summary alone is insufficient when it cannot detect omitted or stale content.
+
+## Review Payload
+
+Provide the Reviewer with both:
+
+1. The manifest used for verification.
+2. A reviewable representation of every manifest entry.
+
+A reviewable representation may be workspace files, complete file content, patches plus required base content, or an equivalent materialization. Diff summaries alone are insufficient for new files or when surrounding code is necessary to evaluate behavior.
+
+Supply targeted dependency or caller context when required to verify impact. Keep that context distinguishable from changed content so the Reviewer does not mistake unchanged files for part of the patch.
+
+## Reviewer Verification
+
+Before normal review, the Reviewer checks:
+
+1. Repository and baseline identity are consistent with the supplied snapshot.
+2. Every changed path in the manifest is available in the review payload.
+3. No unexplained changed path appears outside the manifest.
+4. Staged, unstaged, untracked, deleted, and renamed states are represented without silent loss.
+5. Content identities match the manifest.
+6. The snapshot belongs to the current review round.
+
+When all checks pass, report snapshot verification as `VERIFIED` and proceed with review.
+
+When a check cannot be completed or fails, stop normal review and return:
+
+```text
+### Result: WORKSPACE_MISMATCH
+
+### Snapshot Verification
+- Status: FAILED
+- Mismatch: <missing, extra, stale, or unverifiable manifest entries>
+- Required action: <what the Main Agent must re-capture, transport, or verify>
+```
+
+Do not emit ordinary code findings after `WORKSPACE_MISMATCH`, because findings from an unverified snapshot could misrepresent the current change.
+
+## Round Refresh
+
+After accepted fixes are applied:
+
+1. Discard the previous manifest as current evidence.
+2. Capture a new manifest and review payload from the Main Agent's updated workspace.
+3. Establish a fresh independent Reviewer view using any valid strategy.
+4. Repeat Reviewer verification before the next review.
+
+A platform may reuse an existing Reviewer session only when the refreshed payload replaces stale state and equivalence is verified again.
+
+## Failure Boundary
+
+Retry or change strategy when the mismatch is repairable. Stop when the platform cannot provide an independent Reviewer with a verifiable equivalent snapshot.
+
+Record the failure as an unresolved review blocker with verdict `NEEDS_FIXES`, snapshot verification `FAILED`, and the mismatch evidence. Do not downgrade to Main-Agent self-review, because doing so would satisfy neither the independence invariant nor the user's expectation of an independent quality gate.