# Common Contract

## Authority

Beads is canonical for phase status, ordering, dependencies, blockers, ownership, and completion. Implementation docs preserve accepted intent and execution context. If they disagree, report the mismatch and trust Beads for state; do not silently rewrite authored intent.

## Planning Seam

Planning happens before dirtyloops in a harness-appropriate planning surface. An accepted plan is **decision-complete, implementation-open**:

- the outcome, constraints, scope, consequential decisions, acceptance evidence, dependencies, and replanning triggers are explicit
- implementation details that depend on repository evidence remain open

`dirtyloops create` may clarify structure but must not invent intent. `dirtyloops run` may adapt execution strategy but must not silently change accepted outcomes or constraints.

## Generated Layout

```text
docs/implementation/<stream>/
  IMPLEMENT.md
  00-roadmap.md
  <phase-docs>.md
  loop-state.md
  turn-docs/
  prompts/run-loop.md
  runtime/generation.json
  runtime/binding.json
  runtime/adapter.json  # Pi only
  schemas/
```

`loop-state.md` is a mutable compact resume sidecar, not the source of truth and not part of deterministic runtime generation identity. Material operations still update it inside the same rollback boundary. All generated paths are repo-relative.

## Portable And Generated State

Protected state survives material generated-contract operations byte-for-byte: accepted plans, roadmaps, phase docs, turn docs, implementation code, issue state and dependencies, branch and PR history, review and CI evidence, and storyboards.

Deterministic generated harness state is replaced as one transaction: `IMPLEMENT.md`, `runtime/generation.json`, `runtime/binding.json`, Pi-only `runtime/adapter.json`, the active run prompt, and current schemas. The same transaction updates mutable sidecars such as `loop-state.md` and `runtime/activation.json`, but their routine lifecycle changes never invalidate the generation hash. Harness behavior belongs in adapters; portable docs use `session`, `delegate`, and `completion` rather than product-specific child types.

## Execution Invariants

- Select one ready phase, or one approved Wave of dependency-ready qualified tracer-bullet leaves, only when the accepted plan and Beads explicitly permit that topology.
- When an accepted graph uses broad Phase milestones for grouping, never claim those milestones. Keep phase membership in metadata rather than a Beads `parent-child` edge; execute and review only their qualified tracer-bullet leaves.
- Treat execution-readiness output as boundary evidence. Require a separate live launch-readiness pass for the exact leaf before checkout preparation or mutation.
- Keep one active external implementation PR unless the accepted plan and Beads explicitly permit more. Parallel owner branches may remain internal contributions to that one integration PR.
- Read the linked phase doc before broad work.
- Record an orchestration brief before broad work.
- Keep one owner per mutable checkout or branch.
- Under structured completion, use callback delivery as the normal path with no status, sleep, or wait polling. Delivery is at-least-once: persist one logical result and acknowledgement, replay the acknowledgement response for valid duplicates, and apply downstream effects once. Reasoned recovery is exceptional, evidence-based, rate-limited, and durably recorded.
- Renew a degraded coordinator only at a safe ownership boundary with durable Beads, turn-doc, PR, branch, and checkout evidence. Context pressure may trigger renewal from adapter-observed usage, but no fixed coordinator lifetime, threshold, or topology is portable policy.
- File Beads follow-ups instead of widening the phase.
- Update Beads before mirroring state into `loop-state.md`.
- Do not complete a phase while review or CI is unresolved.
- When an accepted checkpoint defines a shared repair process, wait for every required review role, combine and deduplicate findings, use one repair owner, rerun the affected tests and reviewers, and count one pass across the review set. Enforce the accepted pass limit and ask the user when it is exhausted.
- If the loop upgrades its own control plane, enforce `builder-bootstrap.md`: direct-only mutation before the frozen certificate, a fresh coordinator activation, and exact closure verification before delegated mutation.

## Adaptive Decisions

The run-time orchestrator chooses and may revise:

- direct work versus delegation
- bounded delegates versus durable sessions
- model tier and reasoning effort per mission
- concurrency and number of delegates
- role decomposition and report shape
- coordination strategy supported by the current surface; structured completion remains callback-driven in normal operation

These decisions must be proportional to phase complexity, uncertainty, risk, runtime capability, and user constraints. Do not turn historical defaults into mandatory choreography.

## Review And Storyboard

Preserve every review role required by the accepted phase. Thermonuclear reviewers use `thermo-nuclear-code-quality-review`. Adversarial reviewers must not invoke or consult that skill. Closeout uses `impeccable` when available and records when it is unavailable. Install `@pierre/diffs` when missing and use `@pierre/diffs/ssr` for every storyboard diff.