baldart 3.19.0 → 3.21.2

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

@@ -0,0 +1,315 @@
+---
+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
+---
+
+<!--
+DRIFT-CHECK
+This block is read by scripts/check-update-skill-drift.js (triggered by
+.github/workflows/check-update-skill-drift.yml on push tag v*.*.* and
+pull_request). When any of the numbers below changes against the actual
+sources, a warning is surfaced in the workflow run. The decision whether
+this skill needs an update is left to a human reviewer.
+
+update_js_prompts: 6
+hook_registry_entries: 3
+config_template_top_level_keys: features,git,identity,lsp,paths,stack,tools,version
+last_verified: v3.21.2
+-->
+
+
+# /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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.19.0",
+  "version": "3.21.2",
   "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}`);

package/src/commands/doctor.js

@@ -212,8 +212,47 @@ async function detectState(cwd, opts = {}) {
     state.overlays = countOverlays(cwd);
     state.overlaysDrifted = overlayDrift(cwd, state.frameworkVersion);
 
-    state.editGateRegistered = false;
-    try { state.editGateRegistered = Hooks.isRegistered(cwd); } catch (_) {}
+    state.hooksStatus = { malformed: false, hooks: [] };
+    state.hooksMissing = [];
+    state.hooksDrifted = [];
+    state.hooksLegacy = [];
+    try {
+      const status = Hooks.getStatus(cwd);
+      state.hooksStatus = status;
+      if (!status.malformed) {
+        state.hooksMissing  = status.hooks.filter((h) => !h.registered).map((h) => h.id);
+        state.hooksDrifted  = status.hooks.filter((h) => h.registered && h.drift && !h.legacy).map((h) => h.id);
+        state.hooksLegacy   = status.hooks.filter((h) => h.legacy).map((h) => h.id);
+      }
+    } catch (_) {}
+
+    // ---- Agent symlink integrity (since v3.20.0) -----------------------
+    // Source of truth for the BALDART agent list is the framework filesystem
+    // directory itself (`.framework/framework/.claude/agents/*.md`). For each
+    // name, the consumer must have a working `.claude/agents/<name>.md`
+    // (symlink to the framework copy, possibly merged with an overlay).
+    // A missing or broken symlink would otherwise be detected at runtime by
+    // `agent-discovery-gate.js`, blocking Agent calls. This probe lets the
+    // doctor heal it offline before the user hits the gate.
+    state.agentSymlinksBroken = [];
+    try {
+      if (state.frameworkPresent) {
+        const frameworkAgentsDir = path.join(cwd, '.framework', 'framework', '.claude', 'agents');
+        const consumerAgentsDir = path.join(cwd, '.claude', 'agents');
+        if (fs.existsSync(frameworkAgentsDir)) {
+          const baldartAgents = fs.readdirSync(frameworkAgentsDir)
+            .filter((f) => f.endsWith('.md') && f !== 'REGISTRY.md')
+            .map((f) => f.replace(/\.md$/, ''));
+          for (const name of baldartAgents) {
+            try {
+              fs.statSync(path.join(consumerAgentsDir, `${name}.md`));
+            } catch (_) {
+              state.agentSymlinksBroken.push(name);
+            }
+          }
+        }
+      }
+    } catch (_) { /* never block doctor on probe */ }
 
     // `.framework/` is a git subtree — gitignore matching it breaks every
     // future `git add` under that path (the failure mode that hit v3.13.0
@@ -410,15 +449,75 @@ function planActions(state) {
     // Non-blocking — keep looking for other actions to run in the same pass.
   }
 
-  if (state.editGateRegistered === false) {
+  // BALDART hooks (multi-hook registry since v3.18.0).
+  // Three buckets, three actions: missing → propose; legacy → propose
+  // (silent migration to current id); drifted → require interactive prompt.
+  if ((state.hooksMissing && state.hooksMissing.length > 0)
+      || (state.hooksLegacy && state.hooksLegacy.length > 0)) {
+    const ids = [...(state.hooksMissing || []), ...(state.hooksLegacy || [])];
     actions.push({
-      key: 'register-edit-gate',
-      label: 'Register framework-edit-gate hook (.claude/settings.json)',
-      why: 'Prevents project-specific tokens (Neo-Brutalism, merchant, …) from being written to .framework/ accidentally. Standard in v3.3.0+; missing on installs predating that version.',
+      key: 'register-hooks',
+      label: `Register/migrate BALDART hook(s) in .claude/settings.json (${ids.join(', ')})`,
+      why: 'BALDART hooks are missing or registered under a pre-v3.18 layout. They run on PreToolUse/Stop/SessionStart to gate edits and feed the auto-learning loop. Re-registration is idempotent and never overwrites user-customized commands without asking.',
       autoOk: true,
       run: async () => {
-        const res = require('../utils/hooks').register();
-        UI.success(`Hook registered: ${res.status} (${res.path})`);
+        const Hooks = require('../utils/hooks');
+        const res = await Hooks.registerAll(process.cwd(), {
+          onDrift: Hooks.createDriftPrompt(UI, { autoYes: state.autoMode }),
+        });
+        if (res.malformed) {
+          UI.warning('.claude/settings.json is malformed; fix it manually then re-run `npx baldart doctor`.');
+          return;
+        }
+        for (const r of res.results) {
+          if (r.status === 'created') UI.success(`Registered hook \`${r.id}\``);
+          else if (r.status === 'legacy-migrated') UI.success(`Migrated legacy hook to \`${r.id}\` (previous: ${r.previousCommand})`);
+        }
+      },
+    });
+  }
+  if (state.hooksDrifted && state.hooksDrifted.length > 0) {
+    actions.push({
+      key: 'reconcile-hooks-drift',
+      label: `Reconcile drifted BALDART hook(s) (${state.hooksDrifted.join(', ')})`,
+      why: 'These hooks are registered but their command differs from the BALDART default. This is typically a sign of a manual customization or a stale framework version on disk. Reconciliation prompts you per hook (Keep / Replace / Show diff).',
+      autoOk: false, // drift reconciliation is the kind of decision --auto must NOT make
+      run: async () => {
+        const Hooks = require('../utils/hooks');
+        const res = await Hooks.registerAll(process.cwd(), {
+          onDrift: Hooks.createDriftPrompt(UI), // always interactive here
+        });
+        for (const r of res.results) {
+          if (r.status === 'drift-replaced') UI.success(`Replaced \`${r.id}\` (was: ${r.previousCommand})`);
+          else if (r.status === 'drift-kept') UI.info(`Kept \`${r.id}\` as-is.`);
+        }
+      },
+    });
+  }
+
+  // Agent symlink integrity (since v3.20.0). Re-runs the agent merge loop to
+  // recreate any missing per-agent symlink. Calls `SymlinkUtils.mergeAgents`
+  // directly rather than dispatching to `update` — we want only the symlink
+  // pass, not a full update (which would also pull, merge overlays, register
+  // hooks, and verify config drift).
+  if (state.agentSymlinksBroken && state.agentSymlinksBroken.length > 0) {
+    actions.push({
+      key: 'repair-agent-symlinks',
+      label: `Repair ${state.agentSymlinksBroken.length} broken agent symlink(s)`,
+      why: `BALDART expects these agents to be reachable via .claude/agents/<name>.md but the symlinks are missing or broken: ${state.agentSymlinksBroken.join(', ')}. Without these, the agent-discovery-gate PreToolUse hook will deny Agent calls targeting these names.`,
+      autoOk: true,
+      run: async () => {
+        const SymlinkUtils = require('../utils/symlinks');
+        // Re-read the config here (not stashed on state) to pick up
+        // `tools.enabled`. Falls back to ['claude'] if absent/malformed.
+        const cfg = loadConfig(process.cwd());
+        const enabledTools = (cfg && !cfg.__malformed
+          && cfg.tools && Array.isArray(cfg.tools.enabled))
+          ? cfg.tools.enabled
+          : ['claude'];
+        const symlinks = new SymlinkUtils();
+        symlinks.mergeAgents({ tools: enabledTools });
+        UI.success(`Re-merged agent symlinks for tools: ${enabledTools.join(', ')}`);
       },
     });
   }
@@ -616,11 +715,36 @@ function renderDiagnostic(state) {
       console.log(`   • ${o.name} targets v${o.target}, installed v${o.installed}`));
   }
 
-  console.log(statusLine(
-    'Edit gate',
-    state.editGateRegistered ? 'registered' : 'NOT registered (.claude/settings.json)',
-    state.editGateRegistered ? 'ok' : 'warn'
-  ));
+  {
+    const total = state.hooksStatus && state.hooksStatus.hooks ? state.hooksStatus.hooks.length : 0;
+    const missing = state.hooksMissing ? state.hooksMissing.length : 0;
+    const drifted = state.hooksDrifted ? state.hooksDrifted.length : 0;
+    const legacy  = state.hooksLegacy  ? state.hooksLegacy.length  : 0;
+    const registered = total - missing;
+    let summary;
+    let status;
+    if (state.hooksStatus && state.hooksStatus.malformed) {
+      summary = '.claude/settings.json is malformed';
+      status = 'warn';
+    } else if (missing === 0 && drifted === 0 && legacy === 0) {
+      summary = `${registered}/${total} registered`;
+      status = 'ok';
+    } else {
+      const parts = [`${registered}/${total} registered`];
+      if (missing) parts.push(`${missing} missing`);
+      if (drifted) parts.push(`${drifted} drifted`);
+      if (legacy)  parts.push(`${legacy} pre-v3.18`);
+      summary = parts.join(', ');
+      status = 'warn';
+    }
+    console.log(statusLine('BALDART hooks', summary, status));
+    if (state.hooksMissing && state.hooksMissing.length)
+      console.log(`   • missing:   ${state.hooksMissing.join(', ')}`);
+    if (state.hooksDrifted && state.hooksDrifted.length)
+      console.log(`   • drifted:   ${state.hooksDrifted.join(', ')}`);
+    if (state.hooksLegacy && state.hooksLegacy.length)
+      console.log(`   • pre-v3.18: ${state.hooksLegacy.join(', ')}`);
+  }
 
   if (state.frameworkIgnored && state.frameworkIgnored.ignored) {
     console.log(statusLine(
@@ -663,6 +787,7 @@ async function doctor(opts = {}) {
   const offline = !!opts.offline;
 
   const state = await detectState(cwd, { offline });
+  state.autoMode = auto;
   renderDiagnostic(state);
 
   const actions = planActions(state);

package/src/commands/update.js

@@ -400,13 +400,25 @@ async function update(options = {}) {
       UI.warning(`Routines wizard skipped: ${err.message}`);
     }
 
-    // Framework-edit-gate hook (since v3.3.0) — backfill for consumers
-    // installed before v3.3.0 didn't have this hook. We register it on every
-    // update (idempotent — no-op if already present).
+    // BALDART hooks (multi-hook registry since v3.18.0) — backfill for
+    // consumers that predate any of the hooks shipped in the current
+    // framework version. Idempotent: no-op when every hook is already in
+    // place. Drift on an existing entry triggers an interactive prompt
+    // (Keep / Replace / Show diff); on --auto / -y the default is 'keep'.
     try {
-      const res = Hooks.register();
-      if (res.status === 'created' || res.status === 'updated') {
-        UI.success('Registered framework-edit-gate hook in .claude/settings.json (v3.3.0+ default).');
+      const res = await Hooks.registerAll(process.cwd(), {
+        onDrift: Hooks.createDriftPrompt(UI, { autoYes }),
+      });
+      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 (v3.18.0+ default).`);
+          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.`);
+          // 'already' is silent on update to avoid noise
+        }
       }
     } catch (err) {
       UI.warning(`Hook registration skipped: ${err.message}`);