giro 0.0.1__py3-none-any.whl

giro/__init__.py

@@ -0,0 +1,8 @@
+"""giro — guarded loops for AI coding agents.
+
+Specs become verified work through bounded loops that end in proof or
+escalation, never a silent stop. Control never crosses an LLM; content
+always does.
+"""
+
+__version__ = "0.0.1"

giro/cli.py

@@ -0,0 +1,126 @@
+"""The giro CLI — the product's front door.
+
+Exit codes are part of the contract: 0 = proof, 2 = needs-human, 1 = error.
+A CI job or a chat agent reads them the same way.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import CONFIG_NAME, INIT_TEMPLATE, ConfigError, load_config
+from .drivers import DriverError, build_driver
+from .envelope import EnvelopeError
+from .gates import build_context, run_gates
+from .loops import Engine
+from .store import Store, StoreError
+from .workspace import Workspace, WorkspaceError
+
+EXIT_PROOF = 0
+EXIT_ERROR = 1
+EXIT_NEEDS_HUMAN = 2
+
+
+def _build_engine(root: Path) -> Engine:
+    cfg = load_config(root)
+    drivers = {}
+    for role in ("implementer", "judge", "planner"):
+        entry = cfg.roster_for(role)
+        drivers[role] = build_driver(entry.driver, args=entry.args)
+    return Engine(cfg=cfg, store=Store(root), workspace=Workspace(root), drivers=drivers)
+
+
+def cmd_init(root: Path) -> int:
+    path = root / CONFIG_NAME
+    if path.exists():
+        print(f"{CONFIG_NAME} already exists — edit it directly.")
+        return EXIT_ERROR
+    path.write_text(INIT_TEMPLATE, encoding="utf-8")
+    (root / "docs" / "specs").mkdir(parents=True, exist_ok=True)
+    print(f"Wrote {CONFIG_NAME} and docs/specs/.")
+    print("Next: set your [verify] gates, then write a Spec and run `giro implement <slug>`.")
+    return EXIT_PROOF
+
+
+def cmd_status(root: Path) -> int:
+    store = Store(root)
+    specs = store.list_specs()
+    if not specs:
+        print("No specs under docs/specs/.")
+        return EXIT_PROOF
+    for spec in specs:
+        print(f"{spec.slug} [{spec.state}] {spec.title}")
+        for issue in store.load_issues(spec.slug):
+            deps = f" blocked_by={','.join(issue.blocked_by)}" if issue.blocked_by else ""
+            print(
+                f"  {issue.id} [{issue.state}] attempts={issue.attempts}{deps} {issue.title}"
+            )
+    return EXIT_PROOF
+
+
+def cmd_verify(root: Path) -> int:
+    engine = _build_engine(root)
+    ctx = build_context(
+        engine.cfg, root, "Manual `giro verify` run: judge the working tree.",
+        engine.drivers["judge"],
+    )
+    green, findings = run_gates(engine.cfg.verify_gates, ctx)
+    for finding in findings:
+        print(f"[{finding.gate}] {finding.summary}")
+        if finding.detail:
+            print(f"    {finding.detail[:500]}")
+    print("all green" if green else f"{len(findings)} finding(s)")
+    return EXIT_PROOF if green else EXIT_NEEDS_HUMAN
+
+
+def cmd_implement(root: Path, target: str) -> int:
+    engine = _build_engine(root)
+    report = engine.implement(target)
+    print(f"{report.target}: {report.outcome} — {report.detail}")
+    for ref, state in sorted(report.issues.items()):
+        print(f"  {ref}: {state}")
+    if report.outcome in ("done", "all-done"):
+        return EXIT_PROOF
+    return EXIT_NEEDS_HUMAN
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="giro",
+        description="Guarded loops: Specs become verified work — proof or escalation.",
+    )
+    parser.add_argument("--version", action="version", version=f"giro {__version__}")
+    parser.add_argument(
+        "-C", dest="root", default=".", help="project root (default: current directory)"
+    )
+    sub = parser.add_subparsers(dest="command")
+    sub.add_parser("init", help="write a starter giro.toml")
+    sub.add_parser("status", help="show spec and issue states")
+    sub.add_parser("verify", help="run the [verify] gate set once")
+    p_impl = sub.add_parser("implement", help="run the guarded loop for a spec or issue")
+    p_impl.add_argument("target", help="spec slug, issue id, or slug/issue-id")
+
+    args = parser.parse_args(argv)
+    root = Path(args.root).resolve()
+
+    try:
+        if args.command == "init":
+            return cmd_init(root)
+        if args.command == "status":
+            return cmd_status(root)
+        if args.command == "verify":
+            return cmd_verify(root)
+        if args.command == "implement":
+            return cmd_implement(root, args.target)
+        parser.print_help()
+        return EXIT_PROOF
+    except (ConfigError, StoreError, WorkspaceError, DriverError, EnvelopeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    sys.exit(main())

giro/config.py

@@ -0,0 +1,168 @@
+"""giro.toml — gates, roster, and budgets, fixed at setup.
+
+The loops read this; they never invent it.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+GATE_TYPES = frozenset({"command", "prompt", "skill"})
+ROLES = ("implementer", "judge", "planner")
+
+CONFIG_NAME = "giro.toml"
+
+
+class ConfigError(Exception):
+    """giro.toml is missing or invalid."""
+
+
+@dataclass
+class GateSpec:
+    name: str
+    type: str  # "command" | "prompt" | "skill"
+    run: str = ""  # command gates
+    rubric: str = ""  # prompt gates
+    skill: str = ""  # skill gates
+
+
+@dataclass
+class RosterEntry:
+    driver: str = "claude"
+    model: str = ""
+    args: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Config:
+    root: Path
+    verify_gates: list[GateSpec]
+    validate_gates: list[GateSpec]
+    roster: dict[str, RosterEntry]
+    concurrency: int = 1
+    issue_attempts: int = 3
+    validate_cycles: int = 3
+    gate_timeout: int = 600
+
+    def roster_for(self, role: str) -> RosterEntry:
+        """Resolve a role, falling back to the implementer entry."""
+        if role in self.roster:
+            return self.roster[role]
+        if "implementer" in self.roster:
+            return self.roster["implementer"]
+        return RosterEntry()
+
+
+def _parse_gates(section: object, where: str) -> list[GateSpec]:
+    if section is None:
+        return []
+    if not isinstance(section, dict) or not isinstance(section.get("gates"), list):
+        raise ConfigError(f"[{where}] must contain a 'gates' array")
+    gates: list[GateSpec] = []
+    for i, raw in enumerate(section["gates"]):
+        if not isinstance(raw, dict):
+            raise ConfigError(f"[{where}] gate #{i + 1} must be a table")
+        name = raw.get("name") or f"{where}-{i + 1}"
+        gtype = raw.get("type", "")
+        if gtype not in GATE_TYPES:
+            raise ConfigError(
+                f"[{where}] gate {name!r}: type must be one of {sorted(GATE_TYPES)}"
+            )
+        gate = GateSpec(
+            name=str(name),
+            type=gtype,
+            run=str(raw.get("run", "")),
+            rubric=str(raw.get("rubric", "")),
+            skill=str(raw.get("skill", "")),
+        )
+        required = {"command": "run", "prompt": "rubric", "skill": "skill"}[gtype]
+        if not getattr(gate, required):
+            raise ConfigError(f"[{where}] gate {name!r}: {gtype} gates require {required!r}")
+        gates.append(gate)
+    return gates
+
+
+def _parse_roster(raw: object) -> dict[str, RosterEntry]:
+    roster: dict[str, RosterEntry] = {}
+    if raw is None:
+        return roster
+    if not isinstance(raw, dict):
+        raise ConfigError("[runner.roster] must be a table of role entries")
+    for role, entry in raw.items():
+        if not isinstance(entry, dict):
+            raise ConfigError(f"[runner.roster] {role!r} must be a table")
+        args = entry.get("args", [])
+        if not isinstance(args, list) or not all(isinstance(a, str) for a in args):
+            raise ConfigError(f"[runner.roster] {role!r}: 'args' must be a list of strings")
+        roster[role] = RosterEntry(
+            driver=str(entry.get("driver", "claude")),
+            model=str(entry.get("model", "")),
+            args=list(args),
+        )
+    return roster
+
+
+def load_config(root: Path) -> Config:
+    path = root / CONFIG_NAME
+    if not path.is_file():
+        raise ConfigError(f"{CONFIG_NAME} not found in {root} — run `giro init` first")
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{CONFIG_NAME} is not valid TOML: {exc}") from exc
+
+    runner = data.get("runner", {})
+    budget = data.get("budget", {})
+    if not isinstance(runner, dict) or not isinstance(budget, dict):
+        raise ConfigError("[runner] and [budget] must be tables")
+
+    verify_gates = _parse_gates(data.get("verify"), "verify")
+    if not verify_gates:
+        raise ConfigError("[verify] must define at least one gate")
+
+    def _int(section: dict, key: str, default: int) -> int:
+        value = section.get(key, default)
+        if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+            raise ConfigError(f"{key!r} must be a positive integer")
+        return value
+
+    return Config(
+        root=root,
+        verify_gates=verify_gates,
+        validate_gates=_parse_gates(data.get("validate"), "validate"),
+        roster=_parse_roster(runner.get("roster")),
+        concurrency=_int(runner, "concurrency", 1),
+        issue_attempts=_int(budget, "issue_attempts", 3),
+        validate_cycles=_int(budget, "validate_cycles", 3),
+        gate_timeout=_int(budget, "gate_timeout", 600),
+    )
+
+
+INIT_TEMPLATE = """\
+# giro configuration — gates, roster, budgets. See docs/design.md in the giro repo.
+
+[verify]  # Issue-level gate set: runs after every worker attempt
+gates = [
+  { name = "test", type = "command", run = "make test" },
+]
+
+[validate]  # Spec-level gate set: runs once every child Issue is terminal
+gates = [
+  { name = "spec-fit", type = "prompt", rubric = "Every acceptance criterion in the Spec is met." },
+]
+
+[runner]
+concurrency = 1  # 1 = sequential fresh workers; >1 = isolated worktrees (roadmap)
+
+[runner.roster]  # drivers: claude | agy | codex | gemini; args pass through to the CLI
+implementer = { driver = "claude", args = ["--dangerously-skip-permissions"] }
+judge = { driver = "claude" }
+planner = { driver = "claude" }
+
+[budget]  # the "never silent" bounds
+issue_attempts = 3   # verify retries per Issue before needs-human
+validate_cycles = 3  # gap -> re-wave loops before needs-human
+gate_timeout = 600   # seconds per command gate
+"""

giro/drivers.py

@@ -0,0 +1,213 @@
+"""Drivers — how the engine spawns an LLM context and gets an envelope back.
+
+A Driver's whole contract is: run this prompt in a fresh context at this
+cwd, and return the parsed JSON envelope the context ended with. Everything
+else (what the prompt says, what the schema demands, what happens to the
+result) belongs to the engine.
+
+Four agent CLIs ship as drivers — ``claude``, ``agy``, ``codex``,
+``gemini`` — each a thin argv recipe over one shared subprocess runner.
+Errors surface the CLI's own message (auth failures, quota limits), never a
+bare exit code.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Protocol
+
+
+class DriverError(Exception):
+    """The context could not be run or produced no parseable JSON."""
+
+
+class Driver(Protocol):
+    def run(
+        self, prompt: str, schema: dict[str, Any], cwd: Path, model: str = ""
+    ) -> dict[str, Any]: ...
+
+
+def extract_json(text: str) -> dict[str, Any]:
+    """Extract the last complete JSON object from free text (fenced or bare)."""
+    decoder = json.JSONDecoder()
+    found: dict[str, Any] | None = None
+    idx = 0
+    while (start := text.find("{", idx)) != -1:
+        try:
+            obj, end = decoder.raw_decode(text[start:])
+        except json.JSONDecodeError:
+            idx = start + 1
+            continue
+        if isinstance(obj, dict):
+            found = obj
+        idx = start + end
+    if found is None:
+        raise DriverError("no JSON object found in context output")
+    return found
+
+
+def _tail(text: str, limit: int = 2000) -> str:
+    text = text.strip()
+    return text if len(text) <= limit else "…" + text[-limit:]
+
+
+FakeResponse = dict[str, Any] | Exception | Callable[[str, Path], dict[str, Any]]
+
+
+class FakeDriver:
+    """Scripted driver for tests: canned envelopes, optional side effects.
+
+    Each queued response may be a dict (returned as-is), an Exception
+    (raised), or a callable ``(prompt, cwd) -> dict`` for responses that
+    need to mutate the workspace the way a real worker would.
+    """
+
+    def __init__(self, responses: list[FakeResponse]):
+        self._responses = list(responses)
+        self.calls: list[dict[str, Any]] = []
+
+    def run(
+        self, prompt: str, schema: dict[str, Any], cwd: Path, model: str = ""
+    ) -> dict[str, Any]:
+        self.calls.append({"prompt": prompt, "schema": schema, "cwd": cwd, "model": model})
+        if not self._responses:
+            raise DriverError("FakeDriver ran out of scripted responses")
+        response = self._responses.pop(0)
+        if isinstance(response, Exception):
+            raise response
+        if callable(response):
+            return response(prompt, cwd)
+        return response
+
+
+class SubprocessDriver:
+    """Shared shell-out runner: build argv, spawn, extract the final JSON."""
+
+    name = "subprocess"
+
+    def __init__(self, args: list[str] | None = None, timeout: int = 3600):
+        self.args = list(args or [])
+        self.timeout = timeout
+
+    def build_argv(self, prompt: str, model: str) -> list[str]:  # pragma: no cover
+        raise NotImplementedError
+
+    def postprocess(self, stdout: str) -> str:
+        """Hook: reduce raw stdout to the text that carries the envelope."""
+        return stdout
+
+    def error_detail(self, proc: subprocess.CompletedProcess[str]) -> str:
+        """Hook: the most useful message when the CLI fails."""
+        return _tail(proc.stderr) or _tail(proc.stdout)
+
+    def run(
+        self, prompt: str, schema: dict[str, Any], cwd: Path, model: str = ""
+    ) -> dict[str, Any]:
+        argv = self.build_argv(prompt, model)
+        try:
+            proc = subprocess.run(
+                argv, cwd=cwd, capture_output=True, text=True, timeout=self.timeout
+            )
+        except FileNotFoundError as exc:
+            raise DriverError(f"`{argv[0]}` CLI not found on PATH") from exc
+        except subprocess.TimeoutExpired as exc:
+            raise DriverError(f"{self.name} context timed out after {self.timeout}s") from exc
+        if proc.returncode != 0:
+            raise DriverError(
+                f"{self.name} exited {proc.returncode}: {self.error_detail(proc)}"
+            )
+        return extract_json(self.postprocess(proc.stdout))
+
+
+class ClaudeDriver(SubprocessDriver):
+    """``claude -p`` — non-interactive Claude Code context."""
+
+    name = "claude"
+
+    def build_argv(self, prompt: str, model: str) -> list[str]:
+        argv = ["claude", "-p", prompt, "--output-format", "json", *self.args]
+        if model:
+            argv += ["--model", model]
+        return argv
+
+    def _outer(self, stdout: str) -> dict[str, Any] | None:
+        try:
+            outer = json.loads(stdout)
+        except json.JSONDecodeError:
+            return None
+        return outer if isinstance(outer, dict) else None
+
+    def postprocess(self, stdout: str) -> str:
+        outer = self._outer(stdout)
+        if outer is None:
+            return stdout
+        # claude reports its own failures (auth, quota) inside the result JSON
+        # with is_error=true — surface the message, don't parse it as work.
+        if outer.get("is_error"):
+            raise DriverError(f"claude: {outer.get('result', 'unknown error')}")
+        result = outer.get("result")
+        return result if isinstance(result, str) else stdout
+
+    def error_detail(self, proc: subprocess.CompletedProcess[str]) -> str:
+        outer = self._outer(proc.stdout)
+        if outer is not None and outer.get("result"):
+            return str(outer["result"])
+        return super().error_detail(proc)
+
+
+class AgyDriver(SubprocessDriver):
+    """Antigravity's ``agy`` CLI. Model must be an exact roster name,
+    e.g. ``Gemini 3.6 Flash (Medium)``."""
+
+    name = "agy"
+
+    def build_argv(self, prompt: str, model: str) -> list[str]:
+        argv = ["agy", "-p", prompt, "--dangerously-skip-permissions",
+                "--print-timeout", f"{self.timeout}s", *self.args]
+        if model:
+            argv += ["--model", model]
+        return argv
+
+
+class CodexDriver(SubprocessDriver):
+    """``codex exec`` — the prompt is positional and LAST."""
+
+    name = "codex"
+
+    def build_argv(self, prompt: str, model: str) -> list[str]:
+        argv = ["codex", "exec", "--dangerously-bypass-approvals-and-sandbox",
+                "--skip-git-repo-check", "--color", "never", *self.args]
+        if model:
+            argv += ["--model", model]
+        return [*argv, prompt]
+
+
+class GeminiDriver(SubprocessDriver):
+    """``gemini -p`` — needs GEMINI_API_KEY or prior CLI auth."""
+
+    name = "gemini"
+
+    def build_argv(self, prompt: str, model: str) -> list[str]:
+        argv = ["gemini", "-p", prompt, "--yolo", "--skip-trust", *self.args]
+        if model:
+            argv += ["--model", model]
+        return argv
+
+
+DRIVER_REGISTRY: dict[str, type[SubprocessDriver]] = {
+    "claude": ClaudeDriver,
+    "agy": AgyDriver,
+    "codex": CodexDriver,
+    "gemini": GeminiDriver,
+}
+
+
+def build_driver(name: str, args: list[str] | None = None) -> Driver:
+    if name not in DRIVER_REGISTRY:
+        raise DriverError(
+            f"unknown driver {name!r}; available: {sorted(DRIVER_REGISTRY)}"
+        )
+    return DRIVER_REGISTRY[name](args=args)

giro/envelope.py

@@ -0,0 +1,177 @@
+"""Envelopes — the only things that cross back from an LLM context.
+
+Every spawned context ends by emitting one JSON envelope. The engine
+schema-checks it here; a malformed envelope is an error the caller turns
+into a failed attempt or a failed gate (fail closed), never a shrug.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+WORKER_OUTCOMES = frozenset({"completed", "needs-human", "failed"})
+VERDICTS = frozenset({"pass", "fail"})
+
+
+class EnvelopeError(Exception):
+    """The context's final output did not match the required schema."""
+
+
+@dataclass
+class Finding:
+    summary: str
+    detail: str = ""
+    location: str = ""
+    gate: str = ""
+
+    def as_dict(self) -> dict[str, str]:
+        out = {"summary": self.summary}
+        if self.detail:
+            out["detail"] = self.detail
+        if self.location:
+            out["location"] = self.location
+        if self.gate:
+            out["gate"] = self.gate
+        return out
+
+
+@dataclass
+class GateVerdict:
+    verdict: str  # "pass" | "fail"
+    findings: list[Finding] = field(default_factory=list)
+
+    @property
+    def passed(self) -> bool:
+        return self.verdict == "pass"
+
+
+@dataclass
+class WorkerResult:
+    outcome: str  # "completed" | "needs-human" | "failed"
+    summary: str
+    notes: str = ""
+
+
+def _require(data: Any, key: str, kind: type) -> Any:
+    if not isinstance(data, dict):
+        raise EnvelopeError(f"envelope must be a JSON object, got {type(data).__name__}")
+    if key not in data:
+        raise EnvelopeError(f"envelope missing required key {key!r}")
+    value = data[key]
+    if not isinstance(value, kind):
+        raise EnvelopeError(f"envelope key {key!r} must be {kind.__name__}")
+    return value
+
+
+def parse_findings(raw: Any) -> list[Finding]:
+    if not isinstance(raw, list):
+        raise EnvelopeError("'findings' must be a list")
+    findings: list[Finding] = []
+    for item in raw:
+        summary = _require(item, "summary", str)
+        findings.append(
+            Finding(
+                summary=summary,
+                detail=str(item.get("detail", "")),
+                location=str(item.get("location", "")),
+            )
+        )
+    return findings
+
+
+def parse_verdict(data: Any) -> GateVerdict:
+    verdict = _require(data, "verdict", str)
+    if verdict not in VERDICTS:
+        raise EnvelopeError(f"'verdict' must be one of {sorted(VERDICTS)}, got {verdict!r}")
+    findings = parse_findings(data.get("findings", []))
+    if verdict == "fail" and not findings:
+        findings = [Finding(summary="gate failed without findings")]
+    return GateVerdict(verdict=verdict, findings=findings)
+
+
+def parse_worker(data: Any) -> WorkerResult:
+    outcome = _require(data, "outcome", str)
+    if outcome not in WORKER_OUTCOMES:
+        raise EnvelopeError(f"'outcome' must be one of {sorted(WORKER_OUTCOMES)}, got {outcome!r}")
+    summary = _require(data, "summary", str)
+    return WorkerResult(outcome=outcome, summary=summary, notes=str(data.get("notes", "")))
+
+
+@dataclass
+class PlannedIssue:
+    title: str
+    body: str
+    blocked_by: list[int] = field(default_factory=list)  # 1-based indices into the plan
+
+
+def parse_plan(data: Any) -> list[PlannedIssue]:
+    raw = _require(data, "issues", list)
+    if not raw:
+        raise EnvelopeError("'issues' must contain at least one issue")
+    planned: list[PlannedIssue] = []
+    for item in raw:
+        title = _require(item, "title", str)
+        body = _require(item, "body", str)
+        blocked = item.get("blocked_by", [])
+        if not isinstance(blocked, list) or not all(isinstance(b, int) for b in blocked):
+            raise EnvelopeError("'blocked_by' must be a list of integers (1-based plan indices)")
+        planned.append(PlannedIssue(title=title, body=body, blocked_by=list(blocked)))
+    for i, issue in enumerate(planned, start=1):
+        for dep in issue.blocked_by:
+            if dep < 1 or dep > len(planned) or dep == i:
+                raise EnvelopeError(f"plan issue {i} has invalid dependency index {dep}")
+    return planned
+
+
+# JSON Schemas handed to drivers that support structured output, and embedded
+# in prompts for those that do not.
+
+VERDICT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "required": ["verdict"],
+    "properties": {
+        "verdict": {"enum": ["pass", "fail"]},
+        "findings": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["summary"],
+                "properties": {
+                    "summary": {"type": "string"},
+                    "detail": {"type": "string"},
+                    "location": {"type": "string"},
+                },
+            },
+        },
+    },
+}
+
+WORKER_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "required": ["outcome", "summary"],
+    "properties": {
+        "outcome": {"enum": ["completed", "needs-human", "failed"]},
+        "summary": {"type": "string"},
+        "notes": {"type": "string"},
+    },
+}
+
+PLAN_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "required": ["issues"],
+    "properties": {
+        "issues": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["title", "body"],
+                "properties": {
+                    "title": {"type": "string"},
+                    "body": {"type": "string"},
+                    "blocked_by": {"type": "array", "items": {"type": "integer"}},
+                },
+            },
+        }
+    },
+}