field guidemain · attested greentoolchain pins ↗shippeddirectionproposed
03 Planes

One idea. Four working planes.

A source-backed map of the work lifecycle: where work begins, how it earns its way to main, and what has to be true before a release leaves the hive.

shippeddirection / namingdesign proposal
01UPSTREAM / CONCEPT

IDEATION PLANE

Turn signals into a useful question.

Future plane · intake ships today

Beadhive has report intake and planner adoption — the triage verbs live on the Fleet page — while a distinct ideation plane is still a future concept. This transition shows the current entry points without claiming that candidate discovery is automated.

  1. I01Idea or reportVision, roadmap, operator input
  2. I02Untriaged intakebh report · bh work intake
  3. I03Human triageaccept · reject · reroute · promote
  4. I04Planning framebh plan adopt
↳

Design boundary · bh report creates intake; triage can promote it;bh plan adopt seeds a planning frame. A richer loop from repo vision and accumulated feedback into candidate work needs its own contract.

02HUMAN-INTERACTIVE

PLANNING PLANE · SHIPPED

Shape a plan before work exists.

Current state machine

The planner turns an idea into a dependency-linked molecule. Planning produces bead specifications and decision records; implementation stays downstream.

  1. P01IdeateFrame the request with the human
  2. P02ResearchRead the repo and its constraints
  3. P03ArchitectureDecisions, trade-offs, open questions
  4. P04DecomposeIssues + dependency graph
  5. P05File moleculebh plan file
PLAN APPROVAL Is the decomposition right?KICKOFF APPROVAL Should this work start now?Roots surface in bd readyDispatcher may start the molecule
SPIKE LOOP when feasibility is open

Open question → file a spike molecule → development runs the spike → decision bead records a verdict.

GO · replan into implementationNO-GO · record ADR, close
REPLAN DOOR one scoped re-entry

A spike verdict or mid-work discovery returns one molecule to planning. Backlog-wide reconciliation is groom, not replan.

The shapes a planner files

THE SHAPES — THE DOTTED ID IS THE TIERroadmapan ordered set of workstreams · above the Task-nesting cap, so it runs as its own sessiondirection · namingworkstream · bh-wsissue_type=epic whose children are epics — no new type, no new ruleepic · bh-ws.1issues + dependency DAG.1.1.1.2.1.3a linear chain with no mid-point testable unit:a batch:<group> candidate (≤ 5, cohesive, one model tier)leaf → wt/bead/issue/bh-ws.1.2 · developerepic · bh-ws.2two roots, one join.2.1.2.2.2.3every root carries its own kickoff gate;bh plan approve resolves them all, idempotentlyspike molecule · bh-ws.3same shape, two labels: epic tag:spike + one tag:decision bead depending on every spikespike .3.1spike .3.2decision .3.3acceptance = a verdict doc,never product codeworkstream · bh-ws2 — same machinery; a roadmap orders workstreams by their dependency edges, nothing moretierid shapebranchseatissuebh-ws.2.1wt/bead/issue/<id>developer · dev/epic (molecule)bh-ws.2wt/bead/epic/<id>dispatcher · disp/ — nested under a workstreamworkstreambh-wswt/bead/epic/<id>dispatcher · disp/ (root of its session)WHAT bh plan file COMPILESepic recordtitle · description · design · complexity (explicit or inferred) · adopts / external_ref provenancechildren, in topo orderacceptance REQUIRED · identity triplet · closed dims: size, complexity, harness, componentopen dimsbatch:<group> · tag: · wave: · model: <provider>/<name> — labels, so membership survives filingdependency DAGdeps: closed set, acyclic, no orphans · bd swarm create wires it · bh plan show round-trips itone kickoff gate per roota type:human bd gate blocking each root · kickoff=pending on the epicPLANapprovalbh plan file <spec>is the decomposition right?KICKOFFapprovalbh plan approve <epic>should it start now?never collapsed into one. Then roots surface in bd ready and dispatch may start.FIDELITY — SCALES THE RESEARCH, NOT THE SHAPEquick≈ 2–4 issues · inline spec · dry-run · filespec≈ 5–15 issues · YAML spec authored, checked, previeweddeepcross-cutting · analyst sub-agents research firstAll three converge on the same compiler and the same two gates. After filing,beads is the source of truth; the spec is absorbed scaffolding.Re-entry: replan is scoped to ONE molecule and ONE triggering event (a spikeverdict, a mid-execution blocker); groom is backlog-wide hygiene with no trigger.
kickoff gate on a root beadmolecule (epic)direction / naming
There is one shape, applied recursively. A molecule is an epic with dependency-linked issues; a workstream is an epic whose children are epics; the position in the dotted id is the tier, and every container tier gets the same branch namespace, the same dispatcher seat and the same finish rule. A spike molecule is that shape with two labels. What this site calls a roadmap is the tier above a workstream — an ordered set of workstreams — and because live sub-agent nesting is capped at two levels, it runs as its own supervised session rather than as a nested Task; the name is a convention here, not a verb. The compiler is where accuracy is enforced: acceptance is required on every child, dependencies must form a closed acyclic set, and a hand-assembled epic that lacks any of this plumbing is refused by approve and start until bh plan repair converges it.

The spike loop as a tree

PLANNINGarchitecturedecisions · trade-offsfeasibilitysettled?yesimplementation moleculebh plan fileKICKOFFbh plan approvedispatchroots in bd readyno: unsettledspike moleculeepic tag:spike · bh-spspike S1 · bh-sp.1spike S2 · bh-sp.2decision beaddeps: every spikeeach spike owes docs/spikes/<id>.md: Question · Method · Evidence · Verdict · Recommendationintegration plane runs itnormal dispatch · one worktree per spikeverdictclose reasonbh work submit → review gate → a human readsGO/bh:replan <spike-epic>carry the evidence into architecturefiles the implementation molecule · external_ref → the spike epicNO-GOADR in docs/design · closenothing orphaned — nothing was filed earlyNO-GO,close to GOsecond-level spike · bh-sp.3the narrower question the first verdict exposed, filed as a childof the spike epic — same beads, same gate, one tier downdirection · convention onlyre-enters the same looptwo-molecule loop:nothing exists in the trackerthat current evidencedoesn't support
GONO-GOopen question / replangatedirection, not a verb
A spike molecule is an ordinary molecule with two labels: its spike beads (tag:spike) each owe a verdict document and no product code, and one decision bead (tag:decision) depends on all of them, so it becomes ready only when every artifact is in. The verdict rides the close reason. GO re-enters planning through the one re-entry door, replan, and the implementation molecule links back to the spike for provenance;NO-GO records the decision and closes — no implementation bead was ever filed, so none is orphaned. A verdict that lands close to the bar is still a NO-GO; the honest response is a narrower second-level spike under the same epic, which is the same loop applied again rather than a third outcome. Several ready spike epics can run as one unattended wave, each in its own worktree, stopping at the review gate for a human to read the verdicts together.
03INTEGRATION LOOP

DEVELOPMENT PLANE · CLI NAME: INTEGRATION

Move one bead through its gates.

Current state machine

Parallel developers can work in separate worktrees; merges serialize. A molecule lands as one assembled unit, keeping main green between releases.

  1. D01Ready workApproved roots surface to dispatch
  2. D02Assign + claimDispatcher routes · developer claims
  3. D03WorktreeIsolated branch for one bead
  4. D04Implement + refineShow history · shape clean commits
  5. D05Check + submitValidate a clean proposed tree
ACCEPTED SUBMISSIONBoth required gates resolve before landing
  1. D06Review gatesReview and security must clear
  2. D07Merge beadSerial merge into its molecule
  3. D08Finish moleculeValidate and land the assembled work
  4. D09Integration lineMain remains green
REVIEW BOUNCEChanges requested → developer resumes with written feedback → check and submit again.
BLOCKER / DISCOVERYEvidence that invalidates the molecule returns through the planning plane's replan door.

⬢ For a molecule, beads merge serially into its container branch. bh work finishvalidates the assembled molecule and lands it as one --no-ff bubble.

↗CROSS-PLANE / EVIDENCE

VALIDATION + ATTESTATION

Reuse proof only when its inputs still match.

shipped

Two reuse paths share a safety rule: proof is narrow, recent, and tied to what actually ran. A reused key is not a claim that every key—or the new tree as a whole—is green.

PATH A · EXACT-TREE VERDICT

Same tree, same command.

The ledger keys a completed green result by tree hash and command hash, with a freshness window. Red, stale, missing, or ambiguous results run again. Git-metadata checks may still run on a cache hit.

TREE+ COMMAND HASH+ FRESHNESS

PATH B · GRAPH-DERIVED ATTEST KEYS

Carry only unaffected keys.

An impact receipt maps changed inputs to named validation keys. A key can carry from a current green source only when its complete input closure is unchanged. Carries do not chain or refresh age.

IMPACT RECEIPT→ KEY CLOSURE→ RUN OR CARRY
!

Unknown impact means full validation.native-full invalidates every key; selective validation is opt-in. Unowned paths, resolver trouble, an unproven selector, and build-system changes fail closed to the complete key set.

THE VALIDATION PATH TODAYper hive · host-wide capacity
  1. V01Resolve keysImpact receipt selects what changed
  2. V02Reuse only proofExact tree or proven unchanged closure
  3. V03Serialize identityHive + tree + command hash
  4. V04Acquire slotHost-wide validation capacity
  5. V05Run + recordFull clean green run earns proof
Slot default work.validation_slots: 1Host override BH_VALIDATION_SLOTSSame identity serialized before admissionGreen proof one full, clean confirming run

Attest key slots, and when a verdict carries

ONE GATE, NAMED SLOTS — work.attest.keysdocsjust attest-docsunitjust attest-unitstatefuljust attest-statefulintegrationjust attest-integrationdemosjust attest-demoseach key: an opaque command, a selector the build graphunderstands, and a policy — required (default) or optionalA · identical tree--no-ff land onto an unmoved baseT0= T1 (tree hash equal)docsexact-tree reuseunitexact-tree reusestatefulexact-tree reuseintegrationexact-tree reusedemosexact-tree reusesame bytes, same command hash:every verdict is an exact-tree hit(current, fresh within work.ledger_ttl)B · docs-only changeimpact receipt proves the closureT0T1receipt: digestdocsrunsunitcarried from T0statefulcarried from T0integrationcarried from T0demoscarried from T0changed paths → owning units →transitive dependents → keys. docs runs;the rest carry from T0, age preservedC · moved main · rebase · unownedjustfile, lockfile, BUILD, resolver errorT0T2no receiptdocsrunsunitrunsstatefulrunsintegrationrunsdemosrunsclosure cannot be proven or a globalinput changed: fail closed to every key(native-full — also the default backend)D · reads git metadatagit describe, tags, commit countsT0T1history ≠ contentdocsnever carriesunitnever carriesstatefulnever carriesintegrationnever carriesdemosnever carriesno file inputs a graph can prove:this class never carries; work.always_runruns even on an exact-tree hitPER-KEY STATEcurrentK ran on this exact tree — a fresh (tree, cmd_hash) record, green or redcarriedK did not run here; a green current verdict on T0 was carried by a receipt — timestamp stays T0'sabsentinvalidated and not yet run · never ran · or returned the explicit unknown exit 75POLICYrequired: current green ✓ · carried ✓ · absent ✗ block · red ✗ blockoptional: current green ✓ · carried ✓ · absent ✓ · red ✗ block — optional never ignores a real failurecarries never chainT0 ranT1 carriedT2 ✗one receipt T0 → T2a carried verdict is nevera source. To reach T2 theresolver diffs T0 against T2directly; if T0 aged outthere is nothing to carry.Only green carries.
key runs on this treeverdict reused (exact tree) or carried (receipt)never transfers
A key slot is a verdict with a scope. Exact-tree reuse (A) is the whole-tree case: the same bytes under the same command hash is the same evidence. Carry (B) is narrower and newer: a build-graph receipt proves that everything key K can read is byte-identical between the source tree and this one, so K's green moves across — one key at a time, never the tree's verdict, never another key's. Everything that cannot be proven fails closed to a full run (C): an unowned path, a global build input, a resolver error, an unproven selector. Keys that read git history (D) have no file closure to prove and never carry; thealways_run set runs before any hit is honored. The default backend isnative-full, which invalidates every key on every change; selective validation is opt-in per hive, and on_unresolved: strict exists only so a developer can see why a selection failed instead of paying for the all-key fallback.

Validation slots on one host

ONE HOST — SHIPPED · work.validation_slots: 1 · BH_VALIDATION_SLOTS winsREQUESTSbh work submit bh-api-7hive api · tree T1 · cmd Hleader — admittedbh work submit bh-api-7hive api · tree T1 · cmd Hsame identity — followerbh work check bh-web-3hive web · tree T7 · cmd Hqueued for a slotbh work merge bh-api-9hive api · tree T9 · cmd Hqueued for a slotidentity lock (hive, tree, cmd_hash):serializes ahead of admission — the followertakes no slot, consumes the leader's verdicthost semaphoreone heavyweight gate at a timeslot 0 · executingbh-api-7 · clean checkout of T1key: unitkey: statefulattest keys run under the parent'spermit — no extra slotqueue · bh-web-3, bh-api-9queue_seconds recorded per runthe record.bh/validation/runs/<run-id>/manifest · reports/ · gate.logverdicts/<tree>/<cmd_hash>green · red · none · uses/who reads itsubmit · merge · finish · unionthe push-main hookrelease preflight · attestexact (tree, cmd_hash) · TTL P1D0 slots disables admission — reserve it for a separately contained CI host.Slots are host policy, not per-hive: a hive-local value is ignored.bh work check seeds the same store, so check → submit at one sha pays once.A dead owner is marked abandoned; its locks release and one follower takes over.Lower priority for the gate: work.validation_priority (nice / ionice).EXTERNAL CI HANDLERdirectionthe same command, run elsewherea CI engine or another frame takes the (tree, cmd) and thehost's slot stays free — the handoff is the unbuilt parttyped result — shipped, opt-inwork.validation_protocol: beadhive-validation-result/v1bh exports BH_VALIDATION_RESULT_PATH; the trusted runner writes{"verdict": "green|red|none", "reason": …}green with a nonzero exit is rejected — never less than redlands as an attestation, not a special casesame verdict key (tree, cmd_hash), same per-key states,so the same gates and the same push hook consume itwith no new bypass addedwhat has to be decided firsta verdict from another host is a trust claim, not a cache:it needs signing (ADR Decision 6 — out of scope in v1)validation broker — proposalresource-aware queue: declared CPU / memory / named pools,priority and measured runtime; pueue vs HyperQueue bake-off
Admission is a host question, not a hive question: one counting semaphore covers every worktree on the machine, defaulting to a single heavyweight gate at a time, and exact concurrent requests for the same (hive, tree, command) serialize ahead of it so a duplicate submit never spends a slot. What comes out is a durable run record plus a verdict pointer keyed on the tree and command hash — the object every later boundary reads. The right-hand half is the shape an offload would take: the runner protocol already lets a trusted external runner return a typed verdict, and because that verdict is just another attestation under the same key, the gates and the pre-push hook would need no new code path. What is not built is the handoff itself, and what is not decided is how a verdict earned on another machine is trusted.
DESIGNPROPOSAL2026-09-26

VALIDATION BROKER · NOT SHIPPED

Make slots understand the work they admit.

The current host-slot semaphore grants equal permits. The proposal replaces independent limits with a host-wide queue: each opaque key command declares CPU, memory, and named-pool needs; the broker admits the whole reservation, then passes the grant to the runner through an environment contract. Priority and measured runtime guide the queue. The backend bake-off considers pueue + a packer or HyperQueue; the ADR is still pending.

Shared broker interfaceNested checks use their parent's grantResource-aware admissionBackend choice unresolved
04LOW-FREQUENCY / GUARDED

RELEASE PLANE · SHIPPED

Prove the bump tree before it leaves.

Guarded release flow

The validation path above is what supplies the proof: the release gate runs against the exact tree created by the version bump. A local tag can still be recovered; publication is the point of no return, so main and tag move atomically only after green.

  1. R01PreflightRequire green proof for current tree
  2. R02Bump + tagCreates a new, unproven tree
  3. R03AttestRun the release gate on that exact tree
  4. R04Await verdictGreen permits push · red refuses
  5. R05Atomic pushMain + tag together · remote tag is the boundary

⬢ The tag reaching the remote is the point of no return: before it, recovery undoes locally; after it, roll forward. The commands, merge ordering and recovery are on the Process page.

··PLACEHOLDERS

NEXT PLANES · NOT SPECIFIED

Leave room for the loop to learn.

State machines TBD
05

Observation

A placeholder for the eventual evidence-gathering plane. Inputs, states, seat ownership, and outputs remain to be designed.

FLOW TBD
06

Feedback

The website already sketches a production-to-idea feedback edge; this separate plane needs an explicit contract before it is described as shipped.

FLOW TBD
§READ THE CONTRACTS

SOURCE NOTES

Follow the implementation.