wize-dev-kit 0.16.0 → 0.17.0

package/tools/installer/baseline.js

@@ -0,0 +1,138 @@
+// Brownfield baseline runner — detects AI harness CLIs available on PATH and,
+// when authorized, executes `/wize-document-project` headlessly to populate
+// .wize/knowledge/document-project/. Falls back to printed instructions when
+// no harness is present or the user opts out.
+//
+// Harness priority is:
+//   1. user's selected IDE targets (from .wize/config/project.toml), highest first
+//   2. claude > codex > opencode > hermes > kiro-cli (universal fallback)
+//
+// Set WIZE_SKIP_BASELINE=1 in the environment to disable any execution (the
+// install still suggests the next step). Useful for CI and unattended setups.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+// Harness registry — for each supported CLI we know:
+//   binary  : the executable name to find on PATH
+//   ideCode : the matching `ide_targets` code in project.toml (so we can prioritize)
+//   buildCmd: returns the spawnSync args (binary + arg list) for a headless run
+const HARNESSES = [
+  {
+    code: 'claude-code',
+    binary: 'claude',
+    buildCmd: (prompt) => ({ cmd: 'claude', args: ['-p', prompt] })
+  },
+  {
+    code: 'codex',
+    binary: 'codex',
+    buildCmd: (prompt) => ({ cmd: 'codex', args: ['exec', '--', prompt] })
+  },
+  {
+    code: 'opencode',
+    binary: 'opencode',
+    buildCmd: (prompt) => ({ cmd: 'opencode', args: ['run', prompt] })
+  },
+  {
+    code: 'hermes',
+    binary: 'hermes',
+    buildCmd: (prompt) => ({ cmd: 'hermes', args: ['-z', prompt] })
+  },
+  {
+    code: 'kiro',
+    binary: 'kiro-cli',
+    buildCmd: (prompt) => ({ cmd: 'kiro-cli', args: ['chat', '--no-interactive', '--trust-all-tools', prompt] })
+  }
+];
+
+function whichSync(bin) {
+  // Manual PATH walk — more predictable than shelling out to `which`/`where`,
+  // honors PATH overrides set by callers (and our tests), and stays portable.
+  const PATH = process.env.PATH || '';
+  const sep = process.platform === 'win32' ? ';' : ':';
+  const exts = process.platform === 'win32'
+    ? (process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';')
+    : [''];
+  for (const dir of PATH.split(sep).filter(Boolean)) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, bin + ext);
+      try {
+        const st = fs.statSync(candidate);
+        if (st.isFile() && (process.platform === 'win32' || (st.mode & 0o111))) {
+          return candidate;
+        }
+      } catch (_) { /* not here, keep looking */ }
+    }
+  }
+  return null;
+}
+
+// Returns an ordered list of harnesses present on PATH. When `preferIde`
+// includes a harness's `code`, it floats to the top of the result.
+function detectHarnessCli({ preferIde = [] } = {}) {
+  const found = [];
+  for (const h of HARNESSES) {
+    const p = whichSync(h.binary);
+    if (p) found.push({ ...h, path: p });
+  }
+  // Float preferred IDE targets to the top, keep relative order otherwise.
+  return found.sort((a, b) => {
+    const ai = preferIde.indexOf(a.code);
+    const bi = preferIde.indexOf(b.code);
+    if (ai === -1 && bi === -1) return 0;
+    if (ai === -1) return 1;
+    if (bi === -1) return -1;
+    return ai - bi;
+  });
+}
+
+// Run the harness headless with the document-project prompt. Returns
+// { ok: boolean, exitCode, stdout, stderr }.
+function runHeadlessBaseline({ harness, projectRoot, prompt, log = console.log }) {
+  if (process.env.WIZE_SKIP_BASELINE === '1') {
+    log('WIZE_SKIP_BASELINE=1 — not running the baseline; you can do it later in your IDE.');
+    return { ok: false, skipped: true };
+  }
+  const { cmd, args } = harness.buildCmd(prompt);
+  log(`Running ${cmd} ${args.map(a => /\s/.test(a) ? '"' + a + '"' : a).join(' ')}\n`);
+  const r = spawnSync(cmd, args, { cwd: projectRoot, stdio: 'inherit' });
+  return { ok: r.status === 0, exitCode: r.status, signal: r.signal };
+}
+
+function manualInstructions(harness) {
+  if (!harness) {
+    return [
+      '',
+      'No AI harness CLI was detected on PATH (claude / codex / opencode / hermes / kiro-cli).',
+      'Open your IDE in this repo and run:',
+      '  /wize-document-project',
+      ''
+    ].join('\n');
+  }
+  const { cmd, args } = harness.buildCmd('/wize-document-project');
+  const shown = `${cmd} ${args.map(a => /\s/.test(a) ? '"' + a + '"' : a).join(' ')}`;
+  return [
+    '',
+    `Skipping the headless run. When you're ready, run from this folder:`,
+    `  ${shown}`,
+    '',
+    `Or open your IDE and type:  /wize-document-project`,
+    ''
+  ].join('\n');
+}
+
+function defaultPrompt() {
+  return 'Activate the wize-document-project skill and execute it on this repository. Follow the steps in .claude/skills/wize-document-project/SKILL.md (or the equivalent path for your IDE). Output the baseline docs under .wize/knowledge/document-project/.';
+}
+
+module.exports = {
+  HARNESSES,
+  whichSync,
+  detectHarnessCli,
+  runHeadlessBaseline,
+  manualInstructions,
+  defaultPrompt
+};

package/tools/installer/commands/agent.js

@@ -0,0 +1,197 @@
+// `wize-dev-kit agent <subcommand>` — manage built-in and custom agents.
+//
+//   list        - show every agent the active install resolves (built-in + custom)
+//   create      - scaffold a brand-new custom agent in .wize/custom/agents/{code}/
+//   edit <code> - override an existing built-in via .wize/custom/agents/{code}/customize.toml
+//
+// All write operations validate the result against schemas/agent.schema.json
+// (lite parser — no dependency on Ajv yet) and do a smoke dry-run before
+// persisting, matching the contract `wize-create-agent` describes.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const prompts = require('prompts');
+const { collectAssets } = require('../render-shared.js');
+
+const VALID_CODE = /^wize-(agent|orchestrator)(?:-[a-z0-9-]+)?$/;
+const VALID_MODULES = ['orchestrator', 'method', 'tea', 'builder', 'core', 'web-overlay', 'app-overlay', 'custom'];
+
+function ensureDir(p) { fs.mkdirSync(p, { recursive: true }); }
+
+function listAgents(kitRoot, projectRoot) {
+  const builtIn = collectAssets(kitRoot, { profiles: ['core', 'web-overlay', 'app-overlay'] })
+    .filter(a => a.kind === 'agent')
+    .map(a => ({ code: a.code, name: a.name, title: a.title, source: 'built-in' }));
+  const customDir = path.join(projectRoot, '.wize/custom/agents');
+  const custom = [];
+  if (fs.existsSync(customDir)) {
+    for (const entry of fs.readdirSync(customDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const yamlPath = path.join(customDir, entry.name, 'agent.yaml');
+      const customizePath = path.join(customDir, entry.name, 'customize.toml');
+      if (fs.existsSync(yamlPath)) {
+        const yaml = fs.readFileSync(yamlPath, 'utf-8');
+        const name = (yaml.match(/^name:\s*(.+)$/m) || [])[1] || entry.name;
+        const title = (yaml.match(/^title:\s*(.+)$/m) || [])[1] || '';
+        custom.push({ code: entry.name, name: name.trim(), title: title.trim(), source: 'custom' });
+      } else if (fs.existsSync(customizePath)) {
+        custom.push({ code: entry.name, name: '(override)', title: '', source: 'override' });
+      }
+    }
+  }
+  return { builtIn, custom };
+}
+
+function cmdAgentList({ kitRoot, projectRoot, log = console.log } = {}) {
+  const { builtIn, custom } = listAgents(kitRoot, projectRoot);
+  log('Built-in agents:');
+  for (const a of builtIn) log(`  ${a.code.padEnd(36)} ${a.name}${a.title ? ' — ' + a.title : ''}`);
+  if (custom.length) {
+    log('\nCustom / override agents (from .wize/custom/agents/):');
+    for (const a of custom) log(`  ${a.code.padEnd(36)} ${a.name}${a.title ? ' — ' + a.title : ''}   [${a.source}]`);
+  } else {
+    log('\nCustom / override agents: (none yet — use `wize-dev-kit agent create`)');
+  }
+  return { builtIn, custom };
+}
+
+function validateAgent(spec, kitRoot) {
+  const errs = [];
+  if (!spec.code) errs.push('code is required');
+  else if (!VALID_CODE.test(spec.code)) errs.push(`code "${spec.code}" must match wize-(agent|orchestrator)[-name]`);
+  if (!spec.name) errs.push('name is required');
+  if (!spec.title) errs.push('title is required');
+  if (!VALID_MODULES.includes(spec.module)) errs.push(`module must be one of: ${VALID_MODULES.join(', ')}`);
+  if (!spec.description || spec.description.length < 10) errs.push('description must be ≥ 10 characters');
+  // Collide check against built-ins when not overriding.
+  const builtinCodes = collectAssets(kitRoot, { profiles: ['core', 'web-overlay', 'app-overlay'] })
+    .filter(a => a.kind === 'agent').map(a => a.code);
+  if (builtinCodes.includes(spec.code) && !spec.allowOverride) {
+    errs.push(`code "${spec.code}" already exists as a built-in. Use \`wize-dev-kit agent edit ${spec.code}\` to override.`);
+  }
+  return errs;
+}
+
+function renderAgentYaml(spec) {
+  return [
+    `code: ${spec.code}`,
+    `name: ${spec.name}`,
+    `title: ${spec.title}`,
+    `icon: "${spec.icon || '🔧'}"`,
+    `team: ${spec.team || 'software-development'}`,
+    `module: ${spec.module}`,
+    '',
+    'description: |',
+    ...spec.description.split('\n').map(l => '  ' + l),
+    ''
+  ].join('\n');
+}
+
+function renderPersonaMd(spec) {
+  const body = (spec.persona || `I am **${spec.name}**. ${spec.description}`).trim();
+  return [
+    `# ${spec.name} — ${spec.title}`,
+    '',
+    body,
+    ''
+  ].join('\n');
+}
+
+// Smoke dry-run: write to temp dir, re-read, assert frontmatter parses.
+function dryRunPersist(spec) {
+  const tmp = path.join(require('node:os').tmpdir(), `wize-agent-${spec.code}-${Date.now()}`);
+  ensureDir(tmp);
+  try {
+    fs.writeFileSync(path.join(tmp, 'agent.yaml'), renderAgentYaml(spec), 'utf-8');
+    fs.writeFileSync(path.join(tmp, 'persona.md'), renderPersonaMd(spec), 'utf-8');
+    const reread = fs.readFileSync(path.join(tmp, 'agent.yaml'), 'utf-8');
+    if (!/^code:\s+/m.test(reread)) throw new Error('emitted agent.yaml has no "code:" line');
+    if (!/^name:\s+/m.test(reread)) throw new Error('emitted agent.yaml has no "name:" line');
+    return { ok: true };
+  } finally {
+    try { fs.rmSync(tmp, { recursive: true, force: true }); } catch (_) {}
+  }
+}
+
+async function cmdAgentCreate({ kitRoot, projectRoot, opts = {} } = {}) {
+  const interactive = process.stdout.isTTY && process.stdin.isTTY && !opts.fromSpec;
+  let spec = opts.fromSpec || {};
+
+  if (interactive) {
+    const a = await prompts([
+      { type: 'text', name: 'code',  message: 'Agent code (e.g. wize-agent-runbooks)',
+        validate: v => VALID_CODE.test(v) || 'must match wize-(agent|orchestrator)[-name]' },
+      { type: 'text', name: 'name',  message: 'Display name (e.g. Riri Williams)', validate: v => !!v.trim() || 'required' },
+      { type: 'text', name: 'title', message: 'Role / title (e.g. Reliability Engineer)', validate: v => !!v.trim() || 'required' },
+      { type: 'text', name: 'icon',  message: 'Icon emoji (optional)', initial: '🔧' },
+      { type: 'text', name: 'team',  message: 'Team', initial: 'software-development' },
+      { type: 'select', name: 'module', message: 'Module', choices: VALID_MODULES.map(v => ({ title: v, value: v })), initial: VALID_MODULES.indexOf('custom') },
+      { type: 'text', name: 'description', message: 'One-paragraph description (≥ 10 chars)', validate: v => v.length >= 10 || 'must be ≥ 10 characters' },
+      { type: 'text', name: 'persona', message: 'Persona body (optional — defaults to description)', initial: '' }
+    ], { onCancel: () => process.exit(130) });
+    spec = { ...spec, ...a };
+  }
+
+  const errs = validateAgent(spec, kitRoot);
+  if (errs.length) {
+    console.error('✖ Validation failed:');
+    for (const e of errs) console.error('  - ' + e);
+    process.exit(2);
+  }
+
+  const dry = dryRunPersist(spec);
+  if (!dry.ok) {
+    console.error('✖ Dry-run failed; aborting.');
+    process.exit(3);
+  }
+
+  const target = path.join(projectRoot, '.wize/custom/agents', spec.code);
+  ensureDir(target);
+  fs.writeFileSync(path.join(target, 'agent.yaml'), renderAgentYaml(spec), 'utf-8');
+  fs.writeFileSync(path.join(target, 'persona.md'), renderPersonaMd(spec), 'utf-8');
+
+  console.log(`✓ Created ${path.relative(projectRoot, target)}/`);
+  console.log('  Run `wize-dev-kit sync` to refresh IDE adapter outputs with the new agent.');
+  return { code: spec.code, path: target };
+}
+
+async function cmdAgentEdit({ kitRoot, projectRoot, code, opts = {} } = {}) {
+  if (!code) {
+    console.error('Usage: wize-dev-kit agent edit <code>');
+    process.exit(1);
+  }
+  const builtinCodes = collectAssets(kitRoot, { profiles: ['core', 'web-overlay', 'app-overlay'] })
+    .filter(a => a.kind === 'agent').map(a => a.code);
+  if (!builtinCodes.includes(code)) {
+    console.error(`✖ "${code}" is not a built-in agent. Use \`wize-dev-kit agent create\` for new agents.`);
+    process.exit(2);
+  }
+
+  const target = path.join(projectRoot, '.wize/custom/agents', code);
+  ensureDir(target);
+  const customize = path.join(target, 'customize.toml');
+  if (fs.existsSync(customize) && !opts.force) {
+    console.log(`= ${path.relative(projectRoot, customize)} already exists. Edit it directly.`);
+    return { code, path: customize };
+  }
+  fs.writeFileSync(customize, `# Wize Dev Kit — overrides for the built-in agent "${code}".
+# This file is loaded on top of the built-in agent's persona.md / agent.yaml
+# at IDE adapter render time. Only the fields you set here are overridden.
+
+[persona]
+# motto      = "your custom motto"
+# voice      = "succinct and irreverent"
+# style      = "show with code, not prose"
+
+[behavior]
+# defer_to   = []         # e.g. ["wize-agent-pm"] to lower priority on certain decisions
+# tools_deny = []         # tool codes the override removes from the agent
+`, 'utf-8');
+  console.log(`✓ Created ${path.relative(projectRoot, customize)}`);
+  console.log('  Edit the file, then run `wize-dev-kit sync` to apply.');
+  return { code, path: customize };
+}
+
+module.exports = { cmdAgentList, cmdAgentCreate, cmdAgentEdit, listAgents, validateAgent };

package/tools/installer/commands/doctor.js

@@ -0,0 +1,321 @@
+// `wize-dev-kit doctor` — single-command diagnose.
+//
+// Prints a structured snapshot of the kit + the project + the surrounding
+// environment, plus a list of actionable suggestions ranked by severity.
+// Designed to be the *first* command a new dev runs in an unfamiliar
+// wize-enabled repo, and the *go-to* command when something looks off.
+//
+// Output is plain text (no colors by default) so it's grep-friendly and pipe-
+// friendly. Sections are stable so editors / dashboards can parse them.
+
+'use strict';
+
+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');
+
+function fileExists(p) { try { return fs.statSync(p).isFile(); } catch { return false; } }
+function dirExists(p)  { try { return fs.statSync(p).isDirectory(); } catch { return false; } }
+function readSafe(p)   { try { return fs.readFileSync(p, 'utf-8'); } catch { return ''; } }
+
+function listFilesUnder(root, pattern) {
+  if (!dirExists(root)) return [];
+  const out = [];
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries; try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) stack.push(full);
+      else if (e.isFile() && pattern.test(e.name)) out.push(full);
+    }
+  }
+  return out;
+}
+
+function parseGateStatus(content) {
+  // Find a `status: PASS|CONCERNS|FAIL|WAIVED` line in YAML frontmatter.
+  const m = content.match(/^status:\s*(PASS|CONCERNS|FAIL|WAIVED)\s*$/m);
+  return m ? m[1] : null;
+}
+
+function parseLastRefreshed(content) {
+  const m = content.match(/^last_refreshed:\s*([\d-]+)/m);
+  return m ? m[1] : null;
+}
+
+function daysAgo(dateStr) {
+  const t = Date.parse(dateStr);
+  if (Number.isNaN(t)) return null;
+  return Math.floor((Date.now() - t) / (24 * 3600 * 1000));
+}
+
+function adapterTargetPath(targetCode, projectRoot) {
+  // Mirror of the adapter render conventions documented in adapters/README.md.
+  switch (targetCode) {
+    case 'claude-code':  return path.join(projectRoot, '.claude/skills');
+    case 'antigravity':  return path.join(projectRoot, '.agent/skills');
+    case 'codex':        return path.join(projectRoot, '.agents/skills');
+    case 'kimi-code':    return path.join(projectRoot, '.kimi/skills');
+    case 'hermes':       return path.join(projectRoot, '.hermes/skills');
+    case 'kiro':         return path.join(projectRoot, '.kiro/skills');
+    case 'cursor':       return path.join(projectRoot, '.cursor/rules');
+    case 'windsurf':     return path.join(projectRoot, '.windsurf/rules');
+    case 'continue':     return path.join(projectRoot, '.continue/prompts');
+    case 'opencode':     return path.join(projectRoot, '.opencode/agents');
+    case 'generic':      return path.join(projectRoot, '.wize/agents');
+    default:             return null;
+  }
+}
+
+function countAdapterFiles(targetCode, projectRoot) {
+  const dir = adapterTargetPath(targetCode, projectRoot);
+  if (!dir || !dirExists(dir)) return 0;
+  // Be permissive on file extension; .mdc, .md, .prompt, and SKILL.md dirs all count.
+  let count = 0;
+  const stack = [dir];
+  while (stack.length) {
+    const d = stack.pop();
+    let entries; try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) stack.push(full);
+      else if (e.isFile()) count++;
+    }
+  }
+  return count;
+}
+
+function detectPhase(projectRoot) {
+  const has = (p) => fileExists(path.join(projectRoot, p)) || dirExists(path.join(projectRoot, p));
+  if (!dirExists(path.join(projectRoot, '.wize'))) return 'no-install';
+  if (!has('.wize/planning/brief.md')) return '1-analysis (brief pending)';
+  if (!has('.wize/planning/ux/trigger-map.md')) return '1-analysis (trigger map pending)';
+  if (!has('.wize/planning/prd.md')) return '2-plan (PRD pending)';
+  if (!has('.wize/planning/ux/ux-scenarios.md')) return '2-plan (UX scenarios pending)';
+  if (!has('.wize/planning/tech-vision.md')) return '2→3 boundary (Fury pending)';
+  if (!has('.wize/solutioning/architecture.md')) return '3-solutioning (architecture pending)';
+  if (!dirExists(path.join(projectRoot, '.wize/solutioning/stories')) ||
+      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)';
+  return '4-implementation';
+}
+
+function gateStats(projectRoot) {
+  const root = path.join(projectRoot, '.wize/implementation/tea');
+  const files = listFilesUnder(root, /^gate\.md$/);
+  const stats = { PASS: 0, CONCERNS: 0, FAIL: 0, WAIVED: 0, total: files.length };
+  for (const f of files) {
+    const s = parseGateStatus(readSafe(f));
+    if (s && stats[s] !== undefined) stats[s]++;
+  }
+  return stats;
+}
+
+function knowledgeStatus(projectRoot) {
+  const root = path.join(projectRoot, '.wize/knowledge/document-project');
+  const exists = dirExists(root);
+  if (!exists) return { exists: false };
+  const files = ['overview.md', 'architecture-snapshot.md', 'conventions.md', 'dependencies.md', 'risk-spots.md']
+    .map(name => path.join(root, name))
+    .filter(fileExists);
+  const refreshed = files.map(f => ({
+    name: path.basename(f),
+    days: daysAgo(parseLastRefreshed(readSafe(f)))
+  }));
+  const pendingFile = path.join(root, '_pending.md');
+  const pendingLines = fileExists(pendingFile)
+    ? readSafe(pendingFile).split('\n').filter(l => l.trim() && !l.startsWith('#')).length
+    : 0;
+
+  const indexPath = path.join(root, 'index.md');
+  const indexContent = fileExists(indexPath) ? readSafe(indexPath) : '';
+  const toBeGeneratedMarkers = (indexContent.match(/_\(To be generated\)_/g) || []).length;
+
+  const statePath = path.join(root, 'project-scan-report.json');
+  const stateExists = fileExists(statePath);
+  const stateContent = stateExists ? readSafe(statePath) : '';
+  let stateAgeDays = null;
+  try {
+    const state = JSON.parse(stateContent);
+    stateAgeDays = daysAgo(state.timestamps && state.timestamps.last_updated);
+  } catch (_) {}
+
+  return { exists: true, files: refreshed, pendingLines, toBeGeneratedMarkers, stateExists, stateAgeDays };
+}
+
+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 };
+}
+
+function severityIcon(level) {
+  return level === 'error' ? '✖' : level === 'warn' ? '⚠' : 'ℹ';
+}
+
+async function cmdDoctor({ kitRoot, projectRoot, opts = {} } = {}) {
+  const log = opts.log || console.log;
+  const cwd = projectRoot;
+  const cfg = loadProjectConfig(cwd);
+  const installed = loadInstalledKitVersion(kitRoot);
+  const phase = detectPhase(cwd);
+  const gates = gateStats(cwd);
+  const knowledge = knowledgeStatus(cwd);
+  const git = gitInfo(cwd);
+  const targets = (cfg.install && cfg.install.ide_targets) || [];
+  const profiles = (cfg.install && cfg.install.profiles) || [];
+  const harnesses = detectHarnessCli({ preferIde: targets });
+
+  // Try registry — best-effort, never blocks.
+  let registryLatest = null;
+  try { registryLatest = await getLatestVersion(); } catch (_) {}
+
+  const suggestions = [];
+
+  // -- 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.` });
+  }
+  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.` });
+  }
+
+  // -- Section: Project --
+  log('');
+  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.' });
+  } else {
+    log(`Name:                 ${cfg.project.name || '?'}`);
+    log(`Profiles:             ${profiles.join(', ') || '(none)'}`);
+    log(`IDE targets:          ${targets.join(', ') || '(none)'}`);
+    log(`Communication lang:   ${cfg.language && cfg.language.communication || '?'}`);
+    log(`Document lang:        ${cfg.language && cfg.language.document_output || '?'}`);
+    log(`Current phase:        ${phase}`);
+  }
+
+  // -- Section: Adapters --
+  if (cfg.install) {
+    log('');
+    log('IDE Adapters');
+    log('────────────');
+    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\`.` });
+    }
+  }
+
+  // -- Section: TEA gates --
+  if (gates.total > 0) {
+    log('');
+    log('TEA gates');
+    log('─────────');
+    log(`Total gate.md files:  ${gates.total}`);
+    log(`PASS:      ${gates.PASS}`);
+    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.` });
+  }
+
+  // -- Section: Knowledge --
+  if (knowledge.exists) {
+    log('');
+    log('Knowledge baseline (`document-project/`)');
+    log('────────────────────────────────────────');
+    for (const f of knowledge.files) {
+      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.` });
+      }
+    }
+    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\`.` });
+      }
+    }
+    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.` });
+    }
+    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.' });
+    }
+  }
+
+  // -- Section: Harness CLIs --
+  log('');
+  log('AI Harness CLIs on PATH');
+  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.' });
+  } else {
+    for (const h of harnesses) log(`  ${h.binary.padEnd(10)} ${h.path}`);
+  }
+
+  // -- Section: Git --
+  log('');
+  log('Git');
+  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.' });
+  } else {
+    log(`  branch: ${git.branch}`);
+    log(`  head:   ${git.head}`);
+  }
+
+  // -- Section: Suggestions --
+  log('');
+  log('Suggestions');
+  log('───────────');
+  if (suggestions.length === 0) {
+    log('  ✓ Everything looks good.');
+  } else {
+    for (const s of suggestions) log(`  ${severityIcon(s.level)} ${s.text}`);
+  }
+  log('');
+
+  return { suggestions, phase, gates, knowledge, targets, profiles, installed, registryLatest };
+}
+
+module.exports = {
+  cmdDoctor,
+  // exported for tests:
+  detectPhase, gateStats, knowledgeStatus, gitInfo, adapterTargetPath, countAdapterFiles
+};