baldart 4.9.0 → 4.10.0

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.10.0] - 2026-06-04
+
+**`/new` ora ha una todo list persistente e una progress bar — durante un batch sai sempre quale fase gira, quale wave del team mode è in volo, e quale gate è risolto o skippato (con motivo).** Finora `/new` era un orchestratore autonomo cieco verso l'utente: l'unica traccia di stato era il tracker file interno `/tmp/batch-tracker-<FIRST-CARD-ID>.md`, che l'utente **non vede**. Risultato: in un run lungo (15 fasi per card, 50+ gate, sequential o team mode a wave) non avevi modo di capire dove fosse il processo. La fix replica il doppio meccanismo che dà a `/prd` la sua todo list amata, adattato alla struttura `wave → card → fase/gate`: (1) un **Task spine nativo** (TaskCreate/TaskUpdate) — il pannello todo sempre visibile della UI — tenuto *coarse*, un task per card etichettato per wave (`Wave 1 · FEAT-0502 — <title>`) più i framing task `Pre-flight`/`Final review`/`Merge & cleanup`; (2) una **Progress Bar markdown** emessa **alle transizioni** (cambio fase/wave/card, decisione gate, ogni `AskUserQuestion`/STOP — non a ogni messaggio, per non fare rumore nei tratti autonomi) con tabella card×wave + un **Gate ledger** che mostra ogni gate `✅ risolto` / `⏭️ skippato (+motivo)`. **MINOR** (capability aggiunta alla skill `/new`; nessuna chiave `baldart.config.yml` — usa solo i Task tool nativi e l'`execution_strategy` già esistente).
+
+> **Why.** Il valore è la *visibilità*, ma il vincolo è non trasformare il ledger in una licenza di skip. Per costruzione: ogni entry `⏭️` deve citare un motivo **verbatim** dalle skip-reason già enumerate nelle Gate table (`IS_TRIVIAL`, `review_profile=light`, `backend-only diff`, `features.has_e2e_review:false`, `balanced→Final`, `holistic_audit provenance`); un `⏭️ (time budget)` / `(to save tokens)` è esso stesso una violazione di protocollo per la clausola top-of-file "NO PHASE SKIP FOR PERCEIVED TIME". Il ledger rende i skip **auditabili**, non li autorizza. Il tracker interno resta la SSOT di recovery; il Task spine + Progress Bar sono il suo specchio live — esattamente il pattern `/prd` state-file ↔ progress bar.
+
+### Added
+
+- **`framework/.claude/skills/new/SKILL.md`** — nuova sezione autoritativa **"Progress Visibility (MANDATORY)"** (subito dopo "Context Tracking"): definisce una volta sola (A) il Task spine nativo per-card etichettato per wave con la tabella delle transizioni di stato (`Pre-flight`/card/`Final review`/`Merge & cleanup`), (B) il format e i trigger della Progress Bar a transizione con il Gate ledger e la regola dei motivi-verbatim, (C) il mapping fase→cella del ledger (2.5b/2.55/2.6/3/3.5/3.7 + i gate di setup). Reminder a una riga `→ Visibility` nei punti di transizione già esistenti — Pre-flight (creazione spine dopo la risoluzione di modalità/wave), Phase 1 step 2b (claim → card `in_progress`), Phase 4 step 29 (DONE → card `completed`), team mode Step B/D.6/E (confini di wave) e Step F.1/Phase 6 (transizioni di batch) — senza duplicare logica in ogni fase. Aggiunta una "Update rule" del tracker che lega ogni transizione interna ai due surface visibili.
+
 ## [4.9.0] - 2026-06-04
 
 **`prd-card-writer` Rule C apre `light` alle card UI-presentazionali — la metà `-ui` di una coppia split non paga più una review Codex piena su un diff di pixel.** Finora il pavimento era assoluto: *ogni* card `feature`/`enhancement` era `balanced` minimo, mai `light`. La regola nasceva giusta (non sotto-revisionare feature che *sembrano* piccole ma nascondono logica), ma non distingueva una UI card che *contiene* logica da quella genuinamente presentazionale — tipicamente la metà `-ui` di una coppia `logic/ui` già splittata dalla atomicity rule (es. `…-submit-ui`, la cui logica vive nella card sorella `…-submit-logic`). Risultato: su un epic come FEAT-0019, card puramente compositive venivano marcate `balanced` → review Codex-`full` per-card su un diff di soli componenti. Nuovo **ramo LIGHT (b)**, recintato e deterministico: scatta SOLO se TUTTE valgono — card pure-UI (`areas == [ui]`, o `owner_agent: ui-expert` quando `areas` è assente) · ≤3 file, tutti componenti/stili (zero data-fetching / state / API / server) · **nessun path sotto `paths.components_primitives`** (compone primitive esistenti, non ne crea/modifica) · nessun trigger DEEP. **MINOR** (nuova capability di routing in Rule C; nessuna chiave `baldart.config.yml` — si appoggia su `areas`/`owner_agent`/`paths.components_primitives` già esistenti).

package/VERSION

@@ -1 +1 @@
-4.9.0
+4.10.0

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

@@ -129,6 +129,78 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
   - **card_status: DONE (verified)** — confirms the backlog YAML was updated and re-read to verify
 - **When blocked**: log the blocker in `## Issues & Flags`.
 - **On context recovery**: if you ever feel lost or after context compaction, IMMEDIATELY read your tracker file (`/tmp/batch-tracker-<FIRST-CARD-ID>.md`) to restore your state.
+- **Mirror every transition to the user (MANDATORY)**: this tracker file is internal — the user does NOT see it. Every transition you log here MUST also be reflected in the **two user-visible surfaces** defined in § "Progress Visibility": the native **Task spine** (TaskUpdate) and, at transition boundaries, the **Progress Bar**. The tracker is the recovery SSOT; the Task spine + Progress Bar are its live mirror.
+
+---
+
+## Progress Visibility (MANDATORY)
+
+The `/tmp/batch-tracker-*.md` file is your **internal** recovery SSOT — the user never sees it. Because `/new` runs largely autonomously (YOLO mode, long stretches of agent spawns), the user otherwise has no idea which phase is running, which wave of the team mode is in flight, or which gate was just resolved vs skipped. This section defines the **two user-visible surfaces** that fix that. They are the live mirror of the tracker; keeping them in sync is non-negotiable.
+
+> **HARD RULE — visibility.** (1) Maintain the native **Task spine** via TaskCreate/TaskUpdate. (2) Emit the **Progress Bar** at every transition boundary (defined below). Both mirror the tracker. Failing to update either after a transition is a protocol violation.
+
+### A. Task spine — native TaskCreate/TaskUpdate (the always-visible panel)
+
+The native task list is what Claude Code renders as a **persistent, always-visible todo panel** (this is exactly how `/prd` gets its beloved todo list — see `framework/.claude/skills/prd/SKILL.md` HARD RULE 4). Keep it **coarse**: one task per card plus a few batch-level framing tasks. Do NOT create a task per phase (that buries the overview).
+
+**When to create (once):** right after Pre-flight has resolved the execution mode (sequential vs team) and, in team mode, the wave layout (`execution_strategy.groups[].level`) — because only then do you know the wave label for each card. Create, in this order:
+
+1. `Pre-flight` — framing task (already in progress by the time you create the spine; mark it `in_progress` immediately and `completed` as soon as the worktree is ready).
+2. One task **per card**, in queue order. Subject:
+   - **team mode** (wave-labelled): `Wave <level> · <CARD-ID> — <title>` (e.g. `Wave 1 · FEAT-0502 — Add merchant filter`).
+   - **sequential mode**: `<CARD-ID> — <title>` (no wave prefix).
+3. `Final review` — framing task.
+4. `Merge & cleanup` — framing task.
+
+**State transitions (TaskUpdate):**
+
+| Task | → `in_progress` | → `completed` |
+|------|-----------------|---------------|
+| `Pre-flight` | at spine creation | worktree ready (end of Pre-flight) |
+| card task | **Phase 1 step 2b** (claim — when you set the card `status: IN_PROGRESS`) | **Phase 4 step 28** (after commit + `card_status: DONE (verified)`) |
+| `Final review` | start of Final Review (F.1) | Final Review complete (fixes applied, build green) |
+| `Merge & cleanup` | start of Phase 6 | end of Phase 6c |
+
+**Live sub-state in the subject (optional but encouraged):** while a card task is `in_progress`, you MAY append the current phase to its subject so the panel shows live movement between Progress Bar emissions — e.g. `Wave 1 · FEAT-0502 — Add merchant filter · Phase 3.7 Codex 🔄`. Strip the suffix when the card completes.
+
+In team mode the cards of a wave run in parallel: set ALL of a wave's card tasks `in_progress` when that wave's coders are spawned (Step B), and complete each as its per-card pipeline reaches Phase 4 (team Step D.5/D.6).
+
+### B. Progress Bar — markdown, at transition boundaries
+
+Append this block to your message **at every transition boundary** (NOT on every message — that would be noise across long autonomous runs). A **transition boundary** is any of: a phase change, a wave change, a card change, **any gate decision** (resolved or skipped), and every `AskUserQuestion` / STOP.
+
+```
+---
+📋 **Progresso /new: <batch-id>** — modalità <sequential|team> · Wave <X>/<Y>
+
+| Card | Wave | Fase corrente | Stato |
+|------|------|---------------|-------|
+| FEAT-0501 | 0 | Phase 4 Commit | ✅ |
+| FEAT-0502 | 1 | Phase 3.7 Codex | 🔄 |
+| FEAT-0503 | 1 | — | ⬜ |
+
+Gate ledger (card corrente): 2.5b AC-Closure ✅ · 2.55 Simplify ✅ · 2.6 E2E ⏭️ (backend-only) · 3 Doc ⏭️ (light, no-doc-diff→Final) · 3.5 QA ⏭️ (balanced→Final) · 3.7 Codex 🔄
+Prossimo passo: <cosa succede dopo>
+```
+
+- Legend: `⬜ da fare · 🔄 in corso · ✅ risolto · ⏭️ skippato`.
+- The `Wave` column and the `Wave <X>/<Y>` header are present in **team mode** only; in sequential mode drop the column and write `modalità sequential` with no wave counter.
+- The **Gate ledger** line shows the current card's per-card gates (see § C for which). Each entry is `<gate> <state>`; a skipped entry MUST carry its reason **verbatim from the enumerated Gate-table / fast-lane skip reasons** — e.g. `IS_TRIVIAL`, `review_profile=light`, `backend-only diff`, `features.has_e2e_review:false`, `balanced→Final`, `holistic_audit provenance`. **Never invent a reason.** A ledger entry reading `⏭️ (time budget)` / `(to save tokens)` / any model-invented constraint is itself a protocol violation (see the top-of-file "NO PHASE SKIP FOR PERCEIVED TIME" clause) — the ledger exists to make skips auditable, not to license them.
+
+### C. Phase → ledger mapping
+
+These are the per-card gates tracked in the Gate ledger line (the rest of the pipeline — Phase 1 context, Phase 2 implement, Phase 4 commit — is shown in the table's "Fase corrente" column, not the ledger):
+
+| Ledger entry | Phase | Skipped when (enumerated reason) |
+|--------------|-------|----------------------------------|
+| `2.5b AC-Closure` | Phase 2.5b | never (BLOCKING, unconditional) |
+| `2.55 Simplify` | Phase 2.55 | `IS_TRIVIAL` |
+| `2.6 E2E` | Phase 2.6 | `features.has_e2e_review:false`, backend-only diff, or card type ∈ {backend/api/db/infra/docs/chore/config} |
+| `3 Doc` | Phase 3 | `review_profile=light` AND no doc files in diff → deferred to Final F.3 |
+| `3.5 QA` | Phase 3.5 | `skip`/`light` (tests already ran Phase 2), or `balanced`→Final (unless Step-A escalation) |
+| `3.7 Codex` | Phase 3.7 | `IS_TRIVIAL` only (otherwise unconditional; `light`/`full` is depth, not skip) |
+
+In **team mode** the same gates map to the per-card team sub-steps (D.3a AC-Closure, D.3b Simplify, D.3c E2E, D.4 QA, D.4a/D.2 doc, D.4b Codex) — track them identically. The pre-flight cross-card Codex check (Step 3d) and plan-auditor grounding (Phase 1 step 4) are batch/card-setup gates: surface their resolve/skip in the `Prossimo passo` line or a one-off ledger note, not as recurring per-card rows.
 
 ---
 
@@ -274,6 +346,8 @@ Trunk branch: [resolved git.trunk_branch — Phase 0 step 0 populates]
 
    When `mode == sequential`, the per-card pipeline below runs exactly as documented. The `execution_strategy.groups` levels are simply ignored. When `mode == team`, skip the per-card pipeline and follow the **Team Mode** section at the end of this document.
 
+   **→ Create the Task spine now.** The execution mode and (in team mode) the wave layout are resolved — create the native Task spine per § "Progress Visibility" A: `Pre-flight` (→ `in_progress`) + one task per card (wave-labelled in team mode) + `Final review` + `Merge & cleanup`. Emit the first Progress Bar with this batch's table. Mark `Pre-flight` → `completed` once worktree setup (step 5) finishes.
+
 3d. **Codex batch cross-card grounding check** (runs in background during worktree setup)
 
    > **Why**: a non-Anthropic frontier model (Codex, via `codex-companion.mjs`) reviews the full card batch for cross-card conflicts that per-card plan-auditor checks cannot detect (each plan-auditor sees only one card).
@@ -493,7 +567,7 @@ For each card, execute these phases in order:
    - Read that card's backlog YAML and check its `status` field.
    - If NOT `DONE` → HALT: log in `## Issues & Flags` and ask the user: "Card <CARD-ID> depends on <DEP-ID> which is `<status>`. Proceed anyway, or wait?" Do not start implementation until the user responds explicitly. **The card status is NOT written until this gate passes** — so a HALT leaves the card untouched (no stale `IN_PROGRESS` for the next run to mis-read).
    - If `DONE` (or the user chose "proceed anyway") → continue.
-2b. **Claim** — only now set the card status to `IN_PROGRESS` and assign yourself.
+2b. **Claim** — only now set the card status to `IN_PROGRESS` and assign yourself. **→ Visibility**: TaskUpdate this card's spine task → `in_progress`, and emit a Progress Bar (card change) per § "Progress Visibility".
 2c. **Trivial-card classification (BLOCKING gate for steps 3–4)** — evaluate `IS_TRIVIAL(card)` per § "Trivial-card fast-lane". Note: condition 3 (non-source diff) cannot be fully evaluated until the coder has produced the diff, so at this point compute the **provisional** trivial flag from conditions 1+2 only (`review_profile == skip` AND no Step-A trigger sourced from the card YAML text + `files_likely_touched` extensions — if EVERY path in `files_likely_touched` is non-source, condition 3 is provisionally satisfied). If provisionally trivial → **SKIP steps 3, 3a, and 4** (architecture grounding); log `trivial: architecture grounding skipped (review_profile=skip + non-source files_likely_touched + 0 triggers)` and jump to Phase 2. Re-confirm `IS_TRIVIAL` on the ACTUAL committed diff at the review gates (Phase 2.55/3.5/3.7); if the coder unexpectedly touched a source file, the guard flips the card back onto the normal review path there. If NOT provisionally trivial → run steps 3, 3a, 4 as normal.
 3. **(skip when provisionally trivial — see 2c)** Invoke the **codebase-architect** agent (MUST per AGENTS.md) to understand the relevant codebase area, existing patterns, and architecture before any implementation. When `features.has_lsp_layer: true`, the architect uses LSP find-references for identifier-shaped lookups — this needs NO handoff from the orchestrator: the architect reads `features.has_lsp_layer` from `baldart.config.yml` directly (the flag is ambient) per `agents/code-search-protocol.md`. The orchestrator does NOT propagate the flag. (Earlier doc versions numbered this step 4; the step that read project-status BEFORE the architect was removed because it persisted pre-analysis context — see step 3a.)
 3a. Update `${paths.references_dir}/project-status.md` Active Code Context (skip when the file does not exist in the project) — do this AFTER the codebase-architect run (step 3) so the "Active Code Context" reflects the architect's findings (which files are actually in scope), not just the card YAML's `files_likely_touched`. Writing it before the architect run would persist pre-analysis claims that downstream agents (e.g. a parallel card) would then read as truth.
@@ -1599,7 +1673,7 @@ The detector (Step A) is bash + grep — guaranteed to run, no LLM skip. The dow
     c. **Update `${paths.references_dir}/ssot-registry.md`** — add/update the entry for this card's feature area. The pre-commit doc-freshness hook BLOCKS commits that touch `${paths.backlog_dir}/` without a corresponding ssot-registry update. Always include ssot-registry.md in the same commit as the backlog YAML.
     d. **Verify the write**: re-read the YAML file and confirm `status: DONE` is present. If not, retry the edit.
     e. Stage BOTH the updated YAML AND ssot-registry.md, then commit (or as an immediate follow-up commit if the Phase 4 implementation commit already happened). When this produces a SECOND commit for the card, record BOTH hashes in the tracker (`commit: <impl-hash> + <done-hash>`) so traceability/bisect is unambiguous.
-29. **Update tracker**: move card to `## Completed Cards` with commit hash(es), summary, flags, **and `card_status: DONE (verified)`**.
+29. **Update tracker**: move card to `## Completed Cards` with commit hash(es), summary, flags, **and `card_status: DONE (verified)`**. **→ Visibility**: TaskUpdate this card's spine task → `completed` (strip any live phase suffix) and emit a Progress Bar (card change) per § "Progress Visibility".
 
 ### Sub-agent failure protocol (since v3.28.3)
 
@@ -1649,6 +1723,8 @@ Once ALL cards are committed in the worktree:
 
 ### Step F.1 — Resolve scope
 
+**→ Visibility (batch transition)**: all cards are committed. TaskUpdate `Final review` → `in_progress` and emit a Progress Bar per § "Progress Visibility". Mark `Final review` → `completed` when F.5 finishes (fixes applied, build green).
+
 1. **Read the tracker file** to get the full picture: card IDs, files changed, commit hashes.
 2. Gather git evidence in the worktree:
    ```bash
@@ -1882,6 +1958,8 @@ Once ALL cards are committed in the worktree:
 
 ## Phase 6 — Post-batch merge & cleanup (delegated to worktree-manager skill)
 
+**→ Visibility (batch transition)**: TaskUpdate `Merge & cleanup` → `in_progress` and emit a Progress Bar per § "Progress Visibility". Mark it → `completed` at the end of Phase 6c (merge done, worktree removed, workspace reconciled).
+
 After the final review passes AND all cards are committed in the worktree, delegate the entire merge and cleanup to the **worktree-manager** skill (`/mw` in programmatic mode):
 
 1. **BEFORE invoking /mw** — verify no uncommitted files remain in the worktree:
@@ -2365,6 +2443,8 @@ its `arch_baseline_path` at this file, so the review reuses the group baseline i
 
 #### Step B: Spawn parallel coder agents
 
+**→ Visibility (wave change)**: this is a new wave starting. TaskUpdate ALL of this group's card spine tasks → `in_progress`, and emit a Progress Bar with the new `Wave <X>/<Y>` header per § "Progress Visibility".
+
 For each card in the current group, spawn a coder agent using the Agent tool. ALL agents for the group MUST be spawned in a **SINGLE message** (multiple Agent tool calls) to run truly in parallel.
 
 Each coder agent receives a **SELF-CONTAINED** mission briefing that includes EVERYTHING it needs — it will NOT call codebase-architect or plan-auditor itself:
@@ -2513,6 +2593,7 @@ After ALL agents in the group complete successfully:
    b. **Verify the write**: re-read the YAML file and confirm `status: DONE` is present. If not, retry.
    c. Stage the updated YAML and include it in the card's commit (or as an immediate follow-up commit).
    d. Log in tracker: `card_status: DONE (verified)` for each card.
+   e. **→ Visibility**: TaskUpdate each card's spine task → `completed` (strip any live phase suffix) as it reaches DONE here.
    Note: Phase 6b (Status Reconciliation) will catch any card missed here, but aim for zero misses.
 
 #### Step D coverage assertion (MANDATORY end-of-group check)
@@ -2535,7 +2616,8 @@ A missing entry means a sub-step was skipped. An entry whose value is a **`revie
 After committing all cards in the group:
 1. Update tracker: move group to done, log all results per card.
 2. **PURGE**: forget all implementation details, review findings, architect context.
-3. Move to the next pending group (Step A again).
+3. **→ Visibility**: emit a Progress Bar reflecting the wave boundary (this wave done; next `Wave <X+1>/<Y>` pending) per § "Progress Visibility".
+4. Move to the next pending group (Step A again).
 
 ### Sequential fallback within team mode
 

package/package.json

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