baldart 3.18.1 → 3.19.0

package/CHANGELOG.md

@@ -5,6 +5,54 @@ 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.

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.1
+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/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.1",
+  "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
 };