claude-dev-env 2.3.0 → 2.5.0

package/skills/plan-to-pr/scripts/config/constants.py

@@ -0,0 +1,193 @@
+"""Named values for deterministic skill protocol validation."""
+
+import re
+
+ALLOWED_WORKER_ROLE: str = "implementation worker"
+ALLOWED_WORKER_EFFORT: str = "low"
+ALLOWED_REVIEW_MODEL: str = "Luna"
+NATIVE_REVIEW_COMMAND: str = "/e-code-review low"
+PASSED_EVIDENCE_PREFIX: str = "passed:"
+SURFACE_HASH_PATTERN: re.Pattern[str] = re.compile(r"^[0-9a-f]{64}$")
+PATH_SEPARATOR_PATTERN: re.Pattern[str] = re.compile(r"[/\\]+")
+DOCS_PLANS_PATH_PATTERN: re.Pattern[str] = re.compile(r"^docs/plans(?:/|$)")
+SLUG_PATTERN: re.Pattern[str] = re.compile(r"[a-z0-9](?:[a-z0-9-]*[a-z0-9])?")
+SOURCE_LOCATOR_PATTERN: re.Pattern[str] = re.compile(
+    r"^(?:line|lines|section)\s+\S(?:.*\S)?$", re.IGNORECASE
+)
+PATH_TRAVERSAL_TOKEN: str = ".."
+REPRODUCIBILITY_BLOCK_PATTERN: re.Pattern[str] = re.compile(
+    r"\b(?:date|random|uuidgen|pwsh\s+-c)\b", re.IGNORECASE
+)
+UNRESOLVED_TEXT_PATTERN: re.Pattern[str] = re.compile(
+    r"\b(?:todo|tbd|fixme|placeholder|open questions|to be decided|fill this in)\b|\{\{[^}]+\}\}|<[A-Za-z][^>]*>",
+    re.IGNORECASE,
+)
+COMMIT_RANGE_SEPARATOR: str = ".."
+EXIT_CODE_USAGE_ERROR: int = 2
+PACKET_CREATION_ERROR_EXIT_CODE: int = 2
+PACKET_VALIDATION_ERROR_EXIT_CODE: int = 2
+EXIT_CODE_VALID_SET: int = 0
+EXIT_CODE_INVALID_SET: int = 2
+VALIDATION_PASSED: str = "run validation passed"
+SET_VALIDATION_PASSED: str = "run set validation passed"
+WORKTREE_OPTION: str = "--worktree"
+BASE_HEAD_OPTION: str = "--base-head"
+COMMIT_SET_OPTION: str = "--commits"
+FINDING_STATUS_CONFIRMED: str = "confirmed"
+FINDING_STATUS_DISMISSED: str = "dismissed"
+REPAIR_STATUS_COMPLETE: str = "complete"
+REPAIR_STATUS_NOT_REQUIRED: str = "not-required"
+REVIEW_STATUS_CLEAN: str = "clean"
+GIT_COMMAND: str = "git"
+GIT_DIFF_FORMAT: str = "--format="
+GIT_DIFF_SEPARATOR: str = "\n"
+SHA256_ALGORITHM: str = "sha256"
+ALL_REQUIRED_PACKET_FILES: tuple[str, ...] = (
+    "packet.json",
+    "context.md",
+    "plan.md",
+    "tasks.md",
+    "handoff.md",
+)
+ALL_SOURCE_FIELDS: tuple[str, ...] = ("path", "locator", "fact")
+ALL_TASK_FIELDS: tuple[str, ...] = (
+    "deliverable",
+    "acceptance_command",
+    "test_command",
+    "verification_command",
+)
+ALL_TASK_COMMAND_FIELDS: tuple[str, ...] = (
+    "acceptance_command",
+    "test_command",
+    "verification_command",
+)
+HANDOFF_APPROVAL_LINE: str = "Approval: approved"
+HANDOFF_TASK_ORDER_PREFIX: str = "Task Order: "
+HANDOFF_PACKET_PREFIX: str = "Packet: "
+HANDOFF_ALLOWED_FILES_PREFIX: str = "Allowed files: "
+HANDOFF_ACCEPTANCE_PREFIX: str = "Acceptance command: "
+HANDOFF_TEST_PREFIX: str = "Test command: "
+HANDOFF_VERIFICATION_PREFIX: str = "Verification command: "
+TASK_LINE_PREFIX: str = "Task "
+HANDOFF_TASK_LINE_PATTERN: re.Pattern[str] = re.compile(r"^Task (task-[0-9]+):")
+LINE_SEPARATOR: str = "\n"
+COMMAND_SEPARATOR: str = ", "
+MARKDOWN_FIELD_SEPARATOR: str = ";"
+MARKDOWN_HEADING_PATTERN: re.Pattern[str] = re.compile(
+    r"^#+\s+\S.*\s*$", re.MULTILINE | re.IGNORECASE
+)
+MARKDOWN_HEADING_TEMPLATE: str = r"^#+\s+{}\s*$"
+PACKET_DIRECTORY_MINIMUM_PARTS: int = 3
+PACKET_JSON_INDENT_LEVEL: int = 2
+DOCS_DIRECTORY_NAME: str = "docs"
+NEWLINE_SEPARATOR: str = "\n"
+PACKET_PARENT_PARTS_SLICE_START: int = -3
+PACKET_SLUG_PARTS_SLICE_END: int = -1
+ALL_PACKET_FIELDS: tuple[str, ...] = (
+    "schema_version",
+    "slug",
+    "status",
+    "request",
+    "allowed_files",
+    "sources",
+    "decisions",
+    "open_questions",
+    "tasks",
+    "validation",
+)
+ALL_PACKET_REQUIRED_FIELDS: tuple[str, ...] = ALL_PACKET_FIELDS
+ALL_VALIDATION_FIELDS: tuple[str, ...] = (
+    "schema_valid",
+    "boundary_valid",
+    "markdown_matches",
+    "validated_by",
+)
+ALL_TASK_CONTRACT_FIELDS: tuple[str, ...] = (
+    "id",
+    "deliverable",
+    "allowed_files",
+    "acceptance_command",
+    "test_command",
+    "verification_command",
+    "commit",
+    "dependencies",
+)
+
+ARGUMENT_COUNT_REQUIRED: int = 2
+ARGUMENT_COUNT_WITH_WORKTREE: int = 4
+RUN_ARGUMENT_COUNT_REQUIRED: int = 4
+RUN_ARGUMENT_COUNT_WITH_WORKTREE: int = 5
+OPTION_ARGUMENT_INDEX: int = 2
+COMMIT_RANGE_ARGUMENT_INDEX: int = 3
+WORKTREE_OPTION_ARGUMENT_INDEX: int = 4
+WORKTREE_PATH_ARGUMENT_INDEX: int = 5
+COMMIT_HASH_PATTERN: re.Pattern[str] = re.compile(r"^[0-9a-f]{7,40}$")
+COMMIT_HASH_ERROR_TEMPLATE: str = (
+    "record.commit must be a %d-%d character lowercase commit hash"
+)
+EXIT_CODE_INVALID_RECORD: int = 2
+EXIT_CODE_VALID_RECORD: int = 0
+JSON_ENCODING: str = "utf-8"
+MAXIMUM_COMMIT_HASH_LENGTH: int = 40
+MINIMUM_COMMIT_HASH_LENGTH: int = 7
+MISSING_FIELD_SEPARATOR: str = ", "
+PROTOCOL_VALIDATION_PASSED: str = "protocol validation passed"
+RECORD_SCHEMA_FILENAME: str = "run-record.schema.json"
+ALL_SUPPORTED_SCHEMA_TYPES: tuple[str, ...] = ("object", "array", "string", "boolean")
+ALL_RECORD_FIELDS: tuple[str, ...] = (
+    "task_identity",
+    "deliverable",
+    "allowed_files",
+    "acceptance_check",
+    "baseline",
+    "worker_route",
+    "commit",
+    "review_record",
+    "repair_record",
+    "reverification_record",
+    "verification_record",
+)
+ALL_ALLOWED_RECORD_FIELDS: tuple[str, ...] = ALL_RECORD_FIELDS + ("worktree",)
+ALL_TOP_LEVEL_TEXT_FIELDS: tuple[str, ...] = (
+    "task_identity",
+    "deliverable",
+    "acceptance_check",
+    "baseline",
+    "worker_route",
+)
+ALL_REVIEW_FIELDS: tuple[str, ...] = (
+    "resolved_model",
+    "effort",
+    "command",
+    "findings",
+    "repair_status",
+    "surface_hash",
+    "findings_only",
+    "has_repair_flag",
+)
+ALL_REPAIR_FIELDS: tuple[str, ...] = (
+    "resolved_model",
+    "effort",
+    "confirmed_findings",
+    "repair_status",
+    "surface_hash",
+)
+ALL_VERIFICATION_FIELDS: tuple[str, ...] = (
+    "acceptance_output",
+    "verifier_output",
+    "verified_commit_gate",
+    "surface_hash",
+)
+ALL_REVIEW_TEXT_FIELDS: tuple[str, ...] = (
+    "resolved_model",
+    "effort",
+    "command",
+    "repair_status",
+    "surface_hash",
+)
+ALL_REPAIR_TEXT_FIELDS: tuple[str, ...] = (
+    "resolved_model",
+    "effort",
+    "repair_status",
+    "surface_hash",
+)

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

@@ -0,0 +1,173 @@
+"""Create a deterministic native plan-to-PR packet skeleton."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+if str(Path(__file__).parent) not in sys.path:
+    sys.path.insert(0, str(Path(__file__).parent))
+
+from config.constants import (
+    PACKET_CREATION_ERROR_EXIT_CODE,
+    PACKET_JSON_INDENT_LEVEL,
+    SLUG_PATTERN,
+)
+
+
+def _parse_arguments() -> argparse.Namespace:
+    """Parse packet creation arguments."""
+    parser = argparse.ArgumentParser(
+        description="Create a native planning packet skeleton."
+    )
+    parser.add_argument("--repo-root", required=True, type=Path)
+    parser.add_argument("--slug", required=True)
+    parser.add_argument("--base-ref", required=True)
+    return parser.parse_args()
+
+
+def _validate_slug(slug: str) -> None:
+    """Raise an error when a slug cannot name one plan directory."""
+    if not SLUG_PATTERN.fullmatch(slug):
+        raise ValueError(
+            "slug must contain lowercase letters, numbers, and single hyphens"
+        )
+
+
+def _resolve_base_commit(repo_root: Path, base_ref: str) -> str:
+    """Resolve a base ref to its full commit hash."""
+    if base_ref.startswith("-"):
+        raise ValueError("base-ref must not start with a hyphen")
+    completed_command = subprocess.run(
+        [
+            "git",
+            "-C",
+            str(repo_root),
+            "rev-parse",
+            "--verify",
+            f"{base_ref}^{{commit}}",
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    if completed_command.returncode != 0:
+        error_message = completed_command.stderr.strip() or "unable to resolve base-ref"
+        raise ValueError(error_message)
+    return completed_command.stdout.strip()
+
+
+def _build_packet_payload(
+    slug: str, base_ref: str, base_commit: str
+) -> dict[str, object]:
+    """Build the schema-shaped packet manifest without repository assumptions."""
+    return {
+        "schema_version": 1,
+        "slug": slug,
+        "status": "draft",
+        "request": f"Plan work for {slug}.",
+        "allowed_files": [],
+        "sources": [],
+        "decisions": [
+            f"Base ref {base_ref} resolves to commit {base_commit}.",
+            "Scope is pending planner review.",
+        ],
+        "open_questions": [
+            "What repository behavior and files does the request require?"
+        ],
+        "tasks": [
+            {
+                "id": "task-1",
+                "deliverable": "Planner-defined deliverable",
+                "allowed_files": ["docs/plans/" + slug],
+                "acceptance_command": "Planner-defined acceptance command",
+                "test_command": "Planner-defined test command",
+                "verification_command": "Planner-defined verification command",
+                "commit": 1,
+            }
+        ],
+        "validation": {
+            "schema_valid": False,
+            "boundary_valid": False,
+            "markdown_matches": False,
+            "validated_by": "native-plan-to-pr",
+        },
+    }
+
+
+def _write_packet_file(packet_file: Path, packet_text: str) -> None:
+    """Write one packet file using stable UTF-8 content."""
+    packet_file.write_text(packet_text, encoding="utf-8", newline="\n")
+
+
+def create_packet(repo_root: Path, slug: str, base_ref: str) -> Path:
+    """Create and return a new packet directory under the repository plans path.
+
+    Args:
+        repo_root: Repository containing the plans directory.
+        slug: Packet directory slug.
+        base_ref: Git reference used for the packet decision record.
+    Returns:
+        The created packet directory.
+    Raises:
+        ValueError: If the slug or base reference is invalid.
+        FileExistsError: If the packet directory already exists.
+    """
+    _validate_slug(slug)
+    resolved_repo_root = repo_root.resolve()
+    base_commit = _resolve_base_commit(resolved_repo_root, base_ref)
+    packet_directory = resolved_repo_root / "docs" / "plans" / slug
+    if packet_directory.exists():
+        raise FileExistsError(f"packet already exists: {packet_directory}")
+
+    for each_directory in (
+        packet_directory,
+        packet_directory / "requirements",
+        packet_directory / "tasks",
+    ):
+        each_directory.mkdir(parents=True, exist_ok=True)
+
+    packet_payload = _build_packet_payload(slug, base_ref, base_commit)
+    packet_json = (
+        json.dumps(packet_payload, indent=PACKET_JSON_INDENT_LEVEL, sort_keys=True)
+        + "\n"
+    )
+    packet_files = {
+        "packet.json": packet_json,
+        "context.md": "# Context\n\nThe planner records repository facts and source references here.\n",
+        "plan.md": "# Plan\n\nThe planner records ordered implementation decisions here.\n",
+        "tasks.md": "# Tasks\n\nThe planner records one deliverable per task here.\n",
+        "handoff.md": "# Handoff\n\nThe planner records the approved host task seed here.\n",
+        "requirements/README.md": "# Requirements\n\nThe planner records confirmed requirements here.\n",
+        "tasks/README.md": "# Task Records\n\nThe planner records task details here.\n",
+    }
+    for each_relative_path, each_file_text in packet_files.items():
+        _write_packet_file(packet_directory / each_relative_path, each_file_text)
+    return packet_directory
+
+
+def main() -> int:
+    """Create a packet and print its repository-relative path.
+
+    Returns:
+        The process status code.
+    """
+    parsed_arguments = _parse_arguments()
+    try:
+        packet_directory = create_packet(
+            parsed_arguments.repo_root,
+            parsed_arguments.slug,
+            parsed_arguments.base_ref,
+        )
+    except (FileExistsError, OSError, ValueError) as packet_error:
+        print(str(packet_error), file=sys.stderr)
+        return PACKET_CREATION_ERROR_EXIT_CODE
+    print(packet_directory)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,102 @@
+"""Behavior tests for the native packet skeleton CLI."""
+
+from __future__ import annotations
+
+import json
+import importlib.util
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+script_path = Path(__file__).with_name("create_packet.py")
+script_spec = importlib.util.spec_from_file_location("create_packet", script_path)
+assert script_spec is not None
+assert script_spec.loader is not None
+script_module = importlib.util.module_from_spec(script_spec)
+sys.modules["create_packet"] = script_module
+script_spec.loader.exec_module(script_module)
+create_packet = script_module.create_packet
+
+
+def initialize_repository(repository_path: Path) -> str:
+    """Create a temporary Git repository and return its commit hash."""
+    subprocess.run(
+        ["git", "-C", str(repository_path), "init"], check=True, capture_output=True
+    )
+    subprocess.run(
+        [
+            "git",
+            "-C",
+            str(repository_path),
+            "config",
+            "user.email",
+            "test@example.invalid",
+        ],
+        check=True,
+    )
+    subprocess.run(
+        ["git", "-C", str(repository_path), "config", "user.name", "Test User"],
+        check=True,
+    )
+    (repository_path / "README.md").write_text("repository\n", encoding="utf-8")
+    subprocess.run(["git", "-C", str(repository_path), "add", "README.md"], check=True)
+    subprocess.run(
+        ["git", "-C", str(repository_path), "commit", "-m", "initial"],
+        check=True,
+        capture_output=True,
+    )
+    return subprocess.check_output(
+        ["git", "-C", str(repository_path), "rev-parse", "HEAD"], text=True
+    ).strip()
+
+
+def test_create_packet_writes_deterministic_skeleton(tmp_path: Path) -> None:
+    """A packet contains the schema fields, base commit, and stable files."""
+    base_commit = initialize_repository(tmp_path)
+
+    packet_directory = create_packet(tmp_path, "sample-plan", "HEAD")
+
+    packet_payload = json.loads(
+        (packet_directory / "packet.json").read_text(encoding="utf-8")
+    )
+    assert packet_payload["status"] == "draft"
+    assert base_commit in packet_payload["decisions"][0]
+    assert (packet_directory / "requirements" / "README.md").is_file()
+    assert (packet_directory / "tasks" / "README.md").is_file()
+    assert sorted(path.name for path in packet_directory.glob("*.md")) == [
+        "context.md",
+        "handoff.md",
+        "plan.md",
+        "tasks.md",
+    ]
+
+
+@pytest.mark.parametrize(
+    "unsafe_slug", ["../escape", "Upper", "with space", "-leading"]
+)
+def test_create_packet_rejects_unsafe_slug(tmp_path: Path, unsafe_slug: str) -> None:
+    """Unsafe slugs fail before a plan directory is created."""
+    initialize_repository(tmp_path)
+
+    with pytest.raises(ValueError):
+        create_packet(tmp_path, unsafe_slug, "HEAD")
+
+    assert not (tmp_path / "docs" / "plans").exists()
+
+
+def test_create_packet_rejects_existing_packet(tmp_path: Path) -> None:
+    """Existing packet directories remain untouched."""
+    initialize_repository(tmp_path)
+    packet_directory = create_packet(tmp_path, "sample-plan", "HEAD")
+    packet_json_before_retry = (packet_directory / "packet.json").read_text(
+        encoding="utf-8"
+    )
+
+    with pytest.raises(FileExistsError):
+        create_packet(tmp_path, "sample-plan", "HEAD")
+
+    assert (packet_directory / "packet.json").read_text(
+        encoding="utf-8"
+    ) == packet_json_before_retry