Beat Versions & Revisions
The planning and delivery increments that advance a Beat toward its goal — how capability evolves without losing continuity.
Beat Versions & Revisions
Beat Versions plan the work; Revisions deliver it. Together they form the execution layer of Harmonic Composition — the mechanism by which a durable capability evolves incrementally without losing continuity or context.
A Beat Version is the planning increment of a Beat — a planned slice of its capability, carrying the description, scope, and acceptance criteria for a unit of work. Each Beat Version is delivered through one or more Revisions, which are the PR-level execution units.
The chain
Every capability delivery follows the same chain:
Defines the durable capability. Persists across the life of the system. Written in outcome-first language at the level a stakeholder would discuss it.
Defines a planned increment of the capability. Carries the description, scope, acceptance criteria, and rationale. The plan, not the work.
Delivers the Beat Version. One pull request. Inherits context from the parent Beat Version so the plan doesn't get duplicated across PRs.
This separation keeps the long-lived definition of the capability distinct from the near-term planning of its delivery and the delivery itself.
What Beat Versions carry
A Beat Version is the plan. It answers "what are we trying to accomplish?" with:
- Description — the full narrative of what this increment delivers and why
- Scope — what is and is not included, with explicit boundaries
- Acceptance criteria — the binary-testable conditions that define completion
- Change summary — why this increment now, and what it advances
Beat Version quality is judged by plan_quality — a check across six dimensions (Scoped, Directional, Testable, Traceable, Assignable, Risk-aware). A Beat Version must pass this check before its first Revision can be created.
What Revisions carry
A Revision is the delivery. It has almost no planning content of its own — it inherits meaning from the parent Beat Version so the plan doesn't get duplicated across PRs. Its status mirrors GitHub directly (draft, open, merged), and its quality is judged by build_quality before the PR is opened or merged.
Continuity over pivoting
A key function of Revisions is to preserve continuity. When understanding changes — and it always does — the instinct is often to discard what exists and start fresh. Revisions offer a different path: acknowledge the change, refine the direction, and advance from where the system actually is.
A well-sequenced series of Revisions tells the story of how a capability developed — not just where it ended up. That story is part of the corpus that future team members and agents use to understand the system.
How Beat Versions relate to the Beat arc
A Beat moves through three states: composing → composed → live. Beat Versions are how that movement happens. Once a Beat is composed (quality-gated), Beat Versions are created to plan specific increments. Revisions deliver each increment. As Revisions ship and the capability matures, the Beat moves toward live.
See the Beat arc for the full per-Beat lifecycle.
Orphan Revisions
Hotfixes and small operational fixes — bug fixes, dependency bumps, config tweaks — skip the Beat Version entirely. An orphan Revision carries its own description since there is no Beat Version context to inherit, and no quality-check guards apply.
Orphan Revisions are only valid when the change is operational rather than a new capability, and there are no acceptance criteria worth grading.