01-projects/phdata/brigade-education

02 house anatomy

The House, Precisely — vocabulary, contracts, and gates

Part 2 of 3 — the anatomy, for engineers. Assumes Part 1 (the concept).

Vocabulary (canonical)

Term What it is
Brigade One kitchen: a roster of stations behind an expo, serving a menu, pulling from the rail. Ships as one self-contained plugin.
Station One agent, one narrow job (spec author, test author, code author, critic…). Hands off through file artifacts, never shared context.
The pass The orchestration layer between rail and stations — where routing decisions happen.
Expo The deciding role at the pass. Pulls tickets, runs the gates, dispatches stations, chooses the exit.
Ticket The unit of work AND its permanent record: starts as the order (context pointers + scope), gets marked up at every station, files away as the build record. Mutable while in flight, append-only in spirit — history is never rewritten.
Rail The hot queue tickets hang on, with lease/ack semantics and a work-log.
Cellar The cold store of record: landed artifacts, filed tickets, published menus, competency sources.
Menu A brigade's published answer to "what can you do?" — machine-parseable, hash-stamped, refreshed by a discovery ticket.
Steward The front-of-house role: pairs a request to a menu, gathers context, writes the ticket, hangs it, and closes the loop after filing.
Registrar The house role that owns intake and records — everything before a ticket hangs and after it files. "It never cooks — no expo, no stations, no rail lock." One registrar serves every kitchen.

Kitchen brigade vs house role — the split is load-bearing. A kitchen brigade cooks: stations behind an expo, a walk that leases tickets, a menu. A house role (like the registrar) ships readiness checks plus its role verbs and nothing kitchen-shaped. In the designers' words: "Forcing a hollow service verb onto a house role for uniformity would be checkbox theater — the split is the honest contract."

The five-command surface

Every brigade exposes the same five commands, regardless of domain. A brigade missing any of them is interface-incomplete, and the factory is obligated to be structurally unable to emit one.

Command Question it answers Contract
menu "What can you do?" Discovery is itself a ticket: the steward hangs an artifact: menu order; the expo introspects its own brigade and publishes the menu to the cellar, version-stamped. Capability changes → re-hang. The discovery tickets are the audit trail of what the brigade claimed, when.
mise "Are you ready?" (mise en place) Deterministic preflight from a per-brigade declaration: ports reachable, stations present, declared dependencies (it checks a manifest — it doesn't guess), menu freshness (hash vs published stamp), model access. Every non-PASS row prints its own remedy. Invariant: a brigade whose mise has a FAIL must refuse service — a kitchen that isn't set up doesn't open.
service "Start taking orders." start = lock check → mise gate → take the rail's service lock → walk the rail. end = graceful stand-down between tickets, never mid-ticket; the ticket work-log is the resume state. The lock upgrades the filesystem rail from one-walker-by-convention to one-walker-enforced (advisory-grade — see honesty notes).
fire "Do this one, now." Not a build — an invocation mode: calling the expo directly IS fire. Two non-negotiables: "fire skips the queue, never the record" (a ticket is still created and filed, marked as fired) and "fire means 'now', not 'ungated'" — every gate still applies.
close-out "Order up — who tells the table?" Kitchen side: the expo files the ticket at terminal ack — the rail stays clear. House side: the steward sweeps filed tickets for terminal-without-signature, delivers the result on the intake channel, and signs. The signature is the whole mechanism — it completes the record, marks idempotency, and its absence is the retry queue. No event bus, no daemon: "truth lives on the ticket; there is no second store to reconcile."

Exits (the only five)

advance · refire-to-author · reroute-to-spec · reroute-to-steward · kill

The exit belongs to the expo. Critics return verdicts; verdicts are inputs. reroute-to-steward is the front-door loop: a ticket whose context is insufficient goes back to the person who can fix the context, not to a station that would cook garbage confidently. (escalate — pausing for a human — is a state, not an exit.)

The gates

Layered so that cheap deterministic checks run everywhere and expensive judgment runs where it counts:

  1. Gate A — deterministic ticket lint. Schema-level rules enforced at both ends: steward at enqueue, expo at pull. Malformed work never enters the kitchen, and a corrupted ticket never gets cooked.
  2. Phase-0 — sufficiency judgment. Before any station runs, the expo reads the ticket's context and exits Clear / Ambiguous / Thin. Thin context routes back (reroute-to-steward) instead of proceeding on vibes.
  3. Critic layer — advisory verdicts. Independent zero-context agents, one per axis (fidelity, slop, coverage…), plus a deterministic lint axis that cannot be out-voted by the LLM axes. In mature brigades this layer includes per-gate keepers and a multi-judge council at the highest-stakes gate.
  4. Human gates — recorded, not blocking. Where a phase requires human approval, the pattern is pre-signature: the approval (approver + provenance) is recorded on the ticket at enqueue, so the walk advances without a mid-run pause — while a missing or malformed approval still hard-escalates. Delegation is legitimate when explicit, logged, and revocable; machinery never self-approves.
  5. Execution-eval — does the artifact beat the baseline? For skill artifacts: two arms, with-skill vs base-model, over oracle fixtures. Lift = with-skill pass-rate minus baseline; lift ≈ 0 means the skill is dead weight. Read lift per-fixture, not aggregate — one real fixed failure mode drowns in the average of already-easy fixtures. Its sharpest finding so far: judgment-lift shrinks as models strengthen; convention-lift (house rules a model can't guess) survives every tier.

Nesting: the factory builds brigades

The skill factory is a brigade whose artifact type includes brigade — "assemble a new kitchen" is just a ticket. Every factory run produces two assets: the thing built, and the worked example with its full build trail. Stations are themselves skills, which is what closes the loop: the factory can refine its own stations through the same gates it applies to everything else.

Honesty notes (what the docs themselves flag)

Part 3 puts all of this in motion.