Governance Control Map¶

Purpose¶

Ledger governance is spread across issue metadata, managed comments, pull-request rules, lifecycle labels, project fields, and machine-readable metadata.

This page shows how those surfaces fit together.

Control Surface Map¶

flowchart TD
    A["GitHub issue"] --> B["Issue metadata block"]
    A --> C["Managed execution-state comment"]
    A --> D["Closeout record"]
    A --> E["Lifecycle labels / project status"]

    B --> F["task-routing.yaml"]
    B --> G["issue-governance.yaml"]
    C --> G
    D --> G
    E --> H["project-lifecycle.yaml"]

    I["Pull request"] --> J["PR template fields"]
    J --> K["PR governance model"]
    J --> L["Merge queue / rulesets"]

    F --> M["Required docs / obligations"]
    G --> N["Issue Governance workflow"]
    H --> O["Issue Lifecycle workflow"]
    K --> P["PR Governance workflow"]
    L --> Q["Protected branch behavior"]

What Each Surface Owns¶

Surface	Owns
issue body	task routing, scope, verification plan, evidence plan
managed execution-state comment	live executor, lane, lease, task packet, run, lifecycle execution truth
closeout comment	review, acceptance, and `Ready For Done` truth
labels and project status	visible lifecycle and planning state
PR body	write scope, covered issues, validation summary, closeout expectation
`meta/issue-governance.yaml`	issue-side governance rules and expected fields
`meta/project-lifecycle.yaml`	label and project status alignment rules
`.github/workflows/`	automation that normalizes and checks those surfaces

Issue Path¶

flowchart LR
    A["Issue created"] --> B["Governance metadata present or normalized"]
    B --> C["Lifecycle = Triage or Ready"]
    C --> D["Execution-state comment when active"]
    D --> E["Lifecycle = In Progress"]
    E --> F["PR or review surface"]
    F --> G["Closeout record"]
    G --> H["Lifecycle = Done"]

PR Path¶

flowchart LR
    A["Bounded write scope"] --> B["PR created from template"]
    B --> C["Lead issue and covered issues declared"]
    C --> D["Governance checks pass"]
    D --> E["Queue-protected merge path"]
    E --> F["Issue closeout reconciled"]

Working Distinctions¶

Issue Versus PR¶

issue = planning and control unit
PR = write-scope and review unit

Routing Versus Lifecycle¶

routing = what kind of work this is and what obligations apply
lifecycle = where the work currently is

Metadata Versus Managed State¶

metadata block = relatively stable task description and governance burden
managed execution-state comment = live execution truth
closeout record = acceptance truth at the end

Important Operator Rules¶

Do not treat issue labels alone as full governance truth.
Do not treat PR merge alone as accepted closure.
Do not update managed marker-backed comments casually; they are part of the operational API surface.
Do not invent new marker or field names in normal task work.
For queue-protected branches, merge queue is the default merge path.