baldart 3.33.1 → 3.34.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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.34.0] - 2026-05-30
+
+Adds an **assert-active git-hooks health check** to `baldart doctor` and the `worktree-manager` verify step. A consumer had `core.hooksPath` pointing at `.git/hooks` (empty) while the repo's versioned hooks lived in `scripts/git-hooks/` — the pre-commit schema guard and pre-push were **silently inactive for days**. The existing worktree-manager verify (`git config core.hooksPath || true`) only *read* the value without asserting anything, so it never caught the drift. Same class as the LSP bug: the framework "verifies" by reading a proxy instead of asserting the real state. This moves it from read-only to assert-active. **WARN-only** — the check never mutates `core.hooksPath` (a wrong heuristic + auto-fix would be worse than the original bug); it surfaces the exact remediation command and lets the user apply it. **No new `baldart.config.yml` keys** — it's a universal, always-on, filesystem-autodetected check, so the schema-propagation rule does not apply.
+
+### Added — git-hooks health check (assert-active)
+
+- **[src/utils/githooks.js](src/utils/githooks.js)**: new, self-contained, fail-safe utility (distinct from `src/utils/hooks.js`, which manages `.claude/settings.json` hooks). `getStatus(cwd)` detects the repo's versioned-hooks directory (`.husky`, `.githooks`, `scripts/git-hooks`, `githooks` — first that exists and contains a standard-named hook), resolves the **active** hooks dir explicitly (`core.hooksPath` → relative resolved against `git rev-parse --show-toplevel`, absolute verbatim; unset → `<git-dir>/hooks`, handling the worktree `.git`-is-a-file case), and asserts the active dir serves the versioned hooks. **`git rev-parse --git-path hooks` is deliberately NOT used** — empirically it returns the configured value relative/unresolved and historically some git versions ignored `core.hooksPath` for it. Returns `checked:false` (silent, `ok:true`) when no managed hooks exist or on any error, so the check never produces a false WARN.
+- **[src/utils/githooks.js](src/utils/githooks.js)**: pure exported `isActiveServing(activeAbs, expectedAbs)` — identical-or-nested decision (covers husky v9, which sets `core.hooksPath=.husky/_` with user hooks in `.husky/`). Paths are canonicalized (symlink-resolved, handling non-existent leaves) before comparison so a symlinked ancestor (macOS `/var`→`/private/var`, symlinked repo/home) never yields a false INACTIVE. Executability (`-x`) is asserted only for raw dirs git execs directly; husky user hooks (not required `+x` in v9) skip the assert.
+- **[src/commands/doctor.js](src/commands/doctor.js)**: probe wired into `detectState` (`state.gitHooks`), a `Git hooks` line in `renderDiagnostic` (silent when `checked:false`), and an **advisory print-only** action in `planActions` (`githooks-health`) whose `run()` prints the WARN + fix command and **never mutates** `core.hooksPath` (safe under `--auto`).
+- **[framework/.claude/skills/worktree-manager/SKILL.md](framework/.claude/skills/worktree-manager/SKILL.md)**: step 4 (isolation setup) replaces the silent `git config core.hooksPath || true` read with a lean **assert** — detects the versioned-hooks dir, resolves the active dir, and echoes a loud `⚠️ WARNING` + the `git config core.hooksPath <dir>` fix on mismatch (matches husky v9 `.husky/_` and `<dir>/*` as active). The worktree shares `core.hooksPath` via `.git/commondir`, so the same resolution applies.
+
+### Tests
+
+- **[src/utils/__tests__/githooks-active.test.js](src/utils/__tests__/githooks-active.test.js)**: new — 8 pure fixtures for `isActiveServing` (the mayo bug, husky v9 nesting, identical dirs, prefix-not-a-boundary, trailing-sep normalization).
+- **[scripts/test-githooks.sh](scripts/test-githooks.sh)**: new — drives **real** git repos: misconfig (`hooksPath=.git/hooks`, hooks in `scripts/git-hooks`) → inactive + fix; correctly wired → ok; non-executable raw hook → ok=false + chmod fix; husky v9 → active, `-x` assert skipped; no managed hooks → `checked:false` (silent).
+
 ## [3.33.1] - 2026-05-30
 
 Fixes a **false-positive in the LSP layer's verify step** that let `/lsp-bootstrap` (and `baldart configure` / `doctor`) report a language server as `verified` while every real LSP call failed with `Executable not found in $PATH` — a dead layer masked by `codebase-architect`'s silent Grep fallback. Root cause was a **resolution mismatch**: verify used `npx --no-install typescript-language-server --version` (resolves from `node_modules/.bin`), but the consumer — Claude Code's LSP tool — spawns the server **by name from `$PATH`**. The npm-dev install (`npm install --save-dev`) put the binary in `node_modules/.bin`, which is *not* on `$PATH`, so verify passed and spawn failed. The npm-managed adapters now install **globally** so the binary lands on `$PATH`, and verify checks `$PATH` reachability the *same way the consumer spawns it*. **No new `baldart.config.yml` keys** — reachability is computed, not configured, so the schema-propagation rule does not apply.

package/README.md

@@ -239,7 +239,7 @@ The `ui-expert` agent is upgraded from a generic baseline to a world-class UI/UX
 
 ### LSP Symbol Search Layer (new in v3.10.0)
 
-When `features.has_lsp_layer: true`, `codebase-architect` and the code-exploration skills (`context-primer`, `bug`, `prd`, `new`, `simplify`) prefer LSP `find-references` / `go-to-definition` over Grep for identifier-shaped queries — the filtering happens **before** Claude reads files, so a common function name no longer dumps thousands of textual matches into context. Opt-in at `baldart configure`; BALDART installs the matching language servers (npm devDeps for TypeScript/Python, system commands printed for Go/Rust/Ruby). Grep remains the fallback for free-text queries and degraded states. See [`framework/agents/code-search-protocol.md`](framework/agents/code-search-protocol.md).
+When `features.has_lsp_layer: true`, `codebase-architect` and the code-exploration skills (`context-primer`, `bug`, `prd`, `new`, `simplify`) prefer LSP `find-references` / `go-to-definition` over Grep for identifier-shaped queries — the filtering happens **before** Claude reads files, so a common function name no longer dumps thousands of textual matches into context. Opt-in at `baldart configure`; BALDART installs the matching language servers (global npm install for TypeScript/Python — the binary must be on `$PATH` because Claude Code's LSP tool spawns it by name; system commands printed for Go/Rust/Ruby). Grep remains the fallback for free-text queries and degraded states. See [`framework/agents/code-search-protocol.md`](framework/agents/code-search-protocol.md).
 
 ### Commands
 

package/VERSION

@@ -1 +1 @@
-3.33.1
+3.34.0

package/framework/.claude/skills/worktree-manager/SKILL.md

@@ -411,8 +411,32 @@ else
   echo "PORT=$PORT" >> .env.local
 fi
 
-# 5. Verify husky hooks work (they share via .git/commondir)
-git config core.hooksPath || true
+# 5. ASSERT git hooks are ACTIVE — not just readable.
+#    The worktree shares core.hooksPath via .git/commondir, so the same
+#    resolution applies here as in the main checkout. Reading the value
+#    (the old `git config core.hooksPath || true`) is NOT enough: it never
+#    catches the failure mode where core.hooksPath points at an empty dir
+#    while the repo's versioned hooks live elsewhere (pre-commit / pre-push
+#    silently inactive). Detect the versioned-hooks dir and assert it is served.
+HOOK_SRC=""
+for d in .husky .githooks scripts/git-hooks githooks; do
+  if [ -d "$d" ] && ls "$d" 2>/dev/null | grep -qE '^(pre-commit|pre-push|commit-msg)$'; then
+    HOOK_SRC="$d"; break
+  fi
+done
+if [ -n "$HOOK_SRC" ]; then
+  ACTIVE="$(git config --get core.hooksPath || echo .git/hooks)"
+  # Lean literal-string match (HOOK_SRC is relative). Full path resolution +
+  # canonicalization lives in `baldart doctor` (src/utils/githooks.js); an
+  # absolute core.hooksPath here would warn spuriously — rare, run doctor to confirm.
+  case "$ACTIVE" in
+    "$HOOK_SRC"|"$HOOK_SRC"/*|.husky/_) : ;;  # active dir serves the versioned hooks (incl. husky v9 .husky/_)
+    *)
+      echo "⚠️  WARNING: git hooks INATTIVI — gli hook versionati sono in '$HOOK_SRC' ma core.hooksPath = '$ACTIVE'." >&2
+      echo "    Esegui per riattivarli:  git config core.hooksPath $HOOK_SRC" >&2
+      ;;
+  esac
+fi
 ```
 
 ### 5. Verify baseline

package/package.json

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

package/src/commands/doctor.js

@@ -30,6 +30,7 @@ const GitUtils = require('../utils/git');
 const UI = require('../utils/ui');
 const State = require('../utils/state');
 const Hooks = require('../utils/hooks');
+const GitHooks = require('../utils/githooks');
 const LspInstaller = require('../utils/lsp-installer');
 const UpdateNotifier = require('../utils/update-notifier');
 const cliPackageJson = require('../../package.json');
@@ -234,6 +235,16 @@ async function detectState(cwd, opts = {}) {
       }
     } catch (_) {}
 
+    // ---- Git-hooks health (since v3.34.0) ------------------------------
+    // Assert that the repo's versioned git hooks (pre-commit/pre-push/…) are
+    // actually being run — i.e. `core.hooksPath` resolves to the directory
+    // that holds them. A drift here (e.g. core.hooksPath=.git/hooks while the
+    // hooks live in scripts/git-hooks/) silently disables every hook. Distinct
+    // from the BALDART `.claude/settings.json` hooks probed above. Fully
+    // fail-safe: `checked:false` when no managed hooks exist or on any error.
+    state.gitHooks = { checked: false, ok: true };
+    try { state.gitHooks = GitHooks.getStatus(cwd); } 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
@@ -503,6 +514,28 @@ function planActions(state) {
     });
   }
 
+  // Git-hooks health (since v3.34.0). ADVISORY ONLY — the action's run() never
+  // mutates `core.hooksPath` (a wrong heuristic + auto-fix is worse than the
+  // original silent-inactive bug). It surfaces the WARN + the exact remediation
+  // command so the user applies it deliberately. Present as an action (rather
+  // than a bare table WARN) so `doctor` doesn't contradict it with "Nothing to
+  // do". Safe to run in --auto since it only prints.
+  if (state.gitHooks && state.gitHooks.checked && !state.gitHooks.ok) {
+    actions.push({
+      key: 'githooks-health',
+      label: state.gitHooks.inactive
+        ? `Git hooks INACTIVE — ${state.gitHooks.source} hooks in ${state.gitHooks.expectedDir} are not being run`
+        : `Git hooks not executable — ${state.gitHooks.nonExecutable.join(', ')}`,
+      why: `${state.gitHooks.detail}. Fix: ${state.gitHooks.fixCommand}`,
+      autoOk: true, // advisory print-only; run() does NOT mutate config
+      run: () => {
+        UI.warning(state.gitHooks.detail);
+        UI.info('Run to re-activate the repo\'s versioned git hooks:');
+        console.log(`    ${state.gitHooks.fixCommand}`);
+      },
+    });
+  }
+
   // 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
@@ -787,6 +820,29 @@ function renderDiagnostic(state) {
       console.log(`   • pre-v3.18: ${state.hooksLegacy.join(', ')}`);
   }
 
+  // Git-hooks health (v3.34.0+). Silent when no versioned-hooks dir exists
+  // (`checked:false`) — most consumers have no managed git hooks and must see
+  // zero noise here.
+  if (state.gitHooks && state.gitHooks.checked) {
+    if (state.gitHooks.ok) {
+      console.log(statusLine(
+        'Git hooks',
+        `${state.gitHooks.source} active (${state.gitHooks.expectedHooks.join(', ')})`,
+        'ok'
+      ));
+    } else if (state.gitHooks.inactive) {
+      console.log(statusLine(
+        'Git hooks',
+        `INACTIVE — ${state.gitHooks.source} hooks in ${state.gitHooks.expectedDir} not run by core.hooksPath`,
+        'warn'
+      ));
+      console.log(`   • fix: ${state.gitHooks.fixCommand}`);
+    } else {
+      console.log(statusLine('Git hooks', state.gitHooks.detail, 'warn'));
+      console.log(`   • fix: ${state.gitHooks.fixCommand}`);
+    }
+  }
+
   if (state.frameworkIgnored && state.frameworkIgnored.ignored) {
     console.log(statusLine(
       '.gitignore',

package/src/utils/__tests__/githooks-active.test.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Fixture-driven test for the git-hooks active-vs-expected decision.
+ *
+ * Run: node src/utils/__tests__/githooks-active.test.js
+ * Exits 0 on success, 1 on any mismatch (CI-friendly).
+ *
+ * `isActiveServing` is the one decision that, if wrong, silently invalidates
+ * the entire git-hooks health check (src/utils/githooks.js). It is pure (path
+ * logic only) so it is fully unit-testable without a live repo — covering the
+ * husky-version branches that fs/git probing can't easily exercise.
+ */
+const path = require('path');
+const { isActiveServing } = require('../githooks');
+
+// Absolute roots so the fixtures don't depend on cwd. Normalize through
+// path.resolve the same way the implementation does.
+const ROOT = path.resolve('/repo');
+const j = (...p) => path.join(ROOT, ...p);
+
+const FIXTURES = [
+  // ─── the mayo bug: core.hooksPath=.git/hooks, hooks in scripts/git-hooks ──
+  { active: j('.git', 'hooks'), expected: j('scripts', 'git-hooks'), want: false, note: 'mayo: inactive' },
+
+  // ─── husky v9: active=.husky/_ wrappers, user hooks in .husky ─────────────
+  { active: j('.husky', '_'),   expected: j('.husky'),               want: true,  note: 'husky v9 nested' },
+  // ─── husky v5-v8: core.hooksPath=.husky, hooks in .husky ──────────────────
+  { active: j('.husky'),        expected: j('.husky'),               want: true,  note: 'husky v8 identical' },
+
+  // ─── scripts convention, correctly wired ─────────────────────────────────
+  { active: j('scripts', 'git-hooks'), expected: j('scripts', 'git-hooks'), want: true, note: 'scripts identical' },
+
+  // ─── .githooks convention, wired to default .git/hooks (inactive) ─────────
+  { active: j('.git', 'hooks'), expected: j('.githooks'),            want: false, note: '.githooks inactive' },
+
+  // ─── reverse nesting (expected within active) also counts as serving ──────
+  { active: j('.husky'),        expected: j('.husky', '_'),          want: true,  note: 'reverse nesting' },
+
+  // ─── sibling dirs sharing a prefix must NOT match (prefix-not-boundary) ───
+  { active: j('hooks'),         expected: j('hooks-extra'),          want: false, note: 'prefix not a path boundary' },
+
+  // ─── trailing-slash / non-normalized inputs normalize equal ──────────────
+  { active: j('.husky') + path.sep, expected: j('.husky'),           want: true,  note: 'trailing sep normalized' },
+];
+
+let failures = 0;
+for (const f of FIXTURES) {
+  const got = isActiveServing(f.active, f.expected);
+  const ok = got === f.want;
+  if (!ok) {
+    failures++;
+    console.error(`✗ ${f.note}: isActiveServing(${f.active}, ${f.expected}) = ${got}, expected ${f.want}`);
+  } else {
+    console.log(`✓ ${f.note}`);
+  }
+}
+
+if (failures) {
+  console.error(`\n${failures} failure(s).`);
+  process.exit(1);
+}
+console.log(`\nAll ${FIXTURES.length} fixtures passed.`);
+process.exit(0);

package/src/utils/githooks.js

@@ -0,0 +1,233 @@
+/**
+ * Git-hooks health check — **assert-active**, not read-only.
+ *
+ * NOT to be confused with `src/utils/hooks.js`: that module manages the Claude
+ * Code hooks registered in `.claude/settings.json`. THIS module inspects the
+ * repo's own *git* hooks (pre-commit, pre-push, …) and asserts they are
+ * actually being executed by git — i.e. that `core.hooksPath` resolves to the
+ * directory where the repo's versioned hooks live.
+ *
+ * **Why it exists** (since v3.34.0)
+ *
+ * A consumer had `core.hooksPath` pointing at `.git/hooks` (empty) while the
+ * repo's real, versioned hooks lived in `scripts/git-hooks/`. Result: the
+ * pre-commit schema guard and pre-push were silently inactive for days, and
+ * the worktree-manager verify step (`git config core.hooksPath || true`) only
+ * *read* the value without asserting anything — so it never caught the drift.
+ * Same class as the LSP bug: the framework "verifies" by reading a proxy
+ * instead of asserting the real state. This moves it from read-only to
+ * assert-active.
+ *
+ * **Resolution of the active hooks dir** (the crux)
+ *
+ * `git rev-parse --git-path hooks` is NOT used: empirically it returns the
+ * configured value *relative and unresolved*, and historically some git
+ * versions ignored `core.hooksPath` for `--git-path` entirely. Instead we
+ * resolve explicitly:
+ *   - `core.hooksPath` set      → relative resolves against the working-tree
+ *                                 top (`git rev-parse --show-toplevel`),
+ *                                 absolute is used verbatim.
+ *   - `core.hooksPath` unset    → `<git rev-parse --git-dir>/hooks` (handles
+ *                                 the worktree case where `.git` is a file).
+ *
+ * **Design invariants**
+ *
+ *   - Fail-safe: every probe is wrapped; any internal error yields
+ *     `{ checked: false, ok: true }` so the check NEVER blocks legitimate work
+ *     and never produces a false WARN.
+ *   - Silent when nothing to assert: a repo with no versioned-hooks directory
+ *     returns `checked: false` (most consumers have no managed hooks).
+ *   - No config flag: this is a universal, always-on health check auto-detected
+ *     from the filesystem, so the schema-change-propagation rule does not apply.
+ *   - WARN only: this module never mutates `core.hooksPath`. It reports a
+ *     `fixCommand` string; applying it is the caller's (user's) decision.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// Standard git hook filenames. A managed-hooks directory is recognized by
+// containing at least one of these (husky places them at `.husky/<name>`,
+// raw dirs at `<dir>/<name>`).
+const STANDARD_HOOKS = [
+  'pre-commit', 'pre-push', 'commit-msg', 'prepare-commit-msg',
+  'pre-rebase', 'pre-merge-commit', 'post-checkout', 'post-commit',
+  'post-merge', 'post-rewrite', 'pre-applypatch', 'applypatch-msg',
+];
+
+// Candidate versioned-hooks directories, in priority order. The first that
+// exists AND contains a standard-named hook wins. `scripts/git-hooks` and
+// `githooks` are conventions (not universal) — we enumerate a small known set
+// rather than guess.
+const MANAGED_DIRS = [
+  { dir: '.husky',            source: 'husky' },
+  { dir: '.githooks',         source: 'githooks' },
+  { dir: 'scripts/git-hooks', source: 'scripts' },
+  { dir: 'githooks',          source: 'githooks' },
+];
+
+function git(cwd, args) {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+}
+
+/**
+ * Find the repo's versioned-hooks directory, or null when none is managed.
+ * @returns {{ dir: string, abs: string, source: string, hooks: string[] } | null}
+ */
+function detectExpected(cwd) {
+  for (const cand of MANAGED_DIRS) {
+    const abs = path.join(cwd, cand.dir);
+    let names = [];
+    try {
+      if (!fs.statSync(abs).isDirectory()) continue;
+      names = fs.readdirSync(abs).filter((f) => STANDARD_HOOKS.includes(f));
+    } catch (_) { continue; }
+    if (names.length) return { dir: cand.dir, abs, source: cand.source, hooks: names };
+  }
+  return null;
+}
+
+/**
+ * Resolve the directory git will actually look in for hooks.
+ * @returns {{ configured: string | null, abs: string }}
+ */
+function resolveActiveDir(cwd) {
+  let configured = null;
+  try { configured = git(cwd, ['config', '--get', 'core.hooksPath']) || null; } catch (_) {}
+
+  if (configured) {
+    if (path.isAbsolute(configured)) return { configured, abs: configured };
+    // Relative core.hooksPath resolves against the working-tree top, not cwd.
+    let top = cwd;
+    try { top = git(cwd, ['rev-parse', '--show-toplevel']); } catch (_) {}
+    return { configured, abs: path.resolve(top, configured) };
+  }
+
+  // Unset → <git-dir>/hooks. git-dir may be relative or a worktree gitdir.
+  let gitDir;
+  try { gitDir = git(cwd, ['rev-parse', '--git-dir']); } catch (_) { gitDir = path.join(cwd, '.git'); }
+  if (!path.isAbsolute(gitDir)) gitDir = path.resolve(cwd, gitDir);
+  return { configured: null, abs: path.join(gitDir, 'hooks') };
+}
+
+/**
+ * Resolve a path to its canonical (symlink-free) form so two paths computed
+ * from different bases compare correctly. The active dir (from git's
+ * realpath-resolved toplevel/git-dir) and the expected dir (from cwd) can
+ * otherwise differ purely by a symlinked ancestor — e.g. macOS `/var` →
+ * `/private/var`, or a symlinked repo/home path — yielding a false INACTIVE.
+ *
+ * Handles non-existent leaves (the active `.git/hooks` may not exist on a
+ * misconfigured repo): realpath the deepest existing ancestor, re-append the
+ * rest. Falls back to a plain resolve if nothing along the path is realpath-able.
+ */
+function canonicalize(p) {
+  let dir = path.resolve(p);
+  const tail = [];
+  for (;;) {
+    try {
+      const real = fs.realpathSync(dir);
+      return tail.length ? path.join(real, ...tail) : real;
+    } catch (_) {
+      const parent = path.dirname(dir);
+      if (parent === dir) return path.resolve(p); // reached fs root
+      tail.unshift(path.basename(dir));
+      dir = parent;
+    }
+  }
+}
+
+/**
+ * PURE decision: is the active hooks dir serving the versioned hooks?
+ *
+ * True when the two dirs are identical OR one is nested within the other.
+ * The nesting case covers husky v9, which sets `core.hooksPath=.husky/_`
+ * (wrappers) while the user hooks live in `.husky/`. Exported for unit tests —
+ * this is the one decision that, if wrong, silently invalidates the whole check.
+ */
+function isActiveServing(activeAbs, expectedAbs) {
+  const a = path.resolve(activeAbs);
+  const e = path.resolve(expectedAbs);
+  if (a === e) return true;
+  return a.startsWith(e + path.sep) || e.startsWith(a + path.sep);
+}
+
+/**
+ * Inspect the repo's git-hooks health. Fail-safe.
+ * @returns {{
+ *   checked: boolean, ok: boolean, source: string|null, configured: string|null,
+ *   activeDir: string|null, expectedDir: string|null, expectedHooks: string[],
+ *   inactive: boolean, nonExecutable: string[], detail: string, fixCommand: string|null
+ * }}
+ */
+function getStatus(cwd = process.cwd()) {
+  const result = {
+    checked: false,
+    ok: true,
+    source: null,
+    configured: null,
+    activeDir: null,
+    expectedDir: null,
+    expectedHooks: [],
+    inactive: false,
+    nonExecutable: [],
+    detail: '',
+    fixCommand: null,
+  };
+
+  try {
+    const expected = detectExpected(cwd);
+    if (!expected) return result; // no managed hooks → silent, ok
+
+    const active = resolveActiveDir(cwd);
+    result.checked = true;
+    result.source = expected.source;
+    result.configured = active.configured;
+    result.activeDir = active.abs;
+    result.expectedDir = expected.dir;
+    result.expectedHooks = expected.hooks;
+
+    // Canonicalize both ends before comparing — they're computed from different
+    // bases (git realpath vs cwd) and a symlinked ancestor would otherwise
+    // produce a false INACTIVE.
+    if (!isActiveServing(canonicalize(active.abs), canonicalize(expected.abs))) {
+      result.inactive = true;
+      result.ok = false;
+      result.fixCommand = `git config core.hooksPath ${expected.dir}`;
+      result.detail = `core.hooksPath risolve a ${active.abs} ma gli hook versionati sono in ${expected.dir}`;
+      return result;
+    }
+
+    // Executability assert — only for raw dirs git execs directly. Husky sources
+    // user hooks via its `_` wrappers and v9 does NOT require them to be +x, so
+    // asserting -x there would manufacture false positives.
+    if (expected.source !== 'husky') {
+      for (const h of expected.hooks) {
+        try { fs.accessSync(path.join(expected.abs, h), fs.constants.X_OK); }
+        catch (_) { result.nonExecutable.push(h); }
+      }
+      if (result.nonExecutable.length) {
+        result.ok = false;
+        result.detail = `hook non eseguibili (manca il bit -x): ${result.nonExecutable.join(', ')}`;
+        result.fixCommand = `chmod +x ${result.nonExecutable.map((h) => path.join(expected.dir, h)).join(' ')}`;
+      }
+    }
+
+    return result;
+  } catch (_) {
+    // Never block doctor / worktree verify on a probe failure.
+    return { ...result, checked: false, ok: true };
+  }
+}
+
+module.exports = { getStatus, isActiveServing };
+// Exposed for completeness / advanced callers and unit tests.
+module.exports.detectExpected = detectExpected;
+module.exports.resolveActiveDir = resolveActiveDir;
+module.exports.STANDARD_HOOKS = STANDARD_HOOKS;
+module.exports.MANAGED_DIRS = MANAGED_DIRS;