baldart 4.27.2 → 4.28.1

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.28.1] - 2026-06-11
+
+**Doc: list the `new.migration-example.md` overlay example in the overlays README.** Completes the v4.28.0 Migration Gate docs — the example overlay file shipped in v4.28.0 was not yet listed in the `framework/templates/overlays/README.md` example table. **PATCH** (doc-only).
+
+### Changed
+
+- **`framework/templates/overlays/README.md`** — added the `new.migration-example.md` row (Migration-Gate apply modalities for `/new` Phase 0 step 1b · `new2` Step 3.5).
+
+## [4.28.0] - 2026-06-11
+
+**`new2`: front-loaded Migration Gate — declared DB migrations are applied BEFORE the batch, so downstream cards verify against a live schema.** The workflow runs autonomously and cannot apply an owner-gated DB migration mid-run, so a declared migration was deferred to end-of-batch — and every downstream card was built/verified against a schema not yet live (`validation_commands` / QA / E2E / DB-generated `tsc` types fail falsely → those cards cascade into deferral). The new gate runs in the **skill** (the main loop, which can interact — the workflow's zero-ask contract is untouched), mirroring `/new` Phase 0 step 1b: it finds the batch epic's `migration_plan` (`required: true`), verifies artifacts on disk, assembles apply modalities (epic `apply_modalities` + `.baldart/overlays/new.md` `## Migration modalities` + project memory + built-in `Già applicata`/`Abort`), asks ONE pre-launch question, executes the chosen modality in `$MAIN`, and passes a `migration` manifest into the workflow. **MINOR** (additive capability on the EXPERIMENTAL `new2` surface; the gate is a silent no-op when no migration is declared and degrades to today's end-of-batch deferral when artifacts are missing — no regression; the `migration` arg is the skill→workflow contract only, NOT a `baldart.config.yml` key, so the schema-change propagation rule does not apply).
+
+### Added
+
+- **`framework/.claude/skills/new2/SKILL.md` Step 3.5 — Migration Gate.** BLOCKING only when a migration is declared; otherwise a silent no-op. Emits the `migration = { status: 'none'|'applied'|'skipped'|'degraded', modality?, summary?, artifacts?, affects_cards? }` manifest passed to the workflow (Step 4 args block). The final-record step also logs `migration_gate: <status>` so the A/B comparison stays honest about when a migration was front-loaded (a pre-launch interaction, NOT a mid-batch question — the zero-ask-during-batch invariant holds).
+- **`framework/.claude/workflows/new2.js` — migration manifest consumption.** Reads `a.migration` (args contract documented), and when `status === 'applied'` injects an EXCEPTION to the F-016 owner-gated rule in the preflight (the schema-apply / db-push AC of the affected cards must NOT be classified as a policy-deferred AC — it is satisfied) and a `MIGRATION LIVE` note into each affected card's brief (run REAL validation against the live schema, do not defer or build against an absent schema). A migration NOT covered by the manifest still follows the existing end-of-batch owner-gated deferral.
+
 ## [4.27.2] - 2026-06-11
 
 **`new2` resolve: kill the second self-judging adversarial pass for `security` too.** v4.27.1 removed the wasteful adversarial doc review (doc-reviewer judging doc-reviewer). An audit of every fixer→judge pair in the resolution pass found `security` is the exact same structural case: the fixer is `security-reviewer` (protected domain) and so is the judge, so the mandatory cross-check was `security-reviewer` judging `security-reviewer` — no cross-model diversity, the same waste. The skip is now driven by a structural guard, `selfJudges = (fixerAgent === judgeAgent)`, instead of a per-domain allowlist, so it covers doc + security today and can't silently regress if the fixer/judge map changes. Every domain where fixer ≠ judge (ui/perf/test/code/migration) keeps the mandatory adversarial cross-check unchanged. **PATCH** (cost/latency optimization on the EXPERIMENTAL `new2` surface; no config key, no change to `/new`).

package/VERSION

@@ -1 +1 @@
-4.27.2
+4.28.1

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

@@ -223,4 +223,8 @@ returns when the batch is done. It returns:
    `residualFollowups.length` — which double-counts). `total_tokens`/`agent_count` come from the
    workflow; if `total_tokens` is null, run the `/new` Phase-8 `-stats` script to backfill real
    `usage`. Keep `degraded`/`degradation_reasons` + `cards_deferred_done_pending` in the record so
-   the A/B comparison stays honest. Do NOT re-summarise the cards — the workflow already did.
+   the A/B comparison stays honest. Also record `migration_gate: <migration.status>`
+   (`none`|`applied`|`skipped`|`degraded`) — the Step-3.5 gate is a pre-launch interaction, NOT a
+   mid-batch question, so it does not break the zero-ask-during-batch invariant; logging it keeps the
+   A/B honest about when a migration was front-loaded. Do NOT re-summarise the cards — the workflow
+   already did.

package/framework/.claude/skills/prd/assets/epic-template.yml

@@ -143,6 +143,34 @@ execution_strategy:
     - "{{FEAT-XXXX-N}} e {{FEAT-XXXX-M}} entrambi modificano {{file}} — forzato sequenziale"
     # omit if no conflicts
 
+# =============================================================================
+# Migration Plan (OPTIONAL — declare ONLY when the epic needs a DB schema change
+# applied BEFORE its cards run). Read by /new (Phase 0 step 1b) and new2 (Step 3.5):
+# the skill front-loads the migration interactively so downstream cards verify
+# against the LIVE schema instead of a deferred one. Project-specific — the shape of
+# `apply_modalities` (db:push, local apply, …) belongs in the consumer's
+# `.baldart/overlays/new.md`; see framework/templates/overlays/new.migration-example.md.
+# OMIT this block entirely when the epic introduces no schema change (the common case;
+# the gate then stays a silent no-op). The migration `artifacts` must already exist on
+# disk to be applied up-front — if absent, the gate degrades to the current
+# end-of-batch owner-gated deferral.
+# =============================================================================
+
+# migration_plan:
+#   required: true
+#   summary: "{{Add bookings.status enum column + composite index}}"
+#   artifacts:
+#     - {{supabase/migrations/20260611_add_status.sql}}
+#   apply_modalities:                 # de-duped by id; merged with overlays/new.md + project memory
+#     - id: remote-push
+#       label: "db:push al DB remoto (eseguito dalla skill su tua approvazione)"
+#       command: "{{npx supabase db push}}"
+#     - id: local
+#       label: "Applica in locale"
+#       command: "{{npx supabase db reset --local}}"
+#   affects_cards: [{{FEAT-XXXX-02}}, {{FEAT-XXXX-03}}]   # downstream che richiedono lo schema live
+#   verify: "{{npx supabase gen types typescript --local | head}}"   # opzionale — probe post-apply
+
 # =============================================================================
 # Canonical Docs (epic-level — children inherit subset)
 # =============================================================================

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

@@ -20,6 +20,10 @@ export const meta = {
 //   metricsDir     string     paths.metrics (telemetry dir)
 //   refModulesBase string     dir holding /new reference modules (semantic SSOT)
 //   config         object     parsed baldart.config.yml (paths.*/stack.*/features.*/git.*)
+//   migration      object     Migration Gate manifest (skill Step 3.5): { status:'none'|'applied'|
+//                             'skipped'|'degraded', modality?, summary?, artifacts?, affects_cards? }.
+//                             status:'applied' → the declared schema is LIVE before the batch, so the
+//                             affected cards' apply-AC is NOT owner-gated-deferred (F-016 exception).
 //   flags          { stats, effort, full }
 //   ts             string     ISO timestamp injected by the skill (Date.now() is unavailable here)
 //
@@ -45,6 +49,12 @@ const METRICS = a.metricsDir || 'docs/metrics'
 const REF = (a.refModulesBase || '.claude/skills/new/references').replace(/\/$/, '')
 const FLAGS = a.flags || {}
 const TS = a.ts || ''
+// Migration Gate manifest (skill Step 3.5 — front-loaded BEFORE this workflow ran). When
+// status:'applied', the declared schema is LIVE on the active DB, so its apply-AC must NOT be
+// re-classified as an owner-gated policy-deferred AC (F-016) — the downstream cards verify for real.
+const migration = a.migration || { status: 'none' }
+const migrationApplied = migration && migration.status === 'applied'
+const migrationAffects = Array.isArray(migration.affects_cards) ? migration.affects_cards : []
 const features = cfg.features || {}
 const paths = cfg.paths || {}
 const gitCfg = cfg.git || {}
@@ -230,6 +240,9 @@ try {
       `• cardGraph (REQUIRED, F-021): for every runnable card return { id, dependsOn:[IN-BATCH deps only], ownerAgent (the card's owner_agent; G25 unknown→'coder'), reviewProfile (the card's review_profile; default 'balanced'), policyDeferredACs, alreadyCommitted, alreadyCommittedSha, isEpic (implement.md §6b epic guard: id ends '-00' OR filename ends '-epic.yml' OR group.is_epic:true OR review_profile 'skip' with no requirements), filesLikelyTouched (verbatim from the YAML) }.\n` +
       `• B1/F-026 idempotency (per card, AFTER the worktree exists): set alreadyCommitted:true (+ alreadyCommittedSha) IFF ALL hold: (a) a commit referencing the card id exists in ${TRUNK}..HEAD of the worktree; (b) the card's validation_commands re-run GREEN right now; (c) NO open follow-up card for it exists in ${paths.backlog_dir || 'backlog'}. On a FRESH worktree ${TRUNK}..HEAD is empty → all false, zero extra work.\n` +
       `• F-016 AC↔ownership consistency: for each acceptance_criterion, derive the file(s) it requires editing. If those files are NOT a subset of the card's MAY-EDIT/files_likely_touched → add the AC to policyDeferredACs:[{n,text,owningCard|owningFile,reason}] (it will become ONE follow-up, never a resolve). Do the same for any AC whose remedy is an owner-gated infra action (remote db push / deploy / secret / DNS).\n` +
+      (migrationApplied
+        ? `• MIGRATION ALREADY APPLIED (skill Migration Gate, Step 3.5): the DB migration "${migration.summary || '(declared)'}" was applied to the active DB BEFORE this batch — the schema is LIVE. EXCEPTION to the F-016 owner-gated rule above: do NOT classify the schema-apply / "run migration" / db-push AC of card(s) [${migrationAffects.join(', ') || '(affects_cards from the epic)'}] as policyDeferredAC — it is SATISFIED. Those cards must run REAL validation against the live schema (validation_commands, queries, DB-generated types), not defer it. (A migration NOT covered by this manifest still follows the owner-gated deferral above.)\n`
+        : '') +
       `• Ownership (setup.md 3c): build the file-ownership map → /tmp; return ownershipMapPath. F-040: each card's MAY-EDIT = files_likely_touched ∪ every path NAMED EXPLICITLY in that card's acceptance_criteria/definition_of_done (an ADR the DoD says to update, the data-model / ER doc for a schema-change, etc.) — so editing a DoD-mandated doc is NOT a file-diff violation. Do NOT add another card's files this way.\n` +
       `• Do NOT write architecture baselines — the per-card codebase-architect specialist does that during the card pipeline (B7).\n\n` +
       `Return the structured PREFLIGHT object. ok:false ONLY if the workspace is unworkable.`,
@@ -429,7 +442,10 @@ async function runCard(cardId, cardPath) {
     return { card: cardId, status: 'committed', commit: node.alreadyCommittedSha || '-', filesChanged: [], scopeFiles: [], archBaselinePath: `/tmp/arch-baseline-${cardId}.md`, gates }
   }
 
-  const cardBrief = `${projectBrief}\n\nCard: ${cardId}\nCard YAML: ${cardPath}\nOwner agent: ${ownerAgent} · Review profile: ${reviewProfile}\nWorktree: ${sharedCtx.worktreePath} (cd into it)\nFile-ownership map: ${sharedCtx.ownershipMapPath}\nNOTE: ACs already pre-classified as policy-deferred MUST NOT be implemented or routed — they are tracked as follow-ups.`
+  const migrationNote = (migrationApplied && migrationAffects.includes(cardId))
+    ? `\nMIGRATION LIVE: the DB migration "${migration.summary || '(declared)'}" was applied to the active DB BEFORE this batch (skill Migration Gate). The schema is REAL — run actual validation against it (validation_commands, queries, DB-generated types); do NOT defer the schema-apply AC or build against an absent schema.`
+    : ''
+  const cardBrief = `${projectBrief}\n\nCard: ${cardId}\nCard YAML: ${cardPath}\nOwner agent: ${ownerAgent} · Review profile: ${reviewProfile}\nWorktree: ${sharedCtx.worktreePath} (cd into it)\nFile-ownership map: ${sharedCtx.ownershipMapPath}\nNOTE: ACs already pre-classified as policy-deferred MUST NOT be implemented or routed — they are tracked as follow-ups.${migrationNote}`
 
   // --- Phase 1 (B7, v4.26.0) — SPECIALIST decomposition: each Phase-1 duty runs as its own
   // agent ("ognuno fa una cosa"), with handoff via /tmp files so the owner's context stays
@@ -966,6 +982,10 @@ function buildTelemetry() {
     cards_followup: perCardResults.filter((r) => r.status === 'followup').length,
     cards_blocked: runnableCards.filter((id) => state[id] === 'blocked').length,
     cards_deferred: residuals.filter((x) => x.kind === 'policy-deferred-ac').length,
+    // Migration Gate (skill Step 3.5, pre-launch — NOT a mid-batch question, so the zero-ask-during
+    // -batch invariant is intact). 'applied' = schema front-loaded; the affected cards' apply-AC was
+    // satisfied up-front instead of deferred owner-gated.
+    migration_gate: (migration && migration.status) || 'none',
     residuals_total: residuals.length,
     // followups_on_disk is filled by the SKILL after it materialises pending residuals.
     followups_materialized_in_workflow: residuals.filter((x) => x.materialized).length,

package/framework/templates/overlays/README.md

@@ -50,6 +50,7 @@ Full protocol: [`framework/agents/project-context.md`](../../agents/project-cont
 |------|------|
 | `ui-design.fidelity-example.md` | Neo-Brutalism, Recharts/nivo charting stack, merchant theming pairing, Safari open command, evaluation thresholds |
 | `copywriting.fidelity-example.md` | 4-pillar brand voice, Italian-only rule, segment register matrix (customer/merchant/staff/admin), forbidden vocabulary |
+| `new.migration-example.md` | Migration-Gate apply modalities (`/new` Phase 0 step 1b · `new2` Step 3.5) — how this project front-loads a declared DB migration (db:push / local apply / Prisma deploy) before the batch |
 
 Other overlay examples may be added over time. Skills that did not have
 heavy hard-coded opinions (e.g. `find-skills`, `simplify`) don't need

package/framework/templates/overlays/new.migration-example.md

@@ -0,0 +1,60 @@
+---
+base_skill: new
+base_skill_version: 4.28.0
+mode: extend
+---
+
+# new — migration-gate overlay (example)
+
+> Drop this into your repo at `.baldart/overlays/new.md` (it is shared by `/new`
+> **and** `new2`) to teach the **Migration Gate** how *your* project applies a DB
+> schema change. The gate runs **before** the batch (/new Phase 0 step 1b · new2
+> Step 3.5): when an epic card declares a `migration_plan`, the skill front-loads
+> the migration interactively so downstream cards verify against the **live**
+> schema instead of one deferred to the end of the batch.
+>
+> Two layers cooperate:
+> 1. **The epic card** declares *that* a migration is needed + the artifacts
+>    (`migration_plan` block — see `epic-template.yml`).
+> 2. **This overlay** declares *how* this project applies migrations (the
+>    `## Migration modalities` section below). The gate merges the epic's
+>    `apply_modalities` with these, de-duped by `id`, and adds the built-in
+>    `["Già applicata — prosegui", "Abort"]` tail.
+>
+> Adapt the commands to your stack (Supabase / Prisma / Drizzle / raw SQL / …).
+
+## Migration modalities
+
+These are offered (via `AskUserQuestion`) whenever an epic declares
+`migration_plan.required: true` and its `artifacts` exist on disk. The skill runs
+the chosen `command` in the main repo (`$MAIN`), captures output to
+`/tmp/migration-<first-card>.log`, surfaces only the exit code, and — when the
+`migration_plan.verify` probe is present — requires it green too. A command is
+**never** run without the user selecting it.
+
+- **id: `remote-push`** — applica al DB remoto/condiviso (owner-gated; eseguito
+  dalla skill SOLO su tua approvazione esplicita).
+  - command: `npx supabase db push`
+  - When to pick: dev DB condiviso o staging dove le card verificano contro il
+    DB reale.
+- **id: `local`** — applica a un DB locale/shadow; la prod resta un deploy
+  manuale post-merge (Phase 7 lo riporta come item manuale).
+  - command: `npx supabase db reset --local` *(oppure `npx prisma migrate dev`)*
+  - When to pick: il batch verifica contro un DB locale effimero.
+- **id: `prisma-deploy`** — esempio Prisma per uno stack diverso.
+  - command: `npx prisma migrate deploy`
+
+> Verifica post-apply consigliata (referenziata da `migration_plan.verify`
+> nell'epic): rigenera i tipi dal DB così `tsc` downstream è onesto, es.
+> `npx supabase gen types typescript --local > src/types/db.ts` oppure
+> `npx prisma generate`.
+
+## Notes
+
+- Se l'epic NON dichiara `migration_plan` (o `required: false`), il gate è un
+  **no-op silenzioso** — nessun prompt aggiuntivo, comportamento identico a oggi.
+- Se gli `artifacts` non esistono ancora su disco, il gate **degrada**: non
+  applica nulla e la migrazione segue il path owner-gated di fine batch (nessuna
+  regressione). La migrazione va autorata prima per essere front-loaddata.
+- Le modalità possono anche arrivare dalla **memoria di progetto** (oltre che da
+  questo overlay e dal blocco epic): la skill le unisce tutte.

package/package.json

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