Skip to content

ADR-0009: Repository-native delivery programs

Date: 2026-08-12 Status: accepted Decider: platform owner

PROPOSAL UNTIL MERGED: Treat this ADR as a proposal unless it exists on verified origin/main. Its accepted decision state becomes authoritative only when this exact record reaches verified origin/main.

Context

The repository already owns architecture decisions, desired state, runbooks, and merged history.

Large delivery programs used private implementation plans as a second planning authority. Asana then mirrored parts of those plans. Repository roadmaps and milestones also carried status.

This produced several problems:

  • A new session needed private files to understand repository work.
  • Broad plans, roadmap pages, and Asana could disagree.
  • Tasks mixed decisions, implementation, testing, and sign-off.
  • Evidence and rollback requirements varied between tasks.
  • Readers had no single current milestone or decision page.

The staging and production program needs a durable source that reviewers, agents, and future operators can inspect from source control.

Decision

1. Active programs live in the repository

Each large delivery program lives at:

docs/programs/<program>/

The program owns:

  • Approved scope and exclusions.
  • Current milestone and milestone gates.
  • Program-local decision routing and gate decisions.
  • Work-package contracts.
  • Test and evidence contracts.
  • Runbook readiness.
  • Cutover and sign-off contracts.

The program does not replace other durable authorities.

2. Each information type has one authority

Information Authority
Program scope, gates, and work-package contracts docs/programs/<program>/
Task status, assignee, priority, and dependencies Asana
Architecture decisions docs/adr/
Desired state Terraform and Kubernetes source
Repeatable operations docs/runbooks/
Merged delivery history docs/ledger.md and Git history
Live state Dated runtime evidence
Personal ideas and drafts Private files with no authority

When sources disagree, work stops until the applicable authority is corrected.

A repository record becomes accepted authority only after it lands on origin/main.

A branch, pull request, or working-tree copy is a proposal. It can support review, but it cannot authorize implementation or a live action.

Authority status and lifecycle state answer different questions:

  • Authority status records where the record exists.
  • Lifecycle state records the program phase or package maturity.

An active lifecycle value in a branch does not make that branch authoritative. An accepted record on origin/main can still contain a proposed package. Implementation needs both accepted location and approved package maturity.

3. The decision owner controls program creation

The agent first recommends one work class:

  • Routine tracked work.
  • One work package inside an existing program.
  • A new delivery program.

The decision owner makes the final classification.

A new program starts with a one-page charter and milestone map. The decision owner chooses CREATE or AMEND.

CREATE authorizes preparation of the program record. It does not authorize an Asana change, implementation, publication, merge, or live action.

The program becomes authority only when its program-governance pull request lands on origin/main.

4. Work packages are durable contracts

A work package has:

  • One measurable result.
  • One landing action.
  • One technical boundary.
  • One rollback boundary.
  • One acceptance set.
  • One evidence set.
  • One decision owner.

Separate pull requests, Terraform states, clusters, trust boundaries, data migrations, and external or state-changing human actions require separate packages.

An approved package has exactly one Asana task.

The approved package record must exist on origin/main before implementation starts. An agent cannot introduce and implement a package in one pull request.

Asana does not duplicate the package's technical content.

A decision package can contain option analysis, the owner decision, and its repository record. These steps form one decision boundary and change no external state.

A source pull request and its later apply operation also use separate packages.

External or state-changing human actions use separate packages. Examples include applies, dispatches, migrations, traffic changes, and deletions.

5. Architecture decisions use ADRs

An ADR owns every durable architecture decision.

A decision package prepares source-backed options and a recommendation. The decision owner selects the option. The agent then records the accepted ADR and links it from the program decision register.

An implementation package cannot silently choose or replace architecture.

6. Program gate state differs from task status

The repository records milestone gate state and work-package maturity.

Asana records live task status.

The repository does not copy task status.

7. Only the current milestone receives detailed work packages

Future milestones can have outline records. Detailed work packages stay limited to the current milestone and the immediate-next exception below.

The decision owner activates one milestone at a time.

Detailed future work is created only after the prior gate passes.

This prevents stale task inventories and premature design.

The active milestone can draft proposed packages for the next milestone. This exception supports dependency and rollback review at the active exit gate. Those packages cannot become approved before the next milestone is ready or active.

8. Work isolation follows the package boundary

Each approved package uses one worktree from current origin/main.

It normally produces one pull request.

Packages sharing a Terraform state, cluster, trust root, database, or traffic surface run in sequence.

Independent packages can run in parallel.

9. The owner receives a bounded control view

The agent presents one Owner Brief before detailed investigation.

The brief contains one current decision, at most three completed results, two active packages, three next packages, and three risks. It also states the agent's next action and the user's next decision.

The decision owner does not need to read every package or maintain metadata.

10. Record-only changes do not create package recursion

A program-governance pull request can create or update program records, approvals, templates, ADR links, and gate decisions. It cannot change desired state, application source, or a live system.

An evidence-only record pull request can add immutable proof, deviations, and package maturity after implementation lands. It cannot change acceptance criteria or implementation.

These record changes support the approved package. They do not need another delivery package.

11. Milestone gates use structured metadata

Each milestone record names:

  • One entry-gate identifier.
  • One exit-gate identifier.
  • One exit decision.
  • One next milestone or none.
  • One decision owner.

A milestone can define internal gates when one broad approval would be unsafe. The cutover milestone uses GO before migration work and ENABLE before traffic.

12. Templates define the required record set

Repository-wide templates live under docs/programs/_templates/.

The new-program workflow uses those templates for the program entry page, milestones, decision brief, work packages, and approval cards.

The agent can adapt the content, but it cannot omit required decisions, exclusions, tests, rollback, evidence, or sign-off fields.

13. CI enforcement is deferred

This decision does not add required CI for program records.

Agents and reviewers can run local structure and link checks as optional review aids. These checks do not grant approval or make a record authoritative.

A later owner decision can add CI enforcement after the manual workflow proves useful. That change needs its own reviewed scope and normal source-control gates.

Consequences

  • The repository contains more planning material.
  • That material is durable and reviewable.
  • Private drafts can still exist, but they cannot authorize work.
  • Asana remains necessary for live scheduling and ownership.
  • Programs require manual review when decisions or evidence change.
  • CI does not yet enforce program structure or lifecycle transitions.
  • Historical broad plans can remain as source material after a superseded banner.
  • Stable ADRs and runbooks remain outside program directories.

Bootstrap

This ADR and the first program cannot depend on an already-landed copy of this process.

The user's 2026-08-12 direction authorizes preparation of the first program-governance change in the working tree.

This one-time bootstrap is not a work package. It needs only the normal PUBLISH and MERGE decisions after owner review.

The preparation direction authorizes no commit, push, pull request, tracker change, merge, apply, or implementation package.

Superseded process

When accepted, this ADR supersedes the rule that all implementation plans must stay outside the repository.

Temporary analyses, raw agent drafts, and personal notes still stay outside the repository.

Only reviewed program records and durable execution contracts belong under docs/programs/.