baldart 3.18.0 → 3.19.0

package/CHANGELOG.md

@@ -5,6 +5,79 @@ 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.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.
+
+L'adversarial review del piano v3.19.0 (multi-viewport + interactive states + Phase 4b design judgment pass) ha esplicitamente identificato il problema: "`/design-review` programmatic JSON è vaporware in v3.18.0 — va prima implementato bene come release a sé". Questa release fa esattamente quello, separando la chiusura del debito dall'aggiunta di nuove feature, in modo che v3.19.0 (quando arriverà, post-dogfooding) possa appoggiarsi a un contratto programmatic stabile invece di costruirsi sopra una stub.
+
+### Fixed — `/design-review` dual-mode reale (Markdown ↔ JSON)
+
+- **[framework/.claude/commands/design-review.md](framework/.claude/commands/design-review.md) riscritto** (frontmatter invariato, body completamente sostituito). Quattro sezioni nuove + workflow rivisto:
+  - **§ Invocation Modes**: documenta esplicitamente Mode A (interactive, Markdown — il comportamento storico) e Mode B (programmatic, JSON-only — il nuovo contratto). L'envelope JSON di input per Mode B è specificato verbatim: `{mode, card_id, route, viewport, dev_server_port, registry_paths: {index, tokens, components_dir}, ui_guidelines_path, features: {has_design_system, multi_tenant_theming}, tolerance}`. Il comando lo riceve passato dall'orchestratore `/e2e-review` quando Phase 4b sarà introdotta.
+  - **§ Programmatic output schema**: schema JSON di output vincolato, allineato verbatim a `framework/.claude/agents/visual-fidelity-verifier.md` § "Output Schema" per uniformità di parsing nell'aggregatore orchestratore. Campo `source: "design-review"` distingue le finding di questo command da quelle del verifier in modalità debug; i campi `findings[].severity`/`category`/`description`/`expected`/`actual`/`fix_hint`/`evidence`/`ds_drift_code`/`confidence` sono shape-identici. La deduplicazione cross-source avviene per `(route, category, ds_drift_code)` con precedenza al verifier quando duplicate (più strutturato).
+  - **§ Severity normalization (Markdown ↔ programmatic)**: tabella di mapping deterministica Blocker → `critical`, High → `major`, Medium → `minor`, Nitpick → DROP. Il drop dei Nitpick in modalità programmatic è deliberato (troppo noise per gating; restano nel report Markdown per uso interattivo).
+  - **§ Programmatic-mode category taxonomy**: enumera le 10 categorie ammesse in Mode B (`primitive-reinvented`, `primitive-missing-spec`, `token-bypass`, `component-stale`, `index-drift`, `authority-violation`, `brand-voice-drift`, `a11y-contrast`, `a11y-focus-visible`, `interactive-state-missing`) — sottoinsieme della tassonomia canonica del verifier adattato allo scope di design judgment di questo command. Categorie non in lista vanno emesse come stringhe libere in `gaps[]`, MAI come nuove categorie inventate (l'orchestratore non sa pesarle).
+  - **§ Workflow (both modes)**: passi 0–5 unificati per Mode A e Mode B, con la divergenza solo nel formato di output finale (passi 4 e 5). Mode B usa `dev_server_port` dall'envelope per costruire URL, salva screenshot in `/tmp/design-review/<route-slug>.png` per cross-reference dall'orchestratore.
+  - **§ Mode-detection contract**: regola deterministica anti-ambiguità — Mode B è triggered SOLO se l'input contiene la substring esatta `"mode": "programmatic"` (con quote, come appare nell'envelope JSON). Vietato auto-detection da contesto invocazione ("sto girando dentro a una skill") — produce silent Markdown leakage nel parser dell'orchestratore che rompe il gate. Su envelope malformato emette `{status: "error", source: "design-review", reason: "malformed_input_envelope", findings: []}` invece di fallback a Mode A (il fallback silenzioso bloccherebbe la card invece di segnalare).
+
+### Notes
+
+- **Nessun cambio framework payload oltre al command.** Nessun nuovo agente, nessuna nuova skill, nessuna nuova chiave config, nessuna modifica a `/new` o `/e2e-review`. Solo il command `/design-review` viene reso effettivamente dual-mode come annunciato in v3.18.0. `/e2e-review` non lo invoca ancora — quella connessione (Phase 4b) viene rimandata a una future release post-dogfooding, sulla base di dati reali su quanto valore aggiunge la judgment pass sopra il `visual-fidelity-verifier`.
+- **Backward compatibility totale per uso interattivo**: utenti che invocano `/design-review /merchant/dashboard` continuano a ricevere il Markdown report identico a v3.17.x e prima. Mode A è il default; Mode B è opt-in via envelope JSON esplicito.
+- **Severity taxonomy in lockstep**: il body del command include una nota esplicita "quando aggiorni la taxonomy qui, aggiorna in lockstep `framework/.claude/agents/visual-fidelity-verifier.md` § Severity Taxonomy". Le due fonti restano allineate per evitare drift cross-source nell'aggregatore.
+- **Versioning rationale.** PATCH (3.18.0 → 3.18.1): no new capability. Il contratto Mode B era già annunciato in v3.18.0; questa release rende l'annuncio reale. Decision tree CLAUDE.md: "Doc fix, script bugfix, perf, security patch with no behaviour change → PATCH" — qualifica perché la behavior change è solo per chi sta ancora costruendo l'integrazione (nessun consumer esistente la invoca programmatically oggi).
+- **Verification** (manuale, no test suite): (1) `/design-review /merchant/dashboard` interattivo → Markdown identico al pre-3.18.1 (regression check Mode A); (2) input contenente `"mode": "programmatic"` → JSON-only output, no preamble, parsable da `JSON.parse()`; (3) envelope malformato → emette `{status: "error", reason: "malformed_input_envelope"}` senza fallback a Markdown; (4) campi `route`/`dev_server_port` mancanti dall'envelope → stesso errore; (5) finding di severity Nitpick → presente in Mode A, assente da Mode B `findings[]`.
+- **Path post-3.18.1**: dogfooding di v3.18.0 + 3.18.1 per 1–2 settimane su feature UI reali. Sulla base di falsi positivi/negativi raccolti, decidere data-driven quali estensioni includere in v3.19.0 tra: multi-viewport (mobile/desktop/tablet), interactive states (hover/focus/active/disabled + opt-in loading/empty/error), Phase 4b design judgment pass che invoca `/design-review` in Mode B all'interno di `/e2e-review`. L'adversarial review ha esplicitamente sconsigliato il bundle v3.19.0 senza dati di dogfooding — questa release rispetta quella raccomandazione.
+
 ## [3.18.0] - 2026-05-25
 
 The end-to-end review fase post-implementazione diventa un **gate deterministico e BLOCKING** invece di un assortimento di check advisory. Until v3.17.x, la chiusura di una card via `/new` attraversava tre fasi eterogenee tutte non-bloccanti sul fronte UI: Phase 2.5 (Implementation Completeness Check) validava solo card AC / PRD alignment / code quality / schema / artifacts senza alcun gate visivo o funzionale runtime; Phase 2.6 (E2E Testing) era *condizionale* (solo con `test_plan.e2e_required: true` o QA profile BALANCED/DEEP) e invocava `qa-sentinel` che per charter (`qa-sentinel.md:151-161`) esegue solo gate meccanici (lint/type/test/build/audit) — non test browser-based né design; Phase 2.7 (Visual Design Review) invocava `ui-expert` ma era esplicitamente marcata "advisory, non-blocking" (`new/SKILL.md:897` — "findings logged but do NOT block commit"). Le skill `webapp-testing` e `playwright-skill` esistevano ma non erano mai auto-invocate da `/new`. La routine `ds-drift` (`framework/routines/ds-drift.routine.yml`) girava settimanalmente, catturando il drift visivo 1–7 giorni dopo il merge. **Conseguenza concreta** lamentata dall'utente: doveva rifare manualmente la review schermata-per-schermata di ogni card UI, e i dettagli grafici dei mockup venivano regolarmente ignorati.

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 (28 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), `overlay` (v3.19.0 — guided overlay author)
 
 ### Registry-First UI Protocol (new in v3.11.0)
 

package/VERSION

@@ -1 +1 @@
-3.18.0
+3.19.0

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/commands/design-review.md

@@ -2,19 +2,140 @@
 description: Trigger the design-review subagent with MCP Playwright for the specified route.
 allowed-tools: Bash, Grep, LS, Read, WebFetch, TodoWrite, WebSearch, BashOutput, KillBash, ListMcpResourcesTool, ReadMcpResourceTool, mcp__playwright__browser_navigate, mcp__playwright__browser_click, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_console_messages
 ---
-> **Invocation mode** — When invoked **interactively** by the user, produce the Markdown report described below (Blockers/High/Medium/Nitpicks). When invoked **programmatically** by the `/e2e-review` skill (input includes `"mode": "programmatic"`), return a single JSON object matching the `visual-fidelity-verifier` output schema (`framework/.claude/agents/visual-fidelity-verifier.md` § "Output Schema") so the orchestrator can parse it for gating. No prose preamble in programmatic mode.
 
-You are the design-review subagent. Ensure `npm run design-review` is running before continuing so Playwright MCP can expose `localhost:9221` to Claude. When the user invokes `/design-review`, do the following:
+You are the design-review subagent. Ensure `npm run design-review` is running before continuing so Playwright MCP can expose `localhost:9221` to Claude.
+
+## Invocation Modes (since v3.18.1)
+
+This command supports two output modes, detected from the input prompt:
+
+### Mode A — Interactive (default)
+
+When the user invokes `/design-review` directly (input is a natural-language route reference, e.g. `/design-review /merchant/dashboard`), produce the **Markdown report** described in steps 1–5 below. Use the Blockers/High/Medium/Nitpicks template from `agents/design-review.md` § Report Template.
+
+### Mode B — Programmatic (invoked by `/e2e-review`)
+
+When the input contains a JSON envelope with `"mode": "programmatic"` at any position (typical payload from `/e2e-review` Phase 4b), switch to **JSON-only output**. No prose preamble, no Markdown, no closing remarks — a single JSON object as the final message, parseable by `JSON.parse()` on the orchestrator side.
+
+**Programmatic input envelope** (passed verbatim by `/e2e-review`):
+
+```json
+{
+  "mode": "programmatic",
+  "card_id": "FEAT-XXXX",
+  "route": "/merchant/dashboard",
+  "viewport": { "width": 1440, "height": 900 },
+  "dev_server_port": 3000,
+  "registry_paths": {
+    "index": "docs/design-system/INDEX.md",
+    "tokens": "docs/design-system/tokens-reference.md",
+    "components_dir": "docs/design-system/components"
+  },
+  "ui_guidelines_path": "docs/references/ui-guidelines.md",
+  "features": {
+    "has_design_system": true,
+    "multi_tenant_theming": false
+  },
+  "tolerance": "strict"
+}
+```
+
+**Programmatic output schema** (MUST match this shape verbatim — `/e2e-review` Phase 5 aggregates this output alongside `visual-fidelity-verifier` findings, deduplicating by `(route, category, ds_drift_code)`):
+
+```json
+{
+  "status": "completed" | "skipped" | "error",
+  "source": "design-review",
+  "route": "/merchant/dashboard",
+  "viewport": { "width": 1440, "height": 900 },
+  "findings": [
+    {
+      "severity": "critical" | "major" | "minor",
+      "category": "<category from taxonomy below>",
+      "description": "One-sentence description of what the design-review observed.",
+      "expected": "Brief reference to the design intent (token name, spec excerpt, guideline section).",
+      "actual": "Brief reference to what the rendered output shows.",
+      "fix_hint": "Actionable single-line hint. Never 'make it look right'.",
+      "evidence": {
+        "selector": "[data-testid='...']" | "css-selector",
+        "screenshot_path": "/tmp/design-review/<route-slug>.png"
+      },
+      "ds_drift_code": "DS_INDEX_DRIFT" | "DS_COMPONENT_STALE" | "DS_TOKENS_DRIFT" | null,
+      "confidence": "high" | "medium" | "low"
+    }
+  ],
+  "ds_drift_codes": ["DS_INDEX_DRIFT", "DS_TOKENS_DRIFT"],
+  "gaps": [
+    "Could not find registry spec for primitive `Badge` — flagged as DS_INDEX_DRIFT instead of comparing against spec."
+  ]
+}
+```
+
+#### Severity normalization (Markdown ↔ programmatic)
+
+The interactive Markdown report uses Blockers/High/Medium/Nitpicks. In programmatic mode, normalize as follows for cross-source aggregation with `visual-fidelity-verifier`:
+
+| Markdown tier | Programmatic `severity` | Notes |
+|---|---|---|
+| Blocker | `critical` | Layout broken, primary CTA unreachable, accessibility blocker, security exposure |
+| High | `major` | Token bypass, reinvented primitive, spec divergence on visible prop, contrast failure |
+| Medium | `minor` | Stale spec doc, cosmetic spacing drift, micro-misalignments |
+| Nitpick | DROP | Do not emit in programmatic output — too noisy for gating |
+
+#### Programmatic-mode category taxonomy
+
+Use these categories (subset of the canonical taxonomy in `framework/.claude/agents/visual-fidelity-verifier.md` § "Severity Taxonomy", adapted for the design-judgment scope of this command). The orchestrator deduplicates findings across sources by `(route, category)`, so categories MUST match the canonical names verbatim:
+
+- `primitive-reinvented` (Major) — reimplements a primitive that already exists in `INDEX.md`
+- `primitive-missing-spec` (Major) — new primitive shipped without `components/<Name>.md`
+- `token-bypass` (Major) — hardcoded color/spacing/shadow/radius where a token exists
+- `component-stale` (Minor) — `components/<Name>.md` out of sync with the implemented primitive
+- `index-drift` (Minor) — primitive used but missing from `INDEX.md`
+- `authority-violation` (Major) — local override of a registry-authoritative decision (per Authority Matrix)
+- `brand-voice-drift` (Minor) — microcopy/UI language drift from `${paths.ui_guidelines}` brand voice
+- `a11y-contrast` (Major) — body text < 4.5:1 or focus indicator < 3:1
+- `a11y-focus-visible` (Major) — interactive element with no equivalent focus indicator
+- `interactive-state-missing` (Major) — hover/focus/active visually identical to idle on interactive primitive
+
+When a finding does not match any of these categories, drop it from programmatic output rather than inventing a new category — the orchestrator's aggregator does not know how to weigh unknown categories. Surface it in the `gaps[]` array as a free-text note instead.
+
+---
+
+## Workflow (both modes)
+
+When the user invokes `/design-review`, do the following (in both modes — only the final output format differs):
 
 0. **BLOCKING when `features.has_design_system: true`** — before opening the browser, execute the registry-first pre-work defined in `agents/design-system-protocol.md`:
    - Read `${paths.design_system}/INDEX.md` and the Authority Matrix for the surface under review.
    - Read `${paths.design_system}/tokens-reference.md`.
    - Read `${paths.design_system}/components/<Name>.md` for every primitive expected on the route.
-   When the flag is `false`, skip the registry reads but flag the gap in the final report and recommend `/design-system-init`.
-1. Start with the route or component specified (e.g., `/merchant/dashboard`) and open it in the MCP browser.
+   When the flag is `false`, skip the registry reads. In Mode A flag the gap in the final report and recommend `/design-system-init`. In Mode B add the gap to the `gaps[]` array of the JSON output.
+1. Start with the route or component specified (e.g., `/merchant/dashboard`) and open it in the MCP browser. In Mode B, use the `dev_server_port` from the input envelope to construct `http://localhost:<port><route>`.
 2. Follow the Quick Visual Check in `agents/design-review.md` and run Phases 0‑7 (interaction, responsiveness, polish, accessibility, robustness, code health, content/console).
-3. Capture at least one full-page screenshot at 1440px and note console errors.
-4. Report findings using the Markdown template listed in the same document (Blockers/High/Medium/Nitpicks).
-5. **Include a `Design-System Conformance` section in the report** — primitives reused, primitives reinvented (HIGH), tokens bypassed (HIGH), spec drift (MEDIUM), new primitives proposed. Template in `agents/design-review.md` § Report Template.
+3. Capture at least one full-page screenshot at the viewport from the input (default 1440px) and note console errors. In Mode B save the screenshot at `/tmp/design-review/<route-slug>.png` and cite it in `evidence.screenshot_path`.
+4. **Mode A**: report findings using the Markdown template in `agents/design-review.md` (Blockers/High/Medium/Nitpicks). **Mode B**: assemble the JSON output described above, normalizing severity per the table.
+5. **Design-System Conformance section** — primitives reused, primitives reinvented (HIGH→major), tokens bypassed (HIGH→major), spec drift (MEDIUM→minor), new primitives proposed.
+   - **Mode A**: include as a top-level section in the Markdown report per `agents/design-review.md` § Report Template.
+   - **Mode B**: emit as `findings[]` entries with the appropriate categories from the taxonomy above, and populate `ds_drift_codes[]` with the deduplicated set.
+
+## Mode-detection contract (avoid silent misdetection)
+
+The dual-mode design is deterministic only if the trigger is unambiguous. Apply these rules in order:
+
+1. If the input prompt contains the exact substring `"mode": "programmatic"` (with quotes, as it appears in the JSON envelope) → **Mode B**, JSON only.
+2. Else if the input is a route path or natural-language reference → **Mode A**, Markdown.
+3. **Never auto-detect from invocation context** (e.g., "I'm running inside a skill") — that is unreliable and produces silent Markdown leakage into the orchestrator's JSON parser, which breaks the gate.
+
+In Mode B, if the JSON envelope is malformed (cannot be parsed) or required fields (`route`, `dev_server_port`) are missing, emit:
+
+```json
+{ "status": "error", "source": "design-review", "reason": "malformed_input_envelope", "findings": [] }
+```
+
+Do not fall back to Mode A on input-envelope error — the orchestrator expects JSON and will fail the parse on Markdown, blocking the card silently.
+
+## Notes
 
-Document any blocking issues, regression risks, or accessibility gaps in the final response.
+- Document any blocking issues, regression risks, or accessibility gaps in the final response (Mode A) or `findings[]` array (Mode B).
+- Mode B is consumed by `/e2e-review` Phase 4b (when implemented in a future release) as the "design judgment pass" alongside the `visual-fidelity-verifier` agent's pixel-fidelity pass. The two are complementary: the verifier sees only the screenshot vs mockup; this command additionally reasons over the registry + Authority Matrix + brand voice.
+- The output schema is kept aligned with `framework/.claude/agents/visual-fidelity-verifier.md` § "Output Schema" so the orchestrator can use a single parser for both sources. When updating the taxonomy here, update the verifier's taxonomy in lockstep.

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: {

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

@@ -0,0 +1,214 @@
+---
+name: overlay
+description: "Guided author of .baldart/overlays/ — the per-project customisation layer for BALDART skills, agents, and commands. Use when the user says /overlay, 'customizza skill', 'modifica agente upstream', 'personalizza comando', 'crea overlay', 'extend skill X', 'override agent Y', 'overlay drift', or when the framework-edit-gate hook blocked an edit and pointed here. The skill walks the user through choosing the right canal (skill / agent / command), scaffolds the overlay with correct frontmatter and section markers via `npx baldart overlay scaffold`, validates the merge via `npx baldart overlay validate`, and surfaces drift via `npx baldart overlay drift`. Never edits `.framework/` directly and never re-implements the merger logic — the CLI is the source of truth."
+contamination_scan: skip
+---
+
+# /overlay — Customise the framework, the right way
+
+Author an overlay under `.baldart/overlays/` for a BALDART skill, agent, or command, instead of editing `.framework/` (which gets overwritten on `baldart update` and blocked by the contamination scanner).
+
+## Execution model
+
+This skill is a **thin guidance wrapper** around `npx baldart overlay`. The CLI is non-interactive (no prompts), so the skill can invoke it via the Bash tool. The CLI is the source of truth for:
+
+- Path conventions (`.baldart/overlays/<name>.md` for skills, `.baldart/overlays/agents/<name>.md`, `.baldart/overlays/commands/<name>.md`).
+- Frontmatter schema (`base_<kind>`, `base_<kind>_version`, `base_file_sha`, `mode`).
+- Merger validation (uses `src/utils/overlay-merger.js` internally).
+- Drift detection (SHA-based when `base_file_sha` is present, version-based fallback).
+
+The skill MUST NOT re-implement any of the above. If you find yourself writing path logic or YAML manipulation, stop — invoke the CLI.
+
+## When to use
+
+- The user invokes `/overlay`.
+- The user says "customizza skill X", "personalizza il command Y", "modifica l'agente Z per questo progetto".
+- The user wants a project-specific opinion to apply (brand voice, debug entry point, stack mandate, custom workflow) without contaminating the framework upstream.
+- The user follows the handoff from the `framework-edit-gate` hook message ("invoke /overlay for a guided flow").
+- The user asks "is my overlay still in sync with the framework?" or "drift overlay".
+
+## When NOT to use
+
+- The improvement is **generic** (useful for all consumers). Send it upstream via `/baldart-push` instead.
+- The user wants to install / update the framework itself (use `npx baldart` / `update`).
+- The user wants to author a brand-new skill that has no base in the framework — they create it directly under `.claude/skills/<name>/`. Overlays are for *modifying* a framework primitive, not for net-new ones.
+- The user wants to modify a **hook** under `.claude/hooks/`. Hooks are installed as **plain copies** (consumer-owned, no auto-update) — they do not fit the overlay model. The consumer edits them directly in their repo. If the change should benefit every consumer, edit the `.template` file under `.framework/.claude/hooks/` and push upstream via `/baldart-push`. Overlay scope is limited to skills, agents, and commands.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** none (overlay paths are universal).
+**Gated by features:** none.
+**Overlay:** this skill has no overlay (it would be paradoxical).
+**On missing/empty keys:** not applicable.
+
+## Hard rules
+
+1. **NEVER edit files under `.framework/` directly.** The contamination scanner will block the edit, and even if it didn't, `baldart update` would overwrite the change.
+2. **NEVER edit a file with the marker `<!-- baldart-generated:` on line 1.** It is auto-regenerated from base + overlay. The hook blocks this. Edit the overlay instead.
+3. **NEVER fabricate `base_<kind>_version` or `base_file_sha`.** Both are computed by the CLI at scaffold time. The skill never writes these by hand.
+4. **NEVER write to `.baldart/overlays/` with the Edit/Write tools to *create* a new overlay.** Use `npx baldart overlay scaffold` so the frontmatter is correct. Editing the *body* of an already-scaffolded overlay with Edit/Write is fine.
+5. **NEVER re-implement the section-merge logic** (`[OVERRIDE]/[APPEND]/[PREPEND]`). The merger in `overlay-merger.js` is the only place it lives.
+6. **When the user's intent is clearly generic** ("we should add a Quality bar step to every coder workflow"), redirect them to `/baldart-push` instead of scaffolding an overlay.
+
+## Workflow
+
+### Step 0 — Pre-check
+
+Before anything, confirm this is a consumer repo:
+
+```
+[ -d .framework ] && echo OK
+```
+
+If not OK, stop and say: "This repo is not a BALDART consumer. Run `npx baldart` to install the framework first."
+
+Also confirm the overlays directory exists (it should, after `configure`):
+
+```
+[ -d .baldart/overlays ] || mkdir -p .baldart/overlays
+```
+
+### Step 1 — Discovery
+
+Ask the user:
+
+1. **What do they want to customise?** A skill, an agent, or a command?
+   - **Skill**: shapes how a `/-command` workflow behaves (e.g. `/bug`, `/capture`, `/new`). Base lives at `.framework/framework/.claude/skills/<name>/SKILL.md`. Overlay is concat'd at runtime by the agent — section markers are textual conventions, not parsed.
+   - **Agent**: shapes how a specialised subagent reasons (e.g. `coder`, `code-reviewer`, `qa-sentinel`). Base lives at `.framework/framework/.claude/agents/<name>.md`. Overlay is merged section-by-section via markers, producing a generated file at `.claude/agents/<name>.md`.
+   - **Command**: shapes a top-level slash command (e.g. `/codexreview`, `/check`). Base lives at `.framework/framework/.claude/commands/<name>.md`. Same marker-based merge as agents.
+
+2. **Which one?** List the available bases for the chosen kind:
+
+   ```bash
+   # for skills
+   ls .framework/framework/.claude/skills/
+   # for agents
+   ls .framework/framework/.claude/agents/
+   # for commands
+   ls .framework/framework/.claude/commands/
+   ```
+
+3. **What intent?**
+   - `extend` (default) — add to / tweak parts of the base.
+   - `override` (skills only) — replace the entire base skill with the overlay content. Rare; use only when the base does not fit your project at all.
+
+### Step 2 — Inspect base + existing overlay
+
+Read the base file with the Read tool. Show the user the H2 section list (`grep '^## ' <base-file>`). This is what they can target with `[OVERRIDE]/[APPEND]/[PREPEND]` (for agent/command) or as textual landmarks (for skill).
+
+If `.baldart/overlays/<path>` already exists:
+
+- Show its current frontmatter and section list.
+- Run drift check: `npx baldart overlay drift .baldart/overlays/<path>`.
+- Switch to "extend existing" mode: the skill will guide the user to add / modify sections by **editing the file directly** (Edit tool), not by re-scaffolding.
+
+### Step 3 — Scaffold (new overlays only)
+
+Invoke the CLI:
+
+```bash
+npx baldart overlay scaffold <kind>/<name> [--mode override]
+```
+
+Where `<kind>` is `skill`, `agents`, or `commands` (plural for agent/command to match the overlay subdir convention). Examples:
+
+- `npx baldart overlay scaffold agents/coder`
+- `npx baldart overlay scaffold commands/codexreview`
+- `npx baldart overlay scaffold bug` (no slash → skill)
+- `npx baldart overlay scaffold skill/bug --mode override`
+
+The CLI:
+- Validates that the base exists in `.framework/`.
+- Computes `base_file_sha` (sha256, 12 chars) from the base content.
+- Reads framework `VERSION`.
+- Writes `.baldart/overlays/<path>` with the correct frontmatter and a placeholder body.
+
+If the overlay already exists, the CLI refuses (idempotent). Use Step 4 to extend it instead.
+
+### Step 4 — Author the body
+
+Open the scaffolded file with the Read tool, show the user the placeholder content, and ask what they want to put there. Use the Edit tool to insert their content. Examples of what each marker does:
+
+**For agent / command overlays:**
+
+```markdown
+## [APPEND] Quality bar
+
+- Before closing any task, run `npm run test:e2e -- --grep <feature>`.
+- Attach the Playwright screenshot to the commit body.
+
+## [OVERRIDE] When to escalate
+
+In this project, escalate to the human owner before touching `prisma/schema.prisma`.
+
+## Project-only conventions
+
+(New section, appended at the end of the merged file.)
+- All API calls go through `src/lib/api-client.ts`.
+```
+
+**For skill overlays** (concat model — markers are textual conventions only):
+
+```markdown
+## [APPEND] Project-specific guidance
+
+In this project, debug entry points are in `apps/web/`. Always start
+Playwright in headed mode for visual bugs.
+```
+
+Reference examples already shipped with the framework:
+- `.framework/framework/templates/overlays/ui-design.fidelity-example.md` (skill, fidelity-app brand voice)
+- `.framework/framework/templates/overlays/copywriting.fidelity-example.md` (skill, 4-pillar brand voice)
+- `.framework/framework/templates/overlays/agents/coder.example.md` (agent, marker-based)
+- `.framework/framework/templates/overlays/commands/codexreview.example.md` (command, marker-based)
+
+### Step 5 — Validate
+
+Run:
+
+```bash
+npx baldart overlay validate <path>
+```
+
+The CLI dry-runs the merger and reports:
+- Frontmatter parse status.
+- For agent/command: number of lines generated, any warnings (e.g. an overlay section whose heading does not match any base H2 — it will be appended as a new section, which may be intentional).
+- Whether the base file changed since the overlay was authored (SHA comparison).
+
+If `validate` reports errors, fix them with Edit and re-run. If it reports warnings about non-matching headings, decide with the user whether that is intentional (new custom section) or a typo to correct.
+
+### Step 6 — Apply
+
+- **For skills**: nothing to do. The overlay is loaded at runtime by Claude when the user invokes a `/-command` that uses the skill.
+- **For agents / commands**: run `npx baldart update` to regenerate the file in `.claude/<kind>s/<name>.md` from base + overlay. The regenerated file carries the `<!-- baldart-generated: -->` marker on line 1 — do not edit it manually (the `framework-edit-gate` hook will block, anyway).
+
+### Step 7 — Drift maintenance (periodic)
+
+When the user updates the framework (`npx baldart update` bumps `VERSION`), the base files for their overlays may have changed. Tell them how to audit:
+
+```bash
+npx baldart overlay drift --all
+```
+
+For each drifted overlay, the user should:
+1. Open the base file: `.framework/framework/.claude/<path>`.
+2. Read the diff against what they expected (use `git -C .framework log -p -- framework/.claude/<path>` to see the upstream changes).
+3. If the overlay still makes sense, refresh the `base_file_sha` by re-running scaffold (after backing up the overlay body) — or simply update `base_file_sha` by hand once they have confirmed the overlay still applies cleanly.
+4. If the overlay no longer makes sense, edit it to align with the new base.
+
+## Failure modes & remediation
+
+| Symptom | Likely cause | Remediation |
+|---|---|---|
+| `scaffold` says "already exists" | Overlay was authored previously | Edit the existing file directly. Run `overlay drift` first to check. |
+| `validate` says "frontmatter mismatch" | `base_<kind>: <name>` does not match the overlay's filename | Either fix the frontmatter or rename the file. The two MUST agree. |
+| `validate` warning "overlay section has no matching H2 in base" | The user used `[OVERRIDE]` / `[APPEND]` / `[PREPEND]` with a heading that does not exist in the base file | Either fix the heading to match an existing base H2, or drop the marker (the section will become a new custom section appended at the end). |
+| `drift` says "drift unknown" | Overlay was authored before `base_file_sha` existed (pre-v3.19.0) | Re-run `scaffold` on a temp path to capture the current SHA, then merge that into the overlay frontmatter manually. Or just accept the version-based fallback. |
+| Hook blocked an edit to a generated file | The user tried to edit `.claude/agents/<x>.md` directly, which is BALDART-managed | Edit the overlay at `.baldart/overlays/agents/<x>.md` instead. The hook message already says this. |
+
+## Reference
+
+- `framework/agents/project-context.md` § 5 — overlay protocol.
+- `framework/templates/overlays/README.md` — conventions and pointer to example overlays.
+- `src/utils/overlay-merger.js` — merger implementation (read-only; do not duplicate in the skill).
+- `src/commands/overlay.js` — CLI implementation (skill calls this via Bash).

package/framework/templates/overlays/README.md

@@ -22,10 +22,23 @@ Every overlay file has YAML frontmatter:
 ---
 base_skill: <skill-name>          # MUST match the skill directory name
 base_skill_version: <semver>      # framework version when authored
+base_file_sha: "<12-char-sha>"    # optional (v3.19.0+) — base file content sha for accurate drift detection
 mode: extend | override           # default: extend
 ---
 ```
 
+For agent overlays use `base_agent` / `base_agent_version`, and for command
+overlays `base_command` / `base_command_version`.
+
+The optional `base_file_sha` (v3.19.0+) records the sha256 prefix (12 chars)
+of the base file at the moment the overlay was scaffolded. When present,
+`npx baldart overlay drift` uses it to detect base-file changes precisely
+instead of falling back to a version-string compare. The value MUST be
+quoted because an all-digit hex like `000000000000` would otherwise be
+parsed as a number by YAML. The `npx baldart overlay scaffold` CLI writes
+this field automatically; hand-written overlays may omit it (drift detection
+silently degrades to the version-only fallback — no error).
+
 Sections marked `## [OVERRIDE] <topic>` replace the same `<topic>` from the
 base skill. Everything else extends the base.
 

package/package.json

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

package/src/commands/overlay.js

@@ -0,0 +1,381 @@
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const UI = require('../utils/ui');
+const { mergeOverlay, computeBaseFileSha } = require('../utils/overlay-merger');
+
+const FRAMEWORK_DIR = '.framework';
+const FRAMEWORK_PAYLOAD = path.join(FRAMEWORK_DIR, 'framework');
+const OVERLAYS_DIR = path.join('.baldart', 'overlays');
+
+const KINDS = ['skill', 'agent', 'command'];
+
+function frameworkRoot(cwd) {
+  return path.join(cwd, FRAMEWORK_DIR);
+}
+
+function ensureConsumer(cwd) {
+  if (!fs.existsSync(frameworkRoot(cwd))) {
+    UI.error('Not a BALDART consumer repo — `.framework/` not found.');
+    UI.info('Run `npx baldart` to install the framework first.');
+    process.exit(1);
+  }
+}
+
+function readFrameworkVersion(cwd) {
+  try {
+    return fs.readFileSync(path.join(cwd, FRAMEWORK_DIR, 'VERSION'), 'utf8').trim();
+  } catch (_) {
+    return null;
+  }
+}
+
+function baseFilePathFor(cwd, kind, name) {
+  if (kind === 'skill') {
+    return path.join(cwd, FRAMEWORK_PAYLOAD, '.claude', 'skills', name, 'SKILL.md');
+  }
+  return path.join(cwd, FRAMEWORK_PAYLOAD, '.claude', `${kind}s`, `${name}.md`);
+}
+
+function overlayPathFor(cwd, kind, name) {
+  if (kind === 'skill') return path.join(cwd, OVERLAYS_DIR, `${name}.md`);
+  return path.join(cwd, OVERLAYS_DIR, `${kind}s`, `${name}.md`);
+}
+
+function parseTarget(target) {
+  // Accept "agents/coder", "commands/codexreview", "skill/bug", or bare name
+  // (skill assumed). Always normalise to { kind: 'agent'|'command'|'skill', name }.
+  if (!target || typeof target !== 'string') return null;
+  if (target.includes('/')) {
+    const [head, ...rest] = target.split('/');
+    const name = rest.join('/');
+    if (!name) return null;
+    if (head === 'skill' || head === 'skills') return { kind: 'skill', name };
+    if (head === 'agent' || head === 'agents') return { kind: 'agent', name };
+    if (head === 'command' || head === 'commands') return { kind: 'command', name };
+    return null;
+  }
+  return { kind: 'skill', name: target };
+}
+
+function parseFrontmatter(content) {
+  const m = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return { fm: {}, found: false };
+  try {
+    const fm = yaml.load(m[1]) || {};
+    // Coerce `base_file_sha` to string — a 12-char hex SHA may be all digits,
+    // which YAML would otherwise parse as a number (0 → falsy → false drift).
+    if (fm.base_file_sha != null) fm.base_file_sha = String(fm.base_file_sha);
+    return { fm, found: true };
+  } catch (_) {
+    return { fm: {}, found: true, malformed: true };
+  }
+}
+
+function scaffoldBody(kind, name) {
+  if (kind === 'skill') {
+    return [
+      '',
+      `> Skill overlays are concatenated to the base SKILL.md at runtime by the Claude`,
+      `> agent. The merger does NOT parse [OVERRIDE]/[APPEND]/[PREPEND] markers here —`,
+      `> they are textual conventions for the agent. Use \`mode: override\` in`,
+      `> frontmatter to replace the base skill entirely.`,
+      '',
+      `## [APPEND] Project-specific guidance`,
+      '',
+      `<!-- Add the rules / vocabulary / opinions that apply to THIS project. -->`,
+      '',
+    ].join('\n');
+  }
+  return [
+    '',
+    `> Section markers (parsed by overlay-merger.js):`,
+    `>   ## [OVERRIDE] <H2> — replace base section verbatim`,
+    `>   ## [APPEND]   <H2> — add overlay content after base section`,
+    `>   ## [PREPEND]  <H2> — add overlay content before base section`,
+    `>   ## <H2>            — appended as a new section at the end`,
+    '',
+    `## [APPEND] <heading from base ${kind} "${name}">`,
+    '',
+    `<!-- Replace the heading above with one that exists in the base file. -->`,
+    '',
+  ].join('\n');
+}
+
+function buildFrontmatter({ kind, name, frameworkVersion, baseSha, mode }) {
+  const lines = ['---'];
+  lines.push(`base_${kind}: ${name}`);
+  lines.push(`base_${kind}_version: ${frameworkVersion || 'unknown'}`);
+  // Quote the SHA — a 12-char hex string can be all digits, which YAML would
+  // otherwise parse as a number (0 → falsy → false-negative in drift check).
+  if (baseSha) lines.push(`base_file_sha: "${baseSha}"`);
+  lines.push(`mode: ${mode || 'extend'}`);
+  lines.push('---');
+  return lines.join('\n') + '\n';
+}
+
+// ─── scaffold ──────────────────────────────────────────────────────────────
+
+async function scaffold(target, options = {}) {
+  const cwd = process.cwd();
+  ensureConsumer(cwd);
+
+  const parsed = parseTarget(target);
+  if (!parsed) {
+    UI.error('Invalid target. Use: skill/<name>, agents/<name>, or commands/<name>.');
+    UI.info('Example: npx baldart overlay scaffold agents/coder');
+    process.exit(1);
+  }
+  const { kind, name } = parsed;
+
+  const baseAbs = baseFilePathFor(cwd, kind, name);
+  if (!fs.existsSync(baseAbs)) {
+    UI.error(`Base ${kind} "${name}" not found at ${path.relative(cwd, baseAbs)}.`);
+    UI.info(`Run \`ls ${path.relative(cwd, path.dirname(baseAbs))}\` to list available ${kind}s.`);
+    process.exit(1);
+  }
+
+  const overlayAbs = overlayPathFor(cwd, kind, name);
+  const overlayRel = path.relative(cwd, overlayAbs);
+
+  if (fs.existsSync(overlayAbs)) {
+    UI.warning(`Overlay already exists: ${overlayRel}`);
+    UI.info('Run `npx baldart overlay drift ' + overlayRel + '` to check it, or edit it directly to extend.');
+    process.exit(0);
+  }
+
+  fs.mkdirSync(path.dirname(overlayAbs), { recursive: true });
+
+  const baseContent = fs.readFileSync(baseAbs, 'utf8');
+  const baseSha = computeBaseFileSha(baseContent);
+  const fwVersion = readFrameworkVersion(cwd);
+  const mode = (options.mode || 'extend').trim();
+  if (!['extend', 'override'].includes(mode)) {
+    UI.error(`Invalid --mode "${mode}". Use "extend" or "override".`);
+    process.exit(1);
+  }
+
+  const content =
+    buildFrontmatter({ kind, name, frameworkVersion: fwVersion, baseSha, mode }) +
+    scaffoldBody(kind, name);
+
+  fs.writeFileSync(overlayAbs, content);
+  UI.success(`Created ${overlayRel}`);
+  UI.info(`Base file: ${path.relative(cwd, baseAbs)}`);
+  UI.info(`Targets framework v${fwVersion || 'unknown'} (base_file_sha=${baseSha}).`);
+  UI.newline();
+  UI.list([
+    `Edit ${overlayRel} to add your customisations.`,
+    `Validate the merge with: npx baldart overlay validate ${overlayRel}`,
+    kind === 'skill'
+      ? `Run any /-command that uses this skill to see the overlay applied at runtime.`
+      : `Apply with: npx baldart update (regenerates .claude/${kind}s/${name}.md from base + overlay).`,
+  ]);
+}
+
+// ─── validate ──────────────────────────────────────────────────────────────
+
+function deriveTargetFromOverlayPath(cwd, overlayPath) {
+  const abs = path.isAbsolute(overlayPath) ? overlayPath : path.join(cwd, overlayPath);
+  const root = path.join(cwd, OVERLAYS_DIR);
+  const rel = path.relative(root, abs);
+  if (rel.startsWith('..')) return null;
+  const parts = rel.split(path.sep);
+  if (parts.length === 1) {
+    return { kind: 'skill', name: parts[0].replace(/\.md$/, ''), abs };
+  }
+  if (parts.length === 2) {
+    const sub = parts[0];
+    if (sub === 'agents') return { kind: 'agent', name: parts[1].replace(/\.md$/, ''), abs };
+    if (sub === 'commands') return { kind: 'command', name: parts[1].replace(/\.md$/, ''), abs };
+  }
+  return null;
+}
+
+async function validate(overlayPath) {
+  const cwd = process.cwd();
+  ensureConsumer(cwd);
+
+  if (!overlayPath) {
+    UI.error('Usage: npx baldart overlay validate <path>');
+    UI.info('Example: npx baldart overlay validate .baldart/overlays/agents/coder.md');
+    process.exit(1);
+  }
+
+  const t = deriveTargetFromOverlayPath(cwd, overlayPath);
+  if (!t) {
+    UI.error(`Path is not under ${OVERLAYS_DIR}/ or has unexpected shape: ${overlayPath}`);
+    process.exit(1);
+  }
+  if (!fs.existsSync(t.abs)) {
+    UI.error(`Overlay file not found: ${path.relative(cwd, t.abs)}`);
+    process.exit(1);
+  }
+
+  const overlayContent = fs.readFileSync(t.abs, 'utf8');
+  const { fm, found, malformed } = parseFrontmatter(overlayContent);
+  if (!found) {
+    UI.error('Overlay has no YAML frontmatter.');
+    process.exit(1);
+  }
+  if (malformed) {
+    UI.error('Overlay frontmatter is not valid YAML.');
+    process.exit(1);
+  }
+  const expectedKindField = `base_${t.kind}`;
+  if (fm[expectedKindField] !== t.name) {
+    UI.error(`Frontmatter mismatch: expected ${expectedKindField}: ${t.name} (got ${fm[expectedKindField] || 'missing'}).`);
+    process.exit(1);
+  }
+
+  const baseAbs = baseFilePathFor(cwd, t.kind, t.name);
+  if (!fs.existsSync(baseAbs)) {
+    UI.error(`Base ${t.kind} "${t.name}" not found at ${path.relative(cwd, baseAbs)}.`);
+    process.exit(1);
+  }
+
+  if (t.kind === 'skill') {
+    UI.success(`Overlay valid (skill, concat model).`);
+    UI.info(`Targets v${fm.base_skill_version || 'unknown'}, mode=${fm.mode || 'extend'}.`);
+    if (fm.base_file_sha) {
+      const currentSha = computeBaseFileSha(fs.readFileSync(baseAbs, 'utf8'));
+      if (currentSha !== fm.base_file_sha) {
+        UI.warning(`Base file changed since overlay was authored (sha ${fm.base_file_sha} → ${currentSha}). Review for drift.`);
+      } else {
+        UI.success('Base file unchanged since overlay was authored.');
+      }
+    } else {
+      UI.info('No base_file_sha in frontmatter — drift check by version only.');
+    }
+    return;
+  }
+
+  // Agent/command — dry-run the merger.
+  const baseContent = fs.readFileSync(baseAbs, 'utf8');
+  const fwVersion = readFrameworkVersion(cwd);
+  let result;
+  try {
+    result = mergeOverlay({
+      kind: t.kind,
+      name: t.name,
+      baseContent,
+      overlayContent,
+      frameworkVersion: fwVersion
+    });
+  } catch (err) {
+    UI.error(`Merger threw: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (result.warnings && result.warnings.length) {
+    result.warnings.forEach((w) => UI.warning(w));
+  }
+  UI.success(`Overlay valid (${t.kind}, marker model).`);
+  UI.info(`Targets v${result.baseVersionTargeted}, mode=${result.overlayMode}.`);
+  UI.info(`Generated output: ${result.generated.split('\n').length} lines.`);
+  if (fm.base_file_sha) {
+    const currentSha = computeBaseFileSha(baseContent);
+    if (currentSha !== fm.base_file_sha) {
+      UI.warning(`Base file changed since overlay was authored (sha ${fm.base_file_sha} → ${currentSha}). Review for drift.`);
+    } else {
+      UI.success('Base file unchanged since overlay was authored.');
+    }
+  }
+}
+
+// ─── drift ─────────────────────────────────────────────────────────────────
+
+function collectOverlays(cwd) {
+  const root = path.join(cwd, OVERLAYS_DIR);
+  if (!fs.existsSync(root)) return [];
+  const out = [];
+  const pushFrom = (sub, kind) => {
+    const dir = sub ? path.join(root, sub) : root;
+    if (!fs.existsSync(dir)) return;
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.md')) continue;
+      if (f.endsWith('.example.md')) continue;
+      if (sub === '' && (f === 'README.md')) continue;
+      out.push({ kind, name: f.replace(/\.md$/, ''), abs: path.join(dir, f), rel: path.join(OVERLAYS_DIR, sub || '', f) });
+    }
+  };
+  pushFrom('', 'skill');
+  pushFrom('agents', 'agent');
+  pushFrom('commands', 'command');
+  return out;
+}
+
+async function drift(target, options = {}) {
+  const cwd = process.cwd();
+  ensureConsumer(cwd);
+
+  const fwVersion = readFrameworkVersion(cwd);
+  const all = !!options.all || !target;
+  const targets = [];
+  if (all) {
+    targets.push(...collectOverlays(cwd));
+  } else {
+    const t = deriveTargetFromOverlayPath(cwd, target);
+    if (!t) {
+      UI.error(`Path is not under ${OVERLAYS_DIR}/ or has unexpected shape: ${target}`);
+      process.exit(1);
+    }
+    if (!fs.existsSync(t.abs)) {
+      UI.error(`Overlay not found: ${path.relative(cwd, t.abs)}`);
+      process.exit(1);
+    }
+    targets.push({ kind: t.kind, name: t.name, abs: t.abs, rel: path.relative(cwd, t.abs) });
+  }
+
+  if (targets.length === 0) {
+    UI.info('No overlays authored.');
+    return;
+  }
+
+  let drifted = 0;
+  let unknown = 0;
+  let clean = 0;
+  for (const t of targets) {
+    const content = fs.readFileSync(t.abs, 'utf8');
+    const { fm } = parseFrontmatter(content);
+    const versionField = `base_${t.kind}_version`;
+    const overlayVersion = fm[versionField];
+    const baseAbs = baseFilePathFor(cwd, t.kind, t.name);
+    const baseExists = fs.existsSync(baseAbs);
+
+    if (!baseExists) {
+      UI.error(`${t.rel}: base ${t.kind} "${t.name}" no longer exists in framework.`);
+      drifted++;
+      continue;
+    }
+
+    const baseSha = computeBaseFileSha(fs.readFileSync(baseAbs, 'utf8'));
+    let shaDrift = null;
+    if (fm.base_file_sha) {
+      shaDrift = fm.base_file_sha !== baseSha;
+    }
+    const versionDrift = overlayVersion && fwVersion && overlayVersion !== fwVersion;
+
+    if (shaDrift === true) {
+      UI.warning(`${t.rel}: base file changed since overlay was authored (sha ${fm.base_file_sha} → ${baseSha}).`);
+      drifted++;
+    } else if (shaDrift === false) {
+      UI.success(`${t.rel}: clean (sha matches base v${fwVersion}).`);
+      clean++;
+    } else if (versionDrift) {
+      UI.warning(`${t.rel}: targets v${overlayVersion}, installed v${fwVersion} — review (no base_file_sha to confirm).`);
+      unknown++;
+    } else if (overlayVersion) {
+      UI.info(`${t.rel}: targets v${overlayVersion} (no base_file_sha — drift unknown).`);
+      unknown++;
+    } else {
+      UI.warning(`${t.rel}: no base_${t.kind}_version in frontmatter.`);
+      unknown++;
+    }
+  }
+
+  UI.newline();
+  UI.info(`Summary: ${clean} clean, ${drifted} drifted, ${unknown} unknown — of ${targets.length} overlay(s).`);
+}
+
+module.exports = { scaffold, validate, drift };

package/src/utils/overlay-merger.js

@@ -34,8 +34,16 @@ function shortSha(content) {
   return crypto.createHash('sha256').update(content).digest('hex').slice(0, 12);
 }
 
-function buildMarker({ kind, name, baseVersion, overlaySha }) {
-  return `${MARKER_PREFIX} kind=${kind} name=${name} base_version=${baseVersion} overlay_sha=${overlaySha}
+// Public alias — the CLI scaffolder writes this value into the overlay
+// frontmatter (as `base_file_sha`) so `baldart overlay drift` can detect
+// when the base file changed upstream without re-parsing the merger logic.
+function computeBaseFileSha(content) {
+  return shortSha(content);
+}
+
+function buildMarker({ kind, name, baseVersion, baseSha, overlaySha }) {
+  const baseShaField = baseSha ? ` base_sha=${baseSha}` : '';
+  return `${MARKER_PREFIX} kind=${kind} name=${name} base_version=${baseVersion}${baseShaField} overlay_sha=${overlaySha}
      DO NOT EDIT MANUALLY. Edit .baldart/overlays/${kind}s/${name}.md instead;
      this file is regenerated by \`npx baldart update\`. -->`;
 }
@@ -44,13 +52,15 @@ function buildMarker({ kind, name, baseVersion, overlaySha }) {
  * Returns the marker fields encoded in the first line if present, or null.
  * Used by `update` to know "is this file ours (safe to regenerate) or did the
  * user edit it manually?"
+ *
+ * `base_sha` is optional — older generated files (pre-v3.19.0) won't have it.
  */
 function readMarker(content) {
   const firstLine = content.split('\n').slice(0, 3).join('\n');
   if (!firstLine.includes(MARKER_PREFIX)) return null;
-  const m = firstLine.match(/kind=(\S+) name=(\S+) base_version=(\S+) overlay_sha=(\S+)/);
+  const m = firstLine.match(/kind=(\S+) name=(\S+) base_version=(\S+)(?: base_sha=(\S+))? overlay_sha=(\S+)/);
   if (!m) return null;
-  return { kind: m[1], name: m[2], baseVersion: m[3], overlaySha: m[4] };
+  return { kind: m[1], name: m[2], baseVersion: m[3], baseSha: m[4] || null, overlaySha: m[5] };
 }
 
 /**
@@ -170,10 +180,12 @@ function mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersio
     : '';
 
   const overlaySha = shortSha(overlayContent);
+  const baseSha = shortSha(baseContent);
   const marker = buildMarker({
     kind,
     name,
     baseVersion: frameworkVersion || baseVersionTargeted,
+    baseSha,
     overlaySha
   });
 
@@ -202,5 +214,6 @@ module.exports = {
   readMarker,
   parseMarkdown,
   shortSha,
+  computeBaseFileSha,
   MARKER_PREFIX
 };