giro 0.0.1__tar.gz

giro-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run pytest -q

giro-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: release
+
+# Publishes to PyPI via trusted publishing (OIDC) — no tokens stored anywhere.
+# One-time setup on pypi.org: Account -> Publishing -> add a pending publisher
+#   project: giro, owner: pierg, repository: giro,
+#   workflow: release.yml, environment: pypi
+# Then push a v* tag or trigger this workflow manually.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish --trusted-publishing always

giro-0.0.1/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/

giro-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Piergiuseppe Mallozzi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

giro-0.0.1/Makefile

@@ -0,0 +1,9 @@
+.PHONY: check test lint
+
+check: lint test
+
+lint:
+	uv run ruff check .
+
+test:
+	uv run pytest -q

giro-0.0.1/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: giro
+Version: 0.0.1
+Summary: Guarded-loop engine for AI coding agents: Specs become verified work through bounded loops that end in proof or escalation, never a silent stop.
+Project-URL: Repository, https://github.com/pierg/giro
+Author: Piergiuseppe Mallozzi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,automation,loops,tdd,verification
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# giro
+
+**Guarded loops for AI coding agents.** giro turns a Spec into integrated, verified work through bounded loops that exit exactly two ways — **proof**, or a **hand raised to a human**. Nothing silent in between.
+
+*Giro* — a lap, a loop, a tour in stages. The engine runs the laps; you write the route and take the finish.
+
+> **Status: pre-alpha (M0).** The loop engine, state store, gate runner, and CLI exist and are fully tested against a fake driver. Live agent drivers are the next milestone. Successor to [pierg/orchestrion](https://github.com/pierg/orchestrion), rebuilt from scratch around a narrower thesis.
+
+## The thesis
+
+Most agent frameworks describe what an agent *should* do and hope it complies. giro inverts that:
+
+> **Control never crosses an LLM. Content always does.**
+
+The `giro` CLI is a deterministic loop engine. It owns every arrow — state transitions, budgets, gate execution, wave scheduling, escalation. LLM contexts are spawned *inside* the loop to do the creative work (implement, plan, judge), and each one ends by emitting a JSON envelope. A budget enforced by a `while` loop cannot be talked out of; an LLM "following instructions" can.
+
+## One primitive, two levels
+
+An **actor** makes an attempt. An independent **verifier** — a set of gates — judges it. All green: the loop exits with proof. Otherwise the findings feed the next attempt, until the **budget** runs out and the loop escalates to `needs-human`. It cannot just stop.
+
+| Loop | Actor | Verifier | On fail |
+|---|---|---|---|
+| **Issue loop** | a fresh worker context | `[verify]` gates | retry, findings carried forward |
+| **Spec loop** | a wave of Issue loops | `[validate]` gates | findings become gap Issues → next wave |
+
+There is no third loop. Validate *is* the Spec loop's verifier; gap Issues *are* its feedback. The "lifecycle" is one feedback edge, not a controller.
+
+## One verb
+
+```bash
+giro implement <target>
+```
+
+The router reads the target and picks the level. An Issue runs the Issue loop. A Spec runs the Spec loop — planned into Issues first if it has none. No second entrypoint, no mode flags. When a run ends `needs-human`, you answer (edit the Issue, decide the question) and run the same command again: re-invoking *is* the answer, and the budget resets.
+
+Merging `giro/<spec>` into your main line stays your hand, always.
+
+## Gates
+
+A gate is anything that ends in `{ "verdict": "pass" | "fail", "findings": [...] }`.
+
+- **command** — a shell command; exit 0 is pass. Deterministic and cheap.
+- **prompt** — a rubric applied by a fresh, blind judge context.
+- **skill** — a full SKILL.md procedure, same envelope at the end.
+
+Judges start blind on every attempt; findings feed the next *actor*, never the next judge. A judge that can't produce the envelope gets one retry, then **fails closed**. All gates run to completion — the next attempt sees every finding, not just the first.
+
+## State
+
+Specs and Issues are markdown with tiny frontmatter, committed beside the code:
+
+```
+docs/specs/<slug>/SPEC.md            state: draft | active | done | needs-human
+docs/specs/<slug>/issues/NN-slug.md  state: ready | in-progress | done | needs-human | wontfix
+```
+
+The store is the durable checkpoint: kill the engine at any point and `giro implement` resumes from exactly where the markdown says. Every attempt appends its story to the Issue file — the history is readable, not buried in a log.
+
+## Quickstart
+
+```bash
+uv tool install giro   # not yet published — for now: uv sync && uv run giro
+cd your-project
+giro init              # writes giro.toml — set your [verify] gates
+giro implement <spec>  # go
+```
+
+Exit codes are the contract: `0` proof, `2` needs-human, `1` error. CI and chat agents read them the same way.
+
+## Layout
+
+- [`docs/design.md`](docs/design.md) — the founding design: vocabulary, state machines, envelopes, loop contracts, decisions.
+- [`skills/`](skills/) — the LLM touchpoints: what workers, judges, and chat doorways are told.
+- [`src/giro/`](src/giro/) — the engine. `loops.py` is the heart.
+
+## Roadmap
+
+- **M0 — engine core** *(this)*: guarded loops, gates, store, CLI; proven end-to-end with a fake driver.
+- **M1 — live driver**: `claude -p` worker/judge/planner contexts; first real Spec shipped by the machine.
+- **M2 — parallel waves**: `concurrency > 1`, isolated worktrees, integration branch + re-verify.
+- **M3 — the doorway**: `/giro` chat skill, escalation console, one-shot install (CLI + skills).
+
+MIT — see [LICENSE](LICENSE).

giro-0.0.1/README.md

@@ -0,0 +1,83 @@
+# giro
+
+**Guarded loops for AI coding agents.** giro turns a Spec into integrated, verified work through bounded loops that exit exactly two ways — **proof**, or a **hand raised to a human**. Nothing silent in between.
+
+*Giro* — a lap, a loop, a tour in stages. The engine runs the laps; you write the route and take the finish.
+
+> **Status: pre-alpha (M0).** The loop engine, state store, gate runner, and CLI exist and are fully tested against a fake driver. Live agent drivers are the next milestone. Successor to [pierg/orchestrion](https://github.com/pierg/orchestrion), rebuilt from scratch around a narrower thesis.
+
+## The thesis
+
+Most agent frameworks describe what an agent *should* do and hope it complies. giro inverts that:
+
+> **Control never crosses an LLM. Content always does.**
+
+The `giro` CLI is a deterministic loop engine. It owns every arrow — state transitions, budgets, gate execution, wave scheduling, escalation. LLM contexts are spawned *inside* the loop to do the creative work (implement, plan, judge), and each one ends by emitting a JSON envelope. A budget enforced by a `while` loop cannot be talked out of; an LLM "following instructions" can.
+
+## One primitive, two levels
+
+An **actor** makes an attempt. An independent **verifier** — a set of gates — judges it. All green: the loop exits with proof. Otherwise the findings feed the next attempt, until the **budget** runs out and the loop escalates to `needs-human`. It cannot just stop.
+
+| Loop | Actor | Verifier | On fail |
+|---|---|---|---|
+| **Issue loop** | a fresh worker context | `[verify]` gates | retry, findings carried forward |
+| **Spec loop** | a wave of Issue loops | `[validate]` gates | findings become gap Issues → next wave |
+
+There is no third loop. Validate *is* the Spec loop's verifier; gap Issues *are* its feedback. The "lifecycle" is one feedback edge, not a controller.
+
+## One verb
+
+```bash
+giro implement <target>
+```
+
+The router reads the target and picks the level. An Issue runs the Issue loop. A Spec runs the Spec loop — planned into Issues first if it has none. No second entrypoint, no mode flags. When a run ends `needs-human`, you answer (edit the Issue, decide the question) and run the same command again: re-invoking *is* the answer, and the budget resets.
+
+Merging `giro/<spec>` into your main line stays your hand, always.
+
+## Gates
+
+A gate is anything that ends in `{ "verdict": "pass" | "fail", "findings": [...] }`.
+
+- **command** — a shell command; exit 0 is pass. Deterministic and cheap.
+- **prompt** — a rubric applied by a fresh, blind judge context.
+- **skill** — a full SKILL.md procedure, same envelope at the end.
+
+Judges start blind on every attempt; findings feed the next *actor*, never the next judge. A judge that can't produce the envelope gets one retry, then **fails closed**. All gates run to completion — the next attempt sees every finding, not just the first.
+
+## State
+
+Specs and Issues are markdown with tiny frontmatter, committed beside the code:
+
+```
+docs/specs/<slug>/SPEC.md            state: draft | active | done | needs-human
+docs/specs/<slug>/issues/NN-slug.md  state: ready | in-progress | done | needs-human | wontfix
+```
+
+The store is the durable checkpoint: kill the engine at any point and `giro implement` resumes from exactly where the markdown says. Every attempt appends its story to the Issue file — the history is readable, not buried in a log.
+
+## Quickstart
+
+```bash
+uv tool install giro   # not yet published — for now: uv sync && uv run giro
+cd your-project
+giro init              # writes giro.toml — set your [verify] gates
+giro implement <spec>  # go
+```
+
+Exit codes are the contract: `0` proof, `2` needs-human, `1` error. CI and chat agents read them the same way.
+
+## Layout
+
+- [`docs/design.md`](docs/design.md) — the founding design: vocabulary, state machines, envelopes, loop contracts, decisions.
+- [`skills/`](skills/) — the LLM touchpoints: what workers, judges, and chat doorways are told.
+- [`src/giro/`](src/giro/) — the engine. `loops.py` is the heart.
+
+## Roadmap
+
+- **M0 — engine core** *(this)*: guarded loops, gates, store, CLI; proven end-to-end with a fake driver.
+- **M1 — live driver**: `claude -p` worker/judge/planner contexts; first real Spec shipped by the machine.
+- **M2 — parallel waves**: `concurrency > 1`, isolated worktrees, integration branch + re-verify.
+- **M3 — the doorway**: `/giro` chat skill, escalation console, one-shot install (CLI + skills).
+
+MIT — see [LICENSE](LICENSE).

giro-0.0.1/docs/design.md

@@ -0,0 +1,112 @@
+# giro — founding design
+
+This is the contract the engine is built against. The prose vision lives in the [README](../README.md); this document is the part you can hold the code to.
+
+## Vocabulary
+
+- **Spec** — forward-looking intent for one shippable feature. `docs/specs/<slug>/SPEC.md`.
+- **Issue** — one bounded, demoable slice of a Spec. `docs/specs/<slug>/issues/NN-slug.md`.
+- **Gate** — a verification unit ending in a verdict envelope. Kinds: `command`, `prompt`, `skill`.
+- **Verify** — the Issue-level gate set (`[verify]` in giro.toml).
+- **Validate** — the Spec-level gate set (`[validate]`). It is the Spec loop's verifier, not a separate stage.
+- **Worker** — a fresh LLM context that implements one Issue. Edits files; never commits.
+- **Judge** — a fresh, blind LLM context that applies one prompt/skill gate.
+- **Planner** — a fresh LLM context that decomposes a Spec into Issues. Returns a plan; the engine writes the files.
+- **Driver** — how a context is spawned: `claude`, `agy`, `codex`, `gemini` (plus `FakeDriver` in tests). One contract: prompt in, JSON envelope out; CLI failures surface the CLI's own message and fail the attempt, never a bare exit code.
+- **Finding** — one structured problem `{summary, detail?, location?, gate}`. Findings feed the next actor.
+- **Budget** — the bound that turns "loop until green" into "loop until green or ask."
+- **needs-human** — the only non-proof exit. Both state machines land here when a budget is spent.
+
+## The topology rule
+
+**Control never crosses an LLM. Content always does.**
+
+The engine (deterministic Python) owns: state transitions, attempt counting, gate execution, wave scheduling, commits, escalation. LLM contexts own: implementing, planning, judging. The engine's view of any context is identical — *spawn via driver, wait, parse envelope*. A context that cannot produce its envelope is a failed attempt or a failed gate (fail closed), never a shrug.
+
+Corollaries:
+
+- Workers never run `git commit`; the engine commits. The engine's own bookkeeping (claim, state moves) is committed **separately** from worker output, so "worker produced no changes" is detectable.
+- Judges start blind on every attempt — no memory of prior rounds. Findings feed the next *actor*, never the next judge.
+- Workers never edit `docs/specs/` — state belongs to the engine.
+
+## State machines
+
+Stored frontmatter is exactly what the loops branch on. `blocked` is computed from `blocked_by` at scheduling time, never stored.
+
+### Issue — `state:` in frontmatter, plus `blocked_by: []`, `attempts: N`
+
+| From | To | Actor | When |
+|---|---|---|---|
+| ready | in-progress | engine | attempt starts (claim committed first) |
+| in-progress | done | engine | worker completed + all Verify gates green |
+| in-progress | ready | engine | attempt failed, budget remains (findings carried) |
+| in-progress | needs-human | engine | budget spent, or worker escalated |
+| needs-human | ready | human | re-invoking `giro implement` on the issue *is* the answer; attempts reset |
+| any | wontfix | human | by editing the file; the engine never sets it |
+
+Terminal for scheduling: `done`, `wontfix`.
+
+### Spec — `state:` in frontmatter, plus `base: <sha>`, `gap_cycles: N`
+
+| From | To | Actor | When |
+|---|---|---|---|
+| draft | active | engine | first `giro implement <slug>` |
+| active | done | engine | all Issues terminal + all Validate gates green |
+| active | needs-human | engine | any Issue stuck needs-human, or validate budget spent |
+| needs-human | active | human | re-invoking `giro implement` *is* the answer |
+
+`done` means: **Validate passed; the human merges `giro/<slug>`.** There is no `shipped` state, no Feature record, no auto-merge. The machine's job ends where your branch review begins.
+
+## Envelopes
+
+Every context ends with exactly one JSON object. Schemas in [`envelope.py`](../src/giro/envelope.py):
+
+```json
+// worker            // judge (gate verdict)        // planner
+{ "outcome": "completed | needs-human | failed",
+  "summary": "…",    { "verdict": "pass | fail",    { "issues": [ { "title", "body",
+  "notes": "…" }       "findings": [ {"summary",        "blocked_by": [1] } ] }
+                         "detail", "location"} ] }
+```
+
+Parsing is strict and fails closed: a malformed judge envelope gets one retry (with the validation error appended), then the gate fails with a `failed closed` finding. A malformed worker envelope consumes the attempt.
+
+## The loops
+
+Both loops instantiate one primitive — actor → verifier → proof | escalation — with these bindings:
+
+| Clause | Issue loop | Spec loop |
+|---|---|---|
+| objective | Issue `done` | Spec `done` |
+| actor | worker context | wave of Issue loops |
+| verifier | `[verify]` gates | `[validate]` gates |
+| findings feed | next worker attempt | gap Issues → next wave |
+| budget | `issue_attempts` per Issue | `validate_cycles` gap cycles |
+| escalation | Issue `needs-human` | Spec `needs-human` |
+| memory | Issue frontmatter + attempt log | Spec frontmatter + gap Issues |
+
+Gates run to completion — every gate runs, every finding is collected, so an attempt sees the whole picture. Command gates run first in config order; nothing short-circuits the evidence.
+
+Waves: the frontier is every `ready` Issue whose `blocked_by` are all terminal. Issues in a wave are assumed scope-disjoint; collisions surface in Verify. At `concurrency = 1` (all of M0) the frontier runs sequentially — still one fresh context per attempt, never the invoking chat session.
+
+## Decisions (locked)
+
+1. **CLI owns the loop; skills are the touchpoints** (gnhf-shaped, skills readable). No LLM in the control path.
+2. **One verb.** `giro implement <target>`, routed by what the target is. No mode flags, no second entrypoint.
+3. **Empty Spec → planner context**, engine writes the Issue files (may be a single Issue). No synthetic in-memory units.
+4. **`done` = Validate passed + human merges the branch.** No ship stage, no Feature records, no auto-merge to main.
+5. **Local vs parallel is one code path** — `concurrency` decides; worktree isolation arrives at M2 without a topology change.
+6. **Fail closed everywhere.** Malformed envelope = failed attempt/gate. Dirty tree = refuse to run.
+7. **Re-invocation is the human answer.** `needs-human` + `giro implement` again → state resets, budget resets.
+8. **Markdown is the memory.** Kill the engine anywhere; the store resumes it. Attempt history lives in the Issue file, human-readable.
+
+## Non-goals
+
+Bug intake/triage queues, tracker mirrors (GitHub/Linear sync), Feature documentation, merge-to-main automation, multi-repo orchestration. Some may return later; none are core.
+
+## Milestones
+
+- **M0 — engine core** (done): everything above, proven by `tests/` against `FakeDriver`.
+- **M1 — live driver**: harden `ClaudeDriver` (permissions, sandboxing, structured output), first real Spec end-to-end.
+- **M2 — parallel waves**: worktrees per worker, integration branch, integrated re-Verify after merge.
+- **M3 — the doorway**: `/giro` chat skill + escalation console; one-shot install placing CLI + skills together.

giro-0.0.1/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "giro"
+version = "0.0.1"
+description = "Guarded-loop engine for AI coding agents: Specs become verified work through bounded loops that end in proof or escalation, never a silent stop."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Piergiuseppe Mallozzi" }]
+keywords = ["agents", "ai", "automation", "verification", "tdd", "loops"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development",
+]
+
+[project.scripts]
+giro = "giro.cli:main"
+
+[project.urls]
+Repository = "https://github.com/pierg/giro"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/giro"]
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

giro-0.0.1/skills/giro/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: giro
+description: Drive giro from a chat session — start guarded loops, relay progress, and help the human answer needs-human escalations. Use when the user asks to implement a Spec or Issue with giro, check giro status, or resolve a giro escalation.
+---
+
+# giro — the doorway
+
+giro is a deterministic loop engine: it turns Specs and Issues under `docs/specs/` into verified work on a `giro/<slug>` branch, exiting only through proof or `needs-human`. You do not implement anything yourself — the engine spawns fresh worker contexts for that. Your job is the conversation around the machine.
+
+## Commands
+
+```bash
+giro status                 # spec and issue states
+giro implement <target>     # spec slug, issue id, or slug/issue-id — starts or resumes the loop
+giro verify                 # run the [verify] gate set once, on demand
+giro init                   # first-time setup: writes giro.toml
+```
+
+Exit codes: `0` proof, `2` needs-human, `1` error.
+
+## How to behave
+
+1. **Starting work.** Resolve what the user wants into one target (`giro status` helps), then run `giro implement <target>` and relay the report: outcome, per-issue states, and where the work landed (`giro/<slug>` branch).
+2. **On `needs-human` (exit 2).** This is the escalation console — your main job. Open the Issue file, read its attempt log (the trailing `## Attempt N` / `## Budget exhausted` sections), and present the blocker plainly. Discuss it with the user. Their answer usually lands as an edit to the Issue body (sharper acceptance criteria, the decision made explicit). Then run the same `giro implement` again — **re-invoking is the answer**; the engine resets the budget.
+3. **On proof (exit 0).** Tell the user what is on `giro/<slug>` and remind them the merge into their main line is theirs to make. Never merge it yourself.
+4. **Planning.** If there is no Spec yet, help the user write `docs/specs/<slug>/SPEC.md` conversationally before reaching for the engine. A Spec with no Issues is fine — the engine plans it.
+
+## Hard rules
+
+- Never edit Issue/Spec `state:` frontmatter or attempt logs — state belongs to the engine; you edit *bodies* when the user answers an escalation.
+- Never bypass the engine by implementing Issues in this chat context.
+- Never merge `giro/<slug>` into the main branch.

giro-0.0.1/skills/implement/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: implement
+description: Discipline for a giro worker context implementing one Issue. Injected into every worker task packet by the engine; edit this file to tune how workers in this project behave.
+---
+
+# Implement — worker discipline
+
+You are implementing one Issue. The engine chose it, will commit your work, will run the project's gates, and will decide what happens next. Your job is only the change itself.
+
+## Discipline
+
+1. **Read before writing.** Understand the Issue's acceptance criteria and the surrounding code before editing. Match the codebase's existing style, naming, and idiom.
+2. **Test-first.** Write the smallest failing test that captures the Issue's behavior, watch it fail, make it pass, then clean up. Run only the tests you author — the project-wide gate is the engine's job, not yours.
+3. **Stay on the slice.** Implement this Issue, nothing adjacent. If you notice unrelated problems, mention them in your envelope `notes` — do not fix them.
+4. **Findings first.** If the task packet carries findings from a previous attempt, fix those before anything else — they are why the last attempt failed.
+
+## Hard rules
+
+- Never run `git commit`, `git push`, or anything under `.git` — the engine owns version control.
+- Never edit files under `docs/specs/` — Spec and Issue state belongs to the engine.
+- Never weaken, skip, or delete an existing test to get to green.
+- If the Issue cannot be done as written — ambiguous, contradictory, or requiring a decision that is not yours — stop and return `needs-human` with the question in `summary`. A good question beats a wrong guess.

giro-0.0.1/src/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-0.0.1/src/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())