@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/skills/skill-comply/scripts/run.py

@@ -0,0 +1,127 @@
+"""CLI entry point for skill-comply."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from scripts.grader import grade
+from scripts.report import generate_report
+from scripts.runner import run_scenario
+from scripts.scenario_generator import generate_scenarios
+from scripts.spec_generator import generate_spec
+
+logger = logging.getLogger(__name__)
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+    parser = argparse.ArgumentParser(
+        description="skill-comply: Measure skill compliance rates",
+    )
+    parser.add_argument(
+        "skill",
+        type=Path,
+        help="Path to skill/rule file to test",
+    )
+    parser.add_argument(
+        "--model",
+        default="sonnet",
+        help="Model for scenario execution (default: sonnet)",
+    )
+    parser.add_argument(
+        "--gen-model",
+        default="haiku",
+        help="Model for spec/scenario generation (default: haiku)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Generate spec and scenarios without executing",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        default=None,
+        help="Output report path (default: results/<skill-name>.md)",
+    )
+
+    args = parser.parse_args()
+
+    if not args.skill.is_file():
+        logger.error("Error: Skill file not found: %s", args.skill)
+        sys.exit(1)
+
+    results_dir = Path(__file__).parent.parent / "results"
+    results_dir.mkdir(exist_ok=True)
+
+    # Step 1: Generate compliance spec
+    logger.info("[1/4] Generating compliance spec from %s...", args.skill.name)
+    spec = generate_spec(args.skill, model=args.gen_model)
+    logger.info("       %d steps extracted", len(spec.steps))
+
+    # Step 2: Generate scenarios
+    spec_yaml = yaml.dump({
+        "steps": [
+            {"id": s.id, "description": s.description, "required": s.required}
+            for s in spec.steps
+        ]
+    })
+    logger.info("[2/4] Generating scenarios (3 prompt strictness levels)...")
+    scenarios = generate_scenarios(args.skill, spec_yaml, model=args.gen_model)
+    logger.info("       %d scenarios generated", len(scenarios))
+
+    for s in scenarios:
+        logger.info("       - %s: %s", s.level_name, s.description[:60])
+
+    if args.dry_run:
+        logger.info("\n[dry-run] Spec and scenarios generated. Skipping execution.")
+        logger.info("\nSpec: %s (%d steps)", spec.id, len(spec.steps))
+        for step in spec.steps:
+            marker = "*" if step.required else " "
+            logger.info("  [%s] %s: %s", marker, step.id, step.description)
+        return
+
+    # Step 3: Execute scenarios
+    logger.info("[3/4] Executing scenarios (model=%s)...", args.model)
+    graded_results: list[tuple[str, Any, list[Any]]] = []
+
+    for scenario in scenarios:
+        logger.info("       Running %s...", scenario.level_name)
+        run = run_scenario(scenario, model=args.model)
+        result = grade(spec, list(run.observations))
+        graded_results.append((scenario.level_name, result, list(run.observations)))
+        logger.info("       %s: %.0f%%", scenario.level_name, result.compliance_rate * 100)
+
+    # Step 4: Generate report
+    skill_name = args.skill.parent.name if args.skill.stem == "SKILL" else args.skill.stem
+    output_path = args.output or results_dir / f"{skill_name}.md"
+    logger.info("[4/4] Generating report...")
+
+    report = generate_report(args.skill, spec, graded_results, scenarios=scenarios)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(report)
+    logger.info("       Report saved to %s", output_path)
+
+    # Summary
+    if not graded_results:
+        logger.warning("No scenarios were executed.")
+        return
+    overall = sum(r.compliance_rate for _, r, _obs in graded_results) / len(graded_results)
+    logger.info("\n%s", "=" * 50)
+    logger.info("Overall Compliance: %.0f%%", overall * 100)
+    if overall < spec.threshold_promote_to_hook:
+        logger.info(
+            "Recommendation: Some steps have low compliance. "
+            "Consider promoting them to hooks. See the report for details."
+        )
+
+
+if __name__ == "__main__":
+    main()

package/.agent/skills/skill-comply/scripts/runner.py

@@ -0,0 +1,161 @@
+"""Run scenarios via claude -p and parse tool calls from stream-json output."""
+
+from __future__ import annotations
+
+import json
+import re
+import shlex
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from scripts.parser import ObservationEvent
+from scripts.scenario_generator import Scenario
+
+SANDBOX_BASE = Path("/tmp/skill-comply-sandbox")
+ALLOWED_MODELS = frozenset({"haiku", "sonnet", "opus"})
+
+
+@dataclass(frozen=True)
+class ScenarioRun:
+    scenario: Scenario
+    observations: tuple[ObservationEvent, ...]
+    sandbox_dir: Path
+
+
+def run_scenario(
+    scenario: Scenario,
+    model: str = "sonnet",
+    max_turns: int = 30,
+    timeout: int = 300,
+) -> ScenarioRun:
+    """Execute a scenario and extract tool calls from stream-json output."""
+    if model not in ALLOWED_MODELS:
+        raise ValueError(f"Unknown model: {model!r}. Allowed: {ALLOWED_MODELS}")
+
+    sandbox_dir = _safe_sandbox_dir(scenario.id)
+    _setup_sandbox(sandbox_dir, scenario)
+
+    result = subprocess.run(
+        [
+            "claude", "-p", scenario.prompt,
+            "--model", model,
+            "--max-turns", str(max_turns),
+            "--add-dir", str(sandbox_dir),
+            "--allowedTools", "Read,Write,Edit,Bash,Glob,Grep",
+            "--output-format", "stream-json",
+            "--verbose",
+        ],
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        cwd=sandbox_dir,
+    )
+
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"claude -p failed (rc={result.returncode}): {result.stderr[:500]}"
+        )
+
+    observations = _parse_stream_json(result.stdout)
+
+    return ScenarioRun(
+        scenario=scenario,
+        observations=tuple(observations),
+        sandbox_dir=sandbox_dir,
+    )
+
+
+def _safe_sandbox_dir(scenario_id: str) -> Path:
+    """Sanitize scenario ID and ensure path stays within sandbox base."""
+    safe_id = re.sub(r"[^a-zA-Z0-9\-_]", "_", scenario_id)
+    path = SANDBOX_BASE / safe_id
+    # Validate path stays within sandbox base (raises ValueError on traversal)
+    path.resolve().relative_to(SANDBOX_BASE.resolve())
+    return path
+
+
+def _setup_sandbox(sandbox_dir: Path, scenario: Scenario) -> None:
+    """Create sandbox directory and run setup commands."""
+    if sandbox_dir.exists():
+        shutil.rmtree(sandbox_dir)
+    sandbox_dir.mkdir(parents=True)
+
+    subprocess.run(["git", "init"], cwd=sandbox_dir, capture_output=True)
+
+    for cmd in scenario.setup_commands:
+        parts = shlex.split(cmd)
+        subprocess.run(parts, cwd=sandbox_dir, capture_output=True)
+
+
+def _parse_stream_json(stdout: str) -> list[ObservationEvent]:
+    """Parse claude -p stream-json output into ObservationEvents.
+
+    Stream-json format:
+    - type=assistant with content[].type=tool_use → tool call (name, input)
+    - type=user with content[].type=tool_result → tool result (output)
+    """
+    events: list[ObservationEvent] = []
+    pending: dict[str, dict] = {}
+    event_counter = 0
+
+    for line in stdout.strip().splitlines():
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+
+        msg_type = msg.get("type")
+
+        if msg_type == "assistant":
+            content = msg.get("message", {}).get("content", [])
+            for block in content:
+                if block.get("type") == "tool_use":
+                    tool_use_id = block.get("id", "")
+                    tool_input = block.get("input", {})
+                    input_str = (
+                        json.dumps(tool_input)[:5000]
+                        if isinstance(tool_input, dict)
+                        else str(tool_input)[:5000]
+                    )
+                    pending[tool_use_id] = {
+                        "tool": block.get("name", "unknown"),
+                        "input": input_str,
+                        "order": event_counter,
+                    }
+                    event_counter += 1
+
+        elif msg_type == "user":
+            content = msg.get("message", {}).get("content", [])
+            if isinstance(content, list):
+                for block in content:
+                    tool_use_id = block.get("tool_use_id", "")
+                    if tool_use_id in pending:
+                        info = pending.pop(tool_use_id)
+                        output_content = block.get("content", "")
+                        if isinstance(output_content, list):
+                            output_str = json.dumps(output_content)[:5000]
+                        else:
+                            output_str = str(output_content)[:5000]
+
+                        events.append(ObservationEvent(
+                            timestamp=f"T{info['order']:04d}",
+                            event="tool_complete",
+                            tool=info["tool"],
+                            session=msg.get("session_id", "unknown"),
+                            input=info["input"],
+                            output=output_str,
+                        ))
+
+    for _tool_use_id, info in pending.items():
+        events.append(ObservationEvent(
+            timestamp=f"T{info['order']:04d}",
+            event="tool_complete",
+            tool=info["tool"],
+            session="unknown",
+            input=info["input"],
+            output="",
+        ))
+
+    return sorted(events, key=lambda e: e.timestamp)

package/.agent/skills/skill-comply/scripts/scenario-generator.py

@@ -0,0 +1,70 @@
+"""Generate pressure scenarios from skill + spec using LLM."""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from scripts.utils import extract_yaml
+
+PROMPTS_DIR = Path(__file__).parent.parent / "prompts"
+
+
+@dataclass(frozen=True)
+class Scenario:
+    id: str
+    level: int
+    level_name: str
+    description: str
+    prompt: str
+    setup_commands: tuple[str, ...]
+
+
+def generate_scenarios(
+    skill_path: Path,
+    spec_yaml: str,
+    model: str = "haiku",
+) -> list[Scenario]:
+    """Generate 3 scenarios with decreasing prompt strictness.
+
+    Calls claude -p with the scenario_generator prompt, parses YAML output.
+    """
+    skill_content = skill_path.read_text()
+    prompt_template = (PROMPTS_DIR / "scenario_generator.md").read_text()
+    prompt = (
+        prompt_template
+        .replace("{skill_content}", skill_content)
+        .replace("{spec_yaml}", spec_yaml)
+    )
+
+    result = subprocess.run(
+        ["claude", "-p", prompt, "--model", model, "--output-format", "text"],
+        capture_output=True,
+        text=True,
+        timeout=120,
+    )
+
+    if result.returncode != 0:
+        raise RuntimeError(f"claude -p failed: {result.stderr}")
+
+    if not result.stdout.strip():
+        raise RuntimeError("claude -p returned empty output")
+
+    raw_yaml = extract_yaml(result.stdout)
+    parsed = yaml.safe_load(raw_yaml)
+
+    scenarios: list[Scenario] = []
+    for s in parsed["scenarios"]:
+        scenarios.append(Scenario(
+            id=s["id"],
+            level=s["level"],
+            level_name=s["level_name"],
+            description=s["description"],
+            prompt=s["prompt"].strip(),
+            setup_commands=tuple(s.get("setup_commands", [])),
+        ))
+
+    return sorted(scenarios, key=lambda s: s.level)

package/.agent/skills/skill-comply/scripts/spec-generator.py

@@ -0,0 +1,72 @@
+"""Generate compliance specs from skill files using LLM."""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from pathlib import Path
+
+import yaml
+
+from scripts.parser import ComplianceSpec, parse_spec
+from scripts.utils import extract_yaml
+
+PROMPTS_DIR = Path(__file__).parent.parent / "prompts"
+
+
+def generate_spec(
+    skill_path: Path,
+    model: str = "haiku",
+    max_retries: int = 2,
+) -> ComplianceSpec:
+    """Generate a compliance spec from a skill/rule file.
+
+    Calls claude -p with the spec_generator prompt, parses YAML output.
+    Retries on YAML parse errors with error feedback.
+    """
+    skill_content = skill_path.read_text()
+    prompt_template = (PROMPTS_DIR / "spec_generator.md").read_text()
+    base_prompt = prompt_template.replace("{skill_content}", skill_content)
+
+    last_error: Exception | None = None
+
+    for attempt in range(max_retries + 1):
+        prompt = base_prompt
+        if attempt > 0 and last_error is not None:
+            prompt += (
+                f"\n\nPREVIOUS ATTEMPT FAILED with YAML parse error:\n"
+                f"{last_error}\n\n"
+                f"Please fix the YAML. Remember to quote all string values "
+                f"that contain colons, e.g.: description: \"Use type: description format\""
+            )
+
+        result = subprocess.run(
+            ["claude", "-p", prompt, "--model", model, "--output-format", "text"],
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+
+        if result.returncode != 0:
+            raise RuntimeError(f"claude -p failed: {result.stderr}")
+
+        raw_yaml = extract_yaml(result.stdout)
+
+        tmp_path = None
+        with tempfile.NamedTemporaryFile(
+            mode="w", suffix=".yaml", delete=False,
+        ) as f:
+            f.write(raw_yaml)
+            tmp_path = Path(f.name)
+
+        try:
+            return parse_spec(tmp_path)
+        except (yaml.YAMLError, KeyError, TypeError) as e:
+            last_error = e
+            if attempt == max_retries:
+                raise
+        finally:
+            if tmp_path is not None:
+                tmp_path.unlink(missing_ok=True)
+
+    raise RuntimeError("unreachable")

package/.agent/skills/skill-comply/scripts/utils.py

@@ -0,0 +1,13 @@
+"""Shared utilities for skill-comply scripts."""
+
+from __future__ import annotations
+
+
+def extract_yaml(text: str) -> str:
+    """Extract YAML from LLM output, stripping markdown fences if present."""
+    lines = text.strip().splitlines()
+    if lines and lines[0].startswith("```"):
+        lines = lines[1:]
+    if lines and lines[-1].startswith("```"):
+        lines = lines[:-1]
+    return "\n".join(lines)

package/.agent/skills/skill-comply/tests/test-grader.py

@@ -0,0 +1,137 @@
+"""Tests for grader module — compliance scoring with LLM classification."""
+
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from scripts.grader import ComplianceResult, StepResult, grade
+from scripts.parser import parse_spec, parse_trace
+
+FIXTURES = Path(__file__).parent.parent / "fixtures"
+
+
+@pytest.fixture
+def tdd_spec():
+    return parse_spec(FIXTURES / "tdd_spec.yaml")
+
+
+@pytest.fixture
+def compliant_trace():
+    return parse_trace(FIXTURES / "compliant_trace.jsonl")
+
+
+@pytest.fixture
+def noncompliant_trace():
+    return parse_trace(FIXTURES / "noncompliant_trace.jsonl")
+
+
+def _mock_compliant_classification(spec, trace, model="haiku"):  # noqa: ARG001
+    """Simulate LLM correctly classifying a compliant trace."""
+    return {
+        "write_test": [0],
+        "run_test_red": [1],
+        "write_impl": [2],
+        "run_test_green": [3],
+        "refactor": [4],
+    }
+
+
+def _mock_noncompliant_classification(spec, trace, model="haiku"):
+    """Simulate LLM classifying a noncompliant trace (impl before test)."""
+    return {
+        "write_impl": [0],    # src/fib.py written first
+        "write_test": [1],    # test written second
+        "run_test_green": [2],  # only a passing test run
+    }
+
+
+def _mock_empty_classification(spec, trace, model="haiku"):
+    return {}
+
+
+class TestGradeCompliant:
+    @patch("scripts.grader.classify_events", side_effect=_mock_compliant_classification)
+    def test_returns_compliance_result(self, mock_cls, tdd_spec, compliant_trace) -> None:
+        result = grade(tdd_spec, compliant_trace)
+        assert isinstance(result, ComplianceResult)
+
+    @patch("scripts.grader.classify_events", side_effect=_mock_compliant_classification)
+    def test_full_compliance(self, mock_cls, tdd_spec, compliant_trace) -> None:
+        result = grade(tdd_spec, compliant_trace)
+        assert result.compliance_rate == 1.0
+
+    @patch("scripts.grader.classify_events", side_effect=_mock_compliant_classification)
+    def test_all_required_steps_detected(self, mock_cls, tdd_spec, compliant_trace) -> None:
+        result = grade(tdd_spec, compliant_trace)
+        required_results = [s for s in result.steps if s.step_id in
+                           ("write_test", "run_test_red", "write_impl", "run_test_green")]
+        assert all(s.detected for s in required_results)
+
+    @patch("scripts.grader.classify_events", side_effect=_mock_compliant_classification)
+    def test_optional_step_detected(self, mock_cls, tdd_spec, compliant_trace) -> None:
+        result = grade(tdd_spec, compliant_trace)
+        refactor = next(s for s in result.steps if s.step_id == "refactor")
+        assert refactor.detected is True
+
+    @patch("scripts.grader.classify_events", side_effect=_mock_compliant_classification)
+    def test_no_hook_promotion_recommended(self, mock_cls, tdd_spec, compliant_trace) -> None:
+        result = grade(tdd_spec, compliant_trace)
+        assert result.recommend_hook_promotion is False
+
+    @patch("scripts.grader.classify_events", side_effect=_mock_compliant_classification)
+    def test_step_evidence_not_empty(self, mock_cls, tdd_spec, compliant_trace) -> None:
+        result = grade(tdd_spec, compliant_trace)
+        for step in result.steps:
+            if step.detected:
+                assert len(step.evidence) > 0
+
+
+class TestGradeNoncompliant:
+    @patch("scripts.grader.classify_events", side_effect=_mock_noncompliant_classification)
+    def test_low_compliance(self, mock_cls, tdd_spec, noncompliant_trace) -> None:
+        result = grade(tdd_spec, noncompliant_trace)
+        assert result.compliance_rate < 1.0
+
+    @patch("scripts.grader.classify_events", side_effect=_mock_noncompliant_classification)
+    def test_write_test_fails_ordering(self, mock_cls, tdd_spec, noncompliant_trace) -> None:
+        """write_test has before_step=write_impl, but test is written AFTER impl."""
+        result = grade(tdd_spec, noncompliant_trace)
+        write_test = next(s for s in result.steps if s.step_id == "write_test")
+        assert write_test.detected is False
+
+    @patch("scripts.grader.classify_events", side_effect=_mock_noncompliant_classification)
+    def test_run_test_red_not_detected(self, mock_cls, tdd_spec, noncompliant_trace) -> None:
+        result = grade(tdd_spec, noncompliant_trace)
+        run_red = next(s for s in result.steps if s.step_id == "run_test_red")
+        assert run_red.detected is False
+
+    @patch("scripts.grader.classify_events", side_effect=_mock_noncompliant_classification)
+    def test_hook_promotion_recommended(self, mock_cls, tdd_spec, noncompliant_trace) -> None:
+        result = grade(tdd_spec, noncompliant_trace)
+        assert result.recommend_hook_promotion is True
+
+    @patch("scripts.grader.classify_events", side_effect=_mock_noncompliant_classification)
+    def test_failure_reasons_present(self, mock_cls, tdd_spec, noncompliant_trace) -> None:
+        result = grade(tdd_spec, noncompliant_trace)
+        failed_steps = [s for s in result.steps if not s.detected and s.step_id != "refactor"]
+        for step in failed_steps:
+            assert step.failure_reason is not None
+
+
+class TestGradeEdgeCases:
+    @patch("scripts.grader.classify_events", side_effect=_mock_empty_classification)
+    def test_empty_trace(self, mock_cls, tdd_spec) -> None:
+        result = grade(tdd_spec, [])
+        assert result.compliance_rate == 0.0
+        assert result.recommend_hook_promotion is True
+
+    @patch("scripts.grader.classify_events", side_effect=_mock_compliant_classification)
+    def test_compliance_rate_is_ratio_of_required_only(self, mock_cls, tdd_spec, compliant_trace) -> None:
+        result = grade(tdd_spec, compliant_trace)
+        assert result.compliance_rate == 1.0
+
+    @patch("scripts.grader.classify_events", side_effect=_mock_compliant_classification)
+    def test_spec_id_in_result(self, mock_cls, tdd_spec, compliant_trace) -> None:
+        result = grade(tdd_spec, compliant_trace)
+        assert result.spec_id == "tdd-workflow"

package/.agent/skills/skill-comply/tests/test-parser.py

@@ -0,0 +1,90 @@
+"""Tests for parser module — JSONL trace and YAML spec parsing."""
+
+from pathlib import Path
+
+import pytest
+
+from scripts.parser import (
+    ComplianceSpec,
+    Detector,
+    ObservationEvent,
+    Step,
+    parse_spec,
+    parse_trace,
+)
+
+FIXTURES = Path(__file__).parent.parent / "fixtures"
+
+
+class TestParseTrace:
+    def test_parses_compliant_trace(self) -> None:
+        events = parse_trace(FIXTURES / "compliant_trace.jsonl")
+        assert len(events) == 5
+        assert all(isinstance(e, ObservationEvent) for e in events)
+
+    def test_events_sorted_by_timestamp(self) -> None:
+        events = parse_trace(FIXTURES / "compliant_trace.jsonl")
+        timestamps = [e.timestamp for e in events]
+        assert timestamps == sorted(timestamps)
+
+    def test_event_fields(self) -> None:
+        events = parse_trace(FIXTURES / "compliant_trace.jsonl")
+        first = events[0]
+        assert first.tool == "Write"
+        assert first.session == "sess-001"
+        assert "test_fib.py" in first.input
+        assert first.output == "File created"
+
+    def test_parses_noncompliant_trace(self) -> None:
+        events = parse_trace(FIXTURES / "noncompliant_trace.jsonl")
+        assert len(events) == 3
+        assert "src/fib.py" in events[0].input
+
+    def test_empty_file_returns_empty_list(self, tmp_path: Path) -> None:
+        empty = tmp_path / "empty.jsonl"
+        empty.write_text("")
+        events = parse_trace(empty)
+        assert events == []
+
+    def test_nonexistent_file_raises(self) -> None:
+        with pytest.raises(FileNotFoundError):
+            parse_trace(Path("/nonexistent/trace.jsonl"))
+
+
+class TestParseSpec:
+    def test_parses_tdd_spec(self) -> None:
+        spec = parse_spec(FIXTURES / "tdd_spec.yaml")
+        assert isinstance(spec, ComplianceSpec)
+        assert spec.id == "tdd-workflow"
+        assert len(spec.steps) == 5
+
+    def test_step_fields(self) -> None:
+        spec = parse_spec(FIXTURES / "tdd_spec.yaml")
+        first = spec.steps[0]
+        assert isinstance(first, Step)
+        assert first.id == "write_test"
+        assert first.required is True
+        assert isinstance(first.detector, Detector)
+        assert "test file" in first.detector.description
+        assert first.detector.before_step == "write_impl"
+
+    def test_optional_detector_fields(self) -> None:
+        spec = parse_spec(FIXTURES / "tdd_spec.yaml")
+        write_test = spec.steps[0]
+        assert write_test.detector.after_step is None
+
+        run_test_red = spec.steps[1]
+        assert run_test_red.detector.after_step == "write_test"
+        assert run_test_red.detector.before_step == "write_impl"
+
+    def test_scoring_threshold(self) -> None:
+        spec = parse_spec(FIXTURES / "tdd_spec.yaml")
+        assert spec.threshold_promote_to_hook == 0.6
+
+    def test_required_vs_optional_steps(self) -> None:
+        spec = parse_spec(FIXTURES / "tdd_spec.yaml")
+        required = [s for s in spec.steps if s.required]
+        optional = [s for s in spec.steps if not s.required]
+        assert len(required) == 4
+        assert len(optional) == 1
+        assert optional[0].id == "refactor"