prizmkit 1.1.122 → 1.1.124

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,166 +1,175 @@
1
1
  ---
2
2
  name: "prizmkit-code-review"
3
- description: "Iterative independent review-fix loop against spec, plan, workspace changes, and test evidence. Establishes a verified review snapshot using any platform-supported subagent strategy while keeping review judgment separate from Main-Agent filtering and fixes. Use after /prizmkit-implement as a Full path quality gate or when the user asks to review, check code, validate implementation, or decide whether changes are ready to commit. Loops until PASS or max 3 rounds. (project)"
3
+ description: "Run a fail-closed, convergence-driven independent code review against the current spec, plan, complete workspace snapshot, applicable rules, contracts, and test evidence. Use after /prizmkit-implement, before commit when review is required, or whenever the user asks to review code, validate an implementation, find defects, assess regressions, or decide whether changes are ready. Each round launches exactly one fresh read-only non-delegating Reviewer, validates execution and workspace compliance, then has the Main Agent filter and directly fix accepted findings until PASS or the internal safety fuse stops review. (project)"
4
4
  ---
5
5
 
6
6
  # PrizmKit Code Review
7
7
 
8
- Run an iterative review-fix loop against the current change. Keep review judgment independent from fix application: an independent read-only Reviewer evaluates a verified snapshot, then the Main Agent filters findings and applies accepted fixes.
8
+ Run an independent review-fix loop until the current implementation converges. One fresh Reviewer performs each complete review; the Main Agent alone controls rounds, filters findings, and applies accepted fixes.
9
9
 
10
- Review modes:
11
- - `independent-reviewer-verified-snapshot`: an independent Reviewer verified that its review snapshot is equivalent to the Main Agent's current change.
12
- - `not-run-no-changes`: no workspace changes were detected.
10
+ The safety boundary is fail-closed. A Reviewer may run only when its execution environment makes workspace mutation, downstream execution creation, delegation-equivalent behavior, and orchestration re-entry unavailable. Prompt promises alone do not establish this boundary.
13
11
 
14
- The skill defines review invariants rather than platform tool parameters. Choose any platform-supported subagent launch and snapshot transport strategy that satisfies `${SKILL_DIR}/references/reviewer-workspace-protocol.md`.
12
+ ## When to Use
15
13
 
16
- If no independent Reviewer can receive and verify an equivalent snapshot, stop normal review and report the workspace verification failure. Do not replace the independent review with Main-Agent self-review because that would remove the separation between judgment and implementation.
17
-
18
- ### When to Use
19
14
  - After `/prizmkit-implement` as the Full path quality gate
20
- - For Fast path when risk, scope, or the user warrants review
21
- - When the user says "review", "check code", "review my implementation", or "is it ready to commit"
22
- - Before `/prizmkit-committer` when the chosen lifecycle path requires review
15
+ - For Fast path when scope, risk, or the user warrants review
16
+ - When the user asks to review code, validate implementation, find defects, check regressions, or assess commit readiness
17
+ - Before `/prizmkit-committer` when the selected lifecycle requires review
18
+
19
+ ## When Not to Use
23
20
 
24
- ### When NOT to Use
25
- - Direct edit or low-risk Fast path where review is not required
26
- - No `spec.md` or `plan.md` exists and there is no clear task goal to review against
27
- - Trivial typo, formatting, or config-only changes that the user wants committed directly
21
+ - Direct edit or low-risk Fast path where review is intentionally skipped
22
+ - No task goal, specification, plan, or other review contract can be identified
23
+ - Trivial changes the user explicitly wants committed without review
28
24
 
29
25
  ## Input
30
26
 
31
27
  | Parameter | Required | Description |
32
- |-----------|----------|-------------|
33
- | `artifact_dir` | No | Directory containing `spec.md` and `plan.md`. If omitted, scan `.prizmkit/` subdirectories for the most recently modified directory with a completed `plan.md`. When invoked as a handoff step, reuse the caller's `artifact_dir` rather than re-detecting. |
28
+ |---|---|---|
29
+ | `artifact_dir` | No | Directory containing `spec.md` and `plan.md`. Reuse a caller-provided directory. Otherwise locate the most recently modified completed change artifact under `.prizmkit/`. |
34
30
 
35
- ## Phase 0: Context and Snapshot
31
+ ## Authoritative Protocols
36
32
 
37
- 1. Read `spec.md` from the artifact directory and extract goals plus acceptance criteria.
38
- 2. Read `plan.md` from the artifact directory and extract architecture decisions plus completed tasks.
39
- 3. Read a scoped `/prizmkit-test` report when present:
40
- - If `{artifact_dir}/test-report-path.txt` exists, read the pointed report.
41
- - Extract Scope, Generated / Updated Tests, In-Scope Failures, Baseline Failures, Out of Scope Gaps, Boundary Matrix / Boundary Completion Gate, and Verdict when present.
42
- - If no report exists, pass `No scoped /prizmkit-test report found` as informational context. Treat missing tests as a finding only when the lifecycle path required testing before review.
43
- 4. Read dev rules when configured: load `.prizmkit/prizm-docs/root.prizm`, then referenced `.prizmkit/rules/<layer>-rules.md` files if any exist.
44
- 5. Capture the current workspace manifest and review payload according to `${SKILL_DIR}/references/reviewer-workspace-protocol.md`. Include:
45
- - baseline repository and revision identity
46
- - `git status`, `git diff`, and `git diff --cached` evidence
47
- - staged, unstaged, untracked, deleted, and renamed path inventory
48
- - changed content and stable content identities sufficient to detect missing, stale, or mixed snapshots
49
- - relevant root Prizm rules and plan decisions
50
- 6. If no changes are detected, skip Phase 1 and write `review-report.md` with verdict PASS, rounds 0, review mode `not-run-no-changes`, and snapshot verification `NOT_APPLICABLE`.
33
+ Read these references before starting Phase 1:
51
34
 
52
- ## Phase 1: Review-Fix Loop
35
+ - `${SKILL_DIR}/references/reviewer-execution-protocol.md`: mandatory execution topology, capability attestation, fail-closed behavior, and convergence rules
36
+ - `${SKILL_DIR}/references/reviewer-workspace-protocol.md`: deterministic complete snapshots, content identities, transport reuse, and mismatch handling
37
+ - `${SKILL_DIR}/references/reviewer-agent-prompt.md`: complete Reviewer prompt contract; fill placeholders without summarizing or omitting normative sections
38
+ - `${SKILL_DIR}/assets/reviewer-role.json`: canonical semantic capability manifest used by platform adapters to construct enforceable Reviewer roles
53
39
 
54
- ### Gate Mode Detection
40
+ The protocol describes semantic capabilities rather than a platform-specific command or tool denylist. Current platform names in references are non-normative recognition examples only.
55
41
 
56
- Check Python availability:
42
+ ## Phase 0: Context and Initial Snapshot
57
43
 
58
- ```bash
59
- python3 --version 2>/dev/null && echo "SCRIPT_MODE" || echo "TEXT_MODE"
60
- ```
44
+ 1. Read `spec.md` and extract goals plus acceptance criteria.
45
+ 2. Read `plan.md` and extract architecture decisions plus completed tasks.
46
+ 3. Read scoped `/prizmkit-test` evidence when `{artifact_dir}/test-report-path.txt` exists. Preserve scope, generated or updated tests, in-scope failures, baseline failures, gaps, boundary evidence, and verdict.
47
+ 4. Read `.prizmkit/prizm-docs/root.prizm` and applicable project rules. Load only relevant progressive documentation.
48
+ 5. Capture a content-equivalent complete current logical workspace according to the workspace protocol, including staged, unstaged, untracked, deleted, and renamed states. Prefer `${SKILL_DIR}/scripts/workspace_snapshot.py` when Python is available.
49
+ 6. If no changes exist, skip Reviewer launch and write a no-change `PASS` report with execution metadata `NOT_APPLICABLE`.
61
50
 
62
- - Script mode: use `${SKILL_DIR}/scripts/check_loop.py` for round tracking, max-round enforcement, and divergence detection.
63
- - Text mode: follow §Text Fallback Constraints manually with identical behavior.
51
+ ## Phase 1: Convergence Loop
64
52
 
65
- ### Step 0: Initialize Loop State
53
+ ### Loop State
66
54
 
67
- - `round = 1`
68
- - `max_rounds = 3`
69
- - `findings_history = []`
70
- - `review_mode = independent-reviewer-verified-snapshot` after snapshot verification succeeds
55
+ Track:
71
56
 
72
- ### Step 1: Establish Independent Review
57
+ ```yaml
58
+ round: 1
59
+ reviewers_started_total: 0
60
+ completed_rounds: 0
61
+ structured_result_state: <artifact_dir>/review-result-state.json
62
+ ```
73
63
 
74
- Use the skill-owned review contract:
64
+ The internal safety fuse is fixed at ten rounds. It is not caller-configurable, is not a quality target, and never converts unresolved review into `PASS`.
75
65
 
76
- ```yaml
77
- prompt_reference: ${SKILL_DIR}/references/reviewer-agent-prompt.md
78
- workspace_protocol: ${SKILL_DIR}/references/reviewer-workspace-protocol.md
79
- reviewer_contract: independent, read-only, workspace-equivalent
66
+ ### Step 1: Establish the Reviewer Boundary
67
+
68
+ 1. Select a fresh Reviewer execution mechanism that satisfies every invariant in the execution protocol.
69
+ 2. Establish launch-time capability attestation. Verify that mutation, delegation-equivalent behavior, downstream execution creation, and orchestration re-entry are unavailable.
70
+ 3. Ensure the Reviewer receives the complete authoritative prompt template and current snapshot, but no prior findings, verdicts, filtering decisions, Reviewer reasoning, or fix explanations.
71
+ 4. In script mode, authorize launch through the strict preflight gate:
72
+
73
+ ```bash
74
+ python3 ${SKILL_DIR}/scripts/check_loop.py < preflight-payload.json
80
75
  ```
81
76
 
82
- 1. Read both references and fill the Reviewer prompt with Phase 0 context plus the workspace manifest and payload.
83
- 2. Choose a subagent launch and snapshot transport strategy supported by the current platform. Strategy choice belongs to the Main Agent because platforms expose different capabilities; do not treat a particular tool parameter, checkout layout, branch name, or transport as part of the skill contract.
84
- 3. Require the Reviewer to verify snapshot equivalence before reviewing. Different physical paths or execution environments are acceptable when the verified review view is content-equivalent to the captured Main-Agent workspace.
85
- 4. If the Reviewer returns `WORKSPACE_MISMATCH`, repair or replace the strategy only when equivalence can be established safely. Otherwise write a `NEEDS_FIXES` report with the verification failure unresolved and stop; do not perform Main-Agent self-review.
86
- 5. After the Main Agent applies fixes, capture and verify a fresh snapshot for the next round because the previous snapshot is stale by definition.
77
+ 5. Launch exactly one foreground Reviewer only when the gate returns `launchAuthorized: true`.
87
78
 
88
- ### Step 2: Run Review
79
+ A platform-specific role may be used only when its actual launch configuration proves the semantic boundary. For example, an installed project role whose capability allowlist contains only observational file-inspection capabilities can establish the boundary; a generic subagent with prompt-only restrictions cannot.
89
80
 
90
- Round context:
91
- - Round 1: examine all current changes comprehensively.
92
- - Round 2+: verify prior fixes, look for regressions introduced by the fixes, and identify accepted findings that remain.
81
+ If the boundary cannot be established or attested, do not launch a weaker Reviewer and do not substitute Main-Agent self-review. Stop with `NEEDS_FIXES` and blocker `REVIEW_INFRASTRUCTURE_BLOCKED`.
93
82
 
94
- Review result:
95
- - `PASS`: no findings.
96
- - `NEEDS_FIXES`: one or more findings with severity, dimension, location, problem, and suggested fix.
97
- - `WORKSPACE_MISMATCH`: snapshot equivalence was not established; this is a review transport failure, not a code verdict.
83
+ ### Step 2: Complete Independent Review
98
84
 
99
- ### Step 3: Loop Exit Gate
85
+ The fresh Reviewer performs the complete review itself. Every round evaluates the complete current change against all applicable requirements, contracts, rules, callers, dependents, regression risks, and test evidence.
100
86
 
101
- Call the gate only when:
87
+ Later rounds are not historical fix verification. They remain complete independent reviews of current code and receive no previous-round finding context.
102
88
 
103
- 1. Review returned `PASS`.
104
- 2. The Main Agent has filtered `NEEDS_FIXES` findings.
89
+ The Reviewer uses two-direction inspection inside the same execution:
105
90
 
106
- Do not call the gate for `NEEDS_FIXES` before filtering because `accepted_count` is not known. Handle `WORKSPACE_MISMATCH` through Step 1 rather than passing it to the code-verdict gate.
91
+ - Code-forward: changed code affected symbols callers and dependents concrete failure scenarios
92
+ - Requirement-backward: requirements and contracts → required behavior → implementation path → side effects → test evidence
107
93
 
108
- Script mode invocation:
94
+ Prefer direct read-only inspection, existing valid evidence, and the narrowest verification that can establish or refute a concrete issue. Broad verification is allowed when a concrete cross-cutting risk requires it and narrower evidence is insufficient.
109
95
 
110
- ```bash
111
- echo '{"reviewer_result":"NEEDS_FIXES","accepted_count":2,"findings_count":3,"round":1,"findings_history":[],"max_rounds":3,"filtering_done":true}' | python3 ${SKILL_DIR}/scripts/check_loop.py
112
- ```
96
+ ### Step 3: Validate Reviewer Output Before Consumption
97
+
98
+ Before reading, filtering, or acting on any finding, run the result gate with `filtering_done: false`.
113
99
 
114
- The gate output determines whether to end the loop. If `divergenceWarning` is true, warn the user that the loop may not be converging.
100
+ The result is usable only when all of these are proven:
115
101
 
116
- ### Text Fallback Constraints
102
+ - exactly one fresh Reviewer started in the round;
103
+ - capability attestation remains verified;
104
+ - descendant execution-unit count is zero;
105
+ - delegation depth is zero;
106
+ - orchestration status is compliant;
107
+ - workspace identity is matched;
108
+ - output is complete and structurally valid.
117
109
 
118
- When Python is unavailable, apply these rules manually:
110
+ On orchestration violation or unverifiable topology:
119
111
 
120
- 1. `PASS` exits with verdict PASS.
121
- 2. `NEEDS_FIXES` continues to filtering before any all-rejected or max-round exit.
122
- 3. If all findings are rejected after filtering, exit with verdict PASS.
123
- 4. If `round >= 3` after filtering and accepted findings remain, exit with verdict NEEDS_FIXES.
124
- 5. If findings count strictly increases for 3 consecutive recorded rounds, warn about possible divergence.
125
- 6. Record `findings_history` once per round and increment `round` after a complete review/filter/fix cycle.
112
+ 1. Stop the Reviewer and identifiable descendants on a best-effort basis.
113
+ 2. Discard all Reviewer output without consuming findings.
114
+ 3. Do not count the round as completed, retry it, or launch another Reviewer.
115
+ 4. Stop Code Review with `NEEDS_FIXES` and `REVIEW_ORCHESTRATION_VIOLATION`.
116
+
117
+ On post-launch workspace mismatch, discard the output and stop with `NEEDS_FIXES` and `WORKSPACE_MISMATCH`. Do not launch a replacement Reviewer in that round.
126
118
 
127
119
  ### Step 4: Main Agent Filters Findings
128
120
 
129
- For each finding, decide whether it is reasonable:
121
+ Only after the pre-filter result gate authorizes consumption, classify every finding:
122
+
123
+ - `accepted`: a concrete issue that cannot be refuted with current evidence;
124
+ - `rejected`: not a defect, out of scope under the governing contract, or disproven with concrete evidence.
130
125
 
131
- - Is the finding relevant to the current changes?
132
- - Is it a real problem rather than a subjective style preference?
133
- - Would the fix improve the code without broad out-of-scope refactoring?
134
- - Does the finding conflict with the spec, plan, dev rules, or current test evidence?
126
+ Do not reject a finding because it is inconvenient, uncertain, or low confidence. If a potentially valid defect cannot be concretely refuted, accept it for repair or leave it unresolved with `NEEDS_FIXES` when repair is unsafe.
135
127
 
136
- Output per finding:
137
- - Accepted: queue for direct Main Agent fix work.
138
- - Rejected: record a short reason such as out of scope, not a defect, or too risky for the current task.
128
+ Call the result gate again with `filtering_done: true`, `accepted_count`, and `rejected_count`. Its internal action controls the loop:
139
129
 
140
- After filtering, call the Loop Exit Gate. If `endLoop=true`, proceed to Phase 2.
130
+ - `PASS`: no accepted findings remain;
131
+ - `CONTINUE`: accepted findings remain before the safety limit;
132
+ - `STOP`: a blocker exists or round ten remains non-converged.
133
+
134
+ `CONTINUE` and `STOP` are orchestration actions, not external verdicts.
141
135
 
142
136
  ### Step 5: Main Agent Applies Accepted Fixes
143
137
 
144
- The Main Agent applies accepted findings directly in its current workspace. Keeping fix ownership with the Main Agent prevents the read-only Reviewer from becoming a second, conflicting implementation authority.
138
+ When the gate returns `CONTINUE`:
139
+
140
+ 1. The Main Agent directly applies the accepted batch in the current workspace. Do not launch a separate Fixer or Dev Agent.
141
+ 2. If a repair cannot be completed safely within scope, stop with `NEEDS_FIXES` and record the unresolved finding.
142
+ 3. Capture a fresh complete snapshot after fixes.
143
+ 4. Increment `round`, create a new execution identity, and return to Step 1.
144
+
145
+ Do not send the next Reviewer any prior finding, filtering, or repair history.
146
+
147
+ ### Text Fallback
148
+
149
+ When Python is unavailable, manually enforce the same protocol and state transitions. Text fallback removes only script automation; it does not weaken capability attestation, one-Reviewer topology, result validation, output-discard rules, workspace matching, convergence, or the ten-round safety fuse.
145
150
 
146
- If an accepted finding cannot be fixed safely within scope, record the reason and carry the finding into `review-report.md` as unresolved.
151
+ If exact validation cannot be performed manually, fail closed with `REVIEW_INFRASTRUCTURE_BLOCKED` rather than guessing compliance.
152
+
153
+ ## Phase 2: Persist and Report
154
+
155
+ Persist the minimum structured result needed to regenerate the report before rendering Markdown. Include final verdict, blocker code, completed rounds, Reviewers started, execution metadata, snapshot identities, and accepted, rejected, fixed, or unresolved findings.
156
+
157
+ Write `{artifact_dir}/review-report.md` using `${SKILL_DIR}/references/review-report-template.md`. Prefer deterministic rendering:
158
+
159
+ ```bash
160
+ python3 ${SKILL_DIR}/scripts/render_review_report.py \
161
+ {artifact_dir}/review-result-state.json \
162
+ {artifact_dir}/review-report.md
163
+ ```
147
164
 
148
- After fixes are complete, record results, increment the round, capture a fresh workspace snapshot, and return to Step 1.
165
+ If report rendering or path verification fails after review completed, regenerate the report from `review-result-state.json`. Do not rerun Code Review.
149
166
 
150
- ## Phase 2: Output
167
+ External verdicts are limited to:
151
168
 
152
- Write `review-report.md` to the artifact directory, including no-change PASS and workspace-verification failure results. Read `${SKILL_DIR}/references/review-report-template.md` for the full output format.
169
+ - `PASS`: a usable completed round leaves zero accepted findings, or no workspace changes existed;
170
+ - `NEEDS_FIXES`: code findings remain unresolved or any review infrastructure, execution, workspace, result, or safety blocker prevents valid completion.
153
171
 
154
- Required report fields:
155
- - Verdict: `PASS` or `NEEDS_FIXES`
156
- - Review Mode: `independent-reviewer-verified-snapshot` or `not-run-no-changes`
157
- - Reviewer Strategy: concise strategy summary without relying on platform-specific parameter names
158
- - Snapshot Verification: `VERIFIED`, `FAILED`, or `NOT_APPLICABLE`
159
- - Snapshot Identity: manifest identity or failure reason
160
- - Rounds and total findings
161
- - Fixed, rejected, and unresolved findings
162
- - Final summary
172
+ Completion handoff:
163
173
 
164
- Completion summary:
165
- - `PASS`: hand off to `/prizmkit-retrospective` when docs or durable knowledge changed, otherwise `/prizmkit-committer`.
166
- - `NEEDS_FIXES`: inform the caller of unresolved code findings or snapshot-verification blockers.
174
+ - `PASS`: run `/prizmkit-retrospective` when structural docs or durable knowledge changed; otherwise proceed to `/prizmkit-committer`.
175
+ - `NEEDS_FIXES`: report unresolved findings or the diagnostic blocker and stop.
@@ -0,0 +1,21 @@
1
+ {
2
+ "protocol_version": 1,
3
+ "role_name": "prizmkit-code-reviewer",
4
+ "description": "Use only as the single fresh independent Reviewer launched by /prizmkit-code-review after its strict preflight gate authorizes the round.",
5
+ "observational_capabilities": [
6
+ "read-files",
7
+ "search-content",
8
+ "search-paths"
9
+ ],
10
+ "unavailable_capabilities": [
11
+ "workspace-mutation",
12
+ "shell-execution",
13
+ "downstream-execution-creation",
14
+ "delegation-equivalent-behavior",
15
+ "orchestration-reentry",
16
+ "skill-invocation"
17
+ ],
18
+ "execution_mode": "foreground-single-authority",
19
+ "max_descendant_execution_units": 0,
20
+ "max_delegation_depth": 0
21
+ }
@@ -1,37 +1,53 @@
1
1
  # Review Report Output Template
2
2
 
3
- Used in Phase 2 of `/prizmkit-code-review`. Write `review-report.md` to the artifact directory using this format.
3
+ Use this template to render `{artifact_dir}/review-report.md` from the persisted structured result. Report regeneration must not rerun Reviewer execution.
4
4
 
5
5
  ```markdown
6
6
  # Review Report
7
7
 
8
8
  ## Verdict: <PASS|NEEDS_FIXES>
9
+ ## Rounds Completed: <number>
10
+ ## Reviewers Started: <number>
9
11
  ## Review Mode: <independent-reviewer-verified-snapshot|not-run-no-changes>
10
- ## Reviewer Strategy: <platform-selected strategy summary|not-applicable>
12
+ ## Reviewer Strategy: <semantic strategy summary|not-applicable>
13
+ ## Execution Protocol: <COMPLIANT|BLOCKED|VIOLATION|NOT_APPLICABLE>
14
+ ## Capability Attestation: <VERIFIED|FAILED|NOT_APPLICABLE>
15
+ ## Descendant Execution Units Observed: <number>
16
+ ## Delegation Depth Observed: <number>
11
17
  ## Snapshot Verification: <VERIFIED|FAILED|NOT_APPLICABLE>
12
- ## Snapshot Identity: <manifest identity or failure reason>
13
- ## Rounds: <number of completed review rounds; use 0 for no-change PASS or pre-review snapshot failure>
14
- ## Total findings: <total> → Fixed: <fixed>, Rejected: <rejected>, Unresolved: <unresolved>
18
+ ## Snapshot Identity: <identity|failure reason|not-applicable>
19
+ ## Blocker Code: <REVIEW_INFRASTRUCTURE_BLOCKED|REVIEW_ORCHESTRATION_VIOLATION|WORKSPACE_MISMATCH|REVIEW_SAFETY_LIMIT_REACHED|INVALID_REVIEW_RESULT|NONE>
20
+ ## Total Findings: <total> → Fixed: <fixed>, Rejected: <rejected>, Unresolved: <unresolved>
15
21
 
16
22
  ## Round <N>
17
- Findings: <count> | Accepted: <count>, Rejected: <count>
23
+
24
+ - Snapshot Identity: <identity>
25
+ - Reviewer Execution Identity: <identity>
26
+ - Result: <PASS|NEEDS_FIXES>
27
+ - Findings: <count>
28
+ - Accepted: <count>
29
+ - Rejected: <count>
18
30
 
19
31
  ### Finding <N>: <short title>
32
+
20
33
  - Severity: <high|medium|low>
21
- - Dimension: <goal-alignment|defect|completeness|consistency|security|test-quality|rules-compliance>
22
- - Location: <filepath:line or project-level>
34
+ - Dimension: <dimension>
35
+ - Location: <filepath:line|project-level>
23
36
  - Problem: <what was wrong and why it mattered>
24
- - Status: <fixed (round N)|rejected — reason|unresolved — reason>
37
+ - Failure Scenario: <concrete input or state>
38
+ - Status: <fixed in round N|rejected — concrete evidence|unresolved — reason>
25
39
 
26
40
  ## Final Summary
27
- <One to three sentences summarizing the review outcome, snapshot verification, and any remaining blocker.>
28
- ```
29
41
 
30
- 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`.
31
-
32
- 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.
42
+ <One to three sentences covering the valid review outcome and any remaining blocker. Do not expose Reviewer reasoning traces.>
43
+ ```
33
44
 
34
- ## Verdict Rules
45
+ ## Report Rules
35
46
 
36
- - `PASS`: Reviewer returned no findings from a verified snapshot, no workspace changes existed, or all findings from a verified snapshot were rejected as unreasonable.
37
- - `NEEDS_FIXES`: Max rounds completed with accepted findings unresolved, or no independent Reviewer could verify an equivalent current snapshot.
47
+ - No-change review starts no Reviewer, uses zero completed rounds, and records execution plus snapshot metadata as `NOT_APPLICABLE`.
48
+ - Findings from a violating or mismatched Reviewer are discarded and excluded from totals.
49
+ - A violating or mismatched round is not completed.
50
+ - `PASS` requires no workspace changes or a usable complete Reviewer result with zero accepted findings.
51
+ - The ten-round safety fuse with accepted findings is `NEEDS_FIXES`, never `PASS`.
52
+ - Only `PASS` and `NEEDS_FIXES` are external verdicts. Blocker codes are diagnostic metadata.
53
+ - Persist structured state before Markdown rendering so a report-only failure can be recovered without repeating review.
@@ -1,92 +1,138 @@
1
- # Reviewer Subagent Prompt Template
1
+ # Reviewer Prompt Contract
2
2
 
3
- 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`.
3
+ Use this complete template for every Reviewer execution in Phase 1. Fill documented placeholders only. Do not summarize, shorten, or omit the execution boundary, complete-review scope, independence boundary, workspace guard, or output contract.
4
4
 
5
- ```
6
- 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.
5
+ ```text
6
+ You are the sole independent read-only Reviewer for this round of `/prizmkit-code-review`.
7
+
8
+ ## Execution Boundary
9
+
10
+ Perform the complete review yourself.
11
+
12
+ Do not create, schedule, resume, continue, request, or coordinate any separate downstream execution unit. Do not re-enter orchestration, delegation, another review workflow, or an equivalent process directly or indirectly. Do not ask the Main Agent to create a helper on your behalf.
13
+
14
+ Do not modify, create, delete, rename, stage, or commit workspace files. Do not run a command or tool that changes the review view.
15
+
16
+ If you cannot complete the review within this execution context, stop and return `REVIEW_INFRASTRUCTURE_BLOCKED`. Do not delegate or provide a partial PASS.
17
+
18
+ ## Independent Input Boundary
19
+
20
+ Review only the current state supplied below. No prior Reviewer findings, verdicts, filtering decisions, repair descriptions, or Reviewer reasoning are part of your input. Do not infer that an earlier Reviewer found every defect, and do not attempt historical reconciliation.
7
21
 
8
22
  ## Spec Goals
23
+
9
24
  {goals and acceptance criteria from spec.md}
10
25
 
11
26
  ## Plan Decisions
27
+
12
28
  {architecture decisions and task list from plan.md}
13
29
 
14
- ## Scoped Test Report
15
- {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.}
30
+ ## Applicable Rules and Contracts
31
+
32
+ {relevant Prizm docs, project rules, public and internal contracts, or "No additional project rules identified."}
33
+
34
+ ## Scoped Test Evidence
35
+
36
+ {current test report summary and identities. If absent, write "No scoped /prizmkit-test report found." Treat absence as informational unless the lifecycle contract required prior test evidence.}
16
37
 
17
38
  ## Workspace Manifest
18
- {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}
39
+
40
+ {repository identity, baseline identity, snapshot identity, path inventory, change states, staged and unstaged composition, rename/delete state, content identities, and supporting-context identities}
19
41
 
20
42
  ## Review Payload
21
- {the reviewable representation of every manifest entry, plus clearly identified unchanged context needed to evaluate callers, dependents, or shared patterns}
43
+
44
+ {complete logical representation of every manifest entry plus distinguishable unchanged caller and dependent context}
22
45
 
23
46
  ## Reviewer Strategy
24
- {concise description of how the current platform made the snapshot available. This is diagnostic context, not a required parameter contract.}
47
+
48
+ {concise diagnostic description of how this platform established observational access and made mutation, downstream execution, delegation-equivalent behavior, and orchestration re-entry unavailable}
25
49
 
26
50
  ## Workspace Equivalence Guard
27
- Validate the supplied manifest and payload according to the Reviewer Workspace Protocol before normal review:
28
- - Every manifest path and state must be represented.
29
- - Staged, unstaged, untracked, deleted, and renamed changes must not be silently lost.
30
- - Changed content identities and review-round identity must match.
31
- - Unexplained changed paths, stale content, or unverifiable entries are mismatches.
32
-
33
- 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.
34
-
35
- If equivalence cannot be proven:
36
- - Stop before normal review.
37
- - Do not produce ordinary findings.
38
- - Return `WORKSPACE_MISMATCH` with concrete mismatch evidence and required corrective action.
39
-
40
- ## Dev Rules
41
- {rules from .prizmkit/rules/<layer>-rules.md, or "No custom dev rules configured — use general best practices."}
42
-
43
- ## Review Round
44
- Round {N}. {round_context}
45
-
46
- ## What to Review
47
- Use the verified workspace snapshot as the primary review scope:
48
- - Read the full content of new files.
49
- - For modified files, read enough surrounding context to understand behavior and impact.
50
- - Read unchanged callers, dependents, or shared patterns only when needed to verify a potential finding.
51
- - Do not edit files, stage changes, run tools that modify the review view, spawn other agents, or apply fixes.
52
- - Do not broadly re-index the repository when the supplied snapshot and targeted reads are sufficient.
53
-
54
- ## Review Dimensions
55
- Evaluate the relevant dimensions:
56
-
57
- 1. **Goal alignment**: Do the changes accomplish the spec goals and acceptance criteria?
58
- 2. **Defects**: Are there logic bugs, boundary failures, or missing error handling?
59
- 3. **Completeness**: Are required files, tests, types, imports, or exports missing?
60
- 4. **Consistency**: Do the changes follow existing project patterns, naming, and style?
61
- 5. **Security**: Do the changes introduce secrets, injection paths, or unsafe operations?
62
- 6. **Test quality**: When a scoped report exists, verify its scope and artifact identity, meaningful assertions, failure classification, boundary evidence, and verdict compatibility.
63
- 7. **Rules compliance**: When dev rules exist, verify the relevant layer conventions.
64
-
65
- ## Output Format
51
+
52
+ Validate the manifest and payload before ordinary review:
53
+
54
+ 1. Every manifest path and state is represented.
55
+ 2. Staged, unstaged, untracked, deleted, and renamed changes are preserved.
56
+ 3. Content and snapshot identities match.
57
+ 4. Supporting caller or dependent context is distinguishable from changed content.
58
+ 5. No unexplained changed path, stale content, mixed-round content, or unverifiable entry exists.
59
+
60
+ Physical path, checkout layout, host, or transport may differ. Content-equivalent current state is the invariant.
61
+
62
+ If equivalence cannot be proven, stop before ordinary review and return `WORKSPACE_MISMATCH` with concrete mismatch evidence. Do not return code findings from an unverified snapshot.
63
+
64
+ ## Complete Current-State Review
65
+
66
+ Review the complete current change set independently. Do not limit inspection to files changed by the latest repair or to previously identified categories.
67
+
68
+ Evaluate applicable dimensions:
69
+
70
+ 1. Requirement and acceptance-criteria alignment
71
+ 2. Implementation completeness
72
+ 3. Correctness and concrete failure scenarios
73
+ 4. Error handling
74
+ 5. Security and authorization
75
+ 6. Data integrity
76
+ 7. Transaction and concurrency behavior
77
+ 8. Public and internal contracts
78
+ 9. Backward compatibility and regression risks
79
+ 10. Test adequacy and evidence compatibility
80
+ 11. Project-rule compliance
81
+
82
+ Use both inspection directions inside this one review:
83
+
84
+ - Code-forward: changed code affected symbols callers and dependents → concrete failure scenarios
85
+ - Requirement-backward: requirements and contracts required behavior implementation path → side effects → test evidence
86
+
87
+ Read unchanged callers, dependents, or shared patterns when needed to evaluate impact.
88
+
89
+ ## Review Efficiency
90
+
91
+ Complete the review directly instead of delegating it. Prefer direct read-only inspection and targeted verification.
92
+
93
+ Use existing valid test evidence when it answers the question. Prefer the narrowest verification that can establish or refute a concrete issue. Do not rerun an equivalent check when relevant code and inputs have not changed.
94
+
95
+ Avoid broad builds, tests, lint, or type checks as exploratory defaults. A broad command remains valid when a concrete cross-cutting risk genuinely requires it; state why narrower evidence is insufficient.
96
+
97
+ Non-normative examples:
98
+
99
+ - A repository-wide test or build without a concrete reason is often redundant with the formal Test Gate.
100
+ - A focused module or test-case invocation is usually better when investigating one failure scenario.
101
+
102
+ These examples do not prohibit command names. The governing rule is targeted, non-duplicative evidence gathering.
103
+
104
+ ## Finding Coverage
105
+
106
+ Report every concrete issue you find, including uncertain or low-severity issues. Do not filter for importance or confidence; the Main Agent performs downstream filtering. Exclude pure style or naming preferences that cannot cause incorrect behavior, contract drift, regression, security weakness, or misleading evidence.
107
+
108
+ ## Output Contract
109
+
66
110
  Respond with exactly this structure:
67
111
 
68
- ### Result: PASS | NEEDS_FIXES | WORKSPACE_MISMATCH
112
+ ### Result: PASS | NEEDS_FIXES | WORKSPACE_MISMATCH | REVIEW_INFRASTRUCTURE_BLOCKED
113
+
114
+ ### Execution Compliance
115
+ - Status: COMPLIANT | BLOCKED
116
+ - Descendant execution units created: 0
117
+ - Delegation depth: 0
69
118
 
70
119
  ### Snapshot Verification
71
120
  - Status: VERIFIED | FAILED
72
- - Identity: <manifest identity or mismatch summary>
121
+ - Identity: <snapshot identity or mismatch summary>
73
122
 
74
123
  ### Findings
75
- (If PASS, write "No issues found." If WORKSPACE_MISMATCH, include only mismatch evidence and required action.)
124
+ (If PASS, write "No issues found." If WORKSPACE_MISMATCH or REVIEW_INFRASTRUCTURE_BLOCKED, include only blocker evidence and required action.)
76
125
 
77
126
  #### Finding N
78
- - **Severity**: high | medium | low
79
- - **Dimension**: goal-alignment | defect | completeness | consistency | security | test-quality | rules-compliance
80
- - **Location**: filepath:line (or "project-level")
81
- - **Problem**: What is wrong and why it matters
82
- - **Suggestion**: Recommended fix approach
83
- - **Verification**: How to confirm the fix is correct
127
+ - Severity: high | medium | low
128
+ - Confidence: high | medium | low
129
+ - Dimension: requirement-alignment | defect | completeness | error-handling | security | data-integrity | concurrency | contract | compatibility | test-quality | rules-compliance
130
+ - Location: filepath:line (or "project-level")
131
+ - Problem: concrete wrong behavior and why it matters
132
+ - Failure scenario: inputs or state that produce the wrong result
133
+ - Suggestion: recommended repair approach
134
+ - Verification: how to prove the repair
84
135
 
85
136
  ### Summary
86
- One to two sentences about the snapshot and overall state of the changes.
137
+ One or two sentences describing the verified current state and overall result. Do not expose private reasoning traces.
87
138
  ```
88
-
89
- ## Round Context
90
-
91
- - Round 1: "This is the first review. Examine all changes comprehensively."
92
- - 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."