baldart 4.12.0 → 4.14.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ 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.14.0] - 2026-06-04
+
+**Nuovo tipo di payload `.claude/workflows/` (dynamic workflow di Claude Code) + il primo workflow `new-final-review`: la Final Review F.2–F.4 di `/new` può girare come script di orchestrazione deterministico, opt-in e con fallback inline.** I dynamic workflow (research-preview di Claude Code) spostano l'orchestrazione fan-out fuori dal context-window dell'orchestrator, nel codice. Una review avversariale ha **refutato** l'idea di farne il motore *per-card* di `/new` (rompe la portabilità Codex — sono Claude-only; dipende da una preview come breaking change; duplica la logica di gate col team-mode; introduce attrito-permessi e regressione di recovery proprio dove `/new` è più intrecciata con worktree/git/stato). Il bersaglio scelto è invece la parte dove i rischi spariscono e il valore resta: la **Final Review F.1–F.6** è **read-only** (gli agenti leggono solo il diff committato), ha **definizione SSOT unica** condivisa da sequential e team mode (→ nessun twin), e ha l'**adversarial-verify già nativo** (FP-check di Codex in F.3, cross-validation `code-reviewer` a confidence<80 in F.4). **MINOR** (nuova capability additiva: nuovo payload type + un workflow; nessun breaking change, nessuna chiave `baldart.config.yml` — il gating è runtime via presenza del tool `Workflow`; i consumer senza workflow o Codex-only eseguono la Final Review inline come prima).
+
+> **Why.** La Final Review è l'unica fase di `/new` con una definizione singola condivisa da entrambe le modalità e senza ownership di stato git o gate-utente: estrarla in un workflow non duplica nulla e non regredisce nulla. Il confine è netto — il workflow incapsula **F.2 (baseline) + F.3 (fan-out Codex ‖ doc-reviewer ‖ api-perf-cost-auditor ‖ qa-sentinel) + F.4 (consolidamento + verifica)** e ritorna i finding già classificati (`VERIFIED`/`NEEDS_MANUAL_CONFIRMATION`, `FALSE_POSITIVE` scartati) + la gate table; **F.1 (scope), F.5 (apply fix + build + `AskUserQuestion`) e F.6 (wrap-up) restano nella skill**, perché un workflow non può eseguire git né chiedere all'utente. La prosa di `final-review.md` resta SSOT e fallback sempre-disponibile; il workflow ne mirrora solo la *forma di orchestrazione* (i suoi agent-brief citano il modulo per la *semantica* di review). Distribuzione: symlink per-item come skill/agent/command, ma **senza overlay** (l'overlay-merger è per `.md`; un `.js` non ha sezioni markdown) e **solo per Claude** (`codex.js` ritorna `workflowsDir()=null` → mai linkato in un albero Codex).
+
+### Added
+
+- **`framework/.claude/workflows/new-final-review.js`** (nuovo) — workflow `meta.name: 'new-final-review'`, phases `Baseline`/`Review`/`Verify`. Fan-out F.2–F.4 con fallback Codex→`code-reviewer` come branch JS, schema sui finding (`VERIFIED`/`FALSE_POSITIVE`/`NEEDS_MANUAL_CONFIRMATION`), `api-perf-cost-auditor` saltato via branch quando non ci sono file API/data. Tutto da `args` (portabile, anti-contaminazione).
+- **Payload type `.claude/workflows/`** — `src/utils/tool-adapters/claude.js` espone `workflowsDir()='.claude/workflows'`; `codex.js` `workflowsDir()=null` (Claude-only). `src/utils/symlinks.js`: `_mergeBulkDir` generalizzato con mappa per-kind (`MERGE_KINDS`: estensione + overlay on/off), nuovo `mergeWorkflows()`, chiamato in `createAllSymlinks()` e nel reconcile di `update.js`; `verifySymlinks()` esteso a `workflows`. `BALDART_MANAGED_PATTERNS` (`update.js`) include `workflows`. `doctor.js`: probe + repair advisory dei workflow non linkati (Claude-only, non bloccante).
+- **`framework/docs/WORKFLOWS.md`** (nuovo) — cos'è il payload `.claude/workflows/`, il modello opt-in + degradazione, il perché Claude-only e no-overlay.
+
+### Changed
+
+- **`framework/.claude/skills/new/references/final-review.md`** — nuovo **Step F.1.5 (workflow delegation gate)**: se il tool `Workflow` è disponibile e `new-final-review.js` è linkato → delega F.2–F.4 al workflow e porta i finding/gate-table a F.5; altrimenti inline come prima (prosa = SSOT/fallback). Drift-note per i maintainer. `SKILL.md` § Routing annota la delega.
+
+**Il SKILL.md di `/new` scende da 61k a ~10k token (−82%) — il dettaglio passo-passo di ogni fase è uscito dal corpo skill (prefisso di sistema, ri-letto a ogni turno) in moduli `references/*.md` caricati on-demand.** Diagnosi data-driven su una run reale (`/new` su ~4 card → 480k token di contesto): forensics sul transcript dell'orchestrator → il **floor statico è 152k token PRIMA che parta una card**, e il colpevole #1 è il SKILL.md monolitico da **2766 righe / 61k token**, residente nel prefisso di sistema cached e ri-validato a ogni turno (362 turni nella run osservata). Una prima ipotesi ovvia (comprimere la *prosa* degli agent, stile "caveman") è stata **misurata e scartata**: la prosa è ~8k = 2% del totale. La cura replica 1:1 il pattern già in prod su `/prd` (core snello + reference modules + routing table): il core tiene solo gli invarianti cross-fase (Context Tracking, Progress Visibility, § Context economy, Agent Routing, QA Profile, Trivial fast-lane, Risk-signal detector, Fix Application Log) + una **§ Routing** che mappa fase→modulo→skip; ogni fase carica il suo modulo via Read quando ci entra. Contenuto spostato **verbatim** (zero cambi comportamentali; le stesse fasi/gate, nello stesso ordine). **MINOR** (refactor capability-neutral + nuovo contratto interno di module-loading on-demand; install-contract e invocazione invariati, consumer auto-aggiornati via directory-symlink; nessuna chiave `baldart.config.yml`, nessuna modifica CLI).
+
+> **Why.** Il corpo di una skill vive nel prefisso di sistema: a ogni turno l'harness lo ri-legge dalla cache, quindi un SKILL.md da 61k si paga 362 volte su una run lunga e occupa il tetto-contesto per l'intera durata. Spostare il dettaglio per-fase nella conversazione (via Read on-demand) lo rende **compaction-eligible** (il system prompt non lo è) e fa sì che le card trivial/light non carichino mai i moduli delle fasi che skippano. Caveat onesto: nel caso peggiore (no compaction, ogni fase eseguita una volta) il risparmio è il solo shrink del prefisso (~50k × ogni turno); nel caso tipico è maggiore. La disciplina è preservata da una HARD RULE ("leggi il modulo PRIMA di eseguire la fase") + un campo tracker `phase_module_loaded:` che la § Context recovery ri-legge dopo una compaction. Il Level 2 (card-runner sub-agent per collassare i ~90 turni/card in contesto isolato) resta valutato a parte — i docs ufficiali confermano l'isolamento del contesto subagent, superando la refutazione v4.12.0, ma è fuori da questa release.
+
+### Changed
+
+- **`framework/.claude/skills/new/SKILL.md`** — riscritto come **core ~543 righe / ~10k token** (da 2766 / 61k). Tiene: frontmatter + meta-rules BLOCKING, § Context Tracking (+ nuovo campo `phase_module_loaded:`), § Progress Visibility, § Context economy, **nuova § Routing** (mappa fase→modulo→skip + HARD RULE "Read il modulo prima della fase"), § Parallelism rules, § Context recovery protocol (+ step di ri-Read del modulo post-compaction), § Agent Routing, § QA Profile Selector, § Trivial-card fast-lane, **nuova § Risk-signal detector** (il vecchio Phase 3.7 Step A, rilocato nel core perché usato sia dal Trivial-classifier a Phase 1 sia da Phase 3.7), § Fix Application Log + Domain-Override.
+
+### Added
+
+- **`framework/.claude/skills/new/references/*.md`** (11 moduli on-demand, contenuto verbatim dal SKILL.md originale): `setup.md` (Phase 0 + Pre-flight), `implement.md` (Phase 1-2), `completeness.md` (Phase 2.5/2.5b), `review-cycle.md` (Phase 2.55/2.6/3/3.5), `codex-gate.md` (Phase 3.7, con Step A che ora rimanda al § Risk-signal detector del core), `commit.md` (Phase 4-5), `final-review.md` (Final F.1-F.6), `merge-cleanup.md` (Phase 6/6b/6c), `production-readiness.md` (Phase 7), `team-mode.md` (Team Mode + Step D), `metrics.md` (Phase 8). Arrivano ai consumer (Claude **e** Codex) via il directory-symlink esistente, senza modifiche CLI.
+
+## [4.12.1] - 2026-06-04
+
+**I gate Phase 0 di `/new` (e il finalizer `/mw`) non scattano più sugli artefatti BALDART-managed lasciati dirty da una reinstall/update — `.baldart/generated/`, `.baldart/state.json`, `.baldart/skill-conflicts.json`.** Sintomo riportato dall'utente: *ogni* volta dopo un aggiornamento, `/new` Phase 0 segnalava «stato non pulito» (N file dirty `.baldart/generated` + `state.json`) e «commit ahead di origin», girando all'utente la domanda su come gestire lo stato della main repo. La verifica del sorgente ha confermato la radice: i due gate Phase 0 sapevano auto-ignorare **solo** la telemetria sotto `${paths.metrics}` (dirty-tree gate) e i commit sotto `.framework/` o con subject `baldart update/add` (divergence gate) — ma `baldart update`/`add`/`push` scrivono una **terza** classe di rumore sotto `.baldart/` (i file reali del merge overlay in `generated/`, il ledger `state.json`, il log `skill-conflicts.json`) che nessuno dei due riconosceva, così finiva in `$USER_DIRTY` / `GENUINE_AHEAD` e bloccava. Stessa classe di bug del fix v4.2.2 (telemetria), per gli artefatti `.baldart/` che quel fix non copriva. Cura: **classificazione chirurgica, non rilassamento** — `.baldart/overlays/` resta deliberatamente FUORI dal set ignorato (un overlay editato è lavoro genuino e *deve* gateare). **PATCH** (bugfix di un falso positivo nei gate; nessuna nuova capability, nessuna chiave `baldart.config.yml`).
+
+> **Why.** Un gate di igiene workspace deve distinguere il *lavoro feature in corso* dall'*output del framework stesso*. La v4.2.2 aveva insegnato ai gate a ignorare la telemetria che `/new` scrive di suo; questa fix estende la stessa logica all'output che `baldart update`/`add` lascia dirty per costruzione (rigenera `generated/*` e bumpa `state.json` a ogni sync, committati solo al reconcile successivo). La distinzione critica è `generated|state|skill-conflicts` (framework-managed → ignora) **vs** `overlays/` (user-owned → gatea): un partizionamento di pattern, mai un rilassamento del gate. Verificato con bash reale che le tre forme (porcelain partition, file-list reclassification, `case` glob del finalizer) trattino l'overlay edit come genuino in ogni punto.
+
+### Fixed
+
+- **`framework/.claude/skills/new/SKILL.md`** — Phase 0 step 3 (dirty-tree gate) e Phase 6c step 3 (clean-tree assertion) droppano da `$USER_DIRTY`/`$POST_DIRTY` anche `.baldart/(generated/|state.json|skill-conflicts.json)`; Phase 0 step 4 (divergence reclassification loop) accetta come framework-management i commit che toccano *solo* `.framework/` **e/o** quei `.baldart/` artifacts. Label tracker `framework-telemetry-only` → `framework-managed-only`.
+- **`framework/.claude/skills/worktree-manager/SKILL.md`** — il finalizer `/mw` (sync main repo) classifica gli stessi `.baldart/` artifacts come OWNED (auto-reconcile lossless, come il metrics log) invece che FOREIGN, evitando il falso `[SYNC-NEEDS-DECISION]` che `/new` Phase 6c convertirebbe in un gate utente.
+
 ## [4.12.0] - 2026-06-04
 
 **`/new` non gonfia più il context dell'orchestrator su long-run — il bulk content (log dei gate, `git diff`, file interi, baseline) non scorre più nel canale inline dell'orchestrator: vive su disco e viaggia per *path*.** Sintomo riportato dall'utente: su batch lunghi il consumo si impennava per il context bloat. Una prima ipotesi (i *finding* delle review che tornano inline + un card-runner sub-agent isolato + un "context purge" da rinforzare) è stata **sottoposta a review avversariale e refutata**: (1) l'orchestrator DEVE leggere il contenuto dei finding ai punti-decisione (domain-override partition, AC-Closure, `NEEDS_MANUAL_CONFIRMATION`, merge/dedup del Final gate) → un contratto "verdict-only" che li nasconde romperebbe la skill e i consumer condivisi (`/prd`, `/codexreview`); (2) un card-runner sub-agent non può ospitare i gate utente né garantire il nested-spawn dei reviewer; (3) un "compaction-lossless checkpoint" non regge (`/tmp` è single-point-of-failure, l'auto-compact non è controllabile da una skill). La verifica sul codice ha trovato che **il vero driver del bloat è il bulk content reso inline nei tool-result dell'orchestrator stesso**, non i finding: output dei gate `lint`/`tsc`/`test`/`build` (resi inline da `| tee`, ~40-50%), `git diff` completo passato inline ai simplify agent (~25-30%), Read di file interi nel completeness check, e baseline concatenati nel Final F.3. **MINOR** (cambia il comportamento di esecuzione di `/new`; nessuna nuova capability, nessun nuovo agente, nessuna chiave `baldart.config.yml`, nessun contratto di return degli agent toccato — la schema-propagation rule non si applica).

package/README.md

@@ -339,6 +339,7 @@ your-project/
 │   ├── agents/             # Symlink → .framework/.claude/agents/
 │   ├── commands/           # Symlink → .framework/.claude/commands/
 │   ├── skills/             # Per-item merge dir (v2.1.1+): framework symlinks alongside your own skills
+│   ├── workflows/          # Per-item symlinks of framework dynamic workflows (v4.14.0+, Claude-only)
 │   └── hooks/              # Customizable copies
 ├── baldart.config.yml      # Project context: paths/identity/stack/features (v3.0.0+)
 ├── .baldart/
@@ -427,6 +428,7 @@ Files with symlinks auto-update when framework updates:
 - `agents/`
 - `.claude/agents/`
 - `.claude/commands/`
+- `.claude/workflows/` (v4.14.0+) — framework dynamic workflows, per-item symlinks (Claude-only; no Codex equivalent)
 
 Files managed by the CLI:
 

package/VERSION

@@ -1 +1 @@
-4.12.0
+4.14.0

package/framework/.claude/agents/coder.md

@@ -156,9 +156,9 @@ guard is removed. The canonical regression-test pattern is documented in
 This rule is enforced by:
 - `agents/coding-standards.md § Reference-Aliasing Mutation Patterns` (full
   policy, JSDoc contract, historical incident BUG-0558).
-- `.claude/skills/new/SKILL.md § Phase 2.5 step 5c` (deterministic detector
-  flags un-guarded patterns as `[ALIAS-MUTATION]` in `## Issues & Flags`).
-- `.claude/skills/new/SKILL.md § Phase 3.7 trigger #6` (mutation-after-helper
+- `.claude/skills/new/references/completeness.md § Phase 2.5 step 5c` (deterministic
+  detector flags un-guarded patterns as `[ALIAS-MUTATION]` in `## Issues & Flags`).
+- `.claude/skills/new/references/codex-gate.md § Phase 3.7` (mutation-after-helper
   call invokes per-card `/codexreview` before commit).
 
 ## Database Index Invariant (MUST)