# Beads Contract

Use the installed `bd` command surface. Run `bd --help` and the relevant subcommand help before relying on optional flags.

## Created State

Create or identify:

- one epic for the accepted plan
- one issue per independently verifiable execution unit
- optional broad-Phase milestone issues for progress summaries only
- dependencies matching the accepted execution graph
- links from every execution issue to its phase and turn docs
- quality gates and branch/PR constraints

Do not attach an executable issue to an open grouping milestone with Beads' `parent` field or a `parent-child` dependency. Beads treats that relation as a readiness blocker, so a milestone that waits for its executable issues would deadlock them. Record phase membership as metadata, list executable issue IDs on the milestone, and use only explicit `blocks` edges to control execution order.

## Version 2 Metadata

Store typed metadata when supported; otherwise store a clearly labelled JSON block in the epic design or description.

```json
{
  "dirtyloop_version": 2,
  "planning": {
    "owner": "codex-plan-mode-or-user-supplied-plan",
    "source": "PLAN.md or accepted conversation plan",
    "status": "accepted"
  },
  "stream_slug": "...",
  "doc_root": "docs/implementation/<stream>",
  "harness": {
    "target": "codex|pi",
    "binding_schema": 1,
    "adapter_contract": "dirtyloops-harness/1"
  },
  "run_policy": "until-complete",
  "once_mode": false,
  "execution_profile": "orchestrator-callback",
  "execution_policy": {
    "mode": "adaptive",
    "orchestrator_chooses_topology": false,
    "orchestrator_chooses_model_and_effort": true,
    "orchestrator_chooses_delegation": false,
    "orchestration_brief_required": true
  },
  "delegation_policy": {
    "mode": "strongly-encouraged",
    "max_helpers_per_stage": 20,
    "effective_concurrency": "min(20, user limit, certified runtime capacity, available slots)",
    "mission_selection": "evidence-driven",
    "fixed_personas": false,
    "zero_helper_rationale_for_nontrivial_stage": true
  },
  "constraints": {
    "one_active_pr": true,
    "one_owner_per_mutable_checkout": true,
    "independent_review": true,
    "repo_relative_artifacts": true
  },
  "branch_pr_policy": "...",
  "quality_gates": ["..."],
  "callback_policy": {
    "binding": "required-per-stage-owner",
    "requires_concrete_target": true,
    "requires_source_thread_id": true,
    "forbid_creation_thread_id_as_future_target": true
  }
}
```

The example is `orchestrator-callback`. For `adaptive`, set `execution_profile` to `adaptive`, both orchestrator-choice booleans to `true`, and callback binding to `runtime-when-used`.

User-specified constraints may restrict available models, reasoning effort, concurrency, delegation, cost, thread creation, or review posture. Absence of an override means adaptive choice, not inheritance from a historical dirtyloops default.

Beads stores required harness identity and contract versions, not detected plugins or current runtime capabilities. Those facts drift and must be probed by the active adapter during `run` and `inspect`.

Phase metadata includes:

- phase number, outcome, and issue id
- phase doc and turn doc
- dependencies and scope boundaries
- settled decisions and open questions
- acceptance evidence and quality gates
- branch/PR constraints
- replanning triggers

Store only the durable ownership roles implied by the profile: orchestrator, implementation owner, and independent review owner. Do not store a fixed helper taxonomy, required swarm count, or universal model/reasoning defaults.

## Selection And Mutation

Select from Beads rather than the doc list:

```sh
bd ready
bd show <epic-id> --deps
bd show <phase-id>
```

The actor currently coordinating the loop owns canonical Beads mutations. Delegates may recommend changes but do not mutate Beads unless the orchestration brief explicitly transfers that authority safely.

If Beads is unavailable but `.beads/issues.jsonl` exists, use it only as a read-only routing fallback and report degraded state.

Refresh `.beads/issues.jsonl` after Beads mutations when the repository tracks it, using the locally supported export command.