ladder
v0.1.0Constraints and capabilities on one ladder, as an iii worker. A constraint is what an agent may not do; each one names the rung that carries it, and the ladder refuses a call in the rule's own words from the harness's pre-call hook. Needs iii 0.26.0 or newer, because it speaks observers.
Install
iii trigger compose::add worker=ladder@0.1.0Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.
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=ladderThe 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, ororg. - 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/ladder.