baldart 3.18.1 → 3.21.1

package/CHANGELOG.md

@@ -5,6 +5,198 @@ 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).
 
+## [3.21.1] - 2026-05-26
+
+Fix del Step 0 e Step 1 della skill `/baldart-update` introdotta in v3.21.0. La prima release usava `git -C .framework fetch origin main` per il pre-flight check del numero di commit ahead — pattern **sbagliato** perché `.framework/` è un git subtree all'interno del repo consumer, non un git repo separato: i comandi `git` eseguiti con `-C .framework` ricadono sul `.git` del consumer e fetcherebbero il remote del CONSUMER (es. `github.com/antbald/mayo`), non quello di BALDART. Bug individuato durante test live su `mayo` (l'output mostrava `Da https://github.com/antbald/mayo  * branch  main -> FETCH_HEAD` invece di BALDART).
+
+### Fixed — Pattern git corretto nella skill `/baldart-update`
+
+- **[framework/.claude/skills/baldart-update/SKILL.md](framework/.claude/skills/baldart-update/SKILL.md)**: Step 0 ora delega completamente a `npx baldart version` per ottenere installed version, commit ahead count, e BALDART repo URL — nessuna git operation a mano. Step 1 usa il pattern corretto del CLI (`src/utils/git.js`): `git fetch <BALDART-repo-url> main && git log HEAD..FETCH_HEAD --oneline -- .framework/`, dove l'URL viene estratto dal campo `Repository:` di Step 0. Aggiunta callout box dopo la tabella dei 5 decision point con la regola esplicita: *"do NOT use `git -C .framework fetch`"*, motivazione (`.framework/` è subtree, non repo separato), e pattern corretto.
+
+### Schema change propagation
+
+Nessuna nuova chiave in `baldart.config.yml`. Nessun cambiamento al CLI.
+
+### Versioning rationale
+
+PATCH (3.21.0 → 3.21.1) per la decision tree di [MAINTAINING.md](MAINTAINING.md): bug fix interno alla skill, nessun cambio di behaviour del CLI, nessuna nuova capability, nessun cambio di directory layout o install command.
+
+### Verification (manuale)
+
+Eseguita in `~/mayo`:
+
+1. Test del comando originale ERRATO: `git -C .framework fetch origin main` → l'output mostrava `Da https://github.com/antbald/mayo` (remote di mayo, NOT BALDART) — bug confermato.
+2. Test del pattern CORRETTO: `npx baldart version` espone `Repository: https://github.com/antbald/BALDART`. `git fetch https://github.com/antbald/BALDART.git main && git log HEAD..FETCH_HEAD --oneline -- .framework/` rileva correttamente i commit BALDART ahead del subtree merge nel consumer.
+
+## [3.21.0] - 2026-05-26
+
+Fino a v3.20.x l'aggiornamento di un consumer all'ultima versione del framework passava da due strade: **CLI diretta** (`npx baldart update`, interattivo, con 5 prompt nativi gestiti dall'utente in TTY) oppure **chat ad hoc** (l'utente chiede a Claude di aggiornare, e Claude — senza protocollo standardizzato — improvvisa ogni volta, gestendo gli edge case in modo non riproducibile). La prima opzione è solida ma richiede di lasciare la chat e tornare al terminale; la seconda è comoda ma fragile: silenzia decisioni che il CLI farebbe esplicitamente.
+
+Questa release introduce la skill `/baldart-update` come **wrapper conversazionale agent-driven** di `npx baldart update`, complementare a `/baldart-push`. La skill **replica in chat ognuno dei 5 decision point nativi del CLI** prima di lanciare il comando con `--yes` — non per silenziarli, ma perché ogni prompt è già stato risposto in chat. Il CLI resta source of truth: la skill non re-implementa la logica di `update.js`, la guida e la riporta.
+
+### Added — Skill `/baldart-update`
+
+- **[framework/.claude/skills/baldart-update/SKILL.md](framework/.claude/skills/baldart-update/SKILL.md)**: nuova skill (~220 righe) modellata strutturalmente su [/baldart-push](framework/.claude/skills/baldart-push/SKILL.md) ma con divergenza intenzionale sul modello esecutivo: `/baldart-push` è pure-guidance (l'utente lancia il CLI in TTY), `/baldart-update` è agent-driven con conferme replicate in chat. La skill:
+  - **Pre-flight read-only** (Step 0): legge `.framework/VERSION` e conta i commit ahead con `git -C .framework rev-list HEAD..origin/main --count`. Se 0 → "Already up-to-date", stop senza lanciare il CLI.
+  - **Replica 5 decision point** (Step 1–4) — surface in chat di: preview diff (delta versione + commit message), working tree dirty + stash automatico in ref `baldart-pre-update-<timestamp>`, hooks drift confrontato con `HOOK_REGISTRY` di `.framework/src/utils/hooks.js`, schema config drift confrontato con `.framework/framework/templates/baldart.config.template.yml`, auto-commit classification (BALDART-managed vs user-owned per path-prefix matching su `.framework/`, `.claude/agents/`, `.claude/skills/`, `.claude/commands/`, `AGENTS.md`, `agents/`).
+  - **Run CLI** (Step 5): `Bash` con `timeout: 600000` (10 min — il default 120s è insufficiente per subtree pull + symlink reconcile + post-update wizard + hooks register + auto-commit su repo reali), comando `npx baldart update --yes`. NON passa `--auto-stash` (ridondante con `--yes`, segnalerebbe imprecisione).
+  - **Report** (Step 6): estrae backup tag con `git tag -l 'baldart-pre-update-*' --sort=-creatordate | head -1` (più affidabile del parsing stdout), nuova versione da `cat .framework/VERSION`, e detection stash-pop conflict via grep su stdout/stderr per pattern `CONFLICT` / `stash pop failed` / `unmerged paths`. Fornisce sempre il comando di rollback `git reset --hard <backup-tag>`.
+
+### Bootstrap paradox — esplicitato in cima al SKILL.md
+
+I consumer pre-v3.21.0 incontreranno il paradosso al primo aggiornamento dopo questa release: la skill non è ancora installata, quindi `/baldart-update` non esiste. La skill mette in **box CAPS in prima posizione** l'istruzione di lanciare `npx baldart update` direttamente nel terminale una volta — dopo, `/baldart-update` diventa disponibile per ogni aggiornamento successivo. Non è un edge case nascosto: è il caso primario del rollout, e va trattato come tale.
+
+### Hard rules nella skill
+
+Sette hard rule chiudono i vettori di errore:
+
+1. NEVER re-implementare la logica di `update.js`.
+2. MUST replicare in chat tutti e 5 i decision point prima di passare `--yes`.
+3. MUST passare `timeout: 600000` al Bash.
+4. NEVER passare `--auto-stash`.
+5. MUST riportare il backup tag.
+6. NEVER lanciare update se `.framework/` manca → defer a `npx baldart add`.
+7. NEVER assumere default quando un pre-check fallisce — chiedi all'utente o aborta.
+
+### Schema change propagation
+
+**Nessuna nuova chiave in `baldart.config.yml`** — la skill legge solo `.framework/VERSION`, `.baldart/state.json`, `.claude/settings.json` (file BALDART-owned, non gated da config). La regola di propagazione schema (memoria utente + CLAUDE.md) non si applica a questa release.
+
+### Versioning rationale
+
+MINOR (3.20.0 → 3.21.0) secondo la decision tree di [MAINTAINING.md](MAINTAINING.md):
+- Nuova skill (capability additiva) → MINOR.
+- Nessuna rimozione / cambio directory layout / cambio install command → non MAJOR.
+- Non è un fix doc-only / perf / security senza behaviour change → non PATCH.
+
+### Verification (manuale, no test suite)
+
+Da verificare in un consumer downstream (dopo merge + push + `npx baldart update`):
+
+1. **Discoverability**: dopo l'update, `.claude/skills/baldart-update` esiste come symlink a `.framework/framework/.claude/skills/baldart-update/SKILL.md`. La skill appare nella lista delle skill caricate alla prossima sessione Claude Code.
+2. **Collision test (bootstrap edge case)**: creando `.claude/skills/baldart-update/` user-owned PRIMA dell'update, `SymlinkUtils.mergeSkills` logga in `.baldart/skill-conflicts.json` e NON sovrascrive. La skill ufficiale resta non disponibile — comportamento corretto e documentato.
+3. **Happy path**: in repo allineata, `/baldart-update` risponde "Already up-to-date" via Step 0 (count = 0), senza lanciare il CLI.
+4. **Behind path**: forzato `cd .framework && git reset --hard HEAD~1`, `/baldart-update` rileva 1 commit ahead, replica Step 1–4 in chat, lancia CLI con timeout 600000, riporta backup tag + nuova versione.
+5. **Dirty path**: working tree modificato → Step 2 lista i file e chiede conferma esplicita per lo stash. Se rifiuto → STOP pulito.
+6. **Conflict path**: file modificato sia upstream che locale → CLI esce non-zero, skill riporta verbatim + comando rollback con backup tag.
+
+## [3.20.0] - 2026-05-26
+
+Su `mayo` è stato osservato il seguente comportamento patologico: il modello ha chiamato `Agent({ subagent_type: "code-reviewer" })` e `Agent({ subagent_type: "doc-reviewer" })` (entrambi agent BALDART legittimi e fisicamente presenti su disco), il tool è ritornato `0 tool uses · Done` senza errore visibile, e il modello ha **silenziosamente fatto fallback** su `feature-dev:code-reviewer` + `plan-auditor` — proseguendo come se nulla fosse. Né l'utente né l'agent orchestratore hanno avuto modo di accorgersi che la review codice + doc review obbligatorie non erano state eseguite dagli agent attesi.
+
+Ricerca su issue tracker Anthropic ha confermato due bug Claude Code che si combinano in questo scenario: [#56869](https://github.com/anthropics/claude-code/issues/56869) (sub-agent error non propagato al parent — `0 tool uses · Done` è il sintomo) e [#20931](https://github.com/anthropics/claude-code/issues/20931) (file-based discovery di `.claude/agents/*.md` documentato come BROKEN in certi scenari, anche con file validi). **Nessuno dei due è patchabile lato BALDART** — il framework può solo mitigare con difese stratificate.
+
+Questa release introduce **quattro layer di difesa stratificati** contro la silent-substitution di agent BALDART, senza nuove chiavi in `baldart.config.yml`:
+
+### Added — Hook `agent-discovery-gate` (PreToolUse, bloccante)
+
+- **[framework/.claude/hooks/agent-discovery-gate.js](framework/.claude/hooks/agent-discovery-gate.js)**: nuovo PreToolUse hook con `matcher: 'Agent'` che intercetta ogni invocazione del tool `Agent` (alias `Task`). Estrae `subagent_type` (o `agent_type`) dall'input, lo confronta con la lista degli agent BALDART derivata via `fs.readdirSync` su `.framework/framework/.claude/agents/*.md` (esclusa `REGISTRY.md`). Se il nome è BALDART e il symlink `.claude/agents/<name>.md` del consumer è mancante o rotto (`fs.statSync` segue il link → ENOENT/ELOOP), emette `permissionDecision: "deny"` con reason esplicito che istruisce: *"riavvia la sessione, esegui `npx baldart doctor`, NON sostituire con un altro agent"*. Nomi non-BALDART (built-in `Explore`/`Plan`/`general-purpose`, marketplace `feature-dev:*`/`vercel:*`/`sentry:*`, plugin) passano sempre. Fail-safe contract identico a `framework-edit-gate.js`: ogni try-catch interno esce 0 (allow), mai bloccare per errore proprio.
+
+### Added — Hook `agent-discovery-info` (SessionStart, informativo)
+
+- **[framework/.claude/hooks/agent-discovery-info.sh](framework/.claude/hooks/agent-discovery-info.sh)**: nuovo SessionStart hook bash che enumera gli agent BALDART attesi (stesso `find` su `.framework/framework/.claude/agents/`) e li confronta con `.claude/agents/<name>.md` nel consumer. Quando uno o più sono mancanti, inietta `additionalContext` come **fatto dichiarativo** (best practice anti-prompt-injection da [Claude Code hooks docs](https://code.claude.com/docs/en/hooks)) elencando i nomi non disponibili. Silente quando tutto è OK. **Limite onesto**: il bug Claude Code [#10373](https://github.com/anthropics/claude-code/issues/10373) può saltare l'iniezione su new conversations — in quel caso la difesa scende sul gate bloccante + regola AGENTS.md.
+
+### Added — Regola MUST `framework/AGENTS.md` § 4.a
+
+- **[framework/AGENTS.md](framework/AGENTS.md)**: nuova regola in sezione *Universal MUST*, inserita immediatamente dopo la MUST su `codebase-architect`. Istruisce ogni agent che lavora in un consumer BALDART a **NON fare fallback silenzioso** quando una chiamata `Agent` ritorna `0 tool uses · Done`, va in timeout, o riceve `permissionDecision: deny`. Comportamento richiesto: STOP, replicare verbatim al user il messaggio *"Agent `<name>` non discoverato o fallito in questa sessione — riavvia Claude Code e verifica con `npx baldart doctor`"*, attendere direzione. Nessun auto-routing a `feature-dev:*`/`general-purpose`/altri marketplace. La regola chiude esplicitamente: *"This rule is the ONLY defense against bug #56869, which BALDART cannot patch from outside Claude Code; deviating from it reintroduces the exact failure mode the rule exists to prevent."* È inseparabile dall'hook bloccante — senza la MUST, il `deny` del gate produrrebbe esattamente la silent-substitution che si vuole prevenire.
+
+### Added — `baldart doctor` check integrità symlink agent
+
+- **[src/commands/doctor.js](src/commands/doctor.js)**: aggiunta detection `state.agentSymlinksBroken` nel blocco `detectState` (stesso pattern del check `hooksStatus`, non-blocking probe in `try`/`catch` silenzioso). Enumera `.framework/framework/.claude/agents/*.md`, per ogni nome verifica `fs.statSync('.claude/agents/<name>.md')`, raccoglie i broken. Nuova action `repair-agent-symlinks` con `autoOk: true` che chiama direttamente `new SymlinkUtils().mergeAgents({ tools })` — NON dispatcha `require('./update')` (l'update completo avrebbe side-effect indesiderati: pull, overlay merge, hook register, config drift verify). Tools letti via `loadConfig(cwd).tools.enabled` con fallback `['claude']`.
+
+### Added — Registry idempotente per i due nuovi hook
+
+- **[src/utils/hooks.js](src/utils/hooks.js)**: appese due entry a `HOOK_REGISTRY`: `baldart-agent-discovery-gate` (PreToolUse, matcher `Agent`, order 200 — corre dopo `framework-edit-gate`) e `baldart-agent-discovery-info` (SessionStart, matcher `*`, order 100). Nessuna modifica strutturale al modulo — l'infrastruttura multi-hook esistente (`registerAll`/`getStatus`/`createDriftPrompt`, introdotta in v3.18.0) gestisce automaticamente i due nuovi hook: `baldart add`/`update`/`doctor` li registrano idempotentemente in `.claude/settings.json` del consumer, e `unregisterAll` li rimuove pulitamente. Backfill garantito su consumer pre-3.20.0 via `baldart update`.
+
+### Changed — Nota machine-readability in REGISTRY.md
+
+- **[framework/.claude/agents/REGISTRY.md](framework/.claude/agents/REGISTRY.md)**: nuova nota in cima che dichiara la directory filesystem `framework/.claude/agents/` come fonte di verità machine-readable per i tre nuovi consumatori (gate hook, info hook, doctor). Aggiungere un agent richiede solo `<name>.md` nella directory — nessun manifest JSON da mantenere, nessuna drift da sincronizzare. La tabella Agent Map resta human-readable.
+
+### Limiti dichiarati
+
+Onestà tecnica > marketing: questa release **non risolve** i bug Claude Code che hanno causato il problema su `mayo`, li mitiga.
+
+- **#56869 (silent sub-agent fallback)** non è patchabile dall'esterno di Claude Code. L'unica difesa è la regola MUST in `AGENTS.md` — soft, non meccanicamente bloccante. Il successo dipende dall'aderenza del modello alla regola.
+- **#20931 (file-based discovery broken con file validi)** resta **scoperto dal gate** quando il file esiste e Claude Code lo ignora comunque: il gate vede il file → ritorna allow → la call torna `0 tool uses` (bug originale). In quello scenario worst-case, l'unica difesa attiva è la regola MUST.
+- **#10373 (SessionStart non iniettato)** può saltare il warning informativo su new conversations — accettato come best-effort.
+
+In pratica, il caso comune (symlink rotto / consumer mid-migration) è coperto al 100% dal gate. Il caso patologico (Claude Code ignora silenziosamente un file `.md` valido) è coperto solo dalla regola comportamentale.
+
+### Schema change propagation
+
+- **Nessuna nuova chiave in `baldart.config.yml`** — la lista degli agent vive nel filesystem del payload, gli hook sono auto-registrati via `HOOK_REGISTRY`, il check doctor è always-on quando `state.frameworkPresent`. Schema-change propagation rule non si applica a questa release.
+
+### Versioning rationale
+
+MINOR (3.19.0 → 3.20.0) secondo la decision tree di [MAINTAINING.md](MAINTAINING.md):
+- Due nuovi hook (capability) → MINOR.
+- Nuovo doctor check + nuova action (capability) → MINOR.
+- Nuova MUST in AGENTS.md (regola comportamentale aggiuntiva ma additiva, non rompe install esistenti) → MINOR.
+- Nessuna rimozione / cambio directory layout / cambio install command → non MAJOR.
+
+### Verification (manuale, no test suite)
+
+Eseguita in-place su questa working copy via smoke test del hook standalone (`node framework/.claude/hooks/agent-discovery-gate.js < input`):
+
+1. **Happy path** — input `{ tool_name: 'Agent', tool_input: { subagent_type: 'definitely-not-an-agent' } }`: exit 0, output vuoto. ✓ (nome non in `baldartAgents` → allow).
+2. **Deny path** — input `{ tool_name: 'Agent', tool_input: { subagent_type: 'code-reviewer' }, cwd: '/tmp' }`: exit 0 con stdout JSON `permissionDecision: "deny"` e reason verbose istruttivo. ✓.
+3. **Allow path** — tmpdir con `.claude/agents/code-reviewer.md` simulato + invocation: exit 0, output vuoto. ✓ (symlink healthy → allow).
+4. **Module load** — `node -e "require('./src/utils/hooks.js')"` riporta 3 entries in HOOK_REGISTRY. ✓.
+5. **Doctor module load** — `node -e "require('./src/commands/doctor.js')"` carica senza syntax error. ✓.
+
+Da verificare manualmente in un consumer downstream (dopo merge):
+- `baldart doctor` con un symlink agent volontariamente rotto → propone action `repair-agent-symlinks` con `autoOk: true`, l'esecuzione ripristina il symlink.
+- `baldart update` da consumer pre-3.20.0 → backfilla i due nuovi hook in `.claude/settings.json` senza toccare le entry esistenti.
+- Sessione Claude Code in consumer con symlink rotto → `agent-discovery-info.sh` inietta `additionalContext` al boot; chiamata `Agent` verso quel nome → gate emette deny + il modello (se aderisce alla MUST) replica il messaggio all'utente invece di sostituire.
+
+## [3.19.0] - 2026-05-26
+
+`.baldart/overlays/` smette di essere un percorso "andare al buio". Fino a v3.18.x, un consumer che voleva personalizzare uno skill / agent / command doveva ricordare a memoria tre canali distinti, due modelli di merging (concat per le skill, marker-based per agent/command), il path overlay corretto per ogni canale, lo schema frontmatter (`base_<kind>`, `base_<kind>_version`, `mode`) e la versione framework da targetare — il tutto senza nessun feedback su drift quando il base file cambiava upstream. L'unico touchpoint guida era il messaggio del hook `framework-edit-gate` quando bloccava un edit dentro `.framework/`, che diceva "metti la roba in `.baldart/overlays/<skill>.md`" senza spiegare *quale path esatto*, *quale schema*, *quale versione*. Risultato: overlay scritti raramente o male.
+
+Questa release introduce uno skill `/overlay` + tre nuovi sotto-comandi CLI (`baldart overlay scaffold|validate|drift`) che colmano il gap end-to-end, seguendo il pattern stabilito da `/baldart-push` (skill = guidance, CLI = source of truth). Nessuna nuova chiave in `baldart.config.yml`: gli overlay vivono su path universali che non dipendono dalla configurazione del consumer.
+
+### Added — Skill `/overlay`
+
+- **Nuova skill [framework/.claude/skills/overlay/SKILL.md](framework/.claude/skills/overlay/SKILL.md)**. Thin conversational wrapper attorno al nuovo sotto-comando CLI. Sette fasi: pre-check (`.framework/` esiste?), discovery (skill/agent/command + nome), inspect base + overlay esistente, scaffold via CLI, author body con Edit, validate via CLI, drift maintenance. La skill non re-implementa mai la logica del merger — invoca sempre `npx baldart overlay <sub>`. Quattro hard rules: mai editare `.framework/` direttamente, mai editare file con marker `<!-- baldart-generated: -->`, mai inventare `base_file_sha` o `base_<kind>_version` (computati dalla CLI), mai re-implementare i marker sezionali (vivono in `overlay-merger.js`). Frontmatter porta `contamination_scan: skip` perché contiene esempi illustrativi con token di overlay reali.
+
+### Added — Sotto-comando CLI `baldart overlay {scaffold,validate,drift}`
+
+- **Nuovo file [src/commands/overlay.js](src/commands/overlay.js)** + dispatcher aggiunto in [bin/baldart.js](bin/baldart.js) come gruppo `overlay` (stesso pattern di `routines`). Tre sotto-comandi:
+  - `baldart overlay scaffold <type>/<name> [--mode extend|override]` — idempotente. Valida che il base esista in `.framework/`, computa `base_file_sha` (sha256 12-char) dal contenuto base, legge framework `VERSION`, scrive `.baldart/overlays/<path>` con frontmatter completo e body placeholder appropriato al kind (concat per skill, marker-based per agent/command). Refuse pulito se l'overlay esiste già — punta l'utente a `drift` o all'Edit diretto.
+  - `baldart overlay validate <path>` — dry-run del merger. Per agent/command invoca `mergeOverlay()` e riporta numero linee generate + warning (es. heading non matchato nel base, che diventa nuova sezione in coda). Per skill valida frontmatter YAML + esistenza base. Confronta `base_file_sha` overlay vs SHA attuale e segnala se il base è cambiato.
+  - `baldart overlay drift [<path>] [--all]` — drift report cross-overlay. SHA-based quando `base_file_sha` è presente nel frontmatter, version-based fallback altrimenti. Stampa summary `{clean, drifted, unknown}` su tutti gli overlay sotto `.baldart/overlays/` (root + `agents/` + `commands/`). Skip `*.example.md` e `README.md`.
+- **Pre-check fail-safe**: ogni sotto-comando rifiuta con messaggio chiaro quando `.framework/` non esiste (consumer non installato). Non assume mai stato.
+
+### Changed — `overlay-merger.js` arricchito (additivo, retro-compat)
+
+- **[src/utils/overlay-merger.js](src/utils/overlay-merger.js)**: nuova funzione esportata `computeBaseFileSha(content): string` (12-char sha256 prefix) usata dal CLI scaffolder per scrivere `base_file_sha` nel frontmatter overlay. Il marker `<!-- baldart-generated: -->` ora include opzionalmente `base_sha=<sha>` come campo aggiuntivo; `readMarker()` lo legge se presente, altrimenti ritorna `null` per quel campo (retro-compatibile con file generati pre-v3.19.0). Il merger continua a produrre output bit-identico nei casi senza `base_file_sha` nel overlay frontmatter — l'arricchimento è opt-in via lo scaffolder.
+- **YAML SHA quote**: il scaffolder quota il sha (`base_file_sha: "fd940fcc1786"`) perché un 12-char hex può essere tutto-digit, che YAML interpreterebbe come numero (`0` per `000000000000`). `parseFrontmatter()` lato CLI coerce sempre a string per difensività.
+
+### Changed — Hook `framework-edit-gate` con handoff `/overlay`
+
+- **[framework/.claude/hooks/framework-edit-gate.js](framework/.claude/hooks/framework-edit-gate.js)**: due piccoli edit testuali (logica del hook intatta). Nel messaggio "(B) Project-specific opinion" e nel messaggio "Cannot edit BALDART-generated file" la guida ora suggerisce di invocare `/overlay` per scaffolding guidato + drift check. La consistenza è garantita perché skill, CLI e hook vengono distribuiti insieme dal `baldart update`.
+
+### Schema change propagation
+
+- **Nessuna nuova chiave in `baldart.config.yml`** — gli overlay vivono su path universali (`.framework/`, `.baldart/overlays/`) non parametrizzati. La regola di propagazione schema (template + configure prompt + update detector + doctor) NON si applica a questa release.
+- **Schema change additivo nel frontmatter overlay**: nuovo campo opzionale `base_file_sha`. Retro-compatibile — overlay scritti pre-v3.19.0 senza questo campo restano validi; `drift` li classifica come "unknown" (drift detection by version only) invece di errori. Documentato in `framework/templates/overlays/README.md` come campo opzionale via il body placeholder dello scaffolder.
+
+### Versioning rationale
+
+MINOR (3.18.1 → 3.19.0): added capability (nuova skill + nuovi sotto-comandi CLI). No breaking change: nessuna API esistente modificata semanticamente; `readMarker()` resta backward-compatible; il merger produce lo stesso output per ogni input pre-esistente. Decision tree CLAUDE.md: "Added an agent / command / skill / routine / template → MINOR" qualifica.
+
+### Verification (manuale, no test suite)
+
+Tested in sandbox `/tmp/overlay-test` con symlink `.framework/ → /Users/antoniobaldassarre/BALDART` per simulare un consumer:
+
+1. `baldart overlay scaffold agents/coder` → overlay creato a `.baldart/overlays/agents/coder.md` con frontmatter completo (`base_agent: coder`, `base_agent_version: 3.19.0`, `base_file_sha: "<sha>"`, `mode: extend`).
+2. `baldart overlay validate .baldart/overlays/agents/coder.md` → dry-run del merger, "Overlay valid (agent, marker model), 350 lines generated".
+3. `baldart overlay drift --all` → cross-overlay drift report, summary corretto.
+4. Drift positivo: alterazione manuale di `base_file_sha` nel frontmatter → `drift` segnala "drifted (sha mismatch)".
+5. Scaffold idempotente: re-run con overlay esistente → "Overlay already exists, run drift to check it".
+6. Skill scaffolding: `baldart overlay scaffold bug` → overlay skill creato a `.baldart/overlays/bug.md` con `base_skill: bug`, body concat-friendly.
+7. Pre-check: `baldart overlay scaffold ...` in dir senza `.framework/` → exit 1 con messaggio chiaro.
+
 ## [3.18.1] - 2026-05-25
 
 Chiusura del debito tecnico introdotto da v3.18.0. Il release v3.18.0 ha annunciato che `/design-review` supporta un programmatic JSON output mode invocabile da `/e2e-review` per gating uniforme — ma l'implementazione era una sola nota nel frontmatter ("se invocato con `mode: programmatic` ritorna JSON") senza body command che la concretizzasse, senza schema vincolato, senza mode-detection deterministica, senza taxonomy mapping tra le severity Markdown (Blockers/High/Medium/Nitpicks) e le severity programmatic (critical/major/minor) del `visual-fidelity-verifier`. Il risultato: una feature half-implemented, parsable only in teoria. Questo PATCH la rende reale.

package/README.md

@@ -208,7 +208,7 @@ Skills always-ask when required keys are missing — never silently default.
 never overwrites your file. Full guide:
 [`framework/docs/PROJECT-CONFIGURATION.md`](framework/docs/PROJECT-CONFIGURATION.md).
 
-### Skills (25 portable skills)
+### Skills (29 portable skills)
 
 Skills live under `.claude/skills/` and are auto-discovered by Claude Code.
 Bundled skills:
@@ -219,6 +219,7 @@ Bundled skills:
 - **Product**: `seo-audit`, `copywriting`, `api-design-principles`
 - **Knowledge**: `doc-writing-for-rag`, `capture` (LLM wiki overlay)
 - **Integration**: `kie-ai`, `remotion-best-practices`
+- **Framework**: `baldart-push` (upstream contribution), `baldart-update` (v3.21.0 — agent-driven framework update), `overlay` (v3.19.0 — guided overlay author)
 
 ### Registry-First UI Protocol (new in v3.11.0)
 

package/VERSION

@@ -1 +1 @@
-3.18.1
+3.21.1

package/bin/baldart.js

@@ -115,6 +115,36 @@ program
     await doctorCommand({ auto: !!options.auto, offline: !!options.offline });
   });
 
+const overlayGroup = program
+  .command('overlay')
+  .description('Author and check .baldart/overlays/ — scaffolds, validates, and detects drift on skill/agent/command overlays');
+
+overlayGroup
+  .command('scaffold <target>')
+  .description('Create a new overlay file (e.g. `scaffold agents/coder`, `scaffold bug`)')
+  .option('--mode <mode>', 'Overlay mode: extend (default) or override (skill-only)', 'extend')
+  .action(async (target, options) => {
+    const overlay = require('../src/commands/overlay');
+    await overlay.scaffold(target, options);
+  });
+
+overlayGroup
+  .command('validate <path>')
+  .description('Dry-run the merger on an overlay and report any errors / warnings')
+  .action(async (overlayPath) => {
+    const overlay = require('../src/commands/overlay');
+    await overlay.validate(overlayPath);
+  });
+
+overlayGroup
+  .command('drift [path]')
+  .description('Check whether the base file changed since an overlay was authored. Without `path`, checks all overlays.')
+  .option('--all', 'Check every overlay under .baldart/overlays/ (default when no path is given)')
+  .action(async (overlayPath, options) => {
+    const overlay = require('../src/commands/overlay');
+    await overlay.drift(overlayPath, options);
+  });
+
 const routinesGroup = program
   .command('routines')
   .description('Manage scheduled routines (wiki-review, doc-review, code-review, skill-improve, ds-drift, full-sweep)');

package/framework/.claude/agents/REGISTRY.md

@@ -4,6 +4,8 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 
 **Location**: `.claude/agents/<name>.md` | **Invoke via**: `Task` tool with `subagent_type="<name>"`
 
+> **Machine-readable source of truth (since v3.20.0)**: the filesystem directory `framework/.claude/agents/` is authoritative for the list of BALDART agents. The `agent-discovery-gate.js` PreToolUse hook, the `agent-discovery-info.sh` SessionStart hook, and `baldart doctor` enumerate the directory directly (every `<name>.md` except this file is an agent — no manifest JSON is shipped). Adding a new agent means dropping `<name>.md` here; no other touchpoint.
+
 ## Agent Map
 
 | Agent | Category | When to Use | Specialization | Can Edit Code | Key Tools |

package/framework/.claude/hooks/agent-discovery-gate.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * agent-discovery-gate — Claude Code PreToolUse hook (tool: Agent).
+ *
+ * Intercepts `Agent` tool calls and denies the call when the requested
+ * `subagent_type` / `agent_type` matches the name of a BALDART agent but
+ * the corresponding `.claude/agents/<name>.md` file is missing or its
+ * symlink is broken on the consumer's filesystem.
+ *
+ * Background: Claude Code has two known bugs that combine into a silent
+ * failure mode for sub-agent invocations —
+ *   #56869 — sub-agent returning internal error silently hangs parent
+ *            (no error propagation, parent sees `0 tool uses · Done`)
+ *   #20931 — file-based discovery of `.claude/agents/*.md` is documented
+ *            as BROKEN in some scenarios (files ignored at session start)
+ *
+ * This hook covers the filesystem-detectable subset of the problem
+ * (missing/broken symlinks). The model-side defense (the MUST rule in
+ * `framework/AGENTS.md`) covers the rest. The two are inseparable:
+ * without the MUST rule, a `permissionDecision: deny` from this hook
+ * would likely be worked around by the model trying a different
+ * `subagent_type` — the very failure mode this hook exists to prevent.
+ *
+ * Source of truth for the list of BALDART agents: the filesystem
+ * directory next to this file (`.framework/framework/.claude/agents/`).
+ * Every `<name>.md` (except `REGISTRY.md`) is a BALDART agent. No
+ * separate manifest is shipped — the directory IS the manifest.
+ *
+ * Fail-safe contract: this hook MUST NOT block legitimate work. If
+ * anything unexpected happens (missing directory, parse error, IO
+ * error), it exits 0 and lets the tool call through. We optimise for
+ * false negatives over false blocks — the gate is a safety net, not a
+ * tribunal.
+ *
+ * Registration: see src/utils/hooks.js — `baldart add` and `baldart
+ * update` auto-register this hook in the consumer's
+ * `.claude/settings.json`.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function safeExit() {
+  process.exit(0);
+}
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch (_) {
+    return '';
+  }
+}
+
+function parseInput(raw) {
+  if (!raw) return null;
+  try { return JSON.parse(raw); } catch (_) { return null; }
+}
+
+function loadBaldartAgents() {
+  // `__dirname` resolves to .framework/framework/.claude/hooks/.
+  // The agent files live alongside, in ../agents/.
+  const agentsDir = path.join(__dirname, '..', 'agents');
+  try {
+    if (!fs.existsSync(agentsDir)) return null;
+    const names = fs.readdirSync(agentsDir)
+      .filter((f) => f.endsWith('.md') && f !== 'REGISTRY.md')
+      .map((f) => f.replace(/\.md$/, ''));
+    return new Set(names);
+  } catch (_) {
+    return null;
+  }
+}
+
+function isConsumerSymlinkHealthy(consumerCwd, agentName) {
+  // fs.statSync follows symlinks; ENOENT/ELOOP/EACCES → broken / missing.
+  const target = path.join(consumerCwd, '.claude', 'agents', `${agentName}.md`);
+  try {
+    fs.statSync(target);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function denyReason(agentName, consumerCwd) {
+  const targetPath = path.join('.claude', 'agents', `${agentName}.md`);
+  return [
+    `agent-discovery-gate: BALDART agent \`${agentName}\` is not available on this`,
+    `consumer's filesystem (\`${targetPath}\` is missing or its symlink is broken).`,
+    ``,
+    `This is a recoverable state, not a transient one — calling this agent`,
+    `again will keep failing until the symlink is restored.`,
+    ``,
+    `Fix:`,
+    `  1. Run \`npx baldart doctor\` — it will detect and repair the broken`,
+    `     agent symlink(s) using SymlinkUtils.mergeAgents.`,
+    `  2. Restart this Claude Code session so the discovery index is rebuilt.`,
+    ``,
+    `IMPORTANT — for the agent that received this denial:`,
+    `Do NOT silently fall back to a different \`subagent_type\` (e.g.`,
+    `\`feature-dev:*\`, \`general-purpose\`, or another BALDART agent). The`,
+    `AGENTS.md MUST rule explicitly forbids this — substitution masks the`,
+    `failure that this gate exists to surface. Instead, stop and report this`,
+    `message verbatim to the user, then wait for direction.`,
+    ``,
+    `(Consumer cwd: ${consumerCwd})`,
+  ].join('\n');
+}
+
+function emitDeny(reason) {
+  try {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    }));
+  } catch (_) {
+    // Fallback to legacy mode: exit code 2 + stderr.
+    process.stderr.write(reason + '\n');
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
+function main() {
+  const raw = readStdin();
+  const input = parseInput(raw);
+  if (!input) safeExit();
+
+  // Defensive: hook is registered with matcher 'Agent', but in case Claude
+  // Code routes other tools through us, only proceed for the Agent tool.
+  if (input.tool_name !== 'Agent') safeExit();
+
+  const toolInput = input.tool_input || {};
+  // Claude Code's hook docs name the field `agent_type`; the public SDK
+  // exposes it as `subagent_type`. Accept either for forward/backward
+  // robustness — whichever is present wins.
+  const requested = String(
+    toolInput.agent_type || toolInput.subagent_type || ''
+  ).trim();
+  if (!requested) safeExit();
+
+  const baldartAgents = loadBaldartAgents();
+  if (!baldartAgents || baldartAgents.size === 0) safeExit();
+
+  // Only gate names that BALDART claims as its own. Built-in agents
+  // (Explore, Plan, general-purpose), marketplace agents (feature-dev:*,
+  // vercel:*, sentry:*), and plugin-provided agents are unaffected.
+  if (!baldartAgents.has(requested)) safeExit();
+
+  // Consumer cwd comes from Claude Code's input envelope; fall back to
+  // process.cwd() for robustness.
+  const consumerCwd = (typeof input.cwd === 'string' && input.cwd)
+    ? input.cwd
+    : process.cwd();
+
+  if (isConsumerSymlinkHealthy(consumerCwd, requested)) safeExit();
+
+  emitDeny(denyReason(requested, consumerCwd));
+}
+
+try { main(); } catch (_) { safeExit(); }

package/framework/.claude/hooks/agent-discovery-info.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+#
+# agent-discovery-info.sh — BALDART SessionStart hook (informational).
+#
+# Runs at session start (and on /clear, /compact, URL resume). Compares the
+# set of BALDART agents shipped under .framework/framework/.claude/agents/
+# against the per-name symlinks the consumer should have under
+# .claude/agents/, and — when one or more are missing — injects an
+# `additionalContext` warning so the model can see, at the very top of the
+# session, which agent names will be unavailable.
+#
+# Why injection instead of blocking: SessionStart hooks have no decision
+# control (per Claude Code docs), they can only inject context. The
+# blocking counterpart is `agent-discovery-gate.js` (PreToolUse on the
+# Agent tool). These two hooks complement each other:
+#   - This hook (C′) raises early awareness so the model never tries to
+#     call a missing agent in the first place.
+#   - The gate (B′) is the hard wall when a call slips through anyway.
+#
+# Known limitation: there's a Claude Code bug (#10373) where SessionStart
+# hook output is not injected on new conversations under certain
+# conditions. When that happens, the defense falls back to B′ + the
+# AGENTS.md MUST rule. We accept this — the hook is a best-effort
+# augmentation, not the primary line of defense.
+#
+# Anti-prompt-injection note: per Claude Code docs, SessionStart context
+# is most reliable when phrased as factual statements ("The following
+# agents are missing: …") rather than imperative system instructions.
+# We follow that convention below.
+#
+# Exit: always 0 (Stop/SessionStart hooks should never bubble errors out
+# to the user; failure isolation is a matter of hygiene).
+
+set -u
+exec 2>/dev/null  # silence stderr; we are not user-visible
+
+# --- read envelope --------------------------------------------------------
+
+INPUT=""
+if [ ! -t 0 ]; then
+  INPUT="$(cat)"
+fi
+
+get_field() {
+  local field="$1"
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$INPUT" | jq -r ".$field // empty" 2>/dev/null
+  else
+    printf '%s' "$INPUT" | sed -n "s/.*\"$field\"[[:space:]]*:[[:space:]]*\"\\([^\"]*\\)\".*/\\1/p" | head -1
+  fi
+}
+
+CWD_FROM_ENV="$(get_field cwd)"
+CWD="${CWD_FROM_ENV:-$PWD}"
+
+cd "$CWD" 2>/dev/null || exit 0
+
+# --- locate the framework agent directory --------------------------------
+
+FRAMEWORK_AGENTS_DIR=".framework/framework/.claude/agents"
+CONSUMER_AGENTS_DIR=".claude/agents"
+
+[ -d "$FRAMEWORK_AGENTS_DIR" ] || exit 0  # consumer not installed — silent.
+
+# --- compute missing set --------------------------------------------------
+
+MISSING=""
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  name="$(basename "$f" .md)"
+  [ "$name" = "REGISTRY" ] && continue
+  target="$CONSUMER_AGENTS_DIR/${name}.md"
+  # `test -e` returns false for broken symlinks too — exactly what we want.
+  if [ ! -e "$target" ]; then
+    if [ -z "$MISSING" ]; then
+      MISSING="$name"
+    else
+      MISSING="$MISSING, $name"
+    fi
+  fi
+done < <(find "$FRAMEWORK_AGENTS_DIR" -maxdepth 1 -type f -name '*.md' 2>/dev/null | sort)
+
+# Nothing missing — exit silently. No noise when everything is healthy.
+[ -z "$MISSING" ] && exit 0
+
+# --- emit additionalContext ----------------------------------------------
+
+# Build the JSON string with awk-based escaping (no jq required).
+escape_json() {
+  printf '%s' "$1" | awk 'BEGIN{ORS=""} {gsub(/\\/,"\\\\"); gsub(/"/,"\\\""); gsub(/\r/,""); gsub(/\n/,"\\n"); print}'
+}
+
+MSG="BALDART expects the following sub-agents to be reachable via the Agent tool in this session, but their backing files are missing from .claude/agents/: ${MISSING}. Calling Agent with one of these subagent_type values will be denied by the agent-discovery-gate PreToolUse hook. Run \`npx baldart doctor\` to repair, then restart this session."
+
+cat <<JSON
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "$(escape_json "$MSG")"
+  }
+}
+JSON
+
+exit 0

package/framework/.claude/hooks/framework-edit-gate.js

@@ -133,6 +133,9 @@ function blockReason(realPath, decisions, blockings) {
     `    → Do not write to \`.framework/\`. Instead write to:`,
     `      .baldart/overlays/<skill-name>.md`,
     `    This file is consumer-owned, never pushed upstream.`,
+    `    → Tip: invoke \`/overlay\` for a guided scaffolding flow (correct`,
+    `      frontmatter, base_file_sha, drift check). See also`,
+    `      \`npx baldart overlay scaffold <type>/<name>\`.`,
     ``,
     `(C) Legitimate illustrative example (e.g. docs that quote the canonical`,
     `    paths as examples — \`PROJECT-CONFIGURATION.md\`, \`project-context.md\`)`,
@@ -177,7 +180,8 @@ function main() {
             `This file is auto-generated by \`npx baldart update\` from a base ` +
             `framework file plus an overlay. Manual edits will be overwritten.\n\n` +
             `To customise: edit the corresponding overlay under .baldart/overlays/` +
-            `(or create it if absent), then re-run \`npx baldart update\`.`;
+            `(or create it if absent), then re-run \`npx baldart update\`.\n` +
+            `→ Or invoke \`/overlay\` for a guided flow.`;
           try {
             process.stdout.write(JSON.stringify({
               hookSpecificOutput: {