baldart 3.18.1 → 3.21.1

package/framework/.claude/skills/baldart-update/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: baldart-update
+description: "Guidance for updating BALDART framework to the latest version in a consumer repo. Use when the user says /baldart-update, 'aggiorna baldart', 'aggiorna framework', 'update del framework', 'pull baldart latest', or wants to bring the framework up-to-date. Replicates all 5 native CLI decision points (preview diff, working tree stash, hooks drift, schema config drift, BALDART-managed auto-commit) as chat-side confirmations before launching `npx baldart update --yes` via Bash. For non-update drift, defers to `npx baldart` (smart doctor)."
+contamination_scan: skip
+---
+
+# /baldart-update — Update framework in this consumer
+
+Guide the user through an update of the BALDART framework inside their
+consumer repo, replicating in chat **every interactive decision point** the
+CLI would normally ask in the terminal — so the CLI can be driven with
+`--yes` while the user keeps full control of each choice.
+
+```
+╔══════════════════════════════════════════════════════════════════════╗
+║ BOOTSTRAP NOTICE                                                     ║
+║                                                                      ║
+║ IF THIS IS THE FIRST UPDATE AFTER A CONSUMER WAS ON A VERSION        ║
+║ THAT PREDATES /baldart-update, THIS SKILL DOES NOT YET EXIST IN      ║
+║ THE CONSUMER'S .claude/skills/. The user must run:                   ║
+║                                                                      ║
+║     npx baldart update                                               ║
+║                                                                      ║
+║ directly in their terminal **once**, and the skill becomes           ║
+║ available for every subsequent update. This skill is the pattern     ║
+║ for follow-up updates, not the very first one.                       ║
+╚══════════════════════════════════════════════════════════════════════╝
+```
+
+## Execution model — IMPORTANT
+
+This is an **agent-driven skill with full chat-side replication** of every
+decision point the CLI would pose interactively. The flow is:
+
+1. Run *read-only* probes to detect the same conditions `update.js` would
+   detect (version drift, dirty working tree, hooks drift, schema config
+   drift, BALDART-managed files to auto-commit).
+2. For each detected condition, surface it in chat and ask the user the
+   exact same question the CLI would ask in a TTY.
+3. Once every prompt has been answered in chat, launch `npx baldart update
+   --yes` via `Bash` (with a long timeout — see Hard rules). The `--yes`
+   flag is safe here precisely because there is no native prompt left to
+   silence: every one of them has already been resolved above.
+4. Parse the CLI output, report the backup tag + new version, surface any
+   stash-pop conflicts that may have happened after the subtree pull.
+
+This is the **intentional divergence** from `/baldart-push`, which is
+pure-guidance (the user runs the CLI themselves). Here the user has asked
+for an agent that drives the update, so the skill drives it — but it
+replicates every confirmation so nothing is silently auto-accepted.
+
+## When to use
+
+- The user invokes `/baldart-update`.
+- The user says "aggiorna baldart", "aggiorna framework", "update del
+  framework", "pull baldart latest", "porta baldart all'ultima versione".
+- The user wants to bring the framework payload in the consumer repo
+  in sync with upstream `main`.
+
+## When NOT to use
+
+- The user wants to fix drift that is NOT an update (hooks missing, config
+  schema drift in isolation, broken symlinks). → `npx baldart` (smart
+  doctor) is the right tool — it picks the right action among ~12.
+- The consumer has no `.framework/` directory yet. → `npx baldart add`.
+- The user wants to contribute local framework improvements upstream.
+  → `/baldart-push`.
+- The user is in the BALDART repo itself (i.e. `/Users/.../BALDART`),
+  not in a consumer. This skill is for consumers; this repo updates
+  via `git pull`.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** none directly (the skill reads
+`.framework/VERSION`, `.baldart/state.json`, and `.claude/settings.json`,
+which are BALDART-owned and not gated by config keys).
+**Gated by features:** none.
+**Overlay:** loads `.baldart/overlays/baldart-update.md` if present.
+Typical overlay content: extra pre-flight checks specific to the consumer
+(e.g. "block update if a release branch is open"), or post-update
+verification steps (e.g. "run `npm test` after symlink reconcile").
+**On missing/empty keys:** not applicable — the skill operates on BALDART's
+own state files. See [framework/agents/project-context.md](../../../agents/project-context.md)
+for the protocol.
+
+## Hard rules
+
+1. **MUST NOT re-implement the logic of `update.js`.** Same rule as
+   `/baldart-push`: the CLI is the source of truth. The skill only
+   replicates prompts and parses output.
+2. **MUST replicate in chat all 5 decision points** before passing `--yes`:
+   preview, working-tree stash, hooks drift, schema config drift,
+   auto-commit of BALDART-managed files. Silencing one is dishonest — the
+   user thinks they confirmed everything, but they didn't see that prompt.
+3. **MUST pass `timeout: 600000` (10 minutes)** to the `Bash` call running
+   `npx baldart update --yes`. The default 120s is not enough for subtree
+   pull + symlink reconcile + post-update wizard + hooks register +
+   auto-commit on real-world repos.
+4. **MUST NOT pass `--auto-stash`** to the CLI: `--yes` already implies it.
+   Passing both is imprecise and signals a misread of the CLI.
+5. **MUST report the backup tag** generated by the CLI, so the user has a
+   one-line rollback path.
+6. **MUST NOT launch update if `.framework/` is missing** — defer to
+   `npx baldart add` and stop.
+7. **MUST NOT assume defaults when a pre-check fails.** If the skill cannot
+   read `.claude/settings.json` or `baldart.config.yml`, it asks the user
+   how to proceed or aborts. Never silence a decision point because a
+   probe failed.
+
+## The 5 decision points the skill replicates
+
+| # | Native CLI prompt           | Chat-side replication                                                                                                                                  | Detect via                                                                                                                                                          |
+|---|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 1 | "Proceed with update?"       | Show "Remote: N commit(s) ahead" + last N commit messages, ask "Procedo?"                                                                              | `npx baldart version` (parse "Remote: …" + "Repository: <url>") → if N > 0, `git fetch <url> main && git log HEAD..FETCH_HEAD --oneline -- .framework/`              |
+| 2 | "Stash dirty working tree?"  | List modified files, explain they will go into `baldart-pre-update-<timestamp>`, ask explicit confirmation                                              | `git status --porcelain` in consumer root                                                                                                                            |
+| 3 | Hooks drift prompt           | Compare `.claude/settings.json` entries vs `HOOK_REGISTRY`; if drift, describe what backfill will change                                                | `cat .claude/settings.json` + read `.framework/src/utils/hooks.js` for `HOOK_REGISTRY`                                                                               |
+| 4 | Schema config migration      | Compare `baldart.config.yml` keys vs `.framework/framework/templates/baldart.config.template.yml`; if missing keys, list which + consequence            | semantic diff key-by-key (NOT textual diff)                                                                                                                          |
+| 5 | Auto-commit BALDART-managed  | Classify `git status --porcelain` paths as BALDART-managed vs user-owned by path-prefix, show classification, confirm commit of the managed subset      | path-prefix matching on `.framework/`, `.claude/agents/`, `.claude/skills/`, `.claude/commands/`, `AGENTS.md`, `agents/`                                              |
+
+> **IMPORTANT — do NOT use `git -C .framework fetch`.** `.framework/` is a git
+> subtree, not a separate repo: git commands inside it fall back to the consumer's
+> own repo and would fetch the wrong remote. The correct pattern (mirroring
+> `update.js` + `src/utils/git.js`) is `git fetch <BALDART-repo-url> main` from
+> the consumer root, then `git log HEAD..FETCH_HEAD -- .framework/` for the
+> preview. The repo URL is exposed by `npx baldart version` in the
+> `Repository:` line.
+
+## Workflow
+
+### Step 0 — Pre-flight (read-only)
+
+```bash
+# One call gives both: installed version, behind count, and the
+# BALDART repo URL. NO git operation inside .framework/ — that
+# directory is a git subtree, not a separate repo.
+npx baldart version
+```
+
+Parse the output for:
+
+- `Installed: vX.Y.Z` — current framework version in the consumer.
+- `Remote: N commit(s) ahead — pull with …` — number of commits behind upstream. If this line is absent or shows 0, the consumer is up-to-date.
+- `Repository: <url>` — the BALDART git URL (needed in Step 1).
+
+If `Remote:` is absent / shows 0 → tell the user "Already up-to-date — version vX.Y.Z" and STOP. Do not launch the CLI.
+
+If `.framework/` does not exist, `npx baldart version` will say "framework not installed" — STOP and instruct `npx baldart add`. Do not attempt to recover.
+
+### Step 1 — Replicate decision point #1 (preview)
+
+```bash
+# Use the URL extracted from Step 0, not `git -C .framework`.
+# This mirrors src/utils/git.js (fetch + diffWithRemote use FETCH_HEAD,
+# never `git -C .framework`).
+git fetch <BALDART-repo-url> main
+git log HEAD..FETCH_HEAD --oneline -- .framework/
+```
+
+Surface to the user:
+
+- Current installed version (from Step 0).
+- Number of commits behind (from Step 0).
+- One-line summary of each incoming commit (from the `git log` above).
+
+Ask: *"Procedo con l'aggiornamento?"*. If no → STOP.
+
+### Step 2 — Replicate decision point #2 (working tree)
+
+```bash
+git status --porcelain
+```
+
+If output is empty, proceed silently. If not, list the modified files in
+chat, explain:
+
+> *"Il working tree ha N file modificati. Il CLI li stasherà in un ref
+> `baldart-pre-update-<timestamp>` prima del pull e li ripristinerà dopo.
+> Posso procedere con lo stash automatico?"*
+
+If the user refuses → STOP, instruct them to commit or stash manually
+and re-run `/baldart-update`.
+
+### Step 3 — Replicate decision points #3 + #4 (hooks/schema drift)
+
+```bash
+# Hooks drift detection
+cat .claude/settings.json
+# Compare entries against HOOK_REGISTRY in .framework/src/utils/hooks.js
+# (the skill reads both and reports any expected entry missing
+# or any installed entry with a stale config)
+
+# Schema drift detection
+# Compare top-level keys in baldart.config.yml against
+# .framework/framework/templates/baldart.config.template.yml
+```
+
+For each drift detected, describe what `update.js` would do:
+
+- Hooks drift → "il CLI registrerà le hook mancanti in `settings.json`
+  (entry: `baldart-<hook-name>`). Procedo?"
+- Schema drift → "il CLI segnalerà che mancano le chiavi `X.Y` da
+  `baldart.config.yml` e suggerirà di rilanciare `npx baldart configure`
+  dopo l'update. Procedo (l'update non bloccherà, ma è bene saperlo)?"
+
+If a probe fails (e.g. `settings.json` malformed), ask the user how to
+proceed — never silently assume "no drift".
+
+### Step 4 — Replicate decision point #5 (auto-commit classification)
+
+```bash
+git status --porcelain
+```
+
+Classify each path:
+
+- **BALDART-managed**: starts with `.framework/`, `.claude/agents/`,
+  `.claude/skills/`, `.claude/commands/`, `AGENTS.md`, `agents/`.
+- **User-owned**: everything else.
+
+Show the user the classification:
+
+> *"Dopo il pull, il CLI auto-committa SOLO i file BALDART-managed che
+> risultano modificati dal reconcile (es. symlink ricreati, agent/command
+> generati). I tuoi file user-owned non vengono toccati. Procedo?"*
+
+If no managed files would be modified, skip the prompt silently.
+
+### Step 5 — Run the CLI
+
+```bash
+npx baldart update --yes
+```
+
+**Use the Bash tool with `timeout: 600000`** (10 minutes). Capture stdout
+and stderr — both are needed for Step 6.
+
+Do NOT pass `--auto-stash` (redundant with `--yes`).
+
+### Step 6 — Report
+
+Extract the post-update facts and surface them:
+
+```bash
+# Backup tag (most recent baldart-pre-update-* tag)
+git tag -l 'baldart-pre-update-*' --sort=-creatordate | head -1
+
+# New installed version
+cat .framework/VERSION
+
+# Stash-pop conflicts (if any)
+# Grep stdout/stderr for: CONFLICT, "stash pop failed", "unmerged paths"
+# If matches found, list the conflicted paths:
+git status --porcelain | grep '^UU'
+```
+
+Report to the user, in order:
+
+1. **Version**: `vX.Y.Z → vA.B.C` (delta).
+2. **Backup tag**: the `baldart-pre-update-<timestamp>` ref, with the
+   rollback command: `git reset --hard <tag>` (only if needed).
+3. **Hooks reconciled**: any hook backfilled.
+4. **Schema notes**: any missing key still flagged → suggest
+   `npx baldart configure`.
+5. **Stash-pop status**: clean / conflicts present (with file list).
+6. **Suggested next step**: if schema drift residual or other non-update
+   doctor checks fired, suggest `npx baldart` (smart doctor).
+
+## Failure modes
+
+| Symptom                                                | Cause                                              | What you do                                                                                                                                                  |
+|--------------------------------------------------------|----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `git -C .framework fetch` errors out                   | Offline / auth issue / repo URL changed            | STOP. Surface the error verbatim. Ask the user to retry when network is back. Do not launch update.                                                          |
+| Working tree dirty + user refuses stash                | Authoring decision                                 | STOP cleanly. Instruct: commit or stash manually, then re-run `/baldart-update`.                                                                              |
+| `update.js` exits non-zero (subtree pull conflict)     | Upstream and local both modified the same file     | Surface the CLI error verbatim. Provide the backup tag + `git reset --hard <tag>` rollback command. Do NOT attempt automatic conflict resolution.            |
+| Stash-pop conflicts after the subtree pull             | User-modified file collides with framework change  | Detected by grep on stdout/stderr (`CONFLICT`, `stash pop failed`, `unmerged paths`). List `git status --porcelain | grep '^UU'` paths. Instruct manual resolve. NEVER auto-resolve with `--hard` or `--no-verify`. |
+| `.framework/` missing                                  | Consumer never installed BALDART                   | STOP. Instruct `npx baldart add`. Do not improvise.                                                                                                          |
+| Bash 10-minute timeout exceeded                        | Very slow network / disk / huge repo               | Surface the timeout. Instruct the user to run `npx baldart update` manually in their terminal to see live progress.                                          |
+| Pre-check probe fails (e.g. `settings.json` malformed) | Consumer state inconsistent                        | STOP. Surface the probe failure. Ask the user whether to proceed without that pre-check, or to fix manually first. Never silently assume "no drift".         |
+
+## Why this skill exists
+
+The smart doctor (`npx baldart`, no args) already proposes an update
+when it detects remote ahead — but it does so as **one of about twelve**
+possible actions (install, configure, migrate, repair symlinks, register
+hooks, reconcile state ledger, …). When the user knows they want *only*
+to update, going through the doctor is more friction than signal.
+
+This skill is the direct path for that case, **and** it does what the
+terminal CLI does — surface every decision point as a confirmation —
+inside the chat instead of in the user's shell. The user keeps the
+control they would have in a TTY, but they get it conversationally.
+
+`/baldart-push` and `/baldart-update` together form the conversational
+spine of BALDART maintenance:
+
+- `/baldart-update` — pull from upstream.
+- `/baldart-push` — push to upstream.
+
+Both wrap the CLI without re-implementing it; both keep the user in the
+loop. The CLI remains the source of truth.

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/AGENTS.md

@@ -94,6 +94,7 @@ Conflict steps (must follow in order):
 
 - MUST treat `AGENTS.md` as authoritative for agent rules.
 - MUST invoke `codebase-architect` agent (via Task tool) whenever you need to understand codebase structure, existing patterns, or code architecture before planning or implementing changes; do not proceed with planning or implementation without first understanding the existing system through codebase-architect.
+- MUST NOT silently fall back when an `Agent` (a.k.a. `Task`) tool call returns empty (`0 tool uses · Done`), times out, or fails with `permissionDecision: deny`. This pattern indicates a Claude Code sub-agent failure (see anthropics/claude-code#56869) or a discovery miss / blocked agent (see #20931 and BALDART's own `agent-discovery-gate` PreToolUse hook), NOT a signal to substitute another agent. STOP, report to the user verbatim: "Agent `<name>` non discoverato o fallito in questa sessione — riavvia Claude Code e verifica con `npx baldart doctor`", and wait for direction. Never auto-route to `feature-dev:*`, `general-purpose`, or any other marketplace/built-in agent as a replacement. **This rule is the ONLY defense against bug #56869 (which BALDART cannot patch from outside Claude Code); deviating from it reintroduces the exact failure mode the rule exists to prevent.**
 - MUST NOT work on files/components already claimed by another agent; multiple agents allowed if working on independent areas.
 - MUST perform a mandatory clarity analysis before fixing any issue labeled `bug`; confirm that the issue description, proposed correct behavior, and edge cases are unambiguous, document any resolved doubts, and only start fix work once every zone of uncertainty is covered.
 - MUST mark missing info as UNKNOWN and ask the user; if blocked, set `BLOCKED` with a blocker.

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.21.1",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/add.js

@@ -166,19 +166,24 @@ async function add(repo, options) {
       UI.success('Git aliases configured');
     }
 
-    // Framework-edit-gate hook (since v3.3.0)
-    // Auto-register the PreToolUse hook that prevents project-specific
-    // tokens from being written into .framework/ skills accidentally.
+    // BALDART hooks (multi-hook registry since v3.18.0)
+    // Auto-register every hook in src/utils/hooks.js HOOK_REGISTRY into
+    // .claude/settings.json. Drift on an existing entry triggers an
+    // interactive prompt (Keep / Replace / Show diff).
     try {
-      const res = Hooks.register();
-      if (res.status === 'created') {
-        UI.success('Registered framework-edit-gate hook in .claude/settings.json');
-      } else if (res.status === 'updated') {
-        UI.success('Added framework-edit-gate hook to existing .claude/settings.json');
-      } else if (res.status === 'already') {
-        UI.info('framework-edit-gate hook already registered.');
-      } else if (res.status === 'malformed') {
+      const res = await Hooks.registerAll(process.cwd(), {
+        onDrift: Hooks.createDriftPrompt(UI),
+      });
+      if (res.malformed) {
         UI.warning('.claude/settings.json is malformed; skipped hook registration. Run `npx baldart doctor` after fixing it.');
+      } else {
+        for (const r of res.results) {
+          if (r.status === 'created') UI.success(`Registered hook \`${r.id}\` in .claude/settings.json`);
+          else if (r.status === 'legacy-migrated') UI.success(`Migrated legacy hook to \`${r.id}\` (previous: ${r.previousCommand})`);
+          else if (r.status === 'drift-replaced') UI.success(`Replaced drifted hook \`${r.id}\` (was: ${r.previousCommand})`);
+          else if (r.status === 'drift-kept') UI.info(`Kept user-customized hook \`${r.id}\` as-is.`);
+          else if (r.status === 'already') UI.info(`Hook \`${r.id}\` already registered.`);
+        }
       }
     } catch (err) {
       UI.warning(`Hook registration skipped: ${err.message}`);