@ghl-ai/aw 0.1.39-beta.8 → 0.1.39

package/commands/doctor.mjs

@@ -0,0 +1,1086 @@
+import { execSync } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync, readlinkSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import * as fmt from '../fmt.mjs';
+import { chalk } from '../fmt.mjs';
+import { AW_ECC_TAG } from '../ecc.mjs';
+import { getSupportedHarnessPhaseEntries } from '../hook-manifest.mjs';
+import { getStartupStatus, hasLegacyRepoStartupDefaults } from '../startup.mjs';
+
+const STATUS_PRIORITY = { pass: 0, warn: 1, fail: 2 };
+const STATUS_LABEL = {
+  pass: chalk.green('PASS'),
+  warn: chalk.yellow('WARN'),
+  fail: chalk.red('FAIL'),
+};
+
+const GENERATED_RULE_HEADER = '<!-- Generated by aw — do not edit manually -->';
+const AW_ROUTER_BRIDGE_START_MARKER = '<!-- aw-managed:start router-bridge -->';
+const AW_ROUTER_BRIDGE_END_MARKER = '<!-- aw-managed:end router-bridge -->';
+const PRIMARY_AW_ROUTES = ['plan', 'build', 'test', 'review', 'deploy', 'ship'];
+const CONDITIONAL_AW_ROUTES = ['investigate'];
+const COMPAT_AW_ROUTES = ['execute', 'verify'];
+const EXPECTED_AW_ROUTES = [...PRIMARY_AW_ROUTES, ...CONDITIONAL_AW_ROUTES, ...COMPAT_AW_ROUTES];
+const CLAUDE_PLUGIN_NAME = 'aw@aw-marketplace';
+const CLAUDE_POSIX_HOOK_COMMAND = 'bash "${CLAUDE_PLUGIN_ROOT}/hooks/session-start"';
+const CLAUDE_PORTABLE_HOOK_COMMAND = 'bash "${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/hooks/session-start"';
+const CLAUDE_PORTABLE_BASH_LC_COMMAND = 'bash -lc \'exec bash "${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/hooks/session-start"\'';
+const CLAUDE_POSIX_BASH_LC_COMMAND = 'bash -lc \'exec bash "${CLAUDE_PLUGIN_ROOT}/hooks/session-start"\'';
+const CLAUDE_WINDOWS_HOOK_COMMAND = '"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd" session-start';
+const REPO_CLAUDE_SESSION_START_COMMAND = '"$CLAUDE_PROJECT_DIR"/hooks/aw-session-start';
+const CODEX_HOOK_MATCHER = 'startup|resume';
+const CODEX_HOOK_COMMAND = 'bash "$HOME/.codex/hooks/aw-session-start.sh"';
+const CODEX_PROMPT_HOOK_COMMAND = 'bash "$HOME/.codex/hooks/aw-user-prompt-submit.sh"';
+const CODEX_PRE_TOOL_HOOK_COMMAND = 'bash "$HOME/.codex/hooks/aw-pre-tool-use.sh"';
+const CODEX_POST_TOOL_HOOK_COMMAND = 'bash "$HOME/.codex/hooks/aw-post-tool-use.sh"';
+const CODEX_STOP_HOOK_COMMAND = 'bash "$HOME/.codex/hooks/aw-stop.sh"';
+const CURSOR_HOOK_COMMAND = 'node .cursor/hooks/session-start.js';
+const CURSOR_BEFORE_PROMPT_COMMAND = 'node .cursor/hooks/before-submit-prompt.js';
+
+function hasManagedHookCommand(entry, command) {
+  return Array.isArray(entry?.hooks)
+    && entry.hooks.some(hook => hook?.type === 'command' && hook?.command === command);
+}
+
+function formatMissingParts(parts) {
+  return parts.length > 0 ? parts.join(', ') : 'none';
+}
+
+function formatPhaseSummary(parts) {
+  if (parts.length === 0) return 'none';
+  if (parts.length === 1) return parts[0];
+  if (parts.length === 2) return `${parts[0]} and ${parts[1]}`;
+  return `${parts.slice(0, -1).join(', ')}, and ${parts.at(-1)}`;
+}
+
+function projectRelinkFix(homeDir, cwd, targetDescription) {
+  return cwd !== homeDir
+    ? `Run \`aw link\` from the project root to refresh ${targetDescription}; use \`aw init\` if the global AW install is missing.`
+    : `Run \`aw init\` to refresh ${targetDescription}.`;
+}
+
+function globalInstallStateFix(homeDir, cwd, targetDescription) {
+  return cwd !== homeDir
+    ? `Run \`aw init\` to repair the global ${targetDescription}; use \`aw link\` separately if the current project still needs relinking.`
+    : `Run \`aw init\` to repair the global ${targetDescription}.`;
+}
+
+function readJson(filePath, fallback = {}) {
+  if (!existsSync(filePath)) return fallback;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function readText(filePath, fallback = '') {
+  if (!existsSync(filePath)) return fallback;
+  try {
+    return readFileSync(filePath, 'utf8');
+  } catch {
+    return fallback;
+  }
+}
+
+function makeCheck(id, title, status, summary, fix = null) {
+  return { id, title, status, summary, fix };
+}
+
+function overallStatus(checks) {
+  return checks.reduce((current, check) => (
+    STATUS_PRIORITY[check.status] > STATUS_PRIORITY[current] ? check.status : current
+  ), 'pass');
+}
+
+function parseLegacyClaudeHookTargets(sessionStartEntries = []) {
+  const targets = [];
+  for (const entry of sessionStartEntries) {
+    if (!Array.isArray(entry?.hooks)) continue;
+    for (const hook of entry.hooks) {
+      const command = String(hook?.command || '');
+      if (!command.includes('.aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh')) continue;
+      const match = command.match(/bash\s+("?)(.+?session-start\.sh)\1(?:\s|$)/);
+      const rawPath = (match?.[2] || '').replace(/\\ /g, ' ').trim();
+      targets.push({ command, path: rawPath || null });
+    }
+  }
+  return targets;
+}
+
+function compareVersion(a, b) {
+  const aParts = String(a).split('.').map(part => Number.parseInt(part, 10) || 0);
+  const bParts = String(b).split('.').map(part => Number.parseInt(part, 10) || 0);
+  const max = Math.max(aParts.length, bParts.length);
+  for (let i = 0; i < max; i += 1) {
+    const left = aParts[i] || 0;
+    const right = bParts[i] || 0;
+    if (left > right) return 1;
+    if (left < right) return -1;
+  }
+  return 0;
+}
+
+function latestVersion(dirPath) {
+  if (!existsSync(dirPath)) return null;
+  try {
+    return readdirSync(dirPath, { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+      .map(entry => entry.name)
+      .sort(compareVersion)
+      .at(-1) || null;
+  } catch {
+    return null;
+  }
+}
+
+function parseExactGitTag(repoDir) {
+  if (!existsSync(join(repoDir, '.git'))) return null;
+  try {
+    return execSync(`git -C "${repoDir}" describe --tags --exact-match`, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      encoding: 'utf8',
+      timeout: 3000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function parseCodexHooksFile(filePath) {
+  const content = readText(filePath);
+  return /^\s*codex_hooks\s*=\s*true\b/m.test(content);
+}
+
+function resolveAwRegistryDir(homeDir) {
+  return [
+    join(homeDir, '.aw_registry'),
+    join(homeDir, '.aw', '.aw_registry'),
+  ].find(existsSync) || null;
+}
+
+function resolveRulesDir(homeDir) {
+  const candidates = [
+    join(homeDir, '.aw', '.aw_rules'),
+    join(homeDir, '.aw', '.aw_registry', '.aw_rules'),
+  ];
+  return candidates.find(existsSync) || null;
+}
+
+function findClaudePlugin(homeDir) {
+  const cacheRoot = join(homeDir, '.claude', 'plugins', 'cache', 'aw-marketplace', 'aw');
+  const version = latestVersion(cacheRoot);
+  return {
+    cacheRoot,
+    version,
+    root: version ? join(cacheRoot, version) : null,
+  };
+}
+
+function missingFiles(rootDir, relativePaths) {
+  if (!rootDir) return [...relativePaths];
+  return relativePaths.filter(relativePath => !existsSync(join(rootDir, relativePath)));
+}
+
+function countDomainRuleFiles(rulesDir) {
+  const platformDir = join(rulesDir, 'platform');
+  if (!existsSync(platformDir)) return 0;
+
+  let count = 0;
+  const stack = [platformDir];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const fullPath = join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+      } else if (entry.isFile() && entry.name === 'AGENTS.md') {
+        count += 1;
+      }
+    }
+  }
+  return count;
+}
+
+function directoryContainsGeneratedRuleFiles(dirPath, extension) {
+  if (!existsSync(dirPath)) return false;
+  try {
+    return readdirSync(dirPath, { withFileTypes: true })
+      .filter(entry => entry.isFile() && entry.name.endsWith(extension))
+      .some(entry => readText(join(dirPath, entry.name)).startsWith(GENERATED_RULE_HEADER));
+  } catch {
+    return false;
+  }
+}
+
+function directoryContainsRegistrySymlink(dirPath) {
+  if (!existsSync(dirPath)) return false;
+  try {
+    return readdirSync(dirPath, { withFileTypes: true }).some((entry) => {
+      const fullPath = join(dirPath, entry.name);
+      if (!lstatSync(fullPath).isSymbolicLink()) return false;
+      return readlinkSync(fullPath).includes('.aw_registry');
+    });
+  } catch {
+    return false;
+  }
+}
+
+function jsonMcpHealth(filePath) {
+  const server = readJson(filePath).mcpServers?.['ghl-ai'];
+  return {
+    present: Boolean(server),
+    url: /^https?:\/\//.test(String(server?.url || '')),
+    authorization: typeof server?.headers?.Authorization === 'string' && server.headers.Authorization.length > 0,
+  };
+}
+
+function tomlMcpHealth(filePath) {
+  const content = readText(filePath);
+  return {
+    present: /\[mcp_servers\.ghl-ai\]/.test(content),
+    url: /\[mcp_servers\.ghl-ai\][\s\S]*?url\s*=\s*"https?:\/\/[^"]+"/.test(content),
+    authorization: /\[mcp_servers\.ghl-ai\.headers\][\s\S]*?Authorization\s*=\s*".+"/.test(content),
+  };
+}
+
+function hasManagedCodexSessionStart(filePath) {
+  const config = readJson(filePath, {});
+  return Array.isArray(config?.hooks?.SessionStart)
+    && config.hooks.SessionStart.some(entry =>
+      entry?.matcher === CODEX_HOOK_MATCHER
+      && Array.isArray(entry?.hooks)
+      && entry.hooks.some(hook =>
+        hook?.type === 'command'
+        && hook?.command === CODEX_HOOK_COMMAND
+      )
+    );
+}
+
+function hasManagedCursorSessionStart(filePath) {
+  const config = readJson(filePath, {});
+  return Array.isArray(config?.hooks?.sessionStart)
+    && config.hooks.sessionStart.some(entry =>
+      String(entry?.command || '') === CURSOR_HOOK_COMMAND
+      && String(entry?.event || '') === 'sessionStart'
+    );
+}
+
+function getClaudeHomeHookCoverage(homeDir) {
+  const supportedEntries = getSupportedHarnessPhaseEntries('claude', 'home');
+  const supportedPhases = supportedEntries.map(entry => entry.phase);
+  const hooksPath = join(homeDir, '.claude', 'hooks', 'hooks.json');
+  if (!existsSync(hooksPath)) {
+    return { ok: false, supportedPhases, missingPhases: supportedPhases };
+  }
+
+  const hooksConfig = readJson(hooksPath, {});
+  const sessionStartStatus = getClaudeHomeSessionStartStatus(homeDir);
+  const phaseChecks = {
+    SessionStart: sessionStartStatus.present && sessionStartStatus.ok && sessionStartStatus.reason !== 'missing',
+    UserPromptSubmit: Array.isArray(hooksConfig?.hooks?.UserPromptSubmit)
+      && hooksConfig.hooks.UserPromptSubmit.some(entry =>
+        Array.isArray(entry?.hooks)
+        && entry.hooks.some(hook => String(hook?.command || '').includes('session-start-rules-context.sh'))
+      ),
+    PreToolUse: Array.isArray(hooksConfig?.hooks?.PreToolUse) && hooksConfig.hooks.PreToolUse.length > 0,
+    PostToolUse: Array.isArray(hooksConfig?.hooks?.PostToolUse) && hooksConfig.hooks.PostToolUse.length > 0,
+    Stop: Array.isArray(hooksConfig?.hooks?.Stop) && hooksConfig.hooks.Stop.length > 0,
+    PostToolUseFailure: Array.isArray(hooksConfig?.hooks?.PostToolUseFailure) && hooksConfig.hooks.PostToolUseFailure.length > 0,
+    PreCompact: Array.isArray(hooksConfig?.hooks?.PreCompact) && hooksConfig.hooks.PreCompact.length > 0,
+  };
+
+  const missingPhases = supportedPhases.filter(phase => !phaseChecks[phase]);
+
+  return { ok: missingPhases.length === 0, supportedPhases, missingPhases };
+}
+
+function getCodexHomeHookCoverage(homeDir) {
+  const supportedEntries = getSupportedHarnessPhaseEntries('codex', 'home');
+  const supportedPhases = supportedEntries.map(entry => entry.phase);
+  const hooksPath = join(homeDir, '.codex', 'hooks.json');
+  const hooksConfig = readJson(hooksPath, {});
+  const phaseChecks = {
+    SessionStart: Array.isArray(hooksConfig?.hooks?.SessionStart)
+      && hooksConfig.hooks.SessionStart.some(entry =>
+        entry?.matcher === CODEX_HOOK_MATCHER
+        && hasManagedHookCommand(entry, CODEX_HOOK_COMMAND)
+      ),
+    UserPromptSubmit: Array.isArray(hooksConfig?.hooks?.UserPromptSubmit)
+      && hooksConfig.hooks.UserPromptSubmit.some(entry => hasManagedHookCommand(entry, CODEX_PROMPT_HOOK_COMMAND)),
+    PreToolUse: Array.isArray(hooksConfig?.hooks?.PreToolUse)
+      && hooksConfig.hooks.PreToolUse.some(entry => entry?.matcher === '*' && hasManagedHookCommand(entry, CODEX_PRE_TOOL_HOOK_COMMAND)),
+    PostToolUse: Array.isArray(hooksConfig?.hooks?.PostToolUse)
+      && hooksConfig.hooks.PostToolUse.some(entry => entry?.matcher === '*' && hasManagedHookCommand(entry, CODEX_POST_TOOL_HOOK_COMMAND)),
+    Stop: Array.isArray(hooksConfig?.hooks?.Stop)
+      && hooksConfig.hooks.Stop.some(entry => hasManagedHookCommand(entry, CODEX_STOP_HOOK_COMMAND)),
+  };
+
+  const scriptChecks = {
+    SessionStart: existsSync(join(homeDir, '.codex', 'hooks', 'aw-session-start.sh')),
+    UserPromptSubmit: existsSync(join(homeDir, '.codex', 'hooks', 'aw-user-prompt-submit.sh')),
+    PreToolUse: existsSync(join(homeDir, '.codex', 'hooks', 'aw-pre-tool-use.sh')),
+    PostToolUse: existsSync(join(homeDir, '.codex', 'hooks', 'aw-post-tool-use.sh')),
+    Stop: existsSync(join(homeDir, '.codex', 'hooks', 'aw-stop.sh')),
+  };
+
+  const missingPhases = supportedPhases.filter(phase => !phaseChecks[phase]);
+  const missingScripts = supportedPhases.filter(phase => !scriptChecks[phase]);
+
+  return { ok: missingPhases.length === 0 && missingScripts.length === 0, supportedPhases, missingPhases, missingScripts };
+}
+
+function getCursorHomeHookCoverage(homeDir) {
+  const supportedEntries = getSupportedHarnessPhaseEntries('cursor', 'home');
+  const supportedPhases = supportedEntries.map(entry => entry.phase);
+  const hooksPath = join(homeDir, '.cursor', 'hooks.json');
+  const hooksConfig = readJson(hooksPath, {});
+  const phaseChecks = {
+    SessionStart: Array.isArray(hooksConfig?.hooks?.sessionStart) && hooksConfig.hooks.sessionStart.length > 0,
+    UserPromptSubmit: Array.isArray(hooksConfig?.hooks?.beforeSubmitPrompt) && hooksConfig.hooks.beforeSubmitPrompt.length > 0,
+    PreToolUse: Array.isArray(hooksConfig?.hooks?.beforeShellExecution)
+      && hooksConfig.hooks.beforeShellExecution.length > 0
+      && Array.isArray(hooksConfig?.hooks?.beforeMCPExecution)
+      && hooksConfig.hooks.beforeMCPExecution.length > 0,
+    PostToolUse: Array.isArray(hooksConfig?.hooks?.afterShellExecution)
+      && hooksConfig.hooks.afterShellExecution.length > 0
+      && Array.isArray(hooksConfig?.hooks?.afterFileEdit)
+      && hooksConfig.hooks.afterFileEdit.length > 0
+      && Array.isArray(hooksConfig?.hooks?.afterMCPExecution)
+      && hooksConfig.hooks.afterMCPExecution.length > 0,
+    Stop: Array.isArray(hooksConfig?.hooks?.stop) && hooksConfig.hooks.stop.length > 0,
+    SessionEnd: Array.isArray(hooksConfig?.hooks?.sessionEnd) && hooksConfig.hooks.sessionEnd.length > 0,
+    PreCompact: Array.isArray(hooksConfig?.hooks?.preCompact) && hooksConfig.hooks.preCompact.length > 0,
+  };
+
+  const scriptChecks = {
+    SessionStart: existsSync(join(homeDir, '.cursor', 'hooks', 'session-start.js')),
+    UserPromptSubmit: existsSync(join(homeDir, '.cursor', 'hooks', 'before-submit-prompt.js')),
+    PreToolUse: existsSync(join(homeDir, '.cursor', 'hooks', 'before-shell-execution.js'))
+      && existsSync(join(homeDir, '.cursor', 'hooks', 'before-mcp-execution.js')),
+    PostToolUse: existsSync(join(homeDir, '.cursor', 'hooks', 'after-shell-execution.js'))
+      && existsSync(join(homeDir, '.cursor', 'hooks', 'after-file-edit.js'))
+      && existsSync(join(homeDir, '.cursor', 'hooks', 'after-mcp-execution.js')),
+    Stop: existsSync(join(homeDir, '.cursor', 'hooks', 'stop.js')),
+    SessionEnd: existsSync(join(homeDir, '.cursor', 'hooks', 'session-end.js')),
+    PreCompact: existsSync(join(homeDir, '.cursor', 'hooks', 'pre-compact.js')),
+  };
+
+  const missingPhases = supportedPhases.filter(phase => !phaseChecks[phase]);
+  const missingScripts = supportedPhases.filter(phase => !scriptChecks[phase]);
+
+  return { ok: missingPhases.length === 0 && missingScripts.length === 0, supportedPhases, missingPhases, missingScripts };
+}
+
+function getClaudePluginSessionStartStatus(pluginRoot) {
+  const hooksConfig = readJson(join(pluginRoot, 'hooks', 'hooks.json'), {});
+  if (!Array.isArray(hooksConfig?.hooks?.SessionStart)) {
+    return { ok: false, reason: 'missing' };
+  }
+
+  for (const entry of hooksConfig.hooks.SessionStart) {
+    if (!String(entry?.matcher || '').includes('startup') || !Array.isArray(entry?.hooks)) continue;
+    for (const hook of entry.hooks) {
+      if (hook?.type !== 'command') continue;
+      const command = String(hook?.command || '');
+      if (
+        command === CLAUDE_POSIX_HOOK_COMMAND
+        || command === CLAUDE_PORTABLE_HOOK_COMMAND
+        || command === CLAUDE_POSIX_BASH_LC_COMMAND
+        || command === CLAUDE_PORTABLE_BASH_LC_COMMAND
+      ) {
+        return { ok: true, command };
+      }
+      if (command === CLAUDE_WINDOWS_HOOK_COMMAND) {
+        return process.platform === 'win32'
+          ? { ok: true, command }
+          : { ok: false, reason: 'platform-incompatible', command };
+      }
+      if (command.includes('session-start')) {
+        return { ok: false, reason: 'unexpected-command', command };
+      }
+    }
+  }
+
+  return { ok: false, reason: 'missing' };
+}
+
+function getClaudeHomeSessionStartStatus(homeDir) {
+  const hooksPath = join(homeDir, '.claude', 'hooks', 'hooks.json');
+  if (!existsSync(hooksPath)) {
+    return { present: false, ok: true, reason: 'absent' };
+  }
+
+  const hooksConfig = readJson(hooksPath, {});
+  if (!Array.isArray(hooksConfig?.hooks?.SessionStart)) {
+    return { present: true, ok: true, reason: 'missing' };
+  }
+
+  for (const entry of hooksConfig.hooks.SessionStart) {
+    if (!String(entry?.matcher || '').includes('startup') || !Array.isArray(entry?.hooks)) continue;
+    for (const hook of entry.hooks) {
+      if (hook?.type !== 'command') continue;
+      const command = String(hook?.command || '');
+      if (command === CLAUDE_PORTABLE_HOOK_COMMAND || command === CLAUDE_PORTABLE_BASH_LC_COMMAND) {
+        return { present: true, ok: true, command };
+      }
+      if (command === CLAUDE_POSIX_HOOK_COMMAND || command === CLAUDE_POSIX_BASH_LC_COMMAND) {
+        return { present: true, ok: true, command };
+      }
+      if (command === CLAUDE_WINDOWS_HOOK_COMMAND) {
+        return process.platform === 'win32'
+          ? { present: true, ok: true, command }
+          : { present: true, ok: false, reason: 'platform-incompatible', command };
+      }
+      if (command.includes('session-start')) {
+        return { present: true, ok: false, reason: 'unexpected-command', command };
+      }
+    }
+  }
+
+  return { present: true, ok: true, reason: 'missing' };
+}
+
+function getProjectClaudeSessionStartStatus(cwd) {
+  const settingsPath = join(cwd, '.claude', 'settings.json');
+  if (!existsSync(settingsPath)) {
+    return { present: false, ok: true, reason: 'absent' };
+  }
+
+  const settings = readJson(settingsPath, {});
+  if (!Array.isArray(settings?.hooks?.SessionStart)) {
+    return { present: true, ok: true, reason: 'missing' };
+  }
+
+  for (const entry of settings.hooks.SessionStart) {
+    if (!Array.isArray(entry?.hooks)) continue;
+    for (const hook of entry.hooks) {
+      if (hook?.type !== 'command') continue;
+      const command = String(hook?.command || '');
+      if (command !== REPO_CLAUDE_SESSION_START_COMMAND && !command.includes('hooks/aw-session-start')) continue;
+      const targetPath = join(cwd, 'hooks', 'aw-session-start');
+      if (!existsSync(targetPath)) {
+        return { present: true, ok: false, reason: 'missing-target', command, targetPath };
+      }
+      return { present: true, ok: false, reason: 'legacy-present', command, targetPath };
+    }
+  }
+
+  return { present: true, ok: true, reason: 'missing' };
+}
+
+function textHasRulesReference(text) {
+  return text.includes('Platform Rules') && text.includes('.aw/.aw_rules/platform/');
+}
+
+function textHasManagedRouterBridge(text) {
+  return text.includes(AW_ROUTER_BRIDGE_START_MARKER)
+    && text.includes(AW_ROUTER_BRIDGE_END_MARKER)
+    && text.includes('## AW Router Bridge')
+    && text.includes('### 1. Route First (MANDATORY)')
+    && text.includes('### 5. Verify With Proof')
+    && text.includes('using-aw-skills')
+    && text.includes('incremental-implementation');
+}
+
+function extractRuleReferencePaths(text) {
+  const matches = [];
+  const pattern = /(?:\]\(|`)([^)\n`]*(?:\.aw_rules|\.aw_registry\/\.aw_rules)\/[^)\n`]+\.md)(?:\)|`)/g;
+  for (const match of text.matchAll(pattern)) {
+    if (match[1]) matches.push(match[1]);
+  }
+  return [...new Set(matches)];
+}
+
+function listGeneratedRuleFiles(dirPath, extension) {
+  if (!existsSync(dirPath)) return [];
+  try {
+    return readdirSync(dirPath, { withFileTypes: true })
+      .filter(entry => entry.isFile() && entry.name.endsWith(extension))
+      .map(entry => join(dirPath, entry.name))
+      .filter(filePath => readText(filePath).startsWith(GENERATED_RULE_HEADER));
+  } catch {
+    return [];
+  }
+}
+
+function findBrokenRuleReferences(filePaths) {
+  const broken = [];
+  for (const filePath of filePaths) {
+    const content = readText(filePath);
+    const refs = extractRuleReferencePaths(content);
+    for (const ref of refs) {
+      if (ref.includes('<domain>')) continue;
+      const resolvedPath = join(dirname(filePath), ref);
+      if (!existsSync(resolvedPath)) {
+        broken.push({ filePath, ref, resolvedPath });
+      }
+    }
+  }
+  return broken;
+}
+
+function missingCorePromptFiles(promptsDir) {
+  return EXPECTED_AW_ROUTES
+    .map(route => `aw-${route}.md`)
+    .filter(fileName => !existsSync(join(promptsDir, fileName)));
+}
+
+function missingCoreCursorCommandFiles(commandsDir) {
+  return EXPECTED_AW_ROUTES
+    .map(route => `${route}.md`)
+    .filter(fileName => !existsSync(join(commandsDir, fileName)));
+}
+
+function missingCoreClaudeCommandFiles(pluginRoot) {
+  return EXPECTED_AW_ROUTES
+    .map(route => `commands/${route}.md`)
+    .filter(relativePath => !existsSync(join(pluginRoot, relativePath)));
+}
+
+function buildDoctorChecks(homeDir, cwd) {
+  const startup = getStartupStatus(homeDir);
+  const checks = [];
+  const awRegistryDir = resolveAwRegistryDir(homeDir);
+  const rulesDir = resolveRulesDir(homeDir);
+
+  const usingAwHookPath = [
+    join(homeDir, '.aw_registry', 'platform', 'core', 'skills', 'using-aw-skills', 'hooks', 'session-start.sh'),
+    join(homeDir, '.aw', '.aw_registry', 'platform', 'core', 'skills', 'using-aw-skills', 'hooks', 'session-start.sh'),
+  ].find(existsSync);
+
+  checks.push(usingAwHookPath
+    ? makeCheck('runtime-hook', 'AW runtime hook', 'pass', `Found using-aw-skills hook at ${usingAwHookPath.replace(`${homeDir}/`, '~/')}`)
+    : makeCheck('runtime-hook', 'AW runtime hook', 'fail', 'using-aw-skills hook is missing from ~/.aw_registry', 'Run `aw init` or `aw pull platform` to restore the AW runtime hook.'),
+  );
+
+  checks.push(startup.mode === 'enabled'
+    ? makeCheck('routing-mode', 'Routing mode', 'pass', `Global routing mode is ${startup.mode}`)
+    : makeCheck('routing-mode', 'Routing mode', 'warn', 'Global routing mode is disabled', 'Run `aw routing enable` if you want automatic AW startup behavior.'),
+  );
+
+  if (!rulesDir) {
+    checks.push(makeCheck(
+      'aw-rules-source',
+      'AW rules source',
+      'fail',
+      'No synced .aw/.aw_rules tree found under ~/.aw/.aw_rules',
+      'Run `aw init` or `aw pull platform` to sync the AW rules source into ~/.aw/.aw_rules.',
+    ));
+  } else {
+    const topLevelRulesAgents = join(rulesDir, 'AGENTS.md');
+    const domainRuleCount = countDomainRuleFiles(rulesDir);
+    checks.push(
+      existsSync(topLevelRulesAgents) && domainRuleCount > 0
+        ? makeCheck('aw-rules-source', 'AW rules source', 'pass', `Rules source is synced (${domainRuleCount} domain AGENTS.md files detected)`)
+        : makeCheck(
+          'aw-rules-source',
+          'AW rules source',
+          'fail',
+          'Rules source is incomplete under ~/.aw/.aw_rules',
+          'Run `aw pull platform` to refresh .aw/.aw_rules, then rerun `aw doctor`.',
+        ),
+    );
+  }
+
+  if (cwd !== homeDir) {
+    const projectAgentsPath = join(cwd, 'AGENTS.md');
+    const projectClaudePath = join(cwd, 'CLAUDE.md');
+    const projectAgentsHasBridge = existsSync(projectAgentsPath) && textHasManagedRouterBridge(readText(projectAgentsPath));
+    const projectClaudeExists = existsSync(projectClaudePath);
+    const projectClaudeHasBridge = projectClaudeExists && textHasManagedRouterBridge(readText(projectClaudePath));
+
+    checks.push(
+      !projectAgentsHasBridge && !projectClaudeHasBridge
+        ? makeCheck('project-router-bridge', 'Current repo router bridge', 'pass', 'Current repo does not carry a stale managed AW Router Bridge block')
+        : makeCheck(
+          'project-router-bridge',
+          'Current repo router bridge',
+          'warn',
+          projectAgentsHasBridge
+            ? 'Current repo AGENTS.md still carries a stale managed AW Router Bridge block'
+            : 'Current repo CLAUDE.md still carries a stale managed AW Router Bridge block',
+          'Run `aw init` to move the managed AW Router Bridge into the user-home harness files and remove stale repo-local copies.',
+        ),
+    );
+
+    const projectClaudeSessionStartStatus = getProjectClaudeSessionStartStatus(cwd);
+    if (!projectClaudeSessionStartStatus.ok) {
+      checks.push(makeCheck(
+        'project-claude-session-start',
+        'Current repo Claude session-start hook',
+        projectClaudeSessionStartStatus.reason === 'missing-target' ? 'fail' : 'warn',
+        projectClaudeSessionStartStatus.reason === 'missing-target'
+          ? `Current repo .claude/settings.json points SessionStart at missing ${projectClaudeSessionStartStatus.targetPath.replace(`${cwd}/`, '')}`
+          : 'Current repo still has a legacy Claude SessionStart hook wired through repo-local hooks/aw-session-start',
+        'Run `aw link` from the project root to remove or refresh legacy repo-local Claude startup hooks.',
+      ));
+    } else {
+      checks.push(makeCheck('project-claude-session-start', 'Current repo Claude session-start hook', 'pass', 'No legacy project-local Claude SessionStart hook detected'));
+    }
+
+    checks.push(
+      hasLegacyRepoStartupDefaults(cwd)
+        ? makeCheck('repo-legacy-routing', 'Current repo routing defaults', 'warn', 'Legacy repo-local routing files are still present in the current workspace', 'Run `aw routing enable` to clean repo-local startup defaults and prefer the global-managed setup.')
+        : makeCheck('repo-legacy-routing', 'Current repo routing defaults', 'pass', 'No legacy repo-local routing files detected in the current workspace'),
+    );
+  }
+
+  const claudeSettingsPath = join(homeDir, '.claude', 'settings.json');
+  const claudeSettings = readJson(claudeSettingsPath, {});
+  const claudePluginEnabled = claudeSettings.enabledPlugins?.[CLAUDE_PLUGIN_NAME] === true;
+  const { version: claudePluginVersion, root: claudePluginRoot } = findClaudePlugin(homeDir);
+  if (claudePluginEnabled && claudePluginVersion) {
+    checks.push(makeCheck('claude-plugin', 'Claude plugin', 'pass', `${CLAUDE_PLUGIN_NAME} is enabled (cache version ${claudePluginVersion})`));
+  } else if (claudePluginEnabled) {
+    checks.push(makeCheck('claude-plugin', 'Claude plugin', 'fail', 'Claude settings enable the AW plugin, but no plugin cache version is installed', 'Reinstall the AW Claude plugin by re-running `aw init` or the Claude plugin install flow.'));
+  } else {
+    checks.push(makeCheck('claude-plugin', 'Claude plugin', 'warn', 'Claude plugin is not enabled in ~/.claude/settings.json', 'Enable or reinstall the AW Claude plugin if you expect Claude startup hydration.'));
+  }
+
+  if (claudePluginRoot) {
+    const claudeSessionStartStatus = getClaudePluginSessionStartStatus(claudePluginRoot);
+    const missingBundleFiles = missingFiles(claudePluginRoot, [
+      '.claude-plugin/plugin.json',
+      'hooks/hooks.json',
+      'skills/using-aw-skills/SKILL.md',
+      'skills/using-aw-skills/hooks/session-start.sh',
+    ]);
+    checks.push(
+      missingBundleFiles.length === 0 && claudeSessionStartStatus.ok
+        ? makeCheck('claude-plugin-bundle', 'Claude plugin bundle', 'pass', 'Claude plugin bundle contains AW routing hooks and router skill files')
+        : makeCheck(
+          'claude-plugin-bundle',
+          'Claude plugin bundle',
+          'fail',
+          missingBundleFiles.length > 0
+            ? `Claude plugin bundle is missing: ${missingBundleFiles.join(', ')}`
+            : claudeSessionStartStatus.reason === 'platform-incompatible'
+              ? `Claude plugin bundle uses a Windows-only SessionStart command on ${process.platform}: ${claudeSessionStartStatus.command}`
+              : claudeSessionStartStatus.reason === 'unexpected-command'
+                ? `Claude plugin bundle has an unexpected SessionStart command: ${claudeSessionStartStatus.command}`
+                : 'Claude plugin bundle is installed but hooks/hooks.json is missing the managed SessionStart routing hook',
+          'Reinstall or refresh the AW Claude plugin so hooks/hooks.json uses the managed SessionStart shell entrypoint for the current platform.',
+        ),
+    );
+
+    const missingPluginCommands = missingCoreClaudeCommandFiles(claudePluginRoot);
+    checks.push(
+      missingPluginCommands.length === 0
+        ? makeCheck('claude-plugin-commands', 'Claude public commands', 'pass', 'Claude plugin bundle exposes the current AW command surface (primary, conditional, and compatibility routes)')
+        : makeCheck(
+          'claude-plugin-commands',
+          'Claude public commands',
+          'fail',
+          `Claude plugin bundle is missing core command files: ${missingPluginCommands.join(', ')}`,
+          'Refresh the AW Claude plugin so the plugin bundle includes the full AW public command surface.',
+        ),
+    );
+  } else {
+    checks.push(makeCheck('claude-plugin-bundle', 'Claude plugin bundle', 'warn', 'Claude plugin bundle is not installed', 'Enable/install the AW Claude plugin, then rerun `aw doctor`.'));
+    checks.push(makeCheck('claude-plugin-commands', 'Claude public commands', 'warn', 'Claude plugin command bundle could not be inspected because the plugin is not installed'));
+  }
+
+  const claudeLegacyHooks = parseLegacyClaudeHookTargets(claudeSettings?.hooks?.SessionStart || []);
+  const claudeHomeSessionStartStatus = getClaudeHomeSessionStartStatus(homeDir);
+  const claudeHomeHookCoverage = getClaudeHomeHookCoverage(homeDir);
+  if (claudeLegacyHooks.length > 0) {
+    const brokenTargets = claudeLegacyHooks.filter(target => !target.path || !existsSync(target.path));
+    checks.push(makeCheck(
+      'claude-session-start',
+      'Claude session-start hook',
+      brokenTargets.length > 0 ? 'fail' : 'warn',
+      brokenTargets.length > 0
+        ? `Legacy Claude SessionStart hook points at missing path ${brokenTargets[0].path || '<unknown>'}`
+        : 'Legacy Claude SessionStart hook is still present',
+      'Run `aw routing enable` to clean legacy Claude SessionStart hooks.',
+    ));
+  } else if (startup.claudeDisabled) {
+    checks.push(makeCheck('claude-session-start', 'Claude session-start hook', 'warn', 'Claude automatic startup routing is disabled via ~/.claude/settings.json', 'Run `aw routing enable` to restore Claude startup routing.'));
+  } else if (!claudeHomeSessionStartStatus.ok) {
+    checks.push(makeCheck(
+      'claude-session-start',
+      'Claude session-start hook',
+      'fail',
+      claudeHomeSessionStartStatus.reason === 'platform-incompatible'
+        ? `~/.claude/hooks/hooks.json uses a Windows-only SessionStart command on ${process.platform}: ${claudeHomeSessionStartStatus.command}`
+        : `~/.claude/hooks/hooks.json has an unexpected SessionStart command: ${claudeHomeSessionStartStatus.command}`,
+      'Refresh the home-level Claude hooks so SessionStart uses the managed portable shell entrypoint.',
+    ));
+  } else {
+    checks.push(makeCheck('claude-session-start', 'Claude session-start hook', 'pass', 'No stale Claude SessionStart override detected'));
+  }
+
+  checks.push(
+    claudeHomeHookCoverage.ok
+      ? makeCheck(
+        'claude-home-hooks',
+        'Claude home hook phases',
+        'pass',
+        `Claude home hooks cover all supported AW phases: ${formatPhaseSummary(claudeHomeHookCoverage.supportedPhases)}`,
+      )
+      : makeCheck(
+        'claude-home-hooks',
+        'Claude home hook phases',
+        'fail',
+        `Claude home hooks are missing core phases: ${formatMissingParts(claudeHomeHookCoverage.missingPhases)}`,
+        'Run `aw init` to refresh ~/.claude/hooks/hooks.json with the full home-level AW hook phase set.',
+      ),
+  );
+
+  const claudeInstallStatePath = join(homeDir, '.claude', 'ecc', 'install-state.json');
+  checks.push(existsSync(claudeInstallStatePath)
+    ? makeCheck('claude-install-state', 'Claude install state', 'pass', 'Claude install-state file is present')
+    : makeCheck('claude-install-state', 'Claude install state', 'fail', 'Claude install-state file is missing', globalInstallStateFix(homeDir, cwd, 'Claude install state')),
+  );
+
+  const claudeMcp = jsonMcpHealth(join(homeDir, '.claude.json'));
+  checks.push(
+    claudeMcp.present && claudeMcp.url && claudeMcp.authorization
+      ? makeCheck('claude-mcp', 'Claude MCP config', 'pass', 'Claude has a ghl-ai MCP server with URL and Authorization header')
+      : makeCheck(
+        'claude-mcp',
+        'Claude MCP config',
+        'fail',
+        `Claude MCP is incomplete (present=${claudeMcp.present}, url=${claudeMcp.url}, authorization=${claudeMcp.authorization})`,
+        'Run `aw init` to rewrite ~/.claude.json with a healthy ghl-ai MCP configuration.',
+      ),
+  );
+
+  const claudeRefPath = join(homeDir, '.claude', 'references', 'route-selection-patterns.md');
+  checks.push(
+    existsSync(claudeRefPath)
+      ? makeCheck('claude-references', 'Claude shared references', 'pass', 'Claude shared references are materialized')
+      : makeCheck('claude-references', 'Claude shared references', 'fail', 'Claude shared references are missing', projectRelinkFix(homeDir, cwd, '~/.claude/references')),
+  );
+
+  const claudeRulesDir = join(homeDir, '.claude', 'rules', 'platform');
+  const claudeHomeInstructionsPath = join(homeDir, '.claude', 'CLAUDE.md');
+  checks.push(
+    existsSync(claudeHomeInstructionsPath) && textHasManagedRouterBridge(readText(claudeHomeInstructionsPath))
+      ? makeCheck('claude-home-instructions', 'Claude home instructions', 'pass', 'Claude home CLAUDE.md includes the managed AW Router Bridge block')
+      : makeCheck(
+        'claude-home-instructions',
+        'Claude home instructions',
+        'fail',
+        existsSync(claudeHomeInstructionsPath)
+          ? 'Claude home CLAUDE.md is present but missing the managed AW Router Bridge block'
+          : 'Claude home CLAUDE.md is missing',
+        'Run `aw init` to regenerate ~/.claude/CLAUDE.md with the managed AW Router Bridge block.',
+      ),
+  );
+
+  checks.push(
+    rulesDir && directoryContainsGeneratedRuleFiles(claudeRulesDir, '.md')
+      ? makeCheck('claude-rules', 'Claude AW rules', 'pass', 'Claude has generated platform rules under ~/.claude/rules/platform/')
+      : makeCheck(
+        'claude-rules',
+        'Claude AW rules',
+        rulesDir ? 'fail' : 'warn',
+        rulesDir ? 'Claude platform rules are missing or not generated by AW' : 'Claude platform rules were not checked because .aw/.aw_rules is not synced',
+        'Run `aw pull platform` or `aw init` to render Claude platform rules.',
+      ),
+  );
+
+  const claudeRuleFiles = listGeneratedRuleFiles(claudeRulesDir, '.md');
+  const brokenClaudeRuleRefs = findBrokenRuleReferences(claudeRuleFiles);
+  checks.push(
+    claudeRuleFiles.length === 0
+      ? makeCheck(
+        'claude-rule-references',
+        'Claude rule references',
+        rulesDir ? 'fail' : 'warn',
+        rulesDir ? 'Claude generated rule files are missing, so reference links could not be validated' : 'Claude rule references were not checked because .aw/.aw_rules is not synced',
+        'Run `aw pull platform` or `aw init` to render Claude rules, then rerun `aw doctor`.',
+      )
+      : brokenClaudeRuleRefs.length === 0
+        ? makeCheck('claude-rule-references', 'Claude rule references', 'pass', 'Claude generated rule references resolve to real files in ~/.aw/.aw_rules')
+        : makeCheck(
+          'claude-rule-references',
+          'Claude rule references',
+          'fail',
+          `Claude rule reference is broken in ${brokenClaudeRuleRefs[0].filePath.replace(`${homeDir}/`, '~/')}: ${brokenClaudeRuleRefs[0].ref}`,
+          'Refresh the rendered Claude rules so embedded reference links point at real files under ~/.aw/.aw_rules.',
+        ),
+  );
+
+  const claudeAgentsDir = join(homeDir, '.claude', 'agents');
+  checks.push(
+    directoryContainsRegistrySymlink(claudeAgentsDir)
+      ? makeCheck('claude-agents', 'Claude linked agents', 'pass', 'Claude agents include symlinks into ~/.aw_registry')
+      : makeCheck(
+        'claude-agents',
+        'Claude linked agents',
+        awRegistryDir ? 'fail' : 'warn',
+        'Claude agents directory is missing registry-backed symlinks',
+        projectRelinkFix(homeDir, cwd, 'registry agents under ~/.claude/agents'),
+      ),
+  );
+
+  const codexConfigPath = join(homeDir, '.codex', 'config.toml');
+  const codexHooksPath = join(homeDir, '.codex', 'hooks.json');
+  const codexRuntimePath = join(homeDir, '.codex', 'hooks', 'aw-session-start.sh');
+  const codexHomeHookCoverage = getCodexHomeHookCoverage(homeDir);
+  const codexHealthy = startup.codexHooksEnabled && codexHomeHookCoverage.ok;
+  checks.push(codexHealthy
+    ? makeCheck(
+      'codex-routing',
+      'Codex routing',
+      'pass',
+      `Codex home hooks cover all supported AW phases: ${formatPhaseSummary(codexHomeHookCoverage.supportedPhases)}`,
+    )
+    : makeCheck(
+      'codex-routing',
+      'Codex routing',
+      startup.mode === 'disabled' ? 'warn' : 'fail',
+      `Codex routing incomplete (codex_hooks=${parseCodexHooksFile(codexConfigPath)}, missing phases=${formatMissingParts(codexHomeHookCoverage.missingPhases)}, missing scripts=${formatMissingParts(codexHomeHookCoverage.missingScripts)})`,
+      'Run `aw routing enable` or `aw init` to restore Codex startup wiring.',
+    ),
+  );
+
+  const codexInstallStatePath = join(homeDir, '.codex', 'ecc-install-state.json');
+  checks.push(existsSync(codexInstallStatePath)
+    ? makeCheck('codex-install-state', 'Codex install state', 'pass', 'Codex install-state file is present')
+    : makeCheck('codex-install-state', 'Codex install state', 'fail', 'Codex install-state file is missing', globalInstallStateFix(homeDir, cwd, 'Codex install state')),
+  );
+
+  const codexMcp = tomlMcpHealth(codexConfigPath);
+  checks.push(
+    codexMcp.present && codexMcp.url && codexMcp.authorization
+      ? makeCheck('codex-mcp', 'Codex MCP config', 'pass', 'Codex has a ghl-ai MCP server with URL and Authorization header')
+      : makeCheck(
+        'codex-mcp',
+        'Codex MCP config',
+        'fail',
+        `Codex MCP is incomplete (present=${codexMcp.present}, url=${codexMcp.url}, authorization=${codexMcp.authorization})`,
+        'Run `aw init` to rewrite ~/.codex/config.toml with a healthy ghl-ai MCP configuration.',
+      ),
+  );
+
+  const codexRefPath = join(homeDir, '.codex', 'references', 'route-selection-patterns.md');
+  checks.push(
+    existsSync(codexRefPath)
+      ? makeCheck('codex-references', 'Codex shared references', 'pass', 'Codex shared references are materialized')
+      : makeCheck('codex-references', 'Codex shared references', 'fail', 'Codex shared references are missing', projectRelinkFix(homeDir, cwd, '~/.codex/references')),
+  );
+
+  const missingPrompts = missingCorePromptFiles(join(homeDir, '.codex', 'prompts'));
+  checks.push(
+      missingPrompts.length === 0
+      ? makeCheck('codex-prompts', 'Codex prompts', 'pass', 'Codex prompt sync produced the current AW prompt surface (primary, conditional, and compatibility routes)')
+      : makeCheck(
+        'codex-prompts',
+        'Codex prompts',
+        'fail',
+        `Codex is missing core prompt files: ${missingPrompts.join(', ')}`,
+        'Run `aw init` or refresh the AW ECC bundle to regenerate the Codex prompts.',
+      ),
+  );
+
+  const codexAgentsPath = join(homeDir, '.codex', 'AGENTS.md');
+  checks.push(
+    existsSync(codexAgentsPath) && textHasManagedRouterBridge(readText(codexAgentsPath)) && textHasRulesReference(readText(codexAgentsPath))
+      ? makeCheck('codex-agents-md', 'Codex AGENTS.md', 'pass', 'Codex AGENTS.md includes the managed AW Router Bridge block and AW rules reference table')
+      : makeCheck(
+        'codex-agents-md',
+        'Codex AGENTS.md',
+        rulesDir ? 'fail' : 'warn',
+        existsSync(codexAgentsPath)
+          ? 'Codex AGENTS.md is present but missing the managed AW Router Bridge block or AW rules reference table'
+          : 'Codex AGENTS.md is missing',
+        'Re-run `aw init` so Codex instructions are regenerated with the managed AW Router Bridge block and AW rules reference table.',
+      ),
+  );
+
+  const codexAgentsText = readText(codexAgentsPath);
+  const codexBrokenRuleRefs = existsSync(codexAgentsPath) ? findBrokenRuleReferences([codexAgentsPath]) : [];
+  checks.push(
+    existsSync(codexAgentsPath) && textHasRulesReference(codexAgentsText)
+      ? codexBrokenRuleRefs.length === 0
+        ? makeCheck('codex-rule-references', 'Codex rule references', 'pass', 'Codex AGENTS.md points at real AW rule files')
+        : makeCheck(
+          'codex-rule-references',
+          'Codex rule references',
+          'fail',
+          `Codex AGENTS.md has a broken AW rule path: ${codexBrokenRuleRefs[0].ref}`,
+          'Regenerate ~/.codex/AGENTS.md so its AW rule paths resolve correctly from the Codex home directory.',
+        )
+      : makeCheck(
+        'codex-rule-references',
+        'Codex rule references',
+        rulesDir ? 'warn' : 'warn',
+        existsSync(codexAgentsPath)
+          ? 'Codex rule references were not checked because ~/.codex/AGENTS.md is missing the AW rules reference table'
+          : 'Codex rule references were not checked because ~/.codex/AGENTS.md is missing',
+      ),
+  );
+
+  const cursorHooksPath = join(homeDir, '.cursor', 'hooks.json');
+  const cursorRuntimePath = join(homeDir, '.cursor', 'hooks', 'session-start.js');
+  const cursorHomeHookCoverage = getCursorHomeHookCoverage(homeDir);
+  const cursorHealthy = cursorHomeHookCoverage.ok;
+  checks.push(cursorHealthy
+    ? makeCheck(
+      'cursor-routing',
+      'Cursor routing',
+      'pass',
+      `Cursor home hooks cover all supported AW phases: ${formatPhaseSummary(cursorHomeHookCoverage.supportedPhases)}`,
+    )
+    : makeCheck(
+      'cursor-routing',
+      'Cursor routing',
+      startup.mode === 'disabled' ? 'warn' : 'fail',
+      `Cursor routing incomplete (missing phases=${formatMissingParts(cursorHomeHookCoverage.missingPhases)}, missing scripts=${formatMissingParts(cursorHomeHookCoverage.missingScripts)})`,
+      'Run `aw routing enable` or `aw init` to restore Cursor startup wiring.',
+    ),
+  );
+
+  const cursorInstallStatePath = join(homeDir, '.cursor', 'ecc-install-state.json');
+  checks.push(existsSync(cursorInstallStatePath)
+    ? makeCheck('cursor-install-state', 'Cursor install state', 'pass', 'Cursor install-state file is present')
+    : makeCheck('cursor-install-state', 'Cursor install state', 'fail', 'Cursor install-state file is missing', globalInstallStateFix(homeDir, cwd, 'Cursor install state')),
+  );
+
+  const cursorCommandsDir = join(homeDir, '.cursor', 'commands', 'aw');
+  const missingCursorCommands = missingCoreCursorCommandFiles(cursorCommandsDir);
+  checks.push(
+    missingCursorCommands.length === 0
+      ? makeCheck('cursor-commands', 'Cursor public commands', 'pass', 'Cursor has the current AW command surface under ~/.cursor/commands/aw/')
+      : makeCheck(
+        'cursor-commands',
+        'Cursor public commands',
+        'fail',
+        `Cursor is missing core command files: ${missingCursorCommands.join(', ')}`,
+        projectRelinkFix(homeDir, cwd, 'AW command files under ~/.cursor/commands/aw/'),
+      ),
+  );
+
+  const cursorMcp = jsonMcpHealth(join(homeDir, '.cursor', 'mcp.json'));
+  checks.push(
+    cursorMcp.present && cursorMcp.url && cursorMcp.authorization
+      ? makeCheck('cursor-mcp', 'Cursor MCP config', 'pass', 'Cursor has a ghl-ai MCP server with URL and Authorization header')
+      : makeCheck(
+        'cursor-mcp',
+        'Cursor MCP config',
+        'fail',
+        `Cursor MCP is incomplete (present=${cursorMcp.present}, url=${cursorMcp.url}, authorization=${cursorMcp.authorization})`,
+        'Run `aw init` to rewrite ~/.cursor/mcp.json with a healthy ghl-ai MCP configuration.',
+      ),
+  );
+
+  const cursorRefPath = join(homeDir, '.cursor', 'references', 'route-selection-patterns.md');
+  const cursorAgentsPath = join(homeDir, '.cursor', 'AGENTS.md');
+  checks.push(
+    existsSync(cursorAgentsPath) && textHasManagedRouterBridge(readText(cursorAgentsPath))
+      ? makeCheck('cursor-home-instructions', 'Cursor home instructions', 'pass', 'Cursor home AGENTS.md includes the managed AW Router Bridge block')
+      : makeCheck(
+        'cursor-home-instructions',
+        'Cursor home instructions',
+        'fail',
+        existsSync(cursorAgentsPath)
+          ? 'Cursor home AGENTS.md is present but missing the managed AW Router Bridge block'
+          : 'Cursor home AGENTS.md is missing',
+        'Run `aw init` to regenerate ~/.cursor/AGENTS.md with the managed AW Router Bridge block.',
+      ),
+  );
+  checks.push(
+    existsSync(cursorRefPath)
+      ? makeCheck('cursor-references', 'Cursor shared references', 'pass', 'Cursor shared references are materialized')
+      : makeCheck('cursor-references', 'Cursor shared references', 'fail', 'Cursor shared references are missing', projectRelinkFix(homeDir, cwd, '~/.cursor/references')),
+  );
+
+  checks.push(
+    rulesDir && directoryContainsGeneratedRuleFiles(join(homeDir, '.cursor', 'rules'), '.mdc')
+      ? makeCheck('cursor-rules', 'Cursor AW rules', 'pass', 'Cursor has generated AW rules under ~/.cursor/rules/')
+      : makeCheck(
+        'cursor-rules',
+        'Cursor AW rules',
+        rulesDir ? 'fail' : 'warn',
+        rulesDir ? 'Cursor rules are missing or not generated by AW' : 'Cursor rules were not checked because .aw/.aw_rules is not synced',
+        'Run `aw pull platform` or `aw init` to render Cursor rule files.',
+      ),
+  );
+
+  const cursorRulesDir = join(homeDir, '.cursor', 'rules');
+  const cursorRuleFiles = listGeneratedRuleFiles(cursorRulesDir, '.mdc');
+  const brokenCursorRuleRefs = findBrokenRuleReferences(cursorRuleFiles);
+  checks.push(
+    cursorRuleFiles.length === 0
+      ? makeCheck(
+        'cursor-rule-references',
+        'Cursor rule references',
+        rulesDir ? 'fail' : 'warn',
+        rulesDir ? 'Cursor generated rule files are missing, so reference links could not be validated' : 'Cursor rule references were not checked because .aw/.aw_rules is not synced',
+        'Run `aw pull platform` or `aw init` to render Cursor rules, then rerun `aw doctor`.',
+      )
+      : brokenCursorRuleRefs.length === 0
+        ? makeCheck('cursor-rule-references', 'Cursor rule references', 'pass', 'Cursor generated rule references resolve to real files in ~/.aw/.aw_rules')
+        : makeCheck(
+          'cursor-rule-references',
+          'Cursor rule references',
+          'fail',
+          `Cursor rule reference is broken in ${brokenCursorRuleRefs[0].filePath.replace(`${homeDir}/`, '~/')}: ${brokenCursorRuleRefs[0].ref}`,
+          'Refresh the rendered Cursor rules so embedded reference links point at real files under ~/.aw/.aw_rules.',
+        ),
+  );
+
+  const eccDir = join(homeDir, '.aw-ecc');
+  const eccSyncScript = join(eccDir, 'scripts', 'sync-ecc-to-codex.sh');
+  if (!existsSync(eccDir)) {
+    checks.push(makeCheck('aw-ecc', 'AW ECC bundle', 'warn', '~/.aw-ecc is not installed', 'Run `aw init` to install the bundled AW ECC workspace assets.'));
+  } else if (!existsSync(eccSyncScript)) {
+    checks.push(makeCheck('aw-ecc', 'AW ECC bundle', 'fail', 'AW ECC clone exists but sync-ecc-to-codex.sh is missing', 'Reinstall AW ECC with `aw init` to restore the bundled assets.'));
+  } else {
+    const currentTag = parseExactGitTag(eccDir);
+    const tagSummary = currentTag ? `tag ${currentTag}` : 'no exact tag';
+    checks.push(currentTag === AW_ECC_TAG
+      ? makeCheck('aw-ecc', 'AW ECC bundle', 'pass', `AW ECC clone present at expected ${tagSummary}`)
+      : makeCheck('aw-ecc', 'AW ECC bundle', 'warn', `AW ECC clone present but not on expected tag ${AW_ECC_TAG} (${tagSummary})`, 'Re-run `aw init` if you want the bundled AW ECC clone reset to the expected release tag.'),
+    );
+  }
+
+  return checks;
+}
+
+export function getDoctorReport(homeDir = homedir(), cwd = process.cwd()) {
+  const checks = buildDoctorChecks(homeDir, cwd);
+  const status = overallStatus(checks);
+  const fixes = [...new Set(checks.map(check => check.fix).filter(Boolean))];
+  return {
+    status,
+    checks,
+    fixes,
+  };
+}
+
+function statusIcon(status) {
+  switch (status) {
+    case 'pass': return chalk.green('✓');
+    case 'warn': return chalk.yellow('!');
+    default: return chalk.red('✖');
+  }
+}
+
+export function doctorCommand() {
+  const homeDir = homedir();
+  const report = getDoctorReport(homeDir, process.cwd());
+
+  fmt.intro('aw doctor');
+
+  const summary = report.checks
+    .map(check => `${statusIcon(check.status)} ${check.title}: ${check.summary}`)
+    .join('\n');
+  fmt.note(summary, `Health ${STATUS_LABEL[report.status]}`);
+
+  if (report.fixes.length > 0) {
+    fmt.note(report.fixes.map(fix => `- ${fix}`).join('\n'), 'Suggested Fixes');
+  }
+
+  if (report.status === 'fail') {
+    process.exitCode = 1;
+  }
+
+  fmt.outro(`⟁  aw doctor complete (${report.status.toUpperCase()})`);
+}