prizmkit 1.1.124 → 1.1.126

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

@@ -1,179 +0,0 @@
-# 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,118 +0,0 @@
-# Reviewer Workspace Protocol
-
-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.
-
-## Invariants
-
-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.
-
-## Deterministic Manifest
-
-Prefer `${SKILL_DIR}/scripts/workspace_snapshot.py` when Python and Git are available.
-
-The manifest contains:
-
-```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
-```
-
-Use path-safe Git output so spaces, Unicode, quoting, renames, and deletions remain unambiguous. A prose summary is not a deterministic manifest.
-
-## Review Payload
-
-Provide both:
-
-1. the complete manifest used for verification;
-2. a reviewable representation of every manifest entry.
-
-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.
-
-Supporting unchanged context must be clearly distinguished from changed content.
-
-## Content-Addressed Reuse
-
-Round one establishes the complete logical snapshot. Later rounds may transfer only changed blobs while referring to unchanged content by stable identity:
-
-```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, verify:
-
-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.
-
-On success, return `Snapshot Verification: VERIFIED` and proceed.
-
-On failure:
-
-```text
-### Result: WORKSPACE_MISMATCH
-
-### Snapshot Verification
-- Status: FAILED
-- Identity: <expected and observed identity>
-- Mismatch: <missing, extra, stale, mixed, or unverifiable entries>
-- Required action: <what snapshot preparation failed>
-```
-
-Do not emit ordinary findings after a mismatch.
-
-## Transport Preparation and Failure Boundary
-
-Before launch, snapshot transport may use:
-
-1. the preferred strategy;
-2. at most one alternate strategy.
-
-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
-
-After the Main Agent applies accepted fixes:
-
-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.
-
-Never reuse a Reviewer session or send historical findings to the fresh Reviewer.

package/bundled/skills/prizmkit-code-review/scripts/check_loop.py

@@ -1,380 +0,0 @@
-#!/usr/bin/env python3
-"""Strict execution and convergence gate for prizmkit-code-review protocol v2."""
-
-from __future__ import annotations
-
-import json
-import sys
-from typing import Any
-
-PROTOCOL_VERSION = 2
-REVIEW_SAFETY_LIMIT = 10
-
-CAPABILITY_FIELDS = {
-    "mutation_capability",
-    "delegation_equivalent_capability",
-    "downstream_execution_creation",
-    "orchestration_reentry_capability",
-    "review_execution",
-    "status",
-}
-PREFLIGHT_FIELDS = {
-    "protocol_version",
-    "gate_stage",
-    "round",
-    "reviewers_started_this_round",
-    "reviewers_started_total",
-    "fresh_reviewer",
-    "workspace_snapshot_ready",
-    "capability_attestation",
-}
-RESULT_BASE_FIELDS = {
-    "protocol_version",
-    "gate_stage",
-    "filtering_done",
-    "round",
-    "reviewers_started_this_round",
-    "reviewers_started_total",
-    "fresh_reviewer",
-    "descendant_execution_units_observed",
-    "delegation_depth_observed",
-    "capability_attestation",
-    "orchestration_status",
-    "workspace_status",
-    "review_complete",
-    "reviewer_result",
-    "findings_count",
-}
-RESULT_FILTER_FIELDS = {"accepted_count", "rejected_count"}
-
-
-class ProtocolError(ValueError):
-    """Raised when a payload violates the strict protocol schema."""
-
-
-def _is_int(value: Any) -> bool:
-    return isinstance(value, int) and not isinstance(value, bool)
-
-
-def _require_exact_fields(data: dict[str, Any], required: set[str]) -> None:
-    missing = sorted(required - data.keys())
-    unknown = sorted(data.keys() - required)
-    if missing:
-        raise ProtocolError(f"missing required fields: {', '.join(missing)}")
-    if unknown:
-        raise ProtocolError(f"unknown fields: {', '.join(unknown)}")
-
-
-def _require_bool(data: dict[str, Any], name: str) -> bool:
-    value = data[name]
-    if not isinstance(value, bool):
-        raise ProtocolError(f"{name} must be a boolean")
-    return value
-
-
-def _require_count(data: dict[str, Any], name: str) -> int:
-    value = data[name]
-    if not _is_int(value) or value < 0:
-        raise ProtocolError(f"{name} must be a non-negative integer")
-    return value
-
-
-def _require_round(data: dict[str, Any]) -> int:
-    current_round = _require_count(data, "round")
-    if not 1 <= current_round <= REVIEW_SAFETY_LIMIT:
-        raise ProtocolError(
-            f"round must be between 1 and {REVIEW_SAFETY_LIMIT}"
-        )
-    return current_round
-
-
-def _require_enum(data: dict[str, Any], name: str, allowed: set[str]) -> str:
-    value = data[name]
-    if value not in allowed:
-        choices = ", ".join(sorted(allowed))
-        raise ProtocolError(f"{name} must be one of: {choices}")
-    return value
-
-
-def _validate_protocol_header(data: dict[str, Any], stage: str) -> None:
-    if data["protocol_version"] != PROTOCOL_VERSION:
-        raise ProtocolError(
-            f"protocol_version must be {PROTOCOL_VERSION}"
-        )
-    if data["gate_stage"] != stage:
-        raise ProtocolError(f"gate_stage must be {stage}")
-
-
-def _validate_attestation(value: Any) -> bool:
-    if not isinstance(value, dict):
-        raise ProtocolError("capability_attestation must be an object")
-    _require_exact_fields(value, CAPABILITY_FIELDS)
-
-    unavailable_fields = (
-        "mutation_capability",
-        "delegation_equivalent_capability",
-        "downstream_execution_creation",
-        "orchestration_reentry_capability",
-    )
-    for name in unavailable_fields:
-        _require_enum(value, name, {"available", "unavailable"})
-    _require_enum(
-        value,
-        "review_execution",
-        {"foreground-single-authority", "unsupported"},
-    )
-    _require_enum(value, "status", {"FAILED", "VERIFIED"})
-
-    return (
-        value["status"] == "VERIFIED"
-        and value["review_execution"] == "foreground-single-authority"
-        and all(value[name] == "unavailable" for name in unavailable_fields)
-    )
-
-
-def _response(
-    *,
-    action: str,
-    verdict: str | None,
-    blocker_code: str | None = None,
-    launch_authorized: bool = False,
-    result_usable: bool = False,
-    end_loop: bool = False,
-    reason: str,
-) -> dict[str, Any]:
-    return {
-        "action": action,
-        "launchAuthorized": launch_authorized,
-        "resultUsable": result_usable,
-        "endLoop": end_loop,
-        "verdict": verdict,
-        "blockerCode": blocker_code,
-        "reason": reason,
-    }
-
-
-def check_preflight(data: dict[str, Any]) -> dict[str, Any]:
-    """Authorize one safe Reviewer launch or return a fail-closed blocker."""
-    _require_exact_fields(data, PREFLIGHT_FIELDS)
-    _validate_protocol_header(data, "preflight")
-    current_round = _require_round(data)
-    started_this_round = _require_count(data, "reviewers_started_this_round")
-    started_total = _require_count(data, "reviewers_started_total")
-    fresh_reviewer = _require_bool(data, "fresh_reviewer")
-    snapshot_ready = _require_bool(data, "workspace_snapshot_ready")
-    attested = _validate_attestation(data["capability_attestation"])
-
-    if started_this_round != 0:
-        raise ProtocolError(
-            "preflight requires reviewers_started_this_round to equal 0"
-        )
-    if started_total != current_round - 1:
-        raise ProtocolError(
-            "preflight reviewers_started_total must equal round - 1"
-        )
-    if not fresh_reviewer:
-        return _response(
-            action="STOP",
-            verdict="NEEDS_FIXES",
-            blocker_code="REVIEW_INFRASTRUCTURE_BLOCKED",
-            end_loop=True,
-            reason="Reviewer execution is not fresh",
-        )
-    if not snapshot_ready:
-        return _response(
-            action="STOP",
-            verdict="NEEDS_FIXES",
-            blocker_code="REVIEW_INFRASTRUCTURE_BLOCKED",
-            end_loop=True,
-            reason="Workspace snapshot is not ready",
-        )
-    if not attested:
-        return _response(
-            action="STOP",
-            verdict="NEEDS_FIXES",
-            blocker_code="REVIEW_INFRASTRUCTURE_BLOCKED",
-            end_loop=True,
-            reason="Mandatory Reviewer capability boundary is not verified",
-        )
-
-    return _response(
-        action="AUTHORIZE_LAUNCH",
-        verdict=None,
-        launch_authorized=True,
-        reason=f"Round {current_round} may launch one fresh Reviewer",
-    )
-
-
-def _validate_result_structure(data: dict[str, Any]) -> tuple[int, int, bool]:
-    filtering_done = _require_bool(data, "filtering_done")
-    required_fields = RESULT_BASE_FIELDS | (
-        RESULT_FILTER_FIELDS if filtering_done else set()
-    )
-    _require_exact_fields(data, required_fields)
-    _validate_protocol_header(data, "result")
-
-    current_round = _require_round(data)
-    started_this_round = _require_count(data, "reviewers_started_this_round")
-    started_total = _require_count(data, "reviewers_started_total")
-    fresh_reviewer = _require_bool(data, "fresh_reviewer")
-    _require_count(data, "descendant_execution_units_observed")
-    _require_count(data, "delegation_depth_observed")
-    _require_bool(data, "review_complete")
-    findings_count = _require_count(data, "findings_count")
-    reviewer_result = _require_enum(
-        data, "reviewer_result", {"NEEDS_FIXES", "PASS"}
-    )
-    _require_enum(
-        data,
-        "orchestration_status",
-        {"COMPLIANT", "UNVERIFIABLE", "VIOLATION"},
-    )
-    _require_enum(data, "workspace_status", {"MATCHED", "MISMATCH"})
-    _validate_attestation(data["capability_attestation"])
-
-    if started_this_round != 1:
-        raise ProtocolError(
-            "result requires exactly one Reviewer started in the round"
-        )
-    if started_total != current_round:
-        raise ProtocolError("result reviewers_started_total must equal round")
-    if not fresh_reviewer:
-        raise ProtocolError("result requires a fresh Reviewer execution")
-    if reviewer_result == "PASS" and findings_count != 0:
-        raise ProtocolError("PASS requires findings_count to equal 0")
-    if reviewer_result == "NEEDS_FIXES" and findings_count == 0:
-        raise ProtocolError("NEEDS_FIXES requires at least one finding")
-
-    if filtering_done:
-        accepted_count = _require_count(data, "accepted_count")
-        rejected_count = _require_count(data, "rejected_count")
-        if accepted_count + rejected_count != findings_count:
-            raise ProtocolError(
-                "accepted_count + rejected_count must equal findings_count"
-            )
-        if reviewer_result == "PASS" and (accepted_count or rejected_count):
-            raise ProtocolError("PASS cannot contain finding classifications")
-
-    return current_round, findings_count, filtering_done
-
-
-def check_result(data: dict[str, Any]) -> dict[str, Any]:
-    """Validate topology and workspace before filtering, then decide convergence."""
-    current_round, _, filtering_done = _validate_result_structure(data)
-    attested = _validate_attestation(data["capability_attestation"])
-
-    if (
-        not attested
-        or data["descendant_execution_units_observed"] != 0
-        or data["delegation_depth_observed"] != 0
-        or data["orchestration_status"] != "COMPLIANT"
-    ):
-        return _response(
-            action="STOP",
-            verdict="NEEDS_FIXES",
-            blocker_code="REVIEW_ORCHESTRATION_VIOLATION",
-            end_loop=True,
-            reason="Reviewer execution topology is non-compliant or unverifiable",
-        )
-
-    if data["workspace_status"] != "MATCHED":
-        return _response(
-            action="STOP",
-            verdict="NEEDS_FIXES",
-            blocker_code="WORKSPACE_MISMATCH",
-            end_loop=True,
-            reason="Reviewer workspace does not match the authorized snapshot",
-        )
-
-    if not data["review_complete"]:
-        return _response(
-            action="STOP",
-            verdict="NEEDS_FIXES",
-            blocker_code="INVALID_REVIEW_RESULT",
-            end_loop=True,
-            reason="Reviewer output is incomplete",
-        )
-
-    if not filtering_done:
-        if data["reviewer_result"] == "PASS":
-            return _response(
-                action="PASS",
-                verdict="PASS",
-                result_usable=True,
-                end_loop=True,
-                reason=f"Round {current_round} completed with no findings",
-            )
-        return _response(
-            action="AUTHORIZE_FILTERING",
-            verdict=None,
-            result_usable=True,
-            reason=f"Round {current_round} findings are authorized for filtering",
-        )
-
-    if data["accepted_count"] == 0:
-        return _response(
-            action="PASS",
-            verdict="PASS",
-            result_usable=True,
-            end_loop=True,
-            reason=f"Round {current_round} converged with zero accepted findings",
-        )
-
-    if current_round == REVIEW_SAFETY_LIMIT:
-        return _response(
-            action="STOP",
-            verdict="NEEDS_FIXES",
-            blocker_code="REVIEW_SAFETY_LIMIT_REACHED",
-            result_usable=True,
-            end_loop=True,
-            reason="Accepted findings remain at the internal safety limit",
-        )
-
-    return _response(
-        action="CONTINUE",
-        verdict=None,
-        result_usable=True,
-        reason=(
-            f"Round {current_round} has {data['accepted_count']} accepted "
-            "findings; repair and start a fresh complete review"
-        ),
-    )
-
-
-def check_gate(data: Any) -> dict[str, Any]:
-    """Validate a strict v2 payload and dispatch to the requested stage."""
-    if not isinstance(data, dict):
-        raise ProtocolError("input must be a JSON object")
-    stage = data.get("gate_stage")
-    if stage == "preflight":
-        return check_preflight(data)
-    if stage == "result":
-        return check_result(data)
-    raise ProtocolError("gate_stage must be preflight or result")
-
-
-def main() -> int:
-    try:
-        data = json.load(sys.stdin)
-        result = check_gate(data)
-    except (json.JSONDecodeError, ProtocolError) as error:
-        print(
-            json.dumps(
-                _response(
-                    action="STOP",
-                    verdict="NEEDS_FIXES",
-                    blocker_code="INVALID_REVIEW_RESULT",
-                    end_loop=True,
-                    reason=f"Invalid protocol payload: {error}",
-                ),
-                sort_keys=True,
-            )
-        )
-        return 1
-
-    print(json.dumps(result, sort_keys=True))
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())