baldart 5.7.0 → 5.8.0

package/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.8.0] - 2026-07-06
+
+**Suggested launch plan at the end of `/prd` — waves with a NAME, persisted on the epic card.**
+`/prd` used to close with a progress bar and a bare summary (PRD path, card IDs, branch, PR/SHA)
+but never told you **how to launch `/new`** — one run or several waves, where the boundaries are,
+which engine. You had to reason it out by hand. Now every `/prd` run ends with a mandatory
+**"🚀 Piano di implementazione suggerito"** section, and the plan is **persisted on the epic
+card** so `/new`/`/new2` can, at the end of a subset run, remind you which waves remain to close
+the epic — each wave carries a short, memorable **name** ("Wave 1 · Fondamenta server").
+
+The design was hardened by a two-reviewer adversarial pass that refuted the obvious v1
+(a separate `implementation_plan` block, an `engine` field on the card, a new reference module,
+the mechanical card-writer computing the heuristic). The shipped shape:
+
+- **Drift-free persistence — no new block, no new module.** The wave partition is three OPTIONAL
+  sub-keys (`wave` / `wave_name` / `wave_rationale`) on the EXISTING `execution_strategy.groups[]`
+  entries — the single card-ID partition already consumed by `/new` for parallelism. No parallel
+  `waves[]` array re-listing card IDs (that would drift). Because they are sub-keys of an
+  already-`R` field, the baseline validator never sees them: **no new field-state-matrix row, no
+  migration of legacy epics**. Schema SSOT: `framework/agents/card-schema.md`.
+- **Compute-by-orchestrator / persist-by-writer** (the `provenance.planning_session` split):
+  the `/prd` orchestrator (opus/high) computes the single-run-vs-waves judgment + names + rationale
+  — it needs the discovery context (migration-early, `review_profile: deep` pressure, server↔UI
+  cut) the mechanical `prd-card-writer` never holds — and persists it with a targeted Edit on the
+  epic card. The card-writer emits the keys ONLY when handed them; else it omits them (explicit
+  else branch → no fabrication). Single-run is the default (no wave tags).
+- **Engine + hard rules are render-time, never persisted.** The `/new` vs `/new2` recommendation
+  is computed at render and is **runtime-aware** — `/new2` needs the Workflow tool and is
+  Claude-only, so on Codex the plan recommends `/new` only. A durable, cross-tool artifact must
+  not carry a runtime-capability recommendation a Codex consumer cannot execute.
+- **`/new` + `/new2` remaining-waves.** `/new`'s Step F.6 "Prossimi Passi" and `/new2`'s
+  `buildReport()` "Epic goal" render the remaining waves BY NAME (fallback to the flat card list
+  when the epic has no wave tags — no regression). `/new2` runs fs-less, so the `wave_name` is
+  threaded through `cardGraph` (new `waveName` node field derived by the preflight agent).
+- Project-specific between-wave cautions (migration/deploy gate, compile check, stash) stay in
+  `.baldart/overlays/prd.md` and are surfaced at render-time — no stack names in the base.
+
+No new `baldart.config.yml` key (rides on the existing `execution_strategy` + `features.*`) → the
+schema-change propagation rule does NOT apply. **Codex parity: portable** (runtime-neutral field;
+engine computed at render-time; `/new2` remaining-waves via `cardGraph`).
+
+Skills bumped: `prd` 1.6.1→1.7.0, `new` 2.3.1→2.4.0, `new2` 1.8.1→1.9.0.
+
 ## [5.7.0] - 2026-07-06
 
 **Feature-gated skill linking — stop wasting Codex's 2% skill-description budget.** Codex

package/VERSION

@@ -1 +1 @@
-5.7.0
+5.8.0

package/framework/.claude/agents/prd-card-writer.md

@@ -754,6 +754,29 @@ The consumer (`new/SKILL.md`) reads `execution_strategy.groups[].level` and
 `.cards`. Use these exact keys — `groups`/`level`, not the legacy
 `parallel_groups`/`group`.
 
+**Launch-wave sub-fields (`wave` / `wave_name` / `wave_rationale`) — write ONLY if handed to you.**
+The `/prd` orchestrator may pass a launch-wave partition (a run-sequencing judgment it computes
+AFTER you return the Parallel Execution Map — it needs discovery context you do not hold). When
+and only when the orchestrator hands you these values, add them as optional sub-keys on the
+matching `groups[]` entries:
+
+```yaml
+  groups:
+    - level: 0
+      cards: [FEAT-XXXX-01]
+      description: "Foundation/scaffold"
+      wave: 1                          # only if passed
+      wave_name: "Fondamenta server"   # only if passed
+      wave_rationale: "…"              # only if passed
+```
+
+If the orchestrator does NOT hand you a wave partition, **OMIT all three keys** — do NOT invent a
+wave grouping, a name, or a rationale (a launch judgment fabricated from the card graph alone is
+worse than absent; single-run epics legitimately carry no wave tags). This is the same
+compute-by-orchestrator / persist-by-writer split as `provenance.planning_session`. Schema + the
+render-time derivation live in [`framework/agents/card-schema.md`](../../agents/card-schema.md)
+§ "`execution_strategy.groups[].wave*`".
+
 ## Output Format
 
 **Self-validation BEFORE returning (v5.6.0 — you own your domain's deterministic hygiene).**

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

@@ -2,6 +2,21 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 2.4.0 — 2026-07-06
+
+- **Prossime wave per NOME nel messaggio finale.** Il Step F.6 "Prossimi Passi"
+  (`references/final-review.md`) ora è **wave-aware**: legge la partizione di lancio persistita
+  da `/prd` sull'epic card (sotto-campi opzionali `wave` / `wave_name` su
+  `execution_strategy.groups[]`) e, quando presente, mostra le **wave rimanenti per nome**
+  ("Prossime wave: **Wave 2 · Superfici UI**") invece della sola lista card piatta — così, dopo
+  aver implementato un subset (es. `/new FEAT-0069-01..06`), il riepilogo dice cosa resta per
+  chiudere l'epic senza doverlo ricordare. Engine della prossima wave suggerito runtime-aware
+  (Codex → solo `/new`). Richiede un Read esplicito dell'epic card a F.6 (non è in contesto:
+  letto solo transitoriamente in Phase 0). **Fallback grazioso** alla lista card piatta quando
+  l'epic non ha tag wave (single-run / legacy) → nessuna regressione. Schema SSOT:
+  `framework/agents/card-schema.md` § `execution_strategy.groups[].wave*`.
+  - Codex parity: portable (il campo è runtime-neutral; l'engine è calcolato a render-time).
+
 ## 2.3.1 — 2026-07-06
 
 - **Feature-gate**: added `requires_feature: has_backlog` frontmatter — this skill is now linked into a consumer only when `features.has_backlog` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.

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

@@ -1,7 +1,7 @@
 ---
 name: new
 effort: medium
-version: 2.3.1
+version: 2.4.0
 requires_feature: has_backlog
 description: >
   Orchestrate a team of specialized agents to implement one or more backlog cards

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

@@ -439,7 +439,42 @@ that is a **gate violation**: log it as
      | xargs grep -L "status: DONE"
    ```
 
-   Present the section:
+   **Wave-aware next steps (v5.8.0).** `/prd` may have persisted a **launch-wave partition** on the
+   epic card — optional `wave` / `wave_name` sub-keys on `execution_strategy.groups[]` (schema:
+   `framework/agents/card-schema.md` § "`execution_strategy.groups[].wave*`"). The epic card is NOT
+   in context here (it was read only transiently in Phase 0) — so **Read the epic card now**
+   (`${paths.backlog_dir}/<EPIC-ID>.yml`) to fetch the wave tags. Then:
+   - **If wave tags exist:** map each remaining not-DONE card to its `wave_name` (via the group whose
+     `.cards` contains it), and render the **remaining WAVES by name** instead of a flat card list — a
+     wave is "rimanente" when ≥1 of its cards is not-DONE. This keeps the thread across runs: the user
+     recognises "Wave 2 · Superfici UI" from the `/prd` plan. Suggest the engine for the NEXT wave
+     runtime-aware (Claude → `/new2` for a high-volume wave, else `/new`; Codex → `/new` only —
+     `/new2` is Claude-only).
+   - **If NO wave tags** (legacy epic / single-run): render the flat "Card rimanenti nell'epic" table
+     exactly as before (backwards-compat, no regression).
+
+   Present the section — WAVE-AWARE form (when wave tags exist):
+
+   ```
+   ## Prossimi Passi
+
+   ### Prossime wave da sviluppare
+   | Wave | Nome | Card rimanenti | Engine suggerito |
+   |------|------|----------------|------------------|
+   | 2 | Superfici UI & closer | FEAT-XXXX-07…13 | /new2 |
+
+   ### Lancio prossima wave (copia e incolla)
+   ```
+   /new2 FEAT-XXXX-07-FEAT-XXXX-13
+   ```
+
+   ### Card completate in questa sessione
+   | Card | Titolo | Commit |
+   |------|--------|--------|
+   | FEAT-XXXX-01 | [title] | abc1234 |
+   ```
+
+   FLAT form (no wave tags — unchanged):
 
    ```
    ## Prossimi Passi

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

@@ -2,6 +2,17 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.9.0 — 2026-07-06
+
+- **Prossime wave per NOME nel report finale (parità con `/new`).** `buildReport()` (`new2.js`)
+  ora, per ogni epic APERTA nella sezione "Epic goal", elenca le **wave rimanenti per nome**
+  dalla partizione di lancio persistita da `/prd` sull'epic. Poiché il workflow gira senza
+  accesso al filesystem, il `wave_name` è **portato via `cardGraph`** (nuovo campo `waveName`
+  sul nodo — l'agente preflight lo deriva dai `execution_strategy.groups[]` dell'epic). Scope
+  onesto: visibili solo le wave le cui card sono NEL BATCH (le wave interamente fuori dal batch
+  non sono caricate). `''` quando l'epic non ha tag wave (single-run / legacy) → nessuna riga.
+  - Codex parity: portable (il campo è runtime-neutral).
+
 ## 1.8.1 — 2026-07-06
 
 - **Feature-gate**: added `requires_feature: has_backlog` frontmatter — this skill is now linked into a consumer only when `features.has_backlog` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.

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

@@ -1,7 +1,7 @@
 ---
 name: new2
 effort: high
-version: 1.8.1
+version: 1.9.0
 requires_feature: has_backlog
 description: >
   Workflow-hosted batch engine for /new. Implements one or

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

@@ -2,6 +2,34 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.7.0 — 2026-07-06
+
+- **Piano di implementazione suggerito nel messaggio finale (sempre).** Il run di `/prd` ora
+  chiude con una sezione **"🚀 Piano di implementazione suggerito"** che dice come lanciare
+  `/new` — unica run vs **wave con NOME**, confini, engine (`/new` vs `/new2`) — invece di
+  lasciare all'utente il compito di ricavarla a mano. La logica del piano è **persistita
+  sull'epic card** così `/new`/`/new2` a fine run possono ricordare quali wave restano.
+  - **Persistenza drift-free:** nessun blocco nuovo — sotto-campi OPZIONALI `wave` / `wave_name`
+    / `wave_rationale` sui `groups[]` esistenti di `execution_strategy` (unica partizione di
+    card-ID; niente `waves[]` parallelo che drifta). Sono sotto-chiavi di un campo già `R` →
+    il baseline validator non le vede, **nessuna riga nuova nella field-state matrix**, epic
+    legacy invariate. Schema SSOT: `framework/agents/card-schema.md`.
+  - **Compute-by-orchestrator / persist-by-writer** (stesso split di `provenance.planning_session`):
+    l'**orchestratore `/prd`** calcola la partizione wave + nomi + rationale (giudizio di lancio
+    che serve il contesto di discovery — migration-early, pressione review `deep`, taglio
+    server/UI) e la persiste con un Edit mirato sull'epic card; il `prd-card-writer` scrive i
+    sotto-campi **solo se gli vengono passati**, altrimenti li omette (ramo else esplicito →
+    niente fabbricazione). Single-run resta il default: nessun tag wave.
+  - **Engine + hard-rule = render-time, non persistiti.** La scelta `/new` vs `/new2` è calcolata
+    a render ed è runtime-aware (Codex → solo `/new`, `/new2` è Claude-only) — un artefatto
+    cross-tool durabile non porta una raccomandazione che un consumer Codex non può eseguire.
+  - **Base generico + overlay:** cautele project-specific tra-wave (migration/deploy gate, compile
+    check, stash) restano in `.baldart/overlays/prd.md`, innestate a render-time.
+  - File: `references/backlog-phase.md` (compute+persist), `references/validation-phase.md`
+    (render), `assets/epic-template.yml` (chiavi commentate), `framework/agents/card-schema.md`
+    (schema), `framework/.claude/agents/prd-card-writer.md` (omit-if-not-passed).
+  - Codex parity: portable (campo runtime-neutral; engine calcolato a render-time).
+
 ## 1.6.1 — 2026-07-06
 
 - **Feature-gate**: added `requires_feature: has_prd_workflow` frontmatter — this skill is now linked into a consumer only when `features.has_prd_workflow` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.

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

@@ -1,7 +1,7 @@
 ---
 name: prd
 effort: high
-version: 1.6.1
+version: 1.7.0
 requires_feature: has_prd_workflow
 description: "Structured PRD creation skill. Use when the user says /prd, 'crea un prd', 'nuova funzionalita', 'pianifica feature', or wants to plan a new feature end-to-end. Also handles /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint' for change requests on active PRD sessions — runs ICIAS impact analysis to determine which phases need SKIP/PATCH/REDO. Produces PRD + UI design + backlog cards, all validated and committed. Multi-turn conversation: asks questions, waits for answers, iterates through discovery, design, spec writing, card creation, and validation phases."
 ---

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

@@ -135,6 +135,12 @@ execution_strategy:
     - level: 0
       cards: [{{FEAT-XXXX-01}}]
       rationale: "{{foundation / first dependency layer}}"
+      # Optional launch-wave tags — written by the /prd ORCHESTRATOR only (not the card-writer),
+      # and only when the epic is launched across multiple /new runs. Omit entirely for
+      # single-run epics. Schema: agents/card-schema.md § execution_strategy.groups[].wave*
+      # wave: 1
+      # wave_name: "{{Fondamenta server}}"
+      # wave_rationale: "{{migration + config + resolver + enforcement server}}"
     - level: 1
       cards: [{{FEAT-XXXX-02}}, {{FEAT-XXXX-03}}]
       rationale: "{{parallel after L0}}"

package/framework/.claude/skills/prd/references/backlog-phase.md

@@ -290,6 +290,42 @@ The `prd-card-writer` agent owns the entire card writing pipeline:
 - Presenting results to the user (the agent returns summary, main context displays it)
 - Proceeding to Step 6 (validation phase)
 
+## Launch-wave partition (orchestrator judgment — YOU compute it, not the card-writer)
+
+After the card-writer returns the Parallel Execution Map, **you** (the `/prd` orchestrator)
+decide how the epic should be **launched** across `/new` runs — a judgment the mechanical
+card-writer cannot make because it needs the discovery context you hold (Tier, review-profile
+mix, migration, UI/server split). This is the durable half of the "Piano di implementazione
+suggerito" the final message renders (validation-phase.md § Final output).
+
+**Decide single-run vs waves (scoped — default single-run).** Keep the epic as ONE run unless
+at least one split trigger fires; if none fires, do NOT tag any wave (single-run is the explicit
+else branch — never fabricate a wave grouping just to have one):
+- **Large batch** — many children over several dependency levels (a long single run drifts the
+  trunk mid-batch → merge conflicts instead of fast-forward; keep this rationale generic, do not
+  name a stack).
+- **Migration / schema card present** — land it in an EARLY wave so its migration/deploy gate runs
+  once and later waves build on the real schema.
+- **Review pressure** — many `review_profile: deep` children; splitting keeps the orchestrator
+  context lucid on exactly the cards that need lucid review.
+- **Clear server↔UI cut** — server/data foundation vs UI surfaces is a natural wave boundary
+  (UI/E2E cards exercise the server, so they belong in the later wave).
+- **Cross-domain file conflicts** — `execution_strategy.file_conflicts` that straddle a domain
+  boundary force sequencing.
+
+**Assign waves over the EXISTING groups (one partition, no re-listing of card IDs).** Waves are a
+contiguous grouping of `execution_strategy.groups[]` in `level` order. For each group in a wave,
+set `wave` (1-based, ascending), `wave_name` (a short, unique, human-memorable name derived from
+the wave's dominant domain/role — e.g. "Fondamenta server", "Superfici UI & closer"), and
+`wave_rationale` (one line). Persist them by **editing the epic card** (`backlog/<slug>-00.yml`)
+in the worktree — a targeted Edit adding the three sub-keys to the matching `groups[]` entries.
+Do NOT re-spawn the card-writer; do NOT create a parallel `waves[]` block. Schema:
+`framework/agents/card-schema.md` § "`execution_strategy.groups[].wave*`".
+
+**Do NOT persist the engine (`/new` vs `/new2`) or the hard rules** — those are render-time,
+runtime-aware (validation-phase.md § Final output). On a single-run epic, skip this step entirely
+(no wave keys written).
+
 ## Present and Proceed
 
 Present the plan to the user (traceability matrix + parallel execution map) for

package/framework/.claude/skills/prd/references/validation-phase.md

@@ -410,4 +410,34 @@ A run that prints "local `git.trunk_branch` did not fast-forward, handle the fil
 yourself and then pull" has FAILED Step 7.5 — go back and resolve it before
 printing the summary.
 
+Then, ALWAYS, append the launch plan:
+
+### 🚀 Piano di implementazione suggerito (MANDATORY — always render)
+
+Derive it from the epic card's `execution_strategy` (the wave partition you persisted in
+backlog-phase.md § "Launch-wave partition"); nothing here is recomputed from scratch. Rules +
+schema: `framework/agents/card-schema.md` § "`execution_strategy.groups[].wave*`" (Launch waves).
+
+- **Single-run** (≤1 distinct `wave_name`, e.g. a light-lane 1-child epic): render ONE line —
+  `**Lancia in un'unica run:** \`/new <all card IDs>\`` — no table. Stop here.
+- **Waves** (≥2 distinct `wave_name`): render a table, one row per wave in `wave` order:
+
+  | Wave | Nome | Card | Contenuto |
+  |------|------|------|-----------|
+  | 1 | Fondamenta server | FEAT-XXXX-01…06 | <wave_rationale> |
+  | 2 | Superfici UI & closer | FEAT-XXXX-07…13 | <wave_rationale> |
+
+  Then, below the table:
+  - **Engine (runtime-aware — computed here, never read from the card).** On **Claude** (the
+    `Workflow` tool is available) recommend `/new2` for a high-volume wave (off-context batch, no
+    interactive gates) and `/new` (classic) for a wave that wants human gates (migration / risky
+    review) — a hybrid (`/new` on the risky early wave, `/new2` on the rest) is a valid call. On
+    **Codex** recommend `/new` only — `/new2` needs the `Workflow` tool and does not exist there
+    (`framework/agents/runtime-portability-protocol.md` § "Workflow acceleration"). Give the exact
+    command per wave, e.g. `/new2 FEAT-XXXX-01-FEAT-XXXX-06`.
+  - **Hard rule:** niente altro lavoro in parallelo sugli stessi file tra una wave e l'altra.
+  - **Post-wave gates:** if `.baldart/overlays/prd.md` declares project-specific between-wave
+    cautions (e.g. a migration/deploy gate, a compile check, a stash check), surface them after the
+    relevant wave. Omit this line when the overlay declares none — never invent stack-specific steps.
+
 Display completed Progress Bar.

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

@@ -219,6 +219,11 @@ const PREFLIGHT_SCHEMA = {
           // Drives the epic-closure blocklist (an epic with open scope residuals/follow-ups must
           // not close) and the Epic goal section of the final report.
           parentEpic: { type: 'string', description: "parent epic id from group.parent or parent: ('' when none)" },
+          // v5.8.0 — the launch-wave this card belongs to, IFF /prd persisted a wave partition on
+          // the epic card (optional wave_name on execution_strategy.groups[] whose .cards includes
+          // this id — schema: agents/card-schema.md § execution_strategy.groups[].wave*). '' when the
+          // epic has no wave tags (single-run / legacy). Drives the "Prossime wave" report line.
+          waveName: { type: 'string', description: "launch wave_name from the epic's execution_strategy.groups[] ('' when none)" },
         },
       },
     },
@@ -305,7 +310,7 @@ try {
       g3Bullet +
       `• G4 card-field validation (setup.md 1b/1c, card-schema.md consumer contract): card missing acceptance_criteria/files_likely_touched/scope → EXCLUDE (excluded[] + reason). \`requirements\` is CONDITIONAL, not an auto-exclude: if it is missing BUT acceptance_criteria + scope are both present and non-empty, FAITHFULLY DERIVE it (a concrete restatement/decomposition of the existing AC + scope — faithful, never inventing new scope) and WRITE it back to the card YAML on disk in ${MAIN}/${paths.backlog_dir || 'backlog'} (F-040: main repo, not the worktree copy; the card artifact is NOT a source/doc file, so this is allowed despite the role boundary), logging \`[BACKFILL] <id>: requirements=<N items, AC+scope-derived>\`. Only EXCLUDE for missing requirements when acceptance_criteria OR scope is ALSO empty (a genuinely thin card). Never HALT for one bad card.\n` +
       `• G5 depends-on: a card whose depends_on names a non-DONE card NOT in this batch → EXCLUDE it AND every in-batch card that transitively depends on it.\n` +
-      `• cardGraph (REQUIRED, F-021): for every runnable card return { id, dependsOn:[IN-BATCH deps only], ownerAgent (the card's owner_agent; G25 unknown→'coder'), hasMockup (BOOLEAN — true IFF the card BUILDS the mocked UI: links.design_src non-empty, OR links.design non-empty AND (component_bindings non-empty OR files_likely_touched intersects component/style/UI source paths). A bare links.design on a docs/test/meta-only card is a POINTER to the epic's explainer, not a build target — v5.6.0, FEAT-0068: the bare test clamped a docs+ADR card to ui-expert; drives the mockup-first build override — implement.md §6a), parentEpic (the card's parent epic id from group.parent or a top-level parent: field; '' when none — drives the epic-closure blocklist + the Epic goal report section), designSrcDir (ABS path of links.design_src / the PRD mockups/_src dir; '' when absent), designHtml (ABS path when links.design is an .html file; '' otherwise), hasBindings (BOOLEAN — non-empty component_bindings), 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` +
+      `• cardGraph (REQUIRED, F-021): for every runnable card return { id, dependsOn:[IN-BATCH deps only], ownerAgent (the card's owner_agent; G25 unknown→'coder'), hasMockup (BOOLEAN — true IFF the card BUILDS the mocked UI: links.design_src non-empty, OR links.design non-empty AND (component_bindings non-empty OR files_likely_touched intersects component/style/UI source paths). A bare links.design on a docs/test/meta-only card is a POINTER to the epic's explainer, not a build target — v5.6.0, FEAT-0068: the bare test clamped a docs+ADR card to ui-expert; drives the mockup-first build override — implement.md §6a), parentEpic (the card's parent epic id from group.parent or a top-level parent: field; '' when none — drives the epic-closure blocklist + the Epic goal report section), waveName (v5.8.0 — when the parent epic card carries a launch-wave partition, the wave_name of the execution_strategy.groups[] entry whose .cards includes this id; '' when the epic has no wave tags — single-run/legacy; drives the "Prossime wave" report line), designSrcDir (ABS path of links.design_src / the PRD mockups/_src dir; '' when absent), designHtml (ABS path when links.design is an .html file; '' otherwise), hasBindings (BOOLEAN — non-empty component_bindings), 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
@@ -1687,7 +1692,19 @@ function buildReport(o) {
       const epicHigh = residuals.filter((r) => ((graphById[r.card] && graphById[r.card].parentEpic) === e || r.card === e) && (sevRank[residualSeverity(r)] || 0) >= 2)
       if (closedEpics.includes(e) && !closureBlockedEpics.has(e)) L.push(`- **${e}: CHIUSA** (children DONE + AC epic verificati dal merge agent)`)
       else if (closedEpics.includes(e)) L.push(`- **${e}: ⚠️ CHIUSA CONTRO BLOCKLIST (false DONE)** — riaprire: ${epicHigh.length} residuo/i HIGH aperti`)
-      else L.push(`- **${e}: APERTA** — ${reason || (closureBlockedEpics.has(e) ? 'blocklist: residui/follow-up aperti' : 'merge non eseguito o children aperti')}${epicHigh.length ? ` · ${epicHigh.length} residuo/i HIGH` : ''}`)
+      else {
+        L.push(`- **${e}: APERTA** — ${reason || (closureBlockedEpics.has(e) ? 'blocklist: residui/follow-up aperti' : 'merge non eseguito o children aperti')}${epicHigh.length ? ` · ${epicHigh.length} residuo/i HIGH` : ''}`)
+        // v5.8.0 — remaining launch waves by NAME (parity with /new final-review F.6). Uses the
+        // waveName threaded through cardGraph (buildReport has no fs access to re-read the epic).
+        // Honest scope: only waves whose cards are IN THIS BATCH are visible — waves entirely
+        // outside the batch aren't loaded, so this reflects the batch, not the whole epic.
+        const openWaves = dedupe(
+          cardGraph
+            .filter((n) => (n.parentEpic || '') === e && n.waveName && (perCardResults.find((r) => r.card === n.id) || {}).status !== 'DONE')
+            .map((n) => n.waveName)
+        )
+        if (openWaves.length) L.push(`  - Prossime wave (batch): ${openWaves.map((w) => `**${w}**`).join(' · ')}`)
+      }
     }
   }
   if (finalSummary) {

package/framework/agents/card-schema.md

@@ -230,6 +230,56 @@ Rules:
 - Omit any sub-field whose session id is unavailable (env var unset) rather than writing a
   placeholder.
 
+### `execution_strategy.groups[].wave*` — launch-wave annotation (epic-only, optional, orchestrator-written)
+
+The epic's `execution_strategy.groups[]` is the **single card-ID partition** consumed by `/new`
+for parallelism (`groups[].level` + `.cards` — the machine schedule). A **launch wave** is a
+coarser, human-facing partition layered ON TOP of those same groups so the user can sequence the
+epic across multiple `/new` runs and refer to each run by a stable NAME. It is expressed as three
+**optional sub-fields on the existing `groups[]` entries** — never a parallel block that re-lists
+card IDs (that would be a second SSOT that drifts from `groups[].cards`):
+
+```yaml
+execution_strategy:
+  recommended_mode: team | sequential      # existing — scheduling shape, runtime-neutral
+  groups:
+    - level: 0
+      cards: [FEAT-0069-01, FEAT-0069-02]   # existing — the ONLY card-ID partition
+      description: "Foundation/scaffold"     # existing
+      wave: 1                                # opt — 1-based wave index (contiguous over groups)
+      wave_name: "Fondamenta server"         # opt — short, unique human NAME for the wave
+      wave_rationale: "migration + config + resolver + enforcement server"  # opt — why this wave
+```
+
+Rules:
+- **Optional (`C`)**, epic-only. They are **sub-keys of `execution_strategy`** (already `R`), NOT
+  top-level fields — the field-state matrix carries **no new row** and the baseline validator (which
+  checks only top-level presence/non-emptiness) never sees them. Legacy epics lack them → no HALT,
+  no migration.
+- **Ownership split (same as [`provenance`](#provenance-session-id-traceability--optional-skill-written)):**
+  the `/prd` **orchestrator** COMPUTES the wave partition + names + rationale (a launch judgment that
+  needs discovery context — migration-early, review-`deep` pressure, server↔UI cut — which the
+  mechanical `prd-card-writer` does not hold), and it is PERSISTED onto the epic card. The card-writer
+  emits these keys ONLY when handed them; otherwise it **omits** them.
+- **Contiguity invariant:** waves partition the groups in `level` order — a wave is a contiguous run
+  of groups. `wave` numbers ascend 1,2,3…; every group in the same wave shares one `wave_name`.
+- **Single-run:** ≤1 distinct `wave_name` across all groups (e.g. a light-lane 1-child epic) means
+  "launch in one run" — the orchestrator leaves the wave keys ABSENT rather than tagging everything
+  `wave: 1`.
+
+**Launch waves (render-time — NOT persisted):** the human-facing launch plan is derived, never
+stored beyond the three keys above:
+- The **wave view** = group the epic's `groups[]` by `wave_name`, ordered by `wave`; each wave's
+  cards = the union of its groups' `.cards`. Consumers: `/prd` final message ("Piano di
+  implementazione suggerito") and `/new`/`/new2` final message ("prossime wave rimanenti", joining
+  wave membership with each card's on-disk `status`).
+- The **engine recommendation** (`/new` vs `/new2`) is computed at render time and is **runtime-aware**
+  — `/new2` needs the Workflow tool and is **Claude-only** (see `framework/agents/runtime-portability-protocol.md`
+  § "Workflow acceleration" — *no Codex equivalent*). It is **never persisted** on the card: a durable,
+  cross-tool artifact must not carry a runtime-capability recommendation a Codex consumer cannot execute.
+- The anti-parallel hard rule ("no other work on the same files between waves") and any project-specific
+  post-wave gates (surfaced from `.baldart/overlays/prd.md`) are render-time constants, likewise not persisted.
+
 ## Acceptance-criteria grammar (EARS) + per-AC oracles (since the EARS+verify wave)
 
 **Why**: a prose AC passes gates without being verifiable ("handle it correctly"), and

package/package.json

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