prizmkit 1.1.123 → 1.1.125

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

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""Render the final review-report.md from minimal review data."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+VERDICTS = {"PASS", "NEEDS_FIXES", "BLOCKED"}
+DISPOSITIONS = ("fixed", "rejected", "unresolved")
+
+
+class ReportStateError(ValueError):
+    """Raised when review data cannot produce a valid final report."""
+
+
+def _require_count(data: dict[str, Any], name: str) -> int:
+    value = data.get(name)
+    if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+        raise ReportStateError(f"{name} must be a non-negative integer")
+    return value
+
+
+def validate_data(data: Any) -> dict[str, Any]:
+    if not isinstance(data, dict):
+        raise ReportStateError("review data must be a JSON object")
+
+    verdict = data.get("verdict")
+    if verdict not in VERDICTS:
+        raise ReportStateError(f"verdict has invalid value: {verdict!r}")
+
+    rounds_completed = _require_count(data, "rounds_completed")
+    if rounds_completed > 10:
+        raise ReportStateError("rounds_completed cannot exceed ten")
+
+    findings = data.get("findings")
+    if not isinstance(findings, list):
+        raise ReportStateError("findings must be an array")
+
+    summary = data.get("summary")
+    if not isinstance(summary, str) or not summary.strip():
+        raise ReportStateError("summary must be a non-empty string")
+
+    for index, finding in enumerate(findings, start=1):
+        if not isinstance(finding, dict):
+            raise ReportStateError(f"finding {index} must be an object")
+        required = {
+            "title",
+            "severity",
+            "location",
+            "problem",
+            "failure_scenario",
+            "disposition",
+        }
+        missing = sorted(required - finding.keys())
+        if missing:
+            raise ReportStateError(
+                f"finding {index} missing fields: {', '.join(missing)}"
+            )
+        disposition = finding["disposition"]
+        if not isinstance(disposition, str) or not disposition.startswith(DISPOSITIONS):
+            raise ReportStateError(f"finding {index} has invalid disposition")
+
+    unresolved = sum(
+        finding["disposition"].startswith("unresolved") for finding in findings
+    )
+    blocker = data.get("blocker")
+
+    if verdict == "PASS" and unresolved:
+        raise ReportStateError("PASS cannot contain unresolved findings")
+    if verdict == "NEEDS_FIXES" and not unresolved:
+        raise ReportStateError("NEEDS_FIXES requires an unresolved finding")
+    if verdict == "BLOCKED":
+        if not isinstance(blocker, str) or not blocker.strip():
+            raise ReportStateError("BLOCKED requires a non-empty blocker")
+        if unresolved:
+            raise ReportStateError("BLOCKED cannot classify code findings as unresolved")
+    elif blocker is not None:
+        raise ReportStateError("only BLOCKED may include blocker")
+
+    return data
+
+
+def _finding_totals(findings: list[dict[str, Any]]) -> tuple[int, int, int]:
+    fixed = sum(finding["disposition"].startswith("fixed") for finding in findings)
+    rejected = sum(
+        finding["disposition"].startswith("rejected") for finding in findings
+    )
+    unresolved = sum(
+        finding["disposition"].startswith("unresolved") for finding in findings
+    )
+    return fixed, rejected, unresolved
+
+
+def render_report(data: Any) -> str:
+    valid = validate_data(data)
+    findings = valid["findings"]
+    fixed, rejected, unresolved = _finding_totals(findings)
+
+    lines = [
+        "# Review Report",
+        "",
+        f"## Verdict: {valid['verdict']}",
+        f"## Rounds Completed: {valid['rounds_completed']}",
+        f"## Total Findings: {len(findings)} → Fixed: {fixed}, Rejected: {rejected}, Unresolved: {unresolved}",
+        "",
+    ]
+
+    if findings:
+        lines.extend(["## Findings", ""])
+        for index, finding in enumerate(findings, start=1):
+            lines.extend(
+                [
+                    f"### Finding {index}: {finding['title']}",
+                    "",
+                    f"- Severity: {finding['severity']}",
+                    f"- Location: {finding['location']}",
+                    f"- Problem: {finding['problem']}",
+                    f"- Failure Scenario: {finding['failure_scenario']}",
+                    f"- Disposition: {finding['disposition']}",
+                    "",
+                ]
+            )
+
+    if valid["verdict"] == "BLOCKED":
+        lines.extend(["## Blocker", "", valid["blocker"], ""])
+
+    lines.extend(["## Summary", "", valid["summary"], ""])
+    return "\n".join(lines)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("output", type=Path, help="review-report.md destination")
+    parser.add_argument(
+        "input",
+        nargs="?",
+        type=Path,
+        help="optional JSON input path; reads standard input when omitted",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        raw = args.input.read_text(encoding="utf-8") if args.input else sys.stdin.read()
+        data = json.loads(raw)
+        report = render_report(data)
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(report, encoding="utf-8")
+    except (OSError, json.JSONDecodeError, ReportStateError, KeyError) as error:
+        print(json.dumps({"error": str(error)}, sort_keys=True))
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.123",
+  "version": "1.1.125",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {

package/src/scaffold.js

@@ -226,10 +226,12 @@ export async function installSkills(platform, skills, projectRoot, dryRun, runti
 
   // Load Claude command adapter for skill conversion
   let convertSkillToCommand;
+  let getClaudeSkillAgentDefinitions;
   let convertSkillToCodex;
   if (platform === 'claude') {
     const commandAdapter = await loadAdapter('claude', 'command-adapter.js');
     convertSkillToCommand = commandAdapter.convertSkillToCommand;
+    getClaudeSkillAgentDefinitions = commandAdapter.getClaudeSkillAgentDefinitions;
   } else if (platform === 'codex') {
     const codexSkillAdapter = await loadAdapter('codex', 'skill-adapter.js');
     convertSkillToCodex = codexSkillAdapter.convertSkill;
@@ -321,6 +323,19 @@ export async function installSkills(platform, skills, projectRoot, dryRun, runti
           await fs.copy(path.join(corePath, subdir), path.join(assetTargetDir, subdir));
         }
       }
+
+      const roleManifestPath = path.join(corePath, 'assets', 'reviewer-role.json');
+      const roleManifest = await fs.pathExists(roleManifestPath)
+        ? await fs.readJson(roleManifestPath)
+        : null;
+      const agentDefinitions = getClaudeSkillAgentDefinitions(skillName, roleManifest);
+      if (agentDefinitions.length > 0) {
+        const agentsDir = path.join(projectRoot, '.claude', 'agents');
+        await fs.ensureDir(agentsDir);
+        for (const definition of agentDefinitions) {
+          await fs.writeFile(path.join(agentsDir, definition.fileName), definition.content);
+        }
+      }
       console.log(chalk.green(`      ✓ .claude/commands/${skillName}.md`));
     } else if (platform === 'codex') {
       const content = await fs.readFile(skillMdPath, 'utf8');

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

@@ -1,90 +0,0 @@
-# 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.

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

@@ -1,186 +0,0 @@
-#!/usr/bin/env python3
-"""
-Loop Exit Gatekeeper for prizmkit-code-review skill.
-
-Stateless design: all loop state is passed via stdin and returned via stdout.
-The caller (AI model) tracks `findings_history` and `max_rounds` between calls.
-No runtime files are created — the script is a pure function over JSON.
-
-The model supplies the current round in each call — the script does not auto-increment
-rounds, because the gate is called twice per loop iteration (after Reviewer returns
-and after Main Agent filters), and only the model knows when a full cycle completes.
-
-Usage:
-    echo '{"reviewer_result":"NEEDS_FIXES","accepted_count":2,"findings_count":5,"round":1,"findings_history":[],"max_rounds":3,"filtering_done":true}' | python3 check_loop.py
-
-Input JSON schema:
-    {
-        "reviewer_result": "PASS" | "NEEDS_FIXES",
-        "accepted_count": int,
-        "findings_count": int,
-        "round": int,
-        "findings_history": [int, ...],
-        "max_rounds": int,
-        "filtering_done": bool
-    }
-
-Output JSON schema:
-    {
-        "endLoop": bool,
-        "reason": str,
-        "verdict": "PASS" | "NEEDS_FIXES" | null,
-        "round": int,
-        "maxRounds": int,
-        "divergenceWarning": bool,
-        "findings_history": [int, ...]
-    }
-
-Exit conditions (checked in order):
-    1. Reviewer returned PASS          → endLoop=true, verdict=PASS
-    2. NEEDS_FIXES before filtering    → endLoop=false, wait for filtering
-    3. Filtered findings all rejected  → endLoop=true, verdict=PASS
-    4. Max rounds reached after filtering → endLoop=true, verdict=NEEDS_FIXES
-    5. Otherwise                       → endLoop=false
-
-Divergence detection:
-    If findings_count strictly increases for 3 consecutive rounds, set divergenceWarning=true.
-    This is a warning only — it does not force loop exit.
-"""
-
-import json
-import sys
-
-DEFAULT_MAX_ROUNDS = 3
-
-
-def check_divergence(findings_history):
-    """Return True if the last 3 entries in findings_history are strictly increasing."""
-    if len(findings_history) < 3:
-        return False
-    last_three = findings_history[-3:]
-    return last_three[0] < last_three[1] < last_three[2]
-
-
-def record_findings_count(findings_history, current_round, findings_count):
-    """Record findings_count once per round index, updating duplicate calls for the same round."""
-    if current_round <= 0:
-        return findings_history
-
-    target_index = current_round - 1
-    while len(findings_history) < target_index:
-        findings_history.append(0)
-
-    if len(findings_history) == target_index:
-        findings_history.append(findings_count)
-    else:
-        findings_history[target_index] = findings_count
-
-    return findings_history
-
-
-def check_exit_condition(data):
-    """Determine whether the loop should exit. Pure function — no side effects.
-
-    Round is model-supplied — the script does not auto-increment it because
-    the gate is called twice per loop iteration (after Step 2 and Step 3).
-    """
-    reviewer_result = data.get("reviewer_result")
-    accepted_count = data.get("accepted_count", 0)
-    findings_count = data.get("findings_count", 0)
-    current_round = data.get("round", 0)
-    findings_history = list(data.get("findings_history", []))
-    max_rounds = data.get("max_rounds", DEFAULT_MAX_ROUNDS)
-    filtering_done = data.get("filtering_done", reviewer_result == "PASS")
-
-    findings_history = record_findings_count(
-        findings_history, current_round, findings_count
-    )
-    divergence_warning = check_divergence(findings_history)
-
-    # Condition 1: Reviewer returned PASS
-    if reviewer_result == "PASS":
-        return {
-            "endLoop": True,
-            "reason": f"Round {current_round}: Reviewer returned PASS",
-            "verdict": "PASS",
-            "round": current_round,
-            "maxRounds": max_rounds,
-            "divergenceWarning": False,
-            "findings_history": findings_history,
-        }
-
-    # Condition 2: Reviewer returned findings, but filtering has not happened yet
-    if reviewer_result == "NEEDS_FIXES" and not filtering_done:
-        return {
-            "endLoop": False,
-            "reason": f"Round {current_round}: reviewer returned findings; filter before applying exit conditions",
-            "verdict": None,
-            "round": current_round,
-            "maxRounds": max_rounds,
-            "divergenceWarning": divergence_warning,
-            "findings_history": findings_history,
-        }
-
-    # Condition 3: All findings rejected after filtering
-    if reviewer_result == "NEEDS_FIXES" and accepted_count == 0:
-        return {
-            "endLoop": True,
-            "reason": f"Round {current_round}: all findings rejected by main agent",
-            "verdict": "PASS",
-            "round": current_round,
-            "maxRounds": max_rounds,
-            "divergenceWarning": False,
-            "findings_history": findings_history,
-        }
-
-    # Condition 4: Max rounds reached
-    if current_round >= max_rounds:
-        return {
-            "endLoop": True,
-            "reason": f"Hard limit: max {max_rounds} rounds reached",
-            "verdict": "NEEDS_FIXES",
-            "round": current_round,
-            "maxRounds": max_rounds,
-            "divergenceWarning": divergence_warning,
-            "findings_history": findings_history,
-        }
-
-    # Condition 5: Continue loop
-    next_round = current_round + 1
-    return {
-        "endLoop": False,
-        "reason": f"Round {current_round}: {accepted_count} findings accepted, continuing to round {next_round}",
-        "verdict": None,
-        "round": current_round,
-        "maxRounds": max_rounds,
-        "divergenceWarning": divergence_warning,
-        "findings_history": findings_history,
-    }
-
-
-def main():
-    # Read input from stdin
-    try:
-        data = json.load(sys.stdin)
-    except json.JSONDecodeError as e:
-        print(
-            json.dumps(
-                {
-                    "endLoop": False,
-                    "reason": f"Invalid JSON input: {e}",
-                    "verdict": None,
-                    "round": 0,
-                    "maxRounds": DEFAULT_MAX_ROUNDS,
-                    "divergenceWarning": False,
-                    "findings_history": [],
-                }
-            )
-        )
-        sys.exit(1)
-
-    result = check_exit_condition(data)
-    print(json.dumps(result))
-
-
-if __name__ == "__main__":
-    main()