Skip to content

Decision Records and Ownership

Atlas stays reviewable when ownership is explicit and non-local decisions are recorded where future maintainers can find them.

Decision Classes

flowchart TD
    Change[Proposed change] --> Local[Local to one area]
    Change --> Cross[Cross-domain integration]
    Change --> Contract[Contract or compatibility change]
    Cross --> Record[Record rationale]
    Contract --> Record

This decision-class diagram helps maintainers decide when informal reasoning is no longer enough. A cross-domain or contract-affecting change deserves a durable record other people can find later.

Use local judgment for isolated implementation work. When the change crosses domains or alters a documented promise, capture the decision in a durable record instead of leaving it in chat or commit lore.

Ownership Signals

The most reliable ownership signals in this repository are:

  • page-level owner metadata in canonical docs
  • registry or schema ownership fields in configs/
  • suite, report, and runnable ownership metadata emitted by bijux-dev-atlas
  • repository review boundaries in .github/CODEOWNERS

If those signals disagree, resolve the ownership drift before merging the change.

That rule matters because ambiguous ownership leads to slow reviews, duplicated rules, and undocumented handoffs.

Governance Rules

Atlas governance stays honest when one checked-in source owns each durable rule.

  • public behavior belongs in canonical docs and contracts, not in ad hoc notes
  • generated evidence must point back to the checked-in source that defines it
  • ownership changes should update the owning registry or metadata in the same change

ADR Template

Use this minimum structure when a decision needs durable recordkeeping:

# ADR: <clear decision title>

## Context

## Decision

## Consequences

## Source-of-Truth Files

When to Record a Decision

Capture a durable decision record when you:

  • change a contract, schema, or compatibility promise
  • move a boundary between crates, domains, docs, configs, or ops
  • introduce a new canonical automation surface or retire an old one
  • change a workflow that other contributors will need to repeat

Practical Commands

cargo run -q -p bijux-dev-atlas -- governance adr index --format json
cargo run -q -p bijux-dev-atlas -- governance list --format json
cargo run -q -p bijux-dev-atlas -- governance doctor --format json

Use these commands to inspect the current governance state before you add another layer of implied process.

Maintainer Rule

Never rely on "the owner probably knows" or "the context is in the PR" as the only governance mechanism. If future readers need the decision to understand why the repository is shaped this way, record it in a canonical file.

A Good Ownership Check

  • can you point to the owner in docs, config metadata, or CODEOWNERS?
  • can a future maintainer find the decision without reading chat history?

Purpose

This page explains the Atlas material for decision records and ownership and points readers to the canonical checked-in workflow or boundary for this topic.

Stability

This page is part of the canonical Atlas docs spine. Keep it aligned with the current repository behavior and adjacent contract pages.