baldart 5.4.0 → 5.5.0

package/CHANGELOG.md

@@ -5,6 +5,53 @@ 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),
+coder, code review, doc review, commit, merge. Nothing else.** Completes v5.4.0 per the
+maintainer's directive ("per cose così semplici voglio due passaggi in croce"): the compact
+lane cut the CARD COUNT; this cuts the per-run AGENT COUNT. FEAT-0067-class run: ~33
+agents → ~7.
+
+- **Per-card doc review at light (single-card batch)**: the light review matrix adds the
+  scoped `doc-reviewer` per-card (review-cycle.md deferral-gate exception) because the
+  Final pass it used to defer to is now skippable.
+- **Final Review skip gate (`final-review.md` § F.0 + `new2.js` `skipFinalLight`)**: ONE
+  light card + zero actionable per-card findings (→ zero fixes applied) → skip F.2–F.5
+  entirely. Honors the v4.56.1 refutation (per-card PRE-fix + final POST-fix are
+  non-redundant) by scoping the skip to runs where there IS no post-fix state; any
+  finding, fix, second card, or degraded reviewer → Final runs as always.
+- **i18n fill spawn cut at light**: the owner briefing instructs the coder to fill every
+  target locale itself; the anti-hardcoded lint + locale-parity gates still enforce.
+- **Production-readiness spawn cut for all-light batches**: no deployable surface exists
+  by Rule C (no migrations/indexes/cron/schema) — the agent only ever reported zero items.
+- `check-new-parity.mjs` rule 18 locks the prose↔workflow lockstep for every cut.
+- Skills: `new` 2.2.0 · `new2` 1.6.0.
+
+Codex parity: portable (prose modules are the cross-tool SSOT; `new2.js` Claude-only by design).
+
 ## [5.4.0] - 2026-07-03
 
 **Elastic pipeline — `/prd`+`/new` compress to the minimum for trivial features and

package/VERSION

@@ -1 +1 @@
-5.4.0
+5.5.0

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

@@ -2,6 +2,27 @@
 
 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:
+  grounding-inline (step 2d) → owner → code review (Codex-light/code-reviewer) → scoped
+  doc-reviewer per-card (review-cycle deferral exception) → commit → merge. Cut for the
+  lane: i18n fill spawn (7c — owner fills locales inline, lint gate enforces), Final
+  Review when the per-card review is clean (final-review.md § F.0 Minimal-light skip
+  gate — POST-fix verification with zero fixes is vacuous; any finding/fix/second card →
+  Final runs), production-readiness spawn for all-light batches (no deployable surface
+  by Rule C). Guarded by check-new-parity rule 18.
+
 ## 2.1.0 — 2026-07-03 (framework v5.4.0)
 
 - **Light-lane inline grounding (implement.md step 2d).** A `review_profile: light` card

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

@@ -1,7 +1,7 @@
 ---
 name: new
 effort: medium
-version: 2.1.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/final-review.md

@@ -42,6 +42,19 @@ Once ALL cards are committed in the worktree:
 > A single card has no cross-card surface, so a finder's per-card pass and its final pass are genuinely
 > the same review.
 
+### Step F.0 — Minimal-light skip gate (v5.4.1)
+
+When the batch has exactly ONE committed card AND it is `review_profile: light` AND its
+per-card review surfaced ZERO actionable findings (no blocks, no scope-expansion → no fix
+pass was applied), **SKIP the entire Final Review** (F.2–F.5) and proceed to merge. The
+Final pass exists for POST-fix verification and cross-card surface (v4.56.1 — per-card
+PRE-fix + final POST-fix are non-redundant); with zero fixes and zero cross-card surface,
+both reasons are absent — and doc coverage already ran per-card (the single-card light
+review matrix includes the scoped doc-reviewer instead of deferring here, see
+review-cycle.md § Deferral gate). Any finding on the card, any fix applied, any second
+card, or any degraded reviewer → run the Final Review as written below. Log
+`final-review: SKIPPED (single light card, clean per-card review — nothing post-fix to verify)`.
+
 ### Step F.1 — Resolve scope
 
 (All cards are committed; the batch now enters Final Review. No visibility emission — the internal tracker is the only state surface, see SKILL.md § "State surface — the tracker only". Record the Final-Review start/finish in the tracker only.)

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

@@ -500,7 +500,7 @@
    - **Grounding (cheap `grep`, like the Phase-1 plan-auditor grounding):** every cited source symbol/class MUST appear in `mockups/_src/` (`grep -rF "<symbol>" <prd_dir>/<slug>/mockups/_src/`), and every cited registry primitive MUST exist in the registry (`grep` `${paths.design_system}/INDEX.md` / `components/`). A symbol that is not in the source, or a primitive that is not in the registry, means a fabricated declaration → reject + re-spawn (do NOT pass it to the gates). Log `design-source: grounded` or `design-source: rejected (<reason>)` in the tracker.
    - This does NOT re-verify pixels — that stays with `visual-fidelity-verifier` (Phase 2.6). It only proves the source was read and the reuse-mapping targets are real. When the card has no design source, skip this step entirely.
 
-7c. **i18n fill pass (explicit, deterministic — v5.0.0, promoted from the step-9 sub-bullet).** When `features.has_i18n: true` AND this card's diff added new source-locale keys — detect deterministically, never by intuition:
+7c. **i18n fill pass (explicit, deterministic — v5.0.0, promoted from the step-9 sub-bullet).** **Light lane (v5.4.1): SKIP this spawn** — on the light lane (step 2d) the owner briefing already instructed the coder to fill EVERY target locale itself (context-aware from the registry); the anti-hardcoded lint + locale-parity gates at step 8 enforce it. Log `i18n-fill: SKIP (light lane — owner fills inline)`. Otherwise: when `features.has_i18n: true` AND this card's diff added new source-locale keys — detect deterministically, never by intuition:
    ```bash
    cd <worktree-path>
    # $SRC_LOCALE = the source-language locale file path (from i18n config / the project's locales root)

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

@@ -6,6 +6,12 @@
 
 After Phase 6 completes (or after the final summary report if Phase 6 is deferred), present a **Production Readiness Checklist** — a clear list of all manual or infrastructure actions required to launch the implemented changes in production.
 
+> **Minimal light lane (v5.4.1): SKIP the spawn for an all-`light` batch** — a light card
+> carries no deployable surface by Rule C (no migrations, indexes, cron, schema, env); the
+> checklist agent would only report zero items. Log
+> `phase7-production: SKIPPED (all-light batch — no deployable surface)`. Any
+> `balanced`/`deep` card in the batch → run as written.
+
 ### How to detect items
 
 Scan ALL files changed across the batch (use the tracker's completed cards + `git diff` against the base branch) and check for the items below.

package/framework/.claude/skills/new/references/review-cycle.md

@@ -305,7 +305,7 @@ skill's Phase 1 falls back to deriving Gherkin scenarios from
 
 > **Note**: Code review is NOT performed in this phase — it is handled by the **mandatory unconditional `/codexreview` gate in Phase 3.7**, which runs per-card BEFORE the Phase 4 commit. The post-batch `/codexreview` in the Final review remains as a final FULL-diff sweep over the entire batch (since v3.37.0 — the guaranteed full-depth merge gate). This Phase 3 focuses exclusively on documentation sync, which must happen per-card (tied to the specific commit).
 
-> **Deferral gate (since v4.7.0 — enumerated, `review_profile`-driven)**: SKIP per-card doc-review and defer it to the **Final Review F.3 doc-reviewer** (which runs over the entire batch) when the card is **`review_profile == light` AND its committed diff touches NO documentation file** (no `.md`, no path under `${paths.references_dir}`, no data-model/ssot/api doc). These are small code changes with no doc surface of their own; their only doc concern is drift, which the batch-wide Final doc-reviewer catches. Log `doc-review: DEFERRED to Final FULL gate (light, no doc files in diff)` and proceed to Phase 3.5. **KEEP per-card doc-review** for: `deep` cards, `balanced` cards (they may still PASS-fast via the deterministic gate below — that gate, not this deferral, is their only skip lane), ANY card whose diff touches a doc file (the change IS doc-relevant), and trivial cards (doc-review is their primary gate — § "Trivial-card fast-lane", unchanged). Never defer "for time" — the only enumerated reasons are `light + non-doc diff` and the deterministic PASS-fast below.
+> **Deferral gate (since v4.7.0 — enumerated, `review_profile`-driven)**: SKIP per-card doc-review and defer it to the **Final Review F.3 doc-reviewer** (which runs over the entire batch) when the card is **`review_profile == light` AND its committed diff touches NO documentation file** (no `.md`, no path under `${paths.references_dir}`, no data-model/ssot/api doc). These are small code changes with no doc surface of their own; their only doc concern is drift, which the batch-wide Final doc-reviewer catches. Log `doc-review: DEFERRED to Final FULL gate (light, no doc files in diff)` and proceed to Phase 3.5. **KEEP per-card doc-review** for: `deep` cards, `balanced` cards (they may still PASS-fast via the deterministic gate below — that gate, not this deferral, is their only skip lane), ANY card whose diff touches a doc file (the change IS doc-relevant), and trivial cards (doc-review is their primary gate — § "Trivial-card fast-lane", unchanged). Never defer "for time" — the only enumerated reasons are `light + non-doc diff` and the deterministic PASS-fast below. **Single-card light batch exception (v5.4.1 minimal light lane): do NOT defer** — when the batch has exactly ONE card and it is `light`, the Final Review is itself SKIPPED if the per-card review is clean (see final-review.md § Minimal-light skip gate), so the deferral target would never run: run the scoped per-card doc-reviewer here instead.
 >
 > **Deterministic PASS-fast (v5.0.0 — measured: 84/127 per-card doc reviews returned PASS)**: when implement.md step 11c produced `/tmp/docinv-<CARD-ID>.json` AND it says `pass_fast_eligible: true` (zero non-advisory invariant rows triggered + no doc file in the diff + the card declares no `documentation_impact`/`canonical_docs`) AND the card is NOT `deep` → log `doc-review: PASS-fast (doc-invariants: 0 blocking rows) — Final doc-reviewer backstop stands` and **skip the per-card spawn** (proceed to Phase 3.5). No gate is removed: the batch-Final F.3 doc-reviewer still sees this card's diff. Own-Doc Closure: NEW-file obligations are definitionally empty (no invariant row fired, no docs declared); obligations on MODIFIED primitives/routes are covered by the automatic spec resync (`DS_COMPONENT_STALE` serializer gate, v4.70.0) plus the Final F.3 backstop — the invariant table's R1/R3 fire on new files only, by design. `deep` cards always spawn. Missing docinv JSON → no PASS-fast (fall through to the normal path).
 

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,28 @@
 
 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
+  matrix, skips the i18n fill spawn (owner briefing carries the fill instruction),
+  skips new-final-review when `lightLane && cleanReview` (zero actionable findings),
+  skips production-readiness for all-light batches. Result objects carry
+  `lightLane`/`cleanReview` for the Final gate.
+
 ## (workflow new2.js, framework v5.4.0) — 2026-07-03
 
 - Light lane: `review_profile: light|skip` cards no longer spawn the Phase-1 retriever —

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

@@ -1,7 +1,7 @@
 ---
 name: new2
 effort: high
-version: 1.5.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/framework/.claude/workflows/new2.js

@@ -617,7 +617,7 @@ async function runCard(cardId, cardPath) {
   const phase1Brief = architectOk
     ? `Phase 1 already ran as specialist agents. READ the architecture baseline at ${baselinePath} BEFORE writing any code — it is your codebase context; do NOT redo the exploration.${auditCorrections.length ? `\nPlan-audit corrections (apply them as amendments to this briefing — do NOT modify the backlog YAML):\n${auditCorrections.map((c, i) => `  ${i + 1}. ${c}`).join('\n')}` : ''}`
     : phase1.architect === 'inline-light'
-      ? `Phase 1 light lane (v5.4.0): this card is review_profile '${reviewProfile}' (≤3-file scale) — no dedicated retriever ran. Ground INLINE per AGENTS.md § Change Tiers (orchestrated-pipeline exception): BEFORE writing code, read the files in scope + their immediate integration points (imports/consumers). Scoped exploration of the touched area only — not a repo sweep; the understanding obligation is unchanged, only the delegation was waived.`
+      ? `Phase 1 light lane (v5.4.0): this card is review_profile '${reviewProfile}' (≤3-file scale) — no dedicated retriever ran. Ground INLINE per AGENTS.md § Change Tiers (orchestrated-pipeline exception): BEFORE writing code, read the files in scope + their immediate integration points (imports/consumers). Scoped exploration of the touched area only — not a repo sweep; the understanding obligation is unchanged, only the delegation was waived.${features.has_i18n ? ' I18N (light lane): NO separate fill pass runs for this card — fill EVERY target locale yourself for any new key (context-aware from the registry); the anti-hardcoded lint gate must pass.' : ''}`
       : `Phase 1 fallback: the architect specialist was unavailable — do the Phase 1 claim+architect exploration yourself per ${REF}/implement.md and persist the baseline to ${baselinePath} before coding.`
   // T1.A (v4.90.0) — mockup cards: binding-compliance is verified deterministically by the
   // check-bindings.mjs script (ui-implement Step 5b is the SSOT; this is the new2 parallel).
@@ -670,7 +670,10 @@ async function runCard(cardId, cardPath) {
   // v5.0.0 — explicit i18n fill pass (implement.md step 7c mirror; closes the measured leakage
   // where locale fills were spawned as general-purpose). The translator is named BY TYPE; it
   // self-detects new source-locale keys from the diff and no-ops cheaply when there are none.
-  if (features.has_i18n) {
+  // v5.4.1 minimal light lane — no separate fill pass: the owner filled every locale itself
+  // (its briefing carries the instruction) and the Phase-2 anti-hardcoded lint gate enforces it.
+  if (features.has_i18n && lightLane) g('i18n-fill', 'SKIP', 'light lane — owner fills locales inline; lint gate enforces')
+  else if (features.has_i18n) {
     try {
       const fill = await agentSafe(
         `You are i18n-translator (fill pass for card ${cardId} — agents/i18n-protocol.md per-card cascade). cd into the card worktree. FIRST detect deterministically whether this card's diff (/tmp/diff-${cardId}.txt) added NEW source-locale keys; if none → return { ran:false, keys:0 } immediately (no-op). If keys exist: fill the missing TARGET locales for exactly those keys, context-aware from the registry at ${paths.i18n_registry || 'the i18n registry'} — the source locale stays untouched (the coder is source-only by design). Then re-run the project's locale-parity check if one exists. Return: { ran, keys, note }`,
@@ -834,7 +837,14 @@ async function runCard(cardId, cardPath) {
   }
   let reviewers
   if (reviewProfile === 'skip') reviewers = []
-  else if (reviewProfile === 'light') reviewers = codexAvail ? ['codex'] : ['code-reviewer']
+  else if (reviewProfile === 'light') {
+    reviewers = codexAvail ? ['codex'] : ['code-reviewer']
+    // v5.4.1 minimal light lane — a single-card light batch skips the Final workflow when its
+    // per-card review is clean (nothing post-fix to verify), so doc coverage cannot defer
+    // there: run the scoped doc-reviewer per-card instead. Multi-card light keeps the
+    // deferral (the Final batch pass still runs and covers it).
+    if (cardIds.length === 1) reviewers.push('doc-reviewer')
+  }
   else if (noEvidence) reviewers = FULL_FANOUT // balanced/deep, no surface evidence → conservative full
   else reviewers = relevanceGated() // balanced AND deep — surface-gated breadth
   if (reviewProfile !== 'skip') g('review-matrix', 'PLANNED', `[${reviewProfile}${noEvidence ? '→conservative-full (no surface evidence)' : ''}] ${reviewers.join('+') || '(none)'} · docs:${touchesDocs} code:${touchesCode} api/data:${touchesApiData} sec:${securityRelevant}`)
@@ -974,8 +984,13 @@ async function runCard(cardId, cardPath) {
     // B6 — which reviewers ACTUALLY ran (the gated matrix); Phase Final keys its slim/skip
     // decision on this, and per_card telemetry records it for the A/B spawn accounting.
     reviewersRun: reviewers,
-    // B7 — Phase-1 specialist record (architect: done|inline-fallback; audit: pass|fixes|skipped-*).
+    // B7 — Phase-1 specialist record (architect: done|inline-fallback|inline-light; audit: pass|fixes|skipped-*).
     phase1,
+    // v5.4.1 minimal light lane — Phase Final keys its skip on these: a single light card whose
+    // per-card review surfaced NOTHING actionable has no post-fix state for the Final pass to
+    // verify (the Final review's purpose — v4.56.1 — is POST-fix verification, not re-review).
+    lightLane,
+    cleanReview: blocks.length === 0 && scopeExp.length === 0,
     scopeFiles, archBaselinePath: `/tmp/arch-baseline-${cardId}.md`, gates,
   }
 }
@@ -1151,7 +1166,13 @@ const committed = perCardResults.filter((r) => r.status === 'committed')
 phase('Final')
 let finalSummary = null
 let mergeBlocked = degraded
-if (committed.length && !degraded) {
+// v5.4.1 minimal light lane — ONE light card, clean per-card review (zero actionable
+// findings → zero fixes applied): the Final pass has nothing post-fix to verify and its
+// doc coverage already ran per-card (the light single-card matrix includes doc-reviewer).
+// Any finding/fix on the card, any second card, or any degradation → Final runs as always.
+const skipFinalLight = committed.length === 1 && committed[0].lightLane && committed[0].cleanReview && !degraded
+if (skipFinalLight) ledger(firstCard, 'final-review', 'SKIPPED', 'single light card, clean per-card review — nothing post-fix to verify (doc ran per-card)')
+if (committed.length && !degraded && !skipFinalLight) {
   const reviewScopeFiles = dedupe(committed.flatMap((r) => r.scopeFiles || []))
   const archPaths = committed.map((r) => r.archBaselinePath).filter(Boolean)
   const allArch = archPaths.length === committed.length ? archPaths : null
@@ -1295,7 +1316,11 @@ if (!committed.length) {
 // Phase Production (Phase 7) — non-blocking; report-not-execute (F-011 infra-deferred).
 // ───────────────────────────────────────────────────────────────────────────
 phase('Production')
-if (mergeResult && mergeResult.merged) {
+if (mergeResult && mergeResult.merged && committed.length && committed.every((r) => r.lightLane)) {
+  // v5.4.1 minimal light lane — light cards carry no deployable surface by Rule C (no
+  // migrations/indexes/cron/schema); the checklist would only burn a spawn to report zero items.
+  ledger(firstCard, 'phase7-production', 'SKIPPED', 'all-light batch — no deployable surface (Rule C)')
+} else 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

package/package.json

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