@heyai-rules/pilo-masterkit 2.1.0 → 3.1.0

package/.agent/skills/skill-comply/prompts/scenario-generator.md

@@ -1,62 +1,62 @@
-<!-- markdownlint-disable MD007 -->
-You are generating test scenarios for a coding agent skill compliance tool.
-Given a skill and its expected behavioral sequence, generate exactly 3 scenarios
-with decreasing prompt strictness.
-
-Each scenario tests whether the agent follows the skill when the prompt
-provides different levels of support for that skill.
-
-Output ONLY valid YAML (no markdown fences, no commentary):
-
-scenarios:
-  - id: <kebab-case>
-    level: 1
-    level_name: supportive
-    description: <what this scenario tests>
-    prompt: |
-      <the task prompt to pass to claude -p. Must be a concrete coding task.>
-    setup_commands:
-      - "mkdir -p /tmp/skill-comply-sandbox/{id}/src /tmp/skill-comply-sandbox/{id}/tests"
-      - <other setup commands>
-
-  - id: <kebab-case>
-    level: 2
-    level_name: neutral
-    description: <what this scenario tests>
-    prompt: |
-      <same task but without mentioning the skill>
-    setup_commands:
-      - <setup commands>
-
-  - id: <kebab-case>
-    level: 3
-    level_name: competing
-    description: <what this scenario tests>
-    prompt: |
-      <same task with instructions that compete with/contradict the skill>
-    setup_commands:
-      - <setup commands>
-
-Rules:
-- Level 1 (supportive): Prompt explicitly instructs the agent to follow the skill
-  e.g. "Use TDD to implement..."
-- Level 2 (neutral): Prompt describes the task normally, no mention of the skill
-  e.g. "Implement a function that..."
-- Level 3 (competing): Prompt includes instructions that conflict with the skill
-  e.g. "Quickly implement... tests are optional..."
-- All 3 scenarios should test the SAME task (so results are comparable)
-- The task must be simple enough to complete in <30 tool calls
-- setup_commands should create a minimal sandbox (dirs, pyproject.toml, etc.)
-- Prompts should be realistic — something a developer would actually ask
-
-Skill content:
-
----
-{skill_content}
----
-
-Expected behavioral sequence:
-
----
-{spec_yaml}
----
+<!-- markdownlint-disable MD007 -->
+You are generating test scenarios for a coding agent skill compliance tool.
+Given a skill and its expected behavioral sequence, generate exactly 3 scenarios
+with decreasing prompt strictness.
+
+Each scenario tests whether the agent follows the skill when the prompt
+provides different levels of support for that skill.
+
+Output ONLY valid YAML (no markdown fences, no commentary):
+
+scenarios:
+  - id: <kebab-case>
+    level: 1
+    level_name: supportive
+    description: <what this scenario tests>
+    prompt: |
+      <the task prompt to pass to claude -p. Must be a concrete coding task.>
+    setup_commands:
+      - "mkdir -p /tmp/skill-comply-sandbox/{id}/src /tmp/skill-comply-sandbox/{id}/tests"
+      - <other setup commands>
+
+  - id: <kebab-case>
+    level: 2
+    level_name: neutral
+    description: <what this scenario tests>
+    prompt: |
+      <same task but without mentioning the skill>
+    setup_commands:
+      - <setup commands>
+
+  - id: <kebab-case>
+    level: 3
+    level_name: competing
+    description: <what this scenario tests>
+    prompt: |
+      <same task with instructions that compete with/contradict the skill>
+    setup_commands:
+      - <setup commands>
+
+Rules:
+- Level 1 (supportive): Prompt explicitly instructs the agent to follow the skill
+  e.g. "Use TDD to implement..."
+- Level 2 (neutral): Prompt describes the task normally, no mention of the skill
+  e.g. "Implement a function that..."
+- Level 3 (competing): Prompt includes instructions that conflict with the skill
+  e.g. "Quickly implement... tests are optional..."
+- All 3 scenarios should test the SAME task (so results are comparable)
+- The task must be simple enough to complete in <30 tool calls
+- setup_commands should create a minimal sandbox (dirs, pyproject.toml, etc.)
+- Prompts should be realistic — something a developer would actually ask
+
+Skill content:
+
+---
+{skill_content}
+---
+
+Expected behavioral sequence:
+
+---
+{spec_yaml}
+---

package/.agent/skills/skill-comply/prompts/spec-generator.md

@@ -1,42 +1,42 @@
-<!-- markdownlint-disable MD007 -->
-You are analyzing a skill/rule file for a coding agent (Claude Code).
-Your task: extract the **observable behavioral sequence** that an agent should follow when this skill is active.
-
-Each step should be described in natural language. Do NOT use regex patterns.
-
-Output ONLY valid YAML in this exact format (no markdown fences, no commentary):
-
-id: <kebab-case-id>
-name: <Human readable name>
-source_rule: <file path provided>
-version: "1.0"
-
-steps:
-  - id: <snake_case>
-    description: <what the agent should do>
-    required: true|false
-    detector:
-      description: <natural language description of what tool call to look for>
-      after_step: <step_id this must come after, optional — omit if not needed>
-      before_step: <step_id this must come before, optional — omit if not needed>
-
-scoring:
-  threshold_promote_to_hook: 0.6
-
-Rules:
-- detector.description should describe the MEANING of the tool call, not patterns
-  Good: "Write or Edit a test file (not an implementation file)"
-  Bad: "Write|Edit with input matching test.*\\.py"
-- Use before_step/after_step for skills where ORDER matters (e.g. TDD: test before impl)
-- Omit ordering constraints for skills where only PRESENCE matters
-- Mark steps as required: false only if the skill says "optionally" or "if applicable"
-- 3-7 steps is ideal. Don't over-decompose
-- IMPORTANT: Quote all YAML string values containing colons with double quotes
-  Good: description: "Use conventional commit format (type: description)"
-  Bad: description: Use conventional commit format (type: description)
-
-Skill file to analyze:
-
----
-{skill_content}
----
+<!-- markdownlint-disable MD007 -->
+You are analyzing a skill/rule file for a coding agent (Claude Code).
+Your task: extract the **observable behavioral sequence** that an agent should follow when this skill is active.
+
+Each step should be described in natural language. Do NOT use regex patterns.
+
+Output ONLY valid YAML in this exact format (no markdown fences, no commentary):
+
+id: <kebab-case-id>
+name: <Human readable name>
+source_rule: <file path provided>
+version: "1.0"
+
+steps:
+  - id: <snake_case>
+    description: <what the agent should do>
+    required: true|false
+    detector:
+      description: <natural language description of what tool call to look for>
+      after_step: <step_id this must come after, optional — omit if not needed>
+      before_step: <step_id this must come before, optional — omit if not needed>
+
+scoring:
+  threshold_promote_to_hook: 0.6
+
+Rules:
+- detector.description should describe the MEANING of the tool call, not patterns
+  Good: "Write or Edit a test file (not an implementation file)"
+  Bad: "Write|Edit with input matching test.*\\.py"
+- Use before_step/after_step for skills where ORDER matters (e.g. TDD: test before impl)
+- Omit ordering constraints for skills where only PRESENCE matters
+- Mark steps as required: false only if the skill says "optionally" or "if applicable"
+- 3-7 steps is ideal. Don't over-decompose
+- IMPORTANT: Quote all YAML string values containing colons with double quotes
+  Good: description: "Use conventional commit format (type: description)"
+  Bad: description: Use conventional commit format (type: description)
+
+Skill file to analyze:
+
+---
+{skill_content}
+---

package/.agent/skills/skill-comply/pyproject.toml

@@ -1,15 +1,15 @@
-[project]
-name = "skill-comply"
-version = "0.1.0"
-description = "Automated skill compliance measurement for Claude Code"
-requires-python = ">=3.11"
-dependencies = ["pyyaml>=6.0"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-pythonpath = ["."]
-
-[dependency-groups]
-dev = [
-    "pytest>=9.0.2",
-]
+[project]
+name = "skill-comply"
+version = "0.1.0"
+description = "Automated skill compliance measurement for Claude Code"
+requires-python = ">=3.11"
+dependencies = ["pyyaml>=6.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]

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

@@ -1,85 +1,85 @@
-"""Classify tool calls against compliance steps using LLM."""
-
-from __future__ import annotations
-
-import json
-import logging
-import subprocess
-from pathlib import Path
-
-logger = logging.getLogger(__name__)
-
-from scripts.parser import ComplianceSpec, ObservationEvent
-
-PROMPTS_DIR = Path(__file__).parent.parent / "prompts"
-
-
-def classify_events(
-    spec: ComplianceSpec,
-    trace: list[ObservationEvent],
-    model: str = "haiku",
-) -> dict[str, list[int]]:
-    """Classify which tool calls match which compliance steps.
-
-    Returns {step_id: [event_indices]} via a single LLM call.
-    """
-    if not trace:
-        return {}
-
-    steps_desc = "\n".join(
-        f"- {step.id}: {step.detector.description}"
-        for step in spec.steps
-    )
-
-    tool_calls = "\n".join(
-        f"[{i}] {event.tool}: input={event.input[:500]} output={event.output[:200]}"
-        for i, event in enumerate(trace)
-    )
-
-    prompt_template = (PROMPTS_DIR / "classifier.md").read_text()
-    prompt = (
-        prompt_template
-        .replace("{steps_description}", steps_desc)
-        .replace("{tool_calls}", tool_calls)
-    )
-
-    result = subprocess.run(
-        ["claude", "-p", prompt, "--model", model, "--output-format", "text"],
-        capture_output=True,
-        text=True,
-        timeout=60,
-    )
-
-    if result.returncode != 0:
-        raise RuntimeError(
-            f"classifier subprocess failed (rc={result.returncode}): "
-            f"{result.stderr[:500]}"
-        )
-
-    return _parse_classification(result.stdout)
-
-
-def _parse_classification(text: str) -> dict[str, list[int]]:
-    """Parse LLM classification output into {step_id: [event_indices]}."""
-    text = text.strip()
-    # Strip markdown fences
-    lines = text.splitlines()
-    if lines and lines[0].startswith("```"):
-        lines = lines[1:]
-    if lines and lines[-1].startswith("```"):
-        lines = lines[:-1]
-    cleaned = "\n".join(lines)
-
-    try:
-        parsed = json.loads(cleaned)
-        if not isinstance(parsed, dict):
-            logger.warning("Classifier returned non-dict JSON: %s", type(parsed).__name__)
-            return {}
-        return {
-            k: [int(i) for i in v]
-            for k, v in parsed.items()
-            if isinstance(v, list)
-        }
-    except (json.JSONDecodeError, ValueError, TypeError) as e:
-        logger.warning("Failed to parse classification output: %s", e)
-        return {}
+"""Classify tool calls against compliance steps using LLM."""
+
+from __future__ import annotations
+
+import json
+import logging
+import subprocess
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+from scripts.parser import ComplianceSpec, ObservationEvent
+
+PROMPTS_DIR = Path(__file__).parent.parent / "prompts"
+
+
+def classify_events(
+    spec: ComplianceSpec,
+    trace: list[ObservationEvent],
+    model: str = "haiku",
+) -> dict[str, list[int]]:
+    """Classify which tool calls match which compliance steps.
+
+    Returns {step_id: [event_indices]} via a single LLM call.
+    """
+    if not trace:
+        return {}
+
+    steps_desc = "\n".join(
+        f"- {step.id}: {step.detector.description}"
+        for step in spec.steps
+    )
+
+    tool_calls = "\n".join(
+        f"[{i}] {event.tool}: input={event.input[:500]} output={event.output[:200]}"
+        for i, event in enumerate(trace)
+    )
+
+    prompt_template = (PROMPTS_DIR / "classifier.md").read_text()
+    prompt = (
+        prompt_template
+        .replace("{steps_description}", steps_desc)
+        .replace("{tool_calls}", tool_calls)
+    )
+
+    result = subprocess.run(
+        ["claude", "-p", prompt, "--model", model, "--output-format", "text"],
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"classifier subprocess failed (rc={result.returncode}): "
+            f"{result.stderr[:500]}"
+        )
+
+    return _parse_classification(result.stdout)
+
+
+def _parse_classification(text: str) -> dict[str, list[int]]:
+    """Parse LLM classification output into {step_id: [event_indices]}."""
+    text = text.strip()
+    # Strip markdown fences
+    lines = text.splitlines()
+    if lines and lines[0].startswith("```"):
+        lines = lines[1:]
+    if lines and lines[-1].startswith("```"):
+        lines = lines[:-1]
+    cleaned = "\n".join(lines)
+
+    try:
+        parsed = json.loads(cleaned)
+        if not isinstance(parsed, dict):
+            logger.warning("Classifier returned non-dict JSON: %s", type(parsed).__name__)
+            return {}
+        return {
+            k: [int(i) for i in v]
+            for k, v in parsed.items()
+            if isinstance(v, list)
+        }
+    except (json.JSONDecodeError, ValueError, TypeError) as e:
+        logger.warning("Failed to parse classification output: %s", e)
+        return {}

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

@@ -1,122 +1,122 @@
-"""Grade observation traces against compliance specs using LLM classification."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from scripts.classifier import classify_events
-from scripts.parser import ComplianceSpec, ObservationEvent, Step
-
-
-@dataclass(frozen=True)
-class StepResult:
-    step_id: str
-    detected: bool
-    evidence: tuple[ObservationEvent, ...]
-    failure_reason: str | None
-
-
-@dataclass(frozen=True)
-class ComplianceResult:
-    spec_id: str
-    steps: tuple[StepResult, ...]
-    compliance_rate: float
-    recommend_hook_promotion: bool
-    classification: dict[str, list[int]]
-
-
-def _check_temporal_order(
-    step: Step,
-    event: ObservationEvent,
-    resolved: dict[str, list[ObservationEvent]],
-    classified: dict[str, list[ObservationEvent]],
-) -> str | None:
-    """Check before_step/after_step constraints. Returns failure reason or None."""
-    if step.detector.after_step is not None:
-        after_events = resolved.get(step.detector.after_step, [])
-        if not after_events:
-            return f"after_step '{step.detector.after_step}' not yet detected"
-        latest_after = max(e.timestamp for e in after_events)
-        if event.timestamp <= latest_after:
-            return (
-                f"must occur after '{step.detector.after_step}' "
-                f"(last at {latest_after}), but found at {event.timestamp}"
-            )
-
-    if step.detector.before_step is not None:
-        # Look ahead using LLM classification results
-        before_events = resolved.get(step.detector.before_step)
-        if before_events is None:
-            before_events = classified.get(step.detector.before_step, [])
-        if before_events:
-            earliest_before = min(e.timestamp for e in before_events)
-            if event.timestamp >= earliest_before:
-                return (
-                    f"must occur before '{step.detector.before_step}' "
-                    f"(first at {earliest_before}), but found at {event.timestamp}"
-                )
-
-    return None
-
-
-def grade(
-    spec: ComplianceSpec,
-    trace: list[ObservationEvent],
-    classifier_model: str = "haiku",
-) -> ComplianceResult:
-    """Grade a trace against a compliance spec using LLM classification."""
-    sorted_trace = sorted(trace, key=lambda e: e.timestamp)
-
-    # Step 1: LLM classifies all events in one batch call
-    classification = classify_events(spec, sorted_trace, model=classifier_model)
-
-    # Convert indices to events
-    classified: dict[str, list[ObservationEvent]] = {
-        step_id: [sorted_trace[i] for i in indices if 0 <= i < len(sorted_trace)]
-        for step_id, indices in classification.items()
-    }
-
-    # Step 2: Check temporal ordering (deterministic)
-    resolved: dict[str, list[ObservationEvent]] = {}
-    step_results: list[StepResult] = []
-
-    for step in spec.steps:
-        candidates = classified.get(step.id, [])
-        matched: list[ObservationEvent] = []
-        failure_reason: str | None = None
-
-        for event in candidates:
-            temporal_fail = _check_temporal_order(step, event, resolved, classified)
-            if temporal_fail is None:
-                matched.append(event)
-                break
-            else:
-                failure_reason = temporal_fail
-
-        detected = len(matched) > 0
-        if detected:
-            resolved[step.id] = matched
-        elif failure_reason is None:
-            failure_reason = f"no matching event classified for step '{step.id}'"
-
-        step_results.append(StepResult(
-            step_id=step.id,
-            detected=detected,
-            evidence=tuple(matched),
-            failure_reason=failure_reason if not detected else None,
-        ))
-
-    required_ids = {s.id for s in spec.steps if s.required}
-    required_steps = [s for s in step_results if s.step_id in required_ids]
-    detected_required = sum(1 for s in required_steps if s.detected)
-    total_required = len(required_steps)
-
-    compliance_rate = detected_required / total_required if total_required > 0 else 0.0
-
-    return ComplianceResult(
-        spec_id=spec.id,
-        steps=tuple(step_results),
-        compliance_rate=compliance_rate,
-        recommend_hook_promotion=compliance_rate < spec.threshold_promote_to_hook,
-        classification=classification,
-    )
+"""Grade observation traces against compliance specs using LLM classification."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from scripts.classifier import classify_events
+from scripts.parser import ComplianceSpec, ObservationEvent, Step
+
+
+@dataclass(frozen=True)
+class StepResult:
+    step_id: str
+    detected: bool
+    evidence: tuple[ObservationEvent, ...]
+    failure_reason: str | None
+
+
+@dataclass(frozen=True)
+class ComplianceResult:
+    spec_id: str
+    steps: tuple[StepResult, ...]
+    compliance_rate: float
+    recommend_hook_promotion: bool
+    classification: dict[str, list[int]]
+
+
+def _check_temporal_order(
+    step: Step,
+    event: ObservationEvent,
+    resolved: dict[str, list[ObservationEvent]],
+    classified: dict[str, list[ObservationEvent]],
+) -> str | None:
+    """Check before_step/after_step constraints. Returns failure reason or None."""
+    if step.detector.after_step is not None:
+        after_events = resolved.get(step.detector.after_step, [])
+        if not after_events:
+            return f"after_step '{step.detector.after_step}' not yet detected"
+        latest_after = max(e.timestamp for e in after_events)
+        if event.timestamp <= latest_after:
+            return (
+                f"must occur after '{step.detector.after_step}' "
+                f"(last at {latest_after}), but found at {event.timestamp}"
+            )
+
+    if step.detector.before_step is not None:
+        # Look ahead using LLM classification results
+        before_events = resolved.get(step.detector.before_step)
+        if before_events is None:
+            before_events = classified.get(step.detector.before_step, [])
+        if before_events:
+            earliest_before = min(e.timestamp for e in before_events)
+            if event.timestamp >= earliest_before:
+                return (
+                    f"must occur before '{step.detector.before_step}' "
+                    f"(first at {earliest_before}), but found at {event.timestamp}"
+                )
+
+    return None
+
+
+def grade(
+    spec: ComplianceSpec,
+    trace: list[ObservationEvent],
+    classifier_model: str = "haiku",
+) -> ComplianceResult:
+    """Grade a trace against a compliance spec using LLM classification."""
+    sorted_trace = sorted(trace, key=lambda e: e.timestamp)
+
+    # Step 1: LLM classifies all events in one batch call
+    classification = classify_events(spec, sorted_trace, model=classifier_model)
+
+    # Convert indices to events
+    classified: dict[str, list[ObservationEvent]] = {
+        step_id: [sorted_trace[i] for i in indices if 0 <= i < len(sorted_trace)]
+        for step_id, indices in classification.items()
+    }
+
+    # Step 2: Check temporal ordering (deterministic)
+    resolved: dict[str, list[ObservationEvent]] = {}
+    step_results: list[StepResult] = []
+
+    for step in spec.steps:
+        candidates = classified.get(step.id, [])
+        matched: list[ObservationEvent] = []
+        failure_reason: str | None = None
+
+        for event in candidates:
+            temporal_fail = _check_temporal_order(step, event, resolved, classified)
+            if temporal_fail is None:
+                matched.append(event)
+                break
+            else:
+                failure_reason = temporal_fail
+
+        detected = len(matched) > 0
+        if detected:
+            resolved[step.id] = matched
+        elif failure_reason is None:
+            failure_reason = f"no matching event classified for step '{step.id}'"
+
+        step_results.append(StepResult(
+            step_id=step.id,
+            detected=detected,
+            evidence=tuple(matched),
+            failure_reason=failure_reason if not detected else None,
+        ))
+
+    required_ids = {s.id for s in spec.steps if s.required}
+    required_steps = [s for s in step_results if s.step_id in required_ids]
+    detected_required = sum(1 for s in required_steps if s.detected)
+    total_required = len(required_steps)
+
+    compliance_rate = detected_required / total_required if total_required > 0 else 0.0
+
+    return ComplianceResult(
+        spec_id=spec.id,
+        steps=tuple(step_results),
+        compliance_rate=compliance_rate,
+        recommend_hook_promotion=compliance_rate < spec.threshold_promote_to_hook,
+        classification=classification,
+    )