baldart 5.11.1 → 5.11.2

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.11.2] - 2026-07-07
+
+**`/new` final report — including the v5.8.0 wave-aware launch plan — is now the SINGLE terminal message on BOTH runtimes; fixes the "buried wave summary" on Codex.**
+A user reported that despite the v5.8.0 wave-launch-plan update, a **Codex-hosted** `/new` run ended not on the mandated `## Prossimi Passi` / `### Prossime wave da sviluppare` section but on an ad-hoc operational status (`db:check-sync OK`, `registry:sync OK`, `Repo allineate`, `card 01-05 DONE`). Root cause, confirmed after adversarially refuting the obvious diagnoses: the `/prd` wave-tag persistence is engine-agnostic (backlog-phase.md — fine) and `new2`'s wave line is Claude-only (not the Codex path), so the defect is entirely in `/new`'s **terminal reporting structure**. The wave-aware Next Steps lives only in Final Review **F.6 step 4b**, which the phase order places **before** Phase 6 (merge) / Phase 7 (production readiness) / Phase 8 (metrics). On **Claude** the near-silent rule suppresses that trailing Phase 6/7/8 narration, so the mid-run report survives *by accident* as the last block. On **Codex** the runtime does **not** honor that suppression (it narrates `db:check-sync` / `registry:sync` / `git status`), so the report gets buried and the run closes on operational noise + a self-composed summary. F.6 4b also had **no `Codex:` branch**, against the runtime-portability discipline.
+
+The fix makes the Final Report **engine-independent** by turning it into a genuine terminal emission (no reliance on suppression):
+- **Compose + persist, don't emit mid-run** — Final Review F.6 (steps 4/4b, `final-review.md`) now composes the verdict + per-card result block + actionable residue + **wave-aware Next Steps** and writes them to the tracker under a `## Final Report` section instead of emitting them in place; Phase 7 (`production-readiness.md`) appends its checklist to the same block instead of rendering standalone.
+- **New terminal step** (`metrics.md` § "Terminal — Final Report emission") — runs LAST, after every Phase 8 step, and **ALWAYS** (even if the non-blocking metrics write SKIPPED/failed): it reads `## Final Report` from the tracker and emits it verbatim as the ONE terminal user-facing message, with a fallback that re-derives the wave summary if the tracker block is missing (legacy / compaction) rather than closing on a bare status line.
+- **Explicit `Codex:` reinforcement** on F.6 4b + the terminal step: on Codex the run MUST still END on the `## Final Report` (wave-aware Next Steps included) regardless of any preceding operational narration.
+- **New binding-table row** in `framework/agents/runtime-portability-protocol.md` § "Terminal report emission" (the SSOT the three skill modules now cite) — Claude relies on near-silent suppression; Codex must compose+persist+emit-terminally. SKILL.md § near-silent case 3 updated to name the terminal anchor.
+
+**Codex parity: portable** (prose-only; the persist-then-emit-terminally design is what makes it engine-independent — it is the fix's whole point). `new2` is unaffected (Claude-only; its report is the workflow return, terminal by construction). **No new `baldart.config.yml` key** → the schema-change propagation rule does NOT apply. `/new` skill version → 2.4.2. Parity guard (`scripts/check-new-parity.mjs`) green.
+
 ## [5.11.1] - 2026-07-07
 
 **`/new` now tears down its idle background subagents at end of run — closes the "Background work is running" leak on terminal exit.**

package/VERSION

@@ -1 +1 @@
-5.11.1
+5.11.2

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

@@ -2,6 +2,30 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 2.4.2 — 2026-07-07
+
+- **Il report finale (incl. il piano wave v5.8.0) è ora l'UNICO messaggio terminale su entrambi i runtime — fix del "riepilogo wave sepolto" su Codex.**
+  Su un run Codex-hosted il `/new` chiudeva su uno status operativo ad-hoc (`db:check-sync OK`,
+  `registry:sync OK`, `Repo allineate`, `card 01-05 DONE`) invece della sezione `## Prossimi Passi` /
+  `### Prossime wave da sviluppare`. Refutate le diagnosi ovvie: la persistenza dei tag wave in `/prd`
+  è engine-agnostica (ok) e la riga wave di `new2` è Claude-only (non il path Codex) → il difetto è
+  tutto nella **struttura di reporting terminale** di `/new`. Le Next Steps wave-aware vivono solo in
+  Final Review **F.6 step 4b**, che l'ordine delle fasi colloca **prima** di Phase 6/7/8. Su **Claude**
+  la regola near-silent sopprime la narrazione di Phase 6/7/8, quindi il report a metà run sopravvive
+  *per caso* come ultimo blocco; su **Codex** quella soppressione non è onorata → il report viene
+  sepolto e il run chiude su rumore operativo + riepilogo auto-composto. 4b non aveva ramo `Codex:`.
+  Fix (rende il report engine-independent, senza dipendere dalla soppressione): (1) F.6 4/4b
+  **compone + persiste** verdict + result block + residue + Next Steps wave-aware nel tracker
+  `## Final Report` invece di emetterli in loco (`final-review.md`); (2) Phase 7 vi **appende** la
+  checklist (`production-readiness.md`); (3) **nuovo step terminale** `metrics.md` § "Terminal — Final
+  Report emission" che gira PER ULTIMO, SEMPRE (anche se la telemetria non-bloccante salta), legge
+  `## Final Report` e lo emette come UNICO messaggio finale, con fallback che ri-deriva il riepilogo
+  wave se il blocco manca; (4) rinforzo `Codex:` esplicito su 4b + step terminale; (5) nuova riga
+  della binding-table in `framework/agents/runtime-portability-protocol.md` § "Terminal report
+  emission" (SSOT citato dai tre moduli). SKILL.md § near-silent caso 3 aggiornato. Codex parity:
+  portable. `new2` non affetto (Claude-only, report = ritorno del workflow). Nessuna nuova chiave
+  `baldart.config.yml`.
+
 ## 2.4.1 — 2026-07-07
 
 - **Teardown dei subagent in background a fine run (chiude il leak "Background work is running").**

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

@@ -1,7 +1,7 @@
 ---
 name: new
 effort: medium
-version: 2.4.1
+version: 2.4.2
 requires_feature: has_backlog
 description: >
   Orchestrate a team of specialized agents to implement one or more backlog cards
@@ -349,8 +349,13 @@ baselines. Keep that bulk on disk and pass **paths**, not bodies.
 >    error string verbatim), no prose around them.
 > 3. **One minimal end-of-batch result block** — one line per card (`CARD-ID: merged @<sha> | failed:
 >    <one clause> | deferred → <followup-id>`) plus only the actionable residue (unresolved/flagged items,
->    the launch command, any production-readiness manual step). NOT a per-phase report — process telemetry
->    lives in the tracker + `skill-runs.jsonl`, never rendered.
+>    the **wave-aware Next Steps / launch command**, any production-readiness manual step). NOT a per-phase
+>    report — process telemetry lives in the tracker + `skill-runs.jsonl`, never rendered. **This block is
+>    the SINGLE terminal user-facing message: it is composed + persisted to the tracker `## Final Report`
+>    during Final Review F.6 / Phase 7, then emitted ONCE as the LAST thing the run outputs, AFTER Phase 8
+>    (`metrics.md` § "Terminal — Final Report emission") — never mid-run, never followed by an ad-hoc status
+>    line. On Codex, where Phase 6/7/8 operational output is not suppressed, the run MUST still END on this
+>    `## Final Report`.**
 > This governs the orchestrator's *prose*, not any agent's return contract (that is § "Context economy" above).
 >
 > These rules reduce the *number* of replays; the bulk-content rule above reduces the *size* of each.

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

@@ -410,9 +410,22 @@ that is a **gate violation**: log it as
    If the project ships a `knowledge-sync` corpus agent (declared in `.baldart/overlays/new.md`), invoke it after doc updates so the external corpus stays aligned. If no such agent exists, skip this step with a one-line notice (do NOT dispatch a non-existent agent).
 
 3. **Proceed to Phase 6** (post-batch merge & cleanup).
-4. Emit the **minimal end-of-batch result block** (per § "orchestrator is near-silent" in the core SKILL.md — this is NOT a per-phase report). ONE line per card and nothing more of the process telemetry:
+4. **Compose** the **minimal end-of-batch result block** (per § "orchestrator is near-silent" in the core SKILL.md — this is NOT a per-phase report) and **persist it verbatim to the tracker under a `## Final Report` section — do NOT emit it here.** ONE line per card and nothing more of the process telemetry:
    - `<CARD-ID>: merged @<sha> | failed: <one clause> | deferred → <followup-id>`
 
+   > **Terminal-emission anchor (v5.11.2 — the fix for the Codex "buried wave summary").** The Final
+   > Report (this result block + the Next Steps / wave plan in 4b + the Phase 7 Production Readiness
+   > checklist) is the **single user-facing terminal message** of the whole run — it is emitted **ONCE,
+   > as the LAST thing the user reads, AFTER Phase 8** (`metrics.md` § "Terminal — Final Report
+   > emission"), **not here**. F.6 runs before Phase 6/7/8, so emitting the report now buries it under
+   > the merge / production-readiness / metrics output that follows. On **Claude** the near-silent rule
+   > (SKILL.md case 3) suppresses that trailing output so the mid-run report happens to survive as the
+   > last block; on **Codex** the runtime does NOT honor that suppression (it narrates the Phase 7
+   > `db:check-sync` / `registry:sync` steps), so a mid-run report is lost and the run closes on an
+   > ad-hoc operational status instead of the mandated wave summary. Persisting to `## Final Report`
+   > and emitting terminally makes the report engine-independent. So here in F.6: **compose the content,
+   > write it to the tracker's `## Final Report`, and continue** — the terminal step emits it.
+
    **Report verdict (v5.6.0 — HARD headline rule, FEAT-0068 post-mortem).** The FIRST line of the
    result block is a verdict, and it is computed, not felt:
    - `⚠️ PARTIAL — obiettivo epic NON raggiunto: <one clause naming the gap>` whenever ANY of:
@@ -426,9 +439,9 @@ that is a **gate violation**: log it as
    user discovered it only by asking. "Nulla perso" (tracking) is never a substitute for "non
    finito" (truth): a follow-up that holds the epic's remaining work is REMAINING WORK.
 
-   Then, **only if non-empty**, the **actionable residue**: issues needing user attention (anything unresolved, partially wired, or flagged — terse, with `path:line` / `CARD-ID` exact). All process telemetry — files changed, test/build/lint status, fix cycles, review-finding counts, UX/QA verdicts, commit + merge hashes, card-status reconciliation, worktree cleanup, knowledge-corpus sync — is **NOT rendered**: it lives in the tracker and `$METRICS/skill-runs.jsonl`. (The Next Steps & Launch Command in 4b below and any Production Readiness manual steps ARE part of the actionable residue — keep them.)
+   Then, **only if non-empty**, the **actionable residue**: issues needing user attention (anything unresolved, partially wired, or flagged — terse, with `path:line` / `CARD-ID` exact). All process telemetry — files changed, test/build/lint status, fix cycles, review-finding counts, UX/QA verdicts, commit + merge hashes, card-status reconciliation, worktree cleanup, knowledge-corpus sync — is **NOT rendered**: it lives in the tracker and `$METRICS/skill-runs.jsonl`. (The Next Steps & Launch Command in 4b below and any Production Readiness manual steps ARE part of the actionable residue — keep them.) **The verdict line + result block + actionable residue all go into the same persisted `## Final Report` block** (do NOT emit them now — the terminal step in `metrics.md` does).
 
-4b. **Next Steps & Launch Command** (MANDATORY section — always present):
+4b. **Next Steps & Launch Command** (MANDATORY section — always present). **Compose it and APPEND it to the persisted `## Final Report` block from step 4 — do NOT emit it here** (the terminal step in `metrics.md` emits the whole `## Final Report`). **Codex (runtime-portability): this section is engine-INDEPENDENT and MUST be present in the terminal message on a Codex-hosted run exactly as on Claude** — the near-silent suppression of Phase 6/7/8 narration is NOT guaranteed on Codex, so persisting-then-emitting-terminally (not the suppression) is what keeps the wave summary from being buried. Rule: `framework/agents/runtime-portability-protocol.md` § "Terminal report emission".
 
    Check for remaining not-yet-DONE cards in the same epic group (match "not DONE",
    not a hard-coded status value — see the `status enum` SSOT in REGISTRY.md):

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

@@ -70,3 +70,17 @@ has no blocking consequence the honest label is "monitoring signal".
 **If `$METRICS/skill-runs.jsonl` does not exist**: create it first with `mkdir -p "$METRICS" && touch "$METRICS/skill-runs.jsonl"`.
 **If batch tracker is missing or unreadable**: log "Metrics Log: SKIPPED (tracker not found)" and proceed without blocking.
 **This phase is NON-BLOCKING** — if it fails for any reason, do not abort the run. The `-stats` step in particular is best-effort: the script is fail-safe (always exits 0), so never let it block the commit.
+
+---
+
+## Terminal — Final Report emission (v5.11.2 — the SINGLE user-facing end message)
+
+**This runs LAST, after every Phase 8 step above, and it ALWAYS runs — even if the Phase 8 telemetry SKIPPED or failed** (the report is a user deliverable; the metrics write is monitoring). It is the ONE terminal user-facing message of the whole `/new` run (case 3 of the near-silent rule, SKILL.md).
+
+1. **Read the `## Final Report` section from the tracker** (`$TRACKER`). Final Review F.6 (steps 4/4b) composed it — verdict line + one line per card + actionable residue + Next Steps / **wave-aware launch plan** — and Phase 7 appended the Production Readiness checklist to the same block.
+
+2. **Emit that `## Final Report` verbatim as the run's terminal message** — nothing after it. This is the last thing the user reads. Do NOT re-render process telemetry around it (§ "orchestrator is near-silent").
+
+3. **Fallback (tracker `## Final Report` missing / empty — legacy or a mid-run compaction that lost it):** re-derive the report on the spot from the tracker's `## Completed Cards` + `## Worktree Merges` + the epic card's wave tags (final-review.md F.6 step 4b procedure) rather than closing on a bare status line. A terminal message that is only "repo aligned / cards DONE" is the exact regression this step fixes.
+
+> **Codex (runtime-portability — the fix's target case).** On a **Codex-hosted** run the near-silent suppression of the Phase 6/7/8 operational narration (`db:check-sync`, `registry:sync`, `git status`, …) is NOT guaranteed, so that output may precede this message. It does not matter: **the run MUST still END with the `## Final Report` block** (verdict + result lines + **wave-aware Next Steps**), emitted here as the terminal message — never let an ad-hoc operational summary ("repo allineate / card DONE") be the last thing the user sees. The persisted-then-emitted-terminally design is exactly what makes this engine-independent. Rule: `framework/agents/runtime-portability-protocol.md`.

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

@@ -4,7 +4,7 @@
 
 ## Phase 7 — Production Readiness Checklist
 
-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.
+After Phase 6 completes, compose a **Production Readiness Checklist** — a clear list of all manual or infrastructure actions required to launch the implemented changes in production. **Do NOT emit it standalone here: APPEND it to the persisted `## Final Report` block (the one Final Review F.6 started) — the single terminal step in `metrics.md` § "Terminal — Final Report emission" emits the whole report AFTER Phase 8.** (Auto-executing the agent-doable items below still happens in THIS phase — only the *rendering* of the checklist is deferred to the terminal message.)
 
 > **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
@@ -39,7 +39,8 @@ asking the user.
 
 ### Output format
 
-Present the checklist as a clearly formatted section in the final report.
+Compose the checklist as a clearly formatted section and append it to the persisted
+`## Final Report` (emitted terminally after Phase 8 — see the note at the top of this phase).
 The example below assumes `stack.deployment: firebase` + `stack.database: firestore`;
 adapt commands and tags to the project's resolved stack.
 

package/framework/agents/runtime-portability-protocol.md

@@ -66,6 +66,7 @@ Three of the operations below are already binding cross-tool in
 | **Decision gate (ask user)** | `AskUserQuestion` (STOP, wait — the only action that turn) | a plain, single, concise user prompt (or `request_user_input` if the runtime exposes it); in autonomous mode, the skill's AUTONOMOUS RESOLUTION RULE | this module (gate *policy* — e.g. no-silent-AC-deferral — stays in the skill) |
 | **Read / write path** | `Read` / `Write` / `Edit` (absolute paths) | shell / `apply_patch` / filesystem tools | invariant is **worktree-rooted absolute path**, NOT a tool name — `cd` is not sufficient (an absolute path can still escape). Isolation rule: AGENTS.md (CITE) |
 | **Adversarial vs cross-model review** | an external Codex companion from Claude = genuinely **cross-model** | a same-runtime Codex pass (when the host IS Codex) = **adversarial fresh-context only, NOT cross-model** | this module |
+| **Terminal report emission** | the near-silent rule suppresses trailing phase narration, so a mid-run report survives as the last block | narration is NOT suppressed → a mid-run report gets buried; **compose+persist the report to the run's state file, then emit it ONCE as the terminal message after the last phase** — engine-independent, never rely on suppression | this module |
 
 ## Capability detection contract
 

package/package.json

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