prizmkit 1.1.123 → 1.1.124

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

@@ -0,0 +1,179 @@
+# Reviewer Execution Protocol
+
+This protocol is the mandatory execution contract for `/prizmkit-code-review`. It defines semantic guarantees rather than platform tool, agent, workflow, or command names.
+
+## Terms
+
+| Term | Meaning |
+|---|---|
+| Orchestrator | The single Main Agent that controls rounds, filters findings, and applies accepted fixes |
+| Reviewer | The single independent read-only review authority for one round |
+| Downstream execution unit | Any separately scheduled or executed worker, reviewer, task, workflow child, team member, remote job, or equivalent delegated execution |
+| Delegation-equivalent capability | Any capability that can create, schedule, resume, continue, request, or coordinate downstream execution |
+| Orchestration re-entry | Entering a process that can delegate, fan out, or become another review orchestrator |
+| Capability attestation | Launch-time evidence that the Reviewer environment satisfies the mandatory capability boundary |
+| Completed round | A round whose Reviewer output passed execution and workspace validation |
+| Convergence | A completed round leaves zero accepted findings |
+| Safety fuse | The internal ten-round automation limit |
+
+## Normative Invariants
+
+```yaml
+reviewer_execution:
+  sole_review_authority_per_round: true
+  fresh_execution_per_round: true
+  observational_workspace_access: true
+  mutation_capability: unavailable
+  delegation_equivalent_capability: unavailable
+  orchestration_reentry_capability: unavailable
+  max_reviewers_per_round: 1
+  max_descendant_execution_units: 0
+  max_delegation_depth: 0
+  normal_termination: convergence
+  internal_safety_review_limit: 10
+```
+
+Additional invariants:
+
+1. Only the Main Agent starts a Reviewer or the next round.
+2. A Reviewer cannot create, request, continue, resume, refresh, replace, or coordinate another execution unit.
+3. A Reviewer cannot invoke an equivalent review orchestrator.
+4. A Reviewer performs the complete review itself and cannot delegate a subset.
+5. If the review does not fit its execution context, it returns `REVIEW_INFRASTRUCTURE_BLOCKED` rather than delegating.
+6. Reviewer output is unusable until execution and workspace validation both pass.
+7. Every round uses a fresh execution identity. Reviewer sessions are never reused.
+8. A Reviewer receives no prior findings, verdicts, filtering decisions, repair descriptions, or reasoning.
+9. The Main Agent applies accepted fixes directly; it does not create a separate Fixer or Dev Agent.
+
+## Capability Attestation
+
+Before every launch, establish this claim with platform-native evidence:
+
+```yaml
+capability_attestation:
+  mutation_capability: unavailable
+  delegation_equivalent_capability: unavailable
+  downstream_execution_creation: unavailable
+  orchestration_reentry_capability: unavailable
+  review_execution: foreground-single-authority
+  status: VERIFIED
+```
+
+A prompt promise is not evidence. The selected execution environment must actually remove the prohibited capabilities through a capability-scoped role, restricted tool surface, sandbox policy, launch wrapper, capability token, or equivalent mechanism.
+
+If the platform cannot establish the boundary:
+
+```text
+Do not launch Reviewer
+→ verdict: NEEDS_FIXES
+→ blockerCode: REVIEW_INFRASTRUCTURE_BLOCKED
+```
+
+## One-Reviewer Topology
+
+Required topology:
+
+```text
+Main Agent
+├── Round 1: one fresh Reviewer, no descendants
+├── Round 2: one fresh Reviewer, no descendants
+├── ...
+└── Round N: one fresh Reviewer, no descendants
+```
+
+The Main Agent owns all loop state. No Reviewer may start its successor.
+
+## Execution Validation
+
+Validate topology before consuming output:
+
+1. Exactly one fresh Reviewer started in the active round.
+2. Capability attestation is `VERIFIED`.
+3. Observed descendant execution units equal zero.
+4. Observed delegation depth equals zero.
+5. Orchestration status is `COMPLIANT`.
+6. Execution evidence is sufficient to support those claims.
+
+The Reviewer's own compliance declaration is supplementary. It never replaces launch-time attestation or platform-observed evidence.
+
+## Runtime Violation
+
+A violation exists when a Reviewer creates or requests downstream execution, re-enters orchestration, causes more than one Reviewer in a round, exceeds zero delegation depth, or makes compliance unverifiable.
+
+On violation:
+
+1. Stop the Reviewer and identifiable descendants on a best-effort basis.
+2. Discard the complete Reviewer output.
+3. Do not consume or filter findings.
+4. Do not count the round as completed.
+5. Do not retry or start another Reviewer.
+6. Terminate Code Review.
+7. Return `NEEDS_FIXES` with `REVIEW_ORCHESTRATION_VIOLATION`.
+
+Cleanup success is not required to declare failure.
+
+## Complete Independent Review
+
+Every valid round reviews the complete current implementation against the complete applicable specification, plan, rules, contracts, callers, dependents, and test evidence. Later rounds are not finding reconciliation or fix-only verification.
+
+A fresh Reviewer may independently rediscover an unresolved defect or find a defect earlier Reviewers missed. Historical findings are intentionally withheld to avoid anchoring.
+
+## Convergence and Safety Fuse
+
+Normal completion occurs only when a usable completed round leaves zero accepted findings:
+
+- the Reviewer reports no findings; or
+- the Main Agent rejects every finding with concrete evidence.
+
+When accepted findings remain, the Main Agent repairs the accepted batch and starts a fresh complete round.
+
+The internal limit is ten Reviewer executions. Rounds one through ten may return `PASS` when they converge. If round ten leaves accepted findings:
+
+```text
+Do not apply another automatic repair
+Do not start round 11
+→ verdict: NEEDS_FIXES
+→ blockerCode: REVIEW_SAFETY_LIMIT_REACHED
+```
+
+## External Verdicts and Blockers
+
+External verdicts:
+
+```text
+PASS
+NEEDS_FIXES
+```
+
+Diagnostic blocker codes:
+
+```text
+REVIEW_INFRASTRUCTURE_BLOCKED
+REVIEW_ORCHESTRATION_VIOLATION
+WORKSPACE_MISMATCH
+REVIEW_SAFETY_LIMIT_REACHED
+INVALID_REVIEW_RESULT
+```
+
+A blocker code is metadata, not a third verdict.
+
+## Non-Normative Recognition Examples
+
+These examples help identify prohibited semantics but do not define compliance:
+
+- starting another Agent to inspect a subsystem;
+- invoking a Workflow that fans out workers;
+- entering another code-review Skill;
+- asking a task runner or Main Agent to create a helper on the Reviewer's behalf;
+- creating a remote review job;
+- resuming a stopped helper or successor execution.
+
+A future capability with a different name remains prohibited when it creates or coordinates downstream execution.
+
+## Platform Mapping
+
+A platform mapping is valid only when its actual launch configuration proves all normative capabilities.
+
+For a current platform that supports project-defined subagent roles and a strict capability allowlist, a role containing only observational file-inspection capabilities can satisfy the launch boundary. Omitting downstream-execution and skill-orchestration capabilities is required; a deny instruction in prose is insufficient.
+
+Platforms without an equivalent enforceable role or launch restriction are unsupported for independent Reviewer execution and fail closed. Platform support may be added later through canonical adapters or runtime launchers without changing this protocol.

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

@@ -1,90 +1,118 @@
 # 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.
+Use this protocol for every `/prizmkit-code-review` round. Workspace equivalence and execution compliance are independent requirements; both must pass before Reviewer output is usable.
 
-## Protocol Invariants
+## 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.
+1. **Complete logical view**: represent staged, unstaged, untracked, deleted, and renamed changes plus required unchanged callers and dependents.
+2. **Currency**: capture a new snapshot after every accepted repair batch.
+3. **Equivalence**: the Reviewer's logical view matches the captured Main-Agent workspace even when physical location or transport differs.
+4. **Determinism**: the same repository state and inputs produce the same manifest identity.
+5. **Verifiability**: missing, extra, stale, mixed, or unverifiable content produces `WORKSPACE_MISMATCH`.
+6. **Execution separation**: a matched workspace does not prove the non-delegating execution boundary, and execution compliance does not prove workspace equivalence.
+7. **Main-Agent ownership**: only the Main Agent refreshes snapshots or launches successor Reviewers.
 
-## Strategy Selection
+## Deterministic Manifest
 
-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.
+Prefer `${SKILL_DIR}/scripts/workspace_snapshot.py` when Python and Git are available.
 
-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.
+The manifest contains:
 
-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.
+```text
+protocol version
+repository identity
+baseline identity
+snapshot identity
+path inventory
+change type
+staged and unstaged composition
+rename and delete state
+content identity for available blobs
+supporting-context identity
+```
 
-## Workspace Manifest
+Use path-safe Git output so spaces, Unicode, quoting, renames, and deletions remain unambiguous. A prose summary is not a deterministic manifest.
 
-Create a manifest for each round containing enough information to detect an incomplete or stale review view:
+## Review Payload
 
-- 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
+Provide both:
 
-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.
+1. the complete manifest used for verification;
+2. a reviewable representation of every manifest entry.
 
-## Review Payload
+A representation may be workspace files, complete content, patches plus required base content, or equivalent materialization. Diff summaries alone are insufficient for new files or findings that depend on surrounding code.
 
-Provide the Reviewer with both:
+Supporting unchanged context must be clearly distinguished from changed content.
 
-1. The manifest used for verification.
-2. A reviewable representation of every manifest entry.
+## Content-Addressed Reuse
 
-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.
+Round one establishes the complete logical snapshot. Later rounds may transfer only changed blobs while referring to unchanged content by stable identity:
 
-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.
+```text
+current logical workspace
+= unchanged content-addressed blobs
++ current-round changed blobs
++ current complete manifest
+```
+
+Reuse optimizes transport, never review scope. Every Reviewer remains responsible for the complete current change.
 
 ## Reviewer Verification
 
-Before normal review, the Reviewer checks:
+Before normal review, verify:
 
-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.
+1. repository and baseline identity;
+2. every path and state in the manifest is represented;
+3. no unexplained changed path exists outside the manifest;
+4. staged, unstaged, untracked, deleted, and renamed states are preserved;
+5. content identities match;
+6. supporting-context identities match;
+7. the snapshot belongs to the active round.
 
-When all checks pass, report snapshot verification as `VERIFIED` and proceed with review.
+On success, return `Snapshot Verification: VERIFIED` and proceed.
 
-When a check cannot be completed or fails, stop normal review and return:
+On failure:
 
 ```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>
+- Identity: <expected and observed identity>
+- Mismatch: <missing, extra, stale, mixed, or unverifiable entries>
+- Required action: <what snapshot preparation failed>
 ```
 
-Do not emit ordinary code findings after `WORKSPACE_MISMATCH`, because findings from an unverified snapshot could misrepresent the current change.
+Do not emit ordinary findings after a mismatch.
 
-## Round Refresh
+## Transport Preparation and Failure Boundary
 
-After accepted fixes are applied:
+Before launch, snapshot transport may use:
 
-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.
+1. the preferred strategy;
+2. at most one alternate strategy.
 
-A platform may reuse an existing Reviewer session only when the refreshed payload replaces stale state and equivalence is verified again.
+Both attempts occur before a Reviewer starts. Do not spend the one-Reviewer budget on transport discovery.
+
+After launch, any mismatch makes the Reviewer output unusable and terminates Code Review:
+
+```text
+Discard output
+Do not launch a replacement Reviewer
+→ verdict: NEEDS_FIXES
+→ blockerCode: WORKSPACE_MISMATCH
+```
+
+This prevents workspace repair from becoming another unbounded Reviewer loop.
+
+## Round Refresh
 
-## Failure Boundary
+After the Main Agent applies accepted fixes:
 
-Retry or change strategy when the mismatch is repairable. Stop when the platform cannot provide an independent Reviewer with a verifiable equivalent snapshot.
+1. retain prior identities only as internal report evidence;
+2. capture a new complete manifest and payload;
+3. reuse unchanged blobs by content identity where supported;
+4. create a fresh Reviewer execution identity;
+5. repeat workspace verification.
 
-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.
+Never reuse a Reviewer session or send historical findings to the fresh Reviewer.