transcription/docs/adr/ADR-0002-explicit-schema-bootstrap-policy.md

ADR-0002: Explicit schema bootstrap policy

• Status: accepted
• Date: 2026-06-25

Context

MVP called schema bootstrap (create_all) on every startup. REQ-10 requires explicit, opt-in schema bootstrap behavior so normal production startup does not mutate schema.

Decision

Add environment-aware bootstrap policy:

1. New settings:
   • environment: development | test | production
   • bootstrap_schema_on_startup: optional explicit override
2. Default behavior:
   • Development/test: bootstrap enabled
   • Production: bootstrap disabled
3. App startup calls create_all only when policy evaluates true.

Consequences

Positive

• Production startup behavior is safer and policy-driven.
• Local development remains simple by default.

Tradeoffs

• Deployments now require explicit schema management in production.

Alternatives Considered

1. Always bootstrap in all environments
   • Rejected: violates REQ-10 intent.
2. Disable bootstrap everywhere immediately
   • Rejected: hurts local developer workflow without migration tool replacement yet.