ADR Operating Rules

ADR Operating Rules

ADR is not a meeting note or default paperwork. Most changes use the PR Merge Court block as the decision record.

Required PR Mode

Every PR must declare adr_operating_mode in the Merge Court YAML block:

adr_operating_mode: proposal-only

Allowed values:

• proposal-only: default. Local, reversible, or implementation-level change. PR metadata plus evidence is enough.
• adr-required: new stack, cross-context boundary, authorization or secret lifecycle, data contract, irreversible migration, cost/SLO, or platform topology decision.
• adr-update: changes an existing ADR, constitution page, or operating rule. Update the owner document and remove stale duplicate guidance.
• adr-not-applicable: generated change, docs-only correction, fixture refresh, or no architecture decision.

Fast Path

Use proposal-only unless the change crosses a real architecture boundary.

For proposal-only, required content is:

• one sentence decision
• changed files or affected truth planes
• proof command, metric, screenshot, or live evidence
• rollback class

No standalone ADR file. No duplicated rationale in comments.

ADR Path

Use adr-required or adr-update only when one of these is true:

• ownership moves between bounded contexts
• new external OSS, SaaS, storage plane, identity plane, or workflow engine is introduced
• Kubernetes topology, Gateway/API edge, OpenBao/ESO/SPIRE/SpiceDB, CNPG, object storage, or shared cache policy changes
• data model, contract schema, or CQRS command/query boundary changes
• migration is irreversible without explicit rollback
• cost, latency, build time, or reliability SLO changes

ADR text must fit one screen:

• Context
• Decision
• Consequences
• Evidence
• Supersedes or updates

If it does not fit, split the proposal.

Agent Rules

Agents must not stall delivery to write broad architecture prose. They choose one adr_operating_mode, attach proof, and continue.

Agents must reject and return a PR when:

• mode is missing
• mode is not one of the allowed values
• adr-required claims implementation complete but has no ADR/evidence link
• proposal-only hides a cross-context or irreversible decision

Merge Court Example

proposal_key: proposal.fractalops.example
evidence_key: evidence.fractalops.example
affected_truth_planes: [Portal, Agent Control Surface]
approval_class: human-review
rollback_class: git-revert
adr_operating_mode: proposal-only
constitutional_pass: true

DataHub Scope

ADRs are projected into the DataHub context graph so an AgentSquad can query decision context by direct URN instead of re-deriving or RAG-searching Markdown. The ingest (ops/semantics/adr_datahub_ingest.py, run idempotently by the adr-datahub-ingest workflow on any ADR change) creates, per ADR, a GlossaryTerm + Tag urn:li:glossaryTerm:<project>-adr-ADR-NNNN attached to Domain urn:li:domain:<project>.

Scope is set by ADR frontmatter:

• No project field → global fractalops architecture scope. Cross-cutting architecture decisions live here and are shared by every squad.
• project: <slug> → per-project scope. A decision that belongs to one project’s subgraph stays isolated to that project.

The agent MCP tool get_project_adr_context resolves the squad’s own <project>-adr-* terms first, then falls back by direct URN to the global fractalops-adr-* architecture layer (adopted convention “option A”). It never runs a global adr:* search and never reads another project’s Markdown — direct-URN only, so per-project isolation holds while shared architecture still surfaces.