<!-- voice-register: informational -->

# ghola

*You clone it. You teach it. It remembers.*

**A starter kit for agentic systems on [iii](https://iii.dev).** Clone it, point
it at a repository. A spec goes in, a pull request comes out, nothing merges
itself.

[iii](https://iii.dev) is the framework and the ecosystem doing the real work
here: the turn loop, the tools, worktrees, the forge client, the approval gate,
durable queues, the console. Read it on its own terms first, because everything
below is that, wired up.

There are two ways to build on it. You can add each worker when you need it,
which keeps you holding only the parts you understand, and for a distributed
system that is often the right call. Or you clone a kit that has already made
those choices. This is the second one, and what it gets you is a harness and a
factory already wired together:

- **The harness** constrains one turn. Six phases, each with its own model,
  thinking level, turn cap and tool grant. Four callbacks around the turn. The
  prompts it is actually asked. The ladder deciding what a rule refuses, in the
  rule's own words.
- **The factory** runs many turns to a diff. A stage graph where every transition
  is a durable queue message, so a crash resumes rather than restarts. A worktree
  per job with a claim that stops two racing. A delivery gate over the finished
  diff, then a pull request nothing can merge for you.

A harness with no factory is a well-behaved agent you cannot get work through. A
factory with no harness runs unattended and cannot tell you what it was allowed
to do. That split is also how the improve lane sorts its proposals.

**It works before you configure anything.** A fresh clone runs the whole
lifecycle on built-in defaults with an empty `settings/`. Changing it is a key in
a YAML file, or a Python file dropped into a named directory and found by its
filename, with no registration step and no import to add. `make config` prints
every effective value with the source that produced it, so a default is never a
magic number you go hunting for in the code.

**The rest of what a kit is for is management.** The workers would run without
any of it. `make` is one operator surface over all of them: `doctor` for what is
missing, `config` for what is set and where it came from, `pipeline` for the
stage graph before you pay for one, `status` for what is up, `audit` for whether
the record still verifies, `improve` for what went wrong and what would have
helped.

ghola composes twenty-six iii workers, five engine-owned ones and its own four,
declared in a single `worker-compose.yaml`, and adds the conventions that wire
them together. If a worker does it, ghola does not, which is why there is so little of
ghola to read.

Two of those workers are ghola's own and ship inside this repository: the
constraint and capability ladder at `workers/ghola-ladder`, and the append-only
record at `workers/ghola-audit`. One clone is the whole thing.

Both are also general enough to be worth having on their own, so each has an
upstream that is where it becomes a worker other projects install:
[ladder](https://github.com/tacoda/ladder) and
[audit-log](https://github.com/tacoda/audit-log). Point `LADDER` or `AUDITLOG` at
a checkout and it serves instead of the copy, because the seam is the function id
rather than an import. A starter kit whose best ideas are locked inside it is a
worse starter kit.

**Status: M8.** The whole lifecycle runs. A spec becomes a plan, a diff, a
proof, a review, a commit through your repository's own hook, and a pull
request. Comment on it and the job reworks. 675 tests, and the phased plan is in
[PLAN.md](PLAN.md).

**Start here:** [docs/ADOPTING.md](docs/ADOPTING.md) gets a pull request out of
a repository today. [docs/LIMITATIONS.md](docs/LIMITATIONS.md) says what this
does badly and what it refuses to do. Read that one first. It costs less.

## Usage

```
1. clone the repo          git clone … && cd ghola && make setup
2. add config and scripts  edit settings/, drop files in actions/
3. tell it to do work      make submit SPEC=specs/x.md REPO=../repo
```

Step 2 is optional. ghola runs on built-in defaults with an empty `settings/`,
which is what `make config` is for: it prints every effective setting tagged
with where it came from, so a default is never a magic number.
[examples/](examples/) holds two worked configurations at opposite ends of the
range.

Step 3 needs a repository named in `repos.local.toml`. The shortest version
needs no GitHub account at all:

```toml
[repos."/Users/you/code/scratch"]
forge = "local"     # no account, no token. The request is a file in the repo
base  = "main"
```

Once you have cloned this, it is yours. No upgrade path, and a starter kit works
that way on purpose rather than because I ran out of time.

## Running it

```
make setup      # checks your tools, makes the venv, writes .env. Run this first
make up         # engine, its workers, the ladder and ghola's callbacks
make status     # what is up
make down       # all of it, and wait for the ports to free

make submit SPEC=specs/x.md REPO=../some-repo SLUG=owner/name
make idea IDEA="a rough sentence" REPO=../some-repo   # refined into a spec first
make jobs       # every job, newest first
make turn PHASE=plan PROMPT="why is the queue slow?" WORKSPACE=../some-repo
make config     # the effective settings, and where each value came from
make models     # what the router can actually reach
make test       # 675 tests, seconds, no engine, no money
make help       # everything else
```

![make help: the targets grouped as getting started, running it, doing work,
improving it and checking it, with a dollar sign marking every target that sends
a paid turn](docs/img/terminal/01-help.png)

`make` is the whole operator surface, and the `$` column is there because a
target that spends money should say so before you run it. While a job is up, the
picture worth having open is the console:

![The iii console, chat on the left and a live trace panel on the right, listing
one traced session per phase for each job](docs/img/console/04-failed.png)

`make setup` writes `.env` for you; put your `ANTHROPIC_API_KEY` in it before
`make up`. The provider workers read their credentials from the **engine's**
environment, so an engine started without them serves a router with no models and
every turn fails at `router::provider::resolve` with nothing saying why.

`make doctor` checks your tools, the harness pin, your key and your `gh` login,
which is where the answer to "why did that fail" usually is.

Ports are 3131 (http), 3133 (console), 3132 (stream) and 49154 (worker manager),
off iii's stock numbers so a ghola engine runs beside another project's.

## What ghola does not write

The rule is that if a worker does it, ghola does not.

| Worker | What ghola therefore does not write |
|---|---|
| `harness` | the turn loop, transcript, retry, sub-agents, token budget |
| `shell` | every tool. It owns `coder::*` too: read, search, tree, edit, exec |
| `worktree` | worktree lifecycle, the claim that stops two jobs racing, `land` |
| `github` | the forge: typed `pr`, `issue`, `run`, with read-vs-mutate gating |
| `approval-gate` | the human-in-the-loop hold, and its pending inbox |
| `eval` | A/B evaluation, its durable reports, and its console page |
| `directory` | the charter surfaces: skills, prompts, system prompts |
| `state`, `queue`, `cron`, `http`, `console` | the store, durable topics, scheduling, the surfaces |

**ghola registers no tools a turn can call.** What is left is the stage graph and
the briefs: which base ref, what happens in what order, when to land, and what
the pull request says.

The two workers it does write are the exception that proves the rule. The ladder
registers seven functions and the record registers six, and not one of them is in
any phase's grant: they serve the factory, the policy callbacks and you, never a
model mid-turn. So a phase's tools still all belong to a stock iii worker.

| ghola's own worker | Serves | Upstream |
|---|---|---|
| `workers/ghola-ladder` | `ladder::list`, `evaluate`, `explain`, `move`, `add`, `gate`, `refused` | [tacoda/ladder](https://github.com/tacoda/ladder) |
| `workers/ghola-audit` | `audit::append`, `read`, `verify`, `summary`, `tally`, `recorded` | [tacoda/audit-log](https://github.com/tacoda/audit-log) |

Each ships here so one clone is the whole thing, and each stays swappable for its
upstream because the seam is the function id: `make up LADDER=../ladder` changes
the provider and no call site.

A *forge* is whoever hosts your code and receives the pull request. Which one
you use is a setting rather than a fork. `github` and `local` ship, and a third
is a file in `forges/`. `local` is no forge at all, and the shortest path to
seeing this work.

## The idea

A constraint has a **rung**: the mechanism that carries it.

```
0  prose        stated in the rules, and nothing enforces it
1  tool grant   the phase was never handed the tool
2  hook         the repository's own hook refuses
3  in-turn      a callback refuses the call before the target runs
4  stage gate   the delivery gate, over the finished diff
5  CI           out of reach of both the agent and the factory
```

Each rung puts the rule further out of reach of what it constrains. It is served
by the ladder worker in `workers/ghola-ladder`, which also carries capabilities on
a second ladder joined to this one at the grant, and the whole
promote/demote/add/remove lifecycle.

```bash
iii trigger ladder::list
iii trigger ladder::move --json '{"id":"no-secrets","move":"carry","at":"delivery"}'
```

Everything a team would want to change is configuration:

| What differs between teams | Where |
|---|---|
| the flow of work in the factory | `settings/pipeline.yaml` |
| the development process in the harness | `settings/phases.yaml`, `prompts/` |
| how much a person watches | `settings/oversight.yaml` |
| project specifics | the target repo's own `AGENTS.md` and `.agents/` |

## Oversight is a dial, not a switch

"Dark factory" is a useful phrase and a bad setting. Nobody wants a system where
no human sees anything, and nobody wants to approve every read either.

| level | a person answers | refuses without asking |
|---|---|---|
| `manual` | every call | nothing |
| `attended` | every write | reads run |
| `supervised` | only what a rule marks `ask` | the ladder, deterministically |
| `dark` | nothing | the ladder, and `ask` degrades to refuse |

**`ask` never becomes `allow`** at any level. An unattended factory reading "ask"
as "yes" has answered a question nobody put. Default is `supervised`, and a stage
may override it because `run` and `review` want different answers.

Extension is two mechanisms: drop a Python file in `actions/`, `guards/` or
`predicates/` and it is found by filename, or name any function id on the bus and
write it in whatever language you like.

## It reads its own record

```
make improve REPO=../some-repo   # what went wrong, and what would have helped
make proposals                   # what it staged
make accept RUN=abc123 N=0       # one proposal becomes a spec in specs/
```

The evidence is the audit log and the job records, not anyone's memory of the
week: a refusal, a revision, a question the spec did not answer, a check that
objected. Every proposal names the jobs it came from, and **one that cannot be
traced to evidence is dropped rather than repaired**. A clean record produces no
proposals, because a lane that always finds three things is a lane nobody
believes by the third time.

**Nothing is applied.** Accepting writes a spec into `specs/`, and that spec goes
through the same pipeline and the same pull request as any other work. The one
exception is a move on the ladder — a promotion, a demotion or a carry — which is
a rung in a file, handed to `ladder::move`. The ladder commits nothing either.
Nothing that takes enforcement away is applied this way. Otherwise the lane that
proposes changes to the charter would be the single thing here escaping the gate
everything else goes through.

## Documentation

| Page | Read it when |
|---|---|
| [docs/ADOPTING.md](docs/ADOPTING.md) | you want a pull request out of a repository today |
| [docs/GUIDE.md](docs/GUIDE.md) | you want the walkthrough, part by part |
| [docs/LADDER.md](docs/LADDER.md) | you are deciding where a rule belongs |
| [docs/CUSTOMIZING.md](docs/CUSTOMIZING.md) | you want to change something and need to know where it lives |
| [docs/EVALS.md](docs/EVALS.md) | you are about to edit a prompt |
| [docs/LIMITATIONS.md](docs/LIMITATIONS.md) | before any of it |
| [ROADMAP.md](ROADMAP.md) | you want to know which of those gaps is being worked on |

## Requirements

iii 0.23.0, Python 3.11+, `git`, and an authenticated `gh`. `worker-compose.yaml`
pins `harness` at 1.8.7, and that pin is load-bearing: on 1.8.7 a `pre-trigger` hook's
`deny` is honored, and on 1.8.1 it was ignored and the call ran anyway. A ladder
mounted on 1.8.1 looks wired and enforces nothing.

## License

MIT. See [LICENSE](LICENSE).
