baldart 4.32.0 → 4.33.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.33.0] - 2026-06-12
+
+**New opt-in `stack.schema_deploy_from_trunk_only` safety invariant — `/new` + `new2` never push a remote schema/RLS/index/migration deploy from a non-trunk branch or worktree.** Before this release, the Production Readiness checklist (`/new` Phase 7 / `new2` Production phase) and the front-loaded Migration Gate would auto-execute a remote schema deploy (`supabase db push`, `prisma migrate deploy`, `firebase deploy --only firestore:rules|firestore:indexes|storage`, CDK/Terraform apply, any SQL migrator) gated only on `stack.database`/`stack.deployment` — with no guard against running it from an unmerged feature branch / git worktree. On projects that develop multiple cards in parallel worktrees against a single shared remote datastore, that desyncs migration history and produces "code-ahead-of-schema" outages (a real consumer hit a `42703 undefined_column` production outage this way).
+
+The new key is **stack-agnostic and opt-in**, a no-op for projects that don't set it:
+- `false` (default) / unset → current behavior preserved exactly (unset → the skill asks; `baldart configure` defaults it to `true` only when it autodetects parallel worktree usage).
+- `true` → a remote schema/RLS/index/migration deploy is auto-executed **only** when `git rev-parse --abbrev-ref HEAD == git.trunk_branch`. From any non-trunk branch / worktree it is **never** auto-run: the migration stays committed and the remote deploy is deferred ("happens from trunk after merge") and routed to the existing **`db-migration-deploy`** residual class (dedup-collapsed onto one external action).
+
+**The guard enforces only the branch invariant** — the actual deploy command, env loader, and gate UX stay delegated to the project overlay (`.baldart/overlays/new.md`); core does not move the command in. Datastore-agnostic by design (any persistence layer, not Supabase-specific). The principle is documented as a MUST-rule in `production-readiness.md` and the generic `deployment-protocol.md`. **MINOR** (new opt-in config key + capability; default false ⇒ zero behavior change for existing consumers). Schema-change propagation rule applied end-to-end (template + configure prompt/autodetect + update detector + skills + docs + CHANGELOG).
+
+### Added
+
+- **`framework/templates/baldart.config.template.yml`** — new `stack.schema_deploy_from_trunk_only: false` key with documentation.
+- **`src/commands/configure.js`** — `detectWorktreeUsage()` probe (`git worktree list`); the autodetected default and an interactive confirm prompt for the new key (pre-checked when parallel worktrees are detected).
+
+### Changed
+
+- **`framework/.claude/skills/new/references/production-readiness.md`** — new "Schema-deploy-from-trunk-only guard" subsection + a MUST-rule in § Rules: when the flag is on, gate every remote schema/RLS/index/migration auto-deploy on `current branch == git.trunk_branch`, else defer as a `db-migration-deploy` residual.
+- **`framework/.claude/skills/new/references/setup.md`** — Migration Gate (Phase 0 step 1b) honors the same guard: a command modality (front-loaded apply) runs only when `$MAIN` is on trunk; otherwise it degrades to the end-of-batch owner-gated deferral.
+- **`framework/.claude/workflows/new2.js`** — reads `stack.schema_deploy_from_trunk_only`; the Production phase agent gates schema deploys on `HEAD == TRUNK` and returns `schemaDeploysDeferred`, which the workflow converts into `db-migration-deploy` residuals (owner-gated, collapsed by `ownerGatedActionKey`).
+- **`framework/.claude/skills/new2/SKILL.md`** — Migration Gate Step 3.5 step 6 honors the off-trunk guard (degrade to deferred when `$MAIN` is not on trunk).
+- **`src/commands/update.js`** — the `missingStack` schema-drift detector now surfaces boolean scalar `stack.*` keys (not just strings), so `schema_deploy_from_trunk_only` is offered to pre-v4.33.0 consumers on update.
+- **`framework/agents/deployment-protocol.md`** — new datastore-agnostic "Schema deploys run from trunk only" best-practice subsection.
+- **`framework/docs/PROJECT-CONFIGURATION.md`** — documents the new `stack.schema_deploy_from_trunk_only` key in § 4.4.
+
 ## [4.32.0] - 2026-06-11
 
 **`new2`: `deep` is now relevance-gated too — it no longer fires all 5 reviewers on every card regardless of content.** Diagnosing a real batch (the FEAT-0023 supplier-associated-users epic — permissions/RLS/migrations, so 7 of 11 cards are legitimately `review_profile: deep` per `prd-card-writer` Rule C) exposed an **asymmetry**, not a misclassification: the per-card review matrix relevance-gated `balanced` (a specialist runs only if its domain is evidenced by `scopeFiles ∪ MAY-EDIT`) but left `deep` on an **unconditional 5-way fan-out** (`FULL_FANOUT` = code-reviewer + doc-reviewer + qa-sentinel + api-perf-cost-auditor + security-reviewer). So a `deep` card with no doc surface still paid for a doc-reviewer, and one with no API/data surface still paid for api-perf-cost-auditor — every time. This is exactly the "every card gets a full review regardless of what's inside" symptom.

package/VERSION

@@ -1 +1 @@
-4.32.0
+4.33.0

package/framework/.claude/skills/new/references/production-readiness.md

@@ -97,9 +97,38 @@ is wrong for the project, ask the user — never auto-execute a guess.
 | Third-party service config | Requires external dashboards and secrets |
 | DNS / domain changes | Risk of downtime — needs human judgment |
 
+### Schema-deploy-from-trunk-only guard (when `stack.schema_deploy_from_trunk_only: true`)
+
+**Generic, datastore-agnostic safety invariant.** A remote schema mutation — any
+RLS/access-rule deploy, index deploy, or migration `*deploy`/`*push`/apply command
+(`supabase db push`, `prisma migrate deploy`, `firebase deploy --only firestore:rules|firestore:indexes|storage`,
+`cdk deploy` / `terraform apply` of a table/GSI, a SQL migrator against the live DB,
+etc.) — pushed from a **non-trunk branch / git worktree** desyncs the shared remote
+datastore from every other in-flight branch's migration history, producing
+"code-ahead-of-schema" production outages (a real consumer hit a `42703 undefined_column`
+outage this way).
+
+When `stack.schema_deploy_from_trunk_only: true` in `baldart.config.yml`, BEFORE
+auto-executing ANY such remote schema/RLS/index/migration deploy:
+
+1. Resolve the current branch: `git rev-parse --abbrev-ref HEAD`.
+2. **On `git.trunk_branch`** → behave exactly as today (auto-execute when stack-matched).
+3. **On any other branch / worktree** → **NEVER auto-execute.** The migration stays
+   committed; surface a deferral instead — report it as a `MANUAL` item with the note
+   *"migration committed; remote schema deploy happens from `<trunk>` after merge"* and
+   record it under the tracker `## Production Readiness` as a deferred
+   **`db-migration-deploy`** residual. The deploy is not lost — it is intentionally
+   sequenced to run from trunk post-merge.
+
+This guard enforces only the **branch invariant**; the actual command, env loader, and
+gate UX stay delegated to the project overlay (`.baldart/overlays/new.md`). When the key
+is `false` / unset, this section is a no-op and behavior is unchanged. Env-var / DNS /
+secret / feature-flag items are already manual-only and unaffected.
+
 **Auto-execution procedure:**
 
-1. For each auto-executable item detected, run the command immediately.
+1. For each auto-executable item detected, run the command immediately
+   (subject to the Schema-deploy-from-trunk-only guard above when enabled).
 2. Log the result (success/failure) in the tracker under `## Production Readiness`.
 3. In the final checklist output, mark auto-executed items with their result:
    ```
@@ -227,6 +256,7 @@ All GSIs must show `ACTIVE`. `CREATING` → poll; `DELETING` / `UPDATING` → ma
 - Order items by **deployment sequence** (items that must happen first go first — e.g., indexes before code deploy, env vars before code deploy).
 - For each item, include the **reason** (which card/feature requires it) and the **exact command or UI path**.
 - If an item is **uncertain** (e.g., you suspect a new index might be needed but aren't sure), mark it with `VERIFY` and explain what to check.
+- **MUST — schema deploys from trunk only (when `stack.schema_deploy_from_trunk_only: true`):** never auto-execute a remote schema/RLS/index/migration deploy from a non-trunk branch or worktree. Gate on `git rev-parse --abbrev-ref HEAD == git.trunk_branch`; otherwise defer it as a `db-migration-deploy` residual ("deploy happens from trunk after merge"). Datastore-agnostic — applies to every persistence layer, not just one vendor. See the "Schema-deploy-from-trunk-only guard" above.
 - **Update the tracker** with the full checklist under a new `## Production Readiness` section.
 
 ---

package/framework/.claude/skills/new/references/setup.md

@@ -25,6 +25,7 @@
    4. **(declared + artifacts present) Assemble the apply modalities**, in this source order, de-duplicating by `id`: (a) `migration_plan.apply_modalities` from the epic block; (b) a `## Migration modalities` section in `.baldart/overlays/new.md` if present; (c) any project-memory note on how this project applies migrations; (d) the built-in tail `["Già applicata — prosegui", "Abort"]`. Each modality is `{ id, label, command? }`.
    5. **`AskUserQuestion`** — `"La epic dichiara una migrazione DB (<summary>). Va applicata PRIMA del batch così le card downstream verificano contro lo schema reale. Come procedo?"` with up to 4 of the assembled modalities (always include "Già applicata — prosegui" and "Abort" as the last options). This is a legitimate Phase 0 question (Auto Mode does not override it).
    6. **Execute the choice in `$MAIN`** (project env):
+      - **Schema-deploy-from-trunk-only guard** (when `stack.schema_deploy_from_trunk_only: true`): a **command** modality is a remote schema deploy, so it may run only from trunk. Before executing one, check `git -C "$MAIN" rev-parse --abbrev-ref HEAD`; if it is **not** `git.trunk_branch`, do **NOT** apply or prompt for a command modality — write `## Migration\ndeclared but $MAIN is on '<branch>' (not trunk '<trunk>') — front-load deferred per schema_deploy_from_trunk_only (apply from trunk, then re-run)` to the tracker and **proceed to step 2** (the migration falls back to the end-of-batch owner-gated deferral — no regression). "Già applicata — prosegui" stays available (it executes no deploy). When the key is `false`/unset this guard is a no-op.
       - a **command** modality → run it with output to disk (`<cmd> > /tmp/migration-<FIRST-CARD-ID>.log 2>&1`), surface only the exit code; on exit 0 run the optional `migration_plan.verify` probe and require it green too. On **failure** → surface a bounded extract (`tail -n 30`) and re-ask (re-offer the modalities + Abort); never silently proceed against a non-live schema. **Never run a command without the user having selected it.**
       - **"Già applicata — prosegui"** → run the optional `verify` probe if present; otherwise trust the user.
       - **"Abort"** → HALT the batch cleanly (leave the tracker in place); do not create a worktree.

package/framework/.claude/skills/new2/SKILL.md

@@ -115,6 +115,13 @@ untouched), so the schema is live **before** the workflow starts. It mirrors `/n
    Step-2 "ONE pre-launch question" — pre-launch, not a mid-run gate; the zero-ask contract is about
    the *workflow*, which is untouched.
 6. **Execute the choice in `$MAIN`**:
+   - **Schema-deploy-from-trunk-only guard** (when `stack.schema_deploy_from_trunk_only: true`): a
+     **command** modality is a remote schema deploy → run it only from trunk. Check
+     `git -C "$MAIN" rev-parse --abbrev-ref HEAD`; if it is not `git.trunk_branch`, do NOT apply a
+     command modality — set `migration = { status: 'degraded', reason: 'off-trunk: schema_deploy_from_trunk_only' }`
+     and skip to Step 4 (the migration falls back to the workflow's end-of-batch owner-gated deferral →
+     a `db-migration-deploy` residual; apply it from trunk, then re-run). "Già applicata — prosegui"
+     stays valid (no deploy). No-op when the key is `false`/unset.
    - a **command** modality → run with output to `/tmp/migration-<firstCard>.log`, surface only the
      exit code; on exit 0 run the optional `migration_plan.verify` probe and require it green. On
      failure → bounded extract (`tail -n 30`) + re-ask. **Never run a command the user did not pick.**

package/framework/.claude/workflows/new2.js

@@ -60,8 +60,13 @@ const migrationAffects = Array.isArray(migration.affects_cards) ? migration.affe
 const features = cfg.features || {}
 const paths = cfg.paths || {}
 const gitCfg = cfg.git || {}
+const stack = cfg.stack || {}
 const highRisk = paths.high_risk_modules || []
 const mergeStrategy = gitCfg.merge_strategy || 'pr'
+// Stack-agnostic schema-deploy safety invariant (v4.33.0). When true, a remote
+// schema/RLS/index/migration deploy is auto-executed ONLY from the trunk branch;
+// from any other branch/worktree it is deferred as a `db-migration-deploy` residual.
+const schemaDeployFromTrunkOnly = stack.schema_deploy_from_trunk_only === true
 
 // Mutable batch state — the workflow's variables ARE the tracker (kept out of the main loop).
 const firstCard = cardIds[0] || 'BATCH'
@@ -1067,14 +1072,37 @@ if (!committed.length) {
 phase('Production')
 if (mergeResult && mergeResult.merged) {
   try {
+    // Schema-deploy-from-trunk-only invariant (v4.33.0): a remote schema/RLS/index/
+    // migration deploy desyncs a shared remote datastore when run off-trunk. When the
+    // flag is on, the agent gates every such deploy on `current branch == ${TRUNK}` and
+    // returns any off-trunk deploy in `schemaDeploysDeferred` instead of executing it —
+    // we then track each as a `db-migration-deploy` residual (the existing class, dedup-
+    // collapsed onto one external action). Datastore-agnostic; the command itself stays
+    // in the project overlay. No-op when the flag is false/unset.
+    const trunkGate = schemaDeployFromTrunkOnly
+      ? `\nSCHEMA-DEPLOY-FROM-TRUNK-ONLY is ON (stack.schema_deploy_from_trunk_only): a remote schema/RLS/index/migration deploy (supabase db push, prisma migrate deploy, firebase deploy --only firestore:rules|firestore:indexes|storage, cdk deploy / terraform apply of a table/GSI, any SQL migrator against the live DB) may run ONLY from the trunk branch. Run \`git rev-parse --abbrev-ref HEAD\`; auto-execute such a deploy ONLY if it equals \`${TRUNK}\`. On ANY other branch/worktree: DO NOT execute it — instead add it to schemaDeploysDeferred:[{ command, reason }] (reason = "remote schema deploy happens from ${TRUNK} after merge"). Index/cron/env/flag/DNS items are unaffected by this gate.`
+      : ''
     prodReadiness = await agentSafe(
-      `Run the post-merge Production Readiness checklist per ${REF}/production-readiness.md (Phase 7) over the batch's changed files. Auto-EXECUTE only stack-matched index/access-rule/cron deploys; REPORT (do not execute) env vars, feature flags, DB migrations, secrets, DNS. NON-BLOCKING. ROLE BOUNDARY: you EXECUTE commands, you never edit repository files — a needed code/config change is reported as a manual item.\n\n${projectBrief}\nChanged files: ${dedupe(committed.flatMap((r) => r.filesChanged || [])).join(', ') || '(derive from git)'}\n\nReturn: { autoExecuted:[...], manualItems:[...], note }`,
+      `Run the post-merge Production Readiness checklist per ${REF}/production-readiness.md (Phase 7) over the batch's changed files. Auto-EXECUTE only stack-matched index/access-rule/cron deploys; REPORT (do not execute) env vars, feature flags, DB migrations, secrets, DNS. NON-BLOCKING. ROLE BOUNDARY: you EXECUTE commands, you never edit repository files — a needed code/config change is reported as a manual item.${trunkGate}\n\n${projectBrief}\nChanged files: ${dedupe(committed.flatMap((r) => r.filesChanged || [])).join(', ') || '(derive from git)'}\n\nReturn: { autoExecuted:[...], manualItems:[...], schemaDeploysDeferred:[...], note }`,
       // Sonnet, not the inherited opus: a non-blocking report-not-execute checklist (auto-run only
       // stack-matched deploys, REPORT the rest). Sonnet follows the checklist reliably at a fraction
       // of the cost; nothing here gates the merge (it already happened).
       { label: 'production-readiness', phase: 'Production', agentType: 'general-purpose', model: 'sonnet',
-        schema: { type: 'object', required: ['manualItems'], additionalProperties: true, properties: { autoExecuted: { type: 'array', items: { type: 'string' } }, manualItems: { type: 'array', items: { type: 'string' } }, note: { type: 'string' } } } }
+        schema: { type: 'object', required: ['manualItems'], additionalProperties: true, properties: { autoExecuted: { type: 'array', items: { type: 'string' } }, manualItems: { type: 'array', items: { type: 'string' } }, schemaDeploysDeferred: { type: 'array', items: { type: 'object', additionalProperties: true, properties: { command: { type: 'string' }, reason: { type: 'string' } } } }, note: { type: 'string' } } } }
     )
+    // Off-trunk schema deploys the guard withheld → tracked as db-migration-deploy residuals
+    // (owner-gated external action; collapsed by ownerGatedActionKey's db:push branch). The skill
+    // materialises them; the deploy is sequenced from trunk, never silently dropped.
+    let deployDeferred = 0
+    for (const d of (prodReadiness && prodReadiness.schemaDeploysDeferred) || []) {
+      const cmd = (d && d.command) || ''
+      if (!cmd.trim()) continue
+      // Evidence names "migration deploy" so ownerGatedActionKey maps it onto the single
+      // db-migration-deploy action key (one remote deploy pushes all pending migrations).
+      residuals.push({ card: firstCard, kind: 'db-migration-deploy', evidence: `remote schema/migration deploy deferred off-trunk: ${cmd} (${(d && d.reason) || 'deploy from ' + TRUNK + ' after merge'})`, materialized: false, deferralClass: 'owner-gated' })
+      deployDeferred++
+    }
+    if (deployDeferred) ledger(firstCard, 'schema-deploy-trunk-gate', 'DEFERRED', `${deployDeferred} off-trunk schema deploy(s) → db-migration-deploy residual (run from ${TRUNK})`)
     ledger(firstCard, 'phase7-production', 'DONE', `auto=${((prodReadiness && prodReadiness.autoExecuted) || []).length} manual=${((prodReadiness && prodReadiness.manualItems) || []).length}`)
   } catch (_) { ledger(firstCard, 'phase7-production', 'SKIPPED', 'agent failed (non-blocking)') }
 } else {

package/framework/agents/deployment-protocol.md

@@ -161,6 +161,24 @@ Define safe deployment procedures and rollback strategies.
 - Test with production-sized data
 - Have rollback SQL ready
 
+### Schema deploys run from trunk only (datastore-agnostic)
+
+**Never push a schema change to a shared remote datastore from a non-trunk branch
+or git worktree.** A remote schema/RLS/index/migration deploy (`supabase db push`,
+`prisma migrate deploy`, `firebase deploy --only firestore:rules|firestore:indexes`,
+`cdk deploy` / `terraform apply` of a table or index, any SQL migrator against the
+live DB) applied off-trunk desyncs the migration history from every other in-flight
+branch and produces "code-ahead-of-schema" production outages (a stray
+`undefined_column` / missing-table error against the live DB).
+
+The rule is one line: **resolve the migration locally on the feature branch, but run
+the remote deploy only after merge, from the trunk branch.** On projects that develop
+multiple cards in parallel worktrees against a single shared remote datastore this is
+mandatory. BALDART's `/new` + `new2` enforce it automatically when
+`stack.schema_deploy_from_trunk_only: true` (see PROJECT-CONFIGURATION.md): they gate
+every auto-deploy on `current branch == git.trunk_branch` and defer off-trunk deploys
+to a tracked `db-migration-deploy` follow-up instead of executing them.
+
 ## Monitoring During Deployment
 
 Watch these metrics:

package/framework/docs/PROJECT-CONFIGURATION.md

@@ -159,6 +159,9 @@ stack:
   auth_provider: "firebase-auth" # firebase-auth|supabase-auth|clerk|auth0|cognito|nextauth|lucia|custom|none|""
   framework: "nextjs"          # nextjs|remix|sveltekit|astro|nuxt|rails|django|fastapi|express|none|""
   deployment: "vercel"         # vercel|firebase|aws|gcp|cloudflare|render|fly|self-hosted|none|""
+
+  # Schema-deploy safety invariant (since v4.33.0). Default false (no-op).
+  schema_deploy_from_trunk_only: false   # true → /new + new2 auto-deploy schema only from git.trunk_branch
 ```
 
 Skills propose only `canonical` libraries and refuse `forbidden` ones. Empty
@@ -183,6 +186,16 @@ the skill/agent set:
 - `/new` Production Readiness Checklist picks deploy commands matching
   `stack.deployment` + `stack.database` (firebase deploy, vercel deploy,
   supabase db push, CDK/Terraform apply).
+- `stack.schema_deploy_from_trunk_only` (boolean, v4.33.0+, default `false`) is a
+  **stack-agnostic safety invariant**: when `true`, `/new` and `new2` auto-execute a
+  remote schema/RLS/index/migration deploy **only** when the current branch ==
+  `git.trunk_branch`. From any non-trunk branch / git worktree the deploy is never
+  auto-run — the migration stays committed and the remote deploy is deferred ("happens
+  from trunk after merge") and tracked as a `db-migration-deploy` residual. This prevents
+  migration-history desync / "code-ahead-of-schema" outages on projects that build
+  multiple cards in parallel worktrees against one shared remote datastore. The actual
+  command + env loader stay in the project overlay — core only enforces the branch gate.
+  `baldart configure` defaults it to `true` when it detects parallel worktree usage.
 - `security-reviewer` evaluates access rules per `stack.database`
   (Firestore rules, Supabase RLS, Mongo validators, DynamoDB IAM,
   Postgres RLS+GRANT).

package/framework/templates/baldart.config.template.yml

@@ -122,6 +122,28 @@ stack:
   # "render" | "fly" | "self-hosted" | "none" | "".
   deployment: ""
 
+  # Schema-deploy-from-trunk-only safety invariant (since v4.33.0). Stack-agnostic
+  # guard against migration-history desync / "code-ahead-of-schema" production
+  # outages on projects that develop multiple cards in PARALLEL git worktrees
+  # against a SINGLE shared remote datastore.
+  #
+  #   false (default) — preserves current behavior: /new + new2 may auto-execute a
+  #                     remote schema/RLS/index/migration deploy from whatever branch
+  #                     the deploy step runs on.
+  #   true            — a remote schema/RLS/index/migration deploy is auto-executed
+  #                     ONLY when the current branch == git.trunk_branch. From any
+  #                     non-trunk branch / worktree the deploy is NEVER auto-run:
+  #                     the migration stays committed and the remote deploy is
+  #                     deferred ("happens from trunk after merge") and tracked as a
+  #                     `db-migration-deploy` residual / Production-Readiness manual
+  #                     item. Datastore-agnostic: applies to supabase db push, prisma
+  #                     migrate deploy, firebase deploy --only firestore:rules/indexes,
+  #                     CDK/Terraform apply, etc. The actual command + env loader stay
+  #                     in the project overlay — core only enforces the branch gate.
+  #   "" / unset      — skill asks (and suggests persisting the answer). `baldart
+  #                     configure` defaults it to true when it detects worktree usage.
+  schema_deploy_from_trunk_only: false
+
 # ─── FEATURES ────────────────────────────────────────────────────────────
 # Explicit booleans. ALL keys must be present (true | false) once `baldart
 # configure` has run. An absent flag means the user hasn't been asked yet —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.32.0",
+  "version": "4.33.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/configure.js

@@ -99,6 +99,26 @@ function detectTrunkBranch(cwd = process.cwd()) {
   }
 }
 
+/**
+ * Autodetect whether this project develops in parallel git worktrees
+ * (`git worktree list` shows linked worktrees beyond the main one). Used to
+ * default `stack.schema_deploy_from_trunk_only`: parallel worktrees against a
+ * single shared remote datastore are exactly the topology where a worktree-run
+ * schema deploy causes migration-history desync / code-ahead-of-schema outages.
+ * Non-fatal: any failure returns false (the back-compat default).
+ */
+function detectWorktreeUsage(cwd = process.cwd()) {
+  try {
+    const { execSync } = require('child_process');
+    const opts = { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000, encoding: 'utf8' };
+    const out = execSync('git worktree list --porcelain', opts);
+    const count = (out.match(/^worktree /gm) || []).length;
+    return count > 1; // main worktree always counts as 1 — >1 means linked worktrees exist
+  } catch (_) {
+    return false;
+  }
+}
+
 function detect(cwd = process.cwd()) {
   const exists = (p) => fs.existsSync(path.join(cwd, p));
   const findFirst = (...candidates) => candidates.find(exists) || '';
@@ -313,6 +333,10 @@ function detect(cwd = process.cwd()) {
 
   const trunkBranchProbe = detectTrunkBranch(cwd);
   const mergeStrategyProbe = detectMergeStrategy(cwd, trunkBranchProbe.value);
+  // Default schema_deploy_from_trunk_only ON when parallel worktrees are in use
+  // (the topology prone to migration-history desync). Otherwise keep the
+  // back-compat false default — the guard is a no-op unless explicitly enabled.
+  const usesWorktrees = detectWorktreeUsage(cwd);
 
   // ---- Persistence layer (stack.database) --------------------------------
   let detectedDatabase = '';
@@ -404,6 +428,9 @@ function detect(cwd = process.cwd()) {
       auth_provider: detectedAuthProvider,
       framework: detectedFramework,
       deployment: detectedDeployment,
+      // Stack-agnostic schema-deploy safety invariant (v4.33.0). Defaulted ON when
+      // parallel worktrees are detected (the desync-prone topology), else false.
+      schema_deploy_from_trunk_only: usesWorktrees,
       // New: surface the detected monorepo + DS signals so skills can read them.
       monorepo: isMonorepo ? {
         detected: true,
@@ -938,6 +965,17 @@ async function interactivePrompts(merged, detected) {
     merged.stack.deployment || detected.stack.deployment || ''
   );
 
+  // Schema-deploy-from-trunk-only safety invariant (v4.33.0). Pre-checked when
+  // configure detected parallel worktrees — the topology prone to schema desync.
+  const sdftDefault = typeof merged.stack.schema_deploy_from_trunk_only === 'boolean'
+    ? merged.stack.schema_deploy_from_trunk_only
+    : (detected.stack.schema_deploy_from_trunk_only === true);
+  merged.stack.schema_deploy_from_trunk_only = await promptForKey(
+    'Only auto-deploy remote schema/migrations from the trunk branch? (recommended when cards are developed in parallel worktrees against one shared remote DB)',
+    sdftDefault,
+    'confirm'
+  );
+
   return merged;
 }
 

package/src/commands/update.js

@@ -1284,12 +1284,13 @@ async function update(options = {}, unknownArgs = []) {
               .filter((k) => !(k in (cur2.paths || {})));
             const missingGit = Object.keys(tpl.git || {})
               .filter((k) => !(k in (cur2.git || {})));
-            // Scalar (string) top-level stack.* keys — e.g. stack.database,
-            // stack.auth_provider, stack.framework, stack.deployment. Sub-object
+            // Scalar top-level stack.* keys — e.g. stack.database,
+            // stack.auth_provider, stack.framework, stack.deployment (strings) and
+            // stack.schema_deploy_from_trunk_only (boolean, since v4.33.0). Sub-object
             // keys (charting, animation, testing) are intentionally skipped:
             // their drift is handled by individual sub-prompts in configure.
             const missingStack = Object.keys(tpl.stack || {})
-              .filter((k) => typeof tpl.stack[k] === 'string')
+              .filter((k) => ['string', 'boolean'].includes(typeof tpl.stack[k]))
               .filter((k) => !(k in (cur2.stack || {})));
             // Top-level nested config namespaces (e.g. `graph:` since v4.21.0).
             // Unlike `lsp:` (which propagates only via its `has_lsp_layer` flag),