Skip to main content

Governance

Governance in ASF50 is the set of rules that determine what an actor may do, when an actor must stop, and how decisions are durably recorded. This page summarizes the governance model; the canonical authority lives in agent-harness/governance/ and in the runtime state.

Owner authorization​

The owner is the only principal that may authorize destructive operations. Authorization is scoped — a MERGE_APPROVAL is not a TAG_APPROVAL — and is subject-bound — the approval only applies to the exact subject_sha recorded when the gate was opened.

Role authorization​

Each role has a capability envelope:

  • PLANNER — read canonical sources, write plans.
  • BUILDER — implement the bounded scope.
  • TEST_ENGINEER — run tests, write evidence.
  • INDEPENDENT_AUDIT_HIGH — fresh-context audit of an exact target.
  • INDEPENDENT_DOCS_AUDITOR — fresh-context accuracy audit of documentation.
  • RELEASE_MANAGER — governed merge and deployment.
  • REPAIRER — bounded repair against a frozen target.
  • ARCHITECT — architecture decisions.
  • GOAL_OWNER — owner-only actions (offline).

A role cannot exceed its capability. A BUILDER cannot create a release. A PLANNER cannot write implementation files. The orchestrator enforces the boundary.

Architecture decisions​

Architecture decisions are recorded in goals/<GOAL_ID>/ARCHITECTURE_DECISION.yaml when a goal requires one. An architecture decision is binding for the goal's lifetime; revising it requires a new goal.

Bounded repair​

A bounded repair is the only way to modify a frozen surface. It is itself a goal of type REPAIR_GOAL with:

  • A frozen base_commit matching the frozen surface.
  • An explicit allowed_paths set that names only the files under repair.
  • A forbidden_paths set that explicitly excludes frozen invariants.
  • An audit_target that matches the frozen SHA.

The bounded repair must reach FROZEN_PASS before the orchestrator re-runs the original goal.

Governed publication​

Governed publication is the canonical path for publishing a release:

  1. The orchestrator opens a PR.
  2. CI checks pass.
  3. The owner submits an approving GitHub review.
  4. The orchestrator ingests the review → MERGE_APPROVAL gate.
  5. The orchestrator performs the governed merge.
  6. The orchestrator emits a PRODUCTION_PROMOTION gate.
  7. The owner signs the production ticket offline.
  8. The orchestrator verifies the ticket and consumes the gate.
  9. The goal transitions to FROZEN_PASS.

Exact-head review​

When the owner submits a GitHub review, the orchestrator pins the review to the exact subject_sha at the time of the review. If the PR head moves between review and merge, the gate is stale and is rejected. The owner must re-submit a review at the new head.

MERGE_APPROVAL​

MERGE_APPROVAL is a single-use gate. After consumption, dispatches_used reaches max_dispatches and the gate cannot be replayed. To merge again, the owner must re-open a PR and re-submit a review.

PRODUCTION_PROMOTION​

PRODUCTION_PROMOTION is the canonical production gate. The provenance is a signed ticket verified by signed_ticket_verifier.py. The ticket binds:

  • gate_id
  • goal_id
  • subject_sha
  • production_target
  • issuer
  • namespace
  • payload_digest

If any of these is missing or does not match the canonical value, the ticket is rejected.

Deviation accounting​

A deviation is a recorded non-blocking event. The orchestrator increments current_cycle_deviation_count when a deviation is acknowledged. The count is forward-only — there is no way to decrement it.

No retroactive authorization​

ASF50 never retroactively authorizes an action that already happened. If an action was performed without the proper gate, the correct response is:

  1. Acknowledge the deviation.
  2. Open a bounded repair goal.
  3. Fix the root cause.

You may not "authorize" the past action by editing a state field or writing a backdated evidence file.

Historical evidence preservation​

Historical receipts, historical gates, and historical deviation evidence are immutable. The orchestrator refuses to modify them. Revision requires a bounded repair that explicitly opens the historical envelope.