Docs · Kanban loops
docs/KANBAN-LOOPS.md in the ZoeyOS source. Last verified 2026-10-08. State current, fixed against the running house on 2026-10-08.Kanban loops: green, reframe, retreat
A repeat is not retried. It is reframed, and the frame goes back through the decomposer. Two frames that both fail are a ruling for Zoey, not a third frame.
The one elemental fix
The decomposer reads exactly two things about a card: its title and its body. Not the comments, not the runs, not the failure count. So a card that fails four times the same way is, to the decomposer, the same card it was on day one. The dispatcher retries it, trips the breaker, and the card sits blocked with a "gave up" event nobody reads.
The fix is a new body, not a new retry: a frame written one level up becomes the body of a fresh triage card, and the decomposer does what it already does well, cutting it into children from that spec.
Why this is enough for nearly everything: the failure classes seen are the harness (a VRAM floor, the wrong interpreter, a sandbox that takes one encoding), the wrong lane (no image tool, no root shell), the wrong question (a package name that is not the project), and the world (a feed that fails at one hour and not at another). None of those yield to the same steps again; all of them yield to the six questions below. What it does not cover is physical: hands, a body, a cable. That exit lands as "needs a human", never as an owner's decision about software.
The frame: six answers, under 220 words
- What was being attempted, in one sentence?
- Which failure class repeated (same error, same step)?
- What assumption did every attempt share?
- Two or three framings one level up that drop that assumption.
- The smallest test that tells those framings apart.
- Is any part of this hands or a body in the room? If not: software.
The worker writes it on the second failure of the same shape, before blocking. If no worker did, the loop asks the reframer model; if that is down, it posts a mechanical frame that still carries the six questions.
Loop 1: green
A try needs a green, and a green needs a queue. Improvement and architect ideas are filed blocked with the question "Green this try?". That block is the Decide queue; Zoey's watch wakes on it. Her first word rules:
| try | cuts the try as a triage card (auto-decompose), archives the gate card |
|---|---|
| park | archives the gate card; her words stay on it. A park is sticky on every card. |
| later <date> | a dated park, back on the queue at the date |
| done | closes the card as done from any status, in one pass (added 2026-09-21: a park never had a close verb) |
| archive | retires the card; it never means the work landed |
| nothing | re-blocked: an unblock without a ruling is not a ruling |
Loop 2: reframe
Every 20 minutes, for a card with three repeated failures, a sticky breaker park, or a worker's frame on a blocked card:
- frame: the worker's, else the model's, else mechanical
- cut: a new triage card whose body is the frame, carrying its generation and its source
- park: the source card is parked "superseded by" so it stops burning
- retreat: at the second generation the loop does not cut a third. It blocks the card with both frames as the question. That is generation three: Zoey, Chief of Staff. She rules try (a new frame), park, or hands.
Budget: one cut a tick. Nothing is deleted; archive is the only terminal verb and keeps the thread. A frame whose children are all done completes itself; a frame with an archived child is retired, not completed, because a frame's done closes its source as delivered.
A failure is classified before anything acts on it
Validated on 496 real failed runs before it was wired:
| harness | 378, 76.2 %: spawn refused 204, turn budget 109, process gone 53, skill pin 12 |
|---|---|
| real | 78, 15.7 % |
| verb | 40, 8.1 %: exited clean with no terminal call |
Three quarters of every failure on the board was never the card's fault. A harness fault is retried with a wake and never framed, because there is nothing in the card to reframe. One line per card and cause, not per run. Silence is never "real".
The board's readers
The jam was never a cap or a missing brain: it was blocked cards with no reader. Each class of stuck card got a reader already in the house.
| Ada | ownerless blocks: one batch card, she fans the reads to children and writes one verb per card |
|---|---|
| Zoey | rules every card on the Decide queue per wake, oldest first; a dated park is her alarm |
| Vera | every finished build gets one review card: pass, or fail plus one fix card, never her own fix |
| Judge | one call, one verb, on a card a detector already diagnosed |
| the gate | eight mechanical checks every two minutes, no model: assignee, verb wall, render window, ownerless, review, balance, caps, salad |
Two watchers on the lane, not four: the board gate (two minutes, mechanical) and the loop (twenty minutes, the model's work). Never a watcher that holds the board's dispatch lock while it waits.
Retreat spots
Every loop has an off switch and a dial: the tick can be stopped whole, reframes can be turned off leaving the green loop, the generation count before Zoey can be changed, and a hand's unblock without a verdict counts as "try" so the loop never enforces a ruler's older word against her own newer act.