baldart 4.11.0 → 4.13.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).
 
+## [4.13.0] - 2026-06-04
+
+**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).
+
+> **Why.** L'orchestrator di `/new` è un unico contesto long-lived su tutto il batch: ogni byte che rende inline (Bash tool-result, prompt che compone, file che Read-a) resta in finestra per l'intero run, e nessun "purge" via prompt recupera token. La fix attacca la radice — **tenere il bulk fuori dal canale inline** — senza toccare ciò che l'orchestrator può leggere ai punti-decisione (i finding restano file-resident e leggibili on-demand). Onestà sui limiti: questo riduce il *rate di accumulo* (stima ~40-50% sul footprint dominante), non azzera la crescita del context; il bound vero richiederebbe isolamento per-card a livello di harness, fuori dalla portata di una skill.
+
+### Changed
+
+- **`framework/.claude/skills/new/SKILL.md`** — nuova sezione SSOT **`## Context economy (MANDATORY)`** (HARD RULE in 5 punti: gate-output discipline, diff-to-disk, findings file-resident, pass-paths-not-concatenations, targeted Reads). Applicata ai siti che la violavano:
+  - **Gate bash (Phase 2 step 8)** — `cmd 2>&1 | tee /tmp/x.txt` → `cmd > /tmp/x.txt 2>&1; echo "<gate>:$?"`: l'output completo resta su disco, inline solo l'exit code; su fallimento si legge un estratto *bounded* (`tail -n 30`), mai il log intero. Step 9 passa al fix agent il **path** del log, non il blob.
+  - **Tutti i re-run di gate foreground** (gap-fix Phase 2.5, Phase 2.55 step 5, Phase 3 step 16, pre-commit Phase 4, Final F.5, team D.1/D.3b) — pointer alla disciplina (redirect a disco, mai inline).
+  - **`git diff` (Phase 2.55 step 2-3)** — `git diff > /tmp/diff-<CARD>.txt`; i 3 simplify agent ricevono il **path** e leggono il diff da soli, niente «full diff» nei prompt. Team D.3b allineato.
+  - **Blocchi Codex (Phase 0 cross-card audit, Final F.3)** — `2>&1 | tee "$FILE"` → `> "$FILE" 2>&1` (niente copia inline; il file si riempie comunque in streaming per il polling F.4, commento aggiornato).
+  - **Final F.3 baseline** — `${ARCH_BASELINE}` (contenuti concatenati) → `${ARCH_BASELINE_PATHS}` (lista di path che Codex Read-a on-demand); F.2 non concatena più i per-card baseline.
+  - **Completeness check (Phase 2.5 step 4)** — Read *mirati* (grep con `offset`/`limit` stretti attorno al `file:line` del completion report) invece di Read di file interi.
+  - **Progress Bar** — blocco markdown completo solo alle boundary pesanti (card/wave/gate-decision/STOP); il movimento di fase intra-card si mostra via Task spine sub-state, non ri-emettendo la tabella a ogni fase.
+  - **Phase 5 step 31** — il "CONTEXT PURGE" è ri-etichettato come *reference-hygiene* (non token-reclamation, che un prompt non può ottenere); il leverage reale è upstream (la § Context economy tiene il bulk fuori dal context fin dall'inizio).
+
 ## [4.11.0] - 2026-06-04
 
 **Gli overlay non costringono più a riconciliare a ogni `baldart update` — la VERSION non è più incisa nell'identità dei file generati né usata come segnale di drift quando il base file non è cambiato.** Sintomo riportato dall'utente: ogni update richiedeva una riconciliazione. La verifica del sorgente ha trovato **due trigger indipendenti con la stessa radice** — la VERSION del framework veniva trattata come parte dell'identità di overlay/file-generati, ma viene bumpata a *ogni* release a prescindere dal fatto che lo specifico base file sia cambiato. **(A) churn dei file agent/command generati:** `buildMarker()` stampava `base_version=<VERSION>` nel commento `<!-- baldart-generated -->`; a ogni update la VERSION cambiava → la riga del marker cambiava anche su contenuto byte-identico → git vedeva un diff → scattava il commit `post-update reconcile` *a ogni update*. Il campo era puramente informativo (`readMarker` lo leggeva ma nessuno gate-ava la rigenerazione su di esso). **(B) falso-drift degli skill overlay:** `doctor` e `status` confrontavano il pin `base_skill_version` *direttamente* con la VERSION installata (ignorando `base_file_sha`), così ogni bump faceva apparire ogni overlay come "drifted" anche con base SKILL.md identico — mentre `overlay drift` lo faceva già correttamente SHA-first. **MINOR** (cambia il formato del marker generato; nessuna chiave `baldart.config.yml` — la fix riusa `base_file_sha` già presente).

package/VERSION

@@ -1 +1 @@
-4.11.0
+4.13.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)