@vodmal/vdx-cli 0.21.1 → 0.22.0

package/README.md

@@ -26,8 +26,9 @@ ephemeral environment.
 
 **First command after install: `vdx doctor`** — it inspects your environment
 (Node version, `vdx` on PATH, git, mise, npm auth, container runtime, Claude
-Code plugin; in a project — git hooks and the commit author) and points to remedies for everything that's missing or
-sub-optimal.
+Code plugin; in a project — whether its git hooks are on in this clone, and the
+commit author; with a profile — whether your personal hooks run on this machine)
+and points to remedies for everything that's missing or sub-optimal.
 
 ## Use
 
@@ -44,8 +45,10 @@ vdx init  [project-path] [--baseline github.com/org/repo@vX.Y] [--stack <id>] [-
 # Publish a library (Node MVP; PHP/Python coming in Y.3)
 vdx publish <patch|minor|major> [--dry-run] [--force] [--no-push]
 
-# Environment self-check (Node / git / mise / npm auth / docker / Claude Code plugin)
-vdx doctor [--format=ansi|markdown|json]
+# Environment self-check (Node / git / mise / npm auth / docker / Claude Code plugin; git hooks of the project)
+vdx doctor [project-path] [--format=ansi|markdown|json]   # default: cwd
+vdx doctor --check [project-path]   # one line per hook declared but not running here — the plugin's SessionStart hook tells the agent
+vdx doctor --fix                    # write the profile's personal hooks (git.hooks) into ~/.gitconfig
 
 # Start your agent in a project per your profile (~/.vdx-environment.yaml or $VDX_ENVIRONMENT)
 vdx ai[@host] [project-path] [--new | --conversation <id>] [--restart] [--detach] [--dry-run]   # default: cwd; @host: over ssh, in tmux there
@@ -123,9 +126,14 @@ npm run typecheck
 - `src/rubric.ts`     — types + YAML loader
 - `src/manifest.ts`   — parser for `[vdx]` block in `mise.toml` + `.vdx-overrides.yml`
 - `src/facts.ts`      — fact source loaders (tasks, packages, configs, sub-package detection)
-- `src/predicates.ts` — predicate registry (11 functions)
+- `src/predicates.ts` — predicate registry; true / false / unknown with a reason (schema 0.3)
 - `src/evaluator.ts`  — recursive evaluator + sugar notation
-- `src/scoring.ts`    — delta-style levels, flags for orthogonal axes
+- `src/scoring.ts`    — delta-style levels, `not_required` levels, flags for orthogonal axes
+- `src/gha.ts`        — GitHub Actions workflows as the `ci` axis reads them
+- `src/vocabulary.ts` — which project tasks a command calls through the project's runner
+- `src/hooks.ts`      — one recognizer of hook frameworks for audit and doctor
+- `src/clone-checks.ts` — clone checks printed by doctor and next to an axis in audit
+- `src/personal-hooks.ts` — the profile's personal hooks in ~/.gitconfig: check and `--fix`
 - `src/audit.ts`      — orchestrator: overrides + applies_to filter + subpackage-ctx
 - `src/init.ts`       — `vdx init` planner (`selectVerbTask` + mise.toml renderer)
 - `src/run.ts`        — `resolveLifecycleVerb` + error renderer (pure logic for `vdx <verb>`)
@@ -139,7 +147,9 @@ npm run typecheck
 
 ## Not implemented yet
 
-- `command_succeeds` predicate is a stub (warning at evaluation).
+- Above L1 the `ci` axis reads GitHub Actions only; other CI systems answer
+  "unknown". `branch-protection` is "unknown" everywhere until a hosting
+  extension exists.
 - Baseline loading from a git ref is documented but evaluator still reads file
   paths only — `baseline:` in `mise.toml` is recorded but does not auto-fetch.
 - Watermark drift (phase 2 of `drift-algorithm.md`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vodmal/vdx-cli",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "vdx — unified lifecycle interface (up/down/build/test/check/fix) + versioned maturity audit with drift detection. Pairs with the vdx Claude Code plugin.",
   "keywords": [
     "vdx",

package/rubric/vdx-rubric.yaml

@@ -7,11 +7,11 @@
 # дельту относительно L(N-1). Уровень оси = max L, для которого истинны
 # requires(L1), ..., requires(L) подряд (без разрывов).
 
-schema_version: "0.2"
+schema_version: "0.3"
 
 metadata:
   name: vdx-rubric-vodmal
-  version: "0.7.0"
+  version: "1.0.0"
   description: "Personal maturity rubric for multi-stack projects (vodmal)"
   owner: vodmal
   homepage: "https://github.com/vodmal/vdx-rubric"
@@ -24,8 +24,8 @@ levels:
   L0: { name: chaos,        description: "Не поднимается, знание в голове" }
   L1: { name: reproducible, description: "Поднимается одной задокументированной командой" }
   L2: { name: testable,     description: "Тесты есть; единый словарь up/test/build" }
-  L3: { name: gated,        description: "Статанализ + стиль + CI-гейты на PR (реальные!)" }
-  L4: { name: exemplar,     description: "Полная глубина: хуки, mock-инфра, observability, версионированная общая инфра" }
+  L3: { name: gated,        description: "Статанализ + стиль; CI зовёт словарь проекта; main на хостинге принимает только проверенное" }
+  L4: { name: exemplar,     description: "Полная глубина: хуки повторяют CI, mock-инфра, observability, версионированная общая инфра" }
 
 axes:
 
@@ -183,13 +183,15 @@ axes:
 
   - id: ci
     class: critical
-    description: "Реальное гейтование PR (no `|| true`!)"
+    description: "Сигнал: тесты на каждый push в основную ветку, падение не замаскировано. Гейт до слияния — ось branch-protection"
     storage: level
     default_target: L4
     fact_sources:
       - .github/workflows/
       - .gitlab-ci.yml
       - .circleci/config.yml
+    # Выше L1 vdx читает только GitHub Actions; у прочих CI-систем L2+ —
+    # «неизвестно», в общем уровне это «не выполнено».
     levels:
       L1:
         requires:
@@ -197,28 +199,45 @@ axes:
             - has_file: .github/workflows
             - has_file: .gitlab-ci.yml
             - has_file: .circleci/config.yml
+      # Тесты на push в main/master (фильтр веток или без него). Шаг с `|| true`
+      # или continue-on-error не засчитывается. Только PR-триггер — тоже: в репо
+      # с пушами в main такой CI не запускается никогда.
       L2:
         requires:
-          any_of:
-            - file_contains:
-                paths: [.github/workflows/*.yml, .gitlab-ci.yml]
-                pattern: "(phpstan|phpunit|composer test|npm test|jest|pytest)"
+          gha_tests_on_push:
+            pattern: "\\b(phpunit|pest|composer test|npm test|npm run test|yarn test|pnpm test|jest|vitest|pytest|go test|cargo test|mocha|mix test|rspec|vdx test|mise run test)\\b"
+      # Паритет: CI вызывает задачи проекта check и test (или check:* / test:*)
+      # через его раннер — то же, что человек и агент запускают локально.
       L3:
         requires:
-          all_of:
-            - any_of:
-                - gh_workflow_blocks_pr: {}
-                - file_contains: { path: .gitlab-ci.yml, pattern: "rules:.+merge_request" }
-            - not:
-                file_contains:
-                  paths: [.github/workflows/*.yml, .gitlab-ci.yml]
-                  pattern: "\\|\\| true"
+          gha_runs_tasks: { tasks: [check, test] }
+      # Ширина или конвейер: проверяющая задача идёт по matrix, либо всё, что CI
+      # выкладывает или выпускает (deploy/release/publish), ждёт её через needs:.
       L4:
         requires:
           any_of:
-            - file_contains: { path: .github/workflows/*.yml, pattern: "matrix:" }
-            - file_contains: { path: .github/workflows/*.yml, pattern: "sentry-release|action-release" }
-            - gh_workflow_blocks_pr: { check_name: "deploy" }
+            - gha_test_matrix:
+                pattern: "\\b(phpunit|pest|composer test|npm test|npm run test|yarn test|pnpm test|jest|vitest|pytest|go test|cargo test|mocha|mix test|rspec|vdx test|mise run test)\\b"
+            - gha_ship_needs_checks:
+                pattern: "\\b(phpunit|pest|composer test|npm test|npm run test|yarn test|pnpm test|jest|vitest|pytest|go test|cargo test|mocha|mix test|rspec|vdx test|mise run test)\\b"
+
+  - id: branch-protection
+    class: critical
+    description: "Основная ветка на хостинге принимает изменения только после обязательной проверки"
+    storage: level
+    default_target: L4
+    fact_sources: [hosting API]
+    # Гейт — свойство L3 общей лестницы; ниже ось ничего не требует и уровень
+    # не ограничивает. Знает о защите только хостинг: пока расширения для него
+    # нет, L3 — «неизвестно» у всех. L4 — позже: force-push, удаление ветки,
+    # ревью (как Branch-Protection у Scorecard).
+    levels:
+      L1: { not_required: true }
+      L2: { not_required: true }
+      L3:
+        requires:
+          branch_requires_checks: {}
+      L4: { not_required: true }
 
   # =========================================================================
   # SUPPORTING
@@ -364,32 +383,36 @@ axes:
 
   - id: git-hygiene
     class: supporting
+    description: "Хуки репозитория: ставятся сами, зовут словарь проекта, повторяют проверки CI"
     storage: level
     default_target: L4
-    fact_sources: [.husky/, .lefthook.yml, lefthook.yml, composer.json, package.json]
+    fact_sources: [.gitignore, .husky/, lefthook.yml, .lefthook.yml, .githooks/, package.json, composer.json, mise.toml]
+    # Включены ли хуки в этом клоне — пометка рядом с осью в `vdx audit` и строка
+    # `vdx doctor`; уровень не меняет: тот же репо и тот же тег дают тот же отчёт
+    # в любом клоне.
+    clone_check: git-hooks
     levels:
       L1:
         requires:
           has_file: .gitignore
+      # Репо ставит свои хуки сам на обычной установке: husky в prepare/postinstall
+      # (под Yarn 2+ — только postinstall), пакеты lefthook / simple-git-hooks,
+      # `cghooks add` в post-install-cmd, `git config core.hooksPath` в шаге
+      # установки или в задаче up. Объявленный, но не ставящийся сам — не L2.
       L2:
         requires:
-          any_of:
-            - has_file: .husky
-            - has_file: .lefthook.yml
-            - has_file: lefthook.yml
-            - package_present: { name: brainmaestro/composer-git-hooks, ecosystem: composer }
-            - package_present: { name: husky, ecosystem: npm }
+          git_hooks_arranged: {}
+      # pre-commit или pre-push зовёт задачу словаря (test, check, check:*, test:*)
+      # через раннер проекта.
       L3:
         requires:
-          any_of:
-            - file_contains: { path: composer.json, pattern: "\"pre-push\"" }
-            - file_contains: { paths: [.lefthook.yml, lefthook.yml], pattern: "pre-push:" }
-            - has_file: .husky/pre-push
+          git_hook_runs_task: { tasks: [test, check] }
+      # pre-push вызывает все задачи словаря, которые вызывает CI на push в main
+      # (@-ссылки composer и npm run раскрываются): пуш, прошедший хук, не падает
+      # в CI на проверках.
       L4:
         requires:
-          any_of:
-            - file_contains: { path: composer.json, pattern: "\"(post-commit|commit-msg|post-merge)\"" }
-            - file_contains: { paths: [.lefthook.yml, lefthook.yml], pattern: "(post-commit|commit-msg|post-merge):" }
+          git_hook_covers_ci: { tasks: [test, check] }
 
   - id: observability
     class: supporting

package/src/ai.ts

@@ -4,6 +4,7 @@ import * as path from 'node:path';
 import { execFileSync, spawnSync } from 'node:child_process';
 import YAML from 'js-yaml';
 import { evalPredicate } from './evaluator.ts';
+import { GIT_HOOK_EVENTS } from './hooks.ts';
 import { autoDetectStack, readStructured, resolveConfigPath, type Ctx } from './facts.ts';
 import { loadManifest } from './manifest.ts';
 import { type Author, effectiveAuthor, isGitRepo, rankAuthors, scanPool, writeAuthor } from './author.ts';
@@ -83,9 +84,26 @@ export interface SessionProfile {
   machines?: string[];
 }
 
+/**
+ * A personal hook: the owner's own gate, kept in git's user config
+ * (`hook.<name>.event` / `.command`, Git 2.54) instead of in every repository.
+ * `vdx doctor` checks it is there, `vdx doctor --fix` writes it.
+ */
+export interface PersonalHook {
+  name: string;
+  /** Git hook event(s): `pre-commit`, … */
+  event: string | string[];
+  /** Run by git through the shell; `$HOME` and quotes work as in a hook script. */
+  command: string;
+  /** The hook applies on a machine where this path exists (the tool is installed); `~` is home. */
+  when_exists?: string;
+  description?: string;
+}
+
 export interface GitProfile {
   /** Directories whose repos are the neighbours an author is proposed from; default — the project's parent. */
   author_pool?: string[];
+  hooks?: PersonalHook[];
 }
 
 export interface Environment {
@@ -202,6 +220,27 @@ export function parseEnvironment(text: string, source: string): Environment {
     if (gitDoc.author_pool !== undefined && !isStringList(gitDoc.author_pool)) {
       fail('git.author_pool', 'must be a list of directories');
     }
+    if (gitDoc.hooks !== undefined) {
+      if (!Array.isArray(gitDoc.hooks)) fail('git.hooks', 'must be a list');
+      const names = new Set<string>();
+      gitDoc.hooks.forEach((h, i) => {
+        const at = `git.hooks[${i}]`;
+        if (typeof h !== 'object' || h === null) fail(at, 'must be a mapping');
+        if (typeof h.name !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(h.name)) {
+          fail(`${at}.name`, 'must be a name of letters, digits, . _ - (the git config subsection)');
+        }
+        if (names.has(h.name)) fail(`${at}.name`, `"${h.name}" is declared twice`);
+        names.add(h.name);
+        const events = Array.isArray(h.event) ? h.event : [h.event];
+        if (events.length === 0 || !events.every((e) => typeof e === 'string' && GIT_HOOK_EVENTS.has(e))) {
+          fail(`${at}.event`, 'must be a git hook event (pre-commit, pre-push, …) or a list of them');
+        }
+        if (typeof h.command !== 'string' || h.command.trim() === '') fail(`${at}.command`, 'must be a non-empty string');
+        if (h.when_exists !== undefined && (typeof h.when_exists !== 'string' || h.when_exists === '')) {
+          fail(`${at}.when_exists`, 'must be a path');
+        }
+      });
+    }
   }
   return envDoc;
 }

package/src/audit.ts

@@ -4,7 +4,8 @@ import type { Rubric, LevelName } from './rubric.ts';
 import { findSubPackages, stackForDir, type Ctx } from './facts.ts';
 import { evalPredicate } from './evaluator.ts';
 import type { Override, VdxManifest } from './manifest.ts';
-import { evalAxis, projectLevel, type AxisResult } from './scoring.ts';
+import { evalAxisDetailed, projectLevel, type AxisResult } from './scoring.ts';
+import { cloneCheck } from './clone-checks.ts';
 
 function levelToInt(L: LevelName): number {
   return parseInt(L.slice(1), 10);
@@ -126,7 +127,7 @@ export function audit(
       });
       continue;
     }
-    const achieved = evalAxis(axis, evalCtx);
+    const { achieved, not_required, unknown } = evalAxisDetailed(axis, evalCtx);
     const ov = overrideByAxis.get(axis.id);
     const target = (ov?.target as LevelName) ?? axis.default_target;
     const drift: 'aligned' | 'gap' | 'over' =
@@ -143,6 +144,12 @@ export function audit(
       drift_kind: drift,
     };
     if (ov?.target) entry.override_target = ov.target as LevelName;
+    if (not_required) entry.not_required = not_required;
+    if (unknown) entry.unknown = unknown;
+    if (axis.clone_check) {
+      const c = cloneCheck(axis.clone_check, ctx.projectRoot);
+      if (c && c.status !== 'ok') entry.note = c.remedy ? `${c.message} → ${c.remedy}` : c.message;
+    }
     perAxis.push(entry);
   }
 

package/src/clone-checks.ts

@@ -0,0 +1,166 @@
+/**
+ * Checks of this clone that both `vdx doctor` (a row) and `vdx audit` (a note
+ * next to the axis that names it in `clone_check`) print — one check, two
+ * surfaces, so they cannot disagree.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import type { CheckResult } from './doctor.ts';
+import {
+  cloneHookStates,
+  detectHookFrameworks,
+  effectiveHooksDir,
+  missingMachinePaths,
+  unsetGatingVars,
+} from './hooks.ts';
+import { autoDetectStack, type Ctx } from './facts.ts';
+
+function gitConfig(root: string, key: string): string | null {
+  try {
+    const out = execFileSync('git', ['-C', root, 'config', '--get', key], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+function isGitWorkTree(root: string): boolean {
+  return fs.existsSync(path.join(root, '.git'));
+}
+
+function executableHooks(dir: string): Map<string, string> {
+  const out = new Map<string, string>();
+  let names: string[] = [];
+  try {
+    names = fs.readdirSync(dir).filter((f) => !f.startsWith('.') && !f.endsWith('.sample'));
+  } catch {
+    return out;
+  }
+  for (const f of names) {
+    const file = path.join(dir, f);
+    try {
+      fs.accessSync(file, fs.constants.X_OK);
+      if (fs.statSync(file).isFile()) out.set(f, fs.readFileSync(file, 'utf8'));
+    } catch {
+      /* not executable — git skips it silently */
+    }
+  }
+  return out;
+}
+
+/**
+ * Git hooks: declared vs actually running in this clone.
+ *
+ * A framework leaves two separable traces: files in the repository (tracked,
+ * the same for every clone) and activation in the clone (`core.hooksPath`, or
+ * hooks written into the git hooks directory). The first says nothing about
+ * the second, and a hook that is declared but off fails exactly like success —
+ * nothing is printed, the commit goes through. So does a hook gated on a
+ * variable nobody set, or one that calls a path missing on this machine.
+ *
+ * Null (no row) when the repo declares no hooks — there is nothing to be wrong about.
+ */
+export function checkRepoHooks(root: string | null): CheckResult | null {
+  if (root === null || !isGitWorkTree(root)) return null;
+  const id = 'git-hooks';
+  const label = 'git hooks';
+  const ctx: Ctx = { projectRoot: root, stack: autoDetectStack(root), cache: new Map() };
+  const frameworks = detectHookFrameworks(ctx);
+  const hooksPath = gitConfig(root, 'core.hooksPath');
+
+  if (frameworks.length === 0) {
+    if (hooksPath === null) return null;
+    // Hooks in a directory no framework owns: read what is there.
+    const dir = path.resolve(root, hooksPath);
+    if (!fs.existsSync(dir)) {
+      return {
+        id,
+        label,
+        status: 'missing',
+        message: `core.hooksPath=${hooksPath} but that directory does not exist`,
+        remedy: `git -C ${root} config --unset core.hooksPath, or create ${hooksPath}/`,
+      };
+    }
+    const hooks = executableHooks(dir);
+    if (hooks.size === 0) {
+      return {
+        id,
+        label,
+        status: 'warning',
+        message: `core.hooksPath=${hooksPath} but it holds no executable hook`,
+        remedy: `chmod +x ${hooksPath}/*`,
+      };
+    }
+    return bodyProblems(id, label, [...hooks.values()]) ?? {
+      id,
+      label,
+      status: 'ok',
+      message: `${hooks.size} hook(s) active via ${hooksPath}`,
+    };
+  }
+
+  const states = cloneHookStates(root, ctx, frameworks);
+  const off = states.filter((s) => !s.enabled);
+  if (off.length > 0) {
+    return {
+      id,
+      label,
+      status: 'warning',
+      message: off.map((s) => `${s.framework.id} (${s.framework.declaredIn}): ${s.problem} — those hooks never run`).join('; '),
+      ...(off[0]!.remedy ? { remedy: off[0]!.remedy } : {}),
+    };
+  }
+
+  const commands = frameworks.flatMap((f) => [...f.hooks.values()].flat());
+  const problem = bodyProblems(id, label, commands);
+  if (problem) return problem;
+
+  const dir = effectiveHooksDir(root);
+  const where = dir ? path.relative(root, dir) || dir : 'the hooks directory';
+  const count = frameworks.reduce((n, f) => n + f.hooks.size, 0);
+  return {
+    id,
+    label,
+    status: 'ok',
+    message: `${frameworks.map((f) => f.id).join(', ')}: ${count} hook(s) active in ${where}`,
+  };
+}
+
+/** A body that looks installed but does nothing here: gated on an unset variable, or calling a missing path. */
+function bodyProblems(id: string, label: string, bodies: string[]): CheckResult | null {
+  const unset = unsetGatingVars(bodies);
+  if (unset.length > 0) {
+    return {
+      id,
+      label,
+      status: 'warning',
+      message: `hooks gated on unset ${unset.join(', ')} — those gates are no-ops`,
+      remedy: `export ${unset[0]}=... in your shell profile (see the tool that ships the hook)`,
+    };
+  }
+  const missing = missingMachinePaths(bodies);
+  if (missing.length > 0) {
+    return {
+      id,
+      label,
+      status: 'warning',
+      message: `hooks call ${missing.join(', ')} — not on this machine, the commit fails or the gate is skipped`,
+      remedy: 'install what the hook calls here, or move the hook out of the repository (a personal hook in git config)',
+    };
+  }
+  return null;
+}
+
+/** The checks an axis may name in `clone_check`. */
+export function cloneCheck(name: 'git-hooks', root: string): CheckResult | null {
+  switch (name) {
+    case 'git-hooks':
+      return checkRepoHooks(root);
+    default:
+      return null;
+  }
+}

package/src/doctor.ts

@@ -5,6 +5,8 @@ import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { effectiveAuthor, isGitRepo, rankAuthors, scanPool } from './author.ts';
 import { authorPoolDirs, loadEnvironment, resolveEnvironmentPath, shellQuote, type Environment } from './ai.ts';
+import { checkRepoHooks } from './clone-checks.ts';
+import { checkPersonalHooks, defaultPersonalHookDeps, fixPersonalHooks, type PersonalHookDeps } from './personal-hooks.ts';
 
 export type CheckStatus = 'ok' | 'warning' | 'missing';
 
@@ -380,134 +382,6 @@ export function checkClaudeCodePlugin(
   return { ...base, status: 'ok', message: label };
 }
 
-/**
- * Variables a hook body *gates on*: `[ -n "${VAR:-}" ]`, `[ -x "$VAR" ]` and
- * friends. Restricted to test-expression positions on purpose — a bare `$VAR`
- * anywhere in a script says nothing about whether the hook still does its job,
- * while an unset variable inside the guard means the guarded block never runs.
- */
-const GATING_VAR_RE =
-  /\[\s+-[nxfse]\s+"\$\{([A-Z][A-Z0-9_]*)(?::-[^}]*)?\}"|\[\s+-[nxfse]\s+"\$([A-Z][A-Z0-9_]*)"/g;
-
-/**
- * Git hooks: declared vs actually wired.
- *
- * A hook framework leaves two separable traces: files in the repository
- * (tracked, same for every clone) and activation in `.git/config` (per-clone,
- * never committed). Presence of the first says nothing about the second, and a
- * hook that is present but inert fails exactly like success — nothing is
- * printed, the commit goes through. Same for a hook whose body is gated on an
- * environment variable nobody set: the guard short-circuits and the gate is a
- * no-op.
- *
- * Returns null (row omitted) when the repo declares no hooks at all — there is
- * nothing to be wrong about.
- */
-function checkGitHooks(ctx: DoctorCtx): CheckResult | null {
-  const root = ctx.projectRoot;
-  if (root === null) return null;
-  if (!fs.existsSync(path.join(root, '.git'))) return null;
-
-  const id = 'git-hooks';
-  const label = 'git hooks';
-
-  let hooksPath: string | null = null;
-  try {
-    const out = execFileSync('git', ['-C', root, 'config', '--get', 'core.hooksPath'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    });
-    hooksPath = out.trim() || null;
-  } catch {
-    hooksPath = null;
-  }
-
-  // Directories a framework would have written into the repo.
-  const declaredDirs = ['.githooks', '.husky'].filter((d) =>
-    fs.existsSync(path.join(root, d)),
-  );
-
-  if (hooksPath === null) {
-    if (declaredDirs.length === 0) return null; // nothing declared — not applicable
-    return {
-      id,
-      label,
-      status: 'warning',
-      message: `${declaredDirs.join(', ')} present but core.hooksPath is unset — hooks never run`,
-      remedy: `git -C ${root} config core.hooksPath ${declaredDirs[0]}`,
-    };
-  }
-
-  const dir = path.resolve(root, hooksPath);
-  if (!fs.existsSync(dir)) {
-    return {
-      id,
-      label,
-      status: 'missing',
-      message: `core.hooksPath=${hooksPath} but that directory does not exist`,
-      remedy: `git -C ${root} config --unset core.hooksPath, or create ${hooksPath}/`,
-    };
-  }
-
-  let entries: string[] = [];
-  try {
-    entries = fs.readdirSync(dir).filter((f) => !f.startsWith('.') && !f.endsWith('.sample'));
-  } catch {
-    entries = [];
-  }
-  const executable = entries.filter((f) => {
-    try {
-      fs.accessSync(path.join(dir, f), fs.constants.X_OK);
-      return true;
-    } catch {
-      return false;
-    }
-  });
-
-  if (executable.length === 0) {
-    return {
-      id,
-      label,
-      status: 'warning',
-      message: `core.hooksPath=${hooksPath} but it holds no executable hook`,
-      remedy: `chmod +x ${hooksPath}/*`,
-    };
-  }
-
-  // A hook gated on an unset variable is inert while looking installed.
-  const unresolved = new Set<string>();
-  for (const f of executable) {
-    let body = '';
-    try {
-      body = fs.readFileSync(path.join(dir, f), 'utf8');
-    } catch {
-      continue;
-    }
-    for (const m of body.matchAll(GATING_VAR_RE)) {
-      const name = m[1] ?? m[2];
-      if (name && !process.env[name]) unresolved.add(name);
-    }
-  }
-
-  if (unresolved.size > 0) {
-    const names = [...unresolved].sort();
-    return {
-      id,
-      label,
-      status: 'warning',
-      message: `${executable.length} hook(s) via ${hooksPath}, but gated on unset ${names.join(', ')} — those gates are no-ops`,
-      remedy: `export ${names[0]}=... in your shell profile (see the tool that ships the hook)`,
-    };
-  }
-
-  return {
-    id,
-    label,
-    status: 'ok',
-    message: `${executable.length} hook(s) active via ${hooksPath}`,
-  };
-}
-
 /**
  * The project's commit author. With `user.useConfigOnly` git refuses to commit
  * in a repo that has none; the remedy names the likely one, as `vdx ai` does.
@@ -552,7 +426,8 @@ const CHECKS: Array<(ctx: DoctorCtx) => CheckResult | null> = [
   checkMise,
   checkNpmAuth,
   checkContainerRuntime,
-  checkGitHooks,
+  (ctx) => checkRepoHooks(ctx.projectRoot),
+  (ctx) => checkPersonalHooks(ctx.projectRoot),
   checkGitAuthor,
 ];
 
@@ -568,6 +443,37 @@ export function runDoctor(ctx: DoctorCtx = resolveDoctorCtx()): DoctorReport {
   return { cliVersion: readCliVersion(), checks, ok, warning, missing };
 }
 
+/**
+ * For the agent's own session (the vdx plugin's SessionStart hook): one line
+ * per hook that is declared but does not run — in this clone, or a personal
+ * hook on this machine. Nothing when they are in order; the fix is the user's
+ * call, so the line names it rather than applying it.
+ */
+export function runDoctorCheck(
+  ctx: DoctorCtx = resolveDoctorCtx(),
+  deps: PersonalHookDeps = defaultPersonalHookDeps(),
+): string {
+  const rows = [checkRepoHooks(ctx.projectRoot), checkPersonalHooks(ctx.projectRoot, deps)].filter(
+    (c): c is CheckResult => c !== null && c.status !== 'ok',
+  );
+  return rows
+    .map(
+      (c) =>
+        `vdx doctor: ${c.label} — ${c.message}.` +
+        (c.remedy ? ` Fix, on the user's word: \`${c.remedy}\`.` : ''),
+    )
+    .join('\n');
+}
+
+/**
+ * `vdx doctor --fix`: what doctor can put right without installing anything —
+ * the profile's personal hooks in ~/.gitconfig. Repository hooks are switched
+ * on by the project's own install step; doctor names it and leaves it to you.
+ */
+export function runDoctorFix(deps: PersonalHookDeps = defaultPersonalHookDeps()): string[] {
+  return fixPersonalHooks(deps);
+}
+
 const PROJECT_MARKER_FILES = [
   'package.json',
   'composer.json',