baldart 5.4.1 → 5.5.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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).
 
+## [5.5.0] - 2026-07-03
+
+**Migration deploy chain hardened (FEAT-0067 post-mortem — mayo).** The batch's DB
+migration was fully declared in the cards (`db_migration` + `db_migrations_summary`,
+per the consumer's prd-card-writer overlay) but the remote `db:push` was never
+executed nor surfaced: new2's Migration Gate probed ONLY `migration_plan` (structural
+vocabulary mismatch → silent no-op) and the end-of-batch `db-migration-deploy`
+residual was lost by the mid-run DONE-flip, closing the epic against an unmet DoD.
+
+- **Vocabulary aliases** (`/new` 2.2.1, `new2` 1.7.0): the `-auto` delegation gate,
+  `/new` Phase 0 1b and new2 Step 3.5 now detect a declared migration under
+  `migration_plan.required` (epic) OR `db_migrations_summary` (epic) OR
+  `db_migration.required: true` (per-card overlay convention).
+- **new2 Step 5.1b Migration Sync Tail (NEW)**: after the autonomous workflow returns
+  (post-merge, on trunk), the SKILL runs the project's post-merge sync check
+  (overlay "branch B"); on red it asks Push now / Defer / Override interactively —
+  never pushes autonomously. Triggered by the Step-3.5 DECLARATION, not only by the
+  residual ledger (belt-and-braces vs a dropped residual). Telemetry
+  `migration_sync_tail`.
+- Codex parity: portable (prose-only skill/reference edits; `new2` is Claude-only by
+  design — `/new` classic remains the Codex path and gains the same alias probe).
+
 ## [5.4.1] - 2026-07-03
 
 **Minimal light lane — the roster for a simple card is now literally: grounding (inline),

package/VERSION

@@ -1 +1 @@
-5.4.1
+5.5.0

package/framework/.claude/skills/new/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 2.2.1 — 2026-07-03 (FEAT-0067 post-mortem: migration vocabulary aliases)
+
+- Il gate di delega `-auto` (condizione 4) e il Migration Gate Phase 0 1b (setup.md
+  step 2) ora rilevano una migrazione dichiarata sotto QUALSIASI vocabolario:
+  `migration_plan.required` (epic), `db_migrations_summary` (epic),
+  `db_migration.required: true` (per-card, convenzione overlay consumer). Una
+  migrazione dichiarata solo via alias con artifact non ancora su disco degrada come
+  oggi (missing-artifact) ma la dichiarazione viene SEMPRE registrata nel tracker —
+  il sync post-merge e il ledger dei follow-up devono conoscerla.
+
 ## 2.2.0 — 2026-07-03 (framework v5.4.1)
 
 - **Minimal light lane — roster cut to the core four.** A single light card now runs:

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

@@ -1,7 +1,7 @@
 ---
 name: new
 effort: medium
-version: 2.2.0
+version: 2.2.1
 description: >
   Orchestrate a team of specialized agents to implement one or more backlog cards
   end-to-end inside a dedicated worktree, with code review, doc review, QA, and
@@ -66,10 +66,16 @@ kickoff, right after arg parsing):
 2. `FORCE_INLINE == false` (the user did not pass `-inline`).
 3. The `Workflow` tool is available in this session AND `.claude/workflows/new2.js`
    is linked AND the `new2` skill is available.
-4. No epic card in the batch declares `migration_plan.required: true` (cheap YAML
-   probe on the batch's `group.parent` epics). A declared migration keeps the
-   classic path — its Phase 0 step 1b owns the owner-gated apply under
-   § "AUTONOMOUS RESOLUTION RULE"; `new2`'s own migration gate is interactive.
+4. No card in the batch declares a DB migration, under ANY of the recognized
+   vocabularies (cheap YAML probe): epic `migration_plan.required: true`, epic
+   `db_migrations_summary` (non-empty), or a batch card with
+   `db_migration.required: true` (the consumer-overlay convention — e.g. mayo's
+   prd-card-writer overlay). A declared migration keeps the classic path — its
+   Phase 0 step 1b owns the owner-gated apply under § "AUTONOMOUS RESOLUTION
+   RULE"; `new2`'s own migration gate is interactive. *Why the aliases are
+   load-bearing*: probing only `migration_plan` silently classified a
+   `db_migration`-declaring batch as migration-free (FEAT-0067 post-mortem — the
+   remote `db:push` was never surfaced).
 
 **Action**: log ONE tracker line `[DELEGATED] -auto batch → new2 engine
 (off-context): <residual args>` and invoke the `new2` skill with the SAME residual

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

@@ -22,7 +22,7 @@
 1b. **Migration Gate (BLOCKING only when a migration is *declared* — else a silent no-op)** — resolve DB migrations interactively **before** the worktree exists, so the schema is live before any card builds against it. *Why this exists*: a migration applied to a shared/remote DB is owner-gated, so without this gate it is deferred to the END of the batch — and every downstream card in the batch is then built and verified against a schema that is not yet live (`validation_commands` / QA / E2E / DB-generated `tsc` types fail falsely → those cards cascade into deferral/blocked). Front-loading the migration removes that root cause. **The declaration lives in the EPIC card** (`migration_plan` block — project-specific, authored by the user, typically via the `.baldart/overlays/new.md` overlay). Steps:
 
    1. **Find the batch's epic card(s).** Collect the distinct `group.parent` of the batch cards (or, for a `-full` invocation, the parent already known). For each, locate the epic YAML in `${paths.backlog_dir}` (filename `<PARENT>-*-epic.yml`, or the card whose `id == <PARENT>` / `group.is_epic: true`) and Read it.
-   2. **Look for `migration_plan` with `required: true`.** If **no** epic in the batch declares one → write `## Migration\nnone (no migration_plan declared)` to the tracker and **proceed to step 2** (behaviour is identical to today — zero extra prompts). This is the common case; do not surface anything.
+   2. **Look for a declared migration — under ANY recognized vocabulary.** Primary: epic `migration_plan` with `required: true`. **Compat aliases (consumer-overlay conventions — same semantics, different field names)**: epic `db_migrations_summary` (non-empty), or any batch card carrying `db_migration.required: true` (map: `artifacts` ← each `db_migration.expected_file`; `summary` ← the slug; apply/push modalities ← `db_migration.remote_push` + the overlay's post-merge section; no `verify` unless declared). A migration declared ONLY via alias whose `expected_file` does not yet exist on disk (it will be authored mid-run by the coder) follows the step-3 missing-artifact degradation — but the declaration itself MUST still be recorded in the tracker (`## Migration\ndeclared (via db_migration) — deferred to post-merge sync`) so the post-merge Migration Sync step and the follow-up ledger know about it. If **nothing** declares a migration → write `## Migration\nnone (no migration declared)` to the tracker and **proceed to step 2** (behaviour is identical to today — zero extra prompts). This is the common case; do not surface anything.
    3. **(declared) Verify the artifacts exist on disk.** For each path in `migration_plan.artifacts`, check it exists under `$MAIN`. If **any is missing** → do **NOT** apply or prompt; write `## Migration\ndeclared but artifact(s) missing: <paths> — degraded to deferred (author the migration first)` to the tracker and **proceed to step 2** (the migration falls back to the current end-of-batch owner-gated deferral — no regression). *(Auto-generating a missing artifact is out of scope; the migration must already be authored to be applied up-front.)*
    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).

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

@@ -2,6 +2,20 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.7.0 — 2026-07-03 (FEAT-0067 post-mortem: migration mai deployata)
+
+- **Step 3.5 vocabulary aliases**: il Migration Gate ora riconosce, oltre a
+  `migration_plan.required` (epic), anche `db_migrations_summary` (epic) e
+  `db_migration.required: true` (per-card — convenzione overlay consumer, es. mayo).
+  Root cause FEAT-0067: il probe solo-`migration_plan` classificava la batch come
+  migration-free → gate in silent no-op, `db:push` mai emerso.
+- **Step 5.1b Migration Sync Tail (NEW)**: post-merge, il ramo B interattivo del sync
+  gate eseguito dalla SKILL (check-sync read-only → su rosso `AskUserQuestion`
+  Push now / Defer / Override; mai push in autonomo). Trigger belt-and-braces sulla
+  DICHIARAZIONE Step 3.5, non solo sul residual ledger (che il DONE-flip di FEAT-0067
+  aveva perso). Telemetria `migration_sync_tail`.
+- Step 1.5: nota di delega aggiornata (il probe di `/new -auto` copre tutti i vocabolari).
+
 ## (workflow new2.js, framework v5.4.1) — 2026-07-03
 
 - Minimal light lane mirror: single-card light adds per-card doc-reviewer to the review

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

@@ -1,7 +1,7 @@
 ---
 name: new2
 effort: high
-version: 1.6.0
+version: 1.7.0
 description: >
   Workflow-hosted batch engine for /new. Implements one or
   more backlog cards end-to-end by delegating the WHOLE batch to a background
@@ -85,8 +85,9 @@ everywhere this skill branches on it — Step 3.5 resolves deterministically (it
 AUTONOMOUS branch) and **Step 3b's escape hatch is SKIPPED** (the user asked for
 `-auto`; a post-batch question — and a possible `/new` re-invocation at full
 inline cost — would break that promise even with a TTY present). `/new` only
-delegates **migration-free** batches (it probes `migration_plan.required`
-itself), so Step 3.5's one interactive question cannot fire on a delegated run —
+delegates **migration-free** batches (it probes ALL migration vocabularies
+itself — `migration_plan.required`, epic `db_migrations_summary`, per-card
+`db_migration.required`), so Step 3.5's one interactive question cannot fire on a delegated run —
 if you nonetheless find a declared, unapplied migration in a delegated batch,
 HALT and hand back to `/new` classic (`"batch con migrazione dichiarata — riesegui
 /new <cards> -auto -inline"`) instead of asking. Everything else is identical to a
@@ -129,8 +130,16 @@ untouched), so the schema is live **before** the workflow starts. It mirrors `/n
 1. **Find the batch's epic card(s)** — distinct `group.parent` of the resolved cards (or the `-full`
    parent). Read each epic YAML in `${paths.backlog_dir}` (`<PARENT>-*-epic.yml`, or the card whose
    `id == <PARENT>` / `group.is_epic: true`).
-2. **Look for `migration_plan` with `required: true`.** None → set `migration = { status: 'none' }`
-   and go to Step 4 (identical to today — zero extra prompts; do not surface anything).
+2. **Look for a declared migration — under ANY recognized vocabulary.** Primary: epic
+   `migration_plan` with `required: true`. **Compat aliases (consumer-overlay conventions —
+   FEAT-0067 root cause: probing only `migration_plan` made this gate structurally blind to
+   `db_migration`-declaring cards)**: epic `db_migrations_summary` (non-empty), or any batch card
+   with `db_migration.required: true` (map: `artifacts` ← `db_migration.expected_file`; `summary`
+   ← the slug; modalities ← `db_migration.remote_push` + overlay). Nothing declared → set
+   `migration = { status: 'none' }` and go to Step 4 (identical to today — zero extra prompts; do
+   not surface anything). Declared via ANY vocabulary → record `migrationDeclared: true` +
+   `declaredVia` in your own working state (Step 5.1b keys off it — it must NOT depend on the
+   workflow's residual ledger surviving) and continue below.
 3. **(declared) Verify `migration_plan.artifacts` exist on disk under `$MAIN`.** Any missing → do NOT
    apply or prompt; set `migration = { status: 'degraded', reason: 'artifact missing', artifacts }`
    and go to Step 4 (the migration falls back to the current end-of-batch owner-gated deferral — no
@@ -245,6 +254,40 @@ returns when the batch is done. It returns:
    step-1b HALT fields — the `/new` pre-flight back-fill (step 1b-ii) then normalizes its
    `review_profile`/`owner_agent` on first ingestion, so even the crisis stub self-heals. This
    main-repo, **disk-verified** write is the SSOT — nothing is dropped even on a non-merged batch.
+1b. **Migration Sync Tail (post-merge "branch B" — the interactive owner-gated deploy the
+   autonomous batch could not run).** The workflow has returned and merged; you are the skill
+   main loop, in `$MAIN`, typically on `$TRUNK` — exactly the precondition of the project's
+   post-merge sync gate (e.g. the overlay's "on trunk, post-merge" branch). **Trigger — EITHER
+   condition, independently** (belt-and-braces: the FEAT-0067 failure dropped the residual
+   mid-run, so this tail keys on the Step-3.5 DECLARATION, never only on the ledger):
+   (a) `migrationDeclared` from Step 3.5 (any vocabulary) with `migration.status ≠ 'applied'`;
+   (b) any `residuals[]` entry whose kind/owner-gated action maps to `db-migration-deploy`.
+   Neither → skip silently. Steps:
+   - **Resolve the project's post-merge sync contract**, in source order: (i) the batch cards'
+     `db_migration.remote_push` / `migration_plan` (check command + push command); (ii) the
+     post-merge / trunk branch of the Migration Sync Gate section in `.baldart/overlays/new.md`;
+     (iii) `migration_plan.verify` alone (check-only). Nothing resolvable → skip the tail (the
+     step-1 follow-up card remains the ledger) and say so in the presentation.
+   - **Run the read-only sync CHECK first** (e.g. the overlay's check-sync command), from `$MAIN`
+     on `$TRUNK` (if `$MAIN` is not on `$TRUNK`, do not switch branches yourself — report and
+     leave the follow-up as ledger). **Green** → the migration is live: the `db-migration-deploy`
+     residual is SATISFIED (no follow-up needed — if step 1 already created one, delete it in the
+     same reconciliation commit and note why); record it and let step 2 DONE-flip the migration
+     card with its schema AC satisfied.
+   - **Red + INTERACTIVE** → ONE `AskUserQuestion` (post-batch skill-layer interaction, same
+     class as Step 3b — the zero-ask-during-batch invariant is untouched): *"La migration del
+     batch non risulta applicata al DB remoto (check-sync rosso). Come procedo?"* Options:
+     **[Push now]** (run the declared owner-gated push command from `$TRUNK` — honour
+     `stack.schema_deploy_from_trunk_only`; output to `/tmp/migration-push-<firstCard>.log`,
+     surface the exit code, then RE-RUN the check and require green) / **[Defer]** (keep the
+     step-1 follow-up card as the ledger; the card stays DONE-with-follow-up per its
+     `owner-gated` class) / **[Override]** (record the user's verbatim reason). Never push
+     without the user picking it.
+   - **Red + AUTONOMOUS** (env / delegated `/new -auto` origin — Step 1.5) → NEVER push
+     (outward, owner-gated). Ensure the step-1 follow-up exists, and surface the pending deploy
+     PROMINENTLY in the presentation (step 4) — a truthful "schema NOT live" line, not a footnote.
+   - Record `migration_sync_tail: { ran, trigger: 'declared'|'residual'|'both', check:
+     'green'|'red'|'unavailable', pushed: <bool>, outcome }` for telemetry (step 5).
 2. **Mark deferred cards DONE — only after their follow-up exists AND every deferral class allows
    it (F-040/H + A3).** Some committed cards were intentionally left **NON-DONE** because they carry
    an open deferred AC: they are `perCardResults[]` entries with `deferred:true` plus a
@@ -358,7 +401,8 @@ returns when the batch is done. It returns:
    (partial, output-only, excludes nested workflows). Keep `degraded`/`degradation_reasons` +
    `cards_deferred_done_pending` in the record so
    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
+   (`none`|`applied`|`skipped`|`degraded`) and `migration_sync_tail` (Step 5.1b — whether the
+   post-merge check ran, its outcome, and whether an owner-gated push was user-approved) — 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. Keep `deferral_breakdown` (per-class counts
    of WHY residuals became follow-ups instead of in-batch fixes) in the record — a class dominating

package/package.json

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