wize-dev-kit 0.26.1 → 0.27.2

package/tools/installer/commands/doctor.js

@@ -14,7 +14,12 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { loadProjectConfig, loadInstalledKitVersion } = require('./update.js');
 const { detectHarnessCli } = require('../baseline.js');
-const { getLatestVersion, semverGreater } = require('../version-check.js');
+const { getLatestNoWait } = require('../version-check.js');
+const { compareVersions, semverGreater, safePin } = require('../semver.js');
+const { gitContext, defaultBranch, trackedUnder } = require('../git-context.js');
+const { getProjectStatus, supportsHydrate } = require('../project-status.js');
+const { missingTargets } = require('../render-targets.js');
+const { ALIAS_PATHS, gitignoreBlockStatus } = require('../setup-helpers.js');
 
 function fileExists(p) { try { return fs.statSync(p).isFile(); } catch { return false; } }
 function dirExists(p)  { try { return fs.statSync(p).isDirectory(); } catch { return false; } }
@@ -72,12 +77,16 @@ function adapterTargetPath(targetCode, projectRoot) {
   }
 }
 
+// Adapters that emit into more than one directory.
+const EXTRA_ADAPTER_DIRS = { opencode: ['.opencode/commands'] };
+
 function countAdapterFiles(targetCode, projectRoot) {
   const dir = adapterTargetPath(targetCode, projectRoot);
-  if (!dir || !dirExists(dir)) return 0;
+  if (!dir) return 0;
+  const dirs = [dir, ...(EXTRA_ADAPTER_DIRS[targetCode] || []).map(d => path.join(projectRoot, d))];
   // Be permissive on file extension; .mdc, .md, .prompt, and SKILL.md dirs all count.
   let count = 0;
-  const stack = [dir];
+  const stack = dirs.filter(dirExists);
   while (stack.length) {
     const d = stack.pop();
     let entries; try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { continue; }
@@ -103,7 +112,7 @@ function detectPhase(projectRoot) {
       listFilesUnder(path.join(projectRoot, '.wize/solutioning/stories'), /\.md$/).length === 0)
     return '3-solutioning (stories pending)';
   if (!has('.wize/implementation/tea/risk-profile.md')) return '3-closeout (risk profile pending)';
-  if (!has('.wize/implementation/sprint-status.md')) return '4-implementation (sprint planning pending)';
+  if (!has('.wize/implementation/sprint-status.yaml') && !has('.wize/implementation/sprint-status.md')) return '4-implementation (sprint planning pending)';
   return '4-implementation';
 }
 
@@ -150,19 +159,39 @@ function knowledgeStatus(projectRoot) {
   return { exists: true, files: refreshed, pendingLines, toBeGeneratedMarkers, stateExists, stateAgeDays };
 }
 
+function readHeadFromFs(gitDir, commonDir) {
+  const HEAD = readSafe(path.join(gitDir, 'HEAD')).trim();
+  if (!HEAD) return { branch: null, head: null, detached: false };
+  if (!HEAD.startsWith('ref: ')) return { branch: null, head: HEAD.slice(0, 7), detached: true };
+  const ref = HEAD.slice(5).trim();
+  const branch = ref.replace(/^refs\/heads\//, '');
+  let sha = null;
+  for (const dir of [gitDir, commonDir].filter(Boolean)) {
+    const loose = readSafe(path.join(dir, ref)).trim();
+    if (loose) { sha = loose; break; }
+  }
+  return { branch, head: sha ? sha.slice(0, 7) : null, detached: false };
+}
+
+// Uses git when it works; a `.git` file or directory is enough to count as a
+// repository even when git itself cannot run (fake or broken `.git`).
 function gitInfo(projectRoot) {
-  const dotGit = path.join(projectRoot, '.git');
-  if (!dirExists(dotGit)) return { isRepo: false };
-  let branch = '?'; let head = '?';
-  try {
-    const HEAD = readSafe(path.join(dotGit, 'HEAD')).trim();
-    if (HEAD.startsWith('ref: ')) {
-      branch = HEAD.slice(5).replace('refs/heads/', '');
-    } else {
-      head = HEAD.slice(0, 7);
-    }
-  } catch (_) {}
-  return { isRepo: true, branch, head };
+  const ctx = gitContext(projectRoot);
+  if (!ctx.isRepo) return { isRepo: false };
+  let { branch, head, detached } = ctx;
+  if (!branch && !head && ctx.gitDir) {
+    const fromFs = readHeadFromFs(ctx.gitDir, ctx.commonDir);
+    branch = fromFs.branch; head = fromFs.head; detached = fromFs.detached;
+  }
+  return {
+    isRepo: true,
+    linked: !!ctx.linked,
+    primary: ctx.primary || null,
+    branch: branch || null,
+    detached: !!detached,
+    head: head || null,
+    defaultBranch: defaultBranch(projectRoot)
+  };
 }
 
 function severityIcon(level) {
@@ -170,7 +199,10 @@ function severityIcon(level) {
 }
 
 async function cmdDoctor({ kitRoot, projectRoot, opts = {} } = {}) {
-  const log = opts.log || console.log;
+  const json = !!opts.json;
+  const env = opts.env || process.env;
+  const out = opts.log || console.log;
+  const log = (m) => { if (!json) out(m); };
   const cwd = projectRoot;
   const cfg = loadProjectConfig(cwd);
   const installed = loadInstalledKitVersion(kitRoot);
@@ -181,25 +213,39 @@ async function cmdDoctor({ kitRoot, projectRoot, opts = {} } = {}) {
   const targets = (cfg.install && cfg.install.ide_targets) || [];
   const profiles = (cfg.install && cfg.install.profiles) || [];
   const harnesses = detectHarnessCli({ preferIde: targets });
+  const pin = (cfg.project && cfg.project.kit_version) || null;
 
-  // Try registry — best-effort, never blocks.
+  // Registry: cache only, never the network. WIZE_DISABLE_UPDATE_CHECK=1 skips it.
+  const updateCheckOff = env.WIZE_DISABLE_UPDATE_CHECK === '1';
   let registryLatest = null;
-  try { registryLatest = await getLatestVersion(); } catch (_) {}
+  if (!updateCheckOff) {
+    // Without a terminal (an agent running `doctor --json`) no background refresh is started.
+    const isTTY = opts.isTTY !== undefined ? opts.isTTY : process.stdout.isTTY;
+    const lookupEnv = isTTY ? env : { ...env, WIZE_NO_BG_REFRESH: '1' };
+    try { registryLatest = (opts.getLatestNoWait || getLatestNoWait)({ env: lookupEnv }) || null; } catch (_) { /* best effort */ }
+  }
 
+  const status = getProjectStatus({ kitRoot, cwd, latest: registryLatest, latestSource: 'cache', env });
   const suggestions = [];
+  const suggest = (level, text, command = null) => suggestions.push(command ? { level, text, command } : { level, text });
 
   // -- Section: Kit --
   log('');
   log('Wize Dev Kit — Doctor');
   log('─────────────────────');
   log(`Kit version (installed):   ${installed || '?'}`);
-  log(`Kit version (project):     ${cfg.project && cfg.project.kit_version || '— (no install)'}`);
-  log(`Kit version (registry):    ${registryLatest || '(offline or skipped)'}`);
-  if (installed && cfg.project && cfg.project.kit_version && installed !== cfg.project.kit_version) {
-    suggestions.push({ level: 'warn', text: `Project pinned to ${cfg.project.kit_version} but ${installed} is installed. Run \`npx wize-dev-kit update\` to refresh adapters.` });
+  log(`Kit version (project):     ${pin || '— (no install)'}`);
+  log(`Kit version (registry):    ${registryLatest || (updateCheckOff ? '(update check disabled)' : '(offline or skipped)')}`);
+  if (pin && installed) {
+    const cmp = compareVersions(pin, installed);
+    if (cmp < 0) {
+      suggest('warn', `Project pinned ${pin}, this kit is ${installed}. Run \`npx wize-dev-kit@latest update\` to converge.`, 'npx wize-dev-kit@latest update');
+    } else if (cmp > 0 && safePin(pin)) {
+      suggest('info', `Project pinned ${pin} is newer than this kit (${installed}). Use the pinned kit: \`npx --yes wize-dev-kit@${pin} doctor\`.`, `npx --yes wize-dev-kit@${pin} doctor`);
+    }
   }
   if (registryLatest && installed && semverGreater(registryLatest, installed)) {
-    suggestions.push({ level: 'info', text: `Registry has ${registryLatest}; you're on ${installed}. Run \`npx wize-dev-kit@latest update\` to pick it up.` });
+    suggest('info', `Registry has ${registryLatest}; you're on ${installed}. Run \`npx wize-dev-kit@latest update\` to pick it up.`, 'npx wize-dev-kit@latest update');
   }
 
   // -- Section: Project --
@@ -207,8 +253,13 @@ async function cmdDoctor({ kitRoot, projectRoot, opts = {} } = {}) {
   log('Project');
   log('───────');
   if (!cfg.project) {
-    log('No .wize/config/project.toml — kit is not installed here.');
-    suggestions.push({ level: 'error', text: 'Run `npx wize-dev-kit install` to set the kit up in this repo.' });
+    if (status.reason === 'kit-not-on-branch') {
+      log(`No .wize/config/project.toml on this branch — the kit is installed on ${status.kit_at}'s branch.`);
+      suggest('warn', `The kit is installed on ${status.kit_at}'s branch but not on this one (kit-not-on-branch). Merge the kit into this branch, or pass --here to install here.`);
+    } else {
+      log('No .wize/config/project.toml — kit is not installed here.');
+      suggest('error', 'Run `npx wize-dev-kit install` to set the kit up in this repo.', 'npx wize-dev-kit install');
+    }
   } else {
     log(`Name:                 ${cfg.project.name || '?'}`);
     log(`Profiles:             ${profiles.join(', ') || '(none)'}`);
@@ -218,7 +269,46 @@ async function cmdDoctor({ kitRoot, projectRoot, opts = {} } = {}) {
     log(`Current phase:        ${phase}`);
   }
 
+  // -- Section: Hydration --
+  let hydration = null;
+  if (cfg.project) {
+    const missing = status.missing_targets;
+    hydration = {
+      status: status.hydrated,
+      marker: status.marker_version,
+      pin: status.pin,
+      binary: installed,
+      user_toml: status.user_toml,
+      missing_targets: missing,
+      command: status.commands.hydrate
+    };
+    log('');
+    log('Hydration');
+    log('─────────');
+    log(`  status:     ${status.hydrated}`);
+    log(`  marker:     ${status.marker_version || '(none)'}`);
+    log(`  pin:        ${status.pin || '(none)'}`);
+    log(`  this kit:   ${installed || '?'}`);
+    log(`  user.toml:  ${status.user_toml}`);
+    for (const t of targets) log(`  ${t.padEnd(14)} ${missing.includes(t) ? '✖ not rendered' : '✓ rendered'}`);
+
+    const cmd = status.commands.hydrate;
+    if (status.hydrated === 'missing') {
+      suggest('error', `This checkout is not hydrated (not rendered: ${missing.join(', ')}). Run \`${cmd}\`.`, cmd);
+    } else if (status.hydrated === 'stale') {
+      suggest('error', `Rendered output is stale: marker says kit ${status.marker_version}, project pins ${status.pin}. Run \`${cmd}\`.`, cmd);
+    }
+    if (status.user_toml === 'missing' && status.hydrated === 'ok') {
+      if (supportsHydrate(status.pin)) {
+        suggest('error', `.wize/config/user.toml is missing in this checkout. Run \`${cmd}\`.`, cmd);
+      } else {
+        suggest('warn', '.wize/config/user.toml is missing in this checkout. Copy it from your primary checkout, or run `npx wize-dev-kit@latest update` to adopt hydrate.', 'npx wize-dev-kit@latest update');
+      }
+    }
+  }
+
   // -- Section: Adapters --
+  const adapters = [];
   if (cfg.install) {
     log('');
     log('IDE Adapters');
@@ -226,9 +316,33 @@ async function cmdDoctor({ kitRoot, projectRoot, opts = {} } = {}) {
     for (const t of targets) {
       const dir = adapterTargetPath(t, cwd);
       const count = countAdapterFiles(t, cwd);
-      const status = count > 0 ? `✓ ${count} files` : '✖ none';
-      log(`  ${t.padEnd(14)} ${status.padEnd(15)} ${dir ? path.relative(cwd, dir) : '(no path)'}`);
-      if (count === 0) suggestions.push({ level: 'warn', text: `Adapter "${t}" has no rendered files. Run \`npx wize-dev-kit sync\`.` });
+      const rendered = missingTargets(cwd, [t]).length === 0;
+      adapters.push({ target: t, files: count, rendered });
+      const label = rendered && count > 0 ? `✓ ${count} files` : count > 0 ? `✖ alias only` : '✖ none';
+      log(`  ${t.padEnd(14)} ${label.padEnd(15)} ${dir ? path.relative(cwd, dir) : '(no path)'}`);
+    }
+  }
+
+  // -- Section: Leaks (generated files that git would see) --
+  const leaks = { tracked_aliases: [], gitignore: null };
+  if (cfg.project && git.isRepo) {
+    leaks.tracked_aliases = trackedUnder(cwd, ALIAS_PATHS);
+    const giFile = path.join(cwd, '.gitignore');
+    leaks.gitignore = gitignoreBlockStatus(fs.existsSync(giFile) ? readSafe(giFile) : null);
+    log('');
+    log('Generated files and git');
+    log('───────────────────────');
+    log(`  tracked alias files:   ${leaks.tracked_aliases.length}`);
+    log(`  .gitignore block:      ${leaks.gitignore}`);
+    const fix = 'npx wize-dev-kit@latest update';
+    if (leaks.tracked_aliases.length) {
+      const shown = leaks.tracked_aliases.slice(0, 3).join(', ') + (leaks.tracked_aliases.length > 3 ? ', ...' : '');
+      suggest('warn', `${leaks.tracked_aliases.length} generated alias file(s) are tracked by git (${shown}). Run \`${fix}\` to untrack them.`, fix);
+    }
+    if (leaks.gitignore === 'drift') {
+      suggest('warn', `The managed .gitignore block is out of date; generated files can leak into git status. Run \`${fix}\`.`, fix);
+    } else if (leaks.gitignore === 'missing') {
+      suggest('warn', `.gitignore has no wize-dev-kit managed block; generated files can leak into git status. Run \`${fix}\`.`, fix);
     }
   }
 
@@ -242,8 +356,8 @@ async function cmdDoctor({ kitRoot, projectRoot, opts = {} } = {}) {
     log(`CONCERNS:  ${gates.CONCERNS}`);
     log(`FAIL:      ${gates.FAIL}`);
     log(`WAIVED:    ${gates.WAIVED}`);
-    if (gates.FAIL > 0) suggestions.push({ level: 'error', text: `${gates.FAIL} story gate(s) at FAIL. Stories must not merge until resolved (advisory mode) or are blocking (enforcing mode).` });
-    if (gates.CONCERNS > 0) suggestions.push({ level: 'warn', text: `${gates.CONCERNS} story gate(s) at CONCERNS. Review findings before next sprint.` });
+    if (gates.FAIL > 0) suggest('error', `${gates.FAIL} story gate(s) at FAIL. Stories must not merge until resolved (advisory mode) or are blocking (enforcing mode).`);
+    if (gates.CONCERNS > 0) suggest('warn', `${gates.CONCERNS} story gate(s) at CONCERNS. Review findings before next sprint.`);
   }
 
   // -- Section: Knowledge --
@@ -255,26 +369,26 @@ async function cmdDoctor({ kitRoot, projectRoot, opts = {} } = {}) {
       const age = f.days == null ? 'no last_refreshed' : `${f.days}d ago`;
       log(`  ${f.name.padEnd(28)} ${age}`);
       if (f.days != null && f.days > 60) {
-        suggestions.push({ level: 'warn', text: `\`${f.name}\` last refreshed ${f.days}d ago. Run \`/wize-refresh-knowledge\` after current sprint.` });
+        suggest('warn', `\`${f.name}\` last refreshed ${f.days}d ago. Run \`/wize-refresh-knowledge\` after current sprint.`);
       }
     }
     if (knowledge.pendingLines > 0) {
       log(`  _pending.md:                ${knowledge.pendingLines} inline note(s) waiting consolidation`);
       if (knowledge.pendingLines >= 5) {
-        suggestions.push({ level: 'info', text: `${knowledge.pendingLines} notes piled up in _pending.md. Time to run \`/wize-refresh-knowledge\`.` });
+        suggest('info', `${knowledge.pendingLines} notes piled up in _pending.md. Time to run \`/wize-refresh-knowledge\`.`);
       }
     }
     const markerText = knowledge.toBeGeneratedMarkers > 0 ? `${knowledge.toBeGeneratedMarkers} marker(s)` : 'none';
     log(`  To be generated markers:    ${markerText}`);
     if (knowledge.toBeGeneratedMarkers >= 5) {
-      suggestions.push({ level: 'warn', text: `${knowledge.toBeGeneratedMarkers} docs marked "To be generated" in index.md. Run \`wize-dev-kit document-project initial_scan deep\` to fill them.` });
+      suggest('warn', `${knowledge.toBeGeneratedMarkers} docs marked "To be generated" in index.md. Run \`wize-dev-kit document-project initial_scan deep\` to fill them.`);
     }
     const stateText = knowledge.stateExists
       ? (knowledge.stateAgeDays == null ? 'project-scan-report.json exists (age unknown)' : `project-scan-report.json ${knowledge.stateAgeDays}d old`)
       : 'no project-scan-report.json';
     log(`  Scan state:                 ${stateText}`);
     if (!knowledge.stateExists) {
-      suggestions.push({ level: 'info', text: 'No scan state file found. Run `wize-dev-kit document-project quick` to create a baseline + state.' });
+      suggest('info', 'No scan state file found. Run `wize-dev-kit document-project initial_scan` to create a baseline + state.');
     }
   }
 
@@ -284,7 +398,7 @@ async function cmdDoctor({ kitRoot, projectRoot, opts = {} } = {}) {
   log('───────────────────────');
   if (harnesses.length === 0) {
     log('  (none detected)');
-    suggestions.push({ level: 'info', text: 'No harness CLI detected. Brownfield baseline + auto-run features only work in your IDE; the headless flow is unavailable.' });
+    suggest('info', 'No harness CLI detected. Brownfield baseline + auto-run features only work in your IDE; the headless flow is unavailable.');
   } else {
     for (const h of harnesses) log(`  ${h.binary.padEnd(10)} ${h.path}`);
   }
@@ -295,10 +409,12 @@ async function cmdDoctor({ kitRoot, projectRoot, opts = {} } = {}) {
   log('───');
   if (!git.isRepo) {
     log('  (not a git repo)');
-    suggestions.push({ level: 'warn', text: 'Not a git repository. Run `git init` before installing the kit so version history is recorded.' });
+    suggest('warn', 'Not a git repository. Run `git init` before installing the kit so version history is recorded.');
   } else {
-    log(`  branch: ${git.branch}`);
-    log(`  head:   ${git.head}`);
+    log(`  checkout: ${git.linked ? `linked worktree of ${git.primary || '?'}` : 'primary checkout'}`);
+    log(`  branch:   ${git.detached ? `detached @${git.head || '?'}` : (git.branch || '?')}`);
+    log(`  head:     ${git.head || '(no commits)'}`);
+    log(`  default branch: ${git.defaultBranch || '(unknown)'}`);
   }
 
   // -- Section: Suggestions --
@@ -312,7 +428,37 @@ async function cmdDoctor({ kitRoot, projectRoot, opts = {} } = {}) {
   }
   log('');
 
-  return { suggestions, phase, gates, knowledge, targets, profiles, installed, registryLatest };
+  const count = (level) => suggestions.filter(s => s.level === level).length;
+  const summary = { errors: count('error'), warnings: count('warn'), infos: count('info') };
+  const exitCode = opts.strict && summary.errors > 0 ? 1 : 0;
+
+  if (json) {
+    out(JSON.stringify({
+      schema: 1,
+      ok: summary.errors === 0,
+      exit_code: exitCode,
+      root: cwd,
+      kit: { installed, project: pin, registry: registryLatest, update_check: updateCheckOff ? 'disabled' : 'cache' },
+      project: cfg.project ? {
+        name: cfg.project.name || null,
+        profiles,
+        targets,
+        language: { communication: (cfg.language && cfg.language.communication) || null, document_output: (cfg.language && cfg.language.document_output) || null },
+        phase
+      } : null,
+      git,
+      hydration,
+      adapters,
+      leaks,
+      gates,
+      knowledge,
+      harnesses: harnesses.map(h => ({ binary: h.binary, path: h.path })),
+      suggestions,
+      summary
+    }));
+  }
+
+  return { suggestions, phase, gates, knowledge, targets, profiles, installed, registryLatest, status, hydration, leaks, git, summary, exitCode };
 }
 
 module.exports = {

package/tools/installer/commands/document-project.js

@@ -21,6 +21,7 @@ function parseMode(args) {
   let resume = false;
   let scanLevel = 'quick';
   let target = null;
+  let overwrite = false;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -28,6 +29,10 @@ function parseMode(args) {
       resume = true;
       continue;
     }
+    if (arg === '--force') {
+      overwrite = true;
+      continue;
+    }
     if (arg === '--target') {
       target = args[i + 1];
       i++;
@@ -53,7 +58,7 @@ function parseMode(args) {
     return { mode: null, error: `unknown mode: ${mode}. Valid modes: ${[...VALID_MODES].join(', ')}` };
   }
 
-  return { mode, resume, scanLevel, target };
+  return { mode, resume, scanLevel, target, overwrite };
 }
 
 function cmdDocumentProject({ kitRoot, projectRoot, args = [], opts = {} }) {
@@ -66,12 +71,17 @@ function cmdDocumentProject({ kitRoot, projectRoot, args = [], opts = {} }) {
   }
 
   if (parsed.mode === 'quick') {
-    const r = runQuick(projectRoot, { log });
+    const env = opts.env || process.env;
+    if (env.WIZE_SKIP_BASELINE === '1') {
+      log('WIZE_SKIP_BASELINE=1: skipped');
+      return { ok: true, mode: 'quick', changed: false, skipped: true, written: [] };
+    }
+    const r = runQuick(projectRoot, { log, overwrite: parsed.overwrite });
     return { ok: true, mode: 'quick', ...r };
   }
 
   if (parsed.mode === 'initial_scan') {
-    const r = runInitialScan(projectRoot, { scanLevel: parsed.scanLevel, log });
+    const r = runInitialScan(projectRoot, { scanLevel: parsed.scanLevel, log, overwrite: parsed.overwrite });
     return { ok: true, mode: 'initial_scan', ...r };
   }
 

package/tools/installer/commands/hooks.js

@@ -0,0 +1,215 @@
+// `wize-dev-kit hooks` — opt-in automation that hydrates a checkout on its own.
+//
+//   hooks install [--claude] [--cursor] [--github-action]
+//   hooks print <orca|claude|cursor|codex|github-action>
+//
+// `install` always writes the tracked, managed .wize/hooks/hydrate.sh and then
+// only the config files whose flag was passed. `print` writes nothing. Nothing
+// here runs without an explicit flag, because every file it writes is tracked.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const HOOK_REL = '.wize/hooks/hydrate.sh';
+const HOOK_HEADER = '# wize-dev-kit managed hook v1';
+const TEMPLATES = path.resolve(__dirname, '..', 'templates');
+const PRINT_TARGETS = ['orca', 'claude', 'cursor', 'codex', 'github-action'];
+
+const readTemplate = (name) => fs.readFileSync(path.join(TEMPLATES, name), 'utf-8');
+
+const CLAUDE_ENTRY = {
+  matcher: 'startup',
+  hooks: [{ type: 'command', command: 'sh "$CLAUDE_PROJECT_DIR"/.wize/hooks/hydrate.sh', timeout: 180 }]
+};
+const CURSOR_CONFIG = { 'setup-worktree': ['sh .wize/hooks/hydrate.sh'] };
+
+// A hydrate.sh this kit wrote carries the header within its first lines. Any
+// other file at that path belongs to the user.
+function isManagedHook(content) {
+  return typeof content === 'string' && content.split('\n', 6).some(l => l.trim() === HOOK_HEADER);
+}
+
+// The new content for an installed hook, or null when it is absent, not
+// managed, or already current. Used by `update` to refresh the script.
+function refreshedHook(current) {
+  if (!isManagedHook(current)) return null;
+  const next = readTemplate('hydrate.sh');
+  return next === current ? null : next;
+}
+
+// Pure. `text` is the current .claude/settings.json (null when absent).
+// -> { ok: true, changed, next } | { ok: false, error }. Every other key and
+// hook is kept; an entry that already runs the managed script is not duplicated.
+function mergeClaudeSettings(text) {
+  let settings = {};
+  if (text !== null && text.trim() !== '') {
+    try { settings = JSON.parse(text); }
+    catch (err) { return { ok: false, error: `.claude/settings.json is not valid JSON (${err.message})` }; }
+  }
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+    return { ok: false, error: '.claude/settings.json must hold a JSON object' };
+  }
+  if (settings.hooks === undefined) settings.hooks = {};
+  if (!settings.hooks || typeof settings.hooks !== 'object' || Array.isArray(settings.hooks)) {
+    return { ok: false, error: '.claude/settings.json: "hooks" must be an object' };
+  }
+  if (settings.hooks.SessionStart === undefined) settings.hooks.SessionStart = [];
+  if (!Array.isArray(settings.hooks.SessionStart)) {
+    return { ok: false, error: '.claude/settings.json: hooks.SessionStart must be an array' };
+  }
+  if (JSON.stringify(settings.hooks.SessionStart).includes(HOOK_REL)) return { ok: true, changed: false, next: text };
+  settings.hooks.SessionStart.push(CLAUDE_ENTRY);
+  return { ok: true, changed: true, next: JSON.stringify(settings, null, 2) + '\n' };
+}
+
+const cursorJson = () => JSON.stringify(CURSOR_CONFIG, null, 2) + '\n';
+
+function printSnippet(target) {
+  const claude = JSON.stringify({ hooks: { SessionStart: [CLAUDE_ENTRY] } }, null, 2);
+  const snippets = {
+    orca: [
+      '# orca.yaml (commit it at the repo root)',
+      'scripts:',
+      `  setup: sh ${HOOK_REL}`,
+      'setupAgentStartupPolicy: wait-for-setup',
+      '',
+      '# A non-empty setup hook saved locally in Orca overrides orca.yaml. Clear it in the',
+      '# repository settings, or the line above never runs.',
+      '',
+      '# .worktreeinclude (gitignored files Orca copies into each new worktree)',
+      '.wize/config/user.toml'
+    ].join('\n'),
+    claude: [`# .claude/settings.json (or run: wize-dev-kit hooks install --claude)`, claude].join('\n'),
+    cursor: ['# .cursor/worktrees.json (or run: wize-dev-kit hooks install --cursor)', cursorJson().trimEnd()].join('\n'),
+    codex: [
+      'Codex local environment: set the setup script for this project to',
+      '',
+      `  sh ${HOOK_REL}`,
+      '',
+      'Codex stores it in its own local-environment config, so the kit does not write it.'
+    ].join('\n'),
+    'github-action': [`# .github/workflows/wize-kit-update.yml (or run: wize-dev-kit hooks install --github-action)`, readTemplate('wize-kit-update.yml').trimEnd()].join('\n')
+  };
+  return snippets[target];
+}
+
+const USAGE = [
+  'Usage:',
+  '  wize-dev-kit hooks install [--claude] [--cursor] [--github-action]',
+  '  wize-dev-kit hooks print <orca|claude|cursor|codex|github-action>',
+  '',
+  'install always writes .wize/hooks/hydrate.sh; each flag adds one config file.'
+].join('\n');
+
+function writeText(file, content, mode) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content, mode ? { encoding: 'utf-8', mode } : 'utf-8');
+}
+
+function readOrNull(file) {
+  try { return fs.readFileSync(file, 'utf-8'); } catch { return null; }
+}
+
+function install({ projectRoot, flags, log, errlog }) {
+  const want = { claude: !!flags.claude, cursor: !!flags.cursor, action: !!(flags['github-action'] || flags.githubAction) };
+  if (!want.claude && !want.cursor && !want.action) {
+    errlog('✖ hooks install needs at least one of --claude, --cursor, --github-action');
+    errlog(USAGE);
+    return { exitCode: 1, written: [], unchanged: [] };
+  }
+
+  const written = [];
+  const unchanged = [];
+  const note = (rel, changed) => {
+    (changed ? written : unchanged).push(rel);
+    log(`${changed ? '✓ wrote' : '· unchanged'} ${rel}`);
+  };
+  const abs = (rel) => path.join(projectRoot, rel);
+  const fail = (message) => {
+    errlog(`✖ ${message}`);
+    return { exitCode: 1, written, unchanged };
+  };
+
+  // Validate everything that can refuse before writing anything.
+  const hookFile = abs(HOOK_REL);
+  const hookCurrent = readOrNull(hookFile);
+  if (hookCurrent !== null && !isManagedHook(hookCurrent)) {
+    return fail(`${HOOK_REL} exists and is not managed by wize-dev-kit; move it aside or merge by hand`);
+  }
+  let claudeMerge = null;
+  if (want.claude) {
+    claudeMerge = mergeClaudeSettings(readOrNull(abs('.claude/settings.json')));
+    if (!claudeMerge.ok) return fail(claudeMerge.error);
+  }
+  if (!fs.existsSync(abs('.wize/config/project.toml'))) {
+    errlog('warning: no .wize/config/project.toml here; the hook skips until the kit is installed');
+  }
+
+  const script = readTemplate('hydrate.sh');
+  if (hookCurrent !== script) writeText(hookFile, script);
+  fs.chmodSync(hookFile, 0o755);
+  note(HOOK_REL, hookCurrent !== script);
+
+  if (want.claude) {
+    if (claudeMerge.changed) writeText(abs('.claude/settings.json'), claudeMerge.next);
+    note('.claude/settings.json', claudeMerge.changed);
+  }
+
+  if (want.cursor) {
+    const rel = '.cursor/worktrees.json';
+    const current = readOrNull(abs(rel));
+    if (current === null) {
+      writeText(abs(rel), cursorJson());
+      note(rel, true);
+    } else if (current.includes(HOOK_REL)) {
+      note(rel, false);
+    } else {
+      unchanged.push(rel);
+      log(`· ${rel} exists; add this line to its "setup-worktree" array:`);
+      log(`    "sh ${HOOK_REL}"`);
+    }
+  }
+
+  if (want.action) {
+    const rel = '.github/workflows/wize-kit-update.yml';
+    if (fs.existsSync(abs(rel))) note(rel, false);
+    else {
+      writeText(abs(rel), readTemplate('wize-kit-update.yml'));
+      note(rel, true);
+      log('  enable "Allow GitHub Actions to create and approve pull requests" in the repository settings');
+    }
+  }
+
+  return { exitCode: 0, written, unchanged };
+}
+
+function cmdHooks({ projectRoot, args = [], flags = {}, opts = {} } = {}) {
+  const log = opts.log || console.log;
+  const errlog = opts.errlog || console.error;
+  const [sub, target] = args;
+
+  if (sub === 'install') return install({ projectRoot, flags, log, errlog });
+  if (sub === 'print') {
+    if (!PRINT_TARGETS.includes(target)) {
+      errlog(`✖ ${target ? `unknown target "${target}"` : 'hooks print needs a target'}; available: ${PRINT_TARGETS.join(', ')}`);
+      return { exitCode: 1 };
+    }
+    log(printSnippet(target));
+    return { exitCode: 0 };
+  }
+  errlog(sub ? `✖ unknown hooks subcommand "${sub}"` : '✖ hooks needs a subcommand');
+  errlog(USAGE);
+  return { exitCode: 1 };
+}
+
+module.exports = {
+  cmdHooks,
+  mergeClaudeSettings,
+  isManagedHook,
+  refreshedHook,
+  HOOK_REL,
+  PRINT_TARGETS,
+  readTemplate
+};