Trust a recurring spec
Let the runs of a recurring spec land on main, through a mechanical lander with strict guards
A recurring spec leaves the work of each run on its
lane's branch. When you trust the spec, each run that passes its judgement
lands on main by itself. A mechanical lander does the landing. No model
takes part, so a session can never push an empty or a wrong branch onto
main.
Trust is off for every spec. Only you turn it on, in the Hub, one spec at a time. Each change to the run plan turns it off again.
Before you trust a spec
Set the landing settings of the spec first. Trust names them when it asks you to confirm.
| Setting | Default | Meaning |
|---|---|---|
| Verify step | empty | The commands that must pass on the exact commit, one command on each line. Each command runs with no shell, in the lander's worktree, and must exit 0. With no verify step, nothing lands |
| Delete limit | 0 | The most files that a landing can delete. A cleanup that deletes files needs a higher limit |
| Window | empty | When a landing can occur, as 02:00-05:00, in the zone of the computer. A window can cross midnight. Empty: at any time |
| Quiet minutes | 15 | Inside the window, the lander waits until main got no new commit for this many minutes |
| Land mode | push |
push pushes to origin. local moves the local default branch, for a project with no remote |
- Open the spec on the Specs tab.
- In the Landing part of the Recurring panel, type the verify step,
for example
kiln buildandkiln test --profile gateon two lines. - Push the save button beside the verify step.
- Set the delete limit, the window, the quiet minutes and the land mode. Each one is written when you leave its field.
The verify step, the template, the budget and the delete limit are the run plan. A change to one of them, or to a probe, clears trust.
Turn trust on
- Tick Trust: land its runs on main in the recurring panel.
- Read the confirmation. It names what the lander does and the guards that it passes.
- Confirm.
The spec shows the badge "lands on main", in the warning color, in the tree and in its panel.
Trust asks each time, and it runs only on the Hub that holds the spec
database. A call through the Trove door
cannot trust a spec: the door does not have the scope spec.trust, and it
cannot confirm.
What the lander does
The lander works in a worktree of its own. It never touches your checkout, never deletes a branch, never forces a push and never resets a branch. Each step is a guard. If a guard refuses, the landing stops, every branch stays as it was, and the run records the guard and the reason.
| Guard | Step | Refuses when |
|---|---|---|
| L1 | The kill switch of the project and of the Hub | One of them is on |
| L2 | The window, then the quiet minutes | The time is outside the window. Inside it, the lander waits for the quiet minutes until the window ends |
| L3 | Fetch, then a new detached worktree at origin/main |
The fetch fails |
| L4 | The commits of the run on top of main: a fast-forward, else a rebase |
The rebase has a conflict |
| L5 | The diff against main |
The diff is empty, or it deletes more files than the delete limit |
| L6 | The verify step, on the exact commit | A command fails, or the spec has no verify step |
| L7 | The probes, on the exact commit | The judgement does not pass on that commit |
| L8 | One commit, recurring(<code>): run <n>, <probe> <before> → <after>, with no agent attribution |
The commit fails |
| L9 | Fetch again | main moved during the landing |
| L10 | The push, never forced | Git refuses the push |
The landed commit has the tree that L7 measured. So the value that L7 measured is the landed value of the run, and the drift of the next run uses it.
When main moves
A conflict at L4, a move of main at L9 or a refused push at L10 ends one
attempt, not the run. The lander tries two more times, each time with a new
fetch, rebase, verify and measure. After the third attempt, the run ends as
landing-deferred. Its commits stay on the lane's branch. The next run works
on that branch, so its landing carries the deferred work too. A failed landing
never turns the switch off.
Land one run by hand
You can land one run that passed its judgement, also when the spec is not trusted. The run goes through the same guards.
{"task": "spec.run.land", "args": {"key": "r0123456789"}}
The task asks each time, and it runs only on this Hub. spec.run.get tells
you how the landing ended.
Pause every landing
The kill switch pauses the landings of one project, or of the whole Hub. A landing that is paused refuses at L1, and the reason that you type is the reason of the refusal.
{"task": "trove.land.pause", "args": {"reason": "release freeze"}}
{"task": "trove.land.pause", "args": {"project": "octomy", "reason": "main is red"}}
{"task": "trove.land.resume", "args": {}}
With no project, the switch is the switch of the whole Hub. Each call asks
first.
Turn trust off
Clear Trust: land its runs on main in the panel. It does not ask, because nothing lands after it. The runs stay on their lanes. Each setting stays, and you can trust the spec again later.