prizmkit 1.1.123 → 1.1.124

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

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Render review-report.md from completed structured review state."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+VERDICTS = {"PASS", "NEEDS_FIXES"}
+EXECUTION_PROTOCOLS = {"BLOCKED", "COMPLIANT", "NOT_APPLICABLE", "VIOLATION"}
+ATTESTATIONS = {"FAILED", "NOT_APPLICABLE", "VERIFIED"}
+SNAPSHOT_STATUSES = {"FAILED", "NOT_APPLICABLE", "VERIFIED"}
+BLOCKERS = {
+    "INVALID_REVIEW_RESULT",
+    "NONE",
+    "REVIEW_INFRASTRUCTURE_BLOCKED",
+    "REVIEW_ORCHESTRATION_VIOLATION",
+    "REVIEW_SAFETY_LIMIT_REACHED",
+    "WORKSPACE_MISMATCH",
+}
+REVIEW_MODES = {
+    "independent-reviewer-verified-snapshot",
+    "not-run-no-changes",
+}
+
+
+class ReportStateError(ValueError):
+    """Raised when persisted state cannot produce a trustworthy report."""
+
+
+def _require_enum(state: dict[str, Any], name: str, allowed: set[str]) -> str:
+    value = state.get(name)
+    if value not in allowed:
+        raise ReportStateError(f"{name} has invalid value: {value!r}")
+    return value
+
+
+def _require_count(state: dict[str, Any], name: str) -> int:
+    value = state.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_state(state: Any) -> dict[str, Any]:
+    """Validate the minimum completed state required for report regeneration."""
+    if not isinstance(state, dict):
+        raise ReportStateError("state must be a JSON object")
+
+    _require_enum(state, "verdict", VERDICTS)
+    _require_enum(state, "review_mode", REVIEW_MODES)
+    _require_enum(state, "execution_protocol", EXECUTION_PROTOCOLS)
+    _require_enum(state, "capability_attestation", ATTESTATIONS)
+    _require_enum(state, "snapshot_verification", SNAPSHOT_STATUSES)
+    _require_enum(state, "blocker_code", BLOCKERS)
+    rounds_completed = _require_count(state, "rounds_completed")
+    reviewers_started = _require_count(state, "reviewers_started")
+    descendants = _require_count(state, "descendant_execution_units_observed")
+    delegation_depth = _require_count(state, "delegation_depth_observed")
+
+    rounds = state.get("rounds")
+    findings = state.get("findings")
+    if not isinstance(rounds, list) or not isinstance(findings, list):
+        raise ReportStateError("rounds and findings must be arrays")
+    if rounds_completed != len(rounds):
+        raise ReportStateError("rounds_completed must equal the rounds array length")
+    if reviewers_started < rounds_completed:
+        raise ReportStateError("reviewers_started cannot be below rounds_completed")
+
+    if state["review_mode"] == "not-run-no-changes":
+        if any((rounds_completed, reviewers_started, descendants, delegation_depth)):
+            raise ReportStateError("no-change review cannot contain execution activity")
+        if state["verdict"] != "PASS":
+            raise ReportStateError("no-change review must have PASS verdict")
+
+    if state["verdict"] == "PASS" and state["blocker_code"] != "NONE":
+        raise ReportStateError("PASS cannot include a blocker code")
+    if state["execution_protocol"] == "COMPLIANT":
+        if descendants != 0 or delegation_depth != 0:
+            raise ReportStateError("COMPLIANT execution requires zero descendants and depth")
+
+    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", "dimension", "location", "problem", "failure_scenario", "status"}
+        missing = sorted(required - finding.keys())
+        if missing:
+            raise ReportStateError(
+                f"finding {index} missing fields: {', '.join(missing)}"
+            )
+
+    return state
+
+
+def _finding_totals(findings: list[dict[str, Any]]) -> tuple[int, int, int]:
+    fixed = sum(finding["status"].startswith("fixed") for finding in findings)
+    rejected = sum(finding["status"].startswith("rejected") for finding in findings)
+    unresolved = len(findings) - fixed - rejected
+    return fixed, rejected, unresolved
+
+
+def render_report(state: Any) -> str:
+    """Return deterministic Markdown without launching or resuming a Reviewer."""
+    valid = validate_state(state)
+    findings = valid["findings"]
+    fixed, rejected, unresolved = _finding_totals(findings)
+
+    lines = [
+        "# Review Report",
+        "",
+        f"## Verdict: {valid['verdict']}",
+        f"## Rounds Completed: {valid['rounds_completed']}",
+        f"## Reviewers Started: {valid['reviewers_started']}",
+        f"## Review Mode: {valid['review_mode']}",
+        f"## Reviewer Strategy: {valid.get('reviewer_strategy', 'not-applicable')}",
+        f"## Execution Protocol: {valid['execution_protocol']}",
+        f"## Capability Attestation: {valid['capability_attestation']}",
+        f"## Descendant Execution Units Observed: {valid['descendant_execution_units_observed']}",
+        f"## Delegation Depth Observed: {valid['delegation_depth_observed']}",
+        f"## Snapshot Verification: {valid['snapshot_verification']}",
+        f"## Snapshot Identity: {valid.get('snapshot_identity', 'not-applicable')}",
+        f"## Blocker Code: {valid['blocker_code']}",
+        f"## Total Findings: {len(findings)} → Fixed: {fixed}, Rejected: {rejected}, Unresolved: {unresolved}",
+        "",
+    ]
+
+    if valid["review_mode"] == "not-run-no-changes":
+        lines.extend(["## Round 0: PASS — no workspace changes to review", ""])
+    else:
+        for review_round in valid["rounds"]:
+            lines.extend(
+                [
+                    f"## Round {review_round['round']}",
+                    "",
+                    f"- Snapshot Identity: {review_round['snapshot_identity']}",
+                    f"- Reviewer Execution Identity: {review_round['reviewer_execution_identity']}",
+                    f"- Result: {review_round['result']}",
+                    f"- Findings: {review_round['findings_count']}",
+                    f"- Accepted: {review_round['accepted_count']}",
+                    f"- Rejected: {review_round['rejected_count']}",
+                    "",
+                ]
+            )
+
+    for index, finding in enumerate(findings, start=1):
+        lines.extend(
+            [
+                f"### Finding {index}: {finding['title']}",
+                "",
+                f"- Severity: {finding['severity']}",
+                f"- Dimension: {finding['dimension']}",
+                f"- Location: {finding['location']}",
+                f"- Problem: {finding['problem']}",
+                f"- Failure Scenario: {finding['failure_scenario']}",
+                f"- Status: {finding['status']}",
+                "",
+            ]
+        )
+
+    lines.extend(["## Final Summary", "", valid["final_summary"], ""])
+    return "\n".join(lines)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("state", type=Path, help="completed review-result-state.json")
+    parser.add_argument("output", type=Path, help="review-report.md destination")
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        state = json.loads(args.state.read_text(encoding="utf-8"))
+        report = render_report(state)
+        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/bundled/skills/prizmkit-code-review/scripts/workspace_snapshot.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""Generate a deterministic, path-safe workspace manifest for code review."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+SNAPSHOT_PROTOCOL_VERSION = 1
+
+
+class SnapshotError(RuntimeError):
+    """Raised when the workspace snapshot cannot be generated safely."""
+
+
+def _git(root: Path, *args: str) -> bytes:
+    try:
+        return subprocess.check_output(
+            ["git", "-c", "core.quotepath=false", *args],
+            cwd=root,
+            stderr=subprocess.PIPE,
+        )
+    except (OSError, subprocess.CalledProcessError) as error:
+        detail = getattr(error, "stderr", b"").decode("utf-8", "replace").strip()
+        raise SnapshotError(detail or f"git {' '.join(args)} failed") from error
+
+
+def _decode(value: bytes) -> str:
+    return value.decode("utf-8", "surrogateescape")
+
+
+def _sha256_bytes(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def _file_identity(root: Path, relative_path: str) -> dict[str, Any] | None:
+    path = root / relative_path
+    if not path.is_symlink() and not path.is_file():
+        return None
+    if path.is_symlink():
+        content = os.readlink(path).encode("utf-8", "surrogateescape")
+        kind = "symlink"
+    else:
+        content = path.read_bytes()
+        kind = "file"
+    return {"kind": kind, "sha256": _sha256_bytes(content), "size": len(content)}
+
+
+def _index_identity(root: Path, relative_path: str) -> str | None:
+    try:
+        return _decode(_git(root, "rev-parse", f":{relative_path}")).strip()
+    except SnapshotError:
+        return None
+
+
+def _baseline_identity(root: Path, relative_path: str) -> str | None:
+    try:
+        return _decode(_git(root, "rev-parse", f"HEAD:{relative_path}")).strip()
+    except SnapshotError:
+        return None
+
+
+def _parse_name_status(raw: bytes, layer: str, root: Path) -> list[dict[str, Any]]:
+    fields = raw.rstrip(b"\0").split(b"\0") if raw else []
+    entries: list[dict[str, Any]] = []
+    index = 0
+    while index < len(fields):
+        status = _decode(fields[index])
+        index += 1
+        code = status[:1]
+        if code in {"R", "C"}:
+            if index + 1 >= len(fields):
+                raise SnapshotError("malformed rename or copy record")
+            source = _decode(fields[index])
+            destination = _decode(fields[index + 1])
+            index += 2
+            entry = {
+                "layer": layer,
+                "status": code,
+                "similarity": status[1:] or None,
+                "source_path": source,
+                "path": destination,
+            }
+        else:
+            if index >= len(fields):
+                raise SnapshotError("malformed name-status record")
+            path = _decode(fields[index])
+            index += 1
+            entry = {"layer": layer, "status": code, "path": path}
+
+        entry["worktree_content"] = _file_identity(root, entry["path"])
+        baseline_path = entry.get("source_path", entry["path"])
+        entry["baseline_blob"] = _baseline_identity(root, baseline_path)
+        if layer == "staged" and code != "D":
+            entry["index_blob"] = _index_identity(root, entry["path"])
+        entries.append(entry)
+
+    return entries
+
+
+def _untracked_entries(root: Path) -> list[dict[str, Any]]:
+    raw = _git(root, "ls-files", "--others", "--exclude-standard", "-z")
+    paths = [_decode(field) for field in raw.rstrip(b"\0").split(b"\0") if field]
+    return [
+        {
+            "layer": "untracked",
+            "status": "A",
+            "path": path,
+            "worktree_content": _file_identity(root, path),
+            "baseline_blob": None,
+        }
+        for path in paths
+    ]
+
+
+def _repository_identity(root: Path) -> str:
+    try:
+        remote = _decode(_git(root, "config", "--get", "remote.origin.url")).strip()
+    except SnapshotError:
+        remote = ""
+    return remote or root.name
+
+
+def _supporting_context(root: Path, paths: list[str]) -> list[dict[str, Any]]:
+    records: list[dict[str, Any]] = []
+    for relative_path in sorted(set(paths)):
+        candidate = (root / relative_path).resolve()
+        try:
+            candidate.relative_to(root)
+        except ValueError as error:
+            raise SnapshotError(
+                f"supporting context escapes repository: {relative_path}"
+            ) from error
+        identity = _file_identity(root, relative_path)
+        if identity is None:
+            raise SnapshotError(f"supporting context is not a file: {relative_path}")
+        records.append({"path": relative_path, "content": identity})
+    return records
+
+
+def build_manifest(root: Path, supporting_paths: list[str] | None = None) -> dict[str, Any]:
+    """Return a deterministic manifest for the repository's current logical change."""
+    repository_root = Path(
+        _decode(_git(root, "rev-parse", "--show-toplevel")).strip()
+    ).resolve()
+    baseline = _decode(_git(repository_root, "rev-parse", "HEAD")).strip()
+
+    entries = [
+        *_parse_name_status(
+            _git(repository_root, "diff", "--cached", "--name-status", "-z", "-M"),
+            "staged",
+            repository_root,
+        ),
+        *_parse_name_status(
+            _git(repository_root, "diff", "--name-status", "-z", "-M"),
+            "unstaged",
+            repository_root,
+        ),
+        *_untracked_entries(repository_root),
+    ]
+    entries.sort(
+        key=lambda entry: (
+            entry["path"],
+            entry["layer"],
+            entry.get("source_path", ""),
+        )
+    )
+
+    manifest: dict[str, Any] = {
+        "protocol_version": SNAPSHOT_PROTOCOL_VERSION,
+        "repository_identity": _repository_identity(repository_root),
+        "baseline_identity": baseline,
+        "changes": entries,
+        "supporting_context": _supporting_context(
+            repository_root, supporting_paths or []
+        ),
+    }
+    canonical = json.dumps(
+        manifest,
+        ensure_ascii=True,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+    manifest["snapshot_identity"] = _sha256_bytes(canonical)
+    return manifest
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", default=".", help="path inside the Git repository")
+    parser.add_argument(
+        "--supporting-context",
+        action="append",
+        default=[],
+        metavar="PATH",
+        help="unchanged repository-relative file required for review; repeat as needed",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        manifest = build_manifest(
+            Path(args.root).resolve(), args.supporting_context
+        )
+    except SnapshotError as error:
+        print(json.dumps({"error": str(error)}, sort_keys=True))
+        return 1
+
+    print(json.dumps(manifest, ensure_ascii=True, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.1.123",
+  "version": "1.1.124",
   "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');