arkgate 2.3.0 → 2.4.0

package/bin/ark-check.mjs

@@ -37,6 +37,8 @@ import {
   resolveIntentLayer,
   resolveOperatingMode,
   shouldShowNewHereNudge,
+  usableTypescript,
+  typescriptUsabilityHint,
 } from './ark-shared.mjs';
 
 function parseArgs(argv) {
@@ -1051,49 +1053,89 @@ function writeTemplate(root, relativePath, content, force) {
 }
 
 /**
- * Normalize a required/imported TypeScript module. TS 5.x exposes `sys` on the root
- * export; TS 7+ (and some ESM interop shapes) may not — those are unusable for ark-check's
- * module resolution host, so we reject them and fall through to Ark's own TypeScript.
- */
-function usableTypescript(mod) {
-  if (!mod) return null;
-  const ts = mod.default && mod.sys == null ? mod.default : mod;
-  if (ts && typeof ts === 'object' && ts.sys && typeof ts.sys.fileExists === 'function') {
-    return ts;
-  }
-  return null;
-}
-
-/**
- * Load a TypeScript module with a working `sys`. Prefer the project's install when it is
- * API-compatible; otherwise Ark's dependency (or a bare import). Returns null only when
- * nothing usable is available.
+ * Load a TypeScript module with a working JS API host (`sys` + AST + resolve).
+ * Prefer the project's install when API-compatible (TS 5/6 + any TS 7 that still
+ * exposes the classic JS host). TypeScript 7.0.x main entry is version-only
+ * (`{ version, versionMajorMinor }`); programmatic APIs live under
+ * `typescript/unstable/*` and are not yet the gate's host — we fall through to
+ * ArkGate's own `typescript` dependency (JS-API 5.x) or a bare import.
+ * Returns `{ ts, source, version, fallbackReason? }` or null.
  */
 async function loadTypeScript(root) {
+  const { createRequire } = await import('node:module');
   const loaders = [];
   try {
-    const { createRequire } = await import('node:module');
     const req = createRequire(path.join(root, 'package.json'));
-    loaders.push(() => req('typescript'));
+    loaders.push({
+      label: 'project',
+      load: () => req('typescript'),
+      resolvePath: () => {
+        try {
+          return req.resolve('typescript');
+        } catch {
+          return null;
+        }
+      },
+    });
   } catch {
     /* project has no package.json resolvable tree */
   }
+  // Nested under arkgate (production dependency) — must work when project has only TS7.
   try {
-    const { createRequire } = await import('node:module');
     const req = createRequire(__arkCheckCli);
-    loaders.push(() => req('typescript'));
+    loaders.push({
+      label: 'arkgate',
+      load: () => req('typescript'),
+      resolvePath: () => {
+        try {
+          return req.resolve('typescript');
+        } catch {
+          return null;
+        }
+      },
+    });
   } catch {
     /* ark install tree unavailable */
   }
-  loaders.push(async () => {
-    const m = await import('typescript');
-    return m;
+  loaders.push({
+    label: 'import',
+    load: async () => {
+      const m = await import('typescript');
+      return m;
+    },
+    resolvePath: () => null,
   });
 
-  for (const load of loaders) {
+  let projectRejected = null;
+  const triedPaths = new Set();
+  for (const { label, load, resolvePath } of loaders) {
     try {
-      const ts = usableTypescript(await load());
-      if (ts) return ts;
+      const resolved = typeof resolvePath === 'function' ? resolvePath() : null;
+      if (resolved && triedPaths.has(resolved)) {
+        // Same physical package already rejected (e.g. project === hoisted arkgate path).
+        continue;
+      }
+      if (resolved) triedPaths.add(resolved);
+
+      const mod = await load();
+      const ts = usableTypescript(mod);
+      if (ts) {
+        const version =
+          typeof ts.version === 'string'
+            ? ts.version
+            : typeof mod?.version === 'string'
+              ? mod.version
+              : undefined;
+        return {
+          ts,
+          source: label,
+          version,
+          ...(projectRejected ? { fallbackReason: projectRejected } : {}),
+        };
+      }
+      if (label === 'project' && mod) {
+        projectRejected = `project typescript is not API-compatible (${typescriptUsabilityHint(mod)}); using ArkGate's JS-API TypeScript fallback (TypeScript 7.0 main export is version-only). See docs/typescript-support.md.`;
+      }
     } catch {
       /* try next loader */
     }
@@ -1202,7 +1244,8 @@ function mcpJson(root) {
     mcpServers: {
       ark: {
         type: 'stdio',
-        ...execCommandParts(root, 'ark-mcp', ['--root', '.', '--config', 'ark.config.json']),
+        // Prefer arkgate-mcp; ark-mcp alias still works for one major.
+        ...execCommandParts(root, PREFERRED_MCP_BIN, ['--root', '.', '--config', 'ark.config.json']),
       },
     },
   }, null, 2)}\n`;
@@ -1213,7 +1256,7 @@ function mcpJson(root) {
 // it flags the two gotchas of hand-editing the global config: absolute paths (config.toml is
 // loaded without the project as cwd) and the required restart.
 function codexTomlSnippet(root) {
-  const { command, args } = execCommandParts(root, 'ark-mcp', [
+  const { command, args } = execCommandParts(root, PREFERRED_MCP_BIN, [
     '--root',
     '/absolute/path/to/project',
     '--config',
@@ -1347,7 +1390,7 @@ function claudeSettings(root) {
           hooks: [
             {
               type: 'command',
-              command: `${runner} ark-mcp --session-context --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
+              command: `${runner} ${PREFERRED_MCP_BIN} --session-context --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
             },
           ],
         },
@@ -1358,7 +1401,7 @@ function claudeSettings(root) {
           hooks: [
             {
               type: 'command',
-              command: `${runner} ark-mcp --hook --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
+              command: `${runner} ${PREFERRED_MCP_BIN} --hook --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
             },
           ],
         },
@@ -1370,7 +1413,7 @@ function claudeSettings(root) {
 // Grok Build project config: MCP registration (commit-friendly relative paths — unlike
 // Codex's global config.toml, Grok loads .grok/config.toml from the project).
 function grokProjectConfig(root) {
-  const { command, args } = execCommandParts(root, 'ark-mcp', [
+  const { command, args } = execCommandParts(root, PREFERRED_MCP_BIN, [
     '--root',
     '.',
     '--config',
@@ -1385,7 +1428,7 @@ args = [${argsToml}]
 `;
 }
 
-// Grok Build hooks: same ark-mcp contracts as Claude. Grok sets CLAUDE_PROJECT_DIR as
+// Grok Build hooks: same arkgate-mcp contracts as Claude. Grok sets CLAUDE_PROJECT_DIR as
 // an alias for GROK_WORKSPACE_ROOT. Matcher keeps Claude names (Write|Edit|MultiEdit)
 // and Grok natives (write|search_replace) — Grok aliases both directions.
 function grokHooks(root) {
@@ -1398,7 +1441,7 @@ function grokHooks(root) {
             {
               type: 'command',
               timeout: 30,
-              command: `${runner} ark-mcp --session-context --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
+              command: `${runner} ${PREFERRED_MCP_BIN} --session-context --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
             },
           ],
         },
@@ -1410,7 +1453,7 @@ function grokHooks(root) {
             {
               type: 'command',
               timeout: 30,
-              command: `${runner} ark-mcp --hook --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
+              command: `${runner} ${PREFERRED_MCP_BIN} --hook --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
             },
           ],
         },
@@ -1622,7 +1665,9 @@ function wireCodexMcp(root, force) {
   const esc = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
   const absRoot = path.resolve(root);
   const absConfig = path.join(absRoot, 'ark.config.json');
-  const { command, args } = execCommandParts(root, 'ark-mcp', [
+  // Preferred product bin; absolute --root so Codex (cwd ≠ project) resolves correctly.
+  const preferredBin = 'arkgate-mcp';
+  const { command, args } = execCommandParts(root, preferredBin, [
     '--root',
     esc(absRoot),
     '--config',
@@ -1640,7 +1685,9 @@ args = [${argsToml}]`;
   }
   const tableRe = /(^|\n)\[mcp_servers\.ark\][^\n]*\n(?:(?!\[)[^\n]*\n?)*/;
   const hasTable = tableRe.test(existing);
-  if (hasTable && !force) {
+  // Fail-closed: rewrite temp/upgrade roots and dual/wrong bins even without --force.
+  const mustRewrite = hasTable && codexArkBlockNeedsRewrite(existing, absRoot);
+  if (hasTable && !force && !mustRewrite) {
     return { status: 'skipped', file };
   }
   let next;
@@ -1656,7 +1703,11 @@ args = [${argsToml}]`;
   } catch (error) {
     return { status: 'failed', file, message: error.message };
   }
-  return { status: hasTable ? 'updated' : 'written', file };
+  return {
+    status: hasTable ? 'updated' : 'written',
+    file,
+    ...(mustRewrite && !force ? { reason: 'temp-or-stale-root' } : {}),
+  };
 }
 
 // Detects stale/missing /ark-* skills in the Codex home prompts dir. Only nags
@@ -1735,10 +1786,385 @@ const COMMAND_GATE_TEXT_FILES = [
   '.grok/hooks/ark-write-gate.json', '.grok/config.toml',
 ];
 const COMMAND_GATE_JSON_FILES = ['.mcp.json', '.cursor/mcp.json'];
+// Primary CLI names (product) + one-major aliases. migrate-commands must strip ALL of these
+// before re-emitting a single preferred bin — otherwise a partial rename leaves
+// args: ["ark-mcp", "arkgate-mcp", ...] which breaks stdio MCP hosts.
+const ARK_MCP_BINS = new Set(['arkgate-mcp', 'ark-mcp']);
+const ARK_CHECK_BINS = new Set(['arkgate-check', 'ark-check']);
+const ARK_CLI_BINS = new Set(['arkgate', 'ark']);
+const PREFERRED_MCP_BIN = 'arkgate-mcp';
+const PREFERRED_CHECK_BIN = 'arkgate-check';
+const PREFERRED_CLI_BIN = 'arkgate';
+// Runner argv noise that is not a bin argument (pnpm exec form).
+const MCP_RUNNER_ARGV = new Set(['exec', '--config.verify-deps-before-run=false']);
 // The runner token immediately before an ark command in a text command string.
 // Matches npm/yarn runners and both pnpm forms (legacy `pnpm exec` + verify-deps-safe form).
+// Longer bin names first so `arkgate-check` is not partially matched as `ark`.
 const RUNNER_BEFORE_ARK =
-  /\b(?:npx|pnpm --config\.verify-deps-before-run=false exec|pnpm exec|yarn)(?= (?:ark-check|ark-mcp|ark)\b)/g;
+  /\b(?:npx|pnpm --config\.verify-deps-before-run=false exec|pnpm exec|yarn)(?= (?:arkgate-check|arkgate-mcp|arkgate|ark-check|ark-mcp|ark)\b)/g;
+
+/** Keep only MCP server flags from existing args (drop runner tokens + any ark* bin names). */
+function stripMcpServerArgs(args) {
+  if (!Array.isArray(args) || args.length === 0) {
+    return ['--root', '.', '--config', 'ark.config.json'];
+  }
+  const kept = args.filter(
+    (entry) =>
+      typeof entry === 'string' &&
+      !MCP_RUNNER_ARGV.has(entry) &&
+      !ARK_MCP_BINS.has(entry) &&
+      !ARK_CHECK_BINS.has(entry) &&
+      !ARK_CLI_BINS.has(entry)
+  );
+  return kept.length > 0 ? kept : ['--root', '.', '--config', 'ark.config.json'];
+}
+
+/** True when mcpServers.ark.args list more than one Ark MCP bin (broken dual rename). */
+function mcpArgsHaveDuplicateBins(args) {
+  if (!Array.isArray(args)) return false;
+  const hits = args.filter((entry) => ARK_MCP_BINS.has(entry));
+  return hits.length > 1 || (hits.length === 1 && args.indexOf(hits[0]) !== args.lastIndexOf(hits[0]));
+}
+
+function brokenMcpGateFiles(root) {
+  const bad = [];
+  for (const rel of COMMAND_GATE_JSON_FILES) {
+    let json;
+    try {
+      json = JSON.parse(fs.readFileSync(path.join(root, rel), 'utf8'));
+    } catch {
+      continue;
+    }
+    const ark = json?.mcpServers?.ark;
+    if (ark && mcpArgsHaveDuplicateBins(ark.args)) bad.push(rel);
+  }
+  return bad;
+}
+
+/** Core layers whose optionality matters once they match files (presets share these names). */
+const CORE_LAYER_NAMES = new Set([
+  'DomainModel',
+  'ApplicationOrchestration',
+  'PresentationAdapters',
+  'PersistenceAdapters',
+]);
+
+/** Temp / upgrade sandbox roots must never remain as Codex MCP --root. */
+function isTempOrUpgradeRoot(p) {
+  if (!p || typeof p !== 'string') return false;
+  const n = p.replace(/\\/g, '/');
+  return (
+    /\/var\/folders\//i.test(n) ||
+    /\/tmp\//i.test(n) ||
+    /\/Temp\//i.test(n) ||
+    /ark-upgrade/i.test(n) ||
+    /\/T\/(?:ark-|grok-)/i.test(n) ||
+    /[\\/]AppData[\\/]Local[\\/]Temp[\\/]/i.test(n)
+  );
+}
+
+/** Extract --root value from Codex [mcp_servers.ark] args array text. */
+function extractCodexArkRootFromToml(tomlText) {
+  if (!tomlText || typeof tomlText !== 'string') return null;
+  const start = tomlText.search(/(^|\n)\[mcp_servers\.ark\]/);
+  if (start < 0) return null;
+  const rest = tomlText.slice(start);
+  const endMatch = rest.slice(1).search(/\n\[/);
+  const block = endMatch >= 0 ? rest.slice(0, endMatch + 1) : rest;
+  // args = ["arkgate-mcp", "--root", "/abs/path", ...]
+  const rootIdx = block.search(/"--root"\s*,\s*"/);
+  if (rootIdx < 0) {
+    // alternate: --root as adjacent string after any bin
+    const m = block.match(/"--root"\s*,\s*"([^"]+)"/);
+    return m ? m[1] : null;
+  }
+  const m = block.slice(rootIdx).match(/"--root"\s*,\s*"([^"]+)"/);
+  return m ? m[1] : null;
+}
+
+function codexArkBlockHasPreferredBin(tomlText) {
+  if (!tomlText) return false;
+  const start = tomlText.search(/(^|\n)\[mcp_servers\.ark\]/);
+  if (start < 0) return false;
+  const rest = tomlText.slice(start);
+  const endMatch = rest.slice(1).search(/\n\[/);
+  const block = endMatch >= 0 ? rest.slice(0, endMatch + 1) : rest;
+  const bins = [...block.matchAll(/"(arkgate-mcp|ark-mcp)"/g)].map((m) => m[1]);
+  if (bins.length > 1) return false;
+  return bins.length === 1 && bins[0] === PREFERRED_MCP_BIN;
+}
+
+function codexArkBlockNeedsRewrite(tomlText, absRoot) {
+  if (!tomlText || !tomlText.includes('[mcp_servers.ark]')) return true;
+  const rootArg = extractCodexArkRootFromToml(tomlText);
+  if (!rootArg || isTempOrUpgradeRoot(rootArg)) return true;
+  try {
+    if (path.resolve(rootArg) !== path.resolve(absRoot)) return true;
+  } catch {
+    return true;
+  }
+  if (!codexArkBlockHasPreferredBin(tomlText)) return true;
+  return false;
+}
+
+/**
+ * Adoption completeness (separate from 0–100 fitness). Pure-ish: filesystem + config.
+ * @returns {{ gaps: object[], hosts: object[], mcp: object, codexHome: object|null, coreOptional: object[], originReport: object, baseline: object, layerBalance: object|null }}
+ */
+function collectAdoptionGaps(root, config, coverage) {
+  const gaps = [];
+  const adopted = fs.existsSync(path.join(root, 'AGENTS.md'));
+  const isProducer = fs.existsSync(path.join(root, 'templates', 'skills'));
+
+  // --- Repo MCP dual-bin ---
+  const dualMcp = brokenMcpGateFiles(root);
+  const mcp = {
+    dualBinFiles: dualMcp,
+    ok: dualMcp.length === 0,
+  };
+  if (dualMcp.length > 0) {
+    gaps.push({
+      id: 'mcp-dual-bin',
+      severity: 'warn',
+      message: `Broken MCP argv in ${dualMcp.join(', ')}: more than one of ark-mcp/arkgate-mcp`,
+      fix: arkCommand(root, 'ark-check', '--install-agent-gates --migrate-commands'),
+    });
+  }
+
+  // --- Host completeness (only when project already adopted gates) ---
+  const hosts = [];
+  if (adopted && !isProducer) {
+    const skillNames = skillTemplateNames();
+    const hostChecks = [
+      {
+        host: 'grok',
+        dir: '.grok',
+        skill: (n) => path.join(root, '.grok', 'skills', n, 'SKILL.md'),
+        extras: [
+          ['.grok/hooks/ark-write-gate.json', 'write-gate hook'],
+          ['.grok/config.toml', 'project MCP config'],
+        ],
+        toolsFlag: 'grok',
+      },
+      {
+        host: 'claude',
+        dir: '.claude',
+        skill: (n) => path.join(root, '.claude', 'skills', n, 'SKILL.md'),
+        extras: [['.claude/settings.json', 'settings/hooks']],
+        toolsFlag: 'claude',
+      },
+      {
+        host: 'cursor',
+        dir: '.cursor',
+        skill: (n) => path.join(root, '.cursor', 'commands', `${n}.md`),
+        extras: [['.cursor/mcp.json', 'MCP config']],
+        toolsFlag: 'cursor',
+      },
+    ];
+    for (const h of hostChecks) {
+      if (!fs.existsSync(path.join(root, h.dir))) continue;
+      const missingSkills = skillNames.filter((n) => !fs.existsSync(h.skill(n)));
+      const missingExtras = h.extras.filter(([rel]) => !fs.existsSync(path.join(root, rel)));
+      const complete = missingSkills.length === 0 && missingExtras.length === 0;
+      hosts.push({
+        host: h.host,
+        present: true,
+        complete,
+        missingSkills: missingSkills.length,
+        missingExtras: missingExtras.map(([, label]) => label),
+      });
+      if (!complete) {
+        gaps.push({
+          id: `host-${h.host}-incomplete`,
+          severity: 'warn',
+          message: `${h.host} dir present but incomplete (${missingSkills.length} skill(s) missing${
+            missingExtras.length ? `; missing ${missingExtras.map(([, l]) => l).join(', ')}` : ''
+          })`,
+          fix: arkCommand(
+            root,
+            'ark-check',
+            `--install-agent-gates --tools ${h.toolsFlag} --force`
+          ),
+        });
+      }
+    }
+  }
+
+  // --- Codex home MCP (temp path / wrong root / dual bin) ---
+  let codexHome = null;
+  if (adopted && !isProducer) {
+    const codexFile = codexConfigPath();
+    let toml = '';
+    try {
+      if (fs.existsSync(codexFile)) toml = fs.readFileSync(codexFile, 'utf8');
+    } catch {
+      toml = '';
+    }
+    if (toml.includes('[mcp_servers.ark]')) {
+      const rootArg = extractCodexArkRootFromToml(toml);
+      const absRoot = path.resolve(root);
+      const temp = isTempOrUpgradeRoot(rootArg);
+      let wrongRoot = false;
+      try {
+        wrongRoot = rootArg ? path.resolve(rootArg) !== absRoot : true;
+      } catch {
+        wrongRoot = true;
+      }
+      const preferredBin = codexArkBlockHasPreferredBin(toml);
+      const needsRewrite = codexArkBlockNeedsRewrite(toml, absRoot);
+      codexHome = {
+        file: codexFile,
+        root: rootArg,
+        tempPath: temp,
+        wrongRoot,
+        preferredBin,
+        needsRewrite,
+      };
+      if (needsRewrite) {
+        gaps.push({
+          id: 'codex-home-mcp',
+          severity: temp || wrongRoot ? 'warn' : 'info',
+          message: temp
+            ? `Codex home MCP --root points at a temp/upgrade path (${rootArg})`
+            : wrongRoot
+              ? `Codex home MCP --root is not this project (${rootArg || 'missing'} ≠ ${absRoot})`
+              : `Codex home MCP should use a single ${PREFERRED_MCP_BIN} bin with absolute project paths`,
+          fix: arkCommand(
+            root,
+            'ark-check',
+            '--install-agent-gates --codex-home --force'
+          ),
+        });
+      }
+    }
+  }
+
+  // --- Core layers optional but populated ---
+  const coreOptional = [];
+  const layerRows = coverage?.layers ?? [];
+  const countByName = new Map(layerRows.map((r) => [r.name, r.files]));
+  for (const layer of config?.layers ?? []) {
+    if (!CORE_LAYER_NAMES.has(layer.name)) continue;
+    if (layer.optional !== true) continue;
+    const files = countByName.get(layer.name) ?? 0;
+    if (files > 0) {
+      coreOptional.push({ layer: layer.name, files });
+      gaps.push({
+        id: `core-optional-${layer.name}`,
+        severity: 'info',
+        message: `Core layer ${layer.name} has ${files} file(s) but is still optional: true — contract is weaker than the tree`,
+        fix: `Edit ark.config.json: remove optional on ${layer.name} (or set false), then ${arkCommand(root, 'ark-check', '--strict-config')}`,
+      });
+    }
+  }
+
+  // --- Origin report ---
+  const originJson = path.join(root, '.ark', 'reports', 'origin.json');
+  const originReport = {
+    present: fs.existsSync(originJson),
+    path: '.ark/reports/origin.json',
+  };
+  if (adopted && !originReport.present && (coverage?.governed?.percent ?? 0) >= 50) {
+    gaps.push({
+      id: 'origin-report-missing',
+      severity: 'info',
+      message: 'No origin architecture snapshot under .ark/reports/ yet',
+      fix: arkCommand(root, 'ark-check', '--report ark-report.html'),
+    });
+  }
+
+  // --- Baseline policy ---
+  const baselinePath = path.join(root, '.ark-baseline.json');
+  const baselineExists = fs.existsSync(baselinePath);
+  let frozenKeys = 0;
+  if (baselineExists) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+      frozenKeys = Array.isArray(raw.violations) ? raw.violations.length : 0;
+    } catch {
+      frozenKeys = 0;
+    }
+  }
+  let primaryPathUsesBaseline = false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    const scripts = pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+    primaryPathUsesBaseline = Object.values(scripts).some(
+      (s) => typeof s === 'string' && s.includes('--baseline')
+    );
+  } catch {
+    /* no package.json */
+  }
+  if (!primaryPathUsesBaseline) {
+    try {
+      const wfDir = path.join(root, '.github', 'workflows');
+      if (fs.existsSync(wfDir)) {
+        for (const f of fs.readdirSync(wfDir)) {
+          if (!/\.ya?ml$/i.test(f)) continue;
+          const text = fs.readFileSync(path.join(wfDir, f), 'utf8');
+          if (text.includes('--baseline') && (text.includes('ark-check') || text.includes('arkgate-check'))) {
+            primaryPathUsesBaseline = true;
+            break;
+          }
+        }
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  const baseline = {
+    exists: baselineExists,
+    frozenKeys,
+    primaryPathUsesBaseline,
+    signal: baselineExists
+      ? frozenKeys === 0
+        ? 'keep-empty'
+        : 'active-ratchet'
+      : 'absent',
+  };
+  if (adopted && baselineExists && frozenKeys === 0 && !primaryPathUsesBaseline) {
+    gaps.push({
+      id: 'baseline-unused',
+      severity: 'info',
+      message:
+        'Empty .ark-baseline.json exists but primary scripts/CI do not pass --baseline (policy unclear)',
+      fix: 'Either add --baseline .ark-baseline.json to check:architecture / CI, or remove the unused baseline file',
+    });
+  }
+
+  // --- Educational layer balance (not a violation) ---
+  let layerBalance = null;
+  const total = layerRows.reduce((s, r) => s + (r.files || 0), 0);
+  if (total >= 20) {
+    const presentation = layerRows.find((r) => r.name === 'PresentationAdapters');
+    const domain = layerRows.find((r) => r.name === 'DomainModel');
+    if (presentation && domain) {
+      const pShare = presentation.files / total;
+      const dShare = domain.files / total;
+      if (pShare >= 0.5 && dShare < 0.1) {
+        layerBalance = {
+          kind: 'presentation-heavy-thin-domain',
+          presentationFiles: presentation.files,
+          domainFiles: domain.files,
+          totalFiles: total,
+          educational:
+            'Presentation holds most of the tree while DomainModel is thin — common for UI apps; consider extracting domain types/use-cases as the product grows. Educational only (not a gate failure).',
+        };
+      }
+    }
+  }
+
+  return {
+    gaps,
+    hosts,
+    mcp,
+    codexHome,
+    coreOptional,
+    originReport,
+    baseline,
+    layerBalance,
+  };
+}
 
 // Gate files whose Ark command runner doesn't match this project's package manager — the
 // advisory (and --migrate-commands) target. Returns [] for npm/unknown projects (npx is right)
@@ -1800,6 +2226,8 @@ function warnLockfileConflict(root) {
 // --migrate-commands: rewrite ONLY the Ark command runner in existing gate files to the
 // project's package manager (no --force clobber). Closes the upgrade gap where a repo that
 // adopted before the package-manager-aware templates keeps a stale `npx`.
+// Also normalizes MCP JSON to a single preferred bin (arkgate-mcp), stripping any dual
+// ark-mcp + arkgate-mcp residue left by partial renames during package identity cutover.
 function runMigrateCommands(root) {
   const runner = execRunner(root);
   const changed = [];
@@ -1811,7 +2239,12 @@ function runMigrateCommands(root) {
     } catch {
       continue;
     }
-    const next = text.replace(RUNNER_BEFORE_ARK, runner);
+    let next = text.replace(RUNNER_BEFORE_ARK, runner);
+    // Prefer primary product bins in command strings (aliases still work if left alone).
+    next = next
+      .replace(/\bark-mcp\b/g, PREFERRED_MCP_BIN)
+      .replace(/\bark-check\b/g, PREFERRED_CHECK_BIN);
+    // Do not blanket-replace bare `ark` — it appears in prose ("Ark check", product name).
     if (next !== text) {
       fs.writeFileSync(full, next);
       changed.push(rel);
@@ -1827,23 +2260,23 @@ function runMigrateCommands(root) {
     }
     const ark = json?.mcpServers?.ark;
     if (!ark) continue;
-    const binArgs = Array.isArray(ark.args)
-      ? ark.args.filter((entry) => entry !== 'exec' && entry !== 'ark-mcp')
-      : ['--root', '.', '--config', 'ark.config.json'];
-    const parts = execCommandParts(root, 'ark-mcp', binArgs);
+    const binArgs = stripMcpServerArgs(ark.args);
+    const parts = execCommandParts(root, PREFERRED_MCP_BIN, binArgs);
     if (ark.command !== parts.command || JSON.stringify(ark.args) !== JSON.stringify(parts.args)) {
       json.mcpServers.ark = { ...ark, ...parts };
       fs.writeFileSync(full, `${JSON.stringify(json, null, 2)}\n`);
       changed.push(rel);
     }
   }
-  const pm = runner === 'pnpm exec' ? 'pnpm' : runner;
-  console.log(`Migrated the Ark command runner to "${pm}" in existing gate files.`);
+  const pm = runner === 'pnpm exec' || runner.startsWith('pnpm ') ? 'pnpm' : runner;
+  console.log(`Migrated ArkGate command runners to "${pm}" and normalized MCP bins in gate files.`);
   if (changed.length === 0) {
-    console.log('  Nothing to change — all Ark commands already use the right runner.');
+    console.log('  Nothing to change — runners and MCP bins already look correct.');
   } else {
     for (const rel of changed) console.log(`  updated ${rel}`);
-    console.log('  (only the command runner changed; customized content is untouched.)');
+    console.log(
+      `  (runner + single MCP bin \`${PREFERRED_MCP_BIN}\`; customized non-command content is untouched.)`
+    );
   }
   warnLockfileConflict(root);
 }
@@ -2970,8 +3403,12 @@ function detectEnforcement(root) {
     (f) => has(f) && (fileIncludes(f, 'arkgate') || fileIncludes(f, 'ark-runtime-kernel'))
   );
   const writeGateFile =
-    (fileIncludes('.claude/settings.json', 'ark-mcp') && '.claude/settings.json') ||
+    ((fileIncludes('.claude/settings.json', 'arkgate-mcp') ||
+      fileIncludes('.claude/settings.json', 'ark-mcp')) &&
+      '.claude/settings.json') ||
     (has('.cursor/mcp.json') && '.cursor/mcp.json') ||
+    (fileIncludes('.grok/hooks/ark-write-gate.json', 'arkgate-mcp') &&
+      '.grok/hooks/ark-write-gate.json') ||
     null;
   return [
     { name: 'Write gate', where: writeGateFile, what: 'blocks a bad edit as you type (PreToolUse hook / MCP)' },
@@ -3311,6 +3748,7 @@ function renderHtmlReport({
   originSnapshot = null,
   currentSnapshot = null,
   originJustCreated = false,
+  adoption = null,
 }) {
   const layers = Array.isArray(config.layers) ? config.layers : [];
   const rules = Array.isArray(config.rules) ? config.rules : [];
@@ -3362,6 +3800,8 @@ function renderHtmlReport({
     scoreCaption,
   } = fitness;
 
+  const adoptionView = adoption || collectAdoptionGaps(root, config, coverage);
+
   // ── Senior diagnostics (coupling, purity, contract density) ──────────────
   const layerNames = ordered.map((l) => l.name);
   const pairCount = Math.max(1, layers.length * Math.max(0, layers.length - 1));
@@ -3867,6 +4307,45 @@ function renderHtmlReport({
     </div>
   </div>
 
+  <div class="section card" id="adoption">
+    <h2>Adoption</h2>
+    <p class="dim" style="margin:.15rem 0 .75rem;font-size:.88rem">
+      Co-pilot completeness — separate from the 0–100 fitness score above. Hosts, MCP health, origin snapshot, core optionality, baseline policy.
+    </p>
+    <div class="kpis" style="margin-bottom:.75rem">
+      <div class="kpi"><b>${adoptionView.gaps.length === 0 ? 'OK' : adoptionView.gaps.length}</b><span>${adoptionView.gaps.length === 0 ? 'No adoption gaps' : 'Adoption gap(s)'}</span></div>
+      <div class="kpi"><b>${adoptionView.originReport.present ? 'yes' : 'no'}</b><span>Origin report</span></div>
+      <div class="kpi"><b>${esc(adoptionView.baseline.signal)}</b><span>Baseline policy</span></div>
+      <div class="kpi"><b>${adoptionView.mcp.ok ? 'ok' : 'fix'}</b><span>Repo MCP argv</span></div>
+    </div>
+    ${
+      adoptionView.gaps.length
+        ? `<ul class="senior-list">${adoptionView.gaps
+            .map(
+              (g) =>
+                `<li><b>${esc(g.id)}</b> — ${esc(g.message)}${
+                  g.fix ? `<br/><code>${esc(g.fix)}</code>` : ''
+                }</li>`
+            )
+            .join('')}</ul>`
+        : '<p class="clean-body">No adoption gaps detected for hosts, MCP, core optionality, or origin.</p>'
+    }
+    ${
+      adoptionView.coreOptional.length
+        ? `<p class="dim" style="margin-top:.65rem">Optional-but-populated cores: <code>${adoptionView.coreOptional
+            .map((c) => `${esc(c.layer)} (${c.files})`)
+            .join('</code>, <code>')}</code></p>`
+        : ''
+    }
+    ${
+      adoptionView.hosts.length
+        ? `<p class="dim" style="margin-top:.4rem">Hosts: ${adoptionView.hosts
+            .map((h) => `${esc(h.host)}${h.complete ? ' ✓' : ' incomplete'}`)
+            .join(' · ')}</p>`
+        : ''
+    }
+  </div>
+
   <div class="section grid-2">
     <div class="card">
       <h2>Architecture map</h2>
@@ -4102,6 +4581,14 @@ function renderHtmlReport({
         : '<p class="dim">No <code>intentPrefixes</code> on layers — runtime intent governance and string-intent checks have less to bind to.</p>'
     }
 
+    <h3>Layer balance (educational)</h3>
+    ${
+      adoptionView.layerBalance
+        ? `<p class="dim" style="margin:.1rem 0 .55rem;font-size:.88rem">${esc(adoptionView.layerBalance.educational)}</p>
+           <p class="meta">PresentationAdapters ${adoptionView.layerBalance.presentationFiles} · DomainModel ${adoptionView.layerBalance.domainFiles} · total ${adoptionView.layerBalance.totalFiles}</p>`
+        : '<p class="dim" style="margin:.1rem 0 .55rem;font-size:.88rem">No presentation-heavy / thin-domain imbalance flagged (educational only when Presentation ≥50% and Domain &lt;10% of files).</p>'
+    }
+
     <h3>Pattern forensics</h3>
     <div class="grid-2" style="margin-top:.45rem">
       <div>
@@ -4431,6 +4918,7 @@ function runDoctor(root, config, files, rules, violations, asJson, options = {})
   const gatesMissing = missingGates(root);
   const skillGaps = detectSkillGaps(root);
   const staleRunners = staleRunnerGateFiles(root);
+  const adoption = collectAdoptionGaps(root, config, cov);
   const baseline = readBaseline(root, '.ark-baseline.json');
   const currentKeys = new Set(violations.map(baselineKey));
   const suppressed = baseline.exists
@@ -4472,10 +4960,12 @@ function runDoctor(root, config, files, rules, violations, asJson, options = {})
               exists: baseline.exists,
               frozen: baseline.exists ? baseline.keys.size : 0,
               stale: staleBaseline,
+              policy: adoption.baseline,
             },
             gatesMissing,
             skillGaps,
             staleRunnerFiles: staleRunners,
+            adoption,
             newHere: showNewHere
               ? {
                   show: true,
@@ -4617,6 +5107,37 @@ function runDoctor(root, config, files, rules, violations, asJson, options = {})
     actions.push(`migrate command runners (${arkCommand(root, 'ark-check', '--install-agent-gates --migrate-commands')})`);
   }
 
+  // Adoption completeness (hosts, MCP health, codex home, core optionality, origin, baseline policy)
+  console.log('');
+  console.log(color.bold('Adoption (separate from fitness score)'));
+  if (adoption.gaps.length === 0 && !adoption.layerBalance) {
+    line(ok, 'Hosts, MCP argv, core optionality, origin report, and baseline policy look complete');
+  } else {
+    for (const gap of adoption.gaps) {
+      const mark = gap.severity === 'warn' ? warn : gap.severity === 'info' ? warn : bad;
+      line(mark, gap.message);
+      if (gap.fix) line(' ', color.dim(`Fix: ${gap.fix}`));
+      actions.push(gap.fix || gap.message);
+    }
+    if (adoption.layerBalance) {
+      line(warn, color.dim(adoption.layerBalance.educational));
+    }
+  }
+  if (adoption.baseline) {
+    line(
+      ' ',
+      color.dim(
+        `Baseline policy: ${adoption.baseline.signal}` +
+          (adoption.baseline.primaryPathUsesBaseline
+            ? ' · primary path uses --baseline'
+            : ' · primary path does not use --baseline')
+      )
+    );
+  }
+  if (adoption.originReport.present) {
+    line(ok, 'Origin architecture snapshot present (.ark/reports/origin.json)');
+  }
+
   console.log('');
   if (actions.length === 0) {
     console.log(color.green('✔ Healthy — nothing to do.'));
@@ -4744,24 +5265,39 @@ async function main() {
 
   // Resolve TypeScript from the project first, then Ark's own install, then bare import.
   // --plan can still run honestly (coverage + empty violations) when TS is missing.
-  const ts = await loadTypeScript(root);
-  if (!ts) {
+  // Early TypeScript 7 native builds may load but lack a JS `sys` host — we fall back.
+  const loaded = await loadTypeScript(root);
+  if (!loaded?.ts) {
     if (args.plan) {
       const cov = computeCoverage(root, config, files, rules);
       if (!args.json) {
         console.log(
           color.yellow(
-            `TypeScript not found — plan shows coverage honesty only (no import graph). Install with: ${installDevHint(root, 'typescript')}`
+            `TypeScript not found — plan shows coverage honesty only (no import graph). Install with: ${installDevHint(root, 'typescript')} (supported: 5.x–7.x; see docs/typescript-support.md)`
           )
         );
       }
       runPlan(root, [], args.json, cov.governed.percent, cov.governed.totalFiles);
       return;
     }
-    console.error(`ark-check requires TypeScript. Install it with: ${installDevHint(root, 'typescript')}`);
+    console.error(
+      `ark-check requires a JS-API TypeScript (5.x–7.x with ts.sys). Install with: ${installDevHint(root, 'typescript')} — see docs/typescript-support.md`
+    );
     process.exitCode = 2;
     return;
   }
+  const { ts } = loaded;
+  if (loaded.fallbackReason && !args.json) {
+    console.log(color.yellow(loaded.fallbackReason));
+  }
+  if (process.env.ARK_DEBUG_TS === '1' && !args.json) {
+    console.log(
+      color.dim(
+        `[ark-check] TypeScript ${loaded.version ?? '?'} via ${loaded.source}` +
+          (loaded.fallbackReason ? ' (fallback)' : '')
+      )
+    );
+  }
 
   const manifestIntentLayers = intentLayersFromManifest(manifest);
   const compilerOptionsFor = createCompilerOptionsLookup(ts, root, args.tsconfig);
@@ -5218,6 +5754,16 @@ async function main() {
       );
     }
 
+    const brokenMcp = brokenMcpGateFiles(root);
+    if (brokenMcp.length > 0) {
+      console.log(
+        color.yellow(
+          `Broken MCP argv in ${brokenMcp.join(', ')}: more than one of ark-mcp/arkgate-mcp in args ` +
+            `(stdio hosts get a double binary name). Fix: ${arkCommand(root, 'ark-check', '--install-agent-gates --migrate-commands')}`
+        )
+      );
+    }
+
     if (codexHomeGap) {
       const parts = [];
       if (codexHomeGap.missing > 0) parts.push(`${codexHomeGap.missing} missing`);