loopx 0.4.8__py3-none-any.whl

loopx/capabilities/change_quality/__init__.py

@@ -0,0 +1,19 @@
+from .policy import (
+    CHANGE_QUALITY_POLICY_SCHEMA_VERSION,
+    change_quality_goal_policy,
+    change_quality_goal_policy_summary,
+)
+from .receipt import (
+    build_change_quality_prepare_packet,
+    record_change_quality_receipt,
+    verify_change_quality_receipt,
+)
+
+__all__ = [
+    "CHANGE_QUALITY_POLICY_SCHEMA_VERSION",
+    "build_change_quality_prepare_packet",
+    "change_quality_goal_policy",
+    "change_quality_goal_policy_summary",
+    "record_change_quality_receipt",
+    "verify_change_quality_receipt",
+]

loopx/capabilities/change_quality/cli.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable
+from pathlib import Path
+
+from ...paths import resolve_runtime_root
+from ...registry import read_json
+from .receipt import (
+    build_change_quality_prepare_packet,
+    record_change_quality_receipt,
+    verify_change_quality_receipt,
+)
+
+
+PrintPayload = Callable[
+    [dict[str, object], str, Callable[[dict[str, object]], str]],
+    None,
+]
+FormatSelector = Callable[..., str]
+AddFormat = Callable[[argparse.ArgumentParser], None]
+
+
+def _add_scope_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--goal-id", required=True, help="Goal whose managed policy applies."
+    )
+    parser.add_argument(
+        "--repo-path",
+        type=Path,
+        default=Path("."),
+        help="Git worktree to qualify. Defaults to the current directory.",
+    )
+    parser.add_argument(
+        "--base-ref",
+        default="origin/main",
+        help="Git base ref for committed diff identity. Defaults to origin/main.",
+    )
+
+
+def register_change_quality_commands(
+    subparsers: argparse._SubParsersAction,
+    add_subcommand_format: AddFormat,
+) -> None:
+    parser = subparsers.add_parser(
+        "change-quality",
+        help="Prepare, record, and verify exact-scope change-quality receipts.",
+    )
+    commands = parser.add_subparsers(dest="change_quality_command", required=True)
+    prepare = commands.add_parser(
+        "prepare",
+        help="Build a provider-neutral review packet for the exact current diff.",
+    )
+    add_subcommand_format(prepare)
+    _add_scope_arguments(prepare)
+    record = commands.add_parser(
+        "record",
+        help="Validate an agent result against the exact current diff and store its receipt.",
+    )
+    add_subcommand_format(record)
+    _add_scope_arguments(record)
+    record.add_argument(
+        "--result-json",
+        type=Path,
+        required=True,
+        help="Agent result conforming to change_quality_agent_result_v2.",
+    )
+    record.add_argument(
+        "--execute",
+        action="store_true",
+        help="Write the exact-scope receipt under the LoopX runtime.",
+    )
+    verify = commands.add_parser(
+        "verify",
+        help="Verify the current exact diff against goal policy and stored receipt.",
+    )
+    add_subcommand_format(verify)
+    _add_scope_arguments(verify)
+
+
+def render_change_quality_markdown(payload: dict[str, object]) -> str:
+    receipt = payload.get("receipt") if isinstance(payload.get("receipt"), dict) else {}
+    policy_value = payload.get("policy") or receipt.get("policy")
+    scope_value = payload.get("scope") or receipt.get("scope")
+    policy = policy_value if isinstance(policy_value, dict) else {}
+    scope = scope_value if isinstance(scope_value, dict) else {}
+    pr_evidence_value = payload.get("pr_evidence")
+    pr_evidence = pr_evidence_value if isinstance(pr_evidence_value, dict) else {}
+    lines = [
+        "# Change Quality Qualification",
+        "",
+        f"- ok: `{str(payload.get('ok')).lower()}`",
+        f"- status: `{payload.get('status') or payload.get('decision')}`",
+        f"- goal_id: `{payload.get('goal_id')}`",
+        f"- enabled: `{str(policy.get('enabled')).lower()}`",
+        f"- safe_fix: `{str(policy.get('safe_fix')).lower()}`",
+        f"- strict_receipt: `{str(policy.get('strict_receipt')).lower()}`",
+        f"- scope_fingerprint: `{scope.get('scope_fingerprint') or payload.get('scope_fingerprint')}`",
+        f"- changed_files: `{scope.get('changed_file_count')}`",
+    ]
+    if payload.get("receipt_id"):
+        lines.append(f"- receipt_id: `{payload.get('receipt_id')}`")
+    if pr_evidence:
+        lines.extend(
+            [
+                f"- receipt_state: `{pr_evidence.get('state')}`",
+                (
+                    "- requalification_required: "
+                    f"`{str(pr_evidence.get('requalification_required')).lower()}`"
+                ),
+                f"- summary: {pr_evidence.get('summary')}",
+            ]
+        )
+        if pr_evidence.get("previous_receipt_id"):
+            lines.append(
+                f"- previous_receipt_id: `{pr_evidence.get('previous_receipt_id')}`"
+            )
+    if payload.get("required_action"):
+        lines.append(f"- required_action: {payload.get('required_action')}")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def handle_change_quality_command(
+    args: argparse.Namespace,
+    *,
+    registry_path: Path,
+    runtime_root_arg: str | None,
+    output_format: FormatSelector,
+    print_payload: PrintPayload,
+) -> int | None:
+    if args.command != "change-quality":
+        return None
+    registry = read_json(registry_path)
+    runtime_root = resolve_runtime_root(
+        registry,
+        runtime_root_arg,
+        registry_path=registry_path,
+    )
+    common = {
+        "registry_path": registry_path,
+        "goal_id": str(args.goal_id),
+        "repo_path": Path(args.repo_path),
+        "base_ref": str(args.base_ref),
+    }
+    try:
+        if args.change_quality_command == "prepare":
+            payload = build_change_quality_prepare_packet(**common)
+        elif args.change_quality_command == "record":
+            payload = record_change_quality_receipt(
+                **common,
+                runtime_root=runtime_root,
+                result_path=Path(args.result_json),
+                execute=bool(args.execute),
+            )
+        elif args.change_quality_command == "verify":
+            payload = verify_change_quality_receipt(
+                **common,
+                runtime_root=runtime_root,
+            )
+        else:
+            raise ValueError("change-quality requires prepare, record, or verify")
+    except (OSError, ValueError, TypeError) as exc:
+        payload = {
+            "ok": False,
+            "schema_version": "change_quality_error_v0",
+            "goal_id": str(args.goal_id),
+            "status": "error",
+            "error": str(exc),
+        }
+    print_payload(payload, output_format(args), render_change_quality_markdown)
+    return 0 if payload.get("ok") else 1

loopx/capabilities/change_quality/context.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from .oracles import build_change_quality_validation_plan
+from .scope import resolve_git_root
+
+
+CHANGE_QUALITY_REPOSITORY_CONTEXT_SCHEMA_VERSION = (
+    "change_quality_repository_context_v0"
+)
+
+_DIRECTORY_INSTRUCTION_FILES = ("AGENTS.md", "CLAUDE.md")
+_ROOT_INSTRUCTION_FILES = (
+    "CONTRIBUTING.md",
+    ".github/copilot-instructions.md",
+)
+_OWNERSHIP_FILES = (
+    "CODEOWNERS",
+    ".github/CODEOWNERS",
+    ".gitlab/CODEOWNERS",
+)
+_MANIFEST_SIGNALS: dict[str, tuple[tuple[str, ...], str]] = {
+    "pyproject.toml": (("python",), "python-project"),
+    "setup.py": (("python",), "python-setuptools"),
+    "Cargo.toml": (("rust",), "cargo"),
+    ".cargo/config.toml": (("rust",), "cargo"),
+    "package.json": (("javascript", "typescript"), "node"),
+    "tsconfig.json": (("typescript",), "typescript"),
+    "go.mod": (("go",), "go-modules"),
+    "pom.xml": (("java",), "maven"),
+    "build.gradle": (("java", "kotlin"), "gradle"),
+    "build.gradle.kts": (("java", "kotlin"), "gradle"),
+    "Gemfile": (("ruby",), "bundler"),
+    "Makefile": ((), "make"),
+    "Justfile": ((), "just"),
+    "WORKSPACE": ((), "bazel"),
+    "MODULE.bazel": ((), "bazel"),
+}
+_SUFFIX_LANGUAGE_HINTS = {
+    ".c": "c",
+    ".cc": "cpp",
+    ".cpp": "cpp",
+    ".cs": "csharp",
+    ".go": "go",
+    ".java": "java",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".kt": "kotlin",
+    ".kts": "kotlin",
+    ".m": "objective-c",
+    ".mm": "objective-cpp",
+    ".php": "php",
+    ".py": "python",
+    ".rb": "ruby",
+    ".rs": "rust",
+    ".sh": "shell",
+    ".swift": "swift",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+}
+
+
+def _normalized_changed_paths(changed_files: list[str]) -> list[PurePosixPath]:
+    paths: list[PurePosixPath] = []
+    for value in changed_files:
+        path = PurePosixPath(str(value).replace("\\", "/"))
+        if path.is_absolute() or ".." in path.parts:
+            continue
+        paths.append(path)
+    return paths
+
+
+def _relevant_directories(changed_paths: list[PurePosixPath]) -> list[PurePosixPath]:
+    directories = {PurePosixPath(".")}
+    for path in changed_paths:
+        parent = path.parent
+        while parent != PurePosixPath("."):
+            directories.add(parent)
+            parent = parent.parent
+    return sorted(directories, key=lambda item: (len(item.parts), item.as_posix()))
+
+
+def _existing_repo_ref(repo_root: Path, path: PurePosixPath) -> str | None:
+    candidate = repo_root / path.as_posix()
+    if candidate.is_file():
+        return path.as_posix()
+    return None
+
+
+def build_change_quality_repository_context(
+    *,
+    repo_path: Path,
+    changed_files: list[str],
+) -> dict[str, Any]:
+    """Project safe, path-only repository context for provider-neutral reviewers."""
+    repo_root = resolve_git_root(repo_path)
+    changed_paths = _normalized_changed_paths(changed_files)
+    directories = _relevant_directories(changed_paths)
+
+    instruction_refs: set[str] = set()
+    for directory in directories:
+        for filename in _DIRECTORY_INSTRUCTION_FILES:
+            path = directory / filename
+            if ref := _existing_repo_ref(repo_root, path):
+                instruction_refs.add(ref)
+    for value in _ROOT_INSTRUCTION_FILES:
+        if ref := _existing_repo_ref(repo_root, PurePosixPath(value)):
+            instruction_refs.add(ref)
+
+    ownership_refs = sorted(
+        ref
+        for value in _OWNERSHIP_FILES
+        if (ref := _existing_repo_ref(repo_root, PurePosixPath(value)))
+    )
+
+    manifest_refs: set[str] = set()
+    language_hints = {
+        language
+        for path in changed_paths
+        if (language := _SUFFIX_LANGUAGE_HINTS.get(path.suffix.lower()))
+    }
+    build_system_hints: set[str] = set()
+    for directory in directories:
+        for filename, (languages, build_system) in _MANIFEST_SIGNALS.items():
+            path = directory / filename
+            if ref := _existing_repo_ref(repo_root, path):
+                manifest_refs.add(ref)
+                language_hints.update(languages)
+                build_system_hints.add(build_system)
+
+    changed_surface_roots = sorted(
+        {
+            path.parts[0]
+            for path in changed_paths
+            if path.parts and path.parts[0] not in {"", "."}
+        }
+    )
+    sorted_instruction_refs = sorted(instruction_refs)
+    sorted_manifest_refs = sorted(manifest_refs)
+    return {
+        "schema_version": CHANGE_QUALITY_REPOSITORY_CONTEXT_SCHEMA_VERSION,
+        "instruction_refs": sorted_instruction_refs,
+        "ownership_refs": ownership_refs,
+        "build_manifest_refs": sorted_manifest_refs,
+        "language_hints": sorted(language_hints),
+        "build_system_hints": sorted(build_system_hints),
+        "changed_surface_roots": changed_surface_roots,
+        "validation_plan": build_change_quality_validation_plan(
+            repo_root=repo_root,
+            instruction_refs=sorted_instruction_refs,
+            manifest_refs=sorted_manifest_refs,
+        ),
+        "content_included": False,
+    }

loopx/capabilities/change_quality/oracles.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import tomllib
+from pathlib import Path, PurePosixPath
+from typing import Any, Callable
+
+
+CHANGE_QUALITY_VALIDATION_PLAN_SCHEMA_VERSION = "change_quality_validation_plan_v0"
+
+VALIDATION_CATEGORIES = ("format", "lint", "typecheck", "test")
+
+_CATEGORY_TOKENS = {
+    "format": {"fmt", "format", "formatting"},
+    "lint": {"lint", "linter", "clippy"},
+    "test": {"test", "tests", "pytest"},
+}
+_TASK_LIMIT = 64
+_SAFE_TASK_NAME = re.compile(r"^[A-Za-z0-9@][A-Za-z0-9@._:-]{0,127}$")
+_NON_ORACLE_PATH_PARTS = {
+    "fixtures",
+    "node_modules",
+    "testdata",
+    "third_party",
+    "vendor",
+}
+
+
+def _task_category(task_name: str) -> str | None:
+    tokens = [token for token in re.split(r"[^a-z0-9]+", task_name.lower()) if token]
+    token_set = set(tokens)
+    compact = "".join(tokens)
+    if token_set & _CATEGORY_TOKENS["format"]:
+        return "format"
+    if token_set & _CATEGORY_TOKENS["lint"]:
+        return "lint"
+    if (
+        token_set & {"typecheck", "typechecking"}
+        or compact in {"typecheck", "checktypes", "typechecking"}
+        or {
+            "type",
+            "check",
+        }.issubset(token_set)
+    ):
+        return "typecheck"
+    if token_set & _CATEGORY_TOKENS["test"]:
+        return "test"
+    return None
+
+
+def _source_ref(path: str, *parts: str) -> str:
+    fragment = ".".join(parts)
+    return f"{path}#{fragment}" if fragment else path
+
+
+def _oracle_id(*, source_ref: str, runner: str, task: str) -> str:
+    digest = hashlib.sha256(
+        f"{source_ref}\0{runner}\0{task}".encode("utf-8")
+    ).hexdigest()[:16]
+    return f"oracle_{digest}"
+
+
+def _candidate(
+    *,
+    source_ref: str,
+    runner: str,
+    task: str,
+    languages: tuple[str, ...],
+) -> dict[str, Any] | None:
+    if not _SAFE_TASK_NAME.fullmatch(task):
+        return None
+    category = _task_category(task)
+    if category is None:
+        return None
+    return {
+        "oracle_id": _oracle_id(
+            source_ref=source_ref,
+            runner=runner,
+            task=task,
+        ),
+        "category": category,
+        "runner": runner,
+        "task": task,
+        "source_ref": source_ref,
+        "language_hints": list(languages),
+        "origin": "repository_declared_task",
+        "execution_mode": "host_resolved",
+    }
+
+
+def _mapping(value: Any) -> dict[str, Any]:
+    return value if isinstance(value, dict) else {}
+
+
+def _python_candidates(path: str, payload: dict[str, Any]) -> list[dict[str, Any]]:
+    candidates: list[dict[str, Any]] = []
+    tool = _mapping(payload.get("tool"))
+
+    poe_tasks = _mapping(_mapping(tool.get("poe")).get("tasks"))
+    for task in sorted(poe_tasks):
+        candidate = _candidate(
+            source_ref=_source_ref(path, "tool", "poe", "tasks", task),
+            runner="poe_task",
+            task=task,
+            languages=("python",),
+        )
+        if candidate is not None:
+            candidates.append(candidate)
+
+    hatch_envs = _mapping(_mapping(tool.get("hatch")).get("envs"))
+    for environment in sorted(hatch_envs):
+        scripts = _mapping(_mapping(hatch_envs[environment]).get("scripts"))
+        for task in sorted(scripts):
+            candidate = _candidate(
+                source_ref=_source_ref(
+                    path,
+                    "tool",
+                    "hatch",
+                    "envs",
+                    environment,
+                    "scripts",
+                    task,
+                ),
+                runner="hatch_script",
+                task=task,
+                languages=("python",),
+            )
+            if candidate is not None:
+                candidates.append(candidate)
+
+    configured_tools = (
+        ("mypy", "typecheck"),
+        ("pyright", "typecheck"),
+        ("pytest", "test"),
+    )
+    for tool_name, category in configured_tools:
+        config_key = "pytest.ini_options" if tool_name == "pytest" else tool_name
+        current: Any = tool
+        for part in config_key.split("."):
+            current = _mapping(current).get(part)
+        if current is None:
+            continue
+        source_ref = _source_ref(path, "tool", *config_key.split("."))
+        candidates.append(
+            {
+                "oracle_id": _oracle_id(
+                    source_ref=source_ref,
+                    runner=f"{tool_name}_config",
+                    task=tool_name,
+                ),
+                "category": category,
+                "runner": f"{tool_name}_config",
+                "task": tool_name,
+                "source_ref": source_ref,
+                "language_hints": ["python"],
+                "origin": "repository_tool_config",
+                "execution_mode": "host_resolved",
+            }
+        )
+    return candidates
+
+
+def _node_candidates(path: str, payload: dict[str, Any]) -> list[dict[str, Any]]:
+    candidates: list[dict[str, Any]] = []
+    scripts = _mapping(payload.get("scripts"))
+    for task in sorted(scripts):
+        candidate = _candidate(
+            source_ref=_source_ref(path, "scripts", task),
+            runner="package_script",
+            task=task,
+            languages=("javascript", "typescript"),
+        )
+        if candidate is not None:
+            candidates.append(candidate)
+    return candidates
+
+
+def _cargo_candidates(path: str, payload: dict[str, Any]) -> list[dict[str, Any]]:
+    candidates: list[dict[str, Any]] = []
+    aliases = _mapping(payload.get("alias"))
+    for task in sorted(aliases):
+        candidate = _candidate(
+            source_ref=_source_ref(path, "alias", task),
+            runner="cargo_alias",
+            task=task,
+            languages=("rust",),
+        )
+        if candidate is not None:
+            candidates.append(candidate)
+    return candidates
+
+
+def _read_manifest(path: Path) -> tuple[dict[str, Any] | None, str | None]:
+    try:
+        content = path.read_text(encoding="utf-8")
+        if path.name == "package.json":
+            parsed = json.loads(content)
+        else:
+            parsed = tomllib.loads(content)
+    except (OSError, UnicodeError, json.JSONDecodeError, tomllib.TOMLDecodeError):
+        return None, "manifest_unreadable"
+    if not isinstance(parsed, dict):
+        return None, "manifest_root_not_object"
+    return parsed, None
+
+
+def _is_non_oracle_manifest(relative: PurePosixPath) -> bool:
+    return bool({part.lower() for part in relative.parts} & _NON_ORACLE_PATH_PARTS)
+
+
+def build_change_quality_validation_plan(
+    *,
+    repo_root: Path,
+    instruction_refs: list[str],
+    manifest_refs: list[str],
+) -> dict[str, Any]:
+    """Discover repository-declared quality tasks without copying task bodies."""
+    candidates: list[dict[str, Any]] = []
+    warnings: list[dict[str, str]] = []
+    ignored_manifest_refs: list[str] = []
+    for ref in sorted(set(manifest_refs)):
+        relative = PurePosixPath(ref)
+        if relative.is_absolute() or ".." in relative.parts:
+            continue
+        if _is_non_oracle_manifest(relative):
+            ignored_manifest_refs.append(ref)
+            continue
+        parser: Callable[[str, dict[str, Any]], list[dict[str, Any]]]
+        if relative.name == "pyproject.toml":
+            parser = _python_candidates
+        elif relative.name == "package.json":
+            parser = _node_candidates
+        elif relative.as_posix().endswith(".cargo/config.toml"):
+            parser = _cargo_candidates
+        else:
+            continue
+        payload, warning = _read_manifest(repo_root / relative.as_posix())
+        if warning is not None:
+            warnings.append({"source_ref": ref, "code": warning})
+            continue
+        assert payload is not None
+        candidates.extend(parser(ref, payload))
+
+    deduplicated = {
+        candidate["oracle_id"]: candidate for candidate in candidates[:_TASK_LIMIT]
+    }
+    ordered_candidates = sorted(
+        deduplicated.values(),
+        key=lambda item: (
+            VALIDATION_CATEGORIES.index(item["category"]),
+            item["source_ref"],
+        ),
+    )
+    covered = {item["category"] for item in ordered_candidates}
+    return {
+        "schema_version": CHANGE_QUALITY_VALIDATION_PLAN_SCHEMA_VERSION,
+        "selection_policy": "repository_declared_only",
+        "required_reads": sorted(set(instruction_refs)),
+        "candidates": ordered_candidates,
+        "unresolved_categories": [
+            category for category in VALIDATION_CATEGORIES if category not in covered
+        ],
+        "ignored_manifest_refs": ignored_manifest_refs,
+        "discovery_warnings": warnings,
+        "auto_execute": False,
+        "task_bodies_included": False,
+    }

loopx/capabilities/change_quality/policy.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+CHANGE_QUALITY_POLICY_SCHEMA_VERSION = "change_quality_qualification_policy_v0"
+
+
+def change_quality_goal_policy(goal: dict[str, Any]) -> dict[str, Any]:
+    control_plane = (
+        goal.get("control_plane")
+        if isinstance(goal.get("control_plane"), dict)
+        else {}
+    )
+    raw = (
+        control_plane.get("change_quality_qualification")
+        if isinstance(control_plane.get("change_quality_qualification"), dict)
+        else {}
+    )
+    return {
+        "schema_version": CHANGE_QUALITY_POLICY_SCHEMA_VERSION,
+        "enabled": raw.get("enabled") is True,
+        "safe_fix": raw.get("safe_fix") is True,
+        "strict_receipt": raw.get("strict_receipt") is True,
+    }
+
+
+def change_quality_goal_policy_summary(goal: dict[str, Any]) -> dict[str, Any]:
+    policy = change_quality_goal_policy(goal)
+    return {
+        "enabled": policy["enabled"],
+        "safe_fix": policy["safe_fix"],
+        "strict_receipt": policy["strict_receipt"],
+    }