DevRunbook-Public/adr/ADR-001-git-first-content.md

ADR-001 — Git-first canonical playbook content

Status

Accepted

Context

Built-in playbooks need human review, semantic versioning, reproducible releases, package export and transparent diffs. Storing only opaque database rows would weaken these workflows.

Decision

Canonical built-in content is stored as YAML/Markdown packages in Git. The application validates, canonicalizes and indexes immutable versions into PostgreSQL. Private authoring may use database drafts but exports the same package format.

Consequences

Positive:

• ordinary Git review and history;
• portable packages;
• reproducible catalog builds;
• CI validation;
• no database lock-in for authored content.

Negative:

• import/index synchronization required;
• file and database lifecycle must be clearly separated;
• package migrations need tooling.