# ladder

**Constraints and capabilities on one ladder, as an iii worker.** A constraint
is what an agent may not do; a capability is what it may. They are the same
shape: a rule with a rung, the mechanism that carries it. The ladder refuses a
call in the rule's own words, from the harness's pre-call hook, and serves the
ladder as data: what is carried where, how much of it is measured rather than
hoped for, and what moving one would do. It needs iii 0.26.0 or newer, because
it speaks observers.

```
iii call compose::add worker=ladder
```

## The six rungs

| Rung | Carried by | What it can see |
|---|---|---|
| 0 | prose in the charter | nothing. It asks |
| 1 | the grant: what the phase may call | function ids, before any call |
| 2 | a hook on the tool call | the arguments, before the write lands |
| 3 | a callback inside the turn | the call, and it may hold it for a person |
| 4 | the delivery gate | the finished diff, before the commit |
| 5 | CI | the merged tree, after everybody left |

**A rung is a place, not a strictness.** Rung 3 sees a function call, and a
shell command is one call whose contents it does not read. Rung 4 sees the diff
and never sees the call. Neither can see what the other sees, so a rule that
matters names both.

**Climbing costs something.** Rung 0 is free and enforces nothing. Rung 2 needs
a predicate somebody writes and maintains. Pick the cheapest rung that can
actually see the thing your rule is about.

## A primitive is two files with one name

`team/rules/no-secrets.md` is the rule. `team/rules/no-secrets.py` is the
predicate. The `.md` alone gives you rung 0. Add the `.py` and the same
primitive turns mechanical:

- **kind** comes from the directory. `rules/` is a rule, `skills/` is a skill.
- **side** comes from the kind. A rule constrains; a skill is a capability.
- **layer** is the one thing you declare: `project`, `team`, or `org`.
- **rung** follows from the layer and from whether a script exists beside it.

A rule's script may also be a **function id on the bus**, so a check can be
written in any language and run by whatever worker hosts it.

## Configuration

| Variable | Default | What it is |
|---|---|---|
| `LADDER_REPO` | the working directory | the repository whose `.agents/` the ladder reads |
| `LADDER_HOME` | the worker's own directory | where shipped (team/org) primitives live |
| `III_URL` | `ws://localhost:49134` | the engine |

The repository's own `.agents/settings.json` `permissions.deny` entries are
honoured first, at rung 2, before any team rule: a project is never refused by
a team rule for something it had already forbidden itself. Pass `permissions`
in a call's payload for a caller that can see the settings file when the worker
cannot.

**Run it as a host process when it must read a target repository.** A sandboxed
package worker mounts only its own source; the target repository does not exist
inside that sandbox, and a ladder that reads a settings file that is not there
reports a repository with no permissions — which looks exactly like permissions
that are not enforced. ghola therefore runs its own copy with `path://` in
`worker-compose.yaml`, and installs this registry worker where the repository
it judges is the project's own.

## Functions

| Function | What it does |
|---|---|
| `ladder::gate` | the `harness::hook::on-pre-call` observer: refuses or holds a call that breaks a constraint, in the rule's own words |
| `ladder::list` | everything on the ladder, both sides, with rungs, catches, and `withheld` |
| `ladder::explain` | one primitive, and what each rung it names can actually see |
| `ladder::evaluate` | ask about a proposed write at a given rung, without being a turn |
| `ladder::move` | promote, demote, carry, drop or remove a primitive. Commits nothing |
| `ladder::add` | scaffold a new primitive on the rung its level and script imply |
| `ladder::refused` | the refusal event source. Private, observable: observe it, only this worker fires it |

```
iii call ladder::list --json '{"repo":"/path/to/repo"}'
iii call ladder::evaluate --json '{"repo":"...","function_id":"shell::exec","arguments":{"command":"rm -rf /"},"rung":2}'
worker.observe("ladder::refused", "audit::on-refusal")
```

`ladder::list` reports `measured_share`: the fraction of primitives carried
somewhere a machine records what they caught. It makes the gap visible and
counted; it does not make feedforward reliable.

## License

MIT. Repository: [tacoda/ghola](https://github.com/tacoda/ghola).
