atomadic-forge 0.3.2__py3-none-any.whl

atomadic_forge/a1_at_functions/tool_composer.py

@@ -0,0 +1,130 @@
+"""Tier a1 — compose_tools: tool-use planner (Codex #9).
+
+Codex's prescription:
+
+  > Forge has synergy/emergent. Make that agent-native: compose_tools(
+  > {goal}). Returns a sequence like:
+  >   1. recon
+  >   2. summary
+  >   3. preflight_change
+  >   4. score_patch
+  >   5. select_tests
+  >   6. certify
+  > This makes Forge not just a toolbox, but a planner for tool use.
+
+Pure: maps a goal-keyword to a sequence of MCP tool names with
+short rationale per step. Heuristic; the agent picks one or runs
+the whole sequence.
+"""
+from __future__ import annotations
+
+from typing import TypedDict
+
+SCHEMA_VERSION_COMPOSE_V1 = "atomadic-forge.tool_compose/v1"
+
+
+class ComposedToolStep(TypedDict, total=False):
+    step: int
+    tool: str
+    why: str
+    inputs_hint: dict[str, str]
+
+
+class ComposedToolPlan(TypedDict, total=False):
+    schema_version: str
+    goal: str
+    matched_recipe: str
+    steps: list[ComposedToolStep]
+    notes: list[str]
+
+
+# Recipe library — keyword → ordered tool sequence.
+_RECIPES: dict[str, dict] = {
+    "orient": {
+        "match": ("orient", "what is this", "explain", "first time",
+                   "context", "onboard", "new repo"),
+        "steps": [
+            {"tool": "context_pack", "why": "first-call orientation"},
+            {"tool": "recon", "why": "tier inventory + symbol counts"},
+            {"tool": "audit_list", "why": "what has Forge written before?"},
+        ],
+    },
+    "release_check": {
+        "match": ("release", "ship", "publish", "merge", "ready to ship"),
+        "steps": [
+            {"tool": "wire", "why": "upward-import gate"},
+            {"tool": "certify", "why": "score against the 4 axes"},
+            {"tool": "score_patch", "why": "review the unified diff"},
+            {"tool": "select_tests", "why": "minimum + full test sets"},
+        ],
+    },
+    "fix_violation": {
+        "match": ("fix wire", "fix violation", "fix import", "f0042",
+                   "f0041", "f0046", "upward import"),
+        "steps": [
+            {"tool": "wire", "why": "scan with --suggest-repairs"},
+            {"tool": "auto_plan",
+              "why": "generate ranked action cards"},
+            {"tool": "auto_apply",
+              "why": "execute applyable cards (rollback-safe)"},
+            {"tool": "certify", "why": "verify score recovered"},
+        ],
+    },
+    "before_edit": {
+        "match": ("before edit", "before write", "preflight", "guardrail",
+                   "i'm about to"),
+        "steps": [
+            {"tool": "context_pack", "why": "ground the agent first"},
+            {"tool": "preflight_change",
+              "why": "tier check + forbidden imports + likely tests"},
+            {"tool": "select_tests",
+              "why": "what to run after the edit"},
+        ],
+    },
+    "verify_patch": {
+        "match": ("verify patch", "score diff", "review patch", "is this safe",
+                   "review my change"),
+        "steps": [
+            {"tool": "score_patch",
+              "why": "architecture / api / release / test risk"},
+            {"tool": "wire", "why": "confirm no upward imports introduced"},
+            {"tool": "select_tests",
+              "why": "minimum tests for the changed files"},
+        ],
+    },
+}
+
+
+def compose_tools(*, goal: str) -> ComposedToolPlan:
+    """Match ``goal`` against the recipe library and return an ordered
+    tool-use plan. Falls back to the 'orient' recipe when no keyword
+    matches."""
+    goal_l = (goal or "").lower()
+    matched: str = ""
+    chosen: list[dict] | None = None
+    for name, recipe in _RECIPES.items():
+        if any(kw in goal_l for kw in recipe["match"]):
+            matched = name
+            chosen = recipe["steps"]
+            break
+    if chosen is None:
+        matched = "orient"
+        chosen = _RECIPES["orient"]["steps"]
+    steps: list[ComposedToolStep] = []
+    for i, s in enumerate(chosen, 1):
+        steps.append(ComposedToolStep(
+            step=i,
+            tool=s["tool"],
+            why=s["why"],
+            inputs_hint={},
+        ))
+    notes: list[str] = []
+    if not goal:
+        notes.append("no goal supplied — defaulted to 'orient' recipe.")
+    return ComposedToolPlan(
+        schema_version=SCHEMA_VERSION_COMPOSE_V1,
+        goal=goal,
+        matched_recipe=matched,
+        steps=steps,
+        notes=notes,
+    )

atomadic_forge/a1_at_functions/transcript_log.py

@@ -0,0 +1,70 @@
+"""Tier a1 — append-only LLM transcript logger.
+
+For full transparency, every prompt sent to the LLM and every response
+received is appended to ``.atomadic-forge/transcripts/<run-id>.jsonl``.
+
+Operators can audit exactly what Forge asked the LLM and exactly what the
+LLM emitted.  No black-box magic — every byte is on disk.
+
+Usage:
+    log = TranscriptLog(project_root, run_id="evolve-20260427T0815")
+    log.append("system", system_prompt)
+    log.append("user", user_prompt, role="prompt")
+    log.append("assistant", llm_response, role="response")
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+from pathlib import Path
+from typing import Any
+
+
+class TranscriptLog:
+    """Append-only JSONL log of every LLM exchange in a Forge run."""
+
+    def __init__(self, project_root: Path, run_id: str | None = None,
+                 dirname: str = ".atomadic-forge") -> None:
+        self.project_root = Path(project_root).resolve()
+        self.run_id = run_id or _dt.datetime.now(_dt.timezone.utc).strftime(
+            "run-%Y%m%dT%H%M%S")
+        self.dir = self.project_root / dirname / "transcripts"
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self.path = self.dir / f"{self.run_id}.jsonl"
+        self._turn = 0
+        if not self.path.exists():
+            self._write_meta()
+
+    def _write_meta(self) -> None:
+        self._raw_append({
+            "schema_version": "atomadic-forge.transcript/v1",
+            "ts_utc": _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds"),
+            "kind": "meta",
+            "run_id": self.run_id,
+        })
+
+    def append(self, kind: str, content: str, *,
+               role: str = "", llm: str = "",
+               extra: dict[str, Any] | None = None) -> None:
+        """Append one entry.
+
+        ``kind`` is e.g. ``"prompt"``, ``"response"``, ``"system"``, ``"meta"``.
+        ``role`` is for chat-shape compat (``"system"|"user"|"assistant"``).
+        """
+        self._turn += 1
+        self._raw_append({
+            "schema_version": "atomadic-forge.transcript/v1",
+            "ts_utc": _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds"),
+            "turn": self._turn,
+            "kind": kind,
+            "role": role,
+            "llm": llm,
+            "content": content,
+            "content_len": len(content or ""),
+            "extra": extra or {},
+        })
+
+    def _raw_append(self, entry: dict[str, Any]) -> None:
+        with self.path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(entry, default=str) + "\n")

atomadic_forge/a1_at_functions/wire_check.py

@@ -0,0 +1,260 @@
+"""Tier a1 — pure upward-import scanner + auto-fix proposer.
+
+Walks a tier-organized package and reports every import statement that
+violates the upward-only law (lower tier importing from a higher tier).
+Handles both Python (``from <pkg>.aN_… import …``) AND JavaScript / TypeScript
+(``import "../aN_…/foo"`` or ``require("../aN_…/foo")``).
+
+Lane D2 of the post-audit plan added the optional ``suggest_repairs``
+mode: when enabled, every violation gets a concrete ``proposed_fix``
+string and ``auto_fixable`` counts the suggestions whose minimum-edit
+fix is mechanically obvious (move the violating file UP to the tier of
+the symbol it imports). Heuristic, not a guarantee — the user still
+decides whether the file should move or whether the import should
+instead be inverted. Pure: no file writes, no exec.
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from pathlib import Path
+
+from ..a0_qk_constants.error_codes import fcode_for_tier_violation
+from ..a0_qk_constants.lang_extensions import (
+    JAVASCRIPT_EXTS,
+    PYTHON_EXTS,
+    TYPESCRIPT_EXTS,
+    path_parts_contain_ignored_dir,
+)
+from ..a0_qk_constants.tier_names import TIER_NAMES, can_import
+from .js_parser import parse_imports
+
+_TIER_PATH_RE = re.compile(r"\.(?P<tier>a\d_[a-z_]+)\.")
+_TIER_SLASH_RE = re.compile(r"(?P<tier>a\d_[a-z_]+)(?:/|$)")
+
+
+def _tier_of_module(module: str) -> str | None:
+    m = _TIER_PATH_RE.search(f".{module}.")
+    if m:
+        tier = m.group("tier")
+        if tier in TIER_NAMES:
+            return tier
+    return None
+
+
+def _tier_of_specifier(spec: str) -> str | None:
+    """Pull a tier name out of a JS module specifier.
+
+    ``"../a3_og_features/feature"`` → ``"a3_og_features"``.
+    """
+    if not spec:
+        return None
+    m = _TIER_SLASH_RE.search(spec.replace("\\", "/"))
+    if m:
+        tier = m.group("tier")
+        if tier in TIER_NAMES:
+            return tier
+    return None
+
+
+def _tier_of_file(path: Path, package_root: Path) -> str | None:
+    parts = path.relative_to(package_root).parts
+    for p in parts:
+        if p in TIER_NAMES:
+            return p
+    return None
+
+
+def _scan_python_file(py: Path, package_root: Path,
+                      from_tier: str, violations: list[dict]) -> None:
+    try:
+        tree = ast.parse(py.read_text(encoding="utf-8", errors="replace"),
+                          filename=str(py))
+    except (SyntaxError, OSError):
+        return
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.ImportFrom):
+            continue
+        mod = node.module or ""
+        to_tier = _tier_of_module(mod)
+        if to_tier is None:
+            continue
+        if can_import(from_tier, to_tier):
+            continue
+        for alias in node.names:
+            violations.append({
+                "file": str(py.relative_to(package_root).as_posix()),
+                "from_tier": from_tier,
+                "to_tier": to_tier,
+                "imported": alias.name,
+                "language": "python",
+                "f_code": fcode_for_tier_violation(from_tier, to_tier),
+                "proposed_fix": "",
+            })
+
+
+def _scan_js_file(js: Path, package_root: Path,
+                   from_tier: str, language: str,
+                   violations: list[dict]) -> None:
+    try:
+        text = js.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return
+    for spec in parse_imports(text):
+        to_tier = _tier_of_specifier(spec)
+        if to_tier is None:
+            continue
+        if can_import(from_tier, to_tier):
+            continue
+        violations.append({
+            "file": str(js.relative_to(package_root).as_posix()),
+            "from_tier": from_tier,
+            "to_tier": to_tier,
+            "imported": spec,
+            "language": language,
+            "f_code": fcode_for_tier_violation(from_tier, to_tier),
+            "proposed_fix": "",
+        })
+
+
+def suggest_fix_for_violation(violation: dict) -> dict:
+    """Return the violation augmented with a concrete repair proposal.
+
+    Heuristic: when tier T imports tier U upward (T < U), the safest
+    *mechanical* fix is to move the importing file from T to U — the
+    file is doing higher-tier work (consuming state / orchestrating)
+    and was misclassified. The alternative (push the imported symbol
+    down to T) requires semantic judgement we don't have here.
+
+    The returned dict has the original violation fields plus:
+        proposed_action      — one of "move_file_up" | "review_manually"
+        proposed_destination — target tier directory (e.g. "a2_mo_composites")
+        fix_command          — single shell command sketch the user can adapt
+        auto_fixable         — bool: is this a clean mechanical move?
+
+    Pure: no I/O. Heuristic — for review, not auto-apply.
+    """
+    file = violation["file"]
+    from_tier = violation["from_tier"]
+    to_tier = violation["to_tier"]
+    language = violation.get("language", "python")
+    imported = violation.get("imported", "")
+
+    auto_fixable = (
+        from_tier in TIER_NAMES
+        and to_tier in TIER_NAMES
+        and from_tier != to_tier
+        and language in ("python", "javascript", "typescript")
+    )
+
+    if auto_fixable:
+        proposed_action = "move_file_up"
+        proposed_destination = to_tier
+        # File path under the package: the user's package root prefix
+        # is unknown to this pure function, so the command is a sketch.
+        fix_command = (
+            f"mv <package_root>/{file} <package_root>/{to_tier}/"
+            f"{Path(file).name}  "
+            f"# then update imports referencing the old path"
+        )
+        reasoning = (
+            f"{file} is at tier {from_tier} but imports from "
+            f"tier {to_tier} (symbol: {imported!r}). The safest "
+            f"mechanical fix is to relocate the file up to {to_tier}; "
+            f"if the file is genuinely a {from_tier} citizen, the "
+            f"imported symbol probably belongs at {from_tier} or "
+            f"lower instead."
+        )
+    else:
+        proposed_action = "review_manually"
+        proposed_destination = ""
+        fix_command = ""
+        reasoning = (
+            f"Could not auto-classify a destination for {file} "
+            f"(from_tier={from_tier!r}, to_tier={to_tier!r}, "
+            f"language={language!r}). Review manually."
+        )
+
+    return {
+        **violation,
+        "proposed_action": proposed_action,
+        "proposed_destination": proposed_destination,
+        "fix_command": fix_command,
+        "reasoning": reasoning,
+        "auto_fixable": auto_fixable,
+    }
+
+
+def scan_violations(
+    package_root: Path,
+    *,
+    suggest_repairs: bool = False,
+) -> dict:
+    """Return a wire report dict keyed by ``schema_version``.
+
+    Polyglot: scans Python ``.py`` AND JavaScript / TypeScript files. Each
+    violation includes a ``language`` field so reports can group by source.
+
+    ``suggest_repairs`` (Lane D2): when True, every violation is enriched
+    with a ``proposed_fix`` string, the top-level ``auto_fixable`` count
+    is the number of violations with a clean mechanical move, and the
+    response includes a ``repair_suggestions`` summary (one entry per
+    file, deduplicated). Default False keeps the v1 schema unchanged.
+    """
+    package_root = Path(package_root).resolve()
+    violations: list[dict] = []
+    auto_fixable = 0
+
+    for f in package_root.rglob("*"):
+        if not f.is_file():
+            continue
+        rel_parts = f.relative_to(package_root).parts
+        if path_parts_contain_ignored_dir(rel_parts):
+            continue
+        from_tier = _tier_of_file(f, package_root)
+        if from_tier is None:
+            continue
+        suffix = f.suffix.lower()
+        if suffix in PYTHON_EXTS:
+            _scan_python_file(f, package_root, from_tier, violations)
+        elif suffix in JAVASCRIPT_EXTS:
+            _scan_js_file(f, package_root, from_tier, "javascript", violations)
+        elif suffix in TYPESCRIPT_EXTS:
+            _scan_js_file(f, package_root, from_tier, "typescript", violations)
+
+    repair_suggestions: list[dict] = []
+    if suggest_repairs:
+        for v in violations:
+            enriched = suggest_fix_for_violation(v)
+            v["proposed_fix"] = enriched["fix_command"] or enriched["reasoning"]
+            v["proposed_action"] = enriched["proposed_action"]
+            v["proposed_destination"] = enriched["proposed_destination"]
+            if enriched["auto_fixable"]:
+                auto_fixable += 1
+        # One summary entry per (file, proposed_destination) pair.
+        seen: set[tuple[str, str]] = set()
+        for v in violations:
+            key = (v["file"], v.get("proposed_destination", ""))
+            if key in seen:
+                continue
+            seen.add(key)
+            repair_suggestions.append({
+                "file": v["file"],
+                "from_tier": v["from_tier"],
+                "proposed_action": v.get("proposed_action", "review_manually"),
+                "proposed_destination": v.get("proposed_destination", ""),
+                "violation_count": sum(1 for w in violations if w["file"] == v["file"]),
+            })
+
+    report: dict = {
+        "schema_version": "atomadic-forge.wire/v1",
+        "source_dir": str(package_root),
+        "violation_count": len(violations),
+        "auto_fixable": auto_fixable,
+        "violations": violations,
+        "verdict": "PASS" if not violations else "FAIL",
+    }
+    if suggest_repairs:
+        report["repair_suggestions"] = repair_suggestions
+    return report

atomadic_forge/a2_mo_composites/__init__.py

@@ -0,0 +1 @@
+"""Tier a2 — stateful composites. May import from a0 + a1 only."""

atomadic_forge/a2_mo_composites/lineage_chain_store.py

@@ -0,0 +1,122 @@
+"""Tier a2 — append-only lineage chain store.
+
+Persists the local Vanguard-style lineage chain at
+``.atomadic-forge/lineage_chain.jsonl``. One JSON line per Receipt;
+each line records:
+
+    {
+      "ts_utc":              "2026-04-29T05:30:00Z",
+      "hash":                "<receipt content hash>",
+      "parent_receipt_hash": "<prior link hash, or null for head>",
+      "chain_depth":         <int>,
+      "verdict":             "PASS" | "FAIL" | "REFINE" | "QUARANTINE",
+      "schema_version":      "<receipt schema_version>",
+      "lineage_path":        "<local:// URI>",
+    }
+
+Reading the tip of the chain returns ``(parent_hash, depth)`` for the
+next link to consume. The chain log is append-only — corrupt lines
+are skipped silently so a malformed write never breaks subsequent
+reads.
+
+Lane A W4 ships the LOCAL store today; the AAAA-Nexus
+``/v1/forge/lineage`` POST publisher slots in here once the endpoint
+is live, with the same soft-fail contract as Lane A W2's
+``ReceiptSigner``.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import json
+from pathlib import Path
+
+from ..a0_qk_constants.receipt_schema import ForgeReceiptV1
+from ..a1_at_functions.lineage_chain import (
+    canonical_receipt_hash,
+    link_to_parent,
+)
+
+_DIRNAME = ".atomadic-forge"
+_FILENAME = "lineage_chain.jsonl"
+
+
+class LineageChainStore:
+    """Append-only local Vanguard ledger for one project."""
+
+    def __init__(self, project_root: Path) -> None:
+        self.project_root = Path(project_root).resolve()
+        self.dir = self.project_root / _DIRNAME
+        self.path = self.dir / _FILENAME
+
+    # ---- read paths ----------------------------------------------------
+
+    def read_tip(self) -> tuple[str | None, int]:
+        """Return ``(parent_hash, depth_of_tip)``.
+
+        For the chain head (no prior receipts) the tuple is
+        ``(None, 0)``; the next link should be at depth=1.
+        """
+        if not self.path.exists():
+            return None, 0
+        last: dict | None = None
+        for line in self.path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(entry, dict):
+                last = entry
+        if last is None:
+            return None, 0
+        return last.get("hash"), int(last.get("chain_depth", 0))
+
+    def read_all(self) -> list[dict]:
+        if not self.path.exists():
+            return []
+        out: list[dict] = []
+        for line in self.path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(entry, dict):
+                out.append(entry)
+        return out
+
+    # ---- write path ----------------------------------------------------
+
+    def link_and_append(self, receipt: ForgeReceiptV1) -> ForgeReceiptV1:
+        """Compute the chain link for ``receipt``, append, return the
+        Receipt with its lineage block populated.
+
+        Always writes — append-only. Caller decides whether to also
+        re-emit the Receipt JSON (typically yes; the chain entry and
+        the on-disk Receipt should both reflect the same lineage).
+        """
+        parent_hash, parent_depth = self.read_tip()
+        linked = link_to_parent(
+            receipt,
+            parent_receipt_hash=parent_hash,
+            chain_depth=parent_depth + 1,
+        )
+        own_hash = canonical_receipt_hash(linked)
+        entry = {
+            "ts_utc": _dt.datetime.now(_dt.timezone.utc).strftime(
+                "%Y-%m-%dT%H:%M:%SZ"),
+            "hash": own_hash,
+            "parent_receipt_hash": parent_hash,
+            "chain_depth": parent_depth + 1,
+            "verdict": linked.get("verdict"),
+            "schema_version": linked.get("schema_version"),
+            "lineage_path": (linked.get("lineage") or {}).get("lineage_path"),
+        }
+        self.dir.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(entry) + "\n")
+        return linked

atomadic_forge/a2_mo_composites/manifest_store.py

@@ -0,0 +1,46 @@
+"""Tier a2 — stateful manifest read/write.
+
+Persists scout / cherry / assimilate / certify reports under a project's
+``.atomadic-forge/`` directory, and records run lineage.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+from pathlib import Path
+from typing import Any
+
+_DEFAULT_DIRNAME = ".atomadic-forge"
+
+
+class ManifestStore:
+    """Append-only store for Forge artifacts beneath a project root."""
+
+    def __init__(self, project_root: Path, *, dirname: str = _DEFAULT_DIRNAME):
+        self.project_root = Path(project_root).resolve()
+        self.dir = self.project_root / dirname
+        self.dir.mkdir(parents=True, exist_ok=True)
+
+    def save(self, name: str, payload: dict[str, Any]) -> Path:
+        target = self.dir / f"{name}.json"
+        target.write_text(json.dumps(payload, indent=2, default=str),
+                          encoding="utf-8")
+        self._append_lineage(name, target)
+        return target
+
+    def load(self, name: str) -> dict[str, Any] | None:
+        target = self.dir / f"{name}.json"
+        if not target.exists():
+            return None
+        return json.loads(target.read_text(encoding="utf-8"))
+
+    def _append_lineage(self, name: str, path: Path) -> None:
+        log = self.dir / "lineage.jsonl"
+        entry = {
+            "ts_utc": _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds"),
+            "artifact": name,
+            "path": str(path.relative_to(self.project_root).as_posix()),
+        }
+        with log.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(entry) + "\n")