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).
