atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/a1_at_functions/patch_scorer.py

@@ -0,0 +1,267 @@
+"""Tier a1 — pure unified-diff risk scorer.
+
+Codex's 'Copilot's Copilot' primitive #3:
+
+  > score_patch({diff}) — returns architecture risk, test risk,
+  > public API risk, release risk, 'needs human review?' boolean,
+  > suggested validation commands. Turns Forge into a PR reviewer
+  > before the PR exists.
+
+Pure: parses a unified-diff string, classifies per-file changes,
+returns a structured risk report. Heuristic — false positives are
+expected; the value is the structured prompt for the agent to
+think about before applying the diff.
+"""
+from __future__ import annotations
+
+import re
+from typing import TypedDict
+
+SCHEMA_VERSION_PATCH_SCORE_V1 = "atomadic-forge.patch_score/v1"
+
+
+_FILE_HEADER_RE = re.compile(r"^\+\+\+ b/(.+?)(?:\t|\s|$)", re.MULTILINE)
+_TIER_NAMES = (
+    "a0_qk_constants", "a1_at_functions", "a2_mo_composites",
+    "a3_og_features", "a4_sy_orchestration",
+)
+_PUBLIC_API_PATHS = ("__init__.py",)
+_RELEASE_FILES = (
+    "pyproject.toml", "setup.py", "setup.cfg", "package.json",
+    "Cargo.toml", "version.py", "VERSION", "_version.py",
+    "CHANGELOG.md", "LICENSE",
+)
+_FORBIDDEN_BY_TIER: dict[str, tuple[str, ...]] = {
+    "a0_qk_constants": (
+        "a1_at_functions", "a2_mo_composites",
+        "a3_og_features", "a4_sy_orchestration",
+    ),
+    "a1_at_functions": (
+        "a2_mo_composites", "a3_og_features", "a4_sy_orchestration",
+    ),
+    "a2_mo_composites": ("a3_og_features", "a4_sy_orchestration"),
+    "a3_og_features":   ("a4_sy_orchestration",),
+    "a4_sy_orchestration": (),
+}
+
+
+class PatchFileScore(TypedDict, total=False):
+    path: str
+    detected_tier: str | None
+    added_lines: int
+    removed_lines: int
+    architectural_risk: bool
+    public_api_risk: bool
+    release_risk: bool
+    notes: list[str]
+
+
+class PatchScore(TypedDict, total=False):
+    schema_version: str
+    file_count: int
+    total_added: int
+    total_removed: int
+    architectural_risk: bool
+    test_risk: bool
+    public_api_risk: bool
+    release_risk: bool
+    needs_human_review: bool
+    files: list[PatchFileScore]
+    suggested_validation_commands: list[str]
+    notes: list[str]
+
+
+def _split_diff_per_file(diff: str) -> list[tuple[str, str]]:
+    """Return [(path, file_diff_text), ...] for a unified diff."""
+    chunks: list[tuple[str, str]] = []
+    current_path: str | None = None
+    current: list[str] = []
+    for line in diff.splitlines():
+        if line.startswith("+++ b/"):
+            # Flush prior chunk
+            if current_path is not None and current:
+                chunks.append((current_path, "\n".join(current)))
+            current_path = line[len("+++ b/"):].split("\t", 1)[0].strip()
+            current = []
+        else:
+            current.append(line)
+    if current_path is not None and current:
+        chunks.append((current_path, "\n".join(current)))
+    return chunks
+
+
+def _detect_tier(path: str) -> str | None:
+    for part in path.split("/"):
+        if part in _TIER_NAMES:
+            return part
+    return None
+
+
+def _check_added_imports_against_tier(
+    path: str, tier: str | None, diff_text: str,
+) -> list[str]:
+    """Look at '+' lines for upward imports against the file's tier."""
+    if not tier:
+        return []
+    forbidden = _FORBIDDEN_BY_TIER.get(tier, ())
+    if not forbidden:
+        return []
+    issues: list[str] = []
+    for raw in diff_text.splitlines():
+        if not raw.startswith("+") or raw.startswith("+++"):
+            continue
+        body = raw[1:].lstrip()
+        if not body.startswith(("import ", "from ")):
+            continue
+        for f in forbidden:
+            if f in body:
+                issues.append(
+                    f"new import in {path} references forbidden tier "
+                    f"{f!r}: {body[:120]}"
+                )
+                break
+    return issues
+
+
+def _file_score(path: str, diff_text: str) -> PatchFileScore:
+    added = sum(1 for line in diff_text.splitlines()
+                 if line.startswith("+") and not line.startswith("+++"))
+    removed = sum(1 for line in diff_text.splitlines()
+                   if line.startswith("-") and not line.startswith("---"))
+    tier = _detect_tier(path)
+    notes: list[str] = []
+    arch_risk = False
+    api_risk = False
+    rel_risk = False
+
+    upward = _check_added_imports_against_tier(path, tier, diff_text)
+    if upward:
+        arch_risk = True
+        notes.extend(upward)
+
+    if path.endswith(_PUBLIC_API_PATHS):
+        api_risk = True
+        notes.append(
+            f"{path} is a public-export surface; an unintended "
+            "deletion can break downstream callers"
+        )
+
+    base = path.split("/")[-1]
+    if base in _RELEASE_FILES or path.endswith(_RELEASE_FILES):
+        rel_risk = True
+        notes.append(
+            f"{path} is a release-control file; review version bump "
+            "+ changelog impact before merging"
+        )
+
+    return PatchFileScore(
+        path=path,
+        detected_tier=tier,
+        added_lines=added,
+        removed_lines=removed,
+        architectural_risk=arch_risk,
+        public_api_risk=api_risk,
+        release_risk=rel_risk,
+        notes=notes,
+    )
+
+
+def score_patch(diff: str, *, project_root: object | None = None) -> PatchScore:
+    """Score a unified-diff string. Returns the patch_score/v1 shape.
+
+    Empty or unparseable diffs return a low-risk report with a note
+    instead of raising — the agent should never see a traceback when
+    asking 'is this safe?'.
+
+    Codex-6: when ``project_root`` is provided AND that project has a
+    [tool.forge.agent] policy with protected_files, any diff touching
+    a protected file is flagged as ``needs_human_review``.
+    """
+    if not diff or not diff.strip():
+        return PatchScore(
+            schema_version=SCHEMA_VERSION_PATCH_SCORE_V1,
+            file_count=0, total_added=0, total_removed=0,
+            architectural_risk=False, test_risk=False,
+            public_api_risk=False, release_risk=False,
+            needs_human_review=False, files=[],
+            suggested_validation_commands=[],
+            notes=["empty diff — nothing to score"],
+        )
+
+    chunks = _split_diff_per_file(diff)
+    files = [_file_score(p, txt) for p, txt in chunks]
+
+    arch_risk = any(f["architectural_risk"] for f in files)
+    api_risk = any(f["public_api_risk"] for f in files)
+    rel_risk = any(f["release_risk"] for f in files)
+
+    src_paths = [f for f in files
+                 if not f["path"].startswith(("tests/", "test/"))
+                 and not f["path"].endswith(("_test.py",))]
+    test_paths = [f for f in files
+                   if f["path"].startswith(("tests/", "test/"))
+                   or f["path"].endswith(("_test.py",))]
+    test_risk = bool(src_paths) and not test_paths
+
+    notes: list[str] = []
+    if test_risk:
+        notes.append(
+            "code changed without tests touched — add coverage or "
+            "explicitly justify why existing tests are sufficient"
+        )
+    if not chunks:
+        notes.append(
+            "diff parsed but no '+++ b/<path>' headers found — "
+            "unified-diff format expected"
+        )
+
+    # Codex-6: respect [tool.forge.agent] protected_files when a
+    # project_root is provided. Lazy import to avoid a circular path.
+    protected_hits: list[str] = []
+    if project_root is not None:
+        try:
+            from pathlib import Path as _Path
+
+            from .policy_loader import file_is_protected, load_policy
+            policy = load_policy(_Path(str(project_root)))
+            for f in files:
+                if file_is_protected(f["path"], policy):
+                    protected_hits.append(f["path"])
+                    f.setdefault("notes", []).append(
+                        "policy: file listed in protected_files — needs review"
+                    )
+        except Exception:  # noqa: BLE001
+            pass
+
+    needs_review = arch_risk or api_risk or rel_risk or bool(protected_hits) or (
+        sum(f["added_lines"] for f in files) > 200
+    )
+    if protected_hits:
+        notes.append(
+            f"diff touches {len(protected_hits)} file(s) listed in "
+            "[tool.forge.agent] protected_files — needs_human_review=True"
+        )
+    if needs_review and "review" not in " ".join(notes):
+        notes.append(
+            "needs_human_review=True because of architectural / "
+            "public-API / release / large-patch risk — do NOT auto-merge"
+        )
+
+    return PatchScore(
+        schema_version=SCHEMA_VERSION_PATCH_SCORE_V1,
+        file_count=len(files),
+        total_added=sum(f["added_lines"] for f in files),
+        total_removed=sum(f["removed_lines"] for f in files),
+        architectural_risk=arch_risk,
+        test_risk=test_risk,
+        public_api_risk=api_risk,
+        release_risk=rel_risk,
+        needs_human_review=needs_review,
+        files=files,
+        suggested_validation_commands=[
+            "forge wire src --fail-on-violations",
+            "python -m pytest",
+            "forge certify . --fail-under 75",
+        ],
+        notes=notes,
+    )

atomadic_forge/a1_at_functions/plan_adapter.py

@@ -0,0 +1,75 @@
+"""Tier a1 — adapt_plan: capability-aware card filtering (Codex #8).
+
+Codex's prescription:
+
+  > Different agents have different strengths: some can edit, some
+  > can only review, some can run commands, some cannot access
+  > network. adapt_plan({agent_capabilities}) tailors action cards:
+  > 'agent can apply', 'agent should ask human', 'agent should
+  > delegate', 'agent should only report'.
+
+Pure: takes an existing AgentPlan + capability set, returns a new
+plan with each card's recommended_handling field populated.
+"""
+from __future__ import annotations
+
+from copy import deepcopy
+
+SCHEMA_VERSION_ADAPTED_PLAN_V1 = "atomadic-forge.agent_plan_adapted/v1"
+
+
+# Known agent capability slugs.
+_KNOWN_CAPABILITIES: frozenset[str] = frozenset({
+    "edit_files",       # can write to disk
+    "run_commands",     # can shell out
+    "network",          # can reach external HTTP
+    "review",           # can analyse but not modify
+    "delegate",         # can spawn other agents
+})
+
+
+def _handling_for(card: dict, *, capabilities: set[str]) -> str:
+    """Map a card to one of:
+      apply           — agent has every capability the card needs
+      delegate        — agent should spawn / invoke another tool
+      ask_human       — card needs out-of-band judgement
+      report_only     — agent should surface, not act
+    """
+    applyable = bool(card.get("applyable"))
+    if not applyable:
+        return "ask_human"
+    kind = card.get("kind", "")
+    risk = card.get("risk", "high")
+    if kind == "synthesis" and "delegate" in capabilities:
+        return "delegate"
+    if kind in ("operational", "architectural"):
+        if "edit_files" in capabilities and "run_commands" in capabilities:
+            return "apply"
+        if "edit_files" in capabilities:
+            return "apply"
+        return "report_only"
+    if risk == "high":
+        return "ask_human"
+    return "report_only" if "edit_files" not in capabilities else "apply"
+
+
+def adapt_plan(plan: dict, *, agent_capabilities: list[str]) -> dict:
+    """Return a new plan with per-card 'recommended_handling' set.
+
+    Pure: input is not mutated.
+    """
+    caps = {c for c in agent_capabilities or [] if c in _KNOWN_CAPABILITIES}
+    out = deepcopy(plan)
+    for card in out.get("top_actions", []):
+        card["recommended_handling"] = _handling_for(card, capabilities=caps)
+    out["schema_version"] = SCHEMA_VERSION_ADAPTED_PLAN_V1
+    out["agent_capabilities"] = sorted(caps)
+    out["unknown_capabilities"] = sorted(
+        c for c in (agent_capabilities or []) if c not in _KNOWN_CAPABILITIES
+    )
+    counts: dict[str, int] = {}
+    for card in out.get("top_actions", []):
+        h = card["recommended_handling"]
+        counts[h] = counts.get(h, 0) + 1
+    out["handling_counts"] = counts
+    return out

atomadic_forge/a1_at_functions/policy_loader.py

@@ -0,0 +1,107 @@
+"""Tier a1 — pure pyproject.toml [tool.forge.agent] policy reader.
+
+Codex #10. Reads the policy block (if present) and returns an
+AgentPolicy dict with defaults filled in for any missing fields.
+
+Pure: one bounded read of pyproject.toml; no other I/O. Returns the
+default policy unchanged when no pyproject / no [tool.forge.agent]
+section exists — Forge never errors on policy absence.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+from ..a0_qk_constants.policy_schema import (
+    DEFAULT_MAX_FILES_PER_PATCH,
+    DEFAULT_PROTECTED_FILES,
+    DEFAULT_RELEASE_GATE,
+    DEFAULT_REQUIRE_HUMAN_REVIEW_FOR,
+    SCHEMA_VERSION_POLICY_V1,
+    AgentPolicy,
+)
+
+# Python 3.11+ has stdlib tomllib; older versions need a fallback.
+if sys.version_info >= (3, 11):
+    import tomllib as _toml  # type: ignore[import-not-found]
+else:  # pragma: no cover — Forge requires 3.10+, so this is rare path
+    try:
+        import tomli as _toml  # type: ignore[import-not-found]
+    except ImportError:
+        _toml = None  # type: ignore[assignment]
+
+
+def default_policy() -> AgentPolicy:
+    """The lenient baseline policy applied when no [tool.forge.agent]
+    section is declared. Every field is mutable — caller can layer
+    user overrides on top."""
+    return AgentPolicy(
+        schema_version=SCHEMA_VERSION_POLICY_V1,
+        protected_files=list(DEFAULT_PROTECTED_FILES),
+        release_gate=list(DEFAULT_RELEASE_GATE),
+        max_files_per_patch=DEFAULT_MAX_FILES_PER_PATCH,
+        require_human_review_for=list(DEFAULT_REQUIRE_HUMAN_REVIEW_FOR),
+        extra={},
+    )
+
+
+def load_policy(project_root: Path) -> AgentPolicy:
+    """Read [tool.forge.agent] from project_root/pyproject.toml.
+
+    Returns the default policy with any user-declared values merged
+    on top. Missing pyproject or missing section → defaults.
+    Malformed TOML → defaults + a note in extra['_load_error'].
+    """
+    project_root = Path(project_root).resolve()
+    policy = default_policy()
+
+    pp = project_root / "pyproject.toml"
+    if not pp.exists() or _toml is None:
+        return policy
+    try:
+        data = _toml.loads(pp.read_text(encoding="utf-8"))
+    except Exception as exc:  # noqa: BLE001
+        policy["extra"] = {"_load_error": f"{type(exc).__name__}: {exc}"}
+        return policy
+
+    section = (data.get("tool") or {}).get("forge", {}).get("agent")
+    if not isinstance(section, dict):
+        return policy
+
+    if isinstance(section.get("protected_files"), list):
+        policy["protected_files"] = [str(s) for s in section["protected_files"]]
+    if isinstance(section.get("release_gate"), list):
+        policy["release_gate"] = [str(s) for s in section["release_gate"]]
+    if isinstance(section.get("max_files_per_patch"), int):
+        policy["max_files_per_patch"] = int(section["max_files_per_patch"])
+    if isinstance(section.get("require_human_review_for"), list):
+        policy["require_human_review_for"] = [
+            str(s) for s in section["require_human_review_for"]
+        ]
+    # Forward-compat: any unrecognised keys preserved in extra.
+    known = {
+        "protected_files", "release_gate", "max_files_per_patch",
+        "require_human_review_for",
+    }
+    extra: dict[str, Any] = {}
+    for k, v in section.items():
+        if k not in known:
+            extra[k] = v
+    if extra:
+        policy["extra"] = extra
+    return policy
+
+
+def file_is_protected(path: str, policy: AgentPolicy) -> bool:
+    """True when ``path`` matches any protected_files entry.
+
+    Matching is exact-or-suffix: 'pyproject.toml' matches
+    'pyproject.toml' and 'src/pkg/pyproject.toml' but NOT
+    'src/pyproject_helper.py'.
+    """
+    protected = policy.get("protected_files") or []
+    for p in protected:
+        if path == p or path.endswith("/" + p) or Path(path).name == p:
+            return True
+    return False

atomadic_forge/a1_at_functions/preflight_change.py

@@ -0,0 +1,227 @@
+"""Tier a1 — pure preflight check for proposed changes.
+
+Codex's 'Copilot's Copilot' primitive #2:
+
+  > preflight_change({intent, proposed_files}) — returns where the
+  > code should live, forbidden imports, tests likely affected,
+  > files the agent should read first, whether the write scope is
+  > too broad. Most agent mistakes happen before code is written.
+
+Pure: no I/O beyond optional file-read for write_scope-too-broad
+size hints. The classifier reads the proposed file paths only.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TypedDict
+
+SCHEMA_VERSION_PREFLIGHT_V1 = "atomadic-forge.preflight/v1"
+
+
+_TIER_NAMES = (
+    "a0_qk_constants",
+    "a1_at_functions",
+    "a2_mo_composites",
+    "a3_og_features",
+    "a4_sy_orchestration",
+)
+
+# Per tier: the tier names this tier may NOT import (forbidden).
+_FORBIDDEN_BY_TIER: dict[str, tuple[str, ...]] = {
+    "a0_qk_constants": (
+        "a0_qk_constants",         # may not import siblings either
+        "a1_at_functions", "a2_mo_composites",
+        "a3_og_features", "a4_sy_orchestration",
+    ),
+    "a1_at_functions": (
+        "a2_mo_composites", "a3_og_features", "a4_sy_orchestration",
+    ),
+    "a2_mo_composites": ("a3_og_features", "a4_sy_orchestration"),
+    "a3_og_features":   ("a4_sy_orchestration",),
+    "a4_sy_orchestration": (),
+}
+
+_DEFAULT_SCOPE_TOO_BROAD = 8
+
+
+class PreflightFile(TypedDict, total=False):
+    path: str
+    detected_tier: str | None
+    forbidden_imports: list[str]
+    likely_tests: list[str]
+    siblings_to_read: list[str]
+    notes: list[str]
+
+
+class PreflightReport(TypedDict, total=False):
+    schema_version: str
+    intent: str
+    project_root: str
+    proposed_files: list[PreflightFile]
+    write_scope_too_broad: bool
+    write_scope_size: int
+    write_scope_threshold: int
+    overall_notes: list[str]
+    suggested_validation_commands: list[str]
+
+
+def _detect_tier(path: str) -> str | None:
+    parts = Path(path).parts
+    for p in parts:
+        if p in _TIER_NAMES:
+            return p
+    return None
+
+
+def _likely_tests_for(path: str) -> list[str]:
+    """Mirror-style test path heuristic.
+
+    src/pkg/a1_at_functions/foo.py -> tests/test_foo.py,
+                                       tests/a1_at_functions/test_foo.py
+    """
+    p = Path(path)
+    stem = p.stem
+    if stem.startswith("test_") or stem.endswith("_test"):
+        return [path]  # the file IS a test
+    candidates: list[str] = []
+    candidates.append(f"tests/test_{stem}.py")
+    candidates.append(f"tests/{stem}_test.py")
+    parent_tier = _detect_tier(path)
+    if parent_tier:
+        candidates.append(f"tests/{parent_tier}/test_{stem}.py")
+    return candidates
+
+
+def _siblings_to_read(path: str, *, project_root: Path) -> list[str]:
+    """When the agent edits a file, sibling files in the same tier
+    directory are the most likely places to share patterns or to
+    accidentally diverge — read them first."""
+    p = Path(path)
+    if not p.parent.parts:
+        return []
+    sib_dir = project_root / p.parent
+    if not sib_dir.is_dir():
+        return []
+    out: list[str] = []
+    for sib in sorted(sib_dir.glob("*.py")):
+        if sib.name == p.name:
+            continue
+        if sib.name.startswith("_"):
+            continue
+        out.append(str(sib.relative_to(project_root).as_posix()))
+        if len(out) >= 5:
+            break
+    return out
+
+
+def _file_preflight(
+    path: str,
+    *,
+    project_root: Path,
+) -> PreflightFile:
+    notes: list[str] = []
+    tier = _detect_tier(path)
+    forbidden = list(_FORBIDDEN_BY_TIER.get(tier, ())) if tier else []
+    likely_tests = _likely_tests_for(path)
+    siblings = _siblings_to_read(path, project_root=project_root)
+    if tier is None:
+        notes.append(
+            "no tier directory in this path — file likely belongs in "
+            "a tier under src/<package>/aN_*/"
+        )
+    if Path(path).name == "__init__.py":
+        notes.append(
+            "__init__.py edits affect tier re-exports; run "
+            "tier_init_rebuild after a structural change"
+        )
+    return PreflightFile(
+        path=path,
+        detected_tier=tier,
+        forbidden_imports=forbidden,
+        likely_tests=likely_tests,
+        siblings_to_read=siblings,
+        notes=notes,
+    )
+
+
+def preflight_change(
+    *,
+    intent: str,
+    proposed_files: list[str],
+    project_root: Path,
+    scope_threshold: int = _DEFAULT_SCOPE_TOO_BROAD,
+) -> PreflightReport:
+    """Heuristic preflight for a proposed code change.
+
+    Pure: takes paths + intent, walks the local filesystem only to
+    check sibling presence. Does NOT read the proposed_files
+    themselves — they may not exist yet.
+
+    Codex-6: when [tool.forge.agent] is declared in the project's
+    pyproject.toml, ``max_files_per_patch`` overrides the default
+    threshold and ``protected_files`` adds per-file warnings.
+    """
+    from .policy_loader import file_is_protected, load_policy
+    project_root = Path(project_root).resolve()
+    policy = load_policy(project_root)
+    if scope_threshold == _DEFAULT_SCOPE_TOO_BROAD and \
+            isinstance(policy.get("max_files_per_patch"), int):
+        scope_threshold = int(policy["max_files_per_patch"])
+    files: list[PreflightFile] = [
+        _file_preflight(p, project_root=project_root)
+        for p in proposed_files
+    ]
+    for f in files:
+        if file_is_protected(f["path"], policy):
+            notes = list(f.get("notes") or [])
+            notes.append(
+                "policy: this file is in [tool.forge.agent] "
+                "protected_files — agent should request human review"
+            )
+            f["notes"] = notes
+    overall: list[str] = []
+    protected_in_scope = [f["path"] for f in files
+                           if any("protected_files" in n
+                                  for n in f.get("notes", []))]
+    if protected_in_scope:
+        overall.append(
+            f"{len(protected_in_scope)} protected file(s) in scope "
+            f"(per [tool.forge.agent]): {protected_in_scope[:5]} — "
+            "request human review before applying."
+        )
+    too_broad = len(proposed_files) > scope_threshold
+    if too_broad:
+        overall.append(
+            f"write_scope has {len(proposed_files)} files (> "
+            f"{scope_threshold} threshold). Consider splitting the "
+            "change or asking for human review."
+        )
+    detected_tiers = {f.get("detected_tier") for f in files}
+    detected_tiers.discard(None)
+    if len(detected_tiers) > 1:
+        overall.append(
+            f"change spans {len(detected_tiers)} tiers "
+            f"({sorted(detected_tiers)}); cross-tier edits should be "
+            "split into per-tier patches when possible."
+        )
+    if any(f.get("path", "").startswith("tests/") for f in files) and \
+            not any(not f.get("path", "").startswith("tests/") for f in files):
+        overall.append(
+            "test-only change — verify it pins existing behaviour and "
+            "is not silently masking a regression."
+        )
+    return PreflightReport(
+        schema_version=SCHEMA_VERSION_PREFLIGHT_V1,
+        intent=intent,
+        project_root=str(project_root),
+        proposed_files=files,
+        write_scope_too_broad=too_broad,
+        write_scope_size=len(proposed_files),
+        write_scope_threshold=scope_threshold,
+        overall_notes=overall,
+        suggested_validation_commands=[
+            "forge wire src --fail-on-violations",
+            "python -m pytest",
+            "forge certify . --fail-under 75",
+        ],
+    )