Files

Angelo B. J. Luidens 1dc1a1a07a Stage 0: governance scaffolding + monorepo bootstrap

Phase 1 foundation for the Stargue Publishing Engine (plan v2, BMAD
panel-reviewed 2026-04-19 — 1 APPROVE, 6 REVISE, 0 REJECT; all principles >=3).

- Governance doctrine adopted from DQMS
  (.clinerules/12-foundational-principles.md,
  .claude/hooks/gate-plan-exit.sh, .claude/skills/bmad-plan/SKILL.md)
- Bun workspaces + Turbo; apps/{mcp-linkedin,scheduler,admin};
  packages/{schema,sanitize,linkedin-client,observability}
- Drizzle schema (content, publications, approvals, metrics,
  linkedin_tokens, audit, outlet_feature_flags) with idempotency_key
  UNIQUE and kill-switch table per TEA/dev panel revisions
- LinkedIn API canon: Posts API /rest/posts (not legacy UGC); OAuth
  auth-code without PKCE; secretbox (not sealed-box); Community
  Management API as separate approval gate from MDP
- Frontmatter Zod schema (status, language, outlets[], sanitize,
  scheduled, version)
- Pino observability with PII redaction
- Expand-then-contract migration runbook
- Plan + panel verdicts mirrored to docs/plans/
- Deferred gates logged (Dokploy PaaS verification, LinkedIn Dev
  Portal app registration)

bun install + bun run typecheck both exit 0 across 11 workspaces.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-19 07:22:07 -04:00

1.7 KiB

Raw Blame History

Database migrations — runbook

Authoring rule: every schema change follows expand-then-contract sequencing. A breaking change is split into ≥2 migrations with a rollback point between them.

Pattern

Phase	Migration files	What it does	Rollback
1. Expand	`NNNN_expand_<change>.sql`	Add new nullable column / new table / new index. Old code keeps working.	Drop the new addition.
2. Backfill	`NNNN_backfill_<change>.sql` (if data migration needed)	Populate the new column from existing data. Idempotent.	Re-run or delete column.
3. Constrain	`NNNN_constrain_<change>.sql`	Add NOT NULL / UNIQUE / FK / CHECK now that data is populated.	Drop the constraint.
4. Contract	`NNNN_contract_<change>.sql`	Remove the old column / table once no code reads it. Only after ≥1 deploy cycle of the new code.	Restore from `pg_dump`.

Mandatory for every migration

migrations/NNNN_<name>.sql — the forward migration.
migrations/NNNN_<name>.down.sql — the rollback SQL.
An entry below in the Registry with rationale, linked plan, and rollback cost estimate.

Registry

#	Date	Name	Plan	Forward cost	Rollback cost	Notes
—	—	—	—	—	—	No migrations yet — first migration lands in Stage 2.1

Rehearsal

Stage 2.2 DoD: every schema change is rehearsed end-to-end on staging before production. Command:

bun run db:migrate:rehearse

Rehearsal must cover: forward → backfill (if applicable) → constrain → contract, with a row-count + row-hash check at each step.

Incidents

Any migration incident gets a post-mortem in docs/incidents/YYYY-MM-DD-migration-<name>.md.

1.7 KiB Raw Blame History