rune/docs/factory-verification-ladder.md

FACTORY VERIFICATION LADDER (binding, 2026-10-11)

Every dichotomy port landing MUST pass all six layers before it counts as FULL. The ladder is the anti-slop core: generation is cheap, verification is what transfers reliability.

The six layers (in order)

1. Existence. The commit SHA is on gitea/master; the diff touches the files claimed. Catches fabrication.
2. Green in MY checkout. Battery re-run fresh (Go tests / cargo test / clippy / vet / gofmt). Must pass on the reviewer's machine, not just the agent's. Catches environment artifacts.
3. Truth consumed, not self-generated. The test reads the frozen truth file. Then: regenerate truth from the live oracle independently and byte-compare against the frozen file. Catches self-consistent misreads (agent + battery agree, oracle disagrees) — the most dangerous failure.
4. Live parity re-run. Port vs live oracle on truth inputs, 100%. Catches stale-library and PYTHONPATH artifacts.
5. Python surface intact. Module's existing suite green, both with delegation live and oracle pinned (RUNE_*_CORE=python). Catches wiring regressions and collateral damage.
6. Phase B real (v2). Battery green after the improvement commit; the improvements are genuine language advantages (enums, exhaustive match, iterators, Result, zero-copy, lifetimes / goroutines, interfaces, compile-time safety), not cosmetic churn. Read the diff.

Limits of the ladder

Parity proves faithful translation, NOT original correctness. Oracle bugs need architectural judgment — escalate per the bug policy (rare, to #2479, work keeps flowing).

Throughput law

Verification scales linearly with landings; reviewer throughput is the gate. Spawn rate must not exceed verification rate. Backlog of unverified landings is a stop-spawning signal, not a queue to admire.

Factory workflow law (continuous-flow, 2026-10-11)

On every agent completion notification, the coordinator does exactly three things, in order: (1) verify the landing through the six+1 layer ladder, (2) update the count, (3) run scripts/factory_spawn_gate.sh — if ALLOW, spawn the next queued module into a fresh worktree.

Wave-thinking is the anti-pattern. Waves create dead time: 11 agents porting while the 12th lands means 11 worktrees idle until the wave drains. Continuous flow keeps every worktree occupied, the verification gate never starves, and the spawn gate (factory_spawn_gate.sh) enforces the limits deterministically — agent count and verification backlog never rely on coordinator cognition.

The spawn gate answers ONE question: may a new agent spawn now? Limits: max 12 active, max 3 unverified landings. The gate is law — the coordinator does not override it from feel.

NO-REPORT LAW (operational, 2026-10-12)

The coordinator does NOT report landings, counts, or progress to Nick between waves. Reporting interrupts autonomy — the coordinator's job is to keep the factory running, not narrate it.

What replaces reporting:

• The audit instrument (dichotomy_audit.py) IS the progress report — Nick reads it when he wants to know.
• Session notes capture the full state for checkpoint continuity.
• The only exception: a genuine architectural blocker that needs Nick's decision (per the bug policy), posted to #2479, not surfaced in chat.

Verification and spawning continue silently. The coordinator verifies each landing, updates the count internally, spawns the next module — all without producing output for Nick. This is the no-stop law applied to reporting: stopping to report IS stopping.

DUPLICATE-SPAWN LAW (2026-10-12)

Before spawning an agent for module X:

1. Check docs/factory-claims.json — if the module is in landed or in_flight, SKIP.
2. Check git log gitea/master --oneline -- <module_paths> — if a dichotomy wave commit exists, SKIP.
3. Add the module to in_flight in factory-claims.json BEFORE spawning.
4. On landing: move from in_flight to landed.
5. On abort: move from in_flight back to the queue.

general-47 wasted 1.5h porting behaviour_ledger because general-46 landed it first and the spawn dispatch didn't check. This law prevents that.

SIZE-ADAPTIVE BATCHING (2026-10-12)

The factory auto-scales agent assignment based on module size:

Module size	Agent assignment	Rationale
< 100 lines	3-5 per agent (batch)	Setup cost amortizes; context fits
100-300 lines	1-2 per agent	Moderate context; maybe 2 small + 1 medium
300-800 lines	1 dedicated agent	Full context needed per module
800-1500 lines	1 dedicated agent, possibly split	Large oracle; agent may need 2 sessions
> 1500 lines	Coordinator ports directly (Rune)	Load-bearing; agent context can't hold the full oracle reliably

The batch prompt template includes a "read the module, decide if it fits, skip if it doesn't" instruction so the agent self-reports when a module is too large for the batch context.