Building — the loop that drives a run

▶ RUN THIS FIRST — do not summarise this file

Your first output is a tool call, not a plan. Narrating the pipeline reads like a clean run and leaves defects behind it. A run that left no receipt did not happen; loading these instructions is not running them.

You drive the run, in this session. What stands between you and a claim of "done" is five mechanisms and nothing else: the receipt init run writes, the gate resolver, the T0 witness that runs a scope's fixtures and re-hashes what it cites, the write fence that refuses a worker's write outside its order's substrate, and the dispatch receipts that name which agent ran. Everything else in this file is your own discipline, and no script checks it for you — so after every action, read the files again instead of remembering them.

Every kernel command below is run exactly as written, on ONE line (a grant matches a single-line command; a \-continued one comes back "requires approval"). If a kernel command comes back "requires approval", stop and say so — the scripts need a one-time grant (npx shapeup-sdlc init); never route around it or hand-build the feature.

Rules

1. ASK, DON'T ASSUME. Collect the intake explicitly (resources/intake.md); put every gate to the PO with a recommendation first.
2. SIMPLEST FIRST. The smallest change that satisfies the pitch.
3. NON-REGRESSION. Never touch what already works.
4. A CLAIM NAMES ITS FILE. Every "done", "green" or "shipped" you write cites the file or kernel output it came from.

Step 0 — open the run

Resolve the intake and open it as resources/intake.md says: language check (a non-English pitch is made English by you, right there: <name>.en.md and the glossary, and the run opens on the copy), the L0 collect-list, init run — with every switch the operator typed, because it writes the launch record in the same act as the receipt and refuses a model below the floor (exit 3 = a run is already open, or the worker roster is missing: the record is kept and the loop continues from the files), the shared project-profile.md, and the L0 gate.

Where the facts are

K is node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs". <run> is .shapeup/<slug>/, <spec> is shapeup/<slug>/.

The phases — do the first one whose condition holds, then read the files again

A gate is crossed with K gate --resolve <GATE> --slug <slug> [--round R] [--verdict V] --preset <set> (exit 0 = crossed; 4 = ask the PO and re-run with --answer <decision>; 5 = the set aborts: close the run as aborted and stop). <set> is the launch record's answers.

A plan substep is done here, in this session, with no sub-agent: write the substep's order (resources/orders.md, operation plan, worker: "building"), open it with K order open, write only what the substep produces (resources/plan.md and its plan-*.md siblings say what and how), then write results/plan-<step>.json yourself (the order's own path, so it is writable though results are frozen) and read the artifact back, before you write the next order. The order's substrate is the fence: while it is open, the staged pitch, the receipt and the other orders are frozen.

A dispatch

The same five moves for every worker. resources/orders.md has the order for each operation.

1. Write the order to <run>/orders/<stem>.json from the template for the operation. It carries the substrate (the globs the worker may write, copied from the scope contract for a build) and the payload the worker needs, as paths where a path will do.
2. Open it: K order open --slug <slug> --order "<run>/orders/<stem>.json". This stamps the order's time and names the live order to the fence; without it the fence allows every write.
3. Spawn the agent shapeup-sdlc-plugin:<worker> with the prompt --order "<run>/orders/<stem>.json" and one line of note, and pass the model the launch record names for the role: models.exec for orient and task-executor, models.eval for spec-evaluator, models.qa for qa-edge-hunter. The agent definitions say inherit, so a dispatch that carries no model runs on your session's model, whatever the record asked for. The dispatch is checked against the order schema before it leaves, and leaves a receipt naming the agent that ran, the model the call asked for and the model the host says ran. GATE L4 reads those receipts: an exec or eval worker that ran below the floor refuses ship, and a model other than the record's is written into the gate's row — say so in the ship report.
4. Read the result at <run>/results/<stem>.json: K verify envelope "<run>/results/<stem>.json" "${CLAUDE_PLUGIN_ROOT}/kernel/schemas/work-result.schema.json". Invalid, or absent, goes back once with the reason; a second failure is a phase that did not complete — name it and stop at that phase.
5. Apply it yourself: update the board's status: for the tasks the result closed, append each discovery to <run>/discovery/ledger.md, append the evaluator's verdict-ledger lines to <run>/evaluation/.verdicts-<target>.jsonl, and state what the result changed. Nobody else writes these.

Build a scope

For scope S in round R, attempt A (start at 1): dispatch task-executor with operation execute (round 1, or fix with the verdict's bugs on later rounds), whose substrate is the scope contract's allowed_file_substrate and shared_substrate. The worker runs K verify t0 "<spec>scopes/S.md" --round R --attempt A itself. After its result lands, run the same command yourself and read status from the JSON on stdout, never from the exit code (a kept red-but-improved attempt exits 1):

A scope that reaches attemptBudget attempts without a green is out of attempts: stop building it, record it as a proposal for GATE H, and go on. It never stops the round. Build a scope only after the scopes in its contract's depends_on are green. Two scopes build at once only when no path is writable by both (read the contracts' substrates); otherwise one at a time. Count an attempt from the dispatch receipts in <run>/receipts/dispatch.jsonl, not from your memory: a dispatch with no receipt did not run the shipped worker.

The breakers

maxRounds ends the run: after a failed round R = maxRounds, go to the census. attemptBudget ends one scope. Neither ends the run from outside — both route to GATE H, where the census compares what is green against the baseline and ships what works. A run killed from outside ships nothing.

Sub-commands

/ship with none runs the whole loop. A sub-command does one activity of it: plan (/scopes, /wire) — the planning substeps; stop (/hammer) — the census over the run in hand; retro (/retro, /retro --scan, /retro --research <stack>) — resources/retro.md, retro-scan.md, retro-research.md; intake <path>… (--check writes nothing) — the language gate alone, resources/intake.md §2.

Resume

/ship again over an open run is the resume (over a closed one, phase 0 reports the ending and stops): init run refuses and prints what is on disk, and you continue from the phase table, reading files and nothing else. A run closed without shipping is reopened by init run --force, which resolves every order nobody answered as abandoned before it writes.

Intake, language check and translation, profile, the launch record → resources/intake.md The order for each operation: substrate, payload, where each field comes from → resources/orders.md Planning: how a substep runs, requirements; the spec, wiring and scope formats → resources/plan.md and its plan-*.md siblings Which knowledge-base file is read where, and under what name a rule is filed → resources/guidance.md How to put a gate to the PO, and what to have read first → resources/gates.md What a round is; the attempt loop; why the loop stops where it does → resources/rounds.md The census, the baseline comparison, the cut list, the ship report (GATE H) → resources/stop.md After a ship: feedback, the retro gate, --scan, --research → resources/retro.md, retro-scan.md, retro-research.md