claude-dev-env 2.4.0 → 2.5.0

package/skills/plan-to-pr/scripts/validate_run.py

@@ -0,0 +1,173 @@
+"""Validate a complete task-record set against an explicit Git commit set."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+from config.constants import (
+    COMMIT_RANGE_ARGUMENT_INDEX,
+    COMMIT_RANGE_SEPARATOR,
+    EXIT_CODE_INVALID_SET,
+    EXIT_CODE_VALID_SET,
+    JSON_ENCODING,
+    RUN_ARGUMENT_COUNT_REQUIRED,
+    RUN_ARGUMENT_COUNT_WITH_WORKTREE,
+    SET_VALIDATION_PASSED,
+    OPTION_ARGUMENT_INDEX,
+    WORKTREE_OPTION_ARGUMENT_INDEX,
+    WORKTREE_PATH_ARGUMENT_INDEX,
+    WORKTREE_OPTION,
+)
+from validate_protocol import ProtocolValidationError, validate_record
+
+
+def _load_record_list(record_path: Path) -> list[dict[str, object]]:
+    try:
+        parsed_records = json.loads(record_path.read_text(encoding=JSON_ENCODING))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise ProtocolValidationError("task-record set is not valid JSON") from error
+    if not isinstance(parsed_records, list) or any(
+        not isinstance(each_record, dict) for each_record in parsed_records
+    ):
+        raise ProtocolValidationError("task-record set must be a JSON list of objects")
+    return parsed_records
+
+
+def _git_commits(worktree: Path, commit_range: str) -> set[str]:
+    try:
+        completed = subprocess.run(
+            ["git", "rev-list", "--reverse", commit_range],
+            cwd=worktree,
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    except (OSError, subprocess.CalledProcessError) as error:
+        raise ProtocolValidationError("cannot read the requested commit set") from error
+    return {each_commit for each_commit in completed.stdout.splitlines() if each_commit}
+
+
+def validate_run(
+    all_task_records: Sequence[Mapping[str, object]],
+    all_commit_hashes: set[str],
+    schema_path: Path,
+    all_explicit_mapping: Mapping[str, str],
+) -> None:
+    """Validate task identity uniqueness and one-to-one commit coverage.
+
+    Args:
+        all_task_records: Task records to validate.
+        all_commit_hashes: Commits that the record set must cover.
+        schema_path: Path to the task-record schema JSON file.
+        all_explicit_mapping: Task-to-commit mapping; an empty mapping means
+            records must match commits by count and commit field.
+
+    Returns:
+        None.
+
+    Raises:
+        ProtocolValidationError: If task identity, commit coverage, or record
+            schema validation fails.
+    """
+    task_ids = [
+        each_task_id
+        for each_record in all_task_records
+        if isinstance((each_task_id := each_record.get("task_identity")), str)
+    ]
+    commits = [
+        each_commit
+        for each_record in all_task_records
+        if isinstance((each_commit := each_record.get("commit")), str)
+    ]
+    if len(task_ids) != len(all_task_records):
+        raise ProtocolValidationError("every task record needs a task_identity")
+    if len(task_ids) != len(set(task_ids)):
+        raise ProtocolValidationError("task identities must be unique")
+    if len(commits) != len(all_task_records):
+        raise ProtocolValidationError("every task record needs a commit")
+    if not all_explicit_mapping and len(all_task_records) != len(all_commit_hashes):
+        raise ProtocolValidationError("task and commit counts differ without an explicit mapping")
+    if all_explicit_mapping and len(all_explicit_mapping) != len(set(all_explicit_mapping.values())):
+        raise ProtocolValidationError("explicit task mappings must reference unique commits")
+    if all_explicit_mapping and set(all_explicit_mapping) != set(task_ids):
+        raise ProtocolValidationError("explicit task mappings must reference every task identity")
+    if all_explicit_mapping and any(
+        all_explicit_mapping[each_task_id] != each_commit
+        for each_task_id, each_commit in zip(task_ids, commits)
+    ):
+        raise ProtocolValidationError("explicit task mappings must match record commits")
+    mapped_commits = set(all_explicit_mapping.values()) if all_explicit_mapping else set(commits)
+    if mapped_commits != all_commit_hashes:
+        raise ProtocolValidationError("task records must reference every and only requested commit")
+    for each_record in all_task_records:
+        validate_record(each_record, schema_path)
+
+
+def main(all_cli_arguments: Sequence[str]) -> int:
+    """Validate a record list against a requested commit set.
+
+    Args:
+        all_cli_arguments: Program name followed by record and commit-set
+            arguments, with an optional worktree path.
+
+    Returns:
+        Exit code `0` for a valid set or `2` for invalid input.
+
+    Raises:
+        No exceptions: validation failures are reported and converted to an
+            invalid-set exit code.
+    """
+    if len(all_cli_arguments) not in {
+        RUN_ARGUMENT_COUNT_REQUIRED,
+        RUN_ARGUMENT_COUNT_WITH_WORKTREE,
+        RUN_ARGUMENT_COUNT_WITH_WORKTREE + 1,
+    }:
+        print("usage: validate_run.py <records.json> --base-head <BASE..HEAD> [--worktree PATH]", file=sys.stderr)
+        return EXIT_CODE_INVALID_SET
+    record_path = Path(all_cli_arguments[1])
+    option = all_cli_arguments[OPTION_ARGUMENT_INDEX]
+    commit_range = all_cli_arguments[COMMIT_RANGE_ARGUMENT_INDEX]
+    has_legacy_worktree_argument = len(all_cli_arguments) == RUN_ARGUMENT_COUNT_WITH_WORKTREE
+    has_flagged_worktree_argument = len(all_cli_arguments) == RUN_ARGUMENT_COUNT_WITH_WORKTREE + 1
+    if has_flagged_worktree_argument and all_cli_arguments[WORKTREE_OPTION_ARGUMENT_INDEX] != WORKTREE_OPTION:
+        print("usage: validate_run.py <records.json> --base-head <BASE..HEAD> [--worktree PATH]", file=sys.stderr)
+        return EXIT_CODE_INVALID_SET
+    worktree = Path.cwd()
+    if has_legacy_worktree_argument:
+        worktree = Path(all_cli_arguments[WORKTREE_OPTION_ARGUMENT_INDEX])
+    if has_flagged_worktree_argument:
+        worktree = Path(all_cli_arguments[WORKTREE_PATH_ARGUMENT_INDEX])
+    try:
+        all_task_records = _load_record_list(record_path)
+        if has_legacy_worktree_argument or has_flagged_worktree_argument:
+            for each_record in all_task_records:
+                each_record["worktree"] = str(worktree)
+        if option == "--base-head":
+            if COMMIT_RANGE_SEPARATOR not in commit_range:
+                raise ProtocolValidationError("base-head must be BASE..HEAD")
+            all_commit_hashes = _git_commits(worktree, commit_range)
+        elif option == "--commits":
+            all_commit_hashes = {
+                each_commit for each_commit in commit_range.split(",") if each_commit
+            }
+        else:
+            raise ProtocolValidationError("unknown commit-set option")
+        validate_run(
+            all_task_records,
+            all_commit_hashes,
+            Path(__file__).parent.parent / "reference" / "run-record.schema.json",
+            {},
+        )
+    except ProtocolValidationError as error:
+        print(f"run validation failed: {error}", file=sys.stderr)
+        return EXIT_CODE_INVALID_SET
+    print(SET_VALIDATION_PASSED)
+    return EXIT_CODE_VALID_SET
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

package/skills/plan-to-pr/test_skill_contract.py

@@ -0,0 +1,207 @@
+import re
+from pathlib import Path
+
+
+SKILL_DIRECTORY = Path(__file__).parent
+SKILL_PATH = SKILL_DIRECTORY / "SKILL.md"
+MODEL_ROUTING_PATH = SKILL_DIRECTORY / "reference" / "model-routing.md"
+TASK_TICKET_PATH = SKILL_DIRECTORY / "reference" / "task-ticket.md"
+PACKET_CONTRACT_PATH = SKILL_DIRECTORY / "reference" / "packet-contract.md"
+PACKET_SCHEMA_PATH = SKILL_DIRECTORY / "reference" / "packet-schema.json"
+VALIDATION_SCRIPT_PATH = SKILL_DIRECTORY / "scripts" / "validate_protocol.py"
+RUN_VALIDATION_SCRIPT_PATH = SKILL_DIRECTORY / "scripts" / "validate_run.py"
+PACKET_CREATOR_PATH = SKILL_DIRECTORY / "scripts" / "create_packet.py"
+PACKET_VALIDATOR_PATH = SKILL_DIRECTORY / "scripts" / "validate_packet.py"
+FORBIDDEN_ROUTE_TEXT = ("external planning provider", "Workflow dependency")
+EXPECTED_TASK_PROTOCOL_HEADING = "## One-task and one-commit protocol"
+
+
+def read_skill_text() -> str:
+    return SKILL_PATH.read_text(encoding="utf-8")
+
+
+def read_reference_texts() -> tuple[str, str, str]:
+    return (
+        MODEL_ROUTING_PATH.read_text(encoding="utf-8"),
+        TASK_TICKET_PATH.read_text(encoding="utf-8"),
+        PACKET_CONTRACT_PATH.read_text(encoding="utf-8"),
+    )
+
+
+def test_skill_frontmatter_defines_third_person_trigger_catalog() -> None:
+    skill_text = read_skill_text()
+
+    assert skill_text.startswith("---\nname: plan-to-pr\n")
+    description_text = skill_text.split("description:", 1)[1].split("---", 1)[0]
+    assert "Triggers:" in description_text
+    assert "Coordinates" in description_text
+    assert not re.search(r"\b(I|[Ww]e|[Oo]ur|[Mm]y)\b", description_text)
+
+
+def test_skill_contract_names_capability_boundary_and_refusals() -> None:
+    skill_text = read_skill_text()
+
+    assert "## Capability boundary" in skill_text
+    assert "## Refusal cases" in skill_text
+    assert "one deliverable" in skill_text
+    assert "one allowed file set" in skill_text
+    assert "one acceptance check" in skill_text
+    assert "one commit" in skill_text
+    assert "fail closed" in skill_text
+    assert "Plan-to-PR blocked: <missing input or capability>." in skill_text
+
+
+def test_skill_contract_requires_native_packet_planning_before_task_seeding() -> None:
+    skill_text = read_skill_text()
+
+    assert "## Native planning phase" in skill_text
+    assert "before task seeding and before implementation" in skill_text
+    assert "Luna max planner" in skill_text
+    assert "Sol xhigh advisor" in skill_text
+    assert "native planning packet" in skill_text
+    assert (
+        "Only a passing packet with `status: approved` may seed host tasks"
+        in skill_text
+    )
+    assert skill_text.index("## Native planning phase") < skill_text.index(
+        "## Runtime and task seeding"
+    )
+    assert "anthropic-plan" not in skill_text
+    assert "Workflow" not in skill_text
+
+
+def test_skill_contract_pins_model_roles_and_worker_routing() -> None:
+    skill_text = read_skill_text()
+
+    assert "planner and final validator use Luna max" in skill_text
+    assert "orchestrator uses the max route" in skill_text
+    assert "Sol xhigh advisor" in skill_text
+    assert "Sol xhigh advisor heavily at scope" in skill_text
+    assert (
+        "Every implementation,\nreview, and repair worker uses fast, low-effort Luna"
+        in skill_text
+    )
+    assert "separate fast low-effort Luna review worker" in skill_text
+    assert "separate fast low-effort Luna repair worker" in skill_text
+    assert "Unavailable models or routing tools\nfail closed" in skill_text
+
+
+def test_skill_contract_enforces_task_commit_and_review_order() -> None:
+    skill_text = read_skill_text()
+
+    assert EXPECTED_TASK_PROTOCOL_HEADING in skill_text
+    assert "fresh verification and `verified_commit_gate`" in skill_text
+    assert (
+        "native\nfindings-only correctness review at `/e-code-review low`" in skill_text
+    )
+    assert "findings-only" in skill_text
+    assert "has no repair" in skill_text
+    assert "separate fast low-effort Luna repair worker" in skill_text
+    assert "Rerun the task acceptance check and fresh" in skill_text
+    assert "exact-surface verification" in skill_text
+    assert "amend the task commit" in skill_text.lower()
+    assert (
+        "Record resolved model, effort, command, findings, repair status, and"
+        in skill_text
+    )
+    assert "surface" in skill_text
+    assert "repeat native review" in skill_text
+    assert "until clean" in skill_text
+    assert "maps every commit to one packet task" in skill_text
+
+
+def test_skill_contract_uses_only_the_native_review_route() -> None:
+    all_contract_text = "\n".join((read_skill_text(), *read_reference_texts()))
+
+    assert "/e-code-review low" in all_contract_text
+    assert "findings only" in all_contract_text
+    assert "no repair flag" in all_contract_text
+    assert "separate fast low-effort Luna" in all_contract_text
+    assert "fresh exact-surface verification" in all_contract_text
+    assert "/e-simplify" in all_contract_text
+    assert "cleanup-only" in all_contract_text
+    assert "cleanup-only" in all_contract_text
+    assert "skill-builder" not in all_contract_text
+    for each_forbidden_route_text in FORBIDDEN_ROUTE_TEXT:
+        assert each_forbidden_route_text not in all_contract_text
+
+
+def test_skill_contract_records_review_fields_in_both_references() -> None:
+    model_routing_text, task_ticket_text, packet_contract_text = read_reference_texts()
+    review_fields = (
+        "resolved model",
+        "effort",
+        "command",
+        "findings",
+        "repair status",
+        "surface hash",
+    )
+
+    for each_review_field in review_fields:
+        assert each_review_field in model_routing_text
+        assert each_review_field in task_ticket_text
+    assert "packet.json" in packet_contract_text
+
+
+def test_skill_contract_references_future_fixed_artifacts_without_copying_tables() -> (
+    None
+):
+    skill_text = read_skill_text()
+
+    assert "reference/model-routing.md" in skill_text
+    assert "reference/task-ticket.md" in skill_text
+    assert "reference/packet-contract.md" in skill_text
+    assert "reference/packet-schema.json" in skill_text
+    assert "scripts/validate_protocol.py" in skill_text
+    assert "fixed routing and gate matrix lives only" not in skill_text
+    assert "fixed fields live in" in skill_text
+    assert (
+        "[`reference/run-record.schema.json`](reference/run-record.schema.json)"
+        in skill_text
+    )
+
+
+def test_skill_contract_companion_reference_paths_exist() -> None:
+    skill_text = read_skill_text()
+    local_reference_paths = re.findall(r"\]\(([^)]+)\)", skill_text)
+    repository_paths = [
+        each_path
+        for each_path in local_reference_paths
+        if not each_path.startswith(("http://", "https://", "#"))
+    ]
+
+    assert repository_paths
+    for each_path in repository_paths:
+        assert (SKILL_DIRECTORY / each_path).exists(), each_path
+
+
+def test_skill_contract_requires_self_audit_and_publication_gates() -> None:
+    skill_text = read_skill_text()
+
+    assert "Run the workflow self-audit and retain its evidence." in skill_text
+    assert "unresolved finding blocks\npublication." in skill_text
+    assert "Publish only when final validation\nand self-audit pass." in skill_text
+    assert "Luna max `/e-simplify`" in skill_text
+    assert "Luna low `/e-code-review max loop`" in skill_text
+    assert "no repair flag" in skill_text
+
+
+def test_skill_contract_requires_packet_companions_and_validation_scripts() -> None:
+    skill_text = read_skill_text()
+
+    for each_path in (
+        PACKET_CONTRACT_PATH,
+        PACKET_SCHEMA_PATH,
+        PACKET_CREATOR_PATH,
+        PACKET_VALIDATOR_PATH,
+        VALIDATION_SCRIPT_PATH,
+        RUN_VALIDATION_SCRIPT_PATH,
+    ):
+        assert each_path.exists(), each_path
+
+    assert "reference/packet-contract.md" in skill_text
+    assert "reference/packet-schema.json" in skill_text
+    assert "scripts/create_packet.py" in skill_text
+    assert "scripts/validate_packet.py" in skill_text
+    assert "scripts/validate_protocol.py" in skill_text
+    assert "scripts/validate_run.py" in skill_text

package/skills/plan-to-pr/test_task_ticket_contract.py

@@ -0,0 +1,151 @@
+import json
+import re
+from pathlib import Path
+
+
+SKILL_DIRECTORY = Path(__file__).parent
+REFERENCE_DIRECTORY = SKILL_DIRECTORY / "reference"
+SKILL_PATH = SKILL_DIRECTORY / "SKILL.md"
+SCHEMA_PATH = REFERENCE_DIRECTORY / "run-record.schema.json"
+REFERENCE_NAMES = (
+    "packet-contract.md",
+    "review-loop.md",
+    "task-seeds.md",
+    "final-validation-tasks.md",
+    "process-inventory.md",
+    "self-audit-tasks.md",
+)
+FORBIDDEN_ROUTE_TEXT = (
+    "external planning provider",
+    "Workflow dependency",
+    "skill-builder",
+    "--fix",
+    "C:\\Users\\",
+)
+
+
+def read_reference_texts() -> str:
+    return "\n".join(
+        [SKILL_PATH.read_text(encoding="utf-8")]
+        + [
+            (REFERENCE_DIRECTORY / each_name).read_text(encoding="utf-8")
+            for each_name in REFERENCE_NAMES
+        ]
+    )
+
+
+def test_references_exist_and_are_linked_directly() -> None:
+    skill_text = SKILL_PATH.read_text(encoding="utf-8")
+
+    for each_name in REFERENCE_NAMES:
+        assert (REFERENCE_DIRECTORY / each_name).exists()
+        assert f"reference/{each_name}" in skill_text
+
+    assert (REFERENCE_DIRECTORY / "packet-schema.json").exists()
+    assert "reference/packet-schema.json" in skill_text
+    assert (SKILL_DIRECTORY / "scripts" / "validate_protocol.py").exists()
+    assert (SKILL_DIRECTORY / "scripts" / "validate_run.py").exists()
+
+
+def test_packet_schema_requires_native_planning_fields() -> None:
+    packet_schema = json.loads(
+        (REFERENCE_DIRECTORY / "packet-schema.json").read_text(encoding="utf-8")
+    )
+
+    assert {
+        "schema_version",
+        "slug",
+        "status",
+        "request",
+        "allowed_files",
+        "sources",
+        "decisions",
+        "open_questions",
+        "tasks",
+        "validation",
+    } <= set(packet_schema["required"])
+    assert packet_schema["properties"]["status"]["enum"] == ["draft", "approved"]
+    assert packet_schema["$defs"]["validation"]["properties"]["validated_by"] == {
+        "const": "native-plan-to-pr"
+    }
+
+
+def test_run_record_schema_requires_task_and_review_records() -> None:
+    schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
+    required_fields = set(schema["required"])
+
+    assert {
+        "task_identity",
+        "commit",
+        "review_record",
+        "repair_record",
+        "reverification_record",
+        "verification_record",
+    } <= required_fields
+    review_fields = set(schema["$defs"]["review_record"]["required"])
+    assert {"findings_only", "has_repair_flag", "command"} <= review_fields
+    assert schema["$defs"]["review_record"]["properties"]["command"] == {
+        "type": "string",
+        "minLength": 1,
+    }
+
+
+def test_review_loop_requires_separate_native_review_and_repair() -> None:
+    contract_text = read_reference_texts()
+
+    assert "separate fast low-effort Luna review worker" in contract_text
+    assert "native findings-only" in contract_text
+    assert "/e-code-review low" in contract_text
+    assert "correctness" in contract_text
+    assert "/e-code-review low" in contract_text
+    assert "has no repair flag" in contract_text
+    assert "separate fast low-effort Luna repair worker" in contract_text
+    assert "confirmed findings" in contract_text
+    assert "Amend the task commit" in contract_text
+    assert "repeat the native review until clean" in contract_text
+    assert "packet is complete before `TaskCreate` or `TodoWrite` runs" in contract_text
+
+
+def test_post_pr_cleanup_and_max_review_are_distinct() -> None:
+    contract_text = read_reference_texts()
+
+    assert "Luna max `/e-simplify`" in contract_text
+    assert "cleanup-only" in contract_text
+    assert "Luna low `/e-code-review max loop`" in contract_text
+    assert "separate Luna low repair worker" in contract_text
+    assert "commits, and pushes" in contract_text
+    assert "clean" in contract_text
+    assert "skill-builder" not in contract_text
+
+
+def test_packet_planning_precedes_task_seeding_and_has_no_external_dependency() -> None:
+    contract_text = read_reference_texts()
+
+    assert "before any `TaskCreate` or `TodoWrite` seeding" in contract_text
+    assert (
+        "Only a passing packet with `status: approved` may seed host tasks"
+        in contract_text
+    )
+    assert "external planning provider" not in contract_text
+    assert "Workflow dependency" not in contract_text
+
+
+def test_task_seeding_and_audit_inventories_are_present() -> None:
+    contract_text = read_reference_texts()
+
+    assert "TaskCreate" in contract_text
+    assert "TodoWrite" in contract_text
+    assert "deterministic" in contract_text
+    assert "judgment" in contract_text
+    assert "borderline" in contract_text
+    assert "final-validation" in contract_text
+    assert "self-audit" in contract_text
+    assert re.search(r"\n1\. .*\n2\. .*\n3\. ", contract_text)
+
+
+def test_contract_avoids_forbidden_route_strings_and_absolute_paths() -> None:
+    contract_text = read_reference_texts()
+
+    for each_forbidden_route_text in FORBIDDEN_ROUTE_TEXT:
+        assert each_forbidden_route_text not in contract_text
+    assert not re.search(r"[A-Za-z]:[/\\]", contract_text)