Decision: cross-team alignment decisions are recorded on the change log

Cross-team alignment decisions are now recorded where platform updates already land: as entries on this change log. When teams align on something — a commitment, a contract, a boundary — the agreement gets a decision record: the status (proposed, accepted, or superseded), the DRI, the stakeholders who were present and their roles, and a link to where the decision was made. Every decision is tagged

decision, so the full decision log is always one click away — a system of record for what was agreed, by whom.

What belongs here — and what doesn’t

This log captures alignment decisions across teams, the kind that otherwise live only in a meeting doc or a Slack thread:

• Cross-team commitments. “Auth needs multi-port support; we have agreed to facilitate it, and the item is now on our roadmap.”
• Contracts and boundaries. “This is how the contract between Cells and Theseus looks” — the agreed shape, with the teams who agreed to it named.
• Scope agreements. What a release includes, what was deliberately deferred, and who signed off.

It is not a log of every minor decision. Routine implementation choices belong in the merge requests and design docs of the component that made them; recording them here would bury the agreements that other teams actually need to find.

The stakeholders on this entry are placeholders — it doubles as the worked example of the format. The first real decision record replaces it as the reference.

Authoring a decision entry

Create a normal change log entry (docs/changelog/YYYY-MM-DD-<slug>.md), title it Decision: <what was decided>, include decision in its tags, and add the decision block to the frontmatter:

decision:
  status: accepted            # proposed | accepted | superseded
  dri: "Full Name"
  stakeholders:
    - { name: "Full Name", role: "Accountable" }
    - { name: "Full Name", role: "Consulted" }
  source: https://gitlab.com/...   # the issue, epic, or doc of record

The body should carry the decision in prose: the context, what was decided, what the alternatives were, and what the decision means for teams. Keep the durable detail in the linked source of record; the entry is the communication, not the archive.

When a decision is later reversed or replaced, do not edit history: publish a new decision entry, set the old one’s status to superseded, and link the two.